cartethyia 2.5.9 → 2.6.0

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

@@ -5,6 +5,7 @@ import { deleteShared, publishInvalidation, readShared, writeShared } from "../p
 import { DrizzleApiKeyStore } from "../persistence/stores/api-key-store";
 import { GatewayError } from "../protocol/gateway-error";
 import { hashSecret } from "./crypto";
+import { AUTH_CACHE_TTL_MS, createApiKeyAuthorizationCache } from "./api-key-auth-cache";
 import type { AccessScope } from "./access-control";
 import type { ApiKeyModelAccessMode } from "../persistence/schema";
 
@@ -23,37 +24,7 @@ import type { ApiKeyModelAccessMode } from "../persistence/schema";
  * Negative results (unknown/revoked tokens) are deliberately NOT cached, so
  * a newly minted key is usable immediately.
  */
-const AUTH_CACHE_TTL_MS = 3_000;
-const AUTH_CACHE_MAX_ENTRIES = 10_000;
-/** Negative-result TTL: unknown/revoked tokens miss the DB at most this often. */
-const AUTH_NEGATIVE_CACHE_TTL_MS = 1_500;
-
-interface AuthCacheEntry {
-  readonly at: number;
-  readonly value: ResolvedApiKey;
-  /** Owner of `value`; the reverse-index key this entry is registered under. */
-  readonly keyId: string;
-}
-
-const authCache = new Map<string, AuthCacheEntry>();
-/** Reverse index: keyId → set of token hashes that resolved to it. */
-const authCacheByKeyId = new Map<string, Set<string>>();
-/** Unknown/revoked token HMACs with their miss time; cleared on any key mutation. */
-const authNegativeCache = new Map<string, number>();
-
-/**
- * Short circuit after a credential-store failure.
- *
- * An overloaded or down database fails every lookup, and each failure costs a
- * connection attempt. Without this, a saturated backend received one query per
- * inbound request — load the operator sees as traffic, on top of the load that
- * caused the outage. For the window, lookups answer "unavailable" instead.
- *
- * Deliberately short: this is an auth path, and a brief outage must not lock
- * out valid keys for long.
- */
-const AUTH_FAILURE_COOLDOWN_MS = 1_000;
-let authFailureUntil = 0;
+const authorizationCache = createApiKeyAuthorizationCache<ResolvedApiKey>();
 
 /** Thrown when the credential store could not be reached at all. */
 export class ApiKeyStoreUnavailableError extends Error {
@@ -84,52 +55,6 @@ let pendingUsage: (apiKeyId: string) => number = () => 0;
 export function setPendingUsageSource(source: (apiKeyId: string) => number): void {
   pendingUsage = source;
 }
-/**
- * Negative-result fast path. A repeat miss for an unknown/revoked token within
- * 1.5 s costs one HMAC + one map lookup and no query. Keyed by the full HMAC: a
- * cheap pre-hash would let a crafted collision reject someone else's valid key,
- * while the HMAC key can only match its own token. Bound below beside the
- * positive cache.
- */
-
-/**
- * Drops the oldest entries until `authCache` is within budget. Every removal
- * must also unregister the hash from `authCacheByKeyId`, otherwise the reverse
- * index keeps referencing hashes that no longer exist and grows without bound
- * (one dead hash per eviction, forever).
- */
-function evictAuthCacheOldest(): void {
-  while (authCache.size > AUTH_CACHE_MAX_ENTRIES) {
-    const oldest = authCache.keys().next().value;
-    if (oldest === undefined) return;
-    const entry = authCache.get(oldest);
-    authCache.delete(oldest);
-    if (entry === undefined) continue;
-    const hashes = authCacheByKeyId.get(entry.keyId);
-    if (hashes === undefined) continue;
-    hashes.delete(oldest);
-    if (hashes.size === 0) authCacheByKeyId.delete(entry.keyId);
-  }
-}
-
-/** Registers a resolved hash in both the cache and the keyId reverse index. */
-function indexAuthCache(hash: string, entry: AuthCacheEntry): void {
-  authCache.set(hash, entry);
-  authNegativeCache.delete(hash);
-  const hashes = authCacheByKeyId.get(entry.keyId) ?? new Set<string>();
-  hashes.add(hash);
-  authCacheByKeyId.set(entry.keyId, hashes);
-}
-
-/** Bounds the negative cache; same oldest-first rule as the positive cache. */
-function evictAuthNegativeOldest(): void {
-  while (authNegativeCache.size > AUTH_CACHE_MAX_ENTRIES) {
-    const oldest = authNegativeCache.keys().next().value;
-    if (oldest === undefined) return;
-    authNegativeCache.delete(oldest);
-  }
-}
-
 /**
  * Invalidates every cached authorization entry for one API key (or the entire
  * cache when `keyId` is omitted). Called by the API-key domain after any
@@ -138,19 +63,12 @@ function evictAuthNegativeOldest(): void {
 export function invalidateApiKeyCache(keyId?: string): void {
   // A mutation may mint a token the negative cache has already rejected, so
   // negative entries must go with the positive ones.
-  authNegativeCache.clear();
+  authorizationCache.invalidate(keyId);
   if (keyId === undefined) {
-    authCache.clear();
-    authCacheByKeyId.clear();
     void deleteShared("auth");
     publishInvalidation({ namespace: "auth" });
     return;
   }
-  const hashes = authCacheByKeyId.get(keyId);
-  if (hashes) {
-    for (const hash of hashes) authCache.delete(hash);
-    authCacheByKeyId.delete(keyId);
-  }
   // Peer processes hold their own copy, and `reusePort` means the console
   // write may have landed on a different one entirely. Dropping only locally
   // leaves a revoked key valid for up to a full TTL everywhere else.
@@ -388,13 +306,9 @@ export async function resolveApiKeyAuthorization(
 ): Promise<ResolvedApiKey | undefined> {
   const now = Date.now();
   const hash = hashSecret(token);
-  const negativeAt = authNegativeCache.get(hash);
-  if (negativeAt !== undefined) {
-    if (now - negativeAt < AUTH_NEGATIVE_CACHE_TTL_MS) return undefined;
-    authNegativeCache.delete(hash);
-  }
-  const cached = authCache.get(hash);
-  if (cached && now - cached.at < AUTH_CACHE_TTL_MS) return cached.value;
+  const cached = authorizationCache.lookup(hash, now);
+  if (cached.kind === "negative") return undefined;
+  if (cached.kind === "positive") return cached.value;
   // L2: a peer process may have resolved this token already. Reachable only
   // after the L1 entry lapsed, so Redis is never consulted on a warm hit.
   //
@@ -405,8 +319,7 @@ export async function resolveApiKeyAuthorization(
     try {
       const parsed = JSON.parse(shared) as ResolvedApiKey;
       if (typeof parsed?.id === "string") {
-        indexAuthCache(hash, { at: now, value: parsed, keyId: parsed.id });
-        evictAuthCacheOldest();
+        authorizationCache.rememberPositive(hash, parsed.id, parsed, now);
         return parsed;
       }
     } catch {
@@ -415,7 +328,7 @@ export async function resolveApiKeyAuthorization(
   }
   // Answered from the cooldown before any I/O: during a store outage the
   // query is the expensive part, and it is also the part that fails.
-  if (now < authFailureUntil) throw new ApiKeyStoreUnavailableError();
+  if (authorizationCache.isStoreUnavailable(now)) throw new ApiKeyStoreUnavailableError();
   const store = new DrizzleApiKeyStore(db);
   let row: Awaited<ReturnType<typeof store.findActiveByHash>>;
   try {
@@ -423,12 +336,11 @@ export async function resolveApiKeyAuthorization(
   } catch (error) {
     // Any failure here is the store's, not the key's — a revoked key is a
     // normal empty result, so this only runs on a real fault.
-    authFailureUntil = Date.now() + AUTH_FAILURE_COOLDOWN_MS;
+    authorizationCache.markStoreUnavailable(Date.now());
     throw error;
   }
   if (!row) {
-    authNegativeCache.set(hash, now);
-    evictAuthNegativeOldest();
+    authorizationCache.rememberNegative(hash, now);
     return undefined;
   }
   // A child (shared) key consumes against its parent's quota, not just its
@@ -487,8 +399,7 @@ export async function resolveApiKeyAuthorization(
     ...(policy.modelPrefix ? { modelPrefix: policy.modelPrefix } : {}),
     ...(parent?.keyMode === "share" ? { cliMappingOwnerId: parent.id } : {}),
   };
-  indexAuthCache(hash, { at: Date.now(), value, keyId: value.id });
-  evictAuthCacheOldest();
+  authorizationCache.rememberPositive(hash, value.id, value, Date.now());
   // Shared copy for peer processes, keyed by the token hash so a lookup can
   // find it without resolving the key first. Invalidation travels by broadcast,
   // since a console mutation names a key id and cannot enumerate the hashes

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

@@ -1,3 +1,5 @@
+import { getHeader as readRecordHeader } from "../protocol/canonical-model";
+
 // Client-router fingerprinting for inbound `/v1/*` traffic.
 //
 // Several AI-gateway products can themselves be pointed at this gateway. An
@@ -133,13 +135,7 @@ export interface ClientRouterProbe {
 function readHeader(probe: ClientRouterProbe, name: string): string | undefined {
   const headers = probe.headers;
   if (headers instanceof Headers) return headers.get(name) ?? undefined;
-  const direct = headers[name];
-  if (direct !== undefined) return direct;
-  const lowered = name.toLowerCase();
-  for (const [key, value] of Object.entries(headers)) {
-    if (key.toLowerCase() === lowered) return value;
-  }
-  return undefined;
+  return readRecordHeader(headers, name);
 }
 
 function signalMatches(signal: ClientRouterSignal, value: string): boolean {

package/src/security/ip-boundary.ts

@@ -2,6 +2,7 @@
 
 import { isIP } from "node:net";
 import type { TrustedProxyBoundary } from "../config/network";
+import { log } from "../observability/logger";
 
 function ipv4ToNumber(address: string): number | undefined {
   const parts = address.split(".");
@@ -319,9 +320,12 @@ function maybeWarnIgnoredForwardedHeaders(
   if (collapseWarned) return;
   if (!isSuspectedProxyCollapse(request, boundary, peer)) return;
   collapseWarned = true;
-  // Not `log`, to keep this module importable without the logger's transport
-  // (and usable from the boundary tests, which construct bare `Request`s).
-  console.warn(
+  // Via `log`, so this ships through the same transport as everything else and
+  // is level-filtered. It was `console.warn` to keep the module importable
+  // without the logger, but the logger pulls in only pino, the console log ring
+  // and its own sanitizer — none of which import this module — so there is no
+  // cycle and the boundary tests import it the same way production does.
+  log.warn(
     `[ip-boundary] A forwarded client-address header arrived from a loopback peer ` +
       `(${unwrapMappedIpv4(peer)}) but the trusted-proxy boundary does not trust it, so ` +
       `the client address is the loopback peer for every caller. Every caller behind this ` +

package/src/shared/coerce.ts

@@ -0,0 +1,67 @@
+/**
+ * Shared value-coercion primitives for untyped upstream JSON.
+ *
+ * These used to exist as private copies in a dozen modules, spelled
+ * `record`/`asRecord`/`recordOf`/`isPlainObject` with two different nullish
+ * sentinels. One implementation, one sentinel (`undefined`), one place to fix.
+ */
+
+/** Narrow an unknown value to a plain (non-array) object, else `undefined`. */
+export function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+/** Narrow to a finite number, else `undefined`. `NaN`/`Infinity` are not numbers here. */
+export function asNumber(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+/**
+ * Finite number accepting numeric strings (`"42"` → 42). Whitespace-only or
+ * non-finite results are `undefined`. This is the "upstream JSON may quote a
+ * number" contract; use `asNumber` when strings must stay rejected.
+ */
+export function asCoercedNumber(value: unknown): number | undefined {
+  if (typeof value === "number") return asNumber(value);
+  if (typeof value === "string" && value.trim().length > 0) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+  }
+  return undefined;
+}
+
+/** Trim a string-ish value; empty/whitespace-only becomes `undefined`. */
+export function asTrimmedString(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+/** First non-empty trimmed string among `keys` of `record`. */
+export function firstNonEmptyString(
+  record: Record<string, unknown>,
+  keys: readonly string[],
+): string | undefined {
+  for (const key of keys) {
+    const value = asTrimmedString(record[key]);
+    if (value !== undefined) return value;
+  }
+  return undefined;
+}
+
+/**
+ * `JSON.parse` that yields `undefined` instead of throwing, for untyped
+ * upstream/console JSON that may be malformed. Non-string/empty input is
+ * `undefined` without attempting a parse.
+ */
+export function tryParseJson(value: string | null | undefined): unknown {
+  if (typeof value !== "string" || value.length === 0) return undefined;
+  try {
+    return JSON.parse(value) as unknown;
+  } catch {
+    return undefined;
+  }
+}
+

package/src/shared/hash.ts

@@ -0,0 +1,6 @@
+import { createHash } from "node:crypto";
+
+/** Lowercase hex SHA-256 of a UTF-8 string, for cache-key/identity hashing. */
+export function sha256Hex(value: string): string {
+  return createHash("sha256").update(value, "utf8").digest("hex");
+}

package/src/shared/time.ts

@@ -0,0 +1,7 @@
+/**
+ * `YYYY-MM-DDTHH` stamp used as the prefix of raw telemetry/payload files
+ * and as the hour comparison key on both sides of retention.
+ */
+export function hourStamp(date: Date): string {
+  return date.toISOString().slice(0, 13).replaceAll(":", "-");
+}

package/src/transport/dispatch/attempt-finalize.ts

@@ -7,10 +7,9 @@ import type { UsageRecord } from "../../protocol/canonical-model";
 import { classifyUpstreamFailure } from "../failure-policy";
 import type { AdmissionLease } from "../../security/admission/contracts";
 import type { CartethyiaDatabase } from "../../persistence/db-handle";
-import { TelemetryPayloadCapture } from "../../observability/payload-capture";
+import { resolvePayloadCapture, TelemetryPayloadCapture, truncateUtf8 } from "../../observability/payload-capture";
 import { payloadDirectory } from "../../observability/payload-store";
 import type { TelemetryBatchBuffer } from "../../observability/telemetry-buffer";
-import type { TelemetryPayloadDepth } from "../../console/settings/contracts";
 import type { ProxyRequestOutcome, ProxyRequestState } from "../request/state";
 import type { PayloadCaptureState } from "../../observability/payload-capture";
 import { finalizeRequestTelemetry } from "../guards/error-lifecycle";
@@ -22,126 +21,7 @@ import {
   recordPoolDispatchOutcome,
 } from "../../network/pool-health-machine";
 import { ProxyConnectRefusalError } from "../../network/pool/agent";
-import {
-  payloadCaptureKeepsBodies,
-  payloadRetentionMs,
-  resolvePayloadCapture,
-} from "../../observability/payload-capture";
-
-/**
- * True when the tenant keeps response bodies (mode `full`). The dispatch
- * path calls this once per attempt to decide whether the provider-response
- * tee is worth its clone + bounded read; `none`/`metadata` skip the body.
- */
-export async function shouldCaptureProviderBody(
-  db: CartethyiaDatabase,
-  tenantId: string | null,
-): Promise<boolean> {
-  return payloadCaptureKeepsBodies(db, tenantId);
-}
-
-/**
- * Per-stage cap for the provider request/response tee at one capture depth.
- *
- * The tee is what the drawer's "Provider Request" and "Provider Response"
- * panels read, so its cap is the most a provider panel can ever show. It used
- * to be a flat 256 KiB at every depth: on a large request the translated
- * provider body was clipped to 256 KiB before the shared record budget ever
- * ran, so a tenant who raised the depth to Maximum — 16 MiB — still saw a
- * quarter-megabyte provider request and an empty provider response. Derived
- * from the same depth tiers as the record budget, so raising the depth now
- * raises both.
- *
- * Capped at a quarter of the depth's total budget: four panels share it, and
- * one of them must never be able to spend the whole thing.
- */
-export function providerCaptureMaxBytes(depth?: TelemetryPayloadDepth): number {
-  if (depth === "moderate") return 2 * 1024 * 1024;
-  if (depth === "maximum") return 4 * 1024 * 1024;
-  return 256 * 1024;
-}
-
-/**
- * Same answer as {@link shouldCaptureProviderBody}, memoized on the request.
- *
- * The preference is a tenant setting, so it cannot change between attempts of
- * one request. Resolving it per attempt meant a request with several attempts
- * paid for it repeatedly, and the per-attempt answer could in principle differ
- * from the one the terminal capture then acted on. Passing `state` lets every
- * attempt of a request share one resolution.
- */
-export async function shouldCaptureProviderBodyForRequest(
-  db: CartethyiaDatabase,
-  tenantId: string | null,
-  state: { payloadCapturePreference?: unknown },
-): Promise<boolean> {
-  if (state.payloadCapturePreference === undefined) {
-    state.payloadCapturePreference = await resolvePayloadCapture(db, tenantId);
-  }
-  const resolved = state.payloadCapturePreference as
-    | { readonly ok: true; readonly mode: string }
-    | { readonly ok: false };
-  return resolved.ok === true && resolved.mode === "full";
-}
-
-/**
- * The tenant's capture depth, memoized on the request like the mode above.
- *
- * Read *after* {@link shouldCaptureProviderBodyForRequest} has populated the
- * memo, so the two answers come from one preference read. It sizes the
- * provider tee: a tenant who raised the depth is asking for more of every
- * panel, and a flat cap would answer with the same clipped body regardless.
- */
-export async function resolveCaptureDepthForRequest(
-  db: CartethyiaDatabase,
-  tenantId: string | null,
-  state: { payloadCapturePreference?: unknown },
-): Promise<TelemetryPayloadDepth> {
-  if (state.payloadCapturePreference === undefined) {
-    state.payloadCapturePreference = await resolvePayloadCapture(db, tenantId);
-  }
-  const resolved = state.payloadCapturePreference as
-    | { readonly ok: true; readonly depth: TelemetryPayloadDepth }
-    | { readonly ok: false };
-  return resolved.ok === true ? resolved.depth : "minimum";
-}
-
-/**
- * The tenant's chosen payload retention, memoized on the request like the mode
- * and depth above — and resolved *after* one of them has populated the memo, so
- * all three come from one preference read.
- *
- * Falls back to the deployment default when the read failed, which is the same
- * answer the capture path reaches on its own; returning it here keeps the
- * caller from having to know the fallback exists.
- */
-export async function resolveCaptureRetentionForRequest(
-  db: CartethyiaDatabase,
-  tenantId: string | null,
-  state: { payloadCapturePreference?: unknown },
-): Promise<number> {
-  if (state.payloadCapturePreference === undefined) {
-    state.payloadCapturePreference = await resolvePayloadCapture(db, tenantId);
-  }
-  const resolved = state.payloadCapturePreference as
-    | { readonly ok: true; readonly retentionMs: number }
-    | { readonly ok: false };
-  return resolved.ok === true ? resolved.retentionMs : payloadRetentionMs();
-}
-
-/**
- * Combined body cap for one capture depth. Fixed size tiers: every depth
- * stores all four drawer panels (client request, translated provider
- * request, raw provider response, final client response) — only the cap
- * changes, so raising the depth never changes *what* is visible, only how
- * much of large bodies survives. Moderate and maximum spike CPU/memory while
- * active; minimum is light enough to leave on.
- */
-function captureDepthMaxBytes(depth: TelemetryPayloadDepth): number {
-  if (depth === "moderate") return 8 * 1024 * 1024;
-  if (depth === "maximum") return 16 * 1024 * 1024;
-  return 1 * 1024 * 1024;
-}
+import { captureDepthMaxBytes, providerCaptureMaxBytes } from "./capture-policy";
 
 /**
  * What the client received for a failed terminal attempt, in the same public
@@ -186,21 +66,24 @@ async function readBoundedBody(response: Response, maxBytes: number): Promise<st
   const reader = response.body.getReader();
   const decoder = new TextDecoder();
   // Collect decoded chunks and join once: `+=` per chunk reallocates the
-  // prefix (O(n^2)). Truncation stays at the same decoded-char boundary.
+  // prefix (O(n^2)). The budget is UTF-8 **bytes** — the same basis the record
+  // budget and the request-line slice use — measured per decoded chunk, with
+  // the final chunk trimmed by truncateUtf8 so a code point is never split.
   const parts: string[] = [];
-  let total = 0;
+  let totalBytes = 0;
   try {
-    while (total < maxBytes) {
+    while (totalBytes < maxBytes) {
       const { done, value } = await reader.read();
       if (done) break;
       const chunk = decoder.decode(value, { stream: true });
-      if (total + chunk.length > maxBytes) {
-        parts.push(chunk.slice(0, maxBytes - total));
-        total = maxBytes;
+      const chunkBytes = Buffer.byteLength(chunk, "utf8");
+      if (totalBytes + chunkBytes > maxBytes) {
+        parts.push(truncateUtf8(chunk, maxBytes - totalBytes));
+        totalBytes = maxBytes;
         break;
       }
       parts.push(chunk);
-      total += chunk.length;
+      totalBytes += chunkBytes;
     }
   } catch {
     // Best-effort capture must never fail the request path.
@@ -339,11 +222,16 @@ export function captureProviderExchange(
       method: init?.method ?? "GET",
       url,
       ...(headers === undefined ? {} : { headers }),
-      // Capped the same way the response is. A capture is a diagnostic, and an
-      // unbounded translated request body per attempt — up to `maxAttempts` of
-      // them, all alive until the loop returns — costs more than it can tell
-      // an operator.
-      ...(rawBody === null ? {} : { body: parseCapturedBody(rawBody.slice(0, maxBytes)) }),
+      // `captureBody=false` is the `none`/`metadata` path: record that a body
+      // was sent and how big it was, without slicing or parsing it. The old
+      // shape sliced up to `maxBytes` of the translated body and ran it through
+      // `JSON.parse` for every attempt — content a metadata-mode tenant had
+      // explicitly declined to retain, paid on every dispatch.
+      ...(rawBody === null
+        ? {}
+        : captureBody
+          ? { body: parseCapturedBody(truncateUtf8(rawBody, maxBytes)) }
+          : { body_present: true, body_bytes: Buffer.byteLength(rawBody, "utf8") }),
     };
     const response = await inner(input, init);
     sink.response =
@@ -426,7 +314,7 @@ async function captureTerminalPayload(
         note("captured_metadata");
         return;
       }
-      await new TelemetryPayloadCapture(db).capture({
+      const metadataCapture = await new TelemetryPayloadCapture(db).capture({
         tenantId,
         requestId,
         requestBody: null,
@@ -436,13 +324,13 @@ async function captureTerminalPayload(
         scope: "tenant",
         tenantOptIn: true,
       });
-      note("captured_metadata");
+      note(metadataCapture.payloadCaptureState ?? "captured_metadata");
       return;
     }
     const maxBytes = captureDepthMaxBytes(depth);
     const providerRequest = providerCapture?.request ?? null;
     const providerResponse = await resolvedProviderResponse(providerCapture);
-    await new TelemetryPayloadCapture(db).capture({
+    const terminalCapture = await new TelemetryPayloadCapture(db).capture({
       tenantId,
       requestId,
       requestBody: requestBody ?? null,
@@ -455,7 +343,7 @@ async function captureTerminalPayload(
       scope: "tenant",
       tenantOptIn: true,
     });
-    note("captured");
+    note(terminalCapture.payloadCaptureState ?? "captured");
   } catch (error) {
     note("failed_write");
     reportCaptureFailure(error);