knowless 0.1.10 → 0.2.1

package/src/handlers.js

@@ -163,7 +163,20 @@ function sidHashOf(sid) {
  *   validateNextUrl: (raw:string)=>string|null
  * }}
  */
-export function createHandlers({ store, mailer, config }) {
+export function createHandlers({ store, mailer, config, events }) {
+  // v0.2.1 operator-visibility hooks. All optional; treat missing as
+  // no-ops so the handler hot path is identical for adopters who don't
+  // wire them. The factory passes a fully-populated `events` object;
+  // direct callers of createHandlers (tests / advanced wiring) may omit
+  // it entirely.
+  const noop = () => {};
+  const ev = {
+    shamHit: events?.shamHit ?? noop,
+    rateLimitHit: events?.rateLimitHit ?? noop,
+    onMailerSubmit: events?.onMailerSubmit ?? noop,
+    onTransportFailure: events?.onTransportFailure ?? noop,
+  };
+
   const cfg = { ...DEFAULTS, ...config };
   if (!cfg.secret) throw new Error('config.secret required');
   if (typeof cfg.secret !== 'string' || cfg.secret.length < 64) {
@@ -267,6 +280,7 @@ export function createHandlers({ store, mailer, config }) {
         HOUR_MS,
       )
     ) {
+      ev.rateLimitHit();
       return { handle: null, isSham: false, emailNorm, nextValidated: null };
     }
 
@@ -287,6 +301,11 @@ export function createHandlers({ store, mailer, config }) {
         )
       ) {
         // Cap exceeded — fall through to sham, do NOT short-circuit.
+        // The fall-through becomes a sham-hit too; both counters
+        // increment because they're independent dimensions (operator
+        // can correlate from `rateLimited` jumping in lockstep with
+        // `sham`).
+        ev.rateLimitHit();
         isCreating = false;
       }
     }
@@ -308,9 +327,10 @@ export function createHandlers({ store, mailer, config }) {
     } else {
       isSham = true;
       toAddress = cfg.shamRecipient;
+      ev.shamHit();
     }
 
