@tinytars/vault 0.1.15 → 0.1.17

package/README.md

@@ -120,6 +120,23 @@ against the D1 adapter passes against it, unmodified), and `adapters/pages-http`
 wrapper, not a rewrite, for Cloudflare Pages Functions' request shape). Full picture:
 [`ARCHITECTURE.md` § Adapters](ARCHITECTURE.md#adapters).
 
+### Reference client: auth flows wired to a real API
+
+`auth-client.ts`, `auth-recovery.ts`, `auth-support.ts`, `auth-grants.ts`, and `org-recovery.ts`:
+browser-side orchestration for signup, password/passkey login, Google SSO bootstrap, recovery-code
+issuance and redemption, provider/support access grants, and account-settings method management —
+built on `crypto.ts`'s primitives, calling a specific set of `/api/auth/*`, `/api/account/*`,
+`/api/support/*`, and `/api/providers/*` routes. `vault-session.ts` holds the `VaultEntry`/
+`VaultSession` types and `openVault()` these flows share to open a decrypted vault once a key is in
+hand.
+
+Unlike the four pieces above, this layer is a **reference implementation, not a portable
+primitive** — it's wired to one server API shape (documented in
+[`ARCHITECTURE.md` § Reference auth client](ARCHITECTURE.md#reference-auth-client-auth-clientts-and-friends)),
+the same way `vault-sink.ts`'s `r2Sink`/`localSink` are wired to specific save-vault routes. Read
+it as a worked example of composing `crypto.ts` into real signup/login/recovery/support flows, not
+something you import and point at your own backend unless your routes happen to match.
+
 ## Install
 
 ```
@@ -248,6 +265,13 @@ is entirely your own auth middleware's job. See `THREAT_MODEL.md`'s "trust bound
 | `adapters/memory.ts` | In-memory implementations of all five `stores.ts` contracts — the reference adapter that proves the interfaces are actually storage-agnostic, not just Cloudflare-shaped |
 | `adapters/pages-http.ts` | `pagesHandler()` — wraps a portable `(request, deps) => Promise<Response>` handler into Cloudflare Pages Functions' `onRequestX({request, env, params})` shape |
 | `adapters/conformance.ts` | Shared vitest contract suites for each `stores.ts` interface, run against every adapter above so "storage-agnostic" is proven, not asserted |
+| `auth-client.ts` | Password/passkey/Google signup, login, session resume, account-settings method management — the browser-side orchestration wiring `crypto.ts` to a specific `/api/auth/*`/`/api/account/*` API. Reference client, not a portable primitive |
+| `auth-recovery.ts` | Recovery-code issuance/redemption (owner and provider-issued), DEK rotation, access-event log fetch — same reference-client caveat as `auth-client.ts` |
+| `auth-support.ts` | Audited support-agent access: patient approves a pending request, support enters via an audited endpoint; support→provider roster access |
+| `auth-grants.ts` | Provider/clinician grant CRUD from the patient side: lookup, grant, revoke |
+| `org-recovery.ts` | Backfills the org-recovery envelope for accounts that predate or missed it at signup — best-effort, never blocks an unlock |
+| `vault-session.ts` | `VaultEntry`/`VaultSession` types plus `openVault()` — the decrypt-and-open-session step every unlock path shares |
+| `base64.ts` | Byte ↔ base64 codec used throughout the client layer |
 
 Full design, including the exact envelope byte layout and why extractable keys are a deliberate
 choice, is in `ARCHITECTURE.md` — see **What it does** above for the featureset summary and the

package/adapters/d1/accounts.ts

@@ -70,7 +70,7 @@ export async function getAccountByEmail(db: D1Database, email: string): Promise<
 /**
  * The instant before which this account's session cookies are no longer accepted, or null.
  *
- * Read on every authenticated request, by the adopter's own session-check middleware. One indexed lookup by primary
+ * Read on every authenticated request (see `requireSession`). One indexed lookup by primary
  * key is what buys revocability: the cookie is self-contained, so without a server-side fact to
  * check against, nothing short of rotating SESSION_SECRET for the entire deployment can invalidate one.
  */

package/adapters/d1/audit.ts

@@ -6,7 +6,7 @@ export type { AccessEvent };
 // bookkeeping are app-specific concerns that stay in the app's identity-audit.ts (see stores.ts's
 // own docstring on AuditStore).
 
-// FTC-HBNR (§I) PHI-access/disclosure audit log. Records WHO (actor) accessed WHOSE (subject)
+// FTC Health Breach Notification Rule PHI-access/disclosure audit log. Records WHO (actor) accessed WHOSE (subject)
 // vault and WHY (action + consent_ref), so a breach can be scoped to affected individuals. NO PHI.
 interface AccessEventRow {
   id: string;

package/adapters/d1/credentials.ts

@@ -99,8 +99,8 @@ export async function getCredential(db: D1Database, accountId: string, method: A
   return row ? mapCredential(row) : null;
 }
 
-// The account's key-bearing methods (password/passkey/recovery), for the account-settings screen and
-// the "don't orphan the vault key on remove" invariant. The credentials table is the source of truth (each
+// The account's key-bearing methods (password/passkey/recovery), for the Account screen and the
+// "don't orphan the vault key on remove" invariant. The credentials table is the source of truth (each
 // row independently wraps the same private key); identities lacks a recovery row.
 export async function listCredentials(db: D1Database, accountId: string): Promise<{ method: AuthMethod; createdAt: string }[]> {
   const { results } = await db

package/adapters/d1/providers.ts

@@ -68,7 +68,7 @@ export async function updateProviderLinkStatus(db: D1Database, id: string, statu
   await db.prepare("UPDATE provider_links SET status = ? WHERE id = ?").bind(status, id).run();
 }
 
-// An owner approving a support request: flip the link active, stamp its time-box + consent.
+// A patient approving a support request: flip the link active, stamp its time-box + consent.
 export async function grantSupportLink(
   db: D1Database,
   id: string,

package/adapters/r2.ts

@@ -1,14 +1,13 @@
 import type { BlobStore, BlobConditional, StoredBlob } from "../blob-store";
 
 // Minimal structural type for the R2 binding — no @cloudflare/workers-types dependency, and
-// trivially mockable in tests. An adopter's own Pages Function route should import R2Bucket/
-// R2BlobStore from here instead of declaring its own copy.
+// trivially mockable in tests.
 export interface R2ObjectBody {
   body: ReadableStream;
   /** The version token. Handed to the browser on GET and sent back as If-Match on PUT. */
   etag: string;
 }
-/** A precondition on a write. Verify this against real `workerd` in an adopter's own test suite — see ARCHITECTURE.md's "Adapters" section. */
+/** A precondition on a write. Real workerd conditional-write semantics are verified in an adopter's own test suite, not here — see CHANGELOG.md. */
 export interface R2Conditional {
   etagMatches?: string;
   etagDoesNotMatch?: string;
@@ -17,8 +16,8 @@ export interface R2Bucket {
   get(key: string): Promise<R2ObjectBody | null>;
   /**
    * Returns the stored object (carrying its NEW etag), or `null` when an `onlyIf` precondition fails.
-   * Null-on-failure rather than a throw is observed behaviour, not an assumption — see
-   * tests/unit/r2-conditional-put.test.ts, which pins it against workerd.
+   * Null-on-failure rather than a throw is observed behaviour against workerd, not an assumption —
+   * an adopter's own test suite is where this gets pinned; see CHANGELOG.md.
    */
   put(key: string, value: Uint8Array, options?: { onlyIf?: R2Conditional }): Promise<{ etag: string } | null>;
   delete(key: string): Promise<void>;

package/auth-client.ts

@@ -0,0 +1,422 @@
+// Browser-side orchestration for password signup/login. All crypto primitives
+// live in ./crypto (do not reimplement); this file only wires them to fetch calls against
+// an adopter's own password-auth endpoints. The server never sees a password, a KEK, or a DEK.
+import {
+  generateAccountKeypair,
+  deriveKekFromPassword,
+  deriveAuthHash,
+  wrapPrivateKey,
+  unwrapPrivateKey,
+  generateDEK,
+  encryptVaultV2,
+  wrapDEKForPublicKey,
+  unwrapDEKWithPrivateKey,
+  kekFromPrfSecret,
+  importPrivateKeyPkcs8,
+} from "./crypto";
+import { startRegistration, startAuthentication, base64URLStringToBuffer } from "@simplewebauthn/browser";
+import type {
+  PublicKeyCredentialCreationOptionsJSON,
+  PublicKeyCredentialRequestOptionsJSON,
+} from "@simplewebauthn/browser";
+import { bytesToB64 as bytesToBase64, b64ToBytes as base64ToBytes } from "./base64";
+export { bytesToB64 as bytesToBase64, b64ToBytes as base64ToBytes } from "./base64";
+
+export const KDF_ITERATIONS = 200_000;
+export const rand = (n: number) => globalThis.crypto.getRandomValues(new Uint8Array(n));
+
+export function bytesToHex(bytes: Uint8Array): string {
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+export function hexToBytes(hex: string): Uint8Array {
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < bytes.length; i++) bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  return bytes;
+}
+
+// The org-recovery public key, fetched pre-session (signup has no session yet; a public key
+// is public regardless of who asks for it).
+/**
+ * The error the server actually wrote, when it wrote one.
+ *
+ * Nearly every branch below threw `${what} failed: ${res.status}`, discarding a message the
+ * endpoint had already composed for exactly this moment ("that recovery code has expired", "this
+ * clinician already has access", "no access to this vault") and showing a patient a bare number
+ * instead. These are the paths a person is on during the worst day they will have with this app, and
+ * a status code tells them nothing about whether to retry, wait, or ask someone.
+ *
+ * The status is kept in the fallback so a failure with no body is still diagnosable. Deliberately NOT
+ * used on the salt lookups: those return a decoy for an unknown address, so any detail there would be
+ * an answer about whether the account exists.
+ */
+export async function failed(res: Response, what: string): Promise<Error> {
+  const body = (await res.json().catch(() => null)) as { error?: string } | null;
+  return new Error(body?.error?.trim() || `${what} (${res.status})`);
+}
+
+export async function getOrgKey(): Promise<{ orgAccountId: string; orgPublicKeyJwk: JsonWebKey }> {
+  const res = await fetch("/api/vault/org-key");
+  if (!res.ok) throw await failed(res, "org key failed");
+  return res.json();
+}
+
+// Everything below this point that authenticates a stranger — signup, both login paths, the Google
+// bootstrap, and redeeming a recovery code — deliberately does NOT use `failed()`. A reason there is
+// an answer about whether an address is registered, which is the enumeration oracle the decoy salt at
+// /api/auth/salt exists to close — an adopter's own tests are where "the enumeration oracle stays
+// closed" gets pinned. Once a session exists there is nobody left to enumerate to, and the server's
+// message helps.
+export async function signupPassword(
+  email: string,
+  displayName: string,
+  password: string
+): Promise<{ accountId: string; vaultId: string }> {
+  const { publicKeyJwk, privateKey } = await generateAccountKeypair();
+
+  const salt = rand(16);
+  const kek = await deriveKekFromPassword(password, salt);
+  const wrappedPrivateKey = await wrapPrivateKey(privateKey, kek);
+  const authHash = await deriveAuthHash(password, salt);
+
+  const dek = await generateDEK();
+  const vaultBlob = await encryptVaultV2({ clients: {} }, dek);
+  const ownerEnvelope = await wrapDEKForPublicKey(dek, publicKeyJwk);
+  const { orgPublicKeyJwk } = await getOrgKey();
+  const orgEnvelope = await wrapDEKForPublicKey(dek, orgPublicKeyJwk);
+
+  // No recovery credential at signup; the user mints one on demand from the Account menu.
+  const res = await fetch("/api/auth/password/signup", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({
+      email,
+      displayName,
+      publicKeyJwk,
+      wrappedPrivateKey: bytesToBase64(wrappedPrivateKey),
+      kdfParams: { salt: bytesToHex(salt), iterations: KDF_ITERATIONS },
+      authHash,
+      vaultBlob: bytesToBase64(vaultBlob),
+      ownerEnvelope: {
+        wrappedDEK: bytesToBase64(ownerEnvelope.wrappedDEK),
+        ephemeralPublicKeyJwk: ownerEnvelope.ephemeralPublicKeyJwk,
+      },
+      orgEnvelope: {
+        wrappedDEK: bytesToBase64(orgEnvelope.wrappedDEK),
+        ephemeralPublicKeyJwk: orgEnvelope.ephemeralPublicKeyJwk,
+      },
+    }),
+  });
+  if (!res.ok) throw new Error(`signup failed: ${res.status}`);
+  const { accountId, vaultId } = (await res.json()) as { accountId: string; vaultId: string };
+  return { accountId, vaultId };
+}
+
+export async function loginPassword(
+  email: string,
+  password: string
+): Promise<{
+  accountId: string;
+  vaultId: string | null;
+  r2Key: string | null;
+  privateKey: CryptoKey;
+  dek: CryptoKey | null;
+  rotationPending: boolean;
+}> {
+  // Salt is public, but the client needs it before it can derive authHash — look it up
+  // by email ahead of the login POST.
+  const saltRes = await fetch(`/api/auth/password/salt?email=${encodeURIComponent(email)}`);
+  // NOT "unknown account" any more. The endpoint returns a decoy salt for an address it does
+  // not know, precisely so the browser cannot report which addresses are registered; a non-200 here
+  // now means a malformed request or a server fault, and saying "unknown account" would both be
+  // wrong and re-open the oracle in the UI text.
+  if (!saltRes.ok) throw new Error(`sign-in is unavailable right now (${saltRes.status})`);
+  const { salt } = (await saltRes.json()) as { salt: string; iterations: number };
+
+  const authHash = await deriveAuthHash(password, hexToBytes(salt));
+
+  const res = await fetch("/api/auth/password/login", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ email, authHash }),
+  });
+  if (!res.ok) throw new Error(`login failed: ${res.status}`);
+  const data = (await res.json()) as {
+    accountId: string;
+    vaultId: string | null;
+    r2Key: string | null;
+    wrappedPrivateKey: string;
+    kdfParams: { salt: string; iterations: number };
+    ownerEnvelope: { wrappedDEK: string; ephemeralPublicKeyJwk: JsonWebKey } | null;
+  };
+
+  const kek = await deriveKekFromPassword(password, hexToBytes(data.kdfParams.salt));
+  const privateKey = await unwrapPrivateKey(base64ToBytes(data.wrappedPrivateKey), kek);
+  const dek = data.ownerEnvelope
+    ? await unwrapDEKWithPrivateKey(base64ToBytes(data.ownerEnvelope.wrappedDEK), data.ownerEnvelope.ephemeralPublicKeyJwk, privateKey)
+    : null;
+
+  return { accountId: data.accountId, vaultId: data.vaultId, r2Key: data.r2Key, privateKey, dek, rotationPending: (data as { rotationPending?: boolean }).rotationPending ?? false };
+}
+
+// Browser-side orchestration for passkey (WebAuthn + PRF) signup/login. Mirrors
+// signupPassword/loginPassword above: all crypto stays in ./crypto, this file only wires it to
+// startRegistration/startAuthentication and an adopter's own passkey-auth endpoints. The server
+// never sees the PRF secret, a KEK, or a DEK.
+
+// The server sends the PRF extension's `eval.first` as a base64url STRING (see webauthn.ts) —
+// startRegistration/startAuthentication spread `extensions` straight into
+// navigator.credentials.{create,get}() without decoding custom extensions, so we must convert
+// it back into a BufferSource ourselves before calling them.
+function preparePrfExtension<T extends { extensions?: unknown }>(optionsJSON: T): T {
+  const ext = optionsJSON.extensions as { prf?: { eval?: { first?: string } } } | undefined;
+  if (!ext?.prf?.eval?.first) return optionsJSON;
+  return {
+    ...optionsJSON,
+    extensions: { ...ext, prf: { eval: { first: base64URLStringToBuffer(ext.prf.eval.first) } } },
+  } as T;
+}
+
+function extractPrfSecret(clientExtensionResults: unknown): Uint8Array | null {
+  const first = (clientExtensionResults as { prf?: { results?: { first?: ArrayBuffer } } } | undefined)?.prf?.results?.first;
+  return first ? new Uint8Array(first) : null;
+}
+
+export async function signupPasskey(
+  email: string,
+  displayName: string
+): Promise<{ accountId: string; vaultId: string }> {
+  const optionsRes = await fetch("/api/auth/passkey/register/options", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ email, displayName }),
+  });
+  if (!optionsRes.ok) throw await failed(optionsRes, "register options failed");
+  const optionsJSON = (await optionsRes.json()) as PublicKeyCredentialCreationOptionsJSON;
+  const prfSaltB64 = (optionsJSON.extensions as { prf?: { eval?: { first?: string } } } | undefined)?.prf?.eval?.first;
+  if (!prfSaltB64) throw new Error("registration options missing the PRF extension");
+
+  const attestationResponse = await startRegistration({ optionsJSON: preparePrfExtension(optionsJSON) });
+
+  let prfSecret = extractPrfSecret(attestationResponse.clientExtensionResults);
+  if (!prfSecret) {
+    // Some authenticators don't evaluate PRF during create() — fall back to a local get()
+    // ceremony against the credential we just made, purely to read the PRF secret. This is not
+    // sent to the server; the create() attestation above is what gets verified server-side.
+    const fallbackOptions: PublicKeyCredentialRequestOptionsJSON = {
+      challenge: bytesToBase64(rand(16)),
+      allowCredentials: [{ id: attestationResponse.id, type: "public-key", transports: attestationResponse.response.transports }],
+      userVerification: "preferred",
+      extensions: { prf: { eval: { first: base64URLStringToBuffer(prfSaltB64) } } } as PublicKeyCredentialRequestOptionsJSON["extensions"],
+    };
+    const fallbackAssertion = await startAuthentication({ optionsJSON: fallbackOptions });
+    prfSecret = extractPrfSecret(fallbackAssertion.clientExtensionResults);
+    if (!prfSecret) throw new Error("authenticator does not support the PRF extension");
+  }
+
+  const kek = await kekFromPrfSecret(prfSecret);
+  const { publicKeyJwk, privateKey } = await generateAccountKeypair();
+  const wrappedPrivateKey = await wrapPrivateKey(privateKey, kek);
+
+  const dek = await generateDEK();
+  const vaultBlob = await encryptVaultV2({ clients: {} }, dek);
+  const ownerEnvelope = await wrapDEKForPublicKey(dek, publicKeyJwk);
+  const { orgPublicKeyJwk } = await getOrgKey();
+  const orgEnvelope = await wrapDEKForPublicKey(dek, orgPublicKeyJwk);
+
+  // No recovery credential at signup; minted on demand from the Account menu.
+  const verifyRes = await fetch("/api/auth/passkey/register/verify", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({
+      attestationResponse,
+      publicKeyJwk,
+      wrappedPrivateKey: bytesToBase64(wrappedPrivateKey),
+      vaultBlob: bytesToBase64(vaultBlob),
+      ownerEnvelope: {
+        wrappedDEK: bytesToBase64(ownerEnvelope.wrappedDEK),
+        ephemeralPublicKeyJwk: ownerEnvelope.ephemeralPublicKeyJwk,
+      },
+      orgEnvelope: {
+        wrappedDEK: bytesToBase64(orgEnvelope.wrappedDEK),
+        ephemeralPublicKeyJwk: orgEnvelope.ephemeralPublicKeyJwk,
+      },
+      prfSaltHex: bytesToHex(new Uint8Array(base64URLStringToBuffer(prfSaltB64))),
+    }),
+  });
+  if (!verifyRes.ok) throw await failed(verifyRes, "register verify failed");
+  const { accountId, vaultId } = (await verifyRes.json()) as { accountId: string; vaultId: string };
+  return { accountId, vaultId };
+}
+
+export async function loginPasskey(
+  email: string
+): Promise<{ accountId: string; vaultId: string | null; r2Key: string | null; privateKey: CryptoKey; dek: CryptoKey | null; rotationPending: boolean }> {
+  const optionsRes = await fetch("/api/auth/passkey/login/options", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ email }),
+  });
+  if (!optionsRes.ok) throw new Error(`login options failed: ${optionsRes.status}`);
+  const optionsJSON = (await optionsRes.json()) as PublicKeyCredentialRequestOptionsJSON;
+
+  const authenticationResponse = await startAuthentication({ optionsJSON: preparePrfExtension(optionsJSON) });
+  const prfSecret = extractPrfSecret(authenticationResponse.clientExtensionResults);
+  if (!prfSecret) throw new Error("authenticator did not return a PRF secret");
+
+  const verifyRes = await fetch("/api/auth/passkey/login/verify", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ authenticationResponse }),
+  });
+  if (!verifyRes.ok) throw new Error(`login verify failed: ${verifyRes.status}`);
+  const data = (await verifyRes.json()) as {
+    accountId: string;
+    vaultId: string | null;
+    r2Key: string | null;
+    wrappedPrivateKey: string;
+    prfSalt: string;
+    ownerEnvelope: { wrappedDEK: string; ephemeralPublicKeyJwk: JsonWebKey } | null;
+  };
+
+  const kek = await kekFromPrfSecret(prfSecret);
+  const privateKey = await unwrapPrivateKey(base64ToBytes(data.wrappedPrivateKey), kek);
+  const dek = data.ownerEnvelope
+    ? await unwrapDEKWithPrivateKey(base64ToBytes(data.ownerEnvelope.wrappedDEK), data.ownerEnvelope.ephemeralPublicKeyJwk, privateKey)
+    : null;
+
+  return { accountId: data.accountId, vaultId: data.vaultId, r2Key: data.r2Key, privateKey, dek, rotationPending: (data as { rotationPending?: boolean }).rotationPending ?? false };
+}
+
+// Google login bootstrap. After the OAuth callback redirects to /?google=1 the session is
+// already set; this fetches the server-unwrapped private key + owner envelope and recovers the DEK
+// client-side. Returns the same shape as loginPassword so it flows straight into an adopter's own
+// account-entry step. Unlike password/passkey, the private key is handed over by the server
+// (server-custody) rather than unwrapped from a client-held secret.
+export async function bootstrapGoogleSession(): Promise<{
+  accountId: string;
+  vaultId: string | null;
+  r2Key: string | null;
+  privateKey: CryptoKey;
+  dek: CryptoKey | null;
+  rotationPending: boolean;
+}> {
+  const res = await fetch("/api/auth/google/session", { cache: "no-store" });
+  if (!res.ok) throw new Error(`google session failed: ${res.status}`);
+  const data = (await res.json()) as {
+    accountId: string;
+    vaultId: string | null;
+    r2Key: string | null;
+    rotationPending: boolean;
+    privateKeyPkcs8: string;
+    ownerEnvelope: { wrappedDEK: string; ephemeralPublicKeyJwk: JsonWebKey } | null;
+  };
+  const privateKey = await importPrivateKeyPkcs8(base64ToBytes(data.privateKeyPkcs8));
+  const dek = data.ownerEnvelope
+    ? await unwrapDEKWithPrivateKey(base64ToBytes(data.ownerEnvelope.wrappedDEK), data.ownerEnvelope.ephemeralPublicKeyJwk, privateKey)
+    : null;
+  return { accountId: data.accountId, vaultId: data.vaultId, r2Key: data.r2Key, privateKey, dek, rotationPending: data.rotationPending };
+}
+
+// Plain-refresh resume (password/passkey). Session-gated read of the vault location + owner DEK
+// envelope; the client already holds the account private key (non-extractable, from IndexedDB) and
+// unwraps the DEK locally. Returns null when there's no valid session (401) so the caller can fall
+// back to the lock screen. Does NOT return the wrapped private key — the key never leaves the device.
+export async function resumeSession(): Promise<{
+  accountId: string;
+  vaultId: string | null;
+  r2Key: string | null;
+  rotationPending: boolean;
+  providerKind: "clinician" | "support" | null;
+  ownerEnvelope: { wrappedDEK: string; ephemeralPublicKeyJwk: JsonWebKey } | null;
+} | null> {
+  const res = await fetch("/api/auth/session/resume", { cache: "no-store" });
+  if (res.status === 401) return null;
+  if (!res.ok) throw await failed(res, "resume failed");
+  return res.json();
+}
+
+// Finish adding Google to the signed-in account. The OAuth popup already set the signed
+// link cookie (bound to this account + the verified sub); here we hand the server the in-memory
+// private key so it can wrap it under the server KEK. The sub is trusted from the cookie, not us.
+export async function addGoogleMethod(privateKey: CryptoKey, currentPassword?: string, email?: string): Promise<void> {
+  const currentAuthHash = await currentAuthHashFor(email, currentPassword);
+  const pkcs8 = new Uint8Array(await globalThis.crypto.subtle.exportKey("pkcs8", privateKey));
+  const res = await fetch("/api/account/methods/google", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ privateKeyPkcs8: bytesToBase64(pkcs8), ...(currentAuthHash ? { currentAuthHash } : {}) }),
+  });
+  if (!res.ok) throw new Error((await res.json().catch(() => ({}))).error || `add google failed: ${res.status}`);
+}
+
+export async function getMyAccount(): Promise<{ id: string; email: string | null; emailConfirmed: boolean; displayName: string; providerKind: "clinician" | "support" | null; unitSystem: "metric" | "imperial" | null }> {
+  const res = await fetch("/api/account", { cache: "no-store" });
+  if (!res.ok) throw await failed(res, "account fetch failed");
+  return res.json();
+}
+
+// Account settings. Change email/display name; add/remove a login method (password/passkey).
+// Adding a method re-wraps the account's in-memory private key under the new method's KEK — same
+// zero-knowledge model as signup; the server never sees the key.
+
+/**
+ * The step-up proof, derived the same way the login path derives its authHash.
+ *
+ * Shared by all three add-a-method calls. Adding a passkey or a Google identity used to need only a
+ * session cookie, which meant a captured cookie could mint a credential that outlived it; the server
+ * now challenges those paths too, so all three send the same proof.
+ *
+ * Returns undefined when there is nothing to prove — an account with no password cannot be challenged,
+ * and the server treats that case as allowed-and-notified rather than refusing it.
+ */
+export async function currentAuthHashFor(email?: string, currentPassword?: string): Promise<string | undefined> {
+  if (!currentPassword || !email) return undefined;
+  const saltRes = await fetch(`/api/auth/password/salt?email=${encodeURIComponent(email)}`);
+  if (!saltRes.ok) throw new Error(`could not verify your current password (${saltRes.status})`);
+  const { salt: currentSalt } = (await saltRes.json()) as { salt: string };
+  return deriveAuthHash(currentPassword, hexToBytes(currentSalt));
+}
+
+export async function addPasskeyMethod(privateKey: CryptoKey, currentPassword?: string, email?: string): Promise<void> {
+  const currentAuthHash = await currentAuthHashFor(email, currentPassword);
+  const optionsRes = await fetch("/api/account/methods/passkey/options", { method: "POST" });
+  if (!optionsRes.ok) throw await failed(optionsRes, "passkey options failed");
+  const optionsJSON = (await optionsRes.json()) as PublicKeyCredentialCreationOptionsJSON;
+  const prfSaltB64 = (optionsJSON.extensions as { prf?: { eval?: { first?: string } } } | undefined)?.prf?.eval?.first;
+  if (!prfSaltB64) throw new Error("registration options missing the PRF extension");
+
+  const attestationResponse = await startRegistration({ optionsJSON: preparePrfExtension(optionsJSON) });
+  let prfSecret = extractPrfSecret(attestationResponse.clientExtensionResults);
+  if (!prfSecret) {
+    // Some authenticators don't evaluate PRF during create() — read it via a local get() (not sent).
+    const fallbackAssertion = await startAuthentication({
+      optionsJSON: {
+        challenge: bytesToBase64(rand(16)),
+        allowCredentials: [{ id: attestationResponse.id, type: "public-key", transports: attestationResponse.response.transports }],
+        userVerification: "preferred",
+        extensions: { prf: { eval: { first: base64URLStringToBuffer(prfSaltB64) } } } as PublicKeyCredentialRequestOptionsJSON["extensions"],
+      },
+    });
+    prfSecret = extractPrfSecret(fallbackAssertion.clientExtensionResults);
+    if (!prfSecret) throw new Error("authenticator does not support the PRF extension");
+  }
+
+  const kek = await kekFromPrfSecret(prfSecret);
+  const wrappedPrivateKey = await wrapPrivateKey(privateKey, kek);
+  const verifyRes = await fetch("/api/account/methods/passkey/verify", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({
+      attestationResponse,
+      wrappedPrivateKey: bytesToBase64(wrappedPrivateKey),
+      prfSaltHex: bytesToHex(new Uint8Array(base64URLStringToBuffer(prfSaltB64))),
+      ...(currentAuthHash ? { currentAuthHash } : {}),
+    }),
+  });
+  if (verifyRes.status === 401) {
+    const { error } = (await verifyRes.json().catch(() => ({ error: "" }))) as { error?: string };
+    throw new Error(error || "enter your current password to add a passkey");
+  }
+  if (!verifyRes.ok) throw await failed(verifyRes, "add passkey failed");
+}

