@iam-protocol/pulse-sdk 0.2.5 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iam-protocol/pulse-sdk",
-  "version": "0.2.5",
+  "version": "0.3.0",
   "description": "Client-side SDK for IAM Protocol — sensor capture, TBH generation, ZK proof construction",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -21,6 +21,7 @@
   "dependencies": {
     "circomlibjs": "^0.1.7",
     "meyda": "^5.6.3",
+    "pitchfinder": "^2.3.4",
     "snarkjs": "^0.7.6"
   },
   "peerDependencies": {

package/src/config.ts

@@ -9,7 +9,7 @@ export const BN254_SCALAR_FIELD = BigInt(
 );
 
 export const FINGERPRINT_BITS = 256;
-export const DEFAULT_THRESHOLD = 30;
+export const DEFAULT_THRESHOLD = 96;
 export const DEFAULT_MIN_DISTANCE = 3;
 export const NUM_PUBLIC_INPUTS = 4;
 

package/src/extraction/kinematic.ts

@@ -1,5 +1,5 @@
 import type { MotionSample, TouchSample } from "../sensor/types";
-import { condense, variance } from "./statistics";
+import { condense, variance, entropy } from "./statistics";
 
 /**
  * Extract kinematic features from motion (IMU) data.
@@ -122,3 +122,173 @@ function derivative(values: number[]): number[] {
   }
   return d;
 }
+
+/**
+ * Extract mouse dynamics features as a desktop replacement for motion sensor data.
+ * Captures behavioral patterns from mouse/pointer movement that are user-specific:
+ * path curvature, speed patterns, micro-corrections, pause behavior.
+ *
+ * Returns: 54 values (matches motion feature dimension for consistent SimHash input)
+ */
+export function extractMouseDynamics(samples: TouchSample[]): number[] {
+  if (samples.length < 10) return new Array(54).fill(0);
+
+  const x = samples.map((s) => s.x);
+  const y = samples.map((s) => s.y);
+  const pressure = samples.map((s) => s.pressure);
+  const area = samples.map((s) => s.width * s.height);
+
+  // Velocity
+  const vx = derivative(x);
+  const vy = derivative(y);
+  const speed = vx.map((dx, i) => Math.sqrt(dx * dx + (vy[i] ?? 0) * (vy[i] ?? 0)));
+
+  // Acceleration
+  const accX = derivative(vx);
+  const accY = derivative(vy);
+  const acc = accX.map((ax, i) => Math.sqrt(ax * ax + (accY[i] ?? 0) * (accY[i] ?? 0)));
+
+  // Jerk (derivative of acceleration)
+  const jerkX = derivative(accX);
+  const jerkY = derivative(accY);
+  const jerk = jerkX.map((jx, i) => Math.sqrt(jx * jx + (jerkY[i] ?? 0) * (jerkY[i] ?? 0)));
+
+  // Path curvature: angle change between consecutive movement vectors
+  const curvatures: number[] = [];
+  for (let i = 1; i < vx.length; i++) {
+    const angle1 = Math.atan2(vy[i - 1] ?? 0, vx[i - 1] ?? 0);
+    const angle2 = Math.atan2(vy[i] ?? 0, vx[i] ?? 0);
+    let diff = angle2 - angle1;
+    while (diff > Math.PI) diff -= 2 * Math.PI;
+    while (diff < -Math.PI) diff += 2 * Math.PI;
+    curvatures.push(Math.abs(diff));
+  }
+
+  // Movement directions for directional entropy
+  const directions = vx.map((dx, i) => Math.atan2(vy[i] ?? 0, dx));
+
+  // Micro-corrections: direction reversals
+  let reversals = 0;
+  for (let i = 2; i < directions.length; i++) {
+    const d1 = directions[i - 1]! - directions[i - 2]!;
+    const d2 = directions[i]! - directions[i - 1]!;
+    if (d1 * d2 < 0) reversals++;
+  }
+  const reversalRate = directions.length > 2 ? reversals / (directions.length - 2) : 0;
+  const reversalMagnitude = curvatures.length > 0
+    ? curvatures.reduce((a, b) => a + b, 0) / curvatures.length
+    : 0;
+
+  // Pause detection: frames where speed is near zero
+  const speedThreshold = 0.5;
+  const pauseFrames = speed.filter((s) => s < speedThreshold).length;
+  const pauseRatio = speed.length > 0 ? pauseFrames / speed.length : 0;
+
+  // Path efficiency: straight-line distance / total path length
+  const totalPathLength = speed.reduce((a, b) => a + b, 0);
+  const straightLine = Math.sqrt(
+    (x[x.length - 1]! - x[0]!) ** 2 + (y[y.length - 1]! - y[0]!) ** 2
+  );
+  const pathEfficiency = totalPathLength > 0 ? straightLine / totalPathLength : 0;
+
+  // Movement durations between pauses
+  const movementDurations: number[] = [];
+  let currentDuration = 0;
+  for (const s of speed) {
+    if (s >= speedThreshold) {
+      currentDuration++;
+    } else if (currentDuration > 0) {
+      movementDurations.push(currentDuration);
+      currentDuration = 0;
+    }
+  }
+  if (currentDuration > 0) movementDurations.push(currentDuration);
+
+  // Segment lengths between direction changes
+  const segmentLengths: number[] = [];
+  let segLen = 0;
+  for (let i = 1; i < directions.length; i++) {
+    segLen += speed[i] ?? 0;
+    const angleDiff = Math.abs(directions[i]! - directions[i - 1]!);
+    if (angleDiff > Math.PI / 4) {
+      segmentLengths.push(segLen);
+      segLen = 0;
+    }
+  }
+  if (segLen > 0) segmentLengths.push(segLen);
+
+  // Windowed jitter variance of speed
+  const windowSize = Math.max(5, Math.floor(speed.length / 4));
+  const windowVariances: number[] = [];
+  for (let i = 0; i + windowSize <= speed.length; i += windowSize) {
+    const window = speed.slice(i, i + windowSize);
+    windowVariances.push(variance(window));
+  }
+  const speedJitter = windowVariances.length > 1 ? variance(windowVariances) : 0;
+
+  // Path length normalized by capture duration
+  const duration = samples.length > 1
+    ? (samples[samples.length - 1]!.timestamp - samples[0]!.timestamp) / 1000
+    : 1;
+  const normalizedPathLength = totalPathLength / Math.max(duration, 0.001);
+
+  // Angle autocorrelation at lags 1, 2, 3
+  const angleAutoCorr: number[] = [];
+  for (let lag = 1; lag <= 3; lag++) {
+    if (directions.length <= lag) {
+      angleAutoCorr.push(0);
+      continue;
+    }
+    const n = directions.length - lag;
+    const meanDir = directions.reduce((a, b) => a + b, 0) / directions.length;
+    let num = 0;
+    let den = 0;
+    for (let i = 0; i < n; i++) {
+      num += (directions[i]! - meanDir) * (directions[i + lag]! - meanDir);
+      den += (directions[i]! - meanDir) ** 2;
+    }
+    angleAutoCorr.push(den > 0 ? num / den : 0);
+  }
+
+  // Assemble 54 features
+  const curvatureStats = condense(curvatures);               // 4
+  const dirEntropy = entropy(directions, 16);                 // 1
+  const speedStats = condense(speed);                         // 4
+  const accStats = condense(acc);                             // 4
+  // micro-corrections: reversalRate + reversalMagnitude       // 2
+  // pauseRatio                                                // 1
+  // pathEfficiency                                            // 1
+  // speedJitter                                               // 1
+  const jerkStats = condense(jerk);                           // 4
+  const vxStats = condense(vx);                               // 4
+  const vyStats = condense(vy);                               // 4
+  const accXStats = condense(accX);                           // 4
+  const accYStats = condense(accY);                           // 4
+  const pressureStats = condense(pressure);                   // 4
+  const moveDurStats = condense(movementDurations);           // 4
+  const segLenStats = condense(segmentLengths);               // 4
+  // angleAutoCorr[0..2]                                       // 3
+  // normalizedPathLength                                      // 1
+  // Total: 4+1+4+4+2+1+1+1+4+4+4+4+4+4+4+4+3+1 = 54
+
+  return [
+    curvatureStats.mean, curvatureStats.variance, curvatureStats.skewness, curvatureStats.kurtosis,
+    dirEntropy,
+    speedStats.mean, speedStats.variance, speedStats.skewness, speedStats.kurtosis,
+    accStats.mean, accStats.variance, accStats.skewness, accStats.kurtosis,
+    reversalRate, reversalMagnitude,
+    pauseRatio,
+    pathEfficiency,
+    speedJitter,
+    jerkStats.mean, jerkStats.variance, jerkStats.skewness, jerkStats.kurtosis,
+    vxStats.mean, vxStats.variance, vxStats.skewness, vxStats.kurtosis,
+    vyStats.mean, vyStats.variance, vyStats.skewness, vyStats.kurtosis,
+    accXStats.mean, accXStats.variance, accXStats.skewness, accXStats.kurtosis,
+    accYStats.mean, accYStats.variance, accYStats.skewness, accYStats.kurtosis,
+    pressureStats.mean, pressureStats.variance, pressureStats.skewness, pressureStats.kurtosis,
+    moveDurStats.mean, moveDurStats.variance, moveDurStats.skewness, moveDurStats.kurtosis,
+    segLenStats.mean, segLenStats.variance, segLenStats.skewness, segLenStats.kurtosis,
+    angleAutoCorr[0] ?? 0, angleAutoCorr[1] ?? 0, angleAutoCorr[2] ?? 0,
+    normalizedPathLength,
+  ];
+}

package/src/extraction/lpc.ts

@@ -0,0 +1,215 @@
+/**
+ * Linear Predictive Coding (LPC) for formant detection.
+ *
+ * Implements Levinson-Durbin recursion for LPC coefficient computation
+ * and polynomial root-finding for formant frequency estimation.
+ */
+
+/**
+ * Compute autocorrelation of a signal for lags 0..order.
+ */
+function autocorrelate(signal: Float32Array, order: number): number[] {
+  const r: number[] = [];
+  for (let lag = 0; lag <= order; lag++) {
+    let sum = 0;
+    for (let i = 0; i < signal.length - lag; i++) {
+      sum += signal[i]! * signal[i + lag]!;
+    }
+    r.push(sum);
+  }
+  return r;
+}
+
+/**
+ * Levinson-Durbin recursion to compute LPC coefficients from autocorrelation.
+ * Returns the LPC coefficients a[1..order] (a[0] is implicitly 1).
+ */
+function levinsonDurbin(r: number[], order: number): number[] {
+  const a: number[] = new Array(order + 1).fill(0);
+  const aTemp: number[] = new Array(order + 1).fill(0);
+  a[0] = 1;
+
+  let error = r[0]!;
+  if (error === 0) return new Array(order).fill(0);
+
+  for (let i = 1; i <= order; i++) {
+    let lambda = 0;
+    for (let j = 1; j < i; j++) {
+      lambda += a[j]! * r[i - j]!;
+    }
+    lambda = -(r[i]! + lambda) / error;
+
+    for (let j = 1; j < i; j++) {
+      aTemp[j] = a[j]! + lambda * a[i - j]!;
+    }
+    aTemp[i] = lambda;
+
+    for (let j = 1; j <= i; j++) {
+      a[j] = aTemp[j]!;
+    }
+
+    error *= 1 - lambda * lambda;
+    if (error <= 0) break;
+  }
+
+  return a.slice(1);
+}
+
+/**
+ * Find roots of a polynomial using the Durand-Kerner method.
+ * The polynomial is 1 + a[0]*z^-1 + a[1]*z^-2 + ... + a[n-1]*z^-n
+ * which is equivalent to z^n + a[0]*z^(n-1) + ... + a[n-1] = 0.
+ *
+ * Returns complex roots as [real, imag] pairs.
+ */
+function findRoots(coefficients: number[], maxIterations: number = 50): [number, number][] {
+  const n = coefficients.length;
+  if (n === 0) return [];
+
+  // Initial guesses: points on a circle of radius 0.9
+  const roots: [number, number][] = [];
+  for (let i = 0; i < n; i++) {
+    const angle = (2 * Math.PI * i) / n + 0.1;
+    roots.push([0.9 * Math.cos(angle), 0.9 * Math.sin(angle)]);
+  }
+
+  for (let iter = 0; iter < maxIterations; iter++) {
+    let maxShift = 0;
+
+    for (let i = 0; i < n; i++) {
+      // Evaluate polynomial at roots[i]: z^n + a[0]*z^(n-1) + ... + a[n-1]
+      let pReal = 1;
+      let pImag = 0;
+      let zPowReal = 1;
+      let zPowImag = 0;
+
+      // Compute z^n by repeated multiplication
+      const [rr, ri] = roots[i]!;
+      let curReal = 1;
+      let curImag = 0;
+
+      // Evaluate as: z^n + sum(a[k] * z^(n-1-k))
+      // Start with z^n
+      let znReal = 1;
+      let znImag = 0;
+      for (let k = 0; k < n; k++) {
+        const newReal = znReal * rr - znImag * ri;
+        const newImag = znReal * ri + znImag * rr;
+        znReal = newReal;
+        znImag = newImag;
+      }
+      pReal = znReal;
+      pImag = znImag;
+
+      // Add coefficient terms: a[k] * z^(n-1-k)
+      zPowReal = 1;
+      zPowImag = 0;
+      for (let k = n - 1; k >= 0; k--) {
+        pReal += coefficients[k]! * zPowReal;
+        pImag += coefficients[k]! * zPowImag;
+        const newReal = zPowReal * rr - zPowImag * ri;
+        const newImag = zPowReal * ri + zPowImag * rr;
+        zPowReal = newReal;
+        zPowImag = newImag;
+      }
+
+      // Compute product of (roots[i] - roots[j]) for j != i
+      let denomReal = 1;
+      let denomImag = 0;
+      for (let j = 0; j < n; j++) {
+        if (j === i) continue;
+        const diffReal = rr - roots[j]![0];
+        const diffImag = ri - roots[j]![1];
+        const newReal = denomReal * diffReal - denomImag * diffImag;
+        const newImag = denomReal * diffImag + denomImag * diffReal;
+        denomReal = newReal;
+        denomImag = newImag;
+      }
+
+      // Divide p / denom
+      const denomMag2 = denomReal * denomReal + denomImag * denomImag;
+      if (denomMag2 < 1e-30) continue;
+
+      const shiftReal = (pReal * denomReal + pImag * denomImag) / denomMag2;
+      const shiftImag = (pImag * denomReal - pReal * denomImag) / denomMag2;
+
+      roots[i] = [rr - shiftReal, ri - shiftImag];
+      maxShift = Math.max(maxShift, Math.sqrt(shiftReal * shiftReal + shiftImag * shiftImag));
+    }
+
+    if (maxShift < 1e-10) break;
+  }
+
+  return roots;
+}
+
+/**
+ * Extract formant frequencies (F1, F2, F3) from a single audio frame.
+ * Returns [F1, F2, F3] in Hz, or null if extraction fails.
+ */
+function extractFormants(
+  frame: Float32Array,
+  sampleRate: number,
+  lpcOrder: number = 12
+): [number, number, number] | null {
+  const r = autocorrelate(frame, lpcOrder);
+  const coeffs = levinsonDurbin(r, lpcOrder);
+
+  const roots = findRoots(coeffs);
+
+  // Convert roots to frequencies, keep only positive-frequency roots
+  const formantCandidates: number[] = [];
+
+  for (const [real, imag] of roots) {
+    if (imag <= 0) continue; // Keep only positive-frequency roots
+
+    const freq = (Math.atan2(imag, real) / (2 * Math.PI)) * sampleRate;
+    const bandwidth = (-sampleRate / (2 * Math.PI)) * Math.log(Math.sqrt(real * real + imag * imag));
+
+    // Filter: formants are in 200-5000Hz range with reasonable bandwidth
+    if (freq > 200 && freq < 5000 && bandwidth < 500) {
+      formantCandidates.push(freq);
+    }
+  }
+
+  formantCandidates.sort((a, b) => a - b);
+
+  if (formantCandidates.length < 3) return null;
+
+  return [formantCandidates[0]!, formantCandidates[1]!, formantCandidates[2]!];
+}
+
+/**
+ * Extract formant ratio time series (F1/F2 and F2/F3) from audio.
+ * Returns { f1f2: number[], f2f3: number[] } — one ratio per frame where formants were detected.
+ */
+export function extractFormantRatios(
+  samples: Float32Array,
+  sampleRate: number,
+  frameSize: number,
+  hopSize: number
+): { f1f2: number[]; f2f3: number[] } {
+  const f1f2: number[] = [];
+  const f2f3: number[] = [];
+  const numFrames = Math.floor((samples.length - frameSize) / hopSize) + 1;
+
+  for (let i = 0; i < numFrames; i++) {
+    const start = i * hopSize;
+    const frame = samples.slice(start, start + frameSize);
+
+    // Apply Hamming window
+    const windowed = new Float32Array(frameSize);
+    for (let j = 0; j < frameSize; j++) {
+      windowed[j] = (frame[j] ?? 0) * (0.54 - 0.46 * Math.cos((2 * Math.PI * j) / (frameSize - 1)));
+    }
+
+    const formants = extractFormants(windowed, sampleRate);
+    if (formants) {
+      const [f1, f2, f3] = formants;
+      if (f2 > 0) f1f2.push(f1 / f2);
+      if (f3 > 0) f2f3.push(f2 / f3);
+    }
+  }
+
+  return { f1f2, f2f3 };
+}