@gakr-gakr/matrix 0.1.0

package/src/matrix/media-text.ts

@@ -0,0 +1,162 @@
+import path from "node:path";
+import type {
+  MatrixMessageAttachmentKind,
+  MatrixMessageAttachmentSummary,
+} from "./actions/types.js";
+
+const MATRIX_MEDIA_KINDS: Record<string, MatrixMessageAttachmentKind> = {
+  "m.audio": "audio",
+  "m.file": "file",
+  "m.image": "image",
+  "m.sticker": "sticker",
+  "m.video": "video",
+};
+
+function resolveMatrixMediaKind(msgtype: string | undefined): MatrixMessageAttachmentKind | null {
+  return MATRIX_MEDIA_KINDS[msgtype ?? ""] ?? null;
+}
+
+function resolveMatrixMediaLabel(
+  kind: MatrixMessageAttachmentKind | undefined,
+  fallback = "media",
+): string {
+  return `${kind ?? fallback} attachment`;
+}
+
+function formatMatrixAttachmentMarker(params: {
+  kind?: MatrixMessageAttachmentKind;
+  tooLarge?: boolean;
+  unavailable?: boolean;
+}): string {
+  const label = resolveMatrixMediaLabel(params.kind);
+  if (params.tooLarge) {
+    return `[matrix ${label} too large]`;
+  }
+  return params.unavailable ? `[matrix ${label} unavailable]` : `[matrix ${label}]`;
+}
+
+function isLikelyBareFilename(text: string): boolean {
+  const trimmed = text.trim();
+  if (!trimmed || trimmed.includes("\n") || /\s/.test(trimmed)) {
+    return false;
+  }
+  if (path.basename(trimmed) !== trimmed) {
+    return false;
+  }
+  return path.extname(trimmed).length > 1;
+}
+
+function resolveCaptionOrFilename(params: { body?: string; filename?: string }): {
+  caption?: string;
+  filename?: string;
+} {
+  const body = params.body?.trim() ?? "";
+  const filename = params.filename?.trim() ?? "";
+  if (filename) {
+    if (!body || body === filename) {
+      return { filename };
+    }
+    return { caption: body, filename };
+  }
+  if (!body) {
+    return {};
+  }
+  if (isLikelyBareFilename(body)) {
+    return { filename: body };
+  }
+  return { caption: body };
+}
+
+export function resolveMatrixMessageAttachment(params: {
+  body?: string;
+  filename?: string;
+  msgtype?: string;
+}): MatrixMessageAttachmentSummary | undefined {
+  const kind = resolveMatrixMediaKind(params.msgtype);
+  if (!kind) {
+    return undefined;
+  }
+  const resolved = resolveCaptionOrFilename(params);
+  return {
+    kind,
+    caption: resolved.caption,
+    filename: resolved.filename,
+  };
+}
+
+export function resolveMatrixMessageBody(params: {
+  body?: string;
+  filename?: string;
+  msgtype?: string;
+}): string | undefined {
+  const attachment = resolveMatrixMessageAttachment(params);
+  if (!attachment) {
+    const body = params.body?.trim() ?? "";
+    return body || undefined;
+  }
+  return attachment.caption;
+}
+
+function formatMatrixAttachmentText(params: {
+  attachment?: MatrixMessageAttachmentSummary;
+  tooLarge?: boolean;
+  unavailable?: boolean;
+}): string | undefined {
+  if (!params.attachment) {
+    return undefined;
+  }
+  return formatMatrixAttachmentMarker({
+    kind: params.attachment.kind,
+    tooLarge: params.tooLarge,
+    unavailable: params.unavailable,
+  });
+}
+
+export function formatMatrixMessageText(params: {
+  body?: string;
+  attachment?: MatrixMessageAttachmentSummary;
+  tooLarge?: boolean;
+  unavailable?: boolean;
+}): string | undefined {
+  const body = params.body?.trim() ?? "";
+  const marker = formatMatrixAttachmentText({
+    attachment: params.attachment,
+    tooLarge: params.tooLarge,
+    unavailable: params.unavailable,
+  });
+  if (!marker) {
+    return body || undefined;
+  }
+  if (!body) {
+    return marker;
+  }
+  return `${body}\n\n${marker}`;
+}
+
+export function formatMatrixMediaUnavailableText(params: {
+  body?: string;
+  filename?: string;
+  msgtype?: string;
+}): string {
+  return (
+    formatMatrixMessageText({
+      body: resolveMatrixMessageBody(params),
+      attachment: resolveMatrixMessageAttachment(params),
+      unavailable: true,
+    }) ?? ""
+  );
+}
+
+export function formatMatrixMediaTooLargeText(params: {
+  body?: string;
+  filename?: string;
+  msgtype?: string;
+}): string {
+  return (
+    formatMatrixMessageText({
+      body: resolveMatrixMessageBody(params),
+      attachment: resolveMatrixMessageAttachment(params),
+      tooLarge: true,
+    }) ?? ""
+  );
+}

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

