From 3d7324ffa5073fffc141e06b5e838f46be83b981 Mon Sep 17 00:00:00 2001 From: khaliqgant Date: Thu, 19 Nov 2026 05:31:52 -0800 Subject: [PATCH 1/2] docs(contract): hosted participants get their own group, not the pit The example put hosted participants in gid 22 and said they never read local, but examples/policy.pit.json's pit is the inside group and reads local channels and inboxes. Show a dedicated hosted group with a pit ceiling, write-only access to local inboxes and its own inbox prefix, as checked with relaygate-explain. Co-Authored-By: Claude Opus 5.5 --- docs/contract.md | 33 +++++++++++++++++++++++++-------- 1 file changed, 25 insertions(+), 8 deletions(-) diff --git a/docs/contract.md b/docs/contract.md index c4109b6..a9264c5 100644 --- a/docs/contract.md +++ b/docs/contract.md @@ -507,23 +507,40 @@ Authorization: Bearer sh_ht_... - The agent's key id is `hosted:`. `whoami` carries the person's `user_id`, and no enrollment key or desktop can recover it. -Example rules, one per client an operator allows (put them before any -catch-all; order only matters among rules that can match): +Hosted participants run outside the company network, in someone else's +cloud. Don't put them in the pit (gid 22) of `examples/policy.pit.json`: there +the pit is the inside group and reads `relaycast:channel/` and +`relaycast:inbox/local-`. Give them a group of their own with a pit ceiling, +and grant only what they need. For example, a `hosted` group (55) that local +agents may DM and that may DM local agents but read nothing of theirs (put +the rules before any catch-all; order only matters among rules that can +match): ``` +"groups": [..., {"gid": 55, "name": "hosted"}], "controlPrincipals": [ - {"match": {"orgIds": [""], "kinds": ["hosted"], "clients": ["cursor-cloud"], "as": ["agent"]}, "gid": 22, "namePrefix": "cursor-cloud-"}, - {"match": {"orgIds": [""], "kinds": ["hosted"], "clients": ["chatgpt", "muse"], "as": ["agent"]}, "gid": 22}, - {"match": {"orgIds": [""], "kinds": ["hosted"], "clients": ["mcp"], "roles": ["owner", "admin"], "as": ["agent"]}, "gid": 22}, + {"match": {"orgIds": [""], "kinds": ["hosted"], "clients": ["cursor-cloud"], "as": ["agent"]}, "gid": 55, "namePrefix": "cursor-cloud-"}, + {"match": {"orgIds": [""], "kinds": ["hosted"], "clients": ["chatgpt", "muse"], "as": ["agent"]}, "gid": 55}, + {"match": {"orgIds": [""], "kinds": ["hosted"], "clients": ["mcp"], "roles": ["owner", "admin"], "as": ["agent"]}, "gid": 55}, ... {"match": {"orgIds": [""]}, "gid": 11} ], +"streamDefaults": [ + {"prefix": "relaycast:inbox/cursor-cloud-", "gid": 55, "mode": "660", "acl": [{"gid": 11, "perm": "w"}]}, + {"prefix": "relaycast:inbox/local-", "gid": 11, "mode": "660", "acl": [{"gid": 22, "perm": "r"}, {"gid": 55, "perm": "w"}]}, + ... +], +"ceilings": [..., {"gid": 55, "never": [22]}], "reservedNamePrefixes": ["cursor-cloud-"] ``` -Hosted participants run outside the company network, in someone else's cloud, -so the pit (gid 22) is the natural home: they may write into local inboxes -only as `inboxDefaults` allow, and never read local. +`relaygate-explain` against `examples/policy.pit.json` with these entries: + +- allowed: a hosted `cursor-cloud` participant writing + `relaycast:inbox/local-`, and local writing + `relaycast:inbox/cursor-cloud-`; +- refused: that participant reading `relaycast:inbox/local-` or + `relaycast:channel/`, anything in the pit, and `slack:`. **Migration.** Before this, relay-control registered hosted participants in Relaycast directly with the workspace key, so on gate-only installs they From d75e2d612d168c065e1815bbee848c8c0b10bc00 Mon Sep 17 00:00:00 2001 From: khaliqgant Date: Thu, 19 Nov 2026 05:46:00 -0800 Subject: [PATCH 2/2] docs(contract): hosted group example covers every hosted and local inbox Review: prefix defaults alone left ChatGPT/MCP participants without the cursor-cloud- prefix, and desktop-enrolled local agents, without the two-way DM grants; use inboxDefaults for gids 11 and 55. Checked against the app with examples/policy.pit.json plus these entries. Co-Authored-By: Claude Opus 5.5 --- docs/contract.md | 28 ++++++++++++++++++++-------- 1 file changed, 20 insertions(+), 8 deletions(-) diff --git a/docs/contract.md b/docs/contract.md index a9264c5..0d1010c 100644 --- a/docs/contract.md +++ b/docs/contract.md @@ -526,21 +526,33 @@ match): {"match": {"orgIds": [""]}, "gid": 11} ], "streamDefaults": [ - {"prefix": "relaycast:inbox/cursor-cloud-", "gid": 55, "mode": "660", "acl": [{"gid": 11, "perm": "w"}]}, {"prefix": "relaycast:inbox/local-", "gid": 11, "mode": "660", "acl": [{"gid": 22, "perm": "r"}, {"gid": 55, "perm": "w"}]}, ... ], +"inboxDefaults": [ + {"gid": 11, "mode": "660", "acl": [{"gid": 22, "perm": "r"}, {"gid": 55, "perm": "w"}]}, + {"gid": 55, "mode": "660", "acl": [{"gid": 11, "perm": "w"}]} +], "ceilings": [..., {"gid": 55, "never": [22]}], "reservedNamePrefixes": ["cursor-cloud-"] ``` -`relaygate-explain` against `examples/policy.pit.json` with these entries: - -- allowed: a hosted `cursor-cloud` participant writing - `relaycast:inbox/local-`, and local writing - `relaycast:inbox/cursor-cloud-`; -- refused: that participant reading `relaycast:inbox/local-` or - `relaycast:channel/`, anything in the pit, and `slack:`. +The `inboxDefaults` entries cover inboxes no prefix default names. They +cover hosted participants whose names don't start with `cursor-cloud-` (a +ChatGPT chat, any MCP client), and local agents a desktop enrols under their +own names. The `local-` stream default carries the same grant for +enrollment-key agents. + +With `examples/policy.pit.json` and these entries, `POST /v1/check` gives: + +- for a `cursor-cloud-…` participant and a ChatGPT participant named + without that prefix: + - allowed: writing a desktop-enrolled local agent's inbox and a `local-…` + inbox; + - refused: reading either inbox, reading `relaycast:channel/`, any pit + stream, and `slack:`. +- local agents, desktop-enrolled and key-enrolled: allowed to write both + hosted participants' inboxes. **Migration.** Before this, relay-control registered hosted participants in Relaycast directly with the workspace key, so on gate-only installs they