sirtimbly/cairnquire
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e45eeeb6006ecc7273a3b4663dd5d40f532d5495
cairnquire/docs/adrs/adr-004-auth-strategy.md

2.6 KiB
Raw Blame History

ADR-004: Authentication Strategy

Status

Accepted

Context

The platform needs secure authentication for both technical and non-technical users. Requirements include: primary passkey support, password fallback, session management, and resistance to common attacks (phishing, credential stuffing, session hijacking).

Decision

Passkeys as primary authentication method, Argon2id-hashed passwords as fallback.

Implementation

  1. Registration Flow:

    • User provides email
    • System generates WebAuthn registration challenge
    • Browser creates passkey ( Touch ID, Windows Hello, YubiKey)
    • Server stores credential ID and public key
    • Optional: user sets password fallback

  2. Login Flow (Passkey):

    • User enters email
    • Server returns WebAuthn assertion challenge
    • Browser signs challenge with passkey
    • Server verifies signature, creates session

  3. Login Flow (Password):

    • User enters email + password
    • Server verifies Argon2id hash (constant-time comparison)
    • If valid, creates session
    • Prompts to set up passkey (progressive enhancement)

  4. Session Management:

    • Signed cookies with 24-hour expiry
    • Refresh tokens rotate on each use
    • Sessions stored in database (revocable)
    • HttpOnly, Secure, SameSite=Strict flags

Consequences

Positive

  • Passkeys are phishing-resistant by design
  • No password database to breach (if passkey-only)
  • Argon2id is winner of Password Hashing Competition
  • Session tokens are revocable server-side
  • Progressive enhancement: passkey users never type passwords

Negative

  • Passkey support varies by browser/OS
  • Users may lose access if they lose all devices (recovery flow needed)
  • WebAuthn implementation complexity (mitigated by go-webauthn library)
  • Backup codes or recovery email needed for account recovery

Alternatives Considered

OAuth 2.0 / SSO Only

  • Pros: No password management, familiar UX
  • Cons: Vendor lock-in to identity providers, privacy concerns, not self-hosted
  • Rejected: Violates "no vendor lock-in" principle

Passwords Only (with 2FA)

  • Pros: Simple, universally supported
  • Cons: Vulnerable to phishing, credential stuffing, SIM swapping
  • Rejected: Passkeys are strictly superior

Magic Links

  • Pros: No passwords, simple UX
  • Cons: Email dependency, slower, inbox security issues
  • Rejected: Less secure than passkeys, poor for frequent login

References