@tinytars/vault 0.1.16 → 0.1.18

package/README.md

@@ -7,46 +7,60 @@ A storage operator who can read what it stores hasn't encrypted the data — it'
 and most hand-rolled "encrypted vault" designs end up exactly there, one convenience shortcut at a
 time. This package is the alternative already built: a shared key-derivation primitive, an
 authenticated envelope format with multi-principal access via wrapped data-encryption keys, and
-storage-agnostic contracts for the account/vault/grant data model those envelopes sit on top of.
+storage-agnostic contracts for the account/vault/grant data model those envelopes sit on top of —
+domain-neutral by design, not health-specific code that happened to get open-sourced.
 
-Built for and extracted from a health-records app that needed patient-controlled encryption plus
-revocable provider access; published because the primitives don't have anything health-specific
-in them. Maintained by the [Tiny Tars Foundation](https://tinytars.foundation), a 501(c)(3).
+Maintained by the [Tiny Tars Foundation](https://tinytars.foundation), a 501(c)(3).
 
 ## Why
 
-### Built for a HIPAA-adjacent app
-
-The pattern such an app needs is exactly what ships here, not something you'd assemble from
-parts. `crypto.ts` gives you a zero-knowledge vault — the storage operator holds ciphertext and
-never a key or usable plaintext. `envelope-access.ts` gives you consent-based sharing — access to
-a vault is a per-principal, revocable wrapped-key grant, not a shared secret or a role flag.
-`break-glass.ts` gives you the third piece that's easy to get wrong by hand: a time-boxed grant
-with the TTL clamp, self-expiry, and audit trail built in, so "temporary access" is actually
-temporary instead of a support ticket someone forgets to close. Put together, that's the
-"encrypted vault + consent-based sharing + time-boxed break-glass access" shape any HIPAA-adjacent
-app ends up needing — and this package ships all three, not a subset with the rest left as an
-exercise. None of that makes the package itself HIPAA-compliant; it's a primitive an adopter
-builds compliant handling on top of, not a compliance product in its own right.
-
-### Not health-specific
-
-The storage contracts in `stores.ts` are generic data-access interfaces; the payload `crypto.ts`
-encrypts is an arbitrary JSON value, not a medical-record shape. Even `ProviderLinkStore`'s
-"provider"/"patient" field names are just this package's first adopter's vocabulary —
-`ARCHITECTURE.md` says to read it generically as "grantee linked to vault owner," and nothing in
-the access-policy logic cares what a principal represents. The same three pieces above fit a
-client's encrypted files shared with revocable access for outside counsel, or a household's
-financial records shared temporarily with an accountant at tax time — any case with an owner, a
-resource only they can decrypt by default, and a need to grant and later cut off someone else's
-access to it.
+### The healthcare deployment this was built for
+
+This package was extracted from a health-records app, and that origin is worth stating plainly
+rather than hiding: it's a real, fully worked use case, not a footnote. Map its vocabulary onto
+this package's generic one and the fit is exact. The vault **owner** is a patient; a **provider**
+link is a treating clinician's standing access to that patient's record; a **support** link is a
+care-team member's time-boxed access, handled by `break-glass.ts`'s grant/check/revoke lifecycle
+so a temporary exception doesn't quietly become a permanent one; the audit log in
+`adapters/d1/audit.ts` is shaped to satisfy the FTC Health Breach Notification Rule's
+disclosure-logging requirement — who accessed whose record and why, so a breach can be scoped to
+affected individuals.
+
+`crypto.ts` gives that app a zero-knowledge vault — the storage operator holds ciphertext and
+never a key or usable plaintext, which matters when the payload is a medical record.
+`envelope-access.ts` gives it consent-based sharing — access is a per-principal, revocable
+wrapped-key grant, not a shared secret or a role flag, which is what "the patient controls who
+sees their record" actually requires at the implementation level. `break-glass.ts` gives it the
+piece hand-rolled HIPAA-adjacent systems get wrong most often: a time-boxed grant with the TTL
+clamp, self-expiry, and audit trail built in. None of this makes the package itself HIPAA-
+compliant — it's a primitive an adopter builds compliant handling on top of, not a compliance
+product in its own right — but the shape it ships is exactly the shape that adopter needs, not
+something assembled from unrelated parts after the fact.
+
+### Beyond health
+
+The same three primitives — an encrypted resource only its owner can read by default, a revocable
+per-principal grant, and a time-boxed version of that grant — solve an identical problem anywhere
+one party owns sensitive data and needs to hand a second party temporary or standing access to it,
+under a record of who saw what and when. None of `stores.ts`'s contracts, `crypto.ts`'s envelope
+format, or `break-glass.ts`'s lifecycle reference anything about the payload's shape or domain.
+Concretely, beyond the healthcare case above:
+
+- **Outside counsel** reviewing a client's encrypted case files, access granted for the matter's
+  duration and revoked when it closes.
+- **An accountant** getting temporary access to a household's financial records at tax time,
+  through the same time-boxed grant `break-glass.ts` gives a clinician.
+- **A corporate IT admin** granted standing access to an employee's HR file for the audit trail
+  it creates, or temporary access during an offboarding review.
+- **A SaaS support agent** getting time-boxed access to a customer's account data to debug a
+  ticket, auto-expiring instead of depending on someone remembering to revoke it.
 
 Claims like these are only worth as much as the threat model backing them. **Read
 `THREAT_MODEL.md` before you adopt this** — it documents what's in scope, what isn't, and two
 deliberate design tradeoffs (extractable keys, no forward secrecy on revoke) that look like bugs
-if you haven't read them first. Notice, while you're there, that it's written in fully generic
-terms too — no "patient," no "provider," no health-specific language anywhere in it. That's not
-an oversight; it's the same evidence the argument above rests on, stated a second way.
+if you haven't read them first. It's written in the same domain-neutral vocabulary as the rest of
+this package — no health-specific language anywhere in it. That's not an oversight; it's the same
+evidence the argument above rests on, stated a second way.
 
 ## What it does
 
@@ -170,7 +184,7 @@ const { publicKeyJwk, privateKey } = await generateAccountKeypair();
 
 // Encrypt a payload (any JSON-serializable value) under a fresh, random DEK.
 const dek = await generateDEK();
-const envelope = await encryptVaultV2({ note: "patient-controlled data" }, dek);
+const envelope = await encryptVaultV2({ note: "owner-controlled data" }, dek);
 
 // Grant this account access by wrapping the DEK for its public key.
 const wrapped = await wrapDEKForPublicKey(dek, publicKeyJwk);
@@ -179,7 +193,7 @@ const wrapped = await wrapDEKForPublicKey(dek, publicKeyJwk);
 const recoveredDek = await unwrapDEKWithPrivateKey(wrapped.wrappedDEK, wrapped.ephemeralPublicKeyJwk, privateKey);
 const plaintext = await decryptVaultV2(envelope, recoveredDek);
 
-console.log(plaintext); // { note: "patient-controlled data" }
+console.log(plaintext); // { note: "owner-controlled data" }
 ```
 
 This package ships TypeScript source directly (no compiled `dist/`) — the subpath imports above
@@ -203,7 +217,7 @@ import type { Envelope, ProviderLink, VaultRow } from "@tinytars/vault/stores";
 
 const envelopes = new Map<string, Envelope>(); // key: `${vaultId}:${principalAccountId}`
 const vaults = new Map<string, VaultRow>();
-const providerLinks = new Map<string, ProviderLink>(); // key: `${patientAccountId}:${providerAccountId}`
+const providerLinks = new Map<string, ProviderLink>(); // key: `${ownerAccountId}:${providerAccountId}`
 
 const envelopeSource: EnvelopeAccessSource = {
   async getEnvelopeRow(vaultId, principalAccountId) {
@@ -215,8 +229,8 @@ const envelopeSource: EnvelopeAccessSource = {
 };
 
 const providerLinkSource: ProviderLinkSource = {
-  async getActive(patientAccountId, providerAccountId) {
-    return providerLinks.get(`${patientAccountId}:${providerAccountId}`) ?? null;
+  async getActive(ownerAccountId, providerAccountId) {
+    return providerLinks.get(`${ownerAccountId}:${providerAccountId}`) ?? null;
   },
 };
 
@@ -267,8 +281,8 @@ is entirely your own auth middleware's job. See `THREAT_MODEL.md`'s "trust bound
 | `adapters/conformance.ts` | Shared vitest contract suites for each `stores.ts` interface, run against every adapter above so "storage-agnostic" is proven, not asserted |
 | `auth-client.ts` | Password/passkey/Google signup, login, session resume, account-settings method management — the browser-side orchestration wiring `crypto.ts` to a specific `/api/auth/*`/`/api/account/*` API. Reference client, not a portable primitive |
 | `auth-recovery.ts` | Recovery-code issuance/redemption (owner and provider-issued), DEK rotation, access-event log fetch — same reference-client caveat as `auth-client.ts` |
-| `auth-support.ts` | Audited support-agent access: patient approves a pending request, support enters via an audited endpoint; support→provider roster access |
-| `auth-grants.ts` | Provider/clinician grant CRUD from the patient side: lookup, grant, revoke |
+| `auth-support.ts` | Audited support-agent access: owner approves a pending request, support enters via an audited endpoint; support→provider roster access |
+| `auth-grants.ts` | Provider grant CRUD from the owner side: lookup, grant, revoke |
 | `org-recovery.ts` | Backfills the org-recovery envelope for accounts that predate or missed it at signup — best-effort, never blocks an unlock |
 | `vault-session.ts` | `VaultEntry`/`VaultSession` types plus `openVault()` — the decrypt-and-open-session step every unlock path shares |
 | `base64.ts` | Byte ↔ base64 codec used throughout the client layer |

package/adapters/conformance.ts

@@ -164,14 +164,14 @@ export function runProviderLinkStoreConformance(label: string, factory: () => Pr
   describe(`ProviderLinkStore conformance (${label})`, () => {
     it("creates a link, defaulting status to invited", async () => {
       const store = await factory();
-      const link = await store.create({ patientAccountId: "p1", providerAccountId: "d1", role: "clinician", grantedBy: "p1" });
+      const link = await store.create({ ownerAccountId: "p1", providerAccountId: "d1", role: "primary", grantedBy: "p1" });
       expect(link.status).toBe("invited");
       expect(await store.get(link.id)).toEqual(link);
     });
 
     it("getActive is null for an invited (non-active) link", async () => {
       const store = await factory();
-      const link = await store.create({ patientAccountId: "p1", providerAccountId: "d1", role: "clinician", grantedBy: "p1" });
+      const link = await store.create({ ownerAccountId: "p1", providerAccountId: "d1", role: "primary", grantedBy: "p1" });
       expect(await store.getActive("p1", "d1")).toBeNull();
       await store.updateStatus(link.id, "active");
       expect((await store.getActive("p1", "d1"))?.id).toBe(link.id);
@@ -179,14 +179,14 @@ export function runProviderLinkStoreConformance(label: string, factory: () => Pr
 
     it("getActive is null once expiresAt is in the past", async () => {
       const store = await factory();
-      const link = await store.create({ patientAccountId: "p1", providerAccountId: "d1", role: "support", grantedBy: "p1", status: "active", expiresAt: "2000-01-01T00:00:00.000Z" });
+      const link = await store.create({ ownerAccountId: "p1", providerAccountId: "d1", role: "support", grantedBy: "p1", status: "active", expiresAt: "2000-01-01T00:00:00.000Z" });
       expect(link.status).toBe("active");
       expect(await store.getActive("p1", "d1")).toBeNull();
     });
 
     it("grantSupport activates and time-boxes a link", async () => {
       const store = await factory();
-      const link = await store.create({ patientAccountId: "p1", providerAccountId: "d1", role: "support", grantedBy: "p1" });
+      const link = await store.create({ ownerAccountId: "p1", providerAccountId: "d1", role: "support", grantedBy: "p1" });
       const expiresAt = new Date(Date.now() + 3600_000).toISOString();
       await store.grantSupport(link.id, { expiresAt, consentRef: "consent-1" });
       const after = await store.get(link.id);
@@ -194,12 +194,12 @@ export function runProviderLinkStoreConformance(label: string, factory: () => Pr
       expect(after?.expiresAt).toBe(expiresAt);
     });
 
-    it("listForPatient / listForProvider scope correctly", async () => {
+    it("listForOwner / listForProvider scope correctly", async () => {
       const store = await factory();
-      await store.create({ patientAccountId: "p1", providerAccountId: "d1", role: "clinician", grantedBy: "p1" });
-      await store.create({ patientAccountId: "p1", providerAccountId: "d2", role: "clinician", grantedBy: "p1" });
-      await store.create({ patientAccountId: "p2", providerAccountId: "d1", role: "clinician", grantedBy: "p2" });
-      expect(await store.listForPatient("p1")).toHaveLength(2);
+      await store.create({ ownerAccountId: "p1", providerAccountId: "d1", role: "primary", grantedBy: "p1" });
+      await store.create({ ownerAccountId: "p1", providerAccountId: "d2", role: "primary", grantedBy: "p1" });
+      await store.create({ ownerAccountId: "p2", providerAccountId: "d1", role: "primary", grantedBy: "p2" });
+      expect(await store.listForOwner("p1")).toHaveLength(2);
       expect(await store.listForProvider("d1")).toHaveLength(2);
     });
   });

package/adapters/d1/accounts.ts

@@ -70,7 +70,7 @@ export async function getAccountByEmail(db: D1Database, email: string): Promise<
 /**
  * The instant before which this account's session cookies are no longer accepted, or null.
  *
- * Read on every authenticated request, by the adopter's own session-check middleware. One indexed lookup by primary
+ * Read on every authenticated request (see `requireSession`). One indexed lookup by primary
  * key is what buys revocability: the cookie is self-contained, so without a server-side fact to
  * check against, nothing short of rotating SESSION_SECRET for the entire deployment can invalidate one.
  */

package/adapters/d1/audit.ts

@@ -2,12 +2,15 @@ import type { D1Database } from "./types";
 import type { AccessEvent } from "../../stores";
 export type { AccessEvent };
 
-// AuditStore's two members only — PHI-access events. Lifecycle/CRM events and raw-object ownership
-// bookkeeping are app-specific concerns that stay in the app's identity-audit.ts (see stores.ts's
-// own docstring on AuditStore).
+// AuditStore's two members only — consent-scoped vault-access events. Lifecycle/CRM events and
+// raw-object ownership bookkeeping are app-specific concerns that stay in the app's
+// identity-audit.ts (see stores.ts's own docstring on AuditStore).
 
-// FTC-HBNR (§I) PHI-access/disclosure audit log. Records WHO (actor) accessed WHOSE (subject)
-// vault and WHY (action + consent_ref), so a breach can be scoped to affected individuals. NO PHI.
+// A generic actor/subject/action audit log for consent-scoped vault access — e.g., satisfies FTC
+// Health Breach Notification Rule PHI-disclosure logging for healthcare deployments, or analogous
+// breach-notification and access-audit obligations in other regulated domains. Records WHO
+// (actor) accessed WHOSE (subject) vault and WHY (action + consent_ref), so a breach can be
+// scoped to affected individuals. NO PHI.
 interface AccessEventRow {
   id: string;
   actor_account_id: string;

package/adapters/d1/credentials.ts

@@ -99,8 +99,8 @@ export async function getCredential(db: D1Database, accountId: string, method: A
   return row ? mapCredential(row) : null;
 }
 
-// The account's key-bearing methods (password/passkey/recovery), for the account-settings screen and
-// the "don't orphan the vault key on remove" invariant. The credentials table is the source of truth (each
+// The account's key-bearing methods (password/passkey/recovery), for the Account screen and the
+// "don't orphan the vault key on remove" invariant. The credentials table is the source of truth (each
 // row independently wraps the same private key); identities lacks a recovery row.
 export async function listCredentials(db: D1Database, accountId: string): Promise<{ method: AuthMethod; createdAt: string }[]> {
   const { results } = await db

package/adapters/d1/index.ts

@@ -157,14 +157,14 @@ export class D1ProviderLinkStore implements ProviderLinkStore {
   get(id: string) {
     return providers.getProviderLink(this.db, id);
   }
-  listForPatient(patientAccountId: string) {
-    return providers.listProvidersForPatient(this.db, patientAccountId);
+  listForOwner(ownerAccountId: string) {
+    return providers.listProvidersForOwner(this.db, ownerAccountId);
   }
   listForProvider(providerAccountId: string) {
-    return providers.listPatientsForProvider(this.db, providerAccountId);
+    return providers.listOwnersForProvider(this.db, providerAccountId);
   }
-  getActive(patientAccountId: string, providerAccountId: string) {
-    return providers.getActiveProviderLink(this.db, patientAccountId, providerAccountId);
+  getActive(ownerAccountId: string, providerAccountId: string) {
+    return providers.getActiveProviderLink(this.db, ownerAccountId, providerAccountId);
   }
 }
 

package/adapters/d1/providers.ts

@@ -13,10 +13,14 @@ interface ProviderLinkRow {
   granted_at: string;
   expires_at: string | null;
 }
+// The `patient_account_id` column name is a legacy leftover from before this package's TS-facing
+// vocabulary was genericized to "owner" — renaming a live D1 column is a schema migration against
+// real production data, which that vocabulary cleanup had no reason to force. This mapping function
+// is the boundary that absorbs the difference; the TS-facing shape has never said "patient".
 function mapProviderLink(r: ProviderLinkRow): ProviderLink {
   return {
     id: r.id,
-    patientAccountId: r.patient_account_id,
+    ownerAccountId: r.patient_account_id,
     providerAccountId: r.provider_account_id,
     role: r.role,
     status: r.status,
@@ -30,7 +34,7 @@ function mapProviderLink(r: ProviderLinkRow): ProviderLink {
 export async function createProviderLink(
   db: D1Database,
   l: {
-    patientAccountId: string;
+    ownerAccountId: string;
     providerAccountId: string;
     role: ProviderKind;
     status?: LinkStatus;
@@ -49,11 +53,11 @@ export async function createProviderLink(
     .prepare(
       "INSERT INTO provider_links (id, patient_account_id, provider_account_id, role, status, consent_ref, granted_by, granted_at, expires_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)"
     )
-    .bind(id, l.patientAccountId, l.providerAccountId, l.role, status, consentRef, l.grantedBy, grantedAt, expiresAt)
+    .bind(id, l.ownerAccountId, l.providerAccountId, l.role, status, consentRef, l.grantedBy, grantedAt, expiresAt)
     .run();
   return {
     id,
-    patientAccountId: l.patientAccountId,
+    ownerAccountId: l.ownerAccountId,
     providerAccountId: l.providerAccountId,
     role: l.role,
     status,
@@ -85,15 +89,15 @@ export async function getProviderLink(db: D1Database, id: string): Promise<Provi
   return row ? mapProviderLink(row) : null;
 }
 
-export async function listProvidersForPatient(db: D1Database, patientAccountId: string): Promise<ProviderLink[]> {
+export async function listProvidersForOwner(db: D1Database, ownerAccountId: string): Promise<ProviderLink[]> {
   const { results } = await db
     .prepare("SELECT * FROM provider_links WHERE patient_account_id = ?")
-    .bind(patientAccountId)
+    .bind(ownerAccountId)
     .all<ProviderLinkRow>();
   return results.map(mapProviderLink);
 }
 
-export async function listPatientsForProvider(db: D1Database, providerAccountId: string): Promise<ProviderLink[]> {
+export async function listOwnersForProvider(db: D1Database, providerAccountId: string): Promise<ProviderLink[]> {
   const { results } = await db
     .prepare("SELECT * FROM provider_links WHERE provider_account_id = ?")
     .bind(providerAccountId)
@@ -103,15 +107,15 @@ export async function listPatientsForProvider(db: D1Database, providerAccountId:
 
 export async function getActiveProviderLink(
   db: D1Database,
-  patientAccountId: string,
+  ownerAccountId: string,
   providerAccountId: string
 ): Promise<ProviderLink | null> {
   const link = await db
     .prepare("SELECT * FROM provider_links WHERE patient_account_id = ? AND provider_account_id = ?")
-    .bind(patientAccountId, providerAccountId)
+    .bind(ownerAccountId, providerAccountId)
     .first<ProviderLinkRow>();
   if (!link || link.status !== "active") return null;
-  // `expires_at` is set on time-boxed support grants and null for clinician links.
+  // `expires_at` is set on time-boxed support grants and null for primary links.
   if (link.expires_at && Date.parse(link.expires_at) <= Date.now()) return null;
   return mapProviderLink(link);
 }

package/adapters/memory.ts

@@ -266,10 +266,10 @@ export class MemoryEnvelopeStore implements EnvelopeStore {
 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> {
+  async create(l: { ownerAccountId: 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,
+      ownerAccountId: l.ownerAccountId,
       providerAccountId: l.providerAccountId,
       role: l.role,
       status: l.status ?? "invited",
@@ -300,17 +300,17 @@ export class MemoryProviderLinkStore implements ProviderLinkStore {
     return l ? { ...l } : null;
   }
 
-  async listForPatient(patientAccountId: string): Promise<ProviderLink[]> {
-    return [...this.links.values()].filter((l) => l.patientAccountId === patientAccountId).map((l) => ({ ...l }));
+  async listForOwner(ownerAccountId: string): Promise<ProviderLink[]> {
+    return [...this.links.values()].filter((l) => l.ownerAccountId === ownerAccountId).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> {
+  async getActive(ownerAccountId: string, providerAccountId: string): Promise<ProviderLink | null> {
     const link = [...this.links.values()].find(
-      (l) => l.patientAccountId === patientAccountId && l.providerAccountId === providerAccountId
+      (l) => l.ownerAccountId === ownerAccountId && l.providerAccountId === providerAccountId
     );
     if (!link || link.status !== "active") return null;
     if (link.expiresAt && Date.parse(link.expiresAt) <= Date.now()) return null;

package/adapters/r2.ts

@@ -1,14 +1,13 @@
 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. An adopter's own Pages Function route should import R2Bucket/
-// R2BlobStore from here instead of declaring its own copy.
+// trivially mockable in tests.
 export interface R2ObjectBody {
   body: ReadableStream;
   /** The version token. Handed to the browser on GET and sent back as If-Match on PUT. */
   etag: string;
 }
-/** A precondition on a write. Verify this against real `workerd` in an adopter's own test suite — see ARCHITECTURE.md's "Adapters" section. */
+/** A precondition on a write. Real workerd conditional-write semantics are verified in an adopter's own test suite, not here — see CHANGELOG.md. */
 export interface R2Conditional {
   etagMatches?: string;
   etagDoesNotMatch?: string;
@@ -17,8 +16,8 @@ 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.
+   * Null-on-failure rather than a throw is observed behaviour against workerd, not an assumption —
+   * an adopter's own test suite is where this gets pinned; see CHANGELOG.md.
    */
   put(key: string, value: Uint8Array, options?: { onlyIf?: R2Conditional }): Promise<{ etag: string } | null>;
   delete(key: string): Promise<void>;