@entros/pulse-sdk 1.5.2 → 2.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 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.
 
 > **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**: 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).
 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

@@ -134,8 +134,8 @@ interface VerificationResult {
      * Server-side safe-reveal (validator → executor → SDK):
      *   - `variance_floor`, `entropy_bounds`, `temporal_coupling_low`,
      *     `phrase_content_mismatch`
-     *   Surfaced for the soft-reject + retry UX (master-list #94) so the
-     *   UI can render a per-category hint.
+     *   Surfaced for the soft-reject + retry UX so the UI can render a
+     *   per-category hint.
      *
      * Client-side (SDK-emitted):
      *   - `validation_unavailable` — the relayer's `/validate-features`
@@ -356,21 +356,21 @@ 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.
  *
- * Captures physiological vocal characteristics (F0, jitter, shimmer, HNR, formant
- * ratios) that are stable across different utterances from the same speaker.
- * Content-independent by design — different phrases produce similar feature values.
+ * Captures physiological vocal characteristics that are stable across
+ * different utterances from the same speaker. Content-independent by
+ * design — different phrases produce similar feature values.
  *
  * Returns 44 values.
  */
 /**
  * Extracts 44 speaker features AND the raw F0 contour.
- * The F0 contour is surfaced so Tier 2 cross-modal temporal analysis can be
- * performed server-side against the motion time-series. Feature vector shape
- * and semantics are unchanged.
+ * The F0 contour is surfaced so server-side analysis can pair it with
+ * the motion time-series. Feature vector shape and semantics are
+ * unchanged.
  */
 declare function extractSpeakerFeaturesDetailed(audio: AudioCapture): Promise<{
     features: number[];
@@ -379,33 +379,56 @@ declare function extractSpeakerFeaturesDetailed(audio: AudioCapture): Promise<{
 /**
  * Extracts 44 speaker features. Backward-compatible wrapper that discards
  * the F0 contour; use `extractSpeakerFeaturesDetailed` when the contour is
- * needed (e.g. for Tier 2 server-side cross-modal analysis).
+ * needed (e.g. for server-side analysis).
  */
 declare function extractSpeakerFeatures(audio: AudioCapture): Promise<number[]>;
 
 /**
  * Compute per-sample acceleration magnitude |a| = √(ax² + ay² + az²) and
- * linearly resample to a target frame count. Used for Tier 2 cross-modal
- * temporal analysis against the F0 contour; the two time-series must share
- * the same frame count for direct correlation.
+ * linearly resample to a target frame count. Surfaced for server-side
+ * analysis paired against the F0 contour; the two time-series must share
+ * the same frame count when consumed downstream.
  *
  * Returns an empty array if motion data is absent or too short.
  */
 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[];
 
@@ -513,9 +539,8 @@ declare function submitViaWallet(proof: SolanaProof, commitment: Uint8Array, opt
  * and sets a 7-day cooldown before the next reset.
  *
  * Transaction shape: single instruction (no challenge / verify_proof /
- * ZK proof required). Humanness evidence comes from the Tier 1
- * validation pipeline invoked at the /attest step (same as mint and
- * update).
+ * ZK proof required). Humanness evidence comes from the validation
+ * pipeline invoked at the /attest step (same as mint and update).
  */
 declare function submitResetViaWallet(commitment: Uint8Array, options: {
     wallet: any;
@@ -659,8 +684,8 @@ declare function loadVerificationData(): Promise<StoredVerificationData | null>;
  * FALLBACK challenge-phrase generator. Used only when the executor's
  * `/challenge` endpoint is unreachable; the authoritative phrase comes from
  * the server (5 real words drawn from a curated English-word dictionary). On
- * this fallback path, validation skips server-side phrase content binding —
- * Tier 1 acoustic + Tier 2 cross-modal still run.
+ * this fallback path, validation skips the phrase verification step —
+ * other server-side checks still run.
  *
  * Output is 5-6 syllable pairs, forming nonsensical but speakable words.
  * Uses crypto.getRandomValues for unpredictable challenge generation.
@@ -711,16 +736,14 @@ declare function generateLissajousSequence(count?: number): {
  *
  * The executor's `/challenge` endpoint returns a fresh nonce + 5-word phrase
  * bound to the wallet for a short TTL (default 60s). The phrase is drawn from
- * a curated English-word dictionary (source of truth at
- * `entros-validation/src/word_dict.rs`); shown to the user as the voice challenge
+ * a curated English-word dictionary, shown to the user as the voice challenge
  * and looked up server-side at `/validate-features` to verify the audio
- * matches the issued phrase (master-list #89, phrase content binding).
+ * matches the issued phrase.
  *
- * Server-issued phrases are the only safe design for content binding: if the
- * client generated the phrase and sent it to the server alongside the audio,
- * an attacker would submit their own phrase matching whatever content they
- * captured. With server issuance, the phrase is bound to the nonce and the
- * client cannot substitute it.
+ * Server-issued phrases are the only safe design here: if the client generated
+ * the phrase and sent it to the server alongside the audio, an attacker would
+ * submit their own phrase matching whatever content they captured. With server
+ * issuance, the phrase is bound to the nonce and the client cannot substitute it.
  */
 /**
  * Server-issued challenge artifacts. Returned by `fetchChallenge`.
@@ -745,13 +768,13 @@ declare function fetchChallenge(executorUrl: string, walletAddress: string, apiK
 
 /**
  * Encode captured Float32 audio samples as base64 int16 PCM for transmission
- * to the validation service (master-list #89 phrase content binding).
+ * to the validation service.
  *
  * Audio is captured as `Float32Array` with values in `[-1.0, 1.0]` by the
- * Pulse SDK (`sensor/audio.ts`). The validation service's phrase-binding
- * module decodes base64 → Vec<i16> → Vec<f32> before feeding Whisper-tiny.
- * int16 is the standard compact representation: 2 bytes per sample vs 4 for
- * f32, halving wire size without perceptible quality loss for 16kHz speech.
+ * Pulse SDK (`sensor/audio.ts`). The validation service decodes the base64
+ * payload and feeds the audio into server-side transcription. int16 is the
+ * standard compact representation: 2 bytes per sample vs 4 for f32, halving
+ * wire size without perceptible quality loss for 16kHz speech.
  *
  * Byte layout: little-endian int16 samples, contiguous, no header.
  */

package/dist/index.d.ts

@@ -134,8 +134,8 @@ interface VerificationResult {
      * Server-side safe-reveal (validator → executor → SDK):
      *   - `variance_floor`, `entropy_bounds`, `temporal_coupling_low`,
      *     `phrase_content_mismatch`
-     *   Surfaced for the soft-reject + retry UX (master-list #94) so the
-     *   UI can render a per-category hint.
+     *   Surfaced for the soft-reject + retry UX so the UI can render a
+     *   per-category hint.
      *
      * Client-side (SDK-emitted):
      *   - `validation_unavailable` — the relayer's `/validate-features`
@@ -356,21 +356,21 @@ 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.
  *
- * Captures physiological vocal characteristics (F0, jitter, shimmer, HNR, formant
- * ratios) that are stable across different utterances from the same speaker.
- * Content-independent by design — different phrases produce similar feature values.
+ * Captures physiological vocal characteristics that are stable across
+ * different utterances from the same speaker. Content-independent by
+ * design — different phrases produce similar feature values.
  *
  * Returns 44 values.
  */
 /**
  * Extracts 44 speaker features AND the raw F0 contour.
- * The F0 contour is surfaced so Tier 2 cross-modal temporal analysis can be
- * performed server-side against the motion time-series. Feature vector shape
- * and semantics are unchanged.
+ * The F0 contour is surfaced so server-side analysis can pair it with
+ * the motion time-series. Feature vector shape and semantics are
+ * unchanged.
  */
 declare function extractSpeakerFeaturesDetailed(audio: AudioCapture): Promise<{
     features: number[];
@@ -379,33 +379,56 @@ declare function extractSpeakerFeaturesDetailed(audio: AudioCapture): Promise<{
 /**
  * Extracts 44 speaker features. Backward-compatible wrapper that discards
  * the F0 contour; use `extractSpeakerFeaturesDetailed` when the contour is
- * needed (e.g. for Tier 2 server-side cross-modal analysis).
+ * needed (e.g. for server-side analysis).
  */
 declare function extractSpeakerFeatures(audio: AudioCapture): Promise<number[]>;
 
 /**
  * Compute per-sample acceleration magnitude |a| = √(ax² + ay² + az²) and
- * linearly resample to a target frame count. Used for Tier 2 cross-modal
- * temporal analysis against the F0 contour; the two time-series must share
- * the same frame count for direct correlation.
+ * linearly resample to a target frame count. Surfaced for server-side
+ * analysis paired against the F0 contour; the two time-series must share
+ * the same frame count when consumed downstream.
  *
  * Returns an empty array if motion data is absent or too short.
  */
 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[];
 
@@ -513,9 +539,8 @@ declare function submitViaWallet(proof: SolanaProof, commitment: Uint8Array, opt
  * and sets a 7-day cooldown before the next reset.
  *
  * Transaction shape: single instruction (no challenge / verify_proof /
- * ZK proof required). Humanness evidence comes from the Tier 1
- * validation pipeline invoked at the /attest step (same as mint and
- * update).
+ * ZK proof required). Humanness evidence comes from the validation
+ * pipeline invoked at the /attest step (same as mint and update).
  */
 declare function submitResetViaWallet(commitment: Uint8Array, options: {
     wallet: any;
@@ -659,8 +684,8 @@ declare function loadVerificationData(): Promise<StoredVerificationData | null>;
  * FALLBACK challenge-phrase generator. Used only when the executor's
  * `/challenge` endpoint is unreachable; the authoritative phrase comes from
  * the server (5 real words drawn from a curated English-word dictionary). On
- * this fallback path, validation skips server-side phrase content binding —
- * Tier 1 acoustic + Tier 2 cross-modal still run.
+ * this fallback path, validation skips the phrase verification step —
+ * other server-side checks still run.
  *
  * Output is 5-6 syllable pairs, forming nonsensical but speakable words.
  * Uses crypto.getRandomValues for unpredictable challenge generation.
@@ -711,16 +736,14 @@ declare function generateLissajousSequence(count?: number): {
  *
  * The executor's `/challenge` endpoint returns a fresh nonce + 5-word phrase
  * bound to the wallet for a short TTL (default 60s). The phrase is drawn from
- * a curated English-word dictionary (source of truth at
- * `entros-validation/src/word_dict.rs`); shown to the user as the voice challenge
+ * a curated English-word dictionary, shown to the user as the voice challenge
  * and looked up server-side at `/validate-features` to verify the audio
- * matches the issued phrase (master-list #89, phrase content binding).
+ * matches the issued phrase.
  *
- * Server-issued phrases are the only safe design for content binding: if the
- * client generated the phrase and sent it to the server alongside the audio,
- * an attacker would submit their own phrase matching whatever content they
- * captured. With server issuance, the phrase is bound to the nonce and the
- * client cannot substitute it.
+ * Server-issued phrases are the only safe design here: if the client generated
+ * the phrase and sent it to the server alongside the audio, an attacker would
+ * submit their own phrase matching whatever content they captured. With server
+ * issuance, the phrase is bound to the nonce and the client cannot substitute it.
  */
 /**
  * Server-issued challenge artifacts. Returned by `fetchChallenge`.
@@ -745,13 +768,13 @@ declare function fetchChallenge(executorUrl: string, walletAddress: string, apiK
 
 /**
  * Encode captured Float32 audio samples as base64 int16 PCM for transmission
- * to the validation service (master-list #89 phrase content binding).
+ * to the validation service.
  *
  * Audio is captured as `Float32Array` with values in `[-1.0, 1.0]` by the
- * Pulse SDK (`sensor/audio.ts`). The validation service's phrase-binding
- * module decodes base64 → Vec<i16> → Vec<f32> before feeding Whisper-tiny.
- * int16 is the standard compact representation: 2 bytes per sample vs 4 for
- * f32, halving wire size without perceptible quality loss for 16kHz speech.
+ * Pulse SDK (`sensor/audio.ts`). The validation service decodes the base64
+ * payload and feeds the audio into server-side transcription. int16 is the
+ * standard compact representation: 2 bytes per sample vs 4 for f32, halving
+ * wire size without perceptible quality loss for 16kHz speech.
  *
  * Byte layout: little-endian int16 samples, contiguous, no header.
  */