knowless 0.2.3 → 1.0.1

package/CHANGELOG.md

@@ -15,8 +15,131 @@ Versioning is [SemVer](https://semver.org/).
 
 ## [Unreleased]
 
-**v0.2.3 is feature-complete.** v1.0.0 is the planned next release —
-walk-away promotion, no API changes.
+Walk-away is active. Per PRD §6.3, the only changes that ship after
+v1.0.0 are:
+
+- Security fixes (CVEs in `nodemailer` or `node:sqlite` with
+  user-visible impact)
+- Bug fixes that don't change the API surface
+- Documentation corrections
+
+Feature requests are deflected to PRD §14 NO-GO, to sibling projects,
+or to forking. The library being "done" is a feature.
+
+### Fixed
+
+- **XFF/X-Real-IP never honored through handler path (AF-28).**
+  `createHandlers` pre-built `trustedProxies` into a `{ has }` object
+  and passed it to `determineSourceIp`, which re-called
+  `buildTrustedPeers` on it. The pre-built object is not a `BlockList`,
+  array, or `Set`, so the peer list fell through to `[]`. Net effect:
+  trusted-proxy matching was silently empty in the handler code path —
+  rate limiting hit the reverse-proxy IP instead of the real client IP,
+  and XFF/X-Real-IP headers were ignored regardless of the
+  `trustedProxies` config. Abuse unit tests were passing because they
+  call `determineSourceIp` directly with raw arrays, bypassing the
+  handler path. Fix: removed the pre-build in `createHandlers`;
+  `determineSourceIp` now receives `cfg.trustedProxies` directly. Closes
+  AF-28.
+
+- **`validateSubject` allowed CR/LF, enabling header injection in
+  standalone callers (AF-29).** The ASCII regex `/^[\x00-\x7f]*$/`
+  matched CR (0x0D) and LF (0x0A). `validateSubject` is re-exported as a
+  public validator (AF-9.1 / v0.1.7) so callers using it as a standalone
+  gate were unprotected. `composeRaw` caught the injection downstream, but
+  the validator is the authoritative public guard. Fix: added an explicit
+  `/[\r\n]/` check to `validateSubject`, consistent with the guards already
+  present in `validateFromName` and `validateBodyOverride`. Closes AF-29.
+
+- **Factory `subject` not validated at startup (AF-30).** The factory
+  `subject` option was never passed to `validateSubject` during
+  `createHandlers` startup, breaking the fail-fast pattern that
+  `bodyFooter` (`validateBodyFooter` in `index.js`) and `fromName`
+  (`validateFromName` in `createMailer`) already followed. A non-ASCII
+  subject or empty string silently passed config time and would only fail
+  at first `mailer.submit()` — potentially hours into production. Fix:
+  added `validateSubject(cfg.subject)` to the config-validation block in
+  `createHandlers`. Closes AF-30.
+
+- **`validateBodyFooter` rejected 4-line footers with a trailing newline
+  (AF-31).** `footer.split('\n').length > 4` counted 5 split parts for
+  `"a\nb\nc\nd\n"` (4 logical lines, trailing newline as is conventional
+  for multi-line strings). Fix: strip a single trailing newline before
+  counting: `footer.replace(/\n$/, '').split('\n').length > 4`. Closes
+  AF-31.
+
+### Documentation
+
+- **`runSendLink` JSDoc corrected: `handle` is null for both malformed
+  email and per-IP rate-limit short-circuit (AF-32).** The JSDoc stated
+  `handle` is null "only when the email failed to normalize." The per-IP
+  rate-limit early return also returns `handle: null` because `deriveHandle`
+  has not run at that point. No behavior change — documentation only. Closes
+  AF-32.
+
+## [1.0.0] — 2026-04-29
+
+**Walk-away release.** No new API surface vs v0.2.3 — v1.0.0 is the
+*promotion* tag, marking the library as feature-complete and the
+maintenance mode (security + bug fixes only) as active.
+
+This is the terminal feature release by intent (PRD §6.3). The
+discipline that produced it: every proposed addition during the
+v0.1.x → v0.2.x cycle was stress-tested against two questions —
+*is this identity layer or behavior layer?* and *does the mechanism
+live with the policy?* Items that failed either test were cut to
+adopter / perimeter / operator code. The result is a library small
+enough to audit in an afternoon, with one production dep, and a
+closed feature list.
+
+### Why v1.0.0 now
+
+All PRD §6.1 graduation criteria are met (12/12 after the 2026-04-29
+scope cull). The library is production-validated end-to-end:
+
+- **One real adopter shipped on it.** addypin merged its
+  `try/knowless` branch and runs knowless as its auth+mail layer in
+  production. ~1,150 LOC of bespoke auth/mail removed; ~35 LOC of
+  knowless wiring added; ~33× reduction.
+- **The full v0.2.x hardening cycle was driven by adopter signal.**
+  Eleven audit findings (AF-7 through AF-25) shipped or were
+  recorded as deliberate cuts. Final cycle (AF-19/20/21 operator
+  visibility, AF-26 body override, AF-27 From: display name) all
+  validated by addypin in production:
+  - v0.2.2 + AF-26: bodyOverride wired into pin-confirmation,
+    login, and resend@ flows; subject and body agree end-to-end.
+  - v0.2.3 + AF-27: fromName wired in both factories (web +
+    inbound CLI); inbox preview shows the brand name, not the
+    local-part. Validated by use, not by spec.
+- **Test count: 235** (192 in v0.2.0 → 207 in v0.2.1 → 223 in
+  v0.2.2 → 235 in v0.2.3 → 235 in v1.0.0).
+- **One production dep** (`nodemailer`). Storage uses `node:sqlite`
+  from the Node stdlib. No native compile, no toolchain.
+- **`Δ_mean` for the FR-6 timing test: 0.002ms locally** — 500× under
+  the 1ms practical-effect bar.
+
+### What walk-away means in practice
+
+- **Pin and forget.** v1.0.0 will work the same way three years
+  later. Security patches will land in v1.x.
+- **No v2.0.** No sessions+, no plugin system, no second mailer, no
+  SaaS counterpart. The API closes here.
+- **No additive v1.x.** v1.1.0, v1.2.0, etc. are reserved for
+  security and bug fixes only. Feature requests are deflected.
+  This is the discipline the AF-23/24/25 cuts and the
+  AF-26/AF-27-as-v0.2.x decisions both protect: walk-away has to
+  *mean* walk-away, otherwise the promise is empty.
+- **Procurement signal.** A library that has explicitly committed
+  to *not growing* is a different risk profile from a typical OSS
+  package. Most reviews read "still actively developed" as good —
+  but for an auth dependency, "still actively developed" is also
+  "still changing in ways you'll have to track." knowless inverts
+  that.
+
+### Migration from v0.2.3
+
+None. v1.0.0 is byte-equivalent to v0.2.3 source. `npm install
+knowless@1.0.0` is a drop-in.
 
 ## [0.2.3] — 2026-04-29
 

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.2.3 | 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)** | Apache-2.0
 
 ## Where to go next
 

