@entros/pulse-sdk 1.0.0 → 1.1.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 IAM Protocol
+Copyright (c) 2026 Entros 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

package/README.md

@@ -38,8 +38,8 @@ import { PulseSDK } from '@entros/pulse-sdk';
 const pulse = new PulseSDK({
   cluster: 'devnet',
   relayerUrl: 'https://api.entros.io/relay',
-  wasmUrl: '/circuits/iam_hamming.wasm',
-  zkeyUrl: '/circuits/iam_hamming_final.zkey',
+  wasmUrl: '/circuits/entros_hamming.wasm',
+  zkeyUrl: '/circuits/entros_hamming_final.zkey',
 });
 
 const result = await pulse.verify(touchElement);

package/dist/index.d.mts

@@ -95,6 +95,13 @@ interface VerificationResult {
 }
 
 type ResolvedConfig = Required<Pick<PulseConfig, "cluster" | "threshold">> & PulseConfig;
+/**
+ * Shared pipeline: features → simhash → TBH → proof → submit.
+ * Used by both PulseSDK.verify() and PulseSession.complete().
+ */
+declare const MIN_AUDIO_SAMPLES = 16000;
+declare const MIN_MOTION_SAMPLES = 10;
+declare const MIN_TOUCH_SAMPLES = 10;
 /**
  * PulseSession — event-driven staged capture session.
  *
@@ -402,8 +409,8 @@ declare function prepareCircuitInput(current: TBH, previous: TBH, threshold?: nu
  * 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
+ * @param wasmPath - Path or URL to entros_hamming.wasm
+ * @param zkeyPath - Path or URL to entros_hamming_final.zkey
  */
 declare function generateProof(input: CircuitInput, wasmPath: string, zkeyPath: string): Promise<ProofResult>;
 /**
@@ -512,7 +519,7 @@ declare function attestAgentOperator(agentAsset: string, options: {
 /**
  * Query whether an AI agent has a verified human operator via Entros.
  *
- * Reads the "iam:human-operator" metadata from the agent's on-chain record
+ * Reads the "entros:human-operator" metadata from the agent's on-chain record
  * and returns the operator's Entros Anchor details.
  *
  * @param agentAsset - Base58 pubkey of the agent's Metaplex Core NFT
@@ -562,8 +569,13 @@ declare function storeVerificationData(data: StoredVerificationData): Promise<vo
 declare function loadVerificationData(): Promise<StoredVerificationData | null>;
 
 /**
- * Generate a random phonetically-balanced phrase for the voice challenge.
- * Each phrase is 5-6 syllable pairs, forming nonsensical but speakable words.
+ * 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.
+ *
+ * Output is 5-6 syllable pairs, forming nonsensical but speakable words.
  * Uses crypto.getRandomValues for unpredictable challenge generation.
  */
 declare function generatePhrase(wordCount?: number): string;
