@usearete/sdk 0.32.0 → 0.33.0

package/dist/index.d.ts

@@ -1263,8 +1263,19 @@ interface AuthConfig {
     getToken?: (request?: AuthTokenRequest) => Promise<string | AuthTokenResult>;
     /** Arete Cloud token endpoint URL */
     tokenEndpoint?: string;
-    /** Publishable key for Arete Cloud */
+    /**
+     * Publishable key (`a4_pk_...`) for code shipped to a browser. It is bound
+     * to the origins it was created for; create one with
+     * `a4 auth keys create-publishable --origin <scheme://host[:port]>`.
+     */
     publishableKey?: string;
+    /**
+     * Agent key (`a4_ak_...`) or secret key (`a4_sk_...`) for servers, agents
+     * and local scripts. Server-only: setting it in a browser throws. When no
+     * auth option is set, outside browsers it defaults to the `ARETE_API_KEY`
+     * environment variable.
+     */
+    secretKey?: string;
     /** Pre-minted static token (for server-side use) */
     token?: string;
     /** How the websocket token is sent to the server */
@@ -3082,6 +3093,16 @@ interface ProgramReadTransport {
     read<T>(request: ProgramReadRequest): Promise<T>;
 }
 
+/** Environment variable read for a secret-class key outside browsers. */
+declare const ARETE_API_KEY_ENV = "ARETE_API_KEY";
+/**
+ * Key class inferred from an API key's prefix. `unknown` covers keys this SDK
+ * does not recognise (for example self-hosted credentials); they are passed
+ * through unvalidated.
+ */
+type ApiKeyClass = 'publishable' | 'secret' | 'unknown';
+declare function classifyApiKey(key: string): ApiKeyClass;
+
 declare class MemoryAdapter implements StorageAdapter {
     private views;
     private updateCallbacks;
@@ -3138,5 +3159,5 @@ declare const Arete: typeof Arete$1 & {
     session: typeof createSession;
 };
 
-export { API_PROBLEM_SCHEMA_VERSION, ASSOCIATED_TOKEN_PROGRAM_ADDRESS, Arete, AreteError, CLAIM_AGENT_MATERIALIZER_PATH, ConnectionManager, DEFAULT_CONFIG, DEFAULT_INITIAL_DATA_TIMEOUT_MS, DEFAULT_MAX_ENTRIES_PER_VIEW, EXTENSION_API_VERSION, FrameProcessor, InitialDataTimeoutError, InstructionError, MANAGED_SOLANA_CONTRACT_VERSION, MAX_MANAGED_BATCH_ADDRESSES, MAX_MANAGED_PAGE_SIZE, MemoryAdapter, OPERATION_KIND, OperationCallbackError, OperationExecutionError, PROGRAM_KEY_CONFLICT, PROGRAM_OPERATION_EXTENSIONS, ProcessedSlotTimeoutError, QueryStore, ReadRequestError, SPL_TOKEN_PROGRAM_ADDRESS, STACK_RUNTIME_EXTENSIONS, SYSTEM_PROGRAM_ADDRESS, StreamGapError, SubscriptionRegistry, TOKEN_2022_PROGRAM_ADDRESS, TRANSACTION_RESOURCE_OPTION_KEYS, TransactionExecutionError, TransactionOptionsError, TransactionTransportError, account, accountTombstone, appendFlowTransactions, appendTransactionInstructions, applyConnectedStackExtensions, arg, buildInstruction, bytes, canonicalQueryKey, chainAccountLoader, compareProgramIdentity, createChainClient, createEntityStream, createHostedSolanaGatewayTransports, createInstructionExecutor, createInstructionHandler, createPreparedFlow, createPreparedInstruction, createPreparedTransaction, createPreparedTransactionBody, createProgramPdas, createPublicKeySeed, createRichUpdateStream, createSeed, createSession, createSignerRegistry, createSubscriptionId, createTransactionTransport, createTypedListView, createTypedStateView, createTypedViews, createUpdateStream, decodeBase58, defineProgramExtensions, defineStackExtensions, deriveAssociatedTokenAccount, deriveHttpEndpoint, findProgramAddress as derivePda, describePreparedOperation, encodeBase58, executeInstruction, executePreparedOperation, extendProgram, extendPrograms, extendStack, findProgramAddress, findProgramAddressSync, flowOperation, formatPreparedOperation, formatProgramError, formatRawToUi, getMintDecimals, getOperationKind, getProgramRuntimeExtensions, getStackRuntimeExtensions, getTransactionFailureOutcome, hostedWebsocketSuffixes, inspectPreparedOperation, instructionOperation, isClaimAgentRecoveryAction, isEntityFrame, isErrorFrame, isHostedAreteEndpoint, isReplayErrorCode, isSafeClaimActionUrl, isSameProgramSdk, isSnapshotFrame, isStackVersionRefusalCode, isSubscribedFrame, isUnsubscribedFrame, isValidFrame, literal, managedAddress, managedContext, managedDiscovery, managedPage, managedReadOptions, managedU64, normalizeSubscription, normalizeSubscriptionQuery, normalizeSubscriptionRequest, normalizeTransactionError, parseApiProblem, parseFrame, parseFrameFromBlob, parseInstructionError, parseUiAmountToRaw, pda, prependFlowTransactionInstructions, prependTransactionInstructions, programAccountRead, programQuery, resolveAccounts, resolveAmount, resolveAmountToRaw, resolveAmountsToRaw, resolveTokenProgramAddress, resolveTransactionBuildOptions, safeToRawAmount, serializeInstructionData, serializeViewKey, setHostedWebsocketSuffixes, stackQuery, stringifyBigints, toJsonValue, toRawAmount, toWireResourceOptions, transactionOperation, unwrapOperationExecutionError, validateAccountResolution, validateProgramReadDescriptor, validateSubscriptionId, withProgramIdentity, withProgramRead, withPrograms };
-export type { AccountCategory, AccountLoader, AccountMeta, AccountResolutionOptions, AccountResolutionResult, AccountTombstone, AmountInput, AnyOperation, ApiProblemV1, AreteConfig, AreteOptions, AreteOptionsWithStorage, ArgSchema, ArgType, AuthConfig, AuthTokenRequest, AuthTokenResult, AuthTokenTarget, BuildOptions, BuiltAccountMeta, BuiltInstruction, ChainClient, ChainClock, ChainFailedTransactionOutcome, CompositionSessionOptions, ConfirmationLevel, ConfirmedTransaction, ConfirmedTransactionOutcome, ConnectOptions, ConnectedArete, ConnectedStackClient, ConnectionState, ConnectionStateCallback, ContextSlotOptions, Contextual, CreatePreparedFlowInput, CreatePreparedInstructionInput, CreatePreparedTransactionInput, DefaultViewKey, DiscoveryProvenance, EntityFrame, ErrorFrame, ErrorMetadata, ExecuteOptions, ExecutionResult, ExtendedProgramDefinition, ExtendedStackDefinition, FlowOperation, FlowOperationNamespace, FlowOperationReceipt, Frame, FrameMode, FrameOp, FrameProcessorConfig, FrameValidationDiagnostic, GetOptions, HostedSolanaGatewayBindings, HostedSolanaGatewayCapabilityBinding, HostedSolanaGatewayTransportOptions, HostedSolanaGatewayTransports, HttpAuthMetadata, InstructionExecutor, InstructionHandler, InstructionHandlerConfig, InstructionOperation, InstructionOperationNamespace, JsonObject, JsonPrimitive, JsonValue, LatestBlockhashResult, ManagedReadOptions, MergeProgramMaps, MintAccountInfo, NativeBalanceInfo, NativePositionPage, NativePositionQuery, NonEmptyReadonlyArray, NotSubmittedTransactionOutcome, OperationCallbackPhase, OperationExecutionEvent, OperationExecutionHost, OperationExecutionOptions, OperationExecutionSuccessEvent, OperationInspection, OperationInspectionOptions, OperationKind, OperationKindBrand, OperationNamespace, OperationPlan, OperationReceiptFor, OperationTransactionReceipt, OwnerTokenAccount, OwnerTokenAccountsPage, OwnerTokenAccountsRequest, PdaConfig, PdaDeriveContext, PdaFactory, PdaProgram, PdaProgramSelector, PdaSeed, PreparedFlow, PreparedInstruction, PreparedOperation, PreparedOperationDescription, PreparedTransaction, PreparedTransactionBody, PreparedTransactionInstruction, PreparedTransactionOperation, ProgramAccountBatchItem, ProgramAccountBatchResult, ProgramAccountReadDefinition, ProgramError, ProgramExtensionInput, ProgramIdentityMatch, ProgramInterface, ProgramOperationContext, ProgramOperations, ProgramOperationsOf, ProgramPdas, ProgramQueryDefinition, ProgramReadBinding, ProgramReadBindingAuthTarget, ProgramReadDescriptor, ProgramReadDescriptors, ProgramReadOf, ProgramReadOverride, ProgramReadOverrides, ProgramReadRequest, ProgramReadTransport, ProgramReleaseReference, ProgramRuntimeExtensionCarrier, ProgramRuntimeExtensions, ProgramSdkDefinition, ProgramSdkIdentity, ProgramsInterface, QueriesInterface, QueryLease, QuerySnapshot, RawAccountInfo, RawInstructionsInterface, RawProgramsInterface, ReadArgumentCount, ReadArgumentCounts, ReadContext, ReadTransportMethod, ReadyRecoveryAction, ReadyRecoveryActionV1, RecoveryAction, ReplayErrorCode, ReplayWindow, ResolvedAccount, ResolvedAccounts, ResolvedTransactionBuildOptions, ResolvedTransactionResourceOptions, ResourceLamports, ResourceUnits, RichUpdate, RichUpdateCallback, Schema, SchemaResult, SeedDef, SendOptions, SendResult, Session, SessionDefinition, SessionMemberOptions, SessionOptions, SignerRegistry, SingleTransactionOperationReceipt, SnapshotEntity, SnapshotFrame, SocketIssue, SocketIssueCallback, SolanaGatewayAuthMetadata, SolanaGatewayAuthScope, SolanaGatewayBindingAuthTarget, SortConfig, SortOrder, StackConnectedExtensions, StackDefinition, StackEndpoints, StackExtensionClient, StackExtensionInput, StackQueryDefinition, StackRelease, StackRuntimeExtensionCarrier, StackRuntimeExtensions, StackVersionRefusal, StackWithAttachedPrograms, StorageAdapter, StorageAdapterConfig, StringifiedBigints, SubmittedUnknownTransactionOutcome, SubscribeCallback, SubscribedFrame, Subscription, SubscriptionIdentity, SubscriptionOptions, SubscriptionQuery, SubscriptionRequest, SubscriptionSnapshotOptions, TokenAccountInfo, TokenBalanceInfo, TokenBalanceInput, TransactionAccountBalance, TransactionBuildCapability, TransactionBuildOptions, TransactionCommitment, TransactionExecutionMetadata, TransactionFailureOutcome, TransactionFailurePhase, TransactionFailureStatus, TransactionFeeResult, TransactionInspectOptions, TransactionInspectionOptions, TransactionInspectionResult, TransactionOperation, TransactionOperationNamespace, TransactionOptions, TransactionOptionsErrorCode, TransactionOutcome, TransactionRequestContext, TransactionResourceOptionKey, TransactionResourceOptions, TransactionSendOptions, TransactionSendResult, TransactionSignatureStatus, TransactionSimulationOptions, TransactionSimulationResult, TransactionTransport, TransactionTransportErrorBody, TransactionVersion, TypedAccountReader, TypedInstruction, TypedListView, TypedQueryExecutor, TypedStateView, TypedViewGroup, TypedViews, UnsubscribeFn, UnsubscribedFrame, Update, UpdateCallback, UsageLimit, ViewDef, ViewGroup, ViewKeyFields, ViewKeyValue, ViewSortConfig, WaitForProcessedSlotOptions, WalletAdapter, WalletConnectOptions, WalletExecutionContext, WalletState, WatchOptions, WebSocketFactoryInit };
+export { API_PROBLEM_SCHEMA_VERSION, ARETE_API_KEY_ENV, ASSOCIATED_TOKEN_PROGRAM_ADDRESS, Arete, AreteError, CLAIM_AGENT_MATERIALIZER_PATH, ConnectionManager, DEFAULT_CONFIG, DEFAULT_INITIAL_DATA_TIMEOUT_MS, DEFAULT_MAX_ENTRIES_PER_VIEW, EXTENSION_API_VERSION, FrameProcessor, InitialDataTimeoutError, InstructionError, MANAGED_SOLANA_CONTRACT_VERSION, MAX_MANAGED_BATCH_ADDRESSES, MAX_MANAGED_PAGE_SIZE, MemoryAdapter, OPERATION_KIND, OperationCallbackError, OperationExecutionError, PROGRAM_KEY_CONFLICT, PROGRAM_OPERATION_EXTENSIONS, ProcessedSlotTimeoutError, QueryStore, ReadRequestError, SPL_TOKEN_PROGRAM_ADDRESS, STACK_RUNTIME_EXTENSIONS, SYSTEM_PROGRAM_ADDRESS, StreamGapError, SubscriptionRegistry, TOKEN_2022_PROGRAM_ADDRESS, TRANSACTION_RESOURCE_OPTION_KEYS, TransactionExecutionError, TransactionOptionsError, TransactionTransportError, account, accountTombstone, appendFlowTransactions, appendTransactionInstructions, applyConnectedStackExtensions, arg, buildInstruction, bytes, canonicalQueryKey, chainAccountLoader, classifyApiKey, compareProgramIdentity, createChainClient, createEntityStream, createHostedSolanaGatewayTransports, createInstructionExecutor, createInstructionHandler, createPreparedFlow, createPreparedInstruction, createPreparedTransaction, createPreparedTransactionBody, createProgramPdas, createPublicKeySeed, createRichUpdateStream, createSeed, createSession, createSignerRegistry, createSubscriptionId, createTransactionTransport, createTypedListView, createTypedStateView, createTypedViews, createUpdateStream, decodeBase58, defineProgramExtensions, defineStackExtensions, deriveAssociatedTokenAccount, deriveHttpEndpoint, findProgramAddress as derivePda, describePreparedOperation, encodeBase58, executeInstruction, executePreparedOperation, extendProgram, extendPrograms, extendStack, findProgramAddress, findProgramAddressSync, flowOperation, formatPreparedOperation, formatProgramError, formatRawToUi, getMintDecimals, getOperationKind, getProgramRuntimeExtensions, getStackRuntimeExtensions, getTransactionFailureOutcome, hostedWebsocketSuffixes, inspectPreparedOperation, instructionOperation, isClaimAgentRecoveryAction, isEntityFrame, isErrorFrame, isHostedAreteEndpoint, isReplayErrorCode, isSafeClaimActionUrl, isSameProgramSdk, isSnapshotFrame, isStackVersionRefusalCode, isSubscribedFrame, isUnsubscribedFrame, isValidFrame, literal, managedAddress, managedContext, managedDiscovery, managedPage, managedReadOptions, managedU64, normalizeSubscription, normalizeSubscriptionQuery, normalizeSubscriptionRequest, normalizeTransactionError, parseApiProblem, parseFrame, parseFrameFromBlob, parseInstructionError, parseUiAmountToRaw, pda, prependFlowTransactionInstructions, prependTransactionInstructions, programAccountRead, programQuery, resolveAccounts, resolveAmount, resolveAmountToRaw, resolveAmountsToRaw, resolveTokenProgramAddress, resolveTransactionBuildOptions, safeToRawAmount, serializeInstructionData, serializeViewKey, setHostedWebsocketSuffixes, stackQuery, stringifyBigints, toJsonValue, toRawAmount, toWireResourceOptions, transactionOperation, unwrapOperationExecutionError, validateAccountResolution, validateProgramReadDescriptor, validateSubscriptionId, withProgramIdentity, withProgramRead, withPrograms };
+export type { AccountCategory, AccountLoader, AccountMeta, AccountResolutionOptions, AccountResolutionResult, AccountTombstone, AmountInput, AnyOperation, ApiKeyClass, ApiProblemV1, AreteConfig, AreteOptions, AreteOptionsWithStorage, ArgSchema, ArgType, AuthConfig, AuthTokenRequest, AuthTokenResult, AuthTokenTarget, BuildOptions, BuiltAccountMeta, BuiltInstruction, ChainClient, ChainClock, ChainFailedTransactionOutcome, CompositionSessionOptions, ConfirmationLevel, ConfirmedTransaction, ConfirmedTransactionOutcome, ConnectOptions, ConnectedArete, ConnectedStackClient, ConnectionState, ConnectionStateCallback, ContextSlotOptions, Contextual, CreatePreparedFlowInput, CreatePreparedInstructionInput, CreatePreparedTransactionInput, DefaultViewKey, DiscoveryProvenance, EntityFrame, ErrorFrame, ErrorMetadata, ExecuteOptions, ExecutionResult, ExtendedProgramDefinition, ExtendedStackDefinition, FlowOperation, FlowOperationNamespace, FlowOperationReceipt, Frame, FrameMode, FrameOp, FrameProcessorConfig, FrameValidationDiagnostic, GetOptions, HostedSolanaGatewayBindings, HostedSolanaGatewayCapabilityBinding, HostedSolanaGatewayTransportOptions, HostedSolanaGatewayTransports, HttpAuthMetadata, InstructionExecutor, InstructionHandler, InstructionHandlerConfig, InstructionOperation, InstructionOperationNamespace, JsonObject, JsonPrimitive, JsonValue, LatestBlockhashResult, ManagedReadOptions, MergeProgramMaps, MintAccountInfo, NativeBalanceInfo, NativePositionPage, NativePositionQuery, NonEmptyReadonlyArray, NotSubmittedTransactionOutcome, OperationCallbackPhase, OperationExecutionEvent, OperationExecutionHost, OperationExecutionOptions, OperationExecutionSuccessEvent, OperationInspection, OperationInspectionOptions, OperationKind, OperationKindBrand, OperationNamespace, OperationPlan, OperationReceiptFor, OperationTransactionReceipt, OwnerTokenAccount, OwnerTokenAccountsPage, OwnerTokenAccountsRequest, PdaConfig, PdaDeriveContext, PdaFactory, PdaProgram, PdaProgramSelector, PdaSeed, PreparedFlow, PreparedInstruction, PreparedOperation, PreparedOperationDescription, PreparedTransaction, PreparedTransactionBody, PreparedTransactionInstruction, PreparedTransactionOperation, ProgramAccountBatchItem, ProgramAccountBatchResult, ProgramAccountReadDefinition, ProgramError, ProgramExtensionInput, ProgramIdentityMatch, ProgramInterface, ProgramOperationContext, ProgramOperations, ProgramOperationsOf, ProgramPdas, ProgramQueryDefinition, ProgramReadBinding, ProgramReadBindingAuthTarget, ProgramReadDescriptor, ProgramReadDescriptors, ProgramReadOf, ProgramReadOverride, ProgramReadOverrides, ProgramReadRequest, ProgramReadTransport, ProgramReleaseReference, ProgramRuntimeExtensionCarrier, ProgramRuntimeExtensions, ProgramSdkDefinition, ProgramSdkIdentity, ProgramsInterface, QueriesInterface, QueryLease, QuerySnapshot, RawAccountInfo, RawInstructionsInterface, RawProgramsInterface, ReadArgumentCount, ReadArgumentCounts, ReadContext, ReadTransportMethod, ReadyRecoveryAction, ReadyRecoveryActionV1, RecoveryAction, ReplayErrorCode, ReplayWindow, ResolvedAccount, ResolvedAccounts, ResolvedTransactionBuildOptions, ResolvedTransactionResourceOptions, ResourceLamports, ResourceUnits, RichUpdate, RichUpdateCallback, Schema, SchemaResult, SeedDef, SendOptions, SendResult, Session, SessionDefinition, SessionMemberOptions, SessionOptions, SignerRegistry, SingleTransactionOperationReceipt, SnapshotEntity, SnapshotFrame, SocketIssue, SocketIssueCallback, SolanaGatewayAuthMetadata, SolanaGatewayAuthScope, SolanaGatewayBindingAuthTarget, SortConfig, SortOrder, StackConnectedExtensions, StackDefinition, StackEndpoints, StackExtensionClient, StackExtensionInput, StackQueryDefinition, StackRelease, StackRuntimeExtensionCarrier, StackRuntimeExtensions, StackVersionRefusal, StackWithAttachedPrograms, StorageAdapter, StorageAdapterConfig, StringifiedBigints, SubmittedUnknownTransactionOutcome, SubscribeCallback, SubscribedFrame, Subscription, SubscriptionIdentity, SubscriptionOptions, SubscriptionQuery, SubscriptionRequest, SubscriptionSnapshotOptions, TokenAccountInfo, TokenBalanceInfo, TokenBalanceInput, TransactionAccountBalance, TransactionBuildCapability, TransactionBuildOptions, TransactionCommitment, TransactionExecutionMetadata, TransactionFailureOutcome, TransactionFailurePhase, TransactionFailureStatus, TransactionFeeResult, TransactionInspectOptions, TransactionInspectionOptions, TransactionInspectionResult, TransactionOperation, TransactionOperationNamespace, TransactionOptions, TransactionOptionsErrorCode, TransactionOutcome, TransactionRequestContext, TransactionResourceOptionKey, TransactionResourceOptions, TransactionSendOptions, TransactionSendResult, TransactionSignatureStatus, TransactionSimulationOptions, TransactionSimulationResult, TransactionTransport, TransactionTransportErrorBody, TransactionVersion, TypedAccountReader, TypedInstruction, TypedListView, TypedQueryExecutor, TypedStateView, TypedViewGroup, TypedViews, UnsubscribeFn, UnsubscribedFrame, Update, UpdateCallback, UsageLimit, ViewDef, ViewGroup, ViewKeyFields, ViewKeyValue, ViewSortConfig, WaitForProcessedSlotOptions, WalletAdapter, WalletConnectOptions, WalletExecutionContext, WalletState, WatchOptions, WebSocketFactoryInit };

package/dist/index.esm.js

@@ -1041,6 +1041,124 @@ const AUTH_ERROR_CODES_BY_WIRE = {
     'stack-version-unknown': 'STACK_VERSION_UNKNOWN',
 };
 
+/** Environment variable read for a secret-class key outside browsers. */
+const ARETE_API_KEY_ENV = 'ARETE_API_KEY';
+const CREATE_PUBLISHABLE_HINT = 'create one with `a4 auth keys create-publishable --origin <scheme://host[:port]>`';
+const PUBLISHABLE_PREFIXES = ['a4_pk_', 'hspk_'];
+const SECRET_PREFIXES = ['a4_sk_', 'a4_ak_', 'hsk_'];
+function classifyApiKey(key) {
+    const trimmed = key.trim();
+    if (PUBLISHABLE_PREFIXES.some((prefix) => trimmed.startsWith(prefix)))
+        return 'publishable';
+    if (SECRET_PREFIXES.some((prefix) => trimmed.startsWith(prefix)))
+        return 'secret';
+    return 'unknown';
+}
+/**
+ * True in a browser page: both `window` and `document` exist. Web workers,
+ * service workers, edge runtimes, SSR (Node/Bun) and Deno have no `document`
+ * and count as server-side.
+ */
+function isBrowserEnvironment() {
+    const scope = globalThis;
+    return typeof scope.window === 'object'
+        && scope.window !== null
+        && typeof scope.document === 'object'
+        && scope.document !== null;
+}
+/**
+ * Read an environment variable in Node, Bun or Deno without prompting for or
+ * failing on missing permissions. Browsers have no environment.
+ */
+function readEnvironmentVariable(name) {
+    try {
+        const deno = globalThis.Deno;
+        if (deno) {
+            // Reading without --allow-env throws or prompts; ask first.
+            const state = deno.permissions?.querySync?.({ name: 'env', variable: name })?.state;
+            if (state !== 'granted')
+                return undefined;
+            const value = deno.env?.get?.(name);
+            return typeof value === 'string' ? value : undefined;
+        }
+        const value = globalThis
+            .process?.env?.[name];
+        return typeof value === 'string' ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+const warned$1 = new Set();
+function warnOnce$1(id, message) {
+    if (warned$1.has(id))
+        return;
+    warned$1.add(id);
+    console.warn(`[arete] ${message}`);
+}
+function hasExplicitAuth(auth) {
+    return auth !== undefined && (auth.token !== undefined
+        || auth.getToken !== undefined
+        || auth.tokenEndpoint !== undefined
+        || auth.publishableKey !== undefined
+        || auth.secretKey !== undefined);
+}
+/**
+ * Validate the configured API keys and apply the `ARETE_API_KEY` fallback.
+ *
+ * - `secretKey` is refused in browsers and refuses publishable keys.
+ * - A secret-class key in `publishableKey` is refused in browsers and warned
+ *   about elsewhere (it still works server-side, as it always has).
+ * - Outside browsers, when no auth option is set at all, `ARETE_API_KEY`
+ *   supplies `secretKey`.
+ *
+ * Error and warning text never includes key material.
+ */
+function resolveAuthConfig(auth) {
+    const browser = isBrowserEnvironment();
+    if (auth?.secretKey !== undefined) {
+        if (browser) {
+            throw new AreteError('auth.secretKey cannot be used in a browser: anything shipped to a browser is public. '
+                + 'Use auth.publishableKey with a publishable key (a4_pk_...) instead; '
+                + `${CREATE_PUBLISHABLE_HINT}. Keep secret and agent keys on servers and in local scripts.`, 'INVALID_CONFIG');
+        }
+        if (auth.secretKey.trim() === '') {
+            throw new AreteError('auth.secretKey is empty', 'INVALID_CONFIG');
+        }
+        if (classifyApiKey(auth.secretKey) === 'publishable') {
+            throw new AreteError('auth.secretKey was given a publishable key (a4_pk_...). Pass it as auth.publishableKey '
+                + 'instead; auth.secretKey takes an agent key (a4_ak_...) or secret key (a4_sk_...).', 'INVALID_CONFIG');
+        }
+        if (auth.publishableKey !== undefined) {
+            throw new AreteError('Set either auth.secretKey (servers and scripts) or auth.publishableKey (browsers), not both.', 'INVALID_CONFIG');
+        }
+    }
+    if (auth?.publishableKey !== undefined && classifyApiKey(auth.publishableKey) === 'secret') {
+        if (browser) {
+            throw new AreteError('auth.publishableKey was given a secret-class key (a4_sk_... or a4_ak_...). Never ship a '
+                + 'secret or agent key to a browser. Use a publishable key (a4_pk_...) instead; '
+                + `${CREATE_PUBLISHABLE_HINT}.`, 'INVALID_CONFIG');
+        }
+        warnOnce$1('secret-in-publishable', 'auth.publishableKey was given a secret-class key (a4_sk_... or a4_ak_...). '
+            + 'Pass it as auth.secretKey instead (servers and scripts only), or set ARETE_API_KEY.');
+    }
+    if (browser || hasExplicitAuth(auth))
+        return auth;
+    const environmentKey = readEnvironmentVariable(ARETE_API_KEY_ENV)?.trim();
+    if (!environmentKey)
+        return auth;
+    if (classifyApiKey(environmentKey) === 'publishable') {
+        warnOnce$1('publishable-in-env', `${ARETE_API_KEY_ENV} holds a publishable key (a4_pk_...) and was ignored. Set it to an agent `
+            + 'key (a4_ak_...) or secret key (a4_sk_...), or pass the publishable key as auth.publishableKey.');
+        return auth;
+    }
+    return { ...auth, secretKey: environmentKey };
+}
+/** The key sent as the token endpoint bearer credential, if any. */
+function tokenEndpointApiKey(auth) {
+    return auth?.secretKey ?? auth?.publishableKey;
+}
+
 const GZIP_MAGIC_0 = 0x1f;
 const GZIP_MAGIC_1 = 0x8b;
 const FRAME_MODES = new Set(['state', 'append', 'list']);
@@ -1848,7 +1966,7 @@ class ConnectionManager {
         this.reconnectIntervals = config.reconnectIntervals ?? DEFAULT_CONFIG.reconnectIntervals;
         this.maxReconnectAttempts =
             config.maxReconnectAttempts ?? DEFAULT_CONFIG.maxReconnectAttempts;
-        this.authConfig = config.auth;
+        this.authConfig = resolveAuthConfig(config.auth);
         this.release = normalizeStackRelease(config.release);
         this.authFetch = config.fetch ?? ((input, init) => {
             if (typeof globalThis.fetch !== 'function') {
@@ -2100,12 +2218,11 @@ class ConnectionManager {
         };
     }
     async fetchTokenFromEndpoint(tokenEndpoint, request) {
+        const apiKey = tokenEndpointApiKey(this.authConfig);
         const response = await this.authFetch(tokenEndpoint, {
             method: 'POST',
             headers: {
-                ...(this.authConfig?.publishableKey
-                    ? { Authorization: `Bearer ${this.authConfig.publishableKey}` }
-                    : {}),
+                ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
                 ...(this.authConfig?.tokenEndpointHeaders ?? {}),
                 'Content-Type': 'application/json',
             },
@@ -5451,7 +5568,10 @@ function hasRuntimeAuthStrategy(auth) {
         || auth?.getToken !== undefined
         || auth?.tokenEndpoint !== undefined;
 }
-function bindingAuthConfig(binding, runtimeAuth) {
+function bindingAuthConfig(binding, configuredAuth) {
+    // Resolve ARETE_API_KEY before the binding endpoint is filled in, so an
+    // otherwise unconfigured client still authenticates.
+    const runtimeAuth = resolveAuthConfig(configuredAuth);
     if (hasRuntimeAuthStrategy(runtimeAuth))
         return runtimeAuth;
     if (!binding.auth.required)
@@ -7498,7 +7618,10 @@ function parseProgramReadResponse(response, path, body) {
         throw new AreteError(`Program read '${path}' returned invalid JSON`, 'INVALID_RESPONSE', error);
     }
 }
-function hostedAuthConfig(binding, runtimeAuth) {
+function hostedAuthConfig(binding, configuredAuth) {
+    // Resolve ARETE_API_KEY before the binding endpoint is filled in, so an
+    // otherwise unconfigured client still authenticates.
+    const runtimeAuth = resolveAuthConfig(configuredAuth);
     const metadata = binding.auth;
     const runtimeStrategyConfigured = runtimeAuth?.token !== undefined
         || runtimeAuth?.getToken !== undefined
@@ -8972,5 +9095,5 @@ function stringifyBigints(value) {
 
 const Arete = Object.assign(Arete$1, { session: createSession });
 
-export { API_PROBLEM_SCHEMA_VERSION, ASSOCIATED_TOKEN_PROGRAM_ADDRESS, Arete, AreteError, CLAIM_AGENT_MATERIALIZER_PATH, ConnectionManager, DEFAULT_CONFIG, DEFAULT_INITIAL_DATA_TIMEOUT_MS, DEFAULT_MAX_ENTRIES_PER_VIEW, EXTENSION_API_VERSION, FrameProcessor, InitialDataTimeoutError, InstructionError, MANAGED_SOLANA_CONTRACT_VERSION, MAX_MANAGED_BATCH_ADDRESSES, MAX_MANAGED_PAGE_SIZE, MemoryAdapter, OPERATION_KIND, OperationCallbackError, OperationExecutionError, PROGRAM_KEY_CONFLICT, PROGRAM_OPERATION_EXTENSIONS, ProcessedSlotTimeoutError, QueryStore, ReadRequestError, SPL_TOKEN_PROGRAM_ADDRESS, STACK_RUNTIME_EXTENSIONS, SYSTEM_PROGRAM_ADDRESS, StreamGapError, SubscriptionRegistry, TOKEN_2022_PROGRAM_ADDRESS, TRANSACTION_RESOURCE_OPTION_KEYS, TransactionExecutionError, TransactionOptionsError, TransactionTransportError, account, accountTombstone, appendFlowTransactions, appendTransactionInstructions, applyConnectedStackExtensions, arg, buildInstruction, bytes, canonicalQueryKey, chainAccountLoader, compareProgramIdentity, createChainClient, createEntityStream, createHostedSolanaGatewayTransports, createInstructionExecutor, createInstructionHandler, createPreparedFlow, createPreparedInstruction, createPreparedTransaction, createPreparedTransactionBody, createProgramPdas, createPublicKeySeed, createRichUpdateStream, createSeed, createSession, createSignerRegistry, createSubscriptionId, createTransactionTransport, createTypedListView, createTypedStateView, createTypedViews, createUpdateStream, decodeBase58, defineProgramExtensions, defineStackExtensions, deriveAssociatedTokenAccount, deriveHttpEndpoint, findProgramAddress as derivePda, describePreparedOperation, encodeBase58, executeInstruction, executePreparedOperation, extendProgram, extendPrograms, extendStack, findProgramAddress, findProgramAddressSync, flowOperation, formatPreparedOperation, formatProgramError, formatRawToUi, getMintDecimals, getOperationKind, getProgramRuntimeExtensions, getStackRuntimeExtensions, getTransactionFailureOutcome, hostedWebsocketSuffixes, inspectPreparedOperation, instructionOperation, isClaimAgentRecoveryAction, isEntityFrame, isErrorFrame, isHostedAreteEndpoint, isReplayErrorCode, isSafeClaimActionUrl, isSameProgramSdk, isSnapshotFrame, isStackVersionRefusalCode, isSubscribedFrame, isUnsubscribedFrame, isValidFrame, literal, managedAddress, managedContext, managedDiscovery, managedPage, managedReadOptions, managedU64, normalizeSubscription, normalizeSubscriptionQuery, normalizeSubscriptionRequest, normalizeTransactionError, parseApiProblem, parseFrame, parseFrameFromBlob, parseInstructionError, parseUiAmountToRaw, pda, prependFlowTransactionInstructions, prependTransactionInstructions, programAccountRead, programQuery, resolveAccounts, resolveAmount, resolveAmountToRaw, resolveAmountsToRaw, resolveTokenProgramAddress, resolveTransactionBuildOptions, safeToRawAmount, serializeInstructionData, serializeViewKey, setHostedWebsocketSuffixes, stackQuery, stringifyBigints, toJsonValue, toRawAmount, toWireResourceOptions, transactionOperation, unwrapOperationExecutionError, validateAccountResolution, validateProgramReadDescriptor, validateSubscriptionId, withProgramIdentity, withProgramRead, withPrograms };
+export { API_PROBLEM_SCHEMA_VERSION, ARETE_API_KEY_ENV, ASSOCIATED_TOKEN_PROGRAM_ADDRESS, Arete, AreteError, CLAIM_AGENT_MATERIALIZER_PATH, ConnectionManager, DEFAULT_CONFIG, DEFAULT_INITIAL_DATA_TIMEOUT_MS, DEFAULT_MAX_ENTRIES_PER_VIEW, EXTENSION_API_VERSION, FrameProcessor, InitialDataTimeoutError, InstructionError, MANAGED_SOLANA_CONTRACT_VERSION, MAX_MANAGED_BATCH_ADDRESSES, MAX_MANAGED_PAGE_SIZE, MemoryAdapter, OPERATION_KIND, OperationCallbackError, OperationExecutionError, PROGRAM_KEY_CONFLICT, PROGRAM_OPERATION_EXTENSIONS, ProcessedSlotTimeoutError, QueryStore, ReadRequestError, SPL_TOKEN_PROGRAM_ADDRESS, STACK_RUNTIME_EXTENSIONS, SYSTEM_PROGRAM_ADDRESS, StreamGapError, SubscriptionRegistry, TOKEN_2022_PROGRAM_ADDRESS, TRANSACTION_RESOURCE_OPTION_KEYS, TransactionExecutionError, TransactionOptionsError, TransactionTransportError, account, accountTombstone, appendFlowTransactions, appendTransactionInstructions, applyConnectedStackExtensions, arg, buildInstruction, bytes, canonicalQueryKey, chainAccountLoader, classifyApiKey, compareProgramIdentity, createChainClient, createEntityStream, createHostedSolanaGatewayTransports, createInstructionExecutor, createInstructionHandler, createPreparedFlow, createPreparedInstruction, createPreparedTransaction, createPreparedTransactionBody, createProgramPdas, createPublicKeySeed, createRichUpdateStream, createSeed, createSession, createSignerRegistry, createSubscriptionId, createTransactionTransport, createTypedListView, createTypedStateView, createTypedViews, createUpdateStream, decodeBase58, defineProgramExtensions, defineStackExtensions, deriveAssociatedTokenAccount, deriveHttpEndpoint, findProgramAddress as derivePda, describePreparedOperation, encodeBase58, executeInstruction, executePreparedOperation, extendProgram, extendPrograms, extendStack, findProgramAddress, findProgramAddressSync, flowOperation, formatPreparedOperation, formatProgramError, formatRawToUi, getMintDecimals, getOperationKind, getProgramRuntimeExtensions, getStackRuntimeExtensions, getTransactionFailureOutcome, hostedWebsocketSuffixes, inspectPreparedOperation, instructionOperation, isClaimAgentRecoveryAction, isEntityFrame, isErrorFrame, isHostedAreteEndpoint, isReplayErrorCode, isSafeClaimActionUrl, isSameProgramSdk, isSnapshotFrame, isStackVersionRefusalCode, isSubscribedFrame, isUnsubscribedFrame, isValidFrame, literal, managedAddress, managedContext, managedDiscovery, managedPage, managedReadOptions, managedU64, normalizeSubscription, normalizeSubscriptionQuery, normalizeSubscriptionRequest, normalizeTransactionError, parseApiProblem, parseFrame, parseFrameFromBlob, parseInstructionError, parseUiAmountToRaw, pda, prependFlowTransactionInstructions, prependTransactionInstructions, programAccountRead, programQuery, resolveAccounts, resolveAmount, resolveAmountToRaw, resolveAmountsToRaw, resolveTokenProgramAddress, resolveTransactionBuildOptions, safeToRawAmount, serializeInstructionData, serializeViewKey, setHostedWebsocketSuffixes, stackQuery, stringifyBigints, toJsonValue, toRawAmount, toWireResourceOptions, transactionOperation, unwrapOperationExecutionError, validateAccountResolution, validateProgramReadDescriptor, validateSubscriptionId, withProgramIdentity, withProgramRead, withPrograms };
 //# sourceMappingURL=index.esm.js.map