@frockbot/plugin-user-machine 0.0.0 → 0.1.1

package/src/storage-keys.ts

@@ -0,0 +1,102 @@
+// The User Durable Object storage keys the registered-machine Package owns.
+//
+// "The User's Durable Object is the authority for everything User-scoped:
+// Package availability, Connections, credentials, the Computer assignment,
+// User settings, quotas" — a machine is a User asset, so its registry, its
+// command queue and its results live here and nowhere else. The keys live in
+// the Package rather than in `@frockbot/kernel-do` for the same reason
+// `plugin-routines/src/storage-keys.ts` does: the kernel holds no product
+// policy and imports no Package.
+//
+// None of these prefixes collide with the landed set (`user:`, `memory:`,
+// `settings:`, `connection:`, `credential:`, `routine-*`, `template-*`).
+
+/** One `MachineRecordV1`: the registry row. */
+export const MACHINE_PREFIX = "machine:";
+/** One queued `MachineCommandV1`, oldest first. */
+export const MACHINE_QUEUE_PREFIX = "machine-queue:";
+/** One `MachineCommandResultV1`, keyed by the command it answers. */
+export const MACHINE_RESULT_PREFIX = "machine-result:";
+/** One unspent `MachinePairingRecordV1`. */
+export const MACHINE_PAIRING_PREFIX = "machine-pair:";
+/**
+ * How many times one command's lease has expired.
+ *
+ * It is a key of its own rather than a field on the command because
+ * `MachineCommandV1` is the wire DTO, decoded exact-key at three runtimes: a
+ * recovery counter is the backend's bookkeeping and has no business being
+ * something a device agent is handed, or could send.
+ */
+export const MACHINE_REQUEUE_PREFIX = "machine-requeue:";
+/**
+ * One day's dispatch count. The per-day quota is a rate, and a rate needs a
+ * durable counter rather than a listing: the queue drains, so counting what is
+ * in it would let a Bot spend the day's budget many times over.
+ */
+export const MACHINE_USAGE_PREFIX = "machine-usage:";
+
+export function machineKeyV1(machineId: string): string {
+  return `${MACHINE_PREFIX}${machineId}`;
+}
+
+export function machinePairingKeyV1(machineId: string): string {
+  return `${MACHINE_PAIRING_PREFIX}${machineId}`;
+}
+
+export function machineResultKeyV1(commandId: string): string {
+  return `${MACHINE_RESULT_PREFIX}${commandId}`;
+}
+
+export function machineRequeueKeyV1(commandId: string): string {
+  return `${MACHINE_REQUEUE_PREFIX}${commandId}`;
+}
+
+export function machineQueuePrefixV1(machineId: string): string {
+  return `${MACHINE_QUEUE_PREFIX}${machineId}:`;
+}
+
+/**
+ * Queue keys ascend, so a prefix listing answers oldest-first: a machine that
+ * has been asleep drains its commands in the order they were approved.
+ */
+const QUEUE_SEQUENCE_CEILING = 1_000_000_000;
+
+export function machineQueueKeyV1(machineId: string, seq: number): string {
+  if (!Number.isSafeInteger(seq) || seq < 0 || seq >= QUEUE_SEQUENCE_CEILING) {
+    throw new Error("machine queue sequence is out of range");
+  }
+  return `${machineQueuePrefixV1(machineId)}${String(seq).padStart(10, "0")}`;
+}
+
+/** The sequence the next queued command takes, given the keys already held. */
+export function nextMachineQueueSequenceV1(keys: readonly string[]): number {
+  let highest = -1;
+  for (const key of keys) {
+    const encoded = Number(key.slice(key.lastIndexOf(":") + 1));
+    if (Number.isSafeInteger(encoded)) highest = Math.max(highest, encoded);
+  }
+  return highest + 1;
+}
+
+/** The UTC day a dispatch counts against. Machines cross time zones; the quota does not. */
+/**
+ * One finished command waiting to be told to the Bot that asked for it.
+ *
+ * A durable outbox rather than a call: this object holds the queue, and the
+ * Bot Durable Object namespace belongs to the adapter. The Worker that just
+ * answered the machine drains it, which keeps a Durable Object from holding a
+ * reference to another one open across a request.
+ */
+export const MACHINE_DELIVERY_PREFIX = "machine-delivery:";
+
+export function machineDeliveryKeyV1(commandId: string): string {
+  return `${MACHINE_DELIVERY_PREFIX}${commandId}`;
+}
+
+export function machineUsageDayV1(now: number | Date): string {
+  return new Date(now).toISOString().slice(0, 10);
+}
+
+export function machineUsageKeyV1(now: number | Date): string {
+  return `${MACHINE_USAGE_PREFIX}${machineUsageDayV1(now)}`;
+}

