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

package/dist/cli/types.d.ts

@@ -0,0 +1,79 @@
+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"]>;
+/**
+ * The injectables every CLI verb sees. The dispatcher fills these in
+ * with the real `process.*` streams; tests pass synthetic values.
+ * Verb-specific overrides (e.g. `getToken`, `authorize`) extend this
+ * interface in the relevant verb's module — TS allows the dispatcher
+ * to pass a plain `CommandDeps` because the verb-specific extras are
+ * declared optional.
+ */
+export interface CommandDeps {
+    /**
+     * Standard input. Carries an optional `isTTY` so verbs like
+     * `login` can branch on interactivity. Real `process.stdin`
+     * satisfies the shape; test fixtures using `Readable.from([])`
+     * leave `isTTY` undefined, which coerces to `false`.
+     */
+    stdin: Readable & {
+        isTTY?: boolean;
+    };
+    stdout: Writable;
+    stderr: Writable;
+    /**
+     * Pre-loaded result of `KeyringTokenStore.load()`, populated by the
+     * dispatcher when it ran the keychain read to derive the
+     * `parseCommonArgs` fallback. Verbs prefer this over loading
+     * again so a single `axe-auth token` invocation hits the keychain
+     * once instead of three times. Tests typically leave this
+     * undefined and inject a fake `tokenStore` instead.
+     */
+    loadedEntry?: LoadResult;
+}
+/**
+ * Specification of a single CLI verb. The dispatcher in
+ * `src/index.ts` consumes one of these per registered command:
+ * parses argv, resolves common args, prints `helpText` for `--help`,
+ * runs `run`, and translates thrown `CLIError`s (see `./errors`)
+ * into exit codes.
+ *
+ * Each verb narrows the `run` parameters to its own
+ * `CommonArgs & <Verb>Flags` and `<Verb>Deps`. Method-shorthand
+ * bivariance lets that narrower signature satisfy this interface
+ * without casts at the verb definition.
+ */
+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
+     * (`--server` / `--allow-insecure-issuer` / `--no-allow-insecure-issuer`)
+     * are added by the dispatcher; do not duplicate them here.
+     */
+    readonly options: VerbOptions;
+    /**
+     * `true` if this verb cannot run without a usable walnut URL
+     * (login). `false` for verbs that operate on the stored entry
+     * alone (token, logout) and have their own "not authenticated" /
+     * "already logged out" handling for the empty-entry case. With
+     * the SaaS prod default in `parseCommonArgs`, the walnut URL is
+     * never strictly missing, but this flag remains for future
+     * required-config additions.
+     */
+    readonly requiresConfig: boolean;
+    /**
+     * Run the verb with already-resolved args and the dispatcher's
+     * deps. Throw a `CLIError` to signal a known failure with an
+     * explicit exit code; throw any other error for a generic exit
+     * code 2 plus the error message on stderr.
+     */
+    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,44 @@
+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). Receives the
+     * issuer URL and returns whether the user wants to proceed.
+     */
+    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.";

package/dist/commands/login.help.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HELP_LOGIN = void 0;
+const commonArgs_help_1 = require("../cli/commonArgs.help");
+/** Help text for `axe-auth login --help`. */
+exports.HELP_LOGIN = `axe-auth login
+
+Open a browser, complete the OAuth 2.0 Authorization Code + PKCE
+flow against the customer's Keycloak realm, and persist the
+resulting tokens to the OS keychain.
+
+The CLI discovers the OAuth coordinates by calling
+\`<server>/api/sso-config\` on the axe server, so users only need to
+supply (or default to) the axe server URL — never the underlying
+Keycloak URL, realm, or client ID directly.
+
+Usage:
+  axe-auth login [--server <url>] [--force]
+
+  With no flags, the SaaS prod axe server URL (https://axe.deque.com)
+  is used. Customers on other deployments pass --server (or set
+  AXE_SERVER_URL).
+
+Options:
+${commonArgs_help_1.HELP_COMMON_OPTIONS}
+  --force                  Re-authenticate without prompting even if
+                           a valid token is already stored.
+
+Behavior when already authenticated:
+  axe-auth stores one entry per machine. If a valid entry already
+  exists, an interactive session prompts for confirmation before
+  overwriting it — even when the new login targets a different
+  issuer or client (logging in to B destroys A's tokens). Pass
+  --force to skip the prompt. In a non-interactive session (no TTY)
+  --force is required; otherwise the command refuses to overwrite
+  stored tokens and exits non-zero.
+
+Exit codes:
+  0  Success; tokens persisted to the keychain.
+  2  Configuration error or flow failure.
+  3  Login cancelled at the prompt.`;

