@provablehq/veil-aleo-sdk 0.6.0 → 0.7.1

package/README.md

@@ -31,27 +31,37 @@ const aleo = await loadNetwork('testnet')
 // A record scanner so the wallet client can find the private records that
 // program calls spend. The first requestRecords registers the view key with the
 // service (one network round-trip); later calls reuse it.
-const scanner = aleo.createRemoteScanner({
-  url: 'https://api.provable.com/scanner',
-  consumerId: CONSUMER_ID,
-  apiKey: DPS_API_KEY, // authenticates + registers the view key for scanning
-})
+// `url` defaults to Provable's hosted scanner, so this needs no arguments.
+const scanner = aleo.createRemoteScanner()
 
 // A fully-wired client pair: an account from the private key, a public client
-// for reads, and a wallet client with proving + the scanner attached.
+// for reads, and a wallet client with proving + the scanner attached. The
+// credential store holds one Provable API session shared by proving and
+// scanning — it registers a consumer on the first run and reuses it after.
+import { fileCredentialStore } from '@provablehq/veil-aleo-sdk/node'
+
 const { publicClient, walletClient, account } = aleo.createAleoClient({
   privateKey: PRIVATE_KEY,
   networkUrl: 'https://api.provable.com/v2',
-  provingMode: 'delegated',
-  proverUrl: 'https://api.provable.com/prove/testnet',
-  apiKey: DPS_API_KEY,
-  consumerId: CONSUMER_ID,
+  credentialStore: fileCredentialStore('./.provable-credentials.json'),
   records: scanner,
 })
 
 account.address // 'aleo1...'
 ```
 
+No API key appears above: the store registers a Provable API consumer the first
+time something needs one and reuses it from then on. Already hold credentials?
+Pass `consumerId` and `apiKey` instead and drop the store — see
+[Provable API credentials](#provable-api-credentials).
+
+`proverUrl` is a base URL — the active network is appended, the same way the
+record scanner's `url` works — so `switchChain` re-targets proving instead of
+leaving it on the network the client started from. Do not include the network
+segment yourself. It defaults to Provable's hosted prover
+(`DEFAULT_PROVER_URL`) under delegated proving, so the option only needs setting
+for a self-hosted one.
+
 Pass `provingMode: 'local'` to prove in-process instead of delegating to a prover
 service (drop `proverUrl`/`apiKey`/`consumerId`). The `walletClient` composes with
 action packages the same way a wallet-backed client does:
@@ -60,10 +70,137 @@ action packages the same way a wallet-backed client does:
 import { shieldSwapActions } from '@provablehq/shield-swap-sdk'
 
 const client = walletClient.extend(
-  shieldSwapActions({ api: { baseUrl: 'https://amm-api.dev.provable.com' } }),
+  shieldSwapActions({ api: {} }),
 )
 ```
 
