@tinytars/vault 0.1.4

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@tinytars/vault",
+  "version": "0.1.4",
+  "description": "Runtime-agnostic key derivation, authenticated envelope encryption, and storage-agnostic access-control contracts for per-user encrypted data.",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tinytars/vault"
+  },
+  "homepage": "https://github.com/tinytars/vault",
+  "bugs": "https://github.com/tinytars/vault/issues",
+  "keywords": [
+    "encryption",
+    "webcrypto",
+    "envelope-encryption",
+    "access-control",
+    "key-derivation"
+  ],
+  "engines": {
+    "node": ">=19"
+  },
+  "files": [
+    "*.ts",
+    "adapters/**/*.ts",
+    "!tests"
+  ],
+  "exports": {
+    "./crypto": "./crypto.ts",
+    "./kdf": "./kdf.ts",
+    "./bytes": "./bytes.ts",
+    "./key-store": "./key-store.ts",
+    "./vault-sink": "./vault-sink.ts",
+    "./stores": "./stores.ts",
+    "./envelope-access": "./envelope-access.ts",
+    "./break-glass": "./break-glass.ts",
+    "./blob-store": "./blob-store.ts",
+    "./adapters/d1": "./adapters/d1/index.ts",
+    "./adapters/r2": "./adapters/r2.ts",
+    "./adapters/memory": "./adapters/memory.ts",
+    "./adapters/pages-http": "./adapters/pages-http.ts",
+    "./adapters/conformance": "./adapters/conformance.ts"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.8",
+    "typescript": "~6.0.2"
+  }
+}

package/stores.ts

