@archipelagolab/lobi 1.0.0

package/src/matrix/monitor/access-state.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest";
+import { resolveMatrixMonitorAccessState } from "./access-state.js";
+
+describe("resolveMatrixMonitorAccessState", () => {
+  it("normalizes effective allowlists once and exposes reusable matches", () => {
+    const state = resolveMatrixMonitorAccessState({
+      allowFrom: ["matrix:@Alice:Example.org"],
+      storeAllowFrom: ["user:@bob:example.org"],
+      groupAllowFrom: ["@Carol:Example.org"],
+      roomUsers: ["user:@Dana:Example.org"],
+      senderId: "@dana:example.org",
+      isRoom: true,
+    });
+
+    expect(state.effectiveAllowFrom).toEqual([
+      "matrix:@alice:example.org",
+      "user:@bob:example.org",
+    ]);
+    expect(state.effectiveGroupAllowFrom).toEqual(["@carol:example.org"]);
+    expect(state.effectiveRoomUsers).toEqual(["user:@dana:example.org"]);
+    expect(state.directAllowMatch.allowed).toBe(false);
+    expect(state.roomUserMatch?.allowed).toBe(true);
+    expect(state.groupAllowMatch?.allowed).toBe(false);
+    expect(state.commandAuthorizers).toEqual([
+      { configured: true, allowed: false },
+      { configured: true, allowed: true },
+      { configured: true, allowed: false },
+    ]);
+  });
+
+  it("keeps room-user matching disabled for dm traffic", () => {
+    const state = resolveMatrixMonitorAccessState({
+      allowFrom: [],
+      storeAllowFrom: [],
+      groupAllowFrom: ["@carol:example.org"],
+      roomUsers: ["@dana:example.org"],
+      senderId: "@dana:example.org",
+      isRoom: false,
+    });
+
+    expect(state.roomUserMatch).toBeNull();
+    expect(state.commandAuthorizers[1]).toEqual({ configured: true, allowed: false });
+    expect(state.commandAuthorizers[2]).toEqual({ configured: true, allowed: false });
+  });
+});

package/src/matrix/monitor/access-state.ts

@@ -0,0 +1,77 @@
+import { normalizeMatrixAllowList, resolveMatrixAllowListMatch } from "./allowlist.js";
+import type { MatrixAllowListMatch } from "./allowlist.js";
+
+type MatrixCommandAuthorizer = {
+  configured: boolean;
+  allowed: boolean;
+};
+
+export type MatrixMonitorAccessState = {
+  effectiveAllowFrom: string[];
+  effectiveGroupAllowFrom: string[];
+  effectiveRoomUsers: string[];
+  groupAllowConfigured: boolean;
+  directAllowMatch: MatrixAllowListMatch;
+  roomUserMatch: MatrixAllowListMatch | null;
+  groupAllowMatch: MatrixAllowListMatch | null;
+  commandAuthorizers: [MatrixCommandAuthorizer, MatrixCommandAuthorizer, MatrixCommandAuthorizer];
+};
+
+export function resolveMatrixMonitorAccessState(params: {
+  allowFrom: Array<string | number>;
+  storeAllowFrom: Array<string | number>;
+  groupAllowFrom: Array<string | number>;
+  roomUsers: Array<string | number>;
+  senderId: string;
+  isRoom: boolean;
+}): MatrixMonitorAccessState {
+  const effectiveAllowFrom = normalizeMatrixAllowList([
+    ...params.allowFrom,
+    ...params.storeAllowFrom,
+  ]);
+  const effectiveGroupAllowFrom = normalizeMatrixAllowList(params.groupAllowFrom);
+  const effectiveRoomUsers = normalizeMatrixAllowList(params.roomUsers);
+
+  const directAllowMatch = resolveMatrixAllowListMatch({
+    allowList: effectiveAllowFrom,
+    userId: params.senderId,
+  });
+  const roomUserMatch =
+    params.isRoom && effectiveRoomUsers.length > 0
+      ? resolveMatrixAllowListMatch({
+          allowList: effectiveRoomUsers,
+          userId: params.senderId,
+        })
+      : null;
+  const groupAllowMatch =
+    effectiveGroupAllowFrom.length > 0
+      ? resolveMatrixAllowListMatch({
+          allowList: effectiveGroupAllowFrom,
+          userId: params.senderId,
+        })
+      : null;
+
+  return {
+    effectiveAllowFrom,
+    effectiveGroupAllowFrom,
+    effectiveRoomUsers,
+    groupAllowConfigured: effectiveGroupAllowFrom.length > 0,
+    directAllowMatch,
+    roomUserMatch,
+    groupAllowMatch,
+    commandAuthorizers: [
+      {
+        configured: effectiveAllowFrom.length > 0,
+        allowed: directAllowMatch.allowed,
+      },
+      {
+        configured: effectiveRoomUsers.length > 0,
+        allowed: roomUserMatch?.allowed ?? false,
+      },
+      {
+        configured: effectiveGroupAllowFrom.length > 0,
+        allowed: groupAllowMatch?.allowed ?? false,
+      },
+    ],
+  };
+}

