@kontextmind/kxm 0.7.133 → 0.7.135

package/.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
       "name": "kxm",
       "source": "./plugins/kxm",
       "description": "Durable workflows, peer agents, and kxm tui",
-      "version": "0.7.133",
+      "version": "0.7.135",
       "category": "development",
       "tags": ["kxm", "multi-agent", "workflows", "mcp"]
     }

package/CHANGELOG.md

@@ -140,6 +140,17 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ### Changed
 
+- **Steel clients authenticate to Authentik with `Authorization: Basic`.**
+  `STEEL_AUTH_BASIC`, or `STEEL_AUTH_USER` and `STEEL_AUTH_TOKEN`, set that
+  header on Steel HTTP requests and on the CDP options from `formatCDPConnect()`.
+  `KXM_BROWSER=steel` passes those headers through `connectBrowserOverCdp()`
+  into `chromium.connectOverCDP`. Obscura stays the default and sends no Steel
+  headers. `STEEL_AUTH_HEADER` overrides the value. The CDP URL omits the credential when
+  those variables are set. A 302 to the identity provider fails closed and does
+  not follow the login redirect. `STEEL_API_KEY` still sends the legacy
+  `x-steel-api-key` header and `apiKey` query parameter for the temporary proxy
+  shim, and warns once. See
+  [Browser automation](docs/guides/browser-automation.md).
 - **Dispatch reads role and model files, and agents bind a role.**
   `scripts/roster-policy.mjs` builds the developer policy from
   `.kxm/models/*.yaml` and `.kxm/roles/*.yaml` at `refs/remotes/origin/main`.

package/docs/adr/ADR-0002-browser-automation-steel-doks.md

@@ -7,7 +7,7 @@ project: "kxm"
 status: "accepted"
 owner: "@operator"
 created: "2026-09-14"
-updated: "2026-09-14"
+updated: "2026-09-27"
 authority: "decision"
 confidence: "verified"
 summary: "Adopt self-hosted Steel on DigitalOcean Kubernetes (DOKS) with agent-browser and Playwright as KXM's primary browser automation infrastructure."
@@ -100,7 +100,8 @@ AI coding agents and orchestration workflows in KXM require browser interaction
 
 - **Verification**: Health endpoint `$STEEL_API_URL/v1/health` verified with HTTP 200 and Let's Encrypt TLS.
 - **Integration Test**: `test/core/browser.test.ts` validates session lifecycle, CDP endpoint formatting, takeover transitions, and secret redaction.
-- **Security Check**: `pass-cli` verified as the authoritative store for `STEEL_API_KEY` in the operators' password manager.
+- **Security Check**: `pass-cli` verified as the authoritative store for Steel credentials in the operators' password manager.
+- **Edge auth (2026-09-27)**: `steel.kontextmind.com` and `steel.theneuro.me`, including the CDP WebSocket, are behind Authentik forward auth. Steel does not check `STEEL_API_KEY`. Clients send `Authorization: Basic`. Unauthenticated requests are redirected to `id.kxmd.dev`. The legacy `x-steel-api-key` header and `apiKey` query parameter remain a temporary proxy shim.
 
 ## Related
 

package/docs/guides/agent-skills.md

@@ -68,7 +68,7 @@ Tools map the same way: peer tools to `kxm-peer`, workflow tools to `kxm-workflo
 
 ## Browser automation skills
 
-Playwright testing and verification use Obscura. The Steel skills cover human takeover, MFA, and the live session viewer. They own no `kxm` command. See [Browser automation](browser-automation.md), [ADR-0005](../adr/ADR-0005-obscura-default-playwright.md), and [ADR-0002](../adr/ADR-0002-browser-automation-steel-doks.md).
+Playwright testing and verification use Obscura ([ADR-0005](../adr/ADR-0005-obscura-default-playwright.md)). The Steel skills cover human takeover, MFA, and the live session viewer. Those hosts sit behind Authentik forward auth: send `Authorization: Basic` (`STEEL_AUTH_BASIC`, or `STEEL_AUTH_USER` and `STEEL_AUTH_TOKEN`) and keep the credential out of URLs. They own no `kxm` command. See [Browser automation](browser-automation.md) and [ADR-0002](../adr/ADR-0002-browser-automation-steel-doks.md).
 
 | Skill | Use it to |
 |---|---|

package/docs/guides/browser-automation.md

@@ -5,9 +5,9 @@ Give agents a real browser without giving them your desktop. Playwright testing
 ## Before you begin
 
 - For Playwright: Node, and `node scripts/obscura.mjs` (it downloads pinned Obscura v0.2.3). [ADR-0005](../adr/ADR-0005-obscura-default-playwright.md) records that default.
-- For takeover: a Steel deployment you operate, reachable over HTTPS, and its API key. [ADR-0002](../adr/ADR-0002-browser-automation-steel-doks.md) describes the reference deployment on Kubernetes.
+- For takeover: a Steel deployment you operate, reachable over HTTPS, and an Authentik app password when that host is behind forward auth. [ADR-0002](../adr/ADR-0002-browser-automation-steel-doks.md) describes the reference deployment on Kubernetes.
 - `curl` and `jq`. Optionally `agent-browser` for exploration. Playwright tests use Obscura; do not run `playwright install`.
-- A secret manager for the API key. The bundled skills use `pass-cli`.
+- A secret manager for the Authentik app password and site credentials. The bundled skills use `pass-cli`.
 - The `kxm-browser-*` skills from the plugin or Pi package. See [Agent skills](agent-skills.md#browser-automation-skills).
 
 ## Components
@@ -18,7 +18,7 @@ Give agents a real browser without giving them your desktop. Playwright testing
 | Steel | Isolated Chromium sessions, a REST API, a CDP WebSocket, and a session viewer for takeover |
 | `agent-browser` | Fast, token-efficient exploration: accessibility snapshots, navigation, DOM inspection |
 | Playwright | Assertions, bug reproductions, visual proof and permanent regression tests |
-| Secret manager | The only place the Steel API key and site credentials live |
+| Secret manager | The only place the Authentik app password and site credentials live |
 | Human operator | Completes MFA, CAPTCHA, SSO or consent in the Steel session viewer |
 
 ## Run Playwright on Obscura
@@ -30,49 +30,60 @@ node scripts/obscura.mjs --ensure
 npm run e2e
 ```
 
