cartethyia 2.6.7 → 2.7.0

package/src/transport/guards/request-context.ts

@@ -1,318 +1,238 @@
-// Per-request context, client identity, canonical parse, and route preparation.
-import { Elysia } from "elysia";
-import { GatewayError } from "../../protocol/gateway-error";
-import type { TrustedProxyBoundary } from "../../config/network";
-import { resolveUpstreamTimeoutMs } from "../../config/timeouts";
-import type { ProxyRequestStateStore } from "../request/state";
-import { fastPathname } from "../pathname";
-import type { ProxyRequestPreparer } from "../request/preparer";
-import type { CanonicalAdapter } from "../contracts";
-import type { SurfaceAdapterRegistry } from "../surface/adapters";
-import { resolveClientIdentity } from "../../security/ip-boundary";
-import { GATEWAY_SECURITY_HEADERS } from "../../security/outbound-headers";
-import { pushStructuredConsoleLog } from "../../observability/log-ring";
-import { log } from "../../observability/logger";
-import { isJsonProxyRoutePath, isProxyDispatchRoute } from "./body-policy";
-import { isOpaqueBodyRoute } from "../contracts";
-import {
-  modelAbuseBannedError,
-  modelWarningMessage,
-  type ModelAbuseOutcome,
-  type ModelStrikeService,
-} from "../../security/model-abuse";
-import { peerAddressUnavailableError } from "./guard-errors";
-
-/**
- * Whether a thrown error is a *model* rejection the strike layer counts: the
- * key may not use the named model (`isModelAllowed` → 404), or the name
- * resolves to nothing (`modelNotFoundError` → 404). Both surface as
- * `model_not_found`; every other failure — an aborted request, a store outage,
- * a capability mismatch — is not the caller probing for models and is not
- * counted.
- */
-function isModelRejection(error: unknown): boolean {
-  return error instanceof GatewayError && error.code === "model_not_found";
-}
-
-/**
- * Re-throws a model rejection carrying the escalating strike warning, so an
- * honest client that mistyped sees "Warning 1 of 3" instead of the same generic
- * 404 three times and then a ban. The code/status are unchanged — only the
- * message gains the warning, and the count rides in `details` for the console.
- */
-function withModelWarning(
-  error: unknown,
-  outcome: ModelAbuseOutcome,
-  limit: number,
-  opts?: { allowedModels?: readonly string[] | undefined },
-): GatewayError {
-  if (!(error instanceof GatewayError)) return error as GatewayError;
-  const model = String(error.details.model ?? "");
-  const message = modelWarningMessage(model, outcome, limit);
-  const hint = opts?.allowedModels?.slice(0, 8);
-  return new GatewayError(error.code, error.status, message, {
-    ...error.details,
-    strikes: outcome.strikes,
-    strike_limit: limit,
-
-    remaining_before_ban: Math.max(0, limit - outcome.strikes),
-    ...(hint && hint.length > 0 ? { allowed_models_hint: hint } : {}),
-  }, error.origin);
-}
-
-interface RequestApp {
-  request(
-    handler: (context: { request: Request; set?: { headers: Record<string, string> } }) => void,
-  ): RequestApp;
-}
-
-export interface RequestContextDeps {
-  readonly stateStore: ProxyRequestStateStore;
-  readonly clock?: () => number;
-  /** Explicit deadline override; defaults to `CARTETHYIA_UPSTREAM_TIMEOUT_MS` (120s). */
-  readonly requestDeadlineMs?: number;
-  readonly maxBodyBytes?: number;
-}
-
-/**
- * Initializes per-request `ProxyRequestState` before any other hook runs.
- * Only gateway (`/v1/*`) requests get state: this middleware is mounted at
- * the composition root so it also observes health checks, console traffic,
- * and dashboard assets, but none of those use proxy state and none of them
- * run the `/v1`-scoped cleanup hooks — initializing for them leaked a state,
- * a deadline timer, a live-controller entry, and an in-flight count per
- * request that was never reclaimed. Cleanup (abort + WeakMap eviction) is
- * intentionally NOT done here via `afterResponse`: Elysia's afterResponse
- * hook order across plugins is not something this composition can guarantee
- * ahead of `createTelemetryLifecycleMiddleware`'s afterResponse (now in
- * lifecycle.ts), which still needs to read the state. The WeakMap entry is
- * reclaimed by GC once `request` is unreferenced; nothing needs to run after
- * the response is sent.
- */
-export function createRequestContextMiddleware(deps: RequestContextDeps): Elysia {
-  const app = new Elysia() as unknown as RequestApp;
-  app.request(({ request, set }) => {
-    const pathname = fastPathname(request.url);
-    if (pathname !== "/v1" && !pathname.startsWith("/v1/")) return;
-    const state = deps.stateStore.initialize(
-      request,
-      (deps.clock ?? (() => Date.now()))(),
-      deps.requestDeadlineMs ?? resolveUpstreamTimeoutMs(),
-    );
-    if (set) {
-      set.headers["x-request-id"] = state.requestId;
-      Object.assign(set.headers, GATEWAY_SECURITY_HEADERS);
-    }
-  });
-  return app as unknown as Elysia;
-}
-
-export function createClientIdentityMiddleware(deps: {
-  readonly stateStore: ProxyRequestStateStore;
-  readonly trustedProxyBoundary: TrustedProxyBoundary;
-  readonly resolvePeerAddress?: (request: Request) => string | null;
-}): Elysia {
-  // `beforeHandle`, not `onRequest`: plugin-scoped `onRequest` hooks do not
-  // fire for these routes under Elysia 2 beta (same scoping gap that muted
-  // plugin `afterResponse` before `registerTelemetryLifecycle`), which left
-  // `clientIdentity` unset and every gateway row without a client IP.
-  // `beforeHandle` hooks from `.use()` plugins run in registration order, so
-  // pipeline position still guarantees this executes before IP-abuse checks.
-  return new Elysia()
-    .beforeHandle(({ request, server }) => {
-      const peer = deps.resolvePeerAddress
-        ? deps.resolvePeerAddress(request)
-        : (server?.requestIP(request)?.address ?? null);
-      if (!peer)
-        throw peerAddressUnavailableError();
-      const address = resolveClientIdentity(request, deps.trustedProxyBoundary, peer);
-      const state = deps.stateStore.require(request);
-      state.clientIdentity = {
-        address,
-        source: address === peer ? "tcp-peer" : "trusted-forwarded-header",
-      };
-      const path = state.ingressPath;
-      if (!isProxyDispatchRoute(path)) return;
-      // The ingress policy stage already decoded the body, so the client's
-      // requested model is readable here — before canonical parsing runs. It is
-      // read defensively and only for display: routing still resolves the model
-      // through the surface adapter, and a body that is not an object simply
-      // yields no model rather than failing the request.
-      const body = state.ingressBody;
-      const requestedModel =
-        body !== null && typeof body === "object" && !Array.isArray(body)
-          ? (body as Record<string, unknown>)["model"]
-          : undefined;
-      const userAgent = request.headers.get("user-agent");
-      pushStructuredConsoleLog("info", "Incoming proxy request", {
-        event: "request_start",
-        requestId: state.requestId,
-        method: request.method,
-        endpoint: path,
-        clientIp: address,
-        ...(typeof requestedModel === "string" && requestedModel.length > 0
-          ? { model: requestedModel }
-          : {}),
-        ...(userAgent === null || userAgent.length === 0
-          ? {}
-          : { userAgent: userAgent.slice(0, 512) }),
-      });
-    })
-    .as("plugin");
-}
-
-export function createCanonicalRequestMiddleware(deps: {
-  readonly stateStore: ProxyRequestStateStore;
-  readonly surfaceRegistry: SurfaceAdapterRegistry;
-  readonly adapters: ReadonlyMap<string, CanonicalAdapter>;
-  /**
-   * Whether this tenant's payload-capture mode keeps request bodies
-   * (`full`). `none`/`metadata` never read the request body at finalize, so
-   * the parsed ingress body can be released as soon as the canonical request
-   * exists instead of being held — across the whole upstream stream. Injected
-   * so this stage does not import the capture policy or the database.
-   */
-  readonly keepsIngressBody: (tenantId: string | null) => Promise<boolean>;
-}): Elysia {
-  return new Elysia()
-    .beforeHandle(async ({ request }) => {
-      const path = fastPathname(request.url);
-      if (!path.startsWith("/v1/")) return;
-      if (request.method === "GET" || request.method === "HEAD") return;
-      // `/v1/completions` needs no separate arm: it is already in
-      // the JSON routes table, so the body-policy predicate covers it.
-      // Native routes (compact, System One) read a body but are never parsed
-      // into a canonical request — their bodies are opaque by contract.
-      if (!isJsonProxyRoutePath(path) || path === "/v1/responses/compact" || isOpaqueBodyRoute(path))
-        return;
-      // Model discovery and other GET/multimodal routes must not go through canonical parsing.
-      const state = deps.stateStore.require(request);
-      // Single-read invariant: the ingress policy middleware already decoded the
-      // body once into `state.ingressBody`. Never re-read `request.body` here —
-      // it is already consumed/locked. `undefined` means the ingress stage did
-      // not run (reduced composition); fail closed. An explicit `null` (JSON
-      // literal `null` body) is a valid single-read value and flows to the
-      // surface adapter's parse error rather than triggering a second read.
-      if (state.ingressBody === undefined)
-        throw new GatewayError("admission_unavailable", 503, "The request body was never read, so this route cannot be served. Resend the request.");
-      const body = state.ingressBody;
-      const headers: Record<string, string> = {};
-      request.headers.forEach((value, key) => {
-        headers[key] = value;
-      });
-      const detection = deps.surfaceRegistry.detectOnce({ body, headers, path });
-      if (detection.disagreement) {
-        // A path-vs-body disagreement is expected traffic, not a fault: a
-        // standard chat body ({model, messages[], max_tokens}) also matches
-        // the messages body shape, so nearly every chat request with
-        // max_tokens "disagrees". Warn only when the explicit header is
-        // involved — a marker contradicting the path means the client is
-        // genuinely confused about which surface it wants.
-        const markerInvolved = detection.signals.some((s) => s.source === "explicit_marker");
-        if (markerInvolved) {
-          log.warn("[surface] conflicting signals detected for surface routing", {
-            resolved: detection.surface,
-            winning_source: detection.winning_source,
-            signals: detection.signals,
-          });
-        } else {
-          log.debug("[surface] ambiguous body shape resolved by endpoint path", {
-            resolved: detection.surface,
-            signals: detection.signals,
-          });
-        }
-      }
-      const adapter = deps.adapters.get(detection.surface);
-      if (!adapter)
-        throw new GatewayError(
-          "capability_unsupported",
-          400,
-          `Surface adapter unavailable: ${detection.surface}`,
-          { surface: detection.surface },
-        );
-      const ingress = deps.stateStore.require(request);
-      const userAgent = headers["user-agent"];
-      if (userAgent) ingress.clientUserAgent = userAgent.slice(0, 512);
-      ingress.canonicalRequest = adapter.parse({ body, headers, path });
-      // The parsed body is the largest per-request value, and once the
-      // canonical request exists the only later reader is payload capture — and
-      // only in `full` mode (see `captureTerminalPayload`). For `none`/`metadata`
-      // drop the reference now: held until cleanup, it would otherwise stay
-      // resident for the entire upstream stream.
-      if (!(await deps.keepsIngressBody(ingress.authorization?.tenantId ?? null))) {
-        ingress.releaseIngressBody();
-      }
-    })
-    .as("plugin");
-}
-
-export function createProxyRoutePreparationMiddleware(deps: {
-  readonly stateStore: ProxyRequestStateStore;
-  readonly preparer: ProxyRequestPreparer;
-  /**
-   * Graduated strikes for repeated invalid-model requests. The preparation step
-   * is the single choke point where a request is rejected for naming a model the
-   * key may not use (`isModelAllowed`) or a model that resolves to nothing
-   * (`modelNotFoundError`), so it is where a strike is recorded and where a
-   * valid model clears one.
-   */
-  readonly modelStrikes?: ModelStrikeService;
-}): Elysia {
-  return new Elysia()
-    .beforeHandle(async ({ request }) => {
-      const path = fastPathname(request.url);
-      if (!path.startsWith("/v1/")) return;
-      if (request.method === "GET" || request.method === "HEAD") return;
-      const isJsonRoute = isJsonProxyRoutePath(path);
-      if (!isJsonRoute || path === "/v1/responses/compact" || isOpaqueBodyRoute(path)) return;
-      const state = deps.stateStore.require(request);
-      if (!state.authorization || !state.canonicalRequest)
-        throw new GatewayError("admission_unavailable", 503, "The request was not authenticated and parsed, so this route cannot be served. Resend the request.");
-      const strikes = deps.modelStrikes;
-      const ip = state.clientIdentity?.address;
-      // The key rides along so a strike is charged to the caller that made it.
-      // Without it, one recipient of a shared link could escalate a ban onto
-      // every other caller behind the same address.
-      const strikeIdentity =
-        strikes && ip !== undefined
-          ? { strikes, ip, apiKeyId: state.authorization?.id ?? null }
-          : undefined;
-      try {
-        state.preparedRequest = await deps.preparer.prepare({
-          canonicalRequest: state.canonicalRequest,
-          authorization: state.authorization,
-          deadlineMs: state.deadlineMs,
-          signal: state.abortController.signal,
-          ...(state.clientUserAgent === undefined
-            ? {}
-            : { clientUserAgent: state.clientUserAgent }),
-        });
-      } catch (error) {
-        // Only a *model* rejection is a strike: an invalid model the key may not
-        // use, or a name that resolves to nothing. A store outage, an aborted
-        // request, or any other failure is not the caller probing for models.
-        if (strikeIdentity && isModelRejection(error)) {
-          const outcome = await strikeIdentity.strikes
-            .noteInvalid({ ip: strikeIdentity.ip, apiKeyId: strikeIdentity.apiKeyId })
-            .catch(() => null);
-          if (outcome?.banned === true) throw modelAbuseBannedError();
-          if (outcome) {
-            const snap = state.authorization?.snapshot;
-            const raw = snap?.model_list;
-            const hint = Array.isArray(raw) ? (raw as readonly string[]) : raw instanceof Set ? [...raw] : undefined;
-            throw withModelWarning(error, outcome, strikeIdentity.strikes.limit, {
-              allowedModels: hint,
-            });
-          }
-        }
-        throw error;
-      }
-      // A valid model does not reset the invalid-attempt window. Old attempts
-      // leave only when they age out of that window.
-      if (strikeIdentity)
-        void strikeIdentity.strikes
-          .noteValid({ ip: strikeIdentity.ip })
-          .catch(() => undefined);
-    })
-    .as("plugin");
-}
+// Per-request context, client identity, canonical parse, and route preparation.
+import { Elysia } from "elysia";
+import { GatewayError } from "../../protocol/gateway-error";
+import type { TrustedProxyBoundary } from "../../config/network";
+import { resolveUpstreamTimeoutMs } from "../../config/timeouts";
+import type { ProxyRequestStateStore } from "../request/state";
+import { fastPathname } from "../pathname";
+import type { ProxyRequestPreparer } from "../request/preparer";
+import type { CanonicalAdapter } from "../contracts";
+import type { SurfaceAdapterRegistry } from "../surface/adapters";
+import { resolveClientIdentity } from "../../security/ip-boundary";
+import { GATEWAY_SECURITY_HEADERS } from "../../security/outbound-headers";
+import { pushStructuredConsoleLog } from "../../observability/log-ring";
+import { log } from "../../observability/logger";
+import { isJsonProxyRoutePath, isProxyDispatchRoute } from "./body-policy";
+import { isOpaqueBodyRoute } from "../contracts";
+import { peerAddressUnavailableError } from "./guard-errors";
+
+
+
+interface RequestApp {
+  request(
+    handler: (context: { request: Request; set?: { headers: Record<string, string> } }) => void,
+  ): RequestApp;
+}
+
+export interface RequestContextDeps {
+  readonly stateStore: ProxyRequestStateStore;
+  readonly clock?: () => number;
+  /** Explicit deadline override; defaults to `CARTETHYIA_UPSTREAM_TIMEOUT_MS` (120s). */
+  readonly requestDeadlineMs?: number;
+  readonly maxBodyBytes?: number;
+}
+
+/**
+ * Initializes per-request `ProxyRequestState` before any other hook runs.
+ * Only gateway (`/v1/*`) requests get state: this middleware is mounted at
+ * the composition root so it also observes health checks, console traffic,
+ * and dashboard assets, but none of those use proxy state and none of them
+ * run the `/v1`-scoped cleanup hooks — initializing for them leaked a state,
+ * a deadline timer, a live-controller entry, and an in-flight count per
+ * request that was never reclaimed. Cleanup (abort + WeakMap eviction) is
+ * intentionally NOT done here via `afterResponse`: Elysia's afterResponse
+ * hook order across plugins is not something this composition can guarantee
+ * ahead of `createTelemetryLifecycleMiddleware`'s afterResponse (now in
+ * lifecycle.ts), which still needs to read the state. The WeakMap entry is
+ * reclaimed by GC once `request` is unreferenced; nothing needs to run after
+ * the response is sent.
+ */
+export function createRequestContextMiddleware(deps: RequestContextDeps): Elysia {
+  const app = new Elysia() as unknown as RequestApp;
+  app.request(({ request, set }) => {
+    const pathname = fastPathname(request.url);
+    if (pathname !== "/v1" && !pathname.startsWith("/v1/")) return;
+    const state = deps.stateStore.initialize(
+      request,
+      (deps.clock ?? (() => Date.now()))(),
+      deps.requestDeadlineMs ?? resolveUpstreamTimeoutMs(),
+    );
+    if (set) {
+      set.headers["x-request-id"] = state.requestId;
+      Object.assign(set.headers, GATEWAY_SECURITY_HEADERS);
+    }
+  });
+  return app as unknown as Elysia;
+}
+
+export function createClientIdentityMiddleware(deps: {
+  readonly stateStore: ProxyRequestStateStore;
+  readonly trustedProxyBoundary: TrustedProxyBoundary;
+  readonly resolvePeerAddress?: (request: Request) => string | null;
+}): Elysia {
+  // `beforeHandle`, not `onRequest`: plugin-scoped `onRequest` hooks do not
+  // fire for these routes under Elysia 2 beta (same scoping gap that muted
+  // plugin `afterResponse` before `registerTelemetryLifecycle`), which left
+  // `clientIdentity` unset and every gateway row without a client IP.
+  // `beforeHandle` hooks from `.use()` plugins run in registration order, so
+  // pipeline position still guarantees this executes before IP-abuse checks.
+  return new Elysia()
+    .beforeHandle(({ request, server }) => {
+      const peer = deps.resolvePeerAddress
+        ? deps.resolvePeerAddress(request)
+        : (server?.requestIP(request)?.address ?? null);
+      if (!peer)
+        throw peerAddressUnavailableError();
+      const address = resolveClientIdentity(request, deps.trustedProxyBoundary, peer);
+      const state = deps.stateStore.require(request);
+      state.clientIdentity = {
+        address,
+        source: address === peer ? "tcp-peer" : "trusted-forwarded-header",
+      };
+      const path = state.ingressPath;
+      if (!isProxyDispatchRoute(path)) return;
+      // The ingress policy stage already decoded the body, so the client's
+      // requested model is readable here — before canonical parsing runs. It is
+      // read defensively and only for display: routing still resolves the model
+      // through the surface adapter, and a body that is not an object simply
+      // yields no model rather than failing the request.
+      const body = state.ingressBody;
+      const requestedModel =
+        body !== null && typeof body === "object" && !Array.isArray(body)
+          ? (body as Record<string, unknown>)["model"]
+          : undefined;
+      const userAgent = request.headers.get("user-agent");
+      pushStructuredConsoleLog("info", "Incoming proxy request", {
+        event: "request_start",
+        requestId: state.requestId,
+        method: request.method,
+        endpoint: path,
+        clientIp: address,
+        ...(typeof requestedModel === "string" && requestedModel.length > 0
+          ? { model: requestedModel }
+          : {}),
+        ...(userAgent === null || userAgent.length === 0
+          ? {}
+          : { userAgent: userAgent.slice(0, 512) }),
+      });
+    })
+    .as("plugin");
+}
+
+export function createCanonicalRequestMiddleware(deps: {
+  readonly stateStore: ProxyRequestStateStore;
+  readonly surfaceRegistry: SurfaceAdapterRegistry;
+  readonly adapters: ReadonlyMap<string, CanonicalAdapter>;
+  /**
+   * Whether this tenant's payload-capture mode keeps request bodies
+   * (`full`). `none`/`metadata` never read the request body at finalize, so
+   * the parsed ingress body can be released as soon as the canonical request
+   * exists instead of being held — across the whole upstream stream. Injected
+   * so this stage does not import the capture policy or the database.
+   */
+  readonly keepsIngressBody: (tenantId: string | null) => Promise<boolean>;
+}): Elysia {
+  return new Elysia()
+    .beforeHandle(async ({ request }) => {
+      const path = fastPathname(request.url);
+      if (!path.startsWith("/v1/")) return;
+      if (request.method === "GET" || request.method === "HEAD") return;
+      // `/v1/completions` needs no separate arm: it is already in
+      // the JSON routes table, so the body-policy predicate covers it.
+      // Native routes (compact, System One) read a body but are never parsed
+      // into a canonical request — their bodies are opaque by contract.
+      if (!isJsonProxyRoutePath(path) || path === "/v1/responses/compact" || isOpaqueBodyRoute(path))
+        return;
+      // Model discovery and other GET/multimodal routes must not go through canonical parsing.
+      const state = deps.stateStore.require(request);
+      // Single-read invariant: the ingress policy middleware already decoded the
+      // body once into `state.ingressBody`. Never re-read `request.body` here —
+      // it is already consumed/locked. `undefined` means the ingress stage did
+      // not run (reduced composition); fail closed. An explicit `null` (JSON
+      // literal `null` body) is a valid single-read value and flows to the
+      // surface adapter's parse error rather than triggering a second read.
+      if (state.ingressBody === undefined)
+        throw new GatewayError("admission_unavailable", 503, "The request body was never read, so this route cannot be served. Resend the request.");
+      const body = state.ingressBody;
+      const headers: Record<string, string> = {};
+      request.headers.forEach((value, key) => {
+        headers[key] = value;
+      });
+      const detection = deps.surfaceRegistry.detectOnce({ body, headers, path });
+      if (detection.disagreement) {
+        // A path-vs-body disagreement is expected traffic, not a fault: a
+        // standard chat body ({model, messages[], max_tokens}) also matches
+        // the messages body shape, so nearly every chat request with
+        // max_tokens "disagrees". Warn only when the explicit header is
+        // involved — a marker contradicting the path means the client is
+        // genuinely confused about which surface it wants.
+        const markerInvolved = detection.signals.some((s) => s.source === "explicit_marker");
+        if (markerInvolved) {
+          log.warn("[surface] conflicting signals detected for surface routing", {
+            resolved: detection.surface,
+            winning_source: detection.winning_source,
+            signals: detection.signals,
+          });
+        } else {
+          log.debug("[surface] ambiguous body shape resolved by endpoint path", {
+            resolved: detection.surface,
+            signals: detection.signals,
+          });
+        }
+      }
+      const adapter = deps.adapters.get(detection.surface);
+      if (!adapter)
+        throw new GatewayError(
+          "capability_unsupported",
+          400,
+          `Surface adapter unavailable: ${detection.surface}`,
+          { surface: detection.surface },
+        );
+      const ingress = deps.stateStore.require(request);
+      const userAgent = headers["user-agent"];
+      if (userAgent) ingress.clientUserAgent = userAgent.slice(0, 512);
+      ingress.canonicalRequest = adapter.parse({ body, headers, path });
+      // The parsed body is the largest per-request value, and once the
+      // canonical request exists the only later reader is payload capture — and
+      // only in `full` mode (see `captureTerminalPayload`). For `none`/`metadata`
+      // drop the reference now: held until cleanup, it would otherwise stay
+      // resident for the entire upstream stream.
+      if (!(await deps.keepsIngressBody(ingress.authorization?.tenantId ?? null))) {
+        ingress.releaseIngressBody();
+      }
+    })
+    .as("plugin");
+}
+
+export function createProxyRoutePreparationMiddleware(deps: {
+  readonly stateStore: ProxyRequestStateStore;
+  readonly preparer: ProxyRequestPreparer;
+}): Elysia {
+  return new Elysia()
+    .beforeHandle(async ({ request }) => {
+      const path = fastPathname(request.url);
+      if (!path.startsWith("/v1/")) return;
+      if (request.method === "GET" || request.method === "HEAD") return;
+      const isJsonRoute = isJsonProxyRoutePath(path);
+      if (!isJsonRoute || path === "/v1/responses/compact" || isOpaqueBodyRoute(path)) return;
+      const state = deps.stateStore.require(request);
+      if (!state.authorization || !state.canonicalRequest)
+        throw new GatewayError("admission_unavailable", 503, "The request was not authenticated and parsed, so this route cannot be served. Resend the request.");
+      // The key rides along so a strike is charged to the caller that made it.
+      // Without it, one recipient of a shared link could escalate a ban onto
+      try {
+        state.preparedRequest = await deps.preparer.prepare({
+          canonicalRequest: state.canonicalRequest,
+          authorization: state.authorization,
+          deadlineMs: state.deadlineMs,
+          signal: state.abortController.signal,
+          ...(state.clientUserAgent === undefined
+            ? {}
+            : { clientUserAgent: state.clientUserAgent }),
+        });
+      } catch (error) {
+        throw error;
+      }
+    })
+    .as("plugin");
+}

