@taptapai/taptapai-openclaw 0.0.1

package/README.md

@@ -0,0 +1,141 @@
+# TapTapAI OpenClaw Plugin
+
+TapTapAI plugin for OpenClaw with outbound backend connectivity.
+
+- Primary: `wss://.../ws/openclaw/v2`
+- Fallback: `https://.../relay/*`
+
+There are **no chat setup commands**.
+
+Plugin ID: `taptapai-openclaw`
+
+Setup/pairing is done via the `taptapai` CLI (recommended) or by manually editing OpenClaw config.
+
+## Recommended setup (terminal)
+
+On the OpenClaw host:
+
+```bash
+export TAPTAPAI_BACKEND_WS_URL=wss://your-backend.example.com/ws/openclaw/v2
+export TAPTAPAI_RELAY_URL=https://your-backend.example.com
+
+taptapai setup
+```
+
+## Manual setup (advanced)
+
+### 1) Enable plugin
+
+```bash
+openclaw plugins enable taptapai-openclaw
+```
+
+### 2) Install plugin files/deps (if needed)
+
+```bash
+mkdir -p ~/.openclaw/extensions
+cp -r openclaw-plugin ~/.openclaw/extensions/taptapai
+cd ~/.openclaw/extensions/taptapai && npm install --omit=dev
+```
+
+### 3) Configure (no channels)
+
+Use plugin config under `plugins.entries.taptapai-openclaw.config`:
+
+```bash
+# Required
+openclaw config set plugins.entries.taptapai-openclaw.config.backendWsUrl "wss://your-backend.example.com/ws/openclaw/v2"
+openclaw config set plugins.entries.taptapai-openclaw.config.relayUrl "https://your-backend.example.com"
+
+# Optional (first run only). The plugin clears it after successful setup.
+openclaw config set plugins.entries.taptapai-openclaw.config.setupPassword "choose-a-strong-password"
+
+# Optional
+openclaw config set plugins.entries.taptapai-openclaw.config.pollIntervalMs 1000
+openclaw config set plugins.entries.taptapai-openclaw.config.logLevel "info"
+```
+
+After restarting the gateway, the plugin writes pairing artifacts here:
+
+- `~/.openclaw/taptapai/pairing/pairing.latest.json`
+- `~/.openclaw/taptapai/pairing/pairing.token.txt`
+- `~/.openclaw/taptapai/pairing/pairing.qr.payload.txt`
+- `~/.openclaw/taptapai/pairing/pairing.qr.terminal.txt` (ASCII QR)
+- `~/.openclaw/taptapai/pairing/pairing.qr.png` (best-effort)
+
+### 4) Restart gateway
+
+```bash
+systemctl --user restart openclaw-gateway.service
+```
+
+### 5) Pair iOS using logs
+
+```bash
+journalctl --user -u openclaw-gateway.service -n 200 --no-pager | grep -E "Pair token:|QR payload:"
+```
+
+Use the emitted token (or QR payload) in the iOS app.
+
+After successful setup, `setupPassword` is removed from config automatically.
+
+## Rotation
+
+To rotate (new token; old token becomes invalid), use:
+
+```bash
+taptapai rotate-credential
+```
+
+This prompts for the original setup password, verifies it, and then increments N.
+
+### Manual rotation (advanced)
+
+If you are not using the CLI, the plugin can still bootstrap/rotate from a one-time `setupPassword`:
+
+1) Set a new one-time password:
+
+```bash
+openclaw config set plugins.entries.taptapai-openclaw.config.setupPassword "new-strong-password"
+```
+
+2) Restart the gateway.
+
+The plugin will generate a new token (increments N), overwrite the cached secret, update config, and rewrite pairing artifacts.
+
+## Show current token/QR (no rotation)
+
+If you just need the current token + QR again, run `taptapai setup` (it prints the current token/QR without rotating).
+
+Or manually:
+
+```bash
+openclaw config set plugins.entries.taptapai-openclaw.config.emitPairingArtifacts true
+```
+
+Restart the gateway; the plugin rewrites the pairing artifacts and clears the flag.
+
+## Configuration
+
+| Option | Required | Description |
+|---|---|---|
+| `backendWsUrl` | Yes | Backend WS URL (`wss://.../ws/openclaw/v2`) |
+| `relayUrl` | Yes | Relay fallback URL (`https://...`) |
+| `pollIntervalMs` | No | Relay poll interval (ms) |
+| `setupPassword` | First run | One-time password used to derive token; auto-cleared |
+| `wsToken` / `token` | No | Auto-managed after setup |
+| `emitPairingArtifacts` | No | If true, write pairing artifacts and clear the flag |
+| `emitPairingArtifactsIncludeDataUrl` | No | If true, also write QR data URL artifact |
+| `logLevel` | No | `error`/`warn`/`info`/`debug` |
+
+## Verification
+
+```bash
+journalctl --user -u openclaw-gateway.service -n 200 --no-pager | grep -i "taptapai\|WS connected\|Pair token"
+```
+
+## Troubleshooting
+
+- If setup did not run, prefer `taptapai setup`. If doing manual setup, ensure `setupPassword` is set and restart gateway.
+- If backend WS does not connect, ensure `backendWsUrl` is `wss://`.
+- If relay is used, ensure `relayUrl` is `https://`.

