@typeship-ax/cli 0.8.0 → 0.9.1

package/dist/named-credentials.d.ts

@@ -0,0 +1,21 @@
+/** 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 declare function parseNamedCredentials(value: unknown, schemes: CredentialSchemes): NamedCredentials;
+/** Low-to-high source order. Within a source, exact names beat convenience options. */
+export declare function resolveNamedCredentials(schemes: CredentialSchemes, layers: {
+    named?: NamedCredentials;
+    options?: Record<string, unknown>;
+}[]): NamedCredentials;
+/** Make convenience and named inputs comparable without expanding combinations. */
+export declare function namedCredentialAvailability(schemes: CredentialSchemes, options: Set<string>, named: NamedCredentials): Set<string>;
+/** Bound file/stdin reads before allocating a full credential document. */
+export declare function readNamedCredentialsFile(input: string, schemes: CredentialSchemes): NamedCredentials;
+//# sourceMappingURL=named-credentials.d.ts.map

package/dist/named-credentials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"named-credentials.d.ts","sourceRoot":"","sources":["../src/named-credentials.ts"],"names":[],"mappings":"AAEA,0EAA0E;AAC1E,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAC9E,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;AAC/D,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAAC;AAEpF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,iBAAiB,GAAG,gBAAgB,CAqBlG;AAED,uFAAuF;AACvF,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,iBAAiB,EAAE,MAAM,EAAE;IAAE,KAAK,CAAC,EAAE,gBAAgB,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,EAAE,GAAG,gBAAgB,CAa/J;AAED,mFAAmF;AACnF,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,iBAAiB,EAAE,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,gBAAgB,GAAG,GAAG,CAAC,MAAM,CAAC,CAKlI;AAED,2EAA2E;AAC3E,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,gBAAgB,CAkBpG"}

package/dist/named-credentials.js

@@ -0,0 +1,86 @@
+import { openSync, readSync, closeSync } from "node:fs";
+export function parseNamedCredentials(value, schemes) {
+    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 = 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, layers) {
+    const resolved = 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;
+            }
+        }
+        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, options, named) {
+    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, schemes) {
+    let fd;
+    const chunks = [];
+    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/dist/oauth-login.d.ts

@@ -0,0 +1,39 @@
+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;
+}
+/** 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 declare function oauthBrowserLogin(config: OAuthLoginConfig, interaction: OAuthLoginInteraction): Promise<OAuthLoginSession>;
+//# sourceMappingURL=oauth-login.d.ts.map

package/dist/oauth-login.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-login.d.ts","sourceRoot":"","sources":["../src/oauth-login.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,YAAY,CAAC,EAAE;QAAE,SAAS,EAAE,cAAc,GAAG,iBAAiB,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9E;AAED,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,2EAA2E;IAC3E,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAgDD;gFACgF;AAChF,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,gBAAgB,EAAE,WAAW,EAAE,qBAAqB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAgGhI"}

package/dist/oauth-login.js

@@ -0,0 +1,171 @@
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { createServer } from "node:http";
+import { oauthJsonRequest, OAuthResponseError } from "./oauth-request.js";
+function endpoint(value) {
+    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, signal) {
+    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;
+        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, interaction) {
+    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;
+    let rejectCode;
+    const codeResult = new Promise((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;
+        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((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((resolve) => server.close(() => resolve()));
+    }
+}

package/dist/oauth-request.d.ts

@@ -0,0 +1,21 @@
+export declare class OAuthResponseError extends Error {
+    readonly code: "request_failed" | "timed_out" | "cancelled" | "response_too_large" | "invalid_response";
+    constructor(code: OAuthResponseError["code"]);
+}
+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 declare function oauthJsonRequest(url: string | URL, init?: RequestInit, timeoutMs?: number): Promise<AuthenticationResponse>;
+/** Device polling needs four protocol errors. Return only their exact names,
+ * never descriptions, error URIs, arbitrary error codes or other body fields. */
+export declare function oauthDeviceRequest(url: string | URL, init?: RequestInit, timeoutMs?: number): Promise<AuthenticationResponse>;
+/** Revocation may return an empty success body. Do not wait for or parse it. */
+export declare function oauthStatusRequest(url: string | URL, init?: RequestInit, timeoutMs?: number): Promise<{
+    status: number;
+}>;
+export {};
+//# sourceMappingURL=oauth-request.d.ts.map

package/dist/oauth-request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-request.d.ts","sourceRoot":"","sources":["../src/oauth-request.ts"],"names":[],"mappings":"AACA,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,IAAI,EAAE,gBAAgB,GAAG,WAAW,GAAG,WAAW,GAAG,oBAAoB,GAAG,kBAAkB,CAAC;gBAC5F,IAAI,EAAE,kBAAkB,CAAC,MAAM,CAAC;CAY7C;AAED,MAAM,MAAM,gBAAgB,GAAG,uBAAuB,GAAG,WAAW,GAAG,eAAe,GAAG,eAAe,CAAC;AACzG,UAAU,sBAAsB;IAAG,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE,gBAAgB,CAAA;CAAE;AAE7G,mFAAmF;AACnF,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,EAAE,IAAI,GAAE,WAAgB,EAAE,SAAS,SAAS,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAE/H;AACD;iFACiF;AACjF,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,EAAE,IAAI,GAAE,WAAgB,EAAE,SAAS,SAAS,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAEjI;AACD,gFAAgF;AAChF,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,EAAE,IAAI,GAAE,WAAgB,EAAE,SAAS,SAAS,GAAG,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAE7H"}

package/dist/oauth-request.js

