knowless 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -15,6 +15,54 @@ Versioning is [SemVer](https://semver.org/).
   sham mail, SPF/DKIM/PTR, reverse-proxy configs for Caddy / nginx /
   Traefik). (Tracked in TASKS.md Phase 7.)
 
+## [0.1.1] — 2026-04-29
+
+First-customer scope (the webrevival forum) review identified one
+ergonomic gap and elevated three P1 hardening items to "must ship
+before first real use." All five closed in this release.
+
+### Added
+
+- `auth.handleFromRequest(req)` — programmatic session resolution
+  for in-process middleware. Returns `string | null` (handle on
+  valid session, null on any failure). Recommended integration
+  point for Express / Fastify / Hono `requireAuth` middleware. SPEC
+  §9.4. Closes AF-2.8.
+- `cookieSecure` config option (default `true`). Operators MAY set
+  `false` for `http://localhost` development; the library emits a
+  stderr warning at startup. MUST NOT be `false` in production.
+  SPEC §5.4. PRD FR-30 revised. Closes AF-4.4.
+
+### Security
+
+- **CSRF defense on `POST /login`.** New Origin/Referer header
+  validation as Step 0 of the login flow. Both headers absent →
+  allow (curl, programmatic). Either present → host must equal
+  `cookieDomain` or be a subdomain. Cross-origin / unparseable →
+  silent short-circuit, no DB write, no mail. Same response shape
+  as a legitimate hit, so the attacker's measurement learns
+  nothing the request shape didn't already expose. SPEC §7.3 Step
+  0. Closes AF-4.3, resolves SPEC §15 Q-4.
+
+### Tests
+
+- AF-4.1: concurrent token issuance under cap contention.
+  10-parallel logins with `maxActiveTokensPerHandle=3` must end at
+  exactly 3 active rows. Pins the SPEC §4.7 BEGIN IMMEDIATE
+  contract.
+- AF-4.2: SMTP-failure response-uniformity test. Stubs
+  `mailer.submit` to throw and asserts the response shape is
+  identical to a successful login. Pins NFR-10.
+- 12 new tests total. 122 tests passing on Node 20+.
+
+### Notes
+
+The published `0.1.0` does not have these. Adopters who installed
+`0.1.0` should `npm update knowless` to pick up the CSRF defense
+and the localhost-dev-friendly cookieSecure option.
+
+[0.1.1]: https://github.com/hamr0/knowless/releases/tag/v0.1.1
+
 ## [0.1.0] — 2026-04-28
 
 First public release. Library-mode auth flow is complete and
@@ -138,5 +186,5 @@ Two primary audiences (PRD §4):
 
 Apache 2.0 with NOTICE preservation. See `LICENSE` and `NOTICE`.
 
-[Unreleased]: https://github.com/hamr0/knowless/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/hamr0/knowless/compare/v0.1.1...HEAD
 [0.1.0]: https://github.com/hamr0/knowless/releases/tag/v0.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "knowless",
-  "version": "0.1.0",
+  "version": "0.1.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

