@svrnsec/pulse 0.7.0 → 0.9.0

package/src/collector/sabTimer.js

@@ -1,191 +1,189 @@
-/**
- * @svrnsec/pulse — SharedArrayBuffer Microsecond Timer
- *
- * Bypasses browser timer clamping (Brave 100µs cap, Firefox 20µs cap, Safari
- * 1ms cap) using Atomics.wait() which is exempt from clamping because it maps
- * directly to OS-level futex/semaphore primitives.
- *
- * Requirements
- * ────────────
- * The page must be served with Cross-Origin Isolation headers:
- *   Cross-Origin-Opener-Policy: same-origin
- *   Cross-Origin-Embedder-Policy: require-corp
- *
- * These are mandatory for security (Spectre mitigations) and are already
- * required by WebGPU, WebAssembly threads, and SharedArrayBuffer in all
- * modern browsers.
- *
- * What we measure
- * ───────────────
- *   resolution        the true timer resolution (pre-clamp) in microseconds
- *   isClamped         true if performance.now() is artificially reduced
- *   clampAmount       how much performance.now() was rounded (µs)
- *   highResTimings    entropy probe timings at true microsecond resolution
- *
- * Why this matters
- * ────────────────
- * With 1ms clamping, a VM's flat distribution and a real device's noisy
- * distribution can look similar — both get quantized to the same step.
- * At 1µs resolution, the difference between EJR=1.01 and EJR=1.24 is
- * unmistakable. This upgrade alone materially improves detection accuracy
- * on Brave and Firefox where timer clamping was previously a confound.
- */
-
-/* ─── availability ───────────────────────────────────────────────────────── */
-
-export function isSabAvailable() {
-  return (
-    typeof SharedArrayBuffer !== 'undefined' &&
-    typeof Atomics            !== 'undefined' &&
-    typeof Atomics.wait       === 'function'  &&
-    typeof crossOriginIsolated !== 'undefined' && crossOriginIsolated === true  // COOP+COEP headers
-  );
-}
-
-/* ─── Atomics-based high-resolution clock ───────────────────────────────── */
-
-let _sab  = null;
-let _i32  = null;
-
-function _initSab() {
-  if (!_sab) {
-    _sab = new SharedArrayBuffer(4);
-    _i32 = new Int32Array(_sab);
-  }
-}
-
-/**
- * Wait exactly `us` microseconds using Atomics.wait().
- * Returns wall-clock elapsed in milliseconds.
- * Much more accurate than setTimeout(fn, 0) or performance.now() loops.
- *
- * @param {number} us – microseconds to wait
- * @returns {number}  actual elapsed ms
- */
-function _atomicsWait(us) {
-  _initSab();
-  const t0 = performance.now();
-  Atomics.wait(_i32, 0, 0, us / 1000); // Atomics.wait timeout is in ms
-  return performance.now() - t0;
-}
-
-/* ─── measureClamp ───────────────────────────────────────────────────────── */
-
-/**
- * Determine the true timer resolution by comparing a series of
- * sub-millisecond Atomics.wait() calls against performance.now() deltas.
- *
- * @returns {{ isClamped: boolean, clampAmountUs: number, resolutionUs: number }}
- */
-export function measureClamp() {
-  if (!isSabAvailable()) {
-    return { isClamped: false, clampAmountUs: 0, resolutionUs: 1000 };
-  }
-
-  // Measure the minimum non-zero performance.now() delta
-  const performanceDeltas = [];
-  for (let i = 0; i < 100; i++) {
-    const t0 = performance.now();
-    let t1 = t0;
-    while (t1 === t0) t1 = performance.now();
-    performanceDeltas.push((t1 - t0) * 1000); // convert to µs
-  }
-  performanceDeltas.sort((a, b) => a - b);
-  const perfResolutionUs = performanceDeltas[Math.floor(performanceDeltas.length * 0.1)]; // 10th percentile
-
-  // Measure actual OS timer resolution via Atomics.wait
-  const atomicsDeltas = [];
-  for (let i = 0; i < 20; i++) {
-    const elapsedMs = _atomicsWait(100); // wait 100µs
-    atomicsDeltas.push(Math.abs(elapsedMs * 1000 - 100)); // error from target
-  }
-  const atomicsErrorUs = atomicsDeltas.reduce((s, v) => s + v, 0) / atomicsDeltas.length;
-  const trueResolutionUs = Math.max(1, atomicsErrorUs);
-
-  const isClamped    = perfResolutionUs > trueResolutionUs * 5;
-  const clampAmountUs = isClamped ? perfResolutionUs - trueResolutionUs : 0;
-
-  return { isClamped, clampAmountUs, resolutionUs: perfResolutionUs };
-}
-
-/* ─── collectHighResTimings ──────────────────────────────────────────────── */
-
-/**
- * Collect entropy probe timings at Atomics-level resolution.
- * Falls back to performance.now() if SAB is unavailable.
- *
- * The probe itself is identical to the WASM matrix probe — CPU work unit
- * timed with the highest available clock. The difference: on a clamped
- * browser this replaces quantized 100µs buckets with true µs measurements.
- *
- * @param {object} opts
- * @param {number} [opts.iterations=200]
- * @param {number} [opts.matrixSize=32]     – smaller than WASM probe (no SIMD here)
- * @returns {{ timings: number[], usingAtomics: boolean, resolutionUs: number }}
- */
-export function collectHighResTimings(opts = {}) {
-  const { iterations = 200, matrixSize = 32 } = opts;
-
-  const usingAtomics = isSabAvailable();
-  const clampInfo    = usingAtomics ? measureClamp() : { resolutionUs: 1000 };
-
-  // Simple matrix multiply work unit (JS — no WASM needed for the clock probe)
-  const N = matrixSize;
-  const A = new Float64Array(N * N).map(() => Math.random());
-  const B = new Float64Array(N * N).map(() => Math.random());
-  const C = new Float64Array(N * N);
-
-  const timings = new Array(iterations);
-
-  for (let iter = 0; iter < iterations; iter++) {
-    C.fill(0);
-
-    if (usingAtomics) {
-      // ── Atomics path: start timing, do work, read Atomics-calibrated time ──
-      // We use a sliding window approach: measure with Atomics.wait(0) which
-      // returns immediately but the OS schedules give us a high-res timestamp
-      // via the before/after pattern on the shared memory notification.
-      _initSab();
-
-      const tAtomicsBefore = _getAtomicsTs();
-      for (let i = 0; i < N; i++) {
-        for (let k = 0; k < N; k++) {
-          const aik = A[i * N + k];
-          for (let j = 0; j < N; j++) C[i * N + j] += aik * B[k * N + j];
-        }
-      }
-      const tAtomicsAfter = _getAtomicsTs();
-      timings[iter] = (tAtomicsAfter - tAtomicsBefore) * 1000; // µs → ms
-
-    } else {
-      // ── Standard path: use performance.now() ──
-      const t0 = performance.now();
-      for (let i = 0; i < N; i++) {
-        for (let k = 0; k < N; k++) {
-          const aik = A[i * N + k];
-          for (let j = 0; j < N; j++) C[i * N + j] += aik * B[k * N + j];
-        }
-      }
-      timings[iter] = performance.now() - t0;
-    }
-  }
-
-  return {
-    timings,
-    usingAtomics,
-    resolutionUs: clampInfo.resolutionUs,
-    isClamped:    clampInfo.isClamped ?? false,
-    clampAmountUs: clampInfo.clampAmountUs ?? 0,
-  };
-}
-
-/* ─── internal Atomics timestamp ─────────────────────────────────────────── */
-
-// Use a write to shared memory + memory fence as a timestamp anchor.
-// This forces the CPU to flush its store buffer, giving a hardware-ordered
-// time reference that survives compiler reordering.
-function _getAtomicsTs() {
-  _initSab();
-  Atomics.store(_i32, 0, Atomics.load(_i32, 0) + 1);
-  return performance.now();
-}
+/**
+ * @svrnsec/pulse — SharedArrayBuffer Microsecond Timer
+ *
+ * Bypasses browser timer clamping (Brave 100µs cap, Firefox 20µs cap, Safari
+ * 1ms cap) using Atomics.wait() which is exempt from clamping because it maps
+ * directly to OS-level futex/semaphore primitives.
+ *
+ * Requirements
+ * ────────────
+ * The page must be served with Cross-Origin Isolation headers:
+ *   Cross-Origin-Opener-Policy: same-origin
+ *   Cross-Origin-Embedder-Policy: require-corp
+ *
+ * These are mandatory for security (Spectre mitigations) and are already
+ * required by WebGPU, WebAssembly threads, and SharedArrayBuffer in all
+ * modern browsers.
+ *
+ * What we measure
+ * ───────────────
+ *   resolution        the true timer resolution (pre-clamp) in microseconds
+ *   isClamped         true if performance.now() is artificially reduced
+ *   clampAmount       how much performance.now() was rounded (µs)
+ *   highResTimings    entropy probe timings at true microsecond resolution
+ *
+ * Why this matters
+ * ────────────────
+ * With 1ms clamping, a VM's flat distribution and a real device's noisy
+ * distribution can look similar — both get quantized to the same step.
+ * At 1µs resolution, the difference between EJR=1.01 and EJR=1.24 is
+ * unmistakable. This upgrade alone materially improves detection accuracy
+ * on Brave and Firefox where timer clamping was previously a confound.
+ */
+
+/* ─── availability ───────────────────────────────────────────────────────── */
+
+export function isSabAvailable() {
+  return (
+    typeof SharedArrayBuffer !== 'undefined' &&
+    typeof Atomics            !== 'undefined' &&
+    typeof Atomics.wait       === 'function'  &&
+    typeof crossOriginIsolated !== 'undefined' && crossOriginIsolated === true  // COOP+COEP headers
+  );
+}
+
+/* ─── Atomics-based high-resolution clock ───────────────────────────────── */
+
+function _createSab() {
+  if (!isSabAvailable()) return null;
+  const sab = new SharedArrayBuffer(4);
+  return new Int32Array(sab);
+}
+
+/**
+ * Wait exactly `us` microseconds using Atomics.wait().
+ * Returns wall-clock elapsed in milliseconds.
+ * Much more accurate than setTimeout(fn, 0) or performance.now() loops.
+ *
+ * @param {number} us – microseconds to wait
+ * @param {Int32Array} i32 – shared int32 view
+ * @returns {number}  actual elapsed ms
+ */
+function _atomicsWait(us, i32) {
+  const t0 = performance.now();
+  Atomics.wait(i32, 0, 0, us / 1000); // Atomics.wait timeout is in ms
+  return performance.now() - t0;
+}
+
+/* ─── measureClamp ───────────────────────────────────────────────────────── */
+
+/**
+ * Determine the true timer resolution by comparing a series of
+ * sub-millisecond Atomics.wait() calls against performance.now() deltas.
+ *
+ * @returns {{ isClamped: boolean, clampAmountUs: number, resolutionUs: number }}
+ */
+export function measureClamp() {
+  if (!isSabAvailable()) {
+    return { isClamped: false, clampAmountUs: 0, resolutionUs: 1000 };
+  }
+
+  // Measure the minimum non-zero performance.now() delta
+  const performanceDeltas = [];
+  for (let i = 0; i < 100; i++) {
+    const t0 = performance.now();
+    let t1 = t0;
+    let attempts = 0;
+    while (t1 === t0 && attempts++ < 10000) t1 = performance.now();
+    performanceDeltas.push((t1 - t0) * 1000); // convert to µs
+  }
+  performanceDeltas.sort((a, b) => a - b);
+  const perfResolutionUs = performanceDeltas[Math.floor(performanceDeltas.length * 0.1)]; // 10th percentile
+
+  // Measure actual OS timer resolution via Atomics.wait
+  const i32 = _createSab();
+  if (!i32) return { isClamped: false, clampAmountUs: 0, resolutionUs: 1000 };
+  const atomicsDeltas = [];
+  for (let i = 0; i < 20; i++) {
+    const elapsedMs = _atomicsWait(100, i32); // wait 100µs
+    atomicsDeltas.push(Math.abs(elapsedMs * 1000 - 100)); // error from target
+  }
+  const atomicsErrorUs = atomicsDeltas.reduce((s, v) => s + v, 0) / atomicsDeltas.length;
+  const trueResolutionUs = Math.max(1, atomicsErrorUs);
+
+  const isClamped    = perfResolutionUs > trueResolutionUs * 5;
+  const clampAmountUs = isClamped ? perfResolutionUs - trueResolutionUs : 0;
+
+  return { isClamped, clampAmountUs, resolutionUs: perfResolutionUs };
+}
+
+/* ─── collectHighResTimings ──────────────────────────────────────────────── */
+
+/**
+ * Collect entropy probe timings at Atomics-level resolution.
+ * Falls back to performance.now() if SAB is unavailable.
+ *
+ * The probe itself is identical to the WASM matrix probe — CPU work unit
+ * timed with the highest available clock. The difference: on a clamped
+ * browser this replaces quantized 100µs buckets with true µs measurements.
+ *
+ * @param {object} opts
+ * @param {number} [opts.iterations=200]
+ * @param {number} [opts.matrixSize=32]     – smaller than WASM probe (no SIMD here)
+ * @returns {{ timings: number[], usingAtomics: boolean, resolutionUs: number }}
+ */
+export function collectHighResTimings(opts = {}) {
+  const { iterations = 200, matrixSize = 32 } = opts;
+
+  const usingAtomics = isSabAvailable();
+  const clampInfo    = usingAtomics ? measureClamp() : { resolutionUs: 1000 };
+
+  // Simple matrix multiply work unit (JS — no WASM needed for the clock probe)
+  const N = matrixSize;
+  const A = new Float64Array(N * N).map(() => Math.random());
+  const B = new Float64Array(N * N).map(() => Math.random());
+  const C = new Float64Array(N * N);
+
+  const timings = new Array(iterations);
+  const _i32 = usingAtomics ? _createSab() : null;
+
+  for (let iter = 0; iter < iterations; iter++) {
+    C.fill(0);
+
+    if (usingAtomics && _i32) {
+      // ── Atomics path: start timing, do work, read Atomics-calibrated time ──
+      // We use a sliding window approach: measure with Atomics.wait(0) which
+      // returns immediately but the OS schedules give us a high-res timestamp
+      // via the before/after pattern on the shared memory notification.
+
+      const tAtomicsBefore = _getAtomicsTs(_i32);
+      for (let i = 0; i < N; i++) {
+        for (let k = 0; k < N; k++) {
+          const aik = A[i * N + k];
+          for (let j = 0; j < N; j++) C[i * N + j] += aik * B[k * N + j];
+        }
+      }
+      const tAtomicsAfter = _getAtomicsTs(_i32);
+      timings[iter] = (tAtomicsAfter - tAtomicsBefore) * 1000; // µs → ms
+
+    } else {
+      // ── Standard path: use performance.now() ──
+      const t0 = performance.now();
+      for (let i = 0; i < N; i++) {
+        for (let k = 0; k < N; k++) {
+          const aik = A[i * N + k];
+          for (let j = 0; j < N; j++) C[i * N + j] += aik * B[k * N + j];
+        }
+      }
+      timings[iter] = performance.now() - t0;
+    }
+  }
+
+  return {
+    timings,
+    usingAtomics,
+    resolutionUs: clampInfo.resolutionUs,
+    isClamped:    clampInfo.isClamped ?? false,
+    clampAmountUs: clampInfo.clampAmountUs ?? 0,
+  };
+}
+
+/* ─── internal Atomics timestamp ─────────────────────────────────────────── */
+
+// Use a write to shared memory + memory fence as a timestamp anchor.
+// This forces the CPU to flush its store buffer, giving a hardware-ordered
+// time reference that survives compiler reordering.
+function _getAtomicsTs(i32) {
+  Atomics.store(i32, 0, Atomics.load(i32, 0) + 1);
+  return performance.now();
+}

