@tinytars/vault 0.1.15 → 0.1.17

package/auth-recovery.ts

@@ -0,0 +1,360 @@
+import {
+  generateAccountKeypair,
+  deriveKekFromPassword,
+  deriveAuthHash,
+  wrapPrivateKey,
+  unwrapPrivateKey,
+  wrapDEKWithKek,
+  unwrapDEKWithKek,
+  wrapDEKForPublicKey,
+  unwrapDEKWithPrivateKey,
+} from "./crypto";
+import { bytesToBase64, base64ToBytes, bytesToHex, hexToBytes, rand, failed, KDF_ITERATIONS, currentAuthHashFor } from "./auth-client";
+
+// Not a security boundary (the recovery KEK is still PBKDF2-derived from this code) —
+// just a printable code the user can write down. Excludes ambiguous chars (0/O, 1/I).
+const RECOVERY_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+function randomRecoveryCode(): string {
+  return Array.from(rand(20), (b) => RECOVERY_ALPHABET[b % RECOVERY_ALPHABET.length]).join("");
+}
+
+// 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.
+
+export interface LoginMethod {
+  method: "password" | "passkey" | "google" | "recovery";
+  createdAt: string;
+  isRecovery: boolean;
+}
+
+export async function listMethods(): Promise<LoginMethod[]> {
+  const res = await fetch("/api/account/methods", { cache: "no-store" });
+  if (!res.ok) throw await failed(res, "list methods failed");
+  return ((await res.json()) as { methods: LoginMethod[] }).methods;
+}
+
+export async function updateProfile(updates: { email?: string; displayName?: string; unitSystem?: "metric" | "imperial" }): Promise<void> {
+  const res = await fetch("/api/account", { method: "PATCH", headers: { "content-type": "application/json" }, body: JSON.stringify(updates) });
+  if (!res.ok) throw await failed(res, "profile update failed");
+}
+
+export async function removeMethod(method: "password" | "passkey" | "google"): Promise<void> {
+  const res = await fetch("/api/account/methods", { method: "DELETE", headers: { "content-type": "application/json" }, body: JSON.stringify({ method }) });
+  if (!res.ok) throw await failed(res, "remove method failed");
+}
+
+/**
+ * Sets or replaces the account password.
+ *
+ * `currentPassword` is the step-up proof, and is REQUIRED by the server whenever a password
+ * already exists. It is derived against the account's CURRENT salt, fetched by email, because an
+ * authHash is only meaningful paired with the salt it was derived from; deriving the proof against
+ * the new salt would produce a value that matches nothing.
+ *
+ * Undefined is correct for an account setting its first password — a passkey-only or Google-only
+ * account has nothing to prove and nothing is being destroyed.
+ */
+export async function addPasswordMethod(
+  privateKey: CryptoKey,
+  newPassword: string,
+  currentPassword?: string,
+  email?: string,
+): Promise<void> {
+  const currentAuthHash = await currentAuthHashFor(email, currentPassword);
+
+  const salt = rand(16);
+  const kek = await deriveKekFromPassword(newPassword, salt);
+  const wrappedPrivateKey = await wrapPrivateKey(privateKey, kek);
+  const authHash = await deriveAuthHash(newPassword, salt);
+  const res = await fetch("/api/account/methods", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({
+      method: "password",
+      wrappedPrivateKey: bytesToBase64(wrappedPrivateKey),
+      kdfParams: { salt: bytesToHex(salt), iterations: KDF_ITERATIONS },
+      authHash,
+      ...(currentAuthHash ? { currentAuthHash } : {}),
+    }),
+  });
+  if (res.status === 401) {
+    const { error } = (await res.json().catch(() => ({ error: "" }))) as { error?: string };
+    throw new Error(error || "enter your current password to set a new one");
+  }
+  if (!res.ok) throw await failed(res, "add password failed");
+}
+
+// Recover with a recovery code (mirrors loginPassword, keyed on the recovery credential).
+// Returns the same shape as loginPassword so it flows straight into the app's enter-account path.
+export async function recoverAccount(
+  email: string,
+  recoveryCode: string,
+  /**
+   * The replacement password, set as part of redeeming the code.
+   *
+   * Without this the flow was a trap: redeeming signed you in but left the forgotten password in place,
+   * so the next sign-in put you right back where you started. It cannot be a follow-up call to
+   * `/api/account/methods` either — the account still holds its old password credential, so the
+   * add-a-method step-up would demand the very password being recovered.
+   *
+   * So the code is redeemed TWICE against the same endpoint: once to obtain the wrapped key (which is
+   * the only way to get it — the server releases it on proof, never on request), and once to install
+   * the re-wrapped key. The second call re-proves the recovery code, so the replacement is authorised
+   * by the code rather than by the session the first call happened to mint.
+   */
+  newPassword?: string,
+): Promise<{ accountId: string; vaultId: string | null; r2Key: string | null; privateKey: CryptoKey; dek: CryptoKey | null; rotationPending: boolean }> {
+  const saltRes = await fetch(`/api/auth/recovery/salt?email=${encodeURIComponent(email)}`);
+  // Same as the password path above: a decoy is returned for an address with no recovery credential,
+  // so a non-200 is a fault, not an answer about the account.
+  if (!saltRes.ok) throw new Error(`recovery is unavailable right now (${saltRes.status})`);
+  const { salt } = (await saltRes.json()) as { salt: string; iterations: number };
+
+  const recoveryAuthHash = await deriveAuthHash(recoveryCode, hexToBytes(salt));
+  const res = await fetch("/api/auth/recovery/login", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ email, recoveryAuthHash }),
+  });
+  if (!res.ok) throw new Error(`recovery 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(recoveryCode, 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;
+
+  if (newPassword) {
+    // The SAME private key, re-wrapped under a KEK derived from the new password. It is not a new
+    // keypair, which is why the account's passkey and Google credentials keep working afterwards.
+    const newSalt = rand(16);
+    const newKek = await deriveKekFromPassword(newPassword, newSalt);
+    const install = await fetch("/api/auth/recovery/login", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        email,
+        recoveryAuthHash,
+        newCredential: {
+          wrappedPrivateKey: bytesToBase64(await wrapPrivateKey(privateKey, newKek)),
+          kdfParams: { salt: bytesToHex(newSalt), iterations: KDF_ITERATIONS },
+          authHash: await deriveAuthHash(newPassword, newSalt),
+        },
+      }),
+    });
+    // Deliberately loud rather than silent: the caller is already signed in at this point, so a
+    // swallowed failure would leave the user believing they had set a password they had not.
+    if (!install.ok) throw new Error(`your code was accepted but the new password could not be saved (${install.status}) — try setting it from Account settings`);
+  }
+
+  return { accountId: data.accountId, vaultId: data.vaultId, r2Key: data.r2Key, privateKey, dek, rotationPending: (data as { rotationPending?: boolean }).rotationPending ?? false };
+}
+
+// Regenerate the recovery code (owner session): re-wrap the in-memory private key under a fresh code +
+// store the verifier. Returns the new code to display once.
+// ── Provider-issued recovery ──────────────────────────────────────────────────
+// Apple's recovery-contact model: a clinician who already holds the patient's DEK re-wraps it under a
+// one-time code and READS THE CODE TO THEM. It is never emailed — see RECOVERY.md I2; the server would
+// have to be given the code, and it already holds the wrapped DEK.
+
+// Crockford base32, minus the characters that are misheard or mistyped (I/L/O/U). 12 characters ≈ 60
+// bits, which is only safe because the server caps attempts and expires the grant in an hour — a code
+// short enough to read down a phone line cannot also resist an unbounded oracle.
+const GRANT_ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+export function randomGrantCode(): string {
+  const raw = Array.from(rand(12), (b) => GRANT_ALPHABET[b % GRANT_ALPHABET.length]).join("");
+  return `${raw.slice(0, 4)}-${raw.slice(4, 8)}-${raw.slice(8)}`;
+}
+
+/** Strips the display grouping so "a7k2-9qmf-3xpb" and "A7K29QMF3XPB" are the same code. */
+export function normalizeGrantCode(input: string): string {
+  return input.replace(/[^0-9A-Za-z]/g, "").toUpperCase();
+}
+
+/**
+ * Which ladder rung a pasted/typed string belongs to, by shape alone. `randomRecoveryCode`
+ * always emits 20 raw characters; `randomGrantCode` always emits 12 (displayed grouped). No
+ * collision is possible by construction, so the stripped length alone is enough to route —
+ * this never has to look at what the string actually contains.
+ */
+export function detectRecoveryKind(raw: string): "code" | "grant" {
+  return normalizeGrantCode(raw).length === 12 ? "grant" : "code";
+}
+
+/**
+ * Clinician side. Unwraps the patient's DEK with the clinician's own key — which is what provider
+ * access already is — and re-wraps it under the code. Returns the code to display once.
+ */
+export async function issueRecoveryCode(
+  patientAccountId: string,
+  envelope: { wrappedDEK: string; ephemeralPublicKeyJwk: JsonWebKey },
+  providerKey: CryptoKey,
+): Promise<{ code: string; expiresAt: string }> {
+  const code = randomGrantCode();
+  const normalized = normalizeGrantCode(code);
+  const dek = await unwrapDEKWithPrivateKey(base64ToBytes(envelope.wrappedDEK), envelope.ephemeralPublicKeyJwk, providerKey);
+  const salt = rand(16);
+  const res = await fetch("/api/recovery/grant", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({
+      patientAccountId,
+      wrappedDek: bytesToBase64(await wrapDEKWithKek(dek, await deriveKekFromPassword(normalized, salt))),
+      kdfParams: { salt: bytesToHex(salt), iterations: KDF_ITERATIONS },
+      codeAuthHash: await deriveAuthHash(normalized, salt),
+    }),
+  });
+  if (!res.ok) throw new Error((await res.json().catch(() => ({}))).error || `could not issue a recovery code (${res.status})`);
+  return { code, expiresAt: (await res.json()).expiresAt };
+}
+
+/**
+ * Patient side. Two calls against the same endpoint: the first proves the code and returns the wrapped
+ * DEK, the second installs a brand-new keypair locked under the new password. The code is proved on
+ * both — the second is not authorised by the first having happened.
+ *
+ * Unlike `recoverAccount`, this MINTS A NEW KEYPAIR rather than re-wrapping the old one, because the
+ * old private key is exactly what the patient no longer has. That is why the server clears the other
+ * credentials: they wrap a key nothing references any more.
+ */
+export async function redeemRecoveryCode(
+  email: string,
+  code: string,
+  newPassword: string,
+): Promise<{ accountId: string; vaultId: string | null; r2Key: string | null; privateKey: CryptoKey; dek: CryptoKey; rotationPending: boolean }> {
+  const normalized = normalizeGrantCode(code);
+  const saltRes = await fetch(`/api/auth/recovery/grant-salt?email=${encodeURIComponent(email)}`);
+  if (!saltRes.ok) throw new Error(`recovery is unavailable right now (${saltRes.status})`);
+  const { salt } = (await saltRes.json()) as { salt: string };
+  const codeAuthHash = await deriveAuthHash(normalized, hexToBytes(salt));
+
+  const first = await fetch("/api/auth/recovery/grant-redeem", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ email, codeAuthHash }),
+  });
+  if (!first.ok) throw new Error((await first.json().catch(() => ({}))).error || "that code is not valid, or it has expired");
+  const { wrappedDek } = (await first.json()) as { wrappedDek: string };
+  const dek = await unwrapDEKWithKek(base64ToBytes(wrappedDek), await deriveKekFromPassword(normalized, hexToBytes(salt)));
+
+  const fresh = await generateAccountKeypair();
+  const pwSalt = rand(16);
+  const envelope = await wrapDEKForPublicKey(dek, fresh.publicKeyJwk);
+  const second = await fetch("/api/auth/recovery/grant-redeem", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({
+      email,
+      codeAuthHash,
+      newIdentity: {
+        publicKeyJwk: fresh.publicKeyJwk,
+        wrappedPrivateKey: bytesToBase64(await wrapPrivateKey(fresh.privateKey, await deriveKekFromPassword(newPassword, pwSalt))),
+        kdfParams: { salt: bytesToHex(pwSalt), iterations: KDF_ITERATIONS },
+        authHash: await deriveAuthHash(newPassword, pwSalt),
+        envelope: { wrappedDEK: bytesToBase64(envelope.wrappedDEK), ephemeralPublicKeyJwk: envelope.ephemeralPublicKeyJwk },
+      },
+    }),
+  });
+  if (!second.ok) throw new Error((await second.json().catch(() => ({}))).error || `could not finish recovery (${second.status})`);
+  const data = (await second.json()) as { accountId: string; vaultId: string | null; r2Key: string | null; rotationPending: boolean };
+  return { ...data, privateKey: fresh.privateKey, dek };
+}
+
+// DEK rotation. Fetch the re-wrap targets (owner + org + active providers), then commit the
+// new envelope set after the client re-encrypts the vault under a fresh DEK.
+export interface VaultPrincipals {
+  selfAccountId: string;
+  orgAccountId: string;
+  selfPublicKeyJwk: JsonWebKey;
+  orgPublicKeyJwk: JsonWebKey;
+  providers: { accountId: string; publicKeyJwk: JsonWebKey }[];
+  envelopePrincipalIds: string[];
+  orgRecoveryRevokedAt: string | null;
+  vaultId: string;
+}
+export async function getVaultPrincipals(): Promise<VaultPrincipals> {
+  const res = await fetch("/api/vault/principals", { cache: "no-store" });
+  if (!res.ok) throw await failed(res, "principals failed");
+  return res.json();
+}
+/**
+ * Reserve the object the re-key will write to. The server mints the id; the caller PUTs the
+ * blob re-encrypted under the new DEK there, then calls `rotateVault` to make the swap real.
+ */
+export async function stageVaultRotation(vaultId: string): Promise<string> {
+  const res = await fetch("/api/vault/rotate", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ phase: "stage", vaultId }),
+  });
+  if (!res.ok) throw await failed(res, "stage rotation failed");
+  return (await res.json()).newVaultId as string;
+}
+
+export async function rotateVault(args: {
+  vaultId: string;
+  newVaultId: string;
+  envelopes: { principalAccountId: string; wrappedDEK: string; ephemeralPublicKeyJwk: JsonWebKey }[];
+}): Promise<void> {
+  const res = await fetch("/api/vault/rotate", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ phase: "commit", ...args }),
+  });
+  if (!res.ok) throw await failed(res, "rotate failed");
+}
+
+export async function regenerateRecoveryCode(privateKey: CryptoKey): Promise<string> {
+  const recoveryCode = randomRecoveryCode();
+  const salt = rand(16);
+  const kek = await deriveKekFromPassword(recoveryCode, salt);
+  const wrappedPrivateKey = await wrapPrivateKey(privateKey, kek);
+  const recoveryAuthHash = await deriveAuthHash(recoveryCode, salt);
+  const res = await fetch("/api/account/recovery", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ wrappedPrivateKey: bytesToBase64(wrappedPrivateKey), kdfParams: { salt: bytesToHex(salt), iterations: KDF_ITERATIONS }, recoveryAuthHash }),
+  });
+  if (!res.ok) throw await failed(res, "regenerate recovery failed");
+  return recoveryCode;
+}
+
+export async function putRecoveryEnvelope(e: { wrappedDEK: string; ephemeralPublicKeyJwk: unknown }): Promise<{ status: string }> {
+  const res = await fetch("/api/vault/recovery-envelope", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(e),
+  });
+  if (!res.ok) throw await failed(res, "put recovery envelope failed");
+  return res.json();
+}
+
+export async function revokeRecoveryEnvelope(): Promise<{ status: string; revokedAt: string }> {
+  const res = await fetch("/api/vault/recovery-envelope", { method: "DELETE" });
+  if (!res.ok) throw await failed(res, "revoke recovery envelope failed");
+  return res.json();
+}
+
+export interface AccessEventRow {
+  id: string;
+  action: string;
+  actorAccountId: string;
+  vaultId: string | null;
+  consentRef: string | null;
+  meta: unknown;
+  createdAt: string;
+}
+export async function getAccessEvents(): Promise<{ events: AccessEventRow[] }> {
+  const res = await fetch("/api/account/access-events", { cache: "no-store" });
+  if (!res.ok) throw await failed(res, "access events failed");
+  return res.json();
+}

package/auth-support.ts

@@ -0,0 +1,118 @@
+import { wrapDEKForPublicKey } from "./crypto";
+import { bytesToBase64, failed } from "./auth-client";
+
+// Support consented-access. A patient approves a pending support request by wrapping their
+// in-memory DEK to the support agent's public key (time-boxed); support enters via an audited endpoint.
+
+// Patient side — approve a pending support request (linkId + the agent's publicKeyJwk from GET /api/providers).
+export async function approveSupport(linkId: string, dek: CryptoKey, publicKeyJwk: JsonWebKey, ttlHours: number): Promise<void> {
+  const env = await wrapDEKForPublicKey(dek, publicKeyJwk);
+  const res = await fetch("/api/support/approve", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ linkId, wrappedDEK: bytesToBase64(env.wrappedDEK), ephemeralPublicKeyJwk: env.ephemeralPublicKeyJwk, ttlHours }),
+  });
+  if (!res.ok) throw await failed(res, "approve failed");
+}
+
+// Support side.
+export interface SupportPatient {
+  patientAccountId: string;
+  displayName: string;
+  expiresAt: string | null;
+}
+
+export async function requestSupportAccess(patientEmail: string): Promise<void> {
+  const res = await fetch("/api/support/request", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ patientEmail }),
+  });
+  if (!res.ok) throw await failed(res, "request failed");
+}
+
+export async function listSupportPatients(): Promise<SupportPatient[]> {
+  const res = await fetch("/api/support/patients", { cache: "no-store" });
+  if (!res.ok) throw await failed(res, "support patients failed");
+  return ((await res.json()) as { patients: SupportPatient[] }).patients;
+}
+
+// Enter a patient (audited server-side); returns the envelope for client-side DEK unwrap.
+export async function enterSupportPatient(patientAccountId: string): Promise<{
+  patientAccountId: string;
+  displayName: string;
+  email: string | null;
+  vaultId: string;
+  r2Key: string;
+  envelope: { wrappedDEK: string; ephemeralPublicKeyJwk: JsonWebKey };
+}> {
+  const res = await fetch("/api/support/access", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ patientAccountId }),
+  });
+  if (!res.ok) throw await failed(res, "support access failed");
+  return res.json();
+}
+
+// Support→provider roster access. A support agent can request access to a clinician too (same
+// /api/support/request, which classifies by the target's kind). The clinician approves (metadata only,
+// no DEK), then support sees the clinician's roster and can open the patients who separately consented.
+
+export interface SupportProvider {
+  linkId: string;
+  providerAccountId: string;
+  displayName: string;
+  email: string | null;
+  expiresAt: string | null;
+}
+
+export interface SupportRosterPatient {
+  patientAccountId: string;
+  displayName: string;
+  email: string | null;
+  openable: boolean;
+  pending: boolean;
+}
+
+export interface SupportRequest {
+  linkId: string;
+  targetAccountId: string;
+  displayName: string;
+  email: string | null;
+  kind: "patient" | "provider";
+}
+
+// Provider side — approve a pending support roster request (no DEK; a provider owns no vault).
+export async function approveSupportAsProvider(linkId: string, ttlHours: number): Promise<void> {
+  const res = await fetch("/api/providers/approve-support", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ linkId, ttlHours }),
+  });
+  if (!res.ok) throw await failed(res, "approve failed");
+}
+
+export async function listSupportProviders(): Promise<SupportProvider[]> {
+  const res = await fetch("/api/support/providers", { cache: "no-store" });
+  if (!res.ok) throw await failed(res, "support providers failed");
+  return ((await res.json()) as { providers: SupportProvider[] }).providers;
+}
+
+export async function getProviderRoster(providerId: string): Promise<SupportRosterPatient[]> {
+  const res = await fetch(`/api/support/provider-roster?providerId=${encodeURIComponent(providerId)}`, { cache: "no-store" });
+  if (!res.ok) throw await failed(res, "provider roster failed");
+  return ((await res.json()) as { roster: SupportRosterPatient[] }).roster;
+}
+
+export async function listSupportRequests(): Promise<SupportRequest[]> {
+  const res = await fetch("/api/support/requests", { cache: "no-store" });
+  if (!res.ok) throw await failed(res, "support requests failed");
+  return ((await res.json()) as { requests: SupportRequest[] }).requests;
+}
+
+// Cancel a pending request the support agent made (support is the provider side of the link).
+export async function cancelSupportRequest(linkId: string): Promise<void> {
+  const res = await fetch(`/api/providers/${encodeURIComponent(linkId)}`, { method: "DELETE" });
+  if (!res.ok) throw await failed(res, "cancel failed");
+}

package/base64.ts

@@ -0,0 +1,15 @@
+// Byte <-> base64. Pure, no reactive state — used throughout this package's client layer wherever
+// key material or an envelope needs to cross a JSON boundary.
+
+export function b64ToBytes(b64: string): Uint8Array {
+  const bin = atob(b64);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+export function bytesToB64(bytes: Uint8Array): string {
+  let bin = "";
+  for (const b of bytes) bin += String.fromCharCode(b);
+  return btoa(bin);
+}

package/break-glass.ts

@@ -1,9 +1,8 @@
-// The time-boxed "support agent gets temporary access, then it lapses or is pulled" pattern. It
-// exists because this package's first adopter had several routes that each hardcoded their own TTL
-// clamp, consent-string prefix, and audit shape — one for granting with an envelope, one for
-// granting metadata-only access, one for checking/expiring, one for revoking. Centralizing the
-// pattern here means every one of those routes shares the same TTL clamp, consent format, and audit
-// trail instead of drifting independently.
+// The time-boxed "support agent gets temporary access, then it lapses or is pulled" pattern, factored
+// out of routes that would otherwise each hardcode their own TTL clamp, consent-string prefix, and
+// audit shape: a grant-with-envelope route, a grant-metadata-only route, a check/expire route, and a
+// revoke route. Parameterized TTL rather than a fixed default, so an adopter with different
+// access-window needs isn't stuck with ours.
 
 import type { AuditStore, EnvelopeStore, ProviderLink, ProviderLinkStore } from "./stores";
 

package/crypto.ts

@@ -1,8 +1,8 @@
 import { toArrayBuffer as toAB } from "./bytes";
 import { deriveAesKey, deriveBits, IV_LEN, SALT_LEN } from "./kdf";
 
-// HD1 is this app's own envelope and stays here. Only the derivation is shared with the QBO vault's
-// EB1 — see the header of @tinytars/vault/kdf for why the two formats must NOT be merged.
+// HD1 is this package's own envelope and stays here. Only the derivation is shared with a sibling
+// encrypted-blob format elsewhere — see kdf.ts's header for why the two formats must NOT be merged.
 const MAGIC = new Uint8Array([0x48, 0x44, 0x31]); // "HD1"
 const VERSION = 1;
 
@@ -12,18 +12,22 @@ const dec = new TextDecoder();
 
 const deriveKey = (passphrase: string, salt: Uint8Array) => deriveAesKey(subtle, passphrase, salt);
 
+function bytesToBase64Url(bytes: Uint8Array): string {
+  let bin = "";
+  for (const b of bytes) bin += String.fromCharCode(b);
+  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
 // Deterministic, non-reversible bearer derived from the passphrase: base64url(SHA-256).
 //
-// This is a generator for a stable, non-reversible token an adopter can use to gate a script or an
-// allowlisted bearer-token integration off the same passphrase used for the interactive login path,
-// without storing the passphrase itself anywhere. It is not session auth — an interactive route
-// should be protected by a real session cookie/token, not a static bearer derived here. Keep this
-// only for a script-facing bearer allowlist you still rely on; drop it once you don't.
+// A stable, non-reversible token an adopter can hand to a script or an allowlisted bearer-token
+// integration gated off the same passphrase used for the interactive login path, without storing
+// the passphrase itself anywhere. Not session auth — an interactive route should be protected by a
+// real session cookie/token, not a static bearer derived here. Keep this only for a script-facing
+// bearer allowlist you still rely on; drop it once you don't.
 export async function deriveBearerToken(passphrase: string): Promise<string> {
   const digest = new Uint8Array(await subtle.digest("SHA-256", toAB(enc.encode(passphrase))));
-  let bin = "";
-  for (const b of digest) bin += String.fromCharCode(b);
-  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+  return bytesToBase64Url(digest);
 }
 
 export async function encryptVault<T = Record<string, unknown>>(data: T, passphrase: string): Promise<Uint8Array> {
@@ -114,9 +118,7 @@ export async function deriveAuthHash(password: string, salt: Uint8Array): Promis
   domainSalt.set(salt, 0);
   domainSalt.set(suffix, salt.length);
   const bits = await deriveBits(subtle, password, domainSalt);
-  let bin = "";
-  for (const b of bits) bin += String.fromCharCode(b);
-  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+  return bytesToBase64Url(bits);
 }
 
 // Wrap/unwrap the account private key under a KEK: AES-GCM over its PKCS8 bytes. Blob = iv(12)+ct.
@@ -139,18 +141,17 @@ export async function unwrapPrivateKey(blob: Uint8Array, kek: CryptoKey): Promis
   } catch {
     throw new Error("cannot unwrap private key (wrong KEK or corrupt blob)");
   }
-  // Extractable so an authorized holder can RE-WRAP it — needed to add a login method or regenerate a
-  // recovery code, both of which wrap this same key under a new KEK. Same rationale/posture as the
+  // Extractable so an authorized holder can RE-WRAP it — needed to add a login method or regenerate the
+  // recovery code, which wraps this same key under a new KEK. Same rationale/posture as the
   // DEK returned by unwrapDEKWithPrivateKey (also extractable for re-granting). The key stays in-memory
   // only, same trust boundary as the session's DEK.
   return subtle.importKey("pkcs8", pkcs8, EC_PARAMS, true, ["deriveKey", "deriveBits"]);
 }
 
 // Import a raw PKCS8 ECDH private key (extractable, so it can be re-wrapped to add a login method —
-// same trust boundary as unwrapPrivateKey's output). A server-custody login path (e.g. SSO, where
-// the server itself bootstraps the session) moves the plaintext key over the wire instead of a
-// KEK-wrapped blob, so both server (re-wrap under the server KEK) and client (recover the DEK)
-// import it here rather than unwrapping.
+// same trust boundary as unwrapPrivateKey's output). A federated-login path that moves the plaintext key
+// over the wire (server-custody) needs both server (re-wrap under the server KEK) and client (recover
+// the DEK) to import it here instead of unwrapping a KEK-wrapped blob.
 export async function importPrivateKeyPkcs8(pkcs8: Uint8Array): Promise<CryptoKey> {
   return subtle.importKey("pkcs8", toAB(pkcs8), EC_PARAMS, true, ["deriveKey", "deriveBits"]);
 }

package/kdf.ts

@@ -1,23 +1,15 @@
-// The passphrase→key derivation shared by every passphrase-encrypted blob that builds on this
-// package.
+// The passphrase→key derivation shared by every passphrase-encrypted blob this package produces.
 //
-// This derivation is deliberately factored out on its own, separate from any particular envelope
-// format: PBKDF2-SHA256, 200_000 iterations, AES-GCM-256, a 16-byte salt and a 12-byte IV. An
-// adopter building a second, unrelated encrypted-blob format alongside this package's own HD1
-// envelope (`crypto.ts`) should reuse this file rather than reimplementing the derivation —
-// reimplementing it independently is exactly how a later decision to raise the iteration count
-// gets taken in one copy and silently not the other.
+// This module derives a key from a passphrase and salt and stops there — it does not define an
+// envelope format, version byte, or framing. A caller with its own envelope needs (see `crypto.ts`
+// for this package's own HD1 format) keeps its magic bytes, version handling, and framing in its own
+// module. A unified envelope would make one format's blob a syntactically valid input to another
+// format's reader, which is a confusion this separation prevents for free. Sharing only the
+// derivation, never the envelope, is the design, not an oversight to "fix" by merging.
 //
-// WHAT IS DELIBERATELY NOT SHARED: the envelope. HD1 keeps its own magic bytes, its own version
-// handling and its own framing in its own module — a sibling format should do the same in its own.
-// A unified envelope would make a foreign blob a syntactically valid input to this package's vault
-// reader, which is a confusion this separation prevents for free. If you are here to "finish the
-// job" by merging formats — that is the bug this comment exists to stop.
-//
-// RUNTIME-AGNOSTIC BY CONSTRUCTION: this module imports nothing and touches no global. One caller is
-// Node-only (`node:crypto`'s webcrypto), the others run in the browser and in Workers, so the
-// `SubtleCrypto` is passed in rather than reached for. That also makes the parameters testable
-// without a runtime shim.
+// RUNTIME-AGNOSTIC BY CONSTRUCTION: this module imports nothing and touches no global. Callers run
+// in Node, the browser, and Workers alike, so the `SubtleCrypto` instance is passed in rather than
+// reached for globally. That also makes the parameters testable without a runtime shim.
 
 import { toArrayBuffer } from "./bytes";
 
@@ -56,8 +48,8 @@ export async function deriveAesKey(
 }
 
 /**
- * PBKDF2-SHA256 → raw bits, for a derivation whose output is not itself a key — health-dash's
- * server-verifiable auth hash. Separate entry point rather than a flag on `deriveAesKey`, because a
+ * PBKDF2-SHA256 → raw bits, for a derivation whose output is not itself a key — this package's own
+ * server-verifiable auth hash (see `crypto.ts`'s `deriveAuthHash`). Separate entry point rather than a flag on `deriveAesKey`, because a
  * function that sometimes returns exportable bytes and sometimes an unexportable key is exactly the
  * kind of thing a reviewer has to read twice.
  */

package/key-store.ts

@@ -1,10 +1,11 @@
-// Persist the account private key across a browser refresh so a valid session doesn't force
+// Persist the account private key across a browser refresh so a valid session cookie doesn't force
 // re-auth. The key is stored as a NON-EXTRACTABLE CryptoKey (structured-cloned into IndexedDB): it can
 // still unwrap the vault DEK (ECDH deriveKey) on the next load, but its raw bytes can't be read back
 // out, so an XSS payload can't exfiltrate it (it could still USE it while the page is open — inherent
-// to any "stay signed in"). Password/passkey only; Google re-bootstraps from server-custody material.
+// to any "stay signed in"). Password/passkey only; a federated-login method re-bootstraps from
+// server-custody material instead.
 
-const DB_NAME = "hd-session";
+const DB_NAME = "security-session";
 const STORE = "keys";
 const KEY_ID = "account-private-key";
 const EC_PARAMS = { name: "ECDH", namedCurve: "P-256" } as const;