# 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
- WebAuthn spec: https://www.w3.org/TR/webauthn-2/
- go-webauthn library: https://github.com/go-webauthn/webauthn
- Argon2id RFC: https://datatracker.ietf.org/doc/html/rfc9106