feat(mcp): org-scope MCP enrollment to the subdomain

[angel-manuel]

Implements docs/design/mcp-enrollment-org-scoping.md (now Implemented), recorded as DECISIONS D26.

Problem

On a corp subdomain (<slug>.api.overslash.com), /oauth/authorize derived the enrollment org from the session (pending.org_id = session_claims.org), consulting the subdomain ctx only for the cold-login IdP bounce. So an employee holding a personal-org session who hit acme.api.overslash.com/oauth/authorize while authenticated enrolled the agent into their personal org — the subdomain governed discovery but not where the agent landed. The corporate guarantee ("point our MDM-managed Claude at our subdomain and trust every enrolled agent is ours") did not hold.

Change

The subdomain is now the enrollment boundary. On RequestOrgContext::Org { org_id } the enrolled agent's org is org_id, unconditionally. Root apex stays the multi-org hub — all changes are additive on the subdomain path.

• authorize(): derive the enrollment org from ctx; re-auth a warm session whose org ≠ the subdomain org through the org IdP (idp_bounce, next= preserved) instead of enrolling into the stale session org; org-scope the fast-path binding lookup and pending.org_id.
• register(): stamp oauth_mcp_clients.org_id from ctx (subdomain → that org; root → NULL = multi-org). authorize() rejects a client stamped for a different org (cross-subdomain replay protection); NULL/root clients are accepted.
• Migration 095: add oauth_mcp_clients.org_id; migrate the binding UNIQUE from (user_identity_id, client_id) → (user_identity_id, client_id, org_id).
• Repos: mcp_client_agent_binding::get_for gains an org_id param; upsert ON CONFLICT includes org_id; oauth_mcp_client carries org_id + a new list_for_org.
• Admin surface: Org Settings → MCP Clients list + revoke are scoped to the admin's own org (root/NULL clients belong to no org and are invisible there).

Root apex unchanged

No subdomain to honor → enrollment follows the session org (which may be a corp org the user belongs to), and no re-auth-on-mismatch fires. check_subdomain_matches_jwt is already a no-op at Root. Back-compat: pre-migration NULL-org_id clients keep working as "any subdomain."

Tests

New crates/overslash-api/tests/oauth_mcp_org_scoping.rs covers the design's 7-item plan (stale-session bounce, matching-session enrollment, cross-org binding isolation, cross-subdomain client rejection, root multi-org, NULL-client back-compat). All 6 tests pass; existing mcp_oauth (30), multi_org (28), mcp_elicitation (16), mcp_approve_split (6), subdomain_oauth_as (3) suites stay green. cargo clippy --workspace --all-targets -D warnings clean; make check-sqlx in sync.

Dashboard

No component change — Org Settings → MCP Clients renders whatever /v1/oauth/mcp-clients returns, now backend-scoped to the admin's org. There is no visual diff to screenshot.

Notes

• This PR carries the design doc itself (docs(design): layered service templates + MCP enrollment org-scoping #439's mcp-enrollment-org-scoping.md), which is not yet on dev and which the implementation edits (status flip). Base SCHEMA.sql is identical to dev's, so the schema patch merges cleanly.
• Client admission (which software may enroll) is out of scope; org-scoping is designed to compose with it later.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
overslash	Ready	Preview, Comment	Jul 8, 2026 10:13pm

[codecov]

Codecov Report

❌ Patch coverage is 75.00000% with 18 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
crates/overslash-db/src/repos/oauth_mcp_client.rs	10.00%	9 Missing ⚠️
...ates/overslash-api/src/routes/oauth_mcp_clients.rs	0.00%	6 Missing ⚠️
crates/overslash-api/src/routes/oauth.rs	94.54%	3 Missing ⚠️

📢 Thoughts on this report? Let us know!