knowless 0.1.9 → 0.2.0

package/CHANGELOG.md

@@ -5,17 +5,100 @@ 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. Targeted for v0.2.1.
 - 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. Targeted for v0.2.1.
+
+## [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
+
+addypin manual smoke continued. Two DX docs improvements; no code
+changes.
+
+### Documentation
+
+- **GUIDE: "Local development setup" section (AF-16).** Covers the
+  five flags that turn knowless from "production-tuned, defensive"
+  to "developer-friendly, get-out-of-my-way" — `cookieSecure: false`,
+  `devLogMagicLinks: true`, `maxLoginRequestsPerIpPerHour: 0`,
+  `maxNewHandlesPerIpPerHour: 0`, `openRegistration: true`. Each
+  flag explained with what it solves and a sharp warning about
+  shipping it. Considered auto-disabling rate limits whenever
+  `devLogMagicLinks: true` to save typing, but rejected the
+  coupling — operators turning on `devLogMagicLinks` briefly to
+  debug a single email in prod should NOT have rate limits silently
+  dropped at the same time.
+- **GUIDE: silent-miss debug line is now promoted as a feature
+  (AF-17).** The `[knowless dev:<from>] silent-miss: handle for
+  "X" does not exist (openRegistration=false)` stderr hint
+  introduced in AF-7.2 was buried in the CHANGELOG; it now leads
+  the dev-setup section. First-time closed-reg friction was costing
+  every adopter the same ~30 min; the hint cuts that to seconds
+  but only if you know it exists.
 
 ## [0.1.9] — 2026-04-28
 

package/GUIDE.md

@@ -398,6 +398,59 @@ reverse proxy gates upstreams via `/verify` returning 200/401 +
 `handleFromRequest` — same answer, no sub-request round-trip, no
 header parsing.
 
+### Local development setup
+
+Production defaults are tuned to bite bots, not to be friendly to a
+developer hammering the same address from `127.0.0.1` for the
+hundredth time. Use a dedicated dev config:
+
+```js
+const auth = knowless({
+  // ...required fields
+  cookieSecure: false,             // localhost-only HTTP origins (AF-4.4)
+  devLogMagicLinks: true,          // print magic links to stderr when SMTP fails (AF-6.2)
+  maxLoginRequestsPerIpPerHour: 0, // disable per-IP login cap
+  maxNewHandlesPerIpPerHour: 0,    // disable per-IP create cap
+  openRegistration: true,          // skip the pre-seeding step in dev
+});
+```
+
+Why each flag matters in dev:
+
+- **`cookieSecure: false`** — without it, `http://localhost` browsers
+  reject the session cookie silently. The library logs a stderr
+  warning at startup so you can't accidentally ship this to prod.
+- **`devLogMagicLinks: true`** — when SMTP is unreachable (no local
+  Postfix yet), magic-link URLs print to stderr tagged
+  `[knowless dev:<from>] magic link: ...`. Click straight from the
+  terminal. **Bonus diagnostic** (AF-7.2): on a sham/silent-miss
+  path, you get `[knowless dev:<from>] silent-miss: handle for
+  "X" does not exist (openRegistration=false)` instead — surfaces
+  the closed-reg gotcha that costs everyone the same 30 minutes
+  the first time.
+- **`maxLoginRequestsPerIpPerHour: 0` and `maxNewHandlesPerIpPerHour:
+  0`** — disable per-IP rate caps. The defaults (30 / 3 per hour)
+  are sane for prod but shoot you in the foot during repeated test
+  runs. The counters **persist in the SQLite file** across process
+  restarts, so even rebooting the dev server doesn't clear them —
+  you'd have to delete the DB or wait an hour. Setting both to 0
+  in dev avoids the surprise.
+- **`openRegistration: true`** — saves you from manually pre-seeding
+  every test email via `auth.deriveHandle` + your own store insert.
+
+> **Don't ship this config.** Each of these flags weakens a specific
+> defense. They are coupled to your environment, not to each other —
+> intentionally. (We considered auto-disabling rate limits whenever
+> `devLogMagicLinks` is true, but rejected: an operator turning on
+> `devLogMagicLinks` to debug a single email in production should
+> NOT have rate limits silently dropped at the same time.)
+
+For end-to-end mail rendering checks (verify the `bodyFooter`,
+inspect the magic-link line for QP soft-breaks, confirm the
+right `subjectOverride` shipped), point dev knowless at MailHog
+on `localhost:1025`. Setup walkthrough lives in
+[`OPS.md` §11b](OPS.md).
+
 ### Step 7: GDPR right-to-erasure
 
 The store interface exposes `deleteHandle(handle)` — atomic delete
