claude-flow 3.40.0 → 3.41.1

package/v3/@claude-flow/cli/dist/src/mcp-tools/x-federation-channels.js

@@ -0,0 +1,299 @@
+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) => 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})$/;
+async function loadTools() {
+    try {
+        const nt = (await import('nostr-tools/pure'));
+        const { nip44 } = (await import('nostr-tools'));
+        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)' });
+export function readStore(file = STORE_FILE()) {
+    if (!existsSync(file))
+        return {};
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+export function writeStore(store, file = STORE_FILE()) {
+    mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+    writeFileSync(file, JSON.stringify(store, null, 2), { mode: 0o600 });
+}
+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}`;
+}
+export function privateChannelId(keyHex) {
+    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() { return randomBytes(32).toString('hex'); }
+export function isPrivateChannel(id) { return String(id).startsWith('prv:'); }
+async function relayCall(relayWs, sk, nt, fn) {
+    const { default: WebSocket } = await import('ws');
+    const ws = new WebSocket(relayWs, { perMessageDeflate: false });
+    await new Promise((resolve, reject) => {
+        const t = setTimeout(() => reject(new Error('relay auth timeout')), 15000);
+        ws.on('message', (d) => {
+            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) => { clearTimeout(t); reject(e); });
+    });
+    try {
+        return await fn(ws);
+    }
+    finally {
+        try {
+            ws.close();
+        }
+        catch { /* */ }
+    }
+}
+function publishEvent(ws, nt, sk, tags, content) {
+    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) => {
+            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, filter) {
+    const out = [];
+    return new Promise((resolve) => {
+        const t = setTimeout(() => resolve(out), 12000);
+        ws.on('message', (d) => {
+            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 = [
+    {
+        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;
+            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;
+            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, 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;
+            const t = await loadTools();
+            if (!t)
+                return degraded();
+            const { sk, pubkey } = loadOrCreateKey(t.nt, 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 = [];
+            const failed = [];
+            for (const e of evs) {
+                const ev = e;
+                let body;
+                try {
+                    body = JSON.parse(ev.content);
+                }
+                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;
+            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, KEY_FILE());
+            const priv = isPrivateChannel(i.channel);
+            const body = { type: i.msgType, from: pubkey, ts: new Date().toISOString(), ...i.payload };
+            let content;
+            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;
+            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, 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;
+                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) };
+                    }
+                    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)) };
+                }
+                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 })) };
+        },
+    },
+];
+//# sourceMappingURL=x-federation-channels.js.map

package/v3/@claude-flow/cli/dist/src/mcp-tools/x-federation-join.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Self-service join for the open swarm federation — the user-facing invite path.
+ *
+ * Decentralized by design: the user generates/holds THEIR OWN Nostr key locally,
+ * redeems an invite code with a NIP-98-signed claim (no admin in the loop), proves
+ * membership with NIP-42, and announces themselves. The gateway never signs for them.
+ *
+ * `nostr-tools` is an optional dependency (secp256k1/Schnorr is not in node:crypto):
+ * when absent the tool degrades with an install hint instead of throwing at load.
+ */
+import type { MCPTool } from './types.js';
+type NostrTools = {
+    generateSecretKey: () => Uint8Array;
+    getPublicKey: (sk: Uint8Array) => string;
+    finalizeEvent: (t: Record<string, unknown>, sk: Uint8Array) => Record<string, unknown> & {
+        id: string;
+    };
+};
+export declare function loadOrCreateKey(nt: NostrTools, file?: string): {
+    sk: Uint8Array;
+    pubkey: string;
+    created: boolean;
+};
+export declare function nip98Header(nt: NostrTools, sk: Uint8Array, url: string, method: string, body?: string): string;
+export declare function verifyMembership(nt: NostrTools, sk: Uint8Array, relayWs: string): Promise<{
+    ok: boolean;
+    reason?: string;
+}>;
+export declare const xFederationJoinTools: MCPTool[];
+export {};
+//# sourceMappingURL=x-federation-join.d.ts.map

package/v3/@claude-flow/cli/dist/src/mcp-tools/x-federation-join.js

@@ -0,0 +1,87 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+// ADR-125 precedence: tool args (relayHttp / relayWs / keyFile) take precedence over the
+// RUFLO_X_RELAY_HTTP / RUFLO_X_RELAY_WS / RUFLO_NOSTR_KEY_FILE env vars, which precede defaults.
+const HTTP_BASE = (o) => (o || process.env.RUFLO_X_RELAY_HTTP || 'https://relay.ruv.io').replace(/\/$/, '');
+const RELAY_WS = (o) => 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 hex = (b) => Buffer.from(b).toString('hex');
+const unhex = (h) => Uint8Array.from(Buffer.from(h, 'hex'));
+async function loadNostrTools() {
+    try {
+        return (await import('nostr-tools/pure'));
+    }
+    catch {
+        return null;
+    }
+}
+export function loadOrCreateKey(nt, file = KEY_FILE()) {
+    if (existsSync(file)) {
+        const sk = unhex(readFileSync(file, 'utf8').trim());
+        return { sk, pubkey: nt.getPublicKey(sk), created: false };
+    }
+    mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+    const sk = nt.generateSecretKey();
+    writeFileSync(file, hex(sk), { mode: 0o600 });
+    return { sk, pubkey: nt.getPublicKey(sk), created: true };
+}
+export function nip98Header(nt, sk, url, method, body) {
+    const ev = nt.finalizeEvent({ kind: 27235, created_at: Math.floor(Date.now() / 1000),
+        tags: [['u', url], ['method', method], ...(body ? [['payload', createHash('sha256').update(body).digest('hex')]] : [])], content: '' }, sk);
+    return 'Nostr ' + Buffer.from(JSON.stringify(ev)).toString('base64');
+}
+// NIP-42: connect, answer the challenge, resolve true/false (never throws on refusal).
+export async function verifyMembership(nt, sk, relayWs) {
+    const { default: WebSocket } = await import('ws');
+    return new Promise((resolve) => {
+        const ws = new WebSocket(relayWs, { perMessageDeflate: false });
+        let done = false;
+        const fin = (r) => { if (done)
+            return; done = true; try {
+            ws.close();
+        }
+        catch { /* */ } resolve(r); };
+        ws.on('message', (d) => {
+            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')
+                fin({ ok: !!m[2], reason: m[3] });
+        });
+        ws.on('error', (e) => fin({ ok: false, reason: e.message }));
+        setTimeout(() => fin({ ok: false, reason: 'timeout' }), 15000);
+    });
+}
+export const xFederationJoinTools = [{
+        name: 'x_federation_join',
+        description: 'Join the open swarm federation with YOUR OWN key using an invite code: generates (or reuses) a local Nostr key at ~/.ruflo/nostr.key (0600), redeems the code with a NIP-98-signed claim directly against the relay, proves membership via NIP-42, and returns your pubkey. Use when you have been handed an invite code and want to participate as yourself. Asking an admin to `federation_admit` you instead is wrong for an open swarm because it centralizes onboarding and requires trusting a pubkey out of band; the invite claim binds membership to the key you hold. Never share the invite code publicly — it is a bearer secret.',
+        inputSchema: { type: 'object', properties: {
+                code: { type: 'string', description: 'Invite code (v2.…) received privately from a member/admin.' },
+                relayHttp: { type: 'string', description: 'Relay HTTPS base for the claim; takes precedence over RUFLO_X_RELAY_HTTP.' },
+                relayWs: { type: 'string', description: 'Relay wss URL for NIP-42; takes precedence over RUFLO_X_RELAY_WS.' },
+                keyFile: { type: 'string', description: 'Key file path; takes precedence over RUFLO_NOSTR_KEY_FILE (default ~/.ruflo/nostr.key).' }
+            }, required: ['code'] },
+        handler: async (input) => {
+            const i = input;
+            const nt = await loadNostrTools();
+            // Validate input before the optional-dependency check so a bad code fails fast and identically
+            // whether or not nostr-tools is present.
+            if (!/^v2\.[A-Za-z0-9._-]{8,}$/.test(i.code))
+                throw new Error('invite code must look like v2.<token>');
+            if (!nt)
+                return { degraded: true, reason: 'nostr-tools not installed', hint: 'npm i -g nostr-tools  (secp256k1 signing is not in node:crypto)' };
+            const { sk, pubkey, created } = loadOrCreateKey(nt, i.keyFile);
+            const url = `${HTTP_BASE(i.relayHttp)}/api/invites/claim`;
+            const body = JSON.stringify({ code: i.code });
+            const r = await fetch(url, { method: 'POST', headers: { Authorization: nip98Header(nt, sk, url, 'POST', body), 'Content-Type': 'application/json' }, body, signal: AbortSignal.timeout(20_000) });
+            const claim = (await r.json().catch(() => ({})));
+            if (!r.ok)
+                throw new Error(`claim rejected (${r.status}): ${claim.error ?? claim.message ?? 'unknown'}`);
+            const auth = await verifyMembership(nt, sk, RELAY_WS(i.relayWs));
+            return { ok: auth.ok, pubkey, keyCreated: created, role: claim.role ?? 'member', membershipVerified: auth.ok, ...(auth.ok ? {} : { reason: auth.reason }),
+                next: 'Publish kind-1 events tagged ["t","ruflo-swarm"] — or run `ruflo federation sync` to read the swarm.' };
+        },
+    }];
+//# sourceMappingURL=x-federation-join.js.map

package/v3/@claude-flow/cli/dist/src/mcp-tools/x-federation-tools.d.ts

@@ -0,0 +1,12 @@
+/**
+ * x.ruv.io open swarm federation — ruflo-native MCP tools.
+ *
+ * Bridges ruflo to the open, membership-gated, signed Nostr federation behind
+ * https://x.ruv.io. Reads are open; writes made with the GATEWAY identity need
+ * the gateway admin token (RUFLO_X_ADMIN_TOKEN). Users who want to publish as
+ * themselves should join with their own key via invite→claim (see the
+ * `ruv://federation/registry` resource), not through these gateway-identity tools.
+ */
+import type { MCPTool } from './types.js';
+export declare const xFederationTools: MCPTool[];
+//# sourceMappingURL=x-federation-tools.d.ts.map

package/v3/@claude-flow/cli/dist/src/mcp-tools/x-federation-tools.js

@@ -0,0 +1,96 @@
+// ADR-125 precedence: the tool arg `gatewayUrl` (fed by `ruflo federation --gateway`)
+// takes precedence over the RUFLO_X_GATEWAY_URL env var, which precedes the default.
+const GATEWAY = (override) => ((typeof override === 'string' && override) || process.env.RUFLO_X_GATEWAY_URL || 'https://x.ruv.io').replace(/\/$/, '');
+const gatewayArg = { gatewayUrl: { type: 'string', description: 'Gateway base URL; takes precedence over RUFLO_X_GATEWAY_URL (default https://x.ruv.io).' } };
+const TIMEOUT_MS = 25_000;
+/** Minimal MCP-over-Streamable-HTTP client: POST JSON-RPC, parse the SSE `data:` frame. */
+async function gatewayRpc(method, params, gatewayUrl) {
+    const res = await fetch(`${GATEWAY(gatewayUrl)}/mcp`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', accept: 'application/json, text/event-stream' },
+        body: JSON.stringify({ jsonrpc: '2.0', id: Date.now(), method, params }),
+        signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+    const text = await res.text();
+    const line = text.split('\n').find((l) => l.startsWith('data:'));
+    const payload = JSON.parse(line ? line.slice(5) : text);
+    if (payload.error)
+        throw new Error(`x.ruv.io: ${payload.error.message ?? 'rpc error'}`);
+    return payload.result;
+}
+async function gatewayTool(name, args) {
+    const { gatewayUrl, ...rest } = args;
+    const r = (await gatewayRpc('tools/call', { name, arguments: rest }, gatewayUrl));
+    const text = r.content?.[0]?.text ?? '{}';
+    const parsed = JSON.parse(text);
+    if (r.isError || parsed.error)
+        throw new Error(String(parsed.error ?? 'gateway tool error'));
+    return parsed;
+}
+async function gatewayResource(uri, gatewayUrl) {
+    const r = (await gatewayRpc('resources/read', { uri }, gatewayUrl));
+    return JSON.parse(r.contents?.[0]?.text ?? '{}');
+}
+// Credential: intentionally env-only (a secret must never be a CLI flag — it would land in
+// shell history / process lists). Registered in scripts/audit-env-var-precedence.mjs.
+const adminToken = () => process.env.RUFLO_X_ADMIN_TOKEN;
+export const xFederationTools = [
+    {
+        name: 'x_federation_sync',
+        description: 'Fetch recent signature-verified coordination messages from the open x.ruv.io swarm federation (Nostr, #t=ruflo-swarm). Use when you need to see what other ruflo nodes across the internet have posted (PeerHello/Status/Task/Result/Claim*). Reading the relay directly is wrong because you would have to do NIP-42 auth yourself; the gateway does it and only returns events whose signatures verify.',
+        inputSchema: { type: 'object', properties: { ...gatewayArg, sinceSeconds: { type: 'number', description: 'Look-back window (default 3600).' }, limit: { type: 'number', description: 'Max messages (default 100).' }, type: { type: 'string', description: 'Optional message type filter, e.g. Task.' } } },
+        handler: async (input) => gatewayTool('federation_sync', input),
+    },
+    {
+        name: 'x_federation_roster',
+        description: 'List nodes currently announcing themselves on the open swarm (recent PeerHello events) via the ruv://swarm/roster resource. Use when you need to know who is online across the federation before assigning work. Grepping sync output by hand is wrong because the roster resource already de-duplicates by pubkey and carries lastSeen.',
+        inputSchema: { type: 'object', properties: { ...gatewayArg } },
+        handler: async (input) => gatewayResource('ruv://swarm/roster', input.gatewayUrl),
+    },
+    {
+        name: 'x_federation_claims',
+        description: 'Return the current owner-per-resource work-claims ledger for the open swarm (ruv://claims/board). Use when you are about to start shared work and need to know whether a resourceId is already owned. Inferring ownership from raw ClaimIssued events is wrong because releases, TTL expiry and handoffs change the answer; the board applies those rules.',
+        inputSchema: { type: 'object', properties: { ...gatewayArg } },
+        handler: async (input) => gatewayResource('ruv://claims/board', input.gatewayUrl),
+    },
+    {
+        name: 'x_federation_registry',
+        description: 'Read the federation registry resource (ruv://federation/registry): relay URL, canonical relay tag for NIP-42, gateway pubkey, and the exact self-join steps. Use when onboarding a new node or user to the open federation. Hard-coding the relay URL is wrong because the relay verifies the NIP-42 relay tag strictly against its canonical host, which this resource states.',
+        inputSchema: { type: 'object', properties: { ...gatewayArg } },
+        handler: async (input) => gatewayResource('ruv://federation/registry', input.gatewayUrl),
+    },
+    {
+        name: 'x_federation_publish',
+        description: 'Publish a signed coordination message to the open swarm AS THE GATEWAY identity (Status/Task/Result/…). Requires RUFLO_X_ADMIN_TOKEN. Use when a trusted operator needs a hub-level broadcast. Using this to post on behalf of an individual node is wrong because it attributes the message to the gateway, not the node — nodes should join with their own key via invite→claim and publish themselves.',
+        inputSchema: { type: 'object', properties: { ...gatewayArg, msgType: { type: 'string' }, payload: { type: 'object' } }, required: ['msgType', 'payload'] },
+        handler: async (input) => {
+            const t = adminToken();
+            if (!t)
+                throw new Error('RUFLO_X_ADMIN_TOKEN is not set (gateway-identity writes are admin-gated)');
+            return gatewayTool('federation_publish', { ...input, adminToken: t });
+        },
+    },
+    {
+        name: 'x_federation_invite_mint',
+        description: 'Mint a use-limited, expiring invite code so a new ruflo user can self-join the open federation with THEIR OWN key. Requires RUFLO_X_ADMIN_TOKEN. Use when onboarding someone. Sharing the relay owner key instead is wrong because invites are revocable, hashed at rest, and bind membership to the claimant\'s key; the code is a bearer secret — hand it over privately.',
+        inputSchema: { type: 'object', properties: { ...gatewayArg, ttlSecs: { type: 'number', description: 'Validity (default 7 days).' }, maxUses: { type: 'number', description: 'Redemptions (default 25).' } } },
+        handler: async (input) => {
+            const t = adminToken();
+            if (!t)
+                throw new Error('RUFLO_X_ADMIN_TOKEN is not set (invite minting is admin-gated)');
+            return gatewayTool('federation_invite_mint', { ...input, adminToken: t });
+        },
+    },
+    {
+        name: 'x_federation_admit',
+        description: 'Admit a Nostr pubkey as a relay member directly (NIP-43 kind 9030). Requires RUFLO_X_ADMIN_TOKEN. Use when a known node reports its 64-hex pubkey and you want to skip the invite step. Padding or hand-editing a reported pubkey is wrong because it is a cryptographic identity; a malformed key must be re-reported, never fixed up.',
+        inputSchema: { type: 'object', properties: { ...gatewayArg, pubkey: { type: 'string', description: '64-hex secp256k1 x-only pubkey.' }, role: { type: 'string', enum: ['member', 'admin'] } }, required: ['pubkey'] },
+        handler: async (input) => {
+            const t = adminToken();
+            if (!t)
+                throw new Error('RUFLO_X_ADMIN_TOKEN is not set (admission is admin-gated)');
+            return gatewayTool('federation_admit', { ...input, adminToken: t });
+        },
+    },
+];
+//# sourceMappingURL=x-federation-tools.js.map

package/v3/@claude-flow/cli/dist/src/memory/memory-bridge.d.ts

@@ -34,6 +34,10 @@ export declare function shouldDisableNativeBridge(platform?: NodeJS.Platform, en
  * noise. Suppress the banners, keep the bad news.
  */
 export declare function shouldSuppressInitLog(msg: string): boolean;
+/** Test seam: forget cached registries so a test can exercise a fresh open. */
+export declare function _resetRegistryCacheForTest(): void;
+/** #3196: the sibling store AgentDB owns next to a given sql.js database. */
+export declare function siblingAgentDbPath(dbPath: string): string | null;
 /**
  * Create/migrate the bridge's `memory_entries` table on `db`.
  *