@netcat-ai/openclaw-weixin 2.4.7

package/src/auth/login-qr.ts

@@ -0,0 +1,458 @@
+import { randomUUID } from "node:crypto";
+
+import { apiGetFetch, apiPostFetch } from "../api/api.js";
+import { listIndexedWeixinAccountIds, loadWeixinAccount } from "./accounts.js";
+import { logger } from "../util/logger.js";
+import { redactToken } from "../util/redact.js";
+
+type ActiveLogin = {
+  sessionKey: string;
+  id: string;
+  qrcode: string;
+  qrcodeUrl: string;
+  startedAt: number;
+  botToken?: string;
+  status?: "wait" | "scaned" | "confirmed" | "expired" | "scaned_but_redirect" | "need_verifycode" | "verify_code_blocked" | "binded_redirect";
+  error?: string;
+  /** The current effective polling base URL; may be updated on IDC redirect. */
+  currentApiBaseUrl?: string;
+  /** 待提交的配对码，用户输入后暂存，下次轮询时携带 */
+  pendingVerifyCode?: string;
+};
+
+const ACTIVE_LOGIN_TTL_MS = 5 * 60_000;
+/** Client-side timeout for the long-poll get_qrcode_status request. */
+const QR_LONG_POLL_TIMEOUT_MS = 35_000;
+
+/** Default `bot_type` for ilink get_bot_qrcode / get_qrcode_status (this channel build). */
+export const DEFAULT_ILINK_BOT_TYPE = "3";
+
+const activeLogins = new Map<string, ActiveLogin>();
+
+interface QRCodeResponse {
+  qrcode: string;
+  qrcode_img_content: string;
+}
+
+interface StatusResponse {
+  status: "wait" | "scaned" | "confirmed" | "expired" | "scaned_but_redirect" | "need_verifycode" | "verify_code_blocked" | "binded_redirect";
+  bot_token?: string;
+  ilink_bot_id?: string;
+  baseurl?: string;
+  /** The user ID of the person who scanned the QR code. */
+  ilink_user_id?: string;
+  /** New host to redirect polling to when status is scaned_but_redirect. */
+  redirect_host?: string;
+}
+
+function isLoginFresh(login: ActiveLogin): boolean {
+  return Date.now() - login.startedAt < ACTIVE_LOGIN_TTL_MS;
+}
+
+/** Remove all expired entries from the activeLogins map to prevent memory leaks. */
+function purgeExpiredLogins(): void {
+  for (const [id, login] of activeLogins) {
+    if (!isLoginFresh(login)) {
+      activeLogins.delete(id);
+    }
+  }
+}
+
+/** 获取本地已登录账号的 bot token 列表，最多返回最新的 10 个。 */
+function getLocalBotTokenList(): string[] {
+  const accountIds = listIndexedWeixinAccountIds();
+  const tokens: string[] = [];
+  // 从最新注册的账号开始取（列表末尾为最新）
+  for (let i = accountIds.length - 1; i >= 0 && tokens.length < 10; i--) {
+    const data = loadWeixinAccount(accountIds[i]);
+    const token = data?.token?.trim();
+    if (token) {
+      tokens.push(token);
+    }
+  }
+  return tokens;
+}
+
+async function fetchQRCode(apiBaseUrl: string, botType: string): Promise<QRCodeResponse> {
+  logger.info(`NewFetching QR code from: ${apiBaseUrl} bot_type=${botType}`);
+  const localTokenList = getLocalBotTokenList();
+  logger.info(`newfetchQRCode: local_token_list count=${localTokenList.length}`);
+  const rawText = await apiPostFetch({
+    baseUrl: apiBaseUrl,
+    endpoint: `ilink/bot/get_bot_qrcode?bot_type=${encodeURIComponent(botType)}`,
+    body: JSON.stringify({ local_token_list: localTokenList }),
+    label: "fetchQRCode",
+  });
+  return JSON.parse(rawText) as QRCodeResponse;
+}
+
+/** 从 stdin 读取一行用户输入，输出提示语后等待回车确认，返回 trim 后的字符串。 */
+async function readVerifyCodeFromStdin(prompt: string): Promise<string> {
+  process.stdout.write(prompt);
+  return new Promise((resolve) => {
+    let input = "";
+    const onData = (chunk: Buffer | string) => {
+      const str = chunk.toString();
+      input += str;
+      if (input.includes("\n")) {
+        process.stdin.removeListener("data", onData);
+        process.stdin.pause();
+        resolve(input.trim());
+      }
+    };
+    process.stdin.resume();
+    process.stdin.setEncoding("utf-8");
+    process.stdin.on("data", onData);
+  });
+}
+
+async function pollQRStatus(apiBaseUrl: string, qrcode: string, verifyCode?: string): Promise<StatusResponse> {
+  logger.debug(`Long-poll QR status from: ${apiBaseUrl} qrcode=***`);
+  try {
+    let endpoint = `ilink/bot/get_qrcode_status?qrcode=${encodeURIComponent(qrcode)}`;
+    if (verifyCode) {
+      endpoint += `&verify_code=${encodeURIComponent(verifyCode)}`;
+    }
+    const rawText = await apiGetFetch({
+      baseUrl: apiBaseUrl,
+      endpoint,
+      timeoutMs: QR_LONG_POLL_TIMEOUT_MS,
+      label: "pollQRStatus",
+    });
+    logger.debug(`pollQRStatus: body=${rawText.substring(0, 200)}`);
+    return JSON.parse(rawText) as StatusResponse;
+  } catch (err) {
+    if (err instanceof Error && err.name === "AbortError") {
+      logger.debug(`pollQRStatus: client-side timeout after ${QR_LONG_POLL_TIMEOUT_MS}ms, returning wait`);
+      return { status: "wait" };
+    }
+    // 网关超时（如 Cloudflare 524）或其他网络错误，视为等待状态继续轮询
+    logger.warn(`pollQRStatus: network/gateway error, will retry: ${String(err)}`);
+    return { status: "wait" };
+  }
+}
+
+/**
+ * 在终端展示二维码及备用链接。
+ * 供 CLI 登录流程和 MCP Tool 登录流程共同复用。
+ */
+export async function displayQRCode(qrcodeUrl: string): Promise<void> {
+  try {
+    const qrterm = await import("qrcode-terminal");
+    qrterm.default.generate(qrcodeUrl, { small: true });
+    process.stdout.write(`若二维码未能显示或无法使用，你可以访问以下链接以继续：\n`);
+    process.stdout.write(`${qrcodeUrl}\n`);
+  } catch {
+    process.stdout.write(`若二维码未能显示或无法使用，你可以访问以下链接以继续：\n`);
+    process.stdout.write(`${qrcodeUrl}\n`);
+  }
+}
+
+export type WeixinQrStartResult = {
+  qrcodeUrl?: string;
+  message: string;
+  sessionKey: string;
+};
+
+export type WeixinQrWaitResult = {
+  connected: boolean;
+  /**
+   * Server reported `binded_redirect`: the scanned bot is already bound to
+   * this OpenClaw instance, so no new credentials are issued and existing
+   * local credentials remain valid. Callers should treat this as a successful
+   * outcome (semantically "already done") rather than a login failure.
+   */
+  alreadyConnected?: boolean;
+  botToken?: string;
+  accountId?: string;
+  baseUrl?: string;
+  /** The user ID of the person who scanned the QR code; add to allowFrom. */
+  userId?: string;
+  message: string;
+};
+
+export async function startWeixinLoginWithQr(opts: {
+  verbose?: boolean;
+  force?: boolean;
+  accountId?: string;
+  apiBaseUrl: string;
+  botType?: string;
+}): Promise<WeixinQrStartResult> {
+  const sessionKey = opts.accountId || randomUUID();
+
+  purgeExpiredLogins();
+
+  const existing = activeLogins.get(sessionKey);
+  if (!opts.force && existing && isLoginFresh(existing) && existing.qrcodeUrl) {
+    return {
+      qrcodeUrl: existing.qrcodeUrl,
+      message: "二维码已显示，请用手机微信扫描。",
+      sessionKey,
+    };
+  }
+
+  try {
+    const botType = opts.botType || DEFAULT_ILINK_BOT_TYPE;
+    logger.info(`Starting Weixin login with bot_type=${botType}`);
+
+    const qrResponse = await fetchQRCode(opts.apiBaseUrl, botType);
+    logger.info(
+      `QR code received, qrcode=${redactToken(qrResponse.qrcode)} imgContentLen=${qrResponse.qrcode_img_content?.length ?? 0}`,
+    );
+    logger.info(`二维码链接: ${qrResponse.qrcode_img_content}`);
+
+    const login: ActiveLogin = {
+      sessionKey,
+      id: randomUUID(),
+      qrcode: qrResponse.qrcode,
+      qrcodeUrl: qrResponse.qrcode_img_content,
+      startedAt: Date.now(),
+    };
+
+    activeLogins.set(sessionKey, login);
+
+    return {
+      qrcodeUrl: qrResponse.qrcode_img_content,
+      message: "用手机微信扫描以下二维码，以继续连接：",
+      sessionKey,
+    };
+  } catch (err) {
+    logger.error(`Failed to start Weixin login: ${String(err)}`);
+    return {
+      message: `Failed to start login: ${String(err)}`,
+      sessionKey,
+    };
+  }
+}
+
+const MAX_QR_REFRESH_COUNT = 3;
+
+/**
+ * 刷新二维码并展示给用户，返回是否成功。
+ * 成功时更新 activeLogin 的 qrcode/qrcodeUrl/startedAt，并重置 scannedPrinted。
+ */
+async function refreshQRCode(
+  activeLogin: ActiveLogin,
+  apiBaseUrl: string,
+  botType: string,
+  qrRefreshCount: number,
+  onScannedReset: () => void,
+): Promise<{ success: true } | { success: false; message: string }> {
+  process.stdout.write(`\n⏳ 正在刷新二维码...(${qrRefreshCount}/${MAX_QR_REFRESH_COUNT})\n`);
+  logger.info(`waitForWeixinLogin: refreshing QR code (${qrRefreshCount}/${MAX_QR_REFRESH_COUNT})`);
+  try {
+    const qrResponse = await fetchQRCode(apiBaseUrl, botType);
+    activeLogin.qrcode = qrResponse.qrcode;
+    activeLogin.qrcodeUrl = qrResponse.qrcode_img_content;
+    activeLogin.startedAt = Date.now();
+    onScannedReset();
+    logger.info(`waitForWeixinLogin: new QR code obtained qrcode=${redactToken(qrResponse.qrcode)}`);
+    process.stdout.write(`🔄 二维码已更新，请重新扫描。\n\n`);
+    await displayQRCode(qrResponse.qrcode_img_content);
+    return { success: true };
+  } catch (refreshErr) {
+    logger.error(`waitForWeixinLogin: failed to refresh QR code: ${String(refreshErr)}`);
+    return { success: false, message: `刷新二维码失败: ${String(refreshErr)}` };
+  }
+}
+
+export async function waitForWeixinLogin(opts: {
+  timeoutMs?: number;
+  verbose?: boolean;
+  sessionKey: string;
+  apiBaseUrl: string;
+  botType?: string;
+}): Promise<WeixinQrWaitResult> {
+  let activeLogin = activeLogins.get(opts.sessionKey);
+
+  if (!activeLogin) {
+    logger.warn(`waitForWeixinLogin: no active login sessionKey=${opts.sessionKey}`);
+    return {
+      connected: false,
+      message: "当前没有进行中的登录，请先发起登录。",
+    };
+  }
+
+  if (!isLoginFresh(activeLogin)) {
+    logger.warn(`waitForWeixinLogin: login QR expired sessionKey=${opts.sessionKey}`);
+    activeLogins.delete(opts.sessionKey);
+    return {
+      connected: false,
+      message: "二维码已过期，请重新生成。",
+    };
+  }
+
+  const timeoutMs = Math.max(opts.timeoutMs ?? 480_000, 1000);
+  const deadline = Date.now() + timeoutMs;
+  let scannedPrinted = false;
+  let qrRefreshCount = 1;
+
+  // Initialize the effective polling base URL; may be updated on IDC redirect.
+  activeLogin.currentApiBaseUrl = opts.apiBaseUrl;
+
+  logger.info("Starting to poll QR code status...");
+
+  while (Date.now() < deadline) {
+    try {
+      const currentBaseUrl = activeLogin.currentApiBaseUrl ?? opts.apiBaseUrl;
+      const statusResponse = await pollQRStatus(currentBaseUrl, activeLogin.qrcode, activeLogin.pendingVerifyCode);
+      logger.debug(`pollQRStatus: status=${statusResponse.status} hasBotToken=${Boolean(statusResponse.bot_token)} hasBotId=${Boolean(statusResponse.ilink_bot_id)}`);
+      activeLogin.status = statusResponse.status;
+
+      switch (statusResponse.status) {
+        case "wait":
+          if (opts.verbose) {
+            process.stdout.write(".");
+          }
+          break;
+        case "scaned":
+          // 若携带了配对码且服务端返回 scaned，说明验证码正确，清除暂存
+          if (activeLogin.pendingVerifyCode) {
+            logger.info("verify code accepted, resuming polling");
+            activeLogin.pendingVerifyCode = undefined;
+          }
+          if (!scannedPrinted) {
+            process.stdout.write("\n正在验证\n");
+            scannedPrinted = true;
+          }
+          break;
+        case "need_verifycode": {
+          // 首次进入提示输入，再次进入（已有 pendingVerifyCode）说明上次输入错误
+          const verifyPrompt = activeLogin.pendingVerifyCode
+            ? "❌ 你输入的数字不匹配，请重新输入："
+            : "输入手机微信显示的数字，以继续连接：";
+          const code = await readVerifyCodeFromStdin(verifyPrompt);
+          activeLogin.pendingVerifyCode = code;
+          // 立即进入下一次轮询，不等待 1s
+          continue;
+        }
+        case "expired": {
+          qrRefreshCount++;
+          if (qrRefreshCount > MAX_QR_REFRESH_COUNT) {
+            logger.warn(
+              `waitForWeixinLogin: QR expired ${MAX_QR_REFRESH_COUNT} times, giving up sessionKey=${opts.sessionKey}`,
+            );
+            activeLogins.delete(opts.sessionKey);
+            return {
+              connected: false,
+              message: "二维码多次失效，连接流程已停止。请稍后再试。",
+            };
+          }
+
+          process.stdout.write(`\n⏳ 二维码已过期，正在刷新...\n`);
+          const expiredRefreshResult = await refreshQRCode(
+            activeLogin,
+            opts.apiBaseUrl,
+            opts.botType || DEFAULT_ILINK_BOT_TYPE,
+            qrRefreshCount,
+            () => { scannedPrinted = false; },
+          );
+          if (!expiredRefreshResult.success) {
+            activeLogins.delete(opts.sessionKey);
+            return { connected: false, message: expiredRefreshResult.message };
+          }
+          break;
+        }
+        case "verify_code_blocked": {
+          logger.warn(
+            `waitForWeixinLogin: verify code blocked, qrRefreshCount=${qrRefreshCount} sessionKey=${opts.sessionKey}`,
+          );
+          process.stdout.write("\n⛔ 多次输入错误，请稍后再试。\n");
+          // 清除配对码暂存
+          activeLogin.pendingVerifyCode = undefined;
+
+          qrRefreshCount++;
+          if (qrRefreshCount > MAX_QR_REFRESH_COUNT) {
+            logger.warn(
+              `waitForWeixinLogin: verify_code_blocked and QR refresh limit reached, giving up sessionKey=${opts.sessionKey}`,
+            );
+            activeLogins.delete(opts.sessionKey);
+            return {
+              connected: false,
+              message: "多次输入错误，连接流程已停止。请稍后再试。",
+            };
+          }
+
+          const blockedRefreshResult = await refreshQRCode(
+            activeLogin,
+            opts.apiBaseUrl,
+            opts.botType || DEFAULT_ILINK_BOT_TYPE,
+            qrRefreshCount,
+            () => { scannedPrinted = false; },
+          );
+          if (!blockedRefreshResult.success) {
+            activeLogins.delete(opts.sessionKey);
+            return { connected: false, message: blockedRefreshResult.message };
+          }
+          break;
+        }
+        case "binded_redirect": {
+          logger.info(`waitForWeixinLogin: binded_redirect received, bot already bound sessionKey=${opts.sessionKey}`);
+          process.stdout.write("\n✅ 已连接过此 OpenClaw，无需重复连接。\n");
+          activeLogins.delete(opts.sessionKey);
+          return {
+            connected: false,
+            alreadyConnected: true,
+            message: "已连接过此 OpenClaw，无需重复连接。",
+          };
+        }
+        case "scaned_but_redirect": {
+          const redirectHost = statusResponse.redirect_host;
+          if (redirectHost) {
+            const newBaseUrl = `https://${redirectHost}`;
+            activeLogin.currentApiBaseUrl = newBaseUrl;
+            logger.info(`waitForWeixinLogin: IDC redirect, switching polling host to ${redirectHost}`);
+          } else {
+            logger.warn(`waitForWeixinLogin: received scaned_but_redirect but redirect_host is missing, continuing with current host`);
+          }
+          break;
+        }
+        case "confirmed": {
+          if (!statusResponse.ilink_bot_id) {
+            activeLogins.delete(opts.sessionKey);
+            logger.error("Login confirmed but ilink_bot_id missing from response");
+            return {
+              connected: false,
+              message: "登录失败：服务器未返回 ilink_bot_id。",
+            };
+          }
+
+          activeLogin.botToken = statusResponse.bot_token;
+          activeLogins.delete(opts.sessionKey);
+
+          logger.info(
+            `✅ Login confirmed! ilink_bot_id=${statusResponse.ilink_bot_id} ilink_user_id=${redactToken(statusResponse.ilink_user_id)}`,
+          );
+
+          return {
+            connected: true,
+            botToken: statusResponse.bot_token,
+            accountId: statusResponse.ilink_bot_id,
+            baseUrl: statusResponse.baseurl,
+            userId: statusResponse.ilink_user_id,
+            message: "已将此 OpenClaw 连接到微信。",
+          };
+        }
+      }
+
+    } catch (err) {
+      logger.error(`Error polling QR status: ${String(err)}`);
+      activeLogins.delete(opts.sessionKey);
+      return {
+        connected: false,
+        message: `Login failed: ${String(err)}`,
+      };
+    }
+
+    await new Promise((r) => setTimeout(r, 1000));
+  }
+
+  logger.warn(
+    `waitForWeixinLogin: timed out waiting for QR scan sessionKey=${opts.sessionKey} timeoutMs=${timeoutMs}`,
+  );
+  activeLogins.delete(opts.sessionKey);
+  return {
+    connected: false,
+    message: "登录超时，请重试。",
+  };
+}

package/src/auth/pairing.ts

@@ -0,0 +1,120 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { withFileLock } from "openclaw/plugin-sdk/infra-runtime";
+
+import { resolveStateDir } from "../storage/state-dir.js";
+import { logger } from "../util/logger.js";
+
+/**
+ * Resolve the framework credentials directory (mirrors core resolveOAuthDir).
+ * Path: $OPENCLAW_OAUTH_DIR || $OPENCLAW_STATE_DIR/credentials || ~/.openclaw/credentials
+ */
+function resolveCredentialsDir(): string {
+  const override = process.env.OPENCLAW_OAUTH_DIR?.trim();
+  if (override) return override;
+  return path.join(resolveStateDir(), "credentials");
+}
+
+/**
+ * Sanitize a channel/account key for safe use in filenames (mirrors core safeChannelKey).
+ */
+function safeKey(raw: string): string {
+  const trimmed = raw.trim().toLowerCase();
+  if (!trimmed) throw new Error("invalid key for allowFrom path");
+  const safe = trimmed.replace(/[\\/:*?"<>|]/g, "_").replace(/\.\./g, "_");
+  if (!safe || safe === "_") throw new Error("invalid key for allowFrom path");
+  return safe;
+}
+
+/**
+ * Resolve the framework allowFrom file path for a given account.
+ * Mirrors: `resolveAllowFromPath(channel, env, accountId)` from core.
+ * Path: `<credDir>/openclaw-weixin-<accountId>-allowFrom.json`
+ */
+export function resolveFrameworkAllowFromPath(accountId: string): string {
+  const base = safeKey("openclaw-weixin");
+  const safeAccount = safeKey(accountId);
+  return path.join(resolveCredentialsDir(), `${base}-${safeAccount}-allowFrom.json`);
+}
+
+type AllowFromFileContent = {
+  version: number;
+  allowFrom: string[];
+};
+
+/**
+ * Read the framework allowFrom list for an account (user IDs authorized via pairing).
+ * Returns an empty array when the file is missing or unreadable.
+ */
+export function readFrameworkAllowFromList(accountId: string): string[] {
+  const filePath = resolveFrameworkAllowFromPath(accountId);
+  try {
+    if (!fs.existsSync(filePath)) return [];
+    const raw = fs.readFileSync(filePath, "utf-8");
+    const parsed = JSON.parse(raw) as AllowFromFileContent;
+    if (Array.isArray(parsed.allowFrom)) {
+      return parsed.allowFrom.filter((id): id is string => typeof id === "string" && id.trim() !== "");
+    }
+  } catch {
+    // best-effort
+  }
+  return [];
+}
+
+/** File lock options matching the framework's pairing store lock settings. */
+const LOCK_OPTIONS = {
+  retries: { retries: 3, factor: 2, minTimeout: 100, maxTimeout: 2000 },
+  stale: 10_000,
+};
+
+/**
+ * Register a user ID in the framework's channel allowFrom store.
+ * This writes directly to the same JSON file that `readChannelAllowFromStore` reads,
+ * making the user visible to the framework authorization pipeline.
+ *
+ * Uses file locking to avoid races with concurrent readers/writers.
+ */
+export async function registerUserInFrameworkStore(params: {
+  accountId: string;
+  userId: string;
+}): Promise<{ changed: boolean }> {
+  const { accountId, userId } = params;
+  const trimmedUserId = userId.trim();
+  if (!trimmedUserId) return { changed: false };
+
+  const filePath = resolveFrameworkAllowFromPath(accountId);
+
+  const dir = path.dirname(filePath);
+  fs.mkdirSync(dir, { recursive: true });
+
+  // Ensure the file exists before locking
+  if (!fs.existsSync(filePath)) {
+    const initial: AllowFromFileContent = { version: 1, allowFrom: [] };
+    fs.writeFileSync(filePath, JSON.stringify(initial, null, 2), "utf-8");
+  }
+
+  return await withFileLock(filePath, LOCK_OPTIONS, async () => {
+    let content: AllowFromFileContent = { version: 1, allowFrom: [] };
+    try {
+      const raw = fs.readFileSync(filePath, "utf-8");
+      const parsed = JSON.parse(raw) as AllowFromFileContent;
+      if (Array.isArray(parsed.allowFrom)) {
+        content = parsed;
+      }
+    } catch {
+      // If read/parse fails, start fresh
+    }
+
+    if (content.allowFrom.includes(trimmedUserId)) {
+      return { changed: false };
+    }
+
+    content.allowFrom.push(trimmedUserId);
+    fs.writeFileSync(filePath, JSON.stringify(content, null, 2), "utf-8");
+    logger.info(
+      `registerUserInFrameworkStore: added userId=${trimmedUserId} accountId=${accountId} path=${filePath}`,
+    );
+    return { changed: true };
+  });
+}

package/src/cdn/aes-ecb.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared AES-128-ECB crypto utilities for CDN upload and download.
+ */
+import { createCipheriv, createDecipheriv } from "node:crypto";
+
+/** Encrypt buffer with AES-128-ECB (PKCS7 padding is default). */
+export function encryptAesEcb(plaintext: Buffer, key: Buffer): Buffer {
+  const cipher = createCipheriv("aes-128-ecb", key, null);
+  return Buffer.concat([cipher.update(plaintext), cipher.final()]);
+}
+
+/** Decrypt buffer with AES-128-ECB (PKCS7 padding). */
+export function decryptAesEcb(ciphertext: Buffer, key: Buffer): Buffer {
+  const decipher = createDecipheriv("aes-128-ecb", key, null);
+  return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+}
+
+/** Compute AES-128-ECB ciphertext size (PKCS7 padding to 16-byte boundary). */
+export function aesEcbPaddedSize(plaintextSize: number): number {
+  return Math.ceil((plaintextSize + 1) / 16) * 16;
+}

package/src/cdn/cdn-upload.ts

@@ -0,0 +1,93 @@
+import { encryptAesEcb } from "./aes-ecb.js";
+import { buildCdnUploadUrl } from "./cdn-url.js";
+import { logger } from "../util/logger.js";
+import { redactUrl } from "../util/redact.js";
+
+/** Maximum retry attempts for CDN upload. */
+const UPLOAD_MAX_RETRIES = 3;
+
+/**
+ * Upload one buffer to the Weixin CDN with AES-128-ECB encryption.
+ * Returns the download encrypted_query_param from the CDN response.
+ * Retries up to UPLOAD_MAX_RETRIES times on server errors; client errors (4xx) abort immediately.
+ */
+export async function uploadBufferToCdn(params: {
+  buf: Buffer;
+  /** From getUploadUrl.upload_full_url; POST target when set (takes precedence over uploadParam). */
+  uploadFullUrl?: string;
+  uploadParam?: string;
+  filekey: string;
+  cdnBaseUrl: string;
+  label: string;
+  aeskey: Buffer;
+}): Promise<{ downloadParam: string }> {
+  const { buf, uploadFullUrl, uploadParam, filekey, cdnBaseUrl, label, aeskey } = params;
+  const ciphertext = encryptAesEcb(buf, aeskey);
+  const trimmedFull = uploadFullUrl?.trim();
+  let cdnUrl: string;
+  if (trimmedFull) {
+    cdnUrl = trimmedFull;
+  } else if (uploadParam) {
+    cdnUrl = buildCdnUploadUrl({ cdnBaseUrl, uploadParam, filekey });
+  } else {
+    throw new Error(`${label}: CDN upload URL missing (need upload_full_url or upload_param)`);
+  }
+  logger.debug(`${label}: CDN POST url=${redactUrl(cdnUrl)} ciphertextSize=${ciphertext.length}`);
+
+  let downloadParam: string | undefined;
+  let lastError: unknown;
+
+  for (let attempt = 1; attempt <= UPLOAD_MAX_RETRIES; attempt++) {
+    try {
+      const res = await fetch(cdnUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/octet-stream" },
+        body: new Uint8Array(ciphertext),
+      });
+      if (res.status >= 400 && res.status < 500) {
+        const errMsg = res.headers.get("x-error-message") ?? (await res.text());
+        logger.error(
+          `${label}: CDN client error attempt=${attempt} status=${res.status} errMsg=${errMsg}`,
+        );
+        throw new Error(`CDN upload client error ${res.status}: ${errMsg}`);
+      }
+      if (res.status !== 200) {
+        const errMsg = res.headers.get("x-error-message") ?? `status ${res.status}`;
+        logger.error(
+          `${label}: CDN server error attempt=${attempt} status=${res.status} errMsg=${errMsg}`,
+        );
+        throw new Error(`CDN upload server error: ${errMsg}`);
+      }
+      downloadParam = res.headers.get("x-encrypted-param") ?? undefined;
+      if (!downloadParam) {
+        logger.error(
+          `${label}: CDN response missing x-encrypted-param header attempt=${attempt}`,
+        );
+        throw new Error("CDN upload response missing x-encrypted-param header");
+      }
+      logger.debug(`${label}: CDN upload success attempt=${attempt}`);
+      break;
+    } catch (err) {
+      lastError = err;
+      if (err instanceof Error && err.message.includes("client error")) throw err;
+      const cause =
+        (err as NodeJS.ErrnoException).cause ?? (err as NodeJS.ErrnoException).code ?? "";
+      if (attempt < UPLOAD_MAX_RETRIES) {
+        logger.error(
+          `${label}: attempt ${attempt} failed, retrying... url=${redactUrl(cdnUrl)} error=${String(err)}${cause ? ` cause=${cause}` : ""}`,
+        );
+      } else {
+        logger.error(
+          `${label}: all ${UPLOAD_MAX_RETRIES} attempts failed url=${redactUrl(cdnUrl)} error=${String(err)}${cause ? ` cause=${cause}` : ""}`,
+        );
+      }
+    }
+  }
+
+  if (!downloadParam) {
+    throw lastError instanceof Error
+      ? lastError
+      : new Error(`CDN upload failed after ${UPLOAD_MAX_RETRIES} attempts`);
+  }
+  return { downloadParam };
+}