knowless 0.2.0 → 0.2.2

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.0 | 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.0 | 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
 
@@ -122,6 +122,17 @@ const auth = knowless({
   sweepIntervalMs: 5 * 60 * 1000,     // periodic sweeper tick
   onSweepError: (err) => { /* alerting hook; errors are swallowed */ },
 
+  // --- Operator visibility (v0.2.1, all opt-in) ---
+  // Per-event hooks. Errors swallowed (matches onSweepError contract).
+  onMailerSubmit:     ({messageId, handle, timestamp}) => { /* */ },
+  onTransportFailure: ({error, timestamp})              => { /* */ },
+  // Heartbeat aggregate. Default 60s; emits even when both counters
+  // are zero. See "Operator visibility" section for the threat-model
+  // reasoning behind aggregating sham + rate-limit branches here
+  // rather than emitting per-event.
+  onSuppressionWindow: ({sham, rateLimited, windowMs}) => { /* */ },
+  suppressionWindowMs: 60_000,
+
   // --- Dev mode (AF-6.2) ---
   // When SMTP submission fails AND this flag is true, the magic link
   // is printed to stderr so a developer can click through. Off by
@@ -149,9 +160,10 @@ 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. |
 | `config` | -- | object | Merged effective config; safe to read (do not mutate) |
 | `close` | -- | void | Stops sweeper, closes mailer + store. Call on shutdown. |
 
@@ -166,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)
@@ -173,6 +186,91 @@ import {
 } from 'knowless';
 ```
 
+## Operator visibility (v0.2.1)
+
+Three event hooks + one opt-in method, shipped in v0.2.1. Future
+contributors reading this section before extending the surface: do not
+add a per-event `onShamHit`, do not add a per-handle `onRateLimitHit`,
+do not add an auto-on-boot probe, do not add a `lookupMessageId()`
+endpoint. Each was considered and deliberately rejected during the
+forum + addypin negotiation that produced this surface (PRD §17.3,
+v0.2.1) — see "What's NOT in knowless" below for the reasoning.
+
+### Three hooks (factory options)
+
+```js
+const auth = knowless({
+  // ...required + existing options...
+
+  // Per-event, safe to log per-call.
+  onMailerSubmit:     ({messageId, handle, timestamp}) => { /* */ },
+  onTransportFailure: ({error, timestamp})              => { /* */ },
+
+  // Batched aggregate. Fires every windowMs regardless of count
+  // (heartbeat). Default cadence 60s.
+  onSuppressionWindow: ({sham, rateLimited, windowMs}) => { /* */ },
+  suppressionWindowMs: 60_000,
+});
+```
+
+Field types:
+- `messageId`: string — SMTP `Message-ID` returned by nodemailer
+- `handle`: string — 64-char hex; only emitted on real (non-sham) submits
+- `timestamp`: number — epoch ms
+- `error`: Error
+- `sham`, `rateLimited`: integer counters, count within the window
+- `windowMs`: integer — the configured window length, echoed in the payload
+
+Errors thrown from hooks are caught and swallowed (matches the existing
+`onSweepError` contract); knowless does not depend on hook delivery for
+correctness.
+
+### Method
+
+`auth.verifyTransport()` — wraps `transport.verify()` on the configured
+SMTP transport. Returns `Promise<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:
+deployments where knowless starts before Postfix (docker-compose
+ordering, k8s readiness probes) would fail boot for the wrong reason.
+
+### Threat-model justification (the durable part)
+
+The two silent-202 branches — sham (handle does not exist) and rate-limit
+(any of the three caps) — are aggregated rather than per-event because
+**NFR-10 timing equivalence applies at the log layer too**, not just the
+HTTP response. A per-event `onShamHit({handle})` lets a careless adopter
+log "sham detected for X" and the log file becomes an enumeration oracle
+— the exact thing sham-work was designed to prevent. The response is
+silent; the log must be silent too.
+
+Knowless has three rate limits, and one of them is identity-tied:
+- `maxLoginRequestsPerIpPerHour` — IP-keyed
+- `maxNewHandlesPerIpPerHour` — IP-keyed
+- `maxActiveTokensPerHandle` — **handle-keyed; per-event hits leak
+  "this handle exists and has hit a token cap"**
+
+Splitting per-event-IP from per-event-handle works in theory and fails
+in practice — future contributor sees the asymmetry and adds the missing
+handle variant for symmetry. Bundling all three into the windowed
+aggregate forecloses that drift.
+
+`onMailerSubmit` carries `handle` per-event because it fires *only on
+real submissions*, where the handle was already disclosed to knowless
+by the form input. Emitting it back to the adopter is not a new leak.
+`onTransportFailure` carries no identity data, per-event safe.
+
+### Why no `lookupMessageId()` endpoint
+
+An earlier proposal added an authenticated `auth.lookupMessageId(id)`
+behind an operator secret so operators could correlate maillog entries
+to handles. Rejected: the same capability is achievable by the adopter
+maintaining their own `(messageId → handle)` map, populated from
+`onMailerSubmit`. Knowless never stores the mapping, never exposes a
+new authenticated surface, never carries operator-secret rotation
+burden. The hook is the mechanism; the correlation map is adopter
+choice.
+
 ## Handle / token / session lifecycles
 
 ```
@@ -266,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`)
@@ -352,6 +465,66 @@ URL/email -> handlers.js (login: 12-step sham-work flow per SPEC §7.3)
 | `src/session.js` | ~80 | Cookie signing/verification with constant-time compare |
 | `src/form.js` | ~110 | Hardcoded login HTML |
 
