@blamejs/core 0.14.16 → 0.14.18

package/lib/breach-deadline.js

@@ -33,6 +33,7 @@ var defineClass = require("./framework-error").defineClass;
 var lazyRequire = require("./lazy-require");
 
 var audit = lazyRequire(function () { return require("./audit"); });
+var incidentReport = lazyRequire(function () { return require("./incident-report"); });
 
 var BreachError = defineClass("BreachError", { alwaysPermanent: true });
 
@@ -259,10 +260,174 @@ function createReporter(opts) {
   };
 }
 
+// Resolve a per-state breach deadline entry to its wall-clock due-by ms.
+// Hard-deadline states expose `dueBy`; "without unreasonable delay"
+// states expose the operator-defensible `ceilingDueBy`.
+function _dueByOf(deadlineEntry) {
+  return deadlineEntry.kind === "hard-deadline"
+    ? deadlineEntry.dueBy
+    : deadlineEntry.ceilingDueBy;
+}
+
+/**
+ * @primitive  b.breach.deadline.createClock
+ * @signature  b.breach.deadline.createClock(opts?)
+ * @since      0.14.18
+ * @status     stable
+ * @compliance gdpr, soc2
+ *
+ * Detection-to-notification running clock for US state breach
+ * deadlines. `forStates` / `report.create` compute the static
+ * per-state due-by timestamps; this clock turns them into a live
+ * escalation loop. It composes the regime-agnostic
+ * `b.incident.report.createDeadlineClock` (one underlying clock,
+ * one synthetic incident per affected state) so a breach with
+ * residents in many states escalates each state's statutory wall
+ * independently: an "approaching" warning fires as a state's
+ * deadline nears, a "passed" alert fires when it elapses, and
+ * `acknowledgeSubmission(breachId, state)` silences a state once its
+ * notice is filed. Each (breach, state) escalation fires at most once
+ * per phase regardless of tick cadence.
+ *
+ * The per-state deadline carries the same statutory data the registry
+ * encodes — hard-deadline states (e.g. TX Tex. Bus. & Com. Code
+ * §521.053, 60 days; CO Colo. Rev. Stat. §6-1-716, 30 days) use the
+ * statutory wall; "without unreasonable delay" states (e.g. CA Cal.
+ * Civ. Code §1798.82) use the operator-defensible ASAP ceiling. The
+ * statutory hour/day counts are never re-encoded here — they are read
+ * from STATE_DEADLINES. This mirrors the multi-regime clock in
+ * `b.incident.report` (GDPR Art.33 72h, NIS2 Art.23(4) 24h, DORA
+ * Art.19 4h, HIPAA 45 CFR 164.404/408 60 days) for the federal regimes
+ * that run alongside the state statutes.
+ *
+ * @opts
+ *   audit:              boolean,        // emit tamper-evident clock audits — default true
+ *   notify:             object,         // { send(payload) } escalation sink — best-effort, drop-silent
+ *   approachThresholds: number[],       // unitless proportions of detected-to-due — default [0.5, 0.75, 0.9]
+ *   intervalMs:         number,         // auto-tick cadence — default C.TIME.minutes(1)
+ *   autoStart:          boolean,        // start the auto-tick timer immediately — default true
+ *   now:                function,       // injectable clock source for testing — default Date.now
+ *
+ * @example
+ *   var reporter = b.breach.report.create({ audit: b.audit });
+ *   var rec = reporter.open({
+ *     detectedAt:     Date.now(),
+ *     affectedStates: ["CA", "TX"],
+ *     impact:         { individualsAffected: 5000 },
+ *   });
+ *   var clock = b.breach.deadline.createClock({
+ *     notify:    { send: function (p) { alertOnCall(p); } },
+ *     autoStart: false,
+ *   });
+ *   clock.trackReport(rec);
+ *   // later, on each operator-controlled evaluation:
+ *   clock.tick();
+ *   await reporter.fileNotice(rec.id, "CA", { method: "email" });
+ *   clock.acknowledgeSubmission(rec.id, "CA");   // silence CA escalation
+ */
+function createDeadlineClock(opts) {
+  opts = opts || {};
+  // Compose the regime-agnostic clock — it owns the tick loop,
+  // once-per-phase firing, audit/notify fan-out, and timer lifecycle.
+  // The breach clock only adapts per-state breach deadlines onto its
+  // single-stage `final` slot and tracks the (breach, state) keying.
+  var inner = incidentReport().createDeadlineClock({
+    audit:              opts.audit,
+    notify:             opts.notify,
+    approachThresholds: opts.approachThresholds,
+    intervalMs:         opts.intervalMs,
+    autoStart:          opts.autoStart,
+    now:                opts.now,
+  });
+
+  // breachId -> { detectedAt, states: { STATE -> innerIncidentId } }
+  var tracked = new Map();
+
+  function _innerId(breachId, state) {
+    return breachId + "::" + state;
+  }
+
+  function trackReport(report) {
+    if (!report || typeof report !== "object" || typeof report.id !== "string" || report.id.length === 0) {
+      throw new BreachError("breach-clock/bad-report",
+        "breach.deadline.createClock.trackReport: report must be a breach.report record with a string id");
+    }
+    if (typeof report.detectedAt !== "number" || !isFinite(report.detectedAt)) {
+      throw new BreachError("breach-clock/bad-detected-at",
+        "breach.deadline.createClock.trackReport: report.detectedAt must be a finite Unix-ms timestamp");
+    }
+    if (!Array.isArray(report.deadlines) || report.deadlines.length === 0) {
+      throw new BreachError("breach-clock/bad-deadlines",
+        "breach.deadline.createClock.trackReport: report.deadlines must be the non-empty per-state array from breach.report.open");
+    }
+    var entry = tracked.get(report.id) || { detectedAt: report.detectedAt, states: {} };
+    for (var i = 0; i < report.deadlines.length; i += 1) {
+      var d = report.deadlines[i];
+      var state = d.state;
+      if (entry.states[state]) continue;   // idempotent re-track of the same state
+      var innerId = _innerId(report.id, state);
+      // The statutory wall is carried on the `final` stage so the
+      // approach-then-pass escalation runs against the per-state
+      // deadline; initial/intermediate are left undefined (the inner
+      // tick skips stages with no due-by).
+      inner.track({
+        id:         innerId,
+        detectedAt: report.detectedAt,
+        regime:     d.statute || state,
+        dueBy:      { final: _dueByOf(d) },
+      });
+      entry.states[state] = innerId;
+    }
+    tracked.set(report.id, entry);
+    return report.id;
+  }
+
+  function untrack(breachId) {
+    var entry = tracked.get(breachId);
+    if (!entry) return false;
+    var states = Object.keys(entry.states);
+    for (var i = 0; i < states.length; i += 1) {
+      inner.untrack(entry.states[states[i]]);
+    }
+    return tracked.delete(breachId);
+  }
+
+  function acknowledgeSubmission(breachId, state, info) {
+    var entry = tracked.get(breachId);
+    var stateUp = (typeof state === "string") ? state.toUpperCase() : state;
+    if (!entry || !entry.states[stateUp]) {
+      throw new BreachError("breach-clock/unknown-tracked-state",
+        "breach.deadline.createClock.acknowledgeSubmission: no tracked breach '" + breachId + "' for state '" + state + "'");
+    }
+    return inner.acknowledgeSubmission(entry.states[stateUp], "final", info);
+  }
+
+  function status() {
+    var innerStatus = inner.status();
+    return {
+      breaches:   tracked.size,
+      tracked:    innerStatus.tracked,
+      running:    innerStatus.running,
+      intervalMs: innerStatus.intervalMs,
+    };
+  }
+
+  return {
+    trackReport:           trackReport,
+    untrack:               untrack,
+    acknowledgeSubmission: acknowledgeSubmission,
+    tick:                  inner.tick,
+    start:                 inner.start,
+    stop:                  inner.stop,
+    status:                status,
+  };
+}
+
 module.exports = {
-  // b.breach.deadline.* — registry lookups
+  // b.breach.deadline.* — registry lookups + running clock
   deadline: {
     forStates:                 forStates,
+    createClock:               createDeadlineClock,
     STATE_DEADLINES:           STATE_DEADLINES,
     WITHOUT_UNREASONABLE_DELAY: WITHOUT_UNREASONABLE_DELAY,
   },

package/lib/cloud-events.js

@@ -40,6 +40,7 @@ var rfc3339 = require("./rfc3339");
 var safeJson = require("./safe-json");
 var safeBuffer = require("./safe-buffer");
 var C = require("./constants");
+var codepointClass = require("./codepoint-class");
 var { defineClass } = require("./framework-error");
 
 var CloudEventsError = defineClass("CloudEventsError", { alwaysPermanent: true });
@@ -527,7 +528,8 @@ function _pctDecode(s) {
   var bytes = [];
   var i = 0;
   while (i < s.length) {
-    if (s[i] === "%" && /^[0-9A-Fa-f]{2}$/.test(s.slice(i + 1, i + 3))) {
+    // allow:regex-no-length-cap — the slice is a fixed 2-char window
+    if (s[i] === "%" && codepointClass.HEX_PAIR_RE.test(s.slice(i + 1, i + 3))) {
       bytes.push(parseInt(s.slice(i + 1, i + 3), 16));   // 16 is the hex radix
       i += 3;
     } else {

package/lib/codepoint-class.js

@@ -252,10 +252,31 @@ function applyCharStripPolicies(text, opts) {
   return out;
 }
 
+// REGEXP_META_RE — the full ECMAScript RegExp metacharacter set
+// (. * + ? ^ $ { } ( ) | [ ] \).
+var REGEXP_META_RE = /[.*+?^${}()|[\]\\]/g;
+
+// escapeRegExp — escape every RegExp metacharacter in a string so an
+// operator- or input-supplied token matches literally when spliced into a
+// `new RegExp(...)`. Three lib sites previously rolled the identical body;
+// centralized here so a token destined for dynamic compilation cannot
+// inject a pattern.
+function escapeRegExp(s) {
+  return String(s).replace(REGEXP_META_RE, "\\$&");
+}
+
+// HEX_PAIR_RE — a percent-escape's two-hex-digit value (RFC 3986 §2.1
+// pct-encoded). Percent-decoders test the two characters after a `%`
+// against this before parseInt with the hex radix; shared so the literal
+// lives once.
+var HEX_PAIR_RE = /^[0-9A-Fa-f]{2}$/;
+
 module.exports = {
   hex4:              hex4,
   charClass:         charClass,
   fromCp:            fromCp,
+  escapeRegExp:      escapeRegExp,
+  HEX_PAIR_RE:       HEX_PAIR_RE,
   BIDI_RANGES:       BIDI_RANGES,
   C0_CTRL_RANGES:    C0_CTRL_RANGES,
   ZERO_WIDTH_RANGES: ZERO_WIDTH_RANGES,

package/lib/db-schema.js

@@ -39,6 +39,7 @@
 var nodePath = require("node:path");
 var atomicFile = require("./atomic-file");
 var safeSql = require("./safe-sql");
+var observability = require("./observability");
 
 // SQLite raw-SQL helper. node:sqlite DatabaseSync exposes a method on the
 // database object that runs raw SQL without bind parameters — used for DDL,
@@ -109,22 +110,61 @@ function ensureMigrationsTable(database) {
 
 // ---- Declarative reconcile ----
 
-function reconcile(database, schema) {
+// reconcile — declarative schema reconcile: CREATE TABLE IF NOT EXISTS +
+// additive ALTER TABLE ADD COLUMN + CREATE INDEX IF NOT EXISTS for every
+// table in `schema`. Never drops columns or tables (data-loss safety).
+//
+// `opts.onDrift` adds opt-in detection of config-vs-live divergence — a
+// compliance-evidence concern: the live DB should match the declared data
+// model so an auditor can trust the schema config as ground truth (the
+// change-/configuration-management control families in ISO 27001:2022
+// A.8.9 and SOC 2 CC8.1 turn on "the running system equals the approved
+// definition"). Detection covers the two cases reconcile's additive path
+// cannot fix on its own:
+//
+//   - undeclared (extra) columns present in the live table but absent
+//     from the declared schema — an out-of-band ALTER / hand-edit;
+//   - declared columns still missing from the live table after the
+//     ADD COLUMN pass (e.g. a column whose DDL the engine rejected).
+//
+// Dropped columns are never acted on — reconcile is non-destructive by
+// contract; this is detection + an operator-chosen reaction only.
+//
+// onDrift values (config-time enum; bad value throws):
+//   "ignore"  (default) — pre-detection behavior, byte-for-byte; no
+//                         detection side effects. Existing deployments
+//                         with drift are not broken.
+//   "warn"    — detect + emit a "db.schema.drift" observability event per
+//               drifted table; never throws.
+//   "refuse"  — detect + THROW on the first drifted table, so a strict-
+//               schema posture refuses to boot under divergence. The
+//               operator's explicit posture choice.
+//
+// Returns a { tables: [...], drifted: boolean } report.
+function reconcile(database, schema, opts) {
   if (!Array.isArray(schema)) {
     throw new Error("db.init({ schema }) must be an array of table definitions");
   }
+  var driftMode = resolveDriftMode(opts);
+  var report = { tables: [], drifted: false };
   for (var i = 0; i < schema.length; i++) {
-    reconcileTable(database, schema[i]);
+    var tableReport = reconcileTable(database, schema[i], { onDrift: driftMode });
+    if (tableReport.drift) {
+      report.tables.push(tableReport.drift);
+      report.drifted = true;
+    }
   }
+  return report;
 }
 
-function reconcileTable(database, table) {
+function reconcileTable(database, table, opts) {
   if (!table || !table.name) {
     throw new Error("schema entry missing required 'name' property");
   }
   if (!table.columns || typeof table.columns !== "object") {
     throw new Error("schema entry '" + table.name + "' missing 'columns' object");
   }
+  var driftMode = resolveDriftMode(opts);
 
   var name = table.name;
   validateIdent(name, "table name");
@@ -203,6 +243,62 @@ function reconcileTable(database, table) {
       reconcileIndex(database, name, table.indexes[k]);
     }
   }
+
+  // Schema-drift detection (opt-in; default "ignore" => no-op). Compares
+  // the live table's columns against the declared model AFTER the additive
+  // ADD COLUMN pass so the diff reflects what reconcile could not fix:
+  //   - extra    = live-but-undeclared (out-of-band ALTER / hand-edit);
+  //   - missing  = declared-but-still-absent (ADD COLUMN could not apply).
+  // Dropped columns are never acted on — reconcile stays non-destructive.
+  if (driftMode !== "ignore") {
+    var drift = _detectColumnDrift(database, name, table.columns);
+    if (drift) {
+      if (driftMode === "refuse") {
+        throw new Error(_driftMessage(name, drift));
+      }
+      // "warn": drop-silent observability sink (hot-path-safe), then
+      // report back to the caller for operator-visible logging.
+      observability.safeEvent("db.schema.drift", 1, {
+        table:        name,
+        extraCount:   String(drift.extra.length),
+        missingCount: String(drift.missing.length),
+      });
+      return { drift: drift };
+    }
+  }
+  return { drift: null };
+}
+
+// _detectColumnDrift — diff the live table's columns against the declared
+// column set. Returns null when they agree, else { table, extra, missing }
+// with sorted column-name arrays. Pure read (PRAGMA table_info); never
+// issues DDL.
+function _detectColumnDrift(database, tableName, declaredColumns) {
+  var liveCols = listColumns(database, tableName);
+  var declaredSet = new Set();
+  for (var col in declaredColumns) {
+    if (Object.prototype.hasOwnProperty.call(declaredColumns, col)) declaredSet.add(col);
+  }
+  var extra = [];
+  liveCols.forEach(function (c) { if (!declaredSet.has(c)) extra.push(c); });
+  var missing = [];
+  declaredSet.forEach(function (c) { if (!liveCols.has(c)) missing.push(c); });
+  if (extra.length === 0 && missing.length === 0) return null;
+  extra.sort();
+  missing.sort();
+  return { table: tableName, extra: extra, missing: missing };
+}
+
+function _driftMessage(tableName, drift) {
+  var parts = [];
+  if (drift.extra.length) {
+    parts.push("undeclared column(s) [" + drift.extra.join(", ") + "]");
+  }
+  if (drift.missing.length) {
+    parts.push("missing declared column(s) [" + drift.missing.join(", ") + "]");
+  }
+  return "schema drift on table '" + tableName + "': " + parts.join("; ") +
+    " (onDrift: 'refuse')";
 }
 
 function _validateAction(action, label, tableName) {
@@ -214,6 +310,26 @@ function _validateAction(action, label, tableName) {
   return up;
 }
 
+// onDrift reaction modes. "ignore" preserves pre-drift-detection
+// behavior byte-for-byte; "warn" emits an observability signal and
+// reports; "refuse" throws so a strict-schema posture refuses to boot
+// when the live DB has diverged from the declared model.
+var DRIFT_MODES = ["ignore", "warn", "refuse"];
+
+// resolveDriftMode — config-time enum validation. Undefined => "ignore"
+// (default; existing deployments see zero behavior change). A bad value
+// is an operator typo at config time → THROW (entry-point tier).
+function resolveDriftMode(opts) {
+  if (!opts || opts.onDrift === undefined || opts.onDrift === null) return "ignore";
+  var mode = opts.onDrift;
+  if (typeof mode !== "string" || DRIFT_MODES.indexOf(mode) === -1) {
+    throw new TypeError(
+      "db reconcile: onDrift must be one of " + DRIFT_MODES.join(", ") +
+      " (got: " + (typeof mode === "string" ? "'" + mode + "'" : typeof mode) + ")");
+  }
+  return mode;
+}
+
 function reconcileIndex(database, tableName, idx) {
   var cols, indexName, unique;
   if (typeof idx === "string") {
@@ -319,4 +435,5 @@ module.exports = {
   runSqlOnHandle:   runSqlOnHandle,
   runInTransaction: runInTransaction,
   MIGRATIONS_TABLE: MIGRATIONS_TABLE,
+  DRIFT_MODES:      DRIFT_MODES,
 };

package/lib/db.js

@@ -1340,8 +1340,10 @@ async function init(opts) {
     };
   }
 
-  // Declarative schema reconcile (framework + app tables)
-  dbSchema.reconcile(database, fullSchema);
+  // Declarative schema reconcile (framework + app tables). opts.onDrift
+  // ("ignore" default / "warn" / "refuse") opts into config-vs-live
+  // column-drift detection; unset = unchanged additive reconcile.
+  dbSchema.reconcile(database, fullSchema, { onDrift: opts.onDrift });
 
   // Append-only enforcement on audit_log + consent_log via SQLite triggers.
   // Apps cannot UPDATE or DELETE these tables; the framework's audit.record /
@@ -1763,7 +1765,12 @@ var _SLOW_QUERY_BUCKETS_LOCAL = Object.freeze([
   { ms: C.TIME.seconds(5),  label: "5s" },
   { ms: C.TIME.seconds(1),  label: "1s" },
 ]);
-var _STATEMENT_CLASS_RE_LOCAL = /^\s*(?:\/\*[\s\S]*?\*\/\s*|--[^\n]*\n\s*)*([A-Za-z]+)/;
+// Linear (non-backtracking) comment/whitespace skip — each outer
+// iteration consumes one whitespace char, one complete block comment
+// (star-not-slash form, never a lazy `[\s\S]*?`), or one complete line
+// comment, disjoint by first char, so a crafted SQL string of nested
+// `/**/` or `*/--` runs cannot backtrack polynomially (CWE-1333 ReDoS).
+var _STATEMENT_CLASS_RE_LOCAL = /^(?:\s|\/\*(?:[^*]|\*(?!\/))*\*\/|--[^\n]*\n)*([A-Za-z]+)/;
 function _classifyStatementLocal(sql) {
   if (typeof sql !== "string" || sql.length === 0) return "UNKNOWN";
   var m = _STATEMENT_CLASS_RE_LOCAL.exec(sql);

package/lib/error-page.js

@@ -20,6 +20,12 @@
  *     showEnvVars:      false,   // default false (env can carry secrets)
  *     // optional override — return true to take over the response
  *     onError: function (err, req, res, ctx) { … },
+ *     // optional shaping hooks (run AFTER classification + audit, before
+ *     // the response is written; the default envelope is preserved when
+ *     // they're absent):
+ *     problemDetails:  true,                        // emit RFC 9457 application/problem+json on the JSON path
+ *     jsonFormatter:   function (info, req) { … },  // → { contentType, body } for the JSON path
+ *     renderHtml:      function (info, req) { … },  // → string body for the HTML path
  *   });
  *   router.onError(handler);
  *
@@ -40,6 +46,7 @@
 
 var lazyRequire = require("./lazy-require");
 var logModule = require("./log");
+var problemDetails = require("./problem-details");
 var requestHelpers = require("./request-helpers");
 var safeEnv = require("./parsers/safe-env");
 var template = require("./template");
@@ -309,6 +316,23 @@ function create(opts) {
   var showEnvVars     = mode === "dev" && opts.showEnvVars     === true;
   var onErrorHook = typeof opts.onError === "function" ? opts.onError : null;
 
+  // Response-shaping hooks. They run after classification + audit and
+  // replace only the body/content-type the framework would have written
+  // — status, headers, logging, audit, and the v0.14.17 encrypted-error
+  // sealing are unchanged. Config-time validation: a non-function hook
+  // is an operator typo at boot, so it throws rather than silently no-op.
+  if (opts.jsonFormatter !== undefined && opts.jsonFormatter !== null &&
+      typeof opts.jsonFormatter !== "function") {
+    throw new TypeError("errors-page: opts.jsonFormatter must be a function");
+  }
+  if (opts.renderHtml !== undefined && opts.renderHtml !== null &&
+      typeof opts.renderHtml !== "function") {
+    throw new TypeError("errors-page: opts.renderHtml must be a function");
+  }
+  var jsonFormatter = typeof opts.jsonFormatter === "function" ? opts.jsonFormatter : null;
+  var renderHtmlHook = typeof opts.renderHtml === "function" ? opts.renderHtml : null;
+  var emitProblemDetails = opts.problemDetails === true;
+
   var _log = logModule.makeViaOrFallback(log, bootLog);
 
   function handler(err, req, res) {
@@ -386,6 +410,48 @@ function create(opts) {
     };
 
     if (_wantsJson(req, defaultFormat)) {
+      // Full-override formatter: the operator owns content-type AND body
+      // verbatim. A throwing formatter must never mask the original
+      // error, so it falls through to the default envelope. Operators
+      // who want in-session sealing compose req.apiEncryptEncode in their
+      // own formatter (it's exposed on req); the framework writes the
+      // returned body as-is.
+      if (jsonFormatter) {
+        var shaped = null;
+        try { shaped = jsonFormatter(info, req); }
+        catch (e) {
+          _log("error", "errors-page jsonFormatter threw", { error: (e && e.message) || String(e) });
+          shaped = null;
+        }
+        if (shaped && typeof shaped === "object" && shaped.body !== undefined) {
+          var fmtType = typeof shaped.contentType === "string" && shaped.contentType.length > 0
+            ? shaped.contentType : "application/json; charset=utf-8";
+          var fmtBody = typeof shaped.body === "string" || Buffer.isBuffer(shaped.body)
+            ? shaped.body : JSON.stringify(shaped.body);
+          _writeResponse(res, info.status, fmtType, fmtBody);
+          return;
+        }
+      }
+
+      // RFC 9457 problem+json envelope (Problem Details for HTTP APIs).
+      // problemDetails.respond seals via req.apiEncryptEncode when an
+      // encrypted session is active and falls back to plaintext
+      // problem+json on encrypt failure — same contract as the default
+      // envelope below.
+      if (emitProblemDetails) {
+        var problem = problemDetails.create({
+          type:   "about:blank",
+          title:  STATUS_REASONS[info.status] || "Error",
+          status: info.status,
+          detail: info.publicMessage,
+          code:   info.code || (info.status >= 500 ? "internal_error" : "error"),
+        });
+        if (res && res.writableEnded) return;
+        try { problemDetails.respond(res, problem, req); }
+        catch (_e) { /* response already torn down */ }
+        return;
+      }
+
       var errorObj = {
         code:    info.code || (info.status >= 500 ? "internal_error" : "error"),
         message: info.publicMessage,
@@ -394,19 +460,37 @@ function create(opts) {
       if (mode === "dev" && info.stack && showStack && info.status >= 500) {
         errorObj.stack = info.stack;
       }
+      var errorBody = { error: errorObj };
+      if (req && typeof req.apiEncryptEncode === "function") {
+        try { errorBody = req.apiEncryptEncode(errorBody); } catch (_e) { errorBody = { error: errorObj }; }
+      }
       _writeResponse(res, info.status, "application/json; charset=utf-8",
-        JSON.stringify({ error: errorObj }));
+        JSON.stringify(errorBody));
       return;
     }
 
-    var html = (mode === "dev")
-      ? _renderDevHtml(info, {
-          brand:           brand,
-          showStack:       showStack,
-          showRequestInfo: showRequestInfo,
-          showEnvVars:     showEnvVars,
-        }, ctx)
-      : _renderProdHtml(info, { brand: brand, contact: contact });
+    // HTML path. The renderHtml hook replaces the page body after
+    // classification + audit have run; a throwing hook falls back to the
+    // built-in dev/prod page rather than masking the error.
+    var html = null;
+    if (renderHtmlHook) {
+      try {
+        var custom = renderHtmlHook(info, req);
+        if (typeof custom === "string") html = custom;
+      } catch (e) {
+        _log("error", "errors-page renderHtml hook threw", { error: (e && e.message) || String(e) });
+      }
+    }
+    if (html === null) {
+      html = (mode === "dev")
+        ? _renderDevHtml(info, {
+            brand:           brand,
+            showStack:       showStack,
+            showRequestInfo: showRequestInfo,
+            showEnvVars:     showEnvVars,
+          }, ctx)
+        : _renderProdHtml(info, { brand: brand, contact: contact });
+    }
     _writeResponse(res, info.status, "text/html; charset=utf-8", html);
   }