@entros/pulse-sdk 3.2.0 → 3.3.0

package/dist/index.d.mts

@@ -1,3 +1,5 @@
+import { PublicKey } from '@solana/web3.js';
+
 declare const FINGERPRINT_BITS = 256;
 declare const DEFAULT_THRESHOLD = 96;
 declare const DEFAULT_MIN_DISTANCE = 3;
@@ -511,6 +513,15 @@ declare function submitViaWallet(proof: SolanaProof, commitment: Uint8Array, opt
      * VerificationResult PDA instead.
      */
     signedReceipt?: SignedReceiptDto;
+    /**
+     * Encrypted baseline blob (master-list #98). When present, the SDK
+     * appends a `set_encrypted_baseline` instruction at the end of the
+     * atomic transaction so the wallet's on-chain baseline is rewritten
+     * to reflect the new fingerprint in the same wallet prompt as the
+     * mint / re-verify. Omitted when the wallet adapter lacks
+     * `signMessage` (the SDK can't derive the AES key without it).
+     */
+    encryptedBaselineBlob?: Uint8Array;
 }): Promise<SubmissionResult>;
 /**
  * Submit a baseline reset on-chain via a connected wallet.
@@ -532,6 +543,15 @@ declare function submitResetViaWallet(commitment: Uint8Array, options: {
     connection: any;
     relayerUrl?: string;
     relayerApiKey?: string;
+    /**
+     * Encrypted baseline blob (master-list #98). When present, the SDK
+     * appends a `set_encrypted_baseline` instruction so the wallet's
+     * on-chain baseline is rewritten under the NEW post-reset commitment
+     * in the same atomic transaction. Without this, the prior blob would
+     * be stale on the next recovery attempt (auth-tag mismatch under the
+     * new commitment in AAD) and recovery would fall back to fresh capture.
+     */
+    encryptedBaselineBlob?: Uint8Array;
 }): Promise<SubmissionResult>;
 
 /**
@@ -630,6 +650,125 @@ interface StoredVerificationData {
     timestamp: number;
 }
 
+/**
+ * Wallet-keyed encrypted baseline storage (master-list #98).
+ *
+ * Architecture: the user's previous SimHash + salt (private witnesses for
+ * the Hamming-distance ZK proof) are encrypted with AES-256-GCM under a
+ * key derived from a deterministic `signMessage` on a domain-separated
+ * payload. The 96-byte ciphertext blob is stored on chain in a per-wallet
+ * `EncryptedBaseline` PDA, making the baseline wallet-portable across
+ * devices and recoverable after a cache wipe.
+ *
+ * The GCM AAD binds (version, algorithm, wallet, baselinePda, current on-
+ * chain commitment). After `reset_identity_state` cycles the commitment,
+ * the old blob's auth-tag fails to verify under the new commitment — that
+ * mismatch IS the staleness signal. No explicit version tracking needed.
+ *
+ * Plaintext biometric data never reaches chain at any point. This module
+ * is the only place wallet-derived key material flows; it never leaves
+ * memory and the key is non-extractable.
+ */
+
+/** Layout: version(1) + algo(1) + reserved(2) + IV(12) + ct+tag(80) */
+declare const ENCRYPTED_BASELINE_BLOB_BYTES = 96;
+/**
+ * Pack a 256-bit fingerprint into 32 bytes. LSB-first within each byte —
+ * the convention is internal to the encrypted-baseline blob; the only
+ * requirement is that `bytesToFingerprint` is its exact inverse.
+ */
+declare function fingerprintToBytes(bits: number[]): Uint8Array;
+/** Inverse of `fingerprintToBytes`. */
+declare function bytesToFingerprint(bytes: Uint8Array): number[];
+/** Big-endian 32-byte → BigInt. Inverse of `bigintToBytes32` in hashing/poseidon. */
+declare function bytes32ToBigint(bytes: Uint8Array): bigint;
+/**
+ * The per-wallet `EncryptedBaseline` PDA address. Owned by entros-anchor.
+ * Seeds: `[b"encrypted_baseline", walletPubkey.toBuffer()]`.
+ */
+declare function deriveEncryptedBaselinePda(walletPubkey: PublicKey): Promise<[PublicKey, number]>;
+/**
+ * Wallet adapter shape needed for key derivation.
+ * Compatible with `@solana/wallet-adapter-base` `WalletAdapter`.
+ */
+interface BaselineWallet {
+    publicKey: PublicKey;
+    signMessage: (msg: Uint8Array) => Promise<Uint8Array>;
+}
+/**
+ * Derive an AES-256 key from the wallet's deterministic signature over
+ * the domain-separated payload, via HKDF-SHA256.
+ *
+ *   IKM  = Ed25519 signature (64 bytes, pseudorandom under RoM)
+ *   salt = wallet pubkey bytes (32 bytes — wallet-binding salt)
+ *   info = "entros-protocol/identity-baseline/v1"
+ *   L    = 32 bytes (AES-256 key length)
+ *
+ * Determinism follows from RFC 8032 Ed25519 signature determinism. Same
+ * wallet + same message → same signature → same key, across any device.
+ *
+ * The derived `CryptoKey` is non-extractable; only WebCrypto can use it
+ * for AES-GCM encrypt/decrypt.
+ *
+ * Throws if the wallet doesn't implement `signMessage` (e.g., some Ledger
+ * firmware versions). Callers should catch and fall back gracefully.
+ */
+declare function deriveBaselineKey(wallet: BaselineWallet): Promise<CryptoKey>;
+/**
+ * Derive the baseline AES key for `wallet`, reusing the cached derivation
+ * when one is in-flight or resolved for this wallet pubkey in the current
+ * page lifetime. The key is deterministic per wallet, so caching is purely
+ * a UX optimization (avoids re-prompting `signMessage` on every verification
+ * within a session). Cache survives a single page load and is dropped on
+ * reload or via `clearBaselineKeyCache`.
+ *
+ * Concurrent calls for the same wallet share one `signMessage` prompt; a
+ * failed derivation evicts the cache entry so subsequent calls re-derive.
+ */
+declare function getOrDeriveBaselineKey(wallet: BaselineWallet): Promise<CryptoKey>;
+/** Drop all cached baseline keys. Test hook + emergency wipe. */
+declare function clearBaselineKeyCache(): void;
+/**
+ * Encrypt (simhash || salt) into a 96-byte versioned envelope.
+ *
+ * @param simhash      32-byte SimHash fingerprint (packed 256 bits)
+ * @param salt         32-byte Poseidon commitment salt
+ * @param key          AES-256-GCM key from `deriveBaselineKey`
+ * @param walletPubkey wallet that owns the EncryptedBaseline PDA
+ * @param baselinePda  the EncryptedBaseline PDA address (bound in AAD)
+ * @param commitment   the on-chain `current_commitment` at encryption time
+ *                     (bound in AAD for staleness detection)
+ */
+declare function encryptBaselineBlob(simhash: Uint8Array, salt: Uint8Array, key: CryptoKey, walletPubkey: PublicKey, baselinePda: PublicKey, commitment: Uint8Array): Promise<Uint8Array>;
+/**
+ * Thrown when the on-chain blob's auth tag fails to verify under the
+ * current on-chain commitment. Indicates the blob was sealed against a
+ * different commitment (e.g., before a `reset_identity_state`), or the
+ * AAD-binding is otherwise broken. The SDK should fall back to a fresh-
+ * capture flow rather than attempting to recover.
+ */
+declare class StaleEncryptedBaselineError extends Error {
+    constructor(message: string);
+}
+/**
+ * Decrypt a 96-byte versioned envelope back to (simhash, salt).
+ *
+ * Throws `StaleEncryptedBaselineError` on auth-tag mismatch — this is the
+ * cryptographic staleness signal. Other errors indicate a malformed blob.
+ */
+declare function decryptBaselineBlob(blob: Uint8Array, key: CryptoKey, walletPubkey: PublicKey, baselinePda: PublicKey, commitment: Uint8Array): Promise<{
+    simhash: Uint8Array;
+    salt: Uint8Array;
+}>;
+/**
+ * Fetch the user's `EncryptedBaseline` PDA from chain. Returns `null` if
+ * the account has never been initialized (user hasn't called
+ * `set_encrypted_baseline` yet).
+ */
+declare function fetchEncryptedBaseline(walletPubkey: PublicKey, connection: {
+    getAccountInfo: (k: PublicKey) => Promise<unknown>;
+}): Promise<Uint8Array | null>;
+
 /**
  * Fetch identity state from the on-chain IdentityState PDA.
  *
@@ -664,6 +803,48 @@ declare function storeVerificationData(data: StoredVerificationData): Promise<vo
  * Decrypts if encrypted, migrates plaintext to encrypted on first load.
  */
 declare function loadVerificationData(): Promise<StoredVerificationData | null>;