@@ -610,11 +622,12 @@ declare function generateLissajousSequence(count?: number): {
 /**
  * Fetch the server-issued challenge from the executor.
  *
- * The executor's `/challenge` endpoint returns a fresh nonce + nonsense phrase
- * bound to the wallet for a short TTL (default 60s). The phrase is shown to
- * the user as the voice challenge and is looked up server-side at
- * `/validate-features` to run phoneme-distance matching against the submitted
- * audio (master-list #89, phrase content binding via STT).
+ * 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
+ * and looked up server-side at `/validate-features` to verify the audio
+ * matches the issued phrase (master-list #89, phrase content binding).
  *
  * 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,
@@ -628,7 +641,7 @@ declare function generateLissajousSequence(count?: number): {
 interface ChallengeResponse {
     /** 32-byte nonce used for on-chain `create_challenge` and the `/attest` handshake. */
     nonce: Uint8Array;
-    /** Nonsense phrase (5 space-separated words of 2-3 syllables each) the user must speak aloud. */
+    /** Server-issued 5-word challenge phrase (drawn from a curated English-word dictionary) the user must speak aloud. */
     phrase: string;
     /** Nonce TTL in seconds (default 60). */
     expiresIn: number;
@@ -662,4 +675,4 @@ declare function fetchChallenge(executorUrl: string, walletAddress: string, apiK
  */
 declare function encodeAudioAsBase64(samples: Float32Array): string;
 
-export { type AgentHumanOperator, type AudioCapture, type CaptureOptions, type CaptureStage, type ChallengeResponse, type CircuitInput, DEFAULT_CAPTURE_MS, DEFAULT_MIN_DISTANCE, DEFAULT_THRESHOLD, type EntrosAttestation, 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, SPEAKER_FEATURE_COUNT, type SensorData, type SolanaProof, type StageState, type StatsSummary, type StoredVerificationData, type SubmissionResult, type TBH, type TemporalFingerprint, type TouchSample, type VerificationResult, attestAgentOperator, autocorrelation, bigintToBytes32, computeCommitment, condense, encodeAudioAsBase64, entropy, extractAccelerationMagnitude, extractMotionFeatures, extractMouseDynamics, extractSpeakerFeatures, extractSpeakerFeaturesDetailed, extractTouchFeatures, fetchChallenge, fetchIdentityState, fuseFeatures, fuseRawFeatures, generateLissajousPoints, generateLissajousSequence, generatePhrase, generatePhraseSequence, generateProof, generateSalt, generateSolanaProof, generateTBH, getAgentHumanOperator, hammingDistance, kurtosis, loadVerificationData, mean, packBits, prepareCircuitInput, randomLissajousParams, serializeProof, simhash, skewness, storeVerificationData, submitResetViaWallet, submitViaRelayer, submitViaWallet, toBigEndian32, variance, verifyEntrosAttestation };
+export { type AgentHumanOperator, type AudioCapture, type CaptureOptions, type CaptureStage, type ChallengeResponse, type CircuitInput, DEFAULT_CAPTURE_MS, DEFAULT_MIN_DISTANCE, DEFAULT_THRESHOLD, type EntrosAttestation, FINGERPRINT_BITS, type FeatureVector, type FusedFeatureVector, type IdentityState, type LissajousParams, MAX_CAPTURE_MS, MIN_AUDIO_SAMPLES, MIN_CAPTURE_MS, MIN_MOTION_SAMPLES, MIN_TOUCH_SAMPLES, type MotionSample, PROGRAM_IDS, type PackedFingerprint, type Point2D, type ProofResult, type PulseConfig, PulseSDK, PulseSession, SPEAKER_FEATURE_COUNT, type SensorData, type SolanaProof, type StageState, type StatsSummary, type StoredVerificationData, type SubmissionResult, type TBH, type TemporalFingerprint, type TouchSample, type VerificationResult, attestAgentOperator, autocorrelation, bigintToBytes32, computeCommitment, condense, encodeAudioAsBase64, entropy, extractAccelerationMagnitude, extractMotionFeatures, extractMouseDynamics, extractSpeakerFeatures, extractSpeakerFeaturesDetailed, extractTouchFeatures, fetchChallenge, fetchIdentityState, fuseFeatures, fuseRawFeatures, generateLissajousPoints, generateLissajousSequence, generatePhrase, generatePhraseSequence, generateProof, generateSalt, generateSolanaProof, generateTBH, getAgentHumanOperator, hammingDistance, kurtosis, loadVerificationData, mean, packBits, prepareCircuitInput, randomLissajousParams, serializeProof, simhash, skewness, storeVerificationData, submitResetViaWallet, submitViaRelayer, submitViaWallet, toBigEndian32, variance, verifyEntrosAttestation };

package/dist/index.d.ts

@@ -95,6 +95,13 @@ interface VerificationResult {
 }
 
 type ResolvedConfig = Required<Pick<PulseConfig, "cluster" | "threshold">> & PulseConfig;
+/**
+ * Shared pipeline: features → simhash → TBH → proof → submit.
+ * Used by both PulseSDK.verify() and PulseSession.complete().
+ */
+declare const MIN_AUDIO_SAMPLES = 16000;
+declare const MIN_MOTION_SAMPLES = 10;
+declare const MIN_TOUCH_SAMPLES = 10;
 /**
  * PulseSession — event-driven staged capture session.
  *
@@ -402,8 +409,8 @@ declare function prepareCircuitInput(current: TBH, previous: TBH, threshold?: nu
  * 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
+ * @param wasmPath - Path or URL to entros_hamming.wasm
+ * @param zkeyPath - Path or URL to entros_hamming_final.zkey
  */
 declare function generateProof(input: CircuitInput, wasmPath: string, zkeyPath: string): Promise<ProofResult>;
 /**
@@ -512,7 +519,7 @@ declare function attestAgentOperator(agentAsset: string, options: {
 /**
  * Query whether an AI agent has a verified human operator via Entros.
  *
- * Reads the "iam:human-operator" metadata from the agent's on-chain record
+ * Reads the "entros:human-operator" metadata from the agent's on-chain record
  * and returns the operator's Entros Anchor details.
  *
  * @param agentAsset - Base58 pubkey of the agent's Metaplex Core NFT
@@ -562,8 +569,13 @@ declare function storeVerificationData(data: StoredVerificationData): Promise<vo
 declare function loadVerificationData(): Promise<StoredVerificationData | null>;
 
 /**
- * Generate a random phonetically-balanced phrase for the voice challenge.
- * Each phrase is 5-6 syllable pairs, forming nonsensical but speakable words.
+ * 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.
+ *
+ * Output is 5-6 syllable pairs, forming nonsensical but speakable words.
  * Uses crypto.getRandomValues for unpredictable challenge generation.
  */
 declare function generatePhrase(wordCount?: number): string;
@@ -610,11 +622,12 @@ declare function generateLissajousSequence(count?: number): {
 /**
  * Fetch the server-issued challenge from the executor.
  *
- * The executor's `/challenge` endpoint returns a fresh nonce + nonsense phrase
- * bound to the wallet for a short TTL (default 60s). The phrase is shown to
- * the user as the voice challenge and is looked up server-side at
- * `/validate-features` to run phoneme-distance matching against the submitted
- * audio (master-list #89, phrase content binding via STT).
+ * 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
+ * and looked up server-side at `/validate-features` to verify the audio
+ * matches the issued phrase (master-list #89, phrase content binding).
  *
  * 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,
@@ -628,7 +641,7 @@ declare function generateLissajousSequence(count?: number): {
 interface ChallengeResponse {
     /** 32-byte nonce used for on-chain `create_challenge` and the `/attest` handshake. */
     nonce: Uint8Array;
-    /** Nonsense phrase (5 space-separated words of 2-3 syllables each) the user must speak aloud. */
+    /** Server-issued 5-word challenge phrase (drawn from a curated English-word dictionary) the user must speak aloud. */
     phrase: string;
     /** Nonce TTL in seconds (default 60). */
     expiresIn: number;
@@ -662,4 +675,4 @@ declare function fetchChallenge(executorUrl: string, walletAddress: string, apiK
  */
 declare function encodeAudioAsBase64(samples: Float32Array): string;
 
-export { type AgentHumanOperator, type AudioCapture, type CaptureOptions, type CaptureStage, type ChallengeResponse, type CircuitInput, DEFAULT_CAPTURE_MS, DEFAULT_MIN_DISTANCE, DEFAULT_THRESHOLD, type EntrosAttestation, 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, SPEAKER_FEATURE_COUNT, type SensorData, type SolanaProof, type StageState, type StatsSummary, type StoredVerificationData, type SubmissionResult, type TBH, type TemporalFingerprint, type TouchSample, type VerificationResult, attestAgentOperator, autocorrelation, bigintToBytes32, computeCommitment, condense, encodeAudioAsBase64, entropy, extractAccelerationMagnitude, extractMotionFeatures, extractMouseDynamics, extractSpeakerFeatures, extractSpeakerFeaturesDetailed, extractTouchFeatures, fetchChallenge, fetchIdentityState, fuseFeatures, fuseRawFeatures, generateLissajousPoints, generateLissajousSequence, generatePhrase, generatePhraseSequence, generateProof, generateSalt, generateSolanaProof, generateTBH, getAgentHumanOperator, hammingDistance, kurtosis, loadVerificationData, mean, packBits, prepareCircuitInput, randomLissajousParams, serializeProof, simhash, skewness, storeVerificationData, submitResetViaWallet, submitViaRelayer, submitViaWallet, toBigEndian32, variance, verifyEntrosAttestation };
+export { type AgentHumanOperator, type AudioCapture, type CaptureOptions, type CaptureStage, type ChallengeResponse, type CircuitInput, DEFAULT_CAPTURE_MS, DEFAULT_MIN_DISTANCE, DEFAULT_THRESHOLD, type EntrosAttestation, FINGERPRINT_BITS, type FeatureVector, type FusedFeatureVector, type IdentityState, type LissajousParams, MAX_CAPTURE_MS, MIN_AUDIO_SAMPLES, MIN_CAPTURE_MS, MIN_MOTION_SAMPLES, MIN_TOUCH_SAMPLES, type MotionSample, PROGRAM_IDS, type PackedFingerprint, type Point2D, type ProofResult, type PulseConfig, PulseSDK, PulseSession, SPEAKER_FEATURE_COUNT, type SensorData, type SolanaProof, type StageState, type StatsSummary, type StoredVerificationData, type SubmissionResult, type TBH, type TemporalFingerprint, type TouchSample, type VerificationResult, attestAgentOperator, autocorrelation, bigintToBytes32, computeCommitment, condense, encodeAudioAsBase64, entropy, extractAccelerationMagnitude, extractMotionFeatures, extractMouseDynamics, extractSpeakerFeatures, extractSpeakerFeaturesDetailed, extractTouchFeatures, fetchChallenge, fetchIdentityState, fuseFeatures, fuseRawFeatures, generateLissajousPoints, generateLissajousSequence, generatePhrase, generatePhraseSequence, generateProof, generateSalt, generateSolanaProof, generateTBH, getAgentHumanOperator, hammingDistance, kurtosis, loadVerificationData, mean, packBits, prepareCircuitInput, randomLissajousParams, serializeProof, simhash, skewness, storeVerificationData, submitResetViaWallet, submitViaRelayer, submitViaWallet, toBigEndian32, variance, verifyEntrosAttestation };

package/dist/index.js

@@ -35,7 +35,10 @@ __export(index_exports, {
   DEFAULT_THRESHOLD: () => DEFAULT_THRESHOLD,
   FINGERPRINT_BITS: () => FINGERPRINT_BITS,
   MAX_CAPTURE_MS: () => MAX_CAPTURE_MS,
+  MIN_AUDIO_SAMPLES: () => MIN_AUDIO_SAMPLES,
   MIN_CAPTURE_MS: () => MIN_CAPTURE_MS,
+  MIN_MOTION_SAMPLES: () => MIN_MOTION_SAMPLES,
+  MIN_TOUCH_SAMPLES: () => MIN_TOUCH_SAMPLES,
   PROGRAM_IDS: () => PROGRAM_IDS,
   PulseSDK: () => PulseSDK,
   PulseSession: () => PulseSession,
@@ -113,7 +116,7 @@ var PROGRAM_IDS = {
 var AGENT_REGISTRY_CONFIG = {
   programIdDevnet: "8oo4J9tBB3Hna1jRQ3rWvJjojqM5DYTDJo5cejUuJy3C",
   programIdMainnet: "8oo4dC4JvBLwy5tGgiH3WwK4B9PWxL9Z4XjA2jzkQMbQ",
-  metadataKey: "iam:human-operator"
+  metadataKey: "entros:human-operator"
 };
 var SAS_CONFIG = {
   programId: "22zoJMtdu4tQc2PzL74ZUT7FrwgB1Udec8DdW4yw4BdG",
@@ -2115,7 +2118,7 @@ async function processSensorData(sensorData, config, wallet, connection, onProgr
         success: false,
         commitment: tbh.commitmentBytes,
         isFirstVerification: false,
-        error: "Re-verification requires wasmUrl and zkeyUrl in PulseConfig. Host the iam_hamming.wasm and iam_hamming_final.zkey circuit artifacts at public URLs."
+        error: "Re-verification requires wasmUrl and zkeyUrl in PulseConfig. Host the entros_hamming.wasm and entros_hamming_final.zkey circuit artifacts at public URLs."
       };
     }
     try {
@@ -2403,6 +2406,116 @@ var PulseSession = class {
       );
     this.touchStageState = "skipped";
   }
+  // --- Test hooks (internal builds only) ---
+  /**
+   * @internal Test-only. Primes the session with pre-captured sensor data,
+   * bypassing browser capture APIs. Throws unless built with IAM_INTERNAL_TEST=1.
+   * Stripped from the published .d.ts so npm consumers never see it. Used by the
+   * red team harness to drive the real verification pipeline (extraction →
+   * SimHash → TBH → proof → submit) against synthetic sensor data — never
+   * available to npm consumers.
+   */
+  __injectSensorData(data) {
+    if (true) {
+      throw new Error(
+        "PulseSession.__injectSensorData is only available in internal test builds. Set IAM_INTERNAL_TEST=1 when building pulse-sdk from source."
+      );
+    }
+    const conflicts = [];
+    if (this.audioStageState === "capturing") conflicts.push("audio");
+    if (this.motionStageState === "capturing") conflicts.push("motion");
+    if (this.touchStageState === "capturing") conflicts.push("touch");
+    if (conflicts.length > 0) {
+      throw new Error(
+        `__injectSensorData: cannot inject while stages are capturing: ${conflicts.join(", ")}. Create a fresh session via sdk.createSession() and inject before any startAudio/startMotion/startTouch call.`
+      );
+    }
+    if (!data.audio || data.audio.samples.length < MIN_AUDIO_SAMPLES) {
+      throw new Error(
+        `__injectSensorData: audio required, minimum ${MIN_AUDIO_SAMPLES} samples (got ${data.audio?.samples.length ?? 0}).`
+      );
+    }
+    if (data.motion.length < MIN_MOTION_SAMPLES) {
+      throw new Error(
+        `__injectSensorData: motion required, minimum ${MIN_MOTION_SAMPLES} samples (got ${data.motion.length}).`
+      );
+    }
+    if (data.touch.length < MIN_TOUCH_SAMPLES) {
+      throw new Error(
+        `__injectSensorData: touch required, minimum ${MIN_TOUCH_SAMPLES} samples (got ${data.touch.length}).`
+      );
+    }
+    this.audioData = data.audio;
+    this.motionData = data.motion;
+    this.touchData = data.touch;
+    this.audioStageState = "captured";
+    this.motionStageState = "captured";
+    this.touchStageState = "captured";
+  }
+  /**
+   * @internal
+   *
+   * Run the validation step of the verify pipeline only: feature extraction
+   * + `/validate-features` POST. Returns the validation outcome without ever
+   * touching the on-chain submission path. Mirrors the production user
+   * flow's pre-payment gate — the validation server runs without requiring
+   * the wallet to have SOL, just like a real user gets a validation result
+   * before being prompted to sign the on-chain mint.
+   *
+   * Note: this is a strict subset of `complete()`. It skips the data-quality
+   * gates and re-verification check that `processSensorData` performs. The
+   * validation server still runs its full pipeline (Tier 1 + Tier 2 +
+   * phrase binding); only the client-side pre-flight checks differ.
+   *
+   * Use case: red team campaigns measuring server-side validation at scale
+   * without per-attempt SOL funding. Build-time gated identically to
+   * `__injectSensorData`; throws in production builds.
+   */
+  async __validateOnly(walletAddress) {
+    if (true) {
+      throw new Error(
+        "PulseSession.__validateOnly is only available in internal test builds. Set IAM_INTERNAL_TEST=1 when building pulse-sdk from source."
+      );
+    }
+    if (typeof walletAddress !== "string" || walletAddress.length === 0) {
+      throw new Error(
+        "__validateOnly requires a non-empty walletAddress string (used as wallet_id in the /validate-features payload)."
+      );
+    }
+    const active = [];
+    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 validate: stages still capturing: ${active.join(", ")}`
+      );
+    }
+    if (!this.audioData || this.motionData.length === 0 || this.touchData.length === 0) {
+      throw new Error(
+        "__validateOnly requires sensor data first \u2014 call __injectSensorData() before this."
+      );
+    }
+    const sensorData = {
+      audio: this.audioData,
+      motion: this.motionData,
+      touch: this.touchData,
+      modalities: {
+        audio: true,
+        motion: true,
+        touch: true
+      }
+    };
+    const extraction = await extractFingerprintAndValidate(
+      sensorData,
+      this.config,
+      walletAddress
+    );
+    if (!extraction.ok) {
+      return { validated: false, error: extraction.error };
+    }
+    return { validated: true };
+  }
   // --- Complete ---
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Solana types are optional peer deps
   async complete(wallet, connection, onProgress) {
@@ -3078,7 +3191,10 @@ async function fetchChallenge(executorUrl, walletAddress, apiKey) {
   DEFAULT_THRESHOLD,
   FINGERPRINT_BITS,
   MAX_CAPTURE_MS,
+  MIN_AUDIO_SAMPLES,
   MIN_CAPTURE_MS,
+  MIN_MOTION_SAMPLES,
+  MIN_TOUCH_SAMPLES,
   PROGRAM_IDS,
   PulseSDK,
   PulseSession,