@tinytars/vault 0.1.4

package/adapters/d1/vault.ts

@@ -0,0 +1,209 @@
+import type { D1Database } from "./types";
+import { toBytes } from "./types";
+import type { VaultRow, Envelope } from "../../stores";
+export type { VaultRow, Envelope };
+
+// CRUD only. `getEnvelope()` — the version of this read that applies access POLICY (provider-link
+// state, the org-recovery principal) — is app-specific and stays in the app's identity-vault.ts,
+// built on top of `getEnvelopeRow`/`getVault` below. See stores.ts's own docstring on why policy
+// doesn't belong in a portable adapter.
+
+interface VaultRowRaw {
+  vault_id: string;
+  owner_account_id: string;
+  r2_key: string;
+  hd1_version: number;
+  rotation_pending?: number;
+  org_recovery_revoked_at?: string | null;
+  rotation_staging_r2_key?: string | null;
+}
+function mapVault(r: VaultRowRaw): VaultRow {
+  return {
+    vaultId: r.vault_id,
+    ownerAccountId: r.owner_account_id,
+    r2Key: r.r2_key,
+    hd1Version: r.hd1_version,
+    rotationPending: r.rotation_pending === 1,
+    orgRecoveryRevokedAt: r.org_recovery_revoked_at ?? null,
+    rotationStagingR2Key: r.rotation_staging_r2_key ?? null,
+  };
+}
+
+export async function setRotationPending(db: D1Database, vaultId: string, pending: boolean): Promise<void> {
+  await db.prepare("UPDATE vaults SET rotation_pending = ? WHERE vault_id = ?").bind(pending ? 1 : 0, vaultId).run();
+}
+
+export async function setOrgRecoveryRevoked(db: D1Database, vaultId: string, at: string | null): Promise<void> {
+  await db.prepare("UPDATE vaults SET org_recovery_revoked_at = ? WHERE vault_id = ?").bind(at, vaultId).run();
+}
+
+export async function createVault(
+  db: D1Database,
+  v: { vaultId: string; ownerAccountId: string; r2Key: string; hd1Version: number }
+): Promise<VaultRow> {
+  await db
+    .prepare("INSERT INTO vaults (vault_id, owner_account_id, r2_key, hd1_version) VALUES (?, ?, ?, ?)")
+    .bind(v.vaultId, v.ownerAccountId, v.r2Key, v.hd1Version)
+    .run();
+  return { ...v, rotationPending: false, orgRecoveryRevokedAt: null, rotationStagingR2Key: null };
+}
+
+export async function getVault(db: D1Database, vaultId: string): Promise<VaultRow | null> {
+  const row = await db.prepare("SELECT * FROM vaults WHERE vault_id = ?").bind(vaultId).first<VaultRowRaw>();
+  return row ? mapVault(row) : null;
+}
+
+/** W75 — the vault whose in-flight rotation has reserved this key. See `commitRotation`. */
+export async function getVaultByStagingR2Key(db: D1Database, r2Key: string): Promise<VaultRow | null> {
+  const row = await db.prepare("SELECT * FROM vaults WHERE rotation_staging_r2_key = ?").bind(r2Key).first<VaultRowRaw>();
+  return row ? mapVault(row) : null;
+}
+
+export async function setRotationStaging(db: D1Database, vaultId: string, r2Key: string | null): Promise<void> {
+  await db.prepare("UPDATE vaults SET rotation_staging_r2_key = ? WHERE vault_id = ?").bind(r2Key, vaultId).run();
+}
+
+export async function getVaultByR2Key(db: D1Database, r2Key: string): Promise<VaultRow | null> {
+  const row = await db.prepare("SELECT * FROM vaults WHERE r2_key = ?").bind(r2Key).first<VaultRowRaw>();
+  return row ? mapVault(row) : null;
+}
+
+export async function listVaultsForOwner(db: D1Database, ownerAccountId: string): Promise<VaultRow[]> {
+  const { results } = await db.prepare("SELECT * FROM vaults WHERE owner_account_id = ?").bind(ownerAccountId).all<VaultRowRaw>();
+  return results.map(mapVault);
+}
+
+interface EnvelopeRow {
+  vault_id: string;
+  principal_account_id: string;
+  wrapped_dek: unknown;
+  ephemeral_public_key_jwk: string;
+  created_by: string;
+  created_at: string;
+}
+function mapEnvelope(r: EnvelopeRow): Envelope {
+  return {
+    vaultId: r.vault_id,
+    principalAccountId: r.principal_account_id,
+    wrappedDek: toBytes(r.wrapped_dek),
+    ephemeralPublicKeyJwk: JSON.parse(r.ephemeral_public_key_jwk),
+    createdBy: r.created_by,
+    createdAt: r.created_at,
+  };
+}
+
+export async function putEnvelope(
+  db: D1Database,
+  e: { vaultId: string; principalAccountId: string; wrappedDek: Uint8Array; ephemeralPublicKeyJwk: unknown; createdBy: string }
+): Promise<void> {
+  const createdAt = new Date().toISOString();
+  await db
+    .prepare(
+      "INSERT OR REPLACE INTO vault_envelopes (vault_id, principal_account_id, wrapped_dek, ephemeral_public_key_jwk, created_by, created_at) VALUES (?, ?, ?, ?, ?, ?)"
+    )
+    .bind(e.vaultId, e.principalAccountId, e.wrappedDek, JSON.stringify(e.ephemeralPublicKeyJwk), e.createdBy, createdAt)
+    .run();
+}
+
+/**
+ * W71 — swap a vault's whole envelope set atomically.
+ *
+ * The rotation route used to delete every envelope in a loop and then build the replacements one at a
+ * time, decoding each `wrappedDEK` as it went. Two ways that ended in an unrecoverable vault: a
+ * malformed base64 string threw AFTER the deletes had committed, and a D1 failure partway through the
+ * second loop left the set half-written. Either way the R2 blob stays encrypted under the new DEK
+ * while no envelope anywhere can unwrap it — including the org recovery envelope, so there is no
+ * second door. Nobody finds out until the next unlock fails.
+ *
+ * One batch, so D1 either applies the whole swap or none of it. Callers must still validate the
+ * envelopes before calling: a decode that throws here would throw before the batch is submitted,
+ * which is safe, but the caller owes the user a 400 rather than a 500.
+ */
+export async function replaceEnvelopes(
+  db: D1Database,
+  vaultId: string,
+  envelopes: { principalAccountId: string; wrappedDek: Uint8Array; ephemeralPublicKeyJwk: unknown }[],
+  createdBy: string,
+): Promise<void> {
+  const createdAt = new Date().toISOString();
+  await db.batch([
+    db.prepare("DELETE FROM vault_envelopes WHERE vault_id = ?").bind(vaultId),
+    ...envelopes.map((e) =>
+      db
+        .prepare(
+          "INSERT OR REPLACE INTO vault_envelopes (vault_id, principal_account_id, wrapped_dek, ephemeral_public_key_jwk, created_by, created_at) VALUES (?, ?, ?, ?, ?, ?)"
+        )
+        .bind(vaultId, e.principalAccountId, e.wrappedDek, JSON.stringify(e.ephemeralPublicKeyJwk), createdBy, createdAt)
+    ),
+  ]);
+}
+
+/**
+ * W75 — the whole re-key, committed as one D1 batch: swap the envelope set AND repoint the vault at
+ * the freshly-written object, in one implicit transaction.
+ *
+ * The atomicity is the point. The rotation used to re-encrypt IN PLACE — new DEK into the same r2
+ * key, envelopes updated several network round trips later. Between those two writes the ciphertext
+ * was readable only by a key held in one tab's memory, and a dropped connection there locked every
+ * principal out of the record permanently. Writing to a new key makes this UPDATE the only moment
+ * anything becomes true: before it, the old blob and the old envelopes still agree.
+ *
+ * The old object is deliberately left in R2 rather than deleted here. It is unreferenced and
+ * undecryptable-by-design after the swap, and deleting it would put an irreversible step back inside
+ * the window this function exists to close.
+ */
+export async function commitRotation(
+  db: D1Database,
+  vaultId: string,
+  newR2Key: string,
+  envelopes: { principalAccountId: string; wrappedDek: Uint8Array; ephemeralPublicKeyJwk: unknown }[],
+  createdBy: string,
+): Promise<void> {
+  const createdAt = new Date().toISOString();
+  await db.batch([
+    db.prepare("DELETE FROM vault_envelopes WHERE vault_id = ?").bind(vaultId),
+    ...envelopes.map((e) =>
+      db
+        .prepare(
+          "INSERT OR REPLACE INTO vault_envelopes (vault_id, principal_account_id, wrapped_dek, ephemeral_public_key_jwk, created_by, created_at) VALUES (?, ?, ?, ?, ?, ?)"
+        )
+        .bind(vaultId, e.principalAccountId, e.wrappedDek, JSON.stringify(e.ephemeralPublicKeyJwk), createdBy, createdAt)
+    ),
+    db
+      .prepare("UPDATE vaults SET r2_key = ?, rotation_staging_r2_key = NULL, rotation_pending = 0 WHERE vault_id = ?")
+      .bind(newR2Key, vaultId),
+  ]);
+}
+
+/**
+ * The envelope row as stored, with NO access check. Use the app's `getEnvelope` unless you
+ * specifically need the raw row (listing, rotation, administration) — this one answers "does a row
+ * exist", which is not the same question as "may this principal open the vault".
+ */
+export async function getEnvelopeRow(db: D1Database, vaultId: string, principalAccountId: string): Promise<Envelope | null> {
+  const row = await db
+    .prepare("SELECT * FROM vault_envelopes WHERE vault_id = ? AND principal_account_id = ?")
+    .bind(vaultId, principalAccountId)
+    .first<EnvelopeRow>();
+  return row ? mapEnvelope(row) : null;
+}
+
+export async function listEnvelopesForVault(db: D1Database, vaultId: string): Promise<Envelope[]> {
+  const { results } = await db.prepare("SELECT * FROM vault_envelopes WHERE vault_id = ?").bind(vaultId).all<EnvelopeRow>();
+  return results.map(mapEnvelope);
+}
+
+export async function listEnvelopesForPrincipal(db: D1Database, principalAccountId: string): Promise<Envelope[]> {
+  const { results } = await db
+    .prepare("SELECT * FROM vault_envelopes WHERE principal_account_id = ?")
+    .bind(principalAccountId)
+    .all<EnvelopeRow>();
+  return results.map(mapEnvelope);
+}
+
+export async function deleteEnvelope(db: D1Database, vaultId: string, principalAccountId: string): Promise<void> {
+  await db
+    .prepare("DELETE FROM vault_envelopes WHERE vault_id = ? AND principal_account_id = ?")
+    .bind(vaultId, principalAccountId)
+    .run();
+}

