knowless 1.0.1 → 1.1.1

package/CHANGELOG.md

@@ -12,6 +12,12 @@ Versioning is [SemVer](https://semver.org/).
   auth+mail layer. ~1,150 LOC of bespoke auth/mail code removed,
   ~35 LOC of knowless wiring added (~33× reduction). Drove audit
   findings AF-7 → AF-17 across v0.1.5–v0.1.10.
+- **2026-05-02 — Three adopters in production.** plato (Mode B,
+  forum) and gitdone (Mode A, multi-party email workflows) joined
+  addypin (Mode A, location sharing). gitdone's pre-merge review
+  surfaced the "wrong-shape integration" failure mode (parallel
+  tokens table + manual session minting alongside knowless instead
+  of `auth.startLogin`). Patched docs in v1.1.1; no API change.
 
 ## [Unreleased]
 
@@ -22,6 +28,70 @@ 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.1] — 2026-05-02
+
+Documentation-only release. Adds the wrong-shape-integration
+anti-pattern callout that gitdone's pre-merge review surfaced, and
+records plato + gitdone as the second and third production adopters.
+No code changes.
+
+### Documented
+
+- `README.md` — replaced "Sibling projects" with an "Adopters"
+  section explicitly listing addypin (Mode A), plato (Mode B), and
+  gitdone (Mode A) with a pointer that addypin and gitdone are the
+  Mode A worked references.
+- `GUIDE.md` § "Two adoption modes" — added an anti-pattern callout
+  at the top: if you're considering writing pending rows to a
+  custom tokens table or minting your own confirmation links, that's
+  Mode A and `auth.startLogin({ subjectOverride, bodyOverride })`
+  already does it. Includes a side-by-side wrong-shape vs Mode A
+  sketch. Surfaced by gitdone's pre-merge review where a parallel
+  activation system was built before the existing Mode A flow was
+  noticed.
+- `GUIDE.md` Mode A/B sub-headings — appended the API entrypoint
+  (`auth.startLogin` for Mode A, `auth.login` for Mode B) so the
+  use-case leads and `startLogin` doesn't read as "login button
+  click."
+
+## [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.

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
@@ -265,7 +286,31 @@ 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 — "sign in, then do the thing" (register-first, the default).**
+> ⚠ **Stop before you build a parallel activation system.** If
+> you're considering writing pending rows to a custom tokens table,
+> minting your own confirmation links, or calling into the sessions
+> table directly to mark an account "activated by email" — that is
+> Mode A, and it's already in this library. Use
+> `auth.startLogin({ email, subjectOverride, bodyOverride })` and
+> promote your pending resource in the callback handler. The
+> wrong-shape integration is what every adopter has tried first; the
+> right shape is the worked example below.
+
+The wrong shape vs Mode A, side by side:
+
+```
+WRONG SHAPE                         MODE A (use auth.startLogin)
+─────────────────────────────       ─────────────────────────────
+your_tokens table                   (none — knowless owns the token)
+your custom email composer          subjectOverride + bodyOverride
+your /confirm/:token handler        auth.callback (already mounted)
+manual session insert               handled by callback
+your duplicate rate-limit code      knowless rate-limit applies
+                                    sham-work + timing equivalence
+                                    preserved automatically
+```
+
+**Mode B — "sign in, then do the thing" (register-first, the default, `auth.login`).**
 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
@@ -280,7 +325,7 @@ app.post('/api/comments', (req, res) => {
 });
 ```
 
-**Mode A — "do the thing, confirm by email" (use-first, claim-later).**
+**Mode A — "do the thing, confirm by email" (use-first, claim-later, `auth.startLogin`).**
 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
@@ -574,6 +619,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 +914,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 +938,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/README.md

@@ -148,12 +148,21 @@ rate-limits) belong above the library — patterns in
 Full detail in [`knowless.context.md`](knowless.context.md) §
 "Threat model summary."
 
-## Sibling projects
+## Adopters
 
-- [`addypin`](https://github.com/hamr0/addypin) — location sharing,
-  first knowless adopter
-- [`gitdone`](https://github.com/hamr0/gitdone) — verified email
-  actions via DKIM/SPF inbound
+Production users of knowless, in adoption order:
+
+- [`addypin`](https://github.com/hamr0/addypin) — pin-drop location
+  sharing. First knowless adopter; Mode A (drop-pin-then-confirm).
+- [`plato`](https://github.com/hamr0/plato) — forum (Reddit-shaped,
+  one fingerprint per site). Mode B (sign-in-then-do).
+- [`gitdone`](https://github.com/hamr0/gitdone) — multi-party email
+  workflows verified via DKIM/SPF inbound. Mode A
+  (start-workflow-then-confirm).
+
+If you're picking knowless up: the addypin and gitdone callsites are
+both Mode A and good worked references for the use-first / claim-later
+shape.
 
 ## License
 

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

package/package.json

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