+/**
+ * Outcome of an attempt to recover the local baseline from the on-chain
+ * encrypted blob (master-list #98 cache-clear / cross-device path).
+ *
+ * Reasons distinguish recoverable from terminal failures:
+ *   - `no-on-chain-identity`: caller should treat as first-verification.
+ *   - `no-encrypted-baseline`: identity exists but user has never written
+ *     an encrypted baseline (pre-3.3.0 SDK or pre-#98 deploy). UX should
+ *     surface the existing baseline-missing copy and offer reset.
+ *   - `signing-unavailable`: AES key derivation failed because the wallet
+ *     can't `signMessage` (no method on the adapter, e.g., older Ledger
+ *     firmware) OR the user cancelled the prompt OR the wallet erred. The
+ *     `detail` field carries the specific cause when present.
+ *   - `stale-baseline`: blob predates a `reset_identity_state` cycle.
+ *     Treat as terminal recovery failure; route to fresh-capture flow.
+ *   - `unknown-error`: catch-all (RPC failure, malformed blob, etc.).
+ */
+type BaselineRecoveryReason = "no-on-chain-identity" | "no-encrypted-baseline" | "signing-unavailable" | "stale-baseline" | "unknown-error";
+interface BaselineRecoveryResult {
+    recovered: boolean;
+    reason?: BaselineRecoveryReason;
+    detail?: string;
+}
+/**
+ * Attempt to recover this wallet's local baseline from the on-chain
+ * `EncryptedBaseline` PDA. On success, writes the recovered fingerprint /
+ * salt / commitment / timestamp into the SDK's normal local storage tier
+ * so the next `loadVerificationData()` call returns it transparently.
+ *
+ * Wallet flow on success: ONE `signMessage` prompt (for the AES key
+ * derivation). The wallet's currently-cached key — if `getOrDeriveBaselineKey`
+ * has been called earlier in the session — short-circuits the prompt.
+ *
+ * No-op when:
+ *   - The on-chain `IdentityState` PDA does not exist (treat as first-verify).
+ *   - The on-chain `EncryptedBaseline` PDA does not exist (pre-#98 or wallet
+ *     never had `set_encrypted_baseline` written — UX should offer reset).
+ *   - The wallet lacks `signMessage` (some Ledger firmware versions).
+ *   - The blob's auth tag doesn't verify under the current on-chain
+ *     commitment (stale blob from a prior reset cycle).
+ */
+declare function recoverBaselineFromChain(wallet: BaselineWallet, connection: any): Promise<BaselineRecoveryResult>;
 
 /**
  * FALLBACK challenge-phrase generator. Used only when the executor's
@@ -770,4 +951,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_AUDIO_SAMPLES, MIN_CAPTURE_MS, MIN_MOTION_SAMPLES, MIN_TOUCH_SAMPLES, MOTION_FEATURE_COUNT, 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, TOUCH_FEATURE_COUNT, type TemporalFingerprint, type TouchSample, type VerificationResult, attestAgentOperator, bigintToBytes32, computeCommitment, encodeAudioAsBase64, extractAccelerationMagnitude, extractMotionFeatures, extractMouseDynamics, extractSpeakerFeatures, extractSpeakerFeaturesDetailed, extractTouchFeatures, fetchChallenge, fetchIdentityState, fuseFeatures, fuseRawFeatures, generateLissajousPoints, generateLissajousSequence, generatePhrase, generatePhraseSequence, generateProof, generateSalt, generateSolanaProof, generateTBH, getAgentHumanOperator, hammingDistance, loadVerificationData, packBits, prepareCircuitInput, randomLissajousParams, serializeProof, simhash, storeVerificationData, submitResetViaWallet, submitViaRelayer, submitViaWallet, toBigEndian32, verifyEntrosAttestation };
+export { type AgentHumanOperator, type AudioCapture, type BaselineRecoveryReason, type BaselineRecoveryResult, type BaselineWallet, type CaptureOptions, type CaptureStage, type ChallengeResponse, type CircuitInput, DEFAULT_CAPTURE_MS, DEFAULT_MIN_DISTANCE, DEFAULT_THRESHOLD, ENCRYPTED_BASELINE_BLOB_BYTES, 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, MOTION_FEATURE_COUNT, type MotionSample, PROGRAM_IDS, type PackedFingerprint, type Point2D, type ProofResult, type PulseConfig, PulseSDK, PulseSession, SPEAKER_FEATURE_COUNT, type SensorData, type SolanaProof, type StageState, StaleEncryptedBaselineError, type StatsSummary, type StoredVerificationData, type SubmissionResult, type TBH, TOUCH_FEATURE_COUNT, type TemporalFingerprint, type TouchSample, type VerificationResult, attestAgentOperator, bigintToBytes32, bytes32ToBigint, bytesToFingerprint, clearBaselineKeyCache, computeCommitment, decryptBaselineBlob, deriveBaselineKey, deriveEncryptedBaselinePda, encodeAudioAsBase64, encryptBaselineBlob, extractAccelerationMagnitude, extractMotionFeatures, extractMouseDynamics, extractSpeakerFeatures, extractSpeakerFeaturesDetailed, extractTouchFeatures, fetchChallenge, fetchEncryptedBaseline, fetchIdentityState, fingerprintToBytes, fuseFeatures, fuseRawFeatures, generateLissajousPoints, generateLissajousSequence, generatePhrase, generatePhraseSequence, generateProof, generateSalt, generateSolanaProof, generateTBH, getAgentHumanOperator, getOrDeriveBaselineKey, hammingDistance, loadVerificationData, packBits, prepareCircuitInput, randomLissajousParams, recoverBaselineFromChain, serializeProof, simhash, storeVerificationData, submitResetViaWallet, submitViaRelayer, submitViaWallet, toBigEndian32, verifyEntrosAttestation };

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { PublicKey } from '@solana/web3.js';
+
 declare const FINGERPRINT_BITS = 256;
 declare const DEFAULT_THRESHOLD = 96;
 declare const DEFAULT_MIN_DISTANCE = 3;
@@ -511,6 +513,15 @@ declare function submitViaWallet(proof: SolanaProof, commitment: Uint8Array, opt
      * VerificationResult PDA instead.
      */
     signedReceipt?: SignedReceiptDto;
+    /**
+     * Encrypted baseline blob (master-list #98). When present, the SDK
+     * appends a `set_encrypted_baseline` instruction at the end of the
+     * atomic transaction so the wallet's on-chain baseline is rewritten
+     * to reflect the new fingerprint in the same wallet prompt as the
+     * mint / re-verify. Omitted when the wallet adapter lacks
+     * `signMessage` (the SDK can't derive the AES key without it).
+     */
+    encryptedBaselineBlob?: Uint8Array;
 }): Promise<SubmissionResult>;
 /**
  * Submit a baseline reset on-chain via a connected wallet.
@@ -532,6 +543,15 @@ declare function submitResetViaWallet(commitment: Uint8Array, options: {
     connection: any;
     relayerUrl?: string;
     relayerApiKey?: string;
+    /**
+     * Encrypted baseline blob (master-list #98). When present, the SDK
+     * appends a `set_encrypted_baseline` instruction so the wallet's
+     * on-chain baseline is rewritten under the NEW post-reset commitment
+     * in the same atomic transaction. Without this, the prior blob would
+     * be stale on the next recovery attempt (auth-tag mismatch under the
+     * new commitment in AAD) and recovery would fall back to fresh capture.
+     */
+    encryptedBaselineBlob?: Uint8Array;
 }): Promise<SubmissionResult>;
 
 /**
@@ -630,6 +650,125 @@ interface StoredVerificationData {
     timestamp: number;
 }
 
+/**
+ * Wallet-keyed encrypted baseline storage (master-list #98).
+ *
+ * Architecture: the user's previous SimHash + salt (private witnesses for
+ * the Hamming-distance ZK proof) are encrypted with AES-256-GCM under a
+ * key derived from a deterministic `signMessage` on a domain-separated
+ * payload. The 96-byte ciphertext blob is stored on chain in a per-wallet
+ * `EncryptedBaseline` PDA, making the baseline wallet-portable across
+ * devices and recoverable after a cache wipe.
+ *
+ * The GCM AAD binds (version, algorithm, wallet, baselinePda, current on-
+ * chain commitment). After `reset_identity_state` cycles the commitment,
+ * the old blob's auth-tag fails to verify under the new commitment — that
+ * mismatch IS the staleness signal. No explicit version tracking needed.
+ *
+ * Plaintext biometric data never reaches chain at any point. This module
+ * is the only place wallet-derived key material flows; it never leaves
+ * memory and the key is non-extractable.
+ */
+
+/** Layout: version(1) + algo(1) + reserved(2) + IV(12) + ct+tag(80) */
+declare const ENCRYPTED_BASELINE_BLOB_BYTES = 96;
+/**
+ * Pack a 256-bit fingerprint into 32 bytes. LSB-first within each byte —
+ * the convention is internal to the encrypted-baseline blob; the only
+ * requirement is that `bytesToFingerprint` is its exact inverse.
+ */
+declare function fingerprintToBytes(bits: number[]): Uint8Array;
+/** Inverse of `fingerprintToBytes`. */
+declare function bytesToFingerprint(bytes: Uint8Array): number[];
+/** Big-endian 32-byte → BigInt. Inverse of `bigintToBytes32` in hashing/poseidon. */
+declare function bytes32ToBigint(bytes: Uint8Array): bigint;
+/**
+ * The per-wallet `EncryptedBaseline` PDA address. Owned by entros-anchor.
+ * Seeds: `[b"encrypted_baseline", walletPubkey.toBuffer()]`.
+ */
+declare function deriveEncryptedBaselinePda(walletPubkey: PublicKey): Promise<[PublicKey, number]>;
+/**
+ * Wallet adapter shape needed for key derivation.
+ * Compatible with `@solana/wallet-adapter-base` `WalletAdapter`.
+ */
+interface BaselineWallet {
+    publicKey: PublicKey;
+    signMessage: (msg: Uint8Array) => Promise<Uint8Array>;
+}
+/**
+ * Derive an AES-256 key from the wallet's deterministic signature over
+ * the domain-separated payload, via HKDF-SHA256.
+ *
+ *   IKM  = Ed25519 signature (64 bytes, pseudorandom under RoM)
+ *   salt = wallet pubkey bytes (32 bytes — wallet-binding salt)
+ *   info = "entros-protocol/identity-baseline/v1"
+ *   L    = 32 bytes (AES-256 key length)
+ *
+ * Determinism follows from RFC 8032 Ed25519 signature determinism. Same
+ * wallet + same message → same signature → same key, across any device.
+ *
+ * The derived `CryptoKey` is non-extractable; only WebCrypto can use it
+ * for AES-GCM encrypt/decrypt.
+ *
+ * Throws if the wallet doesn't implement `signMessage` (e.g., some Ledger
+ * firmware versions). Callers should catch and fall back gracefully.
+ */
+declare function deriveBaselineKey(wallet: BaselineWallet): Promise<CryptoKey>;
+/**
+ * Derive the baseline AES key for `wallet`, reusing the cached derivation
+ * when one is in-flight or resolved for this wallet pubkey in the current
+ * page lifetime. The key is deterministic per wallet, so caching is purely
+ * a UX optimization (avoids re-prompting `signMessage` on every verification
+ * within a session). Cache survives a single page load and is dropped on
+ * reload or via `clearBaselineKeyCache`.
+ *
+ * Concurrent calls for the same wallet share one `signMessage` prompt; a
+ * failed derivation evicts the cache entry so subsequent calls re-derive.
+ */
+declare function getOrDeriveBaselineKey(wallet: BaselineWallet): Promise<CryptoKey>;
+/** Drop all cached baseline keys. Test hook + emergency wipe. */
+declare function clearBaselineKeyCache(): void;
+/**
+ * Encrypt (simhash || salt) into a 96-byte versioned envelope.
+ *
+ * @param simhash      32-byte SimHash fingerprint (packed 256 bits)
+ * @param salt         32-byte Poseidon commitment salt
+ * @param key          AES-256-GCM key from `deriveBaselineKey`
+ * @param walletPubkey wallet that owns the EncryptedBaseline PDA
+ * @param baselinePda  the EncryptedBaseline PDA address (bound in AAD)
+ * @param commitment   the on-chain `current_commitment` at encryption time
+ *                     (bound in AAD for staleness detection)
+ */
+declare function encryptBaselineBlob(simhash: Uint8Array, salt: Uint8Array, key: CryptoKey, walletPubkey: PublicKey, baselinePda: PublicKey, commitment: Uint8Array): Promise<Uint8Array>;
+/**
+ * Thrown when the on-chain blob's auth tag fails to verify under the
+ * current on-chain commitment. Indicates the blob was sealed against a
+ * different commitment (e.g., before a `reset_identity_state`), or the
+ * AAD-binding is otherwise broken. The SDK should fall back to a fresh-
+ * capture flow rather than attempting to recover.
+ */
+declare class StaleEncryptedBaselineError extends Error {
+    constructor(message: string);
+}
+/**
+ * Decrypt a 96-byte versioned envelope back to (simhash, salt).
+ *
+ * Throws `StaleEncryptedBaselineError` on auth-tag mismatch — this is the
+ * cryptographic staleness signal. Other errors indicate a malformed blob.
+ */
+declare function decryptBaselineBlob(blob: Uint8Array, key: CryptoKey, walletPubkey: PublicKey, baselinePda: PublicKey, commitment: Uint8Array): Promise<{
+    simhash: Uint8Array;
+    salt: Uint8Array;
+}>;
+/**
+ * Fetch the user's `EncryptedBaseline` PDA from chain. Returns `null` if
+ * the account has never been initialized (user hasn't called
+ * `set_encrypted_baseline` yet).
+ */
+declare function fetchEncryptedBaseline(walletPubkey: PublicKey, connection: {
+    getAccountInfo: (k: PublicKey) => Promise<unknown>;
+}): Promise<Uint8Array | null>;
+
 /**
  * Fetch identity state from the on-chain IdentityState PDA.
  *
@@ -664,6 +803,48 @@ declare function storeVerificationData(data: StoredVerificationData): Promise<vo
  * Decrypts if encrypted, migrates plaintext to encrypted on first load.
  */
 declare function loadVerificationData(): Promise<StoredVerificationData | null>;