+## Provable API credentials
+
+Delegated proving and the hosted record scanner both authenticate with a consumer
+id and API key, which the SDK exchanges for short-lived JWTs. A client builds a
+single session covering both services, so one credential mints one token instead
+of each service minting its own.
+
+Where that credential comes from is the only decision. Three options:
+
+| | Use when | Registers? |
+| --- | --- | --- |
+| `fileCredentialStore(path)` from `/node` | Bots, scripts, servers, CI that can write to disk | On first run, then reuses |
+| `consumerId` + `apiKey` | You already hold credentials — from a secret manager or env | Never |
+| `memoryCredentialStore()` (the default) | Tests, ephemeral workers | Every process, key discarded at exit |
+
+`memoryCredentialStore()` is what a client falls back to when given neither, so
+delegated proving works with no configuration at all. It is only appropriate for
+a single short run: the API issues each key exactly once, so a process that
+registers into memory and runs again registers a second consumer nobody can
+reclaim. Anything long-lived wants a persistent store.
+
+The session resolves on the first prove or scan. `authenticateProvableApi()` does
+it eagerly, which is worth doing at startup so a bad key fails before you have
+built a transaction:
+
+```ts
+const { credentials, expiration, registered, applied } =
+  await walletClient.authenticateProvableApi()
+
+applied // { proving: true, recordScanning: true }
+```
+
+`applied` reports which paths the session actually reaches. `recordScanning` is
+`false` when the client was given a record provider it cannot share a session
+with — any implementation other than the ones this package builds — in which case
+that provider keeps using whatever credentials it was constructed with.
+
+If you do not have credentials yet, register a consumer once. The API key is
+issued exactly once and cannot be recovered, so persist it immediately:
+
+```ts
+import { registerProvableApi } from '@provablehq/veil-aleo-sdk'
+
+const credentials = await registerProvableApi({ username: 'my-bot-42' })
+await writeFile('creds.json', JSON.stringify(credentials), { mode: 0o600 })
+```
+
+A username is spent once. It is globally unique, the API exposes no endpoint that
+reads a consumer back, and a duplicate registration answers 409 with nothing
+usable in it — so a taken name cannot be traded for the credentials it belongs to.
+The stored key is the only copy, which is the real reason to give a client a
+persistent store rather than the in-memory default.
+
+When a client registers for you, `username` chooses the name:
+
+```ts
+const { walletClient } = aleo.createAleoClient({
+  privateKey: PRIVATE_KEY,
+  networkUrl: 'https://api.provable.com/v2',
+  proverUrl: 'https://api.provable.com/prove',
+  credentialStore: fileCredentialStore('./.provable-credentials.json'),
+  username: 'my-bot-42',        // or () => `bot-${shard}`, resolved at registration
+})
+```
+
+Supplied names are used verbatim, so the consumer is identifiable in your account
+— and a collision fails with an error saying the name is taken rather than quietly
+registering something else. Omit it and the name is derived from the account
+address with a random suffix, which keeps the zero-configuration path working:
+since a username cannot be reused, an account that lost its stored key still needs
+to be able to register.
+
+On Node, `fileCredentialStore` covers this. It writes with mode `0600`, treats a
+missing file as "not registered yet", and reports a corrupt one rather than
+registering over credentials that might still be recoverable by hand. It lives on
+the `/node` subpath so the `node:fs` import never reaches a browser bundle:
+
+```ts
+import { fileCredentialStore } from '@provablehq/veil-aleo-sdk/node'
+
+const { walletClient } = aleo.createAleoClient({
+  privateKey: PRIVATE_KEY,
+  networkUrl: 'https://api.provable.com/v2',
+  proverUrl: 'https://api.provable.com/prove',
+  credentialStore: fileCredentialStore('./.provable-credentials.json'),
+  records: scanner,
+})
+
+const { registered } = await walletClient.authenticateProvableApi()
+registered // true on the first run, false afterward
+```
+
+Anywhere else, implement the two-method interface yourself — a keychain,
+`localStorage`, IndexedDB, or a secret manager all satisfy it, and the SDK assumes
+nothing about which:
+
+```ts
+import type { ProvableCredentialStore } from '@provablehq/veil-aleo-sdk'
+
+const credentialStore: ProvableCredentialStore = {
+  load: () => {
+    const raw = localStorage.getItem('provable-credentials')
+    return raw ? JSON.parse(raw) : undefined // undefined → register
+  },
+  save: (c) => localStorage.setItem('provable-credentials', JSON.stringify(c)),
+}
+```
+
+Two rules for a hand-written store. `load` MUST return `undefined` rather than
+throw when nothing is stored, or resolution fails instead of registering. And
+`save` must actually persist: it runs before the credentials are handed back
+precisely so a failed write fails the call, since a swallowed one orphans a
+consumer whose key cannot be reissued. That also means a genuinely read-only
+environment should supply `consumerId`/`apiKey` directly rather than rely on
+registration.
+
+An explicit `consumerId`/`apiKey` pair takes precedence over the store, so an
+operator can inject a rotated key or CI credentials without clearing persisted
+state first.
+
+One caveat on the mint itself: the API does not validate the consumer id against
+the API key. A mismatched id still yields a working token, because the token's
+issuer comes from the key. The mismatch surfaces later as a rejection from the
+service you call — the record scanner reports it as `No credentials found for
+given 'iss'`. Nothing in the mint path can catch that for you, so keep the pair
+together.
+
 The handle also exposes the pieces individually when the caller does not want the
 full pair:
 
