@marshulll/wecom-dual 0.1.0

package/wecom/src/accounts.ts

@@ -0,0 +1,136 @@
+import type { ClawdbotConfig } from "openclaw/plugin-sdk";
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk";
+
+import type { ResolvedWecomAccount, WecomAccountConfig, WecomConfig, WecomMode } from "./types.js";
+
+function resolveEnvValue(cfg: ClawdbotConfig, name: string): string | undefined {
+  const envVars = (cfg as any)?.env?.vars ?? {};
+  const fromCfg = envVars[name];
+  if (fromCfg != null && String(fromCfg).trim() !== "") return String(fromCfg).trim();
+  const fromProcess = process.env[name];
+  if (fromProcess != null && fromProcess.trim() !== "") return fromProcess.trim();
+  return undefined;
+}
+
+function resolveAccountEnv(cfg: ClawdbotConfig, accountId: string, key: string): string | undefined {
+  const prefix = accountId === DEFAULT_ACCOUNT_ID ? "WECOM" : `WECOM_${accountId.toUpperCase()}`;
+  return resolveEnvValue(cfg, `${prefix}_${key}`);
+}
+
+function listConfiguredAccountIds(cfg: ClawdbotConfig): string[] {
+  const accounts = (cfg.channels?.wecom as WecomConfig | undefined)?.accounts;
+  if (!accounts || typeof accounts !== "object") return [];
+  return Object.keys(accounts).filter(Boolean);
+}
+
+export function listWecomAccountIds(cfg: ClawdbotConfig): string[] {
+  const ids = listConfiguredAccountIds(cfg);
+  if (ids.length === 0) return [DEFAULT_ACCOUNT_ID];
+  return ids.sort((a, b) => a.localeCompare(b));
+}
+
+export function resolveDefaultWecomAccountId(cfg: ClawdbotConfig): string {
+  const wecomConfig = cfg.channels?.wecom as WecomConfig | undefined;
+  if (wecomConfig?.defaultAccount?.trim()) return wecomConfig.defaultAccount.trim();
+  const ids = listWecomAccountIds(cfg);
+  if (ids.includes(DEFAULT_ACCOUNT_ID)) return DEFAULT_ACCOUNT_ID;
+  return ids[0] ?? DEFAULT_ACCOUNT_ID;
+}
+
+function resolveAccountConfig(cfg: ClawdbotConfig, accountId: string): WecomAccountConfig | undefined {
+  const accounts = (cfg.channels?.wecom as WecomConfig | undefined)?.accounts;
+  if (!accounts || typeof accounts !== "object") return undefined;
+  return accounts[accountId] as WecomAccountConfig | undefined;
+}
+
+function mergeWecomAccountConfig(cfg: ClawdbotConfig, accountId: string): WecomAccountConfig {
+  const raw = (cfg.channels?.wecom ?? {}) as WecomConfig;
+  const { accounts: _ignored, defaultAccount: _ignored2, ...base } = raw;
+  const account = resolveAccountConfig(cfg, accountId) ?? {};
+  return { ...base, ...account };
+}
+
+function resolveMode(raw?: string): WecomMode {
+  if (raw === "bot" || raw === "app" || raw === "both") return raw;
+  return "both";
+}
+
+export function resolveWecomAccount(params: {
+  cfg: ClawdbotConfig;
+  accountId?: string | null;
+}): ResolvedWecomAccount {
+  const accountId = normalizeAccountId(params.accountId);
+  const baseEnabled = (params.cfg.channels?.wecom as WecomConfig | undefined)?.enabled !== false;
+  const merged = mergeWecomAccountConfig(params.cfg, accountId);
+  const enabled = baseEnabled && merged.enabled !== false;
+
+  const token = merged.token?.trim()
+    || resolveAccountEnv(params.cfg, accountId, "TOKEN")
+    || undefined;
+  const encodingAESKey = merged.encodingAESKey?.trim()
+    || resolveAccountEnv(params.cfg, accountId, "ENCODING_AES_KEY")
+    || undefined;
+  const receiveId = merged.receiveId?.trim()
+    || resolveAccountEnv(params.cfg, accountId, "RECEIVE_ID")
+    || "";
+
+  const corpId = merged.corpId?.trim()
+    || resolveAccountEnv(params.cfg, accountId, "CORP_ID")
+    || undefined;
+  const corpSecret = merged.corpSecret?.trim()
+    || resolveAccountEnv(params.cfg, accountId, "CORP_SECRET")
+    || undefined;
+  const agentIdRaw = merged.agentId != null ? String(merged.agentId) : resolveAccountEnv(params.cfg, accountId, "AGENT_ID");
+  const agentId = agentIdRaw != null ? Number(agentIdRaw) : undefined;
+  const callbackToken = merged.callbackToken?.trim()
+    || resolveAccountEnv(params.cfg, accountId, "CALLBACK_TOKEN")
+    || undefined;
+  const callbackAesKey = merged.callbackAesKey?.trim()
+    || resolveAccountEnv(params.cfg, accountId, "CALLBACK_AES_KEY")
+    || undefined;
+  const webhookPath = merged.webhookPath?.trim()
+    || resolveAccountEnv(params.cfg, accountId, "WEBHOOK_PATH")
+    || undefined;
+
+  const configuredBot = Boolean(token && encodingAESKey);
+  const configuredApp = Boolean(corpId && corpSecret && agentId);
+  const configured = configuredBot || configuredApp;
+
+  const mode = resolveMode(merged.mode);
+
+  const mergedConfig: WecomAccountConfig = {
+    ...merged,
+    webhookPath,
+    token,
+    encodingAESKey,
+    receiveId,
+    corpId,
+    corpSecret,
+    agentId,
+    callbackToken,
+    callbackAesKey,
+  };
+
+  return {
+    accountId,
+    name: merged.name?.trim() || undefined,
+    enabled,
+    configured,
+    mode,
+    token,
+    encodingAESKey,
+    receiveId,
+    corpId,
+    corpSecret,
+    agentId,
+    callbackToken,
+    callbackAesKey,
+    config: mergedConfig,
+  };
+}
+
+export function listEnabledWecomAccounts(cfg: ClawdbotConfig): ResolvedWecomAccount[] {
+  return listWecomAccountIds(cfg)
+    .map((accountId) => resolveWecomAccount({ cfg, accountId }))
+    .filter((account) => account.enabled);
+}

