@connextar/house 0.17.0 → 0.19.0

package/README.md

@@ -80,6 +80,13 @@ submitted from a text field lands in the browser's autofill history — and a
 strength estimate that differs between apps is worse than none. So there is one
 toggle and one estimate, and the estimate runs on the server too.
 
+`admin` is the jobs case with six copies. Every app with platform
+administrators wrote its own "used a second factor" plugin, guard, "view as" and
+bootstrap script, and the copies drifted on exactly the parts that matter: which
+sessions may inherit the proof, whether a revoked session still counts, whether
+the view-as cookie is signed. The module is AltEd's model with each of those
+settled the safe way, and the app's words kept.
+
 ## Modules
 
 ### `@connextar/house/errors`
@@ -548,6 +555,491 @@ PharmaLine (1.6.33).
 8. Copy: the security settings should say that adding a passkey asks for the
    code, the password, or a fresh sign-in, and that an email follows.
 
+### `@connextar/house/admin`, `/admin/second-factor`, `/admin/client`, `/admin/testing`
+
+Who may use administration, how an administrator sees the product as somebody
+else, and what the trail says about either.
+
+Six apps have platform administrators, and each wrote the same four things:
+a rule for who gets in, a Better Auth plugin recording which sessions used a
+second factor, a "view as", and a script to grant the first administrator. They
+agree on the rule and disagree on almost everything else. Three record prefixes,
+two places to record from (a database hook in AltEd, Quickie and PharmaLine, an
+after-hook in senco and FB Web), and two of the six forget that a revoked session
+outlives its cookie cache. FB Web lets any session minted by a signed-in one
+inherit the proof, so a passkey registration with `createSession: true` opened its
+admin tools with no code. AltEd's view-as cookie is unsigned by design. Nobody
+records an administrator signing in. This module is AltEd's model, made the
+default everywhere.
+
+| Entry point                            | What                                                                                   | Imports                |
+| -------------------------------------- | -------------------------------------------------------------------------------------- | ---------------------- |
+| `@connextar/house/admin`               | `adminAccess`, `decideAdminAccess`, `viewAs`, the write guard, audit events, bootstrap | `node:crypto` only     |
+| `@connextar/house/admin/second-factor` | `adminSecondFactorSessions()`, the Better Auth plugin                                  | `better-auth/api`      |
+| `@connextar/house/admin/client`        | `<AdminRefusalNotice>`, `<ViewingAsBanner>`                                            | React, `lucide-react`  |
+| `@connextar/house/admin/testing`       | `assertAdminGuardCoverage`, `memoryCookieJar`                                          | `node:fs`, `node:path` |
+
+`/admin` imports no Better Auth and no Prisma: every lookup is injected. That is
+what lets Canisters, which has its own auth, take the decision, the audit shape
+and "view as" as they are. The plugin is on its own subpath for the same reason.
+`entry-points.test.ts` follows the built imports to keep it that way.
+
+#### Who gets in
+
+```ts
+import { adminAccess } from "@connextar/house/admin";
+
+export const access = adminAccess(
+  {
+    isAdmin: async (id) =>
+      (await prisma.user.findUnique({ where: { id }, select: { platformAdmin: true } }))?.platformAdmin === true,
+    twoFactorEnabled: async (id) =>
+      (await prisma.user.findUnique({ where: { id }, select: { twoFactorEnabled: true } }))?.twoFactorEnabled === true,
+    sessionLive: async (id, userId) =>
+      (await prisma.session.count({ where: { id, userId, expiresAt: { gt: new Date() } } })) > 0,
+    // sessionProven: defaults to the plugin's record, read through `auth`
+  },
+  {
+    auth,
+    recordPrefix: "admin-second-factor:",
+    words: { "two-factor-off": { fixHref: "/settings?tab=security#two-factor" } },
+  },
+);
+
+const decision = await access.check(currentUser, { viewingAs: !!currentUser.impersonatedBy });
+// { ok: true } or { ok: false, reason, message, fixHref, status }
+```
+
+An administrator gets in only when all of these hold, checked in this order:
+
+| `reason`                        | Status | Refused when                                                                                      |
+| ------------------------------- | ------ | ------------------------------------------------------------------------------------------------- |
+| `signed-out`                    | 401    | Nobody is signed in.                                                                              |
+| `not-admin`                     | 403    | `isAdmin` is not `true`. Read from the database on every request, never from the session payload. |
+| `session-ended`                 | 401    | The session row is gone or expired.                                                               |
+| `two-factor-off`                | 403    | Two-factor is off for the account.                                                                |
+| `sign-in-without-second-factor` | 403    | This session was not made with the code, a backup code or a passkey.                              |
+| `viewing-as`                    | 403    | The request is a "view as". For that hour the administrator is not one.                           |
+
+- **`sessionLive` is always asked, from the session store.** Better Auth serves
+  a session from its cookie cache for minutes after it was revoked, and the
+  proof record outlives a revoked session. So "sign out everywhere" has to end
+  administration at once, not when the cache runs out. senco and FB Web fixed
+  this window in their own copies. The shared one cannot have it, because the
+  lookup is required.
+- **Fail-closed.** Only `true` counts for any fact. A lookup that answers
+  `undefined` refuses, and one that throws fails the request.
+- **A non-administrator costs one lookup.** The other three run together, in
+  one round trip, and only for administrators.
+- **The words are the app's.** `words` overrides the `message` and `fixHref`
+  of any reason. `adminRefusalFromParam(searchParams.admin, words)` gives the
+  settings page the same sentence the route refused with. `toString` and arrays
+  give `null`. `decideAdminAccess(facts, words)` is the pure decision, for an app
+  that gathers the facts itself (Canisters).
+- `AdminRefusalError` (`status`, `reason`, `refusal`) and
+  `assertAdminAccess(decision, makeError?)` are for code that answers by
+  throwing. Pass `makeError` to throw the app's own `ForbiddenError`.
+
+#### Server: the plugin
+
+```ts
+import { adminSecondFactorSessions } from "@connextar/house/admin/second-factor";
+
+plugins: [
+  twoFactor({ … }),
+  passkey({ … }),
+  secondFactorEverywhere(),
+  adminSecondFactorSessions({        // after twoFactor() and secondFactorEverywhere(), before nextCookies()
+    isAdmin: (id) => isPlatformAdmin(id),
+    recordPrefix: "admin-second-factor:",    // the app's existing prefix, so its sessions keep counting
+    onAdminSignedIn: (event) => writeAuditLog(event),
+  }),
+  stepUp({ … }),
+  magicLink({ … }),
+],
+```
+
+It replaces six copies. On Better Auth's own `session.create` database hook it
+writes a row in the `verification` table, `<recordPrefix><session id>`, holding
+the user's id and expiring with the session as it was issued. It does this only
+for an administrator's session made by:
+
+- `/two-factor/verify-totp` or `/two-factor/verify-backup-code`. That covers the
+  code at sign-in after a password, an email link or a social sign-in, and the
+  code that ends enrolment, which replaces the enrolling session;
+- `/passkey/verify-authentication`;
+- `/sign-in/email` for an account with two-factor on, when
+  `trustedDeviceCounts` is set (the default, AltEd's rule). The two-factor plugin
+  deletes that session straight after unless the device's trust cookie, which
+  only a correct code issues, lets it stand. A record for a deleted session
+  matches nothing.
+
+**Only `/change-password` inherits.** It carries over the proof of the session
+it replaces, and expires no later than that proof. Every other route that mints a
+session for a signed-in account proves nothing:
+`/passkey/verify-registration` with `createSession: true` (1.7), `/two-factor/disable`,
+`/two-factor/enable` with `skipVerificationOnEnable`, a social or email-link
+sign-in on a trusted device, `/verify-email`, `/two-factor/verify-otp`, and any
+route a later Better Auth adds. No record, no administration.
+
+**The back door is closed.** From a session without the record, an
+administrator cannot re-key two-factor (`/two-factor/enable` once it is on),
+read its key (`/two-factor/get-totp-uri`), make new backup codes, turn it off, or
+add a passkey. These answer `403 ADMIN_SECOND_FACTOR_REQUIRED`. Turning
+two-factor on for the first time stays open. With two-factor still off, a
+passkey waits (`403 ADMIN_PASSKEY_NEEDS_TWO_FACTOR`): a passkey added from a
+password-only session would become a way in that skips the code once enrolment
+is done. `stepUp()` still applies to everybody on top of this, and either
+refusal stops a registration.
+
+**A revoked session is refused on those routes for everyone, with a 401.** The
+routes' own `sessionMiddleware` believes the five-minute cookie cache. In FB Web,
+a signed-out administrator's kept cookies could read the authenticator's secret,
+make backup codes, re-key two-factor or register a passkey. The gate reads the
+session authoritatively and refuses a cookie whose row is gone or expired. A
+request with no session at all, such as a passkey-first sign-up, is left to the
+route.
+
+**`onAdminSignedIn(event, signIn)`** receives an `admin.signed_in` event for
+every session an administrator signs in with that is still standing when the
+response leaves, proven or not. The method is one of `code`, `backup-code`,
+`passkey`, `trusted-device`, `password`, `email-link`, `social` or `other`.
+It never fires for the password step that is still waiting for its code, for a
+password change, or for a two-factor change rotating the session. No app audits
+sign-ins today. The callback cannot fail the sign-in: an error is logged. With
+Better Auth's `advanced.backgroundTasks` set, it runs in the background. Because
+it has to see the session the two-factor hooks leave standing, `init` refuses to
+start if the plugin is listed before `twoFactor()` or `secondFactorEverywhere()`
+while `onAdminSignedIn` is set. Without the callback, the record does not depend
+on order.
+
+| Option                | Default                | What it does                                                                      |
+| --------------------- | ---------------------- | --------------------------------------------------------------------------------- |
+| `isAdmin`             | required               | Whether the account is an administrator now, read from the database.              |
+| `recordPrefix`        | `admin-second-factor:` | The record's prefix. Pass the app's existing one.                                 |
+| `trustedDeviceCounts` | `true`                 | A password sign-in on a trusted device counts, for an account with two-factor on. |
+| `onAdminSignedIn`     | none                   | The sign-in event, for the app's audit log.                                       |
+| `standing`, `scope`   | `"admin"`, platform    | The actor's standing and the event's scope.                                       |
+| `messages`            | the house's            | `factorChange`, `passkeyNeedsTwoFactor`.                                          |
+
+Expired records for the same account are swept whenever a new one is written.
+
+The tests (`admin/second-factor.test.ts`) run a real Better Auth instance with
+the memory adapter, the real `twoFactor`, `passkey` and `magicLink` plugins,
+`secondFactorEverywhere()` and `stepUp()`, a software authenticator that both
+registers and signs in, and requests through `auth.handler` with a cookie jar.
+They run against **1.7.2** and **1.6.33**, in the same two Vitest projects as
+`auth/second-factor`. One test pins what the plugin leans on: a database hook
+sees the creating route's path and, on a password change, the request's own
+session, which is already deleted by then. The sign-in event decides "proven"
+by the record's rule rather than reading the record back, because on 1.6 the
+database after-hook has not run yet when the endpoint's after-hooks do.
+
+#### View as
+
+```ts
+import { cookies } from "next/headers";
+import { viewAs, refuseWhileViewingAs, viewAsWriteGuard, allowWhileViewing } from "@connextar/house/admin";
+
+export const view = viewAs({
+  cookieName: "quickie_view_as",
+  secret: process.env.BETTER_AUTH_SECRET!,
+  cookies, // Next's cookies() fits as it is
+  access, // the app's adminAccess
+  audit: writeAuditLog,
+  names: async (id) => (await prisma.user.findUnique({ where: { id }, select: { name: true } }))?.name,
+});
+
+// POST /api/admin/view-as — after the route's admin guard and the app's own target lookup
+const started = await view.start(admin, { id: target.id, name: target.name }, requestMeta(request));
+// DELETE /api/admin/view-as — from the real session, which is not an admin while viewing
+await view.stop(realUser);
+// getCurrentUser(): every request
+const viewing = await view.read(realUser); // { targetId, adminId, expiresAt } or null; never writes
+```
+
+AltEd's rules, made safe by default:
+
+- **Signed.** The cookie is HMAC-SHA256 over the target, the administrator who
+  started it and the expiry, keyed by `secret` and the cookie name. An edited,
+  forged, re-signed or unsigned cookie (AltEd's format) is worthless. AltEd left
+  its cookie unsigned on the argument that only an administrator could use it.
+  That holds only while every reader checks the binding the same way. Signing
+  costs one HMAC and removes the question.
+- **Bound to the administrator, and only while they are one.** `read` checks the
+  real session against `adminAccess` on every request. A demotion, a revoked
+  session or a sign-in without the second factor ends the view at once. The
+  next person to sign in on a shared machine inherits nothing.
+- **Never another administrator.** Refused at `start`, and checked again on
+  every `read`, so a promotion mid-view ends it.
+- **Short.** Sixty minutes by default (`minutes`, at most a day). The expiry is
+  inside the signed value, so the server decides, not the browser.
+- **Recorded.** `admin.view_as_started` and `admin.view_as_stopped`, with the
+  administrator as the actor and `viewingAs` naming the person. `stop` works for
+  anybody signed in and records only when the view was that administrator's.
+- **Read-only.** `prisma.$extends(viewAsWriteGuard({ allow, getViewing }))`
+  refuses every write while viewing, except the app's allow-list of writes that
+  happen as a side effect of reading. The rule is inverted from "block what is
+  audited", which AltEd learnt the hard way: deleting an account ran
+  `session.deleteMany` and `passkey.deleteMany` before it reached the user row.
+  The guard is typed structurally, with no Prisma import. If an app's Prisma
+  types object, wrap it in `Prisma.defineExtension(…)`.
+
+  ```ts
+  viewAsWriteGuard({
+    allow: allowWhileViewing({
+      Session: ["update", "updateMany"], // Better Auth touching the operator's own session
+      RateLimit: ["create", "update", "upsert", "updateMany"], // the limiter keeps counting
+      AuditLog: ["create"], // the view's own start and stop
+    }),
+    getViewing: async () => (await getRequestActor())?.viewingAs ?? null,
+    makeError: (message) => new ForbiddenError(message),
+  });
+  ```
+
+- **Outside calls** (Stripe, GoCardless, Xero, AI, email, SMS) are refused by
+  default, not route by route. Quickie had to add `refuseWhileViewingAs` to thirty
+  handlers by hand, and the next route would have had to remember. Instead, build
+  one gate over the app's request actor and call it inside the app's own
+  wrappers. Every route that sends or charges through them is then covered:
+
+  ```ts
+  export const viewing = viewingAsGate({
+    getViewing: async () => (await getRequestActor())?.viewingAs ?? null,
+    makeError: (message) => new ForbiddenError(message),
+  });
+
+  export async function sendEmail(message: Email) {
+    await viewing.assertNotViewingAs("sending an email"); // fail-closed: a lookup that throws refuses too
+    return mailer.send(message);
+  }
+  ```
+
+  The gate reads the app's request-scoped actor rather than keeping an
+  `AsyncLocalStorage` of its own. The view is resolved inside `getCurrentUser`,
+  after its session read, and a store entered there does not propagate back to
+  the route's later calls (`view-as.test.ts` pins this). A `withViewingAs(…, fn)`
+  wrapper around each handler would bring back the per-route step the gate
+  exists to remove. Quickie's and AltEd's actor is keyed on Next's per-request
+  `headers()` object, which every call in a request shares.
+  `refuseWhileViewingAs(user, "starting a checkout", { makeError })` stays, for
+  explicit use first in a route.
+
+`start` refuses yourself and another administrator with a `400`, and an
+administrator who does not pass `adminAccess` with that refusal. It sets the
+cookie `httpOnly`, `sameSite: lax`, and `secure` in production.
+
+#### Audit
+
+```ts
+import type { AdminAuditEvent } from "@connextar/house/admin";
+
+const writeAuditLog = async (event: AdminAuditEvent) =>
+  prisma.auditLog.create({
+    data: {
+      organizationId: event.scope.kind === "tenant" ? event.scope.tenantId : null,
+      actorId: event.actor?.id ?? null,
+      actorName: event.actor?.name ?? null,
+      actorRole: event.actor?.standing ?? null,
+      action: event.action,
+      entityType: event.entity.type,
+      entityId: event.entity.id,
+      summary: event.summary,
+      changes: { ...event.changes, ...(event.viewingAs ? { viewingAs: event.viewingAs } : {}) },
+    },
+  });
+```
+
+`AdminAuditEvent` is `{ action, actor: { id, name, standing } | null, viewingAs?, scope: { kind: "platform" } | { kind: "tenant", tenantId }, entity: { type, id }, summary, changes?, at, ip?, userAgent? }`.
+Each app maps it to its own `AuditLog`; the house writes no table. The scope is
+stated outright, because the apps disagree: AltEd has no tenants, while Quickie
+and PM Tool record platform actions with a null `organizationId`. The builders
+are `adminSignedIn`, `roleChanged`, `viewAsStarted`, `viewAsStopped` and
+`platformAction`. Each trims `summary` to the apps' 300-character column.
+`requestMeta(request)` gives `{ ip, userAgent }`. `emitSafely(sink, event)` logs
+and swallows a sink's error, because recording must never break the thing being
+recorded.
+
+#### Bootstrap
+
+```ts
+// scripts/bootstrap-admin.ts
+import { bootstrapAdmin, bootstrapAdminArgs } from "@connextar/house/admin";
+
+const args = bootstrapAdminArgs(process.argv.slice(2)); // email, --force, --revoke, --allow-without-two-factor
+const result = await bootstrapAdmin(
+  {
+    findUser: (email) => prisma.user.findUnique({ where: { email } }).then(toBootstrapUser),
+    countAdmins: () => prisma.user.count({ where: { platformAdmin: true, deletedAt: null } }),
+    setAdmin: (id, isAdmin) => prisma.user.update({ where: { id }, data: { platformAdmin: isAdmin } }).then(() => {}),
+    twoFactorEnabled: async (id) => (await prisma.user.findUnique({ where: { id } }))?.twoFactorEnabled === true,
+    audit: writeAuditLog,
+  },
+  { ...args, standing: "platform-admin" },
+);
+console.log(result.message);
+process.exit(result.ok ? 0 : 1);
+```
+
+These are PM Tool's rules, the stricter of the two:
+
+- The account must exist, be verified and not be deleted. The script creates
+  nothing, as AltEd's did. An unverified row may be somebody else's sign-up with
+  this address.
+- The account must already have two-factor on. Otherwise whoever first holds
+  its mailbox or a session enrols the code that opens administration.
+- If an administrator already exists, the script refuses unless `--force` is
+  given. `--force` never skips two-factor.
+- **Every run is recorded**: the grant and the revoke as `user.role_changed`
+  with no actor, and a refusal as `admin.bootstrap_refused`. If the trail cannot
+  be written, the script throws, because a person is watching it.
+- `--allow-without-two-factor` is the documented first-run escape, for a
+  deployment whose only way to turn two-factor on is behind administration. It
+  works only while no administrator exists, and the event records that it was
+  used. `adminAccess` still refuses that administrator until they turn
+  two-factor on and sign in with it.
+- An option the parser does not know is an error, so a typo never quietly
+  grants without the flag that was meant.
+
+#### The client
+
+```tsx
+import { AdminRefusalNotice, ViewingAsBanner } from "@connextar/house/admin/client";
+
+// Settings › Account & security, from ?admin=
+<AdminRefusalNotice refusal={adminRefusalFromParam(searchParams.admin, access.words)} />
+
+// The root layout, while a view is in force
+<ViewingAsBanner name={user.name} expiresAt={view.expiresAt} onStop={stopViewing} />
+```
+
+Both are drawn on the shared theme tokens (`destructive`, `primary`, `muted`,
+`border`), with every label and class overridable. The notice draws nothing
+without a refusal, and draws no link where there is nowhere to go. The banner is
+sticky and has no close button: the only way to make it go is to stop. A
+refusal thrown by `onStop` is reported through the app's
+`ActionFeedbackProvider`, and the banner stays.
+
+#### Testing: the guard-coverage sweep
+
+```ts
+import { assertAdminGuardCoverage } from "@connextar/house/admin/testing";
+
+it("every admin surface goes through the guard", () => {
+  const report = assertAdminGuardCoverage({
+    apiDirs: ["app/api/admin"],
+    pageDirs: ["app/dashboard/admin"],
+    apiGuard: "requirePlatformAdmin",
+    pageGuard: "requirePlatformAdminPage",
+    exempt: { "app/api/admin/view-as/route.ts DELETE": "stopping a view grants nothing" },
+    flagReaders: {
+      pattern: /platformAdmin|isPlatformAdmin/,
+      dirs: ["app", "components", "lib"],
+      allowed: { "lib/server/session.ts": "the guard itself", "components/dashboard/nav.tsx": "display prop" },
+      ignore: (file) => file.startsWith("lib/db/generated/"),
+    },
+    minimum: { routes: 6, pages: 14 },
+  });
+  expect(report.handlers.length).toBeGreaterThanOrEqual(12);
+});
+```
+
+This is PharmaLine's `admin-guard.test.ts`, the strongest of the apps', with
+Quickie's escape checks added. It reports every problem at once:
+
+- the guard is the **first `await`** of every route handler, not merely called
+  after a body was parsed or a row read. It looks in route files under the pages
+  folder too;
+- a handler exported in a form the sweep cannot read (`export const GET`,
+  `export { x as GET }`, a non-async `function`) is reported;
+- every page file awaits the page guard itself, because a layout is not
+  re-rendered between its children (PM Tool);
+- a `"use server"` file under either folder is reported, since it is an endpoint
+  the sweep cannot see;
+- only allow-listed files mention the raw flag, and an entry that no longer
+  mentions it is reported too;
+- a missing folder, an exemption naming no handler, or fewer files than
+  `minimum` is a problem, so a moved folder cannot pass with nothing checked.
+
+Comments are stripped when looking for the guard and kept when looking for the
+flag. `memoryCookieJar()` stands in for `cookies()` in an app's own "view as"
+tests.
+
+#### Adopting it in an app
+
+The owner approved building it on AltEd's model and adopting it in phases,
+offering "view as" in every app with platform administrators, and requiring
+two-factor for MAS operators.
+
+**(a) Swap the plugin and the guard, behaviour unchanged.** AltEd, Quickie,
+senco, PharmaLine, PM Tool and FB Web.
+
+1. Bump `@connextar/house`.
+2. In `auth.ts`, replace the app's own plugin, or its `databaseHooks` recorder
+   and `hooks.before` factor-change refusal, with `adminSecondFactorSessions()`.
+   List it after `twoFactor()` and `secondFactorEverywhere()`. **Pass the app's
+   existing prefix**, so sessions already proven stay proven:
+
+   | App        | `recordPrefix`            | Replaces                                                                                     |
+   | ---------- | ------------------------- | -------------------------------------------------------------------------------------------- |
+   | AltEd      | `admin-second-factor:`    | `lib/auth/admin-second-factor.ts` (`recordSecondFactorSession`, `refuseAdminFactorChange`)   |
+   | Quickie    | `operator-second-factor-` | `lib/admin/operator-access.ts` (`recordSecondFactorSignIn`, `operatorSecurityChangeRefusal`) |
+   | PharmaLine | `admin-second-factor:`    | `lib/auth/second-factor-session.ts` (`adminSecondFactor()`)                                  |
+   | PM Tool    | `second-factor-session:`  | `lib/auth/second-factor-session.ts`                                                          |
+   | senco      | `second-factor-session:`  | `lib/auth/second-factor-session.ts` (`secondFactorSessions()`)                               |
+   | FB Web     | `second-factor-session:`  | `lib/auth/second-factor-session.ts` (`secondFactorSessions()`)                               |
+
+3. Rebuild the app's guard on `adminAccess(…)`. AltEd's `adminGateFor`,
+   Quickie's `platformAdminRefusal`, PharmaLine's `platformAdminAccess`, PM
+   Tool's `checkAdminAccess` and the others keep their names and callers. Their
+   bodies become `access.check(…)`, and their reasons map onto the shared ones.
+   Pass each app's sentences and `fixHref`s in `words`, so every refusal says
+   what it said before.
+4. Keep the app's own tests of its refusals, and make them pass unchanged. Then
+   replace its guard-coverage test with `assertAdminGuardCoverage` and the same
+   allow-list.
+5. Three things change on purpose, and the tests say so:
+   - **Inheritance is `/change-password` only.** FB Web's plugin let any session
+     made by a signed-in one inherit (passkey `createSession: true`,
+     `/two-factor/disable`, a trusted-device social sign-in). AltEd let any
+     same-account session inherit.
+   - **A revoked session gets a 401 on the factor-change routes**, for everyone,
+     and administration reads `sessionLive` every time. PharmaLine and PM Tool
+     did not check that the session was live.
+   - **An administrator's passkey waits for two-factor, and only first
+     enrolment is open while it is off.** Quickie let an operator without
+     two-factor add a passkey, and AltEd and Quickie left every two-factor route
+     open while it was off. No app's screens call those routes then.
+
+**(b) Audit scope and sign-in events.** Map `AdminAuditEvent` to each app's
+`AuditLog`. Quickie and PM Tool's nullable `organizationId` takes
+`scope.kind === "platform"`; AltEd, with no tenants, ignores the scope. Pass the
+sink as `onAdminSignedIn`, and record role changes through `roleChanged` and
+operator actions through `platformAction` (PM Tool's `recordPlatformAction`
+becomes a call to it). Move each bootstrap script onto `bootstrapAdmin`. AltEd's
+stops creating accounts and starts requiring two-factor.
+
+**(c) "View as" in every app with platform administrators.** AltEd and Quickie
+move their cookie onto `viewAs` (the signed cookie replaces the old one, so a
+view in progress at deploy ends once) and their Prisma guard onto
+`viewAsWriteGuard` with their existing allow-lists. senco, PharmaLine, PM Tool
+and FB Web gain it: a `POST`/`DELETE /api/admin/view-as` route, `view.read` in
+`getCurrentUser`, the write guard, `viewingAsGate().assertNotViewingAs()` inside
+the app's email, SMS, payment and AI wrappers, and `<ViewingAsBanner>` in the
+root layout. Quickie moves its thirty `refuseWhileViewingAs` calls into its
+wrappers the same way.
+
+**(d) The apps without the pieces yet.**
+
+- **MAS** first adds Better Auth's `twoFactor`, because its operators must use
+  two-factor and today nothing can record a second factor. Then it takes phase
+  (a) whole.
+- **The Stripe gateway** adds two-factor for its operators and an audit table to
+  map events into.
+- **Canisters** has its own auth, so it takes only `decideAdminAccess` (it
+  gathers the facts itself), the audit event shape, and "view as". `/admin`
+  imports no Better Auth for exactly this reason.
+
 ### `@connextar/house/account`
 
 The contract for "your data" and "delete my account" — types, the export notice,
@@ -635,6 +1127,159 @@ showed no kind (0.16.0), and a release shown above a hidden, unreviewed one was
 measured against the wrong version. An app that worked out the kind itself can
 drop that and pass `publicChangelog(CHANGELOG)` straight in.
 
+### `@connextar/house/whats-new`
+
+The dialog that tells a signed-in person what changed since they last looked,
+from the changelog the app already keeps. Without it, a `changed` entry that
+says what to do now is read only by whoever happens to open `/changelog`.
+
+The app stores one thing — the version someone last saw, in a nullable column —
+and everything else follows from it and `CHANGELOG`:
+
+- **Only the public's words.** `whatsNew` runs on the server, in the signed-in
+  layout. It reads reviewed releases only, drops internal changes and sections,
+  uses each change's `public` wording, and leaves out the generic "Behind the
+  scenes" line. What reaches the browser is what the public changelog would say.
+- **New or changed, or nothing.** It opens when there is something `new` or
+  `changed` since the stored version. A week of fixes and improvements waits
+  for the next one, and is in the count when it comes. It leads with `changed`
+  — someone may need to act — then `new`, then `improved`, newest release first,
+  five at most, "And 12 more." after them.
+- **A new account is not greeted by a hundred releases.** No stored version (or
+  one that isn't a version) means nothing shown and `stampSilently`: the hook
+  stores the newest version without a word, and the first dialog that person
+  sees is for the first release after they arrived. Adding the column therefore
+  greets nobody on the day it ships; the next release is the first anyone hears
+  about.
+- **Once, and however it closes.** It opens once on mount. The button, Escape, a
+  click outside and following the changelog link all count as seen: the dialog
+  closes at once and the newest version is stored. A save that fails is
+  reported through the app's `ActionFeedbackProvider` and the dialog stays shut
+  for the visit — asking again next time is the honest outcome of a failed
+  save, reopening now is not.
+- **Never while viewing as someone.** `readOnly` keeps it shut and stores
+  nothing, and the seen route refuses the write as well.
+
+```ts
+// app/(signed-in)/layout.tsx — on the server
+const options = { minDaysBetween: 7 }; // AltEd and PharmaLine; the rest leave it at 0
+const news = viewingAs || !inAudience ? null : whatsNew(CHANGELOG, user.lastSeenReleaseVersion, options);
+```
+
+```tsx
+// components/whats-new-dialog.tsx — "use client"; the layout renders <WhatsNewDialog initial={news} … />
+const news = useWhatsNew({ initial, markSeen, readOnly: viewingAs });
+if (!news.data) return null;
+
+<Dialog open={news.open} onOpenChange={news.setOpen}>
+  <DialogContent>
+    <DialogTitle asChild>
+      <WhatsNewTitle />
+    </DialogTitle>
+    <WhatsNewBody data={news.data} changelogHref="/changelog" title={false} onChangelogClick={news.onChangelogClick} />
+    <WhatsNewActions onDismiss={news.dismiss} />
+  </DialogContent>
+</Dialog>;
+```
+
+**The dialog is yours**, as the setup guide's panel is: every app already has
+one, with its own idea of how it appears and where focus goes, so this ships
+what goes inside it. `WhatsNewTitle` is an `<h2>` that passes its props through
+(so Radix's `DialogTitle asChild` names the dialog by it); `WhatsNewBody` is the
+count, the tagged highlights — the changelog's own tags, `tagClassNames` and
+`renderReleaseText` — and "See everything in the changelog", which goes to the
+newest release they hadn't seen (`/changelog#v1-4-0`); `WhatsNewActions` is a
+**Got it** button. A hand-rolled dialog keeps the body's title and gives it an
+id with `titleId` for `aria-labelledby`; MUI puts the three in its `Dialog`
+the same way Radix does. `labels` and `link` take the app's words and router.
+Theme tokens only, and `entry-points.test.ts` holds the module to React — no
+dialog primitive, router or toast library.
+
+**Options worth knowing.**
+
+- `minDaysBetween: 7` — for an app that releases several times a day. It waits
+  that many days after the stored version's release date. No second column is
+  needed: dismissing stores the newest release there was, so its date is close
+  to when the dialog was last seen (exactly so for an app shipping daily).
+  A stored version the changelog doesn't hold has nothing to wait for.
+- `role` — matched against the optional `roles` on a change or a section, so a
+  change for guardians can be kept from children. A scoped change is shown to
+  its roles only, and to nobody when no `role` is passed.
+- `highlight: true` on a change puts it in the dialog whatever its type or
+  heading (and is guaranteed a place); `highlight: false` keeps it out. Both
+  fields are checked by `releaseHistoryProblems` and ignored by both
+  changelogs — [`docs/ReleaseProcess.md`](docs/ReleaseProcess.md) §3.
+- `maxItems`, `highlightTypes`, `showFor`, `skipHeadings` change the defaults
+  above; `now` pins the clock in a test.
+
+Unseen is decided by version number, not by finding the stored version in the
+history, so a version since trimmed from the changelog still works, and one
+newer than the changelog (after a rollback) has nothing unseen and stores
+nothing.
+
+#### Adoption, per app
+
+Each app adds three things.
+
+1. **The column**, on the user. Null for everyone at first, which is right (see
+   above).
+
+   ```prisma
+   model User {
+     // …
+     lastSeenReleaseVersion String?
+   }
+   ```
+
+   `npx prisma migrate dev --name whats_new_last_seen` — one nullable column, no
+   backfill. An app that _wants_ to announce the release it ships with
+   backfills the previous version instead.
+
+2. **`POST /api/whats-new/seen`**, which checks the body before it stores it
+   and never moves backwards:
+
+   ```ts
+   import { acceptSeenVersion } from "@connextar/house/whats-new";
+
+   export async function POST(request: Request) {
+     const session = await requireSession(); // the app's own; 401 without one
+     if (session.viewingAs) return Response.json({ error: "Viewing as someone." }, { status: 403 });
+     const body = await request.json().catch(() => null);
+     const user = await prisma.user.findUniqueOrThrow({
+       where: { id: session.userId },
+       select: { lastSeenReleaseVersion: true },
+     });
+     const result = acceptSeenVersion(body, CHANGELOG, user.lastSeenReleaseVersion);
+     if (!result.ok) return Response.json({ error: result.reason }, { status: 400 });
+     await prisma.user.update({ where: { id: session.userId }, data: { lastSeenReleaseVersion: result.version } });
+     return Response.json({ ok: true });
+   }
+   ```
+
+   `markSeen` is a `fetch` to it with `keepalive: true` — following the
+   changelog link can unload the page while the request is in flight — that
+   resolves `response.ok`.
+
+3. **The dialog**, mounted once in the signed-in layout, with `whatsNew`
+   computed there on the server. Pass `null` to anyone outside the audience
+   rather than mounting it conditionally, so the decision stays in one place.
+
+| App        | Mount                                  | Audience                        | Options             |
+| ---------- | -------------------------------------- | ------------------------------- | ------------------- |
+| AltEd      | the signed-in layout, **not** `/learn` | everyone outside `/learn`       | `minDaysBetween: 7` |
+| PharmaLine | the signed-in layout                   | everyone signed in              | `minDaysBetween: 7` |
+| KRP        | the signed-in layout                   | guardians only — never children |                     |
+| MAS        | the signed-in layout                   | workspace managers only         |                     |
+| The rest   | the signed-in layout                   | everyone signed in              |                     |
+| Every app  | —                                      | nobody while viewing as someone | `readOnly`          |
+
+AltEd ships about twenty-five releases a week and PharmaLine about ten; without
+`minDaysBetween` either could greet someone every day. A week's worth is more
+than the public changelog's five, so the link goes to the newest unseen release
+at the top of the page; an app whose signed-in readers should be able to scroll
+back through all of them passes a larger `limit` to `publicChangelog` on the
+page, or pages it.
+
 ### `@connextar/house/markdown`
 
 The help-centre guide renderer, and the GitHub-flavoured table parser under it.
@@ -665,6 +1310,40 @@ export function Markdown({ content }: { content: string }) {
 ```
 
 `classNames` replaces the look of any element for an app without theme tokens.
+`table` and `figure` are each a set of parts merged over the house's, and both are
+optional: an app that writes out a whole `GuideClassNames` in its own palette
+(KRP) leaves out the ones it doesn't restyle and gets the house's table and
+picture classes. (`figure` was required in 0.18.0 alone, so such an app failed
+typecheck until it added `figure: {}`.) A part added to a class-names or labels
+type after it first shipped is optional for the same reason.
+
+**Pictures.** A guide names a screenshot or a diagram on a line of its own, with a
+blank line either side:
+
+```md
+![The calls log, newest call first, with the ID-checked column](/guide-images/calls-log.webp "Every call, newest first")
+
+![A caller reaches the line, then the assistant answers or hands over](diagram:call-routing)
+```
+
+`GuideMarkdown` draws one only when it is in the app's registry, `figures` — a
+screenshot with its `width` and `height` (so the page doesn't jump as it loads) and
+optionally a `dark` capture of the same size, or a diagram by name — and has alt
+text; anything else is left out, so a guide can't pull an image in from elsewhere
+and a typo never shows a broken image. (Before 0.18.0 such a line came out as a
+`!` and a link.) A screenshot is a plain lazy `<img>`; with a `dark` capture both
+are drawn and the theme's `dark:` variant shows one; without one, the light
+picture is toned down a little on a dark page. A diagram registered as a component
+is given the alt text as `label` for its own `<svg role="img" aria-label>`; one
+registered as an element is wrapped in `role="img"`. Headings keep their ids
+across pictures, and a picture ends a list.
+
+`guideFigureProblems(body, figures, { minAltLength })` is the check an app's test
+asserts empty for every guide: an unregistered picture, missing (or too short) alt
+text, a picture without a blank line either side or indented as if in a list, and
+an image written inside a line of text. `splitGuideFigures` is the same split as
+data; `renderFigure` replaces the drawing. `GuideArticle` adds zoom — see
+[Pictures and zoom](#pictures-and-zoom).
 
 ### `@connextar/house/guides`
 
@@ -706,6 +1385,177 @@ export default async function GuidePage({ params }) {
 }
 ```
 
+#### Pictures and zoom
+
+Pass the registry and `GuideArticle` draws a guide's pictures
+([the Markdown](#connextarhousemarkdown)), each one a button with a zoom-in cursor
+and a hint under the picture, right-aligned above the caption: "Click to enlarge",
+or "Tap to enlarge" on a touch screen. Both words are in the HTML and
+`@media (pointer: coarse)` (Tailwind's `pointer-coarse:`) shows one, so it is right
+before any script runs. The hint sits under the picture rather than over its
+corner, so it never covers part of a small diagram on a phone (at 375px it used to
+sit on a box of PharmaLineAI's call-routing diagram). A click, Enter or Space opens it in a
+dialog fitted to the screen (the whole screen on a phone):
+
+- zoom with the buttons, `+` and `−`, ⌘/Ctrl + scroll (a trackpad pinch arrives as
+  one) or a touch pinch, from fit up to four times full size, at the pointer;
+- when it is bigger than the screen, drag it, scroll it, or move it with the arrow
+  keys — never past its edges;
+- a double-click or double-tap, or the zoom level between the buttons, switches
+  between fit and full size (one image pixel to one CSS pixel); `0` fits again;
+- the caption and the alt text are shown under it; Escape or the close button
+  closes it and focus goes back to the picture. Zoom eases only without
+  `prefers-reduced-motion`; dragging and pinching never do.
+
+Diagrams zoom too. They are vector, so the dialog lays the diagram out at the size
+it had in the article and scales it: fit fills the screen, and "full size" is twice
+the fit. `zoom={false}` draws plain pictures. `labels` changes the words (`zoomHint`,
+`zoomHintTouch` — left out, it is your `zoomHint` if you set one, else "Tap to
+enlarge" — `zoomOpen`, `zoomIn`, `zoomOut`, `zoomToggle`, `zoomLevel`, `zoomClose`,
+`zoomInstructions`), `classNames.figure` the picture's parts and `zoomClassNames`
+the button and dialog's (`GUIDE_ZOOM_CLASS_NAMES` lists them; `hint` is the row
+under the picture, `hintPointer` and `hintTouch` the two sets of words), all on the theme
+tokens. `GuideFigure` and `GuideFigureZoom` are there for a page laid out without
+`GuideArticle`. The zoom's classes appear only in this package, so the
+[Tailwind `@source`](#tailwind-setup-required-for-every-component) line is what
+styles it.
+
+Adopting it (PharmaLineAI's v0.23.1 pictures, which this generalises):
+
+1. **Screenshots** live in `public/guide-images/`, as WebP about 1600px wide (sharp
+   in a 768px column on a 2× screen) and under ~150 KB each. A dark capture, if
+   the app makes one, sits beside it at the same size (`calls-log-dark.webp`).
+2. **The registry.** Sizes in `lib/guide-screenshots.json`, written by the capture
+   script, and the diagrams beside them:
+
+   ```json
+   {
+     "/guide-images/calls-log.webp": { "width": 1600, "height": 986 },
+     "/guide-images/overview.webp": { "width": 1600, "height": 506, "dark": "/guide-images/overview-dark.webp" }
+   }
+   ```
+
+   ```tsx
+   // lib/guide-figures.tsx
+   import type { GuideFigures } from "@connextar/house/markdown";
+
+   import { CallRouting, IdentityCheck } from "@components/guides/guide-diagrams";
+   import screenshots from "@lib/guide-screenshots.json";
+
+   export const GUIDE_FIGURES: GuideFigures = {
+     screenshots,
+     diagrams: { "call-routing": CallRouting, "identity-check": IdentityCheck }, // each takes { label }
+   };
+   ```
+
+3. **The pages** pass it: `<GuideArticle … figures={GUIDE_FIGURES} />`, on the public
+   and the signed-in guide pages alike. A diagram component is drawn on the server;
+   only what it drew crosses into the dialog.
+4. **The app's test** reads the real guides:
+
+   ```ts
+   for (const { slug } of GUIDES) {
+     expect(guideFigureProblems(body(slug), GUIDE_FIGURES, { minAltLength: 20 }), slug).toEqual([]);
+   }
+   ```
+
+   and, because the package can't see the app's disk, checks the files: every
+   registered screenshot (and `dark`) exists at its recorded size (the app's own
+   `sharp`), every file in `public/guide-images/` is registered and used, all
+   WebP and small.
+
+5. **Capturing them (optional).** PharmaLineAI's `scripts/guide-screenshots.ts` is
+   the pattern, and stays in the app — this package ships no Playwright. It runs
+   only against the local harness (it refuses any base URL that isn't
+   `localhost`/`127.0.0.1`), signed in as the seeded owner from the harness's
+   cookie jar, in headless Chromium at 1440px, 2× pixels, light mode and reduced
+   motion. Each shot names a page, an optional `before` step (open a call, pick a
+   setting), and a crop to the panel its guide talks about, found from the page
+   (a heading, a bordered card). It hides the dev overlay, replaces seed text a
+   public page mustn't show (a real brand in a seed name), puts back any seed data
+   it changed for a shot in a `finally`, resizes to 1600px WebP with sharp, and
+   writes the sizes to `lib/guide-screenshots.json`. A dark set is the same run
+   with `colorScheme: "dark"` writing `-dark.webp` files and each entry's `dark`.
+
+PharmaLineAI's own `components/guides/guide-article.tsx` and the split in
+`lib/guide-figures.ts` go; its diagrams and its JSON stay, and its list of diagram
+names becomes the `diagrams` record.
+
+### `@connextar/house/health`
+
+A liveness check that says which release is running, so a deploy can be confirmed
+from outside: `curl https://app.example/healthz` answers `ok 0.18.0 2c9a3cf`.
+From PharmaLineAI's voice relay (v0.24.1), for every app.
+
+- `buildInfo(version, env = process.env)` → `{ version?, commit? }`. The version
+  must be semver-shaped (`1.2.3`, `1.2.3-rc.1`); the commit is the first of
+  `VERCEL_GIT_COMMIT_SHA`, `RENDER_GIT_COMMIT` and `GIT_COMMIT` that is a whole
+  hex hash, cut to 7. Anything else is dropped, never echoed: the endpoint is
+  public.
+- `healthText(build)` → `ok 1.2.3 abc1234` (just `ok` when nothing is known).
+- `healthResponse(build, { format })` → always 200, `Cache-Control: no-store`;
+  `text/plain` by default, `{ "status": "ok", "version", "commit" }` for
+  `format: "json"`. `healthFormat(request)` picks: `?format=json|text`, then an
+  `Accept` that names `application/json`; a browser, curl and a host's checker get
+  text.
+- `createHealthRoute({ version })` → `{ GET }`, the two above as a Next route
+  handler. Next answers `HEAD` from `GET` itself. No Next import, no package at all:
+  it is web `Request` and `Response`.
+
+The whole adoption is one file, `app/healthz/route.ts` (`src/app/…` adds a `../`):
+
+```ts
+import { createHealthRoute } from "@connextar/house/health";
+
+// A route handler is server-only, so package.json is bundled into the server and never reaches the browser.
+import pkg from "../../package.json";
+
+export const { GET } = createHealthRoute({ version: pkg.version });
+```
+
+(Next's default `tsconfig` has `resolveJsonModule`.) **Not**
+`process.env.npm_package_version`: npm sets it only in a process npm itself
+started — `node -e 'console.log(process.env.npm_package_version)'` prints
+`undefined`, and the same line under `npm run` prints the version. A Vercel
+function is started by Vercel's runtime, not `npm start`, so it is unset when the
+route runs; it is set during `npm run build`, so it could be inlined through
+`next.config`'s `env`, but only for as long as the build goes through npm. It works
+on Render under `npm start`, which is why it looks reliable until it isn't.
+
+The commit: Vercel sets `VERCEL_GIT_COMMIT_SHA` on Git deployments while "Automatically
+expose System Environment Variables" is on (the default); Render sets
+`RENDER_GIT_COMMIT`; anywhere else, set `GIT_COMMIT`. On Render, point the service's
+Health Check Path at `/healthz`; it needs the 200 and nothing else. A plain Node
+server (PharmaLineAI's relay) uses `buildInfo` and `healthText` directly.
+
+**Let it through.** `/healthz` must answer without signing in: exclude it from the
+app's `proxy.ts` (`middleware.ts` before Next 16) — e.g.
+`matcher: ["/((?!healthz|_next/static|_next/image|favicon.ico).*)"]` — and from any
+auth redirect, maintenance switch or locale rewrite in it. Vercel Deployment
+Protection on preview deployments answers 401 before the app does; that is
+expected, and production should be unprotected.
+
+**Liveness only.** It touches no database and no provider, so it can't be slow and
+a provider's outage never makes a host restart a healthy app. An app that wants a
+readiness check writes its own, separately — never as the host's health check:
+
+```ts
+// app/readyz/route.ts — the app's own; says only ready / not ready
+export async function GET() {
+  const ok = await Promise.race([
+    prisma.$queryRaw`select 1`.then(
+      () => true,
+      () => false,
+    ),
+    new Promise<boolean>((resolve) => setTimeout(() => resolve(false), 2000)),
+  ]);
+  return new Response(ok ? "ready" : "not ready", {
+    status: ok ? 200 : 503,
+    headers: { "cache-control": "no-store", "content-type": "text/plain; charset=utf-8" },
+  });
+}
+```
+
 ### `@connextar/house/trail`
 
 Where you came from, rather than where the URL says you are. A breadcrumb built