package/dist/commands/login.js

@@ -0,0 +1,117 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const ts_dedent_1 = require("ts-dedent");
+const remove_trailing_slash_1 = __importDefault(require("remove-trailing-slash"));
+const authorize_1 = require("../oauth/authorize");
+const discoverSSOConfig_1 = require("../oauth/discoverSSOConfig");
+const errors_1 = require("../oauth/errors");
+const tokenStore_1 = require("../oauth/tokenStore");
+const confirm_1 = require("../cli/confirm");
+const login_help_1 = require("./login.help");
+const errors_2 = require("../cli/errors");
+/** `axe-auth login` — drive the OAuth flow and persist tokens. */
+const loginCommand = {
+    name: "login",
+    summary: "Open a browser, complete the OAuth flow, and persist tokens to the OS keychain.",
+    helpText: login_help_1.HELP_LOGIN,
+    options: {
+        force: { type: "boolean" },
+    },
+    requiresConfig: true,
+    async run(args, deps) {
+        const isInteractive = deps.isInteractive ?? Boolean(deps.stdin.isTTY);
+        const authorizeFn = deps.authorize ?? authorize_1.authorize;
+        const discoverFn = deps.discoverSSOConfig ?? discoverSSOConfig_1.discoverSSOConfig;
+        const confirmFn = deps.confirm ??
+            ((prompt) => (0, confirm_1.confirm)({
+                question: prompt,
+                input: deps.stdin,
+                output: deps.stderr,
+            }));
+        const tokenStore = deps.tokenStore ?? new tokenStore_1.KeyringTokenStore();
+        // 1. Ask the axe server where its Keycloak lives and which client to use.
+        //    This is the only step that hits the axe server directly; from here on
+        //    the CLI talks to Keycloak using the discovered coordinates.
+        let ssoConfig;
+        try {
+            ssoConfig = await discoverFn(args.walnutURL, {
+                allowInsecure: args.allowInsecureIssuer,
+            });
+        }
+        catch (err) {
+            if (err instanceof errors_1.OAuthFlowError) {
+                throw new errors_2.CLIError("OAUTH_FAILED", err.message);
+            }
+            throw err;
+        }
+        const issuerURL = `${(0, remove_trailing_slash_1.default)(ssoConfig.url)}/auth/realms/${ssoConfig.realm}`;
+        const clientId = ssoConfig.mcpClientId;
+        // 2. Re-auth confirmation. Same UX as the previous flag-driven
+        //    flow, but the comparison is against the *discovered* issuer
+        //    + client, not user-supplied flags.
+        if (!args.force) {
+            const stored = deps.loadedEntry ?? (await tokenStore.load());
+            if (!stored.ok && stored.reason !== "empty") {
+                // Existing entry is unreadable (corrupt or stored under a
+                // schema we can't migrate). authorize() will overwrite it
+                // either way, but the user deserves a breadcrumb for what
+                // disappeared.
+                deps.stderr.write(`axe-auth: replacing unreadable stored credentials (${stored.reason}).\n`);
+            }
+            if (stored.ok) {
+                const sameIssuer = stored.entry.issuerURL === issuerURL &&
+                    stored.entry.clientId === clientId;
+                if (!isInteractive) {
+                    throw new errors_2.CLIError("ALREADY_AUTHENTICATED", sameIssuer
+                        ? `Already authenticated against ${issuerURL}. Re-run with --force to override.`
+                        : (0, ts_dedent_1.dedent) `
+                  Currently authenticated against ${stored.entry.issuerURL}.
+                  Logging in to ${issuerURL} would replace those tokens.
+                  Re-run with --force to override.
+                `);
+                }
+                const prompt = sameIssuer
+                    ? `Already authenticated against ${issuerURL}. Re-authenticate? [y/N]`
+                    : (0, ts_dedent_1.dedent) `
+              Currently authenticated against ${stored.entry.issuerURL} (client ${stored.entry.clientId}).
+              Logging in to ${issuerURL} (client ${clientId}) will replace those tokens.
+              Continue? [y/N]
+            `;
+                const ok = await confirmFn(prompt);
+                if (!ok) {
+                    throw new errors_2.CLIError("USER_CANCELLED", "Login cancelled.");
+                }
+            }
+        }
+        // 3. Drive the OAuth flow. The originating axe server URL rides along
+        //    so it lands in the StoredEntry and future verbs (re-discovery,
+        //    revoke) can operate without user-supplied flags.
+        try {
+            await authorizeFn({
+                issuerURL,
+                clientId,
+                walnutURL: args.walnutURL,
+                scopes: ["offline_access"],
+                allowInsecureIssuer: args.allowInsecureIssuer,
+                tokenStore,
+                onAuthorizationUrl: (url) => {
+                    deps.stderr.write(`Authorization URL: ${url}\n`);
+                },
+                onWarning: (msg) => {
+                    deps.stderr.write(`axe-auth: ${msg}\n`);
+                },
+            });
+        }
+        catch (err) {
+            if (err instanceof errors_1.OAuthFlowError || err instanceof errors_1.OAuthCallbackError) {
+                throw new errors_2.CLIError("OAUTH_FAILED", err.message);
+            }
+            throw err;
+        }
+        deps.stdout.write("✓ Authenticated.\n");
+    },
+};
+exports.default = loginCommand;

package/dist/commands/logout.d.ts

@@ -0,0 +1,24 @@
+import { discoverOIDC } from "../oauth/discoverOIDC";
+import { revokeRefreshToken } from "../oauth/revokeToken";
+import { type TokenStore } from "../oauth/tokenStore";
+import type { CommonArgs } from "../cli/commonArgs";
+import type { CommandDeps } from "../cli/types";
+/** Verb-specific deps for `axe-auth logout`. */
+export interface LogoutDeps extends CommandDeps {
+    /** Override the token store. Defaults to `KeyringTokenStore()`. */
+    tokenStore?: TokenStore;
+    /** Override OIDC discovery (for tests). */
+    discoverOIDC?: typeof discoverOIDC;
+    /** Override the revocation POST (for tests). */
+    revokeRefreshToken?: typeof revokeRefreshToken;
+}
+/** `axe-auth logout` — best-effort revoke + always clear local. */
+declare const logoutCommand: {
+    name: string;
+    summary: string;
+    helpText: string;
+    options: {};
+    requiresConfig: false;
+    run(_args: CommonArgs, deps: LogoutDeps): Promise<void>;
+};
+export default logoutCommand;

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

@@ -0,0 +1,2 @@
+/** Help text for `axe-auth logout --help`. */
+export declare const HELP_LOGOUT = "axe-auth logout\n\nRevoke the stored refresh token server-side (best-effort) and clear\nthe local OS keychain entry.\n\nUsage:\n  axe-auth logout\n\n  Operates exclusively on the keychain entry written by\n  `axe-auth login`. The --server / --allow-insecure-issuer /\n  --no-allow-insecure-issuer flags are accepted for parity with\n  other commands but ignored; revocation uses the issuer, client,\n  and insecure-issuer policy persisted alongside the tokens at login.\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\nBehavior:\n  - If no tokens are stored, prints a note and exits 0 (logout is\n    idempotent).\n  - If the stored blob is unreadable (corrupt or from an\n    unsupported schema version), the local entry is cleared without\n    attempting server-side revocation, and a warning is printed.\n  - Otherwise: discovers the revocation endpoint at the stored\n    issuer, POSTs the stored refresh token per RFC 7009, then\n    clears the local keychain entry. Revocation failures or a\n    missing revocation endpoint are warned about; the local clear\n    still runs.\n\nExit codes:\n  0  Tokens cleared (server-side revocation may have failed; see\n     stderr for warnings).\n  2  Local clear failure.";

package/dist/commands/logout.help.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HELP_LOGOUT = void 0;
+const commonArgs_help_1 = require("../cli/commonArgs.help");
+/** Help text for `axe-auth logout --help`. */
+exports.HELP_LOGOUT = `axe-auth logout
+
+Revoke the stored refresh token server-side (best-effort) and clear
+the local OS keychain entry.
+
+Usage:
+  axe-auth logout
+
+  Operates exclusively on the keychain entry written by
+  \`axe-auth login\`. The --server / --allow-insecure-issuer /
+  --no-allow-insecure-issuer flags are accepted for parity with
+  other commands but ignored; revocation uses the issuer, client,
+  and insecure-issuer policy persisted alongside the tokens at login.
+
+Options:
+${commonArgs_help_1.HELP_COMMON_OPTIONS}
+
+Behavior:
+  - If no tokens are stored, prints a note and exits 0 (logout is
+    idempotent).
+  - If the stored blob is unreadable (corrupt or from an
+    unsupported schema version), the local entry is cleared without
+    attempting server-side revocation, and a warning is printed.
+  - Otherwise: discovers the revocation endpoint at the stored
+    issuer, POSTs the stored refresh token per RFC 7009, then
+    clears the local keychain entry. Revocation failures or a
+    missing revocation endpoint are warned about; the local clear
+    still runs.
+
+Exit codes:
+  0  Tokens cleared (server-side revocation may have failed; see
+     stderr for warnings).
+  2  Local clear failure.`;

