knowless 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -18,11 +18,97 @@ Versioning is [SemVer](https://semver.org/).
 - **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.
+  compile dep.
 - Caddy forward-auth Docker integration test (TASKS.md 6.8).
 - `knowless-server --check-null-route`: CLI probe that submits a
   test message to `shamRecipient` and confirms the local MTA
-  discarded it. Targeted for v0.2.1.
+  discarded it.
+
+## [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.
 
 ## [0.2.0] — 2026-04-28
 

package/GUIDE.md

@@ -295,6 +295,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 +474,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 +630,62 @@ Full options table:
 
 ## FAQ
 
+### 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

package/README.md

@@ -7,7 +7,7 @@ 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.1 | Node.js >= 22.5 | **1 production dep (nodemailer)** | Apache-2.0
 
 ## Why this exists
 

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.1 | 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
@@ -152,6 +163,7 @@ const auth = knowless({
 | `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. |
 | `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. |
 
@@ -173,6 +185,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
 
 ```
@@ -352,6 +449,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),
@@ -482,6 +639,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.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/handlers.js

@@ -163,7 +163,20 @@ function sidHashOf(sid) {
  *   validateNextUrl: (raw:string)=>string|null
  * }}
  */
-export function createHandlers({ store, mailer, config }) {
+export function createHandlers({ store, mailer, config, events }) {
+  // v0.2.1 operator-visibility hooks. All optional; treat missing as
+  // no-ops so the handler hot path is identical for adopters who don't
+  // wire them. The factory passes a fully-populated `events` object;
+  // direct callers of createHandlers (tests / advanced wiring) may omit
+  // it entirely.
+  const noop = () => {};
+  const ev = {
+    shamHit: events?.shamHit ?? noop,
+    rateLimitHit: events?.rateLimitHit ?? noop,
+    onMailerSubmit: events?.onMailerSubmit ?? noop,
+    onTransportFailure: events?.onTransportFailure ?? noop,
+  };
+
   const cfg = { ...DEFAULTS, ...config };
   if (!cfg.secret) throw new Error('config.secret required');
   if (typeof cfg.secret !== 'string' || cfg.secret.length < 64) {
@@ -267,6 +280,7 @@ export function createHandlers({ store, mailer, config }) {
         HOUR_MS,
       )
     ) {
+      ev.rateLimitHit();
       return { handle: null, isSham: false, emailNorm, nextValidated: null };
     }
 
@@ -287,6 +301,11 @@ export function createHandlers({ store, mailer, config }) {
         )
       ) {
         // Cap exceeded — fall through to sham, do NOT short-circuit.
+        // The fall-through becomes a sham-hit too; both counters
+        // increment because they're independent dimensions (operator
+        // can correlate from `rateLimited` jumping in lockstep with
+        // `sham`).
+        ev.rateLimitHit();
         isCreating = false;
       }
     }
@@ -308,9 +327,10 @@ export function createHandlers({ store, mailer, config }) {
     } else {
       isSham = true;
       toAddress = cfg.shamRecipient;
+      ev.shamHit();
     }
 
-    store.insertToken({
+    const evicted = store.insertToken({
       tokenHash: token.hash,
       handle,
       expiresAt,
@@ -318,6 +338,10 @@ export function createHandlers({ store, mailer, config }) {
       isSham,
       maxActive: cfg.maxActiveTokensPerHandle,
     });
+    // Per-handle token cap rotation is the third rate limit. Counted
+    // here in the aggregate `rateLimited` window so operators see
+    // hammering of a single handle without per-event identity leakage.
+    if (evicted > 0) ev.rateLimitHit();
 
     const mailBody = composeBody({
       tokenRaw: token.raw,
@@ -334,10 +358,29 @@ export function createHandlers({ store, mailer, config }) {
     // so timing equivalence is preserved.
     const effectiveSubject = subject ?? cfg.subject;
     try {
-      await mailer.submit({ to: toAddress, subject: effectiveSubject, body: mailBody });
+      const info = await mailer.submit({
+        to: toAddress,
+        subject: effectiveSubject,
+        body: mailBody,
+      });
+      // v0.2.1: per-event hook on real (non-sham) submissions only.
+      // Sham branches go through the windowed aggregate; emitting them
+      // per-event here would let a careless adopter log per-handle
+      // data and reopen the enumeration oracle that sham-work exists
+      // to prevent.
+      if (!isSham) {
+        ev.onMailerSubmit({
+          messageId: info?.messageId ?? null,
+          handle,
+          timestamp: Date.now(),
+        });
+      }
     } catch (err) {
       // Per NFR-10: SMTP failure logged, NEVER leaked to response shape.
       console.error('[knowless] mail submit failed:', err.message);
+      // v0.2.1: per-event hook for SMTP failures. Carries no identity
+      // data, safe per-event. Operator wires this to alerting.
+      ev.onTransportFailure({ error: err, timestamp: Date.now() });
       // AF-6.2: dev-mode fallback. When SMTP is unreachable in local
       // development the operator otherwise has no way to obtain the magic
       // link. Print it to stderr only when explicitly opted in.

package/src/index.js

@@ -9,8 +9,27 @@ const DEFAULT_SWEEP_INTERVAL_MS = 5 * 60 * 1000;
 /** Default rate-limit retention: 24 hours past window-start. */
 const DEFAULT_RATE_LIMIT_RETENTION_MS = 24 * 60 * 60 * 1000;
 
+/** Default suppression-window cadence: 60 seconds. v0.2.1. */
+const DEFAULT_SUPPRESSION_WINDOW_MS = 60 * 1000;
+
 const REQUIRED_FIELDS = ['secret', 'baseUrl', 'from'];
 
+/**
+ * Wrap a user-supplied hook so its errors are caught and swallowed.
+ * Matches the `onSweepError` contract: knowless never crashes because
+ * an operator's observability sink threw.
+ */
+function safeHook(fn, label) {
+  if (typeof fn !== 'function') return () => {};
+  return (arg) => {
+    try {
+      fn(arg);
+    } catch (err) {
+      console.error(`[knowless] ${label} hook threw:`, err?.message ?? err);
+    }
+  };
+}
+
 /**
  * @typedef {Object} KnowlessOptions
  * @property {string} secret           HMAC secret, ≥64 hex chars (32 bytes). FR-47, FR-48.
@@ -37,6 +56,21 @@ const REQUIRED_FIELDS = ['secret', 'baseUrl', 'from'];
  * @property {string[]} [trustedProxies]
  * @property {string} [shamRecipient='null@knowless.invalid']  See SPEC §7.4.
  * @property {number} [sweepIntervalMs]    Sweeper tick; defaults to 5 minutes.
+ * @property {function} [onSweepError]     Optional alerting hook for sweep failures.
+ * @property {function} [onMailerSubmit]   v0.2.1. Per-event hook fired on
+ *   successful mail submission for *real* (non-sham) sends only. Payload:
+ *   `{messageId, handle, timestamp}`. Errors are caught and swallowed.
+ * @property {function} [onTransportFailure]  v0.2.1. Per-event hook fired
+ *   on SMTP errors. Payload: `{error, timestamp}`. Errors swallowed.
+ * @property {function} [onSuppressionWindow] v0.2.1. Heartbeat hook fired
+ *   every `suppressionWindowMs` with aggregate counters. Payload:
+ *   `{sham, rateLimited, windowMs}`. Aggregates the silent-202 branches
+ *   (sham + rate-limit hits) without per-event identity disclosure;
+ *   see knowless.context.md § "v0.2.1 design" for the threat-model
+ *   reasoning. Fires even when both counters are zero (heartbeat).
+ *   Errors swallowed.
+ * @property {number} [suppressionWindowMs=60000]  v0.2.1. Cadence of
+ *   `onSuppressionWindow` emissions. Default 60 seconds.
  * @property {object} [store]              Inject your own store implementation.
  * @property {object} [mailer]             Inject your own mailer.
  * @property {object} [transportOverride]  Pass to nodemailer.createTransport (tests).
@@ -64,7 +98,12 @@ const REQUIRED_FIELDS = ['secret', 'baseUrl', 'from'];
  *   verify: Function,
  *   logout: Function,
  *   loginForm: Function,
+ *   handleFromRequest: (req: any) => string | null,
  *   deleteHandle: (handle: string) => void,
+ *   revokeSessions: (handle: string) => number,
+ *   startLogin: (args: object) => Promise<{handle: string|null, submitted: true}>,
+ *   deriveHandle: (email: string) => string,
+ *   verifyTransport: () => Promise<true>,
  *   config: object,
  *   close: () => void,
  * }}
@@ -102,7 +141,58 @@ export function knowless(options = {}) {
       transportOverride: options.transportOverride,
     });
 
-  const handlers = createHandlers({ store, mailer, config: options });
+  // v0.2.1 operator-visibility hooks. All optional. Validate types up
+  // front so a typo is caught at startup, not on the first hit.
+  for (const k of ['onMailerSubmit', 'onTransportFailure', 'onSuppressionWindow']) {
+    if (options[k] !== undefined && typeof options[k] !== 'function') {
+      throw new Error(`knowless: ${k} must be a function when provided`);
+    }
+  }
+  const suppressionWindowMs =
+    options.suppressionWindowMs ?? DEFAULT_SUPPRESSION_WINDOW_MS;
+  if (
+    typeof suppressionWindowMs !== 'number' ||
+    !Number.isFinite(suppressionWindowMs) ||
+    suppressionWindowMs <= 0
+  ) {
+    throw new Error('knowless: suppressionWindowMs must be a positive number');
+  }
+
+  // Counters reset every windowMs. Aggregating sham + rate-limit
+  // branches behind a windowed counter (rather than per-event hooks)
+  // is the deliberate design — see knowless.context.md § "Why three
+  // hooks, not four" for the threat-model justification.
+  let shamCount = 0;
+  let rateLimitedCount = 0;
+  const onMailerSubmit = safeHook(options.onMailerSubmit, 'onMailerSubmit');
+  const onTransportFailure = safeHook(options.onTransportFailure, 'onTransportFailure');
+  const onSuppressionWindow = safeHook(options.onSuppressionWindow, 'onSuppressionWindow');
+
+  const events = {
+    shamHit: () => { shamCount++; },
+    rateLimitHit: () => { rateLimitedCount++; },
+    onMailerSubmit,
+    onTransportFailure,
+  };
+
+  const handlers = createHandlers({ store, mailer, config: options, events });
+
+  // The window timer fires every windowMs as a heartbeat — emits even
+  // when both counters are zero. Operators rely on the heartbeat as a
+  // liveness signal ("knowless is processing"); a missing emission is
+  // itself diagnostic. Only run the timer when the hook is wired so we
+  // don't spend a setInterval slot on adopters who don't use it.
+  let suppressionTimer = null;
+  if (typeof options.onSuppressionWindow === 'function') {
+    suppressionTimer = setInterval(() => {
+      const sham = shamCount;
+      const rateLimited = rateLimitedCount;
+      shamCount = 0;
+      rateLimitedCount = 0;
+      onSuppressionWindow({ sham, rateLimited, windowMs: suppressionWindowMs });
+    }, suppressionWindowMs);
+    if (typeof suppressionTimer.unref === 'function') suppressionTimer.unref();
+  }
 
   const sweepIntervalMs = options.sweepIntervalMs ?? DEFAULT_SWEEP_INTERVAL_MS;
   const onSweepError = options.onSweepError;
@@ -163,8 +253,15 @@ export function knowless(options = {}) {
     config: handlers._config,
     /** Run a sweep tick on demand. Useful for tests and operator scripts. */
     _sweep: runSweep,
+    /** Probe the configured SMTP transport (v0.2.1). Resolves true on
+     *  success, rejects with the underlying error. Opt-in fail-fast for
+     *  adopters who want to validate SMTP at boot; no auto-on-boot
+     *  variant by design — k8s readiness probes / docker-compose
+     *  ordering would fail boot for the wrong reason. */
+    verifyTransport: () => mailer.verify(),
     close() {
       clearInterval(sweepTimer);
+      if (suppressionTimer !== null) clearInterval(suppressionTimer);
       try {
         mailer.close?.();
       } catch {

package/src/mailer.js

@@ -221,6 +221,27 @@ export function createMailer(cfg) {
         raw,
       });
     },
+    /**
+     * Probe the underlying SMTP transport. Resolves to true on success,
+     * rejects with the underlying error otherwise. Adopters call this
+     * explicitly when they want fail-fast on misconfigured SMTP at boot.
+     * No auto-on-boot variant: deployments where knowless starts before
+     * Postfix (docker-compose ordering, k8s readiness probes) would
+     * fail boot for the wrong reason. v0.2.1.
+     *
+     * Contract: non-rejection means success. The underlying nodemailer
+     * transport may return a truthy value, falsy value, or throw —
+     * non-throwing is treated as success and normalized to `true`.
+     * Tests using `streamTransport` exercise this normalization
+     * (streamTransport's verify() returns false even on healthy probes).
+     */
+    async verify() {
+      if (typeof transport.verify !== 'function') {
+        return true;
+      }
+      await transport.verify();
+      return true;
+    },
     close() {
       if (typeof transport.close === 'function') transport.close();
     },

package/src/store.js

@@ -194,17 +194,23 @@ export function createStore(dbPath = ':memory:') {
   };
 
   // Transactional cap-check + insert per SPEC §4.7.
+  // Returns the number of tokens evicted to make room for the new one
+  // (always 0 when maxActive is 0). Callers use this to count
+  // per-handle-cap rotation events for operator monitoring (v0.2.1).
   const insertTokenAtomic = makeTransaction(db,
     (tokenHash, handle, expiresAt, nextUrl, isSham, maxActive, now) => {
+      let evicted = 0;
       if (maxActive > 0) {
         const { n: count } = stmt.countActiveTokens.get(handle, now);
         let toEvict = count - maxActive + 1;
         while (toEvict > 0) {
           stmt.evictOldestActive.run(handle, now);
           toEvict--;
+          evicted++;
         }
       }
       stmt.insertToken.run(tokenHash, handle, expiresAt, nextUrl, isSham);
+      return evicted;
     },
   );
 
@@ -231,6 +237,13 @@ export function createStore(dbPath = ':memory:') {
     },
 
     // --- Token ---
+    /**
+     * Insert a token, evicting oldest active tokens for the handle when
+     * the per-handle cap (maxActive) would be exceeded.
+     * @returns {number} count of tokens evicted to make room (0 when no
+     *   rotation occurred). Used for operator monitoring (v0.2.1
+     *   `onSuppressionWindow.rateLimited` counter).
+     */
     insertToken(args) {
       const {
         tokenHash,
@@ -243,7 +256,7 @@ export function createStore(dbPath = ':memory:') {
       } = args;
       assertHexHash(tokenHash, 'tokenHash');
       assertHexHash(handle, 'handle');
-      insertTokenAtomic(
+      return insertTokenAtomic(
         tokenHash,
         handle,
         expiresAt,