knowless 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -15,14 +15,75 @@ Versioning is [SemVer](https://semver.org/).
 
 ## [Unreleased]
 
-- **Turnkey Docker image** (`knowless/knowless-server:0.2.x`)
-  bundling Postfix + null-route + the binary. Now meaningfully
-  smaller and faster to build because v0.2.0 dropped the native
-  compile dep.
-- 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.
+**v0.2.2 is feature-complete.** v1.0.0 is the planned next release —
+walk-away promotion, no API changes.
+
+## [0.2.2] — 2026-04-29
+
+**One feature add at the end of v0.2.x: per-call body customization
+for `auth.startLogin` (AF-26).** Closes the last addypin gap before
+v1.0.0 promotion — adopters with multiple Mode-A flows (pin
+confirmation, login, expiry warning) can now phrase the email body
+to match per-call subjects without re-implementing token mint /
+sham-work / SMTP submit.
+
+### Added
+
+- **`bodyOverride: ({url}) => string` arg on `auth.startLogin`
+  (AF-26).** A template function called per-call after the magic-
+  link URL is composed. knowless still owns URL composition (so the
+  v0.11 POC 7bit URL-line invariant stays in knowless's control) and
+  validates the rendered output. `bodyFooter` continues to append
+  after the override; the `lastLogin` line does NOT auto-append on
+  overridden bodies — the template owns content end-to-end.
+
+  ```js
+  await auth.startLogin({
+    email,
+    subjectOverride: `Confirm your pin: ${shortcode}`,
+    bodyOverride: ({ url }) =>
+      `Confirm your pin "${shortcode}":\n\n${url}\n\n` +
+      `Link expires in 15 minutes.\n`,
+  });
+  ```
+
+- **`validateBodyOverride(body, url)` re-export.** Pure validator
+  exposed alongside the other `validate*` re-exports. Same validation
+  knowless runs internally on the override return value:
+  - Non-empty string, ≤ 2048 chars
+  - ASCII only
+  - No CR (header-injection defense)
+  - URL appears exactly once
+  - URL is on its own line (preserves the v0.11 POC 7bit URL-line
+    invariant — QP soft-breaks would break the link)
+
+  Throws on any violation. Adopters generally don't need to call this
+  directly — knowless validates the function's return value at
+  compose time — but it's exported for ahead-of-time tests.
+
+### Why this is in scope (and not a 'forum-style' rejected addition)
+
+The body has to be composed *after* the token is minted (the URL
+contains the token), so the caller can't just "send their own email"
+without re-implementing most of knowless. Bypassing knowless to send
+a custom body would mean rebuilding token mint + token-store insert
++ sham-work timing + SMTP submit — that's most of the library. The
+ASCII / URL-line / 7bit constraints are the right place to keep
+validating, and those live in knowless. Identity-layer concern,
+mechanism stays where the policy is.
+
+Contrast with the rejected items in the v0.2.1 backlog cull
+(disposable-domain, account-age, hashcash, Docker image): each of
+those passed the "could the adopter do this themselves?" test.
+Per-call body customization fails it.
+
+### Internal
+
+- 16 new tests in `test/integration/body-override.test.js` covering
+  happy path on real submissions, sham-branch parity (FR-6),
+  bodyFooter append behavior, lastLogin non-auto-append, every
+  validation error path, undefined/null pass-through, and the
+  re-exported `validateBodyOverride` helper. Test count: 207 → 223.
 
 ## [0.2.1] — 2026-04-29
 
@@ -110,6 +171,36 @@ accessor, hashcash, `lookupMessageId()`, `onShamHit`).
   containment, and `verifyTransport()` resolve/reject paths.
   Test count: 192 → 207.
 
+### Cut from v0.2.x backlog (kept here for the record)
+
+Three items previously listed under Unreleased were stress-tested
+against walk-away-at-v1.0.0 and cut. Rationale per item, so future
+contributors see why these aren't being re-proposed:
+
+- **`knowless-server --check-null-route` CLI probe — CUT.** Operator
+  setup-correctness check, not identity layer. The same probe is
+  three commands of `swaks` + `tail /var/log/maillog`; documented in
+  GUIDE.md Step 3. Adding a knowless CLI feature for it would carry
+  maintenance burden into walk-away for something an operator can
+  already do with a one-line shell command.
+- **Caddy forward-auth Docker integration test (TASKS 6.8) — CUT.**
+  The contract under test is two HTTP responses and one header
+  (`/verify` → 200+`X-User-Handle` or 401). Every hop is already
+  covered by `forward-auth-next.test.js` + `cli.test.js`. addypin
+  runs knowless behind Caddy in production — that is the integration
+  test, with adopter signal stronger than any docker-compose CI
+  could provide. Removed as a v1.0.0 graduation criterion;
+  PRD §6.1 updated.
+- **Turnkey Docker image (`knowless/knowless-server:0.2.x`) — CUT.**
+  Doesn't actually solve the operator problem: SPF / DKIM / PTR /
+  outbound-port-25 work is still the operator's, image only saves
+  ~5 minutes of `apt install postfix && postmap`. Cost-side is
+  permanent: Postfix is on a CVE drumbeat, and a walk-away library
+  shipping a Postfix image would commit to forever-rebuilds —
+  exactly the opposite of walk-away discipline. If a self-hoster
+  builds a community Dockerfile, OPS.md will link to it; knowless
+  itself doesn't ship one.
+
 ## [0.2.0] — 2026-04-28
 
 **No native compile. One production dep.** Drops `better-sqlite3`

package/GUIDE.md

@@ -162,6 +162,25 @@ sudo postmap /etc/postfix/transport
 sudo systemctl reload postfix
 ```
 
+**Verify the null-route is catching mail.** A misconfigured
+null-route doesn't surface until the first sham submission — by
+which point you're debugging a silent-202 from a real form post.
+One-line check, no knowless code needed:
+
+```
+sudo apt install swaks   # one-time, if not present
+swaks --to null@knowless.invalid --server localhost:25 --quit-after RCPT
+sudo journalctl -u postfix --since '1 minute ago' | grep -i 'discard'
+```
+
+A `discard:` line in the postfix log confirms `transport_maps` is
+applied. If you see `relay=` / `delivered` / a queue ID with no
+discard, re-run `postmap` + `systemctl reload postfix` and try
+again. (knowless deliberately does NOT ship a `--check-null-route`
+CLI for this — operator MTA validation is operator-side, and adding
+a wrapper for a one-line `swaks` invocation would carry maintenance
+burden into the v1.0.0 walk-away window for no real value.)
+
 Then the DNS records — set on your sending domain, **not** your
 app's primary domain (typical setup: `auth.example.com` is the
 sending domain):
@@ -240,15 +259,18 @@ the form.
 
 ### Two adoption modes (Mode A vs Mode B)
 
-knowless supports two UX flows out of the box. Pick per-action,
-not per-app — both can coexist.
+In plain English: **"sign in, then do the thing"** (Mode B) and
+**"do the thing, confirm by email"** (Mode A). knowless supports
+both out of the box; pick per-action, not per-app — they coexist.
+The Mode A/B labels are used here and in the CHANGELOG so
+discussions across the docs stay unambiguous.
 
-**Mode B — register-first (the default).** User must log in before
-performing the action. Wire `auth.login` / `auth.callback` as
-above; gate your action with `auth.handleFromRequest(req)`. Use
-when the action requires a session (account settings, paid
-features, anything you want tied to an identity at the moment of
-the action).
+**Mode B — "sign in, then do the thing" (register-first, the default).**
+User must log in before performing the action. Wire `auth.login` /
+`auth.callback` as above; gate your action with
+`auth.handleFromRequest(req)`. Use when the action requires a session
+(account settings, paid features, anything you want tied to an
+identity at the moment of the action).
 
 ```js
 app.post('/api/comments', (req, res) => {
@@ -258,12 +280,12 @@ app.post('/api/comments', (req, res) => {
 });
 ```
 
-**Mode A — use-first, claim-later.** User performs the action
-without logging in; you capture their email and trigger a magic
-link. Clicking it opens a session and your callback handler
-"promotes" the deferred resource. Use for "drop a pin," "post a
-share link," "submit a paste" — patterns where forcing a login
-*before* the action would harm the UX.
+**Mode A — "do the thing, confirm by email" (use-first, claim-later).**
+User performs the action without logging in; you capture their email
+and trigger a magic link. Clicking it opens a session and your
+callback handler "promotes" the deferred resource. Use for "drop a
+pin," "post a share link," "submit a paste" — patterns where forcing
+a login *before* the action would harm the UX.
 
 ```js
 app.post('/api/pins', async (req, res) => {
@@ -277,6 +299,14 @@ app.post('/api/pins', async (req, res) => {
     // Per-call subject so the user can tell at a glance this is a
     // pin-confirmation, not a routine login. AF-9.
     subjectOverride: `Confirm your pin: ${shortcode}`,
+    // Per-call body so subject and body agree. AF-26 (v0.2.2).
+    // knowless still composes the URL and validates the rendered
+    // output (ASCII / URL on its own line / ≤2048 chars). bodyFooter
+    // still appends; the lastLogin line does NOT auto-append on
+    // overridden bodies — the template owns the content.
+    bodyOverride: ({ url }) =>
+      `Confirm your pin "${shortcode}":\n\n${url}\n\n` +
+      `This link expires in 15 minutes. If you didn't request it, ignore.\n`,
   });
   res.status(202).end();  // "we'll email you the link"
 });
@@ -630,6 +660,24 @@ Full options table:
 
 ## FAQ
 
+### Is there an official knowless Docker image?
+
+No. knowless does not ship a turnkey image with Postfix + null-route
++ the binary pre-baked. The reasoning: a Docker image bundling
+Postfix wouldn't actually save the operator from the work that
+matters (SPF / DKIM / PTR records on your sending domain, outbound
+port 25 unblocked at your hosting provider, reverse DNS pointed at
+your sending hostname — all done outside the container regardless),
+and shipping a Postfix image would commit a walk-away library to a
+permanent CVE-rebuild cadence. The OPS.md walkthrough is the
+canonical install path; a fresh VPS to working forward-auth takes
+30–60 minutes of one-time setup, and then it stays put.
+
+If a community Dockerfile emerges (open invitation — knowless is
+Apache-2.0), OPS.md will link to it. Until then, run
+`knowless-server` as a systemd unit alongside Postfix as the OPS
+walkthrough lays out.
+
 ### Why doesn't knowless block disposable email domains?
 
 Disposable-domain blocking (mailinator.com, throwaway.email, etc.) is

package/README.md

@@ -7,198 +7,146 @@ that don't need to email their users for anything but the sign-in link.
 npm install knowless
 ```
 
-> v0.2.1 | Node.js >= 22.5 | **1 production dep (nodemailer)** | Apache-2.0
+> v0.2.2 | Node.js >= 22.5 | **1 production dep (nodemailer)** | Apache-2.0
 
-## Why this exists
+## Where to go next
 
-Most auth libraries (Auth0, Clerk, Magic, Firebase Auth) default to
-maximum identity collection: full email stored in plaintext, profile
-fields, recovery email, federation. Even nominally privacy-focused
-options store enough that a breach is materially harmful.
+Two docs live alongside this README. They serve different readers; pick
+the one that matches yours.
 
-knowless is the simpler answer that always worked: **magic link in,
-session cookie out, nothing else stored.** Email is HMAC-hashed at the
+| You are | Read this | What's there |
+|---|---|---|
+| **A human integrating for the first time** | [`GUIDE.md`](GUIDE.md) | Step-by-step walkthrough — install, generate the secret, set up Postfix, mount handlers, both modes worked end-to-end. Configuration reference, FAQ, troubleshooting. |
+| **An AI agent, or reading in a hurry** | [`knowless.context.md`](knowless.context.md) | Dense single-file reference. Public API table, every option with defaults, 19 gotchas, lifecycle diagrams, the sham-work pattern, threat model, "what's NOT in knowless and why." Designed to fit one context window. |
+| **Deploying to a real server** | [`OPS.md`](OPS.md) | Postfix install, SPF/DKIM/PTR/DMARC, null-route, systemd, Caddy/nginx/Traefik forward-auth, MailHog dev, fail2ban, multi-process. |
+| **Tracking what changed** | [`CHANGELOG.md`](CHANGELOG.md) | Version history. |
+
+## What it does
+
+The simpler answer that always worked: **magic link in, session
+cookie out, nothing else stored.** Email is HMAC-hashed at the
 boundary and discarded. The library refuses, by API shape, to send
 anything but the sign-in link or store anything identifying.
 
+Most auth libraries default to maximum identity collection: full email
+in plaintext, profile fields, recovery email, federation. Even
+nominally privacy-focused options store enough that a breach is
+materially harmful. knowless inverts the default.
+
 The thesis: most services have ten layers of auth tooling where they
 need two.
 
-## Two modes — pick per action
-
-Same library, two flows. They coexist in one app; choose per-endpoint
-based on whether forcing a login *before* the action would harm UX.
+## How it works
 
-### Mode B — register-first (the form)
+```
+email  →  HMAC-SHA256(secret, normalize(email))  →  opaque handle
+            |                                         |
+            v                                         v
+       magic-link token (256-bit, single-use)    sessions, tokens
+            |                                         |
+            v                                         v
+       submitted via localhost SMTP             stored as SHA-256 hashes
+            |
+            v
+       user clicks  →  handle resolved  →  signed cookie set
+```
 
-User must log in before performing the action. Standard "sign in to
-continue" flow.
+- **Plaintext email is never persisted.** Only the salted hash
+  (`HMAC-SHA256(secret, normalized_email)`).
+- **Only the magic link is ever sent.** No welcome, no digest, no
+  notification. There is no API to send anything else.
+- **All outbound mail goes via your localhost MTA.** No vendor SDKs,
+  no API tokens.
+- **Tokens are SHA-256 at rest, single-use, 15-min TTL.** Raw token
+  never persisted.
+- **Session cookies are HMAC-signed.** No JWT, no algorithm confusion.
+- **Sham work on every miss.** Unknown emails do the same work as
+  registered ones (compose, submit, log) but the SMTP recipient is a
+  null-route. Times equivalent within 1ms — measured in CI.
 
-- User hits `/login`, types email
-- Magic link arrives, click → session cookie
-- Your protected endpoints call `auth.handleFromRequest(req)` to gate
-  access
+## Two modes
 
-Use for: account settings, paid features, anything that requires an
-identified user at the moment of the action.
+Same library, two flows. They coexist in one app — pick per action.
 
-### Mode A — use-first, claim-later (programmatic)
+- **"Sign in, then do the thing"** — a normal login.
+- **"Do the thing, confirm by email"** — drop a pin, post a comment,
+  share a link without an account, and the email confirmation creates
+  the account in the background.
 
-User performs the action *without* being logged in. You capture their
-email along with the action, fire a magic link via
-`auth.startLogin({email, nextUrl, ...})`, and clicking it opens a
-session and "promotes" the deferred resource.
+The same sham-work flow runs underneath either mode, so unknown
+emails, rate-limit hits, and real sends look identical to an external
+observer.
 
-Use for: drop-a-pin / submit-a-paste / share-a-link / disposable
-resources / anywhere logging in first kills the UX.
+Worked code for both in [`GUIDE.md`](GUIDE.md).
 
-The same 12-step sham-work flow runs underneath either mode, so
-unknown emails, rate-limit hits, and real sends look identical to an
-external observer (the FR-6 timing-equivalence guarantee). Pick per
-action; the two coexist.
+## Two deployment shapes
 
-Worked code for both modes is in [`GUIDE.md`](GUIDE.md). The dense
-API reference is [`knowless.context.md`](knowless.context.md).
+| Shape | When |
+|---|---|
+| **Library mode** | Mount the five handlers (`login`, `callback`, `verify`, `logout`, `loginForm`) in your existing Node app. |
+| **Standalone server** (`npx knowless-server`) | Forward-auth gateway behind Caddy / nginx / Traefik for self-hosters gating Uptime Kuma / AdGuard / Pi-hole / Sonarr / Jellyfin / etc. One auth subdomain, SSO across services via the parent-domain cookie. |
 
 ## What's opinionated (locked by design)
 
-These are deliberate trade-offs, documented as `NO-GO` in
-[`docs/01-product/PRD.md`](docs/01-product/PRD.md) §14.
-The library refuses, by API shape, to grow into them.
+Deliberate trade-offs. The library refuses, by API shape, to grow
+into them.
 
-- **Localhost SMTP only.** No Mailgun/Postmark/SES/Resend. The
-  operator runs Postfix (or another MTA) on the same host, in
-  outbound-only mode.
-- **One mail purpose: the sign-in link.** No welcome message, no
-  digest, no notification. There is no `sendNotification()` to be
-  tempted by.
+- **Localhost SMTP only.** No Mailgun / Postmark / SES / Resend.
+- **One mail purpose: the sign-in link.** No `sendNotification()` to
+  be tempted by.
 - **Plain-text 7-bit email.** No HTML, no tracking pixels, no
   click-rewriting, no read-receipts.
 - **No OAuth / OIDC / SAML.** Different audience.
 - **No 2FA / WebAuthn / TOTP / passkeys.** Compose with a separate
   library if you need them.
 - **No admin UI.** `sqlite3 knowless.db` is the admin UI.
-- **Hardcoded login form.** No template overrides; fork or live
-  with it.
-- **No telemetry, analytics, or error reporting.** Self-hostable end
-  to end. No phone-home of any kind.
+- **Hardcoded login form.** No template overrides; fork or live with
+  it.
+- **No telemetry, analytics, or error reporting.** No phone-home of
+  any kind.
 - **Walks away at v1.0.0.** Maintenance mode after that — only
   security fixes.
 
-## What's swappable
+If any of those break your case, knowless isn't the right tool. Look
+at [Lucia](https://lucia-auth.com/), [Auth.js](https://authjs.dev/),
+or commercial offerings.
 
-Everything that *isn't* identity-shape or threat-model essential is
-config or injection.
-
-| Knob | Default | Common reasons to change |
-|---|---|---|
-| `dbPath` | `./knowless.db` | Move to `/var/lib/knowless/...` for systemd; share across processes |
-| `smtpHost`, `smtpPort` | `localhost`, `25` | Point at MailHog (`localhost:1025`) for dev mail inspection |
-| `cookieDomain` | hostname of `baseUrl` | Set to your eTLD+1 for SSO across subdomains |
-| `cookieSecure` | `true` | `false` only for `http://localhost` dev (logs a warning) |
-| `tokenTtlSeconds`, `sessionTtlSeconds` | `900`, `2592000` | Tighten for high-security uses; loosen at your peril |
-| `openRegistration` | `false` | `true` to let any new email auto-register on first link |
-| `subject` | `Sign in` | Match your brand; per-call override on `startLogin` (`subjectOverride`) |
-| `bodyFooter` | none | Append a constant brand/legal/feedback line to every magic-link mail |
-| `confirmationMessage` | (default copy) | Replace the post-submit "we'll email you" text |
-| `maxLoginRequestsPerIpPerHour`, `maxNewHandlesPerIpPerHour` | `30`, `3` | Raise for genuinely shared NATs; `0` to disable in dev |
-| `trustedProxies` | `[127.0.0.1, ::1]` | Plain IPs **and** CIDRs (`10.0.0.0/8`) for k8s/docker/cgnat |
-| `bypassRateLimit` (per-call) | `false` | Trusted CLI/cron callers via `auth.startLogin` |
-| `store` | built-in `node:sqlite` | Inject your own store (Postgres, etc.) |
-| `mailer` | built-in nodemailer | Inject your own mailer |
-| `transportOverride` | none | Pass a custom `nodemailer.createTransport` |
-| `onSweepError(err)` | none | Operator alerting hook for sweeper failures |
-| `devLogMagicLinks` | `false` | `true` in dev: print magic-link URLs (or silent-miss hints) to stderr when SMTP fails |
-
-Full table with defaults, types, and validation rules:
-[`GUIDE.md`](GUIDE.md) → "Configuration reference."
-
-## Two deployment shapes (one codebase)
-
-| Mode | Status | When |
-|---|---|---|
-| **Library mode** | shipped (v0.1.0) | Mount handlers in your existing Node app |
-| **Standalone server** (forward-auth) | shipped (v0.1.3) | Self-hosters gating Uptime Kuma / AdGuard / Pi-hole / Sonarr / etc. behind Caddy / nginx / Traefik |
-
-Library mode is the six-line example in [`GUIDE.md`](GUIDE.md).
-Standalone server is `npx knowless-server` — full Postfix + DNS +
-reverse-proxy walkthrough in [`OPS.md`](OPS.md).
+## Operator commitments
 
-## First customer: addypin
+By choosing knowless, you commit to running:
 
-[`addypin`](https://github.com/hamr0/addypin) — location-sharing
-service in the same hermit-architecture lineage — adopted knowless
-as its auth+mail layer. The integration delta:
+- **Postfix** (or another MTA) on the same host, outbound-only
+- **SPF, DKIM, PTR** records for your sending domain
+- **Outbound port 25** open (some clouds block it)
+- A **null-route** for the configured `shamRecipient` so silent-miss
+  sham mail drops, not bounces
 
-- **~1,150 lines of bespoke auth/mail code removed** (custom mailer,
-  inbound CLI, login plumbing, pin-confirmation state machine, email
-  fingerprinting helpers, the matching test files)
-- **~35 lines of knowless wiring added**
-- **~33× reduction** on the auth/mail surface
-- **One production dep** (`nodemailer` only; v0.2.0 dropped
-  `better-sqlite3` for `node:sqlite`, the stdlib SQLite driver — no
-  C++ toolchain, no native compile, ~40 transitive packages → 2)
+Step-by-step in [`OPS.md`](OPS.md).
 
-The integration round produced the audit findings AF-7 through AF-17
-that drove v0.1.5 → v0.1.10. See [`docs/01-product/PRD.md`](docs/01-product/PRD.md)
-§17 for the full backlog.
+## Threat model — one paragraph
 
-## Operator commitments
+**Defends well:** DB-only leaks (handles are HMAC-salted),
+plaintext-email exfiltration (none persisted), password reuse (no
+passwords), silent email enumeration via the login form (timing-
+equivalent + same response shape), email-bombing a target (per-handle
+token cap), naive bots (honeypot), account-creation spam (per-IP
+caps), replay attacks (atomic mark-token-used), open redirects
+(`next_url` whitelist), CSRF on POST endpoints (Origin/Referer
+whitelist).
 
-By choosing knowless, you commit to:
-
-- Running your own server with **Postfix** (or another MTA) installed
-  for outbound-only mail
-- Setting up **SPF, DKIM, and PTR** for your sending domain
-- Verifying **outbound port 25** is open (some clouds block it)
-- A **null-route entry** for the configured `shamRecipient` so
-  silent-miss sham mail is dropped, not bounced
-- Accepting that the magic link is the **only email** your service
-  ever sends
-
-Step-by-step in [`OPS.md`](OPS.md): Postfix install, null-route,
-SPF/DKIM/PTR/DMARC, systemd unit, Caddy / nginx / Traefik
-forward-auth examples, Tailscale pattern, reverse-proxy rate
-limiting, fail2ban / Turnstile, multi-process deployments, MailHog
-dev workflow, backups.
-
-## Documentation
-
-- [**`GUIDE.md`**](GUIDE.md) — start here. Adopter walkthrough,
-  install, six-line example, both modes worked end-to-end,
-  configuration reference, FAQ, troubleshooting.
-- [**`knowless.context.md`**](knowless.context.md) — dense reference
-  for AI agents and humans-in-a-hurry. Public API table, all options,
-  18 gotchas, lifecycles, the sham-work pattern, threat model
-  summary.
-- [`OPS.md`](OPS.md) — operator setup, fresh VPS to working forward-auth.
-- [`CHANGELOG.md`](CHANGELOG.md) — version history.
-- [`docs/01-product/PRD.md`](docs/01-product/PRD.md) — product
-  requirements, threat model, decisions log, NO-GO table, audit
-  findings backlog.
-- [`docs/02-design/SPEC.md`](docs/02-design/SPEC.md) — wire formats,
-  algorithms, byte layouts (reimplementation-grade).
-
-## Threat model (one-paragraph)
-
-Honest version (full detail in [PRD §12](docs/01-product/PRD.md)):
-
-**Defends well:** DB-only leaks, plaintext-email exfiltration, password
-reuse / credential stuffing, silent email enumeration (timing-
-equivalent within 1ms locally), email-bombing a target, naive bot
-traffic, account-creation spam, replay attacks, open redirects, CSRF
-on `POST /login` / `POST /logout` (Origin/Referer whitelist).
-
-**Defends partially:** HMAC-secret-only leak (allows targeted
-existence checks but not session forgery), phishing (no password to
-type into a fake site, but a phished mailbox still receives links).
+**Partially:** HMAC-secret-only leak (allows targeted existence
+checks but not session forgery), phishing (no password to type into a
+fake site, but a phished mailbox still receives links).
 
 **Does NOT defend against:** sophisticated bots that bypass the
 honeypot, distributed floods from many IPs, full server compromise,
-compromised email accounts, social engineering, insider threat at
-the operator. Layer-2 defences (Cloudflare, fail2ban, reverse-proxy
-rate-limits) belong above the library; [`OPS.md`](OPS.md) §9–§10
-covers the patterns.
+compromised email accounts, social engineering, insider threat at the
+operator. Layer-2 defences (Cloudflare, fail2ban, reverse-proxy
+rate-limits) belong above the library — patterns in
+[`OPS.md`](OPS.md).
+
+Full detail in [`knowless.context.md`](knowless.context.md) §
+"Threat model summary."
 
 ## Sibling projects
 
@@ -207,14 +155,6 @@ covers the patterns.
 - [`gitdone`](https://github.com/hamr0/gitdone) — verified email
   actions via DKIM/SPF inbound
 
-## Contributing
-
-Issues and PRs welcome at <https://github.com/hamr0/knowless>.
-
-Per the v1.0.0 walk-away framing in PRD §6.3: feature requests after
-v1.0.0 ships will be deflected to the [§14 NO-GO table](docs/01-product/PRD.md)
-or to sibling projects. The library being "done" is a feature.
-
 ## License
 
 [Apache 2.0](LICENSE) with [`NOTICE`](NOTICE) preservation. Forks

package/knowless.context.md

@@ -1,7 +1,7 @@
 # knowless -- Integration Guide
 
 > For AI assistants and developers wiring knowless into a project.
-> v0.2.1 | Node.js >= 22.5 | 1 dep (nodemailer) | Apache-2.0
+> v0.2.2 | Node.js >= 22.5 | 1 dep (nodemailer) | Apache-2.0
 
 ## What this is
 
@@ -160,7 +160,7 @@ 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?, 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. |
+| `startLogin` | ({email, nextUrl?, sourceIp?, subjectOverride?, bodyOverride?, 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. `bodyOverride` (AF-26, v0.2.2) is a `({url}) => string` template fn that replaces the default body — knowless still composes the URL and validates the rendered output (ASCII, URL on its own line, ≤2048 chars); `bodyFooter` still appends. `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. |
 | `verifyTransport` | -- | Promise\<true\> | Probe the configured SMTP transport (v0.2.1). Resolves true on success, rejects with the underlying error. Adopters call this explicitly when they want fail-fast on misconfigured SMTP at boot — no auto-on-boot variant by design (k8s readiness probes / docker-compose ordering would fail boot for the wrong reason). AF-20. |
@@ -178,6 +178,7 @@ import {
   composeBody,      // pure: build the mail body
   validateSubject,  // pure: validate operator-supplied subject
   validateBodyFooter, // pure: validate operator-supplied footer (AF-8.2)
+  validateBodyOverride, // pure: validate per-call body override (AF-26)
   renderLoginForm,  // pure: HTML5 page rendering
   normalize,        // pure: email normalization
   deriveHandle,     // pure: HMAC-SHA256(hex-decoded secret, email)
@@ -363,6 +364,21 @@ transport_maps = hash:/etc/postfix/transport
 postmap /etc/postfix/transport && systemctl reload postfix
 ```
 
+Verify the null-route is actually discarding (one-line operator
+check, no knowless code involved):
+
+```
+swaks --to null@knowless.invalid --server localhost:25 --quit-after RCPT
+journalctl -u postfix --since '1 minute ago' | grep 'discard'
+```
+
+A `discard:` line in the postfix log confirms the null-route caught
+the message. If you see `relay=` or `delivered`, the
+`transport_maps` entry isn't being applied — re-run `postmap` and
+`systemctl reload postfix`. (No `--check-null-route` CLI in
+knowless: an operator's MTA validation lives with the MTA, not
+inside a walk-away library.)
+
 ## FR-6: timing equivalence (the testable property)
 
 The library ships a CI test (`test/integration/timing.test.js`)
@@ -619,12 +635,12 @@ rate-limits) belongs above the library.
     `console.warn` if it sees `Content-Length > 0` with an empty
     body. AF-7.1.
 
-16. **Two adoption modes — Mode B (register-first) and Mode A
-    (use-first claim-later).** Mode B is the form (`auth.login`).
-    Mode A is `auth.startLogin({email, nextUrl, sourceIp})` for
-    "drop a pin, claim by email click" patterns. Both run the
-    identical 12-step sham-work flow; same FR-6 guarantee. Pick
-    per-action, not per-app.
+16. **Two adoption modes — "sign in, then do" (Mode B) and "do
+    then confirm by email" (Mode A).** Mode B is the form
+    (`auth.login`). Mode A is `auth.startLogin({email, nextUrl,
+    sourceIp})` for "drop a pin, claim by email click" patterns.
+    Both run the identical 12-step sham-work flow; same FR-6
+    guarantee. Pick per-action, not per-app.
 
 17. **Secret is hex-decoded (AF-8.1, since v0.1.6).** Pass a
     64-char lowercase hex string; knowless decodes to 32 raw bytes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "knowless",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "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

@@ -2,7 +2,7 @@ import crypto from 'node:crypto';
 import { normalize, deriveHandle } from './handle.js';
 import { issueToken, hashToken } from './token.js';
 import { newSid, signSession, verifySessionSignature } from './session.js';
-import { composeBody, validateSubject } from './mailer.js';
+import { composeBody, validateSubject, validateBodyOverride } from './mailer.js';
 import { renderLoginForm } from './form.js';
 import {
   buildTrustedPeers,
@@ -256,7 +256,14 @@ export function createHandlers({ store, mailer, config, events }) {
    *   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, bypassRateLimit = false }) {
+  async function runSendLink({
+    emailRaw,
+    nextRaw,
+    sourceIp,
+    subject,
+    bodyOverride,
+    bypassRateLimit = false,
+  }) {
     // Step 1: parse + normalize
     let emailNorm;
     try {
@@ -343,13 +350,31 @@ export function createHandlers({ store, mailer, config, events }) {
     // hammering of a single handle without per-event identity leakage.
     if (evicted > 0) ev.rateLimitHit();
 
-    const mailBody = composeBody({
-      tokenRaw: token.raw,
-      baseUrl: cfg.baseUrl,
-      linkPath: cfg.linkPath,
-      lastLoginAt,
-      bodyFooter: cfg.bodyFooter,
-    });
+    // AF-26: per-call body override for startLogin (Mode A). When
+    // provided, the adopter's template function receives the composed
+    // magic-link URL and returns the full body text. Same submit path,
+    // same sham work, same FR-6 timing equivalence — just lets adopters
+    // phrase the body to match per-call subjects (pin confirmation,
+    // login, expiry warning). bodyFooter still appends; lastLogin line
+    // does not (override is full-content replacement).
+    let mailBody;
+    if (typeof bodyOverride === 'function') {
+      const url = `${cfg.baseUrl}${cfg.linkPath}?t=${token.raw}`;
+      const rendered = bodyOverride({ url });
+      validateBodyOverride(rendered, url); // throws on invalid
+      mailBody = rendered;
+      if (cfg.bodyFooter) {
+        mailBody += `\n-- \n${cfg.bodyFooter}\n`;
+      }
+    } else {
+      mailBody = composeBody({
+        tokenRaw: token.raw,
+        baseUrl: cfg.baseUrl,
+        linkPath: cfg.linkPath,
+        lastLoginAt,
+        bodyFooter: cfg.bodyFooter,
+      });
+    }
 
     // AF-9: programmatic callers may override the subject per call
     // (addypin sends confirmation / login / expiry-warning all via
@@ -454,6 +479,7 @@ export function createHandlers({ store, mailer, config, events }) {
     nextUrl,
     sourceIp = '',
     subjectOverride,
+    bodyOverride,
     bypassRateLimit = false,
   } = {}) {
     // Programmer-error guards (AF-7.3). These DO throw; they're not
@@ -480,11 +506,20 @@ export function createHandlers({ store, mailer, config, events }) {
       validateSubject(subjectOverride); // throws on invalid
       subject = subjectOverride;
     }
+    // AF-26: per-call body override. The function is called inside
+    // runSendLink with the composed magic-link URL; its return value
+    // is validated by validateBodyOverride(). The arg-type check
+    // happens here at the API edge so a non-function bodyOverride
+    // fails fast, before any token is minted.
+    if (bodyOverride !== undefined && bodyOverride !== null && typeof bodyOverride !== 'function') {
+      throw new Error('startLogin: bodyOverride must be a function when provided');
+    }
     const { handle } = await runSendLink({
       emailRaw: email,
       nextRaw: nextUrl ?? null,
       sourceIp,
       subject,
+      bodyOverride,
       bypassRateLimit,
     });
     // Same-shape return: rate-limit / sham / real all collapse here.

package/src/index.js

@@ -273,7 +273,13 @@ export function knowless(options = {}) {
 }
 
 export { createStore } from './store.js';
-export { createMailer, composeBody, validateSubject, validateBodyFooter } from './mailer.js';
+export {
+  createMailer,
+  composeBody,
+  validateSubject,
+  validateBodyFooter,
+  validateBodyOverride,
+} from './mailer.js';
 export { createHandlers } from './handlers.js';
 export { renderLoginForm } from './form.js';
 export { normalize, deriveHandle, secretBytes } from './handle.js';

package/src/mailer.js

@@ -139,6 +139,60 @@ export function composeBody({ tokenRaw, baseUrl, linkPath, lastLoginAt, bodyFoot
   return body;
 }
 
+/**
+ * Validate a body produced by `startLogin`'s `bodyOverride` template
+ * function (AF-26). The override lets adopters phrase the email body
+ * to match per-call subjects (pin confirmation, login, etc.) without
+ * losing knowless's URL-composition / sham-work / 7bit invariants.
+ *
+ * Constraints (deliberately strict to preserve the v0.11 POC URL-line
+ * invariant — QP soft-breaks WILL break the magic link):
+ *   - non-empty string
+ *   - ≤ 2048 chars (operator-side overflow guard)
+ *   - ASCII only
+ *   - no CR (LF allowed; defense-in-depth header-injection guard)
+ *   - the magic-link URL appears EXACTLY ONCE
+ *   - that occurrence is on its own line (no leading or trailing
+ *     non-newline characters on the same line)
+ *
+ * Throws on any violation. Adopter is responsible for the rest of
+ * the body content (security advice, expiry hint, etc.); knowless
+ * does not enforce semantic content.
+ *
+ * @param {unknown} body
+ * @param {string} url  the magic-link URL knowless composed
+ * @returns {void} throws on invalid
+ */
+export function validateBodyOverride(body, url) {
+  if (typeof body !== 'string' || body.length === 0) {
+    throw new Error('bodyOverride must return a non-empty string');
+  }
+  if (body.length > 2048) {
+    throw new Error('bodyOverride must return ≤ 2048 chars');
+  }
+  if (!ASCII_RE.test(body)) {
+    throw new Error('bodyOverride must return ASCII');
+  }
+  if (body.includes('\r')) {
+    throw new Error('bodyOverride must not contain CR (header-injection defense)');
+  }
+  const occurrences = body.split(url).length - 1;
+  if (occurrences === 0) {
+    throw new Error('bodyOverride must include the magic-link URL exactly once');
+  }
+  if (occurrences > 1) {
+    throw new Error('bodyOverride must include the magic-link URL exactly once');
+  }
+  const lines = body.split('\n');
+  const ownLineCount = lines.filter((l) => l === url).length;
+  if (ownLineCount !== 1) {
+    throw new Error(
+      'bodyOverride must place the magic-link URL on its own line ' +
+        '(preserves the 7bit URL-line invariant; QP soft-breaks would break the link)',
+    );
+  }
+}
+
 /**
  * Validate operator-overridden subject per SPEC §12.5.
  * Throws on invalid; warns (returns warnings array) on suspicious-but-allowed.