@gakr-gakr/matrix 0.1.0

package/src/matrix/credentials-read.ts

@@ -0,0 +1,207 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "autobot/plugin-sdk/account-id";
+import type { AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+import {
+  requiresExplicitMatrixDefaultAccount,
+  resolveMatrixDefaultOrOnlyAccountId,
+} from "../account-selection.js";
+import { getMatrixRuntime } from "../runtime.js";
+import {
+  resolveMatrixCredentialsDir as resolveSharedMatrixCredentialsDir,
+  resolveMatrixCredentialsPath as resolveSharedMatrixCredentialsPath,
+} from "../storage-paths.js";
+
+export type MatrixStoredCredentials = {
+  homeserver: string;
+  userId: string;
+  accessToken: string;
+  deviceId?: string;
+  createdAt: string;
+  lastUsedAt?: string;
+};
+
+type MatrixCredentialsSource = "current" | "legacy";
+
+type MatrixCredentialsFileLoadResult =
+  | {
+      kind: "loaded";
+      source: MatrixCredentialsSource;
+      credentials: MatrixStoredCredentials | null;
+    }
+  | {
+      kind: "missing";
+    };
+
+function resolveStateDir(env: NodeJS.ProcessEnv): string {
+  try {
+    return getMatrixRuntime().state.resolveStateDir(env, os.homedir);
+  } catch {
+    // Some config-only helpers read stored credentials before the Matrix plugin
+    // runtime is installed. Fall back to the standard state-dir env contract.
+    const override = env.AUTOBOT_STATE_DIR?.trim();
+    if (override) {
+      return path.resolve(override);
+    }
+    const homeDir = env.AUTOBOT_HOME?.trim() || env.HOME?.trim() || os.homedir();
+    return path.join(homeDir, ".autobot");
+  }
+}
+
+function resolveLegacyMatrixCredentialsPath(env: NodeJS.ProcessEnv): string {
+  return path.join(resolveMatrixCredentialsDir(env), "credentials.json");
+}
+
+function shouldReadLegacyCredentialsForAccount(accountId?: string | null): boolean {
+  const normalizedAccountId = normalizeAccountId(accountId);
+  const cfg = getMatrixRuntime().config.current() as AutoBotConfig;
+  if (!cfg.channels?.matrix || typeof cfg.channels.matrix !== "object") {
+    return normalizedAccountId === DEFAULT_ACCOUNT_ID;
+  }
+  if (requiresExplicitMatrixDefaultAccount(cfg)) {
+    return false;
+  }
+  return normalizeAccountId(resolveMatrixDefaultOrOnlyAccountId(cfg)) === normalizedAccountId;
+}
+
+function resolveLegacyMigrationSourcePath(
+  env: NodeJS.ProcessEnv,
+  accountId?: string | null,
+): string | null {
+  if (!shouldReadLegacyCredentialsForAccount(accountId)) {
+    return null;
+  }
+  const legacyPath = resolveLegacyMatrixCredentialsPath(env);
+  return legacyPath === resolveMatrixCredentialsPath(env, accountId) ? null : legacyPath;
+}
+
+function parseMatrixCredentialsFile(filePath: string): MatrixStoredCredentials | null {
+  const raw = fs.readFileSync(filePath, "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;
+}
+
+function loadMatrixCredentialsFile(
+  filePath: string,
+  source: MatrixCredentialsSource,
+): MatrixCredentialsFileLoadResult {
+  try {
+    return {
+      kind: "loaded",
+      source,
+      credentials: parseMatrixCredentialsFile(filePath),
+    };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException)?.code === "ENOENT") {
+      return { kind: "missing" };
+    }
+    throw error;
+  }
+}
+
+function loadLegacyMatrixCredentialsWithCurrentFallback(params: {
+  legacyPath: string;
+  currentPath: string;
+}): MatrixCredentialsFileLoadResult {
+  const legacy = loadMatrixCredentialsFile(params.legacyPath, "legacy");
+  if (legacy.kind === "loaded") {
+    return legacy;
+  }
+  return loadMatrixCredentialsFile(params.currentPath, "current");
+}
+
+export function resolveMatrixCredentialsDir(
+  env: NodeJS.ProcessEnv = process.env,
+  stateDir?: string,
+): string {
+  const resolvedStateDir = stateDir ?? resolveStateDir(env);
+  return resolveSharedMatrixCredentialsDir(resolvedStateDir);
+}
+
+export function resolveMatrixCredentialsPath(
+  env: NodeJS.ProcessEnv = process.env,
+  accountId?: string | null,
+): string {
+  const resolvedStateDir = resolveStateDir(env);
+  return resolveSharedMatrixCredentialsPath({ stateDir: resolvedStateDir, accountId });
+}
+
+export function loadMatrixCredentials(
+  env: NodeJS.ProcessEnv = process.env,
+  accountId?: string | null,
+): MatrixStoredCredentials | null {
+  const currentPath = resolveMatrixCredentialsPath(env, accountId);
+  try {
+    const current = loadMatrixCredentialsFile(currentPath, "current");
+    if (current.kind === "loaded") {
+      return current.credentials;
+    }
+
+    const legacyPath = resolveLegacyMigrationSourcePath(env, accountId);
+    if (!legacyPath) {
+      return null;
+    }
+
+    const loaded = loadLegacyMatrixCredentialsWithCurrentFallback({
+      legacyPath,
+      currentPath,
+    });
+    if (loaded.kind !== "loaded" || !loaded.credentials) {
+      return null;
+    }
+
+    if (loaded.source === "legacy") {
+      try {
+        fs.mkdirSync(path.dirname(currentPath), { recursive: true });
+        fs.renameSync(legacyPath, currentPath);
+      } catch {
+        // Keep returning the legacy credentials even if migration fails.
+      }
+    }
+
+    return loaded.credentials;
+  } catch {
+    return null;
+  }
+}
+
+export function clearMatrixCredentials(
+  env: NodeJS.ProcessEnv = process.env,
+  accountId?: string | null,
+): void {
+  const paths = [
+    resolveMatrixCredentialsPath(env, accountId),
+    resolveLegacyMigrationSourcePath(env, accountId),
+  ];
+  for (const filePath of paths) {
+    if (!filePath) {
+      continue;
+    }
+    try {
+      fs.unlinkSync(filePath);
+    } catch {
+      // ignore
+    }
+  }
+}
+
+export function credentialsMatchConfig(
+  stored: MatrixStoredCredentials,
+  config: { homeserver: string; userId: string; accessToken?: string },
+): boolean {
+  if (!config.userId) {
+    if (!config.accessToken) {
+      return false;
+    }
+    return stored.homeserver === config.homeserver && stored.accessToken === config.accessToken;
+  }
+  return stored.homeserver === config.homeserver && stored.userId === config.userId;
+}

