@deque/axe-auth 1.1.0-next.759bd5c5 → 1.1.0-next.7b8e88e6

package/dist/commands/login.js

@@ -1,7 +1,12 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 const ts_dedent_1 = require("ts-dedent");
+const remove_trailing_slash_1 = __importDefault(require("remove-trailing-slash"));
 const authorize_1 = require("../oauth/authorize");
+const discoverSSOConfig_1 = require("../oauth/discoverSSOConfig");
 const errors_1 = require("../oauth/errors");
 const tokenStore_1 = require("../oauth/tokenStore");
 const confirm_1 = require("../cli/confirm");
@@ -19,6 +24,7 @@ const loginCommand = {
     async run(args, deps) {
         const isInteractive = deps.isInteractive ?? Boolean(deps.stdin.isTTY);
         const authorizeFn = deps.authorize ?? authorize_1.authorize;
+        const discoverFn = deps.discoverSSOConfig ?? discoverSSOConfig_1.discoverSSOConfig;
         const confirmFn = deps.confirm ??
             ((prompt) => (0, confirm_1.confirm)({
                 question: prompt,
@@ -26,9 +32,27 @@ const loginCommand = {
                 output: deps.stderr,
             }));
         const tokenStore = deps.tokenStore ?? new tokenStore_1.KeyringTokenStore();
+        // 1. Ask the axe server where its Keycloak lives and which client to use.
+        //    This is the only step that hits the axe server directly; from here on
+        //    the CLI talks to Keycloak using the discovered coordinates.
+        let ssoConfig;
+        try {
+            ssoConfig = await discoverFn(args.walnutURL, {
+                allowInsecure: args.allowInsecureIssuer,
+            });
+        }
+        catch (err) {
+            if (err instanceof errors_1.OAuthFlowError) {
+                throw new errors_2.CLIError("OAUTH_FAILED", err.message);
+            }
+            throw err;
+        }
+        const issuerURL = `${(0, remove_trailing_slash_1.default)(ssoConfig.url)}/auth/realms/${ssoConfig.realm}`;
+        const clientId = ssoConfig.mcpClientId;
+        // 2. Re-auth confirmation. Same UX as the previous flag-driven
+        //    flow, but the comparison is against the *discovered* issuer
+        //    + client, not user-supplied flags.
         if (!args.force) {
-            // Prefer the entry the dispatcher already loaded; only fall
-            // back to a fresh read when there isn't one (test path).
             const stored = deps.loadedEntry ?? (await tokenStore.load());
             if (!stored.ok && stored.reason !== "empty") {
                 // Existing entry is unreadable (corrupt or stored under a
@@ -38,26 +62,22 @@ const loginCommand = {
                 deps.stderr.write(`axe-auth: replacing unreadable stored credentials (${stored.reason}).\n`);
             }
             if (stored.ok) {
-                // Two cases: same issuer (re-auth, today's prompt) and
-                // different issuer (overwriting another login's tokens).
-                // Both warrant confirmation; the message text differs so the
-                // user understands what's about to be lost.
-                const sameIssuer = stored.entry.issuerURL === args.issuerURL &&
-                    stored.entry.clientId === args.clientId;
+                const sameIssuer = stored.entry.issuerURL === issuerURL &&
+                    stored.entry.clientId === clientId;
                 if (!isInteractive) {
                     throw new errors_2.CLIError("ALREADY_AUTHENTICATED", sameIssuer
-                        ? `Already authenticated against ${args.issuerURL}. Re-run with --force to override.`
+                        ? `Already authenticated against ${issuerURL}. Re-run with --force to override.`
                         : (0, ts_dedent_1.dedent) `
                   Currently authenticated against ${stored.entry.issuerURL}.
-                  Logging in to ${args.issuerURL} would replace those tokens.
+                  Logging in to ${issuerURL} would replace those tokens.
                   Re-run with --force to override.
                 `);
                 }
                 const prompt = sameIssuer
-                    ? `Already authenticated against ${args.issuerURL}. Re-authenticate? [y/N]`
+                    ? `Already authenticated against ${issuerURL}. Re-authenticate? [y/N]`
                     : (0, ts_dedent_1.dedent) `
               Currently authenticated against ${stored.entry.issuerURL} (client ${stored.entry.clientId}).
-              Logging in to ${args.issuerURL} (client ${args.clientId}) will replace those tokens.
+              Logging in to ${issuerURL} (client ${clientId}) will replace those tokens.
               Continue? [y/N]
             `;
                 const ok = await confirmFn(prompt);
@@ -66,10 +86,14 @@ const loginCommand = {
                 }
             }
         }
+        // 3. Drive the OAuth flow. The originating axe server URL rides along
+        //    so it lands in the StoredEntry and future verbs (re-discovery,
+        //    revoke) can operate without user-supplied flags.
         try {
             await authorizeFn({
-                issuerURL: args.issuerURL,
-                clientId: args.clientId,
+                issuerURL,
+                clientId,
+                walnutURL: args.walnutURL,
                 scopes: ["offline_access"],
                 allowInsecureIssuer: args.allowInsecureIssuer,
                 tokenStore,

package/dist/commands/logout.d.ts

@@ -19,6 +19,6 @@ declare const logoutCommand: {
     helpText: string;
     options: {};
     requiresConfig: false;
-    run(args: CommonArgs, deps: LogoutDeps): Promise<void>;
+    run(_args: CommonArgs, deps: LogoutDeps): Promise<void>;
 };
 export default logoutCommand;

package/dist/commands/logout.help.d.ts

@@ -1,2 +1,2 @@
 /** Help text for `axe-auth logout --help`. */
-export declare const HELP_LOGOUT = "axe-auth logout\n\nRevoke the stored refresh token server-side (best-effort) and clear\nthe local OS keychain entry.\n\nUsage:\n  axe-auth logout\n\n  --server / --realm / --client-id flags are accepted for\n  parity with `login` but are ignored: the stored entry's issuer\n  and client identify what to revoke. Mismatched flags produce a\n  warning on stderr.\n\nOptions:\n  --server <url>           Authorization-server base URL.\n                           Falls back to AXE_OAUTH_SERVER.\n  --realm <name>           Keycloak realm name.\n                           Falls back to AXE_OAUTH_REALM.\n  --client-id <id>         OAuth client ID.\n                           Falls back to AXE_OAUTH_CLIENT_ID.\n  --allow-insecure-issuer  Permit non-loopback http issuers (default\n                           is https only; loopback http is always\n                           allowed).\n  --no-allow-insecure-issuer\n                           Force allowInsecureIssuer=false for this\n                           call, overriding the stored value if any.\n                           Mutually exclusive with\n                           --allow-insecure-issuer.\n  -h, --help               Show this help.\n\nBehavior:\n  - If no tokens are stored, prints a note and exits 0 (logout is\n    idempotent).\n  - If the stored blob is unreadable (corrupt or from an\n    unsupported schema version), the local entry is cleared without\n    attempting server-side revocation, and a warning is printed.\n  - Otherwise: discovers the revocation endpoint at the stored\n    issuer, POSTs the stored refresh token per RFC 7009, then\n    clears the local keychain entry. Revocation failures or a\n    missing revocation endpoint are warned about; the local clear\n    still runs.\n\nExit codes:\n  0  Tokens cleared (server-side revocation may have failed; see\n     stderr for warnings).\n  2  Local clear failure.";
+export declare const HELP_LOGOUT = "axe-auth logout\n\nRevoke the stored refresh token server-side (best-effort) and clear\nthe local OS keychain entry.\n\nUsage:\n  axe-auth logout\n\n  Operates exclusively on the keychain entry written by\n  `axe-auth login`. The --server / --allow-insecure-issuer /\n  --no-allow-insecure-issuer flags are accepted for parity with\n  other commands but ignored; revocation uses the issuer, client,\n  and insecure-issuer policy persisted alongside the tokens at login.\n\nOptions:\n  --server <url>           axe server URL. Used by `login` to fetch\n                           /api/sso-config and derive the OAuth\n                           coordinates. Falls back to AXE_SERVER_URL,\n                           then to https://axe.deque.com (SaaS prod).\n  --allow-insecure-issuer  Permit non-loopback http URLs (default is\n                           https only; loopback http is always\n                           allowed). Applies to `login` only;\n                           `token` and `logout` use the policy\n                           persisted at login.\n  --no-allow-insecure-issuer\n                           Force allowInsecureIssuer=false for the new\n                           `login` (and the entry it persists).\n                           Ignored by `token` and `logout`.\n                           Mutually exclusive with\n                           --allow-insecure-issuer.\n  -h, --help               Show this help.\n\nBehavior:\n  - If no tokens are stored, prints a note and exits 0 (logout is\n    idempotent).\n  - If the stored blob is unreadable (corrupt or from an\n    unsupported schema version), the local entry is cleared without\n    attempting server-side revocation, and a warning is printed.\n  - Otherwise: discovers the revocation endpoint at the stored\n    issuer, POSTs the stored refresh token per RFC 7009, then\n    clears the local keychain entry. Revocation failures or a\n    missing revocation endpoint are warned about; the local clear\n    still runs.\n\nExit codes:\n  0  Tokens cleared (server-side revocation may have failed; see\n     stderr for warnings).\n  2  Local clear failure.";

package/dist/commands/logout.help.js

@@ -11,10 +11,11 @@ the local OS keychain entry.
 Usage:
   axe-auth logout
 
-  --server / --realm / --client-id flags are accepted for
-  parity with \`login\` but are ignored: the stored entry's issuer
-  and client identify what to revoke. Mismatched flags produce a
-  warning on stderr.
+  Operates exclusively on the keychain entry written by
+  \`axe-auth login\`. The --server / --allow-insecure-issuer /
+  --no-allow-insecure-issuer flags are accepted for parity with
+  other commands but ignored; revocation uses the issuer, client,
+  and insecure-issuer policy persisted alongside the tokens at login.
 
 Options:
 ${commonArgs_help_1.HELP_COMMON_OPTIONS}

package/dist/commands/logout.js

@@ -1,6 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-const ts_dedent_1 = require("ts-dedent");
 const discoverOIDC_1 = require("../oauth/discoverOIDC");
 const revokeToken_1 = require("../oauth/revokeToken");
 const tokenStore_1 = require("../oauth/tokenStore");
@@ -13,7 +12,7 @@ const logoutCommand = {
     helpText: logout_help_1.HELP_LOGOUT,
     options: {},
     requiresConfig: false,
-    async run(args, deps) {
+    async run(_args, deps) {
         const discoverFn = deps.discoverOIDC ?? discoverOIDC_1.discoverOIDC;
         const revokeFn = deps.revokeRefreshToken ?? revokeToken_1.revokeRefreshToken;
         const tokenStore = deps.tokenStore ?? new tokenStore_1.KeyringTokenStore();
@@ -34,20 +33,7 @@ const logoutCommand = {
             deps.stdout.write("✓ Logged out.\n");
             return;
         }
-        // Use the stored entry's metadata for revocation, not args. Under
-        // single-entry keying there's only one set of credentials in the
-        // keychain; trying to revoke A's refresh token at B's revocation
-        // endpoint (because the user passed --server B) would just fail
-        // and leave A's token valid server-side.
         const { issuerURL, clientId, allowInsecureIssuer } = loaded.entry;
-        if (issuerURL !== args.issuerURL ||
-            clientId !== args.clientId ||
-            allowInsecureIssuer !== args.allowInsecureIssuer) {
-            deps.stderr.write((0, ts_dedent_1.dedent) `
-          axe-auth: ignoring --server / --realm / --client-id / --allow-insecure-issuer flags.
-          Logging out of stored issuer ${issuerURL} (client ${clientId}) instead.
-        ` + "\n");
-        }
         // Best-effort server-side revocation. Any failure here is a
         // warning; the local clear runs unconditionally below so the
         // user is "logged out" from this machine regardless.

package/dist/commands/token.d.ts

@@ -6,12 +6,7 @@ import type { CommandDeps } from "../cli/types";
 export interface TokenDeps extends CommandDeps {
     /** Override `getValidAccessToken` so tests don't touch the keychain or network. */
     getToken?: typeof getValidAccessToken;
-    /**
-     * Override the token store. Defaults to a fresh
-     * `KeyringTokenStore()`. Used to detect when caller-supplied flags
-     * mismatch the stored entry's issuer/client so the warning fires
-     * with the same store instance the eventual `getToken` call sees.
-     */
+    /** Override the token store. Defaults to a fresh `KeyringTokenStore()`. */
     tokenStore?: TokenStore;
 }
 /** `axe-auth token` — print a currently-valid access token to stdout. */
@@ -21,6 +16,6 @@ declare const tokenCommand: {
     helpText: string;
     options: {};
     requiresConfig: false;
-    run(args: CommonArgs, deps: TokenDeps): Promise<void>;
+    run(_args: CommonArgs, deps: TokenDeps): Promise<void>;
 };
 export default tokenCommand;

package/dist/commands/token.help.d.ts

@@ -1,2 +1,2 @@
 /** Help text for `axe-auth token --help`. */
-export declare const HELP_TOKEN = "axe-auth token\n\nPrint a currently-valid OAuth access token to stdout, refreshing\nsilently against the stored refresh token if needed.\n\nUsage:\n  axe-auth token\n\n  --server / --realm / --client-id flags are accepted for parity\n  with other commands but are not used to select a different\n  configuration for refresh. The stored entry's issuer and client\n  are always used; if the supplied values differ from what login\n  persisted, they are ignored and a warning is emitted.\n\nOptions:\n  --server <url>           Authorization-server base URL.\n                           Falls back to AXE_OAUTH_SERVER.\n  --realm <name>           Keycloak realm name.\n                           Falls back to AXE_OAUTH_REALM.\n  --client-id <id>         OAuth client ID.\n                           Falls back to AXE_OAUTH_CLIENT_ID.\n  --allow-insecure-issuer  Permit non-loopback http issuers (default\n                           is https only; loopback http is always\n                           allowed).\n  --no-allow-insecure-issuer\n                           Force allowInsecureIssuer=false for this\n                           call, overriding the stored value if any.\n                           Mutually exclusive with\n                           --allow-insecure-issuer.\n  -h, --help               Show this help.\n\nOutput:\n  The access token is written to stdout with a trailing newline so\n  shell substitution (`$(axe-auth token)`) works cleanly. Nothing\n  else is written to stdout.\n\nSecurity note:\n  Using `$(axe-auth token)` in a shell command exposes the access\n  token briefly in the system process-list (observable via `ps` on\n  POSIX, Task Manager on Windows). OAuth access tokens are\n  short-lived (typically minutes), which limits this exposure\n  compared to a static API key, but you should prefer streaming the\n  token into a file or env var on platforms where process listings\n  are sensitive.\n\nExit codes:\n  0  Success; the token was printed.\n  1  Not authenticated; run `axe-auth login` to re-authenticate.\n  2  Configuration error or transient failure (network, server,\n     keychain).";
+export declare const HELP_TOKEN = "axe-auth token\n\nPrint a currently-valid OAuth access token to stdout, refreshing\nsilently against the stored refresh token if needed.\n\nUsage:\n  axe-auth token\n\n  Operates exclusively on the keychain entry written by\n  `axe-auth login`. The --server / --allow-insecure-issuer /\n  --no-allow-insecure-issuer flags are accepted for parity with\n  other commands but ignored here; refresh uses the issuer, client,\n  and insecure-issuer policy persisted alongside the tokens at login.\n\nOptions:\n  --server <url>           axe server URL. Used by `login` to fetch\n                           /api/sso-config and derive the OAuth\n                           coordinates. Falls back to AXE_SERVER_URL,\n                           then to https://axe.deque.com (SaaS prod).\n  --allow-insecure-issuer  Permit non-loopback http URLs (default is\n                           https only; loopback http is always\n                           allowed). Applies to `login` only;\n                           `token` and `logout` use the policy\n                           persisted at login.\n  --no-allow-insecure-issuer\n                           Force allowInsecureIssuer=false for the new\n                           `login` (and the entry it persists).\n                           Ignored by `token` and `logout`.\n                           Mutually exclusive with\n                           --allow-insecure-issuer.\n  -h, --help               Show this help.\n\nOutput:\n  The access token is written to stdout with a trailing newline so\n  shell substitution (`$(axe-auth token)`) works cleanly. Nothing\n  else is written to stdout.\n\nSecurity note:\n  Using `$(axe-auth token)` in a shell command exposes the access\n  token briefly in the system process-list (observable via `ps` on\n  POSIX, Task Manager on Windows). OAuth access tokens are\n  short-lived (typically minutes), which limits this exposure\n  compared to a static API key, but you should prefer streaming the\n  token into a file or env var on platforms where process listings\n  are sensitive.\n\nExit codes:\n  0  Success; the token was printed.\n  1  Not authenticated; run `axe-auth login` to re-authenticate.\n  2  Configuration error or transient failure (network, server,\n     keychain).";

package/dist/commands/token.help.js

@@ -11,11 +11,11 @@ silently against the stored refresh token if needed.
 Usage:
   axe-auth token
 
-  --server / --realm / --client-id flags are accepted for parity
-  with other commands but are not used to select a different
-  configuration for refresh. The stored entry's issuer and client
-  are always used; if the supplied values differ from what login
-  persisted, they are ignored and a warning is emitted.
+  Operates exclusively on the keychain entry written by
+  \`axe-auth login\`. The --server / --allow-insecure-issuer /
+  --no-allow-insecure-issuer flags are accepted for parity with
+  other commands but ignored here; refresh uses the issuer, client,
+  and insecure-issuer policy persisted alongside the tokens at login.
 
 Options:
 ${commonArgs_help_1.HELP_COMMON_OPTIONS}

package/dist/commands/token.js

@@ -12,34 +12,22 @@ const tokenCommand = {
     helpText: token_help_1.HELP_TOKEN,
     options: {},
     requiresConfig: false,
-    async run(args, deps) {
+    async run(_args, deps) {
         const getToken = deps.getToken ?? getValidAccessToken_1.getValidAccessToken;
         const tokenStore = deps.tokenStore ?? new tokenStore_1.KeyringTokenStore();
-        // Prefer the entry the dispatcher already loaded; only fall back
-        // to a fresh read when there isn't one (test path).
+        // Stored entry is the only source of truth: single-entry-per-machine
+        // model, the blob carries the issuer/client coordinates the tokens
+        // were minted against, and there is no longer a flag to override
+        // them with.
         const loaded = deps.loadedEntry ?? (await tokenStore.load());
-        // The stored entry is the source of truth for issuer/client
-        // (single-entry-per-machine model). Refreshing tokens against a
-        // different issuer than the one they were minted at would just
-        // get them rejected, so args.* are advisory at most: we warn on
-        // mismatch and route the refresh to the stored coordinates.
-        let target = args;
-        if (loaded.ok) {
-            if (loaded.entry.issuerURL !== args.issuerURL ||
-                loaded.entry.clientId !== args.clientId ||
-                loaded.entry.allowInsecureIssuer !== args.allowInsecureIssuer) {
-                deps.stderr.write(`axe-auth: ignoring --server / --realm / --client-id / --allow-insecure-issuer flags; using stored issuer ${loaded.entry.issuerURL} (client ${loaded.entry.clientId}).\n`);
-            }
-            target = {
-                issuerURL: loaded.entry.issuerURL,
-                clientId: loaded.entry.clientId,
-                allowInsecureIssuer: loaded.entry.allowInsecureIssuer,
-            };
-        }
         let token;
         try {
             token = await getToken({
-                ...target,
+                issuerURL: loaded.ok ? loaded.entry.issuerURL : "",
+                clientId: loaded.ok ? loaded.entry.clientId : "",
+                allowInsecureIssuer: loaded.ok
+                    ? loaded.entry.allowInsecureIssuer
+                    : false,
                 tokenStore,
                 loadedEntry: loaded,
             });

package/dist/index.js

@@ -7,7 +7,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const node_util_1 = require("node:util");
-const ts_dedent_1 = require("ts-dedent");
 const commonArgs_1 = require("./cli/commonArgs");
 const tokenStore_1 = require("./oauth/tokenStore");
 const login_1 = __importDefault(require("./commands/login"));
@@ -83,64 +82,37 @@ async function dispatch(argv) {
         process.stdout.write(`${command.helpText}\n`);
         return 0;
     }
-    // Best-effort load of the stored config — but only when at least
-    // one common field is unspecified. The dispatcher's fallback is
-    // all-or-nothing (parseCommonArgs ignores defaults if any flag/env
-    // is set), so a fully-flagged invocation gains nothing from a
-    // keychain hit on the hot path.
-    //
-    // The load failure isn't fatal on its own — if the user passed
-    // flags/env, the stored config doesn't matter — but if
-    // `parseCommonArgs` then throws `MissingConfigError`, we surface
-    // this failure alongside it so the user understands the keychain
-    // (not just missing flags) is the proximate cause.
+    // Best-effort load of the stored entry. Used to (a) supply the
+    // `allowInsecureIssuer` fallback on flag-free invocations, and (b)
+    // hand the entry to the verb via `deps.loadedEntry` so a single
+    // `axe-auth token` invocation hits the keychain once instead of
+    // twice. A read failure here is non-fatal — `parseCommonArgs`
+    // always succeeds (the SaaS prod default fills any unsupplied
+    // walnut URL), and verbs that need a stored entry have their own
+    // empty/corrupt-entry handling.
     let defaults = null;
-    let defaultLoadError = null;
     let loadedEntry;
-    const commonValues = parsed.values;
-    const allFlagsPresent = Boolean(commonValues.server && commonValues.realm && commonValues["client-id"]);
-    if (!allFlagsPresent) {
-        try {
-            loadedEntry = await new tokenStore_1.KeyringTokenStore().load();
-            if (loadedEntry.ok) {
-                defaults = {
-                    issuerURL: loadedEntry.entry.issuerURL,
-                    clientId: loadedEntry.entry.clientId,
-                    allowInsecureIssuer: loadedEntry.entry.allowInsecureIssuer,
-                };
-            }
-        }
-        catch (err) {
-            defaultLoadError = err;
+    try {
+        loadedEntry = await new tokenStore_1.KeyringTokenStore().load();
+        if (loadedEntry.ok) {
+            defaults = {
+                walnutURL: loadedEntry.entry.walnutURL,
+                allowInsecureIssuer: loadedEntry.entry.allowInsecureIssuer,
+            };
         }
     }
+    catch {
+        // Keychain unavailable: leave defaults null. login will fail at
+        // `tokenStore.save()` with a clearer error than we can produce
+        // here; token / logout's own empty-entry path handles it.
+    }
     let common;
     try {
-        common = (0, commonArgs_1.parseCommonArgs)(commonValues, process.env, defaults);
+        common = (0, commonArgs_1.parseCommonArgs)(parsed.values, process.env, defaults);
     }
     catch (err) {
-        if (err instanceof errors_1.MissingConfigError && !command.requiresConfig) {
-            // The verb operates on the stored entry alone (token,
-            // logout). It has its own handling for the empty / corrupt /
-            // version-mismatch cases, which is friendlier than the
-            // generic "missing required configuration" error
-            // (`No stored credentials. Run \`axe-auth login\` first.` for
-            // token; `Already logged out.` for logout). Pass a
-            // sentinel-empty CommonArgs so the verb runs and decides.
-            common = { issuerURL: "", clientId: "", allowInsecureIssuer: false };
-        }
-        else if (err instanceof errors_1.MissingConfigError && defaultLoadError !== null) {
-            process.stderr.write((0, ts_dedent_1.dedent) `
-        ${err.message}
-        Could not read the stored credentials from the keychain (${(0, errors_1.describeError)(defaultLoadError)});
-        pass the flags explicitly or fix the keychain.
-      ` + "\n");
-            return 2;
-        }
-        else {
-            process.stderr.write(`${(0, errors_1.describeError)(err)}\n`);
-            return 2;
-        }
+        process.stderr.write(`${(0, errors_1.describeError)(err)}\n`);
+        return 2;
     }
     const deps = {
         stdin: process.stdin,

package/dist/oauth/authorize.d.ts

@@ -11,6 +11,13 @@ export interface AuthorizeOptions {
     issuerURL: string;
     /** OAuth client ID registered with the authorization server. */
     clientId: string;
+    /**
+     * Originating walnut (axe server) URL the user supplied (or the
+     * SaaS prod default) at login. Persisted in the stored entry
+     * alongside the OAuth coordinates so future verbs can re-discover
+     * `/api/sso-config` without user-supplied flags.
+     */
+    walnutURL: string;
     /**
      * OAuth scopes to request. Required — this library has no opinion
      * about which scopes your provider expects. Keycloak callers who

package/dist/oauth/authorize.js

@@ -38,7 +38,7 @@ function defaultOnWarning(message) {
  * @throws {OAuthCallbackError} For loopback/callback-server failures.
  */
 async function authorize(options) {
-    const { issuerURL, clientId, scopes, timeoutMs, signal, tokenStore = new tokenStore_1.KeyringTokenStore(), openBrowser = openBrowser_1.openBrowser, onAuthorizationUrl = defaultOnAuthorizationUrl, onWarning = defaultOnWarning, allowInsecureIssuer, } = options;
+    const { issuerURL, clientId, walnutURL, scopes, timeoutMs, signal, tokenStore = new tokenStore_1.KeyringTokenStore(), openBrowser = openBrowser_1.openBrowser, onAuthorizationUrl = defaultOnAuthorizationUrl, onWarning = defaultOnWarning, allowInsecureIssuer, } = options;
     // Discovery first. If the auth server is unreachable we want to fail
     // *before* opening a browser — a rejected discovery throw is
     // strictly more useful than a browser tab pointing at a
@@ -109,6 +109,7 @@ async function authorize(options) {
             issuerURL,
             clientId,
             allowInsecureIssuer: allowInsecureIssuer ?? false,
+            walnutURL,
         });
         return tokens;
     }

package/dist/oauth/discoverOIDC.js

@@ -4,6 +4,7 @@ exports.discoverOIDC = discoverOIDC;
 const errors_1 = require("./errors");
 const issuerURL_1 = require("./issuerURL");
 const predicates_1 = require("./predicates");
+const userAgent_1 = require("../userAgent");
 const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
 function optionalString(v) {
     return (0, predicates_1.isNonEmptyString)(v) ? v : undefined;
@@ -69,6 +70,31 @@ function parseConfiguration(body, url) {
         endSessionEndpoint: optionalString(body.end_session_endpoint),
     };
 }
+/**
+ * `code_challenge_methods_supported` is OPTIONAL in OIDC discovery, so its
+ * absence proves nothing — older providers may support PKCE without
+ * advertising it. But when the list IS present and does not include
+ * `S256` (the only method this CLI uses, per RFC 7636), the server has
+ * explicitly declared it does not support the flow we need. Fail fast
+ * with an actionable message instead of letting the user hit a generic
+ * OAuth error several steps deeper into the flow.
+ *
+ * An empty list (`[]`) is treated the same as a populated list missing
+ * `S256`: the server has explicitly advertised zero supported methods,
+ * which is incompatible.
+ *
+ * Called from `discoverOIDC` after issuer verification so that a
+ * tampered discovery doc surfaces the more security-critical issuer
+ * mismatch first.
+ */
+function assertPKCESupport(body, url) {
+    const methods = body.code_challenge_methods_supported;
+    if (!Array.isArray(methods))
+        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.`);
+}
 /**
  * Fetches and parses the OpenID Connect discovery document for a given
  * issuer. Fails fast (no retry) so the caller does not open a browser
@@ -98,7 +124,10 @@ async function discoverOIDC(issuerURL, options = {}) {
     const url = buildDiscoveryURL(issuerURL);
     let response;
     try {
-        response = await fetch(url, { signal: options.signal });
+        response = await fetch(url, {
+            headers: { "User-Agent": userAgent_1.USER_AGENT },
+            signal: options.signal,
+        });
     }
     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 });
@@ -139,5 +168,6 @@ async function discoverOIDC(issuerURL, options = {}) {
     if (config.endSessionEndpoint) {
         assertSecureURL(config.endSessionEndpoint, "end_session_endpoint", allowInsecure);
     }
+    assertPKCESupport(body, url);
     return config;
 }

package/dist/oauth/discoverSSOConfig.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Subset of the axe server's `/api/sso-config` response that this
+ * package consumes. The full response may carry additional fields
+ * (e.g. `publicClientId` for the SPA frontend); we ignore everything
+ * except what the CLI needs to drive its OAuth flow.
+ */
+export interface SSOConfig {
+    /** Keycloak base URL, e.g. `https://auth.example.com`. */
+    url: string;
+    /** Keycloak realm name. */
+    realm: string;
+    /** OAuth client ID for the axe-auth CLI. */
+    mcpClientId: string;
+}
+/** Options for `discoverSSOConfig`. */
+export interface DiscoverSSOConfigOptions {
+    /** Aborts the underlying fetch when fired. */
+    signal?: AbortSignal;
+    /**
+     * Permit non-HTTPS axe server URLs whose host is not a loopback
+     * literal. Loopback hosts (`localhost`, `127.0.0.1`, `[::1]`) are
+     * always allowed over http; this flag is the opt-in for non-loopback
+     * http (corporate dev / reverse-proxy setups). Default `false`.
+     */
+    allowInsecure?: boolean;
+}
+/**
+ * Fetches and parses the axe server's `/api/sso-config` discovery
+ * endpoint. Used by `axe-auth login` to derive the OAuth issuer URL,
+ * realm, and CLI-specific client ID from the axe server URL the user
+ * supplied (or the SaaS prod default), so users no longer have to know
+ * the underlying Keycloak coordinates.
+ *
+ * Distinguishes three failure shapes for the operator-relevant cases:
+ *
+ * - `mcpClientId` field absent: the axe server deployment predates the
+ *   field entirely. Surfaces as "needs upgrading".
+ * - `mcpClientId` is `null`: the axe server version supports the field
+ *   but the operator has not configured `KEYCLOAK_MCP_PUBLIC_CLIENT_ID`.
+ *   Surfaces as "ask the operator to configure".
+ * - any non-empty string: returned as-is.
+ *
+ * Other failure modes (unreachable, non-2xx, malformed JSON, missing
+ * `url` / `realm`) all map to `DISCOVERY_FAILED` with a descriptive
+ * message. The caller is expected to surface these errors verbatim.
+ */
+export declare function discoverSSOConfig(serverURL: string, options?: DiscoverSSOConfigOptions): Promise<SSOConfig>;

package/dist/oauth/discoverSSOConfig.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.discoverSSOConfig = discoverSSOConfig;
+const errors_1 = require("./errors");
+const predicates_1 = require("./predicates");
+const userAgent_1 = require("../userAgent");
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+function assertSecureServerURL(serverURL, allowInsecure) {
+    let parsed;
+    try {
+        parsed = new URL(serverURL);
+    }
+    catch {
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `axe server URL is not a valid URL: ${serverURL}`);
+    }
+    if (parsed.protocol === "https:")
+        return parsed;
+    if (parsed.protocol === "http:") {
+        const hostname = parsed.host.toLowerCase().replace(/:\d+$/, "");
+        if (LOOPBACK_HOSTS.has(hostname))
+            return parsed;
+        if (allowInsecure)
+            return parsed;
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `Refusing to use axe server URL over http:// against non-loopback host ${parsed.host}. Use https:// or pass --allow-insecure-issuer to override (only do this on trusted networks).`);
+    }
+    throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `Unsupported axe server URL scheme '${parsed.protocol}'; expected https: or http: (loopback only).`);
+}
+function buildSSOConfigURL(parsed) {
+    const copy = new URL(parsed.toString());
+    copy.search = "";
+    copy.hash = "";
+    copy.pathname = `${copy.pathname.replace(/\/+$/, "")}/api/sso-config`;
+    return copy.toString();
+}
+/**
+ * Fetches and parses the axe server's `/api/sso-config` discovery
+ * endpoint. Used by `axe-auth login` to derive the OAuth issuer URL,
+ * realm, and CLI-specific client ID from the axe server URL the user
+ * supplied (or the SaaS prod default), so users no longer have to know
+ * the underlying Keycloak coordinates.
+ *
+ * Distinguishes three failure shapes for the operator-relevant cases:
+ *
+ * - `mcpClientId` field absent: the axe server deployment predates the
+ *   field entirely. Surfaces as "needs upgrading".
+ * - `mcpClientId` is `null`: the axe server version supports the field
+ *   but the operator has not configured `KEYCLOAK_MCP_PUBLIC_CLIENT_ID`.
+ *   Surfaces as "ask the operator to configure".
+ * - any non-empty string: returned as-is.
+ *
+ * Other failure modes (unreachable, non-2xx, malformed JSON, missing
+ * `url` / `realm`) all map to `DISCOVERY_FAILED` with a descriptive
+ * message. The caller is expected to surface these errors verbatim.
+ */
+async function discoverSSOConfig(serverURL, options = {}) {
+    const allowInsecure = options.allowInsecure ?? false;
+    const parsed = assertSecureServerURL(serverURL, allowInsecure);
+    const url = buildSSOConfigURL(parsed);
+    let response;
+    try {
+        response = await fetch(url, {
+            headers: { "User-Agent": userAgent_1.USER_AGENT },
+            signal: options.signal,
+        });
+    }
+    catch (cause) {
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `Could not reach the axe server at ${url}. Check the --server URL and your network connection.`, { cause });
+    }
+    if (!response.ok) {
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `axe server at ${url} responded with HTTP ${response.status}. Check the --server URL.`);
+    }
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch (cause) {
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `axe server at ${url} did not return valid JSON.`, { cause });
+    }
+    if (body === null || typeof body !== "object" || Array.isArray(body)) {
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `axe server at ${url} returned a non-object response body.`);
+    }
+    const raw = body;
+    const missing = [];
+    if (!(0, predicates_1.isNonEmptyString)(raw.url))
+        missing.push("url");
+    if (!(0, predicates_1.isNonEmptyString)(raw.realm))
+        missing.push("realm");
+    if (missing.length > 0) {
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `${url} is missing required field(s): ${missing.join(", ")}`);
+    }
+    if (!("mcpClientId" in raw)) {
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `axe server at ${serverURL} does not advertise OAuth-based MCP authentication. The deployment may need to be upgraded to a version that supports the axe-auth CLI.`);
+    }
+    if (raw.mcpClientId === null) {
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `axe server at ${serverURL} has not been configured for OAuth-based MCP authentication. Ask your operator to set the KEYCLOAK_MCP_PUBLIC_CLIENT_ID environment variable on the axe server.`);
+    }
+    if (!(0, predicates_1.isNonEmptyString)(raw.mcpClientId)) {
+        throw new errors_1.OAuthFlowError("DISCOVERY_FAILED", `axe server at ${serverURL} returned a malformed mcpClientId (expected a non-empty string).`);
+    }
+    return {
+        url: raw.url,
+        realm: raw.realm,
+        mcpClientId: raw.mcpClientId,
+    };
+}

package/dist/oauth/getValidAccessToken.js

@@ -130,6 +130,7 @@ async function getValidAccessToken(options) {
             issuerURL: loaded.entry.issuerURL,
             clientId: loaded.entry.clientId,
             allowInsecureIssuer: loaded.entry.allowInsecureIssuer,
+            walnutURL: loaded.entry.walnutURL,
         });
     }
     catch (err) {