@shenhh/popo-oa 0.1.0

package/src/channel.ts

@@ -0,0 +1,209 @@
+import type { ChannelPlugin } from "openclaw/plugin-sdk";
+import { DEFAULT_ACCOUNT_ID, PAIRING_APPROVED_MESSAGE } from "openclaw/plugin-sdk";
+import type { ResolvedPopoOaAccount, PopoOaConfig } from "./types.js";
+import { resolvePopoOaAccount, resolvePopoOaCredentials } from "./accounts.js";
+import { popoOaOutbound } from "./outbound.js";
+import { probePopoOa } from "./probe.js";
+import { normalizePopoOaTarget, looksLikePopoOaId } from "./targets.js";
+import { sendTextPopoOa } from "./send.js";
+
+const meta = {
+  id: "popo-oa",
+  label: "POPO 服务号",
+  selectionLabel: "POPO 服务号 (网易)",
+  docsPath: "/channels/popo-oa",
+  docsLabel: "popo-oa",
+  blurb: "POPO Official Account messaging via Open API.",
+  aliases: [],
+  order: 82,
+} as const;
+
+export const popoOaPlugin: ChannelPlugin<ResolvedPopoOaAccount> = {
+  id: "popo-oa",
+  meta: {
+    ...meta,
+  },
+  pairing: {
+    idLabel: "openid",
+    normalizeAllowEntry: (entry) => entry.replace(/^(popo-oa|user):/i, ""),
+    notifyApproval: async ({ cfg, id }) => {
+      const account = resolvePopoOaAccount({ cfg });
+      await sendTextPopoOa({
+        cfg: account,
+        to: id,
+        text: PAIRING_APPROVED_MESSAGE,
+      });
+    },
+  },
+  capabilities: {
+    chatTypes: ["direct"], // POPO OA only supports direct messages
+    polls: false,
+    threads: false,
+    media: false, // Limited media support compared to Native API
+    reactions: false,
+    edit: false,
+    reply: false,
+  },
+  agentPrompt: {
+    messageToolHints: () => [
+      "- POPO 服务号 targeting: omit `target` to reply to the current conversation (auto-inferred). Explicit targets: `user:OPENID`.",
+      "- POPO 服务号 uses OpenID (not email) as user identifier.",
+    ],
+  },
+  reload: { configPrefixes: ["channels.popo-oa"] },
+  configSchema: {
+    schema: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        enabled: { type: "boolean" },
+        systemPrompt: { type: "string" },
+        appId: { type: "string" },
+        appSecret: { type: "string" },
+        token: { type: "string" },
+        server: { type: "string" },
+        webhookPath: { type: "string" },
+        dmPolicy: { type: "string", enum: ["open", "pairing", "allowlist"] },
+        allowFrom: { type: "array", items: { type: "string" } },
+        historyLimit: { type: "integer", minimum: 0 },
+        dmHistoryLimit: { type: "integer", minimum: 0 },
+        textChunkLimit: { type: "integer", minimum: 1 },
+        chunkMode: { type: "string", enum: ["length", "newline"] },
+      },
+    },
+  },
+  config: {
+    listAccountIds: () => [DEFAULT_ACCOUNT_ID],
+    resolveAccount: (cfg) => resolvePopoOaAccount({ cfg }),
+    defaultAccountId: () => DEFAULT_ACCOUNT_ID,
+    setAccountEnabled: ({ cfg, enabled }) => ({
+      ...cfg,
+      channels: {
+        ...cfg.channels,
+        "popo-oa": {
+          ...cfg.channels?.["popo-oa"],
+          enabled,
+        },
+      },
+    }),
+    deleteAccount: ({ cfg }) => {
+      const next = { ...cfg };
+      const nextChannels = { ...cfg.channels };
+      delete (nextChannels as Record<string, unknown>)["popo-oa"];
+      if (Object.keys(nextChannels).length > 0) {
+        next.channels = nextChannels;
+      } else {
+        delete next.channels;
+      }
+      return next;
+    },
+    isConfigured: (_account, cfg) =>
+      Boolean(resolvePopoOaCredentials(cfg.channels?.["popo-oa"] as PopoOaConfig | undefined)),
+    describeAccount: (account) => ({
+      accountId: account.id,
+      enabled: account.cfg.enabled !== false,
+      configured: Boolean(resolvePopoOaCredentials(account.cfg)),
+    }),
+    resolveAllowFrom: ({ cfg }) =>
+      (cfg.channels?.["popo-oa"] as PopoOaConfig | undefined)?.allowFrom ?? [],
+    formatAllowFrom: ({ allowFrom }) =>
+      allowFrom
+        .map((entry) => String(entry).trim())
+        .filter(Boolean),
+  },
+  security: {
+    collectWarnings: ({ cfg }) => {
+      const popoCfg = cfg.channels?.["popo-oa"] as PopoOaConfig | undefined;
+      const dmPolicy = popoCfg?.dmPolicy ?? "pairing";
+      if (dmPolicy !== "open") return [];
+      return [
+        `- POPO 服务号: dmPolicy="open" allows any user to interact. Set channels.popo-oa.dmPolicy="allowlist" + channels.popo-oa.allowFrom to restrict users.`,
+      ];
+    },
+  },
+  setup: {
+    resolveAccountId: () => DEFAULT_ACCOUNT_ID,
+    applyAccountConfig: ({ cfg }) => ({
+      ...cfg,
+      channels: {
+        ...cfg.channels,
+        "popo-oa": {
+          ...cfg.channels?.["popo-oa"],
+          enabled: true,
+        },
+      },
+    }),
+  },
+  messaging: {
+    normalizeTarget: normalizePopoOaTarget,
+    targetResolver: {
+      looksLikeId: looksLikePopoOaId,
+      hint: "<openid|user:OPENID>",
+    },
+  },
+  outbound: popoOaOutbound,
+  actions: {
+    listActions: ({ cfg }) => {
+      const enabled = cfg.channels?.["popo-oa"]?.enabled !== false;
+      if (!enabled) return [];
+      return ["send"];
+    },
+    supportsCards: () => false, // POPO OA doesn't support cards like Native API
+    handleAction: async (ctx) => {
+      const { action, params, cfg } = ctx;
+
+      if (action === "send") {
+        const to =
+          typeof params.to === "string"
+            ? params.to.trim()
+            : typeof params.target === "string"
+              ? params.target.trim()
+              : "";
+        const text =
+          typeof params.text === "string"
+            ? params.text
+            : typeof params.message === "string"
+              ? params.message
+              : "";
+
+        if (!to) {
+          return {
+            isError: true,
+            content: [{ type: "text", text: "Send requires a target (to)." }],
+          };
+        }
+
+        const account = resolvePopoOaAccount({ cfg });
+        const result = await sendTextPopoOa({ cfg: account, to, text });
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                ok: result.code === 0,
+                channel: "popo-oa",
+                messageId: result.data?.msgId,
+              }),
+            },
+          ],
+        };
+      }
+
+      return {
+        isError: true,
+        content: [{ type: "text", text: `Unknown action: ${action}` }],
+      };
+    },
+  },
+  health: {
+    check: async ({ cfg }) => {
+      const popoCfg = cfg.channels?.["popo-oa"] as PopoOaConfig | undefined;
+      const result = await probePopoOa(popoCfg);
+      return {
+        ok: result.ok,
+        message: result.error,
+      };
+    },
+  },
+};

