@tinytars/vault 0.1.4

package/adapters/d1/accounts.ts

@@ -0,0 +1,160 @@
+import type { D1Database } from "./types";
+import type { Account, LifecycleStage, ProviderKind, UnitSystem } from "../../stores";
+export type { Account };
+
+interface AccountRow {
+  id: string;
+  email: string | null;
+  email_confirmed: number;
+  display_name: string;
+  lifecycle_stage: LifecycleStage;
+  provider_kind: ProviderKind | null;
+  unit_system: UnitSystem | null;
+  created_at: string;
+  deleted_at?: string | null;
+  email_changed_at?: string | null;
+}
+function mapAccount(r: AccountRow): Account {
+  return {
+    id: r.id,
+    email: r.email,
+    emailConfirmed: r.email_confirmed === 1,
+    displayName: r.display_name,
+    lifecycleStage: r.lifecycle_stage,
+    providerKind: r.provider_kind,
+    unitSystem: r.unit_system,
+    createdAt: r.created_at,
+    deletedAt: r.deleted_at ?? null,
+    emailChangedAt: r.email_changed_at ?? null,
+  };
+}
+
+export async function createAccount(
+  db: D1Database,
+  a: { id: string; displayName: string; email?: string | null; lifecycleStage?: LifecycleStage; providerKind?: ProviderKind | null }
+): Promise<Account> {
+  const createdAt = new Date().toISOString();
+  const email = a.email ?? null;
+  const lifecycleStage = a.lifecycleStage ?? "active";
+  const providerKind = a.providerKind ?? null;
+  await db
+    .prepare(
+      "INSERT INTO accounts (id, email, email_confirmed, display_name, lifecycle_stage, provider_kind, created_at) VALUES (?, ?, 0, ?, ?, ?, ?)"
+    )
+    .bind(a.id, email, a.displayName, lifecycleStage, providerKind, createdAt)
+    .run();
+  return {
+    id: a.id,
+    email,
+    emailConfirmed: false,
+    displayName: a.displayName,
+    lifecycleStage,
+    providerKind,
+    unitSystem: null,
+    createdAt,
+    deletedAt: null,
+    emailChangedAt: null,
+  };
+}
+
+export async function getAccount(db: D1Database, id: string): Promise<Account | null> {
+  const row = await db.prepare("SELECT * FROM accounts WHERE id = ?").bind(id).first<AccountRow>();
+  return row ? mapAccount(row) : null;
+}
+
+export async function getAccountByEmail(db: D1Database, email: string): Promise<Account | null> {
+  const row = await db.prepare("SELECT * FROM accounts WHERE email = ?").bind(email).first<AccountRow>();
+  return row ? mapAccount(row) : null;
+}
+
+/**
+ * The instant before which this account's session cookies are no longer accepted, or null.
+ *
+ * W71 — 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.
+ */
+export async function sessionsValidFrom(db: D1Database, accountId: string): Promise<number | null> {
+  const row = await db.prepare("SELECT sessions_valid_from FROM accounts WHERE id = ?").bind(accountId).first<{ sessions_valid_from: string | null }>();
+  // A cookie for an account that no longer exists is not merely un-revoked, it is unusable. Returning
+  // Infinity rather than null makes deletion revoke by construction instead of by omission.
+  if (!row) return Number.POSITIVE_INFINITY;
+  return row.sessions_valid_from ? Math.floor(Date.parse(row.sessions_valid_from) / 1000) : null;
+}
+
+/**
+ * Invalidates every session cookie already issued for this account.
+ *
+ * Called on logout and after any change to how the account is authenticated — a replaced password, a
+ * removed passkey, a changed email. Those were the mutations that made a stolen cookie permanent:
+ * they changed the credential and left every existing session running.
+ *
+ * Truncated to the second, and the rule is `iat >= validFrom`, so a cookie minted in the SAME second
+ * as the revocation survives. That window is deliberate and cannot be closed without a per-session
+ * id: the cookie's `iat` has one-second resolution, so a cookie minted just before the revocation and
+ * one minted just after — by the login that immediately follows a logout — are indistinguishable.
+ * Rounding the other way would reject the new session instead, which trades a one-second exposure for
+ * a user who cannot log back in.
+ */
+export async function revokeSessions(db: D1Database, accountId: string): Promise<void> {
+  await db
+    .prepare("UPDATE accounts SET sessions_valid_from = ? WHERE id = ?")
+    .bind(new Date(Math.floor(Date.now() / 1000) * 1000).toISOString(), accountId)
+    .run();
+}
+
+export async function setEmailConfirmed(db: D1Database, id: string, confirmed: boolean): Promise<void> {
+  await db.prepare("UPDATE accounts SET email_confirmed = ? WHERE id = ?").bind(confirmed ? 1 : 0, id).run();
+}
+
+export async function setLifecycleStage(db: D1Database, id: string, stage: LifecycleStage): Promise<void> {
+  await db.prepare("UPDATE accounts SET lifecycle_stage = ? WHERE id = ?").bind(stage, id).run();
+}
+
+export async function updateAccountProfile(
+  db: D1Database,
+  id: string,
+  updates: { email?: string | null; displayName?: string; unitSystem?: UnitSystem | null }
+): Promise<void> {
+  const sets: string[] = [];
+  const values: unknown[] = [];
+  if (updates.email !== undefined) {
+    sets.push("email = ?");
+    values.push(updates.email);
+  }
+  if (updates.displayName !== undefined) {
+    sets.push("display_name = ?");
+    values.push(updates.displayName);
+  }
+  if (updates.unitSystem !== undefined) {
+    sets.push("unit_system = ?");
+    values.push(updates.unitSystem);
+  }
+  if (sets.length === 0) return;
+  values.push(id);
+  await db.prepare(`UPDATE accounts SET ${sets.join(", ")} WHERE id = ?`).bind(...values).run();
+}
+
+/**
+ * Nulls every personal field and stamps `deleted_at`, leaving an opaque row behind. See the migration
+ * for why the row survives at all.
+ */
+export async function tombstoneAccount(db: D1Database, accountId: string, at: string): Promise<void> {
+  await db
+    .prepare(
+      "UPDATE accounts SET email = NULL, email_confirmed = 0, display_name = '', lifecycle_stage = 'churned', provider_kind = NULL, unit_system = NULL, deleted_at = ? WHERE id = ?",
+    )
+    .bind(at, accountId)
+    .run();
+}
+
+/**
+ * W73 — stamps when the account's email address changed.
+ *
+ * Read by the recovery routes, which refuse to issue a grant while the address is still new: a stolen
+ * cookie that repoints the mailbox should not be able to convert that into a recovery code minutes
+ * later. See RECOVERY.md and migrations/0009.
+ */
+export async function markEmailChanged(db: D1Database, accountId: string, at: string): Promise<void> {
+  await db.prepare("UPDATE accounts SET email_changed_at = ? WHERE id = ?").bind(at, accountId).run();
+}

