@deque/axe-auth 1.1.0-next.73fce274 → 1.1.0-next.7469dec9

package/dist/oauth/tokenStore.js

@@ -1,24 +1,50 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KeyringTokenStore = exports.STORED_BLOB_VERSION = void 0;
+exports.shouldChunkForKeyring = shouldChunkForKeyring;
 exports.parseAndMigrateBlob = parseAndMigrateBlob;
+exports.keyringErrorMessage = keyringErrorMessage;
+exports.platformKeyringHint = platformKeyringHint;
+exports.chunkBlobForKeyring = chunkBlobForKeyring;
 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.
+/**
+ * Keychain account identifier. On macOS/Linux the entire blob lives at
+ * this single account. On Windows the blob is base64-encoded and split
+ * across `credentials.0`, `credentials.1`, … entries (see `CHUNK_LIMIT`),
+ * so a Windows dev inspecting Credential Manager will see opaque base64.
+ */
 const ACCOUNT_NAME = "credentials";
+/**
+ * Max JS string length per chunk. The limit applies to the full chunk
+ * including chunk 0's `<N>\n` count header, so chunk 0's data slice is
+ * `CHUNK_LIMIT - headerLen`. Windows Credential Manager's per-entry
+ * cap is `CRED_MAX_CREDENTIAL_BLOB_SIZE = 2560` bytes, and the
+ * `@napi-rs/keyring` Windows backend stores strings as UTF-16 (2 bytes
+ * per char), so 1250 chars = 2500 bytes stays safely under the cap.
+ */
+const CHUNK_LIMIT = 1250;
+/**
+ * Cap on chunks per stored blob. A request that would exceed this
+ * raises `TOKEN_TOO_LARGE` so an IDP issuing tokens with extraordinary
+ * claim counts fails with a clear error instead of silently consuming
+ * dozens of keychain entries.
+ */
+const MAX_CHUNKS = 32;
+/**
+ * Whether `KeyringTokenStore` should split the stored blob across
+ * multiple keychain entries on this platform. Windows-only: Credential
+ * Manager has a 2560-byte per-entry cap that large OAuth tokens
+ * routinely exceed. macOS Keychain and Linux libsecret have no
+ * comparable limit, and on macOS each entry is independently lockable
+ * (chunking there would multiply per-entry ACL prompts). Exported
+ * (parameterized for tests) so the chunking path can be exercised
+ * deterministically.
+ */
+function shouldChunkForKeyring(platform = process.platform) {
+    return platform === "win32";
+}
 /**
  * Current on-disk blob schema version. Exported so consumers can
  * display "stored v:N, expected v:M" diagnostics when `load()` returns
@@ -72,7 +98,9 @@ function isLatestBlob(blob) {
         (b.refreshToken === undefined || typeof b.refreshToken === "string") &&
         typeof b.issuerURL === "string" &&
         typeof b.clientId === "string" &&
-        typeof b.allowInsecureIssuer === "boolean");
+        typeof b.allowInsecureIssuer === "boolean" &&
+        typeof b.walnutURL === "string" &&
+        b.walnutURL.length > 0);
 }
 function blobToEntry(blob) {
     const tokens = {
@@ -86,6 +114,7 @@ function blobToEntry(blob) {
         issuerURL: blob.issuerURL,
         clientId: blob.clientId,
         allowInsecureIssuer: blob.allowInsecureIssuer,
+        walnutURL: blob.walnutURL,
     };
 }
 function entryToBlob(entry) {
@@ -96,6 +125,7 @@ function entryToBlob(entry) {
         issuerURL: entry.issuerURL,
         clientId: entry.clientId,
         allowInsecureIssuer: entry.allowInsecureIssuer,
+        walnutURL: entry.walnutURL,
     };
     if (entry.tokens.refreshToken)
         blob.refreshToken = entry.tokens.refreshToken;
@@ -122,10 +152,6 @@ function parseAndMigrateBlob(raw, expectedVersion = exports.STORED_BLOB_VERSION,
     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) {
@@ -139,8 +165,6 @@ function parseAndMigrateBlob(raw, expectedVersion = exports.STORED_BLOB_VERSION,
         }
         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;
@@ -149,32 +173,162 @@ function parseAndMigrateBlob(raw, expectedVersion = exports.STORED_BLOB_VERSION,
     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 });
+    // Pass-through pre-wrapped OAuthFlowErrors so we don't double-wrap
+    // our own error type. The most common source today is
+    // `defaultEntryFactory` throwing `KEYRING_UNAVAILABLE` when the
+    // native binding can't be loaded — relabelling that as another
+    // `KEYRING_UNAVAILABLE` with a duplicate message and a possibly
+    // misleading platform hint helps nobody.
+    if (cause instanceof errors_1.OAuthFlowError) {
+        throw cause;
+    }
+    throw new errors_1.OAuthFlowError("KEYRING_UNAVAILABLE", keyringErrorMessage(op, cause), {
+        cause,
+    });
+}
+/**
+ * Builds the user-facing keychain error message: the underlying
+ * cause's text plus a per-platform hint. Platform is a parameter
+ * (defaulting to `process.platform`) so tests can drive each branch
+ * without mocking the runtime; mirrors the pattern in
+ * `platformKeyringHint`.
+ */
+function keyringErrorMessage(op, cause, platform = process.platform) {
+    const causeMessage = cause instanceof Error ? cause.message : String(cause);
+    return `System keychain ${op} failed: ${causeMessage}. ${platformKeyringHint(platform)}`;
+}
+/**
+ * Returns a per-platform hint appended to keychain error messages so
+ * users see actionable guidance for their OS instead of generic or
+ * Linux-only advice. Exported (but not re-exported from the package
+ * index) so tests can exercise each branch without mocking
+ * `process.platform`.
+ */
+function platformKeyringHint(platform = process.platform) {
+    switch (platform) {
+        case "darwin":
+            return "On macOS this usually means Keychain Access denied or cancelled the prompt.";
+        case "win32":
+            return "On Windows this usually means Credential Manager rejected the operation.";
+        case "linux":
+            return "On Linux this usually means no D-Bus Secret Service is running (e.g. GNOME Keyring or KWallet).";
+        default:
+            return `Underlying platform: ${platform}.`;
+    }
+}
+/**
+ * Parses chunk 0's `<N>\n<rest>` header. Returns the chunk count and
+ * the data part following the newline, or `null` for any malformed /
+ * out-of-range / non-canonically-encoded header. Centralised here
+ * (rather than open-coded twice in `#loadChunked` and
+ * `#previousChunkN`) so the canonical-encoding contract has one
+ * authoritative implementation.
+ */
+function parseChunkHeader(first) {
+    const newlineIdx = first.indexOf("\n");
+    if (newlineIdx <= 0)
+        return null;
+    const nStr = first.slice(0, newlineIdx);
+    const n = parseInt(nStr, 10);
+    // Reject non-canonical encodings ("01", " 3", "3abc"). parseInt is
+    // permissive about those; we want a single canonical encoding so
+    // two different headers can't decode to the same N.
+    if (!Number.isInteger(n) || n < 1 || n > MAX_CHUNKS || String(n) !== nStr) {
+        return null;
+    }
+    return { n, rest: first.slice(newlineIdx + 1) };
 }
 /**
  * `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.
+ * Secret Service). On macOS and Linux the blob lives in a single entry
+ * keyed by the fixed `credentials` account name. On Windows the blob
+ * is split across `credentials.0`, `credentials.1`, … entries to fit
+ * under Credential Manager's 2560-byte (1280 UTF-16 char) per-entry
+ * cap; see `shouldChunkForKeyring`.
+ *
+ * The blob carries its own issuer/client coordinates so verbs can
+ * recover full config without per-issuer keying.
  */
 class KeyringTokenStore {
-    #entry;
+    #entryFactory;
+    #chunked;
+    /**
+     * @param entryFactory Injection seam for `@napi-rs/keyring` entries.
+     *   Defaults to the production lazy-resolved factory; tests pass a
+     *   recording / faking variant.
+     */
     constructor(entryFactory = keyringBinding_1.defaultEntryFactory) {
-        this.#entry = entryFactory(SERVICE_NAME, ACCOUNT_NAME);
+        this.#entryFactory = entryFactory;
+        this.#chunked = shouldChunkForKeyring();
+    }
+    /**
+     * @internal Test seam. Constructs a store with an explicit chunking
+     * decision instead of the platform-determined default, so the
+     * chunked path can be exercised on macOS/Linux CI and the unchunked
+     * path on Windows CI. Production code must use the regular
+     * constructor and let `shouldChunkForKeyring()` decide — passing
+     * `chunked: true` on macOS would write data that the regular
+     * constructor wouldn't be able to read.
+     */
+    static forTesting(entryFactory, chunked) {
+        const store = new KeyringTokenStore(entryFactory);
+        store.#chunked = chunked;
+        return store;
+    }
+    #entry(account) {
+        return this.#entryFactory(SERVICE_NAME, account);
     }
     async save(entry) {
-        try {
-            this.#entry.setPassword(JSON.stringify(entryToBlob(entry)));
+        const jsonBlob = JSON.stringify(entryToBlob(entry));
+        if (this.#chunked) {
+            // Encode + chunk OUTSIDE the try/catch so a TOKEN_TOO_LARGE from
+            // `chunkBlobForKeyring` surfaces unchanged. The keychain
+            // operations stay inside the try and get wrapped as
+            // KEYRING_UNAVAILABLE if they fail.
+            const encoded = Buffer.from(jsonBlob, "utf8").toString("base64");
+            const parts = chunkBlobForKeyring(encoded);
+            try {
+                this.#saveChunked(parts);
+            }
+            catch (cause) {
+                wrapKeyringError("write", cause);
+            }
         }
-        catch (cause) {
-            wrapKeyringError("write", cause);
+        else {
+            try {
+                this.#entry(ACCOUNT_NAME).setPassword(jsonBlob);
+            }
+            catch (cause) {
+                wrapKeyringError("write", cause);
+            }
         }
     }
     async load() {
         let raw;
         try {
-            raw = this.#entry.getPassword();
+            if (this.#chunked) {
+                const result = this.#loadChunked();
+                if (result.kind === "present") {
+                    raw = result.blob;
+                }
+                else if (result.kind === "empty") {
+                    // First-time-upgrade fallback: a Windows dev who upgraded
+                    // across the chunking change has data at the bare
+                    // `credentials` account but no chunks yet. Read that legacy
+                    // entry; the next save() migrates it. Note we only fall
+                    // back when chunked data is *empty* — when chunked data is
+                    // *corrupt* we surface that directly rather than restoring
+                    // potentially stale legacy data underneath the corruption.
+                    raw = this.#entry(ACCOUNT_NAME).getPassword();
+                }
+                else {
+                    return { ok: false, reason: "corrupt" };
+                }
+            }
+            else {
+                raw = this.#entry(ACCOUNT_NAME).getPassword();
+            }
         }
         catch (cause) {
             wrapKeyringError("read", cause);
@@ -188,11 +342,204 @@ class KeyringTokenStore {
     }
     async clear() {
         try {
-            this.#entry.deletePassword();
+            if (this.#chunked) {
+                this.#clearChunked();
+            }
+            else {
+                this.#entry(ACCOUNT_NAME).deletePassword();
+            }
         }
         catch (cause) {
             wrapKeyringError("delete", cause);
         }
     }
+    /**
+     * Writes `parts` (the output of `chunkBlobForKeyring`) to entries
+     * `credentials.0..N-1`.
+     *
+     * Writes are in **reverse index order** — chunks N-1..1, then chunk
+     * 0 with the new header last. Chunk 0's header is what reads use to
+     * learn N, so until it's overwritten the previous chunk 0 still
+     * references the previous N chunks.
+     *
+     * Crash recovery is partial, not total. Reverse order helps in one
+     * case: when N_new > N_old and the crash happens before chunk 0 is
+     * rewritten — writes to indices >= N_old don't disturb old data,
+     * the previous chunk 0 still references the previous N chunks, and
+     * the prior session survives. The typical refresh case (N_new ==
+     * N_old) overwrites chunks 1..N-1 with new data while chunk 0 is
+     * still old, so a crash there reads as corrupt and the user
+     * re-auths. Reverse order is therefore a marginal improvement over
+     * forward order, not a guarantee.
+     *
+     * Cleanup sweeps `[N_new, N_old)` (bounded by the previous chunk
+     * count read from the old chunk 0 header before we overwrite it).
+     * For a typical token refresh (same N) this is zero deletes; the
+     * full safety sweep up to MAX_CHUNKS only runs as a defensive
+     * recovery when the previous N can't be determined. Orphans at
+     * indices >= max(N_new, N_old) from interrupted resize-up writes
+     * persist until the next `clear()` does the full sweep.
+     *
+     * Concurrency: this method is not safe to run concurrently against
+     * the same OS keychain. Two writers can interleave at chunk
+     * boundaries and produce a Frankenstein blob. axe-auth runs as a
+     * short-lived CLI so this is unlikely in practice, but a long-lived
+     * process refreshing in the background while the CLI is invoked
+     * could trip it.
+     */
+    #saveChunked(parts) {
+        const previousN = this.#previousChunkN();
+        for (let i = parts.length - 1; i >= 1; i--) {
+            this.#entry(`${ACCOUNT_NAME}.${i}`).setPassword(parts[i]);
+        }
+        this.#entry(`${ACCOUNT_NAME}.0`).setPassword(parts[0]);
+        // Best-effort sweep: writes have already succeeded, so a sweep
+        // failure shouldn't roll back the save. The next save's bounded
+        // sweep cleans up anything we miss here. Same reasoning for the
+        // legacy delete below.
+        const sweepEnd = previousN ?? MAX_CHUNKS;
+        for (let i = parts.length; i < sweepEnd; i++) {
+            try {
+                this.#entry(`${ACCOUNT_NAME}.${i}`).deletePassword();
+            }
+            catch {
+                // Sweep is best-effort; the next save handles leftovers.
+            }
+        }
+        // Clear any pre-chunking single-entry blob from a previous
+        // axe-auth release. This is a forever-tax (one extra
+        // deletePassword per save even after the migration is done)
+        // because we have no per-machine "migration completed" flag;
+        // adding one would mean another keychain entry to manage. The
+        // cost is one Credential Manager call per refresh — negligible
+        // relative to the OAuth round-trip.
+        try {
+            this.#entry(ACCOUNT_NAME).deletePassword();
+        }
+        catch {
+            // Best-effort; the next save attempts again.
+        }
+    }
+    /**
+     * Reads the chunk-count header from `credentials.0` so `#saveChunked`
+     * can bound its cleanup sweep. Returns `null` when chunk 0 is
+     * missing, when the header is malformed, or when the encoded N is
+     * out of range — every "I don't know the previous count" case
+     * collapses to a full safety sweep at the call site.
+     */
+    #previousChunkN() {
+        const first = this.#entry(`${ACCOUNT_NAME}.0`).getPassword();
+        if (first === null)
+            return null;
+        return parseChunkHeader(first)?.n ?? null;
+    }
+    /**
+     * Reverse of `#saveChunked`. Returns a discriminated result so the
+     * caller can distinguish "no data" from "data is malformed" without
+     * reaching for sentinel strings.
+     */
+    #loadChunked() {
+        const first = this.#entry(`${ACCOUNT_NAME}.0`).getPassword();
+        if (first === null)
+            return { kind: "empty" };
+        const header = parseChunkHeader(first);
+        if (!header)
+            return { kind: "corrupt" };
+        const parts = [header.rest];
+        for (let i = 1; i < header.n; i++) {
+            const part = this.#entry(`${ACCOUNT_NAME}.${i}`).getPassword();
+            if (part === null)
+                return { kind: "corrupt" };
+            parts.push(part);
+        }
+        // `Buffer.from(_, 'base64')` is permissive — invalid characters
+        // are silently dropped rather than throwing. Garbage base64
+        // produces garbage UTF-8, which falls through to the upstream
+        // JSON.parse and surfaces as `corrupt` from
+        // `parseAndMigrateBlob`. So no try/catch is needed here.
+        const blob = Buffer.from(parts.join(""), "base64").toString("utf8");
+        return { kind: "present", blob };
+    }
+    #clearChunked() {
+        // Sweep the whole safety range rather than break-on-first-missing
+        // so chunk holes (from interrupted writes or manual tampering)
+        // still get cleaned up. Logout is rare enough that the
+        // unconditional sweep cost is irrelevant.
+        //
+        // Per-entry errors are caught locally so a single throw doesn't
+        // strand the remaining chunks (or the legacy entry) in the
+        // keychain. After all attempts, we surface the first failure so
+        // the user still sees that logout didn't fully complete.
+        let firstError = null;
+        for (let i = 0; i < MAX_CHUNKS; i++) {
+            try {
+                this.#entry(`${ACCOUNT_NAME}.${i}`).deletePassword();
+            }
+            catch (cause) {
+                firstError ??= cause;
+            }
+        }
+        // And the pre-chunking single-entry blob, in case a Windows dev
+        // had axe-auth installed before chunking shipped.
+        try {
+            this.#entry(ACCOUNT_NAME).deletePassword();
+        }
+        catch (cause) {
+            firstError ??= cause;
+        }
+        if (firstError !== null) {
+            throw firstError;
+        }
+    }
 }
 exports.KeyringTokenStore = KeyringTokenStore;
