@openclaw/zalo 2026.2.24 → 2026.3.1

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 2026.3.1
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.2.26
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.2.25
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
 ## 2026.2.24
 
 ### Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/zalo",
-  "version": "2026.2.24",
+  "version": "2026.3.1",
   "description": "OpenClaw Zalo channel plugin",
   "type": "module",
   "dependencies": {

package/src/accounts.ts

@@ -1,5 +1,9 @@
 import type { OpenClawConfig } from "openclaw/plugin-sdk";
-import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk/account-id";
+import {
+  DEFAULT_ACCOUNT_ID,
+  normalizeAccountId,
+  normalizeOptionalAccountId,
+} from "openclaw/plugin-sdk/account-id";
 import { resolveZaloToken } from "./token.js";
 import type { ResolvedZaloAccount, ZaloAccountConfig, ZaloConfig } from "./types.js";
 
@@ -23,8 +27,12 @@ export function listZaloAccountIds(cfg: OpenClawConfig): string[] {
 
 export function resolveDefaultZaloAccountId(cfg: OpenClawConfig): string {
   const zaloConfig = cfg.channels?.zalo as ZaloConfig | undefined;
-  if (zaloConfig?.defaultAccount?.trim()) {
-    return zaloConfig.defaultAccount.trim();
+  const preferred = normalizeOptionalAccountId(zaloConfig?.defaultAccount);
+  if (
+    preferred &&
+    listZaloAccountIds(cfg).some((accountId) => normalizeAccountId(accountId) === preferred)
+  ) {
+    return preferred;
   }
   const ids = listZaloAccountIds(cfg);
   if (ids.includes(DEFAULT_ACCOUNT_ID)) {

package/src/monitor.ts

@@ -1,6 +1,7 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { MarkdownTableMode, OpenClawConfig, OutboundReplyPayload } from "openclaw/plugin-sdk";
 import {
+  createScopedPairingAccess,
   createReplyPrefixOptions,
   resolveSenderCommandAuthorization,
   resolveOutboundMediaUrls,
@@ -27,6 +28,9 @@ import {
   resolveZaloRuntimeGroupPolicy,
 } from "./group-access.js";
 import {
+  clearZaloWebhookSecurityStateForTest,
+  getZaloWebhookRateLimitStateSizeForTest,
+  getZaloWebhookStatusCounterSizeForTest,
   handleZaloWebhookRequest as handleZaloWebhookRequestInternal,
   registerZaloWebhookTarget as registerZaloWebhookTargetInternal,
   type ZaloWebhookTarget,
@@ -72,6 +76,12 @@ export function registerZaloWebhookTarget(target: ZaloWebhookTarget): () => void
   return registerZaloWebhookTargetInternal(target);
 }
 
+export {
+  clearZaloWebhookSecurityStateForTest,
+  getZaloWebhookRateLimitStateSizeForTest,
+  getZaloWebhookStatusCounterSizeForTest,
+};
+
 export async function handleZaloWebhookRequest(
   req: IncomingMessage,
   res: ServerResponse,
@@ -142,7 +152,7 @@ function startPollingLoop(params: {
       if (err instanceof ZaloApiError && err.isPollingTimeout) {
         // no updates
       } else if (!isStopped() && !abortSignal.aborted) {
-        console.error(`[${account.accountId}] Zalo polling error:`, err);
+        runtime.error?.(`[${account.accountId}] Zalo polling error: ${String(err)}`);
         await new Promise((resolve) => setTimeout(resolve, 5000));
       }
     }
@@ -189,10 +199,12 @@ async function processUpdate(
       );
       break;
     case "message.sticker.received":
-      console.log(`[${account.accountId}] Received sticker from ${message.from.id}`);
+      logVerbose(core, runtime, `[${account.accountId}] Received sticker from ${message.from.id}`);
       break;
     case "message.unsupported.received":
-      console.log(
+      logVerbose(
+        core,
+        runtime,
         `[${account.accountId}] Received unsupported message type from ${message.from.id}`,
       );
       break;
@@ -258,7 +270,7 @@ async function handleImageMessage(
       mediaPath = saved.path;
       mediaType = saved.contentType;
     } catch (err) {
-      console.error(`[${account.accountId}] Failed to download Zalo image:`, err);
+      runtime.error?.(`[${account.accountId}] Failed to download Zalo image: ${String(err)}`);
     }
   }
 
@@ -303,6 +315,11 @@ async function processMessageWithPipeline(params: {
     statusSink,
     fetcher,
   } = params;
+  const pairing = createScopedPairingAccess({
+    core,
+    channel: "zalo",
+    accountId: account.accountId,
+  });
   const { from, chat, message_id, date } = message;
 
   const isGroup = chat.chat_type === "GROUP";
@@ -355,9 +372,10 @@ async function processMessageWithPipeline(params: {
     isGroup,
     dmPolicy,
     configuredAllowFrom: configAllowFrom,
+    configuredGroupAllowFrom: groupAllowFrom,
     senderId,
     isSenderAllowed: isZaloSenderAllowed,
-    readAllowFromStore: () => core.channel.pairing.readAllowFromStore("zalo"),
+    readAllowFromStore: pairing.readAllowFromStore,
     shouldComputeCommandAuthorized: (body, cfg) =>
       core.channel.commands.shouldComputeCommandAuthorized(body, cfg),
     resolveCommandAuthorizedFromAuthorizers: (params) =>
@@ -375,8 +393,7 @@ async function processMessageWithPipeline(params: {
 
       if (!allowed) {
         if (dmPolicy === "pairing") {
-          const { code, created } = await core.channel.pairing.upsertPairingRequest({
-            channel: "zalo",
+          const { code, created } = await pairing.upsertPairingRequest({
             id: senderId,
             meta: { name: senderName ?? undefined },
           });

package/src/monitor.webhook.test.ts

@@ -1,8 +1,14 @@
 import { createServer, type RequestListener } from "node:http";
 import type { AddressInfo } from "node:net";
 import type { OpenClawConfig, PluginRuntime } from "openclaw/plugin-sdk";
-import { describe, expect, it, vi } from "vitest";
-import { handleZaloWebhookRequest, registerZaloWebhookTarget } from "./monitor.js";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  clearZaloWebhookSecurityStateForTest,
+  getZaloWebhookRateLimitStateSizeForTest,
+  getZaloWebhookStatusCounterSizeForTest,
+  handleZaloWebhookRequest,
+  registerZaloWebhookTarget,
+} from "./monitor.js";
 import type { ResolvedZaloAccount } from "./types.js";
 
 async function withServer(handler: RequestListener, fn: (baseUrl: string) => Promise<void>) {
@@ -56,6 +62,10 @@ function registerTarget(params: {
 }
 
 describe("handleZaloWebhookRequest", () => {
+  afterEach(() => {
+    clearZaloWebhookSecurityStateForTest();
+  });
+
   it("returns 400 for non-object payloads", async () => {
     const unregister = registerTarget({ path: "/hook" });
 
@@ -196,4 +206,57 @@ describe("handleZaloWebhookRequest", () => {
       unregister();
     }
   });
+
+  it("does not grow status counters when query strings churn on unauthorized requests", async () => {
+    const unregister = registerTarget({ path: "/hook-query-status" });
+
+    try {
+      await withServer(webhookRequestHandler, async (baseUrl) => {
+        for (let i = 0; i < 200; i += 1) {
+          const response = await fetch(`${baseUrl}/hook-query-status?nonce=${i}`, {
+            method: "POST",
+            headers: {
+              "x-bot-api-secret-token": "invalid-token",
+              "content-type": "application/json",
+            },
+            body: "{}",
+          });
+          expect(response.status).toBe(401);
+        }
+
+        expect(getZaloWebhookStatusCounterSizeForTest()).toBe(1);
+      });
+    } finally {
+      unregister();
+    }
+  });
+
+  it("rate limits authenticated requests even when query strings churn", async () => {
+    const unregister = registerTarget({ path: "/hook-query-rate" });
+
+    try {
+      await withServer(webhookRequestHandler, async (baseUrl) => {
+        let saw429 = false;
+        for (let i = 0; i < 130; i += 1) {
+          const response = await fetch(`${baseUrl}/hook-query-rate?nonce=${i}`, {
+            method: "POST",
+            headers: {
+              "x-bot-api-secret-token": "secret",
+              "content-type": "application/json",
+            },
+            body: "{}",
+          });
+          if (response.status === 429) {
+            saw429 = true;
+            break;
+          }
+        }
+
+        expect(saw429).toBe(true);
+        expect(getZaloWebhookRateLimitStateSizeForTest()).toBe(1);
+      });
+    } finally {
+      unregister();
+    }
+  });
 });

package/src/monitor.webhook.ts

@@ -3,23 +3,21 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import type { OpenClawConfig } from "openclaw/plugin-sdk";
 import {
   createDedupeCache,
-  readJsonBodyWithLimit,
+  createFixedWindowRateLimiter,
+  createWebhookAnomalyTracker,
+  readJsonWebhookBodyOrReject,
+  applyBasicWebhookRequestGuards,
   registerWebhookTarget,
-  rejectNonPostWebhookRequest,
-  requestBodyErrorToText,
   resolveSingleWebhookTarget,
   resolveWebhookTargets,
+  WEBHOOK_ANOMALY_COUNTER_DEFAULTS,
+  WEBHOOK_RATE_LIMIT_DEFAULTS,
 } from "openclaw/plugin-sdk";
 import type { ResolvedZaloAccount } from "./accounts.js";
 import type { ZaloFetch, ZaloUpdate } from "./api.js";
 import type { ZaloRuntimeEnv } from "./monitor.js";
 
-type WebhookRateLimitState = { count: number; windowStartMs: number };
-
-const ZALO_WEBHOOK_RATE_LIMIT_WINDOW_MS = 60_000;
-const ZALO_WEBHOOK_RATE_LIMIT_MAX_REQUESTS = 120;
 const ZALO_WEBHOOK_REPLAY_WINDOW_MS = 5 * 60_000;
-const ZALO_WEBHOOK_COUNTER_LOG_EVERY = 25;
 
 export type ZaloWebhookTarget = {
   token: string;
@@ -40,20 +38,32 @@ export type ZaloWebhookProcessUpdate = (params: {
 }) => Promise<void>;
 
 const webhookTargets = new Map<string, ZaloWebhookTarget[]>();
-const webhookRateLimits = new Map<string, WebhookRateLimitState>();
+const webhookRateLimiter = createFixedWindowRateLimiter({
+  windowMs: WEBHOOK_RATE_LIMIT_DEFAULTS.windowMs,
+  maxRequests: WEBHOOK_RATE_LIMIT_DEFAULTS.maxRequests,
+  maxTrackedKeys: WEBHOOK_RATE_LIMIT_DEFAULTS.maxTrackedKeys,
+});
 const recentWebhookEvents = createDedupeCache({
   ttlMs: ZALO_WEBHOOK_REPLAY_WINDOW_MS,
   maxSize: 5000,
 });
-const webhookStatusCounters = new Map<string, number>();
+const webhookAnomalyTracker = createWebhookAnomalyTracker({
+  maxTrackedKeys: WEBHOOK_ANOMALY_COUNTER_DEFAULTS.maxTrackedKeys,
+  ttlMs: WEBHOOK_ANOMALY_COUNTER_DEFAULTS.ttlMs,
+  logEvery: WEBHOOK_ANOMALY_COUNTER_DEFAULTS.logEvery,
+});
 
-function isJsonContentType(value: string | string[] | undefined): boolean {
-  const first = Array.isArray(value) ? value[0] : value;
-  if (!first) {
-    return false;
-  }
-  const mediaType = first.split(";", 1)[0]?.trim().toLowerCase();
-  return mediaType === "application/json" || Boolean(mediaType?.endsWith("+json"));
+export function clearZaloWebhookSecurityStateForTest(): void {
+  webhookRateLimiter.clear();
+  webhookAnomalyTracker.clear();
+}
+
+export function getZaloWebhookRateLimitStateSizeForTest(): number {
+  return webhookRateLimiter.size();
+}
+
+export function getZaloWebhookStatusCounterSizeForTest(): number {
+  return webhookAnomalyTracker.size();
 }
 
 function timingSafeEquals(left: string, right: string): boolean {
@@ -73,20 +83,6 @@ function timingSafeEquals(left: string, right: string): boolean {
   return timingSafeEqual(leftBuffer, rightBuffer);
 }
 
-function isWebhookRateLimited(key: string, nowMs: number): boolean {
-  const state = webhookRateLimits.get(key);
-  if (!state || nowMs - state.windowStartMs >= ZALO_WEBHOOK_RATE_LIMIT_WINDOW_MS) {
-    webhookRateLimits.set(key, { count: 1, windowStartMs: nowMs });
-    return false;
-  }
-
-  state.count += 1;
-  if (state.count > ZALO_WEBHOOK_RATE_LIMIT_MAX_REQUESTS) {
-    return true;
-  }
-  return false;
-}
-
 function isReplayEvent(update: ZaloUpdate, nowMs: number): boolean {
   const messageId = update.message?.message_id;
   if (!messageId) {
@@ -101,17 +97,13 @@ function recordWebhookStatus(
   path: string,
   statusCode: number,
 ): void {
-  if (![400, 401, 408, 413, 415, 429].includes(statusCode)) {
-    return;
-  }
-  const key = `${path}:${statusCode}`;
-  const next = (webhookStatusCounters.get(key) ?? 0) + 1;
-  webhookStatusCounters.set(key, next);
-  if (next === 1 || next % ZALO_WEBHOOK_COUNTER_LOG_EVERY === 0) {
-    runtime?.log?.(
-      `[zalo] webhook anomaly path=${path} status=${statusCode} count=${String(next)}`,
-    );
-  }
+  webhookAnomalyTracker.record({
+    key: `${path}:${statusCode}`,
+    statusCode,
+    log: runtime?.log,
+    message: (count) =>
+      `[zalo] webhook anomaly path=${path} status=${statusCode} count=${String(count)}`,
+  });
 }
 
 export function registerZaloWebhookTarget(target: ZaloWebhookTarget): () => void {
@@ -127,9 +119,15 @@ export async function handleZaloWebhookRequest(
   if (!resolved) {
     return false;
   }
-  const { targets } = resolved;
+  const { targets, path } = resolved;
 
-  if (rejectNonPostWebhookRequest(req, res)) {
+  if (
+    !applyBasicWebhookRequestGuards({
+      req,
+      res,
+      allowMethods: ["POST"],
+    })
+  ) {
     return true;
   }
 
@@ -140,55 +138,47 @@ export async function handleZaloWebhookRequest(
   if (matchedTarget.kind === "none") {
     res.statusCode = 401;
     res.end("unauthorized");
-    recordWebhookStatus(targets[0]?.runtime, req.url ?? "<unknown>", res.statusCode);
+    recordWebhookStatus(targets[0]?.runtime, path, res.statusCode);
     return true;
   }
   if (matchedTarget.kind === "ambiguous") {
     res.statusCode = 401;
     res.end("ambiguous webhook target");
-    recordWebhookStatus(targets[0]?.runtime, req.url ?? "<unknown>", res.statusCode);
+    recordWebhookStatus(targets[0]?.runtime, path, res.statusCode);
     return true;
   }
   const target = matchedTarget.target;
-  const path = req.url ?? "<unknown>";
   const rateLimitKey = `${path}:${req.socket.remoteAddress ?? "unknown"}`;
   const nowMs = Date.now();
 
-  if (isWebhookRateLimited(rateLimitKey, nowMs)) {
-    res.statusCode = 429;
-    res.end("Too Many Requests");
+  if (
+    !applyBasicWebhookRequestGuards({
+      req,
+      res,
+      rateLimiter: webhookRateLimiter,
+      rateLimitKey,
+      nowMs,
+      requireJsonContentType: true,
+    })
+  ) {
     recordWebhookStatus(target.runtime, path, res.statusCode);
     return true;
   }
-
-  if (!isJsonContentType(req.headers["content-type"])) {
-    res.statusCode = 415;
-    res.end("Unsupported Media Type");
-    recordWebhookStatus(target.runtime, path, res.statusCode);
-    return true;
-  }
-
-  const body = await readJsonBodyWithLimit(req, {
+  const body = await readJsonWebhookBodyOrReject({
+    req,
+    res,
     maxBytes: 1024 * 1024,
     timeoutMs: 30_000,
     emptyObjectOnEmpty: false,
+    invalidJsonMessage: "Bad Request",
   });
   if (!body.ok) {
-    res.statusCode =
-      body.code === "PAYLOAD_TOO_LARGE" ? 413 : body.code === "REQUEST_BODY_TIMEOUT" ? 408 : 400;
-    const message =
-      body.code === "PAYLOAD_TOO_LARGE"
-        ? requestBodyErrorToText("PAYLOAD_TOO_LARGE")
-        : body.code === "REQUEST_BODY_TIMEOUT"
-          ? requestBodyErrorToText("REQUEST_BODY_TIMEOUT")
-          : "Bad Request";
-    res.end(message);
     recordWebhookStatus(target.runtime, path, res.statusCode);
     return true;
   }
+  const raw = body.value;
 
   // Zalo sends updates directly as { event_name, message, ... }, not wrapped in { ok, result }.
-  const raw = body.value;
   const record = raw && typeof raw === "object" ? (raw as Record<string, unknown>) : null;
   const update: ZaloUpdate | undefined =
     record && record.ok === true && record.result