@mi9-identity/token-client 1.0.0

package/dist/client.js

@@ -0,0 +1,485 @@
+import { drainBody } from './drain-body.js';
+import { claimGcpCredential } from './claim.js';
+import { resolveRequestId } from './request-id.js';
+import { isEmpty, isNull, isString, isUndefined } from './type-guards.js';
+import { computeBackoffDelayMs, DEFAULT_BACKOFF, parseRetryAfterMs } from './backoff.js';
+import { deadlineSignal, remainingMs, sleepOrThrowIfDeadlineExceeded, startDeadline } from './deadline.js';
+import { DEFAULT_REFRESH_LEAD_TIME_MS, DEFAULT_REQUEST_ID_HEADER, MAX_RETRIES, NOOP_LOGGER } from './token-client.constants.js';
+import { ConfigurationError, LazyClaimError, ProvisioningError, ResponseShapeError, RevocationError, TransientError } from './errors.js';
+import { credentialMeResponseSchema, oauthErrorSchema, tokenResponseSchema } from './schemas.js';
+/**
+ * Detect the rotation signal in a `/oauth/token` success response. ADR-7 fuses
+ * the body (`credentialRotated`) and header (`X-Mi9-Credential-Rotated`) signals
+ * — either one trips pickup.
+ *
+ * @param { TokenResponse } body The parsed token-response body.
+ * @param { Headers } headers The response headers.
+ * @returns { boolean } `true` when the issuer signalled rotation via either channel.
+ */
+const isRotationSignal = (body, headers) => {
+    if (body.credentialRotated === true) {
+        return true;
+    }
+    const headerValue = headers.get('x-mi9-credential-rotated');
+    return isString(headerValue) && headerValue.toLowerCase() === 'true';
+};
+/**
+ * Best-effort extract of the `error` field from an OAuth error envelope; falls
+ * back to `'unknown'` when the body is missing or malformed.
+ *
+ * @param { Response } response The 4xx fetch response.
+ * @returns { Promise<string> } The `error` field value, or `'unknown'`.
+ */
+const readOAuthErrorMessage = async (response) => {
+    const oauthErr = oauthErrorSchema.safeParse(await response.json().catch(() => ({})));
+    return oauthErr.success ? (oauthErr.data.error ?? 'unknown') : 'unknown';
+};
+/**
+ * Parse a successful `/oauth/token` 2xx body and bundle the rotation signal so
+ * the retry loop can return a single value.
+ *
+ * @param { Response } response The successful fetch response.
+ * @returns { Promise<{ body: TokenResponse; rotated: boolean }> } Parsed body plus the rotation flag.
+ * @throws { ResponseShapeError } If the body fails JSON parsing or schema validation.
+ */
+const parseTokenSuccess = async (response) => {
+    let json;
+    try {
+        json = await response.json();
+    }
+    catch (err) {
+        throw new ResponseShapeError(`Failed to parse /oauth/token JSON body: ${String(err)}`);
+    }
+    const parsed = tokenResponseSchema.safeParse(json);
+    if (!parsed.success) {
+        throw new ResponseShapeError(`Unexpected /oauth/token response shape: ${parsed.error.message}`);
+    }
+    return { body: parsed.data, rotated: isRotationSignal(parsed.data, response.headers) };
+};
+/**
+ * Build a token client bound to one consumer credential. The returned object
+ * is safe to share across the lifetime of the calling process — it manages
+ * its own in-memory cache, single-flight refresh, and rotation pickup.
+ *
+ * @param { TokenClientOptions } opts Client configuration (endpoints, credentials, lead time, retry policy, hooks).
+ * @returns { TokenClient } The configured token client (`acquireToken`, `forceRefresh`, `close`).
+ */
+export const createTokenClient = (opts) => {
+    if (isEmpty(opts.audience)) {
+        throw new ConfigurationError('createTokenClient: `audience` must be a non-empty string or array of strings');
+    }
+    const gcpEnabled = !isUndefined(opts.idTokenProvider);
+    // Classic mode carries a static credential; GCP lazy-claim mode bootstraps
+    // it on first use, so the credential fields are required only without a provider.
+    // The discriminated union already rejects this at compile time — this guard
+    // catches a caller that reached the runtime through an `any` or a JS import.
+    if (!gcpEnabled && (isEmpty(opts.clientId) || isEmpty(opts.clientSecret))) {
+        throw new ConfigurationError('createTokenClient: `clientId` and `clientSecret` are required unless `idTokenProvider` is set');
+    }
+    const log = opts.logger ?? NOOP_LOGGER;
+    const fetchImpl = opts.fetch ?? fetch;
+    const refreshLeadTimeMs = opts.refreshLeadTimeMs ?? DEFAULT_REFRESH_LEAD_TIME_MS;
+    const requestIdHeader = opts.requestIdHeader ?? DEFAULT_REQUEST_ID_HEADER;
+    const backoff = opts.backoff ?? DEFAULT_BACKOFF;
+    const state = {
+        clientId: opts.clientId ?? '',
+        secret: opts.clientSecret ?? '',
+        cached: undefined,
+        inflightRefresh: undefined,
+        inflightPickup: undefined,
+        closed: false,
+    };
+    const ensureOpen = () => {
+        if (state.closed) {
+            throw new Error('TokenClient is closed');
+        }
+    };
+    const buildHeaders = (extra) => ({
+        accept: 'application/json',
+        'content-type': 'application/json',
+        [requestIdHeader]: resolveRequestId(opts.requestId),
+        ...extra,
+    });
+    const postJson = async (url, body, headers, signal) => {
+        const init = {
+            method: 'POST',
+            headers: buildHeaders(headers),
+            body: JSON.stringify(body),
+        };
+        if (!isUndefined(signal)) {
+            init.signal = signal;
+        }
+        return fetchImpl(url, init);
+    };
+    /**
+     * Build the JSON payload for `/oauth/token`. `audience` is forwarded
+     * verbatim — strings, one-element arrays, and multi-element arrays all pass
+     * through unchanged (no collapse). Omits `scope` entirely when the caller
+     * did not configure one.
+     *
+     * @returns { TokenRequestBody } The request body to POST.
+     */
+    const buildTokenRequestBody = () => {
+        const body = {
+            grantType: 'client_credentials',
+            clientId: state.clientId,
+            clientSecret: state.secret,
+            audience: opts.audience,
+        };
+        if (!isUndefined(opts.scope)) {
+            body.scope = opts.scope;
+        }
+        return body;
+    };
+    /**
+     * Map a non-2xx `/oauth/token` response to either a terminal throw (401
+     * revocation, 403 unauthorized audience, 404 not-provisioned, other) or a
+     * transient outcome the retry loop should sleep on.
+     *
+     * @param { Response } response The non-2xx fetch response.
+     * @param { number } attempt Zero-indexed retry attempt number.
+     * @returns { Promise<{ delayMs: number; transient: TransientError }> } Sleep delay and the transient error to remember.
+     * @throws { RevocationError } On 401.
+     * @throws { ConfigurationError } On 403 (`invalid_target` — audience not authorized for this credential).
+     * @throws { ProvisioningError } On 404.
+     * @throws { Error } On any other non-transient status.
+     */
+    const handleTokenErrorResponse = async (response, attempt) => {
+        if (response.status === 401) {
+            throw new RevocationError(`credential rejected by /oauth/token: ${await readOAuthErrorMessage(response)}`);
+        }
+        if (response.status === 403) {
+            throw new ConfigurationError(`audience rejected by /oauth/token: ${await readOAuthErrorMessage(response)}`);
+        }
+        if (response.status === 404) {
+            await drainBody(response);
+            throw new ProvisioningError('credential not provisioned (404 from /oauth/token)');
+        }
+        if (response.status === 429 || response.status >= 500) {
+            const retryAfter = parseRetryAfterMs(response.headers.get('retry-after'), backoff) ?? computeBackoffDelayMs(backoff, attempt);
+            await drainBody(response);
+            const transient = new TransientError(`/oauth/token returned ${String(response.status)}`);
+            log.warn({ attempt, status: response.status, retryAfterMs: retryAfter }, 'token-client.transient');
+            return { delayMs: retryAfter, transient };
+        }
+        throw new Error(`/oauth/token returned ${String(response.status)}: ${await readOAuthErrorMessage(response)}`);
+    };
+    /**
+     * One round-trip to `/oauth/token` for the configured consumer audience(s).
+     * Retries on transient failures per the backoff policy; 401/404 surface
+     * as terminal errors.
+     *
+     * @param { Deadline | undefined } deadline Active wall-clock budget for the whole claim+mint chain, or undefined when `opts.deadlineMs` is unset.
+     * @returns { Promise<{ body: TokenResponse; rotated: boolean }> } Parsed body plus the rotation flag.
+     * @throws { TransientError } When retries are exhausted, or when `deadline` elapses before a retry.
+     */
+    const requestToken = async (deadline) => {
+        let lastTransient;
+        for (let attempt = 0; attempt <= MAX_RETRIES; attempt += 1) {
+            ensureOpen();
+            let response;
+            try {
+                response = await postJson(opts.tokenEndpoint, buildTokenRequestBody(), undefined, deadlineSignal(deadline));
+            }
+            catch (err) {
+                lastTransient = new TransientError('Network failure calling /oauth/token', { cause: err });
+                log.warn({ attempt, err: String(err) }, 'token-client.network_error');
+                await sleepOrThrowIfDeadlineExceeded(deadline, computeBackoffDelayMs(backoff, attempt), '/oauth/token');
+                continue;
+            }
+            if (response.ok) {
+                return parseTokenSuccess(response);
+            }
+            const { delayMs, transient } = await handleTokenErrorResponse(response, attempt);
+            lastTransient = transient;
+            await sleepOrThrowIfDeadlineExceeded(deadline, delayMs, '/oauth/token');
+        }
+        /* v8 ignore next -- defensive; loop runs at least once with MAX_RETRIES > 0 so lastTransient is always assigned */
+        throw lastTransient ?? new TransientError('exhausted retries calling /oauth/token');
+    };
+    /**
+     * Verify every configured audience is covered by the just-claimed
+     * credential's `authorizedAudiences`. Without this, a caller configured for
+     * an audience the credential does not authorize only learns about the gap
+     * from a 403 `invalid_target` on the very next mint — this fails fast,
+     * right after the claim, and names both sets so the operator can see the
+     * mismatch immediately.
+     *
+     * @param { readonly string[] } authorizedAudiences The claimed credential's `authorizedAudiences`.
+     * @returns { void } Nothing — throws on mismatch.
+     * @throws { LazyClaimError } When a configured audience is absent from `authorizedAudiences`.
+     */
+    const assertAudienceAuthorized = (authorizedAudiences) => {
+        const configuredAudiences = isString(opts.audience) ? [opts.audience] : opts.audience;
+        const unauthorized = configuredAudiences.filter((audience) => !authorizedAudiences.includes(audience));
+        if (isEmpty(unauthorized)) {
+            return;
+        }
+        throw new LazyClaimError(`configured audience(s) [${configuredAudiences.join(', ')}] not authorized for claimed credential (authorizedAudiences: [${authorizedAudiences.join(', ')}])`);
+    };
+    /**
+     * (Re)obtain this client's credential via the Tier-1 GCP lazy-claim
+     * (`POST /credentials/me`, `grantType: gcp_identity`) and swap the new
+     * `clientId` + secret into in-memory state. Runs inside the single-flight
+     * refresh promise (so it is coalesced with minting) and never fires
+     * `onSecretRotated` — Tier-1 credentials are held in memory and re-claimed on
+     * demand, not persisted.
+     *
+     * @param { Deadline | undefined } deadline Active wall-clock budget for the whole claim+mint chain, or undefined when `opts.deadlineMs` is unset. The claim receives whatever remains of it as its own `deadlineMs`.
+     * @returns { Promise<void> } Resolves once the freshly-claimed credential is in memory.
+     * @throws { LazyClaimError } The ID token was rejected (401/403), the provider threw, or the claimed credential's `authorizedAudiences` does not cover the configured `audience`.
+     * @throws { ProvisioningError } On 404 — the credential is not provisioned yet.
+     * @throws { TransientError } When `deadline` elapses before the claim completes.
+     */
+    const lazyClaim = async (deadline) => {
+        /* v8 ignore next 3 -- defensive; lazyClaim is only reached when gcpEnabled, i.e. idTokenProvider is set */
+        if (isUndefined(opts.idTokenProvider)) {
+            throw new LazyClaimError('no idTokenProvider configured for GCP lazy-claim');
+        }
+        const claim = await claimGcpCredential({
+            credentialEndpoint: opts.credentialEndpoint,
+            idTokenProvider: opts.idTokenProvider,
+            fetch: fetchImpl,
+            backoff,
+            requestIdHeader,
+            logger: log,
+            ...(isUndefined(opts.retailerCode) ? {} : { retailerCode: opts.retailerCode }),
+            ...(isUndefined(opts.requestId) ? {} : { requestId: opts.requestId }),
+            ...(isUndefined(deadline) ? {} : { deadlineMs: remainingMs(deadline) }),
+        });
+        assertAudienceAuthorized(claim.audience);
+        state.clientId = claim.clientId;
+        state.secret = claim.clientSecret;
+        log.info({ event: 'credential_claimed' }, 'token-client.credential_claimed');
+    };
+    /**
+     * Mint via `/oauth/token`. In GCP mode a 401 (revoked or force-revoked
+     * secret) triggers exactly one lazy re-claim followed by one retry; a second
+     * 401 is terminal (`RevocationError`) so a permanently rejected credential
+     * cannot loop. In classic mode a 401 surfaces unchanged.
+     *
+     * @param { Deadline | undefined } deadline Active wall-clock budget for the whole claim+mint chain, or undefined when `opts.deadlineMs` is unset. The SAME budget is reused across the initial mint, the re-claim, and the retry mint — it is never reset mid-chain.
+     * @returns { Promise<{ body: TokenResponse; rotated: boolean }> } Parsed body plus the rotation flag.
+     */
+    const mintReclaiming = async (deadline) => {
+        try {
+            return await requestToken(deadline);
+        }
+        catch (err) {
+            if (!gcpEnabled || !(err instanceof RevocationError)) {
+                throw err;
+            }
+            log.info({ event: 'reclaiming_after_401' }, 'token-client.reclaiming_after_401');
+            await lazyClaim(deadline);
+            return requestToken(deadline);
+        }
+    };
+    /**
+     * Call `/credentials/me grantType=jwt` to fetch the new client secret.
+     * Reuses the just-acquired consumer-aud access token as the bearer — the
+     * issuer's verifier accepts any audience in the credential's
+     * `authorizedAudiences`, so a second `/oauth/token` mint is no longer
+     * required.
+     *
+     * Status branching: 204 → `null` (rotation already acknowledged — nothing
+     * to deliver), 2xx → the new secret, 401 → `RevocationError`, 429 / 5xx →
+     * `TransientError`. No 404 branch — issuer surfaces `not_found` / `revoked`
+     * as 401 `invalid_client` from `grantType=jwt`, not 404.
+     *
+     * @param { string } accessToken The just-acquired consumer-aud JWT (with `authClass: pending_secret`) carried by the rotated `/oauth/token` response.
+     * @returns { Promise<string | null> } The new client secret, or `null` when the issuer answered 204 (already acknowledged — no-op).
+     * @throws { ResponseShapeError } If a 2xx body fails JSON parsing or schema validation.
+     * @throws { RevocationError } On 401.
+     * @throws { TransientError } On 429 / 5xx.
+     * @throws { Error } On any other non-2xx status.
+     */
+    const pickUpRotatedSecret = async (accessToken) => {
+        const response = await postJson(opts.credentialEndpoint, { grantType: 'jwt' }, { authorization: `Bearer ${accessToken}` });
+        // 204 No Content: another instance (or an earlier pickup) already
+        // acknowledged this rotation, so there is no new secret to deliver. A
+        // no-op, not a shape error — the 2xx branch below would try to parse an
+        // empty body and wrongly throw ResponseShapeError.
+        if (response.status === 204) {
+            await drainBody(response);
+            return null;
+        }
+        if (response.ok) {
+            let json;
+            try {
+                json = await response.json();
+            }
+            catch (err) {
+                throw new ResponseShapeError(`Failed to parse /credentials/me JSON body: ${String(err)}`);
+            }
+            const parsed = credentialMeResponseSchema.safeParse(json);
+            if (!parsed.success) {
+                throw new ResponseShapeError(`Unexpected /credentials/me response shape: ${parsed.error.message}`);
+            }
+            const next = parsed.data;
+            return next.clientSecret;
+        }
+        if (response.status === 401) {
+            const oauthErr = oauthErrorSchema.safeParse(await response.json().catch(() => ({})));
+            throw new RevocationError(`credential rejected by /credentials/me: ${oauthErr.success ? (oauthErr.data.error ?? 'unknown') : 'unknown'}`);
+        }
+        if (response.status === 429 || response.status >= 500) {
+            await drainBody(response);
+            throw new TransientError(`/credentials/me returned ${String(response.status)}`);
+        }
+        await drainBody(response);
+        throw new Error(`/credentials/me returned ${String(response.status)}`);
+    };
+    /**
+     * Pick up a rotated secret in the BACKGROUND. Detached from `acquireToken`
+     * on purpose: the access token just minted by `/oauth/token` is a valid
+     * product token regardless of whether this secondary `/credentials/me`
+     * call succeeds, so a pickup failure must never reject the caller or
+     * discard that token. Single-flight via `state.inflightPickup`; the
+     * rotation signal keeps firing on subsequent mints until the issuer records
+     * the pickup, so a failed attempt is simply retried on the next refresh.
+     *
+     * Persist contract: the new secret is written to in-memory state BEFORE
+     * `onSecretRotated` runs, so a persist-callback throw cannot strand the
+     * client on the old secret (the issuer has recorded the pickup and will
+     * revoke the old secret after the grace window). The throw is logged and
+     * swallowed; the application reconciles its durable store on restart.
+     *
+     * @param { string } accessToken The just-minted consumer-aud JWT used as the pickup bearer.
+     * @returns { void } Nothing — the work runs detached.
+     */
+    const startBackgroundPickup = (accessToken) => {
+        if (!isUndefined(state.inflightPickup)) {
+            return;
+        }
+        const task = (async () => {
+            const newSecret = await pickUpRotatedSecret(accessToken);
+            if (isNull(newSecret)) {
+                log.info({ event: 'rotation_already_acknowledged' }, 'token-client.rotation_already_acknowledged');
+                return;
+            }
+            state.secret = newSecret;
+            if (!isUndefined(opts.onSecretRotated)) {
+                try {
+                    await opts.onSecretRotated(newSecret);
+                }
+                catch (err) {
+                    log.error({ err: String(err) }, 'token-client.persist_failed');
+                }
+            }
+        })()
+            .catch((err) => {
+            log.warn({ err: String(err) }, 'token-client.rotation_pickup_failed');
+        })
+            .finally(() => {
+            state.inflightPickup = undefined;
+        });
+        state.inflightPickup = task;
+    };
+    /**
+     * Internal refresh path. Single-flight via `state.inflightRefresh` so a
+     * burst of concurrent `acquireToken` calls funnels through one network
+     * round-trip. The minted token is cached and returned immediately; a
+     * rotation signal kicks off a detached background pickup
+     * (`startBackgroundPickup`) rather than blocking the caller on the
+     * secondary `/credentials/me` call.
+     *
+     * `opts.deadlineMs` is read fresh here, at the top of the chain this
+     * single-flight refresh drives — so the wall-clock budget spans claim +
+     * mint + re-claim + retry mint as one chain, and every refresh gets its
+     * own budget rather than sharing (or being starved by) a prior one.
+     *
+     * @returns { Promise<AccessToken> } The newly-minted (and cached) access token.
+     */
+    const doRefresh = async () => {
+        const deadline = startDeadline(opts.deadlineMs);
+        if (gcpEnabled && state.secret === '') {
+            await lazyClaim(deadline);
+        }
+        const result = await mintReclaiming(deadline);
+        const expiresInMs = result.body.expiresIn * 1_000;
+        if (expiresInMs <= refreshLeadTimeMs) {
+            log.warn({ expiresInMs, refreshLeadTimeMs }, 'token-client.lead_time_exceeds_ttl');
+        }
+        const token = { token: result.body.accessToken, expiresAt: Date.now() + expiresInMs };
+        state.cached = token;
+        if (result.rotated) {
+            log.info({ event: 'credential_rotation_signal' }, 'token-client.rotation_signaled');
+            startBackgroundPickup(result.body.accessToken);
+        }
+        return token;
+    };
+    /**
+     * Refresh with single-flight. Concurrent callers wait on the same promise so
+     * only one round-trip to the issuer happens when the cache is stale. The
+     * first caller that notices the stale cache kicks off the refresh; others
+     * that arrive while it's in-flight wait for the result and get the fresh token
+     * when it resolves.
+     *
+     * @returns { Promise<AccessToken> } The newly-minted (and cached) access token.
+     */
+    const refreshSingleFlight = () => {
+        if (!isUndefined(state.inflightRefresh)) {
+            return state.inflightRefresh;
+        }
+        const promise = doRefresh().finally(() => {
+            state.inflightRefresh = undefined;
+        });
+        state.inflightRefresh = promise;
+        return promise;
+    };
+    /**
+     * Acquire the cached token if it's fresh, or refresh it if it's stale.
+     *
+     * @returns { Promise<AccessToken> } The cached or newly-minted access token.
+     */
+    const acquireToken = async () => {
+        ensureOpen();
+        const cached = state.cached;
+        if (!isUndefined(cached) && Date.now() < cached.expiresAt - refreshLeadTimeMs) {
+            return cached;
+        }
+        return refreshSingleFlight();
+    };
+    /**
+     * Discard the cached token and mint a fresh one. Intentionally coalesces
+     * with an in-flight refresh: when one is already running it returns that
+     * same promise rather than starting a second concurrent mint, so a
+     * `forceRefresh` racing an automatic refresh still funnels through one
+     * `/oauth/token` round-trip (single-flight via `state.inflightRefresh`).
+     *
+     * @returns { Promise<AccessToken> } The freshly-minted (and cached) access token.
+     */
+    const forceRefresh = async () => {
+        ensureOpen();
+        state.cached = undefined;
+        return refreshSingleFlight();
+    };
+    /**
+     * Close the client and clean up resources. After calling this, the client is
+     * permanently closed and all methods throw. This clears the cache and any
+     * in-flight refresh so that no future calls to `acquireToken` or `forceRefresh`
+     * can succeed. Call this on graceful shutdown to prevent a mid-refresh promise
+     * from outliving the surrounding service.
+     */
+    const close = () => {
+        state.closed = true;
+        state.cached = undefined;
+        state.inflightRefresh = undefined;
+        state.inflightPickup = undefined;
+    };
+    return { acquireToken, forceRefresh, close };
+};
+/**
+ * Build a Tier-1 GCP token client that lazy-claims its credential on first use
+ * (via `POST /credentials/me` `grantType=gcp_identity`) and silently re-claims
+ * when a mint is rejected with 401. A thin wrapper over `createTokenClient` with
+ * `idTokenProvider` required and `clientId` / `clientSecret` omitted (both are
+ * bootstrapped by the first claim). `idTokenProvider` is called with the
+ * credential endpoint URL — the issuer-pinned `aud` — and must return a fresh
+ * Google ID token each call.
+ *
+ * @param { GcpTokenClientOptions } opts GCP client configuration (endpoints, audience, ID-token provider, retry policy).
+ * @returns { TokenClient } The configured token client (`acquireToken`, `forceRefresh`, `close`).
+ */
+export const createGcpTokenClient = (opts) => createTokenClient(opts);
+//# sourceMappingURL=client.js.map

package/dist/deadline.d.ts

@@ -0,0 +1,78 @@
+import { TransientError } from './errors.js';
+/**
+ * Wall-clock budget for one claim+mint(+re-claim+mint) chain. `startDeadline`
+ * computes `expiresAt` once at the top of the public entry point so the
+ * budget spans every step of the chain instead of resetting at each retry,
+ * sleep, or re-claim.
+ */
+export interface Deadline {
+    readonly budgetMs: number;
+    readonly expiresAt: number;
+}
+/**
+ * Start a wall-clock budget for one call, or return undefined when the
+ * caller configured none — undefined preserves today's unbounded-retry
+ * behaviour exactly, since every helper below is a no-op for it.
+ *
+ * @param { number | undefined } deadlineMs Configured wall-clock budget in ms.
+ * @returns { Deadline | undefined } The started budget, or undefined when unset.
+ */
+export declare const startDeadline: (deadlineMs: number | undefined) => Deadline | undefined;
+/**
+ * Milliseconds left before `deadline` expires, floored at 0.
+ *
+ * @param { Deadline } deadline The active budget.
+ * @returns { number } Remaining ms, floored at 0.
+ */
+export declare const remainingMs: (deadline: Deadline) => number;
+/**
+ * Milliseconds elapsed since `deadline` started, for the deadline-exceeded
+ * error message.
+ *
+ * @param { Deadline } deadline The active budget.
+ * @returns { number } Elapsed ms since the budget started.
+ */
+export declare const elapsedMs: (deadline: Deadline) => number;
+/**
+ * True when sleeping `delayMs` from now would meet or exceed `deadline` — the
+ * caller must throw instead of sleeping in that case rather than blocking
+ * past the configured budget.
+ *
+ * @param { Deadline } deadline The active budget.
+ * @param { number } delayMs The backoff delay about to be slept.
+ * @returns { boolean } True when the upcoming sleep would exceed the budget.
+ */
+export declare const sleepWouldExceedDeadline: (deadline: Deadline, delayMs: number) => boolean;
+/**
+ * An `AbortSignal` that fires when `deadline` expires, or undefined when no
+ * deadline is configured — pass this straight to `fetch` so a single stalled
+ * socket cannot outlive the budget either.
+ *
+ * @param { Deadline | undefined } deadline The active budget, or undefined when none is configured.
+ * @returns { AbortSignal | undefined } The timeout signal, or undefined when unconfigured.
+ */
+export declare const deadlineSignal: (deadline: Deadline | undefined) => AbortSignal | undefined;
+/**
+ * Build the deadline-exceeded `TransientError`, naming the configured budget
+ * and the elapsed time so a caller's logs show why the chain stopped short of
+ * the normal retry ceiling. The caller's documented "surface upstream as 503
+ * and retry later" action (see `TransientError`) still applies unchanged.
+ *
+ * @param { Deadline } deadline The exceeded budget.
+ * @param { string } context Short label for which call the deadline stopped (e.g. `'/oauth/token'`, `'/credentials/me (gcp_identity)'`).
+ * @returns { TransientError } The error to throw in place of sleeping.
+ */
+export declare const deadlineExceededError: (deadline: Deadline, context: string) => TransientError;
+/**
+ * Sleep `delayMs` before the next retry, or throw the deadline-exceeded error
+ * when that sleep would cross `deadline` — stopping the retry loop rather
+ * than blocking past the caller's configured budget.
+ *
+ * @param { Deadline | undefined } deadline Active wall-clock budget, or undefined when none is configured (preserves unbounded retry).
+ * @param { number } delayMs The backoff delay computed for this retry.
+ * @param { string } context Short label naming which call the deadline stopped, forwarded to `deadlineExceededError`.
+ * @returns { Promise<void> } Resolves after sleeping `delayMs`.
+ * @throws { TransientError } When `deadline` is configured and sleeping `delayMs` would meet or exceed it.
+ */
+export declare const sleepOrThrowIfDeadlineExceeded: (deadline: Deadline | undefined, delayMs: number, context: string) => Promise<void>;
+//# sourceMappingURL=deadline.d.ts.map

package/dist/deadline.js

@@ -0,0 +1,75 @@
+import { sleep } from './backoff.js';
+import { TransientError } from './errors.js';
+import { isUndefined } from './type-guards.js';
+/**
+ * Start a wall-clock budget for one call, or return undefined when the
+ * caller configured none — undefined preserves today's unbounded-retry
+ * behaviour exactly, since every helper below is a no-op for it.
+ *
+ * @param { number | undefined } deadlineMs Configured wall-clock budget in ms.
+ * @returns { Deadline | undefined } The started budget, or undefined when unset.
+ */
+export const startDeadline = (deadlineMs) => isUndefined(deadlineMs) ? undefined : { budgetMs: deadlineMs, expiresAt: Date.now() + deadlineMs };
+/**
+ * Milliseconds left before `deadline` expires, floored at 0.
+ *
+ * @param { Deadline } deadline The active budget.
+ * @returns { number } Remaining ms, floored at 0.
+ */
+export const remainingMs = (deadline) => Math.max(0, deadline.expiresAt - Date.now());
+/**
+ * Milliseconds elapsed since `deadline` started, for the deadline-exceeded
+ * error message.
+ *
+ * @param { Deadline } deadline The active budget.
+ * @returns { number } Elapsed ms since the budget started.
+ */
+export const elapsedMs = (deadline) => deadline.budgetMs - remainingMs(deadline);
+/**
+ * True when sleeping `delayMs` from now would meet or exceed `deadline` — the
+ * caller must throw instead of sleeping in that case rather than blocking
+ * past the configured budget.
+ *
+ * @param { Deadline } deadline The active budget.
+ * @param { number } delayMs The backoff delay about to be slept.
+ * @returns { boolean } True when the upcoming sleep would exceed the budget.
+ */
+export const sleepWouldExceedDeadline = (deadline, delayMs) => delayMs >= remainingMs(deadline);
+/**
+ * An `AbortSignal` that fires when `deadline` expires, or undefined when no
+ * deadline is configured — pass this straight to `fetch` so a single stalled
+ * socket cannot outlive the budget either.
+ *
+ * @param { Deadline | undefined } deadline The active budget, or undefined when none is configured.
+ * @returns { AbortSignal | undefined } The timeout signal, or undefined when unconfigured.
+ */
+export const deadlineSignal = (deadline) => (isUndefined(deadline) ? undefined : AbortSignal.timeout(remainingMs(deadline)));
+/**
+ * Build the deadline-exceeded `TransientError`, naming the configured budget
+ * and the elapsed time so a caller's logs show why the chain stopped short of
+ * the normal retry ceiling. The caller's documented "surface upstream as 503
+ * and retry later" action (see `TransientError`) still applies unchanged.
+ *
+ * @param { Deadline } deadline The exceeded budget.
+ * @param { string } context Short label for which call the deadline stopped (e.g. `'/oauth/token'`, `'/credentials/me (gcp_identity)'`).
+ * @returns { TransientError } The error to throw in place of sleeping.
+ */
+export const deadlineExceededError = (deadline, context) => new TransientError(`${context}: deadlineMs budget of ${String(deadline.budgetMs)}ms exceeded after ${String(elapsedMs(deadline))}ms elapsed — stopping instead of retrying past the deadline`);
+/**
+ * Sleep `delayMs` before the next retry, or throw the deadline-exceeded error
+ * when that sleep would cross `deadline` — stopping the retry loop rather
+ * than blocking past the caller's configured budget.
+ *
+ * @param { Deadline | undefined } deadline Active wall-clock budget, or undefined when none is configured (preserves unbounded retry).
+ * @param { number } delayMs The backoff delay computed for this retry.
+ * @param { string } context Short label naming which call the deadline stopped, forwarded to `deadlineExceededError`.
+ * @returns { Promise<void> } Resolves after sleeping `delayMs`.
+ * @throws { TransientError } When `deadline` is configured and sleeping `delayMs` would meet or exceed it.
+ */
+export const sleepOrThrowIfDeadlineExceeded = async (deadline, delayMs, context) => {
+    if (!isUndefined(deadline) && sleepWouldExceedDeadline(deadline, delayMs)) {
+        throw deadlineExceededError(deadline, context);
+    }
+    await sleep(delayMs);
+};
+//# sourceMappingURL=deadline.js.map

package/dist/drain-body.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Drain a fetch Response body the caller is about to discard. Skipping this
+ * leaks the underlying connection in the undici pool — long-running pods see
+ * degraded throughput on the next request cycle.
+ *
+ * @param { Response } response The fetch response whose body needs draining.
+ * @returns { Promise<void> } Resolves when the body has been cancelled.
+ */
+export declare const drainBody: (response: Response) => Promise<void>;
+//# sourceMappingURL=drain-body.d.ts.map

package/dist/drain-body.js

@@ -0,0 +1,18 @@
+/**
+ * Drain a fetch Response body the caller is about to discard. Skipping this
+ * leaks the underlying connection in the undici pool — long-running pods see
+ * degraded throughput on the next request cycle.
+ *
+ * @param { Response } response The fetch response whose body needs draining.
+ * @returns { Promise<void> } Resolves when the body has been cancelled.
+ */
+export const drainBody = async (response) => {
+    try {
+        await response.body?.cancel();
+    }
+    catch {
+        // Body already consumed or stream errored — either way nothing for
+        // the caller to recover from.
+    }
+};
+//# sourceMappingURL=drain-body.js.map