@frockbot/cloudflare 0.0.0 → 0.7.291

package/src/debug.ts

@@ -0,0 +1,272 @@
+import {
+  decodeBotDebugQueryV1,
+  isBotDebugQueryRefusalV1,
+  type BotDebugQueryV1,
+} from "@frockbot/app/shell/debug-protocol";
+import {
+  decodeSetUserFeaturesCommandV1,
+  type SetUserFeaturesCommandV1,
+  type UserFeaturesV1,
+} from "@frockbot/app/admin/shared";
+import { decodeBotIdV1 } from "@frockbot/core/configuration";
+import { constantTimeEqualsV1 } from "@frockbot/core/crypto";
+
+/**
+ * The operator surface: `/api/debug/*`, authorized by a shared token rather
+ * than by a session, so it can be read from a terminal while a Bot is wedged
+ * and nobody is signed in.
+ *
+ * Two routes write. A Turn send requires both the debug token and an
+ * owner/admin identity, then enters the ordinary client Turn path with its
+ * ownership check, admission/refusal handling and size limit. An account's
+ * features write is the operator's half of administration: the admin portal is
+ * the hosted deployment's surface for it (ADR 0028), and a deployment with no
+ * portal — a self-hosted one, a test stack — turns Plugin authoring on for an
+ * account from here, under the same deployment secret. Nothing here
+ * can reconcile, cancel, or otherwise move an existing run.
+ */
+export interface DebugGatewaySurface {
+  /** Absent (or empty) disables the whole surface; the routes then 404. */
+  token?: string;
+  listUsers(): Promise<
+    Array<{ id: string; email: string; name: string; createdAt: string }>
+  >;
+  listBots(userId: string): Promise<unknown>;
+  snapshot(
+    userId: string,
+    botId: string,
+    query: BotDebugQueryV1,
+  ): Promise<unknown>;
+  /**
+   * The User's voice assistant ledger: calls, spoken turns with their
+   * transcripts, and the Bot delegations each made. Absent on a deployment
+   * with no voice objects; the route then 404s.
+   */
+  voice?(userId: string): Promise<unknown>;
+  isAdminUser(userId: string): Promise<boolean>;
+  setAccountFeatures(
+    userId: string,
+    command: SetUserFeaturesCommandV1,
+  ): Promise<UserFeaturesV1>;
+}
+
+export type DebugTurnSubmitter = (
+  userId: string,
+  botId: string,
+  text: string,
+) => Promise<Response>;
+
+const DEBUG_PREFIX = "/api/debug";
+
+function jsonError(status: number, message: string): Response {
+  return Response.json({ error: message }, { status });
+}
+
+function forbiddenUser(): Response {
+  return new Response(
+    "Debug Turn submission is only allowed for an administrator account.",
+    {
+      status: 403,
+      headers: { "content-type": "text/plain; charset=utf-8" },
+    },
+  );
+}
+
+/**
+ * Length-independent, constant-time within a length: a token comparison that
+ * returns early leaks the token one character at a time.
+ */
+function tokenMatches(presented: string, expected: string): boolean {
+  return constantTimeEqualsV1(presented, expected);
+}
+
+function presentedToken(request: Request): string | undefined {
+  const header = request.headers.get("authorization");
+  if (header?.toLowerCase().startsWith("bearer ")) {
+    return header.slice("bearer ".length).trim();
+  }
+  return request.headers.get("x-frockbot-debug-token")?.trim() ?? undefined;
+}
+
+/**
+ * The query the URL carries, decoded here rather than inside the Bot: the same
+ * decoder the Durable Object applies, run in the gateway so a query the
+ * operator got wrong is answered as a 400 and never becomes an uncaught
+ * failure in the Bot's isolate.
+ */
+function debugQuery(url: URL): BotDebugQueryV1 {
+  const limit = url.searchParams.get("limit");
+  const before = url.searchParams.get("before");
+  const events = url.searchParams.get("events");
+  return decodeBotDebugQueryV1({
+    schemaVersion: 1,
+    // `Number("nonsense")` is `NaN`, which the decoder refuses with the same
+    // sentence a limit past the cap gets — one message for one bad field.
+    ...(limit === null ? {} : { limit: Number(limit) }),
+    ...(before === null ? {} : { before }),
+    ...(events === null ? {} : { events: events === "true" || events === "1" }),
+  });
+}
+
+function debugTurnText(input: unknown): string {
+  if (typeof input !== "object" || input === null || Array.isArray(input)) {
+    throw new Error("debug Turn body must be an object");
+  }
+  const body = input as Record<string, unknown>;
+  if (Object.keys(body).some((key) => key !== "text")) {
+    throw new Error("debug Turn body only accepts text");
+  }
+  if (typeof body.text !== "string") {
+    throw new Error("debug Turn body.text must be a string");
+  }
+  return body.text;
+}
+
+/**
+ * Mounted ahead of authentication in the gateway, so it answers with no
+ * session. Returns `undefined` for any path it does not own.
+ */
+export function createDebugRoute(
+  surface: DebugGatewaySurface | undefined,
+  submitTurn?: DebugTurnSubmitter,
+): (request: Request, url: URL) => Promise<Response | undefined> {
+  return async (request, url) => {
+    if (
+      url.pathname !== DEBUG_PREFIX &&
+      !url.pathname.startsWith(`${DEBUG_PREFIX}/`)
+    ) {
+      return undefined;
+    }
+    // An unconfigured deployment does not admit that the surface exists.
+    if (!surface?.token) return jsonError(404, "not found");
+    const presented = presentedToken(request);
+    if (!presented || !tokenMatches(presented, surface.token)) {
+      return jsonError(401, "debug token required");
+    }
+
+    const path = url.pathname.slice(DEBUG_PREFIX.length);
+    try {
+      const sendMatch = path.match(/^\/users\/([^/]+)\/bots\/([^/]+)\/turns$/);
+      if (sendMatch) {
+        if (request.method !== "POST") {
+          return jsonError(405, "method not allowed");
+        }
+        const userId = decodeURIComponent(sendMatch[1]!);
+        const botId = decodeBotIdV1(decodeURIComponent(sendMatch[2]!));
+        // Resolve the durable sign-in identity before reading or forwarding
+        // the body. The debug token alone never gains authority to speak as an
+        // arbitrary User, and a User with no identity row is denied too.
+        if (!(await surface.isAdminUser(userId))) return forbiddenUser();
+        let text: string;
+        try {
+          text = debugTurnText(await request.json());
+        } catch (error) {
+          return jsonError(
+            400,
+            error instanceof Error
+              ? error.message
+              : "debug Turn body is invalid",
+          );
+        }
+        // This is the only write on `/api/debug`: `submitTurn` forwards an
+        // ordinary client command to the loaded User application, so the
+        // response (including a 409 admission refusal or a 413 size refusal)
+        // is returned byte-for-byte with its original status.
+        if (!submitTurn)
+          return jsonError(503, "debug Turn send is unavailable");
+        return submitTurn(userId, botId, text);
+      }
+
+      const featuresMatch = path.match(/^\/users\/([^/]+)\/features$/);
+      if (featuresMatch) {
+        if (request.method !== "POST") {
+          return jsonError(405, "method not allowed");
+        }
+        const userId = decodeURIComponent(featuresMatch[1]!);
+        let command: SetUserFeaturesCommandV1;
+        try {
+          command = decodeSetUserFeaturesCommandV1(await request.json());
+        } catch (error) {
+          return jsonError(
+            400,
+            error instanceof Error
+              ? error.message
+              : "account features command is invalid",
+          );
+        }
+        // The account is not provisioned or admitted by this write: the record
+        // is the account's own, and an account that never signs in keeps it.
+        return Response.json(await surface.setAccountFeatures(userId, command));
+      }
+
+      // Every other debug route is read-only.
+      if (request.method !== "GET") return jsonError(405, "method not allowed");
+      if (path === "" || path === "/") {
+        return Response.json({
+          schemaVersion: 1,
+          routes: [
+            "GET /api/debug/users",
+            "GET /api/debug/bots?userId=<id>",
+            "GET /api/debug/bots/<botId>?userId=<id>&limit=<n>&events=true&before=<cursor>",
+            "GET /api/debug/bots/<botId>/runs/<runId>?userId=<id>",
+            "GET /api/debug/voice?userId=<id>",
+            "POST /api/debug/users/<userId>/bots/<botId>/turns",
+            "POST /api/debug/users/<userId>/features",
+          ],
+        });
+      }
+      if (path === "/users") {
+        return Response.json({
+          schemaVersion: 1,
+          users: await surface.listUsers(),
+        });
+      }
+
+      const userId = url.searchParams.get("userId")?.trim();
+      if (path === "/bots") {
+        if (!userId) return jsonError(400, "userId is required");
+        return Response.json(await surface.listBots(userId));
+      }
+      if (path === "/voice") {
+        if (!surface.voice) return jsonError(404, "not found");
+        if (!userId) return jsonError(400, "userId is required");
+        return Response.json(await surface.voice(userId));
+      }
+      const runMatch = path.match(/^\/bots\/([^/]+)\/runs\/([^/]+)$/);
+      const botMatch = path.match(/^\/bots\/([^/]+)$/);
+      if (!runMatch && !botMatch) return jsonError(404, "not found");
+      if (!userId) return jsonError(400, "userId is required");
+      const botId = decodeBotIdV1(
+        decodeURIComponent((runMatch ?? botMatch)![1]!),
+      );
+      const query = runMatch
+        ? decodeBotDebugQueryV1({
+            schemaVersion: 1,
+            runId: decodeURIComponent(runMatch[2]!),
+          })
+        : debugQuery(url);
+      return Response.json(await surface.snapshot(userId, botId, query));
+    } catch (error) {
+      // A query the caller got wrong is their 400, not the deployment's 500 —
+      // and the message says the range so the next attempt can be right.
+      if (isBotDebugQueryRefusalV1(error)) {
+        return jsonError(
+          400,
+          error instanceof Error ? error.message : "debug query is invalid",
+        );
+      }
+      // The operator is the audience: the message is the finding, and a stack
+      // that reached here is more useful than a generic 500.
+      return Response.json(
+        {
+          error:
+            error instanceof Error ? error.message : "debug request failed",
+          ...(error instanceof Error && error.stack
+            ? { stack: error.stack }
+            : {}),
+        },
+        { status: 500 },
+      );
+    }
+  };
+}

