@tinytars/frame 0.1.0

package/recovery-controller.svelte.ts

@@ -0,0 +1,301 @@
+// Getting back in: the four ways a person who cannot sign in ends up signed in again, and the one
+// way they give that up on purpose.
+//
+// App's second controller extraction, and the one with the least test cover behind it. This
+// recovery ladder was built first, with its server-side attempt cap fixed afterward, but the
+// browser half had no unit test at all: which code kind is in play, what is shown once and never
+// again, and what is left behind when a step fails. Those are state questions, and an e2e that
+// drives the happy path cannot ask them.
+//
+// Same getter-parameterized factory shape as vault-principals.svelte.ts and the other controllers in
+// this package. What stays with App is what App owns: the lock screen's email field, the account private key, and
+// what a successful recovery does next (enter the account, persist the key). Two of the five handlers
+// report through panels this module does not own — the Account modal's busy/error line and the lock
+// screen's — so both are injected rather than duplicated here.
+
+import type { VaultSession } from "./vault-session.svelte";
+import {
+  detectRecoveryKind,
+  issueRecoveryCode,
+  recoverAccount,
+  redeemRecoveryCode,
+  regenerateRecoveryCode,
+  revokeRecoveryEnvelope,
+} from "@tinytars/vault/auth-recovery";
+
+/**
+ * The minimum a roster row must carry to have a code issued for it. Structural, and the controller is
+ * generic over it, so the host keeps its own richer row type (and its label function) without this
+ * module importing the roster's shape.
+ */
+export interface RecoveryPatient {
+  patientAccountId: string;
+  envelope: { wrappedDEK: string; ephemeralPublicKeyJwk: JsonWebKey };
+}
+
+/** What both recovery paths hand back; the shape `enterAccount` takes. */
+export interface RecoveredSession {
+  vaultId: string | null;
+  r2Key: string | null;
+  privateKey: CryptoKey;
+  dek: CryptoKey | null;
+  rotationPending?: boolean;
+}
+
+export interface RecoveryControllerDeps {
+  /** The unlocked-session key material; `providerKey` is what authorizes issuing a code. */
+  session: VaultSession;
+  /** The lock screen's email field, read fresh — `enterAccount` clears it, so it must never be captured. */
+  getEmail: () => string;
+  /**
+   * The account private key, or null with the "sign in again" message already posted. Regenerating a
+   * recovery code needs an EXTRACTABLE key, which a resumed session may not have; App owns that check
+   * because it owns the key.
+   */
+  ensureExtractableKey: () => CryptoKey | null;
+  /** Re-reads the method list so the new recovery credential appears. App owns the Account modal. */
+  refreshAccount: () => Promise<void>;
+  setAccountBusy: (busy: boolean) => void;
+  reportAccountError: (message: string | null) => void;
+  /** The lock screen's busy flag and shared error line. */
+  setUnlocking: (busy: boolean) => void;
+  reportError: (message: string | null) => void;
+  /** Enter the account and persist the key so the session survives a refresh. App owns both. */
+  enterRecovered: (r: RecoveredSession) => Promise<void>;
+}
+
+export interface RecoveryController<P extends RecoveryPatient = RecoveryPatient> {
+  /** The roster row whose one-time code dialog is open, or null when it is closed. */
+  readonly issuedFor: P | null;
+  readonly issuedCode: string | null;
+  readonly issuedExpiresAt: string | null;
+  readonly issuing: boolean;
+  readonly issueError: string | null;
+
+  /** Lock screen: recovery form shown instead of sign-in. */
+  recoverMode: boolean;
+  codeInput: string;
+  newPassword: string;
+  /**
+   * Which ladder rung `codeInput` currently looks like: "code" is the patient's own recovery code,
+   * "grant" is the one-time code a clinician reads to a patient who has lost theirs. Read off the
+   * pasted/typed string's shape (`detectRecoveryKind`) — the two never collide by construction, so
+   * there is nothing for the caller to pick.
+   */
+  readonly kind: "code" | "grant";
+
+  /** The freshly minted recovery code, shown once in the Account modal and never fetched again. */
+  readonly regeneratedCode: string | null;
+  /** Whether the org still holds a recovery envelope for this vault, per the server. */
+  readonly orgHeld: boolean;
+  readonly orgRevokedAt: string | null;
+  /** The two-step confirm on removing the org recovery key. */
+  revokeConfirm: boolean;
+  /** Dismissed for this session only — the nudge is per-session, not a stored preference. */
+  nudgeDismissed: boolean;
+
+  /** Provider action: mint a one-time code to read to a locked-out patient. */
+  issueForPatient(p: P): Promise<void>;
+  closeIssueDialog(): void;
+  /** Mint a replacement recovery code for one's own account. */
+  regenerate(): Promise<void>;
+  /** Lock screen: redeem whichever code kind is selected, then enter. */
+  recover(): Promise<void>;
+  /** Give up org recovery: from here the password is the only key to the record. */
+  revokeOrgKey(): Promise<void>;
+  /** Adopt the server's answer about the org envelope. Called when the Account modal loads. */
+  applyPrincipals(p: { envelopePrincipalIds: string[]; orgAccountId: string; orgRecoveryRevokedAt: string | null }): void;
+  /**
+   * Closing the Account modal drops the once-shown code and rearms the revoke confirm — but leaves the
+   * lock-screen fields alone, which is why this is not `reset()`. Reopening the modal must not present
+   * a half-pressed "Yes, remove it", and the code is unrecoverable anyway once the modal is gone.
+   */
+  closeAccountBlocks(): void;
+  /** Clears everything on sign-out. */
+  reset(): void;
+}
+
+export function createRecoveryController<P extends RecoveryPatient = RecoveryPatient>(
+  deps: RecoveryControllerDeps,
+): RecoveryController<P> {
+  let issuedFor = $state<P | null>(null);
+  let issuedCode = $state<string | null>(null);
+  let issuedExpiresAt = $state<string | null>(null);
+  let issuing = $state(false);
+  let issueError = $state<string | null>(null);
+
+  let recoverMode = $state(false);
+  let codeInput = $state("");
+  let newPassword = $state("");
+
+  let regeneratedCode = $state<string | null>(null);
+  let orgHeld = $state(false);
+  let orgRevokedAt = $state<string | null>(null);
+  let revokeConfirm = $state(false);
+  let nudgeDismissed = $state(false);
+
+  /** The Account modal's busy/error envelope, whose line belongs to App. */
+  async function inAccount(body: () => Promise<void>): Promise<void> {
+    deps.setAccountBusy(true);
+    try {
+      await body();
+    } catch (e) {
+      deps.reportAccountError((e as Error).message);
+    } finally {
+      deps.setAccountBusy(false);
+    }
+  }
+
+  return {
+    get issuedFor() {
+      return issuedFor;
+    },
+    get issuedCode() {
+      return issuedCode;
+    },
+    get issuedExpiresAt() {
+      return issuedExpiresAt;
+    },
+    get issuing() {
+      return issuing;
+    },
+    get issueError() {
+      return issueError;
+    },
+    get recoverMode() {
+      return recoverMode;
+    },
+    set recoverMode(v: boolean) {
+      recoverMode = v;
+    },
+    get codeInput() {
+      return codeInput;
+    },
+    set codeInput(v: string) {
+      codeInput = v;
+    },
+    get newPassword() {
+      return newPassword;
+    },
+    set newPassword(v: string) {
+      newPassword = v;
+    },
+    get kind() {
+      return detectRecoveryKind(codeInput);
+    },
+    get regeneratedCode() {
+      return regeneratedCode;
+    },
+    get orgHeld() {
+      return orgHeld;
+    },
+    get orgRevokedAt() {
+      return orgRevokedAt;
+    },
+    get revokeConfirm() {
+      return revokeConfirm;
+    },
+    set revokeConfirm(v: boolean) {
+      revokeConfirm = v;
+    },
+    get nudgeDismissed() {
+      return nudgeDismissed;
+    },
+    set nudgeDismissed(v: boolean) {
+      nudgeDismissed = v;
+    },
+
+    async issueForPatient(p: P) {
+      if (!deps.session.providerKey) return;
+      issuedFor = p;
+      issuedCode = null;
+      issuedExpiresAt = null;
+      issueError = null;
+      issuing = true;
+      try {
+        const r = await issueRecoveryCode(p.patientAccountId, p.envelope, deps.session.providerKey);
+        issuedCode = r.code;
+        issuedExpiresAt = r.expiresAt;
+      } catch (e) {
+        issueError = (e as Error).message;
+      } finally {
+        issuing = false;
+      }
+    },
+
+    closeIssueDialog() {
+      // Cleared on close, not merely hidden: the code is shown once, and leaving it in component state
+      // would keep it alive in memory for the rest of the session for no reason.
+      issuedFor = null;
+      issuedCode = null;
+      issuedExpiresAt = null;
+      issueError = null;
+    },
+
+    async regenerate() {
+      deps.reportAccountError(null);
+      const pk = deps.ensureExtractableKey();
+      if (!pk) return;
+      await inAccount(async () => {
+        regeneratedCode = await regenerateRecoveryCode(pk);
+        await deps.refreshAccount();
+      });
+    },
+
+    async recover() {
+      const email = deps.getEmail();
+      if (!email || !codeInput.trim()) return;
+      deps.setUnlocking(true);
+      deps.reportError(null);
+      try {
+        const r =
+          detectRecoveryKind(codeInput) === "grant"
+            ? await redeemRecoveryCode(email, codeInput.trim(), newPassword)
+            : await recoverAccount(email, codeInput.trim(), newPassword);
+        await deps.enterRecovered(r);
+        // Only on success: a failed attempt keeps the typed code, because the usual failure is a
+        // mistyped character and clearing the form would make the retry a re-entry.
+        recoverMode = false;
+        codeInput = "";
+        newPassword = "";
+      } catch (e) {
+        deps.reportError((e as Error).message);
+      } finally {
+        deps.setUnlocking(false);
+      }
+    },
+
+    async revokeOrgKey() {
+      deps.reportAccountError(null);
+      await inAccount(async () => {
+        const r = await revokeRecoveryEnvelope();
+        orgHeld = false;
+        orgRevokedAt = r.revokedAt;
+        revokeConfirm = false;
+      });
+    },
+
+    closeAccountBlocks() {
+      regeneratedCode = null;
+      revokeConfirm = false;
+    },
+
+    applyPrincipals(p) {
+      orgHeld = p.envelopePrincipalIds.includes(p.orgAccountId);
+      orgRevokedAt = p.orgRecoveryRevokedAt;
+    },
+
+    reset() {
+      issuedFor = null;
+      issuedCode = null;
+      issuedExpiresAt = null;
+      issueError = null;
+      regeneratedCode = null;
+      recoverMode = false;
+      codeInput = "";
+      newPassword = "";
+      revokeConfirm = false;
+      nudgeDismissed = false;
+    },
+  };
+}

