knowless 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -15,6 +15,37 @@ 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

package/package.json

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

@@ -100,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);
@@ -108,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();
 
@@ -125,6 +139,8 @@ export function knowless(options = {}) {
     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/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()) {