cartethyia 2.4.4 → 2.4.6

package/src/console/share/share-stats.ts

@@ -227,12 +227,19 @@ const TOP_IPS_LIMIT = 50;
 const HOURS_WINDOW = 24;
 
 /**
- * Cache lifetime for one family's rollup. Equal to the share page's 2 s SSE
- * tick: a viewer cannot observe staleness longer than the refresh it already
- * accepts, while every viewer of one link shares a single computation. Declared
- * here rather than imported from the router so this port does not depend on it.
+ * Cache lifetime for one family's rollup.
+ *
+ * Matched to the share page's SSE tick, which was the point of the old 2 s
+ * value — but at 2 s the cache expired on every tick, so every single push was
+ * a full parse of the retained telemetry window. A share page's numbers move
+ * when a request does, not every 2 s; 10 s still reads as live, and cuts the
+ * parse rate by five.
+ *
+ * Declared here rather than imported from the router so this port does not
+ * depend on it. `SHARE_STATS_STREAM_INTERVAL_MS` must be raised with it, or
+ * the two drift apart and the cache expires between ticks for no reason.
  */
-export const SHARE_STATS_CACHE_TTL_SECONDS = 2;
+export const SHARE_STATS_CACHE_TTL_SECONDS = 10;
 
 /**
  * Cache key for one family's rollup. Both inputs change the payload — `keyIds`

package/src/console/shared/read-through-cache.ts

@@ -10,8 +10,26 @@
  * A Redis that is slow or down must never fail a request: every cache step
  * falls through to computing the answer, which is exactly what the request
  * would have done before there was a cache.
+ *
+ * ## Validators
+ *
+ * The endpoints answer dashboard polls that repeat every few seconds while the
+ * underlying telemetry window changes every minute. Without a validator every
+ * poll ships the whole payload — 8.8 KiB to 150 KiB of it — even when nothing
+ * changed. An ETag turns that into a ~200-byte `304`.
+ *
+ * Strong, not weak: the hash covers the exact serialized bytes the client
+ * would otherwise have received, so a matching validator means byte-identical
+ * content. A weaker or unstable hash would answer `304` for changed data and
+ * leave the dashboard showing stale numbers, which is worse than the bytes it
+ * saves.
+ *
+ * The ETag is computed **once per write**, never per read: hashing a 150 KiB
+ * body on every poll would move the cost off the wire and onto the CPU.
  */
 
