@oxy.so/core 1.18.0 → 1.18.1

package/dist/types/HttpService.d.ts

@@ -17,6 +17,11 @@ import type { DeviceSecretMintOutcome } from './session/refresh';
 export type AuthRefreshReason = 'preflight' | 'response-401';
 export type AuthRefreshHandler = (reason: AuthRefreshReason) => Promise<string | null>;
 export type AccessTokenProvider = () => string | null;
+/**
+ * Supplies a bearer for a request made while this client holds NO user session
+ * — `null` to send it anonymous. See {@link HttpService.setAnonymousAuthProvider}.
+ */
+export type AnonymousAuthProvider = () => Promise<string | null>;
 /**
  * A low-level authenticated request whose response body remains unread.
  *
@@ -162,6 +167,7 @@ export declare class HttpService {
     private noFresherTokenThan;
     private authRefreshHandler;
     private accessTokenProvider;
+    private anonymousAuthProvider;
     private deviceSecretMintInFlight;
     /**
      * Bumped by every {@link endSession}. A re-mint captures it before its first
@@ -324,6 +330,13 @@ export declare class HttpService {
      * Get auth header with automatic token refresh
      */
     private getAuthHeader;
+    /**
+     * The bearer for a request that has no user session behind it, from the
+     * {@link AnonymousAuthProvider} if one is installed. Never throws: a provider
+     * that fails sends the request anonymous, exactly as it went before any
+     * provider existed.
+     */
+    private getAnonymousAuthHeader;
     refreshAccessToken(reason: AuthRefreshReason): Promise<string | null>;
     /**
      * Report that the refresh/mint endpoint answered 429 Too Many Requests, so the
@@ -442,6 +455,14 @@ export declare class HttpService {
     hasSessionEnded(): boolean;
     setAuthRefreshHandler(handler: AuthRefreshHandler | null): void;
     setAccessTokenProvider(provider: AccessTokenProvider | null): void;
+    /**
+     * Authenticate requests that carry no user session with the bearer this
+     * provider returns — in practice a backend's own service token (see
+     * `OxyConfig.serviceIdentity`). A user session always wins: the provider is
+     * consulted only when there is no access token, and never for `skipAuth`
+     * requests. `null` removes it.
+     */
+    setAnonymousAuthProvider(provider: AnonymousAuthProvider | null): void;
     clearTokens(): void;
     /**
      * Subscribe to access-token changes on this instance.

package/dist/types/mixins/OxyServices.auth.d.ts

@@ -322,6 +322,11 @@ interface ServiceTokenCacheEntry {
 export declare class ServiceCredentialMismatchError extends Error {
     constructor();
 }
+/**
+ * How long a failed service-token mint sends session-less requests anonymous
+ * before the next attempt, under `serviceIdentity: 'when-anonymous'`.
+ */
+export declare const ANONYMOUS_SERVICE_TOKEN_RETRY_MS = 30000;
 export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T): {
     new (...args: any[]): {
         /**
@@ -346,6 +351,34 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
         _serviceApiKey: string | null;
         /** @internal Raw apiSecret stored by configureServiceAuth() for use by getServiceToken() */
         _serviceApiSecret: string | null;
+        /**
+         * Before this instant, a request without a user session does not try to
+         * mint a service token and goes out anonymous. Set after a failed mint; see
+         * {@link _serviceTokenForAnonymousRequest}.
+         *
+         * @internal
+         */
+        _anonymousServiceTokenRetryAt: number;
+        /**
+         * The bearer for a request with no user session, under `serviceIdentity:
+         * 'when-anonymous'`: this process's service token, or `null` to send the
+         * request anonymous as before.
+         *
+         * `null`, never a throw, whenever there is no token to offer:
+         * - no key pair and no attestable workload (a local checkout) — asking
+         *   costs nothing and there is nothing to ask for;
+         * - the mint failed. The request still goes out, anonymous, and so does
+         *   every request for the next {@link ANONYMOUS_SERVICE_TOKEN_RETRY_MS}, so
+         *   an Oxy that is refusing attestation (seen for ~2.5 minutes after a
+         *   deploy on 2026-09-25) is asked once per window rather than once per
+         *   read, and no read waits on a mint that just failed.
+         *
+         * The token itself comes from {@link getServiceToken}: cached for its
+         * lifetime and single-flight, so concurrent reads share one mint.
+         *
+         * @internal
+         */
+        _serviceTokenForAnonymousRequest(): Promise<string | null>;
         /**
          * Hash an apiKey into a stable Map cache key. Uses Node's SHA-256 — service
          * tokens are only ever issued by a Node host (the SDK on web/RN never has

package/dist/types/models/interfaces.d.ts

@@ -13,6 +13,27 @@ export interface OxyConfig {
      * bounce (which uses the RP origin, not this registered client id).
      */
     clientId?: string;
+    /**
+     * How a BACKEND identifies itself on requests that carry no user session.
+     *
+     * - `'never'` (default): such requests go out anonymous. Right for browsers
+     *   and apps, which have no service identity to offer.
+     * - `'when-anonymous'`: they carry this process's service token instead —
+     *   from `configureServiceAuth()`'s key pair, or, with none, from workload
+     *   attestation (ADR 0026). A user session, when there is one, still wins,
+     *   and a process that can produce no service token (a local checkout) keeps
+     *   sending the request anonymous.
+     *
+     * Why a server wants it: oxy-api charges anonymous traffic to the SOURCE
+     * ADDRESS (`rl:general`, and a +500 ms `slowDown` per request past 100 in 15
+     * minutes), and a fleet leaves through one NAT address, so every anonymous
+     * read a backend makes shares — and past the threshold pays for — one budget.
+     * A first-party service token is exempt from both and charged to its own
+     * application's budget instead. Measured from Mention's task (2026-09-25):
+     * `GET /users/:id` 543–575 ms anonymous past the threshold, `POST
+     * /users/by-ids` 19–24 ms with the service token.
+     */
+    serviceIdentity?: 'never' | 'when-anonymous';
     /**
      * Enable the per-instance GET response cache. Defaults to `true` (5-minute
      * TTL). Set to `false` to disable caching entirely for this instance — GET

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/core",
-  "version": "1.18.0",
+  "version": "1.18.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

@@ -38,6 +38,11 @@ interface JwtPayload {
 export type AuthRefreshReason = 'preflight' | 'response-401';
 export type AuthRefreshHandler = (reason: AuthRefreshReason) => Promise<string | null>;
 export type AccessTokenProvider = () => string | null;
+/**
+ * Supplies a bearer for a request made while this client holds NO user session
+ * — `null` to send it anonymous. See {@link HttpService.setAnonymousAuthProvider}.
+ */
+export type AnonymousAuthProvider = () => Promise<string | null>;
 
 /**
  * A low-level authenticated request whose response body remains unread.
@@ -378,6 +383,7 @@ export class HttpService {
   private noFresherTokenThan: string | null = null;
   private authRefreshHandler: AuthRefreshHandler | null = null;
   private accessTokenProvider: AccessTokenProvider | null = null;
+  private anonymousAuthProvider: AnonymousAuthProvider | null = null;
   private deviceSecretMintInFlight: Promise<DeviceSecretMintOutcome> | null = null;
   /**
    * Bumped by every {@link endSession}. A re-mint captures it before its first
@@ -1191,7 +1197,7 @@ export class HttpService {
   private async getAuthHeader(): Promise<string | null> {
     const accessToken = this.syncAccessTokenFromProvider();
     if (!accessToken) {
-      return null;
+      return this.getAnonymousAuthHeader();
     }
 
     try {
@@ -1222,6 +1228,23 @@ export class HttpService {
     }
   }
 
+  /**
+   * The bearer for a request that has no user session behind it, from the
+   * {@link AnonymousAuthProvider} if one is installed. Never throws: a provider
+   * that fails sends the request anonymous, exactly as it went before any
+   * provider existed.
+   */
+  private async getAnonymousAuthHeader(): Promise<string | null> {
+    if (!this.anonymousAuthProvider) return null;
+    try {
+      const token = await this.anonymousAuthProvider();
+      return token ? `Bearer ${token}` : null;
+    } catch (error) {
+      this.logger.debug('Anonymous auth provider failed; sending the request anonymous:', error);
+      return null;
+    }
+  }
+
   async refreshAccessToken(reason: AuthRefreshReason): Promise<string | null> {
     if (!this.authRefreshHandler) {
       return null;
@@ -1565,6 +1588,17 @@ export class HttpService {
     this.accessTokenProvider = provider;
   }
 
+  /**
+   * Authenticate requests that carry no user session with the bearer this
+   * provider returns — in practice a backend's own service token (see
+   * `OxyConfig.serviceIdentity`). A user session always wins: the provider is
+   * consulted only when there is no access token, and never for `skipAuth`
+   * requests. `null` removes it.
+   */
+  setAnonymousAuthProvider(provider: AnonymousAuthProvider | null): void {
+    this.anonymousAuthProvider = provider;
+  }
+
   clearTokens(): void {
     this.tokenStore.clearTokens();
     // Drop the response cache on logout. The cache is identity-scoped, so a

package/src/__tests__/serviceIdentityWhenAnonymous.test.ts

@@ -0,0 +1,159 @@
+/**
+ * `serviceIdentity: 'when-anonymous'` — a backend's session-less reads carry
+ * its service token.
+ *
+ * oxy-api charges anonymous requests to their source address, and a backend
+ * fleet leaves through one NAT address, so past 100 anonymous requests in 15
+ * minutes EVERY anonymous read that backend makes pays a +500 ms `slowDown`.
+ * Mention measured 543–575 ms for `GET /users/:id` anonymous against ~20 ms
+ * with its service token (OxyHQ/Mention#1173). A first-party service token is
+ * exempt, so a backend should present one on every read that has no user.
+ *
+ * What is asserted is the `Authorization` header that reaches `fetch`, because
+ * that is the only thing oxy-api's limiter sees.
+ */
+
+import { OxyServices } from '../OxyServices';
+import { ANONYMOUS_SERVICE_TOKEN_RETRY_MS } from '../mixins/OxyServices.auth';
+
+interface FetchCall {
+  url: string;
+  authorization: string | undefined;
+}
+
+function jsonResponse(data: unknown): Response {
+  return new Response(JSON.stringify({ data }), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+function authorizationOf(init: RequestInit | undefined): string | undefined {
+  const headers = init?.headers;
+  if (!headers) return undefined;
+  if (headers instanceof Headers) return headers.get('authorization') ?? undefined;
+  const record = headers as Record<string, string>;
+  return record.Authorization ?? record.authorization;
+}
+
+function createJwt(payload: Record<string, unknown>): string {
+  const encode = (value: unknown): string => Buffer.from(JSON.stringify(value)).toString('base64url');
+  return `${encode({ alg: 'EdDSA', typ: 'JWT' })}.${encode(payload)}.signature`;
+}
+
+describe("OxyServices serviceIdentity: 'when-anonymous'", () => {
+  const originalFetch = globalThis.fetch;
+  let calls: FetchCall[];
+
+  beforeEach(() => {
+    calls = [];
+    globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+      calls.push({ url: String(input), authorization: authorizationOf(init) });
+      return jsonResponse({ id: 'u1', username: 'alice', name: { displayName: 'Alice' } });
+    }) as typeof fetch;
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    jest.restoreAllMocks();
+  });
+
+  function backend(): OxyServices {
+    return new OxyServices({ baseURL: 'https://api.oxy.test', serviceIdentity: 'when-anonymous' });
+  }
+
+  it('sends a session-less read with the service token', async () => {
+    const oxy = backend();
+    jest.spyOn(oxy, '_canUseWorkloadIdentity').mockResolvedValue(true);
+    const getServiceToken = jest.spyOn(oxy, 'getServiceToken').mockResolvedValue('svc-token');
+
+    await oxy.getUserById('u1');
+    await oxy.getProfileByUsername('alice');
+
+    expect(calls.map((call) => call.authorization)).toEqual(['Bearer svc-token', 'Bearer svc-token']);
+    expect(getServiceToken).toHaveBeenCalledTimes(2);
+  });
+
+  it('uses a configured key pair without asking about attestation', async () => {
+    const oxy = backend();
+    oxy.configureServiceAuth('oxy_dk_test', 'secret');
+    const canAttest = jest.spyOn(oxy, '_canUseWorkloadIdentity');
+    jest.spyOn(oxy, 'getServiceToken').mockResolvedValue('keypair-token');
+
+    await oxy.getUserById('u1');
+
+    expect(calls[0].authorization).toBe('Bearer keypair-token');
+    expect(canAttest).not.toHaveBeenCalled();
+  });
+
+  it('lets a user session win over the service token', async () => {
+    const oxy = backend();
+    const getServiceToken = jest.spyOn(oxy, 'getServiceToken').mockResolvedValue('svc-token');
+    const userToken = createJwt({ userId: 'viewer', exp: Math.floor(Date.now() / 1000) + 3600 });
+    oxy.setTokens(userToken);
+
+    await oxy.getUserById('u1');
+
+    expect(calls[0].authorization).toBe(`Bearer ${userToken}`);
+    expect(getServiceToken).not.toHaveBeenCalled();
+  });
+
+  it('stays anonymous where no service token can exist (a local checkout)', async () => {
+    const oxy = backend();
+    jest.spyOn(oxy, '_canUseWorkloadIdentity').mockResolvedValue(false);
+    const getServiceToken = jest.spyOn(oxy, 'getServiceToken');
+
+    await oxy.getUserById('u1');
+
+    expect(calls[0].authorization).toBeUndefined();
+    expect(getServiceToken).not.toHaveBeenCalled();
+  });
+
+  it('sends the read anonymous when the mint fails, and does not retry the mint for a window', async () => {
+    const oxy = backend();
+    jest.spyOn(oxy, '_canUseWorkloadIdentity').mockResolvedValue(true);
+    const getServiceToken = jest
+      .spyOn(oxy, 'getServiceToken')
+      .mockRejectedValue(new Error('Oxy refused the workload attestation (401)'));
+    const now = jest.spyOn(Date, 'now');
+    const start = 1_800_000_000_000;
+    now.mockReturnValue(start);
+
+    // Different ids: each is a real request, not a cache hit or a deduplicated one.
+    await expect(oxy.getUserById('u1')).resolves.toBeDefined();
+    await expect(oxy.getUserById('u2')).resolves.toBeDefined();
+
+    expect(calls.map((call) => call.authorization)).toEqual([undefined, undefined]);
+    expect(getServiceToken).toHaveBeenCalledTimes(1);
+
+    // After the window the mint is tried again.
+    getServiceToken.mockResolvedValue('svc-token');
+    now.mockReturnValue(start + ANONYMOUS_SERVICE_TOKEN_RETRY_MS + 1);
+    await oxy.getUserById('u3');
+
+    expect(calls[2].authorization).toBe('Bearer svc-token');
+    expect(getServiceToken).toHaveBeenCalledTimes(2);
+  });
+
+  it('never attaches a bearer to a skipAuth request', async () => {
+    const oxy = backend();
+    jest.spyOn(oxy, '_canUseWorkloadIdentity').mockResolvedValue(true);
+    const getServiceToken = jest.spyOn(oxy, 'getServiceToken').mockResolvedValue('svc-token');
+
+    await oxy.makeRequest('GET', '/auth/lookup/alice', undefined, { skipAuth: true, cache: false });
+
+    expect(calls[0].authorization).toBeUndefined();
+    expect(getServiceToken).not.toHaveBeenCalled();
+  });
+
+  it('is off by default: a client without the option stays anonymous', async () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.test' });
+    jest.spyOn(oxy, '_canUseWorkloadIdentity').mockResolvedValue(true);
+    const getServiceToken = jest.spyOn(oxy, 'getServiceToken').mockResolvedValue('svc-token');
+
+    await oxy.getUserById('u1');
+
+    expect(calls[0].authorization).toBeUndefined();
+    expect(getServiceToken).not.toHaveBeenCalled();
+  });
+});

package/src/mixins/OxyServices.auth.ts

@@ -471,6 +471,12 @@ export class ServiceCredentialMismatchError extends Error {
   }
 }
 
+/**
+ * How long a failed service-token mint sends session-less requests anonymous
+ * before the next attempt, under `serviceIdentity: 'when-anonymous'`.
+ */
+export const ANONYMOUS_SERVICE_TOKEN_RETRY_MS = 30_000;
+
 export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T) {
   return class extends Base {
     /**
@@ -497,8 +503,57 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
     /** @internal Raw apiSecret stored by configureServiceAuth() for use by getServiceToken() */
     _serviceApiSecret: string | null = null;
 
+    /**
+     * Before this instant, a request without a user session does not try to
+     * mint a service token and goes out anonymous. Set after a failed mint; see
+     * {@link _serviceTokenForAnonymousRequest}.
+     *
+     * @internal
+     */
+    _anonymousServiceTokenRetryAt = 0;
+
     constructor(...args: any[]) {
       super(...(args as [any]));
+      if (this.config.serviceIdentity === 'when-anonymous') {
+        this.httpService.setAnonymousAuthProvider(() => this._serviceTokenForAnonymousRequest());
+      }
+    }
+
+    /**
+     * The bearer for a request with no user session, under `serviceIdentity:
+     * 'when-anonymous'`: this process's service token, or `null` to send the
+     * request anonymous as before.
+     *
+     * `null`, never a throw, whenever there is no token to offer:
+     * - no key pair and no attestable workload (a local checkout) — asking
+     *   costs nothing and there is nothing to ask for;
+     * - the mint failed. The request still goes out, anonymous, and so does
+     *   every request for the next {@link ANONYMOUS_SERVICE_TOKEN_RETRY_MS}, so
+     *   an Oxy that is refusing attestation (seen for ~2.5 minutes after a
+     *   deploy on 2026-09-25) is asked once per window rather than once per
+     *   read, and no read waits on a mint that just failed.
+     *
+     * The token itself comes from {@link getServiceToken}: cached for its
+     * lifetime and single-flight, so concurrent reads share one mint.
+     *
+     * @internal
+     */
+    async _serviceTokenForAnonymousRequest(): Promise<string | null> {
+      if (Date.now() < this._anonymousServiceTokenRetryAt) return null;
+      const hasKeyPair = Boolean(this._serviceApiKey && this._serviceApiSecret);
+      if (!hasKeyPair && !(await this._canUseWorkloadIdentity())) return null;
+      try {
+        return await this.getServiceToken();
+      } catch (error) {
+        this._anonymousServiceTokenRetryAt = Date.now() + ANONYMOUS_SERVICE_TOKEN_RETRY_MS;
+        logger.warn('[oxy.auth] No service token for a request without a session; sending it anonymous', {
+          component: 'auth',
+          method: '_serviceTokenForAnonymousRequest',
+          retryInMs: ANONYMOUS_SERVICE_TOKEN_RETRY_MS,
+          error: error instanceof Error ? error.message : String(error),
+        });
+        return null;
+      }
     }
 
     /**

package/src/models/interfaces.ts

@@ -22,6 +22,27 @@ export interface OxyConfig {
    * bounce (which uses the RP origin, not this registered client id).
    */
   clientId?: string;
+  /**
+   * How a BACKEND identifies itself on requests that carry no user session.
+   *
+   * - `'never'` (default): such requests go out anonymous. Right for browsers
+   *   and apps, which have no service identity to offer.
+   * - `'when-anonymous'`: they carry this process's service token instead —
+   *   from `configureServiceAuth()`'s key pair, or, with none, from workload
+   *   attestation (ADR 0026). A user session, when there is one, still wins,
+   *   and a process that can produce no service token (a local checkout) keeps
+   *   sending the request anonymous.
+   *
+   * Why a server wants it: oxy-api charges anonymous traffic to the SOURCE
+   * ADDRESS (`rl:general`, and a +500 ms `slowDown` per request past 100 in 15
+   * minutes), and a fleet leaves through one NAT address, so every anonymous
+   * read a backend makes shares — and past the threshold pays for — one budget.
+   * A first-party service token is exempt from both and charged to its own
+   * application's budget instead. Measured from Mention's task (2026-09-25):
+   * `GET /users/:id` 543–575 ms anonymous past the threshold, `POST
+   * /users/by-ids` 19–24 ms with the service token.
+   */
+  serviceIdentity?: 'never' | 'when-anonymous';
   // Performance & caching options
   /**
    * Enable the per-instance GET response cache. Defaults to `true` (5-minute