@iam-protocol/pulse-sdk 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iam-protocol/pulse-sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Client-side SDK for IAM Protocol — sensor capture, TBH generation, ZK proof construction",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/config.ts

@@ -10,7 +10,8 @@ export const BN254_SCALAR_FIELD = BigInt(
 
 export const FINGERPRINT_BITS = 256;
 export const DEFAULT_THRESHOLD = 30;
-export const NUM_PUBLIC_INPUTS = 3;
+export const DEFAULT_MIN_DISTANCE = 3;
+export const NUM_PUBLIC_INPUTS = 4;
 
 export const PROOF_A_SIZE = 64;
 export const PROOF_B_SIZE = 128;

package/src/extraction/kinematic.ts

@@ -1,15 +1,15 @@
 import type { MotionSample, TouchSample } from "../sensor/types";
-import { condense } from "./statistics";
+import { condense, variance } from "./statistics";
 
 /**
  * Extract kinematic features from motion (IMU) data.
  * Computes jerk (3rd derivative) and jounce (4th derivative) of acceleration,
  * then condenses each axis into statistics.
  *
- * Returns: ~48 values (6 axes × 2 derivatives × 4 stats)
+ * Returns: ~54 values (6 axes × 2 derivatives × 4 stats + 6 jitter variance values)
  */
 export function extractMotionFeatures(samples: MotionSample[]): number[] {
-  if (samples.length < 5) return new Array(48).fill(0);
+  if (samples.length < 5) return new Array(54).fill(0);
 
   // Extract acceleration and rotation time series
   const axes = {
@@ -44,6 +44,19 @@ export function extractMotionFeatures(samples: MotionSample[]): number[] {
     );
   }
 
+  // Jitter variance per axis: variance of windowed jerk variance.
+  // Real human tremor fluctuates over time (high jitter variance).
+  // Synthetic/replay data has constant jitter (low jitter variance).
+  for (const values of Object.values(axes)) {
+    const jerk = derivative(values);
+    const windowSize = Math.max(5, Math.floor(jerk.length / 4));
+    const windowVariances: number[] = [];
+    for (let i = 0; i <= jerk.length - windowSize; i += windowSize) {
+      windowVariances.push(variance(jerk.slice(i, i + windowSize)));
+    }
+    features.push(windowVariances.length >= 2 ? variance(windowVariances) : 0);
+  }
+
   return features;
 }
 
@@ -52,10 +65,10 @@ export function extractMotionFeatures(samples: MotionSample[]): number[] {
  * Computes velocity and acceleration of touch coordinates,
  * plus pressure and area statistics.
  *
- * Returns: ~32 values
+ * Returns: ~36 values (32 base + 4 jitter variance for x, y, pressure, area)
  */
 export function extractTouchFeatures(samples: TouchSample[]): number[] {
-  if (samples.length < 5) return new Array(32).fill(0);
+  if (samples.length < 5) return new Array(36).fill(0);
 
   const x = samples.map((s) => s.x);
   const y = samples.map((s) => s.y);
@@ -88,6 +101,16 @@ export function extractTouchFeatures(samples: TouchSample[]): number[] {
   features.push(...Object.values(condense(jerkX)));
   features.push(...Object.values(condense(jerkY)));
 
+  // Jitter variance for touch signals: detects synthetic smoothness
+  for (const values of [vx, vy, pressure, area]) {
+    const windowSize = Math.max(5, Math.floor(values.length / 4));
+    const windowVariances: number[] = [];
+    for (let i = 0; i <= values.length - windowSize; i += windowSize) {
+      windowVariances.push(variance(values.slice(i, i + windowSize)));
+    }
+    features.push(windowVariances.length >= 2 ? variance(windowVariances) : 0);
+  }
+
   return features;
 }
 

package/src/extraction/mfcc.ts

@@ -1,5 +1,5 @@
 import type { AudioCapture } from "../sensor/types";
-import { condense } from "./statistics";
+import { condense, entropy } from "./statistics";
 
 // Frame parameters matching the research paper spec
 const FRAME_SIZE = 400; // 25ms at 16kHz
@@ -11,7 +11,7 @@ const NUM_MFCC = 13;
  * Computes 13 MFCCs per frame, plus delta and delta-delta coefficients,
  * then condenses each coefficient's time series into 4 statistics.
  *
- * Returns: 13 coefficients × 3 (raw + delta + delta-delta) × 4 stats = 156 values
+ * Returns: 13 coefficients × 3 (raw + delta + delta-delta) × 4 stats + 13 entropy values = 169 values
  */
 export function extractMFCC(audio: AudioCapture): number[] {
   const { samples, sampleRate } = audio;
@@ -22,12 +22,12 @@ export function extractMFCC(audio: AudioCapture): number[] {
     Meyda = require("meyda");
   } catch {
     // Meyda not available — return zeros (fallback for environments without it)
-    return new Array(NUM_MFCC * 3 * 4).fill(0);
+    return new Array(NUM_MFCC * 3 * 4 + NUM_MFCC).fill(0);
   }
 
   // Extract MFCCs per frame
   const numFrames = Math.floor((samples.length - FRAME_SIZE) / HOP_SIZE) + 1;
-  if (numFrames < 3) return new Array(NUM_MFCC * 3 * 4).fill(0);
+  if (numFrames < 3) return new Array(NUM_MFCC * 3 * 4 + NUM_MFCC).fill(0);
 
   const mfccFrames: number[][] = [];
 
@@ -78,6 +78,13 @@ export function extractMFCC(audio: AudioCapture): number[] {
     features.push(stats.mean, stats.variance, stats.skewness, stats.kurtosis);
   }
 
+  // Entropy per MFCC coefficient: measures information density across frames.
+  // Real speech has moderate, varied entropy. Synthetic audio is too uniform or too structured.
+  for (let c = 0; c < NUM_MFCC; c++) {
+    const raw = mfccFrames.map((f) => f[c] ?? 0);
+    features.push(entropy(raw));
+  }
+
   return features;
 }
 

package/src/extraction/statistics.ts

@@ -50,6 +50,52 @@ export function condense(values: number[]): StatsSummary {
   };
 }
 
+/**
+ * Shannon entropy over histogram bins. Measures information density.
+ * Real human data has moderate entropy (varied but structured).
+ * Synthetic data is either too uniform (high entropy) or too structured (low entropy).
+ */
+export function entropy(values: number[], bins: number = 16): number {
+  if (values.length < 2) return 0;
+  const min = Math.min(...values);
+  const max = Math.max(...values);
+  if (min === max) return 0;
+
+  const counts = new Array(bins).fill(0);
+  const range = max - min;
+  for (const v of values) {
+    const idx = Math.min(Math.floor(((v - min) / range) * bins), bins - 1);
+    counts[idx]++;
+  }
+
+  let h = 0;
+  for (const c of counts) {
+    if (c > 0) {
+      const p = c / values.length;
+      h -= p * Math.log2(p);
+    }
+  }
+  return h;
+}
+
+/**
+ * Autocorrelation at a given lag. Detects periodic synthetic patterns.
+ * Real human data has low autocorrelation at most lags (chaotic/noisy).
+ * Synthetic data often has high autocorrelation (periodic/smooth).
+ */
+export function autocorrelation(values: number[], lag: number = 1): number {
+  if (values.length <= lag) return 0;
+  const m = mean(values);
+  const v = variance(values, m);
+  if (v === 0) return 0;
+
+  let sum = 0;
+  for (let i = 0; i < values.length - lag; i++) {
+    sum += (values[i]! - m) * (values[i + lag]! - m);
+  }
+  return sum / ((values.length - lag) * v);
+}
+
 export function fuseFeatures(
   audio: number[],
   motion: number[],

package/src/index.ts

@@ -3,7 +3,7 @@ export { PulseSDK, PulseSession } from "./pulse";
 
 // Configuration
 export type { PulseConfig } from "./config";
-export { PROGRAM_IDS, DEFAULT_THRESHOLD, FINGERPRINT_BITS, MIN_CAPTURE_MS, MAX_CAPTURE_MS, DEFAULT_CAPTURE_MS } from "./config";
+export { PROGRAM_IDS, DEFAULT_THRESHOLD, DEFAULT_MIN_DISTANCE, FINGERPRINT_BITS, MIN_CAPTURE_MS, MAX_CAPTURE_MS, DEFAULT_CAPTURE_MS } from "./config";
 
 // Hashing
 export type { TemporalFingerprint, TBH, PackedFingerprint } from "./hashing/types";
@@ -18,7 +18,7 @@ export {
 
 // Feature extraction
 export type { StatsSummary, FeatureVector, FusedFeatureVector } from "./extraction/types";
-export { mean, variance, skewness, kurtosis, condense, fuseFeatures } from "./extraction/statistics";
+export { mean, variance, skewness, kurtosis, condense, entropy, autocorrelation, fuseFeatures } from "./extraction/statistics";
 
 // Proof generation
 export type { SolanaProof, CircuitInput, ProofResult } from "./proof/types";

package/src/proof/prover.ts

@@ -1,7 +1,7 @@
 import type { TBH } from "../hashing/types";
 import type { CircuitInput, ProofResult, SolanaProof } from "./types";
 import { serializeProof } from "./serializer";
-import { DEFAULT_THRESHOLD } from "../config";
+import { DEFAULT_THRESHOLD, DEFAULT_MIN_DISTANCE } from "../config";
 
 // Use dynamic import for snarkjs (it's a CJS module)
 let snarkjsModule: any = null;
@@ -19,7 +19,8 @@ async function getSnarkjs(): Promise<any> {
 export function prepareCircuitInput(
   current: TBH,
   previous: TBH,
-  threshold: number = DEFAULT_THRESHOLD
+  threshold: number = DEFAULT_THRESHOLD,
+  minDistance: number = DEFAULT_MIN_DISTANCE
 ): CircuitInput {
   return {
     ft_new: current.fingerprint,
@@ -29,6 +30,7 @@ export function prepareCircuitInput(
     commitment_new: current.commitment.toString(),
     commitment_prev: previous.commitment.toString(),
     threshold: threshold.toString(),
+    min_distance: minDistance.toString(),
   };
 }
 

package/src/proof/types.ts

@@ -22,6 +22,7 @@ export interface CircuitInput {
   commitment_new: string;
   commitment_prev: string;
   threshold: string;
+  min_distance: string;
 }
 
 /** Proof generation result */

package/src/pulse.ts

@@ -35,7 +35,7 @@ type ResolvedConfig = Required<Pick<PulseConfig, "cluster" | "threshold">> &
 function extractFeatures(data: SensorData): number[] {
   const audioFeatures = data.audio
     ? extractMFCC(data.audio)
-    : new Array(156).fill(0);
+    : new Array(169).fill(0);
   const motionFeatures = extractMotionFeatures(data.motion);
   const touchFeatures = extractTouchFeatures(data.touch);
   return fuseFeatures(audioFeatures, motionFeatures, touchFeatures);

package/test/integration.test.ts

@@ -29,8 +29,8 @@ describe.skipIf(!circuitArtifactsExist)(
   "integration: full crypto pipeline",
   () => {
     it("generates a valid proof from mock features end-to-end", async () => {
-      // 1. Create mock feature vector (~236 random values)
-      const features = Array.from({ length: 236 }, (_, i) =>
+      // 1. Create mock feature vector (~259 random values: 169 audio + 54 motion + 36 touch)
+      const features = Array.from({ length: 259 }, (_, i) =>
         Math.sin(i * 0.3) * Math.cos(i * 0.7)
       );
 
@@ -56,6 +56,7 @@ describe.skipIf(!circuitArtifactsExist)(
       const input = prepareCircuitInput(tbhNew, tbhPrev, 30);
       expect(input.ft_new.length).toBe(256);
       expect(input.threshold).toBe("30");
+      expect(input.min_distance).toBe("3");
 
       // 6. Generate Groth16 proof
       const { proof, publicSignals } = await generateProof(

package/test/serializer.test.ts

@@ -31,6 +31,7 @@ const mockPublicSignals = [
   "111111111111111111111",
   "222222222222222222222",
   "30",
+  "3",
 ];
 
 describe("serializer", () => {