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

package/README.md

@@ -22,11 +22,12 @@ axe-auth <command> [options]
 
 Commands:
 
-| Command  | Description                                                                     |
-| -------- | ------------------------------------------------------------------------------- |
-| `login`  | Open a browser, complete the OAuth flow, persist tokens to the OS keychain.     |
+| Command | Description |
+| --- | --- |
+| `login` | Open a browser, complete the OAuth flow, persist tokens to the OS keychain. |
 | `logout` | Revoke the stored refresh token server-side and clear the local keychain entry. |
-| `token`  | Print a currently-valid access token to stdout, refreshing silently if needed.  |
+| `token` | Print a currently-valid access token to stdout, refreshing silently if needed. |
+| `run` | Launch and supervise the axe MCP server, keeping its OAuth token fresh with no restart. |
 
 Run `axe-auth <command> --help` for command-specific options.
 
@@ -34,11 +35,11 @@ Run `axe-auth <command> --help` for command-specific options.
 
 `axe-auth` discovers its OAuth coordinates by calling `<server>/api/sso-config` on the axe server. Users only supply (or default to) the axe server URL — never the underlying Keycloak URL, realm, or client ID.
 
-| Flag                         | Env var          | Notes                                                                                                                                                                                                            |
-| ---------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--server`                   | `AXE_SERVER_URL` | axe server URL. Defaults to `https://axe.deque.com` (SaaS prod) when neither flag nor env var is set, so SaaS users pass no flags at all. Customers on other deployments override with their own axe server URL. |
-| `--allow-insecure-issuer`    | —                | Permit non-loopback http URLs (default is https only; loopback http is always allowed). Applies to `login` only; `token` and `logout` use the policy persisted at login.                                         |
-| `--no-allow-insecure-issuer` | —                | Force `allowInsecureIssuer=false` for the new `login` (and the entry it persists). Mutually exclusive with `--allow-insecure-issuer`. `token` and `logout` ignore this flag.                                     |
+| Flag | Env var | Notes |
+| --- | --- | --- |
+| `--server` | `AXE_SERVER_URL` | axe server URL. Defaults to `https://axe.deque.com` (SaaS prod) when neither flag nor env var is set, so SaaS users pass no flags at all. Customers on other deployments override with their own axe server URL. |
+| `--allow-insecure-issuer` | — | Permit non-loopback http URLs (default is https only; loopback http is always allowed). Applies to `login` only; `token` and `logout` use the policy persisted at login. |
+| `--no-allow-insecure-issuer` | — | Force `allowInsecureIssuer=false` for the new `login` (and the entry it persists). Mutually exclusive with `--allow-insecure-issuer`. `token` and `logout` ignore this flag. |
 
 `axe-auth` stores one set of credentials per machine. On a successful `login`, the discovered issuer / client / insecure-issuer values are persisted alongside the tokens, so subsequent `axe-auth token` and `axe-auth logout` invocations work flag-free — a typical scripted call is just `$(axe-auth token)`.
 
@@ -46,12 +47,12 @@ There is no concurrent multi-issuer support. Logging in to a second deployment o
 
 ### Exit codes
 
-| Code | Meaning                                                                                                                                                                                                                                                              |
-| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `0`  | Success.                                                                                                                                                                                                                                                             |
-| `1`  | Not authenticated: `axe-auth token` with no stored credentials, or stored credentials are unusable (corrupt, version-mismatch, expired without a usable refresh token, or refresh rejected by the server). Branch on this in scripts that need to trigger a `login`. |
-| `2`  | Usage or runtime error: unknown command, bad flag, missing required configuration, OAuth flow failure, or keychain failure. Details written to stderr.                                                                                                               |
-| `3`  | Cancelled: `axe-auth login` declined at the re-authentication prompt. Distinct from `1` so scripts can tell "needs login" from "user bailed."                                                                                                                        |
+| Code | Meaning |
+| --- | --- |
+| `0` | Success. |
+| `1` | Not authenticated: `axe-auth token` with no stored credentials, or stored credentials are unusable (corrupt, version-mismatch, expired without a usable refresh token, or refresh rejected by the server). Branch on this in scripts that need to trigger a `login`. |
+| `2` | Usage or runtime error: unknown command, bad flag, missing required configuration, OAuth flow failure, or keychain failure. Details written to stderr. |
+| `3` | Cancelled: `axe-auth login` declined at the re-authentication prompt. Distinct from `1` so scripts can tell "needs login" from "user bailed." |
 
 ### Examples
 
