knowless 0.1.8 → 0.1.10

package/CHANGELOG.md

@@ -7,7 +7,75 @@ Versioning is [SemVer](https://semver.org/).
 
 ## [Unreleased]
 
+- **Turnkey Docker image** (`knowless/knowless-server:0.2.x`)
+  bundling Postfix + null-route + the binary so a self-hoster
+  runs `docker compose up` and has a working auth gateway in
+  one step. Material UX win for the PRD §4.2 self-hoster
+  audience. Targeted for v0.2.0.
 - 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. Targeted for v0.2.0.
+
+## [0.1.10] — 2026-04-28
+
+addypin manual smoke continued. Two DX docs improvements; no code
+changes.
+
+### Documentation
+
+- **GUIDE: "Local development setup" section (AF-16).** Covers the
+  five flags that turn knowless from "production-tuned, defensive"
+  to "developer-friendly, get-out-of-my-way" — `cookieSecure: false`,
+  `devLogMagicLinks: true`, `maxLoginRequestsPerIpPerHour: 0`,
+  `maxNewHandlesPerIpPerHour: 0`, `openRegistration: true`. Each
+  flag explained with what it solves and a sharp warning about
+  shipping it. Considered auto-disabling rate limits whenever
+  `devLogMagicLinks: true` to save typing, but rejected the
+  coupling — operators turning on `devLogMagicLinks` briefly to
+  debug a single email in prod should NOT have rate limits silently
+  dropped at the same time.
+- **GUIDE: silent-miss debug line is now promoted as a feature
+  (AF-17).** The `[knowless dev:<from>] silent-miss: handle for
+  "X" does not exist (openRegistration=false)` stderr hint
+  introduced in AF-7.2 was buried in the CHANGELOG; it now leads
+  the dev-setup section. First-time closed-reg friction was costing
+  every adopter the same ~30 min; the hint cuts that to seconds
+  but only if you know it exists.
+
+## [0.1.9] — 2026-04-28
+
+addypin manual smoke turned up one real bug, one defaults footgun,
+and one DX gap.
+
+### Fixed
+
+- **`auth.deriveHandle(email)` now normalizes the email before
+  HMAC (AF-13).** Prior versions skipped `normalize()` while
+  `auth.startLogin` and `POST /login` ran it — adopters using
+  `deriveHandle` to precompute owner-keyed lookups got silent
+  handle mismatches whenever email casing varied between
+  create-time and click-time. Symptom was "user's records
+  disappear after login," which is awful to debug. The bare
+  `deriveHandle(emailNormalized, secret)` re-export still
+  expects pre-normalized input — that contract is unchanged.
+
+### Documentation
+
+- **GUIDE flags the `failureRedirect` Mode-A footgun (AF-14).**
+  Adopters running programmatic-only (`startLogin` without
+  mounting `loginForm`) hit a default `failureRedirect = /login`
+  pointing at a route they don't serve — expired/replayed
+  magic-link clicks 302 to a 404. The GUIDE now leads with this
+  in the Mode-A walkthrough and adds a callout in the config
+  table. Default unchanged to avoid breaking Mode-B users with
+  custom paths.
+- **OPS.md §11b — MailHog dev workflow (AF-15).** `docker run
+  mailhog/mailhog`, point knowless at port 1025, inspect every
+  outgoing mail (including sham submissions) in a UI at port
+  8025. Verifies `bodyFooter`, `subjectOverride`, and the
+  URL-line-isn't-QP-soft-broken invariant without spinning up
+  real Postfix.
 
 ## [0.1.8] — 2026-04-28
 

package/GUIDE.md

@@ -62,8 +62,8 @@ built-in auth is either missing or weak. The existing alternatives
 (Authelia, Authentik, Keycloak, oauth2-proxy) are heavyweight for
 the job: "redirect to login if no cookie, otherwise let through."
 
-knowless's standalone server (v0.2.0, in development) sits behind
-Caddy / nginx / Traefik via forward-auth. One auth subdomain, one
+knowless's standalone server (`bin/knowless-server`, shipped in
+v0.1.3) sits behind Caddy / nginx / Traefik via forward-auth. One auth subdomain, one
 session cookie scoped to the parent eTLD+1, SSO across all your
 services for free.
 
@@ -106,7 +106,7 @@ nothing else*.
 - **Walks away at v1.0.0.** Maintenance mode (security patches +
   bug fixes) after that, by design.
 
-## Walkthrough: library mode (v0.1.0)
+## Walkthrough: library mode
 
 The shape: import `knowless`, configure it, mount the handlers on
 your HTTP framework.