package/src/matrix/monitor/ack-config.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from "vitest";
+import { resolveMatrixAckReactionConfig } from "./ack-config.js";
+
+describe("resolveMatrixAckReactionConfig", () => {
+  it("prefers account-level ack reaction and scope overrides", () => {
+    expect(
+      resolveMatrixAckReactionConfig({
+        cfg: {
+          messages: {
+            ackReaction: "👀",
+            ackReactionScope: "all",
+          },
+          channels: {
+            matrix: {
+              ackReaction: "✅",
+              ackReactionScope: "group-all",
+              accounts: {
+                ops: {
+                  ackReaction: "🟢",
+                  ackReactionScope: "direct",
+                },
+              },
+            },
+          },
+        },
+        agentId: "ops-agent",
+        accountId: "ops",
+      }),
+    ).toEqual({
+      ackReaction: "🟢",
+      ackReactionScope: "direct",
+    });
+  });
+
+  it("falls back to channel then global settings", () => {
+    expect(
+      resolveMatrixAckReactionConfig({
+        cfg: {
+          messages: {
+            ackReaction: "👀",
+            ackReactionScope: "all",
+          },
+          channels: {
+            matrix: {
+              ackReaction: "✅",
+            },
+          },
+        },
+        agentId: "ops-agent",
+        accountId: "missing",
+      }),
+    ).toEqual({
+      ackReaction: "✅",
+      ackReactionScope: "all",
+    });
+  });
+});

package/src/matrix/monitor/ack-config.ts

@@ -0,0 +1,26 @@
+import type { CoreConfig } from "../../types.js";
+import { resolveMatrixAccountConfig } from "../account-config.js";
+import { resolveAckReaction, type OpenClawConfig } from "./runtime-api.js";
+
+type MatrixAckReactionScope = "group-mentions" | "group-all" | "direct" | "all" | "none" | "off";
+
+export function resolveMatrixAckReactionConfig(params: {
+  cfg: OpenClawConfig;
+  agentId: string;
+  accountId?: string | null;
+}): { ackReaction: string; ackReactionScope: MatrixAckReactionScope } {
+  const matrixConfig = params.cfg.channels?.matrix;
+  const accountConfig = resolveMatrixAccountConfig({
+    cfg: params.cfg as CoreConfig,
+    accountId: params.accountId,
+  });
+  const ackReaction = resolveAckReaction(params.cfg, params.agentId, {
+    channel: "matrix",
+    accountId: params.accountId ?? undefined,
+  }).trim();
+  const ackReactionScope = (accountConfig.ackReactionScope ??
+    matrixConfig?.ackReactionScope ??
+    params.cfg.messages?.ackReactionScope ??
+    "group-mentions") as MatrixAckReactionScope;
+  return { ackReaction, ackReactionScope };
+}

