@frockbot/plugin-user-machine 0.0.0 → 0.1.0

package/src/index.ts

@@ -0,0 +1,13 @@
+export * from "./agent.js";
+export * from "./approval.js";
+export * from "./backend.js";
+export * from "./delivery.js";
+export * from "./device.js";
+export * from "./device-runner.js";
+export * from "./intent.js";
+export * from "./pairing.js";
+export * from "./storage-keys.js";
+export * from "./store.js";
+export * from "./target.js";
+export * from "./testing.js";
+export * from "./user.js";

package/src/intent.ts

@@ -0,0 +1,325 @@
+// The Bot Durable Object's half of a machine command: intent, recorded before
+// anything runs.
+//
+// A machine tool does not run a command. It writes one of these, asks the User
+// for an approval, and ends the Turn. The command reaches the User's laptop
+// only when a person answers, and it is *this* record the settlement reads to
+// know what they answered about — the pending-input preamble carries only an
+// `approvalId` and a decision, so the action it authorizes has to be
+// recoverable from that id alone.
+//
+// Three properties the rest of the slice rests on:
+//
+//  1. **`approvalId === commandId === effectId`.** One identity for the
+//     decision, the queue key and the Turn's durable occurrence, so a replayed
+//     settlement addresses the same command rather than queueing a second one.
+//  2. **Written before the send.** "Record intent before an external effect."
+//     The record is durable before the card the User sees exists, so there is
+//     no window in which somebody could approve an action nothing describes.
+//  3. **Pure.** Everything here is a function of its arguments. The storage
+//     seam is in `approval.ts`; this module never reads a clock it was not
+//     handed.
+import {
+  MACHINE_LIMITS_V1,
+  MachineDecodeError,
+  decodeMachineOpV1,
+  type MachineCommandV1,
+  type MachineOpV1,
+} from "@frockbot/machine-protocol";
+
+/**
+ * The approval id — and therefore the command id — one Turn's `effectId` maps
+ * to.
+ *
+ * `effectId` is `tool:<turn>:<step>:<ordinal>`, and an `approvalId` may not
+ * carry a colon: it becomes a URL path segment and a durable storage key, and
+ * `decodeSendToUserPayloadV1` refuses anything but letters, digits, dot,
+ * underscore and dash. The mapping is total, deterministic and injective over
+ * that format, so `commandId === approvalId` is still exactly one identity per
+ * durable occurrence — which is all the idempotency rests on.
+ */
+export function machineApprovalIdV1(effectId: string): string {
+  const mapped = effectId.replace(/[^a-zA-Z0-9._-]/g, ".");
+  return /^[a-zA-Z0-9]/.test(mapped) ? mapped : `m${mapped}`;
+}
+
+/** One intent per approval, in the Bot Durable Object's own storage. */
+export const MACHINE_INTENT_PREFIX = "machine-command:";
+
+export function machineIntentKeyV1(approvalId: string): string {
+  return `${MACHINE_INTENT_PREFIX}${approvalId}`;
+}
+
+/**
+ * What the settlement did with the intent, once a person (or the clock)
+ * answered. `refused` is the queue's own answer — a machine revoked between the
+ * card and the decision — and is a fact about the command, not about the User.
+ */
+export type MachineIntentOutcomeV1 =
+  "dispatched" | "duplicate" | "denied" | "expired" | "refused";
+
+export const MACHINE_INTENT_OUTCOMES_V1: readonly MachineIntentOutcomeV1[] = [
+  "dispatched",
+  "duplicate",
+  "denied",
+  "expired",
+  "refused",
+];
+
+/**
+ * The durable record of one asked-for machine command.
+ *
+ * `decision` is what the User's answer was; `outcome` is what this Package then
+ * did about it. They are separate because "approved" and "queued" are different
+ * facts: an approval whose machine was revoked in between is `approved` and
+ * `refused`, and a reader months later should be able to tell.
+ */
+export interface MachineIntentRecordV1 {
+  schemaVersion: 1;
+  approvalId: string;
+  commandId: string;
+  machineId: string;
+  botId: string;
+  runId: string;
+  turn: number;
+  op: MachineOpV1;
+  createdAt: string;
+  decision?: "approved" | "denied" | "expired";
+  decidedAt?: string;
+  dispatchedAt?: string;
+  outcome?: MachineIntentOutcomeV1;
+  /** Why the dispatch refused, in the queue's own words. */
+  reason?: string;
+}
+
+function object(input: unknown, label: string): Record<string, unknown> {
+  if (typeof input !== "object" || input === null || Array.isArray(input)) {
+    throw new MachineDecodeError(`${label} must be an object`);
+  }
+  return input as Record<string, unknown>;
+}
+
+function exactly(
+  value: Record<string, unknown>,
+  allowed: readonly string[],
+  label: string,
+): void {
+  for (const key of Object.keys(value)) {
+    if (!allowed.includes(key)) {
+      throw new MachineDecodeError(`${label} has an unexpected key "${key}"`);
+    }
+  }
+}
+
+function text(value: unknown, maximum: number, label: string): string {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new MachineDecodeError(`${label} must be a non-empty string`);
+  }
+  if (value.length > maximum) {
+    throw new MachineDecodeError(`${label} exceeds ${maximum} characters`);
+  }
+  return value;
+}
+
+function timestamp(value: unknown, label: string): string {
+  const stamp = text(value, 64, label);
+  if (Number.isNaN(Date.parse(stamp))) {
+    throw new MachineDecodeError(`${label} is not a timestamp`);
+  }
+  return stamp;
+}
+
+function decision(
+  value: unknown,
+  label: string,
+): "approved" | "denied" | "expired" {
+  if (value !== "approved" && value !== "denied" && value !== "expired") {
+    throw new MachineDecodeError(`${label} is invalid`);
+  }
+  return value;
+}
+
+export function decodeMachineIntentRecordV1(
+  input: unknown,
+  label = "machine intent",
+): MachineIntentRecordV1 {
+  const value = object(input, label);
+  exactly(
+    value,
+    [
+      "schemaVersion",
+      "approvalId",
+      "commandId",
+      "machineId",
+      "botId",
+      "runId",
+      "turn",
+      "op",
+      "createdAt",
+      "decision",
+      "decidedAt",
+      "dispatchedAt",
+      "outcome",
+      "reason",
+    ],
+    label,
+  );
+  if (value.schemaVersion !== 1) {
+    throw new MachineDecodeError(`${label} schemaVersion is unsupported`);
+  }
+  if (
+    typeof value.turn !== "number" ||
+    !Number.isSafeInteger(value.turn) ||
+    value.turn < 0
+  ) {
+    throw new MachineDecodeError(`${label} turn is invalid`);
+  }
+  if (
+    value.outcome !== undefined &&
+    !MACHINE_INTENT_OUTCOMES_V1.includes(
+      value.outcome as MachineIntentOutcomeV1,
+    )
+  ) {
+    throw new MachineDecodeError(`${label} outcome is invalid`);
+  }
+  const identifier = MACHINE_LIMITS_V1.identifier;
+  return {
+    schemaVersion: 1,
+    approvalId: text(value.approvalId, identifier, `${label} approvalId`),
+    commandId: text(value.commandId, identifier, `${label} commandId`),
+    machineId: text(value.machineId, identifier, `${label} machineId`),
+    botId: text(value.botId, identifier, `${label} botId`),
+    runId: text(value.runId, identifier, `${label} runId`),
+    turn: value.turn,
+    op: decodeMachineOpV1(value.op, `${label} op`),
+    createdAt: timestamp(value.createdAt, `${label} createdAt`),
+    ...(value.decision === undefined
+      ? {}
+      : { decision: decision(value.decision, `${label} decision`) }),
+    ...(value.decidedAt === undefined
+      ? {}
+      : { decidedAt: timestamp(value.decidedAt, `${label} decidedAt`) }),
+    ...(value.dispatchedAt === undefined
+      ? {}
+      : {
+          dispatchedAt: timestamp(value.dispatchedAt, `${label} dispatchedAt`),
+        }),
+    ...(value.outcome === undefined
+      ? {}
+      : { outcome: value.outcome as MachineIntentOutcomeV1 }),
+    ...(value.reason === undefined
+      ? {}
+      : {
+          reason: text(
+            value.reason,
+            MACHINE_LIMITS_V1.message,
+            `${label} reason`,
+          ),
+        }),
+  };
+}
+
+/**
+ * The command an approved intent dispatches.
+ *
+ * `commandId` is carried over rather than minted, which is the whole
+ * idempotency story: a settlement replayed after an eviction builds the
+ * byte-identical command and the queue answers `duplicate`.
+ */
+export function machineCommandForIntentV1(
+  intent: MachineIntentRecordV1,
+  issuedAt: string,
+): MachineCommandV1 {
+  return {
+    schemaVersion: 1,
+    commandId: intent.commandId,
+    machineId: intent.machineId,
+    botId: intent.botId,
+    runId: intent.runId,
+    turn: intent.turn,
+    approvalId: intent.approvalId,
+    op: intent.op,
+    issuedAt,
+    status: "queued",
+  };
+}
+
+/**
+ * The intent as the settling transaction leaves it.
+ *
+ * First write wins here too: an intent that already carries a decision is
+ * returned unchanged, so an alarm racing a person cannot overwrite the answer
+ * the person gave.
+ */
+export function settledMachineIntentV1(
+  intent: MachineIntentRecordV1,
+  answer: "approved" | "denied" | "expired",
+  at: string,
+): MachineIntentRecordV1 {
+  if (intent.decision !== undefined) return intent;
+  return {
+    ...intent,
+    decision: answer,
+    decidedAt: at,
+    // A denial or an expiry is terminal at the moment it is recorded: nothing
+    // is dispatched, and there is no later step to wait for.
+    ...(answer === "approved" ? {} : { outcome: answer }),
+  };
+}
+
+/** The intent once the queue has answered a dispatch. */
+export function dispatchedMachineIntentV1(
+  intent: MachineIntentRecordV1,
+  outcome: MachineIntentOutcomeV1,
+  at: string,
+  reason?: string,
+): MachineIntentRecordV1 {
+  return {
+    ...intent,
+    ...(outcome === "refused" ? {} : { dispatchedAt: at }),
+    outcome,
+    ...(reason === undefined
+      ? {}
+      : { reason: reason.slice(0, MACHINE_LIMITS_V1.message) }),
+  };
+}
+
+/** The sentence the approval card puts in front of the User. */
+export function machineApprovalActionV1(
+  op: MachineOpV1,
+  label: string,
+): string {
+  switch (op.kind) {
+    case "exec":
+      return `Run on ${label}: ${op.command}${op.cwd === undefined ? "" : ` (in ${op.cwd})`}`;
+    case "read":
+      return `Read ${op.path} from ${label}`;
+    case "copy-to-computer":
+      return `Copy ${op.path} from ${label} into the Computer workspace at ${op.workspacePath}`;
+    case "copy-from-computer":
+      return `Copy ${op.workspacePath} from the Computer workspace onto ${label} at ${op.path}`;
+    case "messages":
+      // Row 57g. Only `send` ever reaches a card — the six reads are exempt —
+      // but the sentence is written for the whole variant so a later call that
+      // does take one cannot fall through to something vague. The card carries
+      // the *exact text*, because approving a message you have not read is not
+      // approving anything.
+      return op.call.kind === "send"
+        ? `Send an iMessage from ${label} to ${op.call.to}: "${op.call.text}"`
+        : `Read Messages on ${label} (${op.call.kind})`;
+  }
+}
+
+/** Why the card is being shown, in the words the User reads under the action. */
+export function machineApprovalRationaleV1(
+  op: MachineOpV1,
+  label: string,
+): string {
+  if (op.kind === "exec") {
+    return `This runs on your own machine "${label}", outside the Computer sandbox, with your account's permissions.`;
+  }
+  if (op.kind === "messages") {
+    return `This sends from Messages.app on your own machine "${label}", as you. The person receiving it sees a message from you, and it cannot be unsent.`;
+  }
+  return `This touches the filesystem of your own machine "${label}", which is separate from the Computer workspace.`;
+}

