@botcord/botcord 0.1.1

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,125 @@
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } 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 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`,
+    );
+  }
+
+  let normalizedHubUrl: string;
+  try {
+    normalizedHubUrl = normalizeAndValidateHubUrl(hubUrl);
+  } catch (err: any) {
+    throw new Error(`BotCord credentials file "${resolved}" has an invalid hubUrl: ${err.message}`);
+  }
+
+  return {
+    version: 1,
+    hubUrl: normalizedHubUrl,
+    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);
+  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;
+}

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/hub-url.ts

@@ -0,0 +1,41 @@
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "::1"]);
+
+function isLoopbackHost(hostname: string): boolean {
+  const normalized = hostname.toLowerCase().replace(/^\[(.*)\]$/, "$1");
+  return LOOPBACK_HOSTS.has(normalized) || normalized.endsWith(".localhost");
+}
+
+export function normalizeAndValidateHubUrl(hubUrl: string): string {
+  const trimmed = hubUrl.trim();
+  if (!trimmed) {
+    throw new Error("BotCord hubUrl is required");
+  }
+
+  let parsed: URL;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    throw new Error(`BotCord hubUrl must be a valid absolute URL: ${hubUrl}`);
+  }
+
+  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+    throw new Error("BotCord hubUrl must use http:// or https://");
+  }
+
+  if (parsed.protocol === "http:" && !isLoopbackHost(parsed.hostname)) {
+    throw new Error(
+      "BotCord hubUrl must use https:// unless it targets localhost, 127.0.0.1, or ::1 for local development",
+    );
+  }
+
+  return trimmed.replace(/\/$/, "");
+}
+
+export function buildHubWebSocketUrl(hubUrl: string): string {
+  const parsed = new URL(normalizeAndValidateHubUrl(hubUrl));
+  parsed.protocol = parsed.protocol === "https:" ? "wss:" : "ws:";
+  parsed.search = "";
+  parsed.hash = "";
+  parsed.pathname = `${parsed.pathname.replace(/\/$/, "")}/hub/ws`;
+  return parsed.toString();
+}