-Set `video: "off"` in Playwright. Obscura does not record video. Connect with the worker-scoped `browser` fixture and `chromium.connectOverCDP()`. `chromium.connect` and `use.connectOptions` are not supported.
+Set `video: "off"` in Playwright. Obscura does not record video. Connect with the worker-scoped `browser` fixture and `connectBrowserOverCdp()`. That helper calls `chromium.connectOverCDP()` with no Steel headers unless `KXM_BROWSER=steel`. `chromium.connect` and `use.connectOptions` are not supported.
 
 ## Configure the Steel endpoint
 
 The KXM browser library reads these variables, and the shell procedure below uses the same names so both agree.
 
+KontextMind's Steel hosts (`steel.kontextmind.com` and `steel.theneuro.me`, including the `wss://` CDP endpoint) sit behind Authentik forward auth at the reverse proxy. Steel itself does not check an API key. Unauthenticated requests receive a 302 redirect to the Authentik login at `id.kxmd.dev`. Authentik accepts an app password only as `Authorization: Basic`. A Bearer token is refused.
+
 | Variable | Default | Effect |
 |---|---|---|
 | `STEEL_API_URL` | A KontextMind-operated deployment | Base URL of your Steel API. Always set it |
 | `STEEL_UI_URL` | `$STEEL_API_URL/ui` | Base URL of the session viewer |
-| `STEEL_API_KEY` | A `pass-cli` lookup | The API key. When unset, the library runs a `pass-cli` lookup of a fixed KontextMind vault item |
-| `USE_PASS_CLI` | enabled | Set to `false` to disable that `pass-cli` fallback |
+| `STEEL_AUTH_HEADER` | unset | Full `Authorization` value. Wins over the other auth variables |
+| `STEEL_AUTH_BASIC` | unset | `base64(user:token)`, with or without a leading `Basic` prefix. Sent as `Authorization: Basic` |
+| `STEEL_AUTH_USER` | unset | Authentik username, for example `svc-steel`. Used with `STEEL_AUTH_TOKEN` |
+| `STEEL_AUTH_TOKEN` | unset | Authentik app password. Used with `STEEL_AUTH_USER` |
+| `STEEL_API_KEY` | A `pass-cli` lookup | Deprecated. Sent as `x-steel-api-key` and as `?apiKey=` on the CDP URL, which the proxy still accepts as a temporary shim. The library warns once on stderr |
+| `USE_PASS_CLI` | enabled | Set to `false` to disable the legacy `STEEL_API_KEY` `pass-cli` fallback |
+
+Set one Authentik credential. Precedence is `STEEL_AUTH_HEADER`, then `STEEL_AUTH_BASIC`, then `STEEL_AUTH_USER` together with `STEEL_AUTH_TOKEN`. If only one of the user or token pair is set, configuration fails instead of falling back to the legacy key. When any of those are set, the legacy key is not sent and is not placed in a URL. The `pass-cli` fallback looks up `STEEL_API_KEY` only.
 
 > [!WARNING]
-> Set `STEEL_API_URL` and `STEEL_API_KEY` explicitly. Without them the library falls back to KontextMind's own deployment and vault item, which are not yours to use.
+> Set `STEEL_API_URL` and an Authentik credential explicitly. Without them the library falls back to KontextMind's own deployment and vault item, which are not yours to use. Never put the credential in a URL, a prompt, or a log.
 
 ```bash
 export STEEL_API_URL="https://steel.example.com"
-# Read the key from your secret manager; <vault> and <item> are yours.
-export STEEL_API_KEY="$(pass-cli item view --vault-name '<vault>' --item-title '<item>' --field STEEL_API_KEY)"
+# Read the app password from your secret manager; <vault> and <item> are yours.
+export STEEL_AUTH_USER="svc-steel"
+export STEEL_AUTH_TOKEN="$(pass-cli item view --vault-name '<vault>' --item-title '<item>' --field password)"
 export USE_PASS_CLI=false
 ```
 