package/src/matrix/monitor/allowlist.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest";
+import { normalizeMatrixAllowList, resolveMatrixAllowListMatch } from "./allowlist.js";
+
+describe("resolveMatrixAllowListMatch", () => {
+  it("matches full user IDs and prefixes", () => {
+    const userId = "@Alice:Example.org";
+    const direct = resolveMatrixAllowListMatch({
+      allowList: normalizeMatrixAllowList(["@alice:example.org"]),
+      userId,
+    });
+    expect(direct.allowed).toBe(true);
+    expect(direct.matchSource).toBe("id");
+
+    const prefixedMatrix = resolveMatrixAllowListMatch({
+      allowList: normalizeMatrixAllowList(["matrix:@alice:example.org"]),
+      userId,
+    });
+    expect(prefixedMatrix.allowed).toBe(true);
+    expect(prefixedMatrix.matchSource).toBe("prefixed-id");
+
+    const prefixedUser = resolveMatrixAllowListMatch({
+      allowList: normalizeMatrixAllowList(["user:@alice:example.org"]),
+      userId,
+    });
+    expect(prefixedUser.allowed).toBe(true);
+    expect(prefixedUser.matchSource).toBe("prefixed-user");
+  });
+
+  it("ignores display names and localparts", () => {
+    const match = resolveMatrixAllowListMatch({
+      allowList: normalizeMatrixAllowList(["alice", "Alice"]),
+      userId: "@alice:example.org",
+    });
+    expect(match.allowed).toBe(false);
+  });
+
+  it("matches wildcard", () => {
+    const match = resolveMatrixAllowListMatch({
+      allowList: normalizeMatrixAllowList(["*"]),
+      userId: "@alice:example.org",
+    });
+    expect(match.allowed).toBe(true);
+    expect(match.matchSource).toBe("wildcard");
+  });
+});

package/src/matrix/monitor/allowlist.ts

@@ -0,0 +1,94 @@
+import {
+  resolveAllowlistMatchByCandidates,
+  type AllowlistMatch,
+} from "openclaw/plugin-sdk/allow-from";
+import { normalizeStringEntries } from "openclaw/plugin-sdk/string-normalization-runtime";
+import { normalizeLowercaseStringOrEmpty } from "openclaw/plugin-sdk/text-runtime";
+
+function normalizeAllowList(list?: Array<string | number>) {
+  return normalizeStringEntries(list);
+}
+
+function normalizeMatrixUser(raw?: string | null): string {
+  const value = (raw ?? "").trim();
+  if (!value) {
+    return "";
+  }
+  if (!value.startsWith("@") || !value.includes(":")) {
+    return normalizeLowercaseStringOrEmpty(value);
+  }
+  const withoutAt = value.slice(1);
+  const splitIndex = withoutAt.indexOf(":");
+  if (splitIndex === -1) {
+    return normalizeLowercaseStringOrEmpty(value);
+  }
+  const localpart = normalizeLowercaseStringOrEmpty(withoutAt.slice(0, splitIndex));
+  const server = normalizeLowercaseStringOrEmpty(withoutAt.slice(splitIndex + 1));
+  if (!server) {
+    return normalizeLowercaseStringOrEmpty(value);
+  }
+  return `@${localpart}:${server}`;
+}
+
+export function normalizeMatrixUserId(raw?: string | null): string {
+  const trimmed = (raw ?? "").trim();
+  if (!trimmed) {
+    return "";
+  }
+  const lowered = normalizeLowercaseStringOrEmpty(trimmed);
+  if (lowered.startsWith("matrix:")) {
+    return normalizeMatrixUser(trimmed.slice("matrix:".length));
+  }
+  if (lowered.startsWith("user:")) {
+    return normalizeMatrixUser(trimmed.slice("user:".length));
+  }
+  return normalizeMatrixUser(trimmed);
+}
+
+function normalizeMatrixAllowListEntry(raw: string): string {
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    return "";
+  }
+  if (trimmed === "*") {
+    return trimmed;
+  }
+  const lowered = normalizeLowercaseStringOrEmpty(trimmed);
+  if (lowered.startsWith("matrix:")) {
+    return `matrix:${normalizeMatrixUser(trimmed.slice("matrix:".length))}`;
+  }
+  if (lowered.startsWith("user:")) {
+    return `user:${normalizeMatrixUser(trimmed.slice("user:".length))}`;
+  }
+  return normalizeMatrixUser(trimmed);
+}
+
+export function normalizeMatrixAllowList(list?: Array<string | number>) {
+  return normalizeAllowList(list).map((entry) => normalizeMatrixAllowListEntry(entry));
+}
+
+export type MatrixAllowListMatch = AllowlistMatch<
+  "wildcard" | "id" | "prefixed-id" | "prefixed-user"
+>;
+
+type MatrixAllowListMatchSource = NonNullable<MatrixAllowListMatch["matchSource"]>;
+
+export function resolveMatrixAllowListMatch(params: {
+  allowList: string[];
+  userId?: string;
+}): MatrixAllowListMatch {
+  const allowList = params.allowList;
+  if (allowList.length === 0) {
+    return { allowed: false };
+  }
+  if (allowList.includes("*")) {
+    return { allowed: true, matchKey: "*", matchSource: "wildcard" };
+  }
+  const userId = normalizeMatrixUser(params.userId);
+  const candidates: Array<{ value?: string; source: MatrixAllowListMatchSource }> = [
+    { value: userId, source: "id" },
+    { value: userId ? `matrix:${userId}` : "", source: "prefixed-id" },
+    { value: userId ? `user:${userId}` : "", source: "prefixed-user" },
+  ];
+  return resolveAllowlistMatchByCandidates<MatrixAllowListMatchSource>({ allowList, candidates });
+}

