hermes-agent/apps/desktop/electron/mcp-oauth-callback-ipc.ts
OOOOOAO 1a6503a520 fix(mcp): thread RFC 9207 iss through every OAuth callback relay
mcp 2.x rejects an authorization response that omits the RFC 9207 `iss`
parameter when the authorization server advertised
`authorization_response_iss_parameter_supported`. Cloudflare advertises it
AND sends it; the CLI loopback handler has always forwarded it, but every
other callback producer parsed only code/state/error, so the SDK raised:

    OAuthFlowError: Authorization response missing iss parameter
    advertised by the authorization server

and the server parked. Same machine, same config, `hermes mcp login <name>`
from a terminal succeeded — the failure is specific to the non-CLI relays.

Forward `iss` on every producer, matching `_make_callback_handler()`:

- tools/mcp_dashboard_oauth.py: `deliver_callback()` accepts `iss`;
  `wait_for_callback()` returns `(code, state, iss)`. The bridge in
  tools/mcp_oauth.py already splats that tuple into
  `_authorization_code_result(code, state, iss)`, so it needs no change.
- tui_gateway/mcp_oauth_sessions.py: the gateway-hosted loopback listener
  parses `iss`, and `deliver_callback_flow()` forwards it.
- tui_gateway/methods_tools.py: the `oauth.callback` RPC passes `iss`.
- hermes_cli/web_routers/mcp.py: the dashboard callback route accepts it.
- apps/desktop/electron/mcp-oauth-callback-ipc.ts: the one-shot listener
  reads `iss` off the redirect (the renderer already spreads the whole
  callback object into the RPC, so it flows through unchanged).

Providers that omit `iss` round-trip as `None`/`null` rather than being
dropped, so servers that do not advertise RFC 9207 keep working.

Verified live on Windows against mcp.cloudflare.com, whose metadata sets
`authorization_response_iss_parameter_supported: true`: the server that
previously parked on the missing-iss error now reports
`Authenticated — 3452 tool(s) available` and `hermes mcp test cloudflare`
connects. State-mismatch and replay rejection are unchanged.

Tests (each fails on base, passes with the fix):
- test_dashboard_flow_preserves_rfc9207_iss
- test_deliver_callback_forwards_iss (client-redirect relay)
- test_loopback_listener_forwards_iss (real HTTP redirect)
- two vitest cases on the Electron listener, incl. the iss-absent case

Refs #92758, #99984. PR #92765 fixes the dashboard route and the loopback
listener but not the client-redirect relay
(`deliver_callback_flow` / `oauth.callback` / the Electron listener), which
is the path Desktop drives against a remote backend.
2026-09-15 13:00:12 +05:30

187 lines
5.4 KiB
TypeScript

