@frockbot/machine-protocol 0.0.0 → 0.1.0

package/src/token.test.ts

@@ -0,0 +1,149 @@
+import { describe, expect, test } from "bun:test";
+import {
+  MACHINE_AUTHORIZATION_SCHEME,
+  MachineTokenError,
+  constantTimeEqualsV1,
+  machineBearerTokenV1,
+  machineTokenClaimsV1,
+  machineTokenDigestV1,
+  machineTokenMatchesRecordV1,
+  mintMachineTokenV1,
+  verifyMachineTokenV1,
+} from "./token.ts";
+
+const SECRET = "machine-token-secret-value-32-bytes";
+const MACHINE_ID = "994dc2ee-3f42-4a4d-9f2a-0a3f6f0d1b77";
+const CLAIMS = { u: "user-1", m: MACHINE_ID, v: 1 } as const;
+
+describe("machine token", () => {
+  test("round-trips its claims and is deterministic", async () => {
+    const token = await mintMachineTokenV1(SECRET, CLAIMS);
+    expect(await mintMachineTokenV1(SECRET, CLAIMS)).toBe(token);
+    expect(await verifyMachineTokenV1(SECRET, token)).toEqual({ ...CLAIMS });
+  });
+
+  test("a tampered payload, signature or secret never verifies", async () => {
+    const token = await mintMachineTokenV1(SECRET, CLAIMS);
+    const [payload, signature] = token.split(".");
+    const forged = btoa(JSON.stringify({ u: "user-2", m: MACHINE_ID, v: 1 }))
+      .replace(/\+/g, "-")
+      .replace(/\//g, "_")
+      .replace(/=+$/, "");
+    for (const bad of [
+      `${forged}.${signature}`,
+      `${payload}.${signature!.slice(0, -1)}A`,
+      payload!,
+      "",
+      "x".repeat(4_096),
+    ]) {
+      await expect(verifyMachineTokenV1(SECRET, bad)).rejects.toThrow(
+        MachineTokenError,
+      );
+    }
+    await expect(
+      verifyMachineTokenV1("another-secret-of-sufficient-length", token),
+    ).rejects.toThrow(/machine token is invalid/);
+  });
+
+  test("a secret too short to be a secret fails loudly, not silently", async () => {
+    await expect(mintMachineTokenV1("short", CLAIMS)).rejects.toThrow(
+      /MACHINE_TOKEN_SECRET/,
+    );
+  });
+
+  test("claims are exact-key and bounded", () => {
+    expect(machineTokenClaimsV1({ ...CLAIMS })).toEqual({ ...CLAIMS });
+    for (const bad of [
+      { ...CLAIMS, extra: 1 },
+      { u: "", m: MACHINE_ID, v: 1 },
+      { u: "user-1", m: "not a machine id", v: 1 },
+      { u: "user-1", m: MACHINE_ID, v: 0 },
+      { u: "user-1", m: MACHINE_ID, v: 1.5 },
+      { u: "user-1", m: MACHINE_ID },
+      [CLAIMS],
+      null,
+    ]) {
+      expect(() => machineTokenClaimsV1(bad)).toThrow(MachineTokenError);
+    }
+  });
+
+  test("verification says nothing about which half failed", async () => {
+    const token = await mintMachineTokenV1(SECRET, CLAIMS);
+    const failure = await verifyMachineTokenV1(SECRET, `${token}x`).catch(
+      (error: MachineTokenError) => error,
+    );
+    expect((failure as MachineTokenError).status).toBe(401);
+    expect((failure as MachineTokenError).message).toBe(
+      "machine token is invalid",
+    );
+  });
+});
+
+describe("digest-only storage", () => {
+  test("the digest is a hex SHA-256 and the token is not recoverable from it", async () => {
+    const token = await mintMachineTokenV1(SECRET, CLAIMS);
+    const digest = await machineTokenDigestV1(token);
+    expect(digest).toMatch(/^[0-9a-f]{64}$/);
+    expect(digest).not.toContain(token.slice(0, 8));
+    expect(await machineTokenDigestV1(token)).toBe(digest);
+    expect(await machineTokenDigestV1(`${token} `)).not.toBe(digest);
+  });
+
+  test("the record check refuses a wrong key version, a wrong digest and a revocation", async () => {
+    const token = await mintMachineTokenV1(SECRET, CLAIMS);
+    const digest = await machineTokenDigestV1(token);
+    const record = { keyVersion: 1, tokenDigest: digest };
+    expect(machineTokenMatchesRecordV1(record, CLAIMS, digest)).toBe(true);
+    // Revocation bumps the key version: a token minted at v1 verifies at the
+    // edge and is still refused by the record, which is the second check.
+    const rotated = await mintMachineTokenV1(SECRET, { ...CLAIMS, v: 2 });
+    expect(
+      machineTokenMatchesRecordV1(
+        record,
+        { ...CLAIMS, v: 2 },
+        await machineTokenDigestV1(rotated),
+      ),
+    ).toBe(false);
+    expect(machineTokenMatchesRecordV1(record, CLAIMS, "b".repeat(64))).toBe(
+      false,
+    );
+    expect(
+      machineTokenMatchesRecordV1(
+        { ...record, revokedAt: "2026-09-01T00:00:00.000Z" },
+        CLAIMS,
+        digest,
+      ),
+    ).toBe(false);
+  });
+});
+
+describe("constant-time compare", () => {
+  test("answers on content, not on where the first difference is", () => {
+    expect(constantTimeEqualsV1("abc", "abc")).toBe(true);
+    expect(constantTimeEqualsV1("abc", "abd")).toBe(false);
+    expect(constantTimeEqualsV1("abc", "zbc")).toBe(false);
+    expect(constantTimeEqualsV1("abc", "abcd")).toBe(false);
+    expect(constantTimeEqualsV1("", "")).toBe(true);
+    expect(constantTimeEqualsV1("abc", "")).toBe(false);
+  });
+});
+
+describe("bearer presentation", () => {
+  test("reads a token only under the declared scheme", () => {
+    expect(
+      machineBearerTokenV1(`${MACHINE_AUTHORIZATION_SCHEME} abc.def`),
+    ).toBe("abc.def");
+    expect(machineBearerTokenV1("Bearer   abc.def  ")).toBe("abc.def");
+    for (const bad of [
+      "bearer abc.def",
+      "Basic abc.def",
+      "abc.def",
+      "Bearer ",
+      "Bearer",
+      null,
+      undefined,
+    ]) {
+      expect(machineBearerTokenV1(bad)).toBeUndefined();
+    }
+  });
+});

package/src/token.ts

@@ -0,0 +1,241 @@
+// The machine door: the key an agent presents, and the two places it is checked.
+//
+// A device agent has no session — it is a program on the User's laptop, not a
+// browser — so `poll`, `claim` and `result` run before gateway authentication.
+// That makes the token the only thing standing between the open internet and a
+// Durable Object, and one check is not enough. This is `plugin-routines`'
+// webhook door, port for port:
+//
+//  1. **At the edge**, the token is a *self-describing signed token*. Its
+//     payload names the User, the machine and the key version; its signature is
+//     `HMAC-SHA256(MACHINE_TOKEN_SECRET, payload)`. The gateway is stateless
+//     and cannot map a machine to its User, so without the claims it could not
+//     address a Durable Object at all without first creating one — which would
+//     hand an anonymous caller Durable Object creation. A token that does not
+//     verify never reaches an object.
+//  2. **In the User Durable Object**, `SHA-256(token)` is compared against the
+//     `tokenDigest` on the machine record, together with its `keyVersion`. That
+//     record is the authority: revocation bumps the version and sets
+//     `revokedAt`, so a token that verified at the edge is still refused the
+//     instant it is no longer the machine's.
+//
+// The token is derived, never stored: given the secret and the three payload
+// fields it is reproducible, and the digest is all the backend keeps. Nothing
+// here writes key material to durable storage, and no view carries any.
+
+import { decodeMachineIdV1 } from "./protocol.js";
+
+/** The self-describing claims a machine token carries. */
+export interface MachineTokenClaimsV1 {
+  /** User. */
+  u: string;
+  /** Machine. */
+  m: string;
+  /** Key version. */
+  v: number;
+}
+
+export class MachineTokenError extends Error {
+  override readonly name = "MachineTokenError";
+  readonly status: number;
+  constructor(status: number, message: string) {
+    super(message);
+    this.status = status;
+  }
+}
+
+/** The one thing a failed verify ever says. Which half failed is not the caller's. */
+const INVALID = "machine token is invalid";
+
+const TEXT = new TextEncoder();
+
+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("");
+}
+
+/**
+ * Constant-time comparison. A signature check that returns early on the first
+ * differing byte leaks the signature one byte at a time to anyone willing to
+ * time it, and this check is the whole of the edge's authority.
+ */
+export function constantTimeEqualsV1(left: string, right: string): boolean {
+  const a = TEXT.encode(left);
+  const b = TEXT.encode(right);
+  // The lengths themselves are not secret; the contents are, so the loop runs
+  // over a fixed span either way.
+  let mismatch = a.length ^ b.length;
+  const span = Math.max(a.length, b.length);
+  for (let index = 0; index < span; index += 1) {
+    mismatch |= (a[index] ?? 0) ^ (b[index] ?? 0);
+  }
+  return mismatch === 0;
+}
+
+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 for machine enrollment",
+    );
+  }
+  return crypto.subtle.importKey(
+    "raw",
+    TEXT.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+}
+
+/** `SHA-256` of a token, hex. The only form of a key the backend keeps. */
+export async function machineTokenDigestV1(token: string): Promise<string> {
+  return hex(await crypto.subtle.digest("SHA-256", TEXT.encode(token)));
+}
+
+/** Mint the token for one machine at one key version. Deterministic. */
+export async function mintMachineTokenV1(
+  secret: string,
+  claims: MachineTokenClaimsV1,
+): Promise<string> {
+  const payload = base64url(
+    TEXT.encode(JSON.stringify({ u: claims.u, m: claims.m, v: claims.v })),
+  );
+  const signature = await crypto.subtle.sign(
+    "HMAC",
+    await signingKey(secret),
+    TEXT.encode(payload),
+  );
+  return `${payload}.${base64url(new Uint8Array(signature))}`;
+}
+
+/**
+ * Verify a presented token and answer with the claims it carries.
+ *
+ * This is the edge's whole decision. It says nothing about whether the machine
+ * exists, is revoked, or still holds this key version — those are the User
+ * Durable Object's to answer against `tokenDigest`, and are answered only after
+ * the token proved it was minted here.
+ */
+export async function verifyMachineTokenV1(
+  secret: string,
+  token: string,
+): Promise<MachineTokenClaimsV1> {
+  if (typeof token !== "string" || token.length === 0 || token.length > 2_048) {
+    throw new MachineTokenError(401, INVALID);
+  }
+  const separator = token.lastIndexOf(".");
+  if (separator <= 0) throw new MachineTokenError(401, INVALID);
+  const payload = token.slice(0, separator);
+  const presented = token.slice(separator + 1);
+  let expected: string;
+  try {
+    expected = base64url(
+      new Uint8Array(
+        await crypto.subtle.sign(
+          "HMAC",
+          await signingKey(secret),
+          TEXT.encode(payload),
+        ),
+      ),
+    );
+  } catch (error) {
+    if (error instanceof MachineTokenError) throw error;
+    throw new MachineTokenError(401, INVALID);
+  }
+  if (!constantTimeEqualsV1(expected, presented)) {
+    throw new MachineTokenError(401, INVALID);
+  }
+  let decoded: unknown;
+  try {
+    decoded = JSON.parse(new TextDecoder().decode(fromBase64url(payload)));
+  } catch {
+    throw new MachineTokenError(401, INVALID);
+  }
+  return machineTokenClaimsV1(decoded);
+}
+
+/** Decode the claims half of a token. Exact-key, like every other seam. */
+export function machineTokenClaimsV1(value: unknown): MachineTokenClaimsV1 {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new MachineTokenError(401, INVALID);
+  }
+  const candidate = value as Record<string, unknown>;
+  for (const key of Object.keys(candidate)) {
+    if (key !== "u" && key !== "m" && key !== "v") {
+      throw new MachineTokenError(401, INVALID);
+    }
+  }
+  const held = candidate.u;
+  if (typeof held !== "string" || held.length === 0 || held.length > 256) {
+    throw new MachineTokenError(401, INVALID);
+  }
+  let machineId: string;
+  try {
+    machineId = decodeMachineIdV1(candidate.m, "machine token m");
+  } catch {
+    throw new MachineTokenError(401, INVALID);
+  }
+  if (
+    !Number.isSafeInteger(candidate.v) ||
+    (candidate.v as number) < 1 ||
+    (candidate.v as number) > 1_000_000
+  ) {
+    throw new MachineTokenError(401, INVALID);
+  }
+  return { u: held, m: machineId, v: candidate.v as number };
+}
+
+/**
+ * The second check, expressed once so the Durable Object and its tests cannot
+ * drift: the presented token's digest must be the record's, at the record's
+ * current key version, and the record must not be revoked. Answering `false`
+ * rather than throwing keeps the caller free to choose 401 or 403.
+ */
+export function machineTokenMatchesRecordV1(
+  record: { keyVersion: number; tokenDigest: string; revokedAt?: string },
+  claims: MachineTokenClaimsV1,
+  presentedDigest: string,
+): boolean {
+  if (record.revokedAt !== undefined) return false;
+  if (record.keyVersion !== claims.v) return false;
+  return constantTimeEqualsV1(record.tokenDigest, presentedDigest);
+}
+
+/** The scheme a machine presents its token under, at every machine route. */
+export const MACHINE_AUTHORIZATION_SCHEME = "Bearer";
+
+/**
+ * The token out of an `Authorization` header, or `undefined`. Parsing lives in
+ * the protocol so the gateway, the desktop agent and the stub agent all agree
+ * on what a presented token looks like before anyone tries to verify one.
+ */
+export function machineBearerTokenV1(
+  header: string | null | undefined,
+): string | undefined {
+  if (typeof header !== "string") return undefined;
+  const prefix = `${MACHINE_AUTHORIZATION_SCHEME} `;
+  if (!header.startsWith(prefix)) return undefined;
+  const token = header.slice(prefix.length).trim();
+  return token.length === 0 ? undefined : token;
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "lib": ["ES2023", "DOM"],
+    "types": ["bun"],
+    "allowImportingTsExtensions": true
+  },
+  "include": ["src/**/*.ts"]
+}

package/README.md

@@ -1,3 +0,0 @@
-# @frockbot/machine-protocol
-
-Placeholder reserving this name. See https://github.com/timoconnellaus/frockbot.