package/index.ts

@@ -0,0 +1,4 @@
+// Thin entrypoint. The implementation lives under ./src for maintainability.
+import { createTapTapAiPlugin } from "./src/plugin";
+
+export default createTapTapAiPlugin();

package/openclaw.plugin.json

@@ -0,0 +1,80 @@
+{
+  "id": "taptapai-openclaw",
+  "name": "TapTapAI",
+  "description": "TapTapAI gateway proxy",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": true,
+    "properties": {
+      "enabled": {
+        "type": "boolean",
+        "description": "Enable or disable the plugin"
+      },
+      "backendWsUrl": {
+        "type": "string",
+        "description": "WebSocket URL to the TapTapAI backend (e.g., wss://taptapai.example.com/ws/openclaw/v2). Required."
+      },
+      "wsToken": {
+        "type": "string",
+        "description": "Shared secret for WebSocket authentication handshake"
+      },
+      "relayUrl": {
+        "type": "string",
+        "description": "Fallback HTTP relay URL (e.g., https://taptapai.example.com). Used when WebSocket is unavailable. Required."
+      },
+      "token": {
+        "type": "string",
+        "description": "Pairing token for the HTTP relay fallback"
+      },
+      "pollIntervalMs": {
+        "type": "number",
+        "description": "Polling interval in milliseconds for HTTP relay fallback (default: 1000)"
+      },
+      "setupPassword": {
+        "type": "string",
+        "description": "One-time setup password used on first startup to derive wsToken/token. Removed from config after successful setup."
+      },
+      "emitPairingArtifacts": {
+        "type": "boolean",
+        "description": "If true, the gateway process writes token + QR artifacts to ~/.openclaw/taptapai/pairing/ and then clears this flag."
+      },
+      "emitPairingArtifactsIncludeDataUrl": {
+        "type": "boolean",
+        "description": "If true, also write the QR data URL (pairing.qr.dataurl.txt). This can be sensitive and large; defaults to false."
+      },
+      "logLevel": {
+        "type": "string",
+        "description": "Plugin log verbosity in the gateway process.",
+        "enum": ["error", "warn", "info", "debug"],
+        "default": "info"
+      }
+    }
+  },
+  "uiHints": {
+    "setupPassword": {
+      "label": "Setup password (one-time)",
+      "sensitive": true,
+      "placeholder": "Choose a strong password"
+    },
+    "backendWsUrl": {
+      "label": "Backend WS URL",
+      "placeholder": "wss://.../ws/openclaw/v2"
+    },
+    "relayUrl": {
+      "label": "Relay URL (fallback)",
+      "placeholder": "https://..."
+    },
+    "emitPairingArtifacts": {
+      "label": "Write pairing artifacts",
+      "placeholder": "true"
+    },
+    "emitPairingArtifactsIncludeDataUrl": {
+      "label": "Include QR data URL",
+      "placeholder": "false"
+    },
+    "logLevel": {
+      "label": "Log level",
+      "placeholder": "info"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@taptapai/taptapai-openclaw",
+  "version": "0.0.1",
+  "description": "TapTapAI gateway proxy plugin",
+  "type": "module",
+  "openclaw": {
+    "extensions": ["./index.ts"]
+  },
+  "files": [
+    "index.ts",
+    "src/",
+    "openclaw.plugin.json",
+    "README.md",
+    "package.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "qrcode": "^1.5.4",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.1",
+    "@types/qrcode": "^1.5.5"
+  }
+}

package/src/backendWs.ts

@@ -0,0 +1,252 @@
+import type { LoggerLike } from "./types";
+import type { RpcRequest } from "./types";
+import { MAX_RECONNECT_DELAY_MS } from "./constants";
+import { sha256HexPrefix } from "./secrets";
+import { getWebSocketCtor } from "./websocketFactory";
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+
+let _pluginVersion = "";
+function getPluginVersion(): string {
+  if (_pluginVersion) return _pluginVersion;
+  try {
+    const dir = dirname(fileURLToPath(import.meta.url));
+    const pkg = JSON.parse(readFileSync(join(dir, "..", "package.json"), "utf8"));
+    _pluginVersion = pkg.version || "0.0.0";
+  } catch {
+    _pluginVersion = "0.0.0";
+  }
+  return _pluginVersion;
+}
+
+export type BackendWsState = {
+  ws: WebSocket | null;
+  connected: boolean;
+  connecting: boolean;
+  currentUrl: string;
+  currentTokenHash: string;
+  reconnectTimer: ReturnType<typeof setTimeout> | null;
+  reconnectAttempt: number;
+  watchdogTimer: ReturnType<typeof setInterval> | null;
+  pingTimer: ReturnType<typeof setInterval> | null;
+};
+
+export function connectBackendWs(params: {
+  state: BackendWsState;
+  logger: LoggerLike;
+  url: string;
+  token: string;
+  runtime: any;
+  onRequest: (req: RpcRequest) => Promise<void>;
+  aborted: () => boolean;
+  enabled: () => boolean;
+}): void {
+  const { state, logger, url, token, runtime, onRequest, aborted, enabled } = params;
+  if (!enabled()) return;
+  if (aborted()) return;
+
+  const normalizedUrl = String(url || "").trim();
+  const normalizedToken = String(token || "").trim();
+  const tokenHash = normalizedToken ? sha256HexPrefix(normalizedToken, 16) : "";
+
+  if (
+    state.ws &&
+    (state.ws.readyState === WebSocket.OPEN || state.ws.readyState === WebSocket.CONNECTING) &&
+    state.currentUrl === normalizedUrl &&
+    state.currentTokenHash === tokenHash
+  ) {
+    return;
+  }
+
+  if (state.ws) {
+    try { state.ws.close(); } catch {}
+    state.ws = null;
+  }
+
+  state.connected = false;
+  state.connecting = true;
+  state.currentUrl = normalizedUrl;
+  state.currentTokenHash = tokenHash;
+
+  logger.info?.(`[taptapai] Connecting WS to ${normalizedUrl}...`);
+
+  let ws: WebSocket;
+  try {
+    const WS = getWebSocketCtor(logger);
+    ws = new WS(normalizedUrl) as any;
+  } catch (e: any) {
+    const msg = e?.message || String(e);
+    logger.error?.(`[taptapai] WebSocket constructor error: ${msg}`);
+    state.connecting = false;
+    // If WebSocket isn't available, reconnecting won't help.
+    if (/WebSocket is not available/i.test(msg)) return;
+    scheduleReconnect({ ...params, url: normalizedUrl, token: normalizedToken });
+    return;
+  }
+
+  state.ws = ws;
+
+  ws.addEventListener("open", () => {
+    if (state.ws !== ws) return;
+    try {
+      logger.info?.("[taptapai] WS open, sending handshake...");
+      state.reconnectAttempt = 0;
+      ws.send(
+        JSON.stringify({
+          type: "handshake",
+          auth: { token: normalizedToken },
+          info: {
+            plugin: "taptapai",
+            version: getPluginVersion(),
+            openclaw_version: runtime?.version ?? "unknown",
+          },
+        }),
+      );
+    } catch (e: any) {
+      logger.error?.(`[taptapai] WS open handler error: ${e?.message || e}`);
+      state.connected = false;
+      state.connecting = false;
+      scheduleReconnect({ ...params, url: normalizedUrl, token: normalizedToken });
+    }
+  });
+
+  ws.addEventListener("message", async (event: MessageEvent) => {
+    if (state.ws !== ws) return;
+    const raw = typeof event.data === "string" ? event.data : (event.data as any).toString();
+    try {
+      const msg = JSON.parse(raw);
+
+      if (msg.type === "welcome") {
+        if (state.ws !== ws) return;
+        state.connected = true;
+        state.connecting = false;
+        if (state.reconnectTimer) {
+          try { clearTimeout(state.reconnectTimer); } catch {}
+          state.reconnectTimer = null;
+        }
+        logger.info?.("[taptapai] ✅ WS connected and authenticated");
+        return;
+      }
+
+      if (msg.type === "pong") return;
+
+      if (msg.id && msg.method) {
+        await onRequest(msg as RpcRequest);
+      }
+    } catch (e: any) {
+      logger.error?.(`[taptapai] WS message error: ${e?.message || e}`);
+    }
+  });
+
+  ws.addEventListener("close", (event: CloseEvent) => {
+    if (state.ws !== ws) return;
+    logger.info?.(`[taptapai] WS closed: ${event.code} ${event.reason}`);
+    state.connected = false;
+    state.connecting = false;
+    state.ws = null;
+    scheduleReconnect({ ...params, url: normalizedUrl, token: normalizedToken });
+  });
+
+  ws.addEventListener("error", (event: any) => {
+    if (state.ws !== ws) return;
+    const msg = event?.message || event?.error?.message || String(event);
+    logger.error?.(`[taptapai] WS error: ${msg}`);
+    try { ws.close(); } catch {}
+    state.ws = null;
+    state.connected = false;
+    state.connecting = false;
+    scheduleReconnect({ ...params, url: normalizedUrl, token: normalizedToken });
+  });
+
+  // Clear any previous ping timer before creating a new one
+  if (state.pingTimer) {
+    clearInterval(state.pingTimer);
+    state.pingTimer = null;
+  }
+
+  state.pingTimer = setInterval(() => {
+    if (state.ws !== ws) {
+      clearInterval(state.pingTimer!);
+      state.pingTimer = null;
+      return;
+    }
+    if (ws.readyState === WebSocket.OPEN) {
+      ws.send(JSON.stringify({ type: "ping" }));
+    } else {
+      clearInterval(state.pingTimer!);
+      state.pingTimer = null;
+    }
+  }, 25_000);
+}
+
+export function scheduleReconnect(params: {
+  state: BackendWsState;
+  logger: LoggerLike;
+  url: string;
+  token: string;
+  runtime: any;
+  onRequest: (req: RpcRequest) => Promise<void>;
+  aborted: () => boolean;
+  enabled: () => boolean;
+}): void {
+  const { state, logger, url, token, aborted, enabled } = params;
+  if (!enabled()) return;
+  if (aborted()) return;
+  if (state.reconnectTimer) return;
+  if (state.connected) return;
+  if (state.ws && (state.ws.readyState === WebSocket.OPEN || state.ws.readyState === WebSocket.CONNECTING)) return;
+  if (state.connecting) return;
+
+  state.reconnectAttempt++;
+  const delay = Math.min(1000 * Math.pow(2, state.reconnectAttempt - 1), MAX_RECONNECT_DELAY_MS);
+  logger.info?.(`[taptapai] Reconnecting in ${delay}ms (attempt ${state.reconnectAttempt})...`);
+  state.reconnectTimer = setTimeout(() => {
+    state.reconnectTimer = null;
+    connectBackendWs(params);
+  }, delay);
+}
+
+export function startBackendWatchdog(params: {
+  state: BackendWsState;
+  logger: LoggerLike;
+  url: string;
+  token: string;
+  runtime: any;
+  onRequest: (req: RpcRequest) => Promise<void>;
+  aborted: () => boolean;
+  enabled: () => boolean;
+}): void {
+  const { state, logger, url, token, aborted, enabled } = params;
+  if (!enabled()) return;
+  if (state.watchdogTimer) return;
+
+  state.watchdogTimer = setInterval(() => {
+    if (!enabled()) return;
+    if (aborted()) return;
+    if (!url) return;
+
+    if (!state.connected && !state.connecting && !state.reconnectTimer && !(state.ws && state.ws.readyState === WebSocket.CONNECTING)) {
+      logger.warn?.("[taptapai] Watchdog: backend WS disconnected, forcing reconnect");
+      try {
+        connectBackendWs(params);
+      } catch (e: any) {
+        logger.error?.(`[taptapai] Watchdog reconnect error: ${e?.message || e}`);
+      }
+    }
+  }, 10_000);
+}
+
+export function stopBackendWatchdog(state: BackendWsState): void {
+  if (!state.watchdogTimer) return;
+  clearInterval(state.watchdogTimer);
+  state.watchdogTimer = null;
+}
+
+export function sendBackendResponse(state: BackendWsState, id: string, type: string, data?: any, extra?: Record<string, any>): void {
+  if (!state.ws || state.ws.readyState !== WebSocket.OPEN) return;
+  const msg: any = { id, type };
+  if (data !== undefined) msg.data = data;
+  if (extra) Object.assign(msg, extra);
+  state.ws.send(JSON.stringify(msg));
+}

package/src/bridgeLock.ts

@@ -0,0 +1,89 @@
+import * as fs from "fs";
+import * as os from "os";
+import type { BridgeLockRecord, LoggerLike } from "./types";
+import { getBridgeLockPath } from "./paths";
+
+export function isPidRunning(pid: number): boolean {
+  if (!Number.isFinite(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export type BridgeLockState = {
+  held: boolean;
+  path: string;
+  skipLogged: boolean;
+};
+
+export function tryAcquireBridgeLock(state: BridgeLockState, logger: LoggerLike, quiet: boolean): boolean {
+  if (state.held) return true;
+  state.path = state.path || getBridgeLockPath();
+
+  const lock: BridgeLockRecord = {
+    pid: process.pid,
+    startedAt: new Date().toISOString(),
+    host: os.hostname(),
+  };
+
+  const attemptCreate = (): { ok: boolean; err?: any } => {
+    try {
+      fs.writeFileSync(state.path, JSON.stringify(lock, null, 2) + "\n", { encoding: "utf8", flag: "wx", mode: 0o600 });
+      try { fs.chmodSync(state.path, 0o600); } catch {}
+      state.held = true;
+      if (!quiet) logger.info?.(`[taptapai] Bridge lock acquired: ${state.path} (pid=${process.pid})`);
+      return { ok: true };
+    } catch (e: any) {
+      return { ok: false, err: e };
+    }
+  };
+
+  const created = attemptCreate();
+  if (created.ok) return true;
+  if (created.err && String(created.err?.code || "") && String(created.err.code) !== "EEXIST") {
+    logger.warn?.(`[taptapai] Bridge lock create failed (${created.err.code}): ${created.err?.message || created.err}`);
+    return false;
+  }
+
+  // Lock exists; if stale, remove and retry once.
+  // Use rename-to-temp-then-create to reduce TOCTOU window.
+  try {
+    const existing = JSON.parse(fs.readFileSync(state.path, "utf8")) as Partial<BridgeLockRecord>;
+    const existingPid = Number(existing?.pid ?? 0);
+    if (!isPidRunning(existingPid)) {
+      // Rename stale lock to temp, then try to create new lock atomically (wx).
+      const stalePath = state.path + ".stale." + process.pid;
+      try { fs.renameSync(state.path, stalePath); } catch {}
+      const recreated = attemptCreate();
+      try { fs.unlinkSync(stalePath); } catch {} // clean up stale
+      if (recreated.ok) return true;
+    }
+
+    if (!quiet && !state.skipLogged) {
+      state.skipLogged = true;
+      logger.info?.(
+        `[taptapai] Bridge already running (pid=${existingPid || "?"} on ${String(existing?.host || "?")}); skipping backend connections in this process.`
+      );
+    }
+  } catch {
+    if (!quiet && !state.skipLogged) {
+      state.skipLogged = true;
+      logger.warn?.("[taptapai] Bridge lock exists but could not be read; skipping backend connections in this process.");
+    }
+  }
+
+  return false;
+}
+
+export function releaseBridgeLock(state: BridgeLockState): void {
+  if (!state.held) return;
+  state.held = false;
+  try {
+    if (state.path) fs.unlinkSync(state.path);
+  } catch (e: any) {
+    // Best-effort: lock file may already be gone
+  }
+}

package/src/constants.ts

@@ -0,0 +1,14 @@
+export const PLUGIN_ID = "taptapai-openclaw";
+export const LEGACY_PLUGIN_ID = "taptapai";
+
+// Backend URLs must be explicitly configured. These are empty by default to
+// prevent connections to a potentially-hijacked third-party endpoint.
+// Users must set backendWsUrl and relayUrl in their plugin config.
+export const DEFAULT_BACKEND_HOST = "";
+export const DEFAULT_BACKEND_WS_URL = "";
+export const DEFAULT_RELAY_URL = "";
+
+export const MAX_RECONNECT_DELAY_MS = 30_000;
+
+export const GATEWAY_DEFAULT_PORT = 18789;
+export const GATEWAY_PROTOCOL_VERSION = 3;

package/src/emitArtifacts.ts

@@ -0,0 +1,46 @@
+import type { LoggerLike } from "./types";
+import { DEFAULT_BACKEND_WS_URL, DEFAULT_RELAY_URL } from "./constants";
+import { loadStoredSecret } from "./secrets";
+import { writePairingArtifacts } from "./qr";
+import { getActivePluginConfig, readOpenClawConfig, writeOpenClawConfig } from "./openclawConfig";
+
+export async function emitPairingArtifactsIfRequested(params: {
+  runtime: any;
+  pluginConfig: any;
+  logger: LoggerLike;
+  quiet: boolean;
+  getActiveSecretToken: () => string;
+}): Promise<void> {
+  const { runtime, pluginConfig, logger, quiet, getActiveSecretToken } = params;
+
+  try {
+    const requested = Boolean((pluginConfig as any)?.emitPairingArtifacts);
+    if (!requested) return;
+
+    const token = String(getActiveSecretToken() || "").trim();
+    if (!token) {
+      if (!quiet) logger.warn?.("[taptapai] emitPairingArtifacts requested but no token is configured");
+      return;
+    }
+
+    const stored = loadStoredSecret();
+    const backendWsUrl = String((pluginConfig as any)?.backendWsUrl || DEFAULT_BACKEND_WS_URL).trim();
+    const relayUrl = String((pluginConfig as any)?.relayUrl || DEFAULT_RELAY_URL).trim();
+    const includeDataUrl = Boolean((pluginConfig as any)?.emitPairingArtifactsIncludeDataUrl);
+
+    await writePairingArtifacts({ token, secret: stored, backendWsUrl, relayUrl, logger, quiet, includeDataUrl });
+
+    // Clear one-shot flag.
+    const cfg = readOpenClawConfig(logger);
+    const conf = getActivePluginConfig(cfg);
+    if (conf && "emitPairingArtifacts" in conf) {
+      delete conf.emitPairingArtifacts;
+      writeOpenClawConfig(runtime, cfg, logger);
+    }
+    if (pluginConfig && (pluginConfig as any).emitPairingArtifacts) delete (pluginConfig as any).emitPairingArtifacts;
+
+    if (!quiet) logger.info?.("[taptapai] emitPairingArtifacts completed");
+  } catch (e: any) {
+    if (!quiet) logger.warn?.(`[taptapai] emitPairingArtifacts failed: ${e?.message || e}`);
+  }
+}