+`STEEL_AUTH_BASIC` is the same pair already encoded: `printf '%s:%s' "$STEEL_AUTH_USER" "$STEEL_AUTH_TOKEN" | base64 | tr -d '\n'`. Prefer the user and token pair, or the pre-encoded value, and keep them in the environment of the process that calls Steel.
+
 | Endpoint | Purpose |
 |---|---|
 | `POST /v1/sessions` | Create a session; body `{"timeout": <ms>}` |
 | `GET /v1/sessions/<id>` | Inspect one session; `GET /v1/sessions` lists them all |
 | `POST /v1/sessions/<id>/release` | Release a session |
 | `POST /v1/scrape`, `POST /v1/screenshot` | One-shot page fetch or screenshot without a session |
-| `wss://<steel-host>/v1/devtools?sessionId=<id>&apiKey=<key>` | CDP endpoint for `agent-browser` and Playwright |
+| `wss://<steel-host>/v1/devtools?sessionId=<id>` | CDP endpoint. Send `Authorization` on the WebSocket handshake; do not add the credential to this URL |
 | `$STEEL_UI_URL?sessionId=<id>` | Session viewer for human takeover |
 
-The CDP URL carries the API key in its query string. Treat it as a secret: never paste it into chat, a prompt, an issue or a log.
-
 ## Run a browser task
 
-1. Define a helper that sends the key as a header read from standard input, so it never appears in a process list:
+1. Define a helper that sends `Authorization` on stdin, so the secret never appears in a process list:
 
    ```bash
    steel() {  # usage: steel METHOD PATH [JSON-BODY]
+     local basic
      local args=(-sS -X "$1" "$STEEL_API_URL$2" -H @- -H 'Content-Type: application/json')
      if [ -n "${3:-}" ]; then args+=(-d "$3"); fi
-     printf 'x-steel-api-key: %s\n' "$STEEL_API_KEY" | curl "${args[@]}"
+     basic="$(printf '%s:%s' "$STEEL_AUTH_USER" "$STEEL_AUTH_TOKEN" | base64 | tr -d '\n')"
+     printf 'Authorization: Basic %s\n' "$basic" | curl "${args[@]}"
    }
    ```
 
@@ -83,7 +94,19 @@ The CDP URL carries the API key in its query string. Treat it as a secret: never
    echo "Session: $SESSION_ID"
    ```
 
-3. For exploration, attach `agent-browser --cdp "<cdp-url>"`. Playwright tests use Obscura. Set `KXM_BROWSER=steel` and `chromium.connectOverCDP(<cdp-url>)` only when the test must drive this takeover session. Check the session's state with `steel GET "/v1/sessions/$SESSION_ID"`.
+3. Playwright tests use Obscura. To drive this takeover session, set `KXM_BROWSER=steel` and pass the headers from `formatCDPConnect()` into `chromium.connectOverCDP`. `connectBrowserOverCdp()` does that when `KXM_BROWSER=steel`. `agent-browser --cdp` accepts a URL only and cannot send that header. Do not put the credential in the URL. Check the session's state with `steel GET "/v1/sessions/$SESSION_ID"`.
+
+   ```typescript
+   import { chromium } from "playwright";
+   import { formatCDPConnect, resolveSteelConfig } from "@kontextmind/kxm/runtime";
+
+   const { url, headers } = formatCDPConnect(
+     { id: sessionId, websocketUrl: "" },
+     resolveSteelConfig(),
+   );
+   const browser = await chromium.connectOverCDP(url, { headers });
+   ```
+
 4. For a quick fetch that needs no session, scrape instead:
 
    ```bash
@@ -99,7 +122,9 @@ The CDP URL carries the API key in its query string. Treat it as a secret: never
 <details><summary>PowerShell</summary>
 
 ```powershell
-$headers = @{ "x-steel-api-key" = $env:STEEL_API_KEY }
+$pair = "{0}:{1}" -f $env:STEEL_AUTH_USER, $env:STEEL_AUTH_TOKEN
+$basic = [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($pair))
+$headers = @{ Authorization = "Basic $basic" }
 $session = Invoke-RestMethod -Method Post -Uri "$env:STEEL_API_URL/v1/sessions" -Headers $headers -ContentType "application/json" -Body '{"timeout": 300000}'
 Invoke-RestMethod -Method Post -Uri "$env:STEEL_API_URL/v1/sessions/$($session.id)/release" -Headers $headers
 ```
@@ -139,9 +164,11 @@ The KXM browser library tracks these states in the process that owns the session
 
 | Symptom | Cause | Fix |
 |---|---|---|
