@provablehq/veil-aleo-sdk 0.6.0 → 0.7.1

package/dist/index.js

@@ -23,6 +23,36 @@ import {
   extractTransitions
 } from "@provablehq/veil-core";
 
+// src/utils/rss.ts
+import {
+  assertValidRecordFilter,
+  resolveScanPrograms
+} from "@provablehq/veil-core";
+function presentList(values) {
+  return values && values.length > 0 ? values : void 0;
+}
+function buildOwnedFilter(params) {
+  const filter = params.filter;
+  assertValidRecordFilter(filter);
+  const wireFilter = Object.fromEntries(
+    Object.entries({
+      programs: resolveScanPrograms(params),
+      records: presentList(filter?.records),
+      functions: presentList(filter?.functions),
+      commitments: presentList(filter?.commitments),
+      start: filter?.start,
+      end: filter?.end,
+      results_per_page: filter?.resultsPerPage,
+      page: filter?.page
+    }).filter(([, value]) => value !== void 0)
+  );
+  const body = {};
+  if (params.statusFilter === "unspent") body.unspent = true;
+  else if (params.statusFilter === "spent") body.unspent = false;
+  if (Object.keys(wireFilter).length > 0) body.filter = wireFilter;
+  return body;
+}
+
 // src/mnemonic.ts
 import { hmac } from "@noble/hashes/hmac";
 import { sha512 } from "@noble/hashes/sha512";
@@ -163,11 +193,168 @@ function mnemonicToHDKey(mnemonic, options = {}) {
   return BLS12377HDKey.fromMasterSeed(seed).derivePath(DERIVATION_PATHS[derivation]).deriveChild(index);
 }
 
