@archipelagolab/lobi 1.0.0

package/src/matrix/monitor/legacy-crypto-restore.ts

@@ -0,0 +1,139 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { readJsonFileWithFallback, writeJsonFileAtomically } from "openclaw/plugin-sdk/json-store";
+import { getMatrixRuntime } from "../../runtime.js";
+import { resolveMatrixStoragePaths } from "../client/storage.js";
+import type { MatrixAuth } from "../client/types.js";
+import type { MatrixClient } from "../sdk.js";
+
+type MatrixLegacyCryptoMigrationState = {
+  version: 1;
+  accountId: string;
+  roomKeyCounts: {
+    total: number;
+    backedUp: number;
+  } | null;
+  restoreStatus: "pending" | "completed" | "manual-action-required";
+  restoredAt?: string;
+  importedCount?: number;
+  totalCount?: number;
+  lastError?: string | null;
+};
+
+export type MatrixLegacyCryptoRestoreResult =
+  | { kind: "skipped" }
+  | {
+      kind: "restored";
+      imported: number;
+      total: number;
+      localOnlyKeys: number;
+    }
+  | {
+      kind: "failed";
+      error: string;
+      localOnlyKeys: number;
+    };
+
+function isMigrationState(value: unknown): value is MatrixLegacyCryptoMigrationState {
+  return (
+    Boolean(value) && typeof value === "object" && (value as { version?: unknown }).version === 1
+  );
+}
+
+async function resolvePendingMigrationStatePath(params: {
+  stateDir: string;
+  auth: Pick<MatrixAuth, "homeserver" | "userId" | "accessToken" | "accountId" | "deviceId">;
+}): Promise<{
+  statePath: string;
+  value: MatrixLegacyCryptoMigrationState | null;
+}> {
+  const { rootDir } = resolveMatrixStoragePaths({
+    homeserver: params.auth.homeserver,
+    userId: params.auth.userId,
+    accessToken: params.auth.accessToken,
+    accountId: params.auth.accountId,
+    deviceId: params.auth.deviceId,
+    stateDir: params.stateDir,
+  });
+  const directStatePath = path.join(rootDir, "legacy-crypto-migration.json");
+  const { value: directValue } =
+    await readJsonFileWithFallback<MatrixLegacyCryptoMigrationState | null>(directStatePath, null);
+  if (isMigrationState(directValue) && directValue.restoreStatus === "pending") {
+    return { statePath: directStatePath, value: directValue };
+  }
+
+  const accountStorageDir = path.dirname(rootDir);
+  let siblingEntries: string[] = [];
+  try {
+    siblingEntries = (await fs.readdir(accountStorageDir, { withFileTypes: true }))
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name)
+      .filter((entry) => path.join(accountStorageDir, entry) !== rootDir)
+      .toSorted((left, right) => left.localeCompare(right));
+  } catch {
+    return { statePath: directStatePath, value: directValue };
+  }
+
+  for (const sibling of siblingEntries) {
+    const siblingStatePath = path.join(accountStorageDir, sibling, "legacy-crypto-migration.json");
+    const { value } = await readJsonFileWithFallback<MatrixLegacyCryptoMigrationState | null>(
+      siblingStatePath,
+      null,
+    );
+    if (isMigrationState(value) && value.restoreStatus === "pending") {
+      return { statePath: siblingStatePath, value };
+    }
+  }
+  return { statePath: directStatePath, value: directValue };
+}
+
+export async function maybeRestoreLegacyMatrixBackup(params: {
+  client: Pick<MatrixClient, "restoreRoomKeyBackup">;
+  auth: Pick<MatrixAuth, "homeserver" | "userId" | "accessToken" | "accountId" | "deviceId">;
+  env?: NodeJS.ProcessEnv;
+  stateDir?: string;
+}): Promise<MatrixLegacyCryptoRestoreResult> {
+  const env = params.env ?? process.env;
+  const stateDir = params.stateDir ?? getMatrixRuntime().state.resolveStateDir(env, os.homedir);
+  const { statePath, value } = await resolvePendingMigrationStatePath({
+    stateDir,
+    auth: params.auth,
+  });
+  if (!isMigrationState(value) || value.restoreStatus !== "pending") {
+    return { kind: "skipped" };
+  }
+
+  const restore = await params.client.restoreRoomKeyBackup();
+  const localOnlyKeys =
+    value.roomKeyCounts && value.roomKeyCounts.total > value.roomKeyCounts.backedUp
+      ? value.roomKeyCounts.total - value.roomKeyCounts.backedUp
+      : 0;
+
+  if (restore.success) {
+    await writeJsonFileAtomically(statePath, {
+      ...value,
+      restoreStatus: "completed",
+      restoredAt: restore.restoredAt ?? new Date().toISOString(),
+      importedCount: restore.imported,
+      totalCount: restore.total,
+      lastError: null,
+    } satisfies MatrixLegacyCryptoMigrationState);
+    return {
+      kind: "restored",
+      imported: restore.imported,
+      total: restore.total,
+      localOnlyKeys,
+    };
+  }
+
+  await writeJsonFileAtomically(statePath, {
+    ...value,
+    lastError: restore.error ?? "unknown",
+  } satisfies MatrixLegacyCryptoMigrationState);
+  return {
+    kind: "failed",
+    error: restore.error ?? "unknown",
+    localOnlyKeys,
+  };
+}

