@typeship-ax/cli 0.8.0 → 0.9.1

package/src/docs.ts

@@ -55,6 +55,144 @@ function safeHttpUrl(value: string | null): string | null {
   }
 }
 
+export interface GuideMatch {
+  title: string;
+  section: string | null;
+  /** Kept for callers that displayed the original heading-only results. */
+  heading: string;
+  excerpt: string;
+  url: string;
+}
+
+interface GuidePage { title: string; url: string; description: string }
+
+/** Links in an index follow URL semantics, including site-root relative links. */
+function docsLink(base: string | null, indexUrl: string | null, value: string): string | null {
+  const index = resolveDocsContentUrl(base, indexUrl, "llms.txt");
+  if (!index) return null;
+  try { return resolveDocsContentUrl(base, indexUrl, new URL(value, index).toString()); }
+  catch { return null; }
+}
+
+export function docsIndexPages(index: string | null, base: string | null, indexUrl: string | null): GuidePage[] {
+  const pages = new Map<string, GuidePage>();
+  for (const line of (index ?? "").split("\n")) {
+    for (const match of line.matchAll(/\[([^\]]+)\]\(([^\s)]+)\)/g)) {
+      const url = docsLink(base, indexUrl, match[2]!);
+      if (!url || /\/llms(?:-full)?\.txt(?:[?#]|$)/.test(url)) continue;
+      const description = line.slice(match.index! + match[0].length).replace(/^\s*:\s*/, "").trim();
+      if (!pages.has(url)) pages.set(url, { title: match[1]!, url, description: cleanDocsText(description) });
+    }
+  }
+  return [...pages.values()];
+}
+
+function cleanDocsText(text: string): string {
+  return text.replace(/^\s*(?:>\s*)+/, "").replace(/!?\[([^\]]+)\]\([^)]*\)/g, "$1").replace(/<[^>]*>/g, "").replace(/[*`]/g, "").replace(/^\s*[-*>]\s*/, "").replace(/\s+/g, " ").trim();
+}
+
+function docsTerms(query: string): string[] {
+  return [...new Set(query.replace(/([a-z])([A-Z])/g, "$1 $2").toLowerCase().split(/[^a-z0-9]+/).filter((term) => term.length >= 2))];
+}
+
+/** Rank sections, then keep the strongest section of each real page. A heading
+ * match must have content: blank lines, fences, and source markers are not hits. */
+export function searchGuidePages(
+  prose: string | null, index: string | null, base: string | null, indexUrl: string | null, query: string,
+): GuideMatch[] {
+  const pages = docsIndexPages(index, base, indexUrl);
+  const terms = docsTerms(query);
+  if (terms.length === 0) return [];
+  const phrase = query.trim().toLowerCase();
+  const candidates: { match: GuideMatch; score: number }[] = [];
+  const add = (title: string, section: string | null, url: string | null, lines: string[]) => {
+    if (!url) return;
+    const content = lines.map(cleanDocsText).filter((line) => line.length > 0);
+    if (content.length === 0) return;
+    const heading = (title + " " + (section ?? "")).toLowerCase();
+    const body = content.join(" ").toLowerCase();
+    const matched = terms.filter((term) => heading.includes(term) || body.includes(term));
+    if (matched.length === 0) return;
+    const score = matched.length * 10 + (matched.length === terms.length ? 50 : 0)
+      + (heading.includes(phrase) ? 35 : body.includes(phrase) ? 25 : 0)
+      + (title.toLowerCase().includes(phrase) ? 25 : 0)
+      + terms.filter((term) => title.toLowerCase().includes(term)).length * 5
+      + terms.filter((term) => heading.includes(term)).length * 5
+      + terms.filter((term) => section?.toLowerCase().includes(term)).length * 3;
+    const excerpt = [...content].sort((a, b) => {
+      const rank = (line: string) => terms.filter((term) => line.toLowerCase().includes(term)).length;
+      return rank(b) - rank(a);
+    })[0]!.slice(0, 240);
+    candidates.push({ match: { title, section, heading: section ?? title, excerpt, url }, score });
+  };
+  let title = "";
+  let section: string | null = null;
+  let url: string | null = null;
+  let lines: string[] = [];
+  let fence: string | null = null;
+  const flush = () => { add(title, section, url, lines); lines = []; };
+  for (const line of (prose ?? "").split("\n")) {
+    const fenced = line.trim().match(/^(`{3,}|~{3,})/);
+    if (fenced) { if (fence === null) fence = fenced[1]![0]!; else if (fenced[1]![0] === fence) fence = null; continue; }
+    if (fence !== null) { if (line.trim()) lines.push(line); continue; }
+    const heading = line.match(/^(#{1,6})\s+(.+?)\s*#*$/);
+    if (heading) {
+      flush();
+      if (heading[1] === "#") {
+        title = cleanDocsText(heading[2]!);
+        section = null;
+        const link = heading[2]!.match(/\[[^\]]+\]\(([^\s)]+)\)/);
+        url = link ? docsLink(base, indexUrl, link[1]!) : pages.find((page) => page.title.toLowerCase() === title.toLowerCase())?.url ?? null;
+      } else section = cleanDocsText(heading[2]!);
+      continue;
+    }
+    const source = line.match(/^Source:\s*(?:\[[^\]]*\]\()?<?(https?:\/\/[^\s)>]+)>?\)?\s*$/i);
+    if (source) {
+      url = docsLink(base, indexUrl, source[1]!);
+      continue;
+    }
+    // Markdown callouts are blockquotes; keep their text for search and excerpts.
+    if (!line.trim() || /^\s*(?:---+|\|[\s:|-]+\|)\s*$/.test(line) || /^\s*</.test(line)) continue;
+    lines.push(line);
+  }
+  flush();
+  // An index is useful without llms-full.txt, and may include additional pages.
+  const described = new Set(candidates.map(({ match }) => match.url.replace(/\.md(?=[?#]|$)/, "")));
+  for (const page of pages) {
+    if (!described.has(page.url.replace(/\.md(?=[?#]|$)/, ""))) add(page.title, null, page.url, [page.description || page.title]);
+  }
+  candidates.sort((a, b) => b.score - a.score || a.match.title.localeCompare(b.match.title) || a.match.url.localeCompare(b.match.url));
+  const distinct = new Map<string, GuideMatch>();
+  for (const { match } of candidates) {
+    const key = match.url.replace(/\.md(?=[?#]|$)/, "");
+    if (!distinct.has(key)) distinct.set(key, match);
+  }
+  return [...distinct.values()];
+}
+
+export async function searchConnectedGuides(
+  base: string | null, indexUrl: string | null, fetchText: (path: string) => Promise<string | null>, query: string,
+): Promise<{ guides: GuideMatch[]; status: "not_configured" | "unavailable" | "ok" }> {
+  if (!base && !indexUrl) return { guides: [], status: "not_configured" };
+  const [index, prose] = await Promise.all([fetchText("llms.txt"), fetchText("llms-full.txt")]);
+  return { guides: searchGuidePages(prose, index, base, indexUrl, query), status: index === null && prose === null ? "unavailable" : "ok" };
+}
+
+export function docsReadTarget(index: string | null, base: string | null, indexUrl: string | null, page: string): string {
+  if (/^https?:\/\//.test(page)) return page;
+  const pages = docsIndexPages(index, base, indexUrl);
+  const term = page.toLowerCase();
+  const exact = pages.find((item) => item.title.toLowerCase() === term || new URL(item.url).pathname.toLowerCase() === term);
+  if (exact) return exact.url;
+  const matches = pages.filter((item) => item.url.toLowerCase().includes(term));
+  return matches.length === 1 ? matches[0]!.url : page;
+}
+
+/** One shell argument, including URLs with quotes, query strings, or fragments. */
+export function docsReadCommand(bin: string, url: string): string {
+  return bin + " docs read '" + url.replace(/'/g, "'\\''") + "'";
+}
+
 /** Markdown-preferred fetch with same-origin redirects, one deadline, and a
  * streaming byte cap. Returns null for every invalid or failed read. */
 export async function fetchDocsText(url: string): Promise<string | null> {

package/src/errors.ts

@@ -4,7 +4,7 @@
 import { ApiError, type ResponseMeta } from "./core/http.js";
 import type { ErrorModel, ErrorModelRead } from "./types.js";
 
-export { ApiError, TransportError, UnexpectedApiError, ValidationError, type Violation, unwrap } from "./core/http.js";
+export { ApiError, ResponseParseError, TransportError, UnexpectedApiError, ValidationError, type Violation, unwrap } from "./core/http.js";
 
 /**
  * The request body, Definition source, target selection, or package name is invalid.
@@ -36,6 +36,16 @@ export class ForbiddenError extends ApiError<403, ErrorModelRead> {
   }
 }
 
+/**
+ * The key identifies changed intent.
+ * Raised for HTTP 409 responses.
+ */
+export class ConflictError extends ApiError<409, ErrorModelRead> {
+  constructor(body: ErrorModelRead, response: ResponseMeta) {
+    super("The key identifies changed intent.", 409, body, response);
+  }
+}
+
 /**
  * Spec exceeds the 10MB limit.
  * Raised for HTTP 413 responses.
@@ -57,12 +67,13 @@ export class UnprocessableEntityError extends ApiError<422, ErrorModelRead> {
 }
 
 /**
- * Too many requests. Wait for Retry-After before retrying.
+ * Too many requests, or an identical write is still in progress. Wait for Retry-After before
+ * retrying.
  * Raised for HTTP 429 responses.
  */
 export class RateLimitedError extends ApiError<429, ErrorModelRead> {
   constructor(body: ErrorModelRead, response: ResponseMeta) {
-    super("Too many requests. Wait for Retry-After before retrying.", 429, body, response);
+    super("Too many requests, or an identical write is still in progress. Wait for Retry-After before retrying.", 429, body, response);
   }
 }
 
@@ -87,22 +98,12 @@ export class PaymentRequiredError extends ApiError<402, ErrorModelRead> {
 }
 
 /**
- * The Idempotency-Key was already used with different request parameters.
- * Raised for HTTP 409 responses.
- */
-export class ConflictError extends ApiError<409, ErrorModelRead> {
-  constructor(body: ErrorModelRead, response: ResponseMeta) {
-    super("The Idempotency-Key was already used with different request parameters.", 409, body, response);
-  }
-}
-
-/**
- * The original idempotent request is temporarily unavailable.
+ * Project setup failed unexpectedly; the key reservation is released.
  * Raised for HTTP 500 responses.
  */
 export class InternalServerError extends ApiError<500, ErrorModelRead> {
   constructor(body: ErrorModelRead, response: ResponseMeta) {
-    super("The original idempotent request is temporarily unavailable.", 500, body, response);
+    super("Project setup failed unexpectedly; the key reservation is released.", 500, body, response);
   }
 }
 
@@ -115,3 +116,13 @@ export class NotFoundError extends ApiError<404, ErrorModelRead> {
     super("No such resource in this account.", 404, body, response);
   }
 }
+
+/**
+ * The Project was saved, but an obsolete release pull request could not be retired.
+ * Raised for HTTP 502 responses.
+ */
+export class BadGatewayError extends ApiError<502, ErrorModelRead> {
+  constructor(body: ErrorModelRead, response: ResponseMeta) {
+    super("The Project was saved, but an obsolete release pull request could not be retired.", 502, body, response);
+  }
+}

package/src/index.ts

@@ -5,6 +5,7 @@ import {
   HttpCore,
   formatDebugEvent,
   type AuthValue,
+  type SecurityCredential,
   type DebugEvent,
   type RequestContext,
   bearerAuth,
@@ -21,8 +22,8 @@ import { AccountResource } from "./resources/account.js";
 import { ApiKeysResource } from "./resources/api-keys.js";
 
 /** This package's version, also sent as the `User-Agent`. */
-export const VERSION = "0.8.0";
-const USER_AGENT = "@typeship-ax/cli/0.8.0 (typeship)";
+export const VERSION = "0.9.1";
+const USER_AGENT = "@typeship-ax/cli/0.9.1 (typeship)";
 
 export interface ClientOptions {
   /** Override the server URL. Default: `https://typeship.dev/api/v1` */
@@ -32,6 +33,13 @@ export interface ClientOptions {
    * before every attempt.
    */
   bearerToken?: string | (() => string | Promise<string>);
+  /**
+   * Credentials keyed by the Definition's security scheme names. Only one complete alternative is
+   * sent for each operation. Named values take precedence over convenience options.
+   */
+  credentials?: {
+    "apiKey"?: AuthValue;
+  };
   /** Per-attempt timeout in milliseconds. Default: 30000. */
   timeoutMs?: number;
   /** Retries after the first attempt (retryable failures only). Default: 2. */
@@ -71,7 +79,7 @@ export interface ClientOptions {
 }
 
 /**
- * typeship — v0.8.0
+ * typeship — v0.9.1
  *
  * Resolve an OpenAPI or GraphQL Definition, diagnose it, and keep every
  * selected SDK, CLI, and MCP Target current.
@@ -105,7 +113,23 @@ export class TypeshipClient {
         ? (event: DebugEvent) => console.error(formatDebugEvent("typeship", event))
         : undefined;
     const query: Record<string, AuthValue> = {};
-    if (options.bearerToken !== undefined) headers["Authorization"] = bearerAuth(options.bearerToken);
+    const authHeaders: Record<string, AuthValue> = {};
+    const authQuery: Record<string, AuthValue> = {};
+
+    let bearerCredential: AuthValue | undefined;
+
+    if (options.bearerToken !== undefined) bearerCredential = bearerAuth(options.bearerToken);
+
+    const allowedCredentials = new Set<string>(["apiKey"]);
+    for (const name of Object.keys(options.credentials ?? {})) {
+      if (!allowedCredentials.has(name)) throw new Error("Unknown security scheme: " + name);
+    }
+    const credentials: Record<string, SecurityCredential> = Object.create(null);
+    {
+      const named = options.credentials && Object.hasOwn(options.credentials, "apiKey") ? options.credentials["apiKey"] : undefined;
+      const value = named !== undefined ? bearerAuth(named) : bearerCredential;
+      if (value !== undefined) credentials["apiKey"] = { headers: { ["Authorization"]: value } };
+    }
     const v = options.validate;
     const validate = v
       ? {
@@ -118,6 +142,7 @@ export class TypeshipClient {
       baseUrl: options.baseUrl ?? "https://typeship.dev/api/v1",
       headers,
       query,
+      credentials,
       fetch: options.fetch ?? fetch,
       timeoutMs: options.timeoutMs ?? 30_000,
       maxRetries: options.maxRetries ?? 2,

package/src/named-credentials.ts

@@ -0,0 +1,74 @@
+import { openSync, readSync, closeSync } from "node:fs";
+
+/** Runtime credentials keyed by the API's exact security-scheme names. */
+export type NamedCredential = string | { username: string; password: string };
+export type NamedCredentials = Record<string, NamedCredential>;
+export type CredentialSchemes = Record<string, { kind: string; options: string[] }>;
+
+export function parseNamedCredentials(value: unknown, schemes: CredentialSchemes): NamedCredentials {
+  if (typeof value === "string") {
+    if (new TextEncoder().encode(value).byteLength > 1_048_576) throw new Error("Named credentials exceed the 1 MiB limit.");
+    try { value = JSON.parse(value); } catch { throw new Error("Named credentials must be a JSON object keyed by security scheme. Credential contents are not included in errors."); }
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Named credentials must be a JSON object keyed by security scheme.");
+  const result: NamedCredentials = Object.create(null);
+  for (const [name, credential] of Object.entries(value)) {
+    if (!Object.hasOwn(schemes, name)) throw new Error("Named credentials contain an unknown or unsupported security scheme. Check the names listed by login --help.");
+    if (schemes[name]!.kind === "basic") {
+      if (!credential || typeof credential !== "object" || Array.isArray(credential) || Object.keys(credential).some((key) => key !== "username" && key !== "password") ||
+        typeof credential.username !== "string" || typeof credential.password !== "string" || !credential.username || !credential.password || credential.username.includes(":")) {
+        throw new Error("A named Basic credential requires a nonempty username and password; the username cannot contain a colon.");
+      }
+      result[name] = { username: credential.username, password: credential.password };
+    } else {
+      if (typeof credential !== "string" || !credential || /[\x00-\x1f\x7f]/.test(credential) || (schemes[name]!.kind === "bearer" && credential.includes(" "))) throw new Error("A named token or API key must be a nonempty string without control characters; bearer tokens cannot contain spaces.");
+      result[name] = credential;
+    }
+  }
+  return result;
+}
+
+/** Low-to-high source order. Within a source, exact names beat convenience options. */
+export function resolveNamedCredentials(schemes: CredentialSchemes, layers: { named?: NamedCredentials; options?: Record<string, unknown> }[]): NamedCredentials {
+  const resolved: NamedCredentials = Object.create(null);
+  for (const layer of layers) {
+    for (const [name, scheme] of Object.entries(schemes)) {
+      for (const option of scheme.options) {
+        if (option === "clientCredentials") continue;
+        const value = layer.options?.[option];
+        if (value !== undefined) resolved[name] = value as NamedCredential;
+      }
+    }
+    if (layer.named) Object.assign(resolved, parseNamedCredentials(layer.named, schemes));
+  }
+  return resolved;
+}
+
+/** Make convenience and named inputs comparable without expanding combinations. */
+export function namedCredentialAvailability(schemes: CredentialSchemes, options: Set<string>, named: NamedCredentials): Set<string> {
+  for (const [name, scheme] of Object.entries(schemes)) {
+    if (Object.hasOwn(named, name) || scheme.options.some((option) => options.has(option))) options.add("credentials." + name);
+  }
+  return options;
+}
+
+/** Bound file/stdin reads before allocating a full credential document. */
+export function readNamedCredentialsFile(input: string, schemes: CredentialSchemes): NamedCredentials {
+  let fd: number | undefined;
+  const chunks: Buffer[] = [];
+  let total = 0;
+  try {
+    fd = input === "-" ? 0 : openSync(input.slice(1), "r");
+    while (true) {
+      const buffer = Buffer.alloc(Math.min(32_768, 1_048_577 - total));
+      const size = readSync(fd, buffer, 0, buffer.length, null);
+      if (!size) break;
+      total += size;
+      if (total > 1_048_576) throw new Error("size");
+      chunks.push(buffer.subarray(0, size));
+    }
+  } catch {
+    throw new Error("Cannot read named credentials. Supply a readable JSON file or stdin input of at most 1 MiB.");
+  } finally { if (fd !== undefined && input !== "-") closeSync(fd); }
+  return parseNamedCredentials(Buffer.concat(chunks).toString("utf8"), schemes);
+}

package/src/oauth-login.ts

@@ -0,0 +1,184 @@
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { createServer } from "node:http";
+import { oauthJsonRequest, OAuthResponseError } from "./oauth-request.js";
+
+export interface OAuthLoginConfig {
+  issuer: string;
+  clientId: string;
+  discoveryUrl?: string;
+  authorizationUrl?: string;
+  tokenUrl?: string;
+  /** Register http://127.0.0.1/callback; an omitted port uses a random port. */
+  redirectUri?: string;
+  scopes?: string[];
+  audience?: string;
+  resource?: string;
+  /** Explicit runtime selection. The CLI verifies this ID through the API. */
+  organization?: { parameter: "organization" | "organization_id"; id: string };
+}
+
+export interface OAuthLoginSession {
+  accessToken: string;
+  refreshToken?: string;
+  expiresAt?: number;
+  issuer: string;
+  clientId: string;
+  tokenUrl: string;
+  /** The actual native callback used for this exchange, including its port. */
+  redirectUri: string;
+  revocationUrl?: string;
+  scopes?: string[];
+}
+
+export interface OAuthLoginInteraction {
+  /** Open or display the URL. Never send the verifier or returned tokens. */
+  authorize(url: string): void | Promise<void>;
+  signal?: AbortSignal;
+  timeoutMs?: number;
+}
+
+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.");
+  }
+  return url;
+}
+
+async function metadata(config: OAuthLoginConfig, signal: AbortSignal) {
+  const issuer = endpoint(config.issuer);
+  if (issuer.search) throw new Error("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,
+    issuer.origin + path + "/.well-known/openid-configuration",
+  ];
+  for (const url of urls) {
+    let response: Awaited<ReturnType<typeof oauthJsonRequest>>;
+    try { response = await oauthJsonRequest(endpoint(url), { headers: { Accept: "application/json" }, signal }, 10_000); }
+    catch (error) {
+      if (!signal.aborted && error instanceof OAuthResponseError && error.code === "request_failed") continue;
+      throw error;
+    }
+    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 (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.");
+    }
+    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.");
+    return {
+      authorizationUrl: endpoint(authorizationUrl), tokenUrl: endpoint(tokenUrl).href,
+      ...(typeof data.revocation_endpoint === "string" ? { revocationUrl: endpoint(data.revocation_endpoint).href } : {}),
+    };
+  }
+  // Some custom providers publish no metadata. Their explicit endpoints are
+  // owner configuration, not endpoints accepted from an unverified document.
+  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.");
+}
+
+/** 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.");
+  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.");
+  }
+  const verifier = randomBytes(32).toString("base64url");
+  const state = randomBytes(32).toString("base64url");
+  const challenge = createHash("sha256").update(verifier).digest("base64url");
+  let resolveCode!: (code: string) => void;
+  let rejectCode!: (error: Error) => void;
+  const codeResult = new Promise<string>((resolve, reject) => { resolveCode = resolve; rejectCode = reject; });
+  // Observe rejection even if opening the browser or starting the server fails.
+  void codeResult.catch(() => undefined);
+  let accepted = false;
+  const server = createServer((request, response) => {
+    response.setHeader("Content-Type", "text/plain; charset=utf-8");
+    response.setHeader("Cache-Control", "no-store");
+    response.setHeader("Referrer-Policy", "no-referrer");
+    response.setHeader("Content-Security-Policy", "default-src 'none'");
+    let incoming: URL;
+    try { incoming = new URL(request.url ?? "/", redirect.origin); } catch { response.writeHead(400).end("Invalid callback URL."); return; }
+    if (accepted || request.method !== "GET" || request.headers.host !== redirect.host || incoming.pathname !== redirect.pathname) {
+      response.writeHead(404).end("Not found."); return;
+    }
+    const returnedState = Buffer.from(incoming.searchParams.get("state") ?? "");
+    const expectedState = Buffer.from(state);
+    if (incoming.searchParams.getAll("state").length !== 1 || returnedState.length !== expectedState.length || !timingSafeEqual(returnedState, expectedState)) {
+      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)) {
+      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.")));
+      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.")));
+      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."));
+  signal.addEventListener("abort", aborted, { once: true });
+  try {
+    await new Promise<void>((resolve, reject) => {
+      server.once("error", reject);
+      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.");
+    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.");
+      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);
+    await interaction.authorize(authorization.href);
+    const code = await codeResult;
+    signal.throwIfAborted();
+    const response = await oauthJsonRequest(endpoints.tokenUrl, {
+      method: "POST", headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" }, redirect: "error",
+      body: new URLSearchParams({ grant_type: "authorization_code", client_id: config.clientId, redirect_uri: redirect.href, code, code_verifier: verifier, ...(config.audience ? { audience: config.audience } : {}), ...(config.resource ? { resource: config.resource } : {}) }),
+      signal,
+    });
+    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.`);
+    }
+    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.");
+    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,
+      ...(endpoints.revocationUrl ? { revocationUrl: endpoints.revocationUrl } : {}),
+      ...(typeof data.scope === "string" ? { scopes: data.scope.split(/\s+/).filter(Boolean) } : {}),
+    };
+  } finally {
+    signal.removeEventListener("abort", aborted);
+    server.closeAllConnections();
+    if (server.listening) await new Promise<void>((resolve) => server.close(() => resolve()));
+  }
+}

package/src/oauth-request.ts

@@ -0,0 +1,90 @@
+
+export class OAuthResponseError extends Error {
+  readonly code: "request_failed" | "timed_out" | "cancelled" | "response_too_large" | "invalid_response";
+  constructor(code: OAuthResponseError["code"]) {
+    const messages = {
+      request_failed: "OAuth request failed. Check the configured provider endpoint.",
+      timed_out: "OAuth request timed out. Run login again to retry.",
+      cancelled: "OAuth request was cancelled.",
+      response_too_large: "OAuth provider response exceeded 1 MiB.",
+      invalid_response: "OAuth provider returned an invalid JSON response.",
+    };
+    super(messages[code]);
+    this.code = code;
+    this.name = "OAuthResponseError";
+  }
+}
+
+export type DeviceOAuthError = "authorization_pending" | "slow_down" | "access_denied" | "expired_token";
+interface AuthenticationResponse { status: number; data?: Record<string, unknown>; error?: DeviceOAuthError }
+
+/** Error bodies and transport causes 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");
+}
+/** Device polling needs four protocol errors. Return only their exact names,
+ * never descriptions, error URIs, arbitrary error codes or other body fields. */
+export function oauthDeviceRequest(url: string | URL, init: RequestInit = {}, timeoutMs = 30_000): Promise<AuthenticationResponse> {
+  return boundedRequest(url, init, timeoutMs, "device");
+}
+/** Revocation may return an empty success body. Do not wait for or parse it. */
+export function oauthStatusRequest(url: string | URL, init: RequestInit = {}, timeoutMs = 30_000): Promise<{ status: number }> {
+  return boundedRequest(url, init, timeoutMs, "status");
+}
+
+/** Bound the entire exchange, including decoded response bytes. */
+async function boundedRequest(url: string | URL, init: RequestInit, timeoutMs: number, mode: "json" | "device" | "status"): Promise<AuthenticationResponse> {
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > 30_000) throw new OAuthResponseError("request_failed");
+  const controller = new AbortController();
+  let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let interrupted: "timed_out" | "cancelled" | 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(); };
+  const cancel = () => stop("cancelled");
+  init.signal?.addEventListener("abort", cancel, { once: true });
+  timer = setTimeout(() => stop("timed_out"), timeoutMs);
+  try {
+    if (init.signal?.aborted) throw new OAuthResponseError("cancelled");
+    const request: RequestInit & { cache: "no-store" } = { ...init, redirect: "error", credentials: "omit", cache: "no-store", signal: controller.signal };
+    const response = await Promise.race([
+      fetch(url, request).then((value) => {
+        // Also dispose a late response from a transport that ignored abort.
+        if (controller.signal.aborted) void value.body?.cancel().catch(() => {});
+        return value;
+      }), 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 (!response.body) throw new OAuthResponseError("invalid_response");
+    reader = response.body.getReader();
+    let size = 0, text = "";
+    const decoder = new TextDecoder("utf-8", { fatal: true });
+    while (true) {
+      const chunk = await Promise.race([reader.read(), deadline]);
+      if (chunk.done) break;
+      size += chunk.value.byteLength;
+      if (size > 1_048_576) throw new OAuthResponseError("response_too_large");
+      try { text += decoder.decode(chunk.value, { stream: true }); }
+      catch { throw new OAuthResponseError("invalid_response"); }
+    }
+    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");
+    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 } : {}) };
+    }
+    return { status: response.status, data: data as Record<string, unknown> };
+  } catch (error) {
+    if (interrupted) throw new OAuthResponseError(interrupted);
+    if (error instanceof OAuthResponseError) throw error;
+    throw new OAuthResponseError("request_failed");
+  } finally {
+    clearTimeout(timer); init.signal?.removeEventListener("abort", cancel); controller.abort();
+    if (reader) { void reader.cancel().catch(() => {}); reader.releaseLock(); }
+  }
+}