package/src/matrix/monitor/auto-join.test.ts

@@ -0,0 +1,203 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { PluginRuntime, RuntimeEnv } from "../../../runtime-api.js";
+import { setMatrixRuntime } from "../../runtime.js";
+import type { MatrixConfig } from "../../types.js";
+import { registerMatrixAutoJoin } from "./auto-join.js";
+
+type InviteHandler = (roomId: string, inviteEvent: unknown) => Promise<void>;
+
+function createClientStub() {
+  let inviteHandler: InviteHandler | null = null;
+  const client = {
+    on: vi.fn((eventName: string, listener: unknown) => {
+      if (eventName === "room.invite") {
+        inviteHandler = listener as InviteHandler;
+      }
+      return client;
+    }),
+    joinRoom: vi.fn(async () => {}),
+    resolveRoom: vi.fn(async () => null),
+  } as unknown as import("../sdk.js").MatrixClient;
+
+  return {
+    client,
+    getInviteHandler: () => inviteHandler,
+    joinRoom: (client as unknown as { joinRoom: ReturnType<typeof vi.fn> }).joinRoom,
+    resolveRoom: (client as unknown as { resolveRoom: ReturnType<typeof vi.fn> }).resolveRoom,
+  };
+}
+
+function registerAutoJoinHarness(params: {
+  accountConfig?: MatrixConfig;
+  resolveRoomValue?: string | null;
+  resolveRoomValues?: Array<string | null>;
+  error?: ReturnType<typeof vi.fn>;
+}) {
+  const harness = createClientStub();
+  if (params.resolveRoomValues) {
+    for (const value of params.resolveRoomValues) {
+      harness.resolveRoom.mockResolvedValueOnce(value);
+    }
+  } else if (params.resolveRoomValue !== undefined) {
+    harness.resolveRoom.mockResolvedValue(params.resolveRoomValue);
+  }
+
+  registerMatrixAutoJoin({
+    client: harness.client,
+    accountConfig: params.accountConfig ?? {},
+    runtime: {
+      log: vi.fn(),
+      error: params.error ?? vi.fn(),
+    } as unknown as RuntimeEnv,
+  });
+
+  return harness;
+}
+
+async function triggerInvite(
+  getInviteHandler: () => InviteHandler | null,
+  inviteEvent: unknown = {},
+) {
+  const inviteHandler = getInviteHandler();
+  expect(inviteHandler).toBeTruthy();
+  await inviteHandler!("!room:example.org", inviteEvent);
+}
+
+describe("registerMatrixAutoJoin", () => {
+  beforeEach(() => {
+    setMatrixRuntime({
+      logging: {
+        shouldLogVerbose: () => false,
+      },
+    } as unknown as PluginRuntime);
+  });
+
+  it("joins all invites when autoJoin=always", async () => {
+    const { getInviteHandler, joinRoom } = registerAutoJoinHarness({
+      accountConfig: {
+        autoJoin: "always",
+      },
+    });
+
+    await triggerInvite(getInviteHandler);
+    expect(joinRoom).toHaveBeenCalledWith("!room:example.org");
+  });
+
+  it("does not auto-join invites by default", async () => {
+    const { getInviteHandler, joinRoom } = registerAutoJoinHarness({});
+
+    expect(getInviteHandler()).toBeNull();
+    expect(joinRoom).not.toHaveBeenCalled();
+  });
+
+  it("ignores invites outside allowlist when autoJoin=allowlist", async () => {
+    const { getInviteHandler, joinRoom } = registerAutoJoinHarness({
+      accountConfig: {
+        autoJoin: "allowlist",
+        autoJoinAllowlist: ["#allowed:example.org"],
+      },
+      resolveRoomValue: null,
+    });
+
+    await triggerInvite(getInviteHandler);
+    expect(joinRoom).not.toHaveBeenCalled();
+  });
+
+  it("joins invite when allowlisted alias resolves to the invited room", async () => {
+    const { getInviteHandler, joinRoom } = registerAutoJoinHarness({
+      accountConfig: {
+        autoJoin: "allowlist",
+        autoJoinAllowlist: [" #allowed:example.org "],
+      },
+      resolveRoomValue: "!room:example.org",
+    });
+
+    await triggerInvite(getInviteHandler);
+    expect(joinRoom).toHaveBeenCalledWith("!room:example.org");
+  });
+
+  it("retries alias resolution after an unresolved lookup", async () => {
+    const { getInviteHandler, joinRoom, resolveRoom } = registerAutoJoinHarness({
+      accountConfig: {
+        autoJoin: "allowlist",
+        autoJoinAllowlist: ["#allowed:example.org"],
+      },
+      resolveRoomValues: [null, "!room:example.org"],
+    });
+
+    await triggerInvite(getInviteHandler);
+    await triggerInvite(getInviteHandler);
+
+    expect(resolveRoom).toHaveBeenCalledTimes(2);
+    expect(joinRoom).toHaveBeenCalledWith("!room:example.org");
+  });
+
+  it("logs and skips allowlist alias resolution failures", async () => {
+    const error = vi.fn();
+    const { getInviteHandler, joinRoom, resolveRoom } = registerAutoJoinHarness({
+      accountConfig: {
+        autoJoin: "allowlist",
+        autoJoinAllowlist: ["#allowed:example.org"],
+      },
+      error,
+    });
+    resolveRoom.mockRejectedValue(new Error("temporary homeserver failure"));
+
+    const inviteHandler = getInviteHandler();
+    expect(inviteHandler).toBeTruthy();
+    await expect(inviteHandler!("!room:example.org", {})).resolves.toBeUndefined();
+
+    expect(joinRoom).not.toHaveBeenCalled();
+    expect(error).toHaveBeenCalledWith(
+      expect.stringContaining("matrix: failed resolving allowlisted alias #allowed:example.org:"),
+    );
+  });
+
+  it("does not trust room-provided alias claims for allowlist joins", async () => {
+    const { getInviteHandler, joinRoom } = registerAutoJoinHarness({
+      accountConfig: {
+        autoJoin: "allowlist",
+        autoJoinAllowlist: ["#allowed:example.org"],
+      },
+      resolveRoomValue: "!different-room:example.org",
+    });
+
+    await triggerInvite(getInviteHandler);
+    expect(joinRoom).not.toHaveBeenCalled();
+  });
+
+  it("uses account-scoped auto-join settings for non-default accounts", async () => {
+    const { getInviteHandler, joinRoom } = registerAutoJoinHarness({
+      accountConfig: {
+        autoJoin: "allowlist",
+        autoJoinAllowlist: ["#ops-allowed:example.org"],
+      },
+      resolveRoomValue: "!room:example.org",
+    });
+
+    await triggerInvite(getInviteHandler);
+    expect(joinRoom).toHaveBeenCalledWith("!room:example.org");
+  });
+
+  it("joins sender-scoped invites without eager direct repair", async () => {
+    const { getInviteHandler, joinRoom } = registerAutoJoinHarness({
+      accountConfig: {
+        autoJoin: "always",
+      },
+    });
+
+    await triggerInvite(getInviteHandler, { sender: "@alice:example.org" });
+
+    expect(joinRoom).toHaveBeenCalledWith("!room:example.org");
+  });
+
+  it("still joins invites when the sender is unavailable", async () => {
+    const { getInviteHandler } = registerAutoJoinHarness({
+      accountConfig: {
+        autoJoin: "always",
+      },
+    });
+
+    await expect(triggerInvite(getInviteHandler, {})).resolves.toBeUndefined();
+  });
+});

