@oxy.so/core 1.5.0 → 1.6.0

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

@@ -34,7 +34,6 @@ import { OxyServicesNodesMixin } from './OxyServices.nodes';
 import { OxyServicesFollowGraphMixin } from './OxyServices.followGraph';
 import { OxyServicesInferenceMixin } from './OxyServices.inference';
 import { OxyServicesDeviceBootMixin } from './OxyServices.deviceBoot';
-import { OxyServicesDeviceTransferMixin } from './OxyServices.deviceTransfer';
 /**
  * Instance shape of every mixin in the pipeline, intersected. The runtime
  * `composeOxyServices()` produces a class whose instances expose all of
@@ -44,7 +43,7 @@ import { OxyServicesDeviceTransferMixin } from './OxyServices.deviceTransfer';
  * If you add a new mixin to `MIXIN_PIPELINE`, add it here too so its methods
  * are visible without a cast.
  */
-type AllMixinInstances = InstanceType<ReturnType<typeof OxyServicesAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUserMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityBackupMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPrivacyMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLanguageMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPaymentMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesReputationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAssetsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAccountsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesConnectedAppsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAgencyMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesStoreMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLocationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAnalyticsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDevicesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSecurityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFeaturesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesTopicsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesContactsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesNotificationsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAppDataMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesCivicMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesChainsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesNodesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFollowGraphMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesInferenceMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDeviceBootMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDeviceTransferMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
+type AllMixinInstances = InstanceType<ReturnType<typeof OxyServicesAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUserMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityBackupMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPrivacyMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLanguageMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPaymentMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesReputationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAssetsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAccountsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesConnectedAppsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAgencyMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesStoreMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLocationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAnalyticsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDevicesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSecurityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFeaturesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesTopicsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesContactsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesNotificationsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAppDataMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesCivicMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesChainsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesNodesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFollowGraphMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesInferenceMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDeviceBootMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
 /**
  * Constructor type for the fully composed mixin pipeline. Each mixin returns
  * a new constructor that augments its input; reducing across the pipeline

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

@@ -38,3 +38,11 @@ export { isOfficialWebOrigin } from '../utils/officialOrigins';
 export { createEcosystemTraffic } from './traffic';
 export type { EcosystemTrafficOptions } from './traffic';
 export { observeNodeHttp, withoutNodeHttpObservation } from './trafficNodeHttp';
+/**
+ * Workload identity (ADR 0026): a first-party service asks Oxy for a service
+ * token by proving what it IS, with no api key and no secret. Server-only, and
+ * exported from this subpath rather than the root barrel because it reaches the
+ * container credentials endpoint.
+ */
+export { canAttestWorkloadIdentity, requestWorkloadServiceToken } from './workloadIdentity';
+export type { WorkloadServiceToken, WorkloadServiceTokenOptions } from './workloadIdentity';

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

