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
+12 -2
View File
@@ -42,6 +42,7 @@ from fluksio.api.deps import (
get_current_active_superuser,
get_current_user,
)
from fluksio.cloud import config as cloud_config
from fluksio.core import security
from fluksio.core.config import settings
from fluksio.models import (
@@ -301,13 +302,22 @@ def authorize_validate(
@router.post("/authorize", response_model=OAuthAuthorizeResponse)
def authorize(
request: Request,
body: OAuthAuthorizeRequest,
current_user: CurrentUser,
session: SessionDep,
) -> Any:
"""Approve a client, on behalf of the signed-in user."""
"""Approve a client, on behalf of the signed-in user.
Through the hub the endpoint is the one there, which is the resource an
agent that came that way asks for.
"""
if not settings.MCP_ENABLED:
return _error("access_denied", "The MCP endpoint is switched off.", 403)
resources = {settings.mcp_resource}
base = cloud_config.portal_base(request.headers)
if base is not None:
resources.add(f"{base}/mcp")
client = _load_client(session, body.client_id)
if client is None:
@@ -318,7 +328,7 @@ def authorize(
return _error("invalid_request", "PKCE must use S256.")
if not _PKCE_RE.match(body.code_challenge):
return _error("invalid_request", "Malformed code challenge.")
if body.resource and body.resource.rstrip("/") != settings.mcp_resource:
if body.resource and body.resource.rstrip("/") not in resources:
return _error("invalid_target", "Unknown resource.")
code = secrets.token_urlsafe(32)
+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
+12 -5
View File
@@ -400,11 +400,18 @@ class HttpNode(Node):
:returns: JSON response with trigger result.
:rtype: JSONResponse
"""
if self.secret and not hmac.compare_digest(
str(request.path_params.get("secret", "")).encode(),
self.secret.encode(),
):
# A wrong secret must look like no such hook at all.
from fluksio.cloud.config import via_portal
if (
self.secret
and not hmac.compare_digest(
str(request.path_params.get("secret", "")).encode(),
self.secret.encode(),
)
) or (not self.secret and via_portal(request.headers)):
# A wrong secret must look like no such hook at all, and so must
# a hook without one reached through the portal, which would
# otherwise be open to the whole internet.
return JSONResponse(content={"detail": "Not Found"}, status_code=404)
try:
+10 -4
View File
@@ -342,11 +342,17 @@ class WebSocketNode(Node):
async def _serve(self, websocket: WebSocket) -> None:
"""One client of a served socket, for as long as it stays."""
if self.secret and not hmac.compare_digest(
str(websocket.path_params.get("secret", "")).encode(),
self.secret.encode(),
):
from fluksio.cloud.config import via_portal
if (
self.secret
and not hmac.compare_digest(
str(websocket.path_params.get("secret", "")).encode(),
self.secret.encode(),
)
) or (not self.secret and via_portal(websocket.headers)):
# Closed before accepting: the same 403 as a path with no route.
# Through the portal a socket needs a secret, as a webhook does.
await websocket.close(code=1008)
return
await websocket.accept()
+13 -5
View File
@@ -540,19 +540,27 @@ async def rebuild_busy(request: Request, exc: RebuildBusy) -> JSONResponse: # n
include_in_schema=False,
tags=["oauth"],
)
def oauth_authorization_server() -> JSONResponse:
def oauth_authorization_server(request: Request) -> JSONResponse:
"""RFC 8414 metadata, so an agent can find its way in unaided.
The authorization endpoint is the dashboard rather than the API: approving
a client needs a signed-in human, and the browser session lives there.
Through the hub that is the dashboard the portal opens, which the hub names
when the link attaches; the hub's own address is the guess an older one
leaves.
"""
issuer = settings.oauth_issuer
from fluksio.cloud import config as cloud_config
base = cloud_config.portal_base(request.headers)
issuer = base or settings.oauth_issuer
dashboard = settings.FRONTEND_HOST.rstrip("/")
if base is not None:
connector = getattr(request.app.state, "cloud_connector", None)
dashboard = getattr(connector, "app_url", None) or base
return JSONResponse(
content={
"issuer": issuer,
"authorization_endpoint": (
f"{settings.FRONTEND_HOST.rstrip('/')}/oauth/authorize"
),
"authorization_endpoint": f"{dashboard}/oauth/authorize",
"token_endpoint": f"{issuer}{settings.API_V1_STR}/oauth/token",
"registration_endpoint": f"{issuer}{settings.API_V1_STR}/oauth/register",
"jwks_uri": f"{issuer}/.well-known/jwks.json",
+73 -5
View File
@@ -4,6 +4,9 @@ The transport is streamable HTTP, stateless, one JSON response per call: no
sticky sessions to route and nothing for a proxy to buffer. The SDK serves both
``/mcp`` and the protected-resource metadata beside it, which is why the sub-app
is mounted at the root rather than under ``/mcp``.
An enrolled instance also answers at ``/i/{id}/mcp`` on its hub, so an agent
that came through the tunnel is shown the hub's addresses instead.
"""
from __future__ import annotations
@@ -14,12 +17,16 @@ from urllib.parse import urlparse
import jwt
from fastapi.concurrency import run_in_threadpool
from mcp.server.auth.provider import AccessToken
from mcp.server.auth.routes import build_resource_metadata_url
from mcp.server.auth.settings import AuthSettings
from mcp.server.transport_security import TransportSecuritySettings
from pydantic import AnyHttpUrl
from starlette.applications import Starlette
from starlette.datastructures import Headers
from starlette.responses import JSONResponse
from starlette.types import ASGIApp, Message, Receive, Scope, Send
from fluksio.api.deps import oauth_client_lives
from fluksio.cloud import config as cloud_config
from fluksio.core import security
from fluksio.core.config import settings
from fluksio.mcp import server
@@ -67,6 +74,20 @@ class _JWTVerifier:
)
class _AndTheHub(list[str]):
"""The hosts named here, plus the hub's while this instance is enrolled.
A call through the tunnel is addressed to the hub, as its Host says. The
hub is looked up per request, since enrolment comes and goes while the
endpoint is up. Its origin is not needed: the hub never forwards one.
"""
def __contains__(self, host: object) -> bool:
config = cloud_config.load()
hub = urlparse(config.issuer).netloc if config is not None else None
return super().__contains__(host) or (hub is not None and host == hub)
def _transport_security() -> TransportSecuritySettings:
"""Which Host headers to trust.
@@ -87,14 +108,61 @@ def _transport_security() -> TransportSecuritySettings:
"testserver",
]
allowed_origins += ["http://localhost", "http://127.0.0.1"]
return TransportSecuritySettings(
# Unvalidated, since validating would copy the hosts into a plain list.
return TransportSecuritySettings.model_construct(
enable_dns_rebinding_protection=True,
allowed_hosts=allowed_hosts,
allowed_hosts=_AndTheHub(allowed_hosts),
allowed_origins=allowed_origins,
)
def build_http_app(app: object) -> Starlette:
class _ThroughThePortal:
"""Show an agent that came through the hub the hub's addresses.
The SDK builds its metadata once, for the API host, and names it in every
401. An agent at ``/i/{id}/mcp`` on the hub cannot reach that host, so its
discovery has to lead to the hub's documents instead.
"""
def __init__(self, app: ASGIApp) -> None:
self.app = app
async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
base = None
if scope["type"] == "http":
base = cloud_config.portal_base(Headers(scope=scope))
if base is None:
await self.app(scope, receive, send)
return
if scope["path"] == "/.well-known/oauth-protected-resource/mcp":
document = {
"resource": f"{base}/mcp",
"authorization_servers": [base],
"bearer_methods_supported": ["header"],
}
headers = {"Cache-Control": "public, max-age=3600"}
await JSONResponse(document, headers=headers)(scope, receive, send)
return
here = str(build_resource_metadata_url(AnyHttpUrl(settings.mcp_resource)))
there = str(build_resource_metadata_url(AnyHttpUrl(f"{base}/mcp")))
async def send_theirs(message: Message) -> None:
if message["type"] == "http.response.start":
message["headers"] = [
(
key,
value.replace(here.encode(), there.encode())
if key == b"www-authenticate"
else value,
)
for key, value in message["headers"]
]
await send(message)
await self.app(scope, receive, send_theirs)
def build_http_app(app: object) -> ASGIApp:
"""The MCP sub-app, wired to this app's API and its OAuth server."""
server.mcp.settings.stateless_http = True
server.mcp.settings.json_response = True
@@ -109,4 +177,4 @@ def build_http_app(app: object) -> Starlette:
server.mcp._token_verifier = _JWTVerifier() # noqa: SLF001
server.connect(app)
return server.mcp.streamable_http_app()
return _ThroughThePortal(server.mcp.streamable_http_app())