@keychat-io/keychat-openclaw 0.1.14 → 0.1.15

package/README.md

@@ -10,115 +10,94 @@ Your agent becomes a full Keychat citizen: it can receive friend requests, estab
 
 ## Install
 
-### Option A: OpenClaw plugin (recommended)
-
 ```bash
 openclaw plugins install @keychat-io/keychat-openclaw
 openclaw gateway restart
 ```
 
+That's it. The plugin automatically downloads the bridge binary and initializes the config on first load.
+
 Supported platforms: macOS (ARM/x64), Linux (x64/ARM64).
 
-### Option B: Shell script
+Alternatively, install via shell script:
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/keychat-io/keychat-openclaw/main/scripts/install.sh | bash
 ```
 
-This clones the repo, downloads the binary, registers the plugin, and restarts the gateway in one step.
-
 ### Security Warnings
 
 During installation, OpenClaw's security scanner may show three warnings. All are expected:
 
 | Warning | Reason |
 |---------|--------|
-| Shell command execution (bridge-client.ts) | Keychat's Signal Protocol and MLS Protocol encryption are implemented in Rust. The plugin spawns a Rust sidecar process to bridge between Node.js and the native crypto layer. |
-| Shell command execution (keychain.ts) | Agent identity mnemonics are stored in the OS keychain (macOS Keychain / Linux libsecret) rather than plain files, which is the more secure option. |
-| Shell command execution (notify.ts) | After startup, the plugin notifies the agent so it can proactively send the Keychat ID and QR code to the user on their active channel (Telegram, webchat, etc). |
+| Shell command execution (bridge-client.ts) | Spawns a Rust sidecar for Signal Protocol and MLS encryption. |
+| Shell command execution (keychain.ts) | Stores identity mnemonics in the OS keychain (macOS Keychain / Linux libsecret). |
+| Shell command execution (notify.ts) | Notifies the agent on startup so it can send the Keychat ID and QR code to the user. |
 
 Source code is fully open: [github.com/keychat-io/keychat-openclaw](https://github.com/keychat-io/keychat-openclaw)
 
 ### Upgrade
 
-**Easiest way:** Just tell your agent "upgrade keychat" in any chat. The agent will handle it and reconnect automatically.
-
-Or manually:
-
-If you installed via **Option A**:
+Tell your agent "upgrade keychat" in any chat, or manually:
 
 ```bash
 openclaw plugins install @keychat-io/keychat-openclaw@latest
 openclaw gateway restart
 ```
 
-If you installed via **Option B**:
+## Add Your Agent as a Keychat Contact
 
-```bash
-curl -fsSL https://raw.githubusercontent.com/keychat-io/keychat-openclaw/main/scripts/install.sh | bash
-```
+After `openclaw gateway restart`, the agent will send you its **Keychat ID**, **contact link**, and **QR code** in your active chat (Telegram, webchat, etc.):
 
-### Connect
+```
+🔑 Keychat ID: npub1...
+📱 Add contact: https://www.keychat.io/u/?k=npub1...
+🖼️ QR code image
+```
 
-1. Run `openclaw status` — your agent's **npub** and **QR code** will be displayed
-2. Open the [Keychat app](https://keychat.io) → tap **Add Contact** on the home page
-3. Scan the QR code, or paste the npub
-4. The agent will automatically accept the friend request and establish an encrypted session
+Open the [Keychat app](https://keychat.io) → tap the link, paste the npub, or scan the QR code to add as contact. If `dmPolicy` is `open` (default after auto-init), the agent accepts immediately.
 
 ## Configuration
 
-All options go under `channels.keychat` in your OpenClaw config:
+All options go under `channels.keychat` in your OpenClaw config (`~/.openclaw/openclaw.json`):
 
 | Option             | Type     | Default                      | Description                                               |
 | ------------------ | -------- | ---------------------------- | --------------------------------------------------------- |
-| `enabled`          | boolean  | `false`                      | Enable/disable the Keychat channel                        |
+| `enabled`          | boolean  | `true`                       | Enable/disable the Keychat channel                        |
 | `name`             | string   | —                            | Display name for this account                             |
 | `relays`           | string[] | `["wss://relay.keychat.io"]` | Nostr relay WebSocket URLs                                |
-| `dmPolicy`         | enum     | `"pairing"`                  | Access policy: `pairing`, `allowlist`, `open`, `disabled` |
+| `dmPolicy`         | enum     | `"open"`                     | Access policy: `pairing`, `allowlist`, `open`, `disabled` |
 | `allowFrom`        | string[] | `[]`                         | Allowed sender pubkeys (npub or hex)                      |
-| `mnemonic`         | string   | —                            | Identity mnemonic (auto-generated, stored in keychain)    |
-| `publicKey`        | string   | —                            | Derived hex public key (read-only)                        |
-| `npub`             | string   | —                            | Derived bech32 npub (read-only)                           |
 | `lightningAddress` | string   | —                            | Lightning address for receiving payments                  |
 | `nwcUri`           | string   | —                            | Nostr Wallet Connect URI for wallet access                |
-| `markdown`         | object   | —                            | Markdown formatting overrides                             |
 
 ### DM Policies
 
-- **`pairing`** (default): New contacts require owner approval via OpenClaw's pairing system
+- **`open`**: Anyone can message the agent (default)
+- **`pairing`**: New contacts require owner approval via OpenClaw
 - **`allowlist`**: Only pubkeys in `allowFrom` can communicate
-- **`open`**: Anyone can message the agent
 - **`disabled`**: No inbound messages accepted
 
 ## Lightning Wallet
 
-Keychat supports Lightning payments:
-
 ### Lightning Address (receive-only)
 
-Configure a Lightning address so your agent can generate invoices:
-
 ```json