package/adapters/memory.ts

@@ -0,0 +1,342 @@
+// In-memory implementations of every stores.ts interface. This is the portability proof: the same
+// conformance suite (./conformance.ts) runs unchanged against these and against the D1 adapter, so
+// "storage-agnostic" is demonstrated rather than merely asserted by interface shape.
+
+import type {
+  Account,
+  AccountStore,
+  AuditStore,
+  AccessEvent,
+  AuthMethod,
+  Credential,
+  CredentialStore,
+  Envelope,
+  EnvelopeInput,
+  EnvelopeStore,
+  Identity,
+  LifecycleStage,
+  LinkStatus,
+  ProviderKind,
+  ProviderLink,
+  ProviderLinkStore,
+  PublicKey,
+  UnitSystem,
+  VaultRow,
+} from "../stores";
+
+export class MemoryAccountStore implements AccountStore {
+  private byId = new Map<string, Account>();
+  private sessionsValidFromMs = new Map<string, number>();
+
+  async create(a: { id: string; displayName: string; email?: string | null; lifecycleStage?: LifecycleStage; providerKind?: ProviderKind | null }): Promise<Account> {
+    const account: Account = {
+      id: a.id,
+      email: a.email ?? null,
+      emailConfirmed: false,
+      displayName: a.displayName,
+      lifecycleStage: a.lifecycleStage ?? "active",
+      providerKind: a.providerKind ?? null,
+      unitSystem: null,
+      createdAt: new Date().toISOString(),
+      deletedAt: null,
+      emailChangedAt: null,
+    };
+    this.byId.set(a.id, account);
+    return { ...account };
+  }
+
+  async get(id: string): Promise<Account | null> {
+    const a = this.byId.get(id);
+    return a ? { ...a } : null;
+  }
+
+  async getByEmail(email: string): Promise<Account | null> {
+    for (const a of this.byId.values()) if (a.email === email) return { ...a };
+    return null;
+  }
+
+  async sessionsValidFrom(accountId: string): Promise<number | null> {
+    if (!this.byId.has(accountId)) return Number.POSITIVE_INFINITY;
+    return this.sessionsValidFromMs.get(accountId) ?? null;
+  }
+
+  async revokeSessions(accountId: string): Promise<void> {
+    this.sessionsValidFromMs.set(accountId, Math.floor(Date.now() / 1000));
+  }
+
+  async setEmailConfirmed(id: string, confirmed: boolean): Promise<void> {
+    const a = this.byId.get(id);
+    if (a) a.emailConfirmed = confirmed;
+  }
+
+  async setLifecycleStage(id: string, stage: LifecycleStage): Promise<void> {
+    const a = this.byId.get(id);
+    if (a) a.lifecycleStage = stage;
+  }
+
+  async updateProfile(id: string, updates: { email?: string | null; displayName?: string; unitSystem?: UnitSystem | null }): Promise<void> {
+    const a = this.byId.get(id);
+    if (!a) return;
+    if (updates.email !== undefined) a.email = updates.email;
+    if (updates.displayName !== undefined) a.displayName = updates.displayName;
+    if (updates.unitSystem !== undefined) a.unitSystem = updates.unitSystem;
+  }
+
+  async tombstone(accountId: string, at: string): Promise<void> {
+    const a = this.byId.get(accountId);
+    if (!a) return;
+    a.email = null;
+    a.emailConfirmed = false;
+    a.displayName = "";
+    a.lifecycleStage = "churned";
+    a.providerKind = null;
+    a.unitSystem = null;
+    a.deletedAt = at;
+  }
+
+  async markEmailChanged(accountId: string, at: string): Promise<void> {
+    const a = this.byId.get(accountId);
+    if (a) a.emailChangedAt = at;
+  }
+}
+
+export class MemoryCredentialStore implements CredentialStore {
+  private identities: Identity[] = [];
+  private credentials = new Map<string, Credential>(); // key: `${accountId}:${method}`
+  private publicKeys = new Map<string, PublicKey>();
+
+  private credKey(accountId: string, method: AuthMethod) {
+    return `${accountId}:${method}`;
+  }
+
+  async addIdentity(i: { accountId: string; method: AuthMethod; providerSubject?: string | null; credentialId?: string | null; id?: string }): Promise<Identity> {
+    const identity: Identity = {
+      id: i.id ?? crypto.randomUUID(),
+      accountId: i.accountId,
+      method: i.method,
+      providerSubject: i.providerSubject ?? null,
+      credentialId: i.credentialId ?? null,
+      createdAt: new Date().toISOString(),
+    };
+    this.identities.push(identity);
+    return { ...identity };
+  }
+
+  async getIdentityByProviderSubject(method: AuthMethod, subject: string): Promise<Identity | null> {
+    const found = this.identities.find((i) => i.method === method && i.providerSubject === subject);
+    return found ? { ...found } : null;
+  }
+
+  async getIdentityByCredentialId(credentialId: string): Promise<Identity | null> {
+    const found = this.identities.find((i) => i.credentialId === credentialId);
+    return found ? { ...found } : null;
+  }
+
+  async listIdentities(accountId: string): Promise<Identity[]> {
+    return this.identities.filter((i) => i.accountId === accountId).map((i) => ({ ...i }));
+  }
+
+  async deleteIdentity(accountId: string, method: AuthMethod): Promise<void> {
+    this.identities = this.identities.filter((i) => !(i.accountId === accountId && i.method === method));
+  }
+
+  async putCredential(c: { accountId: string; method: AuthMethod; wrappedPrivateKey: Uint8Array; kdfParams: unknown }): Promise<void> {
+    this.credentials.set(this.credKey(c.accountId, c.method), { ...c, createdAt: new Date().toISOString() });
+  }
+
+  async getCredential(accountId: string, method: AuthMethod): Promise<Credential | null> {
+    const c = this.credentials.get(this.credKey(accountId, method));
+    return c ? { ...c } : null;
+  }
+
+  async listCredentials(accountId: string): Promise<{ method: AuthMethod; createdAt: string }[]> {
+    return [...this.credentials.values()]
+      .filter((c) => c.accountId === accountId)
+      .map((c) => ({ method: c.method, createdAt: c.createdAt }));
+  }
+
+  async deleteCredential(accountId: string, method: AuthMethod): Promise<void> {
+    this.credentials.delete(this.credKey(accountId, method));
+  }
+
+  async updatePasskeyCounter(accountId: string, counter: number): Promise<void> {
+    const c = this.credentials.get(this.credKey(accountId, "passkey"));
+    if (!c) return;
+    c.kdfParams = { ...(c.kdfParams as Record<string, unknown>), counter };
+  }
+
+  async putPublicKey(p: { accountId: string; publicKeyJwk: unknown }): Promise<void> {
+    this.publicKeys.set(p.accountId, { ...p, createdAt: new Date().toISOString() });
+  }
+
+  async getPublicKey(accountId: string): Promise<PublicKey | null> {
+    const p = this.publicKeys.get(accountId);
+    return p ? { ...p } : null;
+  }
+}
+
+export class MemoryEnvelopeStore implements EnvelopeStore {
+  private vaults = new Map<string, VaultRow>();
+  private envelopes = new Map<string, Envelope>(); // key: `${vaultId}:${principalAccountId}`
+
+  private envKey(vaultId: string, principalAccountId: string) {
+    return `${vaultId}:${principalAccountId}`;
+  }
+
+  async createVault(v: { vaultId: string; ownerAccountId: string; r2Key: string; hd1Version: number }): Promise<VaultRow> {
+    const row: VaultRow = { ...v, rotationPending: false, orgRecoveryRevokedAt: null, rotationStagingR2Key: null };
+    this.vaults.set(v.vaultId, row);
+    return { ...row };
+  }
+
+  async getVault(vaultId: string): Promise<VaultRow | null> {
+    const v = this.vaults.get(vaultId);
+    return v ? { ...v } : null;
+  }
+
+  async getVaultByR2Key(r2Key: string): Promise<VaultRow | null> {
+    for (const v of this.vaults.values()) if (v.r2Key === r2Key) return { ...v };
+    return null;
+  }
+
+  async getVaultByStagingR2Key(r2Key: string): Promise<VaultRow | null> {
+    for (const v of this.vaults.values()) if (v.rotationStagingR2Key === r2Key) return { ...v };
+    return null;
+  }
+
+  async listVaultsForOwner(ownerAccountId: string): Promise<VaultRow[]> {
+    return [...this.vaults.values()].filter((v) => v.ownerAccountId === ownerAccountId).map((v) => ({ ...v }));
+  }
+
+  async setRotationPending(vaultId: string, pending: boolean): Promise<void> {
+    const v = this.vaults.get(vaultId);
+    if (v) v.rotationPending = pending;
+  }
+
+  async setRotationStaging(vaultId: string, r2Key: string | null): Promise<void> {
+    const v = this.vaults.get(vaultId);
+    if (v) v.rotationStagingR2Key = r2Key;
+  }
+
+  async setOrgRecoveryRevoked(vaultId: string, at: string | null): Promise<void> {
+    const v = this.vaults.get(vaultId);
+    if (v) v.orgRecoveryRevokedAt = at;
+  }
+
+  async putEnvelope(e: { vaultId: string; principalAccountId: string; wrappedDek: Uint8Array; ephemeralPublicKeyJwk: unknown; createdBy: string }): Promise<void> {
+    this.envelopes.set(this.envKey(e.vaultId, e.principalAccountId), { ...e, createdAt: new Date().toISOString() });
+  }
+
+  async replaceEnvelopes(vaultId: string, envelopes: EnvelopeInput[], createdBy: string): Promise<void> {
+    for (const key of [...this.envelopes.keys()]) if (key.startsWith(`${vaultId}:`)) this.envelopes.delete(key);
+    const createdAt = new Date().toISOString();
+    for (const e of envelopes) {
+      this.envelopes.set(this.envKey(vaultId, e.principalAccountId), { vaultId, createdBy, createdAt, ...e });
+    }
+  }
+
+  async commitRotation(vaultId: string, newR2Key: string, envelopes: EnvelopeInput[], createdBy: string): Promise<void> {
+    await this.replaceEnvelopes(vaultId, envelopes, createdBy);
+    const v = this.vaults.get(vaultId);
+    if (v) {
+      v.r2Key = newR2Key;
+      v.rotationStagingR2Key = null;
+      v.rotationPending = false;
+    }
+  }
+
+  async getEnvelopeRow(vaultId: string, principalAccountId: string): Promise<Envelope | null> {
+    const e = this.envelopes.get(this.envKey(vaultId, principalAccountId));
+    return e ? { ...e } : null;
+  }
+
+  async listEnvelopesForVault(vaultId: string): Promise<Envelope[]> {
+    return [...this.envelopes.values()].filter((e) => e.vaultId === vaultId).map((e) => ({ ...e }));
+  }
+
+  async listEnvelopesForPrincipal(principalAccountId: string): Promise<Envelope[]> {
+    return [...this.envelopes.values()].filter((e) => e.principalAccountId === principalAccountId).map((e) => ({ ...e }));
+  }
+
+  async deleteEnvelope(vaultId: string, principalAccountId: string): Promise<void> {
+    this.envelopes.delete(this.envKey(vaultId, principalAccountId));
+  }
+}
+
+export class MemoryProviderLinkStore implements ProviderLinkStore {
+  private links = new Map<string, ProviderLink>();
+
+  async create(l: { patientAccountId: string; providerAccountId: string; role: ProviderKind; status?: LinkStatus; consentRef?: string | null; grantedBy: string; expiresAt?: string | null; id?: string }): Promise<ProviderLink> {
+    const link: ProviderLink = {
+      id: l.id ?? crypto.randomUUID(),
+      patientAccountId: l.patientAccountId,
+      providerAccountId: l.providerAccountId,
+      role: l.role,
+      status: l.status ?? "invited",
+      consentRef: l.consentRef ?? null,
+      grantedBy: l.grantedBy,
+      grantedAt: new Date().toISOString(),
+      expiresAt: l.expiresAt ?? null,
+    };
+    this.links.set(link.id, link);
+    return { ...link };
+  }
+
+  async updateStatus(id: string, status: LinkStatus): Promise<void> {
+    const l = this.links.get(id);
+    if (l) l.status = status;
+  }
+
+  async grantSupport(id: string, opts: { expiresAt: string | null; consentRef?: string | null }): Promise<void> {
+    const l = this.links.get(id);
+    if (!l) return;
+    l.status = "active";
+    l.expiresAt = opts.expiresAt;
+    l.consentRef = opts.consentRef ?? null;
+  }
+
+  async get(id: string): Promise<ProviderLink | null> {
+    const l = this.links.get(id);
+    return l ? { ...l } : null;
+  }
+
+  async listForPatient(patientAccountId: string): Promise<ProviderLink[]> {
+    return [...this.links.values()].filter((l) => l.patientAccountId === patientAccountId).map((l) => ({ ...l }));
+  }
+
+  async listForProvider(providerAccountId: string): Promise<ProviderLink[]> {
+    return [...this.links.values()].filter((l) => l.providerAccountId === providerAccountId).map((l) => ({ ...l }));
+  }
+
+  async getActive(patientAccountId: string, providerAccountId: string): Promise<ProviderLink | null> {
+    const link = [...this.links.values()].find(
+      (l) => l.patientAccountId === patientAccountId && l.providerAccountId === providerAccountId
+    );
+    if (!link || link.status !== "active") return null;
+    if (link.expiresAt && Date.parse(link.expiresAt) <= Date.now()) return null;
+    return { ...link };
+  }
+}
+
+export class MemoryAuditStore implements AuditStore {
+  private events: AccessEvent[] = [];
+
+  async insertAccessEvent(e: { actorAccountId: string; subjectAccountId: string; vaultId?: string | null; action: string; consentRef?: string | null; meta?: unknown; id?: string }): Promise<AccessEvent> {
+    const event: AccessEvent = {
+      id: e.id ?? crypto.randomUUID(),
+      actorAccountId: e.actorAccountId,
+      subjectAccountId: e.subjectAccountId,
+      vaultId: e.vaultId ?? null,
+      action: e.action,
+      consentRef: e.consentRef ?? null,
+      meta: e.meta ?? {},
+      createdAt: new Date().toISOString(),
+    };
+    this.events.push(event);
+    return { ...event };
+  }
+
+  async listAccessEventsForSubject(subjectAccountId: string): Promise<AccessEvent[]> {
+    return this.events.filter((e) => e.subjectAccountId === subjectAccountId).map((e) => ({ ...e }));
+  }
+}