@@ -80,6 +217,29 @@ For local iteration without a live chain, `createDevnodeClient()` returns the
 same client pair pointed at an Aleo Devnode instance with a pre-funded seeded
 account.
 
+## Provisioned API keys (edge gateway)
+
+The edge gateway (`edge.provable.com`) runs a different auth model: no consumer
+registration and no JWTs. An operator hands out an API key, and every request
+carries it verbatim in an `X-API-Key` header. Configure it with `auth` instead
+of the consumer options:
+
+```ts
+const { walletClient } = aleo.createAleoClient({
+  privateKey,
+  networkUrl: 'https://edge.provable.com/api/v2',
+  proverUrl: 'https://edge.provable.com/api/prove',
+  records: aleo.createRemoteScanner({ url: 'https://edge.provable.com/api/scanner' }),
+  auth: { mode: 'api-key', value: process.env.PROVABLE_API_KEY! },
+})
+```
+
+The two models are mutually exclusive: combining `auth` with `apiKey`,
+`consumerId`, `username`, `credentialStore`, or `session` throws at
+construction. There is no session under keyed auth — nothing registers,
+persists, or refreshes — so `authenticateProvableApi()` throws, and a 401
+means the key is invalid or revoked, which only the operator can fix.
+
 ## WASM dependency
 
 `@provablehq/sdk` ships the Aleo cryptography as WebAssembly, and this package

package/dist/index.d.ts

@@ -1,6 +1,9 @@
 import { loadNetwork as loadNetwork$1 } from '@provablehq/sdk/dynamic.js';
 export { DEVNODE_ADDR, DEVNODE_PRIVATE_KEY } from '@provablehq/veil-aleo-devnode';
-import { LocalAccount, ProvingConfig, RecordProvider, StandaloneRecordScanner, PublicClient, WalletClient } from '@provablehq/veil-core';
+import { LocalAccount, RecordProvider, StandaloneRecordScanner, PublicClient, WalletClient } from '@provablehq/veil-core';
+import { P as ProvableSession, a as ProvableKeyedAuth, b as ProvingConfigWithSession, c as ProvableCredentialStore, d as ProvableWalletClient } from './provableApi-C4bT37jI.js';
+export { A as AuthenticateProvableApiParameters, e as AuthenticateProvableApiReturnType, C as CreateProvableSessionOptions, f as ProvableApiActions, g as ProvableApiCredentials, h as ProvableJwt, i as ProvableSessionConsumers, R as RegisterProvableApiParameters, j as authenticateProvableApi, k as createProvableSession, m as memoryCredentialStore, p as provableApiActions, r as registerProvableApi } from './provableApi-C4bT37jI.js';
+import '@provablehq/sdk';
 
 /**
  * Names the derivation-path convention used to turn a seed into Aleo keys.
@@ -162,6 +165,20 @@ declare function mnemonicToHDKey(mnemonic: string, options?: {
 
 /** Networks supported by `@provablehq/sdk/dynamic.js`. */
 type SupportedNetwork = 'mainnet' | 'testnet';
