@openclaw/zalo 2026.3.13 → 2026.5.1-beta.2

package/runtime-api.ts

@@ -0,0 +1,75 @@
+export {
+  addWildcardAllowFrom,
+  applyAccountNameToChannelSection,
+  applyBasicWebhookRequestGuards,
+  applySetupAccountConfigPatch,
+  type BaseProbeResult,
+  type BaseTokenResolution,
+  buildBaseAccountStatusSnapshot,
+  buildChannelConfigSchema,
+  buildSecretInputSchema,
+  buildSingleChannelSecretPromptState,
+  buildTokenChannelStatusSummary,
+  type ChannelAccountSnapshot,
+  type ChannelMessageActionAdapter,
+  type ChannelMessageActionName,
+  type ChannelPlugin,
+  type ChannelStatusIssue,
+  chunkTextForOutbound,
+  createChannelPairingController,
+  createChannelReplyPipeline,
+  createDedupeCache,
+  createFixedWindowRateLimiter,
+  createWebhookAnomalyTracker,
+  DEFAULT_ACCOUNT_ID,
+  deliverTextOrMediaReply,
+  evaluateSenderGroupAccess,
+  formatAllowFromLowercase,
+  formatPairingApproveHint,
+  type GroupPolicy,
+  hasConfiguredSecretInput,
+  isNormalizedSenderAllowed,
+  isNumericTargetId,
+  jsonResult,
+  logTypingFailure,
+  type MarkdownTableMode,
+  mergeAllowFromEntries,
+  migrateBaseNameToDefaultAccount,
+  normalizeAccountId,
+  normalizeResolvedSecretInputString,
+  normalizeSecretInputString,
+  type OpenClawConfig,
+  type OutboundReplyPayload,
+  PAIRING_APPROVED_MESSAGE,
+  type PluginRuntime,
+  promptSingleChannelSecretInput,
+  readJsonWebhookBodyOrReject,
+  readStringParam,
+  registerPluginHttpRoute,
+  type RegisterWebhookPluginRouteOptions,
+  registerWebhookTarget,
+  type RegisterWebhookTargetOptions,
+  registerWebhookTargetWithPluginRoute,
+  type ReplyPayload,
+  resolveClientIp,
+  resolveDefaultGroupPolicy,
+  resolveDirectDmAuthorizationOutcome,
+  resolveInboundRouteEnvelopeBuilderWithRuntime,
+  resolveOpenProviderRuntimeGroupPolicy,
+  resolveSenderCommandAuthorizationWithRuntime,
+  resolveWebhookPath,
+  resolveWebhookTargetWithAuthOrRejectSync,
+  runSingleChannelSecretStep,
+  type RuntimeEnv,
+  type SecretInput,
+  type SenderGroupAccessDecision,
+  sendPayloadWithChunkedTextAndMedia,
+  setTopLevelChannelDmPolicyWithAllowFrom,
+  setZaloRuntime,
+  waitForAbortSignal,
+  warnMissingProviderGroupPolicyFallbackOnce,
+  WEBHOOK_ANOMALY_COUNTER_DEFAULTS,
+  WEBHOOK_RATE_LIMIT_DEFAULTS,
+  withResolvedWebhookRequestPipeline,
+  type WizardPrompter,
+} from "./src/runtime-api.js";

package/secret-contract-api.ts

@@ -0,0 +1,5 @@
+export {
+  channelSecrets,
+  collectRuntimeConfigAssignments,
+  secretTargetRegistryEntries,
+} from "./src/secret-contract.js";

package/setup-api.ts

