@svrnsec/pulse 0.7.0 → 0.9.0

package/src/collector/enf.js

@@ -1,311 +1,311 @@
-/**
- * @svrnsec/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
- */
+/**
+ * @svrnsec/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.powers.reduce((best, v, i) => i > 0 && v > psd.powers[best] ? i : best, 1);
+  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
+ */