@botcord/openclaw-plugin 0.0.2

package/src/commands/healthcheck.ts

@@ -0,0 +1,143 @@
+/**
+ * /botcord_healthcheck — Plugin command for BotCord integration health check.
+ *
+ * Checks: plugin config, Hub connectivity, token validity, delivery mode status.
+ */
+import {
+  getSingleAccountModeError,
+  resolveAccountConfig,
+  isAccountConfigured,
+} from "../config.js";
+import { BotCordClient } from "../client.js";
+import { getConfig as getAppConfig } from "../runtime.js";
+
+export function createHealthcheckCommand() {
+  return {
+    name: "botcord_healthcheck",
+    description: "Check BotCord integration health: config, Hub connectivity, token, delivery mode.",
+    acceptsArgs: false,
+    requireAuth: true,
+    handler: async () => {
+      const lines: string[] = [];
+      let pass = 0;
+      let warn = 0;
+      let fail = 0;
+
+      const ok = (msg: string) => { lines.push(`[OK]   ${msg}`); pass++; };
+      const warning = (msg: string) => { lines.push(`[WARN] ${msg}`); warn++; };
+      const error = (msg: string) => { lines.push(`[FAIL] ${msg}`); fail++; };
+      const info = (msg: string) => { lines.push(`[INFO] ${msg}`); };
+
+      // ── 1. Plugin Configuration ──
+      lines.push("", "── Plugin Configuration ──");
+
+      const cfg = getAppConfig();
+      if (!cfg) {
+        error("No OpenClaw configuration available");
+        return { text: lines.join("\n") };
+      }
+      const singleAccountError = getSingleAccountModeError(cfg);
+      if (singleAccountError) {
+        error(singleAccountError);
+        return { text: lines.join("\n") };
+      }
+
+      const acct = resolveAccountConfig(cfg);
+
+      if (!acct.hubUrl) {
+        error("hubUrl is not configured");
+      } else {
+        ok(`Hub URL: ${acct.hubUrl}`);
+      }
+
+      if (acct.credentialsFile) {
+        info(`Credentials file: ${acct.credentialsFile}`);
+        if (!acct.privateKey) {
+          error("credentialsFile is configured but could not be loaded");
+        }
+      }
+
+      if (!acct.agentId) {
+        error("agentId is not configured");
+      } else {
+        ok(`Agent ID: ${acct.agentId}`);
+      }
+
+      if (!acct.keyId) {
+        error("keyId is not configured");
+      } else {
+        ok(`Key ID: ${acct.keyId}`);
+      }
+
+      if (!acct.privateKey) {
+        error("privateKey is not configured");
+      } else {
+        ok("Private key: configured");
+      }
+
+      if (!isAccountConfigured(acct)) {
+        error("Plugin is not fully configured — cannot proceed with connectivity checks");
+        lines.push("", `── Summary ──`);
+        lines.push(`Passed: ${pass}  |  Warnings: ${warn}  |  Failed: ${fail}`);
+        return { text: lines.join("\n") };
+      }
+
+      // ── 2. Hub Connectivity & Token ──
+      lines.push("", "── Hub Connectivity ──");
+
+      const client = new BotCordClient(acct);
+
+      try {
+        await client.ensureToken();
+        ok("Token refresh successful — Hub is reachable and credentials are valid");
+      } catch (err: any) {
+        error(`Token refresh failed: ${err.message}`);
+        lines.push("", `── Summary ──`);
+        lines.push(`Passed: ${pass}  |  Warnings: ${warn}  |  Failed: ${fail}`);
+        return { text: lines.join("\n") };
+      }
+
+      // ── 3. Agent Resolution ──
+      lines.push("", "── Agent Identity ──");
+
+      try {
+        const resolved = await client.resolve(client.getAgentId());
+        if (resolved && typeof resolved === "object") {
+          const r = resolved as Record<string, unknown>;
+          ok(`Agent resolved: ${r.display_name || r.agent_id}`);
+          if (r.bio) info(`Bio: ${r.bio}`);
+          if (Array.isArray(r.endpoints) && r.endpoints.length > 0) {
+            info(`Registered endpoints on Hub: ${r.endpoints.length}`);
+          }
+        }
+      } catch (err: any) {
+        error(`Agent resolution failed: ${err.message}`);
+      }
+
+      // ── 4. Delivery Mode ──
+      lines.push("", "── Delivery Mode ──");
+
+      const mode = acct.deliveryMode || "websocket";
+      ok(`Delivery mode: ${mode}`);
+
+      if (mode === "polling") {
+        info(`Poll interval: ${acct.pollIntervalMs || 5000}ms`);
+      }
+
+      // ── Summary ──
+      lines.push("", "── Summary ──");
+      const total = pass + warn + fail;
+      lines.push(`Passed: ${pass}  |  Warnings: ${warn}  |  Failed: ${fail}  |  Total: ${total}`);
+
+      if (fail > 0) {
+        lines.push("", "Some checks FAILED. Please fix the issues above.");
+      } else if (warn > 0) {
+        lines.push("", "All critical checks passed, but there are warnings to review.");
+      } else {
+        lines.push("", "All checks passed. BotCord is ready!");
+      }
+
+      return { text: lines.join("\n") };
+    },
+  };
+}

