@deque/axe-auth 1.7.1-next.783fc70a → 1.7.1-next.81f1793b

package/README.md

@@ -95,7 +95,7 @@ Under npm the wrapped process inherits the values directly and the listener stay
 npx @deque/axe-auth run -- npx axe-mcp-server
 ```
 
-`run` picks a free loopback port per session; pin one with `AXE_TOKEN_REFRESH_PORT` or `--port` only for containers, which can reach only a port you publish. `run` generates the shared secret unless you pin one with `AXE_TOKEN_REFRESH_SECRET` / `--secret`. The secret authenticates the push; the server's listener binds loopback by default and never starts without a secret.
+`run` picks a free loopback port per session; pin one with `AXE_TOKEN_REFRESH_PORT` or `--port` only for containers, which can reach only a port you publish. `run` generates the shared secret unless you pin one with `AXE_TOKEN_REFRESH_SECRET`. `--secret` also works, but other local users can read it in the process list, so `run` warns when you use it. The secret authenticates the push; the server's listener binds loopback by default and never starts without a secret.
 
 ## Architecture
 

package/dist/cli/confirm.js

@@ -1,7 +1,11 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.confirm = confirm;
 const node_readline_1 = require("node:readline");
+const toTerminalText_1 = __importDefault(require("../toTerminalText"));
 /**
  * Reads a single line from `input` and returns `true` for an
  * affirmative answer (`y` / `yes`, case-insensitive), `false`
@@ -11,9 +15,8 @@ const node_readline_1 = require("node:readline");
 async function confirm(options) {
     const input = options.input ?? process.stdin;
     const output = options.output ?? process.stderr;
-    const question = options.question.endsWith(" ")
-        ? options.question
-        : `${options.question} `;
+    const text = (0, toTerminalText_1.default)(options.question);
+    const question = text.endsWith(" ") ? text : `${text} `;
     // Use createInterface rather than the higher-level `rl.question`
     // promise API because the latter wires up SIGINT handling that
     // doesn't compose well when this is called from a CLI dispatcher

package/dist/commands/login.js

@@ -12,6 +12,8 @@ const tokenStore_1 = require("../oauth/tokenStore");
 const confirm_1 = require("../cli/confirm");
 const login_help_1 = require("./login.help");
 const errors_2 = require("../cli/errors");
+const toTerminalText_1 = __importDefault(require("../toTerminalText"));
+const toPrintableASCII_1 = __importDefault(require("../toPrintableASCII"));
 /** `axe-auth login` — drive the OAuth flow and persist tokens. */
 const loginCommand = {
     name: "login",
@@ -56,20 +58,28 @@ const loginCommand = {
             if (stored.ok) {
                 const sameIssuer = stored.entry.issuerURL === issuerURL &&
                     stored.entry.clientId === clientId;
+                // The issuer and client ID come from the axe server's SSO config, so
+                // keep each to one printable line wherever they are shown.
+                const shown = {
+                    issuer: (0, toPrintableASCII_1.default)(issuerURL),
+                    client: (0, toPrintableASCII_1.default)(clientId),
+                    storedIssuer: (0, toPrintableASCII_1.default)(stored.entry.issuerURL),
+                    storedClient: (0, toPrintableASCII_1.default)(stored.entry.clientId),
+                };
                 if (!isInteractive) {
                     throw new errors_2.CLIError("ALREADY_AUTHENTICATED", sameIssuer
-                        ? `Already authenticated against ${issuerURL}. Re-run with --force to override.`
+                        ? `Already authenticated against ${shown.issuer}. Re-run with --force to override.`
                         : (0, ts_dedent_1.dedent) `
-                  Currently authenticated against ${stored.entry.issuerURL}.
-                  Logging in to ${issuerURL} would replace those tokens.
+                  Currently authenticated against ${shown.storedIssuer}.
+                  Logging in to ${shown.issuer} would replace those tokens.
                   Re-run with --force to override.
                 `);
                 }
                 const prompt = sameIssuer
-                    ? `Already authenticated against ${issuerURL}. Re-authenticate? [y/N]`
+                    ? `Already authenticated against ${shown.issuer}. Re-authenticate? [y/N]`
                     : (0, ts_dedent_1.dedent) `
