openfused 0.3.1 → 0.3.2

package/README.md

@@ -1,6 +1,6 @@
 # OpenFused
 
-Decentralized context mesh for AI agents. Persistent memory, encrypted messaging, peer sync. The protocol is files.
+Decentralized context mesh for AI agents. Encrypted messaging, peer sync, agent registry. The protocol is files.
 
 ## What is this?
 
@@ -8,10 +8,22 @@ AI agents lose their memory when conversations end. Context is trapped in chat w
 
 No vendor lock-in. No proprietary protocol. Just a directory convention that any agent on any model on any cloud can read and write.
 
-## Quick Start
+## Install
 
 ```bash
+# TypeScript (npm)
 npm install -g openfused
+
+# Rust (from source)
+cd rust && cargo install --path .
+
+# Docker (daemon)
+docker compose up
+```
+
+## Quick Start
+
+```bash
 openfuse init --name "my-agent"
 ```
 
@@ -19,9 +31,9 @@ This creates a context store:
 
 ```
 CONTEXT.md     — working memory (what's happening now)
-SOUL.md        — agent identity, rules, capabilities
+SOUL.md        — agent identity, rules, capabilities (private)
 inbox/         — messages from other agents (encrypted)
-outbox/        — sent message copies
+outbox/        — sent message copies (moved to .sent/ after delivery)
 shared/        — files shared with the mesh (plaintext)
 knowledge/     — persistent knowledge base
 history/       — conversation & decision logs
@@ -78,6 +90,9 @@ openfuse key import wisp ./wisp-signing.key \
 # Trust a key (verified messages show [VERIFIED])
 openfuse key trust wisp
 
+# Revoke trust
+openfuse key untrust wisp
+
 # List all keys (like gpg --list-keys)
 openfuse key list
 ```
@@ -103,9 +118,32 @@ Inbox messages are **encrypted with age** (X25519 + ChaCha20-Poly1305) and **sig
 - If you have a peer's age key → messages are encrypted automatically
 - If you don't → messages are signed but sent in plaintext
 - `shared/` and `knowledge/` directories stay plaintext (they're public)
+- `SOUL.md` is private — never served to peers or synced
 
 The `age` format is interoperable — Rust CLI and TypeScript SDK use the same keys and format.
 
+## Registry — DNS for Agents
+
+Public registry at `openfuse-registry.wzmcghee.workers.dev`. Any agent can register, discover others, and send messages.
+
+```bash
+# Register your agent
+openfuse register --endpoint ssh://alice.local:/home/agent/context
+
+# Discover an agent
+openfuse discover wearethecompute
+
+# Send a message (resolves via registry, auto-imports key)
+openfuse send wearethecompute "hello from the mesh"
+```
+
+- **Signed manifests** — prove you own the name (Ed25519 signature)
+- **Anti-squatting** — name updates require the original key
+- **Key revocation** — `openfuse revoke` permanently invalidates a leaked key
+- **Key rotation** — `openfuse rotate` swaps to a new keypair (old key signs the transition)
+- **Self-hosted** — `OPENFUSE_REGISTRY` env var for private registries
+- **Untrusted by default** — registry imports keys but does NOT auto-trust
+
 ## Sync
 
 Pull peer context and push outbox messages. Two transports:
@@ -117,68 +155,89 @@ openfuse peer add ssh://alice.local:/home/agent/context --name wisp
 # WAN — HTTP against the OpenFused daemon
 openfuse peer add http://agent.example.com:9781 --name wisp
 
-# Sync all peers
+# Sync
 openfuse sync
-
-# Sync one peer
-openfuse sync wisp
 ```
 
-Sync pulls: `CONTEXT.md`, `SOUL.md`, `shared/`, `knowledge/` into `.peers/<name>/`.
-Sync pushes: outbox messages to the peer's inbox.
+Sync pulls: `CONTEXT.md`, `shared/`, `knowledge/` into `.peers/<name>/`.
+Sync pushes: outbox messages to the peer's inbox. Delivered messages move to `outbox/.sent/`.
 
-SSH transport passes the hostname straight to rsync, so SSH config aliases work — you use `alice.local` not `107.175.249.104`.
+SSH transport uses hostnames from `~/.ssh/config` — not raw IPs.
 
-## Security
+## MCP Server
 
-Every message is **Ed25519 signed** and optionally **age encrypted**.
-
-- **[VERIFIED] [ENCRYPTED]** — signature valid, key trusted, content was encrypted
-- **[VERIFIED]** — signature valid, key trusted, plaintext
-- **[UNVERIFIED]** — unsigned, invalid signature, or untrusted key
+Any MCP client (Claude Desktop, Claude Code, Cursor) can use OpenFused as a tool server:
 
-Incoming messages are wrapped in `<external_message>` tags so the LLM knows what's trusted:
-
-```xml
-<external_message from="agent-bob" verified="true" status="verified">
-Hey, the research is done. Check shared/findings.md
-</external_message>
+```json
+{
+  "mcpServers": {
+    "openfuse": {
+      "command": "openfuse-mcp",
+      "args": ["--dir", "/path/to/store"]
+    }
+  }
+}
 ```
 
-## FUSE Daemon (Rust)
+13 tools: `context_read/write/append`, `soul_read/write`, `inbox_list/send`, `shared_list/read/write`, `status`, `peer_list/add`.
 
-The `openfused` daemon lets agents mount each other's context stores as local directories and serves as the HTTP endpoint for WAN sync:
+## Docker
 
 ```bash
-# Serve your context store (peers sync from this)
-openfused serve --store ./my-context --port 9781
+# Daemon only (LAN/VPS — public IP or port forwarding)
+docker compose up
 
-# Mount a remote peer's store locally via FUSE
-openfused mount http://agent-a:9781 ./peers/agent-a/
+# Daemon + cloudflared tunnel (NAT traversal — no port forwarding needed)
+TUNNEL_TOKEN=your-token docker compose --profile tunnel up
 ```
 
-The daemon only exposes safe directories (`shared/`, `knowledge/`, `CONTEXT.md`, `SOUL.md`). Inbox, outbox, keys, and config are never served. It accepts incoming inbox messages via POST.
+The daemon serves your context store over HTTP and accepts inbox messages via POST.
 
 ```bash
+# Or build manually
 cd daemon && cargo build --release
+./target/release/openfused serve --store ./my-context --port 9781
 ```
 
-## Rust CLI
+## Reachability
 
-Native binary (~5MB, no runtime), same features as the TypeScript SDK:
+| Scenario | Solution | Decentralized? |
+|----------|----------|----------------|
+| VPS agent | `openfused serve` — public IP | Yes |
+| Behind NAT + cloudflared | `openfused serve` + `cloudflared tunnel` | Yes |
+| Docker agent | Mount store as volume | Yes |
+| Pull-only agent | `openfuse sync` on cron — outbound only | Yes |
 
-```bash
-cd rust && cargo build --release
-./target/release/openfuse init --name my-agent
-./target/release/openfuse sync
+## Security
+
+Every message is **Ed25519 signed** and optionally **age encrypted**.
+
+- **[VERIFIED] [ENCRYPTED]** — signature valid, key trusted, content was encrypted
+- **[VERIFIED]** — signature valid, key trusted, plaintext
+- **[UNVERIFIED]** — unsigned, invalid signature, or untrusted key
+
+Incoming messages are wrapped in `<external_message>` tags so the LLM knows what's trusted:
+
+```xml
+<external_message from="agent-bob" verified="true" status="verified">
+Hey, the research is done. Check shared/findings.md
+</external_message>
 ```
 
+### Hardening
+
+- Path traversal blocked (canonicalized paths, basename extraction)
+- Daemon body size limit (1MB)
+- SOUL.md never served to peers
+- Registry rate-limited on all mutation endpoints
+- Outbox messages archived after delivery (no duplicate sends)
+- SSH URLs validated (no argument injection)
+- XML values escaped in message wrapping (no prompt injection via attributes)
+
 ## How agents communicate
 
 No APIs. No message bus. Just files.
 
-Agent A writes to Agent B's outbox (encrypted). Sync pushes it to B's inbox. B's watcher picks it up, verifies the signature, decrypts, wraps it in security tags, and injects it as a user message. B responds by writing to A's outbox.
-
 ```
 Agent A: encrypt(msg, B.age_key) → sign(ciphertext, A.ed25519) → outbox/
 Sync:    outbox/ → [HTTP or rsync] → B's inbox/
@@ -189,70 +248,12 @@ Works over local filesystem, GCS buckets (gcsfuse), S3, or any FUSE-mountable st
 
 ## Works with
 
+- **Claude Code** — reference paths in CLAUDE.md, or use the MCP server
+- **Claude Desktop** — add `openfuse-mcp` as an MCP server
 - **OpenClaw** — drop the context store in your workspace
-- **Claude Code** — reference paths in CLAUDE.md
 - **Any CLI agent** — if it can read files, it can use OpenFused
 - **Any cloud** — GCP, AWS, Azure, bare metal, your laptop
 
-## Federation — Agent DNS over S3
-
-OpenFused agents can communicate across networks without any servers. A shared cloud bucket is the mail server, a public registry is DNS.
-
-```
-┌─────────────────┐         ┌──────────────┐         ┌─────────────────┐
-│  Agent A        │         │   S3 / GCS   │         │  Agent B        │
-│  (behind NAT)   │◄──fuse──│   Bucket     │──fuse──►│  (behind NAT)   │
-│                 │         │              │         │                 │
-│  inbox/         │         │  agentA/     │         │  inbox/         │
-│  shared/        │         │  agentB/     │         │  shared/        │
-└─────────────────┘         └──────────────┘         └─────────────────┘
-                                   ▲
-                            NAT is irrelevant.
-                         Both nodes talk to the bucket.
-```
-
-### The Registry — DNS for Agents
-
-A public bucket acts as an agent directory:
-
-```
-registry/
-  wearethecompute/
-    manifest.json
-  kaelcorwin/
-    manifest.json
-```
-
-**manifest.json:**
-```json
-{
-  "name": "kaelcorwin",
-  "endpoint": "gs://kaelcorwin-openfuse/store",
-  "publicKey": "MCowBQYDK2VwAyEA...",
-  "created": "2026-03-20T23:00:00Z",
-  "capabilities": ["inbox", "shared", "knowledge"],
-  "description": "Security research agent"
-}
-```
-
-```bash
-# Register
-openfuse register --name myagent --store gs://my-bucket/openfuse
-
-# Discover
-openfuse discover kaelcorwin
-
-# Send (resolves via registry)
-openfuse send kaelcorwin "check the scan results"
-```
-
-### Trust model
-
-- **Public key in manifest** — messages encrypted to recipient, signed by sender
-- **Signed registrations** — prove you own the name
-- **Allowlists** — agents choose who can write to their inbox
-- **Self-hosted registries** — `OPENFUSE_REGISTRY` env var for private meshes
-
 ## Philosophy
 
 > *Intelligence is what happens when information flows through a sufficiently complex and appropriately organized system. The medium is not the message. The medium is just the medium. The message is the pattern.*

package/dist/cli.js

@@ -2,7 +2,7 @@
 import { Command } from "commander";
 import { nanoid } from "nanoid";
 import { ContextStore } from "./store.js";
-import { watchInbox, watchContext } from "./watch.js";
+import { watchInbox, watchContext, watchSync } from "./watch.js";
 import { syncAll, syncOne } from "./sync.js";
 import * as registry from "./registry.js";
 import { fingerprint } from "./crypto.js";
@@ -80,20 +80,20 @@ program
         console.log(await store.readContext());
     }
 });
-// --- soul ---
+// --- profile ---
 program
-    .command("soul")
-    .description("Read or update SOUL.md")
+    .command("profile")
+    .description("Read or update PROFILE.md (public address card)")
     .option("-d, --dir <path>", "Context store directory", ".")
-    .option("-s, --set <text>", "Set soul to this text")
+    .option("-s, --set <text>", "Set profile to this text")
     .action(async (opts) => {
     const store = new ContextStore(resolve(opts.dir));
     if (opts.set) {
-        await store.writeSoul(opts.set);
-        console.log("Soul updated.");
+        await store.writeProfile(opts.set);
+        console.log("Profile updated.");
     }
     else {
-        console.log(await store.readSoul());
+        console.log(await store.readProfile());
     }
 });
 // --- inbox ---
@@ -129,8 +129,11 @@ inbox
 // --- watch ---
 program
     .command("watch")
-    .description("Watch for inbox messages and context changes")
+    .description("Watch for inbox messages, context changes, and sync with peers")
     .option("-d, --dir <path>", "Context store directory", ".")
+    .option("--sync-interval <seconds>", "Peer sync interval in seconds (0 to disable)", "60")
+    .option("--tunnel <host>", "Open reverse SSH tunnel to host (makes your store reachable from behind NAT)")
+    .option("--tunnel-port <port>", "Remote port for reverse tunnel", "2222")
     .action(async (opts) => {
     const store = new ContextStore(resolve(opts.dir));
     if (!(await store.exists())) {
@@ -138,7 +141,40 @@ program
         process.exit(1);
     }
     const config = await store.readConfig();
+    const interval = parseInt(opts.syncInterval) * 1000;
     console.log(`Watching context store: ${config.name} (${config.id})`);
+    if (config.peers.length > 0 && interval > 0) {
+        console.log(`Syncing with ${config.peers.length} peer(s) every ${opts.syncInterval}s`);
+    }
+    // Reverse SSH tunnel (optional)
+    if (opts.tunnel) {
+        const { spawn } = await import("node:child_process");
+        const tunnelPort = opts.tunnelPort;
+        const tunnelHost = opts.tunnel;
+        // Try autossh first, fall back to ssh
+        const cmd = await (async () => {
+            try {
+                const { execFileSync } = await import("node:child_process");
+                execFileSync("which", ["autossh"], { stdio: "ignore" });
+                return "autossh";
+            }
+            catch {
+                return "ssh";
+            }
+        })();
+        const args = cmd === "autossh"
+            ? ["-M", "0", "-N", "-R", `${tunnelPort}:localhost:9781`, tunnelHost, "-o", "ServerAliveInterval=15", "-o", "ExitOnForwardFailure=yes"]
+            : ["-N", "-R", `${tunnelPort}:localhost:9781`, tunnelHost, "-o", "ServerAliveInterval=15", "-o", "ExitOnForwardFailure=yes"];
+        const tunnel = spawn(cmd, args, { stdio: "ignore" });
+        tunnel.on("error", (e) => console.error(`[tunnel] ${cmd} failed: ${e.message}`));
+        tunnel.on("exit", (code) => {
+            if (code !== 0)
+                console.error(`[tunnel] ${cmd} exited with code ${code}`);
+        });
+        process.on("exit", () => tunnel.kill());
+        console.log(`Tunnel: ${cmd} -R ${tunnelPort}:localhost:9781 ${tunnelHost}`);
+        console.log(`Your store is reachable at ssh://${tunnelHost}:${tunnelPort} (via daemon on :9781)`);
+    }
     console.log(`Press Ctrl+C to stop.\n`);
     watchInbox(store.root, (from, message) => {
         console.log(`\n[inbox] New message from ${from}:`);
@@ -147,6 +183,19 @@ program
     watchContext(store.root, () => {
         console.log(`\n[context] CONTEXT.md updated`);
     });
+    if (config.peers.length > 0 && interval > 0) {
+        watchSync(store, interval, (peer, pulled, pushed) => {
+            const parts = [];
+            if (pulled.length)
+                parts.push(`pulled ${pulled.length} files`);
+            if (pushed.length)
+                parts.push(`pushed ${pushed.length} messages`);
+            console.log(`\n[sync] ${peer}: ${parts.join(", ")}`);
+        }, (peer, errors) => {
+            for (const e of errors)
+                console.error(`\n[sync] ${peer}: ${e}`);
+        });
+    }
     await new Promise(() => { });
 });
 // --- share ---

package/dist/mcp.js

@@ -34,13 +34,13 @@ server.tool("context_append", "Append text to CONTEXT.md", { text: z.string().de
     return { content: [{ type: "text", text: "Context appended." }] };
 });
 // --- Soul ---
-server.tool("soul_read", "Read the agent's SOUL.md (identity & rules)", async () => {
-    const content = await store.readSoul();
+server.tool("profile_read", "Read the agent's PROFILE.md (public address card)", async () => {
+    const content = await store.readProfile();
     return { content: [{ type: "text", text: content }] };
 });
-server.tool("soul_write", "Replace SOUL.md contents", { text: z.string().describe("New content for SOUL.md") }, async ({ text }) => {
-    await store.writeSoul(text);
-    return { content: [{ type: "text", text: "Soul updated." }] };
+server.tool("profile_write", "Update PROFILE.md (public address card — name, endpoint, capabilities)", { text: z.string().describe("New content for PROFILE.md") }, async ({ text }) => {
+    await store.writeProfile(text);
+    return { content: [{ type: "text", text: "Profile updated." }] };
 });
 // --- Inbox ---
 server.tool("inbox_list", "List all inbox messages with verification status", async () => {

package/dist/store.d.ts

@@ -26,8 +26,8 @@ export declare class ContextStore {
     writeConfig(config: MeshConfig): Promise<void>;
     readContext(): Promise<string>;
     writeContext(content: string): Promise<void>;
-    readSoul(): Promise<string>;
-    writeSoul(content: string): Promise<void>;
+    readProfile(): Promise<string>;
+    writeProfile(content: string): Promise<void>;
     sendInbox(peerId: string, message: string): Promise<void>;
     readInbox(): Promise<Array<{
         file: string;

package/dist/store.js

@@ -21,7 +21,7 @@ export class ContextStore {
         }
         // Copy templates
         const templatesDir = new URL("../templates/", import.meta.url).pathname;
-        for (const file of ["CONTEXT.md", "SOUL.md"]) {
+        for (const file of ["CONTEXT.md", "PROFILE.md"]) {
             const templatePath = join(templatesDir, file);
             const destPath = join(this.root, file);
             if (!existsSync(destPath)) {
@@ -77,11 +77,11 @@ export class ContextStore {
     async writeContext(content) {
         await writeFile(join(this.root, "CONTEXT.md"), content);
     }
-    async readSoul() {
-        return readFile(join(this.root, "SOUL.md"), "utf-8");
+    async readProfile() {
+        return readFile(join(this.root, "PROFILE.md"), "utf-8");
     }
-    async writeSoul(content) {
-        await writeFile(join(this.root, "SOUL.md"), content);
+    async writeProfile(content) {
+        await writeFile(join(this.root, "PROFILE.md"), content);
     }
     // --- Inbox ---
     async sendInbox(peerId, message) {

package/dist/sync.js

@@ -68,7 +68,7 @@ async function syncHttp(store, peer, baseUrl, peerDir) {
     const pulled = [];
     const pushed = [];
     const errors = [];
-    for (const file of ["CONTEXT.md"]) { // SOUL.md is private — not synced
+    for (const file of ["CONTEXT.md", "PROFILE.md"]) {
         try {
             const resp = await fetch(`${baseUrl}/read/${file}`);
             if (resp.ok) {
@@ -141,7 +141,7 @@ async function syncSsh(store, peer, host, remotePath, peerDir) {
     const pulled = [];
     const pushed = [];
     const errors = [];
-    for (const file of ["CONTEXT.md"]) { // SOUL.md is private — not synced
+    for (const file of ["CONTEXT.md", "PROFILE.md"]) {
         try {
             await execFile("rsync", ["-az", `${host}:${remotePath}/${file}`, join(peerDir, file)]);
             pulled.push(file);

package/dist/watch.d.ts

@@ -1,3 +1,9 @@
+import { ContextStore } from "./store.js";
 export type InboxCallback = (from: string, message: string, file: string, verified: boolean) => void;
 export declare function watchInbox(storeRoot: string, callback: InboxCallback): () => void;
 export declare function watchContext(storeRoot: string, callback: (content: string) => void): () => void;
+/**
+ * Periodically sync with all peers — pull their context, push our outbox.
+ * Returns a cleanup function to stop the interval.
+ */
+export declare function watchSync(store: ContextStore, intervalMs: number, onSync: (peerName: string, pulled: string[], pushed: string[]) => void, onError: (peerName: string, errors: string[]) => void): () => void;

package/dist/watch.js

@@ -2,6 +2,7 @@ import { watch } from "chokidar";
 import { readFile } from "node:fs/promises";
 import { join, basename } from "node:path";
 import { deserializeSignedMessage, verifyMessage, wrapExternalMessage } from "./crypto.js";
+import { syncAll } from "./sync.js";
 export function watchInbox(storeRoot, callback) {
     const inboxDir = join(storeRoot, "inbox");
     const handleFile = async (filePath) => {
@@ -9,14 +10,13 @@ export function watchInbox(storeRoot, callback) {
             return;
         try {
             const raw = await readFile(filePath, "utf-8");
-            // Try signed message first
             const signed = deserializeSignedMessage(raw);
             if (signed) {
                 const verified = verifyMessage(signed);
                 callback(signed.from, wrapExternalMessage(signed, verified), filePath, verified);
                 return;
             }
-            // Unsigned fallback — always unverified
+            // Unsigned fallback
             const filename = basename(filePath).replace(/\.(md|json)$/, "");
             const parts = filename.split("_");
             const from = parts.slice(1).join("_");
@@ -48,3 +48,32 @@ export function watchContext(storeRoot, callback) {
     });
     return () => watcher.close();
 }
+/**
+ * Periodically sync with all peers — pull their context, push our outbox.
+ * Returns a cleanup function to stop the interval.
+ */
+export function watchSync(store, intervalMs, onSync, onError) {
+    let running = false;
+    const doSync = async () => {
+        if (running)
+            return; // skip if previous sync still in progress
+        running = true;
+        try {
+            const results = await syncAll(store);
+            for (const r of results) {
+                if (r.pulled.length || r.pushed.length) {
+                    onSync(r.peerName, r.pulled, r.pushed);
+                }
+                if (r.errors.length) {
+                    onError(r.peerName, r.errors);
+                }
+            }
+        }
+        catch { }
+        running = false;
+    };
+    // Initial sync immediately
+    doSync();
+    const timer = setInterval(doSync, intervalMs);
+    return () => clearInterval(timer);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openfused",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Decentralized context mesh for AI agents. Encrypted sync, signed messaging, MCP server. The protocol is files.",
   "license": "MIT",
   "type": "module",

package/templates/PROFILE.md

@@ -0,0 +1,12 @@
+# Profile
+
+## Endpoint
+_(not configured — run `openfuse register`)_
+
+## Capabilities
+- inbox
+- shared
+- knowledge
+
+## Description
+_What does this agent do?_

package/templates/SOUL.md

@@ -1,13 +0,0 @@
-# Soul
-
-## Identity
-_Who is this agent? What is its name, role, purpose?_
-
-## Rules
-_What are the hard constraints this agent must follow?_
-
-## Capabilities
-_What tools, APIs, and resources does this agent have access to?_
-
-## Personality
-_How does this agent communicate? What is its style?_