@kodelyth/zalouser 2026.5.39 → 2026.5.42

package/src/probe.test.ts

@@ -0,0 +1,60 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { probeZalouser } from "./probe.js";
+import { getZaloUserInfo } from "./zalo-js.js";
+
+vi.mock("./zalo-js.js", () => ({
+  getZaloUserInfo: vi.fn(),
+}));
+
+const mockGetUserInfo = vi.mocked(getZaloUserInfo);
+
+describe("probeZalouser", () => {
+  beforeEach(() => {
+    mockGetUserInfo.mockReset();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("returns ok=true with user when authenticated", async () => {
+    mockGetUserInfo.mockResolvedValueOnce({
+      userId: "123",
+      displayName: "Alice",
+    });
+
+    await expect(probeZalouser("default")).resolves.toEqual({
+      ok: true,
+      user: { userId: "123", displayName: "Alice" },
+    });
+  });
+
+  it("returns not authenticated when no user info is returned", async () => {
+    mockGetUserInfo.mockResolvedValueOnce(null);
+    await expect(probeZalouser("default")).resolves.toEqual({
+      ok: false,
+      error: "Not authenticated",
+    });
+  });
+
+  it("returns error when user lookup throws", async () => {
+    mockGetUserInfo.mockRejectedValueOnce(new Error("network down"));
+    await expect(probeZalouser("default")).resolves.toEqual({
+      ok: false,
+      error: "network down",
+    });
+  });
+
+  it("times out when lookup takes too long", async () => {
+    vi.useFakeTimers();
+    mockGetUserInfo.mockReturnValueOnce(new Promise(() => undefined));
+
+    const pending = probeZalouser("default", 10);
+    await vi.advanceTimersByTimeAsync(1000);
+
+    await expect(pending).resolves.toEqual({
+      ok: false,
+      error: "Not authenticated",
+    });
+  });
+});

package/src/probe.ts

@@ -0,0 +1,35 @@
+import type { BaseProbeResult } from "klaw/plugin-sdk/channel-contract";
+import { formatErrorMessage } from "klaw/plugin-sdk/error-runtime";
+import type { ZcaUserInfo } from "./types.js";
+import { getZaloUserInfo } from "./zalo-js.js";
+
+export type ZalouserProbeResult = BaseProbeResult<string> & {
+  user?: ZcaUserInfo;
+};
+
+export async function probeZalouser(
+  profile: string,
+  timeoutMs?: number,
+): Promise<ZalouserProbeResult> {
+  try {
+    const user = timeoutMs
+      ? await Promise.race([
+          getZaloUserInfo(profile),
+          new Promise<null>((resolve) =>
+            setTimeout(() => resolve(null), Math.max(timeoutMs, 1000)),
+          ),
+        ])
+      : await getZaloUserInfo(profile);
+
+    if (!user) {
+      return { ok: false, error: "Not authenticated" };
+    }
+
+    return { ok: true, user };
+  } catch (error) {
+    return {
+      ok: false,
+      error: formatErrorMessage(error),
+    };
+  }
+}

package/src/qr-temp-file.ts

@@ -0,0 +1,19 @@
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { resolvePreferredKlawTmpDir } from "klaw/plugin-sdk/temp-path";
+
+export async function writeQrDataUrlToTempFile(
+  qrDataUrl: string,
+  profile: string,
+): Promise<string | null> {
+  const trimmed = qrDataUrl.trim();
+  const match = trimmed.match(/^data:image\/png;base64,(.+)$/i);
+  const base64 = (match?.[1] ?? "").trim();
+  if (!base64) {
+    return null;
+  }
+  const safeProfile = profile.replace(/[^a-zA-Z0-9_-]+/g, "-") || "default";
+  const filePath = path.join(resolvePreferredKlawTmpDir(), `klaw-zalouser-qr-${safeProfile}.png`);
+  await fsp.writeFile(filePath, Buffer.from(base64, "base64"));
+  return filePath;
+}

package/src/reaction.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from "vitest";
+import { normalizeZaloReactionIcon } from "./reaction.js";
+
+describe("zalouser reaction alias normalization", () => {
+  it("maps common aliases", () => {
+    expect(normalizeZaloReactionIcon("like")).toBe("/-strong");
+    expect(normalizeZaloReactionIcon("👍")).toBe("/-strong");
+    expect(normalizeZaloReactionIcon("heart")).toBe("/-heart");
+    expect(normalizeZaloReactionIcon("😂")).toBe(":>");
+  });
+
+  it("defaults empty icon to like", () => {
+    expect(normalizeZaloReactionIcon("")).toBe("/-strong");
+  });
+
+  it("passes through unknown custom reactions", () => {
+    expect(normalizeZaloReactionIcon("/custom")).toBe("/custom");
+  });
+});

package/src/reaction.ts

@@ -0,0 +1,32 @@
+import { normalizeLowercaseStringOrEmpty } from "klaw/plugin-sdk/string-coerce-runtime";
+import { Reactions } from "./zca-constants.js";
+
+const REACTION_ALIAS_MAP = new Map<string, string>([
+  ["like", Reactions.LIKE],
+  ["👍", Reactions.LIKE],
+  [":+1:", Reactions.LIKE],
+  ["heart", Reactions.HEART],
+  ["❤️", Reactions.HEART],
+  ["<3", Reactions.HEART],
+  ["haha", Reactions.HAHA],
+  ["laugh", Reactions.HAHA],
+  ["😂", Reactions.HAHA],
+  ["wow", Reactions.WOW],
+  ["😮", Reactions.WOW],
+  ["cry", Reactions.CRY],
+  ["😢", Reactions.CRY],
+  ["angry", Reactions.ANGRY],
+  ["😡", Reactions.ANGRY],
+]);
+
+export function normalizeZaloReactionIcon(raw: string): string {
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    return Reactions.LIKE;
+  }
+  return (
+    REACTION_ALIAS_MAP.get(normalizeLowercaseStringOrEmpty(trimmed)) ??
+    REACTION_ALIAS_MAP.get(trimmed) ??
+    trimmed
+  );
+}

package/src/runtime.ts

@@ -0,0 +1,9 @@
+import type { PluginRuntime } from "klaw/plugin-sdk/core";
+import { createPluginRuntimeStore } from "klaw/plugin-sdk/runtime-store";
+
+const { setRuntime: setZalouserRuntime, getRuntime: getZalouserRuntime } =
+  createPluginRuntimeStore<PluginRuntime>({
+    pluginId: "zalouser",
+    errorMessage: "Zalouser runtime not initialized",
+  });
+export { getZalouserRuntime, setZalouserRuntime };

package/src/security-audit.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from "vitest";
+import { collectZalouserSecurityAuditFindings } from "./security-audit.js";
+import type { ResolvedZalouserAccount, ZalouserAccountConfig } from "./types.js";
+
+function createAccount(config: ZalouserAccountConfig): ResolvedZalouserAccount {
+  return {
+    accountId: "default",
+    enabled: true,
+    profile: "default",
+    authenticated: true,
+    config,
+  };
+}
+
+describe("Zalouser security audit findings", () => {
+  const cases: Array<{
+    name: string;
+    config: ZalouserAccountConfig;
+    expectedSeverity: "info" | "warn";
+    expectedTitle: string;
+    expectedRemediation: string;
+    detailIncludes: string[];
+    detailExcludes?: string[];
+  }> = [
+    {
+      name: "warns when group routing contains mutable group entries",
+      config: {
+        enabled: true,
+        groups: {
+          "Ops Room": { enabled: true },
+          "group:g-123": { enabled: true },
+        },
+      } satisfies ZalouserAccountConfig,
+      expectedSeverity: "warn",
+      expectedTitle: "Zalouser group routing contains mutable group entries",
+      expectedRemediation:
+        "Prefer stable Zalo group IDs in channels.zalouser.groups, or explicitly opt in with dangerouslyAllowNameMatching=true if you accept mutable group-name matching.",
+      detailIncludes: ["channels.zalouser.groups:Ops Room"],
+      detailExcludes: ["group:g-123"],
+    },
+    {
+      name: "marks mutable group routing as break-glass when dangerous matching is enabled",
+      config: {
+        enabled: true,
+        dangerouslyAllowNameMatching: true,
+        groups: {
+          "Ops Room": { enabled: true },
+        },
+      } satisfies ZalouserAccountConfig,
+      expectedSeverity: "info",
+      expectedTitle: "Zalouser group routing uses break-glass name matching",
+      expectedRemediation:
+        "Prefer stable Zalo group IDs (for example group:<id> or provider-native g- ids), then disable dangerouslyAllowNameMatching.",
+      detailIncludes: ["out-of-scope"],
+    },
+  ];
+
+  it.each(cases)("$name", (testCase) => {
+    const findings = collectZalouserSecurityAuditFindings({
+      account: createAccount(testCase.config),
+      accountId: "default",
+      orderedAccountIds: ["default"],
+      hasExplicitAccountPath: false,
+    });
+    const finding = findings.find(
+      (entry) => entry.checkId === "channels.zalouser.groups.mutable_entries",
+    );
+
+    if (!finding) {
+      throw new Error("expected mutable Zalo User group finding");
+    }
+    expect(finding.checkId).toBe("channels.zalouser.groups.mutable_entries");
+    expect(finding.severity).toBe(testCase.expectedSeverity);
+    expect(finding.title).toBe(testCase.expectedTitle);
+    expect(finding.remediation).toBe(testCase.expectedRemediation);
+    for (const snippet of testCase.detailIncludes) {
+      expect(finding.detail).toContain(snippet);
+    }
+    for (const snippet of testCase.detailExcludes ?? []) {
+      expect(finding.detail).not.toContain(snippet);
+    }
+  });
+});

package/src/security-audit.ts

@@ -0,0 +1,71 @@
+import { isDangerousNameMatchingEnabled } from "klaw/plugin-sdk/dangerous-name-runtime";
+import type { ResolvedZalouserAccount } from "./accounts.js";
+
+export function isZalouserMutableGroupEntry(raw: string): boolean {
+  const text = raw.trim();
+  if (!text || text === "*") {
+    return false;
+  }
+  const normalized = text
+    .replace(/^(zalouser|zlu):/i, "")
+    .replace(/^group:/i, "")
+    .trim();
+  if (!normalized) {
+    return false;
+  }
+  if (/^\d+$/.test(normalized)) {
+    return false;
+  }
+  return !/^g-\S+$/i.test(normalized);
+}
+
+export function collectZalouserSecurityAuditFindings(params: {
+  accountId?: string | null;
+  account: ResolvedZalouserAccount;
+  orderedAccountIds: string[];
+  hasExplicitAccountPath: boolean;
+}) {
+  const zalouserCfg = params.account.config ?? {};
+  const accountId = params.accountId?.trim() || params.account.accountId || "default";
+  const dangerousNameMatchingEnabled = isDangerousNameMatchingEnabled(zalouserCfg);
+  const zalouserPathPrefix =
+    params.orderedAccountIds.length > 1 || params.hasExplicitAccountPath
+      ? `channels.zalouser.accounts.${accountId}`
+      : "channels.zalouser";
+  const mutableGroupEntries = new Set<string>();
+  const groups = zalouserCfg.groups;
+  if (groups && typeof groups === "object" && !Array.isArray(groups)) {
+    for (const key of Object.keys(groups as Record<string, unknown>)) {
+      if (!isZalouserMutableGroupEntry(key)) {
+        continue;
+      }
+      mutableGroupEntries.add(`${zalouserPathPrefix}.groups:${key}`);
+    }
+  }
+  if (mutableGroupEntries.size === 0) {
+    return [];
+  }
+  const examples = Array.from(mutableGroupEntries).slice(0, 5);
+  const more =
+    mutableGroupEntries.size > examples.length
+      ? ` (+${mutableGroupEntries.size - examples.length} more)`
+      : "";
+  const severity: "info" | "warn" = dangerousNameMatchingEnabled ? "info" : "warn";
+  return [
+    {
+      checkId: "channels.zalouser.groups.mutable_entries",
+      severity,
+      title: dangerousNameMatchingEnabled
+        ? "Zalouser group routing uses break-glass name matching"
+        : "Zalouser group routing contains mutable group entries",
+      detail: dangerousNameMatchingEnabled
+        ? "Zalouser group-name routing is explicitly enabled via dangerouslyAllowNameMatching. This mutable-identity mode is operator-selected break-glass behavior and out-of-scope for vulnerability reports by itself. " +
+          `Found: ${examples.join(", ")}${more}.`
+        : "Zalouser group auth is ID-only by default, so unresolved group-name or slug entries are ignored for auth and can drift from the intended trusted group. " +
+          `Found: ${examples.join(", ")}${more}.`,
+      remediation: dangerousNameMatchingEnabled
+        ? "Prefer stable Zalo group IDs (for example group:<id> or provider-native g- ids), then disable dangerouslyAllowNameMatching."
+        : "Prefer stable Zalo group IDs in channels.zalouser.groups, or explicitly opt in with dangerouslyAllowNameMatching=true if you accept mutable group-name matching.",
+    },
+  ];
+}

package/src/send-receipt.ts

@@ -0,0 +1,31 @@
+import {
+  createMessageReceiptFromOutboundResults,
+  type MessageReceipt,
+  type MessageReceiptPartKind,
+} from "klaw/plugin-sdk/channel-message";
+
+export function createZalouserSendReceipt(params: {
+  messageId?: string;
+  platformMessageIds?: readonly (string | null | undefined)[];
+  threadId?: string;
+  kind?: MessageReceiptPartKind;
+}): MessageReceipt {
+  const platformMessageIds = (params.platformMessageIds ?? [params.messageId])
+    .map((messageId) => messageId?.trim())
+    .filter((messageId): messageId is string => Boolean(messageId));
+  const threadId = params.threadId?.trim();
+  return createMessageReceiptFromOutboundResults({
+    results: platformMessageIds.map((messageId) => {
+      const result: { channel: string; messageId: string; conversationId?: string } = {
+        channel: "zalouser",
+        messageId,
+      };
+      if (threadId) {
+        result.conversationId = threadId;
+      }
+      return result;
+    }),
+    ...(threadId ? { threadId } : {}),
+    kind: params.kind ?? "unknown",
+  });
+}