@tinytars/vault 0.1.4

package/break-glass.ts

@@ -0,0 +1,158 @@
+// The time-boxed "support agent gets temporary access, then it lapses or is pulled" pattern, used by
+// three routes that used to each hardcode their own TTL clamp, consent-string prefix, and audit shape:
+// functions/api/support/approve.ts (grant, with envelope), functions/api/providers/approve-support.ts
+// (grant, metadata-only), functions/api/support/access.ts (check/expire), and
+// functions/api/providers/[link].ts (revoke). See docs/cross-app/10-open-source-info-security.md step 5.
+
+import type { AuditStore, EnvelopeStore, ProviderLink, ProviderLinkStore } from "./stores";
+
+export interface BreakGlassPolicy {
+  defaultTtlHours: number;
+  maxTtlHours: number;
+}
+
+function clampTtlHours(requested: number | undefined, policy: BreakGlassPolicy): number {
+  return typeof requested === "number" && requested > 0 ? Math.min(requested, policy.maxTtlHours) : policy.defaultTtlHours;
+}
+
+export type BreakGlassGrantResult = { ok: true; expiresAt: string } | { ok: false; error: "no_pending_link" };
+
+export interface BreakGlassGrantStores {
+  links: Pick<ProviderLinkStore, "get" | "grantSupport">;
+  audit: Pick<AuditStore, "insertAccessEvent">;
+  /** Only required when a grant call passes `envelope`. */
+  envelopes?: Pick<EnvelopeStore, "putEnvelope">;
+}
+
+/**
+ * Approves a pending support-role link: validates it's the approver's own pending request, clamps the
+ * requested TTL, stamps a consent ref, optionally writes an envelope (patient approvals only — a
+ * provider approving a roster request owns nothing encrypted), flips the link active, and audits.
+ */
+export async function grantBreakGlass(
+  stores: BreakGlassGrantStores,
+  opts: {
+    linkId: string;
+    approverAccountId: string;
+    requestedTtlHours: number | undefined;
+    policy: BreakGlassPolicy;
+    consentPrefix: string;
+    auditAction: string;
+    envelope?: { vaultId: string; wrappedDek: Uint8Array; ephemeralPublicKeyJwk: unknown };
+    buildAuditMeta: (expiresAt: string, link: ProviderLink) => unknown;
+  }
+): Promise<BreakGlassGrantResult> {
+  const link = await stores.links.get(opts.linkId);
+  if (!link || link.patientAccountId !== opts.approverAccountId || link.role !== "support" || link.status !== "invited") {
+    return { ok: false, error: "no_pending_link" };
+  }
+
+  const ttlHours = clampTtlHours(opts.requestedTtlHours, opts.policy);
+  const expiresAt = new Date(Date.now() + ttlHours * 3600 * 1000).toISOString();
+  const consentRef = `${opts.consentPrefix}:${new Date().toISOString()}`;
+
+  if (opts.envelope) {
+    if (!stores.envelopes) throw new Error("grantBreakGlass: envelope requested but no envelope store supplied");
+    await stores.envelopes.putEnvelope({
+      vaultId: opts.envelope.vaultId,
+      principalAccountId: link.providerAccountId,
+      wrappedDek: opts.envelope.wrappedDek,
+      ephemeralPublicKeyJwk: opts.envelope.ephemeralPublicKeyJwk,
+      createdBy: opts.approverAccountId,
+    });
+  }
+  await stores.links.grantSupport(link.id, { expiresAt, consentRef });
+  await stores.audit.insertAccessEvent({
+    actorAccountId: opts.approverAccountId,
+    subjectAccountId: opts.approverAccountId,
+    vaultId: opts.envelope?.vaultId ?? null,
+    action: opts.auditAction,
+    consentRef,
+    meta: opts.buildAuditMeta(expiresAt, link),
+  });
+
+  return { ok: true, expiresAt };
+}
+
+export type BreakGlassCheckResult = { ok: true } | { ok: false; error: "expired" };
+
+export interface BreakGlassCheckStores {
+  links: Pick<ProviderLinkStore, "updateStatus">;
+  audit: Pick<AuditStore, "insertAccessEvent">;
+}
+
+/**
+ * Checks whether an active support-role link has passed its TTL. Past expiry, self-revokes the link
+ * and audits `expiredAuditAction`; `onExpire` is the caller's chance to clean up whatever the grant
+ * attached (an envelope, for the vault-access case — nothing, for a metadata-only grant).
+ */
+export async function checkBreakGlass(
+  stores: BreakGlassCheckStores,
+  opts: {
+    link: ProviderLink;
+    actorAccountId: string;
+    subjectAccountId: string;
+    vaultId: string | null;
+    now?: number;
+    expiredAuditAction: string;
+    onExpire?: () => Promise<void>;
+  }
+): Promise<BreakGlassCheckResult> {
+  const now = opts.now ?? Date.now();
+  if (!opts.link.expiresAt || new Date(opts.link.expiresAt).getTime() >= now) {
+    return { ok: true };
+  }
+
+  if (opts.onExpire) await opts.onExpire();
+  await stores.links.updateStatus(opts.link.id, "revoked");
+  await stores.audit.insertAccessEvent({
+    actorAccountId: opts.actorAccountId,
+    subjectAccountId: opts.subjectAccountId,
+    vaultId: opts.vaultId,
+    action: opts.expiredAuditAction,
+    consentRef: opts.link.consentRef,
+  });
+
+  return { ok: false, error: "expired" };
+}
+
+export interface BreakGlassRevokeStores {
+  links: Pick<ProviderLinkStore, "updateStatus">;
+  audit: Pick<AuditStore, "insertAccessEvent">;
+  /** Only required when the link being revoked has a vault (i.e. is not metadata-only). */
+  envelopes?: Pick<EnvelopeStore, "deleteEnvelope">;
+}
+
+/**
+ * Ends a link early — either side may call this (the patient revoking, or the provider dropping it).
+ * Deletes the provider's envelope (if any) so no new read can unwrap the DEK, and marks the link
+ * revoked. Idempotent: a second call re-deletes (no-op) and re-marks revoked (no-op); `auditAction` is
+ * omitted for link kinds that don't carry a disclosure-audit obligation (clinician links).
+ */
+export async function revokeBreakGlass(
+  stores: BreakGlassRevokeStores,
+  opts: {
+    linkId: string;
+    actorAccountId: string;
+    subjectAccountId: string;
+    providerAccountId: string;
+    vaultId: string | null;
+    auditAction?: string;
+    auditMeta?: unknown;
+  }
+): Promise<void> {
+  if (opts.vaultId) {
+    if (!stores.envelopes) throw new Error("revokeBreakGlass: vaultId given but no envelope store supplied");
+    await stores.envelopes.deleteEnvelope(opts.vaultId, opts.providerAccountId);
+  }
+  await stores.links.updateStatus(opts.linkId, "revoked");
+  if (opts.auditAction) {
+    await stores.audit.insertAccessEvent({
+      actorAccountId: opts.actorAccountId,
+      subjectAccountId: opts.subjectAccountId,
+      vaultId: opts.vaultId,
+      action: opts.auditAction,
+      meta: opts.auditMeta,
+    });
+  }
+}

package/bytes.ts

@@ -0,0 +1,18 @@
+/**
+ * The one rule for handing a `Uint8Array` to WebCrypto.
+ *
+ * `subtle.*` takes a `BufferSource`, and a `Uint8Array` is only interchangeable with its underlying
+ * `ArrayBuffer` when it spans the whole thing. A view produced by `slice()` on a larger buffer, or by
+ * `subarray()`, carries a non-zero `byteOffset` — passing `view.buffer` there silently encrypts or
+ * hashes the WRONG BYTES rather than failing. Every call site that used to write
+ * `as unknown as ArrayBuffer` was one refactor away from that.
+ *
+ * The whole-buffer case returns the live buffer rather than a copy: the result is consumed
+ * synchronously by the `subtle` call it is written for, so there is no window in which aliasing is
+ * observable, and the copy would be on every vault read.
+ */
+export function toArrayBuffer(view: Uint8Array): ArrayBuffer {
+  return view.byteOffset === 0 && view.byteLength === view.buffer.byteLength
+    ? (view.buffer as ArrayBuffer)
+    : (view.slice().buffer as ArrayBuffer);
+}

package/crypto.ts

@@ -0,0 +1,276 @@
+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.
+const MAGIC = new Uint8Array([0x48, 0x44, 0x31]); // "HD1"
+const VERSION = 1;
+
+const subtle = (globalThis.crypto as Crypto).subtle;
+const enc = new TextEncoder();
+const dec = new TextDecoder();
+
+const deriveKey = (passphrase: string, salt: Uint8Array) => deriveAesKey(subtle, passphrase, salt);
+
+// Deterministic, non-reversible bearer derived from the passphrase: base64url(SHA-256).
+//
+// No longer called from the browser: it gated /api/chat and /api/raw via CHAT_TOKEN/RAW_TOKEN
+// until those routes moved to requireSession, and both secrets were deleted 2026-08-26. It is
+// still the generator for the one bearer allowlist that survives — scripts/chat-allowlist.ts
+// prints the VAULT_TOKEN value, which vault/[id].ts:73,155 checks and scripts/vault-sync.ts sends.
+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(/=+$/, "");
+}
+
+export async function encryptVault<T = Record<string, unknown>>(data: T, passphrase: string): Promise<Uint8Array> {
+  const salt = globalThis.crypto.getRandomValues(new Uint8Array(SALT_LEN));
+  const iv = globalThis.crypto.getRandomValues(new Uint8Array(IV_LEN));
+  const key = await deriveKey(passphrase, salt);
+  const plaintext = enc.encode(JSON.stringify(data));
+  const ciphertext = new Uint8Array(
+    await subtle.encrypt({ name: "AES-GCM", iv: toAB(iv) }, key, toAB(plaintext)),
+  );
+  const out = new Uint8Array(MAGIC.length + 1 + SALT_LEN + IV_LEN + ciphertext.length);
+  let o = 0;
+  out.set(MAGIC, o); o += MAGIC.length;
+  out[o++] = VERSION;
+  out.set(salt, o); o += SALT_LEN;
+  out.set(iv, o); o += IV_LEN;
+  out.set(ciphertext, o);
+  return out;
+}
+
+export async function decryptVault<T = Record<string, unknown>>(blob: Uint8Array, passphrase: string): Promise<T> {
+  if (blob.length < MAGIC.length + 1 + SALT_LEN + IV_LEN) {
+    throw new Error("blob too short");
+  }
+  for (let i = 0; i < MAGIC.length; i++) {
+    if (blob[i] !== MAGIC[i]) throw new Error("not an HD1 blob");
+  }
+  let o = MAGIC.length;
+  const version = blob[o++];
+  if (version === VERSION_V2) throw new Error("v2 envelope blob: open it with decryptVaultV2 and a DEK");
+  if (version !== VERSION) throw new Error(`unsupported version ${version}`);
+  const salt = blob.slice(o, o + SALT_LEN); o += SALT_LEN;
+  const iv = blob.slice(o, o + IV_LEN); o += IV_LEN;
+  const ciphertext = blob.slice(o);
+  const key = await deriveKey(passphrase, salt);
+  let plaintext: ArrayBuffer;
+  try {
+    plaintext = await subtle.decrypt({ name: "AES-GCM", iv: toAB(iv) }, key, toAB(ciphertext));
+  } catch {
+    throw new Error("wrong passphrase or corrupt blob");
+  }
+  return JSON.parse(dec.decode(plaintext)) as T;
+}
+
+// ── W44 envelope encryption (v2) ─────────────────────────────────────────────
+// v1 above (passphrase → PBKDF2 → AES key → blob) is untouched. v2 splits the key:
+// a random per-vault DEK encrypts the blob, and the DEK is wrapped per principal
+// (owner, provider, support) to their ECDH public key. The passphrase path is gone;
+// a v2 blob is opened only with its DEK. This is what makes "grant access" a
+// re-wrap of the DEK rather than a shared secret.
+
+const VERSION_V2 = 2;
+const KEYID_LEN = 16; // opaque per-vault key id, reserved for future re-key tracking
+const EC_PARAMS = { name: "ECDH", namedCurve: "P-256" } as const;
+
+export interface AccountKeypair {
+  publicKeyJwk: JsonWebKey;
+  privateKey: CryptoKey; // extractable ECDH private — wrap it immediately, then drop the handle
+}
+
+export interface DEKEnvelope {
+  wrappedDEK: Uint8Array; // iv(12) + AES-GCM(sharedKey, raw DEK)
+  ephemeralPublicKeyJwk: JsonWebKey;
+}
+
+export async function generateAccountKeypair(): Promise<AccountKeypair> {
+  const pair = await subtle.generateKey(EC_PARAMS, true, ["deriveKey", "deriveBits"]);
+  const publicKeyJwk = await subtle.exportKey("jwk", pair.publicKey);
+  return { publicKeyJwk, privateKey: pair.privateKey };
+}
+
+// A KEK wraps the account's private key. Password → PBKDF2 (same params as v1);
+// passkey → the WebAuthn PRF secret imported directly as an AES-GCM key.
+export async function deriveKekFromPassword(password: string, salt: Uint8Array): Promise<CryptoKey> {
+  return deriveKey(password, salt);
+}
+
+export async function kekFromPrfSecret(prfBytes: Uint8Array): Promise<CryptoKey> {
+  return subtle.importKey("raw", toAB(prfBytes), "AES-GCM", false, ["encrypt", "decrypt"]);
+}
+
+// Server-verifiable password auth signal, in a DISTINCT KDF domain from the KEK (salt||"|auth"),
+// so it can be sent to the server without leaking the key-wrapping secret. The server stores
+// SHA-256(authHash) and compares — it never sees the password or the KEK. base64url of 256 bits.
+export async function deriveAuthHash(password: string, salt: Uint8Array): Promise<string> {
+  const suffix = enc.encode("|auth");
+  const domainSalt = new Uint8Array(salt.length + suffix.length);
+  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(/=+$/, "");
+}
+
+// Wrap/unwrap the account private key under a KEK: AES-GCM over its PKCS8 bytes. Blob = iv(12)+ct.
+export async function wrapPrivateKey(privateKey: CryptoKey, kek: CryptoKey): Promise<Uint8Array> {
+  const pkcs8 = new Uint8Array(await subtle.exportKey("pkcs8", privateKey));
+  const iv = globalThis.crypto.getRandomValues(new Uint8Array(IV_LEN));
+  const ct = new Uint8Array(await subtle.encrypt({ name: "AES-GCM", iv: toAB(iv) }, kek, toAB(pkcs8)));
+  const out = new Uint8Array(IV_LEN + ct.length);
+  out.set(iv, 0);
+  out.set(ct, IV_LEN);
+  return out;
+}
+
+export async function unwrapPrivateKey(blob: Uint8Array, kek: CryptoKey): Promise<CryptoKey> {
+  const iv = blob.slice(0, IV_LEN);
+  const ct = blob.slice(IV_LEN);
+  let pkcs8: ArrayBuffer;
+  try {
+    pkcs8 = await subtle.decrypt({ name: "AES-GCM", iv: toAB(iv) }, kek, toAB(ct));
+  } 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 the
+  // recovery code (W44 P8/P8b), which wrap 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). W45: the Google path moves the plaintext key
+// over the wire (server-custody), so both server (re-wrap under the server KEK) and client (recover
+// the DEK) 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"]);
+}
+
+export async function generateDEK(): Promise<CryptoKey> {
+  return subtle.generateKey({ name: "AES-GCM", length: 256 }, true, ["encrypt", "decrypt"]);
+}
+
+// ECDH-ES: wrap the DEK to a recipient public key via an ephemeral ECDH → AES-GCM key.
+// (A256GCM over the raw DEK; equivalent to JWE ECDH-ES+A256GCM — simpler and less
+// error-prone here than AES-KW, which the plan named illustratively.)
+export async function wrapDEKForPublicKey(dek: CryptoKey, recipientPublicKeyJwk: JsonWebKey): Promise<DEKEnvelope> {
+  const recipientPub = await subtle.importKey("jwk", recipientPublicKeyJwk, EC_PARAMS, false, []);
+  const eph = await subtle.generateKey(EC_PARAMS, true, ["deriveKey"]);
+  const shared = await subtle.deriveKey(
+    { name: "ECDH", public: recipientPub },
+    eph.privateKey,
+    { name: "AES-GCM", length: 256 },
+    false,
+    ["encrypt"],
+  );
+  const rawDek = new Uint8Array(await subtle.exportKey("raw", dek));
+  const iv = globalThis.crypto.getRandomValues(new Uint8Array(IV_LEN));
+  const ct = new Uint8Array(await subtle.encrypt({ name: "AES-GCM", iv: toAB(iv) }, shared, toAB(rawDek)));
+  const wrappedDEK = new Uint8Array(IV_LEN + ct.length);
+  wrappedDEK.set(iv, 0);
+  wrappedDEK.set(ct, IV_LEN);
+  return { wrappedDEK, ephemeralPublicKeyJwk: await subtle.exportKey("jwk", eph.publicKey) };
+}
+
+export async function unwrapDEKWithPrivateKey(
+  wrappedDEK: Uint8Array,
+  ephemeralPublicKeyJwk: JsonWebKey,
+  privateKey: CryptoKey,
+): Promise<CryptoKey> {
+  const ephPub = await subtle.importKey("jwk", ephemeralPublicKeyJwk, EC_PARAMS, false, []);
+  const shared = await subtle.deriveKey(
+    { name: "ECDH", public: ephPub },
+    privateKey,
+    { name: "AES-GCM", length: 256 },
+    false,
+    ["decrypt"],
+  );
+  const iv = wrappedDEK.slice(0, IV_LEN);
+  const ct = wrappedDEK.slice(IV_LEN);
+  let raw: ArrayBuffer;
+  try {
+    raw = await subtle.decrypt({ name: "AES-GCM", iv: toAB(iv) }, shared, toAB(ct));
+  } catch {
+    throw new Error("cannot unwrap DEK (wrong key or corrupt envelope)");
+  }
+  // extractable so an authorized holder can re-wrap it to grant another principal
+  return subtle.importKey("raw", raw, { name: "AES-GCM", length: 256 }, true, ["encrypt", "decrypt"]);
+}
+
+// W73 — the DEK wrapped under a KEK, for a provider-issued recovery grant.
+//
+// The raw-key twin of wrapPrivateKey/unwrapPrivateKey above: same AES-GCM, same iv‖ct blob shape, same
+// reasoning. It exists because a recovery grant hands the DEK to a one-time code rather than to a
+// principal's public key — the ECDH envelope path needs a keypair, and a code read down a phone line
+// is not one.
+//
+// The DEK is `extractable` by design (see unwrapDEKWithPrivateKey below), which is what makes
+// exportKey("raw") here possible at all.
+export async function wrapDEKWithKek(dek: CryptoKey, kek: CryptoKey): Promise<Uint8Array> {
+  const raw = new Uint8Array(await subtle.exportKey("raw", dek));
+  const iv = globalThis.crypto.getRandomValues(new Uint8Array(IV_LEN));
+  const ct = new Uint8Array(await subtle.encrypt({ name: "AES-GCM", iv: toAB(iv) }, kek, toAB(raw)));
+  const out = new Uint8Array(IV_LEN + ct.length);
+  out.set(iv, 0);
+  out.set(ct, IV_LEN);
+  return out;
+}
+
+export async function unwrapDEKWithKek(blob: Uint8Array, kek: CryptoKey): Promise<CryptoKey> {
+  const iv = blob.slice(0, IV_LEN);
+  const ct = blob.slice(IV_LEN);
+  let raw: ArrayBuffer;
+  try {
+    raw = await subtle.decrypt({ name: "AES-GCM", iv: toAB(iv) }, kek, toAB(ct));
+  } catch {
+    // AES-GCM's tag is what tells a holder of this blob that a guessed code was right, which is why the
+    // blob is deleted the moment its grant is consumed — see migrations/0009.
+    throw new Error("cannot unwrap DEK (wrong recovery code or corrupt grant)");
+  }
+  // Extractable for the same reason as every other DEK here: the recovering client immediately re-wraps
+  // it to the new account key it just generated.
+  return subtle.importKey("raw", raw, { name: "AES-GCM", length: 256 }, true, ["encrypt", "decrypt"]);
+}
+
+// HD1 v2 blob: magic(3) + version=2(1) + vaultKeyId(16) + iv(12) + AES-GCM(DEK, JSON).
+// Header = 32 B, equal to v1, so the Functions' MIN_BYTES=32 + magic checks stay valid.
+export async function encryptVaultV2<T = Record<string, unknown>>(data: T, dek: CryptoKey): Promise<Uint8Array> {
+  const vaultKeyId = globalThis.crypto.getRandomValues(new Uint8Array(KEYID_LEN));
+  const iv = globalThis.crypto.getRandomValues(new Uint8Array(IV_LEN));
+  const plaintext = enc.encode(JSON.stringify(data));
+  const ciphertext = new Uint8Array(await subtle.encrypt({ name: "AES-GCM", iv: toAB(iv) }, dek, toAB(plaintext)));
+  const out = new Uint8Array(MAGIC.length + 1 + KEYID_LEN + IV_LEN + ciphertext.length);
+  let o = 0;
+  out.set(MAGIC, o); o += MAGIC.length;
+  out[o++] = VERSION_V2;
+  out.set(vaultKeyId, o); o += KEYID_LEN;
+  out.set(iv, o); o += IV_LEN;
+  out.set(ciphertext, o);
+  return out;
+}
+
+export async function decryptVaultV2<T = Record<string, unknown>>(blob: Uint8Array, dek: CryptoKey): Promise<T> {
+  const header = MAGIC.length + 1 + KEYID_LEN + IV_LEN;
+  if (blob.length < header) throw new Error("blob too short");
+  for (let i = 0; i < MAGIC.length; i++) if (blob[i] !== MAGIC[i]) throw new Error("not an HD1 blob");
+  let o = MAGIC.length;
+  const version = blob[o++];
+  if (version !== VERSION_V2) throw new Error(`expected HD1 v2, got version ${version}`);
+  o += KEYID_LEN; // vaultKeyId — reserved/opaque
+  const iv = blob.slice(o, o + IV_LEN); o += IV_LEN;
+  const ciphertext = blob.slice(o);
+  let plaintext: ArrayBuffer;
+  try {
+    plaintext = await subtle.decrypt({ name: "AES-GCM", iv: toAB(iv) }, dek, toAB(ciphertext));
+  } catch {
+    throw new Error("wrong DEK or corrupt blob");
+  }
+  return JSON.parse(dec.decode(plaintext)) as T;
+}

