@frockbot/cloudflare 0.0.0 → 0.7.291

package/src/account-admission.ts

@@ -0,0 +1,179 @@
+import { BRAND_V1 } from "#brand";
+import {
+  admissionRefusalCopyV1,
+  type AccountAccessV1,
+  type AccountAdmissionDecisionV1,
+  type AdmissionIdentityV1,
+  type AdmissionModeV1,
+  type AdmissionRefusalReasonV1,
+  type EmailInvitationV1,
+  type IdentityCreationRequestV1,
+} from "@frockbot/app/admin/shared";
+
+export interface AdmissionEvaluationV1 {
+  decision: AccountAdmissionDecisionV1;
+  /** Whether this admission moves the account to `active`. */
+  activate: boolean;
+  /** Whether the email invitation that justified it is spent. */
+  redeemInvitation: boolean;
+}
+
+function refused(reason: AdmissionRefusalReasonV1): AdmissionEvaluationV1 {
+  return {
+    decision: { schemaVersion: 1, admitted: false, reason },
+    activate: false,
+    redeemInvitation: false,
+  };
+}
+
+/**
+ * The beta-access rule, with no I/O so every row of it is testable.
+ *
+ * `invitation` is the invitation for this identity's *verified* email, or
+ * null; the caller never passes one for an unverified address. The admission
+ * contract is documented in `docs/beta-access.md`.
+ */
+export function evaluateAdmissionV1(input: {
+  mode: AdmissionModeV1;
+  identity: AdmissionIdentityV1;
+  access: AccountAccessV1 | null;
+  invitation: EmailInvitationV1 | null;
+}): AdmissionEvaluationV1 {
+  const { mode, identity, access, invitation } = input;
+  if (identity.isAdmin) {
+    return {
+      decision: { schemaVersion: 1, admitted: true, basis: "admin" },
+      activate: false,
+      redeemInvitation: false,
+    };
+  }
+  if (access) {
+    switch (access.state) {
+      case "active":
+        return {
+          decision: { schemaVersion: 1, admitted: true, basis: "active" },
+          activate: false,
+          redeemInvitation: false,
+        };
+      case "paused":
+        return refused("account-paused");
+      case "ended":
+        return refused("account-ended");
+      case "blocked":
+        return refused("account-blocked");
+      case "invited":
+        // Closing admission is exactly "admit nobody new", and an invited
+        // account has not been admitted yet.
+        if (mode === "closed") return refused("admission-closed");
+        return {
+          decision: { schemaVersion: 1, admitted: true, basis: "invitation" },
+          activate: true,
+          redeemInvitation: invitation !== null,
+        };
+    }
+  }
+  if (invitation) {
+    if (mode === "closed") return refused("admission-closed");
+    return {
+      decision: { schemaVersion: 1, admitted: true, basis: "invitation" },
+      activate: true,
+      redeemInvitation: true,
+    };
+  }
+  if (mode === "open") {
+    return {
+      decision: { schemaVersion: 1, admitted: true, basis: "open" },
+      activate: true,
+      redeemInvitation: false,
+    };
+  }
+  return refused(
+    mode === "invite-only" ? "invitation-required" : "admission-closed",
+  );
+}
+
+/**
+ * Whether the identity provider may write a brand-new identity. It runs
+ * before there is a User id, so only the mode, the admin allowlist and a
+ * verified invitation can answer it; an identity that is written still has to
+ * pass `evaluateAdmissionV1` on every request.
+ */
+export function identityMayBeCreatedV1(
+  mode: AdmissionModeV1,
+  request: IdentityCreationRequestV1,
+  invitation: EmailInvitationV1 | null,
+): boolean {
+  if (request.isAdmin || mode === "open") return true;
+  return mode === "invite-only" && request.emailVerified && invitation !== null;
+}
+
+export const ACCOUNT_ADMISSION_UNAVAILABLE_MESSAGE = `${BRAND_V1.productName} couldn't check this account's access. Try again in a moment.`;
+
+const NO_STORE = { "cache-control": "no-store" } as const;
+
+function escapeHtml(value: string): string {
+  return value
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}
+
+/**
+ * A refusal a client can act on: the copy to show and the reason it is true.
+ * Only the browser's document request gets a page; everything else is JSON.
+ */
+export function admissionRefusedResponse(
+  reason: AdmissionRefusalReasonV1,
+  page: boolean,
+): Response {
+  const copy = admissionRefusalCopyV1(BRAND_V1.productName)[reason];
+  if (!page) {
+    return Response.json(
+      { error: copy.title, code: "account-access-refused", reason },
+      { status: 403, headers: NO_STORE },
+    );
+  }
+  return new Response(
+    `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>${escapeHtml(BRAND_V1.productName)}</title>
+</head>
+<body>
+  <main data-reason="${escapeHtml(reason)}">
+    <p>${escapeHtml(BRAND_V1.productName)}</p>
+    <h1>${escapeHtml(copy.title)}</h1>
+    <p>${escapeHtml(copy.detail)}</p>
+    <a href="/sign-out">Sign out</a>
+  </main>
+</body>
+</html>`,
+    {
+      status: 403,
+      headers: {
+        ...NO_STORE,
+        "content-type": "text/html; charset=utf-8",
+        "content-security-policy":
+          "default-src 'none'; base-uri 'none'; frame-ancestors 'none'",
+        "x-content-type-options": "nosniff",
+      },
+    },
+  );
+}
+
+/**
+ * The authority could not answer. Never a 401: the session is fine, and a
+ * client that signed out on this would throw away a valid sign-in.
+ */
+export function admissionUnavailableResponse(): Response {
+  return Response.json(
+    {
+      error: ACCOUNT_ADMISSION_UNAVAILABLE_MESSAGE,
+      code: "account-access-unavailable",
+    },
+    { status: 503, headers: { ...NO_STORE, "retry-after": "5" } },
+  );
+}

