@frockbot/machine-protocol 0.0.0 → 0.1.1

package/src/quota.test.ts

@@ -0,0 +1,156 @@
+import { describe, expect, test } from "bun:test";
+import {
+  MACHINE_QUOTA_DEFAULTS_V1,
+  checkMachineQuotaV1,
+  decodeMachineQuotaConfigV1,
+  machineQuotaRefusalV1,
+  type MachineQuotaOutcomeV1,
+} from "./quota.ts";
+import {
+  MACHINE_COMMANDS_PER_DAY,
+  MACHINE_MAX_PER_USER,
+  MACHINE_MAX_QUEUE,
+} from "./protocol.ts";
+
+/**
+ * `plugin-audit/src/bot.ts`'s `outcomeFor`, copied verbatim rather than
+ * imported: a protocol package takes no dependency on a Package. The copy is
+ * the point of the assertion — if the classifier's wording ever moves, this
+ * test is where the machine refusals stop reading as `refused`.
+ */
+const AUDIT_REFUSAL = /\brefus|not allowed|denied|blocked while\b/i;
+
+const refused = (outcome: MachineQuotaOutcomeV1) => {
+  expect(outcome.status).toBe("refused");
+  return outcome as Extract<MachineQuotaOutcomeV1, { status: "refused" }>;
+};
+
+describe("machine quota", () => {
+  test("admits up to each limit and refuses at it", () => {
+    expect(
+      checkMachineQuotaV1({
+        kind: "register",
+        registeredMachines: MACHINE_MAX_PER_USER - 1,
+      }),
+    ).toEqual({ status: "within" });
+    expect(
+      refused(
+        checkMachineQuotaV1({
+          kind: "register",
+          registeredMachines: MACHINE_MAX_PER_USER,
+        }),
+      ).limitName,
+    ).toBe("machine-count");
+
+    expect(
+      checkMachineQuotaV1({
+        kind: "dispatch",
+        queuedCommands: MACHINE_MAX_QUEUE - 1,
+        commandsToday: 0,
+      }),
+    ).toEqual({ status: "within" });
+    expect(
+      refused(
+        checkMachineQuotaV1({
+          kind: "dispatch",
+          queuedCommands: MACHINE_MAX_QUEUE,
+          commandsToday: 0,
+        }),
+      ).limitName,
+    ).toBe("queue-depth");
+
+    expect(
+      refused(
+        checkMachineQuotaV1({
+          kind: "dispatch",
+          queuedCommands: 0,
+          commandsToday: MACHINE_COMMANDS_PER_DAY,
+        }),
+      ).limitName,
+    ).toBe("commands-per-day");
+  });
+
+  test("a breach is an outcome, never a throw, and names its numbers", () => {
+    const outcome = refused(
+      checkMachineQuotaV1({
+        kind: "dispatch",
+        queuedCommands: MACHINE_MAX_QUEUE + 4,
+        commandsToday: 0,
+      }),
+    );
+    expect(outcome.used).toBe(MACHINE_MAX_QUEUE + 4);
+    expect(outcome.limit).toBe(MACHINE_MAX_QUEUE);
+    expect(outcome.reason).toContain(String(MACHINE_MAX_QUEUE));
+  });
+
+  test("every refusal reads as `refused` to the audit classifier", () => {
+    const outcomes = [
+      checkMachineQuotaV1({
+        kind: "register",
+        registeredMachines: MACHINE_MAX_PER_USER,
+      }),
+      checkMachineQuotaV1({
+        kind: "dispatch",
+        queuedCommands: MACHINE_MAX_QUEUE,
+        commandsToday: 0,
+      }),
+      checkMachineQuotaV1({
+        kind: "dispatch",
+        queuedCommands: 0,
+        commandsToday: MACHINE_COMMANDS_PER_DAY,
+      }),
+    ];
+    for (const outcome of outcomes) {
+      const text = machineQuotaRefusalV1(refused(outcome));
+      expect(text.startsWith("Refused: ")).toBe(true);
+      expect(AUDIT_REFUSAL.test(text)).toBe(true);
+    }
+  });
+
+  test("a configured quota overrides the defaults", () => {
+    const config = {
+      ...MACHINE_QUOTA_DEFAULTS_V1,
+      maxQueuedCommands: 2,
+    };
+    expect(
+      checkMachineQuotaV1(
+        { kind: "dispatch", queuedCommands: 1, commandsToday: 0 },
+        config,
+      ),
+    ).toEqual({ status: "within" });
+    expect(
+      checkMachineQuotaV1(
+        { kind: "dispatch", queuedCommands: 2, commandsToday: 0 },
+        config,
+      ).status,
+    ).toBe("refused");
+  });
+
+  test("the defaults are the protocol's declared limits", () => {
+    expect(MACHINE_QUOTA_DEFAULTS_V1).toEqual({
+      schemaVersion: 1,
+      maxMachinesPerUser: MACHINE_MAX_PER_USER,
+      maxQueuedCommands: MACHINE_MAX_QUEUE,
+      maxCommandsPerDay: MACHINE_COMMANDS_PER_DAY,
+    });
+  });
+
+  test("the config decoder is exact-key and bounded", () => {
+    expect(decodeMachineQuotaConfigV1(undefined)).toEqual(
+      MACHINE_QUOTA_DEFAULTS_V1,
+    );
+    expect(
+      decodeMachineQuotaConfigV1({ ...MACHINE_QUOTA_DEFAULTS_V1 }),
+    ).toEqual(MACHINE_QUOTA_DEFAULTS_V1);
+    for (const bad of [
+      { ...MACHINE_QUOTA_DEFAULTS_V1, extra: 1 },
+      { ...MACHINE_QUOTA_DEFAULTS_V1, schemaVersion: 2 },
+      { ...MACHINE_QUOTA_DEFAULTS_V1, maxMachinesPerUser: 0 },
+      { ...MACHINE_QUOTA_DEFAULTS_V1, maxQueuedCommands: 100_000 },
+      { ...MACHINE_QUOTA_DEFAULTS_V1, maxCommandsPerDay: 1.5 },
+      [MACHINE_QUOTA_DEFAULTS_V1],
+    ]) {
+      expect(() => decodeMachineQuotaConfigV1(bad)).toThrow();
+    }
+  });
+});

