@oxy.so/core 1.5.1 → 1.6.1

package/src/server/__tests__/traffic.test.ts

@@ -1,6 +1,61 @@
 import { createEcosystemTraffic } from '../traffic';
 
-jest.mock('../../OxyServices', () => ({ OxyServices: jest.fn(() => ({})) }));
+/**
+ * Every client the publisher builds, so a test can ask what it was handed.
+ *
+ * Named `mock*` because ts-jest hoists `jest.mock` above the imports and only
+ * lets a factory close over a binding with that prefix.
+ */
+const mockClients: Array<{ configureServiceAuth: jest.Mock; getServiceToken: jest.Mock }> = [];
+
+jest.mock('../../OxyServices', () => ({
+  OxyServices: jest.fn(() => {
+    const client = {
+      configureServiceAuth: jest.fn(),
+      getServiceToken: jest.fn(async () => 'token-from-workload'),
+    };
+    mockClients.push(client);
+    return client;
+  }),
+}));
+
+function lastClient() {
+  const client = mockClients[mockClients.length - 1];
+  if (!client) throw new Error('No OxyServices was built.');
+  return client;
+}
+
+/** Accepts every publish and remembers the headers, so nothing reaches a network. */
+function recordingFetch(sent: RequestInit[]) {
+  return jest.fn(async (_input, init) => {
+    sent.push(init as RequestInit);
+    return new Response(null, { status: 204 });
+  }) as unknown as typeof fetch;
+}
+
+function authorizations(sent: RequestInit[]): string[] {
+  return sent.map(init => (init.headers as Record<string, string>).Authorization);
+}
+
+/**
+ * A process with nothing configured and nothing to attest: a laptop.
+ *
+ * Emptied by assignment rather than `delete`, which Biome refuses on a property
+ * access — and `= undefined` would be worse than either, because Node stores the
+ * STRING "undefined" and every check here would read it as a configured value.
+ */
+function clearCredentialEnvironment() {
+  process.env.OXY_ACTIVITY_API_KEY = '';
+  process.env.OXY_ACTIVITY_API_SECRET = '';
+  process.env.OXY_SERVICE_API_KEY = '';
+  process.env.OXY_SERVICE_API_SECRET = '';
+  process.env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI = '';
+  process.env.AWS_CONTAINER_CREDENTIALS_FULL_URI = '';
+}
+
+beforeEach(() => {
+  mockClients.length = 0;
+});
 
 it('publishes independently of viewers and waits for registration before removing a stopped instance', async () => {
   const originalFetch = globalThis.fetch;
@@ -47,3 +102,79 @@ it('rejects a partial activity credential instead of mixing it with service cred
     process.env = previous;
   }
 });