package/env.d.ts

@@ -0,0 +1,9 @@
+// vault-sink.ts's dev/prod switch reads import.meta.env.DEV, a Vite convention this package's
+// consumers (bundler-based, per README.md) provide at build time. Declared locally rather than
+// depending on the `vite` package just for its ambient types.
+interface ImportMetaEnv {
+  readonly DEV: boolean;
+}
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}

package/envelope-access.ts

@@ -0,0 +1,44 @@
+import type { Envelope, ProviderLink, VaultRow } from "./stores";
+
+// Narrow, structural slices of EnvelopeStore/ProviderLinkStore — only what the policy below reads.
+// Any conforming store satisfies these without change; an adopter with no "org recovery account"
+// concept can call this with orgAccountId set to a value nothing will ever match, or skip it.
+export interface EnvelopeAccessSource {
+  getEnvelopeRow(vaultId: string, principalAccountId: string): Promise<Envelope | null>;
+  getVault(vaultId: string): Promise<VaultRow | null>;
+}
+export interface ProviderLinkSource {
+  getActive(patientAccountId: string, providerAccountId: string): Promise<ProviderLink | null>;
+}
+
+/**
+ * The envelope a principal may actually use, or null.
+ *
+ * This check has to live here, composed once, rather than duplicated per route — that is exactly
+ * how it was bypassed before: expiry was enforced lazily and only inside individual routes, so a
+ * grantee who never called the one endpoint that self-revokes a lapsed grant could keep reading PHI
+ * indefinitely. The grant's own expiry was real; nothing on the read path consulted it.
+ *
+ * The owner needs no link (they have no provider-link row about themselves), and neither does the
+ * org-recovery principal, whose envelope the owner can revoke outright — recorded on the vault, not
+ * as a link.
+ */
+export async function resolveEnvelopeAccess(
+  envelopes: EnvelopeAccessSource,
+  providers: ProviderLinkSource,
+  vaultId: string,
+  principalAccountId: string,
+  orgAccountId: string
+): Promise<Envelope | null> {
+  const envelope = await envelopes.getEnvelopeRow(vaultId, principalAccountId);
+  if (!envelope) return null;
+
+  const vault = await envelopes.getVault(vaultId);
+  if (!vault) return null;
+  if (vault.ownerAccountId === principalAccountId) return envelope;
+  if (principalAccountId === orgAccountId) return vault.orgRecoveryRevokedAt ? null : envelope;
+
+  const link = await providers.getActive(vault.ownerAccountId, principalAccountId);
+  if (!link) return null;
+  return envelope;
+}

