@typeship-ax/cli 0.22.0 → 0.24.0

package/dist/named-credentials.js

@@ -37,7 +37,7 @@ export function resolveNamedCredentials(schemes, layers) {
     for (const layer of layers) {
         for (const [name, scheme] of Object.entries(schemes)) {
             for (const option of scheme.options) {
-                if (option === "clientCredentials")
+                if (option === "clientCredentials" || option === "refreshToken")
                     continue;
                 const value = layer.options?.[option];
                 if (value !== undefined)
@@ -57,6 +57,27 @@ export function namedCredentialAvailability(schemes, options, named) {
     }
     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) {
+    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, credentialOptions, options) {
+    const supplied = (key, value) => 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 ?? {})).filter(([name, value]) => supplied(name, value)));
+    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, schemes) {
     let fd;
@@ -84,3 +105,62 @@ export function readNamedCredentialsFile(input, schemes) {
     }
     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, flags, variable) {
+    const entries = [];
+    const line = (text, source) => {
+        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;
+            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));
+        }
+        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 = {};
+    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, extra) {
+    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/dist/oauth-login.d.ts

@@ -1,5 +1,11 @@
+/** Browser OAuth login did not complete; the message names the cause. */
+export declare class OAuthLoginError extends Error {
+    constructor(message?: string);
+}
 export interface OAuthLoginConfig {
-    issuer: string;
+    /** Exact issuer, when the provider publishes metadata. Without one, the
+     * explicit authorization and token URLs from the API Spec are used. */
+    issuer?: string | null;
     clientId: string;
     discoveryUrl?: string;
     authorizationUrl?: string;
@@ -19,7 +25,7 @@ export interface OAuthLoginSession {
     accessToken: string;
     refreshToken?: string;
     expiresAt?: number;
-    issuer: string;
+    issuer?: string;
     clientId: string;
     tokenUrl: string;
     /** The actual native callback used for this exchange, including its port. */

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

@@ -1 +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"}
+{"version":3,"file":"oauth-login.d.ts","sourceRoot":"","sources":["../src/oauth-login.ts"],"names":[],"mappings":"AAIA,yEAAyE;AACzE,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,OAAO,CAAC,EAAE,MAAM;CAC7B;AAED,MAAM,WAAW,gBAAgB;IAC/B;2EACuE;IACvE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,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,CAAC,EAAE,MAAM,CAAC;IAChB,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;AAqDD;gFACgF;AAChF,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,gBAAgB,EAAE,WAAW,EAAE,qBAAqB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAmGhI"}

package/dist/oauth-login.js

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

package/dist/oauth-request.d.ts

@@ -7,8 +7,14 @@ 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;
 }
-/** Error bodies and transport causes may contain credentials and are discarded. */
+/** The provider's standard error fields, never any other body content. */
+export declare function providerErrorOf(data: Record<string, unknown>): string | undefined;
+/** Transport causes and error bodies beyond the standard OAuth `error` and
+ * `error_description` fields 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. */

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

@@ -1 +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"}
+{"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;IAC9B,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzE;+EAC2E;IAC3E,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,0EAA0E;AAC1E,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,SAAS,CAKjF;AAED;2EAC2E;AAC3E,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

@@ -13,7 +13,16 @@ export class OAuthResponseError extends Error {
         this.name = "OAuthResponseError";
     }
 }
-/** Error bodies and transport causes may contain credentials and are discarded. */
+/** The provider's standard error fields, never any other body content. */
+export function providerErrorOf(data) {
+    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;
+}
+/** Transport causes and error bodies beyond the standard OAuth `error` and
+ * `error_description` fields may contain credentials and are discarded. */
 export function oauthJsonRequest(url, init = {}, timeoutMs = 30_000) {
     return boundedRequest(url, init, timeoutMs, "json");
 }
@@ -34,6 +43,9 @@ async function boundedRequest(url, init, timeoutMs, mode) {
     let reader;
     let timer;
     let interrupted;
+    // 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;
     let rejectDeadline;
     const deadline = new Promise((_, reject) => { rejectDeadline = reject; });
     const stop = (code) => { interrupted ??= code; rejectDeadline(new OAuthResponseError(interrupted)); controller.abort(); };
@@ -56,10 +68,12 @@ async function boundedRequest(url, init, timeoutMs, mode) {
             void response.body?.cancel().catch(() => { });
             throw new OAuthResponseError("request_failed");
         }
-        if (mode === "status" || response.status !== 200 && !(mode === "device" && response.status === 400)) {
+        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();
@@ -90,17 +104,25 @@ async function boundedRequest(url, init, timeoutMs, mode) {
             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 (!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.error;
-            return { status: response.status, ...(["authorization_pending", "slow_down", "access_denied", "expired_token"].includes(String(error)) && typeof error === "string" ? { error: error } : {}) };
+            const providerError = providerErrorOf(data);
+            return { status: response.status, ...(providerError ? { providerError } : {}), ...(mode === "device" && ["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 (errorStatus !== undefined && interrupted !== "cancelled")
+            return { status: errorStatus };
         if (interrupted)
             throw new OAuthResponseError(interrupted);
         if (error instanceof OAuthResponseError)

package/dist/oauth-session.d.ts

@@ -70,7 +70,13 @@ export interface CredentialStore {
     read(): StoredCredentials | null;
     withLock<T>(work: (store: LockedCredentials) => Promise<T>): Promise<T>;
 }
+/** The OS credential store or the saved credential file cannot be used. */
 export declare class CredentialStorageError extends Error {
+    constructor(message?: string);
+}
+/** A saved login cannot be used as is; the remedy is to sign in again. */
+export declare class OAuthSessionError extends Error {
+    constructor(message?: string);
 }
 export interface CredentialCodec {
     readonly name: string;
@@ -101,6 +107,12 @@ export declare class FileCredentialStore implements CredentialStore {
 /** 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 declare function oauthSessionToken(store: CredentialStore, config: SessionConfiguration, sessionId: string, tokenParams?: Record<string, string>, rejected?: string): Promise<string>;
+/** 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 declare function sessionCredential(resolve: (rejected?: string) => Promise<string>): (() => Promise<string>) & {
+    invalidate(): void;
+};
 export {};
 //# sourceMappingURL=oauth-session.d.ts.map

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

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

package/dist/oauth-session.js

@@ -6,11 +6,11 @@ import { oauthJsonRequest } from "./oauth-request.js";
 export function assertCredentialDestination(credentials, destination) {
     const saved = credentials.destination;
     if (!saved)
-        throw new Error("Saved credentials have no API and profile binding. Log in again before using them.");
+        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 Error("The API destination changed. Log in again before using saved credentials.");
+        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 Error("The credential environment or profile changed. Log in again before using saved credentials.");
+        throw new OAuthSessionError("The credential environment or profile changed. Log in again before using saved credentials.");
 }
 /** Bind minimal identity evidence to this credential set and its configured read. */
 export function credentialIdentityBinding(credentials, identity) {
@@ -24,7 +24,7 @@ export function assertStoredIdentity(credentials, identity) {
     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.");
     }
 }
 /** Bind the login to effective nonsecret settings. Scope ordering is irrelevant. */
@@ -49,7 +49,13 @@ function alive(pid) {
         return code(error) !== "ESRCH";
     }
 }
+/** The OS credential store or the saved credential file cannot be used. */
 export class CredentialStorageError extends Error {
+    constructor(message) { 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) { super(message); this.name = "OAuthSessionError"; }
 }
 /** Private file adapter. All writers (login, refresh and logout) use the same
  * cross-process lock. Credential storage can be replaced independently of OAuth. */
@@ -78,7 +84,7 @@ export class FileCredentialStore {
                 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.");
         }
     }
     write(credentials) {
@@ -113,10 +119,10 @@ export class FileCredentialStore {
                 }
                 catch (error) {
                     if (code(error) !== "EEXIST")
-                        throw new Error("Cannot lock the credential store.");
+                        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 + ".");
+                        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));
                 }
             }
@@ -170,27 +176,29 @@ export class FileCredentialStore {
 function validSession(credentials, config, sessionId, allowPending = false) {
     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.");
+        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 Error("The API destination changed. Log in again.");
+        throw new OAuthSessionError("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.");
+        throw new OAuthSessionError("The configured issuer changed. Log in again.");
     if (session.configuredClientId !== (config.clientId ?? null))
-        throw new Error("The OAuth client changed. Log in again.");
+        throw new OAuthSessionError("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.");
+        throw new OAuthSessionError("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.");
+        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 Error("The saved OAuth session is invalid. Log in again.");
+        throw new OAuthSessionError("The saved OAuth session is invalid. Log in again.");
     assertStoredIdentity(credentials, config.identity);
     return session;
 }
 /** 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, config, sessionId, tokenParams = {}) {
-    const fresh = (session) => session.expiresAt === undefined || (Number.isFinite(session.expiresAt) && session.expiresAt > Date.now() + 60_000);
+export async function oauthSessionToken(store, config, sessionId, tokenParams = {}, rejected) {
+    // 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) => 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;
@@ -200,7 +208,7 @@ export async function oauthSessionToken(store, config, sessionId, tokenParams =
         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.");
+            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.");
@@ -238,7 +246,15 @@ export async function oauthSessionToken(store, config, sessionId, tokenParams =
         }
         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) {
+    let last, rejected;
+    const token = async () => { const previous = rejected; rejected = undefined; last = await resolve(previous); return last; };
+    return Object.assign(token, { invalidate() { rejected = last; } });
+}