@connextar/house 0.12.0 → 0.13.0

package/README.md

@@ -72,6 +72,14 @@ 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
 
 ### `@connextar/house/errors`
@@ -134,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,
@@ -448,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.

package/dist/auth/index.d.ts

@@ -1,2 +1,4 @@
-export { TWO_FACTOR_BLOCKED_MESSAGE, TWO_FACTOR_BLOCKED_PATHS, isTwoFactorBlockedPath, shouldBlockForTwoFactor, totpSecretFromUri, type TwoFactorBlockedPath, type TwoFactorLookup, } from "./two-factor-policy.js";
+export { TWO_FACTOR_BLOCKED_MESSAGE, TWO_FACTOR_BLOCKED_PATHS, isTwoFactorBlockedPath, magicLinkRefusalRetired, shouldBlockForTwoFactor, totpSecretFromUri, type AuthContextLike, type TwoFactorBlockedPath, type TwoFactorLookup, } from "./two-factor-policy.js";
+export { DEFAULT_CODE_SCREEN_PATH, DEFAULT_NEXT_PARAM, SECOND_FACTOR_CHALLENGE_ROUTES, SECOND_FACTOR_EVERYWHERE_ID, type SecondFactorChallengeRoute, } from "./second-factor-routes.js";
+export { magicLinkConfirmHref, magicLinkVerifyHref, safeNextPath, secondFactorNext } from "./second-factor-next.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/auth/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,0BAA0B,EAC1B,wBAAwB,EACxB,sBAAsB,EACtB,uBAAuB,EACvB,iBAAiB,EACjB,KAAK,oBAAoB,EACzB,KAAK,eAAe,GACrB,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,0BAA0B,EAC1B,wBAAwB,EACxB,sBAAsB,EACtB,uBAAuB,EACvB,uBAAuB,EACvB,iBAAiB,EACjB,KAAK,eAAe,EACpB,KAAK,oBAAoB,EACzB,KAAK,eAAe,GACrB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,wBAAwB,EACxB,kBAAkB,EAClB,8BAA8B,EAC9B,2BAA2B,EAC3B,KAAK,0BAA0B,GAChC,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/auth/index.js

@@ -1,2 +1,4 @@
-export { TWO_FACTOR_BLOCKED_MESSAGE, TWO_FACTOR_BLOCKED_PATHS, isTwoFactorBlockedPath, shouldBlockForTwoFactor, totpSecretFromUri, } from "./two-factor-policy.js";
+export { TWO_FACTOR_BLOCKED_MESSAGE, TWO_FACTOR_BLOCKED_PATHS, isTwoFactorBlockedPath, magicLinkRefusalRetired, shouldBlockForTwoFactor, totpSecretFromUri, } from "./two-factor-policy.js";
+export { DEFAULT_CODE_SCREEN_PATH, DEFAULT_NEXT_PARAM, SECOND_FACTOR_CHALLENGE_ROUTES, SECOND_FACTOR_EVERYWHERE_ID, } from "./second-factor-routes.js";
+export { magicLinkConfirmHref, magicLinkVerifyHref, safeNextPath, secondFactorNext } from "./second-factor-next.js";
 //# sourceMappingURL=index.js.map

package/dist/auth/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,0BAA0B,EAC1B,wBAAwB,EACxB,sBAAsB,EACtB,uBAAuB,EACvB,iBAAiB,GAGlB,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,0BAA0B,EAC1B,wBAAwB,EACxB,sBAAsB,EACtB,uBAAuB,EACvB,uBAAuB,EACvB,iBAAiB,GAIlB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,wBAAwB,EACxB,kBAAkB,EAClB,8BAA8B,EAC9B,2BAA2B,GAE5B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/auth/second-factor-index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `@connextar/house/auth/second-factor` — the server half: a Better Auth plugin. Kept off `@connextar/house/auth`
+ * so that entry point stays free of any Better Auth import and safe for client components.
+ */
+export { findTwoFactorSignInHook, secondFactorEverywhere, type SecondFactorEverywhereOptions, } from "./second-factor.js";
+export { DEFAULT_CODE_SCREEN_PATH, DEFAULT_NEXT_PARAM, SECOND_FACTOR_CHALLENGE_ROUTES, SECOND_FACTOR_EVERYWHERE_ID, type SecondFactorChallengeRoute, } from "./second-factor-routes.js";
+//# sourceMappingURL=second-factor-index.d.ts.map

package/dist/auth/second-factor-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"second-factor-index.d.ts","sourceRoot":"","sources":["../../src/auth/second-factor-index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EACL,uBAAuB,EACvB,sBAAsB,EACtB,KAAK,6BAA6B,GACnC,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,wBAAwB,EACxB,kBAAkB,EAClB,8BAA8B,EAC9B,2BAA2B,EAC3B,KAAK,0BAA0B,GAChC,MAAM,2BAA2B,CAAC"}

package/dist/auth/second-factor-index.js

@@ -0,0 +1,7 @@
+/**
+ * `@connextar/house/auth/second-factor` — the server half: a Better Auth plugin. Kept off `@connextar/house/auth`
+ * so that entry point stays free of any Better Auth import and safe for client components.
+ */
+export { findTwoFactorSignInHook, secondFactorEverywhere, } from "./second-factor.js";
+export { DEFAULT_CODE_SCREEN_PATH, DEFAULT_NEXT_PARAM, SECOND_FACTOR_CHALLENGE_ROUTES, SECOND_FACTOR_EVERYWHERE_ID, } from "./second-factor-routes.js";
+//# sourceMappingURL=second-factor-index.js.map

package/dist/auth/second-factor-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"second-factor-index.js","sourceRoot":"","sources":["../../src/auth/second-factor-index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EACL,uBAAuB,EACvB,sBAAsB,GAEvB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,wBAAwB,EACxB,kBAAkB,EAClB,8BAA8B,EAC9B,2BAA2B,GAE5B,MAAM,2BAA2B,CAAC"}

package/dist/auth/second-factor-next.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `candidate` if it is a same-site path, otherwise `fallback`. The result always starts with a single `/`, so it is
+ * safe to hand straight to `router.replace()` or `redirect()`.
+ */
+export declare function safeNextPath(candidate: string | null | undefined, fallback?: string): string;
+/**
+ * The code screen's `next`, made safe. Pass the page's search params (a `URLSearchParams`, Next's
+ * `ReadonlyURLSearchParams`, or a raw `?a=b` string); read it once the code — or a backup code — has been accepted:
+ *
+ * ```ts
+ * const { error } = await authClient.twoFactor.verifyTotp({ code, trustDevice });
+ * if (!error) router.replace(secondFactorNext(useSearchParams()));
+ * ```
+ */
+export declare function secondFactorNext(search: string | {
+    get(name: string): string | null;
+} | null | undefined, options?: {
+    param?: string;
+    fallback?: string;
+}): string;
+/**
+ * The same-site path of `location` (absolute or relative) on `origin`, or null when it points anywhere else.
+ * Used by the server to turn a sign-in route's `callbackURL` into the code screen's `next`.
+ */
+export declare function sameSitePath(location: string | null | undefined, origin: string): string | null;
+/**
+ * The code screen's URL on `origin`, carrying `next` when it is worth carrying: a safe same-site path that is not
+ * the site root (the default anyway) and not the code screen itself (which would loop).
+ */
+export declare function codeScreenUrl(origin: string, codeScreenPath: string, next: string | null, param?: string): string;
+export declare function magicLinkConfirmHref(verifyUrl: string, confirmPath: string): string;
+/**
+ * The verify URL to send the "Continue" button to, or null when the page was opened without a token. `verifyPath`
+ * is the app's own route, e.g. `/api/auth/magic-link/verify`.
+ */
+export declare function magicLinkVerifyHref(search: string | {
+    get(name: string): string | null;
+}, verifyPath: string): string | null;
+//# sourceMappingURL=second-factor-next.d.ts.map

package/dist/auth/second-factor-next.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"second-factor-next.d.ts","sourceRoot":"","sources":["../../src/auth/second-factor-next.ts"],"names":[],"mappings":"AAcA;;;GAGG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,QAAQ,SAAM,GAAG,MAAM,CAezF;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,GAAG;IAAE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,EACxE,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClD,MAAM,CAMR;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAa/F;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,EACtB,IAAI,EAAE,MAAM,GAAG,IAAI,EACnB,KAAK,GAAE,MAA2B,GACjC,MAAM,CAIR;AAkBD,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAQnF;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,GAAG;IAAE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;CAAE,EACrD,UAAU,EAAE,MAAM,GACjB,MAAM,GAAG,IAAI,CAaf"}