@provablehq/veil-aleo-sdk 0.9.0 → 0.11.0

package/dist/node.d.ts

@@ -1,4 +1,4 @@
-import { c as ProvableCredentialStore } from './provableApi-C4bT37jI.js';
+import { c as ProvableCredentialStore } from './provableApi-BTVe8yl5.js';
 import '@provablehq/veil-core';
 import '@provablehq/sdk';
 

package/dist/{provableApi-C4bT37jI.d.ts → provableApi-BTVe8yl5.d.ts}

@@ -2,15 +2,16 @@ import { ProvingConfig, Client, WalletActions, RecordProvider } from '@provableh
 import { ApiAuthConfig } from '@provablehq/sdk';
 
 /**
- * Credentials issued by the Provable API for a registered consumer.
+ * Credentials for the legacy JWT model of the Provable API.
  *
- * Authenticate delegated proving and the hosted Record Scanner Service. The
- * pair is minted by {@link registerProvableApi} and exchanged for short-lived
- * JWTs.
+ * Optional everywhere: the default gateway needs no consumer and mints no JWT.
+ * A caller who targets a legacy gateway such as `api.provable.com` passes the
+ * pair and the session mints short-lived JWTs from it at that gateway. Nothing
+ * registers new consumers anymore. A provisioned key for the default gateway
+ * goes through {@link ProvableKeyedAuth} instead.
  *
  * @property consumerId Consumer id. Forms the path segment when minting JWTs.
- * @property apiKey API key. Returned once at registration and unrecoverable
- *   afterward, so a caller MUST persist it.
+ * @property apiKey API key. Sent as `X-Provable-API-Key` on the mint.
  */
 type ProvableApiCredentials = {
     consumerId: string;
@@ -20,14 +21,12 @@ type ProvableApiCredentials = {
  * Persists Provable API credentials between runs.
  *
  * Implemented by the caller — a file, a keychain, `localStorage`, or a secret
- * manager are all valid, and the choice belongs to the runtime rather than to
- * the SDK. A session reads through `load` on first use and writes through
- * `save` exactly once, immediately after registering a new consumer.
+ * manager are all valid. A session reads through `load` on first use and never
+ * writes: nothing registers anymore, so `save` is only called by callers who
+ * seed a store themselves.
  *
- * @property load Reads stored credentials. Returning `undefined` means no
- *   consumer is registered yet and triggers registration.
- * @property save Writes credentials. The API key is unrecoverable if this
- *   write is lost, so a failure here should propagate rather than be swallowed.
+ * @property load Reads stored credentials, or `undefined` when none are held.
+ * @property save Writes credentials. Only reached by a caller seeding the store.
  *
  * @example
  * const store: ProvableCredentialStore = {
@@ -42,46 +41,36 @@ type ProvableCredentialStore = {
 /**
  * Builds a credential store that keeps credentials for the life of the process.
  *
- * The default when a client is given no credentials and no store, and the right
- * choice for tests and short-lived workers. Suited to any runtime, since it
- * touches no storage.
- *
- * A consumer registered into this store is lost when the process exits, and its
- * API key is issued once — so a process that registers here and runs again
- * registers a second consumer that nobody can reclaim. Anything longer-lived
- * than a single run belongs in a persistent store: `fileCredentialStore` from
- * `@provablehq/veil-aleo-sdk/node`, or a caller-supplied
- * {@link ProvableCredentialStore}.
+ * The default when a client is given no credentials and no store. Suited to any
+ * runtime, since it touches no storage.
  *
  * @param initial Optional credentials to start with, so a caller can seed the
- *   store from an environment variable and skip registration.
+ *   store from an environment variable.
  * @returns A store backed by a closure variable.
  *
  * @example
  * const store = memoryCredentialStore()
- * // or seeded, in which case nothing registers:
+ * // or seeded:
  * const seeded = memoryCredentialStore({ consumerId, apiKey })
  */
 declare function memoryCredentialStore(initial?: ProvableApiCredentials): ProvableCredentialStore;
 /**
- * Provisioned-key authentication for the edge Provable API gateway.
+ * Provisioned-key authentication for the Provable API gateway.
  *
  * The keyed variant of the Provable SDK's `ApiAuthConfig`, derived rather
  * than restated so the two cannot drift — values of this type pass straight
  * into the SDK's `RecordScanner` and delegated proving as their `auth`
  * option, where the SDK applies the header default (`DEFAULT_API_KEY_HEADER`).
  *
- * The edge gateway (`edge.provable.com`) runs a different auth model from
- * `api.provable.com`: there is no consumer registration and no JWT minting.
- * An operator hands out API keys, and every request carries the key verbatim
- * in a header. Nothing registers, persists, or refreshes, and a rejected
- * request (401) means the key is invalid or revoked — retrying cannot help,
- * and only the operator can issue a replacement.
+ * The gateway is unauthenticated by default, so a key is optional. When an
+ * operator hands one out, every request carries it verbatim in a header.
+ * Nothing registers, persists, or refreshes, and a rejected request (401)
+ * means the key is invalid or revoked — retrying cannot help, and only the
+ * operator can issue a replacement.
  *
  * Mutually exclusive with the session options (`credentials`, `store`,
- * `username`, `session`): those describe the registered-consumer lifecycle,
- * which a provisioned key does not have. Combining them throws at
- * construction.
+ * `username`, `session`): those belong to the legacy JWT model. Combining
+ * them throws at construction.
  *
  * @example
  * const auth: ProvableKeyedAuth = { mode: 'api-key', value: process.env.PROVABLE_API_KEY! }
@@ -108,7 +97,7 @@ type ProvableJwt = {
  * The consumers a session has been wired into.
  *
  * Reported by {@link authenticateProvableApi} so a caller can tell which paths
- * one authentication call actually covers.
+ * one client's session reaches.
  *
  * @property proving Whether a proving configuration carries this session.
  * @property recordScanning Whether a record provider carries this session.
@@ -118,25 +107,23 @@ type ProvableSessionConsumers = {
     recordScanning: boolean;
 };
 /**
- * A live Provable API session: consumer credentials plus a cached, refreshing JWT.
+ * A Provable API session: the configured credentials plus a cached, refreshing JWT.
  *
  * Built by `createProvingConfig`, `createRemoteScanner`, and
  * `createAleoClient` from the credential options they are given — a caller
- * configures credentials and does not construct this directly. Sharing one
- * session across delegated proving and record scanning means a single minted
- * JWT and a single refresh policy for both.
- *
- * @property registeredConsumer Reports whether this session registered a new
- *   consumer rather than loading an existing one. Only meaningful after
- *   credentials have resolved.
- * @property getCredentials Resolves the credentials, registering on first use
- *   when neither direct credentials nor a store supply them.
- * @property getJwt Returns a JWT valid for at least the expiry margin,
- *   minting or refreshing as needed.
+ * configures credentials and does not construct this directly. With a
+ * credential pair and a legacy gateway to mint at, the session mints and
+ * refreshes JWTs; otherwise it is inert, since the default gateway needs
+ * nothing.
+ *
+ * @property registeredConsumer Always false; nothing registers anymore.
+ * @property getCredentials Resolves the supplied or stored credentials, or
+ *   `undefined` when the client holds none.
+ * @property getJwt Returns a JWT valid for at least the expiry margin, minting
+ *   or refreshing as needed, or `undefined` when there are no credentials, no
+ *   legacy gateway to mint at, or the gateway answered the mint with 404.
  * @property consumers Which consumers carry this session. Advisory reporting;
- *   nothing reads it to make decisions. `recordScanning` is set where a record
- *   provider is wired to a client, so sharing one session across several
- *   clients under-reports rather than claiming a path a given client lacks.
+ *   nothing reads it to make decisions.
  * @property attach Records that a consumer now carries this session. Called by
  *   the factories during wiring.
  */
@@ -144,24 +131,19 @@ type ProvableSession = {
     registeredConsumer: () => boolean;
     getCredentials: (options?: {
         username?: string;
-    }) => Promise<ProvableApiCredentials>;
+    }) => Promise<ProvableApiCredentials | undefined>;
     getJwt: (options?: {
         forceRefresh?: boolean;
-    }) => Promise<ProvableJwt>;
+    }) => Promise<ProvableJwt | undefined>;
     consumers: ProvableSessionConsumers;
     attach: (consumer: keyof ProvableSessionConsumers) => void;
 };
 /**
  * Options for {@link registerProvableApi}.
  *
- * @property username Handle for the consumer. Globally unique across the
- *   Provable API, so a taken name fails the call.
- * @property baseUrl Optional Provable API root. Defaults to
- *   `https://api.provable.com`. Applies when targeting a non-production
- *   deployment.
- * @property transport Optional fetch-compatible transport for the request.
- *   Defaults to the global `fetch`. Applies when a caller intercepts or
- *   instruments HTTP — a proxy, a recorder, a test stub.
+ * @property username Handle the retired flow registered under. Ignored.
+ * @property baseUrl Ignored; kept so existing calls compile.
+ * @property transport Ignored; kept so existing calls compile.
  */
 type RegisterProvableApiParameters = {
     username: string;
@@ -171,21 +153,18 @@ type RegisterProvableApiParameters = {
 /**
  * Options for {@link createProvableSession}.
  *
- * @property credentials Optional credentials to use directly. Take precedence
- *   over `store`, so an operator can inject a rotated or CI-provided pair
- *   without clearing persisted state first.
- * @property store Optional persistence for credentials across runs. Omit for a
- *   consumer that lives only as long as the process.
- * @property username Optional handle to register under when neither
- *   `credentials` nor `store` yields a pair. A function is called lazily, so a
- *   caller can derive the name from an account address that is not known at
- *   configuration time. Required only if registration may happen.
- * @property baseUrl Optional Provable API root. Defaults to
- *   `https://api.provable.com`.
- * @property transport Optional fetch-compatible transport used for
- *   registration and JWT minting. Defaults to the global `fetch`. Applies
- *   when a caller intercepts or instruments HTTP — a proxy, a recorder, a
- *   test stub.
+ * @property credentials Optional credentials to mint from. Take precedence
+ *   over `store`, so an operator can inject a rotated pair without clearing
+ *   persisted state first.
+ * @property store Optional store to read credentials from. Never written.
+ * @property username Ignored; nothing registers anymore.
+ * @property baseUrl Optional root of a legacy gateway that serves `/jwts`,
+ *   such as `https://api.provable.com`. Without it the session mints nothing,
+ *   because the default gateway has no JWT route. The factories derive it from
+ *   the prover or scanner URL the caller configured.
+ * @property transport Optional fetch-compatible transport for the mint.
+ *   Defaults to the global `fetch`. Applies when a caller intercepts or
+ *   instruments HTTP — a proxy, a recorder, a test stub.
  */
 type CreateProvableSessionOptions = {
     credentials?: ProvableApiCredentials;
@@ -197,11 +176,10 @@ type CreateProvableSessionOptions = {
 /**
  * Options for {@link authenticateProvableApi}.
  *
- * @property username Optional handle to register under when the client's
- *   configuration yields no credentials. Overrides the name configured on the
- *   session.
+ * @property username Ignored; nothing registers anymore.
  * @property forceRefresh Mint a fresh JWT even when the cached one is still
  *   valid. Defaults to false. Applies when recovering from a rejected token.
+ *   No effect without credentials.
  */
 type AuthenticateProvableApiParameters = {
     username?: string;
@@ -210,20 +188,17 @@ type AuthenticateProvableApiParameters = {
 /**
  * Result of {@link authenticateProvableApi}.
  *
- * @property credentials The resolved consumer credentials. Worth persisting
- *   when `registered` is true — the API key is unrecoverable afterward.
+ * @property credentials The credentials the client was configured with, or
+ *   `undefined` when it holds none.
  * @property expiration Expiry of the minted JWT, as milliseconds since the
- *   Unix epoch.
- * @property registered Whether this call registered a new consumer rather than
- *   loading an existing one.
- * @property applied Which paths the session reaches. `recordScanning` is false
- *   when the client was given a record provider that cannot accept a session —
- *   any implementation other than the ones this package builds — in which case
- *   that provider keeps using the credentials it was constructed with.
+ *   Unix epoch, or `undefined` when nothing mints one.
+ * @property registered Always false; nothing registers anymore.
+ * @property applied Which paths the client's session reaches. All false for a
+ *   keyed client or a client built without a session.
  */
 type AuthenticateProvableApiReturnType = {
-    credentials: ProvableApiCredentials;
-    expiration: number;
+    credentials: ProvableApiCredentials | undefined;
+    expiration: number | undefined;
     registered: boolean;
     applied: ProvableSessionConsumers;
 };
@@ -276,79 +251,71 @@ type ProvingConfigWithSession = ProvingConfig & {
     keyedAuth?: ProvableKeyedAuth | undefined;
 };
 /**
- * Registers a Provable API consumer and returns its credentials.
- *
- * Unauthenticated — this is the call that issues the credentials everything
- * else authenticates with. Hits the network.
+ * Formerly registered a Provable API consumer. Now a no-op.
  *
- * 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, and the only remedy is the stored key or a different name.
+ * The default gateway needs no consumer, and the legacy gateway issues no new
+ * ones through this SDK. Resolves without contacting the network.
  *
- * @param params Handle to register under, and optionally a non-default API root.
- * @returns The consumer id and API key. The key is shown only here, so the
- *   caller MUST persist it.
- * @throws When the username is already registered, when registration returns any
- *   other non-2xx status, or when the response body does not carry a consumer id
- *   and key.
+ * @deprecated Consumer registration is retired. Remove the call; pass a
+ *   consumer pair the caller already holds, or a provisioned key through
+ *   `auth`.
+ * @param params Ignored.
+ * @returns `undefined`.
  *
  * @example
  * const credentials = await registerProvableApi({ username: 'my-bot-42' })
- * await writeFile('creds.json', JSON.stringify(credentials))
+ * // credentials is undefined
  */
-declare function registerProvableApi(params: RegisterProvableApiParameters): Promise<ProvableApiCredentials>;
+declare function registerProvableApi(params: RegisterProvableApiParameters): Promise<ProvableApiCredentials | undefined>;
 /**
- * Builds a Provable API session that resolves credentials and refreshes its JWT.
- *
- * Credentials resolve on first use — supplied directly, else loaded from the
- * store, else registered and saved. Registration and minting are each
- * single-flighted, so a cold client that proves and scans concurrently
- * registers once and mints once. Pure and local until the first
- * `getCredentials` or `getJwt` call.
- *
- * @param options Credential source, optional persistence, and the name to
- *   register under.
+ * Builds a Provable API session that mints JWTs from the credentials it is given.
+ *
+ * Credentials come from `credentials` or, failing that, from the store. With a
+ * pair and a `baseUrl` the session mints a JWT on first use and refreshes it
+ * near expiry, single-flighting concurrent mints so a cold client that proves
+ * and scans together mints once. Without either it is inert: `getJwt` resolves
+ * to `undefined` and nothing is requested, because the default gateway needs
+ * no token. A root that answers the mint with 404 has no JWT route — a devnode,
+ * a self-hosted edge — and the session goes inert from then on rather than
+ * failing a client that never needed a token. Nothing registers a consumer in
+ * any case.
+ *
+ * @param options Credential source, legacy mint root, and transport.
  * @returns A session for `createProvingConfig`, `createRemoteScanner`, and
  *   `createAleoClient` to share.
  *
  * @example
- * const session = createProvableSession({ store, username: 'my-bot-42' })
- * const { jwt } = await session.getJwt()
+ * const session = createProvableSession({
+ *   credentials: { consumerId, apiKey },
+ *   baseUrl: 'https://api.provable.com',
+ * })
+ * const jwt = await session.getJwt()
  */
 declare function createProvableSession(options?: CreateProvableSessionOptions): ProvableSession;
 /**
  * Resolves the Provable API session backing delegated proving and record scanning.
  *
- * Registers a consumer when the client's configuration yields none, mints a
- * JWT, and leaves both on the session the client's proving configuration and
- * record provider already hold — so proving and scanning authenticate from then
- * on without further setup. Optional: the first prove or scan resolves the same
- * session lazily. Calling it explicitly front-loads registration, surfaces
- * credential failures before a transaction is built, and returns a newly issued
- * API key at the one moment it is recoverable.
- *
- * Hits the network: registration on first run, plus one JWT mint.
+ * With a credential pair aimed at a legacy gateway this mints the JWT eagerly,
+ * so a bad key fails before a transaction is built, and reports the expiry.
+ * Otherwise it is a no-op: the default gateway needs no token, so a keyed,
+ * credential-less, or default-gateway client resolves immediately with no
+ * expiry. Never throws for lack of a session, and never registers a consumer.
  *
- * @param client A client whose proving configuration carries Provable API
- *   credentials or a credential store.
- * @param params Optional registration name and forced refresh.
- * @returns The credentials, the JWT expiry, whether a consumer was registered,
- *   and which paths the session reaches.
- * @throws When the client has no Provable API session configured, or when
- *   registration or minting fails.
+ * @param client Any client.
+ * @param params Optional forced refresh; `username` is ignored.
+ * @returns The configured credentials or `undefined`, the JWT expiry or
+ *   `undefined`, `registered` false, and which paths the session reaches.
+ * @throws When a configured pair fails to mint.
  *
  * @example
- * const { credentials, registered } = await client.authenticateProvableApi()
- * if (registered) await store.save(credentials)
+ * const { expiration, applied } = await client.authenticateProvableApi()
  */
 declare function authenticateProvableApi(client: Client, params?: AuthenticateProvableApiParameters): Promise<AuthenticateProvableApiReturnType>;
 /**
  * Builds the Provable API auth decorator for `client.extend()`.
  *
  * `createAleoClient` applies this already. Applies directly when composing a
- * client by hand from `createWalletClient` and a proving configuration built
- * with credentials.
+ * client by hand from `createWalletClient` and a proving configuration.
  *
  * @returns A decorator: pass it to `client.extend(...)`.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@provablehq/veil-aleo-sdk",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Local signing and proving for the Veil Aleo SDK, backed by the Provable SDK.",
   "license": "MIT",
   "repository": {
@@ -33,16 +33,16 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@provablehq/veil-core": ">=0.6.0 <1.0.0",
-    "@provablehq/veil-aleo-devnode": ">=0.6.0 <1.0.0"
+    "@provablehq/veil-core": ">=0.11.0 <1.0.0",
+    "@provablehq/veil-aleo-devnode": ">=0.11.0 <1.0.0"
   },
   "dependencies": {
     "@noble/hashes": "^1.7.2",
-    "@provablehq/sdk": "^0.11.9",
+    "@provablehq/sdk": "^0.11.10",
     "@scure/bip39": "^1.4.0"
   },
   "devDependencies": {
-    "@provablehq/veil-leo": "0.9.0"
+    "@provablehq/veil-leo": "0.11.0"
   },
   "scripts": {
     "build": "tsup",