@entros/pulse-sdk 1.1.0 → 1.4.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

@@ -19,6 +19,22 @@ interface PulseConfig {
     threshold?: number;
     /** Enable console logging for diagnostics. Default: false. */
     debug?: boolean;
+    /**
+     * Optional callback invoked when the SDK detects that encrypted local
+     * storage is unavailable (e.g. iOS Safari private browsing, Brave
+     * shields, Firefox Total Cookie Protection). The host app can prompt
+     * the user and resolve to:
+     *   - `true`  → SDK stores verification data in plaintext localStorage.
+     *               Convenient (baseline survives reload) but the
+     *               256-bit fingerprint + salt + commitment sit unencrypted.
+     *   - `false` → SDK stores in-memory only. Data is lost on reload;
+     *               user must re-enroll each session.
+     * If this callback is NOT provided, the SDK defaults to in-memory only —
+     * never silently writes plaintext to localStorage. This default is the
+     * safer choice; opt-in to plaintext via the callback when the host app
+     * has surfaced the privacy tradeoff to the user.
+     */
+    onPrivacyFallback?: () => Promise<boolean>;
 }
 
 /** Raw audio samples captured during the Pulse challenge */
@@ -84,6 +100,26 @@ interface SubmissionResult {
     attestationTx?: string;
     error?: string;
 }
+/**
+ * Validator-signed receipt binding (wallet, commitment, validated_at) for the
+ * upcoming `mint_anchor` transaction (master-list #146 Phase 4). Returned in
+ * the `/validate-features` response when the request includes
+ * `commitment_new_hex` and the validator has a signing key configured.
+ *
+ * Wire fields are byte-identical to `entros_validation::SignedReceiptDto` and
+ * the executor's local mirror at `executor-node::validation::SignedReceiptDto`.
+ */
+interface SignedReceiptDto {
+    /** Hex-encoded 32-byte Ed25519 public key of the validator. */
+    validator_pubkey_hex: string;
+    /**
+     * Hex-encoded 72-byte message:
+     *   wallet_pubkey (32) || commitment_new (32) || validated_at i64 LE (8)
+     */
+    message_hex: string;
+    /** Hex-encoded 64-byte Ed25519 signature over `message_hex`. */
+    signature_hex: string;
+}
 /** Result of a full Pulse verification */
 interface VerificationResult {
     success: boolean;
@@ -92,6 +128,29 @@ interface VerificationResult {
     attestationTx?: string;
     isFirstVerification: boolean;
     error?: string;
+    /**
+     * Reason label when verification fails. Two-source taxonomy:
+     *
+     * Server-side safe-reveal (validator → executor → SDK):
+     *   - `variance_floor`, `entropy_bounds`, `temporal_coupling_low`,
+     *     `phrase_content_mismatch`
+     *   Surfaced for the soft-reject + retry UX (master-list #94) so the
+     *   UI can render a per-category hint.
+     *
+     * Client-side (SDK-emitted):
+     *   - `validation_unavailable` — the relayer's `/validate-features`
+     *     endpoint was unreachable (network failure, timeout, abort).
+     *     UI should treat as transient + offer retry. NOT a server-side
+     *     ReasonCode; emitted directly by `extractFingerprintAndValidate`
+     *     when the fetch promise rejects.
+     *
+     * 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;
@@ -432,6 +491,15 @@ declare function submitViaWallet(proof: SolanaProof, commitment: Uint8Array, opt
     isFirstVerification: boolean;
     relayerUrl?: string;
     relayerApiKey?: string;
+    /**
+     * Validator-signed mint receipt (master-list #146 Phase 4). Consumed
+     * only on the first-verification path: when present, the SDK prepends
+     * an `Ed25519Program::verify` instruction so on-chain `mint_anchor`
+     * can confirm the commitment was endorsed by the configured validator.
+     * Re-verification ignores the field entirely — `update_anchor` enforces
+     * binding via the VerificationResult PDA instead.
+     */
+    signedReceipt?: SignedReceiptDto;
 }): Promise<SubmissionResult>;
 /**
  * Submit a baseline reset on-chain via a connected wallet.
@@ -558,8 +626,15 @@ interface StoredVerificationData {
 declare function fetchIdentityState(walletPubkey: string, connection: any): Promise<IdentityState | null>;
 /**
  * Store verification data locally for re-verification.
- * Encrypts with AES-256-GCM when Web Crypto is available.
- * Falls back to plaintext with a warning otherwise.
+ *
+ * Storage tiers (preferred first):
+ *   1. Encrypted localStorage envelope (Web Crypto available).
+ *   2. If crypto unavailable AND `onPrivacyFallback` callback registered
+ *      AND the callback resolves true, plaintext localStorage. The host
+ *      app is responsible for surfacing the privacy tradeoff to the user
+ *      before approving the fallback.
+ *   3. Otherwise, in-memory only (lost on reload). Safer default —
+ *      never silently writes plaintext to localStorage.
  */
 declare function storeVerificationData(data: StoredVerificationData): Promise<void>;
 /**

package/dist/index.d.ts

@@ -19,6 +19,22 @@ interface PulseConfig {
     threshold?: number;
     /** Enable console logging for diagnostics. Default: false. */
     debug?: boolean;
