knowless 1.1.6 → 1.1.8

package/CHANGELOG.md

@@ -30,6 +30,80 @@ 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

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,7 +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
+> v1.0.0 (walk-away release) | Node.js >= 22.5 | **1 production dep (nodemailer)**
 
 ## What it does
 
@@ -116,6 +121,10 @@ By choosing knowless, you commit to running:
 
 ## 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-
@@ -129,10 +138,12 @@ 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
+**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

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
@@ -789,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.6",
+  "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",