package/wecom/src/channel.ts

@@ -0,0 +1,221 @@
+import type {
+  ChannelAccountSnapshot,
+  ChannelPlugin,
+  ClawdbotConfig,
+} from "openclaw/plugin-sdk";
+import {
+  buildChannelConfigSchema,
+  DEFAULT_ACCOUNT_ID,
+  deleteAccountFromConfigSection,
+  formatPairingApproveHint,
+  setAccountEnabledInConfigSection,
+} from "openclaw/plugin-sdk";
+
+import { listWecomAccountIds, resolveDefaultWecomAccountId, resolveWecomAccount } from "./accounts.js";
+import { WecomConfigSchema } from "./config-schema.js";
+import type { ResolvedWecomAccount } from "./types.js";
+import { registerWecomWebhookTarget } from "./monitor.js";
+
+const meta = {
+  id: "wecom",
+  label: "WeCom",
+  selectionLabel: "WeCom (plugin)",
+  docsPath: "/channels/wecom",
+  docsLabel: "wecom",
+  blurb: "Enterprise WeCom: bot API + internal app (dual mode).",
+  aliases: ["wechatwork", "wework", "qywx", "企微", "企业微信"],
+  order: 85,
+  quickstartAllowFrom: true,
+};
+
+function normalizeWecomMessagingTarget(raw: string): string | undefined {
+  const trimmed = raw.trim();
+  if (!trimmed) return undefined;
+  return trimmed.replace(/^(wecom|wechatwork|wework|qywx):/i, "").trim() || undefined;
+}
+
+export const wecomPlugin: ChannelPlugin<ResolvedWecomAccount> = {
+  id: "wecom",
+  meta,
+  capabilities: {
+    chatTypes: ["direct", "group"],
+    media: true,
+    reactions: false,
+    threads: false,
+    polls: false,
+    nativeCommands: false,
+    blockStreaming: true,
+  },
+  reload: { configPrefixes: ["channels.wecom"] },
+  configSchema: buildChannelConfigSchema(WecomConfigSchema),
+  config: {
+    listAccountIds: (cfg) => listWecomAccountIds(cfg as ClawdbotConfig),
+    resolveAccount: (cfg, accountId) => resolveWecomAccount({ cfg: cfg as ClawdbotConfig, accountId }),
+    defaultAccountId: (cfg) => resolveDefaultWecomAccountId(cfg as ClawdbotConfig),
+    setAccountEnabled: ({ cfg, accountId, enabled }) =>
+      setAccountEnabledInConfigSection({
+        cfg: cfg as ClawdbotConfig,
+        sectionKey: "wecom",
+        accountId,
+        enabled,
+        allowTopLevel: true,
+      }),
+    deleteAccount: ({ cfg, accountId }) =>
+      deleteAccountFromConfigSection({
+        cfg: cfg as ClawdbotConfig,
+        sectionKey: "wecom",
+        clearBaseFields: [
+          "name",
+          "webhookPath",
+          "token",
+          "encodingAESKey",
+          "receiveId",
+          "corpId",
+          "corpSecret",
+          "agentId",
+          "callbackToken",
+          "callbackAesKey",
+          "welcomeText",
+        ],
+        accountId,
+      }),
+    isConfigured: (account) => account.configured,
+    describeAccount: (account): ChannelAccountSnapshot => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: account.configured,
+      webhookPath: account.config.webhookPath ?? "/wecom",
+    }),
+    resolveAllowFrom: ({ cfg, accountId }) => {
+      const account = resolveWecomAccount({ cfg: cfg as ClawdbotConfig, accountId });
+      return (account.config.dm?.allowFrom ?? []).map((entry) => String(entry));
+    },
+    formatAllowFrom: ({ allowFrom }) =>
+      allowFrom
+        .map((entry) => String(entry).trim())
+        .filter(Boolean)
+        .map((entry) => entry.toLowerCase()),
+  },
+  security: {
+    resolveDmPolicy: ({ cfg, accountId, account }) => {
+      const resolvedAccountId = accountId ?? account.accountId ?? DEFAULT_ACCOUNT_ID;
+      const useAccountPath = Boolean((cfg as ClawdbotConfig).channels?.wecom?.accounts?.[resolvedAccountId]);
+      const basePath = useAccountPath ? `channels.wecom.accounts.${resolvedAccountId}.` : "channels.wecom.";
+      return {
+        policy: account.config.dm?.policy ?? "pairing",
+        allowFrom: (account.config.dm?.allowFrom ?? []).map((entry) => String(entry)),
+        policyPath: `${basePath}dm.policy`,
+        allowFromPath: `${basePath}dm.allowFrom`,
+        approveHint: formatPairingApproveHint("wecom"),
+        normalizeEntry: (raw) => raw.trim().toLowerCase(),
+      };
+    },
+  },
+  groups: {
+    resolveRequireMention: () => true,
+  },
+  threading: {
+    resolveReplyToMode: () => "off",
+  },
+  messaging: {
+    normalizeTarget: normalizeWecomMessagingTarget,
+    targetResolver: {
+      looksLikeId: (raw) => Boolean(raw.trim()),
+      hint: "<userid|chatid>",
+    },
+  },
+  outbound: {
+    deliveryMode: "direct",
+    chunkerMode: "text",
+    textChunkLimit: 20480,
+    sendText: async () => {
+      return {
+        channel: "wecom",
+        ok: false,
+        messageId: "",
+        error: new Error("WeCom outbound sendText not wired yet (skeleton)."),
+      };
+    },
+  },
+  status: {
+    defaultRuntime: {
+      accountId: DEFAULT_ACCOUNT_ID,
+      running: false,
+      lastStartAt: null,
+      lastStopAt: null,
+      lastError: null,
+    },
+    buildChannelSummary: ({ snapshot }) => ({
+      configured: snapshot.configured ?? false,
+      running: snapshot.running ?? false,
+      webhookPath: snapshot.webhookPath ?? null,
+      lastStartAt: snapshot.lastStartAt ?? null,
+      lastStopAt: snapshot.lastStopAt ?? null,
+      lastError: snapshot.lastError ?? null,
+      lastInboundAt: snapshot.lastInboundAt ?? null,
+      lastOutboundAt: snapshot.lastOutboundAt ?? null,
+      probe: snapshot.probe,
+      lastProbeAt: snapshot.lastProbeAt ?? null,
+    }),
+    probeAccount: async () => ({ ok: true }),
+    buildAccountSnapshot: ({ account, runtime }) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: account.configured,
+      webhookPath: account.config.webhookPath ?? "/wecom",
+      running: runtime?.running ?? false,
+      lastStartAt: runtime?.lastStartAt ?? null,
+      lastStopAt: runtime?.lastStopAt ?? null,
+      lastError: runtime?.lastError ?? null,
+      lastInboundAt: runtime?.lastInboundAt ?? null,
+      lastOutboundAt: runtime?.lastOutboundAt ?? null,
+      dmPolicy: account.config.dm?.policy ?? "pairing",
+    }),
+  },
+  gateway: {
+    startAccount: async (ctx) => {
+      const account = ctx.account;
+      if (!account.configured) {
+        ctx.log?.warn(`[${account.accountId}] wecom not configured; skipping webhook registration`);
+        ctx.setStatus({ accountId: account.accountId, running: false, configured: false });
+        return { stop: () => {} };
+      }
+      const path = (account.config.webhookPath ?? "/wecom").trim();
+      const unregister = registerWecomWebhookTarget({
+        account,
+        config: ctx.cfg as ClawdbotConfig,
+        runtime: ctx.runtime,
+        core: ({} as unknown) as any,
+        path,
+        statusSink: (patch) => ctx.setStatus({ accountId: ctx.accountId, ...patch }),
+      });
+      ctx.log?.info(`[${account.accountId}] wecom webhook registered at ${path}`);
+      ctx.setStatus({
+        accountId: account.accountId,
+        running: true,
+        configured: true,
+        webhookPath: path,
+        lastStartAt: Date.now(),
+      });
+      return {
+        stop: () => {
+          unregister();
+          ctx.setStatus({
+            accountId: account.accountId,
+            running: false,
+            lastStopAt: Date.now(),
+          });
+        },
+      };
+    },
+    stopAccount: async (ctx) => {
+      ctx.setStatus({
+        accountId: ctx.account.accountId,
+        running: false,
+        lastStopAt: Date.now(),
+      });
+    },
+  },
+};

