@svrnsec/pulse 0.3.0 → 0.4.0

package/index.d.ts

@@ -586,3 +586,261 @@ export interface SignatureComparison {
   profileMatch: boolean;
   providerMatch: boolean;
 }
+
+// =============================================================================
+// Extended Signal Layer Types
+// =============================================================================
+
+// ── ENF (Electrical Network Frequency) ───────────────────────────────────────
+
+export interface EnfResult {
+  enfAvailable: boolean;
+  ripplePresent: boolean;
+  gridFrequency: 50 | 60 | null;
+  gridRegion: 'americas' | 'emea_apac' | 'unknown';
+  ripplePower: number;
+  snr50hz: number;
+  snr60hz: number;
+  enfDeviation: number | null;
+  sampleRateHz: number;
+  resolutionUs: number;
+  verdict: 'grid_60hz' | 'grid_50hz' | 'no_grid_signal' | 'grid_detected_region_unknown' | 'unavailable';
+  isVmIndicator: boolean;
+  temporalAnchor: {
+    nominalHz: number;
+    measuredRippleHz: number;
+    capturedAt: number;
+    gridHz: number;
+  } | null;
+  reason?: string;
+}
+
+export declare function collectEnfTimings(opts?: { iterations?: number }): Promise<EnfResult>;
+
+// ── WebGPU Thermal Variance ───────────────────────────────────────────────────
+
+export interface GpuEntropyResult {
+  gpuPresent: boolean;
+  isSoftware: boolean;
+  vendorString: string | null;
+  dispatchCV: number;
+  thermalGrowth: number;
+  verdict: 'real_gpu' | 'software_renderer' | 'no_webgpu' | 'ambiguous';
+}
+
+export declare function collectGpuEntropy(opts?: object): Promise<GpuEntropyResult>;
+
+// ── DRAM Refresh Cycle ────────────────────────────────────────────────────────
+
+export interface DramResult {
+  timings: number[];
+  refreshPeriodMs: number | null;
+  refreshPresent: boolean;
+  peakLag: number;
+  peakPower: number;
+  verdict: 'dram' | 'virtual' | 'ambiguous';
+}
+
+export declare function collectDramTimings(opts?: { iterations?: number; bufferMb?: number }): DramResult;
+
+// ── LLM / AI Agent Behavioral Fingerprint ─────────────────────────────────────
+
+export interface LlmResult {
+  aiConf: number;
+  thinkTimePattern: 'llm_latency_peak' | 'human_pareto' | 'unknown';
+  correctionRate: number;
+  rhythmicity: number;
+  pauseDistribution: 'uniform' | 'pareto' | 'unknown';
+  verdict: 'ai_agent' | 'human' | 'insufficient_data';
+  matchedModel: string | null;
+}
+
+export declare function detectLlmAgent(bioSnapshot: object): LlmResult;
+
+// ── SAB Microsecond Timer ─────────────────────────────────────────────────────
+
+export interface SabTimerResult {
+  isClamped: boolean;
+  clampAmountUs: number;
+  resolutionUs: number;
+}
+
+export declare function isSabAvailable(): boolean;
+export declare function collectHighResTimings(opts?: { iterations?: number; matrixSize?: number }): {
+  timings: number[];
+  resolutionUs: number;
+};
+
+// =============================================================================
+// Terminal / DX Utilities
+// =============================================================================
+
+export declare function renderProbeResult(opts: {
+  payload: ProofPayload;
+  hash: string;
+  result?: ValidationResult;
+  enf?: EnfResult | null;
+  gpu?: GpuEntropyResult | null;
+  dram?: DramResult | null;
+  llm?: LlmResult | null;
+  elapsedMs?: number;
+}): void;
+
+export declare function renderError(err: Error | string): void;
+export declare function renderInlineUpdateHint(latest: string): void;
+
+// =============================================================================
+// Version / Update Notifier
+// =============================================================================
+
+export declare const CURRENT_VERSION: string;
+
+export declare function checkForUpdate(opts?: {
+  silent?: boolean;
+  pkg?: string;
+}): Promise<{ current: string; latest: string | null; updateAvailable: boolean }>;
+
+export declare function notifyOnExit(opts?: { pkg?: string }): void;
+
+// =============================================================================
+// Extended PulseCommitment (includes extended signal layer results)
+// =============================================================================
+
+export interface ExtendedPulseCommitment extends PulseCommitment {
+  extended: {
+    enf:  EnfResult  | null;
+    gpu:  GpuEntropyResult | null;
+    dram: DramResult | null;
+    llm:  LlmResult  | null;
+  };
+}
+
+// =============================================================================
+// TrustScore
+// =============================================================================
+
+export interface TrustScoreBreakdown {
+  pts: number;
+  max: number;
+  [key: string]: unknown;
+}
+
+export interface TrustScorePenalty {
+  signal: string;
+  reason: string;
+  cap: number;
+}
+
+export interface TrustScoreBonus {
+  signal: string;
+  reason: string;
+  pts: number;
+}
+
+export interface TrustScore {
+  score: number;
+  grade: 'A' | 'B' | 'C' | 'D' | 'F';
+  label: 'Trusted' | 'Verified' | 'Marginal' | 'Suspicious' | 'Blocked';
+  color: string;
+  hardCap: number | null;
+  breakdown: {
+    physics: TrustScoreBreakdown;
+    enf:     TrustScoreBreakdown;
+    gpu:     TrustScoreBreakdown;
+    dram:    TrustScoreBreakdown;
+    bio:     TrustScoreBreakdown;
+  };
+  penalties: TrustScorePenalty[];
+  bonuses:   TrustScoreBonus[];
+  signals: {
+    physics: number;
+    enf:     number;
+    gpu:     number;
+    dram:    number;
+    bio:     number;
+  };
+}
+
+export declare function computeTrustScore(
+  payload: ProofPayload,
+  extended?: { enf?: EnfResult; gpu?: GpuEntropyResult; dram?: DramResult; llm?: LlmResult }
+): TrustScore;
+
+export declare function formatTrustScore(ts: TrustScore): string;
+
+// =============================================================================
+// HMAC-Signed Challenge
+// =============================================================================
+
+export interface SignedChallenge {
+  nonce:     string;
+  issuedAt:  number;
+  expiresAt: number;
+  sig:       string;
+}
+
+export interface ChallengeVerifyResult {
+  valid:   boolean;
+  reason?: string;
+}
+
+export declare function createChallenge(
+  secret: string,
+  opts?: { ttlMs?: number; nonce?: string }
+): SignedChallenge;
+
+export declare function verifyChallenge(
+  challenge: SignedChallenge,
+  secret: string,
+  opts?: { checkNonce?: (nonce: string) => Promise<boolean> }
+): Promise<ChallengeVerifyResult>;
+
+export declare function embedChallenge(challenge: SignedChallenge, payload: ProofPayload): ProofPayload;
+export declare function extractChallenge(payload: ProofPayload): SignedChallenge;
+export declare function generateSecret(): string;
+
+// =============================================================================
+// React Native Hook
+// =============================================================================
+
+export interface TremorResult {
+  tremorPresent: boolean;
+  tremorPower:   number;
+  rmsNoise:      number;
+  sampleRate:    number;
+  gyroNoise:     number;
+  isStatic:      boolean;
+}
+
+export interface TouchAnalysis {
+  humanConf:    number;
+  dwellMean:    number;
+  dwellCV:      number;
+  sampleCount:  number;
+}
+
+export interface UsePulseNativeOptions {
+  challengeUrl?: string;
+  verifyUrl?:    string;
+  apiKey?:       string;
+  sensorMs?:     number;
+  autoRun?:      boolean;
+  onResult?:     (trustScore: TrustScore, proof: object) => void;
+  onError?:      (error: Error) => void;
+}
+
+export interface UsePulseNativeReturn {
+  run:         () => Promise<void>;
+  reset:       () => void;
+  isRunning:   boolean;
+  stage:       string | null;
+  pct:         number;
+  trustScore:  TrustScore | null;
+  tremor:      TremorResult | null;
+  touches:     TouchAnalysis | null;
+  proof:       object | null;
+  error:       Error | null;
+  panHandlers: object | null;
+}
+
+export declare function usePulseNative(opts?: UsePulseNativeOptions): UsePulseNativeReturn;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@svrnsec/pulse",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Physical Turing Test — Hardware-Biological Symmetry Protocol distinguishing real consumer devices from sanitised datacenter VMs.",
   "type": "module",
   "license": "MIT",
