@deque/axe-auth 1.1.0-next.97bcb8e6 → 1.1.0-next.f082f98a

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,12 +17,73 @@ 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.  |
+
+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):
+
+| 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`. |
+
+The issuer URL is built as `${server}/realms/${realm}`.
+
+`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.
+
+### 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 (opens your browser)
+axe-auth login \
+  --server https://auth.customer.dequecloud.com \
+  --realm customer \
+  --client-id axe-auth
+
+# 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
+
+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
+
+- **`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/dist/cli/commonArgs.d.ts

@@ -0,0 +1,66 @@
+import type { ParseArgsConfig } from "node:util";
+/**
+ * The subset of a `StoredEntry` that `parseCommonArgs` accepts as a
+ * fallback when no flags or env vars supply the common fields.
+ * Sourced from `KeyringTokenStore.load()` by the dispatcher.
+ */
+export interface StoredConfig {
+    issuerURL: string;
+    clientId: string;
+    allowInsecureIssuer: boolean;
+}
+/** Common configuration the three CLI verbs share. */
+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.
+     */
+    allowInsecureIssuer: boolean;
+}
+/**
+ * `parseArgs`-shaped options describing the flags every CLI verb
+ * accepts (server / realm / client-id / allow-insecure-issuer and
+ * its negation). Subcommands spread this into their own `options` so
+ * they can add verb-specific flags alongside.
+ *
+ * Node's `parseArgs` doesn't support `--no-` boolean negation
+ * natively, so the opt-out is registered as its own flag. Passing
+ * both `--allow-insecure-issuer` and `--no-allow-insecure-issuer` is
+ * treated as user error and rejected; `--no-allow-insecure-issuer`
+ * is the only way to force `allowInsecureIssuer: false` for a single
+ * invocation when the stored entry has it set to `true`.
+ */
+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.
+ *
+ * The keychain fallback is all-or-nothing: it kicks in only when no
+ * flag and no env var supplies any common field. Mixed input (e.g.
+ * `--server X` without `--realm`) is treated as deliberate override,
+ * so the missing-field error fires instead of silently filling gaps
+ * from an unrelated stored issuer.
+ *
+ * @param values   The `values` object returned from `parseArgs`.
+ * @param env      Environment to consult for fallback. Defaults to
+ *   `process.env`; injected for test determinism.
+ * @param defaults Stored issuer/client config. Pass `null` (or
+ *   omit) when nothing is stored.
+ */
+export declare function parseCommonArgs(values: ParsedCommonValues, env?: NodeJS.ProcessEnv, defaults?: StoredConfig | 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>           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.";

package/dist/cli/commonArgs.help.js

@@ -0,0 +1,19 @@
+"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>           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).
+  --no-allow-insecure-issuer
+                           Force allowInsecureIssuer=false for this
+                           call, overriding the stored value if any.
+                           Mutually exclusive with
+                           --allow-insecure-issuer.
+  -h, --help               Show this help.`;

package/dist/cli/commonArgs.js

@@ -0,0 +1,119 @@
+"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 = 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");
+/**
+ * `parseArgs`-shaped options describing the flags every CLI verb
+ * accepts (server / realm / client-id / allow-insecure-issuer and
+ * its negation). Subcommands spread this into their own `options` so
+ * they can add verb-specific flags alongside.
+ *
+ * Node's `parseArgs` doesn't support `--no-` boolean negation
+ * natively, so the opt-out is registered as its own flag. Passing
+ * both `--allow-insecure-issuer` and `--no-allow-insecure-issuer` is
+ * treated as user error and rejected; `--no-allow-insecure-issuer`
+ * is the only way to force `allowInsecureIssuer: false` for a single
+ * invocation when the stored entry has it set to `true`.
+ */
+exports.COMMON_OPTIONS = {
+    server: { type: "string" },
+    realm: { type: "string" },
+    "client-id": { type: "string" },
+    "allow-insecure-issuer": { type: "boolean" },
+    "no-allow-insecure-issuer": { type: "boolean" },
+};
+/**
+ * Resolves the common Keycloak coordinates from already-parsed CLI
+ * flag values, falling back to `AXE_OAUTH_SERVER`,
+ * `AXE_OAUTH_REALM`, and `AXE_OAUTH_CLIENT_ID` env vars when a flag
+ * is absent, then to a `StoredConfig` from the keychain when none
+ * of those are set at all. Flag wins over env wins over stored.
+ *
+ * The keychain fallback is all-or-nothing: it kicks in only when no
+ * flag and no env var supplies any common field. Mixed input (e.g.
+ * `--server X` without `--realm`) is treated as deliberate override,
+ * so the missing-field error fires instead of silently filling gaps
+ * from an unrelated stored issuer.
+ *
+ * @param values   The `values` object returned from `parseArgs`.
+ * @param env      Environment to consult for fallback. Defaults to
+ *   `process.env`; injected for test determinism.
+ * @param defaults Stored issuer/client config. Pass `null` (or
+ *   omit) when nothing is stored.
+ */
+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,
+    };
+}
+/**
+ * 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,30 @@
+/** 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);
+}
+/**
+ * Thrown by `parseCommonArgs` when one or more of `server`, `realm`,
+ * or `clientId` cannot be resolved from flags, env vars, or the
+ * keychain default. Carries `missing` so the dispatcher can pair the
+ * list with extra context (e.g. a keychain-load failure).
+ */
+export declare class MissingConfigError extends Error {
+    readonly missing: readonly string[];
+    constructor(missing: readonly string[]);
+}
+/**
+ * Returns the `message` of an `Error`-shaped value, or its `String`
+ * coercion otherwise. Used in user-facing error templates so
+ * callers don't inline the `instanceof` ternary every time.
+ */
+export declare function describeError(err: unknown): string;

package/dist/cli/errors.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MissingConfigError = 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;
+/**
+ * Thrown by `parseCommonArgs` when one or more of `server`, `realm`,
+ * or `clientId` cannot be resolved from flags, env vars, or the
+ * keychain default. Carries `missing` so the dispatcher can pair the
+ * list with extra context (e.g. a keychain-load failure).
+ */
+class MissingConfigError extends Error {
+    missing;
+    constructor(missing) {
+        super(`Missing required configuration: ${missing.join(", ")}.`);
+        this.name = "MissingConfigError";
+        this.missing = missing;
+    }
+}
+exports.MissingConfigError = MissingConfigError;
+/**
+ * Returns the `message` of an `Error`-shaped value, or its `String`
+ * coercion otherwise. Used in user-facing error templates so
+ * callers don't inline the `instanceof` ternary every time.
+ */
+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/realms/prod",
+        clientId: "axe-auth",
+        allowInsecureIssuer: false,
+        ...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 {
+        issuerURL: "https://auth.example.com/realms/prod",
+        clientId: "axe-auth",
+        allowInsecureIssuer: false,
+        ...overrides,
+    };
+}