openfused 0.3.3 → 0.3.4

package/dist/cli.js

@@ -8,7 +8,7 @@ import * as registry from "./registry.js";
 import { fingerprint } from "./crypto.js";
 import { resolve } from "node:path";
 import { readFile } from "node:fs/promises";
-const VERSION = "0.3.3";
+const VERSION = "0.3.4";
 const program = new Command();
 program
     .name("openfuse")

package/dist/crypto.js

@@ -1,3 +1,8 @@
+// --- Why Ed25519 + age? ---
+// Ed25519: fast, deterministic, no padding oracle attacks, widely supported (SSH, FIDO2, libsodium).
+// age over PGP: simpler API, no config footguns, no Web of Trust baggage — just X25519+ChaCha20-Poly1305.
+// Two separate keypairs because signing (Ed25519) and encryption (X25519) are distinct operations;
+// combining them would violate key-separation best practice.
 import { generateKeyPairSync, sign, verify, createPrivateKey, createPublicKey, createHash } from "node:crypto";
 import { readFile, writeFile, mkdir } from "node:fs/promises";
 import { join } from "node:path";
@@ -27,6 +32,8 @@ export async function hasKeys(storeRoot) {
     return existsSync(join(storeRoot, KEY_DIR, "private.key"));
 }
 // --- Fingerprint ---
+// SHA-256 truncated to 16 bytes, displayed as colon-separated hex pairs (GPG-style).
+// Human-readable so agents can verify identities out-of-band — same UX as SSH fingerprints.
 export function fingerprint(publicKey) {
     const hash = createHash("sha256").update(publicKey).digest();
     const pairs = [];
@@ -64,6 +71,12 @@ export async function signMessage(storeRoot, from, message) {
     const signature = sign(null, payload, privateKey).toString("base64");
     return { from, timestamp, message, signature, publicKey, encrypted: false };
 }
+// --- Encrypt-then-sign ---
+// Encrypt first, then sign the ciphertext. This order matters:
+// 1. Proves WHO sent the ciphertext (non-repudiation on the encrypted blob)
+// 2. Prevents Surreptitious Forwarding — signature covers the encrypted form,
+//    so a relay can't strip the signature and re-sign for a different recipient.
+// 3. Signature is verifiable by anyone without needing the decryption key.
 export async function signAndEncrypt(storeRoot, from, plaintext, recipientAgeKey) {
     const ciphertext = await ageEncrypt(plaintext, recipientAgeKey);
     const encoded = Buffer.from(ciphertext).toString("base64");
@@ -104,6 +117,8 @@ async function ageDecrypt(ciphertext, storeRoot) {
     return await d.decrypt(ciphertext, "text");
 }
 // --- Helpers ---
+// XML envelope wrapping — gives LLMs a structured, parseable format with clear
+// trust signals (verified/UNVERIFIED). HTML-escaped to prevent injection into prompts.
 export function wrapExternalMessage(signed, verified) {
     const status = verified ? "verified" : "UNVERIFIED";
     const esc = (s) => s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");

package/dist/mcp.js

@@ -1,12 +1,18 @@
 #!/usr/bin/env node
+// --- MCP server: 13 tools ---
+// Why exactly 13? They map 1:1 to the store's capabilities — no more, no less.
+// CRUD for context (read/write/append), profile (read/write), inbox (list/send),
+// shared files (list/read/write), status, and peer management (list/add).
+// Every tool an LLM needs to be a full participant in the mesh, nothing it doesn't.
+// stdio transport because MCP clients (Claude Desktop, Cursor) expect it.
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { ContextStore } from "./store.js";
 import { resolve } from "node:path";
-/** Reject path traversal in filenames — extract basename, block dangerous patterns */
+// LLMs will pass whatever filenames users ask for — including "../../etc/shadow".
+// This is the trust boundary between the AI and the filesystem.
 function sanitizeFilename(name) {
-    // Extract basename (strip any directory components)
     const base = name.split("/").pop().split("\\").pop();
     if (!base || base === "." || base === ".." || base.includes("..")) {
         throw new Error(`Invalid filename: ${name}`);
@@ -17,7 +23,7 @@ const storeDir = process.env.OPENFUSE_DIR || process.argv[3] || ".";
 const store = new ContextStore(resolve(storeDir));
 const server = new McpServer({
     name: "openfuse",
-    version: "0.3.3",
+    version: "0.3.4",
 });
 // --- Context ---
 server.tool("context_read", "Read the agent's CONTEXT.md (working memory)", async () => {

package/dist/registry.js

@@ -1,3 +1,11 @@
+// --- Registry: DNS + keyserver hybrid ---
+// The registry solves agent discovery without requiring a DHT or blockchain.
+// It's a signed directory: agents register name→endpoint+publicKey mappings,
+// similar to DNS (name resolution) + PGP keyservers (key distribution).
+// Crucially, imported keys are UNTRUSTED by default — the local agent must
+// explicitly `openfuse key trust` after out-of-band verification (fingerprint check).
+// This is TOFU (Trust On First Use) done right: the registry distributes keys,
+// but never asserts trust. Trust is a local decision.
 import { signMessage, fingerprint } from "./crypto.js";
 export const DEFAULT_REGISTRY = "https://openfuse-registry.wzmcghee.workers.dev";
 export function resolveRegistry(flag) {
@@ -16,6 +24,8 @@ export async function register(store, endpoint, registry) {
         created: new Date().toISOString(),
         capabilities: ["inbox", "shared", "knowledge"],
     };
+    // Canonical string prevents field-reordering attacks — pipe-delimited, deterministic order.
+    // Signature proves the registrant owns the private key (anti-squatting).
     const canonical = `${manifest.name}|${manifest.endpoint}|${manifest.publicKey}|${manifest.encryptionKey || ""}`;
     const signed = await signMessage(store.root, manifest.name, canonical);
     manifest.signature = signed.signature;
@@ -39,6 +49,8 @@ export async function discover(name, registry) {
     }
     return (await resp.json());
 }
+// Revocation is permanent and self-authenticated: the agent signs its own revocation
+// with the key being revoked. No admin needed — if you have the private key, you can kill it.
 export async function revoke(store, registry) {
     const config = await store.readConfig();
     if (!config.publicKey)
@@ -59,6 +71,7 @@ export async function revoke(store, registry) {
         throw new Error(body.error || `Revocation failed`);
     }
 }
+// Non-blocking version check with 2s timeout — never delays the CLI for a slow network.
 export async function checkUpdate(currentVersion) {
     try {
         const controller = new AbortController();

package/dist/store.js

@@ -1,3 +1,16 @@
+// --- Store convention ---
+// The context store IS the protocol. Every agent is a directory on disk with a known layout:
+//   CONTEXT.md  — working memory (mutable, private)
+//   PROFILE.md  — public address card (replaces SOUL.md: "soul" implied private identity,
+//                 but this file is shared with peers — "profile" is honest about its visibility)
+//   inbox/      — append-only message queue from other agents
+//   outbox/     — signed envelopes waiting to be delivered
+//   shared/     — files explicitly published to peers
+//   history/    — conversation logs
+//   knowledge/  — reference docs
+//   .keys/      — Ed25519 + age keypairs (gitignored)
+//   .mesh.json  — config, peer list, keyring
+// No database, no daemon required. `ls` is your status command.
 import { readFile, writeFile, mkdir, readdir } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { existsSync } from "node:fs";
@@ -44,7 +57,8 @@ export class ContextStore {
     async readConfig() {
         const raw = await readFile(this.configPath, "utf-8");
         const config = JSON.parse(raw);
-        // Migrate legacy trustedKeys → keyring
+        // Migrate legacy trustedKeys → keyring (v0.1 stored bare public keys in a flat array;
+        // v0.2+ uses a GPG-style keyring with trust levels, fingerprints, and encryption keys)
         if (config.trustedKeys && config.trustedKeys.length > 0) {
             if (!config.keyring)
                 config.keyring = [];
@@ -95,8 +109,10 @@ export class ContextStore {
         else {
             signed = await signMessage(this.root, config.id, message);
         }
+        // Envelope filename encodes routing metadata so sync can match outbox files to peers
+        // without parsing JSON. Colons/dots replaced to stay filesystem-safe across OS.
         const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
-        const filename = `${timestamp}_${peerId}.json`;
+        const filename = `${timestamp}_from-${config.name}_to-${peerId}.json`;
         await writeFile(join(this.root, "outbox", filename), serializeSignedMessage(signed));
     }
     async readInbox() {
@@ -159,7 +175,8 @@ export class ContextStore {
         return readdir(sharedDir);
     }
     async share(filename, content) {
-        // Sanitize: extract basename, reject traversal
+        // Path traversal defense: basename extraction + ".." rejection.
+        // Critical because MCP tools pass user-supplied filenames directly.
         const base = filename.split("/").pop().split("\\").pop();
         if (!base || base === "." || base === ".." || base.includes("..")) {
             throw new Error(`Invalid filename: ${filename}`);

package/dist/sync.js

@@ -1,10 +1,16 @@
+// --- Transport design ---
+// Two transports, one protocol. HTTP for WAN (daemon serves context over the internet),
+// SSH/rsync for LAN (zero config if you already have SSH keys — uses ~/.ssh/config aliases
+// so agents reference hostnames, never raw IPs that change). Both transports do the same
+// thing: pull CONTEXT.md + PROFILE.md + shared/ + knowledge/, push outbox → peer inbox.
 import { readFile, writeFile, mkdir, readdir, rename } from "node:fs/promises";
 import { join } from "node:path";
 import { existsSync } from "node:fs";
 import { execFile as execFileCb } from "node:child_process";
 import { promisify } from "node:util";
 const execFile = promisify(execFileCb);
-/** Move delivered message from outbox/ to outbox/.sent/ to prevent re-delivery. */
+// Archive instead of delete: preserves audit trail and lets agents review what was sent.
+// Without this, sync would re-deliver the same message every cycle.
 async function archiveSent(outboxDir, fname) {
     const sentDir = join(outboxDir, ".sent");
     await mkdir(sentDir, { recursive: true });
@@ -21,7 +27,8 @@ function parseUrl(url) {
             throw new Error("SSH URL must be ssh://host:/path");
         const host = rest.slice(0, colonIdx);
         const path = rest.slice(colonIdx + 1);
-        // Validate: prevent argument injection via rsync
+        // Prevent argument injection: rsync treats leading "-" as flags, and shell
+        // metacharacters could escape the execFile boundary on some platforms.
         if (host.startsWith("-") || path.startsWith("-")) {
             throw new Error("Invalid SSH URL: host/path cannot start with '-'");
         }
@@ -91,7 +98,8 @@ async function syncHttp(store, peer, baseUrl, peerDir) {
             for (const f of files) {
                 if (f.is_dir)
                     continue;
-                // Sanitize remote filename — extract basename, reject traversal
+                // Remote peer controls this filename — must sanitize before writing to local disk.
+                // Basename extraction blocks "../../../etc/passwd" style traversal from a malicious peer.
                 const safeName = f.name.split("/").pop().split("\\").pop();
                 if (!safeName || safeName.includes(".."))
                     continue;
@@ -112,7 +120,7 @@ async function syncHttp(store, peer, baseUrl, peerDir) {
         for (const fname of await readdir(outboxDir)) {
             if (!fname.endsWith(".json"))
                 continue;
-            if (!fname.includes(peer.name) && !fname.includes(peer.id))
+            if (!fname.includes(`_to-${peer.name}`) && !fname.includes(peer.id))
                 continue;
             try {
                 const body = await readFile(join(outboxDir, fname), "utf-8");
@@ -161,13 +169,35 @@ async function syncSsh(store, peer, host, remotePath, peerDir) {
             errors.push(`${dir}/: ${e.stderr || e.message}`);
         }
     }
-    // Push outbox
+    // Pull peer's outbox for messages addressed to us — peer may be behind NAT
+    // and can't push to us, so we grab messages they left in their outbox for us.
+    const config = await store.readConfig();
+    const myName = config.name;
+    const inboxDir = join(store.root, "inbox");
+    await mkdir(inboxDir, { recursive: true });
+    try {
+        await execFile("rsync", [
+            "-az", "--ignore-existing",
+            "--include", `*_to-${myName}.json`,
+            "--include", `*_to-all.json`,
+            "--exclude", "*",
+            `${host}:${remotePath}/outbox/`,
+            `${inboxDir}/`,
+        ]);
+        pulled.push("outbox→inbox");
+    }
+    catch (e) {
+        if (!String(e.stderr || e.message).includes("No such file")) {
+            errors.push(`pull outbox: ${e.stderr || e.message}`);
+        }
+    }
+    // Push our outbox → peer inbox
     const outboxDir = join(store.root, "outbox");
     if (existsSync(outboxDir)) {
         for (const fname of await readdir(outboxDir)) {
             if (!fname.endsWith(".json"))
                 continue;
-            if (!fname.includes(peer.name) && !fname.includes(peer.id))
+            if (!fname.includes(`_to-${peer.name}`) && !fname.includes(peer.id))
                 continue;
             try {
                 await execFile("rsync", ["-az", join(outboxDir, fname), `${host}:${remotePath}/inbox/${fname}`]);

package/dist/watch.js

@@ -1,3 +1,7 @@
+// --- Watch strategy ---
+// chokidar for local filesystem events (inbox, CONTEXT.md) — instant, inotify-backed on Linux.
+// Polling interval for remote sync (watchSync) — because remote peers are over HTTP/SSH,
+// there's no filesystem event to listen for. Polling is the only option without WebSockets.
 import { watch } from "chokidar";
 import { readFile } from "node:fs/promises";
 import { join, basename } from "node:path";
@@ -25,6 +29,8 @@ export function watchInbox(storeRoot, callback) {
         }
         catch { }
     };
+    // awaitWriteFinish: messages are written by sync (multi-step: create + write + close).
+    // Without stability threshold, we'd fire on half-written files.
     const watcher = watch(inboxDir, {
         ignoreInitial: true,
         awaitWriteFinish: { stabilityThreshold: 500 },
@@ -55,8 +61,11 @@ export function watchContext(storeRoot, callback) {
 export function watchSync(store, intervalMs, onSync, onError) {
     let running = false;
     const doSync = async () => {
+        // Guard against overlapping syncs: if a peer is slow or unreachable, the previous
+        // cycle may still be running when the next interval fires. Overlapping syncs could
+        // double-deliver outbox messages or corrupt in-flight file writes.
         if (running)
-            return; // skip if previous sync still in progress
+            return;
         running = true;
         try {
             const results = await syncAll(store);

package/package.json

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