knowless 0.1.3 → 0.1.4

package/CHANGELOG.md

@@ -8,6 +8,55 @@ Versioning is [SemVer](https://semver.org/).
 ## [Unreleased]
 
 - 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. Honest answer to "does the operator's null-route
+  actually work?" — the library can know what it submitted but
+  not what the MTA did, so this is the closest we can get.
+  Targeted for v0.2.0.
+
+## [0.1.4] — 2026-04-28
+
+First real-world integration release. Bugs and ergonomics surfaced
+by the addypin team's spike on v0.1.3, plus two minor security
+hardenings that fell out of the audit.
+
+### Added
+
+- **`auth.revokeSessions(handle)`** — log out everywhere without
+  deleting the account. Returns the number of sessions removed.
+  Closes AF-6.1.
+- **`devLogMagicLinks: true`** opt-in — when SMTP fails AND this
+  flag is set, prints the magic link to stderr so a developer can
+  click through. Off by default; never fires for sham (silent-miss)
+  submissions; never replaces real SMTP delivery on success. Closes
+  AF-6.2.
+- **CIDR support in `trustedProxies`** — accept `10.0.0.0/8`,
+  `fd00::/8`, etc. in addition to plain IPs. Uses `node:net`
+  `BlockList`, no new dep. Closes AF-6.3.
+
+### Security
+
+- **CSRF on `POST /logout`.** Origin/Referer validation now mirrors
+  `POST /login` (AF-4.3). Without this, a malicious page could
+  force-logout an authenticated victim. Closes AF-6.4.
+- **`confirmationMessage` is HTML-escaped before rendering.** The
+  message is operator-config (not user input), but a careless
+  operator interpolating user data into it would have produced an
+  XSS. The whole message is now escaped before `{email}` substitution
+  (which was already escaped). Operators who want HTML in the
+  confirmation message must pre-render upstream. Closes AF-6.5.
+
+### Documentation
+
+- **SPEC §10.2** documents the new logout Origin check.
+- **SPEC §7.3 Step 0** adds an explicit "do NOT add a CSRF token
+  upstream — the Origin/Referer whitelist IS the CSRF defense"
+  note for adopters. Closes AF-6.6.
+- **GUIDE.md** front-matter now leads with the v1.0.0 walks-away
+  commitment. Procurement signal: a library that has explicitly
+  committed to *not growing* is a different risk profile from a
+  typical OSS package. Closes AF-6.7.
 
 ## [0.1.3] — 2026-04-28
 

package/GUIDE.md

@@ -5,6 +5,32 @@
 > For the product philosophy, see
 > [`docs/01-product/PRD.md`](docs/01-product/PRD.md).
 
+## Read this first: knowless walks away at v1.0.0
+
+knowless commits to a small, audit-able surface and a *closed* feature
+list. v1.0.0 is the **terminal release** for new functionality: only
+security fixes ship after that. There will be no v2.0 with sessions+,
+no plugin system, no second mailer, no SaaS counterpart.
+
+What this means for you as an adopter:
+
+- **You own integration breadth.** If knowless's defaults don't fit
+  exactly, you patch around it (the API is small enough to do this) or
+  fork it (Apache 2.0). We won't add a config knob to absorb your
+  case.
+- **You can pin and forget.** v1.0.0 will work the same way three
+  years later. Security patches will land in v1.x.
+- **Procurement signal.** A library that has explicitly committed to
+  *not growing* is a different risk profile from a typical OSS
+  package. Most reviews assume "still actively developed" is good;
+  for an auth dependency, "still actively developed" is also "still
+  changing in ways you'll have to track." knowless inverts that.
+
+If you need a kitchen-sink auth library with active feature
+development, this isn't the right tool. See
+[Lucia](https://lucia-auth.com/), [Auth.js](https://authjs.dev/),
+or commercial offerings.
+
 ## Who this is for
 
 Three audiences, in order of fit:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "knowless",
-  "version": "0.1.3",
+  "version": "0.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/abuse.js

@@ -1,3 +1,62 @@
+import net from 'node:net';
+
+/**
+ * Build a peer-IP matcher from a list of plain IPs and/or CIDR ranges.
+ * AF-6.3 — CIDR support so docker / k8s / cgnat ranges can be trusted
+ * without enumerating every address.
+ *
+ * Accepts:
+ *   - bare IPv4/IPv6 ("127.0.0.1", "::1")
+ *   - CIDR ("10.0.0.0/8", "fd00::/8")
+ *   - a Set or array of either
+ *   - a `node:net` BlockList (passed through)
+ *
+ * @param {Set<string>|string[]|net.BlockList} trustedProxies
+ * @returns {{ has: (ip: string) => boolean }}
+ */
+export function buildTrustedPeers(trustedProxies) {
+  if (trustedProxies && typeof trustedProxies.check === 'function') {
+    return { has: (ip) => safeBlockListCheck(trustedProxies, ip) };
+  }
+  const list = Array.isArray(trustedProxies)
+    ? trustedProxies
+    : trustedProxies instanceof Set
+      ? [...trustedProxies]
+      : [];
+  const exact = new Set();
+  const block = new net.BlockList();
+  for (const entry of list) {
+    if (typeof entry !== 'string' || !entry) continue;
+    const slash = entry.indexOf('/');
+    if (slash >= 0) {
+      const addr = entry.slice(0, slash);
+      const prefix = Number(entry.slice(slash + 1));
+      const family = net.isIPv6(addr) ? 'ipv6' : 'ipv4';
+      try {
+        block.addSubnet(addr, prefix, family);
+      } catch {
+        /* skip malformed CIDR rather than crash */
+      }
+    } else {
+      exact.add(entry);
+    }
+  }
+  return {
+    has: (ip) => exact.has(ip) || safeBlockListCheck(block, ip),
+  };
+}
+
+function safeBlockListCheck(block, ip) {
+  if (typeof ip !== 'string' || ip.length === 0) return false;
+  const family = net.isIPv6(ip) ? 'ipv6' : net.isIPv4(ip) ? 'ipv4' : null;
+  if (!family) return false;
+  try {
+    return block.check(ip, family);
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Determine the source IP of a request per FR-42 and SPEC §7.6.
  *
@@ -6,19 +65,20 @@
  * fall back to the connection's remote address. This prevents IP
  * spoofing from clients while supporting forward-auth deployments.
  *
+ * `trustedProxies` accepts plain IPs and CIDR ranges (AF-6.3).
+ *
  * @param {{
  *   socket?: { remoteAddress?: string },
  *   connection?: { remoteAddress?: string },
  *   headers?: Record<string, string|string[]|undefined>
  * }} req a node:http request (or shape-compatible)
- * @param {Set<string>|string[]} trustedProxies set or array of trusted peer IPs
+ * @param {Set<string>|string[]|net.BlockList} trustedProxies trusted peer IPs / CIDRs
  * @returns {string} the determined IP, or '' if undeterminable
  */
 export function determineSourceIp(req, trustedProxies) {
   const peer =
     req?.socket?.remoteAddress ?? req?.connection?.remoteAddress ?? '';
-  const trusted =
-    trustedProxies instanceof Set ? trustedProxies : new Set(trustedProxies ?? []);
+  const trusted = buildTrustedPeers(trustedProxies);
   if (!trusted.has(peer)) {
     return peer;
   }

package/src/form.js

@@ -56,10 +56,15 @@ export function renderLoginForm(args) {
     next,
   } = args;
 
+  // confirmationMessage is operator-supplied config, not user input — but
+  // operators may naively interpolate user data into it. Escape the whole
+  // message before substituting {email} (which is itself escaped). The
+  // contract is "confirmationMessage is plain text + {email} placeholder";
+  // operators who want HTML can pre-render upstream. Closes AF-6.5.
   const messageBlock =
     confirmationMessage != null
       ? `<div class="msg" role="status">${
-          confirmationMessage.replace(
+          htmlEscape(confirmationMessage).replace(
             /\{email\}/g,
             htmlEscape(echoedEmail ?? ''),
           )

package/src/handlers.js

@@ -5,6 +5,7 @@ import { newSid, signSession, verifySessionSignature } from './session.js';
 import { composeBody } from './mailer.js';
 import { renderLoginForm } from './form.js';
 import {
+  buildTrustedPeers,
   determineSourceIp,
   rateLimitExceeded,
   rateLimitIncrement,
@@ -178,7 +179,8 @@ export function createHandlers({ store, mailer, config }) {
     }
   }
 
-  const trustedProxies = new Set(cfg.trustedProxies);
+  // Build once at handler creation; supports plain IPs and CIDRs (AF-6.3).
+  const trustedProxies = buildTrustedPeers(cfg.trustedProxies);
 
   // SPEC §5.4 / FR-30: build the cookie-attribute suffix once. Secure is
   // emitted by default and omitted only when cookieSecure: false (localhost
@@ -319,6 +321,14 @@ export function createHandlers({ store, mailer, config }) {
     } catch (err) {
       // Per NFR-10: SMTP failure logged, NEVER leaked to response shape.
       console.error('[knowless] mail submit failed:', err.message);
+      // AF-6.2: dev-mode fallback. When SMTP is unreachable in local
+      // development the operator otherwise has no way to obtain the magic
+      // link. Print it to stderr only when explicitly opted in. Sham
+      // submissions are NOT logged (would leak silent-miss outcome).
+      if (cfg.devLogMagicLinks && !isSham) {
+        const link = `${cfg.baseUrl}${cfg.linkPath}?t=${token.raw}`;
+        process.stderr.write(`[knowless dev] magic link: ${link}\n`);
+      }
     }
 
     rateLimitIncrement(store, 'login_ip', ip, HOUR_MS);
@@ -400,6 +410,15 @@ export function createHandlers({ store, mailer, config }) {
   }
 
   async function logout(req, res) {
+    // CSRF defense — same Origin/Referer check as POST /login (AF-4.3).
+    // Without this, a third-party page can force-logout a victim. Closes
+    // AF-6.4. Browser-absent (curl/programmatic) is allowed.
+    if (!validateOrigin(req, cfg.cookieDomain)) {
+      res.statusCode = 403;
+      res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+      res.end('forbidden\n');
+      return;
+    }
     const cookie = getCookie(req, cfg.cookieName);
     if (cookie) {
       const sid = verifySessionSignature(cookie, cfg.secret);

package/src/index.js

@@ -137,6 +137,10 @@ export function knowless(options = {}) {
     handleFromRequest: handlers.handleFromRequest,
     /** Delete a handle + all tokens + all sessions atomically (FR-37a). */
     deleteHandle: (handle) => store.deleteHandle(handle),
+    /** Revoke every session for `handle` without deleting the handle.
+     *  "Log out everywhere." Returns the number of sessions removed.
+     *  AF-6.1. */
+    revokeSessions: (handle) => store.revokeSessions(handle),
     /** Effective config (with defaults applied), useful for routing. */
     config: handlers._config,
     /** Run a sweep tick on demand. Useful for tests and operator scripts. */

package/src/store.js

@@ -278,6 +278,11 @@ export function createStore(dbPath = ':memory:') {
       assertHexHash(sidHash, 'sidHash');
       return stmt.deleteSession.run(sidHash).changes > 0;
     },
+    /** Delete every session for `handle`. Returns rows-deleted. AF-6.1. */
+    revokeSessions(handle) {
+      assertHexHash(handle, 'handle');
+      return stmt.deleteHandleSessions.run(handle).changes;
+    },
     sweepSessions(now = Date.now()) {
       return stmt.sweepSessions.run(now).changes;
     },