@deque/axe-auth 1.1.0-next.6fbca4dd → 1.1.0-next.71013e07

package/README.md

@@ -32,21 +32,17 @@ Run `axe-auth <command> --help` for command-specific options.
 
 ### Common configuration
 
-`axe-auth login` accepts the Keycloak coordinates as flags or environment variables (flag wins over env):
+`axe-auth` discovers its OAuth coordinates by calling `<server>/api/sso-config` on the axe server. Users only supply (or default to) the axe server URL — never the underlying Keycloak URL, realm, or client ID.
 
-| Flag                         | Env var               | Notes                                                                                                                            |
-| ---------------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `--server`                   | `AXE_OAUTH_SERVER`    | Authorization-server base URL.                                                                                                   |
-| `--realm`                    | `AXE_OAUTH_REALM`     | Keycloak realm.                                                                                                                  |
-| `--client-id`                | `AXE_OAUTH_CLIENT_ID` | OAuth client ID registered with Keycloak.                                                                                        |
-| `--allow-insecure-issuer`    | —                     | Permit non-loopback http issuers (default is https only; loopback http is always allowed).                                       |
-| `--no-allow-insecure-issuer` | —                     | Force `allowInsecureIssuer=false` for this call, overriding the stored value. Mutually exclusive with `--allow-insecure-issuer`. |
+| Flag                         | Env var          | Notes                                                                                                                                                                                                            |
+| ---------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--server`                   | `AXE_SERVER_URL` | axe server URL. Defaults to `https://axe.deque.com` (SaaS prod) when neither flag nor env var is set, so SaaS users pass no flags at all. Customers on other deployments override with their own axe server URL. |
+| `--allow-insecure-issuer`    | —                | Permit non-loopback http URLs (default is https only; loopback http is always allowed). Applies to `login` only; `token` and `logout` use the policy persisted at login.                                         |
+| `--no-allow-insecure-issuer` | —                | Force `allowInsecureIssuer=false` for the new `login` (and the entry it persists). Mutually exclusive with `--allow-insecure-issuer`. `token` and `logout` ignore this flag.                                     |
 
-The issuer URL is built as `${server}/realms/${realm}`.
+`axe-auth` stores one set of credentials per machine. On a successful `login`, the discovered issuer / client / insecure-issuer values are persisted alongside the tokens, so subsequent `axe-auth token` and `axe-auth logout` invocations work flag-free — a typical scripted call is just `$(axe-auth token)`.
 
-`axe-auth` stores one set of credentials per machine. On a successful `login`, the resolved issuer / client / insecure-issuer values are persisted alongside the tokens, so subsequent `axe-auth token` and `axe-auth logout` invocations work flag-free — a typical scripted call is just `$(axe-auth token)`. The same flags accepted by `login` work on the other verbs too, but `logout` always operates on the stored entry (mismatched flags trigger a warning on stderr and are ignored).
-
-There is no concurrent multi-issuer support. Logging in to a second Keycloak overwrites the previous tokens; an interactive prompt confirms the switch before destroying the existing session, and `--force` skips the prompt.
+There is no concurrent multi-issuer support. Logging in to a second deployment overwrites the previous tokens; an interactive prompt confirms the switch before destroying the existing session, and `--force` skips the prompt.
 
 ### Exit codes
 
