knowless 0.2.0 → 0.2.2

package/src/handlers.js

@@ -2,7 +2,7 @@ import crypto from 'node:crypto';
 import { normalize, deriveHandle } from './handle.js';
 import { issueToken, hashToken } from './token.js';
 import { newSid, signSession, verifySessionSignature } from './session.js';
-import { composeBody, validateSubject } from './mailer.js';
+import { composeBody, validateSubject, validateBodyOverride } from './mailer.js';
 import { renderLoginForm } from './form.js';
 import {
   buildTrustedPeers,
@@ -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) {
@@ -243,7 +256,14 @@ export function createHandlers({ store, mailer, config }) {
    *   handle is null only when the email failed to normalize (programmer
    *   bug for startLogin; same-shape silent for /login).
    */
-  async function runSendLink({ emailRaw, nextRaw, sourceIp, subject, bypassRateLimit = false }) {
+  async function runSendLink({
+    emailRaw,
+    nextRaw,
+    sourceIp,
+    subject,
+    bodyOverride,
+    bypassRateLimit = false,
+  }) {
     // Step 1: parse + normalize
     let emailNorm;
     try {
@@ -267,6 +287,7 @@ export function createHandlers({ store, mailer, config }) {
         HOUR_MS,
       )
     ) {
+      ev.rateLimitHit();
       return { handle: null, isSham: false, emailNorm, nextValidated: null };
     }
 
@@ -287,6 +308,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 +334,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,14 +345,36 @@ export function createHandlers({ store, mailer, config }) {
       isSham,
       maxActive: cfg.maxActiveTokensPerHandle,
     });
-
-    const mailBody = composeBody({
-      tokenRaw: token.raw,
-      baseUrl: cfg.baseUrl,
-      linkPath: cfg.linkPath,
-      lastLoginAt,
-      bodyFooter: cfg.bodyFooter,
-    });
+    // 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();
+
+    // AF-26: per-call body override for startLogin (Mode A). When
+    // provided, the adopter's template function receives the composed
+    // magic-link URL and returns the full body text. Same submit path,
+    // same sham work, same FR-6 timing equivalence — just lets adopters
+    // phrase the body to match per-call subjects (pin confirmation,
+    // login, expiry warning). bodyFooter still appends; lastLogin line
+    // does not (override is full-content replacement).
+    let mailBody;
+    if (typeof bodyOverride === 'function') {
+      const url = `${cfg.baseUrl}${cfg.linkPath}?t=${token.raw}`;
+      const rendered = bodyOverride({ url });
+      validateBodyOverride(rendered, url); // throws on invalid
+      mailBody = rendered;
+      if (cfg.bodyFooter) {
+        mailBody += `\n-- \n${cfg.bodyFooter}\n`;
+      }
+    } else {
+      mailBody = composeBody({
+        tokenRaw: token.raw,
+        baseUrl: cfg.baseUrl,
+        linkPath: cfg.linkPath,
+        lastLoginAt,
+        bodyFooter: cfg.bodyFooter,
+      });
+    }
 
     // AF-9: programmatic callers may override the subject per call
     // (addypin sends confirmation / login / expiry-warning all via
@@ -334,10 +383,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.
@@ -411,6 +479,7 @@ export function createHandlers({ store, mailer, config }) {
     nextUrl,
     sourceIp = '',
     subjectOverride,
+    bodyOverride,
     bypassRateLimit = false,
   } = {}) {
     // Programmer-error guards (AF-7.3). These DO throw; they're not
@@ -437,11 +506,20 @@ export function createHandlers({ store, mailer, config }) {
       validateSubject(subjectOverride); // throws on invalid
       subject = subjectOverride;
     }
+    // AF-26: per-call body override. The function is called inside
+    // runSendLink with the composed magic-link URL; its return value
+    // is validated by validateBodyOverride(). The arg-type check
+    // happens here at the API edge so a non-function bodyOverride
+    // fails fast, before any token is minted.
+    if (bodyOverride !== undefined && bodyOverride !== null && typeof bodyOverride !== 'function') {
+      throw new Error('startLogin: bodyOverride must be a function when provided');
+    }
     const { handle } = await runSendLink({
       emailRaw: email,
       nextRaw: nextUrl ?? null,
       sourceIp,
       subject,
+      bodyOverride,
       bypassRateLimit,
     });
     // Same-shape return: rate-limit / sham / real all collapse here.

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 {
@@ -176,7 +273,13 @@ export function knowless(options = {}) {
 }
 
 export { createStore } from './store.js';
-export { createMailer, composeBody, validateSubject, validateBodyFooter } from './mailer.js';
+export {
+  createMailer,
+  composeBody,
+  validateSubject,
+  validateBodyFooter,
+  validateBodyOverride,
+} from './mailer.js';
 export { createHandlers } from './handlers.js';
 export { renderLoginForm } from './form.js';
 export { normalize, deriveHandle, secretBytes } from './handle.js';

package/src/mailer.js

@@ -139,6 +139,60 @@ export function composeBody({ tokenRaw, baseUrl, linkPath, lastLoginAt, bodyFoot
   return body;
 }
 
+/**
+ * Validate a body produced by `startLogin`'s `bodyOverride` template
+ * function (AF-26). The override lets adopters phrase the email body
+ * to match per-call subjects (pin confirmation, login, etc.) without
+ * losing knowless's URL-composition / sham-work / 7bit invariants.
+ *
+ * Constraints (deliberately strict to preserve the v0.11 POC URL-line
+ * invariant — QP soft-breaks WILL break the magic link):
+ *   - non-empty string
+ *   - ≤ 2048 chars (operator-side overflow guard)
+ *   - ASCII only
+ *   - no CR (LF allowed; defense-in-depth header-injection guard)
+ *   - the magic-link URL appears EXACTLY ONCE
+ *   - that occurrence is on its own line (no leading or trailing
+ *     non-newline characters on the same line)
+ *
+ * Throws on any violation. Adopter is responsible for the rest of
+ * the body content (security advice, expiry hint, etc.); knowless
+ * does not enforce semantic content.
+ *
+ * @param {unknown} body
+ * @param {string} url  the magic-link URL knowless composed
+ * @returns {void} throws on invalid
+ */
+export function validateBodyOverride(body, url) {
+  if (typeof body !== 'string' || body.length === 0) {
+    throw new Error('bodyOverride must return a non-empty string');
+  }
+  if (body.length > 2048) {
+    throw new Error('bodyOverride must return ≤ 2048 chars');
+  }
+  if (!ASCII_RE.test(body)) {
+    throw new Error('bodyOverride must return ASCII');
+  }
+  if (body.includes('\r')) {
+    throw new Error('bodyOverride must not contain CR (header-injection defense)');
+  }
+  const occurrences = body.split(url).length - 1;
+  if (occurrences === 0) {
+    throw new Error('bodyOverride must include the magic-link URL exactly once');
+  }
+  if (occurrences > 1) {
+    throw new Error('bodyOverride must include the magic-link URL exactly once');
+  }
+  const lines = body.split('\n');
+  const ownLineCount = lines.filter((l) => l === url).length;
+  if (ownLineCount !== 1) {
+    throw new Error(
+      'bodyOverride must place the magic-link URL on its own line ' +
+        '(preserves the 7bit URL-line invariant; QP soft-breaks would break the link)',
+    );
+  }
+}
+
 /**
  * Validate operator-overridden subject per SPEC §12.5.
  * Throws on invalid; warns (returns warnings array) on suspicious-but-allowed.
@@ -221,6 +275,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

@@ -194,17 +194,23 @@ export function createStore(dbPath = ':memory:') {
   };
 
   // Transactional cap-check + insert per SPEC §4.7.
+  // 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;
     },
   );
 
@@ -231,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,
@@ -243,7 +256,7 @@ export function createStore(dbPath = ':memory:') {
       } = args;
       assertHexHash(tokenHash, 'tokenHash');
       assertHexHash(handle, 'handle');
-      insertTokenAtomic(
+      return insertTokenAtomic(
         tokenHash,
         handle,
         expiresAt,