package/src/matrix/monitor/location.ts

@@ -0,0 +1,100 @@
+import {
+  normalizeLowercaseStringOrEmpty,
+  normalizeOptionalString,
+} from "openclaw/plugin-sdk/text-runtime";
+import type { LocationMessageEventContent } from "../sdk.js";
+import { formatLocationText, toLocationContext, type NormalizedLocation } from "./runtime-api.js";
+import { EventType } from "./types.js";
+
+export type MatrixLocationPayload = {
+  text: string;
+  context: ReturnType<typeof toLocationContext>;
+};
+
+type GeoUriParams = {
+  latitude: number;
+  longitude: number;
+  accuracy?: number;
+};
+
+function parseGeoUri(value: string): GeoUriParams | null {
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return null;
+  }
+  if (!normalizeLowercaseStringOrEmpty(trimmed).startsWith("geo:")) {
+    return null;
+  }
+  const payload = trimmed.slice(4);
+  const [coordsPart, ...paramParts] = payload.split(";");
+  const coords = coordsPart.split(",");
+  if (coords.length < 2) {
+    return null;
+  }
+  const latitude = Number.parseFloat(coords[0] ?? "");
+  const longitude = Number.parseFloat(coords[1] ?? "");
+  if (!Number.isFinite(latitude) || !Number.isFinite(longitude)) {
+    return null;
+  }
+
+  const params = new Map<string, string>();
+  for (const part of paramParts) {
+    const segment = part.trim();
+    if (!segment) {
+      continue;
+    }
+    const eqIndex = segment.indexOf("=");
+    const rawKey = eqIndex === -1 ? segment : segment.slice(0, eqIndex);
+    const rawValue = eqIndex === -1 ? "" : segment.slice(eqIndex + 1);
+    const key = normalizeLowercaseStringOrEmpty(rawKey);
+    if (!key) {
+      continue;
+    }
+    const valuePart = rawValue.trim();
+    params.set(key, valuePart ? decodeURIComponent(valuePart) : "");
+  }
+
+  const accuracyRaw = params.get("u");
+  const accuracy = accuracyRaw ? Number.parseFloat(accuracyRaw) : undefined;
+
+  return {
+    latitude,
+    longitude,
+    accuracy: Number.isFinite(accuracy) ? accuracy : undefined,
+  };
+}
+
+export function resolveMatrixLocation(params: {
+  eventType: string;
+  content: LocationMessageEventContent;
+}): MatrixLocationPayload | null {
+  const { eventType, content } = params;
+  const isLocation =
+    eventType === EventType.Location ||
+    (eventType === EventType.RoomMessage && content.msgtype === EventType.Location);
+  if (!isLocation) {
+    return null;
+  }
+  const geoUri = normalizeOptionalString(content.geo_uri) ?? "";
+  if (!geoUri) {
+    return null;
+  }
+  const parsed = parseGeoUri(geoUri);
+  if (!parsed) {
+    return null;
+  }
+  const caption = normalizeOptionalString(content.body) ?? "";
+  const location: NormalizedLocation = {
+    latitude: parsed.latitude,
+    longitude: parsed.longitude,
+    accuracy: parsed.accuracy,
+    caption: caption || undefined,
+    source: "pin",
+    isLive: false,
+  };
+
+  return {
+    text: formatLocationText(location),
+    context: toLocationContext(location),
+  };
+}

package/src/matrix/monitor/media.test.ts