@@ -0,0 +1,190 @@
+// 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; health-dash-web's D1 adapter lives at
+// apps/health-dash-web/functions/_lib/d1-identity-store.ts and is one implementation of these,
+// not the definition of them.
+//
+// health-dash-web's own functions/_lib/identity-*.ts modules re-export 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 LinkStatus = "invited" | "active" | "revoked";
+export type UnitSystem = "metric" | "imperial";
+
+export interface Account {
+  id: string;
+  email: string | null;
+  emailConfirmed: boolean;
+  displayName: string;
+  lifecycleStage: LifecycleStage;
+  providerKind: ProviderKind | null;
+  unitSystem: UnitSystem | null;
+  createdAt: string;
+  /** Set when the account was erased; every personal field is null from that moment. */
+  deletedAt?: string | null;
+  /** When the email address was last changed. Null means never. */
+  emailChangedAt?: string | null;
+}
+
+export interface Identity {
+  id: string;
+  accountId: string;
+  method: AuthMethod;
+  providerSubject: string | null;
+  credentialId: string | null;
+  createdAt: string;
+}
+export interface Credential {
+  accountId: string;
+  method: AuthMethod;
+  wrappedPrivateKey: Uint8Array;
+  kdfParams: unknown;
+  createdAt: string;
+}
+export interface PublicKey {
+  accountId: string;
+  publicKeyJwk: unknown;
+  createdAt: string;
+}
+
+export interface VaultRow {
+  vaultId: string;
+  ownerAccountId: string;
+  r2Key: string;
+  hd1Version: number;
+  /** Set on support-grant expiry; the owner's next login re-keys and clears it. */
+  rotationPending: boolean;
+  /** Set when the owner revokes the org-recovery envelope. */
+  orgRecoveryRevokedAt: string | null;
+  /** The object an in-flight re-key is writing to, before the pointer swap. */
+  rotationStagingR2Key: string | null;
+}
+export interface Envelope {
+  vaultId: string;
+  principalAccountId: string;
+  wrappedDek: Uint8Array;
+  ephemeralPublicKeyJwk: unknown;
+  createdBy: string;
+  createdAt: string;
+}
+export interface EnvelopeInput {
+  principalAccountId: string;
+  wrappedDek: Uint8Array;
+  ephemeralPublicKeyJwk: unknown;
+}
+
+export interface ProviderLink {
+  id: string;
+  patientAccountId: string;
+  providerAccountId: string;
+  role: ProviderKind;
+  status: LinkStatus;
+  consentRef: string | null;
+  grantedBy: string;
+  grantedAt: string;
+  /** Set on time-boxed support grants; null for clinician links. */
+  expiresAt: string | null;
+}
+
+/** A PHI-access audit-log entry — who touched whose vault, and why. */
+export interface AccessEvent {
+  id: string;
+  actorAccountId: string;
+  subjectAccountId: string;
+  vaultId: string | null;
+  action: string;
+  consentRef: string | null;
+  meta: unknown;
+  createdAt: string;
+}
+
+export interface AccountStore {
+  create(a: {
+    id: string;
+    displayName: string;
+    email?: string | null;
+    lifecycleStage?: LifecycleStage;
+    providerKind?: ProviderKind | null;
+  }): Promise<Account>;
+  get(id: string): Promise<Account | null>;
+  getByEmail(email: string): Promise<Account | null>;
+  sessionsValidFrom(accountId: string): Promise<number | null>;
+  revokeSessions(accountId: string): Promise<void>;
+  setEmailConfirmed(id: string, confirmed: boolean): Promise<void>;
+  setLifecycleStage(id: string, stage: LifecycleStage): Promise<void>;
+  updateProfile(id: string, updates: { email?: string | null; displayName?: string; unitSystem?: UnitSystem | null }): Promise<void>;
+  tombstone(accountId: string, at: string): Promise<void>;
+  markEmailChanged(accountId: string, at: string): Promise<void>;
+}
+
+/** Auth-method linkage (`Identity`) plus the key material it points at (`Credential`, `PublicKey`). */
+export interface CredentialStore {
+  addIdentity(i: { accountId: string; method: AuthMethod; providerSubject?: string | null; credentialId?: string | null; id?: string }): Promise<Identity>;
+  getIdentityByProviderSubject(method: AuthMethod, subject: string): Promise<Identity | null>;
+  getIdentityByCredentialId(credentialId: string): Promise<Identity | null>;
+  listIdentities(accountId: string): Promise<Identity[]>;
+  deleteIdentity(accountId: string, method: AuthMethod): Promise<void>;
+  putCredential(c: { accountId: string; method: AuthMethod; wrappedPrivateKey: Uint8Array; kdfParams: unknown }): Promise<void>;
+  getCredential(accountId: string, method: AuthMethod): Promise<Credential | null>;
+  listCredentials(accountId: string): Promise<{ method: AuthMethod; createdAt: string }[]>;
+  deleteCredential(accountId: string, method: AuthMethod): Promise<void>;
+  updatePasskeyCounter(accountId: string, counter: number): Promise<void>;
+  putPublicKey(p: { accountId: string; publicKeyJwk: unknown }): Promise<void>;
+  getPublicKey(accountId: string): Promise<PublicKey | null>;
+}
+
+/**
+ * Vault + envelope storage only — no access policy. `getEnvelopeRow` answers "does a row exist",
+ * not "may this principal open the vault"; see `resolveEnvelopeAccess` in ./envelope-access for
+ * the policy that composes this with `ProviderLinkStore`.
+ */
+export interface EnvelopeStore {
+  createVault(v: { vaultId: string; ownerAccountId: string; r2Key: string; hd1Version: number }): Promise<VaultRow>;
+  getVault(vaultId: string): Promise<VaultRow | null>;
+  getVaultByR2Key(r2Key: string): Promise<VaultRow | null>;
+  getVaultByStagingR2Key(r2Key: string): Promise<VaultRow | null>;
+  listVaultsForOwner(ownerAccountId: string): Promise<VaultRow[]>;
+  setRotationPending(vaultId: string, pending: boolean): Promise<void>;
+  setRotationStaging(vaultId: string, r2Key: string | null): Promise<void>;
+  setOrgRecoveryRevoked(vaultId: string, at: string | null): Promise<void>;
+  putEnvelope(e: { vaultId: string; principalAccountId: string; wrappedDek: Uint8Array; ephemeralPublicKeyJwk: unknown; createdBy: string }): Promise<void>;
+  /** Atomically swaps a vault's whole envelope set. */
+  replaceEnvelopes(vaultId: string, envelopes: EnvelopeInput[], createdBy: string): Promise<void>;
+  /** Atomically swaps the envelope set AND repoints the vault at a freshly-written object. */
+  commitRotation(vaultId: string, newR2Key: string, envelopes: EnvelopeInput[], createdBy: string): Promise<void>;
+  getEnvelopeRow(vaultId: string, principalAccountId: string): Promise<Envelope | null>;
+  listEnvelopesForVault(vaultId: string): Promise<Envelope[]>;
+  listEnvelopesForPrincipal(principalAccountId: string): Promise<Envelope[]>;
+  deleteEnvelope(vaultId: string, principalAccountId: string): Promise<void>;
+}
+
+export interface ProviderLinkStore {
+  create(l: {
+    patientAccountId: string;
+    providerAccountId: string;
+    role: ProviderKind;
+    status?: LinkStatus;
+    consentRef?: string | null;
+    grantedBy: string;
+    expiresAt?: string | null;
+    id?: string;
+  }): Promise<ProviderLink>;
+  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[]>;
+  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 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.
+ */
+export interface AuditStore {
+  insertAccessEvent(e: { actorAccountId: string; subjectAccountId: string; vaultId?: string | null; action: string; consentRef?: string | null; meta?: unknown; id?: string }): Promise<AccessEvent>;
+  listAccessEventsForSubject(subjectAccountId: string): Promise<AccessEvent[]>;
+}

package/vault-sink.ts

@@ -0,0 +1,147 @@
+import { encryptVaultV2 } from "./crypto";
+
+// A VaultSink persists an already-encrypted vault blob under a vault id. The
+// encryption boundary stays in the browser (saveVaultV2 encrypts); a sink only
+// stores opaque ciphertext, never plaintext or a key.
+export interface VaultSink {
+  put(id: string, blob: Uint8Array): Promise<void>;
+}
+
+/**
+ * W70 — the version of each vault blob this browser context last saw.
+ *
+ * Deliberately held HERE rather than threaded through callers. `saveVaultV2` has SEVEN call sites in
+ * App.svelte (the queued edit path plus key rotation, leaf-regen persist, Finding refresh, report
+ * import, raw upload and onboarding), and only one of them goes through the save queue. Since the
+ * precondition is now REQUIRED on the browser path, a call site that forgot to pass an etag would not
+ * degrade — it would 428, i.e. a patient unable to save their own record. 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.
+ */
+const etags = new Map<string, string>();
+
+/** Record the version seen on a GET (or cleared, when a vault is closed). */
+export function rememberVaultEtag(id: string, etag: string | null): void {
+  if (etag) etags.set(id, etag);
+  else etags.delete(id);
+}
+
+export function knownVaultEtag(id: string): string | null {
+  return etags.get(id) ?? null;
+}
+
+/**
+ * The save was refused because the blob moved since this context read it.
+ *
+ * Typed, not a string match: the caller must be able to tell "someone else edited this record" from
+ * "the network is down", because the honest response to each is completely different.
+ */
+export class VaultConflictError extends Error {
+  constructor(readonly serverEtag: string | null) {
+    super("This record was changed in another tab or on another device.");
+    this.name = "VaultConflictError";
+  }
+}
+
+/**
+ * One hook, so every save path reports a conflict — not just the queued one.
+ *
+ * Six of `saveVaultV2`'s seven call sites are direct `await`s outside the save queue (key rotation,
+ * leaf-regen persist, Finding refresh, report import, raw upload, onboarding). Wiring the conflict
+ * state through each would be six chances to miss one, and a missed one is an unhandled rejection on a
+ * health record. 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;
+export function setVaultConflictHandler(fn: ((e: VaultConflictError) => void) | null): void {
+  onConflict = fn;
+}
+
+// Dev-only sink: POSTs the blob to the Vite dev-server middleware, which writes
+// public/data-{id}.enc to disk (see vite.config.ts). Absent from the deployed
+// build — there is no such endpoint in production. The R2 sink (W6) 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)}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/octet-stream" },
+      body: blob as BodyInit,
+    });
+    if (!res.ok) {
+      throw new Error(`save failed (${res.status}): ${(await res.text()) || res.statusText}`);
+    }
+  },
+};
+
+// Remote sink: PUTs the encrypted blob to the R2-backed Pages Function (W6, re-gated W44).
+// `/api/vault/{id}` only exists in the deployed build; the guard now accepts the hd_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.
+/**
+ * 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.
+ *
+ * Serializing HERE rather than in vaultSave 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.
+ */
+const writeChains = new Map<string, Promise<void>>();
+
+export const r2Sink: VaultSink = {
+  put(id, blob) {
+    const prev = writeChains.get(id) ?? Promise.resolve();
+    // The `.catch` is on the READ, not the store: one failed write must not poison every later one,
+    // while the failure still reaches its own caller through the promise returned below. Catching on
+    // both sides would be redundant — and a redundant guard is one no test can distinguish, which is
+    // how it was caught here.
+    const next = prev.catch(() => {}).then(() => putConditional(id, blob));
+    writeChains.set(id, next);
+    return next;
+  },
+};
+
+async function putConditional(id: string, blob: Uint8Array): Promise<void> {
+  {
+    const known = etags.get(id);
+    const headers: Record<string, string> = { "Content-Type": "application/octet-stream" };
+    // Either "replace exactly this version" or "create, and refuse if one already exists". Never
+    // neither: the Function 428s an unconditional browser write, by design.
+    if (known) headers["If-Match"] = known;
+    else headers["If-None-Match"] = "*";
+
+    const res = await fetch(`/api/vault/${encodeURIComponent(id)}`, { method: "PUT", headers, body: blob as BodyInit });
+
+    if (res.status === 412) {
+      // Adopt nothing yet — the caller decides. The server hands back the current version so a
+      // resolution costs one round trip rather than two.
+      const conflict = new VaultConflictError(res.headers.get("ETag"));
+      onConflict?.(conflict);
+      throw conflict;
+    }
+    if (!res.ok) {
+      throw new Error(`save failed (${res.status}): ${(await res.text()) || res.statusText}`);
+    }
+    const newEtag = res.headers.get("ETag");
+    if (newEtag) etags.set(id, newEtag);
+  }
+}
+
+// Build-time selection: dev (vite) writes to disk via localSink; the deployed bundle (and the
+// wrangler-pages-dev e2e harness) persists to R2 and never references /__save-vault.
+export const vaultSink: VaultSink = import.meta.env.DEV ? localSink : r2Sink;
+
+// W44 — 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);
+}