claude-flow 3.39.3 → 3.41.0

package/.claude/.proven-config-version

@@ -0,0 +1 @@
+sha256:6141a8ea990c5063b77e090ae8f37f9c539d8aa8f58dcceb30f3a82f97e57319

package/.claude/proven-config.json

@@ -0,0 +1,42 @@
+{
+  "adoptedAt": 1788986588440,
+  "championId": "sha256:6141a8ea990c5063b77e090ae8f37f9c539d8aa8f58dcceb30f3a82f97e57319",
+  "manifest": {
+    "schema": "ruflo.proven-config/v1",
+    "policy": {
+      "ref": "sha256:6141a8ea990c5063b77e090ae8f37f9c539d8aa8f58dcceb30f3a82f97e57319",
+      "value": {
+        "alpha": 0.3,
+        "subjectWeight": 1,
+        "mmrLambda": 0.5,
+        "bodyWeight": 1.5,
+        "typePenaltyFactor": 0.5
+      }
+    },
+    "layer": "framework/node-cli",
+    "compatibility": {
+      "ruflo": ">=3.24.0"
+    },
+    "benchmark": {
+      "corpus": "ADR-081-labelled-v1",
+      "corpusHash": "sha256:2f700b5c363e20a3bd88ce2bc9b87bbbbaa61732c6177894c6ec37890f888982"
+    },
+    "receipt": {
+      "heldOutDelta": 0.07381404928570845,
+      "redblue": "PASS",
+      "drift": 0,
+      "canary": {
+        "rollbackRate": 0,
+        "latencyP95": 244.612458000076,
+        "costPerTask": 0
+      },
+      "receiptCoverage": 1
+    },
+    "platform": [
+      "linux",
+      "macOS",
+      "windows"
+    ]
+  },
+  "previous": ""
+}

package/.claude-plugin/marketplace.json