package/src/store.test.ts

@@ -0,0 +1,507 @@
+import { beforeEach, describe, expect, test } from "bun:test";
+import {
+  MACHINE_LIMITS_V1,
+  machineConnectedV1,
+  type MachineCommandV1,
+} from "@frockbot/machine-protocol";
+import {
+  claimMachineCommandV1,
+  dispatchMachineCommandV1,
+  enrollMachineV1,
+  listMachineRecordsV1,
+  pendingMachineCommandsV1,
+  readMachineRecordV1,
+  readMachineResultV1,
+  recordMachineResultV1,
+  revokeMachineV1,
+  sweepMachineLeasesV1,
+  touchMachineV1,
+  writeMachinePairingV1,
+  MachineRegistryError,
+} from "./store.ts";
+import { createMemoryMachineStorageV1 } from "./testing.ts";
+import { machineQueuePrefixV1, machineResultKeyV1 } from "./storage-keys.ts";
+
+const USER = "store-user";
+/** A `SHA-256` shaped digest: the record decoder insists on one. */
+const digestFor = (seed: string): string =>
+  [...seed]
+    .reduce((hash, ch) => hash + ch.charCodeAt(0), 0)
+    .toString(16)
+    .padStart(2, "0")
+    .repeat(32)
+    .slice(0, 64);
+const T0 = Date.parse("2026-09-01T00:00:00.000Z");
+
+let storage = createMemoryMachineStorageV1();
+
+beforeEach(() => {
+  storage = createMemoryMachineStorageV1();
+});
+
+async function register(
+  machineId: string,
+  options: {
+    now?: number;
+    capabilities?: ("exec" | "files" | "messages")[];
+  } = {},
+) {
+  const now = options.now ?? T0;
+  await writeMachinePairingV1(storage, {
+    userId: USER,
+    machineId,
+    codeDigest: digestFor(`code-${machineId}`),
+    now,
+  });
+  return enrollMachineV1(storage, {
+    userId: USER,
+    machineId,
+    enrollment: {
+      schemaVersion: 1,
+      code: `code-${machineId}`,
+      label: `${machineId}.local`,
+      platform: "macos",
+      agentVersion: "0.0.1",
+      capabilities: options.capabilities ?? ["exec", "files"],
+    },
+    codeDigest: digestFor(`code-${machineId}`),
+    tokenDigest: digestFor(`token-${machineId}`),
+    now,
+  });
+}
+
+function command(
+  machineId: string,
+  commandId: string,
+  overrides: Partial<MachineCommandV1> = {},
+): MachineCommandV1 {
+  return {
+    schemaVersion: 1,
+    commandId,
+    machineId,
+    botId: "bot",
+    runId: "run",
+    turn: 1,
+    approvalId: commandId,
+    op: {
+      kind: "exec",
+      command: "git status",
+      timeoutMs: 30_000,
+      maxOutputBytes: 4_096,
+    },
+    issuedAt: new Date(T0).toISOString(),
+    status: "queued",
+    ...overrides,
+  };
+}
+
+describe("the registry", () => {
+  test("enrollment spends the pairing offer exactly once", async () => {
+    const machineId = "m-1";
+    const record = await register(machineId);
+    expect(record).toMatchObject({ machineId, userId: USER, keyVersion: 1 });
+    // The offer is gone, so the same code cannot register a second machine.
+    await expect(
+      enrollMachineV1(storage, {
+        userId: USER,
+        machineId,
+        enrollment: {
+          schemaVersion: 1,
+          code: `code-${machineId}`,
+          label: "again.local",
+          platform: "macos",
+          agentVersion: "0.0.1",
+          capabilities: ["exec"],
+        },
+        codeDigest: digestFor(`code-${machineId}`),
+        tokenDigest: digestFor("token-again"),
+        now: T0,
+      }),
+    ).rejects.toThrow(/invalid or has expired/);
+  });
+
+  test("an expired offer, another User's, and a different code are all refused", async () => {
+    await writeMachinePairingV1(storage, {
+      userId: USER,
+      machineId: "m-expired",
+      codeDigest: digestFor("digest"),
+      now: T0,
+    });
+    const enrollment = {
+      schemaVersion: 1 as const,
+      code: "code",
+      label: "late.local",
+      platform: "macos" as const,
+      agentVersion: "0.0.1",
+      capabilities: ["exec" as const],
+    };
+    const attempt = (input: {
+      userId?: string;
+      codeDigest?: string;
+      now?: number;
+    }) =>
+      enrollMachineV1(storage, {
+        userId: input.userId ?? USER,
+        machineId: "m-expired",
+        enrollment,
+        codeDigest: input.codeDigest ?? digestFor("digest"),
+        tokenDigest: digestFor("token"),
+        now: input.now ?? T0,
+      });
+    await expect(
+      attempt({ now: T0 + MACHINE_LIMITS_V1.pairingTtlMs + 1 }),
+    ).rejects.toThrow(MachineRegistryError);
+    await expect(attempt({ userId: "someone-else" })).rejects.toThrow(
+      MachineRegistryError,
+    );
+    await expect(attempt({ codeDigest: digestFor("another") })).rejects.toThrow(
+      MachineRegistryError,
+    );
+    // …and the untouched offer still works, so none of the refusals spent it.
+    await expect(attempt({})).resolves.toMatchObject({
+      machineId: "m-expired",
+    });
+  });
+
+  test("the machine quota refuses the ninth registration", async () => {
+    for (let index = 0; index < MACHINE_LIMITS_V1.maxMachinesPerUser; index++) {
+      await register(`m-${index}`);
+    }
+    await expect(register("m-over")).rejects.toThrow(/^Refused: /);
+    // A revoked machine frees its slot: the row stays as evidence, the quota
+    // counts what is live.
+    await revokeMachineV1(storage, "m-0", T0);
+    await expect(register("m-freed")).resolves.toMatchObject({
+      machineId: "m-freed",
+    });
+  });
+
+  test("presence is arithmetic over lastSeenAt, and a revoked machine is never connected", async () => {
+    await register("m-live");
+    const fresh = await readMachineRecordV1(storage, "m-live");
+    expect(machineConnectedV1(fresh!, T0)).toBe(true);
+    expect(
+      machineConnectedV1(fresh!, T0 + MACHINE_LIMITS_V1.presenceTtlMs + 1),
+    ).toBe(false);
+    await touchMachineV1(storage, "m-live", T0 + 60_000);
+    const touched = await readMachineRecordV1(storage, "m-live");
+    expect(machineConnectedV1(touched!, T0 + 60_000)).toBe(true);
+    const revoked = await revokeMachineV1(storage, "m-live", T0 + 60_000);
+    expect(revoked.keyVersion).toBe(2);
+    expect(machineConnectedV1(revoked, T0 + 60_000)).toBe(false);
+  });
+
+  test("revocation purges the queue and leaves the row", async () => {
+    await register("m-revoke");
+    await dispatchMachineCommandV1(storage, command("m-revoke", "c-1"), T0);
+    await revokeMachineV1(storage, "m-revoke", T0);
+    expect(
+      storage
+        .keys()
+        .filter((key) => key.startsWith(machineQueuePrefixV1("m-revoke"))),
+    ).toEqual([]);
+    expect(await listMachineRecordsV1(storage)).toHaveLength(1);
+  });
+});
+
+describe("the queue", () => {
+  test("a dispatch is idempotent on commandId", async () => {
+    await register("m-q");
+    const first = await dispatchMachineCommandV1(
+      storage,
+      command("m-q", "c-1"),
+      T0,
+    );
+    const second = await dispatchMachineCommandV1(
+      storage,
+      command("m-q", "c-1"),
+      T0,
+    );
+    expect(first.status).toBe("queued");
+    expect(second.status).toBe("duplicate");
+    expect(await pendingMachineCommandsV1(storage, "m-q")).toHaveLength(1);
+  });
+
+  test("the queue refuses visibly at its depth limit", async () => {
+    await register("m-full");
+    for (let index = 0; index < MACHINE_LIMITS_V1.maxQueue; index++) {
+      const outcome = await dispatchMachineCommandV1(
+        storage,
+        command("m-full", `c-${index}`),
+        T0,
+      );
+      expect(outcome.status).toBe("queued");
+    }
+    const refused = await dispatchMachineCommandV1(
+      storage,
+      command("m-full", "c-over"),
+      T0,
+    );
+    expect(refused).toMatchObject({ status: "refused" });
+    // The wording is what `plugin-audit` classifies `refused` rather than
+    // `error`, so it is asserted rather than assumed.
+    expect(refused.status === "refused" ? refused.reason : "").toMatch(
+      /^Refused: /,
+    );
+  });
+
+  test("a machine that is unknown, revoked or lacks the capability is refused", async () => {
+    expect(
+      await dispatchMachineCommandV1(storage, command("m-none", "c"), T0),
+    ).toMatchObject({ status: "refused" });
+    await register("m-files", { capabilities: ["files"] });
+    expect(
+      await dispatchMachineCommandV1(storage, command("m-files", "c"), T0),
+    ).toMatchObject({ status: "refused" });
+    await register("m-gone");
+    await revokeMachineV1(storage, "m-gone", T0);
+    expect(
+      await dispatchMachineCommandV1(storage, command("m-gone", "c"), T0),
+    ).toMatchObject({ status: "refused" });
+  });
+
+  test("the daily quota counts dispatches rather than the queue's depth", async () => {
+    await register("m-day");
+    // Drain after each dispatch, so the queue is never deep: only a durable
+    // counter can notice a Bot that has asked five hundred times today.
+    for (let index = 0; index < 4; index++) {
+      await dispatchMachineCommandV1(
+        storage,
+        command("m-day", `c-${index}`),
+        T0,
+      );
+      await claimMachineCommandV1(storage, "m-day", `c-${index}`, T0);
+      await recordMachineResultV1(
+        storage,
+        "m-day",
+        {
+          schemaVersion: 1,
+          commandId: `c-${index}`,
+          finishedAt: new Date(T0).toISOString(),
+          outcome: "ok",
+          truncated: false,
+          exitCode: 0,
+        },
+        T0,
+      );
+    }
+    const usage = storage
+      .keys()
+      .filter((key) => key.startsWith("machine-usage:"));
+    expect(usage).toHaveLength(1);
+    expect(await storage.get(usage[0]!)).toMatchObject({ count: 4 });
+  });
+});
+
+describe("claims, results and leases", () => {
+  test("the second claim answers already-claimed with the first claim's lease", async () => {
+    await register("m-claim");
+    await dispatchMachineCommandV1(storage, command("m-claim", "c-1"), T0);
+    const first = await claimMachineCommandV1(storage, "m-claim", "c-1", T0);
+    const second = await claimMachineCommandV1(
+      storage,
+      "m-claim",
+      "c-1",
+      T0 + 5,
+    );
+    expect(first.status).toBe("claimed");
+    expect(second).toMatchObject({
+      status: "already-claimed",
+      leaseExpiresAt: first.leaseExpiresAt,
+    });
+    // A claimed command is not offered to the next poll.
+    expect(await pendingMachineCommandsV1(storage, "m-claim")).toEqual([]);
+  });
+
+  test("a result is recorded once and replayed thereafter", async () => {
+    await register("m-result");
+    await dispatchMachineCommandV1(storage, command("m-result", "c-1"), T0);
+    await claimMachineCommandV1(storage, "m-result", "c-1", T0);
+    const result = {
+      schemaVersion: 1 as const,
+      commandId: "c-1",
+      finishedAt: new Date(T0 + 1_000).toISOString(),
+      outcome: "ok" as const,
+      truncated: false,
+      exitCode: 0,
+      stdout: "clean",
+    };
+    const first = await recordMachineResultV1(storage, "m-result", result, T0);
+    expect(first.receipt.status).toBe("recorded");
+    const replay = await recordMachineResultV1(
+      storage,
+      "m-result",
+      { ...result, stdout: "different" },
+      T0,
+    );
+    expect(replay.receipt.status).toBe("replayed");
+    // The replay changed nothing: the first answer is still the answer.
+    expect(await readMachineResultV1(storage, "c-1")).toMatchObject({
+      stdout: "clean",
+    });
+    expect(
+      storage
+        .keys()
+        .filter((key) => key.startsWith(machineQueuePrefixV1("m-result"))),
+    ).toEqual([]);
+  });
+
+  test("a lease expiry re-queues once and then terminates as unknown", async () => {
+    await register("m-lease");
+    await dispatchMachineCommandV1(storage, command("m-lease", "c-1"), T0);
+    await claimMachineCommandV1(storage, "m-lease", "c-1", T0);
+
+    const early = await sweepMachineLeasesV1(
+      storage,
+      "m-lease",
+      T0 + MACHINE_LIMITS_V1.leaseMs - 1,
+    );
+    expect(early).toMatchObject({ requeued: [], terminated: [] });
+
+    const first = await sweepMachineLeasesV1(
+      storage,
+      "m-lease",
+      T0 + MACHINE_LIMITS_V1.leaseMs + 1,
+    );
+    expect(first.requeued).toEqual(["c-1"]);
+    expect(await pendingMachineCommandsV1(storage, "m-lease")).toHaveLength(1);
+
+    const second = T0 + MACHINE_LIMITS_V1.leaseMs + 2;
+    await claimMachineCommandV1(storage, "m-lease", "c-1", second);
+    const terminal = await sweepMachineLeasesV1(
+      storage,
+      "m-lease",
+      second + MACHINE_LIMITS_V1.leaseMs + 1,
+    );
+    expect(terminal).toMatchObject({ requeued: [], terminated: ["c-1"] });
+    expect(await pendingMachineCommandsV1(storage, "m-lease")).toEqual([]);
+    // The terminal fact is durable and says the outcome is unknown, rather
+    // than the command quietly disappearing off somebody's laptop.
+    expect(await storage.get(machineResultKeyV1("c-1"))).toMatchObject({
+      outcome: "error",
+      message: expect.stringContaining("unknown"),
+    });
+  });
+
+  test("a claim or a result for a command that is not queued is a 404", async () => {
+    await register("m-missing");
+    await expect(
+      claimMachineCommandV1(storage, "m-missing", "nope", T0),
+    ).rejects.toThrow(MachineRegistryError);
+    await expect(
+      recordMachineResultV1(
+        storage,
+        "m-missing",
+        {
+          schemaVersion: 1,
+          commandId: "nope",
+          finishedAt: new Date(T0).toISOString(),
+          outcome: "ok",
+          truncated: false,
+        },
+        T0,
+      ),
+    ).rejects.toThrow(MachineRegistryError);
+  });
+});
+
+describe("the Messages permission report (register row 57g)", () => {
+  const permissions = {
+    schemaVersion: 1 as const,
+    fullDiskAccess: true,
+    automation: false,
+    checkedAt: "2026-09-01T00:00:00.000Z",
+    detail: "Automation over Messages.app has not been granted",
+  };
+
+  async function answerCheck(
+    outcome: "ok" | "refused",
+    stdout: string,
+  ): Promise<void> {
+    await register("mac-1", { capabilities: ["exec", "files", "messages"] });
+    await dispatchMachineCommandV1(
+      storage,
+      command("mac-1", "c-messages", {
+        op: { kind: "messages", call: { kind: "check-permissions" } },
+      }),
+      T0,
+    );
+    await recordMachineResultV1(
+      storage,
+      "mac-1",
+      {
+        schemaVersion: 1,
+        commandId: "c-messages",
+        finishedAt: "2026-09-01T00:00:01.000Z",
+        outcome,
+        truncated: false,
+        stdout,
+      },
+      T0,
+    );
+  }
+
+  test("an answered check updates the registry row, and only it can", async () => {
+    await answerCheck(
+      "ok",
+      JSON.stringify({ kind: "permissions", permissions }),
+    );
+    expect(
+      (await readMachineRecordV1(storage, "mac-1"))?.messagesPermissions,
+    ).toEqual(permissions);
+  });
+
+  test("a check the machine refused grants nothing", async () => {
+    await answerCheck(
+      "refused",
+      JSON.stringify({ kind: "permissions", permissions }),
+    );
+    expect(
+      (await readMachineRecordV1(storage, "mac-1"))?.messagesPermissions,
+    ).toBeUndefined();
+  });
+
+  test("a result that is not a permission report leaves the row alone", async () => {
+    await register("mac-2", { capabilities: ["exec", "files", "messages"] });
+    await dispatchMachineCommandV1(
+      storage,
+      command("mac-2", "c-read", {
+        op: { kind: "messages", call: { kind: "activity", limit: 5 } },
+      }),
+      T0,
+    );
+    await recordMachineResultV1(
+      storage,
+      "mac-2",
+      {
+        schemaVersion: 1,
+        commandId: "c-read",
+        finishedAt: "2026-09-01T00:00:01.000Z",
+        outcome: "ok",
+        truncated: false,
+        // A read cannot grant itself a permission by saying it has one.
+        stdout: JSON.stringify({ kind: "permissions", permissions }),
+      },
+      T0,
+    );
+    expect(
+      (await readMachineRecordV1(storage, "mac-2"))?.messagesPermissions,
+    ).toBeUndefined();
+  });
+
+  test("a machine that never reported messages cannot be sent a messages op", async () => {
+    await register("mac-3");
+    expect(
+      await dispatchMachineCommandV1(
+        storage,
+        command("mac-3", "c-x", {
+          op: { kind: "messages", call: { kind: "activity", limit: 5 } },
+        }),
+        T0,
+      ),
+    ).toEqual({
+      status: "refused",
+      reason: "Refused: this machine does not report the messages capability.",
+    });
+  });
+});