knowless 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -26,6 +26,57 @@ v1.0.0 are:
 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

package/knowless.context.md

@@ -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": "1.0.0",
+  "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) {