cairnquire/docs/milestones/milestone-03-authentication.md

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

-- 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