From dcecbd3edd7e7424ce7fcc1b22fd0ecb64f4ea6d Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Mon, 24 Aug 2026 05:52:03 +0000
Subject: [PATCH] feat(docs): add task for WebAuthn PRF extension

Added a new task markdown file `2026-0824.01.jul.feat.webauthn.prf-extension-1200.md` detailing the plan for integrating the WebAuthn PRF extension. It outlines the schema updates, client and server flow implementations, and progressive fallback logic as per Kanban guidelines.

Co-authored-by: mrteye <1945243+mrteye@users.noreply.github.com>
---
 ...01.jul.feat.webauthn.prf-extension-1200.md | 45 +++++++++++++++++++
 1 file changed, 45 insertions(+)
 create mode 100644 tasks/new/2026-0824.01.jul.feat.webauthn.prf-extension-1200.md

diff --git a/tasks/new/2026-0824.01.jul.feat.webauthn.prf-extension-1200.md b/tasks/new/2026-0824.01.jul.feat.webauthn.prf-extension-1200.md
new file mode 100644
index 0000000..2a4a675
--- /dev/null
+++ b/tasks/new/2026-0824.01.jul.feat.webauthn.prf-extension-1200.md
@@ -0,0 +1,45 @@
+# TASK METADATA
+
+- **Target Files:** `server/main.ts`, `server/db.ts`, `ui/public/auth-client.js`, `ui/components/RegisterPage.tsx`, `ui/components/LoginPage.tsx`
+- **Core Objective:** Implement WebAuthn PRF extension support for progressive feature detection and Key Encryption Key (KEK) derivation during registration and login, with graceful fallback.
+- **Dependencies:** WebCrypto API natively in Deno/browser, SimpleWebAuthn v13 for passing PRF extension options.
+- **Additional Important Notes:** This task establishes the PRF derivation pipeline. SSS multi-share reconstruction will integrate in a future story (3.3). If PRF is unsupported, registration/login must proceed normally without breaking standard WebAuthn flows.
+
+---
+
+## Architectural Considerations & Risks
+
+- **Risks:**
+  - **Authenticator Compatibility:** Not all authenticators support the WebAuthn PRF extension. A hard failure when PRF is missing would lock users out. The progressive fallback design is critical to prevent regressions in standard authentication.
+  - **Extension Types & SDK Mapping:** Passing the exact extension payloads for PRF (`eval.first`, `eval.second`) in `generateRegistrationOptions` and `generateAuthenticationOptions` might require careful type mapping if `SimpleWebAuthn` types are strict.
+  - **Database Migrations:** Modifying the `passkeys` table to include `prf_enabled` and `prf_salt` must maintain compatibility with existing passkey rows (which will default to false/null).
+- **Alternatives:**
+  - Traditional server-side wrapping (HSM/KMS) or user passwords could be used for key derivation. However, the WebAuthn PRF extension natively binds the encryption key material to the hardware authenticator itself, preserving Auth-Yes's passwordless UX and zero-trust properties without transmitting raw secrets.
+
+## Proposed Implementation
+
+### 1. Database Schema Updates (`server/db.ts`)
+- Modify the `passkeys` table schema to include a `prf_enabled BOOLEAN DEFAULT FALSE` column.
+- Add a `prf_salt` column (binary or hex string) to store the 32-byte cryptographic salt generated during registration.
+
+### 2. Registration Flow (Server & Client)
+- **Server (`server/main.ts`)**: In the `/api/register/challenge` endpoint, ensure the `prf: {}` extension is requested via `generateRegistrationOptions`.
+- **Client (`ui/public/auth-client.js`)**: Execute `navigator.credentials.create()` through the client SDK. Extract `getClientExtensionResults()?.prf`.
+- **Server (`server/main.ts`)**: In the `/api/register/verify` endpoint, inspect the extension results to check if PRF is enabled (`prf.enabled === true`). If supported, generate a 32-byte secure random salt (`prf_salt`). Store `prf_enabled: true` and the `prf_salt` alongside the new passkey record.
+
+### 3. Login Flow (Server & Client)
+- **Server (`server/main.ts`)**: In the `/api/login/challenge` endpoint, retrieve the user's `prf_salt` if their passkey has `prf_enabled`. Include the `prf: { eval: { first: <prf_salt> } }` extension payload in `generateAuthenticationOptions`.
+- **Client (`ui/public/auth-client.js`)**:
+  - Execute `navigator.credentials.get()` with the provided PRF evaluation salt.
+  - Check `getClientExtensionResults()?.prf?.results?.first` for the PRF output.
+- **Client-Side KEK Derivation**:
+  - If PRF output exists, use it as Input Keying Material (IKM) for WebCrypto HKDF to derive a 256-bit AES-GCM Key Encryption Key (KEK).
+  - **HKDF Parameters**:
+    - Hash: `SHA-256` (RFC 5869)
+    - Salt: 32-byte cryptographic salt (stored with passkey record)
+    - Info: `new TextEncoder().encode("auth-yes:prf:device-share:v1")`
+- **Progressive Fallback**:
+  - If `getClientExtensionResults()?.prf` is missing or fails, gracefully bypass the KEK derivation step and continue standard signature-only WebAuthn login.
+
+### 4. UI Integration (`ui/components/RegisterPage.tsx`, `ui/components/LoginPage.tsx`)
+- (Optional but recommended) Include minor, non-blocking UI indicators or debug logs to signify when advanced hardware encryption (PRF) is successfully negotiated, aiding in development and progressive feature adoption.