@kontextmind/kxm 0.7.134 → 0.7.135

package/plugins/kxm/src/browser.ts

@@ -6,6 +6,10 @@
  * takeover, MFA, and the live session viewer (`KXM_BROWSER=steel`).
  * Manages remote Steel sessions, CDP endpoints, human takeover handoffs,
  * pass-cli credential references, and automated cleanup without leaking secrets.
+ *
+ * Hosts behind Authentik forward auth (the KontextMind Steel proxies) accept
+ * an app password only as `Authorization: Basic`. A Bearer token is refused.
+ * `STEEL_API_KEY` remains a legacy shim: `x-steel-api-key` and `?apiKey=`.
  */
 
 import { execSync } from "node:child_process";
@@ -136,11 +140,156 @@ export interface AnnotationFeedback {
 
 export interface SteelConfig {
   apiUrl: string;
+  /** Legacy Steel key. Omitted once Authentik Basic auth is configured. */
   apiKey?: string | undefined;
+  /**
+   * Full `Authorization` value, for example `Basic <base64>`.
+   * Present when Authentik app-password auth is configured.
+   */
+  authorization?: string | undefined;
   uiUrl?: string | undefined;
   timeoutMs?: number | undefined;
 }
 
+/** Inputs for {@link resolveSteelConfig}. Environment variables fill anything omitted. */
+export interface SteelConfigOverrides extends Partial<SteelConfig> {
+  /** Full Authorization value, or a bare base64 credential. Wins over the other auth inputs. */
+  authHeader?: string | undefined;
+  /** `base64(user:token)`, with or without a leading `Basic `. */
+  authBasic?: string | undefined;
+  /** Authentik username, for example `svc-steel`. Used with `authToken`. */
+  authUser?: string | undefined;
+  /** Authentik app password. Used with `authUser`. */
+  authToken?: string | undefined;
+}
+
+export class SteelAuthConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "SteelAuthConfigError";
+  }
+}
+
+/** Authentik challenged the request with a redirect. The message never includes credentials. */
+export class SteelAuthRedirectError extends Error {
+  readonly status: number;
+  readonly host: string;
+
+  constructor(status: number, host: string) {
+    super(
+      `Steel request was redirected (${status}) to ${host}. ` +
+        "Send Authorization: Basic via STEEL_AUTH_BASIC or STEEL_AUTH_USER and STEEL_AUTH_TOKEN. " +
+        "A Bearer token is not accepted.",
+    );
+    this.name = "SteelAuthRedirectError";
+    this.status = status;
+    this.host = host;
+  }
+}
+
+const LEGACY_STEEL_AUTH_WARNING =
+  "kxm: STEEL_API_KEY is deprecated for Steel. Authentik forward auth accepts app passwords only as Authorization: Basic. " +
+  "Set STEEL_AUTH_BASIC, or STEEL_AUTH_USER and STEEL_AUTH_TOKEN. " +
+  "The legacy x-steel-api-key header and apiKey query parameter remain for the temporary proxy shim.\n";
+
+let legacySteelAuthWarned = false;
+
+/** Test hook. Production calls warn at most once per process. */
+export function resetLegacySteelAuthWarningForTests(): void {
+  legacySteelAuthWarned = false;
+}
+
+function warnLegacySteelAuth(): void {
+  if (legacySteelAuthWarned) return;
+  legacySteelAuthWarned = true;
+  process.stderr.write(LEGACY_STEEL_AUTH_WARNING);
+}
+
+function firstNonEmpty(...values: Array<string | undefined>): string | undefined {
+  for (const value of values) {
+    const trimmed = value?.trim();
+    if (trimmed) return trimmed;
+  }
+  return undefined;
+}
+
+function normalizeAuthorization(raw: string): string {
+  if (/[\r\n]/.test(raw)) {
+    throw new SteelAuthConfigError("Steel authorization value contains a line break.");
+  }
+  const value = raw.trim();
+  if (!value) {
+    throw new SteelAuthConfigError("Steel authorization value is empty.");
+  }
+  const basicPrefix = /^basic\s+(.+)$/i.exec(value);
+  if (basicPrefix) {
+    const credential = basicPrefix[1] ?? "";
+    if (!credential || /\s/.test(credential)) {
+      throw new SteelAuthConfigError("Steel Basic credential must be a single base64 token.");
+    }
+    return `Basic ${credential}`;
+  }
+  if (/\s/.test(value)) {
+    return value;
+  }
+  return `Basic ${value}`;
+}
+
+/**
+ * Resolve the Authentik `Authorization` value.
+ * Precedence: auth header override, then `STEEL_AUTH_BASIC`, then user + token.
+ * Returns undefined when none of those are set so the legacy API key can apply.
+ */
+export function resolveSteelAuthorization(overrides?: SteelConfigOverrides): string | undefined {
+  const header = firstNonEmpty(overrides?.authHeader, overrides?.authorization, process.env.STEEL_AUTH_HEADER);
+  if (header) return normalizeAuthorization(header);
+
+  const basic = firstNonEmpty(overrides?.authBasic, process.env.STEEL_AUTH_BASIC);
+  if (basic) return normalizeAuthorization(basic);
+
+  const user = firstNonEmpty(overrides?.authUser, process.env.STEEL_AUTH_USER);
+  const token = firstNonEmpty(overrides?.authToken, process.env.STEEL_AUTH_TOKEN);
+  if (user || token) {
+    if (!user || !token) {
+      throw new SteelAuthConfigError(
+        "Steel Basic auth needs both STEEL_AUTH_USER and STEEL_AUTH_TOKEN, or STEEL_AUTH_BASIC.",
+      );
+    }
+    return `Basic ${Buffer.from(`${user}:${token}`, "utf8").toString("base64")}`;
+  }
+  return undefined;
+}
+
+/**
+ * Headers for Steel HTTP and for Playwright `chromium.connectOverCDP(url, { headers })`.
+ * Basic auth wins and does not attach the legacy API key.
+ */
+export function steelRequestHeaders(config: Pick<SteelConfig, "authorization" | "apiKey">): Record<string, string> {
+  if (config.authorization) {
+    return { Authorization: config.authorization };
+  }
+  if (config.apiKey) {
+    return { "x-steel-api-key": config.apiKey };
+  }
+  return {};
+}
+
+export function steelAuthRedirectError(res: {
+  status: number;
+  headers: { get(name: string): string | null };
+}): SteelAuthRedirectError {
+  let host = "the identity provider";
+  const location = res.headers.get("location");
+  if (location) {
+    try {
+      host = new URL(location, "https://id.kxmd.dev").host;
+    } catch {
+      host = "the identity provider";
+    }
+  }
+  return new SteelAuthRedirectError(res.status, host);
+}
+
 export function resolvePassCliApiKey(
   execFn: (cmd: string) => string = (cmd) =>
     execSync(cmd, { encoding: "utf8", stdio: ["pipe", "pipe", "ignore"], timeout: 5000 }),
@@ -178,14 +327,24 @@ export function resolvePassCliApiKey(
 /**
  * Resolve Steel configuration from environment or pass-cli.
  * Does not write secrets to disk or logs.
+ *
+ * Authentik Basic auth (`STEEL_AUTH_HEADER`, `STEEL_AUTH_BASIC`, or
+ * `STEEL_AUTH_USER` + `STEEL_AUTH_TOKEN`) wins over `STEEL_API_KEY`.
+ * The legacy key is kept only when no Basic credential is configured, and
+ * a one-time deprecation warning is written to stderr.
  */
-export function resolveSteelConfig(overrides?: Partial<SteelConfig>): SteelConfig {
+export function resolveSteelConfig(overrides?: SteelConfigOverrides): SteelConfig {
   const apiUrl =
     overrides?.apiUrl ||
     process.env.STEEL_API_URL ||
     "https://steel.kontextmind.com";
 
-  const apiKey = overrides?.apiKey || process.env.STEEL_API_KEY || resolvePassCliApiKey();
+  const authorization = resolveSteelAuthorization(overrides);
+  let apiKey: string | undefined;
+  if (!authorization) {
+    apiKey = overrides?.apiKey || process.env.STEEL_API_KEY || resolvePassCliApiKey();
+    if (apiKey) warnLegacySteelAuth();
+  }
 
   const uiUrl =
     overrides?.uiUrl ||
@@ -196,6 +355,7 @@ export function resolveSteelConfig(overrides?: Partial<SteelConfig>): SteelConfi
   return {
     apiUrl: apiUrl.replace(/\/$/, ""),
     apiKey,
+    authorization,
     uiUrl,
     timeoutMs: overrides?.timeoutMs || 300000, // 5 minutes default
   };
@@ -203,6 +363,7 @@ export function resolveSteelConfig(overrides?: Partial<SteelConfig>): SteelConfi
 
 /**
  * Format a remote CDP connection URL for Playwright or agent-browser.
+ * The legacy `apiKey` query parameter is added only when Basic auth is unset.
  */
 export function formatCDPEndpoint(session: Pick<SteelSession, "id" | "websocketUrl">, config: SteelConfig): string {
   const baseApi = config.apiUrl;
@@ -213,13 +374,34 @@ export function formatCDPEndpoint(session: Pick<SteelSession, "id" | "websocketU
 
   const searchParams = new URLSearchParams();
   searchParams.set("sessionId", session.id);
-  if (config.apiKey) {
+  if (!config.authorization && config.apiKey) {
     searchParams.set("apiKey", config.apiKey);
   }
 
   return `${wsProtocol}//${host}/v1/devtools?${searchParams.toString()}`;
 }
 
+export interface SteelCdpConnect {
+  /** WebSocket URL. Credentials stay out of it when Authentik Basic auth is set. */
+  url: string;
+  /** Pass as the second argument to `chromium.connectOverCDP(url, { headers })`. */
+  headers: Record<string, string>;
+}
+
+/**
+ * CDP URL plus the headers Playwright must send on the WebSocket handshake.
+ * Call `chromium.connectOverCDP(url, { headers })`. Do not put the credential in the URL.
+ */
+export function formatCDPConnect(
+  session: Pick<SteelSession, "id" | "websocketUrl">,
+  config: SteelConfig,
+): SteelCdpConnect {
+  return {
+    url: formatCDPEndpoint(session, config),
+    headers: steelRequestHeaders(config),
+  };
+}
+
 export const DEFAULT_OBSCURA_CDP_URL = "http://127.0.0.1:9222";
 const DEFAULT_OBSCURA_PORT = 9222;
 
@@ -249,32 +431,64 @@ export function resolveObscuraCdpEndpoint(): string {
 }
 
 /**
- * Playwright CDP endpoint.
- * Obscura by default. `KXM_BROWSER=steel` uses {@link formatCDPEndpoint} for `session`.
+ * Playwright CDP target.
+ * Obscura by default, with empty headers. `KXM_BROWSER=steel` uses {@link formatCDPConnect}.
  */
-export function resolveBrowserCdpEndpoint(
+export function resolveBrowserCdpConnect(
   session?: Pick<SteelSession, "id" | "websocketUrl">,
   config?: SteelConfig,
-): string {
+): SteelCdpConnect {
   const browser = (process.env.KXM_BROWSER ?? "").trim().toLowerCase();
   if (browser === "" || browser === "obscura") {
-    return resolveObscuraCdpEndpoint();
+    return { url: resolveObscuraCdpEndpoint(), headers: {} };
   }
   if (browser === "steel") {
     if (!session?.id) {
       throw new Error("KXM_BROWSER=steel requires a Steel session id");
     }
-    return formatCDPEndpoint(session, config ?? resolveSteelConfig());
+    return formatCDPConnect(session, config ?? resolveSteelConfig());
   }
   throw new Error(`Unsupported KXM_BROWSER value ${JSON.stringify(process.env.KXM_BROWSER)}; expected "obscura" or "steel"`);
 }
 
+/**
+ * Playwright CDP endpoint.
+ * Obscura by default. `KXM_BROWSER=steel` returns the URL from {@link formatCDPConnect}.
+ * Pass {@link resolveBrowserCdpConnect} headers into `chromium.connectOverCDP`, or call {@link connectBrowserOverCdp}.
+ */
+export function resolveBrowserCdpEndpoint(
+  session?: Pick<SteelSession, "id" | "websocketUrl">,
+  config?: SteelConfig,
+): string {
+  return resolveBrowserCdpConnect(session, config).url;
+}
+
+/**
+ * Connect Playwright over CDP.
+ * Obscura is called with the URL only. `KXM_BROWSER=steel` passes Authentik or legacy Steel headers on the handshake.
+ */
+export async function connectBrowserOverCdp<T>(
+  connectOverCDP: (url: string, options?: { headers?: Record<string, string> }) => Promise<T>,
+  session?: Pick<SteelSession, "id" | "websocketUrl">,
+  config?: SteelConfig,
+): Promise<T> {
+  const { url, headers } = resolveBrowserCdpConnect(session, config);
+  if (Object.keys(headers).length === 0) return connectOverCDP(url);
+  return connectOverCDP(url, { headers });
+}
+
 /**
  * Redact sensitive API keys and tokens from URLs and objects for logging.
  */
 export function sanitizeLogOutput<T>(input: T): T {
   if (typeof input === "string") {
-    return input.replace(/apiKey=[^&]+/g, "apiKey=[REDACTED]").replace(/steel_[a-f0-9]+/g, "steel_[REDACTED]") as unknown as T;
+    const redacted = input
+      .replace(/apiKey=[^&\s]+/gi, "apiKey=[REDACTED]")
+      .replace(/([?&]authorization=)[^&\s]+/gi, "$1[REDACTED]")
+      .replace(/authorization:\s*(?:basic\s+)?\S+/gi, "authorization: [REDACTED]")
+      .replace(/\bBasic\s+(?:[A-Za-z0-9+/]*[+/=0-9][A-Za-z0-9+/]*={0,2})/g, "Basic [REDACTED]")
+      .replace(/steel_[a-f0-9]+/g, "steel_[REDACTED]");
+    return redacted as unknown as T;
   }
   if (Array.isArray(input)) {
     return input.map(sanitizeLogOutput) as unknown as T;
@@ -360,7 +574,7 @@ export class SteelClient {
   private config: SteelConfig;
   private activeSessions = new Map<string, SteelSession>();
 
-  constructor(config?: Partial<SteelConfig>) {
+  constructor(config?: SteelConfigOverrides) {
     this.config = resolveSteelConfig(config);
   }
 
@@ -368,14 +582,31 @@ export class SteelClient {
     return { ...this.config };
   }
 
+  /**
+   * URL and headers for `chromium.connectOverCDP(url, { headers })`.
+   * The URL omits credentials when Authentik Basic auth is configured.
+   */
+  cdpConnectOptions(session: Pick<SteelSession, "id" | "websocketUrl">): SteelCdpConnect {
+    return formatCDPConnect(session, this.config);
+  }
+
   private headers(): Record<string, string> {
-    const h: Record<string, string> = {
+    return {
       "Content-Type": "application/json",
+      ...steelRequestHeaders(this.config),
     };
-    if (this.config.apiKey) {
-      h["x-steel-api-key"] = this.config.apiKey;
+  }
+
+  private async steelFetch(url: string, init: RequestInit): Promise<Response> {
+    const headers = {
+      ...this.headers(),
+      ...(init.headers as Record<string, string> | undefined),
+    };
+    const res = await fetch(url, { ...init, headers, redirect: "manual" });
+    if ((res.status >= 300 && res.status < 400) || res.type === "opaqueredirect") {
+      throw steelAuthRedirectError(res);
     }
-    return h;
+    return res;
   }
 
   /**
@@ -397,14 +628,13 @@ export class SteelClient {
       body.proxy = options.proxy;
     }
 
-    const res = await fetch(`${this.config.apiUrl}/v1/sessions`, {
+    const res = await this.steelFetch(`${this.config.apiUrl}/v1/sessions`, {
       method: "POST",
-      headers: this.headers(),
       body: JSON.stringify(body),
     });
 
     if (!res.ok) {
-      const errText = await res.text();
+      const errText = sanitizeLogOutput(await res.text());
       throw new Error(`Failed to create Steel session (${res.status}): ${errText}`);
     }
 
@@ -432,9 +662,8 @@ export class SteelClient {
    * Get details of an existing session.
    */
   async getSession(sessionId: string): Promise<SteelSession | null> {
-    const res = await fetch(`${this.config.apiUrl}/v1/sessions/${encodeURIComponent(sessionId)}`, {
+    const res = await this.steelFetch(`${this.config.apiUrl}/v1/sessions/${encodeURIComponent(sessionId)}`, {
       method: "GET",
-      headers: this.headers(),
     });
 
     if (res.status === 404) {
@@ -563,9 +792,8 @@ export class SteelClient {
    */
   async releaseSession(sessionId: string): Promise<boolean> {
     try {
-      const res = await fetch(`${this.config.apiUrl}/v1/sessions/${encodeURIComponent(sessionId)}/release`, {
+      const res = await this.steelFetch(`${this.config.apiUrl}/v1/sessions/${encodeURIComponent(sessionId)}/release`, {
         method: "POST",
-        headers: this.headers(),
       });
 
       const session = this.activeSessions.get(sessionId);
@@ -576,7 +804,8 @@ export class SteelClient {
       }
       this.activeSessions.delete(sessionId);
       return res.ok;
-    } catch {
+    } catch (error) {
+      if (error instanceof SteelAuthRedirectError) throw error;
       this.activeSessions.delete(sessionId);
       return false;
     }
@@ -586,14 +815,13 @@ export class SteelClient {
    * Perform a direct stateless scrape without manual session management.
    */
   async scrape(url: string): Promise<ScrapeResult> {
-    const res = await fetch(`${this.config.apiUrl}/v1/scrape`, {
+    const res = await this.steelFetch(`${this.config.apiUrl}/v1/scrape`, {
       method: "POST",
-      headers: this.headers(),
       body: JSON.stringify({ url }),
     });
 
     if (!res.ok) {
-      const err = await res.text();
+      const err = sanitizeLogOutput(await res.text());
       throw new Error(`Scrape failed (${res.status}): ${err}`);
     }
 
@@ -604,14 +832,13 @@ export class SteelClient {
    * Perform a direct screenshot action.
    */
   async screenshot(url: string, fullPage = false): Promise<ScreenshotResult> {
-    const res = await fetch(`${this.config.apiUrl}/v1/screenshot`, {
+    const res = await this.steelFetch(`${this.config.apiUrl}/v1/screenshot`, {
       method: "POST",
-      headers: this.headers(),
       body: JSON.stringify({ url, fullPage }),
     });
 
     if (!res.ok) {
-      const err = await res.text();
+      const err = sanitizeLogOutput(await res.text());
       throw new Error(`Screenshot failed (${res.status}): ${err}`);
     }
 
@@ -622,9 +849,8 @@ export class SteelClient {
    * Detect and list orphaned or timed-out active sessions.
    */
   async checkOrphanedSessions(maxIdleMs = 600000): Promise<string[]> {
-    const res = await fetch(`${this.config.apiUrl}/v1/sessions`, {
+    const res = await this.steelFetch(`${this.config.apiUrl}/v1/sessions`, {
       method: "GET",
-      headers: this.headers(),
     });
 
     if (!res.ok) {

package/plugins/kxm/src/mcp-server.ts

@@ -11,7 +11,7 @@ import { deliverInboxNotification } from "./inbox.ts";
 import type { HubEvent, MessageRecord } from "./protocol.ts";
 import { sessionTokenFixHint } from "./session-token-hint.ts";
 
-const VERSION = "0.7.134";
+const VERSION = "0.7.135";
 const CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 const inbox = new Map<string, MessageRecord>();
 const notifiedInbox = new Set<string>();