+import { createHash } from "node:crypto";
+
 /** The slice of Redis this cache needs, so it can be tested without a server. */
 export interface ReadThroughCacheClient {
   get(key: string): Promise<string | null>;
@@ -25,25 +43,133 @@ export interface ReadThroughCacheClient {
  */
 export const READ_THROUGH_DEFAULT_TTL_SECONDS = 10;
 
-/** `undefined` when the row was never cached, so a computed `null` is cacheable. */
-export async function cachedRead<T>(
+/** The cached value plus the strong validator for the bytes it serializes to. */
+export interface CachedResult<T> {
+  readonly value: T;
+  readonly etag: string;
+}
+
+/** Quoted per RFC 9110: an entity-tag is always `"…"`. */
+function etagFor(bytes: string): string {
+  // SHA-256 over the exact serialized bytes. Not the FNV-1a in
+  // `payload-store.ts` — that one is module-private, and adding a second hash
+  // implementation would risk two different collision profiles for one
+  // purpose. SHA-256 is already used in `share-stats.ts` for cache identity.
+  return `"${createHash("sha256").update(bytes, "utf8").digest("hex").slice(0, 32)}"`;
+}
+
+/** The sibling key holding the validator, so a cached body is never re-hashed. */
+export function etagKey(key: string): string {
+  return `${key}:etag`;
+}
+
+/**
+ * Reads through the cache and returns a strong validator alongside the value.
+ *
+ * The validator is computed once, at the moment the body is written, and read
+ * back from its own key: a hit never hashes the payload. On a validator miss
+ * with a body hit — a partial eviction, or a row written by an older build —
+ * the body is re-hashed rather than discarded, so the pair cannot disagree.
+ *
+ * With no cache configured (`client === undefined`) the value is computed and
+ * the validator is still returned, so conditional requests keep working for
+ * the length of the client's own polling loop; only the cross-instance sharing
+ * is lost.
+ */
+export async function cachedReadWithEtag<T>(
   client: ReadThroughCacheClient | undefined,
   key: string,
   compute: () => Promise<T>,
   ttlSeconds: number = READ_THROUGH_DEFAULT_TTL_SECONDS,
-): Promise<T> {
-  if (client === undefined) return compute();
+): Promise<CachedResult<T>> {
+  if (client === undefined) {
+    const fresh = await compute();
+    return { value: fresh, etag: etagFor(JSON.stringify(fresh) ?? "null") };
+  }
   try {
     const hit = await client.get(key);
-    if (hit !== null) return JSON.parse(hit) as T;
+    if (hit !== null) {
+      const value = JSON.parse(hit) as T;
+      try {
+        const stored = await client.get(etagKey(key));
+        return { value, etag: stored ?? etagFor(hit) };
+      } catch {
+        return { value, etag: etagFor(hit) };
+      }
+    }
   } catch {
-    return compute();
+    // A cache read must never fail a request; compute instead.
   }
   const value = await compute();
+  const bytes = JSON.stringify(value) ?? "null";
+  const etag = etagFor(bytes);
   try {
-    await client.set(key, JSON.stringify(value), "EX", ttlSeconds);
+    await client.set(key, bytes, "EX", ttlSeconds);
+    await client.set(etagKey(key), etag, "EX", ttlSeconds);
   } catch {
     // A cache write must never fail a request that already has its answer.
   }
+  return { value, etag };
+}
+
+/** `undefined` when the row was never cached, so a computed `null` is cacheable. */
+export async function cachedRead<T>(
+  client: ReadThroughCacheClient | undefined,
+  key: string,
+  compute: () => Promise<T>,
+  ttlSeconds: number = READ_THROUGH_DEFAULT_TTL_SECONDS,
+): Promise<T> {
+  const { value } = await cachedReadWithEtag(client, key, compute, ttlSeconds);
   return value;
 }
+
+/**
+ * `cache-control` for a cached console read.
+ *
+ * `no-cache`, not `no-store`: the response may be stored, it simply must be
+ * revalidated, which is exactly what the ETag is for. `no-store` would forbid
+ * storing and so forbid the `304` this exists to enable.
+ */
+const CACHE_CONTROL = "no-cache";
+
+/**
+ * Answers a conditional GET from a {@link CachedResult}.
+ *
+ * A match returns a bodiless `304`. An `If-None-Match` that does not match, or
+ * a request that sent none, returns the body with the validator attached so
+ * the next poll can be the cheap one.
+ *
+ * `If-None-Match` may carry several validators or the `*` form, so the header
+ * is parsed rather than compared as one string.
+ */
+export function conditionalResponse<T>(
+  ifNoneMatch: string | null,
+  result: CachedResult<T>,
+  body: unknown,
+): Response {
+  if (matchesEtag(ifNoneMatch, result.etag)) {
+    return new Response(null, {
+      status: 304,
+      headers: { etag: result.etag, "cache-control": CACHE_CONTROL },
+    });
+  }
+  const response = Response.json(body);
+  response.headers.set("etag", result.etag);
+  response.headers.set("cache-control", CACHE_CONTROL);
+  return response;
+}
+
+/** True when an `If-None-Match` header names this validator. */
+export function matchesEtag(header: string | null, etag: string): boolean {
+  if (header === null) return false;
+  const trimmed = header.trim();
+  if (trimmed === "*") return true;
+  for (const part of trimmed.split(",")) {
+    // The weak prefix is stripped: a weak validator still names the same
+    // representation, and the client that sent it asked to be told if the
+    // current one matches.
+    const candidate = part.trim().replace(/^W\//, "");
+    if (candidate === etag) return true;
+  }
+  return false;
+}

package/src/console/updates/repository-updates.ts

@@ -1,34 +1,39 @@
-/**
- * Public release discovery for the console's update indicator.
- *
- * The browser never talks to GitHub directly: a dashboard-side fetch would put
- * every console user's GitHub rate limit behind one shared, unauthenticated
- * origin, and a CORS or rate-limit failure would surface as a console error
- * nobody can act on. The request is made here, server-side, and any failure
- * degrades to "no update known" rather than an error the operator must read.
- */
-const REPOSITORY = "risunCode/Cartethyia";
-
-/** Timeout for one GitHub read. A hung read must not hold a console query open. */
-const REQUEST_TIMEOUT_MS = 10_000;
-
-export interface LatestRelease {
-  readonly tag_name: string;
-  readonly html_url: string;
-}
-
-/** Fetches the latest public release. Returns `null` when none is known. */
-export async function fetchLatestRelease(): Promise<LatestRelease | null> {
-  try {
-    const response = await fetch(`https://api.github.com/repos/${REPOSITORY}/releases/latest`, {
-      headers: { accept: "application/vnd.github+json", "user-agent": "Cartethyia-updater" },
-      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
-    });
-    if (!response.ok) return null;
-    const value = (await response.json()) as { readonly tag_name?: unknown; readonly html_url?: unknown };
-    if (typeof value.tag_name !== "string" || typeof value.html_url !== "string") return null;
-    return { tag_name: value.tag_name, html_url: value.html_url };
-  } catch {
-    return null;
-  }
-}
+/**
+ * Public release discovery for the console's update indicator.
+ *
+ * The browser never talks to GitHub directly: a dashboard-side fetch would put
+ * every console user's GitHub rate limit behind one shared, unauthenticated
+ * origin, and a CORS or rate-limit failure would surface as a console error
+ * nobody can act on. The request is made here, server-side, and any failure
+ * degrades to "no update known" rather than an error the operator must read.
+ *
+ * Releases are read from the ALTERNATIVE repository (`risunCodex`), not the
+ * primary: the primary repository is hidden from public view, so its releases
+ * endpoint answers 404 and the console would report "no update known" forever —
+ * a silent failure that reads exactly like "you are up to date".
+ */
+const REPOSITORY = "risunCodex/Cartethyia";
+
+/** Timeout for one GitHub read. A hung read must not hold a console query open. */
+const REQUEST_TIMEOUT_MS = 10_000;
+
+export interface LatestRelease {
+  readonly tag_name: string;
+  readonly html_url: string;
+}
+
+/** Fetches the latest public release. Returns `null` when none is known. */
+export async function fetchLatestRelease(): Promise<LatestRelease | null> {
+  try {
+    const response = await fetch(`https://api.github.com/repos/${REPOSITORY}/releases/latest`, {
+      headers: { accept: "application/vnd.github+json", "user-agent": "Cartethyia-updater" },
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    if (!response.ok) return null;
+    const value = (await response.json()) as { readonly tag_name?: unknown; readonly html_url?: unknown };
+    if (typeof value.tag_name !== "string" || typeof value.html_url !== "string") return null;
+    return { tag_name: value.tag_name, html_url: value.html_url };
+  } catch {
+    return null;
+  }
+}

package/src/network/outbound-fetch.ts

@@ -9,6 +9,7 @@ import type { SsrfPolicy } from "../config/network";
 import { isProxyAgentPair, type ProxyAgentPair } from "./pool/agent";
 import { metrics } from "../observability/metrics";
 import { trackNetworkCall } from "../observability/performance-metrics";
+import { bunClientHelloOptions } from "./tls/bun-client-hello";
 import { stripResponseHeaders } from "./response-headers";
 // Validated fetch — single egress with ProxyAgent support
 export interface ValidatedFetchOptions {
@@ -17,6 +18,14 @@ export interface ValidatedFetchOptions {
   readonly maxRedirects?: number;
   readonly resolveFn?: (hostname: string, signal: AbortSignal) => Promise<readonly string[]>;
   readonly agent?: HttpAgent | HttpsAgent | ProxyAgentPair;
+  /**
+   * Handshake with Bun's cipher list, curve list and ALPN instead of
+   * OpenSSL's defaults. Opt-in, and off by default: see
+   * `network/tls/bun-client-hello.ts` — ciphers and curves match exactly, but
+   * the extension list cannot be shaped from Node, so this is a closer hello
+   * rather than an identical one.
+   */
+  readonly bunClientHello?: boolean;
 }
 export type ValidatedFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
 
@@ -34,6 +43,57 @@ function agentForTarget(
   return agent;
 }
 
+/**
+ * Keep-alive options for the direct (non-pool) egress agents.
+ *
+ * Matched to `network/pool/agent.ts`, which builds pool agents from
+ * `resolveProxyMaxSockets()` / `resolveProxyMaxFreeSockets()` and
+ * `PROXY_KEEP_ALIVE_TIMEOUT_MS`. Direct egress has no per-pool config to
+ * read, so it uses the documented defaults those resolvers return.
+ */
+const DIRECT_AGENT_OPTIONS = {
+  keepAlive: true,
+  maxSockets: 100,
+  maxFreeSockets: 20,
+  timeout: 60_000,
+} as const;
+
+/**
+ * An agent whose socket key includes the SSRF-validated address.
+ *
+ * The direct (non-pool) path pins egress by passing a `lookup` that returns the
+ * one validated address, but `Agent#getName` — the keep-alive socket key —
+ * hashes only host/port/localAddress/family. Two requests to the same
+ * `host:port` that validated to *different* addresses therefore share a pooled
+ * socket, and the second one silently egresses to the first one's address:
+ * the pin is bypassed without any error surfacing.
+ *
+ * Including the address in the key makes each validated address its own socket
+ * bucket, so a re-resolved address always dials fresh while the *same* address
+ * still reuses its socket (keep-alive is preserved, not defeated).
+ *
+ * This is a real gap, not a theoretical one: with no agent at all the request
+ * falls back to the global agent, which has the same key shape *and* is shared
+ * with unrelated traffic.
+ */
+class PinnedAddressAgent extends HttpAgent {
+  override getName(options: Record<string, unknown> = {}): string {
+    const base = super.getName(options as never);
+    const pinned = (options["lookup"] as { pinnedAddress?: string } | undefined)?.pinnedAddress;
+    return `${base}:${pinned ?? "-"}`;
+  }
+}
+class PinnedAddressHttpsAgent extends HttpsAgent {
+  override getName(options: Record<string, unknown> = {}): string {
+    const base = super.getName(options as never);
+    const pinned = (options["lookup"] as { pinnedAddress?: string } | undefined)?.pinnedAddress;
+    return `${base}:${pinned ?? "-"}`;
+  }
+}
+
+const DIRECT_HTTP_AGENT = new PinnedAddressAgent(DIRECT_AGENT_OPTIONS);
+const DIRECT_HTTPS_AGENT = new PinnedAddressHttpsAgent(DIRECT_AGENT_OPTIONS);
+
 /**
  * Builds the application-relay request used by hosted relay front doors.
  * These endpoints intentionally do not receive CONNECT: they accept the
@@ -99,10 +159,12 @@ function decompressBody(
   return { stream: body.pipe(decoder), encoding: undefined };
 }
 
-async function pinnedFetch(  url: URL,
+async function pinnedFetch(
+  url: URL,
   init: RequestInit,
   resolvedAddress: string | undefined,
   agent?: HttpAgent | HttpsAgent,
+  useBunHello = false,
 ): Promise<Response> {
   const request = url.protocol === "https:" ? httpsRequest : httpRequest;
   const headers = new Headers(init.headers);
@@ -126,27 +188,38 @@ async function pinnedFetch(  url: URL,
     outboundHeaders["content-length"] =
       typeof body === "string" ? String(Buffer.byteLength(body, "utf8")) : String(body.byteLength);
   }
-  const lookup = ((
-    _hostname: string,
-    options: { all?: boolean; family?: number } | number,
-    callback: (
-      error: Error | null,
-      address?: string | Array<{ address: string; family: number }>,
-      family?: number,
-    ) => void,
-  ): void => {
-    if (resolvedAddress === undefined) {
-      callback(new Error("no validated address available"));
-      return;
-    }
-    const opts = typeof options === "number" ? { family: options } : options;
-    const family = resolvedAddress.includes(":") ? 6 : 4;
-    if (opts?.all) {
-      callback(null, [{ address: resolvedAddress, family }] as never);
-      return;
-    }
-    callback(null, resolvedAddress, family);
-  }) as unknown as NonNullable<RequestOptions["lookup"]>;
+  const lookup = Object.assign(
+    (
+      _hostname: string,
+      options: { all?: boolean; family?: number } | number,
+      callback: (
+        error: Error | null,
+        address?: string | Array<{ address: string; family: number }>,
+        family?: number,
+      ) => void,
+    ): void => {
+      if (resolvedAddress === undefined) {
+        callback(new Error("no validated address available"));
+        return;
+      }
+      const opts = typeof options === "number" ? { family: options } : options;
+      const family = resolvedAddress.includes(":") ? 6 : 4;
+      if (opts?.all) {
+        callback(null, [{ address: resolvedAddress, family }] as never);
+        return;
+      }
+      callback(null, resolvedAddress, family);
+    },
+    // Read by `PinnedAddressAgent#getName` so the keep-alive socket key
+    // carries the validated address. See the class comment for why.
+    { pinnedAddress: resolvedAddress },
+  ) as unknown as NonNullable<RequestOptions["lookup"]>;
+  // Direct egress gets a dedicated agent as well as the pinning `lookup`.
+  // Passing only `lookup` left the request on the global agent, whose socket
+  // key ignores `lookup` — so a re-resolved address could reuse a socket
+  // dialed against an earlier one and egress past the SSRF check. The direct
+  // agent keys its sockets on the pinned address, so the pin holds.
+  const directAgent = url.protocol === "https:" ? DIRECT_HTTPS_AGENT : DIRECT_HTTP_AGENT;
   return new Promise<Response>((resolve, reject) => {
     const nodeRequest = request(
       {
@@ -157,8 +230,17 @@ async function pinnedFetch(  url: URL,
         method: init.method ?? "GET",
         headers: outboundHeaders,
         signal: init.signal ?? undefined,
-        ...(agent ? { agent } : { lookup }),
+        ...(agent ? { agent } : { agent: directAgent, lookup }),
         ...(url.protocol === "https:" ? { servername: url.hostname } : {}),
+        // Bun's cipher list, curve list, ALPN and version span, when this
+        // request opted into it. See `network/tls/bun-client-hello.ts` for
+        // what this does and does not match: ciphers and curves land exactly;
+        // the extension list cannot be shaped from Node at all.
+        //
+        // Opt-in, and off by default. It changes the TLS handshake of every
+        // request it touches, and no provider needs it until the free-tier
+        // gate is shown to reject the default hello.
+        ...(useBunHello && url.protocol === "https:" ? bunClientHelloOptions() : {}),
       },
       (response) => {
         const responseHeaders = stripResponseHeaders(response.headers);
@@ -230,7 +312,7 @@ export function createValidatedFetch(options: ValidatedFetchOptions = {}): Valid
         // The egress dials the pool/relay, which resolves the target itself.
         // Counting these lets ops confirm how much traffic depends on
         // proxy-resolved DNS rather than the local system resolver.
-        metrics.cartethyia_proxy_dial_dns_fallback_total.inc();
+        metrics.cartethyia_proxy_dial_proxy_resolved_total.inc();
       }
       try {
         if (!poolDialsTarget) {
@@ -263,7 +345,13 @@ export function createValidatedFetch(options: ValidatedFetchOptions = {}): Valid
         response = await options.fetchFn(url, requestInit);
       } else {
         const agent = agentForTarget(configuredAgent, url.protocol);
-        response = await pinnedFetch(url, requestInit, resolvedAddress!, agent);
+        response = await pinnedFetch(
+          url,
+          requestInit,
+          resolvedAddress!,
+          agent,
+          options.bunClientHello === true,
+        );
       }
       if (response.status < 300 || response.status >= 400) {
         trackNetworkCall(url.hostname, performance.now() - startedAt);

package/src/network/tls/bun-client-hello.ts

@@ -0,0 +1,112 @@
+import type { Socket } from "node:net";
+import { connect as tlsConnect, type ConnectionOptions } from "node:tls";
+
+/**
+ * A TLS ClientHello that matches Bun's fetch, for the paths that cannot use
+ * Bun's own `fetch`.
+ *
+ * `opencode2api` impersonates OpenCode by impersonating **Bun** — the official
+ * clients are Bun programs, and the free-tier gate fingerprints the TLS
+ * ClientHello, not just headers. It needed `utls` to do that, because Go's
+ * `crypto/tls` cannot change its hello. We are on Bun, so `fetch()` already
+ * emits the right one — but our outbound path is `node:https`, which emits
+ * OpenSSL's.
+ *
+ * This module narrows the gap on the Node path. **It does not close it**, and
+ * the shortfall is stated plainly below because it decides whether this is
+ * worth using at all.
+ *
+ * What it matches, measured:
+ *
+ * | Field | Bun | This module |
+ * |---|---|---|
+ * | Cipher count | 17 | **17** |
+ * | Cipher order | `1301-1302-1303-c02b-c02f-c02c-c030-cca9-cca8-c009-c013-c00a-c014-009c-009d-002f-0035` | **identical** |
+ * | Curves | `4588,29,23,24` | **`4588,29,23,24`** |
+ * | ALPN | `http/1.1` only | **`http/1.1` only** |
+ * | TLS span | 1.2–1.3 | **1.2–1.3** |
+ * | Extensions | 13, order `0,23,65281,10,11,35,16,5,13,18,51,45,43` | **11, `0,23,65281,10,11,35,16,13,51,45,43`** |
+ *
+ * The extension list is the part Node cannot reach. The first seven match
+ * exactly, then it diverges: `status_request` (5, OCSP stapling) and
+ * `signed_certificate_timestamp` (18, SCT) are absent, and BoringSSL sends
+ * both between ALPN and `signature_algorithms`. Neither has a Node option.
+ * No extension we send is foreign to Bun's — we send a subset, not a
+ * different set.
+ *
+ * **So this is a closer hello, not an identical one.** If the gate's check is
+ * JA3/JA4-shaped — and the reference gateway's own comment names JA4
+ * `t13d1713h1`, which is computed from the extension list — this will not pass
+ * it. Use `fetch` through a CONNECT bridge (`outbound-fetch.ts`) where an exact
+ * match is required; that path measures identical, all 13 extensions in order.
+ *
+ * Kept because it is still strictly better than the OpenSSL default (52 ciphers
+ * in OpenSSL's order) for any check that reads ciphers or curves without hashing
+ * the whole extension list, and because it costs one function call.
+ */
+
+/**
+ * Bun's cipher list, in wire order.
+ *
+ * OpenSSL names, because that is what Node accepts — the `TLS_*` spellings
+ * resolve to only 3 suites here (the rest are unavailable to OpenSSL), which is
+ * why an earlier attempt at this produced a 3-cipher hello that was *further*
+ * from Bun than doing nothing.
+ */
+export const BUN_CIPHER_SUITES =
+  "TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:" +
+  "ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:" +
+  "ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:" +
+  "ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:" +
+  "ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES128-SHA:" +
+  "ECDHE-ECDSA-AES256-SHA:ECDHE-RSA-AES256-SHA:" +
+  "AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA:AES256-SHA";
+
+/**
+ * Bun's supported groups, in order: the post-quantum hybrid first, then
+ * X25519, P-256, P-384 — and nothing else. Measured identical to Bun.
+ */
+export const BUN_SUPPORTED_GROUPS = "X25519MLKEM768:X25519:P-256:P-384";
+
+/**
+ * Options that make a Node TLS connection handshake with Bun's cipher list,
+ * curve list, ALPN and version span.
+ *
+ * Spread into `tls.connect` or `https.request`. Does not touch the extension
+ * list, which Node does not expose.
+ */
+export function bunClientHelloOptions(): Pick<
+  ConnectionOptions,
+  "ciphers" | "ecdhCurve" | "ALPNProtocols" | "minVersion" | "maxVersion"
+> {
+  return {
+    ciphers: BUN_CIPHER_SUITES,
+    ecdhCurve: BUN_SUPPORTED_GROUPS,
+    // One protocol, like Bun. Offering `h2` here would change the ALPN
+    // extension and the negotiated protocol.
+    ALPNProtocols: ["http/1.1"],
+    minVersion: "TLSv1.2",
+    maxVersion: "TLSv1.3",
+  };
+}
+
+/**
+ * Upgrades an already-connected socket to TLS with Bun's parameters.
+ *
+ * The socket is the point: it lets a SOCKS5 `SocksProxyAgent` own the dial
+ * (keeping its SSRF `lookup`) while this controls the hello. Bun's `fetch`
+ * cannot do that combination — it refuses SOCKS5 outright.
+ */
+export function bunTlsOverSocket(
+  socket: Socket,
+  servername: string,
+  extra: Omit<ConnectionOptions, "socket" | "servername"> = {},
+) {
+  return tlsConnect({
+    socket,
+    servername,
+    rejectUnauthorized: true,
+    ...bunClientHelloOptions(),
+    ...extra,
+  });
+}

package/src/observability/event-log.ts

@@ -176,19 +176,37 @@ export async function readTelemetryEvents(): Promise<TelemetryEventRecord[]> {
 export interface EventQuery {
   readonly tenantId?: string;
   readonly since?: Date;
+  /**
+   * Exclusive upper bound on `createdAt`, used to push a pagination cursor into
+   * the query instead of filtering after the whole window was parsed. Without
+   * it a cursor page drops `limit` — the reader cannot know where the page
+   * ends — so only the first page of a list is bounded.
+   */
+  readonly until?: Date;
   readonly apiKeyIds?: readonly string[];
   readonly accountIds?: readonly string[];
   readonly requestId?: string;
+  /**
+   * Distinct from {@link requestId}: `id` defaults to the request id when a row
+   * does not carry one of its own (`event-log.ts:68`), so a row can match by
+   * either. A lookup by `id` short-circuits like `requestId` does, which is the
+   * whole point — without it a single-event detail read parses the retention
+   * window and then scans it in JS.
+   */
+  readonly id?: string;
   readonly httpStatus?: number;
   readonly limit?: number;
 }
 
-function matches(event: TelemetryEventRecord, query: EventQuery, since: number | undefined, keys: ReadonlySet<string> | undefined, accounts: ReadonlySet<string> | undefined): boolean {
+function matches(event: TelemetryEventRecord, query: EventQuery, since: number | undefined, until: number | undefined, keys: ReadonlySet<string> | undefined, accounts: ReadonlySet<string> | undefined): boolean {
   if (query.tenantId !== undefined && event.tenantId !== query.tenantId) return false;
-  if (since !== undefined && new Date(event.createdAt).getTime() < since) return false;
+  const at = new Date(event.createdAt).getTime();
+  if (since !== undefined && at < since) return false;
+  if (until !== undefined && at > until) return false;
   if (keys && (event.apiKeyId === null || !keys.has(event.apiKeyId))) return false;
   if (accounts && (event.accountId === null || !accounts.has(event.accountId))) return false;
   if (query.requestId !== undefined && event.requestId !== query.requestId) return false;
+  if (query.id !== undefined && event.id !== query.id) return false;
   if (query.httpStatus !== undefined && event.httpStatus !== query.httpStatus) return false;
   return true;
 }
@@ -199,6 +217,7 @@ export async function queryTelemetryEvents(query: EventQuery): Promise<Telemetry
     .filter((file) => file.endsWith(".jsonl") && (query.since === undefined || eventFileHour(file) >= hourStamp(query.since)))
     .sort((a, b) => (a < b ? 1 : a > b ? -1 : 0));
   const since = query.since?.getTime();
+  const until = query.until?.getTime();
   const keys = query.apiKeyIds ? new Set(query.apiKeyIds) : undefined;
   const accounts = query.accountIds ? new Set(query.accountIds) : undefined;
   const events: TelemetryEventRecord[] = [];
@@ -207,19 +226,21 @@ export async function queryTelemetryEvents(query: EventQuery): Promise<Telemetry
   // field, and a false negative is not possible while a false positive costs
   // only the parse it would have paid anyway.
   const allow =
-    query.tenantId === undefined && query.requestId === undefined
+    query.tenantId === undefined && query.requestId === undefined && query.id === undefined
       ? undefined
       : (line: string): boolean =>
           (query.tenantId === undefined || line.includes(query.tenantId)) &&
-          (query.requestId === undefined || line.includes(query.requestId));
+          (query.requestId === undefined || line.includes(query.requestId)) &&
+          (query.id === undefined || line.includes(query.id));
+  // A single-row lookup: stop at the first (newest) match instead of parsing
+  // the whole retention window.
+  const oneRow = query.requestId !== undefined || query.id !== undefined;
   for (const file of files) {
     const matched: TelemetryEventRecord[] = [];
     for await (const event of readEventFiles([file], allow)) {
-      if (!matches(event, query, since, keys, accounts)) continue;
+      if (!matches(event, query, since, until, keys, accounts)) continue;
       matched.push(event);
-      // A requestId lookup needs one row: stop at the first (newest) match
-      // instead of parsing the whole retention window.
-      if (query.requestId !== undefined) return matched;
+      if (oneRow) return matched;
     }
     matched.sort((a, b) => (a.createdAt < b.createdAt ? 1 : a.createdAt > b.createdAt ? -1 : 0));
     events.push(...matched);