package/adapters/d1/audit.ts

@@ -0,0 +1,58 @@
+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).
+
+// W44 P4b — 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.
+interface AccessEventRow {
+  id: string;
+  actor_account_id: string;
+  subject_account_id: string;
+  vault_id: string | null;
+  action: string;
+  consent_ref: string | null;
+  meta: string;
+  created_at: string;
+}
+function mapAccessEvent(r: AccessEventRow): AccessEvent {
+  return {
+    id: r.id,
+    actorAccountId: r.actor_account_id,
+    subjectAccountId: r.subject_account_id,
+    vaultId: r.vault_id,
+    action: r.action,
+    consentRef: r.consent_ref,
+    meta: JSON.parse(r.meta),
+    createdAt: r.created_at,
+  };
+}
+
+export async function insertAccessEvent(
+  db: D1Database,
+  e: { actorAccountId: string; subjectAccountId: string; vaultId?: string | null; action: string; consentRef?: string | null; meta?: unknown; id?: string }
+): Promise<AccessEvent> {
+  const id = e.id ?? crypto.randomUUID();
+  const vaultId = e.vaultId ?? null;
+  const consentRef = e.consentRef ?? null;
+  const meta = e.meta ?? {};
+  const createdAt = new Date().toISOString();
+  await db
+    .prepare(
+      "INSERT INTO phi_access_events (id, actor_account_id, subject_account_id, vault_id, action, consent_ref, meta, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)"
+    )
+    .bind(id, e.actorAccountId, e.subjectAccountId, vaultId, e.action, consentRef, JSON.stringify(meta), createdAt)
+    .run();
+  return { id, actorAccountId: e.actorAccountId, subjectAccountId: e.subjectAccountId, vaultId, action: e.action, consentRef, meta, createdAt };
+}
+
+export async function listAccessEventsForSubject(db: D1Database, subjectAccountId: string): Promise<AccessEvent[]> {
+  const { results } = await db
+    .prepare("SELECT * FROM phi_access_events WHERE subject_account_id = ? ORDER BY created_at")
+    .bind(subjectAccountId)
+    .all<AccessEventRow>();
+  return results.map(mapAccessEvent);
+}

