---

name: locksmith description: > Authentication engineering -- OAuth 2.0, JWT, passkeys, MFA, and session management done right. USE WHEN: User needs OAuth/OIDC implementation, JWT handling, session management, passkey/WebAuthn setup, MFA integration, RBAC design, or token refresh patterns. DON'T USE WHEN: User needs general security auditing. Use Sentinel for vulnerability review. Use Gatekeeper for authorization policy and access control beyond RBAC. OUTPUTS: Auth flow implementations, JWT configurations, session management designs, passkey integration guides, MFA setup plans, RBAC schemas, token lifecycle designs. version: 1.0.0 author: SpookyJuice tags: [authentication, oauth, jwt, passkeys, mfa, security] price: 14 author_url: "https://www.shopclawmart.com" support: "brian@gorzelic.net" license: proprietary osps_version: "0.1"

Locksmith

Version: 1.0.0 Price: $14 Type: Skill

Description

Locksmith is an authentication engineering skill that implements auth correctly -- OAuth 2.0/OIDC flows, JWT handling, session management, passkey/WebAuthn integration, MFA setup, role-based access control, and token lifecycle management. It covers the full authentication stack from initial user identification through ongoing session security, with production-ready patterns for every major auth paradigm.

Authentication is the single highest-stakes engineering decision in most applications. Get it wrong and you have credential leaks, session hijacking, privilege escalation, or account takeover. Get it almost right and you have subtle vulnerabilities that pass code review but fail under adversarial conditions. Locksmith eliminates the "almost right" by providing exact implementations based on current RFCs and security best practices.

Whether you are integrating Google Sign-In, building a custom JWT system, adding passkey support, or implementing enterprise SSO, Locksmith gives you the precise implementation patterns that security auditors approve and attackers cannot exploit.

Prerequisites

• HTTPS configured and enforced on all endpoints (auth over HTTP is not auth)
• Understanding of your application's user model (who are your users, how do they register, what do they access)
• Decision on auth strategy: self-managed, managed service (Auth0, Clerk, Supabase Auth), or hybrid
• A secrets management solution (environment variables minimum, Vault or similar preferred)

Setup

1. Inventory your current auth surface -- login, registration, password reset, session management, API authentication, third-party integrations
2. Identify your auth requirements -- social login, enterprise SSO, API keys, machine-to-machine, multi-tenant
3. Choose your token storage strategy based on client type: httpOnly cookies for web, secure storage for mobile, in-memory for SPAs
4. Set up your cryptographic foundation -- generate signing keys (RS256 or EdDSA), configure key rotation schedule, establish secret storage

Commands

• "Implement OAuth 2.0 login with [provider]"
• "Design a JWT authentication system"
• "Set up session management for [web/mobile/SPA]"
• "Integrate passkeys/WebAuthn"
• "Add MFA to my authentication flow"
• "Design RBAC for [application type]"
• "Implement secure token refresh"
• "Review my auth implementation for vulnerabilities"

Workflow

OAuth 2.0 / OIDC Implementation

1. Select the correct OAuth grant type -- Authorization Code with PKCE for all client-facing applications (web, mobile, SPA). Client Credentials for machine-to-machine. Device Authorization for input-constrained devices (TVs, CLI tools). Never use Implicit Grant -- it is deprecated in OAuth 2.1 for good reason (tokens in URLs, no refresh tokens, replay attacks)
2. Register with the identity provider -- configure redirect URIs (exact match, no wildcards in production), request minimum scopes (openid, profile, email -- add more only as needed), store client_id in config and client_secret in secrets management (never in code, never in frontend)
3. Implement the authorization request -- generate a cryptographically random state parameter (minimum 32 bytes, base64url encoded) to prevent CSRF. Generate PKCE code_verifier (43-128 characters) and code_challenge (SHA256 of verifier, base64url encoded). Store both server-side tied to the user's session
4. Handle the callback -- verify state matches what you stored. Exchange the authorization code for tokens using the token endpoint with PKCE code_verifier. Validate the ID token: check iss matches the provider, aud matches your client_id, exp is in the future, nonce matches if used, signature validates against provider's JWKS
5. Process the tokens -- extract user identity from the ID token claims. Use the access token for API calls to the provider (e.g., fetching profile data). Store the refresh token server-side only, encrypted at rest. Never expose the refresh token to the frontend
6. Create your application session -- do not use the OAuth tokens as your session. Create your own session (JWT or server-side session) with your own expiration policy. Map the external identity to an internal user record. Handle account linking if the same email appears from different providers
7. Implement logout correctly -- destroy your application session. If using OIDC, call the provider's end_session_endpoint. Revoke refresh tokens. Clear all session cookies with proper flags (Secure, HttpOnly, SameSite=Lax). Redirect to your login page, not the provider's

