@kodelyth/matrix 2026.5.39 → 2026.5.42

package/src/matrix/client-bootstrap.ts

@@ -0,0 +1,173 @@
+import { requireRuntimeConfig } from "klaw/plugin-sdk/plugin-config-runtime";
+import type { CoreConfig } from "../types.js";
+import { getActiveMatrixClient } from "./active-client.js";
+import { isBunRuntime } from "./client/runtime.js";
+import type { MatrixClient } from "./sdk.js";
+
+type ResolvedRuntimeMatrixClient = {
+  client: MatrixClient;
+  stopOnDone: boolean;
+  cleanup?: (mode: ResolvedRuntimeMatrixClientStopMode) => Promise<void>;
+};
+
+type MatrixRuntimeClientReadiness = "none" | "prepared" | "started";
+type ResolvedRuntimeMatrixClientStopMode = "stop" | "persist" | "discard";
+
+type MatrixResolvedClientHook = (
+  client: MatrixClient,
+  context: { preparedByDefault: boolean },
+) => Promise<void> | void;
+
+type MatrixSharedClientRuntimeDeps = Pick<
+  typeof import("./client.js"),
+  "acquireSharedMatrixClient" | "resolveMatrixAuthContext"
+> &
+  Pick<typeof import("./client/shared.js"), "releaseSharedClientInstance">;
+
+let matrixSharedClientRuntimeDepsPromise: Promise<MatrixSharedClientRuntimeDeps> | undefined;
+
+async function loadMatrixSharedClientRuntimeDeps(): Promise<MatrixSharedClientRuntimeDeps> {
+  matrixSharedClientRuntimeDepsPromise ??= Promise.all([
+    import("./client.js"),
+    import("./client/shared.js"),
+  ]).then(([clientModule, sharedModule]) => ({
+    acquireSharedMatrixClient: clientModule.acquireSharedMatrixClient,
+    resolveMatrixAuthContext: clientModule.resolveMatrixAuthContext,
+    releaseSharedClientInstance: sharedModule.releaseSharedClientInstance,
+  }));
+  return await matrixSharedClientRuntimeDepsPromise;
+}
+
+async function ensureResolvedClientReadiness(params: {
+  client: MatrixClient;
+  readiness?: MatrixRuntimeClientReadiness;
+  preparedByDefault: boolean;
+}): Promise<void> {
+  if (params.readiness === "started") {
+    await params.client.start();
+    return;
+  }
+  if (params.readiness === "prepared" || (!params.readiness && params.preparedByDefault)) {
+    await params.client.prepareForOneOff();
+  }
+}
+
+function ensureMatrixNodeRuntime() {
+  if (isBunRuntime()) {
+    throw new Error("Matrix support requires Node (bun runtime not supported)");
+  }
+}
+
+async function resolveRuntimeMatrixClient(opts: {
+  client?: MatrixClient;
+  cfg?: CoreConfig;
+  timeoutMs?: number;
+  accountId?: string | null;
+  onResolved?: MatrixResolvedClientHook;
+}): Promise<ResolvedRuntimeMatrixClient> {
+  ensureMatrixNodeRuntime();
+  if (opts.client) {
+    await opts.onResolved?.(opts.client, { preparedByDefault: false });
+    return { client: opts.client, stopOnDone: false };
+  }
+
+  if (!opts.cfg) {
+    throw new Error(
+      "Matrix runtime client requires a resolved runtime config. Load and resolve config at the command or gateway boundary, then pass cfg through the runtime path.",
+    );
+  }
+  const cfg = requireRuntimeConfig(opts.cfg, "Matrix runtime client") as CoreConfig;
+  const { acquireSharedMatrixClient, releaseSharedClientInstance, resolveMatrixAuthContext } =
+    await loadMatrixSharedClientRuntimeDeps();
+  const authContext = resolveMatrixAuthContext({
+    cfg,
+    accountId: opts.accountId,
+  });
+  const active = getActiveMatrixClient(authContext.accountId);
+  if (active) {
+    await opts.onResolved?.(active, { preparedByDefault: false });
+    return { client: active, stopOnDone: false };
+  }
+  const client = await acquireSharedMatrixClient({
+    cfg,
+    timeoutMs: opts.timeoutMs,
+    accountId: authContext.accountId,
+    startClient: false,
+  });
+  try {
+    await opts.onResolved?.(client, { preparedByDefault: true });
+  } catch (err) {
+    await releaseSharedClientInstance(client, "stop");
+    throw err;
+  }
+  return {
+    client,
+    stopOnDone: true,
+    cleanup: async (mode) => {
+      await releaseSharedClientInstance(client, mode);
+    },
+  };
+}
+
+export async function resolveRuntimeMatrixClientWithReadiness(opts: {
+  client?: MatrixClient;
+  cfg?: CoreConfig;
+  timeoutMs?: number;
+  accountId?: string | null;
+  readiness?: MatrixRuntimeClientReadiness;
+}): Promise<ResolvedRuntimeMatrixClient> {
+  return await resolveRuntimeMatrixClient({
+    client: opts.client,
+    cfg: opts.cfg,
+    timeoutMs: opts.timeoutMs,
+    accountId: opts.accountId,
+    onResolved: async (client, context) => {
+      await ensureResolvedClientReadiness({
+        client,
+        readiness: opts.readiness,
+        preparedByDefault: context.preparedByDefault,
+      });
+    },
+  });
+}
+
+export async function stopResolvedRuntimeMatrixClient(
+  resolved: ResolvedRuntimeMatrixClient,
+  mode: ResolvedRuntimeMatrixClientStopMode = "stop",
+): Promise<void> {
+  if (!resolved.stopOnDone) {
+    return;
+  }
+  if (resolved.cleanup) {
+    await resolved.cleanup(mode);
+    return;
+  }
+  if (mode === "persist") {
+    await resolved.client.stopAndPersist();
+    return;
+  }
+  if (mode === "discard") {
+    resolved.client.stopWithoutPersist();
+    return;
+  }
+  resolved.client.stop();
+}
+
+export async function withResolvedRuntimeMatrixClient<T>(
+  opts: {
+    client?: MatrixClient;
+    cfg?: CoreConfig;
+    timeoutMs?: number;
+    accountId?: string | null;
+    readiness?: MatrixRuntimeClientReadiness;
+  },
+  run: (client: MatrixClient) => Promise<T>,
+  stopMode: ResolvedRuntimeMatrixClientStopMode = "stop",
+): Promise<T> {
+  const resolved = await resolveRuntimeMatrixClientWithReadiness(opts);
+  try {
+    return await run(resolved.client);
+  } finally {
+    await stopResolvedRuntimeMatrixClient(resolved, stopMode);
+  }
+}