package/src/matrix/monitor/auto-join.ts

@@ -0,0 +1,86 @@
+import { normalizeStringifiedOptionalString } from "openclaw/plugin-sdk/text-runtime";
+import { getMatrixRuntime } from "../../runtime.js";
+import type { MatrixConfig } from "../../types.js";
+import type { MatrixClient } from "../sdk.js";
+import type { RuntimeEnv } from "./runtime-api.js";
+
+export function registerMatrixAutoJoin(params: {
+  client: MatrixClient;
+  accountConfig: Pick<MatrixConfig, "autoJoin" | "autoJoinAllowlist">;
+  runtime: RuntimeEnv;
+}) {
+  const { client, accountConfig, runtime } = params;
+  const core = getMatrixRuntime();
+  const logVerbose = (message: string) => {
+    if (!core.logging.shouldLogVerbose()) {
+      return;
+    }
+    runtime.log?.(message);
+  };
+  const autoJoin = accountConfig.autoJoin ?? "off";
+  const rawAllowlist = (accountConfig.autoJoinAllowlist ?? [])
+    .map((entry) => normalizeStringifiedOptionalString(entry))
+    .filter((entry): entry is string => Boolean(entry));
+  const autoJoinAllowlist = new Set(rawAllowlist);
+  const allowedRoomIds = new Set(rawAllowlist.filter((entry) => entry.startsWith("!")));
+  const allowedAliases = rawAllowlist.filter((entry) => entry.startsWith("#"));
+  const resolvedAliasRoomIds = new Map<string, string>();
+
+  if (autoJoin === "off") {
+    return;
+  }
+
+  if (autoJoin === "always") {
+    logVerbose("matrix: auto-join enabled for all invites");
+  } else {
+    logVerbose("matrix: auto-join enabled for allowlist invites");
+  }
+
+  const resolveAllowedAliasRoomId = async (alias: string): Promise<string | null> => {
+    if (resolvedAliasRoomIds.has(alias)) {
+      return resolvedAliasRoomIds.get(alias) ?? null;
+    }
+    const resolved = await params.client.resolveRoom(alias);
+    if (resolved) {
+      resolvedAliasRoomIds.set(alias, resolved);
+    }
+    return resolved;
+  };
+
+  const resolveAllowedAliasRoomIds = async (): Promise<string[]> => {
+    const resolved = await Promise.all(
+      allowedAliases.map(async (alias) => {
+        try {
+          return await resolveAllowedAliasRoomId(alias);
+        } catch (err) {
+          runtime.error?.(`matrix: failed resolving allowlisted alias ${alias}: ${String(err)}`);
+          return null;
+        }
+      }),
+    );
+    return resolved.filter((roomId): roomId is string => Boolean(roomId));
+  };
+
+  // Handle invites directly so both "always" and "allowlist" modes share the same path.
+  client.on("room.invite", async (roomId: string, _inviteEvent: unknown) => {
+    if (autoJoin === "allowlist") {
+      const allowedAliasRoomIds = await resolveAllowedAliasRoomIds();
+      const allowed =
+        autoJoinAllowlist.has("*") ||
+        allowedRoomIds.has(roomId) ||
+        allowedAliasRoomIds.some((resolvedRoomId) => resolvedRoomId === roomId);
+
+      if (!allowed) {
+        logVerbose(`matrix: invite ignored (not in allowlist) room=${roomId}`);
+        return;
+      }
+    }
+
+    try {
+      await client.joinRoom(roomId);
+      logVerbose(`matrix: joined room ${roomId}`);
+    } catch (err) {
+      runtime.error?.(`matrix: failed to join room ${roomId}: ${String(err)}`);
+    }
+  });
+}