@iam-protocol/pulse-sdk 0.1.0

package/src/pulse.ts

@@ -0,0 +1,397 @@
+import type { PulseConfig } from "./config";
+import { DEFAULT_THRESHOLD, DEFAULT_CAPTURE_MS } from "./config";
+import type { SensorData, AudioCapture, MotionSample, TouchSample, StageState } from "./sensor/types";
+import type { TBH } from "./hashing/types";
+import type { SolanaProof } from "./proof/types";
+import type { VerificationResult } from "./submit/types";
+import type { StoredVerificationData } from "./identity/types";
+
+import { captureAudio } from "./sensor/audio";
+import { captureMotion } from "./sensor/motion";
+import { captureTouch } from "./sensor/touch";
+import { extractMFCC } from "./extraction/mfcc";
+import {
+  extractMotionFeatures,
+  extractTouchFeatures,
+} from "./extraction/kinematic";
+import { fuseFeatures } from "./extraction/statistics";
+import { simhash } from "./hashing/simhash";
+import { generateTBH } from "./hashing/poseidon";
+import { prepareCircuitInput, generateProof } from "./proof/prover";
+import { serializeProof } from "./proof/serializer";
+import { submitViaWallet } from "./submit/wallet";
+import { submitViaRelayer } from "./submit/relayer";
+import {
+  storeVerificationData,
+  loadVerificationData,
+} from "./identity/anchor";
+
+type ResolvedConfig = Required<Pick<PulseConfig, "cluster" | "threshold">> &
+  PulseConfig;
+
+/**
+ * Extract features from sensor data and fuse into a single vector.
+ */
+function extractFeatures(data: SensorData): number[] {
+  const audioFeatures = data.audio
+    ? extractMFCC(data.audio)
+    : new Array(156).fill(0);
+  const motionFeatures = extractMotionFeatures(data.motion);
+  const touchFeatures = extractTouchFeatures(data.touch);
+  return fuseFeatures(audioFeatures, motionFeatures, touchFeatures);
+}
+
+/**
+ * Shared pipeline: features → simhash → TBH → proof → submit.
+ * Used by both PulseSDK.verify() and PulseSession.complete().
+ */
+async function processSensorData(
+  sensorData: SensorData,
+  config: ResolvedConfig,
+  wallet?: any,
+  connection?: any
+): Promise<VerificationResult> {
+  // Extract features
+  const features = extractFeatures(sensorData);
+
+  // Generate fingerprint via SimHash
+  const fingerprint = simhash(features);
+
+  // Generate TBH (Poseidon commitment)
+  const tbh = await generateTBH(fingerprint);
+
+  // Check for previous verification data
+  const previousData = loadVerificationData();
+  const isFirstVerification = !previousData;
+
+  let solanaProof: SolanaProof | null = null;
+
+  if (!isFirstVerification && previousData) {
+    const previousTBH: TBH = {
+      fingerprint: previousData.fingerprint,
+      salt: BigInt(previousData.salt),
+      commitment: BigInt(previousData.commitment),
+      commitmentBytes: new Uint8Array(32),
+    };
+
+    const circuitInput = prepareCircuitInput(
+      tbh,
+      previousTBH,
+      config.threshold
+    );
+
+    const wasmPath = config.wasmUrl ?? "";
+    const zkeyPath = config.zkeyUrl ?? "";
+
+    const { proof, publicSignals } = await generateProof(
+      circuitInput,
+      wasmPath,
+      zkeyPath
+    );
+
+    solanaProof = serializeProof(proof, publicSignals);
+  }
+
+  // Submit
+  let submission;
+
+  if (wallet && connection) {
+    if (isFirstVerification) {
+      submission = await submitViaWallet(
+        solanaProof ?? { proofBytes: new Uint8Array(0), publicInputs: [] },
+        tbh.commitmentBytes,
+        { wallet, connection, isFirstVerification: true }
+      );
+    } else {
+      submission = await submitViaWallet(solanaProof!, tbh.commitmentBytes, {
+        wallet,
+        connection,
+        isFirstVerification: false,
+      });
+    }
+  } else if (config.relayerUrl) {
+    submission = await submitViaRelayer(
+      solanaProof ?? { proofBytes: new Uint8Array(0), publicInputs: [] },
+      tbh.commitmentBytes,
+      { relayerUrl: config.relayerUrl, isFirstVerification }
+    );
+  } else {
+    return {
+      success: false,
+      commitment: tbh.commitmentBytes,
+      isFirstVerification,
+      error: "No wallet or relayer configured",
+    };
+  }
+
+  // Store verification data locally for next re-verification
+  if (submission.success) {
+    storeVerificationData({
+      fingerprint: tbh.fingerprint,
+      salt: tbh.salt.toString(),
+      commitment: tbh.commitment.toString(),
+      timestamp: Date.now(),
+    });
+  }
+
+  return {
+    success: submission.success,
+    commitment: tbh.commitmentBytes,
+    txSignature: submission.txSignature,
+    isFirstVerification,
+    error: submission.error,
+  };
+}
+
+/**
+ * PulseSession — event-driven staged capture session.
+ *
+ * Gives the caller control over when each sensor stage starts and stops.
+ * After all stages complete, call complete() to run the processing pipeline.
+ *
+ * Usage:
+ *   const session = pulse.createSession(touchElement);
+ *   await session.startAudio();
+ *   // ... user speaks ...
+ *   await session.stopAudio();
+ *   await session.startMotion();
+ *   // ... user holds device ...
+ *   await session.stopMotion();
+ *   await session.startTouch();
+ *   // ... user traces curve ...
+ *   await session.stopTouch();
+ *   const result = await session.complete(wallet, connection);
+ */
+export class PulseSession {
+  private config: ResolvedConfig;
+  private touchElement: HTMLElement | undefined;
+
+  private audioStageState: StageState = "idle";
+  private motionStageState: StageState = "idle";
+  private touchStageState: StageState = "idle";
+
+  private audioController: AbortController | null = null;
+  private motionController: AbortController | null = null;
+  private touchController: AbortController | null = null;
+
+  private audioPromise: Promise<AudioCapture | null> | null = null;
+  private motionPromise: Promise<MotionSample[]> | null = null;
+  private touchPromise: Promise<TouchSample[]> | null = null;
+
+  private audioData: AudioCapture | null = null;
+  private motionData: MotionSample[] = [];
+  private touchData: TouchSample[] = [];
+
+  constructor(config: ResolvedConfig, touchElement?: HTMLElement) {
+    this.config = config;
+    this.touchElement = touchElement;
+  }
+
+  // --- Audio ---
+
+  async startAudio(): Promise<void> {
+    if (this.audioStageState !== "idle")
+      throw new Error("Audio capture already started");
+    this.audioStageState = "capturing";
+    this.audioController = new AbortController();
+    this.audioPromise = captureAudio({
+      signal: this.audioController.signal,
+    }).catch(() => null);
+  }
+
+  async stopAudio(): Promise<AudioCapture | null> {
+    if (this.audioStageState !== "capturing")
+      throw new Error("Audio capture not active");
+    this.audioController!.abort();
+    this.audioData = await this.audioPromise!;
+    this.audioStageState = "captured";
+    return this.audioData;
+  }
+
+  skipAudio(): void {
+    if (this.audioStageState !== "idle")
+      throw new Error("Audio capture already started");
+    this.audioStageState = "skipped";
+  }
+
+  // --- Motion ---
+
+  async startMotion(): Promise<void> {
+    if (this.motionStageState !== "idle")
+      throw new Error("Motion capture already started");
+    this.motionStageState = "capturing";
+    this.motionController = new AbortController();
+    this.motionPromise = captureMotion({
+      signal: this.motionController.signal,
+    }).catch(() => []);
+  }
+
+  async stopMotion(): Promise<MotionSample[]> {
+    if (this.motionStageState !== "capturing")
+      throw new Error("Motion capture not active");
+    this.motionController!.abort();
+    this.motionData = await this.motionPromise!;
+    this.motionStageState = "captured";
+    return this.motionData;
+  }
+
+  skipMotion(): void {
+    if (this.motionStageState !== "idle")
+      throw new Error("Motion capture already started");
+    this.motionStageState = "skipped";
+  }
+
+  // --- Touch ---
+
+  async startTouch(): Promise<void> {
+    if (this.touchStageState !== "idle")
+      throw new Error("Touch capture already started");
+    if (!this.touchElement)
+      throw new Error("No touch element provided to session");
+    this.touchStageState = "capturing";
+    this.touchController = new AbortController();
+    this.touchPromise = captureTouch(this.touchElement, {
+      signal: this.touchController.signal,
+    }).catch(() => []);
+  }
+
+  async stopTouch(): Promise<TouchSample[]> {
+    if (this.touchStageState !== "capturing")
+      throw new Error("Touch capture not active");
+    this.touchController!.abort();
+    this.touchData = await this.touchPromise!;
+    this.touchStageState = "captured";
+    return this.touchData;
+  }
+
+  skipTouch(): void {
+    if (this.touchStageState !== "idle")
+      throw new Error("Touch capture already started");
+    this.touchStageState = "skipped";
+  }
+
+  // --- Complete ---
+
+  async complete(wallet?: any, connection?: any): Promise<VerificationResult> {
+    const active: string[] = [];
+    if (this.audioStageState === "capturing") active.push("audio");
+    if (this.motionStageState === "capturing") active.push("motion");
+    if (this.touchStageState === "capturing") active.push("touch");
+    if (active.length > 0) {
+      throw new Error(
+        `Cannot complete: stages still capturing: ${active.join(", ")}`
+      );
+    }
+
+    const sensorData: SensorData = {
+      audio: this.audioData,
+      motion: this.motionData,
+      touch: this.touchData,
+      modalities: {
+        audio: this.audioData !== null,
+        motion: this.motionData.length > 0,
+        touch: this.touchData.length > 0,
+      },
+    };
+
+    return processSensorData(sensorData, this.config, wallet, connection);
+  }
+}
+
+/**
+ * PulseSDK — main entry point for IAM Protocol verification.
+ *
+ * Two usage modes:
+ *   1. Simple (backward-compatible): pulse.verify(touchElement) — captures all sensors
+ *      for DEFAULT_CAPTURE_MS in parallel, then processes.
+ *   2. Staged (event-driven): pulse.createSession(touchElement) — caller controls
+ *      when each sensor stage starts and stops.
+ */
+export class PulseSDK {
+  private config: ResolvedConfig;
+
+  constructor(config: PulseConfig) {
+    this.config = {
+      threshold: DEFAULT_THRESHOLD,
+      ...config,
+    };
+  }
+
+  /**
+   * Create a staged capture session for event-driven control.
+   */
+  createSession(touchElement?: HTMLElement): PulseSession {
+    return new PulseSession(this.config, touchElement);
+  }
+
+  /**
+   * Run a full verification with automatic timed capture (backward-compatible).
+   * Captures all sensors in parallel for DEFAULT_CAPTURE_MS, then processes.
+   */
+  async verify(
+    touchElement?: HTMLElement,
+    wallet?: any,
+    connection?: any
+  ): Promise<VerificationResult> {
+    try {
+      const session = this.createSession(touchElement);
+      const stopPromises: Promise<void>[] = [];
+
+      // Audio
+      try {
+        await session.startAudio();
+        stopPromises.push(
+          new Promise<void>((r) => setTimeout(r, DEFAULT_CAPTURE_MS)).then(
+            () => {
+              session.stopAudio();
+            }
+          )
+        );
+      } catch {
+        session.skipAudio();
+      }
+
+      // Motion
+      try {
+        await session.startMotion();
+        stopPromises.push(
+          new Promise<void>((r) => setTimeout(r, DEFAULT_CAPTURE_MS)).then(
+            () => {
+              session.stopMotion();
+            }
+          )
+        );
+      } catch {
+        session.skipMotion();
+      }
+
+      // Touch
+      if (touchElement) {
+        try {
+          await session.startTouch();
+          stopPromises.push(
+            new Promise<void>((r) => setTimeout(r, DEFAULT_CAPTURE_MS)).then(
+              () => {
+                session.stopTouch();
+              }
+            )
+          );
+        } catch {
+          session.skipTouch();
+        }
+      } else {
+        session.skipTouch();
+      }
+
+      await Promise.all(stopPromises);
+      return session.complete(wallet, connection);
+    } catch (err: any) {
+      return {
+        success: false,
+        commitment: new Uint8Array(32),
+        isFirstVerification: true,
+        error: err.message ?? String(err),
+      };
+    }
+  }
+}

