@svrnsec/pulse 0.3.1 → 0.5.0

package/src/proof/engagementToken.js

@@ -0,0 +1,394 @@
+/**
+ * @svrnsec/pulse — Engagement Token
+ *
+ * A short-lived, physics-backed cryptographic token that proves a specific
+ * engagement event (click, view, share, purchase) originated from a real
+ * human on real hardware that had genuinely rested between interactions.
+ *
+ * This is the layer that defeats the "1,000 phones in a warehouse" attack.
+ * Each token proves:
+ *
+ *   1. Real hardware       DRAM refresh present, ENF grid signal detected
+ *   2. Genuine idle        Hash-chained thermal measurements spanning ≥ 45s
+ *   3. Physical cooling    Variance decay was smooth, not a step function
+ *   4. Fresh interaction   30-second TTL eliminates token brokers
+ *   5. Tamper-evident      HMAC-SHA256 over all fraud-relevant fields
+ *
+ * Token wire format (compact: base64url JSON, ~400 bytes)
+ * ────────────────────────────────────────────────────────
+ *   {
+ *     v:    2,                   protocol version
+ *     n:    "hex64",             nonce — 256-bit random
+ *     iat:  1234567890123,       issued-at Unix ms
+ *     exp:  1234567920123,       expires-at  (iat + 30s)
+ *     idle: {
+ *       chain: "hex64",          final hash of idle measurement chain
+ *       s:     3,                sample count (≥ 2 for a valid proof)
+ *       dMs:   180000,           idle duration ms
+ *       therm: "hot_to_cold",    thermal transition label
+ *       mono:  0.67,             cooling monotonicity (0–1)
+ *     },
+ *     hw: {
+ *       dram: "dram",            DRAM probe verdict
+ *       enf:  "grid_60hz",       ENF probe verdict
+ *       ent:  0.73,              normalized physics entropy score (0–1)
+ *     },
+ *     evt: {
+ *       t:   "click",            event type
+ *       ts:  1234567890123,      event Unix ms
+ *       mot: 0.82,               motor consistency (0–1)
+ *     },
+ *     sig: "hex64"               HMAC-SHA256 over all fraud-relevant fields
+ *   }
+ *
+ * HMAC input (pipe-delimited, all fields that matter for fraud)
+ * ─────────────────────────────────────────────────────────────
+ *   `v|n|iat|exp|idle.chain|idle.dMs|hw.ent|evt.t|evt.ts`
+ *
+ * Changing any signed field invalidates the token.  Unsigned fields
+ * (therm, mono, dram, enf) are advisory — they inform risk scoring but
+ * cannot be manipulated for credit fraud without breaking the HMAC.
+ */
+
+import { hmac }                     from '@noble/hashes/hmac';
+import { sha256 }                   from '@noble/hashes/sha256';
+import { bytesToHex,
+         utf8ToBytes,
+         randomBytes }              from '@noble/hashes/utils';
+
+// ── Constants ─────────────────────────────────────────────────────────────────
+
+const TOKEN_VERSION = 2;
+
+/** 30-second TTL: short enough to prevent token brokers (resellers of valid
+ *  tokens scraped from legitimate devices), long enough to survive one API
+ *  round-trip on a slow connection. */
+const TOKEN_TTL_MS  = 30_000;
+
+const NONCE_BYTES   = 32;   // 256-bit nonce → 64-char hex
+
+// ── createEngagementToken ─────────────────────────────────────────────────────
+
+/**
+ * Create a physics-backed engagement token.
+ *
+ * Attach the returned `compact` string to your API call:
+ *   `fetch('/api/action', { headers: { 'X-Pulse-Token': token.compact } })`
+ *
+ * @param {object}         opts
+ * @param {object}         opts.pulseResult      result object from pulse()
+ * @param {IdleProof|null} opts.idleProof         from idleMonitor.getProof()
+ * @param {object}         opts.interaction       { type, ts, motorConsistency }
+ * @param {string}         opts.secret            shared HMAC secret (min 16 chars)
+ * @param {object}         [opts._overrides]      for deterministic testing only
+ * @returns {EngagementToken}
+ */
+export function createEngagementToken(opts) {
+  const {
+    pulseResult  = {},
+    idleProof    = null,
+    interaction  = {},
+    secret,
+    _overrides   = {},
+  } = opts;
+
+  _assertSecret(secret);
+
+  const n   = _overrides.nonce    ?? bytesToHex(randomBytes(NONCE_BYTES));
+  const iat = _overrides.issuedAt ?? Date.now();
+  const exp = iat + TOKEN_TTL_MS;
+
+  // ── Extract hardware evidence from pulse result ───────────────────────────
+  const extended = pulseResult.extended ?? {};
+  const dram     = extended.dram?.verdict ?? pulseResult.dram?.verdict ?? 'unavailable';
+  const enf      = extended.enf?.verdict  ?? pulseResult.enf?.verdict  ?? 'unavailable';
+  const ent      = _extractEntropyScore(pulseResult);
+
+  // ENF deviation for population-level phase coherence test
+  const enfDev   = extended.enf?.enfDeviation
+    ?? pulseResult.enf?.enfDeviation
+    ?? null;
+
+  // ── Pack idle evidence ────────────────────────────────────────────────────
+  const idle = idleProof
+    ? {
+        chain: idleProof.chain,
+        s:     idleProof.samples,
+        dMs:   idleProof.idleDurationMs,
+        therm: idleProof.thermalTransition,
+        mono:  idleProof.coolingMonotonicity,
+      }
+    : null;
+
+  // ── Pack interaction evidence ─────────────────────────────────────────────
+  const evt = {
+    t:   interaction.type             ?? 'unknown',
+    ts:  interaction.ts               ?? iat,
+    mot: +(interaction.motorConsistency ?? 0).toFixed(3),
+  };
+
+  // ── Sign and seal ─────────────────────────────────────────────────────────
+  const hw      = { dram, enf, ent, ...(enfDev != null && { enfDev }) };
+  const unsigned = { v: TOKEN_VERSION, n, iat, exp, idle, hw, evt };
+  const sig      = _sign(unsigned, secret);
+  const token    = { ...unsigned, sig };
+
+  return {
+    token,
+    compact:   _encode(token),
+    expiresAt: exp,
+  };
+}
+
+// ── verifyEngagementToken ─────────────────────────────────────────────────────
+
+/**
+ * Verify an engagement token on the server.
+ *
+ * Call this in your API handler before crediting any engagement metric.
+ * Failed verification returns `{ valid: false, reason }` — never throws.
+ *
+ * @param {string|object}  tokenOrCompact  compact base64url string or parsed token
+ * @param {string}         secret          shared HMAC secret
+ * @param {object}         [opts]
+ * @param {Function}       [opts.checkNonce]  async (nonce: string) => boolean
+ *                         Must atomically consume the nonce (Redis DEL returning 1,
+ *                         DB transaction with SELECT FOR UPDATE, etc.)
+ * @param {Function}       [opts.now]  override Date.now for testing: () => number
+ * @returns {Promise<EngagementVerifyResult>}
+ */
+export async function verifyEngagementToken(tokenOrCompact, secret, opts = {}) {
+  _assertSecret(secret);
+
+  // ── Parse ─────────────────────────────────────────────────────────────────
+  let token;
+  try {
+    token = typeof tokenOrCompact === 'string'
+      ? _decode(tokenOrCompact)
+      : tokenOrCompact;
+  } catch {
+    return _reject('malformed_token');
+  }
+
+  const { v, n, iat, exp, idle, hw, evt, sig } = token ?? {};
+
+  // ── Structural integrity ──────────────────────────────────────────────────
+  if (v !== TOKEN_VERSION)                         return _reject('unsupported_version');
+  if (!n || !/^[0-9a-f]{64}$/i.test(n))           return _reject('invalid_nonce');
+  if (!Number.isFinite(iat) || !Number.isFinite(exp) || !sig) {
+    return _reject('missing_required_fields');
+  }
+
+  // ── Freshness ─────────────────────────────────────────────────────────────
+  const now = (opts.now ?? Date.now)();
+  if (now > exp)         return _reject('token_expired',      { expiredByMs: now - exp });
+  if (iat > now + 5_000) return _reject('token_from_future');
+
+  // ── Signature verification (timing-safe comparison) ───────────────────────
+  const expected = _sign(token, secret);
+  if (!_timingSafeEqual(expected, sig)) {
+    return _reject('invalid_signature');
+  }
+
+  // ── Nonce consumption (replay prevention) ─────────────────────────────────
+  if (typeof opts.checkNonce === 'function') {
+    let consumed;
+    try   { consumed = await opts.checkNonce(n); }
+    catch { return _reject('nonce_check_error'); }
+    if (!consumed) return _reject('nonce_replayed');
+  }
+
+  // ── Advisory analysis (non-blocking) ─────────────────────────────────────
+  const idleWarnings = idle ? _checkIdlePlausibility(idle) : ['no_idle_proof'];
+  const riskSignals  = _assessRisk(hw, idle, evt);
+
+  return {
+    valid:        true,
+    token,
+    idleWarnings,
+    riskSignals,
+    issuedAt:     iat,
+    expiresAt:    exp,
+  };
+}
+
+// ── Encode / decode ───────────────────────────────────────────────────────────
+
+/**
+ * Encode a token object to a compact base64url string.
+ * @param {object} token
+ * @returns {string}
+ */
+export function encodeToken(token) {
+  return _encode(token);
+}
+
+/**
+ * Decode a compact string without verifying the signature.
+ * Safe for logging/debugging; use verifyEngagementToken for security checks.
+ * @param {string} compact
+ * @returns {object}
+ */
+export function decodeToken(compact) {
+  return _decode(compact);
+}
+
+// ── Risk assessment ───────────────────────────────────────────────────────────
+
+/**
+ * Advisory risk signals: concerns that don't outright invalidate the token
+ * but should inform downstream risk decisions.
+ *
+ * Returned in the `riskSignals` array of a successful verify result.
+ * Each entry: `{ code: string, severity: 'high'|'medium'|'low' }`.
+ */
+function _assessRisk(hw, idle, evt) {
+  const signals = [];
+
+  // Hardware layer
+  if (hw?.dram === 'virtual')   signals.push({ code: 'DRAM_VIRTUAL',          severity: 'high'   });
+  if (hw?.dram === 'ambiguous') signals.push({ code: 'DRAM_AMBIGUOUS',        severity: 'medium' });
+  if (hw?.enf  === 'no_grid_signal') signals.push({ code: 'NO_ENF_GRID',      severity: 'medium' });
+  if (hw?.ent != null && hw.ent < 0.35) {
+    signals.push({ code: 'LOW_ENTROPY_SCORE', severity: 'high' });
+  }
+
+  // Idle proof layer
+  if (!idle) {
+    signals.push({ code: 'NO_IDLE_PROOF', severity: 'medium' });
+  } else {
+    if (idle.therm === 'step_function')   signals.push({ code: 'STEP_FUNCTION_THERMAL',   severity: 'high'   });
+    if (idle.therm === 'sustained_hot')   signals.push({ code: 'SUSTAINED_LOAD_PATTERN',  severity: 'high'   });
+    if (idle.mono  < 0.30 && idle.s >= 3) signals.push({ code: 'NON_MONOTONIC_COOLING',   severity: 'medium' });
+    if (idle.dMs   < 50_000)              signals.push({ code: 'MINIMAL_IDLE_DURATION',    severity: 'low'    });
+  }
+
+  // Interaction layer
+  if (evt?.mot != null && evt.mot < 0.25) {
+    signals.push({ code: 'POOR_MOTOR_CONSISTENCY', severity: 'medium' });
+  }
+
+  return signals;
+}
+
+function _checkIdlePlausibility(idle) {
+  const w = [];
+  if (!idle.chain || idle.chain.length !== 64) w.push('malformed_chain_hash');
+  if (idle.s < 2)                              w.push('insufficient_chain_samples');
+  if (idle.therm === 'step_function')          w.push('step_function_transition');
+  if (idle.mono < 0.30 && idle.s >= 3)         w.push('non_monotonic_cooling');
+  return w;
+}
+
+// ── HMAC ──────────────────────────────────────────────────────────────────────
+
+function _sign({ v, n, iat, exp, idle, hw, evt }, secret) {
+  // All fields an attacker might want to inflate/swap are in the signed body.
+  // Advisory fields (therm, mono, dram labels) are deliberately excluded —
+  // they're useful for risk scoring but not for access control.
+  const body = [
+    v,
+    n,
+    iat,
+    exp,
+    idle?.chain ?? 'null',
+    idle?.dMs   ?? 'null',
+    hw?.ent     ?? 'null',
+    evt?.t      ?? 'null',
+    evt?.ts     ?? 'null',
+  ].join('|');
+
+  const mac = hmac(sha256, utf8ToBytes(secret), utf8ToBytes(body));
+  return bytesToHex(mac);
+}
+
+/**
+ * Pure-JS timing-safe string comparison for hex strings.
+ * Operates on char codes — constant time for equal-length inputs.
+ * V8 does not optimize away XOR accumulation on Uint8 arithmetic.
+ */
+function _timingSafeEqual(a, b) {
+  if (typeof a !== 'string' || typeof b !== 'string') return false;
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) {
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return diff === 0;
+}
+
+// ── Encode / decode (base64url) ───────────────────────────────────────────────
+
+function _encode(token) {
+  const bytes = utf8ToBytes(JSON.stringify(token));
+  if (typeof Buffer !== 'undefined') {
+    return Buffer.from(bytes).toString('base64url');
+  }
+  // Browser: manual base64url encoding
+  return btoa(String.fromCharCode(...bytes))
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=/g,  '');
+}
+
+function _decode(compact) {
+  // Normalize base64url to standard base64 with padding
+  let b64 = compact.replace(/-/g, '+').replace(/_/g, '/');
+  while (b64.length % 4) b64 += '=';
+
+  let bytes;
+  if (typeof Buffer !== 'undefined') {
+    bytes = Buffer.from(b64, 'base64');
+  } else {
+    const str = atob(b64);
+    bytes = Uint8Array.from(str, c => c.charCodeAt(0));
+  }
+
+  return JSON.parse(new TextDecoder().decode(bytes));
+}
+
+// ── Misc helpers ──────────────────────────────────────────────────────────────
+
+function _reject(reason, meta = {}) {
+  return { valid: false, reason, ...meta };
+}
+
+function _assertSecret(secret) {
+  if (!secret || typeof secret !== 'string' || secret.length < 16) {
+    throw new Error(
+      '@svrnsec/pulse: engagement token secret must be ≥ 16 characters. ' +
+      'Generate one with: import { generateSecret } from "@svrnsec/pulse/challenge"'
+    );
+  }
+}
+
+function _extractEntropyScore(pulseResult) {
+  // Normalize jitter score (0–1) from wherever it lives in the result tree
+  const score =
+    pulseResult?.payload?.classification?.jitterScore ??
+    pulseResult?.classification?.jitterScore          ??
+    pulseResult?.jitterScore                          ??
+    null;
+  return score != null ? +Number(score).toFixed(3) : null;
+}
+
+// ── JSDoc types ───────────────────────────────────────────────────────────────
+
+/**
+ * @typedef {object} EngagementToken
+ * @property {object} token      full parsed token object
+ * @property {string} compact    base64url-encoded compact form (attach to API headers)
+ * @property {number} expiresAt  Unix ms expiry timestamp
+ */
+
+/**
+ * @typedef {object} EngagementVerifyResult
+ * @property {boolean}    valid          true if all checks passed
+ * @property {string}     [reason]       rejection reason code (when valid=false)
+ * @property {number}     [expiredByMs]  how many ms ago it expired (when reason=token_expired)
+ * @property {object}     [token]        parsed token (when valid=true)
+ * @property {string[]}   [idleWarnings] advisory idle-proof warnings
+ * @property {object[]}   [riskSignals]  non-fatal risk indicators with severity
+ * @property {number}     [issuedAt]     Unix ms issued-at
+ * @property {number}     [expiresAt]    Unix ms expiry
+ */