package/adapters/d1/credentials.ts

@@ -0,0 +1,154 @@
+import type { D1Database } from "./types";
+import { toBytes } from "./types";
+import type { AuthMethod, Identity, Credential, PublicKey } from "../../stores";
+export type { Identity, Credential, PublicKey };
+
+interface IdentityRow {
+  id: string;
+  account_id: string;
+  method: AuthMethod;
+  provider_subject: string | null;
+  credential_id: string | null;
+  created_at: string;
+}
+function mapIdentity(r: IdentityRow): Identity {
+  return {
+    id: r.id,
+    accountId: r.account_id,
+    method: r.method,
+    providerSubject: r.provider_subject,
+    credentialId: r.credential_id,
+    createdAt: r.created_at,
+  };
+}
+
+export async function addIdentity(
+  db: D1Database,
+  i: { accountId: string; method: AuthMethod; providerSubject?: string | null; credentialId?: string | null; id?: string }
+): Promise<Identity> {
+  const id = i.id ?? crypto.randomUUID();
+  const createdAt = new Date().toISOString();
+  const providerSubject = i.providerSubject ?? null;
+  const credentialId = i.credentialId ?? null;
+  await db
+    .prepare(
+      "INSERT INTO identities (id, account_id, method, provider_subject, credential_id, created_at) VALUES (?, ?, ?, ?, ?, ?)"
+    )
+    .bind(id, i.accountId, i.method, providerSubject, credentialId, createdAt)
+    .run();
+  return { id, accountId: i.accountId, method: i.method, providerSubject, credentialId, createdAt };
+}
+
+export async function getIdentityByProviderSubject(
+  db: D1Database,
+  method: AuthMethod,
+  subject: string
+): Promise<Identity | null> {
+  const row = await db
+    .prepare("SELECT * FROM identities WHERE method = ? AND provider_subject = ?")
+    .bind(method, subject)
+    .first<IdentityRow>();
+  return row ? mapIdentity(row) : null;
+}
+
+export async function getIdentityByCredentialId(db: D1Database, credentialId: string): Promise<Identity | null> {
+  const row = await db.prepare("SELECT * FROM identities WHERE credential_id = ?").bind(credentialId).first<IdentityRow>();
+  return row ? mapIdentity(row) : null;
+}
+
+export async function listIdentities(db: D1Database, accountId: string): Promise<Identity[]> {
+  const { results } = await db.prepare("SELECT * FROM identities WHERE account_id = ?").bind(accountId).all<IdentityRow>();
+  return results.map(mapIdentity);
+}
+
+interface CredentialRow {
+  account_id: string;
+  method: AuthMethod;
+  wrapped_private_key: unknown;
+  kdf_params: string;
+  created_at: string;
+}
+function mapCredential(r: CredentialRow): Credential {
+  return {
+    accountId: r.account_id,
+    method: r.method,
+    wrappedPrivateKey: toBytes(r.wrapped_private_key),
+    kdfParams: JSON.parse(r.kdf_params),
+    createdAt: r.created_at,
+  };
+}
+
+export async function putCredential(
+  db: D1Database,
+  c: { accountId: string; method: AuthMethod; wrappedPrivateKey: Uint8Array; kdfParams: unknown }
+): Promise<void> {
+  const createdAt = new Date().toISOString();
+  await db
+    .prepare(
+      "INSERT OR REPLACE INTO credentials (account_id, method, wrapped_private_key, kdf_params, created_at) VALUES (?, ?, ?, ?, ?)"
+    )
+    .bind(c.accountId, c.method, c.wrappedPrivateKey, JSON.stringify(c.kdfParams), createdAt)
+    .run();
+}
+
+export async function getCredential(db: D1Database, accountId: string, method: AuthMethod): Promise<Credential | null> {
+  const row = await db
+    .prepare("SELECT * FROM credentials WHERE account_id = ? AND method = ?")
+    .bind(accountId, method)
+    .first<CredentialRow>();
+  return row ? mapCredential(row) : null;
+}
+
+// W44 P8 — 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
+    .prepare("SELECT method, created_at FROM credentials WHERE account_id = ?")
+    .bind(accountId)
+    .all<{ method: AuthMethod; created_at: string }>();
+  return results.map((r) => ({ method: r.method, createdAt: r.created_at }));
+}
+
+export async function deleteCredential(db: D1Database, accountId: string, method: AuthMethod): Promise<void> {
+  await db.prepare("DELETE FROM credentials WHERE account_id = ? AND method = ?").bind(accountId, method).run();
+}
+
+export async function deleteIdentity(db: D1Database, accountId: string, method: AuthMethod): Promise<void> {
+  await db.prepare("DELETE FROM identities WHERE account_id = ? AND method = ?").bind(accountId, method).run();
+}
+
+// W44 P3 — bump the passkey authenticator's signature counter after a successful login
+// (replay-attack detection). Merges into the existing kdf_params rather than a raw column
+// update so the wrapped key row stays a single INSERT OR REPLACE-shaped record.
+export async function updatePasskeyCounter(db: D1Database, accountId: string, counter: number): Promise<void> {
+  const cred = await getCredential(db, accountId, "passkey");
+  if (!cred) return;
+  const kdfParams = { ...(cred.kdfParams as Record<string, unknown>), counter };
+  await db
+    .prepare("UPDATE credentials SET kdf_params = ? WHERE account_id = ? AND method = 'passkey'")
+    .bind(JSON.stringify(kdfParams), accountId)
+    .run();
+}
+
+interface PublicKeyRow {
+  account_id: string;
+  public_key_jwk: string;
+  created_at: string;
+}
+function mapPublicKey(r: PublicKeyRow): PublicKey {
+  return { accountId: r.account_id, publicKeyJwk: JSON.parse(r.public_key_jwk), createdAt: r.created_at };
+}
+
+export async function putPublicKey(db: D1Database, p: { accountId: string; publicKeyJwk: unknown }): Promise<void> {
+  const createdAt = new Date().toISOString();
+  await db
+    .prepare("INSERT OR REPLACE INTO public_keys (account_id, public_key_jwk, created_at) VALUES (?, ?, ?)")
+    .bind(p.accountId, JSON.stringify(p.publicKeyJwk), createdAt)
+    .run();
+}
+
+export async function getPublicKey(db: D1Database, accountId: string): Promise<PublicKey | null> {
+  const row = await db.prepare("SELECT * FROM public_keys WHERE account_id = ?").bind(accountId).first<PublicKeyRow>();
+  return row ? mapPublicKey(row) : null;
+}