+/**
+ * Base URL of Provable's hosted delegated proving service.
+ *
+ * The default `proverUrl` for `mode: 'delegated'`. A base, so the active network
+ * is appended — which is what lets `switchChain` re-target proving.
+ */
+declare const DEFAULT_PROVER_URL = "https://api.provable.com/prove";
+/**
+ * Base URL of Provable's hosted Record Scanner Service.
+ *
+ * The default `url` for both scanner factories. A base — the SDK appends the
+ * network segment, which is what lets a scanner follow `switchChain`.
+ */
+declare const DEFAULT_SCANNER_URL = "https://api.provable.com/scanner";
 type SdkModule = Awaited<ReturnType<typeof loadNetwork$1<'testnet'>>>;
 /**
  * A network-bound SDK handle. All functions on this handle use the binary
@@ -222,7 +239,26 @@ interface AleoSdk {
     verifySignature(address: string, message: Uint8Array, signature: string): boolean;
     /** Creates an `AleoNetworkClient` for direct SDK access. */
     createNetworkClient(url: string): InstanceType<SdkModule['AleoNetworkClient']>;
-    /** Creates a `ProvingConfig` for `createWalletClient({ proving })`. */
+    /**
+     * Creates a `ProvingConfig` for `createWalletClient({ proving })`.
+     *
+     * @param options.proverUrl Base URL of the delegated proving service — the
+     *   network segment is appended, so do not include it. That is what lets
+     *   `switchChain` re-target proving instead of leaving it on the network the
+     *   client started from. A base that already ends in `/mainnet` or `/testnet`
+     *   is re-targeted rather than doubled. Defaults to
+     *   {@link DEFAULT_PROVER_URL} under `mode: 'delegated'`; unused under
+     *   `mode: 'local'`, which reaches no prover.
+     * @param options.session Optional Provable API session. When present the
+     *   configuration authenticates from it and withholds `apiKey`/`consumerId`
+     *   from the prover client, so one party mints JWTs. The session is attached
+     *   to the returned configuration, which is what lets
+     *   `authenticateProvableApi` find it on a client.
+     * @param options.auth Optional provisioned-key auth for the edge gateway.
+     *   Every proving request carries the key verbatim; nothing registers or
+     *   mints, and a 401 is terminal. Mutually exclusive with `session`,
+     *   `apiKey`, and `consumerId` — combining them throws.
+     */
     createProvingConfig(options: {
         mode: 'delegated' | 'local';
         networkUrl: string;
@@ -232,7 +268,9 @@ interface AleoSdk {
         account?: LocalAccount<'privateKey'>;
         confirmationTimeout?: number;
         useFeeMaster?: boolean;
-    }): ProvingConfig;
+        session?: ProvableSession;
+        auth?: ProvableKeyedAuth;
+    }): ProvingConfigWithSession;
     /**
      * Creates a record scanner backed by Provable's Record Scanner Service.
      *
@@ -245,41 +283,131 @@ interface AleoSdk {
      * against the new network and re-registers lazily on the next scan.
      *
      * @param options.url Base URL of the service (the SDK appends the network
-     *   segment — do not include it).
-     * @param options.consumerId Consumer id used for JWT refresh.
+     *   segment — do not include it). Defaults to {@link DEFAULT_SCANNER_URL}.
+     * @param options.consumerId Optional consumer id used for JWT refresh.
+     *   Unnecessary when a `session` supplies the token. Required alongside
+     *   `apiKey` otherwise — a JWT is minted from the pair, so half of it
+     *   authenticates nothing and construction throws rather than 401ing later.
      * @param options.apiKey Optional API key for the authenticated service
      *   (e.g. the hosted Provable RSS). Omit for an open/unauthenticated service.
+     * @param options.session Optional Provable API session to authenticate from,
+     *   shared with delegated proving. `createAleoClient` supplies its own
+     *   session through `setSession` on the returned provider, so a caller who
+     *   passes the scanner to that factory does not need this.
      * @param options.startBlock Optional block height to begin scanning from at
      *   registration. Defaults to 0 (full history).
+     * @param options.auth Optional provisioned-key auth for the edge gateway.
+     *   Every scan carries the key verbatim; nothing registers or mints, and a
+     *   401 is terminal. Mutually exclusive with `session`, `apiKey`, and
+     *   `consumerId` — combining them throws.
+     * @returns The provider, plus `setSession` and `setAuth` for a factory to
+     *   share one credential source across proving and scanning after
+     *   construction.
      */