+
+/**
+ * Who may publish ecosystem activity, and who is still refused.
+ *
+ * ADR 0026 made "no api key, no secret" a legitimate shape for a first-party
+ * service: it attests its ECS task role instead. This constructor used to throw
+ * on exactly that shape, so the migration it asks for — delete two variables
+ * from a task definition — killed the process at boot, the circuit breaker
+ * rolled the deploy back, and the operator was told the service was stable.
+ */
+describe('ecosystem activity credentials', () => {
+  const previous = { ...process.env };
+  const originalFetch = globalThis.fetch;
+
+  afterEach(() => {
+    process.env = { ...previous };
+    globalThis.fetch = originalFetch;
+  });
+
+  it('uses a service key pair when the process holds one', async () => {
+    clearCredentialEnvironment();
+    process.env.OXY_SERVICE_API_KEY = 'service-key';
+    process.env.OXY_SERVICE_API_SECRET = 'service-secret';
+    const sent: RequestInit[] = [];
+    globalThis.fetch = recordingFetch(sent);
+
+    const traffic = createEcosystemTraffic({ service: 'mention', region: 'us-west-2' });
+    await traffic.stop();
+
+    expect(lastClient().configureServiceAuth).toHaveBeenCalledWith('service-key', 'service-secret');
+    expect(lastClient().getServiceToken).toHaveBeenCalled();
+  });
+
+  it('lets an explicit credential win over the environment', async () => {
+    clearCredentialEnvironment();
+    process.env.OXY_SERVICE_API_KEY = 'service-key';
+    process.env.OXY_SERVICE_API_SECRET = 'service-secret';
+    const sent: RequestInit[] = [];
+    globalThis.fetch = recordingFetch(sent);
+
+    const traffic = createEcosystemTraffic({ service: 'mention', region: 'us-west-2', credential: async () => 'explicit-token' });
+    await traffic.stop();
+
+    expect(authorizations(sent)).not.toContain('Bearer token-from-workload');
+    expect(authorizations(sent)).toContain('Bearer explicit-token');
+    expect(lastClient().getServiceToken).not.toHaveBeenCalled();
+  });
+
+  it('refuses a process with no credential and nothing to attest', () => {
+    clearCredentialEnvironment();
+
+    // A laptop or a CI box: the container credentials endpoint is not going to
+    // appear later, so saying so at boot beats failing on the first heartbeat.
+    expect(() => createEcosystemTraffic({ service: 'homiio', region: 'us-west-2' })).toThrow(
+      /needs one of: an OXY_ACTIVITY_API_KEY and OXY_ACTIVITY_API_SECRET pair, an OXY_SERVICE_API_KEY and OXY_SERVICE_API_SECRET pair, or a workload identity/
+    );
+  });
+
+  it('publishes with no key pair at all when the process can attest its workload identity', async () => {
+    clearCredentialEnvironment();
+    // The variable ECS sets on every task, and nothing else does. Stubbed, so
+    // `canAttestWorkloadIdentity()` answers yes without a credentials endpoint.
+    process.env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI = '/v2/credentials/abc';
+    const sent: RequestInit[] = [];
+    globalThis.fetch = recordingFetch(sent);
+
+    const traffic = createEcosystemTraffic({ service: 'mention', region: 'us-west-2' });
+    await traffic.stop();
+
+    // Unconfigured on purpose: that is what sends `getServiceToken()` down the
+    // workload path instead of handing it half a credential.
+    expect(lastClient().configureServiceAuth).not.toHaveBeenCalled();
+    expect(lastClient().getServiceToken).toHaveBeenCalled();
+    expect(authorizations(sent)).toContain('Bearer token-from-workload');
+  });
+});

package/src/server/__tests__/workloadIdentity.test.ts

