@archipelagolab/lobi 1.0.0

package/src/matrix/monitor/startup-verification.test.ts

@@ -0,0 +1,294 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it, vi } from "vitest";
+import { ensureMatrixStartupVerification } from "./startup-verification.js";
+
+function createTempStateDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "matrix-startup-verify-"));
+}
+
+function createStateFilePath(rootDir: string): string {
+  return path.join(rootDir, "startup-verification.json");
+}
+
+function createAuth(accountId = "default") {
+  return {
+    accountId,
+    homeserver: "https://matrix.example.org",
+    userId: "@bot:example.org",
+    accessToken: "token",
+    encryption: true,
+  };
+}
+
+type VerificationSummaryLike = {
+  id: string;
+  transactionId?: string;
+  isSelfVerification: boolean;
+  completed: boolean;
+  pending: boolean;
+};
+
+function createHarness(params?: {
+  verified?: boolean;
+  localVerified?: boolean;
+  crossSigningVerified?: boolean;
+  signedByOwner?: boolean;
+  requestVerification?: () => Promise<{ id: string; transactionId?: string }>;
+  listVerifications?: () => Promise<VerificationSummaryLike[]>;
+}) {
+  const requestVerification =
+    params?.requestVerification ??
+    (async () => ({
+      id: "verification-1",
+      transactionId: "txn-1",
+    }));
+  const listVerifications = params?.listVerifications ?? (async () => []);
+  const getOwnDeviceVerificationStatus = vi.fn(async () => ({
+    encryptionEnabled: true,
+    userId: "@bot:example.org",
+    deviceId: "DEVICE123",
+    verified: params?.verified === true,
+    localVerified: params?.localVerified ?? params?.verified === true,
+    crossSigningVerified: params?.crossSigningVerified ?? params?.verified === true,
+    signedByOwner: params?.signedByOwner ?? params?.verified === true,
+    recoveryKeyStored: false,
+    recoveryKeyCreatedAt: null,
+    recoveryKeyId: null,
+    backupVersion: null,
+    backup: {
+      serverVersion: null,
+      activeVersion: null,
+      trusted: null,
+      matchesDecryptionKey: null,
+      decryptionKeyCached: null,
+      keyLoadAttempted: false,
+      keyLoadError: null,
+    },
+  }));
+  return {
+    client: {
+      getOwnDeviceVerificationStatus,
+      crypto: {
+        listVerifications: vi.fn(listVerifications),
+        requestVerification: vi.fn(requestVerification),
+      },
+    },
+    getOwnDeviceVerificationStatus,
+  };
+}
+
+describe("ensureMatrixStartupVerification", () => {
+  it("skips automatic requests when the device is already verified", async () => {
+    const tempHome = createTempStateDir();
+    const harness = createHarness({ verified: true });
+
+    const result = await ensureMatrixStartupVerification({
+      client: harness.client as never,
+      auth: createAuth(),
+      accountConfig: {},
+      stateFilePath: createStateFilePath(tempHome),
+    });
+
+    expect(result.kind).toBe("verified");
+    expect(harness.client.crypto.requestVerification).not.toHaveBeenCalled();
+  });
+
+  it("still requests startup verification when trust is only local", async () => {
+    const tempHome = createTempStateDir();
+    const harness = createHarness({
+      verified: false,
+      localVerified: true,
+      crossSigningVerified: false,
+      signedByOwner: false,
+    });
+
+    const result = await ensureMatrixStartupVerification({
+      client: harness.client as never,
+      auth: createAuth(),
+      accountConfig: {},
+      stateFilePath: createStateFilePath(tempHome),
+    });
+
+    expect(result.kind).toBe("requested");
+    expect(harness.client.crypto.requestVerification).toHaveBeenCalledWith({ ownUser: true });
+  });
+
+  it("skips automatic requests when a self verification is already pending", async () => {
+    const tempHome = createTempStateDir();
+    const harness = createHarness({
+      listVerifications: async () => [
+        {
+          id: "verification-1",
+          transactionId: "txn-1",
+          isSelfVerification: true,
+          completed: false,
+          pending: true,
+        },
+      ],
+    });
+
+    const result = await ensureMatrixStartupVerification({
+      client: harness.client as never,
+      auth: createAuth(),
+      accountConfig: {},
+      stateFilePath: createStateFilePath(tempHome),
+    });
+
+    expect(result.kind).toBe("pending");
+    expect(harness.client.crypto.requestVerification).not.toHaveBeenCalled();
+  });
+
+  it("respects the startup verification cooldown", async () => {
+    const tempHome = createTempStateDir();
+    const harness = createHarness();
+    const initialNowMs = Date.parse("2026-03-08T12:00:00.000Z");
+    await ensureMatrixStartupVerification({
+      client: harness.client as never,
+      auth: createAuth(),
+      accountConfig: {},
+      stateFilePath: createStateFilePath(tempHome),
+      nowMs: initialNowMs,
+    });
+    expect(harness.client.crypto.requestVerification).toHaveBeenCalledTimes(1);
+
+    const second = await ensureMatrixStartupVerification({
+      client: harness.client as never,
+      auth: createAuth(),
+      accountConfig: {},
+      stateFilePath: createStateFilePath(tempHome),
+      nowMs: initialNowMs + 60_000,
+    });
+
+    expect(second.kind).toBe("cooldown");
+    expect(harness.client.crypto.requestVerification).toHaveBeenCalledTimes(1);
+  });
+
+  it("supports disabling startup verification requests", async () => {
+    const tempHome = createTempStateDir();
+    const harness = createHarness();
+    const stateFilePath = createStateFilePath(tempHome);
+    fs.writeFileSync(stateFilePath, JSON.stringify({ attemptedAt: "2026-03-08T12:00:00.000Z" }));
+
+    const result = await ensureMatrixStartupVerification({
+      client: harness.client as never,
+      auth: createAuth(),
+      accountConfig: {
+        startupVerification: "off",
+      },
+      stateFilePath,
+    });
+
+    expect(result.kind).toBe("disabled");
+    expect(harness.client.crypto.requestVerification).not.toHaveBeenCalled();
+    expect(fs.existsSync(stateFilePath)).toBe(false);
+  });
+
+  it("persists a successful startup verification request", async () => {
+    const tempHome = createTempStateDir();
+    const harness = createHarness();
+
+    const result = await ensureMatrixStartupVerification({
+      client: harness.client as never,
+      auth: createAuth(),
+      accountConfig: {},
+      stateFilePath: createStateFilePath(tempHome),
+      nowMs: Date.parse("2026-03-08T12:00:00.000Z"),
+    });
+
+    expect(result.kind).toBe("requested");
+    expect(harness.client.crypto.requestVerification).toHaveBeenCalledWith({ ownUser: true });
+
+    expect(fs.existsSync(createStateFilePath(tempHome))).toBe(true);
+  });
+
+  it("keeps startup verification failures non-fatal", async () => {
+    const tempHome = createTempStateDir();
+    const harness = createHarness({
+      requestVerification: async () => {
+        throw new Error("no other verified session");
+      },
+    });
+
+    const result = await ensureMatrixStartupVerification({
+      client: harness.client as never,
+      auth: createAuth(),
+      accountConfig: {},
+      stateFilePath: createStateFilePath(tempHome),
+    });
+
+    expect(result.kind).toBe("request-failed");
+    if (result.kind !== "request-failed") {
+      throw new Error(`Unexpected startup verification result: ${result.kind}`);
+    }
+    expect(result.error).toContain("no other verified session");
+
+    const cooledDown = await ensureMatrixStartupVerification({
+      client: harness.client as never,
+      auth: createAuth(),
+      accountConfig: {},
+      stateFilePath: createStateFilePath(tempHome),
+      nowMs: Date.now() + 60_000,
+    });
+
+    expect(cooledDown.kind).toBe("cooldown");
+  });
+
+  it("retries failed startup verification requests sooner than successful ones", async () => {
+    const tempHome = createTempStateDir();
+    const stateFilePath = createStateFilePath(tempHome);
+    const failingHarness = createHarness({
+      requestVerification: async () => {
+        throw new Error("no other verified session");
+      },
+    });
+
+    await ensureMatrixStartupVerification({
+      client: failingHarness.client as never,
+      auth: createAuth(),
+      accountConfig: {},
+      stateFilePath,
+      nowMs: Date.parse("2026-03-08T12:00:00.000Z"),
+    });
+
+    const retryingHarness = createHarness();
+    const result = await ensureMatrixStartupVerification({
+      client: retryingHarness.client as never,
+      auth: createAuth(),
+      accountConfig: {},
+      stateFilePath,
+      nowMs: Date.parse("2026-03-08T13:30:00.000Z"),
+    });
+
+    expect(result.kind).toBe("requested");
+    expect(retryingHarness.client.crypto.requestVerification).toHaveBeenCalledTimes(1);
+  });
+
+  it("clears the persisted startup state after verification succeeds", async () => {
+    const tempHome = createTempStateDir();
+    const stateFilePath = createStateFilePath(tempHome);
+    const unverified = createHarness();
+
+    await ensureMatrixStartupVerification({
+      client: unverified.client as never,
+      auth: createAuth(),
+      accountConfig: {},
+      stateFilePath,
+      nowMs: Date.parse("2026-03-08T12:00:00.000Z"),
+    });
+
+    expect(fs.existsSync(stateFilePath)).toBe(true);
+
+    const verified = createHarness({ verified: true });
+    const result = await ensureMatrixStartupVerification({
+      client: verified.client as never,
+      auth: createAuth(),
+      accountConfig: {},
+      stateFilePath,
+    });
+
+    expect(result.kind).toBe("verified");
+    expect(fs.existsSync(stateFilePath)).toBe(false);
+  });
+});