-| `401` or `403` from Steel | Missing or wrong API key | Re-export `STEEL_API_KEY` from your secret manager |
+| `302` to `id.kxmd.dev` | The request had no Authentik app password | Export `STEEL_AUTH_USER` and `STEEL_AUTH_TOKEN`, or `STEEL_AUTH_BASIC`. A Bearer token is not accepted |
+| `401` or `403` | Wrong app password, or a legacy key the shim rejected | Re-export the Authentik credential from your secret manager. Re-export `STEEL_API_KEY` only when that is the credential you still use |
 | Requests go to an unexpected host | `STEEL_API_URL` is unset | Export it before starting the agent |
 | Playwright opens a local browser | The client called `chromium.launch()` or `chromium.connect()` | Use the worker-scoped fixture and `connectOverCDP` against Obscura |
+| Steel CDP connects without auth | `connectOverCDP` was called with only the URL | Call `connectOverCDP(url, { headers })` with the headers from `formatCDPConnect()` or `connectBrowserOverCdp()` |
 | `Access to private/internal IP address` | Obscura was started without `--allow-private-network` | Run `node scripts/obscura.mjs`, which passes that flag |
 | Signed-in state is gone | The session expired or was released | Create a new session and repeat the takeover |
 | The viewer shows the page but clicks do nothing | The viewer is a screencast, and some capture modes do not forward clicks | Use the DevTools inspector at `$STEEL_API_URL/v1/devtools/inspector.html`, with the agent paused |

package/docs/kb/how-credentials-retrieved-safely.md

@@ -7,10 +7,10 @@ project: "kxm"
 status: "accepted"
 owner: "@operator"
 created: "2026-09-14"
-updated: "2026-09-23"
+updated: "2026-09-27"
 authority: "instruction"
 confidence: "verified"
-summary: "How the Steel client resolves its API key and how browser work keeps secrets out of model context."
+summary: "How the Steel client resolves Authentik Basic auth and how browser work keeps secrets out of model context."
 tags: ["browser", "credentials", "pass-cli", "security"]
 related: ["docs/guides/browser-automation.md", "docs/guides/agent-skills.md"]
 ---
@@ -21,7 +21,7 @@ Browser automation keeps passwords, MFA secrets and API tokens out of model
 prompts and reasoning traces. The model sees references to credentials, never
 their values.
 
-## How the Steel client finds its API key
+## How the Steel client finds its credential
 
 `resolveSteelConfig()` resolves each setting in this order, and never writes a
 secret to disk or to a log:
@@ -29,12 +29,22 @@ secret to disk or to a log:
 | Setting | Resolved from |
 |---|---|
 | API URL | An explicit override, then `STEEL_API_URL`, then a built-in default |
-| API key | An explicit override, then `STEEL_API_KEY`, then a `pass-cli` lookup |
+| Authentik `Authorization` | `STEEL_AUTH_HEADER`, then `STEEL_AUTH_BASIC`, then `STEEL_AUTH_USER` and `STEEL_AUTH_TOKEN` |
+| Legacy API key | An explicit override, then `STEEL_API_KEY`, then a `pass-cli` lookup, and only when no Authentik credential is set |
 | Session viewer URL | An explicit override, then `STEEL_UI_URL`, then `<api-url>/ui` |
 
+KontextMind's Steel hosts are behind Authentik forward auth. The client sends
+`Authorization: Basic` on every HTTP request and on the CDP WebSocket. A Bearer
+token is not accepted. The legacy key is sent as `x-steel-api-key` and as an
+`apiKey` query parameter, which the proxy still accepts as a temporary shim.
+The library writes one deprecation warning to stderr and does not print the
+key. When an Authentik variable is set, the key is not sent and is not placed
+in a URL.
+
 The built-in default URL and the `pass-cli` lookup point at the maintainers'
-own Steel deployment and vault. Set `STEEL_API_URL` and `STEEL_API_KEY` for
-yours, and set `USE_PASS_CLI=false` to turn the lookup off.
+own Steel deployment and vault. The lookup reads `STEEL_API_KEY` only. Set
+`STEEL_API_URL` and an Authentik credential for yours, and set
+`USE_PASS_CLI=false` to turn the lookup off.
 
 ## Mechanisms
 
@@ -50,8 +60,9 @@ yours, and set `USE_PASS_CLI=false` to turn the lookup off.
 2. **References, not values.** A prompt receives a credential reference such
    as `vault: "<vault>", item: "<item>"`, never the secret itself.
 3. **Log sanitization.** The KXM browser client redacts `apiKey=` query values,
-   `steel_…` keys, and any field named like a key, secret, token, auth or
-   password before it logs or returns output.
+   `Authorization` header values, `Basic` credentials, `steel_…` keys, and any
+   field named like a key, secret, token, auth or password before it logs or
+   returns output.
 4. **Human handoff for high-privilege sign-in.** For production accounts or
    MFA, the agent does not touch the credential at all. It follows the
    `kxm-browser-takeover` skill and lets you sign in directly.

package/docs/kb/how-to-connect-playwright-to-steel.md