package/src/matrix/credentials-write.runtime.ts

@@ -0,0 +1,35 @@
+import type {
+  saveBackfilledMatrixDeviceId as saveBackfilledMatrixDeviceIdType,
+  saveMatrixCredentials as saveMatrixCredentialsType,
+  touchMatrixCredentials as touchMatrixCredentialsType,
+} from "./credentials.js";
+
+type MatrixCredentialsRuntime = typeof import("./credentials.js");
+
+let matrixCredentialsRuntimePromise: Promise<MatrixCredentialsRuntime> | undefined;
+
+function loadMatrixCredentialsRuntime(): Promise<MatrixCredentialsRuntime> {
+  matrixCredentialsRuntimePromise ??= import("./credentials.js");
+  return matrixCredentialsRuntimePromise;
+}
+
+export async function saveMatrixCredentials(
+  ...args: Parameters<typeof saveMatrixCredentialsType>
+): ReturnType<typeof saveMatrixCredentialsType> {
+  const runtime = await loadMatrixCredentialsRuntime();
+  return runtime.saveMatrixCredentials(...args);
+}
+
+export async function saveBackfilledMatrixDeviceId(
+  ...args: Parameters<typeof saveBackfilledMatrixDeviceIdType>
+): ReturnType<typeof saveBackfilledMatrixDeviceIdType> {
+  const runtime = await loadMatrixCredentialsRuntime();
+  return runtime.saveBackfilledMatrixDeviceId(...args);
+}
+
+export async function touchMatrixCredentials(
+  ...args: Parameters<typeof touchMatrixCredentialsType>
+): ReturnType<typeof touchMatrixCredentialsType> {
+  const runtime = await loadMatrixCredentialsRuntime();
+  return runtime.touchMatrixCredentials(...args);
+}