@@ -69,6 +70,33 @@ docker run -e AXE_ACCESS_TOKEN="$(axe-auth token)" axe-mcp-server
 axe-auth logout
 ```
 
+### Long-running sessions
+
+Access tokens are short-lived, so a session that outlives the token's TTL (an agent driving the MCP server for hours, say) would otherwise start seeing auth failures. `axe-auth run` handles this automatically: it launches and supervises the server, then keeps its access token fresh for the whole session with no restart and no manual step. Point your MCP client at `axe-auth run` as the server command; it manages the server process's lifetime like any stdio server. It also shuts the server down when the session ends: on stdin close, on a termination signal, and when the launching process disappears. The server itself exits when the client stops answering its liveness probes. Each session takes a fresh refresh port from the OS unless you pin one with `--port` or `AXE_TOKEN_REFRESH_PORT`, so a server left behind by an earlier session cannot hold the port this one needs. Pin one for containers, which only reach a port you publish: `run` detects `docker`, `podman`, and `nerdctl` and refuses to guess, but any other runtime or a wrapper script is yours to pin. Your refresh token never leaves the machine; only short-lived access tokens are sent to the server.
+
+The server just needs token refresh enabled on a port; `run` supplies the token and secret. Under Docker, publish the port on host loopback, forward the auth vars, and bind the listener to `0.0.0.0` inside the container so the published port can reach it:
+
+```sh
+AXE_TOKEN_REFRESH_PORT=9223 npx @deque/axe-auth run -- \
+  docker run -i --rm \
+    -p 127.0.0.1:9223:9223 \
+    -e AXE_ACCESS_TOKEN \
+    -e AXE_TOKEN_REFRESH_PORT \
+    -e AXE_TOKEN_REFRESH_SECRET \
+    -e AXE_TOKEN_REFRESH_HOST=0.0.0.0 \
+    dequesystems/axe-mcp-server
+```
+
+`AXE_TOKEN_REFRESH_HOST=0.0.0.0` is required under Docker: a published port forwards to the container's network interface, not its loopback, so the default loopback bind would be unreachable. The `-p 127.0.0.1:9223:9223` publish keeps the endpoint off the host's external interfaces, and the shared secret — not container isolation — is what guards the endpoint itself.
+
+Under npm the wrapped process inherits the values directly and the listener stays on loopback:
+
+```sh
+npx @deque/axe-auth run -- npx axe-mcp-server
+```
+
+`run` picks a free loopback port per session; pin one with `AXE_TOKEN_REFRESH_PORT` or `--port` only for containers, which can reach only a port you publish. `run` generates the shared secret unless you pin one with `AXE_TOKEN_REFRESH_SECRET` / `--secret`. The secret authenticates the push; the server's listener binds loopback by default and never starts without a secret.
+
 ## Architecture
 
 See [`docs/architecture.md`](./docs/architecture.md) for the system architecture: components, per-verb data flow, communication security, and persisted data.

package/credits.json

@@ -16,6 +16,30 @@
     "licenseText": "# `@napi-rs/keyring-linux-x64-gnu`\n\nThis is the **x86_64-unknown-linux-gnu** binary for `@napi-rs/keyring`\n",
     "licenseFile": "/home/runner/work/axe-mcp-server/axe-mcp-server/node_modules/.pnpm/@napi-rs+keyring-linux-x64-gnu@1.3.0/node_modules/@napi-rs/keyring-linux-x64-gnu/README.md"
   },
+  "cross-spawn@7.0.6": {
+    "name": "cross-spawn",
+    "version": "7.0.6",
+    "licenses": "MIT",
+    "path": "/home/runner/work/axe-mcp-server/axe-mcp-server/node_modules/.pnpm/cross-spawn@7.0.6/node_modules/cross-spawn",
+    "licenseText": "The MIT License (MIT)\n\nCopyright (c) 2018 Made With MOXY Lda <hello@moxy.studio>\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN\nTHE SOFTWARE.\n",
+    "licenseFile": "/home/runner/work/axe-mcp-server/axe-mcp-server/node_modules/.pnpm/cross-spawn@7.0.6/node_modules/cross-spawn/LICENSE",
+    "repository": "https://github.com/moxystudio/node-cross-spawn",
+    "publisher": "André Cruz",
+    "email": "andre@moxy.studio",
+    "copyright": "Copyright (c) 2018 Made With MOXY Lda <hello@moxy.studio>"
+  },
+  "path-key@3.1.1": {
+    "name": "path-key",
+    "version": "3.1.1",
+    "licenses": "MIT",
+    "path": "/home/runner/work/axe-mcp-server/axe-mcp-server/node_modules/.pnpm/path-key@3.1.1/node_modules/path-key",
+    "licenseText": "MIT License\n\nCopyright (c) Sindre Sorhus <sindresorhus@gmail.com> (sindresorhus.com)\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n",
+    "licenseFile": "/home/runner/work/axe-mcp-server/axe-mcp-server/node_modules/.pnpm/path-key@3.1.1/node_modules/path-key/license",
+    "publisher": "Sindre Sorhus",
+    "email": "sindresorhus@gmail.com",
+    "url": "sindresorhus.com",
+    "copyright": "Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (sindresorhus.com)"
+  },
   "remove-trailing-slash@0.1.1": {
     "name": "remove-trailing-slash",
     "version": "0.1.1",
@@ -27,6 +51,30 @@
     "publisher": "Stephen Mathieson",
     "email": "me@stephenmathieson.com"
   },
+  "shebang-command@2.0.0": {
+    "name": "shebang-command",
+    "version": "2.0.0",
+    "licenses": "MIT",
+    "path": "/home/runner/work/axe-mcp-server/axe-mcp-server/node_modules/.pnpm/shebang-command@2.0.0/node_modules/shebang-command",
+    "licenseText": "MIT License\n\nCopyright (c) Kevin Mårtensson <kevinmartensson@gmail.com> (github.com/kevva)\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n",
+    "licenseFile": "/home/runner/work/axe-mcp-server/axe-mcp-server/node_modules/.pnpm/shebang-command@2.0.0/node_modules/shebang-command/license",
+    "publisher": "Kevin Mårtensson",
+    "email": "kevinmartensson@gmail.com",
+    "url": "github.com/kevva",
+    "copyright": "Copyright (c) Kevin Mårtensson <kevinmartensson@gmail.com> (github.com/kevva)"
+  },
+  "shebang-regex@3.0.0": {
+    "name": "shebang-regex",
+    "version": "3.0.0",
+    "licenses": "MIT",
+    "path": "/home/runner/work/axe-mcp-server/axe-mcp-server/node_modules/.pnpm/shebang-regex@3.0.0/node_modules/shebang-regex",
+    "licenseText": "MIT License\n\nCopyright (c) Sindre Sorhus <sindresorhus@gmail.com> (sindresorhus.com)\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n",
+    "licenseFile": "/home/runner/work/axe-mcp-server/axe-mcp-server/node_modules/.pnpm/shebang-regex@3.0.0/node_modules/shebang-regex/license",
+    "publisher": "Sindre Sorhus",
+    "email": "sindresorhus@gmail.com",
+    "url": "sindresorhus.com",
+    "copyright": "Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (sindresorhus.com)"
+  },
   "shlex@3.0.0": {
     "name": "shlex",
     "version": "3.0.0",
@@ -49,5 +97,31 @@
     "publisher": "Tamino Martinius",
     "email": "dev@zaku.eu",
     "copyright": "Copyright (c) 2018 Tamino Martinius"
+  },
+  "isexe@2.0.0": {
+    "name": "isexe",
+    "version": "2.0.0",
+    "licenses": "ISC",
+    "path": "/home/runner/work/axe-mcp-server/axe-mcp-server/node_modules/.pnpm/isexe@2.0.0/node_modules/isexe",
+    "licenseText": "The ISC License\n\nCopyright (c) Isaac Z. Schlueter and Contributors\n\nPermission to use, copy, modify, and/or distribute this software for any\npurpose with or without fee is hereby granted, provided that the above\ncopyright notice and this permission notice appear in all copies.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\" AND THE AUTHOR DISCLAIMS ALL WARRANTIES\nWITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF\nMERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR\nANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES\nWHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN\nACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR\nIN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.\n",
+    "licenseFile": "/home/runner/work/axe-mcp-server/axe-mcp-server/node_modules/.pnpm/isexe@2.0.0/node_modules/isexe/LICENSE",
+    "repository": "https://github.com/isaacs/isexe",
+    "publisher": "Isaac Z. Schlueter",
+    "email": "i@izs.me",
+    "url": "http://blog.izs.me/",
+    "copyright": "Copyright (c) Isaac Z. Schlueter and Contributors"
+  },
+  "which@2.0.2": {
+    "name": "which",
+    "version": "2.0.2",
+    "licenses": "ISC",
+    "path": "/home/runner/work/axe-mcp-server/axe-mcp-server/node_modules/.pnpm/which@2.0.2/node_modules/which",
+    "licenseText": "The ISC License\n\nCopyright (c) Isaac Z. Schlueter and Contributors\n\nPermission to use, copy, modify, and/or distribute this software for any\npurpose with or without fee is hereby granted, provided that the above\ncopyright notice and this permission notice appear in all copies.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\" AND THE AUTHOR DISCLAIMS ALL WARRANTIES\nWITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF\nMERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR\nANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES\nWHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN\nACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR\nIN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.\n",
+    "licenseFile": "/home/runner/work/axe-mcp-server/axe-mcp-server/node_modules/.pnpm/which@2.0.2/node_modules/which/LICENSE",
+    "repository": "https://github.com/isaacs/node-which",
+    "publisher": "Isaac Z. Schlueter",
+    "email": "i@izs.me",
+    "url": "http://blog.izs.me",
+    "copyright": "Copyright (c) Isaac Z. Schlueter and Contributors"
   }
 }

package/dist/cli/errors.d.ts

@@ -1,5 +1,5 @@
 /** Discriminator for `CLIError`, used by tests and the dispatcher. */
-export type CLIErrorCode = "NOT_AUTHENTICATED" | "USER_CANCELLED" | "ALREADY_AUTHENTICATED" | "OAUTH_FAILED" | "KEYCHAIN_FAILURE";
+export type CLIErrorCode = "NOT_AUTHENTICATED" | "USER_CANCELLED" | "ALREADY_AUTHENTICATED" | "OAUTH_FAILED" | "KEYCHAIN_FAILURE" | "REFRESH_UNREACHABLE";
 /**
  * Thrown from a verb's `run` to signal a known failure. The
  * dispatcher writes `message` to stderr and exits with `exitCode`.

package/dist/cli/errors.js

@@ -8,6 +8,7 @@ const EXIT_CODE_BY_ERROR_CODE = {
     ALREADY_AUTHENTICATED: 2,
     OAUTH_FAILED: 2,
     KEYCHAIN_FAILURE: 2,
+    REFRESH_UNREACHABLE: 2,
 };
 /**
  * Thrown from a verb's `run` to signal a known failure. The

package/dist/commands/run.d.ts

@@ -0,0 +1,16 @@
+import defaultRunSession from "../run/runSession";
+import type { CommandDeps } from "../cli/types";
+/** Extra dependencies `run` needs beyond the shared CLI deps. */
+export interface RunDeps extends CommandDeps {
+    /** Environment source. Defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** Override the session supervisor (tests). */
+    runSession?: typeof defaultRunSession;
+}
+/**
+ * `axe-auth run [--port] [--secret] -- <command> [args...]`. Unlike the other
+ * verbs, everything after `--` is the wrapped server command, so this bypasses
+ * the shared flag-only dispatch and parses its own portion. Returns the exit
+ * code to hand to the process.
+ */
+export declare function dispatchRun(rest: string[], deps: RunDeps): Promise<number>;

package/dist/commands/run.help.d.ts

@@ -0,0 +1,2 @@
+/** Help text for `axe-auth run --help`. */
+export declare const HELP_RUN = "npx @deque/axe-auth run -- <server launch command>\n\nLaunch and supervise the axe MCP server so it keeps a valid OAuth access\ntoken for the whole session, refreshing before expiry without a restart. Use\nthis as your MCP client's server command; the client manages its lifetime like\nany stdio server. Everything after `--` is the command it launches.\n\nUsage:\n  npx @deque/axe-auth run [--port <port>] [--secret <secret>] -- <command> [args...]\n\n  The wrapped server must be started with token refresh on a loopback port.\n  Under Docker, publish it with `-p 127.0.0.1:<port>:<port>`, forward the auth\n  vars with `-e AXE_ACCESS_TOKEN -e AXE_TOKEN_REFRESH_PORT -e AXE_TOKEN_REFRESH_SECRET`,\n  and set `-e AXE_TOKEN_REFRESH_HOST=0.0.0.0` so the published port can reach the\n  listener; `run` supplies the token/port/secret values. Under npm the wrapped\n  node process inherits them directly.\n\nOptions:\n  --port <port>      Loopback port the server's refresh listener uses.\n                     Defaults to AXE_TOKEN_REFRESH_PORT, otherwise a free\n                     port chosen per session. Pin one for a container,\n                     which can only reach a published port: docker,\n                     podman, and nerdctl are detected and refused\n                     without it; pin it yourself for anything else.\n  --secret <secret>  Shared secret for the refresh channel. Defaults to\n                     AXE_TOKEN_REFRESH_SECRET, otherwise a generated one.\n                     Prefer the env var: a value passed here is visible to other\n                     local users via the process list.\n  -h, --help         Show this help.\n\nExit codes:\n  0    The wrapped server exited normally.\n  1    Not authenticated; run `npx @deque/axe-auth login` first.\n  2    Configuration or connectivity error (an invalid port, a container\n       command with no port pinned, no command after `--`, or a pinned\n       refresh port the server could not be reached on).\n  <n>  Otherwise, the wrapped server's own exit code.";

package/dist/commands/run.help.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HELP_RUN = void 0;
+/** Help text for `axe-auth run --help`. */
+exports.HELP_RUN = `npx @deque/axe-auth run -- <server launch command>
+
+Launch and supervise the axe MCP server so it keeps a valid OAuth access
+token for the whole session, refreshing before expiry without a restart. Use
+this as your MCP client's server command; the client manages its lifetime like
+any stdio server. Everything after \`--\` is the command it launches.
+
+Usage:
+  npx @deque/axe-auth run [--port <port>] [--secret <secret>] -- <command> [args...]
+
+  The wrapped server must be started with token refresh on a loopback port.
+  Under Docker, publish it with \`-p 127.0.0.1:<port>:<port>\`, forward the auth
+  vars with \`-e AXE_ACCESS_TOKEN -e AXE_TOKEN_REFRESH_PORT -e AXE_TOKEN_REFRESH_SECRET\`,
+  and set \`-e AXE_TOKEN_REFRESH_HOST=0.0.0.0\` so the published port can reach the
+  listener; \`run\` supplies the token/port/secret values. Under npm the wrapped
+  node process inherits them directly.
+
+Options:
+  --port <port>      Loopback port the server's refresh listener uses.
+                     Defaults to AXE_TOKEN_REFRESH_PORT, otherwise a free
+                     port chosen per session. Pin one for a container,
+                     which can only reach a published port: docker,
+                     podman, and nerdctl are detected and refused
+                     without it; pin it yourself for anything else.
+  --secret <secret>  Shared secret for the refresh channel. Defaults to
+                     AXE_TOKEN_REFRESH_SECRET, otherwise a generated one.
+                     Prefer the env var: a value passed here is visible to other
+                     local users via the process list.
+  -h, --help         Show this help.
+
+Exit codes:
+  0    The wrapped server exited normally.
+  1    Not authenticated; run \`npx @deque/axe-auth login\` first.
+  2    Configuration or connectivity error (an invalid port, a container
+       command with no port pinned, no command after \`--\`, or a pinned
+       refresh port the server could not be reached on).
+  <n>  Otherwise, the wrapped server's own exit code.`;

