@entros/pulse-sdk 1.1.0 → 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,6 +92,19 @@ 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;

package/dist/index.d.ts

@@ -92,6 +92,19 @@ 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;

package/dist/index.js

@@ -568,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)));
@@ -629,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);
@@ -720,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;
@@ -747,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,
@@ -806,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++) {
@@ -1978,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) {
@@ -2058,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;
@@ -2236,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;
@@ -2512,7 +2526,7 @@ var PulseSession = class {
       walletAddress
     );
     if (!extraction.ok) {
-      return { validated: false, error: extraction.error };
+      return { validated: false, error: extraction.error, reason: extraction.reason };
     }
     return { validated: true };
   }