@botcord/openclaw-plugin 0.0.2

package/src/crypto.ts

@@ -0,0 +1,155 @@
+/**
+ * Ed25519 signing for BotCord protocol.
+ * Zero npm dependencies — uses Node.js built-in crypto module.
+ * Ported from botcord-skill/skill/botcord-crypto.mjs.
+ */
+import {
+  createHash,
+  createPublicKey,
+  createPrivateKey,
+  generateKeyPairSync,
+  sign,
+  randomUUID,
+} from "node:crypto";
+import type { BotCordMessageEnvelope, BotCordSignature, MessageType } from "./types.js";
+
+// ── JCS (RFC 8785) canonicalization ─────────────────────────────
+export function jcsCanonicalize(value: unknown): string | undefined {
+  if (value === null || typeof value === "boolean") return JSON.stringify(value);
+  if (typeof value === "number") {
+    if (Object.is(value, -0)) return "0";
+    return JSON.stringify(value);
+  }
+  if (typeof value === "string") return JSON.stringify(value);
+  if (Array.isArray(value))
+    return "[" + value.map((v) => jcsCanonicalize(v)).join(",") + "]";
+  if (typeof value === "object") {
+    const keys = Object.keys(value as Record<string, unknown>).sort();
+    const parts: string[] = [];
+    for (const k of keys) {
+      const v = (value as Record<string, unknown>)[k];
+      if (v === undefined) continue;
+      parts.push(JSON.stringify(k) + ":" + jcsCanonicalize(v));
+    }
+    return "{" + parts.join(",") + "}";
+  }
+  return undefined;
+}
+
+// ── Build Node.js KeyObject from raw 32-byte seed ───────────────
+function privateKeyFromSeed(seed: Buffer): ReturnType<typeof createPrivateKey> {
+  const prefix = Buffer.from("302e020100300506032b657004220420", "hex");
+  return createPrivateKey({
+    key: Buffer.concat([prefix, seed]),
+    format: "der",
+    type: "pkcs8",
+  });
+}
+
+// ── Payload hash ────────────────────────────────────────────────
+export function computePayloadHash(payload: Record<string, unknown>): string {
+  const canonical = jcsCanonicalize(payload)!;
+  const digest = createHash("sha256").update(canonical).digest("hex");
+  return `sha256:${digest}`;
+}
+
+// ── Sign challenge ──────────────────────────────────────────────
+export function signChallenge(privateKeyB64: string, challengeB64: string): string {
+  const pk = privateKeyFromSeed(Buffer.from(privateKeyB64, "base64"));
+  const sig = sign(null, Buffer.from(challengeB64, "base64"), pk);
+  return sig.toString("base64");
+}
+
+export function derivePublicKey(privateKeyB64: string): string {
+  const privateKey = privateKeyFromSeed(Buffer.from(privateKeyB64, "base64"));
+  const publicKey = createPublicKey(privateKey);
+  const pubDer = publicKey.export({ type: "spki", format: "der" });
+  return Buffer.from(pubDer.subarray(-32)).toString("base64");
+}
+
+// ── Build and sign a full message envelope ──────────────────────
+export function buildSignedEnvelope(params: {
+  from: string;
+  to: string;
+  type: MessageType;
+  payload: Record<string, unknown>;
+  privateKey: string; // base64 Ed25519 seed
+  keyId: string;
+  replyTo?: string | null;
+  ttlSec?: number;
+  topic?: string | null;
+  goal?: string | null;
+}): BotCordMessageEnvelope {
+  const {
+    from,
+    to,
+    type,
+    payload,
+    privateKey,
+    keyId,
+    replyTo = null,
+    ttlSec = 3600,
+    topic = null,
+    goal = null,
+  } = params;
+
+  const msgId = randomUUID();
+  const ts = Math.floor(Date.now() / 1000);
+  const payloadHash = computePayloadHash(payload);
+
+  // Build signing input (newline-joined fields)
+  const parts = [
+    "a2a/0.1",
+    msgId,
+    String(ts),
+    from,
+    to,
+    String(type),
+    replyTo || "",
+    String(ttlSec),
+    payloadHash,
+  ];
+
+  const pk = privateKeyFromSeed(Buffer.from(privateKey, "base64"));
+  const sigValue = sign(null, Buffer.from(parts.join("\n")), pk);
+
+  const sig: BotCordSignature = {
+    alg: "ed25519",
+    key_id: keyId,
+    value: sigValue.toString("base64"),
+  };
+
+  return {
+    v: "a2a/0.1",
+    msg_id: msgId,
+    ts,
+    from,
+    to,
+    type,
+    reply_to: replyTo,
+    ttl_sec: ttlSec,
+    topic,
+    goal,
+    payload,
+    payload_hash: payloadHash,
+    sig,
+  };
+}
+
+// ── Keygen ──────────────────────────────────────────────────────
+export function generateKeypair(): {
+  privateKey: string;
+  publicKey: string;
+  pubkeyFormatted: string;
+} {
+  const { publicKey, privateKey } = generateKeyPairSync("ed25519");
+  const privDer = privateKey.export({ type: "pkcs8", format: "der" });
+  const privB64 = Buffer.from(privDer.subarray(-32)).toString("base64");
+  const pubDer = publicKey.export({ type: "spki", format: "der" });
+  const pubB64 = Buffer.from(pubDer.subarray(-32)).toString("base64");
+  return {
+    privateKey: privB64,
+    publicKey: pubB64,
+    pubkeyFormatted: `ed25519:${pubB64}`,
+  };
+}

