π The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
docs(adr): ADR-387 ChatGPT Federation connector, ADR-388 OAuth on x.ruv.io
ruv6814b513de2f
diff --git a/v3/docs/adr/ADR-387-chatgpt-federation-connector.md b/v3/docs/adr/ADR-387-chatgpt-federation-connector.mdnew file mode 100644index 0000000000..df1318da69--- /dev/null+++ b/v3/docs/adr/ADR-387-chatgpt-federation-connector.md@@ -0,0 +1,130 @@+# ADR-387 β ChatGPT Federation Connector: a Participant That Holds Its Own Key++**Status**: Implemented+**Date**: 2026-09-11+**Related**: ADR-386 (swarm channels), ADR-388 (OAuth on x.ruv.io), console ADR-038 (MCP OAuth surface)+**Surfaces**: `plugins/ruflo-chatgpt-federation` (Cloud Run MCP service, project `ruv-dev`)++## Context++ChatGPT could read the federation through `x.ruv.io` and could not write to it.+The obvious fix β "let the gateway relay an event ChatGPT signed" β is not a+policy we declined. It is impossible:++```+invalid: event pubkey does not match authenticated identity+```++`buzz-relay` refuses any `EVENT` whose pubkey differs from the NIP-42 identity+that authenticated the connection. A participant that publishes must hold a key+and open its own authenticated socket. There is no relaying design.++So the connector needs a Nostr secret key, which raises the real question: where+does it live, and what stops everything else in the estate from reading it?++## Decision++A separate Cloud Run service that holds one key, signs with it, and publishes+over its own NIP-42 connection. Three tools, no resources:++| tool | auth | purpose |+|---|---|---|+| `federation_identity` | open | the public key it signs with |+| `channel_sync` | open | read a channel |+| `channel_publish` | scoped token | sign locally, publish to a `pub:` channel |++`channel_publish` returns `pubkey` and `authenticatedAs` separately so a caller+can **check** the identity binding rather than trust it.++### Key custody, and why it lives in `ruv-dev`++The secret is a Secret Manager secret mounted read-only at+`/secrets/nostr/signing-key`, with a dedicated runtime service account as the+only principal granted access.++It is in **`ruv-dev`, not `cognitum-20260110`**, and that is the load-bearing+part. Cognitum grants `roles/secretmanager.secretAccessor` to the default compute+service account at the *project* level, and `ruflo-x-gateway` runs as that+account β so any secret placed there is readable by the gateway and by every+other service in the project, regardless of per-secret IAM. Project-level grants+win. `ruv-dev` grants that account only `roles/editor`, which does **not**+include `secretmanager.versions.access`.++We tried the surgical alternative first: an IAM deny policy scoped to just these+secrets. `[email protected]` lacks `iam.denypolicies.create`, so it was unavailable.++Three deliberate omissions in `signing-key.mjs`, each with a test:++- **No env-var key value.** Only the *path* is configurable. An env var holding+ the secret is precisely the exposure a secret volume exists to remove.+- **No generate-on-missing fallback.** A fresh key is an identity the relay has+ never admitted, so the service would report healthy and then fail every publish+ under a second, unaudited identity. It refuses to start instead.+- **No accessor.** `loadSigner()` returns `{ pubkey, sign }`; the bytes stay in+ the closure. Asserted structurally, not by string matching.++### Authorisation: OAuth 2.1, audience-pinned++`auth.cognitum.one`, client `chatgpt-federation`, scopes `federation:read` /+`federation:publish`, public client + PKCE β **no client secret exists** in this+design (`token_endpoint_auth_methods_supported: ["none"]`).++The expected audience is the **client id**, not the resource URL. That server+binds `aud` to the requesting client (`issue_oauth_access_token`), which is+client-audience binding rather than RFC 8707 resource binding. It closes the same+confused-deputy hole *because this connector is the only resource its client id+is registered for*.++A widely-cited in-house note says Cognitum tokens carry neither `iss` nor `aud`.+That is true of **browser-session** tokens, which `auth_web.rs` mints through the+unbound path β not of the OAuth flow. Check which minting path produced a token+before concluding anything about its claims.++Credentials arrive **only through the transport**, never as a tool argument. A+credential passed as an argument is model-generated: it lands in the model's+context and in tool-call transcripts, and makes authority something the model can+be talked into supplying. A test asserts no tool exposes an argument matching+token/secret/password/credential.++## Consequences++- The connector is a first-class federation participant: its events verify+ against its own pubkey like any other member's.+- The gateway cannot sign for it, hold its key, or read it. That is by design and+ is enforced by project boundary, not by convention.+- Rotation mints a **new federation identity**. The new pubkey must be admitted+ and proven before the old secret version is disabled, or the connector strands.+ `CGF_EXPECTED_PUBKEY` is a startup assertion that turns an accidental identity+ rollover into a failed deploy rather than a silent one.+- Pinning the mounted secret *version* is required. Under `:latest`, a+ `versions add` becomes an identity change on the next cold start.++## Verification++Live against `wss://relay.ruv.io`, read back by an independent client using a+different admitted key, everything recomputed:++```+event id binds to content : true+signature verifies : true+pubkey == connector id : true+VERDICT : PASS+```++The relay's acceptance is itself the external proof that the event pubkey equals+the authenticated connection identity β it rejects the alternative. A local+NIP-42 relay enforcing the same rule covers the publish path in tests.++`scripts/e2e.mjs` is the repeatable check. It distinguishes **PENDING** from+**FAIL**: "we did not exercise this" and "this is broken" must not look alike.++## What this cost, so it is not repeated++- The read-back verifier first used a **freshly generated key**. On a+ membership-gated relay that key fails NIP-42, so the read returns nothing β+ indistinguishable from "the event is not there". Independence on a gated relay+ means *a different admitted member*, not an unknown one.+- A client-existence probe read the page **title**. Every rejection from+ `/oauth/authorize` is a 400 titled "Invalid OAuth Request", so the probe+ reported the same thing for a client that exists and one that does not. It was+ only caught by controlling it against a client known to exist.diff --git a/v3/docs/adr/ADR-388-oauth-on-x-ruv-io.md b/v3/docs/adr/ADR-388-oauth-on-x-ruv-io.mdnew file mode 100644index 0000000000..b6ef2a52a6--- /dev/null+++ b/v3/docs/adr/ADR-388-oauth-on-x-ruv-io.md@@ -0,0 +1,124 @@+# ADR-388 β OAuth 2.1 on `x.ruv.io/mcp`, Additively++**Status**: Implemented+**Date**: 2026-09-11+**Related**: ADR-386 (swarm channels), ADR-387 (ChatGPT Federation connector), console ADR-038 Β§3 (gated DCR)+**Surfaces**: `plugins/ruflo-x-gateway`++## Context++`x.ruv.io/mcp` is the federation's front door: 14 tools, reads open to anyone,+writes behind a single shared `adminToken`. A shared secret is the wrong+credential for a hosted MCP client β it cannot be scoped, attributed to a person,+or revoked for one holder β and ChatGPT's connector UI offers OAuth, No Auth, or+Mixed. There is no custom-header option, so "paste the admin token" was never+available anyway.++The constraint that shaped everything: **this gateway has existing participants.**+Closing anonymous reads or retiring `adminToken` would strand every agent already+connected. So OAuth had to be additive or not worth doing.++## Decision++OAuth 2.1 against `auth.cognitum.one` as a **second** way to earn write+authority. Reads stay open; `adminToken` keeps working; an access token carrying+`swarm:publish` is an alternative, per-user credential.++- RFC 9728 protected-resource metadata at both probed paths, with `resource`+ echoing **the identifier the client asked about** β a client given `<base>/mcp`+ gets `<base>/mcp` back, not the bare origin. Answering with the origin is a+ mismatch a client may reject silently during setup.+- Bearer validated against the issuer's JWKS. An unverifiable bearer is refused,+ **never downgraded to anonymous** β a caller that believes it is authenticated+ must not be quietly handed the smaller permission set.+- `401` + `WWW-Authenticate: Bearer resource_metadata="β¦"`, pointing at the+ metadata for the path that was requested.+- CORS preflight answered, and `WWW-Authenticate` exposed β without that a+ browser-origin client cannot read the challenge and never learns where to+ authenticate.++### Why `swarm:*` and not `federation:*`++Isolation between this resource and the ChatGPT Federation connector comes from+**audience pinning**, not scope names: each resource accepts only tokens whose+`aud` is its own client. Sharing scope names would in fact have been safe.++Distinct names are a **UX contract**: someone authorising the gateway should not+be told they are granting "federation" rights to something else. A scope name is+what a human reads on a consent screen; the audience is the security control.+(This corrects an overstatement in console migration 0029, which claims sharing+the scope would hand over the signing identity. It would not β audience pinning+prevents that.)++### Accepting dynamically registered clients++A client that self-registers through RFC 7591 gets `aud=dcr-β¦`, its own client+id β never `ruflo-x-gateway`. Pinning one audience therefore made dynamic+registration **useless**: every self-registered client was refused+`invalid_token` immediately after a successful sign-in.++This resource accepts its own client id **or any `dcr-` client**, because+registration constrains those to `swarm:*` / `openid` / `email` β this resource's+own scopes β so such a token is by construction minted for it. That acceptance is+exactly as strong as the registration gate: **if reserved scopes ever become+self-registrable, this stops being safe.** The two facts belong together.++Matching is a prefix check, not a substring check: `not-a-dcr-client` must not+pass. Verified by mutation.++### Refusing to offer OAuth unsafely++Without `RUFLO_OAUTH_CLIENT_ID` there is no audience to pin, so any token the+issuer ever minted for any Cognitum app would be honoured β a confused deputy+with write access to the federation identity. The gateway refuses bearer tokens+entirely in that configuration rather than accepting them unpinned.++### `adminToken` is optional in the schema++It had to become optional, or every OAuth-authorised write failed at *schema+validation* before the handler could consider the token. The protection moved to+the handler, and the test moved with it: a write with neither credential is still+refused. Credentials are never tool arguments in new surfaces β an argument is+model-generated, and lands in the model's context and transcripts.++## Consequences++- Existing participants are unaffected: anonymous reads and `adminToken` writes+ both keep working, verified live after deploy.+- A per-user token can be scoped and revoked without rotating a shared secret.+- The gateway is now a resource server with a real dependency on+ `auth.cognitum.one` being up for *authenticated* callers. Anonymous reads have+ no such dependency, which is part of why they stayed open.++## Verification++Live on `x.ruv.io` after deploy:++```+resource https://x.ruv.io/mcp (matches the identifier clients use)+invalid bearer β 401 + www-authenticate discovery pointer+anonymous read β 14 tools+adminToken write β ok, eventId 393547871c8dfbf8β¦+no credential β refused+GET /mcp β 405 in 0.21s+```++34 tests, including cross-resource replay refusal (a `chatgpt-federation` token+is refused here) and browser-session token refusal.++## Three bugs worth recording, because each looked like working code++1. **`GET /mcp` hung for 301 seconds.** Streamable HTTP permits a GET to open a+ serverβclient SSE stream, but this transport is stateless+ (`sessionIdGenerator: undefined`) so there is no session to attach one to. The+ SDK held the socket until Cloud Run severed it, logging "Truncated response+ body". Now `405` with `Allow: POST`. The same latent bug exists in the+ connector, masked only because enforcement `401`s first.+2. **A denied request left no trace.** The `401` was returned *before* the+ `mcp auth=` log line, so a rejected token logged nothing and the logs showed+ only `auth=anonymous`. Reading them produced the confident, wrong conclusion+ that no token had arrived. A log that cannot distinguish "no credential" from+ "credential refused" is worse than no log, because it is believed. Logging now+ happens first and records the reason and observed audience.+3. **`adminToken` required in the schema** made OAuth writes impossible while the+ code read as correct.