@kodelyth/zalo 2026.5.39 → 2026.5.42

package/src/group-access.ts

@@ -0,0 +1,23 @@
+import type { GroupPolicy } from "klaw/plugin-sdk/config-contracts";
+import { resolveOpenProviderRuntimeGroupPolicy } from "klaw/plugin-sdk/runtime-group-policy";
+
+const ZALO_ALLOW_FROM_PREFIX_RE = /^(zalo|zl):/i;
+
+export function normalizeZaloAllowEntry(value: string): string {
+  return value.trim().replace(ZALO_ALLOW_FROM_PREFIX_RE, "").trim().toLowerCase();
+}
+
+export function resolveZaloRuntimeGroupPolicy(params: {
+  providerConfigPresent: boolean;
+  groupPolicy?: GroupPolicy;
+  defaultGroupPolicy?: GroupPolicy;
+}): {
+  groupPolicy: GroupPolicy;
+  providerMissingFallbackApplied: boolean;
+} {
+  return resolveOpenProviderRuntimeGroupPolicy({
+    providerConfigPresent: params.providerConfigPresent,
+    groupPolicy: params.groupPolicy,
+    defaultGroupPolicy: params.defaultGroupPolicy,
+  });
+}

package/src/monitor-durable.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  prepareZaloDurableReplyPayload,
+  resolveZaloDurableReplyOptions,
+} from "./monitor-durable.js";
+
+describe("Zalo durable reply helpers", () => {
+  it("normalizes markdown tables before durable or legacy delivery", () => {
+    const convertMarkdownTables = vi.fn(() => "converted table");
+
+    expect(
+      prepareZaloDurableReplyPayload({
+        payload: { text: "| a |\n| - |" },
+        tableMode: "code",
+        convertMarkdownTables,
+      }),
+    ).toEqual({ text: "converted table" });
+    expect(convertMarkdownTables).toHaveBeenCalledWith("| a |\n| - |", "code");
+  });
+
+  it("uses durable final delivery for text-only final replies", () => {
+    expect(
+      resolveZaloDurableReplyOptions({
+        payload: { text: "hello" },
+        infoKind: "final",
+        chatId: "123456789",
+      }),
+    ).toEqual({
+      to: "123456789",
+    });
+  });
+
+  it("keeps media and non-final replies on the legacy path", () => {
+    expect(
+      resolveZaloDurableReplyOptions({
+        payload: { text: "photo", mediaUrl: "https://example.com/photo.jpg" },
+        infoKind: "final",
+        chatId: "123456789",
+      }),
+    ).toBe(false);
+    expect(
+      resolveZaloDurableReplyOptions({
+        payload: { text: "hello" },
+        infoKind: "block",
+        chatId: "123456789",
+      }),
+    ).toBe(false);
+  });
+});

package/src/monitor-durable.ts

@@ -0,0 +1,38 @@
+import type { MarkdownTableMode } from "klaw/plugin-sdk/config-contracts";
+import { resolveSendableOutboundReplyParts } from "klaw/plugin-sdk/reply-payload";
+import type { OutboundReplyPayload } from "klaw/plugin-sdk/reply-payload";
+
+export type ZaloDurableReplyOptions = {
+  to: string;
+};
+
+export function prepareZaloDurableReplyPayload(params: {
+  payload: OutboundReplyPayload;
+  tableMode: MarkdownTableMode;
+  convertMarkdownTables: (text: string, tableMode: MarkdownTableMode) => string;
+}): OutboundReplyPayload {
+  if (!params.payload.text) {
+    return params.payload;
+  }
+  return {
+    ...params.payload,
+    text: params.convertMarkdownTables(params.payload.text, params.tableMode),
+  };
+}
+
+export function resolveZaloDurableReplyOptions(params: {
+  payload: OutboundReplyPayload;
+  infoKind: string;
+  chatId: string;
+}): ZaloDurableReplyOptions | false {
+  if (params.infoKind !== "final") {
+    return false;
+  }
+  const reply = resolveSendableOutboundReplyParts(params.payload);
+  if (reply.hasMedia || !reply.hasText) {
+    return false;
+  }
+  return {
+    to: params.chatId,
+  };
+}

package/src/monitor.group-policy.test.ts

