@manta-eu/auth 0.1.9 → 0.2.0

package/src/custom-app-user-token.ts

@@ -0,0 +1,100 @@
+import {
+  customAppClientIdProblem,
+  customAppUserDatastoresProblem,
+  customAppUserIdProblem,
+  customAppUserProfileProblem,
+  customAppUserTeamsProblem,
+  customAppUserTokenPath,
+  type CustomAppUserProfile,
+  type CustomAppUserTokenRequest,
+} from "@manta-eu/lib/custom-app";
+import { isPresent } from "@manta-eu/lib/present";
+import { defaultDeployment } from "./default-deployment.js";
+import { type FetchLike, postTo, readJson, RefusedRequestError } from "./http.js";
+
+export type CustomAppUserGrantBase = {
+  /** The custom app's client ID and secret, held only by the app's server. */
+  clientId: string;
+  clientSecret: string;
+  /** Narrows the token to these datastores; leave out to reach every datastore the app reaches. */
+  datastores?: string[];
+  /**
+   * Places the person in these teams of the app's organization, by path like /Sales/EU, as a member of them. An empty
+   * list places them in no team; leaving it out places them in every team the app reaches.
+   */
+  teams?: string[];
+  /** Manta's address, https://app.hiremanta.com unless you name another deployment. */
+  apiUrl?: string;
+};
+
+/** A person your app knows: Manta keeps their chats under your id for them, and no memories. */
+export type IdentifiedCustomAppUser = CustomAppUserGrantBase &
+  CustomAppUserProfile & { userId: string; anonymousId?: never };
+
+/** A visitor your app has not identified, by your session id for them: they chat, and Manta keeps no memories. */
+export type AnonymousCustomAppVisitor = CustomAppUserGrantBase & { anonymousId: string; userId?: never };
+
+export type CustomAppUserAccessTokenOptions = IdentifiedCustomAppUser | AnonymousCustomAppVisitor;
+
+function requestFor(options: CustomAppUserAccessTokenOptions): CustomAppUserTokenRequest {
+  const { clientId, clientSecret, datastores, teams } = options;
+  const narrowed = { ...(datastores === undefined ? {} : { datastores }), ...(teams === undefined ? {} : { teams }) };
+  if (options.userId === undefined) {
+    return { client_id: clientId, client_secret: clientSecret, anonymous_id: options.anonymousId, ...narrowed };
+  }
+  const { userId, name, email, fields } = options;
+  return {
+    client_id: clientId,
+    client_secret: clientSecret,
+    user_id: userId,
+    ...(name === undefined ? {} : { name }),
+    ...(email === undefined ? {} : { email }),
+    ...(fields === undefined ? {} : { fields }),
+    ...narrowed,
+  };
+}
+
+/**
+ * Gets a Manta access token for one of the app's own users, or for an anonymous visitor. It sends the app's client
+ * secret, so call it on the app's server only; the token it returns may go to the browser.
+ */
+export async function customAppUserAccessToken(
+  options: CustomAppUserAccessTokenOptions,
+  fetchImpl: FetchLike = fetch,
+): Promise<string> {
+  if (typeof (globalThis as { document?: unknown }).document !== "undefined") {
+    throw new Error("customAppUserAccessToken runs on your server only: it sends the app's client secret");
+  }
+  const clientIdProblem = customAppClientIdProblem(options.clientId);
+  if (clientIdProblem !== undefined) throw new Error(clientIdProblem);
+  if (!isPresent(options.clientSecret)) throw new Error("The app's client secret is required");
+  const problem =
+    customAppUserIdProblem(options.userId ?? options.anonymousId) ??
+    customAppUserDatastoresProblem(options.datastores) ??
+    customAppUserTeamsProblem(options.teams) ??
+    (options.userId === undefined ? undefined : customAppUserProfileProblem(options));
+  if (problem !== undefined) throw new Error(problem);
+
+  const endpoint = new URL(customAppUserTokenPath, options.apiUrl ?? defaultDeployment.apiUrl).toString();
+  const response = await postTo(
+    endpoint,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Accept: "application/json" },
+      body: JSON.stringify(requestFor(options)),
+    },
+    fetchImpl,
+  );
+  if (!response.ok) {
+    const refusal = await readJson<{ error_description?: string }>(response, endpoint).catch(
+      (): { error_description?: string } => ({}),
+    );
+    throw new RefusedRequestError(
+      `Manta refused the custom app user token (${response.status}). ${refusal.error_description ?? ""}`.trim(),
+      response.status,
+    );
+  }
+  const body = await readJson<{ access_token?: string }>(response, endpoint);
+  if (typeof body.access_token !== "string") throw new Error("Manta answered without an access token");
+  return body.access_token;
+}