package/src/matrix/client.ts

@@ -0,0 +1,23 @@
+export type { MatrixAuth } from "./client/types.js";
+export { isBunRuntime } from "./client/runtime.js";
+export { getMatrixScopedEnvVarNames } from "../env-vars.js";
+export {
+  backfillMatrixAuthDeviceIdAfterStartup,
+  hasReadyMatrixEnvAuth,
+  resolveMatrixEnvAuthReadiness,
+  resolveMatrixConfigForAccount,
+  resolveScopedMatrixEnvConfig,
+  resolveMatrixAuth,
+  resolveMatrixAuthContext,
+  resolveValidatedMatrixHomeserverUrl,
+  validateMatrixHomeserverUrl,
+} from "./client/config.js";
+export { createMatrixClient } from "./client/create-client.js";
+export {
+  acquireSharedMatrixClient,
+  removeSharedClientInstance,
+  releaseSharedClientInstance,
+  resolveSharedMatrixClient,
+  stopSharedClientForAccount,
+  stopSharedClientInstance,
+} from "./client/shared.js";

package/src/matrix/config-paths.ts

@@ -0,0 +1,31 @@
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "klaw/plugin-sdk/account-id";
+import type { CoreConfig } from "../types.js";
+
+export function shouldStoreMatrixAccountAtTopLevel(cfg: CoreConfig, accountId: string): boolean {
+  const normalizedAccountId = normalizeAccountId(accountId);
+  if (normalizedAccountId !== DEFAULT_ACCOUNT_ID) {
+    return false;
+  }
+  const accounts = cfg.channels?.matrix?.accounts;
+  return !accounts || Object.keys(accounts).length === 0;
+}
+
+export function resolveMatrixConfigPath(cfg: CoreConfig, accountId: string): string {
+  const normalizedAccountId = normalizeAccountId(accountId);
+  if (shouldStoreMatrixAccountAtTopLevel(cfg, normalizedAccountId)) {
+    return "channels.matrix";
+  }
+  return `channels.matrix.accounts.${normalizedAccountId}`;
+}
+
+export function resolveMatrixConfigFieldPath(
+  cfg: CoreConfig,
+  accountId: string,
+  fieldPath: string,
+): string {
+  const suffix = fieldPath.trim().replace(/^\.+/, "");
+  if (!suffix) {
+    return resolveMatrixConfigPath(cfg, accountId);
+  }
+  return `${resolveMatrixConfigPath(cfg, accountId)}.${suffix}`;
+}

