Skip to content

fix(mcp): hosted participants enrol through relaygate on gate-only installs - #231

Merged
agent-relay-code[bot] merged 8 commits into
mainfrom
fix/hosted-participants-through-relaygate
Nov 19, 2026
Merged

agent-relay-code[bot] merged 8 commits into
mainfrom
fix/hosted-participants-through-relaygate

Conversation

@khaliqgant

@khaliqgant khaliqgant commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

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 0078 relay_hosted_credentials, hash only, 2-minute TTL, single use). Control presents it to relaygate's POST /v1/register itself, with no DB transaction open, because relaygate introspects it here. Introspection answers principal_type: "relay_hosted" with agent_name and client (the connection's connector kind, else mcp).
  • Fails closed. Requires feat(control): hosted credential kind for hosted MCP participants, fail closed relaygate#45: a hosted credential matches only controlPrincipals rules that name kinds: ["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_id is new; token_ciphertext seals the rg_ token; agent_remote_id stays 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's whoami.
  • 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's DELETE /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/refresh at 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_relay before list_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/check as 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 introspects sh_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 typecheck is 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
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 controlPrincipals rules naming kinds: ["hosted"], never a catch-all; this requires feat(control): hosted credential kind for hosted MCP participants, fail closed relaygate#45. Without a rule, join_relay fails 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 as mcp.

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_relay before 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.

Written for commit ce913cc. Summary will update on new commits.

View guided diff Turn on auto-fix

khaliqgant and others added 2 commits November 17, 2026 11:50
…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>
@khaliqgant khaliqgant added the merge-train:hold Do not merge until the owner gives the go label Nov 17, 2026
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-17T20:02:16.327954Z a064330 PR opened
ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@coderabbitai

coderabbitai Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

Important

  • Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 4ae5a579-9b6e-4f56-811d-30bc217fd222
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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".

Comment thread src/mcp/grok-routines.ts Resolved
Comment thread src/mcp/grok-routines.ts Resolved

@devin-ai-integration devin-ai-integration Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Devin Review found 4 potential issues.

Devin Review

Comment thread src/mcp/grok-routines.ts Resolved
Comment thread src/mcp/grok-routines.ts Resolved
Comment thread src/mcp/relay-participants.ts Resolved
Comment thread src/mcp/relay-participants.ts Resolved
layered-control-agent-host and others added 6 commits November 19, 2026 11:16
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>
@agent-relay-code
agent-relay-code Bot merged commit 3de43bc into main Nov 19, 2026
4 checks passed
@agent-relay-code
agent-relay-code Bot deleted the fix/hosted-participants-through-relaygate branch November 19, 2026 12:16
AgentRelayBot pushed a commit that referenced this pull request Nov 20, 2026
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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

merge-train:hold Do not merge until the owner gives the go

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant