Epic: Phase 3 — WebAuthn Approval/Unlock in Client-Server Mode

[helixclaw]

Overview

Implement WebAuthn-based approval and unlock for client-server mode as specified in docs/encrypted-storage-spec.md (Section 6). This eliminates the server startup password ceremony by using passkeys/biometrics for human approval verification.

Depends on: Phase 2 (Client-Server Mode) — server API + signed grants

Goals

• WebAuthn enrollment: Register passkeys/biometrics for server operators
• WebAuthn assertion for approval: Approve grant requests via biometric verification instead of Discord reactions
• Approval web UI: Minimal web page served by the 2kc server for approve/deny actions
• Notification links: Discord/channel notifications include clickable approval URLs
• Policy enforcement: Server can require WebAuthn-verified approval for grant issuance
• No server startup password: WebAuthn replaces the password-on-startup ceremony for the approval/unlock gate

Key Design Decisions

• Library: @simplewebauthn/server + @simplewebauthn/browser for FIDO2/WebAuthn
• Web origin: Server hosts a minimal web UI at its existing HTTP endpoint (e.g., https://server.example/approve)
• Credential storage: WebAuthn credentials stored in server config or a dedicated credentials file
• Backward compatibility: Hard-coded password auth (Phase 2) remains available as fallback
• Scope: WebAuthn is server-side only — local mode remains password-based (spec constraint)

Out of Scope

• WebAuthn for local-only mode (explicitly excluded by spec)
• Mobile-native biometric SDKs (web-only via browser)
• Multi-tenant / multi-user credential management

Spec Reference

docs/encrypted-storage-spec.md — Section 6 (Variant C: WebAuthn Unlock)

[helixclaw]

Architectural Decision Record (ADR)

Design Rationale

Phase 3 is the final iteration, adding WebAuthn (passkeys/biometrics) as the approval mechanism in client-server mode. This eliminates the need for server operators to type passwords for approval — instead, they tap a biometric prompt on their phone/laptop.

Key Decisions

1. @simplewebauthn/server + @simplewebauthn/browser: Well-maintained, TypeScript-native FIDO2 library. Handles the complex WebAuthn protocol correctly.
2. Single-page approval UI: One self-contained HTML file with inline JS. No build toolchain, no SPA framework. Keeps complexity minimal.
3. Approval links in Discord: Notification includes a clickable URL. This shifts the approval flow from "react on Discord" to "click link → biometric prompt → done."
4. Backward-compatible rollout: approval.requireWebAuthn defaults to false. Teams can adopt WebAuthn gradually — Discord reactions still work when WebAuthn is optional.
5. Enrollment via CLI: 2kc webauthn enroll opens a browser for the registration ceremony. This avoids building a full admin UI.
6. Server-side only: WebAuthn requires a hosted web origin. Local-only mode remains password-based (spec constraint).

Trade-offs

• No mobile SDK: Relies on browser-based WebAuthn only. Works well on iOS Safari / Android Chrome but not in native apps.
• Single-file UI: Limited in sophistication, but sufficient for approve/deny. Can be upgraded to a proper frontend later.
• Challenge TTL in-memory: WebAuthn challenges expire in 5 min and aren't persisted. Server restart during a ceremony requires retry.

Recommended Execution Order

Start with #66 (WebAuthn endpoints), then #67 (approval web UI) and #68 (enrollment CLI) in parallel, then #69 (WebAuthn-gated approval flow), then #70 (notification links), and finally #71 (integration tests).

---

Child Issues Created

Issue	Title	Dependencies
#66	Add WebAuthn server endpoints for registration and assertion	Phase 2
#67	Build minimal approval web UI	#66
#68	Add WebAuthn enrollment CLI command	#66
#69	Implement WebAuthn-gated grant approval flow	#66, #67
#70	Update notification channels to include approval links	#69
#71	Phase 3 integration tests and WebAuthn end-to-end validation	#69, #70

Dependency Graph

graph TD
    66[WebAuthn server endpoints]
    67[Approval web UI]
    68[WebAuthn enrollment CLI]
    69[WebAuthn-gated approval flow]
    70[Notification channel approval links]
    71[Phase 3 integration tests]
    66 --> 67
    66 --> 68
    66 --> 69
    67 --> 69
    69 --> 70
    69 --> 71
    70 --> 71
    click 66 "https://github.com/helixclaw/2keychains/issues/66"
    click 67 "https://github.com/helixclaw/2keychains/issues/67"
    click 68 "https://github.com/helixclaw/2keychains/issues/68"
    click 69 "https://github.com/helixclaw/2keychains/issues/69"
    click 70 "https://github.com/helixclaw/2keychains/issues/70"
    click 71 "https://github.com/helixclaw/2keychains/issues/71"

Loading