@@ -20,33 +20,52 @@ related: ["docs/guides/browser-automation.md", "docs/kb/how-to-connect-playwrigh
 Obscura is the default for Playwright testing and verification. Use this page when `KXM_BROWSER=steel` and you are attaching to a live Steel session for human takeover, MFA, or the session viewer. The default path is [How do I connect Playwright to Obscura?](how-to-connect-playwright-to-obscura.md).
 
 Run Playwright against a remote Steel session instead of a local browser by
-connecting over the Chrome DevTools Protocol (CDP). `resolveBrowserCdpEndpoint(session)` returns the same URL as `formatCDPEndpoint()` when `KXM_BROWSER=steel`.
+connecting over the Chrome DevTools Protocol (CDP). When `KXM_BROWSER=steel`,
+`resolveBrowserCdpEndpoint(session)` returns the same URL as `formatCDPEndpoint()`.
+The handshake needs the headers from `resolveBrowserCdpConnect(session)` or
+`formatCDPConnect()`. `connectBrowserOverCdp()` passes those headers into
+`chromium.connectOverCDP`.
 
 ## 1. Build the CDP endpoint
 
-Build the WebSocket CDP URL from the active session ID. The configuration comes
-from `STEEL_API_URL` and `STEEL_API_KEY`:
+Build the WebSocket CDP URL from the active session ID, and take the headers
+with it. Authentik forward auth accepts the app password only as
+`Authorization: Basic` on the WebSocket handshake. The URL does not carry the
+credential when `STEEL_AUTH_BASIC` or `STEEL_AUTH_USER` and `STEEL_AUTH_TOKEN`
+are set:
 
 ```typescript
-import { formatCDPEndpoint, resolveSteelConfig } from "@kontextmind/kxm/runtime";
+import { formatCDPConnect, resolveSteelConfig } from "@kontextmind/kxm/runtime";
 
-const config = resolveSteelConfig();
-const cdpUrl = formatCDPEndpoint({ id: sessionId, websocketUrl: "" }, config);
+const { url, headers } = formatCDPConnect(
+  { id: sessionId, websocketUrl: "" },
+  resolveSteelConfig(),
+);
 ```
 
-The result has this shape. It carries the API key, so never log it:
+The URL has this shape:
 
 ```text
-wss://<steel-host>/v1/devtools?sessionId=<session-id>&apiKey=<steel-api-key>
+wss://<steel-host>/v1/devtools?sessionId=<session-id>
 ```
 
+`headers` is `{ Authorization: "Basic <base64>" }`. Pass that object to
+Playwright. Do not log it. A legacy `STEEL_API_KEY` still appends `apiKey` to
+the URL for the temporary proxy shim; prefer the Authentik variables so the
+credential stays out of the URL.
+
 ## 2. Connect in Playwright
 
 ```typescript
 import { test, expect, chromium } from "@playwright/test";
+import { formatCDPConnect, resolveSteelConfig } from "@kontextmind/kxm/runtime";
 
 test("execute test on remote steel session", async () => {
-  const browser = await chromium.connectOverCDP(process.env.STEEL_CDP_URL!);
+  const { url, headers } = formatCDPConnect(
+    { id: process.env.STEEL_SESSION_ID!, websocketUrl: "" },
+    resolveSteelConfig(),
+  );
+  const browser = await chromium.connectOverCDP(url, { headers });
 
   // Use the existing context and page, or create them.
   const context = browser.contexts()[0] || await browser.newContext();

package/docs/kb/how-to-recover-expired-session-or-orphan.md

@@ -7,7 +7,7 @@ project: "kxm"
 status: "accepted"
 owner: "@operator"
 created: "2026-09-14"
-updated: "2026-09-23"
+updated: "2026-09-27"
 authority: "instruction"
 confidence: "verified"
 summary: "Find and release stale or orphaned browser sessions on Steel."
@@ -22,23 +22,23 @@ browser can keep running on your Steel deployment until its timeout.
 
 ## 1. List active sessions
 
-Load `STEEL_API_URL` and `STEEL_API_KEY` from your secret manager first. With
-`pass-cli`, for example:
+Load `STEEL_API_URL`, `STEEL_AUTH_USER`, and `STEEL_AUTH_TOKEN` from your secret
+manager first. With `pass-cli`, for example:
 
 ```bash
 export STEEL_API_URL="https://<steel-host>"
-STEEL_API_KEY=$(pass-cli item view --vault-name "<vault>" --item-title "<item>" --field STEEL_API_KEY)
-export STEEL_API_KEY
+export STEEL_AUTH_USER="svc-steel"
+export STEEL_AUTH_TOKEN="$(pass-cli item view --vault-name "<vault>" --item-title "<item>" --field password)"
+basic="$(printf '%s:%s' "$STEEL_AUTH_USER" "$STEEL_AUTH_TOKEN" | base64 | tr -d '\n')"
 
-curl -s "$STEEL_API_URL/v1/sessions" \
-  -H "x-steel-api-key: $STEEL_API_KEY" | jq .
+printf 'Authorization: Basic %s\n' "$basic" | curl -sS -H @- "$STEEL_API_URL/v1/sessions" | jq .
 ```
 
 ## 2. Release an orphaned session
 
 ```bash
-curl -s -X POST "$STEEL_API_URL/v1/sessions/<session-id>/release" \
-  -H "x-steel-api-key: $STEEL_API_KEY"
+printf 'Authorization: Basic %s\n' "$basic" \
+  | curl -sS -X POST -H @- "$STEEL_API_URL/v1/sessions/<session-id>/release"
 ```
 
 ## 3. Sweep orphans with the KXM client
@@ -60,5 +60,6 @@ for (const sessionId of orphans) {
 }
 ```
 
-It returns an empty list when the Steel API request fails, so an empty result
-does not prove there are no orphans. Check with the `curl` call above.
+It returns an empty list when the Steel API responds with an error status, so
+an empty result does not prove there are no orphans. A 302 from Authentik
+throws instead of looking like an empty list. Check with the `curl` call above.

package/docs/kb/why-automation-opened-different-browser.md

@@ -10,7 +10,7 @@ created: "2026-09-14"
 updated: "2026-09-27"
 authority: "instruction"
 confidence: "verified"
-summary: "Prevent accidental local browser launches and make Playwright and agent-browser attach to remote Steel."
+summary: "Prevent accidental local browser launches. Playwright attaches to Obscura, or to Steel with Authentik Basic auth when KXM_BROWSER=steel."
 tags: ["browser", "cdp", "playwright", "agent-browser", "troubleshooting"]
 related: ["docs/guides/browser-automation.md", "docs/kb/how-to-connect-playwright-to-obscura.md", "docs/kb/how-to-connect-playwright-to-steel.md"]
 ---
@@ -26,19 +26,22 @@ You expected automation to run on Obscura, or on a Steel takeover session, but a
 1. **The script called `chromium.launch()` instead of
    `chromium.connectOverCDP()`.**
    - `chromium.launch()` starts a browser on the local machine.
-   - **Fix:** in Playwright, connect with `chromium.connectOverCDP(cdpUrl)`.
+   - **Fix:** Obscura has no auth headers. Call `connectBrowserOverCdp()`, or `chromium.connectOverCDP()` with `resolveObscuraCdpEndpoint()`. For `KXM_BROWSER=steel`, pass `{ headers }` from `formatCDPConnect()`.
 2. **`agent-browser` ran without `--cdp`.**
    - `agent-browser open <url>` without `--cdp` starts a local headless
      browser.
-   - **Fix:** always pass the session's CDP URL:
-     `--cdp "wss://<steel-host>/v1/devtools?sessionId=<session-id>&apiKey=<steel-api-key>"`.
-     Build the Obscura URL with `resolveObscuraCdpEndpoint()`, or the Steel URL with `formatCDPEndpoint()` when `KXM_BROWSER=steel`. See
+   - **Fix:** pass `--cdp` with the Obscura URL from `resolveObscuraCdpEndpoint()`.
+     For a Steel takeover session, `agent-browser --cdp` takes a URL only and
+     cannot send the Authentik `Authorization` header, so use Playwright and
+     `connectBrowserOverCdp()`. Do not put the credential in the URL. See
      [How do I connect Playwright to Obscura?](how-to-connect-playwright-to-obscura.md)
      and
      [How do I connect Playwright to the existing Steel session?](how-to-connect-playwright-to-steel.md).
-3. **The Playwright client had no CDP endpoint.**
+3. **The Playwright client had no CDP endpoint, or Steel auth was missing.**
    - A script that falls back to `chromium.launch()` when no CDP URL is set
      opens a local browser.
    - **Fix:** use `resolveObscuraCdpEndpoint()` (default
      `http://127.0.0.1:9222`). For a Steel takeover session, set
-     `KXM_BROWSER=steel` and load `STEEL_API_URL` and `STEEL_API_KEY`.
+     `KXM_BROWSER=steel` and load `STEEL_API_URL` plus `STEEL_AUTH_USER` and
+     `STEEL_AUTH_TOKEN` (or `STEEL_AUTH_BASIC`). A legacy `STEEL_API_KEY` still
+     works through the proxy shim and warns once.

package/docs/prompts/browser-diagnose-recover.md

@@ -7,7 +7,7 @@ project: "kxm"
 status: "accepted"
 owner: "@operator"
 created: "2026-09-14"
-updated: "2026-09-23"
+updated: "2026-09-27"
 authority: "instruction"
 confidence: "verified"
 summary: "Troubleshoot unresponsive Steel sessions, CDP attachment errors, auth loops, and orphaned browser containers."
@@ -53,4 +53,4 @@ Use this prompt to troubleshoot unresponsive sessions, CDP attachment errors, au
 
 4. **Verify WebSocket / CDP Ingress**:
    - Ensure the reverse proxy or ingress in front of Steel passes WebSocket upgrades through. On Kubernetes with ingress-nginx, that is the `nginx.ingress.kubernetes.io/websocket-services` annotation.
-   - If CDP fails with 401, verify `x-steel-api-key` header or `?apiKey=` query parameter.
+   - If the response is a 302 to `id.kxmd.dev`, or CDP fails with 401, send `Authorization: Basic` from `STEEL_AUTH_BASIC` or from `STEEL_AUTH_USER` and `STEEL_AUTH_TOKEN`. A Bearer token is not accepted. Do not put the credential in the URL. The legacy `x-steel-api-key` header and `?apiKey=` query parameter remain only for the temporary proxy shim.

package/docs/prompts/browser-start.md

@@ -7,7 +7,7 @@ project: "kxm"
 status: "accepted"
 owner: "@operator"
 created: "2026-09-14"
-updated: "2026-09-23"
+updated: "2026-09-27"
 authority: "instruction"
 confidence: "verified"
 summary: "Initialize a remote Steel browser session for a project task, verifying credentials, connectivity, and attachment endpoints before automation."
@@ -42,7 +42,7 @@ Use this prompt to initialize a remote browser session on self-hosted Steel for
 ## Instructions for the agent
 
 1. **Verify Credential Reference**:
-   - Resolve the target credentials and `STEEL_API_KEY` from the secret manager, for example with `pass-cli`, without logging raw values.
+   - Resolve the target credentials and the Steel Authentik app password (`STEEL_AUTH_USER` and `STEEL_AUTH_TOKEN`, or `STEEL_AUTH_BASIC`) from the secret manager, for example with `pass-cli`, without logging raw values. A Bearer token is not accepted. Keep the credential in a header, not a URL.
    - Do not print credentials to the chat or save them to tracked files.
 
 2. **Launch Remote Steel Session**:
@@ -50,7 +50,7 @@ Use this prompt to initialize a remote browser session on self-hosted Steel for
    - Capture `sessionId`, `websocketUrl`, and `sessionViewerUrl`.
 
 3. **Verify Target Endpoint Connectivity**:
-   - Connect `agent-browser` or `Playwright` via CDP.
+   - Connect Playwright via CDP with the headers from `formatCDPConnect()` (`Authorization: Basic`). Do not put the credential in the URL. `agent-browser --cdp` cannot send that header.
    - Navigate to `{{TARGET_BASE_URL}}` within `{{PERMISSION_LEVEL}}` constraints.
    - If `PERMISSION_LEVEL` is `INSPECT_ONLY`, do not click submit buttons or mutate forms.
 

package/docs/reference/configuration.md

@@ -32,7 +32,7 @@ Names that start with `KXM_` are not all operator settings. This map covers ever
 | Runtime supervisor | `KXM_STATE_HOME`, `KXM_RUNTIME_SYNC_INTERVAL_MS`, `KXM_RUNTIME_STOP_GRACE_MS` | [Runtime supervisor settings](#runtime-supervisor-settings) |
 | Operator CLI and sessions | `KXM_USER_CONFIG_DIR`, `KXM_USER_TELEMETRY_DIR`, `KXM_SESSION_TOKEN`, `KXM_SESSION_BRIEF`, `KXM_WORKFLOW_*`, `GITHUB_TOKEN`, and others | [CLI and session settings](#cli-and-session-settings) |
 | Nous model providers | `KXM_NOUS_PROVIDERS`, `KXM_NOUS_PROXY_URL`, `KXM_NOUS_DISCOVERY_TIMEOUT_MS`, `KXM_NOUS_CATALOG_FILE`, `NOUS_API_KEY` | [Nous providers](../guides/nous-providers.md) |
-| Browser automation | `KXM_BROWSER`, `OBSCURA_CDP_URL`, `OBSCURA_PORT`, `STEEL_API_URL`, `STEEL_API_KEY`, `STEEL_UI_URL`, `USE_PASS_CLI` | [Browser settings](#browser-automation) |
+| Browser automation | `KXM_BROWSER`, `OBSCURA_CDP_URL`, `OBSCURA_PORT`, `STEEL_API_URL`, `STEEL_UI_URL`, `STEEL_AUTH_HEADER`, `STEEL_AUTH_BASIC`, `STEEL_AUTH_USER`, `STEEL_AUTH_TOKEN`, `STEEL_API_KEY` (legacy), `USE_PASS_CLI` | [Browser settings](#browser-automation) |
 | Set by a harness, not by you | `KXM_PROJECT_DIR` (Claude Code plugin), `KXM_ATTEMPT_TOKEN` (Runtime attempts), `KXM_WORKER_IDENTITY_KEY`, `KXM_WORKER_GENERATION`, `KXM_WORKER_CHILD_INCARCATION`, `KXM_WORKER_SESSION_SCOPE` (worker supervisor to its Pi child) | [Internal variables](#internal-variables) |
 | Maintainer and test only | `KXM_SMOKE*`, `KXM_ASSET*`, `KXM_RELEASE_TAG`, `KXM_PUBLISH_WAIT_MS`, `KXM_DETERMINISTIC_TEST_CLOCK`, `KXM_WORKER_STOP_AFTER_MS`, `KXM_STUDIO_ONCE` | [Development](../contributing/development.md) |
 | Maintainer critic script | `KXM_CRITIC_DIR`, `KXM_REVIEW_TARGET` | [Maintainer critic script](#maintainer-critic-script) |
@@ -200,17 +200,21 @@ The Runtime supervisor runs `kxm run` workflows and syncs their summaries to the
 
 ## Browser automation
 
-Playwright testing and verification use Obscura. Steel is for human takeover, MFA, and the live session viewer. `resolveBrowserCdpEndpoint()` in `plugins/kxm/src/browser.ts` chooses the CDP URL. `node scripts/obscura.mjs` downloads pinned Obscura v0.2.3 and serves it. See [Browser automation](../guides/browser-automation.md).
+Playwright testing and verification use Obscura. Steel is for human takeover, MFA, and the live session viewer. `resolveBrowserCdpEndpoint()` in `plugins/kxm/src/browser.ts` returns the CDP URL. `resolveBrowserCdpConnect()` returns that URL and the handshake headers, and `connectBrowserOverCdp()` passes them to `chromium.connectOverCDP`. `node scripts/obscura.mjs` downloads pinned Obscura v0.2.3 and serves it. See [Browser automation](../guides/browser-automation.md).
 
 | Variable | Default | Effect |
 |---|---|---|
-| `KXM_BROWSER` | `obscura` | `obscura` selects the Obscura CDP URL. `steel` selects the Steel session URL from `formatCDPEndpoint()` and requires a session id. Any other value throws |
+| `KXM_BROWSER` | `obscura` | `obscura` selects the Obscura CDP URL and sends no Steel headers. `steel` selects `formatCDPConnect()` (the session URL plus `Authorization`, or the legacy API-key header) and requires a session id. Any other value throws |
 | `OBSCURA_CDP_URL` | `http://127.0.0.1:${OBSCURA_PORT:-9222}` | CDP URL passed to `chromium.connectOverCDP()`. When set, it wins over `OBSCURA_PORT` for that URL |
 | `OBSCURA_PORT` | `9222` | TCP port for `obscura serve`. Used in the default CDP URL when `OBSCURA_CDP_URL` is unset. The launcher refuses to start when this port disagrees with the port in `OBSCURA_CDP_URL` |
 | `STEEL_API_URL` | A KontextMind-operated deployment | Base URL of your Steel API. Set it before using `KXM_BROWSER=steel` |
 | `STEEL_UI_URL` | `$STEEL_API_URL/ui` | Base URL of the Steel session viewer |
-| `STEEL_API_KEY` | A `pass-cli` lookup | Steel API key. When unset, the library runs a `pass-cli` lookup of a fixed KontextMind vault item |
-| `USE_PASS_CLI` | enabled | Set to `false` to disable that `pass-cli` fallback |
+| `STEEL_AUTH_HEADER` | unset | Full `Authorization` value. Wins over the other Steel auth variables |
+| `STEEL_AUTH_BASIC` | unset | `base64(user:token)`, with or without a leading `Basic` prefix. Sent as `Authorization: Basic` |
+| `STEEL_AUTH_USER` | unset | Authentik username. Used with `STEEL_AUTH_TOKEN`. An incomplete pair fails closed |
+| `STEEL_AUTH_TOKEN` | unset | Authentik app password. Used with `STEEL_AUTH_USER` |
+| `STEEL_API_KEY` | A `pass-cli` lookup | Deprecated. Sent as `x-steel-api-key` and as `?apiKey=` on the CDP URL for the temporary proxy shim. The library warns once. Not sent when an Authentik variable is set |
+| `USE_PASS_CLI` | enabled | Set to `false` to disable the legacy `STEEL_API_KEY` `pass-cli` fallback |
 
 Obscura's own `OBSCURA_TIMEZONE` (default `Europe/Berlin`) and `OBSCURA_CDP_TOKEN` (required only for a non-loopback bind) are read by the Obscura process, not by KXM.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontextmind/kxm",
-  "version": "0.7.133",
+  "version": "0.7.135",
   "description": "KXM local-first multi-agent orchestration and operator dashboard",
   "type": "module",
   "author": "KontextMind",

package/plugins/kxm/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "kxm",
   "displayName": "KXM",
-  "version": "0.7.133",
+  "version": "0.7.135",
   "description": "Headless multi-agent orchestration, durable workflows, and a live operator dashboard for Pi and Claude Code",
   "author": {
     "name": "KontextMind",

package/plugins/kxm/dist/mcp-server.js

@@ -17313,7 +17313,7 @@ function sessionTokenFixHint(policy) {
 }
 
 // plugins/kxm/src/mcp-server.ts
-var VERSION = "0.7.133";
+var VERSION = "0.7.135";
 var CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 var inbox = /* @__PURE__ */ new Map();
 var notifiedInbox = /* @__PURE__ */ new Set();