package/src/quota.ts

@@ -0,0 +1,152 @@
+// The bounded per-User machine quota.
+//
+// "Quotas refuse visibly": exceeding one refuses the operation and records a
+// visible failure, so this module never throws for a breach. It returns an
+// outcome, exactly as `plugin-skills/src/quota.ts` does, and the caller turns
+// that outcome into an `isError` tool result whose text `plugin-audit`
+// classifies as `refused` rather than `error`.
+//
+// Three things are bounded, and each bounds a different loss:
+//
+//  - **machines per User** — the registry is a projection the settings section
+//    renders and a tool lists; unbounded, it is an unbounded response.
+//  - **commands queued for one machine** — the queue lives in the User Durable
+//    Object and is drained by a laptop that may be asleep for a week.
+//  - **commands per User per day** — the one bound on a Bot that has learned
+//    to ask for approval often. It is a rate, so it needs a durable counter
+//    the User Durable Object keeps; this module only says whether the number
+//    it is handed is over.
+
+import { MACHINE_LIMITS_V1 } from "./protocol.js";
+
+export interface MachineQuotaConfigV1 {
+  schemaVersion: 1;
+  /** Machines one User may hold registered at once. */
+  maxMachinesPerUser: number;
+  /** Commands one machine may hold queued at once. */
+  maxQueuedCommands: number;
+  /** Commands one User may dispatch across all machines in a day. */
+  maxCommandsPerDay: number;
+}
+
+export const MACHINE_QUOTA_DEFAULTS_V1: MachineQuotaConfigV1 = {
+  schemaVersion: 1,
+  maxMachinesPerUser: MACHINE_LIMITS_V1.maxMachinesPerUser,
+  maxQueuedCommands: MACHINE_LIMITS_V1.maxQueue,
+  maxCommandsPerDay: MACHINE_LIMITS_V1.commandsPerDay,
+};
+
+export type MachineQuotaLimitV1 =
+  "machine-count" | "queue-depth" | "commands-per-day";
+
+export type MachineQuotaRequestV1 =
+  | { kind: "register"; registeredMachines: number }
+  | { kind: "dispatch"; queuedCommands: number; commandsToday: number };
+
+export type MachineQuotaOutcomeV1 =
+  | { status: "within" }
+  | {
+      status: "refused";
+      limitName: MachineQuotaLimitV1;
+      reason: string;
+      used: number;
+      limit: number;
+    };
+
+/**
+ * Checks one registration or one dispatch against the quota. Never throws for
+ * a breach: a quota breach is an observable outcome the tool result reports.
+ */
+export function checkMachineQuotaV1(
+  request: MachineQuotaRequestV1,
+  config: MachineQuotaConfigV1 = MACHINE_QUOTA_DEFAULTS_V1,
+): MachineQuotaOutcomeV1 {
+  if (request.kind === "register") {
+    if (request.registeredMachines >= config.maxMachinesPerUser) {
+      return {
+        status: "refused",
+        limitName: "machine-count",
+        reason: `this account holds ${request.registeredMachines} registered machines; the quota allows ${config.maxMachinesPerUser}`,
+        used: request.registeredMachines,
+        limit: config.maxMachinesPerUser,
+      };
+    }
+    return { status: "within" };
+  }
+  if (request.queuedCommands >= config.maxQueuedCommands) {
+    return {
+      status: "refused",
+      limitName: "queue-depth",
+      reason: `this machine already has ${request.queuedCommands} commands waiting; the quota allows ${config.maxQueuedCommands}`,
+      used: request.queuedCommands,
+      limit: config.maxQueuedCommands,
+    };
+  }
+  if (request.commandsToday >= config.maxCommandsPerDay) {
+    return {
+      status: "refused",
+      limitName: "commands-per-day",
+      reason: `this account has sent ${request.commandsToday} machine commands today; the quota allows ${config.maxCommandsPerDay}`,
+      used: request.commandsToday,
+      limit: config.maxCommandsPerDay,
+    };
+  }
+  return { status: "within" };
+}
+
+/**
+ * The refusal a tool result carries.
+ *
+ * The leading "Refused:" is not decoration. `plugin-audit`'s `outcomeFor`
+ * classifies an `isError` result by its text
+ * (`/\brefus|not allowed|denied|blocked while\b/i`, `plugin-audit/src/bot.ts`),
+ * so a quota breach that does not say it refused would be audited as an effect
+ * that ran and failed — which is a materially different fact about somebody's
+ * laptop.
+ */
+export function machineQuotaRefusalV1(
+  outcome: Extract<MachineQuotaOutcomeV1, { status: "refused" }>,
+): string {
+  return `Refused: ${outcome.reason}.`;
+}
+
+export function decodeMachineQuotaConfigV1(
+  input: unknown,
+  label = "machine quota configuration",
+): MachineQuotaConfigV1 {
+  if (input === undefined) return { ...MACHINE_QUOTA_DEFAULTS_V1 };
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    throw new Error(`${label} must be an object`);
+  }
+  const value = input as Record<string, unknown>;
+  const keys = [
+    "schemaVersion",
+    "maxMachinesPerUser",
+    "maxQueuedCommands",
+    "maxCommandsPerDay",
+  ];
+  if (
+    value.schemaVersion !== 1 ||
+    Object.keys(value).length !== keys.length ||
+    !keys.every((key) => Object.hasOwn(value, key))
+  ) {
+    throw new Error(`${label} is invalid`);
+  }
+  const bounded = (name: string, maximum: number): number => {
+    const candidate = value[name];
+    if (
+      !Number.isSafeInteger(candidate) ||
+      (candidate as number) < 1 ||
+      (candidate as number) > maximum
+    ) {
+      throw new Error(`${label}.${name} is out of range`);
+    }
+    return candidate as number;
+  };
+  return {
+    schemaVersion: 1,
+    maxMachinesPerUser: bounded("maxMachinesPerUser", 64),
+    maxQueuedCommands: bounded("maxQueuedCommands", 256),
+    maxCommandsPerDay: bounded("maxCommandsPerDay", 10_000),
+  };
+}

