@entros/pulse-sdk 1.0.1 → 1.2.0

package/README.md

@@ -63,6 +63,12 @@ npm run build     # ESM + CJS output
 npm run typecheck # TypeScript strict mode
 ```
 
+## Migration history
+
+Originally published as `@iam-protocol/pulse-sdk` (deprecated). Renamed during
+the IAM → Entros Protocol rebrand on 2026-04-25; full commit history preserved
+on the current repository at `github.com/entros-protocol/pulse-sdk`.
+
 ## License
 
 MIT

package/dist/index.d.mts

@@ -92,9 +92,29 @@ interface VerificationResult {
     attestationTx?: string;
     isFirstVerification: boolean;
     error?: string;
+    /**
+     * Safe-to-reveal validator reason label when validation rejected — one of
+     * `variance_floor`, `entropy_bounds`, `temporal_coupling_low`,
+     * `phrase_content_mismatch`. Surfaced for the soft-reject + retry UX
+     * (master-list #94) so the UI can show a per-category hint.
+     *
+     * Absent on every other failure path (data-quality, on-chain submission,
+     * baseline missing, etc.) and on attack-signal rejections (TTS detection,
+     * Sybil match) and capture-shape bugs — the validator deliberately keeps
+     * those opaque to prevent adversarial probing. UI must not assume reason
+     * is present even when `success === false`.
+     */
+    reason?: string;
 }
 
 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 +532,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 +638,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 +688,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

@@ -92,9 +92,29 @@ interface VerificationResult {
     attestationTx?: string;
     isFirstVerification: boolean;
     error?: string;
+    /**
+     * Safe-to-reveal validator reason label when validation rejected — one of
+     * `variance_floor`, `entropy_bounds`, `temporal_coupling_low`,
+     * `phrase_content_mismatch`. Surfaced for the soft-reject + retry UX
+     * (master-list #94) so the UI can show a per-category hint.
+     *
+     * Absent on every other failure path (data-quality, on-chain submission,
+     * baseline missing, etc.) and on attack-signal rejections (TTS detection,
+     * Sybil match) and capture-shape bugs — the validator deliberately keeps
+     * those opaque to prevent adversarial probing. UI must not assume reason
+     * is present even when `success === false`.
+     */
+    reason?: string;
 }
 
 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 +532,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 +638,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 +688,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",
@@ -565,7 +568,7 @@ function extractFormantRatios(samples, sampleRate, frameSize, hopSize) {
   const numFrames = Math.floor((samples.length - frameSize) / hopSize) + 1;
   for (let i = 0; i < numFrames; i++) {
     const start = i * hopSize;
-    const frame = samples.slice(start, start + frameSize);
+    const frame = samples.subarray(start, start + frameSize);
     const windowed = new Float32Array(frameSize);
     for (let j = 0; j < frameSize; j++) {
       windowed[j] = (frame[j] ?? 0) * (0.54 - 0.46 * Math.cos(2 * Math.PI * j / (frameSize - 1)));
@@ -626,7 +629,7 @@ async function detectF0Contour(samples, sampleRate) {
   }
   for (let i = 0; i < numFrames; i++) {
     const start = i * hopSize;
-    const frame = samples.slice(start, start + frameSize);
+    const frame = samples.subarray(start, start + frameSize);
     const pitch = detect(frame);
     if (pitch && pitch > 50 && pitch < 600) {
       f0.push(pitch);
@@ -717,7 +720,7 @@ function computeHNR(samples, sampleRate, f0Contour) {
     const f0 = f0Contour[i];
     if (f0 <= 0) continue;
     const start = i * hopSize;
-    const frame = samples.slice(start, start + frameSize);
+    const frame = samples.subarray(start, start + frameSize);
     const period = Math.round(sampleRate / f0);
     if (period <= 0 || period >= frame.length) continue;
     let num = 0;
@@ -744,11 +747,10 @@ async function computeLTAS(samples, sampleRate) {
   const flatnesses = [];
   const spreads = [];
   const numFrames = Math.floor((samples.length - frameSize) / hopSize) + 1;
+  const paddedFrame = new Float32Array(frameSize);
   for (let i = 0; i < numFrames; i++) {
     const start = i * hopSize;
-    const frame = samples.slice(start, start + frameSize);
-    const paddedFrame = new Float32Array(frameSize);
-    paddedFrame.set(frame);
+    paddedFrame.set(samples.subarray(start, start + frameSize), 0);
     const features = Meyda.extract(
       ["spectralCentroid", "spectralRolloff", "spectralFlatness", "spectralSpread"],
       paddedFrame,
@@ -803,7 +805,15 @@ async function extractSpeakerFeaturesDetailed(audio) {
     const abs = Math.abs(samples[i] ?? 0);
     if (abs > peakAmp) peakAmp = abs;
   }
-  const normalizedSamples = peakAmp > 1e-6 ? new Float32Array(samples.map((s) => s / peakAmp * 0.9)) : samples;
+  let normalizedSamples;
+  if (peakAmp > 1e-6) {
+    normalizedSamples = new Float32Array(samples.length);
+    for (let i = 0; i < samples.length; i++) {
+      normalizedSamples[i] = samples[i] / peakAmp * 0.9;
+    }
+  } else {
+    normalizedSamples = samples;
+  }
   const { f0, amplitudes: normalizedAmplitudes, periods } = await detectF0Contour(normalizedSamples, sampleRate);
   const amplitudes = [];
   for (let i = 0; i < numFrames; i++) {
@@ -1975,10 +1985,15 @@ async function extractFingerprintAndValidate(sensorData, config, walletAddress,
       clearTimeout(validateTimer);
       if (!validateResponse.ok) {
         const errorBody = await validateResponse.json().catch(() => ({}));
-        sdkWarn("[Entros SDK] Feature validation rejected by server");
+        const body = errorBody;
+        const reason = typeof body.reason === "string" ? body.reason : void 0;
+        sdkWarn(
+          `[Entros SDK] Feature validation rejected by server${reason ? ` (reason: ${reason})` : ""}`
+        );
         return {
           ok: false,
-          error: errorBody.error || "Feature validation failed"
+          error: body.error || "Feature validation failed",
+          reason
         };
       }
     } catch (err) {
@@ -2055,7 +2070,8 @@ async function processSensorData(sensorData, config, wallet, connection, onProgr
       success: false,
       commitment: new Uint8Array(32),
       isFirstVerification: false,
-      error: extraction.error
+      error: extraction.error,
+      reason: extraction.reason
     };
   }
   const { fingerprint, tbh, features } = extraction;
@@ -2233,7 +2249,8 @@ async function processResetSensorData(sensorData, config, wallet, connection, on
       success: false,
       commitment: new Uint8Array(32),
       isFirstVerification: true,
-      error: extraction.error
+      error: extraction.error,
+      reason: extraction.reason
     };
   }
   const { tbh } = extraction;
@@ -2403,6 +2420,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, reason: extraction.reason };
+    }
+    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 +3205,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,