@shenhh/popo 0.1.8

package/src/config-schema.ts

@@ -0,0 +1,79 @@
+import { z } from "zod";
+export { z };
+
+const DmPolicySchema = z.enum(["open", "pairing", "allowlist"]);
+const GroupPolicySchema = z.enum(["open", "allowlist", "disabled"]);
+
+const ToolPolicySchema = z
+  .object({
+    allow: z.array(z.string()).optional(),
+    deny: z.array(z.string()).optional(),
+  })
+  .strict()
+  .optional();
+
+const DmConfigSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    systemPrompt: z.string().optional(),
+  })
+  .strict()
+  .optional();
+
+// Message render mode: raw (default) = plain text, rich_text = POPO rich text format
+const RenderModeSchema = z.enum(["raw", "rich_text"]).optional();
+
+export const PopoGroupSchema = z
+  .object({
+    requireMention: z.boolean().optional(),
+    tools: ToolPolicySchema,
+    skills: z.array(z.string()).optional(),
+    enabled: z.boolean().optional(),
+    allowFrom: z.array(z.union([z.string(), z.number()])).optional(),
+    systemPrompt: z.string().optional(),
+  })
+  .strict();
+
+export type PopoGroupConfig = z.infer<typeof PopoGroupSchema>;
+
+export const PopoConfigSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    appKey: z.string().optional(),
+    appSecret: z.string().optional(),
+    token: z.string().optional(), // Token for signature verification
+    aesKey: z.string().optional(), // 32-char AES key for encryption
+    server: z
+      .string()
+      .optional()
+      .default("https://open.popo.netease.com/open-apis/robots/v1"),
+    webhookPath: z.string().optional().default("/popo/events"),
+    webhookPort: z.number().int().positive().optional(),
+    dmPolicy: DmPolicySchema.optional().default("pairing"),
+    allowFrom: z.array(z.union([z.string(), z.number()])).optional(),
+    groupPolicy: GroupPolicySchema.optional().default("allowlist"),
+    groupAllowFrom: z.array(z.union([z.string(), z.number()])).optional(),
+    requireMention: z.boolean().optional().default(true),
+    groups: z.record(z.string(), PopoGroupSchema.optional()).optional(),
+    historyLimit: z.number().int().min(0).optional(),
+    dmHistoryLimit: z.number().int().min(0).optional(),
+    dms: z.record(z.string(), DmConfigSchema).optional(),
+    textChunkLimit: z.number().int().positive().optional(),
+    chunkMode: z.enum(["length", "newline"]).optional(),
+    mediaMaxMb: z.number().positive().optional().default(20), // 20MB max
+    renderMode: RenderModeSchema, // raw = plain text (default), rich_text = POPO rich text
+  })
+  .strict()
+  .superRefine((value, ctx) => {
+    if (value.dmPolicy === "open") {
+      const allowFrom = value.allowFrom ?? [];
+      const hasWildcard = allowFrom.some((entry) => String(entry).trim() === "*");
+      if (!hasWildcard) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["allowFrom"],
+          message: 'channels.popo.dmPolicy="open" requires channels.popo.allowFrom to include "*"',
+        });
+      }
+    }
+  });

package/src/crypto.ts

