@badgerclaw/connect 1.0.0

package/src/matrix/credentials.ts

@@ -0,0 +1,125 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk/account-id";
+import { getMatrixRuntime } from "../runtime.js";
+
+export type MatrixStoredCredentials = {
+  homeserver: string;
+  userId: string;
+  accessToken: string;
+  deviceId?: string;
+  createdAt: string;
+  lastUsedAt?: string;
+};
+
+function credentialsFilename(accountId?: string | null): string {
+  const normalized = normalizeAccountId(accountId);
+  if (normalized === DEFAULT_ACCOUNT_ID) {
+    return "credentials.json";
+  }
+  // normalizeAccountId produces lowercase [a-z0-9-] strings, already filesystem-safe.
+  // Different raw IDs that normalize to the same value are the same logical account.
+  return `credentials-${normalized}.json`;
+}
+
+export function resolveMatrixCredentialsDir(
+  env: NodeJS.ProcessEnv = process.env,
+  stateDir?: string,
+): string {
+  const resolvedStateDir = stateDir ?? getMatrixRuntime().state.resolveStateDir(env, os.homedir);
+  return path.join(resolvedStateDir, "credentials", "badgerclaw");
+}
+
+export function resolveMatrixCredentialsPath(
+  env: NodeJS.ProcessEnv = process.env,
+  accountId?: string | null,
+): string {
+  const dir = resolveMatrixCredentialsDir(env);
+  return path.join(dir, credentialsFilename(accountId));
+}
+
+export function loadMatrixCredentials(
+  env: NodeJS.ProcessEnv = process.env,
+  accountId?: string | null,
+): MatrixStoredCredentials | null {
+  const credPath = resolveMatrixCredentialsPath(env, accountId);
+  try {
+    if (!fs.existsSync(credPath)) {
+      return null;
+    }
+    const raw = fs.readFileSync(credPath, "utf-8");
+    const parsed = JSON.parse(raw) as Partial<MatrixStoredCredentials>;
+    if (
+      typeof parsed.homeserver !== "string" ||
+      typeof parsed.userId !== "string" ||
+      typeof parsed.accessToken !== "string"
+    ) {
+      return null;
+    }
+    return parsed as MatrixStoredCredentials;
+  } catch {
+    return null;
+  }
+}
+
+export function saveMatrixCredentials(
+  credentials: Omit<MatrixStoredCredentials, "createdAt" | "lastUsedAt">,
+  env: NodeJS.ProcessEnv = process.env,
+  accountId?: string | null,
+): void {
+  const dir = resolveMatrixCredentialsDir(env);
+  fs.mkdirSync(dir, { recursive: true });
+
+  const credPath = resolveMatrixCredentialsPath(env, accountId);
+
+  const existing = loadMatrixCredentials(env, accountId);
+  const now = new Date().toISOString();
+
+  const toSave: MatrixStoredCredentials = {
+    ...credentials,
+    createdAt: existing?.createdAt ?? now,
+    lastUsedAt: now,
+  };
+
+  fs.writeFileSync(credPath, JSON.stringify(toSave, null, 2), "utf-8");
+}
+
+export function touchMatrixCredentials(
+  env: NodeJS.ProcessEnv = process.env,
+  accountId?: string | null,
+): void {
+  const existing = loadMatrixCredentials(env, accountId);
+  if (!existing) {
+    return;
+  }
+
+  existing.lastUsedAt = new Date().toISOString();
+  const credPath = resolveMatrixCredentialsPath(env, accountId);
+  fs.writeFileSync(credPath, JSON.stringify(existing, null, 2), "utf-8");
+}
+
+export function clearMatrixCredentials(
+  env: NodeJS.ProcessEnv = process.env,
+  accountId?: string | null,
+): void {
+  const credPath = resolveMatrixCredentialsPath(env, accountId);
+  try {
+    if (fs.existsSync(credPath)) {
+      fs.unlinkSync(credPath);
+    }
+  } catch {
+    // ignore
+  }
+}
+
+export function credentialsMatchConfig(
+  stored: MatrixStoredCredentials,
+  config: { homeserver: string; userId: string },
+): boolean {
+  // If userId is empty (token-based auth), only match homeserver
+  if (!config.userId) {
+    return stored.homeserver === config.homeserver;
+  }
+  return stored.homeserver === config.homeserver && stored.userId === config.userId;
+}