package/src/default-deployment.ts

@@ -0,0 +1,15 @@
+// hiremanta.com production, which every SDK entry point targets unless its caller names another deployment.
+export const defaultDeployment = {
+  apiUrl: "https://app.hiremanta.com",
+  keycloakUrl: "https://auth.hiremanta.com",
+  keycloakRealm: "hiremanta-com",
+} as const;
+
+export type Realm = { baseUrl?: string; realm?: string };
+
+export function realmOrDefault(target: Realm = {}): { baseUrl: string; realm: string } {
+  return {
+    baseUrl: (target.baseUrl ?? defaultDeployment.keycloakUrl).replace(/\/+$/, ""),
+    realm: target.realm ?? defaultDeployment.keycloakRealm,
+  };
+}

package/src/device-login.ts

@@ -0,0 +1,181 @@
+import { createHash, randomBytes } from "node:crypto";
+import { type FetchLike, formRequest, isTransientStatus, postTo, readJson } from "./http.js";
+import { tokenEndpoint } from "./token.js";
+
+export type PublicClient = {
+  baseUrl: string;
+  realm: string;
+  clientId: string;
+};
+
+export type DeviceLogin = {
+  deviceCode: string;
+  userCode: string;
+  verificationUri: string;
+  intervalMs: number;
+  expiresInMs: number;
+  codeVerifier: string;
+};
+
+export type PkcePair = { verifier: string; challenge: string };
+
+export type Sleep = (ms: number) => Promise<void>;
+
+const deviceCodeGrant = "urn:ietf:params:oauth:grant-type:device_code";
+
+// RFC 8628 says to add this much whenever the server answers slow_down.
+const slowDownStepMs = 5_000;
+
+const defaultIntervalMs = 5_000;
+
+// RFC 8628 makes expires_in optional, and Keycloak sends ten minutes.
+const defaultExpiresInMs = 600_000;
+
+const sleepFor: Sleep = (ms) => new Promise((done) => setTimeout(done, ms));
+
+export function deviceAuthEndpoint(baseUrl: string, realm: string): string {
+  return `${baseUrl}/realms/${realm}/protocol/openid-connect/auth/device`;
+}
+
+// A public client holds no secret, so PKCE is what ties the token request back to this process.
+export function createPkcePair(): PkcePair {
+  const verifier = randomBytes(32).toString("base64url");
+
+  return { verifier, challenge: createHash("sha256").update(verifier).digest("base64url") };
+}
+
+type DeviceLoginResponse = {
+  device_code?: string;
+  user_code?: string;
+  verification_uri?: string;
+  verification_uri_complete?: string;
+  interval?: number;
+  expires_in?: number;
+};
+
+function readDeviceLogin(body: DeviceLoginResponse, endpoint: string, codeVerifier: string): DeviceLogin {
+  const deviceCode = body.device_code;
+  const userCode = body.user_code;
+  const verificationUri = body.verification_uri_complete ?? body.verification_uri;
+
+  if (!deviceCode || !userCode || !verificationUri) {
+    throw new Error(`the device login response from ${endpoint} is incomplete.`);
+  }
+
+  return {
+    deviceCode,
+    userCode,
+    verificationUri,
+    intervalMs: body.interval ? body.interval * 1000 : defaultIntervalMs,
+    expiresInMs: body.expires_in ? body.expires_in * 1000 : defaultExpiresInMs,
+    codeVerifier,
+  };
+}
+
+// No secret lives on the machine: a developer needs nothing beyond a browser login.
+export async function startDeviceLogin(
+  client: PublicClient,
+  fetchImpl: FetchLike = fetch,
+  pkce: PkcePair = createPkcePair(),
+  scope?: string,
+): Promise<DeviceLogin> {
+  const endpoint = deviceAuthEndpoint(client.baseUrl, client.realm);
+  const request = formRequest({
+    client_id: client.clientId,
+    code_challenge: pkce.challenge,
+    code_challenge_method: "S256",
+    ...(scope ? { scope } : {}),
+  });
+  const response = await postTo(endpoint, request, fetchImpl);
+
+  if (!response.ok) {
+    throw new Error(
+      `${endpoint} refused the device login with status ${response.status}. ` +
+        `Check that the client ${client.clientId} is public and allows the OAuth device flow.`,
+    );
+  }
+
+  return readDeviceLogin(await readJson<DeviceLoginResponse>(response, endpoint), endpoint, pkce.verifier);
+}
+
+function deviceLoginFailure(error: string | undefined, status: number): Error | undefined {
+  if (error === "authorization_pending" || error === "slow_down") return undefined;
+  if (error === "access_denied") return new Error("the login was refused in the browser.");
+  if (error === "expired_token") return new Error("the login code expired. Run the command again.");
+
+  return new Error(`the device login failed with "${error ?? status}".`);
+}
+
+function deviceTokenRequest(client: PublicClient, deviceCode: string, codeVerifier: string): RequestInit {
+  return formRequest({
+    grant_type: deviceCodeGrant,
+    device_code: deviceCode,
+    client_id: client.clientId,
+    code_verifier: codeVerifier,
+  });
+}
+
+export type DeviceTokens = { accessToken: string; refreshToken?: string };
+
+export async function pollForDeviceTokens(
+  client: PublicClient,
+  {
+    deviceCode,
+    codeVerifier,
+    intervalMs = defaultIntervalMs,
+    expiresInMs = defaultExpiresInMs,
+  }: Pick<DeviceLogin, "deviceCode" | "codeVerifier"> & { intervalMs?: number; expiresInMs?: number },
+  {
+    fetchImpl = fetch,
+    sleep = sleepFor,
+    clock = Date.now,
+  }: { fetchImpl?: FetchLike; sleep?: Sleep; clock?: () => number } = {},
+): Promise<DeviceTokens> {
+  const endpoint = tokenEndpoint(client.baseUrl, client.realm);
+  const request = deviceTokenRequest(client, deviceCode, codeVerifier);
+  const deadline = clock() + expiresInMs;
+  let wait = intervalMs;
+
+  for (;;) {
+    // Keycloak answers authorization_pending for ever if nobody opens the link.
+    if (clock() >= deadline) throw new Error("nobody approved the login in time. Run it again.");
+
+    const response = await postTo(endpoint, request, fetchImpl);
+    const body = await readJson<{ access_token?: string; refresh_token?: string; error?: string }>(response, endpoint);
+
+    if (response.ok && body.access_token) {
+      return { accessToken: body.access_token, ...(body.refresh_token ? { refreshToken: body.refresh_token } : {}) };
+    }
+
+    const failure = deviceLoginFailure(body.error, response.status);
+    if (failure) throw failure;
+
+    if (body.error === "slow_down") wait += slowDownStepMs;
+
+    await sleep(wait);
+  }
+}
+
+// A refresh token outlives many access tokens, so a long run renews without a second browser login.
+export async function refreshAccessToken(
+  client: PublicClient,
+  refreshToken: string,
+  fetchImpl: FetchLike = fetch,
+): Promise<DeviceTokens | undefined> {
+  const endpoint = tokenEndpoint(client.baseUrl, client.realm);
+  const request = formRequest({ grant_type: "refresh_token", refresh_token: refreshToken, client_id: client.clientId });
+  const response = await postTo(endpoint, request, fetchImpl);
+
+  // A refused refresh token is terminal and earns a new login; an overloaded Keycloak must not cost one.
+  if (isTransientStatus(response.status)) {
+    throw new Error(`${endpoint} could not renew the token (status ${response.status}).`);
+  }
+
+  if (!response.ok) return undefined;
+
+  const body = await readJson<{ access_token?: string; refresh_token?: string }>(response, endpoint);
+
+  if (!body.access_token) return undefined;
+
+  return { accessToken: body.access_token, refreshToken: body.refresh_token ?? refreshToken };
+}

