cartethyia 2.7.9 → 2.8.0

package/dist/dashboard/precompressed-assets.json

@@ -1,77 +1,77 @@
 {
-  "count": 121,
+  "count": 122,
   "assets": [
-    "assets/BannedPage-BxoG1MrL.js",
-    "assets/CliToolDetailPage-ixwgKk53.js",
-    "assets/CliToolsPage-BmttNV3U.js",
-    "assets/CombosPage-BE3qwwfC.js",
-    "assets/ConsoleLogPage-CRZdmMIX.js",
-    "assets/CustomizationPage-Dv_FJ6Er.js",
-    "assets/HealthEventsModal-CoVrw2sM.js",
-    "assets/InjectSystemPromptPanel-BOoO8rpz.js",
-    "assets/LoginPage-ChJuNNVN.js",
-    "assets/ModelPicker-BZAJtPg1.js",
-    "assets/OverviewPage-BE40s3u5.js",
-    "assets/ProviderDetailPage-sfLoQtPV.js",
-    "assets/ProviderIcon-CQ6bPUf_.js",
-    "assets/ProvidersPage-DcepmPWo.js",
-    "assets/ProxyPage-BJ87Pp0U.js",
-    "assets/QuotaPage-gkSyRAKa.js",
-    "assets/SettingsPage-C5HPWqEv.js",
-    "assets/SetupPage-CFNcATJJ.js",
-    "assets/StudioPage-YoD4tY5l.js",
+    "assets/BannedPage-Cc0vKpMG.js",
+    "assets/CliToolDetailPage-Bqj2aa1T.js",
+    "assets/CliToolsPage-CXsaOAO2.js",
+    "assets/CombosPage-BeLpJ4ma.js",
+    "assets/ConsoleLogPage-DnV0uZ3m.js",
+    "assets/CustomizationPage-CBxAjo63.js",
+    "assets/HealthEventsModal-B5yEE0k6.js",
+    "assets/InjectSystemPromptPanel-BWFLECmz.js",
+    "assets/LoginPage-CgoPc5B9.js",
+    "assets/ModelPicker-D9bFQern.js",
+    "assets/OverviewPage-B_p4tL8k.js",
+    "assets/ProviderDetailPage-rs5E2rxv.js",
+    "assets/ProviderIcon-D_0PiZtg.js",
+    "assets/ProvidersPage-CLI2bJTK.js",
+    "assets/ProxyPage-BwNC_-Cx.js",
+    "assets/QuotaPage-DA-a1iSN.js",
+    "assets/SettingsPage-CctTga2C.js",
+    "assets/SetupPage-febLU4r1.js",
+    "assets/StudioPage-M6fvR5Wz.js",
     "assets/ToolIcon-CfeLA-Z_.js",
-    "assets/UsagePage-DxjaAhb_.js",
-    "assets/api-keys-BTlkq_Uk.js",
-    "assets/app-B7kIWFm5.js",
-    "assets/app-BX2nnKqs.css",
+    "assets/UsagePage-nyeuRqz9.js",
+    "assets/api-keys-BFOlvrJC.js",
+    "assets/app-DIXLjojg.js",
+    "assets/app-Dx2QgsNj.css",
     "assets/arrow-left-CpBxkoxI.js",
     "assets/arrow-right-Dl5yKnp8.js",
     "assets/arrow-up-59ms1iiT.js",
-    "assets/assert-CndthXFQ.js",
+    "assets/assert-CqTLw5e7.js",
     "assets/backup-file-gdKIlg8U.js",
-    "assets/badge-DdbT_7Am.js",
+    "assets/badge-C83EqLB0.js",
     "assets/ban-durations-B58FyRxC.js",
-    "assets/banner-CsGN-nbm.js",
+    "assets/banner-D1xn7pIe.js",
     "assets/brain-Cwed_72z.js",
-    "assets/card-mgZ_TLLZ.js",
+    "assets/card-DU3Lq5Lm.js",
     "assets/chevron-left-Bf6CaTSJ.js",
     "assets/chevron-right-BXIy5l3h.js",
     "assets/circle-alert-CntYHV5v.js",
     "assets/circle-check-BU3v_mFW.js",
     "assets/circle-question-mark-Cz4un8sH.js",
-    "assets/cli-tools-A1-v8-03.js",
-    "assets/clipboard-button-CJ4Zty89.js",
+    "assets/cli-tools-Dw1U_drK.js",
+    "assets/clipboard-button-CEL5Sg_J.js",
     "assets/database-Dz9N3zGd.js",
-    "assets/dialog-B5L2jPQ_.js",
+    "assets/dialog-BjFR5UHy.js",
     "assets/dialog-actions-B1axpEg7.js",
     "assets/download-dRFo5_Wu.js",
-    "assets/drawer-DkjUouAj.js",
-    "assets/entry-B-LVLV6o.js",
-    "assets/entry-CAhdYl3B.js",
-    "assets/entry-D2xD0Tmd.js",
+    "assets/drawer-HvBW0AjI.js",
+    "assets/entry-BSu3gFlt.js",
+    "assets/entry-CECVELyy.js",
+    "assets/entry-DYYofQ7W.js",
     "assets/eye-C_hawfH4.js",
     "assets/eye-off-Bk5g2luF.js",
     "assets/fingerprint-pattern-BWuHtbW4.js",
-    "assets/formatters-CrsdLVsn.js",
+    "assets/formatters-DLW4i8zK.js",
     "assets/gauge-BbIMy7MB.js",
     "assets/house-h9AZlJuT.js",
     "assets/image-BPaouViG.js",
-    "assets/index-BU64Lqvp.js",
-    "assets/inline-B2aDLyyg.js",
-    "assets/input-BCVkdR9d.js",
+    "assets/index-1-fCqe64.js",
+    "assets/inline-DGvU2oLK.js",
+    "assets/input-iNnO1X2K.js",
     "assets/jsx-runtime-CXUMngI_.js",
     "assets/key-round-UkavsGxp.js",
     "assets/layers-2-glBbjl.js",
-    "assets/layout-DNcAdMK-.js",
-    "assets/list-row-DgrIH0hw.js",
-    "assets/live-Cae01iu8.js",
+    "assets/layout-0q8UGypb.js",
+    "assets/list-row-C0w2bQjJ.js",
+    "assets/live-M5aJ_xCa.js",
     "assets/log-in-BmRjy60c.js",
     "assets/message-circle-CCxGwRvv.js",
     "assets/mutation-BQ0ccH_A.js",
-    "assets/network-CRib7H_2.js",
-    "assets/numbers-BKQE8Xpz.js",
-    "assets/pagination-ecPvG_8g.js",
+    "assets/network-BKeQGT3K.js",
+    "assets/numbers-CivAk3da.js",
+    "assets/pagination-CpzvI5ep.js",
     "assets/pencil-768ysRAr.js",
     "assets/plus-DIdX_g-x.js",
     "assets/power-off-Yjw9GMJh.js",
@@ -95,22 +95,23 @@
     "assets/providers/parallel.svg",
     "assets/providers/tokenharbor.svg",
     "assets/providers/windsurf.svg",
+    "assets/providers/zro.svg",
     "assets/query-keys-IKLh0YFd.js",
-    "assets/quota-DJ1QlAOq.js",
+    "assets/quota-DiPD6UKH.js",
     "assets/refresh-cw-BqJFk4sU.js",
     "assets/rotate-ccw-CufcqITi.js",
     "assets/route-CNSNj9Zm.js",
-    "assets/routing-Ckm1UXuC.js",
+    "assets/routing-BFQX2VBc.js",
     "assets/scaling-nWE4Cx8f.js",
     "assets/search-JOKus9rb.js",
-    "assets/select-ChoFWyKz.js",
+    "assets/select-CXbck0jG.js",
     "assets/settings-2-Ds9DQp0t.js",
-    "assets/settings-CKjFPlKW.js",
+    "assets/settings-C_XvMHh9.js",
     "assets/shield-BMQNxORh.js",
     "assets/shield-check-DVS0Foqh.js",
-    "assets/stack-DWCwU3fh.js",
-    "assets/state-Cg3VL5J_.js",
-    "assets/switch-Db70BMix.js",
+    "assets/stack-DggRiCxE.js",
+    "assets/state-ClFzfbYp.js",
+    "assets/switch-CTIFxKqS.js",
     "assets/terminal-0_IjPWTk.js",
     "assets/tokens-COzario9.js",
     "assets/trash-Cppn5c3R.js",
@@ -118,7 +119,7 @@
     "assets/use-modal-focus-By7oJoGd.js",
     "assets/use-reduced-motion-C4B0R6Sz.js",
     "assets/use-timeout-BwcBBRrT.js",
-    "assets/useMutation-BqdE0LuM.js",
+    "assets/useMutation-BClG3yWj.js",
     "assets/wrench-B6E1oEuY.js",
     "assets/zap-C4EeVW4q.js",
     "index.html"

package/migrations/full-postgres/0046_add_accounts_quota_plan_fetched_at.sql

@@ -0,0 +1,7 @@
+-- Freshness stamp for `quota_plan`: the plan column is a bare string, so
+-- routing cannot tell a fresh read from a stale one. This timestamp is written
+-- together with `quota_plan` on a successful quota fetch and lets the routing
+-- engine downgrade a plan older than the freshness horizon to `unknown`
+-- instead of trusting it blindly.
+ALTER TABLE "provider_accounts"
+  ADD COLUMN IF NOT EXISTS "quota_plan_fetched_at" timestamptz;

package/migrations/lite-sqlite3/0046_add_accounts_quota_plan_fetched_at.sql

@@ -0,0 +1,4 @@
+-- SQLite mirror of `full-postgres/0046_add_accounts_quota_plan_fetched_at.sql`:
+-- the timestamp column is stored as an ISO-8601 text string.
+ALTER TABLE "provider_accounts"
+  ADD COLUMN "quota_plan_fetched_at" text;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cartethyia",
-  "version": "2.7.9",
+  "version": "2.8.0",
   "description": "A powerful, self-hosted reverse proxy for OpenAI- and Anthropic-compatible AI clients, powered by native Bun and Elysia. It serves both protocols from a single server, routes every model across any configured provider, and translates requests and responses in real time — streaming and prompt caching included. Underneath it runs a full delivery engine: per-account health tracking, quota and cooldown enforcement, automatic failover across pools and providers, usage accounting, and telemetry. Point OpenCode, Cline, Claude Code, Codex, or any compatible client at Cartethyia and it keeps its native protocol while the gateway absorbs every provider-specific difference behind it. Runs on embedded SQLite or external PostgreSQL with optional Redis coordination, ships as a global CLI with a system-tray console, and needs only Bun 1.4+ alongside Node.js/npm.",
   "license": "GPL-3.0-only",
   "type": "module",

package/src/boot/app.ts

@@ -10,7 +10,7 @@ import { chatAdapter } from "../transport/surface/chat/adapter";
 import { responsesAdapter } from "../transport/surface/responses/adapter";
 import { messagesAdapter } from "../transport/surface/messages/adapter";
 import { completionAdapter } from "../transport/surface/completion";
-import { SurfaceAdapterRegistry } from "../transport/surface/adapters";
+import { SurfaceAdapterRegistry, type SurfaceAdapter } from "../transport/surface/adapters";
 import { GatewayError, publicGatewayErrorBody } from "../protocol/gateway-error";
 import { shutdownError, shutdownNotice } from "../transport/shutdown-notice";
 import type { CanonicalAdapter } from "../transport/contracts";
@@ -47,7 +47,7 @@ import {
 import { createTokenCountHandler } from "../transport/dispatch/token-count";
 
 import { createTransportPipeline } from "../transport/guards/pipeline";
-import { createDrainHandler, isLoopbackPeer, tokenMatches } from "../transport/drain-endpoint";
+import { createDrainHandler, requireLoopbackAdmin } from "../transport/drain-endpoint";
 import { createConsoleAccountResetHandler } from "../console/auth/account-reset";
 import { resetConsoleAuthState } from "../console/auth/account-reset-store";
 import { createBackupExportHandler } from "../console/backup/export-endpoint";
@@ -210,7 +210,7 @@ export function createGatewayApp(deps: GatewayAppDeps) {
     deps.mode === "route-only"
       ? (deps.checkRedis ?? checkRedisConnection)
       : checkRedisConnection;
-  const registry = new SurfaceAdapterRegistry([
+  const registry = new SurfaceAdapterRegistry<SurfaceAdapter & CanonicalAdapter>([
     chatAdapter,
     responsesAdapter,
     messagesAdapter,
@@ -424,12 +424,7 @@ export function createGatewayApp(deps: GatewayAppDeps) {
       db: deps.db,
       stateStore: requestStateStore,
       surfaceRegistry: registry,
-      adapters: new Map<string, CanonicalAdapter>([
-        ["chat", chatAdapter],
-        ["responses", responsesAdapter],
-        ["messages", messagesAdapter],
-        ["completion", completionAdapter],
-      ]),
+      adapters: new Map<string, CanonicalAdapter>(registry.bySurface()),
       preparer: deps.proxyPreparer,
       readiness: deps.readiness,
       trustedProxyBoundary: deps.trustedProxyBoundary,
@@ -652,10 +647,12 @@ export function createGatewayApp(deps: GatewayAppDeps) {
         // well-formed. What refused it is where it came from — the client asked
         // for something only the local host may ask. `invalid_request` told an
         // operator to fix the body, when the body was never the problem.
-        if (!isLoopbackPeer(peerAddresses.get(request) ?? null))
-          throw new GatewayError("policy_rejected", 403, "task trigger 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"), token))
-          throw new GatewayError("authentication_failed", 401, "invalid drain token (request {requestId}). Wrong key, right door — check the token 🔑");
+        requireLoopbackAdmin(request, {
+          peer: peerAddresses.get(request) ?? null,
+          token,
+          policyRejectedMessage: "task trigger is only available from loopback (request {requestId}). This operation is only allowed from a trusted loopback connection — no hard feelings 🫂",
+          authenticationFailedMessage: "invalid drain token (request {requestId}). Wrong key, right door — check the token 🔑",
+        });
         const name = params.name;
         if (!tasks.names().includes(name))
           throw new GatewayError("not_found", 404, `no such task: ${name} (request {requestId}). Nothing here but dust — check the task name 🌙`);

package/src/boot/dependencies.ts

@@ -62,7 +62,7 @@ import {
 } from "../workers/buddy-growth-tasks";
 import { createAccountSecretResolver } from "../providers/operations/provider-credential-service";
 import { quotaCacheSize } from "../providers/quota/cache";
-import { modelCatalogCacheSize } from "../providers/operations/model-catalog-cache";
+import { modelCatalogCacheSize } from "../providers/operations/provider-caches";
 import { preferencesReaderFor } from "../persistence/tenant-preferences";
 import { sweepExpiredCooldowns } from "../providers/operations/account-health-service";
 import { DrizzleTelemetryStore } from "../persistence/stores/telemetry-store";

package/src/boot/flush.ts

@@ -0,0 +1,20 @@
+// Shared drain sequence for the process's queued writers. The console's manual
+// "flush now" and the shutdown coordinator's telemetry flush must drain exactly
+// the same buffers in the same order — a fourth writer added to one path but
+// not the other would silently stop reaching the disk on one of them.
+//
+// The deps are the minimal write surface each buffer exposes: a `flush()` that
+// resolves when the buffer is drained. The concrete buffers satisfy it, and a
+// test can substitute stubs without casting.
+export interface FlushAllBuffersDeps {
+  readonly telemetryBuffer: { flush(): Promise<void> };
+  readonly usageFlush: { flush(): Promise<void> };
+  readonly healthEventFlush: { flush(): Promise<void> };
+}
+
+/** Drains every buffered writer, in the canonical order. */
+export async function flushAllBuffers(deps: FlushAllBuffersDeps): Promise<void> {
+  await deps.telemetryBuffer.flush();
+  await deps.usageFlush.flush();
+  await deps.healthEventFlush.flush();
+}

package/src/boot/lifecycle.ts

@@ -2,6 +2,7 @@ import { closeDb } from "../persistence/boot";
 import { closeRedis } from "../persistence/redis";
 import { buildProductionDeps } from "./dependencies";
 import type { ProductionDeps } from "./dependencies";
+import { flushAllBuffers } from "./flush";
 import { withTimeout } from "./timeout";
 import { resolveShutdownDrainWindowMs } from "../config/runtime";
 import { log } from "../observability/logger";
@@ -35,8 +36,11 @@ export class ShutdownCoordinator {
   ) {
     this.hooks = hooks ?? {};
     this.drainWindowMs = opts?.drainWindowMs ?? 20_000;
-    this.drainTimeoutMs = opts?.drainTimeoutMs ?? 5_000;
-    this.flushTimeoutMs = opts?.flushTimeoutMs ?? 2_000;
+    // Defaults mirror what `bootstrap()` passes (8_000 / 1_000; drainWindowMs
+    // 20_000 is the spec default `resolveShutdownDrainWindowMs()` returns), so
+    // reasoning about drain timing from the class alone matches production.
+    this.drainTimeoutMs = opts?.drainTimeoutMs ?? 8_000;
+    this.flushTimeoutMs = opts?.flushTimeoutMs ?? 1_000;
   }
 
   /**
@@ -217,9 +221,7 @@ export async function bootstrap(): Promise<CartethyiaBoot> {
     shutdownCoordinator: new ShutdownCoordinator(
       {
         flushTelemetry: async () => {
-          await deps.telemetryBuffer.flush();
-          await deps.usageFlush.flush();
-          await deps.healthEventFlush.flush();
+          await flushAllBuffers(deps);
         },
         closePools: async () => {
           await boot.server?.stop();

package/src/config/routing.ts

@@ -0,0 +1,26 @@
+// Routing configuration knobs.
+import { CONFIG_SPEC, readInt } from "./spec";
+
+/** Routing reserve percent (0–100). Accounts at/below this remaining-quota % are demoted. */
+export function accountReservePct(): number {
+  return readInt(
+    "CARTETHYIA_ACCOUNT_RESERVE_PCT",
+    CONFIG_SPEC.CARTETHYIA_ACCOUNT_RESERVE_PCT,
+  );
+}
+
+/** Session-sticky warm window in ms. 0 disables stickiness. */
+export function routingStickyWarmMs(): number {
+  return readInt(
+    "CARTETHYIA_ROUTING_STICKY_WARM_MS",
+    CONFIG_SPEC.CARTETHYIA_ROUTING_STICKY_WARM_MS,
+  );
+}
+
+/** LRU cap on remembered session→account sticky state per provider. */
+export function routingStickyMaxSessions(): number {
+  return readInt(
+    "CARTETHYIA_ROUTING_STICKY_MAX_SESSIONS",
+    CONFIG_SPEC.CARTETHYIA_ROUTING_STICKY_MAX_SESSIONS,
+  );
+}

package/src/config/spec-metadata.ts

@@ -0,0 +1,72 @@
+/**
+ * Shared metadata for config docs and tests.
+ *
+ * `CONFIG_SPEC` declares the gateway's spec-driven variables. These constants
+ * name the deliberate asymmetries around it so `.env.example`, the generated
+ * reference, and the drift tests all project the same exception lists.
+ */
+
+/** Keys in `CONFIG_SPEC` that are intentionally absent from `.env.example`. */
+export const SPEC_ONLY_ENV_EXAMPLE_KEYS: Readonly<Record<string, true>> = {
+  // Setup wizard writes this directly; a sample would mislead copy/paste.
+  CARTETHYIA_API_KEY: true,
+  // Opt-in diagnostics; sampling them would nudge operators to enable them.
+  CARTETHYIA_FORCED_GC: true,
+  CARTETHYIA_RUNTIME_METRICS_INTERVAL_MS: true,
+  // Advanced knobs documented in the generated configuration reference.
+  CARTETHYIA_DISABLED_TASKS: true,
+  // Install-identity directory; only operators who need a stable identity
+  // across restarts touch it, and the reference covers it.
+  CARTETHYIA_INSTALL_ID_DIR: true,
+  CARTETHYIA_OAUTH_CALLBACK_PORT: true,
+  // Provider-specific overrides. Readers live in `src/config/providers.ts`;
+  // the majority of installs do not need them in the starter sample.
+  CARTETHYIA_KIMI_OAUTH_HOST: true,
+  CARTETHYIA_KIMI_QUOTA_BASE_URL: true,
+  CARTETHYIA_GITHUB_ENTERPRISE_DOMAIN: true,
+  CARTETHYIA_OPENCODE_UNAVAILABLE_FREE: true,
+  // Telemetry retention is deployment-level and documented in the reference.
+  CARTETHYIA_TELEMETRY_RETENTION_DAYS: true,
+  CARTETHYIA_TELEMETRY_PAYLOAD_MAX_BYTES: true,
+};
+
+/** Keys in `.env.example` that `CONFIG_SPEC` does not declare. */
+export const ENV_EXAMPLE_ONLY_KEYS: Readonly<Record<string, true>> = {
+  // Read outside `src/config/` by their owning modules.
+  CARTETHYIA_DB_MODE: true,
+  NODE_ENV: true,
+  LOG_LEVEL: true,
+  DATABASE_URL: true,
+  DATABASE_POOL_MAX: true,
+  DATABASE_POOL_IDLE_FLOOR: true,
+  REDIS_URL: true,
+  CARTETHYIA_DATA_DIR: true,
+  CARTETHYIA_TELEMETRY_PAYLOAD_DIR: true,
+  CARTETHYIA_CONFIG_DIR: true,
+  DASHBOARD_PORT: true,
+  VITE_BACKEND_URL: true,
+  // Test-runner-only knob, not read by the gateway runtime.
+  CARTETHYIA_TEST_JOBS: true,
+};
+
+/**
+ * Operator-visible variables that are intentionally outside `CONFIG_SPEC` and
+ * therefore omitted from the generated configuration reference.
+ */
+export const CONFIG_REFERENCE_EXTERNAL_VARIABLES = [
+  "CARTETHYIA_DB_MODE",
+  "DATABASE_URL",
+  "REDIS_URL",
+  "NODE_ENV",
+  "LOG_LEVEL",
+  "DATABASE_POOL_MAX",
+  "DATABASE_POOL_IDLE_FLOOR",
+  "CARTETHYIA_DATA_DIR",
+  "CARTETHYIA_TELEMETRY_PAYLOAD_DIR",
+  "CARTETHYIA_CONFIG_DIR",
+  "DASHBOARD_PORT",
+  "VITE_BACKEND_URL",
+  "CARTETHYIA_TEST_DATABASE_URL",
+  "CARTETHYIA_TEST_JOBS",
+  "CARTETHYIA_REDIS_URL",
+] as const;

package/src/config/spec.ts

@@ -264,6 +264,26 @@ export const CONFIG_SPEC = {
   CARTETHYIA_ACCOUNT_AUTH_REJECTED_COOLDOWN_MS: { kind: "int", default: 300_000, min: 0, max: 86_400_000 },
   CARTETHYIA_ACCOUNT_POLICY_BLOCK_COOLDOWN_MS: { kind: "int", default: 300_000, min: 0, max: 86_400_000 },
   CARTETHYIA_ACCOUNT_DISABLED_RECOVERY_MS: { kind: "int", default: 86_400_000, min: 0, max: 604_800_000 },
+  /**
+   * Routing reserve: an account whose remaining quota fraction falls at or
+   * below this percent is demoted behind non-reserve siblings during ordering
+   * (it is still eligible and still routed — a reserve is a preference, never
+   * an exclusion). 0 disables reserve demotion for every account.
+   */
+  CARTETHYIA_ACCOUNT_RESERVE_PCT: { kind: "int", default: 20, min: 0, max: 100 },
+  /**
+   * Session stickiness warm window (milliseconds). Within this window after an
+   * account last served a session id, routing prefers that account when it is
+   * still eligible — prompt-cache warmth is worth more than perfect load
+   * balance. Past the window, the sticky account is only an ordering hint.
+   * 0 disables stickiness.
+   */
+  CARTETHYIA_ROUTING_STICKY_WARM_MS: { kind: "int", default: 300_000, min: 0, max: 86_400_000 },
+  /**
+   * Hard ceiling on distinct session ids whose sticky state is retained in
+   * memory per provider (LRU). Evicted sessions simply lose their preference.
+   */
+  CARTETHYIA_ROUTING_STICKY_MAX_SESSIONS: { kind: "int", default: 256, min: 1, max: 10_000 },
 
   // Proxy pool agents
   CARTETHYIA_PROXY_MAX_SOCKETS: { kind: "int", default: 100, min: 1, max: 100_000 },

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

@@ -11,7 +11,7 @@ import { type ShareLinkStore, type ShareLinkSummary } from "../../persistence/st
 import { API_KEY_MODES, API_KEY_CONCURRENCY_SCOPES, type ApiKeyMode, type ApiKeyModelAccessMode, type ShareLinkKind } from "../../persistence/schema";
 import { isValidTenantKeyScope, type AccessScope } from "../../security/access-control";
 import { normalizeClientRouterId } from "../../security/client-router-fingerprint";
-import type { ShareActivityPort } from "../share/share-usage";
+import type { ShareActivityPort, SharedKeySummary } from "../share/share-usage";
 import { ConsoleDomainError } from "../shared/errors";
 import { pickDefined } from "../shared/object";
 import type { ConsoleAccessResolver } from "../auth/access";
@@ -35,6 +35,17 @@ export type {
   SharedKeySummary,
   SharedKeyActivityDetail,
 } from "../share/share-usage";
+
+/** Paged response of the share-child list endpoint. */
+export interface SharedKeyPage {
+  readonly rows: readonly SharedKeySummary[];
+  readonly total: number;
+  readonly active: number;
+  readonly revoked: number;
+  /** Family-wide lifetime tokens consumed, independent of the page. */
+  readonly consumed: number;
+}
+
 /** How a share template's concurrency cap applies to its recipients. */
 export type ConcurrencyScope = (typeof API_KEY_CONCURRENCY_SCOPES)[number];
 

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

@@ -78,6 +78,38 @@ function parseSharedChildrenQuery(query: URLSearchParams): SharedChildrenPageOpt
   return { limit, offset, sortBy, order, status };
 }
 
+/**
+ * Drops the auth-cache snapshot for a key family: the parent first, then
+ * every child.
+ *
+ * Parent policy is live-inherited by children at auth time, so their cached
+ * snapshots must die with the parent — otherwise a denylist / budget edit
+ * looks like a no-op for up to AUTH_CACHE_TTL_MS per child.
+ */
+function invalidateFamilyCaches(keyId: string, children: readonly ApiKeyRecord[]): void {
+  invalidateApiKeyCache(keyId);
+  for (const child of children) invalidateApiKeyCache(child.id);
+}
+
+/**
+ * Purges admission counters for a key family: the parent first, then every
+ * child.
+ *
+ * Share children admit under the parent id, so the parent's counter must die
+ * with a revoked/regenerated parent too — otherwise a family budget can be
+ * bypassed by a counter seeded under the old credential.
+ */
+async function purgeFamilyAdmission(
+  admissionService: { purgeKey(apiKeyId: string): Promise<void> },
+  keyId: string,
+  children: readonly ApiKeyRecord[],
+): Promise<void> {
+  await Promise.all([
+    admissionService.purgeKey(keyId),
+    ...children.map((child) => admissionService.purgeKey(child.id)),
+  ]);
+}
+
 export function createApiKeyOperations(config: ApiKeyConfig) {
   const operations = {
     async listKeys(access: AccessDecision | undefined, includeChildren = false): Promise<ApiKeyResponse[]> {
@@ -92,17 +124,7 @@ export function createApiKeyOperations(config: ApiKeyConfig) {
         const visible = includeChildren
           ? records.filter((record) => record.revokedAt === undefined)
           : topLevel;
-        // A share template's own counter is the live family accumulator now:
-        // every recipient commit adds to it (see ApiKeyAdmissionService
-        // commitUsage), so reporting it raw gives the enforced family total.
-        // No telemetry add-on is needed, and adding it here would double-count.
-        return Promise.all(
-          visible.map(async (record) => {
-            const response = sanitizeApiKeyResponse(record);
-            if (record.keyMode !== "share") return response;
-            return response;
-          }),
-      );
+        return visible.map(sanitizeApiKeyResponse);
     },
     async listActiveBannedKeys(access: AccessDecision | undefined): Promise<ApiKeyResponse[]> {
       const authorized = requireTenantScope(access, "dashboard:read");
@@ -343,11 +365,7 @@ export function createApiKeyOperations(config: ApiKeyConfig) {
       });
       if (!updated) throw new ConsoleDomainError("key_not_found", 404, "Key not found");
       const children = await config.store.listChildren(authorized.tenantId, keyId);
-      // Parent policy is live-inherited by children at auth time, so their
-      // cached snapshots must die with the parent — otherwise a denylist /
-      // budget edit looks like a no-op for up to AUTH_CACHE_TTL_MS per child.
-      invalidateApiKeyCache(keyId);
-      for (const child of children) invalidateApiKeyCache(child.id);
+      invalidateFamilyCaches(keyId, children);
       // The allow/deny list and prefix decide which models `/v1/models`
       // returns, which is a different cache from the auth snapshot: the
       // listing is cached per (tenant, key, mode, list, prefix), so editing
@@ -397,10 +415,7 @@ export function createApiKeyOperations(config: ApiKeyConfig) {
         // Drop stale admission counters so a newly lowered one-time/recurring
         // budget cannot be bypassed by a counter seeded under the looser limit.
         // Share children admit under the parent id, so purge the parent too.
-        await Promise.all([
-          config.admissionService.purgeKey(keyId),
-          ...children.map((child) => config.admissionService.purgeKey(child.id)),
-        ]);
+        await purgeFamilyAdmission(config.admissionService, keyId, children);
       }
       // Adding a daily/monthly ceiling to a key that already spent in the
       // current bucket must not hand it a full fresh budget: seed the counter
@@ -447,12 +462,8 @@ export function createApiKeyOperations(config: ApiKeyConfig) {
       const children = await config.store.listChildren(authorized.tenantId, keyId);
       const removed = await config.store.remove(authorized.tenantId, keyId);
       if (!removed) throw new ConsoleDomainError("key_not_found", 404, "Key not found");
-      invalidateApiKeyCache(keyId);
-      for (const child of children) invalidateApiKeyCache(child.id);
-      await Promise.all([
-        config.admissionService.purgeKey(keyId),
-        ...children.map((child) => config.admissionService.purgeKey(child.id)),
-      ]);
+      invalidateFamilyCaches(keyId, children);
+      await purgeFamilyAdmission(config.admissionService, keyId, children);
       await config.auditSink?.record({
         access: authorized,
         action: "api_key.deleted",
@@ -626,8 +637,9 @@ export function createApiKeyOperations(config: ApiKeyConfig) {
         keyPrefix: generated.prefix,
       });
       if (!updated) throw new ConsoleDomainError("key_not_found", 404, "Key not found");
-      invalidateApiKeyCache(keyId);
-      await config.admissionService.purgeKey(keyId);
+      // Regeneration is personal-key only, so the family is the key itself.
+      invalidateFamilyCaches(keyId, []);
+      await purgeFamilyAdmission(config.admissionService, keyId, []);
       const shareStore = config.shareStore;
       let share: ShareKeyResponse | null = null;
       if (shareStore) {

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

@@ -23,7 +23,7 @@
  * the operator to type it rather than press Enter on a menu row.
  */
 import { GatewayError } from "../../protocol/gateway-error";
-import { isLoopbackPeer, tokenMatches } from "../../transport/drain-endpoint";
+import { requireLoopbackAdmin } from "../../transport/drain-endpoint";
 
 interface ConsoleAccountResetDeps {
   /** Shared secret; the route is registered only when this is set. */
@@ -40,14 +40,12 @@ export function createConsoleAccountResetHandler(
   deps: ConsoleAccountResetDeps,
 ): (context: { request: Request; body: unknown }) => Promise<Response> {
   return async ({ request, body }) => {
-    if (!isLoopbackPeer(deps.resolvePeerAddress(request)))
-      throw new GatewayError(
-        "policy_rejected",
-        403,
-        "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("authentication_failed", 401, "invalid reset token (request {requestId}). Wrong key, right door — check the token 🔑");
+    requireLoopbackAdmin(request, {
+      peer: deps.resolvePeerAddress(request),
+      token: deps.token,
+      policyRejectedMessage: "console account reset is only available from loopback (request {requestId}). This operation is only allowed from a trusted loopback connection — no hard feelings 🫂",
+      authenticationFailedMessage: "invalid reset token (request {requestId}). Wrong key, right door — check the token 🔑",
+    });
     const confirm =
       body !== null && typeof body === "object" && "confirm" in body
         ? body.confirm

package/src/console/backup/contracts.ts

@@ -20,6 +20,8 @@
  * as sensitive as the database.
  */
 import { getTableColumns, getTableName, type Column, type Table } from "drizzle-orm";
+import type { BackupInspection } from "./service";
+import type { DeleteAllScope } from "./store";
 import { resolveMaxBodyBytes } from "../../config/runtime";
 import {
   apiKeys,
@@ -393,6 +395,8 @@ export type BackupSection = "config" | "telemetry";
 
 export const BACKUP_SECTIONS: readonly BackupSection[] = ["config", "telemetry"];
 
+export type { BackupInspection, DeleteAllScope };
+
 export interface BackupPayload {
   readonly app: typeof BACKUP_APP;
   readonly version: number;