@mi9-identity/token-client 1.0.0

package/dist/types.d.ts

@@ -0,0 +1,241 @@
+/**
+ * Structural logger contract — any pino-compatible object satisfies this.
+ * Defined in this package (rather than imported from `@mi9-identity/jwt-verifier`) so
+ * the token client has zero dependency on the verifier package.
+ */
+export interface Logger {
+    debug(obj: unknown, msg?: string): void;
+    info(obj: unknown, msg?: string): void;
+    warn(obj: unknown, msg?: string): void;
+    error(obj: unknown, msg?: string): void;
+}
+/**
+ * Exponential backoff policy applied to 429/503/timeout responses. `jitter:
+ * 'full'` is the recommended default — picks a uniform random delay between
+ * 0 and the computed `currentMs`, smoothing thundering-herd retries when
+ * many consumers see the same 503.
+ */
+export interface BackoffPolicy {
+    initialMs: number;
+    maxMs: number;
+    factor: number;
+    jitter: 'full' | 'none';
+}
+/**
+ * Token returned by `acquireToken` / `forceRefresh`. `expiresAt` is a Unix
+ * epoch in milliseconds — compatible with `Date.now()` for cache-hit
+ * comparisons.
+ */
+export interface AccessToken {
+    token: string;
+    expiresAt: number;
+}
+/**
+ * Endpoint, transport, and retry options shared by both credential modes of
+ * `createTokenClient`. The mode itself comes from the
+ * `StaticCredentialOptions | GcpLazyClaimOptions` union this is intersected
+ * with in `TokenClientOptions`.
+ */
+export interface TokenClientBaseOptions {
+    tokenEndpoint: string;
+    credentialEndpoint: string;
+    /**
+     * Full-URL audience(s) the minted access tokens target — a single URL or a
+     * non-empty array of them. Required. Forwarded to `/oauth/token` verbatim;
+     * the issuer echoes the requested shape into `aud` (a one-element array
+     * stays a one-element array, not collapsed to a scalar).
+     */
+    audience: string | readonly string[];
+    scope?: string;
+    /**
+     * Default 5 * 60_000 ms (T-5 min for a 1 h TTL).
+     */
+    refreshLeadTimeMs?: number;
+    backoff?: BackoffPolicy;
+    /**
+     * Persist callback invoked when the issuer rotates the secret. The new
+     * secret is already written to the client's in-memory state before this
+     * runs — a thrown rejection is logged and swallowed, NOT propagated. The
+     * application is responsible for reconciling its durable store on
+     * restart. Rationale: the issuer sets `rotationAcknowledgedAt` on the
+     * first successful pickup; a retry with the prior (active) secret returns
+     * `stale_after_ack` and the consumer is locked out. Better to keep the
+     * new secret in memory and surface the persist failure as an
+     * application-level alert.
+     */
+    onSecretRotated?: (newSecret: string) => Promise<void>;
+    /**
+     * Default `'X-Request-ID'`. Propagated outbound on every fetch (HTTP/2
+     * normalizes to lowercase on the wire).
+     */
+    requestIdHeader?: string;
+    /**
+     * Inbound request_id source. Pass a string to pin one value, or a getter
+     * to thread the caller's current request_id through on each mint. Default
+     * mints a fresh `randomUUID()` per request.
+     */
+    requestId?: string | (() => string);
+    /**
+     * Transport override — supply a wrapped `fetch` to route through a proxy,
+     * add instrumentation, or pin a custom agent/dispatcher. Defaults to the
+     * global `fetch`.
+     */
+    fetch?: typeof fetch;
+    logger?: Logger;
+    /**
+     * Wall-clock budget in ms for one ENTIRE `acquireToken()` / `forceRefresh()`
+     * call — spanning the claim, mint, re-claim, and retry-mint steps as a
+     * single chain rather than resetting the budget at each step. Checked
+     * before every backoff sleep (throws instead of sleeping past the
+     * deadline) and applied to every fetch via `AbortSignal.timeout`, so a
+     * single stalled socket cannot outlive it either. Absent by default —
+     * omitting it preserves today's unbounded-retry behaviour exactly (each
+     * step still stops at its own retry ceiling, just with no wall-clock cap
+     * spanning them). Recommended for a GCP lazy-claim client invoked on the
+     * inbound request path, where an unbounded chain can hold a Cloud Run
+     * request open for minutes during an issuer brownout.
+     */
+    deadlineMs?: number;
+}
+/**
+ * Static-credential mode: the caller already holds a `clientId` + secret
+ * (Tier 2 `on_prem` / Tier 3 `device`). `idTokenProvider` is forbidden here so
+ * the compiler keeps the two modes apart.
+ */
+export interface StaticCredentialOptions {
+    clientId: string;
+    clientSecret: string;
+    idTokenProvider?: never;
+    retailerCode?: never;
+}
+/**
+ * GCP Tier-1 lazy-claim mode: the client bootstraps its own credential on
+ * first use and silently re-claims when a mint is rejected with 401, so
+ * `clientId` / `clientSecret` are optional seeds rather than requirements.
+ */
+export interface GcpLazyClaimOptions {
+    /**
+     * Returns a fresh Google ID token for the audience it is passed — the
+     * client always passes `credentialEndpoint`, which the issuer pins as the
+     * required `aud`. Must return a fresh token per call; the issuer
+     * single-uses each ID token.
+     */
+    idTokenProvider: (audience: string) => string | Promise<string>;
+    /**
+     * Credential identifier (UUIDv7), if one is already known. The first claim
+     * populates it otherwise.
+     */
+    clientId?: string;
+    /**
+     * Initial secret, if one is already known. The first claim populates it
+     * otherwise, and Tier-1 credentials are held in memory only (never
+     * persisted).
+     */
+    clientSecret?: string;
+    /**
+     * Retailer whose credential this client claims. Required only when the
+     * service account holds credentials for several retailers; see
+     * `ClaimGcpCredentialOptions.retailerCode`. One client instance claims one
+     * retailer — a consumer serving several builds one client per retailer so
+     * each keeps its own cached token.
+     */
+    retailerCode?: string;
+}
+/**
+ * Configuration for `createTokenClient`. The client mints + caches access
+ * tokens, refreshes them proactively at `expiresAt - refreshLeadTimeMs`, and
+ * handles rotation pickup transparently when the issuer signals
+ * `credentialRotated`. The union enforces the two credential modes: supply
+ * `clientId` + `clientSecret`, or supply `idTokenProvider` and let the client
+ * lazy-claim.
+ */
+export type TokenClientOptions = TokenClientBaseOptions & (StaticCredentialOptions | GcpLazyClaimOptions);
+/**
+ * Public token-client surface. `close()` clears the in-memory cache and
+ * makes subsequent calls reject — call it on graceful shutdown so a
+ * mid-refresh promise doesn't outlive the surrounding service.
+ */
+export interface TokenClient {
+    acquireToken(): Promise<AccessToken>;
+    forceRefresh(): Promise<AccessToken>;
+    close(): void;
+}
+/**
+ * A credential delivered by the Tier-1 `gcp_identity` lazy-claim: identifier,
+ * raw secret, authorized audiences, and token endpoint. Feed `clientId` /
+ * `clientSecret` into `/oauth/token` to mint access tokens.
+ */
+export interface CredentialClaim {
+    clientId: string;
+    clientSecret: string;
+    audience: readonly string[];
+    tokenUrl: string;
+}
+/**
+ * Configuration for `createGcpTokenClient` — a Tier-1 client that lazy-claims
+ * its credential on first use and silently re-claims on a 401. Derived from
+ * `TokenClientBaseOptions` so every transport/retry option stays in sync, with
+ * `idTokenProvider` required. `onSecretRotated` is absent by design — Tier-1
+ * credentials live in memory and are re-claimed on demand, never persisted.
+ */
+export type GcpTokenClientOptions = Omit<TokenClientBaseOptions, 'onSecretRotated'> & {
+    idTokenProvider: (audience: string) => string | Promise<string>;
+    /** See `GcpLazyClaimOptions.retailerCode`. */
+    retailerCode?: string;
+};
+/**
+ * Options for the standalone Tier-1 GCP lazy-claim.
+ */
+export interface ClaimGcpCredentialOptions {
+    /**
+     * Absolute `/credentials/me` URL. Also the required `aud` passed to
+     * `idTokenProvider`.
+     */
+    credentialEndpoint: string;
+    /**
+     * Returns a fresh Google ID token for the audience it is passed. Must mint
+     * a fresh token per call — the issuer single-uses each one.
+     */
+    idTokenProvider: (audience: string) => string | Promise<string>;
+    /**
+     * Retailer whose credential to claim. Required only when the service
+     * account holds credentials for more than one retailer — a platform
+     * consumer minting tokens on behalf of several tenants. Omit it and the
+     * issuer resolves on the service account alone, which succeeds while the
+     * account holds exactly one credential and is `invalid_request` once it
+     * holds several. Naming it is never a widening: the issuer still only
+     * returns a credential already bound to the calling identity.
+     */
+    retailerCode?: string;
+    /**
+     * Transport override — supply a wrapped `fetch` to route through a proxy,
+     * add instrumentation, or pin a custom agent/dispatcher. Defaults to the
+     * global `fetch`.
+     */
+    fetch?: typeof fetch;
+    /**
+     * Retry/backoff policy for transient (429 / 5xx / network) failures.
+     * Defaults to `DEFAULT_BACKOFF`.
+     */
+    backoff?: BackoffPolicy;
+    /**
+     * Outbound correlation-id source. A string pins one value; a getter
+     * threads a per-call id; default mints a fresh `randomUUID()`.
+     */
+    requestId?: string | (() => string);
+    /**
+     * Header name for the outbound correlation id. Defaults to
+     * `'X-Request-ID'`.
+     */
+    requestIdHeader?: string;
+    logger?: Logger;
+    /**
+     * Wall-clock budget in ms for this call — bounds the claim's own retry
+     * loop so it cannot block a caller (standalone, or one composing this
+     * into a larger chain) past a wall-clock ceiling. Checked before every
+     * backoff sleep and applied to every fetch via `AbortSignal.timeout`.
+     * Absent by default, preserving today's unbounded-retry behaviour exactly.
+     */
+    deadlineMs?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@mi9-identity/token-client",
+  "version": "1.0.0",
+  "private": false,
+  "description": "Mi9 token client — consumer-side acquireToken/forceRefresh state machine for the Mi9 Identity Service. Handles proactive refresh, 429/503 backoff, 401 revocation, and rotation pickup.",
+  "keywords": [
+    "mi9",
+    "identity",
+    "oauth2",
+    "jwt",
+    "rs256",
+    "jwks",
+    "m2m"
+  ],
+  "license": "Apache-2.0",
+  "author": "Mi9 Retail",
+  "homepage": "https://mi9retail.com",
+  "type": "module",
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "!dist/.tsbuildinfo",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "24.13.3",
+    "@vitest/coverage-v8": "4.1.11",
+    "vitest": "4.1.11",
+    "@mi9-identity/tsconfig": "^1.0.0"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:cov": "vitest run --coverage",
+    "lint": "biome lint .",
+    "lint:fix": "biome lint --write .",
+    "clean": "rimraf dist .turbo"
+  }
+}