package/src/client.ts

@@ -0,0 +1,167 @@
+import { getAccessToken, clearAccessToken } from "./auth.js";
+import type {
+  ResolvedPopoOaAccount,
+  PopoOaSendMessage,
+  SendMessageResponse,
+} from "./types.js";
+
+/**
+ * HTTP client for POPO OA API.
+ */
+export class PopoOaClient {
+  private account: ResolvedPopoOaAccount;
+
+  constructor(account: ResolvedPopoOaAccount) {
+    this.account = account;
+  }
+
+  /**
+   * Make an authenticated API request.
+   */
+  async request<T>({
+    path,
+    method = "GET",
+    body,
+    query,
+  }: {
+    path: string;
+    method?: "GET" | "POST" | "PUT" | "DELETE";
+    body?: unknown;
+    query?: Record<string, string>;
+  }): Promise<T> {
+    const accessToken = await getAccessToken({
+      appId: this.account.appId,
+      appSecret: this.account.appSecret,
+      server: this.account.server,
+    });
+
+    const url = new URL(path, this.account.server);
+    url.searchParams.set("access_token", accessToken);
+
+    if (query) {
+      for (const [key, value] of Object.entries(query)) {
+        url.searchParams.set(key, value);
+      }
+    }
+
+    const response = await fetch(url.toString(), {
+      method,
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: body ? JSON.stringify(body) : undefined,
+    });
+
+    // Handle token expiration
+    if (response.status === 401) {
+      clearAccessToken(this.account.appId);
+      // Retry once with new token
+      return this.request({ path, method, body, query });
+    }
+
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error(
+        `POPO OA API error: ${response.status} ${response.statusText} - ${text}`
+      );
+    }
+
+    const data = await response.json();
+    return data as T;
+  }
+
+  /**
+   * Send a message to a user.
+   */
+  async sendMessage(message: PopoOaSendMessage): Promise<SendMessageResponse> {
+    return this.request<SendMessageResponse>({
+      path: "/open/api/v1/message/send",
+      method: "POST",
+      body: message,
+    });
+  }
+
+  /**
+   * Send a text message.
+   */
+  async sendText(openid: string, content: string): Promise<SendMessageResponse> {
+    return this.sendMessage({
+      openid,
+      type: "text",
+      body: { content },
+    });
+  }
+
+  /**
+   * Send an image message.
+   */
+  async sendImage(openid: string, mediaId: string): Promise<SendMessageResponse> {
+    return this.sendMessage({
+      openid,
+      type: "image",
+      body: { mediaId },
+    });
+  }
+
+  /**
+   * Send a news (article) message.
+   */
+  async sendNews(
+    openid: string,
+    articles: Array<{
+      title: string;
+      description: string;
+      url: string;
+      picurl?: string;
+    }>
+  ): Promise<SendMessageResponse> {
+    return this.sendMessage({
+      openid,
+      type: "news",
+      body: { articles },
+    });
+  }
+
+  /**
+   * Send a list/select message.
+   */
+  async sendList(
+    openid: string,
+    header: string,
+    items: Array<{
+      title: string;
+      description?: string;
+      url?: string;
+    }>
+  ): Promise<SendMessageResponse> {
+    return this.sendMessage({
+      openid,
+      type: "list",
+      body: { header, items },
+    });
+  }
+
+  /**
+   * Send a button message.
+   */
+  async sendButton(
+    openid: string,
+    content: string,
+    buttons: Array<{ key: string; value: string }>
+  ): Promise<SendMessageResponse> {
+    return this.sendMessage({
+      openid,
+      type: "button",
+      body: { content, buttons },
+    });
+  }
+}
+
+/**
+ * Create a client for an account.
+ */
+export function createPopoOaClient(
+  account: ResolvedPopoOaAccount
+): PopoOaClient {
+  return new PopoOaClient(account);
+}

