@openclaw/zalo 2026.3.11 → 2026.3.13

package/CHANGELOG.md

@@ -1,8 +1,21 @@
 # Changelog
 
+## 2026.3.13
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.3.12
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
 ## 2026.3.11
 
 ### Changes
+
 - Version alignment with core OpenClaw release numbers.
 
 ## 2026.3.10

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@openclaw/zalo",
-  "version": "2026.3.11",
+  "version": "2026.3.13",
   "description": "OpenClaw Zalo channel plugin",
   "type": "module",
   "dependencies": {
-    "undici": "7.22.0",
+    "undici": "7.24.1",
     "zod": "^4.3.6"
   },
   "openclaw": {

package/src/api.test.ts

@@ -1,31 +1,26 @@
 import { describe, expect, it, vi } from "vitest";
 import { deleteWebhook, getWebhookInfo, sendChatAction, type ZaloFetch } from "./api.js";
 
+function createOkFetcher() {
+  return vi.fn<ZaloFetch>(async () => new Response(JSON.stringify({ ok: true, result: {} })));
+}
+
+async function expectPostJsonRequest(run: (token: string, fetcher: ZaloFetch) => Promise<unknown>) {
+  const fetcher = createOkFetcher();
+  await run("test-token", fetcher);
+  expect(fetcher).toHaveBeenCalledTimes(1);
+  const [, init] = fetcher.mock.calls[0] ?? [];
+  expect(init?.method).toBe("POST");
+  expect(init?.headers).toEqual({ "Content-Type": "application/json" });
+}
+
 describe("Zalo API request methods", () => {
   it("uses POST for getWebhookInfo", async () => {
-    const fetcher = vi.fn<ZaloFetch>(
-      async () => new Response(JSON.stringify({ ok: true, result: {} })),
-    );
-
-    await getWebhookInfo("test-token", fetcher);
-
-    expect(fetcher).toHaveBeenCalledTimes(1);
-    const [, init] = fetcher.mock.calls[0] ?? [];
-    expect(init?.method).toBe("POST");
-    expect(init?.headers).toEqual({ "Content-Type": "application/json" });
+    await expectPostJsonRequest(getWebhookInfo);
   });
 
   it("keeps POST for deleteWebhook", async () => {
-    const fetcher = vi.fn<ZaloFetch>(
-      async () => new Response(JSON.stringify({ ok: true, result: {} })),
-    );
-
-    await deleteWebhook("test-token", fetcher);
-
-    expect(fetcher).toHaveBeenCalledTimes(1);
-    const [, init] = fetcher.mock.calls[0] ?? [];
-    expect(init?.method).toBe("POST");
-    expect(init?.headers).toEqual({ "Content-Type": "application/json" });
+    await expectPostJsonRequest(deleteWebhook);
   });
 
   it("aborts sendChatAction when the typing timeout elapses", async () => {

package/src/channel.directory.test.ts

@@ -1,15 +1,10 @@
 import type { OpenClawConfig, RuntimeEnv } from "openclaw/plugin-sdk/zalo";
 import { describe, expect, it } from "vitest";
+import { createDirectoryTestRuntime, expectDirectorySurface } from "../../test-utils/directory.js";
 import { zaloPlugin } from "./channel.js";
 
 describe("zalo directory", () => {
-  const runtimeEnv: RuntimeEnv = {
-    log: () => {},
-    error: () => {},
-    exit: (code: number): never => {
-      throw new Error(`exit ${code}`);
-    },
-  };
+  const runtimeEnv = createDirectoryTestRuntime() as RuntimeEnv;
 
   it("lists peers from allowFrom", async () => {
     const cfg = {
@@ -20,12 +15,10 @@ describe("zalo directory", () => {
       },
     } as unknown as OpenClawConfig;
 
-    expect(zaloPlugin.directory).toBeTruthy();
-    expect(zaloPlugin.directory?.listPeers).toBeTruthy();
-    expect(zaloPlugin.directory?.listGroups).toBeTruthy();
+    const directory = expectDirectorySurface(zaloPlugin.directory);
 
     await expect(
-      zaloPlugin.directory!.listPeers!({
+      directory.listPeers({
         cfg,
         accountId: undefined,
         query: undefined,
@@ -41,7 +34,7 @@ describe("zalo directory", () => {
     );
 
     await expect(
-      zaloPlugin.directory!.listGroups!({
+      directory.listGroups({
         cfg,
         accountId: undefined,
         query: undefined,

package/src/channel.startup.test.ts

@@ -1,6 +1,9 @@
 import type { ChannelAccountSnapshot } from "openclaw/plugin-sdk/zalo";
 import { afterEach, describe, expect, it, vi } from "vitest";
-import { createStartAccountContext } from "../../test-utils/start-account-context.js";
+import {
+  expectPendingUntilAbort,
+  startAccountAndTrackLifecycle,
+} from "../../test-utils/start-account-lifecycle.js";
 import type { ResolvedZaloAccount } from "./accounts.js";
 
 const hoisted = vi.hoisted(() => ({
@@ -57,37 +60,28 @@ describe("zaloPlugin gateway.startAccount", () => {
         }),
     );
 
-    const patches: ChannelAccountSnapshot[] = [];
-    const abort = new AbortController();
-    const task = zaloPlugin.gateway!.startAccount!(
-      createStartAccountContext({
-        account: buildAccount(),
-        abortSignal: abort.signal,
-        statusPatchSink: (next) => patches.push({ ...next }),
-      }),
-    );
-
-    let settled = false;
-    void task.then(() => {
-      settled = true;
+    const { abort, patches, task, isSettled } = startAccountAndTrackLifecycle({
+      startAccount: zaloPlugin.gateway!.startAccount!,
+      account: buildAccount(),
     });
 
-    await vi.waitFor(() => {
-      expect(hoisted.probeZalo).toHaveBeenCalledOnce();
-      expect(hoisted.monitorZaloProvider).toHaveBeenCalledOnce();
+    await expectPendingUntilAbort({
+      waitForStarted: () =>
+        vi.waitFor(() => {
+          expect(hoisted.probeZalo).toHaveBeenCalledOnce();
+          expect(hoisted.monitorZaloProvider).toHaveBeenCalledOnce();
+        }),
+      isSettled,
+      abort,
+      task,
     });
 
-    expect(settled).toBe(false);
     expect(patches).toContainEqual(
       expect.objectContaining({
         accountId: "default",
       }),
     );
-
-    abort.abort();
-    await task;
-
-    expect(settled).toBe(true);
+    expect(isSettled()).toBe(true);
     expect(hoisted.monitorZaloProvider).toHaveBeenCalledWith(
       expect.objectContaining({
         token: "test-token",

package/src/monitor.lifecycle.test.ts

@@ -32,6 +32,41 @@ async function waitForPollingLoopStart(): Promise<void> {
   await vi.waitFor(() => expect(getUpdatesMock).toHaveBeenCalledTimes(1));
 }
 
+const TEST_ACCOUNT = {
+  accountId: "default",
+  config: {},
+} as unknown as ResolvedZaloAccount;
+
+const TEST_CONFIG = {} as OpenClawConfig;
+
+function createLifecycleRuntime() {
+  return {
+    log: vi.fn<(message: string) => void>(),
+    error: vi.fn<(message: string) => void>(),
+  };
+}
+
+async function startLifecycleMonitor(
+  options: {
+    useWebhook?: boolean;
+    webhookSecret?: string;
+    webhookUrl?: string;
+  } = {},
+) {
+  const { monitorZaloProvider } = await import("./monitor.js");
+  const abort = new AbortController();
+  const runtime = createLifecycleRuntime();
+  const run = monitorZaloProvider({
+    token: "test-token",
+    account: TEST_ACCOUNT,
+    config: TEST_CONFIG,
+    runtime,
+    abortSignal: abort.signal,
+    ...options,
+  });
+  return { abort, runtime, run };
+}
+
 describe("monitorZaloProvider lifecycle", () => {
   afterEach(() => {
     vi.clearAllMocks();
@@ -39,26 +74,9 @@ describe("monitorZaloProvider lifecycle", () => {
   });
 
   it("stays alive in polling mode until abort", async () => {
-    const { monitorZaloProvider } = await import("./monitor.js");
-    const abort = new AbortController();
-    const runtime = {
-      log: vi.fn<(message: string) => void>(),
-      error: vi.fn<(message: string) => void>(),
-    };
-    const account = {
-      accountId: "default",
-      config: {},
-    } as unknown as ResolvedZaloAccount;
-    const config = {} as OpenClawConfig;
-
     let settled = false;
-    const run = monitorZaloProvider({
-      token: "test-token",
-      account,
-      config,
-      runtime,
-      abortSignal: abort.signal,
-    }).then(() => {
+    const { abort, runtime, run } = await startLifecycleMonitor();
+    const monitoredRun = run.then(() => {
       settled = true;
     });
 
@@ -70,7 +88,7 @@ describe("monitorZaloProvider lifecycle", () => {
     expect(settled).toBe(false);
 
     abort.abort();
-    await run;
+    await monitoredRun;
 
     expect(settled).toBe(true);
     expect(runtime.log).toHaveBeenCalledWith(
@@ -84,25 +102,7 @@ describe("monitorZaloProvider lifecycle", () => {
       result: { url: "https://example.com/hooks/zalo" },
     });
 
-    const { monitorZaloProvider } = await import("./monitor.js");
-    const abort = new AbortController();
-    const runtime = {
-      log: vi.fn<(message: string) => void>(),
-      error: vi.fn<(message: string) => void>(),
-    };
-    const account = {
-      accountId: "default",
-      config: {},
-    } as unknown as ResolvedZaloAccount;
-    const config = {} as OpenClawConfig;
-
-    const run = monitorZaloProvider({
-      token: "test-token",
-      account,
-      config,
-      runtime,
-      abortSignal: abort.signal,
-    });
+    const { abort, runtime, run } = await startLifecycleMonitor();
 
     await waitForPollingLoopStart();
 
@@ -120,25 +120,7 @@ describe("monitorZaloProvider lifecycle", () => {
     const { ZaloApiError } = await import("./api.js");
     getWebhookInfoMock.mockRejectedValueOnce(new ZaloApiError("Not Found", 404, "Not Found"));
 
-    const { monitorZaloProvider } = await import("./monitor.js");
-    const abort = new AbortController();
-    const runtime = {
-      log: vi.fn<(message: string) => void>(),
-      error: vi.fn<(message: string) => void>(),
-    };
-    const account = {
-      accountId: "default",
-      config: {},
-    } as unknown as ResolvedZaloAccount;
-    const config = {} as OpenClawConfig;
-
-    const run = monitorZaloProvider({
-      token: "test-token",
-      account,
-      config,
-      runtime,
-      abortSignal: abort.signal,
-    });
+    const { abort, runtime, run } = await startLifecycleMonitor();
 
     await waitForPollingLoopStart();
 
@@ -165,29 +147,13 @@ describe("monitorZaloProvider lifecycle", () => {
         }),
     );
 
-    const { monitorZaloProvider } = await import("./monitor.js");
-    const abort = new AbortController();
-    const runtime = {
-      log: vi.fn<(message: string) => void>(),
-      error: vi.fn<(message: string) => void>(),
-    };
-    const account = {
-      accountId: "default",
-      config: {},
-    } as unknown as ResolvedZaloAccount;
-    const config = {} as OpenClawConfig;
-
     let settled = false;
-    const run = monitorZaloProvider({
-      token: "test-token",
-      account,
-      config,
-      runtime,
-      abortSignal: abort.signal,
+    const { abort, runtime, run } = await startLifecycleMonitor({
       useWebhook: true,
       webhookUrl: "https://example.com/hooks/zalo",
       webhookSecret: "supersecret", // pragma: allowlist secret
-    }).then(() => {
+    });
+    const monitoredRun = run.then(() => {
       settled = true;
     });
 
@@ -202,7 +168,7 @@ describe("monitorZaloProvider lifecycle", () => {
     expect(registry.httpRoutes).toHaveLength(1);
 
     resolveDeleteWebhook?.();
-    await run;
+    await monitoredRun;
 
     expect(settled).toBe(true);
     expect(registry.httpRoutes).toHaveLength(0);

package/src/monitor.ts

@@ -75,6 +75,35 @@ const WEBHOOK_CLEANUP_TIMEOUT_MS = 5_000;
 const ZALO_TYPING_TIMEOUT_MS = 5_000;
 
 type ZaloCoreRuntime = ReturnType<typeof getZaloRuntime>;
+type ZaloStatusSink = (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
+type ZaloProcessingContext = {
+  token: string;
+  account: ResolvedZaloAccount;
+  config: OpenClawConfig;
+  runtime: ZaloRuntimeEnv;
+  core: ZaloCoreRuntime;
+  statusSink?: ZaloStatusSink;
+  fetcher?: ZaloFetch;
+};
+type ZaloPollingLoopParams = ZaloProcessingContext & {
+  abortSignal: AbortSignal;
+  isStopped: () => boolean;
+  mediaMaxMb: number;
+};
+type ZaloUpdateProcessingParams = ZaloProcessingContext & {
+  update: ZaloUpdate;
+  mediaMaxMb: number;
+};
+type ZaloMessagePipelineParams = ZaloProcessingContext & {
+  message: ZaloMessage;
+  text?: string;
+  mediaPath?: string;
+  mediaType?: string;
+};
+type ZaloImageMessageParams = ZaloProcessingContext & {
+  message: ZaloMessage;
+  mediaMaxMb: number;
+};
 
 function formatZaloError(error: unknown): string {
   if (error instanceof Error) {
@@ -135,32 +164,21 @@ export async function handleZaloWebhookRequest(
   res: ServerResponse,
 ): Promise<boolean> {
   return handleZaloWebhookRequestInternal(req, res, async ({ update, target }) => {
-    await processUpdate(
+    await processUpdate({
       update,
-      target.token,
-      target.account,
-      target.config,
-      target.runtime,
-      target.core as ZaloCoreRuntime,
-      target.mediaMaxMb,
-      target.statusSink,
-      target.fetcher,
-    );
+      token: target.token,
+      account: target.account,
+      config: target.config,
+      runtime: target.runtime,
+      core: target.core as ZaloCoreRuntime,
+      mediaMaxMb: target.mediaMaxMb,
+      statusSink: target.statusSink,
+      fetcher: target.fetcher,
+    });
   });
 }
 
-function startPollingLoop(params: {
-  token: string;
-  account: ResolvedZaloAccount;
-  config: OpenClawConfig;
-  runtime: ZaloRuntimeEnv;
-  core: ZaloCoreRuntime;
-  abortSignal: AbortSignal;
-  isStopped: () => boolean;
-  mediaMaxMb: number;
-  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
-  fetcher?: ZaloFetch;
-}) {
+function startPollingLoop(params: ZaloPollingLoopParams) {
   const {
     token,
     account,
@@ -174,6 +192,16 @@ function startPollingLoop(params: {
     fetcher,
   } = params;
   const pollTimeout = 30;
+  const processingContext = {
+    token,
+    account,
+    config,
+    runtime,
+    core,
+    mediaMaxMb,
+    statusSink,
+    fetcher,
+  };
 
   runtime.log?.(`[${account.accountId}] Zalo polling loop started timeout=${String(pollTimeout)}s`);
 
@@ -186,17 +214,10 @@ function startPollingLoop(params: {
       const response = await getUpdates(token, { timeout: pollTimeout }, fetcher);
       if (response.ok && response.result) {
         statusSink?.({ lastInboundAt: Date.now() });
-        await processUpdate(
-          response.result,
-          token,
-          account,
-          config,
-          runtime,
-          core,
-          mediaMaxMb,
-          statusSink,
-          fetcher,
-        );
+        await processUpdate({
+          update: response.result,
+          ...processingContext,
+        });
       }
     } catch (err) {
       if (err instanceof ZaloApiError && err.isPollingTimeout) {
@@ -215,38 +236,27 @@ function startPollingLoop(params: {
   void poll();
 }
 
-async function processUpdate(
-  update: ZaloUpdate,
-  token: string,
-  account: ResolvedZaloAccount,
-  config: OpenClawConfig,
-  runtime: ZaloRuntimeEnv,
-  core: ZaloCoreRuntime,
-  mediaMaxMb: number,
-  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void,
-  fetcher?: ZaloFetch,
-): Promise<void> {
+async function processUpdate(params: ZaloUpdateProcessingParams): Promise<void> {
+  const { update, token, account, config, runtime, core, mediaMaxMb, statusSink, fetcher } = params;
   const { event_name, message } = update;
+  const sharedContext = { token, account, config, runtime, core, statusSink, fetcher };
   if (!message) {
     return;
   }
 
   switch (event_name) {
     case "message.text.received":
-      await handleTextMessage(message, token, account, config, runtime, core, statusSink, fetcher);
+      await handleTextMessage({
+        message,
+        ...sharedContext,
+      });
       break;
     case "message.image.received":
-      await handleImageMessage(
+      await handleImageMessage({
         message,
-        token,
-        account,
-        config,
-        runtime,
-        core,
+        ...sharedContext,
         mediaMaxMb,
-        statusSink,
-        fetcher,
-      );
+      });
       break;
     case "message.sticker.received":
       logVerbose(core, runtime, `[${account.accountId}] Received sticker from ${message.from.id}`);
@@ -262,46 +272,24 @@ async function processUpdate(
 }
 
 async function handleTextMessage(
-  message: ZaloMessage,
-  token: string,
-  account: ResolvedZaloAccount,
-  config: OpenClawConfig,
-  runtime: ZaloRuntimeEnv,
-  core: ZaloCoreRuntime,
-  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void,
-  fetcher?: ZaloFetch,
+  params: ZaloProcessingContext & { message: ZaloMessage },
 ): Promise<void> {
+  const { message } = params;
   const { text } = message;
   if (!text?.trim()) {
     return;
   }
 
   await processMessageWithPipeline({
-    message,
-    token,
-    account,
-    config,
-    runtime,
-    core,
+    ...params,
     text,
     mediaPath: undefined,
     mediaType: undefined,
-    statusSink,
-    fetcher,
   });
 }
 
-async function handleImageMessage(
-  message: ZaloMessage,
-  token: string,
-  account: ResolvedZaloAccount,
-  config: OpenClawConfig,
-  runtime: ZaloRuntimeEnv,
-  core: ZaloCoreRuntime,
-  mediaMaxMb: number,
-  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void,
-  fetcher?: ZaloFetch,
-): Promise<void> {
+async function handleImageMessage(params: ZaloImageMessageParams): Promise<void> {
+  const { message, mediaMaxMb, account, core, runtime } = params;
   const { photo, caption } = message;
 
   let mediaPath: string | undefined;
@@ -325,33 +313,14 @@ async function handleImageMessage(
   }
 
   await processMessageWithPipeline({
-    message,
-    token,
-    account,
-    config,
-    runtime,
-    core,
+    ...params,
     text: caption,
     mediaPath,
     mediaType,
-    statusSink,
-    fetcher,
   });
 }
 
-async function processMessageWithPipeline(params: {
-  message: ZaloMessage;
-  token: string;
-  account: ResolvedZaloAccount;
-  config: OpenClawConfig;
-  runtime: ZaloRuntimeEnv;
-  core: ZaloCoreRuntime;
-  text?: string;
-  mediaPath?: string;
-  mediaType?: string;
-  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
-  fetcher?: ZaloFetch;
-}): Promise<void> {
+async function processMessageWithPipeline(params: ZaloMessagePipelineParams): Promise<void> {
   const {
     message,
     token,
@@ -609,7 +578,7 @@ async function deliverZaloReply(params: {
   core: ZaloCoreRuntime;
   config: OpenClawConfig;
   accountId?: string;
-  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
+  statusSink?: ZaloStatusSink;
   fetcher?: ZaloFetch;
   tableMode?: MarkdownTableMode;
 }): Promise<void> {

package/src/monitor.webhook.test.ts

@@ -283,6 +283,7 @@ describe("handleZaloWebhookRequest", () => {
 
     try {
       await withServer(webhookRequestHandler, async (baseUrl) => {
+        let saw429 = false;
         for (let i = 0; i < 200; i += 1) {
           const response = await fetch(`${baseUrl}/hook-query-status?nonce=${i}`, {
             method: "POST",
@@ -292,10 +293,15 @@ describe("handleZaloWebhookRequest", () => {
             },
             body: "{}",
           });
-          expect(response.status).toBe(401);
+          expect([401, 429]).toContain(response.status);
+          if (response.status === 429) {
+            saw429 = true;
+            break;
+          }
         }
 
-        expect(getZaloWebhookStatusCounterSizeForTest()).toBe(1);
+        expect(saw429).toBe(true);
+        expect(getZaloWebhookStatusCounterSizeForTest()).toBe(2);
       });
     } finally {
       unregister();
@@ -322,6 +328,91 @@ describe("handleZaloWebhookRequest", () => {
     }
   });
 
+  it("rate limits unauthorized secret guesses before authentication succeeds", async () => {
+    const unregister = registerTarget({ path: "/hook-preauth-rate" });
+
+    try {
+      await withServer(webhookRequestHandler, async (baseUrl) => {
+        const saw429 = await postUntilRateLimited({
+          baseUrl,
+          path: "/hook-preauth-rate",
+          secret: "invalid-token", // pragma: allowlist secret
+          withNonceQuery: true,
+        });
+
+        expect(saw429).toBe(true);
+        expect(getZaloWebhookRateLimitStateSizeForTest()).toBe(1);
+      });
+    } finally {
+      unregister();
+    }
+  });
+
+  it("does not let unauthorized floods rate-limit authenticated traffic from a different trusted forwarded client IP", async () => {
+    const unregister = registerTarget({
+      path: "/hook-preauth-split",
+      config: {
+        gateway: {
+          trustedProxies: ["127.0.0.1"],
+        },
+      } as OpenClawConfig,
+    });
+
+    try {
+      await withServer(webhookRequestHandler, async (baseUrl) => {
+        for (let i = 0; i < 130; i += 1) {
+          const response = await fetch(`${baseUrl}/hook-preauth-split?nonce=${i}`, {
+            method: "POST",
+            headers: {
+              "x-bot-api-secret-token": "invalid-token", // pragma: allowlist secret
+              "content-type": "application/json",
+              "x-forwarded-for": "203.0.113.10",
+            },
+            body: "{}",
+          });
+          if (response.status === 429) {
+            break;
+          }
+        }
+
+        const validResponse = await fetch(`${baseUrl}/hook-preauth-split`, {
+          method: "POST",
+          headers: {
+            "x-bot-api-secret-token": "secret",
+            "content-type": "application/json",
+            "x-forwarded-for": "198.51.100.20",
+          },
+          body: JSON.stringify({ event_name: "message.unsupported.received" }),
+        });
+
+        expect(validResponse.status).toBe(200);
+      });
+    } finally {
+      unregister();
+    }
+  });
+
+  it("still returns 401 before 415 when both secret and content-type are invalid", async () => {
+    const unregister = registerTarget({ path: "/hook-auth-before-type" });
+
+    try {
+      await withServer(webhookRequestHandler, async (baseUrl) => {
+        const response = await fetch(`${baseUrl}/hook-auth-before-type`, {
+          method: "POST",
+          headers: {
+            "x-bot-api-secret-token": "invalid-token", // pragma: allowlist secret
+            "content-type": "text/plain",
+          },
+          body: "not-json",
+        });
+
+        expect(response.status).toBe(401);
+      });
+    } finally {
+      unregister();
+    }
+  });
+
   it("scopes DM pairing store reads and writes to accountId", async () => {
     const { core, readAllowFromStore, upsertPairingRequest } = createPairingAuthCore({
       pairingCreated: false,

package/src/monitor.webhook.ts

@@ -16,6 +16,7 @@ import {
   WEBHOOK_ANOMALY_COUNTER_DEFAULTS,
   WEBHOOK_RATE_LIMIT_DEFAULTS,
 } from "openclaw/plugin-sdk/zalo";
+import { resolveClientIp } from "../../../src/gateway/net.js";
 import type { ResolvedZaloAccount } from "./accounts.js";
 import type { ZaloFetch, ZaloUpdate } from "./api.js";
 import type { ZaloRuntimeEnv } from "./monitor.js";
@@ -109,6 +110,10 @@ function recordWebhookStatus(
   });
 }
 
+function headerValue(value: string | string[] | undefined): string | undefined {
+  return Array.isArray(value) ? value[0] : value;
+}
+
 export function registerZaloWebhookTarget(
   target: ZaloWebhookTarget,
   opts?: {
@@ -140,6 +145,33 @@ export async function handleZaloWebhookRequest(
     targetsByPath: webhookTargets,
     allowMethods: ["POST"],
     handle: async ({ targets, path }) => {
+      const trustedProxies = targets[0]?.config.gateway?.trustedProxies;
+      const allowRealIpFallback = targets[0]?.config.gateway?.allowRealIpFallback === true;
+      const clientIp =
+        resolveClientIp({
+          remoteAddr: req.socket.remoteAddress,
+          forwardedFor: headerValue(req.headers["x-forwarded-for"]),
+          realIp: headerValue(req.headers["x-real-ip"]),
+          trustedProxies,
+          allowRealIpFallback,
+        }) ??
+        req.socket.remoteAddress ??
+        "unknown";
+      const rateLimitKey = `${path}:${clientIp}`;
+      const nowMs = Date.now();
+      if (
+        !applyBasicWebhookRequestGuards({
+          req,
+          res,
+          rateLimiter: webhookRateLimiter,
+          rateLimitKey,
+          nowMs,
+        })
+      ) {
+        recordWebhookStatus(targets[0]?.runtime, path, res.statusCode);
+        return true;
+      }
+
       const headerToken = String(req.headers["x-bot-api-secret-token"] ?? "");
       const target = resolveWebhookTargetWithAuthOrRejectSync({
         targets,
@@ -150,16 +182,12 @@ export async function handleZaloWebhookRequest(
         recordWebhookStatus(targets[0]?.runtime, path, res.statusCode);
         return true;
       }
-      const rateLimitKey = `${path}:${req.socket.remoteAddress ?? "unknown"}`;
-      const nowMs = Date.now();
-
+      // Preserve the historical 401-before-415 ordering for invalid secrets while still
+      // consuming rate-limit budget on unauthenticated guesses.
       if (
         !applyBasicWebhookRequestGuards({
           req,
           res,
-          rateLimiter: webhookRateLimiter,
-          rateLimitKey,
-          nowMs,
           requireJsonContentType: true,
         })
       ) {

package/src/send.ts

@@ -21,6 +21,28 @@ export type ZaloSendResult = {
   error?: string;
 };
 
+function toZaloSendResult(response: {
+  ok?: boolean;
+  result?: { message_id?: string };
+}): ZaloSendResult {
+  if (response.ok && response.result) {
+    return { ok: true, messageId: response.result.message_id };
+  }
+  return { ok: false, error: "Failed to send message" };
+}
+
+async function runZaloSend(
+  failureMessage: string,
+  send: () => Promise<{ ok?: boolean; result?: { message_id?: string } }>,
+): Promise<ZaloSendResult> {
+  try {
+    const result = toZaloSendResult(await send());
+    return result.ok ? result : { ok: false, error: failureMessage };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
 function resolveSendContext(options: ZaloSendOptions): {
   token: string;
   fetcher?: ZaloFetch;
@@ -55,15 +77,30 @@ function resolveValidatedSendContext(
   return { ok: true, chatId: trimmedChatId, token, fetcher };
 }
 
+function resolveSendContextOrFailure(
+  chatId: string,
+  options: ZaloSendOptions,
+):
+  | { context: { chatId: string; token: string; fetcher?: ZaloFetch } }
+  | { failure: ZaloSendResult } {
+  const context = resolveValidatedSendContext(chatId, options);
+  return context.ok
+    ? { context }
+    : {
+        failure: { ok: false, error: context.error },
+      };
+}
+
 export async function sendMessageZalo(
   chatId: string,
   text: string,
   options: ZaloSendOptions = {},
 ): Promise<ZaloSendResult> {
-  const context = resolveValidatedSendContext(chatId, options);
-  if (!context.ok) {
-    return { ok: false, error: context.error };
+  const resolved = resolveSendContextOrFailure(chatId, options);
+  if ("failure" in resolved) {
+    return resolved.failure;
   }
+  const { context } = resolved;
 
   if (options.mediaUrl) {
     return sendPhotoZalo(context.chatId, options.mediaUrl, {
@@ -73,24 +110,16 @@ export async function sendMessageZalo(
     });
   }
 
-  try {
-    const response = await sendMessage(
+  return await runZaloSend("Failed to send message", () =>
+    sendMessage(
       context.token,
       {
         chat_id: context.chatId,
         text: text.slice(0, 2000),
       },
       context.fetcher,
-    );
-
-    if (response.ok && response.result) {
-      return { ok: true, messageId: response.result.message_id };
-    }
-
-    return { ok: false, error: "Failed to send message" };
-  } catch (err) {
-    return { ok: false, error: err instanceof Error ? err.message : String(err) };
-  }
+    ),
+  );
 }
 
 export async function sendPhotoZalo(
@@ -98,17 +127,18 @@ export async function sendPhotoZalo(
   photoUrl: string,
   options: ZaloSendOptions = {},
 ): Promise<ZaloSendResult> {
-  const context = resolveValidatedSendContext(chatId, options);
-  if (!context.ok) {
-    return { ok: false, error: context.error };
+  const resolved = resolveSendContextOrFailure(chatId, options);
+  if ("failure" in resolved) {
+    return resolved.failure;
   }
+  const { context } = resolved;
 
   if (!photoUrl?.trim()) {
     return { ok: false, error: "No photo URL provided" };
   }
 
-  try {
-    const response = await sendPhoto(
+  return await runZaloSend("Failed to send photo", () =>
+    sendPhoto(
       context.token,
       {
         chat_id: context.chatId,
@@ -116,14 +146,6 @@ export async function sendPhotoZalo(
         caption: options.caption?.slice(0, 2000),
       },
       context.fetcher,
-    );
-
-    if (response.ok && response.result) {
-      return { ok: true, messageId: response.result.message_id };
-    }
-
-    return { ok: false, error: "Failed to send photo" };
-  } catch (err) {
-    return { ok: false, error: err instanceof Error ? err.message : String(err) };
-  }
+    ),
+  );
 }

package/src/status-issues.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+import { expectOpenDmPolicyConfigIssue } from "../../test-utils/status-issues.js";
+import { collectZaloStatusIssues } from "./status-issues.js";
+
+describe("collectZaloStatusIssues", () => {
+  it("warns when dmPolicy is open", () => {
+    expectOpenDmPolicyConfigIssue({
+      collectIssues: collectZaloStatusIssues,
+      account: {
+        accountId: "default",
+        enabled: true,
+        configured: true,
+        dmPolicy: "open",
+      },
+    });
+  });
+
+  it("skips unconfigured accounts", () => {
+    const issues = collectZaloStatusIssues([
+      {
+        accountId: "default",
+        enabled: true,
+        configured: false,
+        dmPolicy: "open",
+      },
+    ]);
+    expect(issues).toHaveLength(0);
+  });
+});

package/src/status-issues.ts

@@ -1,38 +1,16 @@
 import type { ChannelAccountSnapshot, ChannelStatusIssue } from "openclaw/plugin-sdk/zalo";
+import { coerceStatusIssueAccountId, readStatusIssueFields } from "../../shared/status-issues.js";
 
-type ZaloAccountStatus = {
-  accountId?: unknown;
-  enabled?: unknown;
-  configured?: unknown;
-  dmPolicy?: unknown;
-};
-
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  Boolean(value && typeof value === "object");
-
-const asString = (value: unknown): string | undefined =>
-  typeof value === "string" ? value : typeof value === "number" ? String(value) : undefined;
-
-function readZaloAccountStatus(value: ChannelAccountSnapshot): ZaloAccountStatus | null {
-  if (!isRecord(value)) {
-    return null;
-  }
-  return {
-    accountId: value.accountId,
-    enabled: value.enabled,
-    configured: value.configured,
-    dmPolicy: value.dmPolicy,
-  };
-}
+const ZALO_STATUS_FIELDS = ["accountId", "enabled", "configured", "dmPolicy"] as const;
 
 export function collectZaloStatusIssues(accounts: ChannelAccountSnapshot[]): ChannelStatusIssue[] {
   const issues: ChannelStatusIssue[] = [];
   for (const entry of accounts) {
-    const account = readZaloAccountStatus(entry);
+    const account = readStatusIssueFields(entry, ZALO_STATUS_FIELDS);
     if (!account) {
       continue;
     }
-    const accountId = asString(account.accountId) ?? "default";
+    const accountId = coerceStatusIssueAccountId(account.accountId) ?? "default";
     const enabled = account.enabled !== false;
     const configured = account.configured === true;
     if (!enabled || !configured) {