@@ -0,0 +1,213 @@
+import { resolveStableChannelMessageIngress } from "klaw/plugin-sdk/channel-ingress-runtime";
+import type { GroupPolicy, KlawConfig } from "klaw/plugin-sdk/config-contracts";
+import { describe, expect, it, vi } from "vitest";
+import { normalizeZaloAllowEntry, resolveZaloRuntimeGroupPolicy } from "./group-access.js";
+import type { ZaloAccountConfig } from "./types.js";
+
+function stringEntries(entries: Array<string | number> | undefined): string[] {
+  return (entries ?? []).map((entry) => String(entry));
+}
+
+const groupPolicyCases: Array<[string, ZaloAccountConfig, string, boolean, string]> = [
+  [
+    "disabled policy",
+    { groupPolicy: "disabled", groupAllowFrom: ["zalo:123"] },
+    "123",
+    false,
+    "group_policy_disabled",
+  ],
+  [
+    "empty allowlist",
+    { groupPolicy: "allowlist", groupAllowFrom: [] },
+    "attacker",
+    false,
+    "group_policy_empty_allowlist",
+  ],
+  [
+    "allowlist mismatch",
+    { groupPolicy: "allowlist", groupAllowFrom: ["zalo:victim-user-001"] },
+    "attacker-user-999",
+    false,
+    "group_policy_not_allowlisted",
+  ],
+  [
+    "Zalo prefix match",
+    { groupPolicy: "allowlist", groupAllowFrom: ["zl:12345"] },
+    "12345",
+    true,
+    "group_policy_allowed",
+  ],
+  [
+    "allowFrom fallback",
+    { groupPolicy: "allowlist", allowFrom: ["zl:12345"], groupAllowFrom: [] },
+    "12345",
+    true,
+    "group_policy_allowed",
+  ],
+  [
+    "open policy",
+    { groupPolicy: "open", groupAllowFrom: [] },
+    "attacker-user-999",
+    true,
+    "group_policy_open",
+  ],
+];
+
+async function resolveAccess(
+  params: {
+    cfg?: KlawConfig;
+    accountConfig?: ZaloAccountConfig;
+    providerConfigPresent?: boolean;
+    defaultGroupPolicy?: GroupPolicy;
+    isGroup?: boolean;
+    senderId?: string;
+    rawBody?: string;
+    storeAllowFrom?: string[];
+    shouldComputeCommandAuthorized?: boolean;
+  } = {},
+) {
+  const readAllowFromStore = vi.fn(async () => params.storeAllowFrom ?? []);
+  const accountConfig = {
+    dmPolicy: "pairing",
+    groupPolicy: "allowlist",
+    allowFrom: [],
+    groupAllowFrom: [],
+    ...params.accountConfig,
+  } satisfies ZaloAccountConfig;
+  const { groupPolicy, providerMissingFallbackApplied } = resolveZaloRuntimeGroupPolicy({
+    providerConfigPresent: params.providerConfigPresent ?? true,
+    groupPolicy: accountConfig.groupPolicy,
+    defaultGroupPolicy: params.defaultGroupPolicy ?? "open",
+  });
+  const shouldComputeAuth = params.shouldComputeCommandAuthorized ?? false;
+  const isGroup = params.isGroup ?? true;
+  const result = await resolveStableChannelMessageIngress({
+    channelId: "zalo",
+    accountId: "default",
+    identity: {
+      key: "zalo-user-id",
+      normalize: normalizeZaloAllowEntry,
+      sensitivity: "pii",
+      entryIdPrefix: "zalo-entry",
+    },
+    accessGroups: params.cfg?.accessGroups,
+    readStoreAllowFrom: async () => await readAllowFromStore(),
+    useAccessGroups: params.cfg?.commands?.useAccessGroups !== false,
+    subject: { stableId: params.senderId ?? "123" },
+    conversation: {
+      kind: isGroup ? "group" : "direct",
+      id: "chat-1",
+    },
+    providerMissingFallbackApplied,
+    dmPolicy: accountConfig.dmPolicy ?? "pairing",
+    groupPolicy,
+    policy: { groupAllowFromFallbackToAllowFrom: true },
+    allowFrom: stringEntries(accountConfig.allowFrom),
+    groupAllowFrom: stringEntries(accountConfig.groupAllowFrom),
+    command: shouldComputeAuth ? {} : undefined,
+  });
+  return { result, readAllowFromStore };
+}
+
+function stableSenderAccess(access: { allowed: boolean; decision: string; reasonCode: string }) {
+  return {
+    allowed: access.allowed,
+    decision: access.decision,
+    reasonCode: access.reasonCode,
+  };
+}
+
+describe("zalo shared ingress access policy", () => {
+  it.each(groupPolicyCases)(
+    "maps %s through shared ingress",
+    async (_name, accountConfig, senderId, allowed, reasonCode) => {
+      const { result } = await resolveAccess({ accountConfig, senderId });
+      expect(stableSenderAccess(result.senderAccess)).toEqual({
+        allowed,
+        decision: allowed ? "allow" : "block",
+        reasonCode,
+      });
+    },
+  );
+
+  it("keeps group control-command authorization separate from group sender access", async () => {
+    const { result } = await resolveAccess({
+      accountConfig: {
+        groupPolicy: "open",
+        allowFrom: [],
+        groupAllowFrom: [],
+      },
+      rawBody: "/reset",
+      shouldComputeCommandAuthorized: true,
+    });
+
+    expect(result.senderAccess.decision).toBe("allow");
+    expect(result.commandAccess.authorized).toBe(false);
+  });
+
+  it("authorizes direct commands from the pairing store", async () => {
+    const { result, readAllowFromStore } = await resolveAccess({
+      isGroup: false,
+      accountConfig: {
+        dmPolicy: "pairing",
+        allowFrom: [],
+      },
+      senderId: "12345",
+      storeAllowFrom: ["zl:12345"],
+      rawBody: "/status",
+      shouldComputeCommandAuthorized: true,
+    });
+
+    expect(readAllowFromStore).toHaveBeenCalledTimes(1);
+    expect(stableSenderAccess(result.senderAccess)).toEqual({
+      allowed: true,
+      decision: "allow",
+      reasonCode: "dm_policy_allowlisted",
+    });
+    expect(result.commandAccess.authorized).toBe(true);
+  });
+
+  it("requires an explicit wildcard or allowlist match for open DMs", async () => {
+    const { result, readAllowFromStore } = await resolveAccess({
+      isGroup: false,
+      accountConfig: {
+        dmPolicy: "open",
+        allowFrom: [],
+      },
+      senderId: "12345",
+    });
+
+    expect(readAllowFromStore).not.toHaveBeenCalled();
+    expect(stableSenderAccess(result.senderAccess)).toEqual({
+      allowed: false,
+      decision: "block",
+      reasonCode: "dm_policy_not_allowlisted",
+    });
+  });
+
+  it("matches static access-group entries through the shared ingress resolver", async () => {
+    const { result } = await resolveAccess({
+      cfg: {
+        accessGroups: {
+          operators: {
+            type: "message.senders",
+            members: {
+              zalo: ["zl:12345"],
+            },
+          },
+        },
+      },
+      accountConfig: {
+        groupPolicy: "allowlist",
+        groupAllowFrom: ["accessGroup:operators"],
+      },
+      senderId: "12345",
+    });
+
+    expect(stableSenderAccess(result.senderAccess)).toEqual({
+      allowed: true,
+      decision: "allow",
+      reasonCode: "group_policy_allowed",
+    });
+  });
+});