package/src/default-packages-marker-cleanup.ts

@@ -0,0 +1,39 @@
+// Disposable pre-user cleanup for retired default-Package bootstrap markers.
+//
+// Markers v1–v3 are `{ schemaVersion: 1 | 2 | 3 }` with no ledger. The decoder
+// no longer accepts them. This pass deletes those records before any request
+// or alarm can read settings, so the next read is the no-marker seed. A v4
+// ledger is left alone. The receipt makes a second load free.
+
+export const DEFAULT_PACKAGES_MARKER_KEY = "user-default-packages-bootstrap:v1";
+export const DEFAULT_PACKAGES_MARKER_CLEANUP_RECEIPT_KEY =
+  "maintenance:default-packages-marker:2026-09-20";
+
+export function isRetiredDefaultPackagesMarker(value: unknown): boolean {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+  const keys = Object.keys(value);
+  if (keys.length !== 1 || keys[0] !== "schemaVersion") return false;
+  const version = (value as { schemaVersion?: unknown }).schemaVersion;
+  return version === 1 || version === 2 || version === 3;
+}
+
+export async function cleanDefaultPackagesMarkerV1(
+  storage: DurableObjectStorage,
+  now: Date = new Date(),
+): Promise<void> {
+  if (await storage.get(DEFAULT_PACKAGES_MARKER_CLEANUP_RECEIPT_KEY)) return;
+  await storage.transaction(async (tx) => {
+    if (await tx.get(DEFAULT_PACKAGES_MARKER_CLEANUP_RECEIPT_KEY)) return;
+    const marker = await tx.get<unknown>(DEFAULT_PACKAGES_MARKER_KEY);
+    const removed = isRetiredDefaultPackagesMarker(marker);
+    if (removed) {
+      await tx.delete(DEFAULT_PACKAGES_MARKER_KEY);
+    }
+    await tx.put(DEFAULT_PACKAGES_MARKER_CLEANUP_RECEIPT_KEY, {
+      at: now.toISOString(),
+      removed,
+    });
+  });
+}