package/dist/commands/logout.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const discoverOIDC_1 = require("../oauth/discoverOIDC");
+const revokeToken_1 = require("../oauth/revokeToken");
+const tokenStore_1 = require("../oauth/tokenStore");
+const logout_help_1 = require("./logout.help");
+const errors_1 = require("../cli/errors");
+/** `axe-auth logout` — best-effort revoke + always clear local. */
+const logoutCommand = {
+    name: "logout",
+    summary: "Revoke the stored refresh token server-side and clear the local keychain entry.",
+    helpText: logout_help_1.HELP_LOGOUT,
+    options: {},
+    requiresConfig: false,
+    async run(_args, deps) {
+        const discoverFn = deps.discoverOIDC ?? discoverOIDC_1.discoverOIDC;
+        const revokeFn = deps.revokeRefreshToken ?? revokeToken_1.revokeRefreshToken;
+        const tokenStore = deps.tokenStore ?? new tokenStore_1.KeyringTokenStore();
+        // Prefer the entry the dispatcher already loaded; only fall back
+        // to a fresh read when there isn't one (test path).
+        const loaded = deps.loadedEntry ?? (await tokenStore.load());
+        if (!loaded.ok) {
+            if (loaded.reason === "empty") {
+                deps.stdout.write("No stored credentials. Already logged out.\n");
+                return;
+            }
+            // Corrupt or version-mismatch: there IS a blob, just unusable.
+            // Server-side revocation isn't possible without a parseable
+            // refresh token, but the local entry must be cleared so the
+            // user actually ends up logged out.
+            deps.stderr.write(`axe-auth: stored credentials are unusable (${loaded.reason}); clearing local entry without server-side revocation.\n`);
+            await clearLocal(tokenStore);
+            deps.stdout.write("✓ Logged out.\n");
+            return;
+        }
+        const { issuerURL, clientId, allowInsecureIssuer } = loaded.entry;
+        // Best-effort server-side revocation. Any failure here is a
+        // warning; the local clear runs unconditionally below so the
+        // user is "logged out" from this machine regardless.
+        if (loaded.entry.tokens.refreshToken) {
+            try {
+                const config = await discoverFn(issuerURL, { allowInsecureIssuer });
+                if (config.revocationEndpoint) {
+                    await revokeFn({
+                        revocationEndpoint: config.revocationEndpoint,
+                        clientId,
+                        refreshToken: loaded.entry.tokens.refreshToken,
+                    });
+                }
+                else {
+                    deps.stderr.write(`axe-auth: authorization server did not advertise a revocation endpoint; refresh token cleared locally only.\n`);
+                }
+            }
+            catch (err) {
+                deps.stderr.write(`axe-auth: server-side revocation failed (${(0, errors_1.describeError)(err)}). Continuing with local clear.\n`);
+            }
+        }
+        await clearLocal(tokenStore);
+        deps.stdout.write("✓ Logged out.\n");
+    },
+};
+async function clearLocal(tokenStore) {
+    try {
+        await tokenStore.clear();
+    }
+    catch (err) {
+        throw new errors_1.CLIError("KEYCHAIN_FAILURE", `Failed to clear stored credentials: ${(0, errors_1.describeError)(err)}`);
+    }
+}
+exports.default = logoutCommand;

package/dist/commands/token.d.ts

@@ -0,0 +1,21 @@
+import { getValidAccessToken } from "../oauth/getValidAccessToken";
+import { type TokenStore } from "../oauth/tokenStore";
+import type { CommonArgs } from "../cli/commonArgs";
+import type { CommandDeps } from "../cli/types";
+/** Verb-specific deps for `axe-auth token`. */
+export interface TokenDeps extends CommandDeps {
+    /** Override `getValidAccessToken` so tests don't touch the keychain or network. */
+    getToken?: typeof getValidAccessToken;
+    /** Override the token store. Defaults to a fresh `KeyringTokenStore()`. */
+    tokenStore?: TokenStore;
+}
+/** `axe-auth token` — print a currently-valid access token to stdout. */
+declare const tokenCommand: {
+    name: string;
+    summary: string;
+    helpText: string;
+    options: {};
+    requiresConfig: false;
+    run(_args: CommonArgs, deps: TokenDeps): Promise<void>;
+};
+export default tokenCommand;

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

