@svrnsec/pulse 0.3.0 → 0.4.0

package/src/proof/fingerprint.js

@@ -54,9 +54,9 @@ export function blake3HexStr(str) {
  * @param {string}  p.nonce    – server-issued challenge nonce (hex)
  * @returns {ProofPayload}
  */
-export function buildProof({ entropy, jitter, bio, canvas, audio, nonce }) {
+export function buildProof({ entropy, jitter, bio, canvas, audio, enf, gpu, dram, llm, nonce }) {
   if (!nonce || typeof nonce !== 'string') {
-    throw new Error('@sovereign/pulse: nonce is required for anti-replay protection');
+    throw new Error('@svrnsec/pulse: nonce is required for anti-replay protection');
   }
 
   // Hash the raw timing arrays IN-BROWSER so we can prove their integrity
@@ -138,12 +138,68 @@ export function buildProof({ entropy, jitter, bio, canvas, audio, nonce }) {
         jitterMeanMs:         _round(audio.jitterMeanMs,        4),
         jitterP95Ms:          _round(audio.jitterP95Ms,         4),
       },
+
+      // ── Electrical Network Frequency ─────────────────────────────────────
+      enf: enf ? {
+        available:       enf.enfAvailable,
+        ripplePresent:   enf.ripplePresent,
+        gridFrequency:   enf.gridFrequency,
+        gridRegion:      enf.gridRegion,
+        ripplePower:     _round(enf.ripplePower,    4),
+        enfDeviation:    _round(enf.enfDeviation,   3),
+        snr50hz:         _round(enf.snr50hz,        2),
+        snr60hz:         _round(enf.snr60hz,        2),
+        sampleRateHz:    _round(enf.sampleRateHz,   1),
+        verdict:         enf.verdict,
+        isVmIndicator:   enf.isVmIndicator,
+        capturedAt:      enf.temporalAnchor?.capturedAt ?? null,
+      } : null,
+
+      // ── WebGPU thermal variance ───────────────────────────────────────────
+      gpu: gpu ? {
+        available:       gpu.gpuPresent,
+        isSoftware:      gpu.isSoftware,
+        vendorString:    gpu.vendorString,
+        dispatchCV:      _round(gpu.dispatchCV,     4),
+        thermalGrowth:   _round(gpu.thermalGrowth,  4),
+        verdict:         gpu.verdict,
+      } : null,
+
+      // ── DRAM refresh cycle ────────────────────────────────────────────────
+      dram: dram ? {
+        refreshPresent:  dram.refreshPresent,
+        refreshPeriodMs: _round(dram.refreshPeriodMs, 2),
+        peakPower:       _round(dram.peakPower,        4),
+        verdict:         dram.verdict,
+      } : null,
+
+      // ── LLM / AI agent behavioral fingerprint ────────────────────────────
+      llm: llm ? {
+        aiConf:             _round(llm.aiConf,            3),
+        thinkTimePattern:   llm.thinkTimePattern,
+        correctionRate:     _round(llm.correctionRate,    3),
+        rhythmicity:        _round(llm.rhythmicity,       3),
+        pauseDistribution:  llm.pauseDistribution,
+        verdict:            llm.verdict,
+        matchedModel:       llm.matchedModel ?? null,
+      } : null,
     },
 
-    // Top-level classification summary
+    // Top-level classification summary — all signal layers combined
     classification: {
-      jitterScore:  _round(jitter.score, 4),
-      flags:        jitter.flags ?? [],
+      jitterScore:    _round(jitter.score, 4),
+      flags:          jitter.flags ?? [],
+      enfVerdict:     enf?.verdict  ?? 'unavailable',
+      gpuVerdict:     gpu?.verdict  ?? 'unavailable',
+      dramVerdict:    dram?.verdict ?? 'unavailable',
+      llmVerdict:     llm?.verdict  ?? 'unavailable',
+      // Combined VM confidence: any hard signal raises this
+      vmIndicators: [
+        enf?.isVmIndicator  ? 'enf_no_grid'     : null,
+        gpu?.isSoftware     ? 'gpu_software'     : null,
+        dram?.verdict === 'virtual' ? 'dram_no_refresh' : null,
+        llm?.aiConf > 0.7   ? 'llm_agent'        : null,
+      ].filter(Boolean),
     },
   };
 

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'
+  );
+}

package/src/update-notifier.js