package/src/routes.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, test } from "bun:test";
+import {
+  MACHINE_POLL_WAIT_PARAM_V1,
+  MACHINE_ROUTES_V1,
+  MACHINE_ROUTE_NAMES_V1,
+  MACHINE_ROUTE_PREFIX_V1,
+  decodeMachinePollWaitV1,
+  machineRoutePathV1,
+} from "./routes.ts";
+import { MACHINE_LIMITS_V1, MachineDecodeError } from "./protocol.ts";
+
+const MACHINE_ID = "994dc2ee-3f42-4a4d-9f2a-0a3f6f0d1b77";
+
+describe("machine route table", () => {
+  test("every machine-addressed route is public, and no browser route is", () => {
+    const publicRoutes = MACHINE_ROUTE_NAMES_V1.filter(
+      (name) => MACHINE_ROUTES_V1[name].publicRoute,
+    );
+    expect(publicRoutes).toEqual(["enroll", "poll", "claim", "result"]);
+    // Public means "no session", never "no authority": every public route is
+    // addressed by the machine, which presents a token instead.
+    for (const name of publicRoutes) {
+      expect(MACHINE_ROUTES_V1[name].audience).toBe("machine");
+    }
+    for (const name of MACHINE_ROUTE_NAMES_V1) {
+      const route = MACHINE_ROUTES_V1[name];
+      if (route.audience === "browser") expect(route.publicRoute).toBe(false);
+      expect(route.template.startsWith(MACHINE_ROUTE_PREFIX_V1)).toBe(true);
+    }
+  });
+
+  test("builds each concrete path", () => {
+    expect(machineRoutePathV1("pair")).toBe("/api/machines/pair");
+    expect(machineRoutePathV1("enroll")).toBe("/api/machines/enroll");
+    expect(machineRoutePathV1("list")).toBe("/api/machines");
+    expect(machineRoutePathV1("poll", { machineId: MACHINE_ID })).toBe(
+      `/api/machines/${MACHINE_ID}/poll`,
+    );
+    expect(
+      machineRoutePathV1("poll", { machineId: MACHINE_ID, waitSeconds: 25 }),
+    ).toBe(`/api/machines/${MACHINE_ID}/poll?${MACHINE_POLL_WAIT_PARAM_V1}=25`);
+    expect(machineRoutePathV1("revoke", { machineId: MACHINE_ID })).toBe(
+      `/api/machines/${MACHINE_ID}/revoke`,
+    );
+    expect(
+      machineRoutePathV1("claim", {
+        machineId: MACHINE_ID,
+        commandId: "tool:3:1:0",
+      }),
+    ).toBe(`/api/machines/${MACHINE_ID}/commands/tool%3A3%3A1%3A0/claim`);
+    expect(
+      machineRoutePathV1("result", {
+        machineId: MACHINE_ID,
+        commandId: "tool:3:1:0",
+      }),
+    ).toBe(`/api/machines/${MACHINE_ID}/commands/tool%3A3%3A1%3A0/result`);
+  });
+
+  test("refuses a missing or unsafe segment rather than emitting one", () => {
+    expect(() => machineRoutePathV1("poll")).toThrow(/needs a valid machineId/);
+    expect(() =>
+      machineRoutePathV1("claim", { machineId: MACHINE_ID }),
+    ).toThrow(/needs a valid commandId/);
+    for (const bad of ["../../admin", "a b", "", "-x"]) {
+      expect(() => machineRoutePathV1("poll", { machineId: bad })).toThrow(
+        MachineDecodeError,
+      );
+    }
+  });
+
+  test("no template leaves an unsubstituted parameter behind", () => {
+    for (const name of MACHINE_ROUTE_NAMES_V1) {
+      const path = machineRoutePathV1(name, {
+        machineId: MACHINE_ID,
+        commandId: "tool:3:1:0",
+      });
+      expect(path).not.toContain(":machineId");
+      expect(path).not.toContain(":commandId");
+    }
+  });
+});
+
+describe("poll wait", () => {
+  test("accepts the ceiling from a number or a query string", () => {
+    expect(decodeMachinePollWaitV1(0)).toBe(0);
+    expect(decodeMachinePollWaitV1("25")).toBe(25);
+    expect(decodeMachinePollWaitV1(MACHINE_LIMITS_V1.pollMaxWaitSeconds)).toBe(
+      MACHINE_LIMITS_V1.pollMaxWaitSeconds,
+    );
+  });
+
+  test("refuses a longer hold rather than silently clamping it", () => {
+    // A silently clamped wait is a backoff the agent believes it does not need.
+    for (const bad of [
+      MACHINE_LIMITS_V1.pollMaxWaitSeconds + 1,
+      "26",
+      -1,
+      1.5,
+      "twenty",
+      null,
+    ]) {
+      expect(() => decodeMachinePollWaitV1(bad)).toThrow(MachineDecodeError);
+    }
+  });
+});

