@tinytars/vault 0.1.16 → 0.1.18

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;

package/org-recovery.ts

@@ -0,0 +1,19 @@
+import type { VaultSession } from "./vault-session";
+import { wrapDEKForPublicKey } from "./crypto";
+import { bytesToB64 } from "./base64";
+import { getVaultPrincipals, putRecoveryEnvelope } from "./auth-recovery";
+
+// Backfill the org-recovery envelope for accounts that predate it (or missed it at signup).
+// Best-effort: it must never block or fail an unlock.
+export async function ensureOrgRecoveryEnvelope(session: VaultSession): Promise<void> {
+  if (!session.dek) return;
+  try {
+    const principals = await getVaultPrincipals();
+    if (principals.orgRecoveryRevokedAt !== null) return;
+    if (principals.envelopePrincipalIds.includes(principals.orgAccountId)) return;
+    const e = await wrapDEKForPublicKey(session.dek, principals.orgPublicKeyJwk);
+    await putRecoveryEnvelope({ wrappedDEK: bytesToB64(e.wrappedDEK), ephemeralPublicKeyJwk: e.ephemeralPublicKeyJwk });
+  } catch {
+    /* best-effort — never block or fail an unlock */
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tinytars/vault",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "description": "Runtime-agnostic key derivation, authenticated envelope encryption, and storage-agnostic access-control contracts for per-user encrypted data.",
   "license": "MIT",
   "type": "module",
@@ -52,8 +52,11 @@
     "test": "vitest run",
     "typecheck": "tsc --noEmit"
   },
+  "dependencies": {
+    "@simplewebauthn/browser": "^13.3.0"
+  },
   "devDependencies": {
-    "vitest": "^4.1.8",
-    "typescript": "~6.0.2"
+    "typescript": "~6.0.2",
+    "vitest": "^4.1.8"
   }
 }

package/stores.ts

@@ -1,14 +1,12 @@
 // Storage-agnostic contracts for the identity/vault/access-control data this package's crypto
 // operates over. No Cloudflare or D1 dependency here by design (see README.md) — an adopter wires
-// these to whatever database they run; `adapters/d1/` in this package is one implementation of
-// these contracts, not the definition of them.
-//
-// An adopter's own route handlers should re-export the types below rather than redeclaring them,
-// so there is exactly one definition of each shape.
+// these to whatever database they run. `adapters/d1/` in this package is one implementation of
+// these contracts, not the definition of them; an adopter's own server code should import the
+// types below rather than redeclaring them, so there is exactly one definition of each shape.
 
 export type LifecycleStage = "waitlist" | "lead" | "active" | "paying" | "churned";
 export type AuthMethod = "passkey" | "google" | "password" | "recovery";
-export type ProviderKind = "clinician" | "support";
+export type ProviderKind = "primary" | "support";
 export type LinkStatus = "invited" | "active" | "revoked";
 export type UnitSystem = "metric" | "imperial";
 