@@ -0,0 +1,145 @@
+import {
+  createChannelIngressResolver,
+  defineStableChannelIngressIdentity,
+  type ResolvedChannelMessageIngress,
+} from "autobot/plugin-sdk/channel-ingress-runtime";
+import { normalizeMatrixAllowList, resolveMatrixAllowListMatch } from "./allowlist.js";
+
+type MatrixMonitorAccessState = {
+  effectiveGroupAllowFrom: string[];
+  effectiveRoomUsers: string[];
+  messageIngress: ResolvedChannelMessageIngress;
+  accountId: string;
+  senderId: string;
+  isRoom: boolean;
+};
+
+function normalizeMatrixEntry(raw?: string | null): string | null {
+  return normalizeMatrixAllowList([raw ?? ""])[0] ?? null;
+}
+
+const matrixIngressIdentity = defineStableChannelIngressIdentity({
+  key: "sender-id",
+  normalize: normalizeMatrixEntry,
+  matchEntry({ subject, entry }) {
+    const senderId = subject.identifiers[0]?.value;
+    return (
+      entry.value === "*" ||
+      resolveMatrixAllowListMatch({
+        allowList: [entry.value],
+        userId: senderId ?? "",
+      }).allowed
+    );
+  },
+});
+
+function resolveMatrixGroupIngress(params: {
+  groupPolicy: "open" | "allowlist" | "disabled";
+  effectiveGroupAllowFrom: string[];
+  effectiveRoomUsers: string[];
+}): { groupPolicy: "open" | "allowlist" | "disabled"; groupAllowFrom: string[] } {
+  if (params.groupPolicy === "disabled") {
+    return { groupPolicy: "disabled", groupAllowFrom: [] };
+  }
+  if (params.effectiveRoomUsers.length > 0) {
+    return { groupPolicy: "allowlist", groupAllowFrom: params.effectiveRoomUsers };
+  }
+  if (params.groupPolicy === "allowlist" && params.effectiveGroupAllowFrom.length > 0) {
+    return { groupPolicy: "allowlist", groupAllowFrom: params.effectiveGroupAllowFrom };
+  }
+  return { groupPolicy: "open", groupAllowFrom: [] };
+}
+
+export async function resolveMatrixMonitorAccessState(params: {
+  allowFrom: Array<string | number>;
+  storeAllowFrom: Array<string | number>;
+  dmPolicy?: "open" | "pairing" | "allowlist" | "disabled";
+  groupPolicy?: "open" | "allowlist" | "disabled";
+  groupAllowFrom: Array<string | number>;
+  roomUsers: Array<string | number>;
+  senderId: string;
+  isRoom: boolean;
+  accountId?: string;
+  eventKind?: "message" | "reaction";
+}): Promise<MatrixMonitorAccessState> {
+  const dmPolicy = params.dmPolicy ?? "pairing";
+  const groupPolicy = params.groupPolicy ?? "open";
+  const effectiveGroupAllowFrom = normalizeMatrixAllowList(params.groupAllowFrom);
+  const effectiveRoomUsers = normalizeMatrixAllowList(params.roomUsers);
+  const groupIngress = resolveMatrixGroupIngress({
+    groupPolicy,
+    effectiveGroupAllowFrom,
+    effectiveRoomUsers,
+  });
+  const accountId = params.accountId ?? "default";
+  const eventKind = params.eventKind ?? "message";
+  const ingress = createChannelIngressResolver({
+    channelId: "matrix",
+    accountId,
+    identity: matrixIngressIdentity,
+    readStoreAllowFrom: async () => params.storeAllowFrom,
+  });
+  const resolved = await ingress.message({
+    subject: { stableId: params.senderId },
+    conversation: {
+      kind: params.isRoom ? "group" : "direct",
+      id: params.isRoom ? "matrix-room" : "matrix-dm",
+    },
+    event: {
+      kind: eventKind,
+      authMode: "inbound" as const,
+      mayPair: params.isRoom ? false : eventKind === "message",
+    },
+    dmPolicy,
+    groupPolicy: params.isRoom ? groupIngress.groupPolicy : "disabled",
+    policy: { groupAllowFromFallbackToAllowFrom: false },
+    allowFrom: params.allowFrom,
+    ...(params.isRoom ? { groupAllowFrom: groupIngress.groupAllowFrom } : {}),
+  });
+
+  return {
+    effectiveGroupAllowFrom,
+    effectiveRoomUsers,
+    messageIngress: resolved,
+    accountId,
+    senderId: params.senderId,
+    isRoom: params.isRoom,
+  };
+}
+
+export async function resolveMatrixMonitorCommandAccess(
+  state: MatrixMonitorAccessState,
+  params: {
+    useAccessGroups: boolean;
+    allowTextCommands: boolean;
+    hasControlCommand: boolean;
+  },
+) {
+  const commandAllowFrom = state.isRoom ? [] : state.messageIngress.senderAccess.effectiveAllowFrom;
+  const commandGroupAllowFrom =
+    state.effectiveRoomUsers.length > 0 ? state.effectiveRoomUsers : state.effectiveGroupAllowFrom;
+  const resolved = await createChannelIngressResolver({
+    channelId: "matrix",
+    accountId: state.accountId,
+    identity: matrixIngressIdentity,
+  }).command({
+    subject: { stableId: state.senderId },
+    conversation: {
+      kind: state.isRoom ? "group" : "direct",
+      id: state.isRoom ? "matrix-room" : "matrix-dm",
+    },
+    dmPolicy: "allowlist",
+    groupPolicy: "allowlist",
+    policy: { groupAllowFromFallbackToAllowFrom: false },
+    allowFrom: commandAllowFrom,
+    groupAllowFrom: commandGroupAllowFrom,
+    command: {
+      useAccessGroups: params.useAccessGroups,
+      allowTextCommands: params.allowTextCommands,
+      hasControlCommand: params.hasControlCommand,
+      groupOwnerAllowFrom: "none",
+      commandGroupAllowFromFallbackToAllowFrom: false,
+    },
+  });
+  return resolved.commandAccess;
+}

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

@@ -0,0 +1,27 @@
+import { resolveAckReaction } from "autobot/plugin-sdk/channel-feedback";
+import type { AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+import type { CoreConfig } from "../../types.js";
+import { resolveMatrixAccountConfig } from "../account-config.js";
+
+type MatrixAckReactionScope = "group-mentions" | "group-all" | "direct" | "all" | "none" | "off";
+
+export function resolveMatrixAckReactionConfig(params: {
+  cfg: AutoBotConfig;
+  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.ts

@@ -0,0 +1,92 @@
+import {
+  resolveAllowlistMatchByCandidates,
+  type AllowlistMatch,
+} from "autobot/plugin-sdk/allow-from";
+import { normalizeLowercaseStringOrEmpty } from "autobot/plugin-sdk/string-coerce-runtime";
+import { normalizeStringEntries } from "autobot/plugin-sdk/string-normalization-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));
+}
+
+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.ts

@@ -0,0 +1,86 @@
+import { normalizeStringifiedOptionalString } from "autobot/plugin-sdk/string-coerce-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)}`);
+    }
+  });
+}