@botcord/botcord 0.3.4 → 0.3.6-beta.20260413082920

package/src/client.ts

@@ -24,11 +24,42 @@ import type {
   WithdrawalResponse,
   SubscriptionProduct,
   Subscription,
+  PublicRoomsResponse,
 } from "./types.js";
 
 const MAX_RETRIES = 2;
 const RETRY_BASE_MS = 1000;
 
+/**
+ * Typed error thrown by BotCordClient for non-ok HTTP responses.
+ * Carries the HTTP status and an optional error code parsed from the response body.
+ */
+export class HubApiError extends Error {
+  readonly status: number;
+  readonly code: string | undefined;
+
+  constructor(status: number, body: string, path: string) {
+    super(`BotCord ${path} failed: ${status} ${body}`);
+    this.name = "HubApiError";
+    this.status = status;
+    this.code = HubApiError.parseCode(body);
+  }
+
+  private static parseCode(body: string): string | undefined {
+    try {
+      const parsed = JSON.parse(body);
+      // Hub returns { "detail": "BLOCKED" } or { "code": "NOT_IN_CONTACTS" }
+      if (typeof parsed.code === "string") return parsed.code;
+      if (typeof parsed.detail === "string" && /^[A-Z_]+$/.test(parsed.detail)) return parsed.detail;
+    } catch {
+      // Not JSON — try to extract an all-caps code from the raw body
+      const match = body.match(/\b([A-Z][A-Z_]{2,})\b/);
+      if (match) return match[1];
+    }
+    return undefined;
+  }
+}
+
 export class BotCordClient {
   private hubUrl: string;
   private agentId: string;
@@ -177,13 +208,57 @@ export class BotCordClient {
       }
 
       const body = await resp.text().catch(() => "");
-      const err = new Error(`BotCord ${path} failed: ${resp.status} ${body}`);
-      (err as any).status = resp.status;
-      throw err;
+      throw new HubApiError(resp.status, body, path);
     }
     throw new Error(`BotCord ${path} failed: exhausted retries`);
   }
 
