cairnquire/.project/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

• Passkey registration flow

  • Initiate registration endpoint
  • Verify registration response
  • Store credential with user association
  • Authenticated multiple-passkey management UI (deferred account polish)

• Passkey authentication flow

  • Initiate login endpoint
  • Verify assertion response
  • Create session on success

• Session management

  • Opaque HttpOnly cookie generation
  • Session storage in database
  • Session validation middleware
  • Session revocation endpoint
  • Automatic session refresh (deferred hardening)

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: viewer, editor, admin
  • Token scopes: docs, sync, admin
  • Middleware for permission checking
  • Admin UI for managing user roles

• User management

  • User registration (email + passkey/password)
  • User profile management
  • Account deletion
  • User listing (admin only)

• API token support

  • Bearer token format for developer clients
  • Server stores token hashes only
  • Token scopes and revocation
  • Device-code flow for CLI onboarding

• Content signing (optional)

  • Ed25519 key pair generation
  • Document signing on publish
  • Signature verification display
  • Deferred to production hardening because the current publish path does not yet need signing state.

Acceptance Criteria

Functional

• Users can register with passkey on supported browsers
• Passkey login endpoints verify browser assertions
• Password fallback works when passkey unavailable
• Sessions expire after default 24h timeout
• Sessions can be revoked
• Read/write/admin permissions enforced on protected endpoints
• API clients can use scoped bearer tokens
• CLI clients can use device-code flow
• Per-document and per-collection permission UI (deferred until collaboration resource modeling)

Non-Functional

• Argon2id parameters: time=3, memory=64MB, parallelism=4
• Session cookies: HttpOnly, SameSite=Strict
• Rate limiting: 5 auth attempts per minute per IP/path
• No timing attacks on password comparison (constant-time)
• Password and token comparisons use constant-time comparison
• 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 generated by authenticators
• Password reset requires email verification (out of scope until email/recovery is added)
• Password login uses generic invalid credential responses
• Public registration cannot attach credentials to an existing account
• Device-code polling consumes the code after first token issuance

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

-- Sessions, API tokens, device codes, and audit log are defined in migration 000009_auth.

-- 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 endpoints
3. Role/scope permission documentation
4. API token and device-flow documentation
5. Browser login/account/device verification screens
6. Security implementation checklist
7. Independent penetration test guide (production hardening)

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

• Core implementation acceptance criteria pass
• Implementation security review completed
• Auth flow manually tested on Chrome, Firefox, Safari, Edge (production hardening)
• Mobile passkey tested (iOS, Android) (production hardening)
• Rate limiting verified
• Audit logs verified by service tests