Skip to content
29 changes: 29 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,35 @@ assigned at release.

- Added: `SELFHOST_DEFAULT_SHARING_MODE` (`all` | `new` | `selected`) sets a deployment sharing mode served to callers whose organization has not saved one, and `SELFHOST_SHARING_MODE_OVERRIDE_ROLES` (`owner` and/or `admin`) leaves callers with those roles unlocked: their v1 policy omits `sharing_mode` and `sharing_mode_since`, and the v2 document serves the effective mode as `sections.capture.defaults.sharing_mode`. The organization-saved mode always wins. Applied per caller on `access/me`, the enrollment key exchange, introspection `capture_policy` (staff read grants as a member) and the upload-credentials revision check. Nothing is stored, no revision moves, and the organization policy routes and fleet view still show only what is stored. Both unset (the default), every response is unchanged. See docs/capture-policy.md.
- Added: `relayfacts_list` and `relayfacts_get` on the Agent Relay MCP. They read the sessions pipeline read API's `GET /v1/relayfacts` (topics with counts) and `GET /v1/relayfacts/{topic}` (one page of a topic as markdown, `page` passed back as its cursor) through the same reader as the shared-session tools: `workspace` is always the credential's workspace, and a response without the workspace attestation returns nothing. They store and write nothing. Until the read API serves relayfacts (`READ_API_RELAYFACTS_ENABLED` off), every 501 is a successful `status: "disabled"` result ("relayfacts disabled") with the upstream reason. OAuth connections need `relay:history`; staff read grants do not get them. The per-user session reader now passes relayfacts cursors through unchanged and reports a 501's upstream reason.
- Security: on a gate-only install (`SELFHOST_RELAYGATE_PUBLIC_URL` set), every
hosted MCP participant now enrols at relaygate and its traffic, reads
included, goes through relaygate. That covers native MCP sessions and OAuth
connectors such as ChatGPT, Grok Bot, Muse and Cursor cloud agents. Before,
they were registered in Relaycast with the workspace key and messaged
around relaygate's policy (migration 0079). Control mints a one-time `sh_ht_`
hosted credential that relaygate introspects as `relay_hosted` with the
participant's client. relaygate admits hosted participants only through
rules naming the hosted kind, so **operators must add a relaygate
`controlPrincipals` rule per allowed client** (relaygate's "Hosted
participants"). Without one, `join_relay` fails and names the rule. Existing
participants are re-enrolled through relaygate on next use and keep their
upstream agent, so OAuth connections keep working. OAuth connections can no
longer launch agents on a gate-only install. A session with no relay
identity must `join_relay` before listing agents or channels there. A name
another owner or a provider binding holds is refused before any credential
is minted, and relaygate's answer must be the checked agent, the owner's,
or one relaygate registered itself. Each participant records the hosted
clients relaygate admitted it for (`admitted_clients`, migration 0079); a
connection of another kind enrols it again at relaygate as that kind first,
which re-applies that rule's groups and revokes the earlier token, and a
refusal leaves the participant as it was. The client is the connection's
admission kind, from the redirect URIs its authorization codes were
delivered to (index `mcp_oauth_codes_grant_idx`, migration 0079): a client
that registers a provider's callback beside its own enrols as `mcp`. Grok Bot routines whose token relaygate rejects
enrol again as `grok-bot` and adopt the token only for the same relaygate
and upstream agent. A stored participant is enrolled again only while its
own upstream agent still holds the name. See docs/identity.md, "Hosted
participants on gate-only installs".
- Fixed: a Replicas launch or bind that never got a Relay identity no longer sits in `preparing`/`binding` forever. After 7 days the sync sweep abandons it (`gone`, audited `replicas.spawn.abandoned`). A replica Relay launched is put to sleep first; an existing chat is left awake. A failed sleep is retried no sooner than one hour later, and not at all while the connection is latched as refused. Rows with a Relay identity and environment identities are untouched.
- Added: MCP `get_session_summary` can read recorded short or long summaries
of the requested kind and return validated optional provenance. It enforces
Expand Down
110 changes: 110 additions & 0 deletions docs/identity.md
Original file line number Diff line number Diff line change
Expand Up @@ -1552,6 +1552,116 @@ task to the target node:
Unset `SELFHOST_RELAYGATE_PUBLIC_URL`: no check is made, no credential is minted and every
`sh_lt_` introspects as `unknown`.

#### Hosted participants on gate-only installs

A hosted participant is the relay agent a hosted MCP connection acts as: a
native MCP session's participant, an OAuth connector's approved agent
(ChatGPT, Grok Bot, Muse, Cursor cloud agents, any MCP client), as opposed to
an Agent Relay Desktop identity. On a gate-only install every hosted
participant enrols at relaygate and holds only an rg_ token, so relaygate's
policy decides what it may do. Control uses neither the workspace key nor a
Relaycast agent token for its traffic:

- **Enrolment.** For each participant Control mints an opaque `sh_ht_`
hosted credential, valid for 2 minutes and redeemable once. It is bound to
the workspace, the organization, the owning user, the exact agent name and
the hosted client (table `relay_hosted_credentials`, migration 0079; only
the hash is stored). Control presents it to relaygate's `POST /v1/register`
itself, with no database transaction open, because relaygate introspects it
here. The client is the connection's admission kind: `chatgpt`, `grok-bot`
or `muse` when every redirect URI its authorization codes were delivered
to is that provider's callback, else `mcp`. A client that registers a
provider's callback beside its own receives its codes at its own callback,
so it enrols as `mcp` and never matches a rule written for a provider. (A
connection with no recorded delivery is a provider's only when every
registered redirect URI is.) The kind says where the codes went, not which
software redeemed them: OAuth clients here are public and self-registered,
and the consenting user can read a code out of their own browser. It keeps
another application from passing as a provider; it does not restrain the
user who consents. Native MCP sessions enrol as `mcp`.
- **Name ownership.** relaygate reserves a name for its first enroller and
takes over an upstream agent of that name it did not register. So before
minting a credential Control checks the name with the workspace roster (a
control-plane read with the workspace key, as on other installs): an agent
another owner, or a provider binding, holds is refused ("That relay name is
already taken") and relaygate never sees an enrolment. relaygate's answer
is checked again: the agent must be the one checked, this owner's, or one
relaygate registered itself for this enrolment. Anything else is refused
and never released, since releasing deletes the agent by name. A stored
participant is enrolled again (a lapsed token, or a new hosted client) only
while the roster still shows its own upstream agent under that name; a
replaced or renamed agent is never handed to relaygate. An answer relaygate
gives for another Control user is refused and nothing is released.
- **Introspection.** Checked and burned like a launch credential. The active
answer is `{active: true, sub: <owner user id>, email: null, principal_type:
"relay_hosted", agent_name, client, machine_id: null, org, workspace,
scopes: ["relay:hosted:enrol"], aud, iat, exp, token_id: <credential id>}`.
Audit events: `relay_hosted.credential.issued` and
`relay_hosted.credential.redeemed`. Unset `SELFHOST_RELAYGATE_PUBLIC_URL`:
every `sh_ht_` is `unknown`.
- **relaygate fails closed.** A hosted credential matches only relaygate
`controlPrincipals` rules whose `kinds` lists `"hosted"`, never a catch-all.
Without one, `join_relay` (and any tool that would auto-join) fails with a
message naming the rule to add, e.g.
`{"match": {"orgIds": ["<org>"], "kinds": ["hosted"], "clients": ["mcp"], "as": ["agent"]}, "gid": 22}`.
See "Hosted participants" in relaygate's `docs/contract.md`.
- **The row.** `hosted_relay_participants.relaygate_agent_id` holds relaygate's
agent id, and `token_ciphertext` seals the rg_ token. `agent_remote_id`
stays the upstream Relaycast agent id, which pins, retirement and teardown
key on. Owner metadata (`source`, `owner_hash`, `cloud_workspace_id`,
`kind`, `hosted_client`) is merged onto the agent card through relaygate's
`PATCH /v1/agent`. Ownership is decided by relaygate's `GET /v1/whoami` (the
agent id and the owner), never by that metadata.
`hosted_relay_participants.admitted_clients` (migration 0079) lists the
hosted clients relaygate enrolled the participant for. A participant is
used only by a connection whose admission kind is in that list.
- **A second hosted client.** When a connection of another kind (for example
Grok Bot for a participant enrolled from ChatGPT) uses the participant,
Control enrols it again at relaygate as that kind first, so relaygate's
policy decides that client too. relaygate then applies the current rule's
groups to the agent and revokes its earlier tokens; the row keeps the new
token and adds the kind. If relaygate refuses (no rule for that client),
the call fails, naming the rule to add, and the row and its token stay as
they were, still usable by the clients already admitted.
- **Traffic.** Sends, replies, inbox, conversations, channels and cards go to
relaygate with the rg_ token. So do directory reads (the roster, names,
channel lists and history), which relaygate filters by its policy. On a
gate-only install a session with no relay identity is asked to `join_relay`
before it can list agents or channels.
- **Renewal.** relaygate tokens last 24 hours. When relaygate rejects the
stored one, Control enrols the participant again before taking the owner
lock: the same owner gets the same upstream agent back. If relaygate
answers with a new relaygate agent id for that same upstream agent, the row
adopts it; an enrolment answered with a different upstream agent is never
adopted. Enrolling again after a rejected token resets `admitted_clients`
to the current client, since relaygate revoked the tokens of the others.
Grok Bot routines renew a participant's token with relaygate's
`POST /v1/token/refresh` once it is 12 hours old. When relaygate rejects a
routine's token (it lapsed while the routine was idle), or the participant
was not admitted as `grok-bot`, the routine enrols it again as `grok-bot`
after its delivery transaction ends. It adopts the new token only if
relaygate answered with the stored relaygate agent and the grant's
upstream agent and the row is unchanged; otherwise it records a delivery
failure and releases nothing.
- **Release.** `leave_relay`, linking a desktop identity and OAuth teardown
release a gated participant through relaygate's `DELETE /v1/agent`, which
also revokes its relaygate tokens. If relaygate no longer accepts the token,
Control releases the upstream agent with the workspace key. That is cleanup
of an agent no one can use.
- **Migration.** A participant registered in Relaycast directly before the
install set `SELFHOST_RELAYGATE_PUBLIC_URL` (or before this change) is
enrolled through relaygate on its next use. First, a one-time workspace-key
roster check confirms that its upstream agent is still the owner's. It keeps
its name and upstream agent id, so OAuth connections keep working without
reconnecting. If relaygate refuses it (no hosted rule), it can't send or
read until the operator adds a rule, but `leave_relay` still removes it.
- **Not hosted participants.** The owner's launcher (`launcher-<hash>`) stays a
Relaycast identity: relaygate does not proxy launches, which are checked at
relaygate's `/v1/check` instead (above). The launcher name can't be joined
as a messaging participant. OAuth connections cannot launch agents on a
gate-only install. Provider bindings (Amp, Factory, Capy, Replicas) are
unchanged.

### Scope mint matrix

Scopes are fixed when a credential is issued and stored on its session row.
Expand Down
43 changes: 43 additions & 0 deletions migrations/0079_hosted_relay_gate.sql
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
-- Hosted participants on gate-only installs (SELFHOST_RELAYGATE_PUBLIC_URL
-- set; docs/identity.md, "Hosted participants on gate-only installs"). Every
-- hosted MCP participant (ChatGPT, Grok Bot, Muse, Cursor cloud agents, any
-- MCP client that joins through the hosted MCP endpoint) enrols at relaygate
-- with a single-use `sh_ht_` credential and holds an rg_ token, so relaygate's
-- policy decides what it may do. relaygate introspects the credential at
-- POST /internal/v1/auth/introspect; the first active answer burns it. Only
-- the sha256 hash is stored: relay-control presents the plaintext to
-- relaygate itself, once, right after minting it. No rows are written when the
-- gate URL is unset.
CREATE TABLE IF NOT EXISTS relay_hosted_credentials (
id uuid PRIMARY KEY,
workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
organization_id uuid NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
user_id uuid NOT NULL REFERENCES users(id) ON DELETE CASCADE,
agent_name text NOT NULL,
-- The hosted MCP client (connector kind) relaygate's policy matches on.
client text NOT NULL,
token_hash text NOT NULL UNIQUE,
expires_at timestamptz NOT NULL,
redeemed_at timestamptz,
created_at timestamptz NOT NULL DEFAULT now()
);

CREATE INDEX IF NOT EXISTS relay_hosted_credentials_workspace ON relay_hosted_credentials (workspace_id, created_at);

-- relaygate's agent id for a participant enrolled through relaygate; its
-- token_ciphertext then seals an rg_ token, and agent_remote_id stays the
-- upstream Relaycast agent id. NULL: registered in Relaycast directly (no
-- gate, or created before this install enforced the gate for hosted
-- participants; such a row is re-enrolled through relaygate on its next use).
ALTER TABLE hosted_relay_participants ADD COLUMN IF NOT EXISTS relaygate_agent_id text;

-- The hosted clients (connector kinds: chatgpt, grok-bot, muse, cursor-cloud,
-- mcp) relaygate enrolled a gated participant for. Another kind enrols at
-- relaygate before it may use the participant, so relaygate's policy decides
-- every client that acts as it. Empty: none yet (a row that is not gated, or
-- one written before this column; it enrols on its next use).
ALTER TABLE hosted_relay_participants ADD COLUMN IF NOT EXISTS admitted_clients text[] NOT NULL DEFAULT '{}';

-- A grant's admission kind is read from the redirect URIs its consumed
-- authorization codes were delivered to.
CREATE INDEX IF NOT EXISTS mcp_oauth_codes_grant_idx ON mcp_oauth_authorization_codes (grant_id) WHERE grant_id IS NOT NULL;
Loading
Loading