@deque/axe-auth 1.1.0-next.fb07beab → 1.1.0-next.fea0aa8a

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.

package/docs/callback-page.md

@@ -0,0 +1,24 @@
+# Callback response page
+
+The HTML the browser renders after Keycloak redirects to the loopback URL, produced by `src/oauth/renderHtml.ts`.
+
+## Approach
+
+Visually match Deque's billing-service frontend (palette, typography, centered layout) so developers recognise the page as Deque-owned, but ship no external assets — everything is inline. The logo lives at `assets/logo.png` and is embedded as a base64 data URI via the generated `src/oauth/logo.generated.ts`; regenerate with `node scripts/encode-logo.js` after replacing the PNG.
+
+## Security considerations
+
+**No external stylesheets or images.** billing-service pulls Roboto from Google Fonts. The callback page deliberately does not. Loading any external resource from `http://127.0.0.1:<port>/callback?code=...&state=...` causes the browser to send a `Referer` header containing the full callback URL — leaking the auth code to the third-party origin. A `<meta name="referrer" content="no-referrer">` would suppress the header, but relying on it is brittle; avoiding external references entirely is defense in depth. The `Roboto → Helvetica → Arial` fallback renders indistinguishably on developer machines.
+
+**Content Security Policy.** Every response sets:
+
+```
+Content-Security-Policy: default-src 'none'; img-src data:; style-src 'sha256-<digest>'
+X-Content-Type-Options: nosniff
+```
+
+`default-src 'none'` blocks everything by default. `img-src data:` allows only the inlined logo. `style-src 'sha256-...'` allows only a `<style>` block whose contents match a digest computed at module load — stricter than `'unsafe-inline'`, and any drift between the rendered CSS and the committed hash causes the browser to refuse the stylesheet. Inline `style=""` attributes are avoided entirely (they require separate `style-src-attr` / `'unsafe-hashes'` machinery). The `renderHtml` test suite asserts the hash matches the rendered `<style>` contents to prevent silent drift.
+
+**Auth code not echoed.** The success page deliberately does not render the received `code` in the HTML (RFC 8252 §8.1 interception mitigation).
+
+**XSS escape.** The only untrusted input rendered into the page is `error_description` from the IdP. It is HTML-escaped before interpolation; a regression test feeds `<script>alert(1)</script>` and asserts the escaped form.

package/docs/callback-server.md

@@ -0,0 +1,21 @@
+# Callback server
+
+The loopback HTTP listener that receives the OAuth authorization code redirect, per [RFC 8252 §7.3](https://datatracker.ietf.org/doc/html/rfc8252#section-7.3). Lives in `src/oauth/callbackServer.ts`; the public surface is defined by the module's exported types.
+
+## Loopback bind
+
+RFC 8252 §7.3 says clients SHOULD NOT assume a particular IP version is available and RECOMMENDS trying both. Implementation: bind `127.0.0.1` on an ephemeral port; on `EAFNOSUPPORT` / `EADDRNOTAVAIL` (no IPv4 loopback configured on this host) fall back to `[::1]` on a fresh ephemeral port. The returned `redirectUri` uses whichever literal actually got bound, so the browser connects to exactly what the authorization server redirects it to — no reliance on `localhost` DNS resolution.
+
+Request handling additionally rejects non-loopback `remoteAddress` values with `403` as defense in depth against DNS-rebinding-style pivots — the listener only binds to a loopback interface, but enforcing it at the handler costs nothing.
+
+## RFC 8252 conformance
+
+| Clause | Requirement                                | Handled by                                                                                                 |
+| ------ | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
+| §7.3   | IP literal, not `localhost`                | Binds `127.0.0.1` or `[::1]`; redirect URI uses the literal.                                               |
+| §7.3   | Ephemeral OS-assigned port                 | `listen(0, ...)`; port read from `listening` event.                                                        |
+| §7.3   | Attempt both IPv4 and IPv6                 | IPv4-first, IPv6 fallback when the IPv4 family is unavailable.                                             |
+| §8.3   | Open the port only during the auth request | One-shot: closed on first consuming request, timeout, or abort.                                            |
+| §8.3   | Listen on loopback only                    | IP literal only; `remoteAddress` check as defense in depth.                                                |
+| §8.1   | PKCE                                       | Out of scope — owned by the auth-URL + token-exchange layer.                                               |
+| §8.1   | Auth code interception mitigation          | Success HTML does not echo `code`; CSP locks the page down (see [`callback-page.md`](./callback-page.md)). |

package/docs/oauth-flow.md

@@ -0,0 +1,15 @@
+# OAuth flow — context
+
+`@deque/axe-auth` is the native half of a browser-based OAuth 2.0 Authorization Code + PKCE flow for enterprise customers whose security policies prohibit static API keys. The MCP server itself runs in Docker with no display or interactive terminal, so per [RFC 8252 §7.3](https://datatracker.ietf.org/doc/html/rfc8252#section-7.3) authentication is delegated to this CLI on the developer's host — it opens a browser, receives the redirect on a loopback port, exchanges the code for tokens, and stores a refresh token in the system keychain. The container reads access tokens from the CLI via an environment variable.
+
+## Scope of this module
+
+This package currently implements only the loopback listener and its response page (internal issue #418). PKCE, auth URL construction, browser launch, token exchange, and keychain storage are owned by sibling issues under internal epic #410.
+
+See [`callback-server.md`](./callback-server.md) for the listener API and [`callback-page.md`](./callback-page.md) for the HTML response.
+
+## References
+
+- [RFC 8252 — OAuth 2.0 for Native Apps](https://datatracker.ietf.org/doc/html/rfc8252)
+- [RFC 7636 — PKCE](https://datatracker.ietf.org/doc/html/rfc7636)
+- Internal epic #410

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deque/axe-auth",
-  "version": "1.1.0-next.fb07beab",
+  "version": "1.1.0-next.fea0aa8a",
   "description": "CLI authentication utility for Deque services",
   "license": "SEE LICENSE IN LICENSE",
   "type": "commonjs",
@@ -11,7 +11,9 @@
   },
   "files": [
     "dist",
-    "!dist/**/*.test.*"
+    "!dist/**/*.test.*",
+    "docs",
+    "credits.json"
   ],
   "publishConfig": {
     "access": "public",
@@ -20,15 +22,27 @@
   "engines": {
     "node": ">=22.13.0"
   },
+  "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"
+    "typescript": "^6.0.3"
   },
   "scripts": {
     "build": "tsc",
-    "test": "tsx --test 'src/**/*.test.ts'",
-    "coverage": "c8 pnpm test"
+    "test": "tsx --test \"src/**/*.test.ts\"",
+    "coverage": "c8 pnpm test",
+    "register-dev-client": "tsx scripts/registerDevClient.ts",
+    "smoke-authorize": "tsx scripts/smokeAuthorize.ts",
+    "smoke-cli": "tsx scripts/smokeCLI.ts",
+    "manual-authorize": "tsx scripts/manualAuthorize.ts"
   }
 }