Security Guide

Cryptographic Standards

Password Hashing

Passwords are hashed using Argon2id, the winner of the Password Hashing Competition and recommended by OWASP.

const ARGON2_OPTIONS = {
  memoryCost: 65536,    // 64 MB memory
  timeCost: 3,          // 3 iterations
  parallelism: 4,       // 4 parallel threads
  outputLen: 32,        // 256-bit output
};

Token Storage

Tokens are never stored in plaintext. Before storage, all tokens are hashed using SHA-256:

function hashToken(token) {
  return crypto.createHash('sha256').update(token).digest('hex');
}

This means a database breach doesn't expose usable tokens — tokens cannot be reverse-engineered from their hashes.

Token Generation

Token Security

Token Lifetimes

Single-Use Authorization Codes

Authorization codes are marked as used immediately after successful token exchange. This prevents replay attacks where an attacker intercepts the code during redirect.

Refresh Token Rotation

Each time a refresh token is used, a new one is issued and the old one is revoked. This limits exposure if a refresh token is leaked and enables detection of token theft.

Token Family Revocation

When a refresh token is revoked, all associated access tokens are also revoked. This ensures logout is complete and no orphaned access tokens remain.

Attack Prevention

CSRF Protection

The consent form is protected with server-side CSRF tokens stored in encrypted session cookies. Clients should also always use the state parameter.

// Server validates CSRF token on consent submission
if (session.csrfToken !== submittedToken) {
  return error('invalid_request', 'Invalid CSRF token');
}

// Client validates state on callback
if (returnedState !== sessionStorage.getItem('oauth_state')) {
  throw new Error('State mismatch - possible CSRF attack');
}

PKCE (Proof Key for Code Exchange)

PKCE prevents authorization code interception attacks. The client generates a random verifier, creates a SHA-256 challenge, and proves knowledge of the verifier during token exchange.

// Client: generate verifier and challenge
const verifier = crypto.randomBytes(32).toString('base64url');
const challenge = crypto
  .createHash('sha256')
  .update(verifier)
  .digest('base64url');

// Send challenge in authorization request
// Send verifier in token request
// Server validates: SHA256(verifier) === challenge

Redirect URI Validation

Redirect URIs must exactly match a registered URI. No wildcards or partial matching. URIs must use HTTPS (except localhost for development). Maximum 10 URIs per client.

Token Enumeration Prevention

The introspection endpoint returns { "active": false } for all invalid tokens with no distinction between “invalid” and “expired.” The revocation endpoint always returns 200 OK regardless of whether the token existed.

Client Security

Secret Storage Recommendations

• Store secrets in environment variables
• Never commit secrets to version control
• Use a secrets manager in production (AWS Secrets Manager, HashiCorp Vault)
• Rotate secrets periodically

Session Security

Sessions use iron-session with AES-256-GCM encryption and HMAC integrity verification. Cookies are HttpOnly (not accessible to JavaScript), Secure in production, and SameSite=Lax.

On login, a new session is always created (session fixation prevention). On logout, the session is deleted from the database and the cookie is cleared.

Security Checklist for Integrators

Required

• Use HTTPS for all OAuth endpoints
• Store client secrets securely (not in code)
• Validate state parameter on callback
• Use PKCE for public clients
• Validate token responses before use
• Handle token expiration gracefully

Recommended

• Use PKCE for all clients (even confidential)
• Implement token refresh before expiration
• Log security-relevant events
• Monitor for unusual activity
• Use secure cookie settings for tokens

Avoid

• Storing tokens in localStorage (XSS vulnerable)
• Including tokens in URLs
• Logging tokens or secrets
• Disabling TLS certificate verification
• Using "plain" PKCE method (prefer S256)

Incident Response

Suspected Token Compromise

1. Revoke immediately via the revocation endpoint
2. Rotate client secret if client credentials may be compromised
3. Review access logs for unauthorized activity
4. Notify affected users if data exposure occurred

Suspected Client Credential Compromise

1. Delete the OAuth client immediately
2. Create new client with new credentials
3. Update application with new credentials
4. Revoke all tokens issued to old client
5. Audit access during compromise window