@deque/axe-auth 1.1.0-next.816dc5a1 → 1.1.0-next.82d244e3

package/dist/oauth/openBrowser.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.openBrowser = openBrowser;
 const node_child_process_1 = require("node:child_process");
+const shlex_1 = require("shlex");
 const errors_1 = require("./errors");
 // On Windows `start` is a cmd.exe builtin, not a standalone binary.
 // The empty `""` pair is a positional placeholder for the window
@@ -26,7 +27,11 @@ function windowsCommand(url) {
         args: ["/c", "start", '""', url.replace(/[&|^<>"%\r\n]/g, (c) => `^${c}`)],
     };
 }
-function browserCommand(platform, url) {
+function browserCommand(platform, url, browserOverride) {
+    if (browserOverride && browserOverride.length > 0) {
+        const [command, ...extraArgs] = browserOverride;
+        return { command, args: [...extraArgs, url] };
+    }
     switch (platform) {
         case "darwin":
             return { command: "open", args: [url] };
@@ -47,16 +52,28 @@ function browserCommand(platform, url) {
 }
 /**
  * Launches the system browser at `url` in a detached child process.
- * Returns synchronously once the child is spawned — completion of the
- * browser load is intentionally not awaited.
+ * Honors `$BROWSER` when set, falling back to the platform default
+ * (`open` / `xdg-open` / `cmd start`). Returns synchronously once the
+ * child is spawned — completion of the browser load is intentionally
+ * not awaited.
  *
  * @param url Absolute URL to open.
- * @param options Platform/spawn overrides; only exposed for tests.
+ * @param options Platform/spawn/env overrides; only exposed for tests.
  */
 function openBrowser(url, options = {}) {
     const platform = options.platform ?? process.platform;
     const spawnFn = options.spawnFn ?? node_child_process_1.spawn;
-    const { command, args } = browserCommand(platform, url);
+    const browserEnv = options.browserEnv ?? process.env.BROWSER;
+    let browserOverride;
+    if (browserEnv && browserEnv.length > 0) {
+        try {
+            browserOverride = (0, shlex_1.split)(browserEnv);
+        }
+        catch (cause) {
+            throw new errors_1.OAuthFlowError("BROWSER_LAUNCH_FAILED", `Failed to parse $BROWSER (${browserEnv}). Open this URL manually:\n${url}`, { cause });
+        }
+    }
+    const { command, args } = browserCommand(platform, url, browserOverride);
     let child;
     try {
         child = spawnFn(command, args, {

package/dist/oauth/tokenStore.d.ts

@@ -21,6 +21,11 @@ export interface StoredEntry {
     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.
@@ -95,6 +100,14 @@ export type BlobChainResult = {
  * 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;
+/**
+ * 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`.
+ */
+export declare function platformKeyringHint(platform?: NodeJS.Platform): string;
 /**
  * `TokenStore` backed by the operating system's native keychain via
  * `@napi-rs/keyring` (macOS Keychain, Windows Credential Manager, Linux

package/dist/oauth/tokenStore.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KeyringTokenStore = exports.STORED_BLOB_VERSION = void 0;
 exports.parseAndMigrateBlob = parseAndMigrateBlob;
+exports.platformKeyringHint = platformKeyringHint;
 const errors_1 = require("./errors");
 const keyringBinding_1 = require("./keyringBinding");
 // On macOS: Keychain generic password item with the service name below.
@@ -72,7 +73,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 +89,7 @@ function blobToEntry(blob) {
         issuerURL: blob.issuerURL,
         clientId: blob.clientId,
         allowInsecureIssuer: blob.allowInsecureIssuer,
+        walnutURL: blob.walnutURL,
     };
 }
 function entryToBlob(entry) {
@@ -96,6 +100,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;
@@ -149,7 +154,27 @@ 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 });
+    const causeMessage = cause instanceof Error ? cause.message : String(cause);
+    throw new errors_1.OAuthFlowError("KEYRING_UNAVAILABLE", `System keychain ${op} failed: ${causeMessage}. ${platformKeyringHint()}`, { cause });
+}
+/**
+ * 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}.`;
+    }
 }
 /**
  * `TokenStore` backed by the operating system's native keychain via

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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deque/axe-auth",
-  "version": "1.1.0-next.816dc5a1",
+  "version": "1.1.0-next.82d244e3",
   "description": "CLI authentication utility for Deque services",
   "license": "SEE LICENSE IN LICENSE",
   "type": "commonjs",
@@ -12,7 +12,8 @@
   "files": [
     "dist",
     "!dist/**/*.test.*",
-    "docs"
+    "docs",
+    "credits.json"
   ],
   "publishConfig": {
     "access": "public",
@@ -24,11 +25,14 @@
   "dependencies": {
     "@napi-rs/keyring": "^1.2.0",
     "remove-trailing-slash": "^0.1.1",
+    "shlex": "^3.0.0",
     "ts-dedent": "^2.2.0"
   },
   "devDependencies": {
+    "@hono/node-server": "^1.19.14",
     "@types/node": "^22.13.10",
     "c8": "^10.1.3",
+    "hono": "^4.12.16",
     "tsx": "^4.20.6",
     "typescript": "^5.9.3"
   },