knowless 1.1.2 → 1.1.4

package/CHANGELOG.md

@@ -30,6 +30,90 @@ v1.0.0 are:
 - Documentation corrections
 - Helper exports that pull existing mechanism back into the library
 
+## [1.1.4] — 2026-05-08
+
+Documentation + small bug fix. Adopters (plato, addypin, bareagent,
+bareguard) repeatedly filed feature requests for things knowless
+already shipped (`onTransportFailure` since v0.2.1) or deliberately
+refuses (vendor SMTP, built-in DKIM). Triage showed a single root
+cause: `README.md` under-routed adopters to `GUIDE.md`, `OPS.md`,
+and PRD §16, so adopters read the README and assumed gaps. Pair
+with one bug fix: the legacy `console.error('[knowless] mail submit
+failed:', ...)` in `src/handlers.js` fired alongside
+`onTransportFailure` and actively misled adopters into thinking no
+callback existed.
+
+### Fixed
+
+- `src/handlers.js` — removed the duplicate `console.error` on SMTP
+  submission failure. The `onTransportFailure` hook is now the only
+  reporting path, with the default impl preserving stderr behaviour
+  (see below). Adopters who wired `onTransportFailure` previously
+  saw the same failure logged twice (once via stderr, once via
+  their hook); they now see it once via their hook.
+- `src/index.js` — `onTransportFailure` default changed from a
+  no-op to a stderr printer (`[knowless] mail submit failed:
+  <message>`). Preserves NFR-10 ("SMTP delivery failures MUST be
+  logged") for adopters who don't wire the hook. Adopters who
+  explicitly want silence pass `onTransportFailure: () => {}`.
+  *Behavioural note:* adopters who were relying on the implicit
+  no-op default to suppress stderr will now see lines on transport
+  failure. Pass an explicit no-op to restore prior behaviour.
+
+### Documented
+
+- `README.md` "Where to go next" → "Required reading (before
+  integrating or filing an issue)". Reframed the routing block
+  from an optional menu to required reading, with each linked
+  doc's hook spelled out (hooks live in `GUIDE.md`, registrar
+  setup in `OPS.md` §5, refusal reasoning in PRD §16). Goal:
+  reduce the recurring "missing feature" filings that turn out to
+  be already-shipped or deliberately-refused.
+- `README.md` "What's opinionated (locked by design)" → "What
+  knowless refuses (by design)". Sharper framing — closed doors,
+  not omissions — with PRD §16.2 / §16.7 / §16.12 anchors inline so
+  adopters who want to litigate a refusal land on the reasoning,
+  not the bullet. Added the "No DKIM/SPF in the library" line
+  explicitly (was implicit before; PRD §16.7 reasoning); pointed
+  at `OPS.md` §5 for the operator-side setup.
+- `README.md` new section "Observability (wire it or be silent)" —
+  worked example of the three hooks (`onMailerSubmit`,
+  `onTransportFailure`, `onSuppressionWindow`) with the per-hook
+  threat-model framing. Previously surfaced only in `GUIDE.md`
+  Step 8, which adopters reliably missed.
+
+## [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

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. |
 

package/README.md

@@ -9,17 +9,20 @@ npm install knowless
 
 > v1.0.0 (walk-away release) | Node.js >= 22.5 | **1 production dep (nodemailer)** | Apache-2.0
 
-## Where to go next
+## Required reading (before integrating or filing an issue)
 
-Two docs live alongside this README. They serve different readers; pick
-the one that matches yours.
+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.**
 
-| You are | Read this | What's there |
-|---|---|---|
-| **A human integrating for the first time** | [`GUIDE.md`](GUIDE.md) | Step-by-step walkthrough — install, generate the secret, set up Postfix, mount handlers, both modes worked end-to-end. Configuration reference, FAQ, troubleshooting. |
-| **An AI agent, or reading in a hurry** | [`knowless.context.md`](knowless.context.md) | Dense single-file reference. Public API table, every option with defaults, 19 gotchas, lifecycle diagrams, the sham-work pattern, threat model, "what's NOT in knowless and why." Designed to fit one context window. |
-| **Deploying to a real server** | [`OPS.md`](OPS.md) | Postfix install, SPF/DKIM/PTR/DMARC, null-route, systemd, Caddy/nginx/Traefik forward-auth, MailHog dev, fail2ban, multi-process. |
-| **Tracking what changed** | [`CHANGELOG.md`](CHANGELOG.md) | Version history. |
+| 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. |
 
 ## What it does
 