package/dist/commands/run.js

@@ -0,0 +1,108 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dispatchRun = dispatchRun;
+const node_util_1 = require("node:util");
+const runSession_1 = __importDefault(require("../run/runSession"));
+const findFreePort_1 = __importDefault(require("../run/findFreePort"));
+const run_help_1 = require("./run.help");
+const errors_1 = require("../cli/errors");
+/** Container runtimes whose child cannot reach a host port it was not told to publish. */
+const CONTAINER_COMMANDS = new Set(["docker", "podman", "nerdctl"]);
+/** Whether `command` launches a container runtime rather than a local process. */
+function isContainerCommand(command) {
+    if (!command) {
+        return false;
+    }
+    const name = command.split(/[/\\]/).pop() ?? command;
+    return CONTAINER_COMMANDS.has(name.replace(/\.exe$/i, "").toLowerCase());
+}
+/**
+ * `axe-auth run [--port] [--secret] -- <command> [args...]`. Unlike the other
+ * verbs, everything after `--` is the wrapped server command, so this bypasses
+ * the shared flag-only dispatch and parses its own portion. Returns the exit
+ * code to hand to the process.
+ */
+async function dispatchRun(rest, deps) {
+    const env = deps.env ?? process.env;
+    // Split on the first `--`: our flags precede it, the wrapped command follows.
+    const separator = rest.indexOf("--");
+    const own = separator === -1 ? rest : rest.slice(0, separator);
+    const childArgv = separator === -1 ? [] : rest.slice(separator + 1);
+    let values;
+    try {
+        values = (0, node_util_1.parseArgs)({
+            args: own,
+            options: {
+                port: { type: "string" },
+                secret: { type: "string" },
+                help: { type: "boolean", short: "h" },
+            },
+            strict: true,
+            allowPositionals: false,
+        }).values;
+    }
+    catch (err) {
+        deps.stderr.write(`${(0, errors_1.describeError)(err)}\n`);
+        return 2;
+    }
+    if (values.help) {
+        deps.stdout.write(`${run_help_1.HELP_RUN}\n`);
+        return 0;
+    }
+    if (childArgv.length === 0) {
+        deps.stderr.write("axe-auth run needs a command after `--`, e.g. `npx @deque/axe-auth run -- docker run ... axe-mcp-server`\n");
+        return 2;
+    }
+    // No port pinned: take a fresh one, so a leftover server from an earlier
+    // session cannot collide with it (dequelabs/axe-mcp-server#1013).
+    const portRaw = values.port ?? env.AXE_TOKEN_REFRESH_PORT;
+    let port;
+    const portWasAutoSelected = !portRaw;
+    if (portRaw) {
+        port = Number(portRaw);
+        if (!Number.isInteger(port) || port <= 0 || port >= 65536) {
+            deps.stderr.write(`Invalid port ${portRaw}: must be a TCP port (1-65535)\n`);
+            return 2;
+        }
+    }
+    else if (isContainerCommand(childArgv[0])) {
+        // A container only reaches a published port, so an ephemeral one would
+        // never be reachable. Fail now, not at the first refresh push.
+        deps.stderr.write("axe-auth run needs an explicit refresh port when the wrapped command is a container: set AXE_TOKEN_REFRESH_PORT or pass --port, and publish it with `-p 127.0.0.1:<port>:<port>`\n");
+        return 2;
+    }
+    else {
+        port = await (0, findFreePort_1.default)();
+    }
+    // Mirror the server's minimum-length check so a short pinned secret fails
+    // here, at the command the user ran, rather than as a downstream server
+    // startup crash. An unset secret is generated by `runSession`.
+    const secret = values.secret ?? env.AXE_TOKEN_REFRESH_SECRET;
+    if (secret && secret.length < 16) {
+        deps.stderr.write("AXE_TOKEN_REFRESH_SECRET must be at least 16 characters\n");
+        return 2;
+    }
+    const runSession = deps.runSession ?? runSession_1.default;
+    try {
+        return await runSession({
+            command: childArgv[0],
+            commandArgs: childArgv.slice(1),
+            port,
+            portWasAutoSelected,
+            secret,
+            env,
+            stderr: deps.stderr,
+        });
+    }
+    catch (err) {
+        if (err instanceof errors_1.CLIError) {
+            deps.stderr.write(`${err.message}\n`);
+            return err.exitCode;
+        }
+        deps.stderr.write(`${(0, errors_1.describeError)(err)}\n`);
+        return 2;
+    }
+}

