knowless 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -7,13 +7,88 @@ Versioning is [SemVer](https://semver.org/).
 
 ## [Unreleased]
 
-- Standalone server (`bin/knowless-server`): env-var-driven CLI with
-  `--print-config` and `--config-check`, forward-auth deployment shape
-  for self-hosters gating no-auth services. (Tracked in TASKS.md
-  Phase 6.)
-- `OPS.md`: full operator setup walkthrough (Postfix, null-route for
-  sham mail, SPF/DKIM/PTR, reverse-proxy configs for Caddy / nginx /
-  Traefik). (Tracked in TASKS.md Phase 7.)
+- 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. Honest answer to "does the operator's null-route
+  actually work?" — the library can know what it submitted but
+  not what the MTA did, so this is the closest we can get.
+  Targeted for v0.2.0.
+
+## [0.1.4] — 2026-04-28
+
+First real-world integration release. Bugs and ergonomics surfaced
+by the addypin team's spike on v0.1.3, plus two minor security
+hardenings that fell out of the audit.
+
+### Added
+
+- **`auth.revokeSessions(handle)`** — log out everywhere without
+  deleting the account. Returns the number of sessions removed.
+  Closes AF-6.1.
+- **`devLogMagicLinks: true`** opt-in — when SMTP fails AND this
+  flag is set, prints the magic link to stderr so a developer can
+  click through. Off by default; never fires for sham (silent-miss)
+  submissions; never replaces real SMTP delivery on success. Closes
+  AF-6.2.
+- **CIDR support in `trustedProxies`** — accept `10.0.0.0/8`,
+  `fd00::/8`, etc. in addition to plain IPs. Uses `node:net`
+  `BlockList`, no new dep. Closes AF-6.3.
+
+### Security
+
+- **CSRF on `POST /logout`.** Origin/Referer validation now mirrors
+  `POST /login` (AF-4.3). Without this, a malicious page could
+  force-logout an authenticated victim. Closes AF-6.4.
+- **`confirmationMessage` is HTML-escaped before rendering.** The
+  message is operator-config (not user input), but a careless
+  operator interpolating user data into it would have produced an
+  XSS. The whole message is now escaped before `{email}` substitution
+  (which was already escaped). Operators who want HTML in the
+  confirmation message must pre-render upstream. Closes AF-6.5.
+
+### Documentation
+
+- **SPEC §10.2** documents the new logout Origin check.
+- **SPEC §7.3 Step 0** adds an explicit "do NOT add a CSRF token
+  upstream — the Origin/Referer whitelist IS the CSRF defense"
+  note for adopters. Closes AF-6.6.
+- **GUIDE.md** front-matter now leads with the v1.0.0 walks-away
+  commitment. Procurement signal: a library that has explicitly
+  committed to *not growing* is a different risk profile from a
+  typical OSS package. Closes AF-6.7.
+
+## [0.1.3] — 2026-04-28
+
+Standalone-deployment release. The library could already be embedded
+in a Node service since v0.1.0; v0.1.3 closes the operator-side story
+so a self-hoster can `npx knowless-server` and have a working
+forward-auth gate in front of arbitrary services.
+
+### Added
+
+- **Standalone server** — `bin/knowless-server` ships a self-contained
+  HTTP server for forward-auth deployments. Configuration is via
+  `KNOWLESS_*` env vars (PRD FR-49 to FR-56); CLI flags are inspection-
+  only:
+  - `--help` lists every env var with default and purpose
+  - `--version` prints the package version
+  - `--print-config` prints effective config with secrets redacted as
+    `<set>` / `<unset>`
+  - `--config-check` validates required vars are present, the secret
+    is ≥64 hex chars, the SMTP host is reachable, and the DB path is
+    writable. Suitable for systemd `ExecStartPre`.
+- `config.example.env` — documented sample env file at repo root.
+  Operators copy this and load via `node --env-file=...` or systemd
+  `EnvironmentFile=`. Library does not auto-load it (FR-56).
+- Startup log block (FR-54) with effective config, SMTP check result,
+  and listening address.
+- **`OPS.md`** — full operator setup walkthrough: Postfix
+  outbound-only install, **required** null-route for sham mail,
+  SPF / DKIM / PTR / DMARC, port-25 verification, hardened systemd
+  unit, Caddy / nginx / Traefik forward-auth examples, Tailscale
+  pattern, reverse-proxy rate limiting, fail2ban / Turnstile
+  references, backup guidance.
 
 ## [0.1.2] — 2026-04-28
 

package/GUIDE.md

@@ -5,6 +5,32 @@
 > For the product philosophy, see
 > [`docs/01-product/PRD.md`](docs/01-product/PRD.md).
 
+## Read this first: knowless walks away at v1.0.0
+
+knowless commits to a small, audit-able surface and a *closed* feature
+list. v1.0.0 is the **terminal release** for new functionality: only
+security fixes ship after that. There will be no v2.0 with sessions+,
+no plugin system, no second mailer, no SaaS counterpart.
+
+What this means for you as an adopter:
+
+- **You own integration breadth.** If knowless's defaults don't fit
+  exactly, you patch around it (the API is small enough to do this) or
+  fork it (Apache 2.0). We won't add a config knob to absorb your
+  case.
+- **You can pin and forget.** v1.0.0 will work the same way three
+  years later. Security patches will land in v1.x.
+- **Procurement signal.** A library that has explicitly committed to
+  *not growing* is a different risk profile from a typical OSS
+  package. Most reviews assume "still actively developed" is good;
+  for an auth dependency, "still actively developed" is also "still
+  changing in ways you'll have to track." knowless inverts that.
+
+If you need a kitchen-sink auth library with active feature
+development, this isn't the right tool. See
+[Lucia](https://lucia-auth.com/), [Auth.js](https://authjs.dev/),
+or commercial offerings.
+
 ## Who this is for
 
 Three audiences, in order of fit:

package/OPS.md

@@ -0,0 +1,573 @@
+# OPS — knowless operator setup
+
+This guide takes a fresh Ubuntu/Debian VPS to "knowless is delivering
+magic-link mail to your users' inbox." Every step is a manual decision
+point for the operator. There are no automation scripts; ops is your
+job and we provide the checklist.
+
+If any step here surprises you — outbound port 25, DKIM, PTR records,
+the null-route requirement — stop and read PRD §11 first. knowless
+trades operator effort for a small, auditable surface. If you'd rather
+delegate email to a SaaS, knowless is the wrong tool.
+
+---
+
+## 1. Prerequisites
+
+- Ubuntu 22.04 / 24.04 or Debian 12, on a host that can:
+  - bind a public DNS name (e.g. `auth.example.com`)
+  - send outbound TCP/25 (verify before going further — see §3)
+  - have a working PTR record for its public IPv4 (and IPv6 if used)
+- A domain with control of its DNS records
+- Node.js ≥ 20 installed
+- A reverse proxy in front of HTTP (Caddy, nginx, or Traefik)
+
+knowless does not handle TLS termination. Your reverse proxy does.
+
+---
+
+## 2. Install Postfix (outbound-only)
+
+knowless submits mail to a localhost MTA over plain SMTP on port 25
+without auth. The MTA does the actual delivery. Postfix is the
+recommended choice; any MTA that accepts unauthenticated localhost
+submission works.
+
+```sh
+sudo DEBIAN_FRONTEND=noninteractive apt-get install -y postfix mailutils
+# When the installer asks: choose "Internet Site"
+# System mail name: your sending domain (e.g. example.com)
+```
+
+Minimal `/etc/postfix/main.cf` for outbound-only:
+
+```
+myhostname        = mail.example.com
+mydomain          = example.com
+myorigin          = $mydomain
+inet_interfaces   = loopback-only
+inet_protocols    = ipv4
+mydestination     =
+relayhost         =
+smtp_tls_security_level = may
+smtp_tls_loglevel       = 1
+```
+
+`inet_interfaces = loopback-only` means Postfix accepts submission
+only from `127.0.0.1`. knowless connects there. Restart:
+
+```sh
+sudo systemctl restart postfix
+sudo systemctl enable postfix
+```
+
+Verify the localhost submission works:
+
+```sh
+echo "Subject: test" | sendmail -v you@somewhere-you-control.com
+sudo tail /var/log/mail.log
+```
+
+If you see `status=sent` you are done with §2.
+
+---
+
+## 3. Verify outbound port 25
+
+Many cloud providers (AWS, GCP, Azure, Oracle, DigitalOcean droplets,
+Hetzner cloud, …) block outbound TCP/25 by default to limit spam from
+compromised instances. **Test before troubleshooting anything else.**
+
+```sh
+nc -zv gmail-smtp-in.l.google.com 25
+# Expected: succeeded / Connection to ... 25 port [tcp/smtp] succeeded
+```
+
+If this hangs or fails:
+- AWS: open a "Request to remove email sending limitations" ticket.
+- GCP: port 25 is permanently blocked. Use a relay (see below) or
+  move to a provider that allows it.
+- Hetzner: port 25 is blocked on new accounts; ask support.
+- Most VPS hosts (Vultr, OVH, Linode, your own metal): open by default.
+
+**Alternative if port 25 is permanently blocked:** configure Postfix
+to relay through a transactional provider's submission endpoint
+(587/465 with auth). knowless still talks to localhost; Postfix is
+what relays out. That's a Postfix concern, not a knowless concern.
+
+---
+
+## 4. Null-route for sham mail (REQUIRED)
+
+knowless's silent-miss design (PRD FR-2 to FR-6) submits a real-shaped
+SMTP message on every login attempt — including ones where the email
+doesn't map to any registered handle. The "sham" submissions are
+addressed to `null@knowless.invalid` by default. Without a null-route,
+Postfix will queue these forever trying to resolve a nonexistent
+domain. **Configure the null-route. SPEC §7.4.**
+
+```sh
+# /etc/postfix/transport
+knowless.invalid    discard:silently dropped by knowless null-route
+```
+
+Then:
+
+```sh
+sudo postmap /etc/postfix/transport
+```
+
+Add to `/etc/postfix/main.cf`:
+
+```
+transport_maps = hash:/etc/postfix/transport
+```
+
+Reload:
+
+```sh
+sudo systemctl reload postfix
+```
+
+Verify discard works:
+
+```sh
+echo "test" | mail -s "should be dropped" null@knowless.invalid
+sudo tail /var/log/mail.log | grep knowless.invalid
+# Expected: status=sent (silently dropped by knowless null-route)
+```
+
+If you customized `shamRecipient` in your knowless config to point
+elsewhere, change the transport entry's domain to match.
+
+---
+
+## 5. SPF, DKIM, PTR
+
+Without these your magic-link mail goes to spam. There is no
+shortcut here.
+
+### 5.1 SPF
+
+Add a TXT record at the apex of your sending domain:
+
+```
+example.com.  TXT  "v=spf1 mx a ~all"
+```
+
+If your knowless server is *not* an MX for the domain, replace
+`mx` with `ip4:1.2.3.4` listing the server's public IP.
+
+### 5.2 DKIM
+
+Install OpenDKIM:
+
+```sh
+sudo apt-get install -y opendkim opendkim-tools
+sudo opendkim-genkey -D /etc/opendkim/keys -d example.com -s mail
+sudo chown opendkim:opendkim /etc/opendkim/keys/mail.private
+sudo chmod 600 /etc/opendkim/keys/mail.private
+```
+
+`/etc/opendkim/keys/mail.txt` now contains the DNS record. Publish it
+as `mail._domainkey.example.com` in your DNS.
+
+Wire OpenDKIM into Postfix — add to `/etc/postfix/main.cf`:
+
+```
+milter_default_action = accept
+smtpd_milters         = inet:localhost:8891
+non_smtpd_milters     = $smtpd_milters
+```
+
+Configure `/etc/opendkim.conf`:
+
+```
+Domain                  example.com
+KeyFile                 /etc/opendkim/keys/mail.private
+Selector                mail
+Socket                  inet:8891@localhost
+```
+
+Restart both:
+
+```sh
+sudo systemctl restart opendkim postfix
+```
+
+Verify with `mail-tester.com`: send a test, expect 9–10/10.
+
+### 5.3 PTR (reverse DNS)
+
+Your server's public IP must reverse-resolve to a hostname. **Most
+providers expose this in their control panel** (Hetzner: "rDNS";
+DigitalOcean: name your droplet `mail.example.com`; OVH: "Reverse
+DNS" tab). Set the PTR to the same hostname you put in
+`myhostname` (§2). Verify:
+
+```sh
+dig -x 1.2.3.4 +short
+# Expected: mail.example.com.
+```
+
+A missing or generic PTR (`ec2-...`, `static.cloud-provider.tld`)
+is the single most common reason mail lands in spam.
+
+### 5.4 Optional: DMARC
+
+```
+_dmarc.example.com.  TXT  "v=DMARC1; p=none; rua=mailto:postmaster@example.com"
+```
+
+Start with `p=none` to monitor. Move to `p=quarantine` later if you
+want stricter handling.
+
+---
+
+## 6. Run knowless-server under systemd
+
+```sh
+sudo useradd --system --home /var/lib/knowless --create-home knowless
+sudo install -d -o knowless -g knowless -m 0750 /var/lib/knowless /etc/knowless
+```
+
+Generate a secret and create `/etc/knowless/knowless.env`:
+
+```sh
+sudo install -m 0600 -o knowless -g knowless /dev/null /etc/knowless/knowless.env
+sudo tee /etc/knowless/knowless.env > /dev/null <<EOF
+KNOWLESS_SECRET=$(openssl rand -hex 32)
+KNOWLESS_BASE_URL=https://auth.example.com
+KNOWLESS_FROM=auth@example.com
+KNOWLESS_DB_PATH=/var/lib/knowless/knowless.db
+KNOWLESS_COOKIE_DOMAIN=example.com
+KNOWLESS_COOKIE_SECURE=true
+KNOWLESS_HOST=127.0.0.1
+KNOWLESS_PORT=8080
+EOF
+sudo chmod 0600 /etc/knowless/knowless.env
+```
+
+`/etc/systemd/system/knowless.service`:
+
+```ini
+[Unit]
+Description=knowless passwordless auth server
+Wants=network-online.target postfix.service
+After=network-online.target postfix.service
+
+[Service]
+Type=simple
+User=knowless
+Group=knowless
+EnvironmentFile=/etc/knowless/knowless.env
+ExecStartPre=/usr/bin/npx --yes knowless-server --config-check
+ExecStart=/usr/bin/npx --yes knowless-server
+Restart=on-failure
+RestartSec=2
+
+# Hardening
+NoNewPrivileges=true
+ProtectSystem=strict
+ProtectHome=true
+ReadWritePaths=/var/lib/knowless
+PrivateTmp=true
+PrivateDevices=true
+ProtectKernelTunables=true
+ProtectKernelModules=true
+ProtectControlGroups=true
+RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX
+LockPersonality=true
+SystemCallArchitectures=native
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Enable:
+
+```sh
+sudo systemctl daemon-reload
+sudo systemctl enable --now knowless
+sudo systemctl status knowless
+sudo journalctl -u knowless -f
+```
+
+`ExecStartPre=knowless-server --config-check` ensures a misconfigured
+deploy fails to start instead of silently breaking auth.
+
+---
+
+## 7. Reverse proxy — pick one
+
+knowless does not terminate TLS. Your proxy fronts it on `:443`,
+forwards `Host` and `X-Forwarded-For`, and (for forward-auth
+deployments) routes protected upstreams through `/verify`.
+
+### 7.1 Caddy
+
+```caddy
+auth.example.com {
+    reverse_proxy 127.0.0.1:8080
+}
+
+# Protect Uptime Kuma with knowless forward-auth
+kuma.example.com {
+    forward_auth 127.0.0.1:8080 {
+        uri /verify
+        copy_headers X-Knowless-Handle
+    }
+    reverse_proxy 127.0.0.1:3001
+}
+```
+
+Caddy auto-issues TLS via Let's Encrypt and trusts itself as a proxy
+on the loopback. knowless's default `KNOWLESS_TRUSTED_PROXIES=127.0.0.1,::1`
+covers this.
+
+### 7.2 nginx
+
+```nginx
+# /etc/nginx/sites-available/auth.example.com
+server {
+    listen 443 ssl http2;
+    server_name auth.example.com;
+    # ssl_certificate / ssl_certificate_key managed by certbot
+
+    location / {
+        proxy_pass http://127.0.0.1:8080;
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-For $remote_addr;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+}
+
+# Protect a service with auth_request
+server {
+    listen 443 ssl http2;
+    server_name kuma.example.com;
+
+    location = /_knowless_verify {
+        internal;
+        proxy_pass http://127.0.0.1:8080/verify;
+        proxy_pass_request_body off;
+        proxy_set_header Content-Length "";
+        proxy_set_header X-Original-URI $request_uri;
+        proxy_set_header Cookie $http_cookie;
+    }
+
+    error_page 401 = @knowless_login;
+    location @knowless_login {
+        return 302 https://auth.example.com/login?next=https://$host$request_uri;
+    }
+
+    location / {
+        auth_request /_knowless_verify;
+        auth_request_set $handle $upstream_http_x_knowless_handle;
+        proxy_set_header X-Knowless-Handle $handle;
+        proxy_pass http://127.0.0.1:3001;
+    }
+}
+```
+
+### 7.3 Traefik
+
+```yaml
+# dynamic.yml
+http:
+  middlewares:
+    knowless:
+      forwardAuth:
+        address: "http://127.0.0.1:8080/verify"
+        authResponseHeaders: [ "X-Knowless-Handle" ]
+
+  routers:
+    auth:
+      rule: "Host(`auth.example.com`)"
+      service: knowless
+      tls: { certResolver: le }
+    kuma:
+      rule: "Host(`kuma.example.com`)"
+      service: kuma
+      middlewares: [ knowless ]
+      tls: { certResolver: le }
+
+  services:
+    knowless:
+      loadBalancer:
+        servers: [{ url: "http://127.0.0.1:8080" }]
+    kuma:
+      loadBalancer:
+        servers: [{ url: "http://127.0.0.1:3001" }]
+```
+
+---
+
+## 8. Tailscale / WireGuard pattern
+
+A common deployment: knowless lives on a public VPS (port 25 open,
+PTR set), but the services it protects live on a home server.
+Connect them with a mesh VPN.
+
+```
+public VPS                      home server
++----------------+              +-------------------+
+| Caddy :443     |              | Uptime Kuma :3001 |
+| knowless :8080 |              | Vaultwarden :8222 |
+| tailscale0     |--------------| tailscale0        |
++----------------+              +-------------------+
+```
+
+In Caddy on the VPS:
+
+```caddy
+kuma.example.com {
+    forward_auth 127.0.0.1:8080 {
+        uri /verify
+    }
+    reverse_proxy 100.64.0.5:3001   # tailscale IP of home server
+}
+```
+
+Home server exposes nothing publicly. The VPS terminates TLS, runs
+auth, and proxies through the mesh.
+
+---
+
+## 9. Reverse-proxy rate limiting (defence in depth)
+
+knowless ships modest in-process limits as a baseline (FR-39).
+Operators expecting elevated abuse should layer stricter limits at
+the proxy. The proxy sees traffic earlier and can drop it without
+even hitting Node.
+
+### 9.1 Caddy
+
+```caddy
+auth.example.com {
+    rate_limit {
+        zone login_ip {
+            key      {client_ip}
+            window   1m
+            events   10
+        }
+        match path /login
+    }
+    reverse_proxy 127.0.0.1:8080
+}
+```
+
+(Requires the `caddy-ratelimit` plugin; build with
+`xcaddy build --with github.com/mholt/caddy-ratelimit`.)
+
+### 9.2 nginx
+
+```nginx
+limit_req_zone $binary_remote_addr zone=knowless_login:10m rate=10r/m;
+
+server {
+    location = /login {
+        limit_req zone=knowless_login burst=5 nodelay;
+        proxy_pass http://127.0.0.1:8080;
+    }
+}
+```
+
+---
+
+## 10. fail2ban / Cloudflare Turnstile (heavier abuse profiles)
+
+Optional; both have trade-offs.
+
+**fail2ban** can tail `journalctl -u knowless` and block IPs that
+trip many rate-limit responses:
+
+```ini
+# /etc/fail2ban/filter.d/knowless.conf
+[Definition]
+failregex = ^.*\s+\[knowless\]\s+rate-limited\s+ip=<HOST>
+ignoreregex =
+```
+
+```ini
+# /etc/fail2ban/jail.d/knowless.conf
+[knowless]
+enabled  = true
+filter   = knowless
+backend  = systemd
+journalmatch = _SYSTEMD_UNIT=knowless.service
+maxretry = 20
+findtime = 600
+bantime  = 3600
+action   = iptables[name=knowless, port=https, protocol=tcp]
+```
+
+(knowless does not log structured rate-limit lines today; if you want
+this you may need to wrap it. See Issue tracker.)
+
+**Cloudflare Turnstile** is the lowest-friction CAPTCHA but
+introduces a third-party dependency on Cloudflare for every login
+form load. knowless doesn't integrate it natively; if you need it,
+embed the widget in your own login page (use the library mode
+`renderLoginForm` as a starting template).
+
+Both are last-resort knobs. Most operators won't need them.
+
+---
+
+## 11. Operational checks
+
+Once running:
+
+```sh
+# Validate config
+sudo -u knowless npx --yes knowless-server --config-check
+
+# Print effective config (secrets redacted)
+sudo -u knowless npx --yes knowless-server --print-config
+
+# Watch logs
+sudo journalctl -u knowless -f
+
+# Send yourself a magic link end-to-end
+curl -i -X POST https://auth.example.com/login \
+  -d email=you@somewhere-you-control.com
+# Then check your inbox (NOT spam) for the link.
+```
+
+If the email lands in spam, work through §5 (SPF, DKIM, PTR, DMARC)
+in that order — most spam-folder verdicts trace to one of those four.
+
+---
+
+## 12. Backup and recovery
+
+The only stateful file is the SQLite database (`KNOWLESS_DB_PATH`,
+default `/var/lib/knowless/knowless.db`). It contains:
+
+- Handles (HMAC outputs of email addresses)
+- Active token hashes (short-lived, 15 min default)
+- Session ID hashes (30 day default)
+- Rate-limit counters
+
+Loss is recoverable: users sign in again and get a new session. There
+is no irreplaceable data here. A weekly `sqlite3 knowless.db .backup`
+is sufficient.
+
+The HMAC secret in `/etc/knowless/knowless.env` is the actual asset
+to protect. Losing it logs every user out and changes every handle
+(emails will be re-derived to new opaque values on next login).
+**Back up the secret separately, out-of-band, encrypted.** Never
+commit it.
+
+---
+
+## 13. Where things are documented
+
+- **PRD** (`docs/01-product/PRD.md`) — what the library does and
+  doesn't do, threat model, NO-GO list
+- **SPEC** (`docs/02-design/SPEC.md`) — wire formats, exact flows,
+  schema
+- **GUIDE.md** — application-developer integration in library mode
+- **README.md** — short orientation
+- **OPS.md** (this document) — operator-side setup

package/README.md

@@ -104,16 +104,18 @@ By choosing knowless, you commit to:
   silent-miss sham mail is dropped, not delivered to NXDOMAIN
 - Accepting that this is the **only email** your service ever sends
 
-These are documented in `OPS.md` (forthcoming with 0.2.0). Until
-then, see `GUIDE.md` for the high-level path and the
-[Postfix outbound-only setup guide](https://www.postfix.org/STANDARD_CONFIGURATION_README.html#stand_alone)
-upstream.
+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.
 
 ## 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)
 - [`docs/01-product/PRD.md`](docs/01-product/PRD.md) — product

package/bin/knowless-server

@@ -0,0 +1,313 @@
+#!/usr/bin/env node
+// knowless-server — standalone forward-auth HTTP server.
+// All configuration via KNOWLESS_* env vars. PRD §7.12 (FR-49 to FR-56).
+
+import { parseArgs } from 'node:util';
+import { createServer } from 'node:http';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import net from 'node:net';
+import fs from 'node:fs';
+import { knowless } from '../src/index.js';
+
+const PKG = JSON.parse(
+  readFileSync(
+    join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'),
+    'utf8',
+  ),
+);
+
+// [optionKey, envVar, default (null = required), purpose, secret?]
+const SPEC = [
+  ['secret', 'KNOWLESS_SECRET', null, 'HMAC secret, ≥64 hex chars (32 bytes). REQUIRED.', true],
+  ['baseUrl', 'KNOWLESS_BASE_URL', null, 'Public base URL for magic links. REQUIRED.'],
+  ['from', 'KNOWLESS_FROM', null, 'Sender email address. REQUIRED.'],
+  ['dbPath', 'KNOWLESS_DB_PATH', './knowless.db', 'SQLite database path.'],
+  ['cookieDomain', 'KNOWLESS_COOKIE_DOMAIN', '', 'Session cookie domain. Defaults to baseUrl hostname.'],
+  ['cookieSecure', 'KNOWLESS_COOKIE_SECURE', 'true', 'Set Secure flag on cookies. "false" only for localhost dev.'],
+  ['tokenTtlSeconds', 'KNOWLESS_TOKEN_TTL_SECONDS', '900', 'Magic-link token lifetime (seconds).'],
+  ['sessionTtlSeconds', 'KNOWLESS_SESSION_TTL_SECONDS', '2592000', 'Session lifetime (seconds, default 30d).'],
+  ['linkPath', 'KNOWLESS_LINK_PATH', '/auth/callback', 'Magic-link callback path.'],
+  ['loginPath', 'KNOWLESS_LOGIN_PATH', '/login', 'Login form path.'],
+  ['verifyPath', 'KNOWLESS_VERIFY_PATH', '/verify', 'Forward-auth check path.'],
+  ['logoutPath', 'KNOWLESS_LOGOUT_PATH', '/logout', 'Logout path.'],
+  ['smtpHost', 'KNOWLESS_SMTP_HOST', 'localhost', 'SMTP host for outgoing magic-link mail.'],
+  ['smtpPort', 'KNOWLESS_SMTP_PORT', '25', 'SMTP port.'],
+  ['openRegistration', 'KNOWLESS_OPEN_REGISTRATION', 'false', 'Allow new-handle creation on first email.'],
+  ['subject', 'KNOWLESS_SUBJECT', 'Sign in', 'Email subject line.'],
+  ['includeLastLoginInEmail', 'KNOWLESS_INCLUDE_LAST_LOGIN_IN_EMAIL', 'true', 'Append last-sign-in note to magic-link email.'],
+  ['maxActiveTokensPerHandle', 'KNOWLESS_MAX_ACTIVE_TOKENS_PER_HANDLE', '5', 'Cap on concurrent magic links per handle. 0 disables.'],
+  ['maxLoginRequestsPerIpPerHour', 'KNOWLESS_MAX_LOGIN_REQUESTS_PER_IP_PER_HOUR', '30', 'Per-IP login submission cap. 0 disables.'],
+  ['maxNewHandlesPerIpPerHour', 'KNOWLESS_MAX_NEW_HANDLES_PER_IP_PER_HOUR', '3', 'Per-IP account-creation cap (openRegistration only). 0 disables.'],
+  ['honeypotFieldName', 'KNOWLESS_HONEYPOT_FIELD_NAME', 'website', 'Name of the honeypot field.'],
+  ['trustedProxies', 'KNOWLESS_TRUSTED_PROXIES', '127.0.0.1,::1', 'Comma-separated IPs trusted for X-Forwarded-For.'],
+];
+
+// PORT is a runtime-only knob; not part of the library options object.
+const SERVER_SPEC = [
+  ['port', 'KNOWLESS_PORT', '8080', 'TCP port the HTTP server binds.'],
+  ['host', 'KNOWLESS_HOST', '0.0.0.0', 'Address the HTTP server binds.'],
+];
+
+const NUMERIC = new Set([
+  'tokenTtlSeconds',
+  'sessionTtlSeconds',
+  'smtpPort',
+  'maxActiveTokensPerHandle',
+  'maxLoginRequestsPerIpPerHour',
+  'maxNewHandlesPerIpPerHour',
+]);
+const BOOLEAN = new Set([
+  'cookieSecure',
+  'openRegistration',
+  'includeLastLoginInEmail',
+]);
+const LIST = new Set(['trustedProxies']);
+
+function loadFromEnv(env = process.env) {
+  const opts = {};
+  for (const [key, envVar, def] of SPEC) {
+    const raw = env[envVar];
+    const value = raw !== undefined && raw !== '' ? raw : def;
+    if (value === null) continue; // required, missing — leave unset
+    if (value === '') continue;    // optional with empty default — skip
+    if (NUMERIC.has(key)) opts[key] = Number(value);
+    else if (BOOLEAN.has(key)) opts[key] = value === 'true' || value === '1';
+    else if (LIST.has(key)) opts[key] = value.split(',').map((s) => s.trim()).filter(Boolean);
+    else opts[key] = value;
+  }
+  const serverConfig = {};
+  for (const [key, envVar, def] of SERVER_SPEC) {
+    const raw = env[envVar];
+    const value = raw !== undefined && raw !== '' ? raw : def;
+    serverConfig[key] = key === 'port' ? Number(value) : value;
+  }
+  return { opts, serverConfig };
+}
+
+function printHelp() {
+  process.stdout.write(`knowless-server v${PKG.version}
+
+Usage:  knowless-server [--help | --version | --print-config | --config-check]
+
+Configuration is via environment variables. CLI flags do NOT set config.
+
+Required env vars:
+`);
+  for (const [, envVar, def, purpose] of SPEC) {
+    if (def !== null) continue;
+    process.stdout.write(`  ${envVar}\n      ${purpose}\n`);
+  }
+  process.stdout.write('\nOptional env vars (with defaults):\n');
+  for (const [, envVar, def, purpose] of SPEC) {
+    if (def === null) continue;
+    const shown = def === '' ? '<derived>' : def;
+    process.stdout.write(`  ${envVar}=${shown}\n      ${purpose}\n`);
+  }
+  for (const [, envVar, def, purpose] of SERVER_SPEC) {
+    process.stdout.write(`  ${envVar}=${def}\n      ${purpose}\n`);
+  }
+  process.stdout.write(
+    '\nLoad a .env file with:  node --env-file=knowless.env $(which knowless-server)\n',
+  );
+}
+
+function formatConfig({ opts, serverConfig }) {
+  const lines = [];
+  for (const [key, envVar, , , isSecret] of SPEC) {
+    if (!(key in opts)) {
+      lines.push(`${envVar}=<unset>`);
+      continue;
+    }
+    let val = opts[key];
+    if (isSecret) val = '<set>';
+    else if (Array.isArray(val)) val = val.join(',');
+    lines.push(`${envVar}=${val}`);
+  }
+  for (const [key, envVar] of SERVER_SPEC) {
+    lines.push(`${envVar}=${serverConfig[key]}`);
+  }
+  return lines.join('\n');
+}
+
+function checkRequired(opts) {
+  const errors = [];
+  for (const [key, envVar, def] of SPEC) {
+    if (def !== null) continue;
+    if (!(key in opts)) errors.push(`${envVar} is missing`);
+  }
+  if (opts.secret && opts.secret.length < 64) {
+    errors.push('KNOWLESS_SECRET must be at least 64 hex chars (32 bytes)');
+  }
+  return errors;
+}
+
+function checkSmtpReachable(host, port, timeoutMs = 2000) {
+  return new Promise((resolve) => {
+    const sock = net.createConnection({ host, port });
+    let done = false;
+    const finish = (ok, err) => {
+      if (done) return;
+      done = true;
+      try { sock.destroy(); } catch { /* tolerate */ }
+      resolve({ ok, err });
+    };
+    sock.setTimeout(timeoutMs);
+    sock.once('connect', () => finish(true));
+    sock.once('timeout', () => finish(false, new Error('connection timed out')));
+    sock.once('error', (e) => finish(false, e));
+  });
+}
+
+function checkDbWritable(dbPath) {
+  if (dbPath === ':memory:') return { ok: true };
+  try {
+    const dir = dirname(dbPath);
+    fs.accessSync(dir, fs.constants.W_OK);
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, err };
+  }
+}
+
+async function runConfigCheck({ opts, serverConfig }, { print } = { print: true }) {
+  if (print) process.stdout.write(formatConfig({ opts, serverConfig }) + '\n');
+  const errors = checkRequired(opts);
+  if (errors.length) {
+    for (const e of errors) process.stderr.write(`config error: ${e}\n`);
+    return 1;
+  }
+  const smtp = await checkSmtpReachable(opts.smtpHost, opts.smtpPort);
+  if (!smtp.ok) {
+    process.stderr.write(
+      `config error: SMTP ${opts.smtpHost}:${opts.smtpPort} not reachable: ${smtp.err.message}\n`,
+    );
+    return 1;
+  }
+  process.stdout.write(`SMTP ${opts.smtpHost}:${opts.smtpPort} reachable: OK\n`);
+  const db = checkDbWritable(opts.dbPath);
+  if (!db.ok) {
+    process.stderr.write(
+      `config error: DB path ${opts.dbPath} not writable: ${db.err.message}\n`,
+    );
+    return 1;
+  }
+  process.stdout.write(`DB path ${opts.dbPath} writable: OK\n`);
+  return 0;
+}
+
+function buildRouter(auth, cfg) {
+  const map = new Map([
+    [`POST ${cfg.loginPath}`, auth.login],
+    [`GET ${cfg.loginPath}`, auth.loginForm],
+    [`GET ${cfg.linkPath}`, auth.callback],
+    [`GET ${cfg.verifyPath}`, auth.verify],
+    [`POST ${cfg.logoutPath}`, auth.logout],
+  ]);
+  return (req, res) => {
+    const url = new URL(req.url, 'http://placeholder.invalid');
+    const handler = map.get(`${req.method} ${url.pathname}`);
+    if (!handler) {
+      res.statusCode = 404;
+      res.setHeader('content-type', 'text/plain; charset=utf-8');
+      res.end('not found\n');
+      return;
+    }
+    Promise.resolve()
+      .then(() => handler(req, res))
+      .catch((err) => {
+        process.stderr.write(`[knowless] handler error: ${err.stack || err.message}\n`);
+        if (!res.headersSent) {
+          res.statusCode = 500;
+          res.setHeader('content-type', 'text/plain; charset=utf-8');
+          res.end('internal error\n');
+        }
+      });
+  };
+}
+
+async function runServer({ opts, serverConfig }) {
+  const errors = checkRequired(opts);
+  if (errors.length) {
+    for (const e of errors) process.stderr.write(`config error: ${e}\n`);
+    return 1;
+  }
+  const auth = knowless(opts);
+  const router = buildRouter(auth, auth.config);
+  const server = createServer(router);
+
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(serverConfig.port, serverConfig.host, () => {
+      server.off('error', reject);
+      resolve();
+    });
+  });
+
+  // FR-54: single startup log block.
+  const block =
+    '--- knowless-server started ---\n' +
+    formatConfig({ opts, serverConfig }) +
+    `\nlistening: http://${serverConfig.host}:${serverConfig.port}\n` +
+    '-------------------------------\n';
+  process.stdout.write(block);
+
+  const shutdown = (sig) => {
+    process.stdout.write(`[knowless] ${sig}, shutting down\n`);
+    server.close(() => {
+      try { auth.close(); } catch { /* tolerate */ }
+      process.exit(0);
+    });
+    setTimeout(() => process.exit(1), 5000).unref();
+  };
+  process.on('SIGINT', () => shutdown('SIGINT'));
+  process.on('SIGTERM', () => shutdown('SIGTERM'));
+  return null;
+}
+
+async function main(argv = process.argv.slice(2)) {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      options: {
+        help: { type: 'boolean' },
+        version: { type: 'boolean' },
+        'print-config': { type: 'boolean' },
+        'config-check': { type: 'boolean' },
+      },
+      strict: true,
+      allowPositionals: false,
+    });
+  } catch (err) {
+    process.stderr.write(`error: ${err.message}\nrun with --help for usage\n`);
+    return 2;
+  }
+  const { values } = parsed;
+  if (values.help) { printHelp(); return 0; }
+  if (values.version) { process.stdout.write(PKG.version + '\n'); return 0; }
+
+  const cfg = loadFromEnv();
+  if (values['print-config']) {
+    process.stdout.write(formatConfig(cfg) + '\n');
+    return 0;
+  }
+  if (values['config-check']) {
+    return runConfigCheck(cfg);
+  }
+  const code = await runServer(cfg);
+  return code === null ? undefined : code;
+}
+
+const isEntrypoint = import.meta.url === `file://${process.argv[1]}`;
+if (isEntrypoint) {
+  main().then((code) => {
+    if (code !== undefined) process.exit(code);
+  }).catch((err) => {
+    process.stderr.write(`fatal: ${err.stack || err.message}\n`);
+    process.exit(1);
+  });
+}
+
+export { loadFromEnv, formatConfig, checkRequired, SPEC, SERVER_SPEC, main };

