Consent-time scope narrowing for MCP grants

[ChiragAgg5k]

What

Part C of the granular MCP OAuth scopes plan (companions: appwrite-labs/cloud#4606 — validator cap bumps, already open — and appwrite/mcp#57 — MCP advertises the full scope catalog).

Under that design, MCP clients mechanically request the AS's entire ~118-scope catalog, and the consent screen becomes the control point: because everything granular was literally requested, consent-time downscoping is a plain subset the /approve literal check already supports — no backend logic changes.

MCP-grant detection (src/lib/helpers/oauth2-mcp.ts)

isMcpGrant() — true when the grant's RFC 8707 resources contains the hosted MCP's canonical resource URI (https://mcp.appwrite.io/mcp by default, extendable via comma-separated PUBLIC_MCP_RESOURCE_URLS for local dev). Trailing-slash normalization only; deliberately not loosened to "any URL ending in /mcp". The signal is self-fulfilling: the resource becomes the token's aud and the MCP hard-rejects foreign audiences, so a lying client gains nothing.

Narrowing editor (gated — non-MCP grants render exactly as today)

consent-card.svelte gains an editor only for MCP grants: default state is full access (a plain "Authorize" grants the full request), with a promoted "Customize access" affordance ("You can limit … to specific projects and actions"). Inside: per-resource checkboxes grouped by tier (reusing the existing resource-copy catalog), Read / Read + Write segmented levels, a master read-only toggle, per-tier select-all, and the existing org/project resource pickers unchanged. Identity scopes are not editable.

Grant composition (composeGrantedScopes())

User action	scope sent to /approve
Untouched	omitted — server keeps the full literal requested list, so the consent-skip diff stays empty on re-auth
Resources narrowed only	identity + project:all organization:all — all dropped (it bypasses RAR resource restrictions)
Capabilities narrowed	identity + selected granular tokens; fully-kept tier collapses to its umbrella; "Read + Write" emits both .read and .write

Every emitted token comes verbatim from the request (never synthesized), so the result is a literal subset by construction. Guards: at least one non-identity scope must remain (Authorize disabled with a hint otherwise) and a client-side mirror of the server's 8192 scope-length cap.

Tests

bun run check (0 errors), bun run lint (0 errors), bun run test:unit (235 passed). The grant-composition and detection behavior was verified end to end against the local 3-service stack (12-scenario test matrix — see screenshots below).

Rollout

Safe to deploy with or after cloud#4606 (needed only for the >2048-char approve edge); must be live before appwrite/mcp#57 ships. Production env: rely on the built-in default or set PUBLIC_MCP_RESOURCE_URLS=https://mcp.appwrite.io/mcp.

Screenshots

Captured against the local 3-service stack (cloud API + this console branch + MCP server) during the end-to-end test matrix.

Default state — full access preselected, narrowing promoted (scenario 2):

Customize access expanded — per-resource checkboxes, Read / Read + Write levels, master Read-only toggle (scenario 6; approve sent scope="openid profile email phone project:tables.read project:rows.read"):

[greptile-apps]

Greptile Summary

This PR adds consent-time scope narrowing for MCP OAuth grants: a new oauth2-mcp.ts helper detects MCP grants via RFC 8707 resources, and consent-card.svelte presents an inline editor (gated exclusively to MCP grants) where users can deselect resources, toggle read vs read+write per row, and apply a global read-only lock before approving.

• isMcpGrant() matches the grant's resources against the canonical https://mcp.appwrite.io/mcp URI (extendable via PUBLIC_MCP_RESOURCE_URLS); the detection signal is self-fulfilling because the MCP server rejects foreign audiences.
• composeGrantedScopes() converts the editor state into the scope string for /approve; an untouched selection omits scope entirely so re-authorizations skip consent, and every emitted token is taken verbatim from the request (never synthesized), making the result a structural subset by construction.
• Non-MCP grants are unaffected — the new code path is entirely behind the canNarrow gate.

Confidence Score: 5/5

Safe to merge; non-MCP grants are completely unaffected, and the MCP narrowing path is structurally sound with the literal-subset guarantee enforced at the composition layer.

The grant-composition logic is well-guarded: the umbrella-collapse predicate correctly includes !readOnly, the untouched early-return correctly requires !resourcesNarrowed, and every emitted token is drawn verbatim from the requested scope list. The one asymmetry in the length-collapse fallback (project-first path has no second-tier recovery) is explicitly documented as unreachable given the current ~2.6 KB catalog size.

No files require special attention for merging; consent-card.svelte has some UX edge cases around write-only resources under the global read-only toggle but none affect grant correctness.

Important Files Changed

Filename	Overview
src/lib/helpers/oauth2-mcp.ts	New file implementing MCP grant detection and scope composition; well-documented, the read-only/umbrella-collapse guard (!readOnly) is correctly applied, and the literal-subset guarantee is structurally enforced
src/lib/helpers/oauth2-scopes.ts	Adds new legacy resource copy entries, exports scopeAction/scopeResource under their original internal names via aliases, and adds buildTierEditorRows — all additive and correct
src/routes/(public)/oauth2/consent-card.svelte	Adds MCP-gated narrowing editor with per-resource checkboxes and read/read+write toggles; non-MCP grants render exactly as before; some edge-case UX gaps noted in previous reviews

_{Reviews (4): Last reviewed commit: "(fix): address Greptile review — guard u..." | Re-trigger Greptile}