package/dist/index.js

@@ -12,6 +12,7 @@ const tokenStore_1 = require("./oauth/tokenStore");
 const login_1 = __importDefault(require("./commands/login"));
 const logout_1 = __importDefault(require("./commands/logout"));
 const token_1 = __importDefault(require("./commands/token"));
+const run_1 = require("./commands/run");
 const errors_1 = require("./cli/errors");
 const safeExit_1 = require("./cli/safeExit");
 const pkg = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(__dirname, "..", "package.json"), "utf-8"));
@@ -20,12 +21,18 @@ const COMMANDS = [
     logout_1.default,
     token_1.default,
 ];
+// `run` has its own dispatch (it takes a `-- <command>` passthrough), so it is
+// not a `CommandSpec`; list it in help by hand.
+const RUN_SUMMARY = "Launch and supervise the axe MCP server, keeping its OAuth token fresh with no restart.";
 function findCommand(verb) {
     return COMMANDS.find((c) => c.name === verb);
 }
 function topLevelHelp() {
-    const width = Math.max(...COMMANDS.map((c) => c.name.length));
-    const verbList = COMMANDS.map((c) => `  ${c.name.padEnd(width)}  ${c.summary}`).join("\n");
+    const width = Math.max(...COMMANDS.map((c) => c.name.length), "run".length);
+    const verbList = [
+        ...COMMANDS.map((c) => `  ${c.name.padEnd(width)}  ${c.summary}`),
+        `  ${"run".padEnd(width)}  ${RUN_SUMMARY}`,
+    ].join("\n");
     return `${pkg.name} v${pkg.version}
 
 ${pkg.description}
@@ -56,6 +63,15 @@ async function dispatch(argv) {
         process.stderr.write(`Unknown option: ${first}. Run \`axe-auth --help\` for usage.\n`);
         return 2;
     }
