knowless 1.1.1 → 1.1.3

package/CHANGELOG.md

@@ -30,6 +30,62 @@ v1.0.0 are:
 - Documentation corrections
 - Helper exports that pull existing mechanism back into the library
 
+## [1.1.3] — 2026-05-03
+
+Documentation-only release. Surfaces a partial enumeration leak
+in the default `failureRedirect` fallback that previously read as
+"Mode-A only" guidance but actually applies to every adopter.
+POST /login is built to make valid/invalid/rate-limited responses
+indistinguishable (timing equivalence, sham tokens, sham-recipient
+mailing, identical response shapes); the link-click stage extends
+that contract, but the default `failureRedirect` cascade points at
+`loginPath` (typically `/login`) — so a user clicking a sham link
+lands on a "Sign in" page and immediately knows the link was
+rejected, defeating the POST-stage work. plato wraps knowless with
+`failureRedirect: '/'` for exactly this reason. No code changes.
+
+### Documented
+
+- `GUIDE.md` Step-4 callout — replaced the narrow "Mode-A
+  heads-up" with a broader "set `failureRedirect: '/'` — it's
+  part of the silent-miss contract, not just a UX knob"
+  guidance, with the reasoning chain (POST-stage work, link-
+  click extension, leak-free landing) and the explicit opt-in
+  for adopters who want "try again" UX (`failureRedirect:
+  cfg.loginPath`). plato cited as the reference adopter.
+- `GUIDE.md` config-table row for `failureRedirect` —
+  expanded the cell to lead with the silent-miss framing
+  rather than the Mode-A 404 framing.
+- `knowless.context.md` `failureRedirect` comment in the
+  options block — flagged the default as a leak, pointer to
+  the new gotcha.
+- `knowless.context.md` gotcha #20 — full silent-miss
+  contract write-up with the trade-off and reference adopter.
+
+## [1.1.2] — 2026-05-03
+
+Documentation-only release. Adopters were repeatedly missing that
+`auth.loginForm` is an unstyled contract-minimal fallback they
+should override, and that `/login` is also where every silent-miss
+failure (used / expired / sham / malformed token) redirects — so
+the page deserves first-class UI in the host app, not the bundled
+default. No code changes.
+
+### Documented
+
+- `GUIDE.md` FAQ — added section "Branding the GET /login page
+  (you almost certainly want to override it)" with the three
+  reasons (brand consistency, silent-miss redirect target, opt-in
+  fallback) and the override pattern. Extended the existing
+  custom-form contract with `next` validation against
+  `baseUrl` + `cookieDomain` and the optional honeypot field name
+  from `cfg.honeypotFieldName`.
+- `knowless.context.md` gotcha #10 — expanded the "operators
+  wanting branding fork the project" note to surface the more
+  common path (skip mounting `auth.loginForm`, serve your own
+  `GET /login`) and call out that `/login` is the silent-miss
+  redirect target.
+
 ## [1.1.1] — 2026-05-02
 
 Documentation-only release. Adds the wrong-shape-integration

package/GUIDE.md

@@ -384,12 +384,25 @@ and `startLogin` would compute. The bare `deriveHandle` re-export
 takes pre-normalized input; use the instance method unless you
 have a specific reason to call the lower-level primitive.
 
-> **Mode-A heads-up: set `failureRedirect`.** If you only mount
-> `auth.callback` (not `auth.loginForm`), the default
-> `failureRedirect` cascade points at `/login` — a route you
-> don't serve. An expired or replayed magic-link click will 302
-> to a 404. Set `failureRedirect: '/'` (or any route you do
-> serve) when wiring Mode A.
+> **Set `failureRedirect: '/'` — it's part of the silent-miss
+> contract, not just a UX knob.** The default falls back to
+> `loginPath` (typically `/login`). That's a partial enumeration
+> leak: `POST /login` goes to significant lengths to make
+> valid/invalid/rate-limited submissions indistinguishable
+> (timing equivalence, sham tokens, sham-recipient mailing,
+> identical response shapes) — but if a user clicks a sham or
+> expired magic link and lands on a "Sign in" page, they
+> immediately know the link was rejected, defeating the work the
+> POST stage did. The leak-free landing is the same page any
+> logged-out visitor sees on first arrival — usually `/`. Mode-A
+> adopters have an extra reason: the default `failureRedirect`
+> cascade points at `/login`, a route Mode A doesn't serve, so
+> expired/replayed clicks 302 to a 404. Reference: plato wraps
+> knowless with `failureRedirect: '/'` for this reason.
+> Adopters who genuinely want a "try again" UX after failure
+> can opt in explicitly with `failureRedirect: cfg.loginPath`,
+> but understand you're trading the silent-miss guarantee at
+> the link-click stage for that UX.
 
 ### Step 5: Pre-seed users (closed-registration mode, default)
 
@@ -808,7 +821,7 @@ Full options table:
 | `trustedProxies` | no | `['127.0.0.1', '::1']` | IPs allowed to set `X-Forwarded-For`. |
 | `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. |
+| `failureRedirect` | no | (= `loginPath`) | Where /auth/callback failures (expired / used / sham / malformed token) redirect. **Set this to `'/'` (or any logged-out landing).** Default falls back to `loginPath`, which is a silent-miss leak: a user who clicks a sham/expired link and lands on a "Sign in" page knows the link was rejected, defeating the anti-enumeration work done at POST /login. Part of the silent-miss contract, not a UX knob. Mode-A adopters who don't mount `loginForm` *also* hit a 404 with the default. Opt back into the "try again" UX by passing `loginPath` explicitly if you understand the trade. |
 | `store` | no | (built-in `node:sqlite`) | Inject your own store implementation. |
 | `mailer` | no | (built-in nodemailer) | Inject your own mailer. |
 
@@ -929,7 +942,48 @@ own form, provided it satisfies the handler contract:
   stream itself. A body-parser middleware mounted before `auth.login`
   will silently steal the data (see gotcha #15 in
   [`knowless.context.md`](knowless.context.md)).
-- Optional: include a `next` field for the post-callback redirect URL.
+- Optional: include a `next` field for the post-callback redirect URL
+  (knowless validates `next` against `baseUrl` + `cookieDomain`).
+- Optional but recommended: include the honeypot field using the name
+  from `cfg.honeypotFieldName`.
+
+### Branding the GET /login page (you almost certainly want to override it)
+
+Knowless ships `auth.loginForm(req, res)` as a turnkey fallback so
+adopters can wire `GET /login` in one line and have a working magic-link
+form. The page is intentionally unstyled — it's the contract-minimal
+renderer needed to make the flow demonstrable, not a UI you ship to
+end users. Three reasons most adopters override it:
+
+1. **Brand consistency.** The fallback page has no header, footer, nav,
+   or styling, so users redirected here from elsewhere in your app land
+   on what looks like a different site. That's especially jarring after
+   a sham-token failure (a deliberate part of the silent-miss design —
+   see "Silent miss" in [`knowless.context.md`](knowless.context.md)),
+   where a user clicked a magic link and ended up on a "Sign in" page
+   that looks unrelated to where they started.
+2. **`/login` is load-bearing in the silent-miss contract.** Knowless
+   redirects to `loginPath` on every failure mode that must be
+   indistinguishable from success — used token, expired token, sham
+   token, malformed token. That redirect is correct and required. But
+   it means `/login` is the page users actually land on during
+   anti-enumeration failures, not just the page they navigate to
+   deliberately. It deserves first-class UI in your app.
+3. **`auth.loginForm` is opt-in, not opt-out.** Adopters who never wire
+   the GET route still get a working app — just without a friendly
+   `/login` page. Override it whenever you want your app's chrome on
+   the page. The POST handler can stay as-is (or also be wrapped — for
+   example, plato wraps it for the "we sent a link" confirmation).
+
+Override pattern (mount your own handler instead of `auth.loginForm`):
+
+```js
+app.get('/login', (req, res) => renderMyOwnLogin(req, res));
+app.post('/login', auth.login);  // unchanged
+```
+
+The form just needs to satisfy the contract listed in the previous
+question.
 
 ### How do I add 2FA / WebAuthn / TOTP?
 

package/knowless.context.md

@@ -114,7 +114,7 @@ const auth = knowless({
   linkPath:   '/auth/callback',
   verifyPath: '/verify',
   logoutPath: '/logout',
-  failureRedirect: null,              // null → loginPath
+  failureRedirect: null,              // null → loginPath (LEAK — set '/'; see gotcha #20)
 
   // --- Mail / SMTP ---
   smtpHost: 'localhost',
@@ -699,7 +699,13 @@ rate-limits) belongs above the library.
 10. **No JavaScript in any HTML page.** The login form, the
     confirmation page, error pages — all static HTML5. Works in
     text-mode browsers (Lynx, w3m). Operators wanting branding
-    fork the project.
+    fork the project — **or, more commonly, skip mounting
+    `auth.loginForm` and serve their own `GET /login`**. The
+    fallback is intentionally a contract-minimal renderer, not a
+    UI to ship. `/login` is also where every silent-miss failure
+    redirects (used / expired / sham / malformed token), so it
+    deserves first-class chrome in the host app. See GUIDE.md
+    § "Branding the GET /login page".
 
 11. **Process cleanup matters.** `auth.close()` stops the
     sweeper and closes the SQLite handle. Without it, your
@@ -764,6 +770,24 @@ rate-limits) belongs above the library.
     return shape. Don't wrap `startLogin` in something that surfaces
     the branch to the caller; that re-opens the enumeration oracle.
 
+20. **`failureRedirect` is part of the silent-miss contract.**
+    Default falls back to `loginPath` — a partial enumeration
+    leak. POST /login goes to significant lengths to keep
+    valid/invalid/rate-limited submissions indistinguishable
+    (timing, sham tokens, sham-recipient mailing, identical
+    response shapes), and the link-click stage extends that
+    contract: real tokens issue a session + redirect to
+    `nextUrl`; failures (expired, used, sham, malformed) go to
+    `failureRedirect`. If that's `/login`, a user who clicks a
+    sham link lands on a "Sign in" page and immediately knows
+    the link was rejected — defeating the POST-stage work. Set
+    `failureRedirect: '/'` (or any route a logged-out visitor
+    would see on first arrival) so a sham click is
+    indistinguishable from a never-clicked link. Adopters who
+    genuinely want a "try again" UX after failure opt back in
+    explicitly with `failureRedirect: cfg.loginPath`. plato is
+    the reference adopter for the leak-free wiring.
+
 ## Constraints
 
 - **Node 20+** -- targeting LTS; tested on Node 22

package/package.json

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