package/src/manifest.ts

@@ -0,0 +1,3 @@
+import manifest from "../frockbot.json" with { type: "json" };
+
+export default manifest;

package/src/pairing.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, test } from "bun:test";
+import { MACHINE_LIMITS_V1 } from "@frockbot/machine-protocol";
+import {
+  machinePairingCodeDigestV1,
+  machinePairingNonceV1,
+  mintMachinePairingCodeV1,
+  verifyMachinePairingCodeV1,
+} from "./pairing.ts";
+
+const SECRET = "machine-pairing-secret-0123456789abcdef";
+
+describe("the pairing code", () => {
+  test("round-trips the User and machine it was minted for", async () => {
+    const claims = {
+      userId: "user-with-a-fairly-long-identifier-0123",
+      machineId: crypto.randomUUID(),
+      nonce: machinePairingNonceV1(),
+    };
+    const code = await mintMachinePairingCodeV1(SECRET, claims);
+    expect(code.length).toBeLessThanOrEqual(MACHINE_LIMITS_V1.pairingCode);
+    expect(await verifyMachinePairingCodeV1(SECRET, code)).toEqual(claims);
+  });
+
+  test("a tampered payload, a wrong secret and a truncated code are all refused", async () => {
+    const claims = {
+      userId: "pairing-user",
+      machineId: crypto.randomUUID(),
+      nonce: machinePairingNonceV1(),
+    };
+    const code = await mintMachinePairingCodeV1(SECRET, claims);
+    const [payload, tag] = [
+      code.slice(0, code.lastIndexOf(".")),
+      code.slice(code.lastIndexOf(".") + 1),
+    ];
+    const otherMachine = await mintMachinePairingCodeV1(SECRET, {
+      ...claims,
+      machineId: crypto.randomUUID(),
+    });
+    // The tag of one code on the payload of another: the pairing that would
+    // let a caller redirect an offer at a machine it names itself.
+    const spliced = `${payload}.${otherMachine.slice(otherMachine.lastIndexOf(".") + 1)}`;
+    for (const forged of [
+      spliced,
+      `${payload}x.${tag}`,
+      payload,
+      code.slice(0, -1),
+      "",
+    ]) {
+      await expect(verifyMachinePairingCodeV1(SECRET, forged)).rejects.toThrow(
+        /invalid/,
+      );
+    }
+    await expect(
+      verifyMachinePairingCodeV1(`${SECRET}-other`, code),
+    ).rejects.toThrow(/invalid/);
+  });
+
+  test("no two mints are the same code, and the digest is not the code", async () => {
+    const machineId = crypto.randomUUID();
+    const first = await mintMachinePairingCodeV1(SECRET, {
+      userId: "u",
+      machineId,
+      nonce: machinePairingNonceV1(),
+    });
+    const second = await mintMachinePairingCodeV1(SECRET, {
+      userId: "u",
+      machineId,
+      nonce: machinePairingNonceV1(),
+    });
+    expect(first).not.toBe(second);
+    const digest = await machinePairingCodeDigestV1(first);
+    expect(digest).toMatch(/^[0-9a-f]{64}$/);
+    expect(digest).not.toContain(first);
+  });
+
+  test("a secret that is missing or too weak refuses to mint", async () => {
+    await expect(
+      mintMachinePairingCodeV1("short", {
+        userId: "u",
+        machineId: crypto.randomUUID(),
+        nonce: machinePairingNonceV1(),
+      }),
+    ).rejects.toThrow(/MACHINE_TOKEN_SECRET/);
+  });
+});