@@ -76,18 +74,18 @@ export interface EnvelopeInput {
 
 export interface ProviderLink {
   id: string;
-  patientAccountId: string;
+  ownerAccountId: string;
   providerAccountId: string;
   role: ProviderKind;
   status: LinkStatus;
   consentRef: string | null;
   grantedBy: string;
   grantedAt: string;
-  /** Set on time-boxed support grants; null for clinician links. */
+  /** Set on time-boxed support grants; null for primary links. */
   expiresAt: string | null;
 }
 
-/** A PHI-access audit-log entry — who touched whose vault, and why. */
+/** A consent-scoped access audit-log entry — who touched whose vault, and why. */
 export interface AccessEvent {
   id: string;
   actorAccountId: string;
@@ -161,7 +159,7 @@ export interface EnvelopeStore {
 
 export interface ProviderLinkStore {
   create(l: {
-    patientAccountId: string;
+    ownerAccountId: string;
     providerAccountId: string;
     role: ProviderKind;
     status?: LinkStatus;
@@ -173,15 +171,16 @@ export interface ProviderLinkStore {
   updateStatus(id: string, status: LinkStatus): Promise<void>;
   grantSupport(id: string, opts: { expiresAt: string | null; consentRef?: string | null }): Promise<void>;
   get(id: string): Promise<ProviderLink | null>;
-  listForPatient(patientAccountId: string): Promise<ProviderLink[]>;
+  listForOwner(ownerAccountId: string): Promise<ProviderLink[]>;
   listForProvider(providerAccountId: string): Promise<ProviderLink[]>;
-  /** The active, unexpired link between this patient and provider, or null. */
-  getActive(patientAccountId: string, providerAccountId: string): Promise<ProviderLink | null>;
+  /** The active, unexpired link between this owner and provider, or null. */
+  getActive(ownerAccountId: string, providerAccountId: string): Promise<ProviderLink | null>;
 }
 
 /**
- * The PHI-access half of an adopter's audit trail only. Lifecycle/CRM events and raw-object
- * ownership bookkeeping are app-specific concerns that don't belong in a portable security package.
+ * The consent-scoped access-event half of an adopter's audit trail only. Lifecycle/CRM events and
+ * raw-object ownership bookkeeping are app-specific concerns that don't belong in a portable
+ * security package.
  */
 export interface AuditStore {
   insertAccessEvent(e: { actorAccountId: string; subjectAccountId: string; vaultId?: string | null; action: string; consentRef?: string | null; meta?: unknown; id?: string }): Promise<AccessEvent>;

package/vault-session.ts

@@ -0,0 +1,59 @@
+import { decryptVaultV2 } from "./crypto";
+
+/**
+ * A vault this session may open on someone else's behalf, and the envelope that opens it. The shape
+ * the provider roster and the support console both hand to the host — one drill-in, not two that
+ * agree by coincidence.
+ */
+export interface VaultEntry {
+  ownerAccountId: string;
+  displayName: string;
+  email: string | null;
+  r2Key: string;
+  envelope: { wrappedDEK: string; ephemeralPublicKeyJwk: JsonWebKey };
+}
+
+export interface VaultSession {
+  /** The current vault's data key, or null when no vault is open. */
+  readonly dek: CryptoKey | null;
+  /** The current vault's R2 id (slug of its r2_key), or null. */
+  readonly r2Id: string | null;
+  /**
+   * The signed-in owner's account private key, retained for the session so Account settings can
+   * re-wrap it when adding a login method. Null in a provider or support session.
+   */
+  readonly ownerKey: CryptoKey | null;
+  /** A provider account's private key, which unwraps each owner's envelope. Null for an owner. */
+  readonly providerKey: CryptoKey | null;
+  /** True only when a vault is genuinely open — derived, never tracked separately. */
+  readonly isOpen: boolean;
+
+  /** Opens a vault: the id and the key that decrypts it, together or not at all. */
+  open(r2Id: string, dek: CryptoKey): void;
+  /** Retains the owner's account key for this session. */
+  setOwnerKey(key: CryptoKey | null): void;
+  /** Retains a provider's account key for this session. */
+  setProviderKey(key: CryptoKey | null): void;
+  /**
+   * Closes the open vault. Clears the data key and the id together.
+   *
+   * Does NOT clear the provider key: a provider who leaves one owner's vault is still signed in and
+   * still needs their own key to open the next. That asymmetry was already the behaviour of
+   * `backToRoster()`; stating it here is what stops it being re-derived incorrectly later.
+   */
+  close(): void;
+  /** Ends the whole session — every key, including the provider's. */
+  signOut(): void;
+}
+
+/**
+ * Decrypts a vault blob and opens the session on it in one step, shared by every path that unlocks
+ * a vault — the signed-in owner's own, and a provider's drill-in to an owner's. `fetchBlob` stays a
+ * caller-supplied thunk because fetching it (the R2 route, the ETag it must remember for later saves)
+ * is app-local, not frame-generic.
+ */
+export async function openVault<V>(session: VaultSession, id: string, dek: CryptoKey, fetchBlob: (id: string) => Promise<Uint8Array>): Promise<V> {
+  const vault = await decryptVaultV2<V>(await fetchBlob(id), dek);
+  session.open(id, dek);
+  return vault;
+}

package/vault-sink.ts

@@ -10,13 +10,12 @@ export interface VaultSink {
 /**
  * The version of each vault blob this browser context last saw.
  *
- * Deliberately held HERE rather than threaded through callers. A real adopter typically has several
- * independent call sites that all persist through `saveVaultV2` — a queued-edit path plus things
- * like key rotation, background regeneration, imports, raw uploads and onboarding — and usually only
- * one of them goes through a save queue. Since the precondition is REQUIRED on the browser path, a
- * call site that forgot to pass an etag would not degrade — it would 428, i.e. an owner unable to
- * save their own record. Keeping the token where the
- * request is built makes every path correct by construction instead of by remembering.
+ * Deliberately held HERE rather than threaded through callers. `saveVaultV2` can have several call
+ * sites in an adopting app (a queued edit path plus one-off writes — key rotation, a background
+ * regen, an import, a raw upload), and not all of them necessarily go through the same queue. Since
+ * the precondition is REQUIRED on the browser path, a call site that forgot to pass an etag would not
+ * degrade silently — it would 428, i.e. a user unable to save their own data. Keeping the token where
+ * the request is built makes every path correct by construction instead of by remembering.
  *
  * One entry per vault id, which is exactly the domain: a browser context has one current view of a
  * given blob.
@@ -49,10 +48,10 @@ export class VaultConflictError extends Error {
 /**
  * One hook, so every save path reports a conflict — not just the queued one.
  *
- * Most real `saveVaultV2` call sites are direct `await`s outside any save queue (key rotation,
- * background regeneration, import, raw upload, onboarding). Wiring the conflict state through each
- * would be one chance to miss it per call site, and a missed one is an unhandled rejection on a
- * record someone owns. Every save funnels through this sink, so this is the one place that sees them all.
+ * Most of `saveVaultV2`'s call sites in a typical adopting app are direct `await`s outside any save
+ * queue (key rotation, a background regen, an import, a raw upload). Wiring the conflict state
+ * through each would be one chance per site to miss it, and a missed one is an unhandled rejection on
+ * a user's data. Every save funnels through this sink, so this is the one place that sees them all.
  * The error still throws afterwards, so existing per-path error handling is unchanged.
  */
 let onConflict: ((e: VaultConflictError) => void) | null = null;
@@ -60,9 +59,9 @@ export function setVaultConflictHandler(fn: ((e: VaultConflictError) => void) |
   onConflict = fn;
 }
 
-// Dev-only sink: POSTs the blob to a local dev-server middleware, which writes it to disk.
-// Absent from the deployed build — there is no such endpoint in production. The R2 sink below is
-// the second implementation of this interface, for a real remote/mobile save.
+// Dev-only sink: POSTs the blob to a local dev-server middleware that writes it to disk. Absent
+// from the deployed build — there is no such endpoint in production. r2Sink below is the second
+// implementation of this interface, for remote/mobile save.
 export const localSink: VaultSink = {
   async put(id, blob) {
     const res = await fetch(`/__save-vault?id=${encodeURIComponent(id)}`, {
@@ -76,21 +75,20 @@ export const localSink: VaultSink = {
   },
 };
 
-// Remote sink: PUTs the encrypted blob to an R2-backed Pages Function.
-// `/api/vault/{id}` only exists in the deployed build; the route guard checks the adopter's own
-// session cookie (owner/granted-provider envelope check) — same-origin fetch sends it automatically.
-// The Function stores opaque ciphertext — same as localSink, never plaintext or a key.
+// Remote sink: PUTs the encrypted blob to an R2-backed server route.
+// `/api/vault/{id}` only exists in the deployed build; the route is expected to authenticate the
+// caller via whatever session cookie the adopter's auth layer sets — same-origin fetch sends it
+// automatically. The route stores opaque ciphertext — same as localSink, never plaintext or a key.
 /**
  * One write at a time per vault, so the app never conflicts with ITSELF.
  *
- * `vaultSave` serializes the queued edit path, but six of `saveVaultV2`'s seven call sites bypass it
- * and `await` directly — so a user edit and a leaf-regen persist could be in flight together. Each
- * reads the version token when it builds its request, so the second would send one the first had
- * already superseded, and the guard would correctly report a conflict against a tab that is only
- * racing itself. CI found exactly that: five specs that save and then trigger a regen went red with
- * the conflict panel intercepting pointer events.
+ * A queued edit path is one likely caller, but most adopting apps also have one-off writes that
+ * bypass any queue and `await` directly — so a user edit and a background regen could end up in
+ * flight together. Each reads the version token when it builds its request, so the second would send
+ * one the first had already superseded, and the guard would correctly report a conflict against a
+ * caller that is only racing itself.
  *
- * Serializing HERE rather than in vaultSave is deliberate: this is the only place every write passes
+ * Serializing HERE rather than upstream is deliberate: this is the only place every write passes
  * through, and the version token lives here too — the token must be read after the previous write has
  * settled, which is precisely what a chain guarantees.
  */
@@ -139,8 +137,8 @@ async function putConditional(id: string, blob: Uint8Array): Promise<void> {
 // wrangler-pages-dev e2e harness) persists to R2 and never references /__save-vault.
 export const vaultSink: VaultSink = import.meta.env.DEV ? localSink : r2Sink;
 
-// Encrypt the vault under its DEK (HD1 v2 envelope) and persist. The DEK is the vault's
-// random data key, unwrapped at login from the caller's key envelope; it stays in memory.
+// Encrypt the vault under its DEK (HD1 v2 envelope) and persist. The DEK is the vault's random
+// data key, unwrapped at login from the caller's key envelope; it stays in memory.
 export async function saveVaultV2<T = Record<string, unknown>>(vault: T, id: string, dek: CryptoKey, sink: VaultSink): Promise<void> {
   const blob = await encryptVaultV2(vault, dek);
   await sink.put(id, blob);