@frockbot/plugin-user-machine 0.0.0 → 0.1.0

package/src/target.ts

@@ -0,0 +1,86 @@
+// One machine, as the tool that is about to ask for it needs to see it.
+//
+// A control tool has five things to check before it may put a card in front of
+// a person — is the machine registered, is it revoked, is it connected, does it
+// report the capability the op needs, and is the User inside their quota — and
+// four of them are facts only the User Durable Object holds. Resolving them one
+// at a time would be four round trips and four chances to answer against a
+// different instant, so this is the single narrow view the tool reads: the
+// registry row, and the two counters the quota is arithmetic over.
+//
+// It carries no token digest, no key version and no user id. A projection hands
+// out what the caller renders a decision from, and nothing that proves
+// anything.
+import {
+  MachineDecodeError,
+  decodeMachineListEntryV1,
+  type MachineListEntryV1,
+} from "@frockbot/machine-protocol";
+
+export interface MachineTargetViewV1 {
+  schemaVersion: 1;
+  machineId: string;
+  /** Absent when this User has no machine by that id. */
+  entry?: MachineListEntryV1;
+  /** Commands already waiting on this machine's queue. */
+  queuedCommands: number;
+  /** Commands this User has dispatched today, across every machine. */
+  commandsToday: number;
+  serverTime: string;
+}
+
+export function decodeMachineTargetViewV1(
+  input: unknown,
+  label = "machine target",
+): MachineTargetViewV1 {
+  if (typeof input !== "object" || input === null || Array.isArray(input)) {
+    throw new MachineDecodeError(`${label} must be an object`);
+  }
+  const value = input as Record<string, unknown>;
+  for (const key of Object.keys(value)) {
+    if (
+      ![
+        "schemaVersion",
+        "machineId",
+        "entry",
+        "queuedCommands",
+        "commandsToday",
+        "serverTime",
+      ].includes(key)
+    ) {
+      throw new MachineDecodeError(`${label} has an unexpected key "${key}"`);
+    }
+  }
+  if (value.schemaVersion !== 1) {
+    throw new MachineDecodeError(`${label} schemaVersion is unsupported`);
+  }
+  if (typeof value.machineId !== "string" || value.machineId.length === 0) {
+    throw new MachineDecodeError(`${label} machineId must be a string`);
+  }
+  const count = (candidate: unknown, name: string): number => {
+    if (
+      typeof candidate !== "number" ||
+      !Number.isSafeInteger(candidate) ||
+      candidate < 0
+    ) {
+      throw new MachineDecodeError(`${label} ${name} is invalid`);
+    }
+    return candidate;
+  };
+  if (
+    typeof value.serverTime !== "string" ||
+    Number.isNaN(Date.parse(value.serverTime))
+  ) {
+    throw new MachineDecodeError(`${label} serverTime is not a timestamp`);
+  }
+  return {
+    schemaVersion: 1,
+    machineId: value.machineId,
+    ...(value.entry === undefined
+      ? {}
+      : { entry: decodeMachineListEntryV1(value.entry, `${label} entry`) }),
+    queuedCommands: count(value.queuedCommands, "queuedCommands"),
+    commandsToday: count(value.commandsToday, "commandsToday"),
+    serverTime: value.serverTime,
+  };
+}

package/src/testing.ts

