@tinytars/frame 0.1.0

package/support-access.svelte.ts

@@ -0,0 +1,229 @@
+// The support console: which lists a support agent sees, what they have asked for, and whose record
+// they are about to open.
+//
+// App's third controller extraction. The server side of support access is well covered
+// (support-access-function.test.ts, support-provider-roster-function.test.ts, and
+// auth-client-support.test.ts); what had no test is the browser's answer to "which session is this
+// person in, and whose roster are they looking at" — a six-field state machine that decides whether
+// a patient's name is even offered.
+//
+// Same getter-parameterized factory shape as vault-principals.svelte.ts and
+// recovery-controller.svelte.ts. The audited drill-in stops at the envelope: unwrapping it, decrypting
+// the vault and moving the app to that patient is App's, because App owns the vault, the DEK and the
+// navigation. What is here is the part that decides WHETHER to ask for the envelope at all.
+
+import type { VaultSession, VaultEntry } from "./vault-session.svelte";
+import {
+  listSupportPatients,
+  listSupportProviders,
+  listSupportRequests,
+  requestSupportAccess,
+  cancelSupportRequest,
+  getProviderRoster,
+  enterSupportPatient,
+  type SupportPatient,
+  type SupportProvider,
+  type SupportRosterPatient,
+  type SupportRequest,
+} from "@tinytars/vault/auth-support";
+
+/** What the audited /api/support/access hands back — the envelope plus who it belongs to. */
+export interface SupportEntry extends VaultEntry {
+  vaultId: string;
+}
+
+export interface SupportProviderView {
+  providerAccountId: string;
+  displayName: string;
+  roster: SupportRosterPatient[];
+}
+
+export interface SupportAccessDeps {
+  /** `providerKey` unwraps the envelope; without it there is nothing to drill into. */
+  session: VaultSession;
+  /**
+   * App's shared error line, not a panel of this console's own. Preserved from the extraction: the
+   * support console IS the whole screen in this session, so its errors have always been the shell's.
+   */
+  reportError: (message: string | null) => void;
+  /**
+   * Unwrap, decrypt, and move the app to this patient. App owns all three. The provider key is passed
+   * rather than re-read: it was checked here, and handing it over is what makes that check load-bearing
+   * instead of leaving the host to assert a non-null it cannot prove.
+   */
+  openPatientVault: (entry: VaultEntry, providerKey: CryptoKey) => Promise<void>;
+}
+
+export interface SupportAccess {
+  /** Whether this account is a support agent, and so gets the console instead of the roster. */
+  readonly isSupportSession: boolean;
+  readonly patients: SupportPatient[];
+  readonly providers: SupportProvider[];
+  /** Outstanding (invited) requests, so an ask is visibly pending rather than silently nothing. */
+  readonly requests: SupportRequest[];
+  /** The clinician roster currently drilled into, or null at the console top level. */
+  readonly providerView: SupportProviderView | null;
+  /** Bound to the request-access input. */
+  requestEmail: string;
+
+  /** Enter the support console and load everything it shows. */
+  beginSession(): Promise<void>;
+  loadPatients(): Promise<void>;
+  loadProviders(): Promise<void>;
+  loadRequests(): Promise<void>;
+  /** Ask a patient for access by email. */
+  requestAccess(): Promise<void>;
+  cancelRequest(linkId: string): Promise<void>;
+  openProvider(p: SupportProvider): Promise<void>;
+  closeProvider(): void;
+  /** The audited drill-in. Hands the envelope to the host and never touches it here. */
+  enterPatient(patientAccountId: string): Promise<void>;
+  /** Clears the console on sign-out. */
+  reset(): void;
+}
+
+export function createSupportAccess(deps: SupportAccessDeps): SupportAccess {
+  let isSupportSession = $state(false);
+  let patients = $state<SupportPatient[]>([]);
+  let providers = $state<SupportProvider[]>([]);
+  let requests = $state<SupportRequest[]>([]);
+  let providerView = $state<SupportProviderView | null>(null);
+  let requestEmail = $state("");
+
+  /** Every list load reports to the same line and none of them is worth aborting the console over. */
+  async function load(body: () => Promise<void>): Promise<void> {
+    try {
+      await body();
+    } catch (e) {
+      deps.reportError((e as Error).message);
+    }
+  }
+
+  /**
+   * Re-reads the drilled-into roster if one is open. A request or a cancellation changes the `pending`
+   * and `openable` flags on the very rows being looked at, and without this the row keeps offering the
+   * button that was just pressed.
+   */
+  async function refreshProviderView(): Promise<void> {
+    if (!providerView) return;
+    providerView = { ...providerView, roster: await getProviderRoster(providerView.providerAccountId) };
+  }
+
+  async function loadPatients() {
+    await load(async () => {
+      patients = await listSupportPatients();
+    });
+  }
+
+  async function loadProviders() {
+    await load(async () => {
+      providers = await listSupportProviders();
+    });
+  }
+
+  async function loadRequests() {
+    await load(async () => {
+      requests = await listSupportRequests();
+    });
+  }
+
+  return {
+    get isSupportSession() {
+      return isSupportSession;
+    },
+    get patients() {
+      return patients;
+    },
+    get providers() {
+      return providers;
+    },
+    get requests() {
+      return requests;
+    },
+    get providerView() {
+      return providerView;
+    },
+    get requestEmail() {
+      return requestEmail;
+    },
+    set requestEmail(v: string) {
+      requestEmail = v;
+    },
+
+    async beginSession() {
+      isSupportSession = true;
+      await loadPatients();
+      await loadProviders();
+      await loadRequests();
+    },
+
+    loadPatients,
+    loadProviders,
+    loadRequests,
+
+    async requestAccess() {
+      const em = requestEmail.trim();
+      if (!em) return;
+      deps.reportError(null);
+      try {
+        await requestSupportAccess(em);
+        requestEmail = "";
+        // Invited until approved — show it as pending, and refresh the active lists too.
+        await loadRequests();
+        await loadPatients();
+        await loadProviders();
+        await refreshProviderView();
+      } catch (e) {
+        deps.reportError((e as Error).message);
+      }
+    },
+
+    async cancelRequest(linkId: string) {
+      deps.reportError(null);
+      try {
+        await cancelSupportRequest(linkId);
+        await loadRequests();
+        await refreshProviderView();
+      } catch (e) {
+        deps.reportError((e as Error).message);
+      }
+    },
+
+    async openProvider(p: SupportProvider) {
+      deps.reportError(null);
+      try {
+        providerView = { providerAccountId: p.providerAccountId, displayName: p.displayName, roster: await getProviderRoster(p.providerAccountId) };
+      } catch (e) {
+        deps.reportError((e as Error).message);
+      }
+    },
+
+    closeProvider() {
+      providerView = null;
+    },
+
+    async enterPatient(patientAccountId: string) {
+      const providerKey = deps.session.providerKey;
+      if (!providerKey) return;
+      deps.reportError(null);
+      try {
+        await deps.openPatientVault(await enterSupportPatient(patientAccountId), providerKey);
+      } catch (e) {
+        deps.reportError((e as Error).message);
+      }
+    },
+
+    reset() {
+      // All six, where App used to clear two. The drill-in view was the one that mattered:
+      // nothing reloads it on the next sign-in the way the three lists are reloaded, so a support
+      // agent signing out and another signing in on the same browser opened onto the previous
+      // agent's clinician roster.
+      isSupportSession = false;
+      patients = [];
+      providers = [];
+      requests = [];
+      providerView = null;
+      requestEmail = "";
+    },
+  };
+}

