Serve MCP and hooks with a secret through the portal tunnel

The connector now serves /mcp, its OAuth documents and /hooks/ besides
/api/v1/, refuses any dot segment (httpx resolves them, which carried
/api/v1/../../mcp onto the MCP mount), addresses calls to the hub's host,
and bridges served sockets by calling the app with a websocket scope.
A hook without a secret answers the tunnel with the 404 (or 1008) of a
wrong secret. Requests through the hub get the hub's issuer, resource and
consent page in the OAuth metadata and the 401, and the MCP host check
admits the hub while enrolled.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WgBfkm4rCmtd1T4vHWjEPx
This commit is contained in:
2026-10-15 11:00:19 +02:00
co-authored by Claude Opus 5.5
parent 7a56818213
commit 391edc8766
14 changed files with 526 additions and 31 deletions
+18
View File
@@ -20,6 +20,7 @@ import json
import logging
import os
import secrets
from collections.abc import Mapping
from dataclasses import dataclass
from typing import Any
@@ -114,6 +115,23 @@ def delete() -> None:
_cache = None
def via_portal(headers: Mapping[str, str]) -> bool:
"""Whether the connector replayed this request off the tunnel."""
return secrets.compare_digest(headers.get(VIA_HEADER, ""), VIA_PORTAL)
def portal_base(headers: Mapping[str, str]) -> str | None:
"""Where this instance answers at the hub, for a request that came through it.
The hub serves an instance under ``/i/{id}`` on the host it signs as, the
issuer enrolment pinned. ``None`` for a request made here.
"""
config = _read()
if config is None or not via_portal(headers):
return None
return f"{config.issuer.rstrip('/')}/i/{config.instance_id}"
def decode_portal_token(token: str) -> dict[str, Any]:
"""Validate a token the portal minted for this instance.
+130 -8
View File
@@ -22,6 +22,7 @@ import logging
import random
import time
import uuid
from collections.abc import MutableMapping
from dataclasses import replace
from datetime import timedelta
from typing import Any
@@ -53,9 +54,20 @@ PING_INTERVAL_S = 20.0
PING_TIMEOUT_S = 20.0
CHUNK_BYTES = 256 * 1024
MAX_WS_MESSAGE = 1024 * 1024
#: Only the versioned API is served over the tunnel. The MCP mount and the
#: OAuth endpoints live outside it and stay local-only.
ALLOWED_PREFIX = "/api/v1/"
#: What the tunnel serves: the versioned API, which the hub opens only to a
#: portal session; the MCP endpoint and the OAuth documents leading an agent
#: to it, which take the agent's own token; and the flows' hooks, of which
#: only those with a secret answer a request from the tunnel. Everything else,
#: the API docs included, stays on this machine.
ALLOWED_PREFIXES = ("/api/v1/", "/hooks/")
ALLOWED_PATHS = frozenset(
{
"/mcp",
"/.well-known/oauth-protected-resource/mcp",
"/.well-known/oauth-authorization-server",
"/.well-known/jwks.json",
}
)
#: Proxied calls, and bridged streams, this instance will run at once.
#: Neither dict was bounded, and an id the hub reused silently dropped the
#: reference to a task that was still running.
@@ -143,6 +155,11 @@ class CloudConnector:
self._revoked = False
#: The portal account that owns this instance, as the last welcome said.
self._owner: str | None = None
#: Where the portal opens this instance, as the last welcome said. An
#: older hub does not say.
self.app_url: str | None = None
#: What the hub sent each bridged hook socket, waiting to be received.
self._inboxes: dict[str, asyncio.Queue[dict[str, Any]]] = {}
@property
def revoked(self) -> bool:
@@ -240,6 +257,7 @@ class CloudConnector:
)
self._owner = welcome.get("owner")
self.app_url = welcome.get("app_url")
self._adopt_owner(config, self._owner)
self._adopt_jwks(welcome.get("jwks"))
@@ -260,6 +278,15 @@ class CloudConnector:
self._cancel(str(frame.get("id") or ""))
elif op == "ws_open":
self._start_stream(socket, frame)
elif op == "ws_msg":
inbox = self._inboxes.get(str(frame.get("id") or ""))
if inbox is not None:
inbox.put_nowait(
{
"type": "websocket.receive",
"text": str(frame.get("text") or ""),
}
)
elif op == "ws_close":
self._cancel_stream(str(frame.get("id") or ""))
elif op == "member_removed":
@@ -506,10 +533,10 @@ class CloudConnector:
call_id = str(frame["id"])
path = str(frame.get("path") or "")
try:
if not path.startswith(ALLOWED_PREFIX):
# Defence in depth: the hub only ever forwards API paths, and
# an instance that trusted anything else would be an SSRF
# gadget aimed at its own process.
if not _allowed(path):
# Defence in depth: the hub forwards nothing else, and an
# instance that trusted it to would be an SSRF gadget aimed at
# its own process.
await socket.send(
_dump({"op": "err", "id": call_id, "message": "path not allowed"})
)
@@ -525,6 +552,9 @@ class CloudConnector:
# is the only thing that makes it true, and the value is this
# process's own so nothing off the network can imitate it.
headers[cloud_config.VIA_HEADER] = cloud_config.VIA_PORTAL
# Addressed as the caller addressed it, which is the hub. The MCP
# endpoint checks the Host against the names it answers to.
headers["host"] = _hub_host()
async with self._client() as client:
request = client.build_request(
@@ -619,13 +649,16 @@ class CloudConnector:
stream_id = str(frame["id"])
path = str(frame.get("path") or "")
query = str(frame.get("query") or "")
if _allowed(path) and path.startswith("/hooks/"):
await self._hook_stream(socket, stream_id, path, query)
return
# The browser's ticket when it brought one; the hub restates the
# session it checked as `token` either way, which is the tunnel's own
# channel and stays when the public `?token=` goes.
ticket = _query_value(query, "ticket")
token = redeem_ticket(ticket) if ticket else _query_value(query, "token")
if not path.startswith(ALLOWED_PREFIX) or not path.endswith("/flows/ws"):
if not path.startswith("/api/v1/") or not path.endswith("/flows/ws"):
await socket.send(_dump({"op": "ws_close", "id": stream_id, "code": 1008}))
return
with Session(engine) as session:
@@ -687,12 +720,101 @@ class CloudConnector:
_dump({"op": "ws_close", "id": stream_id, "code": 1011})
)
async def _hook_stream(
self, socket: Any, stream_id: str, path: str, query: str
) -> None:
"""Serve a flow's socket over the tunnel, as uvicorn would serve it here.
The app is called with a websocket scope of its own, so the route a hook
installed answers exactly as it does a local client, secret included.
"""
inbox: asyncio.Queue[dict[str, Any]] = asyncio.Queue()
inbox.put_nowait({"type": "websocket.connect"})
self._inboxes[stream_id] = inbox
state = {"accepted": False, "closed": False}
async def send(message: MutableMapping[str, Any]) -> None:
kind = message["type"]
if kind == "websocket.accept":
state["accepted"] = True
await socket.send(_dump({"op": "ws_open_ok", "id": stream_id}))
elif kind == "websocket.send":
text = message.get("text")
if text is None:
text = (message.get("bytes") or b"").decode(errors="replace")
await socket.send(
_dump({"op": "ws_msg", "id": stream_id, "text": text})
)
elif kind == "websocket.close":
state["closed"] = True
# Refused before it was accepted is a refusal whatever the code,
# so no route, a wrong secret and no secret all look alike.
code = message.get("code", 1000) if state["accepted"] else 1008
await socket.send(
_dump({"op": "ws_close", "id": stream_id, "code": code})
)
scope = {
"type": "websocket",
"asgi": {"version": "3.0"},
"http_version": "1.1",
"scheme": "ws",
"path": path,
"raw_path": path.encode(),
"root_path": "",
"query_string": query.encode(),
"headers": [
(b"host", _hub_host().encode()),
(cloud_config.VIA_HEADER.encode(), cloud_config.VIA_PORTAL.encode()),
],
"client": ("127.0.0.1", 0),
"server": None,
"subprotocols": [],
}
code = 1000
try:
await self._app(scope, inbox.get, send)
except asyncio.CancelledError:
raise
except Exception as exc:
logger.debug("Hook stream %s ended: %s", stream_id, exc)
code = 1011
finally:
self._inboxes.pop(stream_id, None)
if not state["closed"]:
with contextlib.suppress(Exception):
await socket.send(
_dump({"op": "ws_close", "id": stream_id, "code": code})
)
def _cancel_stream(self, stream_id: str) -> None:
task = self._streams.pop(stream_id, None)
if task is not None:
task.cancel()
def _allowed(path: str) -> bool:
"""Whether the tunnel may serve this path.
A dot segment is refused, literal or encoded: httpx resolves a literal one
before dispatching, so ``/hooks/../api/v1/…`` would otherwise reach the API
as a path the hub forwarded without a session.
"""
from urllib.parse import unquote
if {".", ".."} & set(unquote(path).split("/")):
return False
return path in ALLOWED_PATHS or path.startswith(ALLOWED_PREFIXES)
def _hub_host() -> str:
"""The host a caller addressed through the tunnel, the hub's own."""
from urllib.parse import urlsplit
config = cloud_config.load()
return urlsplit(config.issuer).netloc if config is not None else "instance.local"
def _is_revoked(exc: Exception) -> bool:
"""Whether the hub closed the link as revoked, at the handshake or later."""
from websockets.exceptions import ConnectionClosed