@provablehq/sdk 0.11.6 → 0.11.8

package/dist/mainnet/browser.d.cts

@@ -58,6 +58,7 @@ import { BaseFunctionKeyLocator, InvalidLocatorError, InvalidLocatorReason, KeyL
 import { OfflineKeyProvider, OfflineSearchParams } from "./keys/provider/offline.js";
 import { BlockHeightSearch, NetworkRecordProvider, RecordProvider } from "./record-provider.js";
 import { RecordScanner, RecordScannerJWTData, RecordScannerOptions } from "./record-scanner.js";
+import { ApiAuth, ApiAuthConfig, DEFAULT_API_KEY_HEADER, normalizeAuthConfig } from "./api-auth.js";
 import { SealanceMerkleTree } from "./integrations/sealance/merkle-tree.js";
 import { generateHookData } from "./integrations/circle/hook-data.js";
 declare function initializeWasm(): Promise<void>;
@@ -68,7 +69,7 @@ export type { LogLevel } from "./utils/logger.js";
 export { Address, Authorization, Boolean, BHP256, BHP512, BHP768, BHP1024, Ciphertext, ComputeKey, DynamicRecord, Execution as FunctionExecution, ExecutionRequest, ExecutionResponse, EncryptionToolkit, Field, GraphKey, Group, I8, I16, I32, I64, I128, OfflineQuery, QueryOption, Pedersen64, Pedersen128, Plaintext, Poseidon2, Poseidon4, Poseidon8, PrivateKey, PrivateKeyCiphertext, Program, ProgramImportsBuilder, ProgramManager as ProgramManagerBase, Proof, ProvingKey, ProvingRequest, RecordCiphertext, RecordPlaintext, Signature, Scalar, stringToField, Transaction, Transition, U8, U16, U32, U64, U128, Value, VerifyingKey, ViewKey, getMaxProgramImports, initThreadPool, getOrInitConsensusVersionTestHeights, setWasmLogLevel, snarkVerify, snarkVerifyBatch, verifyFunctionExecution, } from "./wasm.js";
 export { initializeWasm };
 export { Key, CREDITS_PROGRAM_KEYS, KEY_STORE, PRIVATE_TRANSFER, PRIVATE_TO_PUBLIC_TRANSFER, PRIVATE_TRANSFER_TYPES, PUBLIC_TRANSFER, PUBLIC_TRANSFER_AS_SIGNER, PUBLIC_TO_PRIVATE_TRANSFER, RECORD_DOMAIN, VALID_TRANSFER_TYPES, } from "./constants.js";
-export { Account, AleoKeyProvider, AleoKeyProviderParams, AleoKeyProviderInitParams, AleoNetworkClient, BlockJSON, BlockHeightSearch, BroadcastResponse, BroadcastResult, CachedKeyPair, ConfirmedTransactionJSON, CryptoBoxPubKey, DecryptionNotEnabledError, DeploymentJSON, DeploymentObject, EncryptedProvingRequest, EncryptedRecord, EncryptedRegistrationRequest, EncryptedRecordsResult, EncryptedRecordsSuccess, ExecutionJSON, ExecutionObject, FeeExecutionJSON, FeeExecutionObject, FinalizeJSON, FunctionInput, FunctionObject, FunctionKeyPair, FunctionKeyProvider, generateHookData, Header, isProvingResponse, isProveApiErrorBody, ImportedPrograms, ImportedVerifyingKeys, IndexedDBKeyStore, InputJSON, InputObject, InvalidLocatorError, InvalidLocatorReason, BaseFunctionKeyLocator, KeyFingerprint, KeyLocator, KeyMetadata, KeySearchParams, KeyStore, KeyType, KeyVerificationError, ProvingKeyLocator, provingKeyLocator, TranslationKeyLocator, translationKeyLocator, VerifyingKeyLocator, verifyingKeyLocator, KeyVerifier, MemKeyVerifier, Metadata, NetworkRecordProvider, OfflineKeyProvider, OfflineSearchParams, OutputJSON, OutputObject, OwnedFilter, OwnedRecord, OwnedRecordsResult, OwnedRecordsResponseFilter, OwnedRecordsSuccess, OwnerJSON, PartialSolutionJSON, PlaintextArray, PlaintextLiteral, PlaintextObject, PlaintextStruct, ProgramImports, ProveApiErrorBody, ProvingFailure, ProvingRequestError, ProvingRequestJSON, ProvingResult, ProvingSuccess, ProvingResponse, RatificationJSON, RecordsFilter, RecordsResponseFilter, RecordProvider, RecordScanner, RecordScannerErrorBody, RecordScannerFailure, RecordScannerJWTData, RecordScannerOptions, RecordNotFoundError, RecordScannerRequestError, ViewKeyNotStoredError, RecordSearchParams, RegisterResult, RegisterSuccess, RegistrationResponse, RevokeResult, RevokeSuccess, RevokeResponse, SealanceMerkleTree, SerialNumbersResult, SerialNumbersSuccess, sha256Hex, SolutionJSON, SolutionsJSON, StatusResponse, StatusResult, StatusSuccess, TagsResult, TagsSuccess, TransactionJSON, TransactionObject, TransitionJSON, TransitionObject, UUIDError, VerifyingKeys, };
+export { Account, AleoKeyProvider, AleoKeyProviderParams, AleoKeyProviderInitParams, AleoNetworkClient, BlockJSON, BlockHeightSearch, BroadcastResponse, BroadcastResult, CachedKeyPair, ConfirmedTransactionJSON, CryptoBoxPubKey, DecryptionNotEnabledError, DeploymentJSON, DeploymentObject, EncryptedProvingRequest, EncryptedRecord, EncryptedRegistrationRequest, EncryptedRecordsResult, EncryptedRecordsSuccess, ExecutionJSON, ExecutionObject, FeeExecutionJSON, FeeExecutionObject, FinalizeJSON, FunctionInput, FunctionObject, FunctionKeyPair, FunctionKeyProvider, generateHookData, Header, isProvingResponse, isProveApiErrorBody, ImportedPrograms, ImportedVerifyingKeys, IndexedDBKeyStore, InputJSON, InputObject, InvalidLocatorError, InvalidLocatorReason, BaseFunctionKeyLocator, KeyFingerprint, KeyLocator, KeyMetadata, KeySearchParams, KeyStore, KeyType, KeyVerificationError, ProvingKeyLocator, provingKeyLocator, TranslationKeyLocator, translationKeyLocator, VerifyingKeyLocator, verifyingKeyLocator, KeyVerifier, MemKeyVerifier, Metadata, NetworkRecordProvider, OfflineKeyProvider, OfflineSearchParams, OutputJSON, OutputObject, OwnedFilter, OwnedRecord, OwnedRecordsResult, OwnedRecordsResponseFilter, OwnedRecordsSuccess, OwnerJSON, PartialSolutionJSON, PlaintextArray, PlaintextLiteral, PlaintextObject, PlaintextStruct, ProgramImports, ProveApiErrorBody, ProvingFailure, ProvingRequestError, ProvingRequestJSON, ProvingResult, ProvingSuccess, ProvingResponse, ApiAuth, ApiAuthConfig, DEFAULT_API_KEY_HEADER, normalizeAuthConfig, RatificationJSON, RecordsFilter, RecordsResponseFilter, RecordProvider, RecordScanner, RecordScannerErrorBody, RecordScannerFailure, RecordScannerJWTData, RecordScannerOptions, RecordNotFoundError, RecordScannerRequestError, ViewKeyNotStoredError, RecordSearchParams, RegisterResult, RegisterSuccess, RegistrationResponse, RevokeResult, RevokeSuccess, RevokeResponse, SealanceMerkleTree, SerialNumbersResult, SerialNumbersSuccess, sha256Hex, SolutionJSON, SolutionsJSON, StatusResponse, StatusResult, StatusSuccess, TagsResult, TagsSuccess, TransactionJSON, TransactionObject, TransitionJSON, TransitionObject, UUIDError, VerifyingKeys, };
 export { KeyVerificationError as ChecksumMismatchError, KeyVerifier as FunctionKeyVerifier, } from "./keys/verifier/interface.js";
 export { encryptAuthorization, encryptProvingRequest, encryptSerializedProvingRequest, encryptViewKey, encryptRegistrationRequest, serializeProvingRequest, zeroizeBytes, } from "./security.js";
 export { toField, toGroup, toViewKey, toSignature, toAddress, isViewKeyStrategy, isInputIdStrategy, isRecordViewKeyStrategy, buildExecutionRequestFromExternallySignedData, computeExternalSigningInputs, } from "./external-signing.js";

package/dist/mainnet/browser.d.ts

@@ -58,6 +58,7 @@ import { BaseFunctionKeyLocator, InvalidLocatorError, InvalidLocatorReason, KeyL
 import { OfflineKeyProvider, OfflineSearchParams } from "./keys/provider/offline.js";
 import { BlockHeightSearch, NetworkRecordProvider, RecordProvider } from "./record-provider.js";
 import { RecordScanner, RecordScannerJWTData, RecordScannerOptions } from "./record-scanner.js";
+import { ApiAuth, ApiAuthConfig, DEFAULT_API_KEY_HEADER, normalizeAuthConfig } from "./api-auth.js";
 import { SealanceMerkleTree } from "./integrations/sealance/merkle-tree.js";
 import { generateHookData } from "./integrations/circle/hook-data.js";
 declare function initializeWasm(): Promise<void>;
@@ -68,7 +69,7 @@ export type { LogLevel } from "./utils/logger.js";
 export { Address, Authorization, Boolean, BHP256, BHP512, BHP768, BHP1024, Ciphertext, ComputeKey, DynamicRecord, Execution as FunctionExecution, ExecutionRequest, ExecutionResponse, EncryptionToolkit, Field, GraphKey, Group, I8, I16, I32, I64, I128, OfflineQuery, QueryOption, Pedersen64, Pedersen128, Plaintext, Poseidon2, Poseidon4, Poseidon8, PrivateKey, PrivateKeyCiphertext, Program, ProgramImportsBuilder, ProgramManager as ProgramManagerBase, Proof, ProvingKey, ProvingRequest, RecordCiphertext, RecordPlaintext, Signature, Scalar, stringToField, Transaction, Transition, U8, U16, U32, U64, U128, Value, VerifyingKey, ViewKey, getMaxProgramImports, initThreadPool, getOrInitConsensusVersionTestHeights, setWasmLogLevel, snarkVerify, snarkVerifyBatch, verifyFunctionExecution, } from "./wasm.js";
 export { initializeWasm };
 export { Key, CREDITS_PROGRAM_KEYS, KEY_STORE, PRIVATE_TRANSFER, PRIVATE_TO_PUBLIC_TRANSFER, PRIVATE_TRANSFER_TYPES, PUBLIC_TRANSFER, PUBLIC_TRANSFER_AS_SIGNER, PUBLIC_TO_PRIVATE_TRANSFER, RECORD_DOMAIN, VALID_TRANSFER_TYPES, } from "./constants.js";
-export { Account, AleoKeyProvider, AleoKeyProviderParams, AleoKeyProviderInitParams, AleoNetworkClient, BlockJSON, BlockHeightSearch, BroadcastResponse, BroadcastResult, CachedKeyPair, ConfirmedTransactionJSON, CryptoBoxPubKey, DecryptionNotEnabledError, DeploymentJSON, DeploymentObject, EncryptedProvingRequest, EncryptedRecord, EncryptedRegistrationRequest, EncryptedRecordsResult, EncryptedRecordsSuccess, ExecutionJSON, ExecutionObject, FeeExecutionJSON, FeeExecutionObject, FinalizeJSON, FunctionInput, FunctionObject, FunctionKeyPair, FunctionKeyProvider, generateHookData, Header, isProvingResponse, isProveApiErrorBody, ImportedPrograms, ImportedVerifyingKeys, IndexedDBKeyStore, InputJSON, InputObject, InvalidLocatorError, InvalidLocatorReason, BaseFunctionKeyLocator, KeyFingerprint, KeyLocator, KeyMetadata, KeySearchParams, KeyStore, KeyType, KeyVerificationError, ProvingKeyLocator, provingKeyLocator, TranslationKeyLocator, translationKeyLocator, VerifyingKeyLocator, verifyingKeyLocator, KeyVerifier, MemKeyVerifier, Metadata, NetworkRecordProvider, OfflineKeyProvider, OfflineSearchParams, OutputJSON, OutputObject, OwnedFilter, OwnedRecord, OwnedRecordsResult, OwnedRecordsResponseFilter, OwnedRecordsSuccess, OwnerJSON, PartialSolutionJSON, PlaintextArray, PlaintextLiteral, PlaintextObject, PlaintextStruct, ProgramImports, ProveApiErrorBody, ProvingFailure, ProvingRequestError, ProvingRequestJSON, ProvingResult, ProvingSuccess, ProvingResponse, RatificationJSON, RecordsFilter, RecordsResponseFilter, RecordProvider, RecordScanner, RecordScannerErrorBody, RecordScannerFailure, RecordScannerJWTData, RecordScannerOptions, RecordNotFoundError, RecordScannerRequestError, ViewKeyNotStoredError, RecordSearchParams, RegisterResult, RegisterSuccess, RegistrationResponse, RevokeResult, RevokeSuccess, RevokeResponse, SealanceMerkleTree, SerialNumbersResult, SerialNumbersSuccess, sha256Hex, SolutionJSON, SolutionsJSON, StatusResponse, StatusResult, StatusSuccess, TagsResult, TagsSuccess, TransactionJSON, TransactionObject, TransitionJSON, TransitionObject, UUIDError, VerifyingKeys, };
+export { Account, AleoKeyProvider, AleoKeyProviderParams, AleoKeyProviderInitParams, AleoNetworkClient, BlockJSON, BlockHeightSearch, BroadcastResponse, BroadcastResult, CachedKeyPair, ConfirmedTransactionJSON, CryptoBoxPubKey, DecryptionNotEnabledError, DeploymentJSON, DeploymentObject, EncryptedProvingRequest, EncryptedRecord, EncryptedRegistrationRequest, EncryptedRecordsResult, EncryptedRecordsSuccess, ExecutionJSON, ExecutionObject, FeeExecutionJSON, FeeExecutionObject, FinalizeJSON, FunctionInput, FunctionObject, FunctionKeyPair, FunctionKeyProvider, generateHookData, Header, isProvingResponse, isProveApiErrorBody, ImportedPrograms, ImportedVerifyingKeys, IndexedDBKeyStore, InputJSON, InputObject, InvalidLocatorError, InvalidLocatorReason, BaseFunctionKeyLocator, KeyFingerprint, KeyLocator, KeyMetadata, KeySearchParams, KeyStore, KeyType, KeyVerificationError, ProvingKeyLocator, provingKeyLocator, TranslationKeyLocator, translationKeyLocator, VerifyingKeyLocator, verifyingKeyLocator, KeyVerifier, MemKeyVerifier, Metadata, NetworkRecordProvider, OfflineKeyProvider, OfflineSearchParams, OutputJSON, OutputObject, OwnedFilter, OwnedRecord, OwnedRecordsResult, OwnedRecordsResponseFilter, OwnedRecordsSuccess, OwnerJSON, PartialSolutionJSON, PlaintextArray, PlaintextLiteral, PlaintextObject, PlaintextStruct, ProgramImports, ProveApiErrorBody, ProvingFailure, ProvingRequestError, ProvingRequestJSON, ProvingResult, ProvingSuccess, ProvingResponse, ApiAuth, ApiAuthConfig, DEFAULT_API_KEY_HEADER, normalizeAuthConfig, RatificationJSON, RecordsFilter, RecordsResponseFilter, RecordProvider, RecordScanner, RecordScannerErrorBody, RecordScannerFailure, RecordScannerJWTData, RecordScannerOptions, RecordNotFoundError, RecordScannerRequestError, ViewKeyNotStoredError, RecordSearchParams, RegisterResult, RegisterSuccess, RegistrationResponse, RevokeResult, RevokeSuccess, RevokeResponse, SealanceMerkleTree, SerialNumbersResult, SerialNumbersSuccess, sha256Hex, SolutionJSON, SolutionsJSON, StatusResponse, StatusResult, StatusSuccess, TagsResult, TagsSuccess, TransactionJSON, TransactionObject, TransitionJSON, TransitionObject, UUIDError, VerifyingKeys, };
 export { KeyVerificationError as ChecksumMismatchError, KeyVerifier as FunctionKeyVerifier, } from "./keys/verifier/interface.js";
 export { encryptAuthorization, encryptProvingRequest, encryptSerializedProvingRequest, encryptViewKey, encryptRegistrationRequest, serializeProvingRequest, zeroizeBytes, } from "./security.js";
 export { toField, toGroup, toViewKey, toSignature, toAddress, isViewKeyStrategy, isInputIdStrategy, isRecordViewKeyStrategy, buildExecutionRequestFromExternallySignedData, computeExternalSigningInputs, } from "./external-signing.js";

package/dist/mainnet/browser.js

@@ -1435,21 +1435,6 @@ async function retryWithBackoff(fn, { maxAttempts = 5, baseDelay = 100, jitter,
     throw new Error("retryWithBackoff: unreachable");
 }
 
-/** Type guard: value is a ProvingResponse. */
-function isProvingResponse(value) {
-    return (typeof value === "object" &&
-        value !== null &&
-        "transaction" in value &&
-        "broadcast_result" in value &&
-        typeof value.broadcast_result === "object");
-}
-/** Type guard: value is a ProveApiErrorBody. */
-function isProveApiErrorBody(value) {
-    return (typeof value === "object" &&
-        value !== null &&
-        "message" in value);
-}
-
 const KEY_STORE = Metadata.baseUrl();
 function convert(metadata) {
     // This looks up the method name in VerifyingKey
@@ -1550,6 +1535,165 @@ const RECORD_DOMAIN = "RecordScannerV0";
 const ZERO_ADDRESS = "aleo1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq3ljyzc";
 const FIVE_MINUTES = 5 * 60 * 1000; // 5 minutes in milliseconds
 
+/** Default header carrying a provisioned API key (e.g. edge.provable.com). */
+const DEFAULT_API_KEY_HEADER = "X-API-Key";
+/**
+ * Normalize legacy auth options into an explicit {@link ApiAuthConfig}.
+ *
+ * Rules, preserving the pre-mode behavior of both clients:
+ * - An explicit `auth` wins. Combining it with legacy fields throws — the caller's intent
+ *   is ambiguous and guessing hides misconfiguration.
+ * - A string `apiKey` (with or without `consumerId`) or a bare `jwtData` selects `jwt` mode.
+ * - An `{ header, value }` apiKey selects `api-key` mode with that header. Combining it with
+ *   a `consumerId` throws: keyed auth has no consumer and the pair would silently pick one.
+ * - Nothing configured selects `none`.
+ */
+function normalizeAuthConfig(options) {
+    if (options.auth) {
+        if (options.apiKey !== undefined || options.consumerId !== undefined || options.jwtData !== undefined) {
+            throw new Error("Pass either `auth` or the legacy apiKey/consumerId/jwtData options, not both");
+        }
+        validateKeyed(options.auth);
+        return options.auth;
+    }
+    if (typeof options.apiKey === "object" && options.apiKey !== null) {
+        if (options.consumerId !== undefined) {
+            throw new Error("A custom-header apiKey cannot be combined with consumerId — keyed auth has no consumer. Use a string apiKey for JWT auth.");
+        }
+        const config = { mode: "api-key", value: options.apiKey.value, header: options.apiKey.header };
+        validateKeyed(config);
+        return config;
+    }
+    if (options.apiKey !== undefined || options.consumerId !== undefined || options.jwtData !== undefined) {
+        return { mode: "jwt", apiKey: options.apiKey, consumerId: options.consumerId, jwtData: options.jwtData };
+    }
+    return { mode: "none" };
+}
+/**
+ * Rejects api-key configurations that would emit an empty or nameless header.
+ *
+ * @param config Any auth configuration; only the api-key mode has anything to check.
+ * @throws When the key value is empty, or a custom header name is given but empty.
+ */
+function validateKeyed(config) {
+    if (config.mode !== "api-key")
+        return;
+    if (!config.value) {
+        throw new Error("api-key auth mode requires a key value. Keys are provisioned, not registered — supply one.");
+    }
+    if (config.header !== undefined && !config.header) {
+        throw new Error("api-key auth header must be a non-empty header name when given.");
+    }
+}
+/**
+ * ApiAuth resolves the auth headers each request must carry, owning the JWT mint/refresh
+ * lifecycle in `jwt` mode. Share one instance across clients that use the same credentials so
+ * only one minter exists and concurrent refreshes are deduplicated.
+ */
+class ApiAuth {
+    config;
+    baseUrl;
+    transport;
+    jwtData;
+    inFlight;
+    warned = false;
+    mintHeaders;
+    /**
+     * @param {ApiAuthConfig} config The auth mode and its material.
+     * @param {string} baseUrl API root origin; `/jwts/{consumerId}` lives here in `jwt` mode.
+     * @param {TransportFunction} transport Transport used for the JWT mint request.
+     * @param {Record<string, string>} [mintHeaders] Extra headers on the mint request (e.g. SDK telemetry).
+     */
+    constructor(config, baseUrl, transport = defaultTransport, mintHeaders = {}) {
+        this.config = config;
+        this.baseUrl = baseUrl;
+        this.transport = transport;
+        this.mintHeaders = mintHeaders;
+        if (config.mode === "jwt")
+            this.jwtData = config.jwtData;
+    }
+    /** The mode this instance authenticates with. */
+    get mode() {
+        return this.config.mode;
+    }
+    /** Replace the stored JWT, e.g. one minted elsewhere. Only meaningful in `jwt` mode. */
+    setJwtData(jwtData) {
+        this.jwtData = jwtData;
+    }
+    /** The stored JWT, when one exists. */
+    getJwtData() {
+        return this.jwtData;
+    }
+    /**
+     * The auth headers a request must carry, refreshing the JWT first when it is stale and a
+     * refresh is possible. Returns an empty object in `none` mode or when `jwt` mode lacks
+     * both a usable token and the material to mint one.
+     */
+    async headers() {
+        if (this.config.mode === "none")
+            return {};
+        if (this.config.mode === "api-key") {
+            return { [this.config.header ?? DEFAULT_API_KEY_HEADER]: this.config.value };
+        }
+        const stale = !this.jwtData || Date.now() >= this.jwtData.expiration - FIVE_MINUTES;
+        if (stale) {
+            const { apiKey, consumerId } = this.config;
+            if (apiKey && consumerId) {
+                this.inFlight ??= this.refreshJwt(apiKey, consumerId).finally(() => {
+                    this.inFlight = undefined;
+                });
+                this.jwtData = await this.inFlight;
+            }
+            else if (!this.jwtData && !this.warned) {
+                this.warned = true;
+                logger.warn("JWT or both apiKey and consumerId are required when using the Provable API");
+            }
+            // A stale JWT that cannot be refreshed is still sent: the server is the
+            // authority on expiry and rejecting locally would break long-lived callers.
+        }
+        return this.jwtData?.jwt ? { Authorization: this.jwtData.jwt } : {};
+    }
+    /**
+     * Refreshes the JWT by making a POST request to /jwts/{consumer_id}.
+     *
+     * @param {string} apiKey The API key to use for the refresh request.
+     * @param {string} consumerId The consumer ID for the JWT endpoint.
+     * @returns {Promise<JWTData>} The new JWT data.
+     */
+    async refreshJwt(apiKey, consumerId) {
+        const response = await post(`${this.baseUrl}/jwts/${consumerId}`, {
+            headers: {
+                ...this.mintHeaders,
+                "X-Provable-API-Key": apiKey,
+            },
+        }, this.transport);
+        const authHeader = response.headers.get("authorization");
+        if (!authHeader) {
+            throw new Error("No authorization header in JWT refresh response");
+        }
+        const body = await response.json();
+        return {
+            jwt: authHeader,
+            expiration: body.exp * 1000, // Convert to milliseconds
+        };
+    }
+}
+
+/** Type guard: value is a ProvingResponse. */
+function isProvingResponse(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "transaction" in value &&
+        "broadcast_result" in value &&
+        typeof value.broadcast_result === "object");
+}
+/** Type guard: value is a ProveApiErrorBody. */
+function isProveApiErrorBody(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "message" in value);
+}
+
 const HEADERS = new Set([
     "x-aleo-sdk-version",
     "x-aleo-environment",
@@ -1580,9 +1724,13 @@ class AleoNetworkClient {
     network;
     transport;
     hasCustomTransport;
+    auth;
     apiKey;
     consumerId;
     jwtData;
+    // The consumer the cached jwtData was minted for, so the cache is never
+    // reused for a different identity on a shared client.
+    jwtConsumerId;
     proverUri;
     recordScannerUri;
     constructor(host, options) {
@@ -1602,7 +1750,7 @@ class AleoNetworkClient {
             else {
                 this.headers = {
                     // This is replaced by the actual version by a Rollup plugin
-                    "X-Aleo-SDK-Version": "0.11.6",
+                    "X-Aleo-SDK-Version": "0.11.8",
                     "X-Aleo-environment": environment(),
                 };
             }
@@ -1614,11 +1762,17 @@ class AleoNetworkClient {
             if (options.recordScannerUri) {
                 this.recordScannerUri = options.recordScannerUri + "/mainnet";
             }
+            // If an explicit auth mode was specified, validate and set it, so a
+            // bad key fails here rather than on the first proving request.
+            if (options.auth) {
+                normalizeAuthConfig({ auth: options.auth });
+                this.auth = options.auth;
+            }
         }
         else {
             this.headers = {
                 // This is replaced by the actual version by a Rollup plugin
-                "X-Aleo-SDK-Version": "0.11.6",
+                "X-Aleo-SDK-Version": "0.11.8",
                 "X-Aleo-environment": environment(),
             };
         }
@@ -3052,33 +3206,6 @@ class AleoNetworkClient {
             throw new Error(`Error posting solution: No response received: ${error.message}`);
         }
     }
-    /**
-     * Refreshes the JWT by making a POST request to /jwts/{consumer_id}
-     *
-     * @param {string} apiKey - The API key for authentication.
-     * @param {string} consumerId - The consumer ID associated with the API key.
-     * @returns {Promise<JwtData>} The JWT token and expiration time
-     */
-    async refreshJwt(apiKey, consumerId) {
-        if (!apiKey || !consumerId) {
-            throw new Error('API key and consumer ID are required to refresh JWT');
-        }
-        const response = await post(`${this.baseUrl}/jwts/${consumerId}`, {
-            headers: {
-                ...this.method("refreshJwt"),
-                'X-Provable-API-Key': apiKey,
-            }
-        }, this.transport);
-        const authHeader = response.headers.get('authorization');
-        if (!authHeader) {
-            throw new Error('No authorization header in JWT refresh response');
-        }
-        const body = await response.json();
-        return {
-            jwt: authHeader,
-            expiration: body.exp * 1000 // Convert to milliseconds
-        };
-    }
     /**
      * Parses a /prove/authorization or /prove/request response. Returns a result object (never throws for 200/400/500/503).
      */
@@ -3141,31 +3268,40 @@ class AleoNetworkClient {
     async submitProvingRequestSafe(options) {
         // Attempt to get the Prover URI first from the options, then from any configured globally, or third try the main configured host.
         const proverUri = (options.url ?? this.proverUri) ?? this.host;
-        // Try to get JWT data to access the Provable API.
-        const apiKey = options.apiKey ?? this.apiKey;
-        const consumerId = options.consumerId ?? this.consumerId;
-        let jwtData = options.jwtData ?? this.jwtData;
-        // Check to see if the JWT needs refreshing. Runs before parsing the
-        // proving request so JWT refresh errors propagate as they always have.
-        const isExpired = jwtData && Date.now() >= jwtData.expiration - FIVE_MINUTES;
-        if (!jwtData || isExpired) {
-            if (apiKey && consumerId) {
-                jwtData = await this.refreshJwt(apiKey, consumerId);
-                this.jwtData = jwtData;
-                options.jwtData = jwtData;
-            }
-            else {
-                logger.warn('JWT or both apiKey and consumerId are required when using the Provable API');
-            }
+        // Resolve the auth mode: per-request, then client-wide, then the legacy fields.
+        // Mixing an explicit per-request auth with per-request legacy fields is
+        // ambiguous, so it throws — matching normalizeAuthConfig and RecordScanner.
+        if (options.auth && (options.apiKey !== undefined || options.consumerId !== undefined || options.jwtData !== undefined)) {
+            throw new Error("Pass either `auth` or the legacy apiKey/consumerId/jwtData options, not both");
+        }
+        const config = options.auth ?? this.auth ?? normalizeAuthConfig({
+            apiKey: options.apiKey ?? this.apiKey,
+            consumerId: options.consumerId ?? this.consumerId,
+            jwtData: options.jwtData ?? this.jwtData,
+        });
+        const auth = new ApiAuth(config, this.baseUrl, this.transport, this.method("refreshJwt"));
+        // Seed the cached token so an explicit jwt config reuses it until the
+        // refresh window instead of minting on every request — but only for the
+        // consumer that minted it, so per-request credentials on a shared
+        // client never ride another identity's token.
+        if (config.mode === "jwt" && !config.jwtData && this.jwtData && config.consumerId === this.jwtConsumerId) {
+            auth.setJwtData(this.jwtData);
+        }
+        // Resolves the auth headers, which refreshes the JWT when it is stale. Runs before
+        // parsing the proving request so JWT refresh errors propagate as they always have.
+        const authHeaders = await auth.headers();
+        const jwtData = auth.getJwtData();
+        if (config.mode === "jwt" && jwtData) {
+            this.jwtData = jwtData;
+            this.jwtConsumerId = config.consumerId;
+            options.jwtData = jwtData;
         }
         // Create the necessary headers to hit the provable api.
         const headers = {
             ...this.method("submitProvingRequest"),
             "Content-Type": "application/json",
+            ...authHeaders,
         };
-        if (jwtData?.jwt) {
-            headers["Authorization"] = jwtData.jwt;
-        }
         // Send the proving request encrypted (libsodium-compatible sealed box).
         // Used by both `/prove/authorization` (Authorization variant) and
         // `/prove/request` (Request variant). The legacy plaintext `/prove`
@@ -4718,9 +4854,10 @@ class RecordScanner {
     cacheViewKeysOnRegister;
     url;
     baseUrl;
-    apiKey;
+    auth;
+    explicitAuth;
+    legacyApiKey;
     consumerId;
-    jwtData;
     uuid;
     viewKeys;
     autoReRegister;
@@ -4757,23 +4894,71 @@ class RecordScanner {
             // Add the view key to the scanner's view keys.
             this.addViewKey(this.account.viewKey());
         }
-        // Configure authentication options.
-        this.apiKey = typeof options.apiKey === "string" ? {
-            header: "X-Provable-API-Key",
-            value: options.apiKey
-        } : options.apiKey;
+        // Configure authentication options. Validated up front so an explicit
+        // auth combined with the legacy fields throws instead of the legacy key
+        // leaking onto requests the explicit mode should own.
+        normalizeAuthConfig(options);
+        this.explicitAuth = options.auth;
+        this.legacyApiKey = options.apiKey;
         this.consumerId = options.consumerId;
-        this.jwtData = options.jwtData;
+        this.auth = this.buildAuth(options.jwtData);
         this.autoReRegister = options.autoReRegister;
         this.decryptEnabled = options.decryptEnabled;
     }
+    /**
+     * Builds the ApiAuth for the current auth configuration. An explicit `auth` option wins;
+     * the legacy apiKey/consumerId fields normalize onto a mode otherwise.
+     *
+     * @param {RecordScannerJWTData} [jwtData] JWT to carry into the rebuilt auth.
+     * @returns {ApiAuth} The auth for the current configuration.
+     */
+    buildAuth(jwtData) {
+        const config = this.explicitAuth ?? normalizeAuthConfig({
+            apiKey: this.legacyApiKey,
+            consumerId: this.consumerId,
+            jwtData,
+        });
+        const auth = new ApiAuth(config, this.baseUrl, this.transport);
+        if (jwtData)
+            auth.setJwtData(jwtData);
+        return auth;
+    }
+    /**
+     * Legacy raw-key header echoed on every request alongside the mode's own headers, matching
+     * the pre-mode wire behavior when the legacy apiKey option is used.
+     *
+     * @returns {{ header: string, value: string } | undefined} The raw key header, when a legacy apiKey is set.
+     */
+    rawKeyHeader() {
+        if (this.legacyApiKey === undefined)
+            return undefined;
+        return typeof this.legacyApiKey === "string"
+            ? { header: "X-Provable-API-Key", value: this.legacyApiKey }
+            : this.legacyApiKey;
+    }
     /**
      * Set the API key to use for the record scanner.
      *
      * @param {string | { header: string, value: string }} apiKey The API key to use for the record scanner.
      */
     setApiKey(apiKey) {
-        this.apiKey = typeof apiKey === "string" ? { header: "X-Provable-API-Key", value: apiKey } : apiKey;
+        if (this.explicitAuth) {
+            throw new Error("This scanner uses an explicit auth mode — replace it with setAuth instead of the legacy setApiKey");
+        }
+        this.legacyApiKey = apiKey;
+        this.auth = this.buildAuth(this.auth.getJwtData());
+    }
+    /**
+     * Set the explicit auth mode, replacing any legacy apiKey/consumerId configuration.
+     *
+     * @param {ApiAuthConfig} auth The auth mode and its material.
+     */
+    setAuth(auth) {
+        normalizeAuthConfig({ auth });
+        this.explicitAuth = auth;
+        this.legacyApiKey = undefined;
+        this.consumerId = undefined;
+        this.auth = this.buildAuth();
     }
     /**
      * Set the consumer ID used for JWT refresh when using authenticated record scanner (e.g. Provable API).
@@ -4781,7 +4966,11 @@ class RecordScanner {
      * @param {string} consumerId The consumer ID to use for JWT refresh.
      */
     setConsumerId(consumerId) {
+        if (this.explicitAuth) {
+            throw new Error("This scanner uses an explicit auth mode — replace it with setAuth instead of the legacy setConsumerId");
+        }
         this.consumerId = consumerId;
+        this.auth = this.buildAuth(this.auth.getJwtData());
     }
     /**
      * Set JWT data for authentication. Optional; when not set, JWT can be refreshed from apiKey + consumerId if provided.
@@ -4789,7 +4978,7 @@ class RecordScanner {
      * @param {RecordScannerJWTData | undefined} jwtData The JWT data to use, or undefined to clear.
      */
     setJwtData(jwtData) {
-        this.jwtData = jwtData;
+        this.auth.setJwtData(jwtData);
     }
     /**
      * Set whether /owned should automatically re-register on 422 (when a view key for the UUID is in viewKeys or account) and retry once.
@@ -4862,54 +5051,6 @@ class RecordScanner {
             this.removeViewKey(this.computeUUID(existingVk).toString());
         }
     }
-    /**
-     * Refreshes the JWT by making a POST request to /jwts/{consumer_id}. Used when authentication is required.
-     *
-     * @param {string} apiKey The API key to use for the refresh request.
-     * @param {string} consumerId The consumer ID for the JWT endpoint.
-     * @returns {Promise<RecordScannerJWTData>} The new JWT data.
-     */
-    async refreshJwt(apiKey, consumerId) {
-        const response = await post(`${this.baseUrl}/jwts/${consumerId}`, {
-            headers: {
-                "X-Provable-API-Key": apiKey,
-            },
-        }, this.transport);
-        const authHeader = response.headers.get("authorization");
-        if (!authHeader) {
-            throw new Error("No authorization header in JWT refresh response");
-        }
-        const body = await response.json();
-        return {
-            jwt: authHeader,
-            expiration: body.exp * 1000, // Convert to milliseconds
-        };
-    }
-    /**
-     * Returns auth headers (e.g. Authorization with JWT). Refreshes JWT if expired and apiKey + consumerId are set. Empty when auth is not configured.
-     *
-     * @returns {Promise<Record<string, string>>} Auth headers to add to requests, or empty object when not configured.
-     */
-    async getAuthHeaders() {
-        let jwtData = this.jwtData;
-        // Consider JWT expired a few minutes early to avoid race at boundary.
-        const isExpired = jwtData && Date.now() >= jwtData.expiration - FIVE_MINUTES;
-        if (!jwtData || isExpired) {
-            const apiKey = this.apiKey?.value;
-            if (apiKey && this.consumerId) {
-                jwtData = await this.refreshJwt(apiKey, this.consumerId);
-                this.jwtData = jwtData;
-            }
-            else if (jwtData?.jwt) {
-                // Use existing JWT even if expired when refresh is not possible.
-                return { Authorization: jwtData.jwt };
-            }
-            else {
-                return {};
-            }
-        }
-        return jwtData?.jwt ? { Authorization: jwtData.jwt } : {};
-    }
     /**
      * Set the UUID for the record scanner.
      *
@@ -5414,13 +5555,15 @@ class RecordScanner {
      */
     async request(req) {
         try {
-            // Attach JWT (if configured) and API key before sending.
-            const authHeaders = await this.getAuthHeaders();
+            // Attach the mode's auth headers before sending.
+            const authHeaders = await this.auth.headers();
             for (const [key, value] of Object.entries(authHeaders)) {
                 req.headers.set(key, value);
             }
-            if (this.apiKey) {
-                req.headers.set(this.apiKey.header, this.apiKey.value);
+            // Legacy apiKey callers also got their raw key echoed on every request.
+            const rawKey = this.rawKeyHeader();
+            if (rawKey) {
+                req.headers.set(rawKey.header, rawKey.value);
             }
             const body = req.body ? await req.text() : undefined;
             const plainHeaders = {};
@@ -8700,7 +8843,7 @@ class ProgramManager {
      * import { AleoKeyProvider, getOrInitConsensusVersionTestHeights, ProgramManager, NetworkRecordProvider } from "@provablehq/sdk/mainnet.js";
      *
      * // Initialize the development consensus heights in order to work with devnode.
-     * getOrInitConsensusVersionTestHeights("0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17");
+     * getOrInitConsensusVersionTestHeights("0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18");
      *
      * // Create a new NetworkClient and RecordProvider.
      * const recordProvider = new NetworkRecordProvider(account, networkClient);
@@ -8827,7 +8970,7 @@ class ProgramManager {
      * import { ProgramManager, NetworkRecordProvider, getOrInitConsensusVersionTestHeights } from "@provablehq/sdk/mainnet.js";
      *
      * // Initialize the development consensus heights in order to work with a local devnode.
-     * getOrInitConsensusVersionTestHeights("0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17");
+     * getOrInitConsensusVersionTestHeights("0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18");
      *
      * // Create a new NetworkClient, and RecordProvider
      * const recordProvider = new NetworkRecordProvider(account, networkClient);
@@ -9373,5 +9516,5 @@ async function initializeWasm() {
     logger.warn("initializeWasm is deprecated, you no longer need to use it");
 }
 
-export { Account, AleoKeyProvider, AleoKeyProviderParams, AleoNetworkClient, BlockHeightSearch, CREDITS_PROGRAM_KEYS, KeyVerificationError as ChecksumMismatchError, DecryptionNotEnabledError, IndexedDBKeyStore, InvalidLocatorError, KEY_STORE, KeyVerificationError, MemKeyVerifier, NetworkRecordProvider, OfflineKeyProvider, OfflineSearchParams, PRIVATE_TO_PUBLIC_TRANSFER, PRIVATE_TRANSFER, PRIVATE_TRANSFER_TYPES, PUBLIC_TO_PRIVATE_TRANSFER, PUBLIC_TRANSFER, PUBLIC_TRANSFER_AS_SIGNER, PreparedProgram, ProgramManager, RECORD_DOMAIN, RecordNotFoundError, RecordScanner, RecordScannerRequestError, SealanceMerkleTree, UUIDError, VALID_TRANSFER_TYPES, ViewKeyNotStoredError, buildExecutionRequestFromExternallySignedData, computeExternalSigningInputs, cookieAffinityTransport, defaultTransport, encryptAuthorization, encryptProvingRequest, encryptRegistrationRequest, encryptSerializedProvingRequest, encryptViewKey, generateHookData, getLogLevel, initializeWasm, inputsToFields, isInputIdStrategy, isProveApiErrorBody, isProvingResponse, isRecordViewKeyStrategy, isViewKeyStrategy, logAndThrow, programChecksum, provingKeyLocator, serializeProvingRequest, setLogLevel, sha256Hex, toAddress, toField, toGroup, toSignature, toViewKey, translationKeyLocator, verifyBatchProof, verifyProof, verifyingKeyLocator, zeroizeBytes };
+export { Account, AleoKeyProvider, AleoKeyProviderParams, AleoNetworkClient, ApiAuth, BlockHeightSearch, CREDITS_PROGRAM_KEYS, KeyVerificationError as ChecksumMismatchError, DEFAULT_API_KEY_HEADER, DecryptionNotEnabledError, IndexedDBKeyStore, InvalidLocatorError, KEY_STORE, KeyVerificationError, MemKeyVerifier, NetworkRecordProvider, OfflineKeyProvider, OfflineSearchParams, PRIVATE_TO_PUBLIC_TRANSFER, PRIVATE_TRANSFER, PRIVATE_TRANSFER_TYPES, PUBLIC_TO_PRIVATE_TRANSFER, PUBLIC_TRANSFER, PUBLIC_TRANSFER_AS_SIGNER, PreparedProgram, ProgramManager, RECORD_DOMAIN, RecordNotFoundError, RecordScanner, RecordScannerRequestError, SealanceMerkleTree, UUIDError, VALID_TRANSFER_TYPES, ViewKeyNotStoredError, buildExecutionRequestFromExternallySignedData, computeExternalSigningInputs, cookieAffinityTransport, defaultTransport, encryptAuthorization, encryptProvingRequest, encryptRegistrationRequest, encryptSerializedProvingRequest, encryptViewKey, generateHookData, getLogLevel, initializeWasm, inputsToFields, isInputIdStrategy, isProveApiErrorBody, isProvingResponse, isRecordViewKeyStrategy, isViewKeyStrategy, logAndThrow, normalizeAuthConfig, programChecksum, provingKeyLocator, serializeProvingRequest, setLogLevel, sha256Hex, toAddress, toField, toGroup, toSignature, toViewKey, translationKeyLocator, verifyBatchProof, verifyProof, verifyingKeyLocator, zeroizeBytes };
 //# sourceMappingURL=browser.js.map