@manta-eu/auth 0.1.8 → 0.1.10

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,60 @@
+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";

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,151 @@
+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) {
+    throw new Error(
+      `Keycloak refused the client credentials for realm ${realm} with status ${response.status}. ` +
+        `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;
+    },
+  });
+}

package/src/web-login.ts

@@ -0,0 +1,106 @@
+import * as oidc from "openid-client";
+import { isTransientStatus, type FetchLike } from "./http.js";
+import { type OidcClient, oidcConfiguration } from "./oidc.js";
+
+export type WebLoginStart = { url: string; state: string; verifier: string };
+
+export type WebTokens = { accessToken: string; refreshToken?: string; idToken?: string };
+
+export type StartWebLoginOptions = {
+  redirectUri: string;
+  offlineAccess?: boolean;
+  scope?: string;
+  idpHint?: string;
+};
+
+export type WebLogoutOptions = { idToken?: string; postLogoutRedirectUri?: string; state?: string };
+
+function tokensOf(response: oidc.TokenEndpointResponse): WebTokens {
+  return {
+    accessToken: response.access_token,
+    ...(response.refresh_token ? { refreshToken: response.refresh_token } : {}),
+    ...(response.id_token ? { idToken: response.id_token } : {}),
+  };
+}
+
+function statusOf(error: unknown): number | undefined {
+  if (error instanceof oidc.ResponseBodyError) return error.status;
+  const cause = error instanceof Error ? error.cause : undefined;
+  return cause instanceof Response ? cause.status : undefined;
+}
+
+/** Starts a sign-in; keep `state` and `verifier` in the person's session for the callback. */
+export async function startWebLogin(client: OidcClient, options: StartWebLoginOptions): Promise<WebLoginStart> {
+  const { redirectUri, offlineAccess = false, idpHint } = options;
+  const verifier = oidc.randomPKCECodeVerifier();
+  const state = oidc.randomState();
+  const url = oidc.buildAuthorizationUrl(oidcConfiguration(client), {
+    redirect_uri: redirectUri,
+    scope: options.scope ?? (offlineAccess ? "openid offline_access" : "openid"),
+    state,
+    code_challenge: await oidc.calculatePKCECodeChallenge(verifier),
+    code_challenge_method: "S256",
+    ...(idpHint ? { kc_idp_hint: idpHint } : {}),
+  });
+
+  return { url: url.toString(), state, verifier };
+}
+
+/** Trades the callback for tokens; pass `callbackUrl` and `state` to have them checked too. */
+export async function finishWebLogin(
+  client: OidcClient,
+  login: { code: string; redirectUri: string; verifier: string; callbackUrl?: string; state?: string },
+  fetchImpl?: FetchLike,
+): Promise<WebTokens> {
+  const { code, redirectUri, verifier, callbackUrl, state } = login;
+  // The library sends the callback URL without its query as redirect_uri, so the registered one carries the answer.
+  const currentUrl = new URL(redirectUri);
+  currentUrl.search =
+    callbackUrl === undefined ? new URLSearchParams({ code }).toString() : new URL(callbackUrl).search;
+  const response = await oidc.authorizationCodeGrant(oidcConfiguration(client, fetchImpl), currentUrl, {
+    pkceCodeVerifier: verifier,
+    expectedState: state ?? oidc.skipStateCheck,
+  });
+  return tokensOf(response);
+}
+
+/** Renews the access token; store the rotated refresh token it returns. `undefined` means sign in again. */
+export async function refreshWebLogin(
+  client: OidcClient,
+  refreshToken: string,
+  fetchImpl?: FetchLike,
+): Promise<WebTokens | undefined> {
+  try {
+    const renewed = tokensOf(await oidc.refreshTokenGrant(oidcConfiguration(client, fetchImpl), refreshToken));
+    return { ...renewed, refreshToken: renewed.refreshToken ?? refreshToken };
+  } catch (error) {
+    const status = statusOf(error);
+    // A refused refresh token is terminal and earns a new login; an overloaded Keycloak must not cost one.
+    if (status === undefined || isTransientStatus(status)) throw error;
+    return undefined;
+  }
+}
+
+/** Where to send the browser to sign out of Manta too; pass the latest `idToken` to skip Keycloak's prompt. */
+export function webLogoutUrl(client: OidcClient, options: WebLogoutOptions = {}): string {
+  const { idToken, postLogoutRedirectUri, state } = options;
+  return oidc
+    .buildEndSessionUrl(oidcConfiguration(client), {
+      ...(idToken ? { id_token_hint: idToken } : {}),
+      ...(postLogoutRedirectUri ? { post_logout_redirect_uri: postLogoutRedirectUri } : {}),
+      ...(state ? { state } : {}),
+    })
+    .toString();
+}
+
+/** Revokes the refresh token, ending this app's session only; `false` when Keycloak did not confirm. */
+export async function endWebLogin(client: OidcClient, refreshToken: string, fetchImpl?: FetchLike): Promise<boolean> {
+  try {
+    await oidc.tokenRevocation(oidcConfiguration(client, fetchImpl), refreshToken, {
+      token_type_hint: "refresh_token",
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}