neurocode-ai 1.18.5

package/test/mcp/oauth-auto-connect.test.ts

@@ -0,0 +1,300 @@
+import { expect } from "bun:test"
+import { Server } from "@modelcontextprotocol/sdk/server/index.js"
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js"
+import { ListResourcesRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js"
+import { LayerNode } from "@neurocode-ai/core/effect/layer-node"
+import { CrossSpawnSpawner } from "@neurocode-ai/core/cross-spawn-spawner"
+import { FSUtil } from "@neurocode-ai/core/fs-util"
+import { Effect } from "effect"
+import { Config } from "../../src/config/config"
+import { EventV2Bridge } from "../../src/event-v2-bridge"
+import { McpAuth } from "../../src/mcp/auth"
+import { MCP } from "../../src/mcp/index"
+import { McpOAuthCallback } from "../../src/mcp/oauth-callback"
+import { McpOAuthPendingProvider, McpOAuthProvider } from "../../src/mcp/oauth-provider"
+import { testEffect } from "../lib/effect"
+
+const mcpTest = testEffect(
+  LayerNode.compile(
+    LayerNode.group([MCP.node, McpAuth.node, EventV2Bridge.node, Config.node, CrossSpawnSpawner.node, FSUtil.node]),
+  ),
+)
+
+interface OAuthMcpOptions {
+  capabilities?: "tools" | "resources"
+}
+
+function serveOAuthMcp(options: OAuthMcpOptions = {}) {
+  return Effect.acquireRelease(
+    Effect.promise(async () => {
+      const capabilities = options.capabilities ?? "tools"
+      const protocol = new Server(
+        { name: "oauth-auto-connect", version: "1.0.0" },
+        { capabilities: capabilities === "tools" ? { tools: {} } : { resources: {} } },
+      )
+      const transport = new WebStandardStreamableHTTPServerTransport({
+        sessionIdGenerator: () => crypto.randomUUID(),
+        enableJsonResponse: true,
+      })
+      let listToolsCalls = 0
+      let requiresAuth = true
+
+      if (capabilities === "tools") {
+        protocol.setRequestHandler(ListToolsRequestSchema, () => {
+          listToolsCalls++
+          return Promise.resolve({ tools: [{ name: "test_tool", inputSchema: { type: "object" } }] })
+        })
+      }
+      if (capabilities === "resources") {
+        protocol.setRequestHandler(ListResourcesRequestSchema, () =>
+          Promise.resolve({ resources: [{ name: "docs", uri: "docs://readme" }] }),
+        )
+      }
+
+      await protocol.connect(transport)
+      const http = Bun.serve({
+        port: 0,
+        async fetch(request) {
+          const url = new URL(request.url)
+          const origin = url.origin
+          const mcpUrl = `${origin}/mcp`
+
+          if (url.pathname === "/.well-known/oauth-protected-resource/mcp") {
+            return Response.json({
+              resource: mcpUrl,
+              authorization_servers: [origin],
+              scopes_supported: ["mcp"],
+            })
+          }
+          if (url.pathname === "/.well-known/oauth-protected-resource") {
+            return Response.json({
+              resource: mcpUrl,
+              authorization_servers: [origin],
+              scopes_supported: ["mcp"],
+            })
+          }
+          if (url.pathname === "/.well-known/oauth-authorization-server") {
+            return Response.json({
+              issuer: origin,
+              authorization_endpoint: `${origin}/authorize`,
+              token_endpoint: `${origin}/token`,
+              registration_endpoint: `${origin}/register`,
+              response_types_supported: ["code"],
+              grant_types_supported: ["authorization_code", "refresh_token"],
+              token_endpoint_auth_methods_supported: ["none"],
+              code_challenge_methods_supported: ["S256"],
+              scopes_supported: ["mcp"],
+            })
+          }
+          if (url.pathname === "/register") {
+            const metadata = (await request.json()) as Record<string, unknown>
+            return Response.json({ ...metadata, client_id: "replacement-client" }, { status: 201 })
+          }
+          if (url.pathname === "/token") {
+            const body = new URLSearchParams(await request.text())
+            if (body.get("code") !== "valid-code") {
+              return Response.json(
+                { error: "invalid_grant", error_description: "Token exchange failed" },
+                { status: 400 },
+              )
+            }
+            return Response.json({ access_token: "replacement-token", token_type: "Bearer" })
+          }
+          if (url.pathname !== "/mcp") return new Response("Not found", { status: 404 })
+
+          if (request.method === "GET") return new Response(null, { status: 405 })
+          if (requiresAuth && request.headers.get("authorization") !== "Bearer replacement-token") {
+            return new Response("Unauthorized", {
+              status: 401,
+              headers: {
+                "WWW-Authenticate": `Bearer resource_metadata="${origin}/.well-known/oauth-protected-resource", scope="mcp"`,
+              },
+            })
+          }
+          return transport.handleRequest(request)
+        },
+      })
+
+      return {
+        url: new URL("/mcp", http.url).toString(),
+        allowAnonymous: () => {
+          requiresAuth = false
+        },
+        listToolsCalls: () => listToolsCalls,
+        close: async () => {
+          await http.stop(true)
+          await protocol.close()
+        },
+      }
+    }),
+    (server) => Effect.promise(server.close),
+  )
+}
+
+const remote = (url: string, enabled = true) => ({
+  type: "remote" as const,
+  url,
+  enabled,
+})
+
+const stopOAuthCallback = Effect.addFinalizer(() => Effect.promise(() => McpOAuthCallback.stop()).pipe(Effect.ignore))
+
+mcpTest.instance("first connect to OAuth server shows needs_auth instead of failed", () =>
+  Effect.gen(function* () {
+    const server = yield* serveOAuthMcp()
+    const mcp = yield* MCP.Service
+    const result = yield* mcp.add("test-oauth", remote(server.url))
+
+    expect((result.status as Record<string, { status: string }>)["test-oauth"]).toEqual({ status: "needs_auth" })
+  }),
+)
+
+mcpTest.instance("state() generates and persists a new state when none is saved", () =>
+  Effect.gen(function* () {
+    const auth = yield* McpAuth.Service
+    const provider = new McpOAuthProvider(
+      "test-state-gen",
+      "https://example.com/mcp",
+      {},
+      { onRedirect: async () => {} },
+      auth,
+    )
+
+    expect((yield* auth.get("test-state-gen"))?.oauthState).toBeUndefined()
+
+    const state = yield* Effect.promise(() => provider.state())
+    expect(state).toHaveLength(64)
+    expect((yield* auth.get("test-state-gen"))?.oauthState).toBe(state)
+  }),
+)
+
+mcpTest.instance("state() returns existing state when one is saved", () =>
+  Effect.gen(function* () {
+    const auth = yield* McpAuth.Service
+    const provider = new McpOAuthProvider(
+      "test-state-existing",
+      "https://example.com/mcp",
+      {},
+      { onRedirect: async () => {} },
+      auth,
+    )
+
+    yield* auth.updateOAuthState("test-state-existing", "pre-saved-state-value")
+    expect(yield* Effect.promise(() => provider.state())).toBe("pre-saved-state-value")
+  }),
+)
+
+mcpTest.instance("pending provider does not expose or overwrite existing credentials before commit", () =>
+  Effect.gen(function* () {
+    const auth = yield* McpAuth.Service
+    const name = "test-pending-credentials"
+    const url = "https://example.com/mcp"
+    const provider = new McpOAuthPendingProvider(name, url, {}, { onRedirect: async () => {} }, auth)
+
+    yield* auth.updateClientInfo(name, { clientId: "old-client" }, url)
+    yield* auth.updateTokens(name, { accessToken: "old-token" }, url)
+
+    expect(yield* Effect.promise(() => provider.clientInformation())).toBeUndefined()
+    expect(yield* Effect.promise(() => provider.tokens())).toBeUndefined()
+    expect((yield* auth.get(name))?.tokens?.accessToken).toBe("old-token")
+    expect((yield* auth.get(name))?.clientInfo?.clientId).toBe("old-client")
+  }),
+)
+
+mcpTest.instance("failed reauthentication preserves existing credentials", () =>
+  Effect.gen(function* () {
+    yield* stopOAuthCallback
+    const server = yield* serveOAuthMcp()
+    const mcp = yield* MCP.Service
+    const auth = yield* McpAuth.Service
+    const name = "test-reauth-failure"
+
+    yield* auth.updateClientInfo(name, { clientId: "dynamic-client", clientSecret: "dynamic-secret" }, server.url)
+    yield* auth.updateTokens(name, { accessToken: "working-token" }, server.url)
+    yield* mcp.add(name, remote(server.url))
+    expect((yield* mcp.startAuth(name)).authorizationUrl).toContain("/authorize")
+
+    expect(yield* mcp.finishAuth(name, "invalid-code")).toEqual({
+      status: "failed",
+      error: "OAuth completion failed: Token exchange failed",
+    })
+    expect((yield* auth.get(name))?.tokens?.accessToken).toBe("working-token")
+    expect((yield* auth.get(name))?.clientInfo).toMatchObject({
+      clientId: "dynamic-client",
+      clientSecret: "dynamic-secret",
+    })
+  }),
+)
+
+mcpTest.instance("successful reauthentication commits replacement credentials", () =>
+  Effect.gen(function* () {
+    yield* stopOAuthCallback
+    const server = yield* serveOAuthMcp()
+    const mcp = yield* MCP.Service
+    const auth = yield* McpAuth.Service
+    const name = "test-reauth-success"
+
+    yield* auth.updateClientInfo(name, { clientId: "old-client" }, server.url)
+    yield* auth.updateTokens(name, { accessToken: "old-token" }, server.url)
+    yield* mcp.add(name, remote(server.url))
+    expect((yield* mcp.startAuth(name)).authorizationUrl).toContain("/authorize")
+    expect((yield* auth.get(name))?.tokens?.accessToken).toBe("old-token")
+
+    expect((yield* mcp.finishAuth(name, "valid-code")).status).toBe("connected")
+    const entry = yield* auth.get(name)
+    expect(entry?.tokens?.accessToken).toBe("replacement-token")
+    expect(entry?.clientInfo?.clientId).toBe("replacement-client")
+    expect(entry?.serverUrl).toBe(server.url)
+  }),
+)
+
+mcpTest.instance("auth status only reports credentials stored for the configured server URL", () =>
+  Effect.gen(function* () {
+    const mcp = yield* MCP.Service
+    yield* mcp.add("test-status-url", remote("https://example.com/mcp", false))
+    yield* McpAuth.use.updateTokens("test-status-url", { accessToken: "old-token" }, "https://old.example.com/mcp")
+
+    expect(yield* mcp.getAuthStatus("test-status-url")).toBe("not_authenticated")
+
+    yield* McpAuth.use.updateTokens("test-status-url", { accessToken: "current-token" }, "https://example.com/mcp")
+    expect(yield* mcp.getAuthStatus("test-status-url")).toBe("authenticated")
+
+    yield* McpAuth.use.updateTokens(
+      "test-status-url",
+      { accessToken: "expired-token", expiresAt: 1 },
+      "https://example.com/mcp",
+    )
+    expect(yield* mcp.getAuthStatus("test-status-url")).toBe("expired")
+  }),
+)
+
+mcpTest.instance("authenticate() stores a connected client when auth completes without redirect", () =>
+  Effect.gen(function* () {
+    yield* stopOAuthCallback
+    const server = yield* serveOAuthMcp()
+    const mcp = yield* MCP.Service
+    const name = "test-oauth-connect"
+    const added = yield* mcp.add(name, remote(server.url))
+    expect((added.status as Record<string, { status: string }>)[name]?.status).toBe("needs_auth")
+
+    server.allowAnonymous()
+    expect((yield* mcp.authenticate(name)).status).toBe("connected")
+    expect((yield* mcp.status())[name]?.status).toBe("connected")
+  }),
+)
+
+mcpTest.instance("authenticate() connects a resource-only server without listing tools", () =>
+  Effect.gen(function* () {
+    yield* stopOAuthCallback
+    const server = yield* serveOAuthMcp({ capabilities: "resources" })
+    const mcp = yield* MCP.Service
+    const name = "test-oauth-resources"
+    const added = yield* mcp.add(name, remote(server.url))
+    expect((added.status as Record<string, { status: string }>)[name]?.status).toBe("needs_auth")
+
+    server.allowAnonymous()
+    expect((yield* mcp.authenticate(name)).status).toBe("connected")
+    expect(server.listToolsCalls()).toBe(0)
+    expect(Object.keys(yield* mcp.resources())).toEqual([`${name}:docs://readme`])
+  }),
+)

package/test/mcp/oauth-browser.test.ts

@@ -0,0 +1,225 @@
+import { expect } from "bun:test"
+import { Server } from "@modelcontextprotocol/sdk/server/index.js"
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js"
+import { ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js"
+import { LayerNode } from "@neurocode-ai/core/effect/layer-node"
+import { Deferred, Effect, Layer, Option } from "effect"
+import { Config } from "../../src/config/config"
+import { EventV2Bridge } from "../../src/event-v2-bridge"
+import { McpAuth } from "../../src/mcp/auth"
+import { McpBrowser } from "../../src/mcp/browser"
+import { MCP } from "../../src/mcp/index"
+import { McpOAuthCallback } from "../../src/mcp/oauth-callback"
+import { awaitWithTimeout, testEffect } from "../lib/effect"
+
+const browsers = new Map<string, { opened: Deferred.Deferred<string>; fail: boolean }>()
+
+const browserLayer = Layer.succeed(
+  McpBrowser.Service,
+  McpBrowser.Service.of({
+    open: (url) =>
+      Effect.gen(function* () {
+        const browser = browsers.get(new URL(url).origin)
+        if (!browser) return yield* Effect.fail(new Error(`Unexpected browser URL: ${url}`))
+        Deferred.doneUnsafe(browser.opened, Effect.succeed(url))
+        if (browser.fail) return yield* Effect.fail(new Error("spawn xdg-open ENOENT"))
+        yield* Effect.tryPromise({
+          try: () => fetch(url).then((response) => response.body?.cancel()),
+          catch: (error) => (error instanceof Error ? error : new Error(String(error))),
+        })
+      }),
+  }),
+)
+
+const mcpTest = testEffect(
+  LayerNode.compile(LayerNode.group([MCP.node, McpAuth.node, EventV2Bridge.node, Config.node]), [
+    [McpBrowser.node, browserLayer],
+  ]),
+)
+
+const serveOAuthMcp = Effect.acquireRelease(
+  Effect.promise(async () => {
+    const requests: Array<{ pathname: string; headers: Headers }> = []
+    const protocol = new Server({ name: "oauth-browser", version: "1.0.0" }, { capabilities: { tools: {} } })
+    protocol.setRequestHandler(ListToolsRequestSchema, () => Promise.resolve({ tools: [] }))
+    const transport = new WebStandardStreamableHTTPServerTransport({
+      sessionIdGenerator: () => crypto.randomUUID(),
+      enableJsonResponse: true,
+    })
+    await protocol.connect(transport)
+
+    const http = Bun.serve({
+      hostname: "127.0.0.1",
+      port: 0,
+      async fetch(request) {
+        const url = new URL(request.url)
+        requests.push({ pathname: url.pathname, headers: new Headers(request.headers) })
+
+        if (url.pathname === "/mcp") {
+          if (request.headers.get("authorization") === "Bearer test-access-token") {
+            return transport.handleRequest(request)
+          }
+          return new Response("Unauthorized", {
+            status: 401,
+            headers: {
+              "WWW-Authenticate": `Bearer resource_metadata="${url.origin}/.well-known/oauth-protected-resource/mcp", scope="mcp"`,
+            },
+          })
+        }
+
+        if (url.pathname === "/.well-known/oauth-protected-resource/mcp") {
+          return Response.json({
+            resource: `${url.origin}/mcp`,
+            authorization_servers: [url.origin],
+            scopes_supported: ["mcp"],
+          })
+        }
+
+        if (url.pathname === "/.well-known/oauth-authorization-server") {
+          return Response.json({
+            issuer: url.origin,
+            authorization_endpoint: `${url.origin}/authorize`,
+            token_endpoint: `${url.origin}/token`,
+            registration_endpoint: `${url.origin}/register`,
+            scopes_supported: ["mcp"],
+            response_types_supported: ["code"],
+            grant_types_supported: ["authorization_code"],
+            token_endpoint_auth_methods_supported: ["none"],
+            code_challenge_methods_supported: ["S256"],
+          })
+        }
+
+        if (url.pathname === "/register") {
+          const metadata = await request.json()
+          if (!metadata || typeof metadata !== "object") return new Response("Invalid metadata", { status: 400 })
+          return Response.json({ ...metadata, client_id: "test-client" }, { status: 201 })
+        }
+
+        if (url.pathname === "/authorize") {
+          const redirect = new URL(url.searchParams.get("redirect_uri") ?? "")
+          redirect.searchParams.set("code", "test-code")
+          const state = url.searchParams.get("state")
+          if (state) redirect.searchParams.set("state", state)
+          return Response.redirect(redirect, 302)
+        }
+
+        if (url.pathname === "/token") {
+          return Response.json({ access_token: "test-access-token", token_type: "Bearer", scope: "mcp" })
+        }
+
+        return new Response("Not found", { status: 404 })
+      },
+    })
+
+    return {
+      requests,
+      url: new URL("/mcp", http.url).toString(),
+      close: async () => {
+        await http.stop(true)
+        await protocol.close()
+      },
+    }
+  }),
+  (server) => Effect.promise(server.close),
+)
+
+const withCallbackStop = Effect.addFinalizer(() => Effect.promise(() => McpOAuthCallback.stop()).pipe(Effect.ignore))
+
+const trackBrowserOpen = (url: string, fail = false) =>
+  Effect.gen(function* () {
+    const origin = new URL(url).origin
+    const opened = yield* Deferred.make<string>()
+    browsers.set(origin, { opened, fail })
+    yield* Effect.addFinalizer(() => Effect.sync(() => browsers.delete(origin)))
+    return opened
+  })
+
+const trackBrowserOpenFailed = Effect.gen(function* () {
+  const events = yield* EventV2Bridge.Service
+  const event = yield* Deferred.make<{ mcpName: string; url: string }>()
+  const unsubscribe = yield* events.listen((evt) => {
+    if (evt.type === MCP.BrowserOpenFailed.type)
+      Deferred.doneUnsafe(event, Effect.succeed(evt.data as { mcpName: string; url: string }))
+    return Effect.void
+  })
+  yield* Effect.addFinalizer(() => unsubscribe)
+  return event
+})
+
+const addServer = Effect.fnUntraced(function* (name: string, url: string, headers?: Record<string, string>) {
+  const mcp = yield* MCP.Service
+  const result = yield* mcp.add(name, { type: "remote", url, headers })
+  expect(result.status).toMatchObject({ [name]: { status: "needs_auth" } })
+  return mcp
+})
+
+mcpTest.instance("BrowserOpenFailed event is published when browser launch fails", () =>
+  Effect.gen(function* () {
+    yield* withCallbackStop
+    const server = yield* serveOAuthMcp
+    yield* trackBrowserOpen(server.url, true)
+
+    const event = yield* trackBrowserOpenFailed
+    const mcp = yield* addServer("test-oauth-server", server.url)
+    yield* mcp.authenticate("test-oauth-server").pipe(Effect.ignore, Effect.forkScoped)
+
+    const failure = yield* awaitWithTimeout(
+      Deferred.await(event),
+      "Timed out waiting for BrowserOpenFailed event",
+      "5 seconds",
+    )
+
+    expect(failure.mcpName).toBe("test-oauth-server")
+    expect(failure.url).toStartWith(new URL("/authorize", server.url).toString())
+  }),
+)
+
+mcpTest.instance("BrowserOpenFailed event is not published when browser launch succeeds", () =>
+  Effect.gen(function* () {
+    yield* withCallbackStop
+    const server = yield* serveOAuthMcp
+
+    const opened = yield* trackBrowserOpen(server.url)
+    const event = yield* trackBrowserOpenFailed
+    const mcp = yield* addServer("test-oauth-server-2", server.url)
+    const status = yield* awaitWithTimeout(
+      mcp.authenticate("test-oauth-server-2"),
+      "Timed out completing OAuth authentication",
+      "5 seconds",
+    )
+    const url = yield* Deferred.await(opened)
+    const failure = yield* Deferred.await(event).pipe(Effect.timeoutOption("700 millis"))
+
+    expect(status).toEqual({ status: "connected" })
+    expect(failure).toEqual(Option.none())
+    expect(new URL(url).origin).toBe(new URL(server.url).origin)
+  }),
+)
+
+mcpTest.instance("browser launch receives the discovered authorization URL", () =>
+  Effect.gen(function* () {
+    yield* withCallbackStop
+    const server = yield* serveOAuthMcp
+
+    const opened = yield* trackBrowserOpen(server.url)
+    const authorization = yield* Deferred.make<string>()
+    const mcp = yield* addServer("test-oauth-server-3", server.url, { "X-Custom-Header": "custom-value" })
+    const status = yield* awaitWithTimeout(
+      mcp.authenticate("test-oauth-server-3", (url) => Deferred.doneUnsafe(authorization, Effect.succeed(url))),
+      "Timed out completing OAuth authentication",
+      "5 seconds",
+    )
+    const url = yield* Deferred.await(opened)
+    const authorizationUrl = yield* Deferred.await(authorization)
+
+    expect(status).toEqual({ status: "connected" })
+    expect(authorizationUrl).toBe(url)
+    expect(new URL(url).pathname).toBe("/authorize")
+    expect(new URL(url).searchParams.get("client_id")).toBe("test-client")
+    expect(
+      server.requests.some(
+        (request) => request.pathname === "/mcp" && request.headers.get("x-custom-header") === "custom-value",
+      ),
+    ).toBe(true)
+  }),
+)

package/test/mcp/oauth-callback.test.ts

@@ -0,0 +1,114 @@
+import { test, expect, describe, afterEach } from "bun:test"
+import { createConnection, createServer as createNetServer } from "net"
+import { McpOAuthCallback } from "../../src/mcp/oauth-callback"
+import { parseRedirectUri } from "../../src/mcp/oauth-provider"
+
+async function getFreeLoopbackPort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const probe = createNetServer()
+    probe.once("error", reject)
+    probe.listen(0, "127.0.0.1", () => {
+      const address = probe.address()
+      probe.close(() => {
+        if (typeof address === "object" && address) {
+          resolve(address.port)
+          return
+        }
+        reject(new Error("Could not allocate a loopback port"))
+      })
+    })
+  })
+}
+
+async function canConnect(host: string, port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = createConnection({ host, port })
+    const done = (ok: boolean) => {
+      socket.removeAllListeners()
+      socket.destroy()
+      resolve(ok)
+    }
+
+    socket.setTimeout(500)
+    socket.once("connect", () => done(true))
+    socket.once("error", () => done(false))
+    socket.once("timeout", () => done(false))
+  })
+}
+
+describe("parseRedirectUri", () => {
+  test("returns defaults when no URI provided", () => {
+    const result = parseRedirectUri()
+    expect(result.port).toBe(19876)
+    expect(result.path).toBe("/mcp/oauth/callback")
+  })
+
+  test("parses port and path from URI", () => {
+    const result = parseRedirectUri("http://127.0.0.1:8080/oauth/callback")
+    expect(result.port).toBe(8080)
+    expect(result.path).toBe("/oauth/callback")
+  })
+
+  test("returns defaults for invalid URI", () => {
+    const result = parseRedirectUri("not-a-valid-url")
+    expect(result.port).toBe(19876)
+    expect(result.path).toBe("/mcp/oauth/callback")
+  })
+})
+
+describe("McpOAuthCallback.ensureRunning", () => {
+  afterEach(async () => {
+    await McpOAuthCallback.stop()
+  })
+
+  test("starts server with custom redirectUri port and path", async () => {
+    await McpOAuthCallback.ensureRunning("http://127.0.0.1:18000/custom/callback")
+    expect(McpOAuthCallback.isRunning()).toBe(true)
+  })
+
+  test("stops after the callback completes", async () => {
+    const redirectUri = "http://127.0.0.1:18003/custom/callback"
+    await McpOAuthCallback.ensureRunning(redirectUri)
+    const callback = McpOAuthCallback.waitForCallback("success")
+
+    const response = await fetch(`${redirectUri}?code=code&state=success`)
+
+    expect(response.status).toBe(200)
+    expect(await callback).toBe("code")
+    expect(McpOAuthCallback.isRunning()).toBe(false)
+  })
+
+  test("escapes provider error markup in callback HTML", async () => {
+    const redirectUri = "http://127.0.0.1:18001/custom/callback"
+    await McpOAuthCallback.ensureRunning(redirectUri)
+
+    const error = `<script>alert("xss" & 'more')</script>`
+    const response = await fetch(
+      `${redirectUri}?state=test&error=access_denied&error_description=${encodeURIComponent(error)}`,
+    )
+    const body = await response.text()
+
+    expect(response.headers.get("content-type")).toBe("text/html; charset=utf-8")
+    expect(body).toContain("&lt;script&gt;alert(&quot;xss&quot; &amp; &#39;more&#39;)&lt;/script&gt;")
+    expect(body).not.toContain(error)
+  })
+
+  test("keeps normal provider errors readable", async () => {
+    const redirectUri = "http://127.0.0.1:18002/custom/callback"
+    await McpOAuthCallback.ensureRunning(redirectUri)
+
+    const response = await fetch(
+      `${redirectUri}?state=test&error=access_denied&error_description=${encodeURIComponent("The user denied access")}`,
+    )
+
+    expect(await response.text()).toContain('<pre class="detail" id="oc-detail">The user denied access</pre>')
+  })
+
+  test("binds the callback server to IPv4 loopback", async () => {
+    const port = await getFreeLoopbackPort()
+    await McpOAuthCallback.ensureRunning(`http://127.0.0.1:${port}/custom/callback`)
+
+    expect(await canConnect("127.0.0.1", port)).toBe(true)
+    expect(await canConnect("::1", port)).toBe(false)
+  })
+})