@frockbot/cloudflare 0.0.0 → 0.7.291

package/src/audit.ts

@@ -0,0 +1,103 @@
+// The audit seam, bound in production.
+//
+// Two directions cross a Durable Object boundary here, and both are decoded on
+// arrival — "Cross-runtime communication uses narrow, versioned DTOs, and
+// every inbound value is decoded at its seam".
+//
+//  * `createUserAuditSinkV1` is the Bot Durable Object's half: a settled
+//    Turn's entries go to the User Durable Object, which is the authority for
+//    User-scoped state. Unlike the transcript index this is *not*
+//    fire-and-forget — the Bot object holds them in a bounded durable outbox
+//    until the User object accepts them (parity register row 30b), because an
+//    audit surface with silent gaps answers no question anybody asks of it.
+//  * `createBotAuditEntryPageV1` is the User Durable Object's half: one page
+//    of a Bot's entries, projected from that Bot's own stored runs, which is
+//    what makes the table rebuildable rather than authoritative.
+import {
+  auditEntriesFromStoredRunV1,
+  type AuditEntryPageV1,
+  type AuditEntryV1,
+  type AuditProjectableRunV1,
+  type AuditSinkV1,
+} from "@frockbot/app/audit";
+
+/** The User Durable Object's audit RPC surface, as the Bot object calls it. */
+export interface UserAuditRpc {
+  indexAuditEntries(input: unknown): Promise<unknown>;
+}
+
+/** The Bot Durable Object's projection RPC, as the User object calls it. */
+export interface BotAuditRpc {
+  projectAuditEntries(input: unknown): Promise<unknown>;
+}
+
+/**
+ * `AuditSinkV1` over the User Durable Object.
+ *
+ * A failure here *throws*, on purpose, and that is the difference between this
+ * sink and the transcript index's. The caller is draining a durable outbox: a
+ * throw leaves the entries queued for the next settlement or alarm, and
+ * swallowing it would turn an at-least-once queue into a silent drop. The Turn
+ * that produced them is already durable and is never failed by this.
+ */
+export function createUserAuditSinkV1(
+  rpc: UserAuditRpc,
+  identity: { userId: string; botId: string },
+): AuditSinkV1 {
+  return {
+    async indexEntries(entries: readonly AuditEntryV1[]) {
+      if (entries.length === 0) return;
+      const owned = entries.filter((entry) => entry.botId === identity.botId);
+      if (owned.length === 0) return;
+      await rpc.indexAuditEntries({
+        schemaVersion: 1,
+        userId: identity.userId,
+        botId: identity.botId,
+        entries: owned,
+      });
+    },
+  };
+}
+
+/** The stored-run page the Shell Package offers, as this adapter reads it. */
+export interface StoredRunEventPageV1 {
+  runs: ReadonlyArray<{
+    runId: string;
+    acceptedAt: string;
+    status: string;
+    events: AuditProjectableRunV1["events"];
+  }>;
+  nextCursor?: string;
+}
+
+/**
+ * One page of a Bot's entries, projected from its own durable session events.
+ *
+ * The *stored* run rather than the client projection: the client projection
+ * drops `call.input`, and the argument digest needs the exact arguments. Same
+ * function as settlement uses, so the entries a rebuild writes are the entries
+ * a settlement would have written — the property the whole "the table is a
+ * projection" claim rests on.
+ */
+export async function createBotAuditEntryPageV1(
+  botId: string,
+  page: StoredRunEventPageV1,
+): Promise<AuditEntryPageV1> {
+  const entries: AuditEntryV1[] = [];
+  for (const run of page.runs) {
+    entries.push(
+      ...(await auditEntriesFromStoredRunV1(botId, {
+        runId: run.runId,
+        status: run.status,
+        acceptedAt: run.acceptedAt,
+        events: run.events,
+      })),
+    );
+  }
+  return {
+    schemaVersion: 1,
+    botId,
+    entries,
+    ...(page.nextCursor === undefined ? {} : { nextCursor: page.nextCursor }),
+  };
+}

package/src/auth-package.access.ts

