feat(control): hosted credential kind for hosted MCP participants, fail closed

Merged
KH
3d ago
+387-40

Why

On gate-only installs, relay-control's hosted MCP participants (ChatGPT chats, Grok Bot, Muse, Cursor cloud agents, generic MCP joins) are registered in Relaycast directly with the workspace key, so they bypass relaygate. The fix in relay-control (next PR) enrols every hosted participant here. This PR adds the credential kind it needs and makes sure no existing policy silently takes those participants in.

What

  • New control credential kind hosted: sh_ht_…, scope relay:hosted:enrol, introspecting as principal_type: "relay_hosted" with agent_name and client (chatgpt | grok-bot | muse | cursor-cloud | mcp). An unknown or missing client means the credential is invalid.
  • Fail closed: a hosted credential matches only controlPrincipals rules whose kinds explicitly list "hosted". The documented catch-all {"match":{"orgIds":[org]},"gid":11} never matches one. With no rule, the answer is 403 relaygate_denied; the detail names the rule to add, and the audit reason is no_hosted_rule:<client>.
  • match.clients narrows a rule per client. The policy is rejected if clients is set without kinds including hosted.
  • It enrols exactly the credential's agent_name, and the rule's namePrefix applies. reservedNamePrefixes don't apply to it, so an operator can reserve cursor-cloud- against desktops and keys. Like a launch credential it is single-use, never cached, accepted only at /v1/register (never on Sessions or /v1/check), and issues a 24 h token that refreshes. The key id is hosted:<userId> (reserved).
  • explain supports kind: "hosted" with a client.
  • docs/contract.md: a new "Hosted participants" section with per-client example rules (pit, gid 22) and a migration note.

Tests

test/hosted.test.ts (12) covers:

  • the catch-all-only policy refuses a hosted participant (and doesn't put it in gid 11);
  • no rule without hosted in kinds ever matches;
  • client scoping;
  • invalid credentials;
  • reserved prefix behaviour;
  • refresh;
  • pit isolation: it may write a local inbox per inboxDefaults but can't read the inbox or other local streams;
  • the credential is never introspected off /v1/register;
  • policy validation and explain.

Full suite: 181 passed; tsc --noEmit clean.

Part of: Agent Relay for Cursor cloud agents (design approved). The relay-control security PR follows and depends 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

Adds a hosted control credential kind (sh_ht_…) so relay-control's hosted MCP participants (ChatGPT chats, Grok Bot, Muse, Cursor cloud agents, generic MCP joins) enrol through relaygate instead of registering directly with the workspace key on gate-only installs.

Behavior

  • Hosted credentials fail closed: they match only controlPrincipals rules whose kinds lists "hosted", so the usual catch-all can't silently place them in the local group. No matching rule means 403 relaygate_denied naming the rule to add.
  • match.clients (chatgpt, grok-bot, muse, cursor-cloud, mcp) narrows a rule; a policy that sets clients without the hosted kind is rejected.
  • Like launch credentials they're single-use, never cached, accepted only at /v1/register, and issue 24-hour tokens that refresh. The agent's key id is hosted:<userId>, which no enrollment key or desktop can recover.
  • explain and docs/contract.md cover the new kind with per-client example rules.

Migration
Installs must add hosted rules before relay-control starts enrolling hosted participants; until then each participant's next join fails with the missing rule named.