@@ -175,7 +175,9 @@ sending domain):
 Without all three, Gmail / Outlook will silently drop your auth
 mail. This is the operator commitment knowless asks of you.
 
-> Full Postfix walkthrough lives in `OPS.md` (shipping with v0.2.0).
+> Full Postfix walkthrough lives in [`OPS.md`](OPS.md) — Postfix
+> install, null-route, SPF/DKIM/PTR, systemd, reverse-proxy
+> forward-auth examples, multi-process deployments.
 
 ### Step 4: Mount the handlers
 
@@ -295,7 +297,19 @@ callers. See SPEC §7.3a for the full contract.
 
 `auth.deriveHandle(email)` returns the same opaque HMAC handle
 that the form path uses, without you having to import the helper
-or pass the secret around.
+or pass the secret around. The instance method **normalizes the
+email** (lowercase, trim) before HMAC (AF-13), so `Alice@X.com`
+and `alice@x.com` produce the same handle — match what the form
+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.
 
 ### Step 5: Pre-seed users (closed-registration mode, default)
 
@@ -384,6 +398,59 @@ reverse proxy gates upstreams via `/verify` returning 200/401 +
 `handleFromRequest` — same answer, no sub-request round-trip, no
 header parsing.
 
+### Local development setup
+
+Production defaults are tuned to bite bots, not to be friendly to a
+developer hammering the same address from `127.0.0.1` for the
+hundredth time. Use a dedicated dev config:
+
+```js
+const auth = knowless({
+  // ...required fields
+  cookieSecure: false,             // localhost-only HTTP origins (AF-4.4)
+  devLogMagicLinks: true,          // print magic links to stderr when SMTP fails (AF-6.2)
+  maxLoginRequestsPerIpPerHour: 0, // disable per-IP login cap
+  maxNewHandlesPerIpPerHour: 0,    // disable per-IP create cap
+  openRegistration: true,          // skip the pre-seeding step in dev
+});
+```
+
+Why each flag matters in dev:
+
+- **`cookieSecure: false`** — without it, `http://localhost` browsers
+  reject the session cookie silently. The library logs a stderr
+  warning at startup so you can't accidentally ship this to prod.
+- **`devLogMagicLinks: true`** — when SMTP is unreachable (no local
+  Postfix yet), magic-link URLs print to stderr tagged
+  `[knowless dev:<from>] magic link: ...`. Click straight from the
+  terminal. **Bonus diagnostic** (AF-7.2): on a sham/silent-miss
+  path, you get `[knowless dev:<from>] silent-miss: handle for
+  "X" does not exist (openRegistration=false)` instead — surfaces
+  the closed-reg gotcha that costs everyone the same 30 minutes
+  the first time.
+- **`maxLoginRequestsPerIpPerHour: 0` and `maxNewHandlesPerIpPerHour:
+  0`** — disable per-IP rate caps. The defaults (30 / 3 per hour)
+  are sane for prod but shoot you in the foot during repeated test
+  runs. The counters **persist in the SQLite file** across process
+  restarts, so even rebooting the dev server doesn't clear them —
+  you'd have to delete the DB or wait an hour. Setting both to 0
+  in dev avoids the surprise.
+- **`openRegistration: true`** — saves you from manually pre-seeding
+  every test email via `auth.deriveHandle` + your own store insert.
+
+> **Don't ship this config.** Each of these flags weakens a specific
+> defense. They are coupled to your environment, not to each other —
+> intentionally. (We considered auto-disabling rate limits whenever
+> `devLogMagicLinks` is true, but rejected: an operator turning on
+> `devLogMagicLinks` to debug a single email in production should
+> NOT have rate limits silently dropped at the same time.)
+
+For end-to-end mail rendering checks (verify the `bodyFooter`,
+inspect the magic-link line for QP soft-breaks, confirm the
+right `subjectOverride` shipped), point dev knowless at MailHog
+on `localhost:1025`. Setup walkthrough lives in
+[`OPS.md` §11b](OPS.md).
+
 ### Step 7: GDPR right-to-erasure
 
 The store interface exposes `deleteHandle(handle)` — atomic delete
@@ -402,11 +469,10 @@ Library doesn't ship a built-in HTTP endpoint for this — operator
 chooses the UX (admin CLI, in-app self-service, ticket-driven
 support).
 
-## Walkthrough: standalone server mode (v0.2.0, coming)
+## Walkthrough: standalone server mode
 