package/src/sensor/audio.ts

@@ -0,0 +1,94 @@
+import type { AudioCapture, CaptureOptions } from "./types";
+import { MIN_CAPTURE_MS, MAX_CAPTURE_MS } from "../config";
+
+const TARGET_SAMPLE_RATE = 16000;
+
+/**
+ * Capture audio at 16kHz until signaled to stop.
+ * Uses ScriptProcessorNode for raw PCM sample access.
+ *
+ * Stop behavior:
+ * - If signal fires before minDurationMs, capture continues until minimum is reached.
+ * - If signal never fires, capture auto-stops at maxDurationMs.
+ * - If no signal provided, captures for maxDurationMs.
+ */
+export async function captureAudio(
+  options: CaptureOptions = {}
+): Promise<AudioCapture> {
+  const {
+    signal,
+    minDurationMs = MIN_CAPTURE_MS,
+    maxDurationMs = MAX_CAPTURE_MS,
+  } = options;
+
+  const stream = await navigator.mediaDevices.getUserMedia({
+    audio: {
+      sampleRate: TARGET_SAMPLE_RATE,
+      channelCount: 1,
+      echoCancellation: false,
+      noiseSuppression: false,
+      autoGainControl: false,
+    },
+  });
+
+  const ctx = new AudioContext({ sampleRate: TARGET_SAMPLE_RATE });
+  const source = ctx.createMediaStreamSource(stream);
+  const chunks: Float32Array[] = [];
+  const startTime = performance.now();
+
+  return new Promise((resolve) => {
+    let stopped = false;
+    const bufferSize = 4096;
+    const processor = ctx.createScriptProcessor(bufferSize, 1, 1);
+
+    processor.onaudioprocess = (e: AudioProcessingEvent) => {
+      chunks.push(new Float32Array(e.inputBuffer.getChannelData(0)));
+    };
+
+    source.connect(processor);
+    processor.connect(ctx.destination);
+
+    function stopCapture() {
+      if (stopped) return;
+      stopped = true;
+      clearTimeout(maxTimer);
+
+      processor.disconnect();
+      source.disconnect();
+      stream.getTracks().forEach((t: MediaStreamTrack) => t.stop());
+      ctx.close().catch(() => {});
+
+      const totalLength = chunks.reduce((sum, c) => sum + c.length, 0);
+      const samples = new Float32Array(totalLength);
+      let offset = 0;
+      for (const chunk of chunks) {
+        samples.set(chunk, offset);
+        offset += chunk.length;
+      }
+
+      resolve({
+        samples,
+        sampleRate: ctx.sampleRate,
+        duration: totalLength / ctx.sampleRate,
+      });
+    }
+
+    const maxTimer = setTimeout(stopCapture, maxDurationMs);
+
+    if (signal) {
+      if (signal.aborted) {
+        setTimeout(stopCapture, minDurationMs);
+      } else {
+        signal.addEventListener(
+          "abort",
+          () => {
+            const elapsed = performance.now() - startTime;
+            const remaining = Math.max(0, minDurationMs - elapsed);
+            setTimeout(stopCapture, remaining);
+          },
+          { once: true }
+        );
+      }
+    }
+  });
+}

