cartethyia 2.7.3 → 2.7.5

package/src/security/abuse.ts

@@ -57,7 +57,7 @@ const BAN_ROUTE_KEY = "#ban";
  * `banThreshold` is both the identity-wide escalation threshold and the
  * highest count either ring must keep observable.
  */
-export interface IpAbuseAttempt {
+interface IpAbuseAttempt {
   readonly identity: string;
   readonly route: string;
   readonly now: number;
@@ -67,7 +67,7 @@ export interface IpAbuseAttempt {
 }
 
 /** What one admission step decided. */
-export interface IpAbuseOutcome {
+interface IpAbuseOutcome {
   /** The identity was already banned; nothing was incremented. */
   readonly banned: boolean;
   /** Attempts now in this route's window, including this one. `0` when banned. */
@@ -115,13 +115,13 @@ export interface IpAbuseStore {
   checkAndRecord(attempt: IpAbuseAttempt): Promise<IpAbuseOutcome>;
 }
 
-export interface IpAbuseProtectionServiceOptions {
+interface IpAbuseProtectionServiceOptions {
   readonly maxRequestsPerWindow?: number;
   readonly banThreshold?: number;
   readonly banDurationMs?: number;
 }
 
-export interface InMemoryIpAbuseStoreOptions {
+interface InMemoryIpAbuseStoreOptions {
   readonly windowMs?: number;
   readonly clock?: () => number;
   /** Distinct (identity, route) keys tracked before the oldest is evicted. */
@@ -399,7 +399,7 @@ export class IpAbuseProtectionService {
     readonly signal?: AbortSignal;
   }): Promise<void> {
     if (input.signal?.aborted) {
-      throw new GatewayError("admission_unavailable", 503, "The abuse check never ran because the request was already cancelled.", {
+      throw new GatewayError("admission_unavailable", 503, "The abuse check never ran because the request was already cancelled (request {requestId}). Send it again whenever ready 🙃", {
         reason: "admission-unavailable",
       });
     }
@@ -436,7 +436,7 @@ export class IpAbuseProtectionService {
 
       if (outcome.banned) {
         metrics.cartethyia_ip_abuse_refusals_total.inc(1, { reason: "ip-banned" });
-        throw new GatewayError("quota_exceeded", 429, "This address is temporarily banned for too many failed requests. Wait for the ban to lift, then slow down.", {
+        throw new GatewayError("rate_limited", 429, "This address is temporarily banned for too many failed requests (request {requestId}). Wait for the ban to lift, then slow down. You've maxed this window — pace yourself ⏳", {
           // Distinguishes this from the rate-limited 429 below and from an API
           // key's own budget. It used to be "admission-unavailable", which is
           // the label for an *unreachable* store — so every refusal from this
@@ -454,7 +454,7 @@ export class IpAbuseProtectionService {
 
       if (outcome.count > this.maxRequestsPerWindow) {
         metrics.cartethyia_ip_abuse_refusals_total.inc(1, { reason: "ip-rate-limited" });
-        throw new GatewayError("quota_exceeded", 429, "This address is sending requests faster than the abuse limit allows. Back off and retry after the window rolls over.", {
+        throw new GatewayError("rate_limited", 429, "This address is sending requests faster than the abuse limit allows (request {requestId}). Back off and retry after the window rolls over. You've maxed this window — pace yourself ⏳", {
           reason: "ip-rate-limited",
           ip,
           route: input.route,
@@ -464,7 +464,7 @@ export class IpAbuseProtectionService {
       }
     } catch (err) {
       if (err instanceof GatewayError) throw err;
-      throw new GatewayError("admission_unavailable", 503, "The abuse-tracking store is unreachable, so requests from this address cannot be checked. Retry shortly.", {
+      throw new GatewayError("admission_unavailable", 503, "The abuse-tracking store is unreachable, so requests from this address cannot be checked (request {requestId}). Retry shortly. The bouncer stepped out — come back shortly 🚪", {
         reason: "admission-unavailable",
         cause: (err as Error).message,
       });

package/src/security/admission/reasons.ts

@@ -19,26 +19,26 @@ const REASON_META: Record<
   }
 > = {
   "rpm-exhausted": {
-    message: "This key has used its requests-per-minute allowance. Wait for the window to roll over, or raise the key's rpm limit.",
-    code: "quota_exceeded",
+    message: "This key has used its requests-per-minute allowance (request {requestId}). Wait for the window to roll over, or raise the key's rpm limit. You've maxed this window — pace yourself ⏳",
+    code: "rate_limited",
     status: 429,
     metricLabel: "rpm_exhausted",
   },
   "daily-token-limit": {
-    message: "This key has used today's token allowance. It resets at the start of the next day, or raise the key's daily limit.",
-    code: "quota_exceeded",
+    message: "This key has used today's token allowance (request {requestId}). It resets at the start of the next day, or raise the key's daily limit. Pace yourself — it resets tomorrow ⏳",
+    code: "rate_limited",
     status: 429,
     metricLabel: "daily",
   },
   "monthly-token-limit": {
-    message: "This key has used this month's token allowance. It resets at the start of the next month, or raise the key's monthly limit.",
-    code: "quota_exceeded",
+    message: "This key has used this month's token allowance (request {requestId}). It resets at the start of the next month, or raise the key's monthly limit. Saving up for next month? It resets then ⏳",
+    code: "rate_limited",
     status: 429,
     metricLabel: "monthly",
   },
   "lifetime-token-budget": {
-    message: "This key has spent its lifetime token budget. Raise the budget, or issue a new key.",
-    code: "quota_exceeded",
+    message: "This key has spent its lifetime token budget (request {requestId}). Raise the budget, or issue a new key. The piggy bank is empty — top it up or mint a new key 🐷",
+    code: "rate_limited",
     status: 429,
     metricLabel: "lifetime",
   },
@@ -47,27 +47,27 @@ const REASON_META: Record<
     // 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.",
+    message: "This API key is already serving its maximum number of concurrent requests (request {requestId}). Retry shortly, or raise the key's concurrency limit. It'll free up in a moment 🌊",
     code: "capacity_exhausted",
     status: 429,
     metricLabel: "concurrency",
   },
   "tenant-capacity-exhausted": {
-    message: "This tenant is already serving its maximum number of concurrent requests. Retry shortly, or raise the tenant's concurrency limit.",
+    message: "This tenant is already serving its maximum number of concurrent requests (request {requestId}). Retry shortly, or raise the tenant's concurrency limit. The tenant is maxed out right now — chill 🏠",
     code: "tenant_capacity_exhausted",
     status: 429,
     metricLabel: "tenant_capacity",
   },
   "model-not-allowed": {
-    message: "This key is not allowed to use this model under its allowlist. Add the model to the key, or use one it already allows.",
-    code: "model_not_found",
-    status: 404,
+    message: "This key is not allowed to use this model under its allowlist (request {requestId}). Add the model to the key, or use one it already allows. The door's locked for this one — check the allowlist 🔒",
+    code: "model_not_allowed",
+    status: 403,
     metricLabel: "model_not_allowed",
   },
   "model-denied": {
-    message: "This key's denylist blocks this model. Remove the model from the denylist, or use a different model.",
-    code: "model_not_found",
-    status: 404,
+    message: "This key's denylist blocks this model (request {requestId}). Remove the model from the denylist, or use a different model. This one's on the banned list — pick another 🚫",
+    code: "model_not_allowed",
+    status: 403,
     metricLabel: "model_not_allowed",
   },
   "admission-unavailable": {
@@ -76,7 +76,7 @@ const REASON_META: Record<
     // `invalid_counter`, `unknown_reservation`, `invalid_actual_usage`). The
     // second is not an outage, so the text must not claim one — it names the
     // effect the client can act on, and the diagnostic stays in `details.reason`.
-    message: "The gateway could not admit this request. Retry shortly; if it persists, check the instance's Redis or coordination backend.",
+    message: "The gateway could not admit this request (request {requestId}). Retry shortly; if it persists, check the instance's Redis or coordination backend. The bouncer stepped out — come back shortly 🚪",
     code: "admission_unavailable",
     status: 503,
     metricLabel: "admission_unavailable",

package/src/security/admission/service.ts

@@ -12,7 +12,7 @@ import { admissionMetricLabel, reasonToGatewayError } from "./reasons";
 
 /** Persists reconciled lifetime token consumption for an API key. Injected so
  *  the in-memory admission service stays decoupled from Drizzle/Postgres. */
-export type LifetimeUsagePersister = (input: {
+type LifetimeUsagePersister = (input: {
   apiKeyId: string;
   delta: number;
 }) => Promise<void>;
@@ -23,7 +23,7 @@ export type LifetimeUsagePersister = (input: {
  * counter store only when it is about to seed a missing lifetime counter, so
  * the ≤3s-stale snapshot value cannot freeze a low baseline in place. Injected
  * so the admission module stays decoupled from Drizzle/Postgres. */
-export type FreshLifetimeConsumedReader = (apiKeyId: string) => Promise<number | undefined>;
+type FreshLifetimeConsumedReader = (apiKeyId: string) => Promise<number | undefined>;
 
 
 export class ApiKeyAdmissionService {

package/src/security/admission/ttl.ts

@@ -1,61 +1,61 @@
-/**
- * Lease and counter lifetimes, and the calendar bucket keys they key on.
- *
- * These live together because they are one arithmetic problem: a counter
- * must outlive the lease that charges it, and a lease key must outlive the
- * horizon the sweeper reads. Splitting them across files is how those
- * invariants silently break, so the reasoning stays in one place.
- */
-export const LEASE_TTL_MS = 3600_000;
-
-/**
- * The lease key's own Redis TTL is deliberately LONGER than the `expires_at`
- * horizon the lease hash records.
- *
- * `expires_at` is the moment the sweeper becomes allowed to reclaim the lease.
- * If the key TTL equalled that horizon, Redis would evict the hash at exactly
- * the moment `reapIfExpired` wanted to read it: `HGET state` would return nil,
- * the sweep would skip it, and a crash between reserve and release would strand
- * the held concurrency / tenant-concurrency slot for as long as the counter
- * keeps being refreshed — every later reserve re-arms the counter's own TTL, so
- * a key still in use never recovers its leaked slot. The grace window keeps the
- * hash readable for several sweep intervals past the horizon, so the recovery
- * path actually runs.
- *
- * Exported so the invariant is asserted directly: a lease key must outlive the
- * horizon it records by more than one sweep interval (`sweepLeases` runs every
- * 30s, wired in `runtime/dependencies.ts`).
- */
-const LEASE_TTL_GRACE_SECONDS = 120;
-/** Seconds after which a lease hash is reapable (`expires_at` horizon). */
-export const LEASE_REAP_HORIZON_SECONDS = Math.ceil(LEASE_TTL_MS / 1000);
-/** Seconds the lease hash itself lives; must exceed the reap horizon. */
-export const LEASE_KEY_TTL_SECONDS = LEASE_REAP_HORIZON_SECONDS + LEASE_TTL_GRACE_SECONDS;
-
-/**
- * TTLs for the token-budget counters, in seconds.
- *
- * Daily lives just past two days (a day bucket plus slack to cover a request
- * straddling midnight); monthly and lifetime share one 35-day window — long
- * enough that a month bucket is never evicted mid-month, and it is the *only*
- * thing bounding `admission:lifetime:*`, which has no natural bucket to expire
- * on. Every writer below must therefore carry its own TTL: a plain `SET`
- * without one creates a key that outlives every bucket it feeds.
- */
-export const DAILY_COUNTER_TTL_SECONDS = 172800;
-export const MONTHLY_COUNTER_TTL_SECONDS = 3024000;
-export const LIFETIME_COUNTER_TTL_SECONDS = 3024000;
-/** RPM window plus slack; concurrency slots are held for the request duration. */
-export const RPM_WINDOW_TTL_SECONDS = 65;
-// Must exceed the lease's own lifetime (`LEASE_TTL_MS` + grace), otherwise a
-// request held longer than this lets its concurrency counter expire underneath
-// a still-live lease and a later reserve INCRs from zero. Derived rather than
-// hard-coded so raising the lease TTL cannot silently reopen the hole.
-export const CONCURRENCY_TTL_SECONDS = LEASE_KEY_TTL_SECONDS;
-
-export function dailyBucket(now: number): string {
-  return new Date(now).toISOString().slice(0, 10);
-}
-export function monthlyBucket(now: number): string {
-  return new Date(now).toISOString().slice(0, 7);
-}
+/**
+ * Lease and counter lifetimes, and the calendar bucket keys they key on.
+ *
+ * These live together because they are one arithmetic problem: a counter
+ * must outlive the lease that charges it, and a lease key must outlive the
+ * horizon the sweeper reads. Splitting them across files is how those
+ * invariants silently break, so the reasoning stays in one place.
+ */
+export const LEASE_TTL_MS = 3600_000;
+
+/**
+ * The lease key's own Redis TTL is deliberately LONGER than the `expires_at`
+ * horizon the lease hash records.
+ *
+ * `expires_at` is the moment the sweeper becomes allowed to reclaim the lease.
+ * If the key TTL equalled that horizon, Redis would evict the hash at exactly
+ * the moment `reapIfExpired` wanted to read it: `HGET state` would return nil,
+ * the sweep would skip it, and a crash between reserve and release would strand
+ * the held concurrency / tenant-concurrency slot for as long as the counter
+ * keeps being refreshed — every later reserve re-arms the counter's own TTL, so
+ * a key still in use never recovers its leaked slot. The grace window keeps the
+ * hash readable for several sweep intervals past the horizon, so the recovery
+ * path actually runs.
+ *
+ * Exported so the invariant is asserted directly: a lease key must outlive the
+ * horizon it records by more than one sweep interval (`sweepLeases` runs every
+ * 30s, wired in `runtime/dependencies.ts`).
+ */
+const LEASE_TTL_GRACE_SECONDS = 120;
+/** Seconds after which a lease hash is reapable (`expires_at` horizon). */
+export const LEASE_REAP_HORIZON_SECONDS = Math.ceil(LEASE_TTL_MS / 1000);
+/** Seconds the lease hash itself lives; must exceed the reap horizon. */
+export const LEASE_KEY_TTL_SECONDS = LEASE_REAP_HORIZON_SECONDS + LEASE_TTL_GRACE_SECONDS;
+
+/**
+ * TTLs for the token-budget counters, in seconds.
+ *
+ * Daily lives just past two days (a day bucket plus slack to cover a request
+ * straddling midnight); monthly and lifetime share one 35-day window — long
+ * enough that a month bucket is never evicted mid-month, and it is the *only*
+ * thing bounding `admission:lifetime:*`, which has no natural bucket to expire
+ * on. Every writer below must therefore carry its own TTL: a plain `SET`
+ * without one creates a key that outlives every bucket it feeds.
+ */
+export const DAILY_COUNTER_TTL_SECONDS = 172800;
+export const MONTHLY_COUNTER_TTL_SECONDS = 3024000;
+export const LIFETIME_COUNTER_TTL_SECONDS = 3024000;
+/** RPM window plus slack; concurrency slots are held for the request duration. */
+export const RPM_WINDOW_TTL_SECONDS = 65;
+// Must exceed the lease's own lifetime (`LEASE_TTL_MS` + grace), otherwise a
+// request held longer than this lets its concurrency counter expire underneath
+// a still-live lease and a later reserve INCRs from zero. Derived rather than
+// hard-coded so raising the lease TTL cannot silently reopen the hole.
+export const CONCURRENCY_TTL_SECONDS = LEASE_KEY_TTL_SECONDS;
+
+export function dailyBucket(now: number): string {
+  return new Date(now).toISOString().slice(0, 10);
+}
+export function monthlyBucket(now: number): string {
+  return new Date(now).toISOString().slice(0, 7);
+}

package/src/security/api-key-auth.ts

@@ -118,7 +118,7 @@ function freezeList(
   return arr;
 }
 
-export function freezeSnapshot(s: ApiKeyAuthorizationSnapshot): ApiKeyAuthorizationSnapshot {
+function freezeSnapshot(s: ApiKeyAuthorizationSnapshot): ApiKeyAuthorizationSnapshot {
   const model_list = freezeList(s.model_list);
   const model_access_mode: ApiKeyModelAccessMode =
     s.model_access_mode === "blacklist" ? "blacklist" : "whitelist";
@@ -239,7 +239,7 @@ export interface ResolvedApiKey {
  * indistinguishable — distinguishing them would let a caller confirm that a
  * guessed token once existed — so there is no variant carrying a reason.
  */
-const INVALID_KEY_MESSAGE = "Invalid API key. Check the key you are sending, or create a new one in API Keys and send it as: Authorization: Bearer <key>.";
+const INVALID_KEY_MESSAGE = "Invalid API key (request {requestId}). Check the key you are sending, or create a new one in API Keys and send it as: Authorization: Bearer <key>. Wrong key, right door — double-check and come back 🔑";
 
 export function unknownApiKeyError(): GatewayError {
   return new GatewayError("authentication_failed", 401, INVALID_KEY_MESSAGE);
@@ -258,7 +258,7 @@ export function modelsListApiKeyError(): GatewayError {
   return new GatewayError(
     "authentication_failed",
     401,
-    "Invalid API key. Rotate the default Cartethyia API key in API Keys and send the new key as: Authorization: Bearer <key>.",
+    "Invalid API key (request {requestId}). Rotate the default Cartethyia API key in API Keys and send the new key as: Authorization: Bearer <key>. Wrong key, right door — rotate and try again 🔑",
   );
 }
 
@@ -279,12 +279,12 @@ export function requestToken(headers: Headers | Record<string, string>): string
     // *different* credentials stay a conflict — accepting whichever came first
     // would silently decide the request's identity.
     if (bearerMatch?.[1] === apiKey) return apiKey;
-    throw new GatewayError("invalid_request", 400, "The request sends two different credentials. Send exactly one key, either as Authorization: Bearer <key> or as the api-key header.");
+    throw new GatewayError("invalid_request", 400, "The request sends two different credentials (request {requestId}). Send exactly one key, either as Authorization: Bearer <key> or as the api-key header. Pick one key and stick with it 🤝");
   }
   if (hasApiKey) return apiKey;
   const token = bearerMatch?.[1];
   if (token === undefined)
-    throw new GatewayError("invalid_request", 401, "The request carries no usable credential. Send the key as: Authorization: Bearer <key>.");
+    throw new GatewayError("authentication_failed", 401, "The request carries no usable credential (request {requestId}). Send the key as: Authorization: Bearer <key>. We need a key to let you in 🔑");
   return token;
 }
 
@@ -363,6 +363,12 @@ export async function resolveApiKeyAuthorization(
   // keep the issued row values forever. Reading the parent here makes denylist /
   // one-time / recurring edits apply on the next cache miss.
   const policy = parent ?? row;
+  // Share-template concurrency scope decides whether the family shares one
+  // admission counter (default `family`) or each recipient has its own
+  // (`per_key`). In `family` mode the child participates in the parent's
+  // counter namespace; in `per_key` mode the child is its own admission
+  // identity and carries its own cap.
+  const perKeyConcurrency = parent !== undefined && row.concurrencyScope === "per_key";
   // Only a `share` parent can have children, and children are the only thing
   // the SUM below can find. Every other key ran an aggregate that was certain
   // to return 0 — one extra Postgres round-trip on the auth path for nothing.
@@ -381,8 +387,10 @@ export async function resolveApiKeyAuthorization(
     api_key_id: row.id,
     tenant_id: row.tenantId,
     // Family quota / concurrency share one admission counter namespace so two
-    // recipients cannot each burn a full lifetime/daily budget.
-    ...(parent ? { admission_identity: parent.id } : {}),
+    // recipients cannot each burn a full lifetime/daily budget. In `per_key`
+    // concurrency mode the child is its own admission identity so its cap and
+    // counter are independent.
+    ...(parent && !perKeyConcurrency ? { admission_identity: parent.id } : {}),
     ...(policy.modelList ? { model_list: policy.modelList as string[] } : {}),
     model_access_mode: policy.modelAccessMode ?? "whitelist",
     ...(policy.clientRouterDenylist
@@ -393,7 +401,11 @@ export async function resolveApiKeyAuthorization(
     ...(policy.monthlyTokenLimit != null ? { monthly_tokens: policy.monthlyTokenLimit } : {}),
     ...(policy.lifetimeTokenBudget != null ? { lifetime_token_budget: policy.lifetimeTokenBudget } : {}),
     lifetime_tokens_consumed: consumed,
-    ...(policy.maxConcurrentRequests != null ? { max_concurrent: policy.maxConcurrentRequests } : {}),
+    // `per_key` mode: the child carries its own cap (copied at issue); family
+    // mode inherits the parent's cap.
+    ...((perKeyConcurrency ? row.maxConcurrentRequests : policy.maxConcurrentRequests) != null
+      ? { max_concurrent: perKeyConcurrency ? row.maxConcurrentRequests : policy.maxConcurrentRequests }
+      : {}),
     scopes,
   });
 

package/src/security/client-router-fingerprint.ts

@@ -21,7 +21,7 @@ import { getHeader as readRecordHeader } from "../protocol/canonical-model";
  * `id` is the stable token an operator stores in a key's denylist, so it is
  * part of the persisted contract and must not be renamed casually.
  */
-export interface ClientRouterDefinition {
+interface ClientRouterDefinition {
   readonly id: string;
   /** Human label for the dashboard. */
   readonly label: string;
@@ -40,7 +40,7 @@ export interface ClientRouterDefinition {
  * safe for a uniquely named header; a header whose value distinguishes it must
  * name a matcher instead.
  */
-export interface ClientRouterSignal {
+interface ClientRouterSignal {
   /** Header name, lowercase. */
   readonly field: string;
   /** Human description shown when the signal matches. */
@@ -114,14 +114,14 @@ export const CLIENT_ROUTERS: readonly ClientRouterDefinition[] = [
 const LEGACY_CLIENT_ROUTER_IDS: Readonly<Record<string, string>> = { omniroute: "9router" };
 
 /** A signal that matched, with the product it belongs to. */
-export interface MatchedClientSignal {
+interface MatchedClientSignal {
   readonly field: string;
   readonly description: string;
   /** The observed value, capped, for the operator's audit trail. */
   readonly value: string;
 }
 
-export interface ClientRouterMatch {
+interface ClientRouterMatch {
   readonly routerId: string;
   readonly label: string;
   readonly signals: readonly MatchedClientSignal[];

package/src/security/credential-codec.ts

@@ -22,7 +22,7 @@ import { isRecord } from "../protocol/codecs";
 const TEXT_DECODER = new TextDecoder();
 
 /** Decodes a stored secret: UTF-8 bytes or a string, trimmed. */
-export function decodeSecretText(secret: Uint8Array | string): string {
+function decodeSecretText(secret: Uint8Array | string): string {
   const raw = typeof secret === "string" ? secret : TEXT_DECODER.decode(secret);
   return raw.trim();
 }
@@ -48,7 +48,7 @@ function fieldString(record: Record<string, unknown>, key: string): string {
 }
 
 /** `{accessToken, orgId?}` — the Kilo Code envelope (org scoping is optional). */
-export interface KiloEnvelope {
+interface KiloEnvelope {
   readonly accessToken: string;
   /** Organization the gateway scopes requests to; absent when the profile omits one. */
   readonly orgId?: string;
@@ -79,7 +79,7 @@ export function decodeKiloCredential(secret: Uint8Array | string): KiloEnvelope
 }
 
 /** `{oauthAccessToken, apiKey}` — the Muse Code (Meta) envelope. */
-export interface MuseEnvelope {
+interface MuseEnvelope {
   readonly oauthAccessToken: string;
   readonly apiKey: string;
 }

package/src/security/csrf.ts

@@ -16,7 +16,7 @@ import { isRecord } from "../protocol/codecs";
  * but cannot read the cookie value, so it cannot forge the header.
  */
 export const CSRF_COOKIE_NAME = "csrf_token";
-export const CSRF_HEADER_NAME = "x-csrf-token";
+const CSRF_HEADER_NAME = "x-csrf-token";
 
 /**
  * Name of the session cookie whose presence gates CSRF validation in
@@ -30,7 +30,7 @@ export const SESSION_COOKIE_NAME = "session_token";
  * `SessionCookiePolicy` structurally satisfies this (extra fields are fine),
  * so call sites keep passing their existing policy object unchanged.
  */
-export interface CsrfCookiePolicy {
+interface CsrfCookiePolicy {
   readonly maxAge: number;
   readonly sameSite: "Lax" | "Strict" | "None";
   readonly secure: boolean;