package/src/http.ts

@@ -0,0 +1,47 @@
+export type FetchLike = (url: string, init: RequestInit) => Promise<Response>;
+
+export function formRequest(fields: Record<string, string>): RequestInit {
+  return {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams(fields).toString(),
+  };
+}
+
+export class RefusedRequestError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+  ) {
+    super(message);
+  }
+}
+
+// Overload and timeout, which are worth repeating; every other refusal is the server's final word.
+export function isTransientStatus(status: number): boolean {
+  return status >= 500 || status === 429 || status === 408;
+}
+
+export async function readJson<T>(response: Response, endpoint: string): Promise<T> {
+  const body = await response.text();
+
+  try {
+    return JSON.parse(body) as T;
+  } catch {
+    throw new Error(`${endpoint} answered status ${response.status} with text, not JSON: ${body}`);
+  }
+}
+
+export async function postTo(endpoint: string, init: RequestInit, fetchImpl: FetchLike = fetch): Promise<Response> {
+  try {
+    return await fetchImpl(endpoint, init);
+  } catch (cause) {
+    throw new Error(`cannot reach ${endpoint}.`, { cause });
+  }
+}
+
+export function describeError(error: unknown): string {
+  if (!(error instanceof Error)) return String(error);
+
+  return error.cause instanceof Error ? `${error.message}\n  caused by: ${error.cause.message}` : error.message;
+}

