knowless 0.1.10 → 0.2.1

package/README.md

@@ -7,35 +7,7 @@ that don't need to email their users for anything but the sign-in link.
 npm install knowless
 ```
 
-> v0.1.10 | Node.js >= 20 | 2 deps (nodemailer, better-sqlite3) | Apache-2.0
-
-## What this is
-
-Magic-link auth + session cookie + nothing else. Six lines of
-operator code:
-
-```js
-import express from 'express';
-import { knowless } from 'knowless';
-
-const app = express();
-const auth = knowless({
-  secret: process.env.KNOWLESS_SECRET,   // 64-char hex (32 bytes)
-  baseUrl: 'https://app.example.com',
-  from: 'auth@app.example.com',
-});
-
-app.use(express.urlencoded({ extended: false }));
-app.get('/login',          auth.loginForm);
-app.post('/login',         auth.login);
-app.get('/auth/callback',  auth.callback);
-app.get('/verify',         auth.verify);
-app.post('/logout',        auth.logout);
-```
-
-That's the entire integration. Users hit `/login`, type their email,
-click the magic link in their inbox, and are logged in for 30 days
-via a signed session cookie.
+> v0.2.1 | Node.js >= 22.5 | **1 production dep (nodemailer)** | Apache-2.0
 
 ## Why this exists
 
@@ -44,114 +16,194 @@ maximum identity collection: full email stored in plaintext, profile
 fields, recovery email, federation. Even nominally privacy-focused
 options store enough that a breach is materially harmful.
 
-`knowless` is the simpler answer that always worked: magic link in,
-session cookie out, nothing else stored. The library refuses, by API
-shape, to send anything but the sign-in link or store anything
-identifying.
+knowless is the simpler answer that always worked: **magic link in,
+session cookie out, nothing else stored.** Email is HMAC-hashed at the
+boundary and discarded. The library refuses, by API shape, to send
+anything but the sign-in link or store anything identifying.
 
 The thesis: most services have ten layers of auth tooling where they
 need two.
 
-## What it commits to
-
-- **Stores no plaintext email, ever.** Email is salted-hashed on the
-  way in (`HMAC-SHA256(secret, normalized_email)`) and discarded.
-- **Sends no email except the magic link.** Not a welcome message,
-  not a digest, not a notification. By API shape — there is no
-  `sendNotification()` method to be tempted by.
-- **Self-hostable end to end.** No vendor relationships. No
-  telemetry. No phone-home of any kind.
-- **Walks away at v1.0.0.** Maintenance mode after that.
-
-## What it deliberately doesn't do
-
-A short list (full table in [`docs/01-product/PRD.md`](docs/01-product/PRD.md) §14):
-
-- No remote SMTP / mail vendor support — localhost Postfix is the
-  only transport
-- No HTML email, no tracking pixels, no click-rewriting
-- No OAuth / OIDC / SAML — different audience
-- No 2FA / WebAuthn / TOTP — compose with a separate library if
-  needed
-- No admin UI for handles or sessions — `sqlite3 knowless.db` is
-  the admin UI
-- No customisable login form templates — the page is hardcoded;
-  fork or live with it
-- No telemetry, analytics, or error reporting
+## Two modes — pick per action
+
+Same library, two flows. They coexist in one app; choose per-endpoint
+based on whether forcing a login *before* the action would harm UX.
+
+### Mode B — register-first (the form)
+
+User must log in before performing the action. Standard "sign in to
+continue" flow.
+
+- User hits `/login`, types email
+- Magic link arrives, click → session cookie
+- Your protected endpoints call `auth.handleFromRequest(req)` to gate
+  access
+
+Use for: account settings, paid features, anything that requires an
+identified user at the moment of the action.
+
+### Mode A — use-first, claim-later (programmatic)
+
+User performs the action *without* being logged in. You capture their
+email along with the action, fire a magic link via
+`auth.startLogin({email, nextUrl, ...})`, and clicking it opens a
+session and "promotes" the deferred resource.
+
+Use for: drop-a-pin / submit-a-paste / share-a-link / disposable
+resources / anywhere logging in first kills the UX.
+
+The same 12-step sham-work flow runs underneath either mode, so
+unknown emails, rate-limit hits, and real sends look identical to an
+external observer (the FR-6 timing-equivalence guarantee). Pick per
+action; the two coexist.
+
+Worked code for both modes is in [`GUIDE.md`](GUIDE.md). The dense
+API reference is [`knowless.context.md`](knowless.context.md).
+
+## What's opinionated (locked by design)
+
+These are deliberate trade-offs, documented as `NO-GO` in
+[`docs/01-product/PRD.md`](docs/01-product/PRD.md) §14.
+The library refuses, by API shape, to grow into them.
+
+- **Localhost SMTP only.** No Mailgun/Postmark/SES/Resend. The
+  operator runs Postfix (or another MTA) on the same host, in
+  outbound-only mode.
+- **One mail purpose: the sign-in link.** No welcome message, no
+  digest, no notification. There is no `sendNotification()` to be
+  tempted by.
+- **Plain-text 7-bit email.** No HTML, no tracking pixels, no
+  click-rewriting, no read-receipts.
+- **No OAuth / OIDC / SAML.** Different audience.
+- **No 2FA / WebAuthn / TOTP / passkeys.** Compose with a separate
+  library if you need them.
+- **No admin UI.** `sqlite3 knowless.db` is the admin UI.
+- **Hardcoded login form.** No template overrides; fork or live
+  with it.
+- **No telemetry, analytics, or error reporting.** Self-hostable end
+  to end. No phone-home of any kind.
+- **Walks away at v1.0.0.** Maintenance mode after that — only
+  security fixes.
+
+## What's swappable
+
+Everything that *isn't* identity-shape or threat-model essential is
+config or injection.
+
+| Knob | Default | Common reasons to change |
+|---|---|---|
+| `dbPath` | `./knowless.db` | Move to `/var/lib/knowless/...` for systemd; share across processes |
+| `smtpHost`, `smtpPort` | `localhost`, `25` | Point at MailHog (`localhost:1025`) for dev mail inspection |
+| `cookieDomain` | hostname of `baseUrl` | Set to your eTLD+1 for SSO across subdomains |
+| `cookieSecure` | `true` | `false` only for `http://localhost` dev (logs a warning) |
+| `tokenTtlSeconds`, `sessionTtlSeconds` | `900`, `2592000` | Tighten for high-security uses; loosen at your peril |
+| `openRegistration` | `false` | `true` to let any new email auto-register on first link |
+| `subject` | `Sign in` | Match your brand; per-call override on `startLogin` (`subjectOverride`) |
+| `bodyFooter` | none | Append a constant brand/legal/feedback line to every magic-link mail |
+| `confirmationMessage` | (default copy) | Replace the post-submit "we'll email you" text |
+| `maxLoginRequestsPerIpPerHour`, `maxNewHandlesPerIpPerHour` | `30`, `3` | Raise for genuinely shared NATs; `0` to disable in dev |
+| `trustedProxies` | `[127.0.0.1, ::1]` | Plain IPs **and** CIDRs (`10.0.0.0/8`) for k8s/docker/cgnat |
+| `bypassRateLimit` (per-call) | `false` | Trusted CLI/cron callers via `auth.startLogin` |
+| `store` | built-in `node:sqlite` | Inject your own store (Postgres, etc.) |
+| `mailer` | built-in nodemailer | Inject your own mailer |
+| `transportOverride` | none | Pass a custom `nodemailer.createTransport` |
+| `onSweepError(err)` | none | Operator alerting hook for sweeper failures |
+| `devLogMagicLinks` | `false` | `true` in dev: print magic-link URLs (or silent-miss hints) to stderr when SMTP fails |
+
+Full table with defaults, types, and validation rules:
+[`GUIDE.md`](GUIDE.md) → "Configuration reference."
 
 ## Two deployment shapes (one codebase)
 
 | Mode | Status | When |
 |---|---|---|
 | **Library mode** | shipped (v0.1.0) | Mount handlers in your existing Node app |