+    /**
+     * Optional callback invoked when the SDK detects that encrypted local
+     * storage is unavailable (e.g. iOS Safari private browsing, Brave
+     * shields, Firefox Total Cookie Protection). The host app can prompt
+     * the user and resolve to:
+     *   - `true`  → SDK stores verification data in plaintext localStorage.
+     *               Convenient (baseline survives reload) but the
+     *               256-bit fingerprint + salt + commitment sit unencrypted.
+     *   - `false` → SDK stores in-memory only. Data is lost on reload;
+     *               user must re-enroll each session.
+     * If this callback is NOT provided, the SDK defaults to in-memory only —
+     * never silently writes plaintext to localStorage. This default is the
+     * safer choice; opt-in to plaintext via the callback when the host app
+     * has surfaced the privacy tradeoff to the user.
+     */
+    onPrivacyFallback?: () => Promise<boolean>;
 }
 
 /** Raw audio samples captured during the Pulse challenge */
@@ -84,6 +100,26 @@ interface SubmissionResult {
     attestationTx?: string;
     error?: string;
 }
+/**
+ * Validator-signed receipt binding (wallet, commitment, validated_at) for the
+ * upcoming `mint_anchor` transaction (master-list #146 Phase 4). Returned in
+ * the `/validate-features` response when the request includes
+ * `commitment_new_hex` and the validator has a signing key configured.
+ *
+ * Wire fields are byte-identical to `entros_validation::SignedReceiptDto` and
+ * the executor's local mirror at `executor-node::validation::SignedReceiptDto`.
+ */
+interface SignedReceiptDto {
+    /** Hex-encoded 32-byte Ed25519 public key of the validator. */
+    validator_pubkey_hex: string;
+    /**
+     * Hex-encoded 72-byte message:
+     *   wallet_pubkey (32) || commitment_new (32) || validated_at i64 LE (8)
+     */
+    message_hex: string;
+    /** Hex-encoded 64-byte Ed25519 signature over `message_hex`. */
+    signature_hex: string;
+}
 /** Result of a full Pulse verification */
 interface VerificationResult {
     success: boolean;
@@ -92,6 +128,29 @@ interface VerificationResult {
     attestationTx?: string;
     isFirstVerification: boolean;
     error?: string;
+    /**
+     * Reason label when verification fails. Two-source taxonomy:
+     *
+     * Server-side safe-reveal (validator → executor → SDK):
+     *   - `variance_floor`, `entropy_bounds`, `temporal_coupling_low`,
+     *     `phrase_content_mismatch`
+     *   Surfaced for the soft-reject + retry UX (master-list #94) so the
+     *   UI can render a per-category hint.
+     *
+     * Client-side (SDK-emitted):
+     *   - `validation_unavailable` — the relayer's `/validate-features`
+     *     endpoint was unreachable (network failure, timeout, abort).
+     *     UI should treat as transient + offer retry. NOT a server-side
+     *     ReasonCode; emitted directly by `extractFingerprintAndValidate`
+     *     when the fetch promise rejects.
+     *
+     * 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;
@@ -432,6 +491,15 @@ declare function submitViaWallet(proof: SolanaProof, commitment: Uint8Array, opt
     isFirstVerification: boolean;
     relayerUrl?: string;
     relayerApiKey?: string;
+    /**
+     * Validator-signed mint receipt (master-list #146 Phase 4). Consumed
+     * only on the first-verification path: when present, the SDK prepends
+     * an `Ed25519Program::verify` instruction so on-chain `mint_anchor`
+     * can confirm the commitment was endorsed by the configured validator.
+     * Re-verification ignores the field entirely — `update_anchor` enforces
+     * binding via the VerificationResult PDA instead.
+     */
+    signedReceipt?: SignedReceiptDto;
 }): Promise<SubmissionResult>;
 /**
  * Submit a baseline reset on-chain via a connected wallet.
@@ -558,8 +626,15 @@ interface StoredVerificationData {
 declare function fetchIdentityState(walletPubkey: string, connection: any): Promise<IdentityState | null>;
 /**
  * Store verification data locally for re-verification.
- * Encrypts with AES-256-GCM when Web Crypto is available.
- * Falls back to plaintext with a warning otherwise.
+ *
+ * Storage tiers (preferred first):
+ *   1. Encrypted localStorage envelope (Web Crypto available).
+ *   2. If crypto unavailable AND `onPrivacyFallback` callback registered
+ *      AND the callback resolves true, plaintext localStorage. The host
+ *      app is responsible for surfacing the privacy tradeoff to the user
+ *      before approving the fallback.
+ *   3. Otherwise, in-memory only (lost on reload). Safer default —
+ *      never silently writes plaintext to localStorage.
  */
 declare function storeVerificationData(data: StoredVerificationData): Promise<void>;
 /**