package/src/index.ts

@@ -0,0 +1,67 @@
+export {
+  ciClientId,
+  cliClientId,
+  clientIdHelp,
+  interactiveLogin,
+  logIn,
+  loginStatus,
+  logOut,
+  publicClientFrom,
+  registerAuthCommands,
+  revokeRefreshToken,
+  userTokenSource,
+  type ClientOptions,
+  type LoginOptions,
+} from "./auth-commands.js";
+export { browserLogin, loginScope } from "./browser-login.js";
+export {
+  defaultCredentialStore,
+  fileCredentialStore,
+  keychainCredentialStore,
+  keychainWithFileFallback,
+  type CredentialStore,
+  type RunSecurity,
+  type SecurityResult,
+  type StoredLogin,
+} from "./credential-store.js";
+export { defaultDeployment } from "./default-deployment.js";
+export {
+  pollForDeviceTokens,
+  refreshAccessToken,
+  startDeviceLogin,
+  type DeviceLogin,
+  type DeviceTokens,
+  type PkcePair,
+  type PublicClient,
+  type Sleep,
+} from "./device-login.js";
+export { describeError, isTransientStatus, postTo, readJson, RefusedRequestError, type FetchLike } from "./http.js";
+export { saveLogin, storedLoginTokenSource } from "./stored-login.js";
+export {
+  cachedToken,
+  mintWithClientCredentials,
+  withRenewal,
+  type ClientCredentials,
+  type RenewableTokenSource,
+  type TokenSource,
+} from "./token.js";
+export { discoveryUrl, issuerUrl, type OidcClient, type Realm } from "./oidc.js";
+export {
+  endWebLogin,
+  finishWebLogin,
+  refreshWebLogin,
+  startWebLogin,
+  webLogoutUrl,
+  type StartWebLoginOptions,
+  type WebLoginStart,
+  type WebLogoutOptions,
+  type WebTokens,
+} from "./web-login.js";
+export { webLoginRoutes, type WebLoginRoutes, type WebLoginRoutesOptions, type WebSession } from "./web-routes.js";
+export {
+  customAppUserAccessToken,
+  type AnonymousCustomAppVisitor,
+  type CustomAppUserAccessTokenOptions,
+  type CustomAppUserGrantBase,
+  type IdentifiedCustomAppUser,
+} from "./custom-app-user-token.js";

package/src/oidc.ts

@@ -0,0 +1,40 @@
+import * as oidc from "openid-client";
+import { type Realm, realmOrDefault } from "./default-deployment.js";
+import type { PublicClient } from "./device-login.js";
+import type { FetchLike } from "./http.js";
+
+export type { Realm };
+
+/** A client with a secret is an app's own server; without one it is a public client, like the CLIs. */
+export type OidcClient = Omit<PublicClient, "baseUrl" | "realm"> & Realm & { clientSecret?: string };
+
+/** The realm's issuer, the `iss` of every token it signs. */
+export function issuerUrl(target?: Realm): string {
+  const { baseUrl, realm } = realmOrDefault(target);
+  return `${baseUrl}/realms/${realm}`;
+}
+
+/** The OpenID Connect discovery document most libraries configure themselves from. */
+export function discoveryUrl(target?: Realm): string {
+  return `${issuerUrl(target)}/.well-known/openid-configuration`;
+}
+
+// Keycloak's endpoints are fixed under the issuer, so no discovery request precedes each call.
+export function oidcConfiguration(client: OidcClient, fetchImpl?: FetchLike): oidc.Configuration {
+  const issuer = issuerUrl(client);
+  const endpoint = (name: string) => `${issuer}/protocol/openid-connect/${name}`;
+  const config = new oidc.Configuration(
+    {
+      issuer,
+      authorization_endpoint: endpoint("auth"),
+      token_endpoint: endpoint("token"),
+      end_session_endpoint: endpoint("logout"),
+      revocation_endpoint: endpoint("revoke"),
+    },
+    client.clientId,
+    undefined,
+    client.clientSecret ? oidc.ClientSecretPost(client.clientSecret) : oidc.None(),
+  );
+  if (fetchImpl) config[oidc.customFetch] = (url, options) => fetchImpl(url, options as RequestInit);
+  return config;
+}