-    createRemoteScanner(options: {
-        url: string;
-        consumerId: string;
+    createRemoteScanner(options?: {
+        url?: string;
+        consumerId?: string;
         apiKey?: string;
+        session?: ProvableSession;
         startBlock?: number;
-    }): RecordProvider;
+        auth?: ProvableKeyedAuth;
+    }): RecordProvider & {
+        setSession: (session: ProvableSession) => void;
+        setAuth: (auth: ProvableKeyedAuth) => void;
+    };
     /**
      * Creates a standalone record scanner with an explicit view key.
      *
      * Like {@link createRemoteScanner}, the first `requestRecords` registers the
      * view key with the service (a network round-trip) to obtain the scanning UUID.
      *
-     * @param options.url Base URL of the service (the SDK appends the network segment).
-     * @param options.consumerId Consumer id used for JWT refresh.
+     * @param options.url Base URL of the service (the SDK appends the network
+     *   segment). Defaults to {@link DEFAULT_SCANNER_URL}.
+     * @param options.consumerId Optional consumer id used for JWT refresh.
+     *   Unnecessary when a `session` supplies the token. Required alongside
+     *   `apiKey` otherwise — a JWT is minted from the pair, so half of it
+     *   authenticates nothing and construction throws rather than 401ing later.
      * @param options.viewKey The view key (`AViewKey1…`) to scan and decrypt with.
      * @param options.apiKey Optional API key for the authenticated service. Omit
      *   for an open/unauthenticated service.
+     * @param options.session Optional Provable API session to authenticate from.
+     *   Supplied at construction only — a standalone scanner is not pluggable
+     *   into a wallet client, so nothing shares a session with it later.
      * @param options.startBlock Optional block height to begin scanning from at
      *   registration. Defaults to 0 (full history).
+     * @param options.auth Optional provisioned-key auth for the edge gateway.
+     *   Every scan carries the key verbatim; nothing registers or mints, and a
+     *   401 is terminal. Mutually exclusive with `session`, `apiKey`, and
+     *   `consumerId` — combining them throws.
      */
     createStandaloneScanner(options: {
-        url: string;
-        consumerId: string;
+        url?: string;
+        consumerId?: string;
         viewKey: string;
         apiKey?: string;
+        session?: ProvableSession;
         startBlock?: number;
+        auth?: ProvableKeyedAuth;
     }): StandaloneRecordScanner;