package/src/commands/register.ts

@@ -0,0 +1,302 @@
+/**
+ * `openclaw botcord-register` — CLI command for agent registration.
+ *
+ * Generates Ed25519 keypair, registers with Hub, writes credentials
+ * to a dedicated file, then saves only its reference in openclaw.json.
+ */
+import {
+  defaultCredentialsFile,
+  loadStoredCredentials,
+  resolveCredentialsFilePath,
+  type StoredBotCordCredentials,
+  writeCredentialsFile,
+} from "../credentials.js";
+import {
+  derivePublicKey,
+  generateKeypair,
+  signChallenge,
+} from "../crypto.js";
+import {
+  getSingleAccountModeError,
+  resolveAccountConfig,
+} from "../config.js";
+import { getBotCordRuntime } from "../runtime.js";
+
+const DEFAULT_HUB = "https://api.botcord.chat";
+
+interface RegisterResult {
+  agentId: string;
+  keyId: string;
+  displayName: string;
+  hub: string;
+  credentialsFile: string;
+}
+
+interface ImportResult {
+  agentId: string;
+  keyId: string;
+  hub: string;
+  sourceFile: string;
+  credentialsFile: string;
+}
+
+function buildRegistrationKeypair(config: Record<string, any>, newIdentity: boolean) {
+  if (newIdentity) return generateKeypair();
+
+  const existing = resolveAccountConfig(config);
+  if (!existing.privateKey) return generateKeypair();
+
+  const publicKey = existing.publicKey || derivePublicKey(existing.privateKey);
+  return {
+    privateKey: existing.privateKey,
+    publicKey,
+    pubkeyFormatted: `ed25519:${publicKey}`,
+  };
+}
+
+function stripInlineCredentials(botcordCfg: Record<string, any>): Record<string, any> {
+  const next = { ...botcordCfg };
+  delete next.hubUrl;
+  delete next.agentId;
+  delete next.keyId;
+  delete next.privateKey;
+  delete next.publicKey;
+  return next;
+}
+
+function buildNextConfig(
+  config: Record<string, any>,
+  credentialsFile: string,
+): Record<string, any> {
+  const currentBotcord = ((config.channels as Record<string, any>)?.botcord ?? {}) as Record<string, any>;
+  return {
+    ...config,
+    channels: {
+      ...(config.channels as Record<string, any>),
+      botcord: {
+        ...stripInlineCredentials(currentBotcord),
+        enabled: true,
+        credentialsFile,
+        deliveryMode:
+          currentBotcord.deliveryMode === "polling"
+            ? "polling"
+            : "websocket",
+        notifySession:
+          currentBotcord.notifySession ||
+          "agent:main:main",
+      },
+    },
+    session: {
+      ...(config.session as Record<string, any>),
+      dmScope:
+        (config.session as Record<string, any>)?.dmScope ||
+        "per-channel-peer",
+    },
+  };
+}
+
+async function persistCredentials(params: {
+  config: Record<string, any>;
+  credentials: StoredBotCordCredentials;
+  destinationFile?: string;
+}): Promise<string> {
+  const runtime = getBotCordRuntime();
+  const existingAccount = resolveAccountConfig(params.config);
+  const credentialsFile = writeCredentialsFile(
+    params.destinationFile || existingAccount.credentialsFile || defaultCredentialsFile(params.credentials.agentId),
+    params.credentials,
+  );
+  await runtime.config.writeConfigFile(buildNextConfig(params.config, credentialsFile));
+  return credentialsFile;
+}
+
+export async function registerAgent(opts: {
+  name: string;
+  bio: string;
+  hub: string;
+  config: Record<string, any>;
+  newIdentity?: boolean;
+}): Promise<RegisterResult> {
+  const {
+    name,
+    bio,
+    hub,
+    config,
+    newIdentity = false,
+  } = opts;
+  const singleAccountError = getSingleAccountModeError(config);
+  if (singleAccountError) {
+    throw new Error(singleAccountError);
+  }
+
+  const currentBotcord = ((config.channels as Record<string, any>)?.botcord ?? {}) as Record<string, any>;
+  const existingAccount = resolveAccountConfig(config);
+  if (!newIdentity && currentBotcord.credentialsFile && !existingAccount.privateKey) {
+    throw new Error(
+      `BotCord credentialsFile is configured but could not be loaded: ${currentBotcord.credentialsFile}`,
+    );
+  }
+
+  // 1. Reuse the existing keypair unless the caller explicitly requests a new identity.
+  const keys = buildRegistrationKeypair(config, newIdentity);
+  const normalizedBio = bio.trim() || `${name} on BotCord`;
+
+  // 2. Register with Hub
+  const regResp = await fetch(`${hub}/registry/agents`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      display_name: name,
+      pubkey: keys.pubkeyFormatted,
+      bio: normalizedBio,
+    }),
+  });
+
+  if (!regResp.ok) {
+    const body = await regResp.text();
+    throw new Error(`Registration failed (${regResp.status}): ${body}`);
+  }
+
+  const regData = (await regResp.json()) as {
+    agent_id: string;
+    key_id: string;
+    challenge: string;
+  };
+
+  // 3. Sign challenge
+  const sig = signChallenge(keys.privateKey, regData.challenge);
+
+  // 4. Verify (challenge-response)
+  const verifyResp = await fetch(
+    `${hub}/registry/agents/${regData.agent_id}/verify`,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        key_id: regData.key_id,
+        challenge: regData.challenge,
+        sig,
+      }),
+    },
+  );
+
+  if (!verifyResp.ok) {
+    const body = await verifyResp.text();
+    throw new Error(`Verification failed (${verifyResp.status}): ${body}`);
+  }
+
+  // 5. Write credentials via OpenClaw's config API
+  const credentialsFile = await persistCredentials({
+    config,
+    credentials: {
+      version: 1,
+      hubUrl: hub,
+      agentId: regData.agent_id,
+      keyId: regData.key_id,
+      privateKey: keys.privateKey,
+      publicKey: keys.publicKey,
+      displayName: name,
+      savedAt: new Date().toISOString(),
+    },
+  });
+
+  return {
+    agentId: regData.agent_id,
+    keyId: regData.key_id,
+    displayName: name,
+    hub,
+    credentialsFile,
+  };
+}
+
+export async function importAgentCredentials(opts: {
+  file: string;
+  config: Record<string, any>;
+  destinationFile?: string;
+}): Promise<ImportResult> {
+  const {
+    file,
+    config,
+    destinationFile,
+  } = opts;
+  const singleAccountError = getSingleAccountModeError(config);
+  if (singleAccountError) {
+    throw new Error(singleAccountError);
+  }
+
+  const sourceFile = resolveCredentialsFilePath(file);
+  const credentials = loadStoredCredentials(sourceFile);
+  const credentialsFile = await persistCredentials({
+    config,
+    credentials,
+    destinationFile,
+  });
+
+  return {
+    agentId: credentials.agentId,
+    keyId: credentials.keyId,
+    hub: credentials.hubUrl,
+    sourceFile,
+    credentialsFile,
+  };
+}
+
+export function createRegisterCli() {
+  return {
+    setup: (ctx: any) => {
+      ctx.program
+        .command("botcord-register")
+        .description("Register a new BotCord agent and configure the plugin")
+        .requiredOption("--name <name>", "Agent display name")
+        .option("--bio <bio>", "Agent bio/description", "")
+        .option("--hub <url>", "Hub URL", DEFAULT_HUB)
+        .option("--new-identity", "Generate a fresh keypair instead of reusing existing BotCord credentials", false)
+        .action(async (options: { name: string; bio: string; hub: string; newIdentity?: boolean }) => {
+          try {
+            const result = await registerAgent({
+              ...options,
+              config: ctx.config,
+            });
+            ctx.logger.info(`Agent registered successfully!`);
+            ctx.logger.info(`  Agent ID:     ${result.agentId}`);
+            ctx.logger.info(`  Key ID:       ${result.keyId}`);
+            ctx.logger.info(`  Display name: ${result.displayName}`);
+            ctx.logger.info(`  Hub:          ${result.hub}`);
+            ctx.logger.info(`  Credentials:  ${result.credentialsFile}`);
+            ctx.logger.info(``);
+            ctx.logger.info(`Restart OpenClaw to activate: openclaw gateway restart`);
+          } catch (err: any) {
+            ctx.logger.error(`Registration failed: ${err.message}`);
+            throw err;
+          }
+        });
+      ctx.program
+        .command("botcord-import")
+        .alias("botcord_import")
+        .description("Import existing BotCord credentials from a file and configure the plugin")
+        .requiredOption("--file <path>", "Path to an existing BotCord credentials JSON file")
+        .option("--dest <path>", "Destination path for the managed credentials file")
+        .action(async (options: { file: string; dest?: string }) => {
+          try {
+            const result = await importAgentCredentials({
+              file: options.file,
+              destinationFile: options.dest,
+              config: ctx.config,
+            });
+            ctx.logger.info("BotCord credentials imported successfully!");
+            ctx.logger.info(`  Agent ID:     ${result.agentId}`);
+            ctx.logger.info(`  Key ID:       ${result.keyId}`);
+            ctx.logger.info(`  Hub:          ${result.hub}`);
+            ctx.logger.info(`  Source:       ${result.sourceFile}`);
+            ctx.logger.info(`  Credentials:  ${result.credentialsFile}`);
+            ctx.logger.info("");
+            ctx.logger.info("Restart OpenClaw to activate: openclaw gateway restart");
+          } catch (err: any) {
+            ctx.logger.error(`Import failed: ${err.message}`);
+            throw err;
+          }
+        });
+    },
+    commands: ["botcord-register", "botcord-import"],
+  };
+}