package/kdf.ts

@@ -0,0 +1,73 @@
+// The passphrase→key derivation shared by every passphrase-encrypted blob in this monorepo.
+//
+// W72. Two envelope formats derive their key identically and independently: the QBO token vault
+// (`EB1`, packages/qbo/crypto.ts) and the health-dash v1 vault plus its account KEKs (`HD1`,
+// apps/health-dash-web/src/lib/crypto.ts). Same PBKDF2-SHA256, same 200_000 iterations, same
+// AES-GCM-256, same 16-byte salt and 12-byte IV — written out twice, so a decision to raise the
+// iteration count could be taken in one file and silently not the other. Only the derivation is
+// shared here.
+//
+// WHAT IS DELIBERATELY NOT SHARED: the envelope. `EB1` and `HD1` keep their own magic bytes, their
+// own version handling and their own framing, in their own modules. A unified envelope would make a
+// QBO token blob a syntactically valid input to the vault reader, which is a confusion this
+// separation prevents for free. If you are here to "finish the job" by merging the two files — 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.
+
+import { toArrayBuffer } from "./bytes";
+
+/**
+ * OWASP's floor for PBKDF2-SHA256 at the time this was set. Raising it is a compatibility decision,
+ * not a tuning knob: existing blobs carry no iteration count in their header, so both formats would
+ * have to grow a version byte that records it before this number can move.
+ */
+export const PBKDF2_ITERATIONS = 200_000;
+export const SALT_LEN = 16;
+/** AES-GCM standard nonce length. Not 16 — a non-96-bit IV is re-hashed by GHASH and buys nothing. */
+export const IV_LEN = 12;
+
+const enc = new TextEncoder();
+
+/**
+ * PBKDF2-SHA256 over `passphrase` and `salt` → a non-extractable AES-GCM-256 key.
+ *
+ * Non-extractable is the point: the caller gets something it can encrypt and decrypt with and cannot
+ * export, so a derived key cannot escape the module that derived it.
+ */
+export async function deriveAesKey(
+  subtle: SubtleCrypto,
+  passphrase: string,
+  salt: Uint8Array,
+  usages: KeyUsage[] = ["encrypt", "decrypt"],
+): Promise<CryptoKey> {
+  const baseKey = await subtle.importKey("raw", toArrayBuffer(enc.encode(passphrase)), "PBKDF2", false, ["deriveKey"]);
+  return subtle.deriveKey(
+    { name: "PBKDF2", salt: toArrayBuffer(salt), iterations: PBKDF2_ITERATIONS, hash: "SHA-256" },
+    baseKey,
+    { name: "AES-GCM", length: 256 },
+    false,
+    usages,
+  );
+}
+
+/**
+ * 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
+ * function that sometimes returns exportable bytes and sometimes an unexportable key is exactly the
+ * kind of thing a reviewer has to read twice.
+ */
+export async function deriveBits(
+  subtle: SubtleCrypto,
+  passphrase: string,
+  salt: Uint8Array,
+  length = 256,
+): Promise<Uint8Array> {
+  const baseKey = await subtle.importKey("raw", toArrayBuffer(enc.encode(passphrase)), "PBKDF2", false, ["deriveBits"]);
+  return new Uint8Array(
+    await subtle.deriveBits({ name: "PBKDF2", salt: toArrayBuffer(salt), iterations: PBKDF2_ITERATIONS, hash: "SHA-256" }, baseKey, length),
+  );
+}

