cartethyia 2.7.2 → 2.7.4

package/src/console/api-keys/routes.ts

@@ -2,7 +2,7 @@
 //
 // Owns validation, CRUD operations, and route wiring through the ApiKeyStore.
 
-import { Elysia, t } from "elysia";
+import { Elysia, t, type AnyElysia } from "elysia";
 import { randomBytes, randomUUID } from "node:crypto";
 import { decryptCredentialToString, encryptCredential } from "../../security/crypto";
 import { invalidateApiKeyCache } from "../../security/api-key-auth";
@@ -12,9 +12,16 @@ import type { AccessDecision } from "../../security/access-control";
 import { ConsoleDomainError, errorResponse, requireTenantScope } from "../shared/errors";
 import { literalUnion } from "../shared/elysia-schema";
 import { API_KEY_MODES, API_KEY_MODEL_ACCESS_MODES, type ShareLinkKind } from "../../persistence/schema";
-import type { ApiKeyConfig, ApiKeyResponse, UpdateApiKeyResponse } from "./contracts";
-import type { ApiKeyPatch, ApiKeyRecord } from "../../persistence/stores/api-key-store";
+import type { ApiKeyConfig, ApiKeyResponse, BanApiKeyRequest, UpdateApiKeyResponse } from "./contracts";
+import type {
+  ApiKeyPatch,
+  ApiKeyRecord,
+  SharedChildSortColumn,
+  SharedChildrenPageOptions,
+} from "../../persistence/stores/api-key-store";
 import {
+  BAN_DURATION_CHOICES,
+  DEFAULT_BAN_MINUTES,
   generateApiKeySecret,
   isDefaultGatewayApiKey,
   parseSharePopupImage,
@@ -34,6 +41,39 @@ import {
 import type { SharedKeyActivityDetail, SharedKeySummary } from "../share/share-usage";
 import { popupImageBytes } from "./share-popup-image";
 
+const SHARED_CHILD_SORT_COLUMNS = new Set<SharedChildSortColumn>([
+  "createdAt",
+  "label",
+  "keyPrefix",
+  "issuedClientIp",
+  "revokedAt",
+  "enabled",
+]);
+
+/** Parses and bounds the paginated share-child list query. */
+function parseSharedChildrenQuery(query: URLSearchParams): SharedChildrenPageOptions {
+  const limitRaw = query.get("limit");
+  const offsetRaw = query.get("offset");
+  const sortRaw = query.get("sort");
+  const orderRaw = query.get("order");
+  const statusRaw = query.get("status");
+  const limit = limitRaw === null ? 50 : Number(limitRaw);
+  const offset = offsetRaw === null ? 0 : Number(offsetRaw);
+  if (!Number.isInteger(limit) || limit < 1 || limit > 500) {
+    throw new ConsoleDomainError("invalid_request", 400, "limit must be an integer between 1 and 500");
+  }
+  if (!Number.isInteger(offset) || offset < 0) {
+    throw new ConsoleDomainError("invalid_request", 400, "offset must be a non-negative integer");
+  }
+  const sortBy = (sortRaw ?? "createdAt") as SharedChildSortColumn;
+  if (!SHARED_CHILD_SORT_COLUMNS.has(sortBy)) {
+    throw new ConsoleDomainError("invalid_request", 400, `unsupported sort column: ${String(sortBy)}`);
+  }
+  const order = orderRaw === "asc" ? "asc" : "desc";
+  const status = statusRaw === "active" || statusRaw === "revoked" ? statusRaw : "all";
+  return { limit, offset, sortBy, order, status };
+}
+
 export function createApiKeyOperations(config: ApiKeyConfig) {
   const operations = {
     async listKeys(access: AccessDecision | undefined): Promise<ApiKeyResponse[]> {
@@ -44,18 +84,19 @@ export function createApiKeyOperations(config: ApiKeyConfig) {
         );
         // A share template's own counter never moves for child traffic, so
         // reporting it raw would show a template as untouched while the gateway
-        // is refusing its recipients on the parent budget. Report the figure the
-        // gateway actually enforces: the template plus every recipient it has
-        // issued, revoked ones included (their spend is already spent).
-        const sumChildren = config.store.sumChildrenConsumed?.bind(config.store);
+        // is refusing its recipients on the parent budget. Report the figure
+        // the gateway actually enforces: the template's counter plus every
+        // telemetry total the family ever recorded — revoked/deleted children
+        // included (their spend is already spent), so the number survives
+        // cleanup and matches the share page.
         return Promise.all(
           topLevel.map(async (record) => {
             const response = sanitizeApiKeyResponse(record);
-            if (record.keyMode !== "share" || !sumChildren) return response;
-            const children = await sumChildren(record.id).catch(() => 0);
-            return children > 0
-              ? { ...response, tokensConsumed: response.tokensConsumed + children }
-              : response;
+            if (record.keyMode !== "share") return response;
+            const family = await config.store
+              .sumFamilyTelemetryConsumed(authorized.tenantId, record.id)
+              .catch(() => 0);
+            return { ...response, tokensConsumed: response.tokensConsumed + family };
           }),
         );
       },
@@ -146,6 +187,7 @@ export function createApiKeyOperations(config: ApiKeyConfig) {
         ...(request.monthlyTokenLimit == null ? {} : { monthlyTokenLimit: request.monthlyTokenLimit }),
         ...(request.lifetimeTokenBudget == null ? {} : { lifetimeTokenBudget: request.lifetimeTokenBudget }),
         ...(request.maxConcurrentRequests == null ? {} : { maxConcurrentRequests: request.maxConcurrentRequests }),
+        ...(request.maxChildren == null ? {} : { maxChildren: request.maxChildren }),
         ...(request.modelPrefix === undefined ? {} : { modelPrefix: request.modelPrefix }),
         modelAccessMode: request.modelAccessMode ?? "whitelist",
         ...(request.modelList === undefined ? {} : { modelList: request.modelList }),
@@ -280,6 +322,7 @@ export function createApiKeyOperations(config: ApiKeyConfig) {
         ...(patchRequest.monthlyTokenLimit === undefined ? {} : { monthlyTokenLimit: patchRequest.monthlyTokenLimit }),
         ...(patchRequest.lifetimeTokenBudget === undefined ? {} : { lifetimeTokenBudget: patchRequest.lifetimeTokenBudget }),
         ...(patchRequest.maxConcurrentRequests === undefined ? {} : { maxConcurrentRequests: patchRequest.maxConcurrentRequests }),
+        ...(patchRequest.maxChildren === undefined ? {} : { maxChildren: patchRequest.maxChildren }),
         ...(patchRequest.modelPrefix === undefined ? {} : { modelPrefix: patchRequest.modelPrefix }),
         ...(patchRequest.modelAccessMode === undefined ? {} : { modelAccessMode: patchRequest.modelAccessMode }),
         ...(patchRequest.modelList === undefined ? {} : { modelList: patchRequest.modelList }),
@@ -376,7 +419,7 @@ export function createApiKeyOperations(config: ApiKeyConfig) {
       });
       return { ...sanitizeApiKeyResponse(updated), ...(secret === undefined ? {} : { secret }) };
     },
-    async revokeKey(access: AccessDecision | undefined, keyId: string): Promise<{ success: true }> {
+    async deleteKey(access: AccessDecision | undefined, keyId: string): Promise<{ success: true }> {
       const authorized = requireTenantScope(access, "dashboard:write");
       const target = await config.store.get(authorized.tenantId, keyId);
       if (!target)
@@ -401,7 +444,7 @@ export function createApiKeyOperations(config: ApiKeyConfig) {
       ]);
       await config.auditSink?.record({
         access: authorized,
-        action: "api_key.revoked",
+        action: "api_key.deleted",
         target: keyId,
       });
       return { success: true };
@@ -643,7 +686,14 @@ export function createApiKeyOperations(config: ApiKeyConfig) {
     async listSharedKeys(
       access: AccessDecision | undefined,
       parentKeyId: string,
-    ): Promise<readonly SharedKeySummary[]> {
+      query: URLSearchParams,
+    ): Promise<{
+      rows: readonly SharedKeySummary[];
+      total: number;
+      active: number;
+      revoked: number;
+      consumed: number;
+    }> {
       const authorized = requireTenantScope(access, "dashboard:read");
       const activity = config.shareActivity;
       if (!activity)
@@ -652,8 +702,14 @@ export function createApiKeyOperations(config: ApiKeyConfig) {
       if (!parent || parent.revokedAt !== undefined ||
           parent.keyMode !== "share" || parent.parentKeyId !== undefined)
         throw new ConsoleDomainError("key_not_found", 404, "Share template not found");
-      const children = await config.store.listChildren(authorized.tenantId, parentKeyId);
-      return activity.getSharedKeySummaries(authorized.tenantId, children);
+      const options = parseSharedChildrenQuery(query);
+      const page = await config.store.listChildrenPage(authorized.tenantId, parentKeyId, options);
+      const rows = await activity.getSharedKeySummaries(
+        authorized.tenantId,
+        page.rows,
+        parentKeyId,
+      );
+      return { rows, total: page.total, active: page.active, revoked: page.revoked, consumed: page.consumed };
     },
     async getSharedKeyActivity(
       access: AccessDecision | undefined,
@@ -668,11 +724,37 @@ export function createApiKeyOperations(config: ApiKeyConfig) {
       if (!parent || parent.revokedAt !== undefined ||
           parent.keyMode !== "share" || parent.parentKeyId !== undefined)
         throw new ConsoleDomainError("key_not_found", 404, "Share template not found");
-      const children = await config.store.listChildren(authorized.tenantId, parentKeyId);
-      if (!children.some((child) => child.id === childKeyId))
+      // Membership is one indexed row read, not a scan of the whole family.
+      const child = await config.store.get(authorized.tenantId, childKeyId);
+      if (!child || child.parentKeyId !== parentKeyId)
         throw new ConsoleDomainError("key_not_found", 404, "Shared API key not found");
       return activity.getSharedKeyDetail(authorized.tenantId, childKeyId);
     },
+    async revokeSharedScope(
+      access: AccessDecision | undefined,
+      parentKeyId: string,
+      scope: "active" | "unused",
+    ): Promise<{ success: true; deleted: number }> {
+      const authorized = requireTenantScope(access, "dashboard:write");
+      const parent = await config.store.get(authorized.tenantId, parentKeyId);
+      if (!parent || parent.keyMode !== "share" || parent.parentKeyId !== undefined)
+        throw new ConsoleDomainError("key_not_found", 404, "Share template not found");
+      const deleted = await config.store.revokeChildrenByScope(
+        authorized.tenantId,
+        parentKeyId,
+        scope,
+      );
+      // Raw batched deletes bypass the per-key purge path; drop the whole auth
+      // cache so no resolved identity survives for a removed recipient.
+      invalidateApiKeyCache();
+      await config.auditSink?.record({
+        access: authorized,
+        action: "api_key.share_revoked_scope",
+        target: parentKeyId,
+        detail: { scope, deleted },
+      });
+      return { success: true, deleted };
+    },
     async revokeShare(
       access: AccessDecision | undefined,
       keyId: string,
@@ -695,6 +777,69 @@ export function createApiKeyOperations(config: ApiKeyConfig) {
       });
       return { success: true };
     },
+    async banKey(
+      access: AccessDecision | undefined,
+      keyId: string,
+      request: BanApiKeyRequest,
+    ): Promise<ApiKeyResponse> {
+      const authorized = requireTenantScope(access, "dashboard:write");
+      const reason = request.reason.trim();
+      if (reason.length === 0)
+        throw new ConsoleDomainError("invalid_request", 400, "reason is required");
+      // Parse the duration choice. `null` is permanent; absent defaults to one
+      // hour. Anything not on the offered list is rejected rather than clamped —
+      // clamping would answer a request for 90 days with a week and report
+      // success.
+      const chosenMinutes = request.minutes === undefined ? DEFAULT_BAN_MINUTES : request.minutes;
+      const allowed = new Set(BAN_DURATION_CHOICES.map((choice) => choice.minutes));
+      if (!allowed.has(chosenMinutes)) {
+        throw new ConsoleDomainError(
+          "invalid_request",
+          400,
+          "Unsupported ban duration. Choose one of the offered durations.",
+        );
+      }
+      const bannedUntil = chosenMinutes === null ? null : new Date(Date.now() + chosenMinutes * 60_000);
+      const current = await config.store.get(authorized.tenantId, keyId);
+      if (!current || current.revokedAt !== undefined)
+        throw new ConsoleDomainError("key_not_found", 404, "Key not found");
+      const banned = await config.store.ban(authorized.tenantId, keyId, reason, bannedUntil);
+      if (!banned) throw new ConsoleDomainError("key_not_found", 404, "Key not found");
+      // A banned child key does not affect its share template or sibling keys:
+      // `store.ban` only turns off the one row named by `keyId`, and the auth
+      // path rejects per key hash. The template keeps issuing working children.
+      // A banned key must leave the auth cache for every process at once.
+      invalidateApiKeyCache();
+      await config.auditSink?.record({
+        access: authorized,
+        action: "api_key.banned",
+        target: keyId,
+        detail: { reason, ...(bannedUntil === null ? { permanent: true } : { bannedUntil: bannedUntil.toISOString() }) },
+      });
+      const record = await config.store.get(authorized.tenantId, keyId);
+      if (!record) throw new ConsoleDomainError("key_not_found", 404, "Key not found");
+      return sanitizeApiKeyResponse(record);
+    },
+    async unbanKey(
+      access: AccessDecision | undefined,
+      keyId: string,
+    ): Promise<ApiKeyResponse> {
+      const authorized = requireTenantScope(access, "dashboard:write");
+      const current = await config.store.get(authorized.tenantId, keyId);
+      if (!current || current.revokedAt !== undefined)
+        throw new ConsoleDomainError("key_not_found", 404, "Key not found");
+      const unbanned = await config.store.unban(authorized.tenantId, keyId);
+      if (!unbanned) throw new ConsoleDomainError("key_not_found", 404, "Key not found");
+      invalidateApiKeyCache();
+      await config.auditSink?.record({
+        access: authorized,
+        action: "api_key.unbanned",
+        target: keyId,
+      });
+      const record = await config.store.get(authorized.tenantId, keyId);
+      if (!record) throw new ConsoleDomainError("key_not_found", 404, "Key not found");
+      return sanitizeApiKeyResponse(record);
+    },
   };
   return operations;
 }
@@ -750,7 +895,7 @@ function jsonNull(): Response {
   });
 }
 /** Creates tenant-bound API-key routes with request-local authorization. */
-export function createApiKeyRoutes(config: ApiKeyConfig): Elysia {
+export function createApiKeyRoutes(config: ApiKeyConfig): AnyElysia {
   const factory = createApiKeyOperations(config);
   return new Elysia({ prefix: "/api-keys" })
     .get("/", async ({ request, set }) => {
@@ -798,7 +943,11 @@ export function createApiKeyRoutes(config: ApiKeyConfig): Elysia {
     })
     .get("/:keyId/shared-keys", async ({ request, params, set }) => {
       try {
-        return await factory.listSharedKeys(config.accessResolver(request), params.keyId);
+        return await factory.listSharedKeys(
+          config.accessResolver(request),
+          params.keyId,
+          new URL(request.url).searchParams,
+        );
       } catch (error) {
         return errorResponse(error, set, "API-key operation failed");
       }
@@ -814,6 +963,21 @@ export function createApiKeyRoutes(config: ApiKeyConfig): Elysia {
         return errorResponse(error, set, "API-key operation failed");
       }
     })
+    .post(
+      "/:keyId/shared-keys/revoke-scope",
+      { body: t.Object({ scope: t.Union([t.Literal("active"), t.Literal("unused")]) }) },
+      async ({ request, params, body, set }) => {
+        try {
+          return await factory.revokeSharedScope(
+            config.accessResolver(request),
+            params.keyId,
+            body.scope,
+          );
+        } catch (error) {
+          return errorResponse(error, set, "API-key operation failed");
+        }
+      },
+    )
     .delete("/:keyId/shares/:shareId", async ({ request, params, set }) => {
       try {
         return await factory.revokeShare(
@@ -846,7 +1010,31 @@ export function createApiKeyRoutes(config: ApiKeyConfig): Elysia {
     })
     .delete("/:keyId", async ({ request, params, set }) => {
       try {
-        return await factory.revokeKey(config.accessResolver(request), params.keyId);
+        return await factory.deleteKey(config.accessResolver(request), params.keyId);
+      } catch (error) {
+        return errorResponse(error, set, "API-key operation failed");
+      }
+    })
+    .post(
+      "/:keyId/ban",
+      {
+        body: t.Object({
+          reason: t.String(),
+          reasonLabel: t.Optional(t.String()),
+          minutes: t.Optional(t.Union([t.Number({ minimum: 1 }), t.Null()])),
+        }),
+      },
+      async ({ request, params, body, set }) => {
+        try {
+          return await factory.banKey(config.accessResolver(request), params.keyId, body);
+        } catch (error) {
+          return errorResponse(error, set, "API-key operation failed");
+        }
+      },
+    )
+    .post("/:keyId/unban", async ({ request, params, set }) => {
+      try {
+        return await factory.unbanKey(config.accessResolver(request), params.keyId);
       } catch (error) {
         return errorResponse(error, set, "API-key operation failed");
       }
@@ -889,5 +1077,5 @@ export function createApiKeyRoutes(config: ApiKeyConfig): Elysia {
       } catch (error) {
         return errorResponse(error, set, "API-key operation failed");
       }
-    }) as unknown as Elysia;
+    });
 }

package/src/console/audit/routes.ts

@@ -1,4 +1,4 @@
-import { Elysia, t } from "elysia";
+import { Elysia, t, type AnyElysia } from "elysia";
 import { errorResponse, requireGlobalAdmin, requireTenantScope } from "../shared/errors";
 import { parseQueryLimit } from "../shared/query";
 import type { AuditRoutesConfig } from "./contracts";
@@ -10,7 +10,7 @@ const listQuery = t.Object({
   actor: t.Optional(t.String()),
 });
 
-export function createAuditRoutes(config: AuditRoutesConfig): Elysia {
+export function createAuditRoutes(config: AuditRoutesConfig): AnyElysia {
   return new Elysia().get("/audit", { query: listQuery }, async ({ request, query, set }) => {
     try {
       const resolved = config.accessResolver(request);
@@ -28,5 +28,5 @@ export function createAuditRoutes(config: AuditRoutesConfig): Elysia {
     } catch (e) {
       return errorResponse(e, set, "Audit read failed");
     }
-  }) as unknown as Elysia;
+  });
 }

package/src/console/auth/account-reset.ts

@@ -42,12 +42,12 @@ export function createConsoleAccountResetHandler(
   return async ({ request, body }) => {
     if (!isLoopbackPeer(deps.resolvePeerAddress(request)))
       throw new GatewayError(
-        "invalid_request",
+        "policy_rejected",
         403,
-        "console account reset is only available from loopback",
+        "console account reset is only available from loopback (request {requestId}). This operation is only allowed from a trusted loopback connection — no hard feelings 🫂",
       );
     if (!tokenMatches(request.headers.get("x-drain-token"), deps.token))
-      throw new GatewayError("invalid_request", 401, "invalid reset token");
+      throw new GatewayError("authentication_failed", 401, "invalid reset token (request {requestId}). Wrong key, right door — check the token 🔑");
     const confirm =
       body !== null && typeof body === "object" && "confirm" in body
         ? body.confirm
@@ -56,7 +56,7 @@ export function createConsoleAccountResetHandler(
       throw new GatewayError(
         "invalid_request",
         400,
-        `send {"confirm":"${CONFIRMATION}"} to confirm; this deletes every console account`,
+        `send {"confirm":"${CONFIRMATION}"} to confirm (request {requestId}); this deletes every console account. Make sure you mean it — there's no undo 🫂`,
       );
 
     const removed = await deps.resetConsoleAccount();

package/src/console/auth/session.ts

@@ -1,5 +1,5 @@
 import { asCookie, clearCsrfCookie, newCsrfToken, setCsrfCookie } from "../../security/csrf";
-import { Elysia, t } from "elysia";
+import { Elysia, t, type AnyElysia } from "elysia";
 import { eq } from "drizzle-orm";
 import { isRecord } from "../../protocol/codecs";
 import { userRecord, returningRows, assertMutationApplied } from "./row-coercion";
@@ -217,7 +217,7 @@ export function createConsoleAuthRoutes(
   cookiePolicy: SessionCookiePolicy = defaultSessionCookiePolicy,
   trustedProxyBoundary: TrustedProxyBoundary = { mode: "disabled" },
   resolvePeerAddress: (request: Request) => string | undefined = () => undefined,
-): Elysia {
+): AnyElysia {
   const app = new Elysia({ prefix: "/auth" });
   const policy = cookiePolicy;
   const database = db;
@@ -532,5 +532,5 @@ export function createConsoleAuthRoutes(
     },
   );
 
-  return app as unknown as Elysia;
+  return app;
 }

package/src/console/backup/contracts.ts

@@ -33,6 +33,7 @@ import {
   poolRoutingSettings,
   providerAccounts,
   providerOauthStates,
+  providerPoolAccounts,
   providerRoutingSettings,
   providers,
   shareLinks,
@@ -96,6 +97,7 @@ export const CONFIG_TABLES = [
   models,
   providerRoutingSettings,
   providerAccounts,
+  providerPoolAccounts,
   poolRoutingSettings,
   networkPools,
   providers,

package/src/console/backup/export-endpoint.ts

@@ -24,7 +24,7 @@ import { join } from "node:path";
 import { GatewayError } from "../../protocol/gateway-error";
 import { isLoopbackPeer, tokenMatches } from "../../transport/drain-endpoint";
 import { BACKUP_SECTIONS, tablesForSection } from "./contracts";
-import { exportBackup } from "./store";
+import { compressBackupStream, exportBackupStream } from "./store";
 import type { CartethyiaDatabase } from "../../persistence/db-handle";
 
 export interface BackupExportDeps {
@@ -52,31 +52,28 @@ export function createBackupExportHandler(
     // came from, the second is the credential it carried — and `invalid_request`
     // told an operator to fix a body that was never the problem.
     if (!isLoopbackPeer(deps.resolvePeerAddress(request)))
-      throw new GatewayError("policy_rejected", 403, "backup export is only available from loopback");
+      throw new GatewayError("policy_rejected", 403, "backup export is only available from loopback (request {requestId}). This operation is only allowed from a trusted loopback connection — no hard feelings 🫂");
     if (!tokenMatches(request.headers.get("x-drain-token"), deps.token))
-      throw new GatewayError("authentication_failed", 401, "invalid export token");
+      throw new GatewayError("authentication_failed", 401, "invalid export token (request {requestId}). Wrong key, right door — check the token 🔑");
 
     const directory =
       body !== null && typeof body === "object" && "directory" in body
         ? body.directory
         : undefined;
     if (directory !== undefined && typeof directory !== "string")
-      throw new GatewayError("invalid_request", 400, "directory must be a string");
+      throw new GatewayError("invalid_request", 400, "directory must be a string (request {requestId}). Check the shape of what you sent — then resend 🪞");
 
     const tenantId = await deps.resolveTenantId();
     if (tenantId === null)
-      throw new GatewayError("invalid_request", 409, "no tenant exists; run setup first");
+      throw new GatewayError("invalid_request", 409, "no tenant exists; run setup first (request {requestId}). Nothing here but dust — run setup first 🌙");
 
-    const { payload, counts } = await exportBackup(
-      deps.db,
-      tablesForSection("config"),
-      tenantId,
-    );
-
-    // gzipSync matches what the console writes, so a CLI backup and a dashboard
-    // backup are the same file format and either can be restored by the other.
-    const json = JSON.stringify(payload);
-    const gzipped = Bun.gzipSync(new TextEncoder().encode(json));
+    // One gzip pass over the streamed document: a tenant with hundreds of
+    // thousands of rows is read page by page and only the compressed bytes
+    // land in the buffer — the same file format a console backup produces, so
+    // a CLI backup and a dashboard backup remain restorable by the other.
+    const stream = await exportBackupStream(deps.db, tablesForSection("config"), tenantId);
+    const gzipped = await compressBackupStream(stream.jsonChunks);
+    const counts = await stream.counts;
     const target = directory ?? downloadDirectory();
     const stamp = new Date().toISOString().replace(/[:.]/g, "-");
     const path = join(target, `cartethyia-backup-${stamp}.json.gz`);
@@ -86,9 +83,9 @@ export function createBackupExportHandler(
       writeFileSync(path, gzipped);
     } catch (error) {
       throw new GatewayError(
-        "invalid_request",
+        "internal_error",
         500,
-        `could not write ${path}: ${error instanceof Error ? error.message : "unknown error"}`,
+        `could not write ${path}: ${error instanceof Error ? error.message : "unknown error"} (request {requestId}). Even we have bad days — retry, and quote the request id if it persists 🐻`,
       );
     }
 

package/src/console/backup/routes.ts

@@ -14,7 +14,7 @@
  * The body bound is enforced here, before the JSON parse, because the whole
  * point of the limit is to not buffer an unbounded file.
  */
-import { Elysia, t } from "elysia";
+import { Elysia, t, type AnyElysia } from "elysia";
 import type { ConsoleAccessResolver } from "../auth/access";
 import { invalidateApiKeyCache } from "../../security/api-key-auth";
 import { invalidatePublicModels } from "../providers/catalog/public-model-store";
@@ -22,7 +22,7 @@ import { ConsoleDomainError, errorResponse, requireAnyScope } from "../shared/er
 import { NO_COMPRESS_HEADER } from "../response-compression";
 import { MAX_BACKUP_BYTES } from "./contracts";
 import type { BackupSection } from "./contracts";
-import { DELETE_ALL_SCOPES, compressBackup } from "./store";
+import { DELETE_ALL_SCOPES, compressBackupStream } from "./store";
 import type { BackupService } from "./service";
 import type { AuditRecorder } from "../auth/audit-recorder";
 
@@ -48,7 +48,7 @@ export interface BackupRoutesConfig {
   /**
    * The tenant's API keys, read after a restore so their admission counters can
    * be purged. A restore replaces `api_keys` wholesale, so a key that was
-   * revoked after the backup — and had its counters purged by `revokeKey` — can
+   * revoked after the backup — and had its counters purged by `deleteKey` — can
    * come back with `revoked_at = NULL`; without purging, its lifetime counter
    * is re-seeded from the restored total, granting a fresh full budget on top
    * of everything already spent. Optional so a host that never restores keys
@@ -118,7 +118,28 @@ function parseSections(raw: string | undefined): readonly BackupSection[] | unde
     .filter((part) => part.length > 0) as readonly BackupSection[];
 }
 
-export function createBackupRoutes(config: BackupRoutesConfig): Elysia {
+/**
+ * Streams the export document into the response body as it is written; one
+ * row-page of the tenant's data is in memory at a time.
+ */
+function payloadDocument(chunks: AsyncGenerator<string, void, void>): ReadableStream<Uint8Array> {
+  const encoder = new TextEncoder();
+  return new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      const next = await chunks.next();
+      if (next.done) {
+        controller.close();
+        return;
+      }
+      controller.enqueue(encoder.encode(next.value));
+    },
+    async cancel() {
+      await chunks.return();
+    },
+  });
+}
+
+export function createBackupRoutes(config: BackupRoutesConfig): AnyElysia {
   return new Elysia({ prefix: "/backup" })
     .get("/export", { query: exportQuery }, async ({ request, query, set }) => {
       try {
@@ -129,7 +150,7 @@ export function createBackupRoutes(config: BackupRoutesConfig): Elysia {
         const backup = config.backupFor(request);
         const sections = parseSections(query.sections);
         const compressed = query.compressed === "1";
-        const { payload } = await backup.export({
+        const exportStream = await backup.export({
           password: query.password,
           tenantId: access.tenantId,
           compressed,
@@ -138,11 +159,22 @@ export function createBackupRoutes(config: BackupRoutesConfig): Elysia {
         const stamp = new Date().toISOString().slice(0, 19).replace(/[:T]/g, "-");
         set.headers["cache-control"] = "no-store";
         if (!compressed) {
-          set.headers["content-disposition"] = `attachment; filename="cartethyia_backup_${stamp}.json"`;
-          set.headers["content-type"] = "application/json; charset=utf-8";
-          return payload;
+          // The document is written through the stream, so a tenant with
+          // hundreds of thousands of rows is serialized here while only one
+          // row-page of it is ever in memory. The headers live on the
+          // Response itself: a native Response carries the stream, and the
+          // response wrapper would otherwise buffer it whole to gzip it —
+          // the same trade its ceiling path already made for large exports
+          // (rebuilt, uncompressed) — so this branch opts out of it.
+          const headers = new Headers({
+            "cache-control": "no-store",
+            "content-disposition": `attachment; filename="cartethyia_backup_${stamp}.json"`,
+            "content-type": "application/json; charset=utf-8",
+            [NO_COMPRESS_HEADER]: "1",
+          });
+          return new Response(payloadDocument(exportStream.jsonChunks), { headers });
         }
-        const bytes = compressBackup(payload);
+        const bytes = await compressBackupStream(exportStream.jsonChunks);
         set.headers["content-type"] = "application/json; charset=utf-8";
         // Opt out of the response wrapper's gzip rather than declaring
         // `content-encoding: gzip`: the bytes here are base64 of a gzip
@@ -193,7 +225,7 @@ export function createBackupRoutes(config: BackupRoutesConfig): Elysia {
         // snapshot must be rebuilt before the next `/v1/*` dispatch.
         await config.snapshotInvalidator?.invalidate();
         // A restore can re-insert keys the tenant revoked after the backup, and
-        // `revokeKey` purged their counters when they went away. Drop the whole
+        // `deleteKey` purged their counters when they went away. Drop the whole
         // auth cache (the restore is rare, and a stale entry for any key must
         // not survive it) and purge admission state for every key the tenant
         // now has, so a resurrected key cannot start with a fresh budget.
@@ -272,5 +304,5 @@ export function createBackupRoutes(config: BackupRoutesConfig): Elysia {
       } catch (error) {
         return errorResponse(error, set, "Backup inspection failed");
       }
-    }) as unknown as Elysia;
+    });
 }

package/src/console/backup/service.ts

@@ -40,7 +40,8 @@ import {
   applyRestore,
   decompressBackup,
   deleteAll,
-  exportBackup,
+  exportBackupStream,
+  type BackupExportStream,
   type DeleteAllResult,
   type DeleteAllScope,
 } from "./store";
@@ -269,17 +270,16 @@ async function omitRowsForUnavailableProviders(
 export class BackupService {
   constructor(private readonly options: BackupServiceOptions) {}
 
-  async export(options: ExportOptions): Promise<{ payload: unknown; counts: Record<string, number> }> {
+  async export(options: ExportOptions): Promise<BackupExportStream> {
     if (!(await this.options.verifyPassword(options.password))) {
       throw new ConsoleDomainError("unauthorized", 401, "password is incorrect");
     }
     const sections = sectionsOrDefault(options.sections);
-    const { payload, counts } = await exportBackup(
+    return exportBackupStream(
       this.options.db,
       sections.flatMap((section) => tablesForSection(section)),
       options.tenantId,
     );
-    return { payload, counts };
   }
 
   /**
@@ -453,11 +453,16 @@ export class BackupService {
     sections: readonly BackupSection[] | undefined,
     tenantId: string,
   ): Promise<Record<string, number>> {
-    const { counts } = await exportBackup(
+    const stream = exportBackupStream(
       this.options.db,
       sectionsOrDefault(sections).flatMap((section) => tablesForSection(section)),
       tenantId,
     );
-    return counts;
+    // Walk the stream so the tally settles, discarding the bytes: a preview
+    // must not hold the payload either.
+    for await (const _chunk of stream.jsonChunks) {
+      // discard
+    }
+    return stream.counts;
   }
 }