knowless 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -15,6 +15,85 @@ 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.2] — 2026-04-28
+
+P2 hardening sprint — completes the audit-finding backlog opened during
+the v0.1.0 self-review. Defense-in-depth and test-strength improvements;
+no behavior changes for correct callers.
+
+### Added
+
+- `onSweepError(err)` config hook — invoked when the periodic sweeper
+  catches an exception (DB corruption, disk full, etc.). Best-effort:
+  hook errors are swallowed and the sweeper keeps running. `auth._sweep()`
+  is now exposed for tests and operator scripts to trigger a sweep on
+  demand. Closes AF-5.3.
+
+### Security
+
+- **Stored-hash integrity check.** All `handle` / `tokenHash` / `sidHash`
+  arguments are validated as 64-char lowercase hex at the store boundary
+  before any DB read or write. A bug elsewhere passing a wrong-format
+  value now fails fast with an actionable error instead of silently
+  corrupting the table. Closes AF-5.4.
+
+### Tests
+
+- Rate-limit window-boundary precision: last ms of window N is still
+  limited; first ms of N+1 is fresh. Limit semantics: "exceeded" fires
+  AT the limit, not strictly above. Closes AF-5.1.
+- Cookie parser hardening: 8 edge-case scenarios (whitespace,
+  duplicates, malformed pairs, RFC 6265 cases) verifying the existing
+  parser is robust. Closes AF-5.2.
+
+## [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 +217,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.2",
   "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 =
@@ -90,7 +100,10 @@ export function knowless(options = {}) {
   const handlers = createHandlers({ store, mailer, config: options });
 
   const sweepIntervalMs = options.sweepIntervalMs ?? DEFAULT_SWEEP_INTERVAL_MS;
-  const sweepTimer = setInterval(() => {
+  const onSweepError = options.onSweepError;
+  // Extract the sweep body so tests / operators can trigger it without
+  // waiting for the interval. Closes AF-5.3.
+  function runSweep() {
     try {
       const now = Date.now();
       store.sweepTokens(now);
@@ -98,8 +111,19 @@ export function knowless(options = {}) {
       store.sweepRateLimits(now - DEFAULT_RATE_LIMIT_RETENTION_MS);
     } catch (err) {
       console.error('[knowless] sweep failed:', err.message);
+      if (typeof onSweepError === 'function') {
+        // Hook errors are swallowed — alerting is best-effort and MUST
+        // NOT crash the sweep loop. Operator's hook can fail; sweeper
+        // continues.
+        try {
+          onSweepError(err);
+        } catch {
+          /* intentional */
+        }
+      }
     }
-  }, sweepIntervalMs);
+  }
+  const sweepTimer = setInterval(runSweep, sweepIntervalMs);
   // Don't keep the event loop alive just for the sweeper.
   if (typeof sweepTimer.unref === 'function') sweepTimer.unref();
 
@@ -109,10 +133,14 @@ 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. */
     config: handlers._config,
+    /** Run a sweep tick on demand. Useful for tests and operator scripts. */
+    _sweep: runSweep,
     close() {
       clearInterval(sweepTimer);
       try {

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();

package/src/store.js

@@ -8,6 +8,28 @@ const DEFAULT_TOKEN_GRACE_MS = 24 * 60 * 60 * 1000;
 
 const SCHEMA_VERSION = '1';
 
+/**
+ * Validate a 64-char lowercase hex string at the store boundary.
+ * Handles, token hashes, and session ID hashes are all this shape per
+ * SPEC §3.1, §4.1, §5.3. A bug elsewhere passing a wrong-format value
+ * would otherwise silently corrupt the table or fail at SELECT time
+ * with a less-actionable error. Closes AF-5.4.
+ *
+ * @param {unknown} value
+ * @param {string} name parameter name for the thrown error
+ */
+function assertHexHash(value, name) {
+  if (typeof value !== 'string' || !/^[a-f0-9]{64}$/.test(value)) {
+    const got =
+      typeof value === 'string'
+        ? `"${value.slice(0, 16)}${value.length > 16 ? '...' : ''}"`
+        : typeof value;
+    throw new Error(
+      `store: ${name} must be 64-char lowercase hex (got ${got})`,
+    );
+  }
+}
+
 const DDL = `
   CREATE TABLE IF NOT EXISTS handles (
     handle         TEXT    PRIMARY KEY,
@@ -168,12 +190,15 @@ export function createStore(dbPath = ':memory:') {
   return {
     // --- Handle ---
     handleExists(handle) {
+      assertHexHash(handle, 'handle');
       return !!stmt.handleExists.get(handle);
     },
     upsertHandle(handle) {
+      assertHexHash(handle, 'handle');
       stmt.upsertHandleNoLogin.run(handle);
     },
     deleteHandle(handle) {
+      assertHexHash(handle, 'handle');
       deleteHandleAtomic(handle);
     },
 
@@ -188,6 +213,8 @@ export function createStore(dbPath = ':memory:') {
         maxActive = 0,
         now = Date.now(),
       } = args;
+      assertHexHash(tokenHash, 'tokenHash');
+      assertHexHash(handle, 'handle');
       insertTokenAtomic(
         tokenHash,
         handle,
@@ -199,6 +226,7 @@ export function createStore(dbPath = ':memory:') {
       );
     },
     getToken(tokenHash) {
+      assertHexHash(tokenHash, 'tokenHash');
       const row = stmt.getToken.get(tokenHash);
       if (!row) return null;
       return {
@@ -210,12 +238,15 @@ export function createStore(dbPath = ':memory:') {
       };
     },
     markTokenUsed(tokenHash, usedAt) {
+      assertHexHash(tokenHash, 'tokenHash');
       return stmt.markTokenUsed.run(usedAt, tokenHash).changes > 0;
     },
     countActiveTokens(handle, now = Date.now()) {
+      assertHexHash(handle, 'handle');
       return stmt.countActiveTokens.get(handle, now).n;
     },
     evictOldestActiveToken(handle, now = Date.now()) {
+      assertHexHash(handle, 'handle');
       return stmt.evictOldestActive.run(handle, now).changes;
     },
     sweepTokens(now = Date.now(), graceMs = DEFAULT_TOKEN_GRACE_MS) {
@@ -224,21 +255,27 @@ export function createStore(dbPath = ':memory:') {
 
     // --- Last login ---
     upsertLastLogin(handle, at) {
+      assertHexHash(handle, 'handle');
       stmt.upsertLastLogin.run(handle, at);
     },
     getLastLogin(handle) {
+      assertHexHash(handle, 'handle');
       const row = stmt.getLastLogin.get(handle);
       return row ? row.lastLoginAt : null;
     },
 
     // --- Session ---
     insertSession(sidHash, handle, expiresAt) {
+      assertHexHash(sidHash, 'sidHash');
+      assertHexHash(handle, 'handle');
       stmt.insertSession.run(sidHash, handle, expiresAt);
     },
     getSession(sidHash) {
+      assertHexHash(sidHash, 'sidHash');
       return stmt.getSession.get(sidHash) ?? null;
     },
     deleteSession(sidHash) {
+      assertHexHash(sidHash, 'sidHash');
       return stmt.deleteSession.run(sidHash).changes > 0;
     },
     sweepSessions(now = Date.now()) {