package/src/matrix/credentials.ts

@@ -0,0 +1,95 @@
+import { writeJsonFileAtomically } from "autobot/plugin-sdk/json-store";
+import { createAsyncLock, type AsyncLock } from "./async-lock.js";
+import { loadMatrixCredentials, resolveMatrixCredentialsPath } from "./credentials-read.js";
+import type { MatrixStoredCredentials } from "./credentials-read.js";
+
+export {
+  clearMatrixCredentials,
+  credentialsMatchConfig,
+  loadMatrixCredentials,
+  resolveMatrixCredentialsDir,
+  resolveMatrixCredentialsPath,
+} from "./credentials-read.js";
+export type { MatrixStoredCredentials } from "./credentials-read.js";
+
+const credentialWriteLocks = new Map<string, AsyncLock>();
+
+function withCredentialWriteLock<T>(credPath: string, fn: () => Promise<T>): Promise<T> {
+  let withLock = credentialWriteLocks.get(credPath);
+  if (!withLock) {
+    withLock = createAsyncLock();
+    credentialWriteLocks.set(credPath, withLock);
+  }
+  return withLock(fn);
+}
+
+async function writeMatrixCredentialsUnlocked(params: {
+  credPath: string;
+  credentials: Omit<MatrixStoredCredentials, "createdAt" | "lastUsedAt">;
+  existing: MatrixStoredCredentials | null;
+}): Promise<void> {
+  const now = new Date().toISOString();
+  const toSave: MatrixStoredCredentials = {
+    ...params.credentials,
+    createdAt: params.existing?.createdAt ?? now,
+    lastUsedAt: now,
+  };
+  await writeJsonFileAtomically(params.credPath, toSave);
+}
+
+export async function saveMatrixCredentials(
+  credentials: Omit<MatrixStoredCredentials, "createdAt" | "lastUsedAt">,
+  env: NodeJS.ProcessEnv = process.env,
+  accountId?: string | null,
+): Promise<void> {
+  const credPath = resolveMatrixCredentialsPath(env, accountId);
+  await withCredentialWriteLock(credPath, async () => {
+    await writeMatrixCredentialsUnlocked({
+      credPath,
+      credentials,
+      existing: loadMatrixCredentials(env, accountId),
+    });
+  });
+}
+
+export async function saveBackfilledMatrixDeviceId(
+  credentials: Omit<MatrixStoredCredentials, "createdAt" | "lastUsedAt">,
+  env: NodeJS.ProcessEnv = process.env,
+  accountId?: string | null,
+): Promise<"saved" | "skipped"> {
+  const credPath = resolveMatrixCredentialsPath(env, accountId);
+  return await withCredentialWriteLock(credPath, async () => {
+    const existing = loadMatrixCredentials(env, accountId);
+    if (
+      existing &&
+      (existing.homeserver !== credentials.homeserver ||
+        existing.userId !== credentials.userId ||
+        existing.accessToken !== credentials.accessToken)
+    ) {
+      return "skipped";
+    }
+
+    await writeMatrixCredentialsUnlocked({
+      credPath,
+      credentials,
+      existing,
+    });
+    return "saved";
+  });
+}
+
+export async function touchMatrixCredentials(
+  env: NodeJS.ProcessEnv = process.env,
+  accountId?: string | null,
+): Promise<void> {
+  const credPath = resolveMatrixCredentialsPath(env, accountId);
+  await withCredentialWriteLock(credPath, async () => {
+    const existing = loadMatrixCredentials(env, accountId);
+    if (!existing) {
+      return;
+    }
+
+    existing.lastUsedAt = new Date().toISOString();
+    await writeJsonFileAtomically(credPath, existing);
+  });
+}

