@btravstack/oauth-client 0.0.0-stage → 0.29.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Benoit TRAVERS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,92 @@
-# Temporary Holding Version
+# @btravstack/oauth-client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> A `TokenSource` port for [`@btravstack/core`](../core): a bearer token so a
+> service calls another as itself, over the OAuth 2.0 client credentials
+> grant — kept per audience until shortly before it expires, one fetch shared
+> by concurrent callers, and a static adapter for tests.
+
+📖 **[Documentation](https://btravstack.github.io/btravstack/reference/oauth-client)** ·
+[API Reference](https://btravstack.github.io/btravstack/api/oauth-client/)
+
+```sh
+pnpm add @btravstack/oauth-client @btravstack/core @btravstack/config \
+  @btravstack/di openid-client unthrown
+```
+
+Every dependency is a peer. Node `>=22.12`: `openid-client` is ESM-only, so
+the CommonJS build relies on `require(esm)`.
+
+## A worked example
+
+<!-- doctest: prelude
+import { Module, Port, Provider } from "@btravstack/di";
+import type { AsyncResult } from "unthrown";
+-->
+
+A port that needs a token for the inventory service, and the composition that
+provides one:
+
+```ts
+import {
+  TokenSource,
+  oauthClient,
+  type TokenIssuerUnavailable,
+  type TokenRefused,
+} from "@btravstack/oauth-client";
+
+class InventoryAuth extends Port("ReadmeInventoryAuth")<{
+  readonly header: () => AsyncResult<string, TokenRefused | TokenIssuerUnavailable>;
+}> {}
+
+export const inventoryAuth = Provider(InventoryAuth)({
+  inject: { tokens: TokenSource },
+  sync: ({ tokens }) => ({
+    header: () =>
+      tokens
+        .token({ audience: "https://inventory.internal", scope: "inventory:read" })
+        .map(({ bearer }) => `Bearer ${bearer}`),
+  }),
+});
+
+export const Gateway = Module("ReadmeGateway")({
+  imports: [oauthClient()],
+  provides: [inventoryAuth],
+  exports: [InventoryAuth],
+});
+```
+
+Putting the token on an oRPC client's `Authorization` header, without a
+`Promise` leaving the `Result`, is
+[Call another service as itself](https://btravstack.github.io/btravstack/how-to/call-another-service-as-itself).
+
+## Options
+
+| Option                | Where                                 | What it is                                                      |
+| --------------------- | ------------------------------------- | --------------------------------------------------------------- |
+| `OAUTH_ISSUER`        | environment, pinned by `issuer`       | the authorization server — required                             |
+| `OAUTH_CLIENT_ID`     | environment, pinned by `clientId`     | this service's client — required                                |
+| `OAUTH_CLIENT_SECRET` | environment, pinned by `clientSecret` | its secret, from a Kubernetes Secret — required                 |
+| `allowInsecureIssuer` | `oauthClient({ … })`                  | accept an `http:` issuer that is not loopback (default `false`) |
+| `clock`               | `oauthClient({ … })`                  | what a token's lifetime is measured against                     |
+
+The full table — defaults, semantics and the reasoning — lives on
+[the reference page](https://btravstack.github.io/btravstack/reference/oauth-client),
+which is this list's one detailed home.
+
+## What it decides, and what it does not
+
+**It decides** that discovery is lazy, so an issuer down at deploy fails the
+calls that need a token rather than the boot; that a token is reused until a
+minute before it expires; that a refusal (`TokenRefused`, with the issuer's
+`error` code) and an outage (`TokenIssuerUnavailable`) are two typed errors;
+that every fetch is reported to `Observers`; and that an `oauth-client` health
+check fails while an audience's last fetch failed.
+
+**It does not decide** what a failure means for your call — retrying belongs
+to your transport — and it does not yet mint a token on behalf of a user
+(RFC 8693 token exchange is deferred). The reasoning is in
+[`AGENTS.md`](./AGENTS.md).
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,207 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _btravstack_config = require("@btravstack/config");
+let _btravstack_core = require("@btravstack/core");
+let _btravstack_di = require("@btravstack/di");
+let openid_client = require("openid-client");
+let unthrown = require("unthrown");
+//#region src/token-source.ts
+/**
+* The authorization server answered, and the answer was no — an OAuth error
+* (`invalid_client`, `invalid_scope`, `invalid_request`, `unauthorized_client`…).
+* A configuration or a registration is wrong, so asking again will not help.
+*
+* It carries the server's `error` code and description, and never the client
+* secret.
+*/
+var TokenRefused = class extends (0, unthrown.TaggedError)("TokenRefused") {};
+/**
+* The authorization server could not be asked: discovery failed, the network
+* did, or it answered with a server error. Transient, so a later call asks
+* again — a failure is never cached.
+*/
+var TokenIssuerUnavailable = class extends (0, unthrown.TaggedError)("TokenIssuerUnavailable") {};
+/**
+* The port an application depends on to call another service as itself: a
+* bearer token for an audience. `oauthClient()` provides it over the client
+* credentials grant; `staticTokenSource` is the in-process stand-in.
+*/
+var TokenSource = class extends (0, _btravstack_di.Port)("TokenSource") {};
+/**
+* The in-process adapter: the same `bearer` for every request, and it cannot
+* fail. The shape `@btravstack/testing`'s `overridden` takes, so a spec swaps
+* the real source under the real root.
+*/
+const staticTokenSource = (bearer) => (0, _btravstack_di.Provider)(TokenSource)({
+	inject: {},
+	value: { token: () => (0, unthrown.OkAsync)({ bearer }) }
+});
+//#endregion
+//#region src/client.ts
+/**
+* How long before its stated expiry a token stops being handed out: it must
+* outlive the request it rides, through the callee's queue and a clock that
+* disagrees with this one. Capped at half a lifetime, so a short-lived token
+* is still reused.
+*/
+const SKEW_MS = 6e4;
+/** The source and its health, built once, so the check reads the same fetches the callers make. */
+var TokenFetches = class extends (0, _btravstack_di.Port)("OAuthTokenFetches") {};
+const fetching = (request) => ({
+	component: "oauth-client",
+	name: "token",
+	attributes: {
+		operation: "token",
+		"btravstack.oauth.audience": request.audience
+	},
+	details: { "btravstack.oauth.scope": request.scope ?? "" }
+});
+/**
+* What the issuer said no with, when the answer was a refusal rather than an
+* outage. A challenge is RFC 6749 §5.2's `401` for a rejected client, which
+* is `invalid_client` by definition.
+*/
+const refusalOf = (cause) => cause instanceof openid_client.WWWAuthenticateChallengeError ? {
+	error: "invalid_client",
+	description: void 0
+} : cause instanceof openid_client.ResponseBodyError && cause.status < 500 ? {
+	error: cause.error,
+	description: cause.error_description
+} : void 0;
+const reasonOf = (audience, failure) => failure.tag === "Err" && failure.error._tag === "TokenRefused" ? `${audience}: refused (${failure.error.error})` : `${audience}: the issuer could not be asked`;
+const tokenFetches = (settings, observers, clock) => {
+	let configuration;
+	const cached = /* @__PURE__ */ new Map();
+	const inFlight = /* @__PURE__ */ new Map();
+	const failing = /* @__PURE__ */ new Map();
+	const discover = () => {
+		configuration ??= (0, unthrown.fromPromise)(Promise.resolve().then(() => (0, openid_client.discovery)(new URL(settings.issuer), settings.clientId, void 0, (0, openid_client.ClientSecretBasic)(settings.clientSecret), { execute: settings.insecure ? [openid_client.allowInsecureRequests] : [] })), (cause) => new TokenIssuerUnavailable({
+			issuer: settings.issuer,
+			cause
+		})).map((config) => {
+			if (settings.insecure) (0, openid_client.allowInsecureRequests)(config);
+			return config;
+		}).tapFailure(() => {
+			configuration = void 0;
+		});
+		return configuration;
+	};
+	const grant = (request, config) => (0, unthrown.fromPromise)((0, openid_client.clientCredentialsGrant)(config, {
+		audience: request.audience,
+		...request.scope === void 0 ? {} : { scope: request.scope }
+	}), (cause) => {
+		const refusal = refusalOf(cause);
+		return refusal === void 0 ? new TokenIssuerUnavailable({
+			issuer: settings.issuer,
+			cause
+		}) : new TokenRefused({
+			audience: request.audience,
+			...refusal
+		});
+	});
+	const fetchToken = (key, request) => {
+		const asked = clock.now();
+		const fetched = (0, _btravstack_core.observed)(observers, fetching(request), () => discover().flatMap((config) => grant(request, config))).map((response) => {
+			const lifetimeMs = (response.expires_in ?? 0) * 1e3;
+			return {
+				token: { bearer: response.access_token },
+				refreshAt: asked + lifetimeMs - Math.min(SKEW_MS, lifetimeMs / 2)
+			};
+		}).tap((entry) => {
+			inFlight.delete(key);
+			failing.delete(key);
+			cached.set(key, entry);
+		}).tapFailure((failure) => {
+			inFlight.delete(key);
+			failing.set(key, reasonOf(request.audience, failure));
+		}).map((entry) => entry.token);
+		inFlight.set(key, fetched);
+		return fetched;
+	};
+	return {
+		source: { token: (request) => {
+			const key = JSON.stringify([request.audience, request.scope ?? null]);
+			const hit = cached.get(key);
+			if (hit !== void 0 && clock.now() < hit.refreshAt) return (0, unthrown.OkAsync)(hit.token);
+			return inFlight.get(key) ?? fetchToken(key, request);
+		} },
+		health: () => failing.size === 0 ? (0, unthrown.OkAsync)() : (0, unthrown.ErrAsync)(new _btravstack_core.HealthCheckFailed({ reason: [...failing.values()].join("; ") }))
+	};
+};
+/**
+* The client credentials starter: `TokenSource` over an OAuth 2.0
+* authorization server, so a service calls another as itself.
+*
+* ```ts
+* Module("Gateway")({ imports: [oauthClient()], provides: [ordersClient] });
+* ```
+*
+* - **Configured from `OAUTH_ISSUER`, `OAUTH_CLIENT_ID` and
+*   `OAUTH_CLIENT_SECRET`**, each pinned by its option, validated as the graph
+*   is built. A cleartext issuer off loopback is a `ConfigInvalid` unless
+*   `allowInsecureIssuer` is pinned.
+* - **Discovery is lazy**: the first token asks for the issuer's metadata, and
+*   a failed discovery is asked again by the next. An authorization server
+*   down at deploy fails the calls that need a token, not the boot.
+* - **A token is kept per audience and scope** until a minute before it
+*   expires (half its lifetime, if that is shorter), and callers asking for
+*   the same one while it is being fetched share that one request. A failure
+*   is never kept.
+* - **Every fetch is reported to `Observers`** (`component: "oauth-client"`);
+*   a token served from memory reports nothing.
+* - **It contributes the `oauth-client` health check**, failing while the
+*   last fetch of any audience failed — a rotated secret and an unreachable
+*   issuer both show there, where a reachability probe would see only the
+*   second.
+*/
+const oauthClient = (options = {}) => {
+	const clock = options.clock ?? _btravstack_core.systemClock;
+	const schema = _btravstack_config.Config.object({
+		issuer: _btravstack_config.Config.pinned(options.issuer, _btravstack_config.Config.url("OAUTH_ISSUER")),
+		clientId: _btravstack_config.Config.pinned(options.clientId, _btravstack_config.Config.string("OAUTH_CLIENT_ID")),
+		clientSecret: _btravstack_config.Config.pinned(options.clientSecret, _btravstack_config.Config.string("OAUTH_CLIENT_SECRET"))
+	});
+	const fetches = (0, _btravstack_di.Provider)(TokenFetches)({
+		inject: {
+			env: _btravstack_config.Env,
+			observers: _btravstack_core.Observers
+		},
+		make: ({ env, observers }) => _btravstack_config.Config.parse("OAuthClient", schema)(env).flatMap((bound) => {
+			const insecure = (0, _btravstack_config.cleartext)(bound.issuer, options.allowInsecureIssuer ?? false);
+			return insecure === "refused" ? (0, unthrown.ErrAsync)((0, _btravstack_config.cleartextRefused)({
+				port: "OAuthClient",
+				variable: "OAUTH_ISSUER",
+				option: "allowInsecureIssuer",
+				on: "oauthClient()",
+				what: "it sends the client secret and every token in the open"
+			})) : (0, unthrown.OkAsync)(tokenFetches({
+				...bound,
+				insecure
+			}, observers, clock));
+		})
+	});
+	return (0, _btravstack_di.Module)("OAuthClient")({
+		needs: [_btravstack_config.Env],
+		provides: [
+			_btravstack_core.noObserverMember,
+			fetches,
+			(0, _btravstack_di.Provider)(TokenSource)({
+				inject: { fetches: TokenFetches },
+				sync: ({ fetches: built }) => built.source
+			}),
+			_btravstack_di.Provider.member(_btravstack_core.HealthChecks)({
+				inject: { fetches: TokenFetches },
+				sync: ({ fetches: built }) => ({
+					name: "oauth-client",
+					check: built.health
+				})
+			})
+		],
+		exports: [TokenSource, _btravstack_core.HealthChecks]
+	});
+};
+//#endregion
+exports.TokenIssuerUnavailable = TokenIssuerUnavailable;
+exports.TokenRefused = TokenRefused;
+exports.TokenSource = TokenSource;
+exports.oauthClient = oauthClient;
+exports.staticTokenSource = staticTokenSource;

package/dist/index.d.cts

@@ -0,0 +1,118 @@
+import { ConfigInvalid, EnvReading, MaybePinned, OptionsAs, Unpinned } from "@btravstack/config";
+import { Clock, HealthChecks } from "@btravstack/core";
+import { Module, Provider } from "@btravstack/di";
+import { AsyncResult } from "unthrown";
+//#region src/token-source.d.ts
+/**
+ * What a token is asked for: the service it will be presented to, and
+ * optionally the scopes it must carry (space-delimited, as OAuth spells them).
+ *
+ * A record rather than positional arguments, so a later field — the actor a
+ * call is made on behalf of — joins it without moving anything already here.
+ */
+type TokenRequest = {
+  /** The callee, as its authorization server names it: the `aud` the token is minted for. */
+  readonly audience: string;
+  readonly scope?: string;
+};
+/**
+ * A token to present, as `Authorization: Bearer <bearer>`.
+ *
+ * No expiry rides it: keeping a token until shortly before it expires is the
+ * source's job, and a caller that held the expiry would be a caller about to
+ * cache it a second time.
+ */
+type AccessToken = {
+  readonly bearer: string;
+};
+declare const TokenRefused_base: import("unthrown").TaggedErrorConstructor<"TokenRefused">;
+/**
+ * The authorization server answered, and the answer was no — an OAuth error
+ * (`invalid_client`, `invalid_scope`, `invalid_request`, `unauthorized_client`…).
+ * A configuration or a registration is wrong, so asking again will not help.
+ *
+ * It carries the server's `error` code and description, and never the client
+ * secret.
+ */
+export declare class TokenRefused extends TokenRefused_base<{
+  readonly audience: string;
+  readonly error: string;
+  readonly description: string | undefined;
+}> {}
+declare const TokenIssuerUnavailable_base: import("unthrown").TaggedErrorConstructor<"TokenIssuerUnavailable">;
+/**
+ * The authorization server could not be asked: discovery failed, the network
+ * did, or it answered with a server error. Transient, so a later call asks
+ * again — a failure is never cached.
+ */
+export declare class TokenIssuerUnavailable extends TokenIssuerUnavailable_base<{
+  readonly issuer: string;
+  readonly cause: unknown;
+}> {}
+type TokenSourceService = {
+  readonly token: (request: TokenRequest) => AsyncResult<AccessToken, TokenRefused | TokenIssuerUnavailable>;
+};
+declare const TokenSource_base: import("@btravstack/di").PortClass<"TokenSource">;
+/**
+ * The port an application depends on to call another service as itself: a
+ * bearer token for an audience. `oauthClient()` provides it over the client
+ * credentials grant; `staticTokenSource` is the in-process stand-in.
+ */
+export declare class TokenSource extends TokenSource_base<TokenSourceService> {}
+/**
+ * The in-process adapter: the same `bearer` for every request, and it cannot
+ * fail. The shape `@btravstack/testing`'s `overridden` takes, so a spec swaps
+ * the real source under the real root.
+ */
+export declare const staticTokenSource: (bearer: string) => Provider<TokenSource, never, never> & {
+  readonly port: typeof TokenSource;
+};
+//#endregion
+//#region src/client.d.ts
+/** What {@link oauthClient} is handed. Each of the first three pins the variable named beside it. */
+type OAuthClientOptions = {
+  /** Pins `OAUTH_ISSUER` — the authorization server, as its discovery document names itself. */
+  readonly issuer?: string | undefined;
+  /** Pins `OAUTH_CLIENT_ID`. */
+  readonly clientId?: string | undefined;
+  /** Pins `OAUTH_CLIENT_SECRET`. A deployment sets the variable, from a Secret. */
+  readonly clientSecret?: string | undefined;
+  /**
+   * Talk to an `http:` issuer that is NOT on a loopback host. Default `false`,
+   * and a `ConfigInvalid` at boot without it: the client secret and every
+   * token cross the wire in the open. An option rather than a variable,
+   * because its silent change is a security regression.
+   */
+  readonly allowInsecureIssuer?: boolean;
+  /** What a token's lifetime is measured against (default: the kernel's `systemClock`). */
+  readonly clock?: Clock | undefined;
+};
+/**
+ * The client credentials starter: `TokenSource` over an OAuth 2.0
+ * authorization server, so a service calls another as itself.
+ *
+ * ```ts
+ * Module("Gateway")({ imports: [oauthClient()], provides: [ordersClient] });
+ * ```
+ *
+ * - **Configured from `OAUTH_ISSUER`, `OAUTH_CLIENT_ID` and
+ *   `OAUTH_CLIENT_SECRET`**, each pinned by its option, validated as the graph
+ *   is built. A cleartext issuer off loopback is a `ConfigInvalid` unless
+ *   `allowInsecureIssuer` is pinned.
+ * - **Discovery is lazy**: the first token asks for the issuer's metadata, and
+ *   a failed discovery is asked again by the next. An authorization server
+ *   down at deploy fails the calls that need a token, not the boot.
+ * - **A token is kept per audience and scope** until a minute before it
+ *   expires (half its lifetime, if that is shorter), and callers asking for
+ *   the same one while it is being fetched share that one request. A failure
+ *   is never kept.
+ * - **Every fetch is reported to `Observers`** (`component: "oauth-client"`);
+ *   a token served from memory reports nothing.
+ * - **It contributes the `oauth-client` health check**, failing while the
+ *   last fetch of any audience failed — a rotated secret and an unreachable
+ *   issuer both show there, where a reachability probe would see only the
+ *   second.
+ */
+export declare const oauthClient: <const O extends OAuthClientOptions = Record<never, never>>(options?: O & OptionsAs<O, OAuthClientOptions>) => Module<TokenSource | HealthChecks, ConfigInvalid, EnvReading<Unpinned<O, "issuer", "OAUTH_ISSUER"> | Unpinned<O, "clientId", "OAUTH_CLIENT_ID"> | Unpinned<O, "clientSecret", "OAUTH_CLIENT_SECRET">, MaybePinned<O, "issuer", "OAUTH_ISSUER"> | MaybePinned<O, "clientId", "OAUTH_CLIENT_ID"> | MaybePinned<O, "clientSecret", "OAUTH_CLIENT_SECRET">>>;
+//#endregion
+export type { AccessToken, OAuthClientOptions, TokenRequest, TokenSourceService };

package/dist/index.d.mts

@@ -0,0 +1,118 @@
+import { ConfigInvalid, EnvReading, MaybePinned, OptionsAs, Unpinned } from "@btravstack/config";
+import { Clock, HealthChecks } from "@btravstack/core";
+import { Module, Provider } from "@btravstack/di";
+import { AsyncResult } from "unthrown";
+//#region src/token-source.d.ts
+/**
+ * What a token is asked for: the service it will be presented to, and
+ * optionally the scopes it must carry (space-delimited, as OAuth spells them).
+ *
+ * A record rather than positional arguments, so a later field — the actor a
+ * call is made on behalf of — joins it without moving anything already here.
+ */
+type TokenRequest = {
+  /** The callee, as its authorization server names it: the `aud` the token is minted for. */
+  readonly audience: string;
+  readonly scope?: string;
+};
+/**
+ * A token to present, as `Authorization: Bearer <bearer>`.
+ *
+ * No expiry rides it: keeping a token until shortly before it expires is the
+ * source's job, and a caller that held the expiry would be a caller about to
+ * cache it a second time.
+ */
+type AccessToken = {
+  readonly bearer: string;
+};
+declare const TokenRefused_base: import("unthrown").TaggedErrorConstructor<"TokenRefused">;
+/**
+ * The authorization server answered, and the answer was no — an OAuth error
+ * (`invalid_client`, `invalid_scope`, `invalid_request`, `unauthorized_client`…).
+ * A configuration or a registration is wrong, so asking again will not help.
+ *
+ * It carries the server's `error` code and description, and never the client
+ * secret.
+ */
+export declare class TokenRefused extends TokenRefused_base<{
+  readonly audience: string;
+  readonly error: string;
+  readonly description: string | undefined;
+}> {}
+declare const TokenIssuerUnavailable_base: import("unthrown").TaggedErrorConstructor<"TokenIssuerUnavailable">;
+/**
+ * The authorization server could not be asked: discovery failed, the network
+ * did, or it answered with a server error. Transient, so a later call asks
+ * again — a failure is never cached.
+ */
+export declare class TokenIssuerUnavailable extends TokenIssuerUnavailable_base<{
+  readonly issuer: string;
+  readonly cause: unknown;
+}> {}
+type TokenSourceService = {
+  readonly token: (request: TokenRequest) => AsyncResult<AccessToken, TokenRefused | TokenIssuerUnavailable>;
+};
+declare const TokenSource_base: import("@btravstack/di").PortClass<"TokenSource">;
+/**
+ * The port an application depends on to call another service as itself: a
+ * bearer token for an audience. `oauthClient()` provides it over the client
+ * credentials grant; `staticTokenSource` is the in-process stand-in.
+ */
+export declare class TokenSource extends TokenSource_base<TokenSourceService> {}
+/**
+ * The in-process adapter: the same `bearer` for every request, and it cannot
+ * fail. The shape `@btravstack/testing`'s `overridden` takes, so a spec swaps
+ * the real source under the real root.
+ */
+export declare const staticTokenSource: (bearer: string) => Provider<TokenSource, never, never> & {
+  readonly port: typeof TokenSource;
+};
+//#endregion
+//#region src/client.d.ts
+/** What {@link oauthClient} is handed. Each of the first three pins the variable named beside it. */
+type OAuthClientOptions = {
+  /** Pins `OAUTH_ISSUER` — the authorization server, as its discovery document names itself. */
+  readonly issuer?: string | undefined;
+  /** Pins `OAUTH_CLIENT_ID`. */
+  readonly clientId?: string | undefined;
+  /** Pins `OAUTH_CLIENT_SECRET`. A deployment sets the variable, from a Secret. */
+  readonly clientSecret?: string | undefined;
+  /**
+   * Talk to an `http:` issuer that is NOT on a loopback host. Default `false`,
+   * and a `ConfigInvalid` at boot without it: the client secret and every
+   * token cross the wire in the open. An option rather than a variable,
+   * because its silent change is a security regression.
+   */
+  readonly allowInsecureIssuer?: boolean;
+  /** What a token's lifetime is measured against (default: the kernel's `systemClock`). */
+  readonly clock?: Clock | undefined;
+};
+/**
+ * The client credentials starter: `TokenSource` over an OAuth 2.0
+ * authorization server, so a service calls another as itself.
+ *
+ * ```ts
+ * Module("Gateway")({ imports: [oauthClient()], provides: [ordersClient] });
+ * ```
+ *
+ * - **Configured from `OAUTH_ISSUER`, `OAUTH_CLIENT_ID` and
+ *   `OAUTH_CLIENT_SECRET`**, each pinned by its option, validated as the graph
+ *   is built. A cleartext issuer off loopback is a `ConfigInvalid` unless
+ *   `allowInsecureIssuer` is pinned.
+ * - **Discovery is lazy**: the first token asks for the issuer's metadata, and
+ *   a failed discovery is asked again by the next. An authorization server
+ *   down at deploy fails the calls that need a token, not the boot.
+ * - **A token is kept per audience and scope** until a minute before it
+ *   expires (half its lifetime, if that is shorter), and callers asking for
+ *   the same one while it is being fetched share that one request. A failure
+ *   is never kept.
+ * - **Every fetch is reported to `Observers`** (`component: "oauth-client"`);
+ *   a token served from memory reports nothing.
+ * - **It contributes the `oauth-client` health check**, failing while the
+ *   last fetch of any audience failed — a rotated secret and an unreachable
+ *   issuer both show there, where a reachability probe would see only the
+ *   second.
+ */
+export declare const oauthClient: <const O extends OAuthClientOptions = Record<never, never>>(options?: O & OptionsAs<O, OAuthClientOptions>) => Module<TokenSource | HealthChecks, ConfigInvalid, EnvReading<Unpinned<O, "issuer", "OAUTH_ISSUER"> | Unpinned<O, "clientId", "OAUTH_CLIENT_ID"> | Unpinned<O, "clientSecret", "OAUTH_CLIENT_SECRET">, MaybePinned<O, "issuer", "OAUTH_ISSUER"> | MaybePinned<O, "clientId", "OAUTH_CLIENT_ID"> | MaybePinned<O, "clientSecret", "OAUTH_CLIENT_SECRET">>>;
+//#endregion
+export type { AccessToken, OAuthClientOptions, TokenRequest, TokenSourceService };

package/dist/index.mjs

@@ -0,0 +1,202 @@
+import { Config, Env, cleartext, cleartextRefused } from "@btravstack/config";
+import { HealthCheckFailed, HealthChecks, Observers, noObserverMember, observed, systemClock } from "@btravstack/core";
+import { Module, Port, Provider } from "@btravstack/di";
+import { ClientSecretBasic, ResponseBodyError, WWWAuthenticateChallengeError, allowInsecureRequests, clientCredentialsGrant, discovery } from "openid-client";
+import { ErrAsync, OkAsync, TaggedError, fromPromise } from "unthrown";
+//#region src/token-source.ts
+/**
+* The authorization server answered, and the answer was no — an OAuth error
+* (`invalid_client`, `invalid_scope`, `invalid_request`, `unauthorized_client`…).
+* A configuration or a registration is wrong, so asking again will not help.
+*
+* It carries the server's `error` code and description, and never the client
+* secret.
+*/
+var TokenRefused = class extends TaggedError("TokenRefused") {};
+/**
+* The authorization server could not be asked: discovery failed, the network
+* did, or it answered with a server error. Transient, so a later call asks
+* again — a failure is never cached.
+*/
+var TokenIssuerUnavailable = class extends TaggedError("TokenIssuerUnavailable") {};
+/**
+* The port an application depends on to call another service as itself: a
+* bearer token for an audience. `oauthClient()` provides it over the client
+* credentials grant; `staticTokenSource` is the in-process stand-in.
+*/
+var TokenSource = class extends Port("TokenSource") {};
+/**
+* The in-process adapter: the same `bearer` for every request, and it cannot
+* fail. The shape `@btravstack/testing`'s `overridden` takes, so a spec swaps
+* the real source under the real root.
+*/
+const staticTokenSource = (bearer) => Provider(TokenSource)({
+	inject: {},
+	value: { token: () => OkAsync({ bearer }) }
+});
+//#endregion
+//#region src/client.ts
+/**
+* How long before its stated expiry a token stops being handed out: it must
+* outlive the request it rides, through the callee's queue and a clock that
+* disagrees with this one. Capped at half a lifetime, so a short-lived token
+* is still reused.
+*/
+const SKEW_MS = 6e4;
+/** The source and its health, built once, so the check reads the same fetches the callers make. */
+var TokenFetches = class extends Port("OAuthTokenFetches") {};
+const fetching = (request) => ({
+	component: "oauth-client",
+	name: "token",
+	attributes: {
+		operation: "token",
+		"btravstack.oauth.audience": request.audience
+	},
+	details: { "btravstack.oauth.scope": request.scope ?? "" }
+});
+/**
+* What the issuer said no with, when the answer was a refusal rather than an
+* outage. A challenge is RFC 6749 §5.2's `401` for a rejected client, which
+* is `invalid_client` by definition.
+*/
+const refusalOf = (cause) => cause instanceof WWWAuthenticateChallengeError ? {
+	error: "invalid_client",
+	description: void 0
+} : cause instanceof ResponseBodyError && cause.status < 500 ? {
+	error: cause.error,
+	description: cause.error_description
+} : void 0;
+const reasonOf = (audience, failure) => failure.tag === "Err" && failure.error._tag === "TokenRefused" ? `${audience}: refused (${failure.error.error})` : `${audience}: the issuer could not be asked`;
+const tokenFetches = (settings, observers, clock) => {
+	let configuration;
+	const cached = /* @__PURE__ */ new Map();
+	const inFlight = /* @__PURE__ */ new Map();
+	const failing = /* @__PURE__ */ new Map();
+	const discover = () => {
+		configuration ??= fromPromise(Promise.resolve().then(() => discovery(new URL(settings.issuer), settings.clientId, void 0, ClientSecretBasic(settings.clientSecret), { execute: settings.insecure ? [allowInsecureRequests] : [] })), (cause) => new TokenIssuerUnavailable({
+			issuer: settings.issuer,
+			cause
+		})).map((config) => {
+			if (settings.insecure) allowInsecureRequests(config);
+			return config;
+		}).tapFailure(() => {
+			configuration = void 0;
+		});
+		return configuration;
+	};
+	const grant = (request, config) => fromPromise(clientCredentialsGrant(config, {
+		audience: request.audience,
+		...request.scope === void 0 ? {} : { scope: request.scope }
+	}), (cause) => {
+		const refusal = refusalOf(cause);
+		return refusal === void 0 ? new TokenIssuerUnavailable({
+			issuer: settings.issuer,
+			cause
+		}) : new TokenRefused({
+			audience: request.audience,
+			...refusal
+		});
+	});
+	const fetchToken = (key, request) => {
+		const asked = clock.now();
+		const fetched = observed(observers, fetching(request), () => discover().flatMap((config) => grant(request, config))).map((response) => {
+			const lifetimeMs = (response.expires_in ?? 0) * 1e3;
+			return {
+				token: { bearer: response.access_token },
+				refreshAt: asked + lifetimeMs - Math.min(SKEW_MS, lifetimeMs / 2)
+			};
+		}).tap((entry) => {
+			inFlight.delete(key);
+			failing.delete(key);
+			cached.set(key, entry);
+		}).tapFailure((failure) => {
+			inFlight.delete(key);
+			failing.set(key, reasonOf(request.audience, failure));
+		}).map((entry) => entry.token);
+		inFlight.set(key, fetched);
+		return fetched;
+	};
+	return {
+		source: { token: (request) => {
+			const key = JSON.stringify([request.audience, request.scope ?? null]);
+			const hit = cached.get(key);
+			if (hit !== void 0 && clock.now() < hit.refreshAt) return OkAsync(hit.token);
+			return inFlight.get(key) ?? fetchToken(key, request);
+		} },
+		health: () => failing.size === 0 ? OkAsync() : ErrAsync(new HealthCheckFailed({ reason: [...failing.values()].join("; ") }))
+	};
+};
+/**
+* The client credentials starter: `TokenSource` over an OAuth 2.0
+* authorization server, so a service calls another as itself.
+*
+* ```ts
+* Module("Gateway")({ imports: [oauthClient()], provides: [ordersClient] });
+* ```
+*
+* - **Configured from `OAUTH_ISSUER`, `OAUTH_CLIENT_ID` and
+*   `OAUTH_CLIENT_SECRET`**, each pinned by its option, validated as the graph
+*   is built. A cleartext issuer off loopback is a `ConfigInvalid` unless
+*   `allowInsecureIssuer` is pinned.
+* - **Discovery is lazy**: the first token asks for the issuer's metadata, and
+*   a failed discovery is asked again by the next. An authorization server
+*   down at deploy fails the calls that need a token, not the boot.
+* - **A token is kept per audience and scope** until a minute before it
+*   expires (half its lifetime, if that is shorter), and callers asking for
+*   the same one while it is being fetched share that one request. A failure
+*   is never kept.
+* - **Every fetch is reported to `Observers`** (`component: "oauth-client"`);
+*   a token served from memory reports nothing.
+* - **It contributes the `oauth-client` health check**, failing while the
+*   last fetch of any audience failed — a rotated secret and an unreachable
+*   issuer both show there, where a reachability probe would see only the
+*   second.
+*/
+const oauthClient = (options = {}) => {
+	const clock = options.clock ?? systemClock;
+	const schema = Config.object({
+		issuer: Config.pinned(options.issuer, Config.url("OAUTH_ISSUER")),
+		clientId: Config.pinned(options.clientId, Config.string("OAUTH_CLIENT_ID")),
+		clientSecret: Config.pinned(options.clientSecret, Config.string("OAUTH_CLIENT_SECRET"))
+	});
+	const fetches = Provider(TokenFetches)({
+		inject: {
+			env: Env,
+			observers: Observers
+		},
+		make: ({ env, observers }) => Config.parse("OAuthClient", schema)(env).flatMap((bound) => {
+			const insecure = cleartext(bound.issuer, options.allowInsecureIssuer ?? false);
+			return insecure === "refused" ? ErrAsync(cleartextRefused({
+				port: "OAuthClient",
+				variable: "OAUTH_ISSUER",
+				option: "allowInsecureIssuer",
+				on: "oauthClient()",
+				what: "it sends the client secret and every token in the open"
+			})) : OkAsync(tokenFetches({
+				...bound,
+				insecure
+			}, observers, clock));
+		})
+	});
+	return Module("OAuthClient")({
+		needs: [Env],
+		provides: [
+			noObserverMember,
+			fetches,
+			Provider(TokenSource)({
+				inject: { fetches: TokenFetches },
+				sync: ({ fetches: built }) => built.source
+			}),
+			Provider.member(HealthChecks)({
+				inject: { fetches: TokenFetches },
+				sync: ({ fetches: built }) => ({
+					name: "oauth-client",
+					check: built.health
+				})
+			})
+		],
+		exports: [TokenSource, HealthChecks]
+	});
+};
+//#endregion
+export { TokenIssuerUnavailable, TokenRefused, TokenSource, oauthClient, staticTokenSource };

package/package.json

@@ -1,6 +1,77 @@
 {
   "name": "@btravstack/oauth-client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.29.0",
+  "description": "A TokenSource port for @btravstack/core: the OAuth 2.0 client credentials grant, so a service calls another as itself — cached per audience until shortly before expiry, one fetch shared by concurrent callers, and a static adapter for tests",
+  "keywords": [
+    "client-credentials",
+    "dependency-injection",
+    "oauth2",
+    "openid-client",
+    "typescript",
+    "unthrown"
+  ],
+  "homepage": "https://github.com/btravstack/btravstack#readme",
+  "bugs": {
+    "url": "https://github.com/btravstack/btravstack/issues"
+  },
+  "license": "MIT",
+  "author": "Benoit TRAVERS <benoit.travers.fr@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/btravstack/btravstack.git",
+    "directory": "packages/oauth-client"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "devDependencies": {
+    "@btravstack/config": "0.29.0",
+    "@btravstack/core": "0.29.0",
+    "@btravstack/di": "0.29.0",
+    "@btravstack/internal-test-infra": "0.0.0",
+    "@btravstack/testing": "0.29.0",
+    "@btravstack/tsconfig": "0.4.0",
+    "@types/node": "26.6.4",
+    "@unthrown/vitest": "5.12.0",
+    "@vitest/coverage-v8": "5.0.3",
+    "openid-client": "6.8.8",
+    "tsdown": "0.23.0",
+    "typescript": "7.0.2",
+    "unthrown": "5.12.0",
+    "vitest": "5.0.3"
+  },
+  "peerDependencies": {
+    "@btravstack/config": "^0.29.0",
+    "@btravstack/core": "^0.29.0",
+    "@btravstack/di": "^0.29.0",
+    "openid-client": "^6",
+    "unthrown": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsdown src/index.ts --format cjs,esm --dts --watch",
+    "test": "vitest run --coverage",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test-d.json"
+  }
 }