package/src/inbound.ts

@@ -0,0 +1,305 @@
+/**
+ * Inbound message dispatch — shared by websocket and polling paths.
+ * Converts BotCord messages to OpenClaw inbound format.
+ */
+import { readFile } from "node:fs/promises";
+import { getBotCordRuntime } from "./runtime.js";
+import { resolveAccountConfig } from "./config.js";
+import { buildSessionKey } from "./session-key.js";
+import type { InboxMessage, MessageType } from "./types.js";
+
+// Envelope types that count as notifications rather than normal messages
+const NOTIFICATION_TYPES: ReadonlySet<string> = new Set([
+  "contact_request",
+  "contact_request_response",
+  "contact_removed",
+  "system",
+]);
+
+/**
+ * Build a structured header line for inbound messages, e.g.:
+ *   [BotCord Message] from: Link (ag_xxx) | to: ag_yyy | room: My Room
+ */
+function buildInboundHeader(params: {
+  type: MessageType;
+  senderName: string;
+  accountId: string;
+  chatType: "direct" | "group";
+  roomName?: string;
+}): string {
+  const tag = NOTIFICATION_TYPES.has(params.type)
+    ? "[BotCord Notification]"
+    : "[BotCord Message]";
+
+  const parts = [
+    tag,
+    `from: ${params.senderName}`,
+    `to: ${params.accountId}`,
+  ];
+
+  if (params.chatType === "group" && params.roomName) {
+    parts.push(`room: ${params.roomName}`);
+  }
+
+  return parts.join(" | ");
+}
+
+export interface InboundParams {
+  cfg: any;
+  accountId: string;
+  senderName: string;
+  senderId: string;
+  content: string;
+  messageId?: string;
+  messageType?: MessageType;
+  chatType: "direct" | "group";
+  groupSubject?: string;
+  replyTarget: string;
+  roomId?: string;
+  topic?: string;
+  topicId?: string;
+  mentioned?: boolean;
+}
+
+/**
+ * Shared handler for InboxMessage — used by both WebSocket and Poller paths.
+ * Normalizes InboxMessage into InboundParams and dispatches to OpenClaw.
+ */
+export async function handleInboxMessage(
+  msg: InboxMessage,
+  accountId: string,
+  cfg: any,
+): Promise<void> {
+  const envelope = msg.envelope;
+  const senderId = envelope.from || "unknown";
+  const rawContent =
+    msg.text ||
+    (typeof envelope.payload === "string"
+      ? envelope.payload
+      : envelope.payload?.text ?? JSON.stringify(envelope.payload));
+  // DM rooms have rm_dm_ prefix; only non-DM rooms are true group chats
+  const isGroupRoom = !!msg.room_id && !msg.room_id.startsWith("rm_dm_");
+  const chatType = isGroupRoom ? "group" : "direct";
+
+  const header = buildInboundHeader({
+    type: envelope.type,
+    senderName: senderId,
+    accountId,
+    chatType,
+    roomName: isGroupRoom ? (msg.room_name || msg.room_id) : undefined,
+  });
+  const silentHint =
+    chatType === "group"
+      ? '\n\n[In group chats, do NOT reply unless you are explicitly mentioned or addressed. If no response is needed, reply with exactly "NO_REPLY" and nothing else.]'
+      : '\n\n[If the conversation has naturally concluded or no response is needed, reply with exactly "NO_REPLY" and nothing else.]';
+  const content = `${header}\n${rawContent}${silentHint}`;
+
+  await dispatchInbound({
+    cfg,
+    accountId,
+    senderName: senderId,
+    senderId,
+    content: content as string,
+    messageId: envelope.msg_id,
+    messageType: envelope.type,
+    chatType,
+    groupSubject: isGroupRoom ? (msg.room_name || msg.room_id) : undefined,
+    replyTarget: isGroupRoom ? msg.room_id! : (envelope.from || ""),
+    roomId: msg.room_id,
+    topic: msg.topic,
+    topicId: msg.topic_id,
+    mentioned: msg.mentioned,
+  });
+}
+
+/**
+ * Dispatch an inbound message into OpenClaw's channel routing system.
+ */
+export async function dispatchInbound(params: InboundParams): Promise<void> {
+  const core = getBotCordRuntime();
+  const {
+    cfg,
+    accountId,
+    senderName,
+    senderId,
+    content,
+    messageId,
+    chatType,
+    groupSubject,
+    replyTarget,
+    roomId,
+    topic,
+  } = params;
+
+  const from = `botcord:${senderId}`;
+  const to = `botcord:${accountId}`;
+  const sessionKey = buildSessionKey(roomId, topic, senderId);
+
+  const route = core.channel.routing.resolveAgentRoute({
+    cfg,
+    channel: "botcord",
+    accountId,
+    peer: {
+      kind: chatType,
+      id: chatType === "group" ? (roomId || replyTarget) : senderId,
+    },
+  });
+
+  const envelopeOptions = core.channel.reply.resolveEnvelopeFormatOptions(cfg);
+  const formattedBody = core.channel.reply.formatAgentEnvelope({
+    channel: "BotCord",
+    from: senderName,
+    timestamp: new Date(),
+    envelope: envelopeOptions,
+    body: content,
+  });
+
+  const ctxPayload = core.channel.reply.finalizeInboundContext({
+    Body: formattedBody,
+    BodyForAgent: content,
+    RawBody: content,
+    CommandBody: content,
+    From: from,
+    To: to,
+    SessionKey: route.sessionKey || sessionKey,
+    AccountId: accountId,
+    ChatType: chatType,
+    GroupSubject: chatType === "group" ? (groupSubject || replyTarget) : undefined,
+    SenderName: senderName,
+    SenderId: senderId,
+    Provider: "botcord" as const,
+    Surface: "botcord" as const,
+    MessageSid: messageId || `botcord-${Date.now()}`,
+    Timestamp: Date.now(),
+    WasMentioned: params.chatType === "direct"
+      ? true
+      : (params.mentioned ?? true),
+    CommandAuthorized: true,
+    OriginatingChannel: "botcord" as const,
+    OriginatingTo: to,
+    ConversationLabel: chatType === "group" ? (groupSubject || senderName) : senderName,
+  });
+
+  await core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+    ctx: ctxPayload,
+    cfg,
+    dispatcherOptions: {
+      // A2A replies are sent explicitly via botcord_send tool.
+      // Suppress automatic delivery to avoid leaking agent narration.
+      deliver: async () => {},
+      onError: (err: any, info: any) => {
+        console.error(`[botcord] ${info?.kind ?? "unknown"} reply error:`, err);
+      },
+    },
+    replyOptions: {},
+  });
+
+  // Auto-notify owner for notification-type messages (contact requests, etc.)
+  // Normal messages are NOT auto-notified; the agent can use the
+  // botcord_notify tool to notify the owner when it deems appropriate.
+  const messageType = params.messageType;
+  if (messageType && NOTIFICATION_TYPES.has(messageType)) {
+    const acct = resolveAccountConfig(cfg, accountId);
+    const notifySession = acct.notifySession;
+    if (notifySession) {
+      const childSessionKey = route.sessionKey || sessionKey;
+      if (childSessionKey !== notifySession) {
+        const topicLabel = topic ? ` (topic: ${topic})` : "";
+        const notification =
+          `[BotCord ${messageType}] from ${senderName}${topicLabel}\n` +
+          `Session: ${childSessionKey}\n` +
+          `Preview: ${(params.content || "").slice(0, 200)}`;
+
+        try {
+          await deliverNotification(core, cfg, notifySession, notification);
+        } catch (err: any) {
+          console.error(`[botcord] auto-notify failed:`, err?.message ?? err);
+        }
+      }
+    }
+  }
+}
+
+// ── Notification delivery helpers ───────────────────────────────────
+
+type DeliveryContext = {
+  channel: string;
+  to: string;
+  accountId?: string;
+  threadId?: string;
+};
+
+/**
+ * Read deliveryContext for a session key from the session store on disk.
+ * Returns undefined when the session has no recorded delivery route.
+ */
+async function resolveSessionDeliveryContext(
+  core: ReturnType<typeof getBotCordRuntime>,
+  cfg: any,
+  sessionKey: string,
+): Promise<DeliveryContext | undefined> {
+  try {
+    const storePath = core.channel.session.resolveStorePath(cfg.session?.store);
+    const raw = await readFile(storePath, "utf-8");
+    const store: Record<string, { deliveryContext?: DeliveryContext }> = JSON.parse(raw);
+    const entry = store[sessionKey];
+    if (entry?.deliveryContext?.channel && entry.deliveryContext.to) {
+      return entry.deliveryContext;
+    }
+  } catch {
+    // best-effort: store may not exist yet
+  }
+  return undefined;
+}
+
+/** Channel name → runtime send function dispatcher. */
+type ChannelSendFn = (to: string, text: string, opts: Record<string, unknown>) => Promise<unknown>;
+
+function resolveChannelSendFn(
+  core: ReturnType<typeof getBotCordRuntime>,
+  channel: string,
+): ChannelSendFn | undefined {
+  const map: Record<string, ChannelSendFn | undefined> = {
+    telegram: core.channel.telegram?.sendMessageTelegram as ChannelSendFn | undefined,
+    discord: core.channel.discord?.sendMessageDiscord as ChannelSendFn | undefined,
+    slack: core.channel.slack?.sendMessageSlack as ChannelSendFn | undefined,
+    whatsapp: core.channel.whatsapp?.sendMessageWhatsApp as ChannelSendFn | undefined,
+    signal: core.channel.signal?.sendMessageSignal as ChannelSendFn | undefined,
+    imessage: core.channel.imessage?.sendMessageIMessage as ChannelSendFn | undefined,
+  };
+  return map[channel];
+}
+
+/**
+ * Deliver a notification message directly to the channel associated with
+ * the target session (looked up via deliveryContext in the session store).
+ * Does not trigger an agent turn — just sends the text.
+ */
+export async function deliverNotification(
+  core: ReturnType<typeof getBotCordRuntime>,
+  cfg: any,
+  sessionKey: string,
+  text: string,
+): Promise<void> {
+  const delivery = await resolveSessionDeliveryContext(core, cfg, sessionKey);
+  if (!delivery) {
+    console.warn(
+      `[botcord] notifySession ${sessionKey} has no deliveryContext — skipping notification`,
+    );
+    return;
+  }
+
+  const sendFn = resolveChannelSendFn(core, delivery.channel);
+  if (!sendFn) {
+    console.warn(
+      `[botcord] unsupported notify channel "${delivery.channel}" — skipping notification`,
+    );
+    return;
+  }
+
+  await sendFn(delivery.to, text, {
+    cfg,
+    accountId: delivery.accountId,
+    threadId: delivery.threadId,
+  });
+}

