@deque/axe-auth 1.1.0-next.ac35e028 → 1.1.0-next.cc7aaec1

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
@@ -75,17 +71,15 @@ axe-auth logout
 
 ## Architecture
 
-Design notes live under [`packages/axe-auth/docs/`](https://github.com/dequelabs/axe-mcp-server/tree/develop/packages/axe-auth/docs):
+See [`docs/architecture.md`](./docs/architecture.md) for the system architecture: components, per-verb data flow, communication security, and persisted data.
+
+Deeper design notes:
 
-- [`oauth-flow.md`](https://github.com/dequelabs/axe-mcp-server/blob/develop/packages/axe-auth/docs/oauth-flow.md) — high-level OAuth 2.0 + PKCE flow.
-- [`callback-server.md`](https://github.com/dequelabs/axe-mcp-server/blob/develop/packages/axe-auth/docs/callback-server.md) — `startCallbackServer` API and RFC 8252 conformance.
-- [`callback-page.md`](https://github.com/dequelabs/axe-mcp-server/blob/develop/packages/axe-auth/docs/callback-page.md) — HTML response design, branding, and CSP rationale.
+- [`oauth-flow.md`](./docs/oauth-flow.md) — protocol-level walkthrough of the OAuth 2.0 + PKCE flow.
+- [`callback-server.md`](./docs/callback-server.md) — `startCallbackServer` API and RFC 8252 conformance.
+- [`callback-page.md`](./docs/callback-page.md) — HTML response design, branding, and CSP rationale.
 
 ## Caveats
 
 - **`axe-auth token` exposes the access token in the shell process list and terminal scrollback.** When used as `$(axe-auth token)` the token briefly appears in the parent process's argument list (observable via `ps`); printed directly to a terminal it also persists in the scrollback buffer (iTerm2, Terminal.app, tmux all retain output by default), which can outlast the token's TTL on a shared machine. OAuth access tokens are short-lived (typically minutes), which limits exposure compared to a static API key. Prefer redirecting into a file (`axe-auth token > /tmp/tok && chmod 600 /tmp/tok`) or directly into an env var (`export AXE_ACCESS_TOKEN=$(axe-auth token)`) on platforms where this matters.
-- **Linux keychain support is untested.** `@napi-rs/keyring` requires a working D-Bus Secret Service (GNOME Keyring, KWallet, etc.). Users on headless or minimal-desktop Linux environments may see `KEYRING_UNAVAILABLE`; a file-backed `TokenStore` fallback is tracked as a follow-up ([#464](https://github.com/dequelabs/axe-mcp-server/issues/464)).
-
-## Contributing
-
-Running the OAuth flow end-to-end against a local Keycloak, plus the smoke-test scripts, is documented in [`docs/local-dev.md`](https://github.com/dequelabs/axe-mcp-server/blob/develop/packages/axe-auth/docs/local-dev.md).
+- **Linux keychain support is untested.** `@napi-rs/keyring` requires a working D-Bus Secret Service (GNOME Keyring, KWallet, etc.). Users on headless or minimal-desktop Linux environments may see `KEYRING_UNAVAILABLE`; a file-backed `TokenStore` fallback is tracked as a follow-up (internal issue #464).

package/credits.json

@@ -0,0 +1,42 @@
+{
+  "@napi-rs/keyring@1.2.0": {
+    "name": "@napi-rs/keyring",
+    "version": "1.2.0",
+    "licenses": "MIT",
+    "path": "/home/runner/work/axe-mcp-server/axe-mcp-server/node_modules/.pnpm/@napi-rs+keyring@1.2.0/node_modules/@napi-rs/keyring",
+    "licenseText": "MIT License\n\nCopyright (c) 2020 N-API for Rust\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/@napi-rs+keyring@1.2.0/node_modules/@napi-rs/keyring/LICENSE",
+    "copyright": "Copyright (c) 2020 N-API for Rust"
+  },
+  "@napi-rs/keyring-linux-x64-gnu@1.2.0": {
+    "name": "@napi-rs/keyring-linux-x64-gnu",
+    "version": "1.2.0",
+    "licenses": "MIT",
+    "path": "/home/runner/work/axe-mcp-server/axe-mcp-server/node_modules/.pnpm/@napi-rs+keyring-linux-x64-gnu@1.2.0/node_modules/@napi-rs/keyring-linux-x64-gnu",
+    "licenseText": "# `@napi-rs/keyring-linux-x64-gnu`\n\nThis is the **x86_64-unknown-linux-gnu** binary for `@napi-rs/keyring`\n",
+    "licenseFile": "/home/runner/work/axe-mcp-server/axe-mcp-server/node_modules/.pnpm/@napi-rs+keyring-linux-x64-gnu@1.2.0/node_modules/@napi-rs/keyring-linux-x64-gnu/README.md"
+  },
+  "remove-trailing-slash@0.1.1": {
+    "name": "remove-trailing-slash",
+    "version": "0.1.1",
+    "licenses": "MIT",
+    "path": "/home/runner/work/axe-mcp-server/axe-mcp-server/node_modules/.pnpm/remove-trailing-slash@0.1.1/node_modules/remove-trailing-slash",
+    "licenseText": "# remove-trailing-slash\n\nremoves trailing slashes\n\n## Installation\n\nwith [component(1)](http://component.io):\n\n    $ component install stephenmathieson/remove-trailing-slash\n\nwith [npm](https://npmjs.org/):\n\n    $ npm install remove-trailing-slash\n\n## API\n\n### `removeTrailingSlash(str)`\n\nRemoves trailing slashes from the given `str`\n\n## Example\n\n```js\nvar slashes = require('remove-trailing-slash')\n\nslashes('http://google.com/').should.be.equal('http://google.com');\n```\n\n## License\n\nMIT\n",
+    "licenseFile": "/home/runner/work/axe-mcp-server/axe-mcp-server/node_modules/.pnpm/remove-trailing-slash@0.1.1/node_modules/remove-trailing-slash/readme.md",
+    "repository": "https://github.com/stephenmathieson/remove-trailing-slash",
+    "publisher": "Stephen Mathieson",
+    "email": "me@stephenmathieson.com"
+  },
+  "ts-dedent@2.2.0": {
+    "name": "ts-dedent",
+    "version": "2.2.0",
+    "licenses": "MIT",
+    "path": "/home/runner/work/axe-mcp-server/axe-mcp-server/node_modules/.pnpm/ts-dedent@2.2.0/node_modules/ts-dedent",
+    "licenseText": "MIT License\n\nCopyright (c) 2018 Tamino Martinius\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/ts-dedent@2.2.0/node_modules/ts-dedent/LICENSE",
+    "repository": "https://github.com/tamino-martinius/node-ts-dedent",
+    "publisher": "Tamino Martinius",
+    "email": "dev@zaku.eu",
+    "copyright": "Copyright (c) 2018 Tamino Martinius"
+  }
+}

package/dist/cli/commonArgs.d.ts

@@ -1,66 +1,82 @@
 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.
+ * Default axe server URL for `axe-auth` users on Deque's SaaS prod
+ * deployment. The CLI's `--server` flag (and `AXE_SERVER_URL` env)
+ * override this; non-prod customers must supply their own walnut URL.
  */
-export interface StoredConfig {
-    issuerURL: string;
-    clientId: string;
-    allowInsecureIssuer: boolean;
-}
-/** Common configuration the three CLI verbs share. */
+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). Used by `login` to fetch
+     * `/api/sso-config` and derive the OAuth issuer / realm / client
+     * coordinates. `token` and `logout` operate on the stored entry
+     * alone and ignore this value.
+     */
+    walnutURL: string;
+    /**
+     * Whether to permit non-loopback http walnut/issuer URLs. Loopback
+     * hosts (`localhost` / `127.0.0.1` / `[::1]`) are always allowed
+     * over http; this flag is the opt-in for non-loopback http
+     * deployments.
      */
     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.
+ * accepts (--server, --allow-insecure-issuer, --no-allow-insecure-issuer).
+ * 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`.
+ * treated as user error and rejected.
  */
 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;
 }
 /**
- * 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.
+ * Subset of a stored entry used as a fallback for
+ * `allowInsecureIssuer` when the user passes neither
+ * `--allow-insecure-issuer` nor `--no-allow-insecure-issuer`.
+ * Sourced from `KeyringTokenStore.load()` by the dispatcher.
+ *
+ * `walnutURL` is carried alongside so the fallback only applies when
+ * the user is targeting the same deployment as the stored entry —
+ * otherwise a dev-time HTTP-allow setting would silently carry over
+ * to a prod login.
+ */
+export interface StoredCommonDefaults {
+    walnutURL: string;
+    allowInsecureIssuer: boolean;
+}
+/**
+ * Resolves common configuration from parsed flag values, falling
+ * back to `AXE_SERVER_URL` when `--server` is absent and finally to
+ * the SaaS prod walnut URL when neither is set.
  *
- * 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.
+ * `allowInsecureIssuer` is consumed by `login` (it is forwarded to
+ * SSO discovery and the OAuth flow). The fallback to a stored value
+ * exists so an interactive re-login on a private dev instance does
+ * not need the flag re-passed when the previous login set it. The
+ * fallback is gated on the resolved walnut URL matching the stored
+ * one: a user logging in to a different deployment must opt back in
+ * with `--allow-insecure-issuer` explicitly. The `token` and `logout`
+ * verbs do **not** consume this resolved value — they read
+ * `allowInsecureIssuer` directly from the keychain entry's metadata,
+ * so flag/env input is silently ignored there (and the help text for
+ * those verbs documents that).
  *
  * @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.
+ * @param defaults Stored fallback for `allowInsecureIssuer` plus the
+ *   `walnutURL` it was minted against. Pass `null` (or omit) when
+ *   nothing is stored.
  */
-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,65 @@ 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 `axe-auth` users on Deque's SaaS prod
+ * deployment. The CLI's `--server` flag (and `AXE_SERVER_URL` env)
+ * override this; non-prod customers must supply their own walnut URL.
+ */
+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.
+ * accepts (--server, --allow-insecure-issuer, --no-allow-insecure-issuer).
+ * 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`.
+ * treated as user error and rejected.
  */
 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.
+ * Resolves common configuration from parsed flag values, falling
+ * back to `AXE_SERVER_URL` when `--server` is absent and finally to
+ * the SaaS prod walnut URL when neither is set.
  *
- * 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.
+ * `allowInsecureIssuer` is consumed by `login` (it is forwarded to
+ * SSO discovery and the OAuth flow). The fallback to a stored value
+ * exists so an interactive re-login on a private dev instance does
+ * not need the flag re-passed when the previous login set it. The
+ * fallback is gated on the resolved walnut URL matching the stored
+ * one: a user logging in to a different deployment must opt back in
+ * with `--allow-insecure-issuer` explicitly. The `token` and `logout`
+ * verbs do **not** consume this resolved value — they read
+ * `allowInsecureIssuer` directly from the keychain entry's metadata,
+ * so flag/env input is silently ignored there (and the help text for
+ * those verbs documents that).
  *
  * @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.
+ * @param defaults Stored fallback for `allowInsecureIssuer` plus the
+ *   `walnutURL` it was minted against. Pass `null` (or omit) when
+ *   nothing is stored.
  */
 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/errors.d.ts

@@ -12,16 +12,6 @@ export declare class CLIError extends Error {
     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

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,
@@ -27,21 +27,6 @@ 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

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

@@ -55,21 +55,18 @@ export interface CommandSpec {
     readonly helpText: string;
     /**
      * Verb-specific `parseArgs` options. Common options
-     * (`--server` / `--realm` / `--client-id` / `--allow-insecure-issuer`)
+     * (`--server` / `--allow-insecure-issuer` / `--no-allow-insecure-issuer`)
      * are added by the dispatcher; do not duplicate them here.
      */
     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). `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. With
+     * the SaaS prod default in `parseCommonArgs`, the walnut URL is
+     * never strictly missing, but this flag remains for future
+     * required-config additions.
      */
     readonly requiresConfig: boolean;
     /**

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,6 +9,8 @@ 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`

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}