package/src/config-schema.ts

@@ -0,0 +1,50 @@
+import { z } from "zod";
+export { z };
+
+const DmPolicySchema = z.enum(["open", "pairing", "allowlist"]);
+
+const DmConfigSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    systemPrompt: z.string().optional(),
+  })
+  .strict()
+  .optional();
+
+export const PopoOaConfigSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    systemPrompt: z.string().optional(),
+    appId: z.string().optional(), // 服务号 AppID
+    appSecret: z.string().optional(), // 服务号 AppSecret
+    token: z.string().optional(), // 用于签名验证的 Token
+    server: z
+      .string()
+      .optional()
+      .default("https://open.popo.netease.com"),
+    webhookPath: z.string().optional().default("/popo-oa/events"),
+    dmPolicy: DmPolicySchema.optional().default("pairing"),
+    allowFrom: z.array(z.string()).optional(), // OpenID 白名单
+    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(),
+  })
+  .strict()
+  .superRefine((value, ctx) => {
+    if (value.dmPolicy === "open") {
+      const allowFrom = value.allowFrom ?? [];
+      const hasWildcard = allowFrom.some((entry) => entry.trim() === "*");
+      if (!hasWildcard) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["allowFrom"],
+          message:
+            'channels.popo-oa.dmPolicy="open" requires channels.popo-oa.allowFrom to include "*"',
+        });
+      }
+    }
+  });
+
+export type PopoOaConfig = z.infer<typeof PopoOaConfigSchema>;

