@keychat-io/keychat-openclaw 0.1.8

package/src/config-schema.ts

@@ -0,0 +1,50 @@
+import { MarkdownConfigSchema, buildChannelConfigSchema } from "openclaw/plugin-sdk";
+import { z } from "zod";
+
+const allowFromEntry = z.union([z.string(), z.number()]);
+
+/** Per-account config fields (used both at top-level and inside accounts.*) */
+const KeychatAccountSchema = z.object({
+  /** Account name */
+  name: z.string().optional(),
+
+  /** Whether this channel is enabled */
+  enabled: z.boolean().optional(),
+
+  /** Markdown formatting overrides */
+  markdown: MarkdownConfigSchema.optional(),
+
+  /** Mnemonic phrase for identity (auto-generated on first start) */
+  mnemonic: z.string().optional(),
+
+  /** Public key hex (derived, read-only) */
+  publicKey: z.string().optional(),
+
+  /** npub bech32 (derived, read-only) */
+  npub: z.string().optional(),
+
+  /** WebSocket relay URLs */
+  relays: z.array(z.string()).optional(),
+
+  /** DM access policy */
+  dmPolicy: z.enum(["pairing", "allowlist", "open", "disabled"]).optional(),
+
+  /** Allowed sender pubkeys (npub or hex format) */
+  allowFrom: z.array(allowFromEntry).optional(),
+
+  /** Lightning address for receiving payments (e.g. "user@walletofsatoshi.com") */
+  lightningAddress: z.string().optional(),
+
+  /** Nostr Wallet Connect URI (nostr+walletconnect://...) for Lightning wallet access */
+  nwcUri: z.string().optional(),
+});
+
+/** Top-level keychat config: single-account fields + optional multi-account map. */
+export const KeychatConfigSchema = KeychatAccountSchema.extend({
+  /** Multiple named accounts, each with its own identity/config. */
+  accounts: z.record(z.string(), KeychatAccountSchema).optional(),
+});
+
+export type KeychatConfig = z.infer<typeof KeychatConfigSchema>;
+
+export const keychatChannelConfigSchema = buildChannelConfigSchema(KeychatConfigSchema);

package/src/ensure-binary.ts