@@ -155,6 +155,14 @@ export declare function inlineScriptCspHash(source: string): string;
 export interface OxyPagesHeadersOptions {
     /** Per-app additions merged into {@link OXY_CSP_BASELINE}. */
     csp?: OxyCspExtensions;
+    /**
+     * An origin where people authenticate, consent or recover (`auth.oxy.so`,
+     * ADR 0024 D1). The Cloudflare Insights beacon — injected by the edge, not by
+     * the app — is REMOVED from `script-src` and `connect-src`, so third-party
+     * measurement cannot run there even when the zone has Web Analytics enabled.
+     * A structural block in the policy the page is served with, not a build flag.
+     */
+    sensitive?: boolean;
     /**
      * Emit `Strict-Transport-Security` (default `true`). Cloudflare Pages serves
      * HTTPS only, so static deploys should keep this on.

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

@@ -0,0 +1,32 @@
+export interface WorkloadServiceTokenOptions {
+    /** Oxy's base URL, e.g. `https://api.oxy.so`. */
+    baseUrl: string;
+    /** Injected in tests; defaults to the global. */
+    fetch?: typeof fetch;
+}
+export interface WorkloadServiceToken {
+    token: string;
+    /** Seconds from now, as Oxy reported it. */
+    expiresIn: number;
+    appName: string;
+}
+/**
+ * Whether this process can attest at all.
+ *
+ * The relative URI is set by ECS on every task and by nothing else, so its
+ * presence is the honest test for "we can prove what we are here". A local
+ * checkout has no attestation to offer and must fall back to a credential.
+ */
+export declare function canAttestWorkloadIdentity(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Exchanges this process's identity for an Oxy service token.
+ *
+ * Two round trips by design (see ADR 0026): a nonce, then an attestation that
+ * signs it. The caller caches the token — it lives an hour — rather than doing
+ * this per request.
+ *
+ * Failures are thrown, never swallowed into an empty token: a caller that
+ * cannot prove what it is must not go on to make an unauthenticated request and
+ * discover the problem as a 401 somewhere else.
+ */
+export declare function requestWorkloadServiceToken(options: WorkloadServiceTokenOptions): Promise<WorkloadServiceToken>;

package/package.json

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

@@ -186,6 +186,34 @@ const TOKEN_REFRESH_COOLDOWN_MS = 15000;
  */
 const EXPIRED_TOKEN_REFRESH_COOLDOWN_MS = 1000;
 
+/**
+ * Cooldown (ms) applied after the refresh endpoint answered 429 Too Many
+ * Requests. Overrides BOTH cooldowns above, because neither of them is about
+ * this failure.
+ *
+ * The other two ask "is the current token still usable?" and answer a server
+ * that is unreachable or erroring. A 429 is the opposite situation: the server
+ * is perfectly reachable and is telling this client, specifically, that it is
+ * asking too often. `EXPIRED_TOKEN_REFRESH_COOLDOWN_MS` then becomes actively
+ * harmful — an expired token drives the request-time preflight and the 401
+ * retry lanes at one mint per second (60/min) against a mint budget of 30/min,
+ * so the client's own retries hold the limiter tripped and it can never fall
+ * back under the ceiling. The limit stops being self-clearing and becomes
+ * self-sustaining for as long as the app keeps issuing requests.
+ *
+ * Sized to the mint limiter's own window (60s, `packages/api/src/routes/sessionDevice.ts`)
+ * so ONE attempt lands per window: enough to discover the moment the budget has
+ * drained, never enough to consume it. The per-device lockout answers 429 for
+ * far longer (15 min), and that is fine — one probe a minute against it is
+ * negligible traffic and the session recovers the instant the lockout lifts.
+ *
+ * NOT routed through the scheduler's exponential backoff: that backoff is
+ * effect-local to `startTokenRefreshScheduler` and governs only the scheduled
+ * lane, while the lanes that actually produce the storm here (preflight, 401
+ * retry) are request-driven and are throttled solely by this cooldown.
+ */
+const RATE_LIMITED_REFRESH_COOLDOWN_MS = 60_000;
+
 /**
  * Lead time (seconds) before access-token expiry at which a preflight refresh
  * is triggered. A token within this window of `exp` is treated as effectively
@@ -293,6 +321,17 @@ export class HttpService {
    * fixed deadline that could not shrink once the token expired mid-cooldown.
    */
   private lastRefreshFailureAt = 0;
+  /**
+   * Whether the last refresh failure was the server answering 429. Selects
+   * {@link RATE_LIMITED_REFRESH_COOLDOWN_MS} over the two token-state cooldowns
+   * for the NEXT attempt, and is cleared by any success or any other failure.
+   *
+   * A boolean beside {@link lastRefreshFailureAt} rather than a stored deadline,
+   * for the same reason that field gives: the cooldown stays a function of the
+   * current state, so it can still shorten if the situation changes underneath
+   * it, and there is exactly one timestamp to reason about.
+   */
+  private lastRefreshWasRateLimited = false;
   private authRefreshHandler: AuthRefreshHandler | null = null;
   private accessTokenProvider: AccessTokenProvider | null = null;
   private deviceSecretMintInFlight: Promise<DeviceSecretMintOutcome> | null = null;
@@ -1156,20 +1195,29 @@ export class HttpService {
       return null;
     }
 
-    // Post-failure cooldown. A genuinely EXPIRED current token uses a much
-    // shorter cooldown than a still-valid (proactive, near-expiry) one: an
-    // expired token is unusable, so re-mint as soon as the endpoint is reachable
-    // again rather than waiting out the full window while requests carry a stale
-    // bearer. Both cooldowns are measured from the last failure, so the moment a
-    // still-valid token crosses `exp` mid-cooldown the shorter window applies.
-    const cooldownMs = this.isAccessTokenExpired()
-      ? EXPIRED_TOKEN_REFRESH_COOLDOWN_MS
-      : TOKEN_REFRESH_COOLDOWN_MS;
+    // Post-failure cooldown. A 429 names its own window regardless of token
+    // state — the server is reachable and is rationing this client, so retrying
+    // at the expired-token rate would spend the very budget being waited on.
+    // Otherwise a genuinely EXPIRED current token uses a much shorter cooldown
+    // than a still-valid (proactive, near-expiry) one: an expired token is
+    // unusable, so re-mint as soon as the endpoint is reachable again rather
+    // than waiting out the full window while requests carry a stale bearer. All
+    // three are measured from the last failure, so the moment a still-valid
+    // token crosses `exp` mid-cooldown the shorter window applies.
+    const cooldownMs = this.lastRefreshWasRateLimited
+      ? RATE_LIMITED_REFRESH_COOLDOWN_MS
+      : this.isAccessTokenExpired()
+        ? EXPIRED_TOKEN_REFRESH_COOLDOWN_MS
+        : TOKEN_REFRESH_COOLDOWN_MS;
     if (Date.now() - this.lastRefreshFailureAt < cooldownMs) {
       return null;
     }
 
     if (!this.tokenRefreshPromise) {
+      // Cleared before the attempt, never after it: the handler reports a 429
+      // by calling `noteRefreshRateLimited()` from INSIDE this call, so clearing
+      // on the way out would discard the flag it just set.
+      this.lastRefreshWasRateLimited = false;
       this.tokenRefreshPromise = this.authRefreshHandler(reason)
         .then((newToken) => {
           if (!newToken) {
@@ -1183,6 +1231,7 @@ export class HttpService {
           // A success clears the failure timestamp so the next refresh is never
           // throttled by a stale cooldown.
           this.lastRefreshFailureAt = 0;
+          this.lastRefreshWasRateLimited = false;
           this.logger.debug('Token refreshed via the auth refresh handler');
           return newToken;
         })
@@ -1199,6 +1248,22 @@ export class HttpService {
     return this.tokenRefreshPromise;
   }
 
+  /**
+   * Report that the refresh/mint endpoint answered 429 Too Many Requests, so the
+   * next attempt waits {@link RATE_LIMITED_REFRESH_COOLDOWN_MS} instead of one of
+   * the token-state cooldowns.
+   *
+   * Called by the refresh handler (`refreshDeviceSecretArm`) from inside the
+   * `authRefreshHandler` call, because the handler's `Promise<string | null>`
+   * contract cannot carry WHY a refresh failed and 429 is the one failure whose
+   * correct retry interval is set by the server rather than by the token.
+   *
+   * Public because the handler lives in `session/refresh.ts`, not on this class.
+   */
+  noteRefreshRateLimited(): void {
+    this.lastRefreshWasRateLimited = true;
+  }
+
   /**
    * Whether the CURRENT stored access token is already past its `exp`. Drives
    * the shorter post-failure refresh cooldown ({@link EXPIRED_TOKEN_REFRESH_COOLDOWN_MS}):

package/src/OxyServices.ts

@@ -61,6 +61,7 @@ import { AssetUrlResolutionError, OxyAuthenticationError, OxyAuthenticationTimeo
 
 // Import mixin composition helper
 import { composeOxyServices } from './mixins';
+import type { OxyAuthRefusal } from './mixins/OxyServices.utility';
 
 /**
  * OxyServices - Unified client library for interacting with the Oxy API
@@ -120,11 +121,18 @@ export interface OxyServices extends InstanceType<ReturnType<typeof composeOxySe
   createLinkedClient(config: OxyConfig): LinkedHttpClient;
 
   // Express.js middleware
+  //
+  // This list is the one CONSUMERS see: `OxyAuthMiddlewareOptions` in
+  // `server/auth.ts` is `Parameters<OxyServices['auth']>[0]`, so an option that
+  // exists on the mixin and not here does not exist for anybody outside this
+  // package. `onRefusal` shipped in 1.5.0 exactly that way — present in the
+  // implementation, invisible to every host that tried to pass it.
   auth(options?: {
     debug?: boolean;
     onError?: (error: unknown) => unknown;
     loadUser?: boolean;
     optional?: boolean;
+    onRefusal?: (refusal: OxyAuthRefusal) => void;
     serviceTokenJwksUrl?: string;
     jwtSecret?: string;
     expectedIssuer?: string;
@@ -139,6 +147,7 @@ export interface OxyServices extends InstanceType<ReturnType<typeof composeOxySe
   // Service-token-only middleware (delegates to auth() internally)
   serviceAuth(options?: {
     debug?: boolean;
+    onRefusal?: (refusal: OxyAuthRefusal) => void;
     serviceTokenJwksUrl?: string;
     jwtSecret?: string;
     expectedIssuer?: string;

package/src/__tests__/httpServiceRateLimitedRefresh.test.ts

@@ -0,0 +1,160 @@
+/**
+ * The post-429 refresh cooldown.
+ *
+ * `POST /session/device/token` is budgeted at 30 mints/minute
+ * (`packages/api/src/routes/sessionDevice.ts`). Once the access token is
+ * EXPIRED, the request-driven refresh lanes — the request-time preflight in
+ * `getAuthHeader` and the 401 retry — reattempt on
+ * `EXPIRED_TOKEN_REFRESH_COOLDOWN_MS`, i.e. one mint per second, 60/min. That
+ * is correct against an unreachable server (recover the instant it returns) and
+ * exactly wrong against a rationing one: the retries spend the very budget they
+ * are waiting on, so the limiter stays tripped for as long as the app keeps
+ * issuing requests and the session can never heal itself.
+ *
+ * These tests pin the discrimination: a 429 lengthens the NEXT cooldown to the
+ * limiter's own window, every other failure keeps the token-state cooldowns, and
+ * a success clears it.
+ *
+ * `Date.now` is stubbed rather than using fake timers: the cooldown is a pure
+ * comparison against a stored epoch, so moving the clock is the whole
+ * experiment, and real microtasks keep the refresh promises resolving normally.
+ */
+import { HttpService } from '../HttpService';
+
+function createJwt(payload: Record<string, unknown>): string {
+  const encode = (value: unknown): string => Buffer.from(JSON.stringify(value)).toString('base64url');
+  return `${encode({ alg: 'HS256', typ: 'JWT' })}.${encode(payload)}.signature`;
+}
+
+/** The server's mint budget window — the interval the fix must wait out. */
+const LIMITER_WINDOW_MS = 60_000;
+
+/** Comfortably past the expired-token cooldown (1s) but inside the 429 window. */
+const BETWEEN_COOLDOWNS_MS = 30_000;
+
+describe('HttpService — refresh cooldown after a rate-limited mint', () => {
+  let clock = 1_700_000_000_000;
+
+  beforeEach(() => {
+    clock = 1_700_000_000_000;
+    jest.spyOn(Date, 'now').mockImplementation(() => clock);
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  /** A client whose CURRENT access token is already past `exp`. */
+  function expiredTokenClient(): HttpService {
+    const http = new HttpService({ baseURL: 'https://api.oxy.so', enableRetry: false });
+    http.setTokens(createJwt({ userId: 'u', exp: Math.floor(clock / 1000) - 60 }));
+    return http;
+  }
+
+  it('retries an expired token ~1s after an ORDINARY failure (the unreachable-server lane is untouched)', async () => {
+    const http = expiredTokenClient();
+    const handler = jest.fn(async () => null);
+    http.setAuthRefreshHandler(handler);
+
+    expect(await http.refreshAccessToken('preflight')).toBeNull();
+    expect(handler).toHaveBeenCalledTimes(1);
+
+    clock += 1_001;
+    expect(await http.refreshAccessToken('preflight')).toBeNull();
+    expect(handler).toHaveBeenCalledTimes(2);
+  });
+
+  it('suppresses the retry for the limiter window after a 429, instead of hammering once a second', async () => {
+    const http = expiredTokenClient();
+    const handler = jest.fn(async () => {
+      // What `refreshDeviceSecretArm` does when the mint answers 429.
+      http.noteRefreshRateLimited();
+      return null;
+    });
+    http.setAuthRefreshHandler(handler);
+
+    expect(await http.refreshAccessToken('preflight')).toBeNull();
+    expect(handler).toHaveBeenCalledTimes(1);
+
+    // Past the expired-token cooldown. Without the 429 discrimination this is
+    // where the client resumes one mint per second and holds the limiter down.
+    clock += BETWEEN_COOLDOWNS_MS;
+    expect(await http.refreshAccessToken('preflight')).toBeNull();
+    expect(handler).toHaveBeenCalledTimes(1);
+
+    // Once the limiter's window has drained, exactly one probe goes out.
+    clock += LIMITER_WINDOW_MS;
+    expect(await http.refreshAccessToken('preflight')).toBeNull();
+    expect(handler).toHaveBeenCalledTimes(2);
+  });
+
+  it('holds a rate-limited client under the mint budget while requests keep arriving', async () => {
+    const http = expiredTokenClient();
+    const handler = jest.fn(async () => {
+      http.noteRefreshRateLimited();
+      return null;
+    });
+    http.setAuthRefreshHandler(handler);
+
+    // One simulated minute of a busy app: a request every 250ms, each one
+    // driving the preflight/401 refresh lane.
+    for (let elapsed = 0; elapsed < 60_000; elapsed += 250) {
+      await http.refreshAccessToken('preflight');
+      clock += 250;
+    }
+
+    // The server's budget is 30/min. The unfixed client issues 60.
+    expect(handler.mock.calls.length).toBeLessThanOrEqual(2);
+  });
+
+  it('clears the lengthened cooldown once a refresh succeeds', async () => {
+    const http = expiredTokenClient();
+    const fresh = createJwt({ userId: 'u', exp: Math.floor(clock / 1000) + 900 });
+    const handler = jest
+      .fn<Promise<string | null>, []>()
+      .mockImplementationOnce(async () => {
+        http.noteRefreshRateLimited();
+        return null;
+      })
+      .mockImplementationOnce(async () => fresh)
+      // A later ordinary failure must be back on the short cooldown, proving the
+      // 429 state did not become sticky.
+      .mockImplementation(async () => null);
+    http.setAuthRefreshHandler(handler);
+
+    await http.refreshAccessToken('preflight');
+    clock += LIMITER_WINDOW_MS + 1;
+    expect(await http.refreshAccessToken('preflight')).toBe(fresh);
+
+    // The planted token is fresh, so this is the still-valid (15s) cooldown.
+    clock += 16_000;
+    await http.refreshAccessToken('preflight');
+    expect(handler).toHaveBeenCalledTimes(3);
+
+    clock += 16_000;
+    await http.refreshAccessToken('preflight');
+    expect(handler).toHaveBeenCalledTimes(4);
+  });
+
+  it('returns to the short cooldown when a later failure is NOT a 429', async () => {
+    const http = expiredTokenClient();
+    const handler = jest
+      .fn<Promise<string | null>, []>()
+      .mockImplementationOnce(async () => {
+        http.noteRefreshRateLimited();
+        return null;
+      })
+      // The limiter window passed and the endpoint is merely erroring now.
+      .mockImplementation(async () => null);
+    http.setAuthRefreshHandler(handler);
+
+    await http.refreshAccessToken('preflight');
+    clock += LIMITER_WINDOW_MS + 1;
+    await http.refreshAccessToken('preflight');
+    expect(handler).toHaveBeenCalledTimes(2);
+
+    clock += 1_001;
+    await http.refreshAccessToken('preflight');
+    expect(handler).toHaveBeenCalledTimes(3);
+  });
+});

package/src/__tests__/publicInterfaceParity.test.ts

@@ -0,0 +1,75 @@
+/**
+ * The middleware options a CONSUMER can pass must be the ones the middleware
+ * actually takes.
+ *
+ * `src/OxyServices.ts` re-declares `auth()` and `serviceAuth()` by hand, with
+ * their option objects written out inline, because declaration emit for the
+ * mixin pipeline does not carry them. That hand-written interface is what
+ * downstream packages see — `OxyAuthMiddlewareOptions` in `server/auth.ts` is
+ * literally `Parameters<OxyServices['auth']>[0]` — so an option that exists on
+ * the mixin and not there exists for this package and for nobody else.
+ *
+ * `onRefusal` shipped in 1.5.0 exactly that way: implemented, tested, exported,
+ * and rejected by the first host that tried to pass it
+ * (`TS2345 … has no properties in common with`). Nothing in this package could
+ * see it, because everything in this package resolves the mixin's own
+ * declaration, where the option is present. Only the published `.d.ts` loses it.
+ *
+ * So the check is on the SOURCE TEXT of the two declarations, which is the
+ * thing that diverges. It is not a type test: a type test here reads the merged
+ * interface and passes either way — measured, by deleting the option and
+ * watching `tsc --noEmit` stay green.
+ */
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const SRC = join(__dirname, '..');
+
+/** Every `name?:` key declared directly inside one brace-balanced block. */
+function optionKeys(source: string, startPattern: RegExp): string[] {
+  const match = startPattern.exec(source);
+  if (!match) throw new Error(`declaration not found: ${String(startPattern)}`);
+  let depth = 0;
+  let index = source.indexOf('{', match.index);
+  const open = index;
+  do {
+    const char = source[index];
+    if (char === '{') depth += 1;
+    else if (char === '}') depth -= 1;
+    index += 1;
+  } while (depth > 0 && index < source.length);
+  const body = source.slice(open + 1, index - 1);
+  // Only keys at THIS level: a nested object literal would otherwise contribute
+  // its own keys. None exist today; the guard keeps that from becoming silent.
+  const withoutNested = body.replace(/\{[^{}]*\}/g, '');
+  return [...withoutNested.matchAll(/^\s*(\w+)\??\s*:/gm)].map((m) => m[1] as string).sort();
+}
+
+describe('the public OxyServices interface declares the options the mixin takes', () => {
+  const mixin = readFileSync(join(SRC, 'mixins/OxyServices.utility.ts'), 'utf8');
+  const publicInterface = readFileSync(join(SRC, 'OxyServices.ts'), 'utf8');
+
+  it('auth() — same option names on both declarations', () => {
+    const declared = optionKeys(mixin, /interface AuthMiddlewareOptions/);
+    const published = optionKeys(publicInterface, /^ {2}auth\(options\?: \{/m);
+
+    expect(declared).toContain('onRefusal');
+    expect(published).toEqual(declared);
+  });
+
+  it('serviceAuth() — same option names on both declarations', () => {
+    const declared = optionKeys(mixin, /^ {4}serviceAuth\(options: \{/m);
+    const published = optionKeys(publicInterface, /^ {2}serviceAuth\(options\?: \{/m);
+
+    expect(declared).toContain('onRefusal');
+    expect(published).toEqual(declared);
+  });
+
+  it('reads real declarations rather than matching nothing', () => {
+    // The floor. A regex that stopped matching would make both cases above
+    // compare two empty lists and pass.
+    expect(optionKeys(mixin, /interface AuthMiddlewareOptions/).length).toBeGreaterThan(5);
+    expect(optionKeys(publicInterface, /^ {2}auth\(options\?: \{/m).length).toBeGreaterThan(5);
+  });
+});

package/src/__tests__/serviceTokenWorkloadFallback.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it, jest } from '@jest/globals';
+
+import { OxyServices } from '../OxyServices';
+
+/**
+ * How an official service stops holding a secret WITHOUT a code change.
+ *
+ * `getServiceToken()` has always required an api key and secret. It now falls
+ * back to workload identity (ADR 0026) when there is none — which means the
+ * migration for each of Oxy's own services is "delete two environment
+ * variables", not "edit and redeploy an app".
+ *
+ * Three things have to be true for that to be safe, and each is asserted below:
+ *
+ *  1. A configured credential still wins. The fallback must not quietly change
+ *     how an already-working service authenticates.
+ *  2. With no credential AND no way to attest — a laptop, a CI box — the caller
+ *     gets the same "no credentials" error as before, not a confusing failure
+ *     from a container credentials endpoint that is not there.
+ *  3. The token is cached, so a service does not mint one per request.
+ */
+
+jest.mock('../server/workloadIdentity', () => ({
+  canAttestWorkloadIdentity: () => Boolean(process.env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI),
+  requestWorkloadServiceToken: jest.fn(async () => ({
+    token: 'token-from-attestation',
+    expiresIn: 3600,
+    appName: 'Mention',
+  })),
+}));
+
+import { requestWorkloadServiceToken } from '../server/workloadIdentity';
+
+const attestations = requestWorkloadServiceToken as unknown as jest.Mock;
+
+function client() {
+  return new OxyServices({ baseURL: 'https://api.oxy.so' });
+}
+
+describe('service token — workload fallback', () => {
+  const previous = process.env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI;
+
+  beforeEach(() => {
+    attestations.mockClear();
+    process.env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI = '/v2/credentials/abc';
+  });
+
+  afterAll(() => {
+    // Cleared by assignment rather than `delete`: Biome refuses `delete` on a
+    // property access, and an empty value reads as "cannot attest" everywhere
+    // that matters here.
+    process.env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI = previous ?? '';
+  });
+
+  it('attests when no credential is configured', async () => {
+    await expect(client().getServiceToken()).resolves.toBe('token-from-attestation');
+    expect(attestations).toHaveBeenCalledWith({ baseUrl: 'https://api.oxy.so' });
+  });
+
+  it('mints once and serves the cached token afterwards', async () => {
+    const oxy = client();
+
+    await oxy.getServiceToken();
+    await oxy.getServiceToken();
+
+    expect(attestations).toHaveBeenCalledTimes(1);
+  });
+
+  it('leaves a configured credential alone', async () => {
+    const oxy = client();
+    oxy.configureServiceAuth('oxy_dk_example', 'secret-example');
+    // The credential path goes to the network; failing there is fine — what
+    // matters is that it did not silently attest instead.
+    await oxy.getServiceToken().catch(() => undefined);
+
+    expect(attestations).not.toHaveBeenCalled();
+  });
+
+  it('still says "no credentials" where nothing can be attested', async () => {
+    process.env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI = '';
+
+    await expect(client().getServiceToken()).rejects.toThrow(/Service credentials not provided/);
+    expect(attestations).not.toHaveBeenCalled();
+  });
+});