@deque/axe-auth 1.1.0-next.816dc5a1 → 1.1.0-next.8e9934f2

package/dist/oauth/tokenStore.js

@@ -72,7 +72,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 +88,7 @@ function blobToEntry(blob) {
         issuerURL: blob.issuerURL,
         clientId: blob.clientId,
         allowInsecureIssuer: blob.allowInsecureIssuer,
+        walnutURL: blob.walnutURL,
     };
 }
 function entryToBlob(entry) {
@@ -96,6 +99,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;

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.8e9934f2",
   "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",