@kodelyth/matrix 2026.5.42 → 2026.6.2

package/src/matrix/sdk/recovery-key-store.ts

@@ -1,453 +0,0 @@
-import { loadJsonFile, saveJsonFile } from "klaw/plugin-sdk/json-store";
-import { decodeRecoveryKey } from "matrix-js-sdk/lib/crypto-api/recovery-key.js";
-import { formatMatrixErrorMessage, formatMatrixErrorReason } from "../errors.js";
-import { LogService } from "./logger.js";
-import type {
-  MatrixCryptoBootstrapApi,
-  MatrixCryptoCallbacks,
-  MatrixGeneratedSecretStorageKey,
-  MatrixSecretStorageStatus,
-  MatrixStoredRecoveryKey,
-} from "./types.js";
-
-export function isRepairableSecretStorageAccessError(err: unknown): boolean {
-  const message = formatMatrixErrorReason(err);
-  if (!message) {
-    return false;
-  }
-  if (message.includes("getsecretstoragekey callback returned falsey")) {
-    return true;
-  }
-  // The homeserver still has secret storage, but the local recovery key cannot
-  // authenticate/decrypt a required secret. During explicit bootstrap we can
-  // recreate secret storage and continue with a new local baseline.
-  if (message.includes("decrypting secret") && message.includes("bad mac")) {
-    return true;
-  }
-  return false;
-}
-
-export class MatrixRecoveryKeyStore {
-  private readonly secretStorageKeyCache = new Map<
-    string,
-    { key: Uint8Array; keyInfo?: MatrixStoredRecoveryKey["keyInfo"] }
-  >();
-  private stagedRecoveryKey: MatrixStoredRecoveryKey | null = null;
-  private stagedRecoveryKeyUsed = false;
-  private readonly stagedCacheKeyIds = new Set<string>();
-
-  constructor(private readonly recoveryKeyPath?: string) {}
-
-  buildCryptoCallbacks(): MatrixCryptoCallbacks {
-    return {
-      getSecretStorageKey: async ({ keys }) => {
-        const requestedKeyIds = Object.keys(keys ?? {});
-        if (requestedKeyIds.length === 0) {
-          return null;
-        }
-
-        const staged = this.resolveStagedSecretStorageKey(requestedKeyIds);
-        if (staged) {
-          return staged;
-        }
-
-        for (const keyId of requestedKeyIds) {
-          const cached = this.secretStorageKeyCache.get(keyId);
-          if (cached) {
-            return [keyId, new Uint8Array(cached.key)];
-          }
-        }
-
-        const stored = this.loadStoredRecoveryKey();
-        if (!stored?.privateKeyBase64) {
-          return null;
-        }
-        const privateKey = new Uint8Array(Buffer.from(stored.privateKeyBase64, "base64"));
-        if (privateKey.length === 0) {
-          return null;
-        }
-
-        if (stored.keyId && requestedKeyIds.includes(stored.keyId)) {
-          this.rememberSecretStorageKey(stored.keyId, privateKey, stored.keyInfo);
-          return [stored.keyId, privateKey];
-        }
-
-        const firstRequestedKeyId = requestedKeyIds[0];
-        if (!firstRequestedKeyId) {
-          return null;
-        }
-        this.rememberSecretStorageKey(firstRequestedKeyId, privateKey, stored.keyInfo);
-        return [firstRequestedKeyId, privateKey];
-      },
-      cacheSecretStorageKey: (keyId, keyInfo, key) => {
-        const privateKey = new Uint8Array(key);
-        const normalizedKeyInfo: MatrixStoredRecoveryKey["keyInfo"] = {
-          passphrase: keyInfo?.passphrase,
-          name: typeof keyInfo?.name === "string" ? keyInfo.name : undefined,
-        };
-        this.rememberSecretStorageKey(keyId, privateKey, normalizedKeyInfo);
-
-        const stored = this.loadStoredRecoveryKey();
-        this.saveRecoveryKeyToDisk({
-          keyId,
-          keyInfo: normalizedKeyInfo,
-          privateKey,
-          encodedPrivateKey: stored?.encodedPrivateKey,
-        });
-      },
-    };
-  }
-
-  getRecoveryKeySummary(): {
-    encodedPrivateKey?: string;
-    keyId?: string | null;
-    createdAt?: string;
-  } | null {
-    const stored = this.loadStoredRecoveryKey();
-    if (!stored) {
-      return null;
-    }
-    return {
-      encodedPrivateKey: stored.encodedPrivateKey,
-      keyId: stored.keyId,
-      createdAt: stored.createdAt,
-    };
-  }
-
-  private resolveEncodedRecoveryKeyInput(params: {
-    encodedPrivateKey: string;
-    keyId?: string | null;
-    keyInfo?: MatrixStoredRecoveryKey["keyInfo"];
-  }): {
-    encodedPrivateKey: string;
-    privateKey: Uint8Array;
-    keyId: string | null;
-    keyInfo?: MatrixStoredRecoveryKey["keyInfo"];
-  } {
-    const encodedPrivateKey = params.encodedPrivateKey.trim();
-    if (!encodedPrivateKey) {
-      throw new Error("Matrix recovery key is required");
-    }
-    let privateKey: Uint8Array;
-    try {
-      privateKey = decodeRecoveryKey(encodedPrivateKey);
-    } catch (err) {
-      throw new Error(`Invalid Matrix recovery key: ${formatMatrixErrorMessage(err)}`, {
-        cause: err,
-      });
-    }
-    const keyId =
-      typeof params.keyId === "string" && params.keyId.trim() ? params.keyId.trim() : null;
-    return {
-      encodedPrivateKey,
-      privateKey,
-      keyId,
-      keyInfo: params.keyInfo ?? this.loadStoredRecoveryKey()?.keyInfo,
-    };
-  }
-
-  storeEncodedRecoveryKey(params: {
-    encodedPrivateKey: string;
-    keyId?: string | null;
-    keyInfo?: MatrixStoredRecoveryKey["keyInfo"];
-  }): {
-    encodedPrivateKey?: string;
-    keyId?: string | null;
-    createdAt?: string;
-  } {
-    const prepared = this.resolveEncodedRecoveryKeyInput(params);
-    this.saveRecoveryKeyToDisk({
-      keyId: prepared.keyId,
-      keyInfo: prepared.keyInfo,
-      privateKey: prepared.privateKey,
-      encodedPrivateKey: prepared.encodedPrivateKey,
-    });
-    if (prepared.keyId) {
-      this.rememberSecretStorageKey(prepared.keyId, prepared.privateKey, prepared.keyInfo);
-    }
-    return this.getRecoveryKeySummary() ?? {};
-  }
-
-  stageEncodedRecoveryKey(params: {
-    encodedPrivateKey: string;
-    keyId?: string | null;
-    keyInfo?: MatrixStoredRecoveryKey["keyInfo"];
-  }): void {
-    const prepared = this.resolveEncodedRecoveryKeyInput(params);
-    this.discardStagedRecoveryKey();
-    this.stagedRecoveryKey = {
-      version: 1,
-      createdAt: new Date().toISOString(),
-      keyId: prepared.keyId,
-      encodedPrivateKey: prepared.encodedPrivateKey,
-      privateKeyBase64: Buffer.from(prepared.privateKey).toString("base64"),
-      keyInfo: prepared.keyInfo,
-    };
-  }
-
-  hasStagedRecoveryKeyBeenUsed(): boolean {
-    return this.stagedRecoveryKeyUsed;
-  }
-
-  commitStagedRecoveryKey(params?: {
-    keyId?: string | null;
-    keyInfo?: MatrixStoredRecoveryKey["keyInfo"];
-  }): {
-    encodedPrivateKey?: string;
-    keyId?: string | null;
-    createdAt?: string;
-  } | null {
-    if (!this.stagedRecoveryKey) {
-      return this.getRecoveryKeySummary();
-    }
-    const staged = this.stagedRecoveryKey;
-    const privateKey = new Uint8Array(Buffer.from(staged.privateKeyBase64, "base64"));
-    const keyId =
-      typeof params?.keyId === "string" && params.keyId.trim() ? params.keyId.trim() : staged.keyId;
-    this.saveRecoveryKeyToDisk({
-      keyId,
-      keyInfo: params?.keyInfo ?? staged.keyInfo,
-      privateKey,
-      encodedPrivateKey: staged.encodedPrivateKey,
-    });
-    this.clearStagedRecoveryKeyTracking();
-    return this.getRecoveryKeySummary();
-  }
-
-  discardStagedRecoveryKey(): void {
-    for (const keyId of this.stagedCacheKeyIds) {
-      this.secretStorageKeyCache.delete(keyId);
-    }
-    this.clearStagedRecoveryKeyTracking();
-  }
-
-  async bootstrapSecretStorageWithRecoveryKey(
-    crypto: MatrixCryptoBootstrapApi,
-    options: {
-      setupNewKeyBackup?: boolean;
-      allowSecretStorageRecreateWithoutRecoveryKey?: boolean;
-      forceNewSecretStorage?: boolean;
-      forceNewRecoveryKey?: boolean;
-    } = {},
-  ): Promise<void> {
-    let status: MatrixSecretStorageStatus | null = null;
-    const getSecretStorageStatus = crypto.getSecretStorageStatus; // pragma: allowlist secret
-    if (typeof getSecretStorageStatus === "function") {
-      try {
-        status = await getSecretStorageStatus.call(crypto);
-      } catch (err) {
-        LogService.warn("MatrixClientLite", "Failed to read secret storage status:", err);
-      }
-    }
-
-    const hasDefaultSecretStorageKey = Boolean(status?.defaultKeyId);
-    const hasKnownInvalidSecrets = Object.values(status?.secretStorageKeyValidityMap ?? {}).some(
-      (valid) => !valid,
-    );
-    let generatedRecoveryKey = false;
-    const storedRecovery = this.loadStoredRecoveryKey();
-    const stagedRecovery = this.stagedRecoveryKey;
-    const sourceRecovery =
-      options.forceNewRecoveryKey === true ? null : (stagedRecovery ?? storedRecovery);
-    let recoveryKey: MatrixGeneratedSecretStorageKey | null = sourceRecovery
-      ? {
-          keyInfo: sourceRecovery.keyInfo,
-          privateKey: new Uint8Array(Buffer.from(sourceRecovery.privateKeyBase64, "base64")),
-          encodedPrivateKey: sourceRecovery.encodedPrivateKey,
-        }
-      : null;
-
-    if (recoveryKey && status?.defaultKeyId) {
-      const defaultKeyId = status.defaultKeyId;
-      if (!stagedRecovery) {
-        this.rememberSecretStorageKey(defaultKeyId, recoveryKey.privateKey, recoveryKey.keyInfo);
-        if (storedRecovery && storedRecovery.keyId !== defaultKeyId) {
-          this.saveRecoveryKeyToDisk({
-            keyId: defaultKeyId,
-            keyInfo: recoveryKey.keyInfo,
-            privateKey: recoveryKey.privateKey,
-            encodedPrivateKey: recoveryKey.encodedPrivateKey,
-          });
-        }
-      }
-    }
-
-    const ensureRecoveryKey = async (): Promise<MatrixGeneratedSecretStorageKey> => {
-      if (recoveryKey) {
-        if (stagedRecovery) {
-          this.stagedRecoveryKeyUsed = true;
-        }
-        return recoveryKey;
-      }
-      if (typeof crypto.createRecoveryKeyFromPassphrase !== "function") {
-        throw new Error(
-          "Matrix crypto backend does not support recovery key generation (createRecoveryKeyFromPassphrase missing)",
-        );
-      }
-      recoveryKey = await crypto.createRecoveryKeyFromPassphrase();
-      this.saveRecoveryKeyToDisk(recoveryKey);
-      generatedRecoveryKey = true;
-      return recoveryKey;
-    };
-
-    const shouldRecreateSecretStorage =
-      options.forceNewSecretStorage === true ||
-      !hasDefaultSecretStorageKey ||
-      (!recoveryKey && status?.ready === false) ||
-      hasKnownInvalidSecrets;
-
-    if (hasKnownInvalidSecrets) {
-      // Existing secret storage keys can't decrypt required secrets. Generate a fresh recovery key.
-      recoveryKey = null;
-    }
-
-    const secretStorageOptions: {
-      createSecretStorageKey?: () => Promise<MatrixGeneratedSecretStorageKey>;
-      setupNewSecretStorage?: boolean;
-      setupNewKeyBackup?: boolean;
-    } = {
-      setupNewKeyBackup: options.setupNewKeyBackup === true,
-    };
-
-    if (shouldRecreateSecretStorage) {
-      secretStorageOptions.setupNewSecretStorage = true;
-      secretStorageOptions.createSecretStorageKey = ensureRecoveryKey;
-    }
-
-    try {
-      await crypto.bootstrapSecretStorage(secretStorageOptions);
-    } catch (err) {
-      const shouldRecreateWithoutRecoveryKey =
-        options.allowSecretStorageRecreateWithoutRecoveryKey === true &&
-        hasDefaultSecretStorageKey &&
-        isRepairableSecretStorageAccessError(err);
-      if (!shouldRecreateWithoutRecoveryKey) {
-        throw err;
-      }
-
-      recoveryKey = null;
-      LogService.warn(
-        "MatrixClientLite",
-        "Secret storage exists on the server but local recovery material cannot unlock it; recreating secret storage during explicit bootstrap.",
-      );
-      await crypto.bootstrapSecretStorage({
-        setupNewSecretStorage: true,
-        setupNewKeyBackup: options.setupNewKeyBackup === true,
-        createSecretStorageKey: ensureRecoveryKey,
-      });
-    }
-
-    if (generatedRecoveryKey && this.recoveryKeyPath) {
-      LogService.warn(
-        "MatrixClientLite",
-        `Generated Matrix recovery key and saved it to ${this.recoveryKeyPath}. Keep this file secure.`,
-      );
-    }
-  }
-
-  private clearStagedRecoveryKeyTracking(): void {
-    this.stagedRecoveryKey = null;
-    this.stagedRecoveryKeyUsed = false;
-    this.stagedCacheKeyIds.clear();
-  }
-
-  private resolveStagedSecretStorageKey(requestedKeyIds: string[]): [string, Uint8Array] | null {
-    const staged = this.stagedRecoveryKey;
-    if (!staged?.privateKeyBase64) {
-      return null;
-    }
-    const privateKey = new Uint8Array(Buffer.from(staged.privateKeyBase64, "base64"));
-    if (privateKey.length === 0) {
-      return null;
-    }
-    const keyId =
-      staged.keyId && requestedKeyIds.includes(staged.keyId) ? staged.keyId : requestedKeyIds[0];
-    if (!keyId) {
-      return null;
-    }
-    this.rememberStagedSecretStorageKey(keyId, privateKey, staged.keyInfo);
-    this.stagedCacheKeyIds.add(keyId);
-    return [keyId, privateKey];
-  }
-
-  private rememberStagedSecretStorageKey(
-    keyId: string,
-    key: Uint8Array,
-    keyInfo?: MatrixStoredRecoveryKey["keyInfo"],
-  ): void {
-    this.stagedRecoveryKeyUsed = true;
-    this.rememberSecretStorageKey(keyId, key, keyInfo);
-  }
-
-  private rememberSecretStorageKey(
-    keyId: string,
-    key: Uint8Array,
-    keyInfo?: MatrixStoredRecoveryKey["keyInfo"],
-  ): void {
-    if (!keyId.trim()) {
-      return;
-    }
-    this.secretStorageKeyCache.set(keyId, {
-      key: new Uint8Array(key),
-      keyInfo,
-    });
-  }
-
-  private loadStoredRecoveryKey(): MatrixStoredRecoveryKey | null {
-    if (!this.recoveryKeyPath) {
-      return null;
-    }
-    try {
-      const parsed = loadJsonFile<Partial<MatrixStoredRecoveryKey>>(this.recoveryKeyPath);
-      if (
-        parsed?.version !== 1 ||
-        typeof parsed.createdAt !== "string" ||
-        typeof parsed.privateKeyBase64 !== "string" || // pragma: allowlist secret
-        !parsed.privateKeyBase64.trim()
-      ) {
-        return null;
-      }
-      return {
-        version: 1,
-        createdAt: parsed.createdAt,
-        keyId: typeof parsed.keyId === "string" ? parsed.keyId : null,
-        encodedPrivateKey:
-          typeof parsed.encodedPrivateKey === "string" ? parsed.encodedPrivateKey : undefined,
-        privateKeyBase64: parsed.privateKeyBase64,
-        keyInfo:
-          parsed.keyInfo && typeof parsed.keyInfo === "object"
-            ? {
-                passphrase: parsed.keyInfo.passphrase,
-                name: typeof parsed.keyInfo.name === "string" ? parsed.keyInfo.name : undefined,
-              }
-            : undefined,
-      };
-    } catch {
-      return null;
-    }
-  }
-
-  private saveRecoveryKeyToDisk(params: MatrixGeneratedSecretStorageKey): void {
-    if (!this.recoveryKeyPath) {
-      return;
-    }
-    try {
-      const payload: MatrixStoredRecoveryKey = {
-        version: 1,
-        createdAt: new Date().toISOString(),
-        keyId: typeof params.keyId === "string" ? params.keyId : null,
-        encodedPrivateKey: params.encodedPrivateKey,
-        privateKeyBase64: Buffer.from(params.privateKey).toString("base64"),
-        keyInfo: params.keyInfo
-          ? {
-              passphrase: params.keyInfo.passphrase,
-              name: params.keyInfo.name,
-            }
-          : undefined,
-      };
-      saveJsonFile(this.recoveryKeyPath, payload);
-    } catch (err) {
-      LogService.warn("MatrixClientLite", "Failed to persist recovery key:", err);
-    }
-  }
-}

package/src/matrix/sdk/timeout-abort-signal.ts

@@ -1 +0,0 @@
-export { buildTimeoutAbortSignal } from "klaw/plugin-sdk/extension-shared";

package/src/matrix/sdk/transport-runtime-api.ts

@@ -1,18 +0,0 @@
-import { fetchWithRuntimeDispatcherOrMockedGlobal } from "klaw/plugin-sdk/runtime-fetch";
-import {
-  closeDispatcher,
-  createPinnedDispatcher,
-  resolvePinnedHostnameWithPolicy,
-  type PinnedDispatcherPolicy,
-  type SsrFPolicy,
-} from "klaw/plugin-sdk/ssrf-dispatcher";
-export { buildTimeoutAbortSignal } from "./timeout-abort-signal.js";
-
-export {
-  closeDispatcher,
-  createPinnedDispatcher,
-  fetchWithRuntimeDispatcherOrMockedGlobal,
-  resolvePinnedHostnameWithPolicy,
-  type PinnedDispatcherPolicy,
-  type SsrFPolicy,
-};