-              Currently authenticated against ${stored.entry.issuerURL} (client ${stored.entry.clientId}).
-              Logging in to ${issuerURL} (client ${clientId}) will replace those tokens.
+              Currently authenticated against ${shown.storedIssuer} (client ${shown.storedClient}).
+              Logging in to ${shown.issuer} (client ${shown.client}) will replace those tokens.
               Continue? [y/N]
             `;
                 const ok = await confirmFn(prompt);
@@ -89,10 +99,10 @@ const loginCommand = {
                 allowInsecureIssuer: args.allowInsecureIssuer,
                 tokenStore,
                 onAuthorizationURL: (url) => {
-                    deps.stderr.write(`Authorization URL: ${url}\n`);
+                    deps.stderr.write(`Authorization URL: ${(0, toTerminalText_1.default)(url)}\n`);
                 },
                 onWarning: (msg) => {
-                    deps.stderr.write(`axe-auth: ${msg}\n`);
+                    deps.stderr.write(`axe-auth: ${(0, toTerminalText_1.default)(msg)}\n`);
                 },
             });
         }

package/dist/commands/logout.js

@@ -1,10 +1,14 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 const discoverOIDC_1 = require("../oauth/discoverOIDC");
 const revokeToken_1 = require("../oauth/revokeToken");
 const tokenStore_1 = require("../oauth/tokenStore");
 const logout_help_1 = require("./logout.help");
 const errors_1 = require("../cli/errors");
+const toTerminalText_1 = __importDefault(require("../toTerminalText"));
 /** `axe-auth logout` — best-effort revoke + always clear local. */
 const logoutCommand = {
     name: "logout",
@@ -50,7 +54,7 @@ const logoutCommand = {
                 }
             }
             catch (err) {
-                deps.stderr.write(`axe-auth: server-side revocation failed (${(0, errors_1.describeError)(err)}). Continuing with local clear.\n`);
+                deps.stderr.write(`axe-auth: server-side revocation failed (${(0, toTerminalText_1.default)((0, errors_1.describeError)(err))}). Continuing with local clear.\n`);
             }
         }
         await clearLocal(tokenStore);

package/dist/commands/run.js

@@ -9,6 +9,7 @@ const runSession_1 = __importDefault(require("../run/runSession"));
 const findFreePort_1 = __importDefault(require("../run/findFreePort"));
 const run_help_1 = require("./run.help");
 const errors_1 = require("../cli/errors");
+const toTerminalText_1 = __importDefault(require("../toTerminalText"));
 /** Container runtimes whose child cannot reach a host port it was not told to publish. */
 const CONTAINER_COMMANDS = new Set(["docker", "podman", "nerdctl"]);
 /** Whether `command` launches a container runtime rather than a local process. */
@@ -45,13 +46,16 @@ async function dispatchRun(rest, deps) {
         }).values;
     }
     catch (err) {
-        deps.stderr.write(`${(0, errors_1.describeError)(err)}\n`);
+        deps.stderr.write(`${(0, toTerminalText_1.default)((0, errors_1.describeError)(err))}\n`);
         return 2;
     }
     if (values.help) {
         deps.stdout.write(`${run_help_1.HELP_RUN}\n`);
         return 0;
     }
+    if (values.secret !== undefined) {
+        deps.stderr.write("axe-auth run: --secret is visible to other local users via the process list; set AXE_TOKEN_REFRESH_SECRET instead\n");
+    }
     if (childArgv.length === 0) {
         deps.stderr.write("axe-auth run needs a command after `--`, e.g. `npx @deque/axe-auth run -- docker run ... axe-mcp-server`\n");
         return 2;
@@ -64,7 +68,7 @@ async function dispatchRun(rest, deps) {
     if (portRaw) {
         port = Number(portRaw);
         if (!Number.isInteger(port) || port <= 0 || port >= 65536) {
-            deps.stderr.write(`Invalid port ${portRaw}: must be a TCP port (1-65535)\n`);
+            deps.stderr.write(`Invalid port ${(0, toTerminalText_1.default)(portRaw)}: must be a TCP port (1-65535)\n`);
             return 2;
         }
     }
@@ -99,10 +103,10 @@ async function dispatchRun(rest, deps) {
     }
     catch (err) {
         if (err instanceof errors_1.CLIError) {
-            deps.stderr.write(`${err.message}\n`);
+            deps.stderr.write(`${(0, toTerminalText_1.default)(err.message)}\n`);
             return err.exitCode;
         }
-        deps.stderr.write(`${(0, errors_1.describeError)(err)}\n`);
+        deps.stderr.write(`${(0, toTerminalText_1.default)((0, errors_1.describeError)(err))}\n`);
         return 2;
     }
 }

package/dist/index.js

@@ -15,6 +15,7 @@ const token_1 = __importDefault(require("./commands/token"));
 const run_1 = require("./commands/run");
 const errors_1 = require("./cli/errors");
 const safeExit_1 = require("./cli/safeExit");
+const toTerminalText_1 = __importDefault(require("./toTerminalText"));
 const pkg = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(__dirname, "..", "package.json"), "utf-8"));
 const COMMANDS = [
     login_1.default,
@@ -60,7 +61,7 @@ async function dispatch(argv) {
         return 0;
     }
     if (first.startsWith("-")) {
-        process.stderr.write(`Unknown option: ${first}. Run \`axe-auth --help\` for usage.\n`);
+        process.stderr.write(`Unknown option: ${(0, toTerminalText_1.default)(first)}. Run \`axe-auth --help\` for usage.\n`);
         return 2;
     }
     // `run` wraps a launch command after `--`; it can't go through the shared
@@ -74,7 +75,7 @@ async function dispatch(argv) {
     }
     const command = findCommand(first);
     if (!command) {
-        process.stderr.write(`Unknown command: ${first}. Run \`axe-auth --help\` for usage.\n`);
+        process.stderr.write(`Unknown command: ${(0, toTerminalText_1.default)(first)}. Run \`axe-auth --help\` for usage.\n`);
         return 2;
     }
     let parsed;
