Skip to content

Add WebAuthn server endpoints for registration and assertion #66

@helixclaw

Description

@helixclaw

Summary

Add WebAuthn (FIDO2) server-side endpoints for passkey registration (enrollment) and authentication assertion using @simplewebauthn/server.

Context

Phase 3 replaces the server startup password ceremony with WebAuthn-based biometric/passkey verification. This issue adds the core server endpoints that handle the WebAuthn protocol.

Acceptance Criteria

  • Add @simplewebauthn/server as a runtime dependency
  • New file: src/server/webauthn.ts with Fastify route plugin
  • Endpoints:
    • POST /api/webauthn/register/options — generate registration options (challenge, RP info)
    • POST /api/webauthn/register/verify — verify registration response, store credential
    • POST /api/webauthn/authenticate/options — generate authentication options (challenge)
    • POST /api/webauthn/authenticate/verify — verify assertion response
  • Credential storage: ~/.2kc/webauthn-credentials.json
    • Stores: credentialID, publicKey, counter, transports, userHandle
    • File permissions: 0o600
  • Config additions:
    • webauthn.rpName (default: "2keychains")
    • webauthn.rpId (default: derived from server hostname)
    • webauthn.origin (default: derived from server URL)
  • Challenges stored in-memory with short TTL (5 min) to prevent replay
  • Unit tests: registration flow, assertion flow, replay rejection, invalid credential rejection

Dependencies

Scope Boundaries

  • Does NOT include the web UI (separate issue)
  • Does NOT include the approval link flow (separate issue)
  • Pure protocol endpoints only

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions