@mi9-identity/token-client 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+# @mi9-identity/token-client
+
+All notable changes to this package are documented here. **Manually maintained** —
+versions are semver and the three publishable `@mi9-identity/*` packages are
+released in lockstep at the same version. Releases up to `2026.8.21` used calver
+(`YYYY.M.D`).
+
+## 1.0.0
+
+- **First public release on npmjs.com**, under the **Apache-2.0** license. Earlier versions were published only to an internal Mi9 registry.
+- **Versioning changes from calver (`YYYY.M.D`) to semver**, starting at `1.0.0`. The three `@mi9-identity/*` packages stay in lockstep at one version. Issuer compatibility is still signalled by the `/api/v{N}` URL, not by the package version.
+- **No functional change compared with `2026.8.21`** — same public API, same wire shapes, same behaviour.
+
+## 2026.8.21
+
+- **`mi9IdentityEndpoints()` is exported from this package again**, returning `{ tokenEndpoint, credentialEndpoint }` — the two endpoints this package actually talks to. It derives them by appending bare paths to the issuer URL, with no `/api/v{N}` literal (ADR-13) and no new dependency, so an outbound-only consumer no longer installs `@mi9-identity/jwt-verifier` (and `jose`) to build two URLs. The JWKS URI now comes from that package's `mi9IdentityJwksEndpoint()`, which is a **breaking** rename on its side — see its changelog.
+
+  Correcting the record: this package exported `mi9IdentityEndpoints` up to `2026.6.4`. It was dropped in `2026.7.24` when the duplicated helper was consolidated into `jwt-verifier`, and that removal was never recorded here — a consumer that reinstalled at `2026.7.24` or later hit `TS2305: Module '"@mi9-identity/token-client"' has no exported member 'mi9IdentityEndpoints'` with nothing in this file to explain it.
+
+- **Multi-retailer GCP lazy-claim.** New optional `retailerCode` on `claimGcpCredential(...)` and on `createGcpTokenClient(...)` / `createTokenClient(...)` in lazy-claim mode, forwarded to `POST /credentials/me` (`grantType: gcp_identity`). One GCP service account may now hold one credential **per retailer**, so a platform consumer minting tokens on behalf of several tenants names the retailer at claim time. Additive and backward compatible: omit it and the issuer resolves on the service account alone, which behaves exactly as before while the account holds a single credential. Naming a retailer is never a widening — the issuer still returns only a credential already bound to the calling identity. One client instance claims one retailer; a consumer serving several builds one client per retailer so each keeps its own cached token.
+- **A non-retryable status from the `gcp_identity` grant now raises `ConfigurationError`, not `TransientError`.** Previously any uncategorized non-2xx (a 400 among them) fell through to `TransientError`, which is misleading — the request itself is wrong — and made a caller's own retry layer re-send it. The retry loop no longer spends a freshly minted single-use ID token per attempt on a request that fails identically every time. The common case is the issuer's `retailer_required`: a service account holding credentials for several retailers claimed without naming one. 404, 401/403, 429 and 5xx classification is unchanged.
+- **Claim rejections now carry the issuer's `errorDescription`.** The thrown `ConfigurationError` message is `"<status> <code>: <description>"`. The issuer's machine-readable sub-codes are audit-only and never on the wire, so the description is the only field that separates `retailer_required` ("specify retailerCode") from an ordinary malformed body — both report `invalid_request`.
+
+## 2026.7.24
+
+- **GCP Tier-1 lazy-claim + automatic re-claim.** New `createGcpTokenClient(...)` factory (and an `idTokenProvider` option on `createTokenClient`) enable **GCP lazy-claim mode**: the client bootstraps its `clientId` + `clientSecret` on first use via `POST /credentials/me` (`grantType: gcp_identity`) — no secret supplied up front — and **auto-re-claims** once when a mint is rejected with 401 (rotation / force-revoke / re-create). A second consecutive 401 is terminal (`RevocationError`); a claim never loops.
+- New standalone primitive `claimGcpCredential(...)` returning a `CredentialClaim` (`clientId`, `clientSecret`, `audience`, `tokenUrl`); new `LazyClaimError` (the Google ID token was rejected 401/403, or the provider threw). `ProvisioningError` now also covers a 404 from the `gcp_identity` grant, and a `503 degraded` from that grant — thrown immediately, never retried in-loop, and deliberately **not** folded into `TransientError` (a caller that buckets it as retryable would retry a misconfigured credential row forever).
+- New `ConfigurationError` — client options that do not describe a usable credential mode, or a `403 invalid_target` from `/oauth/token` (the requested `audience` is outside the credential's `authorizedAudiences`). Terminal and outside the Transient / Revocation / Provisioning taxonomy: the fix is a config or credential change, not a later attempt.
+- `idTokenProvider` is called with the credential endpoint URL (the issuer-pinned `aud`) and must return a **fresh** Google ID token per call — the issuer single-uses each token. No metadata-server helper and no new runtime dependency; obtaining the ID token (metadata server, google-auth, Workload Identity) stays with the caller.
+- `clientId` / `clientSecret` on `TokenClientOptions` are now optional, required (runtime-guarded) only outside lazy-claim mode.
+- **New `deadlineMs` option** bounds the ENTIRE `acquireToken()` / `forceRefresh()` call — claim, mint, re-claim, and retry mint together — to a single wall-clock budget in ms, instead of each step separately retrying up to `MAX_RETRIES + 1` times (a GCP lazy-claim chain could otherwise reach 24 round-trips with no ceiling on wall-clock time, dangerous on an inbound request path during an issuer brownout). Checked before every backoff sleep (stops rather than sleeping past the deadline) and applied to every fetch via `AbortSignal.timeout(remaining)`, so a single stalled socket cannot outlive the budget either. Exceeding it surfaces as a `TransientError` naming the configured budget and the elapsed time. Also added to the standalone `claimGcpCredential(...)`. Optional and unset by default — omitting it preserves today's unbounded-retry behaviour exactly.
+
+## 2026.6.4
+
+- **Removed the `audiences` request option** (reverts the 2026.5.27 addition). `/oauth/token` takes a single `audience` — a string or a non-empty array of strings, forwarded verbatim; the issuer echoes a scalar `aud` for a string request and a JSON array for an array request. Pass `audience: ['…']` where you previously passed `audiences: ['…']`.
+
+## 2026.6.1
+
+- **`Retry-After` header clamped to `policy.maxMs`.** `parseRetryAfterMs` now applies an upper bound of `policy.maxMs` to both the delta-seconds and HTTP-date branches. Previously a hostile or buggy `Retry-After: 3600` (or a far-future HTTP-date) could stall a caller far past the configured backoff ceiling; the value is now clamped to `[policy.initialMs, policy.maxMs]`.
+- **Rotation pickup is now non-blocking / background.** A `credentialRotated` signal no longer blocks `acquireToken` on the secondary `POST /credentials/me` call: the freshly-minted access token is cached and returned immediately, and the secret pickup runs as a detached task. A failed pickup (401 already-acknowledged, 503, other 4xx, or a malformed body) **no longer rejects `acquireToken`** — it is logged (`token-client.rotation_pickup_failed`) and swallowed, and the rotation signal re-triggers the pickup on the next refresh while it remains pending. Single-flight is preserved and `close()` clears the pickup handle.
+- **`204 No Content` from `/credentials/me`** is treated as a no-op (rotation already acknowledged — nothing to pick up), not a `ResponseShapeError`.
+- **Error envelope parser reads camelCase** (ADR-12 amendment). `oauthErrorSchema` now reads `errorDescription` (was `error_description`) plus an optional `requestId`. The client still surfaces only the `error` code, so this is a wire-fidelity fix with no API change.
+
+## 2026.5.27
+
+- **Multiple audiences per token** (ADR-6 amended). Adds an optional `audiences` request option forwarded alongside `audience`; at least one of the two is now required. The singular `audience` is **deprecated** in favor of `audiences` (still accepted and forwarded for backward compatibility). The issuer mints a scalar `aud` for one audience, a JSON array for several.
+- **`/api/v1` cutover** (ADR-13). Consumers point the issuer URL at the versioned value; `mi9IdentityEndpoints()` derives the token + credential endpoints.
+
+## 0.1.0
+
+- Version reset to pre-1.0 (`0.1.0`); the earlier `1.0.0` placeholder is superseded.
+- **Breaking**: wire-naming aligned with ADR-12. `/oauth/token` and `/credentials/me` request/response bodies use camelCase: `clientId`, `clientSecret`, `grantType`, `accessToken`, `tokenType`, `expiresIn`, `credentialRotated`, `tokenUrl`. Snake_case stays for standard OIDC claims (`iss`, `sub`, `aud`, …), RFC 6749 error codes (`invalid_request`, …), and `grantType` literal values (`client_credentials`, `gcp_identity`, `provisioning_token`, `jwt`).

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Mi9 Retail
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,402 @@
+# @mi9-identity/token-client
+
+Consumer-side `acquireToken()` / `forceRefresh()` state machine for the Mi9
+Identity Service. Encapsulates the retry, rotation-pickup, and refresh logic
+so every consumer service does not have to re-implement (and ship five subtly
+different bugs).
+
+Apache-2.0-licensed and free to use; access to the Mi9 Identity Platform it
+acquires tokens from is governed by your commercial agreement with Mi9 Retail.
+
+---
+
+## Which package do I need?
+
+| Package | Use it when |
+| --- | --- |
+| **`@mi9-identity/token-client`** (this one) | Your service **calls** a Mi9 API and needs a token. |
+| [`@mi9-identity/jwt-verifier`](https://www.npmjs.com/package/@mi9-identity/jwt-verifier) | Your service **receives** Mi9-issued tokens and must verify them. |
+| [`@mi9-identity/auth-middleware-express`](https://www.npmjs.com/package/@mi9-identity/auth-middleware-express) | The same, and your service is an Express 5 app. |
+
+A service that both calls Mi9 APIs and serves Mi9-authenticated requests
+installs two of them.
+
+---
+
+## Install
+
+```sh
+npm install @mi9-identity/token-client@1.0.0
+```
+
+Versions are **semver**, and the three `@mi9-identity/*` packages
+(`token-client`, `jwt-verifier`, `auth-middleware-express`) are released in
+lockstep at the same version — pin an **exact** version, no `^` or `~` range.
+Breaking wire changes ship as a new API path version (`/api/v2`), not as a
+package major bump.
+
+> **ESM + Node 24+.** The package is `"type": "module"` and requires Node ≥ 24.
+> Use `await import()` from CJS if needed.
+
+---
+
+## Getting credentials
+
+A Mi9 administrator provisions the credential for your service and gives you
+four things: the issuer URL, a `clientId`, a `clientSecret`, and the audience
+URL or URLs your service is allowed to request. This package does not create,
+register or renew credentials — it only uses them. Ask your Mi9 contact if you
+do not have them.
+
+Secrets rotate on a schedule. When the issuer signals a rotation, this client
+fetches the new secret in the background and calls your `onSecretRotated`
+callback with it; persist it there, or the old secret stops working at the end
+of its grace period. The details are in [Behavior](#behavior) below.
+
+## Configuration
+
+Configure a single issuer URL and derive the endpoints from it:
+
+```
+MI9_IDENTITY_ISSUER   # https://identity.mi9retail.com/api/v1  — matches the JWT `iss` claim
+```
+
+The issuer URL is the **versioned** one: `/api/v1` (or a future `/api/v2`) is
+part of the configured value, so a version cutover is a one-env-var change at
+each consumer.
+
+```ts
+import { mi9IdentityEndpoints } from '@mi9-identity/token-client';
+
+const { tokenEndpoint, credentialEndpoint } = mi9IdentityEndpoints(process.env.MI9_IDENTITY_ISSUER!);
+// → `${issuer}/oauth/token`, `${issuer}/credentials/me`
+```
+
+Audience values are always full URLs of the form `https://<host>/<path>`, never
+a bare service name — `https://lda.mi9retail.com/api/v1`, not `lda`. The issuer
+echoes the requested shape into the token's `aud`: a scalar for a string
+request, a JSON array for an array request.
+
+The Mi9 Identity Service does **not** publish
+`/.well-known/openid-configuration`, so a generic OAuth client library that
+auto-discovers its endpoints will fail — configure them explicitly, as above.
+
+---
+
+## Usage
+
+```ts
+import { createTokenClient } from '@mi9-identity/token-client';
+
+// The versioned issuer URL, e.g. https://identity.mi9retail.com/api/v1
+const issuer = process.env.MI9_IDENTITY_ISSUER!;
+
+const client = createTokenClient({
+    tokenEndpoint: `${issuer}/oauth/token`,
+    credentialEndpoint: `${issuer}/credentials/me`,
+    clientId: process.env.MERCHANT_CLIENT_ID!,
+    clientSecret: process.env.MERCHANT_CLIENT_SECRET!,
+    audience: ['https://lda.mi9retail.com/api/v1'],
+    onSecretRotated: async (newSecret) => {
+        await secretStore.atomicReplace(newSecret);
+    },
+    logger: log,
+});
+
+const { token } = await client.acquireToken();
+await fetch('https://lda.mi9retail.com/api/v1/...', {
+    headers: { authorization: 'Bearer ' + token },
+});
+
+// On graceful shutdown:
+client.close();
+```
+
+> **`audience` accepts one URL or many.** Pass a single full-URL string, or a
+> non-empty array of them for a multi-audience token. The issuer echoes the
+> requested shape into `aud` (scalar for a string, JSON array for an array).
+
+### Scopes
+
+**Do not set `scope`.** Credentials are provisioned today with an empty
+authorized-scope list, so there is no scope you are allowed to request.
+Requesting one is rejected by the issuer with `invalid_scope`, and your token
+request fails. With `scope` unset the issuer grants the credential's full
+authorized set, which is empty, and the token's `scope` claim is an empty
+string.
+
+Authorization is carried by the audience, the retailer and the product in the
+token, not by scopes. Set `scope` only if your Mi9 administrator tells you that
+your credential has authorized scopes.
+
+> **Deriving the endpoint URLs.** `mi9IdentityEndpoints(issuer)` returns
+> `{ tokenEndpoint, credentialEndpoint }` — the two endpoints this package
+> talks to — from the single issuer URL that matches the JWT `iss` claim. It
+> lives here rather than in `@mi9-identity/jwt-verifier` precisely so an
+> outbound-only service takes no dependency on a JOSE stack. If your service
+> also verifies inbound JWTs, that package's `mi9IdentityJwksEndpoint(issuer)`
+> covers the third URL.
+
+---
+
+## Behavior
+
+- **Proactive refresh** — `acquireToken()` returns the **cached** token while
+  `Date.now() < expiresAt - refreshLeadTimeMs` (default T-5 min for a 1 h TTL).
+  Call it on every outbound request — it is cheap on a cache hit.
+- **Single-flight** — a burst of concurrent `acquireToken()` calls during a
+  refresh funnels through **one** `/oauth/token` round-trip. `forceRefresh()`
+  coalesces with an in-flight refresh for the same reason; it does not start a
+  second concurrent mint.
+- **Backoff** — 429 / 503 / network failures are retried internally (up to 5
+  times) with exponential backoff + full jitter. Default curve:
+  `initialMs=1000`, `maxMs=30000`, `factor=2` (unjittered steps: 1 s → 2 s →
+  4 s → 8 s → 16 s → capped at 30 s; actual delays are randomised in
+  `[0, base]`). `Retry-After` is honoured when present, clamped to
+  `[initialMs, maxMs]` — a past or malformed value cannot collapse to an
+  immediate retry, and a hostile `Retry-After: 3600` cannot stall the caller
+  past the configured ceiling.
+- **No retry on 401** — raises `RevocationError`. A GCP (Tier 1) client
+  configured with `idTokenProvider` re-claims once automatically (see **GCP
+  Tier-1 lazy-claim** below) before surfacing this; other callers do not retry
+  with the same secret and escalate to operators (credential revoked or invalid).
+- **Background rotation pickup** — on `credentialRotated: true` (body) or
+  `X-Mi9-Credential-Rotated: true` (header), `acquireToken()` returns the
+  freshly-minted valid token **immediately**. The secret pickup
+  (`POST /credentials/me` with `grantType=jwt`, reusing the just-minted token
+  as bearer) runs as a **detached background task**:
+  - On success: the new secret is written to in-memory state **before**
+    `onSecretRotated(newSecret)` is called, so a callback throw is logged and
+    swallowed — it never locks out the client. The application is responsible
+    for persisting the new secret atomically so a process restart picks it up.
+  - A failed pickup (401 already-acknowledged / 503 / other 4xx / malformed
+    body) is logged and **swallowed — it never rejects `acquireToken()`** and
+    never discards the valid token. The rotation signal keeps firing on
+    subsequent mints; the pickup is retried on the next refresh while still
+    pending.
+  - `204 No Content` from `/credentials/me` means the rotation was already
+    acknowledged by another instance — a clean no-op.
+  - Background pickup is single-flight: a second signal while a pickup is
+    in-flight is ignored until the current one settles.
+- **`close()`** — call on graceful shutdown. Clears the in-memory cache and
+  drops the background pickup handle. Subsequent calls to `acquireToken()` or
+  `forceRefresh()` reject with `TokenClient is closed`.
+- **`X-Request-ID` propagation** — every outbound request carries the request
+  ID from the caller's context (configurable), or a freshly generated UUIDv4.
+- **`deadlineMs` (optional wall-clock budget)** — bounds the ENTIRE
+  `acquireToken()` / `forceRefresh()` call — claim, mint, re-claim, and retry
+  mint together — to a single wall-clock ceiling in ms, computed once when the
+  chain starts rather than reset at each step. Checked before every backoff
+  sleep (stops rather than sleeping past the deadline) and applied to every
+  fetch via `AbortSignal.timeout(remaining)`, so a single stalled socket
+  cannot outlive the budget either. Exceeding it raises a `TransientError`
+  naming the configured budget and the elapsed time. Unset by default —
+  omitting it preserves the unbounded retry behavior described above exactly.
+  Recommended for a GCP lazy-claim client invoked on the inbound request path
+  (see **GCP Tier-1 lazy-claim** below), where an unbounded chain can hold an
+  inbound request open for minutes during an issuer brownout.
+
+---
+
+## GCP Tier-1 lazy-claim
+
+A service hosted on Google Cloud never holds a secret up front. It proves its
+identity with a Google ID token and claims its credential on first use. Build it
+with `createGcpTokenClient` and supply an `idTokenProvider`:
+
+```ts
+import { createGcpTokenClient } from '@mi9-identity/token-client';
+
+const issuer = process.env.MI9_IDENTITY_ISSUER!;
+
+const client = createGcpTokenClient({
+    tokenEndpoint: `${issuer}/oauth/token`,
+    credentialEndpoint: `${issuer}/credentials/me`,
+    audience: ['https://lda.mi9retail.com/api/v1'],
+    // Return a FRESH Google ID token whose `aud` is the argument (the client
+    // always passes `credentialEndpoint`) — e.g. via google-auth's
+    // getIdTokenClient or the Google Cloud metadata server.
+    idTokenProvider: async (audience) => fetchGoogleIdToken(audience),
+    logger: log,
+});
+
+const { token } = await client.acquireToken(); // first call claims, then mints
+```
+
+What happens:
+
+1. The first `acquireToken()` finds no secret and calls
+   `idTokenProvider(credentialEndpoint)` — the client always requests a token
+   scoped to the **credential endpoint URL**, which the issuer pins as the
+   required `aud` (so a leaked token cannot be replayed against any other endpoint).
+2. It `POST`s `/credentials/me` with `{ "grantType": "gcp_identity" }` and that
+   ID token as the bearer, receiving `{ clientId, clientSecret, audience, tokenUrl }`.
+3. It mints against `/oauth/token` as usual. Tier-1 credentials live **in memory
+   only** — nothing is persisted. `createGcpTokenClient` omits `onSecretRotated`
+   from its options entirely, so there is no persist hook to supply. (If you
+   instead use `createTokenClient({ …, idTokenProvider })`, `onSecretRotated`
+   remains available and still fires on rotation pickup — but for a Tier-1
+   credential there is normally nothing to persist.)
+4. If a later mint is rejected with **401** (secret rotated, force-revoked, or
+   the credential re-created), the client re-claims once automatically and
+   retries. A second consecutive 401 is terminal (`RevocationError`) — it never loops.
+
+This means one `acquireToken()` call can chain up to four retried steps
+(claim, mint, re-claim, retry mint) with no wall-clock ceiling by default. That
+is normally fine for a background refresh, but a lazy-claim client is typically
+invoked lazily on an **inbound** request path (a service calling another Mi9
+service to serve its own caller) — during an issuer brownout, an unbounded chain
+can hold that inbound request open for minutes before your own request timeout
+kills it. Set **`deadlineMs`** to bound the whole chain to a wall-clock budget
+instead (see the options reference below) — recommended for exactly this case.
+
+The provider **must mint a fresh token per call** — the issuer single-uses each
+ID token, so a cached one would be rejected on a retry. This package ships **no**
+metadata-server helper and takes **no** `google-auth` dependency; how you obtain
+the ID token (metadata server, `google-auth`, Workload Identity Federation) is
+yours to choose.
+
+
+### Claiming for several retailers
+
+A service account may hold one credential **per retailer**, which is how a
+platform consumer mints tokens whose `retailerId` claim names the *destination*
+tenant rather than itself. Pass `retailerCode` to name which one:
+
+```ts
+const client = createGcpTokenClient({
+    tokenEndpoint: `${issuer}/oauth/token`,
+    credentialEndpoint: `${issuer}/credentials/me`,
+    audience: ['https://acme.pos.mi9retail.com/api/v1'],
+    retailerCode: 'acme',
+    idTokenProvider: async (audience) => fetchGoogleIdToken(audience),
+});
+```
+
+One client instance claims one retailer, so a consumer serving several builds
+one client per retailer and each keeps its own cached token.
+
+Omit `retailerCode` and the issuer resolves on the service account alone — which
+is exactly today's behaviour while the account holds a single credential, so no
+existing consumer needs to change. Once the account holds **two or more**, the
+omitted-retailer claim is a `400` (`retailer_required`) rather than a guess at
+which tenant was meant, surfaced as `ConfigurationError`. If you operate a
+platform consumer, start passing `retailerCode` explicitly **before** the first
+per-retailer credential is created against your account.
+
+Naming a retailer is never a widening: the issuer still returns only a
+credential an admin explicitly provisioned against your own service account.
+
+For the claim without the caching state machine, the standalone
+`claimGcpCredential(...)` primitive (returning a `CredentialClaim`) is also
+exported. `createTokenClient({ ..., idTokenProvider })` works too if you prefer
+the base factory.
+
+---
+
+## `TokenClientOptions` reference
+
+| Option | Required | Default | Purpose |
+| --- | --- | --- | --- |
+| `tokenEndpoint` | **yes** | — | `POST` URL for minting tokens — `${issuer}/oauth/token`. |
+| `credentialEndpoint` | **yes** | — | `POST` URL for the lazy claim and rotation pickup — `${issuer}/credentials/me`. |
+| `clientId` | yes\* | — | Credential's client ID (UUIDv7). Omit in GCP lazy-claim mode. |
+| `clientSecret` | yes\* | — | Initial secret; replaced in-memory on rotation. Omit in GCP lazy-claim mode. |
+| `idTokenProvider` | no | — | Enables GCP Tier-1 lazy-claim mode — `(audience) => string \| Promise<string>` returning a fresh Google ID token (see **GCP Tier-1 lazy-claim** above). |
+| `audience` | **yes** | — | Full-URL audience(s) the minted token targets — a single string or a non-empty array of strings. |
+| `scope` | no | — | Space-separated scope string to request. **Leave it unset** — see [Scopes](#scopes) below. |
+| `refreshLeadTimeMs` | no | `300_000` (5 min) | Refresh this far before `expiresAt`. |
+| `backoff` | no | `DEFAULT_BACKOFF` | `BackoffPolicy`: `{ initialMs, maxMs, factor, jitter }`. |
+| `onSecretRotated` | no | — | `(newSecret: string) => Promise<void>` — persist hook; see rotation behavior above. |
+| `requestIdHeader` | no | `'X-Request-ID'` | Outbound correlation header name. |
+| `requestId` | no | fresh UUID per call | A fixed string or `() => string` getter to thread your current request ID. |
+| `fetch` | no | global `fetch` | Injection point for tests. |
+| `logger` | no | no-op | pino-shaped logger (`debug`/`info`/`warn`/`error`). |
+| `deadlineMs` | no | none (unbounded) | Wall-clock budget in ms for the whole `acquireToken()`/`forceRefresh()` call — claim + mint + re-claim + mint. Checked before each backoff sleep and enforced per-fetch via `AbortSignal.timeout`; exceeding it throws `TransientError`. |
+
+\* `clientId` / `clientSecret` are required unless `idTokenProvider` (GCP lazy-claim mode) is set.
+
+---
+
+## Error taxonomy
+
+Errors fall into five categories — branch on these, not on HTTP status alone:
+
+| Category | Examples | Caller action |
+| --- | --- | --- |
+| **Transient** | 429, network timeout, and a `transient` 503 (all retried internally) | Surface as `503` upstream; let the caller retry with backoff. |
+| **Revocation** | 401 from `/oauth/token` | Do **not** retry with the same secret. A GCP client re-claims automatically (once); otherwise page on-call. |
+| **Provisioning** | 404 / no credential on record (from `/oauth/token` or the `gcp_identity` claim); also a `degraded` 503 on the claim | Page on-call — out-of-band recovery required; a later attempt succeeds once the credential exists or the mis-tiered row is corrected. |
+| **Lazy-claim** | 401 on the `gcp_identity` claim, or `idTokenProvider` threw (`LazyClaimError`) | Fix the provider or the ID-token audience — a retry cannot succeed. |
+| **Configuration** | Options that do not describe a usable credential mode, or a `403 invalid_target` from `/oauth/token` — an `audience` outside the credential's `authorizedAudiences` (`ConfigurationError`) | Fix the config or the credential's grants — no retry and no re-claim can clear it. |
+
+> **The two 503s on the `gcp_identity` claim are not interchangeable**, and the
+> status alone cannot separate them — the client branches on the envelope's
+> `error` code. A `transient` 503 is a subsystem blip and is retried internally.
+> A `degraded` 503 means the credential bound to your service account is not a
+> `gcp`-tier row — operator misconfiguration that stays true until an admin
+> edits it — so it raises `ProvisioningError` immediately rather than burning
+> the whole backoff curve, and every retry would cost a freshly minted ID token
+> against a condition that will not clear.
+
+> **On 403.** The issuer never emits 403 on this grant; every ID-token failure
+> path is `invalid_token` → 401. The client classifies 403 alongside 401 purely
+> as a defence against an intermediary (a load balancer or WAF) answering
+> first.
+
+`ResponseShapeError` sits **outside** the four categories above. It indicates
+an issuer response that did not match the expected schema — an issuer-side bug,
+not a recoverable condition. It is re-exported so callers can narrow on it in
+a custom error handler, but the client never retries on it.
+
+A failed **background rotation pickup** never surfaces here — it is swallowed,
+not thrown (see Behavior above).
+
+---
+
+## Error envelope
+
+When the issuer returns a 4xx or 5xx from `/oauth/token` or `/credentials/me`,
+the JSON body is a camelCase envelope. Only the `error` *code* stays
+snake_case, because RFC 6749 §5.2 reserves the code identifiers:
+
+```jsonc
+{
+  "error":            "invalid_client",          // RFC 6749 code — snake_case
+  "errorDescription": "Authentication failed.",  // Mi9 field — camelCase
+  "requestId":        "8f3c…",                   // echo of X-Request-ID
+  "details": [ /* field-level issues; only on invalid_request */ ]
+}
+```
+
+`token-client` maps this to the typed taxonomy above and surfaces only the
+`error` code in exception messages. If you parse the body yourself, read
+`errorDescription` (camelCase) — **not** the RFC `error_description`.
+
+This is the **outbound** surface. It is not the same shape as the RFC 6750
+Bearer challenge your own resource server returns to its callers, where
+`error` / `error_description` stay snake_case because RFC 6750 defines them
+that way; that surface belongs to
+[`@mi9-identity/auth-middleware-express`](https://www.npmjs.com/package/@mi9-identity/auth-middleware-express).
+
+---
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| `acquireToken()` throws `RevocationError` | Credential revoked, or the persisted secret is stale after a rotation | A GCP (Tier 1) client has already re-claimed once and still failed; otherwise confirm the persisted secret is current, then page on-call. |
+| `ConfigurationError` naming `invalid_target` | The requested `audience` is outside the credential's authorized audiences | Request an audience the credential is granted, or have the grant added. |
+| `ConfigurationError` naming `retailer_required` | The service account holds credentials for more than one retailer and the claim named none | Pass `retailerCode` (see **Claiming for several retailers**). |
+| Outbound calls fail only under load with `TransientError` | The issuer returned 429/503 and the internal retries were exhausted | Surface as 503 upstream and back off. |
+| `LazyClaimError` on the first `acquireToken()` | The Google ID token was rejected, or `idTokenProvider` threw | Return a **fresh** token per call whose `aud` is the credential endpoint URL the client passes in. |
+
+---
+
+JWKS 503 from the verifier side is handled by
+[`@mi9-identity/jwt-verifier`](https://www.npmjs.com/package/@mi9-identity/jwt-verifier)
+(serves cached keys up to 1 h, never fails open).
+
+## License
+
+Apache-2.0. The full text ships in the package as `LICENSE`.