knowless 1.1.5 → 1.1.8

package/CHANGELOG.md

@@ -30,6 +30,121 @@ v1.0.0 are:
 - Documentation corrections
 - Helper exports that pull existing mechanism back into the library
 
+## [1.1.8] — 2026-05-22
+
+Documentation-only release. A security review found the forward-auth
+proxy recipes told operators to copy an identity header
+(`X-Knowless-Handle`) that knowless never sets — the handler, SPEC
+§9.2, the `knowless.context.md` API table, and the integration test
+all use `X-User-Handle`. The recipes were the lone outliers. Effect
+in a real deployment: the verified handle never reaches the upstream
+(broken identity propagation), and because the auth response carries
+no header to copy, a client-supplied `X-User-Handle` is not
+overwritten by the recipe — depending on the proxy's copy semantics
+that is an impersonation path. Corrected the recipes to the canonical
+name and documented the trust boundary so the class can't silently
+reopen. No code changes; the public contract (`X-User-Handle`) was
+already correct and stays unchanged.
+
+### Fixed
+
+- `OPS.md` §7, `GUIDE.md` §forward-auth — corrected the identity
+  header in every Caddy / nginx / Traefik recipe from
+  `X-Knowless-Handle` to `X-User-Handle` (6 references, including the
+  nginx `$upstream_http_x_user_handle` variable). Now matches
+  `src/handlers.js`, `docs/02-design/SPEC.md` §9.2, and the
+  `knowless.context.md` API table.
+
+### Documented
+
+- `OPS.md` §7, `knowless.context.md` § "Forward-auth" — added an
+  "Identity-header trust boundary" note: the proxy must overwrite or
+  strip any client-supplied `X-User-Handle` (never append), and the
+  upstream should reject the header from any source but the proxy.
+  This is the load-bearing forward-auth invariant; making it explicit
+  guards against a future name drift re-introducing the gap.
+- `OPS.md` §1, `docs/01-product/PRD.md` §10.1 — corrected the runtime
+  floor from "Node.js ≥ 20" to "≥ 22.5". The `node:sqlite`
+  (`DatabaseSync`) import hard-crashes below 22.5; `engines.node`,
+  README, `knowless.context.md`, GUIDE, and PRD §16.4 already stated
+  22.5, so §10.1 and the OPS prerequisite were the stale outliers.
+
+## [1.1.7] — 2026-05-11
+
+Documentation-only release. Threat-model wording was being read as
+an oversight rather than a principled boundary — adopters kept
+returning to compromised-inbox scenarios because the README didn't
+lead with the load-bearing fact (the inbox is the trust root, by
+construction, in any email-based auth system). Tightened that
+paragraph, recorded the same-browser-binding decision in the §16
+decisions log so it doesn't have to be relitigated, and added a
+fourth entry under `knowless.context.md` § "What's NOT" with a
+~15-line adopter recipe for adopters who genuinely want the
+defense. No code changes.
+
+### Documented
+
+- `README.md` — tightened the threat-model paragraph. Added a
+  leading sentence stating that email-based magic links are
+  exactly as strong as the user's mailbox (the inbox is the
+  trust root, by construction). Promoted "compromised email
+  accounts" to first position in "Does NOT defend against" with
+  a parenthetical explaining the magic link is a bearer token.
+- `knowless.context.md` — added a fourth entry under "What's NOT
+  in knowless, and why": same-browser binding for magic links.
+  Documents why the library refuses to ship the defense
+  (§16.14 threat-model boundary, cross-device UX cost) and
+  provides a ~15-line adopter recipe using the `next_url`
+  round-trip + a state cookie. Mechanism in adopter, no library
+  change.
+- `docs/01-product/PRD.md` §16.21 — recorded the same-browser-
+  binding decision in the §16 decisions log so the doctrine
+  survives the next agent who proposes it. Cross-references
+  §16.14 (honest threat model) as the load-bearing precedent.
+- `CLAUDE.md` — bumped the §16 entry count (20 → 21) so the
+  pointer stays accurate.
+
+## [1.1.6] — 2026-05-09
+
+Documentation-only release. README was routing adopters into
+internal-only docs (PRD §16) for the "why we refuse X" rationale,
+which collapsed two audiences (adopters reading the README;
+agents/contributors litigating design decisions) into one trail.
+PRD isn't shipped via npm anyway, so npm consumers clicking those
+links got dead repo-relative paths. Restructured the README as a
+self-contained explainer (philosophy → mechanism → modes →
+deployment shapes → refusals → operator commitments → threat model
+→ adopters → going-further footer) and moved the deeper refusal
+rationale into a new repo-root `CLAUDE.md` for future agents
+working on the library. No code changes.
+
+### Documented
+
+- `README.md` — dropped the "Required reading" routing table that
+  pointed adopters at internal docs (PRD, knowless.context.md).
+  Five `PRD §16.x` references in the refusals bullets replaced with
+  inline one-liner reasoning. "Hardcoded login form" bullet now
+  carries a brief inline reason ("templating is a slope") in place
+  of the `PRD §16.12` pointer. Detailed observability code block
+  removed — the philosophy stays as a refusals bullet ("wire it or
+  be silent"), the worked example lives in `GUIDE.md`. Threat model
+  paragraph trimmed (removed trailing `knowless.context.md`
+  pointer). New "Going further" footer at the end pointing at
+  `GUIDE.md`, `OPS.md`, `CHANGELOG.md`. Walk-away bullet now
+  mirrors the four PRD §6.3 carve-outs verbatim.
+- `CLAUDE.md` (new, repo-root, **not shipped via npm**) — agent
+  context with the walk-away doctrine, two-test lens for "should X
+  go in knowless," README-discoverability triage for adopter
+  feature requests, the most-litigated refusals (each with its PRD
+  §16 anchor for long-form reasoning), pointers to PRD / SPEC /
+  TASKS / AGENT_RULES, the decision-revisit protocol, and a
+  condensed code-standards block.
+- `knowless.context.md` — dropped the bare `(PRD §16.2)`
+  parenthetical from the Postfix-on-localhost gotcha. The inline
+  reasoning that follows ("vendor mailers invite 'while we're at
+  it'…") carries the same point without routing readers into a
+  doc that isn't shipped.
+
 ## [1.1.5] — 2026-05-09
 
 Documentation-only release. plato (Mode A adopter) hit a real seam

package/GUIDE.md

@@ -799,7 +799,7 @@ auth.example.com {
 kuma.example.com {
     forward_auth localhost:8080 {
         uri /verify
-        copy_headers X-Knowless-Handle
+        copy_headers X-User-Handle
     }
     reverse_proxy localhost:3001  # Uptime Kuma
 }
@@ -807,7 +807,7 @@ kuma.example.com {
 adguard.example.com {
     forward_auth localhost:8080 {
         uri /verify
-        copy_headers X-Knowless-Handle
+        copy_headers X-User-Handle
     }
     reverse_proxy localhost:3000  # AdGuard Home
 }

package/OPS.md

@@ -19,7 +19,7 @@ delegate email to a SaaS, knowless is the wrong tool.
   - 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
+- Node.js ≥ 22.5 installed (`node:sqlite` requires this floor)
 - A reverse proxy in front of HTTP (Caddy, nginx, or Traefik)
 
 knowless does not handle TLS termination. Your reverse proxy does.
@@ -304,6 +304,20 @@ 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`.
 
+**Identity-header trust boundary.** On success `/verify` returns
+`200` with `X-User-Handle: <handle>`. The proxy copies that header
+onto the request it forwards to the protected upstream, and the
+upstream trusts it as the authenticated identity. This only holds if
+the value the upstream sees is the one knowless set — so the proxy
+**must overwrite (or strip) any client-supplied `X-User-Handle`**, never
+merely append to it. The recipes below do this (`proxy_set_header` in
+nginx replaces; `copy_headers` / `authResponseHeaders` replace from
+the auth response). If you adapt them, confirm a request sent with a
+forged `X-User-Handle:` header reaches the upstream with the value
+*replaced*, not duplicated — a duplicate the upstream reads first is a
+full impersonation bypass. Defense in depth: have the upstream reject
+the header from any source other than the proxy.
+
 ### 7.1 Caddy
 
 ```caddy
@@ -315,7 +329,7 @@ auth.example.com {
 kuma.example.com {
     forward_auth 127.0.0.1:8080 {
         uri /verify
-        copy_headers X-Knowless-Handle
+        copy_headers X-User-Handle
     }
     reverse_proxy 127.0.0.1:3001
 }
@@ -363,8 +377,8 @@ server {
 
     location / {
         auth_request /_knowless_verify;
-        auth_request_set $handle $upstream_http_x_knowless_handle;
-        proxy_set_header X-Knowless-Handle $handle;
+        auth_request_set $handle $upstream_http_x_user_handle;
+        proxy_set_header X-User-Handle $handle;
         proxy_pass http://127.0.0.1:3001;
     }
 }
@@ -379,7 +393,7 @@ http:
     knowless:
       forwardAuth:
         address: "http://127.0.0.1:8080/verify"
-        authResponseHeaders: [ "X-Knowless-Handle" ]
+        authResponseHeaders: [ "X-User-Handle" ]
 
   routers:
     auth:

package/README.md

@@ -1,5 +1,10 @@
 # knowless
 
+<p align="center">
+  <img src="https://img.shields.io/github/package-json/v/hamr0/knowless?label=version&color=2a4f8c" alt="version (auto from package.json)">
+  <img src="https://img.shields.io/badge/license-Apache%202.0-2a4f8c" alt="license: Apache 2.0">
+</p>
+
 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.
 
@@ -7,22 +12,7 @@ that don't need to email their users for anything but the sign-in link.
 npm install knowless
 ```
 
-> v1.0.0 (walk-away release) | Node.js >= 22.5 | **1 production dep (nodemailer)** | Apache-2.0
-
-## Required reading (before integrating or filing an issue)
-
-This README is the front door, not the manual. Most "missing feature"
-questions about knowless turn out to be answered in the docs below —
-hooks that already exist, refusals that are deliberate, operator
-setup steps already documented. **Read these before assuming a gap.**
-
-| Read this | Why you need it |
-|---|---|
-| [`GUIDE.md`](GUIDE.md) | Integration walkthrough, **observability hooks** (`onMailerSubmit` / `onTransportFailure` / `onSuppressionWindow`), edge cases, FAQ, troubleshooting. |
-| [`OPS.md`](OPS.md) | Operator setup — Postfix install, **SPF / DKIM / PTR / DMARC at your domain registrar** (§5), null-route, systemd, Caddy/nginx/Traefik forward-auth, MailHog dev, fail2ban. |
-| [`docs/01-product/PRD.md`](docs/01-product/PRD.md) §16 | Why knowless refuses what it refuses. Decisions log — read §16.2 before asking for vendor SMTP, §16.7 before asking for built-in DKIM, §16.12 before asking for a templatable login form. |
-| [`knowless.context.md`](knowless.context.md) | Dense single-file reference for AI agents and quick lookups. Public API table, every option with defaults, 19 gotchas, threat model. Fits one context window. |
-| [`CHANGELOG.md`](CHANGELOG.md) | Version history. |
+> v1.0.0 (walk-away release) | Node.js >= 22.5 | **1 production dep (nodemailer)**
 
 ## What it does
 
@@ -31,8 +21,8 @@ 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.
 
-Most auth libraries default to maximum identity collection: full email
-in plaintext, profile fields, recovery email, federation. Even
+Most auth libraries default to maximum identity collection: full
+email in plaintext, profile fields, recovery email, federation. Even
 nominally privacy-focused options store enough that a breach is
 materially harmful. knowless inverts the default.
 
@@ -80,8 +70,6 @@ The same sham-work flow runs underneath either mode, so unknown
 emails, rate-limit hits, and real sends look identical to an external
 observer.
 
-Worked code for both in [`GUIDE.md`](GUIDE.md).
-
 ## Two deployment shapes
 
 | Shape | When |
@@ -91,69 +79,35 @@ Worked code for both in [`GUIDE.md`](GUIDE.md).
 
 ## What knowless refuses (by design)
 
-These are closed doors, not omissions. Don't file feature requests
-for them — the reasoning is locked in
-[`docs/01-product/PRD.md`](docs/01-product/PRD.md) §16. If any
-break your case, knowless isn't the right tool — look at
+These are closed doors, not omissions. If any break your case,
+knowless isn't the right tool — look at
 [Lucia](https://lucia-auth.com/), [Auth.js](https://authjs.dev/),
 or commercial offerings.
 
 - **Localhost SMTP only.** No Mailgun / Postmark / SES / Resend.
-  Reasoning: PRD §16.2 — vendor relationships invite reusing the
-  mailer for non-auth mail, which collapses the "one mail purpose"
-  invariant.
+  Vendor relationships invite reusing the mailer for non-auth mail,
+  which collapses the "one mail purpose" invariant.
 - **One mail purpose: the sign-in link.** No `sendNotification()` to
   be tempted by.
 - **Plain-text 7-bit email.** No HTML, no tracking pixels, no
   click-rewriting, no read-receipts.
-- **No DKIM/SPF in the library.** PRD §16.7 — that's the MTA's job;
-  knowless emits clean RFC822 and your Postfix + opendkim signs it.
-  Setup steps in [`OPS.md`](OPS.md) §5.
+- **No DKIM/SPF in the library.** That's the MTA's job; knowless
+  emits clean RFC822 and your Postfix + opendkim signs it.
 - **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 — PRD §16.12.
-  Fork, override the route entirely, or live with it.
+- **Hardcoded login form.** Templating is a slope — today "let me
+  put my logo," tomorrow "let me theme the page," eventually "let me
+  embed a JS framework." Fork, override the route entirely, or live
+  with it.
 - **No telemetry, analytics, or error reporting.** No phone-home of
-  any kind. (Operator-side observability is opt-in via hooks — see
-  below.)
-- **Walks away at v1.0.0.** Maintenance mode after that — only
-  security fixes.
-
-## Observability (wire it or be silent)
-
-knowless emits **three operator-visibility hooks** on the mail-send
-path. They're the only API for SMTP outcomes — there is no internal
-logging the library does on your behalf beyond an unwired-default
-stderr line on transport failure. If you want metrics, alerting, or
-an admin UI showing send results, you wire these.
-
-```js
-const auth = knowless({
-  secret, baseUrl, from,
-
-  onMailerSubmit: ({ messageId, handle, timestamp }) => {
-    // Real (non-sham) submission succeeded. Safe per-event — fires
-    // ONLY on registered handles, so no enumeration oracle.
-  },
-  onTransportFailure: ({ error, timestamp }) => {
-    // SMTP submission failed. Carries no identity data. Wire to
-    // your alerting / admin "last 10 sends" panel.
-  },
-  onSuppressionWindow: ({ sham, rateLimited, windowMs }) => {
-    // Aggregate counters for the silent-202 branches (sham + rate-
-    // limit hits). Windowed, NOT per-event — per-event would reopen
-    // the enumeration oracle that sham-work exists to prevent.
-  },
-});
-```
-
-Threat-model reasoning for why three hooks (and not a fourth
-per-event sham hook) lives in [`GUIDE.md`](GUIDE.md) Step 8 and
-`knowless.context.md` § "Why three hooks, not four". **Read it
-before logging payloads** — careless aggregation can leak handles
-into log lines.
+  any kind. Operator-side observability is opt-in via three hooks
+  (`onMailerSubmit` / `onTransportFailure` / `onSuppressionWindow`) —
+  wire them or be silent.
+- **Walks away at v1.0.0.** Maintenance mode after that — security
+  fixes, bug fixes that don't change the API surface, doc fixes,
+  helper exports.
 
 ## Operator commitments
 
@@ -165,10 +119,12 @@ By choosing knowless, you commit to running:
 - A **null-route** for the configured `shamRecipient` so silent-miss
   sham mail drops, not bounces
 
-Step-by-step in [`OPS.md`](OPS.md).
-
 ## Threat model — one paragraph
 
+Email-based magic links are exactly as strong as the user's mailbox.
+knowless can harden the auth flow; it cannot harden an inbox the user
+has already lost. The list below reflects that boundary.
+
 **Defends well:** DB-only leaks (handles are HMAC-salted),
 plaintext-email exfiltration (none persisted), password reuse (no
 passwords), silent email enumeration via the login form (timing-
@@ -182,15 +138,13 @@ whitelist).
 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 — patterns in
-[`OPS.md`](OPS.md).
-
-Full detail in [`knowless.context.md`](knowless.context.md) §
-"Threat model summary."
+**Does NOT defend against:** compromised email accounts (the magic
+link is a bearer token — anyone who can read the inbox can use it;
+defense lives at the email provider, not in this library),
+sophisticated bots that bypass the honeypot, distributed floods from
+many IPs, full server compromise, social engineering, insider threat
+at the operator. Layer-2 defences (Cloudflare, fail2ban, reverse-proxy
+rate-limits) belong above the library.
 
 ## Adopters
 
@@ -208,6 +162,15 @@ If you're picking knowless up: the addypin and gitdone callsites are
 both Mode A and good worked references for the use-first / claim-later
 shape.
 
+## Going further
+
+- [`GUIDE.md`](GUIDE.md) — integration walkthrough, observability
+  hooks, edge cases, FAQ, troubleshooting.
+- [`OPS.md`](OPS.md) — operator setup (Postfix install, SPF/DKIM/PTR/
+  DMARC at your registrar, null-route, systemd, forward-auth wiring,
+  fail2ban).
+- [`CHANGELOG.md`](CHANGELOG.md) — version history.
+
 ## License
 
 [Apache 2.0](LICENSE) with [`NOTICE`](NOTICE) preservation. Forks

package/knowless.context.md

@@ -483,6 +483,18 @@ which requires the operator secret.
 [Caddy verifies cookie via /verify, proxies to Uptime Kuma]
 ```
 
+**Identity-header trust boundary.** `/verify` returns `200` +
+`X-User-Handle: <handle>` on success; the proxy copies that header
+onto the request forwarded to the protected upstream. The header is
+trustworthy *only* because the proxy sets it from the `/verify`
+response — so your proxy config must **overwrite or strip any
+client-supplied `X-User-Handle`**, never append. nginx
+`proxy_set_header`, Caddy `copy_headers`, and Traefik
+`authResponseHeaders` all replace; if you hand-roll a config, confirm
+a request carrying a forged `X-User-Handle:` reaches the upstream with
+the value replaced (not duplicated), and have the upstream reject the
+header from any source but the proxy. Exact recipes: `OPS.md` §7.
+
 ## Custom mailer contract
 
 When you inject `options.mailer`, knowless hands off five obligations.
@@ -562,7 +574,7 @@ URL/email -> handlers.js (login: 12-step sham-work flow per SPEC §7.3)
 
 ## What's NOT in knowless, and why
 
-Three capabilities that look like they belong here but don't, listed
+Four 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.
 
@@ -611,6 +623,49 @@ requires JS in the login form (the only zero-JS exception we'd carry),
 per-IP signup actually saturating the cap, Caddy (or another perimeter
 layer) can run hashcash off-the-shelf without making knowless carry it.
 
+### Same-browser binding — adopter / landing route
+
+Refuse the magic-link click unless it lands in the browser that
+requested it. Defends against compromised inboxes (attacker reading
+the mail is by definition in a different browser → click fails).
+
+The library refuses this because §16.14 records inbox compromise as
+out-of-scope, and adding the defense would expand the threat model
+knowless promises. It also breaks legitimate cross-device flows
+(request on phone, click on desktop) that many users rely on. PRD
+§16.21 has the full reasoning.
+
+Adopters who genuinely want it can do it in ~15 lines, no knowless
+change:
+
+```js
+// At /login submission, before forwarding to knowless:
+const bind = crypto.randomBytes(16).toString('hex');
+res.setHeader('Set-Cookie',
+  `app_bind=${bind}; HttpOnly; Secure; SameSite=Lax; Path=/; Max-Age=900`);
+const bindHash = crypto.createHash('sha256').update(bind).digest('hex');
+req.body.next = `${baseUrl}/post-login?b=${bindHash}`;
+// → forward to knowless's loginHandler; next_url round-trips through
+//   the token row and lands at /post-login after consume.
+
+// At /post-login (your route, after knowless set the session cookie):
+const cookieBind = getCookie(req, 'app_bind');
+const expected = req.query.b;
+if (!cookieBind ||
+    crypto.createHash('sha256').update(cookieBind).digest('hex') !== expected) {
+  // Different browser → kill the session knowless just minted.
+  res.setHeader('Set-Cookie', 'knowless_session=; Max-Age=0; Path=/');
+  return res.redirect('/login?error=different_browser');
+}
+res.redirect('/');
+```
+
+Mechanism (cookie + hash round-trip) is generic. Policy (refuse, warn,
+require step-up) is the adopter's call. UX recovery ("click the link
+in the same browser you requested it from") is adopter copy.
+Splitting it this way keeps the knowless contract honest while letting
+adopters who accept the cross-device UX cost have the defense.
+
 ### The deciding lens
 
 knowless walks away at v1.0.0 (PRD §6.3). Every config option carried
@@ -649,10 +704,9 @@ rate-limits) belongs above the library.
 
 2. **Postfix on localhost is required.** No remote SMTP, no
    Mailgun / Postmark / SES. The localhost requirement is
-   intentional (PRD §16.2): vendor mailers invite "while we're
-   at it, let's send a welcome email," which contradicts the
-   philosophy. If you can't run Postfix, knowless isn't your
-   library.
+   intentional: vendor mailers invite "while we're at it, let's
+   send a welcome email," which contradicts the philosophy. If
+   you can't run Postfix, knowless isn't your library.
 
 3. **`shamRecipient` MUST be discarded without external delivery.**
    Default is `null@knowless.invalid`. With the default
@@ -790,7 +844,7 @@ rate-limits) belongs above the library.
 
 ## Constraints
 
-- **Node 20+** -- targeting LTS; tested on Node 22
+- **Node 22.5+** -- `node:sqlite` (`DatabaseSync`) floor; tested on Node 22
 - **Plain ES modules** -- no TypeScript source, no build step;
   ships JSDoc + (eventual) `.d.ts`
 - **One production dep** -- `nodemailer` (SMTP submission). Storage

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "knowless",
-  "version": "1.1.5",
+  "version": "1.1.8",
   "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",