package/src/stored-login.ts

@@ -0,0 +1,63 @@
+import type { CredentialStore } from "./credential-store.js";
+import { type DeviceTokens, type PublicClient, refreshAccessToken } from "./device-login.js";
+import { describeError, type FetchLike } from "./http.js";
+import { accessTokenUsername, cachedToken, type RenewableTokenSource } from "./token.js";
+
+// Keycloak may rotate the refresh token on every renewal, so each new one replaces the stored one.
+export async function saveLogin(store: CredentialStore, client: PublicClient, tokens: DeviceTokens): Promise<boolean> {
+  if (!tokens.refreshToken) return false;
+
+  const username = accessTokenUsername(tokens.accessToken);
+
+  await store.write(client, { refreshToken: tokens.refreshToken, ...(username ? { username } : {}) });
+
+  return true;
+}
+
+// Renews from the stored login, and only asks for a new one when Keycloak refuses it; a network error keeps it.
+export function storedLoginTokenSource({
+  client,
+  store,
+  login,
+  warn = console.error,
+  fetchImpl = fetch,
+  clock = Date.now,
+}: {
+  client: PublicClient;
+  store: CredentialStore;
+  login: () => Promise<DeviceTokens>;
+  warn?: (message: string) => void;
+  fetchImpl?: FetchLike;
+  clock?: () => number;
+}): RenewableTokenSource {
+  // A store it cannot write, e.g. a read-only $HOME, costs the next run a login instead of failing this one.
+  async function keep(tokens: DeviceTokens): Promise<void> {
+    await saveLogin(store, client, tokens).catch((error: unknown) =>
+      warn(`could not store the login, so the next run may ask for another: ${describeError(error)}`),
+    );
+  }
+
+  async function renewOrLogIn(): Promise<string> {
+    const stored = await store.read(client);
+
+    if (stored) {
+      const renewed = await refreshAccessToken(client, stored.refreshToken, fetchImpl);
+
+      if (renewed) {
+        await keep(renewed);
+        return renewed.accessToken;
+      }
+
+      await store
+        .remove(client)
+        .catch((error: unknown) => warn(`could not delete the refused login: ${describeError(error)}`));
+    }
+
+    const tokens = await login();
+    await keep(tokens);
+
+    return tokens.accessToken;
+  }
+
+  return cachedToken(renewOrLogIn, clock);
+}

package/src/token.ts

