Skip to content

EliasOulkadi/shokunin / .pack/skills/auth-architect

auth-architect

Verified

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).

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

CommandDescription
implementImplement full authentication system (login, signup, sessions, MFA, password reset)
auditAudit existing auth against OWASP Top 10 checklist
enforceAdd missing security measures (rate limiting, CSRF, session rotation)
teachSet up auth context file (AUTH.md) with project-specific configuration

Workflow

Step 1: Choose auth method

MethodUse CaseSecurityComplexity
Session-based (httpOnly cookies)Server-rendered web appsHighLow
JWT access + refresh tokensSPAs, mobile, APIsHigh (with proper storage)Medium
OAuth 2.0 + OIDCThird-party login, SSOHighHigh
API keys with HMACM2M, CLIs, integrationsMediumLow
WebAuthn / PasskeysPasswordless, high-securityVery HighMedium
Magic links / OTPLow-friction, email-basedMediumLow

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)

ParameterValue
Session ID generationcrypto.randomUUID() - never sequential
Session storageRedis, TTL = 24h (absolute). DB for analytics.
Idle timeout30 min (sensitive), 2h (standard)
Absolute timeout24h
Session rotationOn login, privilege change, password change
Remember meSeparate token, 30 day TTL, rotated on use

CSRF Protection

LayerImplementation
CookieSameSite=Strict on session cookie
TokenCSRF token in state-changing forms (hidden input + cookie, compare server-side)
HeaderCustom header (X-Requested-By: XMLHttpRequest) for API calls

Step 5: MFA Implementation

FactorSecuritySetup complexity
TOTP (Authenticator app)HighLow (QR code)
Hardware key (FIDO2/WebAuthn)Very HighMedium
Passkeys (platform)Very HighLow (biometric)
SMS OTPMedium (SIM swap risk)Low
Backup codes (10 single-use)High (as backup)Low

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.

ScenarioHTTPResponse MessageLog Action
Invalid email/password401"Invalid credentials"Log: auth_failure + username + reason (breach check, hash mismatch, unknown user)
Account locked423"Account temporarily locked. Try again in 30 minutes."Log: account_locked + user_id + failed_attempts
Token expired401"Session expired. Please log in again."Log: token_expired + user_id + token_jti
Token reuse detected401"Session expired. Please log in again."Log: token_reuse_detected ? revoke all user tokens
CSRF token mismatch403"Invalid request"Log: csrf_mismatch + user_id + origin
Rate limit exceeded429"Too many attempts. Try again in 15 minutes."Log: rate_limited + identifier + endpoint
Permission denied403"Access denied"Log: permission_denied + user_id + resource + required_permission
MFA challenge failed401"Verification failed"Log: mfa_failure + user_id + factor_type
OAuth state mismatch400"Invalid request"Log: oauth_state_mismatch + redirect_uri
WebAuthn challenge failed401"Verification failed"Log: webauthn_failure + credential_id + reason

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

Anti-patternFix
JWT in localStoragehttpOnly cookies with CSRF protection
Refresh token static (no rotation)Rotate on every use. Reuse detection.
Password composition rules (uppercase+number+symbol required)Long passwords (>12 chars) + breach check. No complexity rules.
No rate limiting on login5 attempts per 15 min per username + IP
MFA optional, unpromptedPrompt MFA enrollment. Require for sensitive actions.
Session never expiresIdle (2h max) + absolute (24h max) timeout.
No audit loggingLog all auth events. Append-only. Indexed by user_id.
Hardcoded JWT secretEnvironment variable. Rotated. RS256 preferred over HS256.
Password reset without token expiry15 min expiry, single use, sent to verified email.
Sequential or predictable user IDsUUIDv4 for all resource IDs. Never auto-increment.
Session fixationRotate session ID on login, logout, privilege change.

Error Handling

CauseFix
JWT expired but refresh token still validImplement silent refresh with retry. Rotate tokens on 401.
OAuth state parameter mismatchReject. Log possible CSRF attack. Redirect to login flow.
Rate limit exceeded on auth endpointReturn 429 with Retry-After header. Exponential backoff on client.
Password reset token reusedInvalidate all existing tokens for user. Force re-login.
WebAuthn registration timeoutAllow retry. Set 60s timeout. Warn user of inactivity.
Session fixation after loginRegenerate session ID. Invalidate old session.
Refresh token reuse detectedInvalidate entire token family. Force full re-authentication. Notify user.
MFA code brute forceRate limit to 5 attempts per 5 minutes. Account lockout after 10 failures.
OAuth provider returns malformed tokenValidate JWT signature and claims before use. Fallback to error state.
Argon2id verification slow under loadUse worker threads. Cache verified sessions. Check memory=19456 config.

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
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall