knowless 0.1.7 → 0.1.9

package/CHANGELOG.md

@@ -7,7 +7,80 @@ Versioning is [SemVer](https://semver.org/).
 
 ## [Unreleased]
 
+- **Turnkey Docker image** (`knowless/knowless-server:0.2.x`)
+  bundling Postfix + null-route + the binary so a self-hoster
+  runs `docker compose up` and has a working auth gateway in
+  one step. Material UX win for the PRD §4.2 self-hoster
+  audience. Targeted for v0.2.0.
 - Caddy forward-auth Docker integration test (TASKS.md 6.8).
+- `knowless-server --check-null-route`: CLI probe that submits a
+  test message to `shamRecipient` and confirms the local MTA
+  discarded it. Targeted for v0.2.0.
+
+## [0.1.9] — 2026-04-28
+
+addypin manual smoke turned up one real bug, one defaults footgun,
+and one DX gap.
+
+### Fixed
+
+- **`auth.deriveHandle(email)` now normalizes the email before
+  HMAC (AF-13).** Prior versions skipped `normalize()` while
+  `auth.startLogin` and `POST /login` ran it — adopters using
+  `deriveHandle` to precompute owner-keyed lookups got silent
+  handle mismatches whenever email casing varied between
+  create-time and click-time. Symptom was "user's records
+  disappear after login," which is awful to debug. The bare
+  `deriveHandle(emailNormalized, secret)` re-export still
+  expects pre-normalized input — that contract is unchanged.
+
+### Documentation
+
+- **GUIDE flags the `failureRedirect` Mode-A footgun (AF-14).**
+  Adopters running programmatic-only (`startLogin` without
+  mounting `loginForm`) hit a default `failureRedirect = /login`
+  pointing at a route they don't serve — expired/replayed
+  magic-link clicks 302 to a 404. The GUIDE now leads with this
+  in the Mode-A walkthrough and adds a callout in the config
+  table. Default unchanged to avoid breaking Mode-B users with
+  custom paths.
+- **OPS.md §11b — MailHog dev workflow (AF-15).** `docker run
+  mailhog/mailhog`, point knowless at port 1025, inspect every
+  outgoing mail (including sham submissions) in a UI at port
+  8025. Verifies `bodyFooter`, `subjectOverride`, and the
+  URL-line-isn't-QP-soft-broken invariant without spinning up
+  real Postfix.
+
+## [0.1.8] — 2026-04-28
+
+addypin round 4 — one small API addition + documentation polish.
+
+### Added
+
+- **`bypassRateLimit: true` arg on `auth.startLogin` (AF-10).**
+  Trusted server-side callers (CLI workers, cron jobs, internal
+  services on the same host as the web process) opt out of IP-
+  based rate-limit accounting entirely — neither check nor
+  increment for the `login_ip` and `create_ip` buckets. The per-
+  handle token cap (`maxActiveTokensPerHandle`) is still enforced.
+  Solves the "web + CLI sharing 127.0.0.1" starvation problem
+  without requiring config divergence between processes. Throws
+  on non-boolean. Do NOT plumb this from unauthenticated user
+  input.
+
+### Documentation
+
+- **GUIDE Step 6 rewrite (AF-11).** `auth.handleFromRequest(req)`
+  is now front-and-centre as the load-bearing primitive for
+  adopter authorization. Worked Express-style examples for
+  `requireAuth` middleware and per-handle CRUD gating. Replaces
+  the previous "(coming in v0.2.0)" placeholder with the v0.1.1
+  reality.
+- **OPS.md §11a "Multi-process deployments" (AF-12).** Half-page
+  guide covering when sharing one DB across processes is safe
+  (WAL mode, default), sweeper redundancy semantics, rate-limit
+  enforcement-vs-accounting under sharing (and why AF-10
+  matters), `auth.close()` behavior, and the cross-machine no-go.
 
 ## [0.1.7] — 2026-04-28
 

package/GUIDE.md

@@ -62,8 +62,8 @@ built-in auth is either missing or weak. The existing alternatives
 (Authelia, Authentik, Keycloak, oauth2-proxy) are heavyweight for
 the job: "redirect to login if no cookie, otherwise let through."
 
-knowless's standalone server (v0.2.0, in development) sits behind
-Caddy / nginx / Traefik via forward-auth. One auth subdomain, one
+knowless's standalone server (`bin/knowless-server`, shipped in
+v0.1.3) sits behind Caddy / nginx / Traefik via forward-auth. One auth subdomain, one
 session cookie scoped to the parent eTLD+1, SSO across all your
 services for free.
 
@@ -106,7 +106,7 @@ nothing else*.
 - **Walks away at v1.0.0.** Maintenance mode (security patches +
   bug fixes) after that, by design.
 
-## Walkthrough: library mode (v0.1.0)
+## Walkthrough: library mode
 
 The shape: import `knowless`, configure it, mount the handlers on
 your HTTP framework.
@@ -175,7 +175,9 @@ sending domain):
 Without all three, Gmail / Outlook will silently drop your auth
 mail. This is the operator commitment knowless asks of you.
 
-> Full Postfix walkthrough lives in `OPS.md` (shipping with v0.2.0).
+> Full Postfix walkthrough lives in [`OPS.md`](OPS.md) — Postfix
+> install, null-route, SPF/DKIM/PTR, systemd, reverse-proxy
+> forward-auth examples, multi-process deployments.
 
 ### Step 4: Mount the handlers
 
@@ -295,7 +297,19 @@ callers. See SPEC §7.3a for the full contract.
 
 `auth.deriveHandle(email)` returns the same opaque HMAC handle
 that the form path uses, without you having to import the helper
-or pass the secret around.
+or pass the secret around. The instance method **normalizes the
+email** (lowercase, trim) before HMAC (AF-13), so `Alice@X.com`
+and `alice@x.com` produce the same handle — match what the form
+and `startLogin` would compute. The bare `deriveHandle` re-export
+takes pre-normalized input; use the instance method unless you
+have a specific reason to call the lower-level primitive.
+
+> **Mode-A heads-up: set `failureRedirect`.** If you only mount
+> `auth.callback` (not `auth.loginForm`), the default
+> `failureRedirect` cascade points at `/login` — a route you
+> don't serve. An expired or replayed magic-link click will 302
+> to a 404. Set `failureRedirect: '/'` (or any route you do
+> serve) when wiring Mode A.
 
 ### Step 5: Pre-seed users (closed-registration mode, default)
 
@@ -335,25 +349,54 @@ const auth = knowless({ ..., openRegistration: true });
 Note that open registration adds a per-IP cap on new handles
 (default 3/hour) to mitigate signup spam.
 
-### Step 6: Use sessions in your app
+### Step 6: Use sessions in your app — `auth.handleFromRequest`
 
-After `/auth/callback` succeeds, the user has a session cookie.
-Read it on every protected request:
+After `/auth/callback` succeeds, the user has a session cookie. To
+gate your own protected endpoints, call `auth.handleFromRequest(req)`:
+it returns the requesting session's opaque handle (64-char hex), or
+`null` when the cookie is missing, malformed, or expired. **This is
+the load-bearing primitive for adopter authorization.** The five
+mounted handlers (`login`, `callback`, `verify`, `logout`, `loginForm`)
+own the auth round-trip; everything *else* in your app uses
+`handleFromRequest`.
 
 ```js
+// Express-shaped middleware. Same pattern works in Hono / Fastify /
+// node:http — handleFromRequest takes a node-shaped req and returns
+// a string or null synchronously. No async, no DB hop beyond the
+// session lookup.
 function requireAuth(req, res, next) {
-  // Use auth.verify() in a sub-request shape, or read the cookie
-  // and call into the store. Simplest pattern:
-  // Mount a middleware that calls the verify handler against the
-  // request and checks the result.
-  // (Cleaner pattern coming in v0.2.0 with a middleware factory.)
+  const handle = auth.handleFromRequest(req);
+  if (!handle) {
+    res.statusCode = 401;
+    return res.end('unauthorized');
+  }
+  req.handle = handle;
   next();
 }
+
+// Then on every protected endpoint:
+app.get('/api/pins', requireAuth, (req, res) => {
+  const pins = db.findPinsByOwner(req.handle); // owner_handle = req.handle
+  res.json(pins);
+});
+
+app.delete('/api/pins/:id', requireAuth, (req, res) => {
+  const pin = db.getPin(req.params.id);
+  if (pin.owner_handle !== req.handle) {
+    res.statusCode = 403;
+    return res.end('forbidden');
+  }
+  db.deletePin(req.params.id);
+  res.end();
+});
 ```
 
