ClawAuth

Security Model

ClawAuth implements a zero-trust security architecture where cryptographic proof replaces passwords and shared secrets. Even complete database compromise cannot reveal agent identities or enable impersonation.

Core Security Principles

🔒 Zero Trust

No passwords, shared secrets, or trust relationships. Every request requires cryptographic proof of identity.

🔑 Cryptographic Identity

Agent identities are based on ECDSA P-256 public keys, not usernames or passwords.

🛡️ Forward Secrecy

Each authentication uses unique challenges. Past compromises don't affect future security.

🔍 Breach Resilience

Database breaches reveal no secrets that enable impersonation or identity theft.

Cryptographic Foundation

ECDSA P-256 (secp256r1)

ClawAuth uses ECDSA (Elliptic Curve Digital Signature Algorithm) with the P-256 curve for all cryptographic operations:

Why ECDSA P-256?

  • • NSA Suite B approved: Meets US government security standards
  • • Hardware support: Native support in Apple Secure Enclave, TPMs, and HSMs
  • • Performance: Fast signature generation and verification
  • • Security: 128-bit security level, equivalent to 3072-bit RSA
  • • Compact: Small key sizes (64-byte public keys, 64-byte signatures)

Key Generation

Proper key generation is critical for security:

Secure key generation
// Using Node.js crypto (cryptographically secure)
const crypto = require('crypto');

const { publicKey, privateKey } = crypto.generateKeyPairSync('ec', {
  namedCurve: 'prime256v1',  // P-256 curve
  publicKeyEncoding: {
    type: 'spki',
    format: 'pem'
  },
  privateKeyEncoding: {
    type: 'pkcs8',
    format: 'pem'
  }
});

// Private key should be stored securely (chmod 600)
fs.writeFileSync('agent-key.pem', privateKey, { mode: 0o600 });

Authentication Security

Challenge-Response Protocol

ClawAuth's challenge-response protocol prevents replay attacks and ensures freshness:

1

Challenge Request

Agent requests a unique 256-bit random challenge (nonce).

  • • Nonce is cryptographically random (crypto.randomBytes)
  • • Challenge expires in 5 minutes to prevent replay
  • • Each challenge can only be used once
2

Signature Generation

Agent signs the challenge with their private key.

// Agent-side signature (simplified)
const message = challenge.nonce;
const signature = privateKey.sign(message, 'SHA256');
// signature is deterministic but unique per challenge
3

Signature Verification

ClawAuth verifies the signature using the agent's registered public key.

// Server-side verification (simplified)
const publicKey = await getAgentPublicKey(agentId);
const isValid = publicKey.verify(challenge.nonce, signature, 'SHA256');

if (isValid && !challenge.isExpired() && !challenge.isUsed()) {
  return generateJWT(agentId);
} else {
  throw new AuthenticationError('Invalid proof');
}

Security Properties

✅ Guaranteed Protection

  • • No replay attacks (unique challenges)
  • • No offline brute force (no passwords)
  • • Forward secrecy (past compromises irrelevant)
  • • Non-repudiation (cryptographic proof of identity)
  • • Breach resilience (no secrets in database)

⚠️ Attack Vectors

  • • Private key compromise (mitigated by HSMs)
  • • Man-in-the-middle (mitigated by HTTPS)
  • • Timing attacks (mitigated by constant-time ops)
  • • Side-channel attacks (mitigated by secure hardware)

JWT Security

Token Structure

ClawAuth issues JWT tokens signed with ECDSA (ES256 algorithm):

JWT structure
{
  "alg": "ES256",  // ECDSA with P-256 and SHA-256
  "typ": "JWT"
}
{
  "sub": "agent_abc123",           // Subject: Agent ID
  "aud": "service_xyz789",         // Audience: Service ID
  "iss": "https://api.clawauth.com", // Issuer: ClawAuth
  "iat": 1707566400,               // Issued at
  "exp": 1707570000,               // Expires at (1 hour)
  "jti": "jwt_unique_id",          // JWT ID (prevents replay)
  "roles": ["user", "api_access"], // Agent roles
  "permissions": ["read", "write"], // Computed permissions
  "trustScore": 8.7                // Current trust score
}

Token Validation

Services must validate multiple JWT properties:

JWT validation checklist
// Comprehensive JWT validation
const jwt = require('jsonwebtoken');

function validateJWT(token, publicKey) {
  try {
    // 1. Verify signature
    const payload = jwt.verify(token, publicKey, { 
      algorithm: 'ES256' 
    });
    
    // 2. Check expiration (automatic in jwt.verify)
    
    // 3. Validate audience (service ID)
    if (payload.aud !== SERVICE_ID) {
      throw new Error('Invalid audience');
    }
    
    // 4. Check issuer
    if (payload.iss !== 'https://api.clawauth.com') {
      throw new Error('Invalid issuer');
    }
    
    // 5. Ensure not before current time
    const now = Math.floor(Date.now() / 1000);
    if (payload.iat > now + 60) { // 60s clock skew tolerance
      throw new Error('Token issued in future');
    }
    
    // 6. Check against revocation list (if implemented)
    if (await isTokenRevoked(payload.jti)) {
      throw new Error('Token revoked');
    }
    
    return payload;
    
  } catch (error) {
    throw new AuthenticationError(`Invalid token: ${error.message}`);
  }
}