@@ -0,0 +1,159 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { PluginRuntime } from "../../../runtime-api.js";
+import { setMatrixRuntime } from "../../runtime.js";
+import { MatrixMediaSizeLimitError } from "../media-errors.js";
+import { downloadMatrixMedia } from "./media.js";
+
+function createEncryptedClient() {
+  const decryptMedia = vi.fn().mockResolvedValue(Buffer.from("decrypted"));
+
+  return {
+    client: {
+      crypto: { decryptMedia },
+      mxcToHttp: vi.fn().mockReturnValue("https://example/mxc"),
+    } as unknown as import("../sdk.js").MatrixClient,
+    decryptMedia,
+  };
+}
+
+function createEncryptedFile() {
+  return {
+    url: "mxc://example/file",
+    key: {
+      kty: "oct",
+      key_ops: ["encrypt", "decrypt"],
+      alg: "A256CTR",
+      k: "secret",
+      ext: true,
+    },
+    iv: "iv",
+    hashes: { sha256: "hash" },
+    v: "v2",
+  };
+}
+
+describe("downloadMatrixMedia", () => {
+  const saveMediaBuffer = vi.fn().mockResolvedValue({
+    path: "/tmp/media",
+    contentType: "image/png",
+  });
+
+  const runtimeStub = {
+    channel: {
+      media: {
+        saveMediaBuffer: (...args: unknown[]) => saveMediaBuffer(...args),
+      },
+    },
+  } as unknown as PluginRuntime;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    setMatrixRuntime(runtimeStub);
+  });
+
+  it("decrypts encrypted media when file payloads are present", async () => {
+    const { client, decryptMedia } = createEncryptedClient();
+    const file = createEncryptedFile();
+
+    const result = await downloadMatrixMedia({
+      client,
+      mxcUrl: "mxc://example/file",
+      contentType: "image/png",
+      maxBytes: 1024,
+      file,
+    });
+
+    expect(decryptMedia).toHaveBeenCalledWith(file, {
+      maxBytes: 1024,
+      readIdleTimeoutMs: 30_000,
+    });
+    expect(saveMediaBuffer).toHaveBeenCalledWith(
+      Buffer.from("decrypted"),
+      "image/png",
+      "inbound",
+      1024,
+      undefined,
+    );
+    expect(result?.path).toBe("/tmp/media");
+  });
+
+  it("forwards originalFilename to saveMediaBuffer when provided", async () => {
+    const { client } = createEncryptedClient();
+    const file = createEncryptedFile();
+
+    await downloadMatrixMedia({
+      client,
+      mxcUrl: "mxc://example/file",
+      contentType: "image/png",
+      maxBytes: 1024,
+      file,
+      originalFilename: "Screenshot 2026-03-27.png",
+    });
+
+    expect(saveMediaBuffer).toHaveBeenCalledWith(
+      Buffer.from("decrypted"),
+      "image/png",
+      "inbound",
+      1024,
+      "Screenshot 2026-03-27.png",
+    );
+  });
+
+  it("rejects encrypted media that exceeds maxBytes before decrypting", async () => {
+    const { client, decryptMedia } = createEncryptedClient();
+    const file = createEncryptedFile();
+
+    await expect(
+      downloadMatrixMedia({
+        client,
+        mxcUrl: "mxc://example/file",
+        contentType: "image/png",
+        sizeBytes: 2048,
+        maxBytes: 1024,
+        file,
+      }),
+    ).rejects.toBeInstanceOf(MatrixMediaSizeLimitError);
+
+    expect(decryptMedia).not.toHaveBeenCalled();
+    expect(saveMediaBuffer).not.toHaveBeenCalled();
+  });
+
+  it("preserves typed size-limit errors from plain media downloads", async () => {
+    const tooLargeError = new MatrixMediaSizeLimitError(
+      "Matrix media exceeds configured size limit (8192 bytes > 4096 bytes)",
+    );
+    const downloadContent = vi.fn().mockRejectedValue(tooLargeError);
+    const client = {
+      downloadContent,
+    } as unknown as import("../sdk.js").MatrixClient;
+
+    await expect(
+      downloadMatrixMedia({
+        client,
+        mxcUrl: "mxc://example/file",
+        contentType: "image/png",
+        maxBytes: 4096,
+      }),
+    ).rejects.toBe(tooLargeError);
+  });
+
+  it("passes byte limits through plain media downloads", async () => {
+    const downloadContent = vi.fn().mockResolvedValue(Buffer.from("plain"));
+
+    const client = {
+      downloadContent,
+    } as unknown as import("../sdk.js").MatrixClient;
+
+    await downloadMatrixMedia({
+      client,
+      mxcUrl: "mxc://example/file",
+      contentType: "image/png",
+      maxBytes: 4096,
+    });
+
+    expect(downloadContent).toHaveBeenCalledWith("mxc://example/file", {
+      maxBytes: 4096,
+      readIdleTimeoutMs: 30_000,
+    });
+  });
+});