package/src/poller.ts

@@ -0,0 +1,70 @@
+/**
+ * Background inbox polling for BotCord.
+ * Used when websocket delivery is unavailable.
+ */
+import { BotCordClient } from "./client.js";
+import { handleInboxMessage } from "./inbound.js";
+import { displayPrefix } from "./config.js";
+
+interface PollerOptions {
+  client: BotCordClient;
+  accountId: string;
+  cfg: any;
+  intervalMs: number;
+  abortSignal?: AbortSignal;
+  log?: { info: (msg: string) => void; error: (msg: string) => void; warn: (msg: string) => void };
+}
+
+const activePollers = new Map<string, { stop: () => void }>();
+
+export function startPoller(opts: PollerOptions): { stop: () => void } {
+  const { client, accountId, cfg, intervalMs, abortSignal, log } = opts;
+  const dp = displayPrefix(accountId, cfg);
+  let running = true;
+  let timeoutId: ReturnType<typeof setTimeout> | null = null;
+
+  async function poll() {
+    if (!running || abortSignal?.aborted) return;
+
+    try {
+      const resp = await client.pollInbox({ limit: 20, ack: true });
+      const messages = resp.messages || [];
+
+      for (const msg of messages) {
+        try {
+          await handleInboxMessage(msg, accountId, cfg);
+        } catch (err: any) {
+          log?.error(`[${dp}] failed to dispatch message ${msg.hub_msg_id}: ${err.message}`);
+        }
+      }
+    } catch (err: any) {
+      if (!running) return;
+      log?.error(`[${dp}] poll error: ${err.message}`);
+    }
+
+    if (running && !abortSignal?.aborted) {
+      timeoutId = setTimeout(poll, intervalMs);
+    }
+  }
+
+  function stop() {
+    running = false;
+    if (timeoutId) clearTimeout(timeoutId);
+    activePollers.delete(accountId);
+  }
+
+  // Start first poll
+  timeoutId = setTimeout(poll, 500);
+
+  const entry = { stop };
+  activePollers.set(accountId, entry);
+
+  abortSignal?.addEventListener("abort", stop, { once: true });
+
+  return entry;
+}
+
+export function stopPoller(accountId: string): void {
+  const poller = activePollers.get(accountId);
+  if (poller) poller.stop();
+}

