# Milestone 3: Authentication & Authorization

**Duration:** 2 weeks  
**Goal:** Secure access control with passkeys and granular permissions

## Tasks

### Week 5: Passkey Authentication

- [ ] WebAuthn server implementation
  - Relying party configuration
  - Challenge generation and storage
  - Attestation verification
  - Credential storage (credential ID, public key, sign count)
  
- [ ] Passkey registration flow
  - Initiate registration endpoint
  - Verify registration response
  - Store credential with user association
  - Support multiple passkeys per user
  
- [ ] Passkey authentication flow
  - Initiate login endpoint
  - Verify assertion response
  - Create session on success
  
- [ ] Session management
  - Signed cookie generation
  - Session storage in database
  - Session validation middleware
  - Session revocation endpoint
  - Automatic session refresh

### Week 6: Password Fallback & Authorization

- [ ] Password authentication
  - Argon2id password hashing
  - Password validation endpoint
  - Password change endpoint
  - Password strength requirements
  
- [ ] Role-based access control
  - Permission model: read, write, admin
  - Scope: global, collection, document
  - Middleware for permission checking
  - Admin UI for managing permissions
  
- [ ] User management
  - User registration (email + passkey/password)
  - User profile management
  - Account deletion (GDPR compliance)
  - User listing (admin only)
  
- [ ] Content signing (optional)
  - Ed25519 key pair generation
  - Document signing on publish
  - Signature verification display

## Acceptance Criteria

### Functional
- [ ] Users can register with passkey on supported browsers
- [ ] Passkey login works with Touch ID, Windows Hello, YubiKey
- [ ] Password fallback works when passkey unavailable
- [ ] Sessions expire after configurable timeout (default 24h)
- [ ] Sessions can be revoked (logout all devices)
- [ ] Read/write/admin permissions enforced on all endpoints
- [ ] Users can only access documents they have permission for
- [ ] Admin users can manage other users' permissions

### Non-Functional
- [ ] Argon2id parameters: time=3, memory=64MB, parallelism=4
- [ ] Session cookies: HttpOnly, Secure, SameSite=Strict
- [ ] Rate limiting: 5 auth attempts per minute per IP
- [ ] No timing attacks on password comparison (constant-time)
- [ ] All auth events logged to audit_log table
- [ ] Ed25519 signatures verified on document read (if enabled)

### Security
- [ ] WebAuthn challenges single-use and time-limited (5 minutes)
- [ ] Credential IDs are unpredictable (128-bit random)
- [ ] Password reset requires email verification
- [ ] No enumeration attacks (same response for exist/non-exist user)

## Database Schema Additions

```sql
-- WebAuthn credentials
CREATE TABLE webauthn_credentials (
    id TEXT PRIMARY KEY,
    user_id TEXT NOT NULL REFERENCES users(id),
    credential_id BLOB NOT NULL UNIQUE,
    public_key BLOB NOT NULL,
    sign_count INTEGER NOT NULL DEFAULT 0,
    created_at DATETIME NOT NULL,
    last_used_at DATETIME
);

-- Permissions
CREATE TABLE permissions (
    id TEXT PRIMARY KEY,
    user_id TEXT NOT NULL REFERENCES users(id),
    resource_type TEXT NOT NULL CHECK(resource_type IN ('global', 'collection', 'document')),
    resource_id TEXT, -- NULL for global
    permission TEXT NOT NULL CHECK(permission IN ('read', 'write', 'admin')),
    granted_by TEXT REFERENCES users(id),
    created_at DATETIME NOT NULL
);
```

## Deliverables

1. Authentication API documentation
2. WebAuthn flow diagrams
3. Permission system documentation
4. Security test results (penetration test guide)

## Risk Mitigation

| Risk | Mitigation |
|------|-----------|
| Passkey not supported on user's device | Password fallback always available |
| User loses all passkeys | Recovery email + backup codes |
| Permission system too complex | Start with simple roles, iterate |
| Session hijacking | Short expiry, rotation, revocation |

## Definition of Done

- [ ] All acceptance criteria pass
- [ ] Security review completed
- [ ] Auth flow tested on Chrome, Firefox, Safari, Edge
- [ ] Mobile passkey tested (iOS, Android)
- [ ] Rate limiting verified
- [ ] Audit logs verified