package/wecom/src/commands.ts

@@ -0,0 +1,96 @@
+import type { ClawdbotConfig } from "openclaw/plugin-sdk";
+
+import { getWecomRuntime } from "./runtime.js";
+import { listWecomAccountIds } from "./accounts.js";
+import { sendWecomText } from "./wecom-api.js";
+import type { ResolvedWecomAccount } from "./types.js";
+
+export type CommandContext = {
+  account: ResolvedWecomAccount;
+  fromUser: string;
+  chatId?: string;
+  isGroup: boolean;
+  cfg: ClawdbotConfig;
+  log?: (message: string) => void;
+  statusSink?: (patch: { lastOutboundAt?: number }) => void;
+};
+
+async function sendAndRecord(ctx: CommandContext, text: string): Promise<void> {
+  await sendWecomText({ account: ctx.account, toUser: ctx.fromUser, chatId: ctx.isGroup ? ctx.chatId : undefined, text });
+  ctx.statusSink?.({ lastOutboundAt: Date.now() });
+  ctx.log?.(`[wecom] command reply sent to ${ctx.fromUser}`);
+}
+
+async function handleHelp(ctx: CommandContext): Promise<void> {
+  const helpText = `🤖 WeCom 助手使用帮助
+
+可用命令：
+/help - 显示此帮助信息
+/clear - 清除会话历史，开始新对话
+/status - 查看系统状态
+
+直接发送消息即可与 AI 对话。`;
+  await sendAndRecord(ctx, helpText);
+}
+
+async function handleStatus(ctx: CommandContext): Promise<void> {
+  const accounts = listWecomAccountIds(ctx.cfg);
+  const statusText = `📊 系统状态
+
+渠道：WeCom
+会话ID：${ctx.isGroup ? `wecom:group:${ctx.chatId}` : `wecom:${ctx.fromUser}`}
+账户ID：${ctx.account.accountId}
+已配置账户：${accounts.join(", ") || "default"}
+
+功能状态：
+✅ Bot 模式
+✅ App 模式
+✅ 文本消息
+✅ 图片接收
+✅ 语音识别
+✅ 消息分段
+✅ API 限流`;
+  await sendAndRecord(ctx, statusText);
+}
+
+async function handleClear(ctx: CommandContext): Promise<void> {
+  const runtime = getWecomRuntime();
+  const peerId = ctx.isGroup ? (ctx.chatId || "unknown") : ctx.fromUser;
+  const route = runtime.channel.routing.resolveAgentRoute({
+    cfg: ctx.cfg,
+    channel: "wecom",
+    accountId: ctx.account.accountId,
+    peer: { kind: ctx.isGroup ? "group" : "dm", id: peerId },
+  });
+  const storePath = runtime.channel.session.resolveStorePath(ctx.cfg.session?.store, {
+    agentId: route.agentId,
+  });
+
+  const clearFn = (runtime.channel.session as any).clearSession ?? (runtime.channel.session as any).deleteSession;
+  if (typeof clearFn === "function") {
+    await clearFn.call(runtime.channel.session, {
+      storePath,
+      sessionKey: route.sessionKey,
+    });
+    await sendAndRecord(ctx, "✅ 会话已清除，我们可以开始新的对话了！");
+    return;
+  }
+
+  await sendAndRecord(ctx, "✅ 会话已重置，请开始新的对话。");
+}
+
+const COMMANDS: Record<string, (ctx: CommandContext) => Promise<void>> = {
+  "/help": handleHelp,
+  "/status": handleStatus,
+  "/clear": handleClear,
+};
+
+export async function handleCommand(cmd: string, ctx: CommandContext): Promise<boolean> {
+  const key = cmd.trim().split(/\s+/)[0]?.toLowerCase();
+  if (!key) return false;
+  const handler = COMMANDS[key];
+  if (!handler) return false;
+  ctx.log?.(`[wecom] handling command ${key}`);
+  await handler(ctx);
+  return true;
+}

