@entros/pulse-sdk 1.0.1 → 1.1.0

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.
  *
@@ -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
@@ -618,7 +625,7 @@ 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
- * `iam-validation/src/word_dict.rs`); shown to the user as the voice challenge
+ * `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).
  *
@@ -668,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.
  *
@@ -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
@@ -618,7 +625,7 @@ 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
- * `iam-validation/src/word_dict.rs`); shown to the user as the voice challenge
+ * `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).
  *
@@ -668,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",
@@ -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,