Hardware Security

Secure Enclave Support

For maximum security, ClawAuth supports hardware-backed private keys:

Secure Enclave Benefits

  • • Non-extractable keys: Private keys cannot leave the secure element
  • • Tamper resistance: Physical attacks destroy keys rather than revealing them
  • • Isolation: Keys isolated from operating system and applications
  • • Attestation: Cryptographic proof that operations used secure hardware

HSM Integration

Enterprise deployments can use Hardware Security Modules:

HSM key usage example
// Example with PKCS#11 HSM
const pkcs11 = require('pkcs11js');

class HSMSigner {
  constructor(libraryPath, pin) {
    this.pkcs11 = pkcs11.PKCS11();
    this.pkcs11.load(libraryPath);
    this.session = this.pkcs11.C_OpenSession(0, pkcs11.CKF_RW_SESSION);
    this.pkcs11.C_Login(this.session, pkcs11.CKU_USER, pin);
  }
  
  sign(message) {
    // Find private key in HSM
    const privateKey = this.findPrivateKey();
    
    // Sign using HSM (key never leaves hardware)
    this.pkcs11.C_SignInit(this.session, { mechanism: pkcs11.CKM_ECDSA }, privateKey);
    const signature = this.pkcs11.C_Sign(this.session, message);
    
    return signature;
  }
}

Network Security

Transport Security

  • TLS 1.3: All API communications use TLS 1.3 with perfect forward secrecy
  • HSTS: Strict-Transport-Security headers prevent protocol downgrade
  • Certificate Pinning: SDKs can pin ClawAuth's certificate
  • OCSP Stapling: Real-time certificate revocation checking
Certificate pinning example
// Certificate pinning in Node.js
const https = require('https');
const crypto = require('crypto');

const CLAWAUTH_CERT_FINGERPRINT = 'sha256:ABC123...'; // ClawAuth cert

const agent = new https.Agent({
  checkServerIdentity: (hostname, cert) => {
    const fingerprint = 'sha256:' + crypto
      .createHash('sha256')
      .update(cert.raw)
      .digest('hex');
      
    if (fingerprint !== CLAWAUTH_CERT_FINGERPRINT) {
      throw new Error('Certificate fingerprint mismatch');
    }
  }
});

Operational Security

Key Management

Private Key Storage

  • • Store with restricted file permissions (chmod 600)
  • • Use encrypted filesystems when possible
  • • Consider hardware security modules for production
  • • Implement key rotation policies

Key Rotation

  • • Generate new keypairs periodically
  • • Register new public key with ClawAuth
  • • Update agent configuration to use new key
  • • Revoke old key after transition period

Monitoring & Alerting

ClawAuth provides security monitoring through:

  • Authentication Logs: All authentication attempts are logged
  • Anomaly Detection: Unusual patterns trigger alerts
  • Geographic Analysis: Logins from unexpected locations
  • Rate Limiting: Prevents brute force and DoS attacks
  • Webhooks: Real-time notifications of security events
Security webhook example
{
  "event": "security.suspicious_activity",
  "timestamp": "2026-02-09T13:00:00Z",
  "data": {
    "agentId": "agent_abc123",
    "type": "geographic_anomaly",
    "details": {
      "previousLocation": "US",
      "currentLocation": "CN",
      "timeDelta": 300  // 5 minutes between locations
    },
    "riskScore": 8.5
  }
}

Compliance & Standards

Cryptographic Standards

  • FIPS 140-2: Cryptographic modules meet FIPS standards
  • NIST SP 800-56A: Key establishment recommendations
  • RFC 6090: Fundamental ECC implementation guidance
  • RFC 7515: JSON Web Signature (JWS) specification
  • RFC 7517: JSON Web Key (JWK) specification

Security Certifications

Compliance Framework Support

  • • SOC 2 Type II: Security, availability, and confidentiality
  • • ISO 27001: Information security management systems
  • • FedRAMP: Federal Risk and Authorization Management Program
  • • PCI DSS: Payment card industry security standards
  • • GDPR: General Data Protection Regulation compliance

Security Best Practices

For Developers

✅ Do

  • • Use the official SDKs
  • • Validate all JWT claims
  • • Implement proper error handling
  • • Use hardware security when available
  • • Monitor authentication logs
  • • Implement rate limiting
  • • Use HTTPS everywhere

❌ Don't

  • • Store private keys in plaintext
  • • Skip JWT validation
  • • Ignore certificate errors
  • • Use weak random number generators
  • • Log sensitive cryptographic material
  • • Disable security features for debugging
  • • Trust client-side validation only

Incident Response

In case of suspected security incident:

  1. Immediate: Rotate compromised keys
  2. Assessment: Determine scope of compromise
  3. Containment: Revoke affected tokens and permissions
  4. Recovery: Re-register agents with new keys
  5. Lessons: Update security procedures