package/src/matrix/deps.ts

@@ -0,0 +1,309 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { formatErrorMessage } from "autobot/plugin-sdk/error-runtime";
+import type { RuntimeEnv } from "autobot/plugin-sdk/runtime";
+
+const REQUIRED_MATRIX_PACKAGES = [
+  "matrix-js-sdk",
+  "@matrix-org/matrix-sdk-crypto-nodejs",
+  "@matrix-org/matrix-sdk-crypto-wasm",
+];
+const MIN_MATRIX_CRYPTO_NATIVE_BINDING_BYTES = 1_000_000;
+
+type MatrixCryptoRuntimeDeps = {
+  requireFn?: (id: string) => unknown;
+  runCommand?: (params: {
+    argv: string[];
+    cwd: string;
+    timeoutMs: number;
+    env?: NodeJS.ProcessEnv;
+  }) => Promise<CommandResult>;
+  resolveFn?: (id: string) => string;
+  nodeExecutable?: string;
+  log?: (message: string) => void;
+};
+
+function resolveMissingMatrixPackages(resolveFn?: (id: string) => string): string[] {
+  const resolve = resolveFn ?? defaultResolveFn;
+  return REQUIRED_MATRIX_PACKAGES.filter((pkg) => {
+    try {
+      resolve(pkg);
+      return false;
+    } catch {
+      return true;
+    }
+  });
+}
+
+export function isMatrixSdkAvailable(): boolean {
+  return resolveMissingMatrixPackages().length === 0;
+}
+
+function buildMatrixDepsMissingMessage(missing: string[]): string {
+  return [
+    `Matrix plugin dependencies are missing: ${missing.join(", ")}.`,
+    "Repair this plugin with `autobot plugins update matrix` or run `autobot doctor --fix`.",
+  ].join(" ");
+}
+
+type CommandResult = {
+  code: number;
+  stdout: string;
+  stderr: string;
+};
+
+let defaultMatrixCryptoRuntimeEnsurePromise: Promise<void> | null = null;
+
+async function runFixedCommandWithTimeout(params: {
+  argv: string[];
+  cwd: string;
+  timeoutMs: number;
+  env?: NodeJS.ProcessEnv;
+}): Promise<CommandResult> {
+  return await new Promise((resolve) => {
+    const [command, ...args] = params.argv;
+    if (!command) {
+      resolve({
+        code: 1,
+        stdout: "",
+        stderr: "command is required",
+      });
+      return;
+    }
+
+    const proc = spawn(command, args, {
+      cwd: params.cwd,
+      env: { ...process.env, ...params.env },
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    let timer: NodeJS.Timeout | null = null;
+    const killChildOnExit = () => {
+      if (!settled && proc.exitCode === null) {
+        proc.kill("SIGTERM");
+      }
+    };
+
+    const finalize = (result: CommandResult) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      if (timer) {
+        clearTimeout(timer);
+      }
+      process.off("exit", killChildOnExit);
+      resolve(result);
+    };
+    process.once("exit", killChildOnExit);
+
+    proc.stdout?.on("data", (chunk: Buffer | string) => {
+      stdout += chunk.toString();
+    });
+    proc.stderr?.on("data", (chunk: Buffer | string) => {
+      stderr += chunk.toString();
+    });
+
+    timer = setTimeout(() => {
+      proc.kill("SIGKILL");
+      finalize({
+        code: 124,
+        stdout,
+        stderr: stderr || `command timed out after ${params.timeoutMs}ms`,
+      });
+    }, params.timeoutMs);
+
+    proc.on("error", (err) => {
+      finalize({
+        code: 1,
+        stdout,
+        stderr: err.message,
+      });
+    });
+
+    proc.on("close", (code) => {
+      finalize({
+        code: code ?? 1,
+        stdout,
+        stderr,
+      });
+    });
+  });
+}
+
+function defaultRequireFn(id: string): unknown {
+  return createRequire(import.meta.url)(id);
+}
+
+function defaultResolveFn(id: string): string {
+  return createRequire(import.meta.url).resolve(id);
+}
+
+function isMissingMatrixCryptoRuntimeError(error: unknown): boolean {
+  const message = formatErrorMessage(error);
+  return (
+    message.includes("@matrix-org/matrix-sdk-crypto-nodejs-") ||
+    message.includes("matrix-sdk-crypto-nodejs") ||
+    message.includes("download-lib.js")
+  );
+}
+
+function isMuslRuntime(): boolean {
+  try {
+    const report = process.report?.getReport?.() as
+      | { header?: { glibcVersionRuntime?: string } }
+      | undefined;
+    return !report?.header?.glibcVersionRuntime;
+  } catch {
+    return true;
+  }
+}
+
+function resolveMatrixCryptoNativeBindingFilename(): string | null {
+  switch (process.platform) {
+    case "darwin":
+      return process.arch === "arm64"
+        ? "matrix-sdk-crypto.darwin-arm64.node"
+        : process.arch === "x64"
+          ? "matrix-sdk-crypto.darwin-x64.node"
+          : null;
+    case "linux":
+      if (process.arch === "x64") {
+        return isMuslRuntime()
+          ? "matrix-sdk-crypto.linux-x64-musl.node"
+          : "matrix-sdk-crypto.linux-x64-gnu.node";
+      }
+      if (process.arch === "arm64" && !isMuslRuntime()) {
+        return "matrix-sdk-crypto.linux-arm64-gnu.node";
+      }
+      if (process.arch === "arm") {
+        return "matrix-sdk-crypto.linux-arm-gnueabihf.node";
+      }
+      if (process.arch === "s390x") {
+        return "matrix-sdk-crypto.linux-s390x-gnu.node";
+      }
+      return null;
+    case "win32":
+      return process.arch === "x64"
+        ? "matrix-sdk-crypto.win32-x64-msvc.node"
+        : process.arch === "ia32"
+          ? "matrix-sdk-crypto.win32-ia32-msvc.node"
+          : process.arch === "arm64"
+            ? "matrix-sdk-crypto.win32-arm64-msvc.node"
+            : null;
+    default:
+      return null;
+  }
+}
+
+function resolveMatrixCryptoNativeBindingPath(resolveFn: (id: string) => string): string | null {
+  const filename = resolveMatrixCryptoNativeBindingFilename();
+  if (!filename) {
+    return null;
+  }
+  try {
+    return path.join(
+      path.dirname(resolveFn("@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js")),
+      filename,
+    );
+  } catch {
+    return null;
+  }
+}
+
+function removeIncompleteMatrixCryptoNativeBinding(params: {
+  bindingPath: string | null;
+  log?: (message: string) => void;
+}): void {
+  const bindingPath = params.bindingPath;
+  if (!bindingPath) {
+    return;
+  }
+  try {
+    const stat = fs.statSync(bindingPath);
+    if (!stat.isFile() || stat.size >= MIN_MATRIX_CRYPTO_NATIVE_BINDING_BYTES) {
+      return;
+    }
+    fs.unlinkSync(bindingPath);
+    params.log?.(
+      `matrix: removed incomplete native crypto runtime (${stat.size} bytes); it will be downloaded again`,
+    );
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+      throw error;
+    }
+  }
+}
+
+export async function ensureMatrixCryptoRuntime(
+  params: MatrixCryptoRuntimeDeps = {},
+): Promise<void> {
+  const usesDefaultRuntime =
+    !params.requireFn && !params.runCommand && !params.resolveFn && !params.nodeExecutable;
+  if (usesDefaultRuntime && defaultMatrixCryptoRuntimeEnsurePromise) {
+    await defaultMatrixCryptoRuntimeEnsurePromise;
+    return;
+  }
+  const ensurePromise = ensureMatrixCryptoRuntimeOnce(params);
+  if (!usesDefaultRuntime) {
+    await ensurePromise;
+    return;
+  }
+  defaultMatrixCryptoRuntimeEnsurePromise = ensurePromise.catch((error: unknown) => {
+    defaultMatrixCryptoRuntimeEnsurePromise = null;
+    throw error;
+  });
+  await defaultMatrixCryptoRuntimeEnsurePromise;
+}
+
+async function ensureMatrixCryptoRuntimeOnce(params: MatrixCryptoRuntimeDeps): Promise<void> {
+  const resolveFn = params.resolveFn ?? defaultResolveFn;
+  const nativeBindingPath = resolveMatrixCryptoNativeBindingPath(resolveFn);
+  removeIncompleteMatrixCryptoNativeBinding({ bindingPath: nativeBindingPath, log: params.log });
+  const requireFn = params.requireFn ?? defaultRequireFn;
+  try {
+    requireFn("@matrix-org/matrix-sdk-crypto-nodejs");
+    return;
+  } catch (err) {
+    if (!isMissingMatrixCryptoRuntimeError(err)) {
+      throw err;
+    }
+  }
+
+  const scriptPath = resolveFn("@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js");
+  params.log?.("matrix: bootstrapping native crypto runtime");
+  const runCommand = params.runCommand ?? runFixedCommandWithTimeout;
+  const nodeExecutable = params.nodeExecutable ?? process.execPath;
+  const result = await runCommand({
+    argv: [nodeExecutable, scriptPath],
+    cwd: path.dirname(scriptPath),
+    timeoutMs: 300_000,
+    env: { COREPACK_ENABLE_DOWNLOAD_PROMPT: "0" },
+  });
+  if (result.code !== 0) {
+    removeIncompleteMatrixCryptoNativeBinding({ bindingPath: nativeBindingPath, log: params.log });
+    throw new Error(
+      result.stderr.trim() || result.stdout.trim() || "Matrix crypto runtime bootstrap failed.",
+    );
+  }
+
+  removeIncompleteMatrixCryptoNativeBinding({ bindingPath: nativeBindingPath, log: params.log });
+  requireFn("@matrix-org/matrix-sdk-crypto-nodejs");
+}
+
+export async function ensureMatrixSdkInstalled(params?: {
+  runtime?: RuntimeEnv;
+  confirm?: (message: string) => Promise<boolean>;
+  resolveFn?: (id: string) => string;
+}): Promise<void> {
+  const missing = resolveMissingMatrixPackages(params?.resolveFn);
+  if (missing.length === 0) {
+    return;
+  }
+  throw new Error(buildMatrixDepsMissingMessage(missing));
+}