@@ -0,0 +1,24 @@
+/**
+ * How a simple deployment signs people in: Cloudflare Access, and nothing
+ * stored anywhere.
+ *
+ * The twin of `auth-package.ts`, which is the tracked default. A profile whose
+ * `authPackage` is `access` makes the generator write
+ * `alias: { "#auth-package": "<this file> }` into the app Worker's config, and
+ * wrangler resolves every `#auth-package` import here instead — so the Access
+ * bundle carries no better-auth and the hosted bundle carries no Access
+ * verifier. Neither file imports the other, which is what makes that true.
+ *
+ * `tsconfig.access.json` type-checks the whole Worker against this file, so an
+ * `env` name only the hosted build has cannot reach the Access build unnoticed.
+ */
+import type { AuthPackageBuildV1 } from "@frockbot/core/contracts";
+import { ACCESS_AUTH_PACKAGE_V1 } from "@frockbot/app/auth/access";
+import type { AccessEnvironmentV1 } from "@frockbot/app/auth/access";
+
+/** What a Worker must hand the Package this build deploys. */
+export type AuthPackageEnvironmentV1 = AccessEnvironmentV1;
+
+/** The sign-in Package this build deploys. */
+export const AUTH_PACKAGE_V1: AuthPackageBuildV1<AuthPackageEnvironmentV1> =
+  ACCESS_AUTH_PACKAGE_V1;

package/src/auth-package.ts

@@ -0,0 +1,36 @@
+/**
+ * How the hosted deployment signs people in: better-auth with Google.
+ *
+ * `AuthPackageV1` is the interface the gateway speaks to sign-in
+ * (`core/contracts/auth-package.ts`); this file and `auth-package.access.ts`
+ * are the two builds of it, and each is exactly one value import, so that a
+ * build is a one-line file and a `grep` finds it.
+ *
+ * This is the one the tracked source resolves: `wrangler dev`, every suite and
+ * the hosted deploy all reach it through `#auth-package`, which
+ * `apps/cloudflare/package.json` maps here. A profile whose `authPackage` is
+ * `access` gets a generated wrangler config carrying
+ * `alias: { "#auth-package": "<path to auth-package.access.ts>" }`, so the
+ * Access build resolves that specifier to the other file and this one is not in
+ * its bundle at all.
+ *
+ * `scripts/check-auth-package-imports.ts` keeps the `better-auth` dependency
+ * inside `app/auth/better-auth/**` and this file. Nothing else in the Worker may
+ * name an implementation.
+ */
+import type { AuthPackageBuildV1 } from "@frockbot/core/contracts";
+import { BETTER_AUTH_PACKAGE_V1 } from "@frockbot/app/auth/better-auth";
+import type { BetterAuthEnvironmentV1 } from "@frockbot/app/auth/better-auth";
+
+/**
+ * What a Worker must hand the Package this build deploys.
+ *
+ * One Package's settings, not both: the Worker's `env` declares every name
+ * either build reads, and the build that is not here reads none of it. Each
+ * chooser exports this name, so `index.ts` is the same file on both builds.
+ */
+export type AuthPackageEnvironmentV1 = BetterAuthEnvironmentV1;
+
+/** The sign-in Package this build deploys. */
+export const AUTH_PACKAGE_V1: AuthPackageBuildV1<AuthPackageEnvironmentV1> =
+  BETTER_AUTH_PACKAGE_V1;

package/src/avatar-state-cleanup.ts

