@gakr-gakr/matrix 0.1.0

package/package.json

@@ -0,0 +1,101 @@
+{
+  "name": "@gakr-gakr/matrix",
+  "version": "0.1.0",
+  "description": "AutoBot Matrix channel plugin",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/autobot/autobot"
+  },
+  "type": "module",
+  "dependencies": {
+    "@matrix-org/matrix-sdk-crypto-nodejs": "0.5.1",
+    "@matrix-org/matrix-sdk-crypto-wasm": "18.3.0",
+    "fake-indexeddb": "6.2.5",
+    "markdown-it": "14.1.1",
+    "matrix-js-sdk": "41.5.0",
+    "music-metadata": "11.12.3",
+    "typebox": "1.1.38",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@gakr-gakr/plugin-sdk": "workspace:*",
+    "@gakr-gakr/autobot": "workspace:*",
+    "autobot": "workspace:@gakr-gakr/autobot@*"
+  },
+  "peerDependencies": {
+    "@gakr-gakr/autobot": ">=0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@gakr-gakr/autobot": {
+      "optional": true
+    }
+  },
+  "autobot": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "setupEntry": "./setup-entry.ts",
+    "setupFeatures": {
+      "configPromotion": true
+    },
+    "channel": {
+      "id": "matrix",
+      "label": "Matrix",
+      "selectionLabel": "Matrix (plugin)",
+      "docsPath": "/channels/matrix",
+      "docsLabel": "matrix",
+      "blurb": "open protocol; install the plugin to enable.",
+      "order": 70,
+      "quickstartAllowFrom": true,
+      "doctorCapabilities": {
+        "dmAllowFromMode": "nestedOnly",
+        "groupModel": "sender",
+        "groupAllowFromFallbackToAllowFrom": false,
+        "warnOnEmptyGroupSenderAllowlist": true
+      },
+      "cliAddOptions": [
+        {
+          "flags": "--homeserver <url>",
+          "description": "Matrix homeserver URL"
+        },
+        {
+          "flags": "--user-id <id>",
+          "description": "Matrix user ID"
+        },
+        {
+          "flags": "--access-token <token>",
+          "description": "Matrix access token"
+        },
+        {
+          "flags": "--device-name <name>",
+          "description": "Matrix device name"
+        },
+        {
+          "flags": "--initial-sync-limit <n>",
+          "description": "Matrix initial sync limit"
+        }
+      ],
+      "persistedAuthState": {
+        "specifier": "./auth-presence",
+        "exportName": "hasAnyMatrixAuth"
+      }
+    },
+    "install": {
+      "clawhubSpec": "clawhub:@gakr-gakr/matrix",
+      "npmSpec": "@gakr-gakr/matrix",
+      "defaultChoice": "clawhub",
+      "minHostVersion": ">=2026.4.10",
+      "allowInvalidConfigRecovery": true
+    },
+    "compat": {
+      "pluginApi": ">=2026.5.19"
+    },
+    "build": {
+      "autobotVersion": "2026.5.19"
+    },
+    "release": {
+      "publishToClawHub": true,
+      "publishToNpm": true
+    }
+  }
+}

package/plugin-entry.handlers.runtime.ts

@@ -0,0 +1 @@
+export * from "./src/plugin-entry.runtime.ts";

package/runtime-api.ts

