@deque/axe-auth 1.1.0-next.fb07beab → 1.1.0-next.fea0aa8a

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,53 @@
+{
+  "@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"
+  },
+  "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",
+    "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,35 @@
+import type { ParseArgsConfig } from "node:util";
+/** 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 {
+    /** axe server URL (walnut). */
+    walnutURL: string;
+    /** Whether non-loopback http walnut/issuer URLs are permitted. */
+    allowInsecureIssuer: boolean;
+}
+/**
+ * `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;
+    "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 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?: 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,63 @@
+"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 Deque SaaS prod. */
+exports.DEFAULT_WALNUT_URL = "https://axe.deque.com";
+/**
+ * `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" },
+    "allow-insecure-issuer": { type: "boolean" },
+    "no-allow-insecure-issuer": { type: "boolean" },
+};
+/**
+ * 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 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,53 @@
+"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) {
+    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,13 @@
+/** 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 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);
+}
+/** Returns the `message` of an `Error`, or its `String` coercion otherwise. */
+export declare function describeError(err: unknown): string;

package/dist/cli/errors.js

@@ -0,0 +1,30 @@
+"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 writes `message` to stderr and exits with `exitCode`.
+ */
+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`, or its `String` coercion otherwise. */
+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,
+    };
+}

package/dist/cli/types.d.ts

@@ -0,0 +1,39 @@
+import type { Readable, Writable } from "node:stream";
+import type { ParseArgsConfig } from "node:util";
+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"]>;
+/** Injectables every CLI verb sees. Dispatcher fills with `process.*`; tests pass synthetic values. */
+export interface CommandDeps {
+    /** `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()` 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 consumed by the dispatcher. */
+export interface CommandSpec {
+    /** Verb name, e.g. `"login"`. */
+    readonly name: string;
+    /** One-liner shown in the top-level `axe-auth --help` listing. */
+    readonly summary: string;
+    /** Full help text printed for `axe-auth <verb> --help`. */
+    readonly helpText: string;
+    /** Verb-specific `parseArgs` options; common options are added by the dispatcher. */
+    readonly options: VerbOptions;
+    /** `true` if this verb cannot run without a usable walnut URL (login). */
+    readonly requiresConfig: boolean;
+    /**
+     * 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/cli/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/commands/login.d.ts

@@ -0,0 +1,41 @@
+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";
+/** Verb-specific deps for `axe-auth login`. */
+export interface LoginDeps extends CommandDeps {
+    /** Whether to treat the session as interactive. Defaults to `stdin.isTTY`. */
+    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). */
+    confirm?: (prompt: string) => Promise<boolean>;
+}
+/** Verb-specific flags for `axe-auth login`. */
+export interface LoginFlags {
+    /** Set by `--force`. Skip the "already authenticated" prompt. */
+    force?: boolean;
+}
+/** `axe-auth login` — drive the OAuth flow and persist tokens. */
+declare const loginCommand: {
+    name: string;
+    summary: string;
+    helpText: string;
+    options: {
+        force: {
+            type: "boolean";
+        };
+    };
+    requiresConfig: true;
+    run(args: CommonArgs & LoginFlags, deps: LoginDeps): Promise<void>;
+};
+export default loginCommand;

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

@@ -0,0 +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 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.";