@@ -0,0 +1,119 @@
+export class OAuthResponseError extends Error {
+    code;
+    constructor(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";
+    }
+}
+/** Error bodies and transport causes may contain credentials and are discarded. */
+export function oauthJsonRequest(url, init = {}, timeoutMs = 30_000) {
+    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, init = {}, timeoutMs = 30_000) {
+    return boundedRequest(url, init, timeoutMs, "device");
+}
+/** Revocation may return an empty success body. Do not wait for or parse it. */
+export function oauthStatusRequest(url, init = {}, timeoutMs = 30_000) {
+    return boundedRequest(url, init, timeoutMs, "status");
+}
+/** Bound the entire exchange, including decoded response bytes. */
+async function boundedRequest(url, init, timeoutMs, mode) {
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > 30_000)
+        throw new OAuthResponseError("request_failed");
+    const controller = new AbortController();
+    let reader;
+    let timer;
+    let interrupted;
+    let rejectDeadline;
+    const deadline = new Promise((_, reject) => { rejectDeadline = reject; });
+    const stop = (code) => { 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 = { ...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;
+        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.error;
+            return { status: response.status, ...(["authorization_pending", "slow_down", "access_denied", "expired_token"].includes(String(error)) && typeof error === "string" ? { error: error } : {}) };
+        }
+        return { status: response.status, data: data };
+    }
+    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();
+        }
+    }
+}

package/dist/oauth-session.d.ts

@@ -0,0 +1,106 @@
+import { type IdentityConfiguration, type VerifiedIdentity } from "./api-identity.js";
+export interface StoredOAuthSession {
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt?: number;
+    tokenUrl?: string;
+    issuer?: string;
+    clientId?: string;
+    revocationUrl?: string;
+    apiBaseUrl?: string;
+    configuredClientId?: string | null;
+    scopes?: string[];
+    /** New login identity, independent of rotating tokens. */
+    sessionId: string;
+    binding: string;
+    /** Persisted before exchange: an interrupted exchange must not replay a rotating token. */
+    refreshPending?: boolean;
+}
+export interface CredentialDestination {
+    apiBaseUrl: string;
+    environment?: string;
+    profile?: string;
+}
+export declare function assertCredentialDestination(credentials: StoredCredentials, destination: CredentialDestination): void;
+export interface StoredCredentials {
+    destination?: CredentialDestination;
+    named?: Record<string, string | {
+        username: string;
+        password: string;
+    }>;
+    scalars?: Record<string, string>;
+    basic?: {
+        username: string;
+        password: string;
+    };
+    oauth?: StoredOAuthSession;
+    identity?: VerifiedIdentity & {
+        binding: string;
+    };
+    minted?: {
+        via: "browser";
+        key_name: string;
+        org_id?: string;
+        revocationUrl?: string;
+    };
+}
+export interface SessionConfiguration extends CredentialDestination {
+    identity?: IdentityConfiguration;
+    verifyIdentity?: (accessToken: string) => Promise<VerifiedIdentity>;
+    clientId?: string | null;
+    issuer?: string | null;
+    tokenUrl?: string | null;
+    discoveryUrl?: string | null;
+    authorizationUrl?: string | null;
+    scopes?: string[];
+    audience?: string;
+    resource?: string;
+    organizationParameter?: "organization" | "organization_id";
+}
+/** Bind minimal identity evidence to this credential set and its configured read. */
+export declare function credentialIdentityBinding(credentials: StoredCredentials, identity: IdentityConfiguration): string;
+export declare function assertStoredIdentity(credentials: StoredCredentials, identity?: IdentityConfiguration): void;
+/** Bind the login to effective nonsecret settings. Scope ordering is irrelevant. */
+export declare function sessionBinding(config: SessionConfiguration): string;
+interface LockedCredentials {
+    read(): StoredCredentials | null;
+    write(credentials: StoredCredentials | null): void;
+}
+export interface CredentialStore {
+    read(): StoredCredentials | null;
+    withLock<T>(work: (store: LockedCredentials) => Promise<T>): Promise<T>;
+}
+export declare class CredentialStorageError extends Error {
+}
+export interface CredentialCodec {
+    readonly name: string;
+    prepare(): void;
+    encode(plaintext: string): string;
+    decode(encoded: string): string;
+}
+/** Private file adapter. All writers (login, refresh and logout) use the same
+ * cross-process lock. Credential storage can be replaced independently of OAuth. */
+export declare class FileCredentialStore implements CredentialStore {
+    readonly path: string;
+    private readonly lockTimeoutMs;
+    private readonly codec?;
+    constructor(path: string, lockTimeoutMs?: number, codec?: CredentialCodec | undefined);
+    get backend(): string;
+    /** Check storage access before starting an interactive login. */
+    prepare(): Promise<void>;
+    read(): StoredCredentials | null;
+    private write;
+    withLock<T>(work: (store: LockedCredentials) => Promise<T>): Promise<T>;
+    private recoverDeadOwner;
+    update(change: (current: StoredCredentials) => StoredCredentials): Promise<void>;
+    /** Explicit local-only logout can remove an unreadable encrypted session. */
+    clear(): Promise<boolean>;
+    /** Remove under the refresh lock, then revoke the latest token outside it. */
+    take(): Promise<StoredCredentials | null>;
+}
+/** 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 declare function oauthSessionToken(store: CredentialStore, config: SessionConfiguration, sessionId: string, tokenParams?: Record<string, string>): Promise<string>;
+export {};
+//# sourceMappingURL=oauth-session.d.ts.map

package/dist/oauth-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-session.d.ts","sourceRoot":"","sources":["../src/oauth-session.ts"],"names":[],"mappings":"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"}