@entros/pulse-sdk 1.5.3 → 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 134 statistical features, 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).
 
@@ -32,7 +32,7 @@ if (result.success) {
 
 ### Walletless (liveness-check tier)
 
-For non-crypto users. No wallet, no SOL required. The integrator optionally funds verifications via the relayer API.
+For liveness checking without wallet onboarding. The integrator optionally funds verifications via the relayer API. Submits proofs to chain through the relayer; **does not issue SAS attestations** — for SAS attestations bound to a verified wallet, use the wallet-connected path above.
 
 ```typescript
 import { PulseSDK } from '@entros/pulse-sdk';
@@ -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**: 134 features — speaker (F0, jitter, shimmer, HNR, formants, LTAS), motion (jerk/jounce), touch (velocity/pressure)
+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.d.mts

@@ -356,7 +356,7 @@ declare function fuseFeatures(audio: number[], motion: number[], touch: number[]
  *   amplitude statistics (5)
  */
 
-declare const SPEAKER_FEATURE_COUNT = 44;
+declare const SPEAKER_FEATURE_COUNT: number;
 /**
  * Extract speaker-dependent audio features.
  *
@@ -394,18 +394,41 @@ declare function extractSpeakerFeatures(audio: AudioCapture): Promise<number[]>;
 declare function extractAccelerationMagnitude(samples: MotionSample[], targetFrameCount: number): number[];
 /**
  * Extract kinematic features from motion (IMU) data.
- * Computes jerk (3rd derivative) and jounce (4th derivative) of acceleration,
- * then condenses each axis into statistics.
  *
- * Returns: ~54 values (6 axes × 2 derivatives × 4 stats + 6 jitter variance values)
+ * Layout (`MOTION_FEATURE_COUNT = 81`):
+ *   `[0..48)`  legacy: 6 axes × (jerk stats 4 + jounce stats 4)
+ *   `[48..54)` legacy: jitter variance per axis (6)
+ *   `[54..60)` v2:    cross-axis covariance (6 selected pairs)
+ *   `[60..72)` v2:    FFT band energy in {0-2, 2-6, 6-12, 12-30} Hz × {ax, ay, az}
+ *   `[72..74)` v2:    physiological tremor peak frequency + amplitude (4-12 Hz)
+ *   `[74..76)` v2:    direction-reversal rate per axis: mean, variance across {ax, ay, az}
+ *   `[76]`     v2:    mean angular velocity (|gyro| over the capture)
+ *   `[77..81)` v2:    motion-magnitude autocorrelation at lags {1, 5, 10, 25}
+ *
+ * @privacyGuarantee Operates on already-on-device IMU samples and emits
+ * statistical / spectral aggregates (variances, covariances, band sums,
+ * autocorrelation scalars). The full sample stream is never transmitted.
  */
 declare function extractMotionFeatures(samples: MotionSample[]): number[];
 /**
  * Extract kinematic features from touch data.
- * Computes velocity and acceleration of touch coordinates,
- * plus pressure and area statistics.
  *
- * Returns: ~36 values (32 base + 4 jitter variance for x, y, pressure, area)
+ * Layout (`TOUCH_FEATURE_COUNT = 57`):
+ *   `[0..32)`  legacy: velocity / accel / pressure / area / jerk stats (32)
+ *   `[32..36)` legacy: jitter variance for {vx, vy, pressure, area} (4)
+ *   `[36..40)` v2:    pressure first-derivative stats (mean, var, skew, kurt)
+ *   `[40..42)` v2:    contact aspect-ratio stats (mean, var)
+ *   `[42..44)` v2:    contact-area first-derivative stats (mean, var)
+ *   `[44..47)` v2:    trajectory curvature stats (mean, var, skew)
+ *   `[47..50)` v2:    velocity autocorrelation at lags {1, 3, 5}
+ *   `[50..54)` v2:    inter-touch gap duration stats (mean, var, skew, kurt)
+ *   `[54]`     v2:    path efficiency (straight-line / total path length)
+ *   `[55..57)` v2:    per-stroke total path length: mean, variance
+ *
+ * @privacyGuarantee Operates on already-on-device touch samples and emits
+ * statistical aggregates only. The full coordinate stream is never
+ * transmitted; downstream phase-content (e.g. typed text) is not
+ * recoverable from the per-stroke summaries.
  */
 declare function extractTouchFeatures(samples: TouchSample[]): number[];
 /**
@@ -413,7 +436,10 @@ declare function extractTouchFeatures(samples: TouchSample[]): number[];
  * 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)
+ * Returns: `MOUSE_DYNAMICS_FEATURE_COUNT` (= `MOTION_FEATURE_COUNT`) values.
+ * The first 54 entries are the legacy mouse-dynamics signal; the trailing
+ * v2-block slots stay zero on desktop so the per-modality bit-influence
+ * share matches a mobile IMU capture under the new pipeline.
  */
 declare function extractMouseDynamics(samples: TouchSample[]): number[];
 

package/dist/index.d.ts

@@ -356,7 +356,7 @@ declare function fuseFeatures(audio: number[], motion: number[], touch: number[]
  *   amplitude statistics (5)
  */
 
-declare const SPEAKER_FEATURE_COUNT = 44;
+declare const SPEAKER_FEATURE_COUNT: number;
 /**
  * Extract speaker-dependent audio features.
  *
@@ -394,18 +394,41 @@ declare function extractSpeakerFeatures(audio: AudioCapture): Promise<number[]>;
 declare function extractAccelerationMagnitude(samples: MotionSample[], targetFrameCount: number): number[];
 /**
  * Extract kinematic features from motion (IMU) data.
- * Computes jerk (3rd derivative) and jounce (4th derivative) of acceleration,
- * then condenses each axis into statistics.
  *
- * Returns: ~54 values (6 axes × 2 derivatives × 4 stats + 6 jitter variance values)
+ * Layout (`MOTION_FEATURE_COUNT = 81`):
+ *   `[0..48)`  legacy: 6 axes × (jerk stats 4 + jounce stats 4)
+ *   `[48..54)` legacy: jitter variance per axis (6)
+ *   `[54..60)` v2:    cross-axis covariance (6 selected pairs)
+ *   `[60..72)` v2:    FFT band energy in {0-2, 2-6, 6-12, 12-30} Hz × {ax, ay, az}
+ *   `[72..74)` v2:    physiological tremor peak frequency + amplitude (4-12 Hz)
+ *   `[74..76)` v2:    direction-reversal rate per axis: mean, variance across {ax, ay, az}
+ *   `[76]`     v2:    mean angular velocity (|gyro| over the capture)
+ *   `[77..81)` v2:    motion-magnitude autocorrelation at lags {1, 5, 10, 25}
+ *
+ * @privacyGuarantee Operates on already-on-device IMU samples and emits
+ * statistical / spectral aggregates (variances, covariances, band sums,
+ * autocorrelation scalars). The full sample stream is never transmitted.
  */
 declare function extractMotionFeatures(samples: MotionSample[]): number[];
 /**
  * Extract kinematic features from touch data.
- * Computes velocity and acceleration of touch coordinates,
- * plus pressure and area statistics.
  *
- * Returns: ~36 values (32 base + 4 jitter variance for x, y, pressure, area)
+ * Layout (`TOUCH_FEATURE_COUNT = 57`):
+ *   `[0..32)`  legacy: velocity / accel / pressure / area / jerk stats (32)
+ *   `[32..36)` legacy: jitter variance for {vx, vy, pressure, area} (4)
+ *   `[36..40)` v2:    pressure first-derivative stats (mean, var, skew, kurt)
+ *   `[40..42)` v2:    contact aspect-ratio stats (mean, var)
+ *   `[42..44)` v2:    contact-area first-derivative stats (mean, var)
+ *   `[44..47)` v2:    trajectory curvature stats (mean, var, skew)
+ *   `[47..50)` v2:    velocity autocorrelation at lags {1, 3, 5}
+ *   `[50..54)` v2:    inter-touch gap duration stats (mean, var, skew, kurt)
+ *   `[54]`     v2:    path efficiency (straight-line / total path length)
+ *   `[55..57)` v2:    per-stroke total path length: mean, variance
+ *
+ * @privacyGuarantee Operates on already-on-device touch samples and emits
+ * statistical aggregates only. The full coordinate stream is never
+ * transmitted; downstream phase-content (e.g. typed text) is not
+ * recoverable from the per-stroke summaries.
  */
 declare function extractTouchFeatures(samples: TouchSample[]): number[];
 /**
@@ -413,7 +436,10 @@ declare function extractTouchFeatures(samples: TouchSample[]): number[];
  * 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)
+ * Returns: `MOUSE_DYNAMICS_FEATURE_COUNT` (= `MOTION_FEATURE_COUNT`) values.
+ * The first 54 entries are the legacy mouse-dynamics signal; the trailing
+ * v2-block slots stay zero on desktop so the per-modality bit-influence
+ * share matches a mobile IMU capture under the new pipeline.
  */
 declare function extractMouseDynamics(samples: TouchSample[]): number[];