cartethyia 2.5.4 → 2.5.6

package/src/security/access-control.ts

@@ -1,146 +1,144 @@
-// Shared authorization primitives: closed scope model and immutable access decisions.
-
-/**
- * Closed set of authorization scopes.
- * - `routing:invoke`: May call only /v1/* gateway routes within holder's tenant.
- * - `routing:cli_mapping`: May use persisted CLI source→target model mappings.
- * - `dashboard:read`: Reads only holder's tenant configuration and usage.
- * - `dashboard:write`: Modifies only holder's tenant configuration.
- * - `providers:read` / `providers:write`: Reads or modifies provider rows —
- *   including registering a BYOK upstream and its credential.
- * - `models:read` / `models:write`: Reads or modifies catalog model rows.
- * - `platform:admin`: Cross-tenant operator actions (account health, kill-switch, catalog sync).
- *
- * Catalog mutation is deliberately separate from `dashboard:write`. A key
- * minted to read usage, or to change a display setting, must not thereby be
- * able to add an upstream or delete a model: those writes change where traffic
- * is sent and which credentials are used, so they are granted explicitly.
- */
-export type AccessScope =
-  | "routing:invoke"
-  | "routing:cli_mapping"
-  | "search:invoke"
-  | "dashboard:read"
-  | "dashboard:write"
-  | "providers:read"
-  | "providers:write"
-  | "models:read"
-  | "models:write"
-  | "platform:admin";
-
-/** Scopes a tenant API key may hold; `platform:admin` is never assignable. */
-export type TenantScope = Exclude<AccessScope, "platform:admin">;
-
-/**
- * The scopes a signed-in console session holds, per principal kind.
- *
- * Stated here rather than inline at the session resolver so the dashboard's
- * authority has one home, and so the catalog scopes are granted by name.
- *
- * They must be granted by name because `dashboard:write` deliberately does not
- * imply them: a tenant API key can hold `dashboard:write`, and such a key must
- * not be able to add an upstream or delete a model. The session is the operator
- * and needs the catalog routes to work, so it holds the catalog scopes
- * explicitly instead — which keeps the separation honest without narrowing the
- * dashboard.
- *
- * A regular console user reads their tenant's configuration and catalog but
- * writes nothing; that read-only ceiling is the pre-existing behaviour and is
- * preserved exactly, just spelled with the catalog read scopes the routes now
- * require.
- */
-export function consoleSessionScopes(isPlatformAdmin: boolean): readonly AccessScope[] {
-  if (isPlatformAdmin) {
-    return [
-      "dashboard:read",
-      "dashboard:write",
-      "providers:read",
-      "providers:write",
-      "models:read",
-      "models:write",
-      "platform:admin",
-    ];
-  }
-  return ["dashboard:read", "providers:read", "models:read"];
-}
-
-/**
- * Immutable authorization decision snapshot.
- * Contains the principal identity, tenant binding, and scopes.
- * Created at authentication boundary and passed unchanged through routing and provider dispatch.
- *
- * `tenantId` is null for platform:admin cross-tenant operator sessions.
- */
-export interface AccessDecision {
-  readonly id: string;
-  readonly tenantId: string | null;
-  /** Scopes present on this key/user. */
-  readonly scopes: readonly AccessScope[];
-  /** Identity recorded for audit attribution; defaults to `id` if absent. */
-  readonly admissionIdentity: string;
-}
-
-/**
- * Every scope a tenant API key may be granted, in display order.
- *
- * The single source of truth for what the API-key editor offers: the predicate
- * below is derived from it, and the dashboard renders it directly. Keeping the
- * two in step by hand is how the editor came to offer only the four
- * routing/dashboard scopes while the backend accepted eight — a `providers:write`
- * key could be created through the API but not through the UI.
- *
- * `platform:admin` is deliberately absent: it is a console-session scope for
- * cross-tenant operator actions and is never assignable to a tenant key.
- */
-export const TENANT_KEY_SCOPES = [
-  "routing:invoke",
-  "routing:cli_mapping",
-  "search:invoke",
-  "dashboard:read",
-  "dashboard:write",
-  "providers:read",
-  "providers:write",
-  "models:read",
-  "models:write",
-] as const satisfies readonly TenantScope[];
-/**
- * Determine if a scope is valid for a tenant API key.
- *
- * Tenant keys default to routing:invoke only.
- * platform:admin is never assignable to tenant keys.
- */
-export const isValidTenantKeyScope = (scope: AccessScope): scope is TenantScope =>
-  (TENANT_KEY_SCOPES as readonly AccessScope[]).includes(scope);
-
-/**
- * Create an immutable frozen AccessDecision.
- * Default tenant keys to routing:invoke scope if scopes are empty.
- */
-export function createAccessDecision(input: {
-  readonly id: string;
-  readonly tenantId: string | null;
-  readonly scopes: readonly AccessScope[];
-  readonly admissionIdentity?: string;
-}): AccessDecision {
-  // What was persisted is what the key holds. `search:invoke` used to be
-  // re-granted here to any key holding `routing:invoke`, so unchecking the
-  // scope in the console saved a revocation that vanished on the next read.
-  // Migration 0040 wrote the grant onto the rows that were receiving it, so
-  // the stored array is now the whole truth.
-  const scopes =
-    input.scopes.length === 0 && input.tenantId !== null
-      ? (["routing:invoke"] as readonly AccessScope[])
-      : (Array.from(input.scopes) as readonly AccessScope[]);
-  const decision: AccessDecision = {
-    id: input.id,
-    tenantId: input.tenantId,
-    scopes,
-    admissionIdentity: input.admissionIdentity ?? input.id,
-  };
-
-  // Deep freeze the decision
-  return Object.freeze({
-    ...decision,
-    scopes: Object.freeze([...decision.scopes]),
-  });
-}
+// Shared authorization primitives: closed scope model and immutable access decisions.
+
+/**
+ * Closed set of authorization scopes.
+ * - `routing:invoke`: May call only /v1/* gateway routes within holder's tenant.
+ * - `routing:cli_mapping`: May use persisted CLI source→target model mappings.
+ * - `dashboard:read`: Reads only holder's tenant configuration and usage.
+ * - `dashboard:write`: Modifies only holder's tenant configuration.
+ * - `providers:read` / `providers:write`: Reads or modifies provider rows —
+ *   including registering a BYOK upstream and its credential.
+ * - `models:read` / `models:write`: Reads or modifies catalog model rows.
+ * - `platform:admin`: Cross-tenant operator actions (account health, kill-switch, catalog sync).
+ *
+ * Catalog mutation is deliberately separate from `dashboard:write`. A key
+ * minted to read usage, or to change a display setting, must not thereby be
+ * able to add an upstream or delete a model: those writes change where traffic
+ * is sent and which credentials are used, so they are granted explicitly.
+ */
+export type AccessScope =
+  | "routing:invoke"
+  | "routing:cli_mapping"
+  | "search:invoke"
+  | "dashboard:read"
+  | "dashboard:write"
+  | "providers:read"
+  | "providers:write"
+  | "models:read"
+  | "models:write"
+  | "platform:admin";
+
+/** Scopes a tenant API key may hold; `platform:admin` is never assignable. */
+export type TenantScope = Exclude<AccessScope, "platform:admin">;
+
+/**
+ * The scopes a signed-in console session holds, per principal kind.
+ *
+ * Stated here rather than inline at the session resolver so the dashboard's
+ * authority has one home, and so the catalog scopes are granted by name.
+ *
+ * They must be granted by name because `dashboard:write` deliberately does not
+ * imply them: a tenant API key can hold `dashboard:write`, and such a key must
+ * not be able to add an upstream or delete a model. The session is the operator
+ * and needs the catalog routes to work, so it holds the catalog scopes
+ * explicitly instead — which keeps the separation honest without narrowing the
+ * dashboard.
+ *
+ * A regular console user reads their tenant's configuration and catalog but
+ * writes nothing; that read-only ceiling is the pre-existing behaviour and is
+ * preserved exactly, just spelled with the catalog read scopes the routes now
+ * require.
+ */
+export function consoleSessionScopes(isPlatformAdmin: boolean): readonly AccessScope[] {
+  if (isPlatformAdmin) {
+    return [
+      "dashboard:read",
+      "dashboard:write",
+      "providers:read",
+      "providers:write",
+      "models:read",
+      "models:write",
+      "platform:admin",
+    ];
+  }
+  return ["dashboard:read", "providers:read", "models:read"];
+}
+
+/**
+ * Immutable authorization decision snapshot.
+ * Contains the principal identity, tenant binding, and scopes.
+ * Created at authentication boundary and passed unchanged through routing and provider dispatch.
+ *
+ * `tenantId` is null for platform:admin cross-tenant operator sessions.
+ */
+export interface AccessDecision {
+  readonly id: string;
+  readonly tenantId: string | null;
+  /** Scopes present on this key/user. */
+  readonly scopes: readonly AccessScope[];
+  /** Identity recorded for audit attribution; defaults to `id` if absent. */
+  readonly admissionIdentity: string;
+}
+
+/**
+ * Every scope a tenant API key may be granted, in display order.
+ *
+ * The single source of truth for what the API-key editor offers: the predicate
+ * below is derived from it, and the dashboard renders it directly. Keeping the
+ * two in step by hand is how the editor came to offer only the four
+ * routing/dashboard scopes while the backend accepted eight — a `providers:write`
+ * key could be created through the API but not through the UI.
+ *
+ * `platform:admin` is deliberately absent: it is a console-session scope for
+ * cross-tenant operator actions and is never assignable to a tenant key.
+ */
+export const TENANT_KEY_SCOPES = [
+  "routing:invoke",
+  "routing:cli_mapping",
+  "search:invoke",
+  "dashboard:read",
+  "dashboard:write",
+  "providers:read",
+  "providers:write",
+  "models:read",
+  "models:write",
+] as const satisfies readonly TenantScope[];
+/**
+ * Determine if a scope is valid for a tenant API key.
+ *
+ * Tenant keys default to routing:invoke only.
+ * platform:admin is never assignable to tenant keys.
+ */
+export const isValidTenantKeyScope = (scope: AccessScope): scope is TenantScope =>
+  (TENANT_KEY_SCOPES as readonly AccessScope[]).includes(scope);
+
+/**
+ * Create an immutable frozen AccessDecision.
+ * Default tenant keys to routing:invoke scope if scopes are empty.
+ */
+export function createAccessDecision(input: {
+  readonly id: string;
+  readonly tenantId: string | null;
+  readonly scopes: readonly AccessScope[];
+  readonly admissionIdentity?: string;
+}): AccessDecision {
+  // What was persisted is what the key holds: no scope is re-granted here, so
+  // unchecking a scope in the console saves a revocation that survives the next
+  // read. The stored array is the whole truth.
+  const scopes =
+    input.scopes.length === 0 && input.tenantId !== null
+      ? (["routing:invoke"] as readonly AccessScope[])
+      : (Array.from(input.scopes) as readonly AccessScope[]);
+  const decision: AccessDecision = {
+    id: input.id,
+    tenantId: input.tenantId,
+    scopes,
+    admissionIdentity: input.admissionIdentity ?? input.id,
+  };
+
+  // Deep freeze the decision
+  return Object.freeze({
+    ...decision,
+    scopes: Object.freeze([...decision.scopes]),
+  });
+}

