@entros/pulse-sdk 2.0.0 → 3.0.0

package/README.md

@@ -3,7 +3,7 @@
 [![npm version](https://img.shields.io/npm/v/@entros/pulse-sdk.svg)](https://www.npmjs.com/package/@entros/pulse-sdk)
 [![npm downloads](https://img.shields.io/npm/dm/@entros/pulse-sdk.svg)](https://www.npmjs.com/package/@entros/pulse-sdk)
 
-Client-side SDK for the Entros Protocol. Captures behavioral biometrics (voice, motion, touch), extracts a 314-dimensional statistical feature vector (v2 expansion: MFCCs, LPC coefficients, formant trajectories, voice quality, pitch contour shape, IMU FFT-band tremor, cross-axis covariance, touch curvature, gap distribution, path efficiency — see `docs/master/BLUEPRINT-feature-pipeline-v2.md`), generates a Groth16 zero-knowledge proof, and submits for on-chain verification on Solana. Raw biometric data stays on-device — only derived features and the proof are transmitted.
+Client-side SDK for the Entros Protocol. Captures behavioral biometrics (voice, motion, touch), extracts a 308-dimensional statistical feature vector (v3 expansion: MFCCs with pre-emphasis (C1-C12, MFCC[0] dropped), LPC coefficients, formant trajectories, voice quality, pitch contour shape, IMU FFT-band tremor, cross-axis covariance, mouse-derived FFT / autocorrelation analogues for desktop, touch curvature, gap distribution, path efficiency — see `docs/master/BLUEPRINT-feature-pipeline-v2.md`), generates a Groth16 zero-knowledge proof, and submits for on-chain verification on Solana. Raw biometric data stays on-device — only derived features and the proof are transmitted.
 
 > **Looking for a drop-in?** Most integrators want [`@entros/verify`](https://github.com/entros-protocol/entros-verify) — a popup-pattern React component that wraps this SDK and ships verification in five lines of JSX. Use this package directly when you need to own the verification UX (custom capture canvas, branded loading states, mobile-native).
 
@@ -50,7 +50,7 @@ const result = await pulse.verify(touchElement);
 ## Pipeline
 
 1. **Capture**: Audio (16kHz), IMU (accelerometer + gyroscope), touch (pressure + area) — event-driven, caller controls duration
-2. **Extract**: 314 features — speaker block (176): legacy F0 / jitter / shimmer / HNR / formant ratios / LTAS / amplitude (44) plus v2 additions: MFCCs + delta-MFCCs (78), LPC coefficient stats (24), formant absolute trajectories + bandwidths (16), voice quality CPP/tilt/H1-H2/sub-bands (9), pitch contour DCT (5). Motion block (81): legacy jerk + jounce per IMU axis (54) plus v2 additions: cross-axis covariance (6), FFT band energy on accel axes (12), physiological tremor peak (2), direction-reversal stats (3), motion-magnitude autocorrelation (4). Touch block (57): legacy velocity + pressure dynamics (36) plus v2 additions: pressure derivative (4), contact aspect ratio + area derivative (4), trajectory curvature (3), velocity autocorrelation (3), inter-touch gap distribution (4), path efficiency + per-stroke length (3).
+2. **Extract**: 308 features — speaker block (170): legacy F0 / jitter / shimmer / HNR / formant ratios / LTAS / amplitude (44) plus v3 additions: MFCCs + delta-MFCCs (72 — 12 used coefficients × 4 stats + 12 × 2 deltas, MFCC[0] dropped, pre-emphasis applied), LPC coefficient stats (24), formant absolute trajectories + bandwidths (16), voice quality CPP/tilt/H1-H2/sub-bands (9), pitch contour DCT (5). Motion block (81): legacy jerk + jounce per IMU axis (54) plus v2 additions: cross-axis covariance (6), FFT band energy on accel axes (12), physiological tremor peak (2), direction-reversal stats (3), motion-magnitude autocorrelation (4); desktop captures use mouse-derived analogues for these v2 additions. Touch block (57): legacy velocity + pressure dynamics (36) plus v2 additions: pressure derivative (4), contact aspect ratio + area derivative (4), trajectory curvature (3), velocity autocorrelation (3), inter-touch gap distribution (4), path efficiency + per-stroke length (3).
 3. **Validate**: Feature summaries sent to Entros validation server for server-side analysis
 4. **Hash**: SimHash → 256-bit Temporal Fingerprint → Poseidon commitment
 5. **Prove**: Groth16 proof that new fingerprint is within Hamming distance of previous

package/dist/index.js

@@ -138,6 +138,25 @@ function sdkWarn(...args) {
 
 // src/sensor/audio.ts
 var TARGET_SAMPLE_RATE = 16e3;
+var TARGET_CAPTURE_RMS = 0.05;
+var MIN_RMS_FOR_NORMALIZATION = 1e-4;
+var MAX_NORMALIZATION_GAIN = 50;
+function normalizeCaptureRMS(samples) {
+  if (samples.length === 0) return samples;
+  let sumSq = 0;
+  for (let i = 0; i < samples.length; i++) {
+    const s = samples[i];
+    sumSq += s * s;
+  }
+  const rms = Math.sqrt(sumSq / samples.length);
+  if (rms < MIN_RMS_FOR_NORMALIZATION) return samples;
+  const gain = Math.min(TARGET_CAPTURE_RMS / rms, MAX_NORMALIZATION_GAIN);
+  const out = new Float32Array(samples.length);
+  for (let i = 0; i < samples.length; i++) {
+    out[i] = Math.max(-1, Math.min(1, samples[i] * gain));
+  }
+  return out;
+}
 async function captureAudio(options = {}) {
   const {
     signal,
@@ -225,8 +244,9 @@ async function captureAudio(options = {}) {
         samples.set(chunk, offset);
         offset += chunk.length;
       }
+      const normalized = normalizeCaptureRMS(samples);
       resolve({
-        samples,
+        samples: normalized,
         sampleRate: capturedSampleRate,
         duration: totalLength / capturedSampleRate
       });
@@ -401,6 +421,9 @@ function variance(values, mu) {
   for (const v of values) sum += (v - m) ** 2;
   return sum / (values.length - 1);
 }
+var SKEWNESS_BOUND = 20;
+var KURTOSIS_LOWER = 0;
+var KURTOSIS_UPPER = 50;
 function skewness(values) {
   if (values.length < 3) return 0;
   const n = values.length;
@@ -409,7 +432,8 @@ function skewness(values) {
   if (s === 0) return 0;
   let sum = 0;
   for (const v of values) sum += ((v - m) / s) ** 3;
-  return n / ((n - 1) * (n - 2)) * sum;
+  const raw = n / ((n - 1) * (n - 2)) * sum;
+  return Math.max(-SKEWNESS_BOUND, Math.min(SKEWNESS_BOUND, raw));
 }
 function kurtosis(values) {
   if (values.length < 4) return 0;
@@ -420,7 +444,7 @@ function kurtosis(values) {
   let sum = 0;
   for (const v of values) sum += (v - m) ** 4 / s2 ** 2;
   const k = n * (n + 1) / ((n - 1) * (n - 2) * (n - 3)) * sum - 3 * (n - 1) ** 2 / ((n - 2) * (n - 3));
-  return k;
+  return Math.max(KURTOSIS_LOWER, Math.min(KURTOSIS_UPPER, k));
 }
 function condense(values) {
   const m = mean(values);
@@ -681,9 +705,20 @@ function extractLpcAnalysis(samples, sampleRate, frameSize, hopSize, lpcOrder =
 
 // src/extraction/mfcc.ts
 var NUM_MFCC_COEFFICIENTS = 13;
+var MFCC_DROP_LEADING = 1;
+var NUM_USED_MFCC = NUM_MFCC_COEFFICIENTS - MFCC_DROP_LEADING;
 var DELTA_REGRESSION_HALF_WIDTH = 2;
-var MFCC_FEATURE_COUNT = NUM_MFCC_COEFFICIENTS * 4 + // mean, var, skew, kurt per coefficient
-NUM_MFCC_COEFFICIENTS * 2;
+var MFCC_FEATURE_COUNT = NUM_USED_MFCC * 4 + // mean, var, skew, kurt per coefficient
+NUM_USED_MFCC * 2;
+function applyPreEmphasis(samples) {
+  const out = new Float32Array(samples.length);
+  if (samples.length === 0) return out;
+  out[0] = samples[0];
+  for (let i = 1; i < samples.length; i++) {
+    out[i] = samples[i] - 0.97 * samples[i - 1];
+  }
+  return out;
+}
 function computeDelta(series, halfWidth) {
   const n = series.length;
   const out = new Array(n);
@@ -733,15 +768,16 @@ async function extractMfccFeatures(samples, sampleRate, frameSize, hopSize) {
     return new Array(MFCC_FEATURE_COUNT).fill(0);
   }
   const mfccTracks = Array.from(
-    { length: NUM_MFCC_COEFFICIENTS },
+    { length: NUM_USED_MFCC },
     () => []
   );
   const frame = new Float32Array(frameSize);
   Meyda.bufferSize = frameSize;
   Meyda.sampleRate = sampleRate;
+  const emphasized = applyPreEmphasis(samples);
   for (let i = 0; i < numFrames; i++) {
     const start = i * hopSize;
-    frame.set(samples.subarray(start, start + frameSize), 0);
+    frame.set(emphasized.subarray(start, start + frameSize), 0);
     const result = Meyda.extract("mfcc", frame);
     if (!Array.isArray(result) || result.length !== NUM_MFCC_COEFFICIENTS) {
       continue;
@@ -754,21 +790,21 @@ async function extractMfccFeatures(samples, sampleRate, frameSize, hopSize) {
       }
     }
     if (!allFinite) continue;
-    for (let c = 0; c < NUM_MFCC_COEFFICIENTS; c++) {
-      mfccTracks[c].push(result[c]);
+    for (let c = 0; c < NUM_USED_MFCC; c++) {
+      mfccTracks[c].push(result[c + MFCC_DROP_LEADING]);
     }
   }
   const out = [];
   out.length = MFCC_FEATURE_COUNT;
   let writeIdx = 0;
-  for (let c = 0; c < NUM_MFCC_COEFFICIENTS; c++) {
+  for (let c = 0; c < NUM_USED_MFCC; c++) {
     const stats = condense(mfccTracks[c]);
     out[writeIdx++] = stats.mean;
     out[writeIdx++] = stats.variance;
     out[writeIdx++] = stats.skewness;
     out[writeIdx++] = stats.kurtosis;
   }
-  for (let c = 0; c < NUM_MFCC_COEFFICIENTS; c++) {
+  for (let c = 0; c < NUM_USED_MFCC; c++) {
     const delta = computeDelta(mfccTracks[c], DELTA_REGRESSION_HALF_WIDTH);
     const muDelta = mean(delta);
     out[writeIdx++] = muDelta;
@@ -1287,9 +1323,9 @@ async function extractSpeakerFeaturesDetailed(audio) {
   for (let i = 0; i < numFrames; i++) {
     const start = i * hopSize;
     let sum = 0;
-    const end = Math.min(start + frameSize, samples.length);
+    const end = Math.min(start + frameSize, normalizedSamples.length);
     for (let j = start; j < end; j++) {
-      sum += (samples[j] ?? 0) * (samples[j] ?? 0);
+      sum += (normalizedSamples[j] ?? 0) * (normalizedSamples[j] ?? 0);
     }
     amplitudes.push(Math.sqrt(sum / (end - start)));
   }
@@ -1398,15 +1434,15 @@ async function extractSpeakerFeaturesDetailed(audio) {
     ...ampFeatures,
     // 5     [39..44]  AMPLITUDE
     ...mfccFeatures,
-    // 78    [44..122] MFCC + delta-MFCC
+    // 72    [44..116] MFCC + delta-MFCC (MFCC[0] dropped)
     ...lpcStats,
-    // 24    [122..146] LPC coefficient stats
+    // 24    [116..140] LPC coefficient stats
     ...formantTrajectoryFeatures,
-    // 16    [146..162] Formant absolutes + dynamics + bandwidths
+    // 16    [140..156] Formant absolutes + dynamics + bandwidths
     ...voiceQualityFeatures,
-    // 9     [162..171] Voice quality
+    // 9     [156..165] Voice quality
     ...pitchShapeFeatures
-    // 5     [171..176] Pitch contour shape DCT
+    // 5     [165..170] Pitch contour shape DCT
   ];
   return { features, f0Contour: f0 };
 }
@@ -1932,8 +1968,61 @@ function extractMouseDynamics(samples) {
     angleAutoCorr[2] ?? 0,
     normalizedPathLength
   ];
-  const padding = MOUSE_DYNAMICS_FEATURE_COUNT - legacyMouseDynamics.length;
-  return padding > 0 ? [...legacyMouseDynamics, ...new Array(padding).fill(0)] : legacyMouseDynamics;
+  const v2 = computeMouseV2(samples, vx, vy, accX, accY, speed, acc, jerk, directions);
+  return [...legacyMouseDynamics, ...v2];
+}
+function computeMouseV2(samples, vx, vy, accX, accY, speed, acc, jerk, directions) {
+  const out = [];
+  const covPairs = [
+    [vx, vy],
+    [vx, accX],
+    [vx, accY],
+    [vy, accX],
+    [vy, accY],
+    [accX, accY]
+  ];
+  for (const [a, b] of covPairs) out.push(covariance(a, b));
+  const sampleRate = sampleRateFromTimestamps(samples.map((s) => s.timestamp));
+  const fftSize = nextPow2(Math.max(64, speed.length));
+  const bands = [
+    [0, 2],
+    [2, 6],
+    [6, 12],
+    [12, 30]
+  ];
+  const speedSpectrum = realFFT(meanCenter(speed), fftSize);
+  const accSpectrum = realFFT(meanCenter(acc), fftSize);
+  const jerkSpectrum = realFFT(meanCenter(jerk), fftSize);
+  for (const spectrum of [speedSpectrum, accSpectrum, jerkSpectrum]) {
+    for (const [lo, hi] of bands) {
+      out.push(bandEnergy(spectrum.real, spectrum.imag, sampleRate, lo, hi));
+    }
+  }
+  const tremor = peakInBand(
+    speedSpectrum.real,
+    speedSpectrum.imag,
+    sampleRate,
+    4,
+    12
+  );
+  out.push(tremor.freq, tremor.amplitude);
+  const duration = captureDurationSec(samples);
+  const reversalRates = [vx, vy, speed].map(
+    (channel) => duration > 0 ? signChangeCount(derivative2(channel)) / duration : 0
+  );
+  out.push(mean(reversalRates), variance(reversalRates));
+  let dirAccum = 0;
+  for (let i = 1; i < directions.length; i++) {
+    let diff = directions[i] - directions[i - 1];
+    while (diff > Math.PI) diff -= 2 * Math.PI;
+    while (diff < -Math.PI) diff += 2 * Math.PI;
+    dirAccum += Math.abs(diff);
+  }
+  out.push(directions.length > 1 ? dirAccum / (directions.length - 1) : 0);
+  for (const lag of [1, 5, 10, 25]) {
+    out.push(autocorrelation(speed, lag));
+  }
+  return out.map((v) => Number.isFinite(v) ? v : 0);
 }
 
 // src/hashing/simhash.ts