@svrnsec/pulse 0.3.1 → 0.5.0

package/src/collector/enf.js

@@ -0,0 +1,311 @@
+/**
+ * @sovereign/pulse — Electrical Network Frequency (ENF) Detection
+ *
+ * ┌─────────────────────────────────────────────────────────────────────────┐
+ * │  WHAT THIS IS                                                           │
+ * │                                                                         │
+ * │  Power grids operate at a nominal frequency — 60 Hz in the Americas,   │
+ * │  50 Hz in Europe, Asia, Africa, and Australia. This frequency is not   │
+ * │  perfectly stable. It deviates by ±0.05 Hz in real time as generators  │
+ * │  spin up and down to match load. These deviations are unique, logged   │
+ * │  by grid operators, and have been used in forensics since 2010 to      │
+ * │  timestamp recordings to within seconds.                               │
+ * │                                                                         │
+ * │  We are the first to measure it from a browser.                        │
+ * └─────────────────────────────────────────────────────────────────────────┘
+ *
+ * Signal path
+ * ───────────
+ *   AC mains (50/60 Hz)
+ *     → ATX power supply (full-wave rectified → 100/120 Hz ripple on DC rail)
+ *     → Voltage Regulator Module (VRM) on motherboard
+ *     → CPU Vcore (supply voltage to processor dies)
+ *     → Transistor switching speed (slightly modulated by Vcore)
+ *     → Matrix multiply loop timing (measurably longer when Vcore dips)
+ *     → Our microsecond-resolution timing probe
+ *
+ * The ripple amplitude at the timing layer is ~10–100 ns — invisible to
+ * performance.now() at 1 ms resolution, clearly visible with Atomics-based
+ * microsecond timing. This is why this module depends on sabTimer.js.
+ *
+ * What we detect
+ * ──────────────
+ *   gridFrequency    50.0 or 60.0 Hz (nominal), ±0.5 Hz measured
+ *   gridRegion       'americas' (60 Hz) | 'emea_apac' (50 Hz) | 'unknown'
+ *   ripplePresent    true if the 100/120 Hz harmonic is statistically significant
+ *   ripplePower      power of the dominant grid harmonic (0–1)
+ *   enfDeviation     precise measured frequency – nominal (Hz) — temporal fingerprint
+ *   temporalHash     BLAKE3 of (enfDeviation + timestamp) — attestation anchor
+ *
+ * What this proves
+ * ───────────────
+ *   1. The device is connected to a real AC power grid (rules out cloud VMs,
+ *      UPS-backed datacenter servers, and battery-only devices off-grid)
+ *   2. The geographic grid region (50 Hz vs 60 Hz — no IP, no location API)
+ *   3. A temporal fingerprint that can be cross-referenced against public ENF
+ *      logs (e.g., www.gridwatch.templar.linux.org.uk) to verify the session
+ *      timestamp is authentic
+ *
+ * Why VMs fail
+ * ────────────
+ *   Datacenter power is conditioned, filtered, and UPS-backed. Grid frequency
+ *   deviations are removed before they reach the server. Cloud VMs receive
+ *   perfectly regulated power — the ENF signal does not exist in their timing
+ *   measurements. This is a physical property of datacenter infrastructure,
+ *   not a software configuration that can be patched or spoofed.
+ *
+ *   A VM attempting to inject synthetic ENF ripple into its virtual clock
+ *   would need to:
+ *     1. Know the real-time ENF of the target grid region (requires live API)
+ *     2. Modulate the virtual TSC at sub-microsecond precision
+ *     3. Match the precise VRM transfer function of the target motherboard
+ *   This is not a realistic attack surface.
+ *
+ * Battery devices
+ * ───────────────
+ *   Laptops on battery have no AC ripple. The module detects this via absence
+ *   of both 100 Hz and 120 Hz signal, combined with very low ripple variance.
+ *   This is handled by the 'battery_or_conditioned' verdict — treated as
+ *   inconclusive rather than VM (real laptops exist).
+ *
+ * Required: crossOriginIsolated = true (COOP + COEP headers)
+ * The SAB microsecond timer is required for ENF detection. On browsers where
+ * it is unavailable, the module returns { enfAvailable: false }.
+ */
+
+import { isSabAvailable, collectHighResTimings } from './sabTimer.js';
+
+// ── Grid frequency constants ──────────────────────────────────────────────────
+const GRID_60HZ_NOMINAL   = 60.0;  // Americas, parts of Japan & Korea
+const GRID_50HZ_NOMINAL   = 50.0;  // EMEA, APAC, most of Asia
+const RIPPLE_60HZ         = 120.0; // Full-wave rectified: 2 × 60 Hz
+const RIPPLE_50HZ         = 100.0; // Full-wave rectified: 2 × 50 Hz
+const RIPPLE_SLACK_HZ     = 2.0;   // ±2 Hz around nominal (accounts for VRM response)
+const MIN_RIPPLE_POWER    = 0.04;  // Minimum power ratio to declare ripple present
+const SNR_THRESHOLD       = 2.0;   // Signal-to-noise ratio for confident detection
+
+// ── Probe parameters ──────────────────────────────────────────────────────────
+// We need enough samples at sufficient rate to resolve 100–120 Hz.
+// Nyquist: sample_rate > 240 Hz (need >2× the highest target frequency).
+// With ~1 ms per iteration, 100 Hz ≈ 10 samples per cycle — adequate.
+// We want at least 20 full cycles → 200 iterations minimum.
+const PROBE_ITERATIONS    = 512;   // power of 2 for clean FFT
+const PROBE_MATRIX_SIZE   = 16;    // small matrix → ~1 ms/iter → ~500 Hz sample rate
+
+/* ─── collectEnfTimings ─────────────────────────────────────────────────────── */
+
+/**
+ * @param {object}  [opts]
+ * @param {number}  [opts.iterations=512]
+ * @returns {Promise<EnfResult>}
+ */
+export async function collectEnfTimings(opts = {}) {
+  const { iterations = PROBE_ITERATIONS } = opts;
+
+  if (!isSabAvailable()) {
+    return _noEnf('SharedArrayBuffer not available — COOP+COEP headers required');
+  }
+
+  // Collect high-resolution CPU timing series
+  const { timings, resolutionUs } = collectHighResTimings({
+    iterations,
+    matrixSize: PROBE_MATRIX_SIZE,
+  });
+
+  if (timings.length < 128) {
+    return _noEnf('insufficient timing samples');
+  }
+
+  // Estimate the sample rate from actual timing
+  const meanIterMs = timings.reduce((s, v) => s + v, 0) / timings.length;
+  const sampleRateHz = meanIterMs > 0 ? 1000 / meanIterMs : 0;
+
+  if (sampleRateHz < 60) {
+    return _noEnf(`sample rate too low for ENF detection: ${sampleRateHz.toFixed(0)} Hz`);
+  }
+
+  // ── Power Spectral Density ────────────────────────────────────────────────
+  const n       = timings.length;
+  const psd     = _computePsd(timings, sampleRateHz);
+
+  // Find the dominant frequency peak
+  const peakIdx  = psd.reduce((best, v, i) => v > psd[best] ? i : best, 0);
+  const peakFreq = psd.freqs[peakIdx];
+
+  // Power in 100 Hz window vs 120 Hz window
+  const power100 = _bandPower(psd, RIPPLE_50HZ,  RIPPLE_SLACK_HZ);
+  const power120 = _bandPower(psd, RIPPLE_60HZ,  RIPPLE_SLACK_HZ);
+  const baseline = _baselinePower(psd, [
+    [RIPPLE_50HZ - RIPPLE_SLACK_HZ, RIPPLE_50HZ + RIPPLE_SLACK_HZ],
+    [RIPPLE_60HZ - RIPPLE_SLACK_HZ, RIPPLE_60HZ + RIPPLE_SLACK_HZ],
+  ]);
+
+  const snr100 = baseline > 0 ? power100 / baseline : 0;
+  const snr120 = baseline > 0 ? power120 / baseline : 0;
+
+  // ── Verdict ───────────────────────────────────────────────────────────────
+  const has100 = power100 > MIN_RIPPLE_POWER && snr100 > SNR_THRESHOLD;
+  const has120 = power120 > MIN_RIPPLE_POWER && snr120 > SNR_THRESHOLD;
+
+  let gridFrequency = null;
+  let gridRegion    = 'unknown';
+  let ripplePower   = 0;
+  let nominalHz     = null;
+
+  if (has120 && power120 >= power100) {
+    gridFrequency = GRID_60HZ_NOMINAL;
+    gridRegion    = 'americas';
+    ripplePower   = power120;
+    nominalHz     = RIPPLE_60HZ;
+  } else if (has100) {
+    gridFrequency = GRID_50HZ_NOMINAL;
+    gridRegion    = 'emea_apac';
+    ripplePower   = power100;
+    nominalHz     = RIPPLE_50HZ;
+  }
+
+  const ripplePresent = has100 || has120;
+
+  // ── ENF deviation (temporal fingerprint) ─────────────────────────────────
+  // The precise ripple frequency deviates from nominal by ±0.1 Hz in real time.
+  // We measure the peak frequency in the ripple band to extract this deviation.
+  let enfDeviation = null;
+  if (ripplePresent && nominalHz !== null) {
+    const preciseRippleFreq = _precisePeakFreq(psd, nominalHz, RIPPLE_SLACK_HZ);
+    enfDeviation = +(preciseRippleFreq - nominalHz).toFixed(3); // Hz deviation from nominal
+  }
+
+  // ── Verdict ───────────────────────────────────────────────────────────────
+  const verdict =
+    !ripplePresent                     ? 'no_grid_signal'    // VM, UPS, or battery
+    : gridRegion === 'americas'        ? 'grid_60hz'
+    : gridRegion === 'emea_apac'       ? 'grid_50hz'
+    : 'grid_detected_region_unknown';
+
+  const isVmIndicator = !ripplePresent && sampleRateHz > 100;
+  // High sample rate + no ripple = conditioned power (datacenter)
+
+  return {
+    enfAvailable:   true,
+    ripplePresent,
+    gridFrequency,
+    gridRegion,
+    ripplePower:    +ripplePower.toFixed(4),
+    snr50hz:        +snr100.toFixed(2),
+    snr60hz:        +snr120.toFixed(2),
+    enfDeviation,
+    sampleRateHz:   +sampleRateHz.toFixed(1),
+    resolutionUs,
+    verdict,
+    isVmIndicator,
+    // For cross-referencing against public ENF databases (forensic timestamp)
+    temporalAnchor: enfDeviation !== null ? {
+      nominalHz,
+      measuredRippleHz: +(nominalHz + enfDeviation).toFixed(4),
+      capturedAt:       Date.now(),
+      // Matches format used by ENF forensic databases:
+      // https://www.enf.cc | UK National Grid ESO data
+      gridHz:           gridFrequency,
+    } : null,
+  };
+}
+
+/* ─── Power Spectral Density (Welch-inspired DFT) ───────────────────────── */
+
+function _computePsd(signal, sampleRateHz) {
+  const n       = signal.length;
+  const mean    = signal.reduce((s, v) => s + v, 0) / n;
+
+  // Remove DC offset and apply Hann window
+  const windowed = signal.map((v, i) => {
+    const w = 0.5 * (1 - Math.cos((2 * Math.PI * i) / (n - 1))); // Hann
+    return (v - mean) * w;
+  });
+
+  // DFT up to Nyquist — only need up to ~200 Hz so we cap bins
+  const maxFreq = Math.min(200, sampleRateHz / 2);
+  const maxBin  = Math.floor(maxFreq * n / sampleRateHz);
+
+  const powers = new Float64Array(maxBin);
+  const freqs  = new Float64Array(maxBin);
+
+  for (let k = 1; k < maxBin; k++) {
+    let re = 0, im = 0;
+    for (let t = 0; t < n; t++) {
+      const angle = (2 * Math.PI * k * t) / n;
+      re += windowed[t] * Math.cos(angle);
+      im -= windowed[t] * Math.sin(angle);
+    }
+    powers[k] = (re * re + im * im) / (n * n);
+    freqs[k]  = (k * sampleRateHz) / n;
+  }
+
+  // Normalise powers so they sum to 1 (makes thresholds sample-count-independent)
+  const total = powers.reduce((s, v) => s + v, 0);
+  if (total > 0) for (let i = 0; i < powers.length; i++) powers[i] /= total;
+
+  return { powers, freqs };
+}
+
+function _bandPower(psd, centerHz, halfwidthHz) {
+  let power = 0;
+  for (let i = 0; i < psd.freqs.length; i++) {
+    if (Math.abs(psd.freqs[i] - centerHz) <= halfwidthHz) {
+      power += psd.powers[i];
+    }
+  }
+  return power;
+}
+
+function _baselinePower(psd, excludeBands) {
+  let sum = 0, count = 0;
+  for (let i = 0; i < psd.freqs.length; i++) {
+    const f = psd.freqs[i];
+    const excluded = excludeBands.some(([lo, hi]) => f >= lo && f <= hi);
+    if (!excluded && f > 10 && f < 200) { sum += psd.powers[i]; count++; }
+  }
+  return count > 0 ? sum / count : 0;
+}
+
+function _precisePeakFreq(psd, centerHz, halfwidthHz) {
+  // Quadratic interpolation around the peak bin for sub-bin precision
+  let peakBin = 0, peakPow = -Infinity;
+  for (let i = 0; i < psd.freqs.length; i++) {
+    if (Math.abs(psd.freqs[i] - centerHz) <= halfwidthHz && psd.powers[i] > peakPow) {
+      peakPow = psd.powers[i]; peakBin = i;
+    }
+  }
+  if (peakBin <= 0 || peakBin >= psd.powers.length - 1) return psd.freqs[peakBin];
+
+  // Quadratic peak interpolation (Jacobsen method)
+  const alpha = psd.powers[peakBin - 1];
+  const beta  = psd.powers[peakBin];
+  const gamma = psd.powers[peakBin + 1];
+  const denom = alpha - 2 * beta + gamma;
+  if (Math.abs(denom) < 1e-14) return psd.freqs[peakBin];
+  const deltaBin = 0.5 * (alpha - gamma) / denom;
+  const binWidth = psd.freqs[1] - psd.freqs[0];
+  return psd.freqs[peakBin] + deltaBin * binWidth;
+}
+
+function _noEnf(reason) {
+  return {
+    enfAvailable: false, ripplePresent: false, gridFrequency: null,
+    gridRegion: 'unknown', ripplePower: 0, snr50hz: 0, snr60hz: 0,
+    enfDeviation: null, sampleRateHz: 0, resolutionUs: 0,
+    verdict: 'unavailable', isVmIndicator: false, temporalAnchor: null, reason,
+  };
+}
+
+/**
+ * @typedef {object} EnfResult
+ * @property {boolean}      enfAvailable
+ * @property {boolean}      ripplePresent    false = VM / datacenter / battery
+ * @property {number|null}  gridFrequency    50 or 60 Hz
+ * @property {string}       gridRegion       'americas' | 'emea_apac' | 'unknown'
+ * @property {number}       ripplePower      normalised PSD power at grid harmonic
+ * @property {number|null}  enfDeviation     Hz deviation from nominal (temporal fingerprint)
+ * @property {string}       verdict
+ * @property {boolean}      isVmIndicator    true if signal absence + high sample rate
+ * @property {object|null}  temporalAnchor   forensic timestamp anchor
+ */

