Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 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

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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.