-For now, the friendliest pattern: route a dedicated `/me` endpoint
-through `auth.verify` and have the rest of your app fetch it on
-mount.
+The `verify` handler is for **forward-auth deployments** (your
+reverse proxy gates upstreams via `/verify` returning 200/401 +
+`X-User-Handle`). For in-process middleware, prefer
+`handleFromRequest` — same answer, no sub-request round-trip, no
+header parsing.
 
 ### Step 7: GDPR right-to-erasure
 
@@ -373,11 +416,10 @@ Library doesn't ship a built-in HTTP endpoint for this — operator
 chooses the UX (admin CLI, in-app self-service, ticket-driven
 support).
 
-## Walkthrough: standalone server mode (v0.2.0, coming)
+## Walkthrough: standalone server mode
 
-The shape: run `npx knowless-server`, point Caddy / nginx /
-Traefik at it for forward-auth, protect any HTTP service behind
-magic-link login.
+Run `npx knowless-server`, point Caddy / nginx / Traefik at it for
+forward-auth, protect any HTTP service behind magic-link login.
 
 The deployment-shape pattern:
 ```
@@ -389,7 +431,9 @@ The deployment-shape pattern:
                 [Caddy redirects to auth.example.com/login?next=...]
 ```
 
-Sample Caddyfile (forthcoming OPS.md will have the full setup):
+Sample Caddyfile (full setup including TLS/ACME + multiple gated
+services lives in [`OPS.md`](OPS.md) §7):
+
 ```caddy
 auth.example.com {
     reverse_proxy localhost:8080
@@ -398,7 +442,7 @@ auth.example.com {
 kuma.example.com {
     forward_auth localhost:8080 {
         uri /verify
-        copy_headers X-User-Handle
+        copy_headers X-Knowless-Handle
     }
     reverse_proxy localhost:3001  # Uptime Kuma
 }
@@ -406,7 +450,7 @@ kuma.example.com {
 adguard.example.com {
     forward_auth localhost:8080 {
         uri /verify
-        copy_headers X-User-Handle
+        copy_headers X-Knowless-Handle
     }
     reverse_proxy localhost:3000  # AdGuard Home
 }
@@ -415,9 +459,11 @@ adguard.example.com {
 One auth subdomain, one cookie, SSO across all gated services
 because the cookie is scoped to the parent eTLD+1.
 
-Until v0.2.0, you can replicate this yourself with ~30 lines of
-`node:http` wrapping the library-mode handlers — see
-`knowless.context.md` for the pattern.
+Configuration is via `KNOWLESS_*` env vars — see
+[`config.example.env`](config.example.env) and run
+`knowless-server --help` for the full list. `knowless-server
+--config-check` validates your env, SMTP reachability, and DB
+write access; suitable for systemd `ExecStartPre`.
 
 ## Configuration reference
 
@@ -450,7 +496,7 @@ Full options table:
 | `trustedProxies` | no | `['127.0.0.1', '::1']` | IPs allowed to set `X-Forwarded-For`. |
 | `shamRecipient` | no | `null@knowless.invalid` | Where sham mail goes (your MTA must discard it). |
 | `sweepIntervalMs` | no | `300000` | Sweeper tick (5 min default). |
-| `failureRedirect` | no | (= `loginPath`) | Where /auth/callback failures redirect. |
+| `failureRedirect` | no | (= `loginPath`) | Where /auth/callback failures redirect. **Mode-A adopters:** if you don't mount `loginForm`, set this to a route you actually serve (e.g. `/`) — otherwise expired/replayed magic-link clicks 302 to a 404. |
 | `store` | no | (built-in better-sqlite3) | Inject your own store implementation. |
 | `mailer` | no | (built-in nodemailer) | Inject your own mailer. |
 

package/OPS.md

@@ -540,6 +540,103 @@ in that order — most spam-folder verdicts trace to one of those four.
 
 ---
 
+## 11a. Multi-process deployments (web + worker / CLI)
+
+Multiple processes can share one knowless SQLite file. This is a
+common adopter pattern: a long-running web server plus a per-message
+CLI invoked by Postfix's `pipe` transport, or a web server plus a
+cron worker handling 48h reminders. Each process instantiates
+`knowless({...})` against the same `dbPath`.
+
+**Why this works.** `better-sqlite3` opens the database in WAL mode
+by default (knowless explicitly sets `journal_mode=WAL` at startup).
+WAL allows multiple readers and one writer concurrently, with the
+OS-level locking semantics needed for cross-process safety. Every
+write goes through a prepared statement under a SQLite transaction,
+so two processes inserting tokens or sessions at the same time can't
+corrupt the table.
+
+**What to know about each subsystem under multi-process:**
+
+- **Sweeper redundancy is harmless.** Each process runs its own 5-
+  minute sweep tick. The DELETE statements are idempotent — once
+  one process has deleted a row, the others' DELETEs simply affect
+  zero rows. No coordination needed.
+- **Rate-limit rows are shared but enforcement is per-process.**
+  All processes read and write the same `rate_limits` table, so
+  counter values are consistent. But each process makes its own
+  *enforcement* decision against its own configured cap. This
+  matters: a CLI worker calling `auth.startLogin` from `127.0.0.1`
+  uses the same `login_ip` bucket as web traffic from `127.0.0.1`.
+  Trusted CLI callers should pass `bypassRateLimit: true` to
+  `startLogin` (AF-10) so they don't starve the shared bucket and
+  don't participate in accounting.
+- **`auth.close()` from one process doesn't affect the others.**
+  Each process holds its own connection. Closing one is the right
+  thing to do at that process's shutdown; the database remains
+  open for the others.
+- **Magic-link tokens and session IDs are globally unique.** The
+  random-byte primitives have enough entropy that two processes
+  minting tokens concurrently won't collide (43-char base64url =
+  256 bits).
+
+**Don't share the DB across machines.** SQLite WAL only protects
+processes on the same host (it relies on POSIX advisory locks).
+For a multi-host knowless deployment, run a single instance behind
+a load balancer or — better — run one knowless per host, each
+with its own DB. Sessions are per-host but that's usually what you
+want for forward-auth-style deployments anyway.
+
+---
+
+## 11b. Local development without a real Postfix
+
+Spinning up Postfix on a developer laptop just to inspect what
+knowless sends is heavy. Two leaner options:
+
+### Option A — `devLogMagicLinks: true` (no MTA needed)
+
+knowless already supports this for the URL. When SMTP submission
+fails AND `devLogMagicLinks: true` is set, the magic link is
+printed to stderr tagged `[knowless dev:<from>]`. Sufficient for
+smoke-testing the click flow, not the email content. AF-6.2.
+
+### Option B — MailHog (visual UI for the rendered mail)
+
+For verifying subject/body/footer rendering or the timing of
+sham-vs-real submissions, run [MailHog](https://github.com/mailhog/MailHog)
+or any compatible test SMTP catcher (e.g. mailpit, smtp4dev) on
+the dev machine and point knowless at it.
+
+```sh
+# Docker one-liner for MailHog
+docker run --rm -p 1025:1025 -p 8025:8025 mailhog/mailhog
+```
+
+Then in your dev knowless config:
+
+```js
+const auth = knowless({
+  secret: process.env.KNOWLESS_SECRET,
+  baseUrl: 'http://localhost:3000',
+  from: 'auth@dev.local',
+  smtpHost: 'localhost',
+  smtpPort: 1025,         // MailHog's SMTP port
+  cookieSecure: false,    // localhost-only dev
+});
+```
+
+Open `http://localhost:8025` in your browser; every magic-link mail
+(including sham submissions to `null@knowless.invalid`) shows up in
+the inbox UI with full subject/body/headers visible. Perfect for
+verifying `bodyFooter`, `subjectOverride`, the URL line is intact
+without QP soft-breaks, etc.
+
+> Don't ship MailHog into production. It accepts mail from anywhere
+> and stores it forever — defeats the entire knowless threat model.
+
+---
+
 ## 12. Backup and recovery
 
 The only stateful file is the SQLite database (`KNOWLESS_DB_PATH`,

package/README.md

@@ -7,7 +7,7 @@ that don't need to email their users for anything but the sign-in link.
 npm install knowless
 ```
 
-> v0.1.7 | Node.js >= 20 | 2 deps (nodemailer, better-sqlite3) | Apache-2.0
+> v0.1.9 | Node.js >= 20 | 2 deps (nodemailer, better-sqlite3) | Apache-2.0
 
 ## What this is
 

package/knowless.context.md

@@ -1,7 +1,7 @@
 # knowless -- Integration Guide
 
 > For AI assistants and developers wiring knowless into a project.
-> v0.1.0 | Node.js >= 20 | 2 deps (nodemailer, better-sqlite3) | Apache-2.0
+> v0.1.9 | Node.js >= 20 | 2 deps (nodemailer, better-sqlite3) | Apache-2.0
 
 ## What this is
 
@@ -18,11 +18,13 @@ npm install knowless
 
 Two integration paths:
 
-1. **Library mode (v0.1.0):** `import { knowless } from 'knowless'` --
-   mount five handlers on Express / Fastify / Hono / `node:http`
-2. **Standalone server (v0.2.0, in development):** `npx knowless-server` --
-   forward-auth gateway for Caddy / nginx / Traefik in front of
-   no-auth services like Uptime Kuma, AdGuard, Pi-hole
+1. **Library mode:** `import { knowless } from 'knowless'` --
+   mount five handlers on Express / Fastify / Hono / `node:http`,
+   gate your endpoints with `auth.handleFromRequest(req)`.
+2. **Standalone server:** `npx knowless-server` -- forward-auth
+   gateway for Caddy / nginx / Traefik in front of no-auth services
+   like Uptime Kuma, AdGuard, Pi-hole. Configured via `KNOWLESS_*`
+   env vars; see [`OPS.md`](OPS.md) for the full deployment guide.
 
 This document is the dense reference. For the why, see
 `docs/01-product/PRD.md`. For the wire formats, see
@@ -147,8 +149,8 @@ const auth = knowless({
 | `handleFromRequest` | (req) | string \| null | Programmatic session resolver for in-process middleware. Returns the handle if the cookie is valid, else null. SPEC §9.4. |
 | `deleteHandle` | (handle: string) | void | Atomic delete of handle + tokens + sessions (FR-37a, GDPR) |
 | `revokeSessions` | (handle: string) | number | Drops every session for `handle` without deleting the account ("log out everywhere"). Returns rows removed. AF-6.1. |
-| `startLogin` | ({email, nextUrl?, sourceIp?, subjectOverride?}) | Promise\<{handle, submitted: true}\> | Programmatic magic-link send for "use first, claim later" flows. Same 12-step sham-work as form. `subjectOverride` (AF-9) replaces `cfg.subject` for this call. SPEC §7.3a. AF-7.3. |
-| `deriveHandle` | (email: string) | string | HMAC-SHA256(secret, normalize(email)) using the configured secret. Use to compute owner-handles outside HTTP context. AF-7.4. |
+| `startLogin` | ({email, nextUrl?, sourceIp?, subjectOverride?, bypassRateLimit?}) | Promise\<{handle, submitted: true}\> | Programmatic magic-link send for "use first, claim later" flows. Same 12-step sham-work as form. `subjectOverride` (AF-9) replaces `cfg.subject` per call. `bypassRateLimit: true` (AF-10) opts trusted server-side callers (CLI, cron, worker) out of IP-rate-limit accounting. SPEC §7.3a. AF-7.3. |
+| `deriveHandle` | (email: string) | string | `HMAC-SHA256(secret, normalize(email))` using the configured secret. Normalizes input (lowercase + trim) so `Alice@X.com` and `alice@x.com` produce the same handle. Match what `startLogin` and `POST /login` compute. AF-7.4 / AF-13. |
 | `_sweep` | -- | void | Trigger one sweep tick on demand (tests, operator scripts). AF-5.3. |
 | `config` | -- | object | Merged effective config; safe to read (do not mutate) |
 | `close` | -- | void | Stops sweeper, closes mailer + store. Call on shutdown. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "knowless",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Small, opinionated, full-stack passwordless auth for Node.js services that don't need to email their users for anything but the sign-in link.",
   "type": "module",
   "main": "./src/index.js",

package/src/handlers.js

@@ -243,7 +243,7 @@ export function createHandlers({ store, mailer, config }) {
    *   handle is null only when the email failed to normalize (programmer
    *   bug for startLogin; same-shape silent for /login).
    */
-  async function runSendLink({ emailRaw, nextRaw, sourceIp, subject }) {
+  async function runSendLink({ emailRaw, nextRaw, sourceIp, subject, bypassRateLimit = false }) {
     // Step 1: parse + normalize
     let emailNorm;
     try {
@@ -252,8 +252,13 @@ export function createHandlers({ store, mailer, config }) {
       return { handle: null, isSham: false, emailNorm: emailRaw, nextValidated: null };
     }
 
-    // Step 3: per-IP rate limit on /login — exempt short-circuit
+    // Step 3: per-IP rate limit on /login — exempt short-circuit.
+    // AF-10: trusted server-side callers (CLI, cron, worker) opt out
+    // of IP-based rate-limit accounting entirely — neither check nor
+    // increment. Per-handle token cap (insertToken's maxActive) still
+    // applies; only the IP buckets are bypassed.
     if (
+      !bypassRateLimit &&
       rateLimitExceeded(
         store,
         'login_ip',
@@ -271,7 +276,7 @@ export function createHandlers({ store, mailer, config }) {
     const exists = store.handleExists(handle);
     let isCreating = !exists && cfg.openRegistration;
 
-    if (isCreating) {
+    if (isCreating && !bypassRateLimit) {
       if (
         rateLimitExceeded(
           store,
@@ -353,8 +358,10 @@ export function createHandlers({ store, mailer, config }) {
       }
     }
 
-    rateLimitIncrement(store, 'login_ip', sourceIp, HOUR_MS);
-    if (isCreating) rateLimitIncrement(store, 'create_ip', sourceIp, HOUR_MS);
+    if (!bypassRateLimit) {
+      rateLimitIncrement(store, 'login_ip', sourceIp, HOUR_MS);
+      if (isCreating) rateLimitIncrement(store, 'create_ip', sourceIp, HOUR_MS);
+    }
 
     return { handle, isSham, emailNorm, nextValidated };
   }
@@ -404,6 +411,7 @@ export function createHandlers({ store, mailer, config }) {
     nextUrl,
     sourceIp = '',
     subjectOverride,
+    bypassRateLimit = false,
   } = {}) {
     // Programmer-error guards (AF-7.3). These DO throw; they're not
     // silent-miss conditions, they're "you called the API wrong."
@@ -416,6 +424,9 @@ export function createHandlers({ store, mailer, config }) {
     if (typeof sourceIp !== 'string') {
       throw new Error('startLogin: sourceIp must be a string when provided');
     }
+    if (typeof bypassRateLimit !== 'boolean') {
+      throw new Error('startLogin: bypassRateLimit must be a boolean when provided');
+    }
     // AF-9: per-call subject override. Validated with the same rules as
     // the factory subject (ASCII, ≤60 chars, no CR/LF). Throws on
     // invalid — same "programmer-error" treatment as other startLogin
@@ -431,6 +442,7 @@ export function createHandlers({ store, mailer, config }) {
       nextRaw: nextUrl ?? null,
       sourceIp,
       subject,
+      bypassRateLimit,
     });
     // Same-shape return: rate-limit / sham / real all collapse here.
     // `handle` is the HMAC of the normalized email (or null if email

package/src/index.js

@@ -1,7 +1,7 @@
 import { createStore } from './store.js';
 import { createMailer, validateBodyFooter } from './mailer.js';
 import { createHandlers } from './handlers.js';
-import { deriveHandle as deriveHandleRaw } from './handle.js';
+import { deriveHandle as deriveHandleRaw, normalize } from './handle.js';
 
 /** Default sweeper tick: 5 minutes. Per FR-13. */
 const DEFAULT_SWEEP_INTERVAL_MS = 5 * 60 * 1000;
@@ -153,9 +153,12 @@ export function knowless(options = {}) {
      *  See SPEC §7.3a. AF-7.3. */
     startLogin: handlers.startLogin,
     /** Derive the opaque handle for an email using the configured
-     *  secret. Lets adopters compute owner-handles outside HTTP context
-     *  without spreading the secret across modules. AF-7.4. */
-    deriveHandle: (email) => deriveHandleRaw(email, options.secret),
+     *  secret. Normalizes the email first (AF-13) so handles match
+     *  what `auth.startLogin` and `POST /login` would compute for the
+     *  same address typed with different casing or surrounding
+     *  whitespace. Adopters should treat this as the canonical handle
+     *  derivation. AF-7.4 / AF-13. */
+    deriveHandle: (email) => deriveHandleRaw(normalize(email), options.secret),
     /** Effective config (with defaults applied), useful for routing. */
     config: handlers._config,
     /** Run a sweep tick on demand. Useful for tests and operator scripts. */