@connextar/house 0.11.0 → 0.13.0

package/README.md

@@ -67,7 +67,18 @@ caller's own organisation — and both printed a job's result as its variable
 names, so production read "0 chargesRaised · 0 totalOutstanding", with an amount
 of money shown as a number of things. The module is their union, with that
 made impossible rather than fixed: a count reaches the screen only through a
-declaration that says its words and its kind.
+declaration that says its words and its kind. 0.12.0 lets a job offer Run now
+to owners and operators both — Quickie's operators could not re-run a failed
+overnight sweep of a per-organisation job — and prunes the ledger without ever
+deleting a row health is read from.
+
+`password`, in 0.13.0, is the other case in the rule: something ten apps were
+each about to write. None of them can show a password being typed, and the one
+strength meter in the portfolio is a checklist "Password1!" passes. A reveal
+toggle is easy to write and easy to get quietly wrong — a revealed password
+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.
 
 ## Modules
 
@@ -131,6 +142,178 @@ possession of a device and is phishing-resistant; a social login delegates to a
 provider enforcing its own second factor. Neither is weaker than password plus
 TOTP. A link in an inbox is.
 
+### `@connextar/house/auth/second-factor`
+
+The code screen after a magic link and after a social sign-in, so every sign-in
+path treats two-factor the same way.
+
+Better Auth's `twoFactor` plugin only intercepts the password routes
+(`/sign-in/email`, `/sign-in/username`, `/sign-in/phone-number`). A magic link
+(`/magic-link/verify`) and a Google, Microsoft or Apple callback (`/callback/:id`)
+hand out a full session with no code. Until now the house apps refused magic
+links for two-factor accounts, and let social sign-in skip the code.
+`secondFactorEverywhere()` fixes both. For an account with two-factor on, a magic
+link or a social sign-in now ends up exactly where a password sign-in does:
+
+- **No session survives.** The session the route just created is deleted, and
+  its cookies (including the cached `session_data`) are expired.
+- **The pending state is Better Auth's own.** It uses the same signed
+  `two_factor` cookie and verification row, so `/two-factor/verify-totp` and
+  `/two-factor/verify-backup-code` finish the sign-in unchanged. Attempt limits,
+  account lockout and "trust this device" all keep working.
+- **A trusted device skips the code** under the plugin's own rule, and its trust
+  cookie is rotated.
+- **The browser goes to the code screen** instead of `callbackURL`. The original
+  destination comes along as `?next=`, but only when it is a path on this site.
+  Another origin (even one Better Auth trusts), `//host`, `/\host` and
+  `javascript:` are all dropped.
+- **A JSON caller**, such as a magic-link verify without `callbackURL` or
+  `/sign-in/social` with an `idToken`, gets the plugin's own
+  `{ twoFactorRedirect: true }`. `twoFactorClient`'s `onTwoFactorRedirect`
+  already handles that.
+
+Passkeys stay a single step. A passkey proves possession of a device and resists
+phishing, so it is excluded and cannot be added to the list.
+
+**How it works.** This module copies none of Better Auth's pending-state
+internals: no cookie names, no signing, no identifiers. On these routes it runs
+the two-factor plugin's own password-sign-in after-hook, then turns the plugin's
+`{ twoFactorRedirect: true }` into a redirect to the code screen. It depends on
+three things, and `second-factor.test.ts` pins each of them against the installed
+Better Auth:
+
+- the plugin exposes that hook;
+- the hook still covers only the password routes;
+- the hook answers `twoFactorRedirect` when it takes the session away.
+
+`init` also refuses to start if it cannot find the hook. The tests run a real
+Better Auth instance (memory adapter, the real `twoFactor` and `magicLink`
+plugins, a stub OAuth provider, requests through `auth.handler` with a cookie
+jar) against both lines the apps use. The `house` Vitest project runs them
+against **1.7.2**. The `better-auth-1.6` project runs them against **1.6.33**
+(`better-auth-1-6`, an npm alias, re-pointed with a Vitest alias). The supported
+peer range is `>=1.6.33 <1.8.0`. Before you widen it, update the dev dependency
+and read the new two-factor plugin.
+
+#### Server
+
+```ts
+import { secondFactorEverywhere } from "@connextar/house/auth/second-factor";
+
+plugins: [
+  twoFactor({ … }),
+  passkey({ … }),
+  secondFactorSessions(),          // the app's own proof recorder: unchanged
+  secondFactorEverywhere(),        // after twoFactor(), before nextCookies()
+  magicLink({ … }),
+],
+```
+
+| Option           | Default                                 | What it does                                                                                                                                                                                |
+| ---------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `codeScreenPath` | `/auth/two-factor`                      | Where the code screen is. Every house app already uses this path.                                                                                                                           |
+| `nextParam`      | `next`                                  | The query parameter that carries the destination.                                                                                                                                           |
+| `appOrigin`      | origin of Better Auth's `baseURL`       | The origin of the code screen, and the only origin a `next` may point to.                                                                                                                   |
+| `routes`         | all of `SECOND_FACTOR_CHALLENGE_ROUTES` | `/magic-link/verify`, `/callback/:id`, `/oauth2/callback/:providerId`, `/sign-in/social` (idToken), `/one-tap/callback`, `/sign-in/email-otp`. A route that is not installed never matches. |
+| `providers`      | `"all"`                                 | Limits the social routes to these provider ids, e.g. `["google", "microsoft"]`.                                                                                                             |
+| `enabled`        | `true`                                  | Set it to `false` to opt this app out and keep the plugin listed. The old magic-link refusal comes back (see below).                                                                        |
+
+**Composing with `second-factor-session`.** Your existing plugin needs no change.
+The session a magic link or a social callback creates is deleted before the
+response goes out. The session that counts is created by
+`/two-factor/verify-totp` or `/two-factor/verify-backup-code`, and your plugin
+already records those as proven. The tests check this with a stand-in recorder.
+
+One optional refinement: on a trusted device, a magic-link or social session
+survives, just as `/sign-in/email` does today. Your plugin does not count that
+session as proven, so an administrator is asked to sign in again. That fails
+safe. If you want those sessions to count the way `/sign-in/email` does, extend
+your `provesSecondFactor` rule with care: `providers` can leave some callbacks
+unchallenged.
+
+#### The code screen
+
+When the code or backup code is accepted, go to the safe `next`:
+
+```ts
+import { secondFactorNext } from "@connextar/house/auth";
+
+const { error } = await authClient.twoFactor.verifyTotp({ code, trustDevice });
+if (!error) router.replace(secondFactorNext(searchParams)); // "/" if next is missing or unsafe
+```
+
+`@connextar/house/auth` does not import Better Auth, so client components can use
+it. `safeNextPath(candidate, fallback)` is the rule underneath.
+
+#### Retiring the magic-link refusal
+
+Pass the hook's `ctx.context` as a fourth argument to `shouldBlockForTwoFactor`:
+
+```ts
+if (await shouldBlockForTwoFactor(ctx.path, email, lookup, ctx.context)) throw new APIError("BAD_REQUEST", { … });
+```
+
+While `secondFactorEverywhere()` is installed, enabled and covering
+`/magic-link/verify`, the refusal steps aside and skips the lookup
+(`magicLinkRefusalRetired(ctx.context)`). If the challenge is ever switched off,
+the refusal comes back by itself, so turning the challenge off cannot quietly
+reopen the magic-link hole. You can delete the refusal outright once every
+environment runs the plugin. Keeping the fourth argument is the safe middle
+ground.
+
+#### Email link scanners
+
+Link scanners such as Microsoft Defender Safe Links, Mimecast and Proofpoint open
+the link before the person does. A magic link works only once, so the scanner
+uses it up. With two-factor on, the scanner gets only the pending code state
+(never a session), and the person's own click lands on `?error=INVALID_TOKEN`.
+Without two-factor it was already this way, except that the scanner got a full
+session. A test pins this behaviour.
+
+**Mitigation, optional and simple:** put a confirm page between the email and the
+verify URL. Scanners fetch pages; they do not press buttons.
+
+```ts
+// sendMagicLink: email the confirm page instead of Better Auth's URL
+import { magicLinkConfirmHref } from "@connextar/house/auth";
+sendMagicLink: async ({ email, url }) => send(email, magicLinkConfirmHref(url, "/auth/confirm-link")),
+
+// app/auth/confirm-link/page.tsx: a "Continue signing in" button
+import { magicLinkVerifyHref } from "@connextar/house/auth";
+const href = magicLinkVerifyHref(searchParams, "/api/auth/magic-link/verify"); // null → "link incomplete"
+<a href={href}>Continue signing in</a>
+```
+
+`magicLinkVerifyHref` rebuilds the verify URL from the app's own fixed path,
+never from the query. It keeps only the token and same-site redirect targets.
+Better Auth still origin-checks those targets itself.
+
+#### Adopting it in an app
+
+This applies to AltEd, Quickie, PM Tool, senco, KRP, FB Web (1.7.2) and
+PharmaLine (1.6.33). All of them already use `/auth/two-factor` and `?next=`.
+
+1. Bump `@connextar/house`.
+2. In `auth.ts`, add `secondFactorEverywhere()` after `twoFactor()` and before
+   `nextCookies()`, if the app has it.
+3. In the `hooks.before` refusal, pass `ctx.context` to `shouldBlockForTwoFactor`,
+   or delete the refusal and the app's `lib/auth/two-factor.ts` binding. Do not
+   change the deleted-account or suspended-account checks.
+4. On the code screen, send the person to `secondFactorNext(searchParams)` after
+   a successful code, or keep the app's own safe-next helper if it already
+   validates `next`.
+5. Update the copy. Remove the settings dialog line "email sign-in links stop
+   working on this account… Passkeys and Google sign-in keep working" and replace
+   it with something like "you'll be asked for your code after an email link or
+   Google sign-in too; passkeys stay one step".
+6. Update comments that say social or magic-link sessions skip the second factor
+   (`second-factor-session.ts`, AltEd `admin-second-factor.ts`). The admin proof
+   rule itself does not change.
+7. Add an app test: a magic link for a two-factor account redirects to
+   `/auth/two-factor?next=…` with no session, and the code then signs in with
+   proof.
+8. Optional: the confirm page for link scanners.
+
 ### `@connextar/house/account`
 
 The contract for "your data" and "delete my account" — types, the export notice,