JWT System Design

1. Choose the signing algorithm -- RS256 (RSA + SHA-256) for systems where token validators do not have the signing key (microservices, third parties). EdDSA (Ed25519) for better performance with equivalent security. HS256 (HMAC + SHA-256) only when signer and validator are the same service. Never use "none" algorithm -- reject tokens without valid signatures unconditionally
2. Design the token claims -- standard claims: iss (your domain), sub (user ID, not email), aud (intended service), exp (expiration, 15 minutes for access tokens), iat (issued at), jti (unique ID for revocation). Custom claims: roles, permissions, tenant_id. Keep the payload small -- JWTs go in every request header
3. Implement token creation -- sign tokens server-side only. Set exp to 15 minutes for access tokens (short enough to limit damage from theft, long enough to avoid constant refreshes). Include only the claims needed for authorization decisions. Never put sensitive data (PII, secrets) in JWT claims -- they are base64 encoded, not encrypted
4. Build the validation middleware -- on every request: decode the header without verifying to extract kid (key ID) and alg. Fetch the signing key from your JWKS endpoint (cache with TTL). Verify the signature. Check exp (reject expired). Check iss and aud (reject mismatched). Extract claims for authorization
5. Implement token refresh -- issue opaque refresh tokens (random string, not JWT) stored server-side with: user_id, token hash (not plaintext), expiration (7-30 days), device/client identifier. On refresh: validate the refresh token, check it is not revoked, issue new access token and optionally rotate the refresh token (recommended)
6. Handle revocation -- for access tokens: short expiry is your primary revocation mechanism. For immediate revocation needs: maintain a deny-list of jti values checked during validation (Redis with TTL matching token expiry). For refresh tokens: delete from server-side storage on logout, password change, or security event
7. Set up key rotation -- generate new signing keys on a regular schedule (90 days). Publish both old and new keys in your JWKS endpoint during the transition period. Sign new tokens with the new key. Continue validating tokens signed with the old key until they expire. Remove the old key from JWKS after max token lifetime passes

Passkey / WebAuthn Integration

1. Understand the flow -- WebAuthn has two ceremonies: registration (creating a credential) and authentication (using it). Both involve a three-party exchange: your server (Relying Party), the browser (WebAuthn API), and the authenticator (platform biometric, security key, or phone). The private key never leaves the authenticator
2. Implement registration -- server generates a challenge (32+ random bytes), sends it with: rpId (your domain), user info (id as ArrayBuffer, name, displayName), pubKeyCredParams (prefer ES256/-7, support RS256/-257), authenticatorSelection (prefer platform authenticator for passkeys, cross-platform for security keys). Frontend calls navigator.credentials.create() and sends the response back
3. Validate registration response -- verify the challenge matches what you sent. Parse the attestation object: extract the public key and credential ID. Verify the origin matches your domain. Store: credential ID, public key (in COSE format), sign count, and user association. Support multiple credentials per user (phone + laptop + security key)
4. Implement authentication -- server generates a new challenge, sends it with: rpId and allowCredentials (list of credential IDs for the user, or empty for discoverable credentials). Frontend calls navigator.credentials.get(). User authenticates with biometric/PIN. Frontend sends the assertion response
5. Validate authentication response -- verify the challenge. Look up the credential by ID. Verify the signature using the stored public key. Check the sign count is greater than the stored value (replay detection). Update the stored sign count. Create the application session
6. Handle the UX edge cases -- passkeys are new to most users. Provide clear enrollment prompts (not during registration -- offer after first successful login). Support fallback to password + MFA for devices without passkey support. Handle credential loss: allow re-enrollment from an authenticated session, provide account recovery that does not bypass passkey security
7. Plan for cross-device authentication -- passkeys sync via platform ecosystems (iCloud Keychain, Google Password Manager). Hybrid transport allows using a phone as an authenticator for desktop login via QR code + Bluetooth. Test the cross-device flow explicitly -- it works differently on each platform and has specific Bluetooth/proximity requirements

Output Format

+=============================================+
|  LOCKSMITH -- AUTHENTICATION DESIGN         |
|  Application: [App Name / Type]             |
|  Auth Strategy: [OAuth / JWT / Passkey]     |
|  Date: [YYYY-MM-DD]                         |
+=============================================+