package/vault-principals.svelte.ts

@@ -0,0 +1,245 @@
+// Who can open this vault, and the re-key that changes the answer.
+//
+// The first of App's five controller extractions. This cluster was ~110 lines of the
+// component: six `$state` declarations, three `$derived` filters and seven async handlers, including
+// `rotateVaultKey` — the single most consequential operation in the app, whose only test was an e2e
+// that by construction cannot interrupt it.
+//
+// Same getter-parameterized factory shape used consistently across this package's controllers: the
+// host passes thunks rather than values, so this module never captures a stale vault. What stays with
+// App is what App owns — the decrypted record and the sink that writes it.
+
+import type { VaultSession } from "./vault-session.svelte";
+import { generateDEK, wrapDEKForPublicKey } from "@tinytars/vault/crypto";
+import { bytesToB64 } from "@tinytars/vault/base64";
+import { listMyProviders, lookupProvider, grantProvider, revokeProvider, type ProviderLinkView } from "@tinytars/vault/auth-grants";
+import { approveSupport, approveSupportAsProvider } from "@tinytars/vault/auth-support";
+import { getVaultPrincipals, stageVaultRotation, rotateVault } from "@tinytars/vault/auth-recovery";
+
+export interface VaultPrincipalsDeps<V> {
+  /** The decrypted record, read fresh — never captured. Still App's, along with the sink below. */
+  getVault: () => V | null;
+  /** The unlocked-session key material. Stable identity, its own module. */
+  session: VaultSession;
+  /** Re-encrypts and writes the vault under a given id and key. App owns the sink. */
+  saveVault: (vault: V, r2Id: string, dek: CryptoKey) => Promise<unknown>;
+  /**
+   * The provider-side pair (approve/revoke a support agent's roster grant) reports through App's
+   * shared error line rather than this panel's, because it renders in the clinician console where
+   * the Access modal is not mounted. Behaviour preserved from the extraction, not a new idea.
+   */
+  reportError: (message: string | null) => void;
+}
+
+export interface VaultPrincipals {
+  readonly open: boolean;
+  readonly providers: ProviderLinkView[];
+  readonly busy: boolean;
+  readonly error: string | null;
+  /** Bound to the add-provider input. */
+  newProviderEmail: string;
+  /** Bound to the approval TTL select. */
+  ttlHours: number;
+
+  /** Support agents who have asked and not yet been approved. */
+  readonly pendingSupport: ProviderLinkView[];
+  /** Everything that is not a pending support request — clinicians plus approved support. */
+  readonly activeAccess: ProviderLinkView[];
+  /** Approved support agents, as the clinician console lists them. */
+  readonly activeSupport: ProviderLinkView[];
+
+  openPanel(): Promise<void>;
+  closePanel(): void;
+  /** Reloads the list without opening the panel. Non-fatal: an empty section beats a blocked boot. */
+  refreshQuietly(): Promise<void>;
+  addProvider(): Promise<void>;
+  revoke(p: ProviderLinkView): Promise<void>;
+  approve(p: ProviderLinkView): Promise<void>;
+  approveAsProvider(p: ProviderLinkView): Promise<void>;
+  revokeAsProvider(p: ProviderLinkView): Promise<void>;
+  /**
+   * Mints a fresh DEK, re-encrypts the vault under it, re-wraps it to every remaining principal and
+   * swaps. Exposed because a pending rotation from a prior session is resumed at boot.
+   */
+  rotateVaultKey(): Promise<void>;
+  /** Clears panel state on sign-out. */
+  reset(): void;
+}
+
+export function createVaultPrincipals<V>(deps: VaultPrincipalsDeps<V>): VaultPrincipals {
+  let open = $state(false);
+  let providers = $state<ProviderLinkView[]>([]);
+  let newProviderEmail = $state("");
+  let busy = $state(false);
+  let error = $state<string | null>(null);
+  let ttlHours = $state(72);
+
+  const pendingSupport = $derived(providers.filter((p) => p.kind === "support" && p.status === "invited"));
+  const activeAccess = $derived(providers.filter((p) => !(p.kind === "support" && p.status === "invited")));
+  const activeSupport = $derived(providers.filter((p) => p.kind === "support" && p.status === "active"));
+
+  /** The busy/error/reload envelope every handler here shares. */
+  async function run(body: () => Promise<void>, report: (m: string | null) => void): Promise<void> {
+    busy = true;
+    report(null);
+    try {
+      await body();
+      providers = await listMyProviders();
+    } catch (e) {
+      report((e as Error).message);
+    } finally {
+      busy = false;
+    }
+  }
+
+  const toPanel = (m: string | null) => (error = m);
+
+  async function rotateVaultKey(): Promise<void> {
+    const vault = deps.getVault();
+    const { session } = deps;
+    if (!vault || !session.dek || !session.r2Id) return;
+    const principals = await getVaultPrincipals();
+    const newDek = await generateDEK();
+    // The blob goes to a NEW object, reserved here, and the envelope commit below doubles as the
+    // pointer swap. This used to re-encrypt in place and commit the matching envelopes four round
+    // trips later; anything that interrupted that window — a dropped connection, a closed lid
+    // mid-revoke — left every principal holding an envelope for a key the ciphertext no longer used.
+    // An interruption before the commit now leaves the old blob and the old envelopes still agreeing,
+    // and the abandoned object is ciphertext under a key nobody kept.
+    const newVaultId = await stageVaultRotation(principals.vaultId);
+    await deps.saveVault(vault, newVaultId, newDek);
+    const targets = [
+      { accountId: principals.selfAccountId, publicKeyJwk: principals.selfPublicKeyJwk },
+      // A patient who removed org recovery must not have it silently restored by the next re-key.
+      ...(principals.orgRecoveryRevokedAt ? [] : [{ accountId: principals.orgAccountId, publicKeyJwk: principals.orgPublicKeyJwk }]),
+      ...principals.providers,
+    ];
+    const envelopes = await Promise.all(
+      targets.map(async (t) => {
+        const e = await wrapDEKForPublicKey(newDek, t.publicKeyJwk);
+        return { principalAccountId: t.accountId, wrappedDEK: bytesToB64(e.wrappedDEK), ephemeralPublicKeyJwk: e.ephemeralPublicKeyJwk };
+      }),
+    );
+    await rotateVault({ vaultId: principals.vaultId, newVaultId, envelopes });
+    session.open(newVaultId, newDek);
+  }
+
+  return {
+    get open() {
+      return open;
+    },
+    get providers() {
+      return providers;
+    },
+    get busy() {
+      return busy;
+    },
+    get error() {
+      return error;
+    },
+    get newProviderEmail() {
+      return newProviderEmail;
+    },
+    set newProviderEmail(v: string) {
+      newProviderEmail = v;
+    },
+    get ttlHours() {
+      return ttlHours;
+    },
+    set ttlHours(v: number) {
+      ttlHours = v;
+    },
+    get pendingSupport() {
+      return pendingSupport;
+    },
+    get activeAccess() {
+      return activeAccess;
+    },
+    get activeSupport() {
+      return activeSupport;
+    },
+
+    async openPanel() {
+      open = true;
+      error = null;
+      try {
+        providers = await listMyProviders();
+      } catch (e) {
+        error = (e as Error).message;
+      }
+    },
+
+    closePanel() {
+      open = false;
+    },
+
+    async refreshQuietly() {
+      try {
+        providers = await listMyProviders();
+      } catch {
+        /* non-fatal; the section just stays empty */
+      }
+    },
+
+    async addProvider() {
+      const emailInput = newProviderEmail.trim();
+      const dek = deps.session.dek;
+      if (!emailInput || !dek) return;
+      busy = true;
+      error = null;
+      try {
+        const provider = await lookupProvider(emailInput);
+        // Not an exception, and deliberately not a reload either: a typo is an ordinary outcome, and
+        // re-listing for it would be a round trip that changes nothing.
+        if (!provider) {
+          error = "No provider found with that email.";
+          return;
+        }
+        await grantProvider(dek, provider);
+        newProviderEmail = "";
+        providers = await listMyProviders();
+      } catch (e) {
+        error = (e as Error).message;
+      } finally {
+        busy = false;
+      }
+    },
+
+    async revoke(p: ProviderLinkView) {
+      await run(async () => {
+        await revokeProvider(p.linkId);
+        // True forward-secret revocation for SUPPORT: re-key the vault so a support agent
+        // who cached the DEK can no longer decrypt it. Clinician revoke stays delete-only. Denying a
+        // pending (never-active) support request needs no rotation — support never held the DEK.
+        if (p.kind === "support" && p.status === "active") await rotateVaultKey();
+      }, toPanel);
+    },
+
+    async approve(p: ProviderLinkView) {
+      if (!deps.session.dek || !p.publicKeyJwk) return;
+      const dek = deps.session.dek;
+      const jwk = p.publicKeyJwk;
+      await run(() => approveSupport(p.linkId, dek, jwk, ttlHours).then(() => undefined), toPanel);
+    },
+
+    async approveAsProvider(p: ProviderLinkView) {
+      await run(() => approveSupportAsProvider(p.linkId, ttlHours).then(() => undefined), deps.reportError);
+    },
+
+    async revokeAsProvider(p: ProviderLinkView) {
+      // No vault rotation, unlike the patient-side revoke: a provider owns nothing encrypted, and
+      // support only ever held per-patient DEKs via separate patient grants, which are the patients'
+      // to rotate.
+      await run(() => revokeProvider(p.linkId).then(() => undefined), deps.reportError);
+    },
+
+    rotateVaultKey,
+
+    reset() {
+      open = false;
+      providers = [];
+      newProviderEmail = "";
+      error = null;
+    },
+  };
+}

