@oxy.so/core 4.8.0 → 4.9.1

package/dist/cjs/HttpService.js

@@ -26,6 +26,7 @@ const redactUrl_1 = require("./utils/redactUrl");
 const OxyServices_errors_1 = require("./OxyServices.errors");
 const edgeRegion_1 = require("./utils/edgeRegion");
 const activityId_1 = require("./utils/activityId");
+const corsPreflight_1 = require("./utils/corsPreflight");
 const slashes_1 = require("./utils/slashes");
 /** Comparison only fences local async work; it never validates token authority. */
 function sameTokenSession(left, right) {
@@ -508,12 +509,17 @@ class HttpService {
                 const headers = {
                     Accept: 'application/json',
                 };
-                // Only set Content-Type for non-FormData requests (FormData sets it automatically with boundary)
-                if (isUrlEncoded) {
-                    headers['Content-Type'] = 'application/x-www-form-urlencoded;charset=UTF-8';
-                }
-                else if (!isFormData) {
-                    headers['Content-Type'] = 'application/json';
+                // Content-Type describes a body, so a GET (which never sends one) gets
+                // none: `application/json` is not a CORS-safelisted type, and on a GET it
+                // only made the browser preflight a request with nothing to describe.
+                // FormData sets its own multipart type with the boundary.
+                if (method !== 'GET') {
+                    if (isUrlEncoded) {
+                        headers['Content-Type'] = 'application/x-www-form-urlencoded;charset=UTF-8';
+                    }
+                    else if (!isFormData) {
+                        headers['Content-Type'] = 'application/json';
+                    }
                 }
                 // Add authorization header if available
                 if (authHeader) {
@@ -533,9 +539,14 @@ class HttpService {
                 }
                 // This is Cloudflare's coarse serving PoP (for example `mad`), never an
                 // IP or coordinate. Set it after caller headers so request code cannot
-                // accidentally or deliberately substitute a different origin.
-                Object.assign(headers, edgeRegionHeader);
-                Object.assign(headers, activityIdHeader);
+                // accidentally or deliberately substitute a different origin. Both are
+                // advisory telemetry, so they ride only on a request the browser
+                // preflights anyway: on an anonymous GET they were the only thing that
+                // made it non-simple, and every distinct URL paid an OPTIONS round trip.
+                if ((0, corsPreflight_1.requiresCorsPreflight)(method, Object.entries(headers))) {
+                    Object.assign(headers, edgeRegionHeader);
+                    Object.assign(headers, activityIdHeader);
+                }
                 // `URLSearchParams` is serialised explicitly rather than handed to
                 // `fetch` as-is: RN's fetch does not consistently encode it, and doing
                 // it here keeps the body identical across every platform.
@@ -1307,12 +1318,20 @@ class HttpService {
             headers.delete(name);
         if (authHeader)
             headers.set('Authorization', authHeader);
-        const edgeRegionHeader = (0, edgeRegion_1.peekBrowserEdgeRegionHeader)();
-        for (const [name, value] of Object.entries(edgeRegionHeader))
-            headers.set(name, value);
-        const activityIdHeader = (0, activityId_1.getBrowserActivityIdHeader)();
-        for (const [name, value] of Object.entries(activityIdHeader))
-            headers.set(name, value);
+        // Telemetry rides only on a request the browser preflights anyway — see
+        // `request()`.
+        const sentHeaders = [];
+        headers.forEach((value, name) => {
+            sentHeaders.push([name, value]);
+        });
+        if ((0, corsPreflight_1.requiresCorsPreflight)(config.method, sentHeaders)) {
+            const edgeRegionHeader = (0, edgeRegion_1.peekBrowserEdgeRegionHeader)();
+            for (const [name, value] of Object.entries(edgeRegionHeader))
+                headers.set(name, value);
+            const activityIdHeader = (0, activityId_1.getBrowserActivityIdHeader)();
+            for (const [name, value] of Object.entries(activityIdHeader))
+                headers.set(name, value);
+        }
         try {
             const body = config.method === 'GET' ? undefined : config.body;
             const init = {

package/dist/cjs/server/OxyServer.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OxyServer = exports.ServiceCredentialMismatchError = exports.ANONYMOUS_SERVICE_TOKEN_RETRY_MS = void 0;
+exports.OxyServer = exports.DEFAULT_SERVICE_TOKEN_AUDIENCE = exports.ServiceCredentialMismatchError = exports.ANONYMOUS_SERVICE_TOKEN_RETRY_MS = void 0;
 const contracts_1 = require("@oxy.so/contracts");
 /**
  * `OxyServer` — the Oxy client for a backend.
@@ -67,6 +67,12 @@ class ServiceCredentialMismatchError extends Error {
 }
 exports.ServiceCredentialMismatchError = ServiceCredentialMismatchError;
 const WORKLOAD_CACHE_KEY = 'workload-identity';
+/** What `serviceToken()` mints, and what Oxy assumes when no audience is sent. */
+exports.DEFAULT_SERVICE_TOKEN_AUDIENCE = 'oxy-api';
+/** Tokens of different audiences never share a cache entry; the default keeps its old key. */
+function audienceCacheKey(audience, key) {
+    return audience === exports.DEFAULT_SERVICE_TOKEN_AUDIENCE ? key : `${audience}\u0000${key}`;
+}
 /** A token is reused until 60s before expiry (clock drift). */
 const TOKEN_REUSE_MARGIN_MS = 60000;
 /** Bound on remembered `appId:userId` delegation answers. */
@@ -202,19 +208,28 @@ class OxyServer extends OxyServices_1.OxyServices {
      * {@link ServiceCredentialMismatchError} rather than return the cached token.
      */
     async serviceToken(apiKey, apiSecret) {
+        return this.serviceTokenFor(exports.DEFAULT_SERVICE_TOKEN_AUDIENCE, apiKey, apiSecret);
+    }
+    /**
+     * A service token for `audience` — e.g. `kaana.ai` for https://kaana.ai/v1.
+     * Minted, cached and refreshed exactly as {@link serviceToken} (which is this
+     * with `oxy-api`), from the same credential or attested workload identity;
+     * each audience has its own cache entry, so one never answers for another.
+     */
+    async serviceTokenFor(audience, apiKey, apiSecret) {
         const key = apiKey || this.serviceApiKey;
         const secret = apiSecret || this.serviceApiSecret;
         if (!key || !secret) {
             // No credential — prove what this process IS instead. The fallback, not the
             // preference: a deployment that still has a credential keeps using it.
             if ((0, workloadIdentity_1.canAttestWorkloadIdentity)()) {
-                return this.workloadServiceToken();
+                return this.workloadServiceToken(audience);
             }
             throw new Error('Service credentials not provided. Pass serviceAuth, call configureServiceAuth(), or pass apiKey and apiSecret.');
         }
         // The apiKey is the credential's PUBLIC id (`oxy_dk_…`, the OAuth
         // client_id), so it keys the in-memory cache as is; the secret never does.
-        const cacheKey = key;
+        const cacheKey = audienceCacheKey(audience, key);
         const now = Date.now();
         const providedSecretBuf = Buffer.from(secret, 'utf8');
         let entry = this.serviceTokens.get(cacheKey);
@@ -247,7 +262,7 @@ class OxyServer extends OxyServices_1.OxyServices {
             entry = { token: '', expiresAt: 0, secretBuf: providedSecretBuf, pending: null, apiKey: key };
             this.serviceTokens.set(cacheKey, entry);
         }
-        const pending = this.mintServiceToken(key, secret, cacheKey, providedSecretBuf);
+        const pending = this.mintServiceToken(key, secret, cacheKey, providedSecretBuf, audience);
         entry.pending = pending;
         try {
             return await pending;
@@ -280,7 +295,11 @@ class OxyServer extends OxyServices_1.OxyServices {
             this.serviceTokens.clear();
             return;
         }
-        this.serviceTokens.delete(targetKey);
+        // Every audience minted from that credential goes with it.
+        for (const [cacheKey, entry] of this.serviceTokens) {
+            if (entry.apiKey === targetKey)
+                this.serviceTokens.delete(cacheKey);
+        }
     }
     /**
      * One request with this service's token. `actAs` sends `X-Oxy-User-Id`: the
@@ -406,8 +425,12 @@ class OxyServer extends OxyServices_1.OxyServices {
     canMintServiceToken() {
         return Boolean(this.serviceApiKey && this.serviceApiSecret) || (0, workloadIdentity_1.canAttestWorkloadIdentity)();
     }
-    async mintServiceToken(key, secret, cacheKey, secretBuf) {
-        const response = await this.request('POST', '/auth/service-token', { apiKey: key, apiSecret: secret }, { cache: false, retry: false, skipAuth: true });
+    async mintServiceToken(key, secret, cacheKey, secretBuf, audience) {
+        const response = await this.request('POST', '/auth/service-token', {
+            apiKey: key,
+            apiSecret: secret,
+            ...(audience === exports.DEFAULT_SERVICE_TOKEN_AUDIENCE ? {} : { audience }),
+        }, { cache: false, retry: false, skipAuth: true });
         const expiresAt = Date.now() + response.expiresIn * 1000;
         const entry = this.serviceTokens.get(cacheKey);
         if (entry) {
@@ -426,9 +449,10 @@ class OxyServer extends OxyServices_1.OxyServices {
         }
         return response.token;
     }
-    /** A token obtained by attestation, cached like a credential's (one identity per process). */
-    async workloadServiceToken() {
-        const entry = this.serviceTokens.get(WORKLOAD_CACHE_KEY);
+    /** A token obtained by attestation, cached like a credential's (one identity per process, one entry per audience). */
+    async workloadServiceToken(audience) {
+        const cacheKey = audienceCacheKey(audience, WORKLOAD_CACHE_KEY);
+        const entry = this.serviceTokens.get(cacheKey);
         if (entry?.token &&
             reusableServiceToken(entry.token) &&
             entry.expiresAt > Date.now() + TOKEN_REUSE_MARGIN_MS)
@@ -442,10 +466,13 @@ class OxyServer extends OxyServices_1.OxyServices {
             pending: null,
             apiKey: WORKLOAD_CACHE_KEY,
         };
-        this.serviceTokens.set(WORKLOAD_CACHE_KEY, seeded);
+        this.serviceTokens.set(cacheKey, seeded);
         const pending = (async () => {
-            const granted = await (0, workloadIdentity_1.requestWorkloadServiceToken)({ baseUrl: this.baseURL });
-            const current = this.serviceTokens.get(WORKLOAD_CACHE_KEY);
+            const granted = await (0, workloadIdentity_1.requestWorkloadServiceToken)({
+                baseUrl: this.baseURL,
+                ...(audience === exports.DEFAULT_SERVICE_TOKEN_AUDIENCE ? {} : { audience }),
+            });
+            const current = this.serviceTokens.get(cacheKey);
             if (current) {
                 current.token = granted.token;
                 current.expiresAt = Date.now() + granted.expiresIn * 1000;
@@ -457,13 +484,13 @@ class OxyServer extends OxyServices_1.OxyServices {
             return await pending;
         }
         catch (error) {
-            const failed = this.serviceTokens.get(WORKLOAD_CACHE_KEY);
+            const failed = this.serviceTokens.get(cacheKey);
             if (failed?.pending === pending && !failed.token)
-                this.serviceTokens.delete(WORKLOAD_CACHE_KEY);
+                this.serviceTokens.delete(cacheKey);
             throw error;
         }
         finally {
-            const settled = this.serviceTokens.get(WORKLOAD_CACHE_KEY);
+            const settled = this.serviceTokens.get(cacheKey);
             if (settled?.pending === pending)
                 settled.pending = null;
         }

package/dist/cjs/server/index.js

@@ -16,14 +16,15 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.inlineScriptCspHash = exports.formatOxyCspPolicy = exports.extractInlineScripts = exports.cspSourcesFor = exports.createOxySecurityHeaders = exports.buildOxyPagesHeaders = exports.buildOxyCspDirectives = exports.createOxyCors = exports.UPSTREAM_HEADERS_TIMEOUT_MS = exports.MAX_URL_LENGTH = exports.MAX_REDIRECTS = exports.DEFAULT_USER_AGENT = exports.BLOCKED_HOSTNAMES = exports.ALLOWED_PROTOCOLS = exports.ALLOWED_PORTS = exports.UpstreamError = exports.SsrfRejection = exports.safeFetch = exports.isBlockedIp = exports.assertSafePublicUrl = exports.createOxyRateLimit = exports.OXY_SERVICE_ENVIRONMENTS = exports.requireOxyAuth = exports.isOxyAuthenticated = exports.getRequiredOxyUserId = exports.getRequiredOxyBillingPrincipal = exports.getOxyUserId = exports.getOxyRequestAttribution = exports.getOxyDelegatedUserId = exports.getOxyBillingPrincipal = exports.getOxyAuthRefusal = exports.getOxyActor = exports.createOxyAuthMiddleware = exports.createOptionalOxyAuth = exports.OXY_ACCOUNT_DELETED_EVENT_URI = exports.OxyAccountEventError = exports.OXY_ALIA_MACHINE_SCOPES = exports.OXY_ALIA_RESOURCE_APPLICATION_ID = exports.isOxyAliaMachinePrincipal = exports.getOxyAliaMachineCredentialBearer = exports.createOxyAliaMachineCredentialAuth = exports.ServerReputationApi = exports.ServerNotificationsApi = exports.ServerLinkedAccountsApi = exports.ServerAssetsApi = exports.ServerAgencyApi = exports.ServerAppsApi = exports.ANONYMOUS_SERVICE_TOKEN_RETRY_MS = exports.ServiceCredentialMismatchError = exports.OxyServer = void 0;
-exports.signInAgentAccount = exports.hasBoundedServiceTokenLifetime = exports.OXY_SERVICE_TOKEN_MAX_LIFETIME_SECONDS = exports.requestWorkloadServiceToken = exports.canAttestWorkloadIdentity = exports.attestWorkloadIdentity = exports.withoutNodeHttpObservation = exports.observeNodeHttp = exports.createEcosystemTraffic = exports.isAllowedDeviceJoinOrigin = exports.isOfficialWebOrigin = exports.isLoopbackOrigin = exports.registrableApex = exports.OXY_IDENTITY_CACHE_PREFIXES = exports.oxyUserByIdCacheKey = exports.evictOxyIdentityCache = exports.publishOxyUserInvalidation = exports.createOxyUserInvalidationHandler = exports.createLiveCapabilityTicketVerifier = exports.verifySecret = exports.verifyOxyRequesterAssertion = exports.signOxyRequesterAssertion = exports.readOxyRequesterAssertionKeyId = exports.oxyRequesterAssertionClaimsSchema = exports.OxyRequesterAssertionError = exports.OXY_REQUESTER_ASSERTION_TYPE = exports.OXY_REQUESTER_ASSERTION_MAX_TTL_SECONDS = exports.OXY_REQUESTER_ASSERTION_HEADER = exports.OXY_REQUESTER_ASSERTION_DEFAULT_ISSUER = exports.createOxyRequesterAssertionAuth = exports.createOxyJwksKeyResolver = exports.verifyCapabilityTicket = exports.readCapabilityAuthorization = exports.issueCapabilityTicket = exports.inputSatisfiesCapabilityLimits = exports.createCapabilityTicketMiddleware = exports.CapabilityTicketError = exports.OXY_CSP_BASELINE = void 0;
+exports.formatOxyCspPolicy = exports.extractInlineScripts = exports.cspSourcesFor = exports.createOxySecurityHeaders = exports.buildOxyPagesHeaders = exports.buildOxyCspDirectives = exports.createOxyCors = exports.UPSTREAM_HEADERS_TIMEOUT_MS = exports.MAX_URL_LENGTH = exports.MAX_REDIRECTS = exports.DEFAULT_USER_AGENT = exports.BLOCKED_HOSTNAMES = exports.ALLOWED_PROTOCOLS = exports.ALLOWED_PORTS = exports.UpstreamError = exports.SsrfRejection = exports.safeFetch = exports.isBlockedIp = exports.assertSafePublicUrl = exports.createOxyRateLimit = exports.OXY_SERVICE_ENVIRONMENTS = exports.requireOxyAuth = exports.isOxyAuthenticated = exports.getRequiredOxyUserId = exports.getRequiredOxyBillingPrincipal = exports.getOxyUserId = exports.getOxyRequestAttribution = exports.getOxyDelegatedUserId = exports.getOxyBillingPrincipal = exports.getOxyAuthRefusal = exports.getOxyActor = exports.createOxyAuthMiddleware = exports.createOptionalOxyAuth = exports.OXY_ACCOUNT_DELETED_EVENT_URI = exports.OxyAccountEventError = exports.OXY_ALIA_MACHINE_SCOPES = exports.OXY_ALIA_RESOURCE_APPLICATION_ID = exports.isOxyAliaMachinePrincipal = exports.getOxyAliaMachineCredentialBearer = exports.createOxyAliaMachineCredentialAuth = exports.ServerReputationApi = exports.ServerNotificationsApi = exports.ServerLinkedAccountsApi = exports.ServerAssetsApi = exports.ServerAgencyApi = exports.ServerAppsApi = exports.DEFAULT_SERVICE_TOKEN_AUDIENCE = exports.ANONYMOUS_SERVICE_TOKEN_RETRY_MS = exports.ServiceCredentialMismatchError = exports.OxyServer = void 0;
+exports.signInAgentAccount = exports.hasBoundedServiceTokenLifetime = exports.OXY_SERVICE_TOKEN_MAX_LIFETIME_SECONDS = exports.requestWorkloadServiceToken = exports.canAttestWorkloadIdentity = exports.attestWorkloadIdentity = exports.withoutNodeHttpObservation = exports.observeNodeHttp = exports.createEcosystemTraffic = exports.isAllowedDeviceJoinOrigin = exports.isOfficialWebOrigin = exports.isLoopbackOrigin = exports.registrableApex = exports.OXY_IDENTITY_CACHE_PREFIXES = exports.oxyUserByIdCacheKey = exports.evictOxyIdentityCache = exports.publishOxyUserInvalidation = exports.createOxyUserInvalidationHandler = exports.createLiveCapabilityTicketVerifier = exports.verifySecret = exports.verifyOxyRequesterAssertion = exports.signOxyRequesterAssertion = exports.readOxyRequesterAssertionKeyId = exports.oxyRequesterAssertionClaimsSchema = exports.OxyRequesterAssertionError = exports.OXY_REQUESTER_ASSERTION_TYPE = exports.OXY_REQUESTER_ASSERTION_MAX_TTL_SECONDS = exports.OXY_REQUESTER_ASSERTION_HEADER = exports.OXY_REQUESTER_ASSERTION_DEFAULT_ISSUER = exports.createOxyRequesterAssertionAuth = exports.createOxyJwksKeyResolver = exports.verifyCapabilityTicket = exports.readCapabilityAuthorization = exports.issueCapabilityTicket = exports.inputSatisfiesCapabilityLimits = exports.createCapabilityTicketMiddleware = exports.CapabilityTicketError = exports.OXY_CSP_BASELINE = exports.inlineScriptCspHash = void 0;
 // The backend client: OxyServices plus the service-token lane, middleware,
 // account events and the service-only namespace methods.
 var OxyServer_1 = require("./OxyServer");
 Object.defineProperty(exports, "OxyServer", { enumerable: true, get: function () { return OxyServer_1.OxyServer; } });
 Object.defineProperty(exports, "ServiceCredentialMismatchError", { enumerable: true, get: function () { return OxyServer_1.ServiceCredentialMismatchError; } });
 Object.defineProperty(exports, "ANONYMOUS_SERVICE_TOKEN_RETRY_MS", { enumerable: true, get: function () { return OxyServer_1.ANONYMOUS_SERVICE_TOKEN_RETRY_MS; } });
+Object.defineProperty(exports, "DEFAULT_SERVICE_TOKEN_AUDIENCE", { enumerable: true, get: function () { return OxyServer_1.DEFAULT_SERVICE_TOKEN_AUDIENCE; } });
 var namespaces_1 = require("./namespaces");
 Object.defineProperty(exports, "ServerAppsApi", { enumerable: true, get: function () { return namespaces_1.ServerAppsApi; } });
 Object.defineProperty(exports, "ServerAgencyApi", { enumerable: true, get: function () { return namespaces_1.ServerAgencyApi; } });

package/dist/cjs/server/workloadIdentity.js

@@ -176,7 +176,12 @@ async function requestWorkloadServiceToken(options) {
     const tokenResponse = await fetchImpl(`${base}/auth/service-token/workload`, {
         method: 'POST',
         headers: { 'content-type': 'application/json' },
-        body: JSON.stringify({ provider: 'aws-iam', nonce: challenge.nonce, attestation }),
+        body: JSON.stringify({
+            provider: 'aws-iam',
+            nonce: challenge.nonce,
+            attestation,
+            ...(options.audience === undefined ? {} : { audience: options.audience }),
+        }),
     });
     if (!tokenResponse.ok) {
         // The body carries a bounded `reason`; the token never travels on a failure,

package/dist/cjs/utils/corsPreflight.js

@@ -0,0 +1,48 @@
+"use strict";
+/**
+ * Whether a browser has to send a CORS preflight (`OPTIONS`) before this
+ * cross-origin request goes out, per the Fetch standard's CORS-safelisted
+ * methods and request headers.
+ *
+ * The SDK uses it for one invariant: its anonymous telemetry headers
+ * (`X-Oxy-Activity-Id`, `X-Oxy-Edge-Region`) ride only on requests that are
+ * preflighted anyway, so they never turn a request that would go straight out
+ * into one that first waits a round trip for an `OPTIONS`. A browser caches a
+ * preflight per URL, so without this every distinct anonymous read (a post's
+ * replies, a profile, a public app record) paid a round trip of its own.
+ *
+ * Deliberately conservative: a header it does not recognise as safelisted
+ * counts as needing a preflight, which only means the telemetry headers ride
+ * along exactly as they always did. Value-level rules (for example `Accept`'s
+ * 128-byte limit) are not modelled; a misjudgement in that direction drops two
+ * advisory headers from one request and nothing else.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requiresCorsPreflight = requiresCorsPreflight;
+const SAFELISTED_METHODS = new Set(['GET', 'HEAD', 'POST']);
+const SAFELISTED_HEADERS = new Set([
+    'accept',
+    'accept-language',
+    'content-language',
+    'content-type',
+]);
+const SAFELISTED_CONTENT_TYPES = new Set([
+    'application/x-www-form-urlencoded',
+    'multipart/form-data',
+    'text/plain',
+]);
+function requiresCorsPreflight(method, headers) {
+    if (!SAFELISTED_METHODS.has(method.toUpperCase()))
+        return true;
+    for (const [rawName, value] of headers) {
+        const name = rawName.toLowerCase();
+        if (!SAFELISTED_HEADERS.has(name))
+            return true;
+        if (name === 'content-type') {
+            const essence = value.split(';')[0]?.trim().toLowerCase() ?? '';
+            if (!SAFELISTED_CONTENT_TYPES.has(essence))
+                return true;
+        }
+    }
+    return false;
+}

package/dist/esm/HttpService.js

@@ -23,6 +23,7 @@ import { redactUrlQuery } from './utils/redactUrl.js';
 import { OxyAuthenticationError } from './OxyServices.errors.js';
 import { peekBrowserEdgeRegionHeader } from './utils/edgeRegion.js';
 import { getBrowserActivityIdHeader } from './utils/activityId.js';
+import { requiresCorsPreflight } from './utils/corsPreflight.js';
 import { trimLeadingSlashes, trimTrailingSlashes } from './utils/slashes.js';
 /** Comparison only fences local async work; it never validates token authority. */
 function sameTokenSession(left, right) {
@@ -505,12 +506,17 @@ export class HttpService {
                 const headers = {
                     Accept: 'application/json',
                 };
-                // Only set Content-Type for non-FormData requests (FormData sets it automatically with boundary)
-                if (isUrlEncoded) {
-                    headers['Content-Type'] = 'application/x-www-form-urlencoded;charset=UTF-8';
-                }
-                else if (!isFormData) {
-                    headers['Content-Type'] = 'application/json';
+                // Content-Type describes a body, so a GET (which never sends one) gets
+                // none: `application/json` is not a CORS-safelisted type, and on a GET it
+                // only made the browser preflight a request with nothing to describe.
+                // FormData sets its own multipart type with the boundary.
+                if (method !== 'GET') {
+                    if (isUrlEncoded) {
+                        headers['Content-Type'] = 'application/x-www-form-urlencoded;charset=UTF-8';
+                    }
+                    else if (!isFormData) {
+                        headers['Content-Type'] = 'application/json';
+                    }
                 }
                 // Add authorization header if available
                 if (authHeader) {
@@ -530,9 +536,14 @@ export class HttpService {
                 }
                 // This is Cloudflare's coarse serving PoP (for example `mad`), never an
                 // IP or coordinate. Set it after caller headers so request code cannot
-                // accidentally or deliberately substitute a different origin.
-                Object.assign(headers, edgeRegionHeader);
-                Object.assign(headers, activityIdHeader);
+                // accidentally or deliberately substitute a different origin. Both are
+                // advisory telemetry, so they ride only on a request the browser
+                // preflights anyway: on an anonymous GET they were the only thing that
+                // made it non-simple, and every distinct URL paid an OPTIONS round trip.
+                if (requiresCorsPreflight(method, Object.entries(headers))) {
+                    Object.assign(headers, edgeRegionHeader);
+                    Object.assign(headers, activityIdHeader);
+                }
                 // `URLSearchParams` is serialised explicitly rather than handed to
                 // `fetch` as-is: RN's fetch does not consistently encode it, and doing
                 // it here keeps the body identical across every platform.
@@ -1304,12 +1315,20 @@ export class HttpService {
             headers.delete(name);
         if (authHeader)
             headers.set('Authorization', authHeader);
-        const edgeRegionHeader = peekBrowserEdgeRegionHeader();
-        for (const [name, value] of Object.entries(edgeRegionHeader))
-            headers.set(name, value);
-        const activityIdHeader = getBrowserActivityIdHeader();
-        for (const [name, value] of Object.entries(activityIdHeader))
-            headers.set(name, value);
+        // Telemetry rides only on a request the browser preflights anyway — see
+        // `request()`.
+        const sentHeaders = [];
+        headers.forEach((value, name) => {
+            sentHeaders.push([name, value]);
+        });
+        if (requiresCorsPreflight(config.method, sentHeaders)) {
+            const edgeRegionHeader = peekBrowserEdgeRegionHeader();
+            for (const [name, value] of Object.entries(edgeRegionHeader))
+                headers.set(name, value);
+            const activityIdHeader = getBrowserActivityIdHeader();
+            for (const [name, value] of Object.entries(activityIdHeader))
+                headers.set(name, value);
+        }
         try {
             const body = config.method === 'GET' ? undefined : config.body;
             const init = {

package/dist/esm/server/OxyServer.js

@@ -63,6 +63,12 @@ export class ServiceCredentialMismatchError extends Error {
     }
 }
 const WORKLOAD_CACHE_KEY = 'workload-identity';
+/** What `serviceToken()` mints, and what Oxy assumes when no audience is sent. */
+export const DEFAULT_SERVICE_TOKEN_AUDIENCE = 'oxy-api';
+/** Tokens of different audiences never share a cache entry; the default keeps its old key. */
+function audienceCacheKey(audience, key) {
+    return audience === DEFAULT_SERVICE_TOKEN_AUDIENCE ? key : `${audience}\u0000${key}`;
+}
 /** A token is reused until 60s before expiry (clock drift). */
 const TOKEN_REUSE_MARGIN_MS = 60000;
 /** Bound on remembered `appId:userId` delegation answers. */
@@ -198,19 +204,28 @@ export class OxyServer extends OxyServices {
      * {@link ServiceCredentialMismatchError} rather than return the cached token.
      */
     async serviceToken(apiKey, apiSecret) {
+        return this.serviceTokenFor(DEFAULT_SERVICE_TOKEN_AUDIENCE, apiKey, apiSecret);
+    }
+    /**
+     * A service token for `audience` — e.g. `kaana.ai` for https://kaana.ai/v1.
+     * Minted, cached and refreshed exactly as {@link serviceToken} (which is this
+     * with `oxy-api`), from the same credential or attested workload identity;
+     * each audience has its own cache entry, so one never answers for another.
+     */
+    async serviceTokenFor(audience, apiKey, apiSecret) {
         const key = apiKey || this.serviceApiKey;
         const secret = apiSecret || this.serviceApiSecret;
         if (!key || !secret) {
             // No credential — prove what this process IS instead. The fallback, not the
             // preference: a deployment that still has a credential keeps using it.
             if (canAttestWorkloadIdentity()) {
-                return this.workloadServiceToken();
+                return this.workloadServiceToken(audience);
             }
             throw new Error('Service credentials not provided. Pass serviceAuth, call configureServiceAuth(), or pass apiKey and apiSecret.');
         }
         // The apiKey is the credential's PUBLIC id (`oxy_dk_…`, the OAuth
         // client_id), so it keys the in-memory cache as is; the secret never does.
-        const cacheKey = key;
+        const cacheKey = audienceCacheKey(audience, key);
         const now = Date.now();
         const providedSecretBuf = Buffer.from(secret, 'utf8');
         let entry = this.serviceTokens.get(cacheKey);
@@ -243,7 +258,7 @@ export class OxyServer extends OxyServices {
             entry = { token: '', expiresAt: 0, secretBuf: providedSecretBuf, pending: null, apiKey: key };
             this.serviceTokens.set(cacheKey, entry);
         }
-        const pending = this.mintServiceToken(key, secret, cacheKey, providedSecretBuf);
+        const pending = this.mintServiceToken(key, secret, cacheKey, providedSecretBuf, audience);
         entry.pending = pending;
         try {
             return await pending;
@@ -276,7 +291,11 @@ export class OxyServer extends OxyServices {
             this.serviceTokens.clear();
             return;
         }
-        this.serviceTokens.delete(targetKey);
+        // Every audience minted from that credential goes with it.
+        for (const [cacheKey, entry] of this.serviceTokens) {
+            if (entry.apiKey === targetKey)
+                this.serviceTokens.delete(cacheKey);
+        }
     }
     /**
      * One request with this service's token. `actAs` sends `X-Oxy-User-Id`: the
@@ -402,8 +421,12 @@ export class OxyServer extends OxyServices {
     canMintServiceToken() {
         return Boolean(this.serviceApiKey && this.serviceApiSecret) || canAttestWorkloadIdentity();
     }
-    async mintServiceToken(key, secret, cacheKey, secretBuf) {
-        const response = await this.request('POST', '/auth/service-token', { apiKey: key, apiSecret: secret }, { cache: false, retry: false, skipAuth: true });
+    async mintServiceToken(key, secret, cacheKey, secretBuf, audience) {
+        const response = await this.request('POST', '/auth/service-token', {
+            apiKey: key,
+            apiSecret: secret,
+            ...(audience === DEFAULT_SERVICE_TOKEN_AUDIENCE ? {} : { audience }),
+        }, { cache: false, retry: false, skipAuth: true });
         const expiresAt = Date.now() + response.expiresIn * 1000;
         const entry = this.serviceTokens.get(cacheKey);
         if (entry) {
@@ -422,9 +445,10 @@ export class OxyServer extends OxyServices {
         }
         return response.token;
     }
-    /** A token obtained by attestation, cached like a credential's (one identity per process). */
-    async workloadServiceToken() {
-        const entry = this.serviceTokens.get(WORKLOAD_CACHE_KEY);
+    /** A token obtained by attestation, cached like a credential's (one identity per process, one entry per audience). */
+    async workloadServiceToken(audience) {
+        const cacheKey = audienceCacheKey(audience, WORKLOAD_CACHE_KEY);
+        const entry = this.serviceTokens.get(cacheKey);
         if (entry?.token &&
             reusableServiceToken(entry.token) &&
             entry.expiresAt > Date.now() + TOKEN_REUSE_MARGIN_MS)
@@ -438,10 +462,13 @@ export class OxyServer extends OxyServices {
             pending: null,
             apiKey: WORKLOAD_CACHE_KEY,
         };
-        this.serviceTokens.set(WORKLOAD_CACHE_KEY, seeded);
+        this.serviceTokens.set(cacheKey, seeded);
         const pending = (async () => {
-            const granted = await requestWorkloadServiceToken({ baseUrl: this.baseURL });
-            const current = this.serviceTokens.get(WORKLOAD_CACHE_KEY);
+            const granted = await requestWorkloadServiceToken({
+                baseUrl: this.baseURL,
+                ...(audience === DEFAULT_SERVICE_TOKEN_AUDIENCE ? {} : { audience }),
+            });
+            const current = this.serviceTokens.get(cacheKey);
             if (current) {
                 current.token = granted.token;
                 current.expiresAt = Date.now() + granted.expiresIn * 1000;
@@ -453,13 +480,13 @@ export class OxyServer extends OxyServices {
             return await pending;
         }
         catch (error) {
-            const failed = this.serviceTokens.get(WORKLOAD_CACHE_KEY);
+            const failed = this.serviceTokens.get(cacheKey);
             if (failed?.pending === pending && !failed.token)
-                this.serviceTokens.delete(WORKLOAD_CACHE_KEY);
+                this.serviceTokens.delete(cacheKey);
             throw error;
         }
         finally {
-            const settled = this.serviceTokens.get(WORKLOAD_CACHE_KEY);
+            const settled = this.serviceTokens.get(cacheKey);
             if (settled?.pending === pending)
                 settled.pending = null;
         }

package/dist/esm/server/index.js

@@ -16,7 +16,7 @@
  */
 // The backend client: OxyServices plus the service-token lane, middleware,
 // account events and the service-only namespace methods.
-export { OxyServer, ServiceCredentialMismatchError, ANONYMOUS_SERVICE_TOKEN_RETRY_MS, } from './OxyServer.js';
+export { OxyServer, ServiceCredentialMismatchError, ANONYMOUS_SERVICE_TOKEN_RETRY_MS, DEFAULT_SERVICE_TOKEN_AUDIENCE, } from './OxyServer.js';
 export { ServerAppsApi, ServerAgencyApi, ServerAssetsApi, ServerLinkedAccountsApi, ServerNotificationsApi, ServerReputationApi, } from './namespaces.js';
 export { createOxyAliaMachineCredentialAuth, getOxyAliaMachineCredentialBearer, isOxyAliaMachinePrincipal, OXY_ALIA_RESOURCE_APPLICATION_ID, OXY_ALIA_MACHINE_SCOPES, } from './aliaMachineCredential.js';
 export { OxyAccountEventError, OXY_ACCOUNT_DELETED_EVENT_URI } from './middleware.js';

package/dist/esm/server/workloadIdentity.js

@@ -171,7 +171,12 @@ export async function requestWorkloadServiceToken(options) {
     const tokenResponse = await fetchImpl(`${base}/auth/service-token/workload`, {
         method: 'POST',
         headers: { 'content-type': 'application/json' },
-        body: JSON.stringify({ provider: 'aws-iam', nonce: challenge.nonce, attestation }),
+        body: JSON.stringify({
+            provider: 'aws-iam',
+            nonce: challenge.nonce,
+            attestation,
+            ...(options.audience === undefined ? {} : { audience: options.audience }),
+        }),
     });
     if (!tokenResponse.ok) {
         // The body carries a bounded `reason`; the token never travels on a failure,

package/dist/esm/utils/corsPreflight.js

@@ -0,0 +1,45 @@
+/**
+ * Whether a browser has to send a CORS preflight (`OPTIONS`) before this
+ * cross-origin request goes out, per the Fetch standard's CORS-safelisted
+ * methods and request headers.
+ *
+ * The SDK uses it for one invariant: its anonymous telemetry headers
+ * (`X-Oxy-Activity-Id`, `X-Oxy-Edge-Region`) ride only on requests that are
+ * preflighted anyway, so they never turn a request that would go straight out
+ * into one that first waits a round trip for an `OPTIONS`. A browser caches a
+ * preflight per URL, so without this every distinct anonymous read (a post's
+ * replies, a profile, a public app record) paid a round trip of its own.
+ *
+ * Deliberately conservative: a header it does not recognise as safelisted
+ * counts as needing a preflight, which only means the telemetry headers ride
+ * along exactly as they always did. Value-level rules (for example `Accept`'s
+ * 128-byte limit) are not modelled; a misjudgement in that direction drops two
+ * advisory headers from one request and nothing else.
+ */
+const SAFELISTED_METHODS = new Set(['GET', 'HEAD', 'POST']);
+const SAFELISTED_HEADERS = new Set([
+    'accept',
+    'accept-language',
+    'content-language',
+    'content-type',
+]);
+const SAFELISTED_CONTENT_TYPES = new Set([
+    'application/x-www-form-urlencoded',
+    'multipart/form-data',
+    'text/plain',
+]);
+export function requiresCorsPreflight(method, headers) {
+    if (!SAFELISTED_METHODS.has(method.toUpperCase()))
+        return true;
+    for (const [rawName, value] of headers) {
+        const name = rawName.toLowerCase();
+        if (!SAFELISTED_HEADERS.has(name))
+            return true;
+        if (name === 'content-type') {
+            const essence = value.split(';')[0]?.trim().toLowerCase() ?? '';
+            if (!SAFELISTED_CONTENT_TYPES.has(essence))
+                return true;
+        }
+    }
+    return false;
+}

package/dist/types/api/safety.d.ts

@@ -8,7 +8,7 @@ export declare class SafetyApi {
         accessToken: string | null;
     }): Promise<{
         allowed: boolean;
-        reason: "public" | "owner" | "private" | "blocked" | "unavailable";
+        reason: "unavailable" | "owner" | "public" | "private" | "blocked";
         policyVersion: "1";
     }>;
 }

package/dist/types/server/OxyServer.d.ts

@@ -58,6 +58,15 @@ export interface ServiceTokenResponse {
 export declare class ServiceCredentialMismatchError extends Error {
     constructor();
 }
+/**
+ * The resource server a service token is minted for (Oxy's closed set,
+ * `packages/api/src/config/serviceTokenAudiences.ts`). A token is only ever
+ * accepted by its own audience: Oxy's API refuses a `kaana.ai` token and
+ * https://kaana.ai/v1 refuses an `oxy-api` one (Kaana ADR 0002 decision 6).
+ */
+export type ServiceTokenAudience = 'oxy-api' | 'kaana.ai' | 'oxy-api:kaana-control';
+/** What `serviceToken()` mints, and what Oxy assumes when no audience is sent. */
+export declare const DEFAULT_SERVICE_TOKEN_AUDIENCE: ServiceTokenAudience;
 export declare class OxyServer extends OxyServices {
     private readonly serviceTokens;
     private serviceApiKey;
@@ -120,6 +129,13 @@ export declare class OxyServer extends OxyServices {
      * {@link ServiceCredentialMismatchError} rather than return the cached token.
      */
     serviceToken(apiKey?: string, apiSecret?: string): Promise<string>;
+    /**
+     * A service token for `audience` — e.g. `kaana.ai` for https://kaana.ai/v1.
+     * Minted, cached and refreshed exactly as {@link serviceToken} (which is this
+     * with `oxy-api`), from the same credential or attested workload identity;
+     * each audience has its own cache entry, so one never answers for another.
+     */
+    serviceTokenFor(audience: ServiceTokenAudience, apiKey?: string, apiSecret?: string): Promise<string>;
     /**
      * Forget cached service token(s) so the next `serviceToken()` mints anew —
      * the way back from a 401 after a credential was revoked or rotated.
@@ -187,7 +203,7 @@ export declare class OxyServer extends OxyServices {
     private serviceTokenForAnonymousRequest;
     private canMintServiceToken;
     private mintServiceToken;
-    /** A token obtained by attestation, cached like a credential's (one identity per process). */
+    /** A token obtained by attestation, cached like a credential's (one identity per process, one entry per audience). */
     private workloadServiceToken;
     private lookupActingAs;
     private clearActingAsPair;

package/dist/types/server/index.d.ts

@@ -14,8 +14,8 @@
  * app.use('/api', createOxyAuthMiddleware(oxy));
  * ```
  */
-export { OxyServer, ServiceCredentialMismatchError, ANONYMOUS_SERVICE_TOKEN_RETRY_MS, } from './OxyServer';
-export type { OxyServerConfig, ServiceTokenResponse } from './OxyServer';
+export { OxyServer, ServiceCredentialMismatchError, ANONYMOUS_SERVICE_TOKEN_RETRY_MS, DEFAULT_SERVICE_TOKEN_AUDIENCE, } from './OxyServer';
+export type { OxyServerConfig, ServiceTokenAudience, ServiceTokenResponse } from './OxyServer';
 export { ServerAppsApi, ServerAgencyApi, ServerAssetsApi, ServerLinkedAccountsApi, ServerNotificationsApi, ServerReputationApi, } from './namespaces';
 export { createOxyAliaMachineCredentialAuth, getOxyAliaMachineCredentialBearer, isOxyAliaMachinePrincipal, OXY_ALIA_RESOURCE_APPLICATION_ID, OXY_ALIA_MACHINE_SCOPES, } from './aliaMachineCredential';
 export type { AliaMachineCredentialIntrospection, OxyAliaMachinePrincipal, OxyAliaMachineRequest, OxyAliaMachineCredentialHost, } from './aliaMachineCredential';

package/dist/types/server/requesterAssertion.d.ts

@@ -36,8 +36,8 @@ export declare const oxyRequesterAssertionClaimsSchema: z.ZodObject<{
     /** The one native agent this requester may reach with it. */
     agentId: z.ZodString;
 }, "strict", z.ZodTypeAny, {
-    sub: string;
     exp: number;
+    sub: string;
     aud: string;
     iss: string;
     jti: string;
@@ -46,8 +46,8 @@ export declare const oxyRequesterAssertionClaimsSchema: z.ZodObject<{
     cid: string;
     agentId: string;
 }, {
-    sub: string;
     exp: number;
+    sub: string;
     aud: string;
     iss: string;
     jti: string;

package/dist/types/server/workloadIdentity.d.ts

@@ -1,6 +1,11 @@
 export interface WorkloadServiceTokenOptions {
     /** Oxy's base URL, e.g. `https://api.oxy.so`. */
     baseUrl: string;
+    /**
+     * The resource server the token is for (e.g. `kaana.ai`). Omitted, Oxy mints
+     * for `oxy-api`, as it always has.
+     */
+    audience?: string;
     /** Injected in tests; defaults to the global. */
     fetch?: typeof fetch;
 }

package/dist/types/utils/corsPreflight.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Whether a browser has to send a CORS preflight (`OPTIONS`) before this
+ * cross-origin request goes out, per the Fetch standard's CORS-safelisted
+ * methods and request headers.
+ *
+ * The SDK uses it for one invariant: its anonymous telemetry headers
+ * (`X-Oxy-Activity-Id`, `X-Oxy-Edge-Region`) ride only on requests that are
+ * preflighted anyway, so they never turn a request that would go straight out
+ * into one that first waits a round trip for an `OPTIONS`. A browser caches a
+ * preflight per URL, so without this every distinct anonymous read (a post's
+ * replies, a profile, a public app record) paid a round trip of its own.
+ *
+ * Deliberately conservative: a header it does not recognise as safelisted
+ * counts as needing a preflight, which only means the telemetry headers ride
+ * along exactly as they always did. Value-level rules (for example `Accept`'s
+ * 128-byte limit) are not modelled; a misjudgement in that direction drops two
+ * advisory headers from one request and nothing else.
+ */
+export declare function requiresCorsPreflight(method: string, headers: Iterable<readonly [string, string]>): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/core",
-  "version": "4.8.0",
+  "version": "4.9.1",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/HttpService.ts

@@ -32,6 +32,7 @@ import type { DeviceSecretMintOutcome } from './session/refresh';
 import { OxyAuthenticationError } from './OxyServices.errors';
 import { peekBrowserEdgeRegionHeader } from './utils/edgeRegion';
 import { getBrowserActivityIdHeader } from './utils/activityId';
+import { requiresCorsPreflight } from './utils/corsPreflight';
 import { trimLeadingSlashes, trimTrailingSlashes } from './utils/slashes';
 
 export type AuthRefreshReason = 'preflight' | 'response-401';
@@ -712,11 +713,16 @@ export class HttpService {
           Accept: 'application/json',
         };
 
-        // Only set Content-Type for non-FormData requests (FormData sets it automatically with boundary)
-        if (isUrlEncoded) {
-          headers['Content-Type'] = 'application/x-www-form-urlencoded;charset=UTF-8';
-        } else if (!isFormData) {
-          headers['Content-Type'] = 'application/json';
+        // Content-Type describes a body, so a GET (which never sends one) gets
+        // none: `application/json` is not a CORS-safelisted type, and on a GET it
+        // only made the browser preflight a request with nothing to describe.
+        // FormData sets its own multipart type with the boundary.
+        if (method !== 'GET') {
+          if (isUrlEncoded) {
+            headers['Content-Type'] = 'application/x-www-form-urlencoded;charset=UTF-8';
+          } else if (!isFormData) {
+            headers['Content-Type'] = 'application/json';
+          }
         }
 
         // Add authorization header if available
@@ -741,9 +747,14 @@ export class HttpService {
 
         // This is Cloudflare's coarse serving PoP (for example `mad`), never an
         // IP or coordinate. Set it after caller headers so request code cannot
-        // accidentally or deliberately substitute a different origin.
-        Object.assign(headers, edgeRegionHeader);
-        Object.assign(headers, activityIdHeader);
+        // accidentally or deliberately substitute a different origin. Both are
+        // advisory telemetry, so they ride only on a request the browser
+        // preflights anyway: on an anonymous GET they were the only thing that
+        // made it non-simple, and every distinct URL paid an OPTIONS round trip.
+        if (requiresCorsPreflight(method, Object.entries(headers))) {
+          Object.assign(headers, edgeRegionHeader);
+          Object.assign(headers, activityIdHeader);
+        }
 
         // `URLSearchParams` is serialised explicitly rather than handed to
         // `fetch` as-is: RN's fetch does not consistently encode it, and doing
@@ -1637,10 +1648,18 @@ export class HttpService {
     for (const name of ['Authorization', 'Cookie', 'Cookie2', 'Host', 'Proxy-Authorization'])
       headers.delete(name);
     if (authHeader) headers.set('Authorization', authHeader);
-    const edgeRegionHeader = peekBrowserEdgeRegionHeader();
-    for (const [name, value] of Object.entries(edgeRegionHeader)) headers.set(name, value);
-    const activityIdHeader = getBrowserActivityIdHeader();
-    for (const [name, value] of Object.entries(activityIdHeader)) headers.set(name, value);
+    // Telemetry rides only on a request the browser preflights anyway — see
+    // `request()`.
+    const sentHeaders: Array<[string, string]> = [];
+    headers.forEach((value, name) => {
+      sentHeaders.push([name, value]);
+    });
+    if (requiresCorsPreflight(config.method, sentHeaders)) {
+      const edgeRegionHeader = peekBrowserEdgeRegionHeader();
+      for (const [name, value] of Object.entries(edgeRegionHeader)) headers.set(name, value);
+      const activityIdHeader = getBrowserActivityIdHeader();
+      for (const [name, value] of Object.entries(activityIdHeader)) headers.set(name, value);
+    }
 
     try {
       const body = config.method === 'GET' ? undefined : config.body;

package/src/server/OxyServer.ts

@@ -162,6 +162,22 @@ interface ServiceTokenCacheEntry {
 }
 
 const WORKLOAD_CACHE_KEY = 'workload-identity';
+
+/**
+ * The resource server a service token is minted for (Oxy's closed set,
+ * `packages/api/src/config/serviceTokenAudiences.ts`). A token is only ever
+ * accepted by its own audience: Oxy's API refuses a `kaana.ai` token and
+ * https://kaana.ai/v1 refuses an `oxy-api` one (Kaana ADR 0002 decision 6).
+ */
+export type ServiceTokenAudience = 'oxy-api' | 'kaana.ai' | 'oxy-api:kaana-control';
+
+/** What `serviceToken()` mints, and what Oxy assumes when no audience is sent. */
+export const DEFAULT_SERVICE_TOKEN_AUDIENCE: ServiceTokenAudience = 'oxy-api';
+
+/** Tokens of different audiences never share a cache entry; the default keeps its old key. */
+function audienceCacheKey(audience: ServiceTokenAudience, key: string): string {
+  return audience === DEFAULT_SERVICE_TOKEN_AUDIENCE ? key : `${audience}\u0000${key}`;
+}
 /** A token is reused until 60s before expiry (clock drift). */
 const TOKEN_REUSE_MARGIN_MS = 60_000;
 
@@ -298,6 +314,20 @@ export class OxyServer extends OxyServices {
    * {@link ServiceCredentialMismatchError} rather than return the cached token.
    */
   async serviceToken(apiKey?: string, apiSecret?: string): Promise<string> {
+    return this.serviceTokenFor(DEFAULT_SERVICE_TOKEN_AUDIENCE, apiKey, apiSecret);
+  }
+
+  /**
+   * A service token for `audience` — e.g. `kaana.ai` for https://kaana.ai/v1.
+   * Minted, cached and refreshed exactly as {@link serviceToken} (which is this
+   * with `oxy-api`), from the same credential or attested workload identity;
+   * each audience has its own cache entry, so one never answers for another.
+   */
+  async serviceTokenFor(
+    audience: ServiceTokenAudience,
+    apiKey?: string,
+    apiSecret?: string,
+  ): Promise<string> {
     const key = apiKey || this.serviceApiKey;
     const secret = apiSecret || this.serviceApiSecret;
 
@@ -305,7 +335,7 @@ export class OxyServer extends OxyServices {
       // No credential — prove what this process IS instead. The fallback, not the
       // preference: a deployment that still has a credential keeps using it.
       if (canAttestWorkloadIdentity()) {
-        return this.workloadServiceToken();
+        return this.workloadServiceToken(audience);
       }
       throw new Error(
         'Service credentials not provided. Pass serviceAuth, call configureServiceAuth(), or pass apiKey and apiSecret.',
@@ -314,7 +344,7 @@ export class OxyServer extends OxyServices {
 
     // The apiKey is the credential's PUBLIC id (`oxy_dk_…`, the OAuth
     // client_id), so it keys the in-memory cache as is; the secret never does.
-    const cacheKey = key;
+    const cacheKey = audienceCacheKey(audience, key);
     const now = Date.now();
     const providedSecretBuf = Buffer.from(secret, 'utf8');
 
@@ -351,7 +381,7 @@ export class OxyServer extends OxyServices {
       this.serviceTokens.set(cacheKey, entry);
     }
 
-    const pending = this.mintServiceToken(key, secret, cacheKey, providedSecretBuf);
+    const pending = this.mintServiceToken(key, secret, cacheKey, providedSecretBuf, audience);
     entry.pending = pending;
     try {
       return await pending;
@@ -382,7 +412,10 @@ export class OxyServer extends OxyServices {
       this.serviceTokens.clear();
       return;
     }
-    this.serviceTokens.delete(targetKey);
+    // Every audience minted from that credential goes with it.
+    for (const [cacheKey, entry] of this.serviceTokens) {
+      if (entry.apiKey === targetKey) this.serviceTokens.delete(cacheKey);
+    }
   }
 
   /**
@@ -580,11 +613,16 @@ export class OxyServer extends OxyServices {
     secret: string,
     cacheKey: string,
     secretBuf: Buffer,
+    audience: ServiceTokenAudience,
   ): Promise<string> {
     const response = await this.request<ServiceTokenResponse>(
       'POST',
       '/auth/service-token',
-      { apiKey: key, apiSecret: secret },
+      {
+        apiKey: key,
+        apiSecret: secret,
+        ...(audience === DEFAULT_SERVICE_TOKEN_AUDIENCE ? {} : { audience }),
+      },
       { cache: false, retry: false, skipAuth: true },
     );
     const expiresAt = Date.now() + response.expiresIn * 1000;
@@ -605,9 +643,10 @@ export class OxyServer extends OxyServices {
     return response.token;
   }
 
-  /** A token obtained by attestation, cached like a credential's (one identity per process). */
-  private async workloadServiceToken(): Promise<string> {
-    const entry = this.serviceTokens.get(WORKLOAD_CACHE_KEY);
+  /** A token obtained by attestation, cached like a credential's (one identity per process, one entry per audience). */
+  private async workloadServiceToken(audience: ServiceTokenAudience): Promise<string> {
+    const cacheKey = audienceCacheKey(audience, WORKLOAD_CACHE_KEY);
+    const entry = this.serviceTokens.get(cacheKey);
     if (
       entry?.token &&
       reusableServiceToken(entry.token) &&
@@ -623,11 +662,14 @@ export class OxyServer extends OxyServices {
       pending: null,
       apiKey: WORKLOAD_CACHE_KEY,
     };
-    this.serviceTokens.set(WORKLOAD_CACHE_KEY, seeded);
+    this.serviceTokens.set(cacheKey, seeded);
 
     const pending = (async () => {
-      const granted = await requestWorkloadServiceToken({ baseUrl: this.baseURL });
-      const current = this.serviceTokens.get(WORKLOAD_CACHE_KEY);
+      const granted = await requestWorkloadServiceToken({
+        baseUrl: this.baseURL,
+        ...(audience === DEFAULT_SERVICE_TOKEN_AUDIENCE ? {} : { audience }),
+      });
+      const current = this.serviceTokens.get(cacheKey);
       if (current) {
         current.token = granted.token;
         current.expiresAt = Date.now() + granted.expiresIn * 1000;
@@ -639,12 +681,11 @@ export class OxyServer extends OxyServices {
     try {
       return await pending;
     } catch (error) {
-      const failed = this.serviceTokens.get(WORKLOAD_CACHE_KEY);
-      if (failed?.pending === pending && !failed.token)
-        this.serviceTokens.delete(WORKLOAD_CACHE_KEY);
+      const failed = this.serviceTokens.get(cacheKey);
+      if (failed?.pending === pending && !failed.token) this.serviceTokens.delete(cacheKey);
       throw error;
     } finally {
-      const settled = this.serviceTokens.get(WORKLOAD_CACHE_KEY);
+      const settled = this.serviceTokens.get(cacheKey);
       if (settled?.pending === pending) settled.pending = null;
     }
   }

package/src/server/index.ts

@@ -21,8 +21,9 @@ export {
   OxyServer,
   ServiceCredentialMismatchError,
   ANONYMOUS_SERVICE_TOKEN_RETRY_MS,
+  DEFAULT_SERVICE_TOKEN_AUDIENCE,
 } from './OxyServer';
-export type { OxyServerConfig, ServiceTokenResponse } from './OxyServer';
+export type { OxyServerConfig, ServiceTokenAudience, ServiceTokenResponse } from './OxyServer';
 export {
   ServerAppsApi,
   ServerAgencyApi,

package/src/server/workloadIdentity.ts

@@ -41,6 +41,11 @@ const STS_BODY = 'Action=GetCallerIdentity&Version=2011-06-15';
 export interface WorkloadServiceTokenOptions {
   /** Oxy's base URL, e.g. `https://api.oxy.so`. */
   baseUrl: string;
+  /**
+   * The resource server the token is for (e.g. `kaana.ai`). Omitted, Oxy mints
+   * for `oxy-api`, as it always has.
+   */
+  audience?: string;
   /** Injected in tests; defaults to the global. */
   fetch?: typeof fetch;
 }
@@ -233,7 +238,12 @@ export async function requestWorkloadServiceToken(
   const tokenResponse = await fetchImpl(`${base}/auth/service-token/workload`, {
     method: 'POST',
     headers: { 'content-type': 'application/json' },
-    body: JSON.stringify({ provider: 'aws-iam', nonce: challenge.nonce, attestation }),
+    body: JSON.stringify({
+      provider: 'aws-iam',
+      nonce: challenge.nonce,
+      attestation,
+      ...(options.audience === undefined ? {} : { audience: options.audience }),
+    }),
   });
   if (!tokenResponse.ok) {
     // The body carries a bounded `reason`; the token never travels on a failure,

package/src/utils/corsPreflight.ts

@@ -0,0 +1,49 @@
+/**
+ * Whether a browser has to send a CORS preflight (`OPTIONS`) before this
+ * cross-origin request goes out, per the Fetch standard's CORS-safelisted
+ * methods and request headers.
+ *
+ * The SDK uses it for one invariant: its anonymous telemetry headers
+ * (`X-Oxy-Activity-Id`, `X-Oxy-Edge-Region`) ride only on requests that are
+ * preflighted anyway, so they never turn a request that would go straight out
+ * into one that first waits a round trip for an `OPTIONS`. A browser caches a
+ * preflight per URL, so without this every distinct anonymous read (a post's
+ * replies, a profile, a public app record) paid a round trip of its own.
+ *
+ * Deliberately conservative: a header it does not recognise as safelisted
+ * counts as needing a preflight, which only means the telemetry headers ride
+ * along exactly as they always did. Value-level rules (for example `Accept`'s
+ * 128-byte limit) are not modelled; a misjudgement in that direction drops two
+ * advisory headers from one request and nothing else.
+ */
+
+const SAFELISTED_METHODS: ReadonlySet<string> = new Set(['GET', 'HEAD', 'POST']);
+
+const SAFELISTED_HEADERS: ReadonlySet<string> = new Set([
+  'accept',
+  'accept-language',
+  'content-language',
+  'content-type',
+]);
+
+const SAFELISTED_CONTENT_TYPES: ReadonlySet<string> = new Set([
+  'application/x-www-form-urlencoded',
+  'multipart/form-data',
+  'text/plain',
+]);
+
+export function requiresCorsPreflight(
+  method: string,
+  headers: Iterable<readonly [string, string]>,
+): boolean {
+  if (!SAFELISTED_METHODS.has(method.toUpperCase())) return true;
+  for (const [rawName, value] of headers) {
+    const name = rawName.toLowerCase();
+    if (!SAFELISTED_HEADERS.has(name)) return true;
+    if (name === 'content-type') {
+      const essence = value.split(';')[0]?.trim().toLowerCase() ?? '';
+      if (!SAFELISTED_CONTENT_TYPES.has(essence)) return true;
+    }
+  }
+  return false;
+}