package/wecom/src/config-schema.ts

@@ -0,0 +1,84 @@
+import { z } from "zod";
+
+const allowFromEntry = z.union([z.string(), z.number()]);
+
+const dmSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    policy: z.enum(["pairing", "allowlist", "open", "disabled"]).optional(),
+    allowFrom: z.array(allowFromEntry).optional(),
+  })
+  .optional();
+
+const accountSchema = z.object({
+  name: z.string().optional(),
+  enabled: z.boolean().optional(),
+  mode: z.enum(["bot", "app", "both"]).optional(),
+  webhookPath: z.string().optional(),
+  welcomeText: z.string().optional(),
+  dm: dmSchema,
+
+  // Bot API
+  token: z.string().optional(),
+  encodingAESKey: z.string().optional(),
+  receiveId: z.string().optional(),
+
+  // Internal app
+  corpId: z.string().optional(),
+  corpSecret: z.string().optional(),
+  agentId: z.union([z.string(), z.number()]).optional(),
+  callbackToken: z.string().optional(),
+  callbackAesKey: z.string().optional(),
+
+  media: z.object({
+    tempDir: z.string().optional(),
+    retentionHours: z.number().optional(),
+    cleanupOnStart: z.boolean().optional(),
+    maxBytes: z.number().optional(),
+  }).optional(),
+
+  network: z.object({
+    timeoutMs: z.number().optional(),
+    retries: z.number().optional(),
+    retryDelayMs: z.number().optional(),
+  }).optional(),
+
+  botMediaBridge: z.boolean().optional(),
+});
+
+export const WecomConfigSchema = z.object({
+  name: z.string().optional(),
+  enabled: z.boolean().optional(),
+  mode: z.enum(["bot", "app", "both"]).optional(),
+  webhookPath: z.string().optional(),
+  welcomeText: z.string().optional(),
+  dm: dmSchema,
+
+  token: z.string().optional(),
+  encodingAESKey: z.string().optional(),
+  receiveId: z.string().optional(),
+
+  corpId: z.string().optional(),
+  corpSecret: z.string().optional(),
+  agentId: z.union([z.string(), z.number()]).optional(),
+  callbackToken: z.string().optional(),
+  callbackAesKey: z.string().optional(),
+
+  media: z.object({
+    tempDir: z.string().optional(),
+    retentionHours: z.number().optional(),
+    cleanupOnStart: z.boolean().optional(),
+    maxBytes: z.number().optional(),
+  }).optional(),
+
+  network: z.object({
+    timeoutMs: z.number().optional(),
+    retries: z.number().optional(),
+    retryDelayMs: z.number().optional(),
+  }).optional(),
+
+  botMediaBridge: z.boolean().optional(),
+
+  defaultAccount: z.string().optional(),
+  accounts: z.object({}).catchall(accountSchema).optional(),
+});

