knowless 0.1.10 → 0.2.1

package/CHANGELOG.md

@@ -5,17 +5,160 @@ All notable changes to `knowless` are recorded here.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 Versioning is [SemVer](https://semver.org/).
 
+## Milestones
+
+- **2026-04-28 — First customer integration shipped.** addypin
+  merged its `try/knowless` branch and runs knowless as its
+  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.
+
 ## [Unreleased]
 
 - **Turnkey Docker image** (`knowless/knowless-server:0.2.x`)
-  bundling Postfix + null-route + the binary so a self-hoster
-  runs `docker compose up` and has a working auth gateway in
-  one step. Material UX win for the PRD §4.2 self-hoster
-  audience. Targeted for v0.2.0.
+  bundling Postfix + null-route + the binary. Now meaningfully
+  smaller and faster to build because v0.2.0 dropped the native
+  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.0.
+  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
+
+**No native compile. One production dep.** Drops `better-sqlite3`
+in favour of `node:sqlite` (Node stdlib). Adopters on long-LTS
+distros (RHEL 8/9, Alma, Rocky, Amazon Linux 2) no longer need a
+C++20 toolchain to `npm install knowless`.
+
+### Breaking
+
+- **Node floor bumped: `>=20.0.0` → `>=22.5.0`.** `node:sqlite`
+  requires Node 22.5+; unflagged stable on Node 24 LTS. Node 20
+  reaches EOL April 2026.
+- **`better-sqlite3` removed from `dependencies`.** Down to one
+  production dep (`nodemailer`). Transitive package count goes
+  from ~40 to ~2. No `prebuild-install`, no `gcc`, no `make`,
+  no Python during install.
+- **Storage internals changed**, public API unchanged. The
+  `createStore()` interface (SPEC §13) is byte-for-byte identical.
+  All 192 tests pass on first run after the swap.
+
+### Migration
+
+- **For knowless library adopters:** ensure your runtime is
+  Node 22.5+. If you pinned `better-sqlite3` somewhere yourself
+  for unrelated reasons, that's now your call. Otherwise:
+  ```sh
+  npm install knowless@0.2.0
+  ```
+  No code changes on your side. Existing SQLite databases
+  continue to work — same schema, same WAL mode, same
+  prepared statements. Sessions and handles persist across
+  the upgrade.
+- **For `knowless-server` operators:** ensure the host runs
+  Node 22.5+. If you ran `dnf install gcc-toolset-13` to get
+  v0.1.x to compile, you can remove it after the upgrade —
+  v0.2.0 doesn't need it. The systemd unit and env-var config
+  are unchanged.
+- **You may see one `ExperimentalWarning` from `node:sqlite`
+  at first import** on Node 22.x. Suppress with `--no-warnings`
+  or run on Node 24 LTS where the API is fully stable.
+
+### Internal
+
+- New `makeTransaction(db, fn)` adapter in `src/store.js`
+  replaces `better-sqlite3`'s `db.transaction()` wrapper. Uses
+  `BEGIN IMMEDIATE` / `COMMIT` / `ROLLBACK` directly — same
+  serialisation guarantee for the transactional cap-check
+  (SPEC §4.7) and account-deletion paths (FR-37a).
+- Closes AF-18 (the addypin RHEL 8 deployment trap).
 
 ## [0.1.10] — 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
@@ -550,11 +625,67 @@ Full options table:
 | `shamRecipient` | no | `null@knowless.invalid` | Where sham mail goes (your MTA must discard it). |
 | `sweepIntervalMs` | no | `300000` | Sweeper tick (5 min default). |
 | `failureRedirect` | no | (= `loginPath`) | Where /auth/callback failures redirect. **Mode-A adopters:** if you don't mount `loginForm`, set this to a route you actually serve (e.g. `/`) — otherwise expired/replayed magic-link clicks 302 to a 404. |
-| `store` | no | (built-in better-sqlite3) | Inject your own store implementation. |
+| `store` | no | (built-in `node:sqlite`) | Inject your own store implementation. |
 | `mailer` | no | (built-in nodemailer) | Inject your own mailer. |
 
 ## 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
@@ -659,15 +790,19 @@ mail account is later compromised.
 
 ## Constraints / install footprint
 
-- **Two direct dependencies.** `nodemailer` (SMTP submission) and
-  `better-sqlite3` (storage). Both audited and pinned at major
-  versions in `package.json`.
-- **~40 transitive packages** in a typical install. The bulk are
-  `nodemailer`'s ecosystem deps (mostly idle in our usage) and
-  `better-sqlite3`'s build-time prebuild fetcher. You may see one
-  deprecation warning during install for `prebuild-install` —
-  build-chain noise, not runtime code.
-- **Node ≥ 20.** Uses `node:util parseArgs`, `node:net BlockList`
-  for CIDR support, and `--env-file=` for the standalone server.
-- **No optional deps, no postinstall scripts** beyond `better-
-  sqlite3`'s native binding fetch.
+- **One direct dependency.** `nodemailer` (SMTP submission). Storage
+  is `node:sqlite` (Node stdlib, no native compile, no toolchain
+  required on the host).
+- **~2 transitive packages** in a typical install (down from ~40 in
+  v0.1.x). No `prebuild-install`, no `gcc`, no `make`, no Python.
+  `npm ci` works on stock RHEL 8 / Alma / Rocky / Amazon Linux 2
+  with no extra packages. Self-hosters: `npm install knowless` is
+  done.
+- **Node ≥ 22.5.** `node:sqlite` requires this floor (introduced
+  22.5, unflagged in 22.13+, fully stable in 24 LTS). Drops Node
+  20 — about to EOL anyway.
+- **No optional deps, no postinstall scripts.**
+
+> `node:sqlite` may print one `ExperimentalWarning` to stderr on
+> first import. Suppress with `--no-warnings` or by running on
+> Node 24 LTS where the API is fully stable.

package/OPS.md

@@ -548,13 +548,14 @@ CLI invoked by Postfix's `pipe` transport, or a web server plus a
 cron worker handling 48h reminders. Each process instantiates
 `knowless({...})` against the same `dbPath`.
 
-**Why this works.** `better-sqlite3` opens the database in WAL mode
-by default (knowless explicitly sets `journal_mode=WAL` at startup).
-WAL allows multiple readers and one writer concurrently, with the
-OS-level locking semantics needed for cross-process safety. Every
-write goes through a prepared statement under a SQLite transaction,
-so two processes inserting tokens or sessions at the same time can't
-corrupt the table.
+**Why this works.** knowless opens the database in WAL mode at
+startup (`PRAGMA journal_mode = WAL`). WAL allows multiple readers
+and one writer concurrently, with the OS-level locking semantics
+needed for cross-process safety. Every write goes through a prepared
+statement under a SQLite transaction, so two processes inserting
+tokens or sessions at the same time can't corrupt the table. Since
+v0.2.0 the storage backend is `node:sqlite` (Node stdlib) — no
+native compile, no `gcc` toolchain on the host.
 
 **What to know about each subsystem under multi-process:**