π 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
feat(x-gateway): public and private swarm channels (ADR-386) (#3261)
rUv90bff10f150c
diff --git a/plugins/ruflo-x-gateway/.claude-plugin/plugin.json b/plugins/ruflo-x-gateway/.claude-plugin/plugin.jsonindex e70071d09c..eb8b85fb2b 100644--- a/plugins/ruflo-x-gateway/.claude-plugin/plugin.json+++ b/plugins/ruflo-x-gateway/.claude-plugin/plugin.json@@ -1,7 +1,7 @@{"name": "ruflo-x-gateway","description": "x.ruv.io gateway service β an MCP server (Streamable HTTP at /mcp) exposing ruflo swarm FEDERATION and CLAIMS tools over an open, membership-gated, signed Nostr relay (buzz-relay). Tools: federation_identity/join/publish/sync, claims_issue/release/status. Resources: ruv://federation/registry, ruv://swarm/roster, ruv://claims/board. Every coordination message is a signed Nostr event (verifiable authorship); the relay gates membership + NIP-42 auth for security. Deployed to Cloud Run behind x.ruv.io.",- "version": "0.3.2",+ "version": "0.4.0","author": { "name": "ruvnet", "url": "https://github.com/ruvnet" },"homepage": "https://github.com/ruvnet/ruflo","license": "MIT",diff --git a/plugins/ruflo-x-gateway/package.json b/plugins/ruflo-x-gateway/package.jsonindex f50a3a7537..cfd13d4849 100644--- a/plugins/ruflo-x-gateway/package.json+++ b/plugins/ruflo-x-gateway/package.json@@ -1,6 +1,6 @@{"name": "@ruflo/x-gateway",- "version": "0.3.2",+ "version": "0.4.0","private": true,"type": "module","description": "x.ruv.io gateway β MCP server for ruflo swarm federation + claims over a signed, membership-gated Nostr relay. Exposes /mcp tools and ruv:// resources.",diff --git a/plugins/ruflo-x-gateway/src/channels.mjs b/plugins/ruflo-x-gateway/src/channels.mjsnew file mode 100644index 0000000000..51c4c8e5bf--- /dev/null+++ b/plugins/ruflo-x-gateway/src/channels.mjs@@ -0,0 +1,78 @@+/**+ * ADR-386 β public and private swarm channels.+ *+ * A channel is one extra tag on an ordinary swarm event: ['c', channelId].+ * NOT ['h', β¦]: buzz-relay reserves `h` for NIP-29-style groups and refuses a REQ+ * filtered on #h with "restricted: not a channel member", so an h-tagged event can+ * be published but never read back. `c` is indexed and unrestricted.+ * public channelId = `pub:<name>` content = plaintext JSON, k = msgType+ * private channelId = `prv:<16 hex>` content = NIP-44 v2 ciphertext, k = 'enc'+ *+ * Private-channel keys are generated and held by CLIENTS. The gateway seals+ * nothing on anyone's behalf and stores no channel key: it filters by `h` and+ * relays ciphertext. See ADR-386 "the gateway is not a custodian".+ */+import { createHash, randomBytes } from 'node:crypto';+import { nip44 } from 'nostr-tools';++export const CHANNEL_NAME_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/;+export const CHANNEL_ID_RE = /^(pub:[a-z0-9][a-z0-9._-]{0,63}|prv:[0-9a-f]{16})$/;+export const ENC_TYPE = 'enc';++/** Public channel id for a human-readable name. */+export function publicChannelId(name) {+ if (!CHANNEL_NAME_RE.test(String(name))) throw new Error('channel name must match [a-z0-9][a-z0-9._-]{0,63}');+ return `pub:${name}`;+}++/** Opaque private channel id derived from the key, so the name never reaches the wire. */+export function privateChannelId(channelKey) {+ const k = toKey(channelKey);+ return `prv:${createHash('sha256').update(k).digest('hex').slice(0, 16)}`;+}++/** A fresh 32-byte channel key (hex). Generated client-side, never by the gateway. */+export function newChannelKey() { return randomBytes(32).toString('hex'); }++function toKey(k) {+ const b = typeof k === 'string' ? Buffer.from(k, 'hex') : Buffer.from(k);+ if (b.length !== 32) throw new Error('channel key must be 32 bytes (64 hex)');+ return b;+}++/** Encrypt a message body under the channel key (NIP-44 v2). */+export function sealMessage(channelKey, body) {+ return nip44.v2.encrypt(JSON.stringify(body), toKey(channelKey));+}++/** Decrypt a channel message. Returns null when this key cannot open it. */+export function openMessage(channelKey, ciphertext) {+ try { return JSON.parse(nip44.v2.decrypt(ciphertext, toKey(channelKey))); } catch { return null; }+}++/**+ * Seal a channel key to one member: NIP-44 under the ECDH conversation key+ * between the granter's secret key and the member's pubkey. Only that member opens it.+ */+export function sealChannelKey(granterSk, memberPubkey, channelKey) {+ if (!/^[0-9a-f]{64}$/i.test(String(memberPubkey))) throw new Error('member pubkey must be 64 hex');+ const conv = nip44.v2.utils.getConversationKey(granterSk, memberPubkey);+ return nip44.v2.encrypt(toKey(channelKey).toString('hex'), conv);+}++/** Open a sealed channel key with the member's own secret key. Returns hex, or null. */+export function openChannelKey(memberSk, granterPubkey, sealed) {+ try {+ const conv = nip44.v2.utils.getConversationKey(memberSk, granterPubkey);+ const hex = nip44.v2.decrypt(sealed, conv);+ return /^[0-9a-f]{64}$/.test(hex) ? hex : null;+ } catch { return null; }+}++/** Tags for a channel event. Private channels hide the message type behind k=enc. */+export function channelTags(channelId, msgType, isPrivate) {+ if (!CHANNEL_ID_RE.test(String(channelId))) throw new Error('bad channel id');+ return [['t', 'ruflo-swarm'], ['c', String(channelId)], ['k', isPrivate ? ENC_TYPE : String(msgType)]];+}++export function isPrivateChannel(channelId) { return String(channelId).startsWith('prv:'); }diff --git a/plugins/ruflo-x-gateway/src/nostr-federation.mjs b/plugins/ruflo-x-gateway/src/nostr-federation.mjsindex 586d8e2fef..bcfba7f3ab 100644--- a/plugins/ruflo-x-gateway/src/nostr-federation.mjs+++ b/plugins/ruflo-x-gateway/src/nostr-federation.mjs@@ -114,3 +114,66 @@ export async function fetchManyOn(relayUrl, sk, filters) {// Tiny TTL cache for hot read paths (roster/claims) to absorb bursts without re-dialing the relay.const cache = new Map();export async function cached(key, ttlMs, fn) { const c = cache.get(key); const now = Date.now(); if (c && now - c.at < ttlMs) return c.v; const v = await fn(); cache.set(key, { v, at: now }); return v; }++// ---- ADR-386 channels ----+// A channel scopes events with a ['c', channelId] tag (`h` is reserved by the relay for NIP-29 groups). Private channels carry+// NIP-44 ciphertext in `content` and hide the type behind k='enc'; the gateway+// holds no channel keys and never decrypts them.++/** Publish an already-shaped channel event (tags built by channels.mjs). */+export async function publishTagged(relayUrl, sk, tags, content) {+ const bytes = Buffer.byteLength(String(content));+ if (bytes > MAX_PAYLOAD_BYTES) throw new Error(`content too large (${bytes} > ${MAX_PAYLOAD_BYTES} bytes)`);+ const ws = await connectAuthed(relayUrl, sk);+ const ev = finalizeEvent({ kind: SWARM_KIND, created_at: Math.floor(Date.now() / 1000), tags, content: String(content) }, sk);+ return new Promise((resolve, reject) => {+ const timer = setTimeout(() => { try { ws.close(); } catch {} reject(new Error('publish timeout')); }, 15000);+ ws.on('message', (data) => {+ const m = JSON.parse(data.toString());+ if (m[0] === 'OK' && m[1] === ev.id) { clearTimeout(timer); try { ws.close(); } catch {}+ m[2] ? resolve(ev.id) : reject(new Error(m[3] || 'publish rejected')); }+ });+ ws.send(JSON.stringify(['EVENT', ev]));+ });+}++/**+ * Fetch a channel's recent events. Content is returned VERBATIM β parsed for a+ * public channel, left as ciphertext for a private one, because only a key+ * holder can open it and the gateway is not one.+ */+export async function fetchChannel(relayUrl, sk, { channelId, sinceSeconds = 3600, limit = 100, recipient } = {}) {+ const ws = await connectAuthed(relayUrl, sk);+ const filter = { kinds: [SWARM_KIND], '#t': [SWARM_TAG], since: Math.floor(Date.now() / 1000) - sinceSeconds, limit };+ if (channelId) filter['#c'] = [String(channelId)];+ if (recipient) filter['#p'] = [String(recipient)];+ const out = [];+ return new Promise((resolve) => {+ const timer = setTimeout(() => { try { ws.close(); } catch {} resolve(out); }, 12000);+ ws.on('message', (data) => {+ const m = JSON.parse(data.toString());+ if (m[0] === 'EVENT' && verifyEvent(m[2])) {+ const e = m[2];+ const h = e.tags.find((t) => t[0] === 'c')?.[1];+ const k = e.tags.find((t) => t[0] === 'k')?.[1];+ const rec = { id: e.id, pubkey: e.pubkey, created_at: e.created_at, channel: h, k };+ if (k === 'enc') out.push({ ...rec, encrypted: true, content: e.content });+ else { let body; try { body = JSON.parse(e.content); } catch { body = { raw: e.content }; } out.push({ ...rec, ...body }); }+ } else if (m[0] === 'EOSE') { clearTimeout(timer); try { ws.close(); } catch {} resolve(out); }+ });+ ws.send(JSON.stringify(['REQ', 'ruflo-channel', filter]));+ });+}++/** Channel ids seen recently, with counts. Private ids are opaque by construction. */+export async function listChannels(relayUrl, sk, { sinceSeconds = 86400, limit = 500 } = {}) {+ const evs = await fetchChannel(relayUrl, sk, { sinceSeconds, limit });+ const seen = new Map();+ for (const e of evs) {+ if (!e.channel) continue;+ const c = seen.get(e.channel) || { channel: e.channel, visibility: e.channel.startsWith('prv:') ? 'private' : 'public', messages: 0, publishers: new Set(), lastSeen: 0 };+ c.messages++; c.publishers.add(e.pubkey); c.lastSeen = Math.max(c.lastSeen, e.created_at); seen.set(e.channel, c);+ }+ return [...seen.values()].map((c) => ({ ...c, publishers: c.publishers.size, lastSeen: new Date(c.lastSeen * 1000).toISOString() }))+ .sort((a, b) => (a.lastSeen < b.lastSeen ? 1 : -1));+}diff --git a/plugins/ruflo-x-gateway/src/server.mjs b/plugins/ruflo-x-gateway/src/server.mjsindex c2d409e9f7..b714d4e681 100644--- a/plugins/ruflo-x-gateway/src/server.mjs+++ b/plugins/ruflo-x-gateway/src/server.mjs@@ -10,7 +10,8 @@ import { createServer } from 'node:http';import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';import { z } from 'zod';-import { loadIdentity, publish, fetchRecent, fetchManyOn, cached } from './nostr-federation.mjs';+import { loadIdentity, publish, fetchRecent, fetchManyOn, cached, publishTagged, fetchChannel, listChannels } from './nostr-federation.mjs';+import { publicChannelId, channelTags, isPrivateChannel, CHANNEL_ID_RE } from './channels.mjs';import { reduceClaims } from './claims.mjs';import { rateLimited, readBody, securityHeaders, checkAdmin } from './security.mjs';import { mintInvite, admitMember } from './relay-admin.mjs';@@ -29,7 +30,7 @@ export function createGateway({ relay, keyFile, port } = {}) {const adminArg = { adminToken: z.string().describe('Gateway admin token (RUFLO_ADMIN_TOKEN). Required for any write made with the gateway identity.') };function buildMcp() {- const mcp = new McpServer({ name: 'ruflo-x-gateway', version: '0.3.2' });+ const mcp = new McpServer({ name: 'ruflo-x-gateway', version: '0.4.0' });// ---- open reads ----mcp.tool('federation_identity', 'Gateway Nostr pubkey + relay. Open read.', {}, async () => text({ pubkey, relay: RELAY, httpBase: HTTP_BASE }));mcp.tool('federation_sync', 'Fetch recent verified swarm coordination messages (#t=ruflo-swarm). Open read; optional type filter.',@@ -56,6 +57,27 @@ export function createGateway({ relay, keyFile, port } = {}) {mcp.tool('federation_admit', 'Admit a pubkey as a relay member directly (NIP-43 kind 9030). Admin-gated.',{ pubkey: z.string(), role: z.enum(['member', 'admin']).optional(), ...adminArg },gated(async ({ pubkey: pk, role }) => text(await admitMember(RELAY, sk, pk, role))));+ // ---- ADR-386 channels ----+ mcp.tool('channel_list', 'List swarm channels seen recently, with visibility, message count and publisher count. Open read. Public channel ids carry their name (pub:<name>); private ids are opaque (prv:<hex>) and reveal nothing about the topic. Use when you want to find where coordination is happening before reading a stream. Reading the flat firehose with federation_sync instead is wrong once channels are in use, because it mixes unrelated work and cannot show you private traffic exists at all.',+ { sinceSeconds: z.number().optional(), limit: z.number().optional() },+ async (a) => text({ channels: await listChannels(RELAY, sk, a) }));+ mcp.tool('channel_sync', 'Read one channel. Open read. A public channel returns parsed JSON messages. A PRIVATE channel returns NIP-44 ciphertext verbatim with encrypted:true β the gateway holds no channel keys and cannot decrypt, by design (ADR-386); open it client-side with `ruflo federation channel read`. Use when you know the channel id. Asking the gateway to decrypt is wrong because a gateway that could would be a custodian of every private channel on the service.',+ { channel: z.string().describe('Channel id: pub:<name> or prv:<16 hex>'), sinceSeconds: z.number().optional(), limit: z.number().optional() },+ async ({ channel, sinceSeconds, limit }) => {+ if (!CHANNEL_ID_RE.test(String(channel))) throw new Error('channel must be pub:<name> or prv:<16 hex>');+ const messages = await fetchChannel(RELAY, sk, { channelId: channel, sinceSeconds, limit });+ return text({ channel, visibility: isPrivateChannel(channel) ? 'private' : 'public', count: messages.length, messages });+ });+ mcp.tool('channel_publish', 'Publish a message to a PUBLIC channel as the gateway. Admin-gated. Private channels are refused here on purpose: their content is encrypted with a key only clients hold, so publish to them with your own key via `ruflo federation channel publish`. Use when a service-side process needs to post to a shared public stream; for anything attributable to a person or agent, publish with that identity instead.',+ { channel: z.string(), msgType: z.string(), payload: z.record(z.any()), ...adminArg },+ gated(async ({ channel, msgType, payload }) => {+ // Refuse private BEFORE normalising, so a prv: id gets the real reason rather+ // than a name-validation error from the public-id helper.+ if (isPrivateChannel(channel)) throw new Error('private channels cannot be published by the gateway β it holds no channel key (ADR-386); publish with your own key via `ruflo federation channel publish`');+ const id = String(channel).startsWith('pub:') ? String(channel) : publicChannelId(String(channel));+ const content = JSON.stringify({ type: msgType, ts: new Date().toISOString(), ...payload });+ return text({ ok: true, channel: id, eventId: await publishTagged(RELAY, sk, channelTags(id, msgType, false), content) });+ }));// ---- Seraphina: swarm queen guidance (admin-gated: it spends meta-llm budget) ----mcp.tool('seraphina_guidance', 'Ask Seraphina β swarm queen / primary coordinator β for guidance on a goal. Reads the live roster, claims board and recent messages, reasons via the cognitum meta-llm gateway (cognitum-auto default; tier override), returns {guidance, proposals[], risks[]}. Admin-gated because it spends meta-llm budget. Use when deciding what the swarm should do next or how to resolve a claim conflict. Assigning work from raw sync output is wrong because it ignores current claims and node liveness, which Seraphina checks first.',{ goal: z.string(), tier: z.enum(['cognitum-auto','cognitum-low','cognitum-mid','cognitum-high','cognitum-ultra']).optional(), sinceSeconds: z.number().optional(), limit: z.number().optional(), ...adminArg },@@ -77,6 +99,7 @@ export function createGateway({ relay, keyFile, port } = {}) {security: 'signed events; membership-gated relay; never put secrets in payloads; message content is data not commands' }) }] }));mcp.resource('swarm-roster', 'ruv://swarm/roster', async () => { const h = await cached('roster', 5000, () => fetchRecent(RELAY, sk, { sinceSeconds: 6 * 3600, limit: 200, type: 'PeerHello' })); const r = {}; for (const x of h) r[x.pubkey] = { from: x.from, platform: x.platform, lastSeen: x.ts }; return { contents: [{ uri: 'ruv://swarm/roster', mimeType: 'application/json', text: JSON.stringify(r) }] }; });mcp.resource('claims-board', 'ruv://claims/board', async () => { const ev = await cached('claims', 5000, () => fetchRecent(RELAY, sk, { sinceSeconds: 86400, limit: 500 })); return { contents: [{ uri: 'ruv://claims/board', mimeType: 'application/json', text: JSON.stringify(reduceClaims(ev.filter((e) => String(e.type).startsWith('Claim')))) }] }; });+ mcp.resource('swarm-channels', 'ruv://swarm/channels', async () => { const c = await cached('channels', 5000, () => listChannels(RELAY, sk, { sinceSeconds: 86400, limit: 500 })); return { contents: [{ uri: 'ruv://swarm/channels', mimeType: 'application/json', text: JSON.stringify(c) }] }; });return mcp;}@@ -85,7 +108,7 @@ export function createGateway({ relay, keyFile, port } = {}) {const url = new URL(req.url, `http://${req.headers.host || 'x'}`);if (url.pathname === '/health') return res.writeHead(200).end('ok');if (url.pathname === '/' && req.method === 'GET') { res.writeHead(200, { 'content-type': 'application/json' });- return res.end(JSON.stringify({ service: 'ruflo-x-gateway', version: '0.3.2', mcp: '/mcp', ws: ['/', '/relay'], relay: RELAY, canonicalRelay: RELAY, legacyRelay: LEGACY_RELAY, authNote: 'When connecting via wss://x.ruv.io, sign the NIP-42 AUTH `relay` tag with canonicalRelay (the relay verifies it strictly).', gatewayPubkey: pubkey, resources: ['ruv://federation/registry', 'ruv://swarm/roster', 'ruv://claims/board'] })); }+ return res.end(JSON.stringify({ service: 'ruflo-x-gateway', version: '0.4.0', mcp: '/mcp', ws: ['/', '/relay'], relay: RELAY, canonicalRelay: RELAY, legacyRelay: LEGACY_RELAY, authNote: 'When connecting via wss://x.ruv.io, sign the NIP-42 AUTH `relay` tag with canonicalRelay (the relay verifies it strictly).', gatewayPubkey: pubkey, resources: ['ruv://federation/registry', 'ruv://swarm/roster', 'ruv://claims/board', 'ruv://swarm/channels'] })); }if (url.pathname === '/mcp') {if (rateLimited(req)) return res.writeHead(429, { 'content-type': 'application/json' }).end('{"error":"rate limited"}');let body; try { body = await readBody(req); } catch { return res.writeHead(413, { 'content-type': 'application/json' }).end('{"error":"payload too large"}'); }diff --git a/plugins/ruflo-x-gateway/test/gateway.test.mjs b/plugins/ruflo-x-gateway/test/gateway.test.mjsindex eb1825f4e8..6977a55002 100644--- a/plugins/ruflo-x-gateway/test/gateway.test.mjs+++ b/plugins/ruflo-x-gateway/test/gateway.test.mjs@@ -94,3 +94,65 @@ test('hardening: publish bounds, bucket eviction, ws maxPayload/404, fetchManyOnwss.close();assert.equal(out.length, 3); assert.equal(handshakes, 1); assert.equal(reqs, 3);});++// ---- ADR-386 channels ----+test('channels: ids, seal/open, non-member cannot open, type hidden on private', async () => {+ const c = await import('../src/channels.mjs');+ const { generateSecretKey, getPublicKey } = await import('nostr-tools/pure');++ // public ids carry the name; private ids are derived from the key and carry nothing+ assert.equal(c.publicChannelId('release-3-41'), 'pub:release-3-41');+ assert.throws(() => c.publicChannelId('Bad Name'), /channel name/);+ const key = c.newChannelKey();+ const id = c.privateChannelId(key);+ assert.match(id, /^prv:[0-9a-f]{16}$/);+ assert.equal(c.privateChannelId(key), id, 'id is deterministic in the key');+ assert.notEqual(c.privateChannelId(c.newChannelKey()), id);+ assert.ok(c.isPrivateChannel(id) && !c.isPrivateChannel('pub:x'));+ assert.throws(() => c.privateChannelId('abcd'), /32 bytes/);++ // message sealing round trip, and a wrong key opens nothing+ const ct = c.sealMessage(key, { type: 'Task', taskId: 't-1' });+ assert.ok(!/taskId|Task/.test(ct), 'ciphertext must not leak the body');+ assert.deepEqual(c.openMessage(key, ct), { type: 'Task', taskId: 't-1' });+ assert.equal(c.openMessage(c.newChannelKey(), ct), null);++ // key grant: only the addressed member opens it+ const granter = generateSecretKey(), member = generateSecretKey(), outsider = generateSecretKey();+ const sealed = c.sealChannelKey(granter, getPublicKey(member), key);+ assert.equal(c.openChannelKey(member, getPublicKey(granter), sealed), key);+ assert.equal(c.openChannelKey(outsider, getPublicKey(granter), sealed), null);+ assert.throws(() => c.sealChannelKey(granter, 'nothex', key), /64 hex/);++ // tags: private hides the message type behind k=enc, public keeps it+ assert.deepEqual(c.channelTags(id, 'Task', true), [['t', 'ruflo-swarm'], ['c', id], ['k', 'enc']]);+ assert.deepEqual(c.channelTags('pub:ops', 'Status', false), [['t', 'ruflo-swarm'], ['c', 'pub:ops'], ['k', 'Status']]);+ assert.throws(() => c.channelTags('bogus', 'Task', false), /bad channel id/);+});++test('channels: tools are registered, private publish refused, ids validated', async () => {+ process.env.RUFLO_ADMIN_TOKEN = 'test-admin-token';+ const gw = createGateway({ relay: 'ws://127.0.0.1:1', keyFile: '/tmp/x-gw-ch-' + Date.now() + '.key', port: 0 });+ const port = await gw.listen(0); const base = `http://127.0.0.1:${port}`;+ const rpc = (m) => fetch(base + '/mcp', { method: 'POST', headers: { 'content-type': 'application/json', accept: 'application/json, text/event-stream' }, body: JSON.stringify(m) }).then((r) => r.text());+ const list = await rpc({ jsonrpc: '2.0', id: 1, method: 'tools/list', params: {} });+ for (const n of ['channel_list', 'channel_sync', 'channel_publish']) assert.ok(list.includes(`"name":"${n}"`), n);+ assert.ok(list.includes('Use when'), 'ADR-112 descriptions');++ // channel_publish is admin-gated like every other gateway-identity write+ const noTok = await rpc({ jsonrpc: '2.0', id: 2, method: 'tools/call', params: { name: 'channel_publish', arguments: { channel: 'pub:ops', msgType: 'Status', payload: {} } } });+ assert.match(noTok, /admin token required|invalid_type|Required/);++ // the gateway refuses to publish to a private channel: it holds no channel key+ const priv = await rpc({ jsonrpc: '2.0', id: 3, method: 'tools/call', params: { name: 'channel_publish', arguments: { channel: 'prv:0123456789abcdef', msgType: 'Status', payload: {}, adminToken: 'test-admin-token' } } });+ assert.match(priv, /holds no channel key|private channels cannot/);++ // a malformed id is rejected before any relay work+ const bad = await rpc({ jsonrpc: '2.0', id: 4, method: 'tools/call', params: { name: 'channel_sync', arguments: { channel: 'not a channel' } } });+ assert.match(bad, /pub:<name> or prv:/);++ const info = await (await fetch(base + '/')).json();+ assert.ok(info.resources.includes('ruv://swarm/channels'));+ assert.equal(info.version, '0.4.0');+ gw.server.close();+});diff --git a/v3/@claude-flow/cli/__tests__/x-federation-channels.test.ts b/v3/@claude-flow/cli/__tests__/x-federation-channels.test.tsnew file mode 100644index 0000000000..67863ad871--- /dev/null+++ b/v3/@claude-flow/cli/__tests__/x-federation-channels.test.ts@@ -0,0 +1,92 @@+/**+ * ADR-386 client-side channels: key custody, id derivation, grant round trip,+ * and the tool contract. Crypto cases skip when the optional `nostr-tools`+ * dependency is absent (the root Test Suite installs only root dependencies).+ */+import { describe, it, expect } from 'vitest';+import { mkdtempSync, statSync, existsSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import {+ publicChannelId, privateChannelId, newChannelKey, isPrivateChannel,+ readStore, writeStore, xFederationChannelTools, CHANNEL_ID_RE,+} from '../src/mcp-tools/x-federation-channels.js';++const nt: any = await import('nostr-tools/pure').catch(() => null);+const n44: any = await import('nostr-tools').then((m: any) => m.nip44).catch(() => null);++describe('channel ids (ADR-386)', () => {+ it('public ids carry the name; private ids are derived from the key and carry nothing', () => {+ expect(publicChannelId('release-3-41')).toBe('pub:release-3-41');+ expect(() => publicChannelId('Bad Name')).toThrow(/channel name/);+ const key = newChannelKey();+ const id = privateChannelId(key);+ expect(id).toMatch(/^prv:[0-9a-f]{16}$/);+ expect(privateChannelId(key)).toBe(id);+ expect(privateChannelId(newChannelKey())).not.toBe(id);+ expect(CHANNEL_ID_RE.test(id)).toBe(true);+ expect(isPrivateChannel(id)).toBe(true);+ expect(isPrivateChannel('pub:ops')).toBe(false);+ expect(() => privateChannelId('abcd')).toThrow(/32 bytes/);+ });+});++describe('local channel key store', () => {+ it('writes 0600 and round-trips; a missing file reads as empty, not a throw', () => {+ const f = join(mkdtempSync(join(tmpdir(), 'ch-')), 'channels.json');+ expect(readStore(f)).toEqual({});+ const key = newChannelKey(); const id = privateChannelId(key);+ writeStore({ [id]: { key, name: 'ops', at: new Date().toISOString() } }, f);+ expect(existsSync(f)).toBe(true);+ expect(statSync(f).mode & 0o777).toBe(0o600);+ expect(readStore(f)[id].key).toBe(key);+ });+});++describe.skipIf(!nt || !n44)('grant sealing', () => {+ it('only the addressed pubkey can open a sealed channel key', () => {+ const key = newChannelKey();+ const granter = nt.generateSecretKey(), member = nt.generateSecretKey(), outsider = nt.generateSecretKey();+ const sealed = n44.v2.encrypt(key, n44.v2.utils.getConversationKey(granter, nt.getPublicKey(member)));+ expect(sealed).not.toContain(key);+ const opened = n44.v2.decrypt(sealed, n44.v2.utils.getConversationKey(member, nt.getPublicKey(granter)));+ expect(opened).toBe(key);+ expect(privateChannelId(opened)).toBe(privateChannelId(key));+ expect(() => n44.v2.decrypt(sealed, n44.v2.utils.getConversationKey(outsider, nt.getPublicKey(granter)))).toThrow();+ });++ it('a message sealed under the channel key is opaque without it', () => {+ const key = Uint8Array.from(Buffer.from(newChannelKey(), 'hex'));+ const ct = n44.v2.encrypt(JSON.stringify({ type: 'Task', taskId: 'secret-1' }), key);+ expect(ct).not.toContain('secret-1');+ expect(JSON.parse(n44.v2.decrypt(ct, key)).taskId).toBe('secret-1');+ const other = Uint8Array.from(Buffer.from(newChannelKey(), 'hex'));+ expect(() => n44.v2.decrypt(ct, other)).toThrow();+ });+});++describe('tool contract', () => {+ const byName = (n: string) => xFederationChannelTools.find((t) => t.name === n)!;++ it('registers the six client channel tools with ADR-112 descriptions', () => {+ for (const n of ['create', 'grant', 'accept', 'publish', 'read', 'list']) {+ const t = byName(`x_federation_channel_${n}`);+ expect(t, n).toBeTruthy();+ expect(t.description).toMatch(/Use when|Use this/);+ expect(t.description).toMatch(/wrong/);+ }+ });++ it('rejects malformed channel ids and non-private grants before any network call', async () => {+ await expect(byName('x_federation_channel_read').handler({ channel: 'not a channel' } as never, {} as never)).rejects.toThrow(/pub:<name> or prv:/);+ await expect(byName('x_federation_channel_publish').handler({ channel: 'nope', msgType: 'X', payload: {} } as never, {} as never)).rejects.toThrow(/pub:<name> or prv:/);+ await expect(byName('x_federation_channel_grant').handler({ channel: 'pub:ops', pubkey: 'a'.repeat(64) } as never, {} as never)).rejects.toThrow(/only private channels/);+ await expect(byName('x_federation_channel_grant').handler({ channel: 'prv:0123456789abcdef', pubkey: 'zz' } as never, {} as never)).rejects.toThrow(/64 hex/);+ });++ it('creating a public channel touches no key material', async () => {+ const r = await byName('x_federation_channel_create').handler({ name: 'ops', visibility: 'public' } as never, {} as never) as Record<string, unknown>;+ expect(r.channel).toBe('pub:ops');+ expect(r).not.toHaveProperty('keyStoredAt');+ });+});diff --git a/v3/@claude-flow/cli/src/commands/federation.ts b/v3/@claude-flow/cli/src/commands/federation.tsindex ece55183e0..ac14f1aba4 100644--- a/v3/@claude-flow/cli/src/commands/federation.ts+++ b/v3/@claude-flow/cli/src/commands/federation.ts@@ -51,6 +51,36 @@ export const federationCommand: Command = {options: [{ name: 'type', description: 'Message type (Status|Task|Result|β¦)', type: 'string', required: true }, { name: 'payload', description: 'JSON payload', type: 'string', required: true }],action: (ctx) => { let payload: unknown; try { payload = JSON.parse(String(ctx.flags.payload)); } catch { output.printError('--payload must be JSON'); return Promise.resolve({ success: false, exitCode: 1 }); }return run(ctx, 'x_federation_publish', { msgType: ctx.flags.type, payload }, 'Published'); } },+ { name: 'channel', description: 'Public and private swarm channels (ADR-386). Private channels are encrypted with a key only this machine holds.',+ options: [+ { name: 'action', description: 'create|grant|accept|publish|read|list', type: 'string', required: true },+ { name: 'name', description: 'Channel name (create)', type: 'string' },+ { name: 'visibility', description: 'public|private (create)', type: 'string' },+ { name: 'channel', description: 'Channel id: pub:<name> or prv:<16 hex>', type: 'string' },+ { name: 'pubkey', description: '64-hex member pubkey (grant)', type: 'string' },+ { name: 'type', description: 'Message type (publish)', type: 'string' },+ { name: 'payload', description: 'JSON payload (publish)', type: 'string' },+ { name: 'since', description: 'Look-back seconds (read|accept)', type: 'number' },+ { name: 'limit', description: 'Max messages (read)', type: 'number' },+ ],+ action: (ctx) => {+ const a = String(ctx.flags.action);+ switch (a) {+ case 'create': return run(ctx, 'x_federation_channel_create', { name: ctx.flags.name, visibility: ctx.flags.visibility ?? 'public' }, 'Channel created');+ case 'grant': return run(ctx, 'x_federation_channel_grant', { channel: ctx.flags.channel, pubkey: ctx.flags.pubkey }, 'Channel granted');+ case 'accept': return run(ctx, 'x_federation_channel_accept', { sinceSeconds: ctx.flags.since }, 'Grants accepted');+ case 'read': return run(ctx, 'x_federation_channel_read', { channel: ctx.flags.channel, sinceSeconds: ctx.flags.since, limit: ctx.flags.limit }, 'Channel messages');+ case 'list': return run(ctx, 'x_federation_channel_list', {}, 'Channel keys held');+ case 'publish': {+ let payload: unknown;+ try { payload = JSON.parse(String(ctx.flags.payload)); } catch { output.printError('--payload must be JSON'); return Promise.resolve({ success: false, exitCode: 1 }); }+ return run(ctx, 'x_federation_channel_publish', { channel: ctx.flags.channel, msgType: ctx.flags.type, payload }, 'Published to channel');+ }+ default:+ output.printError('--action must be create|grant|accept|publish|read|list');+ return Promise.resolve({ success: false, exitCode: 1 });+ }+ } },],- action: async (ctx) => { output.printInfo('Usage: ruflo federation <join|sync|roster|claims|registry|invite|admit|publish>'); void ctx; return { success: true }; },+ action: async (ctx) => { output.printInfo('Usage: ruflo federation <join|sync|roster|claims|registry|invite|admit|publish|channel>'); void ctx; return { success: true }; },};diff --git a/v3/@claude-flow/cli/src/mcp-client.ts b/v3/@claude-flow/cli/src/mcp-client.tsindex 808d106968..38a5bf3663 100644--- a/v3/@claude-flow/cli/src/mcp-client.ts+++ b/v3/@claude-flow/cli/src/mcp-client.ts@@ -71,6 +71,7 @@ import { agentbbsTools } from './mcp-tools/agentbbs-tools.js';import { xFederationTools } from './mcp-tools/x-federation-tools.js';import { seraphinaTools } from './mcp-tools/seraphina-tools.js';import { xFederationJoinTools } from './mcp-tools/x-federation-join.js';+import { xFederationChannelTools } from './mcp-tools/x-federation-channels.js';// ADR-164 Phase 2 β Business-pod template validation (pure local, no optional deps).import { businessPodTools } from './mcp-tools/business-pod-tools.js';// ADR-164 Phase 4 Β§5.1.8 β http_fetch MCP tool (secure-by-default HTTP probe@@ -184,6 +185,7 @@ registerTools([...xFederationTools,...seraphinaTools,...xFederationJoinTools,+ ...xFederationChannelTools,// ADR-164 Phase 2 + Phase 3 β business_pod_validate + business_pod_route_backend// (2 tools, no optional dep β schema validator + Β§3.4 domain-affinity router)...businessPodTools,diff --git a/v3/@claude-flow/cli/src/mcp-tools/index.ts b/v3/@claude-flow/cli/src/mcp-tools/index.tsindex 700609ef3d..6813798fa5 100644--- a/v3/@claude-flow/cli/src/mcp-tools/index.ts+++ b/v3/@claude-flow/cli/src/mcp-tools/index.ts@@ -63,6 +63,7 @@ export { agentbbsTools } from './agentbbs-tools.js';export { xFederationTools } from './x-federation-tools.js';export { seraphinaTools } from './seraphina-tools.js';export { xFederationJoinTools } from './x-federation-join.js';+export { xFederationChannelTools } from './x-federation-channels.js';// ADR-164 Phase 2 β Business-pod template validationexport { businessPodTools } from './business-pod-tools.js';// ADR-164 Phase 4 Β§5.1.8 β http_fetch (secure-by-default HTTP probe)diff --git a/v3/@claude-flow/cli/src/mcp-tools/x-federation-channels.ts b/v3/@claude-flow/cli/src/mcp-tools/x-federation-channels.tsnew file mode 100644index 0000000000..c513cd7c62--- /dev/null+++ b/v3/@claude-flow/cli/src/mcp-tools/x-federation-channels.ts@@ -0,0 +1,246 @@+/**+ * ADR-386 β public and private swarm channels, client side.+ *+ * Channel keys live HERE, never on the gateway. A private channel is a 32-byte+ * key you generate; messages are NIP-44 v2 ciphertext under it, and the channel+ * id (`prv:<16 hex>`) is derived from the key so the name never reaches the wire.+ * You grant access by sealing the key to a member's pubkey (ECDH), which only+ * they can open. The gateway relays ciphertext and cannot decrypt it.+ *+ * `nostr-tools` is an optional dependency; every tool degrades with an install+ * hint rather than throwing at load.+ */+import type { MCPTool } from './types.js';+import { createHash, randomBytes } from 'node:crypto';+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';+import { homedir } from 'node:os';+import { join, dirname } from 'node:path';+import { loadOrCreateKey } from './x-federation-join.js';++// ADR-125 precedence: tool args > env var > default.+const RELAY_WS = (o?: string) => o || process.env.RUFLO_X_RELAY_WS || 'wss://relay.ruv.io';+const KEY_FILE = () => process.env.RUFLO_NOSTR_KEY_FILE || join(homedir(), '.ruflo', 'nostr.key');+const STORE_FILE = () => process.env.RUFLO_CHANNELS_FILE || join(homedir(), '.ruflo', 'channels.json');++export const CHANNEL_NAME_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/;+export const CHANNEL_ID_RE = /^(pub:[a-z0-9][a-z0-9._-]{0,63}|prv:[0-9a-f]{16})$/;++type Nt = {+ generateSecretKey: () => Uint8Array; getPublicKey: (sk: Uint8Array) => string;+ finalizeEvent: (t: Record<string, unknown>, sk: Uint8Array) => Record<string, unknown> & { id: string };+};+type Nip44 = { v2: { encrypt: (p: string, k: Uint8Array) => string; decrypt: (c: string, k: Uint8Array) => string; utils: { getConversationKey: (sk: Uint8Array, pk: string) => Uint8Array } } };+async function loadTools(): Promise<{ nt: Nt; nip44: Nip44 } | null> {+ try {+ const nt = (await import('nostr-tools/pure')) as unknown as Nt;+ const { nip44 } = (await import('nostr-tools')) as unknown as { nip44: Nip44 };+ return { nt, nip44 };+ } catch { return null; }+}+const degraded = () => ({ degraded: true, reason: 'nostr-tools not installed', hint: 'npm i nostr-tools (secp256k1 + NIP-44 are not in node:crypto)' });++/** Locally cached channel keys, 0600. Losing this file loses the channels in it β by design. */+export type ChannelStore = Record<string, { key: string; name?: string; grantedBy?: string; at: string }>;+export function readStore(file = STORE_FILE()): ChannelStore {+ if (!existsSync(file)) return {};+ try { return JSON.parse(readFileSync(file, 'utf8')) as ChannelStore; } catch { return {}; }+}+export function writeStore(store: ChannelStore, file = STORE_FILE()): void {+ mkdirSync(dirname(file), { recursive: true, mode: 0o700 });+ writeFileSync(file, JSON.stringify(store, null, 2), { mode: 0o600 });+}+export function publicChannelId(name: string): string {+ if (!CHANNEL_NAME_RE.test(String(name))) throw new Error('channel name must match [a-z0-9][a-z0-9._-]{0,63}');+ return `pub:${name}`;+}+export function privateChannelId(keyHex: string): string {+ const k = Buffer.from(keyHex, 'hex');+ if (k.length !== 32) throw new Error('channel key must be 32 bytes (64 hex)');+ return `prv:${createHash('sha256').update(k).digest('hex').slice(0, 16)}`;+}+export function newChannelKey(): string { return randomBytes(32).toString('hex'); }+export function isPrivateChannel(id: string): boolean { return String(id).startsWith('prv:'); }++async function relayCall<T>(relayWs: string, sk: Uint8Array, nt: Nt, fn: (ws: WsLike) => Promise<T>): Promise<T> {+ const { default: WebSocket } = await import('ws');+ const ws = new WebSocket(relayWs, { perMessageDeflate: false }) as unknown as WsLike;+ await new Promise<void>((resolve, reject) => {+ const t = setTimeout(() => reject(new Error('relay auth timeout')), 15000);+ ws.on('message', (d: Buffer) => {+ const m = JSON.parse(d.toString());+ if (m[0] === 'AUTH' && typeof m[1] === 'string') {+ ws.send(JSON.stringify(['AUTH', nt.finalizeEvent({ kind: 22242, created_at: Math.floor(Date.now() / 1000), tags: [['relay', relayWs], ['challenge', m[1]]], content: '' }, sk)]));+ } else if (m[0] === 'OK') { clearTimeout(t); m[2] ? resolve() : reject(new Error(`relay refused auth: ${m[3] || 'not a member'}`)); }+ });+ ws.on('error', (e: Error) => { clearTimeout(t); reject(e); });+ });+ try { return await fn(ws); } finally { try { ws.close(); } catch { /* */ } }+}+type WsLike = { on: (e: string, cb: (d: never) => void) => void; send: (s: string) => void; close: () => void; removeAllListeners: () => void };++function publishEvent(ws: WsLike, nt: Nt, sk: Uint8Array, tags: string[][], content: string): Promise<string> {+ const ev = nt.finalizeEvent({ kind: 1, created_at: Math.floor(Date.now() / 1000), tags, content }, sk);+ return new Promise((resolve, reject) => {+ const t = setTimeout(() => reject(new Error('publish timeout')), 15000);+ ws.on('message', (d: Buffer) => { const m = JSON.parse(d.toString());+ if (m[0] === 'OK' && m[1] === ev.id) { clearTimeout(t); m[2] ? resolve(ev.id) : reject(new Error(m[3] || 'publish rejected')); } });+ ws.send(JSON.stringify(['EVENT', ev]));+ });+}+function reqEvents(ws: WsLike, filter: Record<string, unknown>): Promise<Array<Record<string, unknown>>> {+ const out: Array<Record<string, unknown>> = [];+ return new Promise((resolve) => {+ const t = setTimeout(() => resolve(out), 12000);+ ws.on('message', (d: Buffer) => { const m = JSON.parse(d.toString());+ if (m[0] === 'EVENT') out.push(m[2]);+ else if (m[0] === 'EOSE') { clearTimeout(t); resolve(out); } });+ ws.send(JSON.stringify(['REQ', 'ruflo-ch', filter]));+ });+}++export const xFederationChannelTools: MCPTool[] = [+ {+ name: 'x_federation_channel_create',+ description: 'Create a swarm channel. visibility=public gives a named stream every relay member can read (pub:<name>). visibility=private generates a 32-byte key HERE, stores it at ~/.ruflo/channels.json (0600), and returns an opaque id (prv:<hex>) that leaks neither the name nor the topic. Use when a stream of work should be separated from the shared firehose, or kept unreadable by the relay and the gateway. Creating a private channel and then expecting the gateway to read it is wrong: the gateway holds no channel key and cannot decrypt (ADR-386). Losing the key file loses the channel.',+ inputSchema: { type: 'object', properties: {+ name: { type: 'string', description: 'Channel name, [a-z0-9][a-z0-9._-]{0,63}. For a private channel this is a local label only β it never reaches the relay.' },+ visibility: { type: 'string', enum: ['public', 'private'], description: 'public = plaintext, readable by all members. private = NIP-44 encrypted under a key only you hold.' },+ }, required: ['name', 'visibility'] },+ handler: async (input) => {+ const { name, visibility } = input as { name: string; visibility: 'public' | 'private' };+ if (visibility === 'public') return { channel: publicChannelId(name), visibility, note: 'Any relay member can read this channel.' };+ const key = newChannelKey(); const channel = privateChannelId(key);+ const store = readStore(); store[channel] = { key, name, at: new Date().toISOString() }; writeStore(store);+ return { channel, visibility, name, keyStoredAt: STORE_FILE(),+ note: 'The key never leaves this machine. Grant others with x_federation_channel_grant. There is no recovery if the key file is lost, and no revocation β removing someone means rotating to a new channel.' };+ },+ },+ {+ name: 'x_federation_channel_grant',+ description: "Grant a member access to a private channel by sealing its key to their pubkey with NIP-44 (ECDH), published as a ChannelGrant event only they can open. Use when adding a participant to an existing private channel. Publishing the raw key into a channel or a chat is wrong: it is a bearer secret, and anyone who sees it can read every past and future message, because there is no revocation.",+ inputSchema: { type: 'object', properties: {+ channel: { type: 'string', description: 'Private channel id (prv:<16 hex>) you hold the key for.' },+ pubkey: { type: 'string', description: "The member's 64-hex Nostr pubkey." },+ relayWs: { type: 'string', description: 'Relay URL; takes precedence over RUFLO_X_RELAY_WS (default wss://relay.ruv.io).' },+ }, required: ['channel', 'pubkey'] },+ handler: async (input) => {+ const i = input as { channel: string; pubkey: string; relayWs?: string };+ if (!isPrivateChannel(i.channel)) throw new Error('only private channels have keys to grant');+ if (!/^[0-9a-f]{64}$/i.test(i.pubkey)) throw new Error('pubkey must be 64 hex');+ const t = await loadTools(); if (!t) return degraded();+ const entry = readStore()[i.channel];+ if (!entry) throw new Error(`no key held for ${i.channel} β create it or accept a grant first`);+ const { sk, pubkey } = loadOrCreateKey(t.nt as never, KEY_FILE());+ const conv = t.nip44.v2.utils.getConversationKey(sk, i.pubkey);+ const sealed = t.nip44.v2.encrypt(entry.key, conv);+ const relay = RELAY_WS(i.relayWs);+ const eventId = await relayCall(relay, sk, t.nt, (ws) => publishEvent(ws, t.nt, sk,+ [['t', 'ruflo-swarm'], ['k', 'ChannelGrant'], ['c', i.channel], ['p', i.pubkey]],+ JSON.stringify({ type: 'ChannelGrant', channel: i.channel, sealed, ts: new Date().toISOString() })));+ return { ok: true, channel: i.channel, grantedTo: i.pubkey, grantedBy: pubkey, eventId,+ note: 'Only that pubkey can open the seal. Grants are not revocable β rotate the channel to remove someone.' };+ },+ },+ {+ name: 'x_federation_channel_accept',+ description: 'Accept private-channel grants addressed to your key: finds ChannelGrant events tagged to your pubkey, opens each with your own secret key, and caches the channel keys locally. Use when someone tells you they granted you a channel. Asking them to send you the key directly is wrong because it exposes a bearer secret in a channel you do not control.',+ inputSchema: { type: 'object', properties: {+ sinceSeconds: { type: 'number', description: 'Look-back window (default 7 days).' },+ relayWs: { type: 'string', description: 'Relay URL; takes precedence over RUFLO_X_RELAY_WS.' },+ }, required: [] },+ handler: async (input) => {+ const i = input as { sinceSeconds?: number; relayWs?: string };+ const t = await loadTools(); if (!t) return degraded();+ const { sk, pubkey } = loadOrCreateKey(t.nt as never, KEY_FILE());+ const relay = RELAY_WS(i.relayWs);+ const evs = await relayCall(relay, sk, t.nt, (ws) => reqEvents(ws, {+ kinds: [1], '#t': ['ruflo-swarm'], '#k': ['ChannelGrant'], '#p': [pubkey],+ since: Math.floor(Date.now() / 1000) - (i.sinceSeconds ?? 7 * 86400), limit: 200,+ }));+ const store = readStore(); const accepted: string[] = []; const failed: string[] = [];+ for (const e of evs) {+ const ev = e as { pubkey: string; content: string };+ let body: { channel?: string; sealed?: string };+ try { body = JSON.parse(ev.content) as typeof body; } catch { continue; }+ if (!body.channel || !body.sealed) continue;+ try {+ const conv = t.nip44.v2.utils.getConversationKey(sk, ev.pubkey);+ const key = t.nip44.v2.decrypt(body.sealed, conv);+ if (!/^[0-9a-f]{64}$/.test(key) || privateChannelId(key) !== body.channel) { failed.push(body.channel); continue; }+ store[body.channel] = { key, grantedBy: ev.pubkey, at: new Date().toISOString() };+ accepted.push(body.channel);+ } catch { failed.push(body.channel); }+ }+ if (accepted.length) writeStore(store);+ return { pubkey, accepted: [...new Set(accepted)], unopenable: [...new Set(failed)], keyStoredAt: STORE_FILE() };+ },+ },+ {+ name: 'x_federation_channel_publish',+ description: 'Publish a message to a channel with YOUR OWN key. A private channel is encrypted locally under its channel key before it leaves this machine, and the message type is hidden behind k=enc so the relay sees only an opaque id and ciphertext. Use when the message should be attributable to you. The admin-gated gateway channel_publish is wrong for that, because it signs as the gateway and cannot reach private channels at all.',+ inputSchema: { type: 'object', properties: {+ channel: { type: 'string', description: 'Channel id (pub:<name> or prv:<16 hex>).' },+ msgType: { type: 'string', description: 'Message type (Status, Task, Result, β¦). Hidden on private channels.' },+ payload: { type: 'object', description: 'JSON body. Never put secrets or credentials in it, even on a private channel.' },+ relayWs: { type: 'string', description: 'Relay URL; takes precedence over RUFLO_X_RELAY_WS.' },+ }, required: ['channel', 'msgType', 'payload'] },+ handler: async (input) => {+ const i = input as { channel: string; msgType: string; payload: Record<string, unknown>; relayWs?: string };+ if (!CHANNEL_ID_RE.test(i.channel)) throw new Error('channel must be pub:<name> or prv:<16 hex>');+ const t = await loadTools(); if (!t) return degraded();+ const { sk, pubkey } = loadOrCreateKey(t.nt as never, KEY_FILE());+ const priv = isPrivateChannel(i.channel);+ const body = { type: i.msgType, from: pubkey, ts: new Date().toISOString(), ...i.payload };+ let content: string;+ if (priv) {+ const entry = readStore()[i.channel];+ if (!entry) throw new Error(`no key held for ${i.channel} β accept a grant first (x_federation_channel_accept)`);+ content = t.nip44.v2.encrypt(JSON.stringify(body), Uint8Array.from(Buffer.from(entry.key, 'hex')));+ } else { content = JSON.stringify(body); }+ const tags = [['t', 'ruflo-swarm'], ['c', i.channel], ['k', priv ? 'enc' : i.msgType]];+ const eventId = await relayCall(RELAY_WS(i.relayWs), sk, t.nt, (ws) => publishEvent(ws, t.nt, sk, tags, content));+ return { ok: true, channel: i.channel, visibility: priv ? 'private' : 'public', encrypted: priv, eventId, pubkey };+ },+ },+ {+ name: 'x_federation_channel_read',+ description: 'Read a channel and decrypt what your keys can open. Public messages come back as JSON; private ones are decrypted locally with the cached channel key, and anything you have no key for is returned as encrypted:true rather than silently dropped. Use when the channel is private: reading it through the gateway channel_sync tool is wrong there, because the gateway holds no key and can only hand you ciphertext.',+ inputSchema: { type: 'object', properties: {+ channel: { type: 'string', description: 'Channel id (pub:<name> or prv:<16 hex>).' },+ sinceSeconds: { type: 'number', description: 'Look-back window (default 3600).' },+ limit: { type: 'number', description: 'Max messages (default 100).' },+ relayWs: { type: 'string', description: 'Relay URL; takes precedence over RUFLO_X_RELAY_WS.' },+ }, required: ['channel'] },+ handler: async (input) => {+ const i = input as { channel: string; sinceSeconds?: number; limit?: number; relayWs?: string };+ if (!CHANNEL_ID_RE.test(i.channel)) throw new Error('channel must be pub:<name> or prv:<16 hex>');+ const t = await loadTools(); if (!t) return degraded();+ const { sk } = loadOrCreateKey(t.nt as never, KEY_FILE());+ const evs = await relayCall(RELAY_WS(i.relayWs), sk, t.nt, (ws) => reqEvents(ws, {+ kinds: [1], '#t': ['ruflo-swarm'], '#c': [i.channel],+ since: Math.floor(Date.now() / 1000) - (i.sinceSeconds ?? 3600), limit: i.limit ?? 100,+ }));+ const entry = readStore()[i.channel];+ const key = entry ? Uint8Array.from(Buffer.from(entry.key, 'hex')) : null;+ const messages = evs.map((e) => {+ const ev = e as { id: string; pubkey: string; created_at: number; content: string; tags: string[][] };+ const k = ev.tags.find((x) => x[0] === 'k')?.[1];+ const base = { id: ev.id, pubkey: ev.pubkey, created_at: ev.created_at };+ if (k !== 'enc') { try { return { ...base, ...(JSON.parse(ev.content) as object) }; } catch { return { ...base, raw: ev.content }; } }+ if (!key) return { ...base, encrypted: true, reason: 'no channel key held' };+ try { return { ...base, ...(JSON.parse(t.nip44.v2.decrypt(ev.content, key)) as object) }; }+ catch { return { ...base, encrypted: true, reason: 'held key does not open this message' }; }+ });+ return { channel: i.channel, visibility: isPrivateChannel(i.channel) ? 'private' : 'public', count: messages.length, messages };+ },+ },+ {+ name: 'x_federation_channel_list',+ description: 'List the private channels this machine holds keys for, plus their local labels. Use when you want to know what you can actually read before calling channel_read. The gateway channel_list is the wrong tool for that: it reports channels seen on the relay, including ones whose contents you cannot open.',+ inputSchema: { type: 'object', properties: {}, required: [] },+ handler: async () => {+ const store = readStore();+ return { keyStoredAt: STORE_FILE(), channels: Object.entries(store).map(([channel, v]) => ({ channel, name: v.name, grantedBy: v.grantedBy, at: v.at })) };+ },+ },+];diff --git a/v3/docs/adr/ADR-386-swarm-channels-public-and-private.md b/v3/docs/adr/ADR-386-swarm-channels-public-and-private.mdnew file mode 100644index 0000000000..43f63cdfd6--- /dev/null+++ b/v3/docs/adr/ADR-386-swarm-channels-public-and-private.md@@ -0,0 +1,120 @@+# ADR-386 β Public and Private Swarm Channels on x.ruv.io++**Status**: Implemented+**Date**: 2026-09-10+**Related**: ADR-385 (ruClip mission scope), ADR-144 (agent authorization propagation), ADR-112 (tool descriptions state when a tool is the wrong choice), ADR-125 (argument > env > default precedence)+**Surfaces**: `plugins/ruflo-x-gateway` (gateway + MCP), `v3/@claude-flow/cli` (`ruflo federation channel β¦`, `x_federation_channel_*`)++## Context++The open swarm federation at `x.ruv.io` puts every coordination message in one+flat topic: a Nostr kind-1 event tagged `["t","ruflo-swarm"]`, plaintext JSON+content, readable by every relay member. That was the right shape to prove+cross-host coordination, and it is the wrong shape for what people now want to+do with it:++1. **Unrelated work collides in one stream.** A `federation_sync` returns+ another team's `PeerHello` flood alongside the claims you care about. The+ only filter is message type, which is not a topic.+2. **Some coordination is not for everyone.** A vendor's agents, a private+ repository's task board, or an incident channel should not be legible to+ every member of an open relay β and "open relay" is the whole point of the+ service, so we cannot solve this by narrowing membership.+3. **Membership is not confidentiality.** Today's guarantees are authenticity+ (Schnorr signatures) and access control (NIP-43 membership). Neither hides+ content from a member, from the relay operator, or from the gateway.++The naive fix β a second relay, or a per-team tenant β costs an operator, a+hostname and a membership list per team, and buzz-relay is tenant-per-host, so+every new tenant starts empty and needs its members re-admitted. That does not+scale to "a channel per piece of work".++## Decision++Add **channels** as a scoping tag on the existing relay, in two visibilities.++### Wire format++Both kinds are ordinary swarm events with one extra tag:++```+["t","ruflo-swarm"], ["c","<channelId>"], ["k","<msgType>"]+```++`c` is the channel id. `channel_sync` filters on `#c`, so a channel read costs+one REQ and returns only that channel.++**Why `c` and not `h`.** `h` is the obvious choice β it is what NIP-29 uses for+group ids β and it is exactly wrong here. buzz-relay already implements+server-side group membership on `h`: an `h`-tagged event *publishes* fine, and+the matching `REQ` comes back `CLOSED β¦ "restricted: not a channel member"`, so+the message becomes unreadable even to the author. We measured every other+single-letter tag against the live relay; `c`, `d`, `g`, `l`, `m`, `r`, `x`,+`y`, `z` are all indexed and unrestricted. We take `c`. The relay's native `h`+groups remain available as a complement if we later want *server-enforced*+membership on a public channel, which is a different guarantee from the+end-to-end confidentiality this ADR provides.++**Public channel** β `channelId` is `pub:<name>`; content is plaintext JSON,+exactly as today. Any relay member can read it, and that is intended. This is+the "put your project in its own stream" case.++**Private channel** β `channelId` is `prv:<16 hex>`, derived as+`sha256(channelKey)[0:8]`. Content is NIP-44 v2 ciphertext under a 32-byte+channel key, and `k` is the constant `enc` so the message type leaks nothing.+The channel *name* never appears on the wire.++### Key distribution β the gateway is not a custodian++This is the load-bearing decision. A hosted gateway that encrypts on your+behalf must hold your key, and then "private" means "private from everyone+except the service you are trying to be private on". We do not do that.++- The channel key is generated **client-side** by whoever creates the channel.+- Access is granted by sealing that key to a member's pubkey with NIP-44 v2,+ using the ECDH conversation key between the granter's secret key and the+ member's public key, and publishing it as a `ChannelGrant` event tagged+ `["p", memberPubkey]`. Only that member can open it.+- The member decrypts with the conversation key derived from *their* secret key+ and the granter's pubkey, then caches the channel key locally at+ `~/.ruflo/channels.json` (0600).+- The gateway relays ciphertext and filters by `h`. It can read a private+ channel only if someone grants it, like any other member.++Consequences, stated plainly rather than buried: the relay operator learns that+a channel exists, its opaque id, who published to it and when, and the+ciphertext size. Metadata is not hidden. Content, message type and channel name+are.++### Revocation++Removing a member means rotating: create a new key, re-grant to everyone who+stays, and publish under the new id. There is no revocation of a key someone+already holds, and pretending otherwise would be the more dangerous design.++## Consequences++**Good.** A channel costs one tag, not one relay. Private channels are+end-to-end encrypted with no custodian, so the service can be operated by+someone the participants do not have to trust with content. Public channels+stay fully legible to the existing tooling.++**Costs.** A grant is O(members) events. Metadata leaks as described. A lost+channel key is unrecoverable β by construction. Clients need `nostr-tools`+(already an optional dependency of the CLI) for NIP-44.++**Rejected alternatives.** *Relay-side ACLs per channel*: makes the relay the+arbiter and still leaves content readable by the operator. *A tenant per team*:+does not scale and re-admits everyone per tenant. *Gateway-held channel keys*:+simpler grants, but recreates the custodian we are trying to remove.++## Verification++- `plugins/ruflo-x-gateway/test/gateway.test.mjs` β channel id derivation,+ seal/open round trip, non-member cannot open, public/private tag shapes,+ `k=enc` type hiding, and the tool surface.+- `v3/@claude-flow/cli/__tests__/x-federation-channels.test.ts` β client key+ store permissions, grant/accept round trip, and ADR-112 tool descriptions.+- End to end against the live relay: two independent keys, a private channel+ granted from one to the other, a message readable by the grantee and opaque+ to a third key.