@kodelyth/zalouser 2026.5.39 → 2026.5.42

package/src/directory.ts

@@ -0,0 +1,54 @@
+import { resolveZalouserAccountSync } from "./accounts.js";
+import type { ChannelDirectoryEntry, KlawConfig } 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: KlawConfig;
+    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 "klaw/plugin-sdk/channel-contract";
+import type { KlawConfig } from "klaw/plugin-sdk/config-contracts";
+
+type ZalouserChannelsConfig = NonNullable<KlawConfig["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: KlawConfig): 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 "klaw 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 "klaw doctor --fix".',
+    match: hasLegacyZalouserAccountGroupAllowAliases,
+  },
+];
+
+export function normalizeCompatibilityConfig(params: {
+  cfg: KlawConfig;
+}): ChannelDoctorConfigMutation {
+  return normalizeZalouserCompatibilityConfig(params.cfg);
+}

package/src/doctor.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it } from "vitest";
+import { zalouserDoctor } from "./doctor.js";
+
+function getZaloUserCompatibilityNormalizer(): NonNullable<
+  typeof zalouserDoctor.normalizeCompatibilityConfig
+> {
+  const normalize = zalouserDoctor.normalizeCompatibilityConfig;
+  if (!normalize) {
+    throw new Error("Expected zalouser doctor to expose normalizeCompatibilityConfig");
+  }
+  return normalize;
+}
+
+describe("zalouser doctor", () => {
+  it("warns when mutable group names rely on disabled name matching", async () => {
+    const warnings = await Promise.resolve(
+      zalouserDoctor.collectMutableAllowlistWarnings?.({
+        cfg: {
+          channels: {
+            zalouser: {
+              groups: {
+                "group:trusted": {
+                  enabled: true,
+                },
+              },
+            },
+          },
+        } as never,
+      }) ?? [],
+    );
+
+    expect(
+      warnings.some((warning: string) =>
+        warning.includes("mutable allowlist entry across zalouser"),
+      ),
+    ).toBe(true);
+    expect(
+      warnings.some((warning: string) =>
+        warning.includes("channels.zalouser.groups: group:trusted"),
+      ),
+    ).toBe(true);
+  });
+
+  it("normalizes legacy group allow aliases to enabled", () => {
+    const normalize = getZaloUserCompatibilityNormalizer();
+
+    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([
+      "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 "klaw/plugin-sdk/channel-contract";
+import { createDangerousNameMatchingMutableAllowlistWarningCollector } from "klaw/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

@@ -0,0 +1,61 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildZalouserGroupCandidates,
+  findZalouserGroupEntry,
+  isZalouserGroupEntryAllowed,
+  normalizeZalouserGroupSlug,
+} from "./group-policy.js";
+
+describe("zalouser group policy helpers", () => {
+  it("normalizes group slug names", () => {
+    expect(normalizeZalouserGroupSlug(" Team Alpha ")).toBe("team-alpha");
+    expect(normalizeZalouserGroupSlug("#Roadmap Updates")).toBe("roadmap-updates");
+  });
+
+  it("builds ordered candidates with optional aliases", () => {
+    expect(
+      buildZalouserGroupCandidates({
+        groupId: "123",
+        groupChannel: "chan-1",
+        groupName: "Team Alpha",
+        includeGroupIdAlias: true,
+      }),
+    ).toEqual(["123", "group:123", "chan-1", "Team Alpha", "team-alpha", "*"]);
+  });
+
+  it("builds id-only candidates when name matching is disabled", () => {
+    expect(
+      buildZalouserGroupCandidates({
+        groupId: "123",
+        groupChannel: "chan-1",
+        groupName: "Team Alpha",
+        includeGroupIdAlias: true,
+        allowNameMatching: false,
+      }),
+    ).toEqual(["123", "group:123", "*"]);
+  });
+
+  it("finds the first matching group entry", () => {
+    const groups = {
+      "group:123": { enabled: true },
+      "team-alpha": { requireMention: false },
+      "*": { requireMention: true },
+    };
+    const entry = findZalouserGroupEntry(
+      groups,
+      buildZalouserGroupCandidates({
+        groupId: "123",
+        groupName: "Team Alpha",
+        includeGroupIdAlias: true,
+      }),
+    );
+    expect(entry).toEqual({ enabled: true });
+  });
+
+  it("evaluates allow/enable flags", () => {
+    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

@@ -0,0 +1,83 @@
+import { normalizeOptionalLowercaseString } from "klaw/plugin-sdk/string-coerce-runtime";
+import type { ZalouserGroupConfig } from "./types.js";
+
+type ZalouserGroups = Record<string, ZalouserGroupConfig>;
+
+function toGroupCandidate(value?: string | null): string {
+  return value?.trim() ?? "";
+}
+
+export function normalizeZalouserGroupSlug(raw?: string | null): string {
+  const trimmed = normalizeOptionalLowercaseString(raw) ?? "";
+  if (!trimmed) {
+    return "";
+  }
+  return trimmed
+    .replace(/^#/, "")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+export function buildZalouserGroupCandidates(params: {
+  groupId?: string | null;
+  groupChannel?: string | null;
+  groupName?: string | null;
+  includeGroupIdAlias?: boolean;
+  includeWildcard?: boolean;
+  allowNameMatching?: boolean;
+}): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  const push = (value?: string | null) => {
+    const normalized = toGroupCandidate(value);
+    if (!normalized || seen.has(normalized)) {
+      return;
+    }
+    seen.add(normalized);
+    out.push(normalized);
+  };
+
+  const groupId = toGroupCandidate(params.groupId);
+  const groupChannel = toGroupCandidate(params.groupChannel);
+  const groupName = toGroupCandidate(params.groupName);
+
+  push(groupId);
+  if (params.includeGroupIdAlias === true && groupId) {
+    push(`group:${groupId}`);
+  }
+  if (params.allowNameMatching !== false) {
+    push(groupChannel);
+    push(groupName);
+    if (groupName) {
+      push(normalizeZalouserGroupSlug(groupName));
+    }
+  }
+  if (params.includeWildcard !== false) {
+    push("*");
+  }
+  return out;
+}
+
+export function findZalouserGroupEntry(
+  groups: ZalouserGroups | undefined,
+  candidates: string[],
+): ZalouserGroupConfig | undefined {
+  if (!groups) {
+    return undefined;
+  }
+  for (const candidate of candidates) {
+    const entry = groups[candidate];
+    if (entry) {
+      return entry;
+    }
+  }
+  return undefined;
+}
+
+export function isZalouserGroupEntryAllowed(entry: ZalouserGroupConfig | undefined): boolean {
+  if (!entry) {
+    return false;
+  }
+  const legacyAllow = (entry as ZalouserGroupConfig & { allow?: unknown }).allow;
+  return legacyAllow !== false && entry.enabled !== false;
+}

package/src/message-sid.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from "vitest";
+import {
+  formatZalouserMessageSidFull,
+  parseZalouserMessageSidFull,
+  resolveZalouserMessageSid,
+  resolveZalouserReactionMessageIds,
+} from "./message-sid.js";
+
+describe("zalouser message sid helpers", () => {
+  it("parses MessageSidFull pairs", () => {
+    expect(parseZalouserMessageSidFull("111:222")).toEqual({
+      msgId: "111",
+      cliMsgId: "222",
+    });
+    expect(parseZalouserMessageSidFull("111")).toBeNull();
+    expect(parseZalouserMessageSidFull(undefined)).toBeNull();
+  });
+
+  it("resolves reaction ids from explicit params first", () => {
+    expect(
+      resolveZalouserReactionMessageIds({
+        messageId: "m-1",
+        cliMsgId: "c-1",
+        currentMessageId: "x:y",
+      }),
+    ).toEqual({
+      msgId: "m-1",
+      cliMsgId: "c-1",
+    });
+  });
+
+  it("resolves reaction ids from current message sid full", () => {
+    expect(
+      resolveZalouserReactionMessageIds({
+        currentMessageId: "m-2:c-2",
+      }),
+    ).toEqual({
+      msgId: "m-2",
+      cliMsgId: "c-2",
+    });
+  });
+
+  it("falls back to duplicated current id when no pair is available", () => {
+    expect(
+      resolveZalouserReactionMessageIds({
+        currentMessageId: "solo",
+      }),
+    ).toEqual({
+      msgId: "solo",
+      cliMsgId: "solo",
+    });
+  });
+
+  it("formats message sid fields for context payload", () => {
+    expect(formatZalouserMessageSidFull({ msgId: "1", cliMsgId: "2" })).toBe("1:2");
+    expect(formatZalouserMessageSidFull({ msgId: "1" })).toBe("1");
+    expect(formatZalouserMessageSidFull({ cliMsgId: "2" })).toBe("2");
+    expect(formatZalouserMessageSidFull({})).toBeUndefined();
+  });
+
+  it("resolves primary message sid with fallback timestamp", () => {
+    expect(resolveZalouserMessageSid({ msgId: "1", cliMsgId: "2", fallback: "t" })).toBe("1");
+    expect(resolveZalouserMessageSid({ cliMsgId: "2", fallback: "t" })).toBe("2");
+    expect(resolveZalouserMessageSid({ fallback: "t" })).toBe("t");
+  });
+});

package/src/message-sid.ts

@@ -0,0 +1,80 @@
+function toMessageSidPart(value?: string | number | null): string {
+  if (typeof value === "string") {
+    return value.trim();
+  }
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return String(Math.trunc(value));
+  }
+  return "";
+}
+
+export function parseZalouserMessageSidFull(
+  value?: string | number | null,
+): { msgId: string; cliMsgId: string } | null {
+  const raw = toMessageSidPart(value);
+  if (!raw) {
+    return null;
+  }
+  const [msgIdPart, cliMsgIdPart] = raw.split(":").map((entry) => entry.trim());
+  if (!msgIdPart || !cliMsgIdPart) {
+    return null;
+  }
+  return { msgId: msgIdPart, cliMsgId: cliMsgIdPart };
+}
+
+export function resolveZalouserReactionMessageIds(params: {
+  messageId?: string;
+  cliMsgId?: string;
+  currentMessageId?: string | number;
+}): { msgId: string; cliMsgId: string } | null {
+  const explicitMessageId = toMessageSidPart(params.messageId);
+  const explicitCliMsgId = toMessageSidPart(params.cliMsgId);
+  if (explicitMessageId && explicitCliMsgId) {
+    return { msgId: explicitMessageId, cliMsgId: explicitCliMsgId };
+  }
+
+  const parsedFromCurrent = parseZalouserMessageSidFull(params.currentMessageId);
+  if (parsedFromCurrent) {
+    return parsedFromCurrent;
+  }
+
+  const currentRaw = toMessageSidPart(params.currentMessageId);
+  if (!currentRaw) {
+    return null;
+  }
+  if (explicitMessageId && !explicitCliMsgId) {
+    return { msgId: explicitMessageId, cliMsgId: currentRaw };
+  }
+  if (!explicitMessageId && explicitCliMsgId) {
+    return { msgId: currentRaw, cliMsgId: explicitCliMsgId };
+  }
+  return { msgId: currentRaw, cliMsgId: currentRaw };
+}
+
+export function formatZalouserMessageSidFull(params: {
+  msgId?: string | null;
+  cliMsgId?: string | null;
+}): string | undefined {
+  const msgId = toMessageSidPart(params.msgId);
+  const cliMsgId = toMessageSidPart(params.cliMsgId);
+  if (!msgId && !cliMsgId) {
+    return undefined;
+  }
+  if (msgId && cliMsgId) {
+    return `${msgId}:${cliMsgId}`;
+  }
+  return msgId || cliMsgId || undefined;
+}
+
+export function resolveZalouserMessageSid(params: {
+  msgId?: string | null;
+  cliMsgId?: string | null;
+  fallback?: string | null;
+}): string | undefined {
+  const msgId = toMessageSidPart(params.msgId);
+  const cliMsgId = toMessageSidPart(params.cliMsgId);
+  if (msgId || cliMsgId) {
+    return msgId || cliMsgId;
+  }
+  return toMessageSidPart(params.fallback) || undefined;
+}