knowless 1.1.4 → 1.1.6

package/CHANGELOG.md

@@ -30,6 +30,82 @@ v1.0.0 are:
 - Documentation corrections
 - Helper exports that pull existing mechanism back into the library
 
+## [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
+under `bodyOverride`: they want to reorder the body (expiry warning
+before URL) AND keep the "Last sign-in" security signal. The current
+contract drops the line under override — deliberately, since override
+is full-content replacement — and that read as a missing capability.
+It isn't: `auth.deriveHandle(email)` and a parallel `createStore`
+handle calling `getLastLogin(handle)` already give adopters everything
+they need to compose the signal themselves. The gap was discoverability,
+not surface area. Considered exporting a `formatLastLogin` helper to
+centralize the canonical wording across adopters; held off under the
+walk-away default-no, since the population that hits the
+override + reorder + want-signal intersection is narrow (most
+`bodyOverride` uses are per-call subject branding without a sign-in
+event), and the drift risk for the few who do is small and recoverable.
+Cross-product wording consistency for operators running multiple
+knowless adopters belongs in a shared module on the operator side, not
+in knowless. Revisit if a second independent adopter asks for the
+helper. No code changes.
+
+### Documented
+
+- `GUIDE.md` Mode A walkthrough — added a "Composing the 'Last
+  sign-in' security signal under `bodyOverride`" callout right after
+  the `auth.deriveHandle` paragraph. Explains why the line doesn't
+  auto-append on overridden bodies (override is full-content
+  replacement, AF-26), points at the existing recipe
+  (`auth.deriveHandle` + parallel `createStore` + `getLastLogin`),
+  notes that `upsertLastLogin` only fires on callback consumption so
+  a pre-call read matches what knowless reads internally, and
+  includes a worked example. Targeted at adopters who reorder the
+  body and want the signal back; default-path adopters (no override)
+  are unaffected.
+
 ## [1.1.4] — 2026-05-08
 
 Documentation + small bug fix. Adopters (plato, addypin, bareagent,

package/GUIDE.md

@@ -384,6 +384,39 @@ 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.
 
+> **Composing the "Last sign-in" security signal under
+> `bodyOverride`.** The default last-sign-in line lives in
+> `composeBody` and does **not** auto-append on overridden bodies —
+> override is full-content replacement (handlers.js AF-26). If your
+> override needs the same signal, look up the timestamp before
+> calling `startLogin` and interpolate it yourself. Everything you
+> need is already exported: `auth.deriveHandle(email)` returns the
+> handle, and a parallel read-only `createStore(dbPath)` exposes
+> `getLastLogin(handle)` (Unix ms when the handle exists, `null` for
+> sham / new / opted-out). `upsertLastLogin` only fires on callback
+> consumption, so a pre-call read returns the same value knowless
+> reads internally. Wording stays your responsibility under override —
+> small drift cost for taking the wheel.
+>
+> ```js
+> import { createStore } from 'knowless';
+> const store = createStore(process.env.KNOWLESS_DB_PATH);
+> // ... in your request handler ...
+> const handle = auth.deriveHandle(email);
+> const lastLoginAt = store.getLastLogin(handle); // null for sham/new
+> await auth.startLogin({
+>   email,
+>   bodyOverride: ({ url }) =>
+>     `Click to sign in:\n\n${url}\n\n` +
+>     `This link expires in 15 minutes. If you didn't request this,\n` +
+>     `ignore this email.\n` +
+>     (lastLoginAt != null
+>       ? `\nLast sign-in: ${new Date(lastLoginAt).toISOString()}.\n` +
+>         `If that wasn't you, do not click the link above.\n`
+>       : ''),
+> });
+> ```
+
 > **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

package/README.md

@@ -9,21 +9,6 @@ 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. |
-
 ## What it does
 
 The simpler answer that always worked: **magic link in, session
@@ -31,8 +16,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 +65,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 +74,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,8 +114,6 @@ 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
 
 **Defends well:** DB-only leaks (handles are HMAC-salted),
@@ -184,13 +131,9 @@ 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."
+compromised email accounts, social engineering, insider threat at
+the operator. Layer-2 defences (Cloudflare, fail2ban, reverse-proxy
+rate-limits) belong above the library.
 
 ## Adopters
 
@@ -208,6 +151,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

@@ -649,10 +649,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

package/package.json

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