package/src/deployment-policy-admin-host.ts

@@ -0,0 +1,121 @@
+import type { AdminOperationsHostV1 } from "@frockbot/app/admin/operations";
+import {
+  AccountAccessConflictError,
+  decodeAccountAccessV1,
+  decodeAccountAccessViewV1,
+  decodeAdminWriteResultV1,
+  decodeDeploymentPolicyV1,
+  decodeEmailInvitationV1,
+  DeploymentPolicyConflictError,
+} from "@frockbot/app/admin/shared";
+import {
+  decodeHostedModelRatesV1,
+  decodeHostedModelRatesViewV1,
+  ModelRatesConflictError,
+} from "@frockbot/app/billing/rates";
+import { rpcJsonSnapshotV1 } from "./durable-rpc.js";
+
+interface DeploymentPolicyAdminRpc {
+  readPolicy(input: unknown): Promise<unknown>;
+  setAdmissionMode(input: unknown): Promise<unknown>;
+  readAccountAccess(input: unknown): Promise<unknown>;
+  setAccountAccess(input: unknown): Promise<unknown>;
+  inviteEmail(input: unknown): Promise<unknown>;
+  readModelRatesView(input: unknown): Promise<unknown>;
+  saveModelRates(input: unknown): Promise<unknown>;
+}
+
+function appliedWrite(
+  answer: unknown,
+  conflict: (currentRevision: number) => Error,
+): unknown {
+  const write = rpcJsonSnapshotV1(answer) as Record<string, unknown> | null;
+  let decoded;
+  try {
+    decoded = decodeAdminWriteResultV1(
+      write,
+      (value) => value,
+      "access authority write result",
+    );
+  } catch {
+    throw new Error("access authority answered an unknown write result");
+  }
+  if (decoded.status === "conflict") throw conflict(decoded.currentRevision);
+  return decoded.value;
+}
+
+export function createDeploymentPolicyAdminHost(
+  authority: () => DeploymentPolicyAdminRpc,
+): Pick<
+  AdminOperationsHostV1,
+  | "readDeploymentPolicy"
+  | "setAdmissionMode"
+  | "readAccountAccess"
+  | "setAccountAccess"
+  | "inviteEmail"
+  | "readModelRates"
+  | "saveModelRates"
+> {
+  return {
+    readDeploymentPolicy: async () =>
+      decodeDeploymentPolicyV1(
+        rpcJsonSnapshotV1(await authority().readPolicy({ schemaVersion: 1 })),
+      ),
+    setAdmissionMode: async (command, updatedBy) =>
+      decodeDeploymentPolicyV1(
+        appliedWrite(
+          await authority().setAdmissionMode({
+            schemaVersion: 1,
+            command,
+            updatedBy,
+          }),
+          (revision) => new DeploymentPolicyConflictError(revision),
+        ),
+      ),
+    readAccountAccess: async (userId) =>
+      decodeAccountAccessViewV1(
+        rpcJsonSnapshotV1(
+          await authority().readAccountAccess({ schemaVersion: 1, userId }),
+        ),
+      ),
+    setAccountAccess: async (userId, command, updatedBy) =>
+      decodeAccountAccessV1(
+        appliedWrite(
+          await authority().setAccountAccess({
+            schemaVersion: 1,
+            userId,
+            command,
+            updatedBy,
+          }),
+          (revision) => new AccountAccessConflictError(revision),
+        ),
+      ),
+    inviteEmail: async (command, invitedBy) =>
+      decodeEmailInvitationV1(
+        rpcJsonSnapshotV1(
+          await authority().inviteEmail({
+            schemaVersion: 1,
+            command,
+            invitedBy,
+          }),
+        ),
+      ),
+    readModelRates: async () =>
+      decodeHostedModelRatesViewV1(
+        rpcJsonSnapshotV1(
+          await authority().readModelRatesView({ schemaVersion: 1 }),
+        ),
+      ),
+    saveModelRates: async (command, createdBy) =>
+      decodeHostedModelRatesV1(
+        appliedWrite(
+          await authority().saveModelRates({
+            schemaVersion: 1,
+            command,
+            createdBy,
+          }),
+          (revision) => new ModelRatesConflictError(revision),
+        ),
+      ),
+  };
+}