package/src/commands/token.ts

@@ -0,0 +1,43 @@
+/**
+ * /botcord_token — Output the current JWT token for the configured account.
+ */
+import {
+  getSingleAccountModeError,
+  resolveAccountConfig,
+  isAccountConfigured,
+} from "../config.js";
+import { BotCordClient } from "../client.js";
+import { getConfig as getAppConfig } from "../runtime.js";
+
+export function createTokenCommand() {
+  return {
+    name: "botcord_token",
+    description: "Fetch and display the current BotCord JWT token.",
+    acceptsArgs: false,
+    requireAuth: true,
+    handler: async () => {
+      const cfg = getAppConfig();
+      if (!cfg) {
+        return { text: "[FAIL] No OpenClaw configuration available" };
+      }
+      const singleAccountError = getSingleAccountModeError(cfg);
+      if (singleAccountError) {
+        return { text: `[FAIL] ${singleAccountError}` };
+      }
+
+      const acct = resolveAccountConfig(cfg);
+      if (!isAccountConfigured(acct)) {
+        return { text: "[FAIL] BotCord is not fully configured (need hubUrl, agentId, keyId, privateKey)" };
+      }
+
+      const client = new BotCordClient(acct);
+
+      try {
+        const token = await client.ensureToken();
+        return { text: token };
+      } catch (err: any) {
+        return { text: `[FAIL] Token refresh failed: ${err.message}` };
+      }
+    },
+  };
+}