package/src/runtime.ts

@@ -0,0 +1,25 @@
+/**
+ * Plugin runtime store — holds a reference to OpenClaw's PluginRuntime
+ * and a config getter for tools/hooks that need the full app config.
+ */
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+
+let runtime: PluginRuntime | null = null;
+let configGetter: (() => any) | null = null;
+
+export function setBotCordRuntime(rt: PluginRuntime): void {
+  runtime = rt;
+}
+
+export function getBotCordRuntime(): PluginRuntime {
+  if (!runtime) throw new Error("BotCord runtime not initialized");
+  return runtime;
+}
+
+export function setConfigGetter(fn: () => any): void {
+  configGetter = fn;
+}
+
+export function getConfig(): any {
+  return configGetter?.() ?? null;
+}

package/src/session-key.ts

@@ -0,0 +1,59 @@
+/**
+ * Deterministic session key derivation.
+ * Must match hub/forward.py build_session_key() exactly.
+ */
+import { createHash } from "node:crypto";
+
+// UUID v5 namespace — must match hub/constants.py SESSION_KEY_NAMESPACE
+const SESSION_KEY_NAMESPACE = "d4e8f2a1-3b6c-4d5e-9f0a-1b2c3d4e5f6a";
+
+/**
+ * RFC 4122 UUID v5 (SHA-1 based, deterministic).
+ */
+function uuidV5(name: string, namespace: string): string {
+  // Parse namespace UUID to bytes
+  const nsHex = namespace.replace(/-/g, "");
+  const nsBytes = Buffer.from(nsHex, "hex");
+
+  const hash = createHash("sha1")
+    .update(nsBytes)
+    .update(Buffer.from(name, "utf-8"))
+    .digest();
+
+  // Set version (5) and variant (RFC 4122)
+  hash[6] = (hash[6] & 0x0f) | 0x50;
+  hash[8] = (hash[8] & 0x3f) | 0x80;
+
+  const hex = hash.subarray(0, 16).toString("hex");
+  return [
+    hex.slice(0, 8),
+    hex.slice(8, 12),
+    hex.slice(12, 16),
+    hex.slice(16, 20),
+    hex.slice(20, 32),
+  ].join("-");
+}
+
+/**
+ * Derive a deterministic sessionKey from room_id, optional topic, and senderId.
+ * Same inputs always produce the same key.
+ *
+ * - Group room: seed from room_id (+ optional topic)
+ * - DM with room_id (rm_dm_*): seed from room_id (already unique per DM pair)
+ * - DM without room_id: seed from senderId to isolate per-sender conversations
+ */
+export function buildSessionKey(
+  roomId?: string,
+  topic?: string,
+  senderId?: string,
+): string {
+  let seed: string;
+  if (roomId) {
+    seed = topic ? `${roomId}:${topic}` : roomId;
+  } else if (senderId) {
+    seed = `dm:${senderId}`;
+  } else {
+    seed = "default";
+  }
+  return `botcord:${uuidV5(seed, SESSION_KEY_NAMESPACE)}`;
+}