@@ -0,0 +1,107 @@
+/**
+ * Disposable pre-user cleanup for the retired layered-sheep appearance.
+ *
+ * Directory registrations are retained so their conversations remain
+ * reachable. Only the incompatible appearance and receipts which fingerprinted
+ * it are replaced. Bot objects drop the old identity keys; the new identity is
+ * materialized from the cleaned registration on first use.
+ */
+
+const USER_RECEIPT = "maintenance:avatar-cast:2026-09-16-v2";
+const BOT_RECEIPT = "maintenance:avatar-cast:2026-09-16";
+const DIRECTORY_KEY = "flock:directory:v1";
+
+const pixel = { schemaVersion: 1, characterId: "pixel", primary: "#fc85ae" };
+
+function layeredAvatar(value: unknown): boolean {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const avatar = value as Record<string, unknown>;
+  return (
+    typeof avatar.background === "string" ||
+    typeof avatar.upper === "string" ||
+    typeof avatar.middle === "string" ||
+    typeof avatar.lower === "string"
+  );
+}
+
+export async function cleanUserAvatarTestState(
+  storage: DurableObjectStorage,
+): Promise<void> {
+  await storage.transaction(async (tx) => {
+    if (await tx.get(USER_RECEIPT)) return;
+    const stored = await tx.get<unknown>(DIRECTORY_KEY);
+    let replaced = 0;
+    if (
+      typeof stored === "object" &&
+      stored !== null &&
+      !Array.isArray(stored)
+    ) {
+      const directory = stored as Record<string, unknown>;
+      if (Array.isArray(directory.bots)) {
+        const bots = directory.bots.map((entry) => {
+          if (
+            typeof entry !== "object" ||
+            entry === null ||
+            Array.isArray(entry)
+          ) {
+            return entry;
+          }
+          const registration = entry as Record<string, unknown>;
+          const carriedSheep = Object.hasOwn(registration, "sheep");
+          if (!carriedSheep && !layeredAvatar(registration.avatar))
+            return entry;
+          replaced += 1;
+          const { sheep: _retired, ...current } = registration;
+          return {
+            ...current,
+            avatar: layeredAvatar(registration.avatar)
+              ? { ...pixel }
+              : (registration.avatar ?? { ...pixel }),
+          };
+        });
+        if (replaced > 0) await tx.put(DIRECTORY_KEY, { ...directory, bots });
+      }
+    }
+    let deletedReceipts = 0;
+    for (;;) {
+      const keys = [
+        ...(
+          await tx.list({ prefix: "flock:create-receipt:", limit: 128 })
+        ).keys(),
+      ];
+      if (!keys.length) break;
+      deletedReceipts += await tx.delete(keys);
+    }
+    await tx.put(USER_RECEIPT, {
+      schemaVersion: 1,
+      replaced,
+      deletedReceipts,
+      completedAt: new Date().toISOString(),
+    });
+  });
+}
+
+export async function cleanBotAvatarTestState(
+  storage: DurableObjectStorage,
+): Promise<void> {
+  await storage.transaction(async (tx) => {
+    if (await tx.get(BOT_RECEIPT)) return;
+    let deleted = (await tx.delete("flock:sheep:v1")) ? 1 : 0;
+    for (;;) {
+      const keys = [
+        ...(
+          await tx.list({ prefix: "flock:sheep-receipt:", limit: 128 })
+        ).keys(),
+      ];
+      if (!keys.length) break;
+      deleted += await tx.delete(keys);
+    }
+    await tx.put(BOT_RECEIPT, {
+      schemaVersion: 1,
+      deleted,
+      completedAt: new Date().toISOString(),
+    });
+  });
+}

package/src/billing-computer.ts