package/src/monitor.image.polling.test.ts

@@ -0,0 +1,113 @@
+import { createRuntimeEnv } from "klaw/plugin-sdk/plugin-test-runtime";
+import { afterAll, beforeEach, describe, expect, it } from "vitest";
+import {
+  createImageLifecycleCore,
+  createImageUpdate,
+  createLifecycleMonitorSetup,
+  expectImageLifecycleDelivery,
+  settleAsyncWork,
+} from "./test-support/lifecycle-test-support.js";
+import {
+  getUpdatesMock,
+  getZaloRuntimeMock,
+  loadCachedLifecycleMonitorModule,
+  resetLifecycleTestState,
+  sendMessageMock,
+} from "./test-support/monitor-mocks-test-support.js";
+
+describe("Zalo polling image handling", () => {
+  const {
+    core,
+    finalizeInboundContextMock,
+    recordInboundSessionMock,
+    readRemoteMediaBufferMock,
+    saveRemoteMediaMock,
+    saveMediaBufferMock,
+  } = createImageLifecycleCore();
+
+  beforeEach(async () => {
+    await resetLifecycleTestState();
+    getZaloRuntimeMock.mockReturnValue(core);
+  });
+
+  afterAll(async () => {
+    await resetLifecycleTestState();
+  });
+
+  it("downloads inbound image media from photo_url and preserves display_name", async () => {
+    getUpdatesMock
+      .mockResolvedValueOnce({
+        ok: true,
+        result: createImageUpdate({ date: 1774084566880 }),
+      })
+      .mockImplementation(() => new Promise(() => {}));
+
+    const { monitorZaloProvider } = await loadCachedLifecycleMonitorModule("zalo-image-polling");
+    const abort = new AbortController();
+    const runtime = createRuntimeEnv();
+    const { account, config } = createLifecycleMonitorSetup({
+      accountId: "default",
+      dmPolicy: "open",
+    });
+    const run = monitorZaloProvider({
+      token: "zalo-token", // pragma: allowlist secret
+      account,
+      config,
+      runtime,
+      abortSignal: abort.signal,
+    });
+
+    await settleAsyncWork();
+    expect(saveRemoteMediaMock).toHaveBeenCalledTimes(1);
+    expect(readRemoteMediaBufferMock).not.toHaveBeenCalled();
+    expectImageLifecycleDelivery({
+      readRemoteMediaBufferMock,
+      saveRemoteMediaMock,
+      saveMediaBufferMock,
+      finalizeInboundContextMock,
+      recordInboundSessionMock,
+    });
+
+    abort.abort();
+    await run;
+  });
+
+  it("rejects unauthorized DM images before downloading media", async () => {
+    getUpdatesMock
+      .mockResolvedValueOnce({
+        ok: true,
+        result: createImageUpdate({
+          messageId: "msg-unauthorized-1",
+          userId: "user-unauthorized-1",
+          chatId: "chat-unauthorized-1",
+        }),
+      })
+      .mockImplementation(() => new Promise(() => {}));
+
+    const { monitorZaloProvider } = await loadCachedLifecycleMonitorModule("zalo-image-polling");
+    const abort = new AbortController();
+    const runtime = createRuntimeEnv();
+    const { account, config } = createLifecycleMonitorSetup({
+      accountId: "default",
+      dmPolicy: "pairing",
+      allowFrom: ["allowed-user"],
+    });
+    const run = monitorZaloProvider({
+      token: "zalo-token", // pragma: allowlist secret
+      account,
+      config,
+      runtime,
+      abortSignal: abort.signal,
+    });
+
+    await settleAsyncWork();
+    expect(sendMessageMock).toHaveBeenCalledTimes(1);
+    expect(readRemoteMediaBufferMock).not.toHaveBeenCalled();
+    expect(saveMediaBufferMock).not.toHaveBeenCalled();
+    expect(finalizeInboundContextMock).not.toHaveBeenCalled();
+    expect(recordInboundSessionMock).not.toHaveBeenCalled();
+
+    abort.abort();
+    await run;
+  });
+});