package/adapters/pages-http.ts

@@ -0,0 +1,13 @@
+// Wraps a portable (request, deps) => Promise<Response> handler into Cloudflare Pages Functions'
+// onRequestX({request, env, params}) shape. The portable handler never sees `env` or `context` — only
+// the plain `Deps` object `buildDeps` constructs from them — so the same handler runs unmodified under
+// any host that can produce a Deps value and a Request.
+
+export type PortableHandler<Deps> = (request: Request, deps: Deps) => Promise<Response>;
+
+export function pagesHandler<Deps, Env = unknown, Params = unknown>(
+  handler: PortableHandler<Deps>,
+  buildDeps: (context: { request: Request; env: Env; params: Params }) => Deps
+): (context: { request: Request; env: Env; params: Params }) => Promise<Response> {
+  return (context) => handler(context.request, buildDeps(context));
+}

package/adapters/r2.ts

@@ -0,0 +1,50 @@
+import type { BlobStore, BlobConditional, StoredBlob } from "../blob-store";
+
+// Minimal structural type for the R2 binding — no @cloudflare/workers-types dependency, and
+// trivially mockable in tests. Moved from apps/health-dash-web/functions/api/vault/[id].ts, which
+// now imports R2Bucket/R2BlobStore from here instead of declaring its own copy.
+export interface R2ObjectBody {
+  body: ReadableStream;
+  /** W70 — the version token. Handed to the browser on GET and sent back as If-Match on PUT. */
+  etag: string;
+}
+/** A precondition on a write. Verified against real workerd in tests/unit/r2-conditional-put.test.ts. */
+export interface R2Conditional {
+  etagMatches?: string;
+  etagDoesNotMatch?: string;
+}
+export interface R2Bucket {
+  get(key: string): Promise<R2ObjectBody | null>;
+  /**
+   * Returns the stored object (carrying its NEW etag), or `null` when an `onlyIf` precondition fails.
+   * Null-on-failure rather than a throw is observed behaviour, not an assumption — see
+   * tests/unit/r2-conditional-put.test.ts, which pins it against workerd.
+   */
+  put(key: string, value: Uint8Array, options?: { onlyIf?: R2Conditional }): Promise<{ etag: string } | null>;
+  delete(key: string): Promise<void>;
+}
+
+/** `BlobStore`'s conditional field names, mapped onto R2's own (`onlyIf.etagMatches`/`etagDoesNotMatch`). */
+function toOnlyIf(conditional?: BlobConditional): R2Conditional | undefined {
+  if (!conditional) return undefined;
+  if (conditional.ifMatch) return { etagMatches: conditional.ifMatch };
+  if (conditional.ifNoneMatch === "*") return { etagDoesNotMatch: "*" };
+  return undefined;
+}
+
+export class R2BlobStore implements BlobStore {
+  constructor(private bucket: R2Bucket) {}
+
+  async get(key: string): Promise<StoredBlob | null> {
+    return this.bucket.get(key);
+  }
+
+  async put(key: string, value: Uint8Array, conditional?: BlobConditional): Promise<{ etag: string } | null> {
+    const onlyIf = toOnlyIf(conditional);
+    return onlyIf ? this.bucket.put(key, value, { onlyIf }) : this.bucket.put(key, value);
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.bucket.delete(key);
+  }
+}