package/wecom/src/crypto.ts

@@ -0,0 +1,129 @@
+import crypto from "node:crypto";
+
+function decodeEncodingAESKey(encodingAESKey: string): Buffer {
+  const trimmed = encodingAESKey.trim();
+  if (!trimmed) throw new Error("encodingAESKey missing");
+  const withPadding = trimmed.endsWith("=") ? trimmed : `${trimmed}=`;
+  const key = Buffer.from(withPadding, "base64");
+  if (key.length !== 32) {
+    throw new Error(`invalid encodingAESKey (expected 32 bytes after base64 decode, got ${key.length})`);
+  }
+  return key;
+}
+
+const WECOM_PKCS7_BLOCK_SIZE = 32;
+
+function pkcs7Pad(buf: Buffer, blockSize: number): Buffer {
+  const mod = buf.length % blockSize;
+  const pad = mod === 0 ? blockSize : blockSize - mod;
+  const padByte = Buffer.from([pad]);
+  return Buffer.concat([buf, Buffer.alloc(pad, padByte[0]!)]);
+}
+
+function pkcs7Unpad(buf: Buffer, blockSize: number): Buffer {
+  if (buf.length === 0) throw new Error("invalid pkcs7 payload");
+  const pad = buf[buf.length - 1]!;
+  if (pad < 1 || pad > blockSize) {
+    throw new Error("invalid pkcs7 padding");
+  }
+  if (pad > buf.length) {
+    throw new Error("invalid pkcs7 payload");
+  }
+  for (let i = 0; i < pad; i += 1) {
+    if (buf[buf.length - 1 - i] !== pad) {
+      throw new Error("invalid pkcs7 padding");
+    }
+  }
+  return buf.subarray(0, buf.length - pad);
+}
+
+function sha1Hex(input: string): string {
+  return crypto.createHash("sha1").update(input).digest("hex");
+}
+
+export function computeWecomMsgSignature(params: {
+  token: string;
+  timestamp: string;
+  nonce: string;
+  encrypt: string;
+}): string {
+  const parts = [params.token, params.timestamp, params.nonce, params.encrypt]
+    .map((v) => String(v ?? ""))
+    .sort();
+  return sha1Hex(parts.join(""));
+}
+
+export function verifyWecomSignature(params: {
+  token: string;
+  timestamp: string;
+  nonce: string;
+  encrypt: string;
+  signature: string;
+}): boolean {
+  const expected = computeWecomMsgSignature({
+    token: params.token,
+    timestamp: params.timestamp,
+    nonce: params.nonce,
+    encrypt: params.encrypt,
+  });
+  return expected === params.signature;
+}
+
+export function decryptWecomEncrypted(params: {
+  encodingAESKey: string;
+  receiveId?: string;
+  encrypt: string;
+}): string {
+  const aesKey = decodeEncodingAESKey(params.encodingAESKey);
+  const iv = aesKey.subarray(0, 16);
+  const decipher = crypto.createDecipheriv("aes-256-cbc", aesKey, iv);
+  decipher.setAutoPadding(false);
+  const decryptedPadded = Buffer.concat([
+    decipher.update(Buffer.from(params.encrypt, "base64")),
+    decipher.final(),
+  ]);
+  const decrypted = pkcs7Unpad(decryptedPadded, WECOM_PKCS7_BLOCK_SIZE);
+
+  if (decrypted.length < 20) {
+    throw new Error(`invalid decrypted payload (expected at least 20 bytes, got ${decrypted.length})`);
+  }
+
+  const msgLen = decrypted.readUInt32BE(16);
+  const msgStart = 20;
+  const msgEnd = msgStart + msgLen;
+  if (msgEnd > decrypted.length) {
+    throw new Error(`invalid decrypted msg length (msgEnd=${msgEnd}, payloadLength=${decrypted.length})`);
+  }
+  const msg = decrypted.subarray(msgStart, msgEnd).toString("utf8");
+
+  const receiveId = params.receiveId ?? "";
+  if (receiveId) {
+    const trailing = decrypted.subarray(msgEnd).toString("utf8");
+    if (trailing !== receiveId) {
+      throw new Error(`receiveId mismatch (expected "${receiveId}", got "${trailing}")`);
+    }
+  }
+
+  return msg;
+}
+
+export function encryptWecomPlaintext(params: {
+  encodingAESKey: string;
+  receiveId?: string;
+  plaintext: string;
+}): string {
+  const aesKey = decodeEncodingAESKey(params.encodingAESKey);
+  const iv = aesKey.subarray(0, 16);
+  const random16 = crypto.randomBytes(16);
+  const msg = Buffer.from(params.plaintext ?? "", "utf8");
+  const msgLen = Buffer.alloc(4);
+  msgLen.writeUInt32BE(msg.length, 0);
+  const receiveId = Buffer.from(params.receiveId ?? "", "utf8");
+
+  const raw = Buffer.concat([random16, msgLen, msg, receiveId]);
+  const padded = pkcs7Pad(raw, WECOM_PKCS7_BLOCK_SIZE);
+  const cipher = crypto.createCipheriv("aes-256-cbc", aesKey, iv);
+  cipher.setAutoPadding(false);
+  const encrypted = Buffer.concat([cipher.update(padded), cipher.final()]);
+  return encrypted.toString("base64");
+}