@@ -0,0 +1,264 @@
+/**
+ * @svrnsec/pulse — Update Notifier
+ *
+ * Checks the npm registry for a newer version and prints a styled terminal
+ * notice when one is available. Non-blocking — the check runs in the
+ * background and only displays if a newer version is found before the
+ * process exits.
+ *
+ * Zero dependencies. Pure Node.js https module.
+ * Silent in browser environments and when stdout is not a TTY.
+ */
+
+import { createRequire } from 'module';
+
+/* ─── version from package.json ─────────────────────────────────────────── */
+
+let _currentVersion = '0.0.0';
+try {
+  const require = createRequire(import.meta.url);
+  _currentVersion = require('../package.json').version;
+} catch {}
+
+export const CURRENT_VERSION = _currentVersion;
+
+/* ─── ANSI helpers ───────────────────────────────────────────────────────── */
+
+const isTTY   = () =>
+  typeof process !== 'undefined' &&
+  process.stdout?.isTTY === true &&
+  process.env?.NO_COLOR == null &&
+  process.env?.PULSE_NO_UPDATE == null;
+
+const isNode  = () => typeof process !== 'undefined' && typeof window === 'undefined';
+
+const C = {
+  reset:     '\x1b[0m',
+  bold:      '\x1b[1m',
+  dim:       '\x1b[2m',
+  // foreground
+  black:     '\x1b[30m',
+  red:       '\x1b[31m',
+  green:     '\x1b[32m',
+  yellow:    '\x1b[33m',
+  blue:      '\x1b[34m',
+  magenta:   '\x1b[35m',
+  cyan:      '\x1b[36m',
+  white:     '\x1b[37m',
+  // bright foreground
+  bgray:     '\x1b[90m',
+  bred:      '\x1b[91m',
+  bgreen:    '\x1b[92m',
+  byellow:   '\x1b[93m',
+  bblue:     '\x1b[94m',
+  bmagenta:  '\x1b[95m',
+  bcyan:     '\x1b[96m',
+  bwhite:    '\x1b[97m',
+  // background
+  bgBlack:   '\x1b[40m',
+  bgYellow:  '\x1b[43m',
+  bgBlue:    '\x1b[44m',
+  bgCyan:    '\x1b[46m',
+};
+
+const c  = isTTY;
+const ft = (code, s) => c() ? `${code}${s}${C.reset}` : s;
+
+/* ─── box renderer ───────────────────────────────────────────────────────── */
+
+/**
+ * Render a bordered notification box to stderr.
+ * Uses box-drawing characters and ANSI colors when the terminal supports them.
+ */
+function _box(lines, opts = {}) {
+  const { borderColor = C.yellow, titleColor = C.bwhite } = opts;
+  const pad   = 2;
+  const width = Math.max(...lines.map(l => _visLen(l))) + pad * 2;
+  const hr    = '─'.repeat(width);
+  const bc    = (s) => c() ? `${borderColor}${s}${C.reset}` : s;
+
+  const out = [
+    bc(`╭${hr}╮`),
+    ...lines.map(l => {
+      const vis  = _visLen(l);
+      const fill = ' '.repeat(Math.max(0, width - vis - pad * 2));
+      return bc('│') + ' '.repeat(pad) + (c() ? l : _stripAnsi(l)) + fill + ' '.repeat(pad) + bc('│');
+    }),
+    bc(`╰${hr}╯`),
+  ];
+
+  process.stderr.write('\n' + out.join('\n') + '\n\n');
+}
+
+/* ─── version comparison ─────────────────────────────────────────────────── */
+
+function _semverGt(a, b) {
+  const pa = a.replace(/[^0-9.]/g, '').split('.').map(Number);
+  const pb = b.replace(/[^0-9.]/g, '').split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    const da = pa[i] ?? 0, db = pb[i] ?? 0;
+    if (da > db) return true;
+    if (da < db) return false;
+  }
+  return false;
+}
+
+/* ─── registry fetch ─────────────────────────────────────────────────────── */
+
+async function _fetchLatest(pkg) {
+  return new Promise((resolve) => {
+    let resolved = false;
+    const done = (v) => { if (!resolved) { resolved = true; resolve(v); } };
+
+    const timeout = setTimeout(() => done(null), 3_000);
+
+    try {
+      const https = require('https');
+      const req   = https.get(
+        `https://registry.npmjs.org/${encodeURIComponent(pkg)}/latest`,
+        { headers: { 'Accept': 'application/json', 'User-Agent': `${pkg}/${_currentVersion}` } },
+        (res) => {
+          let body = '';
+          res.setEncoding('utf8');
+          res.on('data', d => body += d);
+          res.on('end', () => {
+            clearTimeout(timeout);
+            try { done(JSON.parse(body).version ?? null); } catch { done(null); }
+          });
+        }
+      );
+      req.on('error', () => { clearTimeout(timeout); done(null); });
+      req.end();
+    } catch {
+      clearTimeout(timeout);
+      done(null);
+    }
+  });
+}
+
+// Lazy require for Node.js https module (avoids bundler issues)
+let _httpsReq = null;
+function require(m) {
+  if (typeof globalThis.require === 'function') return globalThis.require(m);
+  // CJS interop — only used server-side
+  if (typeof process !== 'undefined') {
+    const mod = process.mainModule?.require ?? (() => null);
+    return mod(m);
+  }
+  return null;
+}
+
+/* ─── checkForUpdate ─────────────────────────────────────────────────────── */
+
+/**
+ * Check npm for a newer version of @svrnsec/pulse.
+ * Call once at process startup — the result is shown before process exit
+ * (or immediately if already resolved).
+ *
+ * @param {object} [opts]
+ * @param {boolean} [opts.silent=false]  suppress output even when update exists
+ * @param {string}  [opts.pkg='@svrnsec/pulse']
+ * @returns {Promise<{ current: string, latest: string|null, updateAvailable: boolean }>}
+ */
+export async function checkForUpdate(opts = {}) {
+  const { silent = false, pkg = '@svrnsec/pulse' } = opts;
+
+  if (!isNode()) return { current: _currentVersion, latest: null, updateAvailable: false };
+
+  const latest = await _fetchLatest(pkg);
+  const updateAvailable = latest != null && _semverGt(latest, _currentVersion);
+
+  if (updateAvailable && !silent && isTTY()) {
+    _showUpdateBox(_currentVersion, latest, pkg);
+  }
+
+  return { current: _currentVersion, latest, updateAvailable };
+}
+
+/* ─── notifyOnExit ───────────────────────────────────────────────────────── */
+
+let _notifyRegistered = false;
+
+/**
+ * Register a one-time process 'exit' listener that prints the update notice
+ * after your application's own output has finished. This is the least
+ * intrusive way to show the notification.
+ *
+ * Called automatically by the package initialiser — you do not need to call
+ * this manually unless you want to control the timing.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.pkg='@svrnsec/pulse']
+ */
+export function notifyOnExit(opts = {}) {
+  if (!isNode() || _notifyRegistered) return;
+  _notifyRegistered = true;
+
+  const pkg = opts.pkg ?? '@svrnsec/pulse';
+  let _latest = null;
+
+  // Start the background check immediately
+  _fetchLatest(pkg).then(v => { _latest = v; }).catch(() => {});
+
+  // Show the box just before the process exits (after all user output)
+  process.on('exit', () => {
+    if (_latest && _semverGt(_latest, _currentVersion) && isTTY()) {
+      _showUpdateBox(_currentVersion, _latest, pkg);
+    }
+  });
+}
+
+/* ─── banner ─────────────────────────────────────────────────────────────── */
+
+/**
+ * Print the @svrnsec/pulse ASCII banner to stderr.
+ * Called once at package initialisation in Node.js environments.
+ */
+export function printBanner() {
+  if (!isNode() || !isTTY()) return;
+
+  const v   = ft(C.bgray, `v${_currentVersion}`);
+  const tag = ft(C.bmagenta + C.bold, 'SVRN');
+  const pkg = ft(C.bwhite  + C.bold, ':PULSE');
+
+  process.stderr.write(
+    '\n' +
+    ft(C.bgray, '  ┌─────────────────────────────────────┐') + '\n' +
+    ft(C.bgray, '  │') + `  ${tag}${pkg}  ` + ft(C.bgray, '─  Physical Turing Test  │') + '\n' +
+    ft(C.bgray, '  │') + `  ${ft(C.bgray, 'Hardware-Biological Symmetry Protocol')}  ` + ft(C.bgray, '│') + '\n' +
+    ft(C.bgray, '  │') + `  ${ft(C.bcyan, 'npm i @svrnsec/pulse')}  ${' '.repeat(16)}${v}  ` + ft(C.bgray, '│') + '\n' +
+    ft(C.bgray, '  └─────────────────────────────────────┘') + '\n\n'
+  );
+}
+
+/* ─── _showUpdateBox ─────────────────────────────────────────────────────── */
+
+function _showUpdateBox(current, latest, pkg) {
+  const arrow  = ft(C.bgray, '→');
+  const oldV   = ft(C.bred,    current);
+  const newV   = ft(C.bgreen + C.bold, latest);
+  const cmd    = ft(C.bcyan + C.bold, `npm i ${pkg}@latest`);
+  const notice = ft(C.byellow + C.bold, '  UPDATE AVAILABLE  ');
+
+  _box([
+    notice,
+    '',
+    `  ${oldV}  ${arrow}  ${newV}`,
+    '',
+    `  Run:  ${cmd}`,
+    '',
+    ft(C.bgray, `  Changelog: https://github.com/ayronny14-alt/Svrn-Pulse-Security/releases`),
+  ], { borderColor: C.byellow });
+}
+
+/* ─── ANSI utilities ─────────────────────────────────────────────────────── */
+
+// Measure visible length of string (strip ANSI escape codes)
+function _visLen(s) {
+  return _stripAnsi(s).length;
+}
+
+function _stripAnsi(s) {
+  // eslint-disable-next-line no-control-regex
+  return s.replace(/\x1b\[[0-9;]*m/g, '');
+}