@svrnsec/pulse 0.1.0

package/pkg/pulse_core.js

@@ -0,0 +1,173 @@
+/**
+ * pulse_core — pure-JavaScript probe engine
+ *
+ * This module ships the entropy probe as portable JS so the package works
+ * out-of-the-box without a Rust toolchain.  When a compiled .wasm binary is
+ * present (dropped in via `build.sh`) this file is replaced by the wasm-pack
+ * output and the native engine runs instead.
+ *
+ * Physics model
+ * ─────────────
+ * Real silicon: DRAM refresh cycles, branch-predictor misses, and L3-cache
+ * evictions inject sub-microsecond noise into any tight compute loop.
+ * Hypervisors virtualise the TSC and smooth those interrupts out, leaving
+ * a near-flat timing distribution that our QE/EJR checks catch.
+ *
+ * The JS loop below is a faithful port of the Rust matrix-multiply probe:
+ * same work unit (N×N DGEMM-style loop), same checksum accumulation to
+ * prevent dead-code elimination, same resolution micro-probe.
+ */
+
+/* ─── clock ─────────────────────────────────────────────────────────────── */
+
+const _now = (typeof performance !== 'undefined' && typeof performance.now === 'function')
+  ? () => performance.now()
+  : (() => {
+      // Node.js fallback: process.hrtime.bigint() → milliseconds
+      const _hr = process.hrtime.bigint;
+      return () => Number(_hr()) / 1_000_000;
+    })();
+
+/* ─── init (no-op for the JS engine) ───────────────────────────────────── */
+
+/**
+ * Initialise the engine.  When a real .wasm binary is supplied the wasm-pack
+ * glue calls WebAssembly.instantiateStreaming here.  The JS engine is already
+ * "compiled", so we return immediately.
+ *
+ * @param {string|URL|Request|BufferSource|WebAssembly.Module} [_source]
+ * @returns {Promise<void>}
+ */
+export default async function init(_source) {
+  // JS engine is ready synchronously — nothing to stream or compile.
+}
+
+/* ─── run_entropy_probe ─────────────────────────────────────────────────── */
+
+/**
+ * Run N iterations of a matrix-multiply work unit and record wall-clock time
+ * per iteration.  The distribution of those times is what the heuristic
+ * engine analyses.
+ *
+ * @param {number} iterations  – number of timing samples to collect
+ * @param {number} matrixSize  – N for the N×N multiply (default 64)
+ * @returns {{ timings: Float64Array, checksum: number, resolution_probe: Float64Array }}
+ */
+export function run_entropy_probe(iterations, matrixSize = 64) {
+  const N = matrixSize | 0;
+
+  // Persistent working matrices — allocated once per probe to avoid GC noise.
+  const A = new Float64Array(N * N);
+  const B = new Float64Array(N * N);
+  const C = new Float64Array(N * N);
+
+  // Seed matrices with pseudo-random data (deterministic per call for
+  // reproducibility, but different each run due to xorshift seeding from time).
+  let seed = (_now() * 1e6) | 0 || 0xdeadbeef;
+  const xr  = () => { seed ^= seed << 13; seed ^= seed >> 17; seed ^= seed << 5; return (seed >>> 0) / 4294967296; };
+  for (let i = 0; i < N * N; i++) { A[i] = xr(); B[i] = xr(); }
+
+  const timings         = new Float64Array(iterations);
+  const resolution_probe = new Float64Array(32);
+  let   checksum        = 0;
+
+  for (let iter = 0; iter < iterations; iter++) {
+    // Zero accumulator each round (realistic cache pressure).
+    C.fill(0);
+
+    const t0 = _now();
+
+    // N×N matrix multiply: C = A · B  (ikj loop order for cache friendliness)
+    for (let i = 0; i < N; i++) {
+      const rowA = i * N;
+      const rowC = i * N;
+      for (let k = 0; k < N; k++) {
+        const aik   = A[rowA + k];
+        const rowBk = k * N;
+        for (let j = 0; j < N; j++) {
+          C[rowC + j] += aik * B[rowBk + j];
+        }
+      }
+    }
+
+    const t1 = _now();
+    timings[iter] = t1 - t0;
+
+    // Accumulate one element so the compiler cannot eliminate the work.
+    checksum += C[0];
+  }
+
+  // Resolution micro-probe: fire 32 back-to-back timestamps.
+  // The minimum non-zero delta reveals timer granularity.
+  for (let i = 0; i < resolution_probe.length; i++) {
+    resolution_probe[i] = _now();
+  }
+
+  return { timings, checksum, resolution_probe };
+}
+
+/* ─── run_memory_probe ──────────────────────────────────────────────────── */
+
+/**
+ * Sequential read/write bandwidth probe over a large buffer.
+ * Memory latency variance is a secondary signal (NUMA, DRAM refresh).
+ *
+ * @param {number} memSizeKb    – buffer size in kibibytes
+ * @param {number} memIterations
+ * @returns {{ timings: Float64Array, checksum: number }}
+ */
+export function run_memory_probe(memSizeKb = 512, memIterations = 50) {
+  const len     = (memSizeKb * 1024 / 8) | 0;   // 64-bit elements
+  const buf     = new Float64Array(len);
+  const timings = new Float64Array(memIterations);
+  let   checksum = 0;
+
+  // Warm-up pass (fills TLB, avoids first-access bias)
+  for (let i = 0; i < len; i++) buf[i] = i;
+
+  for (let iter = 0; iter < memIterations; iter++) {
+    const t0 = _now();
+    // Sequential read-modify-write
+    for (let i = 0; i < len; i++) buf[i] = buf[i] * 1.0000001;
+    const t1 = _now();
+
+    timings[iter] = t1 - t0;
+    checksum += buf[0];
+  }
+
+  return { timings, checksum };
+}
+
+/* ─── compute_autocorrelation ───────────────────────────────────────────── */
+
+/**
+ * Pearson autocorrelation for lags 1..maxLag.
+ * O(n·maxLag) — kept cheap by the adaptive early-exit cap.
+ *
+ * @param {ArrayLike<number>} data
+ * @param {number}            maxLag
+ * @returns {Float64Array}  length = maxLag, index 0 = lag-1
+ */
+export function compute_autocorrelation(data, maxLag) {
+  const n    = data.length;
+  let   mean = 0;
+  for (let i = 0; i < n; i++) mean += data[i];
+  mean /= n;
+
+  let variance = 0;
+  for (let i = 0; i < n; i++) variance += (data[i] - mean) ** 2;
+  variance /= n;
+
+  const result = new Float64Array(maxLag);
+  if (variance < 1e-14) return result;          // degenerate — all identical
+
+  for (let lag = 1; lag <= maxLag; lag++) {
+    let cov = 0;
+    for (let i = 0; i < n - lag; i++) {
+      cov += (data[i] - mean) * (data[i + lag] - mean);
+    }
+    result[lag - 1] = cov / ((n - lag) * variance);
+  }
+
+  return result;
+}

