@typeship-ax/cli 0.22.0 → 0.23.1

package/src/index.ts

@@ -1,5 +1,5 @@
-// typeship — client entry point.
-// Generated by typeship — https://typeship.dev
+// Typeship — client entry point.
+// Generated by Typeship — https://typeship.dev
 
 import {
   HttpCore,
@@ -10,34 +10,33 @@ import {
   type RequestContext,
   bearerAuth,
 } from "./core/http.js";
-import { DEFS, SCHEMAS } from "./schemas.js";
 
-import { GenerateResource } from "./resources/generate.js";
 import { ProjectsResource } from "./resources/projects.js";
 import { SpecsResource } from "./resources/specs.js";
 import { SpecRevisionsResource } from "./resources/spec-revisions.js";
 import { TargetsResource } from "./resources/targets.js";
-import { DraftsResource } from "./resources/drafts.js";
-import { ReleasesResource } from "./resources/releases.js";
 import { DeliveriesResource } from "./resources/deliveries.js";
-import { PublicationsResource } from "./resources/publications.js";
 import { GenerationsResource } from "./resources/generations.js";
+import { DraftsResource } from "./resources/drafts.js";
+import { ReleasesResource } from "./resources/releases.js";
 import { FilesResource } from "./resources/files.js";
+import { PackagesResource } from "./resources/packages.js";
 import { OrganizationResource } from "./resources/organization.js";
 import { ApiKeysResource } from "./resources/api-keys.js";
 
 /** This package's version, also sent as the `User-Agent`. */
-export const VERSION = "0.22.0";
-const USER_AGENT = "@typeship-ax/cli/0.22.0";
+export const VERSION = "0.23.1";
+const USER_AGENT = "@typeship-ax/cli/0.23.1";
 
 export interface ClientOptions {
   /** Override the server URL. Default: `https://typeship.dev/api/v1` */
   baseUrl?: string;
   /**
    * Sent as `Authorization: Bearer <token>`. Pass a callback for tokens that expire; it is resolved
-   * before every attempt.
+   * before every attempt, and after a 401 it is called once more with `{ rejected: true }` so it
+   * can refresh instead of returning the rejected token.
    */
-  bearerToken?: string | (() => string | Promise<string>);
+  bearerToken?: AuthValue;
   /**
    * Credentials keyed by the Spec's security scheme names. Only one complete alternative is sent
    * for each operation. Named values take precedence over convenience options.
@@ -45,10 +44,15 @@ export interface ClientOptions {
   credentials?: {
     "apiKey"?: AuthValue;
   };
-  /** Per-attempt timeout in milliseconds. Default: 30000. */
+  /** Per-attempt timeout in milliseconds. Default: 60000. */
   timeoutMs?: number;
   /** Retries after the first attempt (retryable failures only). Default: 2. */
   maxRetries?: number;
+  /**
+   * The longest wait a server may request (Retry-After, x-ratelimit-reset) that a retry honors; a
+   * longer one fails the call with the reset time. Default: 60000.
+   */
+  maxRetryWaitMs?: number;
   /** Custom fetch implementation (proxies, testing, instrumentation). */
   fetch?: typeof fetch;
   /** Headers sent with every request. */
@@ -83,7 +87,7 @@ export interface ClientOptions {
 }
 
 /**
- * typeship — v0.22.0
+ * Typeship — v0.23.1
  *
  * Resolve an OpenAPI or GraphQL Spec, diagnose it, and keep every
  * selected CLI, MCP, and SDK Target current.
@@ -100,21 +104,22 @@ export interface ClientOptions {
  * petstore Spec is a runnable sample.
  */
 export class TypeshipClient {
-  readonly generate: GenerateResource;
   readonly projects: ProjectsResource;
   readonly specs: SpecsResource;
   readonly specRevisions: SpecRevisionsResource;
   readonly targets: TargetsResource;
-  readonly drafts: DraftsResource;
-  readonly releases: ReleasesResource;
   readonly deliveries: DeliveriesResource;
-  readonly publications: PublicationsResource;
   readonly generations: GenerationsResource;
+  readonly drafts: DraftsResource;
+  readonly releases: ReleasesResource;
   readonly files: FilesResource;
+  readonly packages: PackagesResource;
   readonly organization: OrganizationResource;
   readonly apiKeys: ApiKeysResource;
+  private readonly _options: ClientOptions;
 
   constructor(options: ClientOptions = {}) {
+    this._options = options;
     // Identifies this package to the API (ignored by browsers, which
     // control their own User-Agent); override via defaultHeaders.
     const headers: Record<string, AuthValue> = { "User-Agent": USER_AGENT, ...options.defaultHeaders };
@@ -157,30 +162,42 @@ export class TypeshipClient {
       query,
       credentials,
       fetch: options.fetch ?? fetch,
-      timeoutMs: options.timeoutMs ?? 30_000,
+      timeoutMs: options.timeoutMs ?? 60_000,
       maxRetries: options.maxRetries ?? 2,
+      maxRetryWaitMs: options.maxRetryWaitMs,
       onRequest: options.onRequest,
       onResponse: options.onResponse,
       onError: options.onError,
       debug,
       validate,
-      schemas: validate ? SCHEMAS : undefined,
-      schemaDefs: validate ? DEFS : undefined,
+      // Loaded on the first validated request, so the schema table costs
+      // nothing when validation is off.
+      loadSchemas: validate ? () => import("./schemas.js") : undefined,
     });
-    this.generate = new GenerateResource(core);
     this.projects = new ProjectsResource(core);
     this.specs = new SpecsResource(core);
     this.specRevisions = new SpecRevisionsResource(core);
     this.targets = new TargetsResource(core);
-    this.drafts = new DraftsResource(core);
-    this.releases = new ReleasesResource(core);
     this.deliveries = new DeliveriesResource(core);
-    this.publications = new PublicationsResource(core);
     this.generations = new GenerationsResource(core);
+    this.drafts = new DraftsResource(core);
+    this.releases = new ReleasesResource(core);
     this.files = new FilesResource(core);
+    this.packages = new PackagesResource(core);
     this.organization = new OrganizationResource(core);
     this.apiKeys = new ApiKeysResource(core);
   }
+
+  /**
+   * A client with this client's configuration and only these credentials,
+   * for a server acting on behalf of many users. Nothing is inherited from
+   * this client's credentials. The copy shares the configured fetch.
+   */
+  withCredentials(credentials: Pick<ClientOptions, "bearerToken" | "credentials">): TypeshipClient {
+    const options: Record<string, unknown> = { ...this._options };
+    for (const key of ["bearerToken","credentials"]) delete options[key];
+    return new TypeshipClient({ ...options, ...credentials } as ClientOptions);
+  }
 }
 
 export * from "./types.js";
@@ -188,6 +205,7 @@ export * from "./errors.js";
 export {
   formatDebugEvent,
   type AuthValue,
+  type CredentialContext,
   type DebugEvent,
   type RequestContext,
   type RequestOptions,
@@ -195,16 +213,15 @@ export {
 } from "./core/http.js";
 export { Page, PagePromise } from "./core/pagination.js";
 
-export * from "./resources/generate.js";
 export * from "./resources/projects.js";
 export * from "./resources/specs.js";
 export * from "./resources/spec-revisions.js";
 export * from "./resources/targets.js";
-export * from "./resources/drafts.js";
-export * from "./resources/releases.js";
 export * from "./resources/deliveries.js";
-export * from "./resources/publications.js";
 export * from "./resources/generations.js";
+export * from "./resources/drafts.js";
+export * from "./resources/releases.js";
 export * from "./resources/files.js";
+export * from "./resources/packages.js";
 export * from "./resources/organization.js";
 export * from "./resources/api-keys.js";

package/src/named-credentials.ts

@@ -34,7 +34,7 @@ export function resolveNamedCredentials(schemes: CredentialSchemes, layers: { na
   for (const layer of layers) {
     for (const [name, scheme] of Object.entries(schemes)) {
       for (const option of scheme.options) {
-        if (option === "clientCredentials") continue;
+        if (option === "clientCredentials" || option === "refreshToken") continue;
         const value = layer.options?.[option];
         if (value !== undefined) resolved[name] = value as NamedCredential;
       }
@@ -52,6 +52,28 @@ export function namedCredentialAvailability(schemes: CredentialSchemes, options:
   return options;
 }
 
+/** The schemes an interactive OAuth login session authenticates by name. When
+ * the API also declares a separate non-OAuth bearer scheme, the convenience
+ * bearer token belongs to that scheme, so the session must be passed to each
+ * OAuth scheme by name. Empty: the session is the convenience bearer token. */
+export function oauthSessionSchemes(schemes: CredentialSchemes): string[] {
+  return Object.entries(schemes).filter(([, scheme]) => (scheme.options.includes("clientCredentials") || scheme.options.includes("refreshToken")) && !scheme.options.includes("bearerToken")).map(([name]) => name);
+}
+
+/** Whether resolved client options satisfy one complete credential alternative
+ * of an operation. Returns null when satisfied (or when no credential is
+ * required); otherwise the named alternatives and the schemes each lacks. */
+export function missingCredentials(schemes: CredentialSchemes, credentialOptions: string[][] | undefined, options: Record<string, unknown>): { alternatives: string[][]; missing: string[][] } | null {
+  const supplied = (key: string, value: unknown): boolean => typeof value === "function" || (typeof value === "string" && value.length > 0)
+    || (key === "clientCredentials" && value !== null && typeof value === "object")
+    || (value !== null && typeof value === "object" && "username" in value && "password" in value && typeof value.username === "string" && value.username.length > 0 && typeof value.password === "string" && value.password.length > 0);
+  const named = Object.fromEntries(Object.entries((options.credentials ?? {}) as Record<string, unknown>).filter(([name, value]) => supplied(name, value))) as NamedCredentials;
+  const available = namedCredentialAvailability(schemes, new Set(Object.keys(options).filter((key) => key !== "credentials" && supplied(key, options[key]))), named);
+  if (credentialOptions?.some((alternative) => alternative.length > 0 && alternative.every((option) => available.has(option)))) return null;
+  const alternatives = (credentialOptions ?? []).filter((alternative) => alternative.length > 0 && alternative.every((option) => option.startsWith("credentials."))).map((alternative) => alternative.map((option) => option.slice("credentials.".length)));
+  return { alternatives, missing: alternatives.map((alternative) => alternative.filter((name) => !available.has("credentials." + name))) };
+}
+
 /** Bound file/stdin reads before allocating a full credential document. */
 export function readNamedCredentialsFile(input: string, schemes: CredentialSchemes): NamedCredentials {
   let fd: number | undefined;
@@ -72,3 +94,46 @@ export function readNamedCredentialsFile(input: string, schemes: CredentialSchem
   } finally { if (fd !== undefined && input !== "-") closeSync(fd); }
   return parseNamedCredentials(Buffer.concat(chunks).toString("utf8"), schemes);
 }
+
+const HEADER_NAME = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
+const TRANSPORT_HEADERS = new Set(["host", "content-length", "content-type", "transfer-encoding", "connection"]);
+
+/** Extra request headers from repeated `--header "Name: value"` flags and a
+ * `<PREFIX>_HEADERS` variable (a JSON object, or one `Name: value` per line).
+ * The escape hatch for credentials a spec does not declare. Flags win over
+ * the environment; values never appear in errors. */
+export function parseExtraHeaders(environment: string | undefined, flags: readonly string[], variable: string): Record<string, string> {
+  const entries: [string, string][] = [];
+  const line = (text: string, source: string) => {
+    const colon = text.indexOf(":");
+    if (colon <= 0) throw new Error(source + " expects \"Name: value\".");
+    entries.push([text.slice(0, colon).trim(), text.slice(colon + 1).trim()]);
+  };
+  if (environment !== undefined && environment.trim()) {
+    const text = environment.trim();
+    if (text.startsWith("{")) {
+      let value: unknown;
+      try { value = JSON.parse(text); } catch { throw new Error(variable + " must be a JSON object of header names to values, or one \"Name: value\" per line."); }
+      if (!value || typeof value !== "object" || Array.isArray(value) || Object.values(value).some((entry) => typeof entry !== "string")) throw new Error(variable + " must map header names to string values.");
+      entries.push(...Object.entries(value as Record<string, string>));
+    } else for (const part of text.split(/\r?\n/)) if (part.trim()) line(part, variable);
+  }
+  for (const flag of flags) line(flag, "--header");
+  const headers: Record<string, string> = {};
+  for (const [name, value] of entries) {
+    if (!HEADER_NAME.test(name)) throw new Error("Header names may contain only token characters. Check --header and " + variable + ".");
+    if (TRANSPORT_HEADERS.has(name.toLowerCase())) throw new Error("The " + name + " header is set by the client and cannot be overridden.");
+    if (/[\r\n\0]/.test(value)) throw new Error("Header values cannot contain line breaks. Check --header and " + variable + ".");
+    for (const existing of Object.keys(headers)) if (existing.toLowerCase() === name.toLowerCase()) delete headers[existing];
+    headers[name] = value;
+  }
+  return headers;
+}
+
+/** Apply extra headers last, replacing any header of the same name. */
+export function applyExtraHeaders(target: Record<string, string>, extra: Record<string, string>): void {
+  for (const [name, value] of Object.entries(extra)) {
+    for (const existing of Object.keys(target)) if (existing.toLowerCase() === name.toLowerCase()) delete target[existing];
+    target[name] = value;
+  }
+}

package/src/oauth-login.ts

@@ -1,9 +1,16 @@
 import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
 import { createServer } from "node:http";
-import { oauthJsonRequest, OAuthResponseError } from "./oauth-request.js";
+import { oauthJsonRequest, OAuthResponseError, providerErrorOf } from "./oauth-request.js";
+
+/** Browser OAuth login did not complete; the message names the cause. */
+export class OAuthLoginError extends Error {
+  constructor(message?: string) { super(message); this.name = "OAuthLoginError"; }
+}
 
 export interface OAuthLoginConfig {
-  issuer: string;
+  /** Exact issuer, when the provider publishes metadata. Without one, the
+   * explicit authorization and token URLs from the API Spec are used. */
+  issuer?: string | null;
   clientId: string;
   discoveryUrl?: string;
   authorizationUrl?: string;
@@ -21,7 +28,7 @@ export interface OAuthLoginSession {
   accessToken: string;
   refreshToken?: string;
   expiresAt?: number;
-  issuer: string;
+  issuer?: string;
   clientId: string;
   tokenUrl: string;
   /** The actual native callback used for this exchange, including its port. */
@@ -41,14 +48,19 @@ function endpoint(value: string): URL {
   const url = new URL(value);
   const loopback = ["127.0.0.1", "[::1]", "localhost"].includes(url.hostname);
   if ((url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) || url.username || url.password || url.hash) {
-    throw new Error("OAuth endpoints require HTTPS without credentials or fragments; loopback HTTP is allowed for development.");
+    throw new OAuthLoginError("OAuth endpoints require HTTPS without credentials or fragments; loopback HTTP is allowed for development.");
   }
   return url;
 }
 
 async function metadata(config: OAuthLoginConfig, signal: AbortSignal) {
+  // The Spec's authorizationCode flow names both endpoints; no discovery.
+  if (!config.issuer) {
+    if (config.authorizationUrl && config.tokenUrl) return { authorizationUrl: endpoint(config.authorizationUrl), tokenUrl: endpoint(config.tokenUrl).href };
+    throw new OAuthLoginError("Browser login needs the provider's authorization and token URLs, or an issuer that publishes them.");
+  }
   const issuer = endpoint(config.issuer);
-  if (issuer.search) throw new Error("The OAuth issuer must not contain a query.");
+  if (issuer.search) throw new OAuthLoginError("The OAuth issuer must not contain a query.");
   const path = issuer.pathname.replace(/\/$/, "");
   const urls = config.discoveryUrl ? [config.discoveryUrl] : [
     issuer.origin + "/.well-known/oauth-authorization-server" + path,
@@ -63,13 +75,13 @@ async function metadata(config: OAuthLoginConfig, signal: AbortSignal) {
     }
     if (response.status !== 200) continue;
     const data = response.data!;
-    if (data.issuer !== config.issuer) throw new Error("OAuth discovery returned a different issuer. Check the issuer and discovery URL.");
+    if (data.issuer !== config.issuer) throw new OAuthLoginError("OAuth discovery returned a different issuer. Check the issuer and discovery URL.");
     if (Array.isArray(data.code_challenge_methods_supported) && !data.code_challenge_methods_supported.includes("S256")) {
-      throw new Error("The provider does not advertise S256 PKCE support.");
+      throw new OAuthLoginError("The provider does not advertise S256 PKCE support.");
     }
     const authorizationUrl = config.authorizationUrl ?? data.authorization_endpoint;
     const tokenUrl = config.tokenUrl ?? data.token_endpoint;
-    if (typeof authorizationUrl !== "string" || typeof tokenUrl !== "string") throw new Error("Browser login requires authorization and token endpoints.");
+    if (typeof authorizationUrl !== "string" || typeof tokenUrl !== "string") throw new OAuthLoginError("Browser login requires authorization and token endpoints.");
     return {
       authorizationUrl: endpoint(authorizationUrl), tokenUrl: endpoint(tokenUrl).href,
       ...(typeof data.revocation_endpoint === "string" ? { revocationUrl: endpoint(data.revocation_endpoint).href } : {}),
@@ -80,20 +92,20 @@ async function metadata(config: OAuthLoginConfig, signal: AbortSignal) {
   if (config.authorizationUrl && config.tokenUrl) return {
     authorizationUrl: endpoint(config.authorizationUrl), tokenUrl: endpoint(config.tokenUrl).href,
   };
-  throw new Error("Could not discover OAuth endpoints. Check the issuer or provide explicit authorization and token URLs.");
+  throw new OAuthLoginError("Could not discover OAuth endpoints. Check the issuer or provide explicit authorization and token URLs.");
 }
 
 /** Authorization Code + S256 PKCE for a public native client. The listener
  * binds only a loopback IP, verifies state/issuer, and closes on every path. */
 export async function oauthBrowserLogin(config: OAuthLoginConfig, interaction: OAuthLoginInteraction): Promise<OAuthLoginSession> {
-  if (!config.clientId.trim()) throw new Error("Browser login requires a public client ID.");
-  if (config.organization && (!["organization", "organization_id"].includes(config.organization.parameter) || typeof config.organization.id !== "string" || !config.organization.id || config.organization.id.length > 512 || /\s|[\u0000-\u001F\u007F]/.test(config.organization.id))) throw new Error("Organization selection requires a supported parameter and a nonempty organization ID without whitespace.");
+  if (!config.clientId.trim()) throw new OAuthLoginError("Browser login requires a public client ID.");
+  if (config.organization && (!["organization", "organization_id"].includes(config.organization.parameter) || typeof config.organization.id !== "string" || !config.organization.id || config.organization.id.length > 512 || /\s|[\u0000-\u001F\u007F]/.test(config.organization.id))) throw new OAuthLoginError("Organization selection requires a supported parameter and a nonempty organization ID without whitespace.");
   const signal = AbortSignal.any([interaction.signal ?? new AbortController().signal, AbortSignal.timeout(interaction.timeoutMs ?? 600_000)]);
   signal.throwIfAborted();
   const endpoints = await metadata(config, signal);
   const redirect = new URL(config.redirectUri ?? "http://127.0.0.1/callback");
   if (redirect.protocol !== "http:" || !["127.0.0.1", "[::1]"].includes(redirect.hostname) || redirect.username || redirect.password || redirect.search || redirect.hash) {
-    throw new Error("The OAuth redirect must be an HTTP loopback IP URL without credentials, query, or fragment.");
+    throw new OAuthLoginError("The OAuth redirect must be an HTTP loopback IP URL without credentials, query, or fragment.");
   }
   const verifier = randomBytes(32).toString("base64url");
   const state = randomBytes(32).toString("base64url");
@@ -120,24 +132,27 @@ export async function oauthBrowserLogin(config: OAuthLoginConfig, interaction: O
       response.writeHead(400).end("Invalid login state. Return to the terminal and try again."); return;
     }
     const returnedIssuer = incoming.searchParams.get("iss");
-    if (returnedIssuer !== null && (incoming.searchParams.getAll("iss").length !== 1 || returnedIssuer !== config.issuer)) {
+    if (returnedIssuer !== null && config.issuer && (incoming.searchParams.getAll("iss").length !== 1 || returnedIssuer !== config.issuer)) {
       response.writeHead(400).end("The login issuer did not match."); return;
     }
     accepted = true;
     if (incoming.searchParams.has("error")) {
-      response.writeHead(400).end("Login was not approved. Return to the terminal.", () => rejectCode(new Error("OAuth authorization was denied or cancelled. Run login again to retry.")));
+      const provider = providerErrorOf({ error: incoming.searchParams.get("error"), error_description: incoming.searchParams.get("error_description") ?? undefined });
+      const denied = incoming.searchParams.get("error") === "access_denied";
+      response.writeHead(400).end("Login was not approved. Return to the terminal.", () => rejectCode(new OAuthLoginError(
+        (provider ? "The provider returned " + provider + ". " : "") + (denied ? "OAuth authorization was denied or cancelled. Run login again to retry." : "Check the client ID, the registered redirect URI and the requested scopes, then run login again."))));
       return;
     }
     const code = incoming.searchParams.get("code");
     if (!code || incoming.searchParams.getAll("code").length !== 1) {
-      response.writeHead(400).end("The provider returned no authorization code.", () => rejectCode(new Error("OAuth callback did not contain one authorization code.")));
+      response.writeHead(400).end("The provider returned no authorization code.", () => rejectCode(new OAuthLoginError("OAuth callback did not contain one authorization code.")));
       return;
     }
     response.end("Authorization received. Return to the terminal to finish signing in.", () => resolveCode(code));
   });
   server.headersTimeout = 10_000;
   server.requestTimeout = 10_000;
-  const aborted = () => rejectCode(new Error("Browser login timed out or was cancelled. Run login again to retry."));
+  const aborted = () => rejectCode(new OAuthLoginError("Browser login timed out or was cancelled. Run login again to retry."));
   signal.addEventListener("abort", aborted, { once: true });
   try {
     await new Promise<void>((resolve, reject) => {
@@ -145,13 +160,13 @@ export async function oauthBrowserLogin(config: OAuthLoginConfig, interaction: O
       server.listen(Number(redirect.port) || 0, redirect.hostname === "[::1]" ? "::1" : "127.0.0.1", () => { server.off("error", reject); resolve(); });
     });
     const address = server.address();
-    if (!address || typeof address === "string") throw new Error("Could not start the OAuth callback listener.");
+    if (!address || typeof address === "string") throw new OAuthLoginError("Could not start the OAuth callback listener.");
     redirect.port = String(address.port);
     signal.throwIfAborted();
     const authorization = new URL(endpoints.authorizationUrl);
     if (config.organization) {
       const other = config.organization.parameter === "organization" ? "organization_id" : "organization";
-      if (authorization.searchParams.has(other)) throw new Error("The authorization URL contains a conflicting organization parameter. Update the provider configuration.");
+      if (authorization.searchParams.has(other)) throw new OAuthLoginError("The authorization URL contains a conflicting organization parameter. Update the provider configuration.");
       authorization.searchParams.set(config.organization.parameter, config.organization.id);
     }
     for (const [key, value] of Object.entries({ response_type: "code", client_id: config.clientId, redirect_uri: redirect.href, state, code_challenge: challenge, code_challenge_method: "S256", ...(config.scopes?.length ? { scope: config.scopes.join(" ") } : {}), ...(config.audience ? { audience: config.audience } : {}), ...(config.resource ? { resource: config.resource } : {}) })) authorization.searchParams.set(key, value);
@@ -165,14 +180,14 @@ export async function oauthBrowserLogin(config: OAuthLoginConfig, interaction: O
     });
     const data = response.data;
     if (response.status !== 200 || !data || typeof data.access_token !== "string" || !data.access_token || typeof data.token_type !== "string" || data.token_type.toLowerCase() !== "bearer") {
-      throw new Error(`OAuth token exchange failed (HTTP ${response.status}). Check the public client registration and run login again.`);
+      throw new OAuthLoginError(`OAuth token exchange failed (HTTP ${response.status}${response.providerError ? ": " + response.providerError : ""}). Check the public client registration and run login again.`);
     }
-    if (data.expires_in !== undefined && (typeof data.expires_in !== "number" || !Number.isFinite(data.expires_in) || data.expires_in <= 0)) throw new Error("OAuth provider returned an invalid token lifetime.");
+    if (data.expires_in !== undefined && (typeof data.expires_in !== "number" || !Number.isFinite(data.expires_in) || data.expires_in <= 0)) throw new OAuthLoginError("OAuth provider returned an invalid token lifetime.");
     return {
       accessToken: data.access_token,
       ...(typeof data.refresh_token === "string" && data.refresh_token ? { refreshToken: data.refresh_token } : {}),
       ...(typeof data.expires_in === "number" ? { expiresAt: Date.now() + data.expires_in * 1000 } : {}),
-      issuer: config.issuer, clientId: config.clientId, tokenUrl: endpoints.tokenUrl, redirectUri: redirect.href,
+      ...(config.issuer ? { issuer: config.issuer } : {}), clientId: config.clientId, tokenUrl: endpoints.tokenUrl, redirectUri: redirect.href,
       ...(endpoints.revocationUrl ? { revocationUrl: endpoints.revocationUrl } : {}),
       ...(typeof data.scope === "string" ? { scopes: data.scope.split(/\s+/).filter(Boolean) } : {}),
     };

package/src/oauth-request.ts

@@ -16,9 +16,23 @@ export class OAuthResponseError extends Error {
 }
 
 export type DeviceOAuthError = "authorization_pending" | "slow_down" | "access_denied" | "expired_token";
-interface AuthenticationResponse { status: number; data?: Record<string, unknown>; error?: DeviceOAuthError }
+interface AuthenticationResponse {
+  status: number; data?: Record<string, unknown>; error?: DeviceOAuthError;
+  /** RFC 6749 `error` and `error_description` from a 400 or 401 body, as
+   * "code: description". Only those two fields, printable ASCII, bounded. */
+  providerError?: string;
+}
+
+/** The provider's standard error fields, never any other body content. */
+export function providerErrorOf(data: Record<string, unknown>): string | undefined {
+  const code = typeof data.error === "string" && /^[\x20-\x21\x23-\x5b\x5d-\x7e]{1,64}$/.test(data.error) ? data.error : undefined;
+  if (!code) return undefined;
+  const description = typeof data.error_description === "string" ? data.error_description.replace(/[^\x20-\x7e]/g, " ").trim().slice(0, 300) : "";
+  return description ? code + ": " + description : code;
+}
 
-/** Error bodies and transport causes may contain credentials and are discarded. */
+/** Transport causes and error bodies beyond the standard OAuth `error` and
+ * `error_description` fields may contain credentials and are discarded. */
 export function oauthJsonRequest(url: string | URL, init: RequestInit = {}, timeoutMs = 30_000): Promise<AuthenticationResponse> {
   return boundedRequest(url, init, timeoutMs, "json");
 }
@@ -39,6 +53,9 @@ async function boundedRequest(url: string | URL, init: RequestInit, timeoutMs: n
   let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
   let timer: ReturnType<typeof setTimeout> | undefined;
   let interrupted: "timed_out" | "cancelled" | undefined;
+  // An error status is already an answer: its body only adds the provider's
+  // explanation, so a stalled or malformed error body never becomes a failure.
+  let errorStatus: number | undefined;
   let rejectDeadline!: (reason: Error) => void;
   const deadline = new Promise<never>((_, reject) => { rejectDeadline = reject; });
   const stop = (code: "timed_out" | "cancelled") => { interrupted ??= code; rejectDeadline(new OAuthResponseError(interrupted)); controller.abort(); };
@@ -56,7 +73,8 @@ async function boundedRequest(url: string | URL, init: RequestInit, timeoutMs: n
       }), deadline,
     ]);
     if (response.redirected) { void response.body?.cancel().catch(() => {}); throw new OAuthResponseError("request_failed"); }
-    if (mode === "status" || response.status !== 200 && !(mode === "device" && response.status === 400)) { void response.body?.cancel().catch(() => {}); return { status: response.status }; }
+    if (mode === "status" || response.status !== 200 && response.status !== 400 && response.status !== 401) { void response.body?.cancel().catch(() => {}); return { status: response.status }; }
+    if (response.status !== 200) errorStatus = response.status;
     if (!response.body) throw new OAuthResponseError("invalid_response");
     reader = response.body.getReader();
     let size = 0, text = "";
@@ -72,14 +90,22 @@ async function boundedRequest(url: string | URL, init: RequestInit, timeoutMs: n
     try { text += decoder.decode(); }
     catch { throw new OAuthResponseError("invalid_response"); }
     let data: unknown;
-    try { data = JSON.parse(text); } catch { throw new OAuthResponseError("invalid_response"); }
-    if (!data || typeof data !== "object" || Array.isArray(data)) throw new OAuthResponseError("invalid_response");
+    try { data = JSON.parse(text); } catch {
+      if (response.status !== 200) return { status: response.status };
+      throw new OAuthResponseError("invalid_response");
+    }
+    if (!data || typeof data !== "object" || Array.isArray(data)) {
+      if (response.status !== 200) return { status: response.status };
+      throw new OAuthResponseError("invalid_response");
+    }
     if (response.status !== 200) {
       const error = (data as Record<string, unknown>).error;
-      return { status: response.status, ...(["authorization_pending", "slow_down", "access_denied", "expired_token"].includes(String(error)) && typeof error === "string" ? { error: error as DeviceOAuthError } : {}) };
+      const providerError = providerErrorOf(data as Record<string, unknown>);
+      return { status: response.status, ...(providerError ? { providerError } : {}), ...(mode === "device" && ["authorization_pending", "slow_down", "access_denied", "expired_token"].includes(String(error)) && typeof error === "string" ? { error: error as DeviceOAuthError } : {}) };
     }
     return { status: response.status, data: data as Record<string, unknown> };
   } catch (error) {
+    if (errorStatus !== undefined && interrupted !== "cancelled") return { status: errorStatus };
     if (interrupted) throw new OAuthResponseError(interrupted);
     if (error instanceof OAuthResponseError) throw error;
     throw new OAuthResponseError("request_failed");

package/src/oauth-session.ts

@@ -26,9 +26,9 @@ export interface CredentialDestination { apiBaseUrl: string; environment?: strin
 
 export function assertCredentialDestination(credentials: StoredCredentials, destination: CredentialDestination): void {
   const saved = credentials.destination;
-  if (!saved) throw new Error("Saved credentials have no API and profile binding. Log in again before using them.");
-  if (new URL(saved.apiBaseUrl).href !== new URL(destination.apiBaseUrl).href) throw new Error("The API destination changed. Log in again before using saved credentials.");
-  if ((saved.environment ?? null) !== (destination.environment ?? null) || (saved.profile ?? null) !== (destination.profile ?? null)) throw new Error("The credential environment or profile changed. Log in again before using saved credentials.");
+  if (!saved) throw new OAuthSessionError("Saved credentials have no API and profile binding. Log in again before using them.");
+  if (new URL(saved.apiBaseUrl).href !== new URL(destination.apiBaseUrl).href) throw new OAuthSessionError("The API destination changed. Log in again before using saved credentials.");
+  if ((saved.environment ?? null) !== (destination.environment ?? null) || (saved.profile ?? null) !== (destination.profile ?? null)) throw new OAuthSessionError("The credential environment or profile changed. Log in again before using saved credentials.");
 }
 
 export interface StoredCredentials {
@@ -67,7 +67,7 @@ export function credentialIdentityBinding(credentials: StoredCredentials, identi
 export function assertStoredIdentity(credentials: StoredCredentials, identity?: IdentityConfiguration): void {
   if (!identity) return;
   if (!credentials.identity?.values || credentials.identity.binding !== credentialIdentityBinding(credentials, identity) || Object.keys(identity.fields).some((kind) => !Object.hasOwn(credentials.identity!.values, kind))) {
-    throw new Error("The saved login has no matching API identity verification. Sign in again to verify the current account and organization.");
+    throw new OAuthSessionError("The saved login has no matching API identity verification. Sign in again to verify the current account and organization.");
   }
 }
 
@@ -99,7 +99,14 @@ function alive(pid: number): boolean {
   try { process.kill(pid, 0); return true; } catch (error) { return code(error) !== "ESRCH"; }
 }
 
-export class CredentialStorageError extends Error {}
+/** The OS credential store or the saved credential file cannot be used. */
+export class CredentialStorageError extends Error {
+  constructor(message?: string) { super(message); this.name = "CredentialStorageError"; }
+}
+/** A saved login cannot be used as is; the remedy is to sign in again. */
+export class OAuthSessionError extends Error {
+  constructor(message?: string) { super(message); this.name = "OAuthSessionError"; }
+}
 
 export interface CredentialCodec {
   readonly name: string;
@@ -127,7 +134,7 @@ export class FileCredentialStore implements CredentialStore {
     } catch (error) {
       if (code(error) === "ENOENT") return null;
       if (error instanceof CredentialStorageError) throw error;
-      throw new Error("Cannot read saved credentials. Check the credential store before logging in again.");
+      throw new CredentialStorageError("Cannot read saved credentials. Check the credential store before logging in again.");
     }
   }
 
@@ -154,9 +161,9 @@ export class FileCredentialStore implements CredentialStore {
       while (!acquired) {
         try { linkSync(claim, lock); acquired = true; }
         catch (error) {
-          if (code(error) !== "EEXIST") throw new Error("Cannot lock the credential store.");
+          if (code(error) !== "EEXIST") throw new CredentialStorageError("Cannot lock the credential store.");
           this.recoverDeadOwner(lock);
-          if (Date.now() >= deadline) throw new Error("The credential store is busy. Wait for the other login or refresh to finish and retry. If its process stopped, inspect " + lock + ".");
+          if (Date.now() >= deadline) throw new CredentialStorageError("The credential store is busy. Wait for the other login or refresh to finish and retry. If its process stopped, inspect " + lock + ".");
           await new Promise((resolve) => setTimeout(resolve, 25));
         }
       }
@@ -199,13 +206,13 @@ export class FileCredentialStore implements CredentialStore {
 
 function validSession(credentials: StoredCredentials | null, config: SessionConfiguration, sessionId: string, allowPending = false): StoredOAuthSession {
   const session = credentials?.oauth;
-  if (!session || !session.sessionId || session.sessionId !== sessionId) throw new Error("The saved OAuth session changed or was logged out. Run login again and retry the request.");
-  if (session.apiBaseUrl && new URL(session.apiBaseUrl).href !== new URL(config.apiBaseUrl).href) throw new Error("The API destination changed. Log in again.");
-  if (session.issuer && config.issuer && session.issuer !== config.issuer) throw new Error("The configured issuer changed. Log in again.");
-  if (session.configuredClientId !== (config.clientId ?? null)) throw new Error("The OAuth client changed. Log in again.");
-  if (!session.binding || session.binding !== sessionBinding(config)) throw new Error("The API or OAuth configuration changed. Log in again before using saved credentials.");
-  if (session.refreshPending && !allowPending) throw new Error("The previous OAuth refresh did not finish safely. Log in again; its refresh token will not be reused.");
-  if (typeof session.accessToken !== "string" || !session.accessToken) throw new Error("The saved OAuth session is invalid. Log in again.");
+  if (!session || !session.sessionId || session.sessionId !== sessionId) throw new OAuthSessionError("The saved OAuth session changed or was logged out. Run login again and retry the request.");
+  if (session.apiBaseUrl && new URL(session.apiBaseUrl).href !== new URL(config.apiBaseUrl).href) throw new OAuthSessionError("The API destination changed. Log in again.");
+  if (session.issuer && config.issuer && session.issuer !== config.issuer) throw new OAuthSessionError("The configured issuer changed. Log in again.");
+  if (session.configuredClientId !== (config.clientId ?? null)) throw new OAuthSessionError("The OAuth client changed. Log in again.");
+  if (!session.binding || session.binding !== sessionBinding(config)) throw new OAuthSessionError("The API or OAuth configuration changed. Log in again before using saved credentials.");
+  if (session.refreshPending && !allowPending) throw new OAuthSessionError("The previous OAuth refresh did not finish safely. Log in again; its refresh token will not be reused.");
+  if (typeof session.accessToken !== "string" || !session.accessToken) throw new OAuthSessionError("The saved OAuth session is invalid. Log in again.");
   assertStoredIdentity(credentials!, config.identity);
   return session;
 }
@@ -213,15 +220,17 @@ function validSession(credentials: StoredCredentials | null, config: SessionConf
 /** Re-read on every request attempt; only one process may rotate the token.
  * A failed or interrupted exchange requires login, since the server may have
  * consumed its refresh token even when no response reached this process. */
-export async function oauthSessionToken(store: CredentialStore, config: SessionConfiguration, sessionId: string, tokenParams: Record<string, string> = {}): Promise<string> {
-  const fresh = (session: StoredOAuthSession) => session.expiresAt === undefined || (Number.isFinite(session.expiresAt) && session.expiresAt > Date.now() + 60_000);
+export async function oauthSessionToken(store: CredentialStore, config: SessionConfiguration, sessionId: string, tokenParams: Record<string, string> = {}, rejected?: string): Promise<string> {
+  // A token the API just rejected (401) is refreshed once even if unexpired;
+  // another process may already have replaced it, which is fine.
+  const fresh = (session: StoredOAuthSession) => session.accessToken !== rejected && (session.expiresAt === undefined || (Number.isFinite(session.expiresAt) && session.expiresAt > Date.now() + 60_000));
   const first = validSession(store.read(), config, sessionId, true);
   if (!first.refreshPending && fresh(first)) return first.accessToken;
   return store.withLock(async (locked) => {
     const credentials = locked.read();
     const session = validSession(credentials, config, sessionId);
     if (fresh(session)) return session.accessToken;
-    if (!session.refreshToken || !session.tokenUrl || !session.clientId) throw new Error("The OAuth session expired and cannot be refreshed. Log in again.");
+    if (!session.refreshToken || !session.tokenUrl || !session.clientId) throw new OAuthSessionError(session.accessToken === rejected ? "The API rejected the saved OAuth session and it has no refresh token. Log in again." : "The OAuth session expired and cannot be refreshed. Log in again.");
     const endpoint = new URL(session.tokenUrl);
     if ((endpoint.protocol !== "https:" && !(endpoint.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(endpoint.hostname))) || endpoint.username || endpoint.password || endpoint.hash) throw new Error("The OAuth token endpoint requires HTTPS; loopback HTTP is allowed for development.");
     locked.write({ ...credentials, oauth: { ...session, refreshPending: true } });
@@ -252,7 +261,16 @@ export async function oauthSessionToken(store: CredentialStore, config: SessionC
       return next.accessToken;
     } catch {
       // Never expose an error body, a refresh token, or fetch's nested cause.
-      throw new Error("The OAuth session could not be refreshed safely. Log in again.");
+      throw new OAuthSessionError("The OAuth session could not be refreshed safely. Log in again.");
     }
   });
 }
+
+/** A saved-session token for the request runtime: resolved before every
+ * attempt, and after a 401 (invalidate) the next resolve forces one refresh
+ * of the token the API rejected. */
+export function sessionCredential(resolve: (rejected?: string) => Promise<string>): (() => Promise<string>) & { invalidate(): void } {
+  let last: string | undefined, rejected: string | undefined;
+  const token = async () => { const previous = rejected; rejected = undefined; last = await resolve(previous); return last; };
+  return Object.assign(token, { invalidate() { rejected = last; } });
+}