fix(mcp): hosted participants enrol through relaygate on gate-only installs
Why (security)
On a gate-only install (SELFHOST_RELAYGATE_PUBLIC_URL set), 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
- Enrol through relaygate. Each hosted participant gets a one-time
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). - Fails closed. Requires AgentWorkforce/relaygate#45: a hosted credential matches only
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. - Only rg_ tokens.
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. - Renewal and migration. A rejected (expired, 24 h) rg_ token is re-enrolled before the owner lock, and the same owner gets the same relaygate agent back. A participant created before this change is re-enrolled on next use, after a one-time workspace-roster check that its upstream agent is still the owner's. It keeps its upstream id, so OAuth connections keep working without reconnecting.
- Release.
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. - Grok routines read gated participants through relaygate and renew their token with
POST /v1/token/refreshat 12 h.
Behaviour changes on gate-only installs (migration note in CHANGELOG and docs/identity.md)
- Operators must add a relaygate rule per hosted client they allow (see relaygate#45, "Hosted participants"). Until then, hosted connectors are refused with that message.
- A session with no relay identity must
join_relaybeforelist_relay_agents/list_relay_channels/get_relay_agent_card, since relaygate answers as the caller. - OAuth connections can't launch agents (relaygate doesn't proxy launches). The owner's native launcher stays a Relaycast identity, checked at relaygate's
/v1/checkas before, and its name can't be joined as a messaging participant.
Not changed (follow-ups I'll file if you agree)
- Desktop-linked and managed chats still do directory reads (roster, channel history) with the workspace key on gate-only installs; their sends already go through relaygate.
- Provider bindings (Amp, Factory, Capy, Replicas) still hold Relaycast tokens.
Tests
- New
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:- the full tool surface through relaygate, with the assertion that no direct Relaycast call (no workspace key, no agent token) happens;
- fail closed with no hosted rule (error names
"kinds": ["hosted"],"clients": ["mcp"], no row, no upstream agent); - pre-gate participant re-enrolled with the same upstream id, after which nothing reaches Relaycast directly;
- expired token renewal (same relaygate agent) and leave through
DELETE /v1/agent; - join-first for directory reads and the reserved launcher name.
test/grok-routines.test.ts: a gated routine reads through relaygate and refreshes its token.- Schema manifest regenerated with the PG 15 harness; the diff is only 0078's objects.
- Full suite: 1805 pass, 109 skipped, 1 fail before the manifest refresh. That failure is the manifest check, which passes now. I reran the affected files (51/51), and
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
![Autofix with [code]smith](https://pr-comments-assets.blacksmith.sh/codesmith/autofix-with-codesmith-dark-3x.png)
Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.
Summary by cubic
On gate-only installs (SELFHOST_RELAYGATE_PUBLIC_URL set), 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's POST /v1/register. Participants then hold only an rg_ token and keep their upstream agent id, so existing OAuth connections work without reconnecting. Release (leave_relay, desktop link, OAuth teardown) goes through relaygate's DELETE /v1/agent. Grok routines read gated participants through relaygate and refresh tokens at 12 hours.
Fails closed
- An enrolment is checked against the workspace roster first: another owner's or a binding's name is refused before a credential is minted, and relaygate's answer is accepted only for the checked agent, the owner's own, or one relaygate registered itself. Release touches only agents relaygate registered for this enrolment. A re-enrolment happens only while the roster still shows the participant's own upstream agent under that name.
- relaygate admits hosted credentials only through
controlPrincipalsrules namingkinds: ["hosted"], never a catch-all; this requires AgentWorkforce/relaygate#45. Without a rule,join_relayfails and names the rule to add. - The hosted clients relaygate admitted a participant for are recorded (
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
- Operators must add a relaygate rule per hosted client they allow; until then, hosted connectors are refused. Migration notes are in the CHANGELOG and
docs/identity.md. - A session with no relay identity must
join_relaybefore directory reads (list_relay_agents,list_relay_channels,get_relay_agent_card). - OAuth connections can't launch agents (relaygate doesn't proxy launches), and the owner's native launcher name can't be joined as a messaging participant.