-    store.insertToken({
+    const evicted = store.insertToken({
       tokenHash: token.hash,
       handle,
       expiresAt,
@@ -318,6 +338,10 @@ export function createHandlers({ store, mailer, config }) {
       isSham,
       maxActive: cfg.maxActiveTokensPerHandle,
     });
+    // Per-handle token cap rotation is the third rate limit. Counted
+    // here in the aggregate `rateLimited` window so operators see
+    // hammering of a single handle without per-event identity leakage.
+    if (evicted > 0) ev.rateLimitHit();
 
     const mailBody = composeBody({
       tokenRaw: token.raw,
@@ -334,10 +358,29 @@ export function createHandlers({ store, mailer, config }) {
     // so timing equivalence is preserved.
     const effectiveSubject = subject ?? cfg.subject;
     try {
-      await mailer.submit({ to: toAddress, subject: effectiveSubject, body: mailBody });
+      const info = await mailer.submit({
+        to: toAddress,
+        subject: effectiveSubject,
+        body: mailBody,
+      });
+      // v0.2.1: per-event hook on real (non-sham) submissions only.
+      // Sham branches go through the windowed aggregate; emitting them
+      // per-event here would let a careless adopter log per-handle
+      // data and reopen the enumeration oracle that sham-work exists
+      // to prevent.
+      if (!isSham) {
+        ev.onMailerSubmit({
+          messageId: info?.messageId ?? null,
+          handle,
+          timestamp: Date.now(),
+        });
+      }
     } catch (err) {
       // Per NFR-10: SMTP failure logged, NEVER leaked to response shape.
       console.error('[knowless] mail submit failed:', err.message);
+      // v0.2.1: per-event hook for SMTP failures. Carries no identity
+      // data, safe per-event. Operator wires this to alerting.
+      ev.onTransportFailure({ error: err, timestamp: Date.now() });
       // 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.

package/src/index.js

@@ -9,8 +9,27 @@ const DEFAULT_SWEEP_INTERVAL_MS = 5 * 60 * 1000;
 /** Default rate-limit retention: 24 hours past window-start. */
 const DEFAULT_RATE_LIMIT_RETENTION_MS = 24 * 60 * 60 * 1000;
 
+/** Default suppression-window cadence: 60 seconds. v0.2.1. */
+const DEFAULT_SUPPRESSION_WINDOW_MS = 60 * 1000;
+
 const REQUIRED_FIELDS = ['secret', 'baseUrl', 'from'];
 
+/**
+ * Wrap a user-supplied hook so its errors are caught and swallowed.
+ * Matches the `onSweepError` contract: knowless never crashes because
+ * an operator's observability sink threw.
+ */
+function safeHook(fn, label) {
+  if (typeof fn !== 'function') return () => {};
+  return (arg) => {
+    try {
+      fn(arg);
+    } catch (err) {
+      console.error(`[knowless] ${label} hook threw:`, err?.message ?? err);
+    }
+  };
+}
+
 /**
  * @typedef {Object} KnowlessOptions
  * @property {string} secret           HMAC secret, ≥64 hex chars (32 bytes). FR-47, FR-48.
@@ -37,6 +56,21 @@ const REQUIRED_FIELDS = ['secret', 'baseUrl', 'from'];
  * @property {string[]} [trustedProxies]
  * @property {string} [shamRecipient='null@knowless.invalid']  See SPEC §7.4.
  * @property {number} [sweepIntervalMs]    Sweeper tick; defaults to 5 minutes.
+ * @property {function} [onSweepError]     Optional alerting hook for sweep failures.
+ * @property {function} [onMailerSubmit]   v0.2.1. Per-event hook fired on
+ *   successful mail submission for *real* (non-sham) sends only. Payload:
+ *   `{messageId, handle, timestamp}`. Errors are caught and swallowed.
+ * @property {function} [onTransportFailure]  v0.2.1. Per-event hook fired
+ *   on SMTP errors. Payload: `{error, timestamp}`. Errors swallowed.
+ * @property {function} [onSuppressionWindow] v0.2.1. Heartbeat hook fired
+ *   every `suppressionWindowMs` with aggregate counters. Payload:
+ *   `{sham, rateLimited, windowMs}`. Aggregates the silent-202 branches
+ *   (sham + rate-limit hits) without per-event identity disclosure;
+ *   see knowless.context.md § "v0.2.1 design" for the threat-model
+ *   reasoning. Fires even when both counters are zero (heartbeat).
+ *   Errors swallowed.
+ * @property {number} [suppressionWindowMs=60000]  v0.2.1. Cadence of
+ *   `onSuppressionWindow` emissions. Default 60 seconds.
  * @property {object} [store]              Inject your own store implementation.
  * @property {object} [mailer]             Inject your own mailer.
  * @property {object} [transportOverride]  Pass to nodemailer.createTransport (tests).
@@ -64,7 +98,12 @@ const REQUIRED_FIELDS = ['secret', 'baseUrl', 'from'];
  *   verify: Function,
  *   logout: Function,
  *   loginForm: Function,
+ *   handleFromRequest: (req: any) => string | null,
  *   deleteHandle: (handle: string) => void,
+ *   revokeSessions: (handle: string) => number,
+ *   startLogin: (args: object) => Promise<{handle: string|null, submitted: true}>,
+ *   deriveHandle: (email: string) => string,
+ *   verifyTransport: () => Promise<true>,
  *   config: object,
  *   close: () => void,
  * }}
@@ -102,7 +141,58 @@ export function knowless(options = {}) {
       transportOverride: options.transportOverride,
     });
 
-  const handlers = createHandlers({ store, mailer, config: options });
+  // v0.2.1 operator-visibility hooks. All optional. Validate types up
+  // front so a typo is caught at startup, not on the first hit.
+  for (const k of ['onMailerSubmit', 'onTransportFailure', 'onSuppressionWindow']) {
+    if (options[k] !== undefined && typeof options[k] !== 'function') {
+      throw new Error(`knowless: ${k} must be a function when provided`);
+    }
+  }
+  const suppressionWindowMs =
+    options.suppressionWindowMs ?? DEFAULT_SUPPRESSION_WINDOW_MS;
+  if (
+    typeof suppressionWindowMs !== 'number' ||
+    !Number.isFinite(suppressionWindowMs) ||
+    suppressionWindowMs <= 0
+  ) {
+    throw new Error('knowless: suppressionWindowMs must be a positive number');
+  }
+
+  // Counters reset every windowMs. Aggregating sham + rate-limit
+  // branches behind a windowed counter (rather than per-event hooks)
+  // is the deliberate design — see knowless.context.md § "Why three
+  // hooks, not four" for the threat-model justification.
+  let shamCount = 0;
+  let rateLimitedCount = 0;
+  const onMailerSubmit = safeHook(options.onMailerSubmit, 'onMailerSubmit');
+  const onTransportFailure = safeHook(options.onTransportFailure, 'onTransportFailure');
+  const onSuppressionWindow = safeHook(options.onSuppressionWindow, 'onSuppressionWindow');
+
+  const events = {
+    shamHit: () => { shamCount++; },
+    rateLimitHit: () => { rateLimitedCount++; },
+    onMailerSubmit,
+    onTransportFailure,
+  };
+
+  const handlers = createHandlers({ store, mailer, config: options, events });
+
+  // The window timer fires every windowMs as a heartbeat — emits even
+  // when both counters are zero. Operators rely on the heartbeat as a
+  // liveness signal ("knowless is processing"); a missing emission is
+  // itself diagnostic. Only run the timer when the hook is wired so we
+  // don't spend a setInterval slot on adopters who don't use it.
+  let suppressionTimer = null;
+  if (typeof options.onSuppressionWindow === 'function') {
+    suppressionTimer = setInterval(() => {
+      const sham = shamCount;
+      const rateLimited = rateLimitedCount;
+      shamCount = 0;
+      rateLimitedCount = 0;
+      onSuppressionWindow({ sham, rateLimited, windowMs: suppressionWindowMs });
+    }, suppressionWindowMs);
+    if (typeof suppressionTimer.unref === 'function') suppressionTimer.unref();
+  }
 
   const sweepIntervalMs = options.sweepIntervalMs ?? DEFAULT_SWEEP_INTERVAL_MS;
   const onSweepError = options.onSweepError;
@@ -163,8 +253,15 @@ export function knowless(options = {}) {
     config: handlers._config,
     /** Run a sweep tick on demand. Useful for tests and operator scripts. */
     _sweep: runSweep,
+    /** Probe the configured SMTP transport (v0.2.1). Resolves true on
+     *  success, rejects with the underlying error. Opt-in fail-fast for
+     *  adopters who want to validate SMTP at boot; no auto-on-boot
+     *  variant by design — k8s readiness probes / docker-compose
+     *  ordering would fail boot for the wrong reason. */
+    verifyTransport: () => mailer.verify(),
     close() {
       clearInterval(sweepTimer);
+      if (suppressionTimer !== null) clearInterval(suppressionTimer);
       try {
         mailer.close?.();
       } catch {

package/src/mailer.js

@@ -221,6 +221,27 @@ export function createMailer(cfg) {
         raw,
       });
     },
+    /**
+     * Probe the underlying SMTP transport. Resolves to true on success,
+     * rejects with the underlying error otherwise. Adopters call this
+     * explicitly when they want fail-fast on misconfigured SMTP at boot.
+     * No auto-on-boot variant: deployments where knowless starts before
+     * Postfix (docker-compose ordering, k8s readiness probes) would
+     * fail boot for the wrong reason. v0.2.1.
+     *
+     * Contract: non-rejection means success. The underlying nodemailer
+     * transport may return a truthy value, falsy value, or throw —
+     * non-throwing is treated as success and normalized to `true`.
+     * Tests using `streamTransport` exercise this normalization
+     * (streamTransport's verify() returns false even on healthy probes).
+     */
+    async verify() {
+      if (typeof transport.verify !== 'function') {
+        return true;
+      }
+      await transport.verify();
+      return true;
+    },
     close() {
       if (typeof transport.close === 'function') transport.close();
     },

package/src/store.js

@@ -1,4 +1,32 @@
-import Database from 'better-sqlite3';
+import { DatabaseSync } from 'node:sqlite';
+
+/**
+ * Wrap a function in a SQLite transaction. Mirrors better-sqlite3's
+ * `db.transaction(fn)` shape: returns a function that opens
+ * BEGIN IMMEDIATE, runs `fn`, COMMITs on success, ROLLBACKs on
+ * throw, and propagates the original error.
+ *
+ * BEGIN IMMEDIATE rather than BEGIN DEFERRED — knowless's
+ * transactional cap-check (SPEC §4.7) needs a write lock from the
+ * start to serialise concurrent issuance attempts.
+ *
+ * @param {DatabaseSync} db
+ * @param {Function} fn
+ */
+function makeTransaction(db, fn) {
+  return (...args) => {
+    db.exec('BEGIN IMMEDIATE');
+    let result;
+    try {
+      result = fn(...args);
+    } catch (err) {
+      try { db.exec('ROLLBACK'); } catch { /* tolerate stack-unwind issues */ }
+      throw err;
+    }
+    db.exec('COMMIT');
+    return result;
+  };
+}
 
 /**
  * Default token-sweeper grace: keep used tokens for 24h after redemption
@@ -76,11 +104,11 @@ const DDL = `
  * @returns {Store}
  */
 export function createStore(dbPath = ':memory:') {
-  const db = new Database(dbPath);
-  db.pragma('journal_mode = WAL');
-  db.pragma('synchronous = NORMAL');
-  db.pragma('foreign_keys = OFF');
-  db.pragma('temp_store = MEMORY');
+  const db = new DatabaseSync(dbPath);
+  db.exec('PRAGMA journal_mode = WAL');
+  db.exec('PRAGMA synchronous = NORMAL');
+  db.exec('PRAGMA foreign_keys = OFF');
+  db.exec('PRAGMA temp_store = MEMORY');
   db.exec(DDL);
 
   const existing = db
@@ -166,22 +194,28 @@ export function createStore(dbPath = ':memory:') {
   };
 
   // Transactional cap-check + insert per SPEC §4.7.
-  const insertTokenAtomic = db.transaction(
+  // Returns the number of tokens evicted to make room for the new one
+  // (always 0 when maxActive is 0). Callers use this to count
+  // per-handle-cap rotation events for operator monitoring (v0.2.1).
+  const insertTokenAtomic = makeTransaction(db,
     (tokenHash, handle, expiresAt, nextUrl, isSham, maxActive, now) => {
+      let evicted = 0;
       if (maxActive > 0) {
         const { n: count } = stmt.countActiveTokens.get(handle, now);
         let toEvict = count - maxActive + 1;
         while (toEvict > 0) {
           stmt.evictOldestActive.run(handle, now);
           toEvict--;
+          evicted++;
         }
       }
       stmt.insertToken.run(tokenHash, handle, expiresAt, nextUrl, isSham);
+      return evicted;
     },
   );
 
   // Transactional account deletion per FR-37a.
-  const deleteHandleAtomic = db.transaction((handle) => {
+  const deleteHandleAtomic = makeTransaction(db, (handle) => {
     stmt.deleteHandleSessions.run(handle);
     stmt.deleteHandleTokens.run(handle);
     stmt.deleteHandleRow.run(handle);
@@ -203,6 +237,13 @@ export function createStore(dbPath = ':memory:') {
     },
 
     // --- Token ---
+    /**
+     * Insert a token, evicting oldest active tokens for the handle when
+     * the per-handle cap (maxActive) would be exceeded.
+     * @returns {number} count of tokens evicted to make room (0 when no
+     *   rotation occurred). Used for operator monitoring (v0.2.1
+     *   `onSuppressionWindow.rateLimited` counter).
+     */
     insertToken(args) {
       const {
         tokenHash,
@@ -215,7 +256,7 @@ export function createStore(dbPath = ':memory:') {
       } = args;
       assertHexHash(tokenHash, 'tokenHash');
       assertHexHash(handle, 'handle');
-      insertTokenAtomic(
+      return insertTokenAtomic(
         tokenHash,
         handle,
         expiresAt,