package/src/matrix/device-health.ts

@@ -0,0 +1,31 @@
+export type MatrixManagedDeviceInfo = {
+  deviceId: string;
+  displayName: string | null;
+  current: boolean;
+};
+
+export type MatrixDeviceHealthSummary = {
+  currentDeviceId: string | null;
+  staleAutoBotDevices: MatrixManagedDeviceInfo[];
+  currentAutoBotDevices: MatrixManagedDeviceInfo[];
+};
+
+const AUTOBOT_DEVICE_NAME_PREFIX = "AutoBot ";
+
+export function isAutoBotManagedMatrixDevice(displayName: string | null | undefined): boolean {
+  return displayName?.startsWith(AUTOBOT_DEVICE_NAME_PREFIX) === true;
+}
+
+export function summarizeMatrixDeviceHealth(
+  devices: MatrixManagedDeviceInfo[],
+): MatrixDeviceHealthSummary {
+  const currentDeviceId = devices.find((device) => device.current)?.deviceId ?? null;
+  const autoBotDevices = devices.filter((device) =>
+    isAutoBotManagedMatrixDevice(device.displayName),
+  );
+  return {
+    currentDeviceId,
+    staleAutoBotDevices: autoBotDevices.filter((device) => !device.current),
+    currentAutoBotDevices: autoBotDevices.filter((device) => device.current),
+  };
+}