@@ -0,0 +1,69 @@
+import crypto from "crypto";
+
+/**
+ * Verify POPO webhook signature.
+ * Signature = SHA256(token + nonce + timestamp)
+ */
+export function verifySignature(params: {
+  token: string;
+  nonce: string;
+  timestamp: string;
+  signature: string;
+}): boolean {
+  const { token, nonce, timestamp, signature } = params;
+  const data = token + nonce + timestamp;
+  const computed = crypto.createHash("sha256").update(data).digest("hex");
+  return computed.toLowerCase() === signature.toLowerCase();
+}
+
+/**
+ * Decrypt POPO encrypted message using AES-CBC.
+ * Key derivation: Base64 decode(aesKey + "=") -> 32 bytes, first 16 bytes = IV
+ */
+export function decryptMessage(encrypt: string, aesKey: string): string {
+  // POPO uses Base64(aesKey + "=") as the key source
+  const keyBuffer = Buffer.from(aesKey + "=", "base64");
+  if (keyBuffer.length < 32) {
+    throw new Error("Invalid AES key length");
+  }
+
+  // First 16 bytes as IV, full 32 bytes as key
+  const iv = keyBuffer.subarray(0, 16);
+  const key = keyBuffer.subarray(0, 32);
+
+  // Decrypt the base64-encoded ciphertext
+  const ciphertext = Buffer.from(encrypt, "base64");
+  const decipher = crypto.createDecipheriv("aes-256-cbc", key, iv);
+  let decrypted = decipher.update(ciphertext);
+  decrypted = Buffer.concat([decrypted, decipher.final()]);
+
+  // Remove PKCS7 padding and parse as UTF-8
+  return decrypted.toString("utf8");
+}
+
+/**
+ * Encrypt POPO response message using AES-CBC.
+ * Used to encrypt the "success" response.
+ */
+export function encryptMessage(plaintext: string, aesKey: string): string {
+  const keyBuffer = Buffer.from(aesKey + "=", "base64");
+  if (keyBuffer.length < 32) {
+    throw new Error("Invalid AES key length");
+  }
+
+  const iv = keyBuffer.subarray(0, 16);
+  const key = keyBuffer.subarray(0, 32);
+
+  const cipher = crypto.createCipheriv("aes-256-cbc", key, iv);
+  let encrypted = cipher.update(plaintext, "utf8");
+  encrypted = Buffer.concat([encrypted, cipher.final()]);
+
+  return encrypted.toString("base64");
+}
+
+/**
+ * Generate a random nonce for webhook responses.
+ */
+export function generateNonce(): string {
+  return crypto.randomBytes(16).toString("hex");
+}

package/src/media.ts