@@ -60,11 +56,11 @@ There is no concurrent multi-issuer support. Logging in to a second Keycloak ove
 ### Examples
 
 ```sh
-# First-time login (opens your browser)
-axe-auth login \
-  --server https://auth.customer.dequecloud.com \
-  --realm customer \
-  --client-id axe-auth
+# First-time login on Deque SaaS prod (opens your browser, no flags needed)
+axe-auth login
+
+# First-time login on a non-SaaS-prod deployment
+axe-auth login --server https://axe.customer.dequecloud.com
 
 # Pull a fresh access token for use in shell substitution
 docker run -e AXE_ACCESS_TOKEN="$(axe-auth token)" axe-mcp-server

package/credits.json

@@ -27,6 +27,17 @@
     "publisher": "Stephen Mathieson",
     "email": "me@stephenmathieson.com"
   },
+  "shlex@3.0.0": {
+    "name": "shlex",
+    "version": "3.0.0",
+    "licenses": "MIT",
+    "path": "/home/runner/work/axe-mcp-server/axe-mcp-server/node_modules/.pnpm/shlex@3.0.0/node_modules/shlex",
+    "licenseText": "MIT License\n\nCopyright (c) 2018 Ryan Govostes\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n",
+    "licenseFile": "/home/runner/work/axe-mcp-server/axe-mcp-server/node_modules/.pnpm/shlex@3.0.0/node_modules/shlex/LICENSE",
+    "repository": "https://github.com/rgov/node-shlex",
+    "publisher": "Ryan Govostes",
+    "copyright": "Copyright (c) 2018 Ryan Govostes"
+  },
   "ts-dedent@2.2.0": {
     "name": "ts-dedent",
     "version": "2.2.0",
@@ -39,4 +50,4 @@
     "email": "dev@zaku.eu",
     "copyright": "Copyright (c) 2018 Tamino Martinius"
   }
-}
+}

package/dist/cli/commonArgs.d.ts

@@ -1,66 +1,35 @@
 import type { ParseArgsConfig } from "node:util";
-/**
- * The subset of a `StoredEntry` that `parseCommonArgs` accepts as a
- * fallback when no flags or env vars supply the common fields.
- * Sourced from `KeyringTokenStore.load()` by the dispatcher.
- */
-export interface StoredConfig {
-    issuerURL: string;
-    clientId: string;
-    allowInsecureIssuer: boolean;
-}
-/** Common configuration the three CLI verbs share. */
+/** Default axe server URL for Deque SaaS prod. */
+export declare const DEFAULT_WALNUT_URL = "https://axe.deque.com";
+/** Common configuration the CLI verbs share. */
 export interface CommonArgs {
-    /** OIDC issuer URL, built as `${server}/realms/${realm}`. */
-    issuerURL: string;
-    /** OAuth client ID. */
-    clientId: string;
-    /**
-     * Whether to permit non-loopback http issuers. Loopback hosts
-     * (`localhost` / `127.0.0.1` / `[::1]`) are always allowed over
-     * http; this flag is the opt-in for non-loopback http issuers.
-     */
+    /** axe server URL (walnut). */
+    walnutURL: string;
+    /** Whether non-loopback http walnut/issuer URLs are permitted. */
     allowInsecureIssuer: boolean;
 }
 /**
- * `parseArgs`-shaped options describing the flags every CLI verb
- * accepts (server / realm / client-id / allow-insecure-issuer and
- * its negation). Subcommands spread this into their own `options` so
- * they can add verb-specific flags alongside.
- *
- * Node's `parseArgs` doesn't support `--no-` boolean negation
- * natively, so the opt-out is registered as its own flag. Passing
- * both `--allow-insecure-issuer` and `--no-allow-insecure-issuer` is
- * treated as user error and rejected; `--no-allow-insecure-issuer`
- * is the only way to force `allowInsecureIssuer: false` for a single
- * invocation when the stored entry has it set to `true`.
+ * `parseArgs`-shaped options shared by every CLI verb. `parseArgs`
+ * doesn't support `--no-` boolean negation natively, so the opt-out
+ * is registered as its own flag and `parseCommonArgs` rejects passing
+ * both together.
  */
 export declare const COMMON_OPTIONS: NonNullable<ParseArgsConfig["options"]>;
 /** Subset of `parseArgs(...).values` this helper consumes. */
 export interface ParsedCommonValues {
     server?: string;
-    realm?: string;
-    "client-id"?: string;
     "allow-insecure-issuer"?: boolean;
     "no-allow-insecure-issuer"?: boolean;
 }
+/** Stored fallback for `allowInsecureIssuer` + the `walnutURL` it was minted against. */
+export interface StoredCommonDefaults {
+    walnutURL: string;
+    allowInsecureIssuer: boolean;
+}
 /**
- * Resolves the common Keycloak coordinates from already-parsed CLI
- * flag values, falling back to `AXE_OAUTH_SERVER`,
- * `AXE_OAUTH_REALM`, and `AXE_OAUTH_CLIENT_ID` env vars when a flag
- * is absent, then to a `StoredConfig` from the keychain when none
- * of those are set at all. Flag wins over env wins over stored.
- *
- * The keychain fallback is all-or-nothing: it kicks in only when no
- * flag and no env var supplies any common field. Mixed input (e.g.
- * `--server X` without `--realm`) is treated as deliberate override,
- * so the missing-field error fires instead of silently filling gaps
- * from an unrelated stored issuer.
- *
- * @param values   The `values` object returned from `parseArgs`.
- * @param env      Environment to consult for fallback. Defaults to
- *   `process.env`; injected for test determinism.
- * @param defaults Stored issuer/client config. Pass `null` (or
- *   omit) when nothing is stored.
+ * Resolves common configuration from parsed flag values, falling
+ * back to `AXE_SERVER_URL` and finally to `DEFAULT_WALNUT_URL`.
+ * `allowInsecureIssuer` falls back to `defaults` only when the
+ * resolved walnut URL matches `defaults.walnutURL`.
  */
-export declare function parseCommonArgs(values: ParsedCommonValues, env?: NodeJS.ProcessEnv, defaults?: StoredConfig | null): CommonArgs;
+export declare function parseCommonArgs(values: ParsedCommonValues, env?: NodeJS.ProcessEnv, defaults?: StoredCommonDefaults | null): CommonArgs;

package/dist/cli/commonArgs.help.d.ts

@@ -1,2 +1,2 @@
 /** Help-text fragment describing the flags every CLI verb shares. */
-export declare const HELP_COMMON_OPTIONS = "  --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.";
+export declare const HELP_COMMON_OPTIONS = "  --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.";

package/dist/cli/commonArgs.help.js

@@ -2,18 +2,19 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HELP_COMMON_OPTIONS = void 0;
 /** Help-text fragment describing the flags every CLI verb shares. */
-exports.HELP_COMMON_OPTIONS = `  --server <url>           Authorization-server base URL.
-                           Falls back to AXE_OAUTH_SERVER.
-  --realm <name>           Keycloak realm name.
-                           Falls back to AXE_OAUTH_REALM.
-  --client-id <id>         OAuth client ID.
-                           Falls back to AXE_OAUTH_CLIENT_ID.
-  --allow-insecure-issuer  Permit non-loopback http issuers (default
-                           is https only; loopback http is always
-                           allowed).
+exports.HELP_COMMON_OPTIONS = `  --server <url>           axe server URL. Used by \`login\` to fetch
+                           /api/sso-config and derive the OAuth
+                           coordinates. Falls back to AXE_SERVER_URL,
+                           then to https://axe.deque.com (SaaS prod).
+  --allow-insecure-issuer  Permit non-loopback http URLs (default is
+                           https only; loopback http is always
+                           allowed). Applies to \`login\` only;
+                           \`token\` and \`logout\` use the policy
+                           persisted at login.
   --no-allow-insecure-issuer
-                           Force allowInsecureIssuer=false for this
-                           call, overriding the stored value if any.
+                           Force allowInsecureIssuer=false for the new
+                           \`login\` (and the entry it persists).
+                           Ignored by \`token\` and \`logout\`.
                            Mutually exclusive with
                            --allow-insecure-issuer.
   -h, --help               Show this help.`;

