@mi9-identity/token-client 1.0.0

package/dist/backoff.d.ts

@@ -0,0 +1,35 @@
+import type { BackoffPolicy } from './types.js';
+export declare const DEFAULT_BACKOFF: BackoffPolicy;
+/**
+ * Apply jitter on top of the base delay. `'full'` picks a uniform random
+ * value in `[0, base]` to smooth synchronized client retries; `'none'` is
+ * deterministic (useful for tests / benchmarks).
+ *
+ * @param { BackoffPolicy } policy The backoff policy parameters.
+ * @param { number } attempt Zero-indexed retry attempt number.
+ * @returns { number } The (optionally jittered) delay in milliseconds.
+ */
+export declare const computeBackoffDelayMs: (policy: BackoffPolicy, attempt: number) => number;
+/**
+ * Resolve `Retry-After` header per RFC 7231 §7.1.3 (delta-seconds OR HTTP-date).
+ * Returns `undefined` when absent or unparseable so callers fall back to the
+ * computed backoff. A past HTTP-date is floored to `policy.initialMs` so a
+ * malformed or already-elapsed `Retry-After` cannot collapse to a 0 ms
+ * immediate retry that hammers a broken upstream. The result is also clamped
+ * to `policy.maxMs` so a hostile or buggy large value cannot stall the caller
+ * beyond the configured backoff ceiling.
+ *
+ * @param { string | null | undefined } header The raw `Retry-After` header value.
+ * @param { BackoffPolicy } policy The backoff policy (floor `initialMs` and ceiling `maxMs` applied to the result).
+ * @returns { number | undefined } The delay in milliseconds, or `undefined` when the header is absent/unparseable.
+ */
+export declare const parseRetryAfterMs: (header: string | null | undefined, policy: BackoffPolicy) => number | undefined;
+/**
+ * Sleep promise that respects `unref` so it never holds the event loop open
+ * past intentional shutdown.
+ *
+ * @param { number } ms Delay in milliseconds (negative values are clamped to 0).
+ * @returns { Promise<void> } Resolves after the delay.
+ */
+export declare const sleep: (ms: number) => Promise<void>;
+//# sourceMappingURL=backoff.d.ts.map

package/dist/backoff.js

@@ -0,0 +1,79 @@
+import { isEmpty, isFunction } from './type-guards.js';
+export const DEFAULT_BACKOFF = {
+    initialMs: 1_000,
+    maxMs: 30_000,
+    factor: 2,
+    jitter: 'full',
+};
+/**
+ * Compute the delay for the Nth retry attempt (zero-indexed). With `factor=2`
+ * and `initialMs=1000` this yields 1s, 2s, 4s, 8s, ..., capped at `maxMs`.
+ *
+ * @param { BackoffPolicy } policy The backoff policy parameters.
+ * @param { number } attempt Zero-indexed retry attempt number.
+ * @returns { number } The unjittered base delay in milliseconds.
+ */
+const baseDelayMs = (policy, attempt) => {
+    const raw = policy.initialMs * policy.factor ** attempt;
+    return Math.min(raw, policy.maxMs);
+};
+/**
+ * Apply jitter on top of the base delay. `'full'` picks a uniform random
+ * value in `[0, base]` to smooth synchronized client retries; `'none'` is
+ * deterministic (useful for tests / benchmarks).
+ *
+ * @param { BackoffPolicy } policy The backoff policy parameters.
+ * @param { number } attempt Zero-indexed retry attempt number.
+ * @returns { number } The (optionally jittered) delay in milliseconds.
+ */
+export const computeBackoffDelayMs = (policy, attempt) => {
+    const base = baseDelayMs(policy, attempt);
+    if (policy.jitter === 'none') {
+        return base;
+    }
+    return Math.floor(Math.random() * base);
+};
+/**
+ * Resolve `Retry-After` header per RFC 7231 §7.1.3 (delta-seconds OR HTTP-date).
+ * Returns `undefined` when absent or unparseable so callers fall back to the
+ * computed backoff. A past HTTP-date is floored to `policy.initialMs` so a
+ * malformed or already-elapsed `Retry-After` cannot collapse to a 0 ms
+ * immediate retry that hammers a broken upstream. The result is also clamped
+ * to `policy.maxMs` so a hostile or buggy large value cannot stall the caller
+ * beyond the configured backoff ceiling.
+ *
+ * @param { string | null | undefined } header The raw `Retry-After` header value.
+ * @param { BackoffPolicy } policy The backoff policy (floor `initialMs` and ceiling `maxMs` applied to the result).
+ * @returns { number | undefined } The delay in milliseconds, or `undefined` when the header is absent/unparseable.
+ */
+export const parseRetryAfterMs = (header, policy) => {
+    if (isEmpty(header)) {
+        return undefined;
+    }
+    const trimmed = header.trim();
+    const seconds = Number(trimmed);
+    if (Number.isFinite(seconds) && seconds >= 0) {
+        return Math.min(Math.max(Math.floor(seconds * 1_000), policy.initialMs), policy.maxMs);
+    }
+    const dateMs = Date.parse(trimmed);
+    if (Number.isFinite(dateMs)) {
+        const deltaMs = dateMs - Date.now();
+        return Math.min(Math.max(deltaMs, policy.initialMs), policy.maxMs);
+    }
+    return undefined;
+};
+/**
+ * Sleep promise that respects `unref` so it never holds the event loop open
+ * past intentional shutdown.
+ *
+ * @param { number } ms Delay in milliseconds (negative values are clamped to 0).
+ * @returns { Promise<void> } Resolves after the delay.
+ */
+export const sleep = (ms) => new Promise((resolve) => {
+    const timer = setTimeout(resolve, Math.max(0, ms));
+    /* v8 ignore next 3 -- defensive cross-runtime guard; setTimeout in Node always returns a Timeout with unref */
+    if (isFunction(timer.unref)) {
+        timer.unref();
+    }
+});
+//# sourceMappingURL=backoff.js.map

package/dist/claim.d.ts

@@ -0,0 +1,21 @@
+import type { ClaimGcpCredentialOptions, CredentialClaim } from './types.js';
+/**
+ * Perform the Tier-1 GCP lazy-claim against `credentialEndpoint` and return the
+ * delivered credential.
+ *
+ * `idTokenProvider` is called with `credentialEndpoint` (the required `aud`)
+ * once per attempt and MUST return a fresh Google ID token each time — the
+ * issuer single-uses each token, so a cached one would be rejected on retry.
+ * Transient failures (429 / 5xx / network) are retried per the backoff policy,
+ * honouring a clamped `Retry-After`.
+ *
+ * @param { ClaimGcpCredentialOptions } opts Endpoint, ID-token provider, and transport/retry knobs.
+ * @returns { Promise<CredentialClaim> } The delivered `{ clientId, clientSecret, audience, tokenUrl }`.
+ * @throws { ProvisioningError } On 404 — no credential bound to the identity yet — and immediately on a 5xx carrying `degraded` (see `classifyServerError`).
+ * @throws { LazyClaimError } On 401/403 — the ID token was rejected, or the provider threw.
+ * @throws { ConfigurationError } On every other non-2xx — the request itself is wrong (malformed body, or a `retailerCode` that must be supplied or corrected).
+ * @throws { TransientError } When transient failures persist past the retry budget, or when `opts.deadlineMs` elapses before a retry.
+ * @throws { ResponseShapeError } When a 200 body fails the wire schema.
+ */
+export declare const claimGcpCredential: (opts: ClaimGcpCredentialOptions) => Promise<CredentialClaim>;
+//# sourceMappingURL=claim.d.ts.map

package/dist/claim.js

@@ -0,0 +1,169 @@
+import { drainBody } from './drain-body.js';
+import { isUndefined } from './type-guards.js';
+import { resolveRequestId } from './request-id.js';
+import { credentialMeResponseSchema } from './schemas.js';
+import { readOAuthErrorCode, readOAuthErrorDetail } from './oauth-error.js';
+import { computeBackoffDelayMs, DEFAULT_BACKOFF, parseRetryAfterMs } from './backoff.js';
+import { deadlineSignal, sleepOrThrowIfDeadlineExceeded, startDeadline } from './deadline.js';
+import { ConfigurationError, LazyClaimError, ProvisioningError, ResponseShapeError, TransientError } from './errors.js';
+import { DEFAULT_REQUEST_ID_HEADER, MAX_RETRIES, NOOP_LOGGER, OAUTH_ERROR_CODE_DEGRADED } from './token-client.constants.js';
+/**
+ * Parse a 200 `gcp_identity` delivery body into a `CredentialClaim`, reusing
+ * the shared `/credentials/me` delivery schema.
+ *
+ * @param { Response } response The successful fetch response.
+ * @returns { Promise<CredentialClaim> } The delivered credential.
+ * @throws { ResponseShapeError } If the body fails JSON parsing or schema validation.
+ */
+const parseDelivery = async (response) => {
+    let json;
+    try {
+        json = await response.json();
+    }
+    catch (error) {
+        throw new ResponseShapeError(`Failed to parse /credentials/me JSON body: ${String(error)}`);
+    }
+    const parsed = credentialMeResponseSchema.safeParse(json);
+    if (!parsed.success) {
+        throw new ResponseShapeError(`Unexpected /credentials/me response shape: ${parsed.error.message}`);
+    }
+    return parsed.data;
+};
+/**
+ * Classify a 5xx, splitting the in-loop-retryable ones from `degraded`.
+ *
+ * `degraded` is raised by two unrelated issuer paths — a credential bound to
+ * this service account but carrying a non-`gcp` consumer type, and the per-IP
+ * limiter failing closed when Redis is unreachable. The first is permanent until
+ * an admin acts; the second clears on its own.
+ * The discriminating `error_subcode` is audit-only, so a consumer cannot tell
+ * them apart and must treat the code as terminal FOR THIS ATTEMPT: each in-loop
+ * retry mints a fresh single-use Google ID token (the issuer fingerprints and
+ * refuses reuse) and the backoff curve spends ~60s on the inbound request path,
+ * all against an answer that does not change. It raises `ProvisioningError`
+ * rather than `TransientError` because the wire spec forbids folding `degraded`
+ * into the retryable class: a caller that buckets it as transient retries a
+ * misconfigured row forever. The rare limiter-outage case is then reported as
+ * needing an operator too — accepted, since a supervised restart is its
+ * recovery path either way.
+ *
+ * @param { Response } response The 5xx fetch response; its body is consumed here.
+ * @param { BackoffPolicy } backoff Active backoff policy used to compute the retry delay.
+ * @param { number } attempt Zero-based attempt index.
+ * @returns { Promise<{ transient: TransientError; retryAfterMs: number }> } The retry signal for an ordinary 5xx.
+ * @throws { ProvisioningError } Immediately, without an in-loop retry, when the envelope carries `degraded`.
+ */
+const classifyServerError = async (response, backoff, attempt) => {
+    const isDegraded = (await readOAuthErrorCode(response)) === OAUTH_ERROR_CODE_DEGRADED;
+    await drainBody(response);
+    if (isDegraded) {
+        throw new ProvisioningError(`/credentials/me (gcp_identity) returned ${String(response.status)} degraded — not retried in-loop, because every attempt would spend a freshly minted single-use ID token on an answer that cannot change within this call. An operator has to correct the credential row; retry the operation after that.`);
+    }
+    const retryAfterMs = parseRetryAfterMs(response.headers.get('retry-after'), backoff) ?? computeBackoffDelayMs(backoff, attempt);
+    return { transient: new TransientError(`/credentials/me (gcp_identity) returned ${String(response.status)}`), retryAfterMs };
+};
+/**
+ * Classify a non-2xx `/credentials/me` (gcp_identity) response: throw the
+ * terminal error for 404 / 401 / 403 / anything else, or return the transient
+ * retry signal (error + backoff delay) for a retryable 429 / 5xx.
+ *
+ * @param { Response } response The non-ok fetch response.
+ * @param { BackoffPolicy } backoff Active backoff policy used to compute the retry delay.
+ * @param { number } attempt Zero-based attempt index.
+ * @returns { Promise<{ transient: TransientError; retryAfterMs: number }> } The retry signal for a 429 / 5xx.
+ * @throws { ProvisioningError } On 404 — no credential bound to the identity yet — and on a 5xx carrying `degraded` (thrown without an in-loop retry).
+ * @throws { LazyClaimError } On 401 / 403 — the ID token was rejected.
+ * @throws { ConfigurationError } On every other status — a malformed body, or a `retailerCode` the calling identity must supply or correct. Permanent: retrying burns a freshly minted ID token against a request that will fail identically. Carries the envelope's `errorDescription`.
+ */
+const classifyNonOkResponse = async (response, backoff, attempt) => {
+    if (response.status === 404) {
+        await drainBody(response);
+        throw new ProvisioningError('credential not provisioned (404 from /credentials/me gcp_identity)');
+    }
+    if (response.status === 401 || response.status === 403) {
+        throw new LazyClaimError(`GCP identity token rejected by /credentials/me: ${await readOAuthErrorCode(response)}`);
+    }
+    if (response.status >= 500) {
+        return classifyServerError(response, backoff, attempt);
+    }
+    if (response.status === 429) {
+        const retryAfterMs = parseRetryAfterMs(response.headers.get('retry-after'), backoff) ?? computeBackoffDelayMs(backoff, attempt);
+        await drainBody(response);
+        return { transient: new TransientError('/credentials/me (gcp_identity) returned 429'), retryAfterMs };
+    }
+    // Everything left is the caller's own request: a malformed body, or a
+    // retailerCode that must be supplied or corrected. Permanent — folding
+    // these into TransientError would have the retry loop mint a fresh ID
+    // token per attempt against a request that fails identically every time.
+    // The detail reader keeps the envelope's `errorDescription`, the only field
+    // that separates `retailer_required` from an ordinary malformed body.
+    throw new ConfigurationError(`/credentials/me (gcp_identity) rejected the request: ${String(response.status)} ${await readOAuthErrorDetail(response)}`);
+};
+/**
+ * Perform the Tier-1 GCP lazy-claim against `credentialEndpoint` and return the
+ * delivered credential.
+ *
+ * `idTokenProvider` is called with `credentialEndpoint` (the required `aud`)
+ * once per attempt and MUST return a fresh Google ID token each time — the
+ * issuer single-uses each token, so a cached one would be rejected on retry.
+ * Transient failures (429 / 5xx / network) are retried per the backoff policy,
+ * honouring a clamped `Retry-After`.
+ *
+ * @param { ClaimGcpCredentialOptions } opts Endpoint, ID-token provider, and transport/retry knobs.
+ * @returns { Promise<CredentialClaim> } The delivered `{ clientId, clientSecret, audience, tokenUrl }`.
+ * @throws { ProvisioningError } On 404 — no credential bound to the identity yet — and immediately on a 5xx carrying `degraded` (see `classifyServerError`).
+ * @throws { LazyClaimError } On 401/403 — the ID token was rejected, or the provider threw.
+ * @throws { ConfigurationError } On every other non-2xx — the request itself is wrong (malformed body, or a `retailerCode` that must be supplied or corrected).
+ * @throws { TransientError } When transient failures persist past the retry budget, or when `opts.deadlineMs` elapses before a retry.
+ * @throws { ResponseShapeError } When a 200 body fails the wire schema.
+ */
+export const claimGcpCredential = async (opts) => {
+    const fetchImpl = opts.fetch ?? fetch;
+    const backoff = opts.backoff ?? DEFAULT_BACKOFF;
+    const log = opts.logger ?? NOOP_LOGGER;
+    const requestIdHeader = opts.requestIdHeader ?? DEFAULT_REQUEST_ID_HEADER;
+    const deadline = startDeadline(opts.deadlineMs);
+    let lastTransient;
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt += 1) {
+        let idToken;
+        try {
+            idToken = await opts.idTokenProvider(opts.credentialEndpoint);
+        }
+        catch (error) {
+            throw new LazyClaimError('idTokenProvider threw while minting a GCP identity token', { cause: error });
+        }
+        const signal = deadlineSignal(deadline);
+        let response;
+        try {
+            response = await fetchImpl(opts.credentialEndpoint, {
+                method: 'POST',
+                headers: {
+                    accept: 'application/json',
+                    'content-type': 'application/json',
+                    [requestIdHeader]: resolveRequestId(opts.requestId),
+                    authorization: `Bearer ${idToken}`,
+                },
+                // The request schema is strict and rejects a null, so an unset
+                // retailer omits the key rather than sending one.
+                body: JSON.stringify({ grantType: 'gcp_identity', ...(isUndefined(opts.retailerCode) ? {} : { retailerCode: opts.retailerCode }) }),
+                ...(isUndefined(signal) ? {} : { signal }),
+            });
+        }
+        catch (error) {
+            lastTransient = new TransientError('Network failure calling /credentials/me (gcp_identity)', { cause: error });
+            log.warn({ attempt, err: String(error) }, 'token-client.claim_network_error');
+            await sleepOrThrowIfDeadlineExceeded(deadline, computeBackoffDelayMs(backoff, attempt), '/credentials/me (gcp_identity)');
+            continue;
+        }
+        if (response.ok) {
+            return parseDelivery(response);
+        }
+        const { transient, retryAfterMs } = await classifyNonOkResponse(response, backoff, attempt);
+        lastTransient = transient;
+        log.warn({ attempt, status: response.status, retryAfterMs }, 'token-client.claim_transient');
+        await sleepOrThrowIfDeadlineExceeded(deadline, retryAfterMs, '/credentials/me (gcp_identity)');
+    }
+    /* v8 ignore next -- defensive; the loop assigns lastTransient on every transient path before exhausting MAX_RETRIES */
+    throw lastTransient ?? new TransientError('exhausted retries calling /credentials/me (gcp_identity)');
+};
+//# sourceMappingURL=claim.js.map

package/dist/client.d.ts

@@ -0,0 +1,24 @@
+import type { GcpTokenClientOptions, TokenClient, TokenClientOptions } from './types.js';
+/**
+ * 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 declare const createTokenClient: (opts: TokenClientOptions) => TokenClient;
+/**
+ * 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 declare const createGcpTokenClient: (opts: GcpTokenClientOptions) => TokenClient;
+//# sourceMappingURL=client.d.ts.map