@usearete/sdk 0.32.0 → 0.34.0

package/dist/index.esm.js

@@ -1041,6 +1041,639 @@ const AUTH_ERROR_CODES_BY_WIRE = {
     'stack-version-unknown': 'STACK_VERSION_UNKNOWN',
 };
 
+/**
+ * The key from the active `a4` CLI login, for servers and local scripts.
+ *
+ * The `a4` CLI stores the keys it logs in with in a TOML credentials file
+ * (`~/.arete/credentials.toml`, or `ARETE_CREDENTIALS_PATH`), keyed by profile
+ * and API URL. This module mirrors the CLI's lookup (the Rust SDK's
+ * `credentials` module is the reference):
+ *
+ * - Profile: `.arete/auth.toml` in the working directory (may pin only the
+ *   `agent` profile), then `ARETE_PROFILE`, then the single profile holding a
+ *   key for the API URL. More than one candidate means no key.
+ * - Only the key stored for the default Arete API is used, because that is
+ *   where the SDK's default token endpoint sends it. Keys the CLI stored for
+ *   another API URL are never sent anywhere else.
+ * - Any problem (no file, unreadable, malformed, ambiguous) means no key.
+ *
+ * Browser safety: nothing here is imported statically from Node. Node builtins
+ * are reached at call time through `process.getBuiltinModule` (Node 20.16+,
+ * 22.3+, Bun), Deno through its own permission-checked APIs, so bundlers see no
+ * `fs` import. Callers must not call this in a browser; `resolveAuthConfig`
+ * returns before reaching it there.
+ */
+/** API URL whose key the SDK may use: its default token endpoint's origin. */
+const DEFAULT_A4_API_URL = 'https://api.arete.run';
+/**
+ * True when `url` is on the API the `a4` login key was stored for. A key
+ * found in the login is only ever sent there, never to an endpoint a stack
+ * names on another host.
+ */
+function isA4LoginKeyDestination(url) {
+    try {
+        const parsed = new URL(url);
+        const host = parsed.hostname.toLowerCase().replace(/\.+$/, '');
+        return parsed.protocol === 'https:'
+            && host === new URL(DEFAULT_A4_API_URL).hostname
+            && (parsed.port === '' || parsed.port === '443')
+            && parsed.username === ''
+            && parsed.password === '';
+    }
+    catch {
+        return false;
+    }
+}
+const PROFILE_ENV = 'ARETE_PROFILE';
+const CREDENTIALS_PATH_ENV = 'ARETE_CREDENTIALS_PATH';
+const AGENT_PROFILE = 'agent';
+const HUMAN_PROFILE = 'human';
+// ── Minimal TOML reader ─────────────────────────────────────────────────────
+//
+// Covers what the CLI writes (`[a.b."c"]` tables and `key = "string"`
+// pairs) plus one-line scalars. Anything else (arrays, inline tables,
+// multi-line strings) makes the whole document unreadable, which means
+// "no key" rather than a guess.
+/** A one-line non-string value (number, boolean, date); its text is unused. */
+class TomlScalar {
+    constructor(text) {
+        this.text = text;
+    }
+}
+class TomlUnsupported extends Error {
+}
+function isTable(value) {
+    return typeof value === 'object' && !(value instanceof TomlScalar);
+}
+function readBasicString(line, start) {
+    let out = '';
+    let index = start + 1;
+    while (index < line.length) {
+        const char = line[index];
+        if (char === '"')
+            return [out, index + 1];
+        if (char === '\\') {
+            const next = line[index + 1];
+            const simple = {
+                b: '\b', t: '\t', n: '\n', f: '\f', r: '\r', '"': '"', '\\': '\\',
+            };
+            if (next !== undefined && simple[next] !== undefined) {
+                out += simple[next];
+                index += 2;
+                continue;
+            }
+            if (next === 'u' || next === 'U') {
+                const length = next === 'u' ? 4 : 8;
+                const hex = line.slice(index + 2, index + 2 + length);
+                if (!/^[0-9a-fA-F]+$/.test(hex) || hex.length !== length)
+                    throw new TomlUnsupported();
+                out += String.fromCodePoint(parseInt(hex, 16));
+                index += 2 + length;
+                continue;
+            }
+            throw new TomlUnsupported();
+        }
+        out += char;
+        index += 1;
+    }
+    throw new TomlUnsupported();
+}
+function readLiteralString(line, start) {
+    const end = line.indexOf("'", start + 1);
+    if (end < 0)
+        throw new TomlUnsupported();
+    return [line.slice(start + 1, end), end + 1];
+}
+function skipSpaces(line, index) {
+    while (index < line.length && (line[index] === ' ' || line[index] === '\t'))
+        index += 1;
+    return index;
+}
+/** Read a dotted key (`a."b".c`) ending at `terminator`. */
+function readKey(line, start, terminator) {
+    const parts = [];
+    let index = skipSpaces(line, start);
+    for (;;) {
+        let part;
+        if (line[index] === '"') {
+            [part, index] = readBasicString(line, index);
+        }
+        else if (line[index] === "'") {
+            [part, index] = readLiteralString(line, index);
+        }
+        else {
+            const match = /^[A-Za-z0-9_-]+/.exec(line.slice(index));
+            if (!match)
+                throw new TomlUnsupported();
+            part = match[0];
+            index += part.length;
+        }
+        parts.push(part);
+        index = skipSpaces(line, index);
+        if (line[index] === '.') {
+            index = skipSpaces(line, index + 1);
+            continue;
+        }
+        if (line.startsWith(terminator, index))
+            return [parts, index + terminator.length];
+        throw new TomlUnsupported();
+    }
+}
+function assertRestIsComment(line, index) {
+    const rest = line.slice(index).trim();
+    if (rest !== '' && !rest.startsWith('#'))
+        throw new TomlUnsupported();
+}
+function tableAt(root, path) {
+    let table = root;
+    for (const part of path) {
+        const existing = table[part];
+        if (existing === undefined) {
+            const created = Object.create(null);
+            table[part] = created;
+            table = created;
+        }
+        else if (isTable(existing)) {
+            table = existing;
+        }
+        else {
+            throw new TomlUnsupported();
+        }
+    }
+    return table;
+}
+/** @internal Parse the subset of TOML described above; throws when unsupported. */
+function parseSimpleToml(content) {
+    const root = Object.create(null);
+    let current = root;
+    for (const rawLine of content.replace(/^/, '').split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (line === '' || line.startsWith('#'))
+            continue;
+        if (line.startsWith('[['))
+            throw new TomlUnsupported();
+        if (line.startsWith('[')) {
+            const [path, end] = readKey(line, 1, ']');
+            assertRestIsComment(line, end);
+            current = tableAt(root, path);
+            continue;
+        }
+        const [path, afterEquals] = readKey(line, 0, '=');
+        const valueStart = skipSpaces(line, afterEquals);
+        let value;
+        let end;
+        if (line.startsWith('"""', valueStart) || line.startsWith("'''", valueStart)) {
+            throw new TomlUnsupported();
+        }
+        else if (line[valueStart] === '"') {
+            [value, end] = readBasicString(line, valueStart);
+        }
+        else if (line[valueStart] === "'") {
+            [value, end] = readLiteralString(line, valueStart);
+        }
+        else {
+            const match = /^[A-Za-z0-9_:.+-]+(?:[ T][0-9:.+Z-]+)?/.exec(line.slice(valueStart));
+            if (!match)
+                throw new TomlUnsupported();
+            value = new TomlScalar(match[0]);
+            end = valueStart + match[0].length;
+        }
+        assertRestIsComment(line, end);
+        const key = path[path.length - 1];
+        const table = tableAt(current, path.slice(0, -1));
+        if (Object.prototype.hasOwnProperty.call(table, key))
+            throw new TomlUnsupported();
+        table[key] = value;
+    }
+    return root;
+}
+// ── Lookup (mirror of the Rust `lookup_credentials`) ─────────────────────────
+/** Mirror of the CLI's API URL normalisation for credential lookup. */
+function normalizeA4ApiUrl(url) {
+    const trimmed = url.trim().replace(/\/+$/, '');
+    const schemeAt = trimmed.indexOf('://');
+    const scheme = schemeAt >= 0 ? trimmed.slice(0, schemeAt).toLowerCase() : '';
+    const rest = schemeAt >= 0 ? trimmed.slice(schemeAt + 3) : trimmed;
+    const authorityEnd = rest.search(/[/?#]/);
+    const authority = authorityEnd >= 0 ? rest.slice(0, authorityEnd) : rest;
+    const tail = authorityEnd >= 0 ? rest.slice(authorityEnd) : '';
+    const hostStart = authority.lastIndexOf('@') + 1;
+    const hostPort = authority.slice(hostStart);
+    let host;
+    let port;
+    if (hostPort.startsWith('[')) {
+        const close = hostPort.indexOf(']');
+        host = close >= 0 ? hostPort.slice(0, close + 1) : hostPort;
+        port = close >= 0 ? hostPort.slice(close + 1) : '';
+    }
+    else {
+        const colon = hostPort.lastIndexOf(':');
+        host = colon >= 0 ? hostPort.slice(0, colon) : hostPort;
+        port = colon >= 0 ? hostPort.slice(colon) : '';
+    }
+    host = host.replace(/\.+$/, '').toLowerCase();
+    return `${scheme ? `${scheme}://` : ''}${authority.slice(0, hostStart)}${host}${port}${tail}`;
+}
+function stringMap(value) {
+    if (value === undefined)
+        return undefined;
+    if (!isTable(value))
+        throw new TomlUnsupported();
+    const out = new Map();
+    for (const [key, entry] of Object.entries(value)) {
+        if (typeof entry !== 'string')
+            throw new TomlUnsupported();
+        out.set(key, entry);
+    }
+    return out;
+}
+function findUrlKey(keys, apiUrl) {
+    if (!keys)
+        return undefined;
+    const wanted = normalizeA4ApiUrl(apiUrl);
+    const exact = (keys.get(apiUrl) ?? keys.get(wanted))?.trim();
+    if (exact)
+        return exact;
+    return [...keys.entries()]
+        .filter(([url]) => normalizeA4ApiUrl(url) === wanted)
+        .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+        .map(([, key]) => key.trim())
+        .find((key) => key !== '');
+}
+function isValidProfileName(profile) {
+    return profile.length > 0 && profile.length <= 64 && /^[A-Za-z0-9_-]+$/.test(profile);
+}
+function keyFitsProfile(profile, key) {
+    const agentKey = key.trim().startsWith('a4_ak_');
+    if (profile === AGENT_PROFILE)
+        return agentKey;
+    if (profile === HUMAN_PROFILE)
+        return !agentKey;
+    return true;
+}
+/** @internal Mirror of the Rust `lookup_credentials`. */
+function lookupA4Credentials(content, apiUrl, requestedProfile) {
+    let profiles;
+    let legacyKeys;
+    let legacyApiKey;
+    try {
+        const parsed = parseSimpleToml(content);
+        const profilesValue = parsed['profiles'];
+        if (profilesValue !== undefined && !isTable(profilesValue))
+            return { kind: 'invalid' };
+        profiles = Object.entries(profilesValue ?? {}).map(([name, profile]) => {
+            if (!isTable(profile))
+                throw new TomlUnsupported();
+            return [name, stringMap(profile['keys'])];
+        });
+        legacyKeys = stringMap(parsed['keys']);
+        const apiKey = parsed['api_key'];
+        if (apiKey !== undefined && typeof apiKey !== 'string')
+            return { kind: 'invalid' };
+        legacyApiKey = apiKey?.trim() || undefined;
+    }
+    catch {
+        return { kind: 'invalid' };
+    }
+    const legacy = findUrlKey(legacyKeys, apiUrl) ?? legacyApiKey;
+    if (requestedProfile !== undefined) {
+        if (!isValidProfileName(requestedProfile))
+            return { kind: 'invalid' };
+        const entry = profiles.find(([name]) => name === requestedProfile);
+        const key = findUrlKey(entry?.[1], apiUrl);
+        if (key !== undefined) {
+            return keyFitsProfile(requestedProfile, key) ? { kind: 'key', key } : { kind: 'invalid' };
+        }
+        if (legacy !== undefined) {
+            const compatible = requestedProfile === AGENT_PROFILE
+                ? legacy.startsWith('a4_ak_')
+                : requestedProfile === HUMAN_PROFILE && !legacy.startsWith('a4_ak_');
+            if (compatible)
+                return { kind: 'key', key: legacy };
+        }
+        return { kind: 'none' };
+    }
+    const matches = profiles
+        .map(([name, keys]) => [name, findUrlKey(keys, apiUrl)])
+        .filter((entry) => entry[1] !== undefined);
+    if (matches.length > 1)
+        return { kind: 'ambiguous' };
+    if (matches.length === 1) {
+        const [name, key] = matches[0];
+        return keyFitsProfile(name, key) ? { kind: 'key', key } : { kind: 'invalid' };
+    }
+    return legacy !== undefined ? { kind: 'key', key: legacy } : { kind: 'none' };
+}
+/** Selected profile: `undefined` for none, `null` when selection is invalid. */
+function selectProfile(host) {
+    // The project file can pin the agent profile; if it cannot be checked
+    // (unknown working directory, denied or failed read), choose nothing rather
+    // than risk a profile the project excludes.
+    const cwd = host.cwd();
+    if (cwd === undefined)
+        return null;
+    let project;
+    try {
+        project = host.readTextFile(host.joinPath(cwd, '.arete', 'auth.toml'));
+    }
+    catch {
+        return null;
+    }
+    if (project !== null) {
+        try {
+            const profile = parseSimpleToml(project)['default_profile'];
+            return profile === AGENT_PROFILE ? AGENT_PROFILE : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    const profile = host.readEnv(PROFILE_ENV)?.trim();
+    if (profile === undefined)
+        return undefined;
+    return isValidProfileName(profile) ? profile : null;
+}
+/**
+ * @internal Key of the active `a4` login for the default Arete API, or
+ * `undefined`. Never throws. The caller checks the key class.
+ */
+function readA4ProfileKey(host = systemProfileHost()) {
+    if (!host)
+        return {};
+    try {
+        const profile = selectProfile(host);
+        if (profile === null)
+            return {};
+        const override = host.readEnv(CREDENTIALS_PATH_ENV);
+        let path;
+        if (override) {
+            path = override;
+        }
+        else {
+            const home = host.homeDir();
+            path = home ? host.joinPath(home, '.arete', 'credentials.toml') : undefined;
+        }
+        if (!path)
+            return {};
+        const content = host.readTextFile(path);
+        if (content === null)
+            return {};
+        const lookup = lookupA4Credentials(content, DEFAULT_A4_API_URL, profile);
+        if (lookup.kind === 'key')
+            return { key: lookup.key };
+        if (lookup.kind === 'ambiguous')
+            return { ambiguous: true };
+        return {};
+    }
+    catch {
+        return {};
+    }
+}
+function denoHost(deno) {
+    const granted = (descriptor) => {
+        try {
+            return deno.permissions?.querySync?.(descriptor)?.state === 'granted';
+        }
+        catch {
+            return false;
+        }
+    };
+    const readEnv = (name) => granted({ name: 'env', variable: name }) ? deno.env?.get?.(name) : undefined;
+    const separator = deno.build?.os === 'windows' ? '\\' : '/';
+    return {
+        readEnv,
+        readTextFile(path) {
+            // Without --allow-read Deno would prompt or throw; ask first. Denied
+            // access is not a missing file: callers must not treat it as absent.
+            if (!deno.readTextFileSync)
+                throw new Error('file reads unavailable');
+            if (!granted({ name: 'read', path }))
+                throw new Error('read permission not granted');
+            try {
+                return deno.readTextFileSync(path);
+            }
+            catch (error) {
+                const notFound = deno.errors?.NotFound;
+                if (notFound && error instanceof notFound)
+                    return null;
+                throw error;
+            }
+        },
+        cwd() {
+            if (!granted({ name: 'read' }))
+                return undefined;
+            try {
+                return deno.cwd?.();
+            }
+            catch {
+                return undefined;
+            }
+        },
+        homeDir: () => readEnv('HOME') ?? readEnv('USERPROFILE'),
+        joinPath: (...parts) => parts.join(separator),
+    };
+}
+function nodeHost(process) {
+    const load = process.getBuiltinModule;
+    if (typeof load !== 'function')
+        return undefined;
+    const fs = load.call(process, 'fs');
+    const os = load.call(process, 'os');
+    const path = load.call(process, 'path');
+    if (!fs || !os || !path)
+        return undefined;
+    return {
+        readEnv: (name) => process.env?.[name],
+        readTextFile(file) {
+            try {
+                return fs.readFileSync(file, 'utf8');
+            }
+            catch (error) {
+                if (error.code === 'ENOENT')
+                    return null;
+                throw error;
+            }
+        },
+        cwd: () => process.cwd?.(),
+        homeDir: () => os.homedir(),
+        joinPath: (...parts) => path.join(...parts),
+    };
+}
+/** Host for the current server runtime, or `undefined` where files are unreachable. */
+function systemProfileHost() {
+    try {
+        const scope = globalThis;
+        if (scope.Deno)
+            return denoHost(scope.Deno);
+        if (scope.process)
+            return nodeHost(scope.process);
+    }
+    catch {
+        // Fall through: no profile support in this runtime.
+    }
+    return undefined;
+}
+
+/** 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();
+/**
+ * Marks a resolved config whose `secretKey` came from the `a4` login. It holds
+ * that key, so the mark is carried through object spreads (binding paths copy
+ * the resolved config) and only applies while `secretKey` is still that key:
+ * a copy given another `secretKey` is no longer restricted. Per config, never
+ * process-wide, so the same key passed explicitly elsewhere is unaffected.
+ */
+const A4_LOGIN_SECRET_KEY = Symbol('arete.a4LoginSecretKey');
+/** True when `auth.secretKey` was supplied by the `a4` login fallback. */
+function secretKeyFromA4Login(auth) {
+    const marked = auth;
+    return marked?.secretKey !== undefined && marked[A4_LOGIN_SECRET_KEY] === marked.secretKey;
+}
+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 server-side credential chain.
+ *
+ * - `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`; without it, the agent or secret key from the active
+ *   `a4` CLI login does. Browsers never read either.
+ *
+ * Error and warning text never includes key material.
+ */
+function resolveAuthConfig(auth, readProfileKey = readA4ProfileKey) {
+    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) {
+        if (classifyApiKey(environmentKey) !== 'publishable') {
+            return { ...auth, secretKey: environmentKey };
+        }
+        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.');
+    }
+    const profile = readProfileKey();
+    if (profile.ambiguous) {
+        warnOnce$1('ambiguous-a4-profile', 'More than one a4 login profile holds a key; not choosing one. Set ARETE_PROFILE '
+            + `(for example \`agent\`) or ${ARETE_API_KEY_ENV}.`);
+    }
+    if (profile.key && classifyApiKey(profile.key) === 'secret') {
+        const resolved = {
+            ...auth,
+            secretKey: profile.key,
+            [A4_LOGIN_SECRET_KEY]: profile.key,
+        };
+        return resolved;
+    }
+    return auth;
+}
+/**
+ * Appended to a 401 for a request that carried no API key. It names the
+ * commands and options that supply one, never where credentials are stored.
+ */
+const NO_API_KEY_HINT = 'No Arete API key found. Run `a4 auth login` (or `a4 auth signup` for an agent), '
+    + 'or set ARETE_API_KEY, or pass auth.secretKey.';
+/**
+ * The key sent as the bearer credential to `endpoint`, if any. A key taken
+ * from the `a4` login is only sent to the Arete API it was stored for.
+ */
+function tokenEndpointApiKey(auth, endpoint) {
+    if (secretKeyFromA4Login(auth) && !isA4LoginKeyDestination(endpoint))
+        return undefined;
+    return auth?.secretKey ?? auth?.publishableKey;
+}
+/** True when `headers` carries its own `Authorization` header. */
+function hasAuthorizationHeader(headers) {
+    return Object.keys(headers ?? {}).some((name) => name.toLowerCase() === 'authorization');
+}
+
 const GZIP_MAGIC_0 = 0x1f;
 const GZIP_MAGIC_1 = 0x8b;
 const FRAME_MODES = new Set(['state', 'append', 'list']);
@@ -1848,7 +2481,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 +2733,11 @@ class ConnectionManager {
         };
     }
     async fetchTokenFromEndpoint(tokenEndpoint, request) {
+        const apiKey = tokenEndpointApiKey(this.authConfig, tokenEndpoint);
         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',
             },
@@ -2132,9 +2764,17 @@ class ConnectionManager {
                 : response.status === 429
                     ? 'QUOTA_EXCEEDED'
                     : 'AUTH_REQUIRED';
-            const errorMessage = typeof parsedError?.error === 'string' && parsedError.error.length > 0
+            const responseMessage = typeof parsedError?.error === 'string' && parsedError.error.length > 0
                 ? parsedError.error
                 : rawError || response.statusText || 'Authentication request failed';
+            // A server-side 401 for a request that carried no credential at all:
+            // say how to supply one. Custom Authorization headers have their own
+            // advice to give.
+            const sentCredential = Boolean(apiKey)
+                || hasAuthorizationHeader(this.authConfig?.tokenEndpointHeaders);
+            const errorMessage = response.status === 401 && !sentCredential && !isBrowserEnvironment()
+                ? `${responseMessage}. ${NO_API_KEY_HINT}`
+                : responseMessage;
             const retryAfterHeader = response.headers.get('Retry-After');
             const retryAfterSeconds = retryAfterHeader && /^\d+$/.test(retryAfterHeader)
                 ? Number(retryAfterHeader)
@@ -5451,7 +6091,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 +8141,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 +9618,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