mirror of https://github.com/turnstonelabs/turnstone.git synced 2026-08-12 23:12:23 -06:00

Files

T

Patrick Buckley 464450b9e2 feat(mcp): admin status, deferred-consent persistence, operator docs (Phase 9) (#516 )

* feat(mcp): admin status, deferred-consent persistence, operator docs (Phase 9)

Completes the OAuth-MCP build-out (Phases 0-8 shipped) by closing the
operator + deferred-consent gaps:

1. **Per-(user, server) deferred-consent persistence** — when a
   non-interactive run (scheduled / channel) hits ``mcp_consent_required``
   or ``mcp_insufficient_scope``, the sync pool dispatchers now upsert a
   row into a new ``mcp_pending_consent`` table.  The dashboard hydrates
   the gear-icon badge from this table on load, so users who weren't
   online to see the in-flight SSE prompt still surface the deferred
   work on next login.  Cleared automatically by the OAuth callback
   handler on consent completion; manual user dismiss via new DELETE
   endpoints.  Composite PK ``(user_id, server_name)`` collapses repeat
   occurrences for the same server — no NULLs-not-distinct trap.

2. **Admin status pill + bulk-revoke** — the MCP Servers admin row now
   shows ``consented_users_count`` for ``auth_type=oauth_user`` rows
   when ≥1, with a two-step-confirm ``bulk-revoke`` button that drops
   every user's token for the server via the existing
   ``delete_mcp_oauth_rows_by_server_name`` primitive.  Upstream RFC
   7009 revoke is intentionally NOT attempted in bulk (avoids N
   upstream HTTP calls per admin click); audit detail records
   ``upstream_revoke_outcome=bulk_admin_no_upstream``.  A "last
   refresh" pill (age + outcome) renders on each row, sourced from a
   new ``_last_refresh`` dict populated by ``_refresh_server`` on every
   call (both manual ``refresh_sync`` and the ``_cb_auto_reconnect``
   follow-up).

3. **ClientType.SCHEDULED** added to the prompts module + scheduler
   passes it through to ``create_workstream``.  ``ChatSession`` now
   computes ``_is_interactive_for_consent`` at construction (WEB / CLI
   are interactive; CHAT / SCHEDULED are not) and plumbs the flag
   through ``call_tool_sync`` / ``read_resource_sync`` /
   ``get_prompt_sync`` to the three sync dispatchers.  The wrap at the
   ``_is_structured_error`` gate routes consent codes to the new
   ``_record_pending_consent_best_effort`` helper for non-interactive
   callers only; interactive sessions stay on the in-flight SSE path
   Phase 8 ships unchanged.

4. **Operator docs** — ``docs/mcp-oauth.md`` (operator guide, parallel
   to ``docs/oidc.md``: ``auth_type`` choice, OAuth client setup,
   encryption-key rotation, troubleshooting matrix) and
   ``docs/operations/mcp-oauth-headless.md`` (one-paragraph runbook
   per ``feedback_runbook_trust_llm.md``: pre-consent recipe for
   scheduled / channel-driven runs).

Schema
- Migration 054_mcp_pending_consent.py — composite PK
  ``(user_id, server_name)``, ``occurrence_count`` + ``first_seen_at`` /
  ``last_seen_at`` for recency metadata, ``idx_mcp_pending_consent_user``
  for the badge-load query.  No FKs (matches the rest of the
  oauth_user schema).
- Migration 055_mcp_user_tokens_server_index.py — adds
  ``idx_mcp_user_tokens_server`` on ``(server_name, expires_at)`` so
  the admin pill's ``count_mcp_consented_users_*`` queries don't
  full-scan against the leading-``user_id`` composite PK.
- Cross-backend: works on SQLite + PostgreSQL via dialect-specific
  ``on_conflict_do_update`` (PG ``postgresql.insert`` / SQLite
  ``sqlalchemy.dialects.sqlite.insert``).  No ``NULLS NOT DISTINCT``
  needed — the simplified PK eliminates the cross-version trap.

Endpoints
- ``GET /v1/api/mcp/oauth/pending`` — list deferred-consent records for
  the authenticated user.  Install-level gate via cached
  ``any_oauth_user_mcp_servers`` short-circuits to ``{pending: 0}`` on
  installs with no oauth_user MCP servers — local-auth deployments
  exercise zero new storage queries on this path.  The gate result is
  cached on ``app.state`` with a 60s TTL to spare repeat dashboard
  loads.
- ``DELETE /v1/api/mcp/oauth/pending/{server_name}`` — single dismiss.
  Returns 204 in both existed-and-deleted and never-existed cases
  (no cross-tenant existence leak); audits
  ``mcp_server.oauth.pending_consent_dismissed`` with
  ``mode=single`` + ``cleared=0|1`` so a session-hijack attacker
  scrubbing breadcrumbs leaves an audit trail.
- ``DELETE /v1/api/mcp/oauth/pending`` — bulk dismiss; audits
  ``mode=bulk`` + ``cleared=N``.
- ``POST /v1/api/admin/mcp-servers/{name}/bulk-revoke`` — admin
  bulk-revoke for the named server's per-user tokens.  Requires
  ``admin.mcp`` permission + 400s when the row isn't ``oauth_user``.

All four registered on both ``turnstone-server`` and
``turnstone-console`` (mirrors the Phase 8 ``/connections`` endpoint
shape).

Performance
- Admin list handler now uses a single ``GROUP BY`` bulk-count query
  (``count_mcp_consented_users_grouped_by_server``) wrapped in
  ``asyncio.to_thread`` rather than N per-row sync DB round-trips
  inside the async handler.  Skipped entirely when no row is
  oauth_user.

Frontend
- ``ui/static/app.js``: ``loadPendingConsents()`` hydrates the
  existing ``_pendingConsentServers`` set on dashboard init + after
  the user opens the settings modal.  Endpoint failures stay silent
  — the badge will be re-driven by the next in-flight tool error.
- ``console/static/admin.js``: ``consented_users_count`` pill +
  ``bulk-revoke`` button on each MCP row (only when ≥1 consented),
  two-step confirm matching the existing delete pattern.  ``last-
  refresh`` age + outcome pill in the per-row status cell, sourced
  from the freshest per-node entry in ``status[*].last_refresh_at`` /
  ``last_refresh_outcome``.  CSS for the pills in ``style.css``.

Tests
- ``test_mcp_pending_consent_storage`` — 13 tests covering upsert
  idempotency, list ordering, per-user isolation, single/bulk delete,
  count-by-server + grouped variant, install-level gate.
- ``test_mcp_pending_consent_dispatch`` — 9 tests, including the
  boundary-cross gate per ``feedback_tests_through_boundaries.md``:
  drives the real ``call_tool_sync`` → ``_dispatch_pool_sync`` →
  ``_is_structured_error`` → ``_record_pending_consent_best_effort``
  with a mocked classified-lookup so the structural plumb-through is
  verified end-to-end.  Includes a storage-failure test that pins
  the docstring's "envelope unchanged on storage failure" promise.
- ``test_mcp_pending_consent_endpoints`` — 11 tests: install gate,
  list-for-self, no-cross-user-leak, single/bulk delete, idempotent
  not-found, audit emission on single + bulk + cross-tenant dismiss.
- ``test_chat_session_interactivity_flag`` — 7 tests pinning the
  ``ClientType`` → ``_is_interactive_for_consent`` mapping against
  the module-level ``INTERACTIVE_CONSENT_CLIENT_TYPES`` frozenset.
- ``test_mcp_admin_bulk_revoke`` — 7 tests covering admin.mcp
  permission gate, 404 on missing, 400 on non-oauth_user, 200 with
  ``rows_deleted`` + ``consented_users_before``, audit row with
  ``upstream_revoke_outcome=bulk_admin_no_upstream``, cross-server
  isolation.
- ``test_mcp_oauth_handlers`` — 2 new callback tests pin the post-
  callback ``delete_mcp_pending_consent`` invocation: success-clears
  + storage-failure-still-redirects.
- 636 tests pass on the impacted surface (47 new + Phase 0-8 OAuth-MCP
  + session + prompts + storage admin).  ruff + mypy clean.

Hard invariants honored
- Static path byte-identical for ``auth_type ∈ {none, static}`` — the
  flag flows only through the pool dispatchers, which only fire when
  the row resolves to ``oauth_user``.
- ``asyncio.timeout`` (not ``asyncio.wait_for``) preserved on every
  AS / SDK / pool-loop await — no new awaits added to the hot path.
- Install-level gate on the badge endpoint: cached
  ``any_oauth_user_mcp_servers`` returns False on a row-less
  deployment → endpoint short-circuits without touching the pending-
  consent table; 60s TTL bounds the staleness window after admin
  flips ``auth_type``.
- Operator-actionable codes (key-unknown, url-insecure, *_forbidden)
  explicitly filtered out of persistence — they're outside the
  user-facing consent badge scope.
- Best-effort write: the structured-error envelope returned to the
  agent is identical whether the persistence write succeeds or fails
  (storage exception is logged with type name only — no chained
  context that could carry an ``httpx.Request`` bearer header).
- No ``exc_info=True`` on any new path that can chain a bearer-bearing
  ``httpx.Request``.
- Defensive parsing: ``_parse_pending_consent_envelope`` mirrors
  ``_is_structured_error``'s ``isinstance(decoded, dict)`` guard plus
  filters scope tokens through ``is_valid_scope_token`` capped at
  ``MAX_INSUFFICIENT_SCOPE_REPORTED`` — defense-in-depth even though
  production callers already validate upstream.
- Audit events on every dismiss endpoint so a session-control attacker
  scrubbing dashboard breadcrumbs still leaves a trail.

Cross-backend
- Tested on SQLite via the conftest backend fixture.
- PostgreSQL path uses ``postgresql.insert(...).on_conflict_do_update``
  parallel to the existing ``mcp_user_tokens`` upsert in Phase 3.

Deferred (not Phase 9 blockers)
- Multi-node pool eviction on bulk-revoke: only local-node sessions
  would be evicted if we built it, and there's no bulk-by-server
  primitive on MCPClientManager today; remote nodes will surface as
  a 401 on next dispatch which refreshes through the (now empty)
  token row.
- RFC 8693 / Azure OBO ``auth_type=oauth_token_exchange`` — captured
  in the design doc as a future architectural direction (~600 LOC +
  IdP-side admin work); requires OIDC token capture and per-MCP-server
  resource-trust configuration that v1 does not ship.

* docs(mcp): address Copilot review feedback on Phase 9

- Fix misleading admin.js comment that claimed the refresh pill rendered
  "<short-relative> <outcome>" — the pill actually renders only the short
  age, with outcome reflected via CSS class and tooltip.
- Replace broken feedback_secrets_not_in_env.md repo-root link in
  mcp-oauth.md with the inlined rationale (env-borne secrets reachable
  via shell tools / os.environ; TOML secrets are not).

2026-05-12 20:55:01 -07:00

9.4 KiB

Raw Permalink Blame History

MCP OAuth — per-user authorization for MCP servers

Turnstone supports per-(user, MCP server) OAuth 2.1 + PKCE delegation so each Turnstone user authorizes a remote MCP server with their own identity, rather than sharing a single bearer token across the deployment. This is the right shape for MCP servers that expose user-specific data (a personal CRM, an email inbox, a calendar) and for MCP servers that want per-user audit attribution.

Per-user OAuth is opt-in per mcp_servers row. Local-auth Turnstone installs with no oauth_user rows exercise zero new code paths — the entire feature is dark by default.

Note

: This is a separate authorization layer from Turnstone's own user authentication. A user who logs into Turnstone with a local username + password can still authorize a per-server OAuth MCP server. OIDC SSO and per-server OAuth are orthogonal.

When to use which `auth_type`

The MCP server admin form exposes three authorization modes ("Multitenant Authorization"):

`auth_type`	What it means	When to use
`none`	No headers attached. Open MCP server (or one gated by network policy only).	Internal MCP servers on a trusted network.
`static`	One static bearer token, configured per server, sent on every request from every user.	Service-to-service MCP servers where per-user attribution doesn't matter, or single-tenant deployments.
`oauth_user` (recommended for user-data servers)	Each user authorizes separately via OAuth 2.1 + PKCE; Turnstone stores per-user tokens encrypted at rest.	MCP servers that expose user-specific data or that want per-user audit attribution.

Switching auth_type away from oauth_user orphans existing per-user tokens. Use the admin bulk-revoke affordance on the server row (Phase 9) to clear them, or let them expire naturally — they're inert without the matching auth_type value.

Prerequisites for `auth_type=oauth_user`

Encryption key. Tokens are stored encrypted with Fernet. Set [security] mcp_token_encryption_key in config.toml (Turnstone won't start with an oauth_user row configured but no key installed). Rotate via MultiFernet — add the new key first, then later remove the old one once all rows have been re-encrypted.
MCP server publishes RFC 9728 PRM and RFC 8414 AS metadata or you configure the AS URL override on the server row. PKCE S256 is mandatory; Turnstone refuses to connect to authorization servers that don't advertise code_challenge_methods_supported: ["S256"].
OAuth client registration. Two paths:
- Pre-registered (most common): you create an OAuth client at the authorization server (manually, via admin console, or via Terraform), then paste the client_id / client_secret into the Turnstone admin form.
- Dynamic client registration (RFC 7591): if the AS supports it and you select that mode in the admin form, Turnstone registers a client at first use and persists the client_id automatically.
Redirect URI registered at the authorization server: https://your-turnstone-host/v1/api/mcp/oauth/callback.

Configuration

Per-server fields (admin UI)

Field	Required	Description
Server URL	Yes	The MCP server's `streamable-http` base URL.
Multitenant Authorization	Yes	`none` / `static` / `oauth_user` (recommended).
Authorization Server URL	No	Override for RFC 9728 PRM discovery. Set when your AS endpoint differs from the MCP server URL (e.g., corporate AS protecting a third-party MCP). When unset, Turnstone falls back to PRM discovery against the MCP server itself.
Client Registration	Yes (oauth_user)	`preregistered` or `dynamic`.
Client ID	Yes (preregistered)	OAuth 2.0 client ID. Stored unencrypted.
Client Secret	Optional (write-only)	OAuth 2.0 client secret (confidential client). Encrypted at rest. Written but never re-read by the API; field stays masked.
Scopes	No	Space-separated default scope set requested at the authorize endpoint. Per-tool step-up may union additional scopes from a server's `insufficient_scope` response.
Audience	No	RFC 8707 `resource=` parameter sent on every authorize and token request. Defaults to the MCP server URL when unset. Validate against the `aud` claim in returned JWT tokens.

Encryption key

[security]
mcp_token_encryption_key = "base64-fernet-key"
# For rotation, list the keys in priority order — first is used for new
# writes, all are tried for reads.
# mcp_token_encryption_keys = ["new-key", "old-key"]

Keep this in config.toml rather than environment variables. An in-process LLM with shell-tool access can read the server's environment via env / os.environ and exfiltrate any secret stored there; secrets in config.toml are only loaded into the server at startup and never re-read on a tool-driven path, so a prompt-injection attack against the agent cannot reach them.

Lifecycle

First tool call for a user against an oauth_user MCP server: pool dispatch finds no stored token, returns mcp_consent_required to the agent. Dashboard renders an inline "Connect" action card.
User clicks Connect: opens /v1/api/mcp/oauth/start?server=<name> in a popup. Browser redirects through the AS authorize endpoint, user grants consent, AS redirects back to /v1/api/mcp/oauth/callback. Turnstone exchanges code → tokens via PKCE, validates audience, encrypts, persists in mcp_user_tokens, redirects user back to the originating URL.
Subsequent tool calls by the same user against the same server reuse the persisted token via the per-(user, server) session pool. Tokens auto-refresh via the refresh-token grant when expired; failed refresh emits mcp_consent_required to drive re-consent.
Step-up scope: when a tool call hits 403 with WWW-Authenticate: error="insufficient_scope", Turnstone emits mcp_insufficient_scope with the parsed scope set; the dashboard offers a "Connect with additional scopes" affordance that opens /v1/api/mcp/oauth/start?server=<name>&scopes=<extra> so the union of original + new scopes flows into the AS authorize request.
User revoke (settings modal): DELETE /v1/api/mcp/oauth/connections/{server_name} runs the authoritative local delete + best-effort RFC 7009 upstream revoke (fire-and-forget, capped at 256 concurrent in-flight tasks).
Admin bulk-revoke (Phase 9): POST /v1/api/admin/mcp-servers/{name}/bulk-revoke drops every user's token for the server. Upstream RFC 7009 revoke is intentionally not attempted in bulk (avoids N upstream HTTP calls per admin click); tokens at the AS expire naturally. Use the per-user revoke endpoint if you need guaranteed upstream invalidation.

Admin status indicators

The MCP Servers admin tab shows per-server status pills (Phase 9):

Consented users count — distinct users with a non-expired token for this server. Surfaced as a bulk-revoke (N) button when ≥1; clicking it opens a confirmation dialog. Hidden when 0.
Last refresh — timestamp + outcome (ok / error:ClassName) of the most recent manual or auto-reconnect refresh. Per node. Absent until at least one refresh has occurred (renders as "never" in the admin UI).

Additional indicators (circuit-breaker state, encryption-key mismatch) are exposed via get_server_status on the API but do not yet have a dedicated admin pill — operators see them today via the per-server status text + error tooltip and in audit logs. A future phase may surface these as discrete pills.

Auth-type transitions

From	To	What happens
`none` / `static` → `oauth_user`	—	New code path activates for this server. Existing static headers (if any) are no longer sent. Users must authorize on first use.
`oauth_user` → `none` / `static`	—	Existing `mcp_user_tokens` rows are orphaned — inert without a matching `auth_type`. Use admin bulk-revoke to drop them, or let them expire. Switching back to `oauth_user` later re-activates the orphaned rows if they haven't been deleted.
OAuth `client_id` or `client_secret` rotated	—	Existing tokens may stop refreshing if the AS treats them as bound to the previous client. Bulk-revoke after rotation.

The orphan-by-default behavior is chosen so switching back to oauth_user is non-destructive. Bulk-revoke is the explicit cleanup path.

Troubleshooting

Symptom	Likely cause	Action
`mcp_consent_required` even after consenting	Token persistence failed, or refresh-token rejected by AS	Check audit log for `mcp_server.oauth.persist_failed` or `mcp_server.oauth.token_revoked`. Re-consent via settings modal.
`mcp_token_undecryptable_key_unknown`	Encryption key rotated without keeping the previous key in the keyring	Add the previous key back to `mcp_token_encryption_keys` until all rows have been re-encrypted, then drop.
`mcp_oauth_url_insecure`	MCP server URL is `http://` (not `https://`) on a non-loopback host	Use `https://`. Per-user bearers must not transit cleartext.
Tools fail in scheduled / Discord / Slack runs	OAuth-MCP requires browser-based consent	Users must pre-consent via the web UI. Phase 9 dashboard badge surfaces deferred consents from these runs on next login.
Circuit breaker open repeatedly	Transport-level errors on the MCP server (DNS, TLS, 5xx)	Check the per-server error pill; auth errors do not trip the breaker.

See also: docs/operations/mcp-oauth-headless.md for the cron / channel-driven run caveat.

9.4 KiB Raw Permalink Blame History