package/src/account-deletion.ts

@@ -0,0 +1,274 @@
+/**
+ * The steps of deleting an account, over this Worker's bindings.
+ *
+ * The saga itself — its order, its record, its retries — is
+ * `@frockbot/app/account/deletion`. This file is what each step does here:
+ * which object, bucket, index or provider it reaches and how it knows it is
+ * done. What only the User's own Durable Object can do — its Bots, its Group
+ * Chats, its ledger and its Memory tables — comes in as seams, so every step
+ * is testable without one.
+ *
+ * Each step only deletes, and each is safe to repeat: a provider answering
+ * "already gone" is a deletion, never an error.
+ */
+import type {
+  AccountDeletionRecordV1,
+  AccountDeletionStepOutcomeV1,
+  AccountDeletionStepV1,
+} from "@frockbot/app/account/deletion";
+import {
+  StripeClient,
+  deleteAccountCustomersV1,
+} from "@frockbot/app/billing/stripe";
+import { ComposioClient } from "@frockbot/app/connect/composio";
+import type { MemoryVectorIndex } from "@frockbot/app/memory/types";
+import { uploadUserPrefixV1 } from "@frockbot/app/uploads/shared";
+import {
+  WORKSPACE_OBJECT_PREFIX,
+  workspaceObjectPrefixV1,
+} from "@frockbot/core/workspace-store";
+import { stripeConfig, type BillingEnv } from "./billing.js";
+import {
+  computerHostBindingV1,
+  createComputerHostV1,
+  type ComputerHostEnvV1,
+} from "./computer-host.js";
+import { DEPLOYMENT_POLICY_SINGLETON_NAME } from "./deployment-policy.js";
+
+export interface AccountDeletionEnvV1 extends BillingEnv, ComputerHostEnvV1 {
+  DEPLOYMENT_POLICY?: DurableObjectNamespace;
+  VOICE_ASSISTANTS?: DurableObjectNamespace;
+  COMPOSIO_API_KEY?: string;
+  MEMORY_FILES?: R2Bucket;
+  MEMORY_INDEX?: MemoryVectorIndex;
+}
+
+/** What only the User Durable Object can do, handed to the steps. */
+export interface AccountDeletionUserSeamsV1 {
+  /**
+   * Deletes every Group Chat through its own delete command: the first pass
+   * names them in the cursor, the next deletes those it names.
+   */
+  deleteGroupChats(
+    cursor: string | undefined,
+  ): Promise<AccountDeletionStepOutcomeV1>;
+  /** Deletes every Bot through the Bot delete saga. */
+  deleteBots(): Promise<AccountDeletionStepOutcomeV1>;
+  /** The payment customer the ledger recorded, if it recorded one. */
+  recordedPaymentCustomer(): string | undefined;
+  /** User and Group Chat Memory vector ids, a page at a time. */
+  vectorIdsAfter(cursor: string | undefined, limit: number): string[];
+  /** Forgets the sign-in identity, its sessions and linked accounts. */
+  deleteIdentity(): Promise<void>;
+  /** Erases the voice session object. */
+  eraseVoice(): Promise<void>;
+  /**
+   * Revokes the grants the User's MCP servers issued, forgetting each once
+   * its server has answered — or, with `giveUp`, whether it did or not.
+   * Answers how many servers did not answer.
+   */
+  revokeMcpGrants(giveUp: boolean): Promise<number>;
+}
+
+const COMPLETE: AccountDeletionStepOutcomeV1 = { status: "complete" };
+/** One listing page, and one bulk delete, of object storage or the index. */
+const PAGE = 1_000;
+/**
+ * Passes an MCP server that does not answer its revocation is given — about
+ * half a minute of the saga's backoff — before its grant is forgotten
+ * unrevoked, so a server that is gone never holds a deletion up.
+ */
+export const MCP_REVOCATION_ATTEMPTS_V1 = 5;
+
+interface DeploymentPolicyDeletionRpc {
+  closeAccountForDeletion(input: unknown): Promise<unknown>;
+  forgetAccount(input: unknown): Promise<unknown>;
+}
+
+function deploymentPolicy(
+  env: AccountDeletionEnvV1,
+): DeploymentPolicyDeletionRpc | undefined {
+  const namespace = env.DEPLOYMENT_POLICY;
+  // SAFETY: the binding names DeploymentPolicy; these are its deletion doors.
+  return namespace
+    ? (namespace.get(
+        namespace.idFromName(DEPLOYMENT_POLICY_SINGLETON_NAME),
+      ) as unknown as DeploymentPolicyDeletionRpc)
+    : undefined;
+}
+
+/**
+ * Every object-storage prefix that holds one User's files: the User's own
+ * Skills and Memory, every Plugin-declared root, and every Bot root and Bot's
+ * uploads — which the Bot delete saga already removed, and which are swept
+ * again in case a Bot was lost before it could be.
+ *
+ * Content-addressed stores — Skill bodies, Plugin artifacts and exported
+ * templates — are not here. One address can hold the same bytes for two
+ * accounts, so deleting it could break another account's Skill or Plugin;
+ * once this account is gone nothing names them.
+ */
+export function accountObjectPrefixesV1(userId: string): string[] {
+  const user = encodeURIComponent(userId);
+  return [
+    workspaceObjectPrefixV1({ kind: "user-instructions", userId }),
+    workspaceObjectPrefixV1({ kind: "user-memory", userId }),
+    `${WORKSPACE_OBJECT_PREFIX}/package-declared:${user}:`,
+    `${WORKSPACE_OBJECT_PREFIX}/bot-instructions:${user}:`,
+    `${WORKSPACE_OBJECT_PREFIX}/bot-memory:${user}:`,
+    uploadUserPrefixV1(userId),
+  ];
+}
+
+/** One page of every prefix; done once a pass finds nothing left. */
+async function deleteAccountObjects(
+  bucket: R2Bucket,
+  userId: string,
+): Promise<AccountDeletionStepOutcomeV1> {
+  let remaining = false;
+  for (const prefix of accountObjectPrefixesV1(userId)) {
+    const page = await bucket.list({ prefix, limit: PAGE });
+    const keys = page.objects.map((object) => object.key);
+    if (keys.length > 0) await bucket.delete(keys);
+    if (page.truncated) remaining = true;
+  }
+  return remaining ? { status: "pending" } : COMPLETE;
+}
+
+/**
+ * The provider's accounts and triggers for this User, found by asking the
+ * provider rather than by what this application recorded: a sign-in started
+ * and never finished leaves an account no Connection names. Triggers go
+ * first, then the accounts, each revoked upstream.
+ *
+ * A pass that deleted anything is followed by one more that lists again and
+ * deletes whatever it still finds, and the step then ends. A provider that
+ * keeps listing an account it has accepted the deletion of is keeping its own
+ * record, and a third pass would only delete it a third time.
+ */
+async function deleteConnectedApps(
+  client: ComposioClient,
+  userId: string,
+  record: AccountDeletionRecordV1,
+): Promise<AccountDeletionStepOutcomeV1> {
+  const triggers = await client.listTriggerInstanceIds(userId);
+  for (const id of triggers) await client.deleteTriggerInstance(id);
+  const accounts = await client.listConnectedAccountIds(userId);
+  for (const id of accounts) await client.deleteConnectedAccount(id);
+  if (triggers.length + accounts.length === 0 || record.cursor === "verify")
+    return COMPLETE;
+  return { status: "pending", cursor: "verify" };
+}
+
+/**
+ * The payment customer, which ends the subscription with it. With no
+ * payments configured there is nothing to reach — unless the ledger recorded
+ * a customer, which means payments were on once and a live subscription may
+ * still be charging. That is refused, and retried, until someone restores
+ * the configuration: finishing the deletion around it would leave the person
+ * paying for an account that no longer exists.
+ */
+async function deletePayments(
+  env: AccountDeletionEnvV1,
+  userId: string,
+  recorded: string | undefined,
+): Promise<AccountDeletionStepOutcomeV1> {
+  let config: ReturnType<typeof stripeConfig>;
+  try {
+    config = stripeConfig(env);
+  } catch (error) {
+    if (recorded === undefined) return COMPLETE;
+    throw new Error(
+      `payments are not configured, so customer ${recorded} cannot be deleted`,
+      { cause: error },
+    );
+  }
+  await deleteAccountCustomersV1(new StripeClient(config), userId, recorded);
+  return COMPLETE;
+}
+
+/** One page of Memory vectors, deleted from the index by id. */
+async function deleteMemoryVectors(
+  index: MemoryVectorIndex,
+  seams: AccountDeletionUserSeamsV1,
+  record: AccountDeletionRecordV1,
+): Promise<AccountDeletionStepOutcomeV1> {
+  const page = seams.vectorIdsAfter(record.cursor, PAGE);
+  if (page.length === 0) return COMPLETE;
+  await index.deleteByIds(page);
+  return { status: "pending", cursor: page.at(-1)! };
+}
+
+/** Runs one step of one account's deletion. */
+export async function runAccountDeletionStepV1(
+  env: AccountDeletionEnvV1,
+  seams: AccountDeletionUserSeamsV1,
+  step: AccountDeletionStepV1,
+  record: AccountDeletionRecordV1,
+): Promise<AccountDeletionStepOutcomeV1> {
+  const { userId } = record;
+  switch (step) {
+    case "access":
+      await deploymentPolicy(env)?.closeAccountForDeletion({
+        schemaVersion: 1,
+        userId,
+      });
+      return COMPLETE;
+    case "voice":
+      if (env.VOICE_ASSISTANTS) await seams.eraseVoice();
+      return COMPLETE;
+    case "groups":
+      return seams.deleteGroupChats(record.cursor);
+    case "bots":
+      return seams.deleteBots();
+    case "computer": {
+      const binding = computerHostBindingV1(env);
+      if (!binding) return COMPLETE;
+      const host = createComputerHostV1(binding);
+      if (!host.teardown)
+        throw new Error("this Computer host cannot tear a Computer down");
+      await host.teardown({ userId });
+      return COMPLETE;
+    }
+    case "connected-apps":
+      return env.COMPOSIO_API_KEY
+        ? deleteConnectedApps(
+            new ComposioClient({ apiKey: env.COMPOSIO_API_KEY }),
+            userId,
+            record,
+          )
+        : COMPLETE;
+    case "mcp-servers": {
+      // A failure is what backs the saga off between passes; the record's
+      // count of them is what bounds how long a silent server is waited on.
+      const owed = await seams.revokeMcpGrants(
+        record.attempts + 1 >= MCP_REVOCATION_ATTEMPTS_V1,
+      );
+      if (owed > 0)
+        throw new Error(
+          `${owed} MCP server${owed === 1 ? "" : "s"} did not answer the revocation`,
+        );
+      return COMPLETE;
+    }
+    case "payments":
+      return deletePayments(env, userId, seams.recordedPaymentCustomer());
+    case "files":
+      return env.MEMORY_FILES
+        ? deleteAccountObjects(env.MEMORY_FILES, userId)
+        : COMPLETE;
+    case "memory-vectors":
+      return env.MEMORY_INDEX
+        ? deleteMemoryVectors(env.MEMORY_INDEX, seams, record)
+        : COMPLETE;
+    case "identity":
+      await seams.deleteIdentity();
+      return COMPLETE;
+    case "admission":
+      await deploymentPolicy(env)?.forgetAccount({
+        schemaVersion: 1,
+        userId,
+        ...(record.email === undefined ? {} : { email: record.email }),
+      });
+      return COMPLETE;
+  }
+}

