@deque/axe-auth 1.4.0 → 1.5.0-next.7a5a136d

package/docs/architecture.md

@@ -15,6 +15,7 @@ flowchart TB
   keychain[(OS keychain)]
   axe[axe server]
   keycloak[Customer Keycloak]
+  mcp[axe MCP server]
 
   user -- "axe-auth login / token / logout" --> cli
   cli -- "GET /api/sso-config (login only)" --> axe
@@ -27,19 +28,21 @@ flowchart TB
   cli <-- "OIDC discovery, token exchange,<br/>refresh, revoke (HTTPS)" --> keycloak
   cli <-- "tokens + issuer/client/walnutURL<br/>(versioned blob)" --> keychain
   cli -- "access token (stdout)" --> user
+  cli -- "axe-auth run: spawn + supervise,<br/>access-token push (loopback POST /token)" --> mcp
 ```
 
 **Components and their roles:**
 
-1. **Developer**: invokes `axe-auth login`, `axe-auth token`, or `axe-auth logout` on their host machine.
+1. **Developer**: invokes `axe-auth login`, `axe-auth token`, or `axe-auth logout` on their host machine. `axe-auth run` is not typed directly; the developer configures it as their MCP client's server command, and the client spawns the CLI over stdio (see [`axe-auth run`](#axe-auth-run) below).
 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.
+8. **axe MCP server**: the server that `axe-auth run` launches and supervises. It receives freshly-minted access tokens pushed over loopback (`POST /token`) so a long session survives token expiry without a restart. Present only in the `run` flow, not in `login`/`token`/`logout`.
 
-`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 ...`.
+`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 ...`. The one exception is `axe-auth run`, which supervises a running axe MCP server and pushes freshly-minted access tokens to it over a loopback (`127.0.0.1`) connection so a long session survives token expiry without a restart; it never sends the refresh token, only short-lived access tokens.
 
 ## Data flow per verb
 
@@ -119,6 +122,64 @@ sequenceDiagram
 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 run`
+
+```mermaid
+sequenceDiagram
+  participant User as Developer
+  participant Client as MCP client
+  participant CLI as axe-auth run
+  participant KC as Customer Keycloak
+  participant Server as axe MCP server
+
+  User->>Client: set axe-auth run as the stdio server command
+  Client->>CLI: spawn (stdio)
+  alt --port or AXE_TOKEN_REFRESH_PORT pinned
+    Note over CLI: use it as given (required for a container runtime)
+  else nothing pinned
+    Note over CLI: take a free loopback port from the OS,<br/>so a leftover server cannot collide
+  end
+  Note over CLI: mint initial access token (refresh via Keycloak if near expiry)
+  opt token near expiry
+    CLI->>KC: POST /token (refresh_token)
+    KC-->>CLI: { access_token, expires_in }
+  end
+  CLI->>Server: spawn child (AXE_ACCESS_TOKEN, refresh port + secret injected)
+  Client->>CLI: MCP JSON-RPC (stdin)
+  CLI->>Server: bridged stdin
+  Server->>CLI: bridged stdout
+  CLI->>Client: MCP JSON-RPC (stdout)
+  loop each interval, before expiry
+    CLI->>KC: POST /token (refresh_token)
+    KC-->>CLI: { access_token }
+    CLI->>Server: POST /token (x-refresh-secret) — swap in-memory token
+  end
+  alt wrapped server exits on its own
+    Server-->>CLI: child exits
+    CLI-->>Client: exit with the child's code
+  else session ends (stdin EOF, forwarded signal, launcher gone, or fatal startup abort)
+    CLI->>Server: polite rung — forwarded signal or SIGTERM across the process group, or a closed stdin on Windows
+    opt still alive after the grace period
+      CLI->>Server: SIGKILL (process group, or taskkill /T /F on Windows)
+    end
+    Server-->>CLI: child exits
+  end
+```
+
+1. The developer points their MCP client at `axe-auth run -- <server launch command>` as the stdio server command. A free loopback refresh port is taken from the OS per session, so a server left behind by an earlier session cannot collide with it; `--port` or `AXE_TOKEN_REFRESH_PORT` pins one instead. A container only reaches a host port it was told to publish with `-p`, so `run` refuses to guess one when it recognises the wrapped command as `docker`, `podman`, or `nerdctl`. Detection is by command name, so another runtime, or one reached through a wrapper script, takes an auto-selected port it cannot reach and degrades to no token refresh; pin a port yourself there.
+2. `run` obtains a currently-valid access token (exactly as `axe-auth token` does, refreshing against Keycloak if needed), generates a shared secret unless one is provided, and launches the wrapped server as a child process with the token, port, and secret injected into its environment.
+3. `run` transparently bridges the client's stdio to the child so the MCP session flows through untouched, and supervises the child for the session's lifetime.
+4. In the background, `run` keeps the access token fresh and pushes each new token to the server's loopback listener at `http://127.0.0.1:<port>/token` (secret in an `x-refresh-secret` header). The refresh token is never sent; only short-lived access tokens.
+5. When the wrapped server exits on its own, `run` exits with the same code.
+6. `run` also ends the session itself, so the server cannot outlive it holding the refresh port: on stdin EOF, on a forwarded `SIGINT`/`SIGTERM`/`SIGHUP`, when the launching process disappears, and on a fatal error. Each puts the child on a teardown ladder: a polite rung the server can shut down on, then a forced one. On macOS and Linux that is the forwarded signal (or `SIGTERM`), then `SIGKILL` across the process group. Windows has no polite signal, so the closed stdin pipe is the polite rung and the forced one is `taskkill /T /F` across the process tree. The wrapped server separately ends the session when the client stops answering `ping`, which catches a client that never closed the pipe.
+
+#### Known limitations
+
+Two cases are bounded rather than closed.
+
+- **A container can outlive an ungraceful teardown.** When the wrapped command is a container runtime, `axe-auth` supervises the client, not the container, so the polite rung is forwarded to the container but `SIGKILL` reaches only the client. A server that does not stop within the grace therefore leaves the container running on the port it published, which the next session cannot reuse. Recover with `docker rm -f <container>`. Pinning a port is already required here, so the collision is not silent. Tracked in [#1027](https://github.com/dequelabs/axe-mcp-server/issues/1027).
+- **A browser can outlive an ungraceful teardown.** On POSIX the final `SIGKILL` reaches the server's process group, but Playwright runs Chromium in its own, so a scan still mid-flight when the grace expires leaves a browser for the user to close by hand. It holds no port, so it does not block the next session. Windows is unaffected: the forced rung there walks the whole process tree.
+
 ### `axe-auth logout`
 
 ```mermaid

package/docs/callback-server.md

@@ -10,12 +10,12 @@ Request handling additionally rejects non-loopback `remoteAddress` values with `
 
 ## 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)). |
+| 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deque/axe-auth",
-  "version": "1.4.0",
+  "version": "1.5.0-next.7a5a136d",
   "description": "CLI authentication utility for Deque services",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {
@@ -31,15 +31,17 @@
   },
   "dependencies": {
     "@napi-rs/keyring": "^1.3.0",
+    "cross-spawn": "^7.0.6",
     "remove-trailing-slash": "^0.1.1",
     "shlex": "^3.0.0",
     "ts-dedent": "^2.2.0"
   },
   "devDependencies": {
-    "@hono/node-server": "^1.19.14",
+    "@hono/node-server": "^2.1.0",
+    "@types/cross-spawn": "^6.0.6",
     "@types/node": "^24.13.2",
-    "c8": "^11.0.0",
-    "hono": "^4.12.27",
+    "c8": "^12.0.0",
+    "hono": "^4.12.34",
     "tsx": "^4.22.4",
     "typescript": "^6.0.3"
   },