@typeship-ax/mcp 0.21.0 → 0.22.0

package/src/mcp.ts

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
-// typeship — MCP server. Generated by typeship — https://typeship.dev
+// Typeship — MCP server. Generated by Typeship — https://typeship.dev
 // Speaks MCP 2026-07-28 and accepts the 2025-11-25 initialize handshake.
 // HTTP is stateless (no sessions); the protocol layer and tool surface
-// live in ./mcp-protocol.js, shared with typeship's hosted endpoint. Two
-// transports, zero dependencies:
+// live in ./mcp-protocol.js, shared by both transports. Two transports,
+// zero dependencies:
 //   node mcp.js            stdio (newline-delimited JSON-RPC 2.0)
 //   createMcpHandler()    configured Streamable HTTP handler
 // Surface switches (flags or environment):
@@ -22,19 +22,19 @@ import { homedir, tmpdir } from "node:os";
 import { basename, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { TypeshipClient, formatDebugEvent, type ClientOptions, type DebugEvent } from "./index.js";
-import { asApiResult } from "./core/http.js";
+import { asApiResult, mediaTypeForPath } from "./core/http.js";
 import { GLOBALS, OMITTED_OPS, OPS, buildArgs, type OpSpec } from "./ops.js";
 import {
   DEFAULT_MAX_RESULT_CHARS, SUPPORTED_PROTOCOL_VERSIONS, McpAccountLinkRequired, argumentsError, asJsonRpc, binaryOutcome, callSharedTool, checkRequestHeaders,
-  createStdioRpcHandler, dataOutcome, errorOutcome, handleRpc, isRpcOutcome, pageOutcome, parseIncludeList, prepareCall, resolveReferences, serverInstructions,
-  takeCancelled, textError, toolDefinitions, visibleOps,
+  createStdioRpcHandler, dataOutcome, errorOutcome, handleRpc, hiddenOperations, isRpcOutcome, pageOutcome, parseIncludeList, prepareCall, resolveReferences, serverInstructions,
+  requiredScopes, takeCancelled, textError, toolDefinitions, unmatchedIncludes, unsupportedAuthOutcome, visibleOps,
   type ArgumentIssue, type DocsSource, type McpServer, type OpLike, type RpcOutcome, type ToolOutcome,
 } from "./mcp-protocol.js";
 import { fetchDocsText } from "./docs.js";
-import { assertCredentialDestination, assertStoredIdentity, oauthSessionToken } from "./oauth-session.js";
+import { assertCredentialDestination, assertStoredIdentity, oauthSessionToken, sessionCredential } from "./oauth-session.js";
 import { createCredentialStore } from "./credential-storage.js";
 import { identityPolicyOf, verifyClientIdentity, type IdentityConfiguration } from "./api-identity.js";
-import { parseNamedCredentials, resolveNamedCredentials, namedCredentialAvailability, type NamedCredentials, type CredentialSchemes } from "./named-credentials.js";
+import { parseNamedCredentials, resolveNamedCredentials, namedCredentialAvailability, missingCredentials, oauthSessionSchemes, parseExtraHeaders, applyExtraHeaders, type NamedCredentials, type CredentialSchemes } from "./named-credentials.js";
 import { resolveProfile, profileFlag, readProfileConfig } from "./auth-profiles.js";
 import { createMcpAuthorizer, McpAuthorizationError, type McpAuthorizationConfiguration, type McpTokenIntrospectionConfiguration, type McpPrincipal } from "./mcp-authorization.js";
 export type { McpAuthorizationConfiguration, McpTokenIntrospectionConfiguration, McpPrincipal } from "./mcp-authorization.js";
@@ -43,7 +43,7 @@ export { McpAccountLinkRequired } from "./mcp-protocol.js";
 const BIN = "typeship";
 const PKG_NAME = "@typeship-ax/mcp";
 const SERVER_NAME = "typeship-mcp";
-const SERVER_VERSION = "0.21.0";
+const SERVER_VERSION = "0.22.0";
 /** The MCP client's announced name (clientInfo in request _meta), for the User-Agent. */
 let MCP_CLIENT_NAME: string | null = null;
 function noteClientInfo(message: unknown): void {
@@ -57,8 +57,8 @@ const AUTH_SCALARS: { option: string; flag: string; env: string }[] = [{"option"
 const BASIC: { envUser: string; envPass: string } | null = null;
 
 const ENVIRONMENTS: Record<string, string> = {};
-const DOCS_URL_DEFAULT: string | null = "https://typeship.dev";
-const DOCS_INDEX_URL_DEFAULT: string | null = null;
+const DOCS_URL_DEFAULT: string | null = "https://typeship.dev/docs";
+const DOCS_INDEX_URL_DEFAULT: string | null = "https://typeship.dev/llms.txt";
 /** "meta" collapses per-operation tools into search/read/execute so huge
  * APIs don't flood agent context with hundreds of tools. */
 const TOOL_MODE: "operations" | "meta" = "meta";
@@ -71,6 +71,10 @@ const IDENTITY_TOOL: string | null = null;
 const ARGV = process.argv.slice(2);
 const READ_ONLY = ARGV.includes("--read-only") || process.env["TYPESHIP_MCP_READ_ONLY"] === "1" || process.env["TYPESHIP_MCP_READ_ONLY"] === "true";
 const INCLUDE = parseIncludeList(ARGV.includes("--tools") ? ARGV[ARGV.indexOf("--tools") + 1] : process.env["TYPESHIP_MCP_TOOLS"]);
+/** How the operator set each switch, for errors that name it. */
+const READ_ONLY_SWITCH = ARGV.includes("--read-only") ? "--read-only" : "TYPESHIP_MCP_READ_ONLY";
+const TOOLS_SWITCH = ARGV.includes("--tools") ? "--tools" : "TYPESHIP_MCP_TOOLS";
+const HEADER_ARGS = ARGV.flatMap((arg, index) => arg === "--header" && ARGV[index + 1] !== undefined ? [ARGV[index + 1]!] : arg.startsWith("--header=") ? [arg.slice("--header=".length)] : []);
 const MAX_RESULT_CHARS = Number(process.env["TYPESHIP_MCP_MAX_RESULT_CHARS"]) || DEFAULT_MAX_RESULT_CHARS;
 /** One sentence on where credentials come from on each transport; goes
  * into the instructions and into 401 results. */
@@ -97,7 +101,7 @@ function readJson<T>(file: string): T | null {
 
 function makeClient(op: OpSpec): TypeshipClient {
   const profile = LOCAL_CREDENTIALS ? resolveProfile(configRoot(), { flag: profileFlag(ARGV), environment: process.env["TYPESHIP_PROFILE"] }) : null;
-  const store = createCredentialStore(profile?.directory ?? configRoot(), process.env["TYPESHIP_CREDENTIAL_STORE"], "TYPESHIP_CREDENTIAL_STORE");
+  const store = createCredentialStore(profile?.directory ?? configRoot(), BIN, process.env["TYPESHIP_CREDENTIAL_STORE"], "TYPESHIP_CREDENTIAL_STORE");
   if (BASIC && (process.env[BASIC.envUser] !== undefined) !== (process.env[BASIC.envPass] !== undefined)) throw new Error("Supply both Basic-auth environment variables together, or use a complete named Basic credential.");
   const envNamed = LOCAL_CREDENTIALS && process.env["TYPESHIP_CREDENTIALS"] !== undefined ? parseNamedCredentials(process.env["TYPESHIP_CREDENTIALS"], NAMED_SCHEMES) : {};
   const explicitOptions = new Set(AUTH_SCALARS.filter((a) => process.env[a.env] !== undefined).map((a) => a.option));
@@ -139,27 +143,71 @@ function makeClient(op: OpSpec): TypeshipClient {
   ]);
 
 
+  requireOperationCredentials(op, options);
   for (const g of GLOBALS) {
     const value = process.env["TYPESHIP_" + g.envSuffix];
     if (value !== undefined) options[g.option] = value;
   }
   if (process.env["TYPESHIP_DEBUG"] === "1") {
-    options.debug = (event: DebugEvent) => process.stderr.write(formatDebugEvent(BIN + "-mcp", event) + "\n");
+    options.debug = (event: DebugEvent) => process.stderr.write(formatDebugEvent(SERVER_NAME, event) + "\n");
   }
   // The local MCP server identifies itself (surface + the client it serves, when announced).
-  options.defaultHeaders = { "User-Agent": PKG_NAME + "-mcp/" + SERVER_VERSION + (MCP_CLIENT_NAME ? " (client=" + MCP_CLIENT_NAME + ")" : "") };
+  options.defaultHeaders = { "User-Agent": SERVER_NAME + "/" + SERVER_VERSION + (MCP_CLIENT_NAME ? " (client=" + MCP_CLIENT_NAME + ")" : "") };
+  // --header / TYPESHIP_HEADERS: headers the spec does not declare, applied last.
+  const extraHeaders = LOCAL_CREDENTIALS ? parseExtraHeaders(process.env["TYPESHIP_HEADERS"], HEADER_ARGS, "TYPESHIP_HEADERS") : {};
+  if (Object.keys(extraHeaders).length) options.onRequest = (context) => { applyExtraHeaders(context.headers, extraHeaders); };
   // Keep the SDK's machine-token cache while re-evaluating local configuration.
   const key = createHash("sha256").update(JSON.stringify([options, config, profile?.name, stored?.oauth?.sessionId, null, process.env["TYPESHIP_DEBUG"]])).digest("hex");
   if (clientInstance && clientKey === key) return clientInstance;
   const client = new TypeshipClient(options);
+  CLIENT_BASIC.set(client, { basicAuth: options.basicAuth, credentials: options.credentials });
   clientKey = key;
   CLIENT_CREDENTIALS.set(client, Object.keys(options.credentials ?? {}).length > 0 || AUTH_SCALARS.some((a) => options[a.option] !== undefined) || options.basicAuth !== undefined || options.bearerToken !== undefined || options.clientCredentials !== undefined);
   return (clientInstance = client);
 }
 
+/** A required operation without one complete credential alternative stops
+ * before any request, as the CLI does, with the variables that supply it.
+ * Operations with no supported alternative are reported separately. */
+class MissingCredentialsError extends Error {
+  constructor(readonly outcome: ToolOutcome) { super("Missing credentials"); }
+}
+function requireOperationCredentials(op: OpSpec, options: ClientOptions & Record<string, unknown>): void {
+  if (op.auth !== "required") return;
+  const gap = missingCredentials(NAMED_SCHEMES, op.credentialOptions, options);
+  if (!gap || !gap.alternatives.length) return;
+  const names = new Set(gap.missing.flat());
+  const needs = (option: string) => [...names].some((name) => NAMED_SCHEMES[name]?.options.includes(option));
+  const scalars = AUTH_SCALARS.filter((scalar) => needs(scalar.option));
+  throw new MissingCredentialsError(textError(
+    op.tool + " needs one complete credential alternative. Missing security schemes: " + gap.missing.map((alternative) => alternative.join(" + ")).join(" OR ") + ". No request was sent.",
+    "NO_AUTH",
+    [
+      ...scalars.map((scalar) => "Set " + scalar.env + " in the MCP server's environment."),
+      ...(BASIC && needs("basicAuth") ? ["Set " + BASIC.envUser + " and " + BASIC.envPass + " in the MCP server's environment."] : []),
+      "Or set TYPESHIP_CREDENTIALS to a JSON object with every scheme in one alternative: " + gap.alternatives.map((alternative) => alternative.join(" + ")).join(" OR ") + ".",
+      "Credentials saved by '" + BIN + " login' are read on the next call without a restart.",
+    ],
+  ));
+}
+
 let clientInstance: TypeshipClient | undefined;
 let clientKey = "";
 const CLIENT_CREDENTIALS = new WeakMap<TypeshipClient, boolean>();
+/** Each client's Basic credentials, for path arguments that default to the username. */
+const CLIENT_BASIC = new WeakMap<TypeshipClient, { basicAuth?: unknown; credentials?: unknown }>();
+
+/** The Basic-auth username a path argument of op defaults to (Twilio's
+ * AccountSid): the named scheme's, else basicAuth's. */
+function credentialUsername(op: OpSpec, client: TypeshipClient): string | undefined {
+  const scheme = op.params.find((p) => p.credential)?.credential?.scheme;
+  const basic = scheme ? CLIENT_BASIC.get(client) : undefined;
+  if (!basic) return undefined;
+  const named = (basic.credentials as Record<string, unknown> | undefined)?.[scheme!];
+  const username = named && typeof named === "object" ? (named as { username?: unknown }).username
+    : (basic.basicAuth as { username?: unknown } | undefined)?.username;
+  return typeof username === "string" && username !== "" ? username : undefined;
+}
 
 /** Resolve configuration and credentials for each tool call, including login/logout changes. */
 function getClient(op: OpSpec): TypeshipClient {
@@ -172,9 +220,9 @@ async function callOperationRaw(op: OpSpec, rawArgs: Record<string, unknown>, re
   // Arguments are checked against the tool's schema first: unknown names,
   // wrong types and missing requirements come back as one isError result,
   // nothing reaches the API half-formed and nothing is dropped silently.
-  const prepared = prepareCall(op as unknown as OpLike, rawArgs, { maxChars: MAX_RESULT_CHARS });
+  const prepared = prepareCall(op as unknown as OpLike, rawArgs, { maxChars: MAX_RESULT_CHARS, credentialUsername: credentialUsername(op, client) });
   if (!prepared.ok) return prepared.outcome;
-  const { args, fields, maxChars } = prepared.call;
+  const { args, fields, optionalFields, maxChars } = prepared.call;
   const values: Record<string, unknown> = {};
   for (const p of op.params) {
     const argument = p.kind === "header" && p.name === "If-Match" ? "if_match" : p.name;
@@ -186,14 +234,24 @@ async function callOperationRaw(op: OpSpec, rawArgs: Record<string, unknown>, re
   let rawBody: unknown = op.bodyStyle === "data" ? args.body : undefined;
   if (LOCAL_PROCESS && !remote) {
     for (const p of op.params) {
-      if (p.type !== "file" || typeof values[p.name] !== "string") continue;
-      try { values[p.name] = fileArgument(values[p.name] as string); } catch (e) { fileIssues.push({ code: "INVALID_ARGUMENT", argument: p.name, message: p.name + ": cannot read " + String(values[p.name]) + " (" + (e as Error).message + ")" }); }
+      if (p.type !== "file") continue;
+      const paths = values[p.name];
+      if (typeof paths !== "string" && !(Array.isArray(paths) && paths.every((path) => typeof path === "string"))) continue;
+      const files: File[] = [];
+      for (const path of Array.isArray(paths) ? paths as string[] : [paths]) {
+        try { files.push(fileArgument(path)); } catch (e) { fileIssues.push({ code: "INVALID_ARGUMENT", argument: p.name, message: p.name + ": cannot read " + path + " (" + (e as Error).message + ")" }); }
+      }
+      values[p.name] = Array.isArray(paths) ? files : files[0];
     }
     if (op.bodyKind === "binary" && typeof rawBody === "string") {
       try { rawBody = fileArgument(rawBody); } catch (e) { fileIssues.push({ code: "INVALID_ARGUMENT", argument: "body", message: "body: cannot read " + String(rawBody) + " (" + (e as Error).message + ")" }); }
     }
   }
   if (fileIssues.length > 0) return argumentsError(op, fileIssues);
+  // A tool result is one value: a streamed response is not available here.
+  if (op.streamMethod && args[op.streamMethod.flag] === op.streamMethod.value) {
+    return argumentsError(op, [{ code: "INVALID_ARGUMENT", argument: op.streamMethod.flag, message: op.streamMethod.flag + ": streaming is not available over MCP, which returns one result per call. Call again without " + op.streamMethod.flag + " " + JSON.stringify(op.streamMethod.value) + " to get the complete response." }]);
+  }
   const callArgs = buildArgs(
     op,
     values,
@@ -204,8 +262,9 @@ async function callOperationRaw(op: OpSpec, rawArgs: Record<string, unknown>, re
     authHint: remote ? AUTH_HINT_HTTP : AUTH_HINT_STDIO,
     docsUrl: docsSource.docsUrl(),
     hadCredential: !!remote || CLIENT_CREDENTIALS.get(client) === true,
+    requiredScopes: requiredScopes(op.security),
   };
-  const shape = { fields, maxChars, pagination: op.pagination, args };
+  const shape = { fields, optionalFields, maxChars, pagination: op.pagination, args, safety: op.safety };
   try {
     const target = (client as unknown as Record<string, Record<string, (...a: unknown[]) => unknown>>)[op.resource]!;
     let result = await asApiResult(target[op.method]!(...callArgs) as Promise<unknown>);
@@ -223,7 +282,7 @@ async function callOperationRaw(op: OpSpec, rawArgs: Record<string, unknown>, re
     }
     if (op.paginated) {
       const page = result.data as { items: unknown[]; nextPageParams(): Record<string, unknown> | null; response: { requestId?: string } };
-      return pageOutcome(page.items, page.nextPageParams(), { ...shape, requestId: page.response.requestId });
+      return pageOutcome(page.items, page.nextPageParams(), { ...shape, requestId: page.response.requestId, carryArgs: op.params.filter((p) => p.required || p.credential).map((p) => p.name) });
     }
     // A binary body (the SDK hands back a Blob): an image block, or a file
     // on disk, never "{}".
@@ -249,13 +308,23 @@ function referenceCacheFor(authHeader?: string): Map<string, string | number> {
 }
 
 async function callOperation(op: OpSpec, rawArgs: Record<string, unknown>, remote?: RemoteContext): Promise<ToolOutcome> {
-  const prepared = prepareCall(op as unknown as OpLike, rawArgs, { maxChars: MAX_RESULT_CHARS });
+  // A path argument that defaults to the Basic-auth username needs the
+  // configured credential before validation; a credential failure is
+  // reported below, after the arguments.
+  let username: string | undefined;
+  if (op.params.some((p) => p.credential && rawArgs[p.name] === undefined)) {
+    try { username = credentialUsername(op, remote ? await remote.client() : getClient(op)); } catch { username = undefined; }
+  }
+  const prepared = prepareCall(op as unknown as OpLike, rawArgs, { maxChars: MAX_RESULT_CHARS, credentialUsername: username });
   if (!prepared.ok) return prepared.outcome;
+  const unsupported = unsupportedAuthOutcome(op as unknown as OpLike);
+  if (unsupported) return unsupported;
   // One client/session for the entire tool, including name-to-ID lookups.
   // If login changes during a lookup, the token callback rejects the old session.
   let client: TypeshipClient;
   try { client = remote ? await remote.client() : getClient(op); } catch (error) {
     if (remote && error instanceof McpAccountLinkRequired) throw error;
+    if (!remote && error instanceof MissingCredentialsError) return error.outcome;
     return textError(remote ? "API access is unavailable for this MCP account. Reconnect your API account or contact the server owner." : (error as Error).message);
   }
   const resolved = await resolveReferences(op as unknown as OpLike, prepared.call.args, {
@@ -267,7 +336,7 @@ async function callOperation(op: OpSpec, rawArgs: Record<string, unknown>, remot
   if (!resolved.ok) return resolved.outcome;
   const args = {
     ...resolved.args,
-    ...(prepared.call.fields ? { fields: prepared.call.fields.map((path) => path.join(".")) } : {}),
+    ...(prepared.call.fields ? { fields: prepared.call.fields.map((path) => (prepared.call.optionalFields.includes(path.join(".")) ? "?" : "") + path.join(".")) } : {}),
   };
   return callOperationRaw(op, args, remote, client);
 }
@@ -293,7 +362,7 @@ const HAS_UPLOADS = MCP_OPS.some((op) => op.bodyKind === "multipart" || op.bodyK
 
 /** A local file as an upload part (multipart field or raw body). */
 function fileArgument(path: string): File {
-  return new File([readFileSync(path)], basename(path));
+  return new File([readFileSync(path)], basename(path), { type: mediaTypeForPath(path) });
 }
 
 /** Where binary responses land on a local server: a per-server temp dir. */
@@ -308,6 +377,7 @@ function saveBinary(bytes: Uint8Array, _mediaType: string, suggestedName: string
 const docsSource: DocsSource = {
   ops: MCP_OPS as unknown as OpLike[],
   omittedOps: OMITTED_OPS as unknown as OpLike[],
+  hiddenOps: hiddenOperations(OPS as unknown as OpLike[], { readOnly: READ_ONLY, include: INCLUDE, uploads: LOCAL_PROCESS }, { readOnly: READ_ONLY_SWITCH, include: TOOLS_SWITCH }),
   generatedOperationCount: OPS.length,
   docsUrl: () => readJson<{ docsUrl?: string }>("config.json")?.docsUrl ?? DOCS_URL_DEFAULT,
   docsIndexUrl: () => readJson<{ docsUrl?: string }>("config.json")?.docsUrl ? null : DOCS_INDEX_URL_DEFAULT,
@@ -322,9 +392,9 @@ function serverFor(remote?: RemoteContext): McpServer {
   const source = remote ? { ...docsSource, ops: operations } : docsSource;
   const website = docsSource.docsUrl();
   return {
-    serverInfo: { name: SERVER_NAME, title: "typeship", version: SERVER_VERSION, ...(website ? { websiteUrl: website } : {}) },
+    serverInfo: { name: SERVER_NAME, title: "Typeship", version: SERVER_VERSION, ...(website ? { websiteUrl: website } : {}) },
     instructions: serverInstructions({
-      title: "typeship",
+      title: "Typeship",
       ops: operations,
       toolCount: operations.length,
       generatedOperationCount: OPS.length,
@@ -452,12 +522,15 @@ async function authorizedHttp(request: Request, authorizer: ReturnType<typeof cr
     if (credentials.baseUrl !== undefined && credentials.baseUrl !== baseUrl) throw new Error("API credentials target a different API URL.");
     const token = request.headers.get("authorization")!.slice(7);
     const transport = credentials.fetch ?? fetch;
-    return new TypeshipClient({ ...credentials, baseUrl, fetch: async (input, init) => {
+    const created = new TypeshipClient({ ...credentials, baseUrl, fetch: async (input, init) => {
       const headers = new Headers(init?.headers);
       const destination = new URL(typeof input === "string" ? input : input instanceof URL ? input.href : input.url);
       if ([...headers.values()].some(value => value === token || value === "Bearer " + token) || [...destination.searchParams.values()].includes(token)) throw new Error("An MCP connection token cannot authorize an upstream API request.");
       return transport(input, init);
     } });
+    const { basicAuth, credentials: named } = credentials as unknown as { basicAuth?: unknown; credentials?: unknown };
+    CLIENT_BASIC.set(created, { basicAuth, credentials: named });
+    return created;
   })() };
 
   let incoming: unknown;
@@ -569,7 +642,21 @@ function invokedDirectly(): boolean {
     return /mcp\.(js|mjs|ts)$/.test(entry);
   }
 }
+/** A --tools value that names nothing would start a server with no
+ * operations, which reads to an agent like an empty API. */
+function toolsSwitchProblem(): string | null {
+  if (ARGV.includes("--tools") && INCLUDE === undefined) return "--tools needs a comma-separated list of resources, tool names, or resource.method.";
+  const unmatched = unmatchedIncludes(OPS as unknown as OpLike[], INCLUDE);
+  if (unmatched.length === 0) return null;
+  const resources = [...new Set(OPS.map((op) => op.resource))];
+  return TOOLS_SWITCH + " names nothing in this API: " + unmatched.join(", ") + ". Resources: " + resources.slice(0, 30).join(", ") + (resources.length > 30 ? ", …" : "") + ".";
+}
 if (invokedDirectly()) {
+  const problem = toolsSwitchProblem();
+  if (problem !== null) {
+    process.stderr.write(SERVER_NAME + ": " + problem + "\n");
+    process.exit(2);
+  }
   const httpFlag = process.argv.indexOf("--http");
   if (httpFlag !== -1) {
     const port = Number(process.argv[httpFlag + 1]) || Number(process.env.PORT) || 3000;

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-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; } });
+}