@@ -445,6 +628,245 @@ independent sections are a form with three headings. A flow whose steps are
 separate saves, each landing before the next opens, is not one form and must not
 pretend to be: this wizard keeps one register and submits once.
 
+### `@connextar/house/password`, `/password/estimate`
+
+The password field every form uses, and the strength meter for the ones where a
+password is being chosen. Ten apps have password fields, in 38 files, and not
+one of them can show what has been typed. One shows a strength meter
+(Canisters, with an unused copy in FB): a checklist of length, digit, capital and
+symbol that "Password1!" passes on every line.
+
+| Export                                                          | What it is                                                                         |
+| --------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `PasswordInput`                                                 | `<input>` with a show/hide toggle inside it. Drop-in for `<Input type="password">` |
+| `PasswordStrength`                                              | Four bars and one plain sentence, under a field that sets a new password           |
+| `estimatePasswordStrength(password, { userInputs, minLength })` | The judgement itself — score 0–4, label, sentence, reason. Pure; server-safe       |
+| `usePasswordReveal(options)`                                    | The toggle's behaviour without its markup, for fields that are not a plain input   |
+| `@connextar/house/password/estimate`                            | The estimator alone: imports no package at all, not even React                     |
+
+```tsx
+import { PasswordInput, PasswordStrength } from "@connextar/house/password";
+
+// Signing in, or confirming it's you: the toggle, no meter.
+<PasswordInput id="password" purpose="current" {...register("password")} />;
+
+// Choosing one: the toggle and the meter.
+const newPassword = watch("newPassword") ?? "";
+<PasswordInput id="new-password" purpose="new" aria-describedby="new-password-strength" {...register("newPassword")} />;
+<PasswordStrength
+  id="new-password-strength"
+  password={newPassword}
+  userInputs={[session.user.email, session.user.name, "Quickie"]}
+  minLength={8}
+/>;
+```
+
+Inside a shadcn `FormField`, `<FormControl><PasswordInput purpose="new" {...field} /></FormControl>`
+— `FormControl`'s `id`, `aria-invalid` and `aria-describedby` land on the input.
+With plain state, `value` and `onChange` as with any input.
+
+**`PasswordInput`.** Every input prop and the ref pass straight through, so
+`register`, a `Controller`'s `field` and plain state all work unchanged (all
+three are tested). `purpose` sets `autoComplete` — `"current"` (the default)
+gives `current-password`, `"new"` gives `new-password` — and an explicit
+`autoComplete` wins. What the toggle takes care of:
+
+- **It is a `<button type="button">`**, inside the field and in the tab order,
+  so it never submits the form. Its accessible name stays **"Show password"** and
+  `aria-pressed` carries the state. A toggle that also changed its name to "Hide
+  password" would be read as "Hide password, pressed" — the opposite of what is
+  on screen — which is why WAI-ARIA's button pattern says the name of a toggle
+  must not change. Sighted people see the eye become a struck-through eye.
+- **The field keeps focus and the caret stays where it was.** A pointer press on
+  the toggle never takes focus; the selection is put back after the type
+  switches, since some browsers reset it. A keyboard user who tabbed to the
+  toggle stays on the toggle.
+- **It is hidden again as its form submits** — synchronously, before any submit
+  handler or the browser reads the form. A password submitted from a text field
+  is a value the browser may keep in its ordinary autofill history and offer in
+  other text boxes. It is hidden on reset too.
+- **Spellcheck, autocorrect and autocapitalise are always off.** A revealed field
+  is a text field, and enhanced spellcheck sends the contents of text fields to
+  a server.
+- `revealed`/`onRevealedChange` make it controlled — one toggle state for a new
+  and a confirm field. Edge's own reveal button is hidden, so there is one eye.
+
+**`PasswordStrength`** — only where a password is being chosen:
+
+| Field                                                                    | Toggle | Meter                         |
+| ------------------------------------------------------------------------ | ------ | ----------------------------- |
+| Sign-in                                                                  | yes    | **never**                     |
+| Two-factor enable/disable "confirm your password", any re-authentication | yes    | never                         |
+| Change password — current                                                | yes    | never                         |
+| Sign-up, reset, set a first password, change password — new              | yes    | **yes**                       |
+| Confirm new password                                                     | yes    | no — it must match, not score |
+| Someone setting a password for someone else (a guardian for a child)     | yes    | yes                           |
+
+Rating a password someone already has tells them nothing they can act on, and
+tells anyone watching the screen something about it. A form that is sign-in and
+sign-up in one (AltEd, Quickie, PharmaLine, FB) shows the meter only in sign-up
+mode.
+
+- **It refuses nothing.** There is no `valid` to wire a button to. Whether a
+  password is allowed is the app's rule — its minimum length, its schema — and
+  `minLength` exists only so the sentence can say "Use at least 8 characters."
+  while the password is shorter, in agreement with the form rather than
+  contradicting it.
+- **Nothing shows for an empty field.** The label and sentence are ordinary text
+  (put `id` on it and point the field's `aria-describedby` at it); the bars are
+  `aria-hidden`. A visually hidden `role="status"` `aria-live="polite"` region
+  says the new strength once typing has paused (`announceDelay`, 1 s) and only
+  when it changed — never a word per keystroke.
+- `userInputs` takes what the person's password should not be built from: email,
+  name, username, organisation, **and the app's own name**. They are matched in
+  pieces and through l33t, so `amir@connextar.com` also catches `Amir2026!` and
+  `C0nn3xtar`.
+- `messages` replaces the labels and sentences (Canisters is `next-intl`);
+  `classNames` replaces the look part by part; the root carries `data-score` for
+  an app styling it from its own stylesheet.
+
+**The estimator — zxcvbn's method, written small.** A password is read as the
+cheapest sequence of patterns a cracker would try: a common password or word
+(including reversed and l33t), the person's own details, a keyboard walk
+(QWERTY and keypad), a sequence (`abc`, `9753`), a repeat (`aaaa`, `abcabc`), a
+date or year, and plain characters for whatever is left. The score is the
+number of guesses that costs, on zxcvbn's scale: under 10³ is 0, 10⁶ is 1, 10⁸
+is 2, 10¹⁰ is 3, and above is 4. Two departures from zxcvbn, both making it
+stricter: the person's own words, dates, and up to four digits or symbols on
+either end are free pieces rather than earning zxcvbn's allowance for an
+unpredictable structure — so "Summer2024!" and "amir-connextar-2026" are weak
+rather than fair — and a separator after a word belongs to the word.
+
+| Password                                        | Score | Why                                           |
+| ----------------------------------------------- | ----- | --------------------------------------------- |
+| `password`, `qwerty`, `trustno1`                | 0     | among the most common passwords               |
+| `Password1!`, `P@ssw0rd123!`, `Summer2024!`     | 0–1   | a common word dressed up                      |
+| `xcvbnm,.`, `78963214`                          | 0–1   | keyboard walks                                |
+| `aaaaaaaa`, `abcabcabc`, `abcdefgh`, `98765432` | 0     | repeats and sequences                         |
+| `01/02/1987`, `19870201`                        | 1     | dates                                         |
+| `amir-connextar-2026` for amir@connextar.com    | 1     | the person's own details (3+ for anyone else) |
+| `kX9#vQ2$mL`                                    | 3     | ten random characters                         |
+| `correct horse battery staple`                  | 4     | a long passphrase                             |
+
+**Why not zxcvbn itself.** It is the honest measure, and this is its method.
+What it adds is frequency lists — tens of thousands of leaked passwords, English
+words, names and surnames — and they are most of its weight: zxcvbn's README
+puts the original at about 400 kB gzipped (820 kB minified), and
+`@zxcvbn-ts/core` with its common and English packs is published as 0.8 MB,
+1.9 MB and 5.4 MB unpacked. Taking it as an optional peer would mean ten apps
+each deciding whether to install it and each lazy-loading a chunk on their
+sign-up page, and an app that did not would quietly score differently — the
+divergence this package exists to prevent. The estimator here is **12.6 kB
+minified, 5.9 kB gzipped**, dictionary included; the whole module with both
+components is 17.0 kB / 7.7 kB, before React and two lucide icons. The cost of
+the smaller dictionary is known and one-sided: a rare word nobody has leaked
+("Tr0ub4dor") scores as random characters, so the estimate is a little generous
+on unusual vocabulary and never on the patterns people actually lean on. The
+first 100 characters are analysed; the search takes a fraction of a
+millisecond for anything typed.
+
+**On the server**, from `@connextar/house/password/estimate`, which imports no
+package at all:
+
+```ts
+import { estimatePasswordStrength } from "@connextar/house/password/estimate";
+
+const strength = estimatePasswordStrength(body.newPassword, { userInputs: [user.email, user.name] });
+if (strength.score < 2) return problem(400, strength.sentence);
+```
+
+Whether to refuse the weakest is each app's decision, and it is the same
+judgement the meter showed. Nothing in this module refuses anything.
+
+**Fields that are not a plain input.** `usePasswordReveal({ inputId })` returns
+`inputProps` and `toggleProps` (and `inputRef`) to spread on markup of the app's
+own: Tracker C's floating label sits _after_ its input and is styled with a
+sibling selector that a wrapper would break; an MUI `TextField` puts the toggle
+in an `InputAdornment`. Same behaviour, the app's markup. The toggle still needs
+its `aria-label`.
+
+**Look.** The input is the shadcn input on the theme tokens, with room on the
+right for the eye; an app whose `Input` differs passes its classes as
+`classNames.input`, and `className` is appended as with its own `Input`. KRP,
+MAS and Tracker C have no shadcn tokens and pass their own classes. The meter's
+amber and green are Tailwind palette classes — no theme token names them — and
+all of it rides the `@source` line in [Tailwind setup](#tailwind-setup-required-for-every-component).
+
+#### Adoption, per app
+
+Every file with a password field on 2026-09-30. **New** marks a field that sets a
+new password — toggle and meter; every other field gets the toggle only. No app
+has a reveal toggle today.
+
+| App        | File                                                  | Fields                                                                                                 |
+| ---------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| AltEd      | `components/auth/sign-in-form.tsx`                    | sign-in; sign-up (**new**, same field in sign-up mode)                                                 |
+|            | `components/auth/reset-password-form.tsx`             | reset **new**; confirm                                                                                 |
+|            | `components/settings/account/password-section.tsx`    | set **new** + confirm; change: current, **new** + confirm (all through the file-local `PasswordField`) |
+|            | `components/settings/account/two-factor-section.tsx`  | enable and disable: confirm password                                                                   |
+|            | `components/learners/learner-sign-in.tsx`             | guardian sets a learner's password (**new**)                                                           |
+| Quickie    | `components/auth/sign-in-form.tsx`                    | sign-in; sign-up (**new**)                                                                             |
+|            | `components/auth/reset-password-form.tsx`             | reset **new**; confirm                                                                                 |
+|            | `components/settings/account/password-section.tsx`    | set **new** + confirm; change: current, **new** + confirm                                              |
+|            | `components/settings/account/two-factor-section.tsx`  | enable and disable: confirm password                                                                   |
+| PM Tool    | `components/auth/sign-in-form.tsx`                    | sign-in (no sign-up); no `autoComplete` today                                                          |
+|            | `app/auth/reset-password/page.tsx`                    | reset **new** (no confirm); no `autoComplete` today                                                    |
+|            | `components/settings/account/password-section.tsx`    | set **new** + confirm; change: current, **new** + confirm                                              |
+|            | `components/settings/account/two-factor-section.tsx`  | enable and disable: confirm password                                                                   |
+| senco      | `components/auth/sign-in-form.tsx`                    | sign-in; sign-up (**new**, a separate form)                                                            |
+|            | `components/auth/reset-password-form.tsx`             | reset **new**; confirm                                                                                 |
+|            | `components/settings/account/password-section.tsx`    | set **new** + confirm; change: current, **new** + confirm                                              |
+|            | `components/settings/account/two-factor-section.tsx`  | enable and disable: confirm password                                                                   |
+| PharmaLine | `components/auth/sign-in-form.tsx`                    | sign-in; sign-up (**new**)                                                                             |
+|            | `components/auth/reset-password-form.tsx`             | reset **new**; confirm                                                                                 |
+|            | `components/settings/account/password-section.tsx`    | set **new** + confirm; change: current, **new** + confirm                                              |
+|            | `components/settings/account/two-factor-section.tsx`  | enable and disable: confirm password                                                                   |
+| KRP        | `src/components/Auth/SignInForm.tsx`                  | child sign-in; guardian sign-in                                                                        |
+|            | `src/components/Auth/SignUpForm.tsx`                  | sign-up **new**; confirm                                                                               |
+|            | `src/app/auth/reset-password/page.tsx`                | reset **new**; confirm                                                                                 |
+|            | `src/page-components/guardian/ProfileSettings.tsx`    | current (may be empty to set a first one); **new**; confirm                                            |
+|            | `src/page-components/guardian/ChildrenManagement.tsx` | guardian sets a child's password: **new**; confirm                                                     |
+| FB Web     | `components/auth/sign-in-form.tsx`                    | sign-in; sign-up (**new**)                                                                             |
+|            | `components/auth/reset-password-form.tsx`             | reset **new**; confirm                                                                                 |
+|            | `components/settings/account/password-section.tsx`    | set **new** + confirm; change: current, **new** + confirm                                              |
+|            | `components/settings/account/two-factor-section.tsx`  | enable and disable: confirm password                                                                   |
+|            | `components/profile/password-strength.tsx`            | an unused checklist meter — delete it                                                                  |
+| MAS        | `src/app/(site)/signin/SigninForm.tsx`                | sign-in                                                                                                |
+|            | `src/app/(site)/signup/SignupForm.tsx`                | sign-up **new** (no confirm)                                                                           |
+| Tracker C  | `src/app/(routes)/auth/login/page.tsx`                | sign-in (password mode) — Formik, floating label: use `usePasswordReveal`                              |
+|            | `src/app/(routes)/auth/signup/page.tsx`               | sign-up **new** (no confirm)                                                                           |
+|            | `src/app/(routes)/auth/forgot-password/page.tsx`      | reset **new**; confirm                                                                                 |
+| Canisters  | `components/auth/login-form.tsx`                      | sign-in                                                                                                |
+|            | `components/auth/register-form.tsx`                   | sign-up **new** — replaces its inline requirements checklist                                           |
+|            | `components/profile/settings-form.tsx`                | change: current; **new** — replaces `components/profile/password-strength.tsx`                         |
+
+Every app is shadcn/Radix on Tailwind v4 with a `components/ui/input.tsx`, except
+KRP (Tailwind v4, its own `src/components/Input.tsx`), MAS (raw inputs with
+literal classes in these two forms; MUI elsewhere), Tracker C (Formik and global
+`form-textbox` classes; MUI elsewhere, not in these forms) and Canisters
+(shadcn on Tailwind 3.3). Forms are react-hook-form + zod, except the two-factor
+dialogs everywhere and PM Tool's sign-in and reset (plain state), KRP and MAS
+(plain state), and Tracker C (Formik + Yup, plain state on reset).
+
+Found while surveying, and each app's to fix while it is there:
+
+- **Minimums agree at 8 everywhere, maximums do not.** Better Auth is 8–128 in
+  all nine apps that use it (Canisters has its own auth). **Tracker C's sign-up
+  Yup caps at 20** (and its message says "at least"), so a passphrase the server
+  accepts is refused.
+  **Canisters has no maximum**, and bcrypt ignores everything past 72 bytes.
+- **Rules disagree within an app.** AltEd, Quickie, PharmaLine and FB require a
+  letter and a digit on set/reset/change but not on sign-up, where only Better
+  Auth's 8–128 applies — and in all five apps with that schema (PM Tool and
+  senco without the letter-and-digit rule) the server applies it only on
+  `/api/auth/set-password`, never on sign-up, reset or change. Canisters' sign-up needs 8
+  characters, its checklist shows digit and symbol, and change-password needs
+  digit, capital and symbol. Composition rules are what "Password1!" is built
+  to pass; the meter is the better guide, and length the better rule.
+- **Missing `autoComplete`**: PM Tool's sign-in and reset, and every password
+  field in KRP, MAS, Tracker C and Canisters. `purpose` fixes it on adoption.
+- **Tracker C's reset** posts to the legacy API rather than Better Auth.
+
 ### `@connextar/house/setup-guide`
 
 The checklist a new account works through, and what finishing a step earns.
@@ -763,7 +1185,7 @@ got wrong:
 | A run in progress       | Shown as **Errored** (`ok` is false until it finishes); one cut off stays so, with no reason | The same                                                                                            | Running inside its timeout; past it, Failed — "never finished, probably cut off"                        |
 | Staleness               | Last OK older than `maxAgeMs` (strictly)                                                     | The same — and a tenant's Run now reset it for everyone                                             | Last successful _whole_ run older than the threshold; healthy exactly at it                             |
 | Pause / resume          | Per job, who and when, audited; harvest's switch shared with its own screen                  | None                                                                                                | Per job, who and when; platform authority; audit in the adapter's transaction; tick says it skipped     |
-| Run now                 | `runJobNow` exists but has no caller, and every job is `global`, so it would refuse them all | Owner-only, scoped to the caller's organisation; no cool-down, and `force` skips reminder throttles | `tenant` or `platform` scope, refused outside it, while paused, while running, and within a cool-down   |
+| Run now                 | `runJobNow` exists but has no caller, and every job is `global`, so it would refuse them all | Owner-only, scoped to the caller's organisation; no cool-down, and `force` skips reminder throttles | `tenant`, `platform` or both; refused outside it, while paused, while running, in its cool-down         |
 | Jobs on their own clock | Harvest (10 min) and imports (1 min): switchable, but record no runs, so no health           | —                                                                                                   | `schedule: "own"` + `runOwn`: the switch and the ledger, with or without a window                       |
 | Errors                  | Message stored; shown to administrators                                                      | Message stored; shown to **every** organisation's owner, whoever's data it came from                | Message stored; a tenant viewer sees whether a sweep failed, not its words or its numbers               |
 | `CRON_SECRET`           | Bearer or `?secret=`; `timingSafeEqual` after a length check                                 | Bearer (prefix optional) or `?secret=`; SHA-256 digests; dev secret refused in production           | Bearer required; digests; dev secret refused; `?secret=` only when a route asks                         |
@@ -805,9 +1227,11 @@ export const jobs = defineJobs([
     cadence: "Daily, from 09:00",
     window: daily({ from: 9 }),
     staleAfterMs: 26 * HOUR,
-    runNow: { scope: "tenant" }, // an owner sweeps their own organisation, and nobody else's
+    // An owner sweeps their own organisation, and nobody else's; an operator re-runs the sweep over all of them.
+    // One scope — `{ scope: "tenant" }` — is declared as before.
+    runNow: { scope: ["tenant", "platform"] },
     counts: { remindersSent: { label: { one: "reminder sent", other: "reminders sent" } } },
-    // `tenantId` is null for the schedule's sweep and always set for an owner's Run now.
+    // `tenantId` is null for the schedule's sweep and a platform Run now, and always set for an owner's.
     run: async ({ now, tenantId }) => {
       const { remindersSent } = await sendPaymentReminders(now, { organizationId: tenantId ?? undefined });
       return { remindersSent };
@@ -854,6 +1278,7 @@ const outcome = await scheduler.runNow(body.job, {
   actor: { id: user.id, name: user.name },
   platform: user.platformAdmin,
   tenantId: user.organizationId,
+  scope: body.scope, // the button pressed, on a job that offers both; optional
 });
 if (outcome.status === "refused") return apiError(outcome.message, refusalStatus(outcome.reason));
 if (outcome.status === "failed") return apiError(outcome.message, 500);
@@ -884,7 +1309,8 @@ import { JobHealthList } from "@connextar/house/jobs/react";
   onSwitch={async (job, on) => {
     await commitApi("/api/admin/cron", { job, action: on ? "resume" : "pause" });
   }}
-  onRunNow={(job) => commitApi("/api/cron/run", { job })}
+  onRunNow={(job, scope) => commitApi("/api/cron/run", { job, scope })}
+  runNowWords={{ tenant: "your organisation", platform: "every organisation" }}
   onSettled={router.refresh}
   extra={(job) => (job.id === "harvest" ? <Link href={routes.harvest}>What it searches next</Link> : null)}
 />;
@@ -897,10 +1323,14 @@ refusal puts both back and reports the reason through the
 `ActionFeedbackProvider`. No other row is disabled while one saves. Run now is
 `useKeyedAction`: that row's button is busy (`data-busy`), the route's message is
 said, and the screen refreshes whether the run worked or not, since a failure is
-on the ledger too. Dates are drawn in `timeZone` (default `Europe/London`),
-never the runtime's own — the server draws the list in UTC and the browser
-again in BST, and two times in one element is a hydration error. `classNames`
-replaces any part's look.
+on the ledger too. A row draws one button per scope the view offers
+(`runNowScopes`) and hands `onRunNow` the one pressed; nearly every viewer holds
+one — an operator the platform run, an owner their own — and sees "Run now". A
+viewer who holds both sees two, "Run for every account" and "Run for your
+account", in the app's words through `runNowWords`. Dates are drawn in
+`timeZone` (default `Europe/London`), never the runtime's own — the server
+draws the list in UTC and the browser again in BST, and two times in one
+element is a hydration error. `classNames` replaces any part's look.
 
 The rules it keeps:
 
@@ -933,9 +1363,21 @@ The rules it keeps:
   needs one; `platform` sweeps everything and needs platform authority. It is
   refused while the job is off, while a run it would overlap is in flight (the
   schedule's sweep covers the caller's tenant too), and within its cool-down
-  (default ten minutes, per job and scope) — a manual run sets `force`, so a
-  second press would otherwise send the whole batch again. `force` is for a
-  job's hour gates; a per-recipient throttle should stay on.
+  (default ten minutes, per job and scope, and per tenant for tenant runs) — a
+  manual run sets `force`, so a second press would otherwise send the whole
+  batch again. `force` is for a job's hour gates; a per-recipient throttle
+  should stay on.
+- **A job may offer both** — `runNow: { scope: ["tenant", "platform"] }` —
+  and a single scope is declared as it always was. The caller's `scope` says
+  which was pressed; left out, it is the caller's tenant when they have one and
+  every tenant when they do not, and it never grants anything `platform` and
+  `tenantId` do not. The scopes are fenced from each other: separate
+  cool-downs, and neither starts while the other is in flight — a tenant run
+  waits for a platform run, and a platform run waits for any tenant's
+  (`JobStore.latestUnfinishedRun`, which `createScheduler` requires the moment
+  one job offers both). A platform Run now is a run over every tenant, so it
+  resets the job's health for everyone, as the schedule's does; a tenant's never
+  does. `outcome.scope` says which ran, for the app's audit entry.
 - **A tenant sees their own.** To a tenant viewer, a sweep over every tenant
   shows whether it ran and when, but not its numbers (which are everyone's) or
   its error (which may name another organisation's data). Their own Run now
@@ -953,7 +1395,11 @@ The rules it keeps:
   `allowQuery: true`, because an address lands in request logs.
 
 **Storage.** The package owns no schema. The app implements `JobStore` — claim,
-finish, latest run, read switches, write a switch — over its own tables. This is
+finish, latest run, read switches, write a switch, and, since 0.12.0, the latest
+unfinished run over any tenant (for a job with both Run now scopes) and pruning
+— over its own tables. The two new methods are optional in the type, so an
+0.11.0 adapter still compiles; `createScheduler` and `pruneJobRuns` say by name
+what is missing when a feature needs one. This is
 the reference model; both apps' existing `cron_run` tables are it minus two
 nullable columns, so every row they hold maps across as it is:
 
@@ -1030,10 +1476,38 @@ export const jobStore: JobStore = {
         ...(ok ? { ok: true } : {}),
         ...(manualOnly ? { windowKey: { startsWith: "manual:" } } : {}),
       },
-      orderBy: { startedAt: "desc" },
+      // `id` breaks a tie the way `pruneRuns` does, so the row read as latest is the row kept as latest.
+      orderBy: [{ startedAt: "desc" }, { id: "desc" }],
     });
     return row && { ...row, by: row.triggeredBy };
   },
+  // Since 0.12.0 — needed once a job's Run now offers both scopes.
+  async latestUnfinishedRun(job) {
+    const row = await prisma.cronRun.findFirst({
+      where: { job, finishedAt: null }, // any tenant: a platform run must wait for every tenant's
+      orderBy: [{ startedAt: "desc" }, { id: "desc" }],
+    });
+    return row && { ...row, by: row.triggeredBy };
+  },
+  // Since 0.12.0 — `pruneJobRuns` calls it from the housekeeping job. One statement, at most `limit` rows, oldest
+  // first. `PARTITION BY` groups every NULL tenant together, which is exactly "the runs over every tenant".
+  async pruneRuns({ startedBefore, limit }) {
+    return prisma.$executeRaw`
+      DELETE FROM "cron_run" WHERE "id" IN (
+        SELECT "id" FROM (
+          SELECT "id", "ok", "started_at", "finished_at",
+            ROW_NUMBER() OVER (PARTITION BY "job", "tenant_id" ORDER BY "started_at" DESC, "id" DESC) AS "nth",
+            ROW_NUMBER() OVER (PARTITION BY "job", "tenant_id", "ok" ORDER BY "started_at" DESC, "id" DESC) AS "nth_of_kind"
+          FROM "cron_run"
+        ) AS "ranked"
+        WHERE "started_at" < ${startedBefore}
+          AND "finished_at" IS NOT NULL -- never a run still under way
+          AND "nth" > 1 -- never the latest run of a job for its tenant
+          AND NOT ("ok" AND "nth_of_kind" = 1) -- nor its latest success
+        ORDER BY "started_at", "id"
+        LIMIT ${limit}
+      )`;
+  },
   async readSwitches() {
     const rows = await prisma.cronSwitch.findMany();
     return new Map(rows.map((r) => [r.job, { paused: r.paused, at: r.switchedAt, by: r.switchedByName }]));
@@ -1060,11 +1534,49 @@ export const jobStore: JobStore = {
 };
 ```
 
-`createMemoryJobStore()` is the same contract in memory, unique index included,
-for the app's own tests of its binding. Prune the ledger in the app's
-housekeeping job like any other growing table, keeping more than the longest
-threshold — health reads the latest run and the latest success per job, so an
-older row is history, not state.
+`createMemoryJobStore()` is the same contract in memory, unique index and
+pruning rules included, for the app's own tests of its binding.
+
+**Pruning the ledger.** Every tick and every own-clock call writes a row —
+AltEd about 150 a day — and a Run now row keeps the name of whoever pressed it.
+`pruneJobRuns(store, { now, retentionDays, batchLimit })` deletes the old ones
+through `JobStore.pruneRuns`, from the app's **own housekeeping job**, and
+reports what it removed as a declared count:
+
+```ts
+import { JOB_RUN_PRUNE_COUNTS, pruneJobRuns } from "@connextar/house/jobs";
+
+defineJob({
+  id: "rate-limit-prune",
+  label: "Housekeeping",
+  // …
+  counts: { windowsPruned: { label: "…" }, ...JOB_RUN_PRUNE_COUNTS }, // "12 old job runs removed"
+  run: async ({ now }) => ({ windowsPruned: await pruneRateLimits(), ...(await pruneJobRuns(jobStore, { now })) }),
+});
+```
+
+- **Retention** is 90 days by default, in days (at least 1), so a number cannot
+  be read as milliseconds and empty the ledger. A run exactly at the boundary is
+  kept.
+- **Always kept, however old:** per job, the latest run and the latest
+  successful run — once for the runs over every tenant (the schedule's and
+  platform Run nows), and once for each tenant's own. Health, the Last run and
+  Last success lines and an owner's own view are read from exactly these, so a
+  monthly job that last ran 120 days ago still says so rather than "Never run",
+  and a job whose last run failed still shows when it last worked.
+- **Never a run still under way** — an unfinished row is never deleted. (A run
+  cut off by the platform stays as the evidence; there are few.)
+- **Bounded:** at most `batchLimit` rows a call (default 1,000), oldest first, in
+  one statement, so a housekeeping run never holds the table. What is left goes
+  the next day; calling it again straight away deletes only that. A long
+  history is caught up a batch a day — or raise `batchLimit` for the first run.
+
+Choosing the retention: keep it longer than the longest window (a monthly job's
+33 days), so the ledger holds a whole period of every job to investigate; and
+where the privacy policy names a period for operator activity, use that — the
+`triggered_by` names are why it matters. The rows always kept outlive it, name
+included; a quiet job's single last run is the price of its health staying
+true.
 
 **What should not be a scheduled job.**
 
@@ -1177,6 +1689,56 @@ older row is history, not state.
 8. **The guide** (`docs/guides/automation.md`): Errored is now Failed, a run in
    progress says Running, and the counts read as words.
 
+**Upgrading to 0.12.0 — both Run now scopes, and pruning.** A job declared
+with one scope behaves exactly as in 0.11.0, and an 0.11.0 adapter compiles
+unchanged. Each app then adds pruning to its housekeeping, and Quickie makes
+its per-organisation jobs that are safe to re-sweep dual.
+
+- **AltEd** — no dual jobs: it is single-tenant, and every job that offers Run
+  now already sweeps everything (`platform`). In `lib/jobs/store.ts` add
+  `pruneRuns` from the adapter above (`latestUnfinishedRun` is not needed
+  until a job offers both), and add `{ id: "desc" }` to `latestRun`'s
+  `orderBy`. In `lib/jobs/index.ts`, Housekeeping (`rate-limit-prune`) takes
+  `...JOB_RUN_PRUNE_COUNTS` in its counts and
+  `...(await pruneJobRuns(jobStore, { now }))` in its result. The harvest's
+  144 rows a day are most of the ledger; whatever history has built up beyond
+  90 days is caught up at a thousand rows a day. Test the SQL in
+  `store.db.test.ts` with runs dated before 2000 under the test's own job ids
+  and `startedBefore` in 2000, so no real row is old enough to go.
+- **Quickie** — make these dual, `runNow: { scope: ["tenant", "platform"] }`,
+  because a second sweep sends nobody anything twice: **payment reminders**
+  (the per-invoice throttle, which Run now does not lift), **booking
+  reminders** (a booking's `REMINDER` message), **review requests** (`PENDING`
+  becomes `SENT`), **bank consent check** (`expiryNoticeAt`) and **budget
+  alerts** (`BudgetAlert`, one per budget, category and month). Keep these
+  tenant-only: the **follow-up** and **weekly finance digests** —
+  `ignoreHour: force` would email every opted-in organisation at once, and
+  nothing stops a second digest the same day; the **monthly report** — nothing
+  records that an organisation's report went, so re-running a sweep that failed
+  half-way emails the first half again (make it dual once it does); and the
+  **bank feed sync** — `force` lifts each connection's six-hour hold, so a
+  platform run would call every bank for every organisation, and the next
+  window recovers anyway (if it is ever made dual, pass
+  `force && tenantId !== null`). In `lib/repos/cron.repo.ts` add
+  `latestUnfinishedRun` — `createScheduler` refuses a dual job without it — and
+  `pruneRuns`. No route changes: `/api/admin/cron` already calls `runNow` with
+  `platform: true, tenantId: null`, which on a dual job is the platform run,
+  and `/api/cron/run` with `platform: false` and the organisation, which is the
+  tenant run; the admin panel now shows Run now on the dual jobs, and owners see
+  what they saw. Reword the admin route's and panel's "only for the jobs that
+  sweep shared tables", and the automation guide, to say an operator can re-run
+  a failed sweep. Housekeeping (`rate-limit-prune`, `lib/services/cron.service.ts`)
+  prunes through `cronJobStore`. The old `unrecorded` Run now rows age out like
+  any tenant's, the latest per job kept; no screen reads them.
+- **senco** — no dual jobs: retention and housekeeping are sweeps over every
+  school, and a school's Run now is refused on purpose (`lib/jobs/index.ts`).
+  In `lib/jobs/store.ts` add `pruneRuns` and `{ id: "desc" }` in `latestRun`'s
+  `orderBy`; Housekeeping (`rate-limit-prune`, `lib/jobs/index.ts`) takes the
+  counts and `pruneJobRuns(jobStore, { now })`. `CronSwitchChange` is the
+  switches' audit record, not ledger, and is not pruned. Retention enforcement
+  is a promise to schools about how long evidence is kept; say the ledger's 90
+  days in the same place.
+
 ### Styles — `@connextar/house/house.css`
 
 What the components need that utility classes cannot say: rich text, the editor's