@oxy.so/core 1.5.0 → 1.6.0

package/src/mixins/__tests__/OxyServices.identity.test.ts

@@ -3,9 +3,7 @@
  *
  * Stubs `makeRequest` so the tests run with no network. We assert request shape
  * (method, URL, body, cache options), response unwrapping, the DID derivation,
- * the EXACT signed payload `linkIdentityKey` produces (it must match the
- * server's `JSON.stringify({ action, userId, timestamp })` reconstruction
- * byte-for-byte), and the cache sweep on every mutation.
+ * and the cache sweep on every mutation.
  */
 
 import type { AuthMethodsResponse, DidDocument, SignedRecordEnvelope, VerifiedDomain } from '@oxy.so/contracts';
@@ -129,79 +127,6 @@ describe('OxyServices.identity', () => {
     });
   });
 
-  describe('linkIdentityKey', () => {
-    it('signs the exact server-expected payload and POSTs /auth/link', async () => {
-      jest.spyOn(Date, 'now').mockReturnValue(1700000000000);
-      jest.spyOn(KeyManager, 'getPublicKey').mockResolvedValue('pub-hex');
-      const signSpy = jest.spyOn(SignatureService, 'sign').mockResolvedValue('sig-hex');
-      makeRequestSpy.mockResolvedValue({ success: true, message: 'Identity linked successfully' });
-
-      const result = await oxy.linkIdentityKey();
-
-      // The signed message MUST match the server's reconstruction byte-for-byte:
-      // JSON.stringify({ action, userId, timestamp }) in that key order.
-      const expectedMessage = JSON.stringify({
-        action: 'link_identity',
-        userId: 'user-123',
-        timestamp: 1700000000000,
-      });
-      expect(signSpy).toHaveBeenCalledWith(expectedMessage);
-      expect(expectedMessage).toBe(
-        '{"action":"link_identity","userId":"user-123","timestamp":1700000000000}',
-      );
-
-      expect(makeRequestSpy).toHaveBeenCalledWith(
-        'POST',
-        '/auth/link',
-        { type: 'identity', publicKey: 'pub-hex', signature: 'sig-hex', timestamp: 1700000000000 },
-        expect.objectContaining({ cache: false }),
-      );
-      expect(result).toEqual({ success: true, message: 'Identity linked successfully' });
-    });
-
-    it('sweeps /users/me, auth methods, domains and the DID cache after linking', async () => {
-      jest.spyOn(KeyManager, 'getPublicKey').mockResolvedValue('pub-hex');
-      jest.spyOn(SignatureService, 'sign').mockResolvedValue('sig-hex');
-      makeRequestSpy.mockResolvedValue({ success: true, message: 'ok' });
-
-      await oxy.linkIdentityKey();
-
-      expect(clearPrefixSpy).toHaveBeenCalledWith('GET:/users/me');
-      expect(clearEntrySpy).toHaveBeenCalledWith('GET:/auth/methods');
-      expect(clearEntrySpy).toHaveBeenCalledWith('GET:/identity/domains');
-      expect(clearEntrySpy).toHaveBeenCalledWith('GET:/u/user-123/did.json');
-    });
-
-    it('throws (no network) when the device has no identity', async () => {
-      jest.spyOn(KeyManager, 'getPublicKey').mockResolvedValue(null);
-      await expect(oxy.linkIdentityKey()).rejects.toThrow(/No identity found/);
-      expect(makeRequestSpy).not.toHaveBeenCalled();
-    });
-
-    it('throws when no user is authenticated', async () => {
-      jest.spyOn(oxy, 'getCurrentUserId').mockReturnValue(null);
-      jest.spyOn(KeyManager, 'getPublicKey').mockResolvedValue('pub-hex');
-      await expect(oxy.linkIdentityKey()).rejects.toThrow(/No authenticated user/);
-      expect(makeRequestSpy).not.toHaveBeenCalled();
-    });
-  });
-
-  describe('unlinkAuthMethod', () => {
-    it('DELETEs /auth/link/:type and sweeps cache', async () => {
-      makeRequestSpy.mockResolvedValue({ success: true, message: 'identity auth unlinked successfully' });
-
-      await oxy.unlinkAuthMethod('identity');
-
-      expect(makeRequestSpy).toHaveBeenCalledWith(
-        'DELETE',
-        '/auth/link/identity',
-        undefined,
-        expect.objectContaining({ cache: false }),
-      );
-      expect(clearEntrySpy).toHaveBeenCalledWith('GET:/u/user-123/did.json');
-    });
-  });
-
   describe('removePasskey', () => {
     it('DELETEs /auth/link/webauthn/:credentialID and sweeps cache', async () => {
       makeRequestSpy.mockResolvedValue({ success: true, message: 'Passkey unlinked successfully' });

package/src/mixins/index.ts

@@ -35,7 +35,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
@@ -75,7 +74,6 @@ type AllMixinInstances =
   & 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>>>;
 
 /**
@@ -169,7 +167,6 @@ const MIXIN_PIPELINE: MixinFunction[] = [
 
     // Device-to-device identity transfer ("add a device"): E2E-encrypted key
     // clone over a short-lived relay (b3 Feature 2).
-    OxyServicesDeviceTransferMixin,
 
     // Utility (last, can use all above)
     OxyServicesUtilityMixin,

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

@@ -198,6 +198,21 @@ function expoExportHtml(body = EXPO_HYDRATE_SCRIPT): string {
   ].join('');
 }
 
+describe('@oxy.so/core/server buildOxyPagesHeaders on a sensitive origin (ADR 0024 D1)', () => {
+  it('removes the Cloudflare Insights beacon from script-src and connect-src, and nothing else', () => {
+    const csp = (block: string) => block.split('\n').find((line) => line.includes('Content-Security-Policy')) ?? '';
+    const normal = csp(buildOxyPagesHeaders({ csp: { connectSrc: ['https://example.test'] } }));
+    const sensitive = csp(buildOxyPagesHeaders({ csp: { connectSrc: ['https://example.test'] }, sensitive: true }));
+
+    expect(normal).toContain('static.cloudflareinsights.com');
+    expect(sensitive).not.toContain('cloudflareinsights.com');
+    expect(sensitive).toContain("script-src 'self'");
+    expect(sensitive).toContain('https://example.test');
+    expect(sensitive).toContain('https://api.oxy.so');
+    expect(sensitive).toContain("frame-ancestors 'none'");
+  });
+});
+
 describe('@oxy.so/core/server extractInlineScripts', () => {
   it('returns inline bodies and skips external scripts', () => {
     expect(extractInlineScripts(expoExportHtml())).toEqual([EXPO_HYDRATE_SCRIPT]);

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/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.