@openclaw/zalouser 2026.3.12 → 2026.5.1-beta.2

package/src/config-schema.ts

@@ -3,12 +3,12 @@ import {
   buildCatchallMultiAccountChannelSchema,
   DmPolicySchema,
   GroupPolicySchema,
-} from "openclaw/plugin-sdk/compat";
-import { MarkdownConfigSchema, ToolPolicySchema } from "openclaw/plugin-sdk/zalouser";
-import { z } from "zod";
+  MarkdownConfigSchema,
+  ToolPolicySchema,
+} from "openclaw/plugin-sdk/channel-config-schema";
+import { z } from "openclaw/plugin-sdk/zod";
 
 const groupConfigSchema = z.object({
-  allow: z.boolean().optional(),
   enabled: z.boolean().optional(),
   requireMention: z.boolean().optional(),
   tools: ToolPolicySchema,
@@ -24,7 +24,7 @@ const zalouserAccountSchema = z.object({
   allowFrom: AllowFromListSchema,
   historyLimit: z.number().int().min(0).optional(),
   groupAllowFrom: AllowFromListSchema,
-  groupPolicy: GroupPolicySchema.optional(),
+  groupPolicy: GroupPolicySchema.optional().default("allowlist"),
   groups: z.object({}).catchall(groupConfigSchema).optional(),
   messagePrefix: z.string().optional(),
   responsePrefix: z.string().optional(),

package/src/directory.ts

@@ -0,0 +1,54 @@
+import { resolveZalouserAccountSync } from "./accounts.js";
+import type { ChannelDirectoryEntry, OpenClawConfig } from "./channel-api.js";
+import { parseZalouserDirectoryGroupId } from "./session-route.js";
+
+type ZalouserDirectoryDeps = {
+  listZaloGroupMembers: (
+    profile: string,
+    groupId: string,
+  ) => Promise<
+    Array<{
+      userId: string;
+      displayName?: string | null;
+      avatar?: string | null;
+    }>
+  >;
+};
+
+function mapUser(params: {
+  id: string;
+  name?: string | null;
+  avatarUrl?: string | null;
+  raw?: unknown;
+}): ChannelDirectoryEntry {
+  return {
+    kind: "user",
+    id: params.id,
+    name: params.name ?? undefined,
+    avatarUrl: params.avatarUrl ?? undefined,
+    raw: params.raw,
+  };
+}
+
+export async function listZalouserDirectoryGroupMembers(
+  params: {
+    cfg: OpenClawConfig;
+    accountId?: string;
+    groupId: string;
+    limit?: number;
+  },
+  deps: ZalouserDirectoryDeps,
+) {
+  const account = resolveZalouserAccountSync({ cfg: params.cfg, accountId: params.accountId });
+  const normalizedGroupId = parseZalouserDirectoryGroupId(params.groupId);
+  const members = await deps.listZaloGroupMembers(account.profile, normalizedGroupId);
+  const rows = members.map((member) =>
+    mapUser({
+      id: member.userId,
+      name: member.displayName,
+      avatarUrl: member.avatar ?? null,
+      raw: member,
+    }),
+  );
+  return typeof params.limit === "number" && params.limit > 0 ? rows.slice(0, params.limit) : rows;
+}

package/src/doctor-contract.ts

@@ -0,0 +1,156 @@
+import type {
+  ChannelDoctorConfigMutation,
+  ChannelDoctorLegacyConfigRule,
+} from "openclaw/plugin-sdk/channel-contract";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+
+type ZalouserChannelsConfig = NonNullable<OpenClawConfig["channels"]>;
+
+function asObjectRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function hasLegacyZalouserGroupAllowAlias(value: unknown): boolean {
+  const group = asObjectRecord(value);
+  return Boolean(group && typeof group.allow === "boolean");
+}
+
+function hasLegacyZalouserGroupAllowAliases(value: unknown): boolean {
+  const groups = asObjectRecord(value);
+  return Boolean(
+    groups && Object.values(groups).some((group) => hasLegacyZalouserGroupAllowAlias(group)),
+  );
+}
+
+function hasLegacyZalouserAccountGroupAllowAliases(value: unknown): boolean {
+  const accounts = asObjectRecord(value);
+  if (!accounts) {
+    return false;
+  }
+  return Object.values(accounts).some((account) => {
+    const accountRecord = asObjectRecord(account);
+    return Boolean(accountRecord && hasLegacyZalouserGroupAllowAliases(accountRecord.groups));
+  });
+}
+
+function normalizeZalouserGroupAllowAliases(params: {
+  groups: Record<string, unknown>;
+  pathPrefix: string;
+  changes: string[];
+}): { groups: Record<string, unknown>; changed: boolean } {
+  let changed = false;
+  const nextGroups: Record<string, unknown> = { ...params.groups };
+  for (const [groupId, groupValue] of Object.entries(params.groups)) {
+    const group = asObjectRecord(groupValue);
+    if (!group || typeof group.allow !== "boolean") {
+      continue;
+    }
+    const nextGroup = { ...group };
+    if (typeof nextGroup.enabled !== "boolean") {
+      nextGroup.enabled = group.allow;
+    }
+    delete nextGroup.allow;
+    nextGroups[groupId] = nextGroup;
+    changed = true;
+    params.changes.push(
+      `Moved ${params.pathPrefix}.${groupId}.allow → ${params.pathPrefix}.${groupId}.enabled (${String(nextGroup.enabled)}).`,
+    );
+  }
+  return { groups: nextGroups, changed };
+}
+
+function normalizeZalouserCompatibilityConfig(cfg: OpenClawConfig): ChannelDoctorConfigMutation {
+  const channels = asObjectRecord(cfg.channels);
+  const zalouser = asObjectRecord(channels?.zalouser);
+  if (!zalouser) {
+    return { config: cfg, changes: [] };
+  }
+
+  const changes: string[] = [];
+  let updatedZalouser: Record<string, unknown> = zalouser;
+  let changed = false;
+
+  const groups = asObjectRecord(updatedZalouser.groups);
+  if (groups) {
+    const normalized = normalizeZalouserGroupAllowAliases({
+      groups,
+      pathPrefix: "channels.zalouser.groups",
+      changes,
+    });
+    if (normalized.changed) {
+      updatedZalouser = { ...updatedZalouser, groups: normalized.groups };
+      changed = true;
+    }
+  }
+
+  const accounts = asObjectRecord(updatedZalouser.accounts);
+  if (accounts) {
+    let accountsChanged = false;
+    const nextAccounts: Record<string, unknown> = { ...accounts };
+    for (const [accountId, accountValue] of Object.entries(accounts)) {
+      const account = asObjectRecord(accountValue);
+      if (!account) {
+        continue;
+      }
+      const accountGroups = asObjectRecord(account.groups);
+      if (!accountGroups) {
+        continue;
+      }
+      const normalized = normalizeZalouserGroupAllowAliases({
+        groups: accountGroups,
+        pathPrefix: `channels.zalouser.accounts.${accountId}.groups`,
+        changes,
+      });
+      if (!normalized.changed) {
+        continue;
+      }
+      nextAccounts[accountId] = {
+        ...account,
+        groups: normalized.groups,
+      };
+      accountsChanged = true;
+    }
+    if (accountsChanged) {
+      updatedZalouser = { ...updatedZalouser, accounts: nextAccounts };
+      changed = true;
+    }
+  }
+
+  if (!changed) {
+    return { config: cfg, changes: [] };
+  }
+
+  return {
+    config: {
+      ...cfg,
+      channels: {
+        ...cfg.channels,
+        zalouser: updatedZalouser as ZalouserChannelsConfig["zalouser"],
+      },
+    },
+    changes,
+  };
+}
+
+export const legacyConfigRules: ChannelDoctorLegacyConfigRule[] = [
+  {
+    path: ["channels", "zalouser", "groups"],
+    message:
+      'channels.zalouser.groups.<id>.allow is legacy; use channels.zalouser.groups.<id>.enabled instead. Run "openclaw doctor --fix".',
+    match: hasLegacyZalouserGroupAllowAliases,
+  },
+  {
+    path: ["channels", "zalouser", "accounts"],
+    message:
+      'channels.zalouser.accounts.<id>.groups.<id>.allow is legacy; use channels.zalouser.accounts.<id>.groups.<id>.enabled instead. Run "openclaw doctor --fix".',
+    match: hasLegacyZalouserAccountGroupAllowAliases,
+  },
+];
+
+export function normalizeCompatibilityConfig(params: {
+  cfg: OpenClawConfig;
+}): ChannelDoctorConfigMutation {
+  return normalizeZalouserCompatibilityConfig(params.cfg);
+}

package/src/doctor.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, it } from "vitest";
+import { zalouserDoctor } from "./doctor.js";
+
+describe("zalouser doctor", () => {
+  it("warns when mutable group names rely on disabled name matching", () => {
+    expect(
+      zalouserDoctor.collectMutableAllowlistWarnings?.({
+        cfg: {
+          channels: {
+            zalouser: {
+              groups: {
+                "group:trusted": {
+                  enabled: true,
+                },
+              },
+            },
+          },
+        } as never,
+      }),
+    ).toEqual(
+      expect.arrayContaining([
+        expect.stringContaining("mutable allowlist entry across zalouser"),
+        expect.stringContaining("channels.zalouser.groups: group:trusted"),
+      ]),
+    );
+  });
+
+  it("normalizes legacy group allow aliases to enabled", () => {
+    const normalize = zalouserDoctor.normalizeCompatibilityConfig;
+    expect(normalize).toBeDefined();
+    if (!normalize) {
+      return;
+    }
+
+    const result = normalize({
+      cfg: {
+        channels: {
+          zalouser: {
+            groups: {
+              "group:trusted": {
+                allow: true,
+              },
+            },
+            accounts: {
+              work: {
+                groups: {
+                  "group:legacy": {
+                    allow: false,
+                  },
+                },
+              },
+            },
+          },
+        },
+      } as never,
+    });
+
+    expect(result.config.channels?.zalouser?.groups?.["group:trusted"]).toEqual({
+      enabled: true,
+    });
+    expect(
+      (
+        result.config.channels?.zalouser?.accounts?.work as
+          | { groups?: Record<string, unknown> }
+          | undefined
+      )?.groups?.["group:legacy"],
+    ).toEqual({
+      enabled: false,
+    });
+    expect(result.changes).toEqual(
+      expect.arrayContaining([
+        "Moved channels.zalouser.groups.group:trusted.allow → channels.zalouser.groups.group:trusted.enabled (true).",
+        "Moved channels.zalouser.accounts.work.groups.group:legacy.allow → channels.zalouser.accounts.work.groups.group:legacy.enabled (false).",
+      ]),
+    );
+  });
+});

package/src/doctor.ts

@@ -0,0 +1,37 @@
+import type { ChannelDoctorAdapter } from "openclaw/plugin-sdk/channel-contract";
+import { createDangerousNameMatchingMutableAllowlistWarningCollector } from "openclaw/plugin-sdk/channel-policy";
+import { legacyConfigRules, normalizeCompatibilityConfig } from "./doctor-contract.js";
+import { isZalouserMutableGroupEntry } from "./security-audit.js";
+
+function asObjectRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+const collectZalouserMutableAllowlistWarnings =
+  createDangerousNameMatchingMutableAllowlistWarningCollector({
+    channel: "zalouser",
+    detector: isZalouserMutableGroupEntry,
+    collectLists: (scope) => {
+      const groups = asObjectRecord(scope.account.groups);
+      return groups
+        ? [
+            {
+              pathLabel: `${scope.prefix}.groups`,
+              list: Object.keys(groups),
+            },
+          ]
+        : [];
+    },
+  });
+
+export const zalouserDoctor: ChannelDoctorAdapter = {
+  dmAllowFromMode: "topOnly",
+  groupModel: "hybrid",
+  groupAllowFromFallbackToAllowFrom: false,
+  warnOnEmptyGroupSenderAllowlist: false,
+  legacyConfigRules,
+  normalizeCompatibilityConfig,
+  collectMutableAllowlistWarnings: collectZalouserMutableAllowlistWarnings,
+};

package/src/group-policy.test.ts

@@ -37,7 +37,7 @@ describe("zalouser group policy helpers", () => {
 
   it("finds the first matching group entry", () => {
     const groups = {
-      "group:123": { allow: true },
+      "group:123": { enabled: true },
       "team-alpha": { requireMention: false },
       "*": { requireMention: true },
     };
@@ -49,12 +49,12 @@ describe("zalouser group policy helpers", () => {
         includeGroupIdAlias: true,
       }),
     );
-    expect(entry).toEqual({ allow: true });
+    expect(entry).toEqual({ enabled: true });
   });
 
   it("evaluates allow/enable flags", () => {
-    expect(isZalouserGroupEntryAllowed({ allow: true, enabled: true })).toBe(true);
-    expect(isZalouserGroupEntryAllowed({ allow: false })).toBe(false);
+    expect(isZalouserGroupEntryAllowed({ enabled: true })).toBe(true);
+    expect(isZalouserGroupEntryAllowed({ allow: false } as never)).toBe(false);
     expect(isZalouserGroupEntryAllowed({ enabled: false })).toBe(false);
     expect(isZalouserGroupEntryAllowed(undefined)).toBe(false);
   });

package/src/group-policy.ts

@@ -1,3 +1,4 @@
+import { normalizeOptionalLowercaseString } from "openclaw/plugin-sdk/text-runtime";
 import type { ZalouserGroupConfig } from "./types.js";
 
 type ZalouserGroups = Record<string, ZalouserGroupConfig>;
@@ -7,7 +8,7 @@ function toGroupCandidate(value?: string | null): string {
 }
 
 export function normalizeZalouserGroupSlug(raw?: string | null): string {
-  const trimmed = raw?.trim().toLowerCase() ?? "";
+  const trimmed = normalizeOptionalLowercaseString(raw) ?? "";
   if (!trimmed) {
     return "";
   }
@@ -77,5 +78,6 @@ export function isZalouserGroupEntryAllowed(entry: ZalouserGroupConfig | undefin
   if (!entry) {
     return false;
   }
-  return entry.allow !== false && entry.enabled !== false;
+  const legacyAllow = (entry as ZalouserGroupConfig & { allow?: unknown }).allow;
+  return legacyAllow !== false && entry.enabled !== false;
 }

package/src/monitor.account-scope.test.ts

@@ -1,9 +1,11 @@
-import type { OpenClawConfig, PluginRuntime, RuntimeEnv } from "openclaw/plugin-sdk/zalouser";
 import { describe, expect, it, vi } from "vitest";
+import type { OpenClawConfig, PluginRuntime } from "../runtime-api.js";
 import "./monitor.send-mocks.js";
 import { __testing } from "./monitor.js";
+import "./zalo-js.test-mocks.js";
 import { sendMessageZalouserMock } from "./monitor.send-mocks.js";
 import { setZalouserRuntime } from "./runtime.js";
+import { createZalouserRuntimeEnv } from "./test-helpers.js";
 import type { ResolvedZalouserAccount, ZaloInboundMessage } from "./types.js";
 
 describe("zalouser monitor pairing account scoping", () => {
@@ -80,19 +82,11 @@ describe("zalouser monitor pairing account scoping", () => {
       raw: { source: "test" },
     };
 
-    const runtime: RuntimeEnv = {
-      log: vi.fn(),
-      error: vi.fn(),
-      exit: ((code: number): never => {
-        throw new Error(`exit ${code}`);
-      }) as RuntimeEnv["exit"],
-    };
-
     await __testing.processMessage({
       message,
       account,
       config,
-      runtime,
+      runtime: createZalouserRuntimeEnv(),
     });
 
     expect(readAllowFromStore).toHaveBeenCalledWith(