package/src/matrix/deps.ts

@@ -0,0 +1,126 @@
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { runPluginCommandWithTimeout, type RuntimeEnv } from "openclaw/plugin-sdk/matrix";
+
+const MATRIX_SDK_PACKAGE = "@vector-im/matrix-bot-sdk";
+const MATRIX_CRYPTO_DOWNLOAD_HELPER = "@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js";
+
+function formatCommandError(result: { stderr: string; stdout: string }): string {
+  const stderr = result.stderr.trim();
+  if (stderr) {
+    return stderr;
+  }
+  const stdout = result.stdout.trim();
+  if (stdout) {
+    return stdout;
+  }
+  return "unknown error";
+}
+
+function isMissingMatrixCryptoRuntimeError(err: unknown): boolean {
+  const message = err instanceof Error ? err.message : String(err ?? "");
+  return (
+    message.includes("Cannot find module") &&
+    message.includes("@matrix-org/matrix-sdk-crypto-nodejs-")
+  );
+}
+
+export function isMatrixSdkAvailable(): boolean {
+  try {
+    const req = createRequire(import.meta.url);
+    req.resolve(MATRIX_SDK_PACKAGE);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function resolvePluginRoot(): string {
+  const currentDir = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(currentDir, "..", "..");
+}
+
+export async function ensureMatrixCryptoRuntime(
+  params: {
+    log?: (message: string) => void;
+    requireFn?: (id: string) => unknown;
+    resolveFn?: (id: string) => string;
+    runCommand?: typeof runPluginCommandWithTimeout;
+    nodeExecutable?: string;
+  } = {},
+): Promise<void> {
+  const req = createRequire(import.meta.url);
+  const requireFn = params.requireFn ?? ((id: string) => req(id));
+  const resolveFn = params.resolveFn ?? ((id: string) => req.resolve(id));
+  const runCommand = params.runCommand ?? runPluginCommandWithTimeout;
+  const nodeExecutable = params.nodeExecutable ?? process.execPath;
+
+  try {
+    requireFn(MATRIX_SDK_PACKAGE);
+    return;
+  } catch (err) {
+    if (!isMissingMatrixCryptoRuntimeError(err)) {
+      throw err;
+    }
+  }
+
+  const scriptPath = resolveFn(MATRIX_CRYPTO_DOWNLOAD_HELPER);
+  params.log?.("badgerclaw: crypto runtime missing; downloading platform library…");
+  const result = await runCommand({
+    argv: [nodeExecutable, scriptPath],
+    cwd: path.dirname(scriptPath),
+    timeoutMs: 300_000,
+    env: { COREPACK_ENABLE_DOWNLOAD_PROMPT: "0" },
+  });
+  if (result.code !== 0) {
+    throw new Error(`BadgerClaw crypto runtime bootstrap failed: ${formatCommandError(result)}`);
+  }
+
+  try {
+    requireFn(MATRIX_SDK_PACKAGE);
+  } catch (err) {
+    throw new Error(
+      `BadgerClaw crypto runtime remains unavailable after bootstrap: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}
+
+export async function ensureMatrixSdkInstalled(params: {
+  runtime: RuntimeEnv;
+  confirm?: (message: string) => Promise<boolean>;
+}): Promise<void> {
+  if (isMatrixSdkAvailable()) {
+    return;
+  }
+  const confirm = params.confirm;
+  if (confirm) {
+    const ok = await confirm("BadgerClaw requires @vector-im/matrix-bot-sdk. Install now?");
+    if (!ok) {
+      throw new Error("BadgerClaw requires @vector-im/matrix-bot-sdk (install dependencies first).");
+    }
+  }
+
+  const root = resolvePluginRoot();
+  const command = fs.existsSync(path.join(root, "pnpm-lock.yaml"))
+    ? ["pnpm", "install"]
+    : ["npm", "install", "--omit=dev", "--silent"];
+  params.runtime.log?.(`badgerclaw: installing dependencies via ${command[0]} (${root})…`);
+  const result = await runPluginCommandWithTimeout({
+    argv: command,
+    cwd: root,
+    timeoutMs: 300_000,
+    env: { COREPACK_ENABLE_DOWNLOAD_PROMPT: "0" },
+  });
+  if (result.code !== 0) {
+    throw new Error(
+      result.stderr.trim() || result.stdout.trim() || "BadgerClaw dependency install failed.",
+    );
+  }
+  if (!isMatrixSdkAvailable()) {
+    throw new Error(
+      "BadgerClaw dependency install completed but @vector-im/matrix-bot-sdk is still missing.",
+    );
+  }
+}

package/src/matrix/format.ts

@@ -0,0 +1,22 @@
+import MarkdownIt from "markdown-it";
+
+const md = new MarkdownIt({
+  html: false,
+  linkify: true,
+  breaks: true,
+  typographer: false,
+});
+
+md.enable("strikethrough");
+
+const { escapeHtml } = md.utils;
+
+md.renderer.rules.image = (tokens, idx) => escapeHtml(tokens[idx]?.content ?? "");
+
+md.renderer.rules.html_block = (tokens, idx) => escapeHtml(tokens[idx]?.content ?? "");
+md.renderer.rules.html_inline = (tokens, idx) => escapeHtml(tokens[idx]?.content ?? "");
+
+export function markdownToMatrixHtml(markdown: string): string {
+  const rendered = md.render(markdown ?? "");
+  return rendered.trimEnd();
+}

package/src/matrix/index.ts

@@ -0,0 +1,11 @@
+export { monitorMatrixProvider } from "./monitor/index.js";
+export { probeMatrix } from "./probe.js";
+export {
+  reactMatrixMessage,
+  resolveMatrixRoomId,
+  sendReadReceiptMatrix,
+  sendMessageMatrix,
+  sendPollMatrix,
+  sendTypingMatrix,
+} from "./send.js";
+export { resolveMatrixAuth, resolveSharedMatrixClient } from "./client.js";

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

@@ -0,0 +1,126 @@
+import {
+  formatAllowlistMatchMeta,
+  issuePairingChallenge,
+  readStoreAllowFromForDmPolicy,
+  resolveDmGroupAccessWithLists,
+  resolveSenderScopedGroupPolicy,
+} from "openclaw/plugin-sdk/matrix";
+import {
+  normalizeMatrixAllowList,
+  resolveMatrixAllowListMatch,
+  resolveMatrixAllowListMatches,
+} from "./allowlist.js";
+
+type MatrixDmPolicy = "open" | "pairing" | "allowlist" | "disabled";
+type MatrixGroupPolicy = "open" | "allowlist" | "disabled";
+
+export async function resolveMatrixAccessState(params: {
+  isDirectMessage: boolean;
+  resolvedAccountId: string;
+  dmPolicy: MatrixDmPolicy;
+  groupPolicy: MatrixGroupPolicy;
+  allowFrom: string[];
+  groupAllowFrom: Array<string | number>;
+  senderId: string;
+  readStoreForDmPolicy: (provider: string, accountId: string) => Promise<string[]>;
+}) {
+  const storeAllowFrom = params.isDirectMessage
+    ? await readStoreAllowFromForDmPolicy({
+        provider: "badgerclaw",
+        accountId: params.resolvedAccountId,
+        dmPolicy: params.dmPolicy,
+        readStore: params.readStoreForDmPolicy,
+      })
+    : [];
+  const normalizedGroupAllowFrom = normalizeMatrixAllowList(params.groupAllowFrom);
+  const senderGroupPolicy = resolveSenderScopedGroupPolicy({
+    groupPolicy: params.groupPolicy,
+    groupAllowFrom: normalizedGroupAllowFrom,
+  });
+  const access = resolveDmGroupAccessWithLists({
+    isGroup: !params.isDirectMessage,
+    dmPolicy: params.dmPolicy,
+    groupPolicy: senderGroupPolicy,
+    allowFrom: params.allowFrom,
+    groupAllowFrom: normalizedGroupAllowFrom,
+    storeAllowFrom,
+    groupAllowFromFallbackToAllowFrom: false,
+    isSenderAllowed: (allowFrom) =>
+      resolveMatrixAllowListMatches({
+        allowList: normalizeMatrixAllowList(allowFrom),
+        userId: params.senderId,
+      }),
+  });
+  const effectiveAllowFrom = normalizeMatrixAllowList(access.effectiveAllowFrom);
+  const effectiveGroupAllowFrom = normalizeMatrixAllowList(access.effectiveGroupAllowFrom);
+  return {
+    access,
+    effectiveAllowFrom,
+    effectiveGroupAllowFrom,
+    groupAllowConfigured: effectiveGroupAllowFrom.length > 0,
+  };
+}
+
+export async function enforceMatrixDirectMessageAccess(params: {
+  dmEnabled: boolean;
+  dmPolicy: MatrixDmPolicy;
+  accessDecision: "allow" | "block" | "pairing";
+  senderId: string;
+  senderName: string;
+  effectiveAllowFrom: string[];
+  upsertPairingRequest: (input: {
+    id: string;
+    meta?: Record<string, string | undefined>;
+  }) => Promise<{
+    code: string;
+    created: boolean;
+  }>;
+  sendPairingReply: (text: string) => Promise<void>;
+  logVerboseMessage: (message: string) => void;
+}): Promise<boolean> {
+  if (!params.dmEnabled) {
+    return false;
+  }
+  if (params.accessDecision === "allow") {
+    return true;
+  }
+  const allowMatch = resolveMatrixAllowListMatch({
+    allowList: params.effectiveAllowFrom,
+    userId: params.senderId,
+  });
+  const allowMatchMeta = formatAllowlistMatchMeta(allowMatch);
+  if (params.accessDecision === "pairing") {
+    await issuePairingChallenge({
+      channel: "badgerclaw",
+      senderId: params.senderId,
+      senderIdLine: `BadgerClaw user id: ${params.senderId}`,
+      meta: { name: params.senderName },
+      upsertPairingRequest: params.upsertPairingRequest,
+      buildReplyText: ({ code }) =>
+        [
+          "OpenClaw: access not configured.",
+          "",
+          `Pairing code: ${code}`,
+          "",
+          "Ask the bot owner to approve with:",
+          "openclaw pairing approve badgerclaw <code>",
+        ].join("\n"),
+      sendPairingReply: params.sendPairingReply,
+      onCreated: () => {
+        params.logVerboseMessage(
+          `badgerclaw pairing request sender=${params.senderId} name=${params.senderName ?? "unknown"} (${allowMatchMeta})`,
+        );
+      },
+      onReplyError: (err) => {
+        params.logVerboseMessage(
+          `badgerclaw pairing reply failed for ${params.senderId}: ${String(err)}`,
+        );
+      },
+    });
+    return false;
+  }
+  params.logVerboseMessage(
+    `badgerclaw: blocked dm sender ${params.senderId} (dmPolicy=${params.dmPolicy}, ${allowMatchMeta})`,
+  );
+  return false;
+}

package/src/matrix/monitor/allowlist.ts

@@ -0,0 +1,94 @@
+import {
+  compileAllowlist,
+  normalizeStringEntries,
+  resolveCompiledAllowlistMatch,
+  type AllowlistMatch,
+} from "openclaw/plugin-sdk/matrix";
+
+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 value.toLowerCase();
+  }
+  const withoutAt = value.slice(1);
+  const splitIndex = withoutAt.indexOf(":");
+  if (splitIndex === -1) {
+    return value.toLowerCase();
+  }
+  const localpart = withoutAt.slice(0, splitIndex).toLowerCase();
+  const server = withoutAt.slice(splitIndex + 1).toLowerCase();
+  if (!server) {
+    return value.toLowerCase();
+  }
+  return `@${localpart}:${server.toLowerCase()}`;
+}
+
+export function normalizeMatrixUserId(raw?: string | null): string {
+  const trimmed = (raw ?? "").trim();
+  if (!trimmed) {
+    return "";
+  }
+  const lowered = trimmed.toLowerCase();
+  if (lowered.startsWith("badgerclaw:")) {
+    return normalizeMatrixUser(trimmed.slice("badgerclaw:".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 = trimmed.toLowerCase();
+  if (lowered.startsWith("badgerclaw:")) {
+    return `badgerclaw:${normalizeMatrixUser(trimmed.slice("badgerclaw:".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 MatrixAllowListSource = Exclude<MatrixAllowListMatch["matchSource"], undefined>;
+
+export function resolveMatrixAllowListMatch(params: {
+  allowList: string[];
+  userId?: string;
+}): MatrixAllowListMatch {
+  const compiledAllowList = compileAllowlist(params.allowList);
+  const userId = normalizeMatrixUser(params.userId);
+  const candidates: Array<{ value?: string; source: MatrixAllowListSource }> = [
+    { value: userId, source: "id" },
+    { value: userId ? `badgerclaw:${userId}` : "", source: "prefixed-id" },
+    { value: userId ? `user:${userId}` : "", source: "prefixed-user" },
+  ];
+  return resolveCompiledAllowlistMatch({
+    compiledAllowlist: compiledAllowList,
+    candidates,
+  });
+}
+
+export function resolveMatrixAllowListMatches(params: { allowList: string[]; userId?: string }) {
+  return resolveMatrixAllowListMatch(params).allowed;
+}

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

@@ -0,0 +1,72 @@
+import type { MatrixClient } from "@vector-im/matrix-bot-sdk";
+import type { RuntimeEnv } from "openclaw/plugin-sdk/matrix";
+import { getMatrixRuntime } from "../../runtime.js";
+import type { CoreConfig } from "../../types.js";
+import { loadMatrixSdk } from "../sdk-runtime.js";
+
+export function registerMatrixAutoJoin(params: {
+  client: MatrixClient;
+  cfg: CoreConfig;
+  runtime: RuntimeEnv;
+}) {
+  const { client, cfg, runtime } = params;
+  const core = getMatrixRuntime();
+  const logVerbose = (message: string) => {
+    if (!core.logging.shouldLogVerbose()) {
+      return;
+    }
+    runtime.log?.(message);
+  };
+  const autoJoin = cfg.channels?.badgerclaw?.autoJoin ?? "always";
+  const autoJoinAllowlist = cfg.channels?.badgerclaw?.autoJoinAllowlist ?? [];
+
+  if (autoJoin === "off") {
+    return;
+  }
+
+  if (autoJoin === "always") {
+    // Use the built-in autojoin mixin for "always" mode
+    const { AutojoinRoomsMixin } = loadMatrixSdk();
+    AutojoinRoomsMixin.setupOnClient(client);
+    logVerbose("badgerclaw: auto-join enabled for all invites");
+    return;
+  }
+
+  // For "allowlist" mode, handle invites manually
+  client.on("room.invite", async (roomId: string, _inviteEvent: unknown) => {
+    if (autoJoin !== "allowlist") {
+      return;
+    }
+
+    // Get room alias if available
+    let alias: string | undefined;
+    let altAliases: string[] = [];
+    try {
+      const aliasState = await client
+        .getRoomStateEvent(roomId, "m.room.canonical_alias", "")
+        .catch(() => null);
+      alias = aliasState?.alias;
+      altAliases = Array.isArray(aliasState?.alt_aliases) ? aliasState.alt_aliases : [];
+    } catch {
+      // Ignore errors
+    }
+
+    const allowed =
+      autoJoinAllowlist.includes("*") ||
+      autoJoinAllowlist.includes(roomId) ||
+      (alias ? autoJoinAllowlist.includes(alias) : false) ||
+      altAliases.some((value) => autoJoinAllowlist.includes(value));
+
+    if (!allowed) {
+      logVerbose(`badgerclaw: invite ignored (not in allowlist) room=${roomId}`);
+      return;
+    }
+
+    try {
+      await client.joinRoom(roomId);
+      logVerbose(`badgerclaw: joined room ${roomId}`);
+    } catch (err) {
+      runtime.error?.(`badgerclaw: failed to join room ${roomId}: ${String(err)}`);
+    }
+  });
+}