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

package/dist/oauth/tokenResponse.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.throwTokenEndpointError = throwTokenEndpointError;
+exports.parseTokenResponse = parseTokenResponse;
+const errors_1 = require("./errors");
+const predicates_1 = require("./predicates");
+// RFC 6749 §5.1 describes `expires_in` as "the lifetime in seconds"
+// without pinning the JSON type, and some providers historically send
+// numeric strings. Accept both; reject anything non-positive or
+// non-finite.
+function parseExpiresIn(v) {
+    if (typeof v === "number" && Number.isFinite(v) && v > 0)
+        return v;
+    if (typeof v === "string") {
+        const n = Number(v);
+        if (Number.isFinite(n) && n > 0)
+            return n;
+    }
+    return null;
+}
+function parseErrorBody(body) {
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return {};
+    }
+    if (parsed === null || typeof parsed !== "object")
+        return {};
+    const raw = parsed;
+    return {
+        error: (0, predicates_1.isNonEmptyString)(raw.error) ? raw.error : undefined,
+        description: (0, predicates_1.isNonEmptyString)(raw.error_description)
+            ? raw.error_description
+            : undefined,
+    };
+}
+/**
+ * Reads a non-2xx response body and throws
+ * `OAuthFlowError("TOKEN_EXCHANGE_FAILED", …)` with the OAuth
+ * `error` / `error_description` surfaced in both message and details
+ * when present. Shared by both the authorization-code exchange and
+ * refresh-token paths since the error contract is identical.
+ *
+ * @param context Short human-readable description of which call
+ *   failed ("Token exchange", "Token refresh", etc.). Appears in the
+ *   error message.
+ */
+async function throwTokenEndpointError(response, context) {
+    const body = await response.text().catch(() => "");
+    const { error, description } = parseErrorBody(body);
+    const suffix = error
+        ? description
+            ? `: ${error}: ${description}`
+            : `: ${error}`
+        : "";
+    const details = {};
+    if (error)
+        details.error = error;
+    if (description)
+        details.error_description = description;
+    throw new errors_1.OAuthFlowError("TOKEN_EXCHANGE_FAILED", `${context} failed with HTTP ${response.status}${suffix}`, Object.keys(details).length > 0 ? { details } : undefined);
+}
+/**
+ * Parses a 2xx response body from an RFC 6749 §5.1 token endpoint
+ * (authorization-code exchange, refresh-token grant, etc.) into a
+ * `TokenSet`. Validates the required shape (`access_token`,
+ * `expires_in`, Bearer `token_type`) and converts the relative
+ * `expires_in` into an absolute `expiresAt` using `issuedAt`.
+ *
+ * @param response The HTTP response (must be 2xx; caller handles
+ *   error statuses via `throwTokenEndpointError`).
+ * @param issuedAt The timestamp captured just before the network
+ *   call. Slightly conservative — the token actually expires
+ *   `expires_in` seconds from when the server issued it, so the
+ *   effective usable window is `expires_in - RTT`, which errs toward
+ *   "expires sooner" rather than "expires later."
+ * @param endpointURL URL used for error messages.
+ */
+async function parseTokenResponse(response, issuedAt, endpointURL) {
+    let parsed;
+    try {
+        parsed = await response.json();
+    }
+    catch (cause) {
+        throw new errors_1.OAuthFlowError("TOKEN_EXCHANGE_FAILED", `Token endpoint at ${endpointURL} returned a non-JSON response`, { cause });
+    }
+    if (parsed === null || typeof parsed !== "object") {
+        throw new errors_1.OAuthFlowError("TOKEN_EXCHANGE_FAILED", `Token endpoint at ${endpointURL} returned a non-object response`);
+    }
+    const raw = parsed;
+    if (!(0, predicates_1.isNonEmptyString)(raw.access_token)) {
+        throw new errors_1.OAuthFlowError("TOKEN_EXCHANGE_FAILED", `Token response missing 'access_token'`);
+    }
+    const expiresIn = parseExpiresIn(raw.expires_in);
+    if (expiresIn === null) {
+        throw new errors_1.OAuthFlowError("TOKEN_EXCHANGE_FAILED", `Token response missing or has invalid 'expires_in'`);
+    }
+    // RFC 6749 §5.1: token_type is REQUIRED. We only speak Bearer;
+    // DPoP / MAC / other proof-of-possession types need request-side
+    // support we don't implement, and silently treating them as Bearer
+    // would send tokens in the wrong header with unclear semantics.
+    if (!(0, predicates_1.isNonEmptyString)(raw.token_type)) {
+        throw new errors_1.OAuthFlowError("TOKEN_EXCHANGE_FAILED", `Token response missing required 'token_type'`);
+    }
+    if (raw.token_type.toLowerCase() !== "bearer") {
+        throw new errors_1.OAuthFlowError("TOKEN_EXCHANGE_FAILED", `Unsupported token_type '${raw.token_type}'; this library only handles Bearer.`);
+    }
+    const tokens = {
+        accessToken: raw.access_token,
+        expiresAt: issuedAt + expiresIn * 1000,
+    };
+    if ((0, predicates_1.isNonEmptyString)(raw.refresh_token)) {
+        tokens.refreshToken = raw.refresh_token;
+    }
+    if ((0, predicates_1.isNonEmptyString)(raw.scope)) {
+        tokens.grantedScope = raw.scope;
+    }
+    return tokens;
+}