package/src/monitor.lifecycle.test.ts

@@ -0,0 +1,194 @@
+import {
+  createEmptyPluginRegistry,
+  createRuntimeEnv,
+  setActivePluginRegistry,
+} from "klaw/plugin-sdk/plugin-test-runtime";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { KlawConfig } from "../runtime-api.js";
+import type { ResolvedZaloAccount } from "./accounts.js";
+
+const getWebhookInfoMock = vi.fn(async () => ({ ok: true, result: { url: "" } }));
+const deleteWebhookMock = vi.fn(async () => ({ ok: true, result: { url: "" } }));
+const getUpdatesMock = vi.fn(() => new Promise(() => {}));
+const setWebhookMock = vi.fn(async () => ({ ok: true, result: { url: "" } }));
+
+vi.mock("./api.js", async () => {
+  const actual = await vi.importActual<typeof import("./api.js")>("./api.js");
+  return {
+    ...actual,
+    deleteWebhook: deleteWebhookMock,
+    getWebhookInfo: getWebhookInfoMock,
+    getUpdates: getUpdatesMock,
+    setWebhook: setWebhookMock,
+  };
+});
+
+vi.mock("./runtime.js", () => ({
+  getZaloRuntime: () => ({
+    logging: {
+      shouldLogVerbose: () => false,
+    },
+  }),
+}));
+
+const TEST_ACCOUNT = {
+  accountId: "default",
+  config: {},
+} as unknown as ResolvedZaloAccount;
+
+const TEST_CONFIG = {} as KlawConfig;
+
+async function settleLifecycleWork(): Promise<void> {
+  for (let i = 0; i < 6; i += 1) {
+    await Promise.resolve();
+    await new Promise((resolve) => setImmediate(resolve));
+  }
+}
+
+async function startLifecycleMonitor(
+  options: {
+    useWebhook?: boolean;
+    webhookSecret?: string;
+    webhookUrl?: string;
+  } = {},
+) {
+  const { monitorZaloProvider } = await import("./monitor.js");
+  const abort = new AbortController();
+  const runtime = createRuntimeEnv();
+  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();
+    setActivePluginRegistry(createEmptyPluginRegistry());
+  });
+
+  it("stays alive in polling mode until abort", async () => {
+    let settled = false;
+    const { abort, runtime, run } = await startLifecycleMonitor();
+    const monitoredRun = run.then(() => {
+      settled = true;
+    });
+
+    await settleLifecycleWork();
+    expect(getUpdatesMock).toHaveBeenCalledTimes(1);
+
+    expect(getWebhookInfoMock).toHaveBeenCalledTimes(1);
+    expect(deleteWebhookMock).not.toHaveBeenCalled();
+    expect(getUpdatesMock).toHaveBeenCalledTimes(1);
+    expect(settled).toBe(false);
+
+    abort.abort();
+    await monitoredRun;
+
+    expect(settled).toBe(true);
+    expect(runtime.log).toHaveBeenCalledWith("[default] Zalo provider stopped mode=polling");
+  });
+
+  it("deletes an existing webhook before polling", async () => {
+    getWebhookInfoMock.mockResolvedValueOnce({
+      ok: true,
+      result: { url: "https://example.com/hooks/zalo" },
+    });
+
+    const { abort, runtime, run } = await startLifecycleMonitor();
+
+    await settleLifecycleWork();
+    expect(getUpdatesMock).toHaveBeenCalledTimes(1);
+
+    expect(getWebhookInfoMock).toHaveBeenCalledTimes(1);
+    expect(deleteWebhookMock).toHaveBeenCalledTimes(1);
+    expect(runtime.log).toHaveBeenCalledWith(
+      "[default] Zalo polling mode ready (webhook disabled)",
+    );
+
+    abort.abort();
+    await run;
+  });
+
+  it("continues polling when webhook inspection returns 404", async () => {
+    const { ZaloApiError } = await import("./api.js");
+    getWebhookInfoMock.mockRejectedValueOnce(new ZaloApiError("Not Found", 404, "Not Found"));
+
+    const { abort, runtime, run } = await startLifecycleMonitor();
+
+    await settleLifecycleWork();
+    expect(getUpdatesMock).toHaveBeenCalledTimes(1);
+
+    expect(getWebhookInfoMock).toHaveBeenCalledTimes(1);
+    expect(deleteWebhookMock).not.toHaveBeenCalled();
+    expect(runtime.log).toHaveBeenCalledWith(
+      "[default] Zalo polling mode webhook inspection unavailable; continuing without webhook cleanup",
+    );
+    expect(runtime.error).not.toHaveBeenCalled();
+
+    abort.abort();
+    await run;
+  });
+
+  it("waits for webhook deletion before finishing webhook shutdown", async () => {
+    const registry = createEmptyPluginRegistry();
+    setActivePluginRegistry(registry);
+
+    let resolveSetWebhookCalled: (() => void) | undefined;
+    const setWebhookCalled = new Promise<void>((resolve) => {
+      resolveSetWebhookCalled = resolve;
+    });
+    setWebhookMock.mockImplementationOnce(async () => {
+      resolveSetWebhookCalled?.();
+      return { ok: true, result: { url: "" } };
+    });
+
+    let resolveDeleteWebhookCalled: (() => void) | undefined;
+    const deleteWebhookCalled = new Promise<void>((resolve) => {
+      resolveDeleteWebhookCalled = resolve;
+    });
+    let resolveDeleteWebhook: (() => void) | undefined;
+    deleteWebhookMock.mockImplementationOnce(
+      () =>
+        new Promise((resolve) => {
+          resolveDeleteWebhookCalled?.();
+          resolveDeleteWebhook = () => resolve({ ok: true, result: { url: "" } });
+        }),
+    );
+
+    let settled = false;
+    const { abort, runtime, run } = await startLifecycleMonitor({
+      useWebhook: true,
+      webhookUrl: "https://example.com/hooks/zalo",
+      webhookSecret: "supersecret", // pragma: allowlist secret
+    });
+    const monitoredRun = run.then(() => {
+      settled = true;
+    });
+
+    await setWebhookCalled;
+    await settleLifecycleWork();
+    expect(setWebhookMock).toHaveBeenCalledTimes(1);
+    expect(registry.httpRoutes).toHaveLength(2);
+
+    abort.abort();
+
+    await deleteWebhookCalled;
+    expect(deleteWebhookMock).toHaveBeenCalledTimes(1);
+    expect(deleteWebhookMock).toHaveBeenCalledWith("test-token", undefined, 5000);
+    expect(settled).toBe(false);
+    expect(registry.httpRoutes).toHaveLength(2);
+
+    resolveDeleteWebhook?.();
+    await monitoredRun;
+
+    expect(settled).toBe(true);
+    expect(registry.httpRoutes).toHaveLength(0);
+    expect(runtime.log).toHaveBeenCalledWith("[default] Zalo provider stopped mode=webhook");
+  });
+});