cartethyia 2.7.1 → 2.7.3

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

@@ -13,7 +13,12 @@ import { ConsoleDomainError, errorResponse, requireTenantScope } from "../shared
 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 {
+  ApiKeyPatch,
+  ApiKeyRecord,
+  SharedChildSortColumn,
+  SharedChildrenPageOptions,
+} from "../../persistence/stores/api-key-store";
 import {
   generateApiKeySecret,
   isDefaultGatewayApiKey,
@@ -34,6 +39,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 +82,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 +185,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 +320,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 +417,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 +442,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 +684,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 +700,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 +722,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,
@@ -798,7 +878,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 +898,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 +945,7 @@ 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");
       }

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 {
@@ -67,16 +67,13 @@ export function createBackupExportHandler(
     if (tenantId === null)
       throw new GatewayError("invalid_request", 409, "no tenant exists; 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`);

package/src/console/backup/routes.ts

@@ -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,6 +118,27 @@ function parseSections(raw: string | undefined): readonly BackupSection[] | unde
     .filter((part) => part.length > 0) as readonly BackupSection[];
 }
 
+/**
+ * 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): Elysia {
   return new Elysia({ prefix: "/backup" })
     .get("/export", { query: exportQuery }, async ({ request, query, set }) => {
@@ -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.

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;
   }
 }