@@ -32,6 +32,7 @@ const DEFAULTS = {
   shamRecipient: 'null@knowless.invalid',
   trustedProxies: ['127.0.0.1', '::1', '::ffff:127.0.0.1'],
   failureRedirect: null,
+  cookieSecure: true,
 };
 
 /**
@@ -84,6 +85,38 @@ function getCookie(req, name) {
   return null;
 }
 
+/**
+ * Validate the request's Origin/Referer header against the cookie
+ * domain whitelist per SPEC §7.3 Step 0 (AF-4.3, CSRF defense).
+ *
+ * - Both headers absent → allow (curl, fetch without CORS, programmatic
+ *   clients). Browsers always send Origin on cross-origin POST.
+ * - Either present → parse and require host == cookieDomain or
+ *   .endsWith('.' + cookieDomain). Same whitelist as the next-URL
+ *   check in §11.2.
+ * - Unparseable URL or non-matching host → reject.
+ *
+ * Origin is preferred when both are present (it's harder to spoof and
+ * more reliably set by browsers on POST).
+ */
+function validateOrigin(req, cookieDomain) {
+  const origin = req.headers?.origin;
+  const referer = req.headers?.referer ?? req.headers?.referrer;
+  const candidate = origin ?? referer;
+  if (!candidate) return true;
+  if (typeof candidate !== 'string') return false;
+  let parsed;
+  try {
+    parsed = new URL(candidate);
+  } catch {
+    return false;
+  }
+  const host = parsed.hostname.toLowerCase();
+  if (!host) return false;
+  const dom = cookieDomain.toLowerCase();
+  return host === dom || host.endsWith('.' + dom);
+}
+
 /**
  * Validate the `next` URL per SPEC §11.2.
  * @param {string|null|undefined} rawNext
@@ -147,6 +180,12 @@ export function createHandlers({ store, mailer, config }) {
 
   const trustedProxies = new Set(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
+  // dev). HttpOnly + SameSite=Lax are always set.
+  const secureAttr = cfg.cookieSecure ? '; Secure' : '';
+  const setCookieAttrs = `Domain=${cfg.cookieDomain}; Path=/; HttpOnly; SameSite=Lax`;
+
   function sameResponse(res, echoedEmail, next) {
     const html = renderLoginForm({
       loginPath: cfg.loginPath,
@@ -168,6 +207,15 @@ export function createHandlers({ store, mailer, config }) {
   }
 
   async function login(req, res) {
+    // Step 0 — Origin / Referer validation (SPEC §7.3 Step 0, AF-4.3).
+    // CSRF defense: a malicious cross-origin page autosubmitting to /login
+    // would otherwise trigger magic-link sends to known emails. Exempt
+    // from FR-6 timing equivalence per SPEC §7.3.
+    if (!validateOrigin(req, cfg.cookieDomain)) {
+      sameResponse(res, '', '');
+      return;
+    }
+
     let raw;
     try {
       raw = await readBody(req);
@@ -312,33 +360,42 @@ export function createHandlers({ store, mailer, config }) {
     res.statusCode = 302;
     res.setHeader(
       'Set-Cookie',
-      `${cfg.cookieName}=${cookie}; Domain=${cfg.cookieDomain}; Path=/; Max-Age=${cfg.sessionTtlSeconds}; Secure; HttpOnly; SameSite=Lax`,
+      `${cfg.cookieName}=${cookie}; ${setCookieAttrs}; Max-Age=${cfg.sessionTtlSeconds}${secureAttr}`,
     );
     res.setHeader('Location', row.nextUrl ?? `${cfg.baseUrl}/`);
     res.end();
   }
 
-  function verify(req, res) {
+  /**
+   * Programmatic session resolution per SPEC §9.4. Reads the
+   * configured cookie from the request, validates its signature,
+   * looks up the session row, and returns the handle. Returns
+   * null on any failure (missing/malformed cookie, signature
+   * mismatch, expired session, no row). Recommended integration
+   * point for in-process middleware. Closes AF-2.8.
+   *
+   * @param {{ headers?: { cookie?: string } }} req
+   * @returns {string | null}
+   */
+  function handleFromRequest(req) {
     const cookie = getCookie(req, cfg.cookieName);
-    if (!cookie) {
-      res.statusCode = 401;
-      res.end();
-      return;
-    }
+    if (!cookie) return null;
     const sid = verifySessionSignature(cookie, cfg.secret);
-    if (!sid) {
-      res.statusCode = 401;
-      res.end();
-      return;
-    }
+    if (!sid) return null;
     const row = store.getSession(sidHashOf(sid));
-    if (!row || row.expiresAt <= Date.now()) {
+    if (!row || row.expiresAt <= Date.now()) return null;
+    return row.handle;
+  }
+
+  function verify(req, res) {
+    const handle = handleFromRequest(req);
+    if (!handle) {
       res.statusCode = 401;
       res.end();
       return;
     }
     res.statusCode = 200;
-    res.setHeader('X-User-Handle', row.handle);
+    res.setHeader('X-User-Handle', handle);
     res.end();
   }
 
@@ -351,7 +408,7 @@ export function createHandlers({ store, mailer, config }) {
     res.statusCode = 200;
     res.setHeader(
       'Set-Cookie',
-      `${cfg.cookieName}=; Domain=${cfg.cookieDomain}; Path=/; Max-Age=0; Secure; HttpOnly; SameSite=Lax`,
+      `${cfg.cookieName}=; ${setCookieAttrs}; Max-Age=0${secureAttr}`,
     );
     res.end();
   }
@@ -376,6 +433,7 @@ export function createHandlers({ store, mailer, config }) {
     verify,
     logout,
     loginForm,
+    handleFromRequest,
     validateNextUrl: (raw) => validateNextUrl(raw, cfg.baseUrl, cfg.cookieDomain),
     // exposed for tests
     _config: cfg,

package/src/index.js

@@ -76,6 +76,16 @@ export function knowless(options = {}) {
     throw new Error('knowless: secret must be at least 64 hex chars (32 bytes)');
   }
 
+  // SPEC §5.4: cookieSecure: false is allowed only for localhost dev.
+  // The library can't tell whether the operator is in production, but a
+  // visible warning makes it harder to ship by accident.
+  if (options.cookieSecure === false) {
+    console.warn(
+      '[knowless] WARNING: cookieSecure is false. Session cookies will be set without the Secure flag. ' +
+        'This is only safe for http://localhost development. Never deploy with cookieSecure: false.',
+    );
+  }
+
   const store = options.store ?? createStore(options.dbPath ?? './knowless.db');
 
   const mailer =
@@ -109,6 +119,8 @@ export function knowless(options = {}) {
     verify: handlers.verify,
     logout: handlers.logout,
     loginForm: handlers.loginForm,
+    /** Resolve handle from request cookie programmatically (SPEC §9.4). */
+    handleFromRequest: handlers.handleFromRequest,
     /** Delete a handle + all tokens + all sessions atomically (FR-37a). */
     deleteHandle: (handle) => store.deleteHandle(handle),
     /** Effective config (with defaults applied), useful for routing. */

package/src/mailer.js

@@ -19,6 +19,22 @@ const ASCII_RE = /^[\x00-\x7f]*$/;
  * @returns {string} RFC822 message with CRLF line endings
  */
 function composeRaw({ from, to, subject, body }) {
+  // AF-2.1: header-injection defense in depth. normalize() upstream
+  // already rejects \r and \n in email addresses, but the mailer
+  // shouldn't trust its callers — this is the layer that emits the
+  // wire-format bytes, so it owns the invariant.
+  for (const [name, value] of [
+    ['from', from],
+    ['to', to],
+    ['subject', subject],
+  ]) {
+    if (typeof value !== 'string') {
+      throw new Error(`mailer: ${name} must be a string`);
+    }
+    if (/[\r\n]/.test(value)) {
+      throw new Error(`mailer: ${name} contains CR/LF — header injection blocked`);
+    }
+  }
   const fromDomain = from.includes('@') ? from.split('@').pop() : 'localhost';
   const messageId = `<${crypto.randomUUID()}@${fromDomain}>`;
   const date = new Date().toUTCString();