feat(control): hosted credential kind for hosted MCP participants, fail closed
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_…, scoperelay:hosted:enrol, introspecting asprincipal_type: "relay_hosted"withagent_nameandclient(chatgpt | grok-bot | muse | cursor-cloud | mcp). An unknown or missing client means the credential is invalid. - Fail closed: a hosted credential matches only
controlPrincipalsrules whosekindsexplicitly list"hosted". The documented catch-all{"match":{"orgIds":[org]},"gid":11}never matches one. With no rule, the answer is403 relaygate_denied; the detail names the rule to add, and the audit reason isno_hosted_rule:<client>. match.clientsnarrows a rule per client. The policy is rejected ifclientsis set withoutkindsincludinghosted.- It enrols exactly the credential's
agent_name, and the rule'snamePrefixapplies.reservedNamePrefixesdon't apply to it, so an operator can reservecursor-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 ishosted:<userId>(reserved). explainsupportskind: "hosted"with aclient.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
hostedinkindsever matches; - client scoping;
- invalid credentials;
- reserved prefix behaviour;
- refresh;
- pit isolation: it may write a local inbox per
inboxDefaultsbut 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](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
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
controlPrincipalsrules whosekindslists"hosted", so the usual catch-all can't silently place them in the local group. No matching rule means403 relaygate_deniednaming the rule to add. match.clients(chatgpt,grok-bot,muse,cursor-cloud,mcp) narrows a rule; a policy that setsclientswithout thehostedkind 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 ishosted:<userId>, which no enrollment key or desktop can recover. explainanddocs/contract.mdcover 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.