@@ -14,6 +14,9 @@
     "url": "https://github.com/ayronny14-alt/Svrn-Pulse-Security/issues"
   },
   "types": "index.d.ts",
+  "bin": {
+    "svrnsec-pulse": "./bin/svrnsec-pulse.js"
+  },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
@@ -21,28 +24,39 @@
   "exports": {
     ".": {
       "browser": "./dist/pulse.esm.js",
-      "import": "./dist/pulse.esm.js",
+      "import":  "./dist/pulse.esm.js",
       "require": "./dist/pulse.cjs.js"
     },
     "./validator": {
-      "node": "./src/proof/validator.js",
+      "node":   "./src/proof/validator.js",
       "import": "./src/proof/validator.js"
     },
+    "./challenge": {
+      "node":   "./src/proof/challenge.js",
+      "import": "./src/proof/challenge.js"
+    },
+    "./trust": {
+      "import": "./src/analysis/trustScore.js",
+      "node":   "./src/analysis/trustScore.js"
+    },
     "./registry": {
       "import": "./src/registry/serializer.js",
-      "node": "./src/registry/serializer.js"
+      "node":   "./src/registry/serializer.js"
     },
     "./middleware/express": {
       "import": "./src/middleware/express.js",
-      "node": "./src/middleware/express.js"
+      "node":   "./src/middleware/express.js"
     },
     "./middleware/next": {
       "import": "./src/middleware/next.js",
-      "node": "./src/middleware/next.js"
+      "node":   "./src/middleware/next.js"
     },
     "./react": {
       "import": "./src/integrations/react.js"
     },
+    "./react-native": {
+      "import": "./src/integrations/react-native.js"
+    },
     "./gpu": {
       "import": "./src/collector/gpu.js"
     },
@@ -59,38 +73,45 @@
       "import": "./src/collector/enf.js"
     }
   },