package/dist/oauth/tokenStore.d.ts

@@ -0,0 +1,116 @@
+import { type KeyringEntryFactory } from "./keyringBinding";
+import type { TokenSet } from "./tokenResponse";
+/**
+ * Current on-disk blob schema version. Exported so consumers can
+ * display "stored v:N, expected v:M" diagnostics when `load()` returns
+ * a `version-mismatch` result.
+ */
+export declare const STORED_BLOB_VERSION = 1;
+/**
+ * What `KeyringTokenStore` persists: the OAuth tokens plus the
+ * issuer/client coordinates they were minted against. Carrying the
+ * coordinates inside the entry means a verb can recover its full
+ * config from the keychain alone, with no separate "default issuer"
+ * pointer.
+ */
+export interface StoredEntry {
+    tokens: TokenSet;
+    /** OIDC issuer URL the tokens were minted against. */
+    issuerURL: string;
+    /** OAuth client ID used at login. */
+    clientId: string;
+    /** Whether the original login allowed a non-loopback http issuer. */
+    allowInsecureIssuer: boolean;
+    /**
+     * Originating axe server (walnut) URL the user supplied (or the
+     * SaaS prod default) at login.
+     */
+    walnutURL: string;
+}
+/**
+ * Outcome of a `TokenStore.load()` call.
+ *
+ * Note on downgrades: the migrator chain only walks *forward*. A user
+ * who downgrades `axe-auth` to a release that predates a schema bump
+ * will see `version-mismatch` on any blob written by the newer
+ * release, even if the change was strictly additive. That is the safe
+ * default for a credentials blob — the older version cannot vouch for
+ * the meaning of fields it has never seen. Callers hitting this case
+ * should treat it as "re-authenticate" rather than attempting to
+ * parse an unknown future shape.
+ */
+export type LoadResult = {
+    ok: true;
+    entry: StoredEntry;
+} | {
+    ok: false;
+    reason: "empty";
+} | {
+    ok: false;
+    reason: "corrupt";
+} | {
+    ok: false;
+    reason: "version-mismatch";
+    storedVersion: number;
+};
+/** Persistence layer for an OAuth `StoredEntry`. */
+export interface TokenStore {
+    /** Write-through save. Replaces any previously stored entry. */
+    save(entry: StoredEntry): Promise<void>;
+    /**
+     * Reads the stored entry and returns a structured result.
+     *
+     * Callers should branch on `result.ok` first. When `ok` is `false`,
+     * `reason` tells them *why* there is no usable entry: `empty`
+     * (nothing stored), `corrupt` (unparseable or shape-invalid), or
+     * `version-mismatch` (stored under a schema we cannot migrate from).
+     * The library does not emit output on these cases — surfacing them
+     * to the user is the caller's responsibility.
+     */
+    load(): Promise<LoadResult>;
+    /** Removes any stored entry. No-op if none is present. */
+    clear(): Promise<void>;
+}
+/**
+ * Outcome of `parseAndMigrateBlob`: same set of failure reasons as
+ * `LoadResult`, but on success carries the post-migration blob as an
+ * unknown payload. The caller is responsible for shape-validating
+ * that payload against the latest schema.
+ */
+export type BlobChainResult = {
+    ok: true;
+    blob: unknown;
+} | {
+    ok: false;
+    reason: "empty";
+} | {
+    ok: false;
+    reason: "corrupt";
+} | {
+    ok: false;
+    reason: "version-mismatch";
+    storedVersion: number;
+};
+/**
+ * JSON-parses the raw keychain password and walks the migrator chain
+ * until it reaches `expectedVersion`. Exported with `expectedVersion`
+ * and `migrators` parameters only for testing the chain mechanics
+ * against synthetic versions / migrators; production callers use
+ * `KeyringTokenStore.load()`, which feeds in `STORED_BLOB_VERSION`
+ * and `MIGRATORS` and applies the latest-shape check on top.
+ */
+export declare function parseAndMigrateBlob(raw: string | null, expectedVersion?: number, migrators?: ReadonlyMap<number, (old: unknown) => unknown | null>): BlobChainResult;
+/**
+ * `TokenStore` backed by the operating system's native keychain via
+ * `@napi-rs/keyring` (macOS Keychain, Windows Credential Manager, Linux
+ * Secret Service). One entry per machine, keyed by a fixed account
+ * name; the blob carries its own issuer/client coordinates so verbs
+ * can recover full config without per-issuer keying.
+ */
+export declare class KeyringTokenStore implements TokenStore {
+    #private;
+    constructor(entryFactory?: KeyringEntryFactory);
+    save(entry: StoredEntry): Promise<void>;
+    load(): Promise<LoadResult>;
+    clear(): Promise<void>;
+}