package/src/sensor/motion.ts

@@ -0,0 +1,83 @@
+import type { MotionSample, CaptureOptions } from "./types";
+import { MIN_CAPTURE_MS, MAX_CAPTURE_MS } from "../config";
+
+/**
+ * Request motion sensor permission (required on iOS 13+).
+ * No-op on Android/Chrome where permission is implicit.
+ */
+export async function requestMotionPermission(): Promise<boolean> {
+  const DME = (globalThis as any).DeviceMotionEvent;
+  if (!DME) return false;
+
+  if (typeof DME.requestPermission === "function") {
+    const permission = await DME.requestPermission();
+    return permission === "granted";
+  }
+
+  // Android/Chrome: permission is implicit
+  return true;
+}
+
+/**
+ * Capture accelerometer + gyroscope data until signaled to stop.
+ * Samples at the device's native rate (typically ~60-100Hz).
+ */
+export async function captureMotion(
+  options: CaptureOptions = {}
+): Promise<MotionSample[]> {
+  const {
+    signal,
+    minDurationMs = MIN_CAPTURE_MS,
+    maxDurationMs = MAX_CAPTURE_MS,
+  } = options;
+
+  const hasPermission = await requestMotionPermission();
+  if (!hasPermission) return [];
+
+  const samples: MotionSample[] = [];
+  const startTime = performance.now();
+
+  return new Promise((resolve) => {
+    let stopped = false;
+
+    const handler = (e: DeviceMotionEvent) => {
+      samples.push({
+        timestamp: performance.now(),
+        ax: e.acceleration?.x ?? 0,
+        ay: e.acceleration?.y ?? 0,
+        az: e.acceleration?.z ?? 0,
+        gx: e.rotationRate?.alpha ?? 0,
+        gy: e.rotationRate?.beta ?? 0,
+        gz: e.rotationRate?.gamma ?? 0,
+      });
+    };
+
+    function stopCapture() {
+      if (stopped) return;
+      stopped = true;
+      clearTimeout(maxTimer);
+      window.removeEventListener("devicemotion", handler);
+      resolve(samples);
+    }
+
+    window.addEventListener("devicemotion", handler);
+
+    const maxTimer = setTimeout(stopCapture, maxDurationMs);
+
+    if (signal) {
+      if (signal.aborted) {
+        setTimeout(stopCapture, minDurationMs);
+      } else {
+        signal.addEventListener(
+          "abort",
+          () => {
+            const elapsed = performance.now() - startTime;
+            const remaining = Math.max(0, minDurationMs - elapsed);
+            setTimeout(stopCapture, remaining);
+          },
+          { once: true }
+        );
+      }
+    }
+  });
+}