package/vault-session.svelte.ts

@@ -0,0 +1,77 @@
+import type { VaultSession } from "@tinytars/vault/vault-session";
+
+export type { VaultEntry, VaultSession } from "@tinytars/vault/vault-session";
+export { openVault } from "@tinytars/vault/vault-session";
+
+// The unlocked-session key material, as one object with one transition each way.
+//
+// This consolidation was done as its own careful, tested commit rather than a drive-by change
+// folded into a larger move — the key material it manages is live PHI-handling code, and a change
+// to it needs its own verification pass regardless of what else is happening around it.
+//
+// The argument is not only tidiness. Until now `dek`, `vaultR2Id` and the two private keys were four
+// separate `$state` declarations, set in four separate assignments and cleared in four more. Nothing
+// made them move together, so a HALF-OPEN session was representable: `backToRoster()` clears the DEK
+// and the r2 id, and any future path that forgot one would leave a live data key in memory for a
+// vault the user believes they have closed. Here that state cannot be expressed — `close()` clears
+// everything, and `isOpen` is derived rather than tracked.
+//
+// What is deliberately NOT here: `vault` itself, the decrypted record. It has 86 references in
+// App and is mutated by every save, so moving it is a much larger edit than moving the key
+// material, and a larger edit on PHI-handling code than this one commit should carry. The key
+// material is the part whose lifetime is a security property; the plaintext record's lifetime is the
+// same as the key's by construction, because it cannot be re-read without one.
+//
+// `VaultEntry`/`VaultSession` (the shapes) and `openVault` (rune-free logic) live in
+// packages/security/vault-session.ts — this file imports them back and adds only the one thing that
+// cannot move there: the $state-backed implementation, which is Svelte-coupled by construction.
+
+export function createVaultSession(): VaultSession {
+  let dek = $state<CryptoKey | null>(null);
+  let r2Id = $state<string | null>(null);
+  let ownerKey = $state<CryptoKey | null>(null);
+  let providerKey = $state<CryptoKey | null>(null);
+
+  return {
+    get dek() {
+      return dek;
+    },
+    get r2Id() {
+      return r2Id;
+    },
+    get ownerKey() {
+      return ownerKey;
+    },
+    get providerKey() {
+      return providerKey;
+    },
+    get isOpen() {
+      // Both, though the API makes it impossible for them to disagree — `open` sets the pair and
+      // `close` clears the pair. That redundancy is deliberate defence in depth and is deliberately
+      // NOT testable: a mutation to `r2Id !== null` alone passes every test in vault-session.test.ts,
+      // because reaching the state it would misreport requires bypassing this object. Noted rather
+      // than covered by a contrived test.
+      return dek !== null && r2Id !== null;
+    },
+    open(nextId: string, nextDek: CryptoKey) {
+      r2Id = nextId;
+      dek = nextDek;
+    },
+    setOwnerKey(key: CryptoKey | null) {
+      ownerKey = key;
+    },
+    setProviderKey(key: CryptoKey | null) {
+      providerKey = key;
+    },
+    close() {
+      dek = null;
+      r2Id = null;
+    },
+    signOut() {
+      dek = null;
+      r2Id = null;
+      ownerKey = null;
+      providerKey = null;
+    },
+  };
+}