package/dist/oauth/tokenStore.js

@@ -0,0 +1,202 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KeyringTokenStore = exports.STORED_BLOB_VERSION = void 0;
+exports.parseAndMigrateBlob = parseAndMigrateBlob;
+const errors_1 = require("./errors");
+const keyringBinding_1 = require("./keyringBinding");
+// On macOS: Keychain generic password item with the service name below.
+// On Windows: Credential Manager entry. On Linux: Secret Service / libsecret.
+// Exposed as a human-readable string because these all surface the service
+// name in OS UIs (Keychain Access, credmgr.exe, seahorse).
+const SERVICE_NAME = "axe-auth";
+// Single keychain entry per machine. The blob it holds is fully
+// self-describing (issuerURL, clientId, allowInsecureIssuer, plus the
+// tokens), so verbs that don't pass `--server` / `--realm` /
+// `--client-id` can resolve their config from the entry.
+//
+// Account name is human-readable so users investigating the entry in
+// macOS Keychain Access (or `secret-tool` on Linux, credmgr on
+// Windows) can tell what it is. Not versioned: the schema version
+// lives inside the blob and migrators handle the upgrade path.
+const ACCOUNT_NAME = "credentials";
+/**
+ * Current on-disk blob schema version. Exported so consumers can
+ * display "stored v:N, expected v:M" diagnostics when `load()` returns
+ * a `version-mismatch` result.
+ */
+exports.STORED_BLOB_VERSION = 1;
+/**
+ * Migrators upgrade an older blob to the next version up. Walked by
+ * `load()` until the stored blob reaches `STORED_BLOB_VERSION`.
+ *
+ * A migrator returns `null` when the bump cannot be inferred from the
+ * old shape (e.g. a new required field with no derivable default); the
+ * caller then sees `{ ok: false, reason: "version-mismatch" }` and
+ * decides whether to re-auth, prompt, or preserve the old blob.
+ *
+ * Each migrator is responsible for taking `vN` → `vN+1`. To skip a
+ * version deliberately, register a migrator that returns `null` for
+ * that `fromVersion`.
+ */
+const MIGRATORS = new Map([
+// [1, (v1) => migrateV1ToV2(v1 as StoredBlobV1)],
+]);
+// Sanity-check the migrator map at module load. Every key must be
+// strictly less than `STORED_BLOB_VERSION` — the chain only walks
+// forward, so a leftover migrator at the current (or future) version
+// would either be unreachable or confuse the loop. Fail-fast so a
+// dev forgetting to remove a stale entry during a version bump
+// notices before shipping.
+for (const fromVersion of MIGRATORS.keys()) {
+    if (fromVersion >= exports.STORED_BLOB_VERSION) {
+        throw new Error(`MIGRATORS contains a key (v${fromVersion}) that is not strictly less than STORED_BLOB_VERSION (${exports.STORED_BLOB_VERSION}). The chain only walks forward; remove stale migrators when bumping the schema version.`);
+    }
+}
+function getStoredVersion(blob) {
+    if (blob === null || typeof blob !== "object")
+        return null;
+    const v = blob.v;
+    return typeof v === "number" && Number.isInteger(v) && v > 0 ? v : null;
+}
+function isLatestBlob(blob) {
+    if (blob === null || typeof blob !== "object")
+        return false;
+    const b = blob;
+    return (b.v === exports.STORED_BLOB_VERSION &&
+        // Empty access token is treated as corrupt rather than a usable
+        // credential. `axe-auth token` printing an empty line and exiting
+        // 0 would look like success and silently break downstream.
+        typeof b.accessToken === "string" &&
+        b.accessToken.length > 0 &&
+        typeof b.expiresAt === "number" &&
+        (b.refreshToken === undefined || typeof b.refreshToken === "string") &&
+        typeof b.issuerURL === "string" &&
+        typeof b.clientId === "string" &&
+        typeof b.allowInsecureIssuer === "boolean" &&
+        typeof b.walnutURL === "string" &&
+        b.walnutURL.length > 0);
+}
+function blobToEntry(blob) {
+    const tokens = {
+        accessToken: blob.accessToken,
+        expiresAt: blob.expiresAt,
+    };
+    if (blob.refreshToken)
+        tokens.refreshToken = blob.refreshToken;
+    return {
+        tokens,
+        issuerURL: blob.issuerURL,
+        clientId: blob.clientId,
+        allowInsecureIssuer: blob.allowInsecureIssuer,
+        walnutURL: blob.walnutURL,
+    };
+}
+function entryToBlob(entry) {
+    const blob = {
+        v: exports.STORED_BLOB_VERSION,
+        accessToken: entry.tokens.accessToken,
+        expiresAt: entry.tokens.expiresAt,
+        issuerURL: entry.issuerURL,
+        clientId: entry.clientId,
+        allowInsecureIssuer: entry.allowInsecureIssuer,
+        walnutURL: entry.walnutURL,
+    };
+    if (entry.tokens.refreshToken)
+        blob.refreshToken = entry.tokens.refreshToken;
+    return blob;
+}
+/**
+ * JSON-parses the raw keychain password and walks the migrator chain
+ * until it reaches `expectedVersion`. Exported with `expectedVersion`
+ * and `migrators` parameters only for testing the chain mechanics
+ * against synthetic versions / migrators; production callers use
+ * `KeyringTokenStore.load()`, which feeds in `STORED_BLOB_VERSION`
+ * and `MIGRATORS` and applies the latest-shape check on top.
+ */
+function parseAndMigrateBlob(raw, expectedVersion = exports.STORED_BLOB_VERSION, migrators = MIGRATORS) {
+    if (raw === null)
+        return { ok: false, reason: "empty" };
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, reason: "corrupt" };
+    }
+    const storedVersion = getStoredVersion(parsed);
+    if (storedVersion === null)
+        return { ok: false, reason: "corrupt" };
+    // Walk the migrator chain until we reach the expected version. A
+    // missing or null-returning migrator means the old blob cannot be
+    // upgraded; surface that so callers can prompt re-auth with a
+    // clear signal instead of silently returning `empty`.
+    let current = parsed;
+    let currentVersion = storedVersion;
+    while (currentVersion !== expectedVersion) {
+        const migrator = migrators.get(currentVersion);
+        if (!migrator) {
+            return { ok: false, reason: "version-mismatch", storedVersion };
+        }
+        const next = migrator(current);
+        if (next === null) {
+            return { ok: false, reason: "version-mismatch", storedVersion };
+        }
+        const nextVersion = getStoredVersion(next);
+        if (nextVersion === null || nextVersion <= currentVersion) {
+            // Migrator output is malformed or didn't advance. Treat the
+            // stored blob as un-migratable rather than loop forever.
+            return { ok: false, reason: "version-mismatch", storedVersion };
+        }
+        current = next;
+        currentVersion = nextVersion;
+    }
+    return { ok: true, blob: current };
+}
+function wrapKeyringError(op, cause) {
+    throw new errors_1.OAuthFlowError("KEYRING_UNAVAILABLE", `System keychain ${op} failed. On Linux this usually means no D-Bus Secret Service is running.`, { cause });
+}
+/**
+ * `TokenStore` backed by the operating system's native keychain via
+ * `@napi-rs/keyring` (macOS Keychain, Windows Credential Manager, Linux
+ * Secret Service). One entry per machine, keyed by a fixed account
+ * name; the blob carries its own issuer/client coordinates so verbs
+ * can recover full config without per-issuer keying.
+ */
+class KeyringTokenStore {
+    #entry;
+    constructor(entryFactory = keyringBinding_1.defaultEntryFactory) {
+        this.#entry = entryFactory(SERVICE_NAME, ACCOUNT_NAME);
+    }
+    async save(entry) {
+        try {
+            this.#entry.setPassword(JSON.stringify(entryToBlob(entry)));
+        }
+        catch (cause) {
+            wrapKeyringError("write", cause);
+        }
+    }
+    async load() {
+        let raw;
+        try {
+            raw = this.#entry.getPassword();
+        }
+        catch (cause) {
+            wrapKeyringError("read", cause);
+        }
+        const chain = parseAndMigrateBlob(raw);
+        if (!chain.ok)
+            return chain;
+        if (!isLatestBlob(chain.blob))
+            return { ok: false, reason: "corrupt" };
+        return { ok: true, entry: blobToEntry(chain.blob) };
+    }
+    async clear() {
+        try {
+            this.#entry.deletePassword();
+        }
+        catch (cause) {
+            wrapKeyringError("delete", cause);
+        }
+    }
+}
+exports.KeyringTokenStore = KeyringTokenStore;

