@iam-protocol/pulse-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 IAM Protocol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,59 @@
+# @iam-protocol/pulse-sdk
+
+Client-side SDK for the IAM Protocol. Captures behavioral biometrics (voice, motion, touch), generates a Temporal-Biometric Hash, produces a Groth16 zero-knowledge proof, and submits it for on-chain verification on Solana.
+
+## Install
+
+```bash
+npm install @iam-protocol/pulse-sdk
+```
+
+## Usage
+
+```typescript
+import { PulseSDK } from '@iam-protocol/pulse-sdk';
+
+const pulse = new PulseSDK({
+  cluster: 'devnet',
+  relayerUrl: 'https://api.iam-human.io/relay', // walletless mode
+  wasmUrl: '/circuits/iam_hamming.wasm',
+  zkeyUrl: '/circuits/iam_hamming_final.zkey',
+});
+
+// Verify (captures sensors, generates proof, submits)
+const result = await pulse.verify(touchElement);
+
+if (result.success) {
+  console.log('Verified:', result.txSignature);
+}
+```
+
+### Wallet-connected mode
+
+```typescript
+import { PulseSDK } from '@iam-protocol/pulse-sdk';
+
+const pulse = new PulseSDK({ cluster: 'devnet' });
+const result = await pulse.verify(touchElement, walletAdapter, connection);
+```
+
+## Pipeline
+
+1. **Capture**: Audio (16kHz), IMU (accelerometer + gyroscope), touch (pressure + area) — event-driven, caller controls duration
+2. **Extract**: MFCC (voice), jerk/jounce (motion), velocity/pressure (touch)
+3. **Hash**: SimHash → 256-bit Temporal Fingerprint → Poseidon commitment
+4. **Prove**: Groth16 proof that new fingerprint is within Hamming distance of previous
+5. **Submit**: On-chain verification via wallet or relayer
+
+## Development
+
+```bash
+npm install
+npm test          # 31 vitest tests
+npm run build     # ESM + CJS output
+npm run typecheck # TypeScript strict mode
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,376 @@
+declare const FINGERPRINT_BITS = 256;
+declare const DEFAULT_THRESHOLD = 30;
+declare const MIN_CAPTURE_MS = 2000;
+declare const MAX_CAPTURE_MS = 60000;
+declare const DEFAULT_CAPTURE_MS = 7000;
+declare const PROGRAM_IDS: {
+    readonly iamAnchor: "GZYwTp2ozeuRA5Gof9vs4ya961aANcJBdUzB7LN6q4b2";
+    readonly iamVerifier: "4F97jNoxQzT2qRbkWpW3ztC3Nz2TtKj3rnKG8ExgnrfV";
+    readonly iamRegistry: "6VBs3zr9KrfFPGd6j7aGBPQWwZa5tajVfA7HN6MMV9VW";
+};
+interface PulseConfig {
+    cluster: "devnet" | "mainnet-beta" | "localnet";
+    rpcEndpoint?: string;
+    relayerUrl?: string;
+    zkeyUrl?: string;
+    wasmUrl?: string;
+    threshold?: number;
+}
+
+/** Raw audio samples captured during the Pulse challenge */
+interface AudioCapture {
+    samples: Float32Array;
+    sampleRate: number;
+    duration: number;
+}
+/** Single IMU reading */
+interface MotionSample {
+    timestamp: number;
+    ax: number;
+    ay: number;
+    az: number;
+    gx: number;
+    gy: number;
+    gz: number;
+}
+/** Single touch reading */
+interface TouchSample {
+    timestamp: number;
+    x: number;
+    y: number;
+    pressure: number;
+    width: number;
+    height: number;
+}
+/** Options for event-driven sensor capture */
+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 */
+type CaptureStage = "audio" | "motion" | "touch";
+/** State of an individual capture stage */
+type StageState = "idle" | "capturing" | "captured" | "skipped";
+/** Combined sensor data from a Pulse capture session */
+interface SensorData {
+    audio: AudioCapture | null;
+    motion: MotionSample[];
+    touch: TouchSample[];
+    modalities: {
+        audio: boolean;
+        motion: boolean;
+        touch: boolean;
+    };
+}
+
+/** Result of a verification submission */
+interface SubmissionResult {
+    success: boolean;
+    txSignature?: string;
+    error?: string;
+}
+/** Result of a full Pulse verification */
+interface VerificationResult {
+    success: boolean;
+    commitment: Uint8Array;
+    txSignature?: string;
+    isFirstVerification: boolean;
+    error?: string;
+}
+
+type ResolvedConfig = Required<Pick<PulseConfig, "cluster" | "threshold">> & PulseConfig;
+/**
+ * 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);
+ */
+declare class PulseSession {
+    private config;
+    private touchElement;
+    private audioStageState;
+    private motionStageState;
+    private touchStageState;
+    private audioController;
+    private motionController;
+    private touchController;
+    private audioPromise;
+    private motionPromise;
+    private touchPromise;
+    private audioData;
+    private motionData;
+    private touchData;
+    constructor(config: ResolvedConfig, touchElement?: HTMLElement);
+    startAudio(): Promise<void>;
+    stopAudio(): Promise<AudioCapture | null>;
+    skipAudio(): void;
+    startMotion(): Promise<void>;
+    stopMotion(): Promise<MotionSample[]>;
+    skipMotion(): void;
+    startTouch(): Promise<void>;
+    stopTouch(): Promise<TouchSample[]>;
+    skipTouch(): void;
+    complete(wallet?: any, connection?: any): Promise<VerificationResult>;
+}
+/**
+ * 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.
+ */
+declare class PulseSDK {
+    private config;
+    constructor(config: PulseConfig);
+    /**
+     * Create a staged capture session for event-driven control.
+     */
+    createSession(touchElement?: HTMLElement): PulseSession;
+    /**
+     * Run a full verification with automatic timed capture (backward-compatible).
+     * Captures all sensors in parallel for DEFAULT_CAPTURE_MS, then processes.
+     */
+    verify(touchElement?: HTMLElement, wallet?: any, connection?: any): Promise<VerificationResult>;
+}
+
+/** 256-bit Temporal Fingerprint as an array of 0/1 values */
+type TemporalFingerprint = number[];
+/** Temporal-Biometric Hash: commitment + data needed for re-verification */
+interface TBH {
+    fingerprint: TemporalFingerprint;
+    salt: bigint;
+    commitment: bigint;
+    commitmentBytes: Uint8Array;
+}
+/** Packed field elements from bit packing (2 × 128-bit) */
+interface PackedFingerprint {
+    lo: bigint;
+    hi: bigint;
+}
+
+/**
+ * Compute a 256-bit SimHash fingerprint from a feature vector.
+ * Uses deterministic random hyperplanes seeded from the protocol constant.
+ * Similar feature vectors produce fingerprints with low Hamming distance.
+ */
+declare function simhash(features: number[]): TemporalFingerprint;
+/**
+ * Compute Hamming distance between two fingerprints.
+ */
+declare function hammingDistance(a: TemporalFingerprint, b: TemporalFingerprint): number;
+
+/**
+ * Pack 256-bit fingerprint into two 128-bit field elements.
+ * Little-endian bit ordering within each chunk (matches circuit's Bits2Num).
+ */
+declare function packBits(fingerprint: TemporalFingerprint): PackedFingerprint;
+/**
+ * Compute Poseidon commitment: Poseidon(pack_lo, pack_hi, salt).
+ * Matches the circuit's CommitmentCheck template exactly.
+ */
+declare function computeCommitment(fingerprint: TemporalFingerprint, salt: bigint): Promise<bigint>;
+/**
+ * Generate a random salt within the BN254 scalar field.
+ */
+declare function generateSalt(): bigint;
+/**
+ * Convert a BigInt to a 32-byte big-endian Uint8Array.
+ */
+declare function bigintToBytes32(n: bigint): Uint8Array;
+/**
+ * Generate a complete TBH from a fingerprint.
+ */
+declare function generateTBH(fingerprint: TemporalFingerprint, salt?: bigint): Promise<TBH>;
+
+/** Statistical summary of a time series */
+interface StatsSummary {
+    mean: number;
+    variance: number;
+    skewness: number;
+    kurtosis: number;
+}
+/** Feature vector from all sensor modalities */
+interface FeatureVector {
+    audio: number[];
+    motion: number[];
+    touch: number[];
+}
+/** Concatenated feature vector for SimHash input */
+type FusedFeatureVector = number[];
+
+declare function mean(values: number[]): number;
+declare function variance(values: number[], mu?: number): number;
+declare function skewness(values: number[]): number;
+declare function kurtosis(values: number[]): number;
+declare function condense(values: number[]): StatsSummary;
+declare function fuseFeatures(audio: number[], motion: number[], touch: number[]): number[];
+
+/** Serialized proof ready for on-chain submission */
+interface SolanaProof {
+    proofBytes: Uint8Array;
+    publicInputs: Uint8Array[];
+}
+/** Raw snarkjs proof output */
+interface RawProof {
+    pi_a: string[];
+    pi_b: string[][];
+    pi_c: string[];
+    protocol: string;
+    curve: string;
+}
+/** Circuit input for proof generation */
+interface CircuitInput {
+    ft_new: number[];
+    ft_prev: number[];
+    salt_new: string;
+    salt_prev: string;
+    commitment_new: string;
+    commitment_prev: string;
+    threshold: string;
+}
+/** Proof generation result */
+interface ProofResult {
+    proof: RawProof;
+    publicSignals: string[];
+}
+
+/**
+ * Convert a decimal string to a 32-byte big-endian Uint8Array.
+ */
+declare function toBigEndian32(decStr: string): Uint8Array;
+/**
+ * Serialize an snarkjs proof into the 256-byte format groth16-solana expects.
+ *
+ * proof_a: 64 bytes (x + negated y)
+ * proof_b: 128 bytes (G2 with reversed coordinate ordering: c1 before c0)
+ * proof_c: 64 bytes (x + y)
+ */
+declare function serializeProof(proof: RawProof, publicSignals: string[]): SolanaProof;
+
+/**
+ * Prepare circuit input from current and previous TBH data.
+ */
+declare function prepareCircuitInput(current: TBH, previous: TBH, threshold?: number): CircuitInput;
+/**
+ * Generate a Groth16 proof for the Hamming distance circuit.
+ *
+ * @param input - Circuit input (fingerprints, salts, commitments, threshold)
+ * @param wasmPath - Path or URL to iam_hamming.wasm
+ * @param zkeyPath - Path or URL to iam_hamming_final.zkey
+ */
+declare function generateProof(input: CircuitInput, wasmPath: string, zkeyPath: string): Promise<ProofResult>;
+/**
+ * Generate a proof and serialize it for Solana submission.
+ */
+declare function generateSolanaProof(current: TBH, previous: TBH, wasmPath: string, zkeyPath: string, threshold?: number): Promise<SolanaProof>;
+
+/**
+ * Submit a proof on-chain via a connected wallet (wallet-connected mode).
+ * Uses Anchor SDK to construct and send the transaction.
+ *
+ * Flow: create_challenge → verify_proof → update_anchor (or mint_anchor for first time)
+ */
+declare function submitViaWallet(proof: SolanaProof, commitment: Uint8Array, options: {
+    wallet: any;
+    connection: any;
+    isFirstVerification: boolean;
+    trustScore?: number;
+}): Promise<SubmissionResult>;
+
+/**
+ * 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).
+ */
+declare function submitViaRelayer(proof: SolanaProof, commitment: Uint8Array, options: {
+    relayerUrl: string;
+    apiKey?: string;
+    isFirstVerification: boolean;
+}): Promise<SubmissionResult>;
+
+/** On-chain identity state (mirrors the Anchor program's IdentityState) */
+interface IdentityState {
+    owner: string;
+    creationTimestamp: number;
+    lastVerificationTimestamp: number;
+    verificationCount: number;
+    trustScore: number;
+    currentCommitment: Uint8Array;
+    mint: string;
+}
+/** Local storage of previous verification data (needed for re-verification) */
+interface StoredVerificationData {
+    fingerprint: number[];
+    salt: string;
+    commitment: string;
+    timestamp: number;
+}
+
+/**
+ * Fetch identity state from the on-chain IdentityState PDA.
+ */
+declare function fetchIdentityState(walletPubkey: string, connection: any): Promise<IdentityState | null>;
+/**
+ * Store verification data locally for re-verification.
+ * Uses localStorage (browser) or in-memory fallback (Node.js).
+ */
+declare function storeVerificationData(data: StoredVerificationData): void;
+/**
+ * Load previously stored verification data.
+ */
+declare function loadVerificationData(): StoredVerificationData | null;
+
+/**
+ * Generate a random phonetically-balanced phrase for the voice challenge.
+ * Each phrase is 5-6 syllable pairs, forming nonsensical but speakable words.
+ */
+declare function generatePhrase(wordCount?: number): string;
+
+/**
+ * Generate Lissajous curve points for the touch tracing challenge.
+ * The user traces this shape on screen while speaking the phrase.
+ *
+ * x(t) = A * sin(a*t + delta)
+ * y(t) = B * sin(b*t)
+ */
+interface LissajousParams {
+    a: number;
+    b: number;
+    delta: number;
+    points: number;
+}
+interface Point2D {
+    x: number;
+    y: number;
+}
+/**
+ * Generate random Lissajous parameters for a challenge.
+ */
+declare function randomLissajousParams(): LissajousParams;
+/**
+ * Generate Lissajous curve points normalized to [0, 1] range.
+ */
+declare function generateLissajousPoints(params: LissajousParams): Point2D[];
+
+export { type AudioCapture, type CaptureOptions, type CaptureStage, type CircuitInput, DEFAULT_CAPTURE_MS, DEFAULT_THRESHOLD, FINGERPRINT_BITS, type FeatureVector, type FusedFeatureVector, type IdentityState, type LissajousParams, MAX_CAPTURE_MS, MIN_CAPTURE_MS, type MotionSample, PROGRAM_IDS, type PackedFingerprint, type Point2D, type ProofResult, type PulseConfig, PulseSDK, PulseSession, type SensorData, type SolanaProof, type StageState, type StatsSummary, type StoredVerificationData, type SubmissionResult, type TBH, type TemporalFingerprint, type TouchSample, type VerificationResult, bigintToBytes32, computeCommitment, condense, fetchIdentityState, fuseFeatures, generateLissajousPoints, generatePhrase, generateProof, generateSalt, generateSolanaProof, generateTBH, hammingDistance, kurtosis, loadVerificationData, mean, packBits, prepareCircuitInput, randomLissajousParams, serializeProof, simhash, skewness, storeVerificationData, submitViaRelayer, submitViaWallet, toBigEndian32, variance };