Repository navigation
fix(mcp): hosted participants enrol through relaygate on gate-only installs - #231
Conversation
…stalls On a gate-only install (SELFHOST_RELAYGATE_PUBLIC_URL set) hosted MCP participants were registered in Relaycast with the workspace key and messaged with their own Relaycast tokens, around relaygate's policy. That covers native MCP sessions and OAuth connectors such as ChatGPT, Grok Bot, Muse and Cursor cloud agents. Now every one of them enrols at relaygate and holds only an rg_ token, and all of its traffic, directory reads included, goes through relaygate. - One-time sh_ht_ hosted credentials (migration 0078, relay_hosted_credentials, hash only). Control presents each to relaygate's POST /v1/register itself, with no transaction open, and introspection answers relay_hosted with the participant's client (connector kind). relaygate admits hosted participants only through rules naming the hosted kind; a refusal names the rule to add. - hosted_relay_participants.relaygate_agent_id; agent_remote_id stays the upstream Relaycast id, so pins, retirement and teardown are unchanged. Owner metadata is merged through relaygate. Ownership is decided by relaygate's whoami. - Rejected (expired) rg_ tokens re-enrol before the owner lock and get the same relaygate agent back. Pre-gate rows are re-enrolled on next use after a one-time workspace-roster ownership check. - Release through relaygate's DELETE /v1/agent: leave, desktop link and OAuth teardown. Grok routines read through relaygate and refresh tokens at 12 h. - The owner's launcher stays a Relaycast identity (relaygate does not proxy launches; they are checked at /v1/check) and can't be joined as a messaging participant. OAuth connections cannot launch on gate-only installs. - docs/identity.md "Hosted participants on gate-only installs"; CHANGELOG. Needs AgentWorkforce/relaygate#45 (hosted credential kind). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Generated with the PostgreSQL 15 synthetic harness (dry-run.ts --write-schema-manifest); the diff is exactly relay_hosted_credentials and hosted_relay_participants.relaygate_agent_id. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Codex Review Summary: ✅ CompletedThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
|
Important
This repository does not receive automatic reviews because it has fewer than 10 stars.
|
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a0643308fb
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Co-Authored-By: Claude <noreply@anthropic.com>
…aygate Gate-only installs, review fixes for hosted participants: - Check a name with the workspace roster before minting a hosted credential; refuse another owner's or a binding's agent, and accept relaygate's answer only for the checked agent, the owner's own, or one relaygate registered itself. Release only agents relaygate registered for this enrolment. - Record the hosted clients relaygate admitted a participant for (hosted_relay_participants.admitted_clients, migration 0079). A connection of another kind enrols again at relaygate as that kind first; a refusal leaves the row and token unchanged. - Enrol with the grant's admission kind: a registration whose redirect URIs name two different providers enrols as mcp. - Adopt a new relaygate agent id for the same upstream agent on renewal. - A join that enrolled while a concurrent join wrote the row adopts the prepared token for the same agent, and releases nothing it does not own. - Grok routines pass the request signal to token refresh and, on a rejected token, enrol again as grok-bot outside the delivery transaction under a 60 s lease, adopting only the same agents. Co-Authored-By: Claude <noreply@anthropic.com>
…s the name relaygate takes an upstream agent of a known name over when it enrols it. A stored participant whose token lapsed, or which a new hosted client connects to, is now enrolled again only while the workspace roster still shows its own upstream agent under that name, so a replaced or renamed agent is never handed to relaygate. An answer relaygate gives for another Control user is refused without releasing the agent behind it. Refreshes the schema manifest for migration 0079. Co-Authored-By: Claude <noreply@anthropic.com>
…into fix/hosted-participants-through-relaygate
Co-Authored-By: Claude <noreply@anthropic.com>
…e delivered A self-registered OAuth client could list a provider's callback beside its own redirect URI and enrol at relaygate as that provider. The admission kind is now the provider named by every redirect URI the grant's consumed authorization codes were delivered to; a grant with no recorded delivery is a provider's only when every registered URI is. Grok Bot routines use the same rule. Adds the partial index mcp_oauth_codes_grant_idx to migration 0079 and refreshes the schema manifest. The kind says where the codes went, not which software redeemed them: it keeps another application from passing as a provider, not the consenting user. Co-Authored-By: Claude <noreply@anthropic.com>
Merges main (including #231's relaygate path); no history rewrite. Review findings on #236: - Migration renumbered to 0082 (main took 0079-0081); verifier manifest regenerated on PostgreSQL 15, diff only 0082. - Flag off no longer scans Cloud-copy rows. A per-row cloud_copy marker decides behaviour: rows saved before the flag keep inbox-batch wakes when it is turned on, so an already-pasted prompt is never silently broken; saving again with the flag on moves a row to the copy. The setup page marks such a routine. Polling rows are always copy rows (CHECK). - Sender trust comes only from rows this service owns: the person's hosted participants, Desktop identities and bound Amp/Capy bindings in this workspace. Agent metadata is never used; person identities give the sender kind. The scan no longer reads the roster. - Ingest and post-commit acknowledgements use #231's client choice and the renewed token, after its recovery early-returns; a gated participant never talks to Relaycast directly. Gate-only test added. - connect_grok_bot_routine checks the grant (setup allowed) before joining. - Retention: events reference their routine row ON DELETE CASCADE (disconnect, revocation, grant loss), every scan deletes events older than seven days whatever the flag, and reads never return them. - A concurrent duplicate routine-URL save maps the unique-index error to the duplicate answer. The URL hash is stored for every save. - grok_events gets its own capability reason. An undecryptable event is skipped instead of blocking later wakes; the bot's own deliveries are acknowledged; the cursor is a per-grant sequence. - Private references removed from comments, docs and the spec (repository paths, a commit, an issue number, incident dates, a person-derived example agent name). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Why (security)
On a gate-only install (
SELFHOST_RELAYGATE_PUBLIC_URLset), relaygate is supposed to be the only way into Relaycast. But hosted MCP participants were registered in Relaycast with the workspace key and messaged with their own Relaycast tokens, so they bypassed relaygate's policy entirely. Those participants are native MCP sessions and OAuth connectors: ChatGPT, Grok Bot, Muse, Cursor cloud agents. relay-participants.ts said so: "hosted participants keep Relaycast". On a pit deployment, any hosted connector could therefore read and write outside its group.What
sh_ht_hosted credential (migration 0078relay_hosted_credentials, hash only, 2-minute TTL, single use). Control presents it to relaygate'sPOST /v1/registeritself, with no DB transaction open, because relaygate introspects it here. Introspection answersprincipal_type: "relay_hosted"withagent_nameandclient(the connection's connector kind, elsemcp).controlPrincipalsrules that namekinds: ["hosted"], never a catch-all. With no such rule,join_relay(and anything that would auto-join) fails with a message naming the rule to add. No silent gid 11.hosted_relay_participants.relaygate_agent_idis new;token_ciphertextseals the rg_ token;agent_remote_idstays the upstream Relaycast id, so pins, retirement and teardown are unchanged. Every call goes to relaygate: send, reply, inbox/ack, conversations, channels, cards (PATCH /v1/agent), heartbeats. So do directory reads (roster, names, channel list, channel history), which relaygate filters. Owner metadata is merged through relaygate. Ownership is decided by relaygate'swhoami.leave_relay, desktop link and OAuth teardown release through relaygate'sDELETE /v1/agent, which also revokes its relaygate tokens. If relaygate no longer accepts the token, Control falls back to a workspace-key release; that is cleanup of an agent no one can use.POST /v1/token/refreshat 12 h.Behaviour changes on gate-only installs (migration note in CHANGELOG and docs/identity.md)
join_relaybeforelist_relay_agents/list_relay_channels/get_relay_agent_card, since relaygate answers as the caller./v1/checkas before, and its name can't be joined as a messaging participant.Not changed (follow-ups I'll file if you agree)
Tests
test/gate-only-hosted-participants.test.ts(5). It uses a fake relaygate that introspectssh_ht_against Control's real endpoint and records every request that bypasses it. It covers:"kinds": ["hosted"],"clients": ["mcp"], no row, no upstream agent);DELETE /v1/agent;test/grok-routines.test.ts: a gated routine reads through relaygate and refreshes its token.npm run typecheckis clean.Part of: Agent Relay for Cursor cloud agents (design approved). Cursor-cloud identity PRs stack on this one.
🤖 Generated with Claude Code
Open in [code]smith · Need help on this PR? Tag
@codesmith-botwith what you need.Summary by cubic
On gate-only installs (
SELFHOST_RELAYGATE_PUBLIC_URLset), hosted MCP participants (ChatGPT, Grok Bot, Muse, Cursor cloud agents, native MCP sessions) previously bypassed relaygate: they were registered in Relaycast with the workspace key and messaged with their own Relaycast tokens. Now they enrol at relaygate, and all their traffic—sends, replies, directory reads, heartbeats, teardown—goes through it, subject to relaygate's policy.Each hosted participant gets a one-time
sh_ht_credential (migration 0079, hash only, 2-minute TTL) that Control presents to relaygate'sPOST /v1/register. Participants then hold only anrg_token and keep their upstream agent id, so existing OAuth connections work without reconnecting. Release (leave_relay, desktop link, OAuth teardown) goes through relaygate'sDELETE /v1/agent. Grok routines read gated participants through relaygate and refresh tokens at 12 hours.Fails closed
controlPrincipalsrules namingkinds: ["hosted"], never a catch-all; this requires feat(control): hosted credential kind for hosted MCP participants, fail closed relaygate#45. Without a rule,join_relayfails and names the rule to add.admitted_clients); a connection of another kind enrols again at relaygate as that kind first, and a refusal leaves the row and token unchanged. The admission kind is read from where a grant's consumed authorization codes were delivered: only a grant whose codes all went to one provider's own callback enrols as that provider, and a registration that names no single provider enrols asmcp.Behavior changes on gate-only installs
docs/identity.md.join_relaybefore directory reads (list_relay_agents,list_relay_channels,get_relay_agent_card).Written for commit ce913cc. Summary will update on new commits.