+## What's NOT in knowless, and why
+
+Three capabilities that look like they belong here but don't, listed
+because the "why not" needs to outlast walk-away-at-v1.0.0. When future
+contributors propose adding any of these back, point them here.
+
+### Disposable-domain blocking — adopter / form handler
+
+Reject `mailinator.com` etc. before knowless sees the submission.
+Mechanism + list + override + weekly cron all live in the adopter's
+form handler.
+
+The argument for putting this in knowless was timing equivalence: if
+the adopter rejects fast, an attacker times the response and learns
+"this domain is on a public blocklist." Counter: the blocklist is a
+public GitHub repo (`disposable-email-domains/disposable-email-domains`).
+Anyone can fetch it directly. Timing-equivalence here protects information
+that isn't secret. Knowless's sham-work protects against email
+*enumeration* (is `alice@x.com` registered?), not domain *classification*
+(is `x.com` on a public list?). Different threat, different defense.
+
+Splitting mechanism (knowless) from policy + list curation (adopter) is
+the wrong seam. Both stay in the adopter's form handler.
+
+### App-tenure / account-age — adopter / first-seen tracking
+
+Knowless's "handle creation date" is when this email first hit knowless.
+The adopter's interesting question is "how long has this user been
+participating in *my app*" — a different number, and the adopter's
+number is the one that should drive trust decisions.
+
+Concrete failure mode: a handle registered with knowless six months ago
+but never posted has zero app-tenure. If the adopter reads knowless's
+age, a brand-new spammer with an old handle gets unearned credibility.
+
+Pattern: adopter stores `(handle, first_seen_at)` the first time it sees
+a handle perform a meaningful action. App-tenure is app-derived. Knowless
+doesn't expose age data — and wouldn't even if it could, because
+returning `Date | null` keyed by handle is itself an enumeration leak.
+
+### Per-IP hashcash / proof-of-work — Caddy / perimeter layer
+
+`maxNewHandlesPerIpPerHour: 3` already covers the ground hashcash would
+cover. A botnet that can't get past three signups per IP per hour needs
+IP rotation regardless; once rotated, a 2s hashcash is rounding error
+at botnet economics. Costs are real: breaks Lynx/w3m (gotcha #10),
+requires JS in the login form (the only zero-JS exception we'd carry),
+~2s UX delay for legit users on weak devices. If a deployment observes
+per-IP signup actually saturating the cap, Caddy (or another perimeter
+layer) can run hashcash off-the-shelf without making knowless carry it.
+
+### The deciding lens
+
+knowless walks away at v1.0.0 (PRD §6.3). Every config option carried
+into v1.0.0 is something v1.x has to keep stable through the
+maintenance window. The test for any proposed addition: does this
+belong in the **identity layer** (who they are) or the **behavior
+layer** (what they did)? Identity layer is in scope. Behavior layer is
+out. When unsure, default out — less surface, less carrying cost.
+
 ## Threat model summary
 
 **Defends well:** DB-only leaks (handles are HMAC-salted),
@@ -462,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
@@ -482,6 +655,15 @@ rate-limits) belongs above the library.
     factory startup; fails fast. Goes after RFC 3676 `"-- "`
     delimiter so mail clients strip it from quoted replies.
 
+19. **`startLogin` is silent at every layer (FR-6).** Returns
+    `{handle, submitted: true}` for *every* branch — real send, sham,
+    rate-limited, missing-handle-with-`openRegistration:false`. Adopters
+    cannot derive the branch from the return value, by design.
+    Operator visibility comes from the v0.2.1 hooks (`onMailerSubmit`
+    per-event, `onSuppressionWindow` aggregated) — *not* from the
+    return shape. Don't wrap `startLogin` in something that surfaces
+    the branch to the caller; that re-opens the enumeration oracle.
+
 ## Constraints
 
 - **Node 20+** -- targeting LTS; tested on Node 22

package/package.json

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