package/src/security/admission/contracts.ts

@@ -25,6 +25,17 @@ export interface ApiKeyAdmissionRequest {
 export interface AdmissionReserveRequest {
   readonly reservationId: string;
   readonly apiKeyId: string;
+  /**
+   * The key whose rpm and concurrency counters are charged.
+   *
+   * Share child keys set this to their own id so each child has an independent
+   * rpm window and concurrency slot. Token budgets (daily / monthly / lifetime)
+   * are still charged to `apiKeyId` — the parent — so the shared pool is
+   * enforced globally across all children.
+   *
+   * Defaults to `apiKeyId` when absent (non-share keys, backward compat).
+   */
+  readonly rpmConcurrencyKeyId?: string;
   readonly now: number;
   readonly estimatedTokens: number;
   readonly rpmLimit: number | null;

package/src/security/admission/in-memory-store.ts

@@ -94,12 +94,13 @@ export class InMemoryAdmissionCounterStore implements AdmissionCounterStore {
       ) {
         throw reasonToGatewayError("admission-unavailable", { reason: "invalid_counter" });
       }
-      const rpm = this.pruneRpm(request.apiKeyId, request.now);
+      const rpmConcId = request.rpmConcurrencyKeyId ?? request.apiKeyId;
+      const rpm = this.pruneRpm(rpmConcId, request.now);
       const dailyKey = bucketKey(request.apiKeyId, dailyBucket(request.now));
       const monthlyKey = bucketKey(request.apiKeyId, monthlyBucket(request.now));
       const daily = this.value(this.daily, dailyKey);
       const monthly = this.value(this.monthly, monthlyKey);
-      const concurrent = this.value(this.concurrent, request.apiKeyId);
+      const concurrent = this.value(this.concurrent, rpmConcId);
       const tenantConcurrent = this.value(this.tenantConcurrent, request.tenantId);
       // A missing counter is the only path that seeds from the snapshot; on
       // that path prefer a fresh persisted read over the ≤3s-stale snapshot,
@@ -165,7 +166,7 @@ export class InMemoryAdmissionCounterStore implements AdmissionCounterStore {
         this.evictCounter(this.lifetime);
       }
       if (request.concurrencyLimit != null) {
-        this.concurrent.set(request.apiKeyId, concurrent + 1);
+        this.concurrent.set(rpmConcId, concurrent + 1);
         this.evictCounter(this.concurrent);
       }
       if (request.tenantConcurrencyLimit != null) {

package/src/security/admission/lease-sweep.ts

@@ -14,12 +14,12 @@ const ADMISSION_LEASE_PATTERN = "admission:lease:*";
 /**
  * Bounds for one pass.
  *
- * The scan walks the whole keyspace and the loop used to follow the cursor
- * until it wrapped, reaping every expired lease it found. On a keyspace that
- * has grown for months that is one pass with no ceiling: it holds the timer
- * slot for as long as the backlog takes and starves every other sweep. A
- * backlog drains over successive passes instead; leases the cap leaves behind
- * are still expired on the next tick.
+ * The scan walks the whole keyspace, so following the cursor until it wraps and
+ * reaping every expired lease it finds is one pass with no ceiling on a
+ * keyspace that has grown for months: it would hold the timer slot for as long
+ * as the backlog takes and starve every other sweep. A backlog drains over
+ * successive passes instead; leases the cap leaves behind are still expired on
+ * the next tick.
  */
 export const MAX_LEASE_SCAN_ITERATIONS = 50;
 export const MAX_LEASE_REAPS_PER_PASS = 500;

package/src/security/admission/reasons.ts

@@ -43,7 +43,11 @@ const REASON_META: Record<
     metricLabel: "lifetime",
   },
   "concurrency-limit": {
-    message: "This model is already serving its maximum number of concurrent requests. Retry shortly, or raise the provider's max-inflight.",
+    // This ceiling is the API key's own `max_concurrent`, not the provider's
+    // max-inflight. The two used to be indistinguishable and both named the
+    // provider, sending operators to the wrong setting after a rejection. The
+    // `details` carry the limit so a client can tell which one fired.
+    message: "This API key is already serving its maximum number of concurrent requests. Retry shortly, or raise the key's concurrency limit.",
     code: "capacity_exhausted",
     status: 429,
     metricLabel: "concurrency",