+    // `run` wraps a launch command after `--`; it can't go through the shared
+    // flag-only parse below.
+    if (first === "run") {
+        return (0, run_1.dispatchRun)(rest, {
+            stdin: process.stdin,
+            stdout: process.stdout,
+            stderr: process.stderr,
+        });
+    }
     const command = findCommand(first);
     if (!command) {
         process.stderr.write(`Unknown command: ${first}. Run \`axe-auth --help\` for usage.\n`);

package/dist/oauth/keyringBinding.d.ts

@@ -19,4 +19,4 @@ export type KeyringEntryFactory = (service: string, account: string) => KeyringE
  * `KEYRING_UNAVAILABLE` on first store construction, not on module
  * import.
  */
-export declare const defaultEntryFactory: KeyringEntryFactory;
+export declare function defaultEntryFactory(service: string, account: string): KeyringEntry;

package/dist/oauth/keyringBinding.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.defaultEntryFactory = void 0;
+exports.defaultEntryFactory = defaultEntryFactory;
 const node_module_1 = require("node:module");
 const errors_1 = require("./errors");
 const requireFromHere = (0, node_module_1.createRequire)(__filename);
@@ -34,8 +34,7 @@ function resolveEntryCtor() {
  * `KEYRING_UNAVAILABLE` on first store construction, not on module
  * import.
  */
-const defaultEntryFactory = (service, account) => {
+function defaultEntryFactory(service, account) {
     const Ctor = resolveEntryCtor();
     return new Ctor(service, account);
-};
-exports.defaultEntryFactory = defaultEntryFactory;
+}

package/dist/run/findFreePort.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Ask the OS for a free loopback port by binding port 0 and releasing it.
+ *
+ * Sessions used to share one fixed port, so a leftover server held it and the
+ * next session lost token refresh (dequelabs/axe-mcp-server#1013). The OS
+ * never hands out a port something is still bound to.
+ *
+ * It is released before the child binds it, so another process could take it
+ * in between. That window is not small: it spans minting a token against
+ * Keycloak and starting the child. Because the port was not the user's
+ * choice, losing it degrades the session to no token refresh rather than
+ * failing it (see `portWasAutoSelected` in `runSession`).
+ *
+ * Nothing proves the listener on that port is our child, so a process that
+ * takes it receives whatever is pushed there. Tracked in #1028.
+ */
+export default function findFreePort(host?: string): Promise<number>;

package/dist/run/findFreePort.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = findFreePort;
+const node_net_1 = require("node:net");
+/**
+ * Ask the OS for a free loopback port by binding port 0 and releasing it.
+ *
+ * Sessions used to share one fixed port, so a leftover server held it and the
+ * next session lost token refresh (dequelabs/axe-mcp-server#1013). The OS
+ * never hands out a port something is still bound to.
+ *
+ * It is released before the child binds it, so another process could take it
+ * in between. That window is not small: it spans minting a token against
+ * Keycloak and starting the child. Because the port was not the user's
+ * choice, losing it degrades the session to no token refresh rather than
+ * failing it (see `portWasAutoSelected` in `runSession`).
+ *
+ * Nothing proves the listener on that port is our child, so a process that
+ * takes it receives whatever is pushed there. Tracked in #1028.
+ */
+async function findFreePort(host = "127.0.0.1") {
+    const probe = (0, node_net_1.createServer)();
+    try {
+        return await new Promise((resolve, reject) => {
+            probe.once("error", reject);
+            probe.listen(0, host, () => {
+                const address = probe.address();
+                if (address === null) {
+                    reject(new Error("could not determine a free port"));
+                    return;
+                }
+                resolve(address.port);
+            });
+        });
+    }
+    finally {
+        await new Promise((resolve) => probe.close(() => resolve()));
+    }
+}

package/dist/run/pushToken.d.ts

@@ -0,0 +1,10 @@
+/** Header carrying the shared secret on a token-refresh push. Matches the server's listener. */
+export declare const REFRESH_SECRET_HEADER = "x-refresh-secret";
+/** Pushes a fresh access token to the running server's loopback listener. */
+export type PushToken = (params: {
+    port: number;
+    secret: string;
+    accessToken: string;
+}) => Promise<void>;
+/** POST the fresh token to the server's loopback refresh listener. */
+export default function pushToken({ port, secret, accessToken, }: Parameters<PushToken>[0]): Promise<void>;

package/dist/run/pushToken.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REFRESH_SECRET_HEADER = void 0;
+exports.default = pushToken;
+/** Header carrying the shared secret on a token-refresh push. Matches the server's listener. */
+exports.REFRESH_SECRET_HEADER = "x-refresh-secret";
+/** Bound the push so a stalled server can't hang the caller. */
+const PUSH_TIMEOUT_MS = 5_000;
+/** How much of a failed push's response body is worth repeating to the user. */
+const MAX_DETAIL_LEN = 200;
+/** POST the fresh token to the server's loopback refresh listener. */
+async function pushToken({ port, secret, accessToken, }) {
+    const res = await fetch(`http://127.0.0.1:${port}/token`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            [exports.REFRESH_SECRET_HEADER]: secret,
+        },
+        body: JSON.stringify({ accessToken }),
+        signal: AbortSignal.timeout(PUSH_TIMEOUT_MS),
+    });
+    if (!res.ok) {
+        // Whatever holds this port wrote the body, and it reaches the client's
+        // stderr, so take a little of it and strip anything that could forge log
+        // lines or redraw the terminal.
+        const detail = await res
+            .text()
+            .then((text) => text
+            .slice(0, MAX_DETAIL_LEN)
+            .replace(/[^\t\x20-\x7e]/g, " ")
+            .trim())
+            .catch(() => "");
+        throw new Error(`server responded ${res.status}${detail ? `: ${detail}` : ""}`);
+    }
+}

package/dist/run/runSession.d.ts

@@ -0,0 +1,62 @@
+import type { Readable, Writable } from "node:stream";
+import { getValidAccessToken } from "../oauth/getValidAccessToken";
+import { type TokenStore } from "../oauth/tokenStore";
+import { type SuperviseOptions } from "./supervise";
+import { type PushToken } from "./pushToken";
+/** Starts a repeating callback and returns a canceller. Injectable so tests drive ticks by hand. */
+export type Scheduler = (intervalMs: number, tick: () => void) => () => void;
+/** Options for {@link runSession}. */
+export interface RunSessionOptions {
+    /** Executable of the wrapped server command (everything after `--`). */
+    command: string;
+    /** Arguments for the wrapped command. */
+    commandArgs: string[];
+    /** Loopback port the server's refresh listener is on. */
+    port: number;
+    /**
+     * Whether the port was chosen by us rather than by the user. An auto-picked
+     * port can lose a race it is not the user's fault to lose, so a first push
+     * that cannot reach it degrades the session instead of failing it.
+     */
+    portWasAutoSelected?: boolean;
+    /** Shared secret authenticating pushes. Generated if omitted. */
+    secret?: string;
+    /** Cadence of the refresh-and-push loop, ms. */
+    refreshIntervalMs?: number;
+    /** Override token minting (tests). */
+    getToken?: typeof getValidAccessToken;
+    /** Override the token store (tests). */
+    tokenStore?: TokenStore;
+    /** Override the push (tests). */
+    push?: PushToken;
+    /** Override the child supervisor (tests). */
+    supervise?: (options: SuperviseOptions) => Promise<number>;
+    /** Override the refresh scheduler (tests). */
+    scheduler?: Scheduler;
+    /** Base environment for the wrapped child. Defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** Forwarded to the supervisor as the child's stdin. Defaults to `process.stdin`. */
+    stdin?: Readable;
+    /** Forwarded to the supervisor as the child's stdout (the MCP channel). Defaults to `process.stdout`. */
+    stdout?: Writable;
+    /** Diagnostics stream. Defaults to `process.stderr`. NEVER stdout (that is the MCP channel). */
+    stderr?: Writable;
+    /** Forwarded to the supervisor's signal registrar (tests). Defaults to `process.on`. */
+    onSignal?: (signal: NodeJS.Signals, handler: () => void) => void;
+}
+/**
+ * Supervise the wrapped server command for a session: mint an initial access
+ * token, inject it plus the refresh secret and port into the child's
+ * environment, and keep the running server's token fresh by refreshing and
+ * pushing before expiry. Resolves with the child's exit code.
+ *
+ * Fails fast with a `NOT_AUTHENTICATED` {@link CLIError} if there are no stored
+ * credentials to mint from, and with `REFRESH_UNREACHABLE` if the very first
+ * push cannot reach the server (almost always a misconfigured port/secret) —
+ * exiting so the MCP client sees the failure rather than letting the session
+ * silently die at expiry. Once a push has succeeded, a later refresh failure is
+ * logged (the server keeps its last good token) rather than tearing the session
+ * down, with one louder diagnostic after {@link CONSECUTIVE_FAILURE_WARNING_THRESHOLD}
+ * consecutive failures.
+ */
+export default function runSession(options: RunSessionOptions): Promise<number>;