@deque/axe-auth 1.1.0-next.789db6ed → 1.1.0-next.8e9934f2

package/README.md

@@ -1,6 +1,6 @@
 # @deque/axe-auth
 
-CLI for authenticating with Deque's axe MCP server and other services.
+CLI for authenticating with Deque services via the OAuth 2.0 Authorization Code + PKCE flow (RFC 6749, RFC 7636, RFC 8252 §7.3). Tokens are persisted to the OS keychain so subsequent invocations can refresh silently.
 
 ## Installation
 
@@ -17,22 +17,69 @@ npx @deque/axe-auth
 ## Usage
 
 ```sh
-axe-auth [options]
+axe-auth <command> [options]
 ```
 
-### Options
+Commands:
 
-| Flag              | Description         |
-| ----------------- | ------------------- |
-| `-v`, `--version` | Show version number |
-| `-h`, `--help`    | Show help message   |
+| Command  | Description                                                                     |
+| -------- | ------------------------------------------------------------------------------- |
+| `login`  | Open a browser, complete the OAuth flow, persist tokens to the OS keychain.     |
+| `logout` | Revoke the stored refresh token server-side and clear the local keychain entry. |
+| `token`  | Print a currently-valid access token to stdout, refreshing silently if needed.  |
 
-> Login, token exchange, and keychain storage are owned by sibling issues under epic [#410](https://github.com/dequelabs/axe-mcp-server/issues/410). This package currently ships only the loopback callback server module; see the architecture docs below.
+Run `axe-auth <command> --help` for command-specific options.
+
+### Common configuration
+
+`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_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.                                     |
+
+`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)`.
+
+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
+
+| Code | Meaning                                                                                                                                                                                                                                                              |
+| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `0`  | Success.                                                                                                                                                                                                                                                             |
+| `1`  | Not authenticated: `axe-auth token` with no stored credentials, or stored credentials are unusable (corrupt, version-mismatch, expired without a usable refresh token, or refresh rejected by the server). Branch on this in scripts that need to trigger a `login`. |
+| `2`  | Usage or runtime error: unknown command, bad flag, missing required configuration, OAuth flow failure, or keychain failure. Details written to stderr.                                                                                                               |
+| `3`  | Cancelled: `axe-auth login` declined at the re-authentication prompt. Distinct from `1` so scripts can tell "needs login" from "user bailed."                                                                                                                        |
+
+### Examples
+
+```sh
+# 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
+
+# Sign out
+axe-auth logout
+```
 
 ## Architecture
 
-Design notes live in the repository 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`](./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
 
-- [`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 and where each concern lives.
-- [`callback-server.md`](https://github.com/dequelabs/axe-mcp-server/blob/develop/packages/axe-auth/docs/callback-server.md) — `startCallbackServer` API, error codes, 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.
+- **`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 (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

@@ -0,0 +1,82 @@
+import type { ParseArgsConfig } from "node:util";
+/**
+ * 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 declare const DEFAULT_WALNUT_URL = "https://axe.deque.com";
+/** Common configuration the CLI verbs share. */
+export interface CommonArgs {
+    /**
+     * 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, --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.
+ */
+export declare const COMMON_OPTIONS: NonNullable<ParseArgsConfig["options"]>;
+/** Subset of `parseArgs(...).values` this helper consumes. */
+export interface ParsedCommonValues {
+    server?: string;
+    "allow-insecure-issuer"?: boolean;
+    "no-allow-insecure-issuer"?: boolean;
+}
+/**
+ * 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.
+ *
+ * `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 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?: StoredCommonDefaults | null): CommonArgs;

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

@@ -0,0 +1,2 @@
+/** Help-text fragment describing the flags every CLI verb shares. */
+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

@@ -0,0 +1,20 @@
+"use strict";
+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>           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 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

@@ -0,0 +1,90 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMMON_OPTIONS = exports.DEFAULT_WALNUT_URL = void 0;
+exports.parseCommonArgs = parseCommonArgs;
+const remove_trailing_slash_1 = __importDefault(require("remove-trailing-slash"));
+/**
+ * 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, --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.
+ */
+exports.COMMON_OPTIONS = {
+    server: { type: "string" },
+    "allow-insecure-issuer": { type: "boolean" },
+    "no-allow-insecure-issuer": { type: "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.
+ *
+ * `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 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 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
+ * negation, and the keychain default — in that precedence order.
+ * Throws when both flags are passed together.
+ */
+function resolveAllowInsecureIssuer(values, defaults) {
+    // Truthy checks (rather than `!== undefined`) are deliberate:
+    // `parseArgs` with `type: "boolean"` only ever produces `true` or
+    // `undefined`, but `ParsedCommonValues` types these as
+    // `boolean | undefined` so a programmatic caller could thread in
+    // `false`. Treating `false` as "flag not set" lets such a caller
+    // mix `{ "allow-insecure-issuer": false, "no-allow-insecure-issuer":
+    // true }` without tripping the mutex — `false` here is equivalent
+    // to "absent", which is what parseArgs would have produced anyway.
+    const allow = values["allow-insecure-issuer"];
+    const deny = values["no-allow-insecure-issuer"];
+    if (allow && deny) {
+        throw new Error("--allow-insecure-issuer and --no-allow-insecure-issuer are mutually exclusive.");
+    }
+    if (allow)
+        return true;
+    if (deny)
+        return false;
+    return defaults?.allowInsecureIssuer ?? false;
+}

package/dist/cli/confirm.d.ts

@@ -0,0 +1,17 @@
+import type { Readable, Writable } from "node:stream";
+/** Options for `confirm`. */
+export interface ConfirmOptions {
+    /** Question to display. A trailing space is added if absent. */
+    question: string;
+    /** Stream to read the answer from. Defaults to `process.stdin`. */
+    input?: Readable;
+    /** Stream to print the question on. Defaults to `process.stderr`. */
+    output?: Writable;
+}
+/**
+ * Reads a single line from `input` and returns `true` for an
+ * affirmative answer (`y` / `yes`, case-insensitive), `false`
+ * otherwise. Empty / EOF / Ctrl-C are all treated as "no" so the
+ * default action stays conservative.
+ */
+export declare function confirm(options: ConfirmOptions): Promise<boolean>;

package/dist/cli/confirm.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.confirm = confirm;
+const node_readline_1 = require("node:readline");
+/**
+ * Reads a single line from `input` and returns `true` for an
+ * affirmative answer (`y` / `yes`, case-insensitive), `false`
+ * otherwise. Empty / EOF / Ctrl-C are all treated as "no" so the
+ * 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(" ")
+        ? options.question
+        : `${options.question} `;
+    // Use createInterface rather than the higher-level `rl.question`
+    // promise API because the latter wires up SIGINT handling that
+    // doesn't compose well when this is called from a CLI dispatcher
+    // that owns its own signals.
+    const rl = (0, node_readline_1.createInterface)({ input, output });
+    try {
+        output.write(question);
+        const line = await waitForLineOrClose(rl);
+        if (line === null)
+            return false;
+        const trimmed = line.trim().toLowerCase();
+        return trimmed === "y" || trimmed === "yes";
+    }
+    finally {
+        rl.close();
+    }
+}
+/**
+ * Resolves with the next line emitted by `rl`, or `null` if the
+ * underlying stream closes first (EOF / Ctrl-D / Ctrl-C). Both
+ * listeners detach themselves on the other event so we never hold
+ * references to a closed interface.
+ */
+function waitForLineOrClose(rl) {
+    return new Promise((resolve) => {
+        const onLine = (line) => {
+            rl.off("close", onClose);
+            resolve(line);
+        };
+        const onClose = () => {
+            rl.off("line", onLine);
+            resolve(null);
+        };
+        rl.once("line", onLine);
+        rl.once("close", onClose);
+    });
+}

package/dist/cli/errors.d.ts

@@ -0,0 +1,20 @@
+/** Discriminator for `CLIError`, used by tests and the dispatcher. */
+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.
+ */
+export declare class CLIError extends Error {
+    readonly code: CLIErrorCode;
+    readonly exitCode: number;
+    constructor(code: CLIErrorCode, message: 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.
+ */
+export declare function describeError(err: unknown): string;

package/dist/cli/errors.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLIError = void 0;
+exports.describeError = describeError;
+const EXIT_CODE_BY_ERROR_CODE = {
+    NOT_AUTHENTICATED: 1,
+    USER_CANCELLED: 3,
+    ALREADY_AUTHENTICATED: 2,
+    OAUTH_FAILED: 2,
+    KEYCHAIN_FAILURE: 2,
+};
+/**
+ * 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.
+ */
+class CLIError extends Error {
+    code;
+    exitCode;
+    constructor(code, message) {
+        super(message);
+        this.name = "CLIError";
+        this.code = code;
+        this.exitCode = EXIT_CODE_BY_ERROR_CODE[code];
+    }
+}
+exports.CLIError = CLIError;
+/**
+ * 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.
+ */
+function describeError(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/cli/testUtils.d.ts

@@ -0,0 +1,52 @@
+import { Readable, Writable } from "node:stream";
+import type { CommonArgs } from "./commonArgs";
+import type { CommandDeps } from "./types";
+import type { LoadResult, StoredEntry, TokenStore } from "../oauth/tokenStore";
+import type { TokenSet } from "../oauth/tokenResponse";
+/** A `Writable` that accumulates everything written into a string. */
+export interface CapturedStream extends Writable {
+    /** Concatenation of every chunk written to the stream so far. */
+    readonly value: string;
+}
+/**
+ * Returns a `Writable` that records every write into a string for
+ * assertion. Reads via `.value`. Defined as a real `Writable`
+ * subclass so it can be passed straight into `CommandDeps.stdout` /
+ * `CommandDeps.stderr` without casts.
+ */
+export declare function captureStream(): CapturedStream;
+/** Convenience: an empty `Readable` to stand in for stdin in tests. */
+export declare function emptyStdin(): Readable;
+/** A `TokenStore` plus instrumentation for assertions. */
+export interface FakeStore extends TokenStore {
+    /** Number of times `load()` was called. */
+    readonly loadedTimes: number;
+    /** Number of times `clear()` was called. */
+    readonly clearedTimes: number;
+    /** Current state, observable from tests. */
+    readonly current: LoadResult;
+}
+/**
+ * In-memory `TokenStore` that starts in `initial`, accepts
+ * `save()` / `clear()`, and exposes `loadedTimes` / `clearedTimes`
+ * / `current` for assertions.
+ */
+export declare function makeStore(initial: LoadResult): FakeStore;
+/**
+ * Builds a `StoredEntry` for the standard test issuer/client. Pass a
+ * `TokenSet` (from a per-test fixture) and override the
+ * issuer/client/insecure fields when a test cares about them.
+ */
+export declare function entry(tokens: TokenSet, overrides?: Partial<Omit<StoredEntry, "tokens">>): StoredEntry;
+/** A `CommandDeps` shape with the captured streams exposed. */
+export interface CapturedDeps extends CommandDeps {
+    stdout: CapturedStream;
+    stderr: CapturedStream;
+}
+/** Returns a `CommandDeps` populated with capturing streams. */
+export declare function captureDeps(overrides?: Partial<CapturedDeps>): CapturedDeps;
+/**
+ * Returns a fully-resolved `CommonArgs` for the standard test
+ * issuer/client. Override individual fields as needed.
+ */
+export declare function commonArgs(overrides?: Partial<CommonArgs>): CommonArgs;

package/dist/cli/testUtils.js

@@ -0,0 +1,100 @@
+"use strict";
+// Shared test helpers for the command tests. Excluded from c8
+// coverage in `.c8rc.json` since this is test-only code.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.captureStream = captureStream;
+exports.emptyStdin = emptyStdin;
+exports.makeStore = makeStore;
+exports.entry = entry;
+exports.captureDeps = captureDeps;
+exports.commonArgs = commonArgs;
+const node_stream_1 = require("node:stream");
+/**
+ * Returns a `Writable` that records every write into a string for
+ * assertion. Reads via `.value`. Defined as a real `Writable`
+ * subclass so it can be passed straight into `CommandDeps.stdout` /
+ * `CommandDeps.stderr` without casts.
+ */
+function captureStream() {
+    let value = "";
+    const stream = new node_stream_1.Writable({
+        write(chunk, _encoding, cb) {
+            value +=
+                typeof chunk === "string" ? chunk : Buffer.from(chunk).toString();
+            cb();
+        },
+    });
+    Object.defineProperty(stream, "value", { get: () => value });
+    return stream;
+}
+/** Convenience: an empty `Readable` to stand in for stdin in tests. */
+function emptyStdin() {
+    return node_stream_1.Readable.from([]);
+}
+/**
+ * In-memory `TokenStore` that starts in `initial`, accepts
+ * `save()` / `clear()`, and exposes `loadedTimes` / `clearedTimes`
+ * / `current` for assertions.
+ */
+function makeStore(initial) {
+    let current = initial;
+    let loadedTimes = 0;
+    let clearedTimes = 0;
+    return {
+        save: async (entry) => {
+            current = { ok: true, entry };
+        },
+        load: async () => {
+            loadedTimes++;
+            return current;
+        },
+        clear: async () => {
+            clearedTimes++;
+            current = { ok: false, reason: "empty" };
+        },
+        get loadedTimes() {
+            return loadedTimes;
+        },
+        get clearedTimes() {
+            return clearedTimes;
+        },
+        get current() {
+            return current;
+        },
+    };
+}
+/**
+ * Builds a `StoredEntry` for the standard test issuer/client. Pass a
+ * `TokenSet` (from a per-test fixture) and override the
+ * issuer/client/insecure fields when a test cares about them.
+ */
+function entry(tokens, overrides = {}) {
+    return {
+        tokens,
+        issuerURL: "https://auth.example.com/auth/realms/prod",
+        clientId: "axe-auth",
+        allowInsecureIssuer: false,
+        walnutURL: "https://axe.example.com",
+        ...overrides,
+    };
+}
+/** Returns a `CommandDeps` populated with capturing streams. */
+function captureDeps(overrides = {}) {
+    return {
+        stdin: emptyStdin(),
+        stdout: captureStream(),
+        stderr: captureStream(),
+        ...overrides,
+    };
+}
+/**
+ * Returns a fully-resolved `CommonArgs` for the standard test
+ * issuer/client. Override individual fields as needed.
+ */
+function commonArgs(overrides = {}) {
+    return {
+        walnutURL: "https://axe.example.com",
+        allowInsecureIssuer: false,
+        ...overrides,
+    };
+}