+// src/provableApi.ts
+var DEFAULT_PROVABLE_API_URL = "https://api.provable.com";
+var EXPIRY_SKEW_MS = 5 * 60 * 1e3;
+function memoryCredentialStore(initial) {
+  let held = initial;
+  return {
+    load: () => held,
+    save: (credentials) => {
+      held = credentials;
+    }
+  };
+}
+async function registerProvableApi(params) {
+  const baseUrl = params.baseUrl ?? DEFAULT_PROVABLE_API_URL;
+  const transport = params.transport ?? fetch;
+  const response = await transport(`${baseUrl}/consumers`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ username: params.username })
+  });
+  if (!response.ok) {
+    const body2 = await response.text();
+    if (response.status === 409) {
+      throw new Error(
+        `Provable API username '${params.username}' is already registered. Credentials cannot be recovered from a username: supply the existing consumerId and apiKey, or register under a different name. (HTTP 409: ${body2})`
+      );
+    }
+    throw new Error(
+      `Provable API consumer registration failed (HTTP ${response.status}): ${body2}`
+    );
+  }
+  const body = await response.json();
+  if (!body.consumer?.id || !body.key) {
+    throw new Error("Provable API consumer registration response carried no consumer id and key.");
+  }
+  return { consumerId: body.consumer.id, apiKey: body.key };
+}
+async function mintJwt(credentials, baseUrl, transport) {
+  const response = await transport(`${baseUrl}/jwts/${encodeURIComponent(credentials.consumerId)}`, {
+    method: "POST",
+    headers: { "X-Provable-API-Key": credentials.apiKey }
+  });
+  if (!response.ok) {
+    throw new Error(
+      `Provable API JWT mint failed (HTTP ${response.status}): ${await response.text()}`
+    );
+  }
+  const header = response.headers.get("authorization");
+  if (!header) {
+    throw new Error("Provable API JWT mint response carried no authorization header.");
+  }
+  const body = await response.json();
+  if (typeof body.exp !== "number") {
+    throw new Error("Provable API JWT mint response carried no exp claim.");
+  }
+  return { jwt: header, expiration: body.exp * 1e3 };
+}
+function createProvableSession(options = {}) {
+  const baseUrl = options.baseUrl ?? DEFAULT_PROVABLE_API_URL;
+  const transport = options.transport ?? fetch;
+  const consumers = { proving: false, recordScanning: false };
+  let credentials = options.credentials;
+  let registered = false;
+  let credentialsInFlight;
+  let jwt;
+  let jwtInFlight;
+  async function resolveCredentials(usernameOverride) {
+    if (credentials) return credentials;
+    const stored = await options.store?.load();
+    if (stored) {
+      credentials = stored;
+      return credentials;
+    }
+    const username = usernameOverride ?? (typeof options.username === "function" ? options.username() : options.username);
+    if (!username) {
+      throw new Error(
+        "No Provable API credentials available \u2014 pass credentials, a store holding them, or a username to register with."
+      );
+    }
+    const issued = await registerProvableApi({ username, baseUrl, transport });
+    credentials = issued;
+    registered = true;
+    try {
+      await options.store?.save(issued);
+    } catch (cause) {
+      throw new Error(
+        `Registered Provable API consumer ${issued.consumerId}, but persisting its credentials failed. They are live for this process \u2014 read them from getCredentials() and store them yourself \u2014 but the API key cannot be reissued, so a restart loses it.`,
+        { cause }
+      );
+    }
+    return credentials;
+  }
+  function getCredentials({ username } = {}) {
+    credentialsInFlight ??= resolveCredentials(username).finally(() => {
+      credentialsInFlight = void 0;
+    });
+    return credentialsInFlight;
+  }
+  function getJwt({ forceRefresh = false } = {}) {
+    const stale = !jwt || Date.now() >= jwt.expiration - EXPIRY_SKEW_MS;
+    if (!forceRefresh && !stale) return Promise.resolve(jwt);
+    jwtInFlight ??= (async () => {
+      const resolved = await getCredentials();
+      jwt = await mintJwt(resolved, baseUrl, transport);
+      return jwt;
+    })().finally(() => {
+      jwtInFlight = void 0;
+    });
+    return jwtInFlight;
+  }
+  return {
+    registeredConsumer: () => registered,
+    getCredentials,
+    getJwt,
+    consumers,
+    attach: (consumer) => {
+      consumers[consumer] = true;
+    }
+  };
+}
+function getProvableSession(client) {
+  return client.proving?.session;
+}
+async function authenticateProvableApi(client, params = {}) {
+  if (client.proving?.keyedAuth) {
+    throw new Error(
+      "This client authenticates with a provisioned API key \u2014 every request already carries it, and there is no consumer or JWT to resolve. Remove the authenticateProvableApi call."
+    );
+  }
+  const session = getProvableSession(client);
+  if (!session) {
+    throw new Error(
+      "No Provable API session on this client \u2014 pass consumerId and apiKey, or a credentialStore, when creating it."
+    );
+  }
+  const credentials = await session.getCredentials({ username: params.username });
+  const { expiration } = await session.getJwt({ forceRefresh: params.forceRefresh });
+  return {
+    credentials,
+    expiration,
+    registered: session.registeredConsumer(),
+    applied: { ...session.consumers }
+  };
+}
+function provableApiActions() {
+  return (client) => ({
+    authenticateProvableApi: (params) => authenticateProvableApi(client, params)
+  });
+}
+
 // src/index.ts
+var DEFAULT_PROVER_URL = "https://api.provable.com/prove";
+var DEFAULT_SCANNER_URL = "https://api.provable.com/scanner";
 async function loadNetwork(name) {
   const sdk = await loadSdk(name);
+  silenceSdkLogs(sdk);
   return buildSdk(name, sdk);
 }
