@usearete/sdk 0.32.0 → 0.34.0

package/dist/index.cjs

@@ -1043,6 +1043,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']);
@@ -1850,7 +2483,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') {
@@ -2102,12 +2735,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',
             },
@@ -2134,9 +2766,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)
@@ -5453,7 +6093,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)
@@ -7500,7 +8143,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
@@ -8975,6 +9621,7 @@ function stringifyBigints(value) {
 const Arete = Object.assign(Arete$1, { session: createSession });
 
 exports.API_PROBLEM_SCHEMA_VERSION = API_PROBLEM_SCHEMA_VERSION;
+exports.ARETE_API_KEY_ENV = ARETE_API_KEY_ENV;
 exports.ASSOCIATED_TOKEN_PROGRAM_ADDRESS = ASSOCIATED_TOKEN_PROGRAM_ADDRESS;
 exports.Arete = Arete;
 exports.AreteError = AreteError;
@@ -9019,6 +9666,7 @@ exports.buildInstruction = buildInstruction;
 exports.bytes = bytes;
 exports.canonicalQueryKey = canonicalQueryKey;
 exports.chainAccountLoader = chainAccountLoader;
+exports.classifyApiKey = classifyApiKey;
 exports.compareProgramIdentity = compareProgramIdentity;
 exports.createChainClient = createChainClient;
 exports.createEntityStream = createEntityStream;