package/src/crypto.ts

@@ -0,0 +1,44 @@
+import crypto from "crypto";
+
+/**
+ * Verify POPO OA webhook signature using SHA1.
+ * Signature = SHA1(token + timestamp + nonce) with sorted params
+ */
+export function verifySignature(
+  token: string,
+  timestamp: string,
+  nonce: string,
+  signature: string
+): boolean {
+  // Sort token, timestamp, nonce alphabetically and join
+  const str = [token, timestamp, nonce].sort().join("");
+  const computed = crypto.createHash("sha1").update(str).digest("hex");
+  return computed.toLowerCase() === signature.toLowerCase();
+}
+
+/**
+ * Generate signature for webhook verification.
+ * Used when constructing verification responses.
+ */
+export function generateSignature(
+  token: string,
+  timestamp: string,
+  nonce: string
+): string {
+  const str = [token, timestamp, nonce].sort().join("");
+  return crypto.createHash("sha1").update(str).digest("hex");
+}
+
+/**
+ * Generate a random nonce for webhook verification.
+ */
+export function generateNonce(): string {
+  return crypto.randomBytes(16).toString("hex");
+}
+
+/**
+ * Get current timestamp in seconds.
+ */
+export function getTimestamp(): string {
+  return Math.floor(Date.now() / 1000).toString();
+}

package/src/monitor.ts