package/src/admin-entrypoint.ts

@@ -0,0 +1,194 @@
+import { WorkerEntrypoint } from "cloudflare:workers";
+import {
+  createAdminOperationsV1,
+  type AdminOperationsHostV1,
+  type AdminOperationsV1,
+} from "@frockbot/app/admin/operations";
+import {
+  decodeAdminUserBillingV1,
+  decodeUserFeaturesV1,
+  type AccountAccessV1,
+  type AccountAccessViewV1,
+  type AdminUserBillingV1,
+  type AdminUserListViewV1,
+  type AdminWriteResultV1,
+  type DeploymentPolicyV1,
+  type EmailInvitationV1,
+  type UserFeaturesV1,
+} from "@frockbot/app/admin/shared";
+import type {
+  HostedModelRatesV1,
+  HostedModelRatesViewV1,
+} from "@frockbot/app/billing/rates";
+import { createDeploymentPolicyAdminHost } from "./deployment-policy-admin-host.js";
+import { DEPLOYMENT_POLICY_SINGLETON_NAME } from "./deployment-policy.js";
+import { rpcJsonSnapshotV1 } from "./durable-rpc.js";
+
+/**
+ * What administration needs from the Worker's environment: the access
+ * authority, the identity store and one account's User Durable Object.
+ *
+ * Deliberately narrower than the app's `Env`. Administration reaches three
+ * bindings, and naming them here is what says so.
+ */
+export interface AdminEntrypointEnvV1 {
+  AUTH_DB: D1Database;
+  USER_CONFIGURATIONS: DurableObjectNamespace;
+  DEPLOYMENT_POLICY: DurableObjectNamespace;
+}
+
+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>;
+}
+
+interface UserAccountRpc {
+  readFeatures(input: unknown): Promise<unknown>;
+  setFeatures(input: unknown): Promise<unknown>;
+  readBillingBalance(input: unknown): Promise<unknown>;
+  grantComplimentaryCredit(input: unknown): Promise<unknown>;
+}
+
+function userAccountStub(
+  env: AdminEntrypointEnvV1,
+  userId: string,
+): UserAccountRpc {
+  const id = env.USER_CONFIGURATIONS.idFromName(userId);
+  // SAFETY: Wrangler binds USER_CONFIGURATIONS to UserConfiguration; workers-types cannot infer its account features and billing RPC surface.
+  return env.USER_CONFIGURATIONS.get(id) as unknown as UserAccountRpc;
+}
+
+function deploymentPolicyStub(
+  env: AdminEntrypointEnvV1,
+): DeploymentPolicyAdminRpc {
+  // SAFETY: Wrangler binds DEPLOYMENT_POLICY to DeploymentPolicy; workers-types cannot infer its authority RPC surface.
+  return env.DEPLOYMENT_POLICY.getByName(
+    DEPLOYMENT_POLICY_SINGLETON_NAME,
+  ) as unknown as DeploymentPolicyAdminRpc;
+}
+
+export function createAdminOperationsHostV1(
+  env: AdminEntrypointEnvV1,
+): AdminOperationsHostV1 {
+  return {
+    ...createDeploymentPolicyAdminHost(() => deploymentPolicyStub(env)),
+    listUsers: async () => {
+      const result = await env.AUTH_DB.prepare(
+        'select "id", "email", "name" from "user" order by "createdAt" desc limit 200',
+      ).all<{ id: string; email: string; name: string }>();
+      return (result.results ?? []).map((user) => ({
+        userId: user.id,
+        email: user.email,
+        name: user.name,
+      }));
+    },
+    readUserFeatures: async (userId) =>
+      decodeUserFeaturesV1(
+        rpcJsonSnapshotV1(
+          await userAccountStub(env, userId).readFeatures({
+            schemaVersion: 1,
+            userId,
+          }),
+        ),
+      ),
+    setUserFeatures: async (userId, command, updatedBy) =>
+      decodeUserFeaturesV1(
+        rpcJsonSnapshotV1(
+          await userAccountStub(env, userId).setFeatures({
+            schemaVersion: 1,
+            userId,
+            command,
+            updatedBy,
+          }),
+        ),
+      ),
+    readUserBilling: async (userId) =>
+      decodeAdminUserBillingV1(
+        rpcJsonSnapshotV1(
+          await userAccountStub(env, userId).readBillingBalance({ userId }),
+        ),
+      ),
+    grantUserCredit: async (userId, command, grantedBy) =>
+      decodeAdminUserBillingV1(
+        rpcJsonSnapshotV1(
+          await userAccountStub(env, userId).grantComplimentaryCredit({
+            userId,
+            command: {
+              id: command.id,
+              micros: command.cents * 10_000,
+              grantedBy,
+              reason: command.reason,
+            },
+          }),
+        ),
+      ),
+  };
+}
+
+/**
+ * Administration, reachable only over a service binding.
+ *
+ * No HTTP route reaches this class: the admin portal
+ * (`apps/admin-portal`) binds it as `APP` and is the one caller, so the
+ * authority that decides who administers the deployment is Cloudflare Access
+ * plus the admin emails list, checked there, and never a session in this
+ * Worker (ADR 0028). Every method decodes its input the way the Durable
+ * Objects behind it do, and every compare-and-swap answers `applied` or
+ * `conflict` rather than throwing, because a conflict is an answer.
+ */
+export class AdminEntrypoint extends WorkerEntrypoint<AdminEntrypointEnvV1> {
+  private get operations(): AdminOperationsV1 {
+    return createAdminOperationsV1(createAdminOperationsHostV1(this.env));
+  }
+
+  readPolicy(): Promise<DeploymentPolicyV1> {
+    return this.operations.readPolicy();
+  }
+
+  setAdmissionMode(
+    input: unknown,
+  ): Promise<AdminWriteResultV1<DeploymentPolicyV1>> {
+    return this.operations.setAdmissionMode(input);
+  }
+
+  listAccounts(): Promise<AdminUserListViewV1> {
+    return this.operations.listAccounts();
+  }
+
+  readAccountAccess(input: unknown): Promise<AccountAccessViewV1> {
+    return this.operations.readAccountAccess(input);
+  }
+
+  setAccountAccess(
+    input: unknown,
+  ): Promise<AdminWriteResultV1<AccountAccessV1>> {
+    return this.operations.setAccountAccess(input);
+  }
+
+  inviteEmail(input: unknown): Promise<EmailInvitationV1> {
+    return this.operations.inviteEmail(input);
+  }
+
+  setAccountFeatures(input: unknown): Promise<UserFeaturesV1> {
+    return this.operations.setAccountFeatures(input);
+  }
+
+  grantCredit(input: unknown): Promise<AdminUserBillingV1> {
+    return this.operations.grantCredit(input);
+  }
+
+  readModelRates(): Promise<HostedModelRatesViewV1> {
+    return this.operations.readModelRates();
+  }
+
+  saveModelRates(
+    input: unknown,
+  ): Promise<AdminWriteResultV1<HostedModelRatesV1>> {
+    return this.operations.saveModelRates(input);
+  }
+}

package/src/admin-identities.ts

@@ -0,0 +1,26 @@
+import { adminEmailsV1 } from "@frockbot/app/admin/shared";
+
+export { adminEmailsV1 };
+
+/** The one identity a development stack signs in as; an admin there. */
+export const DEVELOPMENT_USER_ID = "development";
+
+export interface GatewayIdentityV1 {
+  id: string;
+  email?: string;
+  mode: "better-auth" | "development";
+}
+
+export function isDeploymentAdminV1(
+  identity: GatewayIdentityV1,
+  configuredEmails: string | undefined,
+): boolean {
+  if (identity.mode === "development" && identity.id === DEVELOPMENT_USER_ID) {
+    return true;
+  }
+  const emails = adminEmailsV1(configuredEmails);
+  if (identity.email && emails.has(identity.email.trim().toLowerCase())) {
+    return true;
+  }
+  return identity.mode === "development" && emails.size === 0;
+}