@@ -0,0 +1,154 @@
+import { type Realm, realmOrDefault } from "./default-deployment.js";
+import { type FetchLike, formRequest, postTo, RefusedRequestError } from "./http.js";
+
+export type ClientCredentials = Realm & {
+  clientId: string;
+  clientSecret: string;
+  scope?: string;
+};
+
+export type TokenSource = () => Promise<string>;
+
+// A source that can drop its cached token, so a request the API rejected is retried with a fresh one.
+export type RenewableTokenSource = TokenSource & { renew: (rejected?: string) => void };
+
+function isRenewable(token: TokenSource): token is RenewableTokenSource {
+  return typeof (token as Partial<RenewableTokenSource>).renew === "function";
+}
+
+// A token revoked or expired early answers 401 once; renewing and retrying once is what Claude Code does for MCP.
+export async function withRenewal<T>(token: TokenSource, call: (accessToken: string) => Promise<T>): Promise<T> {
+  let accessToken: string | undefined;
+  try {
+    accessToken = await token();
+    return await call(accessToken);
+  } catch (error) {
+    if (!(error instanceof RefusedRequestError && error.status === 401) || !isRenewable(token)) throw error;
+
+    token.renew(accessToken);
+
+    return call(await token());
+  }
+}
+
+// Re-mint before Keycloak's own exp, so an in-flight request never races an expired token.
+export const tokenExpiryBufferMs = 60_000;
+
+// The exp claim did not parse, so the token gets a short life rather than none.
+export const unparsableTokenTtlMs = 30_000;
+
+export function tokenEndpoint(baseUrl: string, realm: string): string {
+  return `${baseUrl}/realms/${realm}/protocol/openid-connect/token`;
+}
+
+// atob and TextDecoder, not Buffer, so the token helpers also run in a browser.
+function decodeBase64Url(value: string): string {
+  const base64 = value
+    .replace(/-/g, "+")
+    .replace(/_/g, "/")
+    .padEnd(Math.ceil(value.length / 4) * 4, "=");
+  return new TextDecoder().decode(Uint8Array.from(atob(base64), (char) => char.charCodeAt(0)));
+}
+
+// Reads the claims without checking the signature: callers only use them to schedule and to label.
+function unverifiedClaims(accessToken: string): Record<string, unknown> {
+  const payload = accessToken.split(".")[1];
+
+  if (!payload) return {};
+
+  try {
+    const claims: unknown = JSON.parse(decodeBase64Url(payload));
+
+    return typeof claims === "object" && claims !== null ? (claims as Record<string, unknown>) : {};
+  } catch {
+    return {};
+  }
+}
+
+export function accessTokenExpiresAt(accessToken: string, now: number): number {
+  const exp = unverifiedClaims(accessToken).exp;
+
+  return typeof exp === "number" ? exp * 1000 - tokenExpiryBufferMs : now + unparsableTokenTtlMs;
+}
+
+export function accessTokenUsername(accessToken: string): string | undefined {
+  const claims = unverifiedClaims(accessToken);
+  const name = claims.preferred_username ?? claims.email;
+
+  return typeof name === "string" ? name : undefined;
+}
+
+export function isFresh(expiresAt: number, now: number): boolean {
+  return expiresAt > now;
+}
+
+function clientCredentialsRequest({ clientId, clientSecret, scope }: ClientCredentials): RequestInit {
+  return formRequest({
+    grant_type: "client_credentials",
+    client_id: clientId,
+    client_secret: clientSecret,
+    ...(scope ? { scope } : {}),
+  });
+}
+
+function readAccessToken(body: unknown, realm: string): string {
+  const accessToken = (body as { access_token?: unknown }).access_token;
+
+  if (typeof accessToken !== "string") {
+    throw new Error(`the Keycloak response for realm ${realm} carries no access_token.`);
+  }
+
+  return accessToken;
+}
+
+export async function mintWithClientCredentials(
+  credentials: ClientCredentials,
+  fetchImpl: FetchLike = fetch,
+): Promise<string> {
+  const { baseUrl, realm } = realmOrDefault(credentials);
+  const endpoint = tokenEndpoint(baseUrl, realm);
+  const response = await postTo(endpoint, clientCredentialsRequest(credentials), fetchImpl);
+
+  if (!response.ok) {
+    const { error } = (await response.json().catch(() => ({}))) as { error?: unknown };
+    throw new Error(
+      `Keycloak refused the client credentials for realm ${realm} with status ${response.status}. ` +
+        (error === "unauthorized_client"
+          ? "This client may not mint tokens on its own: for a custom app, turn on Machine access."
+          : `Check the client id and the secret against ${endpoint}.`),
+    );
+  }
+
+  return readAccessToken(await response.json(), realm);
+}
+
+export function cachedToken(mint: TokenSource, clock: () => number = Date.now): RenewableTokenSource {
+  let held: { token: string; expiresAt: number } | undefined;
+  // Shared, so callers racing an expired token start one mint: parallel refreshes would spend one refresh token.
+  let minting: Promise<string> | undefined;
+
+  const mintOnce = async () => {
+    const token = await mint();
+    // A device login blocks until the browser answers, so `now` is already stale here.
+    held = { token, expiresAt: accessTokenExpiresAt(token, clock()) };
+
+    return token;
+  };
+
+  const source = async () => {
+    if (held && isFresh(held.expiresAt, clock())) return held.token;
+
+    const current = (minting ??= mintOnce().finally(() => {
+      if (minting === current) minting = undefined;
+    }));
+
+    return current;
+  };
+
+  return Object.assign(source, {
+    // Keeps an in-flight mint, so racing 401s join it, and a newer token than the one refused.
+    renew: (rejected?: string) => {
+      if (rejected === undefined || held?.token === rejected) held = undefined;
+    },
+  });
+}