@@ -91,7 +92,7 @@ async function dispatch(argv) {
         });
     }
     catch (err) {
-        process.stderr.write(`${(0, errors_1.describeError)(err)}\n`);
+        process.stderr.write(`${(0, toTerminalText_1.default)((0, errors_1.describeError)(err))}\n`);
         return 2;
     }
     if (parsed.values.help) {
@@ -121,7 +122,7 @@ async function dispatch(argv) {
         common = (0, commonArgs_1.parseCommonArgs)(parsed.values, process.env, defaults);
     }
     catch (err) {
-        process.stderr.write(`${(0, errors_1.describeError)(err)}\n`);
+        process.stderr.write(`${(0, toTerminalText_1.default)((0, errors_1.describeError)(err))}\n`);
         return 2;
     }
     const deps = {
@@ -136,14 +137,14 @@ async function dispatch(argv) {
     }
     catch (err) {
         if (err instanceof errors_1.CLIError) {
-            process.stderr.write(`${err.message}\n`);
+            process.stderr.write(`${(0, toTerminalText_1.default)(err.message)}\n`);
             return err.exitCode;
         }
-        process.stderr.write(`${(0, errors_1.describeError)(err)}\n`);
+        process.stderr.write(`${(0, toTerminalText_1.default)((0, errors_1.describeError)(err))}\n`);
         return 2;
     }
 }
 dispatch(process.argv.slice(2)).then((code) => (0, safeExit_1.safeExit)(code), (err) => {
-    process.stderr.write(`${err instanceof Error ? (err.stack ?? err.message) : String(err)}\n`);
+    process.stderr.write(`${(0, toTerminalText_1.default)(err instanceof Error ? (err.stack ?? err.message) : String(err))}\n`);
     return (0, safeExit_1.safeExit)(1);
 });

package/dist/oauth/authorizationURL.js

@@ -1,7 +1,11 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildAuthorizationURL = buildAuthorizationURL;
 const errors_1 = require("./errors");
+const toPrintableASCII_1 = __importDefault(require("../toPrintableASCII"));
 // Pre-existing values for these on the authorization endpoint are a
 // security trap: the auth server's disambiguation is unspecified.
 const OAUTH_REQUIRED_PARAMS = [
@@ -29,7 +33,7 @@ function buildAuthorizationURL(options) {
             collisions.push(name);
     }
     if (collisions.length > 0) {
-        throw new errors_1.OAuthFlowError("INVALID_AUTHORIZATION_ENDPOINT", `Authorization endpoint ${options.authorizationEndpoint} already carries OAuth-required param(s) ${collisions.join(", ")}; refusing to ship a URL the server may disambiguate unpredictably.`, { details: { params: collisions.join(",") } });
+        throw new errors_1.OAuthFlowError("INVALID_AUTHORIZATION_ENDPOINT", `Authorization endpoint ${(0, toPrintableASCII_1.default)(options.authorizationEndpoint)} already carries OAuth-required param(s) ${collisions.join(", ")}; refusing to ship a URL the server may disambiguate unpredictably.`, { details: { params: collisions.join(",") } });
     }
     // `set` each required OAuth param. Non-OAuth params the discovery
     // endpoint already carries (e.g. Keycloak's `kc_idp_hint=github`)

package/dist/oauth/authorize.js

@@ -1,4 +1,7 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.authorize = authorize;
 const callbackServer_1 = require("./callbackServer");
@@ -9,14 +12,16 @@ const openBrowser_1 = require("./openBrowser");
 const tokenExchange_1 = require("./tokenExchange");
 const tokenStore_1 = require("./tokenStore");
 const errors_1 = require("./errors");
+const toTerminalText_1 = __importDefault(require("../toTerminalText"));
+const toPrintableASCII_1 = __importDefault(require("../toPrintableASCII"));
 function defaultOnAuthorizationURL(url) {
     if (process.stderr.isTTY) {
-        console.error(`Authorization URL: ${url}`);
+        console.error(`Authorization URL: ${(0, toTerminalText_1.default)(url)}`);
     }
 }
 function defaultOnWarning(message) {
     if (process.stderr.isTTY) {
-        console.error(`axe-auth: ${message}`);
+        console.error(`axe-auth: ${(0, toTerminalText_1.default)(message)}`);
     }
 }
 /**
@@ -98,7 +103,7 @@ async function authorize(options) {
         // screen may have dropped the scope.
         if (scopes.includes("offline_access") && !tokens.refreshToken) {
             const grantedSuffix = tokens.grantedScope
-                ? ` (server granted: ${tokens.grantedScope})`
+                ? ` (server granted: ${(0, toPrintableASCII_1.default)(tokens.grantedScope)})`
                 : "";
             onWarning(`'offline_access' was requested but no refresh_token was returned${grantedSuffix}. Cross-session refresh will not be available.`);
         }

package/dist/oauth/callbackServer.js

@@ -1,4 +1,7 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.bindLoopback = bindLoopback;
 exports.startCallbackServer = startCallbackServer;
@@ -6,6 +9,7 @@ const node_events_1 = require("node:events");
 const node_http_1 = require("node:http");
 const errors_1 = require("./errors");
 const renderHTML_1 = require("./renderHTML");
+const toPrintableASCII_1 = __importDefault(require("../toPrintableASCII"));
 const DEFAULT_TIMEOUT_MS = 120_000;
 const LOOPBACK_ADDRESSES = new Set(["127.0.0.1", "::1", "::ffff:127.0.0.1"]);
 function isLoopback(addr) {
@@ -177,10 +181,24 @@ async function startCallbackServer(opts) {
             }));
             return;
         }
+        const code = url.searchParams.get("code");
+        const state = url.searchParams.get("state");
+        // Checked before `error` so that only the authorization server, which
+        // echoes `state` on error redirects too (RFC 6749 §4.1.2.1), gets its
+        // error text shown to the user.
+        if (state !== expectedState) {
+            const error = new errors_1.OAuthCallbackError("STATE_MISMATCH", "Authorization response 'state' did not match expected value.");
+            deferSettleOnClose(res, () => rejectResult(error));
+            writeHTML(res, 400, (0, renderHTML_1.renderHTML)({
+                kind: "error",
+                reason: "The authorization response failed state validation.",
+            }));
+            return;
+        }
         const providerError = url.searchParams.get("error");
         if (providerError) {
             const description = url.searchParams.get("error_description") ?? undefined;
-            const error = new errors_1.OAuthCallbackError("PROVIDER_ERROR", `Authorization server returned error: ${providerError}`, {
+            const error = new errors_1.OAuthCallbackError("PROVIDER_ERROR", `Authorization server returned error: ${(0, toPrintableASCII_1.default)(providerError)}`, {
                 details: description
                     ? { error: providerError, error_description: description }
                     : { error: providerError },
@@ -193,8 +211,6 @@ async function startCallbackServer(opts) {
             }));
             return;
         }
-        const code = url.searchParams.get("code");
-        const state = url.searchParams.get("state");
         if (!code) {
             const error = new errors_1.OAuthCallbackError("MISSING_CODE", "Authorization response missing 'code' parameter.");
             deferSettleOnClose(res, () => rejectResult(error));
@@ -204,15 +220,6 @@ async function startCallbackServer(opts) {
             }));
             return;
         }
-        if (state !== expectedState) {
-            const error = new errors_1.OAuthCallbackError("STATE_MISMATCH", "Authorization response 'state' did not match expected value.");
-            deferSettleOnClose(res, () => rejectResult(error));
-            writeHTML(res, 400, (0, renderHTML_1.renderHTML)({
-                kind: "error",
-                reason: "The authorization response failed state validation.",
-            }));
-            return;
-        }
         deferSettleOnClose(res, () => resolveResult({ code, state }));
         writeHTML(res, 200, (0, renderHTML_1.renderHTML)({ kind: "success" }));
     };

package/dist/oauth/discoverOIDC.js

@@ -1,10 +1,14 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.discoverOIDC = discoverOIDC;
 const errors_1 = require("./errors");
 const issuerURL_1 = require("./issuerURL");
 const predicates_1 = require("./predicates");
 const userAgent_1 = require("../userAgent");
+const toPrintableASCII_1 = __importDefault(require("../toPrintableASCII"));
 const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
 function optionalString(v) {
     return (0, predicates_1.isNonEmptyString)(v) ? v : undefined;
@@ -16,7 +20,7 @@ function assertSecureURL(url, label, allowInsecurePermitted) {
         parsed = new URL(url);
     }
     catch {
-        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `${label} is not a valid URL: ${url}`);
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `${label} is not a valid URL: ${(0, toPrintableASCII_1.default)(url)}`);
     }
     if (parsed.protocol === "https:")
         return;
@@ -53,7 +57,7 @@ function parseConfiguration(body, url) {
     if (!(0, predicates_1.isNonEmptyString)(body.token_endpoint))
         missing.push("token_endpoint");
     if (missing.length > 0) {
-        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `OpenID configuration at ${url} is missing required field(s): ${missing.join(", ")}`);
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `OpenID configuration at ${(0, toPrintableASCII_1.default)(url)} is missing required field(s): ${missing.join(", ")}`);
     }
     return {
         issuer: body.issuer,
@@ -75,7 +79,7 @@ function assertPKCESupport(body, url) {
         return;
     if (methods.includes("S256"))
         return;
-    throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `OpenID configuration at ${url} advertises code_challenge_methods_supported = ${JSON.stringify(methods)}, but axe-auth requires S256 (PKCE per RFC 7636). The OAuth client used by axe-auth needs PKCE enabled, or you may be on an axe server version that predates OAuth-based MCP authentication.`);
+    throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `OpenID configuration at ${(0, toPrintableASCII_1.default)(url)} advertises code_challenge_methods_supported = ${(0, toPrintableASCII_1.default)(JSON.stringify(methods))}, but axe-auth requires S256 (PKCE per RFC 7636). The OAuth client used by axe-auth needs PKCE enabled, or you may be on an axe server version that predates OAuth-based MCP authentication.`);
 }
 /**
  * Fetches and parses the OIDC discovery document. Fails fast (no
@@ -101,20 +105,20 @@ async function discoverOIDC(issuerURL, options = {}) {
         });
     }
     catch (cause) {
-        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `Could not reach the authentication server at ${url}. Check the URL and your network connection.`, { cause });
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `Could not reach the authentication server at ${(0, toPrintableASCII_1.default)(url)}. Check the URL and your network connection.`, { cause });
     }
     if (!response.ok) {
-        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `Authentication server at ${url} responded with HTTP ${response.status}. Check the issuer URL.`);
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `Authentication server at ${(0, toPrintableASCII_1.default)(url)} responded with HTTP ${response.status}. Check the issuer URL.`);
     }
     let body;
     try {
         body = await response.json();
     }
     catch (cause) {
-        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `Authentication server at ${url} did not return a valid JSON OpenID configuration`, { cause });
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `Authentication server at ${(0, toPrintableASCII_1.default)(url)} did not return a valid JSON OpenID configuration`, { cause });
     }
     if (body === null || typeof body !== "object") {
-        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `OpenID configuration at ${url} was not a JSON object`);
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `OpenID configuration at ${(0, toPrintableASCII_1.default)(url)} was not a JSON object`);
     }
     const config = parseConfiguration(body, url);
     // OIDC Discovery §3: the `issuer` value returned MUST equal the URL
@@ -124,7 +128,7 @@ async function discoverOIDC(issuerURL, options = {}) {
     // token endpoints to attacker hosts while still appearing to come
     // from the legitimate origin.
     if ((0, issuerURL_1.normalizeIssuerURL)(config.issuer) !== (0, issuerURL_1.normalizeIssuerURL)(issuerURL)) {
-        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `Issuer mismatch: requested ${issuerURL} but discovery document claims ${config.issuer}`);
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `Issuer mismatch: requested ${(0, toPrintableASCII_1.default)(issuerURL)} but discovery document claims ${(0, toPrintableASCII_1.default)(config.issuer)}`);
     }
     // Enforce scheme on the endpoints the flow actually hits. A tampered
     // discovery response could claim the legitimate issuer while

package/dist/oauth/errors.d.ts

@@ -2,11 +2,11 @@
 export type OAuthCallbackErrorCode = 
 /** No callback arrived within `timeoutMs`; a retry is reasonable. */
 "TIMEOUT"
-/** Callback `state` did not match `expectedState`. Surface a generic failure — do NOT echo the expected value. */
+/** Callback `state` did not match `expectedState`. Checked first, so it takes precedence over `?error=` and a missing `code`. Surface a generic failure — do NOT echo the expected value. */
  | "STATE_MISMATCH"
-/** Callback carried `?error=...`. `details` holds `error` and optionally `error_description` for display. */
+/** Callback carried a matching `state` and `?error=...`. `details` holds the raw `error` and optional `error_description`. */
  | "PROVIDER_ERROR"
-/** Callback had no `code` parameter; treat as a malformed response. */
+/** Callback carried a matching `state` but no `code`; treat as a malformed response. */
  | "MISSING_CODE"
 /** Could not bind the loopback port. No retry — environment likely blocked. */
  | "BIND_FAILED"
@@ -27,7 +27,11 @@ export interface OAuthCallbackErrorOptions {
 export declare class OAuthCallbackError extends Error {
     /** Discriminator for programmatic handling. */
     readonly code: OAuthCallbackErrorCode;
-    /** Structured metadata carried alongside the error, if any. */
+    /**
+     * Raw, unsanitized values from the authorization server, for matching
+     * (e.g. `details.error === "access_denied"`). Not for display: unlike
+     * `message`, control characters are left in.
+     */
     readonly details?: Record<string, string>;
     constructor(code: OAuthCallbackErrorCode, message: string, options?: OAuthCallbackErrorOptions);
 }
@@ -71,7 +75,12 @@ export interface OAuthFlowErrorOptions {
 export declare class OAuthFlowError extends Error {
     /** Discriminator for programmatic handling. */
     readonly code: OAuthFlowErrorCode;
-    /** Structured metadata carried alongside the error, if any. */
+    /**
+     * Structured metadata, for matching (e.g. `details.error ===
+     * "invalid_grant"`). Values from the authorization server are raw and
+     * unsanitized, so do not display them: unlike `message`, control
+     * characters are left in.
+     */
     readonly details?: Record<string, string>;
     constructor(code: OAuthFlowErrorCode, message: string, options?: OAuthFlowErrorOptions);
 }

package/dist/oauth/errors.js

@@ -9,7 +9,11 @@ exports.OAuthFlowError = exports.OAuthCallbackError = void 0;
 class OAuthCallbackError extends Error {
     /** Discriminator for programmatic handling. */
     code;
-    /** Structured metadata carried alongside the error, if any. */
+    /**
+     * Raw, unsanitized values from the authorization server, for matching
+     * (e.g. `details.error === "access_denied"`). Not for display: unlike
+     * `message`, control characters are left in.
+     */
     details;
     constructor(code, message, options = {}) {
         super(message, { cause: options.cause });
@@ -36,7 +40,12 @@ exports.OAuthCallbackError = OAuthCallbackError;
 class OAuthFlowError extends Error {
     /** Discriminator for programmatic handling. */
     code;
-    /** Structured metadata carried alongside the error, if any. */
+    /**
+     * Structured metadata, for matching (e.g. `details.error ===
+     * "invalid_grant"`). Values from the authorization server are raw and
+     * unsanitized, so do not display them: unlike `message`, control
+     * characters are left in.
+     */
     details;
     constructor(code, message, options = {}) {
         super(message, { cause: options.cause });

package/dist/oauth/getValidAccessToken.js

@@ -1,14 +1,19 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getValidAccessToken = getValidAccessToken;
 const discoverOIDC_1 = require("./discoverOIDC");
 const errors_1 = require("./errors");
 const refreshTokens_1 = require("./refreshTokens");
+const toPrintableASCII_1 = __importDefault(require("../toPrintableASCII"));
 const tokenStore_1 = require("./tokenStore");
+const toTerminalText_1 = __importDefault(require("../toTerminalText"));
 const DEFAULT_EXPIRY_BUFFER_MS = 60_000;
 function defaultOnWarning(message) {
     if (process.stderr.isTTY) {
-        console.error(`axe-auth: ${message}`);
+        console.error(`axe-auth: ${(0, toTerminalText_1.default)(message)}`);
     }
 }
 function isInvalidGrant(err) {
@@ -64,7 +69,7 @@ async function getValidAccessToken(options) {
     // server.
     if (loaded.entry.issuerURL !== issuerURL ||
         loaded.entry.clientId !== clientId) {
-        throw notAuthenticated(`Stored credentials are for issuer ${loaded.entry.issuerURL} (client ${loaded.entry.clientId}), but the requested issuer is ${issuerURL} (client ${clientId}). Run \`axe-auth login\` to re-authenticate.`);
+        throw notAuthenticated(`Stored credentials are for issuer ${(0, toPrintableASCII_1.default)(loaded.entry.issuerURL)} (client ${(0, toPrintableASCII_1.default)(loaded.entry.clientId)}), but the requested issuer is ${(0, toPrintableASCII_1.default)(issuerURL)} (client ${(0, toPrintableASCII_1.default)(clientId)}). Run \`axe-auth login\` to re-authenticate.`);
     }
     const tokens = loaded.entry.tokens;
     if (now() + expiryBufferMs < tokens.expiresAt) {

package/dist/oauth/refreshTokens.js

@@ -1,10 +1,14 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.refreshTokens = refreshTokens;
 const errors_1 = require("./errors");
 const retry_1 = require("./retry");
 const tokenResponse_1 = require("./tokenResponse");
 const userAgent_1 = require("../userAgent");
+const toPrintableASCII_1 = __importDefault(require("../toPrintableASCII"));
 /**
  * Exchanges a refresh token for a fresh access token via RFC 6749 §6.
  *
@@ -44,11 +48,14 @@ async function refreshTokens(options) {
                 "User-Agent": userAgent_1.USER_AGENT,
             },
             body,
+            // A 307/308 would replay the refresh token to a URL discovery never vetted;
+            // "manual" surfaces the 3xx as an HTTP error rather than a network one.
+            redirect: "manual",
             signal: options.signal,
         });
     }
     catch (cause) {
-        throw new errors_1.OAuthFlowError("TOKEN_EXCHANGE_FAILED", `Could not reach the token endpoint at ${options.tokenEndpoint}. Check your network connection.`, { cause });
+        throw new errors_1.OAuthFlowError("TOKEN_EXCHANGE_FAILED", `Could not reach the token endpoint at ${(0, toPrintableASCII_1.default)(options.tokenEndpoint)}. Check your network connection.`, { cause });
     }
     if (!response.ok) {
         await (0, tokenResponse_1.throwTokenEndpointError)(response, "Token refresh");

package/dist/oauth/revokeToken.js

@@ -1,8 +1,12 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.revokeRefreshToken = revokeRefreshToken;
 const retry_1 = require("./retry");
 const userAgent_1 = require("../userAgent");
+const toPrintableASCII_1 = __importDefault(require("../toPrintableASCII"));
 /**
  * Revokes a refresh token via RFC 7009. Servers SHOULD return 200
  * regardless of whether the token was valid (the spec doesn't want
@@ -34,12 +38,15 @@ async function revokeRefreshToken(options) {
                 "User-Agent": userAgent_1.USER_AGENT,
             },
             body,
+            // A 307/308 would replay the refresh token to a URL discovery never vetted;
+            // "manual" surfaces the 3xx as an HTTP error rather than a network one.
+            redirect: "manual",
             signal: options.signal,
         });
     }
     catch (cause) {
         const reason = cause instanceof Error ? cause.message : String(cause);
-        throw new Error(`Could not reach the revocation endpoint at ${options.revocationEndpoint}: ${reason}`, { cause });
+        throw new Error(`Could not reach the revocation endpoint at ${(0, toPrintableASCII_1.default)(options.revocationEndpoint)}: ${reason}`, { cause });
     }
     if (!response.ok) {
         // Deliberately do NOT include the response body. The request
@@ -59,6 +66,6 @@ async function revokeRefreshToken(options) {
         catch {
             // ignore — body is purely diagnostic
         }
-        throw new Error(`Revocation endpoint at ${options.revocationEndpoint} returned HTTP ${response.status}`);
+        throw new Error(`Revocation endpoint at ${(0, toPrintableASCII_1.default)(options.revocationEndpoint)} returned HTTP ${response.status}`);
     }
 }

package/dist/oauth/testUtils.d.ts

@@ -33,3 +33,23 @@ export declare const KEYCLOAK_ISSUER = "http://localhost:8080/auth/realms/local"
  * (Bearer, positive `expires_in`) are what most tests want.
  */
 export declare function tokenResponseBody(overrides?: Record<string, unknown>): Record<string, unknown>;
+/** A loopback endpoint that answers every request with a 307 to a second server. */
+export interface RedirectingEndpoint {
+    /** URL of the endpoint that issues the redirect. */
+    url: string;
+    /** Request bodies received by the redirect target. */
+    targetBodies: string[];
+    /** Stops both servers. */
+    close(): Promise<void>;
+}
+/**
+ * Starts two loopback servers: one that 307-redirects everything to the
+ * other, and a target that records each request body it receives.
+ */
+export declare function startRedirectingEndpoint(): Promise<RedirectingEndpoint>;
+/**
+ * Lists the control characters (C0, DEL, C1) in `text`, as code points, so
+ * a test can assert none reached a terminal-bound message. `allowed` names
+ * characters the caller expects to keep, such as `"\n"`.
+ */
+export declare function controlCharacters(text: string, allowed?: string): number[];

package/dist/oauth/testUtils.js

@@ -7,6 +7,9 @@ exports.KEYCLOAK_ISSUER = exports.FIXED_NOW = void 0;
 exports.withFetch = withFetch;
 exports.jsonResponse = jsonResponse;
 exports.tokenResponseBody = tokenResponseBody;
+exports.startRedirectingEndpoint = startRedirectingEndpoint;
+exports.controlCharacters = controlCharacters;
+const node_http_1 = require("node:http");
 /**
  * A fixed "now" timestamp used by token-endpoint tests that need
  * determinism for `expiresAt` assertions. Any constant would do;
@@ -59,3 +62,53 @@ function tokenResponseBody(overrides = {}) {
         ...overrides,
     };
 }
+/**
+ * Starts two loopback servers: one that 307-redirects everything to the
+ * other, and a target that records each request body it receives.
+ */
+async function startRedirectingEndpoint() {
+    const targetBodies = [];
+    const target = (0, node_http_1.createServer)((req, res) => {
+        let body = "";
+        req.on("data", (chunk) => (body += chunk));
+        req.on("end", () => {
+            targetBodies.push(body);
+            res.statusCode = 200;
+            res.setHeader("content-type", "application/json");
+            res.end(JSON.stringify(tokenResponseBody()));
+        });
+    });
+    await listen(target);
+    const targetURL = `http://127.0.0.1:${target.address().port}/elsewhere`;
+    const origin = (0, node_http_1.createServer)((req, res) => {
+        req.resume();
+        res.statusCode = 307;
+        res.setHeader("location", targetURL);
+        res.end();
+    });
+    await listen(origin);
+    return {
+        url: `http://127.0.0.1:${origin.address().port}/token`,
+        targetBodies,
+        close: async () => {
+            await Promise.all([target, origin].map(closeServer));
+        },
+    };
+}
+function listen(server) {
+    return new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+}
+function closeServer(server) {
+    return new Promise((resolve) => server.close(() => resolve()));
+}
+/**
+ * Lists the control characters (C0, DEL, C1) in `text`, as code points, so
+ * a test can assert none reached a terminal-bound message. `allowed` names
+ * characters the caller expects to keep, such as `"\n"`.
+ */
+function controlCharacters(text, allowed = "") {
+    return [...text]
+        .filter((c) => !allowed.includes(c))
+        .map((c) => c.codePointAt(0))
+        .filter((cp) => cp < 0x20 || (cp >= 0x7f && cp <= 0x9f));
+}

package/dist/oauth/tokenExchange.js

@@ -1,10 +1,14 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.exchangeCodeForTokens = exchangeCodeForTokens;
 const errors_1 = require("./errors");
 const retry_1 = require("./retry");
 const tokenResponse_1 = require("./tokenResponse");
 const userAgent_1 = require("../userAgent");
+const toPrintableASCII_1 = __importDefault(require("../toPrintableASCII"));
 /**
  * Exchanges an authorization code for a `TokenSet` via the
  * authorization server's token endpoint (RFC 6749 §4.1.3 + RFC 7636
@@ -32,11 +36,14 @@ async function exchangeCodeForTokens(options) {
                 "User-Agent": userAgent_1.USER_AGENT,
             },
             body,
+            // A 307/308 would replay the code verifier to a URL discovery never vetted;
+            // "manual" surfaces the 3xx as an HTTP error rather than a network one.
+            redirect: "manual",
             signal: options.signal,
         });
     }
     catch (cause) {
-        throw new errors_1.OAuthFlowError("TOKEN_EXCHANGE_FAILED", `Could not reach the token endpoint at ${options.tokenEndpoint}. Check your network connection.`, { cause });
+        throw new errors_1.OAuthFlowError("TOKEN_EXCHANGE_FAILED", `Could not reach the token endpoint at ${(0, toPrintableASCII_1.default)(options.tokenEndpoint)}. Check your network connection.`, { cause });
     }
     if (!response.ok) {
         await (0, tokenResponse_1.throwTokenEndpointError)(response, "Token exchange");

package/dist/oauth/tokenResponse.js

@@ -1,9 +1,13 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.throwTokenEndpointError = throwTokenEndpointError;
 exports.parseTokenResponse = parseTokenResponse;
 const errors_1 = require("./errors");
 const predicates_1 = require("./predicates");
+const toPrintableASCII_1 = __importDefault(require("../toPrintableASCII"));
 // RFC 6749 §5.1 doesn't pin the JSON type and some providers send
 // numeric strings; accept both, reject non-positive or non-finite.
 function parseExpiresIn(v) {
@@ -43,8 +47,8 @@ async function throwTokenEndpointError(response, context) {
     const { error, description } = parseErrorBody(body);
     const suffix = error
         ? description
-            ? `: ${error}: ${description}`
-            : `: ${error}`
+            ? `: ${(0, toPrintableASCII_1.default)(error)}: ${(0, toPrintableASCII_1.default)(description)}`
+            : `: ${(0, toPrintableASCII_1.default)(error)}`
         : "";
     const details = {};
     if (error)
@@ -64,10 +68,10 @@ async function parseTokenResponse(response, issuedAt, endpointURL) {
         parsed = await response.json();
     }
     catch (cause) {
-        throw new errors_1.OAuthFlowError("TOKEN_EXCHANGE_FAILED", `Token endpoint at ${endpointURL} returned a non-JSON response`, { cause });
+        throw new errors_1.OAuthFlowError("TOKEN_EXCHANGE_FAILED", `Token endpoint at ${(0, toPrintableASCII_1.default)(endpointURL)} returned a non-JSON response`, { cause });
     }
     if (parsed === null || typeof parsed !== "object") {
-        throw new errors_1.OAuthFlowError("TOKEN_EXCHANGE_FAILED", `Token endpoint at ${endpointURL} returned a non-object response`);
+        throw new errors_1.OAuthFlowError("TOKEN_EXCHANGE_FAILED", `Token endpoint at ${(0, toPrintableASCII_1.default)(endpointURL)} returned a non-object response`);
     }
     const raw = parsed;
     if (!(0, predicates_1.isNonEmptyString)(raw.access_token)) {
@@ -85,7 +89,7 @@ async function parseTokenResponse(response, issuedAt, endpointURL) {
         throw new errors_1.OAuthFlowError("TOKEN_EXCHANGE_FAILED", `Token response missing required 'token_type'`);
     }
     if (raw.token_type.toLowerCase() !== "bearer") {
-        throw new errors_1.OAuthFlowError("TOKEN_EXCHANGE_FAILED", `Unsupported token_type '${raw.token_type}'; this library only handles Bearer.`);
+        throw new errors_1.OAuthFlowError("TOKEN_EXCHANGE_FAILED", `Unsupported token_type '${(0, toPrintableASCII_1.default)(raw.token_type)}'; this library only handles Bearer.`);
     }
     const tokens = {
         accessToken: raw.access_token,

package/dist/run/pushToken.js

@@ -1,7 +1,11 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.REFRESH_SECRET_HEADER = void 0;
 exports.default = pushToken;
+const toPrintableASCII_1 = __importDefault(require("../toPrintableASCII"));
 /** Header carrying the shared secret on a token-refresh push. Matches the server's listener. */
 exports.REFRESH_SECRET_HEADER = "x-refresh-secret";
 /** Bound the push so a stalled server can't hang the caller. */
@@ -21,14 +25,10 @@ async function pushToken({ port, secret, accessToken, }) {
     });
     if (!res.ok) {
         // Whatever holds this port wrote the body, and it reaches the client's
-        // stderr, so take a little of it and strip anything that could forge log
-        // lines or redraw the terminal.
+        // stderr, so repeat only a little of it.
         const detail = await res
             .text()
-            .then((text) => text
-            .slice(0, MAX_DETAIL_LEN)
-            .replace(/[^\t\x20-\x7e]/g, " ")
-            .trim())
+            .then((text) => (0, toPrintableASCII_1.default)(text.slice(0, MAX_DETAIL_LEN)).trim())
             .catch(() => "");
         throw new Error(`server responded ${res.status}${detail ? `: ${detail}` : ""}`);
     }

package/dist/run/runSession.js

@@ -44,6 +44,7 @@ const tokenStore_1 = require("../oauth/tokenStore");
 const errors_2 = require("../cli/errors");
 const supervise_1 = __importStar(require("./supervise"));
 const pushToken_1 = __importDefault(require("./pushToken"));
+const toTerminalText_1 = __importDefault(require("../toTerminalText"));
 /**
  * Cadence of the refresh-and-push loop. Must be shorter than the access-token
  * TTL: each tick mints (which refreshes when the token is near expiry) and
@@ -130,7 +131,7 @@ async function runSession(options) {
     // louder line (they will keep failing every tick otherwise). The session
     // stays alive on its last good token.
     const noteRecoverableFailure = (message) => {
-        stderr.write(`axe-auth run: token refresh failed: ${message}\n`);
+        stderr.write(`axe-auth run: token refresh failed: ${(0, toTerminalText_1.default)(message)}\n`);
         consecutiveFailures += 1;
         if (consecutiveFailures === CONSECUTIVE_FAILURE_WARNING_THRESHOLD) {
             stderr.write(`axe-auth run: token refresh has failed ${consecutiveFailures} times in a row; the server's access token will expire and calls will start failing — check that the refresh listener is reachable\n`);

package/dist/toPrintableASCII.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Replaces everything outside printable ASCII (tab excepted) with a space,
+ * for remote-supplied text bound for the terminal: control sequences in it
+ * could forge log lines or redraw the screen.
+ */
+export default function toPrintableASCII(text: string): string;

package/dist/toPrintableASCII.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = toPrintableASCII;
+/**
+ * Replaces everything outside printable ASCII (tab excepted) with a space,
+ * for remote-supplied text bound for the terminal: control sequences in it
+ * could forge log lines or redraw the screen.
+ */
+function toPrintableASCII(text) {
+    return text.replace(/[^\t\x20-\x7e]/g, " ");
+}

package/dist/toTerminalText.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Replaces control characters other than tab and newline, and bidirectional
+ * controls, with a space, for text bound for the terminal: control sequences
+ * in remote-supplied text could forge log lines, redraw the screen, or reorder
+ * what is displayed. Unlike `toPrintableASCII`,
+ * newlines and non-ASCII survive, so it can wrap the CLI's own multi-line
+ * messages at the point they are written.
+ */
+export default function toTerminalText(text: string): string;

package/dist/toTerminalText.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = toTerminalText;
+/**
+ * Replaces control characters other than tab and newline, and bidirectional
+ * controls, with a space, for text bound for the terminal: control sequences
+ * in remote-supplied text could forge log lines, redraw the screen, or reorder
+ * what is displayed. Unlike `toPrintableASCII`,
+ * newlines and non-ASCII survive, so it can wrap the CLI's own multi-line
+ * messages at the point they are written.
+ */
+function toTerminalText(text) {
+    return text.replace(/[^\t\n\x20-\x7e\u00a0-\uffff]|[\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/g, " ");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deque/axe-auth",
-  "version": "1.7.1-next.783fc70a",
+  "version": "1.7.1-next.81f1793b",
   "description": "CLI authentication utility for Deque services",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {