libp2p-mesh 2026.5.13 → 2026.5.15

package/dist/src/dht-registry.js

@@ -0,0 +1,80 @@
+/**
+ * DHT-based public key registry for cross-instance identity verification.
+ *
+ * Each OpenClaw instance publishes its Ed25519 pubkey to the DHT under the key:
+ *   openclaw:pubkey:<instanceId>
+ *
+ * Other instances can look up this pubkey to verify message signatures.
+ */
+const DHT_KEY_PREFIX = "openclaw:pubkey:";
+const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+const pubkeyCache = new Map();
+function encodeKey(instanceId) {
+    return new TextEncoder().encode(`${DHT_KEY_PREFIX}${instanceId}`);
+}
+/**
+ * Register this instance's pubkey in the DHT.
+ * Other nodes can later look it up to verify signatures from this instance.
+ */
+export async function registerPubkey(dht, instanceId, pubkey, logger) {
+    const key = encodeKey(instanceId);
+    const value = new TextEncoder().encode(pubkey);
+    try {
+        for await (const event of dht.put(key, value)) {
+            // Drain the async iterable; put completes when the iterable ends
+            logger?.info?.(`[dht-registry] put event: ${event.name}`);
+        }
+        logger?.info?.(`[dht-registry] Registered pubkey for ${instanceId}`);
+    }
+    catch (err) {
+        logger?.warn?.(`[dht-registry] Failed to register pubkey: ${String(err)}`);
+        // Non-fatal: identity verification may degrade but mesh continues
+    }
+}
+/**
+ * Look up a pubkey from the DHT for the given instanceId.
+ * Results are cached locally to avoid repeated DHT queries.
+ */
+export async function lookupPubkey(dht, instanceId, logger) {
+    // 1. Check local cache
+    const cached = pubkeyCache.get(instanceId);
+    if (cached && cached.expiry > Date.now()) {
+        logger?.debug?.(`[dht-registry] Cache hit for ${instanceId}`);
+        return cached.pubkey;
+    }
+    // 2. Query DHT
+    const key = encodeKey(instanceId);
+    try {
+        for await (const event of dht.get(key)) {
+            if (event.name === "VALUE") {
+                const pubkey = new TextDecoder().decode(event.value);
+                pubkeyCache.set(instanceId, {
+                    pubkey,
+                    expiry: Date.now() + CACHE_TTL_MS,
+                });
+                logger?.info?.(`[dht-registry] DHT lookup success for ${instanceId}`);
+                return pubkey;
+            }
+        }
+    }
+    catch (err) {
+        logger?.warn?.(`[dht-registry] DHT lookup failed for ${instanceId}: ${String(err)}`);
+    }
+    logger?.info?.(`[dht-registry] No pubkey found for ${instanceId}`);
+    return undefined;
+}
+/**
+ * Clear the local pubkey cache.
+ */
+export function clearPubkeyCache() {
+    pubkeyCache.clear();
+}
+/**
+ * Get cache stats for observability.
+ */
+export function getCacheStats() {
+    return {
+        size: pubkeyCache.size,
+        keys: Array.from(pubkeyCache.keys()),
+    };
+}

package/dist/src/inbound.d.ts

@@ -1,5 +1,4 @@
 import type { P2PMessage } from "./types.js";
-import type { FeishuApiClient } from "./feishu-client.js";
 export type InboundHandlerDeps = {
     logger?: {
         info?: (msg: string) => void;
@@ -7,7 +6,5 @@ export type InboundHandlerDeps = {
         warn?: (msg: string) => void;
         error?: (msg: string) => void;
     };
-    sendToChannel?: (channelId: string, target: string, text: string) => Promise<void>;
-    feishuClient?: FeishuApiClient;
 };
 export declare function handleP2PInbound(msg: P2PMessage, deps: InboundHandlerDeps): void;

package/dist/src/inbound.js

@@ -1,20 +1,35 @@
+import { verifyInstanceSignature } from "./instance-id.js";
 export function handleP2PInbound(msg, deps) {
-    const { logger, sendToChannel, feishuClient } = deps;
-    if (msg.type === "broadcast") {
-        logger?.info?.(`[libp2p-mesh] Broadcast from ${msg.from} on topic ${msg.topic ?? "(none)"}: ${msg.payload}`);
+    const { logger } = deps;
+    const instanceTag = msg.instanceId ? ` [instance: ${msg.instanceId}]` : "";
+    const signedTag = msg.signature ? " [signed]" : "";
+    // Verify signature if present
+    if (msg.signature && msg.instanceId && msg.pubkey) {
+        const signedPayload = JSON.stringify({
+            id: msg.id,
+            type: msg.type,
+            from: msg.from,
+            to: msg.to,
+            topic: msg.topic,
+            payload: msg.payload,
+            timestamp: msg.timestamp,
+            instanceId: msg.instanceId,
+        });
+        const valid = verifyInstanceSignature({ id: msg.instanceId, name: "", pubkey: msg.pubkey, binding: "", bindingComponents: { username: "", hostname: "", platform: "" }, createdAt: 0 }, signedPayload, msg.signature);
+        if (valid) {
+            logger?.info?.(`[libp2p-mesh] Verified signature from instance ${msg.instanceId}`);
+        }
+        else {
+            logger?.warn?.(`[libp2p-mesh] Invalid signature from instance ${msg.instanceId}`);
+        }
     }
-    else {
-        logger?.info?.(`[libp2p-mesh] Direct message from ${msg.from}: ${msg.payload}`);
+    else if (msg.signature) {
+        logger?.warn?.(`[libp2p-mesh] Message has signature but no pubkey; cannot verify`);
     }
-    if (msg.type !== "broadcast" && sendToChannel && msg.payload) {
-        const text = `[来自 ${msg.from}]\n${msg.payload}`;
-        sendToChannel("libp2p-mesh", msg.from, text).catch((err) => {
-            logger?.error?.(`[libp2p-mesh] Failed to forward direct message from ${msg.from}: ${err}`);
-        });
+    if (msg.type === "broadcast") {
+        logger?.info?.(`[libp2p-mesh] Broadcast from ${msg.from}${instanceTag}${signedTag} on topic ${msg.topic ?? "(none)"}: ${msg.payload}`);
     }
-    if (feishuClient && msg.payload) {
-        feishuClient.sendMessage(msg.from, msg.payload).catch(() => {
-            logger?.warn?.("[libp2p-mesh] Failed to forward P2P message to Feishu");
-        });
+    else {
+        logger?.info?.(`[libp2p-mesh] Direct message from ${msg.from}${instanceTag}${signedTag}: ${msg.payload}`);
     }
 }

package/dist/src/instance-id.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Lightweight Instance Identity module inspired by BAID (Binding Agent ID).
+ *
+ * BAID core idea: bind multiple identity dimensions (name, code, profile, user)
+ * into a single cryptographic identity.
+ *
+ * Our lightweight adaptation:
+ * - Ed25519 keypair for self-sovereign identity (provable via signatures)
+ * - Multi-dimensional binding hash: username + hostname + platform
+ * - InstanceID format: name@<pubkey_b64url[0:12]>.<binding[0:8]>
+ * - Persistent storage in ~/.openclaw/libp2p/instance-id.json
+ */
+export interface InstanceIdentity {
+    /** Full InstanceID string, e.g. "alice-mac@AQIDBAUGBweI.7a3f9e2b" */
+    id: string;
+    /** Human-readable instance name */
+    name: string;
+    /** Base64url-encoded Ed25519 public key (SPKI/DER) */
+    pubkey: string;
+    /** Hex SHA-256 binding hash of environment dimensions */
+    binding: string;
+    /** Components that contributed to the binding hash */
+    bindingComponents: {
+        username: string;
+        hostname: string;
+        platform: string;
+    };
+    /** Timestamp when the identity was created */
+    createdAt: number;
+}
+interface PersistedIdentity extends InstanceIdentity {
+    /** Base64url-encoded Ed25519 private key (PKCS8/DER) — stored for signing */
+    privkey: string;
+}
+export interface InstanceIDOptions {
+    /** Custom instance name (defaults to "<username>-<hostname>") */
+    name?: string;
+    /** Custom storage path for the identity file */
+    customPath?: string;
+}
+export declare function generateInstanceIdentity(options?: InstanceIDOptions): PersistedIdentity;
+export declare function loadOrCreateInstanceIdentity(options?: InstanceIDOptions): Promise<{
+    identity: InstanceIdentity;
+    signMessage: (message: string) => string;
+}>;
+export declare function verifyInstanceSignature(identity: InstanceIdentity, message: string, signature: string): boolean;
+export declare function verifyInstanceIDBinding(identity: InstanceIdentity): {
+    valid: boolean;
+    currentBinding: string;
+    mismatch?: string;
+};
+export declare function formatInstanceIDForDisplay(identity: InstanceIdentity): string;
+export {};

package/dist/src/instance-id.js

@@ -0,0 +1,156 @@
+/**
+ * Lightweight Instance Identity module inspired by BAID (Binding Agent ID).
+ *
+ * BAID core idea: bind multiple identity dimensions (name, code, profile, user)
+ * into a single cryptographic identity.
+ *
+ * Our lightweight adaptation:
+ * - Ed25519 keypair for self-sovereign identity (provable via signatures)
+ * - Multi-dimensional binding hash: username + hostname + platform
+ * - InstanceID format: name@<pubkey_b64url[0:12]>.<binding[0:8]>
+ * - Persistent storage in ~/.openclaw/libp2p/instance-id.json
+ */
+import { createHash, generateKeyPairSync, sign, verify } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir, hostname, platform, userInfo } from "node:os";
+import path from "node:path";
+function resolveInstanceIDPath(customPath) {
+    if (customPath)
+        return customPath;
+    const stateDir = process.env.OPENCLAW_STATE_DIR;
+    if (stateDir) {
+        return path.join(stateDir, "libp2p", "instance-id.json");
+    }
+    return path.join(homedir(), ".openclaw", "libp2p", "instance-id.json");
+}
+function getBindingComponents() {
+    let username;
+    try {
+        username = userInfo().username;
+    }
+    catch {
+        username = process.env.USER || process.env.USERNAME || "unknown";
+    }
+    return {
+        username,
+        hostname: hostname(),
+        platform: platform(),
+    };
+}
+function computeBindingHash(components) {
+    const data = `${components.username}::${components.hostname}::${components.platform}`;
+    return createHash("sha256").update(data).digest("hex");
+}
+function getDefaultName() {
+    const { username, hostname: h } = getBindingComponents();
+    const shortHost = h.split(".")[0];
+    return `${username}-${shortHost}`;
+}
+function generateEd25519KeyPair() {
+    const { publicKey, privateKey } = generateKeyPairSync("ed25519", {
+        publicKeyEncoding: { type: "spki", format: "der" },
+        privateKeyEncoding: { type: "pkcs8", format: "der" },
+    });
+    return { publicKey: Buffer.from(publicKey), privateKey: Buffer.from(privateKey) };
+}
+function pubkeyShort(pubkey) {
+    return pubkey.toString("base64url").slice(0, 12);
+}
+function bindingShort(binding) {
+    return binding.slice(0, 8);
+}
+export function generateInstanceIdentity(options = {}) {
+    const name = options.name?.trim() || getDefaultName();
+    const { publicKey, privateKey } = generateEd25519KeyPair();
+    const bindingComponents = getBindingComponents();
+    const binding = computeBindingHash(bindingComponents);
+    const id = `${name}@${pubkeyShort(publicKey)}.${bindingShort(binding)}`;
+    return {
+        id,
+        name,
+        pubkey: publicKey.toString("base64url"),
+        privkey: privateKey.toString("base64url"),
+        binding,
+        bindingComponents,
+        createdAt: Date.now(),
+    };
+}
+export async function loadOrCreateInstanceIdentity(options = {}) {
+    const filePath = resolveInstanceIDPath(options.customPath);
+    try {
+        const raw = await readFile(filePath, "utf8");
+        const persisted = JSON.parse(raw);
+        // Validate that the stored identity still matches this environment
+        const currentComponents = getBindingComponents();
+        const currentBinding = computeBindingHash(currentComponents);
+        if (persisted.binding !== currentBinding) {
+            // Environment changed (e.g. migrated to new machine) — regenerate
+            const fresh = generateInstanceIdentity(options);
+            await mkdir(path.dirname(filePath), { recursive: true });
+            await writeFile(filePath, JSON.stringify(fresh, null, 2));
+            return {
+                identity: stripPrivateKey(fresh),
+                signMessage: (msg) => signWithKey(Buffer.from(fresh.privkey, "base64url"), msg),
+            };
+        }
+        return {
+            identity: stripPrivateKey(persisted),
+            signMessage: (msg) => signWithKey(Buffer.from(persisted.privkey, "base64url"), msg),
+        };
+    }
+    catch {
+        // File doesn't exist or is corrupt — create new identity
+        const fresh = generateInstanceIdentity(options);
+        await mkdir(path.dirname(filePath), { recursive: true });
+        await writeFile(filePath, JSON.stringify(fresh, null, 2));
+        return {
+            identity: stripPrivateKey(fresh),
+            signMessage: (msg) => signWithKey(Buffer.from(fresh.privkey, "base64url"), msg),
+        };
+    }
+}
+function stripPrivateKey(persisted) {
+    const { privkey: _, ...identity } = persisted;
+    return identity;
+}
+function signWithKey(privateKey, message) {
+    const sig = sign(null, Buffer.from(message, "utf8"), {
+        key: privateKey,
+        format: "der",
+        type: "pkcs8",
+    });
+    return sig.toString("base64url");
+}
+export function verifyInstanceSignature(identity, message, signature) {
+    try {
+        const pubkeyBuffer = Buffer.from(identity.pubkey, "base64url");
+        return verify(null, Buffer.from(message, "utf8"), { key: pubkeyBuffer, format: "der", type: "spki" }, Buffer.from(signature, "base64url"));
+    }
+    catch {
+        return false;
+    }
+}
+export function verifyInstanceIDBinding(identity) {
+    const currentComponents = getBindingComponents();
+    const currentBinding = computeBindingHash(currentComponents);
+    if (identity.binding !== currentBinding) {
+        return {
+            valid: false,
+            currentBinding,
+            mismatch: `Stored binding ${identity.binding.slice(0, 8)} does not match current environment ${currentBinding.slice(0, 8)}`,
+        };
+    }
+    return { valid: true, currentBinding };
+}
+export function formatInstanceIDForDisplay(identity) {
+    const { bindingComponents, createdAt } = identity;
+    const date = new Date(createdAt).toLocaleString();
+    return [
+        `Instance ID: ${identity.id}`,
+        `Name:        ${identity.name}`,
+        `Pubkey:      ${identity.pubkey.slice(0, 24)}...`,
+        `Binding:     ${identity.binding.slice(0, 16)}...`,
+        `Bound to:    ${bindingComponents.username}@${bindingComponents.hostname} (${bindingComponents.platform})`,
+        `Created:     ${date}`,
+    ].join("\n");
+}