-  "main": "dist/pulse.cjs.js",
+  "main":   "dist/pulse.cjs.js",
   "module": "dist/pulse.esm.js",
   "files": [
     "dist/",
     "pkg/",
+    "bin/",
+    "src/",
     "index.d.ts",
-    "src/proof/validator.js",
-    "src/proof/fingerprint.js",
-    "src/middleware/express.js",
-    "src/middleware/next.js",
-    "src/registry/serializer.js",
-    "src/integrations/react.js",
     "SECURITY.md"
   ],
   "scripts": {
     "build:wasm": "bash build.sh",
-    "build:js": "rollup -c rollup.config.js",
-    "build": "npm run build:wasm && npm run build:js",
-    "dev": "rollup -c rollup.config.js --watch",
-    "test": "node --experimental-vm-modules ./node_modules/jest-cli/bin/jest.js",
-    "demo": "node demo/node-demo.js"
+    "build:js":   "rollup -c rollup.config.js",
+    "build":      "npm run build:wasm && npm run build:js",
+    "dev":        "rollup -c rollup.config.js --watch",
+    "test":       "node --experimental-vm-modules ./node_modules/jest-cli/bin/jest.js",
+    "demo":       "node demo/node-demo.js",
+    "scan":       "node bin/svrnsec-pulse.js scan"
   },
   "dependencies": {
     "@noble/hashes": "^1.4.0"
   },
   "devDependencies": {
-    "@rollup/plugin-commonjs": "^25.0.0",
+    "@rollup/plugin-commonjs":     "^25.0.0",
     "@rollup/plugin-node-resolve": "^15.0.0",
-    "@rollup/plugin-wasm": "^6.2.2",
-    "@types/jest": "^29.0.0",
-    "jest": "^29.0.0",
-    "rollup": "^4.0.0"
+    "@rollup/plugin-wasm":         "^6.2.2",
+    "@types/jest":                 "^29.0.0",
+    "jest":                        "^29.0.0",
+    "rollup":                      "^4.0.0"
+  },
+  "peerDependencies": {
+    "react":        ">=17.0.0",
+    "react-native": ">=0.70.0",
+    "expo-sensors": ">=13.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react":        { "optional": true },
+    "react-native": { "optional": true },
+    "expo-sensors": { "optional": true }
   },
   "keywords": [
     "physical-turing-test",
@@ -105,7 +126,13 @@
     "dram-detection",
     "llm-detection",
     "ai-agent-detection",
-    "behavioral-biometrics"
+    "behavioral-biometrics",
+    "trust-score",
+    "hmac-challenge",
+    "react-native",
+    "mobile-security",
+    "enf-detection",
+    "cli"
   ],
   "engines": {
     "node": ">=18.0.0"

package/src/analysis/audio.js

@@ -0,0 +1,213 @@
+/**
+ * @sovereign/pulse — AudioContext Oscillator Jitter
+ *
+ * Measures the scheduling jitter of the browser's audio pipeline.
+ * Real audio hardware callbacks are driven by a hardware interrupt (IRQ)
+ * from the sound card; the timing reflects the actual interrupt latency
+ * of the physical device.  VM audio drivers (if present at all) are
+ * emulated and show either unrealistically low jitter or burst-mode
+ * scheduling artefacts that are statistically distinguishable.
+ */
+
+/**
+ * @param {object} [opts]
+ * @param {number} [opts.durationMs=2000]  - how long to collect audio callbacks
+ * @param {number} [opts.bufferSize=256]   - ScriptProcessorNode buffer size
+ * @returns {Promise<AudioJitter>}
+ */
+export async function collectAudioJitter(opts = {}) {
+  const { durationMs = 2000, bufferSize = 256 } = opts;
+
+  const base = {
+    available:         false,
+    workletAvailable:  false,
+    callbackJitterCV:  0,
+    noiseFloorMean:    0,
+    sampleRate:        0,
+    callbackCount:     0,
+    jitterTimings:     [],
+  };
+
+  if (typeof AudioContext === 'undefined' && typeof webkitAudioContext === 'undefined') {
+    return base; // Node.js / server environment
+  }
+
+  let ctx;
+  try {
+    ctx = new (window.AudioContext || window.webkitAudioContext)();
+  } catch (_) {
+    return base;
+  }
+
+  // Some browsers require a user gesture before AudioContext can run.
+  if (ctx.state === 'suspended') {
+    try {
+      await ctx.resume();
+    } catch (_) {
+      await ctx.close().catch(() => {});
+      return base;
+    }
+  }
+
+  const sampleRate       = ctx.sampleRate;
+  const expectedInterval = (bufferSize / sampleRate) * 1000; // ms per callback
+
+  const jitterTimings = []; // absolute AudioContext.currentTime at each callback
+  const callbackDeltas = [];
+
+  const result = await new Promise((resolve) => {
+    // ── AudioWorklet (preferred — runs on dedicated real-time thread) ──────
+    const useWorklet = typeof AudioWorkletNode !== 'undefined';
+    base.workletAvailable = useWorklet;
+
+    if (useWorklet) {
+      // Inline worklet: send currentTime back via MessagePort every buffer
+      const workletCode = `
+        class PulseProbe extends AudioWorkletProcessor {
+          process(inputs, outputs) {
+            this.port.postMessage({ t: currentTime });
+            // Pass-through silence
+            for (const out of outputs)
+              for (const ch of out) ch.fill(0);
+            return true;
+          }
+        }
+        registerProcessor('pulse-probe', PulseProbe);
+      `;
+      const blob    = new Blob([workletCode], { type: 'application/javascript' });
+      const blobUrl = URL.createObjectURL(blob);
+
+      ctx.audioWorklet.addModule(blobUrl).then(() => {
+        const node = new AudioWorkletNode(ctx, 'pulse-probe');
+        node.port.onmessage = (e) => {
+          jitterTimings.push(e.data.t * 1000); // convert to ms
+        };
+        node.connect(ctx.destination);
+
+        setTimeout(async () => {
+          node.disconnect();
+          URL.revokeObjectURL(blobUrl);
+          resolve(node);
+        }, durationMs);
+      }).catch(() => {
+        URL.revokeObjectURL(blobUrl);
+        _fallbackScriptProcessor(ctx, bufferSize, durationMs, jitterTimings, resolve);
+      });
+
+    } else {
+      _fallbackScriptProcessor(ctx, bufferSize, durationMs, jitterTimings, resolve);
+    }
+  });
+
+  // ── Compute deltas between successive callback times ────────────────────
+  for (let i = 1; i < jitterTimings.length; i++) {
+    callbackDeltas.push(jitterTimings[i] - jitterTimings[i - 1]);
+  }
+
+  // ── Noise floor via AnalyserNode ─────────────────────────────────────────
+  // Feed a silent oscillator through an analyser; the FFT magnitude at silence
+  // reveals the hardware's thermal noise floor (varies per ADC/DAC chipset).
+  const noiseFloor = await _measureNoiseFloor(ctx);
+
+  await ctx.close().catch(() => {});
+
+  // ── Statistics ────────────────────────────────────────────────────────────
+  const mean = callbackDeltas.length
+    ? callbackDeltas.reduce((s, v) => s + v, 0) / callbackDeltas.length
+    : 0;
+  const variance = callbackDeltas.length > 1
+    ? callbackDeltas.reduce((s, v) => s + (v - mean) ** 2, 0) / (callbackDeltas.length - 1)
+    : 0;
+  const jitterCV = mean > 0 ? Math.sqrt(variance) / mean : 0;
+
+  return {
+    available:         true,
+    workletAvailable:  base.workletAvailable,
+    callbackJitterCV:  jitterCV,
+    noiseFloorMean:    noiseFloor.mean,
+    noiseFloorStd:     noiseFloor.std,
+    sampleRate,
+    callbackCount:     jitterTimings.length,
+    expectedIntervalMs: expectedInterval,
+    // Only include summary stats, not raw timings (privacy / size)
+    jitterMeanMs:      mean,
+    jitterP95Ms:       _percentile(callbackDeltas, 95),
+  };
+}
+
+/**
+ * @typedef {object} AudioJitter
+ * @property {boolean} available
+ * @property {boolean} workletAvailable
+ * @property {number}  callbackJitterCV
+ * @property {number}  noiseFloorMean
+ * @property {number}  sampleRate
+ * @property {number}  callbackCount
+ */
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function _fallbackScriptProcessor(ctx, bufferSize, durationMs, jitterTimings, resolve) {
+  // ScriptProcessorNode is deprecated but universally supported.
+  const proc = ctx.createScriptProcessor(bufferSize, 1, 1);
+  proc.onaudioprocess = () => {
+    jitterTimings.push(ctx.currentTime * 1000);
+  };
+  // Connect to keep the graph alive
+  const osc = ctx.createOscillator();
+  osc.frequency.value = 1; // sub-audible
+  osc.connect(proc);
+  proc.connect(ctx.destination);
+  osc.start();
+
+  setTimeout(() => {
+    osc.stop();
+    osc.disconnect();
+    proc.disconnect();
+    resolve(proc);
+  }, durationMs);
+}
+
+async function _measureNoiseFloor(ctx) {
+  try {
+    const analyser = ctx.createAnalyser();
+    analyser.fftSize = 256;
+    analyser.connect(ctx.destination);
+
+    // Silent source
+    const buf  = ctx.createBuffer(1, ctx.sampleRate * 0.1, ctx.sampleRate);
+    const src  = ctx.createBufferSource();
+    src.buffer = buf;
+    src.connect(analyser);
+    src.start();
+
+    await new Promise(r => setTimeout(r, 150));
+
+    const data = new Float32Array(analyser.frequencyBinCount);
+    analyser.getFloatFrequencyData(data);
+    analyser.disconnect();
+
+    // Limit to 32 bins to keep the payload small
+    const trimmed = Array.from(data.slice(0, 32)).map(v =>
+      isFinite(v) ? Math.pow(10, v / 20) : 0 // dB → linear
+    );
+    const mean = trimmed.reduce((s, v) => s + v, 0) / trimmed.length;
+    const std  = Math.sqrt(
+      trimmed.reduce((s, v) => s + (v - mean) ** 2, 0) / trimmed.length
+    );
+    return { mean, std };
+  } catch (_) {
+    return { mean: 0, std: 0 };
+  }
+}
+
+function _percentile(arr, p) {
+  if (!arr.length) return 0;
+  const sorted = [...arr].sort((a, b) => a - b);
+  const idx    = (p / 100) * (sorted.length - 1);
+  const lo     = Math.floor(idx);
+  const hi     = Math.ceil(idx);
+  return sorted[lo] + (sorted[hi] - sorted[lo]) * (idx - lo);
+}