/**
* mcp-oauth-callback-ipc.ts
*
* Client-side loopback callback listener for MCP OAuth against a REMOTE
* backend. The gateway's own `mcp.servers.oauth.start` flow binds its
* callback listener on the BACKEND machine's 127.0.0.1 — unreachable from
* the user's browser when Desktop connects over SSH/Tailscale, so the
* provider redirect dies on the user's machine and the flow times out.
*
* This module gives the renderer the same primitive the native gateway
* login uses (native-oauth-login.ts): bind an ephemeral one-shot listener
* on the USER'S loopback, hand its URL to the gateway as the OAuth
* redirect_uri (`client_redirect_uri` on oauth.start), and resolve with the
* redirect's `code`/`state` so the renderer can relay them via
* `mcp.servers.oauth.callback`.
*
* Security posture:
* - binds 127.0.0.1 on an ephemeral port; closes on first callback,
* cancel, or timeout — no long-lived listener;
* - the listener only ever RECEIVES `code`/`state` query params and
* forwards them to the renderer; no tokens are exchanged here — the
* gateway verifies `state` (constant-time) before redeeming anything;
* - the browser sees only a minimal "return to Hermes" page.
*/
import http from 'node:http'
import type { AddressInfo } from 'node:net'
import { ipcMain } from 'electron'
const DEFAULT_WAIT_TIMEOUT_MS = 5 * 60 * 1000
const MAX_PENDING_LISTENERS = 8
const DONE_HTML =
'<!doctype html><meta charset="utf-8"><title>Authorization received</title>' +
'<body style="font:15px system-ui;margin:3rem;text-align:center">' +
'<h2>&#10003; Authorization received</h2>' +
'<p>You can close this window and return to Hermes.</p>' +
'<script>setTimeout(()=>window.close(),800)</script>'
interface CallbackResult {
code: null | string
error: null | string
// RFC 9207 issuer identifier. Cloudflare and Resend advertise
// `authorization_response_iss_parameter_supported`, and mcp 2.x rejects an
// authorization response that omits it — relay it rather than dropping it.
iss: null | string
state: null | string
}
interface PendingListener {
result: CallbackResult | null
server: http.Server
settled: boolean
waiters: Array<(result: CallbackResult) => void>
}
const pending = new Map<string, PendingListener>()
let nextId = 1
function settle(id: string, result: CallbackResult) {
const entry = pending.get(id)
if (!entry || entry.settled) {
return
}
entry.settled = true
entry.result = result
try {
entry.server.close()
} catch {
// already closed
}
for (const waiter of entry.waiters.splice(0)) {
waiter(result)
}
}
function dispose(id: string) {
const entry = pending.get(id)
if (!entry) {
return
}
if (!entry.settled) {
settle(id, { code: null, error: 'cancelled', iss: null, state: null })
}
pending.delete(id)
}
export function registerMcpOauthCallbackIpc() {
// Bind a one-shot loopback listener; resolves { id, redirectUri }.
ipcMain.handle('hermes:mcp-oauth:listen', async () => {
if (pending.size >= MAX_PENDING_LISTENERS) {
throw new Error('Too many MCP OAuth listeners are already pending')
}
const id = String(nextId++)
const server = http.createServer((req, res) => {
res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' })
res.end(DONE_HTML)
const url = req.url || '/'
// Ignore favicon and other noise — wait for the ?code= / ?error= hit.
if (!/[?&](code|error)=/.test(url)) {
return
}
let code: null | string = null
let state: null | string = null
let error: null | string = null
let iss: null | string = null
try {
const parsed = new URL(url, 'http://127.0.0.1')
code = parsed.searchParams.get('code')
state = parsed.searchParams.get('state')
error = parsed.searchParams.get('error')
iss = parsed.searchParams.get('iss')
} catch {
error = 'unparseable callback URL'
}
settle(id, { code, error, iss, state })
})
await new Promise<void>((resolve, reject) => {
server.once('error', reject)
server.listen(0, '127.0.0.1', () => resolve())
})
const port = (server.address() as AddressInfo).port
pending.set(id, { result: null, server, settled: false, waiters: [] })
return { id, redirectUri: `http://127.0.0.1:${port}/callback` }
})
// Resolve when the redirect arrives (or timeout). Safe to call once per id.
ipcMain.handle('hermes:mcp-oauth:wait', async (_event, id, timeoutMs) => {
const entry = pending.get(String(id || ''))
if (!entry) {
return { code: null, error: 'listener not found', iss: null, state: null }
}
if (entry.result) {
const result = entry.result
pending.delete(String(id))
return result
}
const timeout = Math.min(Math.max(Number(timeoutMs) || DEFAULT_WAIT_TIMEOUT_MS, 1000), 15 * 60 * 1000)
const result = await new Promise<CallbackResult>(resolve => {
const timer = setTimeout(() => {
settle(String(id), { code: null, error: 'timeout waiting for OAuth callback', iss: null, state: null })
}, timeout)
entry.waiters.push(value => {
clearTimeout(timer)
resolve(value)
})
})
pending.delete(String(id))
return result
})
// Tear a listener down without waiting (user cancelled, flow errored).
ipcMain.handle('hermes:mcp-oauth:cancel', (_event, id) => {
dispose(String(id || ''))
return true
})
}