@@ -497,7 +550,7 @@ 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
@@ -606,15 +659,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:**
 

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.9 | 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.0 | 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.9 | Node.js >= 20 | 2 deps (nodemailer, better-sqlite3) | Apache-2.0
+> v0.2.0 | Node.js >= 22.5 | 1 dep (nodemailer) | Apache-2.0
 
 ## What this is
 
@@ -333,7 +333,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 +344,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 |
@@ -433,7 +433,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;
@@ -487,8 +487,9 @@ rate-limits) belongs above the library.
 - **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.9",
+  "version": "0.2.0",
   "description": "Small, opinionated, full-stack passwordless auth for Node.js services that don't need to email their users for anything but the sign-in link.",
   "type": "module",
   "main": "./src/index.js",
@@ -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",

package/src/store.js

@@ -1,4 +1,32 @@
-import Database from 'better-sqlite3';
+import { DatabaseSync } from 'node:sqlite';
+
+/**
+ * Wrap a function in a SQLite transaction. Mirrors better-sqlite3's
+ * `db.transaction(fn)` shape: returns a function that opens
+ * BEGIN IMMEDIATE, runs `fn`, COMMITs on success, ROLLBACKs on
+ * throw, and propagates the original error.
+ *
+ * BEGIN IMMEDIATE rather than BEGIN DEFERRED — knowless's
+ * transactional cap-check (SPEC §4.7) needs a write lock from the
+ * start to serialise concurrent issuance attempts.
+ *
+ * @param {DatabaseSync} db
+ * @param {Function} fn
+ */
+function makeTransaction(db, fn) {
+  return (...args) => {
+    db.exec('BEGIN IMMEDIATE');
+    let result;
+    try {
+      result = fn(...args);
+    } catch (err) {
+      try { db.exec('ROLLBACK'); } catch { /* tolerate stack-unwind issues */ }
+      throw err;
+    }
+    db.exec('COMMIT');
+    return result;
+  };
+}
 
 /**
  * Default token-sweeper grace: keep used tokens for 24h after redemption
@@ -76,11 +104,11 @@ const DDL = `
  * @returns {Store}
  */
 export function createStore(dbPath = ':memory:') {
-  const db = new Database(dbPath);
-  db.pragma('journal_mode = WAL');
-  db.pragma('synchronous = NORMAL');
-  db.pragma('foreign_keys = OFF');
-  db.pragma('temp_store = MEMORY');
+  const db = new DatabaseSync(dbPath);
+  db.exec('PRAGMA journal_mode = WAL');
+  db.exec('PRAGMA synchronous = NORMAL');
+  db.exec('PRAGMA foreign_keys = OFF');
+  db.exec('PRAGMA temp_store = MEMORY');
   db.exec(DDL);
 
   const existing = db
@@ -166,7 +194,7 @@ export function createStore(dbPath = ':memory:') {
   };
 
   // Transactional cap-check + insert per SPEC §4.7.
-  const insertTokenAtomic = db.transaction(
+  const insertTokenAtomic = makeTransaction(db,
     (tokenHash, handle, expiresAt, nextUrl, isSham, maxActive, now) => {
       if (maxActive > 0) {
         const { n: count } = stmt.countActiveTokens.get(handle, now);
@@ -181,7 +209,7 @@ export function createStore(dbPath = ':memory:') {
   );
 
   // Transactional account deletion per FR-37a.
-  const deleteHandleAtomic = db.transaction((handle) => {
+  const deleteHandleAtomic = makeTransaction(db, (handle) => {
     stmt.deleteHandleSessions.run(handle);
     stmt.deleteHandleTokens.run(handle);
     stmt.deleteHandleRow.run(handle);