+  // ── Raw API access ──────────────────────────────────────────
+
+  /**
+   * Execute an arbitrary authenticated request against the Hub API.
+   * Returns the parsed JSON response body.
+   */
+  async request(
+    method: string,
+    path: string,
+    options?: { body?: unknown; query?: Record<string, string | string[]> },
+  ): Promise<unknown> {
+    let fullPath = path;
+    if (options?.query) {
+      const params = new URLSearchParams();
+      for (const [key, val] of Object.entries(options.query)) {
+        if (Array.isArray(val)) {
+          for (const v of val) params.append(key, v);
+        } else {
+          params.append(key, val);
+        }
+      }
+      const sep = path.includes("?") ? "&" : "?";
+      fullPath = `${path}${sep}${params}`;
+    }
+    const init: RequestInit = { method };
+    if (options?.body !== undefined) {
+      init.body = JSON.stringify(options.body);
+    }
+    const resp = await this.hubFetch(fullPath, init);
+    const text = await resp.text();
+    // Guard against unexpectedly large responses (1MB cap for raw API use)
+    const MAX_RESPONSE_SIZE = 1024 * 1024;
+    if (text.length > MAX_RESPONSE_SIZE) {
+      throw new HubApiError(
+        resp.status,
+        `Response too large (${(text.length / 1024).toFixed(0)}KB > 1MB limit)`,
+        fullPath,
+      );
+    }
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  }
+
   // ── File upload ──────────────────────────────────────────────
 
   async uploadFile(
@@ -584,6 +659,20 @@ export class BotCordClient {
     return (await resp.json()) as RoomInfo[];
   }
 
+  async discoverPublicRooms(q?: string): Promise<PublicRoomsResponse> {
+    const params = new URLSearchParams();
+    if (q) params.set("q", q);
+    const qs = params.toString();
+    const resp = await fetch(`${this.hubUrl}/public/rooms${qs ? `?${qs}` : ""}`, {
+      signal: AbortSignal.timeout(30000),
+    });
+    if (!resp.ok) {
+      const body = await resp.text().catch(() => "");
+      throw new Error(`BotCord /public/rooms failed: ${resp.status} ${body}`);
+    }
+    return (await resp.json()) as PublicRoomsResponse;
+  }
+
   async updateRoom(
     roomId: string,
     params: {
@@ -774,7 +863,7 @@ export class BotCordClient {
     name: string;
     description?: string;
     amount_minor: string;
-    billing_interval: "week" | "month";
+    billing_interval: "week" | "month" | "once";
     asset_code?: string;
   }): Promise<SubscriptionProduct> {
     const resp = await this.hubFetch("/subscriptions/products", {
@@ -866,7 +955,7 @@ export class BotCordClient {
 
   async roomSearch(
     roomId: string,
-    query: string,
+    query: string | string[],
     opts?: {
       limit?: number;
       before?: string;
@@ -875,7 +964,9 @@ export class BotCordClient {
     },
   ): Promise<any> {
     const params = new URLSearchParams();
-    params.set("q", query);
+    const queries = (Array.isArray(query) ? query : [query])
+      .map((q) => q.trim()).filter(Boolean);
+    for (const q of queries) params.append("q", q);
     if (opts?.limit) params.set("limit", String(opts.limit));
     if (opts?.before) params.set("before", opts.before);
     if (opts?.topicId) params.set("topic_id", opts.topicId);
@@ -893,7 +984,7 @@ export class BotCordClient {
   }
 
   async globalSearch(
-    query: string,
+    query: string | string[],
     opts?: {
       limit?: number;
       roomId?: string;
@@ -903,7 +994,9 @@ export class BotCordClient {
     },
   ): Promise<any> {
     const params = new URLSearchParams();
-    params.set("q", query);
+    const queries = (Array.isArray(query) ? query : [query])
+      .map((q) => q.trim()).filter(Boolean);
+    for (const q of queries) params.append("q", q);
     if (opts?.limit) params.set("limit", String(opts.limit));
     if (opts?.roomId) params.set("room_id", opts.roomId);
     if (opts?.topicId) params.set("topic_id", opts.topicId);

package/src/commands/bind.ts

@@ -19,10 +19,11 @@ export function createBindCommand() {
         return { text: "[FAIL] Usage: /botcord_bind <bind_code_or_bind_ticket>" };
       }
 
-      const result = await executeBind(bindCredential);
+      const result = await executeBind(bindCredential) as Record<string, unknown>;
 
-      if ("error" in result) {
-        return { text: `[FAIL] ${result.error}` };
+      if (!result.ok) {
+        const err = (result.error as { message?: string })?.message || "Unknown error";
+        return { text: `[FAIL] ${err}` };
       }
 
       const agentId = result.agent_id || "unknown";

package/src/commands/uninstall.ts

@@ -0,0 +1,129 @@
+/**
+ * CLI: `openclaw botcord-uninstall`
+ *
+ * Safe uninstall that uses OpenClaw's plugin API instead of editing JSON directly.
+ * Prevents the common failure mode where AI agents corrupt openclaw.json.
+ */
+
+export function createUninstallCli() {
+  return {
+    setup: (ctx: any) => {
+      ctx.program
+        .command("botcord-uninstall")
+        .description("Safely uninstall the BotCord plugin")
+        .option("--purge", "Also delete credentials from ~/.botcord/", false)
+        .option("--keep-channel", "Keep channel config in openclaw.json", false)
+        .option("--profile <name>", "OpenClaw profile to target")
+        .option("--dev", "Target the dev profile")
+        .action(async (options: { purge?: boolean; keepChannel?: boolean; profile?: string; dev?: boolean }) => {
+          const { existsSync, rmSync, readdirSync } = await import("node:fs");
+          const { join } = await import("node:path");
+          const { spawnSync } = await import("node:child_process");
+          const { homedir } = await import("node:os");
+
+          const home = homedir();
+          const credDir = join(home, ".botcord", "credentials");
+
+          // Build profile args to forward to openclaw CLI (as array, never shell-interpolated)
+          const profileArgs: string[] = [];
+          if (options.dev) profileArgs.push("--dev");
+          else if (options.profile) {
+            // Validate profile name to prevent injection via spawn args
+            if (!/^[a-zA-Z0-9._-]+$/.test(options.profile)) {
+              ctx.logger.error("Invalid profile name — only alphanumeric, dots, hyphens, and underscores are allowed");
+              return;
+            }
+            profileArgs.push("--profile", options.profile);
+          }
+
+          // Helper: run openclaw CLI safely via spawnSync (no shell interpolation)
+          const oc = (cmdArgs: string[]) =>
+            spawnSync("openclaw", [...profileArgs, ...cmdArgs], { stdio: "pipe", encoding: "utf8" });
+
+          // Resolve extension dir from openclaw CLI if possible, else default
+          let extensionDir = join(home, ".openclaw", "extensions", "botcord");
+          try {
+            const result = oc(["config", "path"]);
+            const configFile = (result.stdout || "").trim();
+            if (configFile) {
+              const configDir = join(configFile, "..");
+              extensionDir = join(configDir, "extensions", "botcord");
+            }
+          } catch {
+            // fall back to default path
+          }
+
+          // Step 1: Disable plugin via OpenClaw CLI (safe — no JSON editing)
+          ctx.logger.info("Disabling BotCord plugin ...");
+          try {
+            const result = oc(["plugins", "disable", "botcord"]);
+            if (result.status === 0) {
+              ctx.logger.info("  Plugin disabled");
+            } else {
+              ctx.logger.warn("  Plugin was not enabled (or already disabled)");
+            }
+          } catch {
+            ctx.logger.warn("  Plugin was not enabled (or already disabled)");
+          }
+
+          // Step 2: Remove channel config via OpenClaw CLI if available
+          if (!options.keepChannel) {
+            ctx.logger.info("Removing channel configuration ...");
+            try {
+              const result = oc(["config", "unset", "channels.botcord"]);
+              if (result.status === 0) {
+                ctx.logger.info("  Channel config removed");
+              } else {
+                ctx.logger.warn("  Could not remove channel config via CLI — may need manual cleanup");
+                ctx.logger.warn("  If needed, remove 'channels.botcord' from openclaw.json");
+              }
+            } catch {
+              ctx.logger.warn("  Could not remove channel config via CLI — may need manual cleanup");
+              ctx.logger.warn("  If needed, remove 'channels.botcord' from openclaw.json");
+            }
+          } else {
+            ctx.logger.info("Keeping channel configuration (--keep-channel)");
+          }
+
+          // Step 3: Remove plugin files
+          if (existsSync(extensionDir)) {
+            ctx.logger.info(`Removing plugin files from ${extensionDir} ...`);
+            rmSync(extensionDir, { recursive: true, force: true });
+            ctx.logger.info("  Plugin files removed");
+          } else {
+            ctx.logger.info("  No plugin files found (already removed)");
+          }
+
+          // Step 4: Optionally purge credentials
+          if (options.purge) {
+            if (existsSync(credDir)) {
+              const files = readdirSync(credDir).filter((f: string) => f.endsWith(".json"));
+              if (files.length > 0) {
+                ctx.logger.info(`Deleting ${files.length} credential file(s) from ${credDir} ...`);
+                for (const f of files) {
+                  rmSync(join(credDir, f), { force: true });
+                  ctx.logger.info(`  Deleted ${f}`);
+                }
+              }
+            } else {
+              ctx.logger.info("  No credentials directory found");
+            }
+          } else {
+            // Show what's preserved
+            if (existsSync(credDir)) {
+              const files = readdirSync(credDir).filter((f: string) => f.endsWith(".json"));
+              if (files.length > 0) {
+                ctx.logger.info(`Credentials preserved in ${credDir} (${files.length} file(s))`);
+                ctx.logger.info("  Use --purge to also delete credentials");
+              }
+            }
+          }
+
+          ctx.logger.info("");
+          ctx.logger.info("BotCord plugin uninstalled.");
+          ctx.logger.info("Restart OpenClaw to apply: openclaw gateway restart");
+        });
+    },
+    commands: ["botcord-uninstall"],
+  };
+}

package/src/constants.ts

@@ -9,7 +9,7 @@
 
 export type ReleaseChannel = "stable" | "beta";
 
-export const RELEASE_CHANNEL: ReleaseChannel = "stable";
+export const RELEASE_CHANNEL: ReleaseChannel = "beta";
 
 const HUB_URLS: Record<ReleaseChannel, string> = {
   stable: "https://api.botcord.chat",

package/src/credentials.ts

@@ -1,108 +1,26 @@
-import { chmodSync, mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { derivePublicKey } from "./crypto.js";
-import { normalizeAndValidateHubUrl } from "./hub-url.js";
+import { existsSync, readFileSync, writeFileSync, chmodSync } from "node:fs";
+import {
+  type StoredBotCordCredentials,
+  updateCredentialsToken,
+  loadStoredCredentials,
+  writeCredentialsFile,
+  resolveCredentialsFilePath,
+  defaultCredentialsFile,
+} from "@botcord/protocol-core";
 import type { BotCordAccountConfig } from "./types.js";
 import type { BotCordClient as BotCordClientType } from "./client.js";
 
-export interface StoredBotCordCredentials {
-  version: 1;
-  hubUrl: string;
-  agentId: string;
-  keyId: string;
-  privateKey: string;
-  publicKey: string;
-  displayName?: string;
-  savedAt: string;
-  token?: string;
-  tokenExpiresAt?: number;
-  onboardedAt?: 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"]);
-  const token = normalizeCredentialValue(raw, ["token"]);
-  const tokenExpiresAt = typeof raw.tokenExpiresAt === "number"
-    ? raw.tokenExpiresAt
-    : typeof raw.token_expires_at === "number"
-      ? raw.token_expires_at
-      : undefined;
-
-  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`,
-    );
-  }
-
-  let normalizedHubUrl: string;
-  try {
-    normalizedHubUrl = normalizeAndValidateHubUrl(hubUrl);
-  } catch (err: any) {
-    throw new Error(`BotCord credentials file "${resolved}" has an invalid hubUrl: ${err.message}`);
-  }
-
-  const onboardedAt = normalizeCredentialValue(raw, ["onboardedAt", "onboarded_at"]);
+// Re-export core functions so existing plugin imports don't break
+export {
+  type StoredBotCordCredentials,
+  updateCredentialsToken,
+  loadStoredCredentials,
+  writeCredentialsFile,
+  resolveCredentialsFilePath,
+  defaultCredentialsFile,
+} from "@botcord/protocol-core";
 
-  return {
-    version: 1,
-    hubUrl: normalizedHubUrl,
-    agentId,
-    keyId,
-    privateKey,
-    publicKey: publicKey || derivedPublicKey,
-    displayName,
-    savedAt: savedAt || new Date().toISOString(),
-    token,
-    tokenExpiresAt,
-    onboardedAt,
-  };
-}
+// Plugin-specific helpers below
 
 export function readCredentialFileData(credentialsFile?: string): Partial<BotCordAccountConfig> {
   if (!credentialsFile) return {};
@@ -123,51 +41,6 @@ export function readCredentialFileData(credentialsFile?: string): Partial<BotCor
   }
 }
 
-export function writeCredentialsFile(
-  credentialsFile: string,
-  credentials: StoredBotCordCredentials,
-): string {
-  const resolved = resolveCredentialsFilePath(credentialsFile);
-  const normalizedCredentials = {
-    ...credentials,
-    hubUrl: normalizeAndValidateHubUrl(credentials.hubUrl),
-  };
-  mkdirSync(path.dirname(resolved), { recursive: true, mode: 0o700 });
-  writeFileSync(resolved, JSON.stringify(normalizedCredentials, null, 2) + "\n", {
-    encoding: "utf8",
-    mode: 0o600,
-  });
-  chmodSync(resolved, 0o600);
-  return resolved;
-}
-
-/**
- * Atomically update only the token fields in an existing credentials file.
- * Reads current file, merges new token/expiresAt, writes back.
- * Returns false if the file does not exist or the write fails.
- */
-export function updateCredentialsToken(
-  credentialsFile: string,
-  token: string,
-  tokenExpiresAt: number,
-): boolean {
-  const resolved = resolveCredentialsFilePath(credentialsFile);
-  try {
-    if (!existsSync(resolved)) return false;
-    const raw = JSON.parse(readFileSync(resolved, "utf8")) as Record<string, unknown>;
-    raw.token = token;
-    raw.tokenExpiresAt = tokenExpiresAt;
-    writeFileSync(resolved, JSON.stringify(raw, null, 2) + "\n", {
-      encoding: "utf8",
-      mode: 0o600,
-    });
-    chmodSync(resolved, 0o600);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 /**
  * Check whether the agent has completed onboarding.
  */

package/src/crypto.ts

@@ -1,155 +1 @@
-/**
- * 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}`,
-  };
-}
+export * from "@botcord/protocol-core";