@svrnsec/pulse 0.7.0 → 0.9.0

package/src/analysis/authenticityAudit.js

@@ -1,393 +1,408 @@
-/**
- * @svrnsec/pulse — Authenticity Audit
- *
- * Produces a statistically rigorous, physics-backed estimate of what fraction
- * of a user cohort are real humans on real hardware.
- *
- * This is the "$44 billion question" — the number Twitter and Elon argued
- * about for months with no physics-layer evidence on either side.  Browser
- * fingerprinting can be spoofed.  Declared metrics can be gamed.  The thermal
- * state of a real device at 2 AM cannot.
- *
- * Method
- * ──────
- *   1. Cluster tokens by hardware signature
- *        ENF deviation bucket (±0.025 Hz → localizes to substation/building)
- *        × DRAM verdict (dram | virtual | ambiguous)
- *        × Thermal label (hot_to_cold | sustained_hot | step_function …)
- *        × 10-minute time bucket
- *      Authentic users scatter across all dimensions.
- *      A farm in one building, running the same script, on the same hardware
- *      generation collapses into one tight cluster.
- *
- *   2. Score each cluster with Population Entropy (5 statistical tests).
- *      Clusters with sybilScore > FARM_THRESHOLD are classified as bot farms.
- *
- *   3. Bootstrap a 95% confidence interval on the human-rate estimate.
- *      Each resample draws tokens with replacement and re-runs classification.
- *
- *   4. Fingerprint each bot cluster for cross-window tracking.
- *      Same ENF deviation + thermal pattern reappearing next hour = same farm.
- *
- * Output
- * ──────
- *   estimatedHumanPct   The headline number.  Treat anything below 90% as
- *                       a platform health emergency.
- *
- *   confidenceInterval  [lo, hi] at the requested confidence level.
- *                       Narrow CI = large cohort + clear signal.
- *                       Wide CI = small cohort or mixed evidence.
- *
- *   botClusters         Per-farm breakdown: size, sybilScore, ENF location,
- *                       thermal pattern, dominant attack signal.
- *
- *   grade               CLEAN / LOW_FRAUD / MODERATE_FRAUD / HIGH_FRAUD
- *
- * Typical values
- * ──────────────
- *   Organic product feed, 10k tokens over 1 hour  → humanPct ≈ 92–97%
- *   Incentivised engagement campaign               → humanPct ≈ 55–75%
- *   Coordinated click farm attack                 → humanPct ≈ 8–35%
- */
-
-import { analysePopulation } from './populationEntropy.js';
-
-// ── Thresholds ─────────────────────────────────────────────────────────────────
-
-/** Clusters scoring above this are classified as bot farms. */
-const FARM_THRESHOLD      = 65;
-
-/** Minimum tokens in a cluster before we run population analysis on it.
- *  Smaller clusters are treated as noise and counted as authentic. */
-const MIN_CLUSTER_SIZE    = 5;
-
-/** ENF deviation bucket width in Hz.  ±0.025 Hz localizes devices to the same
- *  substation — close enough to imply the same building. */
-const ENF_BUCKET_HZ       = 0.05;
-
-/** Time bucket width.  10-minute buckets catch batch-dispatch patterns
- *  without splitting a legitimate organic traffic surge. */
-const TIME_BUCKET_MS      = 10 * 60 * 1000;
-
-/** Bootstrap iterations for confidence interval estimation. */
-const BOOTSTRAP_ITERATIONS = 500;
-
-// ── Grade thresholds ──────────────────────────────────────────────────────────
-
-const GRADES = [
-  { min: 90, grade: 'CLEAN',           label: 'Authentic cohort',           color: 'bgreen'  },
-  { min: 75, grade: 'LOW_FRAUD',       label: 'Elevated fraud signal',      color: 'byellow' },
-  { min: 50, grade: 'MODERATE_FRAUD',  label: 'Significant bot presence',   color: 'byellow' },
-  { min:  0, grade: 'HIGH_FRAUD',      label: 'Platform health emergency',  color: 'bred'    },
-];
-
-// ── authenticityAudit ─────────────────────────────────────────────────────────
-
-/**
- * Run a full authenticity audit on a cohort of decoded engagement tokens.
- *
- * @param {object[]}  tokens                  Decoded engagement token objects
- *                                            (from decodeToken / verifyEngagementToken)
- * @param {object}    [opts]
- * @param {number}    [opts.windowMs]          Analysis window in ms (default: all tokens)
- * @param {number}    [opts.minClusterSize]    Min cluster size for farm analysis (default: 5)
- * @param {number}    [opts.farmThreshold]     sybilScore cutoff for farm classification (default: 65)
- * @param {number}    [opts.confidenceLevel]   Bootstrap CI level, e.g. 0.95 (default: 0.95)
- * @param {number}    [opts.bootstrapIter]     Bootstrap iterations (default: 500)
- * @returns {AuthenticityReport}
- */
-export function authenticityAudit(tokens, opts = {}) {
-  const {
-    minClusterSize  = MIN_CLUSTER_SIZE,
-    farmThreshold   = FARM_THRESHOLD,
-    confidenceLevel = 0.95,
-    bootstrapIter   = BOOTSTRAP_ITERATIONS,
-  } = opts;
-
-  if (!Array.isArray(tokens) || tokens.length === 0) {
-    return _emptyReport();
-  }
-
-  // ── 1. Cluster ─────────────────────────────────────────────────────────────
-  const clusterMap = _clusterTokens(tokens);
-
-  // ── 2. Score each cluster ──────────────────────────────────────────────────
-  const botClusterIds  = new Set();
-  const clusterResults = [];
-
-  for (const [key, clusterTokens] of clusterMap) {
-    if (clusterTokens.length < minClusterSize) continue;
-
-    const pop    = analysePopulation(clusterTokens);
-    const isFarm = pop.sybilScore >= farmThreshold;
-
-    const fingerprint = _fingerprint(key, clusterTokens, pop);
-
-    clusterResults.push({
-      id:          fingerprint.id,
-      size:        clusterTokens.length,
-      sybilScore:  pop.sybilScore,
-      authentic:   !isFarm,
-      signature:   fingerprint.signature,
-      topSignals:  _topSignals(pop),
-      flags:       pop.flags,
-    });
-
-    if (isFarm) {
-      for (const t of clusterTokens) botClusterIds.add(t);
-    }
-  }
-
-  // ── 3. Count fraudulent tokens ─────────────────────────────────────────────
-  // Tokens in clusters too small to analyse are given benefit of the doubt.
-  const fraudCount     = botClusterIds.size;
-  const authenticCount = tokens.length - fraudCount;
-  const rawHumanPct    = (authenticCount / tokens.length) * 100;
-
-  // ── 4. Bootstrap confidence interval ──────────────────────────────────────
-  // We bootstrap the "is this token authentic?" binary labels.
-  const labels = tokens.map(t => (botClusterIds.has(t) ? 0 : 1));
-  const ci     = _bootstrapCI(labels, confidenceLevel, bootstrapIter);
-
-  // ── 5. Grade and summarise ─────────────────────────────────────────────────
-  const gradeEntry   = GRADES.find(g => rawHumanPct >= g.min) ?? GRADES[GRADES.length - 1];
-  const botClusters  = clusterResults.filter(c => !c.authentic)
-    .sort((a, b) => b.sybilScore - a.sybilScore);
-  const authClusters = clusterResults.filter(c =>  c.authentic);
-
-  return {
-    // ── Headline ──
-    cohortSize:           tokens.length,
-    estimatedHumanPct:    +rawHumanPct.toFixed(1),
-    confidenceInterval:   ci,
-    confidenceLevel,
-
-    // ── Cluster breakdown ──
-    clusterCount:         clusterResults.length,
-    botClusterCount:      botClusters.length,
-    authenticClusterCount: authClusters.length,
-
-    // ── Token counts ──
-    authenticTokenCount:  authenticCount,
-    fraudulentTokenCount: fraudCount,
-
-    // ── Farm detail ──
-    botClusters,
-
-    // ── Grade ──
-    grade:          gradeEntry.grade,
-    label:          gradeEntry.label,
-    color:          gradeEntry.color,
-    recommendation: _recommendation(gradeEntry.grade, botClusters),
-  };
-}
-
-// ── Clustering ────────────────────────────────────────────────────────────────
-
-/**
- * Bucket tokens into hardware-signature clusters.
- *
- * Cluster key = ENF deviation bucket × DRAM verdict × thermal label × time bucket
- *
- * This collapses bot farms (same building, same hardware, same script, same
- * time window) into single clusters while leaving organic traffic scattered.
- *
- * @param {object[]} tokens
- * @returns {Map<string, object[]>}
- */
-function _clusterTokens(tokens) {
-  const map = new Map();
-
-  for (const token of tokens) {
-    const key = _clusterKey(token);
-    if (!map.has(key)) map.set(key, []);
-    map.get(key).push(token);
-  }
-
-  return map;
-}
-
-function _clusterKey(token) {
-  const hw  = token.hw ?? {};
-  const iat = token.iat ?? 0;
-
-  // ENF deviation → nearest bucket (null/undefined → 'no_enf')
-  // ±0.025 Hz resolution localizes devices to the same building/substation.
-  const enfBucket = hw.enfDev != null
-    ? `e${Math.round(hw.enfDev / ENF_BUCKET_HZ)}`
-    : 'no_enf';
-
-  // DRAM verdict string — proxy for hardware generation
-  const dram = hw.dram ?? 'unknown';
-
-  // 10-minute time bucket — captures batch dispatch without splitting organic traffic
-  const tBucket = Math.floor(iat / TIME_BUCKET_MS);
-
-  // Note: thermal label is intentionally NOT part of the key.
-  // Clustering by thermal label would make testThermalDiversity a tautology
-  // (every cluster would have zero diversity by construction).
-  // Thermal diversity is left as a within-cluster discriminator — farms that
-  // co-locate in the same ENF + DRAM + time bucket will still show sustained_hot
-  // homogeneity; organic users in the same bucket will show hot_to_cold / cooling mix.
-  return `${enfBucket}:${dram}:${tBucket}`;
-}
-
-// ── Bootstrap CI ──────────────────────────────────────────────────────────────
-
-/**
- * Non-parametric bootstrap confidence interval on the mean of a 0/1 vector.
- *
- * @param {number[]} values   0 (fraudulent) or 1 (authentic) per token
- * @param {number}   level    Confidence level, e.g. 0.95
- * @param {number}   iters    Bootstrap iterations
- * @returns {[number, number]} [lo, hi] as percentages (0–100)
- */
-function _bootstrapCI(values, level, iters) {
-  const n = values.length;
-  if (n === 0) return [0, 0];
-
-  const means = new Float64Array(iters);
-
-  for (let i = 0; i < iters; i++) {
-    let sum = 0;
-    for (let j = 0; j < n; j++) {
-      sum += values[(Math.random() * n) | 0];
-    }
-    means[i] = (sum / n) * 100;
-  }
-
-  means.sort();
-
-  const alpha = 1 - level;
-  const lo    = means[(alpha / 2 * iters) | 0];
-  const hi    = means[((1 - alpha / 2) * iters) | 0];
-
-  return [+lo.toFixed(1), +hi.toFixed(1)];
-}
-
-// ── Cluster fingerprinting ────────────────────────────────────────────────────
-
-/**
- * Produce a stable fingerprint for a bot cluster so the same farm can be
- * recognised across multiple analysis windows.
- *
- * Fingerprint components that are stable across time:
- *   - ENF deviation (tied to physical location / substation)
- *   - DRAM verdict  (tied to hardware generation)
- *   - Thermal label (tied to operational pattern)
- *
- * @param {string}   key
- * @param {object[]} tokens
- * @param {object}   pop  analysePopulation result
- * @returns {{ id: string, signature: object }}
- */
-function _fingerprint(key, tokens, pop) {
-  const sample = tokens[0] ?? {};
-  const hw     = sample.hw   ?? {};
-  const idle   = sample.idle ?? {};
-
-  // Mean ENF deviation across cluster (stable for co-located devices)
-  const enfDevs = tokens.map(t => t.hw?.enfDev).filter(v => v != null);
-  const meanEnfDev = enfDevs.length
-    ? +(enfDevs.reduce((s, v) => s + v, 0) / enfDevs.length).toFixed(4)
-    : null;
-
-  // Mean idle duration (reveals script-sleep cadence)
-  const idleDurations = tokens.map(t => t.idle?.dMs).filter(v => v != null);
-  const meanIdleMs = idleDurations.length
-    ? Math.round(idleDurations.reduce((s, v) => s + v, 0) / idleDurations.length)
-    : null;
-
-  const signature = {
-    enfRegion:    hw.enf        ?? 'unknown',
-    dramVerdict:  hw.dram       ?? 'unknown',
-    thermalLabel: idle.therm    ?? 'unknown',
-    meanEnfDev,
-    meanIdleMs,
-  };
-
-  // Stable ID: hash-like hex derived from the signature (deterministic, not crypto)
-  const sigStr = JSON.stringify(signature);
-  const id     = 'farm_' + _djb2(sigStr).toString(16).slice(0, 8);
-
-  return { id, signature };
-}
-
-// ── Helpers ───────────────────────────────────────────────────────────────────
-
-function _topSignals(pop) {
-  return Object.entries(pop.tests ?? {})
-    .map(([name, result]) => ({ name, score: result.score ?? 0 }))
-    .sort((a, b) => b.score - a.score)
-    .slice(0, 2)
-    .map(s => s.name);
-}
-
-function _recommendation(grade, botClusters) {
-  if (grade === 'CLEAN') {
-    return 'Cohort appears authentic. No action required.';
-  }
-  if (grade === 'LOW_FRAUD') {
-    return `${botClusters.length} suspicious cluster(s) detected. Monitor and consider manual review.`;
-  }
-  if (grade === 'MODERATE_FRAUD') {
-    return `${botClusters.length} bot farm cluster(s) identified. Block tokens from flagged clusters and investigate upstream traffic source.`;
-  }
-  return (
-    `CRITICAL: ${botClusters.length} bot farm cluster(s) account for a majority of traffic. ` +
-    `Suspend engagement credit for this cohort and audit the traffic acquisition channel.`
-  );
-}
-
-function _emptyReport() {
-  return {
-    cohortSize:            0,
-    estimatedHumanPct:     null,
-    confidenceInterval:    null,
-    confidenceLevel:       0.95,
-    clusterCount:          0,
-    botClusterCount:       0,
-    authenticClusterCount: 0,
-    authenticTokenCount:   0,
-    fraudulentTokenCount:  0,
-    botClusters:           [],
-    grade:                 'CLEAN',
-    label:                 'No data',
-    color:                 'bgreen',
-    recommendation:        'No tokens provided.',
-  };
-}
-
-/**
- * DJB2 hash — non-cryptographic, deterministic, produces stable cluster IDs.
- * @param {string} str
- * @returns {number}
- */
-function _djb2(str) {
-  let h = 5381;
-  for (let i = 0; i < str.length; i++) {
-    h = ((h << 5) + h) ^ str.charCodeAt(i);
-    h = h >>> 0; // keep unsigned 32-bit
-  }
-  return h;
-}
-
-// ── JSDoc types ───────────────────────────────────────────────────────────────
-
-/**
- * @typedef {object} AuthenticityReport
- * @property {number}         cohortSize              Total tokens analysed
- * @property {number|null}    estimatedHumanPct       Estimated % of real humans (0–100)
- * @property {[number,number]|null} confidenceInterval [lo, hi] at confidenceLevel
- * @property {number}         confidenceLevel         Bootstrap CI level (e.g. 0.95)
- * @property {number}         clusterCount            Total hardware clusters identified
- * @property {number}         botClusterCount         Clusters classified as bot farms
- * @property {number}         authenticClusterCount   Clusters classified as authentic
- * @property {number}         authenticTokenCount     Tokens NOT in bot farm clusters
- * @property {number}         fraudulentTokenCount    Tokens IN bot farm clusters
- * @property {object[]}       botClusters             Per-farm breakdown (sorted by sybilScore desc)
- * @property {string}         grade                   CLEAN|LOW_FRAUD|MODERATE_FRAUD|HIGH_FRAUD
- * @property {string}         label                   Human-readable grade label
- * @property {string}         color                   ANSI color hint for terminal rendering
- * @property {string}         recommendation          Actionable guidance string
- */
+/**
+ * @svrnsec/pulse — Authenticity Audit
+ *
+ * Produces a statistically rigorous, physics-backed estimate of what fraction
+ * of a user cohort are real humans on real hardware.
+ *
+ * This is the "$44 billion question" — the number Twitter and Elon argued
+ * about for months with no physics-layer evidence on either side.  Browser
+ * fingerprinting can be spoofed.  Declared metrics can be gamed.  The thermal
+ * state of a real device at 2 AM cannot.
+ *
+ * Method
+ * ──────
+ *   1. Cluster tokens by hardware signature
+ *        ENF deviation bucket (±0.025 Hz → localizes to substation/building)
+ *        × DRAM verdict (dram | virtual | ambiguous)
+ *        × Thermal label (hot_to_cold | sustained_hot | step_function …)
+ *        × 10-minute time bucket
+ *      Authentic users scatter across all dimensions.
+ *      A farm in one building, running the same script, on the same hardware
+ *      generation collapses into one tight cluster.
+ *
+ *   2. Score each cluster with Population Entropy (5 statistical tests).
+ *      Clusters with sybilScore > FARM_THRESHOLD are classified as bot farms.
+ *
+ *   3. Bootstrap a 95% confidence interval on the human-rate estimate.
+ *      Each resample draws tokens with replacement and re-runs classification.
+ *
+ *   4. Fingerprint each bot cluster for cross-window tracking.
+ *      Same ENF deviation + thermal pattern reappearing next hour = same farm.
+ *
+ * Output
+ * ──────
+ *   estimatedHumanPct   The headline number.  Treat anything below 90% as
+ *                       a platform health emergency.
+ *
+ *   confidenceInterval  [lo, hi] at the requested confidence level.
+ *                       Narrow CI = large cohort + clear signal.
+ *                       Wide CI = small cohort or mixed evidence.
+ *
+ *   botClusters         Per-farm breakdown: size, sybilScore, ENF location,
+ *                       thermal pattern, dominant attack signal.
+ *
+ *   grade               CLEAN / LOW_FRAUD / MODERATE_FRAUD / HIGH_FRAUD
+ *
+ * Typical values
+ * ──────────────
+ *   Organic product feed, 10k tokens over 1 hour  → humanPct ≈ 92–97%
+ *   Incentivised engagement campaign               → humanPct ≈ 55–75%
+ *   Coordinated click farm attack                 → humanPct ≈ 8–35%
+ */
+
+import { analysePopulation } from './populationEntropy.js';
+
+// ── Thresholds ─────────────────────────────────────────────────────────────────
+
+/** Clusters scoring above this are classified as bot farms. */
+const FARM_THRESHOLD      = 65;
+
+/** Minimum tokens in a cluster before we run population analysis on it.
+ *  Smaller clusters are treated as noise and counted as authentic. */
+const MIN_CLUSTER_SIZE    = 5;
+
+/** ENF deviation bucket width in Hz.  ±0.025 Hz localizes devices to the same
+ *  substation — close enough to imply the same building. */
+const ENF_BUCKET_HZ       = 0.05;
+
+/** Time bucket width.  10-minute buckets catch batch-dispatch patterns
+ *  without splitting a legitimate organic traffic surge. */
+const TIME_BUCKET_MS      = 10 * 60 * 1000;
+
+/** Bootstrap iterations for confidence interval estimation. */
+const BOOTSTRAP_ITERATIONS = 500;
+
+// ── Grade thresholds ──────────────────────────────────────────────────────────
+
+const GRADES = [
+  { min: 90, grade: 'CLEAN',           label: 'Authentic cohort',           color: 'bgreen'  },
+  { min: 75, grade: 'LOW_FRAUD',       label: 'Elevated fraud signal',      color: 'byellow' },
+  { min: 50, grade: 'MODERATE_FRAUD',  label: 'Significant bot presence',   color: 'byellow' },
+  { min:  0, grade: 'HIGH_FRAUD',      label: 'Platform health emergency',  color: 'bred'    },
+];
+
+// ── authenticityAudit ─────────────────────────────────────────────────────────
+
+/**
+ * Run a full authenticity audit on a cohort of decoded engagement tokens.
+ *
+ * @param {object[]}  tokens                  Decoded engagement token objects
+ *                                            (from decodeToken / verifyEngagementToken)
+ * @param {object}    [opts]
+ * @param {number}    [opts.windowMs]          Analysis window in ms (default: all tokens)
+ * @param {number}    [opts.minClusterSize]    Min cluster size for farm analysis (default: 5)
+ * @param {number}    [opts.farmThreshold]     sybilScore cutoff for farm classification (default: 65)
+ * @param {number}    [opts.confidenceLevel]   Bootstrap CI level, e.g. 0.95 (default: 0.95)
+ * @param {number}    [opts.bootstrapIter]     Bootstrap iterations (default: 500)
+ * @returns {AuthenticityReport}
+ */
+export function authenticityAudit(tokens, opts = {}) {
+  const {
+    minClusterSize  = MIN_CLUSTER_SIZE,
+    farmThreshold   = FARM_THRESHOLD,
+    confidenceLevel = 0.95,
+    bootstrapIter   = BOOTSTRAP_ITERATIONS,
+  } = opts;
+
+  if (!Array.isArray(tokens) || tokens.length === 0) {
+    return _emptyReport();
+  }
+
+  // ── 1. Cluster ─────────────────────────────────────────────────────────────
+  const clusterMap = _clusterTokens(tokens);
+
+  // ── 2. Score each cluster ──────────────────────────────────────────────────
+  const botClusterIds  = new Set();
+  const clusterResults = [];
+
+  for (const [key, clusterTokens] of clusterMap) {
+    if (clusterTokens.length < minClusterSize) continue;
+
+    const pop    = analysePopulation(clusterTokens);
+    const isFarm = pop.sybilScore >= farmThreshold;
+
+    const fingerprint = _fingerprint(key, clusterTokens, pop);
+
+    clusterResults.push({
+      id:          fingerprint.id,
+      size:        clusterTokens.length,
+      sybilScore:  pop.sybilScore,
+      authentic:   !isFarm,
+      signature:   fingerprint.signature,
+      topSignals:  _topSignals(pop),
+      flags:       pop.flags,
+    });
+
+    if (isFarm) {
+      for (const t of clusterTokens) botClusterIds.add(t);
+    }
+  }
+
+  // ── 3. Count fraudulent tokens ─────────────────────────────────────────────
+  // Tokens in clusters too small to analyse are given benefit of the doubt.
+  const fraudCount     = botClusterIds.size;
+  const authenticCount = tokens.length - fraudCount;
+  const rawHumanPct    = (authenticCount / tokens.length) * 100;
+
+  // ── 4. Bootstrap confidence interval ──────────────────────────────────────
+  // We bootstrap the "is this token authentic?" binary labels.
+  const labels = tokens.map(t => (botClusterIds.has(t) ? 0 : 1));
+  const ci     = _bootstrapCI(labels, confidenceLevel, bootstrapIter);
+
+  // ── 5. Grade and summarise ─────────────────────────────────────────────────
+  const gradeEntry   = GRADES.find(g => rawHumanPct >= g.min) ?? GRADES[GRADES.length - 1];
+  const botClusters  = clusterResults.filter(c => !c.authentic)
+    .sort((a, b) => b.sybilScore - a.sybilScore);
+  const authClusters = clusterResults.filter(c =>  c.authentic);
+
+  return {
+    // ── Headline ──
+    cohortSize:           tokens.length,
+    estimatedHumanPct:    +rawHumanPct.toFixed(1),
+    confidenceInterval:   ci,
+    confidenceLevel,
+
+    // ── Cluster breakdown ──
+    clusterCount:         clusterResults.length,
+    botClusterCount:      botClusters.length,
+    authenticClusterCount: authClusters.length,
+
+    // ── Token counts ──
+    authenticTokenCount:  authenticCount,
+    fraudulentTokenCount: fraudCount,
+
+    // ── Farm detail ──
+    botClusters,
+
+    // ── Grade ──
+    grade:          gradeEntry.grade,
+    label:          gradeEntry.label,
+    color:          gradeEntry.color,
+    recommendation: _recommendation(gradeEntry.grade, botClusters),
+  };
+}
+
+// ── Clustering ────────────────────────────────────────────────────────────────
+
+/**
+ * Bucket tokens into hardware-signature clusters.
+ *
+ * Cluster key = ENF deviation bucket × DRAM verdict × thermal label × time bucket
+ *
+ * This collapses bot farms (same building, same hardware, same script, same
+ * time window) into single clusters while leaving organic traffic scattered.
+ *
+ * @param {object[]} tokens
+ * @returns {Map<string, object[]>}
+ */
+function _clusterTokens(tokens) {
+  const map = new Map();
+
+  for (const token of tokens) {
+    const key = _clusterKey(token);
+    if (!map.has(key)) map.set(key, []);
+    map.get(key).push(token);
+  }
+
+  return map;
+}
+
+function _clusterKey(token) {
+  const hw  = token.hw ?? {};
+  const iat = token.iat ?? 0;
+
+  // ENF deviation → nearest bucket (null/undefined → 'no_enf')
+  // ±0.025 Hz resolution localizes devices to the same building/substation.
+  const enfBucket = hw.enfDev != null
+    ? `e${Math.round(hw.enfDev / ENF_BUCKET_HZ)}`
+    : 'no_enf';
+
+  // DRAM verdict string — proxy for hardware generation
+  const dram = hw.dram ?? 'unknown';
+
+  // 10-minute time bucket — captures batch dispatch without splitting organic traffic
+  const tBucket = Math.floor(iat / TIME_BUCKET_MS);
+
+  // Note: thermal label is intentionally NOT part of the key.
+  // Clustering by thermal label would make testThermalDiversity a tautology
+  // (every cluster would have zero diversity by construction).
+  // Thermal diversity is left as a within-cluster discriminator — farms that
+  // co-locate in the same ENF + DRAM + time bucket will still show sustained_hot
+  // homogeneity; organic users in the same bucket will show hot_to_cold / cooling mix.
+  return `${enfBucket}:${dram}:${tBucket}`;
+}
+
+// ── Bootstrap CI ──────────────────────────────────────────────────────────────
+
+/**
+ * Splitmix32 deterministic PRNG seeded from input data.
+ * Replaces Math.random() for reproducible bootstrap results.
+ */
+function _splitmix32(seed) {
+  return function() {
+    seed |= 0; seed = seed + 0x9e3779b9 | 0;
+    let t = seed ^ seed >>> 16; t = Math.imul(t, 0x21f0aaad);
+    t = t ^ t >>> 15; t = Math.imul(t, 0x735a2d97);
+    return ((t = t ^ t >>> 15) >>> 0) / 4294967296;
+  };
+}
+
+/**
+ * Non-parametric bootstrap confidence interval on the mean of a 0/1 vector.
+ *
+ * @param {number[]} values   0 (fraudulent) or 1 (authentic) per token
+ * @param {number}   level    Confidence level, e.g. 0.95
+ * @param {number}   iters    Bootstrap iterations
+ * @returns {[number, number]} [lo, hi] as percentages (0–100)
+ */
+function _bootstrapCI(values, level, iters) {
+  const n = values.length;
+  if (n === 0) return [0, 0];
+
+  const seed = values.reduce((s, v) => (s * 31 + (v * 1000 | 0)) | 0, 0);
+  const rand = _splitmix32(seed);
+  const means = new Float64Array(iters);
+
+  for (let i = 0; i < iters; i++) {
+    let sum = 0;
+    for (let j = 0; j < n; j++) {
+      sum += values[(rand() * n) | 0];
+    }
+    means[i] = (sum / n) * 100;
+  }
+
+  means.sort();
+
+  const alpha = 1 - level;
+  const lo    = means[(alpha / 2 * iters) | 0];
+  const hi    = means[((1 - alpha / 2) * iters) | 0];
+
+  return [+lo.toFixed(1), +hi.toFixed(1)];
+}
+
+// ── Cluster fingerprinting ────────────────────────────────────────────────────
+
+/**
+ * Produce a stable fingerprint for a bot cluster so the same farm can be
+ * recognised across multiple analysis windows.
+ *
+ * Fingerprint components that are stable across time:
+ *   - ENF deviation (tied to physical location / substation)
+ *   - DRAM verdict  (tied to hardware generation)
+ *   - Thermal label (tied to operational pattern)
+ *
+ * @param {string}   key
+ * @param {object[]} tokens
+ * @param {object}   pop  analysePopulation result
+ * @returns {{ id: string, signature: object }}
+ */
+function _fingerprint(key, tokens, pop) {
+  const sample = tokens[0] ?? {};
+  const hw     = sample.hw   ?? {};
+  const idle   = sample.idle ?? {};
+
+  // Mean ENF deviation across cluster (stable for co-located devices)
+  const enfDevs = tokens.map(t => t.hw?.enfDev).filter(v => v != null);
+  const meanEnfDev = enfDevs.length
+    ? +(enfDevs.reduce((s, v) => s + v, 0) / enfDevs.length).toFixed(4)
+    : null;
+
+  // Mean idle duration (reveals script-sleep cadence)
+  const idleDurations = tokens.map(t => t.idle?.dMs).filter(v => v != null);
+  const meanIdleMs = idleDurations.length
+    ? Math.round(idleDurations.reduce((s, v) => s + v, 0) / idleDurations.length)
+    : null;
+
+  const signature = {
+    enfRegion:    hw.enf        ?? 'unknown',
+    dramVerdict:  hw.dram       ?? 'unknown',
+    thermalLabel: idle.therm    ?? 'unknown',
+    meanEnfDev,
+    meanIdleMs,
+  };
+
+  // Stable ID: hash-like hex derived from the signature (deterministic, not crypto)
+  const sigStr = JSON.stringify(signature);
+  const id     = 'farm_' + _djb2(sigStr).toString(16).slice(0, 8);
+
+  return { id, signature };
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function _topSignals(pop) {
+  return Object.entries(pop.tests ?? {})
+    .map(([name, result]) => ({ name, score: result.score ?? 0 }))
+    .sort((a, b) => b.score - a.score)
+    .slice(0, 2)
+    .map(s => s.name);
+}
+
+function _recommendation(grade, botClusters) {
+  if (grade === 'CLEAN') {
+    return 'Cohort appears authentic. No action required.';
+  }
+  if (grade === 'LOW_FRAUD') {
+    return `${botClusters.length} suspicious cluster(s) detected. Monitor and consider manual review.`;
+  }
+  if (grade === 'MODERATE_FRAUD') {
+    return `${botClusters.length} bot farm cluster(s) identified. Block tokens from flagged clusters and investigate upstream traffic source.`;
+  }
+  return (
+    `CRITICAL: ${botClusters.length} bot farm cluster(s) account for a majority of traffic. ` +
+    `Suspend engagement credit for this cohort and audit the traffic acquisition channel.`
+  );
+}
+
+function _emptyReport() {
+  return {
+    cohortSize:            0,
+    estimatedHumanPct:     null,
+    confidenceInterval:    null,
+    confidenceLevel:       0.95,
+    clusterCount:          0,
+    botClusterCount:       0,
+    authenticClusterCount: 0,
+    authenticTokenCount:   0,
+    fraudulentTokenCount:  0,
+    botClusters:           [],
+    grade:                 'CLEAN',
+    label:                 'No data',
+    color:                 'bgreen',
+    recommendation:        'No tokens provided.',
+  };
+}
+
+/**
+ * DJB2 hash — non-cryptographic, deterministic, produces stable cluster IDs.
+ * @param {string} str
+ * @returns {number}
+ */
+function _djb2(str) {
+  let h = 5381;
+  for (let i = 0; i < str.length; i++) {
+    h = ((h << 5) + h) ^ str.charCodeAt(i);
+    h = h >>> 0; // keep unsigned 32-bit
+  }
+  return h;
+}
+
+// ── JSDoc types ───────────────────────────────────────────────────────────────
+
+/**
+ * @typedef {object} AuthenticityReport
+ * @property {number}         cohortSize              Total tokens analysed
+ * @property {number|null}    estimatedHumanPct       Estimated % of real humans (0–100)
+ * @property {[number,number]|null} confidenceInterval [lo, hi] at confidenceLevel
+ * @property {number}         confidenceLevel         Bootstrap CI level (e.g. 0.95)
+ * @property {number}         clusterCount            Total hardware clusters identified
+ * @property {number}         botClusterCount         Clusters classified as bot farms
+ * @property {number}         authenticClusterCount   Clusters classified as authentic
+ * @property {number}         authenticTokenCount     Tokens NOT in bot farm clusters
+ * @property {number}         fraudulentTokenCount    Tokens IN bot farm clusters
+ * @property {object[]}       botClusters             Per-farm breakdown (sorted by sybilScore desc)
+ * @property {string}         grade                   CLEAN|LOW_FRAUD|MODERATE_FRAUD|HIGH_FRAUD
+ * @property {string}         label                   Human-readable grade label
+ * @property {string}         color                   ANSI color hint for terminal rendering
+ * @property {string}         recommendation          Actionable guidance string
+ */