@@ -0,0 +1,34 @@
+import { loadBundledEntryExportSync } from "openclaw/plugin-sdk/channel-entry-contract";
+
+type SetupSurfaceModule = typeof import("./src/setup-surface.js");
+
+function createLazyObjectValue<T extends object>(load: () => T): T {
+  return new Proxy({} as T, {
+    get(_target, property, receiver) {
+      return Reflect.get(load(), property, receiver);
+    },
+    has(_target, property) {
+      return property in load();
+    },
+    ownKeys() {
+      return Reflect.ownKeys(load());
+    },
+    getOwnPropertyDescriptor(_target, property) {
+      const descriptor = Object.getOwnPropertyDescriptor(load(), property);
+      return descriptor ? { ...descriptor, configurable: true } : undefined;
+    },
+  });
+}
+
+function loadSetupSurfaceModule(): SetupSurfaceModule {
+  return loadBundledEntryExportSync<SetupSurfaceModule>(import.meta.url, {
+    specifier: "./src/setup-surface.js",
+  });
+}
+
+export { zaloDmPolicy, zaloSetupAdapter, createZaloSetupWizardProxy } from "./src/setup-core.js";
+export { evaluateZaloGroupAccess, resolveZaloRuntimeGroupPolicy } from "./src/group-access.js";
+
+export const zaloSetupWizard: SetupSurfaceModule["zaloSetupWizard"] = createLazyObjectValue(
+  () => loadSetupSurfaceModule().zaloSetupWizard as object,
+) as SetupSurfaceModule["zaloSetupWizard"];

package/setup-entry.ts

@@ -0,0 +1,13 @@
+import { defineBundledChannelSetupEntry } from "openclaw/plugin-sdk/channel-entry-contract";
+
+export default defineBundledChannelSetupEntry({
+  importMetaUrl: import.meta.url,
+  plugin: {
+    specifier: "./api.js",
+    exportName: "zaloPlugin",
+  },
+  secrets: {
+    specifier: "./secret-contract-api.js",
+    exportName: "channelSecrets",
+  },
+});

package/src/accounts.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from "vitest";
+import { resolveZaloAccount } from "./accounts.js";
+
+describe("resolveZaloAccount", () => {
+  it("resolves account config when account key casing differs from normalized id", () => {
+    const resolved = resolveZaloAccount({
+      cfg: {
+        channels: {
+          zalo: {
+            webhookUrl: "https://top.example.com",
+            accounts: {
+              Work: {
+                name: "Work",
+                webhookUrl: "https://work.example.com",
+              },
+            },
+          },
+        },
+      },
+      accountId: "work",
+    });
+
+    expect(resolved.accountId).toBe("work");
+    expect(resolved.name).toBe("Work");
+    expect(resolved.config.webhookUrl).toBe("https://work.example.com");
+  });
+
+  it("falls back to top-level config for named accounts without overrides", () => {
+    const resolved = resolveZaloAccount({
+      cfg: {
+        channels: {
+          zalo: {
+            enabled: true,
+            webhookUrl: "https://top.example.com",
+            accounts: {
+              work: {},
+            },
+          },
+        },
+      },
+      accountId: "work",
+    });
+
+    expect(resolved.accountId).toBe("work");
+    expect(resolved.enabled).toBe(true);
+    expect(resolved.config.webhookUrl).toBe("https://top.example.com");
+  });
+
+  it("uses configured defaultAccount when accountId is omitted", () => {
+    const resolved = resolveZaloAccount({
+      cfg: {
+        channels: {
+          zalo: {
+            defaultAccount: "work",
+            accounts: {
+              work: {
+                name: "Work",
+                botToken: "work-token",
+              },
+            },
+          },
+        },
+      },
+    });
+
+    expect(resolved.accountId).toBe("work");
+    expect(resolved.name).toBe("Work");
+    expect(resolved.token).toBe("work-token");
+  });
+});

package/src/accounts.ts

@@ -1,5 +1,10 @@
-import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk/account-id";
-import { createAccountListHelpers, type OpenClawConfig } from "openclaw/plugin-sdk/zalo";
+import {
+  createAccountListHelpers,
+  resolveMergedAccountConfig,
+} from "openclaw/plugin-sdk/account-helpers";
+import { normalizeAccountId } from "openclaw/plugin-sdk/account-id";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import { normalizeOptionalString } from "openclaw/plugin-sdk/text-runtime";
 import { resolveZaloToken } from "./token.js";
 import type { ResolvedZaloAccount, ZaloAccountConfig, ZaloConfig } from "./types.js";
 