+function silenceSdkLogs(sdk) {
+  const { setLogLevel } = sdk;
+  setLogLevel?.("silent");
+}
 function buildSdk(initialNetwork, initialSdk) {
   let currentSdk = initialSdk;
   const network = initialNetwork;
@@ -207,12 +394,35 @@ function buildSdk(initialNetwork, initialSdk) {
     return new AleoNetworkClient(url);
   }
   function createProvingConfig(options) {
+    assertKeyedAuthAlone(options.auth, {
+      session: options.session,
+      apiKey: options.apiKey,
+      consumerId: options.consumerId
+    });
     let networkUrl = options.networkUrl;
     let keyProvider = new currentSdk.AleoKeyProvider();
     keyProvider.useCache(true);
+    options.session?.attach("proving");
+    let configNetwork = network;
+    const resolveProverUrl = () => {
+      const configured = options.proverUrl ?? (options.mode === "delegated" ? DEFAULT_PROVER_URL : void 0);
+      if (!configured) return void 0;
+      const base = configured.replace(/\/+$/, "").replace(/\/(mainnet|testnet)$/, "");
+      return `${base}/${configNetwork}`;
+    };
     return {
       mode: options.mode,
-      url: options.proverUrl,
+      // A getter, not a snapshot: the network segment moves with `switchChain`,
+      // and a fixed string here would report the network this config started on
+      // long after it left.
+      get url() {
+        return resolveProverUrl();
+      },
+      // Carried for `authenticateProvableApi` to find on a client. Core never
+      // reads binding-specific fields on a proving config — `url` and `apiKey`
+      // already travel the same way.
+      session: options.session,
+      keyedAuth: options.auth,
       buildTransaction: async (txOptions) => {
         const programManager = new currentSdk.ProgramManager(
           networkUrl,
@@ -305,9 +515,10 @@ function buildSdk(initialNetwork, initialSdk) {
           const ct = RecordCiphertext.fromString(ciphertext);
           return ct.isOwner(accountViewKey) ? ct.decrypt(accountViewKey).toString() : null;
         } : void 0;
-        const buildPollingClient = () => createPublicClient({ transport: http(networkUrl, { network }) });
+        const buildPollingClient = () => createPublicClient({ transport: http(networkUrl, { network: configNetwork }) });
         if (options.mode === "delegated") {
-          if (!options.proverUrl) throw new ConfigurationError("Delegated execution requires proverUrl. Pass proverUrl to createProvingConfig or createAleoClient.");
+          const proverUrl = resolveProverUrl();
+          if (!proverUrl) throw new ConfigurationError("Delegated execution requires proverUrl. Pass proverUrl to createProvingConfig or createAleoClient.");
           let response;
           try {
             const provingRequest = await programManager.provingRequest({
@@ -321,13 +532,33 @@ function buildSdk(initialNetwork, initialSdk) {
               broadcast: true,
               useFeeMaster: options.useFeeMaster ?? true
             });
-            const dpsClient = new AleoNetworkClient(options.proverUrl);
-            response = await dpsClient.submitProvingRequest({
+            const dpsClient = new AleoNetworkClient(proverUrl);
+            const auth = async (forceRefresh) => {
+              if (options.auth) return { auth: options.auth };
+              if (options.session) return { jwtData: await options.session.getJwt({ forceRefresh }) };
+              return { apiKey: options.apiKey, consumerId: options.consumerId };
+            };
+            let credentials = await auth(false);
+            let result = await dpsClient.submitProvingRequestSafe({
               provingRequest,
-              url: options.proverUrl,
-              apiKey: options.apiKey,
-              consumerId: options.consumerId
+              url: proverUrl,
+              ...credentials
             });
+            if (!result.ok && (result.status === 401 || result.status === 403) && options.session) {
+              credentials = await auth(true);
+              result = await dpsClient.submitProvingRequestSafe({
+                provingRequest,
+                url: proverUrl,
+                ...credentials
+              });
+            }
+            if (!result.ok) {
+              throw new ProvingError({
+                message: `Delegated proving failed (HTTP ${result.status}): ${result.error?.message ?? "unknown error"}`,
+                statusCode: result.status
+              });
+            }
+            response = result.data;
           } catch (e) {
             if (e instanceof BaseError) throw e;
             throw classifyProvingError(e);
@@ -382,8 +613,10 @@ function buildSdk(initialNetwork, initialSdk) {
           );
         }
         currentSdk = await loadSdk(newNetwork);
+        silenceSdkLogs(currentSdk);
         keyProvider = new currentSdk.AleoKeyProvider();
         keyProvider.useCache(true);
+        configNetwork = newNetwork;
       }
     };
   }
@@ -428,43 +661,74 @@ function buildSdk(initialNetwork, initialSdk) {
       }
     };
   }
-  async function scanOwned(scanner, program, statusFilter, canReMint) {
+  function assertKeyedAuthAlone(auth, conflicts) {
+    if (!auth) return;
+    const named = Object.keys(conflicts).filter((key) => conflicts[key]);
+    if (named.length) {
+      throw new ConfigurationError(
+        `Provisioned-key auth is mutually exclusive with ${named.join(", ")} \u2014 edge API keys are handed out, not registered.`
+      );
+    }
+  }
+  async function scanOwned(scanner, params, hasCredentials, session) {
+    const ownedFilter = buildOwnedFilter(params);
     const ALWAYS_RETRY = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
     const AUTH_RETRY = /* @__PURE__ */ new Set([401, 403]);
+    const canReMint = hasCredentials || !!session;
     const retryable = (status) => ALWAYS_RETRY.has(status) || canReMint && AUTH_RETRY.has(status);
     const MAX_ATTEMPTS = 4;
     let last = "";
+    let lastStatus;
     for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
       try {
-        const result = await scanner.owned({
-          unspent: statusFilter !== "spent",
-          filter: { programs: [program] }
-        });
+        const result = await scanner.owned(ownedFilter);
         if (result.ok) return (result.data ?? []).map((r) => toOwnedRecord(r));
         last = `HTTP ${result.status}: ${result.error?.message ?? "unknown error"}`;
+        lastStatus = result.status;
         if (!retryable(result.status)) break;
       } catch (err) {
         last = err instanceof Error ? err.message : String(err);
+        lastStatus = void 0;
       }
       if (attempt === MAX_ATTEMPTS - 1) break;
-      scanner.setJwtData(void 0);
+      if (lastStatus !== void 0 && AUTH_RETRY.has(lastStatus)) {
+        if (session) scanner.setJwtData(await session.getJwt({ forceRefresh: true }));
+        else scanner.setJwtData(void 0);
+      }
       await new Promise((resolve) => setTimeout(resolve, 500 * 2 ** attempt));
     }
     throw new Error(`Record scan failed (${last})`);
   }
-  function createRemoteScanner(options) {
+  function createRemoteScanner(options = {}) {
+    assertKeyedAuthAlone(options.auth, {
+      session: options.session,
+      apiKey: options.apiKey,
+      consumerId: options.consumerId
+    });
+    if (!options.session && options.apiKey && !options.consumerId) {
+      throw new ConfigurationError(
+        "Record scanning with an apiKey also needs consumerId \u2014 a JWT is minted from the pair. Pass both, pass a session, or omit both for an unauthenticated service."
+      );
+    }
     let scannerSdk = { RecordScanner, ViewKey };
     let scanner;
     let viewKey;
     let viewKeyString;
     let registration = makeRegisterOnce(options.startBlock ?? 0);
+    let credential = options.auth ?? options.session;
+    const sessionOf = (source) => source && !("mode" in source) ? source : void 0;
+    sessionOf(credential)?.attach("recordScanning");
+    const url = options.url ?? DEFAULT_SCANNER_URL;
     function buildScanner() {
       if (!viewKeyString) return;
       viewKey = scannerSdk.ViewKey.from_string(viewKeyString);
+      const credentialProps = credential && "mode" in credential ? { auth: credential } : credential ? {} : {
+        ...options.consumerId ? { consumerId: options.consumerId } : {},
+        ...options.apiKey ? { apiKey: options.apiKey } : {}
+      };
       scanner = new scannerSdk.RecordScanner({
-        url: options.url,
-        consumerId: options.consumerId,
-        ...options.apiKey ? { apiKey: options.apiKey } : {},
+        url,
+        ...credentialProps,
         viewKeys: [viewKey],
         decryptEnabled: true,
         autoReRegister: true
@@ -476,6 +740,30 @@ function buildSdk(initialNetwork, initialSdk) {
         viewKeyString = account.viewKey;
         buildScanner();
       },
+      /**
+       * Shares a Provable API session with this scanner.
+       *
+       * Called by {@link createAleoClient} so one session covers proving and
+       * scanning. Takes effect on the next scan — the token is applied at the
+       * scan boundary, not at construction.
+       */
+      setSession: (next) => {
+        credential = next;
+        next.attach("recordScanning");
+        buildScanner();
+      },
+      /**
+       * Shares provisioned-key auth with this scanner.
+       *
+       * Called by {@link createAleoClient} when the client uses the edge
+       * gateway's keyed model. Replaces any session, since the two models are
+       * mutually exclusive. Takes effect on the next scan.
+       */
+      setAuth: (next) => {
+        credential = next;
+        if (scanner) scanner.setAuth(next);
+        else buildScanner();
+      },
       requestRecords: async (params) => {
         if (!scanner) {
           throw new Error("No active account set on record scanner. Call setAccount() first.");
@@ -483,8 +771,11 @@ function buildSdk(initialNetwork, initialSdk) {
         const activeScanner = scanner;
         const activeViewKey = viewKey;
         const activeRegistration = registration;
+        const activeSession = sessionOf(credential);
+        if (activeSession) activeScanner.setJwtData(await activeSession.getJwt());
         await activeRegistration.ensure(activeScanner, activeViewKey);
-        return scanOwned(activeScanner, params.program, params.statusFilter, !!options.apiKey);
+        const canReMint = !credential && !!(options.apiKey && options.consumerId);
+        return scanOwned(activeScanner, params, canReMint, activeSession);
       },
       switchNetwork: async (newNetwork) => {
         if (newNetwork !== "mainnet" && newNetwork !== "testnet") {
@@ -498,11 +789,25 @@ function buildSdk(initialNetwork, initialSdk) {
     };
   }
   function createStandaloneScanner(options) {
+    assertKeyedAuthAlone(options.auth, {
+      session: options.session,
+      apiKey: options.apiKey,
+      consumerId: options.consumerId
+    });
+    if (!options.session && options.apiKey && !options.consumerId) {
+      throw new ConfigurationError(
+        "Record scanning with an apiKey also needs consumerId \u2014 a JWT is minted from the pair. Pass both, pass a session, or omit both for an unauthenticated service."
+      );
+    }
     const viewKey = ViewKey.from_string(options.viewKey);
+    const session = options.session;
+    const credentialProps = options.auth ? { auth: options.auth } : session ? {} : {
+      ...options.consumerId ? { consumerId: options.consumerId } : {},
+      ...options.apiKey ? { apiKey: options.apiKey } : {}
+    };
     const scanner = new RecordScanner({
-      url: options.url,
-      consumerId: options.consumerId,
-      ...options.apiKey ? { apiKey: options.apiKey } : {},
+      url: options.url ?? DEFAULT_SCANNER_URL,
+      ...credentialProps,
       viewKeys: [viewKey],
       decryptEnabled: true,
       autoReRegister: true
@@ -510,25 +815,57 @@ function buildSdk(initialNetwork, initialSdk) {
     const registration = makeRegisterOnce(options.startBlock ?? 0);
     return {
       requestRecords: async (params) => {
+        if (session) scanner.setJwtData(await session.getJwt());
         await registration.ensure(scanner, viewKey);
-        return scanOwned(scanner, params.program, params.statusFilter, !!options.apiKey);
+        return scanOwned(scanner, params, !!(options.apiKey && options.consumerId), session);
       }
     };
   }
   function createAleoClient(options) {
+    assertKeyedAuthAlone(options.auth, {
+      apiKey: options.apiKey,
+      consumerId: options.consumerId,
+      username: options.username,
+      credentialStore: options.credentialStore,
+      session: options.session
+    });
+    if (options.auth && options.records && !options.records.setAuth) {
+      throw new ConfigurationError(
+        "Provisioned-key auth needs a record provider with setAuth \u2014 pass a scanner from createRemoteScanner, or construct the provider with the key."
+      );
+    }
     const account = privateKeyToAccount(options.privateKey);
     const transport = http(options.networkUrl, { network });
+    const credentials = options.consumerId && options.apiKey ? { consumerId: options.consumerId, apiKey: options.apiKey } : void 0;
+    const configured = !!(credentials || options.credentialStore || options.session);
+    const session = options.auth ? void 0 : options.session ?? createProvableSession({
+      credentials,
+      store: options.credentialStore ?? memoryCredentialStore(),
+      // Resolved lazily: only a registration needs it. The derived default
+      // carries a random suffix because a username is spent once — an account
+      // that lost its stored key must still be able to register, and the old
+      // key is unrecoverable. A caller-supplied name is used verbatim, so a
+      // collision fails rather than quietly registering something else.
+      username: options.username ?? (() => `veil-${account.address.slice(5, 13)}-${Math.random().toString(36).slice(2, 8)}`)
+    });
     const proving = createProvingConfig({
       mode: options.provingMode ?? "delegated",
       networkUrl: options.networkUrl,
       proverUrl: options.proverUrl,
+      session,
+      auth: options.auth,
+      // Ignored by the proving config whenever a session is present, which is
+      // where the one-minter rule is enforced.
       apiKey: options.apiKey,
       consumerId: options.consumerId,
       account,
-      ...options.useFeeMaster !== void 0 ? { useFeeMaster: options.useFeeMaster } : {}
+      ...options.useFeeMaster !== void 0 ? { useFeeMaster: options.useFeeMaster } : {},
+      ...options.confirmationTimeout !== void 0 ? { confirmationTimeout: options.confirmationTimeout } : {}
     });
     const publicClient = createPublicClient({ transport });
     if (options.records) {
+      if (options.auth) options.records.setAuth?.(options.auth);
+      else if (configured && session) options.records.setSession?.(session);
       options.records.setAccount({ viewKey: account.viewKey });
     }
     const walletClient = createWalletClient({
@@ -536,7 +873,7 @@ function buildSdk(initialNetwork, initialSdk) {
       transport,
       proving,
       ...options.records ? { recordProvider: options.records } : {}
-    });
+    }).extend(provableApiActions());
     return { publicClient, walletClient, account };
   }
   return {
@@ -554,7 +891,7 @@ function buildSdk(initialNetwork, initialSdk) {
     createAleoClient
   };
 }
-var DEVNODE_CONSENSUS_HEIGHTS = "0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16";
+var DEVNODE_CONSENSUS_HEIGHTS = "0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,4294967295";
 function privateKeyToAccount(privateKey) {
   const sdkAccount = new Account({ privateKey });
   const address = sdkAccount.address().to_string();
@@ -665,16 +1002,23 @@ function createDevnodeClient(options) {
 }
 export {
   BLS12377HDKey,
+  DEFAULT_PROVER_URL,
+  DEFAULT_SCANNER_URL,
   DEVNODE_ADDR,
   DEVNODE_PRIVATE_KEY,
   LEGACY_PATH,
   STANDARD_PATH,
+  authenticateProvableApi,
   createDevnodeClient,
+  createProvableSession,
   generateAccount,
   generateMnemonic2 as generateMnemonic,
   loadNetwork,
+  memoryCredentialStore,
   mnemonicToHDKey,
   mnemonicToSeed,
+  provableApiActions,
+  registerProvableApi,
   validateMnemonic2 as validateMnemonic,
   validateWord
 };