package/knowless.context.md

@@ -1,7 +1,7 @@
 # knowless -- Integration Guide
 
 > For AI assistants and developers wiring knowless into a project.
-> v0.2.3 | Node.js >= 22.5 | 1 dep (nodemailer) | Apache-2.0
+> v1.0.0 (walk-away release) | Node.js >= 22.5 | 1 dep (nodemailer) | Apache-2.0
 
 ## What this is
 
@@ -659,10 +659,11 @@ rate-limits) belongs above the library.
     who hold raw 32-byte keys.
 
 18. **`bodyFooter` constraints (AF-8.2).** ASCII only — `·` is NOT
-    ASCII, use `|` or `-`. ≤ 240 chars, ≤ 4 lines, no `http(s)://`
-    URLs (would conflict with the magic-link line). Validated at
-    factory startup; fails fast. Goes after RFC 3676 `"-- "`
-    delimiter so mail clients strip it from quoted replies.
+    ASCII, use `|` or `-`. ≤ 240 chars, ≤ 4 lines (a single trailing
+    newline is allowed and not counted as an extra line), no
+    `http(s)://` URLs (would conflict with the magic-link line).
+    Validated at factory startup; fails fast. Goes after RFC 3676
+    `"-- "` delimiter so mail clients strip it from quoted replies.
 
 19. **`startLogin` is silent at every layer (FR-6).** Returns
     `{handle, submitted: true}` for *every* branch — real send, sham,

package/package.json

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

@@ -5,7 +5,6 @@ import { newSid, signSession, verifySessionSignature } from './session.js';
 import { composeBody, validateSubject, validateBodyOverride } from './mailer.js';
 import { renderLoginForm } from './form.js';
 import {
-  buildTrustedPeers,
   determineSourceIp,
   rateLimitExceeded,
   rateLimitIncrement,
@@ -191,9 +190,7 @@ export function createHandlers({ store, mailer, config, events }) {
       throw new Error('config.baseUrl invalid');
     }
   }
-
-  // Build once at handler creation; supports plain IPs and CIDRs (AF-6.3).
-  const trustedProxies = buildTrustedPeers(cfg.trustedProxies);
+  validateSubject(cfg.subject);
 
   // AF-7.1: emit at most one warning per handler instance about an
   // upstream body parser swallowing the request body. Loud enough to
@@ -253,8 +250,9 @@ export function createHandlers({ store, mailer, config, events }) {
    *
    * @returns {Promise<{handle: string|null, isSham: boolean,
    *                    emailNorm: string, nextValidated: string|null}>}
-   *   handle is null only when the email failed to normalize (programmer
-   *   bug for startLogin; same-shape silent for /login).
+   *   handle is null when the email failed to normalize (programmer bug
+   *   for startLogin) OR when per-IP rate-limit short-circuited before
+   *   handle derivation; same-shape silent for /login.
    */
   async function runSendLink({
     emailRaw,
@@ -469,7 +467,7 @@ export function createHandlers({ store, mailer, config, events }) {
       return;
     }
 
-    const sourceIp = determineSourceIp(req, trustedProxies);
+    const sourceIp = determineSourceIp(req, cfg.trustedProxies);
     const result = await runSendLink({ emailRaw, nextRaw, sourceIp });
     sameResponse(res, result.emailNorm, result.nextValidated ?? '');
   }

package/src/mailer.js

@@ -88,7 +88,7 @@ export function validateBodyFooter(footer) {
   if (footer.length > 240) throw new Error('bodyFooter must be ≤ 240 chars');
   if (!ASCII_RE.test(footer)) throw new Error('bodyFooter must be ASCII');
   if (footer.includes('\r')) throw new Error('bodyFooter must not contain CR');
-  if (footer.split('\n').length > 4) {
+  if (footer.replace(/\n$/, '').split('\n').length > 4) {
     throw new Error('bodyFooter must be ≤ 4 lines');
   }
   if (/https?:\/\//i.test(footer)) {
@@ -269,6 +269,7 @@ export function validateSubject(subject) {
   }
   if (subject.length > 60) throw new Error('subject longer than 60 chars');
   if (!ASCII_RE.test(subject)) throw new Error('subject contains non-ASCII');
+  if (/[\r\n]/.test(subject)) throw new Error('subject must not contain CR/LF');
   const warnings = [];
   const triggers = ['!!', '$$', 'FREE', 'URGENT', 'WINNER'];
   for (const t of triggers) {