package/src/integrations/react.js

@@ -0,0 +1,185 @@
+/**
+ * @sovereign/pulse — React Hook
+ *
+ * import { usePulse } from '@sovereign/pulse/react';
+ *
+ * const {
+ *   run, reset,
+ *   stage, pct, vmConf, hwConf, earlyVerdict,
+ *   proof, result,
+ *   isRunning, isReady, error,
+ * } = usePulse({ apiKey: 'sk_live_...' });
+ *
+ * // Or self-hosted:
+ * const { run, proof, result } = usePulse({
+ *   challengeUrl: '/api/pulse/challenge',
+ *   verifyUrl:    '/api/pulse/verify',
+ * });
+ */
+
+import { useState, useCallback, useRef } from 'react';
+
+// Lazy import — only loaded in browser, allows tree-shaking in SSR builds
+let _pulseModule = null;
+async function getPulse() {
+  if (!_pulseModule) {
+    _pulseModule = await import('../index.js');
+  }
+  return _pulseModule.pulse;
+}
+
+/**
+ * @param {object}   opts
+ * @param {string}   [opts.apiKey]         - hosted API key (zero-config)
+ * @param {string}   [opts.apiUrl]         - hosted API base URL (default: https://api.sovereign.dev)
+ * @param {string}   [opts.challengeUrl]   - self-hosted challenge endpoint
+ * @param {string}   [opts.verifyUrl]      - self-hosted verify endpoint
+ * @param {number}   [opts.iterations=200]
+ * @param {number}   [opts.bioWindowMs=3000]
+ * @param {boolean}  [opts.adaptive=true]
+ * @param {boolean}  [opts.autoRun=false]  - run immediately on mount
+ * @param {Function} [opts.onResult]       - callback when result is ready
+ * @param {Function} [opts.onError]        - callback on error
+ */
+export function usePulse(opts = {}) {
+  const {
+    apiKey,
+    apiUrl        = 'https://api.sovereign.dev',
+    challengeUrl,
+    verifyUrl,
+    iterations    = 200,
+    bioWindowMs   = 3000,
+    adaptive      = true,
+    autoRun       = false,
+    onResult,
+    onError,
+  } = opts;
+
+  // ── State ────────────────────────────────────────────────────────────────
+  const [stage,        setStage]       = useState(null);
+  const [pct,          setPct]         = useState(0);
+  const [vmConf,       setVmConf]      = useState(0);
+  const [hwConf,       setHwConf]      = useState(0);
+  const [earlyVerdict, setEarlyVerdict]= useState(null);
+  const [proof,        setProof]       = useState(null);
+  const [result,       setResult]      = useState(null);
+  const [isRunning,    setIsRunning]   = useState(false);
+  const [error,        setError]       = useState(null);
+
+  const abortRef = useRef(null);
+  const hasAutoRun = useRef(false);
+
+  // ── run() ────────────────────────────────────────────────────────────────
+  const run = useCallback(async () => {
+    if (isRunning) return;
+
+    // Reset
+    setStage(null); setPct(0); setVmConf(0); setHwConf(0);
+    setEarlyVerdict(null); setProof(null); setResult(null);
+    setError(null); setIsRunning(true);
+
+    try {
+      // 1. Resolve nonce
+      let nonce;
+      if (apiKey) {
+        const res = await fetch(`${apiUrl}/v1/challenge`, {
+          headers: { 'Authorization': `Bearer ${apiKey}` },
+        });
+        if (!res.ok) throw new Error(`Challenge failed: ${res.status}`);
+        ({ nonce } = await res.json());
+      } else if (challengeUrl) {
+        const res = await fetch(challengeUrl);
+        if (!res.ok) throw new Error(`Challenge failed: ${res.status}`);
+        ({ nonce } = await res.json());
+      } else {
+        throw new Error(
+          'usePulse requires either apiKey or challengeUrl. ' +
+          'Pass apiKey for the hosted API, or challengeUrl + verifyUrl for self-hosted.'
+        );
+      }
+
+      // 2. Run the probe
+      const pulse = await getPulse();
+      const commitment = await pulse({
+        nonce,
+        iterations,
+        bioWindowMs,
+        adaptive,
+        onProgress: (s, meta = {}) => {
+          setStage(s);
+          if (s === 'entropy_batch' && meta) {
+            if (meta.pct         != null) setPct(meta.pct);
+            if (meta.vmConf      != null) setVmConf(meta.vmConf);
+            if (meta.hwConf      != null) setHwConf(meta.hwConf);
+            if (meta.earlyVerdict != null) setEarlyVerdict(meta.earlyVerdict);
+          }
+        },
+      });
+
+      setProof(commitment);
+      setPct(100);
+
+      // 3. Verify (hosted or self-hosted)
+      if (apiKey || verifyUrl) {
+        const url     = apiKey ? `${apiUrl}/v1/verify` : verifyUrl;
+        const headers = {
+          'Content-Type': 'application/json',
+          ...(apiKey ? { 'Authorization': `Bearer ${apiKey}` } : {}),
+        };
+
+        const res = await fetch(url, {
+          method:  'POST',
+          headers,
+          body:    JSON.stringify({ payload: commitment.payload, hash: commitment.hash }),
+        });
+        const verifyResult = await res.json();
+        setResult(verifyResult);
+        onResult?.(verifyResult, commitment);
+      } else {
+        onResult?.(null, commitment);
+      }
+
+    } catch (err) {
+      setError(err);
+      onError?.(err);
+    } finally {
+      setIsRunning(false);
+    }
+  }, [isRunning, apiKey, apiUrl, challengeUrl, verifyUrl, iterations, bioWindowMs, adaptive, onResult, onError]);
+
+  // ── reset() ──────────────────────────────────────────────────────────────
+  const reset = useCallback(() => {
+    setStage(null); setPct(0); setVmConf(0); setHwConf(0);
+    setEarlyVerdict(null); setProof(null); setResult(null);
+    setIsRunning(false); setError(null);
+  }, []);
+
+  // ── autoRun on mount ──────────────────────────────────────────────────────
+  // Note: We use a ref to avoid triggering on every render.
+  // Consumers should wrap in useEffect if they need SSR safety:
+  // useEffect(() => { if (autoRun) run(); }, []);
+  if (autoRun && !hasAutoRun.current && typeof window !== 'undefined') {
+    hasAutoRun.current = true;
+    // Defer to next microtask so hook state is initialised
+    Promise.resolve().then(run);
+  }
+
+  return {
+    // Actions
+    run,
+    reset,
+    // Live probe state
+    stage,
+    pct,
+    vmConf,
+    hwConf,
+    earlyVerdict,
+    // Results
+    proof,
+    result,
+    // Status
+    isRunning,
+    isReady: !isRunning && (proof != null || error != null),
+    error,
+  };
+}

package/src/middleware/express.js

@@ -0,0 +1,155 @@
+/**
+ * @sovereign/pulse — Express Middleware
+ *
+ * Drop-in middleware for Express / Fastify / Hono.
+ * Handles the full challenge → verify flow in two lines of code.
+ *
+ * Usage:
+ *
+ *   import { createPulseMiddleware } from '@sovereign/pulse/middleware/express';
+ *
+ *   const pulse = createPulseMiddleware({ threshold: 0.6 });
+ *
+ *   app.get('/api/pulse/challenge', pulse.challenge);
+ *   app.post('/checkout', pulse.verify, checkoutHandler);
+ *
+ * With Redis (recommended for production):
+ *
+ *   import Redis from 'ioredis';
+ *   const redis = new Redis(process.env.REDIS_URL);
+ *
+ *   const pulse = createPulseMiddleware({
+ *     threshold: 0.6,
+ *     store: {
+ *       set: (k, ttl) => redis.set(k, '1', 'EX', ttl),
+ *       consume: (k)  => redis.del(k).then(n => n === 1),
+ *     },
+ *   });
+ */
+
+import { validateProof, generateNonce } from '../proof/validator.js';
+
+// ---------------------------------------------------------------------------
+// In-memory nonce store (single-process / development only)
+// ---------------------------------------------------------------------------
+
+function createMemoryStore(ttlMs = 300_000) {
+  const store = new Map();
+  return {
+    set(key) {
+      store.set(key, Date.now() + ttlMs);
+      // Lazy cleanup — don't leak memory in long-running processes
+      if (store.size > 10_000) {
+        const now = Date.now();
+        for (const [k, exp] of store) {
+          if (exp < now) store.delete(k);
+        }
+      }
+    },
+    consume(key) {
+      const exp = store.get(key);
+      if (!exp || Date.now() > exp) return false;
+      store.delete(key);
+      return true;
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// createPulseMiddleware
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {object}   opts
+ * @param {number}   [opts.threshold=0.55]          - minimum jitter score (0–1)
+ * @param {number}   [opts.nonceTTL=300]             - nonce lifetime in seconds
+ * @param {boolean}  [opts.requireBio=false]         - reject if no mouse/keyboard activity
+ * @param {boolean}  [opts.blockSoftwareRenderer=true]
+ * @param {object}   [opts.store]                    - custom nonce store (see above)
+ * @param {string}   [opts.proofHeader='x-pulse-proof'] - request header name
+ * @param {string}   [opts.hashHeader='x-pulse-hash']
+ * @param {Function} [opts.onReject]                 - custom rejection handler
+ * @param {Function} [opts.onError]                  - custom error handler
+ * @returns {{ challenge: Function, verify: Function }}
+ */
+export function createPulseMiddleware(opts = {}) {
+  const {
+    threshold            = 0.55,
+    nonceTTL             = 300,
+    requireBio           = false,
+    blockSoftwareRenderer = true,
+    proofHeader          = 'x-pulse-proof',
+    hashHeader           = 'x-pulse-hash',
+    onReject,
+    onError,
+  } = opts;
+
+  // Allow external store (Redis, etc.) or default to in-memory
+  const store = opts.store ?? createMemoryStore(nonceTTL * 1000);
+
+  // ── challenge — GET /api/pulse/challenge ──────────────────────────────────
+  async function challenge(req, res) {
+    try {
+      const nonce = generateNonce();
+      await store.set(`pulse:${nonce}`);
+      res.json({ nonce, expiresIn: nonceTTL });
+    } catch (err) {
+      if (onError) return onError(err, req, res);
+      res.status(500).json({ error: 'Failed to generate challenge' });
+    }
+  }
+
+  // ── verify — middleware for protected routes ───────────────────────────────
+  async function verify(req, res, next) {
+    try {
+      // Support both header and body delivery
+      let payload, hash;
+      if (req.headers[proofHeader]) {
+        try   { payload = JSON.parse(req.headers[proofHeader]); }
+        catch { return _reject(res, 400, 'MALFORMED_PROOF_HEADER', 'Could not parse x-pulse-proof header as JSON', onReject, req); }
+        hash = req.headers[hashHeader];
+      } else if (req.body?.pulsePayload) {
+        payload = req.body.pulsePayload;
+        hash    = req.body.pulseHash;
+      } else {
+        return _reject(res, 401, 'MISSING_PROOF', 'No pulse proof found in headers or body', onReject, req);
+      }
+
+      if (!hash) {
+        return _reject(res, 401, 'MISSING_HASH', 'No pulse hash provided', onReject, req);
+      }
+
+      const result = await validateProof(payload, hash, {
+        minJitterScore: threshold,
+        requireBio,
+        blockSoftwareRenderer,
+        checkNonce: async (n) => store.consume(`pulse:${n}`),
+      });
+
+      if (!result.valid) {
+        return _reject(res, 403, 'PROOF_INVALID', result.reasons.join('; '), onReject, req, result);
+      }
+
+      // Attach result to request for downstream handlers
+      req.pulse = result;
+      next();
+
+    } catch (err) {
+      if (onError) return onError(err, req, res, next);
+      res.status(500).json({ error: 'Pulse verification error' });
+    }
+  }
+
+  return { challenge, verify };
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function _reject(res, status, code, message, customHandler, req, result = {}) {
+  if (customHandler) {
+    return customHandler(req, res, { code, message, ...result });
+  }
+  res.status(status).json({ error: code, message, ...result });
+}

package/src/middleware/next.js

@@ -0,0 +1,175 @@
+/**
+ * @sovereign/pulse — Next.js App Router Middleware
+ *
+ * Works with Next.js App Router (13+) and Edge Runtime.
+ *
+ * ── Route Handler wrapper ──────────────────────────────────────────────────
+ *
+ *   // app/api/checkout/route.js
+ *   import { withPulse } from '@sovereign/pulse/middleware/next';
+ *
+ *   export const POST = withPulse({ threshold: 0.6 })(
+ *     async (req) => {
+ *       const { score, provider } = req.pulse;
+ *       return Response.json({ ok: true, score });
+ *     }
+ *   );
+ *
+ * ── Challenge endpoint (copy-paste ready) ─────────────────────────────────
+ *
+ *   // app/api/pulse/challenge/route.js
+ *   import { pulseChallenge } from '@sovereign/pulse/middleware/next';
+ *   export const GET = pulseChallenge();
+ *
+ * ── Edge-compatible nonce store ────────────────────────────────────────────
+ *
+ *   // Uses in-memory by default.  For multi-instance deployments, provide
+ *   // a KV store (Vercel KV, Cloudflare KV, Redis via fetch):
+ *
+ *   import { kv } from '@vercel/kv';
+ *   export const POST = withPulse({
+ *     threshold: 0.6,
+ *     store: {
+ *       set:     (k, ttl) => kv.set(k, '1', { ex: ttl }),
+ *       consume: (k)      => kv.del(k).then(n => n === 1),
+ *     },
+ *   })(handler);
+ */
+
+import { validateProof, generateNonce } from '../proof/validator.js';
+
+// ---------------------------------------------------------------------------
+// Shared in-memory nonce store (single instance / dev only)
+// ---------------------------------------------------------------------------
+
+const _memStore = new Map();
+
+function memoryStore(ttlSec) {
+  return {
+    set(key) {
+      _memStore.set(key, Date.now() + ttlSec * 1000);
+    },
+    consume(key) {
+      const exp = _memStore.get(key);
+      if (!exp || Date.now() > exp) return false;
+      _memStore.delete(key);
+      return true;
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// pulseChallenge  — GET /api/pulse/challenge
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {object} [opts]
+ * @param {number} [opts.ttl=300]    - nonce TTL in seconds
+ * @param {object} [opts.store]      - custom nonce store
+ */
+export function pulseChallenge(opts = {}) {
+  const { ttl = 300, store } = opts;
+  const _store = store ?? memoryStore(ttl);
+
+  return async function GET() {
+    const nonce = generateNonce();
+    await _store.set(`pulse:${nonce}`);
+    return Response.json({ nonce, expiresIn: ttl });
+  };
+}
+
+// ---------------------------------------------------------------------------
+// withPulse  — wraps a Next.js route handler
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {object}   opts
+ * @param {number}   [opts.threshold=0.55]
+ * @param {number}   [opts.ttl=300]               - nonce TTL
+ * @param {boolean}  [opts.requireBio=false]
+ * @param {boolean}  [opts.blockSoftwareRenderer=true]
+ * @param {object}   [opts.store]                  - custom nonce store
+ * @returns {(handler: Function) => Function}       - HOC
+ */
+export function withPulse(opts = {}) {
+  const {
+    threshold            = 0.55,
+    ttl                  = 300,
+    requireBio           = false,
+    blockSoftwareRenderer = true,
+    store,
+  } = opts;
+
+  const _store = store ?? memoryStore(ttl);
+
+  return function wrap(handler) {
+    return async function wrappedHandler(req, ...args) {
+      // ── Read proof from headers (preferred) or body ──────────────────────
+      const proofHeader = req.headers.get('x-pulse-proof');
+      const hashHeader  = req.headers.get('x-pulse-hash');
+
+      let payload, hash;
+
+      if (proofHeader) {
+        try   { payload = JSON.parse(proofHeader); }
+        catch { return _err(400, 'MALFORMED_PROOF', 'Could not parse x-pulse-proof header'); }
+        hash = hashHeader;
+      } else {
+        // Attempt to read from JSON body (non-streaming)
+        try {
+          const body = await req.clone().json();
+          payload    = body.pulsePayload;
+          hash       = body.pulseHash;
+        } catch {}
+      }
+
+      if (!payload || !hash) {
+        return _err(401, 'MISSING_PROOF',
+          'Provide pulse proof via x-pulse-proof + x-pulse-hash headers, ' +
+          'or pulsePayload + pulseHash in the request body.'
+        );
+      }
+
+      // ── Validate ───────────────────────────────────────────────────────────
+      let result;
+      try {
+        result = await validateProof(payload, hash, {
+          minJitterScore: threshold,
+          requireBio,
+          blockSoftwareRenderer,
+          checkNonce: async (n) => _store.consume(`pulse:${n}`),
+        });
+      } catch (err) {
+        console.error('[pulse] validateProof error:', err);
+        return _err(500, 'VALIDATION_ERROR', 'Internal error during proof validation');
+      }
+
+      if (!result.valid) {
+        return Response.json(
+          { error: 'PULSE_REJECTED', reasons: result.reasons, riskFlags: result.riskFlags },
+          { status: 403 }
+        );
+      }
+
+      // ── Attach pulse result and call the real handler ──────────────────────
+      // Next.js Request is immutable so we inject via a lightweight proxy
+      const enriched = new Proxy(req, {
+        get(target, prop) {
+          if (prop === 'pulse') return result;
+          const val = target[prop];
+          return typeof val === 'function' ? val.bind(target) : val;
+        },
+      });
+
+      return handler(enriched, ...args);
+    };
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function _err(status, code, message) {
+  return Response.json({ error: code, message }, { status });
+}