package/src/matrix/config-update.ts

@@ -0,0 +1,292 @@
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "klaw/plugin-sdk/account-id";
+import { coerceSecretRef } from "klaw/plugin-sdk/secret-ref-runtime";
+import { normalizeSecretInputString } from "klaw/plugin-sdk/setup";
+import type { CoreConfig, MatrixConfig } from "../types.js";
+import { findMatrixAccountConfig } from "./account-config.js";
+import {
+  resolveMatrixConfigPath as resolveMatrixConfigPathBase,
+  shouldStoreMatrixAccountAtTopLevel,
+} from "./config-paths.js";
+
+export {
+  resolveMatrixConfigFieldPath,
+  shouldStoreMatrixAccountAtTopLevel,
+} from "./config-paths.js";
+export const resolveMatrixConfigPath = resolveMatrixConfigPathBase;
+
+export type MatrixAccountPatch = {
+  name?: string | null;
+  enabled?: boolean;
+  homeserver?: string | null;
+  allowPrivateNetwork?: boolean | null;
+  proxy?: string | null;
+  userId?: string | null;
+  accessToken?: MatrixConfig["accessToken"] | null;
+  password?: MatrixConfig["password"] | null;
+  deviceId?: string | null;
+  deviceName?: string | null;
+  avatarUrl?: string | null;
+  encryption?: boolean | null;
+  initialSyncLimit?: number | null;
+  allowBots?: MatrixConfig["allowBots"] | null;
+  autoJoin?: MatrixConfig["autoJoin"] | null;
+  autoJoinAllowlist?: MatrixConfig["autoJoinAllowlist"] | null;
+  dm?: MatrixConfig["dm"] | null;
+  groupPolicy?: MatrixConfig["groupPolicy"] | null;
+  groupAllowFrom?: MatrixConfig["groupAllowFrom"] | null;
+  groups?: MatrixConfig["groups"] | null;
+  rooms?: MatrixConfig["rooms"] | null;
+};
+
+function applyNullableStringField(
+  target: Record<string, unknown>,
+  key: keyof MatrixAccountPatch,
+  value: string | null | undefined,
+): void {
+  if (value === undefined) {
+    return;
+  }
+  if (value === null) {
+    delete target[key];
+    return;
+  }
+  const trimmed = value.trim();
+  if (!trimmed) {
+    delete target[key];
+    return;
+  }
+  target[key] = trimmed;
+}
+
+function applyNullableSecretInputField(
+  target: Record<string, unknown>,
+  key: "accessToken" | "password",
+  value: MatrixConfig["accessToken"] | null | undefined,
+  defaults?: NonNullable<CoreConfig["secrets"]>["defaults"],
+): void {
+  if (value === undefined) {
+    return;
+  }
+  if (value === null) {
+    delete target[key];
+    return;
+  }
+  if (typeof value === "string") {
+    const normalized = normalizeSecretInputString(value);
+    if (normalized) {
+      target[key] = normalized;
+    } else {
+      delete target[key];
+    }
+    return;
+  }
+
+  const ref = coerceSecretRef(value, defaults);
+  if (!ref) {
+    throw new Error(`Invalid Matrix ${key} SecretInput.`);
+  }
+  target[key] = ref;
+}
+
+function cloneMatrixDmConfig(dm: MatrixConfig["dm"]): MatrixConfig["dm"] {
+  if (!dm) {
+    return dm;
+  }
+  return {
+    ...dm,
+    ...(dm.allowFrom ? { allowFrom: [...dm.allowFrom] } : {}),
+  };
+}
+
+function cloneMatrixRoomMap(rooms: MatrixConfig["groups"]): MatrixConfig["groups"] {
+  if (!rooms) {
+    return rooms;
+  }
+  const clonedRoomEntries: Array<[string, NonNullable<MatrixConfig["groups"]>[string]]> = [];
+  for (const [roomId, roomCfg] of Object.entries(rooms)) {
+    clonedRoomEntries.push([roomId, roomCfg ? { ...roomCfg } : roomCfg]);
+  }
+  return Object.fromEntries(clonedRoomEntries);
+}
+
+function applyNullableArrayField(
+  target: Record<string, unknown>,
+  key: keyof MatrixAccountPatch,
+  value: Array<string | number> | null | undefined,
+): void {
+  if (value === undefined) {
+    return;
+  }
+  if (value === null) {
+    delete target[key];
+    return;
+  }
+  target[key] = [...value];
+}
+
+export function updateMatrixAccountConfig(
+  cfg: CoreConfig,
+  accountId: string,
+  patch: MatrixAccountPatch,
+): CoreConfig {
+  const matrix = cfg.channels?.matrix ?? {};
+  const normalizedAccountId = normalizeAccountId(accountId);
+  const existingAccount = (findMatrixAccountConfig(cfg, normalizedAccountId) ??
+    (normalizedAccountId === DEFAULT_ACCOUNT_ID ? matrix : {})) as MatrixConfig;
+  const nextAccount: Record<string, unknown> = { ...existingAccount };
+
+  if (patch.name !== undefined) {
+    if (patch.name === null) {
+      delete nextAccount.name;
+    } else {
+      const trimmed = patch.name.trim();
+      if (trimmed) {
+        nextAccount.name = trimmed;
+      } else {
+        delete nextAccount.name;
+      }
+    }
+  }
+  if (typeof patch.enabled === "boolean") {
+    nextAccount.enabled = patch.enabled;
+  } else if (typeof nextAccount.enabled !== "boolean") {
+    nextAccount.enabled = true;
+  }
+
+  applyNullableStringField(nextAccount, "homeserver", patch.homeserver);
+  applyNullableStringField(nextAccount, "proxy", patch.proxy);
+  applyNullableStringField(nextAccount, "userId", patch.userId);
+  applyNullableSecretInputField(
+    nextAccount,
+    "accessToken",
+    patch.accessToken,
+    cfg.secrets?.defaults,
+  );
+  applyNullableSecretInputField(nextAccount, "password", patch.password, cfg.secrets?.defaults);
+  applyNullableStringField(nextAccount, "deviceId", patch.deviceId);
+  applyNullableStringField(nextAccount, "deviceName", patch.deviceName);
+  applyNullableStringField(nextAccount, "avatarUrl", patch.avatarUrl);
+
+  if (patch.allowPrivateNetwork !== undefined) {
+    const nextNetwork =
+      nextAccount.network && typeof nextAccount.network === "object"
+        ? { ...(nextAccount.network as Record<string, unknown>) }
+        : {};
+    if (patch.allowPrivateNetwork === null) {
+      delete nextNetwork.dangerouslyAllowPrivateNetwork;
+    } else {
+      nextNetwork.dangerouslyAllowPrivateNetwork = patch.allowPrivateNetwork;
+    }
+    if (Object.keys(nextNetwork).length > 0) {
+      nextAccount.network = nextNetwork;
+    } else {
+      delete nextAccount.network;
+    }
+  }
+
+  if (patch.initialSyncLimit !== undefined) {
+    if (patch.initialSyncLimit === null) {
+      delete nextAccount.initialSyncLimit;
+    } else {
+      nextAccount.initialSyncLimit = Math.max(0, Math.floor(patch.initialSyncLimit));
+    }
+  }
+
+  if (patch.encryption !== undefined) {
+    if (patch.encryption === null) {
+      delete nextAccount.encryption;
+    } else {
+      nextAccount.encryption = patch.encryption;
+    }
+  }
+  if (patch.allowBots !== undefined) {
+    if (patch.allowBots === null) {
+      delete nextAccount.allowBots;
+    } else {
+      nextAccount.allowBots = patch.allowBots;
+    }
+  }
+  if (patch.autoJoin !== undefined) {
+    if (patch.autoJoin === null) {
+      delete nextAccount.autoJoin;
+    } else {
+      nextAccount.autoJoin = patch.autoJoin;
+    }
+  }
+  applyNullableArrayField(nextAccount, "autoJoinAllowlist", patch.autoJoinAllowlist);
+  if (patch.dm !== undefined) {
+    if (patch.dm === null) {
+      delete nextAccount.dm;
+    } else {
+      nextAccount.dm = cloneMatrixDmConfig({
+        ...(nextAccount.dm as MatrixConfig["dm"] | undefined),
+        ...patch.dm,
+      });
+    }
+  }
+  if (patch.groupPolicy !== undefined) {
+    if (patch.groupPolicy === null) {
+      delete nextAccount.groupPolicy;
+    } else {
+      nextAccount.groupPolicy = patch.groupPolicy;
+    }
+  }
+  applyNullableArrayField(nextAccount, "groupAllowFrom", patch.groupAllowFrom);
+  if (patch.groups !== undefined) {
+    if (patch.groups === null) {
+      delete nextAccount.groups;
+    } else {
+      nextAccount.groups = cloneMatrixRoomMap(patch.groups);
+    }
+  }
+  if (patch.rooms !== undefined) {
+    if (patch.rooms === null) {
+      delete nextAccount.rooms;
+    } else {
+      nextAccount.rooms = cloneMatrixRoomMap(patch.rooms);
+    }
+  }
+
+  const nextAccounts = Object.fromEntries(
+    Object.entries(matrix.accounts ?? {}).filter(
+      ([rawAccountId]) =>
+        rawAccountId === normalizedAccountId ||
+        normalizeAccountId(rawAccountId) !== normalizedAccountId,
+    ),
+  );
+
+  if (shouldStoreMatrixAccountAtTopLevel(cfg, normalizedAccountId)) {
+    const { accounts: _ignoredAccounts, defaultAccount } = matrix;
+    const {
+      accounts: _ignoredNextAccounts,
+      defaultAccount: _ignoredNextDefaultAccount,
+      ...topLevelAccount
+    } = nextAccount;
+    return {
+      ...cfg,
+      channels: {
+        ...cfg.channels,
+        matrix: {
+          ...(defaultAccount ? { defaultAccount } : {}),
+          enabled: true,
+          ...topLevelAccount,
+        },
+      },
+    };
+  }
+
+  return {
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      matrix: {
+        ...matrix,
+        enabled: true,
+        accounts: {
+          ...nextAccounts,
+          [normalizedAccountId]: nextAccount as MatrixConfig,
+        },
+      },
+    },
+  };
+}