From ec1c70e2c21c9dae18760e6892fd0212781c4843 Mon Sep 17 00:00:00 2001 From: khaliqgant Date: Tue, 17 Nov 2026 11:50:20 -0800 Subject: [PATCH 1/5] fix(mcp): hosted participants enrol through relaygate on gate-only installs 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 --- CHANGELOG.md | 16 + docs/identity.md | 67 +++ migrations/0078_hosted_relay_gate.sql | 32 ++ src/app.ts | 7 + src/auth/introspect.ts | 82 +++- src/control-tables.ts | 1 + src/mcp/grok-routines.ts | 28 +- src/mcp/hosted-gate.ts | 80 ++++ src/mcp/oauth/teardown.ts | 23 +- src/mcp/relay-hosted-credentials.ts | 145 +++++++ src/mcp/relay-participants.ts | 478 +++++++++++++++++---- src/messaging/relaycast.ts | 43 ++ test/gate-only-hosted-participants.test.ts | 302 +++++++++++++ test/grok-routines.test.ts | 39 ++ 14 files changed, 1243 insertions(+), 100 deletions(-) create mode 100644 migrations/0078_hosted_relay_gate.sql create mode 100644 src/mcp/hosted-gate.ts create mode 100644 src/mcp/relay-hosted-credentials.ts create mode 100644 test/gate-only-hosted-participants.test.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index 339aead2..179a5056 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,22 @@ assigned at release. ## Unreleased +- 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 0078). 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. See + docs/identity.md, "Hosted participants on gate-only installs". - Added: MCP `get_session_summary` can read recorded short or long summaries of the requested kind and return validated optional provenance. It enforces 320/16000 Unicode code-point bounds, preserves empty/unsupported responses, diff --git a/docs/identity.md b/docs/identity.md index 5cf28e87..1124922d 100644 --- a/docs/identity.md +++ b/docs/identity.md @@ -1552,6 +1552,73 @@ 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 0078; 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 connector kind (`chatgpt`, `grok-bot`, + `muse`, `cursor-cloud`) from its registered OAuth redirect URIs, else `mcp`. +- **Introspection.** Checked and burned like a launch credential. The active + answer is `{active: true, sub: , email: null, principal_type: + "relay_hosted", agent_name, client, machine_id: null, org, workspace, + scopes: ["relay:hosted:enrol"], aud, iat, exp, token_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": [""], "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. +- **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 relaygate agent back. Grok Bot routines + renew a participant's token with relaygate's `POST /v1/token/refresh` once + it is 12 hours old. +- **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-`) 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. diff --git a/migrations/0078_hosted_relay_gate.sql b/migrations/0078_hosted_relay_gate.sql new file mode 100644 index 00000000..fbc15182 --- /dev/null +++ b/migrations/0078_hosted_relay_gate.sql @@ -0,0 +1,32 @@ +-- 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; diff --git a/src/app.ts b/src/app.ts index 02acdc19..45b5067c 100644 --- a/src/app.ts +++ b/src/app.ts @@ -3,6 +3,7 @@ import { revokeOrganizationMcpOAuthGrants } from "./mcp/oauth/revocations.js"; import { createMcpOAuthHttpModule } from "./mcp/oauth/routes.js"; import { McpOAuthStore } from "./mcp/oauth/store.js"; import { connectorKind } from "./mcp/oauth/connector-kind.js"; +import { relayHostedCredentials } from "./mcp/relay-hosted-credentials.js"; import { ownerHash, HOSTED_SOURCE } from "./mcp/relay-participants.js"; import { McpOAuthTeardown,mcpOAuthTeardownFetch } from "./mcp/oauth/teardown.js"; import { mcpOAuthActive } from "./mcp/oauth/config.js"; @@ -617,9 +618,12 @@ export function createApp(input: { const oauthTeardown=mcpOAuthActive(config) ? input.mcpOAuthTeardown??new McpOAuthTeardown({ database:store.database,keyring:config.encryptionKeyring, client:createRelaycastClient({internalOrigin:config.relaycastUrl,fetchImpl:mcpOAuthTeardownFetch(input.messagingFetch)}),now:input.now, + ...(config.relaygatePublicUrl ? {gate:createRelaycastClient({internalOrigin:config.relaygatePublicUrl, + fetchImpl:mcpOAuthTeardownFetch(input.messagingFetch)})} : {}), }) : null; const grokRoutines = mcpOAuthActive(config) ? input.grokRoutines ?? new GrokRoutines({ database:store.database,keyring:config.encryptionKeyring,client:oauthRelay, + ...(config.relaygatePublicUrl ? {gate:createRelaycastClient({internalOrigin:config.relaygatePublicUrl,fetchImpl:input.messagingFetch})} : {}), publicOrigin:new URL(config.publicBaseUrl).origin,tenancyMode:store.tenancy,now:input.now, }) : undefined; const mcpOAuth = createMcpOAuthHttpModule({ @@ -975,6 +979,8 @@ export function createApp(input: { // Gate-only installs only: relaygate introspects one-time `sh_lt_` launch credentials. const relayLaunchCredentialStore = config.relaygatePublicUrl ? relayLaunchCredentials(store.database, config.encryptionKeyring) : undefined; + // Gate-only installs only: relaygate introspects one-time `sh_ht_` hosted participant credentials. + const relayHostedCredentialStore = config.relaygatePublicUrl ? relayHostedCredentials(store.database) : undefined; // Gate-only installs only: Control holds relay nodes' Relaycast node tokens and bridges their sockets. const relayNodeCredentialStore = config.relaygatePublicUrl ? relayNodeCredentials(store.database, config.encryptionKeyring) : undefined; @@ -1334,6 +1340,7 @@ export function createApp(input: { if (method === "POST" && publicPath === INTROSPECT_PATH) { const outcome = await handleIntrospection( config, store, request, undefined, admin?.apiTokens, flowRelayfileCredentials, relayLaunchCredentialStore, introspectionHold, + relayHostedCredentialStore, ); if (outcome.status === 200) json(response, 200, outcome.body, true); else json(response, outcome.status, { error: outcome.error, message: outcome.message }, true); diff --git a/src/auth/introspect.ts b/src/auth/introspect.ts index fe2331aa..ce9ff187 100644 --- a/src/auth/introspect.ts +++ b/src/auth/introspect.ts @@ -13,6 +13,9 @@ import { } from "../mcp/relay-launch-credentials.js"; import { NODE_ID_PATTERN, type ControlPlaneStore, type IntrospectedToken, type Principal } from "../store.js"; import type { HeldAudienceVerdict, IntrospectionHold } from "./introspection-hold.js"; +import { + RELAY_HOSTED_CREDENTIAL_PREFIX, RELAY_HOSTED_SCOPE, type RelayHostedClient, type RelayHostedCredentials, +} from "../mcp/relay-hosted-credentials.js"; /** * POST /internal/v1/auth/introspect: the sessions pipeline (and relayfile) @@ -76,6 +79,14 @@ import type { HeldAudienceVerdict, IntrospectionHold } from "./introspection-hol * node_name of the launch, scopes `["relay:agent:enrol"]`, token_id = the * credential id, iat = minted and exp = the credential's expiry. Unset gate * URL: every `sh_lt_` is `unknown`. + * - Hosted participant credentials (gate-only installs; docs/identity.md, + * "Hosted participants on gate-only installs"): an `sh_ht_` token + * relay-control mints for one hosted MCP participant and presents to + * relaygate's POST /v1/register itself. Checked and burned like a launch + * credential. Active answers have principal_type `relay_hosted`, sub = the + * participant's owner, agent_name, client (the hosted MCP client), scopes + * `["relay:hosted:enrol"]`, token_id = the credential id. Unset gate URL: + * every `sh_ht_` is `unknown`. * - User tokens also carry `role`, the live organization role, so optional * add-on services can make the same admin decisions as this service without * reading its database. Each add-on is one more origin in @@ -202,12 +213,36 @@ export type IntrospectionResult = iat: number; exp: number; token_id: string; + } + | { + active: true; + /** The participant's owner. */ + sub: string; + email: null; + principal_type: "relay_hosted"; + agent_name: string; + /** The hosted MCP client relaygate's controlPrincipals match on (`match.clients`). */ + client: RelayHostedClient; + machine_id: null; + org: string; + workspace: string; + /** Always `["relay:hosted:enrol"]` (RELAY_HOSTED_SCOPE). */ + scopes: string[]; + aud: string; + iat: number; + exp: number; + token_id: string; }; export type IntrospectionLog = (message: string, fields: Record) => void; /** Only the HTTP route passes a hold; every in-process caller stays strict. */ -export type IntrospectionOptions = { hold?: IntrospectionHold; log?: IntrospectionLog }; +export type IntrospectionOptions = { + hold?: IntrospectionHold; + log?: IntrospectionLog; + /** Gate-only installs: one-time hosted participant credentials (`sh_ht_`). */ + hostedCredentials?: RelayHostedCredentials; +}; export type IntrospectionOutcome = | { status: 200; body: IntrospectionResult } @@ -515,6 +550,45 @@ async function introspectRelayLaunchCredential( }; } +/** One-time hosted participant credentials (`sh_ht_`, principal `relay_hosted`); burned on the active answer. */ +async function introspectRelayHostedCredential( + config: SelfhostConfig, + credentials: RelayHostedCredentials | undefined, + request: IntrospectionRequest, +): Promise { + const found = credentials ? await credentials.peek(request.token) : { state: "unknown" as const }; + if (found.state === "unknown") return { active: false, reason: "unknown" }; + if (found.state === "redeemed") return { active: false, reason: "revoked" }; + if (found.state === "expired") return { active: false, reason: "expired" }; + const aud = normalizedOrigin(request.aud); + if (aud === null || !acceptedAudiences(config).includes(aud)) return { active: false, reason: "audience" }; + if (request.workspace !== undefined && found.credential.workspaceId !== request.workspace) { + return { active: false, reason: "workspace" }; + } + if (request.machine !== undefined) return { active: false, reason: "machine_not_owned" }; + const redeemed = await credentials!.redeem(request.token); + if (redeemed.state !== "active") { + return { active: false, reason: redeemed.state === "expired" ? "expired" : redeemed.state === "unknown" ? "unknown" : "revoked" }; + } + const credential = redeemed.credential; + return { + active: true, + sub: credential.userId, + email: null, + principal_type: "relay_hosted", + agent_name: credential.agentName, + client: credential.client, + machine_id: null, + org: credential.organizationId, + workspace: credential.workspaceId, + scopes: [RELAY_HOSTED_SCOPE], + aud, + iat: epochSeconds(credential.createdAt), + exp: epochSeconds(credential.expiresAt), + token_id: credential.id, + }; +} + export async function introspect( config: SelfhostConfig, store: ControlPlaneStore, @@ -536,6 +610,9 @@ export async function introspect( if (request.token.startsWith(RELAY_LAUNCH_CREDENTIAL_PREFIX)) { return introspectRelayLaunchCredential(config, launchCredentials, request); } + if (request.token.startsWith(RELAY_HOSTED_CREDENTIAL_PREFIX)) { + return introspectRelayHostedCredential(config, options?.hostedCredentials, request); + } // Refresh, internal, bootstrap, worker, run and enrollment tokens are // never looked up as user tokens. That includes sh_ek_ desktop enrollment // keys: they are exchanged once at POST /api/v1/auth/enrollment/token and @@ -664,6 +741,7 @@ export async function handleIntrospection( flowRunCredentials?: FlowRunRelayfileCredentials, launchCredentials?: RelayLaunchCredentials, hold?: IntrospectionHold, + hostedCredentials?: RelayHostedCredentials, ): Promise { const secret = config.introspectSecret; if (!secret) { @@ -687,5 +765,5 @@ export async function handleIntrospection( message: "Body must be a JSON object with string token and aud, optionally a non-empty string (or null) workspace, and optionally a node-id string machine (at most 16 KiB)", }; } - return { status: 200, body: await introspect(config, store, body, apiTokens, flowRunCredentials, launchCredentials, { hold, log }) }; + return { status: 200, body: await introspect(config, store, body, apiTokens, flowRunCredentials, launchCredentials, { hold, log, hostedCredentials }) }; } diff --git a/src/control-tables.ts b/src/control-tables.ts index 37f8f036..98652ca6 100644 --- a/src/control-tables.ts +++ b/src/control-tables.ts @@ -72,6 +72,7 @@ export const CONTROL_TABLES: readonly string[] = [ "person_identities", "person_messages", "person_revocations", + "relay_hosted_credentials", "relay_launch_credentials", "relay_node_credentials", "relay_spawns", diff --git a/src/mcp/grok-routines.ts b/src/mcp/grok-routines.ts index f59cc7fc..83dc917c 100644 --- a/src/mcp/grok-routines.ts +++ b/src/mcp/grok-routines.ts @@ -22,8 +22,13 @@ const escape = (value: string) => value.replaceAll("&", "&").replaceAll("<", .replaceAll('"', """).replaceAll("'", "'"); /** One encrypted routine per grant. User -> organization -> grant locks fence every delivery against revocation. */ +/** A gated participant's rg_ token (24 h at relaygate) is renewed once it is this old. */ +const GATE_TOKEN_REFRESH_AFTER_MS = 12 * 3_600_000; + export class GrokRoutines { constructor(readonly options: { database: Database; keyring: EncryptionKeyring; client: RelaycastClient; + /** Gate-only installs: participants enrolled through relaygate (relaygate_agent_id set) are read through it. */ + gate?: RelaycastClient; publicOrigin: string; tenancyMode: TenancyMode; fetchImpl?: typeof fetch; now?: () => Date; requestTimeoutMs?: number }) {} private now() { return this.options.now?.() ?? new Date(); } @@ -142,19 +147,32 @@ form.addEventListener('submit',e=>{e.preventDefault();change('POST');});document // while the revocation fence is held. stop() aborts the same requests. const deadline = AbortSignal.timeout(this.options.requestTimeoutMs ?? 5_000); const requestSignal = signal ? AbortSignal.any([signal, deadline]) : deadline; - const participant = (await tx.query<{ token_ciphertext: string; relaycast_workspace_id: string }>(`SELECT p.token_ciphertext,p.relaycast_workspace_id + const participant = (await tx.query<{ id: string; token_ciphertext: string; relaycast_workspace_id: string; + relaygate_agent_id: string | null; stale: boolean }>(`SELECT p.id,p.token_ciphertext,p.relaycast_workspace_id,p.relaygate_agent_id, + p.updated_at < $5 AS stale FROM hosted_relay_participants p JOIN workspaces w ON w.id=p.workspace_id AND w.organization_id=$4 WHERE p.workspace_id=$1 AND p.user_id=$2 AND p.agent_remote_id=$3 AND p.relaycast_workspace_id=w.relaycast_workspace_id`, - [candidate.workspace_id, candidate.user_id, grant.agent_remote_id, candidate.organization_id])).rows[0]; + [candidate.workspace_id, candidate.user_id, grant.agent_remote_id, candidate.organization_id, + new Date(this.now().getTime() - GATE_TOKEN_REFRESH_AFTER_MS)])).rows[0]; if (!participant) throw new Error("identity_unavailable"); - const token = decryptSecret(participant.token_ciphertext, this.options.keyring); - const remote = await this.options.client.authenticatedAgent(token, requestSignal); + // A participant enrolled through relaygate holds an rg_ token: it reads through relaygate only. + const gated = participant.relaygate_agent_id !== null; + if (gated && !this.options.gate) throw new Error("identity_unavailable"); + const via = gated ? this.options.gate! : this.options.client; + let token = decryptSecret(participant.token_ciphertext, this.options.keyring); + if (gated && participant.stale) { + // rg_ tokens last 24 hours; a routine may poll an idle participant for longer, so renew it at half-life. + token = await via.refreshGateToken(token); + await tx.query("UPDATE hosted_relay_participants SET token_ciphertext=$2, updated_at=now() WHERE id=$1", + [participant.id, encryptSecret(token, this.options.keyring.active)]); + } + const remote = await via.authenticatedAgent(token, requestSignal); if (remote.id !== grant.agent_remote_id || remote.workspaceId !== participant.relaycast_workspace_id || remote.status === "released" || isBindingOwnedIdentity(remote.metadata) || remote.metadata.source !== HOSTED_SOURCE || remote.metadata.owner_hash !== ownerHash(candidate.user_id) || remote.metadata.cloud_workspace_id !== candidate.workspace_id) throw new Error("identity_unavailable"); - const inbox = (await this.options.client.readHostedInbox(token, requestSignal)).slice(0, 100).filter(message => message.sender_id !== remote.id); + const inbox = (await via.readHostedInbox(token, requestSignal)).slice(0, 100).filter(message => message.sender_id !== remote.id); const ids = inbox.map(message => message.delivery_id).sort(); const fresh = ids.filter(id => !routine.notified_delivery_ids.includes(id)); if (fresh.length) { diff --git a/src/mcp/hosted-gate.ts b/src/mcp/hosted-gate.ts new file mode 100644 index 00000000..a60ef92b --- /dev/null +++ b/src/mcp/hosted-gate.ts @@ -0,0 +1,80 @@ +import type { Database } from "../database.js"; +import { RelaycastCallError, type RelaycastClient } from "../messaging/relaycast.js"; +import { relayHostedCredentials, type RelayHostedClient } from "./relay-hosted-credentials.js"; + +/** + * Hosted participants on gate-only installs (SELFHOST_RELAYGATE_PUBLIC_URL; + * docs/identity.md, "Hosted participants on gate-only installs"). + * + * relaygate is the only public way into Relaycast there, and its policy + * decides each agent's group. A hosted MCP participant used to be registered + * in Relaycast with the workspace key and to message with a Relaycast token, + * around relaygate. Now it enrols at relaygate's POST /v1/register with a + * single-use hosted credential (`sh_ht_`, ./relay-hosted-credentials.ts) and + * holds only an rg_ token, so every call it makes goes through relaygate. + * + * relaygate fails closed: a hosted credential matches only controlPrincipals + * rules that name the hosted kind, so an install without such a rule refuses + * the participant, and the error names the rule to add. + */ +export class HostedGateRefused extends Error { + constructor(message: string) { + super(message); + this.name = "HostedGateRefused"; + } +} + +export const hostedGateNoRule = (client: RelayHostedClient) => + `This install's relaygate policy does not allow hosted ${client} participants. Ask your operator to add a controlPrincipals rule with "kinds": ["hosted"] and "clients": ["${client}"] (see "Hosted participants" in relaygate's docs/contract.md).`; + +function refusal(error: unknown, input: { agentName: string; client: RelayHostedClient }): Error { + if (!(error instanceof RelaycastCallError)) return error instanceof Error ? error : new Error("relaygate enrolment failed"); + if (error.status === 0 || error.status >= 500) { + return new HostedGateRefused("relaygate is unavailable, so this hosted participant could not enrol. Retry shortly."); + } + if (error.status === 409) return new HostedGateRefused("That relay name is already taken. Choose another name."); + if (error.status === 403 && error.code === "relaygate_name_scope") { + return new HostedGateRefused(`relaygate's policy does not allow the name ${input.agentName} for hosted ${input.client} participants. Choose a name its rule allows.`); + } + if (error.status === 403) return new HostedGateRefused(hostedGateNoRule(input.client)); + if (error.status === 401) { + return new HostedGateRefused("relaygate could not verify this install's hosted participant credential. Check relaygate's relay-control introspection settings."); + } + return new HostedGateRefused("relaygate refused this hosted participant."); +} + +export type GateEnrolment = { + /** relaygate's agent id. */ + relaygateAgentId: string; + /** The upstream Relaycast agent id (what pins, retirement and launches key on). */ + relaycastAgentId: string; + name: string; + /** An rg_ token; only relaygate accepts it. */ + token: string; +}; + +/** + * Enrols (or, for the same owner and name, recovers) one hosted participant + * at relaygate. Throws HostedGateRefused with an operator-facing reason when + * relaygate refuses. + */ +export async function enrolHostedAtGate( + deps: { database: Database; gate: RelaycastClient }, + input: { workspaceId: string; organizationId: string; userId: string; agentName: string; client: RelayHostedClient }, +): Promise { + const { token: credential } = await relayHostedCredentials(deps.database).issue(input); + let enrolled; + try { + enrolled = await deps.gate.registerAtGate(credential, input.agentName); + } catch (error) { + throw refusal(error, input); + } + // relaygate names the Control user it enrolled the agent for; any other user is not this owner. + if (enrolled.userId !== null && enrolled.userId !== input.userId) { + await deps.gate.releaseOwnAgent(enrolled.token).catch(() => {}); + throw new HostedGateRefused("relaygate enrolled this participant for another user. Nothing was joined."); + } + const upstream = await deps.gate.authenticatedAgent(enrolled.token); + if (upstream.name !== input.agentName) throw new HostedGateRefused("relaygate enrolled a different agent name. Nothing was joined."); + return { relaygateAgentId: enrolled.agentId, relaycastAgentId: upstream.id, name: upstream.name, token: enrolled.token }; +} diff --git a/src/mcp/oauth/teardown.ts b/src/mcp/oauth/teardown.ts index d32a4039..e66da733 100644 --- a/src/mcp/oauth/teardown.ts +++ b/src/mcp/oauth/teardown.ts @@ -11,6 +11,8 @@ type Intent = { type Participant = { id:string; agent_name:string; agent_remote_id:string; relaycast_workspace_id:string; session_hash:string|null; token_ciphertext:string; + /** Set when the participant enrolled through relaygate: token_ciphertext then seals an rg_ token. */ + relaygate_agent_id:string|null; }; type Workspace = {relaycast_workspace_id:string|null;relaycast_api_key_ciphertext:string|null}; type Grant = {id:string;agent_remote_id:string|null;agent_name:string;created_at:Date|string}; @@ -91,6 +93,8 @@ export class McpOAuthTeardown { private migrationWarned=false; constructor(readonly deps:{ database:Database; keyring:EncryptionKeyring; client:RelaycastClient; now?:()=>Date; + /** Gate-only installs: participants enrolled through relaygate are looked up and released through it. */ + gate?:RelaycastClient; /** Wall-clock budget of one pass; the remainder follows in an immediate rerun. */ passBudgetMs?:number; }) {} @@ -228,7 +232,8 @@ export class McpOAuthTeardown { private async snapshot(tx:SqlExecutor,intent:Claim["intent"]):Promise { const workspace=(await tx.query(`SELECT relaycast_workspace_id,relaycast_api_key_ciphertext FROM workspaces WHERE id=$1 AND organization_id=$2`,[intent.workspace_id,intent.organization_id])).rows[0]??null; - const row=(await tx.query(`SELECT p.id,p.agent_name,p.agent_remote_id,p.relaycast_workspace_id,p.session_hash,p.token_ciphertext + const row=(await tx.query(`SELECT p.id,p.agent_name,p.agent_remote_id,p.relaycast_workspace_id,p.session_hash,p.token_ciphertext, + p.relaygate_agent_id FROM hosted_relay_participants p WHERE p.workspace_id=$1 AND p.user_id=$2 AND p.agent_remote_id=$3`, [intent.workspace_id,intent.user_id,intent.agent_remote_id])).rows[0]??null; @@ -273,6 +278,9 @@ export class McpOAuthTeardown { const byId=async()=>(await this.deps.client.listAgents(key,"all",{includeStale:true})) .find(agent=>agent.id===intent.agent_remote_id && agent.status!=="released")??null; let remote:RosterAgent|null; + // A participant enrolled through relaygate holds an rg_ token only relaygate accepts. + const via=row?.relaygate_agent_id && this.deps.gate ? this.deps.gate : this.deps.client; + let gateToken:string|null=null; if(row) { let token:string|null=null; // A token sealed under a retired key: the workspace-key roster still @@ -281,7 +289,8 @@ export class McpOAuthTeardown { try { if(token===null) remote=await byId(); else { - remote=await this.deps.client.authenticatedAgent(token); + remote=await via.authenticatedAgent(token); + if(via!==this.deps.client) gateToken=token; if(remote.status==="released") remote=null; } } catch(error) { @@ -316,6 +325,16 @@ export class McpOAuthTeardown { // a binding committed before the revocation row existed; the commit // re-read below is the last belt, and keeps the row pending if one appears. if(!await this.unchanged(claim)) return "pending"; + // Through relaygate when it still accepts the participant's token: that also revokes its relaygate tokens. + // A rejected (expired) rg_ token is held by no one, so the workspace-key release below is enough. + if(gateToken) { + try { + await this.deps.gate!.releaseOwnAgent(gateToken); + return {outcome:"released",deleteRow:true}; + } catch(error) { + if(!(error instanceof RelaycastCallError) || error.status!==401) throw error; + } + } try { await this.deps.client.releaseHosted(key,remote.name,remote.id); } catch(error) { diff --git a/src/mcp/relay-hosted-credentials.ts b/src/mcp/relay-hosted-credentials.ts new file mode 100644 index 00000000..1d36d895 --- /dev/null +++ b/src/mcp/relay-hosted-credentials.ts @@ -0,0 +1,145 @@ +import { randomUUID } from "node:crypto"; +import { recordAudit } from "../admin/audit.js"; +import { hashSecret, opaqueToken } from "../crypto.js"; +import type { Database } from "../database.js"; + +/** + * One-time hosted participant credentials for gate-only installs + * (SELFHOST_RELAYGATE_PUBLIC_URL set; docs/identity.md, "Hosted participants + * on gate-only installs"). Migration 0078. + * + * Every hosted MCP participant (an MCP connector's agent: ChatGPT, Grok Bot, + * Muse, Cursor cloud agents, any MCP client) enrols at relaygate, so the + * install's relaygate policy decides what it may do, never the workspace + * Relaycast key. relay-control mints one opaque `sh_ht_` credential per + * enrolment, bound to the workspace, organization, owning user, the exact + * agent name and the hosted client, and presents it itself to relaygate's + * POST /v1/register at once. relaygate introspects it at + * POST /internal/v1/auth/introspect, which answers principal_type + * `relay_hosted` and burns it on the first active answer (peek for the + * checks, then the atomic redeem). Only the hash is stored; the plaintext + * exists only for that one call and is never logged, audited or returned. + */ +export const RELAY_HOSTED_CREDENTIAL_PREFIX = "sh_ht_"; +/** Long enough for one relaygate round trip; never reused. */ +export const RELAY_HOSTED_CREDENTIAL_TTL_MS = 2 * 60 * 1_000; +export const RELAY_HOSTED_SCOPE = "relay:hosted:enrol"; +/** relaygate's hosted clients (relaygate src/hosted-clients.ts); a connector kind outside it is refused there. */ +export const RELAY_HOSTED_CLIENTS = ["chatgpt", "grok-bot", "muse", "cursor-cloud", "mcp"] as const; +export type RelayHostedClient = (typeof RELAY_HOSTED_CLIENTS)[number]; + +export type RelayHostedCredentialInput = { + workspaceId: string; + organizationId: string; + /** The participant's owner. */ + userId: string; + agentName: string; + client: RelayHostedClient; +}; + +export type RelayHostedCredentialRow = RelayHostedCredentialInput & { id: string; createdAt: Date; expiresAt: Date }; + +export type RelayHostedCredentialLookup = + | { state: "unknown" } + | { state: "expired" } + | { state: "redeemed" } + | { state: "active"; credential: RelayHostedCredentialRow }; + +const COLUMNS = "id, workspace_id, organization_id, user_id, agent_name, client, created_at, expires_at"; + +function rowFrom(row: Record): RelayHostedCredentialRow { + return { + id: String(row.id), + workspaceId: String(row.workspace_id), + organizationId: String(row.organization_id), + userId: String(row.user_id), + agentName: String(row.agent_name), + client: String(row.client) as RelayHostedClient, + createdAt: new Date(row.created_at as string | Date), + expiresAt: new Date(row.expires_at as string | Date), + }; +} + +const detail = (row: Pick) => + `${row.id} agent=${row.agentName} client=${row.client}`; + +export function relayHostedCredentials(database: Database) { + /** Read-only state of a presented token; never burns it. */ + async function peek(token: string): Promise { + if (!token.startsWith(RELAY_HOSTED_CREDENTIAL_PREFIX)) return { state: "unknown" }; + const result = await database.query( + `SELECT ${COLUMNS}, redeemed_at, expires_at <= now() AS expired FROM relay_hosted_credentials WHERE token_hash = $1`, + [hashSecret(token)], + ); + const row = result.rows[0]; + if (!row) return { state: "unknown" }; + if (row.redeemed_at) return { state: "redeemed" }; + if (row.expired === true) return { state: "expired" }; + return { state: "active", credential: rowFrom(row) }; + } + + return { + /** + * Mints a credential and records `relay_hosted.credential.issued`. The + * plaintext is for the caller's single relaygate registration only. + */ + async issue(input: RelayHostedCredentialInput): Promise<{ id: string; token: string; expiresAt: Date }> { + const token = opaqueToken(RELAY_HOSTED_CREDENTIAL_PREFIX); + const id = randomUUID(); + return database.transaction(async (tx) => { + const inserted = await tx.query<{ expires_at: Date | string }>( + `INSERT INTO relay_hosted_credentials + (id, workspace_id, organization_id, user_id, agent_name, client, token_hash, expires_at) + VALUES ($1, $2, $3, $4, $5, $6, $7, now() + ($8::integer * interval '1 millisecond')) + RETURNING expires_at`, + [id, input.workspaceId, input.organizationId, input.userId, input.agentName, input.client, + hashSecret(token), RELAY_HOSTED_CREDENTIAL_TTL_MS], + ); + const expiresAt = new Date(inserted.rows[0]!.expires_at); + await recordAudit(tx, { + organizationId: input.organizationId, + workspaceId: input.workspaceId, + actor: { kind: "user", userId: input.userId }, + action: "relay_hosted.credential.issued", + target: `${detail({ id, ...input })} expires=${expiresAt.toISOString()}`, + }); + return { id, token, expiresAt }; + }); + }, + + peek, + + /** + * Burns the credential atomically and records + * `relay_hosted.credential.redeemed`. Call only after every introspection + * check on peek() passed; a lost race never answers active twice. + */ + async redeem(token: string): Promise { + if (!token.startsWith(RELAY_HOSTED_CREDENTIAL_PREFIX)) return { state: "unknown" }; + const burned = await database.transaction(async (tx) => { + const result = await tx.query( + `UPDATE relay_hosted_credentials SET redeemed_at = now() + WHERE token_hash = $1 AND redeemed_at IS NULL AND expires_at > now() + RETURNING ${COLUMNS}`, + [hashSecret(token)], + ); + const row = result.rows[0]; + if (!row) return null; + const credential = rowFrom(row); + await recordAudit(tx, { + organizationId: credential.organizationId, + workspaceId: credential.workspaceId, + actor: { kind: "user", userId: credential.userId }, + action: "relay_hosted.credential.redeemed", + target: detail(credential), + }); + return credential; + }); + if (burned) return { state: "active", credential: burned }; + const current = await peek(token); + return current.state === "active" ? { state: "redeemed" } : current; + }, + }; +} + +export type RelayHostedCredentials = ReturnType; diff --git a/src/mcp/relay-participants.ts b/src/mcp/relay-participants.ts index 5fe3be3c..05fa2af2 100644 --- a/src/mcp/relay-participants.ts +++ b/src/mcp/relay-participants.ts @@ -16,6 +16,8 @@ import { connectorKind } from "./oauth/connector-kind.js"; import { LAUNCH_ROLE_REFUSAL } from "./catalog.js"; import { RECEIPT_GUIDANCE } from "../messaging/delivery-status.js"; import { MCP_OAUTH_RETIRING_MESSAGE, McpOAuthAgentRetiring, retiringIdentity } from "./oauth/retirement.js"; +import { enrolHostedAtGate, HostedGateRefused, type GateEnrolment } from "./hosted-gate.js"; +import type { RelayHostedClient } from "./relay-hosted-credentials.js"; /** * Hosted relay participants and the Relaycast operations behind the @@ -128,11 +130,16 @@ export type ParticipantRow = { agentName: string; agentRemoteId: string; tokenCiphertext: string; + /** + * relaygate's agent id when the participant enrolled through relaygate + * (gate-only installs; the token is then an rg_ token), else null. + */ + relaygateAgentId: string | null; }; type Selector = { name: string } | { sessionHash: string } | { agentRemoteId: string }; -const COLUMNS = `p.id, p.workspace_id, p.user_id, p.relaycast_workspace_id, p.session_hash, p.agent_name, p.agent_remote_id, p.token_ciphertext`; +const COLUMNS = `p.id, p.workspace_id, p.user_id, p.relaycast_workspace_id, p.session_hash, p.agent_name, p.agent_remote_id, p.token_ciphertext, p.relaygate_agent_id`; function rowFrom(row: Record): ParticipantRow { return { @@ -144,6 +151,7 @@ function rowFrom(row: Record): ParticipantRow { agentName: String(row.agent_name), agentRemoteId: String(row.agent_remote_id), tokenCiphertext: String(row.token_ciphertext), + relaygateAgentId: typeof row.relaygate_agent_id === "string" ? row.relaygate_agent_id : null, }; } @@ -163,20 +171,22 @@ async function findParticipant(executor: SqlExecutor, workspaceId: string, userI async function insertParticipant(executor: SqlExecutor, row: Omit): Promise { await executor.query( `INSERT INTO hosted_relay_participants - (id, workspace_id, user_id, relaycast_workspace_id, session_hash, agent_name, agent_remote_id, token_ciphertext) - VALUES ($1, $2, $3, $4, $5, $6, $7, $8)`, - [randomUUID(), row.workspaceId, row.userId, row.relayWorkspaceId, row.sessionHash, row.agentName, row.agentRemoteId, row.tokenCiphertext], + (id, workspace_id, user_id, relaycast_workspace_id, session_hash, agent_name, agent_remote_id, token_ciphertext, relaygate_agent_id) + VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)`, + [randomUUID(), row.workspaceId, row.userId, row.relayWorkspaceId, row.sessionHash, row.agentName, row.agentRemoteId, row.tokenCiphertext, + row.relaygateAgentId], ); } async function updateParticipant(executor: SqlExecutor, id: string, - fields: { sessionHash?: string; agentName?: string; tokenCiphertext?: string }) { + fields: { sessionHash?: string; agentName?: string; tokenCiphertext?: string; relaygateAgentId?: string }) { await executor.query( `UPDATE hosted_relay_participants SET session_hash = COALESCE($2, session_hash), agent_name = COALESCE($3, agent_name), - token_ciphertext = COALESCE($4, token_ciphertext), updated_at = now() + token_ciphertext = COALESCE($4, token_ciphertext), relaygate_agent_id = COALESCE($5, relaygate_agent_id), + updated_at = now() WHERE id = $1`, - [id, fields.sessionHash ?? null, fields.agentName ?? null, fields.tokenCiphertext ?? null], + [id, fields.sessionHash ?? null, fields.agentName ?? null, fields.tokenCiphertext ?? null, fields.relaygateAgentId ?? null], ); } @@ -239,7 +249,12 @@ export function relayFailure(error: unknown, operation?: RelayToolOperation) { // The per-request relay service. /** `desktop` marks a synced Agent Relay Desktop identity; its deliveries are injected, not polled. */ -type Identity = { name: string; token: string; desktop?: boolean; factory?: boolean; capy?: boolean; capyGrant?: boolean }; +/** + * `gated` marks a hosted participant enrolled through relaygate (gate-only + * installs): its token is an rg_ token, and every call it makes, reads + * included, goes through relaygate. + */ +type Identity = { name: string; token: string; desktop?: boolean; gated?: boolean; factory?: boolean; capy?: boolean; capyGrant?: boolean }; type DesktopActor = LinkedDesktopIdentity & { desktop: true }; /** * `remotePresent` and the ownership checks come from the token or, when @@ -257,6 +272,8 @@ type ParticipantOptions = { /** The caller binds this MCP session to the selected row (native join); requires `executor` under the owner lock. */ bind?: boolean; executor?: SqlExecutor; + /** The owner's launcher (withSpawnActor only): on gate-only installs it is never a messaging identity. */ + internal?: boolean; }; /** The hosted participant every agent launch of one owner is sent as (src/mcp/relay-spawn.ts). */ export type SpawnActor = { @@ -283,7 +300,13 @@ export async function hasActiveLaunches(executor: SqlExecutor, workspaceId: stri const UNKNOWN_CARD_AGENT = "Unknown agent name or stale machine address in this workspace. Use list_relay_agents."; const CARD_NEEDS_IDENTITY = "This MCP session has no relay identity to publish a card for. Call join_relay with desktop_address (from GET /whoami on the relay socket) to publish your Agent Relay Desktop identity's card, or join_relay to use a hosted participant, then retry."; const CARD_IDENTITY_CHANGED = "Your relay identity is no longer available or changed. Call relay_status, join_relay again if needed, then retry."; +/** joinLocked found nothing to join on a gate-only install: enrol at relaygate outside the lock, then retry. */ +const NEEDS_GATE_ENROLMENT = Symbol("needs-gate-enrolment"); const NO_PARTICIPANT_MESSAGE = "No hosted participant with that name is owned by you in this workspace."; +/** Gate-only installs: reads go through relaygate as the caller's own relay identity, so one is needed first. */ +export const GATE_JOIN_FIRST = "This install routes relay traffic through relaygate, which answers as your relay identity. Call join_relay first (or join_relay with desktop_address to use your Agent Relay Desktop identity), then retry."; +export const GATE_RENEW_FAILED = "relaygate did not accept this hosted participant's token, and renewing it failed. Retry; if it keeps failing, ask your operator whether relaygate's policy still allows hosted participants."; +export const GATE_OAUTH_LAUNCH_REFUSED = "Launching agents from a hosted connector is not available on this install: relaygate does not proxy launches. Launch from Agent Relay Desktop or a native MCP session."; const rejectedToken = (name: string) => new RelayToolError( `The relay token for participant ${name} was rejected by Relaycast. Call join_relay with name=${name} to recover it, or leave_relay to remove it.`); type ChannelInput = { as?: string; as_person?: boolean; hosted?: boolean }; @@ -292,10 +315,19 @@ function createRelayService(context: McpContext) { const { database, keyring, client, sessionId, gateClient: gate } = context.relay; /** * The client for calls made with an identity's own token. On gate-only - * installs a Desktop identity holds an rg_ token only relaygate accepts, - * so those calls go through relaygate; hosted participants keep Relaycast. + * installs Desktop identities and hosted participants hold rg_ tokens only + * relaygate accepts, so those calls go through relaygate. */ - const clientFor = (identity: { desktop?: boolean }) => identity.desktop && gate ? gate : client; + const clientFor = (identity: { desktop?: boolean; gated?: boolean }) => (identity.desktop || identity.gated) && gate ? gate : client; + /** + * Directory reads (roster, names, channels, channel history) for an + * identity: a gated hosted participant reads through relaygate with its own + * token, so relaygate's policy filters what it sees; everyone else reads + * with the workspace key as before. + */ + const directory = (identity?: Identity | null) => identity?.gated && gate + ? { via: gate, credential: identity.token } : { via: client, credential: key }; + type Directory = ReturnType; const workspaceId = context.workspace.id; const organizationId = context.workspace.organizationId; const executor = database; @@ -410,12 +442,138 @@ function createRelayService(context: McpContext) { } } + /** The hosted MCP client relaygate's policy matches this caller's participants on. */ + let clientKind: Promise | undefined; + function hostedClient(): Promise { + clientKind ??= (async () => { + if (!oauth) return "mcp" as const; + const row = (await executor.query<{ client_name: string | null; redirect_uris: string[] }>( + "SELECT client_name, redirect_uris FROM mcp_oauth_clients WHERE client_id = $1", [oauth.access.clientId])).rows[0]; + return row ? connectorKind({ clientName: row.client_name, redirectUris: row.redirect_uris ?? [] }) : "mcp" as const; + })(); + return clientKind; + } + + /** Enrols `name` for this owner at relaygate; refusals become tool errors naming what the operator must change. */ + async function enrolAtGate(name: string): Promise { + try { + return await enrolHostedAtGate({ database, gate: gate! }, { + workspaceId, organizationId, userId, agentName: name, client: await hostedClient() }); + } catch (error) { + if (error instanceof HostedGateRefused) throw new RelayToolError(error.message); + throw error; + } + } + + /** + * A gated participant's live state at relaygate: whoami must name the + * stored relaygate agent and this owner, and the upstream agent behind it + * must be the stored Relaycast agent. "rejected" means relaygate no longer + * accepts the token (it expires after 24 hours). + */ + async function gateState(row: ParticipantRow, token: string): + Promise<{ state: "ok"; remote: RosterAgent } | { state: "rejected" } | { state: "changed" }> { + let who; + try { + who = await gate!.whoami(token); + } catch (error) { + if (error instanceof RelaycastCallError && error.status === 401) return { state: "rejected" }; + throw error; + } + if (who.agentId !== row.relaygateAgentId || (who.userId !== null && who.userId !== userId)) return { state: "changed" }; + const remote = await gate!.authenticatedAgent(token); + return remote.id === row.agentRemoteId && remote.status !== "released" ? { state: "ok", remote } : { state: "changed" }; + } + + /** The row participant() would select for `as` (or this session), read without the owner lock. */ + async function selectedRow(as?: string): Promise { + const approvedId = oauth?.access.agentRemoteId; + const name = oauth && !approvedId ? oauth.access.agentName : as; + const selector: Selector | null = approvedId ? { agentRemoteId: approvedId } + : name ? { name } : sessionHash ? { sessionHash } : null; + return selector ? findParticipant(executor, workspaceId, userId, organizationId, selector) : null; + } + + /** + * Gate-only installs, before any owner-locked work: makes the selected row + * usable at relaygate. A gated row whose rg_ token relaygate rejects (it + * expires after 24 hours) enrols again, and the same owner gets the same + * relaygate agent back. A row registered in Relaycast directly before this + * install enforced relaygate for hosted participants is enrolled through + * relaygate once, after its upstream agent is confirmed as this owner's + * with the workspace roster (a one-time control-plane check, never the + * participant's traffic), so the enrolment only takes over the agent the + * row already is. relaygate introspects the credential with this service, + * so no transaction is open while it enrols; the result is written under + * the owner lock only if the row is unchanged. Throws when relaygate + * refuses, naming what its policy is missing. + */ + async function refreshGated(as?: string): Promise { + if (!gate) return; + const row = await selectedRow(as); + if (!row || row.relayWorkspaceId !== relayWorkspaceId || row.agentName === launcherName(userId)) return; + if (row.relaygateAgentId !== null && (await gateState(row, decryptSecret(row.tokenCiphertext, keyring))).state !== "rejected") return; + if (row.relaygateAgentId === null) { + const upstream = await client.getRosterAgent(key, row.agentName); + if (!upstream || upstream.status === "released" || upstream.id !== row.agentRemoteId || !ownsRemote(upstream)) return; + } + const enrolled = await enrolAtGate(row.agentName); + if (enrolled.relaycastAgentId !== row.agentRemoteId || + (row.relaygateAgentId !== null && enrolled.relaygateAgentId !== row.relaygateAgentId)) { + // The agent this row was is gone (relaygate enrolled a fresh one under the name): never adopt it. + await gate.releaseOwnAgent(enrolled.token).catch(() => {}); + return; + } + await withOwnerLock(async (tx) => { + const current = await findParticipant(tx, workspaceId, userId, organizationId, { agentRemoteId: row.agentRemoteId }); + if (!current || current.id !== row.id || current.tokenCiphertext !== row.tokenCiphertext) return; + await updateParticipant(tx, row.id, { + tokenCiphertext: encryptSecret(enrolled.token, keyring.active), relaygateAgentId: enrolled.relaygateAgentId }); + }); + } + + /** + * participant() on a gate-only install. Never enrols (refreshGated did, + * before the lock). A row relaygate does not accept is returned only to + * `allowRejected` callers, for cleanup: its upstream agent is then + * released with the workspace key, as for any participant whose token no + * one can use. + */ + async function gatedParticipant(row: ParticipantRow, requested: string | undefined, options: ParticipantOptions): Promise { + const { allowGone = false, allowRejected = false, executor: query = executor } = options; + const token = decryptSecret(row.tokenCiphertext, keyring); + const checked = row.relaygateAgentId === null ? null : await gateState(row, token); + if (checked?.state === "changed" && !allowGone) { + throw new RelayToolError("The hosted participant is no longer available. Its relay identity changed."); + } + let remote: RosterAgent | null = checked?.state === "ok" ? checked.remote : null; + const usable = remote !== null; + if (!usable && checked?.state !== "changed") { + if (!allowRejected) throw new RelayToolError(GATE_RENEW_FAILED); + const upstream = await client.getRosterAgent(key, row.agentName); + remote = upstream && upstream.id === row.agentRemoteId && upstream.status !== "released" ? upstream : null; + } + let name = row.agentName; + if (usable && remote && remote.name !== row.agentName) { + await updateParticipant(query, row.id, { agentName: remote.name }); + name = remote.name; + } + if (oauth) { + oauth.assertActor(requested, name); + if (usable) await oauth.pin(query, { workspaceId, userId, agentName: name, agentRemoteId: row.agentRemoteId }); + } + return { row: { ...row, agentName: name }, token, name, gated: usable, + remotePresent: remote !== null, tokenUsable: usable }; + } + /** * The owner's participant selected by `as`, else by this MCP session. * Verifies the remote agent is still the one this owner registered, and * refuses a rejected token unless `allowRejected`. */ async function participant(as?: string, options: ParticipantOptions = {}): Promise { + // Gate-only installs renew or migrate the row at relaygate before any lock is taken. + if (gate && !options.executor && !options.internal) await refreshGated(as); if (oauth && !options.executor) return withOwnerLock(tx=>participant(as,{...options,executor:tx})); const { allowMissing = false, allowGone = false, allowRejected = false, executor: query = executor } = options; const requested = as; @@ -437,6 +595,12 @@ function createRelayService(context: McpContext) { if (((oauth && !approvedId) || (options.bind && !row.sessionHash)) && options.executor) { await refuseRetiring(query, row.agentRemoteId, row.agentName); } + if (gate) { + // The owner's launcher stays a Relaycast identity (relaygate does not proxy launches; each launch is + // checked at relaygate's /v1/check instead), so it never messages on a gate-only install. + if (row.agentName === launcherName(userId) && !options.internal) throw new RelayToolError(NO_PARTICIPANT_MESSAGE); + if (row.agentName !== launcherName(userId)) return gatedParticipant(row, requested, options); + } const token = decryptSecret(row.tokenCiphertext, keyring); const { remote, tokenUsable } = await hostedRemote(row, token); if ((!remote && !allowGone) || (remote && (remote.id !== row.agentRemoteId || !ownsRemote(remote)))) { @@ -455,28 +619,28 @@ function createRelayService(context: McpContext) { return { row: { ...row, agentName: name }, token, name, remotePresent: remote !== null, tokenUsable }; } - async function touchPresence(token: string): Promise { + async function touchPresence(identity: Identity): Promise { try { - await client.heartbeat(token); + await clientFor(identity).heartbeat(identity.token); } catch { // Presence is best effort; the call itself proceeds. } } - async function listedAgents(status: "active" | "all", includeStale = false) { - return (await client.listAgents(key, status, { includeStale })).filter(isListedRelayAgent); + async function listedAgents(status: "active" | "all", includeStale = false, dir: Directory = directory()) { + return (await dir.via.listAgents(dir.credential, status, { includeStale })).filter(isListedRelayAgent); } - async function roster(status: "live" | "all" | "offline", people: readonly McpMember[], includeStale = false) { - return (await listedAgents(status === "live" ? "active" : "all", includeStale)) + async function roster(status: "live" | "all" | "offline", people: readonly McpMember[], includeStale = false, dir: Directory = directory()) { + return (await listedAgents(status === "live" ? "active" : "all", includeStale, dir)) .map(agent => ({ ...rosterAgent(agent, people, userId, workspaceId), ...cardSummary(agent.metadata) })) .filter(agent => status === "all" || (status === "live" ? agent.online : !agent.online)); } - async function addressFor(name: string, bestEffort = false): Promise { + async function addressFor(name: string, bestEffort = false, dir: Directory = directory()): Promise { try { // Bounded lookup: one name, never the whole roster. - const agent = await client.findAgentByName(key, name); + const agent = await dir.via.findAgentByName(dir.credential, name); return agent && isListedRelayAgent(agent) ? agent.address : null; } catch (error) { if (bestEffort) return null; @@ -485,16 +649,16 @@ function createRelayService(context: McpContext) { } /** A name or `name@machine` address, resolved by name without listing the roster. */ - async function explicitAgent(target: string): Promise { + async function explicitAgent(target: string, dir: Directory = directory()): Promise { const separator = target.lastIndexOf("@"); const name = separator < 0 ? target : target.slice(0, separator); if (!name) return null; - const agent = await client.findAgentByName(key, name) ?? await client.getRosterAgent(key, name); + const agent = await dir.via.findAgentByName(dir.credential, name) ?? await dir.via.getRosterAgent(dir.credential, name); return agent?.name === name && (separator < 0 || agent.address === target) ? agent : null; } - async function recipient(to: string, people: readonly McpMember[]) { - const agent = await explicitAgent(to); + async function recipient(to: string, people: readonly McpMember[], dir: Directory = directory()) { + const agent = await explicitAgent(to, dir); if (!agent || agent.status === "released" || agent.metadata.source === "cloud-persona-deploy" || agent.metadata.source === "cloud-persona") { throw new RelayToolError("Unknown agent name or stale machine address in this workspace. Use list_relay_agents."); @@ -507,8 +671,17 @@ function createRelayService(context: McpContext) { .find(item => item.participants.length === 2 && item.participants.includes(name) && item.participants.includes(peer)); } - /** Callers hold the owner lock. */ - async function registerParticipant(tx: SqlExecutor, name: string, boundSession: string | null, objective: string) { + /** + * Callers hold the owner lock. On a gate-only install every participant but + * the owner's launcher (`internal`) enrols through relaygate. + */ + async function registerParticipant(tx: SqlExecutor, name: string, boundSession: string | null, objective: string, + options: { internal?: boolean; enrolled?: GateEnrolment } = {}) { + if (gate && !options.internal) { + // Gate-only installs enrol at relaygate before the owner lock (prepareGateRegistration). + if (!options.enrolled || options.enrolled.name !== name) throw new Error("gate registration needs a prepared enrolment"); + return registerAtGate(tx, options.enrolled, boundSession); + } const remote = await client.getAgent(key, name); if (remote && !ownsRemote(remote)) throw new RelayToolError("That relay name is already taken. Choose another name."); // Recovering an owned agent binds it again; its release may be in flight. @@ -526,7 +699,7 @@ function createRelayService(context: McpContext) { await insertParticipant(tx, { workspaceId, userId, relayWorkspaceId, sessionHash: boundSession, agentName: registered.name, agentRemoteId: registered.id, - tokenCiphertext: encryptSecret(registered.token, keyring.active), + tokenCiphertext: encryptSecret(registered.token, keyring.active), relaygateAgentId: null, }); if (oauth) await oauth.pin(tx, { workspaceId, userId, agentName: registered.name, agentRemoteId: registered.id }); } catch (error) { @@ -536,6 +709,66 @@ function createRelayService(context: McpContext) { return registered; } + /** + * Gate-only installs, before the owner lock: relaygate enrols the name for + * this owner (refusing it, with the rule to add, when its policy has none + * for this hosted client). relaygate introspects the credential with this + * service, so no transaction may be open meanwhile. The owner metadata + * Relaycast registration used to carry is merged through relaygate: OAuth + * teardown and the roster read it. Ownership itself is decided by + * relaygate's whoami, never by it. + */ + async function prepareGateRegistration(name: string, objective: string): Promise { + const enrolled = await enrolAtGate(name); + try { + await gate!.mergeOwnAgentMetadata(enrolled.token, { + source: HOSTED_SOURCE, cloud_workspace_id: workspaceId, owner_hash: owner, objective, + kind: await hostedKind(), hosted_client: await hostedClient(), ...(ownerName ? { owner_name: ownerName } : {}), + ...(oauth ? { created_by: "mcp-oauth" } : {}), + }); + } catch (error) { + await gate!.releaseOwnAgent(enrolled.token).catch(() => {}); + throw error; + } + return enrolled; + } + + /** registerParticipant on a gate-only install, under the owner lock: the row keeps relaygate's rg_ token. */ + async function registerAtGate(tx: SqlExecutor, enrolled: GateEnrolment, boundSession: string | null) { + try { + // The same owner may get an agent back whose release is in flight. + await refuseRetiring(tx, enrolled.relaycastAgentId, enrolled.name); + await insertParticipant(tx, { + workspaceId, userId, relayWorkspaceId, sessionHash: boundSession, + agentName: enrolled.name, agentRemoteId: enrolled.relaycastAgentId, + tokenCiphertext: encryptSecret(enrolled.token, keyring.active), relaygateAgentId: enrolled.relaygateAgentId, + }); + if (oauth) await oauth.pin(tx, { workspaceId, userId, agentName: enrolled.name, agentRemoteId: enrolled.relaycastAgentId }); + } catch (error) { + // Never leave a retiring agent's release to race a new binding: only a fresh one is released here. + if (!(error instanceof RelayToolError && error.message === MCP_OAUTH_RETIRING_MESSAGE)) { + await gate!.releaseOwnAgent(enrolled.token).catch(() => {}); + } + throw error; + } + return { id: enrolled.relaycastAgentId, name: enrolled.name, token: enrolled.token }; + } + + /** Releases a participant's agent: through relaygate (its own token) when gated, else with the workspace key. */ + async function releaseRemote(hosted: Hosted): Promise { + if (!hosted.remotePresent) return; + if (hosted.gated) { + await gate!.releaseOwnAgent(hosted.token); + return; + } + try { + await client.releaseHosted(key, hosted.name, hosted.row.agentRemoteId); + } catch (error) { + // A concurrent remote deletion also completes the release. + if (!(error instanceof RelaycastCallError) || error.status !== 404 || await client.getAgent(key, hosted.name)) throw error; + } + } + /** * Re-issues the token of an existing participant whose stored token * Relaycast rejects. Callers hold the owner lock, and `participant` has @@ -577,33 +810,55 @@ function createRelayService(context: McpContext) { if (!sessionHash && !input.name && !oauth) { throw new RelayToolError("Initialize MCP to receive Mcp-Session-Id, or pass an explicit name and use as on later calls."); } + const requestedName = oauth?.access.agentName ?? input.name ?? automaticParticipantName(context.principal, sessionHash!); + const ownerLabel = context.principal.name.trim() || context.principal.email || userId; + const objective = input.description ?? `Hosted MCP inbox participant acting for ${ownerLabel}`; + if (gate) { + // Gate-only installs: the launcher name is the owner's launcher, never a messaging participant. + if (requestedName === launcherName(userId)) throw new RelayToolError("That relay name is reserved. Choose another name."); + // Renew or migrate an existing participant at relaygate before taking the owner lock. + await refreshGated(); + await refreshGated(requestedName); + } + let prepared: GateEnrolment | undefined; + for (;;) { + const outcome = await joinLocked(input, requestedName, objective, prepared); + if (outcome !== NEEDS_GATE_ENROLMENT) return outcome; + // No participant yet: enrol at relaygate with no lock held, then join again under the lock. + prepared = await prepareGateRegistration(requestedName, objective); + } + } + + async function joinLocked(input: { name?: string; description?: string }, requestedName: string, objective: string, + prepared: GateEnrolment | undefined) { const joined = await withOwnerLock(async (tx) => { const bound = await participant(undefined, { allowRejected: true, executor: tx }); if (oauth && bound) oauth.assertActor(input.name, bound.name); if (bound && input.name && bound.name !== input.name && !oauth) { throw new RelayToolError("This MCP session is already joined. Leave before choosing another name."); } - const requestedName = oauth?.access.agentName ?? input.name ?? automaticParticipantName(context.principal, sessionHash!); const existing = bound ?? await participant(requestedName, { allowMissing: true, allowRejected: true, executor: tx, bind: Boolean(sessionHash) }); if (existing) { if (sessionHash && existing.row.sessionHash && existing.row.sessionHash !== sessionHash) { throw new RelayToolError("That participant is bound to another MCP session. Use as to act as it without changing its binding, or choose a new name."); } + // A gated participant is renewed only at relaygate (refreshGated), never by a Relaycast takeover. + if (gate && existing.row.agentName !== launcherName(userId) && !existing.tokenUsable) throw new RelayToolError(GATE_RENEW_FAILED); const token = existing.tokenUsable ? existing.token : await recoverToken(tx, existing); if (sessionHash && !existing.row.sessionHash) await updateParticipant(tx, existing.row.id, { sessionHash }); await unlinkDesktop(tx); - return { name: existing.name, token, alreadyJoined: true, recovered: !existing.tokenUsable }; + return { name: existing.name, token, gated: existing.gated, alreadyJoined: true, recovered: !existing.tokenUsable }; } - const ownerLabel = context.principal.name.trim() || context.principal.email || userId; - const registered = await registerParticipant(tx, requestedName, sessionHash, - input.description ?? `Hosted MCP inbox participant acting for ${ownerLabel}`); + if (gate && !prepared) return NEEDS_GATE_ENROLMENT; + const registered = await registerParticipant(tx, requestedName, sessionHash, objective, { enrolled: prepared }); // Joining a hosted participant replaces this session's desktop link. await unlinkDesktop(tx); - return { name: registered.name, token: registered.token, alreadyJoined: false, recovered: false }; + return { name: registered.name, token: registered.token, gated: Boolean(gate), alreadyJoined: false, recovered: false }; }); - await touchPresence(joined.token); - return { joined: true, linked: "hosted" as const, name: joined.name, address: await addressFor(joined.name, true), + if (joined === NEEDS_GATE_ENROLMENT) return joined; + await touchPresence(joined); + return { joined: true, linked: "hosted" as const, name: joined.name, address: await addressFor(joined.name, true, directory(joined)), already_joined: joined.alreadyJoined, recovered: joined.recovered, reply_guidance: HOSTED_REPLY_GUIDANCE, desktop_relay_guidance: DESKTOP_RELAY_GUIDANCE }; } @@ -624,6 +879,8 @@ function createRelayService(context: McpContext) { if (!sessionHash) throw new RelayToolError(DESKTOP_LINK_NEEDS_SESSION); const linkedSession = sessionHash; const owned = { workspaceId, userId, sessionHash: linkedSession }; + // Gate-only installs: renew this session's participant at relaygate first, so linking releases it through relaygate. + await refreshGated().catch(() => {}); const joined = await withOwnerLock(async (tx) => { const row = await findDesktopIdentityByAddress(tx, workspaceId, userId, address); if (!row) { @@ -652,14 +909,7 @@ function createRelayService(context: McpContext) { await bind(); try { if (hosted) { - if (hosted.remotePresent) { - try { - await client.releaseHosted(key, hosted.name, hosted.row.agentRemoteId); - } catch (error) { - // A concurrent remote deletion also completes the release. - if (!(error instanceof RelaycastCallError) || error.status !== 404 || await client.getAgent(key, hosted.name)) throw error; - } - } + await releaseRemote(hosted); await removeParticipant(tx, hosted.row.id); } } catch (error) { @@ -735,7 +985,7 @@ function createRelayService(context: McpContext) { hosted = await participant(); } if (!hosted) throw new RelayToolError("Could not create a hosted participant for this MCP session. Call join_relay, then retry."); - await touchPresence(hosted.token); + await touchPresence(hosted); return fn(hosted); } @@ -768,7 +1018,7 @@ function createRelayService(context: McpContext) { if (create) return hostedActor(input.as, fn); const hosted = await participant(input.as); if (!hosted) return null; - await touchPresence(hosted.token); + await touchPresence(hosted); return fn(hosted); } @@ -782,7 +1032,7 @@ function createRelayService(context: McpContext) { const cardOptions = { organization: context.workspace.name, relaycastUrl: context.relay.relaycastPublicUrl }; - type CardIdentity = { name: string; agentId: string; linked: "desktop" | "hosted"; kind: string }; + type CardIdentity = { name: string; agentId: string; linked: "desktop" | "hosted"; kind: string; gated?: { token: string } }; /** The identity set_relay_agent_card writes: the caller's own, chosen as relay_status reports it. */ async function ownCardIdentity(): Promise { @@ -794,7 +1044,8 @@ function createRelayService(context: McpContext) { if (linkedIdentity) return { name: linkedIdentity.name, agentId: linkedIdentity.agentId, linked: "desktop", kind: DESKTOP_KIND }; const hosted = await participant(); if (!hosted) throw new RelayToolError(CARD_NEEDS_IDENTITY); - return { name: hosted.name, agentId: hosted.row.agentRemoteId, linked: "hosted", kind: await hostedKind() }; + return { name: hosted.name, agentId: hosted.row.agentRemoteId, linked: "hosted", kind: await hostedKind(), + ...(hosted.gated ? { gated: { token: hosted.token } } : {}) }; } /** @@ -818,6 +1069,8 @@ function createRelayService(context: McpContext) { */ async function withSpawnActor(fn: (actor: SpawnActor) => Promise): Promise { if (oauth) { + // A gated participant's rg_ token can't invoke launches: relaygate does not proxy them. + if (gate) throw new RelayToolError(GATE_OAUTH_LAUNCH_REFUSED); // The grant's approved participant is the launcher; never borrow the // person's native launcher or another client's identity. await withOwnerLock(async () => { @@ -843,10 +1096,10 @@ function createRelayService(context: McpContext) { } const name = launcherName(userId); const actor = await withOwnerLock(async (tx) => { - let hosted = await participant(name, { allowMissing: true, allowRejected: true, executor: tx }); + let hosted = await participant(name, { allowMissing: true, allowRejected: true, executor: tx, internal: true }); if (!hosted) { - await registerParticipant(tx, name, null, "Launches agents for its owner through MCP"); - hosted = await participant(name, { executor: tx }); + await registerParticipant(tx, name, null, "Launches agents for its owner through MCP", { internal: true }); + hosted = await participant(name, { executor: tx, internal: true }); if (!hosted) throw new RelayToolError("Could not create the launcher participant. Retry."); } const token = hosted.tokenUsable ? hosted.token : await recoverToken(tx, hosted); @@ -856,13 +1109,46 @@ function createRelayService(context: McpContext) { return fn(actor); } + /** + * The directory a tool with no acting identity of its own reads (the + * roster, a card): the workspace key, except on a gate-only install where a + * caller that is not a Desktop identity reads through relaygate as its + * hosted participant, and must have joined first. + */ + async function callerDirectory(): Promise { + if (!gate || managed || await linkedDesktop()) return directory(); + const hosted = await participant(); + if (!hosted) throw new RelayToolError(GATE_JOIN_FIRST); + return directory(hosted); + } + + /** read_relay_conversation once the reading identity and the peer's name are known. */ + async function readConversation(hosted: Identity, peerName: string, input: { before?: string; limit: number }) { + const via = clientFor(hosted); + // relaygate does not proxy heartbeats; Desktop keeps its own presence. + if (via === client) await touchPresence(hosted); + const conv = await conversation(hosted.token, hosted.name, peerName, via); + if (!conv) return { you: hosted.name, conversation_id: null, messages: [], earlier: null }; + const page = await via.listMessages(hosted.token, conv.id, { before: input.before, limit: input.limit }); + const messages = []; + // The DM listing omits thread_id; enrich only authorized ids, five at a time. + for (let index = 0; index < page.messages.length; index += 5) { + messages.push(...await Promise.all(page.messages.slice(index, index + 5).map(async message => ({ + message_id: message.id, sender: message.sender, text: message.text, created_at: message.createdAt, + thread_id: await via.getMessageThreadId(hosted.token, message.id), mine: message.sender === hosted.name, + })))); + } + return { you: hosted.name, conversation_id: conv.id, messages, + earlier: page.hasEarlier ? page.messages[0]?.id ?? null : null }; + } + return { withSpawnActor, async list(input: { status: "live" | "all" | "offline"; person?: string; query?: string; include_stale?: boolean }) { const query = input.query?.toLowerCase(); const person = input.person?.toLowerCase(); - const agents = await roster(input.status, await context.members(), input.include_stale); + const agents = await roster(input.status, await context.members(), input.include_stale, await callerDirectory()); return { workspace_id: workspaceId, agents: agents.filter(agent => (!person || (person === "me" ? agent.is_mine : agent.owner?.user_id.toLowerCase() === person || agent.owner?.name.toLowerCase().includes(person))) && @@ -873,7 +1159,7 @@ function createRelayService(context: McpContext) { /** get_relay_agent_card: any listed agent in this workspace, by name or exact machine address. Read-only. */ async getCard(input: { agent: string }) { - const agent = await explicitAgent(input.agent.trim()); + const agent = await explicitAgent(input.agent.trim(), await callerDirectory()); if (!agent || agent.status === "released" || !isListedRelayAgent(agent)) throw new RelayToolError(UNKNOWN_CARD_AGENT); return buildAgentCard(agent, cardOptions); }, @@ -889,6 +1175,16 @@ function createRelayService(context: McpContext) { */ async setCard(input: SetCardInput) { const own = await ownCardIdentity(); + if (own.gated) { + // A gated participant writes its own card through relaygate (which merges it upstream). + const current = await gate!.authenticatedAgent(own.gated.token); + if (current.id !== own.agentId || current.status === "released") throw new RelayToolError(CARD_IDENTITY_CHANGED); + await gate!.mergeOwnAgentMetadata(own.gated.token, { + ...cardMetadata(input, current.metadata, new Date()), kind: own.kind, ...(ownerName ? { owner_name: ownerName } : {}) }); + const updated = await gate!.authenticatedAgent(own.gated.token); + if (updated.id !== own.agentId) throw new RelayToolError(CARD_IDENTITY_CHANGED); + return { updated: true, linked: own.linked, name: updated.name, card: buildAgentCard(updated, cardOptions) }; + } const current = await client.getRosterAgent(key, own.name); if (!current || current.id !== own.agentId || current.status === "released") throw new RelayToolError(CARD_IDENTITY_CHANGED); // Only these keys are sent; Relaycast merges them, keeping every other key. @@ -910,13 +1206,15 @@ function createRelayService(context: McpContext) { await desktop(); return { joined: false, desktop_agent_unchanged: true, native_chat_identity_retained: true }; } + // Gate-only installs: renew at relaygate first so the release goes through it; a refusal still lets it leave. + await refreshGated(as).catch(() => {}); return withOwnerLock(async (tx) => { if (!as && sessionHash && !oauth && await findDesktopIdentityBySession(tx, workspaceId, userId, sessionHash)) { // Unlinking leaves the Desktop's own agent running. await unlinkDesktop(tx); return { joined: false, linked: null, already_left: false, desktop_agent_unchanged: true }; } - // Release uses the workspace key, so a rejected token can still leave. + // Release uses the workspace key (or, gated, a token re-enrolled at relaygate), so a rejected token can still leave. const hosted = await participant(as, { allowGone: true, allowRejected: true, executor: tx }); if (!hosted) return { joined: false, already_left: true }; if (oauth && hosted.row.sessionHash) { @@ -926,14 +1224,7 @@ function createRelayService(context: McpContext) { throw new RelayToolError("Another active connection still uses this agent. Disconnect it before leaving."); } if (await hasActiveLaunches(tx, workspaceId, hosted.row.agentRemoteId)) throw new RelayToolError(ACTIVE_LAUNCHES); - if (hosted.remotePresent) { - try { - await client.releaseHosted(key, hosted.name, hosted.row.agentRemoteId); - } catch (error) { - // A concurrent remote deletion also completes leave. - if (!(error instanceof RelaycastCallError) || error.status !== 404 || await client.getAgent(key, hosted.name)) throw error; - } - } + await releaseRemote(hosted); await removeParticipant(tx, hosted.row.id); return { joined: false, already_left: false }; }); @@ -954,8 +1245,8 @@ function createRelayService(context: McpContext) { const hosted = await participant(as); if (!hosted) return { joined: false, name: null, address: null, unread_count: 0, guidance: "Send a message with send_relay_message to auto-join this MCP session, or call join_relay first." }; - await touchPresence(hosted.token); - const [address, inbox] = await Promise.all([addressFor(hosted.name), client.readHostedInbox(hosted.token)]); + await touchPresence(hosted); + const [address, inbox] = await Promise.all([addressFor(hosted.name, false, directory(hosted)), clientFor(hosted).readHostedInbox(hosted.token)]); return { joined: true, linked: "hosted" as const, name: hosted.name, address, unread_count: inbox.length, unread_count_is_lower_bound: inbox.length === 100 }; }, @@ -974,21 +1265,23 @@ function createRelayService(context: McpContext) { } const hosted = await participant(as); if (!hosted) throw new RelayToolError("No hosted participant is bound to this MCP session. Send a message with send_relay_message to auto-join, or call join_relay first."); - await touchPresence(hosted.token); + await touchPresence(hosted); // Every fallible read finishes before any acknowledgement, so a failed // enrichment leaves the deliveries pending for a retry. + const via = clientFor(hosted); + const dir = directory(hosted); const [messages, conversations] = await Promise.all([ - client.readHostedInbox(hosted.token), client.listConversations(hosted.token), + via.readHostedInbox(hosted.token), via.listConversations(hosted.token), ]); // Sender addresses come from one bounded lookup of the senders' names. const senders = [...new Set(messages.flatMap(message => message.sender ? [message.sender] : []))]; - const agents = senders.length ? (await client.findAgentsByNames(key, senders)).filter(isListedRelayAgent) : []; + const agents = senders.length ? (await dir.via.findAgentsByNames(dir.credential, senders)).filter(isListedRelayAgent) : []; const addresses = new Map(agents.map(agent => [agent.name, agent.address])); const channelNames = new Map(); if (messages.some(isChannelDelivery)) { - for (const row of (await client.authenticatedAgent(hosted.token)).channels) channelNames.set(row.id, row.name); + for (const row of (await via.authenticatedAgent(hosted.token)).channels) channelNames.set(row.id, row.name); if (messages.some(message => isChannelDelivery(message) && message.channel_id && !channelNames.has(message.channel_id))) { - for (const row of await client.listChannels(key)) channelNames.set(row.id, row.name); + for (const row of await dir.via.listChannels(dir.credential)) channelNames.set(row.id, row.name); } } const enriched = messages.map(message => { @@ -1010,7 +1303,7 @@ function createRelayService(context: McpContext) { // absent or not owned by this participant and stays an error. A retry of a // partly failed batch therefore resumes cleanly. const requested = [...new Set(acknowledge)]; - for (const id of requested) await client.acknowledgeDelivery(hosted.token, id); + for (const id of requested) await via.acknowledgeDelivery(hosted.token, id); const acknowledged = new Set(requested); return { name: hosted.name, messages: enriched.filter(message => !acknowledged.has(message.delivery_id)), acknowledged: requested, has_more: messages.length === 100 }; @@ -1022,16 +1315,20 @@ function createRelayService(context: McpContext) { await managedActorOnly(input.as, Boolean(input.as_person)); if (input.as_person) throw new RelayToolError(AS_PERSON_UNAVAILABLE); // The recipient is validated before any identity is joined, so an - // unknown recipient never leaves a participant behind. - const peer = await recipient(input.to, await context.members()); + // unknown recipient never leaves a participant behind. On a gate-only + // install it is resolved through relaygate as the sending identity, so + // it can only be an agent relaygate lets that identity see. + const people = await context.members(); + const early = gate ? null : await recipient(input.to, people); return hostedActor(input.as, async (identity) => { + const peer = early ?? await recipient(input.to, people, directory(identity)); if (identity.name === peer.name) throw new RelayToolError("Choose another agent as the recipient."); const responseIdempotencyKey = input.idempotency_key ?? serverIdempotencyKey; const idempotencyKey = `hosted-mcp:${userId}:${identity.name}:${responseIdempotencyKey}`; // Response metadata and reply_to are resolved before the write, so a // later read failure never hides a send Relaycast already accepted. const [fromAddress, conv] = await Promise.all([ - addressFor(identity.name), + addressFor(identity.name, false, directory(identity)), input.reply_to ? (async () => { const found = await conversation(identity.token, identity.name, peer.name, clientFor(identity)); // Look the parent up by its exclusive successor to verify old ids without paging. @@ -1096,7 +1393,7 @@ function createRelayService(context: McpContext) { async read(input: { agent: string; as?: string; before?: string; limit: number }) { // Names resolve within the actor's own DMs; only a machine address needs a lookup. - const peerName = input.agent.includes("@") ? (await explicitAgent(input.agent))?.name : input.agent; + const peerName = input.agent.includes("@") && !gate ? (await explicitAgent(input.agent))?.name : input.agent; if (!peerName) throw new RelayToolError("Unknown or stale machine address in this workspace."); await managedActorOnly(input.as); const hosted: Identity | null = managed ? await desktop() @@ -1104,31 +1401,28 @@ function createRelayService(context: McpContext) { ?? await participant(input.as, { allowMissing: factoryFallback(input.as) }) ?? (factoryFallback(input.as) ? await factoryActor(input.as) : null); if (!hosted) return { you: null, conversation_id: null, messages: [], earlier: null }; - const via = clientFor(hosted); - // relaygate does not proxy heartbeats; Desktop keeps its own presence. - if (via === client) await touchPresence(hosted.token); - const conv = await conversation(hosted.token, hosted.name, peerName, via); - if (!conv) return { you: hosted.name, conversation_id: null, messages: [], earlier: null }; - const page = await via.listMessages(hosted.token, conv.id, { before: input.before, limit: input.limit }); - const messages = []; - // The DM listing omits thread_id; enrich only authorized ids, five at a time. - for (let index = 0; index < page.messages.length; index += 5) { - messages.push(...await Promise.all(page.messages.slice(index, index + 5).map(async message => ({ - message_id: message.id, sender: message.sender, text: message.text, created_at: message.createdAt, - thread_id: await via.getMessageThreadId(hosted.token, message.id), mine: message.sender === hosted.name, - })))); + // Gate-only installs resolve a machine address as the reading identity, through relaygate when gated. + if (gate && input.agent.includes("@")) { + const resolved = (await explicitAgent(input.agent, directory(hosted)))?.name; + if (!resolved) throw new RelayToolError("Unknown or stale machine address in this workspace."); + return readConversation(hosted, resolved, input); } - return { you: hosted.name, conversation_id: conv.id, messages, - earlier: page.hasEarlier ? page.messages[0]?.id ?? null : null }; + return readConversation(hosted, peerName, input); }, async listChannels(input: ChannelInput) { let acted = false; - const [channels, mine] = await Promise.all([client.listChannels(key), channelActor(input, false, async (identity) => { + let actor: Identity | null = null; + const mine = await channelActor(input, false, async (identity) => { acted = true; + actor = identity; return { you: identity.name, linked: linkedKind(identity), ids: new Set((await clientFor(identity).authenticatedAgent(identity.token)).channels.map(row => row.id)) }; - }, "none")]); + }, "none"); + // Gate-only installs: a gated participant lists through relaygate; nobody lists without an identity. + if (gate && !actor) throw new RelayToolError(GATE_JOIN_FIRST); + const dir = directory(actor); + const channels = await dir.via.listChannels(dir.credential); const unlinked = !managed && !acted && !input.as && !input.hosted && !(sessionHash && await findParticipant(executor, workspaceId, userId, organizationId, { sessionHash })); return { you: mine?.you ?? null, linked: mine?.linked ?? null, @@ -1203,9 +1497,11 @@ function createRelayService(context: McpContext) { async readChannel(input: ChannelInput & { channel: string; before?: string; limit: number }) { const channel = normalizeChannelName(input.channel); return (await channelActor(input, false, async (identity) => { - // History is read with the workspace key, so membership is checked here. + // History is read with the workspace key (a gated participant: through relaygate, which checks read + // itself), so membership is checked here. if (!await membership(identity, channel)) notSubscribed(channel); - const page = await client.listChannelMessages(key, channel, { before: input.before, limit: input.limit }); + const dir = directory(identity); + const page = await dir.via.listChannelMessages(dir.credential, channel, { before: input.before, limit: input.limit }); return { you: identity.name, channel, messages: page.messages.map(message => ({ message_id: message.id, sender: message.sender, text: message.text, created_at: message.createdAt, thread_id: message.threadId, reply_count: message.replyCount, mine: message.sender === identity.name })), diff --git a/src/messaging/relaycast.ts b/src/messaging/relaycast.ts index 662b03e0..f0df8d22 100644 --- a/src/messaging/relaycast.ts +++ b/src/messaging/relaycast.ts @@ -613,6 +613,49 @@ export function createRelaycastClient(input: { call("DELETE", `/v1/subscriptions/${encodeURIComponent(id)}`, workspaceKey, undefined, undefined, true)); }, + /** + * relaygate only: enrols one hosted participant with a single-use hosted + * credential (`sh_ht_`) at POST /v1/register. The answer is not wrapped in + * { ok, data }. agentId is relaygate's agent id; the rg_ token is valid + * only at relaygate. + */ + async registerAtGate(credential: string, name: string): Promise<{ agentId: string; gid: number | null; token: string; expiresAt: string | null; userId: string | null }> { + const data = record(await labeled("gate_register", () => call("POST", "/v1/register", credential, { name }))); + const agentId = text(data?.agent_id); + const token = text(data?.token); + if (!agentId || !token?.startsWith("rg_")) throw new RelaycastCallError(502, "", true); + return { agentId, gid: typeof data?.gid === "number" ? data.gid : null, token, + expiresAt: text(data?.expires_at), userId: text(data?.user_id) }; + }, + + /** + * relaygate only: merges metadata into the token's own agent card + * (PATCH /v1/agent; relaygate keeps its own `relaygate` stamp). + */ + async mergeOwnAgentMetadata(token: string, metadata: Record): Promise { + await labeled("gate_update_agent", () => call("PATCH", "/v1/agent", token, { metadata })); + }, + + /** + * relaygate only: renews an unexpired rg_ token of a launched or hosted + * agent (POST /v1/token/refresh); the presented token is revoked. + */ + async refreshGateToken(token: string): Promise { + const data = record(await labeled("gate_refresh", () => call("POST", "/v1/token/refresh", token, {}))); + const renewed = text(data?.token); + if (!renewed?.startsWith("rg_")) throw new RelaycastCallError(502, "", true); + return renewed; + }, + + /** + * relaygate only: deletes the token's own agent upstream (DELETE + * /v1/agent). relaygate revokes its tokens; the name stays reserved for + * its owner. An agent already gone upstream (404) is fine. + */ + async releaseOwnAgent(token: string): Promise { + await labeled("gate_release_agent", () => call("DELETE", "/v1/agent", token, undefined, undefined, true)); + }, + /** * relaygate only (a client bound to relaygate's origin): the agent an rg_ * token controls, from GET /v1/whoami. The body is not wrapped in diff --git a/test/gate-only-hosted-participants.test.ts b/test/gate-only-hosted-participants.test.ts new file mode 100644 index 00000000..d0ab6ea3 --- /dev/null +++ b/test/gate-only-hosted-participants.test.ts @@ -0,0 +1,302 @@ +import assert from "node:assert/strict"; +import { createHash, randomBytes, randomUUID } from "node:crypto"; +import test, { type TestContext } from "node:test"; +import { Client } from "@modelcontextprotocol/sdk/client/index.js"; +import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"; +import { decryptSecret, encryptSecret } from "../src/crypto.js"; +import { launcherName } from "../src/mcp/relay-participants.js"; +/** The keyring test/support/copilot-desktop.ts configures. */ +const KEYRING = { active: { id: "test-key", key: Buffer.alloc(32, 7) } }; +import { copilotDesktopSetup, MCP_PATH, type DesktopGate } from "./support/copilot-desktop.js"; + +// Gate-only installs (relaygatePublicUrl set): every hosted MCP participant +// enrols at relaygate with a one-time hosted credential (sh_ht_) that +// relaygate introspects with relay-control, holds only an rg_ token, and +// makes every call, reads included, through relaygate. relay-control never +// talks to Relaycast for a hosted participant's traffic, neither with its +// own Relaycast token nor with the workspace key. + +const GATE = "https://gate.selfhosted.test"; +const INTROSPECT_SECRET = "gate-introspection-secret-".repeat(2); +const AUD = "https://history.selfhosted.test"; +const WORKSPACE_KEY = "rk_primary"; +const ownerHash = (userId: string) => createHash("sha256").update(userId).digest("hex"); + +type CallResult = Awaited>; +function structured(result: CallResult): Record { + assert.notEqual(result.isError, true, JSON.stringify(result.content)); + return result.structuredContent as Record; +} +function toolError(result: CallResult): string { + assert.equal(result.isError, true, JSON.stringify(result.content)); + return (result.content as Array<{ text: string }>)[0]!.text; +} + +/** + * A fake relaygate in front of the Relaycast world. POST /v1/register takes a + * hosted credential and introspects it with relay-control (the real + * endpoint), refusing clients its policy has no rule for; every other call is + * authorized by an rg_ token and forwarded upstream as that agent (or, for the + * directory and self-administration routes relaygate answers itself, with the + * workspace key). Requests that bypass relaygate are recorded. + */ +const plain = (headers: Headers) => { + const out: Record = {}; + headers.forEach((value, name) => { out[name] = value; }); + return out; +}; + +function relaygate(control: { origin: () => string }) { + const state = { + /** Hosted clients the policy has a rule for. */ + allowed: new Set(["mcp"]), + tokens: new Map(), + agents: new Map(), + /** `METHOD path` of every request relaygate received. */ + seen: [] as string[], + /** Introspection answers relaygate got. */ + introspected: [] as Array>, + /** Hosted credentials presented to /v1/register. */ + credentials: [] as string[], + /** `METHOD path bearer-kind` of every call that went to Relaycast without relaygate. */ + direct: [] as string[], + }; + const revoke = (name: string) => { + for (const [token, owner] of state.tokens) if (owner === name) state.tokens.delete(token); + }; + const issue = (name: string) => { + revoke(name); + const token = `rg_${randomBytes(24).toString("base64url")}`; + state.tokens.set(token, name); + return token; + }; + const gate: DesktopGate = { + url: GATE, + fetch: (relaycast, world) => (async (input: string | URL | Request, init?: RequestInit) => { + const url = new URL(String(input instanceof Request ? input.url : input)); + const method = init?.method ?? "GET"; + const headers = new Headers(init?.headers); + const bearer = (headers.get("authorization") ?? "").replace(/^Bearer /, ""); + if (url.origin !== GATE) { + const kind = bearer === WORKSPACE_KEY ? "workspace-key" : bearer.startsWith("rg_") ? "rg" : "agent-token"; + state.direct.push(`${method} ${url.pathname} ${kind}`); + return relaycast(input, init); + } + const json = (status: number, body: unknown) => new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } }); + state.seen.push(`${method} ${url.pathname}`); + const upstream = (path: string, token: string, override?: { method?: string; body?: unknown }) => + relaycast(`http://relaycast.internal${path}`, { + ...init, method: override?.method ?? method, + headers: { ...plain(headers), authorization: `Bearer ${token}`, "content-type": "application/json" }, + ...(override?.body !== undefined ? { body: JSON.stringify(override.body) } : {}), + }); + if (method === "POST" && url.pathname === "/v1/register") { + if (!bearer.startsWith("sh_ht_")) return json(401, { error: "relaygate_unauthenticated" }); + state.credentials.push(bearer); + const answer = await (await fetch(`${control.origin()}/internal/v1/auth/introspect`, { + method: "POST", headers: { authorization: `Bearer ${INTROSPECT_SECRET}`, "content-type": "application/json" }, + body: JSON.stringify({ token: bearer, aud: AUD }), + })).json() as Record; + state.introspected.push(answer); + if (answer.active !== true || answer.principal_type !== "relay_hosted") return json(401, { error: "relaygate_unauthenticated" }); + if (!state.allowed.has(answer.client)) { + return json(403, { error: "relaygate_denied", detail: `no controlPrincipals rule allows hosted ${answer.client} participants` }); + } + const { name } = JSON.parse(String(init!.body)) as { name: string }; + if (name !== answer.agent_name) return json(403, { error: "relaygate_name_scope" }); + let agent = state.agents.get(name); + if (agent && agent.userId !== answer.sub) return json(409, { error: "relaygate_name_taken" }); + if (!agent) { + agent = { agentId: `rga_${randomUUID()}`, userId: answer.sub }; + state.agents.set(name, agent); + } + // relaygate registers the agent upstream with its own workspace key, or takes the name over. + const existing = world.agents.get(name); + if (existing) existing.metadata = { ...existing.metadata, relaygate: { agent_id: agent.agentId } }; + else world.addAgent(name, { relaygate: { agent_id: agent.agentId } }); + return json(200, { agent_id: agent.agentId, gid: 22, token: issue(name), expires_at: new Date(Date.now() + 86_400_000).toISOString(), user_id: answer.sub }); + } + const name = state.tokens.get(bearer); + if (!name) return json(401, { error: "relaygate_unauthenticated" }); + const enrolled = state.agents.get(name)!; + if (method === "GET" && url.pathname === "/v1/whoami") return json(200, { agent_id: enrolled.agentId, name, user_id: enrolled.userId }); + if (method === "PATCH" && url.pathname === "/v1/agent") { + return upstream(`/v1/agents/${encodeURIComponent(name)}`, WORKSPACE_KEY, { method: "PATCH" }); + } + if (method === "DELETE" && url.pathname === "/v1/agent") { + const own = world.agents.get(name); + revoke(name); + if (!own) return json(404, { ok: false, error: { code: "agent_not_found" } }); + return upstream("/v1/agents/release-exact", WORKSPACE_KEY, { method: "POST", body: { name, expected_agent_id: own.id, delete_agent: true } }); + } + // Directory reads relaygate answers with the workspace key (filtered by policy in the real gate). + if (method === "GET" && (url.pathname === "/v1/agents" || url.pathname.startsWith("/v1/agents/") || url.pathname === "/v1/channels" || + /^\/v1\/channels\/[^/]+\/messages$/.test(url.pathname))) { + return upstream(`${url.pathname}${url.search}`, WORKSPACE_KEY); + } + const own = world.agents.get(name); + if (!own) return json(401, { error: "relaygate_unauthenticated" }); + return upstream(`${url.pathname}${url.search}`, own.token); + }) as typeof fetch, + }; + return { gate, state, issue }; +} + +async function gateHosted(t: TestContext) { + let origin = ""; + const { gate, state, issue } = relaygate({ origin: () => origin }); + const env = await copilotDesktopSetup(t, {}, gate); + origin = env.origin; + // relaygate introspects hosted credentials here. + env.config.introspectSecret = INTROSPECT_SECRET; + const peer = env.world.addAgent("peer"); + const accessToken = await env.deviceLogin(); + const connect = async () => { + const client = new Client({ name: "gate-hosted-test", version: "1.0.0" }); + await client.connect(new StreamableHTTPClientTransport(new URL(`${env.origin}${MCP_PATH}`), + { requestInit: { headers: { authorization: `Bearer ${accessToken}` } } })); + t.after(() => client.close()); + return client; + }; + const rows = async () => (await env.database.query<{ agent_name: string; agent_remote_id: string; token_ciphertext: string; relaygate_agent_id: string | null }>( + "SELECT agent_name, agent_remote_id, token_ciphertext, relaygate_agent_id FROM hosted_relay_participants ORDER BY agent_name")).rows + .map(row => ({ ...row, token: decryptSecret(row.token_ciphertext, KEYRING) })); + /** Direct Relaycast calls made since `mark`. */ + const directSince = (mark: number) => state.direct.slice(mark); + return { env, state, issue, peer, connect, rows, directSince }; +} + +test("on a gate-only install a hosted participant enrols at relaygate and every call it makes goes through relaygate", async (t) => { + const { env, state, peer, connect, rows, directSince } = await gateHosted(t); + const client = await connect(); + const mark = state.direct.length; + + const joined = structured(await client.callTool({ name: "join_relay", arguments: { name: "notes-agent" } })); + assert.equal(joined.name, "notes-agent"); + // One single-use hosted credential, introspected as relay_hosted for the owner, the exact name and the client. + assert.equal(state.credentials.length, 1); + assert.match(state.credentials[0]!, /^sh_ht_/); + assert.deepEqual({ ...state.introspected[0], iat: 0, exp: 0, token_id: "" }, { + active: true, sub: env.ownerId, email: null, principal_type: "relay_hosted", agent_name: "notes-agent", client: "mcp", + machine_id: null, org: env.orgId, workspace: env.workspaceId, scopes: ["relay:hosted:enrol"], aud: AUD, iat: 0, exp: 0, token_id: "", + }); + // Burned: presenting it again is inactive. + const again = await (await fetch(`${env.origin}/internal/v1/auth/introspect`, { + method: "POST", headers: { authorization: `Bearer ${INTROSPECT_SECRET}`, "content-type": "application/json" }, + body: JSON.stringify({ token: state.credentials[0], aud: AUD }), + })).json() as Record; + assert.deepEqual(again, { active: false, reason: "revoked" }); + + const [row] = await rows(); + assert.match(row!.token, /^rg_/, "the participant holds only a relaygate token"); + assert.equal(row!.relaygate_agent_id, state.agents.get("notes-agent")!.agentId); + assert.equal(row!.agent_remote_id, env.world.agents.get("notes-agent")!.id, "agent_remote_id stays the upstream Relaycast id"); + // Owner metadata was merged upstream through relaygate (OAuth teardown and the roster read it). + assert.deepEqual( + (({ source, owner_hash, cloud_workspace_id, kind, hosted_client }) => ({ source, owner_hash, cloud_workspace_id, kind, hosted_client }))( + env.world.agents.get("notes-agent")!.metadata as Record), + { source: "cloud-hosted-mcp", owner_hash: ownerHash(env.ownerId), cloud_workspace_id: env.workspaceId, kind: "hosted", hosted_client: "mcp" }); + + const sent = structured(await client.callTool({ name: "send_relay_message", arguments: { to: "peer", text: "hello through the gate" } })); + assert.equal(sent.from, "notes-agent"); + env.world.sendAs("peer", "notes-agent", "hello back"); + const inbox = structured(await client.callTool({ name: "check_relay_inbox", arguments: {} })); + assert.deepEqual(inbox.messages.map((message: any) => message.text), ["hello back"]); + const read = structured(await client.callTool({ name: "read_relay_conversation", arguments: { agent: "peer" } })); + assert.deepEqual(read.messages.map((message: any) => message.text).sort(), ["hello back", "hello through the gate"]); + const listed = structured(await client.callTool({ name: "list_relay_agents", arguments: { status: "all" } })); + assert.ok(listed.agents.some((agent: any) => agent.name === peer.name)); + structured(await client.callTool({ name: "subscribe_relay_channel", arguments: { channel: "team", create: true } })); + structured(await client.callTool({ name: "post_relay_channel", arguments: { channel: "team", text: "posted through the gate" } })); + const history = structured(await client.callTool({ name: "read_relay_channel", arguments: { channel: "team" } })); + assert.deepEqual(history.messages.map((message: any) => message.text), ["posted through the gate"]); + structured(await client.callTool({ name: "list_relay_channels", arguments: {} })); + structured(await client.callTool({ name: "relay_status", arguments: {} })); + structured(await client.callTool({ name: "set_relay_agent_card", arguments: { description: "Takes notes", skills: [] } })); + + // Nothing above reached Relaycast without relaygate: no participant token, no workspace key. + assert.deepEqual(directSince(mark), []); + for (const expected of ["POST /v1/register", "GET /v1/whoami", "POST /v1/dm", "GET /v1/deliveries", "GET /v1/agents", "POST /v1/channels", + "GET /v1/channels", "PATCH /v1/agent"]) { + assert.ok(state.seen.includes(expected), `${expected} went through relaygate: ${JSON.stringify(state.seen)}`); + } +}); + +test("on a gate-only install relaygate fails closed: without a hosted rule nothing joins, and the error names the rule to add", async (t) => { + const { env, state, connect, rows, directSince } = await gateHosted(t); + state.allowed.clear(); + const client = await connect(); + const mark = state.direct.length; + const refused = toolError(await client.callTool({ name: "join_relay", arguments: { name: "notes-agent" } })); + assert.match(refused, /does not allow hosted mcp participants/); + assert.match(refused, /"kinds": \["hosted"\]/); + assert.match(refused, /"clients": \["mcp"\]/); + assert.deepEqual(await rows(), []); + // Sending auto-joins, and is refused the same way; no agent was registered in Relaycast directly. + assert.match(toolError(await client.callTool({ name: "send_relay_message", arguments: { to: "peer", text: "x" } })), /does not allow hosted mcp/); + assert.equal(env.world.agents.has("notes-agent"), false); + assert.deepEqual(directSince(mark), []); +}); + +test("on a gate-only install a hosted participant can no longer reach Relaycast directly, and a pre-gate participant is re-enrolled through relaygate", async (t) => { + const { env, state, connect, rows, directSince } = await gateHosted(t); + // A participant registered in Relaycast directly, before this install enforced relaygate for hosted participants. + const legacy = env.world.addAgent("old-notes", { + source: "cloud-hosted-mcp", cloud_workspace_id: env.workspaceId, owner_hash: ownerHash(env.ownerId), kind: "hosted" }); + const relayWorkspace = (await env.database.query<{ relaycast_workspace_id: string }>( + "SELECT relaycast_workspace_id FROM workspaces WHERE id = $1", [env.workspaceId])).rows[0]!.relaycast_workspace_id; + await env.database.query( + `INSERT INTO hosted_relay_participants (id, workspace_id, user_id, relaycast_workspace_id, session_hash, agent_name, agent_remote_id, token_ciphertext) + VALUES ($1, $2, $3, $4, NULL, $5, $6, $7)`, + [randomUUID(), env.workspaceId, env.ownerId, relayWorkspace, legacy.name, legacy.id, encryptSecret(legacy.token, KEYRING.active)]); + const client = await connect(); + + const mark = state.direct.length; + const sent = structured(await client.callTool({ name: "send_relay_message", arguments: { to: "peer", text: "migrated", as: "old-notes" } })); + assert.equal(sent.from, "old-notes"); + const [row] = await rows(); + assert.match(row!.token, /^rg_/, "the Relaycast token was replaced by a relaygate token"); + assert.equal(row!.agent_remote_id, legacy.id, "the same upstream agent: pins and launches keep working"); + assert.equal(row!.relaygate_agent_id, state.agents.get("old-notes")!.agentId); + // The only direct call was the one-time ownership check of the legacy agent, with the workspace key; the + // participant's own Relaycast token was never used. + assert.deepEqual(directSince(mark), ["GET /v1/agents/old-notes workspace-key"]); + + // The old Relaycast token is useless to relay-control from now on: everything goes through relaygate. + const before = state.direct.length; + structured(await client.callTool({ name: "relay_status", arguments: { as: "old-notes" } })); + structured(await client.callTool({ name: "check_relay_inbox", arguments: { as: "old-notes" } })); + assert.deepEqual(directSince(before), []); +}); + +test("on a gate-only install a rejected relaygate token is renewed by enrolling again, and leave releases through relaygate", async (t) => { + const { env, state, issue, connect, rows } = await gateHosted(t); + const client = await connect(); + structured(await client.callTool({ name: "join_relay", arguments: { name: "notes-agent" } })); + const first = (await rows())[0]!; + // relaygate tokens expire after 24 hours: the stored one stops working. + issue("notes-agent"); + const status = structured(await client.callTool({ name: "relay_status", arguments: {} })); + assert.equal(status.name, "notes-agent"); + const renewed = (await rows())[0]!; + assert.notEqual(renewed.token, first.token); + assert.equal(renewed.relaygate_agent_id, first.relaygate_agent_id, "the same relaygate agent"); + assert.equal(state.credentials.length, 2); + + const mark = state.direct.length; + const left = structured(await client.callTool({ name: "leave_relay", arguments: {} })); + assert.equal(left.already_left, false); + assert.deepEqual(await rows(), []); + assert.equal(env.world.agents.has("notes-agent"), false, "released upstream"); + assert.ok(state.seen.includes("DELETE /v1/agent")); + assert.deepEqual(state.direct.slice(mark), [], "released through relaygate, not with the workspace key"); +}); + +test("on a gate-only install directory reads need a relay identity first, and the launcher name is not a messaging participant", async (t) => { + const { env, connect, rows } = await gateHosted(t); + const client = await connect(); + assert.match(toolError(await client.callTool({ name: "list_relay_agents", arguments: { status: "all" } })), /Call join_relay first/); + assert.match(toolError(await client.callTool({ name: "list_relay_channels", arguments: {} })), /Call join_relay first/); + assert.match(toolError(await client.callTool({ name: "join_relay", arguments: { name: launcherName(env.ownerId) } })), /reserved/); + assert.deepEqual(await rows(), []); +}); diff --git a/test/grok-routines.test.ts b/test/grok-routines.test.ts index dc583b00..766a6169 100644 --- a/test/grok-routines.test.ts +++ b/test/grok-routines.test.ts @@ -266,3 +266,42 @@ test("routine credentials refuse alternate origins, redirects, URL credentials, assert.throws(() => parseGrokRoutineCredentials(URL, "secret-invalid"), error => error instanceof Error && !error.message.includes("secret-invalid")); assert.deepEqual(parseGrokRoutineCredentials(URL, `Authorization: Bearer ${KEY}`), { url: URL, key: KEY }); }); + +test("gate-only: a routine reads a gated participant through relaygate and renews its rg_ token at half-life", async t => { + const f = await fixture(t, "/mcp"); + await f.tool("connect_grok_bot_routine"); await f.save(); + const agent = f.world.agents.get("fake-grok")!; + // The participant as a gate-only install stores it: relaygate's agent id and an rg_ token, written 13 hours ago. + const tokens = new Map([["rg_old", agent.token]]); + const refreshed: string[] = []; + await f.database.query(`UPDATE hosted_relay_participants SET relaygate_agent_id='rga_fake', token_ciphertext=$1, + updated_at=now() - interval '13 hours' WHERE agent_remote_id=$2`, [encryptSecret("rg_old", KEYRING.active), agent.id]); + const gate = createRelaycastClient({ internalOrigin: "https://gate.example.test", fetchImpl: async (input, init) => { + const url = new globalThis.URL(input instanceof Request ? input.url : String(input)); + const bearer = (new Headers(init?.headers).get("authorization") ?? "").replace(/^Bearer /, ""); + const upstream = tokens.get(bearer); + if (!upstream) return Response.json({ error: "relaygate_unauthenticated" }, { status: 401 }); + if (url.pathname === "/v1/token/refresh") { + tokens.delete(bearer); refreshed.push(bearer); + tokens.set("rg_new", upstream); + return Response.json({ token: "rg_new", expires_at: new Date(Date.now() + 86_400_000).toISOString() }); + } + const result = await f.world.handle(init?.method ?? "GET", url.pathname, url.searchParams, upstream, null, null); + if (url.pathname === "/v1/agent" && result?.status === 200) (result.body as any).data.workspace_id = "fake-workspace"; + return Response.json(result?.body ?? { ok: false }, { status: result?.status ?? 404 }); + } }); + // Relaycast refuses rg_ tokens: anything sent there directly would fail the wake. + const routines = new GrokRoutines({ ...f.routines.options, gate }); + await f.message(); + await routines.tick(); + assert.deepEqual(refreshed, ["rg_old"]); + const row = (await f.database.query<{ token_ciphertext: string; fresh: boolean }>( + "SELECT token_ciphertext, updated_at > now() - interval '1 minute' AS fresh FROM hosted_relay_participants WHERE agent_remote_id=$1", [agent.id])).rows[0]!; + assert.equal(decryptSecret(row.token_ciphertext, KEYRING), "rg_new"); + assert.equal(row.fresh, true); + assert.equal(f.calls.length, 1, "the pending inbox, read through relaygate, woke the routine"); + // Without a relaygate client a gated participant is never read with Relaycast. + await f.message(); f.advance(); + await new GrokRoutines(f.routines.options).tick(); + assert.equal(f.calls.length, 1); +}); From a0643308fba8a8fb1f44448d0b42642378769380 Mon Sep 17 00:00:00 2001 From: khaliqgant Date: Tue, 17 Nov 2026 11:59:20 -0800 Subject: [PATCH 2/5] chore(verify): schema manifest for migration 0078 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 --- .../cloud-import-verify/schema-manifest.json | 25 +++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) diff --git a/scripts/cloud-import-verify/schema-manifest.json b/scripts/cloud-import-verify/schema-manifest.json index 9dabf672..891b2ee6 100644 --- a/scripts/cloud-import-verify/schema-manifest.json +++ b/scripts/cloud-import-verify/schema-manifest.json @@ -79,7 +79,8 @@ {"name":"0074_enrollment_key_uses.sql","sha256":"7deea130fead087f8522a5d5862aeacf7476eab5787f62796087978f3fa72036"}, {"name":"0075_token_session_client_telemetry.sql","sha256":"6c9ce658602d7a5eebad9b7c13a2e2ddca6c1a22f6a3e4ee0be8b3357fafd479"}, {"name":"0076_events_shim_agent_links.sql","sha256":"3f1441ca8cd33613c585c4c725de0a8e88df457e070ec6fb1756214aa7c3e821"}, - {"name":"0077_events_shim_sender_release_attempts.sql","sha256":"f586a6324c3af8d81e00cae9fea161772673a0d7ea55c865dfb00bafa3d901cd"} + {"name":"0077_events_shim_sender_release_attempts.sql","sha256":"f586a6324c3af8d81e00cae9fea161772673a0d7ea55c865dfb00bafa3d901cd"}, + {"name":"0078_hosted_relay_gate.sql","sha256":"e4e6e37fed462f13df43bcd521436120064f1e89e4048168bb055200eb1db9ed"} ], "required":[ {"kind":"column","name":"public.admin_audit_events.action","definition":{"collation":"pg_catalog.default","default":null,"generated":"","identity":"","not_null":true,"position":6,"type":"text"}}, @@ -577,6 +578,7 @@ {"kind":"column","name":"public.hosted_relay_participants.created_at","definition":{"collation":null,"default":"now()","generated":"","identity":"","not_null":true,"position":9,"type":"timestamp with time zone"}}, {"kind":"column","name":"public.hosted_relay_participants.id","definition":{"collation":null,"default":null,"generated":"","identity":"","not_null":true,"position":1,"type":"uuid"}}, {"kind":"column","name":"public.hosted_relay_participants.relaycast_workspace_id","definition":{"collation":"pg_catalog.default","default":null,"generated":"","identity":"","not_null":true,"position":4,"type":"text"}}, + {"kind":"column","name":"public.hosted_relay_participants.relaygate_agent_id","definition":{"collation":"pg_catalog.default","default":null,"generated":"","identity":"","not_null":false,"position":11,"type":"text"}}, {"kind":"column","name":"public.hosted_relay_participants.session_hash","definition":{"collation":"pg_catalog.default","default":null,"generated":"","identity":"","not_null":false,"position":5,"type":"text"}}, {"kind":"column","name":"public.hosted_relay_participants.token_ciphertext","definition":{"collation":"pg_catalog.default","default":null,"generated":"","identity":"","not_null":true,"position":8,"type":"text"}}, {"kind":"column","name":"public.hosted_relay_participants.updated_at","definition":{"collation":null,"default":"now()","generated":"","identity":"","not_null":true,"position":10,"type":"timestamp with time zone"}}, @@ -800,6 +802,16 @@ {"kind":"column","name":"public.person_revocations.relaycast_workspace_id","definition":{"collation":"pg_catalog.default","default":null,"generated":"","identity":"","not_null":true,"position":4,"type":"text"}}, {"kind":"column","name":"public.person_revocations.user_id","definition":{"collation":null,"default":null,"generated":"","identity":"","not_null":true,"position":3,"type":"uuid"}}, {"kind":"column","name":"public.person_revocations.workspace_id","definition":{"collation":null,"default":null,"generated":"","identity":"","not_null":true,"position":2,"type":"uuid"}}, + {"kind":"column","name":"public.relay_hosted_credentials.agent_name","definition":{"collation":"pg_catalog.default","default":null,"generated":"","identity":"","not_null":true,"position":5,"type":"text"}}, + {"kind":"column","name":"public.relay_hosted_credentials.client","definition":{"collation":"pg_catalog.default","default":null,"generated":"","identity":"","not_null":true,"position":6,"type":"text"}}, + {"kind":"column","name":"public.relay_hosted_credentials.created_at","definition":{"collation":null,"default":"now()","generated":"","identity":"","not_null":true,"position":10,"type":"timestamp with time zone"}}, + {"kind":"column","name":"public.relay_hosted_credentials.expires_at","definition":{"collation":null,"default":null,"generated":"","identity":"","not_null":true,"position":8,"type":"timestamp with time zone"}}, + {"kind":"column","name":"public.relay_hosted_credentials.id","definition":{"collation":null,"default":null,"generated":"","identity":"","not_null":true,"position":1,"type":"uuid"}}, + {"kind":"column","name":"public.relay_hosted_credentials.organization_id","definition":{"collation":null,"default":null,"generated":"","identity":"","not_null":true,"position":3,"type":"uuid"}}, + {"kind":"column","name":"public.relay_hosted_credentials.redeemed_at","definition":{"collation":null,"default":null,"generated":"","identity":"","not_null":false,"position":9,"type":"timestamp with time zone"}}, + {"kind":"column","name":"public.relay_hosted_credentials.token_hash","definition":{"collation":"pg_catalog.default","default":null,"generated":"","identity":"","not_null":true,"position":7,"type":"text"}}, + {"kind":"column","name":"public.relay_hosted_credentials.user_id","definition":{"collation":null,"default":null,"generated":"","identity":"","not_null":true,"position":4,"type":"uuid"}}, + {"kind":"column","name":"public.relay_hosted_credentials.workspace_id","definition":{"collation":null,"default":null,"generated":"","identity":"","not_null":true,"position":2,"type":"uuid"}}, {"kind":"column","name":"public.relay_launch_credentials.agent_name","definition":{"collation":"pg_catalog.default","default":null,"generated":"","identity":"","not_null":true,"position":7,"type":"text"}}, {"kind":"column","name":"public.relay_launch_credentials.created_at","definition":{"collation":null,"default":"now()","generated":"","identity":"","not_null":true,"position":12,"type":"timestamp with time zone"}}, {"kind":"column","name":"public.relay_launch_credentials.expires_at","definition":{"collation":null,"default":null,"generated":"","identity":"","not_null":true,"position":10,"type":"timestamp with time zone"}}, @@ -1550,6 +1562,11 @@ {"kind":"constraint","name":"public.person_revocations.person_revocations_user_id_fkey","definition":{"deferrable":false,"deferred":false,"definition":"FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE","no_inherit":true,"triggers":[{"deferrable":false,"deferred":false,"enabled":"O","function":"pg_catalog.RI_FKey_check_ins","table":"public.person_revocations","type":5},{"deferrable":false,"deferred":false,"enabled":"O","function":"pg_catalog.RI_FKey_check_upd","table":"public.person_revocations","type":17},{"deferrable":false,"deferred":false,"enabled":"O","function":"pg_catalog.RI_FKey_cascade_del","table":"public.users","type":9},{"deferrable":false,"deferred":false,"enabled":"O","function":"pg_catalog.RI_FKey_noaction_upd","table":"public.users","type":17}],"type":"f","validated":true}}, {"kind":"constraint","name":"public.person_revocations.person_revocations_workspace_id_fkey","definition":{"deferrable":false,"deferred":false,"definition":"FOREIGN KEY (workspace_id) REFERENCES workspaces(id) ON DELETE CASCADE","no_inherit":true,"triggers":[{"deferrable":false,"deferred":false,"enabled":"O","function":"pg_catalog.RI_FKey_check_ins","table":"public.person_revocations","type":5},{"deferrable":false,"deferred":false,"enabled":"O","function":"pg_catalog.RI_FKey_check_upd","table":"public.person_revocations","type":17},{"deferrable":false,"deferred":false,"enabled":"O","function":"pg_catalog.RI_FKey_cascade_del","table":"public.workspaces","type":9},{"deferrable":false,"deferred":false,"enabled":"O","function":"pg_catalog.RI_FKey_noaction_upd","table":"public.workspaces","type":17}],"type":"f","validated":true}}, {"kind":"constraint","name":"public.person_revocations.person_revocations_workspace_id_user_id_agent_remo_key","definition":{"deferrable":false,"deferred":false,"definition":"UNIQUE (workspace_id, user_id, agent_remote_id)","no_inherit":true,"triggers":[],"type":"u","validated":true}}, + {"kind":"constraint","name":"public.relay_hosted_credentials.relay_hosted_credentials_organization_id_fkey","definition":{"deferrable":false,"deferred":false,"definition":"FOREIGN KEY (organization_id) REFERENCES organizations(id) ON DELETE CASCADE","no_inherit":true,"triggers":[{"deferrable":false,"deferred":false,"enabled":"O","function":"pg_catalog.RI_FKey_cascade_del","table":"public.organizations","type":9},{"deferrable":false,"deferred":false,"enabled":"O","function":"pg_catalog.RI_FKey_noaction_upd","table":"public.organizations","type":17},{"deferrable":false,"deferred":false,"enabled":"O","function":"pg_catalog.RI_FKey_check_ins","table":"public.relay_hosted_credentials","type":5},{"deferrable":false,"deferred":false,"enabled":"O","function":"pg_catalog.RI_FKey_check_upd","table":"public.relay_hosted_credentials","type":17}],"type":"f","validated":true}}, + {"kind":"constraint","name":"public.relay_hosted_credentials.relay_hosted_credentials_pkey","definition":{"deferrable":false,"deferred":false,"definition":"PRIMARY KEY (id)","no_inherit":true,"triggers":[],"type":"p","validated":true}}, + {"kind":"constraint","name":"public.relay_hosted_credentials.relay_hosted_credentials_token_hash_key","definition":{"deferrable":false,"deferred":false,"definition":"UNIQUE (token_hash)","no_inherit":true,"triggers":[],"type":"u","validated":true}}, + {"kind":"constraint","name":"public.relay_hosted_credentials.relay_hosted_credentials_user_id_fkey","definition":{"deferrable":false,"deferred":false,"definition":"FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE","no_inherit":true,"triggers":[{"deferrable":false,"deferred":false,"enabled":"O","function":"pg_catalog.RI_FKey_check_ins","table":"public.relay_hosted_credentials","type":5},{"deferrable":false,"deferred":false,"enabled":"O","function":"pg_catalog.RI_FKey_check_upd","table":"public.relay_hosted_credentials","type":17},{"deferrable":false,"deferred":false,"enabled":"O","function":"pg_catalog.RI_FKey_cascade_del","table":"public.users","type":9},{"deferrable":false,"deferred":false,"enabled":"O","function":"pg_catalog.RI_FKey_noaction_upd","table":"public.users","type":17}],"type":"f","validated":true}}, + {"kind":"constraint","name":"public.relay_hosted_credentials.relay_hosted_credentials_workspace_id_fkey","definition":{"deferrable":false,"deferred":false,"definition":"FOREIGN KEY (workspace_id) REFERENCES workspaces(id) ON DELETE CASCADE","no_inherit":true,"triggers":[{"deferrable":false,"deferred":false,"enabled":"O","function":"pg_catalog.RI_FKey_check_ins","table":"public.relay_hosted_credentials","type":5},{"deferrable":false,"deferred":false,"enabled":"O","function":"pg_catalog.RI_FKey_check_upd","table":"public.relay_hosted_credentials","type":17},{"deferrable":false,"deferred":false,"enabled":"O","function":"pg_catalog.RI_FKey_cascade_del","table":"public.workspaces","type":9},{"deferrable":false,"deferred":false,"enabled":"O","function":"pg_catalog.RI_FKey_noaction_upd","table":"public.workspaces","type":17}],"type":"f","validated":true}}, {"kind":"constraint","name":"public.relay_launch_credentials.relay_launch_credentials_organization_id_fkey","definition":{"deferrable":false,"deferred":false,"definition":"FOREIGN KEY (organization_id) REFERENCES organizations(id) ON DELETE CASCADE","no_inherit":true,"triggers":[{"deferrable":false,"deferred":false,"enabled":"O","function":"pg_catalog.RI_FKey_cascade_del","table":"public.organizations","type":9},{"deferrable":false,"deferred":false,"enabled":"O","function":"pg_catalog.RI_FKey_noaction_upd","table":"public.organizations","type":17},{"deferrable":false,"deferred":false,"enabled":"O","function":"pg_catalog.RI_FKey_check_ins","table":"public.relay_launch_credentials","type":5},{"deferrable":false,"deferred":false,"enabled":"O","function":"pg_catalog.RI_FKey_check_upd","table":"public.relay_launch_credentials","type":17}],"type":"f","validated":true}}, {"kind":"constraint","name":"public.relay_launch_credentials.relay_launch_credentials_pkey","definition":{"deferrable":false,"deferred":false,"definition":"PRIMARY KEY (id)","no_inherit":true,"triggers":[],"type":"p","validated":true}}, {"kind":"constraint","name":"public.relay_launch_credentials.relay_launch_credentials_spawn_id_fkey","definition":{"deferrable":false,"deferred":false,"definition":"FOREIGN KEY (spawn_id) REFERENCES relay_spawns(id) ON DELETE CASCADE","no_inherit":true,"triggers":[{"deferrable":false,"deferred":false,"enabled":"O","function":"pg_catalog.RI_FKey_check_ins","table":"public.relay_launch_credentials","type":5},{"deferrable":false,"deferred":false,"enabled":"O","function":"pg_catalog.RI_FKey_check_upd","table":"public.relay_launch_credentials","type":17},{"deferrable":false,"deferred":false,"enabled":"O","function":"pg_catalog.RI_FKey_cascade_del","table":"public.relay_spawns","type":9},{"deferrable":false,"deferred":false,"enabled":"O","function":"pg_catalog.RI_FKey_noaction_upd","table":"public.relay_spawns","type":17}],"type":"f","validated":true}}, @@ -1902,6 +1919,9 @@ {"kind":"index","name":"public.person_messages.person_messages_pkey","definition":{"definition":"CREATE UNIQUE INDEX person_messages_pkey ON public.person_messages USING btree (id)","live":true,"nulls_not_distinct":false,"primary":true,"ready":true,"unique":true,"valid":true}}, {"kind":"index","name":"public.person_revocations.person_revocations_pkey","definition":{"definition":"CREATE UNIQUE INDEX person_revocations_pkey ON public.person_revocations USING btree (id)","live":true,"nulls_not_distinct":false,"primary":true,"ready":true,"unique":true,"valid":true}}, {"kind":"index","name":"public.person_revocations.person_revocations_workspace_id_user_id_agent_remo_key","definition":{"definition":"CREATE UNIQUE INDEX person_revocations_workspace_id_user_id_agent_remo_key ON public.person_revocations USING btree (workspace_id, user_id, agent_remote_id)","live":true,"nulls_not_distinct":false,"primary":false,"ready":true,"unique":true,"valid":true}}, + {"kind":"index","name":"public.relay_hosted_credentials.relay_hosted_credentials_pkey","definition":{"definition":"CREATE UNIQUE INDEX relay_hosted_credentials_pkey ON public.relay_hosted_credentials USING btree (id)","live":true,"nulls_not_distinct":false,"primary":true,"ready":true,"unique":true,"valid":true}}, + {"kind":"index","name":"public.relay_hosted_credentials.relay_hosted_credentials_token_hash_key","definition":{"definition":"CREATE UNIQUE INDEX relay_hosted_credentials_token_hash_key ON public.relay_hosted_credentials USING btree (token_hash)","live":true,"nulls_not_distinct":false,"primary":false,"ready":true,"unique":true,"valid":true}}, + {"kind":"index","name":"public.relay_hosted_credentials.relay_hosted_credentials_workspace","definition":{"definition":"CREATE INDEX relay_hosted_credentials_workspace ON public.relay_hosted_credentials USING btree (workspace_id, created_at)","live":true,"nulls_not_distinct":false,"primary":false,"ready":true,"unique":false,"valid":true}}, {"kind":"index","name":"public.relay_launch_credentials.relay_launch_credentials_pkey","definition":{"definition":"CREATE UNIQUE INDEX relay_launch_credentials_pkey ON public.relay_launch_credentials USING btree (id)","live":true,"nulls_not_distinct":false,"primary":true,"ready":true,"unique":true,"valid":true}}, {"kind":"index","name":"public.relay_launch_credentials.relay_launch_credentials_spawn_id_key","definition":{"definition":"CREATE UNIQUE INDEX relay_launch_credentials_spawn_id_key ON public.relay_launch_credentials USING btree (spawn_id)","live":true,"nulls_not_distinct":false,"primary":false,"ready":true,"unique":true,"valid":true}}, {"kind":"index","name":"public.relay_launch_credentials.relay_launch_credentials_token_hash_key","definition":{"definition":"CREATE UNIQUE INDEX relay_launch_credentials_token_hash_key ON public.relay_launch_credentials USING btree (token_hash)","live":true,"nulls_not_distinct":false,"primary":false,"ready":true,"unique":true,"valid":true}}, @@ -2065,6 +2085,7 @@ {"kind":"table","name":"public.person_identities","definition":{"force_row_security":false,"kind":"r","row_security":false}}, {"kind":"table","name":"public.person_messages","definition":{"force_row_security":false,"kind":"r","row_security":false}}, {"kind":"table","name":"public.person_revocations","definition":{"force_row_security":false,"kind":"r","row_security":false}}, + {"kind":"table","name":"public.relay_hosted_credentials","definition":{"force_row_security":false,"kind":"r","row_security":false}}, {"kind":"table","name":"public.relay_launch_credentials","definition":{"force_row_security":false,"kind":"r","row_security":false}}, {"kind":"table","name":"public.relay_node_credentials","definition":{"force_row_security":false,"kind":"r","row_security":false}}, {"kind":"table","name":"public.relay_spawns","definition":{"force_row_security":false,"kind":"r","row_security":false}}, @@ -2108,5 +2129,5 @@ "optional":{ }, - "sha256":"1f22e78a1802ad28aec003e5a7fa244effa7093f7dcb8c1d5b992c18dfcfd177" + "sha256":"916331cb32a94e8abe384be468915a614fab34231d8faeefcb3e1d3081dc85bf" } From 20d542d8e9940f184e09575a316908e5fde775f0 Mon Sep 17 00:00:00 2001 From: layered-control-agent-host Date: Thu, 19 Nov 2026 11:33:10 +0000 Subject: [PATCH 3/5] fix(mcp): check hosted name ownership and per-client admission at relaygate 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 --- CHANGELOG.md | 15 ++- docs/identity.md | 44 ++++++- migrations/0079_hosted_relay_gate.sql | 7 ++ src/mcp/grok-routines.ts | 108 +++++++++++++--- src/mcp/hosted-gate.ts | 16 ++- src/mcp/oauth/connector-kind.ts | 15 +++ src/mcp/relay-participants.ts | 137 ++++++++++++++++----- src/messaging/relaycast.ts | 5 +- test/gate-only-hosted-participants.test.ts | 107 ++++++++++++++-- test/grok-routines.test.ts | 82 +++++++++++- test/mcp-oauth-connector-kind.test.ts | 22 +++- 11 files changed, 488 insertions(+), 70 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f5888f50..81656fe8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -21,8 +21,19 @@ assigned at release. 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. See - docs/identity.md, "Hosted participants on gate-only installs". + 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: a registration whose redirect URIs name two different + providers 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. See docs/identity.md, "Hosted participants on gate-only + installs". - Added: MCP `get_session_summary` can read recorded short or long summaries of the requested kind and return validated optional provenance. It enforces 320/16000 Unicode code-point bounds, preserves empty/unsupported responses, diff --git a/docs/identity.md b/docs/identity.md index 6a86bb49..175e9a07 100644 --- a/docs/identity.md +++ b/docs/identity.md @@ -1568,8 +1568,21 @@ Relaycast agent token for its traffic: 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 connector kind (`chatgpt`, `grok-bot`, - `muse`, `cursor-cloud`) from its registered OAuth redirect URIs, else `mcp`. + here. The client is the connection's admission kind, from its registered + OAuth redirect URIs: `chatgpt`, `grok-bot`, `muse` or `cursor-cloud` when + every URI that names a provider names the same one, else `mcp`. A + registration whose redirect URIs name two different providers enrols as + `mcp`, so it never matches a rule written for either provider. 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. - **Introspection.** Checked and burned like a launch credential. The active answer is `{active: true, sub: , email: null, principal_type: "relay_hosted", agent_name, client, machine_id: null, org, workspace, @@ -1590,6 +1603,17 @@ Relaycast agent token for its traffic: `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 @@ -1597,9 +1621,19 @@ Relaycast agent token for its traffic: 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 relaygate agent back. Grok Bot routines - renew a participant's token with relaygate's `POST /v1/token/refresh` once - it is 12 hours old. + 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, diff --git a/migrations/0079_hosted_relay_gate.sql b/migrations/0079_hosted_relay_gate.sql index fbc15182..cc71af08 100644 --- a/migrations/0079_hosted_relay_gate.sql +++ b/migrations/0079_hosted_relay_gate.sql @@ -30,3 +30,10 @@ CREATE INDEX IF NOT EXISTS relay_hosted_credentials_workspace ON relay_hosted_cr -- 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 '{}'; diff --git a/src/mcp/grok-routines.ts b/src/mcp/grok-routines.ts index 83dc917c..e2786ff7 100644 --- a/src/mcp/grok-routines.ts +++ b/src/mcp/grok-routines.ts @@ -2,10 +2,11 @@ import { randomBytes } from "node:crypto"; import { decryptSecret, encryptSecret, hashSecret, type EncryptionKeyring } from "../crypto.js"; import type { Database, SqlExecutor } from "../database.js"; import { page } from "../identity/pages.js"; -import type { RelaycastClient } from "../messaging/relaycast.js"; +import { RelaycastCallError, type RelaycastClient } from "../messaging/relaycast.js"; import { isBindingOwnedIdentity } from "../messaging/binding-identities.js"; import { lockOrganization, lockUser, type TenancyMode } from "../tenancy.js"; -import { connectorKind } from "./oauth/connector-kind.js"; +import { admissionConnectorKind } from "./oauth/connector-kind.js"; +import { enrolHostedAtGate, type GateEnrolment } from "./hosted-gate.js"; import type { McpConsentPrincipal } from "./oauth/consent.js"; import { GrokRoutineError, grokInboxPrompt, parseGrokRoutineCredentials } from "./grok-routine.js"; import { ownerHash, HOSTED_SOURCE } from "./relay-participants.js"; @@ -16,6 +17,8 @@ type Owner = Pick Response.json(value, { status, headers: { "cache-control": "no-store" } }); const escape = (value: string) => value.replaceAll("&", "&").replaceAll("<", "<").replaceAll(">", ">") @@ -24,6 +27,8 @@ const escape = (value: string) => value.replaceAll("&", "&").replaceAll("<", /** One encrypted routine per grant. User -> organization -> grant locks fence every delivery against revocation. */ /** A gated participant's rg_ token (24 h at relaygate) is renewed once it is this old. */ const GATE_TOKEN_REFRESH_AFTER_MS = 12 * 3_600_000; +/** How long one scan holds a routine while its participant enrols again at relaygate, so another scan does not race it. */ +const GATE_RECOVERY_LEASE_MS = 60_000; export class GrokRoutines { constructor(readonly options: { database: Database; keyring: EncryptionKeyring; client: RelaycastClient; @@ -49,7 +54,7 @@ export class GrokRoutines { FOR UPDATE OF g`, [id, owner.userId, owner.organizationId, owner.workspaceId, [this.options.publicOrigin + "/mcp", this.options.publicOrigin + "/cloud/api/v1/mcp/shared-sessions"], this.options.tenancyMode, this.now()])).rows[0]; - if (!row || connectorKind({ clientName: row.client_name, redirectUris: row.redirect_uris }) !== "grok-bot") { + if (!row || admissionConnectorKind({ clientName: row.client_name, redirectUris: row.redirect_uris }) !== "grok-bot") { throw new GrokRoutineError("This Grok Bot connection is no longer available. Reconnect it in this workspace."); } return row; @@ -130,25 +135,25 @@ form.addEventListener('submit',e=>{e.preventDefault();change('POST');});document JOIN mcp_oauth_grants g ON g.id=r.grant_id WHERE r.next_attempt_at<=$1 ORDER BY r.next_attempt_at LIMIT 20`, [this.now()]); for (const candidate of candidates.rows) { if (signal?.aborted) break; - await this.options.database.transaction(async tx => { + const owner: Owner = { userId: candidate.user_id, organizationId: candidate.organization_id, workspaceId: candidate.workspace_id }; + const recovery = await this.options.database.transaction(async (tx): Promise => { let grant: Grant; - try { grant = await this.grant(tx, candidate.grant_id, { - userId: candidate.user_id, organizationId: candidate.organization_id, workspaceId: candidate.workspace_id, - }); } catch (error) { + try { grant = await this.grant(tx, candidate.grant_id, owner); } catch (error) { if (!(error instanceof GrokRoutineError)) throw error; await tx.query("DELETE FROM grok_bot_routines WHERE grant_id=$1", [candidate.grant_id]); - return; + return null; } const routine = (await tx.query("SELECT * FROM grok_bot_routines WHERE grant_id=$1 AND next_attempt_at<=$2 FOR UPDATE", [grant.id, this.now()])).rows[0]; - if (!routine) return; + if (!routine) return null; try { // One budget bounds all remote reads, response bodies and the wake // while the revocation fence is held. stop() aborts the same requests. const deadline = AbortSignal.timeout(this.options.requestTimeoutMs ?? 5_000); const requestSignal = signal ? AbortSignal.any([signal, deadline]) : deadline; const participant = (await tx.query<{ id: string; token_ciphertext: string; relaycast_workspace_id: string; - relaygate_agent_id: string | null; stale: boolean }>(`SELECT p.id,p.token_ciphertext,p.relaycast_workspace_id,p.relaygate_agent_id, + relaygate_agent_id: string | null; agent_name: string; admitted_clients: string[]; stale: boolean }>( + `SELECT p.id,p.token_ciphertext,p.relaycast_workspace_id,p.relaygate_agent_id,p.agent_name,p.admitted_clients, p.updated_at < $5 AS stale FROM hosted_relay_participants p JOIN workspaces w ON w.id=p.workspace_id AND w.organization_id=$4 WHERE p.workspace_id=$1 AND p.user_id=$2 AND p.agent_remote_id=$3 @@ -161,13 +166,29 @@ form.addEventListener('submit',e=>{e.preventDefault();change('POST');});document if (gated && !this.options.gate) throw new Error("identity_unavailable"); const via = gated ? this.options.gate! : this.options.client; let token = decryptSecret(participant.token_ciphertext, this.options.keyring); - if (gated && participant.stale) { - // rg_ tokens last 24 hours; a routine may poll an idle participant for longer, so renew it at half-life. - token = await via.refreshGateToken(token); - await tx.query("UPDATE hosted_relay_participants SET token_ciphertext=$2, updated_at=now() WHERE id=$1", - [participant.id, encryptSecret(token, this.options.keyring.active)]); + // relaygate enrolled this participant for other hosted clients only, or rejects its token (it lapsed + // while the routine was idle): enrol it again as Grok Bot once this transaction ends (recover). + const recover = async (rejected: boolean): Promise => { + await tx.query("UPDATE grok_bot_routines SET next_attempt_at=$2,updated_at=$3 WHERE grant_id=$1", + [grant.id, new Date(this.now().getTime() + GATE_RECOVERY_LEASE_MS), this.now()]); + return { participantId: participant.id, tokenCiphertext: participant.token_ciphertext, relaygateAgentId: participant.relaygate_agent_id!, + agentName: participant.agent_name, + admittedClients: rejected ? ["grok-bot"] : [...new Set([...(participant.admitted_clients ?? []), "grok-bot"])] }; + }; + if (gated && !(participant.admitted_clients ?? []).includes("grok-bot")) return await recover(false); + let remote: Awaited>; + try { + if (gated && participant.stale) { + // rg_ tokens last 24 hours; a routine may poll an idle participant for longer, so renew it at half-life. + token = await via.refreshGateToken(token, requestSignal); + await tx.query("UPDATE hosted_relay_participants SET token_ciphertext=$2, updated_at=now() WHERE id=$1", + [participant.id, encryptSecret(token, this.options.keyring.active)]); + } + remote = await via.authenticatedAgent(token, requestSignal); + } catch (error) { + if (gated && error instanceof RelaycastCallError && error.status === 401) return await recover(true); + throw error; } - const remote = await via.authenticatedAgent(token, requestSignal); if (remote.id !== grant.agent_remote_id || remote.workspaceId !== participant.relaycast_workspace_id || remote.status === "released" || isBindingOwnedIdentity(remote.metadata) || remote.metadata.source !== HOSTED_SOURCE || remote.metadata.owner_hash !== ownerHash(candidate.user_id) || @@ -190,14 +211,63 @@ form.addEventListener('submit',e=>{e.preventDefault();change('POST');});document next_attempt_at=$3,updated_at=$4,last_delivered_at=CASE WHEN $5 THEN $4 ELSE last_delivered_at END WHERE grant_id=$1`, [grant.id, ids, new Date(this.now().getTime() + 5_000), this.now(), fresh.length > 0]); } catch { - // Neither provider error bodies nor URLs/keys are ever stored or logged. - await tx.query(`UPDATE grok_bot_routines SET failures=failures+1,last_error='delivery_unavailable',next_attempt_at=$2,updated_at=$3 - WHERE grant_id=$1`, [grant.id, new Date(this.now().getTime() + Math.min(300_000, 5_000 * 2 ** Math.min(routine.failures + 1, 6))), this.now()]); + await this.failed(tx, grant.id, routine.failures); } + return null; }); + if (recovery) await this.recover(owner, candidate.grant_id, recovery); } } + /** Neither provider error bodies nor URLs/keys are ever stored or logged. */ + private async failed(tx: SqlExecutor, grantId: string, failures: number): Promise { + await tx.query(`UPDATE grok_bot_routines SET failures=failures+1,last_error='delivery_unavailable',next_attempt_at=$2,updated_at=$3 + WHERE grant_id=$1`, [grantId, new Date(this.now().getTime() + Math.min(300_000, 5_000 * 2 ** Math.min(failures + 1, 6))), this.now()]); + } + + /** + * Enrols a gated participant again at relaygate as Grok Bot (the kind its + * grant is admitted as), with no transaction open: relaygate introspects + * the hosted credential with this service. The new token is adopted, under + * the same user, organization, grant and routine locks as a delivery, only + * if relaygate answered with the stored relaygate agent and the grant's + * Relaycast agent and the row is unchanged. Anything else, including a + * relaygate refusal, records a delivery failure; nothing is released. + */ + private async recover(owner: Owner, grantId: string, recovery: Recovery): Promise { + let enrolled: GateEnrolment | null = null; + if (this.options.gate) { + try { + enrolled = await enrolHostedAtGate({ database: this.options.database, gate: this.options.gate }, { + workspaceId: owner.workspaceId, organizationId: owner.organizationId, userId: owner.userId, + agentName: recovery.agentName, client: "grok-bot" }); + } catch { + enrolled = null; + } + } + await this.options.database.transaction(async tx => { + let grant: Grant; + try { grant = await this.grant(tx, grantId, owner); } catch (error) { + if (error instanceof GrokRoutineError) return; + throw error; + } + const routine = (await tx.query("SELECT * FROM grok_bot_routines WHERE grant_id=$1 FOR UPDATE", [grant.id])).rows[0]; + if (!routine) return; + const current = (await tx.query<{ token_ciphertext: string; relaygate_agent_id: string | null; agent_remote_id: string }>( + `SELECT token_ciphertext,relaygate_agent_id,agent_remote_id FROM hosted_relay_participants + WHERE id=$1 AND workspace_id=$2 AND user_id=$3 FOR UPDATE`, [recovery.participantId, owner.workspaceId, owner.userId])).rows[0]; + if (enrolled && current && current.token_ciphertext === recovery.tokenCiphertext + && current.relaygate_agent_id === recovery.relaygateAgentId && enrolled.relaygateAgentId === recovery.relaygateAgentId + && current.agent_remote_id === grant.agent_remote_id && enrolled.relaycastAgentId === current.agent_remote_id) { + await tx.query("UPDATE hosted_relay_participants SET token_ciphertext=$2,admitted_clients=$3::text[],updated_at=now() WHERE id=$1", + [recovery.participantId, encryptSecret(enrolled.token, this.options.keyring.active), recovery.admittedClients]); + await tx.query("UPDATE grok_bot_routines SET next_attempt_at=$2,updated_at=$2 WHERE grant_id=$1", [grant.id, this.now()]); + return; + } + await this.failed(tx, grant.id, routine.failures); + }); + } + private timer?: ReturnType; private active?: Promise; private abort?: AbortController; diff --git a/src/mcp/hosted-gate.ts b/src/mcp/hosted-gate.ts index a60ef92b..09247cca 100644 --- a/src/mcp/hosted-gate.ts +++ b/src/mcp/hosted-gate.ts @@ -51,8 +51,21 @@ export type GateEnrolment = { name: string; /** An rg_ token; only relaygate accepts it. */ token: string; + /** + * The upstream agent's metadata as relaygate left it. relaygate stamps a + * name it registers itself with `relaygate.agent_id`; a name it took over + * keeps the metadata it had. + */ + metadata: Record; }; +/** Whether relaygate registered the upstream agent itself for this enrolment, so it carries no other owner's metadata. */ +export function freshAtGate(enrolled: Pick): boolean { + const stamp = enrolled.metadata.relaygate; + return enrolled.metadata.source === undefined && typeof stamp === "object" && stamp !== null + && (stamp as Record).agent_id === enrolled.relaygateAgentId; +} + /** * Enrols (or, for the same owner and name, recovers) one hosted participant * at relaygate. Throws HostedGateRefused with an operator-facing reason when @@ -76,5 +89,6 @@ export async function enrolHostedAtGate( } const upstream = await deps.gate.authenticatedAgent(enrolled.token); if (upstream.name !== input.agentName) throw new HostedGateRefused("relaygate enrolled a different agent name. Nothing was joined."); - return { relaygateAgentId: enrolled.agentId, relaycastAgentId: upstream.id, name: upstream.name, token: enrolled.token }; + return { relaygateAgentId: enrolled.agentId, relaycastAgentId: upstream.id, name: upstream.name, token: enrolled.token, + metadata: upstream.metadata }; } diff --git a/src/mcp/oauth/connector-kind.ts b/src/mcp/oauth/connector-kind.ts index 4ab1be1d..aadcb61d 100644 --- a/src/mcp/oauth/connector-kind.ts +++ b/src/mcp/oauth/connector-kind.ts @@ -39,3 +39,18 @@ export function connectorKind(client: { clientName: string | null; redirectUris: if (hosts.some(({ scheme, host }) => scheme === "https" && (under(host, "muse.ai") || under(host, "agent.meta.ai")))) return "muse"; return "mcp"; } + +/** + * The kind an OAuth grant is admitted as: relaygate enrolment of its hosted + * participant and Grok routines. Unlike connectorKind's display precedence, a + * registration naming two different providers is no provider at all ("mcp"), + * so a client cannot claim one provider's admission by adding its callback + * beside another's. Callbacks that classify as no provider (cursor://, + * localhost) are neutral: Grok Bot registers them beside its cursor.com + * callback. + */ +export function admissionConnectorKind(client: { clientName: string | null; redirectUris: string[] }): ConnectorKind { + const kinds = new Set(client.redirectUris.map((uri) => connectorKind({ clientName: client.clientName, redirectUris: [uri] }))); + kinds.delete("mcp"); + return kinds.size === 1 ? [...kinds][0]! : "mcp"; +} diff --git a/src/mcp/relay-participants.ts b/src/mcp/relay-participants.ts index 05fa2af2..0393d79c 100644 --- a/src/mcp/relay-participants.ts +++ b/src/mcp/relay-participants.ts @@ -12,11 +12,11 @@ import type { McpContext, McpMember } from "./context.js"; import { isListedRelayAgent, rosterAgent } from "./team-activity.js"; import { buildAgentCard, cardMetadata, cardSummary, recipientCard, type SetCardInput } from "./relay-agent-cards.js"; import { McpOAuthAccessRefused, McpOAuthActorRefused } from "./oauth/admission.js"; -import { connectorKind } from "./oauth/connector-kind.js"; +import { admissionConnectorKind, connectorKind } from "./oauth/connector-kind.js"; import { LAUNCH_ROLE_REFUSAL } from "./catalog.js"; import { RECEIPT_GUIDANCE } from "../messaging/delivery-status.js"; import { MCP_OAUTH_RETIRING_MESSAGE, McpOAuthAgentRetiring, retiringIdentity } from "./oauth/retirement.js"; -import { enrolHostedAtGate, HostedGateRefused, type GateEnrolment } from "./hosted-gate.js"; +import { enrolHostedAtGate, freshAtGate, HostedGateRefused, type GateEnrolment } from "./hosted-gate.js"; import type { RelayHostedClient } from "./relay-hosted-credentials.js"; /** @@ -135,11 +135,17 @@ export type ParticipantRow = { * (gate-only installs; the token is then an rg_ token), else null. */ relaygateAgentId: string | null; + /** + * Gate-only installs: the hosted clients (connector kinds) relaygate + * enrolled this participant for. Another kind enrols at relaygate before + * it may use the participant, so relaygate's policy decides it too. + */ + admittedClients: string[]; }; type Selector = { name: string } | { sessionHash: string } | { agentRemoteId: string }; -const COLUMNS = `p.id, p.workspace_id, p.user_id, p.relaycast_workspace_id, p.session_hash, p.agent_name, p.agent_remote_id, p.token_ciphertext, p.relaygate_agent_id`; +const COLUMNS = `p.id, p.workspace_id, p.user_id, p.relaycast_workspace_id, p.session_hash, p.agent_name, p.agent_remote_id, p.token_ciphertext, p.relaygate_agent_id, p.admitted_clients`; function rowFrom(row: Record): ParticipantRow { return { @@ -152,6 +158,7 @@ function rowFrom(row: Record): ParticipantRow { agentRemoteId: String(row.agent_remote_id), tokenCiphertext: String(row.token_ciphertext), relaygateAgentId: typeof row.relaygate_agent_id === "string" ? row.relaygate_agent_id : null, + admittedClients: Array.isArray(row.admitted_clients) ? row.admitted_clients.map(String) : [], }; } @@ -171,22 +178,24 @@ async function findParticipant(executor: SqlExecutor, workspaceId: string, userI async function insertParticipant(executor: SqlExecutor, row: Omit): Promise { await executor.query( `INSERT INTO hosted_relay_participants - (id, workspace_id, user_id, relaycast_workspace_id, session_hash, agent_name, agent_remote_id, token_ciphertext, relaygate_agent_id) - VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)`, + (id, workspace_id, user_id, relaycast_workspace_id, session_hash, agent_name, agent_remote_id, token_ciphertext, relaygate_agent_id, + admitted_clients) + VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10::text[])`, [randomUUID(), row.workspaceId, row.userId, row.relayWorkspaceId, row.sessionHash, row.agentName, row.agentRemoteId, row.tokenCiphertext, - row.relaygateAgentId], + row.relaygateAgentId, row.admittedClients], ); } async function updateParticipant(executor: SqlExecutor, id: string, - fields: { sessionHash?: string; agentName?: string; tokenCiphertext?: string; relaygateAgentId?: string }) { + fields: { sessionHash?: string; agentName?: string; tokenCiphertext?: string; relaygateAgentId?: string; admittedClients?: string[] }) { await executor.query( `UPDATE hosted_relay_participants SET session_hash = COALESCE($2, session_hash), agent_name = COALESCE($3, agent_name), token_ciphertext = COALESCE($4, token_ciphertext), relaygate_agent_id = COALESCE($5, relaygate_agent_id), - updated_at = now() + admitted_clients = COALESCE($6::text[], admitted_clients), updated_at = now() WHERE id = $1`, - [id, fields.sessionHash ?? null, fields.agentName ?? null, fields.tokenCiphertext ?? null, fields.relaygateAgentId ?? null], + [id, fields.sessionHash ?? null, fields.agentName ?? null, fields.tokenCiphertext ?? null, fields.relaygateAgentId ?? null, + fields.admittedClients ?? null], ); } @@ -303,9 +312,12 @@ const CARD_IDENTITY_CHANGED = "Your relay identity is no longer available or cha /** joinLocked found nothing to join on a gate-only install: enrol at relaygate outside the lock, then retry. */ const NEEDS_GATE_ENROLMENT = Symbol("needs-gate-enrolment"); const NO_PARTICIPANT_MESSAGE = "No hosted participant with that name is owned by you in this workspace."; +const NAME_TAKEN = "That relay name is already taken. Choose another name."; /** Gate-only installs: reads go through relaygate as the caller's own relay identity, so one is needed first. */ export const GATE_JOIN_FIRST = "This install routes relay traffic through relaygate, which answers as your relay identity. Call join_relay first (or join_relay with desktop_address to use your Agent Relay Desktop identity), then retry."; export const GATE_RENEW_FAILED = "relaygate did not accept this hosted participant's token, and renewing it failed. Retry; if it keeps failing, ask your operator whether relaygate's policy still allows hosted participants."; +const gateNotAdmitted = (client: RelayHostedClient) => + `This hosted participant is not enrolled at relaygate for hosted ${client} clients. Retry; if it keeps failing, ask your operator whether relaygate's policy allows hosted ${client} participants.`; export const GATE_OAUTH_LAUNCH_REFUSED = "Launching agents from a hosted connector is not available on this install: relaygate does not proxy launches. Launch from Agent Relay Desktop or a native MCP session."; const rejectedToken = (name: string) => new RelayToolError( `The relay token for participant ${name} was rejected by Relaycast. Call join_relay with name=${name} to recover it, or leave_relay to remove it.`); @@ -442,14 +454,18 @@ function createRelayService(context: McpContext) { } } - /** The hosted MCP client relaygate's policy matches this caller's participants on. */ + /** + * The hosted MCP client relaygate's policy matches this caller's + * participants on: the grant's admission kind, so a registration naming two + * providers enrols as neither ("mcp"). Callers inside a transaction pass it. + */ let clientKind: Promise | undefined; - function hostedClient(): Promise { + function hostedClient(query: SqlExecutor = executor): Promise { clientKind ??= (async () => { if (!oauth) return "mcp" as const; - const row = (await executor.query<{ client_name: string | null; redirect_uris: string[] }>( + const row = (await query.query<{ client_name: string | null; redirect_uris: string[] }>( "SELECT client_name, redirect_uris FROM mcp_oauth_clients WHERE client_id = $1", [oauth.access.clientId])).rows[0]; - return row ? connectorKind({ clientName: row.client_name, redirectUris: row.redirect_uris ?? [] }) : "mcp" as const; + return row ? admissionConnectorKind({ clientName: row.client_name, redirectUris: row.redirect_uris ?? [] }) : "mcp" as const; })(); return clientKind; } @@ -496,9 +512,12 @@ function createRelayService(context: McpContext) { /** * Gate-only installs, before any owner-locked work: makes the selected row - * usable at relaygate. A gated row whose rg_ token relaygate rejects (it - * expires after 24 hours) enrols again, and the same owner gets the same - * relaygate agent back. A row registered in Relaycast directly before this + * usable at relaygate for this caller's hosted client. A gated row whose + * rg_ token relaygate rejects (it expires after 24 hours) enrols again, and + * the same owner gets the same relaygate agent back. A gated row relaygate + * has not admitted this hosted client for enrols again as it, so + * relaygate's policy decides that client too: a refusal leaves the row and + * its token as they were. A row registered in Relaycast directly before this * install enforced relaygate for hosted participants is enrolled through * relaygate once, after its upstream agent is confirmed as this owner's * with the workspace roster (a one-time control-plane check, never the @@ -512,29 +531,39 @@ function createRelayService(context: McpContext) { if (!gate) return; const row = await selectedRow(as); if (!row || row.relayWorkspaceId !== relayWorkspaceId || row.agentName === launcherName(userId)) return; - if (row.relaygateAgentId !== null && (await gateState(row, decryptSecret(row.tokenCiphertext, keyring))).state !== "rejected") return; - if (row.relaygateAgentId === null) { + const kind = await hostedClient(); + let rejected = true; + if (row.relaygateAgentId !== null) { + const state = (await gateState(row, decryptSecret(row.tokenCiphertext, keyring))).state; + if (state === "changed" || (state === "ok" && row.admittedClients.includes(kind))) return; + rejected = state === "rejected"; + } else { const upstream = await client.getRosterAgent(key, row.agentName); if (!upstream || upstream.status === "released" || upstream.id !== row.agentRemoteId || !ownsRemote(upstream)) return; } const enrolled = await enrolAtGate(row.agentName); - if (enrolled.relaycastAgentId !== row.agentRemoteId || - (row.relaygateAgentId !== null && enrolled.relaygateAgentId !== row.relaygateAgentId)) { - // The agent this row was is gone (relaygate enrolled a fresh one under the name): never adopt it. - await gate.releaseOwnAgent(enrolled.token).catch(() => {}); + if (enrolled.relaycastAgentId !== row.agentRemoteId) { + // The agent this row was is gone: never adopt another. Release only an agent relaygate registered itself for + // this enrolment; a name it took over is someone's live agent, and releasing it would delete that agent. + if (freshAtGate(enrolled)) await gate.releaseOwnAgent(enrolled.token).catch(() => {}); return; } + // The same upstream agent. relaygate may answer with a new relaygate agent for it (it re-created its own + // record); the row adopts that one with the token, as long as nothing changed the row meanwhile. + const admittedClients = rejected ? [kind] : [...new Set([...row.admittedClients, kind])]; await withOwnerLock(async (tx) => { const current = await findParticipant(tx, workspaceId, userId, organizationId, { agentRemoteId: row.agentRemoteId }); - if (!current || current.id !== row.id || current.tokenCiphertext !== row.tokenCiphertext) return; + if (!current || current.id !== row.id || current.tokenCiphertext !== row.tokenCiphertext + || current.relaygateAgentId !== row.relaygateAgentId) return; await updateParticipant(tx, row.id, { - tokenCiphertext: encryptSecret(enrolled.token, keyring.active), relaygateAgentId: enrolled.relaygateAgentId }); + tokenCiphertext: encryptSecret(enrolled.token, keyring.active), relaygateAgentId: enrolled.relaygateAgentId, admittedClients }); }); } /** * participant() on a gate-only install. Never enrols (refreshGated did, - * before the lock). A row relaygate does not accept is returned only to + * before the lock), and refuses a row relaygate has not admitted this + * caller's hosted client for. A row relaygate does not accept is returned only to * `allowRejected` callers, for cleanup: its upstream agent is then * released with the workspace key, as for any participant whose token no * one can use. @@ -548,10 +577,14 @@ function createRelayService(context: McpContext) { } let remote: RosterAgent | null = checked?.state === "ok" ? checked.remote : null; const usable = remote !== null; + if (usable) { + const kind = await hostedClient(query); + if (!row.admittedClients.includes(kind)) throw new RelayToolError(gateNotAdmitted(kind)); + } if (!usable && checked?.state !== "changed") { if (!allowRejected) throw new RelayToolError(GATE_RENEW_FAILED); const upstream = await client.getRosterAgent(key, row.agentName); - remote = upstream && upstream.id === row.agentRemoteId && upstream.status !== "released" ? upstream : null; + remote = upstream && upstream.id === row.agentRemoteId && upstream.status !== "released" && ownsRemote(upstream) ? upstream : null; } let name = row.agentName; if (usable && remote && remote.name !== row.agentName) { @@ -683,7 +716,7 @@ function createRelayService(context: McpContext) { return registerAtGate(tx, options.enrolled, boundSession); } const remote = await client.getAgent(key, name); - if (remote && !ownsRemote(remote)) throw new RelayToolError("That relay name is already taken. Choose another name."); + if (remote && !ownsRemote(remote)) throw new RelayToolError(NAME_TAKEN); // Recovering an owned agent binds it again; its release may be in flight. if (remote) await refuseRetiring(tx, remote.id, remote.name); // An owned agent without a row is an interrupted join: recover its token. @@ -699,7 +732,7 @@ function createRelayService(context: McpContext) { await insertParticipant(tx, { workspaceId, userId, relayWorkspaceId, sessionHash: boundSession, agentName: registered.name, agentRemoteId: registered.id, - tokenCiphertext: encryptSecret(registered.token, keyring.active), relaygateAgentId: null, + tokenCiphertext: encryptSecret(registered.token, keyring.active), relaygateAgentId: null, admittedClients: [], }); if (oauth) await oauth.pin(tx, { workspaceId, userId, agentName: registered.name, agentRemoteId: registered.id }); } catch (error) { @@ -717,9 +750,28 @@ function createRelayService(context: McpContext) { * Relaycast registration used to carry is merged through relaygate: OAuth * teardown and the roster read it. Ownership itself is decided by * relaygate's whoami, never by it. + * + * relaygate reserves a name for its first enroller only, and takes over an + * upstream agent of that name that it did not register. So the name is + * checked with the workspace roster first, as registerParticipant does: an + * agent another owner (or a binding) holds is refused before any credential + * is minted. 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 (that would + * delete the other owner's agent). */ async function prepareGateRegistration(name: string, objective: string): Promise { + const checked = await client.getRosterAgent(key, name); + const held = checked && checked.status !== "released" ? checked : null; + if (held && !ownsRemote(held)) throw new RelayToolError(NAME_TAKEN); + // An owned agent without a row is an interrupted join: relaygate enrols the same agent again. const enrolled = await enrolAtGate(name); + const ours = held ? enrolled.relaycastAgentId === held.id + : !isBindingOwnedIdentity(enrolled.metadata) && (ownsRemote(enrolled) || freshAtGate(enrolled)); + if (!ours) { + if (freshAtGate(enrolled)) await gate!.releaseOwnAgent(enrolled.token).catch(() => {}); + throw new RelayToolError(NAME_TAKEN); + } try { await gate!.mergeOwnAgentMetadata(enrolled.token, { source: HOSTED_SOURCE, cloud_workspace_id: workspaceId, owner_hash: owner, objective, @@ -742,6 +794,7 @@ function createRelayService(context: McpContext) { workspaceId, userId, relayWorkspaceId, sessionHash: boundSession, agentName: enrolled.name, agentRemoteId: enrolled.relaycastAgentId, tokenCiphertext: encryptSecret(enrolled.token, keyring.active), relaygateAgentId: enrolled.relaygateAgentId, + admittedClients: [await hostedClient(tx)], }); if (oauth) await oauth.pin(tx, { workspaceId, userId, agentName: enrolled.name, agentRemoteId: enrolled.relaycastAgentId }); } catch (error) { @@ -837,12 +890,13 @@ function createRelayService(context: McpContext) { if (bound && input.name && bound.name !== input.name && !oauth) { throw new RelayToolError("This MCP session is already joined. Leave before choosing another name."); } - const existing = bound ?? await participant(requestedName, { + let existing = bound ?? await participant(requestedName, { allowMissing: true, allowRejected: true, executor: tx, bind: Boolean(sessionHash) }); if (existing) { if (sessionHash && existing.row.sessionHash && existing.row.sessionHash !== sessionHash) { throw new RelayToolError("That participant is bound to another MCP session. Use as to act as it without changing its binding, or choose a new name."); } + if (gate && prepared && existing.row.agentName !== launcherName(userId)) existing = await settlePrepared(tx, existing, prepared); // A gated participant is renewed only at relaygate (refreshGated), never by a Relaycast takeover. if (gate && existing.row.agentName !== launcherName(userId) && !existing.tokenUsable) throw new RelayToolError(GATE_RENEW_FAILED); const token = existing.tokenUsable ? existing.token : await recoverToken(tx, existing); @@ -862,6 +916,31 @@ function createRelayService(context: McpContext) { already_joined: joined.alreadyJoined, recovered: joined.recovered, reply_guidance: HOSTED_REPLY_GUIDANCE, desktop_relay_guidance: DESKTOP_RELAY_GUIDANCE }; } + /** + * joinLocked found a participant after this join enrolled at relaygate: a + * concurrent join of this owner wrote it meanwhile. relaygate gives the same + * owner and name the same agent and revokes its earlier tokens, so the + * prepared enrolment is usually the row's own agent, whose stored token it + * just revoked: the row adopts the prepared token. Otherwise the prepared + * agent is released only when relaygate registered it itself and no row of + * this owner holds its name or upstream agent, since releasing deletes the + * upstream agent by name. In every other case nothing is done: the agent + * belongs to a row, and a rejected token renews at relaygate on the next + * call. Callers hold the owner lock. + */ + async function settlePrepared(tx: SqlExecutor, existing: Hosted, prepared: GateEnrolment): Promise { + if (existing.row.relaygateAgentId === prepared.relaygateAgentId && existing.row.agentRemoteId === prepared.relaycastAgentId) { + if (existing.tokenUsable) return existing; + await updateParticipant(tx, existing.row.id, { + tokenCiphertext: encryptSecret(prepared.token, keyring.active), admittedClients: [await hostedClient(tx)] }); + return { ...existing, token: prepared.token, gated: true, remotePresent: true, tokenUsable: true }; + } + const held = await findParticipant(tx, workspaceId, userId, organizationId, { name: prepared.name }) + ?? await findParticipant(tx, workspaceId, userId, organizationId, { agentRemoteId: prepared.relaycastAgentId }); + if (!held && freshAtGate(prepared)) await gate!.releaseOwnAgent(prepared.token).catch(() => {}); + return existing; + } + /** Callers hold the owner lock. */ async function unlinkDesktop(tx: SqlExecutor): Promise { if (sessionHash && !oauth) await unbindDesktopSession(tx, { workspaceId, userId, sessionHash }); diff --git a/src/messaging/relaycast.ts b/src/messaging/relaycast.ts index f0df8d22..769c5244 100644 --- a/src/messaging/relaycast.ts +++ b/src/messaging/relaycast.ts @@ -639,9 +639,10 @@ export function createRelaycastClient(input: { /** * relaygate only: renews an unexpired rg_ token of a launched or hosted * agent (POST /v1/token/refresh); the presented token is revoked. + * `signal` aborts the request (a caller's deadline or shutdown). */ - async refreshGateToken(token: string): Promise { - const data = record(await labeled("gate_refresh", () => call("POST", "/v1/token/refresh", token, {}))); + async refreshGateToken(token: string, signal?: AbortSignal): Promise { + const data = record(await labeled("gate_refresh", () => call("POST", "/v1/token/refresh", token, {}, undefined, false, signal))); const renewed = text(data?.token); if (!renewed?.startsWith("rg_")) throw new RelaycastCallError(502, "", true); return renewed; diff --git a/test/gate-only-hosted-participants.test.ts b/test/gate-only-hosted-participants.test.ts index d0ab6ea3..f587def5 100644 --- a/test/gate-only-hosted-participants.test.ts +++ b/test/gate-only-hosted-participants.test.ts @@ -110,10 +110,9 @@ function relaygate(control: { origin: () => string }) { agent = { agentId: `rga_${randomUUID()}`, userId: answer.sub }; state.agents.set(name, agent); } - // relaygate registers the agent upstream with its own workspace key, or takes the name over. - const existing = world.agents.get(name); - if (existing) existing.metadata = { ...existing.metadata, relaygate: { agent_id: agent.agentId } }; - else world.addAgent(name, { relaygate: { agent_id: agent.agentId } }); + // relaygate registers the agent upstream with its own workspace key, stamped with its agent id, or takes an + // existing upstream agent of that name over, leaving its metadata as it was. + if (!world.agents.has(name)) world.addAgent(name, { relaygate: { agent_id: agent.agentId } }); return json(200, { agent_id: agent.agentId, gid: 22, token: issue(name), expires_at: new Date(Date.now() + 86_400_000).toISOString(), user_id: answer.sub }); } const name = state.tokens.get(bearer); @@ -158,8 +157,9 @@ async function gateHosted(t: TestContext) { t.after(() => client.close()); return client; }; - const rows = async () => (await env.database.query<{ agent_name: string; agent_remote_id: string; token_ciphertext: string; relaygate_agent_id: string | null }>( - "SELECT agent_name, agent_remote_id, token_ciphertext, relaygate_agent_id FROM hosted_relay_participants ORDER BY agent_name")).rows + const rows = async () => (await env.database.query<{ agent_name: string; agent_remote_id: string; token_ciphertext: string; relaygate_agent_id: string | null; + admitted_clients: string[] }>( + "SELECT agent_name, agent_remote_id, token_ciphertext, relaygate_agent_id, admitted_clients FROM hosted_relay_participants ORDER BY agent_name")).rows .map(row => ({ ...row, token: decryptSecret(row.token_ciphertext, KEYRING) })); /** Direct Relaycast calls made since `mark`. */ const directSince = (mark: number) => state.direct.slice(mark); @@ -214,8 +214,10 @@ test("on a gate-only install a hosted participant enrols at relaygate and every structured(await client.callTool({ name: "relay_status", arguments: {} })); structured(await client.callTool({ name: "set_relay_agent_card", arguments: { description: "Takes notes", skills: [] } })); - // Nothing above reached Relaycast without relaygate: no participant token, no workspace key. - assert.deepEqual(directSince(mark), []); + assert.deepEqual((await rows())[0]!.admitted_clients, ["mcp"]); + // Nothing above reached Relaycast without relaygate: no participant token, and the workspace key only for the + // one control-plane check that the name is free before enrolling. + assert.deepEqual(directSince(mark), ["GET /v1/agents/notes-agent workspace-key"]); for (const expected of ["POST /v1/register", "GET /v1/whoami", "POST /v1/dm", "GET /v1/deliveries", "GET /v1/agents", "POST /v1/channels", "GET /v1/channels", "PATCH /v1/agent"]) { assert.ok(state.seen.includes(expected), `${expected} went through relaygate: ${JSON.stringify(state.seen)}`); @@ -235,7 +237,9 @@ test("on a gate-only install relaygate fails closed: without a hosted rule nothi // Sending auto-joins, and is refused the same way; no agent was registered in Relaycast directly. assert.match(toolError(await client.callTool({ name: "send_relay_message", arguments: { to: "peer", text: "x" } })), /does not allow hosted mcp/); assert.equal(env.world.agents.has("notes-agent"), false); - assert.deepEqual(directSince(mark), []); + // Only the control-plane name checks used the workspace key; no agent was registered with it. + assert.ok(directSince(mark).length > 0); + for (const call of directSince(mark)) assert.match(call, /^GET \/v1\/agents\/[^/]+ workspace-key$/); }); test("on a gate-only install a hosted participant can no longer reach Relaycast directly, and a pre-gate participant is re-enrolled through relaygate", async (t) => { @@ -300,3 +304,88 @@ test("on a gate-only install directory reads need a relay identity first, and th assert.match(toolError(await client.callTool({ name: "join_relay", arguments: { name: launcherName(env.ownerId) } })), /reserved/); assert.deepEqual(await rows(), []); }); + +test("on a gate-only install a name another owner holds is refused before any hosted credential is minted", async (t) => { + const { env, state, connect, rows } = await gateHosted(t); + const foreign = env.world.addAgent("notes-agent", { + source: "cloud-hosted-mcp", cloud_workspace_id: env.workspaceId, owner_hash: ownerHash("another-user"), kind: "hosted" }); + const client = await connect(); + assert.match(toolError(await client.callTool({ name: "join_relay", arguments: { name: "notes-agent" } })), /already taken/); + assert.equal(state.credentials.length, 0, "relaygate never saw an enrolment, so it never took the name over"); + assert.deepEqual(await rows(), []); + assert.equal(env.world.agents.get("notes-agent"), foreign, "the other owner's agent is untouched"); +}); + +test("on a gate-only install a binding-owned agent's name is refused before any hosted credential is minted", async (t) => { + const { env, state, connect, rows } = await gateHosted(t); + env.world.addAgent("notes-agent", { capy_binding_id: "binding-1" }); + const client = await connect(); + assert.match(toolError(await client.callTool({ name: "join_relay", arguments: { name: "notes-agent" } })), /already taken/); + assert.equal(state.credentials.length, 0); + assert.deepEqual(await rows(), []); + assert.ok(env.world.agents.has("notes-agent")); +}); + +test("on a gate-only install an interrupted join of the owner's own agent enrols that same agent through relaygate", async (t) => { + const { env, state, connect, rows } = await gateHosted(t); + const own = env.world.addAgent("notes-agent", { + source: "cloud-hosted-mcp", cloud_workspace_id: env.workspaceId, owner_hash: ownerHash(env.ownerId), kind: "hosted" }); + const client = await connect(); + structured(await client.callTool({ name: "join_relay", arguments: { name: "notes-agent" } })); + const [row] = await rows(); + assert.equal(row!.agent_remote_id, own.id); + assert.equal(row!.relaygate_agent_id, state.agents.get("notes-agent")!.agentId); + assert.match(row!.token, /^rg_/); +}); + +test("on a gate-only install a participant relaygate admitted for another hosted client is refused when the policy has no rule for this one", async (t) => { + const { env, state, connect, rows } = await gateHosted(t); + const client = await connect(); + structured(await client.callTool({ name: "join_relay", arguments: { name: "notes-agent" } })); + // Enrolled as another hosted client; this install's policy now allows only that one. + await env.database.query("UPDATE hosted_relay_participants SET admitted_clients = '{chatgpt}'"); + state.allowed = new Set(["chatgpt"]); + const before = (await rows())[0]!; + const credentials = state.credentials.length; + assert.match(toolError(await client.callTool({ name: "relay_status", arguments: {} })), /does not allow hosted mcp participants/); + assert.equal(state.credentials.length, credentials + 1, "relaygate's policy decided, with a fresh enrolment"); + const after = (await rows())[0]!; + assert.equal(after.token, before.token, "a refusal leaves the row and its token as they were"); + assert.deepEqual(after.admitted_clients, ["chatgpt"]); + assert.equal(state.tokens.get(after.token), "notes-agent", "the stored token still works for the client it was admitted for"); +}); + +test("on a gate-only install a second hosted client enrols once at relaygate and is then admitted beside the first", async (t) => { + const { env, state, connect, rows } = await gateHosted(t); + const client = await connect(); + structured(await client.callTool({ name: "join_relay", arguments: { name: "notes-agent" } })); + await env.database.query("UPDATE hosted_relay_participants SET admitted_clients = '{chatgpt}'"); + state.allowed = new Set(["mcp", "chatgpt"]); + const before = (await rows())[0]!; + const credentials = state.credentials.length; + structured(await client.callTool({ name: "relay_status", arguments: {} })); + assert.equal(state.credentials.length, credentials + 1); + const after = (await rows())[0]!; + assert.deepEqual([...after.admitted_clients].sort(), ["chatgpt", "mcp"]); + assert.notEqual(after.token, before.token, "relaygate revoked the earlier token and issued one for the current rule"); + assert.equal(after.relaygate_agent_id, before.relaygate_agent_id); + structured(await client.callTool({ name: "relay_status", arguments: {} })); + assert.equal(state.credentials.length, credentials + 1, "an admitted client does not enrol again"); +}); + +test("on a gate-only install a renewed participant adopts the new relaygate agent relaygate answers for the same upstream agent", async (t) => { + const { env, state, issue, connect, rows } = await gateHosted(t); + const client = await connect(); + structured(await client.callTool({ name: "join_relay", arguments: { name: "notes-agent" } })); + const before = (await rows())[0]!; + // relaygate re-created its record for the name (a new relaygate agent id), and the stored token stopped working. + state.agents.set("notes-agent", { agentId: `rga_${randomUUID()}`, userId: env.ownerId }); + issue("notes-agent"); + const status = structured(await client.callTool({ name: "relay_status", arguments: {} })); + assert.equal(status.name, "notes-agent"); + const after = (await rows())[0]!; + assert.equal(after.relaygate_agent_id, state.agents.get("notes-agent")!.agentId); + assert.notEqual(after.relaygate_agent_id, before.relaygate_agent_id); + assert.equal(after.agent_remote_id, before.agent_remote_id, "the same upstream agent"); + assert.ok(env.world.agents.has("notes-agent"), "the upstream agent was not released"); +}); diff --git a/test/grok-routines.test.ts b/test/grok-routines.test.ts index 766a6169..5ef7f1d6 100644 --- a/test/grok-routines.test.ts +++ b/test/grok-routines.test.ts @@ -9,12 +9,13 @@ import type { SelfhostConfig } from "../src/config.js"; import { encryptSecret, decryptSecret } from "../src/crypto.js"; import { migrate } from "../src/migrations.js"; import { ControlPlaneStore } from "../src/store.js"; -import { createRelaycastClient } from "../src/messaging/relaycast.js"; +import { createRelaycastClient, RelaycastCallError } from "../src/messaging/relaycast.js"; import { GrokRoutines, GROK_SETUP_PATH } from "../src/mcp/grok-routines.js"; import { parseGrokRoutineCredentials } from "../src/mcp/grok-routine.js"; import { createMcpOAuthProtocol } from "../src/mcp/oauth/protocol.js"; import { McpOAuthSessions } from "../src/mcp/oauth/sessions.js"; import { revokeMcpOAuthGrantRows } from "../src/mcp/oauth/revocations.js"; +import { relayHostedCredentials } from "../src/mcp/relay-hosted-credentials.js"; import { PGliteDatabase, listen, close } from "./support/harness.js"; import { createRelaycastWorld } from "./support/relaycast-world.js"; @@ -274,7 +275,7 @@ test("gate-only: a routine reads a gated participant through relaygate and renew // The participant as a gate-only install stores it: relaygate's agent id and an rg_ token, written 13 hours ago. const tokens = new Map([["rg_old", agent.token]]); const refreshed: string[] = []; - await f.database.query(`UPDATE hosted_relay_participants SET relaygate_agent_id='rga_fake', token_ciphertext=$1, + await f.database.query(`UPDATE hosted_relay_participants SET relaygate_agent_id='rga_fake', token_ciphertext=$1, admitted_clients='{grok-bot}', updated_at=now() - interval '13 hours' WHERE agent_remote_id=$2`, [encryptSecret("rg_old", KEYRING.active), agent.id]); const gate = createRelaycastClient({ internalOrigin: "https://gate.example.test", fetchImpl: async (input, init) => { const url = new globalThis.URL(input instanceof Request ? input.url : String(input)); @@ -305,3 +306,80 @@ test("gate-only: a routine reads a gated participant through relaygate and renew await new GrokRoutines(f.routines.options).tick(); assert.equal(f.calls.length, 1); }); + +test("relaygate token refresh honours the caller's abort signal", async () => { + const gate = createRelaycastClient({ internalOrigin: "https://gate.example.test", fetchImpl: async (_input, init) => { + if (init?.signal?.aborted) throw init.signal.reason; + return Response.json({ token: "rg_renewed" }); + } }); + assert.equal(await gate.refreshGateToken("rg_current"), "rg_renewed"); + await assert.rejects(gate.refreshGateToken("rg_current", AbortSignal.abort()), RelaycastCallError); +}); + +/** + * A gated Grok participant whose stored rg_ token relaygate no longer accepts, + * and a fake relaygate whose POST /v1/register checks the hosted credential + * with relay-control's store and answers with `answer.agentId`. + */ +async function lapsedGatedParticipant(t: test.TestContext, answer: { agentId: string }) { + const f = await fixture(t, "/mcp"); + await f.tool("connect_grok_bot_routine"); await f.save(); + const agent = f.world.agents.get("fake-grok")!; + await f.database.query(`UPDATE hosted_relay_participants SET relaygate_agent_id='rga_fake', token_ciphertext=$1, admitted_clients='{grok-bot}' + WHERE agent_remote_id=$2`, [encryptSecret("rg_lapsed", KEYRING.active), agent.id]); + const tokens = new Map(); + const enrolments: Array<{ agentName: string; client: string }> = []; + const gate = createRelaycastClient({ internalOrigin: "https://gate.example.test", fetchImpl: async (input, init) => { + const url = new globalThis.URL(input instanceof Request ? input.url : String(input)); + const bearer = (new Headers(init?.headers).get("authorization") ?? "").replace(/^Bearer /, ""); + if (url.pathname === "/v1/register") { + const checked = await relayHostedCredentials(f.database).redeem(bearer); + if (checked.state !== "active") return Response.json({ error: "relaygate_unauthenticated" }, { status: 401 }); + enrolments.push({ agentName: checked.credential.agentName, client: checked.credential.client }); + tokens.clear(); tokens.set("rg_renewed", agent.token); + return Response.json({ agent_id: answer.agentId, gid: 22, token: "rg_renewed", user_id: checked.credential.userId }); + } + const upstream = tokens.get(bearer); + if (!upstream) return Response.json({ error: "relaygate_unauthenticated" }, { status: 401 }); + const result = await f.world.handle(init?.method ?? "GET", url.pathname, url.searchParams, upstream, null, null); + if (url.pathname === "/v1/agent" && result?.status === 200) (result.body as any).data.workspace_id = "fake-workspace"; + return Response.json(result?.body ?? { ok: false }, { status: result?.status ?? 404 }); + } }); + const routines = new GrokRoutines({ ...f.routines.options, gate }); + const stored = async () => (await f.database.query<{ token_ciphertext: string; relaygate_agent_id: string; admitted_clients: string[] }>( + "SELECT token_ciphertext, relaygate_agent_id, admitted_clients FROM hosted_relay_participants WHERE agent_remote_id=$1", [agent.id])).rows + .map(row => ({ ...row, token: decryptSecret(row.token_ciphertext, KEYRING) }))[0]!; + const routine = async () => (await f.database.query<{ failures: number; last_error: string | null }>( + "SELECT failures, last_error FROM grok_bot_routines")).rows[0]!; + return { f, routines, enrolments, stored, routine }; +} + +test("gate-only: a routine whose rg_ token relaygate rejects enrols again as Grok Bot and wakes on the next scan", async t => { + const { f, routines, enrolments, stored, routine } = await lapsedGatedParticipant(t, { agentId: "rga_fake" }); + await f.message(); + await routines.tick(); + assert.deepEqual(enrolments, [{ agentName: "fake-grok", client: "grok-bot" }]); + const row = await stored(); + assert.equal(row.token, "rg_renewed"); + assert.equal(row.relaygate_agent_id, "rga_fake"); + assert.deepEqual(row.admitted_clients, ["grok-bot"]); + assert.equal(f.calls.length, 0, "the scan that recovered the token woke nothing"); + assert.equal((await routine()).failures, 0); + await routines.tick(); + assert.equal(f.calls.length, 1, "the next scan read the inbox through relaygate with the new token"); +}); + +test("gate-only: a routine re-enrolment answered with another relaygate agent is not adopted and records a failure", async t => { + const { f, routines, enrolments, stored, routine } = await lapsedGatedParticipant(t, { agentId: "rga_other" }); + await f.message(); + await routines.tick(); + assert.equal(enrolments.length, 1); + const row = await stored(); + assert.equal(row.token, "rg_lapsed", "the stored token is kept"); + assert.equal(row.relaygate_agent_id, "rga_fake"); + assert.deepEqual(row.admitted_clients, ["grok-bot"]); + const state = await routine(); + assert.equal(state.failures, 1); assert.equal(state.last_error, "delivery_unavailable"); + f.advance(); await routines.tick(); + assert.equal(f.calls.length, 0); +}); diff --git a/test/mcp-oauth-connector-kind.test.ts b/test/mcp-oauth-connector-kind.test.ts index 2fef7c52..45c02510 100644 --- a/test/mcp-oauth-connector-kind.test.ts +++ b/test/mcp-oauth-connector-kind.test.ts @@ -1,6 +1,6 @@ import assert from "node:assert/strict"; import { test } from "node:test"; -import { connectorKind, hostOf, type ConnectorKind } from "../src/mcp/oauth/connector-kind.js"; +import { admissionConnectorKind, connectorKind, hostOf, type ConnectorKind } from "../src/mcp/oauth/connector-kind.js"; const classifications: ReadonlyArray = [ ["https://cursor.com/agents/fake/callback", "grok-bot"], @@ -41,6 +41,26 @@ test("mixed registrations retain Grok then ChatGPT then Muse precedence in eithe assert.equal(connectorKind({ clientName: "Grok Bot ChatGPT Muse", redirectUris: ["https://other.example.test/callback"] }), "mcp"); }); +test("admission kind refuses registrations that name two different providers", () => { + const grok = "https://www.cursor.com/agents/fake/callback"; + const chatgpt = "https://chatgpt.com/callback"; + const muse = "https://muse.ai/callback"; + for (const uris of [[grok, chatgpt], [chatgpt, grok], [chatgpt, muse], [grok, muse], [grok, chatgpt, muse]]) { + assert.equal(admissionConnectorKind({ clientName: "fake-grok", redirectUris: uris }), "mcp"); + } + assert.equal(admissionConnectorKind({ clientName: "Grok Bot", redirectUris: ["https://other.example.test/callback"] }), "mcp"); + assert.equal(admissionConnectorKind({ clientName: null, redirectUris: [] }), "mcp"); +}); + +test("admission kind keeps one provider beside neutral cursor and localhost callbacks", () => { + assert.equal(admissionConnectorKind({ clientName: null, redirectUris: [ + "https://www.cursor.com/agents/fake/callback", "cursor://agents/fake/callback", "http://localhost:8787/callback", + ] }), "grok-bot"); + assert.equal(admissionConnectorKind({ clientName: null, redirectUris: ["https://chatgpt.com/a", "https://api.openai.com/b"] }), "chatgpt"); + assert.equal(admissionConnectorKind({ clientName: null, redirectUris: ["https://muse.ai/callback"] }), "muse"); + assert.equal(admissionConnectorKind({ clientName: null, redirectUris: ["cursor://agents/fake/callback"] }), "mcp"); +}); + test("host parsing normalizes hostname and keeps display port/path; malformed URI stays null", () => { assert.deepEqual(hostOf("https://WWW.X.AI:8443/fake/callback"), { scheme: "https", host: "www.x.ai", displayHost: "www.x.ai:8443", path: "/fake/callback", From 875be54ce61faecb55836b731f39e55a00926faf Mon Sep 17 00:00:00 2001 From: layered-control-agent-host Date: Thu, 19 Nov 2026 11:42:01 +0000 Subject: [PATCH 4/5] fix(mcp): re-enrol a hosted participant only while its own agent holds 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 --- docs/identity.md | 6 +++++- .../cloud-import-verify/schema-manifest.json | 6 ++++-- src/mcp/hosted-gate.ts | 4 ++-- src/mcp/relay-participants.ts | 9 +++++--- test/gate-only-hosted-participants.test.ts | 21 +++++++++++++++++++ 5 files changed, 38 insertions(+), 8 deletions(-) diff --git a/docs/identity.md b/docs/identity.md index 175e9a07..0b9a30d1 100644 --- a/docs/identity.md +++ b/docs/identity.md @@ -1582,7 +1582,11 @@ Relaycast agent token for its traffic: 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. + 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: , email: null, principal_type: "relay_hosted", agent_name, client, machine_id: null, org, workspace, diff --git a/scripts/cloud-import-verify/schema-manifest.json b/scripts/cloud-import-verify/schema-manifest.json index 94fbbeea..e07ed1bd 100644 --- a/scripts/cloud-import-verify/schema-manifest.json +++ b/scripts/cloud-import-verify/schema-manifest.json @@ -80,7 +80,8 @@ {"name":"0075_token_session_client_telemetry.sql","sha256":"6c9ce658602d7a5eebad9b7c13a2e2ddca6c1a22f6a3e4ee0be8b3357fafd479"}, {"name":"0076_events_shim_agent_links.sql","sha256":"3f1441ca8cd33613c585c4c725de0a8e88df457e070ec6fb1756214aa7c3e821"}, {"name":"0077_events_shim_sender_release_attempts.sql","sha256":"f586a6324c3af8d81e00cae9fea161772673a0d7ea55c865dfb00bafa3d901cd"}, - {"name":"0078_events_shim_claim_leases.sql","sha256":"1729204ca96b4196d16369b039b72c70b43ae6036c955d06e89f2f168d6d4b7a"} + {"name":"0078_events_shim_claim_leases.sql","sha256":"1729204ca96b4196d16369b039b72c70b43ae6036c955d06e89f2f168d6d4b7a"}, + {"name":"0079_hosted_relay_gate.sql","sha256":"dcba28091f8a00963cc52463f3f7165cd6f41ef08b03f47d0a5a1ff355a4144c"} ], "required":[ {"kind":"column","name":"public.admin_audit_events.action","definition":{"collation":"pg_catalog.default","default":null,"generated":"","identity":"","not_null":true,"position":6,"type":"text"}}, @@ -574,6 +575,7 @@ {"kind":"column","name":"public.grok_bot_routines.next_attempt_at","definition":{"collation":null,"default":"now()","generated":"","identity":"","not_null":true,"position":4,"type":"timestamp with time zone"}}, {"kind":"column","name":"public.grok_bot_routines.notified_delivery_ids","definition":{"collation":"pg_catalog.default","default":"'{}'::text[]","generated":"","identity":"","not_null":true,"position":3,"type":"text[]"}}, {"kind":"column","name":"public.grok_bot_routines.updated_at","definition":{"collation":null,"default":"now()","generated":"","identity":"","not_null":true,"position":8,"type":"timestamp with time zone"}}, + {"kind":"column","name":"public.hosted_relay_participants.admitted_clients","definition":{"collation":"pg_catalog.default","default":"'{}'::text[]","generated":"","identity":"","not_null":true,"position":12,"type":"text[]"}}, {"kind":"column","name":"public.hosted_relay_participants.agent_name","definition":{"collation":"pg_catalog.default","default":null,"generated":"","identity":"","not_null":true,"position":6,"type":"text"}}, {"kind":"column","name":"public.hosted_relay_participants.agent_remote_id","definition":{"collation":"pg_catalog.default","default":null,"generated":"","identity":"","not_null":true,"position":7,"type":"text"}}, {"kind":"column","name":"public.hosted_relay_participants.created_at","definition":{"collation":null,"default":"now()","generated":"","identity":"","not_null":true,"position":9,"type":"timestamp with time zone"}}, @@ -2130,5 +2132,5 @@ "optional":{ }, - "sha256":"58bf921c18df5ac451d344a78b72cb34a3a58b79bebfc058845ba1dd36fd5c6c" + "sha256":"f462e4c9a77b83b5eed8a420c6209270833589dc2ccaaffc0865326001eed50a" } diff --git a/src/mcp/hosted-gate.ts b/src/mcp/hosted-gate.ts index 09247cca..31cb951f 100644 --- a/src/mcp/hosted-gate.ts +++ b/src/mcp/hosted-gate.ts @@ -82,9 +82,9 @@ export async function enrolHostedAtGate( } catch (error) { throw refusal(error, input); } - // relaygate names the Control user it enrolled the agent for; any other user is not this owner. + // relaygate names the Control user it enrolled the agent for; any other user is not this owner. The token is + // dropped and nothing is released: by relaygate's own answer the agent behind it is that other user's. if (enrolled.userId !== null && enrolled.userId !== input.userId) { - await deps.gate.releaseOwnAgent(enrolled.token).catch(() => {}); throw new HostedGateRefused("relaygate enrolled this participant for another user. Nothing was joined."); } const upstream = await deps.gate.authenticatedAgent(enrolled.token); diff --git a/src/mcp/relay-participants.ts b/src/mcp/relay-participants.ts index 0393d79c..514577d3 100644 --- a/src/mcp/relay-participants.ts +++ b/src/mcp/relay-participants.ts @@ -537,10 +537,13 @@ function createRelayService(context: McpContext) { const state = (await gateState(row, decryptSecret(row.tokenCiphertext, keyring))).state; if (state === "changed" || (state === "ok" && row.admittedClients.includes(kind))) return; rejected = state === "rejected"; - } else { - const upstream = await client.getRosterAgent(key, row.agentName); - if (!upstream || upstream.status === "released" || upstream.id !== row.agentRemoteId || !ownsRemote(upstream)) return; } + // relaygate takes an upstream agent of this name over when it enrols one it already knows. Ask only while that + // agent is still this row's: a replaced or renamed one is never handed to relaygate. A pre-gate row must also + // still be this owner's; a gated row's agent was registered by relaygate and carries no owner marker. + const upstream = await client.getRosterAgent(key, row.agentName); + if (!upstream || upstream.status === "released" || upstream.id !== row.agentRemoteId + || (row.relaygateAgentId === null && !ownsRemote(upstream))) return; const enrolled = await enrolAtGate(row.agentName); if (enrolled.relaycastAgentId !== row.agentRemoteId) { // The agent this row was is gone: never adopt another. Release only an agent relaygate registered itself for diff --git a/test/gate-only-hosted-participants.test.ts b/test/gate-only-hosted-participants.test.ts index f587def5..950bc25b 100644 --- a/test/gate-only-hosted-participants.test.ts +++ b/test/gate-only-hosted-participants.test.ts @@ -389,3 +389,24 @@ test("on a gate-only install a renewed participant adopts the new relaygate agen assert.equal(after.agent_remote_id, before.agent_remote_id, "the same upstream agent"); assert.ok(env.world.agents.has("notes-agent"), "the upstream agent was not released"); }); + +test("on a gate-only install a lapsed participant whose name now belongs to another agent is not enrolled again at relaygate", async (t) => { + const { env, state, issue, connect, rows } = await gateHosted(t); + const client = await connect(); + structured(await client.callTool({ name: "join_relay", arguments: { name: "notes-agent" } })); + const before = (await rows())[0]!; + // The upstream agent was released outside this service and another owner registered the name; the stored token lapsed. + env.world.agents.delete("notes-agent"); + const foreign = env.world.addAgent("notes-agent", { + source: "cloud-hosted-mcp", cloud_workspace_id: env.workspaceId, owner_hash: ownerHash("another-user"), kind: "hosted" }); + assert.notEqual(foreign.id, before.agent_remote_id); + issue("notes-agent"); + const credentials = state.credentials.length; + const registrations = state.seen.filter(call => call === "POST /v1/register").length; + await client.callTool({ name: "relay_status", arguments: {} }); + assert.equal(state.credentials.length, credentials, "no hosted credential was minted for a name that is no longer this row's agent"); + assert.equal(state.seen.filter(call => call === "POST /v1/register").length, registrations, "relaygate was not asked to take the name over"); + assert.equal(env.world.agents.get("notes-agent"), foreign, "the other owner's agent is untouched"); + const after = (await rows())[0]; + if (after) assert.equal(after.token, before.token, "the row adopted nothing"); +}); From ce913ccf93ae2be9820d0e1f6a8a954d357c9c80 Mon Sep 17 00:00:00 2001 From: layered-control-agent-host Date: Thu, 19 Nov 2026 12:00:50 +0000 Subject: [PATCH 5/5] fix(mcp): read a connection's admission kind from where its codes were 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 --- CHANGELOG.md | 5 +-- docs/identity.md | 17 ++++++---- migrations/0079_hosted_relay_gate.sql | 4 +++ .../cloud-import-verify/schema-manifest.json | 5 +-- src/mcp/grok-routines.ts | 7 +++-- src/mcp/oauth/connector-kind.ts | 31 +++++++++++++------ src/mcp/relay-participants.ts | 15 +++++---- test/grok-routines.test.ts | 20 +++++++++++- test/mcp-oauth-connector-kind.test.ts | 31 ++++++++++++++++--- 9 files changed, 101 insertions(+), 34 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 68280a63..507ac4c1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -29,8 +29,9 @@ assigned at release. 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: a registration whose redirect URIs name two different - providers enrols as `mcp`. Grok Bot routines whose token relaygate rejects + 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 diff --git a/docs/identity.md b/docs/identity.md index 0b9a30d1..20c62178 100644 --- a/docs/identity.md +++ b/docs/identity.md @@ -1568,12 +1568,17 @@ Relaycast agent token for its traffic: 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, from its registered - OAuth redirect URIs: `chatgpt`, `grok-bot`, `muse` or `cursor-cloud` when - every URI that names a provider names the same one, else `mcp`. A - registration whose redirect URIs name two different providers enrols as - `mcp`, so it never matches a rule written for either provider. Native MCP - sessions enrol as `mcp`. + 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 diff --git a/migrations/0079_hosted_relay_gate.sql b/migrations/0079_hosted_relay_gate.sql index cc71af08..c6c32d16 100644 --- a/migrations/0079_hosted_relay_gate.sql +++ b/migrations/0079_hosted_relay_gate.sql @@ -37,3 +37,7 @@ ALTER TABLE hosted_relay_participants ADD COLUMN IF NOT EXISTS relaygate_agent_i -- 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; diff --git a/scripts/cloud-import-verify/schema-manifest.json b/scripts/cloud-import-verify/schema-manifest.json index e07ed1bd..4dc10943 100644 --- a/scripts/cloud-import-verify/schema-manifest.json +++ b/scripts/cloud-import-verify/schema-manifest.json @@ -81,7 +81,7 @@ {"name":"0076_events_shim_agent_links.sql","sha256":"3f1441ca8cd33613c585c4c725de0a8e88df457e070ec6fb1756214aa7c3e821"}, {"name":"0077_events_shim_sender_release_attempts.sql","sha256":"f586a6324c3af8d81e00cae9fea161772673a0d7ea55c865dfb00bafa3d901cd"}, {"name":"0078_events_shim_claim_leases.sql","sha256":"1729204ca96b4196d16369b039b72c70b43ae6036c955d06e89f2f168d6d4b7a"}, - {"name":"0079_hosted_relay_gate.sql","sha256":"dcba28091f8a00963cc52463f3f7165cd6f41ef08b03f47d0a5a1ff355a4144c"} + {"name":"0079_hosted_relay_gate.sql","sha256":"c9b201ff87a00dc9bf06cb304e46673556e47153343a68edf8d557029b988af1"} ], "required":[ {"kind":"column","name":"public.admin_audit_events.action","definition":{"collation":"pg_catalog.default","default":null,"generated":"","identity":"","not_null":true,"position":6,"type":"text"}}, @@ -1880,6 +1880,7 @@ {"kind":"index","name":"public.mcp_attestation_tool_uses.mcp_attestation_tool_uses_pkey","definition":{"definition":"CREATE UNIQUE INDEX mcp_attestation_tool_uses_pkey ON public.mcp_attestation_tool_uses USING btree (workspace_id, user_id, tool_use_id)","live":true,"nulls_not_distinct":false,"primary":true,"ready":true,"unique":true,"valid":true}}, {"kind":"index","name":"public.mcp_oauth_authorization_codes.mcp_oauth_authorization_codes_pkey","definition":{"definition":"CREATE UNIQUE INDEX mcp_oauth_authorization_codes_pkey ON public.mcp_oauth_authorization_codes USING btree (code_hash)","live":true,"nulls_not_distinct":false,"primary":true,"ready":true,"unique":true,"valid":true}}, {"kind":"index","name":"public.mcp_oauth_authorization_codes.mcp_oauth_codes_expiry_idx","definition":{"definition":"CREATE INDEX mcp_oauth_codes_expiry_idx ON public.mcp_oauth_authorization_codes USING btree (expires_at)","live":true,"nulls_not_distinct":false,"primary":false,"ready":true,"unique":false,"valid":true}}, + {"kind":"index","name":"public.mcp_oauth_authorization_codes.mcp_oauth_codes_grant_idx","definition":{"definition":"CREATE INDEX mcp_oauth_codes_grant_idx ON public.mcp_oauth_authorization_codes USING btree (grant_id) WHERE (grant_id IS NOT NULL)","live":true,"nulls_not_distinct":false,"primary":false,"ready":true,"unique":false,"valid":true}}, {"kind":"index","name":"public.mcp_oauth_clients.mcp_oauth_clients_pkey","definition":{"definition":"CREATE UNIQUE INDEX mcp_oauth_clients_pkey ON public.mcp_oauth_clients USING btree (client_id)","live":true,"nulls_not_distinct":false,"primary":true,"ready":true,"unique":true,"valid":true}}, {"kind":"index","name":"public.mcp_oauth_grants.mcp_oauth_grant_family_pair","definition":{"definition":"CREATE UNIQUE INDEX mcp_oauth_grant_family_pair ON public.mcp_oauth_grants USING btree (id, token_family_id)","live":true,"nulls_not_distinct":false,"primary":false,"ready":true,"unique":true,"valid":true}}, {"kind":"index","name":"public.mcp_oauth_grants.mcp_oauth_grants_id_organization_id_workspace_id_u_key","definition":{"definition":"CREATE UNIQUE INDEX mcp_oauth_grants_id_organization_id_workspace_id_u_key ON public.mcp_oauth_grants USING btree (id, organization_id, workspace_id, user_id)","live":true,"nulls_not_distinct":false,"primary":false,"ready":true,"unique":true,"valid":true}}, @@ -2132,5 +2133,5 @@ "optional":{ }, - "sha256":"f462e4c9a77b83b5eed8a420c6209270833589dc2ccaaffc0865326001eed50a" + "sha256":"33cc721c5bde60d7b06dde343d9f6027dcf8c784ca2212d615bedd16eb5cd863" } diff --git a/src/mcp/grok-routines.ts b/src/mcp/grok-routines.ts index e2786ff7..14f4a1b6 100644 --- a/src/mcp/grok-routines.ts +++ b/src/mcp/grok-routines.ts @@ -5,7 +5,7 @@ import { page } from "../identity/pages.js"; import { RelaycastCallError, type RelaycastClient } from "../messaging/relaycast.js"; import { isBindingOwnedIdentity } from "../messaging/binding-identities.js"; import { lockOrganization, lockUser, type TenancyMode } from "../tenancy.js"; -import { admissionConnectorKind } from "./oauth/connector-kind.js"; +import { admissionConnectorKind, usedRedirectUrisSql } from "./oauth/connector-kind.js"; import { enrolHostedAtGate, type GateEnrolment } from "./hosted-gate.js"; import type { McpConsentPrincipal } from "./oauth/consent.js"; import { GrokRoutineError, grokInboxPrompt, parseGrokRoutineCredentials } from "./grok-routine.js"; @@ -41,7 +41,8 @@ export class GrokRoutines { async grant(tx: SqlExecutor, id: string, owner: Owner): Promise { await lockUser(tx, owner.userId); await lockOrganization(tx, owner.organizationId); - const row = (await tx.query(`SELECT g.id,g.agent_name,g.agent_remote_id,c.client_name,c.redirect_uris + const row = (await tx.query(`SELECT g.id,g.agent_name,g.agent_remote_id,c.client_name,c.redirect_uris, + ${usedRedirectUrisSql("g.id", "g.client_id")} AS used FROM mcp_oauth_grants g JOIN mcp_oauth_clients c ON c.client_id=g.client_id JOIN workspaces w ON w.id=g.workspace_id AND w.organization_id=g.organization_id JOIN organization_memberships m ON m.organization_id=g.organization_id AND m.user_id=g.user_id @@ -54,7 +55,7 @@ export class GrokRoutines { FOR UPDATE OF g`, [id, owner.userId, owner.organizationId, owner.workspaceId, [this.options.publicOrigin + "/mcp", this.options.publicOrigin + "/cloud/api/v1/mcp/shared-sessions"], this.options.tenancyMode, this.now()])).rows[0]; - if (!row || admissionConnectorKind({ clientName: row.client_name, redirectUris: row.redirect_uris }) !== "grok-bot") { + if (!row || admissionConnectorKind({ clientName: row.client_name, redirectUris: row.redirect_uris }, row.used ?? []) !== "grok-bot") { throw new GrokRoutineError("This Grok Bot connection is no longer available. Reconnect it in this workspace."); } return row; diff --git a/src/mcp/oauth/connector-kind.ts b/src/mcp/oauth/connector-kind.ts index aadcb61d..26c5afb7 100644 --- a/src/mcp/oauth/connector-kind.ts +++ b/src/mcp/oauth/connector-kind.ts @@ -42,15 +42,28 @@ export function connectorKind(client: { clientName: string | null; redirectUris: /** * The kind an OAuth grant is admitted as: relaygate enrolment of its hosted - * participant and Grok routines. Unlike connectorKind's display precedence, a - * registration naming two different providers is no provider at all ("mcp"), - * so a client cannot claim one provider's admission by adding its callback - * beside another's. Callbacks that classify as no provider (cursor://, - * localhost) are neutral: Grok Bot registers them beside its cursor.com - * callback. + * participant and Grok routines. `used` holds the redirect URIs the grant's + * authorization codes were delivered to; the kind is the provider all of them + * name, so only a grant whose codes went to a provider's own callback is that + * provider's. A client that registers its own callback beside a provider's + * receives its codes at its own callback and is "mcp". A grant with no + * recorded delivery falls back to the registration, and then every + * registered URI must name the same provider. Unlike connectorKind's display + * precedence, any mix is no provider at all. */ -export function admissionConnectorKind(client: { clientName: string | null; redirectUris: string[] }): ConnectorKind { - const kinds = new Set(client.redirectUris.map((uri) => connectorKind({ clientName: client.clientName, redirectUris: [uri] }))); - kinds.delete("mcp"); +export function admissionConnectorKind( + client: { clientName: string | null; redirectUris: string[] }, + used: readonly string[] = [], +): ConnectorKind { + const uris = used.length > 0 ? used : client.redirectUris; + const kinds = new Set(uris.map((uri) => connectorKind({ clientName: client.clientName, redirectUris: [uri] }))); return kinds.size === 1 ? [...kinds][0]! : "mcp"; } + +/** + * SQL for `used` above: the redirect URIs of the consumed authorization codes + * of the grant in `grantId` (a SQL expression) issued to `clientId`. + */ +export const usedRedirectUrisSql = (grantId: string, clientId: string) => + `ARRAY(SELECT DISTINCT a.redirect_uri FROM mcp_oauth_authorization_codes a + WHERE a.grant_id = ${grantId} AND a.client_id = ${clientId} AND a.consumed_at IS NOT NULL)`; diff --git a/src/mcp/relay-participants.ts b/src/mcp/relay-participants.ts index 514577d3..47179994 100644 --- a/src/mcp/relay-participants.ts +++ b/src/mcp/relay-participants.ts @@ -12,7 +12,7 @@ import type { McpContext, McpMember } from "./context.js"; import { isListedRelayAgent, rosterAgent } from "./team-activity.js"; import { buildAgentCard, cardMetadata, cardSummary, recipientCard, type SetCardInput } from "./relay-agent-cards.js"; import { McpOAuthAccessRefused, McpOAuthActorRefused } from "./oauth/admission.js"; -import { admissionConnectorKind, connectorKind } from "./oauth/connector-kind.js"; +import { admissionConnectorKind, connectorKind, usedRedirectUrisSql } from "./oauth/connector-kind.js"; import { LAUNCH_ROLE_REFUSAL } from "./catalog.js"; import { RECEIPT_GUIDANCE } from "../messaging/delivery-status.js"; import { MCP_OAUTH_RETIRING_MESSAGE, McpOAuthAgentRetiring, retiringIdentity } from "./oauth/retirement.js"; @@ -456,16 +456,19 @@ function createRelayService(context: McpContext) { /** * The hosted MCP client relaygate's policy matches this caller's - * participants on: the grant's admission kind, so a registration naming two - * providers enrols as neither ("mcp"). Callers inside a transaction pass it. + * participants on: the grant's admission kind, from the redirect URIs its + * authorization codes were delivered to, so a client that only registers a + * provider's callback beside its own enrols as "mcp". Callers inside a + * transaction pass it. */ let clientKind: Promise | undefined; function hostedClient(query: SqlExecutor = executor): Promise { clientKind ??= (async () => { if (!oauth) return "mcp" as const; - const row = (await query.query<{ client_name: string | null; redirect_uris: string[] }>( - "SELECT client_name, redirect_uris FROM mcp_oauth_clients WHERE client_id = $1", [oauth.access.clientId])).rows[0]; - return row ? admissionConnectorKind({ clientName: row.client_name, redirectUris: row.redirect_uris ?? [] }) : "mcp" as const; + const row = (await query.query<{ client_name: string | null; redirect_uris: string[]; used: string[] }>( + `SELECT c.client_name, c.redirect_uris, ${usedRedirectUrisSql("$2::uuid", "c.client_id")} AS used + FROM mcp_oauth_clients c WHERE c.client_id = $1`, [oauth.access.clientId, oauth.access.grantId])).rows[0]; + return row ? admissionConnectorKind({ clientName: row.client_name, redirectUris: row.redirect_uris ?? [] }, row.used ?? []) : "mcp" as const; })(); return clientKind; } diff --git a/test/grok-routines.test.ts b/test/grok-routines.test.ts index 5ef7f1d6..3d696b0d 100644 --- a/test/grok-routines.test.ts +++ b/test/grok-routines.test.ts @@ -1,6 +1,6 @@ import assert from "node:assert/strict"; import test from "node:test"; -import { randomUUID } from "node:crypto"; +import { randomBytes, randomUUID } from "node:crypto"; import { createServer } from "node:http"; import { Client } from "@modelcontextprotocol/sdk/client/index.js"; import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"; @@ -226,6 +226,24 @@ test("browser setup refuses anonymous, bearer, cross-origin and cross-owner call assert.equal((await f.save()).status, 400); }); +test("a connection is Grok Bot's only when its authorization codes were delivered to the Grok callback", async (t) => { + const f = await fixture(t); + const grok = "https://www.cursor.com/agents/fake/callback", own = "http://localhost:8787/callback"; + await f.database.query("UPDATE mcp_oauth_clients SET redirect_uris=$2 WHERE client_id=$1", [f.clientId, [grok, own]]); + const code = (redirectUri: string, consumed: boolean) => f.database.query(`INSERT INTO mcp_oauth_authorization_codes + (code_hash,client_id,user_id,organization_id,workspace_id,agent_name,redirect_uri,code_challenge,scopes,resource,grant_id,expires_at,consumed_at) + SELECT $1,g.client_id,g.user_id,g.organization_id,g.workspace_id,g.agent_name,$2,'fake-challenge',g.scopes,g.resource,g.id,now(),$3 + FROM mcp_oauth_grants g WHERE g.id=$4`, [randomBytes(32).toString("hex"), redirectUri, consumed ? new Date() : null, f.owner.grantId]); + // No recorded delivery: a registration with the client's own callback beside Grok's is not Grok Bot. + await assert.rejects(f.routines.status(f.owner.grantId, f.owner)); + // A code that was never redeemed says nothing; one delivered to the Grok callback makes the connection Grok Bot's. + await code(own, false); await code(grok, true); + assert.equal((await f.routines.status(f.owner.grantId, f.owner)).configured, false); + // A code delivered to the client's own callback: not Grok Bot, whatever else it registered. + await code(own, true); + await assert.rejects(f.routines.status(f.owner.grantId, f.owner)); +}); + test("revocation deletes the encrypted routine atomically; expired sessions stop the worker", async t => { const f = await fixture(t); await f.tool("connect_grok_bot_routine"); await f.save(); await f.message(); await assert.rejects(f.database.transaction(async tx => { diff --git a/test/mcp-oauth-connector-kind.test.ts b/test/mcp-oauth-connector-kind.test.ts index 45c02510..63ddee6d 100644 --- a/test/mcp-oauth-connector-kind.test.ts +++ b/test/mcp-oauth-connector-kind.test.ts @@ -52,13 +52,34 @@ test("admission kind refuses registrations that name two different providers", ( assert.equal(admissionConnectorKind({ clientName: null, redirectUris: [] }), "mcp"); }); -test("admission kind keeps one provider beside neutral cursor and localhost callbacks", () => { - assert.equal(admissionConnectorKind({ clientName: null, redirectUris: [ - "https://www.cursor.com/agents/fake/callback", "cursor://agents/fake/callback", "http://localhost:8787/callback", - ] }), "grok-bot"); +test("admission kind from the registration needs every redirect URI to name the same provider", () => { assert.equal(admissionConnectorKind({ clientName: null, redirectUris: ["https://chatgpt.com/a", "https://api.openai.com/b"] }), "chatgpt"); assert.equal(admissionConnectorKind({ clientName: null, redirectUris: ["https://muse.ai/callback"] }), "muse"); - assert.equal(admissionConnectorKind({ clientName: null, redirectUris: ["cursor://agents/fake/callback"] }), "mcp"); + assert.equal(admissionConnectorKind({ clientName: null, redirectUris: ["https://www.cursor.com/agents/fake/callback"] }), "grok-bot"); + // A callback of its own beside a provider's is where such a client would receive its codes. + for (const provider of ["https://chatgpt.com/callback", "https://muse.ai/callback", "https://www.cursor.com/agents/fake/callback"]) { + for (const own of ["https://attacker.example.test/callback", "http://localhost:8787/callback", "http://127.0.0.1:8787/callback"]) { + assert.equal(admissionConnectorKind({ clientName: "ChatGPT", redirectUris: [provider, own] }), "mcp"); + assert.equal(admissionConnectorKind({ clientName: "ChatGPT", redirectUris: [own, provider] }), "mcp"); + } + } +}); + +test("admission kind follows the redirect URIs the grant's codes were delivered to", () => { + const grok = "https://www.cursor.com/agents/fake/callback"; + const chatgpt = "https://chatgpt.com/callback"; + const own = "https://attacker.example.test/callback"; + const local = "http://localhost:8787/callback"; + // A provider that also registers a loopback callback is still that provider when its codes went to its own callback. + assert.equal(admissionConnectorKind({ clientName: null, redirectUris: [grok, local] }, [grok]), "grok-bot"); + assert.equal(admissionConnectorKind({ clientName: null, redirectUris: [chatgpt, own] }, [chatgpt]), "chatgpt"); + // The same registrations are no provider when a code went anywhere else. + assert.equal(admissionConnectorKind({ clientName: null, redirectUris: [grok, local] }, [local]), "mcp"); + assert.equal(admissionConnectorKind({ clientName: null, redirectUris: [chatgpt, own] }, [own]), "mcp"); + assert.equal(admissionConnectorKind({ clientName: null, redirectUris: [chatgpt, own] }, [chatgpt, own]), "mcp"); + assert.equal(admissionConnectorKind({ clientName: null, redirectUris: [grok, chatgpt] }, [grok, chatgpt]), "mcp"); + // The delivery decides even when the registration alone names one provider. + assert.equal(admissionConnectorKind({ clientName: null, redirectUris: [chatgpt] }, [own]), "mcp"); }); test("host parsing normalizes hostname and keeps display port/path; malformed URI stays null", () => {