package/adapters/d1/index.ts

@@ -0,0 +1,179 @@
+// D1 implementations of the storage-agnostic contracts in ../../stores.ts. Each method is a
+// one-line delegation to the corresponding module in this directory — this file wires the portable
+// interfaces to a D1 schema, and carries no logic of its own.
+
+import type { D1Database } from "./types";
+import type {
+  AccountStore,
+  CredentialStore,
+  EnvelopeStore,
+  ProviderLinkStore,
+  AuditStore,
+  EnvelopeInput,
+} from "../../stores";
+
+import * as accounts from "./accounts";
+import * as credentials from "./credentials";
+import * as vault from "./vault";
+import * as providers from "./providers";
+import * as audit from "./audit";
+
+export type { D1Database, D1PreparedStatement, toBytes } from "./types";
+
+export class D1AccountStore implements AccountStore {
+  constructor(private db: D1Database) {}
+  create(a: Parameters<AccountStore["create"]>[0]) {
+    return accounts.createAccount(this.db, a);
+  }
+  get(id: string) {
+    return accounts.getAccount(this.db, id);
+  }
+  getByEmail(email: string) {
+    return accounts.getAccountByEmail(this.db, email);
+  }
+  sessionsValidFrom(accountId: string) {
+    return accounts.sessionsValidFrom(this.db, accountId);
+  }
+  revokeSessions(accountId: string) {
+    return accounts.revokeSessions(this.db, accountId);
+  }
+  setEmailConfirmed(id: string, confirmed: boolean) {
+    return accounts.setEmailConfirmed(this.db, id, confirmed);
+  }
+  setLifecycleStage(id: string, stage: Parameters<AccountStore["setLifecycleStage"]>[1]) {
+    return accounts.setLifecycleStage(this.db, id, stage);
+  }
+  updateProfile(id: string, updates: Parameters<AccountStore["updateProfile"]>[1]) {
+    return accounts.updateAccountProfile(this.db, id, updates);
+  }
+  tombstone(accountId: string, at: string) {
+    return accounts.tombstoneAccount(this.db, accountId, at);
+  }
+  markEmailChanged(accountId: string, at: string) {
+    return accounts.markEmailChanged(this.db, accountId, at);
+  }
+}
+
+export class D1CredentialStore implements CredentialStore {
+  constructor(private db: D1Database) {}
+  addIdentity(i: Parameters<CredentialStore["addIdentity"]>[0]) {
+    return credentials.addIdentity(this.db, i);
+  }
+  getIdentityByProviderSubject(method: Parameters<CredentialStore["getIdentityByProviderSubject"]>[0], subject: string) {
+    return credentials.getIdentityByProviderSubject(this.db, method, subject);
+  }
+  getIdentityByCredentialId(credentialId: string) {
+    return credentials.getIdentityByCredentialId(this.db, credentialId);
+  }
+  listIdentities(accountId: string) {
+    return credentials.listIdentities(this.db, accountId);
+  }
+  deleteIdentity(accountId: string, method: Parameters<CredentialStore["deleteIdentity"]>[1]) {
+    return credentials.deleteIdentity(this.db, accountId, method);
+  }
+  putCredential(c: Parameters<CredentialStore["putCredential"]>[0]) {
+    return credentials.putCredential(this.db, c);
+  }
+  getCredential(accountId: string, method: Parameters<CredentialStore["getCredential"]>[1]) {
+    return credentials.getCredential(this.db, accountId, method);
+  }
+  listCredentials(accountId: string) {
+    return credentials.listCredentials(this.db, accountId);
+  }
+  deleteCredential(accountId: string, method: Parameters<CredentialStore["deleteCredential"]>[1]) {
+    return credentials.deleteCredential(this.db, accountId, method);
+  }
+  updatePasskeyCounter(accountId: string, counter: number) {
+    return credentials.updatePasskeyCounter(this.db, accountId, counter);
+  }
+  putPublicKey(p: Parameters<CredentialStore["putPublicKey"]>[0]) {
+    return credentials.putPublicKey(this.db, p);
+  }
+  getPublicKey(accountId: string) {
+    return credentials.getPublicKey(this.db, accountId);
+  }
+}
+
+export class D1EnvelopeStore implements EnvelopeStore {
+  constructor(private db: D1Database) {}
+  createVault(v: Parameters<EnvelopeStore["createVault"]>[0]) {
+    return vault.createVault(this.db, v);
+  }
+  getVault(vaultId: string) {
+    return vault.getVault(this.db, vaultId);
+  }
+  getVaultByR2Key(r2Key: string) {
+    return vault.getVaultByR2Key(this.db, r2Key);
+  }
+  getVaultByStagingR2Key(r2Key: string) {
+    return vault.getVaultByStagingR2Key(this.db, r2Key);
+  }
+  listVaultsForOwner(ownerAccountId: string) {
+    return vault.listVaultsForOwner(this.db, ownerAccountId);
+  }
+  setRotationPending(vaultId: string, pending: boolean) {
+    return vault.setRotationPending(this.db, vaultId, pending);
+  }
+  setRotationStaging(vaultId: string, r2Key: string | null) {
+    return vault.setRotationStaging(this.db, vaultId, r2Key);
+  }
+  setOrgRecoveryRevoked(vaultId: string, at: string | null) {
+    return vault.setOrgRecoveryRevoked(this.db, vaultId, at);
+  }
+  putEnvelope(e: Parameters<EnvelopeStore["putEnvelope"]>[0]) {
+    return vault.putEnvelope(this.db, e);
+  }
+  replaceEnvelopes(vaultId: string, envelopes: EnvelopeInput[], createdBy: string) {
+    return vault.replaceEnvelopes(this.db, vaultId, envelopes, createdBy);
+  }
+  commitRotation(vaultId: string, newR2Key: string, envelopes: EnvelopeInput[], createdBy: string) {
+    return vault.commitRotation(this.db, vaultId, newR2Key, envelopes, createdBy);
+  }
+  getEnvelopeRow(vaultId: string, principalAccountId: string) {
+    return vault.getEnvelopeRow(this.db, vaultId, principalAccountId);
+  }
+  listEnvelopesForVault(vaultId: string) {
+    return vault.listEnvelopesForVault(this.db, vaultId);
+  }
+  listEnvelopesForPrincipal(principalAccountId: string) {
+    return vault.listEnvelopesForPrincipal(this.db, principalAccountId);
+  }
+  deleteEnvelope(vaultId: string, principalAccountId: string) {
+    return vault.deleteEnvelope(this.db, vaultId, principalAccountId);
+  }
+}
+
+export class D1ProviderLinkStore implements ProviderLinkStore {
+  constructor(private db: D1Database) {}
+  create(l: Parameters<ProviderLinkStore["create"]>[0]) {
+    return providers.createProviderLink(this.db, l);
+  }
+  updateStatus(id: string, status: Parameters<ProviderLinkStore["updateStatus"]>[1]) {
+    return providers.updateProviderLinkStatus(this.db, id, status);
+  }
+  grantSupport(id: string, opts: Parameters<ProviderLinkStore["grantSupport"]>[1]) {
+    return providers.grantSupportLink(this.db, id, opts);
+  }
+  get(id: string) {
+    return providers.getProviderLink(this.db, id);
+  }
+  listForPatient(patientAccountId: string) {
+    return providers.listProvidersForPatient(this.db, patientAccountId);
+  }
+  listForProvider(providerAccountId: string) {
+    return providers.listPatientsForProvider(this.db, providerAccountId);
+  }
+  getActive(patientAccountId: string, providerAccountId: string) {
+    return providers.getActiveProviderLink(this.db, patientAccountId, providerAccountId);
+  }
+}
+
+export class D1AuditStore implements AuditStore {
+  constructor(private db: D1Database) {}
+  insertAccessEvent(e: Parameters<AuditStore["insertAccessEvent"]>[0]) {
+    return audit.insertAccessEvent(this.db, e);
+  }
+  listAccessEventsForSubject(subjectAccountId: string) {
+    return audit.listAccessEventsForSubject(this.db, subjectAccountId);
+  }
+}

