Auth Architect

--- name: auth-architect description: Implement authentication and authorization with OWASP Top 10 standards, OAuth 2.0 + OIDC, WebAuthn/Passkeys, session management, and RBAC/ABAC. Use when user asks to implement login, signup, authentication, authorization, JWT, OAuth, SSO, passkeys, MFA, or role-based access. Do NOT use for API key management (use api-forge), encryption at rest, or network-level security (firewalls, WAF). triggers: - "authentication" - "authorization" - "login" - "signup" - "OAuth" - "JWT" - "SSO" - "passkeys" - "WebAuthn" - "MFA" - "role-based access" - "RBAC" - "session management" - "passwordless" negatives: - "API key management" - "encryption at rest" - "firewall" - "WAF" - "network security" - "API design" license: MIT compatibility: opencode metadata: workflow: backend audience: developers version: "4.0.0" author: shokunin

Auth Architect

Production authentication following OWASP Top 10, NIST SP 800-63B, and patterns from Auth0, AWS Cognito, and the OWASP Cheat Sheet Series.

Sub-Commands

Workflow

Step 1: Choose auth method

Step 2: Implement authentication

Password-based auth

1. Validate email format + length (< 254 chars)
2. Check against breached passwords (HaveIBeenPwned API k-anonymity)
3. Hash with Argon2id: memory=19456, iterations=2, parallelism=1
   OR BCrypt: cost=12 minimum
4. Generate session UUIDv4 via crypto.randomUUID()
5. Store session server-side (Redis, TTL=24h)
6. Set cookie: httpOnly, Secure, SameSite=Strict
7. Return user object (never return password hash)

Password requirements (NIST SP 800-63B):

• Minimum 12 characters (no max below 64)
• NO composition rules (uppercase, number, symbol required - these weaken security, NIST §5.1.1.2)
• Allow all printable ASCII + Unicode
• Check against HaveIBeenPwned API (k-anonymity, SHA-1 prefix)
• Rate limit: 5 attempts per 15 min per IP + username

JWT implementation

{
  "iss": "https://api.example.com",
  "sub": "user_abc123",
  "aud": ["web", "mobile"],
  "exp": 900,
  "iat": 1700000000,
  "jti": "a1b2c3d4e5f6",
  "sid": "sess_xyz789"
}

Exact values:

• Access token: 15 min expiry. Algorithm: RS256 (asymmetric) or HS256 (symmetric, single service).
• Refresh token: 7 day expiry. Rotation on every use.
• Refresh token reuse detection: revoke ALL tokens if a used refresh token is presented (theft indicator).

// Refresh rotation + reuse detection
async function refreshToken(providedRefreshToken: string) {
  const stored = await db.findRefreshToken(providedRefreshToken)

  if (!stored) {
    // Token not found - possible reuse. Revoke all user tokens.
    await db.revokeAllRefreshTokens(extractUserId(providedRefreshToken))
    throw new AuthError('Token family revoked')
  }

  if (stored.used) {
    // This token was already used - reuse detected. Revoke all.
    await db.revokeAllRefreshTokens(stored.userId)
    throw new AuthError('Token reuse detected')
  }

  // Mark as used, issue new pair
  await db.markRefreshTokenUsed(providedRefreshToken)
  const newToken = await generateRefreshToken(stored.userId)
  const newAccessToken = await generateAccessToken(stored.userId)
  return { accessToken: newAccessToken, refreshToken: newToken }
}

Storage (CRITICAL):

• httpOnly, Secure, SameSite=Strict cookies
• NEVER localStorage (XSS reads it)
• NEVER sessionStorage (XSS reads it)
• NEVER in-memory only (page refresh kills auth)

OAuth 2.0 + OIDC

Authorization Code + PKCE (RFC 7636). Mandatory for public clients (SPA, mobile).

1. Client generates code_verifier: crypto.randomBytes(32).toString('base64url')
2. Client computes code_challenge = SHA256(code_verifier).toString('base64url')
3. Redirect to /authorize?response_type=code&code_challenge=<challenge>&code_challenge_method=S256&scope=openid+profile+email
4. Server issues authorization code (5 min TTL, single use)
5. Client exchanges: POST /token { grant_type: 'authorization_code', code, code_verifier }
6. Server verifies: SHA256(code_verifier) === code_challenge
7. Server returns: { access_token, id_token, refresh_token, expires_in: 900 }

Scopes: Always least privilege. Document each scope's access level.

WebAuthn / Passkeys (FIDO2)

Registration ceremony:

1. Server: challenge = crypto.randomBytes(32)
2. Server sends: { challenge, rp: { name, id }, user: { id, name, displayName }, pubKeyCredParams, timeout: 60000 }
3. Browser: credential = await navigator.credentials.create({ publicKey })
4. Client sends: { id, rawId, type, response: { clientDataJSON, attestationObject } }
5. Server verifies attestation against challenge, stores credential ID + public key

Authentication ceremony:

1. Server: challenge = crypto.randomBytes(32)
2. Server sends: { challenge, rpId, allowCredentials: [{ id, type: 'public-key' }], timeout: 60000 }
3. Browser: assertion = await navigator.credentials.get({ publicKey })
4. Client sends: { id, rawId, type, response: { clientDataJSON, authenticatorData, signature, userHandle } }
5. Server verifies signature against stored public key using crypto.verify()

Step 3: Authorization

RBAC

User ? Role(s) ? Permission(s)

{
  "admin": ["users:*", "orders:*", "settings:*", "billing:*"],
  "manager": ["orders:read", "orders:write", "users:read", "reports:read"],
  "support": ["orders:read", "tickets:*", "users:read"],
  "user": ["orders:read", "orders:write:own", "profile:write:own"]
}

Permission format: resource:action[:scope]

ABAC (when RBAC isn't enough)

Allow if:
  user.department === resource.department
  AND user.clearance >= resource.classification
  AND resource.country IN user.authorizedCountries

Step 4: Session Management (exact specs)

CSRF Protection

Step 5: MFA Implementation

TOTP enrollment:

const secret = authenticator.generateSecret()  // 32 bytes
const otpauth = authenticator.keyuri(user.email, 'MyApp', secret)
// Display QR: otpauth
// Verify: authenticator.verify({ token: userInput, secret })
// Issue: 10 backup codes, BCrypt-hashed, shown once

Step 6: Breach Response

• Log ALL auth events: login, logout, failure, password change, token refresh, MFA enrollment, permission change
• Alert on: multiple geo-locations < 30min apart, rapid failures (credential stuffing), abnormal request patterns
• Notify user on: new device login, password change, email change, MFA change
• Support account recovery: out-of-band verification (email + SMS), time-delayed

Error Handling

Every auth failure must return a generic message. Never reveal which part of auth failed. Log the specific reason internally.

Rules:

• Never distinguish between "email not found" and "wrong password" in responses - identical 401 for both
• Never expose reason or code to the client on auth errors
• Log all auth failures with user identifier, timestamp, IP, and user agent
• Alert on spikes: >20 auth failures per user per minute, >100 per IP per minute
• Return Retry-After header for rate-limited responses

Production Checklist

• Password hashing: Argon2id (memory=19456, iterations=2, parallelism=1) or BCrypt (cost = 12)
• Password breach check (HaveIBeenPwned API, k-anonymity)
• Rate limiting: login (5/15min per IP+username), reset (3/60min), MFA (3/15min)
• Refresh token: rotation on every use. Reuse detection revokes ALL user tokens.
• Token storage: httpOnly + Secure + SameSite=Strict cookies
• No JWT in localStorage, sessionStorage, or URL
• Session: crypto.randomUUID() generation, rotate on login/privilege change
• CSRF: SameSite cookies + token verification for state-changing operations
• CORS: whitelist origins, never * with credentials
• SQL injection: parameterized queries everywhere. Never string interpolation.
• MFA available for all users. Required for admin actions.
• Account lockout: 5 failed attempts ? temporary lockout (30 min) with notification
• Logging: every auth event. Append-only. No PII in logs.
• Passwords: min 12 chars. No composition rules (NIST §5.1.1.2).
• Recovery: time-limited token (15 min), sent to verified email only. Single use.
• OAuth PKCE mandatory for public clients
• WebAuthn: challenge verified server-side. Attestation verified.

Anti-Patterns

Error Handling

Sources

• OWASP Top 10 (2025)
• OWASP Cheat Sheet Series - Authentication, Session Management, CSRF, Forgot Password
• NIST SP 800-63B - Digital Identity Guidelines (§5.1.1.2 password requirements)
• IETF RFC 7519 (JWT), RFC 6749 (OAuth 2.0), RFC 7636 (PKCE)
• WebAuthn Level 2 (W3C Recommendation)
• Auth0 Security Architecture
• FIDO2 Specification
• HaveIBeenPwned API (k-anonymity model)

Checklist

• Skill loads without errors in the AI agent
• YAML frontmatter is valid (description, compatibility, audience)
• Workflow section provides clear step-by-step instructions
• Error handling section covers common failure modes
• All referenced files (references/, scripts/, assets/) exist
• Skill triggers correctly for intended use cases
• No broken links or missing resources