package/src/matrix/monitor/media.ts

@@ -0,0 +1,119 @@
+import { getMatrixRuntime } from "../../runtime.js";
+import { MatrixMediaSizeLimitError, isMatrixMediaSizeLimitError } from "../media-errors.js";
+import type { MatrixClient } from "../sdk.js";
+
+// Type for encrypted file info
+type EncryptedFile = {
+  url: string;
+  key: {
+    kty: string;
+    key_ops: string[];
+    alg: string;
+    k: string;
+    ext: boolean;
+  };
+  iv: string;
+  hashes: Record<string, string>;
+  v: string;
+};
+
+const MATRIX_MEDIA_DOWNLOAD_IDLE_TIMEOUT_MS = 30_000;
+
+async function fetchMatrixMediaBuffer(params: {
+  client: MatrixClient;
+  mxcUrl: string;
+  maxBytes: number;
+}): Promise<{ buffer: Buffer } | null> {
+  try {
+    const buffer = await params.client.downloadContent(params.mxcUrl, {
+      maxBytes: params.maxBytes,
+      readIdleTimeoutMs: MATRIX_MEDIA_DOWNLOAD_IDLE_TIMEOUT_MS,
+    });
+    return { buffer };
+  } catch (err) {
+    if (isMatrixMediaSizeLimitError(err)) {
+      throw err;
+    }
+    throw new Error(`Matrix media download failed: ${String(err)}`, { cause: err });
+  }
+}
+
+/**
+ * Download and decrypt encrypted media from a Matrix room.
+ * Uses the Matrix crypto adapter's decryptMedia helper.
+ */
+async function fetchEncryptedMediaBuffer(params: {
+  client: MatrixClient;
+  file: EncryptedFile;
+  maxBytes: number;
+}): Promise<{ buffer: Buffer } | null> {
+  if (!params.client.crypto) {
+    throw new Error("Cannot decrypt media: crypto not enabled");
+  }
+
+  const decrypted = await params.client.crypto.decryptMedia(
+    params.file as Parameters<typeof params.client.crypto.decryptMedia>[0],
+    {
+      maxBytes: params.maxBytes,
+      readIdleTimeoutMs: MATRIX_MEDIA_DOWNLOAD_IDLE_TIMEOUT_MS,
+    },
+  );
+
+  if (decrypted.byteLength > params.maxBytes) {
+    throw new MatrixMediaSizeLimitError();
+  }
+
+  return { buffer: decrypted };
+}
+
+export async function downloadMatrixMedia(params: {
+  client: MatrixClient;
+  mxcUrl: string;
+  contentType?: string;
+  sizeBytes?: number;
+  maxBytes: number;
+  file?: EncryptedFile;
+  originalFilename?: string;
+}): Promise<{
+  path: string;
+  contentType?: string;
+  placeholder: string;
+} | null> {
+  let fetched: { buffer: Buffer; headerType?: string } | null;
+  if (typeof params.sizeBytes === "number" && params.sizeBytes > params.maxBytes) {
+    throw new MatrixMediaSizeLimitError();
+  }
+
+  if (params.file) {
+    // Encrypted media
+    fetched = await fetchEncryptedMediaBuffer({
+      client: params.client,
+      file: params.file,
+      maxBytes: params.maxBytes,
+    });
+  } else {
+    // Unencrypted media
+    fetched = await fetchMatrixMediaBuffer({
+      client: params.client,
+      mxcUrl: params.mxcUrl,
+      maxBytes: params.maxBytes,
+    });
+  }
+
+  if (!fetched) {
+    return null;
+  }
+  const headerType = params.contentType ?? undefined;
+  const saved = await getMatrixRuntime().channel.media.saveMediaBuffer(
+    fetched.buffer,
+    headerType,
+    "inbound",
+    params.maxBytes,
+    params.originalFilename,
+  );
+  return {
+    path: saved.path,
+    contentType: saved.contentType,
+    placeholder: "[matrix media]",
+  };
+}