atelier/domains/security/authentication.md

Authentication — Derived Rules

Derives from domains/security/first-principles.md P1 (Zero Trust), P2 (Least Privilege), P6 (Crypto Correctness).

The Default: Authenticated

• Every endpoint is authenticated unless explicitly public.
• "Public" is an explicit declaration, not a default.
• A missing auth check is a bug, not an oversight.

Authentication Methods

Session-based (browser)

• Server-side session, cookie-borne session ID.
• Cookie: HttpOnly, Secure, SameSite=Lax (or Strict).
• Session ID: cryptographically random, ≥ 128 bits.
• Session timeout: bounded. Idle timeout + absolute timeout.

Token-based (API, SPA)

• Bearer token in Authorization: Bearer <token>.
• Token: JWT (signed) or opaque (server-stored).
• JWT: signed (HS256/RS256), never none. Short TTL (≤ 1 hour). Refresh token for long sessions.
• Opaque: server-stored, revocable. Use when revocation matters.

API Keys (service-to-service)

• Long-lived, scoped, rotatable.
• Sent in header (X-API-Key), not query string (logged in URLs).
• Stored in a secrets manager, never in code.

What Never to Do (P6 Crypto Correctness)

• Never roll your own auth. Use a vetted library or framework.
• Never store passwords in plaintext. Use bcrypt/scrypt/argon2 with a work factor.
• Never use MD5 or SHA1 for password hashing.
• Never put a token in a URL. URLs are logged.
• Never accept alg: none in a JWT.
• Never trust a token without verifying its signature.

Password Rules (P4 Input Validation)

• Minimum length: 12 characters (NIST 800-63B). No maximum (don't prevent long passwords).
• No composition rules (no "must contain a symbol"). They don't help and frustrate users.
• Check against a breach corpus (HIBP API or similar).
• Rate limit login attempts. Lockout after N failures (with exponential backoff, not a hard lock).

Multi-Factor (P3 Defense in Depth)

• MFA is the default for privileged accounts.
• TOTP (RFC 6238) or WebAuthn. SMS is deprecated (SIM swapping).
• MFA is a layer, not a replacement for strong primary auth.

Session Lifecycle (P2 Least Privilege, P5 Reversibility)

• Sessions are revocable. A logout invalidates the session server-side, not just client-side.
• Tokens are revocable. A refresh token revocation list is maintained.
• "Remember me" extends the session, it does not make it permanent.

Audit (P7 Auditability)

• Every auth event is logged: login (success/fail), logout, token issuance, token revocation.
• Logs include: user ID, timestamp, IP, user agent, outcome.
• Logs do not include: passwords, tokens, session IDs (use a hash).