@sixtyninecommerce/admin 0.4.0 → 0.6.0

package/README.md

@@ -38,6 +38,7 @@ for await (const form of await admin.content.forms.list()) {
 |---|---|---|
 | API token | `auth: { token: 's69t_…' }` | server only — constructing one in a browser throws `CREDENTIAL_IN_BROWSER` |
 | Admin session | `auth: { session: { token?, onToken } }` | server or browser |
+| App installation | `auth: { app: { appId, kid, privateKey }, installationId }` | server only — a private key in a browser throws `CREDENTIAL_IN_BROWSER` |
 
 A session client can start empty and sign in:
 
@@ -94,14 +95,72 @@ const created = await scoped.apiTokens.create({
 console.log(created.token); // shown exactly once
 ```
 
+### Apps
+
+An app is registered once by a platform operator from its `sixtynine.app.json` manifest, enabled
+per tenant, and then installed by a tenant admin who consents to a subset of what it declares.
+
+```ts
+// Tenant side — needs `InstallApps` and a tenant context.
+const available = await scoped.apps.list();
+const installation = await scoped.apps.install({
+  appId: available[0]!.id,
+  grantedPermissions: ['ReadCatalog', 'ReadOrder'], // ⊆ declaredPermissions, and ⊆ your own
+});
+```
+
+Your own permissions are the ceiling: you cannot grant an app something you do not hold on that
+channel. When the app's declarations later grow, the installation moves to `needs_consent` and its
+`pendingConsentReasons` say what changed — **tokens already minted keep the old grants and keep
+working** until `apps.approveConsent(id)` lands, so this is a notice, not an outage. `apps.uninstall(id)`
+revokes every token immediately and keeps the row as provenance for what the app wrote.
+
+```ts
+// App side — the app authenticates as itself. No token handling.
+const app = createAdminClient({
+  urls,
+  auth: {
+    app: { appId: process.env.APP_ID!, kid: '2026-09', privateKey: process.env.APP_PRIVATE_KEY! },
+    installationId: process.env.INSTALLATION_ID!,
+  },
+  tenant: { scope: { kind: 'channel', code: 'velvet-thread' } },
+});
+
+// A token is minted on the first call and refreshed for you from then on.
+const me = await app.auth.whoami();          // kind: 'app_installation'
+me.installation?.status;                     // 'needs_consent' → tell the merchant
+me.permissions;                              // what this installation was actually granted
+const products = await app.content.forms.list();  // …and any module those permissions allow
+```
+
+The SDK signs a short-lived Ed25519 assertion with your private key, exchanges it for an `s69i_`
+bearer, and refreshes that bearer a minute before it expires. The key never leaves your process and
+the bearer is never yours to store. `privateKey` takes a PKCS#8 PEM, a JWK, or an already-imported
+`CryptoKey` for a caller whose key lives in a KMS handle.
+
+`apps.*` itself is a TENANT ADMIN's surface, not an app's: `InstallApps` is never grantable to an
+app, because an installation is a minted credential and an app that could install one could grant
+another app a subset of its own permissions with nobody consenting. An app reads its own state
+through `auth.whoami()`.
+
+Registering apps, managing their keys, suspension and per-tenant enablement live under
+`platform.apps.*` and need a human SuperAdmin session — an app that could register apps could
+declare anything and enable itself.
+
+`APP_MANIFEST_SCHEMA` is exported from `@sixtyninecommerce/core`, so a build step can validate a
+manifest before anyone tries to register it.
+
 ### Knowing what credential you hold
 
 ```ts
 const who = await admin.auth.whoami();
-who.kind;          // 'api_token' | 'user'
+who.kind;          // 'api_token' | 'user' | 'app_installation'
 who.token?.expiresAt;  // null means it never expires
 who.permissions;   // effective on the ACTIVE channel, not the union
 who.entitlements;  // connected plugin keys for that channel
+// For an app: who.app (id, slug, name) and who.installation (status, consentVersion).
+// `installation.status === 'needs_consent'` is how an app learns the merchant has
+// to approve declarations it has since grown.
 ```
 
 For a machine credential this is the only way to learn any of it without being refused. It needs a
@@ -329,6 +388,71 @@ had before the registry.
 Read with `ReadSettings` and written with `UpdateSettings` — the same grants that govern
 `storefrontUrl` itself. A head an app installed (`installationId` set) is managed through that app's
 declarations and is refused here with `HEAD_APP_OWNED`.
+### Capabilities
+
+`admin.tenant.capabilities()` answers what this tenant's channel can actually do — one read instead
+of a dozen probes, and the read a head should make before it decides what to render.
+
+```ts
+const manifest = await admin.tenant.capabilities();
+
+manifest.capabilities.catalog.ready;          // false on a catalog-less tenant — render no product routes
+manifest.capabilities.search.blockers;        // ['search returned 0 hits — reindex Meilisearch for this channel']
+manifest.capabilities.age_gate.ready;         // true only when the channel has a minimum age set
+manifest.capabilities.mollie?.entitled;       // is the integration licensed to this tenant
+manifest.capabilities.mollie.ready;           // …and actually connected and enabled
+manifest.capabilities.checkout.dependsOn;     // ['catalog']
+
+await admin.tenant.capabilities.refresh();    // needs UpdateSettings; skips the freshness window
+```
+
+Four fields per key, and they answer different questions:
+
+| Field | Question |
+|---|---|
+| `provisioned` | does the thing exist here — and for a merchant switch (quotes, returns, reviews, the age gate, subscription plans, B2B price lists) that means **switched on** |
+| `configured` | did the probe find no hard blocker |
+| `entitled` | does the tenant hold this plugin's entitlement |
+| `ready` | `provisioned && configured && (entitled || the key is core)` — the one to branch on |
+
+`entitled` is `false` on every CORE capability and that is not a bug: the entitlement registry has
+rows only for the catalogue's gated plugins, and `catalog`, `search`, `routes` and the rest are the
+platform itself. `ready` is what excuses them.
+
+`blockers` are the platform's own readiness evidence, in the words its preflight uses — never a
+sentence this SDK composed, and never a UI flag. **Non-empty with `ready: true` means degraded, not
+broken**: a storefront that renders anyway is correct, and a merchant still wants to see the line.
+A feature deliberately left off carries no blocker at all — nothing is wrong with it.
+
+A blocker that opens with **`not established`** is different from both: it means a dependency would
+not answer, so the server could not read that capability's state at all. Treat it as unknown rather
+than as off — and note that such a manifest is served with a much shorter `Cache-Control` window,
+so asking again shortly is worth doing.
+
+**Capability keys are data, so they keep their wire spelling** — `content_pages`, `age_gate`,
+`b2b_pricing`, `payment-links` — exactly like the meta catalogue's data-keyed maps. The fields
+*inside* each entry are camelised (`depends_on` → `dependsOn`). Core keys are `catalog`, `search`,
+`routes`, `menus`, `content_pages`, `checkout`, `branding`, `age_gate`, `reviews`, `subscriptions`,
+`b2b_pricing`, `quotes` and `returns`; beside them there is one key per entitlement-gated plugin in
+the platform catalogue. **Treat an absent key as unknown, never as `false`** — the set grows, and a
+key whose rules are not settled is held back rather than published wrong. A plugin with no cheap server-side configuration read says so in `blockers`
+and stays `ready: false` — for those, `entitled` is the only authoritative field.
+
+`b2b_pricing` answers whether the tenant does trade pricing, and it is decided by ONE thing: the
+channel's trade customer groups. That is the registry the engine itself acts on — `checkIsB2BCustomer`,
+B2B tax display, quote eligibility and credit all resolve through it, and with no trade groups
+configured it returns false for every customer, so nothing trade can execute. Neither the quotes
+switch nor the price lists an anonymous caller can see change the answer: the switch is inert
+without trade groups, and that price-list query returns only applies-to-everyone lists, which an
+ordinary retail sale also uses. Both are reported as evidence on a channel already known to be B2B.
+So this key is worth reading with its `blockers`: `ready: true` with a blocker means the tenant IS a
+B2B channel and one piece of evidence was unreadable, and a `not established` blocker means the
+platform declined to guess. `ready: false` with an empty `blockers` means the channel has no trade
+groups — note that this reads the same whether or not the quotes switch is on, so the manifest does
+not currently distinguish a plain retail channel from one where quoting is enabled but inert.
+
+The service caches the manifest 60 s per channel and serves it with an `ETag`, so polling it is
+cheap. `installedApps` is on the wire already and stays empty until the app registry ships.
 
 ### Errors
 

package/dist/apps/assertion.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Signing the app assertion the platform exchanges for an `s69i_` token
+ * (headless spec §6.3).
+ *
+ * Web Crypto, not `jose`. `@sixtyninecommerce/core` has zero runtime
+ * dependencies by contract and `@sixtyninecommerce/admin` may depend only on
+ * it, so pulling a JWS library in here to produce ONE fixed shape — an EdDSA
+ * compact JWS over five claims — would trade that contract for about forty lines.
+ * `crypto.subtle` is available on Node 20+, Deno, Bun, Cloudflare Workers and
+ * every browser, which is the same reach.
+ *
+ * Ed25519 only. RS256 is accepted by the REGISTRY (an app may have been built
+ * around an existing RSA key), but this SDK signs with Ed25519: one algorithm
+ * means one code path, and an app using the SDK has no reason to want the
+ * larger, slower one.
+ */
+/**
+ * Web Crypto, typed LOCALLY rather than from `lib.dom` or `@types/node`.
+ *
+ * This package compiles with `lib: ["ES2022"]` and no DOM — deliberately, so a
+ * stray `document.` reference cannot slip in (`client.ts` makes the same point
+ * about the browser guard). Naming just the two operations used keeps that
+ * property and keeps the published `.d.ts` free of a lib a consumer may not have.
+ */
+export interface AppCryptoKey {
+    readonly type: string;
+    readonly algorithm: {
+        readonly name: string;
+    };
+}
+/** The private half, as an app author holds it. */
+export type AppPrivateKey = 
+/** PKCS#8 PEM (`-----BEGIN PRIVATE KEY-----`). */
+string
+/** A JWK (`{ kty: 'OKP', crv: 'Ed25519', d, x }`). */
+ | Record<string, unknown>
+/** An already-imported key, for a caller that keeps one in a KMS-backed handle. */
+ | AppCryptoKey;
+/**
+ * Import the key once. Wrapping the failure is the point: `importKey` rejects
+ * with `DataError`/`OperationError`, which tells an app author nothing about
+ * which of their two keys they pasted.
+ */
+export declare function importAppPrivateKey(key: AppPrivateKey): Promise<AppCryptoKey>;
+export interface AssertionClaims {
+    /** The registered app's id — the platform checks it against the installation. */
+    appId: string;
+    /**
+     * The installation this assertion may be exchanged at. Signed, and compared to
+     * the id in the exchange URL, so an app installed on two tenants cannot be
+     * handed a token for the wrong one by sending the wrong path.
+     */
+    installationId: string;
+    kid: string;
+    /** Seconds. The platform refuses more than 600 (spec §6.3). */
+    lifetimeSeconds?: number;
+    /** Injectable clock, so a spec can pin `iat`/`exp` without waiting. */
+    now?: () => number;
+}
+/** Default assertion lifetime: well inside the 600 s cap, with room for skew. */
+export declare const DEFAULT_ASSERTION_LIFETIME_SECONDS = 120;
+/**
+ * Build and sign the assertion.
+ *
+ * `jti` is a fresh uuid every time: the platform refuses a replayed one, so a
+ * cached assertion is worse than useless. `sub` is the installation id, which is
+ * what actually binds the assertion to one tenant — the path parameter alone
+ * would not, since the endpoint is unauthenticated. `aud` is deliberately absent:
+ * there is no stable audience string a self-hosted platform could publish, and
+ * `iss` + `sub` already name exactly one app on one installation.
+ */
+export declare function signAppAssertion(key: AppCryptoKey, claims: AssertionClaims): Promise<string>;

package/dist/apps/assertion.js

@@ -0,0 +1,141 @@
+import { ValidationError } from '@sixtyninecommerce/core';
+const PEM_BODY = /-----BEGIN [A-Z ]*PRIVATE KEY-----([\s\S]*?)-----END [A-Z ]*PRIVATE KEY-----/;
+function base64UrlEncode(bytes) {
+    let binary = '';
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    // `btoa` is in every runtime this package targets; Node has had it since 16.
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+function encodeJson(value) {
+    return base64UrlEncode(new TextEncoder().encode(JSON.stringify(value)));
+}
+function pemToDer(pem) {
+    const match = PEM_BODY.exec(pem);
+    if (!match?.[1]) {
+        throw new ValidationError({
+            code: 'APP_PRIVATE_KEY_INVALID',
+            message: 'The app private key is not a PKCS#8 PEM. Expected a block starting with "-----BEGIN PRIVATE KEY-----", a JWK object, or an imported CryptoKey.',
+            status: 400,
+            service: 'vendure',
+        });
+    }
+    const binary = atob(match[1].replace(/\s+/g, ''));
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i += 1)
+        bytes[i] = binary.charCodeAt(i);
+    return bytes;
+}
+function subtle() {
+    const webcrypto = globalThis.crypto;
+    if (!webcrypto?.subtle) {
+        throw new ValidationError({
+            code: 'WEB_CRYPTO_UNAVAILABLE',
+            message: 'globalThis.crypto.subtle is not available, so an app assertion cannot be signed. Node 20+, Deno, Bun and browsers all provide it; a Node 18 runtime needs --experimental-global-webcrypto.',
+            status: 400,
+            service: 'vendure',
+        });
+    }
+    return webcrypto.subtle;
+}
+/**
+ * Import the key once. Wrapping the failure is the point: `importKey` rejects
+ * with `DataError`/`OperationError`, which tells an app author nothing about
+ * which of their two keys they pasted.
+ */
+export async function importAppPrivateKey(key) {
+    if (typeof key === 'object' && 'type' in key && 'algorithm' in key) {
+        const handle = key;
+        // Checked, not trusted. The registry also accepts RS256 keys, so an app
+        // built around one can reach here with a perfectly valid RSA handle —
+        // `subtle.sign('Ed25519', …)` would then reject with a raw WebCrypto
+        // `InvalidAccessError`, and every other failure in this file is an
+        // actionable `APP_PRIVATE_KEY_INVALID`.
+        if (handle.algorithm?.name !== 'Ed25519') {
+            throw new ValidationError({
+                code: 'APP_PRIVATE_KEY_INVALID',
+                message: `This SDK signs app assertions with Ed25519, but the key handle provided is ${String(handle.algorithm?.name)}. Register an Ed25519 key for the app, or sign the assertion yourself.`,
+                status: 400,
+                service: 'vendure',
+            });
+        }
+        // The PRIVATE half, too. A public Ed25519 handle passes the check above and
+        // fails inside `subtle.sign` as a raw `DOMException`, which is not a
+        // `PlatformError`: the transport reads it as a network fault, marks it
+        // retryable and burns the whole backoff budget reporting a permanent key
+        // mistake as an outage.
+        if (handle.type !== 'private') {
+            throw new ValidationError({
+                code: 'APP_PRIVATE_KEY_INVALID',
+                message: `The key handle provided is a "${String(handle.type)}" key. Sign with the PRIVATE half; the public half is what you register with addAppKey.`,
+                status: 400,
+                service: 'vendure',
+            });
+        }
+        return handle;
+    }
+    try {
+        if (typeof key === 'string') {
+            return await subtle().importKey('pkcs8', pemToDer(key), 'Ed25519', false, ['sign']);
+        }
+        return await subtle().importKey('jwk', key, 'Ed25519', false, ['sign']);
+    }
+    catch (error) {
+        if (error instanceof ValidationError)
+            throw error;
+        throw new ValidationError({
+            code: 'APP_PRIVATE_KEY_INVALID',
+            message: 'The app private key could not be imported as an Ed25519 key. Check that it is the PRIVATE half, in PKCS#8 PEM or JWK form, and that the runtime supports Ed25519.',
+            status: 400,
+            service: 'vendure',
+            cause: error,
+        });
+    }
+}
+/** Default assertion lifetime: well inside the 600 s cap, with room for skew. */
+export const DEFAULT_ASSERTION_LIFETIME_SECONDS = 120;
+/**
+ * Build and sign the assertion.
+ *
+ * `jti` is a fresh uuid every time: the platform refuses a replayed one, so a
+ * cached assertion is worse than useless. `sub` is the installation id, which is
+ * what actually binds the assertion to one tenant — the path parameter alone
+ * would not, since the endpoint is unauthenticated. `aud` is deliberately absent:
+ * there is no stable audience string a self-hosted platform could publish, and
+ * `iss` + `sub` already name exactly one app on one installation.
+ */
+export async function signAppAssertion(key, claims) {
+    const now = Math.floor((claims.now?.() ?? Date.now()) / 1000);
+    const lifetime = claims.lifetimeSeconds ?? DEFAULT_ASSERTION_LIFETIME_SECONDS;
+    const header = encodeJson({ alg: 'EdDSA', typ: 'JWT', kid: claims.kid });
+    const payload = encodeJson({
+        iss: claims.appId,
+        sub: claims.installationId,
+        iat: now,
+        exp: now + lifetime,
+        jti: randomId(),
+    });
+    const signingInput = `${header}.${payload}`;
+    const signature = await subtle().sign('Ed25519', key, new TextEncoder().encode(signingInput));
+    return `${signingInput}.${base64UrlEncode(new Uint8Array(signature))}`;
+}
+/** A uuid for `jti`. `randomUUID` is available wherever `subtle` is. */
+function randomId() {
+    const webcrypto = globalThis.crypto;
+    if (webcrypto?.randomUUID)
+        return webcrypto.randomUUID();
+    // Only reachable on a runtime with `subtle` but no `randomUUID`; 16 random
+    // bytes are as unique as a v4 uuid, and the platform treats `jti` as opaque.
+    // `Math.random` is NOT a fallback here: a guessable `jti` would let anyone who
+    // saw one assertion pre-burn the next one's id and lock the app out.
+    if (!webcrypto?.getRandomValues) {
+        throw new ValidationError({
+            code: 'WEB_CRYPTO_UNAVAILABLE',
+            message: 'This runtime provides neither crypto.randomUUID nor crypto.getRandomValues, so a unique assertion id cannot be generated.',
+            status: 400,
+            service: 'vendure',
+        });
+    }
+    const bytes = webcrypto.getRandomValues(new Uint8Array(16));
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+}

package/dist/apps/credential.d.ts

@@ -0,0 +1,36 @@
+import { type AppPrivateKey } from './assertion.js';
+/**
+ * Holding, minting and refreshing an installation token (headless spec §6.3).
+ *
+ * An app never handles the `s69i_` bearer itself: it hands the SDK its private
+ * key and installation id, and every call goes out with a live token. The token
+ * lasts an hour, so this mints once and refreshes a minute before expiry —
+ * early enough that a call is never made with a token that expires mid-flight.
+ *
+ * Concurrent calls collapse onto ONE mint (`inFlight`). Without it, an app that
+ * fires ten requests at startup signs ten assertions and burns ten tokens, and
+ * every one of them is a round trip the caller waits for.
+ */
+export interface AppCredentialConfig {
+    /** The registered app's id, which the assertion carries as `iss`. */
+    appId: string;
+    /** The `kid` of the key below, as registered with `addAppKey`. */
+    kid: string;
+    /** PKCS#8 PEM, a JWK, or an already-imported `CryptoKey`. Never leaves the process. */
+    privateKey: AppPrivateKey;
+}
+export interface AppCredential {
+    /** A live bearer, minting or refreshing if needed. */
+    current(): Promise<string>;
+    /** The last bearer minted, or `''`. Synchronous, for the transport's principal. */
+    peek(): string;
+    /** Drop the cached token, so the next call mints a fresh one. */
+    invalidate(): void;
+    /**
+     * Replace `stale`, which the server has just refused. Returns whatever a
+     * sibling minted if one already has, so a burst of concurrent 401s collapses
+     * onto ONE exchange instead of one per request.
+     */
+    refresh(stale: string): Promise<string>;
+}
+export declare function createAppCredential(app: AppCredentialConfig, installationId: string, vendureUrl: string, fetchImpl: typeof globalThis.fetch): AppCredential;

package/dist/apps/credential.js

@@ -0,0 +1,182 @@
+import { errorFromResponse, TransportError } from '@sixtyninecommerce/core';
+import { importAppPrivateKey, signAppAssertion, } from './assertion.js';
+/** Refresh this long before expiry, so no call goes out on a dying token. */
+const REFRESH_MARGIN_MS = 60_000;
+/**
+ * Wall-clock budget for one exchange; see the `signal` below. The SAME 15 s the
+ * transport gives every other call — a longer one here meant a caller who
+ * budgeted 15 s could block for 45 while a stalled mint ran to its own deadline.
+ */
+const EXCHANGE_TIMEOUT_MS = 15_000;
+export function createAppCredential(app, installationId, vendureUrl, fetchImpl) {
+    let token = '';
+    let expiresAt = 0;
+    let inFlight = null;
+    /** Bumped by `invalidate()`; a mint from an older generation is not cached. */
+    let invalidations = 0;
+    /** The dead bearer the in-flight mint is REPLACING, for `refresh()`. */
+    let refreshingFrom = null;
+    let key = null;
+    async function mint() {
+        // The generation this mint belongs to. An `invalidate()` that lands while
+        // this is in flight bumps it, and the result is then returned to the caller
+        // but NOT cached — otherwise the token the server has just killed would be
+        // written back over the fresh one and the app would 401 again.
+        const generation = invalidations;
+        // Imported once and kept: `importKey` is not free, and an app makes this
+        // call every hour for the life of the process.
+        key ??= importAppPrivateKey(app.privateKey);
+        const assertion = await signAppAssertion(await key, {
+            appId: app.appId,
+            installationId,
+            kid: app.kid,
+        });
+        // Trailing slash stripped, as every other URL in the client is: a
+        // `vendureUrl` of `https://api.example.test/` works for every GraphQL call
+        // and produced `…test//apps/installations/…` here, which the controller's
+        // route does not match — app auth 404s while the rest of the client works.
+        const base = vendureUrl.replace(/\/+$/, '');
+        const url = `${base}/apps/installations/${encodeURIComponent(installationId)}/access-tokens`;
+        let response;
+        try {
+            response = await fetchImpl(url, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ assertion }),
+                // DEADLINED, like every other call the client makes. Without it an
+                // exchange that never settles wedges `current()` for the life of the
+                // process: the slot it holds is freed only by `invalidate()`, which is
+                // only reachable from a 401 — which can never arrive, because no
+                // request ever goes out.
+                signal: AbortSignal.timeout(EXCHANGE_TIMEOUT_MS),
+            });
+        }
+        catch (error) {
+            // A network failure minting the credential is retryable, and must not be
+            // reported as "your key is wrong".
+            throw new TransportError({
+                code: 'INSTALLATION_TOKEN_UNREACHABLE',
+                message: `Could not reach the token exchange at ${url}.`,
+                status: 0,
+                service: 'vendure',
+                retryable: true,
+                cause: error,
+            });
+        }
+        if (!response.ok) {
+            // problem+json first, legacy second — the exchange answers the same shape
+            // every other refusal on this platform does.
+            throw await errorFromResponse(response, 'vendure');
+        }
+        // Read inside the same guard as the request: an abort that fires while the
+        // body is still streaming would otherwise escape as a raw `AbortError`,
+        // which is not a `PlatformError` — the transport then re-wraps it as a
+        // timeout naming a deadline that did not fire.
+        let body;
+        try {
+            body = (await response.json());
+        }
+        catch (error) {
+            throw new TransportError({
+                code: 'INSTALLATION_TOKEN_UNREACHABLE',
+                message: `The token exchange at ${url} did not answer in full.`,
+                status: 0,
+                service: 'vendure',
+                retryable: true,
+                cause: error,
+            });
+        }
+        const minted = typeof body.access_token === 'string' ? body.access_token : '';
+        if (minted === '') {
+            throw new TransportError({
+                code: 'INSTALLATION_TOKEN_MALFORMED',
+                message: 'The token exchange answered 200 with no access_token.',
+                status: 0,
+                service: 'vendure',
+                retryable: true,
+            });
+        }
+        // `expires_in` WINS, because it is the only one of the two that does not
+        // require the two clocks to agree. `expires_at` is the SERVER's absolute
+        // instant; comparing it against this host's `Date.now()` on a client running
+        // two minutes slow means refreshing two minutes late in real time — the
+        // bearer is already dead, and the gate answers a NON-retryable 401 that
+        // nothing here recovers from. The relative form is measured from the moment
+        // the response arrived, on this clock, and cannot skew.
+        //
+        // `expires_at` stays the fallback for a server that sends only the absolute
+        // form. A body with neither is treated as already-expiring rather than
+        // never-expiring: minting again costs one round trip, while trusting a
+        // missing expiry means every call 401s from the hour mark on with nothing to
+        // tell the caller why.
+        const relative = typeof body.expires_in === 'number' ? Date.now() + body.expires_in * 1000 : Number.NaN;
+        const absolute = typeof body.expires_at === 'string' ? Date.parse(body.expires_at) : Number.NaN;
+        const expiry = Number.isFinite(relative)
+            ? relative
+            : Number.isFinite(absolute)
+                ? absolute
+                : Date.now();
+        // Nothing from a discarded generation is cached — not the token, and not
+        // its expiry, which would otherwise move the live token's refresh window.
+        if (generation !== invalidations)
+            return minted;
+        expiresAt = expiry;
+        token = minted;
+        return token;
+    }
+    /** Start a mint, or join the one already running. */
+    function mintOnce() {
+        if (inFlight)
+            return inFlight;
+        // The slot is cleared only by the mint that OWNS it: `invalidate()` also
+        // nulls it, and an unconditional `finally` then cleared the slot belonging
+        // to the newer mint that had already replaced it.
+        const pending = mint().finally(() => {
+            if (inFlight === pending) {
+                inFlight = null;
+                refreshingFrom = null;
+            }
+        });
+        inFlight = pending;
+        return pending;
+    }
+    return {
+        async current() {
+            if (token !== '' && Date.now() < expiresAt - REFRESH_MARGIN_MS)
+                return token;
+            return mintOnce();
+        },
+        peek: () => token,
+        async refresh(stale) {
+            // A sibling has already replaced it — the commonest case when a burst of
+            // concurrent calls all meet the same 401. Its freshness is checked too, so
+            // the retry cannot go out on a bearer that has since expired and burn the
+            // one attempt it gets.
+            if (token !== '' && token !== stale && Date.now() < expiresAt - REFRESH_MARGIN_MS) {
+                return token;
+            }
+            // A mint is already running for a state that is no older than this refusal
+            // — either a refresh for this same dead bearer, or one started after an
+            // invalidation (`token === ''`, so nothing is cached to be stale). Join it
+            // rather than dropping it and starting another: N concurrent 401s would
+            // otherwise sign N assertions for the one kill they are all reacting to.
+            if (inFlight && (refreshingFrom === stale || token === ''))
+                return inFlight;
+            token = '';
+            expiresAt = 0;
+            invalidations += 1;
+            inFlight = null;
+            refreshingFrom = stale;
+            return mintOnce();
+        },
+        invalidate() {
+            token = '';
+            expiresAt = 0;
+            // Drops any mint already in flight as well: it was started for the
+            // credential state that has just been declared dead.
+            invalidations += 1;
+            inFlight = null;
+            refreshingFrom = null;
+        },
+    };
+}