package/adapters/d1/providers.ts

@@ -0,0 +1,117 @@
+import type { D1Database } from "./types";
+import type { ProviderKind, LinkStatus, ProviderLink } from "../../stores";
+export type { ProviderLink };
+
+interface ProviderLinkRow {
+  id: string;
+  patient_account_id: string;
+  provider_account_id: string;
+  role: ProviderKind;
+  status: LinkStatus;
+  consent_ref: string | null;
+  granted_by: string;
+  granted_at: string;
+  expires_at: string | null;
+}
+function mapProviderLink(r: ProviderLinkRow): ProviderLink {
+  return {
+    id: r.id,
+    patientAccountId: r.patient_account_id,
+    providerAccountId: r.provider_account_id,
+    role: r.role,
+    status: r.status,
+    consentRef: r.consent_ref,
+    grantedBy: r.granted_by,
+    grantedAt: r.granted_at,
+    expiresAt: r.expires_at ?? null,
+  };
+}
+
+export async function createProviderLink(
+  db: D1Database,
+  l: {
+    patientAccountId: string;
+    providerAccountId: string;
+    role: ProviderKind;
+    status?: LinkStatus;
+    consentRef?: string | null;
+    grantedBy: string;
+    expiresAt?: string | null;
+    id?: string;
+  }
+): Promise<ProviderLink> {
+  const id = l.id ?? crypto.randomUUID();
+  const status = l.status ?? "invited";
+  const consentRef = l.consentRef ?? null;
+  const expiresAt = l.expiresAt ?? null;
+  const grantedAt = new Date().toISOString();
+  await db
+    .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)
+    .run();
+  return {
+    id,
+    patientAccountId: l.patientAccountId,
+    providerAccountId: l.providerAccountId,
+    role: l.role,
+    status,
+    consentRef,
+    grantedBy: l.grantedBy,
+    grantedAt,
+    expiresAt,
+  };
+}
+
+export async function updateProviderLinkStatus(db: D1Database, id: string, status: LinkStatus): Promise<void> {
+  await db.prepare("UPDATE provider_links SET status = ? WHERE id = ?").bind(status, id).run();
+}
+
+// W44 P4b — a patient approving a support request: flip the link active, stamp its time-box + consent.
+export async function grantSupportLink(
+  db: D1Database,
+  id: string,
+  opts: { expiresAt: string | null; consentRef?: string | null }
+): Promise<void> {
+  await db
+    .prepare("UPDATE provider_links SET status = 'active', expires_at = ?, consent_ref = ? WHERE id = ?")
+    .bind(opts.expiresAt, opts.consentRef ?? null, id)
+    .run();
+}
+
+export async function getProviderLink(db: D1Database, id: string): Promise<ProviderLink | null> {
+  const row = await db.prepare("SELECT * FROM provider_links WHERE id = ?").bind(id).first<ProviderLinkRow>();
+  return row ? mapProviderLink(row) : null;
+}
+
+export async function listProvidersForPatient(db: D1Database, patientAccountId: string): Promise<ProviderLink[]> {
+  const { results } = await db
+    .prepare("SELECT * FROM provider_links WHERE patient_account_id = ?")
+    .bind(patientAccountId)
+    .all<ProviderLinkRow>();
+  return results.map(mapProviderLink);
+}
+
+export async function listPatientsForProvider(db: D1Database, providerAccountId: string): Promise<ProviderLink[]> {
+  const { results } = await db
+    .prepare("SELECT * FROM provider_links WHERE provider_account_id = ?")
+    .bind(providerAccountId)
+    .all<ProviderLinkRow>();
+  return results.map(mapProviderLink);
+}
+
+export async function getActiveProviderLink(
+  db: D1Database,
+  patientAccountId: 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)
+    .first<ProviderLinkRow>();
+  if (!link || link.status !== "active") return null;
+  // `expires_at` is set on time-boxed support grants and null for clinician links.
+  if (link.expires_at && Date.parse(link.expires_at) <= Date.now()) return null;
+  return mapProviderLink(link);
+}

package/adapters/d1/types.ts

@@ -0,0 +1,22 @@
+// Structural D1 types only, so this module has no dependency on @cloudflare/workers-types — any
+// D1-compatible database (Cloudflare's own, or a test double) satisfies this by shape.
+
+export interface D1Database {
+  prepare(query: string): D1PreparedStatement;
+  /**
+   * D1 runs a batch as a single implicit transaction, which `vault.ts`'s `replaceEnvelopes`/
+   * `commitRotation` need and nothing else here does. The shape is pinned against real workerd by
+   * the adopting app's own tests rather than trusted from a comment.
+   */
+  batch(statements: D1PreparedStatement[]): Promise<unknown[]>;
+}
+export interface D1PreparedStatement {
+  bind(...values: unknown[]): D1PreparedStatement;
+  first<T = unknown>(): Promise<T | null>;
+  all<T = unknown>(): Promise<{ results: T[] }>;
+  run(): Promise<unknown>;
+}
+
+export function toBytes(blob: unknown): Uint8Array {
+  return blob instanceof Uint8Array ? blob : new Uint8Array(blob as ArrayBuffer);
+}