From 90e97830f16c8ef00674f82e11ac50cc0305189c Mon Sep 17 00:00:00 2001 From: Adeel Ahmad Date: Fri, 2 Oct 2026 14:12:46 +0000 Subject: [PATCH] fix(mcp): check the token's audience, cap body reads and batches - Carry an app's RFC 8707 resource from the code onto its grant and its access and refresh tokens (renewals keep it), and expose it on the Principal. /mcp refuses an lo_ token whose resource names another server (Lens and its /mcp, on any address Lens is reached at, pass). - Check Content-Length and read the body as a capped stream, so a message over MAX_BODY is never held whole. - Cap JSON-RPC batches at 20 messages. - get_entity's mentions_offset gets search's 10000 maximum. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01TUqMhwUCvF9dsP5JzVvMJf --- CHANGELOG.md | 3 ++- docs/mcp.md | 5 ++-- fastapi_backend/app/api/deps.py | 3 ++- fastapi_backend/app/api/mcp.py | 35 +++++++++++++++++++++++++-- fastapi_backend/app/api/mcp_tools.py | 2 +- fastapi_backend/app/domain/oauth.py | 22 +++++++++++------ fastapi_backend/tests/api/test_mcp.py | 31 +++++++++++++++++++++++- 7 files changed, 85 insertions(+), 16 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index bc6b0ddd7..bd1918adb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,7 +12,8 @@ The backend (`fastapi_backend`) and the frontend (`nextjs-frontend`) are version time and a link, as Markdown), `list_entities`, `get_entity`, `explore_graph` and `find_path`. Links open the recording at that moment in the web app. Streamable HTTP without sessions, in both protocol eras (the 2025 `initialize` handshake and 2026-07-28's per-request envelope); an API token works for clients that can't sign in - (docs/mcp.md). + (docs/mcp.md). An app's token keeps the server it was asked for (`resource`, RFC 8707), and the MCP server refuses + one asked for another. - **Opt-in telemetry.** Lens can send OpenTelemetry traces and metrics about its own work to a collector you choose: API requests by route, jobs and each step, routines, workflow runs, and model calls with their tokens and an estimated cost (from per-model prices you set). It is off by default and never on unless you turn it on, in diff --git a/docs/mcp.md b/docs/mcp.md index 18e15f744..b299d544d 100644 --- a/docs/mcp.md +++ b/docs/mcp.md @@ -21,7 +21,8 @@ locally). Add it to the client as a remote (Streamable HTTP) server, and the cli Signing in is OAuth ([Authentication](authentication.md#oauth)): the client finds out where to sign in from the 401 it gets first (`WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource/mcp"`), registers itself, and opens Lens's consent page, where you sign in if you aren't and choose Allow. Read access is all it needs. -The client renews its token by itself; you see it under API tokens → Apps with access, and take its access away +A token an app asked for another server (its `resource`, RFC 8707) doesn't work here; one for Lens or for its +`/mcp` is fine. The client renews its token by itself; you see it under API tokens → Apps with access, and take its access away there. A client that can't sign in can send an API token instead (`Authorization: Bearer la_…`, made under API tokens), for @@ -71,5 +72,5 @@ Streamable HTTP without sessions: every request is a `POST /mcp` answered with J The `MCP-Protocol-Version` header decides the era: none or a handshake version is the first, anything else the second, where a version Lens doesn't speak is answered `-32022` with the ones it does. Requests from a browser must come from the web app's own address or one in `CORS_ORIGINS` (403 otherwise), which keeps other sites from using a -signed-in browser to reach it. Implemented in `fastapi_backend/app/api/mcp.py` (protocol) and `mcp_tools.py` (tools); +signed-in browser to reach it. A message may be 1 MB at most (413), and a batch 20 messages. Implemented in `fastapi_backend/app/api/mcp.py` (protocol) and `mcp_tools.py` (tools); the tests run the official MCP SDK's client against it in both eras. diff --git a/fastapi_backend/app/api/deps.py b/fastapi_backend/app/api/deps.py index 146254f5b..410142db8 100644 --- a/fastapi_backend/app/api/deps.py +++ b/fastapi_backend/app/api/deps.py @@ -52,6 +52,7 @@ class Principal: sid: str | None = None roles: dict[int, str] = field(default_factory=dict) collections: dict[int, dict[int, str]] = field(default_factory=dict) # roles on collections: {space: {collection: role}} + resource: str | None = None # an app's token: the server it was given for (RFC 8707), when the app named one @property def can_write(self) -> bool: @@ -76,7 +77,7 @@ def _principal(request: Request, db: DB) -> Principal | None: elif raw.startswith("lo_"): u = oauth.token_account(db, raw) if u: - p = Principal(u["id"], u["email"], u.get("name"), bool(u.get("admin")), "oauth", u["scope"]) + p = Principal(u["id"], u["email"], u.get("name"), bool(u.get("admin")), "oauth", u["scope"], resource=u.get("resource")) elif raw: claims = security.decode_access_token(raw) u = auth.active_account(db, claims.account) if claims and auth.session_active(db, claims.sid) else None diff --git a/fastapi_backend/app/api/mcp.py b/fastapi_backend/app/api/mcp.py index 4303da8c7..2f74f439b 100644 --- a/fastapi_backend/app/api/mcp.py +++ b/fastapi_backend/app/api/mcp.py @@ -49,6 +49,7 @@ HANDSHAKE = ("2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05") PER_REQUEST = ("2026-07-28",) MAX_BODY = 1_000_000 +MAX_BATCH = 20 # messages in one batch (2025-03-26), each of which may search SERVER_INFO = {"name": "lens", "title": settings.PROJECT_NAME, "version": __version__} CAPABILITIES = {"tools": {"listChanged": False}} INSTRUCTIONS = ( @@ -222,6 +223,31 @@ def handle_per_request(message: Any, request: Request, ctx: mcp_tools.Context) - return {"jsonrpc": "2.0", "id": mid, "result": result}, 200 +def _audience_ok(request: Request, resource: str | None) -> bool: + """An app's token that names the server it is for (RFC 8707) must name this one: Lens, or its MCP server, on any + address Lens is reached at. Tokens that name none (API tokens, apps that didn't say) are Lens's.""" + if resource is None: + return True + bases = {public_base(request), web_app_base(request), settings.FRONTEND_URL} + return resource.rstrip("/") in {b.rstrip("/") + end for b in bases for end in ("", PATH)} + + +async def _read(request: Request) -> bytes | None: + """The body, or None when it's more than MAX_BODY: told by Content-Length, or found while reading, so a large one + is never held whole.""" + try: + if int(request.headers.get("content-length") or 0) > MAX_BODY: + return None + except ValueError: + pass # a malformed length: reading tells + body = bytearray() + async for chunk in request.stream(): + body += chunk + if len(body) > MAX_BODY: + return None + return bytes(body) + + @router.post(PATH) async def post(request: Request, db: Db) -> Response: if not _origin_ok(request): @@ -232,8 +258,11 @@ async def post(request: Request, db: Db) -> Response: user = await run_in_threadpool(optional_user, request, db) # the database blocks if not user: raise HTTPException(401, "sign in first", headers={"WWW-Authenticate": "Bearer"}) - body = await request.body() - if len(body) > MAX_BODY: + if not _audience_ok(request, user.resource): + # a token an app was given for another server (RFC 8707) isn't one to use here; the app asks again for this one + raise HTTPException(401, "this token was given for another server", headers={"WWW-Authenticate": "Bearer"}) + body = await _read(request) + if body is None: return JSONResponse(Fault(INVALID_REQUEST, "the message is too large").error(None), status_code=413) try: message = json.loads(body) @@ -247,6 +276,8 @@ async def post(request: Request, db: Db) -> Response: if isinstance(message, list): if not message: return JSONResponse(Fault(INVALID_REQUEST, "an empty batch").error(None), status_code=400) + if len(message) > MAX_BATCH: + return JSONResponse(Fault(INVALID_REQUEST, f"a batch may hold {MAX_BATCH} messages at most").error(None), status_code=400) answers = [a for m in message if (a := await run_in_threadpool(handle, m, ctx)) is not None] return JSONResponse(answers) if answers else Response(status_code=202) answer = await run_in_threadpool(handle, message, ctx) diff --git a/fastapi_backend/app/api/mcp_tools.py b/fastapi_backend/app/api/mcp_tools.py index 8e8f08a7b..61b9fbbb5 100644 --- a/fastapi_backend/app/api/mcp_tools.py +++ b/fastapi_backend/app/api/mcp_tools.py @@ -748,7 +748,7 @@ def _entities( "it most, and the lines that mention it (newest first), each with a url to that moment.", Arg("entity_id", "integer", "the entity (from list_entities, get_recording or the graph)", required=True), Arg("mentions", "integer", "how many mentioning lines", default=10, minimum=0, maximum=100), - Arg("mentions_offset", "integer", "skip this many lines (for the next page)", default=0, minimum=0), + Arg("mentions_offset", "integer", "skip this many lines (for the next page)", default=0, minimum=0, maximum=10000), Arg("sort", "string", "the lines' order", default="newest", enum=("newest", "oldest", "most")), ) def get_entity(ctx: Context, entity_id: int, mentions: int, mentions_offset: int, sort: str) -> dict[str, Any]: diff --git a/fastapi_backend/app/domain/oauth.py b/fastapi_backend/app/domain/oauth.py index 68ceb0870..40f76ffa6 100644 --- a/fastapi_backend/app/domain/oauth.py +++ b/fastapi_backend/app/domain/oauth.py @@ -233,12 +233,13 @@ def _verifier_ok(verifier, challenge): return hmac.compare_digest(calc, challenge or "") -def _issue(db, cfg, grant, uid, scope): +def _issue(db, cfg, grant, uid, scope, resource=None): life = lifetimes(cfg) access, refresh = "lo_" + secrets.token_urlsafe(32), "lr_" + secrets.token_urlsafe(32) ttl = life["access_minutes"] * 60 ends = _later(life["refresh_days"] * 86400) - base = {"gid": grant, "account": uid, "scope": scope, "created_at": store.now()} + # resource: the server the tokens are for (RFC 8707), when the app named one; that server checks it + base = store.clean({"gid": grant, "account": uid, "scope": scope, "resource": resource, "created_at": store.now()}) # a grant revoked while its app was renewing gets nothing: the tokens hang off the grant if not db.rows("UPDATE $g SET expires_at = $ends RETURN id", g=R("oauth_grant", grant), ends=ends): raise OAuthError("invalid_grant", "this access was revoked") @@ -287,18 +288,22 @@ def exchange_code(db, cfg, client_id, client_secret, code, redirect_uri, verifie "name": c["name"], "uri": c.get("uri"), "scope": row["scope"], + "resource": row.get("resource"), "created_at": store.now(), }, c=R("oauth_client", c["id"]), ) - return _issue(db, cfg, gid, row["account"], row["scope"]), {"id": gid, "account": row["account"], "client": c["id"], "name": c["name"]} + tokens = _issue(db, cfg, gid, row["account"], row["scope"], row.get("resource")) + return tokens, {"id": gid, "account": row["account"], "client": c["id"], "name": c["name"]} def refresh(db, cfg, client_id, client_secret, raw): """A new pair for a refresh token, which then stops working. One that was swapped a while ago and comes back ends the grant: it was probably copied.""" c = _client(db, client_id, client_secret, check_secret=True) - t = db.one("SELECT gid, account, kind, scope, expires_at, rotated, rotated_at FROM $r", r=R("oauth_token", auth.sha(raw or ""))) + t = db.one( + "SELECT gid, account, kind, scope, resource, expires_at, rotated, rotated_at FROM $r", r=R("oauth_token", auth.sha(raw or "")) + ) g = db.one("SELECT client FROM $r", r=R("oauth_grant", t["gid"])) if t else None if not t or not g or t["kind"] != "refresh" or g["client"] != c["id"] or t["expires_at"] < store.now(): raise OAuthError("invalid_grant", "the refresh token is wrong, was revoked or has expired") @@ -318,14 +323,15 @@ def refresh(db, cfg, client_id, client_secret, raw): now=now, g=t["gid"], ) - return _issue(db, cfg, t["gid"], t["account"], t["scope"]) + return _issue(db, cfg, t["gid"], t["account"], t["scope"], t.get("resource")) def token_account(db, raw): - """The account an access token acts as ({…account, scope}), or None. Refresh tokens don't open the API.""" + """The account an access token acts as ({…account, scope, grant, resource}), or None. Refresh tokens don't open + the API. resource is the server the token was given for, when the app named one.""" if not raw or not raw.startswith("lo_"): return None - t = db.one("SELECT gid, account, kind, scope, expires_at FROM $r", r=R("oauth_token", auth.sha(raw))) + t = db.one("SELECT gid, account, kind, scope, resource, expires_at FROM $r", r=R("oauth_token", auth.sha(raw))) if not t or t["kind"] != "access" or t["expires_at"] < store.now(): return None u = auth.active_account(db, t["account"]) @@ -333,7 +339,7 @@ def token_account(db, raw): return None if not db.rows("UPDATE $r SET last_used_at = $n RETURN id", r=R("oauth_grant", t["gid"]), n=store.now()): return None # its grant is gone - return {**u, "scope": "write" if can_write(t["scope"]) else "read", "grant": t["gid"]} + return {**u, "scope": "write" if can_write(t["scope"]) else "read", "grant": t["gid"], "resource": t.get("resource")} # ---------- grants: the apps a person gave access to ---------- diff --git a/fastapi_backend/tests/api/test_mcp.py b/fastapi_backend/tests/api/test_mcp.py index ee17240cc..9930bff38 100644 --- a/fastapi_backend/tests/api/test_mcp.py +++ b/fastapi_backend/tests/api/test_mcp.py @@ -10,7 +10,7 @@ from fastapi.testclient import TestClient from app.api import mcp, mcp_tools -from tests.api.test_oauth import _bearer, _grant +from tests.api.test_oauth import O, _bearer, _grant from tests.helpers import login, make_user, seed MODERN = "2026-07-28" @@ -79,6 +79,26 @@ def test_clients_are_sent_to_sign_in(client, app, env): assert client.post("/mcp", headers=env["h"], json={"jsonrpc": "2.0", "id": 1, "method": "ping"}).status_code == 401 +def test_tokens_given_for_another_server(client, env): + # an app names the server it wants a token for (RFC 8707); one for Lens or its MCP server works here, on any + # address Lens is reached at, and keeps working when renewed + renew = lambda app, t: client.post( # noqa: E731 + f"{O}/token", data={"grant_type": "refresh_token", "client_id": app["client_id"], "refresh_token": t["refresh_token"]} + ) + for resource in ("http://127.0.0.1/mcp", "http://localhost:3000/mcp", "http://localhost:3000/", "http://127.0.0.1"): + app, t = _grant(client, env["hv"], scope="read", resource=resource) + assert rpc(client, _bearer(t), "ping")["result"] == {} + r = renew(app, t) + assert rpc(client, _bearer(r.json()), "ping")["result"] == {} + # one for another server is refused, renewed or not, and the app is told where to sign in for this one + app, t = _grant(client, env["hv"], scope="read", resource="https://elsewhere.example/mcp") + r = client.post("/mcp", headers=_bearer(t), json={"jsonrpc": "2.0", "id": 1, "method": "ping"}) + assert r.status_code == 401 and "oauth-protected-resource/mcp" in r.headers["www-authenticate"] + r = renew(app, t) + assert client.post("/mcp", headers=_bearer(r.json()), json={"jsonrpc": "2.0", "id": 1, "method": "ping"}).status_code == 401 + assert client.get("/api/v1/auth/me", headers=_bearer(r.json())).status_code == 200 # the check is the MCP server's + + def test_the_transport(client, env): h = env["h"] post = lambda body, **hd: client.post("/mcp", headers={**h, **hd}, content=body if isinstance(body, str) else json.dumps(body)) # noqa: E731 @@ -89,6 +109,14 @@ def test_the_transport(client, env): r = post([{"jsonrpc": "2.0", "id": 1, "method": "ping"}, {"jsonrpc": "2.0", "method": "notifications/initialized"}]) assert r.json() == [{"jsonrpc": "2.0", "id": 1, "result": {}}] assert post([]).status_code == 400 + assert post([{"jsonrpc": "2.0", "id": i, "method": "ping"} for i in range(mcp.MAX_BATCH)]).status_code == 200 + r = post([{"jsonrpc": "2.0", "id": i, "method": "ping"} for i in range(mcp.MAX_BATCH + 1)]) + assert r.status_code == 400 and r.json()["error"]["code"] == -32600 + # too large: said by Content-Length, or found while reading one sent in chunks (which has none), never read whole + big = b" " * (mcp.MAX_BODY + 1) + assert post(big.decode()).status_code == 413 + r = client.post("/mcp", headers=h, content=iter([b'{"jsonrpc": "2.0", "id": 1, "method": "ping"}', big])) + assert r.status_code == 413 and r.json()["error"]["code"] == -32600 # JSON-RPC errors assert post("{nope").json()["error"]["code"] == -32700 assert post({"id": 1, "method": "ping"}).json()["error"]["code"] == -32600 @@ -224,6 +252,7 @@ def test_entities_and_the_graph(client, env, monkeypatch): e = tool(client, h, "get_entity", entity_id=dyno["entity_id"], mentions=2) assert e["name"] == "Dyno Therapeutics" and e["mentions"] == 4 and e["next_mentions_offset"] == 2 + assert tool_error(client, h, "get_entity", entity_id=dyno["entity_id"], mentions_offset=10001).startswith("mentions_offset") assert {m["name"] for m in e["mentioned_most_by"]} == {"Alice", "Bob", "Carol"} line = e["lines"][0] assert line["recording_id"] in (ep1, ep2) and "Dyno Therapeutics" in line["text"]