package/config.example.env

@@ -0,0 +1,74 @@
+# knowless-server — example configuration. PRD FR-56.
+#
+# Copy to e.g. /etc/knowless/knowless.env (mode 0600) and load via:
+#   node --env-file=/etc/knowless/knowless.env $(which knowless-server)
+# or systemd:
+#   EnvironmentFile=/etc/knowless/knowless.env
+#
+# This file is documentation, NOT loaded automatically by the library.
+
+# --- REQUIRED ---
+
+# HMAC secret for handle derivation and session signing.
+# Generate with: openssl rand -hex 32
+KNOWLESS_SECRET=
+
+# Public base URL of this auth server.
+KNOWLESS_BASE_URL=https://auth.example.com
+
+# Sender address for outgoing magic-link mail.
+KNOWLESS_FROM=auth@example.com
+
+# --- COMMON ---
+
+# SQLite database path. Parent dir must be writable.
+KNOWLESS_DB_PATH=/var/lib/knowless/knowless.db
+
+# Cookie domain. Defaults to baseUrl hostname; usually set to your eTLD+1
+# (e.g. example.com) so the session cookie is shared across subdomains.
+# KNOWLESS_COOKIE_DOMAIN=example.com
+
+# Set "false" only for http://localhost development. Library logs a warning.
+KNOWLESS_COOKIE_SECURE=true
+
+# Allow new-handle creation on first email. Default false (closed-reg).
+KNOWLESS_OPEN_REGISTRATION=false
+
+# --- SERVER ---
+
+KNOWLESS_HOST=0.0.0.0
+KNOWLESS_PORT=8080
+
+# --- SMTP ---
+# Default assumes a local Postfix on the same host (recommended).
+
+KNOWLESS_SMTP_HOST=localhost
+KNOWLESS_SMTP_PORT=25
+
+# --- TIMINGS (seconds) ---
+
+KNOWLESS_TOKEN_TTL_SECONDS=900
+KNOWLESS_SESSION_TTL_SECONDS=2592000
+
+# --- PATHS ---
+
+KNOWLESS_LOGIN_PATH=/login
+KNOWLESS_LINK_PATH=/auth/callback
+KNOWLESS_VERIFY_PATH=/verify
+KNOWLESS_LOGOUT_PATH=/logout
+
+# --- ABUSE LIMITS (0 disables) ---
+
+KNOWLESS_MAX_ACTIVE_TOKENS_PER_HANDLE=5
+KNOWLESS_MAX_LOGIN_REQUESTS_PER_IP_PER_HOUR=30
+KNOWLESS_MAX_NEW_HANDLES_PER_IP_PER_HOUR=3
+KNOWLESS_HONEYPOT_FIELD_NAME=website
+
+# Comma-separated. Reverse proxy must be in this list for X-Forwarded-For
+# to be honored.
+KNOWLESS_TRUSTED_PROXIES=127.0.0.1,::1
+
+# --- EMAIL CONTENT ---
+
+KNOWLESS_SUBJECT=Sign in
+KNOWLESS_INCLUDE_LAST_LOGIN_IN_EMAIL=true