@@ -0,0 +1,128 @@
+import { describe, expect, it, jest } from '@jest/globals';
+
+import { canAttestWorkloadIdentity, requestWorkloadServiceToken } from '../workloadIdentity';
+
+/**
+ * The client half of ADR 0026, and the two properties that decide whether it
+ * works at all against the verifier in `packages/api`:
+ *
+ *  1. **The nonce is inside the signature.** The verifier refuses an attestation
+ *     whose `SignedHeaders` omits the nonce header, so a signer that merely sets
+ *     the header produces attestations that are always rejected — a failure that
+ *     would only show up in production, against the real verifier.
+ *  2. **The signed request is never sent to AWS.** Only Oxy replays it. A client
+ *     that called STS itself would work in a test and leak an identity call per
+ *     token in production.
+ *
+ * The signature's cryptographic correctness is AWS's to judge; what is asserted
+ * here is its SHAPE, which is what the two halves have to agree on.
+ */
+
+const CREDENTIALS = {
+  AccessKeyId: 'ASIAEXAMPLE',
+  SecretAccessKey: 'secret-example',
+  Token: 'session-token-example',
+};
+
+function harness(overrides: { tokenStatus?: number } = {}) {
+  const calls: { url: string; init?: RequestInit }[] = [];
+  const fetchImpl = (async (input: string | URL | Request, init?: RequestInit) => {
+    const url = String(input);
+    calls.push({ url, init });
+    if (url.endsWith('/auth/service-token/workload/challenge')) {
+      return new Response(JSON.stringify({ data: { nonce: 'nonce-from-oxy', expiresIn: 60 } }), { status: 200 });
+    }
+    if (url.includes('169.254.170.2')) {
+      return new Response(JSON.stringify(CREDENTIALS), { status: 200 });
+    }
+    if (url.endsWith('/auth/service-token/workload')) {
+      const status = overrides.tokenStatus ?? 200;
+      if (status !== 200) return new Response('{}', { status });
+      return new Response(
+        JSON.stringify({ data: { token: 'service-token', expiresIn: 3600, appName: 'Mention' } }),
+        { status: 200 },
+      );
+    }
+    throw new Error(`unexpected request to ${url}`);
+  }) as unknown as typeof fetch;
+  return { calls, fetchImpl };
+}
+
+describe('workload identity client', () => {
+  const previous = process.env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI;
+
+  beforeEach(() => {
+    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('knows whether this process can attest at all', () => {
+    expect(canAttestWorkloadIdentity({ AWS_CONTAINER_CREDENTIALS_RELATIVE_URI: '/v2/x' } as NodeJS.ProcessEnv)).toBe(true);
+    expect(canAttestWorkloadIdentity({} as NodeJS.ProcessEnv)).toBe(false);
+  });
+
+  it('answers the challenge with a signature that covers the nonce', async () => {
+    const { calls, fetchImpl } = harness();
+
+    const granted = await requestWorkloadServiceToken({ baseUrl: 'https://api.oxy.so/', fetch: fetchImpl });
+
+    expect(granted).toEqual({ token: 'service-token', expiresIn: 3600, appName: 'Mention' });
+
+    const exchange = calls.find((call) => call.url.endsWith('/auth/service-token/workload'));
+    const body = JSON.parse(String(exchange?.init?.body)) as {
+      provider: string;
+      nonce: string;
+      attestation: { headers: Record<string, string> };
+    };
+
+    expect(body.provider).toBe('aws-iam');
+    expect(body.nonce).toBe('nonce-from-oxy');
+    expect(body.attestation.headers['x-oxy-attestation-nonce']).toBe('nonce-from-oxy');
+    expect(body.attestation.headers.host).toBe('sts.amazonaws.com');
+    expect(body.attestation.headers['x-amz-security-token']).toBe(CREDENTIALS.Token);
+    // The property the verifier actually checks.
+    expect(body.attestation.headers.authorization).toMatch(
+      /^AWS4-HMAC-SHA256 Credential=ASIAEXAMPLE\/\d{8}\/us-east-1\/sts\/aws4_request, SignedHeaders=[^,]*x-oxy-attestation-nonce[^,]*, Signature=[0-9a-f]{64}$/,
+    );
+  });
+
+  it('never sends the signed request to AWS itself', async () => {
+    const { calls, fetchImpl } = harness();
+
+    await requestWorkloadServiceToken({ baseUrl: 'https://api.oxy.so', fetch: fetchImpl });
+
+    expect(calls.some((call) => call.url.includes('sts.amazonaws.com'))).toBe(false);
+  });
+
+  it('carries no credential material into the request body', async () => {
+    const { calls, fetchImpl } = harness();
+
+    await requestWorkloadServiceToken({ baseUrl: 'https://api.oxy.so', fetch: fetchImpl });
+
+    const exchange = calls.find((call) => call.url.endsWith('/auth/service-token/workload'));
+    expect(String(exchange?.init?.body)).not.toContain(CREDENTIALS.SecretAccessKey);
+  });
+
+  it('throws rather than returning an empty token when Oxy refuses', async () => {
+    const { fetchImpl } = harness({ tokenStatus: 403 });
+
+    await expect(
+      requestWorkloadServiceToken({ baseUrl: 'https://api.oxy.so', fetch: fetchImpl }),
+    ).rejects.toThrow(/refused the workload attestation \(403\)/);
+  });
+
+  it('throws when the process has no identity to prove', async () => {
+    process.env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI = '';
+    const { fetchImpl } = harness();
+
+    await expect(
+      requestWorkloadServiceToken({ baseUrl: 'https://api.oxy.so', fetch: fetchImpl }),
+    ).rejects.toThrow(/cannot attest its identity/);
+  });
+});

package/src/server/index.ts

@@ -168,3 +168,12 @@ 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/src/server/securityHeaders.ts

@@ -360,6 +360,14 @@ const MAX_INLINE_SCRIPT_HASHES = 8;
 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.
@@ -399,13 +407,18 @@ export function buildOxyPagesHeaders(options: OxyPagesHeadersOptions = {}): stri
     );
   }
 
-  const csp = formatOxyCspPolicy(
-    buildOxyCspDirectives(
-      hashes.length === 0
-        ? options.csp
-        : { ...options.csp, scriptSrc: [...(options.csp?.scriptSrc ?? []), ...hashes] },
-    ),
+  const directives = buildOxyCspDirectives(
+    hashes.length === 0
+      ? options.csp
+      : { ...options.csp, scriptSrc: [...(options.csp?.scriptSrc ?? []), ...hashes] },
   );
+  if (options.sensitive) {
+    const beacon = new Set([CLOUDFLARE_INSIGHTS_SCRIPT_ORIGIN, CLOUDFLARE_INSIGHTS_REPORT_ORIGIN]);
+    for (const name of ['script-src', 'connect-src']) {
+      directives[name] = (directives[name] ?? []).filter((source) => !beacon.has(source));
+    }
+  }
+  const csp = formatOxyCspPolicy(directives);
   const lines = [
     '/*',
     `  Content-Security-Policy: ${csp}`,

package/src/server/traffic.ts

@@ -3,6 +3,12 @@ import { observeTrafficSocket, observeTrafficWebSocket, type TrafficWebSocket, t
 import { randomUUID } from 'node:crypto';
 import type { RequestHandler } from 'express';
 import { OxyServices } from '../OxyServices';
+// Static, unlike the lazy import in `mixins/OxyServices.auth.ts`: that module is
+// reachable from the root barrel, which ships to React Native, so pulling
+// `node:crypto` in eagerly there would cost every mobile bundle. This file is
+// server-only and the server barrel already exports `./workloadIdentity`, so
+// there is nothing here for a phone to load.
+import { canAttestWorkloadIdentity } from './workloadIdentity';
 import { createTrafficCollector, instrumentTrafficFetch, trafficMiddleware, type TrafficFlow, type ServiceEndpoint, resolveOxyServiceEndpoint, infrastructureLocation } from '@oxy.so/telemetry/collector';
 
 export interface EcosystemTrafficOptions {
@@ -36,8 +42,32 @@ export function createEcosystemTraffic(options: EcosystemTrafficOptions): {
   }
   const apiKey = activityKey || process.env.OXY_SERVICE_API_KEY;
   const apiSecret = activitySecret || process.env.OXY_SERVICE_API_SECRET;
-  if (!options.credential && (!apiKey || !apiSecret)) throw new Error('Ecosystem activity requires OXY_SERVICE_API_KEY and OXY_SERVICE_API_SECRET');
+  /**
+   * Having no key pair is a legitimate configuration now — but only where this
+   * process can prove what it IS (ADR 0026).
+   *
+   * This used to throw on a missing pair, full stop. Every service in the fleet
+   * boots with `OXY_ECOSYSTEM_ACTIVITY_ENABLED=true`, so deleting
+   * `OXY_SERVICE_API_KEY` and `OXY_SERVICE_API_SECRET` from a task definition —
+   * which is the entire migration ADR 0026 asks for — killed the process at
+   * boot. The ECS circuit breaker then rolled the deploy back and reported the
+   * service stable, so the operator saw a rollback with nothing naming its
+   * cause. That is what one line cost, multiplied by fourteen services holding
+   * a secret they no longer need.
+   *
+   * What is still refused: nothing to authenticate with AND nothing to attest.
+   * That is a laptop or a CI box, where the container credentials endpoint is
+   * not going to turn up later, and the honest answer is to say so at boot
+   * rather than to fail on the first heartbeat.
+   */
+  if (!options.credential && (!apiKey || !apiSecret) && !canAttestWorkloadIdentity()) {
+    throw new Error(
+      'Ecosystem activity needs one of: an OXY_ACTIVITY_API_KEY and OXY_ACTIVITY_API_SECRET pair, an OXY_SERVICE_API_KEY and OXY_SERVICE_API_SECRET pair, or a workload identity this process can attest (ADR 0026).',
+    );
+  }
   const oxy = new OxyServices({ baseURL });
+  // Left unconfigured when there is no pair on purpose: `getServiceToken()`
+  // attests instead of being handed half a credential to fail on.
   if (apiKey && apiSecret) oxy.configureServiceAuth(apiKey, apiSecret);
   const credential = options.credential ?? (() => oxy.getServiceToken());
   const fetcher = globalThis.fetch.bind(globalThis);

package/src/server/workloadIdentity.ts

@@ -0,0 +1,207 @@
+import { createHash, createHmac } from 'node:crypto';
+
+/**
+ * Asking Oxy for a service token by proving what this process IS (ADR 0026).
+ *
+ * The other half of the credential-free path: `packages/api` verifies the proof,
+ * this builds one. A first-party service that calls
+ * {@link requestWorkloadServiceToken} needs no api key, no secret and no entry in
+ * a parameter store — only to be running as itself.
+ *
+ * ## Why this signs SigV4 by hand
+ *
+ * The attestation is a signed `GetCallerIdentity` request that is never sent to
+ * AWS by us; Oxy replays it. Producing one needs credentials and a signature,
+ * and the obvious way to get both is the AWS SDK — which this package must not
+ * depend on. `@oxy.so/core` ships to React Native and Expo, where several
+ * megabytes of AWS client for a call that only ever happens on a server is not a
+ * trade worth making, and the package rules keep optional heavyweights out of
+ * the root barrel for exactly this reason.
+ *
+ * So: credentials come from the container credentials endpoint ECS already
+ * exposes to every task, and the signature is ~40 lines of HMAC out of
+ * `node:crypto`. No dependency, and nothing here is AWS-specific above
+ * {@link awsContainerAttestation} — a second provider is another function with
+ * the same shape.
+ *
+ * ## What this never does
+ *
+ * It never sends the signed request to AWS. It never logs a credential, a
+ * signature or a token. It caches the TOKEN (short-lived, from Oxy) and never
+ * the AWS credentials, which the endpoint hands out fresh anyway.
+ */
+
+/** The header Oxy's verifier requires inside the signature. Must match `ATTESTATION_NONCE_HEADER`. */
+const NONCE_HEADER = 'x-oxy-attestation-nonce';
+const STS_HOST = 'sts.amazonaws.com';
+const STS_REGION = 'us-east-1';
+const STS_BODY = 'Action=GetCallerIdentity&Version=2011-06-15';
+
+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;
+}
+
+/** Credentials as the ECS container credentials endpoint returns them. */
+interface ContainerCredentials {
+  AccessKeyId: string;
+  SecretAccessKey: string;
+  Token?: 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 function canAttestWorkloadIdentity(env: NodeJS.ProcessEnv = process.env): boolean {
+  return Boolean(env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI || env.AWS_CONTAINER_CREDENTIALS_FULL_URI);
+}
+
+async function containerCredentials(fetchImpl: typeof fetch): Promise<ContainerCredentials> {
+  const relative = process.env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI;
+  const url = relative
+    ? `http://169.254.170.2${relative}`
+    : (process.env.AWS_CONTAINER_CREDENTIALS_FULL_URI as string);
+  if (!url) {
+    throw new Error('No container credentials endpoint: this process cannot attest its identity.');
+  }
+  const response = await fetchImpl(url, {
+    headers: process.env.AWS_CONTAINER_AUTHORIZATION_TOKEN
+      ? { authorization: process.env.AWS_CONTAINER_AUTHORIZATION_TOKEN }
+      : {},
+  });
+  if (!response.ok) {
+    throw new Error(`The container credentials endpoint answered ${response.status}.`);
+  }
+  const credentials = (await response.json()) as ContainerCredentials;
+  if (!credentials.AccessKeyId || !credentials.SecretAccessKey) {
+    throw new Error('The container credentials endpoint answered without credentials.');
+  }
+  return credentials;
+}
+
+function hmac(key: Buffer | string, data: string): Buffer {
+  return createHmac('sha256', key).update(data, 'utf8').digest();
+}
+
+function sha256Hex(value: string): string {
+  return createHash('sha256').update(value, 'utf8').digest('hex');
+}
+
+/**
+ * Signs `GetCallerIdentity` with SigV4, binding the nonce into the signature.
+ *
+ * `SignedHeaders` includes the nonce header deliberately: Oxy refuses an
+ * attestation whose signature does not cover it, because a nonce the signature
+ * does not cover can be swapped by whoever captured the attestation.
+ */
+function signGetCallerIdentity(credentials: ContainerCredentials, nonce: string, now: Date): Record<string, string> {
+  const amzDate = now.toISOString().replace(/[-:]/g, '').replace(/\.\d{3}/, '');
+  const dateStamp = amzDate.slice(0, 8);
+
+  const headers: Record<string, string> = {
+    host: STS_HOST,
+    'x-amz-date': amzDate,
+    [NONCE_HEADER]: nonce,
+  };
+  if (credentials.Token) headers['x-amz-security-token'] = credentials.Token;
+
+  const signedHeaderNames = Object.keys(headers).sort();
+  const canonicalHeaders = signedHeaderNames.map((name) => `${name}:${headers[name]}\n`).join('');
+  const signedHeaders = signedHeaderNames.join(';');
+
+  const canonicalRequest = [
+    'POST',
+    '/',
+    '',
+    canonicalHeaders,
+    signedHeaders,
+    sha256Hex(STS_BODY),
+  ].join('\n');
+
+  const scope = `${dateStamp}/${STS_REGION}/sts/aws4_request`;
+  const stringToSign = ['AWS4-HMAC-SHA256', amzDate, scope, sha256Hex(canonicalRequest)].join('\n');
+
+  const signingKey = hmac(hmac(hmac(hmac(`AWS4${credentials.SecretAccessKey}`, dateStamp), STS_REGION), 'sts'), 'aws4_request');
+  const signature = createHmac('sha256', signingKey).update(stringToSign, 'utf8').digest('hex');
+
+  return {
+    ...headers,
+    authorization:
+      `AWS4-HMAC-SHA256 Credential=${credentials.AccessKeyId}/${scope}, ` +
+      `SignedHeaders=${signedHeaders}, Signature=${signature}`,
+  };
+}
+
+/** The AWS attestation: signed headers, and nothing else. */
+async function awsContainerAttestation(fetchImpl: typeof fetch, nonce: string): Promise<{ headers: Record<string, string> }> {
+  const credentials = await containerCredentials(fetchImpl);
+  return { headers: signGetCallerIdentity(credentials, nonce, new Date()) };
+}
+
+/**
+ * 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 async function requestWorkloadServiceToken(
+  options: WorkloadServiceTokenOptions,
+): Promise<WorkloadServiceToken> {
+  const fetchImpl = options.fetch ?? fetch;
+  const base = options.baseUrl.replace(/\/+$/, '');
+
+  const challengeResponse = await fetchImpl(`${base}/auth/service-token/workload/challenge`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+  });
+  if (!challengeResponse.ok) {
+    throw new Error(`Oxy refused to issue a workload challenge (${challengeResponse.status}).`);
+  }
+  const challenge = unwrap<{ nonce?: string }>(await challengeResponse.json());
+  if (!challenge?.nonce) {
+    throw new Error('Oxy issued a workload challenge with no nonce.');
+  }
+
+  const attestation = await awsContainerAttestation(fetchImpl, challenge.nonce);
+
+  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 }),
+  });
+  if (!tokenResponse.ok) {
+    // The body carries a bounded `reason`; the token never travels on a failure,
+    // so there is nothing here that must not be seen.
+    throw new Error(`Oxy refused the workload attestation (${tokenResponse.status}).`);
+  }
+  const granted = unwrap<Partial<WorkloadServiceToken>>(await tokenResponse.json());
+  if (!granted?.token || typeof granted.expiresIn !== 'number') {
+    throw new Error('Oxy answered the attestation without a usable token.');
+  }
+  return { token: granted.token, expiresIn: granted.expiresIn, appName: granted.appName ?? '' };
+}
+
+/** Oxy wraps successful bodies in `{ data }`; older routes answer flat. */
+function unwrap<T>(body: unknown): T | null {
+  if (typeof body !== 'object' || body === null) return null;
+  const envelope = body as { data?: unknown };
+  return (typeof envelope.data === 'object' && envelope.data !== null ? envelope.data : body) as T;
+}

package/src/session/__tests__/refresh.test.ts

@@ -57,17 +57,23 @@ interface RefreshMockOverrides {
   signInWithSharedIdentity?: OxyServices['signInWithSharedIdentity'];
 }
 
-function makeOxy(overrides: RefreshMockOverrides = {}): { oxy: OxyServices; setTokens: jest.Mock } {
+function makeOxy(
+  overrides: RefreshMockOverrides = {},
+): { oxy: OxyServices; setTokens: jest.Mock; noteRefreshRateLimited: jest.Mock } {
   const setTokens = jest.fn();
+  const noteRefreshRateLimited = jest.fn();
   const oxy = {
     setTokens,
     mintFromDeviceSecret: overrides.mintFromDeviceSecret ?? (async () => MINT),
     signInWithSharedIdentity: overrides.signInWithSharedIdentity ?? (async () => null),
     // The rotating mint runs under the client's process-wide single-flight; the
     // arm reaches for it via `oxy.httpService.runSingleFlightDeviceSecretMint`.
-    httpService: { runSingleFlightDeviceSecretMint: makeMintSingleFlight() },
+    httpService: {
+      runSingleFlightDeviceSecretMint: makeMintSingleFlight(),
+      noteRefreshRateLimited,
+    },
   } as unknown as OxyServices;
-  return { oxy, setTokens };
+  return { oxy, setTokens, noteRefreshRateLimited };
 }
 
 describe('refreshPersistedSession — arm 1 (device-secret mint)', () => {
@@ -179,6 +185,50 @@ describe('refreshPersistedSession — arm 1 (device-secret mint)', () => {
     expect(await store.load()).toEqual(STORED);
     expect(signInWithSharedIdentity).not.toHaveBeenCalled();
   });
+
+  it('KEEPS the store on a 429 and does NOT fall through to shared-key — a rationed mint never judged the secret', async () => {
+    const store = createMemoryAuthStateStore();
+    await store.save(STORED);
+    const signInWithSharedIdentity = jest.fn(async () => null);
+    const { oxy } = makeOxy({
+      mintFromDeviceSecret: async () => {
+        throw Object.assign(new Error('Too many requests'), { status: 429 });
+      },
+      signInWithSharedIdentity,
+    });
+
+    expect(await refreshPersistedSession({ oxy, store, allowSharedKeyFallback: true })).toBeNull();
+    expect(await store.load()).toEqual(STORED);
+    expect(signInWithSharedIdentity).not.toHaveBeenCalled();
+  });
+
+  it('tells HttpService to lengthen the refresh cooldown when the mint is rate limited', async () => {
+    const store = createMemoryAuthStateStore();
+    await store.save(STORED);
+    const { oxy, noteRefreshRateLimited } = makeOxy({
+      mintFromDeviceSecret: async () => {
+        throw Object.assign(new Error('Too many requests'), { status: 429 });
+      },
+    });
+
+    await refreshPersistedSession({ oxy, store, allowSharedKeyFallback: false });
+
+    expect(noteRefreshRateLimited).toHaveBeenCalledTimes(1);
+  });
+
+  it('does NOT lengthen the cooldown for failures the server did not ration', async () => {
+    const store = createMemoryAuthStateStore();
+    await store.save(STORED);
+    const { oxy, noteRefreshRateLimited } = makeOxy({
+      mintFromDeviceSecret: async () => {
+        throw Object.assign(new Error('server'), { status: 500 });
+      },
+    });
+
+    await refreshPersistedSession({ oxy, store, allowSharedKeyFallback: false });
+
+    expect(noteRefreshRateLimited).not.toHaveBeenCalled();
+  });
 });
 
 describe('refreshPersistedSession — arm 2 (native shared-key fallback)', () => {

package/src/session/refresh.ts

@@ -159,6 +159,18 @@ export async function refreshDeviceSecretArm(deps: {
           })
         : await oxy.mintFromDeviceSecret(persisted.deviceId, persisted.deviceSecret);
     } catch (error) {
+      // 429 keeps the credential like any other transient failure — the secret
+      // was never judged — but it must NOT retry on the transient cadence. The
+      // request-driven lanes (request-time preflight, 401 retry) reattempt every
+      // second once the access token is expired, which is 60 mints/min against a
+      // 30/min server budget: the client's own retries then hold the limiter
+      // tripped and the session cannot recover while the app keeps making
+      // requests. Telling HttpService lengthens the next cooldown to one attempt
+      // per limiter window, which lets the budget drain and the session heal.
+      if (extractErrorStatus(error) === 429) {
+        oxy.httpService.noteRefreshRateLimited();
+        return { status: 'transient' };
+      }
       if (extractErrorStatus(error) === 401) {
         // Structural read (not `instanceof Error`): the thrown value can be a
         // plain ApiError-shaped object or come from another realm.