+/**
+ * Outcome of an attempt to recover the local baseline from the on-chain
+ * encrypted blob (master-list #98 cache-clear / cross-device path).
+ *
+ * Reasons distinguish recoverable from terminal failures:
+ *   - `no-on-chain-identity`: caller should treat as first-verification.
+ *   - `no-encrypted-baseline`: identity exists but user has never written
+ *     an encrypted baseline (pre-3.3.0 SDK or pre-#98 deploy). UX should
+ *     surface the existing baseline-missing copy and offer reset.
+ *   - `signing-unavailable`: AES key derivation failed because the wallet
+ *     can't `signMessage` (no method on the adapter, e.g., older Ledger
+ *     firmware) OR the user cancelled the prompt OR the wallet erred. The
+ *     `detail` field carries the specific cause when present.
+ *   - `stale-baseline`: blob predates a `reset_identity_state` cycle.
+ *     Treat as terminal recovery failure; route to fresh-capture flow.
+ *   - `unknown-error`: catch-all (RPC failure, malformed blob, etc.).
+ */
+type BaselineRecoveryReason = "no-on-chain-identity" | "no-encrypted-baseline" | "signing-unavailable" | "stale-baseline" | "unknown-error";
+interface BaselineRecoveryResult {
+    recovered: boolean;
+    reason?: BaselineRecoveryReason;
+    detail?: string;
+}
+/**
+ * Attempt to recover this wallet's local baseline from the on-chain
+ * `EncryptedBaseline` PDA. On success, writes the recovered fingerprint /
+ * salt / commitment / timestamp into the SDK's normal local storage tier
+ * so the next `loadVerificationData()` call returns it transparently.
+ *
+ * Wallet flow on success: ONE `signMessage` prompt (for the AES key
+ * derivation). The wallet's currently-cached key — if `getOrDeriveBaselineKey`
+ * has been called earlier in the session — short-circuits the prompt.
+ *
+ * No-op when:
+ *   - The on-chain `IdentityState` PDA does not exist (treat as first-verify).
+ *   - The on-chain `EncryptedBaseline` PDA does not exist (pre-#98 or wallet
+ *     never had `set_encrypted_baseline` written — UX should offer reset).
+ *   - The wallet lacks `signMessage` (some Ledger firmware versions).
+ *   - The blob's auth tag doesn't verify under the current on-chain
+ *     commitment (stale blob from a prior reset cycle).
+ */
+declare function recoverBaselineFromChain(wallet: BaselineWallet, connection: any): Promise<BaselineRecoveryResult>;
 
 /**
  * FALLBACK challenge-phrase generator. Used only when the executor's
@@ -770,4 +951,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_AUDIO_SAMPLES, MIN_CAPTURE_MS, MIN_MOTION_SAMPLES, MIN_TOUCH_SAMPLES, MOTION_FEATURE_COUNT, 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, TOUCH_FEATURE_COUNT, type TemporalFingerprint, type TouchSample, type VerificationResult, attestAgentOperator, bigintToBytes32, computeCommitment, encodeAudioAsBase64, extractAccelerationMagnitude, extractMotionFeatures, extractMouseDynamics, extractSpeakerFeatures, extractSpeakerFeaturesDetailed, extractTouchFeatures, fetchChallenge, fetchIdentityState, fuseFeatures, fuseRawFeatures, generateLissajousPoints, generateLissajousSequence, generatePhrase, generatePhraseSequence, generateProof, generateSalt, generateSolanaProof, generateTBH, getAgentHumanOperator, hammingDistance, loadVerificationData, packBits, prepareCircuitInput, randomLissajousParams, serializeProof, simhash, storeVerificationData, submitResetViaWallet, submitViaRelayer, submitViaWallet, toBigEndian32, verifyEntrosAttestation };
+export { type AgentHumanOperator, type AudioCapture, type BaselineRecoveryReason, type BaselineRecoveryResult, type BaselineWallet, type CaptureOptions, type CaptureStage, type ChallengeResponse, type CircuitInput, DEFAULT_CAPTURE_MS, DEFAULT_MIN_DISTANCE, DEFAULT_THRESHOLD, ENCRYPTED_BASELINE_BLOB_BYTES, 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, MOTION_FEATURE_COUNT, type MotionSample, PROGRAM_IDS, type PackedFingerprint, type Point2D, type ProofResult, type PulseConfig, PulseSDK, PulseSession, SPEAKER_FEATURE_COUNT, type SensorData, type SolanaProof, type StageState, StaleEncryptedBaselineError, type StatsSummary, type StoredVerificationData, type SubmissionResult, type TBH, TOUCH_FEATURE_COUNT, type TemporalFingerprint, type TouchSample, type VerificationResult, attestAgentOperator, bigintToBytes32, bytes32ToBigint, bytesToFingerprint, clearBaselineKeyCache, computeCommitment, decryptBaselineBlob, deriveBaselineKey, deriveEncryptedBaselinePda, encodeAudioAsBase64, encryptBaselineBlob, extractAccelerationMagnitude, extractMotionFeatures, extractMouseDynamics, extractSpeakerFeatures, extractSpeakerFeaturesDetailed, extractTouchFeatures, fetchChallenge, fetchEncryptedBaseline, fetchIdentityState, fingerprintToBytes, fuseFeatures, fuseRawFeatures, generateLissajousPoints, generateLissajousSequence, generatePhrase, generatePhraseSequence, generateProof, generateSalt, generateSolanaProof, generateTBH, getAgentHumanOperator, getOrDeriveBaselineKey, hammingDistance, loadVerificationData, packBits, prepareCircuitInput, randomLissajousParams, recoverBaselineFromChain, serializeProof, simhash, storeVerificationData, submitResetViaWallet, submitViaRelayer, submitViaWallet, toBigEndian32, verifyEntrosAttestation };