-{
-  "lightningAddress": "user@walletofsatoshi.com"
-}
+{ "lightningAddress": "user@walletofsatoshi.com" }
 ```
 
-The agent can create invoices via LNURL-pay protocol. Note: payment verification depends on the provider (some don't support verify URLs).
-
 ### Nostr Wallet Connect (NWC)
 
-For full wallet access (create invoices, check balance, verify payments), configure NWC:
+For full wallet access (create invoices, check balance, verify payments):
 
 ```json
-{
-  "nwcUri": "nostr+walletconnect://pubkey?relay=wss://...&secret=..."
-}
+{ "nwcUri": "nostr+walletconnect://pubkey?relay=wss://...&secret=..." }
 ```
 
 Generate an NWC connection string from your wallet app (Keychat, Alby Hub, Mutiny, Coinos, etc.).
 
-**Security note**: The agent can receive payments freely. Outbound payments require owner approval — the agent will forward the invoice to the owner instead of paying directly.
+**Security note**: The agent can receive payments freely. Outbound payments require owner approval.
 
 ## Architecture
 
@@ -133,71 +112,32 @@ Generate an NWC connection string from your wallet app (Keychat, Alby Hub, Mutin
                                   └────────────────────┘
 ```
 
-- **TypeScript plugin** (`src/channel.ts`): Integrates with OpenClaw's channel system, handles routing, pairing, and message dispatch
-- **Rust sidecar** (`bridge/`): Manages Signal Protocol sessions, Nostr transport, encryption/decryption
-- **Communication**: JSON-RPC over stdin/stdout of spawned child process
-- **Encryption**: Signal Protocol (Double Ratchet) for E2E encryption
+- **TypeScript plugin**: OpenClaw channel integration, routing, pairing, message dispatch
+- **Rust sidecar**: Signal Protocol sessions, Nostr transport, encryption/decryption
+- **Communication**: JSON-RPC over stdin/stdout
+- **Encryption**: Signal Protocol (Double Ratchet) with forward and backward secrecy
 - **Transport**: Nostr relays (kind:4 DMs + kind:1059 Gift Wrap for friend requests)
 
-## Pairing
-
-1. Agent starts and logs its **npub** and **contact URL**
-2. User opens the URL or scans the QR code in the Keychat app
-3. Keychat app sends a **friend request** (Gift Wrap, kind:1059)
-4. Agent processes the hello, establishes Signal session, and replies
-5. If `dmPolicy` is `pairing`, the owner must approve via `openclaw pair approve keychat <pubkey>`
-6. Once approved, full bidirectional encrypted chat is established
-
 ## Security
 
 - **E2E Encryption**: All messages encrypted with Signal Protocol — relay operators cannot read content
-- **Forward Secrecy**: Compromising current keys doesn't reveal past messages (Double Ratchet)
-- **Backward Secrecy**: New messages use fresh keys after each exchange
+- **Forward & Backward Secrecy**: Double Ratchet ensures compromising current keys reveals neither past nor future messages
 - **Sovereign Identity**: Agent generates its own keypair — no third-party identity provider
-- **Key Storage**: Mnemonic stored in system keychain (macOS Keychain, Linux secret service); falls back to config file
-- **Ephemeral Senders**: Each outbound message uses a fresh Nostr keypair, preventing metadata correlation
-- **Receiving Address Rotation**: Ratchet-derived addresses rotate per message, preventing traffic analysis
+- **Key Storage**: Mnemonic stored in system keychain (macOS Keychain, Linux secret service)
+- **Sending Address Rotation**: Each outbound message uses a fresh Nostr keypair, preventing metadata correlation
+- **Receiving Address Rotation**: Ratchet-derived addresses rotate almost per message, preventing traffic analysis
 
 ## Troubleshooting
 
-### Bridge not starting
-
-- Ensure the binary exists: `ls bridge/target/release/keychat-openclaw`
-- Rebuild: `cd bridge && cargo build --release`
-- Check logs for startup errors
-
-### Relay connection issues
-
-- Verify relay URLs are correct WebSocket endpoints (`wss://...`)
-- Test relay connectivity: `websocat wss://relay.keychat.io`
-- Try alternative relays
-
-### Session corruption
-
-- If messages fail to decrypt, the plugin will automatically warn the peer
-- The peer should re-add the agent as a contact to establish a new session
-- As a last resort, delete the Signal DB: `rm ~/.openclaw/keychat/signal-default.db` and restart
-
-### Messages not delivered
-
-- Check if the bridge is responsive: look for health check logs
-- The plugin queues failed messages (up to 100) and retries every 30s
-- Pending messages are also flushed after bridge restart
-
-### No QR code generated
-
-- Install the `qrcode` npm package: `npm install qrcode`
-- The contact URL in logs works without QR code
+- **Bridge not starting**: Check `ls ~/.openclaw/extensions/keychat-openclaw/bridge/target/release/keychat-openclaw`. If missing, restart gateway (auto-downloads) or build from source: `cd bridge && cargo build --release`
+- **Relay issues**: Verify relay URLs (`wss://...`), try alternative relays
+- **Decryption errors**: Peer should delete old contact and re-add the agent
+- **Messages not delivered**: Plugin queues failed messages (up to 100) and retries every 30s
 
 ## Development
 
-### Building
-
 ```bash
-# Build the Rust sidecar
 cd bridge && cargo build --release
-
-# Run tests
 cargo test
 ```
 
@@ -205,24 +145,23 @@ cargo test
 
 ```
 ├── src/
-│   ├── channel.ts        # Main channel plugin (OpenClaw integration)
-│   ├── bridge-client.ts  # TypeScript RPC client for the Rust sidecar
+│   ├── channel.ts        # Main channel plugin
+│   ├── bridge-client.ts  # RPC client for Rust sidecar
 │   ├── config-schema.ts  # Zod config schema
 │   ├── keychain.ts       # System keychain integration
-│   ├── lightning.ts      # Lightning address (LNURL-pay) support
-│   ├── nwc.ts            # Nostr Wallet Connect (NIP-47) client
+│   ├── lightning.ts      # LNURL-pay support
+│   ├── nwc.ts            # Nostr Wallet Connect (NIP-47)
 │   ├── media.ts          # Blossom media encryption/upload
 │   ├── qrcode.ts         # QR code generation
 │   ├── runtime.ts        # Plugin runtime accessor
 │   └── types.ts          # Account types and resolvers
-├── bridge/
-│   └── src/
-│       ├── main.rs       # Sidecar entry point (stdin/stdout loop)
-│       ├── rpc.rs        # JSON-RPC dispatch
-│       ├── signal.rs     # Signal Protocol manager
-│       ├── protocol.rs   # Keychat protocol types
-│       ├── mls.rs        # MLS large group support
-│       └── transport.rs  # Nostr relay transport
+├── bridge/src/
+│   ├── main.rs           # Sidecar entry point
+│   ├── rpc.rs            # JSON-RPC dispatch
+│   ├── signal.rs         # Signal Protocol manager
+│   ├── protocol.rs       # Keychat protocol types
+│   ├── mls.rs            # MLS large group support
+│   └── transport.rs      # Nostr relay transport
 ├── scripts/
 │   └── install.sh        # One-line installer
 ├── index.ts              # Plugin entry point

package/index.ts

@@ -2,7 +2,87 @@ import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
 import { keychatPlugin, getAgentKeychatId, getAgentKeychatUrl, getAllAgentContacts } from "./src/channel.js";
 import { setKeychatRuntime } from "./src/runtime.js";
-import { existsSync } from "node:fs";
+import { existsSync, mkdirSync, chmodSync, writeFileSync, readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+import https from "node:https";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/** Download a URL following redirects, return a Buffer. */
+function downloadBinary(url: string): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    https.get(url, (res) => {
+      if (res.statusCode && res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        return downloadBinary(res.headers.location).then(resolve, reject);
+      }
+      if (res.statusCode !== 200) {
+        return reject(new Error(`HTTP ${res.statusCode}`));
+      }
+      const chunks: Buffer[] = [];
+      res.on("data", (chunk: Buffer) => chunks.push(chunk));
+      res.on("end", () => resolve(Buffer.concat(chunks)));
+      res.on("error", reject);
+    }).on("error", reject);
+  });
+}
+
+/** Ensure bridge binary exists, download if missing. */
+async function ensureBinary(): Promise<void> {
+  const binaryDir = join(__dirname, "bridge", "target", "release");
+  const binaryPath = join(binaryDir, "keychat-openclaw");
+
+  if (existsSync(binaryPath)) return;
+
+  const platform = process.platform;
+  const arch = process.arch;
+  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",
+  };
+
+  const artifact = artifacts[`${platform}-${arch}`];
+  if (!artifact) {
+    console.warn(`[keychat] No pre-compiled binary for ${platform}-${arch}. Build from source: cd bridge && cargo build --release`);
+    return;
+  }
+
+  const url = `https://github.com/keychat-io/keychat-openclaw/releases/latest/download/${artifact}`;
+  console.log(`[keychat] Bridge binary not found, downloading ${artifact}...`);
+
+  try {
+    mkdirSync(binaryDir, { recursive: true });
+    const buffer = await downloadBinary(url);
+    writeFileSync(binaryPath, buffer);
+    chmodSync(binaryPath, 0o755);
+    console.log("[keychat] ✅ Bridge binary installed");
+  } catch (err: any) {
+    console.warn(`[keychat] Binary download failed: ${err.message}`);
+    console.warn("[keychat] Build from source: cd bridge && cargo build --release");
+  }
+}
+
+/** Ensure channels.keychat exists in openclaw.json config. */
+function ensureConfig(): void {
+  const configPath = join(homedir(), ".openclaw", "openclaw.json");
+  try {
+    let config: any = {};
+    if (existsSync(configPath)) {
+      config = JSON.parse(readFileSync(configPath, "utf-8"));
+    }
+    if (config.channels?.keychat) return;
+
+    if (!config.channels) config.channels = {};
+    config.channels.keychat = { enabled: true, dmPolicy: "open" };
+    writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
+    console.log("[keychat] ✅ Config initialized (channels.keychat.enabled = true)");
+  } catch (err: any) {
+    console.warn(`[keychat] Could not auto-configure: ${err.message}`);
+  }
+}
 
 const plugin = {
   id: "keychat",
@@ -14,6 +94,9 @@ const plugin = {
   register(api: OpenClawPluginApi) {
     console.log("[keychat] register() called");
     try {
+      // Auto-setup: download binary + init config on first load
+      ensureConfig();
+      ensureBinary().catch((err) => console.warn("[keychat] ensureBinary error:", err));
       setKeychatRuntime(api.runtime);
       console.log("[keychat] runtime set, registering channel...");
       api.registerChannel({ plugin: keychatPlugin });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keychat-io/keychat-openclaw",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "Keychat — E2E encrypted chat + Lightning wallet for OpenClaw agents",
   "license": "AGPL-3.0",
   "repository": {

package/scripts/install.sh

@@ -136,7 +136,8 @@ fi
 # ── Restart gateway ──
 echo ""
 echo "🔄 Restarting gateway..."
-openclaw gateway restart 2>&1 || true
+openclaw gateway install 2>&1 || true
+openclaw gateway start 2>&1 || true
 
 # ── Done ──
 echo ""
@@ -149,6 +150,6 @@ echo "To connect: open the Keychat app and scan the QR code."
 echo ""
 echo "View QR code in terminal:"
 echo "  chafa ~/.openclaw/keychat/qr-default.png"
-echo "  # or: qrencode -t ANSIUTF8 \"\$(openclaw status 2>/dev/null | grep -oP 'npub[a-z0-9]+' | head -1 | xargs -I{} echo 'https://www.keychat.io/u/?k={}')\""
+echo "  # or: qrencode -t ANSIUTF8 \"\$(openclaw status 2>/dev/null | grep -o 'npub[a-z0-9]*' | head -1 | xargs -I{} echo 'https://www.keychat.io/u/?k={}')\""
 echo ""
 echo "Docs: https://github.com/$REPO"

package/scripts/postinstall.mjs

@@ -4,7 +4,7 @@
  * Runs automatically after `npm install` / `openclaw plugins install`.
  * Uses native fetch/https — no child_process dependency.
  */
-import { existsSync, mkdirSync, chmodSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, chmodSync, writeFileSync, readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import https from "node:https";
@@ -14,11 +14,26 @@ const REPO = "keychat-io/keychat-openclaw";
 const BINARY_DIR = join(__dirname, "..", "bridge", "target", "release");
 const BINARY_PATH = join(BINARY_DIR, "keychat-openclaw");
 
-if (existsSync(BINARY_PATH)) {
-  console.log("[keychat] Binary already exists, skipping download");
+import { statSync } from "node:fs";
+
+// Read expected version from package.json
+const pkgPath = join(__dirname, "..", "package.json");
+const pkgVersion = JSON.parse(readFileSync(pkgPath, "utf-8")).version;
+const versionFile = join(BINARY_DIR, ".version");
+
+const currentVersion = existsSync(versionFile)
+  ? readFileSync(versionFile, "utf-8").trim()
+  : null;
+
+if (existsSync(BINARY_PATH) && currentVersion === pkgVersion) {
+  console.log(`[keychat] Binary already exists (v${pkgVersion}), skipping download`);
   process.exit(0);
 }
 
+if (existsSync(BINARY_PATH)) {
+  console.log(`[keychat] Binary exists but version mismatch (${currentVersion || "unknown"} → ${pkgVersion}), re-downloading...`);
+}
+
 const platform = process.platform; // darwin, linux
 const arch = process.arch; // arm64, x64
 
@@ -64,7 +79,8 @@ try {
   const buffer = await download(url);
   writeFileSync(BINARY_PATH, buffer);
   chmodSync(BINARY_PATH, 0o755);
-  console.log("[keychat] ✅ Binary installed");
+  writeFileSync(versionFile, pkgVersion + "\n");
+  console.log(`[keychat] ✅ Binary installed (v${pkgVersion})`);
 } catch (err) {
   console.warn(`[keychat] Download failed: ${err.message}`);
   console.warn("[keychat] Build from source: cd bridge && cargo build --release");
@@ -72,7 +88,6 @@ try {
 }
 
 // Auto-initialize config if channels.keychat not set
-import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 
 const configPath = join(homedir(), ".openclaw", "openclaw.json");

package/scripts/setup.sh

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# Keychat OpenClaw plugin setup
+# Downloads the bridge binary and initializes config.
+# Run after: openclaw plugins install @keychat-io/keychat-openclaw
+set -euo pipefail
+
+# --- Locate plugin directory ---
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PLUGIN_DIR="$(dirname "$SCRIPT_DIR")"
+
+# Also check common install locations
+if [ ! -f "$PLUGIN_DIR/package.json" ]; then
+  for d in \
+    "$HOME/.openclaw/extensions/keychat-openclaw" \
+    "$HOME/.openclaw/plugins/@keychat-io/keychat-openclaw"; do
+    if [ -f "$d/package.json" ]; then
+      PLUGIN_DIR="$d"
+      break
+    fi
+  done
+fi
+
+BINARY_DIR="$PLUGIN_DIR/bridge/target/release"
+BINARY_PATH="$BINARY_DIR/keychat-openclaw"
+
+# --- Download binary ---
+if [ -f "$BINARY_PATH" ]; then
+  echo "[keychat] ✅ Binary already exists: $BINARY_PATH"
+else
+  REPO="keychat-io/keychat-openclaw"
+  OS="$(uname -s | tr '[:upper:]' '[:lower:]')"
+  ARCH="$(uname -m)"
+
+  case "$OS-$ARCH" in
+    darwin-arm64)  ARTIFACT="keychat-openclaw-darwin-arm64" ;;
+    darwin-x86_64) ARTIFACT="keychat-openclaw-darwin-x64" ;;
+    linux-x86_64)  ARTIFACT="keychat-openclaw-linux-x64" ;;
+    linux-aarch64) ARTIFACT="keychat-openclaw-linux-arm64" ;;
+    *)
+      echo "[keychat] ❌ No pre-compiled binary for $OS-$ARCH"
+      echo "[keychat] Build from source: cd $PLUGIN_DIR/bridge && cargo build --release"
+      exit 1
+      ;;
+  esac
+
+  URL="https://github.com/$REPO/releases/latest/download/$ARTIFACT"
+  echo "[keychat] Downloading $ARTIFACT..."
+  mkdir -p "$BINARY_DIR"
+  curl -fsSL -o "$BINARY_PATH" "$URL"
+  chmod +x "$BINARY_PATH"
+  echo "[keychat] ✅ Binary installed: $BINARY_PATH"
+fi
+
+# --- Initialize config ---
+CONFIG_PATH="$HOME/.openclaw/openclaw.json"
+
+if [ ! -f "$CONFIG_PATH" ]; then
+  echo '{}' > "$CONFIG_PATH"
+fi
+
+# Check if channels.keychat already exists
+if node -e "
+  const c = JSON.parse(require('fs').readFileSync('$CONFIG_PATH','utf-8'));
+  process.exit(c.channels?.keychat ? 0 : 1);
+" 2>/dev/null; then
+  echo "[keychat] ✅ Config already has channels.keychat"
+else
+  node -e "
+    const fs = require('fs');
+    const c = JSON.parse(fs.readFileSync('$CONFIG_PATH','utf-8'));
+    if (!c.channels) c.channels = {};
+    c.channels.keychat = { enabled: true, dmPolicy: 'open' };
+    fs.writeFileSync('$CONFIG_PATH', JSON.stringify(c, null, 2) + '\n');
+  "
+  echo "[keychat] ✅ Config initialized (channels.keychat.enabled = true, dmPolicy = open)"
+fi
+
+echo ""
+echo "[keychat] Setup complete! Restart gateway to activate:"
+echo "  openclaw gateway install && openclaw gateway start"