package/src/sensor/touch.ts

@@ -0,0 +1,65 @@
+import type { TouchSample, CaptureOptions } from "./types";
+import { MIN_CAPTURE_MS, MAX_CAPTURE_MS } from "../config";
+
+/**
+ * Capture touch/pointer data (position, pressure, contact area) until signaled to stop.
+ * Uses PointerEvent for cross-platform support (touch, pen, mouse).
+ */
+export function captureTouch(
+  element: HTMLElement,
+  options: CaptureOptions = {}
+): Promise<TouchSample[]> {
+  const {
+    signal,
+    minDurationMs = MIN_CAPTURE_MS,
+    maxDurationMs = MAX_CAPTURE_MS,
+  } = options;
+
+  const samples: TouchSample[] = [];
+  const startTime = performance.now();
+
+  return new Promise((resolve) => {
+    let stopped = false;
+
+    const handler = (e: PointerEvent) => {
+      samples.push({
+        timestamp: performance.now(),
+        x: e.clientX,
+        y: e.clientY,
+        pressure: e.pressure,
+        width: e.width,
+        height: e.height,
+      });
+    };
+
+    function stopCapture() {
+      if (stopped) return;
+      stopped = true;
+      clearTimeout(maxTimer);
+      element.removeEventListener("pointermove", handler);
+      element.removeEventListener("pointerdown", handler);
+      resolve(samples);
+    }
+
+    element.addEventListener("pointermove", handler);
+    element.addEventListener("pointerdown", handler);
+
+    const maxTimer = setTimeout(stopCapture, maxDurationMs);
+
+    if (signal) {
+      if (signal.aborted) {
+        setTimeout(stopCapture, minDurationMs);
+      } else {
+        signal.addEventListener(
+          "abort",
+          () => {
+            const elapsed = performance.now() - startTime;
+            const remaining = Math.max(0, minDurationMs - elapsed);
+            setTimeout(stopCapture, remaining);
+          },
+          { once: true }
+        );
+      }
+    }
+  });
+}

