knowless 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -22,10 +22,99 @@ v1.0.0 are:
   user-visible impact)
 - Bug fixes that don't change the API surface
 - Documentation corrections
+- Helper exports that pull existing mechanism back into the library
+
+## [1.1.0] — 2026-05-02
+
+Mailer-contract clarification release. Pulls FR-6 sham-routing
+mechanism back into the library, makes the custom-mailer contract
+explicit, and codifies walk-away scope in the docs.
+
+### Added
+
+- `dropShamRecipient(envelope, shamRecipient?)` — exported pure
+  helper. Custom mailers call it to no-op sham sends without external
+  delivery. Exact-match predicate against the configured
+  `shamRecipient` (default `null@knowless.invalid`). No behaviour
+  change inside the library; ~10 LOC.
+
+### Documented
+
+- `knowless.context.md` § "What knowless is and is not" — scope
+  doctrine: knowless is the substrate for session-bearing logins, not
+  generic confirmation tokens. Adopters with one-shot non-login flows
+  keep their own token system.
+- `knowless.context.md` § "Custom mailer contract" — five explicit
+  obligations for injected mailers: sham-recipient handling, FR-6
+  timing equivalence ownership (≤1ms, mailer's responsibility),
+  RFC822 fidelity, `verify()` semantics, `close()` lifecycle.
+- `knowless.context.md` Public API — "Post-callback handle resolution"
+  block: no callback hook, `nextUrl` route is the seam.
+- `GUIDE.md` § "Stability commitments under walk-away" — what v1.x
+  will and will not accept.
+- `GUIDE.md` § "Custom mailer adapter" — appendix with sendmail-pipe
+  skeleton, FR-6 CI smoke-test pattern, and Postfix fallback note.
+- `GUIDE.md` FAQ — custom login form contract, rate-limit defaults
+  and response shape, Origin/Referer CSRF failure mode (accurate;
+  replaces stale v0.2-era note), SQLite single-process envelope
+  (qualitative; no numeric guarantee carried forward).
+
+No breaking changes. No behaviour changes inside the library.
 
 Feature requests are deflected to PRD §14 NO-GO, to sibling projects,
 or to forking. The library being "done" is a feature.
 
+### Fixed
+
+- **XFF/X-Real-IP never honored through handler path (AF-28).**
+  `createHandlers` pre-built `trustedProxies` into a `{ has }` object
+  and passed it to `determineSourceIp`, which re-called
+  `buildTrustedPeers` on it. The pre-built object is not a `BlockList`,
+  array, or `Set`, so the peer list fell through to `[]`. Net effect:
+  trusted-proxy matching was silently empty in the handler code path —
+  rate limiting hit the reverse-proxy IP instead of the real client IP,
+  and XFF/X-Real-IP headers were ignored regardless of the
+  `trustedProxies` config. Abuse unit tests were passing because they
+  call `determineSourceIp` directly with raw arrays, bypassing the
+  handler path. Fix: removed the pre-build in `createHandlers`;
+  `determineSourceIp` now receives `cfg.trustedProxies` directly. Closes
+  AF-28.
+
+- **`validateSubject` allowed CR/LF, enabling header injection in
+  standalone callers (AF-29).** The ASCII regex `/^[\x00-\x7f]*$/`
+  matched CR (0x0D) and LF (0x0A). `validateSubject` is re-exported as a
+  public validator (AF-9.1 / v0.1.7) so callers using it as a standalone
+  gate were unprotected. `composeRaw` caught the injection downstream, but
+  the validator is the authoritative public guard. Fix: added an explicit
+  `/[\r\n]/` check to `validateSubject`, consistent with the guards already
+  present in `validateFromName` and `validateBodyOverride`. Closes AF-29.
+
+- **Factory `subject` not validated at startup (AF-30).** The factory
+  `subject` option was never passed to `validateSubject` during
+  `createHandlers` startup, breaking the fail-fast pattern that
+  `bodyFooter` (`validateBodyFooter` in `index.js`) and `fromName`
+  (`validateFromName` in `createMailer`) already followed. A non-ASCII
+  subject or empty string silently passed config time and would only fail
+  at first `mailer.submit()` — potentially hours into production. Fix:
+  added `validateSubject(cfg.subject)` to the config-validation block in
+  `createHandlers`. Closes AF-30.
+
+- **`validateBodyFooter` rejected 4-line footers with a trailing newline
+  (AF-31).** `footer.split('\n').length > 4` counted 5 split parts for
+  `"a\nb\nc\nd\n"` (4 logical lines, trailing newline as is conventional
+  for multi-line strings). Fix: strip a single trailing newline before
+  counting: `footer.replace(/\n$/, '').split('\n').length > 4`. Closes
+  AF-31.
+
+### Documentation
+
+- **`runSendLink` JSDoc corrected: `handle` is null for both malformed
+  email and per-IP rate-limit short-circuit (AF-32).** The JSDoc stated
+  `handle` is null "only when the email failed to normalize." The per-IP
+  rate-limit early return also returns `handle: null` because `deriveHandle`
+  has not run at that point. No behavior change — documentation only. Closes
+  AF-32.
+
 ## [1.0.0] — 2026-04-29
 
 **Walk-away release.** No new API surface vs v0.2.3 — v1.0.0 is the

package/GUIDE.md

@@ -106,6 +106,27 @@ nothing else*.
 - **Walks away at v1.0.0.** Maintenance mode (security patches +
   bug fixes) after that, by design.
 
+### Stability commitments under walk-away
+
+v1.x will accept:
+- Documentation corrections and clarifications.
+- Helper exports that pull existing mechanism back into the library
+  (where adopters were re-implementing it inline).
+- Bug fixes that don't change the API surface.
+- Security fixes (CVEs in `nodemailer` or `node:sqlite` with
+  user-visible impact).
+
+v1.x will NOT accept:
+- New flows, new methods on the auth instance, new constructor options.
+- Generalisations toward token-issuance frameworks (see
+  [`knowless.context.md`](knowless.context.md) § "What knowless is and
+  is not").
+- Per-adopter ergonomic shortcuts that the host can implement in ≤30
+  LOC against the existing API.
+
+The library being closed is a feature. Forks are encouraged for
+requirements that don't fit.
+
 ## Walkthrough: library mode
 
 The shape: import `knowless`, configure it, mount the handlers on
@@ -574,6 +595,114 @@ boot for the wrong reason. Adopters who want fail-fast call
 `verifyTransport()` explicitly; everyone else gets eventually-consistent
 SMTP startup.
 
+## Custom mailer adapter (hosts with their own outbound stack)
+
+The default mailer submits via nodemailer to localhost:25 (your Postfix).
+If you already run outbound infrastructure with DKIM signing, a
+transactional API, or a sendmail pipe, you can inject a mailer object:
+
+```js
+import { knowless, dropShamRecipient } from 'knowless';
+
+// Timing-equivalence self-equalisation for subprocess-based mailers.
+// Pre-measure your P95 delivery time, pad real sends to match.
+const TRANSPORT_FLOOR_MS = 8; // example — calibrate for your stack
+
+async function padToTransportFloor(startMs) {
+  const elapsed = performance.now() - startMs;
+  if (elapsed < TRANSPORT_FLOOR_MS) {
+    await new Promise(r => setTimeout(r, TRANSPORT_FLOOR_MS - elapsed));
+  }
+}
+
+const mailer = {
+  async send(envelope, raw) {
+    const t0 = performance.now();
+
+    if (dropShamRecipient(envelope)) {
+      // FR-6: no wire bytes, but burn the same wall time real delivery
+      // would take so real-vs-sham timing stays within ≤1ms.
+      await padToTransportFloor(t0);
+      return;
+    }
+
+    // Example: pipe to sendmail (local MTA handles DKIM via opendkim milter)
+    await new Promise((resolve, reject) => {
+      const proc = spawn('sendmail', ['-t', '-oi'], { stdio: ['pipe', 'ignore', 'pipe'] });
+      let stderr = '';
+      proc.stderr.on('data', d => { stderr += d; });
+      proc.stdin.write(raw);
+      proc.stdin.end();
+      proc.on('close', code => {
+        if (code === 0) resolve();
+        else reject(new Error(`sendmail exited ${code}: ${stderr}`));
+      });
+    });
+    await padToTransportFloor(t0);
+  },
+
+  async verify() {
+    // Optional — called once at factory construction.
+    // Throw here to abort startup on misconfigured transport.
+    // Example: probe that sendmail is available.
+    await execFile('sendmail', ['-bv', 'root']).catch(err => {
+      throw new Error(`sendmail probe failed: ${err.message}`);
+    });
+  },
+
+  // close() is optional — call yourself on shutdown if you allocated resources.
+};
+
+const auth = knowless({ secret, baseUrl, from, mailer });
+```
+
+### Timing-equivalence CI smoke test
+
+Add this to your integration tests to verify your adapter meets the
+≤1ms FR-6 bar:
+
+```js
+// Run 200 warmup pairs, then 500 timed pairs.
+// Assert |mean(real) - mean(sham)| < 1.0ms.
+const WARMUP = 200, SAMPLES = 500;
+const realTimes = [], shamTimes = [];
+
+for (let i = 0; i < WARMUP + SAMPLES; i++) {
+  const t0 = performance.now();
+  await mailer.send({ to: 'alice@example.com' }, RAW_FIXTURE);
+  const tReal = performance.now() - t0;
+
+  const t1 = performance.now();
+  await mailer.send({ to: 'null@knowless.invalid' }, RAW_FIXTURE);
+  const tSham = performance.now() - t1;
+
+  if (i >= WARMUP) { realTimes.push(tReal); shamTimes.push(tSham); }
+}
+
+const mean = arr => arr.reduce((a, b) => a + b, 0) / arr.length;
+const delta = Math.abs(mean(realTimes) - mean(shamTimes));
+assert(delta < 1.0, `timing delta ${delta.toFixed(3)}ms exceeds 1ms FR-6 bar`);
+```
+
+### Postfix transport_maps fallback
+
+If you don't want to write a custom mailer, the default nodemailer
+path still works even with opendkim: configure Postfix to sign on the
+way out (MTA-level DKIM via `milter_default_action`). You only need a
+custom mailer if you want to bypass localhost submission entirely.
+
+Whichever path you take, ensure the `transport_maps` null-route is in
+place:
+
+```
+# /etc/postfix/transport
+knowless.invalid    discard:silently dropped by knowless null-route
+```
+
+```
+postmap /etc/postfix/transport && systemctl reload postfix
+```
+
 ## Walkthrough: standalone server mode
 
 Run `npx knowless-server`, point Caddy / nginx / Traefik at it for
@@ -761,11 +890,22 @@ once, back it up safely, never expose it.
 
 ### Can I customise the login HTML?
 
-No. The form is hardcoded. Operators wanting branding fork the
+The built-in form is hardcoded. Operators wanting branding fork the
 project. Rationale in [`docs/01-product/PRD.md`](docs/01-product/PRD.md) §16.12: templating
 is a slope ("let me put my logo" → "let me theme the page" →
-"let me embed a JS framework"). The hardcoded form refuses to
-drift.
+"let me embed a JS framework"). The hardcoded form refuses to drift.
+
+However, you can **skip mounting `loginForm`** entirely and serve your
+own form, provided it satisfies the handler contract:
+
+- POST to `loginPath` (default `/login`).
+- Include an `email` field in the `application/x-www-form-urlencoded`
+  body.
+- Do **not** pre-parse the body upstream — knowless reads the request
+  stream itself. A body-parser middleware mounted before `auth.login`
+  will silently steal the data (see gotcha #15 in
+  [`knowless.context.md`](knowless.context.md)).
+- Optional: include a `next` field for the post-callback redirect URL.
 
 ### How do I add 2FA / WebAuthn / TOTP?
 
@@ -774,20 +914,51 @@ stop. WebAuthn after login is a different layer.
 
 ### What about CSRF on POST /login?
 
-The login form is unauthenticated, so traditional CSRF
-mitigations (anti-CSRF tokens) don't apply directly. SameSite=Lax
-on the session cookie covers the post-login risk. CSRF on the
-unauthenticated /login endpoint is on the v0.2 open-questions
-list (SPEC §15 Q-4) — Origin-header validation is the likely
-answer.
+Knowless validates the `Origin` (or `Referer`) header against
+`cookieDomain` on both `POST /login` and `POST /logout`.
+
+- **Failure mode:** 403 with a plain-text body `"Forbidden"`. No
+  redirect, no JSON envelope.
+- **Browser-absent callers** (curl, server-to-server): if neither
+  `Origin` nor `Referer` is present, the check passes — the
+  browser is the CSRF threat model, not API callers. Programmatic
+  callers that do send an `Origin` header must ensure it matches
+  `cookieDomain`.
+- **The check is not disable-able.** Do not add an upstream
+  exception; the Origin check is the CSRF defence (SPEC §7.3 Step
+  0). Do NOT add a separate CSRF token — it would duplicate a
+  defence already in place and complicate custom form integration.
+
+### What are the rate-limit defaults, and what does a rate-limited response look like?
+
+Defaults (all configurable at construction, no live tuning):
+
+| Option | Default | Scope |
+|---|---|---|
+| `maxLoginRequestsPerIpPerHour` | 30 | Per source IP |
+| `maxNewHandlesPerIpPerHour` | 3 | Per source IP (open-registration only) |
+| `maxActiveTokensPerHandle` | 5 | Per handle (unexpired, unused) |
+
+A rate-limited submission returns **202** with the same HTML body as a
+successful send — identical to the sham and real-send responses. This
+is intentional: distinct status or body would let an attacker enumerate
+which IP is being throttled. Aggregate counts are surfaced via the
+`onSuppressionWindow` hook (v0.2.1); individual rate-limit hits are
+not exposed per-event by design (see [`knowless.context.md`](knowless.context.md)
+§ "Why three hooks, not four").
 
 ### Can I run multiple instances behind a load balancer?
 
-Yes — the SQLite store is shared across processes via the file
-system. Concurrent writes use SQLite's `BEGIN IMMEDIATE` for the
-token-issuance transaction (SPEC §4.7). For very high concurrency
-(>1000 logins/sec), implement the store interface against
-Postgres or Redis.
+The default SQLite store is a single-process embedded engine. Knowless
+is designed for single-process deployments. Contention shows up as
+`SQLITE_BUSY` errors in logs; if you see them, your write rate exceeds
+the single-process envelope. Benchmark in your own environment — the
+answer depends on kernel, filesystem, SQLite version, and Node version,
+and v1.x carries no numeric guarantee across upgrades.
+
+For multi-process or multi-node deployments, implement the store
+interface against Postgres, Redis, or any other backend. The interface
+is documented in [`docs/02-design/SPEC.md`](docs/02-design/SPEC.md) §13.
 
 ### How do I see what's in the store?
 

package/knowless.context.md

@@ -30,6 +30,23 @@ This document is the dense reference. For the why, see
 `docs/01-product/PRD.md`. For the wire formats, see
 `docs/02-design/SPEC.md`. For an adopter walkthrough, see `GUIDE.md`.
 
+## What knowless is and is not
+
+Knowless is the substrate for **session-bearing logins**: prove control
+of an email, get a session cookie, do work under that session. The mint
+path is single-use, short-TTL, and exists to bootstrap the cookie — not
+as a generic confirmation primitive.
+
+If you need ad-hoc one-shot confirmation tokens with caller-chosen TTLs
+(event activation that may sit in an inbox over a weekend, email-change
+confirmation, magic-action links that aren't logins), **keep your own
+token system for that step** and use knowless for the session that
+follows. The walk-away release intentionally does not grow toward generic
+token issuance — that's a different library with a different threat
+model.
+
+See § "What's NOT in knowless, and why" for the full lens.
+
 ## Which mode do I need?
 
 | Mode | What it does | When to use |
@@ -175,23 +192,41 @@ const auth = knowless({
 | `config` | -- | object | Merged effective config; safe to read (do not mutate) |
 | `close` | -- | void | Stops sweeper, closes mailer + store. Call on shutdown. |
 
+### Post-callback handle resolution
+
+There is no callback hook fired by knowless on confirmation. The host's
+`nextUrl` route is the seam. Read the handle there:
+
+```js
+// In your post-callback landing route:
+const handle = auth.handleFromRequest(req);
+if (!handle) return res.writeHead(401).end();
+// Now do host-side work keyed by handle.
+```
+
+This is deliberate: the host knows what "successful login means for me";
+knowless does not. Both `auth.login` (form) and `auth.startLogin`
+(programmatic) land here after the link is clicked — the post-callback
+route is the single seam for all login modes.
+
 Re-exports for advanced consumers:
 
 ```js
 import {
-  knowless,         // factory
-  createStore,      // direct store access (admin scripts)
-  createMailer,     // direct mailer access
-  createHandlers,   // bring your own factory wiring
-  composeBody,      // pure: build the mail body
-  validateSubject,  // pure: validate operator-supplied subject
-  validateBodyFooter, // pure: validate operator-supplied footer (AF-8.2)
+  knowless,            // factory
+  dropShamRecipient,   // pure: sham-address predicate for custom mailers
+  createStore,         // direct store access (admin scripts)
+  createMailer,        // direct mailer access
+  createHandlers,      // bring your own factory wiring
+  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)
-  validateFromName, // pure: validate operator-supplied From: display name (AF-27)
-  renderLoginForm,  // pure: HTML5 page rendering
-  normalize,        // pure: email normalization
-  deriveHandle,     // pure: HMAC-SHA256(hex-decoded secret, email)
-  secretBytes,      // pure: coerce hex string → 32-byte HMAC key
+  validateFromName,    // pure: validate operator-supplied From: display name (AF-27)
+  renderLoginForm,     // pure: HTML5 page rendering
+  normalize,           // pure: email normalization
+  deriveHandle,        // pure: HMAC-SHA256(hex-decoded secret, email)
+  secretBytes,         // pure: coerce hex string → 32-byte HMAC key
 } from 'knowless';
 ```
 
@@ -448,6 +483,57 @@ which requires the operator secret.
 [Caddy verifies cookie via /verify, proxies to Uptime Kuma]
 ```
 
+## Custom mailer contract
+
+When you inject `options.mailer`, knowless hands off five obligations.
+The default localhost-SMTP mailer satisfies them all; custom mailers
+must satisfy them deliberately.
+
+**1. Sham-recipient handling.** Knowless addresses sham sends (FR-6
+timing-equivalence sends for missed handles, rate-limit hits,
+exempt-handle short-circuits) to `shamRecipient` (default
+`null@knowless.invalid`). Custom mailers MUST drop these without
+external delivery. Use the exported helper:
+
+```js
+import { dropShamRecipient } from 'knowless';
+
+async function send(envelope, raw) {
+  if (dropShamRecipient(envelope)) return; // no wire send, no error
+  // ...actually deliver raw
+}
+```
+
+Forgetting this lets sham mail bounce, distinguishing miss from hit on
+the wire and reopening the enumeration oracle that FR-6 closes. If you
+configured a custom `shamRecipient`, pass it as the second argument:
+`dropShamRecipient(envelope, cfg.shamRecipient)`.
+
+**2. Timing equivalence (≤1ms).** Real-vs-sham wire-time difference
+must stay within ≤1ms, measured from the start of the mailer's
+`send(envelope, raw)` call to its returned promise's resolution. The
+host knows its transport's jitter; the library cannot equalise around an
+opaque mailer. Mailers spawning a subprocess per send (e.g. `sendmail`
+pipe) MUST self-equalise: pre-warm the subprocess,
+parallel-spawn-then-discard, or measure-and-pad. See FR-6 above for
+why the bar matters.
+
+**3. RFC822 fidelity.** Ship the body knowless composes byte-for-byte.
+No quoted-printable re-encoding, no header rewriting (other than
+envelope routing your transport requires), no soft-break wrapping, no
+charset transcoding. See gotcha #9.
+
+**4. `verify()` semantics.** Optional. If present, knowless calls it
+once at factory construction (synchronously awaited before `knowless()`
+resolves). Throwing aborts startup; resolving with any value is success.
+Knowless does not call `verify()` again on a per-send basis. Hosts
+whose transports can fail-after-warm-up should monitor independently.
+
+**5. `close()` lifecycle.** Optional. Knowless does not call it on
+normal operation. Hosts that wire it up are responsible for calling it
+on their own shutdown path. Knowless guarantees `close()` is safe to
+call multiple times after the auth instance has stopped issuing sends.
+
 ## Architecture
 
 ```
@@ -568,11 +654,13 @@ rate-limits) belongs above the library.
    philosophy. If you can't run Postfix, knowless isn't your
    library.
 
-3. **`shamRecipient` MUST be discarded by your MTA.** Default
-   is `null@knowless.invalid`. If your MTA tries to deliver it,
-   it'll bounce against an `.invalid` TLD that never resolves —
-   noise in your mail logs, wasted DNS lookups. Add the
-   `transport_maps` entry per Postfix snippet above.
+3. **`shamRecipient` MUST be discarded without external delivery.**
+   Default is `null@knowless.invalid`. With the default
+   localhost-SMTP mailer, add the `transport_maps` entry per Postfix
+   snippet above. With a custom injected mailer, call
+   `dropShamRecipient(envelope)` and no-op the send; forgetting this
+   bounces sham mail and reopens the enumeration oracle. See §
+   "Custom mailer contract".
 
 4. **Cookie domain defaults to baseUrl's hostname.** This is the
    *narrow* default; for SSO across subdomains (forward-auth
@@ -603,8 +691,10 @@ rate-limits) belongs above the library.
    default encoding picks base64 or QP for plain ASCII bodies,
    breaking the magic-link URL with QP soft-breaks (the v0.11
    POC finding). We sidestep by composing the message ourselves
-   and using nodemailer only for SMTP. If you swap mailers, your
-   replacement must handle this OR keep emitting raw RFC822.
+   and using nodemailer only for SMTP. If you inject a custom
+   mailer, ship the body byte-for-byte — no QP re-encoding, no
+   soft-break wrapping, no charset transcoding. See § "Custom
+   mailer contract" obligation 3.
 
 10. **No JavaScript in any HTML page.** The login form, the
     confirmation page, error pages — all static HTML5. Works in
@@ -659,10 +749,11 @@ rate-limits) belongs above the library.
     who hold raw 32-byte keys.
 
 18. **`bodyFooter` constraints (AF-8.2).** ASCII only — `·` is NOT
-    ASCII, use `|` or `-`. ≤ 240 chars, ≤ 4 lines, no `http(s)://`
-    URLs (would conflict with the magic-link line). Validated at
-    factory startup; fails fast. Goes after RFC 3676 `"-- "`
-    delimiter so mail clients strip it from quoted replies.
+    ASCII, use `|` or `-`. ≤ 240 chars, ≤ 4 lines (a single trailing
+    newline is allowed and not counted as an extra line), no
+    `http(s)://` URLs (would conflict with the magic-link line).
+    Validated at 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,

package/package.json

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

@@ -5,7 +5,6 @@ import { newSid, signSession, verifySessionSignature } from './session.js';
 import { composeBody, validateSubject, validateBodyOverride } from './mailer.js';
 import { renderLoginForm } from './form.js';
 import {
-  buildTrustedPeers,
   determineSourceIp,
   rateLimitExceeded,
   rateLimitIncrement,
@@ -191,9 +190,7 @@ export function createHandlers({ store, mailer, config, events }) {
       throw new Error('config.baseUrl invalid');
     }
   }
-
-  // Build once at handler creation; supports plain IPs and CIDRs (AF-6.3).
-  const trustedProxies = buildTrustedPeers(cfg.trustedProxies);
+  validateSubject(cfg.subject);
 
   // AF-7.1: emit at most one warning per handler instance about an
   // upstream body parser swallowing the request body. Loud enough to
@@ -253,8 +250,9 @@ export function createHandlers({ store, mailer, config, events }) {
    *
    * @returns {Promise<{handle: string|null, isSham: boolean,
    *                    emailNorm: string, nextValidated: string|null}>}
-   *   handle is null only when the email failed to normalize (programmer
-   *   bug for startLogin; same-shape silent for /login).
+   *   handle is null when the email failed to normalize (programmer bug
+   *   for startLogin) OR when per-IP rate-limit short-circuited before
+   *   handle derivation; same-shape silent for /login.
    */
   async function runSendLink({
     emailRaw,
@@ -469,7 +467,7 @@ export function createHandlers({ store, mailer, config, events }) {
       return;
     }
 
-    const sourceIp = determineSourceIp(req, trustedProxies);
+    const sourceIp = determineSourceIp(req, cfg.trustedProxies);
     const result = await runSendLink({ emailRaw, nextRaw, sourceIp });
     sameResponse(res, result.emailNorm, result.nextValidated ?? '');
   }

package/src/index.js

@@ -279,6 +279,24 @@ export function knowless(options = {}) {
   };
 }
 
+/**
+ * Returns true if `envelope.to` equals the sham null-route recipient
+ * that knowless uses for FR-6 timing-equivalence sends. Custom mailers
+ * MUST call this and no-op the wire send when it returns true. The
+ * library still records the sham token row; this helper only governs
+ * whether to put bytes on the wire.
+ *
+ * Pass the same `shamRecipient` you configured the auth instance with,
+ * or omit to use the default `null@knowless.invalid`.
+ *
+ * @param {object} envelope  Object with a `to` field (the recipient address).
+ * @param {string} [shamRecipient]  Defaults to `'null@knowless.invalid'`.
+ * @returns {boolean}
+ */
+export function dropShamRecipient(envelope, shamRecipient = 'null@knowless.invalid') {
+  return envelope?.to === shamRecipient;
+}
+
 export { createStore } from './store.js';
 export {
   createMailer,

package/src/mailer.js

@@ -88,7 +88,7 @@ export function validateBodyFooter(footer) {
   if (footer.length > 240) throw new Error('bodyFooter must be ≤ 240 chars');
   if (!ASCII_RE.test(footer)) throw new Error('bodyFooter must be ASCII');
   if (footer.includes('\r')) throw new Error('bodyFooter must not contain CR');
-  if (footer.split('\n').length > 4) {
+  if (footer.replace(/\n$/, '').split('\n').length > 4) {
     throw new Error('bodyFooter must be ≤ 4 lines');
   }
   if (/https?:\/\//i.test(footer)) {
@@ -269,6 +269,7 @@ export function validateSubject(subject) {
   }
   if (subject.length > 60) throw new Error('subject longer than 60 chars');
   if (!ASCII_RE.test(subject)) throw new Error('subject contains non-ASCII');
+  if (/[\r\n]/.test(subject)) throw new Error('subject must not contain CR/LF');
   const warnings = [];
   const triggers = ['!!', '$$', 'FREE', 'URGENT', 'WINNER'];
   for (const t of triggers) {