package/src/pairing.ts

@@ -0,0 +1,182 @@
+// The pairing code: the one secret a browser ever holds for a machine.
+//
+// A device agent that has never enrolled has no token, so the code is the only
+// thing it can present — and `POST /api/machines/enroll` runs *before* gateway
+// authentication, because a program on somebody's laptop has no session. That
+// puts the code in exactly the position `plugin-routines`' webhook key is in:
+// the gateway is stateless and cannot map a machine to its User, so a code that
+// did not name one would force an anonymous caller to decide which Durable
+// Object gets created. So the code is a signed token, not a random string:
+//
+//   base64url(userId) "." machineId "." nonce "." truncated-HMAC
+//
+// The signature is checked at the edge, in constant time, before any object is
+// addressed; the User Durable Object then checks the code's digest against the
+// unspent pairing record it holds, which is what makes the code *one-time* and
+// what expires it after five minutes. Neither check is sufficient alone: the
+// signature proves only that this deployment minted the code, and the record
+// proves only that some code was minted for this machine.
+//
+// The code is derived and never stored, exactly as the machine token is: the
+// backend keeps `SHA-256(code)` and nothing else.
+
+import {
+  constantTimeEqualsV1,
+  MACHINE_LIMITS_V1,
+  MachineTokenError,
+} from "@frockbot/machine-protocol";
+
+/** What a verified pairing code names. */
+export interface MachinePairingClaimsV1 {
+  userId: string;
+  machineId: string;
+  nonce: string;
+}
+
+/** The one thing a failed verify ever says. Which half failed is not the caller's. */
+const INVALID = "machine pairing code is invalid";
+
+const TEXT = new TextEncoder();
+
+/**
+ * 128 bits of tag and 96 bits of nonce.
+ *
+ * The full `HMAC-SHA256` output would be 43 base64url characters and the code
+ * has a length ceiling it must live inside — `MACHINE_LIMITS_V1.pairingCode` —
+ * which the User claim already spends most of. A 128-bit tag is the standard
+ * truncation and is not the code's only defence: the code is single-use, dies
+ * in five minutes, and is checked against a stored digest.
+ */
+const TAG_BYTES = 16;
+const NONCE_BYTES = 12;
+
+function base64url(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary)
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+}
+
+function fromBase64url(value: string): Uint8Array {
+  const padded = value.replace(/-/g, "+").replace(/_/g, "/");
+  const binary = atob(padded + "=".repeat((4 - (padded.length % 4)) % 4));
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index += 1) {
+    bytes[index] = binary.charCodeAt(index);
+  }
+  return bytes;
+}
+
+function hex(bytes: ArrayBuffer): string {
+  return [...new Uint8Array(bytes)]
+    .map((byte) => byte.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+async function signingKey(secret: string): Promise<CryptoKey> {
+  if (typeof secret !== "string" || secret.length < 16) {
+    throw new MachineTokenError(
+      500,
+      "MACHINE_TOKEN_SECRET is missing or too short to mint a pairing code",
+    );
+  }
+  return crypto.subtle.importKey(
+    "raw",
+    TEXT.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+}
+
+async function tag(secret: string, payload: string): Promise<string> {
+  const signature = await crypto.subtle.sign(
+    "HMAC",
+    await signingKey(secret),
+    TEXT.encode(payload),
+  );
+  return base64url(new Uint8Array(signature).slice(0, TAG_BYTES));
+}
+
+/** A fresh, unpredictable nonce. One per mint, so no two codes are the same. */
+export function machinePairingNonceV1(): string {
+  return base64url(crypto.getRandomValues(new Uint8Array(NONCE_BYTES)));
+}
+
+/** `SHA-256` of a code, hex. The only form of a code the backend keeps. */
+export async function machinePairingCodeDigestV1(
+  code: string,
+): Promise<string> {
+  return hex(await crypto.subtle.digest("SHA-256", TEXT.encode(code)));
+}
+
+/**
+ * Mint one pairing code. Deterministic given the nonce, so a test can mint the
+ * exact code it is about to present and a forged one it must be refused.
+ */
+export async function mintMachinePairingCodeV1(
+  secret: string,
+  claims: MachinePairingClaimsV1,
+): Promise<string> {
+  const payload = `${base64url(TEXT.encode(claims.userId))}.${claims.machineId}.${claims.nonce}`;
+  const code = `${payload}.${await tag(secret, payload)}`;
+  if (code.length > MACHINE_LIMITS_V1.pairingCode) {
+    // Refused rather than truncated: a code the enrollment decoder would
+    // refuse is a pairing that fails at the machine instead of here, with
+    // nothing to say why.
+    throw new MachineTokenError(
+      500,
+      "machine pairing code exceeds its length bound for this account",
+    );
+  }
+  return code;
+}
+
+/**
+ * Verify a presented code and answer with the claims it carries.
+ *
+ * This is the edge's whole decision. Whether the code has been spent, has
+ * expired, or was ever minted for this machine is the User Durable Object's to
+ * answer against the pairing record it holds — and it is asked only after the
+ * code proved it was minted here.
+ */
+export async function verifyMachinePairingCodeV1(
+  secret: string,
+  code: string,
+): Promise<MachinePairingClaimsV1> {
+  if (
+    typeof code !== "string" ||
+    code.length === 0 ||
+    code.length > MACHINE_LIMITS_V1.pairingCode
+  ) {
+    throw new MachineTokenError(401, INVALID);
+  }
+  const separator = code.lastIndexOf(".");
+  if (separator <= 0) throw new MachineTokenError(401, INVALID);
+  const payload = code.slice(0, separator);
+  const presented = code.slice(separator + 1);
+  let expected: string;
+  try {
+    expected = await tag(secret, payload);
+  } catch (error) {
+    if (error instanceof MachineTokenError) throw error;
+    throw new MachineTokenError(401, INVALID);
+  }
+  if (!constantTimeEqualsV1(expected, presented)) {
+    throw new MachineTokenError(401, INVALID);
+  }
+  const parts = payload.split(".");
+  if (parts.length !== 3) throw new MachineTokenError(401, INVALID);
+  let userId: string;
+  try {
+    userId = new TextDecoder().decode(fromBase64url(parts[0]!));
+  } catch {
+    throw new MachineTokenError(401, INVALID);
+  }
+  if (userId.length === 0 || userId.length > 256) {
+    throw new MachineTokenError(401, INVALID);
+  }
+  return { userId, machineId: parts[1]!, nonce: parts[2]! };
+}