-| **Standalone server** (forward-auth) | shipped (v0.1.3) | Self-hosters gating Uptime Kuma / AdGuard / Pi-hole / Sonarr / etc. via Caddy or nginx |
+| **Standalone server** (forward-auth) | shipped (v0.1.3) | Self-hosters gating Uptime Kuma / AdGuard / Pi-hole / Sonarr / etc. behind Caddy / nginx / Traefik |
+
+Library mode is the six-line example in [`GUIDE.md`](GUIDE.md).
+Standalone server is `npx knowless-server` — full Postfix + DNS +
+reverse-proxy walkthrough in [`OPS.md`](OPS.md).
+
+## First customer: addypin
+
+[`addypin`](https://github.com/hamr0/addypin) — location-sharing
+service in the same hermit-architecture lineage — adopted knowless
+as its auth+mail layer. The integration delta:
+
+- **~1,150 lines of bespoke auth/mail code removed** (custom mailer,
+  inbound CLI, login plumbing, pin-confirmation state machine, email
+  fingerprinting helpers, the matching test files)
+- **~35 lines of knowless wiring added**
+- **~33× reduction** on the auth/mail surface
+- **One production dep** (`nodemailer` only; v0.2.0 dropped
+  `better-sqlite3` for `node:sqlite`, the stdlib SQLite driver — no
+  C++ toolchain, no native compile, ~40 transitive packages → 2)
 
-Library mode is the six-line example above. Standalone server is
-`npx knowless-server` — see [`OPS.md`](OPS.md) for the full Postfix +
-DNS + reverse-proxy walkthrough.
+The integration round produced the audit findings AF-7 through AF-17
+that drove v0.1.5 → v0.1.10. See [`docs/01-product/PRD.md`](docs/01-product/PRD.md)
+§17 for the full backlog.
 
 ## Operator commitments
 
 By choosing knowless, you commit to:
 
-- Running your own server with **Postfix installed and configured**
-  for outbound-only mail (or another localhost MTA)
-- Setting up **SPF, DKIM, and PTR records** for your sending domain
-  (one-time DNS setup)
+- Running your own server with **Postfix** (or another MTA) installed
+  for outbound-only mail
+- Setting up **SPF, DKIM, and PTR** for your sending domain
 - Verifying **outbound port 25** is open (some clouds block it)
-- A **null-route entry** in your MTA's `transport_maps` for the
-  configured `shamRecipient` (default `null@knowless.invalid`) — so
-  silent-miss sham mail is dropped, not delivered to NXDOMAIN
-- Accepting that this is the **only email** your service ever sends
+- A **null-route entry** for the configured `shamRecipient` so
+  silent-miss sham mail is dropped, not bounced
+- Accepting that the magic link is the **only email** your service
+  ever sends
 
-These are documented in [`OPS.md`](OPS.md): Postfix install,
-null-route, SPF/DKIM/PTR, systemd unit, Caddy / nginx / Traefik
-forward-auth examples, Tailscale pattern, reverse-proxy rate limiting,
-and fail2ban / Turnstile references.
+Step-by-step in [`OPS.md`](OPS.md): Postfix install, null-route,
+SPF/DKIM/PTR/DMARC, systemd unit, Caddy / nginx / Traefik
+forward-auth examples, Tailscale pattern, reverse-proxy rate
+limiting, fail2ban / Turnstile, multi-process deployments, MailHog
+dev workflow, backups.
 
 ## Documentation
 
-- [`README.md`](README.md) (this file) — project pitch, six-line example
-- [`GUIDE.md`](GUIDE.md) — adopter walkthrough: who it's for, who it
-  isn't, how to integrate, configuration reference, FAQ
-- [`OPS.md`](OPS.md) — operator setup: Postfix, null-route, DNS,
-  systemd, reverse-proxy forward-auth examples
-- [`knowless.context.md`](knowless.context.md) — dense AI-agent
-  integration guide (tables, gotchas, public API at a glance)
+- [**`GUIDE.md`**](GUIDE.md) — start here. Adopter walkthrough,
+  install, six-line example, both modes worked end-to-end,
+  configuration reference, FAQ, troubleshooting.
+- [**`knowless.context.md`**](knowless.context.md) — dense reference
+  for AI agents and humans-in-a-hurry. Public API table, all options,
+  18 gotchas, lifecycles, the sham-work pattern, threat model
+  summary.
+- [`OPS.md`](OPS.md) — operator setup, fresh VPS to working forward-auth.
+- [`CHANGELOG.md`](CHANGELOG.md) — version history.
 - [`docs/01-product/PRD.md`](docs/01-product/PRD.md) — product
-  requirements: scope, threat model, decisions log, NO-GO table
+  requirements, threat model, decisions log, NO-GO table, audit
+  findings backlog.
 - [`docs/02-design/SPEC.md`](docs/02-design/SPEC.md) — wire formats,
-  byte layouts, algorithms (reimplementation-grade)
-- [`docs/03-tasks/TASKS.md`](docs/03-tasks/TASKS.md) — implementation
-  task list and phase plan
-- [`CHANGELOG.md`](CHANGELOG.md) — version history
+  algorithms, byte layouts (reimplementation-grade).
 
-## Threat model — what this defends and what it doesn't
+## Threat model (one-paragraph)
 
-Honest version (full detail in [`docs/01-product/PRD.md`](docs/01-product/PRD.md) §12):
+Honest version (full detail in [PRD §12](docs/01-product/PRD.md)):
 
-**Defends well:** database-only leaks, plaintext email exfiltration,
-password reuse / credential stuffing, silent email enumeration
-(timing-equivalent within 1ms locally), email-bombing a target,
-naive bot traffic, account-creation spam, replay attacks, open
-redirects.
+**Defends well:** DB-only leaks, plaintext-email exfiltration, password
+reuse / credential stuffing, silent email enumeration (timing-
+equivalent within 1ms locally), email-bombing a target, naive bot
+traffic, account-creation spam, replay attacks, open redirects, CSRF
+on `POST /login` / `POST /logout` (Origin/Referer whitelist).
 
 **Defends partially:** HMAC-secret-only leak (allows targeted
-existence-checks but not session forgery), phishing (no password
-to type into a fake site, but a phished mailbox can still receive
-links).
+existence checks but not session forgery), phishing (no password to
+type into a fake site, but a phished mailbox still receives links).
 
 **Does NOT defend against:** sophisticated bots that bypass the
 honeypot, distributed floods from many IPs, full server compromise,
 compromised email accounts, social engineering, insider threat at
 the operator. Layer-2 defences (Cloudflare, fail2ban, reverse-proxy
-rate-limits) belong above the library; OPS.md will document the
-common patterns.
+rate-limits) belong above the library; [`OPS.md`](OPS.md) §9–§10
+covers the patterns.
 
 ## Sibling projects
 