@@ -9,22 +14,15 @@ const { listAccountIds: listZaloAccountIds, resolveDefaultAccountId: resolveDefa
   createAccountListHelpers("zalo");
 export { listZaloAccountIds, resolveDefaultZaloAccountId };
 
-function resolveAccountConfig(
-  cfg: OpenClawConfig,
-  accountId: string,
-): ZaloAccountConfig | undefined {
-  const accounts = (cfg.channels?.zalo as ZaloConfig | undefined)?.accounts;
-  if (!accounts || typeof accounts !== "object") {
-    return undefined;
-  }
-  return accounts[accountId] as ZaloAccountConfig | undefined;
-}
-
 function mergeZaloAccountConfig(cfg: OpenClawConfig, accountId: string): ZaloAccountConfig {
-  const raw = (cfg.channels?.zalo ?? {}) as ZaloConfig;
-  const { accounts: _ignored, defaultAccount: _ignored2, ...base } = raw;
-  const account = resolveAccountConfig(cfg, accountId) ?? {};
-  return { ...base, ...account };
+  return resolveMergedAccountConfig<ZaloAccountConfig>({
+    channelConfig: cfg.channels?.zalo as ZaloAccountConfig | undefined,
+    accounts: (cfg.channels?.zalo as ZaloConfig | undefined)?.accounts as
+      | Record<string, Partial<ZaloAccountConfig>>
+      | undefined,
+    accountId,
+    omitKeys: ["defaultAccount"],
+  });
 }
 
 export function resolveZaloAccount(params: {
@@ -32,7 +30,9 @@ export function resolveZaloAccount(params: {
   accountId?: string | null;
   allowUnresolvedSecretRef?: boolean;
 }): ResolvedZaloAccount {
-  const accountId = normalizeAccountId(params.accountId);
+  const accountId = normalizeAccountId(
+    params.accountId ?? (params.cfg.channels?.zalo as ZaloConfig | undefined)?.defaultAccount,
+  );
   const baseEnabled = (params.cfg.channels?.zalo as ZaloConfig | undefined)?.enabled !== false;
   const merged = mergeZaloAccountConfig(params.cfg, accountId);
   const accountEnabled = merged.enabled !== false;
@@ -45,7 +45,7 @@ export function resolveZaloAccount(params: {
 
   return {
     accountId,
-    name: merged.name?.trim() || undefined,
+    name: normalizeOptionalString(merged.name),
     enabled,
     token: tokenResolution.token,
     tokenSource: tokenResolution.source,

package/src/actions.runtime.ts

@@ -0,0 +1,5 @@
+import { sendMessageZalo as sendMessageZaloImpl } from "./send.js";
+
+export const zaloActionsRuntime = {
+  sendMessageZalo: sendMessageZaloImpl,
+};

package/src/actions.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+import { zaloMessageActions } from "./actions.js";
+import type { OpenClawConfig } from "./runtime-api.js";
+
+describe("zaloMessageActions.describeMessageTool", () => {
+  it("honors the selected Zalo account during discovery", () => {
+    const cfg: OpenClawConfig = {
+      channels: {
+        zalo: {
+          enabled: true,
+          botToken: "root-token",
+          accounts: {
+            default: {
+              enabled: false,
+              botToken: "default-token",
+            },
+            work: {
+              enabled: true,
+              botToken: "work-token",
+            },
+          },
+        },
+      },
+    };
+
+    expect(zaloMessageActions.describeMessageTool?.({ cfg, accountId: "default" })).toBeNull();
+    expect(zaloMessageActions.describeMessageTool?.({ cfg, accountId: "work" })).toEqual({
+      actions: ["send"],
+      capabilities: [],
+    });
+  });
+});

package/src/actions.ts

@@ -1,30 +1,35 @@
+import { jsonResult, readStringParam } from "openclaw/plugin-sdk/channel-actions";
 import type {
   ChannelMessageActionAdapter,
   ChannelMessageActionName,
-  OpenClawConfig,
-} from "openclaw/plugin-sdk/zalo";
-import { extractToolSend, jsonResult, readStringParam } from "openclaw/plugin-sdk/zalo";
-import { listEnabledZaloAccounts } from "./accounts.js";
-import { sendMessageZalo } from "./send.js";
+} from "openclaw/plugin-sdk/channel-contract";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import { createLazyRuntimeNamedExport } from "openclaw/plugin-sdk/lazy-runtime";
+import { extractToolSend } from "openclaw/plugin-sdk/tool-send";
+import { listEnabledZaloAccounts, resolveZaloAccount } from "./accounts.js";
+
+const loadZaloActionsRuntime = createLazyRuntimeNamedExport(
+  () => import("./actions.runtime.js"),
+  "zaloActionsRuntime",
+);
 
 const providerId = "zalo";
 
-function listEnabledAccounts(cfg: OpenClawConfig) {
-  return listEnabledZaloAccounts(cfg).filter(
-    (account) => account.enabled && account.tokenSource !== "none",
-  );
+function listEnabledAccounts(cfg: OpenClawConfig, accountId?: string | null) {
+  return (
+    accountId ? [resolveZaloAccount({ cfg, accountId })] : listEnabledZaloAccounts(cfg)
+  ).filter((account) => account.enabled && account.tokenSource !== "none");
 }
 
 export const zaloMessageActions: ChannelMessageActionAdapter = {
-  listActions: ({ cfg }) => {
-    const accounts = listEnabledAccounts(cfg);
+  describeMessageTool: ({ cfg, accountId }) => {
+    const accounts = listEnabledAccounts(cfg, accountId);
     if (accounts.length === 0) {
-      return [];
+      return null;
     }
     const actions = new Set<ChannelMessageActionName>(["send"]);
-    return Array.from(actions);
+    return { actions: Array.from(actions), capabilities: [] };
   },
-  supportsButtons: () => false,
   extractToolSend: ({ args }) => extractToolSend(args, "sendMessage"),
   handleAction: async ({ action, params, cfg, accountId }) => {
     if (action === "send") {
@@ -35,6 +40,7 @@ export const zaloMessageActions: ChannelMessageActionAdapter = {
       });
       const mediaUrl = readStringParam(params, "media", { trim: false });
 
+      const { sendMessageZalo } = await loadZaloActionsRuntime();
       const result = await sendMessageZalo(to ?? "", content ?? "", {
         accountId: accountId ?? undefined,
         mediaUrl: mediaUrl ?? undefined,

package/src/api.test.ts

@@ -1,5 +1,13 @@
-import { describe, expect, it, vi } from "vitest";
-import { deleteWebhook, getWebhookInfo, sendChatAction, type ZaloFetch } from "./api.js";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const resolvePinnedHostnameWithPolicyMock = vi.fn();
+
+vi.mock("openclaw/plugin-sdk/ssrf-runtime", () => ({
+  resolvePinnedHostnameWithPolicy: (...args: unknown[]) =>
+    resolvePinnedHostnameWithPolicyMock(...args),
+}));
+
+import { deleteWebhook, getWebhookInfo, sendChatAction, sendPhoto, type ZaloFetch } from "./api.js";
 
 function createOkFetcher() {
   return vi.fn<ZaloFetch>(async () => new Response(JSON.stringify({ ok: true, result: {} })));
@@ -15,6 +23,15 @@ async function expectPostJsonRequest(run: (token: string, fetcher: ZaloFetch) =>
 }
 
 describe("Zalo API request methods", () => {
+  beforeEach(() => {
+    resolvePinnedHostnameWithPolicyMock.mockReset();
+    resolvePinnedHostnameWithPolicyMock.mockResolvedValue({
+      hostname: "example.com",
+      addresses: ["93.184.216.34"],
+      lookup: vi.fn(),
+    });
+  });
+
   it("uses POST for getWebhookInfo", async () => {
     await expectPostJsonRequest(getWebhookInfo);
   });
@@ -55,4 +72,78 @@ describe("Zalo API request methods", () => {
       vi.useRealTimers();
     }
   });
+
+  it("validates outbound photo URLs against the SSRF guard before posting", async () => {
+    const fetcher = createOkFetcher();
+
+    await sendPhoto(
+      "test-token",
+      {
+        chat_id: "chat-123",
+        photo: "https://example.com/image.png",
+      },
+      fetcher,
+    );
+
+    expect(resolvePinnedHostnameWithPolicyMock).toHaveBeenCalledWith("example.com", {
+      policy: {},
+    });
+    expect(fetcher).toHaveBeenCalledTimes(1);
+  });
+
+  it("blocks private-network photo URLs before they reach the Zalo API", async () => {
+    const fetcher = createOkFetcher();
+    resolvePinnedHostnameWithPolicyMock.mockRejectedValueOnce(
+      new Error("Blocked hostname or private/internal/special-use IP address"),
+    );
+
+    await expect(
+      sendPhoto(
+        "test-token",
+        {
+          chat_id: "chat-123",
+          photo: "http://169.254.169.254/latest/meta-data/iam/security-credentials/",
+        },
+        fetcher,
+      ),
+    ).rejects.toThrow("Blocked hostname or private/internal/special-use IP address");
+
+    expect(fetcher).not.toHaveBeenCalled();
+  });
+
+  it("rejects non-http photo URLs", async () => {
+    const fetcher = createOkFetcher();
+
+    await expect(
+      sendPhoto(
+        "test-token",
+        {
+          chat_id: "chat-123",
+          photo: "file:///etc/passwd",
+        },
+        fetcher,
+      ),
+    ).rejects.toThrow("Zalo photo URL must use HTTP or HTTPS");
+
+    expect(resolvePinnedHostnameWithPolicyMock).not.toHaveBeenCalled();
+    expect(fetcher).not.toHaveBeenCalled();
+  });
+
+  it("rejects non-URL strings", async () => {
+    const fetcher = createOkFetcher();
+
+    await expect(
+      sendPhoto(
+        "test-token",
+        {
+          chat_id: "chat-123",
+          photo: "not a url",
+        },
+        fetcher,
+      ),
+    ).rejects.toThrow("Zalo photo URL must be an absolute HTTP or HTTPS URL");
+
+    expect(resolvePinnedHostnameWithPolicyMock).not.toHaveBeenCalled();
+    expect(fetcher).not.toHaveBeenCalled();
+  });
 });

package/src/api.ts

@@ -3,7 +3,10 @@
  * @see https://bot.zaloplatforms.com/docs
  */
 
+import { resolvePinnedHostnameWithPolicy, type SsrFPolicy } from "openclaw/plugin-sdk/ssrf-runtime";
+
 const ZALO_API_BASE = "https://bot-api.zaloplatforms.com";
+const ZALO_MEDIA_SSRF_POLICY: SsrFPolicy = {};
 
 export type ZaloFetch = (input: string, init?: RequestInit) => Promise<Response>;
 
@@ -25,7 +28,9 @@ export type ZaloMessage = {
   from: {
     id: string;
     name?: string;
+    display_name?: string;
     avatar?: string;
+    is_bot?: boolean;
   };
   chat: {
     id: string;
@@ -33,9 +38,10 @@ export type ZaloMessage = {
   };
   date: number;
   text?: string;
-  photo?: string;
+  photo_url?: string;
   caption?: string;
   sticker?: string;
+  message_type?: string;
 };
 
 export type ZaloUpdate = {
@@ -169,7 +175,28 @@ export async function sendPhoto(
   params: ZaloSendPhotoParams,
   fetcher?: ZaloFetch,
 ): Promise<ZaloApiResponse<ZaloMessage>> {
-  return callZaloApi<ZaloMessage>("sendPhoto", token, params, { fetch: fetcher });
+  const photoUrl = params.photo.trim();
+  let parsedPhotoUrl: URL;
+  try {
+    parsedPhotoUrl = new URL(photoUrl);
+  } catch {
+    throw new Error("Zalo photo URL must be an absolute HTTP or HTTPS URL");
+  }
+
+  if (parsedPhotoUrl.protocol !== "http:" && parsedPhotoUrl.protocol !== "https:") {
+    throw new Error("Zalo photo URL must use HTTP or HTTPS");
+  }
+
+  await resolvePinnedHostnameWithPolicy(parsedPhotoUrl.hostname, {
+    policy: ZALO_MEDIA_SSRF_POLICY,
+  });
+
+  return callZaloApi<ZaloMessage>(
+    "sendPhoto",
+    token,
+    { ...params, photo: parsedPhotoUrl.href },
+    { fetch: fetcher },
+  );
 }
 
 /**

package/src/approval-auth.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from "vitest";
+import { zaloApprovalAuth } from "./approval-auth.js";
+
+describe("zaloApprovalAuth", () => {
+  it("authorizes numeric Zalo user ids", () => {
+    const cfg = { channels: { zalo: { allowFrom: ["zl:123"] } } };
+
+    expect(
+      zaloApprovalAuth.authorizeActorAction({
+        cfg,
+        senderId: "123",
+        action: "approve",
+        approvalKind: "exec",
+      }),
+    ).toEqual({ authorized: true });
+  });
+});

package/src/approval-auth.ts

@@ -0,0 +1,25 @@
+import {
+  createResolvedApproverActionAuthAdapter,
+  resolveApprovalApprovers,
+} from "openclaw/plugin-sdk/approval-auth-runtime";
+import { resolveZaloAccount } from "./accounts.js";
+
+function normalizeZaloApproverId(value: string | number): string | undefined {
+  const normalized = String(value)
+    .trim()
+    .replace(/^(zalo|zl):/i, "")
+    .trim();
+  return /^\d+$/.test(normalized) ? normalized : undefined;
+}
+
+export const zaloApprovalAuth = createResolvedApproverActionAuthAdapter({
+  channelLabel: "Zalo",
+  resolveApprovers: ({ cfg, accountId }) => {
+    const account = resolveZaloAccount({ cfg, accountId }).config;
+    return resolveApprovalApprovers({
+      allowFrom: account.allowFrom,
+      normalizeApprover: normalizeZaloApproverId,
+    });
+  },
+  normalizeSenderId: (value) => normalizeZaloApproverId(value),
+});

package/src/channel.directory.test.ts

@@ -1,22 +1,24 @@
-import type { OpenClawConfig, RuntimeEnv } from "openclaw/plugin-sdk/zalo";
+import {
+  createDirectoryTestRuntime,
+  expectDirectorySurface,
+} from "openclaw/plugin-sdk/channel-test-helpers";
 import { describe, expect, it } from "vitest";
-import { createDirectoryTestRuntime, expectDirectorySurface } from "../../test-utils/directory.js";
+import type { OpenClawConfig, RuntimeEnv } from "../runtime-api.js";
 import { zaloPlugin } from "./channel.js";
 
 describe("zalo directory", () => {
   const runtimeEnv = createDirectoryTestRuntime() as RuntimeEnv;
+  const directory = expectDirectorySurface(zaloPlugin.directory);
 
-  it("lists peers from allowFrom", async () => {
+  async function expectPeersFromAllowFrom(allowFrom: string[]) {
     const cfg = {
       channels: {
         zalo: {
-          allowFrom: ["zalo:123", "zl:234", "345"],
+          allowFrom,
         },
       },
     } as unknown as OpenClawConfig;
 
-    const directory = expectDirectorySurface(zaloPlugin.directory);
-
     await expect(
       directory.listPeers({
         cfg,
@@ -42,5 +44,16 @@ describe("zalo directory", () => {
         runtime: runtimeEnv,
       }),
     ).resolves.toEqual([]);
+  }
+
+  it("lists peers from allowFrom", async () => {
+    await expectPeersFromAllowFrom(["zalo:123", "zl:234", "345"]);
+  });
+
+  it("normalizes spaced zalo prefixes in allowFrom and pairing entries", async () => {
+    await expectPeersFromAllowFrom(["  zalo:123  ", "  zl:234  ", " 345 "]);
+
+    expect(zaloPlugin.pairing?.normalizeAllowEntry?.("  zalo:123  ")).toBe("123");
+    expect(zaloPlugin.messaging?.normalizeTarget?.("  zl:234  ")).toBe("234");
   });
 });