@tinytars/vault 0.1.17 → 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/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 Health Breach Notification Rule 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/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,
@@ -68,7 +72,7 @@ export async function updateProviderLinkStatus(db: D1Database, id: string, statu
   await db.prepare("UPDATE provider_links SET status = ? WHERE id = ?").bind(status, id).run();
 }
 
-// A patient approving a support request: flip the link active, stamp its time-box + consent.
+// An owner approving a support request: flip the link active, stamp its time-box + consent.
 export async function grantSupportLink(
   db: D1Database,
   id: string,
@@ -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/auth-client.ts

@@ -20,6 +20,7 @@ import type {
   PublicKeyCredentialRequestOptionsJSON,
 } from "@simplewebauthn/browser";
 import { bytesToB64 as bytesToBase64, b64ToBytes as base64ToBytes } from "./base64";
+import type { ProviderKind } from "./stores";
 export { bytesToB64 as bytesToBase64, b64ToBytes as base64ToBytes } from "./base64";
 
 export const KDF_ITERATIONS = 200_000;
@@ -42,7 +43,7 @@ export function hexToBytes(hex: string): Uint8Array {
  *
  * Nearly every branch below threw `${what} failed: ${res.status}`, discarding a message the
  * endpoint had already composed for exactly this moment ("that recovery code has expired", "this
- * clinician already has access", "no access to this vault") and showing a patient a bare number
+ * provider already has access", "no access to this vault") and showing an owner a bare number
  * instead. These are the paths a person is on during the worst day they will have with this app, and
  * a status code tells them nothing about whether to retry, wait, or ask someone.
  *
@@ -327,7 +328,7 @@ export async function resumeSession(): Promise<{
   vaultId: string | null;
   r2Key: string | null;
   rotationPending: boolean;
-  providerKind: "clinician" | "support" | null;
+  providerKind: ProviderKind | null;
   ownerEnvelope: { wrappedDEK: string; ephemeralPublicKeyJwk: JsonWebKey } | null;
 } | null> {
   const res = await fetch("/api/auth/session/resume", { cache: "no-store" });
@@ -350,7 +351,7 @@ export async function addGoogleMethod(privateKey: CryptoKey, currentPassword?: s
   if (!res.ok) throw new Error((await res.json().catch(() => ({}))).error || `add google failed: ${res.status}`);
 }
 
-export async function getMyAccount(): Promise<{ id: string; email: string | null; emailConfirmed: boolean; displayName: string; providerKind: "clinician" | "support" | null; unitSystem: "metric" | "imperial" | null }> {
+export async function getMyAccount(): Promise<{ id: string; email: string | null; emailConfirmed: boolean; displayName: string; providerKind: ProviderKind | null; unitSystem: "metric" | "imperial" | null }> {
   const res = await fetch("/api/account", { cache: "no-store" });
   if (!res.ok) throw await failed(res, "account fetch failed");
   return res.json();

package/auth-grants.ts

@@ -1,7 +1,8 @@
 import { wrapDEKForPublicKey } from "./crypto";
 import { bytesToBase64, failed } from "./auth-client";
+import type { ProviderKind } from "./stores";
 
-// Provider escrow (patient side). A logged-in patient grants a provider access by wrapping
+// Provider escrow (owner side). A logged-in owner grants a provider access by wrapping
 // their in-memory DEK to the provider's public key client-side and posting the opaque envelope; the
 // server never sees a plaintext DEK. Revoke deletes the envelope + marks the link revoked.
 
@@ -9,7 +10,7 @@ export interface ProviderLinkView {
   linkId: string;
   providerAccountId: string;
   displayName: string;
-  kind: "clinician" | "support";
+  kind: ProviderKind;
   status: "invited" | "active" | "revoked";
   expiresAt: string | null;
   publicKeyJwk?: JsonWebKey | null; // present only for a pending (invited) support request

package/auth-recovery.ts

@@ -162,7 +162,7 @@ export async function recoverAccount(
 // Regenerate the recovery code (owner session): re-wrap the in-memory private key under a fresh code +
 // store the verifier. Returns the new code to display once.
 // ── Provider-issued recovery ──────────────────────────────────────────────────
-// Apple's recovery-contact model: a clinician who already holds the patient's DEK re-wraps it under a
+// Apple's recovery-contact model: a provider who already holds the owner's DEK re-wraps it under a
 // one-time code and READS THE CODE TO THEM. It is never emailed — see RECOVERY.md I2; the server would
 // have to be given the code, and it already holds the wrapped DEK.
 
@@ -191,11 +191,11 @@ export function detectRecoveryKind(raw: string): "code" | "grant" {
 }
 
 /**
- * Clinician side. Unwraps the patient's DEK with the clinician's own key — which is what provider
+ * Provider side. Unwraps the owner's DEK with the provider's own key — which is what provider
  * access already is — and re-wraps it under the code. Returns the code to display once.
  */
 export async function issueRecoveryCode(
-  patientAccountId: string,
+  ownerAccountId: string,
   envelope: { wrappedDEK: string; ephemeralPublicKeyJwk: JsonWebKey },
   providerKey: CryptoKey,
 ): Promise<{ code: string; expiresAt: string }> {
@@ -207,7 +207,7 @@ export async function issueRecoveryCode(
     method: "POST",
     headers: { "content-type": "application/json" },
     body: JSON.stringify({
-      patientAccountId,
+      ownerAccountId,
       wrappedDek: bytesToBase64(await wrapDEKWithKek(dek, await deriveKekFromPassword(normalized, salt))),
       kdfParams: { salt: bytesToHex(salt), iterations: KDF_ITERATIONS },
       codeAuthHash: await deriveAuthHash(normalized, salt),
@@ -218,12 +218,12 @@ export async function issueRecoveryCode(
 }
 
 /**
- * Patient side. Two calls against the same endpoint: the first proves the code and returns the wrapped
+ * Owner side. Two calls against the same endpoint: the first proves the code and returns the wrapped
  * DEK, the second installs a brand-new keypair locked under the new password. The code is proved on
  * both — the second is not authorised by the first having happened.
  *
  * Unlike `recoverAccount`, this MINTS A NEW KEYPAIR rather than re-wrapping the old one, because the
- * old private key is exactly what the patient no longer has. That is why the server clears the other
+ * old private key is exactly what the owner no longer has. That is why the server clears the other
  * credentials: they wrap a key nothing references any more.
  */
 export async function redeemRecoveryCode(

package/auth-support.ts

@@ -1,10 +1,10 @@
 import { wrapDEKForPublicKey } from "./crypto";
 import { bytesToBase64, failed } from "./auth-client";
 
-// Support consented-access. A patient approves a pending support request by wrapping their
+// Support consented-access. A vault owner approves a pending support request by wrapping their
 // in-memory DEK to the support agent's public key (time-boxed); support enters via an audited endpoint.
 
-// Patient side — approve a pending support request (linkId + the agent's publicKeyJwk from GET /api/providers).
+// Owner side — approve a pending support request (linkId + the agent's publicKeyJwk from GET /api/providers).
 export async function approveSupport(linkId: string, dek: CryptoKey, publicKeyJwk: JsonWebKey, ttlHours: number): Promise<void> {
   const env = await wrapDEKForPublicKey(dek, publicKeyJwk);
   const res = await fetch("/api/support/approve", {
@@ -16,30 +16,30 @@ export async function approveSupport(linkId: string, dek: CryptoKey, publicKeyJw
 }
 
 // Support side.
-export interface SupportPatient {
-  patientAccountId: string;
+export interface SupportOwner {
+  ownerAccountId: string;
   displayName: string;
   expiresAt: string | null;
 }
 
-export async function requestSupportAccess(patientEmail: string): Promise<void> {
+export async function requestSupportAccess(ownerEmail: string): Promise<void> {
   const res = await fetch("/api/support/request", {
     method: "POST",
     headers: { "content-type": "application/json" },
-    body: JSON.stringify({ patientEmail }),
+    body: JSON.stringify({ ownerEmail }),
   });
   if (!res.ok) throw await failed(res, "request failed");
 }
 
-export async function listSupportPatients(): Promise<SupportPatient[]> {
-  const res = await fetch("/api/support/patients", { cache: "no-store" });
-  if (!res.ok) throw await failed(res, "support patients failed");
-  return ((await res.json()) as { patients: SupportPatient[] }).patients;
+export async function listSupportOwners(): Promise<SupportOwner[]> {
+  const res = await fetch("/api/support/owners", { cache: "no-store" });
+  if (!res.ok) throw await failed(res, "support owners failed");
+  return ((await res.json()) as { owners: SupportOwner[] }).owners;
 }
 
-// Enter a patient (audited server-side); returns the envelope for client-side DEK unwrap.
-export async function enterSupportPatient(patientAccountId: string): Promise<{
-  patientAccountId: string;
+// Enter an owner's vault (audited server-side); returns the envelope for client-side DEK unwrap.
+export async function enterSupportOwner(ownerAccountId: string): Promise<{
+  ownerAccountId: string;
   displayName: string;
   email: string | null;
   vaultId: string;
@@ -49,15 +49,15 @@ export async function enterSupportPatient(patientAccountId: string): Promise<{
   const res = await fetch("/api/support/access", {
     method: "POST",
     headers: { "content-type": "application/json" },
-    body: JSON.stringify({ patientAccountId }),
+    body: JSON.stringify({ ownerAccountId }),
   });
   if (!res.ok) throw await failed(res, "support access failed");
   return res.json();
 }
 
-// Support→provider roster access. A support agent can request access to a clinician too (same
-// /api/support/request, which classifies by the target's kind). The clinician approves (metadata only,
-// no DEK), then support sees the clinician's roster and can open the patients who separately consented.
+// Support→provider roster access. A support agent can request access to a primary provider too (same
+// /api/support/request, which classifies by the target's kind). The primary provider approves (metadata
+// only, no DEK), then support sees their roster and can open the owners who separately consented.
 
 export interface SupportProvider {
   linkId: string;
@@ -67,8 +67,8 @@ export interface SupportProvider {
   expiresAt: string | null;
 }
 
-export interface SupportRosterPatient {
-  patientAccountId: string;
+export interface SupportRosterOwner {
+  ownerAccountId: string;
   displayName: string;
   email: string | null;
   openable: boolean;
@@ -80,7 +80,7 @@ export interface SupportRequest {
   targetAccountId: string;
   displayName: string;
   email: string | null;
-  kind: "patient" | "provider";
+  kind: "owner" | "provider";
 }
 
 // Provider side — approve a pending support roster request (no DEK; a provider owns no vault).
@@ -99,10 +99,10 @@ export async function listSupportProviders(): Promise<SupportProvider[]> {
   return ((await res.json()) as { providers: SupportProvider[] }).providers;
 }
 
-export async function getProviderRoster(providerId: string): Promise<SupportRosterPatient[]> {
+export async function getProviderRoster(providerId: string): Promise<SupportRosterOwner[]> {
   const res = await fetch(`/api/support/provider-roster?providerId=${encodeURIComponent(providerId)}`, { cache: "no-store" });
   if (!res.ok) throw await failed(res, "provider roster failed");
-  return ((await res.json()) as { roster: SupportRosterPatient[] }).roster;
+  return ((await res.json()) as { roster: SupportRosterOwner[] }).roster;
 }
 
 export async function listSupportRequests(): Promise<SupportRequest[]> {

package/break-glass.ts

@@ -26,7 +26,7 @@ export interface BreakGlassGrantStores {
 
 /**
  * Approves a pending support-role link: validates it's the approver's own pending request, clamps the
- * requested TTL, stamps a consent ref, optionally writes an envelope (patient approvals only — a
+ * requested TTL, stamps a consent ref, optionally writes an envelope (owner approvals only — a
  * provider approving a roster request owns nothing encrypted), flips the link active, and audits.
  */
 export async function grantBreakGlass(
@@ -43,7 +43,7 @@ export async function grantBreakGlass(
   }
 ): Promise<BreakGlassGrantResult> {
   const link = await stores.links.get(opts.linkId);
-  if (!link || link.patientAccountId !== opts.approverAccountId || link.role !== "support" || link.status !== "invited") {
+  if (!link || link.ownerAccountId !== opts.approverAccountId || link.role !== "support" || link.status !== "invited") {
     return { ok: false, error: "no_pending_link" };
   }
 
@@ -124,10 +124,10 @@ export interface BreakGlassRevokeStores {
 }
 
 /**
- * Ends a link early — either side may call this (the patient revoking, or the provider dropping it).
+ * Ends a link early — either side may call this (the owner revoking, or the provider dropping it).
  * Deletes the provider's envelope (if any) so no new read can unwrap the DEK, and marks the link
  * revoked. Idempotent: a second call re-deletes (no-op) and re-marks revoked (no-op); `auditAction` is
- * omitted for link kinds that don't carry a disclosure-audit obligation (clinician links).
+ * omitted for link kinds that don't carry a disclosure-audit obligation (primary links).
  */
 export async function revokeBreakGlass(
   stores: BreakGlassRevokeStores,

package/envelope-access.ts

@@ -8,7 +8,7 @@ export interface EnvelopeAccessSource {
   getVault(vaultId: string): Promise<VaultRow | null>;
 }
 export interface ProviderLinkSource {
-  getActive(patientAccountId: string, providerAccountId: string): Promise<ProviderLink | null>;
+  getActive(ownerAccountId: string, providerAccountId: string): Promise<ProviderLink | null>;
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tinytars/vault",
-  "version": "0.1.17",
+  "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",

package/stores.ts

@@ -6,7 +6,7 @@
 
 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";
 
@@ -74,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;
@@ -159,7 +159,7 @@ export interface EnvelopeStore {
 
 export interface ProviderLinkStore {
   create(l: {
-    patientAccountId: string;
+    ownerAccountId: string;
     providerAccountId: string;
     role: ProviderKind;
     status?: LinkStatus;
@@ -171,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

@@ -6,7 +6,7 @@ import { decryptVaultV2 } from "./crypto";
  * agree by coincidence.
  */
 export interface VaultEntry {
-  patientAccountId: string;
+  ownerAccountId: string;
   displayName: string;
   email: string | null;
   r2Key: string;
@@ -23,7 +23,7 @@ export interface VaultSession {
    * 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. */
+  /** 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;
@@ -37,8 +37,8 @@ export interface VaultSession {
   /**
    * 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
+   * 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;
@@ -48,7 +48,7 @@ export interface VaultSession {
 
 /**
  * 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
+ * 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.
  */