package/dist/cli/commonArgs.js

@@ -3,94 +3,38 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.COMMON_OPTIONS = void 0;
+exports.COMMON_OPTIONS = exports.DEFAULT_WALNUT_URL = void 0;
 exports.parseCommonArgs = parseCommonArgs;
 const remove_trailing_slash_1 = __importDefault(require("remove-trailing-slash"));
-const strict_1 = __importDefault(require("node:assert/strict"));
-const errors_1 = require("./errors");
+/** Default axe server URL for Deque SaaS prod. */
+exports.DEFAULT_WALNUT_URL = "https://axe.deque.com";
 /**
- * `parseArgs`-shaped options describing the flags every CLI verb
- * accepts (server / realm / client-id / allow-insecure-issuer and
- * its negation). Subcommands spread this into their own `options` so
- * they can add verb-specific flags alongside.
- *
- * Node's `parseArgs` doesn't support `--no-` boolean negation
- * natively, so the opt-out is registered as its own flag. Passing
- * both `--allow-insecure-issuer` and `--no-allow-insecure-issuer` is
- * treated as user error and rejected; `--no-allow-insecure-issuer`
- * is the only way to force `allowInsecureIssuer: false` for a single
- * invocation when the stored entry has it set to `true`.
+ * `parseArgs`-shaped options shared by every CLI verb. `parseArgs`
+ * doesn't support `--no-` boolean negation natively, so the opt-out
+ * is registered as its own flag and `parseCommonArgs` rejects passing
+ * both together.
  */
 exports.COMMON_OPTIONS = {
     server: { type: "string" },
-    realm: { type: "string" },
-    "client-id": { type: "string" },
     "allow-insecure-issuer": { type: "boolean" },
     "no-allow-insecure-issuer": { type: "boolean" },
 };
 /**
- * Resolves the common Keycloak coordinates from already-parsed CLI
- * flag values, falling back to `AXE_OAUTH_SERVER`,
- * `AXE_OAUTH_REALM`, and `AXE_OAUTH_CLIENT_ID` env vars when a flag
- * is absent, then to a `StoredConfig` from the keychain when none
- * of those are set at all. Flag wins over env wins over stored.
- *
- * The keychain fallback is all-or-nothing: it kicks in only when no
- * flag and no env var supplies any common field. Mixed input (e.g.
- * `--server X` without `--realm`) is treated as deliberate override,
- * so the missing-field error fires instead of silently filling gaps
- * from an unrelated stored issuer.
- *
- * @param values   The `values` object returned from `parseArgs`.
- * @param env      Environment to consult for fallback. Defaults to
- *   `process.env`; injected for test determinism.
- * @param defaults Stored issuer/client config. Pass `null` (or
- *   omit) when nothing is stored.
+ * Resolves common configuration from parsed flag values, falling
+ * back to `AXE_SERVER_URL` and finally to `DEFAULT_WALNUT_URL`.
+ * `allowInsecureIssuer` falls back to `defaults` only when the
+ * resolved walnut URL matches `defaults.walnutURL`.
  */
 function parseCommonArgs(values, env = process.env, defaults = null) {
-    const server = values.server ?? env.AXE_OAUTH_SERVER;
-    const realm = values.realm ?? env.AXE_OAUTH_REALM;
-    const clientId = values["client-id"] ?? env.AXE_OAUTH_CLIENT_ID;
-    const allowInsecureIssuer = resolveAllowInsecureIssuer(values, defaults);
-    // All-or-nothing fallback to the keychain default. Any flag or env
-    // input opts out, so partial overrides still surface the
-    // missing-field error rather than mixing flags with stored config.
-    // The `--allow-insecure-issuer` / `--no-allow-insecure-issuer`
-    // pair does NOT count toward this check: it modifies the security
-    // posture of the call without identifying a different issuer, so
-    // it should compose with the stored issuer/client fallback.
-    const noFlagOrEnv = !server && !realm && !clientId;
-    if (noFlagOrEnv && defaults) {
-        return {
-            issuerURL: defaults.issuerURL,
-            clientId: defaults.clientId,
-            allowInsecureIssuer,
-        };
-    }
-    const missing = [];
-    if (!server)
-        missing.push("--server (or AXE_OAUTH_SERVER)");
-    if (!realm)
-        missing.push("--realm (or AXE_OAUTH_REALM)");
-    if (!clientId)
-        missing.push("--client-id (or AXE_OAUTH_CLIENT_ID)");
-    if (missing.length > 0) {
-        throw new errors_1.MissingConfigError(missing);
-    }
-    // The `missing.length` check above already threw when any of these
-    // were absent. The `assert` calls narrow `server` / `realm` /
-    // `clientId` from `string | undefined` to `string` for the return
-    // expression, replacing the non-null `!` shortcut with a runtime
-    // check that gives a real error if the invariant is ever broken.
-    (0, strict_1.default)(server);
-    (0, strict_1.default)(realm);
-    (0, strict_1.default)(clientId);
-    const serverBase = (0, remove_trailing_slash_1.default)(server);
-    return {
-        issuerURL: `${serverBase}/realms/${realm}`,
-        clientId,
-        allowInsecureIssuer,
-    };
+    const walnutURL = (0, remove_trailing_slash_1.default)(values.server ?? env.AXE_SERVER_URL ?? exports.DEFAULT_WALNUT_URL);
+    // Only inherit the stored `allowInsecureIssuer` when the incoming
+    // walnut URL matches the stored one. A user logging in to a
+    // different deployment must opt back in via `--allow-insecure-issuer`
+    // explicitly; otherwise a dev-time HTTP-allow setting would silently
+    // carry over to a prod login.
+    const matchingDefaults = defaults && defaults.walnutURL === walnutURL ? defaults : null;
+    const allowInsecureIssuer = resolveAllowInsecureIssuer(values, matchingDefaults);
+    return { walnutURL, allowInsecureIssuer };
 }
 /**
  * Resolves `allowInsecureIssuer` from the positive flag, its

package/dist/cli/confirm.js

@@ -9,9 +9,6 @@ const node_readline_1 = require("node:readline");
  * default action stays conservative.
  */
 async function confirm(options) {
-    // Annotate after the ?? fallbacks so the union of `Writable |
-    // NodeJS.WriteStream` (from `process.stderr`) collapses to the
-    // base class — otherwise `output.write(...)` is ambiguous.
     const input = options.input ?? process.stdin;
     const output = options.output ?? process.stderr;
     const question = options.question.endsWith(" ")

package/dist/cli/errors.d.ts

@@ -2,29 +2,12 @@
 export type CLIErrorCode = "NOT_AUTHENTICATED" | "USER_CANCELLED" | "ALREADY_AUTHENTICATED" | "OAUTH_FAILED" | "KEYCHAIN_FAILURE";
 /**
  * Thrown from a verb's `run` to signal a known failure. The
- * dispatcher in `src/index.ts` writes `message` to stderr and exits
- * with `exitCode`. The `code` field is the load-bearing
- * discriminator; `exitCode` is derived for shell scripts and is
- * documented in the README.
+ * dispatcher writes `message` to stderr and exits with `exitCode`.
  */
 export declare class CLIError extends Error {
     readonly code: CLIErrorCode;
     readonly exitCode: number;
     constructor(code: CLIErrorCode, message: string);
 }
-/**
- * Thrown by `parseCommonArgs` when one or more of `server`, `realm`,
- * or `clientId` cannot be resolved from flags, env vars, or the
- * keychain default. Carries `missing` so the dispatcher can pair the
- * list with extra context (e.g. a keychain-load failure).
- */
-export declare class MissingConfigError extends Error {
-    readonly missing: readonly string[];
-    constructor(missing: readonly string[]);
-}
-/**
- * Returns the `message` of an `Error`-shaped value, or its `String`
- * coercion otherwise. Used in user-facing error templates so
- * callers don't inline the `instanceof` ternary every time.
- */
+/** Returns the `message` of an `Error`, or its `String` coercion otherwise. */
 export declare function describeError(err: unknown): string;

package/dist/cli/errors.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MissingConfigError = exports.CLIError = void 0;
+exports.CLIError = void 0;
 exports.describeError = describeError;
 const EXIT_CODE_BY_ERROR_CODE = {
     NOT_AUTHENTICATED: 1,
@@ -11,10 +11,7 @@ const EXIT_CODE_BY_ERROR_CODE = {
 };
 /**
  * Thrown from a verb's `run` to signal a known failure. The
- * dispatcher in `src/index.ts` writes `message` to stderr and exits
- * with `exitCode`. The `code` field is the load-bearing
- * discriminator; `exitCode` is derived for shell scripts and is
- * documented in the README.
+ * dispatcher writes `message` to stderr and exits with `exitCode`.
  */
 class CLIError extends Error {
     code;
@@ -27,26 +24,7 @@ class CLIError extends Error {
     }
 }
 exports.CLIError = CLIError;
-/**
- * Thrown by `parseCommonArgs` when one or more of `server`, `realm`,
- * or `clientId` cannot be resolved from flags, env vars, or the
- * keychain default. Carries `missing` so the dispatcher can pair the
- * list with extra context (e.g. a keychain-load failure).
- */
-class MissingConfigError extends Error {
-    missing;
-    constructor(missing) {
-        super(`Missing required configuration: ${missing.join(", ")}.`);
-        this.name = "MissingConfigError";
-        this.missing = missing;
-    }
-}
-exports.MissingConfigError = MissingConfigError;
-/**
- * Returns the `message` of an `Error`-shaped value, or its `String`
- * coercion otherwise. Used in user-facing error templates so
- * callers don't inline the `instanceof` ternary every time.
- */
+/** Returns the `message` of an `Error`, or its `String` coercion otherwise. */
 function describeError(err) {
     return err instanceof Error ? err.message : String(err);
 }

package/dist/cli/testUtils.js

@@ -71,9 +71,10 @@ function makeStore(initial) {
 function entry(tokens, overrides = {}) {
     return {
         tokens,
-        issuerURL: "https://auth.example.com/realms/prod",
+        issuerURL: "https://auth.example.com/auth/realms/prod",
         clientId: "axe-auth",
         allowInsecureIssuer: false,
+        walnutURL: "https://axe.example.com",
         ...overrides,
     };
 }
@@ -92,8 +93,7 @@ function captureDeps(overrides = {}) {
  */
 function commonArgs(overrides = {}) {
     return {
-        issuerURL: "https://auth.example.com/realms/prod",
-        clientId: "axe-auth",
+        walnutURL: "https://axe.example.com",
         allowInsecureIssuer: false,
         ...overrides,
     };

package/dist/cli/types.d.ts

@@ -4,48 +4,22 @@ import type { LoadResult } from "../oauth/tokenStore";
 import type { CommonArgs } from "./commonArgs";
 /** Mapping passed to `parseArgs` for verb-specific flags. */
 export type VerbOptions = NonNullable<ParseArgsConfig["options"]>;
-/**
- * The injectables every CLI verb sees. The dispatcher fills these in
- * with the real `process.*` streams; tests pass synthetic values.
- * Verb-specific overrides (e.g. `getToken`, `authorize`) extend this
- * interface in the relevant verb's module — TS allows the dispatcher
- * to pass a plain `CommandDeps` because the verb-specific extras are
- * declared optional.
- */
+/** Injectables every CLI verb sees. Dispatcher fills with `process.*`; tests pass synthetic values. */
 export interface CommandDeps {
-    /**
-     * Standard input. Carries an optional `isTTY` so verbs like
-     * `login` can branch on interactivity. Real `process.stdin`
-     * satisfies the shape; test fixtures using `Readable.from([])`
-     * leave `isTTY` undefined, which coerces to `false`.
-     */
+    /** `isTTY` is optional so `Readable.from([])` test fixtures coerce to non-TTY. */
     stdin: Readable & {
         isTTY?: boolean;
     };
     stdout: Writable;
     stderr: Writable;
     /**
-     * Pre-loaded result of `KeyringTokenStore.load()`, populated by the
-     * dispatcher when it ran the keychain read to derive the
-     * `parseCommonArgs` fallback. Verbs prefer this over loading
-     * again so a single `axe-auth token` invocation hits the keychain
-     * once instead of three times. Tests typically leave this
-     * undefined and inject a fake `tokenStore` instead.
+     * Pre-loaded result of `KeyringTokenStore.load()` from the
+     * dispatcher's keychain read, so a single CLI invocation hits the
+     * keychain once instead of N times.
      */
     loadedEntry?: LoadResult;
 }
-/**
- * Specification of a single CLI verb. The dispatcher in
- * `src/index.ts` consumes one of these per registered command:
- * parses argv, resolves common args, prints `helpText` for `--help`,
- * runs `run`, and translates thrown `CLIError`s (see `./errors`)
- * into exit codes.
- *
- * Each verb narrows the `run` parameters to its own
- * `CommonArgs & <Verb>Flags` and `<Verb>Deps`. Method-shorthand
- * bivariance lets that narrower signature satisfy this interface
- * without casts at the verb definition.
- */
+/** Specification of a single CLI verb consumed by the dispatcher. */
 export interface CommandSpec {
     /** Verb name, e.g. `"login"`. */
     readonly name: string;
@@ -53,30 +27,13 @@ export interface CommandSpec {
     readonly summary: string;
     /** Full help text printed for `axe-auth <verb> --help`. */
     readonly helpText: string;
-    /**
-     * Verb-specific `parseArgs` options. Common options
-     * (`--server` / `--realm` / `--client-id` / `--allow-insecure-issuer`)
-     * are added by the dispatcher; do not duplicate them here.
-     */
+    /** Verb-specific `parseArgs` options; common options are added by the dispatcher. */
     readonly options: VerbOptions;
-    /**
-     * `true` if this verb cannot run without resolved
-     * `--server` / `--realm` / `--client-id` (login). `false` for
-     * verbs that operate on the stored entry alone (token, logout)
-     * and have their own "not authenticated" / "already logged out"
-     * handling for the empty-entry case.
-     *
-     * When `false` and `parseCommonArgs` throws `MissingConfigError`,
-     * the dispatcher passes a sentinel-empty `CommonArgs` to `run()`
-     * instead of erroring, so the verb's own empty/corrupt-entry
-     * branch fires.
-     */
+    /** `true` if this verb cannot run without a usable walnut URL (login). */
     readonly requiresConfig: boolean;
     /**
-     * Run the verb with already-resolved args and the dispatcher's
-     * deps. Throw a `CLIError` to signal a known failure with an
-     * explicit exit code; throw any other error for a generic exit
-     * code 2 plus the error message on stderr.
+     * Throw `CLIError` for a known failure with an explicit exit code;
+     * any other error becomes exit code 2 with the message on stderr.
      */
     run(args: CommonArgs, deps: CommandDeps): Promise<void>;
 }

package/dist/commands/login.d.ts

@@ -1,4 +1,5 @@
 import { authorize } from "../oauth/authorize";
+import { discoverSSOConfig } from "../oauth/discoverSSOConfig";
 import { type TokenStore } from "../oauth/tokenStore";
 import type { CommonArgs } from "../cli/commonArgs";
 import type { CommandDeps } from "../cli/types";
@@ -8,16 +9,15 @@ export interface LoginDeps extends CommandDeps {
     isInteractive?: boolean;
     /** Override `authorize` (for tests). */
     authorize?: typeof authorize;
+    /** Override the SSO discovery helper (for tests). */
+    discoverSSOConfig?: typeof discoverSSOConfig;
     /**
      * Override the token store. Defaults to a fresh
      * `KeyringTokenStore()`. The same instance is passed to `authorize`
      * so the pre-check and post-flow save agree on the keychain entry.
      */
     tokenStore?: TokenStore;
-    /**
-     * Override the confirmation prompt (for tests). Receives the
-     * issuer URL and returns whether the user wants to proceed.
-     */
+    /** Override the confirmation prompt (for tests). */
     confirm?: (prompt: string) => Promise<boolean>;
 }
 /** Verb-specific flags for `axe-auth login`. */

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

@@ -1,2 +1,2 @@
 /** Help text for `axe-auth login --help`. */
-export declare const HELP_LOGIN = "axe-auth login\n\nOpen a browser, complete the OAuth 2.0 Authorization Code + PKCE\nflow against your Keycloak realm, and persist the resulting tokens\nto the OS keychain.\n\nUsage:\n  axe-auth login --server <url> --realm <name> --client-id <id> [--force]\n\n  After a first successful login, --server / --realm / --client-id\n  can be omitted; the previously stored values are reused.\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  --force                  Re-authenticate without prompting even if\n                           a valid token is already stored.\n\nBehavior when already authenticated:\n  axe-auth stores one entry per machine. If a valid entry already\n  exists, an interactive session prompts for confirmation before\n  overwriting it \u2014 even when the new login targets a different\n  issuer or client (logging in to B destroys A's tokens). Pass\n  --force to skip the prompt. In a non-interactive session (no TTY)\n  --force is required; otherwise the command refuses to overwrite\n  stored tokens and exits non-zero.\n\nExit codes:\n  0  Success; tokens persisted to the keychain.\n  2  Configuration error or flow failure.\n  3  Login cancelled at the prompt.";
+export declare const HELP_LOGIN = "axe-auth login\n\nOpen a browser, complete the OAuth 2.0 Authorization Code + PKCE\nflow against the customer's Keycloak realm, and persist the\nresulting tokens to the OS keychain.\n\nThe CLI discovers the OAuth coordinates by calling\n`<server>/api/sso-config` on the axe server, so users only need to\nsupply (or default to) the axe server URL \u2014 never the underlying\nKeycloak URL, realm, or client ID directly.\n\nUsage:\n  axe-auth login [--server <url>] [--force]\n\n  With no flags, the SaaS prod axe server URL (https://axe.deque.com)\n  is used. Customers on other deployments pass --server (or set\n  AXE_SERVER_URL).\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  --force                  Re-authenticate without prompting even if\n                           a valid token is already stored.\n\nBehavior when already authenticated:\n  axe-auth stores one entry per machine. If a valid entry already\n  exists, an interactive session prompts for confirmation before\n  overwriting it \u2014 even when the new login targets a different\n  issuer or client (logging in to B destroys A's tokens). Pass\n  --force to skip the prompt. In a non-interactive session (no TTY)\n  --force is required; otherwise the command refuses to overwrite\n  stored tokens and exits non-zero.\n\nExit codes:\n  0  Success; tokens persisted to the keychain.\n  2  Configuration error or flow failure.\n  3  Login cancelled at the prompt.";

package/dist/commands/login.help.js

@@ -6,14 +6,20 @@ const commonArgs_help_1 = require("../cli/commonArgs.help");
 exports.HELP_LOGIN = `axe-auth login
 
 Open a browser, complete the OAuth 2.0 Authorization Code + PKCE
-flow against your Keycloak realm, and persist the resulting tokens
-to the OS keychain.
+flow against the customer's Keycloak realm, and persist the
+resulting tokens to the OS keychain.
+
+The CLI discovers the OAuth coordinates by calling
+\`<server>/api/sso-config\` on the axe server, so users only need to
+supply (or default to) the axe server URL — never the underlying
+Keycloak URL, realm, or client ID directly.
 
 Usage:
-  axe-auth login --server <url> --realm <name> --client-id <id> [--force]
+  axe-auth login [--server <url>] [--force]
 
-  After a first successful login, --server / --realm / --client-id
-  can be omitted; the previously stored values are reused.
+  With no flags, the SaaS prod axe server URL (https://axe.deque.com)
+  is used. Customers on other deployments pass --server (or set
+  AXE_SERVER_URL).
 
 Options:
 ${commonArgs_help_1.HELP_COMMON_OPTIONS}