@tinytars/vault 0.1.15 → 0.1.17

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.15",
+  "version": "0.1.17",
   "description": "Runtime-agnostic key derivation, authenticated envelope encryption, and storage-agnostic access-control contracts for per-user encrypted data.",
   "license": "MIT",
   "type": "module",
@@ -35,6 +35,13 @@
     "./envelope-access": "./envelope-access.ts",
     "./break-glass": "./break-glass.ts",
     "./blob-store": "./blob-store.ts",
+    "./auth-client": "./auth-client.ts",
+    "./auth-recovery": "./auth-recovery.ts",
+    "./auth-support": "./auth-support.ts",
+    "./auth-grants": "./auth-grants.ts",
+    "./org-recovery": "./org-recovery.ts",
+    "./vault-session": "./vault-session.ts",
+    "./base64": "./base64.ts",
     "./adapters/d1": "./adapters/d1/index.ts",
     "./adapters/r2": "./adapters/r2.ts",
     "./adapters/memory": "./adapters/memory.ts",
@@ -45,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,10 +1,8 @@
 // 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";

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 {
+  patientAccountId: 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 patient'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 patient 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 a patient'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);