@provablehq/sdk 0.11.6 → 0.11.8

package/dist/mainnet/browser.cjs

@@ -1436,21 +1436,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 = mainnet_js.Metadata.baseUrl();
 function convert(metadata) {
     // This looks up the method name in VerifyingKey
@@ -1551,6 +1536,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",
@@ -1581,9 +1725,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) {
@@ -1603,7 +1751,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(),
                 };
             }
@@ -1615,11 +1763,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(),
             };
         }
@@ -3053,33 +3207,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).
      */
@@ -3142,31 +3269,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`
@@ -4719,9 +4855,10 @@ class RecordScanner {
     cacheViewKeysOnRegister;
     url;
     baseUrl;
-    apiKey;
+    auth;
+    explicitAuth;
+    legacyApiKey;
     consumerId;
-    jwtData;
     uuid;
     viewKeys;
     autoReRegister;
@@ -4758,23 +4895,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).
@@ -4782,7 +4967,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.
@@ -4790,7 +4979,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.
@@ -4863,54 +5052,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.
      *
@@ -5415,13 +5556,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 = {};
@@ -8701,7 +8844,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);
@@ -8828,7 +8971,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);
@@ -9618,9 +9761,11 @@ exports.Account = Account;
 exports.AleoKeyProvider = AleoKeyProvider;
 exports.AleoKeyProviderParams = AleoKeyProviderParams;
 exports.AleoNetworkClient = AleoNetworkClient;
+exports.ApiAuth = ApiAuth;
 exports.BlockHeightSearch = BlockHeightSearch;
 exports.CREDITS_PROGRAM_KEYS = CREDITS_PROGRAM_KEYS;
 exports.ChecksumMismatchError = KeyVerificationError;
+exports.DEFAULT_API_KEY_HEADER = DEFAULT_API_KEY_HEADER;
 exports.DecryptionNotEnabledError = DecryptionNotEnabledError;
 exports.IndexedDBKeyStore = IndexedDBKeyStore;
 exports.InvalidLocatorError = InvalidLocatorError;
@@ -9665,6 +9810,7 @@ exports.isProvingResponse = isProvingResponse;
 exports.isRecordViewKeyStrategy = isRecordViewKeyStrategy;
 exports.isViewKeyStrategy = isViewKeyStrategy;
 exports.logAndThrow = logAndThrow;
+exports.normalizeAuthConfig = normalizeAuthConfig;
 exports.programChecksum = programChecksum;
 exports.provingKeyLocator = provingKeyLocator;
 exports.serializeProvingRequest = serializeProvingRequest;