@svrnsec/pulse 0.4.0 → 0.5.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@svrnsec/pulse",
-  "version": "0.4.0",
-  "description": "Physical Turing Test — Hardware-Biological Symmetry Protocol distinguishing real consumer devices from sanitised datacenter VMs.",
+  "version": "0.5.0",
+  "description": "Physical Turing Test — Idle attestation, population-level Sybil detection, and engagement tokens that defeat click farms at the physics layer.",
   "type": "module",
   "license": "MIT",
   "author": "Aaron Miller",
@@ -71,6 +71,18 @@
     },
     "./enf": {
       "import": "./src/collector/enf.js"
+    },
+    "./idle": {
+      "import": "./src/collector/idleAttestation.js",
+      "node":   "./src/collector/idleAttestation.js"
+    },
+    "./population": {
+      "import": "./src/analysis/populationEntropy.js",
+      "node":   "./src/analysis/populationEntropy.js"
+    },
+    "./engage": {
+      "import": "./src/proof/engagementToken.js",
+      "node":   "./src/proof/engagementToken.js"
     }
   },
   "main":   "dist/pulse.cjs.js",
@@ -132,7 +144,13 @@
     "react-native",
     "mobile-security",
     "enf-detection",
-    "cli"
+    "cli",
+    "click-farm-detection",
+    "idle-attestation",
+    "engagement-token",
+    "sybil-detection",
+    "invalid-traffic",
+    "proof-of-idle"
   ],
   "engines": {
     "node": ">=18.0.0"

package/src/analysis/populationEntropy.js

@@ -0,0 +1,403 @@
+/**
+ * @svrnsec/pulse — Population Entropy Analysis
+ *
+ * Server-side Sybil detector: given N engagement tokens from the same cohort
+ * (e.g., all ad clicks in a 10-minute window), determine whether they
+ * represent independently-operated consumer devices or a coordinated farm.
+ *
+ * Why per-token verification is necessary but not sufficient
+ * ──────────────────────────────────────────────────────────
+ * A single token from a farm device may pass every individual check:
+ *   - Real hardware  ✓  (it is a real phone)
+ *   - Valid idle proof ✓  (45+ seconds of forced downtime)
+ *   - Plausible entropy ✓  (within normal ranges)
+ *
+ * But 1,000 farm devices in one warehouse share inescapable physical context:
+ *   - Same ambient temperature  → correlated DRAM timing variance
+ *   - Same power circuit        → near-identical ENF phase deviation
+ *   - Coordinator dispatch      → rhythmic submission timestamp patterns
+ *   - Same operational pattern  → homogeneous thermal transitions
+ *   - Economic throughput limit → idle durations cluster at the minimum
+ *
+ * Population analysis exposes these systematic correlations that are
+ * individually invisible but statistically unmistakable at scale.
+ *
+ * Statistical tests (5)
+ * ─────────────────────
+ *   1. Timestamp rhythm        — autocorrelation of inter-arrival times
+ *   2. Entropy dispersion      — coefficient of variation across physics scores
+ *   3. Thermal diversity       — Shannon entropy of thermal transition labels
+ *   4. Idle duration cluster   — fraction of durations near the minimum viable
+ *   5. ENF phase coherence     — variance of measured grid frequency deviations
+ *
+ * Scoring
+ * ───────
+ * Each test returns a sybilScore in [0, 100] where 100 = maximally suspicious.
+ * The population sybilScore is a weighted average of the five tests.
+ * An authentic cohort scores < 40; a clear farm scores > 70.
+ */
+
+// ── analysePopulation ─────────────────────────────────────────────────────────
+
+/**
+ * Analyse a cohort of parsed engagement tokens for population-level Sybil signals.
+ *
+ * @param {ParsedEngagementToken[]} tokens  decoded (not yet signature-verified) tokens
+ * @param {object}  [opts]
+ * @param {number}  [opts.minSample=5]  minimum cohort size for a meaningful verdict
+ * @returns {PopulationVerdict}
+ */
+export function analysePopulation(tokens, opts = {}) {
+  const { minSample = 5 } = opts;
+
+  if (!Array.isArray(tokens) || tokens.length < minSample) {
+    return _insufficientSample(tokens?.length ?? 0, minSample);
+  }
+
+  const rhythmResult  = testTimestampRhythm(tokens);
+  const dispersion    = testEntropyDispersion(tokens);
+  const thermalDiv    = testThermalDiversity(tokens);
+  const idlePlaus     = testIdlePlausibility(tokens);
+  const enfCoherence  = testEnfCoherence(tokens);
+
+  // Weighted aggregate (weights reflect signal reliability and discriminative power)
+  const sybilScore = Math.round(
+    rhythmResult.score * 0.25 +
+    dispersion.score   * 0.25 +
+    thermalDiv.score   * 0.20 +
+    idlePlaus.score    * 0.20 +
+    enfCoherence.score * 0.10
+  );
+
+  // Confidence scales with cohort size — small cohorts can't make strong claims
+  const confidence = +Math.min(1.0, tokens.length / 50).toFixed(3);
+
+  const flags = [
+    rhythmResult.score  > 60 && 'RHYTHMIC_DISPATCH',
+    dispersion.score    > 60 && 'HOMOGENEOUS_HARDWARE',
+    thermalDiv.score    > 60 && 'UNIFORM_THERMAL_PATTERN',
+    idlePlaus.score     > 60 && 'SYNTHETIC_IDLE_CLUSTERING',
+    enfCoherence.score  > 60 && 'CO_LOCATED_DEVICES',
+  ].filter(Boolean);
+
+  return {
+    authentic:   sybilScore < 40,
+    sybilScore,
+    confidence,
+    tests: {
+      timestampRhythm:   rhythmResult,
+      entropyDispersion: dispersion,
+      thermalDiversity:  thermalDiv,
+      idlePlausibility:  idlePlaus,
+      enfCoherence,
+    },
+    flags,
+    summary: _formatSummary(sybilScore, flags, tokens.length),
+  };
+}
+
+// ── Test 1: Timestamp Rhythm ──────────────────────────────────────────────────
+
+/**
+ * Farm coordinators dispatch tokens in batches at scheduler-driven intervals.
+ * A coordinator sending 1,000 tokens at 120-second intervals produces strong
+ * positive autocorrelation in the inter-arrival time series.
+ *
+ * Real users click independently; their inter-arrival times are random.
+ *
+ * @param {ParsedEngagementToken[]} tokens
+ * @returns {{ score: number, ac1: number, ac2: number, detail: string }}
+ */
+export function testTimestampRhythm(tokens) {
+  const timestamps = tokens.map(t => t.iat).filter(Number.isFinite).sort((a, b) => a - b);
+  if (timestamps.length < 4) {
+    return { score: 0, ac1: 0, ac2: 0, detail: 'insufficient_samples' };
+  }
+
+  // Inter-arrival times in milliseconds
+  const deltas = [];
+  for (let i = 1; i < timestamps.length; i++) {
+    deltas.push(timestamps[i] - timestamps[i - 1]);
+  }
+
+  const n    = deltas.length;
+  const mean = _mean(deltas);
+  const v0   = _variance(deltas, mean);
+
+  // Zero-variance: perfectly uniform dispatch — maximally suspicious
+  if (v0 < 1e-6) {
+    return { score: 100, ac1: 1, ac2: 1, detail: 'perfectly_uniform_dispatch' };
+  }
+
+  const ac1 = _autocorrAtLag(deltas, mean, v0, 1);
+  const ac2 = _autocorrAtLag(deltas, mean, v0, 2);
+
+  // Use the more suspicious of the two lags
+  const signal = Math.max(Math.abs(ac1), Math.abs(ac2));
+
+  // Threshold calibration:
+  //   |ac| < 0.15  → independent (real users)
+  //   |ac| > 0.40  → rhythmic (farm coordinator)
+  const score = Math.min(100, Math.max(0,
+    ((signal - 0.15) / (0.40 - 0.15)) * 100
+  ));
+
+  return {
+    score:  Math.round(score),
+    ac1:    +ac1.toFixed(3),
+    ac2:    +ac2.toFixed(3),
+    detail: signal > 0.40 ? 'rhythmic_dispatch_detected' : 'normal_variance',
+  };
+}
+
+// ── Test 2: Entropy Dispersion ────────────────────────────────────────────────
+
+/**
+ * Real users bring diverse device histories: different ages, temperatures,
+ * load profiles. Their physics scores (entropy, jitter) span a wide range.
+ *
+ * Farm devices in one warehouse are typically the same model, same ambient
+ * temperature, running the same workload. Their scores cluster tightly.
+ *
+ * @param {ParsedEngagementToken[]} tokens
+ * @returns {{ score: number, cv: number, mean: number, detail: string }}
+ */
+export function testEntropyDispersion(tokens) {
+  const scores = tokens.map(t => t.hw?.ent).filter(v => v != null && Number.isFinite(v) && v > 0);
+  if (scores.length < 3) {
+    return { score: 0, cv: 0, mean: 0, detail: 'no_entropy_data' };
+  }
+
+  const mean   = _mean(scores);
+  if (mean < 1e-9) return { score: 50, cv: 0, mean: 0, detail: 'zero_entropy_scores' };
+
+  const stddev = Math.sqrt(_variance(scores, mean));
+  const cv     = stddev / mean; // Coefficient of Variation
+
+  // Calibration:
+  //   CV > 0.12  → diverse hardware (real users)
+  //   CV < 0.04  → homogeneous (farm devices)
+  const score = Math.min(100, Math.max(0,
+    ((0.10 - cv) / (0.10 - 0.03)) * 100
+  ));
+
+  return {
+    score:  Math.round(score),
+    cv:     +cv.toFixed(4),
+    mean:   +mean.toFixed(3),
+    detail: cv < 0.04 ? 'homogeneous_hardware_detected' : 'normal_diversity',
+  };
+}
+
+// ── Test 3: Thermal Diversity ─────────────────────────────────────────────────
+
+/**
+ * Real users encounter devices in diverse thermal states throughout the day:
+ * cold morning wake-ups, warm post-commute picks, hot post-gaming sessions.
+ * The population distribution across transition labels should be broad.
+ *
+ * Farm devices maintain constant operational throughput. Their transitions
+ * cluster at 'step_function' (scripted pause) or 'sustained_hot' (constant load).
+ *
+ * @param {ParsedEngagementToken[]} tokens
+ * @returns {{ score: number, suspiciousRatio: number, distribution: object, detail: string }}
+ */
+export function testThermalDiversity(tokens) {
+  const transitions = tokens.map(t => t.idle?.therm).filter(Boolean);
+  if (transitions.length < 3) {
+    return { score: 0, suspiciousRatio: 0, distribution: {}, detail: 'no_thermal_data' };
+  }
+
+  const counts = {};
+  for (const t of transitions) counts[t] = (counts[t] ?? 0) + 1;
+  const total = transitions.length;
+
+  // Farm-indicator transitions
+  const suspicious     = (counts.step_function ?? 0) + (counts.sustained_hot ?? 0);
+  const suspiciousRatio = suspicious / total;
+
+  // Shannon entropy of the transition label distribution
+  const probs           = Object.values(counts).map(c => c / total);
+  const popEntropy      = _shannonEntropy(probs);
+  const maxEntropy      = Math.log2(6); // 6 possible labels
+
+  // Combined: raw suspicious ratio + low population entropy both indicate farm
+  const ratioScore   = Math.min(100, suspiciousRatio * 100);
+  const entropyScore = Math.min(80, (1 - popEntropy / maxEntropy) * 80);
+  const score        = Math.round(0.6 * ratioScore + 0.4 * entropyScore);
+
+  const detail = suspiciousRatio > 0.50
+    ? 'majority_farm_thermal_transitions'
+    : popEntropy < maxEntropy * 0.40
+      ? 'low_thermal_label_diversity'
+      : 'normal_distribution';
+
+  return {
+    score,
+    suspiciousRatio: +suspiciousRatio.toFixed(3),
+    distribution:    Object.fromEntries(
+      Object.entries(counts).map(([k, v]) => [k, +(v / total).toFixed(3)])
+    ),
+    detail,
+  };
+}
+
+// ── Test 4: Idle Duration Plausibility ───────────────────────────────────────
+
+/**
+ * Real humans idle unpredictably: 5 minutes for a notification, an hour for
+ * lunch, 8 hours overnight. The distribution is broad and roughly log-normal.
+ *
+ * Farm scripts, constrained by throughput targets, idle for exactly the
+ * minimum duration required to pass attestation (~45–90s). The population
+ * reveals a tight cluster just above the minimum viable threshold.
+ *
+ * @param {ParsedEngagementToken[]} tokens
+ * @returns {{ score: number, clusterRatio: number, medianMs: number, detail: string }}
+ */
+export function testIdlePlausibility(tokens) {
+  const durations = tokens.map(t => t.idle?.dMs).filter(d => d != null && d > 0);
+  if (durations.length < 3) {
+    return { score: 0, clusterRatio: 0, medianMs: 0, detail: 'no_idle_data' };
+  }
+
+  // The "barely made it" window: idle just long enough to pass, then immediately resume
+  const CLUSTER_LO = 45_000;   // MIN_IDLE_MS
+  const CLUSTER_HI = 100_000;  // 2.2× minimum — beyond this, farms lose too much throughput
+
+  const inCluster    = durations.filter(d => d >= CLUSTER_LO && d <= CLUSTER_HI).length;
+  const clusterRatio = inCluster / durations.length;
+
+  // Low coefficient of variation = durations are suspiciously uniform
+  const mean   = _mean(durations);
+  const stddev = Math.sqrt(_variance(durations, mean));
+  const cv     = stddev / (mean + 1);
+
+  // Scoring: high cluster ratio + low duration CV = farm fingerprint
+  const clusterScore = Math.min(70, Math.max(0, (clusterRatio - 0.40) / (0.80 - 0.40)) * 70);
+  const cvScore      = Math.min(30, Math.max(0, (0.50 - cv)           / (0.50 - 0.10)) * 30);
+  const score        = Math.round(clusterScore + cvScore);
+
+  return {
+    score,
+    clusterRatio: +clusterRatio.toFixed(3),
+    medianMs:     _median(durations),
+    detail:       clusterRatio > 0.70 ? 'idle_duration_clustered_at_minimum' : 'normal_distribution',
+  };
+}
+
+// ── Test 5: ENF Phase Coherence ───────────────────────────────────────────────
+
+/**
+ * All devices on the same electrical circuit share the same ENF phase.
+ * A 1,000-device farm in a single warehouse shares one power feed — their
+ * ENF frequency deviations are nearly identical.
+ *
+ * Real users across a city are on separate circuits with independent phase
+ * evolution; their deviations spread naturally over a measurable range.
+ *
+ * @param {ParsedEngagementToken[]} tokens
+ * @returns {{ score: number, phaseVariance: number|null, detail: string }}
+ */
+export function testEnfCoherence(tokens) {
+  const deviations = tokens
+    .map(t => t.hw?.enfDev)
+    .filter(d => d != null && Number.isFinite(d));
+
+  if (deviations.length < 4) {
+    return { score: 0, phaseVariance: null, detail: 'enf_unavailable_or_insufficient' };
+  }
+
+  const mean     = _mean(deviations);
+  const variance = _variance(deviations, mean);
+
+  // Calibration (Hz² variance):
+  //   variance > 0.0002  → diverse circuits (real users across a city)
+  //   variance < 0.00002 → same rack, same feed (co-located farm)
+  const score = Math.round(Math.min(100, Math.max(0,
+    (1 - variance / 0.0002) * 100
+  )));
+
+  return {
+    score,
+    phaseVariance: +variance.toFixed(8),
+    detail:        variance < 0.00002 ? 'co_located_devices_same_circuit' : 'normal_phase_spread',
+  };
+}
+
+// ── Internal helpers ──────────────────────────────────────────────────────────
+
+function _mean(arr) {
+  if (!arr.length) return 0;
+  return arr.reduce((s, v) => s + v, 0) / arr.length;
+}
+
+function _variance(arr, mean) {
+  if (arr.length < 2) return 0;
+  return arr.reduce((s, v) => s + (v - mean) ** 2, 0) / arr.length;
+}
+
+function _median(arr) {
+  const s   = [...arr].sort((a, b) => a - b);
+  const mid = Math.floor(s.length / 2);
+  return s.length % 2 ? s[mid] : Math.round((s[mid - 1] + s[mid]) / 2);
+}
+
+function _autocorrAtLag(data, mean, variance, lag) {
+  const n = data.length;
+  if (lag >= n || variance < 1e-12) return 0;
+  let cov = 0;
+  for (let i = 0; i < n - lag; i++) {
+    cov += (data[i] - mean) * (data[i + lag] - mean);
+  }
+  return cov / ((n - lag) * variance);
+}
+
+function _shannonEntropy(probs) {
+  return -probs
+    .filter(p => p > 0)
+    .reduce((s, p) => s + p * Math.log2(p), 0);
+}
+
+function _formatSummary(score, flags, n) {
+  const risk    = score >= 80 ? 'HIGH_RISK'
+                : score >= 50 ? 'SUSPICIOUS'
+                : score >= 30 ? 'MARGINAL'
+                :               'CLEAN';
+  const flagStr = flags.length ? `  flags=[${flags.join(',')}]` : '';
+  return `${risk}: sybilScore=${score}/100  n=${n}${flagStr}`;
+}
+
+function _insufficientSample(n, required) {
+  return {
+    authentic:   true,    // default to not blocking on insufficient data
+    sybilScore:  0,
+    confidence:  0,
+    tests:       {},
+    flags:       [],
+    summary:     `INSUFFICIENT_SAMPLE: ${n}/${required} tokens required for analysis`,
+  };
+}
+
+// ── JSDoc types ───────────────────────────────────────────────────────────────
+
+/**
+ * @typedef {object} ParsedEngagementToken
+ * @property {number}       iat          issued-at Unix ms
+ * @property {object}       [idle]       idle proof summary
+ * @property {number|null}  [idle.dMs]   idle duration ms
+ * @property {string}       [idle.therm] thermal transition label
+ * @property {object}       [hw]         hardware signal summary
+ * @property {number}       [hw.ent]     normalized entropy score (0–1)
+ * @property {number}       [hw.enfDev]  ENF frequency deviation (Hz)
+ */
+
+/**
+ * @typedef {object} PopulationVerdict
+ * @property {boolean}   authentic      true if population appears legitimate (sybilScore < 40)
+ * @property {number}    sybilScore     0–100 suspicion score (higher = more suspicious)
+ * @property {number}    confidence     0–1 confidence in verdict (scales with cohort size)
+ * @property {object}    tests          per-test result objects
+ * @property {string[]}  flags          fired detection flags
+ * @property {string}    summary        one-line human-readable summary
+ */

package/src/analysis/trustScore.js

@@ -119,6 +119,31 @@ export function computeTrustScore(payload, extended = {}) {
     bonuses.push({ signal: 'gpu+dram', reason: 'GPU thermal + DRAM refresh both confirmed', pts: 3 });
   }
 
+  // ── 6. Idle attestation (bonus/penalty from engagement token) ─────────────
+  // The idle proof is optional — only present when createEngagementToken() is used.
+  // Genuine thermal cooling proves the device was not running continuous load.
+  const idleProof = extended.idle ?? payload?.signals?.idle ?? null;
+  if (idleProof) {
+    const { thermalTransition, coolingMonotonicity, samples } = idleProof;
+
+    if (thermalTransition === 'hot_to_cold' || thermalTransition === 'cold') {
+      bonuses.push({ signal: 'idle', reason: 'Genuine thermal cooling confirmed between interactions', pts: 5 });
+      if (coolingMonotonicity >= 0.8 && samples >= 3) {
+        bonuses.push({ signal: 'idle', reason: 'Smooth exponential cooling curve — consistent with Newton cooling', pts: 3 });
+      }
+    } else if (thermalTransition === 'cooling') {
+      bonuses.push({ signal: 'idle', reason: 'Mild thermal decay during idle period', pts: 2 });
+    } else if (thermalTransition === 'step_function') {
+      // Abrupt variance drop: characteristic of script pause, not natural idle
+      hardCap = Math.min(hardCap, 65);
+      penalties.push({ signal: 'idle', reason: 'Step-function thermal transition (click farm script pause pattern)', cap: 65 });
+    } else if (thermalTransition === 'sustained_hot') {
+      // No cooling at all: device was under constant load throughout "idle"
+      hardCap = Math.min(hardCap, 60);
+      penalties.push({ signal: 'idle', reason: 'No thermal decay during idle — sustained load pattern', cap: 60 });
+    }
+  }
+
   // ── Raw score ─────────────────────────────────────────────────────────────
   const bonusPts = bonuses.reduce((s, b) => s + b.pts, 0);
   const raw = Math.min(100,

package/src/collector/idleAttestation.js

@@ -0,0 +1,480 @@
+/**
+ * @svrnsec/pulse — Idle Attestation Collector
+ *
+ * Click farms run thousands of real devices at sustained maximum throughput —
+ * they physically cannot let a device idle. This module builds a cryptographic
+ * proof that a device experienced a genuine rest period between interactions:
+ * thermal cooling, CPU clock-scaling, and a hash-chained measurement sequence
+ * that cannot be back-filled faster than real time.
+ *
+ * Physics basis
+ * ─────────────
+ *   Real device between interactions:
+ *     → CPU frequency drops via DVFS (Dynamic Voltage/Frequency Scaling)
+ *     → DRAM access latency rises as the front-side bus slows down
+ *     → Thermal mass of die + PCB means temperature decays exponentially
+ *     → Timing variance follows Newton's Law of Cooling — a smooth curve
+ *
+ *   Click farm device with paused script:
+ *     → CPU load drops from ~100% to ~0% INSTANTLY (OS task queue emptied)
+ *     → DRAM timing shows a STEP FUNCTION, not an exponential curve
+ *     → The step is economically forced: farm scripts resume within 90s
+ *       to maintain throughput; real thermal settling takes minutes
+ *
+ * Hash chain
+ * ──────────
+ *   Each idle sample produces a chain node:
+ *     node[n].hash = SHA-256(node[n-1].hash ‖ ts ‖ meanMs ‖ variance)
+ *
+ *   The chain proves samples were taken in sequence at regular intervals.
+ *   N nodes at 30-second intervals = (N−1)×30s minimum elapsed time.
+ *   It cannot be fabricated faster than real time without the server
+ *   noticing the timing impossibility.
+ *
+ * Thermal transition taxonomy
+ * ───────────────────────────
+ *   hot_to_cold    → smooth exponential variance decay  (genuine cooling ✓)
+ *   cold           → device was already at rest temperature (genuine idle ✓)
+ *   cooling        → mild, ongoing decay (genuine idle ✓)
+ *   warming        → device heating up (uncommon during idle)
+ *   sustained_hot  → elevated variance throughout (click farm: constant load ✗)
+ *   step_function  → abrupt single-interval drop (click farm: script paused ✗)
+ *   unknown        → insufficient samples to classify
+ */
+
+import { sha256 }               from '@noble/hashes/sha256';
+import { bytesToHex,
+         utf8ToBytes,
+         randomBytes }          from '@noble/hashes/utils';
+
+// ── Constants ─────────────────────────────────────────────────────────────────
+
+/** Minimum idle duration before issuing a proof.
+ *  Farm scripts pause for < 30s to maintain throughput.
+ *  This threshold creates a real economic cost: 45s idle × 1000 devices =
+ *  12.5 device-hours of forced downtime per 1000 tokens. */
+const MIN_IDLE_MS             = 45_000;
+
+/** Sampling interval. 30s gives 3 nodes in a 90s session — enough to
+ *  differentiate a cooling curve from a step function. */
+const SAMPLE_INTERVAL_MS      = 30_000;
+
+/** Grace period after focus/visibility loss before declaring idle.
+ *  Absorbs rapid tab switches and accidental blur events. */
+const IDLE_WATCH_GRACE_MS     = 5_000;
+
+/** Mini probe buffer — 16 MB exceeds L3 cache on most consumer devices,
+ *  forcing reads to DRAM. Small enough that the probe finishes in < 100ms,
+ *  so we don't meaningfully disturb the idle state we're measuring. */
+const MINI_BUFFER_MB          = 16;
+
+/** Mini probe iteration count. ~80ms total wall-clock time. */
+const MINI_ITERATIONS         = 80;
+
+/** Variance at or below this value indicates a device at rest temperature.
+ *  Calibrated from empirical measurements on idle consumer hardware. */
+const COLD_VARIANCE_THRESHOLD = 0.003;
+
+/** Variance above this value indicates sustained CPU load — characteristic
+ *  of click farm operation (continuous task execution). */
+const HOT_VARIANCE_THRESHOLD  = 0.025;
+
+/** If more than this fraction of the total variance drop happens in the
+ *  first sample interval, we classify the transition as 'step_function'. */
+const STEP_FUNCTION_RATIO     = 0.75;
+
+// ── State machine ─────────────────────────────────────────────────────────────
+
+/** @enum {string} */
+const State = Object.freeze({
+  ACTIVE:         'active',         // device in normal use
+  IDLE_WATCH:     'idle_watch',     // focus lost, in grace period
+  IDLE_SAMPLING:  'idle_sampling',  // sampling in progress, chain building
+  IDLE_COMMITTED: 'idle_committed', // proof ready to consume
+});
+
+// ── createIdleMonitor ─────────────────────────────────────────────────────────
+
+/**
+ * Create a stateful idle monitor for the current session.
+ *
+ * **Browser**: automatically hooks `visibilitychange` and `blur`/`focus`.
+ * Call `monitor.start()` once on page load and `monitor.stop()` on unload.
+ *
+ * **Node.js / React Native**: call `monitor.declareIdle()` and
+ * `monitor.declareActive()` manually to drive the state machine.
+ *
+ * @param {object}  [opts]
+ * @param {number}  [opts.minIdleMs=45000]         minimum idle ms for valid proof
+ * @param {number}  [opts.sampleIntervalMs=30000]   thermal sampling interval
+ * @param {string}  [opts.sessionNonce]             ties hash chain to this session
+ * @returns {IdleMonitor}
+ */
+export function createIdleMonitor(opts = {}) {
+  const {
+    minIdleMs        = MIN_IDLE_MS,
+    sampleIntervalMs = SAMPLE_INTERVAL_MS,
+    sessionNonce     = bytesToHex(randomBytes(8)),
+  } = opts;
+
+  // ── Mutable private state (encapsulated in closure — no global mutation) ───
+  let _state         = State.ACTIVE;
+  let _idleStartMs   = 0;
+  let _watchTimer    = null;
+  let _sampleTimer   = null;
+  let _chain         = _genesisHash(sessionNonce);
+  let _samples       = /** @type {ThermalSample[]} */ ([]);
+  let _pendingProof  = null;
+  let _probeBuffer   = null;  // allocated lazily on first sample, then reused
+
+  // ── State transition: ACTIVE / IDLE_COMMITTED → IDLE_WATCH ───────────────
+  function _enterWatch() {
+    if (_state !== State.ACTIVE && _state !== State.IDLE_COMMITTED) return;
+    // Discard any unconsumed proof — a new idle cycle supersedes the old one.
+    _pendingProof = null;
+    _state        = State.IDLE_WATCH;
+    _watchTimer   = setTimeout(_enterSampling, IDLE_WATCH_GRACE_MS);
+  }
+
+  // ── State transition: IDLE_WATCH → IDLE_SAMPLING ──────────────────────────
+  function _enterSampling() {
+    _state       = State.IDLE_SAMPLING;
+    _idleStartMs = Date.now();
+    _samples     = [];
+    _chain       = _genesisHash(`${sessionNonce}:${_idleStartMs}`);
+
+    // Take first sample immediately, then on interval
+    _tick();
+    _sampleTimer = setInterval(_tick, sampleIntervalMs);
+  }
+
+  // ── Periodic sample tick ───────────────────────────────────────────────────
+  function _tick() {
+    // Allocate probe buffer once; reuse to avoid GC pressure every 30s
+    if (!_probeBuffer) _probeBuffer = _allocBuffer();
+    const sample = _miniProbe(_probeBuffer);
+    _samples.push(sample);
+    _chain = _chainStep(_chain, sample);
+  }
+
+  // ── State transition: IDLE_SAMPLING → IDLE_COMMITTED or ACTIVE ────────────
+  function _commitOrReset() {
+    clearTimeout(_watchTimer);
+    clearInterval(_sampleTimer);
+    _watchTimer  = null;
+    _sampleTimer = null;
+
+    const idleDurationMs   = Date.now() - _idleStartMs;
+    const hasEnoughTime    = idleDurationMs  >= minIdleMs;
+    const hasEnoughSamples = _samples.length >= 2;
+
+    if (_state === State.IDLE_SAMPLING && hasEnoughTime && hasEnoughSamples) {
+      _pendingProof = _buildProof(_chain, _samples, idleDurationMs);
+      _state        = State.IDLE_COMMITTED;
+    } else {
+      _reset();
+    }
+  }
+
+  // ── Reset to ACTIVE ────────────────────────────────────────────────────────
+  function _reset() {
+    _state        = State.ACTIVE;
+    _idleStartMs  = 0;
+    _samples      = [];
+    _pendingProof = null;
+    _chain        = _genesisHash(sessionNonce);
+  }
+
+  // ── Browser event handlers ─────────────────────────────────────────────────
+  const _onHide = () => _enterWatch();
+  const _onShow = () => { if (_state !== State.ACTIVE) _commitOrReset(); };
+
+  // ── Public API ────────────────────────────────────────────────────────────
+
+  /** Register browser event listeners. No-op in non-browser environments. */
+  function start() {
+    if (typeof document !== 'undefined') {
+      document.addEventListener('visibilitychange',
+        () => (document.hidden ? _onHide() : _onShow()));
+    }
+    if (typeof window !== 'undefined') {
+      window.addEventListener('blur',  _onHide);
+      window.addEventListener('focus', _onShow);
+    }
+    return api;
+  }
+
+  /** Deregister browser event listeners and cancel pending timers. */
+  function stop() {
+    clearTimeout(_watchTimer);
+    clearInterval(_sampleTimer);
+    if (typeof document !== 'undefined') {
+      document.removeEventListener('visibilitychange', _onHide);
+    }
+    if (typeof window !== 'undefined') {
+      window.removeEventListener('blur',  _onHide);
+      window.removeEventListener('focus', _onShow);
+    }
+    return api;
+  }
+
+  /** Manual idle declaration for Node.js or non-browser environments. */
+  function declareIdle()   { _enterWatch();       return api; }
+
+  /** Manual active declaration for Node.js or non-browser environments. */
+  function declareActive() { _commitOrReset();    return api; }
+
+  /**
+   * Consume the pending idle proof — one-time read that resets the monitor.
+   * Returns null if no valid proof is ready (device hasn't been idle long enough).
+   *
+   * @returns {IdleProof|null}
+   */
+  function getProof() {
+    if (_state !== State.IDLE_COMMITTED || !_pendingProof) return null;
+    const proof = { ..._pendingProof, capturedAt: Date.now() };
+    _reset();
+    return proof;
+  }
+
+  /** Current state machine state — useful for debugging and tests. */
+  function getState() { return _state; }
+
+  const api = { start, stop, getProof, getState, declareIdle, declareActive };
+  return api;
+}
+
+// ── analyseIdleProof ──────────────────────────────────────────────────────────
+
+/**
+ * Validate the physical plausibility of an IdleProof before embedding it in
+ * an engagement token. Returns advisory warnings without rejecting outright —
+ * the server-side verifier makes the final call.
+ *
+ * @param {IdleProof} proof
+ * @returns {{ plausible: boolean, reason?: string, warnings: string[] }}
+ */
+export function analyseIdleProof(proof) {
+  if (!proof) return { plausible: false, reason: 'no_proof', warnings: [] };
+
+  const warnings = [];
+
+  if (proof.idleDurationMs < MIN_IDLE_MS) {
+    return { plausible: false, reason: 'idle_too_short', warnings };
+  }
+
+  if (proof.samples < 2) {
+    return { plausible: false, reason: 'insufficient_chain_samples', warnings };
+  }
+
+  if (!proof.chain || proof.chain.length !== 64) {
+    return { plausible: false, reason: 'malformed_chain_hash', warnings };
+  }
+
+  if (proof.thermalTransition === 'step_function') {
+    warnings.push('abrupt_cpu_transition_detected');
+  }
+  if (proof.thermalTransition === 'sustained_hot') {
+    warnings.push('no_thermal_decay_observed');
+  }
+  if (proof.coolingMonotonicity < 0.3 && proof.samples >= 3) {
+    warnings.push('non_monotonic_cooling_curve');
+  }
+
+  return { plausible: true, warnings };
+}
+
+// ── Internal: mini DRAM probe ─────────────────────────────────────────────────
+
+/**
+ * Lightweight DRAM probe: 16 MB buffer, 80 iterations, < 100ms.
+ * Returns mean iteration time (reflects CPU clock frequency) and
+ * variance (reflects thermal noise intensity).
+ *
+ * Exported for unit testing — not part of the public API surface.
+ *
+ * @param {Float64Array} buf  pre-allocated cache-busting buffer
+ * @returns {ThermalSample}
+ */
+export function _miniProbe(buf) {
+  const pass   = _calibratePass(buf);
+  const timings = new Float64Array(MINI_ITERATIONS);
+  let   dummy   = 0;
+
+  for (let i = 0; i < MINI_ITERATIONS; i++) {
+    const t0 = performance.now();
+    for (let j = 0; j < pass; j++) dummy += buf[j];
+    timings[i] = performance.now() - t0;
+  }
+
+  // Prevent dead-code elimination of the memory reads
+  if (dummy === 0) buf[0] = 1;
+
+  const mean     = _mean(timings, MINI_ITERATIONS);
+  const variance = _variance(timings, MINI_ITERATIONS, mean);
+
+  return {
+    ts:       Date.now(),
+    meanMs:   +mean.toFixed(4),
+    variance: +variance.toFixed(6),
+  };
+}
+
+function _allocBuffer() {
+  const elements = (MINI_BUFFER_MB * 1024 * 1024) / 8;
+  try {
+    const buf    = new Float64Array(elements);
+    const stride = 64 / 8; // one element per 64-byte cache line
+    for (let i = 0; i < elements; i += stride) buf[i] = i;
+    return buf;
+  } catch {
+    // Memory-constrained fallback — smaller buffer means weaker signal
+    return new Float64Array(8_192);
+  }
+}
+
+function _calibratePass(buf) {
+  // Dynamically size the pass so each iteration takes ~1ms wall-clock.
+  // This self-calibrates across device classes (desktop, mobile, low-end).
+  const target  = 1.0; // ms
+  let   n       = Math.min(50_000, buf.length);
+  let   dummy   = 0;
+
+  // Warm-up (ensures first measurement isn't cold-start biased)
+  for (let i = 0; i < n; i++) dummy += buf[i];
+
+  const t0      = performance.now();
+  for (let i    = 0; i < n; i++) dummy += buf[i];
+  const elapsed = performance.now() - t0;
+  if (dummy === 0) buf[0] = 1;
+
+  return elapsed > 0
+    ? Math.min(buf.length, Math.round(n * target / elapsed))
+    : n;
+}
+
+// ── Internal: hash chain ──────────────────────────────────────────────────────
+
+function _genesisHash(seed) {
+  return bytesToHex(sha256(utf8ToBytes(`pulse:idle:genesis:${seed}`)));
+}
+
+function _chainStep(prevHex, sample) {
+  // Each node commits to: previous state, exact timestamp, CPU freq proxy, thermal noise
+  const input = `${prevHex}:${sample.ts}:${sample.meanMs}:${sample.variance}`;
+  return bytesToHex(sha256(utf8ToBytes(input)));
+}
+
+// ── Internal: thermal classification ─────────────────────────────────────────
+
+/**
+ * Classify the thermal transition from an ordered sequence of samples.
+ *
+ * The key discriminator is whether the variance follows a smooth exponential
+ * decay (genuine cooling) or drops abruptly in one interval (farm script pause).
+ *
+ * @param {ThermalSample[]} samples
+ * @returns {{ transition: string, coolingMonotonicity: number }}
+ */
+function _classifyThermal(samples) {
+  if (samples.length < 2) {
+    return { transition: 'unknown', coolingMonotonicity: 0 };
+  }
+
+  const variances = samples.map(s => s.variance);
+  const first     = variances[0];
+  const last      = variances[variances.length - 1];
+
+  // Cooling monotonicity: fraction of consecutive pairs where variance decreased
+  let decreasingPairs = 0;
+  for (let i = 1; i < variances.length; i++) {
+    if (variances[i] < variances[i - 1]) decreasingPairs++;
+  }
+  const coolingMonotonicity = +(decreasingPairs / (variances.length - 1)).toFixed(3);
+
+  // Step function detection: > STEP_FUNCTION_RATIO of total drop in first interval
+  if (variances.length >= 3) {
+    const firstDrop = Math.max(0, first - variances[1]);
+    const totalDrop = Math.max(0, first - last);
+    const isSignificantDrop = totalDrop > first * 0.15;      // must be >15% absolute drop
+    const stepRatio = totalDrop > 1e-9 ? firstDrop / totalDrop : 0;
+
+    if (isSignificantDrop && stepRatio > STEP_FUNCTION_RATIO) {
+      return { transition: 'step_function', coolingMonotonicity };
+    }
+  }
+
+  // Classify by absolute variance levels and direction
+  if (first < COLD_VARIANCE_THRESHOLD) {
+    return { transition: 'cold', coolingMonotonicity };
+  }
+  if (last > first * 1.10) {
+    return { transition: 'warming', coolingMonotonicity };
+  }
+  if (first > HOT_VARIANCE_THRESHOLD && last > HOT_VARIANCE_THRESHOLD * 0.85) {
+    return { transition: 'sustained_hot', coolingMonotonicity };
+  }
+  if ((first - last) / (first + 1e-9) > 0.12 && coolingMonotonicity >= 0.5) {
+    return { transition: 'hot_to_cold', coolingMonotonicity };
+  }
+
+  return { transition: 'cooling', coolingMonotonicity };
+}
+
+function _buildProof(chain, samples, idleDurationMs) {
+  const { transition, coolingMonotonicity } = _classifyThermal(samples);
+  return {
+    chain,
+    samples:             samples.length,
+    idleDurationMs,
+    thermalTransition:   transition,
+    coolingMonotonicity,
+    baselineVariance:    +(samples[0]?.variance ?? 0).toFixed(6),
+    finalVariance:       +(samples[samples.length - 1]?.variance ?? 0).toFixed(6),
+  };
+}
+
+// ── Internal: statistics ──────────────────────────────────────────────────────
+
+function _mean(arr, n) {
+  let s = 0;
+  for (let i = 0; i < n; i++) s += arr[i];
+  return s / n;
+}
+
+function _variance(arr, n, mean) {
+  let s = 0;
+  for (let i = 0; i < n; i++) s += (arr[i] - mean) ** 2;
+  return s / n;
+}
+
+// ── JSDoc types ───────────────────────────────────────────────────────────────
+
+/**
+ * @typedef {object} ThermalSample
+ * @property {number} ts        Unix ms timestamp of this measurement
+ * @property {number} meanMs    Mean DRAM iteration time — proxy for CPU clock frequency
+ * @property {number} variance  Variance of iteration times — proxy for thermal noise
+ */
+
+/**
+ * @typedef {object} IdleProof
+ * @property {string}  chain               Final SHA-256 hash in the measurement chain
+ * @property {number}  samples             Number of chain nodes (≥ 2 for a valid proof)
+ * @property {number}  idleDurationMs      Total elapsed idle time (ms)
+ * @property {string}  thermalTransition   'hot_to_cold'|'cold'|'cooling'|'warming'|'sustained_hot'|'step_function'|'unknown'
+ * @property {number}  coolingMonotonicity Fraction of sample pairs with decreasing variance (0–1)
+ * @property {number}  baselineVariance    Timing variance at idle start
+ * @property {number}  finalVariance       Timing variance at idle end
+ * @property {number}  capturedAt          Unix ms when proof was consumed (set by getProof)
+ */
+
+/**
+ * @typedef {object} IdleMonitor
+ * @property {() => IdleMonitor}       start          Register browser event listeners
+ * @property {() => IdleMonitor}       stop           Deregister listeners and cancel timers
+ * @property {() => IdleProof|null}    getProof       Consume pending proof (one-time)
+ * @property {() => string}            getState       Current state machine state
+ * @property {() => IdleMonitor}       declareIdle    Manually trigger idle (Node.js)
+ * @property {() => IdleMonitor}       declareActive  Manually trigger active (Node.js)
+ */

package/src/proof/engagementToken.js

@@ -0,0 +1,394 @@
+/**
+ * @svrnsec/pulse — Engagement Token
+ *
+ * A short-lived, physics-backed cryptographic token that proves a specific
+ * engagement event (click, view, share, purchase) originated from a real
+ * human on real hardware that had genuinely rested between interactions.
+ *
+ * This is the layer that defeats the "1,000 phones in a warehouse" attack.
+ * Each token proves:
+ *
+ *   1. Real hardware       DRAM refresh present, ENF grid signal detected
+ *   2. Genuine idle        Hash-chained thermal measurements spanning ≥ 45s
+ *   3. Physical cooling    Variance decay was smooth, not a step function
+ *   4. Fresh interaction   30-second TTL eliminates token brokers
+ *   5. Tamper-evident      HMAC-SHA256 over all fraud-relevant fields
+ *
+ * Token wire format (compact: base64url JSON, ~400 bytes)
+ * ────────────────────────────────────────────────────────
+ *   {
+ *     v:    2,                   protocol version
+ *     n:    "hex64",             nonce — 256-bit random
+ *     iat:  1234567890123,       issued-at Unix ms
+ *     exp:  1234567920123,       expires-at  (iat + 30s)
+ *     idle: {
+ *       chain: "hex64",          final hash of idle measurement chain
+ *       s:     3,                sample count (≥ 2 for a valid proof)
+ *       dMs:   180000,           idle duration ms
+ *       therm: "hot_to_cold",    thermal transition label
+ *       mono:  0.67,             cooling monotonicity (0–1)
+ *     },
+ *     hw: {
+ *       dram: "dram",            DRAM probe verdict
+ *       enf:  "grid_60hz",       ENF probe verdict
+ *       ent:  0.73,              normalized physics entropy score (0–1)
+ *     },
+ *     evt: {
+ *       t:   "click",            event type
+ *       ts:  1234567890123,      event Unix ms
+ *       mot: 0.82,               motor consistency (0–1)
+ *     },
+ *     sig: "hex64"               HMAC-SHA256 over all fraud-relevant fields
+ *   }
+ *
+ * HMAC input (pipe-delimited, all fields that matter for fraud)
+ * ─────────────────────────────────────────────────────────────
+ *   `v|n|iat|exp|idle.chain|idle.dMs|hw.ent|evt.t|evt.ts`
+ *
+ * Changing any signed field invalidates the token.  Unsigned fields
+ * (therm, mono, dram, enf) are advisory — they inform risk scoring but
+ * cannot be manipulated for credit fraud without breaking the HMAC.
+ */
+
+import { hmac }                     from '@noble/hashes/hmac';
+import { sha256 }                   from '@noble/hashes/sha256';
+import { bytesToHex,
+         utf8ToBytes,
+         randomBytes }              from '@noble/hashes/utils';
+
+// ── Constants ─────────────────────────────────────────────────────────────────
+
+const TOKEN_VERSION = 2;
+
+/** 30-second TTL: short enough to prevent token brokers (resellers of valid
+ *  tokens scraped from legitimate devices), long enough to survive one API
+ *  round-trip on a slow connection. */
+const TOKEN_TTL_MS  = 30_000;
+
+const NONCE_BYTES   = 32;   // 256-bit nonce → 64-char hex
+
+// ── createEngagementToken ─────────────────────────────────────────────────────
+
+/**
+ * Create a physics-backed engagement token.
+ *
+ * Attach the returned `compact` string to your API call:
+ *   `fetch('/api/action', { headers: { 'X-Pulse-Token': token.compact } })`
+ *
+ * @param {object}         opts
+ * @param {object}         opts.pulseResult      result object from pulse()
+ * @param {IdleProof|null} opts.idleProof         from idleMonitor.getProof()
+ * @param {object}         opts.interaction       { type, ts, motorConsistency }
+ * @param {string}         opts.secret            shared HMAC secret (min 16 chars)
+ * @param {object}         [opts._overrides]      for deterministic testing only
+ * @returns {EngagementToken}
+ */
+export function createEngagementToken(opts) {
+  const {
+    pulseResult  = {},
+    idleProof    = null,
+    interaction  = {},
+    secret,
+    _overrides   = {},
+  } = opts;
+
+  _assertSecret(secret);
+
+  const n   = _overrides.nonce    ?? bytesToHex(randomBytes(NONCE_BYTES));
+  const iat = _overrides.issuedAt ?? Date.now();
+  const exp = iat + TOKEN_TTL_MS;
+
+  // ── Extract hardware evidence from pulse result ───────────────────────────
+  const extended = pulseResult.extended ?? {};
+  const dram     = extended.dram?.verdict ?? pulseResult.dram?.verdict ?? 'unavailable';
+  const enf      = extended.enf?.verdict  ?? pulseResult.enf?.verdict  ?? 'unavailable';
+  const ent      = _extractEntropyScore(pulseResult);
+
+  // ENF deviation for population-level phase coherence test
+  const enfDev   = extended.enf?.enfDeviation
+    ?? pulseResult.enf?.enfDeviation
+    ?? null;
+
+  // ── Pack idle evidence ────────────────────────────────────────────────────
+  const idle = idleProof
+    ? {
+        chain: idleProof.chain,
+        s:     idleProof.samples,
+        dMs:   idleProof.idleDurationMs,
+        therm: idleProof.thermalTransition,
+        mono:  idleProof.coolingMonotonicity,
+      }
+    : null;
+
+  // ── Pack interaction evidence ─────────────────────────────────────────────
+  const evt = {
+    t:   interaction.type             ?? 'unknown',
+    ts:  interaction.ts               ?? iat,
+    mot: +(interaction.motorConsistency ?? 0).toFixed(3),
+  };
+
+  // ── Sign and seal ─────────────────────────────────────────────────────────
+  const hw      = { dram, enf, ent, ...(enfDev != null && { enfDev }) };
+  const unsigned = { v: TOKEN_VERSION, n, iat, exp, idle, hw, evt };
+  const sig      = _sign(unsigned, secret);
+  const token    = { ...unsigned, sig };
+
+  return {
+    token,
+    compact:   _encode(token),
+    expiresAt: exp,
+  };
+}
+
+// ── verifyEngagementToken ─────────────────────────────────────────────────────
+
+/**
+ * Verify an engagement token on the server.
+ *
+ * Call this in your API handler before crediting any engagement metric.
+ * Failed verification returns `{ valid: false, reason }` — never throws.
+ *
+ * @param {string|object}  tokenOrCompact  compact base64url string or parsed token
+ * @param {string}         secret          shared HMAC secret
+ * @param {object}         [opts]
+ * @param {Function}       [opts.checkNonce]  async (nonce: string) => boolean
+ *                         Must atomically consume the nonce (Redis DEL returning 1,
+ *                         DB transaction with SELECT FOR UPDATE, etc.)
+ * @param {Function}       [opts.now]  override Date.now for testing: () => number
+ * @returns {Promise<EngagementVerifyResult>}
+ */
+export async function verifyEngagementToken(tokenOrCompact, secret, opts = {}) {
+  _assertSecret(secret);
+
+  // ── Parse ─────────────────────────────────────────────────────────────────
+  let token;
+  try {
+    token = typeof tokenOrCompact === 'string'
+      ? _decode(tokenOrCompact)
+      : tokenOrCompact;
+  } catch {
+    return _reject('malformed_token');
+  }
+
+  const { v, n, iat, exp, idle, hw, evt, sig } = token ?? {};
+
+  // ── Structural integrity ──────────────────────────────────────────────────
+  if (v !== TOKEN_VERSION)                         return _reject('unsupported_version');
+  if (!n || !/^[0-9a-f]{64}$/i.test(n))           return _reject('invalid_nonce');
+  if (!Number.isFinite(iat) || !Number.isFinite(exp) || !sig) {
+    return _reject('missing_required_fields');
+  }
+
+  // ── Freshness ─────────────────────────────────────────────────────────────
+  const now = (opts.now ?? Date.now)();
+  if (now > exp)         return _reject('token_expired',      { expiredByMs: now - exp });
+  if (iat > now + 5_000) return _reject('token_from_future');
+
+  // ── Signature verification (timing-safe comparison) ───────────────────────
+  const expected = _sign(token, secret);
+  if (!_timingSafeEqual(expected, sig)) {
+    return _reject('invalid_signature');
+  }
+
+  // ── Nonce consumption (replay prevention) ─────────────────────────────────
+  if (typeof opts.checkNonce === 'function') {
+    let consumed;
+    try   { consumed = await opts.checkNonce(n); }
+    catch { return _reject('nonce_check_error'); }
+    if (!consumed) return _reject('nonce_replayed');
+  }
+
+  // ── Advisory analysis (non-blocking) ─────────────────────────────────────
+  const idleWarnings = idle ? _checkIdlePlausibility(idle) : ['no_idle_proof'];
+  const riskSignals  = _assessRisk(hw, idle, evt);
+
+  return {
+    valid:        true,
+    token,
+    idleWarnings,
+    riskSignals,
+    issuedAt:     iat,
+    expiresAt:    exp,
+  };
+}
+
+// ── Encode / decode ───────────────────────────────────────────────────────────
+
+/**
+ * Encode a token object to a compact base64url string.
+ * @param {object} token
+ * @returns {string}
+ */
+export function encodeToken(token) {
+  return _encode(token);
+}
+
+/**
+ * Decode a compact string without verifying the signature.
+ * Safe for logging/debugging; use verifyEngagementToken for security checks.
+ * @param {string} compact
+ * @returns {object}
+ */
+export function decodeToken(compact) {
+  return _decode(compact);
+}
+
+// ── Risk assessment ───────────────────────────────────────────────────────────
+
+/**
+ * Advisory risk signals: concerns that don't outright invalidate the token
+ * but should inform downstream risk decisions.
+ *
+ * Returned in the `riskSignals` array of a successful verify result.
+ * Each entry: `{ code: string, severity: 'high'|'medium'|'low' }`.
+ */
+function _assessRisk(hw, idle, evt) {
+  const signals = [];
+
+  // Hardware layer
+  if (hw?.dram === 'virtual')   signals.push({ code: 'DRAM_VIRTUAL',          severity: 'high'   });
+  if (hw?.dram === 'ambiguous') signals.push({ code: 'DRAM_AMBIGUOUS',        severity: 'medium' });
+  if (hw?.enf  === 'no_grid_signal') signals.push({ code: 'NO_ENF_GRID',      severity: 'medium' });
+  if (hw?.ent != null && hw.ent < 0.35) {
+    signals.push({ code: 'LOW_ENTROPY_SCORE', severity: 'high' });
+  }
+
+  // Idle proof layer
+  if (!idle) {
+    signals.push({ code: 'NO_IDLE_PROOF', severity: 'medium' });
+  } else {
+    if (idle.therm === 'step_function')   signals.push({ code: 'STEP_FUNCTION_THERMAL',   severity: 'high'   });
+    if (idle.therm === 'sustained_hot')   signals.push({ code: 'SUSTAINED_LOAD_PATTERN',  severity: 'high'   });
+    if (idle.mono  < 0.30 && idle.s >= 3) signals.push({ code: 'NON_MONOTONIC_COOLING',   severity: 'medium' });
+    if (idle.dMs   < 50_000)              signals.push({ code: 'MINIMAL_IDLE_DURATION',    severity: 'low'    });
+  }
+
+  // Interaction layer
+  if (evt?.mot != null && evt.mot < 0.25) {
+    signals.push({ code: 'POOR_MOTOR_CONSISTENCY', severity: 'medium' });
+  }
+
+  return signals;
+}
+
+function _checkIdlePlausibility(idle) {
+  const w = [];
+  if (!idle.chain || idle.chain.length !== 64) w.push('malformed_chain_hash');
+  if (idle.s < 2)                              w.push('insufficient_chain_samples');
+  if (idle.therm === 'step_function')          w.push('step_function_transition');
+  if (idle.mono < 0.30 && idle.s >= 3)         w.push('non_monotonic_cooling');
+  return w;
+}
+
+// ── HMAC ──────────────────────────────────────────────────────────────────────
+
+function _sign({ v, n, iat, exp, idle, hw, evt }, secret) {
+  // All fields an attacker might want to inflate/swap are in the signed body.
+  // Advisory fields (therm, mono, dram labels) are deliberately excluded —
+  // they're useful for risk scoring but not for access control.
+  const body = [
+    v,
+    n,
+    iat,
+    exp,
+    idle?.chain ?? 'null',
+    idle?.dMs   ?? 'null',
+    hw?.ent     ?? 'null',
+    evt?.t      ?? 'null',
+    evt?.ts     ?? 'null',
+  ].join('|');
+
+  const mac = hmac(sha256, utf8ToBytes(secret), utf8ToBytes(body));
+  return bytesToHex(mac);
+}
+
+/**
+ * Pure-JS timing-safe string comparison for hex strings.
+ * Operates on char codes — constant time for equal-length inputs.
+ * V8 does not optimize away XOR accumulation on Uint8 arithmetic.
+ */
+function _timingSafeEqual(a, b) {
+  if (typeof a !== 'string' || typeof b !== 'string') return false;
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) {
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return diff === 0;
+}
+
+// ── Encode / decode (base64url) ───────────────────────────────────────────────
+
+function _encode(token) {
+  const bytes = utf8ToBytes(JSON.stringify(token));
+  if (typeof Buffer !== 'undefined') {
+    return Buffer.from(bytes).toString('base64url');
+  }
+  // Browser: manual base64url encoding
+  return btoa(String.fromCharCode(...bytes))
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=/g,  '');
+}
+
+function _decode(compact) {
+  // Normalize base64url to standard base64 with padding
+  let b64 = compact.replace(/-/g, '+').replace(/_/g, '/');
+  while (b64.length % 4) b64 += '=';
+
+  let bytes;
+  if (typeof Buffer !== 'undefined') {
+    bytes = Buffer.from(b64, 'base64');
+  } else {
+    const str = atob(b64);
+    bytes = Uint8Array.from(str, c => c.charCodeAt(0));
+  }
+
+  return JSON.parse(new TextDecoder().decode(bytes));
+}
+
+// ── Misc helpers ──────────────────────────────────────────────────────────────
+
+function _reject(reason, meta = {}) {
+  return { valid: false, reason, ...meta };
+}
+
+function _assertSecret(secret) {
+  if (!secret || typeof secret !== 'string' || secret.length < 16) {
+    throw new Error(
+      '@svrnsec/pulse: engagement token secret must be ≥ 16 characters. ' +
+      'Generate one with: import { generateSecret } from "@svrnsec/pulse/challenge"'
+    );
+  }
+}
+
+function _extractEntropyScore(pulseResult) {
+  // Normalize jitter score (0–1) from wherever it lives in the result tree
+  const score =
+    pulseResult?.payload?.classification?.jitterScore ??
+    pulseResult?.classification?.jitterScore          ??
+    pulseResult?.jitterScore                          ??
+    null;
+  return score != null ? +Number(score).toFixed(3) : null;
+}
+
+// ── JSDoc types ───────────────────────────────────────────────────────────────
+
+/**
+ * @typedef {object} EngagementToken
+ * @property {object} token      full parsed token object
+ * @property {string} compact    base64url-encoded compact form (attach to API headers)
+ * @property {number} expiresAt  Unix ms expiry timestamp
+ */
+
+/**
+ * @typedef {object} EngagementVerifyResult
+ * @property {boolean}    valid          true if all checks passed
+ * @property {string}     [reason]       rejection reason code (when valid=false)
+ * @property {number}     [expiredByMs]  how many ms ago it expired (when reason=token_expired)
+ * @property {object}     [token]        parsed token (when valid=true)
+ * @property {string[]}   [idleWarnings] advisory idle-proof warnings
+ * @property {object[]}   [riskSignals]  non-fatal risk indicators with severity
+ * @property {number}     [issuedAt]     Unix ms issued-at
+ * @property {number}     [expiresAt]    Unix ms expiry
+ */