package/src/terminal.js

@@ -0,0 +1,263 @@
+/**
+ * @svrnsec/pulse — Terminal Result Renderer
+ *
+ * Pretty-prints probe results to the terminal for Node.js server usage.
+ * Used by middleware and the CLI so developers see clean, actionable output
+ * during integration and debugging — not raw JSON.
+ *
+ * Zero dependencies. Pure ANSI escape codes.
+ * Automatically disabled when stdout is not a TTY or NO_COLOR is set.
+ */
+
+/* ─── TTY guard ──────────────────────────────────────────────────────────── */
+
+const isTTY = () =>
+  typeof process !== 'undefined' &&
+  process.stderr?.isTTY === true &&
+  process.env?.NO_COLOR == null;
+
+const c = isTTY;
+
+/* ─── ANSI color palette ─────────────────────────────────────────────────── */
+
+const A = {
+  reset:   '\x1b[0m',
+  bold:    '\x1b[1m',
+  dim:     '\x1b[2m',
+  // foreground — normal
+  red:     '\x1b[31m',
+  green:   '\x1b[32m',
+  yellow:  '\x1b[33m',
+  blue:    '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan:    '\x1b[36m',
+  white:   '\x1b[37m',
+  gray:    '\x1b[90m',
+  // foreground — bright
+  bred:    '\x1b[91m',
+  bgreen:  '\x1b[92m',
+  byellow: '\x1b[93m',
+  bblue:   '\x1b[94m',
+  bmagenta:'\x1b[95m',
+  bcyan:   '\x1b[96m',
+  bwhite:  '\x1b[97m',
+};
+
+const paint = (code, s) => c() ? `${code}${s}${A.reset}` : s;
+const dim   = (s) => paint(A.dim,     s);
+const bold  = (s) => paint(A.bold,    s);
+const gray  = (s) => paint(A.gray,    s);
+const cyan  = (s) => paint(A.cyan,    s);
+const green = (s) => paint(A.bgreen,  s);
+const red   = (s) => paint(A.bred,    s);
+const yel   = (s) => paint(A.byellow, s);
+const mag   = (s) => paint(A.bmagenta,s);
+const wh    = (s) => paint(A.bwhite,  s);
+
+function stripAnsi(s) {
+  // eslint-disable-next-line no-control-regex
+  return s.replace(/\x1b\[[0-9;]*m/g, '');
+}
+const visLen = (s) => stripAnsi(s).length;
+
+/* ─── bar renderer ───────────────────────────────────────────────────────── */
+
+/**
+ * Render a horizontal progress / confidence bar.
+ * @param {number}  pct      0–1
+ * @param {number}  width    character width of the bar
+ * @param {string}  fillCode ANSI color code for filled blocks
+ */
+function bar(pct, width = 20, fillCode = A.bgreen) {
+  const filled = Math.round(Math.min(1, Math.max(0, pct)) * width);
+  const empty  = width - filled;
+  const fill   = c() ? `${fillCode}${'█'.repeat(filled)}${A.reset}` : '█'.repeat(filled);
+  const void_  = gray('░'.repeat(empty));
+  return fill + void_;
+}
+
+/* ─── verdict badge ──────────────────────────────────────────────────────── */
+
+function verdictBadge(result) {
+  if (!result) return gray('  PENDING   ');
+  const { valid, score, confidence } = result;
+
+  if (valid && confidence === 'high')   return green('  ✓ PASS     ');
+  if (valid && confidence === 'medium') return yel('  ⚠ PASS     ');
+  if (!valid && score < 0.3)            return red('  ✗ BLOCKED  ');
+  return yel('  ⚠ REVIEW  ');
+}
+
+/* ─── renderProbeResult ──────────────────────────────────────────────────── */
+
+/**
+ * Print a formatted probe result card to stderr.
+ *
+ * @param {object} opts
+ * @param {object}  opts.payload          - ProofPayload from pulse()
+ * @param {string}  opts.hash             - BLAKE3 hex commitment
+ * @param {object}  [opts.result]         - ValidationResult (server-side verify)
+ * @param {object}  [opts.enf]            - EnfResult if available
+ * @param {object}  [opts.gpu]            - GpuEntropyResult if available
+ * @param {object}  [opts.dram]           - DramResult if available
+ * @param {object}  [opts.llm]            - LlmResult if available
+ * @param {number}  [opts.elapsedMs]      - total probe time
+ */
+export function renderProbeResult({ payload, hash, result, enf, gpu, dram, llm, elapsedMs }) {
+  if (!c()) return;
+
+  const W    = 54;
+  const hr   = gray('─'.repeat(W));
+  const vbar = gray('│');
+
+  const row = (label, value, valueColor = A.bwhite) => {
+    const lbl  = gray(label.padEnd(24));
+    const val  = c() ? `${valueColor}${value}${A.reset}` : String(value);
+    const line = `  ${lbl}${val}`;
+    const pad  = ' '.repeat(Math.max(0, W - visLen(line) - 2));
+    process.stderr.write(`${vbar}${line}${pad}  ${vbar}\n`);
+  };
+
+  const blank = () => {
+    process.stderr.write(`${vbar}${' '.repeat(W + 2)}${vbar}\n`);
+  };
+
+  const section = (title) => {
+    const t   = `  ${bold(title)}`;
+    const pad = ' '.repeat(Math.max(0, W - visLen(t) - 2));
+    process.stderr.write(`${vbar}${t}${pad}  ${vbar}\n`);
+  };
+
+  const badge = verdictBadge(result);
+  const hashShort = hash ? hash.slice(0, 16) + '…' : 'pending';
+  const elapsed   = elapsedMs ? `${(elapsedMs / 1000).toFixed(2)}s` : '—';
+
+  const sigs = payload?.signals ?? {};
+  const cls  = payload?.classification ?? {};
+  const jScore = cls.jitterScore ?? 0;
+
+  // ── Physics signals ──────────────────────────────────────────────────────
+  const qe        = sigs.entropy?.quantizationEntropy ?? 0;
+  const hurst     = sigs.entropy?.hurstExponent ?? 0;
+  const cv        = sigs.entropy?.timingsCV ?? 0;
+  const ejrClass  = qe >= 1.08 ? A.bgreen : qe >= 0.95 ? A.byellow : A.bred;
+  const hwConf    = result?.confidence === 'high' ? 1.0 : result?.confidence === 'medium' ? 0.65 : 0.3;
+  const vmConf    = 1 - hwConf;
+
+  // ── ENF signals ──────────────────────────────────────────────────────────
+  const enfRegion = enf?.gridRegion === 'americas' ? '60 Hz  Americas'
+    : enf?.gridRegion === 'emea_apac'              ? '50 Hz  EMEA/APAC'
+    : enf?.enfAvailable === false                  ? 'unavailable'
+    : '—';
+  const enfColor = enf?.ripplePresent ? A.bgreen : enf?.enfAvailable === false ? A.gray : A.byellow;
+
+  // ── GPU signals ──────────────────────────────────────────────────────────
+  const gpuStr    = gpu?.gpuPresent
+    ? (gpu.isSoftware ? red('Software renderer') : green(gpu.vendorString ?? 'GPU detected'))
+    : gray('unavailable');
+
+  // ── DRAM signals ─────────────────────────────────────────────────────────
+  const dramStr   = dram?.refreshPresent
+    ? green(`${(dram.refreshPeriodMs ?? 0).toFixed(1)} ms  (DDR4 JEDEC ✓)`)
+    : dram ? red('No refresh cycle (VM)') : gray('unavailable');
+
+  // ── LLM signals ──────────────────────────────────────────────────────────
+  const llmStr    = llm
+    ? (llm.aiConf > 0.7 ? red(`AI agent  ${(llm.aiConf * 100).toFixed(0)}%`) : green(`Human  ${((1 - llm.aiConf) * 100).toFixed(0)}%`))
+    : gray('no bio data');
+
+  // ── Render ───────────────────────────────────────────────────────────────
+  const topTitle  = `  ${mag('SVRN')}${wh(':PULSE')}  ${badge}`;
+  const topPad    = ' '.repeat(Math.max(0, W - visLen(topTitle) - 2));
+  const topBorder = gray('╭' + '─'.repeat(W + 2) + '╮');
+  const botBorder = gray('╰' + '─'.repeat(W + 2) + '╯');
+
+  process.stderr.write('\n');
+  process.stderr.write(topBorder + '\n');
+  process.stderr.write(`${vbar}${topTitle}${topPad}  ${vbar}\n`);
+  process.stderr.write(gray('├' + '─'.repeat(W + 2) + '┤') + '\n');
+  blank();
+
+  section('PHYSICS LAYER');
+  blank();
+  row('Jitter score',     (jScore * 100).toFixed(1) + '%',    jScore > 0.7 ? A.bgreen : jScore > 0.45 ? A.byellow : A.bred);
+  row('QE (entropy)',     qe.toFixed(3),                       ejrClass);
+  row('Hurst exponent',   hurst.toFixed(4),                    Math.abs(hurst - 0.5) < 0.1 ? A.bgreen : A.byellow);
+  row('Timing CV',        cv.toFixed(4),                       cv > 0.08 ? A.bgreen : A.byellow);
+  row('Timer granularity',`${((sigs.entropy?.timerGranularityMs ?? 0) * 1000).toFixed(1)} µs`, A.bcyan);
+  blank();
+
+  const hwBar = bar(hwConf, 18, A.bgreen);
+  const vmBar = bar(vmConf, 18, A.bred);
+  row('HW confidence',    hwBar + '  ' + (hwConf * 100).toFixed(0) + '%');
+  row('VM confidence',    vmBar + '  ' + (vmConf * 100).toFixed(0) + '%');
+
+  blank();
+  process.stderr.write(gray('├' + '─'.repeat(W + 2) + '┤') + '\n');
+  blank();
+
+  section('SIGNAL LAYERS');
+  blank();
+  row('Grid (ENF)',        enfRegion,   enfColor);
+  process.stderr.write(`${vbar}  ${gray('GPU (thermal)')}${' '.repeat(10)}${gpuStr}  ${vbar}\n`);
+  process.stderr.write(`${vbar}  ${gray('DRAM refresh')} ${' '.repeat(11)}${dramStr}  ${vbar}\n`);
+  process.stderr.write(`${vbar}  ${gray('Behavioral (LLM)')}${' '.repeat(7)}${llmStr}  ${vbar}\n`);
+
+  blank();
+  process.stderr.write(gray('├' + '─'.repeat(W + 2) + '┤') + '\n');
+  blank();
+
+  section('PROOF');
+  blank();
+  row('BLAKE3',           hashShort,   A.bcyan);
+  row('Nonce',            (payload?.nonce ?? '').slice(0, 16) + '…', A.gray);
+  row('Elapsed',          elapsed,     A.gray);
+  if (result) {
+    row('Server verdict', result.valid ? 'valid' : 'rejected', result.valid ? A.bgreen : A.bred);
+    row('Score',          ((result.score ?? 0) * 100).toFixed(1) + '%', A.bwhite);
+    if ((result.riskFlags ?? []).length > 0) {
+      blank();
+      row('Risk flags', result.riskFlags.join(', '), A.byellow);
+    }
+  }
+  blank();
+  process.stderr.write(botBorder + '\n\n');
+}
+
+/* ─── renderError ────────────────────────────────────────────────────────── */
+
+/**
+ * Print a formatted error card for pulse() failures.
+ * @param {Error|string} err
+ */
+export function renderError(err) {
+  if (!c()) return;
+  const msg  = err?.message ?? String(err);
+  const W    = 54;
+  const vbar = gray('│');
+
+  process.stderr.write('\n');
+  process.stderr.write(red('╭' + '─'.repeat(W + 2) + '╮') + '\n');
+  process.stderr.write(`${red('│')}  ${red('✗')} ${bold('SVRN:PULSE — probe failed')}${' '.repeat(Math.max(0, W - 28))}  ${red('│')}\n`);
+  process.stderr.write(red('├' + '─'.repeat(W + 2) + '┤') + '\n');
+  process.stderr.write(`${vbar}  ${gray(msg.slice(0, W - 2).padEnd(W))}  ${vbar}\n`);
+  process.stderr.write(red('╰' + '─'.repeat(W + 2) + '╯') + '\n\n');
+}
+
+/* ─── renderUpdateBanner ─────────────────────────────────────────────────── */
+
+/**
+ * Render a simple one-line update available hint inline (used by middleware).
+ * @param {string} latest
+ */
+export function renderInlineUpdateHint(latest) {
+  if (!c()) return;
+  process.stderr.write(
+    gray('  ╴╴╴  ') +
+    yel('update available ') +
+    gray(latest) +
+    '  ' + cyan('npm i @svrnsec/pulse@latest') +
+    gray('  ╴╴╴') +
+    '\n'
+  );
+}