@@ -0,0 +1,299 @@
+import type { ClawdbotConfig } from "openclaw/plugin-sdk";
+import type { PopoConfig, PopoSendResult } from "./types.js";
+import { popoRequest, popoUploadRequest, popoDownloadRequest } from "./client.js";
+import { normalizePopoTarget, detectReceiverType } from "./targets.js";
+import path from "path";
+import fs from "fs";
+
+export type DownloadFileResult = {
+  buffer: Buffer;
+  contentType?: string;
+  fileName?: string;
+};
+
+/**
+ * Download a file from POPO using fileId.
+ */
+export async function downloadFilePopo(params: {
+  cfg: ClawdbotConfig;
+  fileId: string;
+}): Promise<DownloadFileResult> {
+  const { cfg, fileId } = params;
+  const popoCfg = cfg.channels?.popo as PopoConfig | undefined;
+  if (!popoCfg) {
+    throw new Error("POPO channel not configured");
+  }
+
+  const result = await popoDownloadRequest({
+    cfg: popoCfg,
+    path: `/im/file/download?fileId=${encodeURIComponent(fileId)}`,
+  });
+
+  return {
+    buffer: result.buffer,
+    contentType: result.contentType,
+  };
+}
+
+export type UploadFileResult = {
+  fileId: string;
+  fileName: string;
+};
+
+/**
+ * Upload a file to POPO.
+ */
+export async function uploadFilePopo(params: {
+  cfg: ClawdbotConfig;
+  file: Buffer | string;
+  fileName: string;
+  fileType?: string;
+}): Promise<UploadFileResult> {
+  const { cfg, file, fileName, fileType } = params;
+  const popoCfg = cfg.channels?.popo as PopoConfig | undefined;
+  if (!popoCfg) {
+    throw new Error("POPO channel not configured");
+  }
+
+  const formData = new FormData();
+
+  let fileBuffer: Buffer;
+  if (typeof file === "string") {
+    fileBuffer = fs.readFileSync(file);
+  } else {
+    fileBuffer = file;
+  }
+
+  const blob = new Blob([fileBuffer as unknown as ArrayBuffer], { type: fileType || "application/octet-stream" });
+  formData.append("file", blob, fileName);
+
+  const response = await popoUploadRequest<{ fileId: string; fileName: string }>({
+    cfg: popoCfg,
+    path: "/im/file/upload",
+    formData,
+  });
+
+  if (response.code !== 200 || !response.result) {
+    throw new Error(`POPO file upload failed: ${response.message || "unknown error"}`);
+  }
+
+  return {
+    fileId: response.result.fileId,
+    fileName: response.result.fileName,
+  };
+}
+
+/**
+ * Upload an image to POPO.
+ */
+export async function uploadImagePopo(params: {
+  cfg: ClawdbotConfig;
+  image: Buffer | string;
+  fileName?: string;
+}): Promise<UploadFileResult> {
+  const { cfg, image, fileName } = params;
+
+  let actualFileName = fileName ?? "image.png";
+  let buffer: Buffer;
+
+  if (typeof image === "string") {
+    buffer = fs.readFileSync(image);
+    if (!fileName) {
+      actualFileName = path.basename(image);
+    }
+  } else {
+    buffer = image;
+  }
+
+  // Detect content type from extension
+  const ext = path.extname(actualFileName).toLowerCase();
+  const contentTypes: Record<string, string> = {
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".bmp": "image/bmp",
+  };
+  const contentType = contentTypes[ext] || "image/png";
+
+  return uploadFilePopo({
+    cfg,
+    file: buffer,
+    fileName: actualFileName,
+    fileType: contentType,
+  });
+}
+
+/**
+ * Send an image message using a fileId.
+ */
+export async function sendImagePopo(params: {
+  cfg: ClawdbotConfig;
+  to: string;
+  fileId: string;
+}): Promise<PopoSendResult> {
+  const { cfg, to, fileId } = params;
+  const popoCfg = cfg.channels?.popo as PopoConfig | undefined;
+  if (!popoCfg) {
+    throw new Error("POPO channel not configured");
+  }
+
+  const receiver = normalizePopoTarget(to);
+  if (!receiver) {
+    throw new Error(`Invalid POPO target: ${to}`);
+  }
+
+  const receiverType = detectReceiverType(receiver);
+  const receiverKey = receiverType === "email" ? "receiver" : "groupId";
+
+  const response = await popoRequest<{ msgId?: string }>({
+    cfg: popoCfg,
+    method: "POST",
+    path: "/im/send-msg",
+    body: {
+      [receiverKey]: receiver,
+      msgType: "image",
+      message: { fileId },
+    },
+  });
+
+  if (response.code !== 200) {
+    throw new Error(`POPO image send failed: ${response.message || `code ${response.code}`}`);
+  }
+
+  return {
+    messageId: response.result?.msgId,
+    sessionId: receiver,
+  };
+}
+
+/**
+ * Send a file message using a fileId.
+ */
+export async function sendFilePopo(params: {
+  cfg: ClawdbotConfig;
+  to: string;
+  fileId: string;
+}): Promise<PopoSendResult> {
+  const { cfg, to, fileId } = params;
+  const popoCfg = cfg.channels?.popo as PopoConfig | undefined;
+  if (!popoCfg) {
+    throw new Error("POPO channel not configured");
+  }
+
+  const receiver = normalizePopoTarget(to);
+  if (!receiver) {
+    throw new Error(`Invalid POPO target: ${to}`);
+  }
+
+  const receiverType = detectReceiverType(receiver);
+  const receiverKey = receiverType === "email" ? "receiver" : "groupId";
+
+  const response = await popoRequest<{ msgId?: string }>({
+    cfg: popoCfg,
+    method: "POST",
+    path: "/im/send-msg",
+    body: {
+      [receiverKey]: receiver,
+      msgType: "file",
+      message: { fileId },
+    },
+  });
+
+  if (response.code !== 200) {
+    throw new Error(`POPO file send failed: ${response.message || `code ${response.code}`}`);
+  }
+
+  return {
+    messageId: response.result?.msgId,
+    sessionId: receiver,
+  };
+}
+
+/**
+ * Helper to detect file type from extension.
+ */
+export function detectFileType(fileName: string): "image" | "audio" | "file" {
+  const ext = path.extname(fileName).toLowerCase();
+  const imageExts = [".jpg", ".jpeg", ".png", ".gif", ".webp", ".bmp", ".ico", ".tiff"];
+  const audioExts = [".mp3", ".wav", ".ogg", ".opus", ".m4a", ".aac"];
+
+  if (imageExts.includes(ext)) return "image";
+  if (audioExts.includes(ext)) return "audio";
+  return "file";
+}
+
+/**
+ * Upload and send media (image or file) from URL, local path, or buffer.
+ */
+export async function sendMediaPopo(params: {
+  cfg: ClawdbotConfig;
+  to: string;
+  mediaUrl?: string;
+  mediaBuffer?: Buffer;
+  fileName?: string;
+}): Promise<PopoSendResult> {
+  const { cfg, to, mediaUrl, mediaBuffer, fileName } = params;
+
+  let buffer: Buffer;
+  let name: string;
+
+  if (mediaBuffer) {
+    buffer = mediaBuffer;
+    name = fileName ?? "file";
+  } else if (mediaUrl) {
+    if (isLocalPath(mediaUrl)) {
+      // Local file path - read directly
+      const filePath = mediaUrl.startsWith("~")
+        ? mediaUrl.replace("~", process.env.HOME ?? "")
+        : mediaUrl.replace("file://", "");
+
+      if (!fs.existsSync(filePath)) {
+        throw new Error(`Local file not found: ${filePath}`);
+      }
+      buffer = fs.readFileSync(filePath);
+      name = fileName ?? path.basename(filePath);
+    } else {
+      // Remote URL - fetch
+      const response = await fetch(mediaUrl);
+      if (!response.ok) {
+        throw new Error(`Failed to fetch media from URL: ${response.status}`);
+      }
+      buffer = Buffer.from(await response.arrayBuffer());
+      name = fileName ?? (path.basename(new URL(mediaUrl).pathname) || "file");
+    }
+  } else {
+    throw new Error("Either mediaUrl or mediaBuffer must be provided");
+  }
+
+  // Upload the file
+  const fileType = detectFileType(name);
+  const uploadResult = await uploadFilePopo({
+    cfg,
+    file: buffer,
+    fileName: name,
+  });
+
+  // Send based on file type
+  if (fileType === "image") {
+    return sendImagePopo({ cfg, to, fileId: uploadResult.fileId });
+  } else {
+    return sendFilePopo({ cfg, to, fileId: uploadResult.fileId });
+  }
+}
+
+/**
+ * Check if a string is a local file path (not a URL).
+ */
+function isLocalPath(urlOrPath: string): boolean {
+  if (urlOrPath.startsWith("/") || urlOrPath.startsWith("~") || /^[a-zA-Z]:/.test(urlOrPath)) {
+    return true;
+  }
+  try {
+    const url = new URL(urlOrPath);
+    return url.protocol === "file:";
+  } catch {
+    return true;
+  }
+}