+/**
+ * Splits `blob` into the N parts that `KeyringTokenStore.#saveChunked`
+ * writes to `credentials.0..N-1`. Chunk 0 is prefixed with `<N>\n` so
+ * the reader can learn N from a single getPassword call. Each chunk
+ * stays under `CHUNK_LIMIT` UTF-16 characters; throws if the blob would
+ * require more than `MAX_CHUNKS` chunks. Exported for tests.
+ */
+function chunkBlobForKeyring(blob) {
+    // N depends on the header length, which depends on N. Solve by
+    // iterating until the chunk count stabilises (converges in <= a
+    // couple of steps for any realistic blob). The safety counter is
+    // belt-and-suspenders against a future tweak (different
+    // CHUNK_LIMIT, different header format) accidentally introducing
+    // oscillation; an unbounded loop here would hang `axe-auth login`
+    // with no error.
+    let n = Math.max(1, Math.ceil(blob.length / CHUNK_LIMIT));
+    let safety = 0;
+    while (true) {
+        if (++safety > 8) {
+            throw new Error(`chunkBlobForKeyring: chunk count failed to converge after ${safety} iterations (blob length ${blob.length})`);
+        }
+        const headerLen = String(n).length + 1; // "<N>\n"
+        const chunk0Capacity = CHUNK_LIMIT - headerLen;
+        if (chunk0Capacity <= 0) {
+            throw new Error(`chunkBlobForKeyring: chunk count ${n} leaves no room for data`);
+        }
+        const remaining = Math.max(0, blob.length - chunk0Capacity);
+        const next = 1 + Math.ceil(remaining / CHUNK_LIMIT);
+        if (next === n)
+            break;
+        n = next;
+    }
+    if (n > MAX_CHUNKS) {
+        // Surfaced as a distinct error code (rather than KEYRING_UNAVAILABLE)
+        // because the keystore is healthy — the failure is that the IDP's
+        // token has too many claims to fit. Wrapping this as a keychain
+        // error would attach a misleading "Credential Manager rejected"
+        // platform hint via `wrapKeyringError`'s default path.
+        throw new errors_1.OAuthFlowError("TOKEN_TOO_LARGE", `OAuth token blob would require ${n} keyring entries (max ${MAX_CHUNKS}). The IDP may be issuing tokens with unusually many claims; talk to the realm administrator.`);
+    }
+    const headerLen = String(n).length + 1;
+    const chunk0Capacity = CHUNK_LIMIT - headerLen;
+    const parts = [`${n}\n${blob.slice(0, chunk0Capacity)}`];
+    let pos = chunk0Capacity;
+    while (pos < blob.length) {
+        parts.push(blob.slice(pos, pos + CHUNK_LIMIT));
+        pos += CHUNK_LIMIT;
+    }
+    return parts;
+}

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