package/src/transport/request/inflight.ts

@@ -22,12 +22,23 @@ import { metrics } from "../../observability/metrics";
 export interface InFlightSnapshot {
   readonly inFlight: number;
   readonly uniqueIps: number;
+  /**
+   * How long the longest-lived flight has been tracked, in milliseconds.
+   *
+   * The count alone cannot tell a healthy queue from a leak: six flights
+   * could be six requests in progress or six that never finished. The age
+   * separates them — a flight far past its own deadline is the backstop's
+   * job, so a growing age with a flat count means the sweep is not running.
+   */
+  readonly oldestAgeMs: number;
 }
 
 interface Flight {
   readonly clientIp: string;
   /** Hard deadline after which the backstop sweep releases this flight. */
   expiresAtMs: number;
+  /** When this flight was tracked, for the age reported in a snapshot. */
+  readonly startedAtMs: number;
 }
 
 export interface InFlightRegistry {
@@ -50,14 +61,18 @@ export function createInFlightRegistry(): InFlightRegistry {
 
   const snapshot = (): InFlightSnapshot => {
     let uniqueIps = 0;
+    let oldest = 0;
+    const now = Date.now();
     const seen = new Set<string>();
     for (const flight of flights.values()) {
       if (!seen.has(flight.clientIp)) {
         seen.add(flight.clientIp);
         uniqueIps += 1;
       }
+      const age = now - flight.startedAtMs;
+      if (age > oldest) oldest = age;
     }
-    return { inFlight: flights.size, uniqueIps };
+    return { inFlight: flights.size, uniqueIps, oldestAgeMs: oldest };
   };
 
   const publish = (): void => {
@@ -68,7 +83,11 @@ export function createInFlightRegistry(): InFlightRegistry {
 
   return {
     track(requestId, clientIp, expiresAtMs) {
-      flights.set(requestId, { clientIp: clientIp.length > 0 ? clientIp : "unknown", expiresAtMs });
+      flights.set(requestId, {
+        clientIp: clientIp.length > 0 ? clientIp : "unknown",
+        expiresAtMs,
+        startedAtMs: Date.now(),
+      });
       publish();
     },
     untrack(requestId) {