package/blob-store.ts

@@ -0,0 +1,27 @@
+// A BlobStore persists an opaque byte blob under a string key, with an optional optimistic-
+// concurrency conditional on write. Server-side counterpart to vault-sink.ts's browser-side
+// VaultSink — that one calls an HTTP endpoint from the browser; this one is the interface the
+// endpoint's own handler stores through, so the handler need not assume any particular backend.
+export interface StoredBlob {
+  body: ReadableStream;
+  /** The version token of the object as stored. Handed back on GET, sent back as `ifMatch` on PUT. */
+  etag: string;
+}
+
+export interface BlobConditional {
+  /** Only write if the current object's etag matches this value. */
+  ifMatch?: string;
+  /** Only write if no object currently exists at this key. `"*"` is the only supported value. */
+  ifNoneMatch?: "*";
+}
+
+export interface BlobStore {
+  get(key: string): Promise<StoredBlob | null>;
+  /**
+   * Returns the written object's new etag, or `null` when a conditional fails. Null-on-failure
+   * rather than a thrown error mirrors R2's own observed contract (see adapters/r2.ts) — an
+   * implementation is a drop-in replacement only if it fails the same way.
+   */
+  put(key: string, value: Uint8Array, conditional?: BlobConditional): Promise<{ etag: string } | null>;
+  delete(key: string): Promise<void>;
+}