package/src/matrix/monitor/startup-verification.ts

@@ -0,0 +1,237 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { readJsonFileWithFallback, writeJsonFileAtomically } from "openclaw/plugin-sdk/json-store";
+import type { MatrixConfig } from "../../types.js";
+import { resolveMatrixStoragePaths } from "../client/storage.js";
+import type { MatrixAuth } from "../client/types.js";
+import { formatMatrixErrorMessage } from "../errors.js";
+import type { MatrixClient, MatrixOwnDeviceVerificationStatus } from "../sdk.js";
+
+const STARTUP_VERIFICATION_STATE_FILENAME = "startup-verification.json";
+const DEFAULT_STARTUP_VERIFICATION_MODE = "if-unverified" as const;
+const DEFAULT_STARTUP_VERIFICATION_COOLDOWN_HOURS = 24;
+const DEFAULT_STARTUP_VERIFICATION_FAILURE_COOLDOWN_MS = 60 * 60 * 1000;
+
+type MatrixStartupVerificationState = {
+  userId?: string | null;
+  deviceId?: string | null;
+  attemptedAt?: string;
+  outcome?: "requested" | "failed";
+  requestId?: string;
+  transactionId?: string;
+  error?: string;
+};
+
+export type MatrixStartupVerificationOutcome =
+  | {
+      kind: "disabled" | "verified" | "cooldown" | "pending" | "requested" | "request-failed";
+      verification: MatrixOwnDeviceVerificationStatus;
+      requestId?: string;
+      transactionId?: string;
+      error?: string;
+      retryAfterMs?: number;
+    }
+  | {
+      kind: "unsupported";
+      verification?: undefined;
+    };
+
+function normalizeCooldownHours(value: number | undefined): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return DEFAULT_STARTUP_VERIFICATION_COOLDOWN_HOURS;
+  }
+  return Math.max(0, value);
+}
+
+function resolveStartupVerificationStatePath(params: {
+  auth: MatrixAuth;
+  env?: NodeJS.ProcessEnv;
+}): string {
+  const storagePaths = resolveMatrixStoragePaths({
+    homeserver: params.auth.homeserver,
+    userId: params.auth.userId,
+    accessToken: params.auth.accessToken,
+    accountId: params.auth.accountId,
+    deviceId: params.auth.deviceId,
+    env: params.env,
+  });
+  return path.join(storagePaths.rootDir, STARTUP_VERIFICATION_STATE_FILENAME);
+}
+
+async function readStartupVerificationState(
+  filePath: string,
+): Promise<MatrixStartupVerificationState | null> {
+  const { value } = await readJsonFileWithFallback<MatrixStartupVerificationState | null>(
+    filePath,
+    null,
+  );
+  return value && typeof value === "object" ? value : null;
+}
+
+async function clearStartupVerificationState(filePath: string): Promise<void> {
+  await fs.rm(filePath, { force: true }).catch(() => {});
+}
+
+function resolveStateCooldownMs(
+  state: MatrixStartupVerificationState | null,
+  cooldownMs: number,
+): number {
+  if (state?.outcome === "failed") {
+    return Math.min(cooldownMs, DEFAULT_STARTUP_VERIFICATION_FAILURE_COOLDOWN_MS);
+  }
+  return cooldownMs;
+}
+
+function resolveRetryAfterMs(params: {
+  attemptedAt?: string;
+  cooldownMs: number;
+  nowMs: number;
+}): number | undefined {
+  const attemptedAtMs = Date.parse(params.attemptedAt ?? "");
+  if (!Number.isFinite(attemptedAtMs)) {
+    return undefined;
+  }
+  const remaining = attemptedAtMs + params.cooldownMs - params.nowMs;
+  return remaining > 0 ? remaining : undefined;
+}
+
+function shouldHonorCooldown(params: {
+  state: MatrixStartupVerificationState | null;
+  verification: MatrixOwnDeviceVerificationStatus;
+  stateCooldownMs: number;
+  nowMs: number;
+}): boolean {
+  if (!params.state || params.stateCooldownMs <= 0) {
+    return false;
+  }
+  if (
+    params.state.userId &&
+    params.verification.userId &&
+    params.state.userId !== params.verification.userId
+  ) {
+    return false;
+  }
+  if (
+    params.state.deviceId &&
+    params.verification.deviceId &&
+    params.state.deviceId !== params.verification.deviceId
+  ) {
+    return false;
+  }
+  return (
+    resolveRetryAfterMs({
+      attemptedAt: params.state.attemptedAt,
+      cooldownMs: params.stateCooldownMs,
+      nowMs: params.nowMs,
+    }) !== undefined
+  );
+}
+
+function hasPendingSelfVerification(
+  verifications: Array<{
+    isSelfVerification: boolean;
+    completed: boolean;
+    pending: boolean;
+  }>,
+): boolean {
+  return verifications.some(
+    (entry) => entry.isSelfVerification && !entry.completed && entry.pending,
+  );
+}
+
+export async function ensureMatrixStartupVerification(params: {
+  client: Pick<MatrixClient, "crypto" | "getOwnDeviceVerificationStatus">;
+  auth: MatrixAuth;
+  accountConfig: Pick<MatrixConfig, "startupVerification" | "startupVerificationCooldownHours">;
+  env?: NodeJS.ProcessEnv;
+  nowMs?: number;
+  stateFilePath?: string;
+}): Promise<MatrixStartupVerificationOutcome> {
+  if (params.auth.encryption !== true || !params.client.crypto) {
+    return { kind: "unsupported" };
+  }
+
+  const verification = await params.client.getOwnDeviceVerificationStatus();
+  const statePath =
+    params.stateFilePath ??
+    resolveStartupVerificationStatePath({
+      auth: params.auth,
+      env: params.env,
+    });
+
+  if (verification.verified) {
+    await clearStartupVerificationState(statePath);
+    return {
+      kind: "verified",
+      verification,
+    };
+  }
+
+  const mode = params.accountConfig.startupVerification ?? DEFAULT_STARTUP_VERIFICATION_MODE;
+  if (mode === "off") {
+    await clearStartupVerificationState(statePath);
+    return {
+      kind: "disabled",
+      verification,
+    };
+  }
+
+  const verifications = await params.client.crypto.listVerifications().catch(() => []);
+  if (hasPendingSelfVerification(verifications)) {
+    return {
+      kind: "pending",
+      verification,
+    };
+  }
+
+  const cooldownHours = normalizeCooldownHours(
+    params.accountConfig.startupVerificationCooldownHours,
+  );
+  const cooldownMs = cooldownHours * 60 * 60 * 1000;
+  const nowMs = params.nowMs ?? Date.now();
+  const state = await readStartupVerificationState(statePath);
+  const stateCooldownMs = resolveStateCooldownMs(state, cooldownMs);
+  if (shouldHonorCooldown({ state, verification, stateCooldownMs, nowMs })) {
+    return {
+      kind: "cooldown",
+      verification,
+      retryAfterMs: resolveRetryAfterMs({
+        attemptedAt: state?.attemptedAt,
+        cooldownMs: stateCooldownMs,
+        nowMs,
+      }),
+    };
+  }
+
+  try {
+    const request = await params.client.crypto.requestVerification({ ownUser: true });
+    await writeJsonFileAtomically(statePath, {
+      userId: verification.userId,
+      deviceId: verification.deviceId,
+      attemptedAt: new Date(nowMs).toISOString(),
+      outcome: "requested",
+      requestId: request.id,
+      transactionId: request.transactionId,
+    } satisfies MatrixStartupVerificationState);
+    return {
+      kind: "requested",
+      verification,
+      requestId: request.id,
+      transactionId: request.transactionId ?? undefined,
+    };
+  } catch (err) {
+    const error = formatMatrixErrorMessage(err);
+    await writeJsonFileAtomically(statePath, {
+      userId: verification.userId,
+      deviceId: verification.deviceId,
+      attemptedAt: new Date(nowMs).toISOString(),
+      outcome: "failed",
+      error,
+    } satisfies MatrixStartupVerificationState).catch(() => {});
+    return {
+      kind: "request-failed",
+      verification,
+      error,
+    };
+  }
+}