package/roster-session.svelte.ts

@@ -0,0 +1,263 @@
+// How a session starts, and whose record it is on.
+//
+// App's fifth and last controller extraction. This is the cluster that answers "who is
+// signed in": the cold-load resume, the owner/provider/support routing that follows a login, and the
+// clinician roster that a provider drills into. It had no unit test at all, and two of its rules are
+// security properties rather than conveniences — a stored account key whose session has expired is
+// DROPPED rather than kept, and the resume marker is only written once the key is actually stored, so
+// a browser that refuses persistence does not advertise a resume it cannot perform.
+//
+// Same getter-parameterized factory shape as the other four. The vault itself stays with App, per
+// vault-session.svelte.ts's own note: the key material's lifetime is the security property, and the
+// plaintext record cannot outlive it because it cannot be re-read without one.
+
+import type { VaultSession, VaultEntry } from "./vault-session.svelte";
+import { getAccountKey, putAccountKey, clearAccountKey } from "@tinytars/vault/key-store";
+import { unwrapDEKWithPrivateKey } from "@tinytars/vault/crypto";
+import { b64ToBytes } from "@tinytars/vault/base64";
+import { resumeSession, bootstrapGoogleSession, getMyAccount } from "@tinytars/vault/auth-client";
+import { revokeProvider } from "@tinytars/vault/auth-grants";
+
+/** Non-sensitive flag marking that a session may be resumable on reload. */
+export const RESUME_MARKER = "hd_resume";
+
+export interface RosterPatient extends VaultEntry {
+  /** The provider can DELETE /api/providers/{linkId} to drop this patient. */
+  linkId: string;
+  vaultId: string;
+}
+
+/** What a login, a resume or a recovery all hand back. */
+export interface EnteredAccount {
+  vaultId: string | null;
+  r2Key: string | null;
+  privateKey: CryptoKey;
+  dek: CryptoKey | null;
+  rotationPending?: boolean;
+}
+
+export interface RosterSessionDeps {
+  session: VaultSession;
+  reportError: (message: string | null) => void;
+  /** The lock screen's fields, cleared the moment a session begins. */
+  clearLoginForm: () => void;
+  /** Owner path: decrypt and install the owner's own vault. App owns the decrypted record. */
+  openOwnVault: (r2Key: string, dek: CryptoKey) => Promise<void>;
+  /** Owner path, after the vault is open: the recovery-envelope backfill, account info, any re-key. */
+  afterOwnerEnter: (rotationPending: boolean) => Promise<void>;
+  /** A support provider gets the audited console; a clinician gets the roster and the refresh token. */
+  beginSupportSession: () => Promise<void>;
+  beginClinicianSession: () => Promise<void>;
+  /** The drill-in: unwrap, decrypt, and move the app to this patient. One body, both consoles. */
+  openPatientVault: (entry: VaultEntry, providerKey: CryptoKey) => Promise<void>;
+  /** Drops the decrypted record. Paired with session.close(), which drops the key that made it. */
+  closeVault: () => void;
+  /** The roster-removal confirmation. Injected so the dialog stays the host's. */
+  confirmRemoval: (label: string) => boolean;
+}
+
+export interface RosterSession {
+  /** True for a clinician or support account — one without a vault of its own. */
+  readonly isProvider: boolean;
+  /** The clinician's roster. Empty in an owner session. */
+  readonly patients: RosterPatient[];
+  /** Who is being viewed, when a provider has drilled in. Null on one's own record. */
+  readonly enteredPatient: { email: string | null; displayName: string } | null;
+  /**
+   * True while the cold-load resume is still deciding, so the lock screen does not flash. Starts
+   * false and is raised by `bootResume` itself — synchronously, before its first await — so the host
+   * has no window in which it must own a second copy of this flag. App previously did own one, and
+   * that copy was never lowered, leaving every reloaded page on "Restoring your session…" forever.
+   */
+  readonly resuming: boolean;
+
+  /** Routes a login/resume/recovery result to the owner, clinician or support path. */
+  enterAccount(r: EnteredAccount): Promise<void>;
+  /** The cold-load resume, dispatched by the marker so we only probe when there is one. */
+  bootResume(): Promise<void>;
+  /** Stores the account key and marks the session resumable — in that order, and only in that order. */
+  persistSessionKey(privateKey: CryptoKey): Promise<void>;
+  loadPatients(): Promise<void>;
+  removeFromRoster(p: RosterPatient): Promise<void>;
+  /** The label a roster row shows, which is the email whenever the "name" is a signup placeholder. */
+  label(p: RosterPatient): string;
+  enterPatient(p: RosterPatient): Promise<void>;
+  /** Leaves a patient's record without leaving the provider's session. */
+  backToRoster(): void;
+  /** Records who was entered. Called by the host once the vault is actually installed. */
+  setEnteredPatient(who: { email: string | null; displayName: string } | null): void;
+  reset(): void;
+}
+
+export function createRosterSession(deps: RosterSessionDeps): RosterSession {
+  let isProvider = $state(false);
+  let patients = $state<RosterPatient[]>([]);
+  let enteredPatient = $state<{ email: string | null; displayName: string } | null>(null);
+  let resuming = $state(false);
+
+  async function loadPatients(): Promise<void> {
+    const res = await fetch("/api/providers/patients", { cache: "no-store" });
+    // A failed fetch leaves the previous roster standing rather than blanking it. A provider whose
+    // network blipped keeps the list they were working from; an empty roster would read as "you have
+    // no patients", which is a different and wrong statement.
+    if (res.ok) patients = ((await res.json()).patients ?? []) as RosterPatient[];
+  }
+
+  async function enterAccount(r: EnteredAccount): Promise<void> {
+    deps.clearLoginForm();
+    if (r.vaultId && r.r2Key && r.dek) {
+      deps.session.setOwnerKey(r.privateKey);
+      isProvider = false;
+      await deps.openOwnVault(r.r2Key, r.dek);
+      await deps.afterOwnerEnter(r.rotationPending ?? false);
+      return;
+    }
+    deps.session.setProviderKey(r.privateKey);
+    isProvider = true;
+    const acct = await getMyAccount();
+    if (acct.providerKind === "support") await deps.beginSupportSession();
+    else {
+      await loadPatients();
+      await deps.beginClinicianSession();
+    }
+  }
+
+  /**
+   * Password/passkey: the account private key is a non-extractable CryptoKey persisted in IndexedDB.
+   * With a valid session, re-fetch the vault location and owner envelope, unwrap the DEK with the
+   * stored key, and enter. A stored key whose session has expired is dropped, not kept — otherwise a
+   * shared machine keeps a key for an account nobody is signed into any more.
+   */
+  async function resumeFromStoredKey(): Promise<boolean> {
+    let storedKey: CryptoKey | null = null;
+    try {
+      storedKey = await getAccountKey();
+    } catch {
+      return false;
+    }
+    if (!storedKey) return false;
+    const r = await resumeSession();
+    if (!r) {
+      try {
+        await clearAccountKey();
+      } catch {
+        /* best-effort */
+      }
+      return false;
+    }
+    const dek = r.ownerEnvelope
+      ? await unwrapDEKWithPrivateKey(b64ToBytes(r.ownerEnvelope.wrappedDEK), r.ownerEnvelope.ephemeralPublicKeyJwk, storedKey)
+      : null;
+    await enterAccount({ vaultId: r.vaultId, r2Key: r.r2Key, privateKey: storedKey, dek, rotationPending: r.rotationPending });
+    return true;
+  }
+
+  /** Google: no client-held key (server custody). A non-Google session 401s and stays locked. */
+  async function resumeGoogle(): Promise<boolean> {
+    try {
+      await enterAccount(await bootstrapGoogleSession());
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  return {
+    get isProvider() {
+      return isProvider;
+    },
+    get patients() {
+      return patients;
+    },
+    get enteredPatient() {
+      return enteredPatient;
+    },
+    get resuming() {
+      return resuming;
+    },
+
+    enterAccount,
+    loadPatients,
+
+    async bootResume() {
+      resuming = true;
+      try {
+        const marker = localStorage.getItem(RESUME_MARKER);
+        if (marker === "key" && (await resumeFromStoredKey())) return;
+        if (marker === "google" && (await resumeGoogle())) return;
+        // Nothing resumed — clear the marker so the next load goes straight to the lock screen
+        // instead of paying for a probe that already failed once.
+        localStorage.removeItem(RESUME_MARKER);
+      } catch {
+        localStorage.removeItem(RESUME_MARKER);
+      } finally {
+        resuming = false;
+      }
+    },
+
+    async persistSessionKey(privateKey: CryptoKey) {
+      try {
+        await putAccountKey(privateKey);
+        // Only once the key is genuinely stored. Setting the marker first would promise a resume that
+        // private browsing cannot deliver, and the next load would probe, fail, and clear it anyway.
+        localStorage.setItem(RESUME_MARKER, "key");
+      } catch {
+        /* persistence unavailable; the session still works this page, it just re-auths on refresh */
+      }
+    },
+
+    // Dropping a patient deletes the provider's envelope; the patient must re-grant to restore
+    // access. The patient's own vault is untouched.
+    async removeFromRoster(p: RosterPatient) {
+      if (!deps.confirmRemoval(p.displayName)) return;
+      deps.reportError(null);
+      try {
+        await revokeProvider(p.linkId);
+        await loadPatients();
+      } catch (e) {
+        deps.reportError((e as Error).message);
+      }
+    },
+
+    // Names are auto-derived at signup (password/passkey → the email local-part;
+    // Google-without-name → "New member"), so when the "name" is really a placeholder we show the
+    // full email, which actually tells two patients apart.
+    label(p: RosterPatient): string {
+      const name = p.displayName?.trim() ?? "";
+      if (!p.email) return name;
+      // Exact match against the verbatim local-part — that is the untouched auto value. A
+      // capitalised or edited name like "Liz" is a real, human-set one and stands.
+      const localPart = p.email.split("@")[0];
+      return name === "" || name === "New member" || name === localPart ? p.email : name;
+    },
+
+    async enterPatient(p: RosterPatient) {
+      const providerKey = deps.session.providerKey;
+      if (!providerKey) return;
+      deps.reportError(null);
+      try {
+        await deps.openPatientVault(p, providerKey);
+      } catch (e) {
+        deps.reportError((e as Error).message);
+      }
+    },
+
+    backToRoster() {
+      deps.closeVault();
+      deps.session.close();
+      enteredPatient = null;
+      // The roster, the provider key and the provider flag all stay — this provider is still signed in
+      // and still needs their key to open the next patient.
+    },
+
+    setEnteredPatient(who) {
+      enteredPatient = who;
+    },
+
+    reset() {
+      isProvider = false;
+      patients = [];
+      enteredPatient = null;
+    },
+  };
+}