-The shape: run `npx knowless-server`, point Caddy / nginx /
-Traefik at it for forward-auth, protect any HTTP service behind
-magic-link login.
+Run `npx knowless-server`, point Caddy / nginx / Traefik at it for
+forward-auth, protect any HTTP service behind magic-link login.
 
 The deployment-shape pattern:
 ```
@@ -418,7 +484,9 @@ The deployment-shape pattern:
                 [Caddy redirects to auth.example.com/login?next=...]
 ```
 
-Sample Caddyfile (forthcoming OPS.md will have the full setup):
+Sample Caddyfile (full setup including TLS/ACME + multiple gated
+services lives in [`OPS.md`](OPS.md) §7):
+
 ```caddy
 auth.example.com {
     reverse_proxy localhost:8080
@@ -427,7 +495,7 @@ auth.example.com {
 kuma.example.com {
     forward_auth localhost:8080 {
         uri /verify
-        copy_headers X-User-Handle
+        copy_headers X-Knowless-Handle
     }
     reverse_proxy localhost:3001  # Uptime Kuma
 }
@@ -435,7 +503,7 @@ kuma.example.com {
 adguard.example.com {
     forward_auth localhost:8080 {
         uri /verify
-        copy_headers X-User-Handle
+        copy_headers X-Knowless-Handle
     }
     reverse_proxy localhost:3000  # AdGuard Home
 }
@@ -444,9 +512,11 @@ adguard.example.com {
 One auth subdomain, one cookie, SSO across all gated services
 because the cookie is scoped to the parent eTLD+1.
 
-Until v0.2.0, you can replicate this yourself with ~30 lines of
-`node:http` wrapping the library-mode handlers — see
-`knowless.context.md` for the pattern.
+Configuration is via `KNOWLESS_*` env vars — see
+[`config.example.env`](config.example.env) and run
+`knowless-server --help` for the full list. `knowless-server
+--config-check` validates your env, SMTP reachability, and DB
+write access; suitable for systemd `ExecStartPre`.
 
 ## Configuration reference
 
@@ -479,7 +549,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. |
+| `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. |
 | `store` | no | (built-in better-sqlite3) | Inject your own store implementation. |
 | `mailer` | no | (built-in nodemailer) | Inject your own mailer. |
 

package/OPS.md

@@ -589,6 +589,54 @@ want for forward-auth-style deployments anyway.
 
 ---
 