@@ -0,0 +1,352 @@
+// The stub device agent, and the in-memory storage the store is tested on.
+//
+// `MachineAgentDriverV1` is the honest half of "no native binary in slice R".
+// It is not a mock of the protocol: it speaks the real wire, over an injected
+// `fetch`, against the real routes — pair, enroll, poll, claim, result — and
+// decodes every answer with the same decoders the desktop agent will. What it
+// does *not* do is shell out. So the untested surface is `child_process` and
+// nothing else, and the day a real agent lands it can be checked byte for byte
+// against this one.
+//
+// It is deliberately scriptable in the ways a laptop actually fails: a command
+// it claims and never answers (the machine slept), one it never claims (the
+// poll was lost), one it answers twice (the POST was retried), and one it
+// claims twice (two agents, or one agent and its own retry).
+
+import {
+  MACHINE_LIMITS_V1,
+  decodeMachineClaimReceiptV1,
+  decodeMachineEnrollmentReceiptV1,
+  decodeMachineListViewV1,
+  decodeMachinePairingOfferV1,
+  decodeMachinePollResultV1,
+  decodeMachineResultReceiptV1,
+  machineRoutePathV1,
+  type MachineCapabilityV1,
+  type MachineClaimReceiptV1,
+  type MachineCommandResultV1,
+  type MachineCommandV1,
+  type MachineListViewV1,
+  type MachinePairingOfferV1,
+  type MachinePlatformV1,
+  type MachineResultReceiptV1,
+} from "@frockbot/machine-protocol";
+import type { MachineStorageV1, MachineStorageWritesV1 } from "./store.js";
+
+// ---------------------------------------------------------------------------
+// Storage
+// ---------------------------------------------------------------------------
+
+export interface MemoryMachineStorageV1 extends MachineStorageV1 {
+  /** Every key currently held, sorted. Useful for asserting purges. */
+  keys(): string[];
+}
+
+function reads(map: Map<string, unknown>): MachineStorageWritesV1 {
+  return {
+    get<T>(key: string): Promise<T | undefined> {
+      return Promise.resolve(map.get(key) as T | undefined);
+    },
+    list<T>(options: {
+      prefix: string;
+      limit?: number;
+    }): Promise<Map<string, T>> {
+      const entries = [...map.entries()]
+        .filter(([key]) => key.startsWith(options.prefix))
+        .sort(([left], [right]) => left.localeCompare(right))
+        .slice(0, options.limit ?? Number.POSITIVE_INFINITY);
+      return Promise.resolve(new Map(entries as Array<[string, T]>));
+    },
+    put(key: string, value: unknown): Promise<void> {
+      map.set(key, structuredClone(value));
+      return Promise.resolve();
+    },
+    delete(key: string): Promise<boolean> {
+      return Promise.resolve(map.delete(key));
+    },
+  };
+}
+
+/** The Durable Object's storage contract and nothing more. */
+export function createMemoryMachineStorageV1(): MemoryMachineStorageV1 {
+  const map = new Map<string, unknown>();
+  const base = reads(map);
+  return {
+    ...base,
+    keys: () => [...map.keys()].sort(),
+    async transaction<T>(
+      closure: (transaction: MachineStorageWritesV1) => Promise<T>,
+    ): Promise<T> {
+      const snapshot = new Map(map);
+      try {
+        return await closure(base);
+      } catch (error) {
+        map.clear();
+        for (const [key, value] of snapshot) map.set(key, value);
+        throw error;
+      }
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The stub agent
+// ---------------------------------------------------------------------------
+
+/** What the scripted agent does with one command it was handed. */
+export type MachineAgentActionV1 =
+  | {
+      kind: "result";
+      result: Omit<MachineCommandResultV1, "schemaVersion" | "commandId">;
+      /** Post the result twice, as a retried POST does. */
+      twice?: boolean;
+    }
+  /** Claim it and never answer: the laptop slept. The lease is what recovers. */
+  | { kind: "vanish" }
+  /** Claim it twice, as two agents — or one agent and its own retry — would. */
+  | {
+      kind: "double-claim";
+      result: Omit<MachineCommandResultV1, "schemaVersion" | "commandId">;
+    }
+  /** Leave it queued: the poll answer was lost before it was acted on. */
+  | { kind: "ignore" };
+
+export interface MachineAgentDriverOptionsV1 {
+  /** Injected: `SELF.fetch` in workerd, a stub in a unit test. */
+  fetch(input: string, init?: RequestInit): Promise<Response>;
+  /** The origin every path is resolved against. */
+  origin: string;
+  label?: string;
+  platform?: MachinePlatformV1;
+  agentVersion?: string;
+  capabilities?: MachineCapabilityV1[];
+  /** What to do with a command. Defaults to exit 0 with empty output. */
+  handle?(command: MachineCommandV1): Promise<MachineAgentActionV1>;
+  now?(): number;
+}
+
+export interface MachineAgentRunSummaryV1 {
+  delivered: MachineCommandV1[];
+  claimed: string[];
+  alreadyClaimed: string[];
+  reported: string[];
+  replayed: string[];
+}
+
+export class MachineAgentError extends Error {
+  override readonly name = "MachineAgentError";
+  readonly status: number;
+  readonly body: string;
+  constructor(status: number, body: string) {
+    super(`machine agent request failed with ${status}: ${body.slice(0, 200)}`);
+    this.status = status;
+    this.body = body;
+  }
+}
+
+/**
+ * A device agent, in TypeScript, with no `child_process`.
+ *
+ * It holds exactly what a real one does: its machine id and the token it was
+ * handed at enrollment. Both are public here — a test needs to present a
+ * revoked token and a forged one — and neither is ever written anywhere.
+ */
+export class MachineAgentDriverV1 {
+  machineId: string | undefined;
+  token: string | undefined;
+  /** Every command this agent has been delivered, in order. */
+  readonly delivered: MachineCommandV1[] = [];
+
+  constructor(private readonly options: MachineAgentDriverOptionsV1) {}
+
+  private now(): number {
+    return this.options.now?.() ?? Date.now();
+  }
+
+  private async call(
+    path: string,
+    init: RequestInit & { token?: string } = {},
+  ): Promise<unknown> {
+    const headers = new Headers(init.headers);
+    if (init.token) headers.set("authorization", `Bearer ${init.token}`);
+    if (init.body !== undefined)
+      headers.set("content-type", "application/json");
+    const response = await this.options.fetch(`${this.options.origin}${path}`, {
+      ...init,
+      headers,
+    });
+    const text = await response.text();
+    if (!response.ok) throw new MachineAgentError(response.status, text);
+    return text.length === 0 ? undefined : (JSON.parse(text) as unknown);
+  }
+
+  /** The status of a call that is expected to be refused. */
+  async attempt(
+    path: string,
+    init: RequestInit & { token?: string } = {},
+  ): Promise<number> {
+    const headers = new Headers(init.headers);
+    if (init.token) headers.set("authorization", `Bearer ${init.token}`);
+    const response = await this.options.fetch(`${this.options.origin}${path}`, {
+      ...init,
+      headers,
+    });
+    await response.text();
+    return response.status;
+  }
+
+  /** Present a pairing code and become a registered machine. */
+  async enroll(offer: MachinePairingOfferV1 | string): Promise<string> {
+    const code = typeof offer === "string" ? offer : offer.code;
+    const receipt = decodeMachineEnrollmentReceiptV1(
+      await this.call(machineRoutePathV1("enroll"), {
+        method: "POST",
+        token: code,
+        body: JSON.stringify({
+          schemaVersion: 1,
+          code,
+          label: this.options.label ?? "Stub-Machine.local",
+          platform: this.options.platform ?? "macos",
+          agentVersion: this.options.agentVersion ?? "0.0.1",
+          capabilities: this.options.capabilities ?? ["exec", "files"],
+        }),
+      }),
+    );
+    this.machineId = receipt.machineId;
+    this.token = receipt.token;
+    return receipt.token;
+  }
+
+  private identity(): { machineId: string; token: string } {
+    if (!this.machineId || !this.token) {
+      throw new MachineAgentError(401, "this agent has not enrolled");
+    }
+    return { machineId: this.machineId, token: this.token };
+  }
+
+  /** One long poll. `waitSeconds` of 0 answers immediately. */
+  async poll(waitSeconds = 0): Promise<MachineCommandV1[]> {
+    const { machineId, token } = this.identity();
+    const answered = decodeMachinePollResultV1(
+      await this.call(
+        machineRoutePathV1("poll", {
+          machineId,
+          waitSeconds: Math.min(
+            waitSeconds,
+            MACHINE_LIMITS_V1.pollMaxWaitSeconds,
+          ),
+        }),
+        { token },
+      ),
+    );
+    this.delivered.push(...answered.commands);
+    return answered.commands;
+  }
+
+  async claim(commandId: string): Promise<MachineClaimReceiptV1> {
+    const { machineId, token } = this.identity();
+    return decodeMachineClaimReceiptV1(
+      await this.call(machineRoutePathV1("claim", { machineId, commandId }), {
+        method: "POST",
+        token,
+        body: JSON.stringify({}),
+      }),
+    );
+  }
+
+  async report(
+    commandId: string,
+    result: Omit<MachineCommandResultV1, "schemaVersion" | "commandId">,
+  ): Promise<MachineResultReceiptV1> {
+    const { machineId, token } = this.identity();
+    return decodeMachineResultReceiptV1(
+      await this.call(machineRoutePathV1("result", { machineId, commandId }), {
+        method: "POST",
+        token,
+        body: JSON.stringify({
+          schemaVersion: 1,
+          commandId,
+          ...result,
+        }),
+      }),
+    );
+  }
+
+  /** The registry as the browser reads it. Only a test ever calls this. */
+  async listMachines(
+    fetchAsUser: (path: string) => Promise<Response>,
+  ): Promise<MachineListViewV1> {
+    const response = await fetchAsUser(machineRoutePathV1("list"));
+    const text = await response.text();
+    if (!response.ok) throw new MachineAgentError(response.status, text);
+    return decodeMachineListViewV1(JSON.parse(text) as unknown);
+  }
+
+  /**
+   * One turn of the agent's loop: poll, then claim, run and answer each
+   * command the script says to.
+   */
+  async runOnce(waitSeconds = 0): Promise<MachineAgentRunSummaryV1> {
+    const commands = await this.poll(waitSeconds);
+    const summary: MachineAgentRunSummaryV1 = {
+      delivered: commands,
+      claimed: [],
+      alreadyClaimed: [],
+      reported: [],
+      replayed: [],
+    };
+    for (const command of commands) {
+      const action = this.options.handle
+        ? await this.options.handle(command)
+        : ({
+            kind: "result",
+            result: {
+              finishedAt: new Date(this.now()).toISOString(),
+              outcome: "ok",
+              truncated: false,
+              exitCode: 0,
+              stdout: "",
+            },
+          } satisfies MachineAgentActionV1);
+      if (action.kind === "ignore") continue;
+      const claimed = await this.claim(command.commandId);
+      (claimed.status === "claimed"
+        ? summary.claimed
+        : summary.alreadyClaimed
+      ).push(command.commandId);
+      if (action.kind === "vanish") continue;
+      if (action.kind === "double-claim") {
+        const second = await this.claim(command.commandId);
+        summary.alreadyClaimed.push(second.commandId);
+        const receipt = await this.report(command.commandId, action.result);
+        (receipt.status === "recorded"
+          ? summary.reported
+          : summary.replayed
+        ).push(command.commandId);
+        continue;
+      }
+      const receipt = await this.report(command.commandId, action.result);
+      (receipt.status === "recorded"
+        ? summary.reported
+        : summary.replayed
+      ).push(command.commandId);
+      if (action.twice) {
+        const replay = await this.report(command.commandId, action.result);
+        (replay.status === "recorded"
+          ? summary.reported
+          : summary.replayed
+        ).push(command.commandId);
+      }
+    }
+    return summary;
+  }
+}
+
+/** The pairing offer a browser fetch answered with, decoded. */
+export async function readMachinePairingOfferV1(
+  response: Response,
+): Promise<MachinePairingOfferV1> {
+  const text = await response.text();
+  if (!response.ok) throw new MachineAgentError(response.status, text);
+  return decodeMachinePairingOfferV1(JSON.parse(text) as unknown);
+}

package/src/user.test.ts

@@ -0,0 +1,182 @@
+// The User Contribution's own two facts: a hold that ends early, and a door
+// that stays shut without the deployment secret.
+import { describe, expect, test } from "bun:test";
+import { MachineUserBackendContribution } from "./user.ts";
+import { createMemoryMachineStorageV1 } from "./testing.ts";
+import { machineTokenDigestV1 } from "@frockbot/machine-protocol";
+
+const SECRET = "machine-user-secret-0123456789abcdef";
+const T0 = Date.parse("2026-09-01T00:00:00.000Z");
+
+function contribution(secret: string | undefined) {
+  return new MachineUserBackendContribution({
+    storage: createMemoryMachineStorageV1(),
+    readSecret: () => secret,
+    now: () => T0,
+    // A hold that never ends on its own, so only a dispatch can end it.
+    sleep: () => new Promise<void>(() => {}),
+  });
+}
+
+/** Pair, enroll, and hand back what a machine needs to speak. */
+async function enrolled(
+  authority: MachineUserBackendContribution,
+  userId: string,
+) {
+  const offer = await authority.createPairing(userId, {});
+  const receipt = await authority.enroll(
+    { userId, machineId: offer.machineId, nonce: "n" },
+    {
+      schemaVersion: 1,
+      code: offer.code,
+      label: "held.local",
+      platform: "macos",
+      agentVersion: "0.0.1",
+      capabilities: ["exec"],
+    },
+  );
+  return {
+    machineId: offer.machineId,
+    claims: { u: userId, m: offer.machineId, v: receipt.keyVersion },
+    digest: await machineTokenDigestV1(receipt.token),
+  };
+}
+
+function command(machineId: string, commandId: string) {
+  return {
+    schemaVersion: 1 as const,
+    commandId,
+    machineId,
+    botId: "bot-1",
+    runId: "run-1",
+    turn: 1,
+    approvalId: commandId,
+    op: {
+      kind: "exec" as const,
+      command: "uname -a",
+      timeoutMs: 1_000,
+      maxOutputBytes: 1_024,
+    },
+    issuedAt: new Date(T0).toISOString(),
+    status: "queued" as const,
+  };
+}
+
+describe("the User Contribution", () => {
+  test("a long poll ends the moment a command is queued", async () => {
+    const authority = contribution(SECRET);
+    const offer = await authority.createPairing("hold-user", {});
+    const receipt = await authority.enroll(
+      { userId: "hold-user", machineId: offer.machineId, nonce: "n" },
+      {
+        schemaVersion: 1,
+        code: offer.code,
+        label: "held.local",
+        platform: "macos",
+        agentVersion: "0.0.1",
+        capabilities: ["exec"],
+      },
+    );
+    const held = authority.poll(
+      { u: "hold-user", m: offer.machineId, v: receipt.keyVersion },
+      await machineTokenDigestV1(receipt.token),
+      offer.machineId,
+      25,
+    );
+    // The `sleep` above never resolves, so this only returns because the
+    // dispatch woke it — which is the whole claim.
+    await authority.dispatch({
+      schemaVersion: 1,
+      commandId: "tool:1:1:0",
+      machineId: offer.machineId,
+      botId: "bot",
+      runId: "run",
+      turn: 1,
+      approvalId: "tool:1:1:0",
+      op: {
+        kind: "exec",
+        command: "uname -a",
+        timeoutMs: 1_000,
+        maxOutputBytes: 1_024,
+      },
+      issuedAt: new Date(T0).toISOString(),
+      status: "queued",
+    });
+    const answered = await held;
+    expect(answered.commands.map((command) => command.commandId)).toEqual([
+      "tool:1:1:0",
+    ]);
+  });
+
+  test("without a secret nothing can be paired", async () => {
+    await expect(
+      contribution(undefined).createPairing("u", {}),
+    ).rejects.toThrow(/not configured/);
+  });
+
+  test("one read answers the five questions a control tool has to ask", async () => {
+    const authority = contribution(SECRET);
+    const { machineId } = await enrolled(authority, "target-user");
+    const target = await authority.describeTarget(machineId);
+    expect(target.entry?.machineId).toBe(machineId);
+    expect(target.entry?.connected).toBe(true);
+    expect(target.entry?.capabilities).toEqual(["exec"]);
+    expect(target.queuedCommands).toBe(0);
+    expect(target.commandsToday).toBe(0);
+    await authority.dispatch(command(machineId, "tool:1:1:0"));
+    const after = await authority.describeTarget(machineId);
+    expect(after.queuedCommands).toBe(1);
+    expect(after.commandsToday).toBe(1);
+    // A machine this User does not hold is a view with no row, never a throw:
+    // the tool has to be able to say so in words.
+    const missing = await authority.describeTarget("mac-nobody");
+    expect(missing.entry).toBeUndefined();
+  });
+
+  test("a recorded result is delivered once, and a replay tells nobody", async () => {
+    const authority = contribution(SECRET);
+    const { machineId, claims, digest } = await enrolled(
+      authority,
+      "deliver-user",
+    );
+    await authority.dispatch(command(machineId, "tool:1:1:0"));
+    await authority.claim(claims, digest, machineId, "tool:1:1:0");
+    const answer = {
+      schemaVersion: 1,
+      commandId: "tool:1:1:0",
+      finishedAt: new Date(T0).toISOString(),
+      outcome: "ok",
+      truncated: false,
+      exitCode: 0,
+      stdout: "Darwin",
+    };
+    const first = await authority.recordResult(
+      claims,
+      digest,
+      machineId,
+      "tool:1:1:0",
+      answer,
+    );
+    expect(first.status).toBe("recorded");
+    const deliveries = await authority.takeDeliveries();
+    expect(deliveries).toHaveLength(1);
+    expect(deliveries[0]).toMatchObject({
+      botId: "bot-1",
+      commandId: "tool:1:1:0",
+      machineId,
+      outcome: "ok",
+    });
+    // The agent retried. "Recovery never silently duplicates" applies to the
+    // telling as much as to the running.
+    const replay = await authority.recordResult(
+      claims,
+      digest,
+      machineId,
+      "tool:1:1:0",
+      answer,
+    );
+    expect(replay.status).toBe("replayed");
+    // Taking is removing, and a replay writes nothing to take.
+    expect(await authority.takeDeliveries()).toEqual([]);
+  });
+});