@@ -0,0 +1,2 @@
+/** Help text for `axe-auth token --help`. */
+export declare const HELP_TOKEN = "axe-auth token\n\nPrint a currently-valid OAuth access token to stdout, refreshing\nsilently against the stored refresh token if needed.\n\nUsage:\n  axe-auth token\n\n  Operates exclusively on the keychain entry written by\n  `axe-auth login`. The --server / --allow-insecure-issuer /\n  --no-allow-insecure-issuer flags are accepted for parity with\n  other commands but ignored here; refresh uses the issuer, client,\n  and insecure-issuer policy persisted alongside the tokens at login.\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\nOutput:\n  The access token is written to stdout with a trailing newline so\n  shell substitution (`$(axe-auth token)`) works cleanly. Nothing\n  else is written to stdout.\n\nSecurity note:\n  Using `$(axe-auth token)` in a shell command exposes the access\n  token briefly in the system process-list (observable via `ps` on\n  POSIX, Task Manager on Windows). OAuth access tokens are\n  short-lived (typically minutes), which limits this exposure\n  compared to a static API key, but you should prefer streaming the\n  token into a file or env var on platforms where process listings\n  are sensitive.\n\nExit codes:\n  0  Success; the token was printed.\n  1  Not authenticated; run `axe-auth login` to re-authenticate.\n  2  Configuration error or transient failure (network, server,\n     keychain).";

package/dist/commands/token.help.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HELP_TOKEN = void 0;
+const commonArgs_help_1 = require("../cli/commonArgs.help");
+/** Help text for `axe-auth token --help`. */
+exports.HELP_TOKEN = `axe-auth token
+
+Print a currently-valid OAuth access token to stdout, refreshing
+silently against the stored refresh token if needed.
+
+Usage:
+  axe-auth token
+
+  Operates exclusively on the keychain entry written by
+  \`axe-auth login\`. The --server / --allow-insecure-issuer /
+  --no-allow-insecure-issuer flags are accepted for parity with
+  other commands but ignored here; refresh uses the issuer, client,
+  and insecure-issuer policy persisted alongside the tokens at login.
+
+Options:
+${commonArgs_help_1.HELP_COMMON_OPTIONS}
+
+Output:
+  The access token is written to stdout with a trailing newline so
+  shell substitution (\`$(axe-auth token)\`) works cleanly. Nothing
+  else is written to stdout.
+
+Security note:
+  Using \`$(axe-auth token)\` in a shell command exposes the access
+  token briefly in the system process-list (observable via \`ps\` on
+  POSIX, Task Manager on Windows). OAuth access tokens are
+  short-lived (typically minutes), which limits this exposure
+  compared to a static API key, but you should prefer streaming the
+  token into a file or env var on platforms where process listings
+  are sensitive.
+
+Exit codes:
+  0  Success; the token was printed.
+  1  Not authenticated; run \`axe-auth login\` to re-authenticate.
+  2  Configuration error or transient failure (network, server,
+     keychain).`;

package/dist/commands/token.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const errors_1 = require("../oauth/errors");
+const getValidAccessToken_1 = require("../oauth/getValidAccessToken");
+const tokenStore_1 = require("../oauth/tokenStore");
+const token_help_1 = require("./token.help");
+const errors_2 = require("../cli/errors");
+/** `axe-auth token` — print a currently-valid access token to stdout. */
+const tokenCommand = {
+    name: "token",
+    summary: "Print a currently-valid access token to stdout, refreshing silently if needed.",
+    helpText: token_help_1.HELP_TOKEN,
+    options: {},
+    requiresConfig: false,
+    async run(_args, deps) {
+        const getToken = deps.getToken ?? getValidAccessToken_1.getValidAccessToken;
+        const tokenStore = deps.tokenStore ?? new tokenStore_1.KeyringTokenStore();
+        // Stored entry is the only source of truth: single-entry-per-machine
+        // model, the blob carries the issuer/client coordinates the tokens
+        // were minted against, and there is no longer a flag to override
+        // them with.
+        const loaded = deps.loadedEntry ?? (await tokenStore.load());
+        let token;
+        try {
+            token = await getToken({
+                issuerURL: loaded.ok ? loaded.entry.issuerURL : "",
+                clientId: loaded.ok ? loaded.entry.clientId : "",
+                allowInsecureIssuer: loaded.ok
+                    ? loaded.entry.allowInsecureIssuer
+                    : false,
+                tokenStore,
+                loadedEntry: loaded,
+            });
+        }
+        catch (err) {
+            if (err instanceof errors_1.OAuthFlowError && err.code === "NOT_AUTHENTICATED") {
+                throw new errors_2.CLIError("NOT_AUTHENTICATED", err.message);
+            }
+            throw err;
+        }
+        deps.stdout.write(`${token}\n`);
+    },
+};
+exports.default = tokenCommand;