-- [`addypin`](https://github.com/hamr0/addypin) — location sharing
-  with the same hermit philosophy
+- [`addypin`](https://github.com/hamr0/addypin) — location sharing,
+  first knowless adopter
 - [`gitdone`](https://github.com/hamr0/gitdone) — verified email
   actions via DKIM/SPF inbound
 
@@ -160,8 +212,8 @@ common patterns.
 Issues and PRs welcome at <https://github.com/hamr0/knowless>.
 
 Per the v1.0.0 walk-away framing in PRD §6.3: feature requests after
-v1.0.0 ships will be deflected to the §14 NO-GO table or to sibling
-projects. The library being "done" is a feature.
+v1.0.0 ships will be deflected to the [§14 NO-GO table](docs/01-product/PRD.md)
+or to sibling projects. The library being "done" is a feature.
 
 ## License
 

package/knowless.context.md

@@ -1,7 +1,7 @@
 # knowless -- Integration Guide
 
 > For AI assistants and developers wiring knowless into a project.
-> v0.1.10 | Node.js >= 20 | 2 deps (nodemailer, better-sqlite3) | 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
 
 ```
@@ -333,7 +430,7 @@ URL/email -> handlers.js (login: 12-step sham-work flow per SPEC §7.3)
           -> handle.js   (normalize ASCII-only, HMAC-SHA256)
           -> abuse.js    (per-IP rate limit, per-handle token cap, honeypot)
           -> token.js    (32 random bytes, base64url; SHA-256 at rest)
-          -> store.js    (better-sqlite3, transactional, prepared statements)
+          -> store.js    (node:sqlite, transactional, prepared statements)
           -> mailer.js   (raw RFC822 7bit; nodemailer for SMTP submission only)
           -> session.js  (HMAC-signed cookie with "sess\\0" domain tag)
           -> form.js     (hardcoded HTML5; no JS, no external resources)
@@ -344,7 +441,7 @@ URL/email -> handlers.js (login: 12-step sham-work flow per SPEC §7.3)
 |---|---|---|
 | `src/index.js` | ~140 | Public factory, sweeper, re-exports |
 | `src/handlers.js` | ~310 | login (sham), callback, verify, logout, loginForm, validateNextUrl |
-| `src/store.js` | ~210 | better-sqlite3 store; SPEC §13 interface |
+| `src/store.js` | ~240 | node:sqlite store + transaction adapter; SPEC §13 interface |
 | `src/mailer.js` | ~120 | RFC822 raw composition + nodemailer SMTP submission |
 | `src/abuse.js` | ~95 | Source-IP determination, rate limits |
 | `src/handle.js` | ~50 | Email normalization, handle derivation |
@@ -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),
@@ -433,7 +590,7 @@ rate-limits) belongs above the library.
     sweeper and closes the SQLite handle. Without it, your
     process won't exit cleanly. The sweeper timer is `unref()`d
     so it won't *prevent* exit, but the SQLite handle held by
-    `better-sqlite3` will leave a finalizer warning.
+    `node:sqlite` will leave a finalizer warning.
 
 12. **CSRF defense is the Origin/Referer whitelist, not a token.**
     Modern browsers always emit `Origin` on cross-origin POSTs;
@@ -482,13 +639,23 @@ 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
 - **Plain ES modules** -- no TypeScript source, no build step;
   ships JSDoc + (eventual) `.d.ts`
-- **Two production deps** -- `nodemailer` (SMTP submission) and
-  `better-sqlite3` (storage). No third dep without revisiting
+- **One production dep** -- `nodemailer` (SMTP submission). Storage
+  uses `node:sqlite` (stdlib, no native compile). No second runtime
+  dep without revisiting
   AGENT_RULES External Dependency Checklist.
 - **Localhost MTA only** -- no remote SMTP, no vendor SDKs.
   Operators run their own Postfix / OpenSMTPD / Exim.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "knowless",
-  "version": "0.1.10",
+  "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",
@@ -23,14 +23,13 @@
     "knowless.context.md"
   ],
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.5.0"
   },
   "scripts": {
     "test": "node --test 'test/**/*.test.js'",
     "lint": "find src bin -type f \\( -name '*.js' -o -name 'knowless-server' \\) -exec node --check {} \\;"
   },
   "dependencies": {
-    "better-sqlite3": "^11.0.0",
     "nodemailer": "^8.0.7"
   },
   "license": "Apache-2.0",