@@ -86,30 +89,71 @@ Worked code for both in [`GUIDE.md`](GUIDE.md).
 | **Library mode** | Mount the five handlers (`login`, `callback`, `verify`, `logout`, `loginForm`) in your existing Node app. |
 | **Standalone server** (`npx knowless-server`) | Forward-auth gateway behind Caddy / nginx / Traefik for self-hosters gating Uptime Kuma / AdGuard / Pi-hole / Sonarr / Jellyfin / etc. One auth subdomain, SSO across services via the parent-domain cookie. |
 
-## What's opinionated (locked by design)
+## What knowless refuses (by design)
 
-Deliberate trade-offs. The library refuses, by API shape, to grow
-into them.
+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
+[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.
 - **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 OAuth / OIDC / SAML.** Different audience.
 - **No 2FA / WebAuthn / TOTP / passkeys.** Compose with a separate
   library if you need them.
 - **No admin UI.** `sqlite3 knowless.db` is the admin UI.
-- **Hardcoded login form.** No template overrides; fork or live with
-  it.
+- **Hardcoded login form.** No template overrides — PRD §16.12.
+  Fork, override the route entirely, or live with it.
 - **No telemetry, analytics, or error reporting.** No phone-home of
-  any kind.
+  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.
 
-If any of those break your case, knowless isn't the right tool. Look
-at [Lucia](https://lucia-auth.com/), [Auth.js](https://authjs.dev/),
-or commercial offerings.
+## 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.
 
 ## Operator commitments
 

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',
@@ -770,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.2",
+  "version": "1.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",

package/src/handlers.js

@@ -399,10 +399,14 @@ export function createHandlers({ store, mailer, config, events }) {
         });
       }
     } catch (err) {
-      // Per NFR-10: SMTP failure logged, NEVER leaked to response shape.
-      console.error('[knowless] mail submit failed:', err.message);
-      // v0.2.1: per-event hook for SMTP failures. Carries no identity
-      // data, safe per-event. Operator wires this to alerting.
+      // NFR-10: SMTP failure must be reported to the operator but
+      // MUST NOT leak to response shape. Reporting goes through the
+      // onTransportFailure hook only — the default impl (see
+      // index.js safeHook) writes to stderr when the adopter hasn't
+      // wired their own; an adopter who wires the hook owns the
+      // policy. The previous explicit console.error fired alongside
+      // the hook and misled adopters into thinking no callback
+      // existed.
       ev.onTransportFailure({ error: err, timestamp: Date.now() });
       // AF-6.2: dev-mode fallback. When SMTP is unreachable in local
       // development the operator otherwise has no way to obtain the magic

package/src/index.js

@@ -172,7 +172,19 @@ export function knowless(options = {}) {
   let shamCount = 0;
   let rateLimitedCount = 0;
   const onMailerSubmit = safeHook(options.onMailerSubmit, 'onMailerSubmit');
-  const onTransportFailure = safeHook(options.onTransportFailure, 'onTransportFailure');
+  // NFR-10: SMTP failures must be reported to the operator. When the
+  // adopter doesn't wire onTransportFailure, default to a stderr
+  // printer so the unwired case still satisfies NFR-10. Adopters who
+  // want programmatic alerting override; adopters who want silence
+  // pass `() => {}` explicitly.
+  const onTransportFailure = safeHook(
+    options.onTransportFailure ??
+      ((p) =>
+        process.stderr.write(
+          `[knowless] mail submit failed: ${p?.error?.message ?? p?.error ?? 'unknown'}\n`,
+        )),
+    'onTransportFailure',
+  );
   const onSuppressionWindow = safeHook(options.onSuppressionWindow, 'onSuppressionWindow');
 
   const events = {