-    /** Creates a fully-wired Aleo client from a private key and network URL. */
+    /**
+     * Creates a fully-wired Aleo client from a private key and network URL.
+     *
+     * Builds one Provable API session from the credential options and shares it
+     * across delegated proving and record scanning, so a single
+     * `walletClient.authenticateProvableApi()` covers both. Omit the credential
+     * options for a client that authenticates neither.
+     *
+     * @param options.apiKey Optional Provable API key. Paired with `consumerId`,
+     *   it seeds the session directly.
+     * @param options.consumerId Optional Provable API consumer id.
+     * @param options.proverUrl Base URL of the delegated proving service — the
+     *   network segment is appended, so do not include it. That is what lets
+     *   `switchChain` re-target proving. Defaults to {@link DEFAULT_PROVER_URL},
+     *   since `provingMode` itself defaults to `'delegated'`; pass an override for
+     *   a self-hosted prover.
+     * @param options.confirmationTimeout Milliseconds to wait for a submitted
+     *   transaction to confirm. Defaults to 60_000 (one minute), which covers a
+     *   healthy confirmation with room to spare; a transaction still absent after
+     *   that is more often one the node never included than one about to land.
+     *   Raise it for a congested network or a multi-transition call that takes
+     *   longer to include, rather than treating a slow confirmation as a failure.
+     * @param options.username Optional handle to register a Provable API consumer
+     *   under, used only when no credentials and no stored pair are available.
+     *   A function is called lazily, at the moment registration happens. Defaults
+     *   to a name derived from the account address plus a random suffix — the
+     *   suffix matters because a username is spent once, so an account that lost
+     *   its stored key must still be able to register. Supplying a fixed name
+     *   makes the consumer identifiable but fails if that name is taken, since
+     *   credentials cannot be recovered from a username.
+     * @param options.credentialStore Optional persistence for Provable API
+     *   credentials. When neither `consumerId`/`apiKey` nor a stored pair is
+     *   available, a consumer is registered under a name derived from the account
+     *   address and saved here. Defaults to `memoryCredentialStore()`, which holds
+     *   a registered consumer only for the life of the process — pass
+     *   `fileCredentialStore` from `@provablehq/veil-aleo-sdk/node`, or any
+     *   {@link ProvableCredentialStore}, for anything longer-lived. A client left
+     *   fully unconfigured does not share its session with `records`, so a scanner
+     *   aimed at an open service keeps needing no credential.
+     * @param options.session Optional pre-built session, for a caller that owns
+     *   one already. Takes precedence over the credential options.
+     * @param options.auth Optional provisioned-key auth for the edge gateway.
+     *   Selects the keyed model for the whole client: proving and scanning carry
+     *   the key on every request, no session exists, and
+     *   `authenticateProvableApi` throws since there is nothing to resolve.
+     *   Mutually exclusive with every consumer option (`apiKey`, `consumerId`,
+     *   `username`, `credentialStore`, `session`) — edge keys are handed out by
+     *   an operator, not registered.
+     * @returns A public client, a wallet client carrying
+     *   `authenticateProvableApi`, and the account.
+     *
+     * @example
+     * const scanner = aleo.createRemoteScanner({ url: SCANNER_URL })
+     * const { walletClient } = aleo.createAleoClient({
+     *   privateKey, networkUrl, proverUrl, records: scanner, credentialStore: store,
+     * })
+     * const { credentials, registered } = await walletClient.authenticateProvableApi()
+     * if (registered) console.log('registered consumer', credentials.consumerId)
+     */
     createAleoClient(options: {
         privateKey: string;
         networkUrl: string;
@@ -288,16 +416,24 @@ interface AleoSdk {
         apiKey?: string;
         consumerId?: string;
         useFeeMaster?: boolean;
+        confirmationTimeout?: number;
+        username?: string | (() => string);
+        credentialStore?: ProvableCredentialStore;
+        session?: ProvableSession;
+        auth?: ProvableKeyedAuth;
         /**
          * Record provider for `requestRecords`. Not wired by default — pass
          * `aleo.createRemoteScanner(...)` or any
          * custom `RecordProvider`. `requestRecords` throws with a setup hint
          * when no provider is configured.
          */
-        records?: RecordProvider;
+        records?: RecordProvider & {
+            setSession?: (session: ProvableSession) => void;
+            setAuth?: (auth: ProvableKeyedAuth) => void;
+        };
     }): {
         publicClient: PublicClient;
-        walletClient: WalletClient;
+        walletClient: ProvableWalletClient;
         account: LocalAccount<'privateKey'>;
     };
 }
@@ -345,4 +481,4 @@ declare function createDevnodeClient(options?: {
     account: LocalAccount<'privateKey'>;
 };
 
-export { type AleoDerivationId, type AleoSdk, BLS12377HDKey, LEGACY_PATH, STANDARD_PATH, type SupportedNetwork, createDevnodeClient, generateAccount, generateMnemonic, loadNetwork, mnemonicToHDKey, mnemonicToSeed, validateMnemonic, validateWord };
+export { type AleoDerivationId, type AleoSdk, BLS12377HDKey, DEFAULT_PROVER_URL, DEFAULT_SCANNER_URL, LEGACY_PATH, ProvableCredentialStore, ProvableKeyedAuth, ProvableSession, ProvableWalletClient, ProvingConfigWithSession, STANDARD_PATH, type SupportedNetwork, createDevnodeClient, generateAccount, generateMnemonic, loadNetwork, mnemonicToHDKey, mnemonicToSeed, validateMnemonic, validateWord };