@entros/pulse-sdk 1.2.0 → 1.4.1

package/dist/index.mjs

@@ -64,14 +64,25 @@ async function captureAudio(options = {}) {
       autoGainControl: false
     }
   });
-  const ctx = new AudioContext({ sampleRate: TARGET_SAMPLE_RATE });
-  await ctx.resume();
-  const capturedSampleRate = ctx.sampleRate;
-  const source = ctx.createMediaStreamSource(stream);
+  let ctx;
+  let source;
+  let capturedSampleRate;
+  try {
+    ctx = new AudioContext({ sampleRate: TARGET_SAMPLE_RATE });
+    await ctx.resume();
+    capturedSampleRate = ctx.sampleRate;
+    source = ctx.createMediaStreamSource(stream);
+  } catch (err) {
+    if (!preAcquiredStream) {
+      stream.getTracks().forEach((t) => t.stop());
+    }
+    throw err;
+  }
   const chunks = [];
   const startTime = performance.now();
   return new Promise((resolve) => {
     let stopped = false;
+    let abortTimer = null;
     const bufferSize = 4096;
     const processor = ctx.createScriptProcessor(bufferSize, 1, 1);
     processor.onaudioprocess = (e) => {
@@ -89,6 +100,7 @@ async function captureAudio(options = {}) {
       if (stopped) return;
       stopped = true;
       clearTimeout(maxTimer);
+      if (abortTimer !== null) clearTimeout(abortTimer);
       processor.disconnect();
       source.disconnect();
       stream.getTracks().forEach((t) => t.stop());
@@ -110,14 +122,14 @@ async function captureAudio(options = {}) {
     const maxTimer = setTimeout(stopCapture, maxDurationMs);
     if (signal) {
       if (signal.aborted) {
-        setTimeout(stopCapture, minDurationMs);
+        abortTimer = setTimeout(stopCapture, minDurationMs);
       } else {
         signal.addEventListener(
           "abort",
           () => {
             const elapsed = performance.now() - startTime;
             const remaining = Math.max(0, minDurationMs - elapsed);
-            setTimeout(stopCapture, remaining);
+            abortTimer = setTimeout(stopCapture, remaining);
           },
           { once: true }
         );
@@ -169,6 +181,7 @@ async function captureMotion(options = {}) {
   const startTime = performance.now();
   return new Promise((resolve) => {
     let stopped = false;
+    let abortTimer = null;
     const handler = (e) => {
       samples.push({
         timestamp: performance.now(),
@@ -184,6 +197,7 @@ async function captureMotion(options = {}) {
       if (stopped) return;
       stopped = true;
       clearTimeout(maxTimer);
+      if (abortTimer !== null) clearTimeout(abortTimer);
       window.removeEventListener("devicemotion", handler);
       resolve(samples);
     }
@@ -191,14 +205,14 @@ async function captureMotion(options = {}) {
     const maxTimer = setTimeout(stopCapture, maxDurationMs);
     if (signal) {
       if (signal.aborted) {
-        setTimeout(stopCapture, minDurationMs);
+        abortTimer = setTimeout(stopCapture, minDurationMs);
       } else {
         signal.addEventListener(
           "abort",
           () => {
             const elapsed = performance.now() - startTime;
             const remaining = Math.max(0, minDurationMs - elapsed);
-            setTimeout(stopCapture, remaining);
+            abortTimer = setTimeout(stopCapture, remaining);
           },
           { once: true }
         );
@@ -218,6 +232,7 @@ function captureTouch(element, options = {}) {
   const startTime = performance.now();
   return new Promise((resolve) => {
     let stopped = false;
+    let abortTimer = null;
     const handler = (e) => {
       samples.push({
         timestamp: performance.now(),
@@ -232,6 +247,7 @@ function captureTouch(element, options = {}) {
       if (stopped) return;
       stopped = true;
       clearTimeout(maxTimer);
+      if (abortTimer !== null) clearTimeout(abortTimer);
       element.removeEventListener("pointermove", handler);
       element.removeEventListener("pointerdown", handler);
       sdkLog(`[Entros SDK] Touch capture stopped: ${samples.length} samples collected`);
@@ -243,14 +259,14 @@ function captureTouch(element, options = {}) {
     const maxTimer = setTimeout(stopCapture, maxDurationMs);
     if (signal) {
       if (signal.aborted) {
-        setTimeout(stopCapture, minDurationMs);
+        abortTimer = setTimeout(stopCapture, minDurationMs);
       } else {
         signal.addEventListener(
           "abort",
           () => {
             const elapsed = performance.now() - startTime;
             const remaining = Math.max(0, minDurationMs - elapsed);
-            setTimeout(stopCapture, remaining);
+            abortTimer = setTimeout(stopCapture, remaining);
           },
           { once: true }
         );
@@ -1257,6 +1273,45 @@ async function generateSolanaProof(current, previous, wasmPath, zkeyPath, thresh
   return serializeProof(proof, publicSignals);
 }
 
+// src/submit/receipt.ts
+var PUBKEY_BYTES = 32;
+var SIGNATURE_BYTES = 64;
+var MESSAGE_BYTES = 72;
+function bytesToHex(bytes) {
+  let out = "";
+  for (let i = 0; i < bytes.length; i += 1) {
+    out += (bytes[i] ?? 0).toString(16).padStart(2, "0");
+  }
+  return out;
+}
+function hexToBytes(hex, expectedLen) {
+  const trimmed = hex.startsWith("0x") || hex.startsWith("0X") ? hex.slice(2) : hex;
+  if (trimmed.length !== expectedLen * 2) return null;
+  if (!/^[0-9a-f]+$/.test(trimmed)) return null;
+  const out = new Uint8Array(expectedLen);
+  for (let i = 0; i < expectedLen; i += 1) {
+    out[i] = parseInt(trimmed.substr(i * 2, 2), 16);
+  }
+  return out;
+}
+function decodeSignedReceipt(receipt) {
+  const publicKey = hexToBytes(receipt.validator_pubkey_hex, PUBKEY_BYTES);
+  const signature = hexToBytes(receipt.signature_hex, SIGNATURE_BYTES);
+  const message = hexToBytes(receipt.message_hex, MESSAGE_BYTES);
+  if (!publicKey || !signature || !message) return null;
+  return { publicKey, signature, message };
+}
+async function buildEd25519ReceiptIx(receipt) {
+  const decoded = decodeSignedReceipt(receipt);
+  if (!decoded) return null;
+  const { Ed25519Program } = await import("@solana/web3.js");
+  return Ed25519Program.createInstructionWithPublicKey({
+    publicKey: decoded.publicKey,
+    message: decoded.message,
+    signature: decoded.signature
+  });
+}
+
 // src/submit/wallet.ts
 async function requestSasAttestation(wallet, walletAddress, relayerUrl, relayerApiKey, serverNonce) {
   try {
@@ -1298,14 +1353,22 @@ async function requestSasAttestation(wallet, walletAddress, relayerUrl, relayerA
         return attestData.attestation_tx;
       }
     }
-  } catch {
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    sdkWarn(`[Entros SDK] SAS attestation request failed: ${msg}`);
   }
   return void 0;
 }
 async function submitViaWallet(proof, commitment, options) {
   try {
     const anchor = await import("@coral-xyz/anchor");
-    const { PublicKey, SystemProgram, Transaction, ComputeBudgetProgram } = await import("@solana/web3.js");
+    const {
+      PublicKey,
+      SystemProgram,
+      Transaction,
+      ComputeBudgetProgram,
+      SYSVAR_INSTRUCTIONS_PUBKEY
+    } = await import("@solana/web3.js");
     const provider = new anchor.AnchorProvider(
       options.connection,
       options.wallet,
@@ -1474,7 +1537,7 @@ async function submitViaWallet(proof, commitment, options) {
         false,
         TOKEN_2022_PROGRAM_ID
       );
-      await anchorProgram.methods.mintAnchor(Array.from(commitment)).accounts({
+      const mintAnchorIx = await anchorProgram.methods.mintAnchor(Array.from(commitment)).accounts({
         user: provider.wallet.publicKey,
         identityState: identityPda,
         mint: mintPda,
@@ -1486,8 +1549,36 @@ async function submitViaWallet(proof, commitment, options) {
         tokenProgram: TOKEN_2022_PROGRAM_ID,
         systemProgram: SystemProgram.programId,
         protocolConfig: protocolConfigPda,
-        treasury: treasuryPda
-      }).rpc();
+        treasury: treasuryPda,
+        instructionsSysvar: SYSVAR_INSTRUCTIONS_PUBKEY
+      }).instruction();
+      let ed25519Ix = null;
+      if (options.signedReceipt) {
+        ed25519Ix = await buildEd25519ReceiptIx(options.signedReceipt);
+        if (!ed25519Ix) {
+          return {
+            success: false,
+            error: "Validator returned a signed receipt that failed to decode (malformed hex or wrong byte length). Refusing to mint without a valid binding. The validator service may be misconfigured \u2014 check the validation-service logs."
+          };
+        }
+        sdkLog(
+          "[Entros SDK] Bundling validator-signed mint receipt before mint_anchor"
+        );
+      } else {
+        sdkLog(
+          "[Entros SDK] No validator receipt available; minting without binding (on-chain check is log-only today)"
+        );
+      }
+      const tx = new Transaction();
+      tx.add(ComputeBudgetProgram.setComputeUnitLimit({ units: 2e5 }));
+      if (ed25519Ix) tx.add(ed25519Ix);
+      tx.add(mintAnchorIx);
+      tx.feePayer = provider.wallet.publicKey;
+      tx.recentBlockhash = (await options.connection.getLatestBlockhash("confirmed")).blockhash;
+      txSig = await options.wallet.sendTransaction(tx, options.connection, {
+        skipPreflight: true
+      });
+      await options.connection.confirmTransaction(txSig, "confirmed");
     }
     const attestationTx = options.relayerUrl ? await requestSasAttestation(
       options.wallet,
@@ -1729,11 +1820,24 @@ function fromBase64(b64) {
 var STORAGE_KEY = "entros-protocol-verification-data";
 var ENCRYPTED_VERSION = 2;
 var inMemoryStore = null;
+var privacyFallbackCallback = null;
+function setPrivacyFallback(cb) {
+  privacyFallbackCallback = cb ?? null;
+}
 function isEncryptedEnvelope(obj) {
-  return typeof obj === "object" && obj !== null && obj.v === ENCRYPTED_VERSION && typeof obj.iv === "string" && typeof obj.ct === "string";
+  if (typeof obj !== "object" || obj === null) return false;
+  const o = obj;
+  return o.v === ENCRYPTED_VERSION && typeof o.iv === "string" && o.iv.length > 0 && typeof o.ct === "string" && o.ct.length > 0;
 }
 function isPlaintextData(obj) {
-  return typeof obj === "object" && obj !== null && Array.isArray(obj.fingerprint);
+  if (typeof obj !== "object" || obj === null) return false;
+  const o = obj;
+  if (!Array.isArray(o.fingerprint)) return false;
+  if (!o.fingerprint.every((bit) => typeof bit === "number")) return false;
+  if (typeof o.salt !== "string" || o.salt.length === 0) return false;
+  if (typeof o.commitment !== "string" || o.commitment.length === 0) return false;
+  if (typeof o.timestamp !== "number" || !Number.isFinite(o.timestamp)) return false;
+  return true;
 }
 async function fetchIdentityState(walletPubkey, connection) {
   try {
@@ -1772,14 +1876,34 @@ async function fetchIdentityState(walletPubkey, connection) {
 async function storeVerificationData(data) {
   try {
     if (!hasCryptoSupport()) {
-      sdkWarn("[Entros SDK] Crypto unavailable \u2014 verification data stored unencrypted");
-      localStorage.setItem(STORAGE_KEY, JSON.stringify(data));
+      const allowPlaintext = privacyFallbackCallback ? await privacyFallbackCallback().catch(() => false) : false;
+      if (allowPlaintext) {
+        sdkWarn(
+          "[Entros SDK] Crypto unavailable; user-approved plaintext storage"
+        );
+        localStorage.setItem(STORAGE_KEY, JSON.stringify(data));
+      } else {
+        sdkWarn(
+          "[Entros SDK] Crypto unavailable and no privacy-fallback approval \u2014 using in-memory storage (data lost on reload)"
+        );
+        inMemoryStore = data;
+      }
       return;
     }
     const key = await getOrCreateEncryptionKey();
     if (!key) {
-      sdkWarn("[Entros SDK] Encryption key unavailable \u2014 storing unencrypted");
-      localStorage.setItem(STORAGE_KEY, JSON.stringify(data));
+      const allowPlaintext = privacyFallbackCallback ? await privacyFallbackCallback().catch(() => false) : false;
+      if (allowPlaintext) {
+        sdkWarn(
+          "[Entros SDK] Encryption key unavailable; user-approved plaintext storage"
+        );
+        localStorage.setItem(STORAGE_KEY, JSON.stringify(data));
+      } else {
+        sdkWarn(
+          "[Entros SDK] Encryption key unavailable and no privacy-fallback approval \u2014 using in-memory storage"
+        );
+        inMemoryStore = data;
+      }
       return;
     }
     const { iv, ct } = await encrypt(JSON.stringify(data), key);
@@ -1865,6 +1989,9 @@ async function extractFingerprintAndValidate(sensorData, config, walletAddress,
   sdkLog(
     `[Entros SDK] Feature vector: ${features.length} dimensions, ${nonZero} non-zero. Audio[0..43]: ${features.slice(0, 44).filter((v) => v !== 0).length} non-zero. Motion/Mouse[44..97]: ${features.slice(44, 98).filter((v) => v !== 0).length} non-zero. Touch[98..133]: ${features.slice(98, 134).filter((v) => v !== 0).length} non-zero.`
   );
+  const fingerprint = simhash(normalizedFeatures);
+  const tbh = await generateTBH(fingerprint);
+  let signedReceipt;
   onProgress?.("Validating...");
   if (config.relayerUrl && walletAddress) {
     try {
@@ -1876,6 +2003,7 @@ async function extractFingerprintAndValidate(sensorData, config, walletAddress,
       }
       const audioSamplesB64 = sensorData.audio?.samples ? encodeAudioAsBase64(sensorData.audio.samples) : void 0;
       const audioSampleRateHz = sensorData.audio?.sampleRate;
+      const commitmentNewHex = bytesToHex(tbh.commitmentBytes);
       const validateController = new AbortController();
       const validateTimer = setTimeout(() => validateController.abort(), 15e3);
       const validateResponse = await fetch(validateUrl, {
@@ -1887,32 +2015,43 @@ async function extractFingerprintAndValidate(sensorData, config, walletAddress,
           accel_magnitude: accelMagnitude,
           wallet_id: walletAddress,
           audio_samples_b64: audioSamplesB64,
-          audio_sample_rate_hz: audioSampleRateHz
+          audio_sample_rate_hz: audioSampleRateHz,
+          commitment_new_hex: commitmentNewHex
         }),
         signal: validateController.signal
       });
       clearTimeout(validateTimer);
       if (!validateResponse.ok) {
         const errorBody = await validateResponse.json().catch(() => ({}));
-        const body = errorBody;
-        const reason = typeof body.reason === "string" ? body.reason : void 0;
-        sdkWarn(
-          `[Entros SDK] Feature validation rejected by server${reason ? ` (reason: ${reason})` : ""}`
-        );
+        sdkWarn("[Entros SDK] Feature validation rejected by server");
         return {
           ok: false,
-          error: body.error || "Feature validation failed",
-          reason
+          error: errorBody.error || "Feature validation failed",
+          reason: errorBody.reason
         };
       }
+      try {
+        const successBody = await validateResponse.json();
+        if (successBody.signed_receipt) {
+          signedReceipt = successBody.signed_receipt;
+        }
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        sdkWarn(
+          `[Entros SDK] /validate-features returned 200 but body was not parseable JSON; proceeding without receipt: ${msg}`
+        );
+      }
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
-      sdkWarn(`[Entros SDK] Feature validation unavailable: ${msg}, proceeding without server validation`);
+      sdkWarn(`[Entros SDK] Feature validation unavailable: ${msg}`);
+      return {
+        ok: false,
+        error: "Validation service unreachable. Please check your connection and try again.",
+        reason: "validation_unavailable"
+      };
     }
   }
-  const fingerprint = simhash(normalizedFeatures);
-  const tbh = await generateTBH(fingerprint);
-  return { ok: true, features, f0Contour, accelMagnitude, fingerprint, tbh };
+  return { ok: true, features, f0Contour, accelMagnitude, fingerprint, tbh, signedReceipt };
 }
 async function processSensorData(sensorData, config, wallet, connection, onProgress) {
   const audioSamples = sensorData.audio?.samples.length ?? 0;
@@ -1983,7 +2122,7 @@ async function processSensorData(sensorData, config, wallet, connection, onProgr
       reason: extraction.reason
     };
   }
-  const { fingerprint, tbh, features } = extraction;
+  const { fingerprint, tbh, features, signedReceipt } = extraction;
   let isFirstVerification;
   const previousData = await loadVerificationData();
   if (wallet && connection) {
@@ -2073,7 +2212,14 @@ async function processSensorData(sensorData, config, wallet, connection, onProgr
       submission = await submitViaWallet(
         solanaProof ?? { proofBytes: new Uint8Array(0), publicInputs: [] },
         tbh.commitmentBytes,
-        { wallet, connection, isFirstVerification: true, relayerUrl: config.relayerUrl, relayerApiKey: config.relayerApiKey }
+        {
+          wallet,
+          connection,
+          isFirstVerification: true,
+          relayerUrl: config.relayerUrl,
+          relayerApiKey: config.relayerApiKey,
+          signedReceipt
+        }
       );
     } else {
       submission = await submitViaWallet(solanaProof, tbh.commitmentBytes, {
@@ -2375,70 +2521,6 @@ var PulseSession = class {
     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) {
@@ -2513,6 +2595,7 @@ var PulseSDK = class {
       ...config
     };
     setDebug(config.debug ?? false);
+    setPrivacyFallback(config.onPrivacyFallback);
   }
   /**
    * Create a staged capture session for event-driven control.