@usearete/sdk 0.32.0 → 0.33.0

package/README.md

@@ -25,6 +25,32 @@ for await (const item of session.stacks.myStack.views.MyEntity.list.use()) {
 }
 ```
 
+## Authentication
+
+Pick the key by where the code runs:
+
+```ts
+// Servers, agents and local scripts (Node, Bun, Deno, workers, SSR):
+// an agent key (a4_ak_...) or secret key (a4_sk_...).
+const server = await createSession(
+  { stacks: { myStack: MY_STACK } },
+  { auth: { secretKey: process.env.ARETE_API_KEY } },
+);
+
+// Anything shipped to a browser: an origin-bound publishable key (a4_pk_...).
+// Create one with `a4 auth keys create-publishable --origin <scheme://host[:port]>`.
+const browser = await createSession(
+  { stacks: { myStack: MY_STACK } },
+  { auth: { publishableKey: import.meta.env.VITE_ARETE_PUBLISHABLE_KEY } },
+);
+```
+
+Outside a browser, when no `auth` option is set, the SDK reads `ARETE_API_KEY`
+itself, so `createSession({ stacks })` is enough on a server with that variable
+set. `secretKey` throws in a browser, as does a secret or agent key passed as
+`publishableKey`; a publishable key passed as `secretKey` is refused everywhere.
+Keys are never included in error messages or logs.
+
 ## SDK Shapes
 
 ### Mental Model

package/dist/index.cjs

@@ -1043,6 +1043,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']);
@@ -1850,7 +1968,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 +2220,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',
             },
@@ -5453,7 +5570,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 +7620,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 +9098,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 +9143,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;