@@ -0,0 +1,65 @@
+/**
+ * Auto-download the keychat-openclaw bridge binary if missing.
+ * Called before bridge startup. Downloads from GitHub Releases.
+ * Uses native fetch — no child_process dependency.
+ */
+
+import { existsSync, mkdirSync, chmodSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const REPO = "keychat-io/keychat-openclaw";
+
+const ARTIFACTS: Record<string, string> = {
+  "darwin-arm64": "keychat-openclaw-darwin-arm64",
+  "darwin-x64": "keychat-openclaw-darwin-x64",
+  "linux-x64": "keychat-openclaw-linux-x64",
+  "linux-arm64": "keychat-openclaw-linux-arm64",
+};
+
+export function getBridgePath(): string {
+  return join(
+    import.meta.dirname ?? ".",
+    "..",
+    "bridge",
+    "target",
+    "release",
+    "keychat-openclaw",
+  );
+}
+
+export async function ensureBinary(): Promise<string> {
+  const binaryPath = getBridgePath();
+  if (existsSync(binaryPath)) return binaryPath;
+
+  const key = `${process.platform}-${process.arch}`;
+  const artifact = ARTIFACTS[key];
+  if (!artifact) {
+    throw new Error(
+      `No pre-compiled keychat-openclaw binary for ${key}. ` +
+      `Build from source: cd bridge && cargo build --release`
+    );
+  }
+
+  const url = `https://github.com/${REPO}/releases/latest/download/${artifact}`;
+  console.log(`[keychat] Downloading bridge binary (${artifact})...`);
+
+  const dir = join(binaryPath, "..");
+  mkdirSync(dir, { recursive: true });
+
+  try {
+    const response = await fetch(url, { redirect: "follow" });
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+    const buffer = Buffer.from(await response.arrayBuffer());
+    writeFileSync(binaryPath, buffer);
+    chmodSync(binaryPath, 0o755);
+    console.log("[keychat] ✅ Bridge binary downloaded");
+    return binaryPath;
+  } catch (err: any) {
+    throw new Error(
+      `Failed to download bridge binary: ${err.message}\n` +
+      `Build from source: cd bridge && cargo build --release`
+    );
+  }
+}

package/src/keychain.ts

@@ -0,0 +1,75 @@
+/**
+ * Secure mnemonic storage using system keychain.
+ * Falls back gracefully if keychain is unavailable.
+ *
+ * macOS: Uses `security` CLI (Keychain Access)
+ * Linux: Uses `secret-tool` (libsecret / GNOME Keyring)
+ *
+ * Note: This file intentionally uses child_process for system keychain access.
+ * This triggers an OpenClaw scanner warning ("Shell command execution detected")
+ * which is expected — keychain storage is more secure than file-based alternatives.
+ */
+
+import { execFileSync } from "node:child_process";
+
+const SERVICE = "openclaw-keychat";
+
+export async function storeMnemonic(accountId: string, mnemonic: string): Promise<boolean> {
+  const key = `mnemonic-${accountId}`;
+  try {
+    if (process.platform === "darwin") {
+      execFileSync("security", [
+        "add-generic-password", "-a", key, "-s", SERVICE, "-w", mnemonic, "-U",
+      ], { stdio: "pipe" });
+      return true;
+    } else if (process.platform === "linux") {
+      execFileSync("secret-tool", [
+        "store", "--label", SERVICE, "service", SERVICE, "account", key,
+      ], { stdio: "pipe", input: mnemonic });
+      return true;
+    }
+  } catch {
+    // Keychain not available
+  }
+  return false;
+}
+
+export async function retrieveMnemonic(accountId: string): Promise<string | null> {
+  const key = `mnemonic-${accountId}`;
+  try {
+    if (process.platform === "darwin") {
+      const result = execFileSync("security", [
+        "find-generic-password", "-a", key, "-s", SERVICE, "-w",
+      ], { stdio: "pipe" });
+      return result.toString().trim();
+    } else if (process.platform === "linux") {
+      const result = execFileSync("secret-tool", [
+        "lookup", "service", SERVICE, "account", key,
+      ], { stdio: "pipe" });
+      return result.toString().trim();
+    }
+  } catch {
+    // Not found or keychain unavailable
+  }
+  return null;
+}
+
+export async function deleteMnemonic(accountId: string): Promise<boolean> {
+  const key = `mnemonic-${accountId}`;
+  try {
+    if (process.platform === "darwin") {
+      execFileSync("security", [
+        "delete-generic-password", "-a", key, "-s", SERVICE,
+      ], { stdio: "pipe" });
+      return true;
+    } else if (process.platform === "linux") {
+      execFileSync("secret-tool", [
+        "clear", "service", SERVICE, "account", key,
+      ], { stdio: "pipe" });
+      return true;
+    }
+  } catch {
+    // Not found
+  }
+  return false;
+}

package/src/lightning.ts

@@ -0,0 +1,128 @@
+/**
+ * Lightning wallet — receive-only via Lightning Address (LNURL-pay).
+ *
+ * The agent can:
+ * - Generate invoices from its configured Lightning address
+ * - Tell users its Lightning address for payments
+ * - Forward outbound payment requests (invoices) to the owner
+ *
+ * The agent CANNOT send payments directly.
+ */
+
+export interface LnurlPayMetadata {
+  callback: string;
+  minSendable: number; // millisatoshis
+  maxSendable: number; // millisatoshis
+  metadata: string;
+  tag: string;
+}
+
+export interface LnurlInvoice {
+  pr: string; // BOLT11 payment request
+  routes: unknown[];
+  verify?: string; // verification URL
+}
+
+/**
+ * Parse a Lightning address into a LNURL-pay endpoint URL.
+ * e.g. "user@domain.com" → "https://domain.com/.well-known/lnurlp/user"
+ */
+export function lightningAddressToLnurlp(address: string): string | null {
+  const parts = address.trim().split("@");
+  if (parts.length !== 2) return null;
+  const [user, domain] = parts;
+  if (!user || !domain) return null;
+  return `https://${domain}/.well-known/lnurlp/${user}`;
+}
+
+/**
+ * Fetch LNURL-pay metadata for a Lightning address.
+ */
+export async function fetchLnurlPayMetadata(
+  lightningAddress: string,
+): Promise<LnurlPayMetadata | null> {
+  const url = lightningAddressToLnurlp(lightningAddress);
+  if (!url) return null;
+
+  try {
+    const res = await fetch(url, {
+      headers: { Accept: "application/json" },
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!res.ok) return null;
+    const data = (await res.json()) as LnurlPayMetadata;
+    if (data.tag !== "payRequest") return null;
+    return data;
+  } catch (err) {
+    console.error(`[keychat/lightning] Failed to fetch LNURL-pay metadata: ${err}`);
+    return null;
+  }
+}
+
+/**
+ * Request an invoice from the LNURL-pay callback.
+ * @param amountSats Amount in satoshis
+ * @param comment Optional comment/memo
+ */
+export async function requestInvoice(
+  lightningAddress: string,
+  amountSats: number,
+  comment?: string,
+): Promise<LnurlInvoice | null> {
+  const meta = await fetchLnurlPayMetadata(lightningAddress);
+  if (!meta) return null;
+
+  const amountMsats = amountSats * 1000;
+  if (amountMsats < meta.minSendable || amountMsats > meta.maxSendable) {
+    console.error(
+      `[keychat/lightning] Amount ${amountSats} sats outside range: ${meta.minSendable / 1000}-${meta.maxSendable / 1000} sats`,
+    );
+    return null;
+  }
+
+  let callbackUrl = `${meta.callback}${meta.callback.includes("?") ? "&" : "?"}amount=${amountMsats}`;
+  if (comment) {
+    callbackUrl += `&comment=${encodeURIComponent(comment)}`;
+  }
+
+  try {
+    const res = await fetch(callbackUrl, {
+      headers: { Accept: "application/json" },
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!res.ok) return null;
+    const data = (await res.json()) as LnurlInvoice;
+    if (!data.pr) return null;
+    return data;
+  } catch (err) {
+    console.error(`[keychat/lightning] Failed to request invoice: ${err}`);
+    return null;
+  }
+}
+
+/**
+ * Verify if an invoice has been paid (if verify URL is available).
+ */
+export async function verifyPayment(verifyUrl: string): Promise<boolean> {
+  try {
+    const res = await fetch(verifyUrl, {
+      headers: { Accept: "application/json" },
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!res.ok) return false;
+    const data = (await res.json()) as { settled: boolean };
+    return data.settled === true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Format satoshi amounts for display.
+ */
+export function formatSats(sats: number): string {
+  if (sats >= 100_000_000) return `${(sats / 100_000_000).toFixed(8)} BTC`;
+  if (sats >= 1_000_000) return `${(sats / 1_000_000).toFixed(2)}M sats`;
+  if (sats >= 1_000) return `${(sats / 1_000).toFixed(1)}k sats`;
+  return `${sats} sats`;
+}

package/src/media.ts

@@ -0,0 +1,189 @@
+import { createDecipheriv, createCipheriv, randomBytes, createHash } from "node:crypto";
+import { writeFile, mkdir, readFile } from "node:fs/promises";
+import { join, extname, basename } from "node:path";
+import { MEDIA_DIR } from "./paths.js";
+
+export interface KeychatMediaInfo {
+  url: string;
+  kctype: string;
+  suffix: string;
+  key: string;
+  iv: string;
+  size: number;
+  hash?: string;
+  sourceName?: string;
+}
+
+export interface MediaUploadResult {
+  /** The full Keychat media URL with encryption params */
+  mediaUrl: string;
+  /** The kctype (image, video, file) */
+  kctype: string;
+}
+
+/** Default Blossom media server (same as Keychat app default) */
+const DEFAULT_MEDIA_SERVER = "https://relay.keychat.io";
+
+/** Determine kctype from file extension or mime type */
+function resolveKctype(filePath: string, mimeType?: string): string {
+  const ext = extname(filePath).toLowerCase();
+  const imageExts = [".jpg", ".jpeg", ".png", ".gif", ".bmp", ".webp", ".tiff", ".svg"];
+  const videoExts = [".mp4", ".avi", ".mov", ".mkv", ".webm", ".flv", ".wmv", ".m4v"];
+
+  if (mimeType?.startsWith("image/") || imageExts.includes(ext)) return "image";
+  if (mimeType?.startsWith("video/") || videoExts.includes(ext)) return "video";
+  return "file";
+}
+
+/**
+ * Encrypt a file with AES-256-CTR (matches Keychat app's encryptFile).
+ * Returns the encrypted bytes + key/iv/hash/suffix/sourceName.
+ */
+async function encryptFile(filePath: string): Promise<{
+  encrypted: Buffer;
+  key: string;
+  iv: string;
+  hash: string;
+  suffix: string;
+  sourceName: string;
+}> {
+  const fileBytes = await readFile(filePath);
+  const key = randomBytes(32);
+  const iv = randomBytes(16);
+
+  const cipher = createCipheriv("aes-256-ctr", key, iv);
+  const encrypted = Buffer.concat([cipher.update(fileBytes), cipher.final()]);
+
+  const sha256 = createHash("sha256").update(encrypted).digest("base64");
+
+  const fileName = basename(filePath);
+  const suffix = extname(filePath).replace(".", "");
+
+  return {
+    encrypted,
+    key: key.toString("base64"),
+    iv: iv.toString("base64"),
+    hash: sha256,
+    suffix,
+    sourceName: fileName,
+  };
+}
+
+/**
+ * Upload encrypted bytes to a Blossom server.
+ * Uses Nostr auth (kind:24242 event signed by agent's key).
+ */
+async function uploadToBlossom(
+  encrypted: Buffer,
+  hash: string,
+  signEvent: (content: string, tags: string[][]) => Promise<string>,
+  server?: string,
+): Promise<string> {
+  const baseUrl = server || DEFAULT_MEDIA_SERVER;
+
+  // Sign authorization event (kind:24242)
+  const expiration = Math.floor(Date.now() / 1000) + 86400 * 30; // 30 days
+  const eventJson = await signEvent(hash, [
+    ["t", "upload"],
+    ["x", hash],
+    ["expiration", expiration.toString()],
+  ]);
+
+  const authHeader = `Nostr ${Buffer.from(eventJson).toString("base64")}`;
+
+  const response = await fetch(`${baseUrl}/upload`, {
+    method: "PUT",
+    headers: {
+      "Content-Type": "application/octet-stream",
+      Authorization: authHeader,
+    },
+    body: new Uint8Array(encrypted),
+  });
+
+  if (!response.ok) {
+    const body = await response.text().catch(() => "");
+    throw new Error(`Blossom upload failed (${response.status}): ${body}`);
+  }
+
+  const data = (await response.json()) as { url?: string; size?: number };
+  if (!data.url) throw new Error("Blossom upload response missing url");
+  return data.url;
+}
+
+/**
+ * Encrypt and upload a local file, returning a Keychat media URL.
+ *
+ * @param filePath - Local file path to upload
+ * @param signEvent - Function to sign a Nostr kind:24242 event for Blossom auth
+ * @param server - Optional Blossom server URL (defaults to relay.keychat.io)
+ * @param mimeType - Optional MIME type hint
+ */
+export async function encryptAndUpload(
+  filePath: string,
+  signEvent: (content: string, tags: string[][]) => Promise<string>,
+  server?: string,
+  mimeType?: string,
+): Promise<MediaUploadResult> {
+  const { encrypted, key, iv, hash, suffix, sourceName } = await encryptFile(filePath);
+  const url = await uploadToBlossom(encrypted, hash, signEvent, server);
+  const kctype = resolveKctype(filePath, mimeType);
+
+  // Construct the Keychat media URL (same format as app)
+  const parsedUrl = new URL(url);
+  const mediaUrl = new URL(parsedUrl.origin + parsedUrl.pathname);
+  mediaUrl.searchParams.set("kctype", kctype);
+  mediaUrl.searchParams.set("suffix", suffix);
+  mediaUrl.searchParams.set("key", key);
+  mediaUrl.searchParams.set("iv", iv);
+  mediaUrl.searchParams.set("size", encrypted.length.toString());
+  mediaUrl.searchParams.set("hash", hash);
+  mediaUrl.searchParams.set("sourceName", sourceName);
+
+  return { mediaUrl: mediaUrl.toString(), kctype };
+}
+
+/** Parse a Keychat encrypted media URL. Returns null if not a media message. */
+export function parseMediaUrl(content: string): KeychatMediaInfo | null {
+  const trimmed = content.trim();
+  if (!trimmed.startsWith("http://") && !trimmed.startsWith("https://")) return null;
+
+  let uri: URL;
+  try { uri = new URL(trimmed); } catch { return null; }
+
+  const kctype = uri.searchParams.get("kctype");
+  if (!kctype) return null;
+
+  const key = uri.searchParams.get("key");
+  const iv = uri.searchParams.get("iv");
+  if (!key || !iv) return null;
+
+  return {
+    url: uri.origin + uri.pathname,
+    kctype,
+    suffix: uri.searchParams.get("suffix") || kctype,
+    key,
+    iv,
+    size: parseInt(uri.searchParams.get("size") || "0", 10),
+    hash: uri.searchParams.get("hash") || undefined,
+    sourceName: uri.searchParams.get("sourceName") || undefined,
+  };
+}
+
+/** Download and decrypt a Keychat media file. Returns local file path. */
+export async function downloadAndDecrypt(media: KeychatMediaInfo): Promise<string> {
+  const response = await fetch(media.url);
+  if (!response.ok) throw new Error(`Download failed: ${response.status}`);
+  const encrypted = Buffer.from(await response.arrayBuffer());
+
+  const keyBuf = Buffer.from(media.key, "base64");
+  const ivBuf = Buffer.from(media.iv, "base64");
+  const decipher = createDecipheriv("aes-256-ctr", keyBuf, ivBuf);
+  const decrypted = Buffer.concat([decipher.update(encrypted)]);
+
+  await mkdir(MEDIA_DIR, { recursive: true });
+  const filename = media.sourceName || `${Date.now()}.${media.suffix}`;
+  const filepath = join(MEDIA_DIR, filename);
+  await writeFile(filepath, decrypted);
+
+  return filepath;
+}