package/auth-grants.ts

@@ -0,0 +1,55 @@
+import { wrapDEKForPublicKey } from "./crypto";
+import { bytesToBase64, failed } from "./auth-client";
+
+// Provider escrow (patient side). A logged-in patient grants a provider access by wrapping
+// their in-memory DEK to the provider's public key client-side and posting the opaque envelope; the
+// server never sees a plaintext DEK. Revoke deletes the envelope + marks the link revoked.
+
+export interface ProviderLinkView {
+  linkId: string;
+  providerAccountId: string;
+  displayName: string;
+  kind: "clinician" | "support";
+  status: "invited" | "active" | "revoked";
+  expiresAt: string | null;
+  publicKeyJwk?: JsonWebKey | null; // present only for a pending (invited) support request
+}
+
+export async function listMyProviders(): Promise<ProviderLinkView[]> {
+  const res = await fetch("/api/providers", { cache: "no-store" });
+  if (!res.ok) throw await failed(res, "list providers failed");
+  return ((await res.json()) as { providers: ProviderLinkView[] }).providers;
+}
+
+// Resolve a provider by email to their public key; null if no such provider (uniform 404).
+export async function lookupProvider(
+  email: string
+): Promise<{ providerAccountId: string; displayName: string; providerKind: string; publicKeyJwk: JsonWebKey } | null> {
+  const res = await fetch(`/api/providers/lookup?email=${encodeURIComponent(email)}`);
+  if (res.status === 404) return null;
+  if (!res.ok) throw await failed(res, "lookup failed");
+  return res.json();
+}
+
+// Grant a looked-up provider access to the caller's vault. `dek` is the owner's in-memory DEK.
+export async function grantProvider(
+  dek: CryptoKey,
+  provider: { providerAccountId: string; publicKeyJwk: JsonWebKey }
+): Promise<void> {
+  const env = await wrapDEKForPublicKey(dek, provider.publicKeyJwk);
+  const res = await fetch("/api/providers/grant", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({
+      providerAccountId: provider.providerAccountId,
+      wrappedDEK: bytesToBase64(env.wrappedDEK),
+      ephemeralPublicKeyJwk: env.ephemeralPublicKeyJwk,
+    }),
+  });
+  if (!res.ok) throw await failed(res, "grant failed");
+}
+
+export async function revokeProvider(linkId: string): Promise<void> {
+  const res = await fetch(`/api/providers/${encodeURIComponent(linkId)}`, { method: "DELETE" });
+  if (!res.ok) throw await failed(res, "revoke failed");
+}