@kodelyth/matrix 2026.5.42 → 2026.6.1

package/src/matrix/credentials-read.ts

@@ -1,208 +0,0 @@
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "klaw/plugin-sdk/account-id";
-import type { KlawConfig } from "klaw/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.KLAW_STATE_DIR ?? env.KLAW_STATE_DIR)?.trim();
-    if (override) {
-      return path.resolve(override);
-    }
-    const homeDir =
-      env.KLAW_HOME?.trim() || env.KLAW_HOME?.trim() || env.HOME?.trim() || os.homedir();
-    return path.join(homeDir, ".klaw");
-  }
-}
-
-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 KlawConfig;
-  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

@@ -1,35 +0,0 @@
-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

@@ -1,95 +0,0 @@
-import { writeJsonFileAtomically } from "klaw/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

@@ -1,309 +0,0 @@
-import { spawn } from "node:child_process";
-import fs from "node:fs";
-import { createRequire } from "node:module";
-import path from "node:path";
-import { formatErrorMessage } from "klaw/plugin-sdk/error-runtime";
-import type { RuntimeEnv } from "klaw/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 `klaw plugins update matrix` or run `klaw 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

@@ -1,29 +0,0 @@
-export type MatrixManagedDeviceInfo = {
-  deviceId: string;
-  displayName: string | null;
-  current: boolean;
-};
-
-export type MatrixDeviceHealthSummary = {
-  currentDeviceId: string | null;
-  staleKlawDevices: MatrixManagedDeviceInfo[];
-  currentKlawDevices: MatrixManagedDeviceInfo[];
-};
-
-const KLAW_DEVICE_NAME_PREFIX = "Klaw ";
-
-export function isKlawManagedMatrixDevice(displayName: string | null | undefined): boolean {
-  return displayName?.startsWith(KLAW_DEVICE_NAME_PREFIX) === true;
-}
-
-export function summarizeMatrixDeviceHealth(
-  devices: MatrixManagedDeviceInfo[],
-): MatrixDeviceHealthSummary {
-  const currentDeviceId = devices.find((device) => device.current)?.deviceId ?? null;
-  const openClawDevices = devices.filter((device) => isKlawManagedMatrixDevice(device.displayName));
-  return {
-    currentDeviceId,
-    staleKlawDevices: openClawDevices.filter((device) => !device.current),
-    currentKlawDevices: openClawDevices.filter((device) => device.current),
-  };
-}