package/src/config.ts

@@ -0,0 +1,92 @@
+/**
+ * Configuration resolution for BotCord channel.
+ * The runtime still understands both flat and account-mapped config shapes,
+ * but the plugin currently operates in single-account mode.
+ */
+import {
+  readCredentialFileData,
+  resolveCredentialsFilePath,
+} from "./credentials.js";
+import type { BotCordAccountConfig, BotCordChannelConfig } from "./types.js";
+
+export const SINGLE_ACCOUNT_ONLY_MESSAGE =
+  "BotCord currently supports only a single configured account. Multi-account support is planned for a future update.";
+
+export function resolveChannelConfig(cfg: any): BotCordChannelConfig {
+  return (cfg?.channels?.botcord ?? {}) as BotCordChannelConfig;
+}
+
+function hydrateAccountConfig(acct: BotCordAccountConfig): BotCordAccountConfig {
+  const credentialsFile = acct.credentialsFile
+    ? resolveCredentialsFilePath(acct.credentialsFile)
+    : undefined;
+  const fileData = readCredentialFileData(credentialsFile);
+  const inlineData = Object.fromEntries(
+    Object.entries(acct).filter(([, value]) => value !== undefined),
+  ) as BotCordAccountConfig;
+  return {
+    ...fileData,
+    ...inlineData,
+    credentialsFile,
+  };
+}
+
+/** Resolve all account configs from either flat or account-mapped config. */
+export function resolveAccounts(
+  channelCfg: BotCordChannelConfig,
+): Record<string, BotCordAccountConfig> {
+  if (channelCfg.accounts && Object.keys(channelCfg.accounts).length > 0) {
+    return Object.fromEntries(
+      Object.entries(channelCfg.accounts).map(([accountId, acct]) => [
+        accountId,
+        hydrateAccountConfig(acct),
+      ]),
+    );
+  }
+  // Single-account fallback
+  return {
+    default: hydrateAccountConfig({
+      enabled: channelCfg.enabled,
+      credentialsFile: channelCfg.credentialsFile,
+      hubUrl: channelCfg.hubUrl,
+      agentId: channelCfg.agentId,
+      keyId: channelCfg.keyId,
+      privateKey: channelCfg.privateKey,
+      publicKey: channelCfg.publicKey,
+      deliveryMode: channelCfg.deliveryMode,
+      pollIntervalMs: channelCfg.pollIntervalMs,
+      allowFrom: channelCfg.allowFrom,
+      notifySession: channelCfg.notifySession,
+    }),
+  };
+}
+
+export function resolveAccountConfig(
+  cfg: any,
+  accountId?: string,
+): BotCordAccountConfig {
+  const channelCfg = resolveChannelConfig(cfg);
+  const accounts = resolveAccounts(channelCfg);
+  const id = accountId || "default";
+  return accounts[id] || accounts[Object.keys(accounts)[0]] || {};
+}
+
+export function isAccountConfigured(acct: BotCordAccountConfig): boolean {
+  return !!(acct.hubUrl && acct.agentId && acct.keyId && acct.privateKey);
+}
+
+export function countAccounts(cfg: any): number {
+  const channelCfg = resolveChannelConfig(cfg);
+  return Object.keys(resolveAccounts(channelCfg)).length;
+}
+
+export function getSingleAccountModeError(cfg: any): string | null {
+  return countAccounts(cfg) > 1 ? SINGLE_ACCOUNT_ONLY_MESSAGE : null;
+}
+
+/** Display prefix for logs and messages. */
+export function displayPrefix(accountId: string, cfg: any): string {
+  const total = countAccounts(cfg);
+  if (total <= 1 && accountId === "default") return "BotCord";
+  return `BotCord:${accountId}`;
+}