package/src/collector/entropy.js

@@ -0,0 +1,195 @@
+/**
+ * @sovereign/pulse — Entropy Collector
+ *
+ * Bridges the Rust/WASM matrix-multiply probe into JavaScript.
+ * The WASM module is lazily initialised once and cached for subsequent calls.
+ */
+
+import { collectEntropyAdaptive } from './adaptive.js';
+
+// ---------------------------------------------------------------------------
+// WASM loader (lazy singleton)
+// ---------------------------------------------------------------------------
+let _wasmModule   = null;
+let _initPromise  = null;
+
+/**
+ * Initialise (or return the cached) WASM module.
+ * Works in browsers (via fetch), in Electron (Node.js context), and in
+ * Jest/Vitest via a manual WASM path override.
+ *
+ * @param {string} [wasmPath] – override path/URL to the .wasm binary
+ */
+async function initWasm(wasmPath) {
+  if (_wasmModule) return _wasmModule;
+  if (_initPromise) return _initPromise;
+
+  _initPromise = (async () => {
+    // Dynamic import so bundlers can tree-shake this for server-only builds.
+    const { default: init, run_entropy_probe, run_memory_probe, compute_autocorrelation } =
+      await import('../../pkg/pulse_core.js');
+
+    const url = wasmPath ?? new URL('../../pkg/pulse_core_bg.wasm', import.meta.url).href;
+    await init(url);
+
+    _wasmModule = { run_entropy_probe, run_memory_probe, compute_autocorrelation };
+    return _wasmModule;
+  })();
+
+  return _initPromise;
+}
+
+// ---------------------------------------------------------------------------
+// collectEntropy
+// ---------------------------------------------------------------------------
+
+/**
+ * Run the WASM entropy probe and return raw timing data.
+ *
+ * @param {object}  opts
+ * @param {number}  [opts.iterations=200]  - number of matrix-multiply rounds
+ * @param {number}  [opts.matrixSize=64]   - N for the N×N matrices
+ * @param {number}  [opts.memSizeKb=512]   - size of the memory bandwidth probe
+ * @param {number}  [opts.memIterations=50]
+ * @param {boolean} [opts.phased=true]     - run cold/load/hot phases for entropy-jitter ratio
+ * @param {string}  [opts.wasmPath]        - optional custom WASM binary path
+ *
+ * @returns {Promise<EntropyResult>}
+ */
+export async function collectEntropy(opts = {}) {
+  const {
+    iterations        = 200,
+    matrixSize        = 64,
+    memSizeKb         = 512,
+    memIterations     = 50,
+    phased            = true,
+    adaptive          = false,
+    adaptiveThreshold = 0.85,
+    onBatch,
+    wasmPath,
+  } = opts;
+
+  const wasm    = await initWasm(wasmPath);
+  const t_start = Date.now();
+
+  let phases = null;
+  let timings, resolutionProbe, checksum, timerGranularityMs;
+  let _adaptiveInfo = null;
+
+  // ── Adaptive mode: smart early exit, fastest for obvious VMs ──────────
+  if (adaptive) {
+    const r = await collectEntropyAdaptive(wasm, {
+      minIterations:   50,
+      maxIterations:   iterations,
+      batchSize:       25,
+      vmThreshold:     adaptiveThreshold,
+      hwThreshold:     0.80,
+      hwMinIterations: 75,
+      matrixSize,
+      onBatch,
+    });
+    timings            = r.timings;
+    resolutionProbe    = r.resolutionProbe ?? [];
+    checksum           = r.checksum;
+    timerGranularityMs = r.timerGranularityMs;
+    _adaptiveInfo      = { earlyExit: r.earlyExit, batches: r.batches, elapsedMs: r.elapsedMs };
+
+  // ── Phased collection: cold → load → hot ──────────────────────────────
+  // Each phase runs a separate WASM probe.  On real hardware, sustained load
+  // increases thermal noise so Phase 3 (hot) entropy is measurably higher
+  // than Phase 1 (cold).  A VM's hypervisor clock is insensitive to guest
+  // thermal state, so all three phases return nearly identical entropy.
+  } else if (phased && iterations >= 60) {
+    const coldN = Math.floor(iterations * 0.25);  // ~25% cold
+    const loadN = Math.floor(iterations * 0.50);  // ~50% sustained load
+    const hotN  = iterations - coldN - loadN;     // ~25% hot
+
+    const cold = wasm.run_entropy_probe(coldN, matrixSize);
+    const load = wasm.run_entropy_probe(loadN, matrixSize);
+    const hot  = wasm.run_entropy_probe(hotN,  matrixSize);
+
+    const coldTimings = Array.from(cold.timings);
+    const loadTimings = Array.from(load.timings);
+    const hotTimings  = Array.from(hot.timings);
+
+    timings         = [...coldTimings, ...loadTimings, ...hotTimings];
+    resolutionProbe = Array.from(cold.resolution_probe);
+    checksum        = (cold.checksum + load.checksum + hot.checksum).toString();
+
+    const { detectQuantizationEntropy } = await import('../analysis/jitter.js');
+    const coldQE = detectQuantizationEntropy(coldTimings);
+    const hotQE  = detectQuantizationEntropy(hotTimings);
+
+    phases = {
+      cold: { n: coldN, timings: coldTimings, qe: coldQE, mean: _mean(coldTimings) },
+      load: { n: loadN, timings: loadTimings, qe: detectQuantizationEntropy(loadTimings), mean: _mean(loadTimings) },
+      hot:  { n: hotN,  timings: hotTimings,  qe: hotQE,  mean: _mean(hotTimings)  },
+      // The key signal: entropy growth under load.
+      // Real silicon: hotQE / coldQE typically 1.05 – 1.40
+      // VM:           hotQE / coldQE typically 0.95 – 1.05 (flat)
+      entropyJitterRatio: coldQE > 0 ? hotQE / coldQE : 1.0,
+    };
+  } else {
+    // Single-phase fallback (fewer iterations or phased disabled)
+    const result    = wasm.run_entropy_probe(iterations, matrixSize);
+    timings         = Array.from(result.timings);
+    resolutionProbe = Array.from(result.resolution_probe);
+    checksum        = result.checksum.toString();
+  }
+
+  // ── Timer resolution (non-adaptive path only — adaptive computes its own) ─
+  if (!adaptive) {
+    const resDeltas = [];
+    for (let i = 1; i < resolutionProbe.length; i++) {
+      const d = resolutionProbe[i] - resolutionProbe[i - 1];
+      if (d > 0) resDeltas.push(d);
+    }
+    timerGranularityMs = resDeltas.length
+      ? resDeltas.reduce((a, b) => Math.min(a, b), Infinity)
+      : null;
+  }
+
+  // ── Autocorrelation at diagnostic lags ────────────────────────────────
+  // Extended lags catch long-period steal-time rhythms (Xen: ~150 iters)
+  const lags = [1, 2, 3, 5, 10, 25, 50];
+  const autocorrelations = {};
+  for (const lag of lags) {
+    if (lag < timings.length) {
+      autocorrelations[`lag${lag}`] = wasm.compute_autocorrelation(timings, lag);
+    }
+  }
+
+  // ── Secondary probe: memory bandwidth jitter ───────────────────────────
+  const memTimings = Array.from(wasm.run_memory_probe(memSizeKb, memIterations));
+
+  return {
+    timings,
+    resolutionProbe,
+    timerGranularityMs,
+    autocorrelations,
+    memTimings,
+    phases,
+    checksum,
+    collectedAt: t_start,
+    iterations: timings.length,   // actual count (adaptive may differ from requested)
+    matrixSize,
+    adaptive: _adaptiveInfo,      // null in non-adaptive mode
+  };
+}
+
+function _mean(arr) {
+  return arr.length ? arr.reduce((s, v) => s + v, 0) / arr.length : 0;
+}
+
+/**
+ * @typedef {object} EntropyResult
+ * @property {number[]}  timings            - per-iteration wall-clock deltas (ms)
+ * @property {number[]}  resolutionProbe    - raw successive perf.now() readings
+ * @property {number|null} timerGranularityMs - effective timer resolution
+ * @property {object}    autocorrelations   - { lag1, lag2, lag3, lag5, lag10 }
+ * @property {number[]}  memTimings         - memory-probe timings (ms)
+ * @property {string}    checksum           - proof the computation ran
+ * @property {number}    collectedAt        - Date.now() at probe start
+ * @property {number}    iterations
+ * @property {number}    matrixSize
+ */