@@ -0,0 +1,72 @@
+export {
+  type MatrixResolvedStringField,
+  type MatrixResolvedStringValues,
+  resolveMatrixAccountStringValues,
+} from "./src/auth-precedence.js";
+export {
+  requiresExplicitMatrixDefaultAccount,
+  resolveMatrixDefaultOrOnlyAccountId,
+} from "./src/account-selection.js";
+export {
+  findMatrixAccountEntry,
+  resolveConfiguredMatrixAccountIds,
+  resolveMatrixChannelConfig,
+} from "./src/account-selection.js";
+export {
+  getMatrixScopedEnvVarNames,
+  listMatrixEnvAccountIds,
+  resolveMatrixEnvAccountToken,
+} from "./src/env-vars.js";
+export {
+  hashMatrixAccessToken,
+  resolveMatrixAccountStorageRoot,
+  resolveMatrixCredentialsDir,
+  resolveMatrixCredentialsFilename,
+  resolveMatrixCredentialsPath,
+  resolveMatrixHomeserverKey,
+  resolveMatrixLegacyFlatStoragePaths,
+  resolveMatrixLegacyFlatStoreRoot,
+  sanitizeMatrixPathSegment,
+} from "./src/storage-paths.js";
+export { ensureMatrixSdkInstalled, isMatrixSdkAvailable } from "./src/matrix/deps.js";
+export {
+  assertHttpUrlTargetsPrivateNetwork,
+  closeDispatcher,
+  createPinnedDispatcher,
+  resolvePinnedHostnameWithPolicy,
+  ssrfPolicyFromDangerouslyAllowPrivateNetwork,
+  ssrfPolicyFromAllowPrivateNetwork,
+  type LookupFn,
+  type SsrFPolicy,
+} from "autobot/plugin-sdk/ssrf-runtime";
+export {
+  setMatrixThreadBindingIdleTimeoutBySessionKey,
+  setMatrixThreadBindingMaxAgeBySessionKey,
+} from "./src/matrix/thread-bindings-shared.js";
+export { setMatrixRuntime } from "./src/runtime.js";
+export { writeJsonFileAtomically } from "autobot/plugin-sdk/json-store";
+export type {
+  ChannelDirectoryEntry,
+  ChannelMessageActionContext,
+} from "autobot/plugin-sdk/channel-contract";
+export type { AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+export { formatZonedTimestamp } from "autobot/plugin-sdk/time-runtime";
+export type { PluginRuntime, RuntimeLogger } from "autobot/plugin-sdk/plugin-runtime";
+export type { RuntimeEnv } from "autobot/plugin-sdk/runtime-env";
+export type { WizardPrompter } from "autobot/plugin-sdk/setup";
+
+export function chunkTextForOutbound(text: string, limit: number): string[] {
+  const chunks: string[] = [];
+  let remaining = text;
+  while (remaining.length > limit) {
+    const window = remaining.slice(0, limit);
+    const splitAt = Math.max(window.lastIndexOf("\n"), window.lastIndexOf(" "));
+    const breakAt = splitAt > 0 ? splitAt : limit;
+    chunks.push(remaining.slice(0, breakAt).trimEnd());
+    remaining = remaining.slice(breakAt).trimStart();
+  }
+  if (remaining.length > 0 || text.length === 0) {
+    chunks.push(remaining);
+  }
+  return chunks;
+}

package/runtime-heavy-api.ts

@@ -0,0 +1 @@
+export * from "./src/matrix-migration.runtime.js";

package/runtime-setter-api.ts

@@ -0,0 +1,3 @@
+// Narrow entry point for setMatrixRuntime. The full runtime-api barrel is kept
+// for external/runtime callers, but bundled plugin register only needs this.
+export { setMatrixRuntime } from "./src/runtime.js";

package/secret-contract-api.ts

@@ -0,0 +1,5 @@
+export {
+  channelSecrets,
+  collectRuntimeConfigAssignments,
+  secretTargetRegistryEntries,
+} from "./src/secret-contract.js";

package/setup-entry.ts

@@ -0,0 +1,17 @@
+import { defineBundledChannelSetupEntry } from "autobot/plugin-sdk/channel-entry-contract";
+
+export default defineBundledChannelSetupEntry({
+  importMetaUrl: import.meta.url,
+  plugin: {
+    specifier: "./setup-plugin-api.js",
+    exportName: "matrixSetupPlugin",
+  },
+  secrets: {
+    specifier: "./secret-contract-api.js",
+    exportName: "channelSecrets",
+  },
+  runtime: {
+    specifier: "./runtime-setter-api.js",
+    exportName: "setMatrixRuntime",
+  },
+});

package/setup-plugin-api.ts

@@ -0,0 +1,3 @@
+// Keep bundled setup entry imports narrow so setup loads do not pull the
+// broader Matrix runtime plugin surface.
+export { matrixSetupPlugin } from "./src/channel.setup.js";

package/src/account-selection.ts

@@ -0,0 +1,223 @@
+import {
+  listCombinedAccountIds,
+  listConfiguredAccountIds,
+  resolveListedDefaultAccountId,
+  resolveNormalizedAccountEntry,
+} from "autobot/plugin-sdk/account-core";
+import {
+  DEFAULT_ACCOUNT_ID,
+  normalizeAccountId,
+  normalizeOptionalAccountId,
+} from "autobot/plugin-sdk/account-id";
+import type { AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+import { hasConfiguredSecretInput } from "autobot/plugin-sdk/secret-input-runtime";
+import { normalizeOptionalString } from "autobot/plugin-sdk/string-coerce-runtime";
+import {
+  resolveMatrixAccountStringValues,
+  type MatrixResolvedStringField,
+} from "./auth-precedence.js";
+import { getMatrixScopedEnvVarNames, listMatrixEnvAccountIds } from "./env-vars.js";
+import { isRecord } from "./record-shared.js";
+
+type MatrixTopologyStringSources = Partial<Record<MatrixResolvedStringField, string>>;
+
+function readConfiguredMatrixString(value: unknown): string {
+  return normalizeOptionalString(value) ?? "";
+}
+
+function readConfiguredMatrixSecretSource(value: unknown): string {
+  return hasConfiguredSecretInput(value) ? "configured" : "";
+}
+
+function resolveMatrixChannelStringSources(
+  entry: Record<string, unknown> | null,
+): MatrixTopologyStringSources {
+  if (!entry) {
+    return {};
+  }
+  return {
+    homeserver: readConfiguredMatrixString(entry.homeserver),
+    userId: readConfiguredMatrixString(entry.userId),
+    accessToken: readConfiguredMatrixSecretSource(entry.accessToken),
+    password: readConfiguredMatrixSecretSource(entry.password),
+    deviceId: readConfiguredMatrixString(entry.deviceId),
+    deviceName: readConfiguredMatrixString(entry.deviceName),
+  };
+}
+
+function readEnvMatrixString(env: NodeJS.ProcessEnv, key: string): string {
+  return normalizeOptionalString(env[key]) ?? "";
+}
+
+function resolveScopedMatrixEnvStringSources(
+  accountId: string,
+  env: NodeJS.ProcessEnv,
+): MatrixTopologyStringSources {
+  const keys = getMatrixScopedEnvVarNames(accountId);
+  return {
+    homeserver: readEnvMatrixString(env, keys.homeserver),
+    userId: readEnvMatrixString(env, keys.userId),
+    accessToken: readEnvMatrixString(env, keys.accessToken),
+    password: readEnvMatrixString(env, keys.password),
+    deviceId: readEnvMatrixString(env, keys.deviceId),
+    deviceName: readEnvMatrixString(env, keys.deviceName),
+  };
+}
+
+function resolveGlobalMatrixEnvStringSources(env: NodeJS.ProcessEnv): MatrixTopologyStringSources {
+  return {
+    homeserver: readEnvMatrixString(env, "MATRIX_HOMESERVER"),
+    userId: readEnvMatrixString(env, "MATRIX_USER_ID"),
+    accessToken: readEnvMatrixString(env, "MATRIX_ACCESS_TOKEN"),
+    password: readEnvMatrixString(env, "MATRIX_PASSWORD"),
+    deviceId: readEnvMatrixString(env, "MATRIX_DEVICE_ID"),
+    deviceName: readEnvMatrixString(env, "MATRIX_DEVICE_NAME"),
+  };
+}
+
+function hasUsableResolvedMatrixAuth(values: {
+  homeserver: string;
+  userId: string;
+  accessToken: string;
+}): boolean {
+  // Account discovery must keep homeserver+userId shapes because auth can still
+  // resolve through cached Matrix credentials even when no fresh token/password
+  // is present in config or env.
+  return Boolean(values.homeserver && (values.accessToken || values.userId));
+}
+
+function hasFreshResolvedMatrixAuth(values: {
+  homeserver: string;
+  userId: string;
+  accessToken: string;
+  password: string;
+}): boolean {
+  return Boolean(values.homeserver && (values.accessToken || (values.userId && values.password)));
+}
+
+function resolveEffectiveMatrixAccountSources(params: {
+  channel: Record<string, unknown> | null;
+  accountId: string;
+  env: NodeJS.ProcessEnv;
+}): ReturnType<typeof resolveMatrixAccountStringValues> {
+  const normalizedAccountId = normalizeAccountId(params.accountId);
+  return resolveMatrixAccountStringValues({
+    accountId: normalizedAccountId,
+    scopedEnv: resolveScopedMatrixEnvStringSources(normalizedAccountId, params.env),
+    channel: resolveMatrixChannelStringSources(params.channel),
+    globalEnv: resolveGlobalMatrixEnvStringSources(params.env),
+  });
+}
+
+function hasUsableEffectiveMatrixAccountSource(params: {
+  channel: Record<string, unknown> | null;
+  accountId: string;
+  env: NodeJS.ProcessEnv;
+}): boolean {
+  return hasUsableResolvedMatrixAuth(resolveEffectiveMatrixAccountSources(params));
+}
+
+function hasFreshEffectiveMatrixAccountSource(params: {
+  channel: Record<string, unknown> | null;
+  accountId: string;
+  env: NodeJS.ProcessEnv;
+}): boolean {
+  return hasFreshResolvedMatrixAuth(resolveEffectiveMatrixAccountSources(params));
+}
+
+function hasConfiguredDefaultMatrixAccountSource(params: {
+  channel: Record<string, unknown> | null;
+  env: NodeJS.ProcessEnv;
+}): boolean {
+  return hasFreshEffectiveMatrixAccountSource({
+    channel: params.channel,
+    accountId: DEFAULT_ACCOUNT_ID,
+    env: params.env,
+  });
+}
+
+export function resolveMatrixChannelConfig(cfg: AutoBotConfig): Record<string, unknown> | null {
+  return isRecord(cfg.channels?.matrix) ? cfg.channels.matrix : null;
+}
+
+export function findMatrixAccountEntry(
+  cfg: AutoBotConfig,
+  accountId: string,
+): Record<string, unknown> | null {
+  const channel = resolveMatrixChannelConfig(cfg);
+  if (!channel) {
+    return null;
+  }
+
+  const accounts = isRecord(channel.accounts) ? channel.accounts : null;
+  if (!accounts) {
+    return null;
+  }
+  const entry = resolveNormalizedAccountEntry(accounts, accountId, normalizeAccountId);
+  return isRecord(entry) ? entry : null;
+}
+
+export function resolveConfiguredMatrixAccountIds(
+  cfg: AutoBotConfig,
+  env: NodeJS.ProcessEnv = process.env,
+): string[] {
+  const channel = resolveMatrixChannelConfig(cfg);
+  const configuredAccountIds = listConfiguredAccountIds({
+    accounts: channel && isRecord(channel.accounts) ? channel.accounts : undefined,
+    normalizeAccountId,
+  });
+  if (hasConfiguredDefaultMatrixAccountSource({ channel, env })) {
+    configuredAccountIds.push(DEFAULT_ACCOUNT_ID);
+  }
+  const readyEnvAccountIds = listMatrixEnvAccountIds(env).filter((accountId) =>
+    normalizeAccountId(accountId) === DEFAULT_ACCOUNT_ID
+      ? hasConfiguredDefaultMatrixAccountSource({ channel, env })
+      : hasUsableEffectiveMatrixAccountSource({ channel, accountId, env }),
+  );
+  return listCombinedAccountIds({
+    configuredAccountIds,
+    additionalAccountIds: readyEnvAccountIds,
+    fallbackAccountIdWhenEmpty: channel ? DEFAULT_ACCOUNT_ID : undefined,
+  });
+}
+
+export function resolveMatrixDefaultOrOnlyAccountId(
+  cfg: AutoBotConfig,
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  const channel = resolveMatrixChannelConfig(cfg);
+  if (!channel) {
+    return DEFAULT_ACCOUNT_ID;
+  }
+
+  const configuredDefault = normalizeOptionalAccountId(
+    typeof channel.defaultAccount === "string" ? channel.defaultAccount : undefined,
+  );
+  const configuredAccountIds = resolveConfiguredMatrixAccountIds(cfg, env);
+  return resolveListedDefaultAccountId({
+    accountIds: configuredAccountIds,
+    configuredDefaultAccountId: configuredDefault,
+    ambiguousFallbackAccountId: DEFAULT_ACCOUNT_ID,
+  });
+}
+
+export function requiresExplicitMatrixDefaultAccount(
+  cfg: AutoBotConfig,
+  env: NodeJS.ProcessEnv = process.env,
+): boolean {
+  const channel = resolveMatrixChannelConfig(cfg);
+  if (!channel) {
+    return false;
+  }
+  const configuredAccountIds = resolveConfiguredMatrixAccountIds(cfg, env);
+  if (configuredAccountIds.length <= 1) {
+    return false;
+  }
+  if (configuredAccountIds.includes(DEFAULT_ACCOUNT_ID)) {
+    return false;
+  }
+  const configuredDefault = normalizeOptionalAccountId(
+    typeof channel.defaultAccount === "string" ? channel.defaultAccount : undefined,
+  );
+  return !(configuredDefault && configuredAccountIds.includes(configuredDefault));
+}