+## 11b. Local development without a real Postfix
+
+Spinning up Postfix on a developer laptop just to inspect what
+knowless sends is heavy. Two leaner options:
+
+### Option A — `devLogMagicLinks: true` (no MTA needed)
+
+knowless already supports this for the URL. When SMTP submission
+fails AND `devLogMagicLinks: true` is set, the magic link is
+printed to stderr tagged `[knowless dev:<from>]`. Sufficient for
+smoke-testing the click flow, not the email content. AF-6.2.
+
+### Option B — MailHog (visual UI for the rendered mail)
+
+For verifying subject/body/footer rendering or the timing of
+sham-vs-real submissions, run [MailHog](https://github.com/mailhog/MailHog)
+or any compatible test SMTP catcher (e.g. mailpit, smtp4dev) on
+the dev machine and point knowless at it.
+
+```sh
+# Docker one-liner for MailHog
+docker run --rm -p 1025:1025 -p 8025:8025 mailhog/mailhog
+```
+
+Then in your dev knowless config:
+
+```js
+const auth = knowless({
+  secret: process.env.KNOWLESS_SECRET,
+  baseUrl: 'http://localhost:3000',
+  from: 'auth@dev.local',
+  smtpHost: 'localhost',
+  smtpPort: 1025,         // MailHog's SMTP port
+  cookieSecure: false,    // localhost-only dev
+});
+```
+
+Open `http://localhost:8025` in your browser; every magic-link mail
+(including sham submissions to `null@knowless.invalid`) shows up in
+the inbox UI with full subject/body/headers visible. Perfect for
+verifying `bodyFooter`, `subjectOverride`, the URL line is intact
+without QP soft-breaks, etc.
+
+> Don't ship MailHog into production. It accepts mail from anywhere
+> and stores it forever — defeats the entire knowless threat model.
+
+---
+
 ## 12. Backup and recovery
 
 The only stateful file is the SQLite database (`KNOWLESS_DB_PATH`,

package/README.md

@@ -7,7 +7,7 @@ that don't need to email their users for anything but the sign-in link.
 npm install knowless
 ```
 
-> v0.1.8 | Node.js >= 20 | 2 deps (nodemailer, better-sqlite3) | Apache-2.0
+> v0.1.10 | Node.js >= 20 | 2 deps (nodemailer, better-sqlite3) | Apache-2.0
 
 ## What this is
 

package/knowless.context.md

@@ -1,7 +1,7 @@
 # knowless -- Integration Guide
 
 > For AI assistants and developers wiring knowless into a project.
-> v0.1.0 | Node.js >= 20 | 2 deps (nodemailer, better-sqlite3) | Apache-2.0
+> v0.1.10 | Node.js >= 20 | 2 deps (nodemailer, better-sqlite3) | Apache-2.0
 
 ## What this is
 
@@ -18,11 +18,13 @@ npm install knowless
 
 Two integration paths:
 
-1. **Library mode (v0.1.0):** `import { knowless } from 'knowless'` --
-   mount five handlers on Express / Fastify / Hono / `node:http`
-2. **Standalone server (v0.2.0, in development):** `npx knowless-server` --
-   forward-auth gateway for Caddy / nginx / Traefik in front of
-   no-auth services like Uptime Kuma, AdGuard, Pi-hole
+1. **Library mode:** `import { knowless } from 'knowless'` --
+   mount five handlers on Express / Fastify / Hono / `node:http`,
+   gate your endpoints with `auth.handleFromRequest(req)`.
+2. **Standalone server:** `npx knowless-server` -- forward-auth
+   gateway for Caddy / nginx / Traefik in front of no-auth services
+   like Uptime Kuma, AdGuard, Pi-hole. Configured via `KNOWLESS_*`
+   env vars; see [`OPS.md`](OPS.md) for the full deployment guide.
 
 This document is the dense reference. For the why, see
 `docs/01-product/PRD.md`. For the wire formats, see
@@ -148,7 +150,7 @@ const auth = knowless({
 | `deleteHandle` | (handle: string) | void | Atomic delete of handle + tokens + sessions (FR-37a, GDPR) |
 | `revokeSessions` | (handle: string) | number | Drops every session for `handle` without deleting the account ("log out everywhere"). Returns rows removed. AF-6.1. |
 | `startLogin` | ({email, nextUrl?, sourceIp?, subjectOverride?, bypassRateLimit?}) | Promise\<{handle, submitted: true}\> | Programmatic magic-link send for "use first, claim later" flows. Same 12-step sham-work as form. `subjectOverride` (AF-9) replaces `cfg.subject` per call. `bypassRateLimit: true` (AF-10) opts trusted server-side callers (CLI, cron, worker) out of IP-rate-limit accounting. SPEC §7.3a. AF-7.3. |
-| `deriveHandle` | (email: string) | string | HMAC-SHA256(secret, normalize(email)) using the configured secret. Use to compute owner-handles outside HTTP context. AF-7.4. |
+| `deriveHandle` | (email: string) | string | `HMAC-SHA256(secret, normalize(email))` using the configured secret. Normalizes input (lowercase + trim) so `Alice@X.com` and `alice@x.com` produce the same handle. Match what `startLogin` and `POST /login` compute. AF-7.4 / AF-13. |
 | `_sweep` | -- | void | Trigger one sweep tick on demand (tests, operator scripts). AF-5.3. |
 | `config` | -- | object | Merged effective config; safe to read (do not mutate) |
 | `close` | -- | void | Stops sweeper, closes mailer + store. Call on shutdown. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "knowless",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "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/index.js

@@ -1,7 +1,7 @@
 import { createStore } from './store.js';
 import { createMailer, validateBodyFooter } from './mailer.js';
 import { createHandlers } from './handlers.js';
-import { deriveHandle as deriveHandleRaw } from './handle.js';
+import { deriveHandle as deriveHandleRaw, normalize } from './handle.js';
 
 /** Default sweeper tick: 5 minutes. Per FR-13. */
 const DEFAULT_SWEEP_INTERVAL_MS = 5 * 60 * 1000;
@@ -153,9 +153,12 @@ export function knowless(options = {}) {
      *  See SPEC §7.3a. AF-7.3. */
     startLogin: handlers.startLogin,
     /** Derive the opaque handle for an email using the configured
-     *  secret. Lets adopters compute owner-handles outside HTTP context
-     *  without spreading the secret across modules. AF-7.4. */
-    deriveHandle: (email) => deriveHandleRaw(email, options.secret),
+     *  secret. Normalizes the email first (AF-13) so handles match
+     *  what `auth.startLogin` and `POST /login` would compute for the
+     *  same address typed with different casing or surrounding
+     *  whitespace. Adopters should treat this as the canonical handle
+     *  derivation. AF-7.4 / AF-13. */
+    deriveHandle: (email) => deriveHandleRaw(normalize(email), options.secret),
     /** Effective config (with defaults applied), useful for routing. */
     config: handlers._config,
     /** Run a sweep tick on demand. Useful for tests and operator scripts. */