package/src/sensor/types.ts

@@ -0,0 +1,55 @@
+/** Raw audio samples captured during the Pulse challenge */
+export interface AudioCapture {
+  samples: Float32Array;
+  sampleRate: number;
+  duration: number;
+}
+
+/** Single IMU reading */
+export interface MotionSample {
+  timestamp: number;
+  ax: number;
+  ay: number;
+  az: number;
+  gx: number;
+  gy: number;
+  gz: number;
+}
+
+/** Single touch reading */
+export interface TouchSample {
+  timestamp: number;
+  x: number;
+  y: number;
+  pressure: number;
+  width: number;
+  height: number;
+}
+
+/** Options for event-driven sensor capture */
+export interface CaptureOptions {
+  /** AbortSignal to stop capture. If omitted, captures for maxDurationMs. */
+  signal?: AbortSignal;
+  /** Minimum capture duration in ms. Capture continues until this even if signal fires early. Default: 2000 */
+  minDurationMs?: number;
+  /** Maximum capture duration in ms. Auto-stops if signal hasn't fired. Default: 60000 */
+  maxDurationMs?: number;
+}
+
+/** Stage of a capture session */
+export type CaptureStage = "audio" | "motion" | "touch";
+
+/** State of an individual capture stage */
+export type StageState = "idle" | "capturing" | "captured" | "skipped";
+
+/** Combined sensor data from a Pulse capture session */
+export interface SensorData {
+  audio: AudioCapture | null;
+  motion: MotionSample[];
+  touch: TouchSample[];
+  modalities: {
+    audio: boolean;
+    motion: boolean;
+    touch: boolean;
+  };
+}