package/dist/userAgent.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `User-Agent` header value sent on all outbound requests, per
+ * Service Development Standards §4.4.
+ *
+ * Format: `axe-auth/v<package-version>` (e.g. `axe-auth/v1.0.2`).
+ *
+ * The npm scope (`@deque/`) is deliberately omitted from the wire format:
+ * `@` and `/` are not valid `tchar` per RFC 9110 §5.6.2, so a token like
+ * `@deque/axe-auth` would make the User-Agent malformed and risk WAF
+ * rejection (e.g. OWASP CRS rule 920330).
+ */
+export declare const USER_AGENT: string;

package/dist/userAgent.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.USER_AGENT = void 0;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const pkg = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(__dirname, "..", "package.json"), "utf-8"));
+/**
+ * `User-Agent` header value sent on all outbound requests, per
+ * Service Development Standards §4.4.
+ *
+ * Format: `axe-auth/v<package-version>` (e.g. `axe-auth/v1.0.2`).
+ *
+ * The npm scope (`@deque/`) is deliberately omitted from the wire format:
+ * `@` and `/` are not valid `tchar` per RFC 9110 §5.6.2, so a token like
+ * `@deque/axe-auth` would make the User-Agent malformed and risk WAF
+ * rejection (e.g. OWASP CRS rule 920330).
+ */
+exports.USER_AGENT = `axe-auth/v${pkg.version}`;

