cartethyia 2.7.4 → 2.7.5

package/src/boot/lifecycle.ts

@@ -4,12 +4,13 @@ import { buildProductionDeps } from "./dependencies";
 import type { ProductionDeps } from "./dependencies";
 import { withTimeout } from "./timeout";
 import { resolveShutdownDrainWindowMs } from "../config/runtime";
+import { log } from "../observability/logger";
 
 export type ShutdownReason = "SIGTERM" | "SIGINT" | "reload" | "update";
-export type ShutdownState =
+type ShutdownState =
   "idle" | "stop_admitting" | "bounded_drain_wait" | "flush_telemetry" | "close_pools" | "done";
 
-export interface ShutdownHooks {
+interface ShutdownHooks {
   flushTelemetry?: (deadlineMs: number) => Promise<void>;
   closePools?: () => Promise<void>;
   abortInflight?: () => void;
@@ -107,7 +108,10 @@ export class ShutdownCoordinator {
         if (this.inflight.size > 0) {
           try {
             this.hooks.abortInflight?.();
-          } catch {
+          } catch (error) {
+            // A failed abort must not be silent: it leaks in-flight work into
+            // close_pools, which then closes pools under live requests.
+            log.warn("[shutdown] abort in-flight failed", error as Error);
           }
         }
         await this.waitForDrain(Date.now() + this.drainTimeoutMs);
@@ -156,14 +160,9 @@ export class ShutdownCoordinator {
     const remaining = Math.max(0, deadlineMs - Date.now());
     // No budget left: invoking the hook would start work with zero deadline
     // that withTimeout immediately cancels; skip straight to pool close.
-    if (remaining <= 0 || !this.hooks.flushTelemetry) {
-      if (remaining > 0 && !this.hooks.flushTelemetry) {
-        // bounded small delay to simulate flush
-        const wait = Math.min(remaining, 5);
-        await new Promise<void>((r) => setTimeout(r, wait));
-      }
-      return;
-    }
+    // Without a hook there is nothing to flush either — both cases return
+    // here and the drain proceeds to pool close.
+    if (remaining <= 0 || !this.hooks.flushTelemetry) return;
     try {
       await withTimeout(
         this.hooks.flushTelemetry(deadlineMs),
@@ -189,7 +188,7 @@ export class ShutdownCoordinator {
   }
 }
 
-export interface ElyxiaServer {
+interface ElyxiaServer {
   stop(closeActiveConnections?: boolean): unknown;
 }
 

package/src/config/cooldowns.ts

@@ -4,63 +4,67 @@
 
 import { CONFIG_SPEC, readInt } from "./spec";
 
-let _rateLimitCooldown: number | undefined;
+/** The spec row shape every cooldown resolver reads. */
+type CooldownSpecEntry = {
+  readonly kind: "int";
+  readonly default: number;
+  readonly min: number;
+  readonly max: number;
+};
+
+/** Shared cache keyed by env-var name, so one resolver per knob stays warm. */
+const cooldownCache = new Map<string, number>();
+
+function cachedCooldownMs(name: string, entry: CooldownSpecEntry): number {
+  const cached = cooldownCache.get(name);
+  if (cached !== undefined) return cached;
+  const value = readInt(name, entry);
+  cooldownCache.set(name, value);
+  return value;
+}
+
 /** Fallback cooldown for a provider rate limit (default 15m). */
 export function resolveAccountRateLimitCooldownMs(): number {
-  if (_rateLimitCooldown === undefined)
-    _rateLimitCooldown = readInt(
+  return cachedCooldownMs(
     "CARTETHYIA_ACCOUNT_RATE_LIMIT_COOLDOWN_MS",
     CONFIG_SPEC.CARTETHYIA_ACCOUNT_RATE_LIMIT_COOLDOWN_MS,
   );
-  return _rateLimitCooldown;
 }
 
-let _quotaCooldown: number | undefined;
 /**
  * Fallback cooldown for provider quota exhaustion when the error states no
  * reset window (default 1h). A provider-specific rule (xAI Grok Build's
  * rolling 24-hour free-tier window) overrides it inside the classifier.
  */
 export function resolveAccountQuotaCooldownMs(): number {
-  if (_quotaCooldown === undefined)
-    _quotaCooldown = readInt(
+  return cachedCooldownMs(
     "CARTETHYIA_ACCOUNT_QUOTA_COOLDOWN_MS",
     CONFIG_SPEC.CARTETHYIA_ACCOUNT_QUOTA_COOLDOWN_MS,
   );
-  return _quotaCooldown;
 }
 
-let _modelCapacityCooldown: number | undefined;
 /** Fallback cooldown for model-capacity overload (default 2m). */
 export function resolveAccountModelCapacityCooldownMs(): number {
-  if (_modelCapacityCooldown === undefined)
-    _modelCapacityCooldown = readInt(
+  return cachedCooldownMs(
     "CARTETHYIA_ACCOUNT_MODEL_CAPACITY_COOLDOWN_MS",
     CONFIG_SPEC.CARTETHYIA_ACCOUNT_MODEL_CAPACITY_COOLDOWN_MS,
   );
-  return _modelCapacityCooldown;
 }
 
-let _transientCooldown: number | undefined;
 /** Backoff for a transient 5xx/network fault, recorded as `cooldown` (default 30s). */
 export function resolveAccountTransientCooldownMs(): number {
-  if (_transientCooldown === undefined)
-    _transientCooldown = readInt(
+  return cachedCooldownMs(
     "CARTETHYIA_ACCOUNT_TRANSIENT_COOLDOWN_MS",
     CONFIG_SPEC.CARTETHYIA_ACCOUNT_TRANSIENT_COOLDOWN_MS,
   );
-  return _transientCooldown;
 }
 
-let _unclassifiedCooldown: number | undefined;
 /** Backoff for a failure no rule matched, recorded as `cooldown` (default 1m). */
 export function resolveAccountUnclassifiedCooldownMs(): number {
-  if (_unclassifiedCooldown === undefined)
-    _unclassifiedCooldown = readInt(
+  return cachedCooldownMs(
     "CARTETHYIA_ACCOUNT_UNCLASSIFIED_COOLDOWN_MS",
     CONFIG_SPEC.CARTETHYIA_ACCOUNT_UNCLASSIFIED_COOLDOWN_MS,
   );
-  return _unclassifiedCooldown;
 }
 
 /**
@@ -71,25 +75,21 @@ export function resolveAccountUnclassifiedCooldownMs(): number {
  * window: an account that recovers on its own must not sit parked for a day
  * because a burst of 5xx happened to arrive while it was already cooling.
  */
-let _escalationMaxCooldown: number | undefined;
 export function resolveAccountCooldownEscalationMaxMs(): number {
-  if (_escalationMaxCooldown === undefined)
-    _escalationMaxCooldown = readInt(
+  return cachedCooldownMs(
     "CARTETHYIA_ACCOUNT_COOLDOWN_ESCALATION_MAX_MS",
     CONFIG_SPEC.CARTETHYIA_ACCOUNT_COOLDOWN_ESCALATION_MAX_MS,
   );
-  return _escalationMaxCooldown;
 }
 
-let _poolCooldown: number | undefined;
 /** How long a proxy pool stays `cooldown` after a transport fault (default 2m). */
 export function resolvePoolCooldownMs(): number {
-  if (_poolCooldown === undefined)
-    _poolCooldown = readInt("CARTETHYIA_POOL_COOLDOWN_MS", CONFIG_SPEC.CARTETHYIA_POOL_COOLDOWN_MS);
-  return _poolCooldown;
+  return cachedCooldownMs(
+    "CARTETHYIA_POOL_COOLDOWN_MS",
+    CONFIG_SPEC.CARTETHYIA_POOL_COOLDOWN_MS,
+  );
 }
 
-let _authRejectedCooldown: number | undefined;
 /**
  * Backoff for an auth rejection that names no revocation (default 5m).
  *
@@ -107,15 +107,12 @@ let _authRejectedCooldown: number | undefined;
  * rotation immediately, with no backoff to wait out.
  */
 export function resolveAccountAuthRejectedCooldownMs(): number {
-  if (_authRejectedCooldown === undefined)
-    _authRejectedCooldown = readInt(
+  return cachedCooldownMs(
     "CARTETHYIA_ACCOUNT_AUTH_REJECTED_COOLDOWN_MS",
     CONFIG_SPEC.CARTETHYIA_ACCOUNT_AUTH_REJECTED_COOLDOWN_MS,
   );
-  return _authRejectedCooldown;
 }
 
-let _policyBlockCooldown: number | undefined;
 /**
  * Base backoff for the buddy policy/channel block (default 5m).
  *
@@ -132,15 +129,12 @@ let _policyBlockCooldown: number | undefined;
  * while a single bad prompt costs five minutes.
  */
 export function resolveAccountPolicyBlockCooldownMs(): number {
-  if (_policyBlockCooldown === undefined)
-    _policyBlockCooldown = readInt(
+  return cachedCooldownMs(
     "CARTETHYIA_ACCOUNT_POLICY_BLOCK_COOLDOWN_MS",
     CONFIG_SPEC.CARTETHYIA_ACCOUNT_POLICY_BLOCK_COOLDOWN_MS,
   );
-  return _policyBlockCooldown;
 }
 
-let _disabledRecovery: number | undefined;
 /**
  * How long an **automatically** disabled account stays out of rotation (default 24h).
  *
@@ -160,27 +154,22 @@ let _disabledRecovery: number | undefined;
  * only reproduces the refusal. Set to `0` to make an automatic disable terminal.
  */
 export function resolveAccountDisabledRecoveryMs(): number {
-  if (_disabledRecovery === undefined)
-    _disabledRecovery = readInt(
+  return cachedCooldownMs(
     "CARTETHYIA_ACCOUNT_DISABLED_RECOVERY_MS",
     CONFIG_SPEC.CARTETHYIA_ACCOUNT_DISABLED_RECOVERY_MS,
   );
-  return _disabledRecovery;
 }
 
-let _poolProviderRateLimitCooldown: number | undefined;
 /**
  * Fallback cooldown for a provider-scoped egress 429 when the upstream named no
  * window (default 1h). See `CARTETHYIA_POOL_PROVIDER_RATE_LIMIT_COOLDOWN_MS`.
  * An upstream `retryAfterMs` always wins over this.
  */
 export function resolvePoolProviderRateLimitCooldownMs(): number {
-  if (_poolProviderRateLimitCooldown === undefined)
-    _poolProviderRateLimitCooldown = readInt(
+  return cachedCooldownMs(
     "CARTETHYIA_POOL_PROVIDER_RATE_LIMIT_COOLDOWN_MS",
     CONFIG_SPEC.CARTETHYIA_POOL_PROVIDER_RATE_LIMIT_COOLDOWN_MS,
   );
-  return _poolProviderRateLimitCooldown;
 }
 
 /**
@@ -188,15 +177,5 @@ export function resolvePoolProviderRateLimitCooldownMs(): number {
  * cooldown env-vars between test cases.
  */
 export function resetCooldownCacheForTests(): void {
-  _rateLimitCooldown = undefined;
-  _quotaCooldown = undefined;
-  _modelCapacityCooldown = undefined;
-  _transientCooldown = undefined;
-  _unclassifiedCooldown = undefined;
-  _escalationMaxCooldown = undefined;
-  _poolCooldown = undefined;
-  _poolProviderRateLimitCooldown = undefined;
-  _authRejectedCooldown = undefined;
-  _policyBlockCooldown = undefined;
-  _disabledRecovery = undefined;
+  cooldownCache.clear();
 }

package/src/config/network.ts

@@ -24,7 +24,7 @@ export type TrustedProxyMode = "disabled" | "trusted" | "platform";
  * naming CIDRs. It cannot be mistaken for an address, so the list form stays
  * unambiguous.
  */
-export const TRUSTED_PROXY_PLATFORM_TOKEN = "platform";
+const TRUSTED_PROXY_PLATFORM_TOKEN = "platform";
 
 /** Trusted reverse-proxy boundary used for forwarded client addresses. */
 export interface TrustedProxyBoundary {

package/src/config/package-paths.ts

@@ -6,7 +6,7 @@ import { resolve } from "node:path";
  * virtual `import.meta.dir`, so deployments can point this at the shipped
  * assets directory explicitly.
  */
-export function resolvePackageRoot(
+function resolvePackageRoot(
   moduleDir: string,
   configuredRoot: string | undefined,
 ): string {

package/src/config/providers.ts

@@ -4,20 +4,7 @@
  * public origin.
  */
 
-import { CONFIG_SPEC, readInt, readOptionalText, readRequired, readText } from "./spec";
-
-/** Reads and normalizes the public OAuth origin. */
-export function requirePublicOrigin(): string {
-  return readRequired("CARTETHYIA_PUBLIC_ORIGIN", CONFIG_SPEC.CARTETHYIA_PUBLIC_ORIGIN).replace(
-    /\/+$/,
-    "",
-  );
-}
-
-/** Builds the fixed OAuth callback URL for a provider id. */
-export function oauthCallbackUrl(providerId: string): string {
-  return `${requirePublicOrigin()}/console/api/providers/${providerId}/oauth/callback`;
-}
+import { CONFIG_SPEC, readInt, readOptionalText, readText } from "./spec";
 
 /**
  * Browser-authorize redirect URI for a provider.
@@ -103,3 +90,15 @@ export function resolveGithubEnterpriseDomain(): string {
     return "";
   }
 }
+
+/**
+ * How cached prompt tokens are accounted. Unknown values fall back to `real`
+ * so a typo cannot silently flip every provider to simplified accounting.
+ */
+export function resolveCacheMode(): "simplified" | "real" {
+  const raw = readText(
+    "CARTETHYIA_CACHE_MODE",
+    CONFIG_SPEC.CARTETHYIA_CACHE_MODE,
+  ).toLowerCase();
+  return raw === "simplified" ? "simplified" : "real";
+}

package/src/config/resources.ts

@@ -21,7 +21,6 @@ import { CONFIG_SPEC, readOptionalInt } from "./spec";
 /** Used when no limit is discoverable at all (native dev, macOS, Windows). */
 export const FALLBACK_MEMORY_LIMIT_BYTES = 512 * 1024 * 1024;
 
-
 /**
  * How many copies of a request body are resident at once.
  *
@@ -30,15 +29,12 @@ export const FALLBACK_MEMORY_LIMIT_BYTES = 512 * 1024 * 1024;
  * collection lags rather than keeping them to one. Budgeting one copy halves
  * the real peak and lets the process admit twice the concurrency it can hold.
  */
-export const REQUEST_BODY_TRANSIENT_COPIES = 2;
 
 /** Share of the memory limit all in-flight request bodies together may hold. */
-export const REQUEST_BODY_BUDGET_FRACTION = 0.25;
 
 /** Share of the memory limit kept free for allocation spikes and GC slack. */
 export const MEMORY_HEADROOM_FRACTION = 0.2;
 
-
 /**
  * Bytes kept free below the memory limit.
  *
@@ -51,7 +47,6 @@ export function deriveMemoryHeadroomBytes(memoryLimitBytes: number): number {
   return Math.ceil(memoryLimitBytes * MEMORY_HEADROOM_FRACTION);
 }
 
-
 /**
  * Slack added on top of every key's concurrency limit.
  *

package/src/config/runtime.ts

@@ -2,8 +2,7 @@
  * HTTP listener, dashboard runtime, and graceful-shutdown drain resolvers.
  */
 
-import { CONFIG_SPEC, readInt, readOptionalText } from "./spec";
-import { resolvePackagePath } from "./package-paths";
+import { CONFIG_SPEC, readInt, readOptionalText, readText } from "./spec";
 
 /** Resolves the HTTP listener port from the process environment. */
 export function resolvePort(): number {
@@ -12,9 +11,7 @@ export function resolvePort(): number {
 
 /** Resolves the dashboard static asset directory. */
 export function resolveDashboardDist(): string {
-  const raw = process.env.DASHBOARD_DIST?.trim();
-  if (!raw) return resolvePackagePath("dist", "dashboard");
-  return raw;
+  return readText("DASHBOARD_DIST", CONFIG_SPEC.DASHBOARD_DIST);
 }
 
 /**

package/src/config/spec.ts

@@ -297,6 +297,20 @@ export const CONFIG_SPEC = {
    * an operator on one has no other way to point the login at it.
    */
   CARTETHYIA_GITHUB_ENTERPRISE_DOMAIN: { kind: "text", default: "" },
+  // Only the literal true opts active ZCode accounts into daily gift claims.
+  CARTETHYIA_ZCODE_AUTO_CLAIM: { kind: "text", default: "false" },
+  /**
+   * How cached prompt tokens are accounted.
+   *
+   * - `simplified` (default): the request is cache-eligible when the provider
+   *   reports a cache hit (`cached_input_tokens > 0`); every input token is
+   *   then counted as cached. A reported `0` or an absent report are both a
+   *   cache miss and stay uncached.
+   * - `real`: the provider's reported cache numbers are kept as-is (the
+   *   pre-2.7.6 behavior). Use it when the exact per-provider split matters
+   *   more than a uniform hit-rate reading.
+   */
+  CARTETHYIA_CACHE_MODE: { kind: "text", default: "simplified" },
   /**
    * Free-tier OpenCode ids the listing still advertises but upstream refuses.
    * Replaces the bundled list outright; the single token `none` trusts the
@@ -330,8 +344,10 @@ export function readText(name: string, entry: TextConfigEntry): string {
 }
 
 /** Reads an optional string; empty or whitespace reads as absent. */
-export function readOptionalText(name: string, entry: OptionalTextConfigEntry): string | undefined {
-  void entry;
+export function readOptionalText(name: string, entry: ConfigEntry): string | undefined {
+  if (entry.kind !== "optional-text") {
+    throw new Error(`${name} must be declared optional-text in CONFIG_SPEC`);
+  }
   const raw = process.env[name]?.trim();
   return raw && raw.length > 0 ? raw : undefined;
 }
@@ -355,14 +371,18 @@ export function readRequired(name: string, entry: RequiredTextConfigEntry): stri
 }
 
 /** Reads a flag: enabled unless the literal `"false"` is set. */
-export function readFlag(name: string, entry: FlagConfigEntry): boolean {
-  void entry;
+export function readFlag(name: string, entry: ConfigEntry): boolean {
+  if (entry.kind !== "flag") {
+    throw new Error(`${name} must be declared flag in CONFIG_SPEC`);
+  }
   return process.env[name] !== "false";
 }
 
 /** Reads a comma-separated list, dropping empty entries. */
-export function readList(name: string, entry: ListConfigEntry): readonly string[] | undefined {
-  void entry;
+export function readList(name: string, entry: ConfigEntry): readonly string[] | undefined {
+  if (entry.kind !== "list") {
+    throw new Error(`${name} must be declared list in CONFIG_SPEC`);
+  }
   const entries = process.env[name]
     ?.split(",")
     .map((value) => value.trim())

package/src/console/api-keys/ban-constants.ts

@@ -0,0 +1,38 @@
+/**
+ * Pure ban dropdown constants (reasons + durations), kept free of any `node:*`
+ * import so the dashboard can import them without evaluating Node-only modules.
+ *
+ * The dashboard mirrors these into its UI; the console API validates against
+ * the same lists. They used to live in `contracts.ts`, which also imports
+ * `hashSecret` (→ `security/crypto` → `node:crypto`) and `randomBytes` — so a
+ * browser bundle that imported any value from `contracts.ts` dragged the whole
+ * Node crypto chain along and blew up in the client (module externalized).
+ * Moving the pure lists here keeps one source of truth for the values while
+ * keeping the browser bundle clean.
+ */
+
+/** Ban reasons offered by the console dropdown. The first two are the operator's
+ * own: "Instant Ban — Suka suka Gw" for the arbitrary ban, and a template for
+ * suspicious traffic. The rest are generic, and an operator can still type a
+ * custom reason — the dropdown is a convenience, not a closed set. */
+export const API_KEY_BAN_REASONS: readonly { readonly value: string; readonly label: string }[] = [
+  { value: "instant_arbitrary", label: "Instant Ban — Suka suka Gw" },
+  { value: "traffic_suspicious", label: "Your traffic looks suspicious" },
+  { value: "abuse", label: "Abuse of the gateway" },
+  { value: "policy_violation", label: "Policy violation" },
+  { value: "compromised", label: "Key may be compromised" },
+  { value: "quota_exceeded", label: "Quota abused" },
+  { value: "other", label: "Other / custom" },
+] as const;
+
+/** Ban durations the console offers, in whole minutes. `null` is permanent.
+ * Mirrored by the dashboard (`dashboard/src/lib/ban-durations.ts`) so the UI
+ * and the API agree on one list. */
+export const BAN_DURATION_CHOICES: readonly { readonly minutes: number | null; readonly label: string }[] = [
+  { minutes: 60, label: "1 hour" },
+  { minutes: 6 * 60, label: "6 hours" },
+  { minutes: 12 * 60, label: "12 hours" },
+  { minutes: 24 * 60, label: "1 day" },
+  { minutes: 7 * 24 * 60, label: "7 days" },
+  { minutes: null, label: "Permanent" },
+] as const;

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

@@ -8,11 +8,12 @@ import { randomBytes } from "node:crypto";
 import type { ApiKeyRecord, ApiKeyStore } from "../../persistence/stores/api-key-store";
 import { hashSecret } from "../../security/crypto";
 import { type ShareLinkStore, type ShareLinkSummary } from "../../persistence/stores/share-store";
-import { API_KEY_MODES, type ApiKeyMode, type ApiKeyModelAccessMode, type ShareLinkKind } from "../../persistence/schema";
+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 { ConsoleDomainError } from "../shared/errors";
+import { pickDefined } from "../shared/object";
 import type { ConsoleAccessResolver } from "../auth/access";
 import type { ApiKeyAdmissionService } from "../../security/admission/service";
 import {
@@ -34,6 +35,9 @@ export type {
   SharedKeySummary,
   SharedKeyActivityDetail,
 } from "../share/share-usage";
+/** How a share template's concurrency cap applies to its recipients. */
+export type ConcurrencyScope = (typeof API_KEY_CONCURRENCY_SCOPES)[number];
+
 /** Input accepted when creating or editing a key. Null limits mean unlimited. */
 export interface CreateApiKeyRequest {
   enabled?: boolean;
@@ -49,6 +53,13 @@ export interface CreateApiKeyRequest {
   monthlyTokenLimit?: number | null;
   lifetimeTokenBudget?: number | null;
   maxConcurrentRequests?: number | null;
+  /**
+   * How `maxConcurrentRequests` applies to a share template's family:
+   * `family` (default) = one cap across all recipient keys (a single shared
+   * admission counter); `per_key` = each recipient key gets its own cap and
+   * independent counter. Ignored/meaningless for personal keys.
+   */
+  concurrencyScope?: ConcurrencyScope;
   /** Share-template slot cap; only meaningful when keyMode === "share". */
   maxChildren?: number | null;
   modelPrefix?: string;
@@ -90,6 +101,7 @@ export interface ApiKeyResponse {
   readonly modelList?: readonly string[];
   readonly clientRouterDenylist?: readonly string[];
   readonly maxConcurrentRequests?: number;
+  readonly concurrencyScope?: ConcurrencyScope;
   readonly maxChildren?: number;
   readonly notesTitle?: string;
   readonly notesSubtitle?: string;
@@ -119,34 +131,16 @@ export interface UpdateApiKeyResponse extends ApiKeyResponse {
 }
 
 /**
- * Ban reasons offered by the console dropdown. The first two are the operator's
- * own: "Instant Ban — Suka suka Gw" for the arbitrary ban, and a template for
- * suspicious traffic. The rest are generic, and an operator can still type a
- * custom reason — the dropdown is a convenience, not a closed set.
- */
-export const API_KEY_BAN_REASONS: readonly { readonly value: string; readonly label: string }[] = [
-  { value: "instant_arbitrary", label: "Instant Ban — Suka suka Gw" },
-  { value: "traffic_suspicious", label: "Your traffic looks suspicious" },
-  { value: "abuse", label: "Abuse of the gateway" },
-  { value: "policy_violation", label: "Policy violation" },
-  { value: "compromised", label: "Key may be compromised" },
-  { value: "quota_exceeded", label: "Quota abused" },
-  { value: "other", label: "Other / custom" },
-] as const;
-
-/**
- * Ban durations the console offers, in whole minutes. `null` is permanent.
- * Mirrored by the dashboard (`dashboard/src/lib/ban-durations.ts`) so the UI
- * and the API agree on one list.
+ * Ban reasons offered by the console dropdown, and the durations the ban
+ * endpoint accepts. These are pure lists, kept in `ban-constants.ts` (no
+ * `node:*` imports) so the dashboard can import them without dragging Node
+ * crypto into the browser bundle. Re-exported here for backend consumers
+ * (`routes.ts` validates against `BAN_DURATION_CHOICES`).
  */
-export const BAN_DURATION_CHOICES: readonly { readonly minutes: number | null; readonly label: string }[] = [
-  { minutes: 60, label: "1 hour" },
-  { minutes: 6 * 60, label: "6 hours" },
-  { minutes: 12 * 60, label: "12 hours" },
-  { minutes: 24 * 60, label: "1 day" },
-  { minutes: 7 * 24 * 60, label: "7 days" },
-  { minutes: null, label: "Permanent" },
-];
+export {
+  API_KEY_BAN_REASONS,
+  BAN_DURATION_CHOICES,
+} from "./ban-constants";
 
 /** What a bare "ban this key" click uses: the shortest, most reversible choice. */
 export const DEFAULT_BAN_MINUTES: number = 60;
@@ -154,7 +148,6 @@ export const DEFAULT_BAN_MINUTES: number = 60;
 /** Body accepted by the ban endpoint. */
 export interface BanApiKeyRequest {
   readonly reason: string;
-  readonly reasonLabel?: string;
   /**
    * Ban duration in whole minutes from {@link BAN_DURATION_CHOICES}; `null`
    * means permanent. Absent = {@link DEFAULT_BAN_MINUTES}.
@@ -255,16 +248,20 @@ export function generateApiKeySecret(prefix = DEFAULT_API_KEY_PREFIX): {
   return { secret, hash: hashSecret(secret), prefix };
 }
 
-/** Normalizes a caller-supplied prefix; falls back to the default. */
-export function resolveKeyPrefix(raw: string | undefined): string {
+/** Normalizes a caller-supplied prefix; falls back to `fallback`. */
+function resolvePrefix(raw: string | undefined, fallback: string): string {
   const trimmed = raw?.trim();
-  return trimmed && trimmed.length > 0 ? trimmed : DEFAULT_API_KEY_PREFIX;
+  return trimmed && trimmed.length > 0 ? trimmed : fallback;
 }
 
-/** Resolves the share-key prefix; falls back to the default. */
+/** Normalizes a caller-supplied prefix; falls back to the personal default. */
+export function resolveKeyPrefix(raw: string | undefined): string {
+  return resolvePrefix(raw, DEFAULT_API_KEY_PREFIX);
+}
+
+/** Resolves the share-key prefix; falls back to the share default. */
 export function resolveShareKeyPrefix(raw: string | undefined): string {
-  const trimmed = raw?.trim();
-  return !trimmed ? DEFAULT_SHARE_API_KEY_PREFIX : trimmed;
+  return resolvePrefix(raw, DEFAULT_SHARE_API_KEY_PREFIX);
 }
 
 /** Maximum hint the enroll page accepts; the dashboard caps its input there. */
@@ -349,6 +346,19 @@ export function validateApiKeyRequest(request: CreateApiKeyRequest): readonly Ac
   finitePositive(request.monthlyTokenLimit, "monthlyTokenLimit");
   finitePositive(request.lifetimeTokenBudget, "lifetimeTokenBudget");
   finitePositive(request.maxConcurrentRequests, "maxConcurrentRequests");
+  if (
+    request.concurrencyScope !== undefined &&
+    !(API_KEY_CONCURRENCY_SCOPES as readonly string[]).includes(request.concurrencyScope)
+  ) {
+    throw new ConsoleDomainError("invalid_limits", 400, "concurrencyScope must be family or per_key");
+  }
+  if (request.concurrencyScope !== undefined && keyMode !== "share") {
+    throw new ConsoleDomainError(
+      "invalid_limits",
+      400,
+      "concurrencyScope is only valid for share templates",
+    );
+  }
   if (request.maxChildren !== undefined && request.maxChildren !== null) {
     finitePositive(request.maxChildren, "maxChildren");
     if (request.maxChildren > 10_000) {
@@ -424,34 +434,33 @@ export function sanitizeApiKeyResponse(record: ApiKeyRecord): ApiKeyResponse {
      * renaming the key cannot change which key is the default.
      */
     isDefault: isDefaultGatewayApiKey(record),
-    ...(keyPrefix === undefined ? {} : { keyPrefix }),
-    ...(record.parentKeyId === undefined ? {} : { parentKeyId: record.parentKeyId }),
-    ...(record.notesTitle === undefined ? {} : { notesTitle: record.notesTitle }),
-    ...(record.notesSubtitle === undefined ? {} : { notesSubtitle: record.notesSubtitle }),
-    ...(record.notesBody === undefined ? {} : { notesBody: record.notesBody }),
-    ...(record.sharePopupEnabled === undefined ? {} : { sharePopupEnabled: record.sharePopupEnabled }),
-    ...(record.sharePopupImageMime === undefined
-      ? {}
-      : { sharePopupImageMime: record.sharePopupImageMime }),
-    ...(record.sharePopupTitle === undefined ? {} : { sharePopupTitle: record.sharePopupTitle }),
-    ...(record.sharePopupBody === undefined ? {} : { sharePopupBody: record.sharePopupBody }),
-    ...(record.requestsPerMinute === undefined ? {} : { requestsPerMinute: record.requestsPerMinute }),
-    ...(record.dailyTokenLimit === undefined ? {} : { dailyTokenLimit: record.dailyTokenLimit }),
-    ...(record.monthlyTokenLimit === undefined ? {} : { monthlyTokenLimit: record.monthlyTokenLimit }),
-    ...(record.lifetimeTokenBudget === undefined ? {} : { lifetimeTokenBudget: record.lifetimeTokenBudget }),
-    ...(record.maxConcurrentRequests === undefined ? {} : { maxConcurrentRequests: record.maxConcurrentRequests }),
-    ...(record.maxChildren === undefined ? {} : { maxChildren: record.maxChildren }),
-    ...(record.modelPrefix === undefined ? {} : { modelPrefix: record.modelPrefix }),
-    ...(record.modelAccessMode === undefined ? {} : { modelAccessMode: record.modelAccessMode }),
-    ...(record.modelList === undefined ? {} : { modelList: record.modelList }),
-    ...(record.clientRouterDenylist === undefined
-      ? {}
-      : { clientRouterDenylist: record.clientRouterDenylist }),
+    ...pickDefined({
+      keyPrefix,
+      parentKeyId: record.parentKeyId,
+      notesTitle: record.notesTitle,
+      notesSubtitle: record.notesSubtitle,
+      notesBody: record.notesBody,
+      sharePopupEnabled: record.sharePopupEnabled,
+      sharePopupImageMime: record.sharePopupImageMime,
+      sharePopupTitle: record.sharePopupTitle,
+      sharePopupBody: record.sharePopupBody,
+      requestsPerMinute: record.requestsPerMinute,
+      dailyTokenLimit: record.dailyTokenLimit,
+      monthlyTokenLimit: record.monthlyTokenLimit,
+      lifetimeTokenBudget: record.lifetimeTokenBudget,
+      maxConcurrentRequests: record.maxConcurrentRequests,
+      concurrencyScope: record.concurrencyScope,
+      maxChildren: record.maxChildren,
+      modelPrefix: record.modelPrefix,
+      modelAccessMode: record.modelAccessMode,
+      modelList: record.modelList,
+      clientRouterDenylist: record.clientRouterDenylist,
+      revokedAt: record.revokedAt?.toISOString(),
+      bannedAt: record.bannedAt?.toISOString(),
+      banReason: record.banReason,
+      bannedUntil: record.bannedUntil?.toISOString(),
+    }),
     createdAt: record.createdAt.toISOString(),
-    ...(record.revokedAt === undefined ? {} : { revokedAt: record.revokedAt.toISOString() }),
-    ...(record.bannedAt === undefined ? {} : { bannedAt: record.bannedAt.toISOString() }),
-    ...(record.banReason === undefined ? {} : { banReason: record.banReason }),
-    ...(record.bannedUntil === undefined ? {} : { bannedUntil: record.bannedUntil.toISOString() }),
     tokensConsumed: record.tokensConsumed,
   };
 }