knowless 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -15,14 +15,191 @@ 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. Targeted for v0.2.1.
-- 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.1.
+**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
+
+**Operator visibility, opt-in.** Three event hooks + one method,
+the full surface forum + addypin asked for during the v0.2.0
+integration spike. The shape was negotiated against
+`walk-away-at-v1.0.0` (PRD §6.3): every "obvious" addition was
+deliberately rejected if it could be done in adopter or perimeter
+code. See `knowless.context.md` § "What's NOT in knowless, and why"
+for the rejected-by-design list (disposable-domain check, account-age
+accessor, hashcash, `lookupMessageId()`, `onShamHit`).
+
+### Added
+
+- **`onMailerSubmit({messageId, handle, timestamp})` (AF-19).**
+  Per-event hook fired on successful SMTP submission for *real*
+  (non-sham) sends only. Adopters log it, build msg_id ↔ handle
+  correlation maps, or pipe to structured logging. Knowless never
+  stores the mapping. Sham branches deliberately do NOT fire this
+  hook — that's the load-bearing NFR-10 invariant (would let a
+  careless adopter log per-handle data and reopen the enumeration
+  oracle that sham-work was designed to prevent).
+- **`onTransportFailure({error, timestamp}) (AF-19).** Per-event
+  hook fired on SMTP errors. No identity data — safe per-event,
+  safe to alert on.
+- **`onSuppressionWindow({sham, rateLimited, windowMs})` (AF-19).**
+  Heartbeat hook fired every `suppressionWindowMs` (default 60s)
+  with aggregate counters across all silent-202 branches: sham
+  hits, `login_ip` cap, `create_ip` cap (counted both as sham and
+  rate-limited when fall-through happens), and per-handle token-cap
+  rotation. Heartbeats fire even when both counters are zero — a
+  missing emission is itself diagnostic. Replaces a per-event
+  `onShamHit` / `onRateLimitHit` design that would have leaked
+  per-handle data through log lines; the windowed aggregate
+  preserves the spike signal without per-call distinguishability.
+- **`auth.verifyTransport()` method (AF-20).** Wraps
+  `transport.verify()`. Resolves `Promise<true>` on non-rejection,
+  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 (AF-21).** Deployments where
+  knowless starts before Postfix (docker-compose ordering, k8s
+  readiness probes) would fail boot for the wrong reason.
+- **`startLogin` silent-202 documented (AF-22).** New gotcha #19 in
+  `knowless.context.md` and a Mode-A pointer in GUIDE.md make
+  explicit that `startLogin` returns `{handle, submitted: true}`
+  for every branch (real, sham, rate-limited, missing handle) by
+  design. Operators who need branch visibility wire the v0.2.1
+  hooks; the per-call return shape never reveals which branch ran.
+
+### Changed
+
+- **`store.insertToken` returns the eviction count.** Internal
+  store-interface change: `insertToken` now returns the number of
+  tokens evicted to make room for the new one (always `0` when
+  `maxActive` is `0`). Used by `runSendLink` to count per-handle
+  cap rotation events into the `rateLimited` counter. Adopters
+  with custom stores implementing the SPEC §13 interface should
+  update accordingly; the change is forward-compatible (returning
+  `undefined` is treated as zero evictions).
+
+### Documentation (forum + addypin negotiation outcome)
+
+- **knowless.context.md § "What's NOT in knowless, and why"** —
+  permanent record of three rejected-by-design additions
+  (disposable-domain check, account-age accessor, per-IP hashcash)
+  with the seam argument and walk-away-at-v1.0.0 framing. Future
+  contributors evaluating "should X go in knowless?" run two tests
+  before answering yes: identity layer vs behavior layer; mechanism
+  living with policy.
+- **GUIDE.md FAQ** — "Why doesn't knowless block disposable email
+  domains?" + "How do I check how old a user is?" with adopter-side
+  code patterns for both. Closes the most likely "but-can-it" requests.
+
+### Internal
+
+- Hook errors are caught and swallowed via a single `safeHook()`
+  wrapper, matching the existing `onSweepError` contract. Knowless
+  never crashes because an operator's observability sink threw.
+- Suppression-window timer is `unref()`'d and only started when
+  `onSuppressionWindow` is wired — adopters not using the hook
+  spend zero `setInterval` slots on it.
+- 16 new tests in `test/integration/v021-hooks.test.js` covering
+  payload shapes, the sham-no-fire invariant, aggregation
+  semantics, heartbeat behavior, counter reset, hook-error
+  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
 

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"
 });
@@ -295,6 +325,11 @@ return identical shapes — the caller can't observe which happened.
 This preserves FR-6 timing equivalence even for programmatic
 callers. See SPEC §7.3a for the full contract.
 
+If you need *operator* visibility (not per-call: aggregate counts and
+real-send confirmation), wire the v0.2.1 hooks documented in
+[Step 8](#step-8-optional-operator-monitoring-via-event-hooks-v021)
+below — they emit without breaking the per-call silent-202 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. The instance method **normalizes the
@@ -469,6 +504,76 @@ Library doesn't ship a built-in HTTP endpoint for this — operator
 chooses the UX (admin CLI, in-app self-service, ticket-driven
 support).
 
+### Step 8 (optional): Operator monitoring via event hooks (v0.2.1+)
+
+Three event hooks + one opt-in method. All optional, all opt-in. None
+are required for correct operation; the library is fully functional
+with zero hooks wired. They exist so an operator can wire knowless to
+their existing observability stack (Prometheus, statsd, structured
+logs, on-call paging) without knowless curating its own metrics shape.
+
+```js
+const auth = knowless({
+  // ...required + existing options...
+
+  onMailerSubmit: ({messageId, handle, timestamp}) => {
+    log.info('knowless.dispatch', { messageId, handle, ts: timestamp });
+  },
+  onTransportFailure: ({error, timestamp}) => {
+    log.error('knowless.smtp_failed', { err: error.message, ts: timestamp });
+    pager.notify('SMTP transport failed');
+  },
+  onSuppressionWindow: ({sham, rateLimited, windowMs}) => {
+    metrics.gauge('knowless.sham_count', sham);
+    metrics.gauge('knowless.rate_limited', rateLimited);
+    if (sham > BASELINE * 10) pager.notify('possible enumeration attack');
+  },
+  // suppressionWindowMs: 60_000,  // default; configurable
+});
+
+// Optional: explicit transport probe at boot. No auto-probe by design.
+try {
+  await auth.verifyTransport();
+} catch (err) {
+  console.error('SMTP unreachable at boot:', err);
+  process.exit(1);
+}
+```
+
+#### Why three hooks, not four
+
+The two silent-202 branches — sham hits (handle does not exist) and
+rate-limit hits (any of the three caps) — are bundled into one *windowed
+aggregate* (`onSuppressionWindow`) rather than per-event hooks. Per-event
+hooks would let a careless adopter log per-handle data, which is the
+enumeration oracle that sham-work exists to prevent. The HTTP response
+is silent on these branches; the log file must be silent too.
+
+Operators still get the spike signal — a 10× jump in `sham` count over
+the window is the enumeration-attack alarm. They don't get per-call
+correlation to a specific handle, and they shouldn't have it.
+
+`onMailerSubmit` is per-event because it fires *only* on real
+submissions, where the handle was already disclosed by the form
+input. `onTransportFailure` is per-event because it carries no
+identity data.
+
+> **Don't log `onSuppressionWindow` payloads in a way that distinguishes
+> them from `onMailerSubmit` at the log-line level.** The aggregate
+> count is fine; the line itself should be cleanly labeled as a periodic
+> counter emission, not "a sham just happened." If your log shipper or
+> dashboard groups them differently, you've put back the per-event
+> distinguishability the bundling was meant to remove.
+
+#### Why `verifyTransport()` is opt-in
+
+No auto-on-boot variant exists by design. Deployments where knowless
+starts before Postfix (docker-compose ordering, k8s readiness probes
+that run knowless before the SMTP container is healthy) would fail
+boot for the wrong reason. Adopters who want fail-fast call
+`verifyTransport()` explicitly; everyone else gets eventually-consistent
+SMTP startup.
+
 ## Walkthrough: standalone server mode
 
 Run `npx knowless-server`, point Caddy / nginx / Traefik at it for
@@ -555,6 +660,80 @@ 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
+adopter policy, not identity layer. The blocklist is a public GitHub
+repo, the override list is operator-specific, and the cron to refresh
+it lives in your ops layer. Putting the *mechanism* in knowless while
+the *list curation* and *overrides* live in the adopter is the wrong
+seam — both stay together in your form handler.
+
+```js
+// In your /login form handler, before calling auth.login:
+import { DISPOSABLE_DOMAINS, ADOPTER_OVERRIDES } from './disposable-domains.js';
+
+app.post('/login', async (req, res) => {
+  const email = /* parse from body */;
+  const domain = email.split('@')[1]?.toLowerCase();
+  if (domain && DISPOSABLE_DOMAINS.has(domain) && !ADOPTER_OVERRIDES.has(domain)) {
+    // Reply with the same shape as auth.login's success/sham response
+    // to preserve FR-6-equivalent timing at your layer too. Match
+    // status, headers, and body that auth.login would emit.
+    return res.status(200).type('html').send(/* same confirmation HTML */);
+  }
+  return auth.login(req, res);
+});
+```
+
+The same argument applies to per-IP hashcash / proof-of-work: if
+`maxNewHandlesPerIpPerHour: 3` isn't enough for your threat model,
+run hashcash at Caddy or your edge layer — knowless's login form
+deliberately stays zero-JS.
+
+### How do I check how old a handle / user is?
+
+knowless deliberately doesn't expose handle creation dates. The reason:
+"first time this email hit knowless" is rarely the trust signal you
+actually want — you want "first time this user did something meaningful
+in *my app*." A six-month-old knowless handle that has never posted
+has zero application tenure.
+
+Pattern: track `(handle, first_seen_at)` in your own table the first
+time a handle performs the action you care about (first post, first
+purchase, first non-trivial API call). Bucket by your tenure, not
+knowless's.
+
+```js
+// On the action you care about:
+const handle = auth.handleFromRequest(req);
+db.recordFirstSeen(handle, Date.now());  // INSERT OR IGNORE
+const age = db.ageBucketFor(handle);     // 'new' | '1mo' | '1y' | '5y+'
+```
+
+This is also safer: returning a `Date | null` keyed by handle is itself
+an enumeration oracle (null leaks "this handle doesn't exist"). Bucket
+on your side from a table that only knows about handles that have
+already acted.
+
 ### My users say magic links land in spam.
 
 This is operator infrastructure, not the library. The library