package/docs/architecture.md

@@ -0,0 +1,201 @@
+# `@deque/axe-auth` Architecture
+
+This document describes the system architecture and data flow of the `@deque/axe-auth` CLI: the components it interacts with, the data passed between them, what is persisted, and how communication is authenticated and protected.
+
+`axe-auth` is a developer-facing CLI that performs OAuth 2.0 Authorization Code + PKCE login (RFC 6749, RFC 7636, RFC 8252 §7.3) against a Keycloak deployment, persists the resulting tokens in the operating-system keychain, and prints currently-valid access tokens on demand. The tokens it produces are consumed by downstream tools (notably the axe MCP server) to authenticate against Deque services on behalf of the developer.
+
+## High-level architecture
+
+```mermaid
+flowchart TB
+  user[Developer]
+  cli[axe-auth CLI]
+  browser[System browser]
+  callback[Loopback callback server<br/>127.0.0.1:ephemeral]
+  keychain[(OS keychain)]
+  axe[axe server]
+  keycloak[Customer Keycloak]
+
+  user -- "axe-auth login / token / logout" --> cli
+  cli -- "GET /api/sso-config (login only)" --> axe
+  cli -- "spawns" --> callback
+  cli -- "opens" --> browser
+  browser -- "authorize redirect<br/>(state, PKCE challenge)" --> keycloak
+  keycloak -- "302 to loopback<br/>(code, state)" --> browser
+  browser -- "GET /callback?code=...&state=..." --> callback
+  callback -- "code, state" --> cli
+  cli <-- "OIDC discovery, token exchange,<br/>refresh, revoke (HTTPS)" --> keycloak
+  cli <-- "tokens + issuer/client/walnutURL<br/>(versioned blob)" --> keychain
+  cli -- "access token (stdout)" --> user
+```
+
+**Components and their roles:**
+
+1. **Developer**: invokes `axe-auth login`, `axe-auth token`, or `axe-auth logout` on their host machine.
+2. **axe-auth CLI**: this package. Drives the OAuth flow, persists tokens, prints access tokens on stdout, revokes refresh tokens on logout.
+3. **System browser**: the developer's default OS browser (Chrome, Safari, Firefox, etc.). Used only for the user-interactive part of the OAuth Authorization Code flow. Runs on the host, never in a container or sandbox controlled by `axe-auth`.
+4. **Loopback callback server**: an HTTP listener bound to `127.0.0.1` on an OS-assigned ephemeral port. Spawned by the CLI at the start of `login` and torn down as soon as the OAuth callback fires. Per RFC 8252 §7.3, this is the standard pattern for native-app OAuth.
+5. **OS keychain**: the platform-native credential store accessed through [`@napi-rs/keyring`](https://www.npmjs.com/package/@napi-rs/keyring) — macOS Keychain, Windows Credential Manager, or Linux Secret Service (GNOME Keyring, KWallet). The CLI writes one entry per machine.
+6. **axe server**: the customer's deployment of the axe API. The CLI hits its `/api/sso-config` endpoint at the start of `login` to discover the Keycloak URL, realm, and OAuth client ID; no other CLI traffic flows through the axe server.
+7. **Customer Keycloak**: the OAuth authorization server for the customer's deployment. Issues access and refresh tokens. Federation between Keycloak and any upstream enterprise IdP (Okta, AAD, etc.) is the customer's concern and out of scope for this document.
+
+`axe-auth` itself does **not** communicate with Deque's API services directly. The access tokens it produces are consumed by downstream tools, most notably the axe MCP server, which presents them to Deque's services as `Authorization: Bearer ...`.
+
+## Data flow per verb
+
+### `axe-auth login`
+
+```mermaid
+sequenceDiagram
+  participant User as Developer
+  participant CLI as axe-auth CLI
+  participant Browser as System browser
+  participant CB as Loopback callback<br/>(127.0.0.1:port)
+  participant Axe as axe server
+  participant KC as Customer Keycloak
+
+  User->>CLI: axe-auth login [--server <axe-url>]
+  CLI->>Axe: GET /api/sso-config
+  Axe-->>CLI: { url, realm, mcpClientId }
+  CLI->>KC: GET /.well-known/openid-configuration
+  KC-->>CLI: { authorization_endpoint, token_endpoint, ... }
+  CLI->>CB: spawn on 127.0.0.1:<ephemeral>
+  CLI->>Browser: authorize URL (+PKCE, state, redirect_uri)
+  Browser->>KC: GET /authorize
+  Note over KC: User authenticates via SSO
+  KC-->>Browser: 302 to loopback (code, state)
+  Browser->>CB: GET /callback?code=...&state=...
+  CB-->>Browser: HTML success page
+  CB-->>CLI: { code, state }
+  CLI->>KC: POST /token (code, code_verifier)
+  KC-->>CLI: { access_token, refresh_token, expires_in }
+  Note over CLI: save tokens + issuer/client/walnutURL to OS keychain
+  CLI-->>User: ✓ Authenticated.
+```
+
+1. The developer invokes `axe-auth login`, optionally with `--server <axe-url>` (or `AXE_SERVER_URL`); when neither is set the CLI defaults to Deque's SaaS prod axe server.
+2. The CLI fetches `<axe-server>/api/sso-config` to learn the Keycloak base URL, realm, and OAuth client ID. The axe server returns `mcpClientId: null` when the deployment has not been configured for OAuth-based MCP authentication, and the field is absent on older axe server versions; both cases surface as a clear error before any browser is opened.
+3. With the discovered coordinates the CLI fetches the OIDC discovery document at `<issuer>/.well-known/openid-configuration` to learn the authorization, token, and revocation endpoint URLs.
+4. The CLI generates a PKCE `code_verifier` + `code_challenge` (S256) and a random `state` value.
+5. The CLI starts a loopback HTTP listener on `127.0.0.1` at an OS-assigned port.
+6. The CLI opens the developer's system browser to the authorization endpoint with the PKCE challenge, the state, and the loopback `redirect_uri`.
+7. The developer authenticates with Keycloak (typically via the customer's federated SSO).
+8. Keycloak redirects the browser to the loopback `redirect_uri` with an authorization `code` and the original `state`.
+9. The loopback listener validates `state`, captures the `code`, and renders a small success page so the developer knows they can close the tab.
+10. The CLI POSTs `code` + `code_verifier` to Keycloak's token endpoint and receives an `access_token`, `refresh_token`, and `expires_in`.
+11. The CLI persists the resulting `StoredEntry` (tokens plus the issuer/client coordinates that minted them, plus the originating axe server URL) into the OS keychain.
+12. The CLI prints `✓ Authenticated.` on stdout and exits 0.
+
+### `axe-auth token`
+
+```mermaid
+sequenceDiagram
+  participant User as Developer
+  participant CLI as axe-auth CLI
+  participant KC as Customer Keycloak
+
+  User->>CLI: axe-auth token
+  Note over CLI: load stored entry from OS keychain
+  alt access token still fresh (within expiry buffer)
+    CLI-->>User: print access_token to stdout
+  else access token expired or near expiry
+    CLI->>KC: POST /token (refresh_token)
+    alt success (rotated tokens)
+      KC-->>CLI: { access_token, refresh_token, expires_in }
+      Note over CLI: save rotated entry to OS keychain
+      CLI-->>User: print access_token to stdout
+    else invalid_grant (refresh rejected)
+      KC-->>CLI: 400 invalid_grant
+      Note over CLI: clear OS keychain entry
+      CLI-->>User: stderr "session expired", exit 1
+    end
+  end
+```
+
+1. The developer invokes `axe-auth token` (typically inside shell substitution: `$(axe-auth token)`).
+2. The CLI loads the stored entry from the OS keychain.
+3. If the access token is still within its expiry buffer, the CLI prints it on stdout and exits 0 with no network call.
+4. Otherwise the CLI POSTs the refresh token to Keycloak's token endpoint to obtain a fresh access token (and a rotated refresh token, since Keycloak rotates by default).
+5. On success, the CLI persists the rotated entry and prints the new access token on stdout.
+6. On `invalid_grant` (refresh token revoked or expired server-side), the CLI clears the local entry and exits 1 with a "re-authenticate" message on stderr. Other transient failures (network, 5xx) leave the stored entry intact so the user can retry.
+
+### `axe-auth logout`
+
+```mermaid
+sequenceDiagram
+  participant User as Developer
+  participant CLI as axe-auth CLI
+  participant KC as Customer Keycloak
+
+  User->>CLI: axe-auth logout
+  Note over CLI: load stored entry from OS keychain
+  alt no entry stored
+    CLI-->>User: "Already logged out."
+  else entry unreadable (corrupt or version-mismatch)
+    Note over CLI: clear OS keychain entry
+    CLI-->>User: stderr warning + ✓ Logged out.
+  else valid entry
+    CLI->>KC: GET /.well-known/openid-configuration
+    KC-->>CLI: { revocation_endpoint }
+    CLI->>KC: POST /revoke (refresh_token)
+    KC-->>CLI: 200 (best-effort, non-2xx warns but does not block)
+    Note over CLI: clear OS keychain entry
+    CLI-->>User: ✓ Logged out.
+  end
+```
+
+1. The developer invokes `axe-auth logout`.
+2. The CLI loads the stored entry. If nothing is stored, it prints "Already logged out." and exits 0. If the entry is unreadable (corrupt or under a schema version we cannot migrate), it clears the local entry and exits 0 with a warning on stderr.
+3. With a valid entry, the CLI re-fetches the OIDC discovery document to find the revocation endpoint, then POSTs the refresh token there per RFC 7009.
+4. Server-side revocation is best-effort: a non-2xx response is logged to stderr but does not block the local clear. The response body is deliberately not echoed (the request body contains the refresh token, and some Keycloak / WAF / reverse-proxy error templates reflect request fields back into 4xx pages).
+5. The CLI clears the local OS keychain entry and prints `✓ Logged out.`.
+
+## Communication security
+
+### Transport
+
+- **CLI ↔ Customer Keycloak**: HTTPS by default. The CLI refuses non-loopback http issuers unless explicitly opted in via `--allow-insecure-issuer` (loopback http remains allowed because RFC 8252 §7.3 mandates it). All outbound requests carry a `User-Agent: @deque/axe-auth/v<version>` header per [Service Development Standards §4.4](https://github.com/dequelabs/product-org/blob/main/policies/services/standards.md#44-client-user-agents).
+- **Browser ↔ Customer Keycloak**: HTTPS, same as any standard web SSO interaction. `axe-auth` does not see, store, or proxy the developer's password or any SSO session cookies.
+- **Browser ↔ Loopback callback**: Loopback HTTP. Per RFC 8252 §7.3 this is acceptable because traffic stays on the local machine. The loopback listener accepts a single request, validates `state` against the value generated at the start of the flow, and shuts down immediately afterwards.
+- **CLI ↔ OS keychain**: Native OS APIs (Keychain Services, Credential Manager, Secret Service). Access control is the OS's: the entry is readable only by the same user account on the same machine.
+
+### Flow integrity
+
+- **Authorization-code interception (PKCE)**: The CLI generates a fresh `code_verifier` per login, sends only the `code_challenge` (SHA-256 hash) to the authorize endpoint, and supplies the `code_verifier` at the token-exchange step. An attacker who intercepts the authorization code on the loopback redirect cannot exchange it without the verifier.
+- **CSRF on the loopback redirect (`state`)**: The CLI generates a cryptographically random `state` per login, sends it on the authorize request, and rejects any callback whose `state` does not match.
+
+### Token handling
+
+- **Refresh-token confidentiality**: The refresh token never leaves the OS keychain except as the body of the POST to Keycloak's `/token` (refresh) or `/revoke` endpoints. It is never printed to stdout, written to logs, or surfaced in error messages. (See the deliberate response-body suppression in the revocation path, called out under `logout` above.)
+- **Access-token surfacing (`axe-auth token`)**: Access tokens are printed to stdout for shell substitution. They appear briefly in process arguments (`ps` on POSIX, Task Manager on Windows) and in terminal scrollback buffers (iTerm2, Terminal.app, tmux). Mitigation guidance is documented in the README's caveats section. Access tokens are short-lived (Keycloak default ~5 minutes), which limits the exposure window.
+- **Browser session isolation**: The browser used for OAuth login is the developer's host browser. Any tooling consuming the access token (e.g. the axe MCP server in a Docker container) runs in its own browser context with no shared cookies, storage, or session state.
+
+## Persisted data
+
+`axe-auth` writes exactly one keychain entry per machine, under the service name `axe-auth` and the account name `credentials`. The stored payload is a versioned JSON blob:
+
+```json
+{
+  "v": 1,
+  "accessToken": "...",
+  "refreshToken": "...",
+  "expiresAt": 1714426800000,
+  "issuerURL": "https://auth.customer.example.com/auth/realms/customer",
+  "clientId": "axe-auth-cli",
+  "allowInsecureIssuer": false,
+  "walnutURL": "https://axe.customer.example.com"
+}
+```
+
+- **Tokens** (`accessToken`, `refreshToken`, `expiresAt`): the OAuth token set returned by Keycloak. `refreshToken` is omitted if the granted scopes did not include `offline_access`.
+- **Issuer / client coordinates** (`issuerURL`, `clientId`, `allowInsecureIssuer`): the values the tokens were minted against. Persisting them lets `token` and `logout` operate flag-free after first login: the CLI resolves the right discovery URL, token endpoint, and revocation endpoint from the stored values, with no separate "default issuer" pointer to drift out of sync with the tokens themselves.
+- **`walnutURL`**: the originating axe server URL that the SSO discovery used to resolve the OAuth coordinates. Persisted so future verbs can re-discover `/api/sso-config` without user-supplied flags.
+- **Schema version** (`v`): incremented when the blob shape changes incompatibly. A mismatch surfaces as `version-mismatch` from `KeyringTokenStore.load()`, and the CLI prompts re-authentication rather than guessing at unknown shapes.
+
+No other persistent state exists. There is no filesystem cache of OIDC discovery documents (each `login` and `logout` re-fetches), no separate config file, and no logs written to disk by default.
+
+## Related documentation
+
+- [`oauth-flow.md`](./oauth-flow.md) — protocol-level walkthrough of the OAuth 2.0 + PKCE flow as implemented here.
+- [`callback-server.md`](./callback-server.md) — the `startCallbackServer` API, RFC 8252 §7.3 conformance, port allocation, and listener teardown.
+- [`callback-page.md`](./callback-page.md) — the HTML rendered to the developer's browser after the redirect, branding, and CSP rationale.