@iam-protocol/pulse-sdk 0.2.2 → 0.2.5

package/package.json

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

package/src/challenge/lissajous.ts

@@ -28,11 +28,13 @@ export function randomLissajousParams(): LissajousParams {
     [3, 5],
     [4, 5],
   ];
-  const pair = ratios[Math.floor(Math.random() * ratios.length)]!;
+  const arr = new Uint32Array(2);
+  crypto.getRandomValues(arr);
+  const pair = ratios[arr[0]! % ratios.length]!;
   return {
     a: pair[0]!,
     b: pair[1]!,
-    delta: Math.PI * (0.25 + Math.random() * 0.5),
+    delta: Math.PI * (0.25 + (arr[1]! / 0xFFFFFFFF) * 0.5),
     points: 200,
   };
 }
@@ -67,15 +69,25 @@ export function generateLissajousSequence(
     [1, 3], [2, 5], [5, 6], [3, 7], [4, 7],
   ];
 
-  const shuffled = [...allRatios].sort(() => Math.random() - 0.5);
+  // Fisher-Yates shuffle with crypto randomness
+  const shuffled = [...allRatios];
+  for (let i = shuffled.length - 1; i > 0; i--) {
+    const arr = new Uint32Array(1);
+    crypto.getRandomValues(arr);
+    const j = arr[0]! % (i + 1);
+    [shuffled[i], shuffled[j]] = [shuffled[j]!, shuffled[i]!];
+  }
+
   const sequence: { params: LissajousParams; points: Point2D[] }[] = [];
 
   for (let i = 0; i < count; i++) {
     const pair = shuffled[i % shuffled.length]!;
+    const deltaArr = new Uint32Array(1);
+    crypto.getRandomValues(deltaArr);
     const params: LissajousParams = {
       a: pair[0],
       b: pair[1],
-      delta: Math.PI * (0.1 + Math.random() * 0.8),
+      delta: Math.PI * (0.1 + (deltaArr[0]! / 0xFFFFFFFF) * 0.8),
       points: 200,
     };
     sequence.push({ params, points: generateLissajousPoints(params) });

package/src/challenge/phrase.ts

@@ -10,18 +10,25 @@ const SYLLABLES = [
   "fu", "gu", "ku", "lu", "mu", "nu", "pu", "ru", "su", "tu",
 ];
 
+/** Cryptographically random integer in [0, max) */
+function secureRandom(max: number): number {
+  const arr = new Uint32Array(1);
+  crypto.getRandomValues(arr);
+  return arr[0]! % max;
+}
+
 /**
  * Generate a random phonetically-balanced phrase for the voice challenge.
  * Each phrase is 5-6 syllable pairs, forming nonsensical but speakable words.
+ * Uses crypto.getRandomValues for unpredictable challenge generation.
  */
 export function generatePhrase(wordCount: number = 5): string {
   const words: string[] = [];
   for (let w = 0; w < wordCount; w++) {
-    const syllableCount = 2 + Math.floor(Math.random() * 2);
+    const syllableCount = 2 + secureRandom(2);
     let word = "";
     for (let s = 0; s < syllableCount; s++) {
-      const idx = Math.floor(Math.random() * SYLLABLES.length);
-      word += SYLLABLES[idx];
+      word += SYLLABLES[secureRandom(SYLLABLES.length)];
     }
     words.push(word);
   }
@@ -48,10 +55,10 @@ export function generatePhraseSequence(
 
     const words: string[] = [];
     for (let w = 0; w < wordCount; w++) {
-      const syllableCount = 2 + Math.floor(Math.random() * 2);
+      const syllableCount = 2 + secureRandom(2);
       let word = "";
       for (let s = 0; s < syllableCount; s++) {
-        word += subset[Math.floor(Math.random() * subset.length)];
+        word += subset[secureRandom(subset.length)];
       }
       words.push(word);
     }

package/src/config.ts

@@ -35,6 +35,7 @@ export interface PulseConfig {
   cluster: "devnet" | "mainnet-beta" | "localnet";
   rpcEndpoint?: string;
   relayerUrl?: string;
+  relayerApiKey?: string;
   zkeyUrl?: string;
   wasmUrl?: string;
   threshold?: number;

package/src/extraction/mfcc.ts

@@ -6,6 +6,20 @@ const FRAME_SIZE = 400; // 25ms at 16kHz
 const HOP_SIZE = 160; // 10ms hop
 const NUM_MFCC = 13;
 
+// Dynamic import cache for Meyda (works in both browser and Node.js)
+let meydaModule: any = null;
+
+async function getMeyda(): Promise<any> {
+  if (!meydaModule) {
+    try {
+      meydaModule = await import("meyda");
+    } catch {
+      return null;
+    }
+  }
+  return meydaModule.default ?? meydaModule;
+}
+
 /**
  * Extract MFCC features from audio data.
  * Computes 13 MFCCs per frame, plus delta and delta-delta coefficients,
@@ -13,21 +27,22 @@ const NUM_MFCC = 13;
  *
  * Returns: 13 coefficients × 3 (raw + delta + delta-delta) × 4 stats + 13 entropy values = 169 values
  */
-export function extractMFCC(audio: AudioCapture): number[] {
+export async function extractMFCC(audio: AudioCapture): Promise<number[]> {
   const { samples, sampleRate } = audio;
 
-  // Lazy import of Meyda (browser/Node compatible)
-  let Meyda: any;
-  try {
-    Meyda = require("meyda");
-  } catch {
-    // Meyda not available — return zeros (fallback for environments without it)
+  const Meyda = await getMeyda();
+  if (!Meyda) {
+    // Meyda genuinely unavailable — this is a real problem, not a silent fallback
+    console.warn("[IAM SDK] Meyda library failed to load. Audio features will be zeros.");
     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 + NUM_MFCC).fill(0);
+  if (numFrames < 3) {
+    console.warn(`[IAM SDK] Too few audio frames (${numFrames}). Need at least 3.`);
+    return new Array(NUM_MFCC * 3 * 4 + NUM_MFCC).fill(0);
+  }
 
   const mfccFrames: number[][] = [];
 
@@ -50,7 +65,7 @@ export function extractMFCC(audio: AudioCapture): number[] {
     }
   }
 
-  if (mfccFrames.length < 3) return new Array(NUM_MFCC * 3 * 4).fill(0);
+  if (mfccFrames.length < 3) return new Array(NUM_MFCC * 3 * 4 + NUM_MFCC).fill(0);
 
   // Compute delta (1st derivative) and delta-delta (2nd derivative)
   const deltaFrames = computeDeltas(mfccFrames);
@@ -60,7 +75,6 @@ export function extractMFCC(audio: AudioCapture): number[] {
   const features: number[] = [];
 
   for (let c = 0; c < NUM_MFCC; c++) {
-    // Raw MFCC coefficient c across all frames
     const raw = mfccFrames.map((f) => f[c] ?? 0);
     const stats = condense(raw);
     features.push(stats.mean, stats.variance, stats.skewness, stats.kurtosis);
@@ -78,8 +92,7 @@ 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.
+  // Entropy per MFCC coefficient
   for (let c = 0; c < NUM_MFCC; c++) {
     const raw = mfccFrames.map((f) => f[c] ?? 0);
     features.push(entropy(raw));

package/src/hashing/simhash.ts

@@ -52,11 +52,20 @@ function getHyperplanes(dimension: number): number[][] {
  * Uses deterministic random hyperplanes seeded from the protocol constant.
  * Similar feature vectors produce fingerprints with low Hamming distance.
  */
+const EXPECTED_FEATURE_DIMENSION = 259; // 169 audio + 54 motion + 36 touch
+
 export function simhash(features: number[]): TemporalFingerprint {
   if (features.length === 0) {
     return new Array(FINGERPRINT_BITS).fill(0);
   }
 
+  if (features.length !== EXPECTED_FEATURE_DIMENSION) {
+    console.warn(
+      `[IAM SDK] Feature vector has ${features.length} dimensions, expected ${EXPECTED_FEATURE_DIMENSION}. ` +
+      `Fingerprint quality may be degraded.`
+    );
+  }
+
   const planes = getHyperplanes(features.length);
   const fingerprint: TemporalFingerprint = [];
 

package/src/proof/serializer.ts

@@ -41,6 +41,12 @@ export function serializeProof(
   proof: RawProof,
   publicSignals: string[]
 ): SolanaProof {
+  if (publicSignals.length !== NUM_PUBLIC_INPUTS) {
+    throw new Error(
+      `Expected ${NUM_PUBLIC_INPUTS} public signals, got ${publicSignals.length}`
+    );
+  }
+
   // proof_a: x (32 bytes) + negated y (32 bytes)
   const a0 = toBigEndian32(proof.pi_a[0]!);
   const a1 = negateG1Y(proof.pi_a[1]!);

package/src/pulse.ts

@@ -16,7 +16,7 @@ import {
 } from "./extraction/kinematic";
 import { fuseFeatures } from "./extraction/statistics";
 import { simhash } from "./hashing/simhash";
-import { generateTBH } from "./hashing/poseidon";
+import { generateTBH, bigintToBytes32 } from "./hashing/poseidon";
 import { prepareCircuitInput, generateProof } from "./proof/prover";
 import { serializeProof } from "./proof/serializer";
 import { submitViaWallet } from "./submit/wallet";
@@ -32,9 +32,9 @@ type ResolvedConfig = Required<Pick<PulseConfig, "cluster" | "threshold">> &
 /**
  * Extract features from sensor data and fuse into a single vector.
  */
-function extractFeatures(data: SensorData): number[] {
+async function extractFeatures(data: SensorData): Promise<number[]> {
   const audioFeatures = data.audio
-    ? extractMFCC(data.audio)
+    ? await extractMFCC(data.audio)
     : new Array(169).fill(0);
   const motionFeatures = extractMotionFeatures(data.motion);
   const touchFeatures = extractTouchFeatures(data.touch);
@@ -45,14 +45,47 @@ function extractFeatures(data: SensorData): number[] {
  * Shared pipeline: features → simhash → TBH → proof → submit.
  * Used by both PulseSDK.verify() and PulseSession.complete().
  */
+// Minimum sample counts for meaningful feature extraction
+const MIN_AUDIO_SAMPLES = 16000; // ~1 second at 16kHz
+const MIN_MOTION_SAMPLES = 10;
+const MIN_TOUCH_SAMPLES = 10;
+
 async function processSensorData(
   sensorData: SensorData,
   config: ResolvedConfig,
   wallet?: any,
   connection?: any
 ): Promise<VerificationResult> {
+  // Data quality gate: reject if insufficient behavioral data captured
+  const audioSamples = sensorData.audio?.samples.length ?? 0;
+  const motionSamples = sensorData.motion.length;
+  const touchSamples = sensorData.touch.length;
+
+  // Need at least audio OR (motion + touch) to produce a meaningful fingerprint
+  const hasAudio = audioSamples >= MIN_AUDIO_SAMPLES;
+  const hasMotion = motionSamples >= MIN_MOTION_SAMPLES;
+  const hasTouch = touchSamples >= MIN_TOUCH_SAMPLES;
+
+  if (!hasAudio && !hasMotion && !hasTouch) {
+    return {
+      success: false,
+      commitment: new Uint8Array(32),
+      isFirstVerification: true,
+      error: "Insufficient behavioral data. Please speak the phrase and trace the curve during capture.",
+    };
+  }
+
+  if (!hasAudio) {
+    return {
+      success: false,
+      commitment: new Uint8Array(32),
+      isFirstVerification: true,
+      error: "No voice data detected. Please speak the phrase clearly during capture.",
+    };
+  }
+
   // Extract features
-  const features = extractFeatures(sensorData);
+  const features = await extractFeatures(sensorData);
 
   // Generate fingerprint via SimHash
   const fingerprint = simhash(features);
@@ -71,7 +104,7 @@ async function processSensorData(
       fingerprint: previousData.fingerprint,
       salt: BigInt(previousData.salt),
       commitment: BigInt(previousData.commitment),
-      commitmentBytes: new Uint8Array(32),
+      commitmentBytes: bigintToBytes32(BigInt(previousData.commitment)),
     };
 
     const circuitInput = prepareCircuitInput(
@@ -80,8 +113,17 @@ async function processSensorData(
       config.threshold
     );
 
-    const wasmPath = config.wasmUrl ?? "";
-    const zkeyPath = config.zkeyUrl ?? "";
+    const wasmPath = config.wasmUrl;
+    const zkeyPath = config.zkeyUrl;
+
+    if (!wasmPath || !zkeyPath) {
+      return {
+        success: false,
+        commitment: tbh.commitmentBytes,
+        isFirstVerification: false,
+        error: "wasmUrl and zkeyUrl must be configured for re-verification proof generation",
+      };
+    }
 
     const { proof, publicSignals } = await generateProof(
       circuitInput,
@@ -113,7 +155,7 @@ async function processSensorData(
     submission = await submitViaRelayer(
       solanaProof ?? { proofBytes: new Uint8Array(0), publicInputs: [] },
       tbh.commitmentBytes,
-      { relayerUrl: config.relayerUrl, isFirstVerification }
+      { relayerUrl: config.relayerUrl, apiKey: config.relayerApiKey, isFirstVerification }
     );
   } else {
     return {

package/src/sensor/audio.ts

@@ -33,6 +33,7 @@ export async function captureAudio(
   });
 
   const ctx = new AudioContext({ sampleRate: TARGET_SAMPLE_RATE });
+  const capturedSampleRate = ctx.sampleRate;
   const source = ctx.createMediaStreamSource(stream);
   const chunks: Float32Array[] = [];
   const startTime = performance.now();
@@ -76,8 +77,8 @@ export async function captureAudio(
 
       resolve({
         samples,
-        sampleRate: ctx.sampleRate,
-        duration: totalLength / ctx.sampleRate,
+        sampleRate: capturedSampleRate,
+        duration: totalLength / capturedSampleRate,
       });
     }
 

package/src/submit/relayer.ts

@@ -1,12 +1,12 @@
 import type { SolanaProof } from "../proof/types";
 import type { SubmissionResult } from "./types";
 
+const RELAYER_TIMEOUT_MS = 30_000;
+
 /**
  * Submit a proof via the IAM relayer API (walletless mode).
  * The relayer submits the on-chain transaction using the integrator's funded account.
  * The user needs no wallet, no SOL, no crypto knowledge.
- *
- * In Phase 3, the relayer endpoint is configurable (stub until executor-node in Phase 4).
  */
 export async function submitViaRelayer(
   proof: SolanaProof,
@@ -33,12 +33,18 @@ export async function submitViaRelayer(
       headers["X-API-Key"] = options.apiKey;
     }
 
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), RELAYER_TIMEOUT_MS);
+
     const response = await fetch(options.relayerUrl, {
       method: "POST",
       headers,
       body: JSON.stringify(body),
+      signal: controller.signal,
     });
 
+    clearTimeout(timer);
+
     if (!response.ok) {
       const errorText = await response.text();
       return { success: false, error: `Relayer error: ${response.status} ${errorText}` };
@@ -48,11 +54,19 @@ export async function submitViaRelayer(
       success?: boolean;
       tx_signature?: string;
     };
+
+    if (result.success !== true) {
+      return { success: false, error: "Relayer returned unsuccessful response" };
+    }
+
     return {
-      success: result.success ?? true,
+      success: true,
       txSignature: result.tx_signature,
     };
   } catch (err: any) {
+    if (err.name === "AbortError") {
+      return { success: false, error: "Relayer request timed out" };
+    }
     return { success: false, error: err.message ?? String(err) };
   }
 }

package/src/submit/wallet.ts

@@ -97,7 +97,11 @@ export async function submitViaWallet(
 
     // 3. Mint or update anchor
     const anchorIdl = await anchor.Program.fetchIdl(anchorProgramId, provider);
-    if (anchorIdl) {
+    if (!anchorIdl) {
+      return { success: false, error: "Failed to fetch IAM Anchor program IDL" };
+    }
+
+    {
       const anchorProgram: any = new anchor.Program(anchorIdl, provider);
 
       if (options.isFirstVerification) {