package/src/errors.js

@@ -0,0 +1,54 @@
+/**
+ * @svrnsec/pulse — Structured Error Codes
+ *
+ * Use these constants instead of string matching for type-safe error handling.
+ */
+export const PulseErrorCode = Object.freeze({
+  // Structural
+  INVALID_PAYLOAD_STRUCTURE: 'INVALID_PAYLOAD_STRUCTURE',
+  PROTOTYPE_POLLUTION_ATTEMPT: 'PROTOTYPE_POLLUTION_ATTEMPT',
+  MISSING_REQUIRED_FIELD: 'MISSING_REQUIRED_FIELD',
+  INVALID_TYPE: 'INVALID_TYPE',
+  TIMESTAMP_OUT_OF_RANGE: 'TIMESTAMP_OUT_OF_RANGE',
+  UNSUPPORTED_PROOF_VERSION: 'UNSUPPORTED_PROOF_VERSION',
+
+  // Hash integrity
+  INVALID_HASH_FORMAT: 'INVALID_HASH_FORMAT',
+  HASH_MISMATCH_PAYLOAD_TAMPERED: 'HASH_MISMATCH_PAYLOAD_TAMPERED',
+
+  // Timestamp / freshness
+  PROOF_EXPIRED: 'PROOF_EXPIRED',
+  PROOF_FROM_FUTURE: 'PROOF_FROM_FUTURE',
+  NONCE_INVALID_OR_REPLAYED: 'NONCE_INVALID_OR_REPLAYED',
+
+  // Jitter / scoring
+  JITTER_SCORE_TOO_LOW: 'JITTER_SCORE_TOO_LOW',
+  DYNAMIC_THRESHOLD_NOT_MET: 'DYNAMIC_THRESHOLD_NOT_MET',
+
+  // Heuristic / coherence overrides
+  HEURISTIC_HARD_OVERRIDE: 'HEURISTIC_HARD_OVERRIDE',
+  COHERENCE_HARD_OVERRIDE: 'COHERENCE_HARD_OVERRIDE',
+
+  // Renderer
+  SOFTWARE_RENDERER_DETECTED: 'SOFTWARE_RENDERER_DETECTED',
+  BLOCKLISTED_RENDERER: 'BLOCKLISTED_RENDERER',
+
+  // Bio activity
+  NO_BIO_ACTIVITY_DETECTED: 'NO_BIO_ACTIVITY_DETECTED',
+
+  // Cross-signal forgery detection
+  FORGED_SIGNAL_CV_SCORE_IMPOSSIBLE: 'FORGED_SIGNAL:CV_SCORE_IMPOSSIBLE',
+  FORGED_SIGNAL_AUTOCORR_SCORE_IMPOSSIBLE: 'FORGED_SIGNAL:AUTOCORR_SCORE_IMPOSSIBLE',
+  FORGED_SIGNAL_QE_SCORE_IMPOSSIBLE: 'FORGED_SIGNAL:QE_SCORE_IMPOSSIBLE',
+
+  // Risk flags (informational, not rejection reasons)
+  NONCE_FRESHNESS_NOT_CHECKED: 'NONCE_FRESHNESS_NOT_CHECKED',
+  CANVAS_UNAVAILABLE: 'CANVAS_UNAVAILABLE',
+  ZERO_BIO_SAMPLES: 'ZERO_BIO_SAMPLES',
+  NEGATIVE_INTERFERENCE_COEFFICIENT: 'NEGATIVE_INTERFERENCE_COEFFICIENT',
+  INCONSISTENCY_LOW_CV_BUT_HIGH_SCORE: 'INCONSISTENCY:LOW_CV_BUT_HIGH_SCORE',
+  SUSPICIOUS_ZERO_TIMER_GRANULARITY: 'SUSPICIOUS_ZERO_TIMER_GRANULARITY',
+  INCONSISTENCY_FLAT_THERMAL_BUT_HIGH_SCORE: 'INCONSISTENCY:FLAT_THERMAL_BUT_HIGH_SCORE',
+  EXTREME_HURST: 'EXTREME_HURST',
+  AUDIO_JITTER_TOO_FLAT: 'AUDIO_JITTER_TOO_FLAT',
+});