package/src/credentials.ts

@@ -0,0 +1,113 @@
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { derivePublicKey } from "./crypto.js";
+import type { BotCordAccountConfig } from "./types.js";
+
+export interface StoredBotCordCredentials {
+  version: 1;
+  hubUrl: string;
+  agentId: string;
+  keyId: string;
+  privateKey: string;
+  publicKey: string;
+  displayName?: string;
+  savedAt: string;
+}
+
+function normalizeCredentialValue(raw: any, keys: string[]): string | undefined {
+  for (const key of keys) {
+    const value = raw?.[key];
+    if (typeof value === "string" && value.trim()) return value;
+  }
+  return undefined;
+}
+
+export function resolveCredentialsFilePath(credentialsFile: string): string {
+  if (credentialsFile === "~") return os.homedir();
+  if (credentialsFile.startsWith("~/")) {
+    return path.join(os.homedir(), credentialsFile.slice(2));
+  }
+  return path.isAbsolute(credentialsFile)
+    ? credentialsFile
+    : path.resolve(credentialsFile);
+}
+
+export function defaultCredentialsFile(agentId: string): string {
+  return path.join(os.homedir(), ".botcord", "credentials", `${agentId}.json`);
+}
+
+function readCredentialSource(credentialsFile: string): Record<string, unknown> {
+  const resolved = resolveCredentialsFilePath(credentialsFile);
+  try {
+    return JSON.parse(readFileSync(resolved, "utf8")) as Record<string, unknown>;
+  } catch (err: any) {
+    throw new Error(`Unable to read BotCord credentials file "${resolved}": ${err.message}`);
+  }
+}
+
+export function loadStoredCredentials(credentialsFile: string): StoredBotCordCredentials {
+  const resolved = resolveCredentialsFilePath(credentialsFile);
+  const raw = readCredentialSource(resolved);
+  const hubUrl = normalizeCredentialValue(raw, ["hubUrl", "hub_url", "hub"]);
+  const agentId = normalizeCredentialValue(raw, ["agentId", "agent_id"]);
+  const keyId = normalizeCredentialValue(raw, ["keyId", "key_id"]);
+  const privateKey = normalizeCredentialValue(raw, ["privateKey", "private_key"]);
+  const publicKey = normalizeCredentialValue(raw, ["publicKey", "public_key"]);
+  const displayName = normalizeCredentialValue(raw, ["displayName", "display_name"]);
+  const savedAt = normalizeCredentialValue(raw, ["savedAt", "saved_at"]);
+
+  if (!hubUrl) throw new Error(`BotCord credentials file "${resolved}" is missing hubUrl`);
+  if (!agentId) throw new Error(`BotCord credentials file "${resolved}" is missing agentId`);
+  if (!keyId) throw new Error(`BotCord credentials file "${resolved}" is missing keyId`);
+  if (!privateKey) throw new Error(`BotCord credentials file "${resolved}" is missing privateKey`);
+
+  const derivedPublicKey = derivePublicKey(privateKey);
+  if (publicKey && publicKey !== derivedPublicKey) {
+    throw new Error(
+      `BotCord credentials file "${resolved}" has a publicKey that does not match privateKey`,
+    );
+  }
+
+  return {
+    version: 1,
+    hubUrl,
+    agentId,
+    keyId,
+    privateKey,
+    publicKey: publicKey || derivedPublicKey,
+    displayName,
+    savedAt: savedAt || new Date().toISOString(),
+  };
+}
+
+export function readCredentialFileData(credentialsFile?: string): Partial<BotCordAccountConfig> {
+  if (!credentialsFile) return {};
+
+  try {
+    const raw = loadStoredCredentials(credentialsFile);
+    return {
+      hubUrl: raw.hubUrl,
+      agentId: raw.agentId,
+      keyId: raw.keyId,
+      privateKey: raw.privateKey,
+      publicKey: raw.publicKey,
+    };
+  } catch {
+    return {};
+  }
+}
+
+export function writeCredentialsFile(
+  credentialsFile: string,
+  credentials: StoredBotCordCredentials,
+): string {
+  const resolved = resolveCredentialsFilePath(credentialsFile);
+  mkdirSync(path.dirname(resolved), { recursive: true, mode: 0o700 });
+  writeFileSync(resolved, JSON.stringify(credentials, null, 2) + "\n", {
+    encoding: "utf8",
+    mode: 0o600,
+  });
+  chmodSync(resolved, 0o600);
+  return resolved;
+}