package/src/monitor.ts

@@ -0,0 +1,241 @@
+import http from "http";
+import type { ClawdbotConfig, RuntimeEnv, HistoryEntry } from "openclaw/plugin-sdk";
+import type { PopoConfig } from "./types.js";
+import { resolvePopoCredentials } from "./accounts.js";
+import { verifySignature, decryptMessage, encryptMessage } from "./crypto.js";
+import { handlePopoMessage, type PopoMessageEvent } from "./bot.js";
+import { probePopo } from "./probe.js";
+
+export type MonitorPopoOpts = {
+  config?: ClawdbotConfig;
+  runtime?: RuntimeEnv;
+  abortSignal?: AbortSignal;
+  accountId?: string;
+};
+
+let currentServer: http.Server | null = null;
+
+export async function monitorPopoProvider(opts: MonitorPopoOpts = {}): Promise<void> {
+  const cfg = opts.config;
+  if (!cfg) {
+    throw new Error("Config is required for POPO monitor");
+  }
+
+  const popoCfg = cfg.channels?.popo as PopoConfig | undefined;
+  const creds = resolvePopoCredentials(popoCfg);
+  if (!creds) {
+    throw new Error("POPO credentials not configured (appKey, appSecret required)");
+  }
+
+  const log = opts.runtime?.log ?? console.log;
+  const error = opts.runtime?.error ?? console.error;
+
+  // Verify credentials by getting a token
+  const probeResult = await probePopo(popoCfg);
+  if (!probeResult.ok) {
+    throw new Error(`POPO probe failed: ${probeResult.error}`);
+  }
+  log(`popo: credentials verified for appKey ${probeResult.appKey}`);
+
+  const webhookPath = popoCfg?.webhookPath ?? "/popo/events";
+  const webhookPort = popoCfg?.webhookPort ?? 3001;
+  const chatHistories = new Map<string, HistoryEntry[]>();
+
+  return new Promise((resolve, reject) => {
+    const server = http.createServer(async (req, res) => {
+      // Handle CORS preflight
+      if (req.method === "OPTIONS") {
+        res.writeHead(200, {
+          "Access-Control-Allow-Origin": "*",
+          "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+          "Access-Control-Allow-Headers": "Content-Type, Authorization",
+        });
+        res.end();
+        return;
+      }
+
+      const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
+
+      // Only handle the webhook path
+      if (url.pathname !== webhookPath) {
+        res.writeHead(404);
+        res.end("Not Found");
+        return;
+      }
+
+      // Handle URL validation (GET request)
+      if (req.method === "GET") {
+        const nonce = url.searchParams.get("nonce");
+        const timestamp = url.searchParams.get("timestamp");
+        const signature = url.searchParams.get("signature");
+
+        if (nonce && timestamp && signature && creds.token) {
+          const valid = verifySignature({
+            token: creds.token,
+            nonce,
+            timestamp,
+            signature,
+          });
+
+          if (valid) {
+            log(`popo: URL validation successful`);
+            res.writeHead(200, { "Content-Type": "text/plain" });
+            res.end(nonce);
+            return;
+          }
+        }
+
+        res.writeHead(400);
+        res.end("Invalid validation request");
+        return;
+      }
+
+      // Handle webhook event (POST request)
+      if (req.method === "POST") {
+        try {
+          const body = await readRequestBody(req);
+          const payload = JSON.parse(body);
+
+          // Check for encrypted payload
+          let eventData: unknown;
+          if (payload.encrypt && creds.aesKey) {
+            // Verify signature first
+            const { nonce, timestamp, signature } = payload;
+            if (nonce && timestamp && signature && creds.token) {
+              const valid = verifySignature({
+                token: creds.token,
+                nonce,
+                timestamp,
+                signature,
+              });
+
+              if (!valid) {
+                log(`popo: invalid signature in webhook event`);
+                res.writeHead(403);
+                res.end("Invalid signature");
+                return;
+              }
+            }
+
+            // Decrypt the message
+            const decrypted = decryptMessage(payload.encrypt, creds.aesKey);
+            eventData = JSON.parse(decrypted);
+          } else {
+            eventData = payload;
+          }
+
+          const event = eventData as { eventType?: string };
+
+          // Handle valid_url event (inline URL validation)
+          if (event.eventType === "valid_url") {
+            log(`popo: received valid_url event`);
+            const response = { eventType: "valid_url" };
+
+            if (creds.aesKey) {
+              const encrypted = encryptMessage(JSON.stringify(response), creds.aesKey);
+              res.writeHead(200, { "Content-Type": "application/json" });
+              res.end(JSON.stringify({ encrypt: encrypted }));
+            } else {
+              res.writeHead(200, { "Content-Type": "application/json" });
+              res.end(JSON.stringify(response));
+            }
+            return;
+          }
+
+          // Handle message events
+          if (
+            event.eventType === "IM_P2P_TO_ROBOT_MSG" ||
+            event.eventType === "IM_CHAT_TO_ROBOT_AT_MSG"
+          ) {
+            const messageEvent = eventData as PopoMessageEvent;
+            log(`popo: received ${event.eventType} event`);
+
+            // Process message asynchronously
+            handlePopoMessage({
+              cfg,
+              event: messageEvent,
+              runtime: opts.runtime,
+              chatHistories,
+            }).catch((err) => {
+              error(`popo: error handling message: ${String(err)}`);
+            });
+          }
+
+          // Handle ACTION events (card interactions)
+          if (event.eventType === "ACTION") {
+            log(`popo: received ACTION event`);
+            // TODO: Implement card action handling if needed
+          }
+
+          // Return success response
+          const successResponse = { success: true };
+          if (creds.aesKey) {
+            const encrypted = encryptMessage(JSON.stringify(successResponse), creds.aesKey);
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ encrypt: encrypted }));
+          } else {
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify(successResponse));
+          }
+        } catch (err) {
+          error(`popo: error processing webhook: ${String(err)}`);
+          res.writeHead(500);
+          res.end("Internal Server Error");
+        }
+        return;
+      }
+
+      res.writeHead(405);
+      res.end("Method Not Allowed");
+    });
+
+    currentServer = server;
+
+    const cleanup = () => {
+      if (currentServer === server) {
+        server.close();
+        currentServer = null;
+      }
+    };
+
+    const handleAbort = () => {
+      log("popo: abort signal received, stopping webhook server");
+      cleanup();
+      resolve();
+    };
+
+    if (opts.abortSignal?.aborted) {
+      cleanup();
+      resolve();
+      return;
+    }
+
+    opts.abortSignal?.addEventListener("abort", handleAbort, { once: true });
+
+    server.on("error", (err) => {
+      cleanup();
+      opts.abortSignal?.removeEventListener("abort", handleAbort);
+      reject(err);
+    });
+
+    server.listen(webhookPort, () => {
+      log(`popo: webhook server started on port ${webhookPort}, path ${webhookPath}`);
+    });
+  });
+}
+
+function readRequestBody(req: http.IncomingMessage): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    req.on("data", (chunk) => chunks.push(chunk));
+    req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+    req.on("error", reject);
+  });
+}
+
+export function stopPopoMonitor(): void {
+  if (currentServer) {
+    currentServer.close();
+    currentServer = null;
+  }
+}