package/key-store.ts

@@ -0,0 +1,67 @@
+// W49 — persist the account private key across a browser refresh so a valid hd_session 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.
+
+const DB_NAME = "hd-session";
+const STORE = "keys";
+const KEY_ID = "account-private-key";
+const EC_PARAMS = { name: "ECDH", namedCurve: "P-256" } as const;
+
+function openDb(): Promise<IDBDatabase> {
+  return new Promise((resolve, reject) => {
+    const req = indexedDB.open(DB_NAME, 1);
+    req.onupgradeneeded = () => req.result.createObjectStore(STORE);
+    req.onsuccess = () => resolve(req.result);
+    req.onerror = () => reject(req.error);
+  });
+}
+
+// Store a non-extractable copy of the (currently extractable, in-memory) account private key. Silent
+// no-op if IndexedDB is unavailable (private-browsing / disabled) — persistence is best-effort; the
+// session still works for the current page, the user just re-auths on the next refresh.
+export async function putAccountKey(extractableKey: CryptoKey): Promise<void> {
+  const subtle = (globalThis.crypto as Crypto).subtle;
+  const pkcs8 = await subtle.exportKey("pkcs8", extractableKey);
+  const nonExtractable = await subtle.importKey("pkcs8", pkcs8, EC_PARAMS, false, ["deriveKey", "deriveBits"]);
+  const db = await openDb();
+  try {
+    await new Promise<void>((resolve, reject) => {
+      const tx = db.transaction(STORE, "readwrite");
+      tx.objectStore(STORE).put(nonExtractable, KEY_ID);
+      tx.oncomplete = () => resolve();
+      tx.onerror = () => reject(tx.error);
+    });
+  } finally {
+    db.close();
+  }
+}
+
+export async function getAccountKey(): Promise<CryptoKey | null> {
+  const db = await openDb();
+  try {
+    return await new Promise<CryptoKey | null>((resolve, reject) => {
+      const tx = db.transaction(STORE, "readonly");
+      const req = tx.objectStore(STORE).get(KEY_ID);
+      req.onsuccess = () => resolve((req.result as CryptoKey | undefined) ?? null);
+      req.onerror = () => reject(req.error);
+    });
+  } finally {
+    db.close();
+  }
+}
+
+export async function clearAccountKey(): Promise<void> {
+  const db = await openDb();
+  try {
+    await new Promise<void>((resolve, reject) => {
+      const tx = db.transaction(STORE, "readwrite");
+      tx.objectStore(STORE).delete(KEY_ID);
+      tx.oncomplete = () => resolve();
+      tx.onerror = () => reject(tx.error);
+    });
+  } finally {
+    db.close();
+  }
+}