@oxy.so/core 1.5.1 → 1.6.1

package/dist/esm/server/workloadIdentity.js

@@ -0,0 +1,166 @@
+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';
+/**
+ * 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 = process.env) {
+    return Boolean(env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI || env.AWS_CONTAINER_CREDENTIALS_FULL_URI);
+}
+async function containerCredentials(fetchImpl) {
+    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;
+    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());
+    if (!credentials.AccessKeyId || !credentials.SecretAccessKey) {
+        throw new Error('The container credentials endpoint answered without credentials.');
+    }
+    return credentials;
+}
+function hmac(key, data) {
+    return createHmac('sha256', key).update(data, 'utf8').digest();
+}
+function sha256Hex(value) {
+    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, nonce, now) {
+    const amzDate = now.toISOString().replace(/[-:]/g, '').replace(/\.\d{3}/, '');
+    const dateStamp = amzDate.slice(0, 8);
+    const headers = {
+        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, nonce) {
+    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) {
+    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(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(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(body) {
+    if (typeof body !== 'object' || body === null)
+        return null;
+    const envelope = body;
+    return (typeof envelope.data === 'object' && envelope.data !== null ? envelope.data : body);
+}

package/dist/esm/session/refresh.js

@@ -72,6 +72,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.