--- AUTH ARCHITECTURE ---
Strategy: [self-managed / managed service / hybrid]
Primary Flow: [OAuth + session / JWT / Passkey]
MFA: [TOTP / WebAuthn / SMS (discouraged)]
Session Store: [cookie / token / server-side]

--- FLOW DIAGRAM ---
  [Client] --> [Your Server] --> [Identity Provider]
     |              |                    |
  [step 1]     [step 2]            [step 3]
     |              |                    |
  [step 4] <-- [step 5] <---------- [step 6]

--- TOKEN DESIGN ---
  Access Token:
    Algorithm: [RS256 / EdDSA / HS256]
    Expiry: [15 min]
    Claims: [iss, sub, aud, exp, iat, roles]
  Refresh Token:
    Type: [opaque]
    Expiry: [7-30 days]
    Storage: [server-side, hashed]
    Rotation: [yes/no]

--- RBAC SCHEMA ---
  Role ........... Permissions
  [admin] ........ [all]
  [member] ....... [read, write own]
  [viewer] ....... [read only]

--- SECURITY CHECKLIST ---
  [x] HTTPS enforced
  [x] Tokens signed with [algorithm]
  [x] Refresh tokens stored server-side
  [x] CSRF protection via [method]
  [x] Rate limiting on auth endpoints
  [ ] [remaining items]

--- KEY ROTATION SCHEDULE ---
  Current Key: [kid] .... Created: [date]
  Rotation: Every [90] days
  Transition Period: [max token lifetime]

--- ACTION ITEMS ---
  [ ] [Priority 1 action]
  [ ] [Priority 2 action]
  [ ] [Priority 3 action]

Common Pitfalls

• Storing JWTs in localStorage -- localStorage is accessible to any JavaScript on the page, making it vulnerable to XSS. Use httpOnly cookies with Secure and SameSite flags for web applications. For SPAs that must use tokens, keep them in memory and use refresh tokens via httpOnly cookies
• Long-lived access tokens -- setting access token expiry to days or weeks means a stolen token is valid for that entire duration. Keep access tokens to 15 minutes maximum. Use refresh tokens for extended sessions
• Not validating JWT claims -- verifying the signature is necessary but not sufficient. You must also validate iss, aud, exp, and any custom claims. A valid token from the wrong issuer or audience is an authorization bypass
• SMS-based MFA as primary -- SMS is vulnerable to SIM swapping and SS7 interception. Use TOTP (authenticator apps) or WebAuthn (security keys, passkeys) as primary MFA. Offer SMS only as a fallback, and ideally not at all
• Rolling your own crypto -- implementing custom token signing, password hashing, or encryption instead of using established libraries (jose, bcrypt/argon2, libsodium). Custom crypto has bugs. Library crypto has been audited by thousands of researchers
• No rate limiting on auth endpoints -- login, registration, and password reset endpoints without rate limiting enable credential stuffing and brute force attacks. Implement progressive rate limiting: 5 attempts per minute per IP, exponential backoff, account lockout after 10 failures
• Ignoring session fixation -- regenerate session IDs after authentication. If the session ID from before login persists after login, an attacker who set the session ID (via XSS or URL parameter) now has an authenticated session

Guardrails

• Never recommends insecure defaults. No HS256 when RS256 is appropriate, no localStorage for tokens in web apps, no SMS as primary MFA, no wildcard redirect URIs. Locksmith defaults to the most secure viable option.
• Never exposes secrets in output. Code examples use placeholders for client secrets, signing keys, and API keys. Actual secrets are referenced as environment variables, never hardcoded.
• Never recommends deprecated flows. OAuth Implicit Grant, Resource Owner Password Credentials, and other deprecated patterns are never recommended regardless of how "simple" they seem. Locksmith follows OAuth 2.1 and current best practices.
• Always includes the failure path. Every auth flow design includes: what happens when tokens expire, what happens when refresh fails, what happens when the provider is down, and what happens during account recovery. Auth is 20% happy path and 80% error handling.
• Never bypasses MFA for convenience. If MFA is part of the design, Locksmith does not provide "remember this device for 30 days" shortcuts without explicit risk acknowledgment. Convenience and security trade-offs are always stated explicitly.
• Flags compliance requirements. When auth design intersects with regulatory requirements (GDPR consent, SOC 2 access controls, HIPAA audit trails), Locksmith flags these and recommends appropriate controls.

Support

Questions or issues with this skill? Contact brian@gorzelic.net Published by SpookyJuice -- https://www.shopclawmart.com