@@ -74,7 +74,7 @@
     {
       "name": "ruflo-agent",
       "source": "./plugins/ruflo-agent",
-      "description": "Agent runtimes — local WASM-sandboxed agents (rvagent) + Anthropic Claude Managed Agents (cloud); one interface, local-vs-cloud backends"
+      "description": "Agent runtimes \u2014 local WASM-sandboxed agents (rvagent) + Anthropic Claude Managed Agents (cloud); one interface, local-vs-cloud backends"
     },
     {
       "name": "ruflo-workflows",
@@ -109,7 +109,7 @@
     {
       "name": "ruflo-adr",
       "source": "./plugins/ruflo-adr",
-      "description": "ADR lifecycle management — create, index, supersede, and link Architecture Decision Records to code"
+      "description": "ADR lifecycle management \u2014 create, index, supersede, and link Architecture Decision Records to code"
     },
     {
       "name": "ruflo-cost-tracker",
@@ -119,7 +119,7 @@
     {
       "name": "ruflo-ddd",
       "source": "./plugins/ruflo-ddd",
-      "description": "Domain-Driven Design scaffolding — bounded contexts, aggregate roots, domain events, and anti-corruption layers"
+      "description": "Domain-Driven Design scaffolding \u2014 bounded contexts, aggregate roots, domain events, and anti-corruption layers"
     },
     {
       "name": "ruflo-federation",
@@ -129,7 +129,7 @@
     {
       "name": "ruflo-graph-intelligence",
       "source": "./plugins/ruflo-graph-intelligence",
-      "description": "Real-time graph intelligence — personalized PageRank, streaming delta updates, witness-signed reasoning, and federation-distributable vectors"
+      "description": "Real-time graph intelligence \u2014 personalized PageRank, streaming delta updates, witness-signed reasoning, and federation-distributable vectors"
     },
     {
       "name": "ruflo-iot-cognitum",
@@ -139,67 +139,67 @@
     {
       "name": "ruflo-knowledge-graph",
       "source": "./plugins/ruflo-knowledge-graph",
-      "description": "Knowledge graph construction — entity extraction, relation mapping, and pathfinder graph traversal"
+      "description": "Knowledge graph construction \u2014 entity extraction, relation mapping, and pathfinder graph traversal"
     },
     {
       "name": "ruflo-market-data",
       "source": "./plugins/ruflo-market-data",
-      "description": "Market data ingestion — feed normalization, OHLCV vectorization, and HNSW-indexed pattern matching"
+      "description": "Market data ingestion \u2014 feed normalization, OHLCV vectorization, and HNSW-indexed pattern matching"
     },
     {
       "name": "ruflo-migrations",
       "source": "./plugins/ruflo-migrations",
-      "description": "Schema migration management — generate, validate, dry-run, and rollback database migrations"
+      "description": "Schema migration management \u2014 generate, validate, dry-run, and rollback database migrations"
     },
     {
       "name": "ruflo-neural-trader",
       "source": "./plugins/ruflo-neural-trader",
-      "description": "Neural trading strategies — self-learning LSTM/Transformer/N-BEATS models with Rust/NAPI backtesting"
+      "description": "Neural trading strategies \u2014 self-learning LSTM/Transformer/N-BEATS models with Rust/NAPI backtesting"
     },
     {
       "name": "ruflo-observability",
       "source": "./plugins/ruflo-observability",
-      "description": "Structured logging, distributed tracing, and metrics — correlate agent swarm activity with application telemetry"
+      "description": "Structured logging, distributed tracing, and metrics \u2014 correlate agent swarm activity with application telemetry"
     },
     {
       "name": "ruflo-ruvector",
       "source": "./plugins/ruflo-ruvector",
-      "description": "Self-learning vector database — HNSW, FlashAttention-3, Graph RAG, hybrid search, DiskANN, and Brain AGI"
+      "description": "Self-learning vector database \u2014 HNSW, FlashAttention-3, Graph RAG, hybrid search, DiskANN, and Brain AGI"
     },
     {
       "name": "ruflo-sparc",
       "source": "./plugins/ruflo-sparc",
-      "description": "SPARC methodology — Specification, Pseudocode, Architecture, Refinement, Completion phases with quality gates"
+      "description": "SPARC methodology \u2014 Specification, Pseudocode, Architecture, Refinement, Completion phases with quality gates"
     },
     {
       "name": "ruflo-metaharness",
       "source": "./plugins/ruflo-metaharness",
-      "description": "MetaHarness integration — surfaces score/genome/mint/mcp-scan/threat-model via skills; pairs with @metaharness/router (ADR-148/149) for cost-optimal model routing; honors ADR-150 optional-augmentation constraint"
+      "description": "MetaHarness integration \u2014 surfaces score/genome/mint/mcp-scan/threat-model via skills; pairs with @metaharness/router (ADR-148/149) for cost-optimal model routing; honors ADR-150 optional-augmentation constraint"
     },
     {
       "name": "ruflo-arena",
       "source": "./plugins/ruflo-arena",
-      "description": "Competitive ruliology for ruflo swarms — arenas, tournaments, and adaptive co-evolution of program strategies (ADR-147/148); strategies-as-programs compete under payoff games"
+      "description": "Competitive ruliology for ruflo swarms \u2014 arenas, tournaments, and adaptive co-evolution of program strategies (ADR-147/148); strategies-as-programs compete under payoff games"
     },
     {
       "name": "ruflo-agntcy",
       "source": "./plugins/ruflo-agntcy",
-      "description": "AGNTCY/Outshift Internet-of-Cognition runtime integration — SLIM secure transport, CASA intent-scoped tool authorization, and AGNTCY identity/observability spans (ADR-380); optional, removable augmentation per ADR-150"
+      "description": "AGNTCY/Outshift Internet-of-Cognition runtime integration \u2014 SLIM secure transport, CASA intent-scoped tool authorization, and AGNTCY identity/observability spans (ADR-380); optional, removable augmentation per ADR-150"
     },
     {
       "name": "ruflo-bbs-federation",
       "source": "./plugins/ruflo-bbs-federation",
-      "description": "AgentBBS federated business-domain BBS room integration (ADR-164 Phase 1) — register/publish/watch/human-join MCP tools wrapping the agentbbs Rust workspace as a federation peer; degrades gracefully when agentbbs is absent"
+      "description": "AgentBBS cross-host agent federation (ADR-164). Phase 1: register/publish/watch/human-join room coordination. Phase 2 (v3.40.0): signed cross-host federation \u2014 identity, peer_add (pin by nodeId+Ed25519 key), peers, serve (read-only pull), sync (pull + union-merge what verifies). Registry-anchored pinning; works on any network (no tailnet required); coordinates work claims (ClaimIssued/Released/Handoff/Ack). Degrades gracefully when agentbbs is absent."
     },
     {
       "name": "ruflo-business-pods",
       "source": "./plugins/ruflo-business-pods",
-      "description": "Business-domain pod templates for the federated business autopilot (ADR-164 Phase 2) — pod templates plus a dry-run-by-default single-tick runner that validates, reserves budget, and resolves agent roles before posting to the BBS room"
+      "description": "Business-domain pod templates for the federated business autopilot (ADR-164 Phase 2) \u2014 pod templates plus a dry-run-by-default single-tick runner that validates, reserves budget, and resolves agent roles before posting to the BBS room"
     },
     {
       "name": "ruflo-music",
       "source": "./plugins/ruflo-music",
-      "description": "AI music generation via Cognitum Music (cogmusic MCP) — compose lyrics/prompts, generate tracks, separate stems, extract MIDI, and master through your own music.cognitum.one account"
+      "description": "AI music generation via Cognitum Music (cogmusic MCP) \u2014 compose lyrics/prompts, generate tracks, separate stems, extract MIDI, and master through your own music.cognitum.one account"
     }
   ]
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-flow",
-  "version": "3.39.3",
+  "version": "3.41.0",
   "workspaces": [
     "v3/@claude-flow/codex",
     "v3/@claude-flow/mcp",

package/v3/@claude-flow/cli/catalog-manifest.json

@@ -1,11 +1,11 @@
 {
   "schemaVersion": 1,
   "generation": 6,
-  "generatedAt": "2026-09-09T20:21:54.605Z",
-  "gitSha": "07f1cf3a",
+  "generatedAt": "2026-09-10T11:59:15.567Z",
+  "gitSha": "cb10bf61",
   "catalog": {
     "agents": 167,
-    "tools": 397,
+    "tools": 418,
     "skills": 34
   },
   "benchmark": null

package/v3/@claude-flow/cli/dist/src/commands/federation.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `ruflo federation` — open swarm federation via x.ruv.io (Nostr, signed,
+ * membership-gated). Thin CLI over the x_federation_* MCP tools so the same
+ * behaviour is available in-process and from any MCP client.
+ */
+import type { Command } from '../types.js';
+export declare const federationCommand: Command;
+//# sourceMappingURL=federation.d.ts.map

package/v3/@claude-flow/cli/dist/src/commands/federation.js

@@ -0,0 +1,98 @@
+import { output } from '../output.js';
+import { callMCPTool } from '../mcp-client.js';
+function printJsonOrTable(ctx, data, title) {
+    if (ctx.flags.format === 'json') {
+        output.printJson(data);
+        return;
+    }
+    output.printInfo(title);
+    output.writeln(JSON.stringify(data, null, 2));
+}
+async function run(ctx, tool, args, title) {
+    try {
+        // CLI flag --gateway takes precedence over the RUFLO_X_GATEWAY_URL env var (ADR-125).
+        const data = await callMCPTool(tool, { gatewayUrl: ctx.flags.gateway, ...args });
+        printJsonOrTable(ctx, data, title);
+        return { success: true, data };
+    }
+    catch (e) {
+        output.printError(`${title} failed: ${e.message}`);
+        return { success: false, exitCode: 1 };
+    }
+}
+export const federationCommand = {
+    name: 'federation',
+    description: 'Open swarm federation via x.ruv.io — sync messages, roster, claims, registry, invites (Nostr, signed, membership-gated)',
+    options: [
+        { name: 'format', short: 'f', description: 'Output format (json|text)', type: 'string', default: 'text' },
+        { name: 'gateway', description: 'Gateway base URL (takes precedence over RUFLO_X_GATEWAY_URL; default https://x.ruv.io)', type: 'string' },
+    ],
+    subcommands: [
+        { name: 'join', description: 'Join the open swarm with YOUR OWN key using an invite code (generates ~/.ruflo/nostr.key if absent, claims via NIP-98, verifies via NIP-42)',
+            options: [{ name: 'code', description: 'Invite code (v2.…) — a bearer secret, keep it private', type: 'string', required: true }],
+            action: (ctx) => run(ctx, 'x_federation_join', { code: ctx.flags.code }, 'Join federation') },
+        { name: 'sync', description: 'Fetch recent verified swarm messages',
+            options: [{ name: 'since', description: 'Look-back seconds (default 3600)', type: 'number' }, { name: 'limit', description: 'Max messages', type: 'number' }, { name: 'type', description: 'Filter by message type', type: 'string' }],
+            action: (ctx) => run(ctx, 'x_federation_sync', { sinceSeconds: ctx.flags.since, limit: ctx.flags.limit, type: ctx.flags.type }, 'Federation sync') },
+        { name: 'roster', description: 'Nodes currently announcing on the open swarm', action: (ctx) => run(ctx, 'x_federation_roster', {}, 'Swarm roster') },
+        { name: 'claims', description: 'Current owner-per-resource claims ledger', action: (ctx) => run(ctx, 'x_federation_claims', {}, 'Claims board') },
+        { name: 'registry', description: 'Relay, canonical NIP-42 relay tag, gateway pubkey and self-join steps', action: (ctx) => run(ctx, 'x_federation_registry', {}, 'Federation registry') },
+        { name: 'invite', description: 'Mint a self-join invite code (admin; needs RUFLO_X_ADMIN_TOKEN). The code is a bearer secret — share privately.',
+            options: [{ name: 'ttl', description: 'Validity seconds (default 7d)', type: 'number' }, { name: 'uses', description: 'Max redemptions (default 25)', type: 'number' }],
+            action: (ctx) => run(ctx, 'x_federation_invite_mint', { ttlSecs: ctx.flags.ttl, maxUses: ctx.flags.uses }, 'Invite minted') },
+        { name: 'admit', description: 'Admit a 64-hex Nostr pubkey as relay member (admin; needs RUFLO_X_ADMIN_TOKEN)',
+            options: [{ name: 'pubkey', description: '64-hex pubkey', type: 'string', required: true }, { name: 'role', description: 'member|admin', type: 'string' }],
+            action: (ctx) => run(ctx, 'x_federation_admit', { pubkey: ctx.flags.pubkey, role: ctx.flags.role }, 'Admit member') },
+        { name: 'publish', description: 'Publish a message AS THE GATEWAY (admin; needs RUFLO_X_ADMIN_TOKEN). Nodes should publish with their own key instead.',
+            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;
+                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;
+                        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|channel>'); void ctx; return { success: true }; },
+};
+//# sourceMappingURL=federation.js.map

package/v3/@claude-flow/cli/dist/src/commands/index.d.ts

@@ -17,6 +17,7 @@ export { sessionCommand } from './session.js';
 export { agentCommand } from './agent.js';
 export { swarmCommand } from './swarm.js';
 export { memoryCommand } from './memory.js';
+export { federationCommand } from './federation.js';
 export { mcpCommand } from './mcp.js';
 export { hooksCommand } from './hooks.js';
 export declare function getConfigCommand(): Promise<Command | undefined>;

package/v3/@claude-flow/cli/dist/src/commands/index.js

@@ -138,6 +138,7 @@ import { sessionCommand } from './session.js';
 import { agentCommand } from './agent.js';
 import { swarmCommand } from './swarm.js';
 import { memoryCommand } from './memory.js';
+import { federationCommand } from './federation.js';
 import { mcpCommand } from './mcp.js';
 import { hooksCommand } from './hooks.js';
 // Pre-populate cache with core commands only
@@ -149,6 +150,7 @@ loadedCommands.set('session', sessionCommand);
 loadedCommands.set('agent', agentCommand);
 loadedCommands.set('swarm', swarmCommand);
 loadedCommands.set('memory', memoryCommand);
+loadedCommands.set('federation', federationCommand);
 loadedCommands.set('mcp', mcpCommand);
 loadedCommands.set('hooks', hooksCommand);
 // =============================================================================
@@ -163,6 +165,7 @@ export { sessionCommand } from './session.js';
 export { agentCommand } from './agent.js';
 export { swarmCommand } from './swarm.js';
 export { memoryCommand } from './memory.js';
+export { federationCommand } from './federation.js';
 export { mcpCommand } from './mcp.js';
 export { hooksCommand } from './hooks.js';
 // Lazy-loaded command re-exports (for backwards compatibility, but async-only)
@@ -207,6 +210,7 @@ export const commands = [
     agentCommand,
     swarmCommand,
     memoryCommand,
+    federationCommand,
     mcpCommand,
     hooksCommand,
 ];

package/v3/@claude-flow/cli/dist/src/commands/memory.js

@@ -352,7 +352,14 @@ const searchCommand = {
             name: 'threshold',
             description: 'Similarity threshold (0-1)',
             type: 'number',
-            default: 0.7
+            // MUST stay <= 0.4. The recall fusion in bridgeSearchEntries scores a
+            // full-coverage exact-keyword hit as 0.6*max(0,semantic) + 0.4*lexical,
+            // so when the semantic cosine is <= 0 (routine for a one-word query) a
+            // perfect keyword match tops out at exactly 0.40. #2790 raised this
+            // default to 0.7, which silently re-broke #2558: `memory search` matched
+            // content word-for-word and still returned nothing. Regression guard:
+            // __tests__/memory-search-recall-2558.test.ts.
+            default: 0.3
         },
         {
             name: 'type',
@@ -421,7 +428,7 @@ const searchCommand = {
         // coalescing preserves an explicit zero. Fallback aligned with the
         // option's declared `default: 0.7` (was `0.3` — the two disagreed
         // and --help advertised a default the code did not honor).
-        const threshold = ctx.flags.threshold ?? 0.7;
+        const threshold = ctx.flags.threshold ?? 0.3;
         const searchType = ctx.flags.type || 'semantic';
         const buildHnsw = (ctx.flags['build-hnsw'] || ctx.flags.buildHnsw);
         const requestedIntent = ctx.flags.intent || 'mixed';

package/v3/@claude-flow/cli/dist/src/mcp-client.js

@@ -62,6 +62,10 @@ import { agenticowSpeculateTools } from './mcp-tools/agenticow-speculate-tools.j
 // ADR-164 — AgentBBS federated business-domain BBS rooms (Phase 1).
 // Optional runtime dep, every handler returns `{degraded: true}` when missing.
 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
@@ -167,6 +171,10 @@ registerTools([
     ...agenticowSpeculateTools,
     // ADR-164 — AgentBBS federated business-domain BBS rooms (4 tools, Phase 1, graceful-degraded)
     ...agentbbsTools,
+    ...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,

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

@@ -0,0 +1,178 @@
+/**
+ * agentbbs Phase 2 — cross-host federation.
+ *
+ * Phase 1 (`agentbbs-tools.ts`) gives every host an append-only room log at
+ * `<basePath>/room-<roomId>.jsonl`, and derives `roomId` deterministically from
+ * the room label. Two independent hosts that register `#sales` therefore
+ * compute the *same* roomId without ever talking to each other. That is the
+ * property this module builds on.
+ *
+ * ## Why a signed union-merge, and not a consensus protocol
+ *
+ * A room log is an append-only set of immutable envelopes. Two hosts that each
+ * append locally hold two subsets of the same logical set, so reconciling them
+ * is a set union — there is no conflicting write to arbitrate, and therefore
+ * nothing for a consensus round to decide. Union is commutative, associative
+ * and idempotent, which makes sync order-independent and safe to retry: pulling
+ * the same peer twice, or pulling A-then-B versus B-then-A, converges on the
+ * same log. That is a CRDT (a grow-only set keyed by `envelopeId`), and it is
+ * strictly cheaper and less failure-prone than the Byzantine agreement the
+ * plugin README gestures at.
+ *
+ * What union does *not* give you is authenticity. If any peer can inject an
+ * envelope, the merge faithfully replicates forgeries. So every envelope is
+ * Ed25519-signed by its originating node, and a receiver verifies the signature
+ * against the *pinned* public key it recorded when the peer was added — not
+ * against a key carried in the envelope, which would let an attacker sign with
+ * their own key and claim any origin. Trust is pinned at peer-add time; the
+ * wire is treated as hostile.
+ *
+ * ## Transport
+ *
+ * Pull-based HTTP. A node serves `GET /agentbbs/v1/rooms/:roomId/envelopes?since=N`
+ * and peers poll it. Pull is deliberate: it needs no inbound connectivity from
+ * the peer's side, survives a node being offline (it just catches up later),
+ * and gives the *receiver* control over how much it ingests. Push would invert
+ * that and make every node an unauthenticated write target.
+ *
+ * Designed for a private overlay (Tailscale/WireGuard) where the network
+ * already authenticates the host. Signatures mean a compromised or hostile peer
+ * still cannot forge another node's envelopes. See `bindHost` on serve() — it
+ * binds loopback by default, and binding a routable interface is an explicit
+ * operator choice.
+ *
+ * ## Bounds
+ *
+ * Every ingest path is bounded: envelope count per sync, byte size per envelope,
+ * total bytes per response, peer count, and hop count. An unbounded merge from
+ * an untrusted peer is a memory-exhaustion primitive, so limits are enforced on
+ * the *receiving* side where they cannot be negotiated away by the sender.
+ *
+ * @module @claude-flow/cli/mcp-tools/agentbbs-federation
+ */
+import { type Server } from 'node:http';
+/** Max envelopes accepted from one peer in one sync. */
+export declare const MAX_ENVELOPES_PER_SYNC = 5000;
+/** Max serialized bytes for a single envelope. */
+export declare const MAX_ENVELOPE_BYTES: number;
+/** Max total bytes read from one peer response. */
+export declare const MAX_SYNC_RESPONSE_BYTES: number;
+/** Max peers in the registry. */
+export declare const MAX_PEERS = 256;
+/** Max federation hops before an envelope stops propagating. */
+export declare const MAX_HOPS = 8;
+/** Per-request timeout when pulling from a peer. */
+export declare const SYNC_TIMEOUT_MS = 15000;
+export interface NodeIdentity {
+    nodeId: string;
+    publicKey: string;
+    privateKey: string;
+    createdAt: string;
+}
+export interface FederationPeer {
+    nodeId: string;
+    url: string;
+    publicKey: string;
+    label?: string;
+    addedAt: string;
+    lastSyncedAt?: string;
+    lastSeq?: Record<string, number>;
+}
+export interface SignedEnvelope {
+    envelopeId: string;
+    roomId: string;
+    seq: number;
+    msgType: string;
+    payload: unknown;
+    timestamp: string;
+    origin?: string;
+    hops?: number;
+    signature?: string;
+}
+/**
+ * Deterministic byte string an envelope's signature covers.
+ *
+ * Field order is fixed here rather than relying on `JSON.stringify` key order,
+ * because a receiver must reconstruct byte-identical input from a payload that
+ * survived a JSON round trip. `payload` is canonicalized recursively with
+ * sorted keys for the same reason: `{a:1,b:2}` and `{b:2,a:1}` are the same
+ * value and must not produce different signatures.
+ *
+ * `hops` is deliberately excluded — it is mutated in transit by design, so
+ * including it would invalidate the signature at the first relay.
+ */
+export declare function canonicalEnvelopeBytes(env: SignedEnvelope): Uint8Array;
+/**
+ * Load or create this host's long-lived Ed25519 identity.
+ *
+ * Phase 1 minted an ephemeral key per process, which is fine for local token
+ * signing but useless across hosts: a peer cannot pin a key that changes on
+ * every restart. This persists one, 0600, and derives a stable nodeId from the
+ * public key so identity is verifiable rather than self-asserted.
+ */
+export declare function getNodeIdentity(basePath: string): Promise<NodeIdentity>;
+export declare function signEnvelope(basePath: string, env: SignedEnvelope): Promise<SignedEnvelope>;
+/**
+ * Verify an envelope against a public key the caller already trusts.
+ *
+ * The key is passed in rather than read from the envelope on purpose: an
+ * envelope-carried key proves only that the sender holds *a* key, not that they
+ * are who the `origin` field claims. Callers pass the key pinned at peer-add.
+ */
+export declare function verifyEnvelope(env: SignedEnvelope, publicKeyHex: string): Promise<boolean>;
+export declare function readPeers(basePath: string): FederationPeer[];
+/**
+ * Reject anything that is not a plain http(s) URL to a host.
+ *
+ * Blocks credentials-in-URL (they would be logged), and non-http schemes such
+ * as `file:` which would turn a peer entry into a local file read.
+ */
+export declare function validatePeerUrl(raw: string): string;
+export declare function addPeer(basePath: string, input: {
+    nodeId: string;
+    url: string;
+    publicKey: string;
+    label?: string;
+}): FederationPeer;
+export declare function removePeer(basePath: string, nodeId: string): boolean;
+export declare function readEnvelopes(basePath: string, roomId: string): SignedEnvelope[];
+export declare function validateRoomId(roomId: string): string;
+export interface MergeResult {
+    merged: number;
+    skippedDuplicate: number;
+    skippedUnverified: number;
+    skippedOversize: number;
+    skippedHopLimit: number;
+}
+/**
+ * Union-merge verified envelopes from a peer into the local room log.
+ *
+ * Idempotent: `envelopeId` is the merge key, so replaying the same batch is a
+ * no-op. Anything that fails verification is dropped and counted rather than
+ * quarantined — a receiver has no use for an envelope it cannot attribute.
+ */
+export declare function mergeEnvelopes(basePath: string, roomId: string, incoming: SignedEnvelope[], peerPublicKey: string): Promise<MergeResult>;
+/** Pull one room from one peer and merge what verifies. */
+export declare function syncRoomFromPeer(basePath: string, peer: FederationPeer, roomId: string, fetchImpl?: typeof fetch): Promise<MergeResult & {
+    peerNodeId: string;
+    roomId: string;
+}>;
+/**
+ * Serve this node's room logs for peers to pull.
+ *
+ * Binds loopback unless the caller explicitly asks otherwise, so starting a
+ * server never silently exposes room contents on a routable interface. Read
+ * only by construction: there is no route that mutates state, which removes the
+ * whole class of unauthenticated-write attacks that a push design would open.
+ */
+export declare function serveFederation(basePath: string, opts?: {
+    port?: number;
+    bindHost?: string;
+}): Promise<{
+    server: Server;
+    port: number;
+    host: string;
+}>;
+/** Constant-time compare for any future shared-secret paths. */
+export declare function safeEqual(a: string, b: string): boolean;
+//# sourceMappingURL=agentbbs-federation.d.ts.map