@@ -13,9 +13,11 @@ flowchart TB
   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
@@ -23,7 +25,7 @@ flowchart TB
   browser -- "GET /callback?code=...&state=..." --> callback
   callback -- "code, state" --> cli
   cli <-- "OIDC discovery, token exchange,<br/>refresh, revoke (HTTPS)" --> keycloak
-  cli <-- "tokens + issuer/client<br/>(versioned blob)" --> keychain
+  cli <-- "tokens + issuer/client/walnutURL<br/>(versioned blob)" --> keychain
   cli -- "access token (stdout)" --> user
 ```
 
@@ -34,7 +36,8 @@ flowchart TB
 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. **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.
+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 ...`.
 
@@ -48,9 +51,12 @@ sequenceDiagram
   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 [...]
+  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>
@@ -63,21 +69,22 @@ sequenceDiagram
   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 to OS keychain
+  Note over CLI: save tokens + issuer/client/walnutURL to OS keychain
   CLI-->>User: ✓ Authenticated.
 ```
 
-1. The developer invokes `axe-auth login` with the authorization-server coordinates (or after a prior login, with no flags — the stored entry supplies them).
-2. The CLI fetches the OIDC discovery document at `<issuer>/.well-known/openid-configuration` to learn the authorization, token, and revocation endpoint URLs.
-3. The CLI generates a PKCE `code_verifier` + `code_challenge` (S256) and a random `state` value.
-4. The CLI starts a loopback HTTP listener on `127.0.0.1` at an OS-assigned port.
-5. The CLI opens the developer's system browser to the authorization endpoint with the PKCE challenge, the state, and the loopback `redirect_uri`.
-6. The developer authenticates with Keycloak (typically via the customer's federated SSO).
-7. Keycloak redirects the browser to the loopback `redirect_uri` with an authorization `code` and the original `state`.
-8. The loopback listener validates `state`, captures the `code`, and renders a small success page so the developer knows they can close the tab.
-9. The CLI POSTs `code` + `code_verifier` to Keycloak's token endpoint and receives an `access_token`, `refresh_token`, and `expires_in`.
-10. The CLI persists the resulting `StoredEntry` (tokens plus the issuer/client coordinates that minted them) into the OS keychain.
-11. The CLI prints `✓ Authenticated.` on stdout and exits 0.
+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`
 
@@ -173,14 +180,16 @@ sequenceDiagram
   "accessToken": "...",
   "refreshToken": "...",
   "expiresAt": 1714426800000,
-  "issuerURL": "https://auth.customer.example.com/realms/customer",
-  "clientId": "axe-auth",
-  "allowInsecureIssuer": false
+  "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.