package/package.json

@@ -1,19 +1,25 @@
 {
   "name": "knowless",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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",
   "exports": {
     ".": "./src/index.js"
   },
+  "bin": {
+    "knowless-server": "./bin/knowless-server"
+  },
   "files": [
     "src/",
+    "bin/",
+    "config.example.env",
     "LICENSE",
     "NOTICE",
     "README.md",
     "CHANGELOG.md",
     "GUIDE.md",
+    "OPS.md",
     "knowless.context.md"
   ],
   "engines": {

package/src/abuse.js

@@ -1,3 +1,62 @@
+import net from 'node:net';
+
+/**
+ * Build a peer-IP matcher from a list of plain IPs and/or CIDR ranges.
+ * AF-6.3 — CIDR support so docker / k8s / cgnat ranges can be trusted
+ * without enumerating every address.
+ *
+ * Accepts:
+ *   - bare IPv4/IPv6 ("127.0.0.1", "::1")
+ *   - CIDR ("10.0.0.0/8", "fd00::/8")
+ *   - a Set or array of either
+ *   - a `node:net` BlockList (passed through)
+ *
+ * @param {Set<string>|string[]|net.BlockList} trustedProxies
+ * @returns {{ has: (ip: string) => boolean }}
+ */
+export function buildTrustedPeers(trustedProxies) {
+  if (trustedProxies && typeof trustedProxies.check === 'function') {
+    return { has: (ip) => safeBlockListCheck(trustedProxies, ip) };
+  }
+  const list = Array.isArray(trustedProxies)
+    ? trustedProxies
+    : trustedProxies instanceof Set
+      ? [...trustedProxies]
+      : [];
+  const exact = new Set();
+  const block = new net.BlockList();
+  for (const entry of list) {
+    if (typeof entry !== 'string' || !entry) continue;
+    const slash = entry.indexOf('/');
+    if (slash >= 0) {
+      const addr = entry.slice(0, slash);
+      const prefix = Number(entry.slice(slash + 1));
+      const family = net.isIPv6(addr) ? 'ipv6' : 'ipv4';
+      try {
+        block.addSubnet(addr, prefix, family);
+      } catch {
+        /* skip malformed CIDR rather than crash */
+      }
+    } else {
+      exact.add(entry);
+    }
+  }
+  return {
+    has: (ip) => exact.has(ip) || safeBlockListCheck(block, ip),
+  };
+}
+
+function safeBlockListCheck(block, ip) {
+  if (typeof ip !== 'string' || ip.length === 0) return false;
+  const family = net.isIPv6(ip) ? 'ipv6' : net.isIPv4(ip) ? 'ipv4' : null;
+  if (!family) return false;
+  try {
+    return block.check(ip, family);
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Determine the source IP of a request per FR-42 and SPEC §7.6.
  *
@@ -6,19 +65,20 @@
  * fall back to the connection's remote address. This prevents IP
  * spoofing from clients while supporting forward-auth deployments.
  *
+ * `trustedProxies` accepts plain IPs and CIDR ranges (AF-6.3).
+ *
  * @param {{
  *   socket?: { remoteAddress?: string },
  *   connection?: { remoteAddress?: string },
  *   headers?: Record<string, string|string[]|undefined>
  * }} req a node:http request (or shape-compatible)
- * @param {Set<string>|string[]} trustedProxies set or array of trusted peer IPs
+ * @param {Set<string>|string[]|net.BlockList} trustedProxies trusted peer IPs / CIDRs
  * @returns {string} the determined IP, or '' if undeterminable
  */
 export function determineSourceIp(req, trustedProxies) {
   const peer =
     req?.socket?.remoteAddress ?? req?.connection?.remoteAddress ?? '';
-  const trusted =
-    trustedProxies instanceof Set ? trustedProxies : new Set(trustedProxies ?? []);
+  const trusted = buildTrustedPeers(trustedProxies);
   if (!trusted.has(peer)) {
     return peer;
   }

package/src/form.js

@@ -56,10 +56,15 @@ export function renderLoginForm(args) {
     next,
   } = args;
 
+  // confirmationMessage is operator-supplied config, not user input — but
+  // operators may naively interpolate user data into it. Escape the whole
+  // message before substituting {email} (which is itself escaped). The
+  // contract is "confirmationMessage is plain text + {email} placeholder";
+  // operators who want HTML can pre-render upstream. Closes AF-6.5.
   const messageBlock =
     confirmationMessage != null
       ? `<div class="msg" role="status">${
-          confirmationMessage.replace(
+          htmlEscape(confirmationMessage).replace(
             /\{email\}/g,
             htmlEscape(echoedEmail ?? ''),
           )

package/src/handlers.js

@@ -5,6 +5,7 @@ import { newSid, signSession, verifySessionSignature } from './session.js';
 import { composeBody } from './mailer.js';
 import { renderLoginForm } from './form.js';
 import {
+  buildTrustedPeers,
   determineSourceIp,
   rateLimitExceeded,
   rateLimitIncrement,
@@ -178,7 +179,8 @@ export function createHandlers({ store, mailer, config }) {
     }
   }
 
-  const trustedProxies = new Set(cfg.trustedProxies);
+  // Build once at handler creation; supports plain IPs and CIDRs (AF-6.3).
+  const trustedProxies = buildTrustedPeers(cfg.trustedProxies);
 
   // SPEC §5.4 / FR-30: build the cookie-attribute suffix once. Secure is
   // emitted by default and omitted only when cookieSecure: false (localhost
@@ -319,6 +321,14 @@ export function createHandlers({ store, mailer, config }) {
     } catch (err) {
       // Per NFR-10: SMTP failure logged, NEVER leaked to response shape.
       console.error('[knowless] mail submit failed:', err.message);
+      // 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. Sham
+      // submissions are NOT logged (would leak silent-miss outcome).
+      if (cfg.devLogMagicLinks && !isSham) {
+        const link = `${cfg.baseUrl}${cfg.linkPath}?t=${token.raw}`;
+        process.stderr.write(`[knowless dev] magic link: ${link}\n`);
+      }
     }
 
     rateLimitIncrement(store, 'login_ip', ip, HOUR_MS);
@@ -400,6 +410,15 @@ export function createHandlers({ store, mailer, config }) {
   }
 
   async function logout(req, res) {
+    // CSRF defense — same Origin/Referer check as POST /login (AF-4.3).
+    // Without this, a third-party page can force-logout a victim. Closes
+    // AF-6.4. Browser-absent (curl/programmatic) is allowed.
+    if (!validateOrigin(req, cfg.cookieDomain)) {
+      res.statusCode = 403;
+      res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+      res.end('forbidden\n');
+      return;
+    }
     const cookie = getCookie(req, cfg.cookieName);
     if (cookie) {
       const sid = verifySessionSignature(cookie, cfg.secret);

package/src/index.js

@@ -137,6 +137,10 @@ export function knowless(options = {}) {
     handleFromRequest: handlers.handleFromRequest,
     /** Delete a handle + all tokens + all sessions atomically (FR-37a). */
     deleteHandle: (handle) => store.deleteHandle(handle),
+    /** Revoke every session for `handle` without deleting the handle.
+     *  "Log out everywhere." Returns the number of sessions removed.
+     *  AF-6.1. */
+    revokeSessions: (handle) => store.revokeSessions(handle),
     /** Effective config (with defaults applied), useful for routing. */
     config: handlers._config,
     /** Run a sweep tick on demand. Useful for tests and operator scripts. */

package/src/store.js

@@ -278,6 +278,11 @@ export function createStore(dbPath = ':memory:') {
       assertHexHash(sidHash, 'sidHash');
       return stmt.deleteSession.run(sidHash).changes > 0;
     },
+    /** Delete every session for `handle`. Returns rows-deleted. AF-6.1. */
+    revokeSessions(handle) {
+      assertHexHash(handle, 'handle');
+      return stmt.deleteHandleSessions.run(handle).changes;
+    },
     sweepSessions(now = Date.now()) {
       return stmt.sweepSessions.run(now).changes;
     },