@@ -0,0 +1,267 @@
+import {
+  BillingError,
+  BILLING_PLAN,
+  type UsageAttributionV1,
+} from "@frockbot/app/billing/ledger";
+import {
+  COMPUTER_TARIFF,
+  computerChargeMicros,
+  computerCostMicros,
+} from "@frockbot/app/billing/computer";
+import {
+  decodeComputerHostHttpRequestV1,
+  encodeComputerHostRequestV1,
+  problem,
+  type ComputerHostOperationV1,
+  type ComputerHostRequestV1,
+} from "@frockbot/computer/host-protocol";
+import type { BillingAccountRpc } from "./billing.js";
+
+/**
+ * Fixed launch tariff for Computers, in micro-US-dollars per active hour.
+ *
+ * Fly exposes 8 vCPU, 16 GB RAM and 100 GB storage to one Computer. At the
+ * published rates that ceiling costs US$1.3283/hour while active. Two times
+ * the ceiling is US$2.6566; the public rate rounds up so an unmetered Computer
+ * cannot turn unusually heavy use into a loss.
+ */
+export const COMPUTER_ACTIVE_MICROS_PER_HOUR =
+  COMPUTER_TARIFF.activeMicrosPerHour;
+export const COMPUTER_RATE_DESCRIPTION = "Computer · US$2.75 per active hour";
+
+const SECOND_MS = 1_000;
+const VIEWER_OPEN_MS = COMPUTER_TARIFF.viewerOpenSeconds * SECOND_MS;
+const VIEWER_RENEW_MS = COMPUTER_TARIFF.viewerRenewSeconds * SECOND_MS;
+const DEFAULT_MAXIMUM_MS = 60_000;
+const OPEN_MAXIMUM_MS = 10 * 60_000;
+const SERVICE_MAXIMUM_MS = 120_000;
+const EXEC_SETTLEMENT_GRACE_MS = 6_000;
+/** A checkpoint or a restore, which the host bounds at four minutes. */
+const CHECKPOINT_MAXIMUM_MS = 5 * 60_000;
+/** A sign-in restore may start the browser before it writes. */
+const LOGINS_MAXIMUM_MS = 2 * 60_000;
+/** A replacement discards the machine and waits for its name to free. */
+const REPLACE_MAXIMUM_MS = 3 * 60_000;
+
+function maximumDuration(operation: ComputerHostOperationV1): number {
+  if (operation.kind === "exec")
+    return operation.timeoutMs + EXEC_SETTLEMENT_GRACE_MS;
+  if (operation.kind === "open") return OPEN_MAXIMUM_MS;
+  if (operation.kind === "service") return SERVICE_MAXIMUM_MS;
+  if (operation.kind === "checkpoint") return CHECKPOINT_MAXIMUM_MS;
+  if (operation.kind === "logins") return LOGINS_MAXIMUM_MS;
+  if (operation.kind === "replace") return REPLACE_MAXIMUM_MS;
+  if (operation.kind === "viewer")
+    return operation.action === "open"
+      ? VIEWER_OPEN_MS
+      : operation.action === "renew"
+        ? VIEWER_RENEW_MS
+        : 0;
+  return DEFAULT_MAXIMUM_MS;
+}
+
+function billedDuration(
+  operation: ComputerHostOperationV1,
+  elapsedMs: number,
+  granted = true,
+): number {
+  if (operation.kind === "viewer" && granted) {
+    if (operation.action === "open") return VIEWER_OPEN_MS;
+    if (operation.action === "renew") return VIEWER_RENEW_MS;
+  }
+  return Math.max(SECOND_MS, Math.ceil(elapsedMs / SECOND_MS) * SECOND_MS);
+}
+
+function cleanupOperation(operation: ComputerHostOperationV1): boolean {
+  return (
+    operation.kind === "cancel" ||
+    (operation.kind === "viewer" && operation.action === "revoke") ||
+    (operation.kind === "control" && operation.action === "release")
+  );
+}
+
+function revokeViewerRequest(
+  request: Request,
+  decoded: ComputerHostRequestV1,
+): Request | undefined {
+  if (
+    decoded.operation.kind !== "viewer" ||
+    decoded.operation.action !== "renew" ||
+    !decoded.operation.sessionId
+  )
+    return;
+  return new Request(request.url, {
+    method: request.method,
+    headers: request.headers,
+    body: JSON.stringify(
+      encodeComputerHostRequestV1({
+        ...decoded,
+        operation: {
+          kind: "viewer",
+          action: "revoke",
+          sessionId: decoded.operation.sessionId,
+        },
+      }),
+    ),
+  });
+}
+
+async function responseWithSettlement(
+  response: Response,
+  settle: () => Promise<void>,
+): Promise<Response> {
+  if (!response.body) {
+    await settle();
+    return response;
+  }
+  const reader = response.body.getReader();
+  let settled = false;
+  const once = async () => {
+    if (settled) return;
+    settled = true;
+    await settle();
+  };
+  return new Response(
+    new ReadableStream<Uint8Array>({
+      async pull(controller) {
+        try {
+          const next = await reader.read();
+          if (!next.done) {
+            controller.enqueue(next.value);
+            return;
+          }
+          await once();
+          controller.close();
+        } catch (error) {
+          await once().catch(() => undefined);
+          controller.error(error);
+        }
+      },
+      async cancel(reason) {
+        try {
+          await reader.cancel(reason);
+        } finally {
+          await once();
+        }
+      },
+    }),
+    {
+      status: response.status,
+      statusText: response.statusText,
+      headers: response.headers,
+    },
+  );
+}
+
+/**
+ * What a Computer charge is recorded against. Watching or taking control is
+ * the person at the Computer, whatever the Bot is doing meanwhile; anything
+ * else is the Turn the Bot is running, when it is running one.
+ */
+export type ComputerSpendV1 = (
+  botId: string,
+  personal: boolean,
+) => Promise<UsageAttributionV1 | undefined>;
+
+function personalOperation(operation: ComputerHostOperationV1): boolean {
+  return operation.kind === "viewer" || operation.kind === "control";
+}
+
+/** Authorize and settle fixed-rate Computer time at the existing host seam. */
+export function prepaidComputerHost(
+  host: Fetcher,
+  account: (userId: string) => BillingAccountRpc,
+  now: () => number = Date.now,
+  spend?: ComputerSpendV1,
+): Fetcher {
+  return new Proxy(host, {
+    get(target, property) {
+      if (property !== "fetch") {
+        const value = Reflect.get(target, property);
+        return typeof value === "function" ? value.bind(target) : value;
+      }
+      return async (request: Request): Promise<Response> => {
+        const decoded = await decodeComputerHostHttpRequestV1(
+          request.clone() as unknown as Parameters<
+            typeof decodeComputerHostHttpRequestV1
+          >[0],
+        );
+        if (!decoded.ok) return decoded.response;
+        const { operation, identity, tenant, effectId } = decoded.value;
+        if (cleanupOperation(operation)) return target.fetch(request);
+
+        const billing = account(identity.userId);
+        // Attribution never stops the Computer.
+        const attribution = await spend?.(
+          tenant.botId,
+          personalOperation(operation),
+        ).catch(() => undefined);
+        let reservation:
+          | {
+              status: "reserved" | "settled" | "released";
+              created: boolean;
+            }
+          | undefined;
+        try {
+          reservation = await billing.reserveUsage({
+            userId: identity.userId,
+            reservation: {
+              id: `computer:${effectId}`,
+              kind: "computer",
+              maximumMicros: computerChargeMicros(maximumDuration(operation)),
+              botId: tenant.botId,
+              description: COMPUTER_RATE_DESCRIPTION,
+              pricingVersion: BILLING_PLAN.pricingVersion,
+              unitRates: {
+                activeMicrosPerHour: COMPUTER_ACTIVE_MICROS_PER_HOUR,
+              },
+              ...(attribution ? { attribution } : {}),
+            },
+          });
+        } catch (error) {
+          const revoke = revokeViewerRequest(request, decoded.value);
+          if (revoke) await target.fetch(revoke).catch(() => undefined);
+          return problem(
+            error instanceof BillingError ? error.status : 402,
+            "not-authorized",
+            error instanceof Error
+              ? error.message
+              : "Open Billing to check your subscription and balance.",
+          );
+        }
+
+        const started = now();
+        const settle = async (granted = true) => {
+          if (!reservation?.created) return;
+          const durationMs = billedDuration(
+            operation,
+            now() - started,
+            granted,
+          );
+          const chargeMicros = computerChargeMicros(durationMs);
+          await billing.settleUsage({
+            userId: identity.userId,
+            settlement: {
+              id: `computer:${effectId}`,
+              costMicros: computerCostMicros(durationMs),
+              chargeMicros,
+              quantities: { activeSeconds: durationMs / SECOND_MS },
+            },
+          });
+        };
+
+        // A thrown service-binding failure does not say whether the host ran
+        // the effect. Keep that reservation for evidence-based reconciliation
+        // instead of inventing either a charge or a refund.
+        const response = await target.fetch(request);
+        const streaming =
+          operation.kind === "exec"
+            ? operation.stream
+            : operation.kind === "open" && operation.stream;
+        if (streaming) return await responseWithSettlement(response, settle);
+        await settle(response.ok);
+        return response;
+      };
+    },
+  });
+}

package/src/billing-readiness.ts

@@ -0,0 +1,21 @@
+/** Remove each blocker only with its implemented and verified replacement. */
+export const BILLING_LAUNCH_BLOCKERS: readonly string[] = [];
+
+export interface BillingSwitchEnv {
+  STRIPE_SECRET_KEY?: string;
+  BETTER_AUTH_URL?: string;
+}
+
+/**
+ * Billing is switched off until Stripe is configured. Without
+ * `STRIPE_SECRET_KEY` a deployment meters nothing and requires no
+ * subscription, so a release can ship the billing code while the account has
+ * no customers. A local origin stays off even with a key, so a copied
+ * `.dev.vars.example` cannot bill a developer.
+ */
+export function hostedBillingEnabledV1(env: BillingSwitchEnv): boolean {
+  if (!env.STRIPE_SECRET_KEY?.trim() || !env.BETTER_AUTH_URL) return false;
+  return !/^(localhost|127\.0\.0\.1|\[::1\])$/.test(
+    new URL(env.BETTER_AUTH_URL).hostname,
+  );
+}