package/src/routes.ts

@@ -0,0 +1,161 @@
+// The route table, declared once.
+//
+// Three parties address these paths — the browser, the gateway that registers
+// them, and the device agent that dials them — and each would otherwise hold
+// its own string. One table means the agent cannot poll a path the gateway
+// does not serve, and a test cannot pass against a route nobody registered.
+//
+// `audience` and `publicRoute` are the load-bearing columns. `poll`, `claim`
+// and `result` are declared public because they carry a *machine token*, not a
+// session: they run at the seam in `apps/cloudflare/src/gateway.ts` that
+// executes before session authentication, which `plugin-routines`' webhook
+// already uses. Public here means "no session", never "no authority" — the
+// token is verified at the edge and re-checked against the machine record's
+// digest inside the User Durable Object.
+
+import { MACHINE_LIMITS_V1, MachineDecodeError } from "./protocol.js";
+
+export const MACHINE_ROUTE_PREFIX_V1 = "/api/machines";
+
+export type MachineRouteNameV1 =
+  "pair" | "enroll" | "poll" | "claim" | "result" | "list" | "revoke";
+
+export interface MachineRouteV1 {
+  method: "GET" | "POST";
+  /** The template the gateway registers, with `:machineId` / `:commandId`. */
+  template: string;
+  /** Who presents at this route. */
+  audience: "browser" | "machine";
+  /** Declared `publicRoute` on the gateway contribution: bearer, not session. */
+  publicRoute: boolean;
+}
+
+export const MACHINE_ROUTES_V1: Readonly<
+  Record<MachineRouteNameV1, MachineRouteV1>
+> = {
+  pair: {
+    method: "POST",
+    template: `${MACHINE_ROUTE_PREFIX_V1}/pair`,
+    audience: "browser",
+    publicRoute: false,
+  },
+  enroll: {
+    method: "POST",
+    template: `${MACHINE_ROUTE_PREFIX_V1}/enroll`,
+    audience: "machine",
+    publicRoute: true,
+  },
+  poll: {
+    method: "GET",
+    template: `${MACHINE_ROUTE_PREFIX_V1}/:machineId/poll`,
+    audience: "machine",
+    publicRoute: true,
+  },
+  claim: {
+    method: "POST",
+    template: `${MACHINE_ROUTE_PREFIX_V1}/:machineId/commands/:commandId/claim`,
+    audience: "machine",
+    publicRoute: true,
+  },
+  result: {
+    method: "POST",
+    template: `${MACHINE_ROUTE_PREFIX_V1}/:machineId/commands/:commandId/result`,
+    audience: "machine",
+    publicRoute: true,
+  },
+  list: {
+    method: "GET",
+    template: MACHINE_ROUTE_PREFIX_V1,
+    audience: "browser",
+    publicRoute: false,
+  },
+  revoke: {
+    method: "POST",
+    template: `${MACHINE_ROUTE_PREFIX_V1}/:machineId/revoke`,
+    audience: "browser",
+    publicRoute: false,
+  },
+} as const;
+
+export const MACHINE_ROUTE_NAMES_V1 = Object.keys(
+  MACHINE_ROUTES_V1,
+) as MachineRouteNameV1[];
+
+/** The query parameter a long poll asks its hold with. */
+export const MACHINE_POLL_WAIT_PARAM_V1 = "wait";
+
+export interface MachineRouteParamsV1 {
+  machineId?: string;
+  commandId?: string;
+  /** `poll` only: seconds to hold, bounded by `pollMaxWaitSeconds`. */
+  waitSeconds?: number;
+}
+
+const SEGMENT_SAFE = /^[A-Za-z0-9][A-Za-z0-9._:@-]*$/;
+
+/**
+ * The concrete path for one route.
+ *
+ * Every substituted segment is checked against the same identifier rule the
+ * decoders use and then percent-encoded: a `commandId` is an `effectId` and
+ * carries colons, which are legal in a path segment, but nothing here trusts
+ * that an id it was handed is one it minted.
+ */
+export function machineRoutePathV1(
+  name: MachineRouteNameV1,
+  params: MachineRouteParamsV1 = {},
+): string {
+  const route = MACHINE_ROUTES_V1[name];
+  if (!route) {
+    throw new MachineDecodeError(`unknown machine route: ${String(name)}`);
+  }
+  const path = route.template.replace(
+    /:(machineId|commandId)/g,
+    (_match, key: "machineId" | "commandId") => {
+      const value = params[key];
+      if (
+        typeof value !== "string" ||
+        value.length === 0 ||
+        value.length > MACHINE_LIMITS_V1.identifier ||
+        !SEGMENT_SAFE.test(value)
+      ) {
+        throw new MachineDecodeError(
+          `machine route ${name} needs a valid ${key}`,
+        );
+      }
+      return encodeURIComponent(value);
+    },
+  );
+  if (name !== "poll" || params.waitSeconds === undefined) return path;
+  const wait = decodeMachinePollWaitV1(params.waitSeconds);
+  return `${path}?${MACHINE_POLL_WAIT_PARAM_V1}=${wait}`;
+}
+
+/**
+ * How long a poll may be held, from a number or from the raw query string.
+ *
+ * The ceiling is the protocol's, not the caller's: a machine that asks to be
+ * held for an hour is asking a Worker to hold a request past every limit it
+ * has, so the value is refused rather than silently clamped — a silently
+ * clamped wait is a backoff the agent thinks it does not need.
+ */
+export function decodeMachinePollWaitV1(
+  input: unknown,
+  label = "machine poll wait",
+): number {
+  const value =
+    typeof input === "string" && /^[0-9]{1,4}$/.test(input)
+      ? Number.parseInt(input, 10)
+      : input;
+  if (!Number.isSafeInteger(value)) {
+    throw new MachineDecodeError(`${label} must be an integer`);
+  }
+  const seconds = value as number;
+  if (seconds < 0 || seconds > MACHINE_LIMITS_V1.pollMaxWaitSeconds) {
+    throw new MachineDecodeError(
+      `${label} must be between 0 and ${MACHINE_LIMITS_V1.pollMaxWaitSeconds}`,
+      "limit-exceeded",
+    );
+  }
+  return seconds;
+}