@@ -0,0 +1,215 @@
+import http from "http";
+import { registerPluginHttpRoute, normalizePluginHttpPath } from "openclaw/plugin-sdk";
+import type { ClawdbotConfig, RuntimeEnv, HistoryEntry } from "openclaw/plugin-sdk";
+import type { PopoOaConfig } from "./types.js";
+import { resolvePopoOaCredentials } from "./accounts.js";
+import { verifySignature } from "./crypto.js";
+import { handlePopoOaMessage, type PopoOaMessageEvent, buildPassiveReply } from "./bot.js";
+import { probePopoOa } from "./probe.js";
+
+export type MonitorPopoOaOpts = {
+  config?: ClawdbotConfig;
+  runtime?: RuntimeEnv;
+  abortSignal?: AbortSignal;
+  accountId?: string;
+};
+
+// Helper function to read request body
+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 async function monitorPopoOaProvider(opts: MonitorPopoOaOpts = {}): Promise<void> {
+  const cfg = opts.config;
+  if (!cfg) {
+    throw new Error("Config is required for POPO OA monitor");
+  }
+
+  const popoCfg = cfg.channels?.["popo-oa"] as PopoOaConfig | undefined;
+  const creds = resolvePopoOaCredentials(popoCfg);
+  if (!creds) {
+    throw new Error("POPO OA credentials not configured (appId, appSecret, token required)");
+  }
+
+  const log = opts.runtime?.log ?? console.log;
+  const error = opts.runtime?.error ?? console.error;
+
+  // Verify credentials by getting a token
+  const probeResult = await probePopoOa(popoCfg);
+  if (!probeResult.ok) {
+    throw new Error(`POPO OA probe failed: ${probeResult.error}`);
+  }
+  log(`popo-oa: credentials verified for appId ${probeResult.appId}`);
+
+  const webhookPath = popoCfg?.webhookPath?.trim() || "/popo-oa/events";
+  const chatHistories = new Map<string, HistoryEntry[]>();
+
+  // Track approved users (for pairing policy)
+  const approvedUsers = new Set<string>();
+
+  // Normalize path
+  const normalizedPath = normalizePluginHttpPath(webhookPath, "/popo-oa/events") ?? "/popo-oa/events";
+
+  // Register HTTP route to gateway
+  const unregisterHttp = registerPluginHttpRoute({
+    path: normalizedPath,
+    pluginId: "popo-oa",
+    accountId: opts.accountId,
+    log: (msg: string) => log(msg),
+    handler: async (req, res) => {
+      const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
+      log(`popo-oa: received ${req.method} request to ${url.pathname}`);
+
+      // 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;
+      }
+
+      // Handle URL validation (GET request) - POPO OA webhook verification
+      if (req.method === "GET") {
+        const signature = url.searchParams.get("signature");
+        const timestamp = url.searchParams.get("timestamp");
+        const nonce = url.searchParams.get("nonce");
+        const echostr = url.searchParams.get("echostr");
+
+        log(`popo-oa: URL validation attempt - signature=${signature?.slice(0, 10)}..., timestamp=${timestamp}, nonce=${nonce?.slice(0, 10)}...`);
+
+        if (signature && timestamp && nonce && echostr) {
+          const valid = verifySignature(
+            creds.token,
+            timestamp,
+            nonce,
+            signature
+          );
+
+          if (valid) {
+            log(`popo-oa: URL validation successful`);
+            res.writeHead(200, { "Content-Type": "text/plain" });
+            res.end(echostr);
+            return;
+          } else {
+            log(`popo-oa: signature verification failed`);
+          }
+        } else {
+          log(`popo-oa: missing required parameters for validation`);
+        }
+
+        res.writeHead(403);
+        res.end("Invalid validation request");
+        return;
+      }
+
+      // Handle webhook event (POST request)
+      if (req.method === "POST") {
+        try {
+          const body = await readRequestBody(req);
+
+          // Verify signature for POST requests too
+          const signature = url.searchParams.get("signature");
+          const timestamp = url.searchParams.get("timestamp");
+          const nonce = url.searchParams.get("nonce");
+
+          if (signature && timestamp && nonce) {
+            const valid = verifySignature(
+              creds.token,
+              timestamp,
+              nonce,
+              signature
+            );
+
+            if (!valid) {
+              log(`popo-oa: invalid signature in webhook event`);
+              res.writeHead(403);
+              res.end("Invalid signature");
+              return;
+            }
+          }
+
+          log(`popo-oa: received XML message body length=${body.length}`);
+
+          const event: PopoOaMessageEvent = {
+            xml: {
+              ToUserName: "",
+              FromUserName: "",
+              CreateTime: String(Date.now()),
+              MsgType: "text",
+            },
+            rawBody: body,
+          };
+
+          // Process message
+          const passiveReply = await handlePopoOaMessage({
+            cfg,
+            event,
+            runtime: opts.runtime,
+            approvedUsers,
+            chatHistories,
+          });
+
+          // If there's a passive reply, return it in the response
+          if (passiveReply) {
+            const xml = buildPassiveReply({
+              toUser: event.xml.FromUserName,
+              fromUser: event.xml.ToUserName,
+              content: passiveReply,
+            });
+            res.writeHead(200, { "Content-Type": "application/xml" });
+            res.end(xml);
+            return;
+          }
+
+          // Return success response
+          res.writeHead(200, { "Content-Type": "text/plain" });
+          res.end("success");
+        } catch (err) {
+          error(`popo-oa: error processing webhook: ${String(err)}`);
+          res.writeHead(500);
+          res.end("Internal Server Error");
+        }
+        return;
+      }
+
+      res.writeHead(405);
+      res.end("Method Not Allowed");
+    },
+  });
+
+  log(`popo-oa: registered webhook handler at ${normalizedPath}`);
+
+  // Handle abort signal
+  const stopHandler = () => {
+    log("popo-oa: stopping provider");
+    unregisterHttp();
+  };
+
+  if (opts.abortSignal?.aborted) {
+    stopHandler();
+    return;
+  }
+
+  opts.abortSignal?.addEventListener("abort", stopHandler, { once: true });
+
+  // Keep promise pending until abort
+  return new Promise((resolve) => {
+    const handler = () => {
+      stopHandler();
+      resolve();
+    };
+
+    if (opts.abortSignal) {
+      opts.abortSignal.removeEventListener("abort", stopHandler);
+      opts.abortSignal.addEventListener("abort", handler, { once: true });
+    }
+  });
+}