@stigmer/server 3.14.0-dev.20260910084630

package/src/transport/console/handler.ts

@@ -0,0 +1,309 @@
+/**
+ * The console lane — lane 4 of the unified port (DD-005; DD-012 in the
+ * parent program's records): serves the web console's static export and
+ * synthesizes its runtime /config.json, restoring the local console the
+ * June CLI migration lost. Routing decisions live in resolver.ts (pure,
+ * nginx-equivalence-gated); this module owns the HTTP half: the lane
+ * guard, header policy, config synthesis, and file streaming.
+ *
+ * Lane guard (consoleLaneEligible): the lane claims GET/HEAD only — RPC
+ * traffic is POST on service-qualified paths, and OPTIONS preflights keep
+ * flowing to the RPC lane's CORS handling — and it never claims:
+ *   - `/v1/*`: the registry/skill lanes' namespace; unknown paths there
+ *     must keep reaching the adapter's 404 (the CW-10 pinned contract).
+ *   - service-shaped paths (`/<package.Service>/<Method>` — exactly two
+ *     segments with a dotted first): even though no RPC answers GET today
+ *     (zero no_side_effects methods), the adapter must stay the authority
+ *     for its own namespace if one ever does.
+ *
+ * Header policy follows nginx.conf's four explicit postures byte-for-byte
+ * (immutable /_next/static/, no-cache index.html, no-store config.json,
+ * max-age=300 embed.js). Everything else is served `no-cache` — a
+ * deliberate divergence from nginx, which falls back to default validator
+ * behavior (ETag/Last-Modified) this handler does not emit; no-cache
+ * keeps every document fresh across server upgrades at the cost of
+ * revalidating tiny files, while the heavy assets all live under the
+ * immutable /_next/static/ rule.
+ */
+import { createReadStream } from "node:fs";
+import { stat } from "node:fs/promises";
+import path from "node:path";
+
+import type { Logger } from "../../boot/logger.js";
+import type { LaneHandler, LaneRequest, LaneResponse } from "../lanes.js";
+import type { ConsoleAssets } from "./assets.js";
+import { resolveConsoleRequest } from "./resolver.js";
+
+/** The runtime-config route the ConfigGate fetches before first render. */
+const CONFIG_JSON_PATH = "/config.json";
+
+/** nginx: runtime config must never be cached (config changes propagate immediately). */
+const CONFIG_JSON_CACHE_CONTROL = "no-cache, no-store, must-revalidate";
+
+/** nginx: Next.js hashed assets are safe to cache indefinitely. */
+const IMMUTABLE_CACHE_CONTROL = "public, max-age=31536000, immutable";
+
+/** nginx: the embed loader rides an unversioned URL; a short TTL lets fixes reach embedders in minutes. */
+const EMBED_JS_CACHE_CONTROL = "public, max-age=300";
+
+/** Everything else (see the module header for the divergence rationale). */
+const DEFAULT_CACHE_CONTROL = "no-cache";
+
+/**
+ * Whether the console lane may claim this request. Exported for the lane
+ * router (server.ts), which stays a thin if-chain — the guard's knowledge
+ * of RPC path shapes belongs to this module.
+ */
+export function consoleLaneEligible(request: LaneRequest): boolean {
+  if (request.method !== "GET" && request.method !== "HEAD") {
+    return false;
+  }
+  const pathname = (request.url ?? "").split("?", 1)[0] ?? "";
+  if (pathname === "" || !pathname.startsWith("/")) {
+    return false;
+  }
+  if (pathname.startsWith("/v1/")) {
+    return false;
+  }
+  return !isServiceShapedPath(pathname);
+}
+
+/** `/<package.Service>/<Method>` — exactly two segments, dotted first. */
+function isServiceShapedPath(pathname: string): boolean {
+  const segments = pathname.split("/").filter((segment) => segment !== "");
+  return segments.length === 2 && (segments[0] ?? "").includes(".");
+}
+
+export interface ConsoleLaneOptions {
+  readonly assets: ConsoleAssets;
+  /**
+   * Fallback port for the synthesized apiUrl when a request carries no
+   * Host/:authority (technically possible on HTTP/1.0-style clients).
+   */
+  readonly grpcPort: number;
+  readonly logger: Logger;
+}
+
+export function createConsoleLane(options: ConsoleLaneOptions): LaneHandler {
+  const { assets, grpcPort, logger } = options;
+
+  return (request: LaneRequest, response: LaneResponse): void => {
+    const url = request.url ?? "";
+    const queryStart = url.indexOf("?");
+    const rawPath = queryStart === -1 ? url : url.slice(0, queryStart);
+    const query = queryStart === -1 ? "" : url.slice(queryStart);
+
+    if (rawPath === CONFIG_JSON_PATH) {
+      serveConfigJson(request, response, grpcPort);
+      return;
+    }
+
+    let pathname: string;
+    try {
+      pathname = decodeURIComponent(rawPath);
+    } catch {
+      // Malformed percent-escapes are a client error (the artifact file
+      // server's posture); the export's own 404 document still answers.
+      serveNotFound(request, response, assets, logger);
+      return;
+    }
+
+    const resolution = resolveConsoleRequest(pathname, assets.index);
+    switch (resolution.kind) {
+      case "redirect":
+        // Relative Location (nginx absolute_redirect off: an absolute form
+        // would embed this listener's port, wrong behind any proxy). The
+        // query rides through, as nginx's `$is_args$args` spells out.
+        response.statusCode = 301;
+        response.setHeader("Location", `${resolution.location}${query}`);
+        response.end();
+        return;
+      case "file":
+        serveFile(request, response, assets, resolution.file, 200, logger);
+        return;
+      case "notFound":
+        serveNotFound(request, response, assets, logger);
+        return;
+      default: {
+        const exhaustive: never = resolution;
+        throw new Error(`unhandled resolution ${String(exhaustive)}`);
+      }
+    }
+  };
+}
+
+/**
+ * The runtime config the cloud container's entrypoint.sh generates from
+ * env — synthesized here from the server's own knowledge instead (DD-012:
+ * the nginx entrypoint script is not ported). apiUrl derives from the
+ * request's own Host so the answer is correct wherever the browser
+ * reached us from (localhost, a LAN address, a self-host name) — the
+ * console cannot express "same origin" itself (its config loader maps
+ * empty fields to a localhost default). TLS-terminating proxies
+ * (x-forwarded-proto) are out of scope until a tier serves TLS.
+ */
+function serveConfigJson(
+  request: LaneRequest,
+  response: LaneResponse,
+  grpcPort: number,
+): void {
+  // HTTP/1.1 carries Host; Node maps HTTP/2's :authority into the same
+  // headers view (and Http2ServerRequest.authority falls back to it).
+  const host = request.headers.host ?? request.headers[":authority"];
+  const apiUrl =
+    typeof host === "string" && host !== ""
+      ? `http://${host}`
+      : `http://localhost:${grpcPort}`;
+  const body = JSON.stringify({
+    apiUrl,
+    appUrl: "",
+    authMode: "disabled",
+    oidcIssuer: "",
+    oidcClientId: "",
+    oidcAudience: "",
+  });
+  response.statusCode = 200;
+  response.setHeader("Content-Type", "application/json");
+  response.setHeader("Cache-Control", CONFIG_JSON_CACHE_CONTROL);
+  response.setHeader("Content-Length", String(Buffer.byteLength(body)));
+  if (request.method === "HEAD") {
+    response.end();
+    return;
+  }
+  response.end(body);
+}
+
+function serveNotFound(
+  request: LaneRequest,
+  response: LaneResponse,
+  assets: ConsoleAssets,
+  logger: Logger,
+): void {
+  // The export's real not-found page, WITH the 404 status (nginx
+  // error_page semantics) — never the blank app shell, and never the
+  // adapter's terse 404 once a console is bundled.
+  if (assets.index.hasFile("/404.html")) {
+    serveFile(request, response, assets, "/404.html", 404, logger);
+    return;
+  }
+  response.statusCode = 404;
+  response.end("404 page not found\n");
+}
+
+function serveFile(
+  request: LaneRequest,
+  response: LaneResponse,
+  assets: ConsoleAssets,
+  file: string,
+  statusCode: number,
+  logger: Logger,
+): void {
+  // Containment by construction: `file` is an INDEX member (produced by
+  // the boot-time scan), never raw request input — a traversal path can
+  // only miss the index and 404 in the resolver. The join below therefore
+  // cannot escape the asset root.
+  const filePath = path.join(assets.root, ...file.split("/").filter(Boolean));
+
+  streamFile(request, response, file, filePath, statusCode).catch(
+    (error: unknown) => {
+      // Detached-async terminal catch (the skill transfer lane's
+      // load-bearing pattern): an escape here would be process-fatal.
+      logger.error("console lane failed to serve file", {
+        file,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      if (!response.headersSent) {
+        response.statusCode = 500;
+      }
+      response.end();
+    },
+  );
+}
+
+async function streamFile(
+  request: LaneRequest,
+  response: LaneResponse,
+  file: string,
+  filePath: string,
+  statusCode: number,
+): Promise<void> {
+  // The index said the file exists; a stat failure means the artifact was
+  // mutilated underneath us — the terminal catch answers 500.
+  const info = await stat(filePath);
+  response.statusCode = statusCode;
+  response.setHeader("Content-Type", contentTypeOf(file));
+  response.setHeader("Cache-Control", cacheControlOf(file, statusCode));
+  response.setHeader("Content-Length", String(info.size));
+  if (request.method === "HEAD") {
+    response.end();
+    return;
+  }
+  await new Promise<void>((resolve, reject) => {
+    const stream = createReadStream(filePath);
+    stream.on("error", (error) => {
+      response.destroy();
+      reject(error);
+    });
+    response.on("close", () => resolve());
+    stream.pipe(response);
+  });
+}
+
+/**
+ * Cache policy keyed on the SERVED document (nginx keys locations on the
+ * request URI, but its internal try_files redirects re-enter location
+ * matching, so the effective key is the final document there too).
+ * nginx's explicit `index.html → no-cache` rule is subsumed by the
+ * default here. Only 200 responses carry cache headers beyond the
+ * default — nginx's add_header skips error statuses, and a cached 404
+ * page would mask a later upgrade that adds the route.
+ */
+function cacheControlOf(file: string, statusCode: number): string {
+  if (statusCode !== 200) {
+    return DEFAULT_CACHE_CONTROL;
+  }
+  if (file.startsWith("/_next/static/")) {
+    return IMMUTABLE_CACHE_CONTROL;
+  }
+  if (file === "/embed.js") {
+    return EMBED_JS_CACHE_CONTROL;
+  }
+  return DEFAULT_CACHE_CONTROL;
+}
+
+/**
+ * Explicit type map: the artifact file server deliberately omits
+ * Content-Type (clients sniff), but a BROWSER document target must be
+ * typed — an untyped .html deep link would download instead of render.
+ * Extensions are the export's observed inventory; unknowns fall back to
+ * octet-stream rather than guessing.
+ */
+const CONTENT_TYPES: Readonly<Record<string, string>> = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json",
+  ".map": "application/json",
+  ".txt": "text/plain; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".ico": "image/x-icon",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".avif": "image/avif",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf",
+  ".otf": "font/otf",
+  ".wasm": "application/wasm",
+  ".xml": "application/xml",
+  ".webmanifest": "application/manifest+json",
+};
+
+function contentTypeOf(file: string): string {
+  const extension = path.posix.extname(file).toLowerCase();
+  return CONTENT_TYPES[extension] ?? "application/octet-stream";
+}

package/src/transport/console/resolver.ts

@@ -0,0 +1,199 @@
+/**
+ * The console static-export route resolver — the PURE routing half of the
+ * unified port's console lane (DD-005 lane 4; DD-012 in the parent
+ * program's records). Given a decoded request path and an index of the
+ * export's files, it answers WHICH document serves — no I/O, so the
+ * contract is exhaustively unit-testable and machine-checkable against
+ * the nginx model (see __tests__/nginx-equivalence.test.ts).
+ *
+ * The contract merges the correct half of each prior implementation:
+ *
+ * - PAGE resolution reproduces client-apps/web/nginx.conf (the cloud
+ *   serving rules, hardened after the channel-conversations F-12
+ *   blank-page failures): try the literal file, its `.html` sibling, the
+ *   directory index, then the Next.js `__placeholder__.html` candidates —
+ *   most-literal first, at most two trailing dynamic segments — and
+ *   unknown URLs land on /404.html WITH a 404 status, never the blank app
+ *   shell. Trailing slashes 301 to the canonical slashless URL.
+ *   scripts/verify-static-export-routes.mjs holds nginx.conf and the route
+ *   tree together; the equivalence test holds THIS resolver to the same
+ *   model, so the two serving paths cannot drift.
+ *
+ * - RSC FLIGHT resolution restores the retired Go CLI handler's rewrites
+ *   (client-apps/cli/embedded/webconsole/handler.go at 8dc9df7e4~1,
+ *   deleted with the June CLI migration): a soft navigation to a dynamic
+ *   route fetches `<path>.txt` (and nested `<path>/__next.*.txt`) flight
+ *   payloads that exist on disk only in `__placeholder__` form. nginx
+ *   never handled these (filed as a cloud-side follow-up); without the
+ *   rewrite every soft navigation to a dynamic route degrades to a full
+ *   page load. Formulated here as "resolve the stem as a page, serve the
+ *   resolved document's twin" — one candidate discipline for both
+ *   contracts, which also covers the two-dynamic-segment routes the Go
+ *   handler's single-substitution loop predated.
+ */
+
+/** The literal Next.js static-export sentinel for dynamic segments. */
+const PLACEHOLDER = "__placeholder__";
+
+/** Nested RSC payload files: `__next.<segment-path>.txt` siblings. */
+const FLIGHT_SEGMENT_PREFIX = "__next.";
+
+/**
+ * The export's files and the directories they imply, both as "/"-rooted,
+ * "/"-separated paths (e.g. "/sessions/__placeholder__.html"). Built once
+ * per asset root by {@link buildConsoleFileIndex}; filesystem separators
+ * are the serving layer's concern, never the resolver's.
+ */
+export interface ConsoleFileIndex {
+  hasFile(path: string): boolean;
+  hasDirectory(path: string): boolean;
+}
+
+export function buildConsoleFileIndex(
+  files: Iterable<string>,
+): ConsoleFileIndex {
+  const fileSet = new Set<string>();
+  // The export root itself is a directory, so "/" resolves through the
+  // directory-index candidate (the root route's own serving path).
+  const directorySet = new Set<string>(["/"]);
+  for (const file of files) {
+    fileSet.add(file);
+    let parent = file;
+    for (;;) {
+      const slash = parent.lastIndexOf("/");
+      if (slash <= 0) break;
+      parent = parent.slice(0, slash);
+      if (directorySet.has(parent)) break;
+      directorySet.add(parent);
+    }
+  }
+  return {
+    hasFile: (path) => fileSet.has(path),
+    hasDirectory: (path) => directorySet.has(path),
+  };
+}
+
+export type ConsoleResolution =
+  /** 301 to the canonical URL (the handler carries the query through). */
+  | { readonly kind: "redirect"; readonly location: string }
+  /** Serve this export file with a 200. */
+  | { readonly kind: "file"; readonly file: string }
+  /** Serve /404.html (when the export has one) WITH a 404 status. */
+  | { readonly kind: "notFound" };
+
+/**
+ * Resolve a decoded, query-less request path against the export index.
+ * Redirects resolve one step per call, exactly as nginx's single
+ * `^(.+)/$` rewrite does — the client (or a test) follows them.
+ */
+export function resolveConsoleRequest(
+  pathname: string,
+  index: ConsoleFileIndex,
+): ConsoleResolution {
+  // Trailing-slash canonicalization (nginx `location ~ ^(.+)/$`): the
+  // export writes sibling .html files, never directory indexes, so a
+  // trailing-slash deep link would miss every candidate below. "/" itself
+  // cannot match (the capture needs one character before the slash).
+  if (pathname.length > 1 && pathname.endsWith("/")) {
+    return { kind: "redirect", location: pathname.slice(0, -1) };
+  }
+
+  const lastSegment = pathname.slice(pathname.lastIndexOf("/") + 1);
+
+  // Nested RSC flight payload: /<dir>/__next.<x>.txt. Direct hits cover
+  // static parents (and the root-level __next.*.txt family); otherwise
+  // resolve the parent as a page and serve the payload from the resolved
+  // (placeholder-substituted) document's directory.
+  if (
+    lastSegment.startsWith(FLIGHT_SEGMENT_PREFIX) &&
+    lastSegment.endsWith(".txt")
+  ) {
+    if (index.hasFile(pathname)) {
+      return { kind: "file", file: pathname };
+    }
+    const parent = pathname.slice(0, pathname.lastIndexOf("/"));
+    const parentDocument = parent === "" ? null : resolvePage(parent, index);
+    if (parentDocument !== null && parentDocument.endsWith(".html")) {
+      const candidate = `${parentDocument.slice(0, -".html".length)}/${lastSegment}`;
+      if (index.hasFile(candidate)) {
+        return { kind: "file", file: candidate };
+      }
+    }
+    return { kind: "notFound" };
+  }
+
+  // Page-level RSC flight payload: /<path>.txt is the twin of the
+  // document /<path> resolves to (the export writes a .txt beside every
+  // page's .html). Excludes _next/ internals, which are literal files.
+  if (
+    lastSegment.endsWith(".txt") &&
+    !pathname.startsWith("/_next/") &&
+    index.hasFile(pathname) === false
+  ) {
+    const stemDocument = resolvePage(pathname.slice(0, -".txt".length), index);
+    if (stemDocument !== null && stemDocument.endsWith(".html")) {
+      const twin = `${stemDocument.slice(0, -".html".length)}.txt`;
+      if (index.hasFile(twin)) {
+        return { kind: "file", file: twin };
+      }
+    }
+    return { kind: "notFound" };
+  }
+
+  const document = resolvePage(pathname, index);
+  return document === null
+    ? { kind: "notFound" }
+    : { kind: "file", file: document };
+}
+
+/**
+ * The nginx try_files chain, generalized: literal file, `.html` sibling,
+ * directory index, then the placeholder candidates — substitute the last
+ * segment, then the last two (nginx's declaration order: the more-literal
+ * candidate first, mirroring Next.js route priority where a literal
+ * segment beats a dynamic one). Returns the served document or null.
+ *
+ * `/_next/` build assets are literal-only (nginx's `^~ /_next/static/`
+ * location has no try_files): the placeholder candidates could never hit
+ * there — no export writes placeholder documents under /_next/ — so the
+ * short-circuit changes no outcome, it just refuses to pretend those
+ * candidates make sense.
+ */
+function resolvePage(pathname: string, index: ConsoleFileIndex): string | null {
+  if (index.hasFile(pathname)) {
+    return pathname;
+  }
+  if (pathname.startsWith("/_next/")) {
+    return null;
+  }
+  if (pathname !== "/" && index.hasFile(`${pathname}.html`)) {
+    return `${pathname}.html`;
+  }
+  // nginx `$uri/` + `index index.html`: a directory serves its index.
+  if (index.hasDirectory(pathname)) {
+    const indexFile =
+      pathname === "/" ? "/index.html" : `${pathname}/index.html`;
+    if (index.hasFile(indexFile)) {
+      return indexFile;
+    }
+  }
+
+  const segments = pathname.split("/").filter((segment) => segment !== "");
+  for (const dynamicCount of [1, 2]) {
+    // Substituting the last k segments needs at least k+1 segments: the
+    // nginx regexes require a non-empty static prefix (`(.+)/…`), so a
+    // top-level path never resolves through placeholders.
+    if (segments.length < dynamicCount + 1) {
+      break;
+    }
+    const candidate = [
+      "",
+      ...segments.slice(0, -dynamicCount),
+      ...Array<string>(dynamicCount).fill(PLACEHOLDER),
+    ].join("/");
+    if (index.hasFile(`${candidate}.html`)) {
+      return `${candidate}.html`;
+    }
+  }
+  return null;
+}

package/src/transport/constants.ts

@@ -0,0 +1,47 @@
+/**
+ * Transport-layer semantic constants. Every value here was tuned in the Go
+ * server against real behavior; the rationale rides with the constant so
+ * nobody "fixes" one casually (coding guideline 001 §5).
+ */
+
+/**
+ * Message size cap in BOTH directions, matching Go's
+ * grpc.MaxRecvMsgSize/MaxSendMsgSize (backend/libs/go/grpc/server.go:94-95).
+ * Skills and execution payloads approach but must not exceed this; raising
+ * it silently would let one edition accept payloads the other refuses.
+ */
+export const MAX_MESSAGE_BYTES = 10 * 1024 * 1024;
+
+/**
+ * Server-initiated HTTP/2 keepalive: ping idle sessions every 15s, close if
+ * the ack takes longer than 5s (Go keepalive.ServerParameters, grpc lib
+ * server.go:111-114). Detects half-dead connections from suspended laptops
+ * and NAT timeouts without waiting for a write to fail.
+ *
+ * Go additionally ENFORCES a client-ping rate floor
+ * (keepalive.EnforcementPolicy MinTime 5s, server.go:102-105). Node's
+ * http2 auto-acks client pings below the API surface and emits no event
+ * for them, so the enforcement half is not implementable here. It is
+ * protective-only (guards against ping-flooding clients) and invisible to
+ * every well-behaved client — recorded as a disclosed parity nuance in the
+ * sub-project record, not silently dropped.
+ */
+export const KEEPALIVE_PING_INTERVAL_MS = 15_000;
+export const KEEPALIVE_PING_TIMEOUT_MS = 5_000;
+
+/**
+ * Graceful-shutdown drain budget, matching Go's http.Server.Shutdown
+ * context timeout (backend/libs/go/grpc/server.go Stop). Order is contract:
+ * health flips NOT_SERVING first, in-flight requests get up to this long,
+ * then remaining connections are destroyed.
+ */
+export const SHUTDOWN_DRAIN_TIMEOUT_MS = 10_000;
+
+/**
+ * Lane paths on the unified port, byte-pinned from the Go router
+ * (pkg/server/server.go:812-826) and asserted by the CW-10 conformance
+ * suite (test/conformance/src/suites/registry-proxy.conformance.test.ts).
+ */
+export const TASK_KIND_REGISTRY_PATH = "/v1/proxy/task-kind-registry";
+export const MODEL_REGISTRY_PATH = "/v1/proxy/model-registry";
+export const SKILL_ARTIFACTS_PATH_PREFIX = "/v1/skill-artifacts";

package/src/transport/cors.ts

@@ -0,0 +1,119 @@
+/**
+ * CORS for the unified port's two lane families. Two deliberately different
+ * policies, both ported from verified Go behavior:
+ *
+ * REGISTRY lanes (`registryCorsHeaders`/`handleRegistryPreflight`): the
+ * byte-for-byte port of pkg/server/registry_cors.go (oss#571) —
+ * `Access-Control-Allow-Origin: *` on every response; OPTIONS answered 204
+ * with the fixed `GET, OPTIONS` / `Authorization, Content-Type` allow-lists.
+ * Asserted by the CW-10 conformance suite.
+ *
+ * RPC lane (`applyRpcCors`/`isRpcPreflight`): mirrors what the Go server's
+ * gRPC-Web wrapper actually does — improbable-eng/grpc-web v0.15.0 wrapping
+ * rs/cors v1.7.0 with AllowOriginFunc=allow-all, AllowedHeaders=["*"],
+ * AllowCredentials=true, MaxAge=600 (grpcweb/wrapper.go:70-76). Concretely:
+ * the request Origin is echoed (never `*` — credentials mode), preflights
+ * answer 200 with the requested method/headers echoed back, and
+ * `WithCorsForRegisteredEndpointsOnly(false)` means preflights succeed for
+ * ANY path, registered or not (server.go:777-784, the silent-preflight-404
+ * fix).
+ *
+ * One ratified extension (D2 delta 2): Go only classifies a preflight as
+ * gRPC-Web CORS when the requested headers include `x-grpc-web`
+ * (grpcweb/wrapper.go IsAcceptableGrpcCorsRequest). The Connect protocol's
+ * browser preflights carry `content-type` but not `x-grpc-web`, so under
+ * Go's predicate the protocol this server ADDS would be unusable from
+ * browsers. The RPC lane therefore answers every OPTIONS carrying
+ * `Access-Control-Request-Method` — a strict superset of Go's behavior,
+ * disclosed with the Connect delta rather than silent.
+ */
+import type { LaneRequest, LaneResponse } from "./lanes.js";
+
+/** rs/cors option in the Go wrapper: 10 minutes, "pre-flights every 5s for Chromium :(". */
+const RPC_PREFLIGHT_MAX_AGE_SECONDS = "600";
+
+/** Applies the registry lanes' unconditional allow-all header (Go registryCORS). */
+export function applyRegistryCorsHeaders(response: LaneResponse): void {
+  response.setHeader("Access-Control-Allow-Origin", "*");
+}
+
+/**
+ * Answers a registry-lane OPTIONS request exactly as Go's registryCORS:
+ * 204 with the fixed allow-lists. Returns false for non-OPTIONS requests.
+ */
+export function handleRegistryPreflight(
+  request: LaneRequest,
+  response: LaneResponse,
+): boolean {
+  if (request.method !== "OPTIONS") {
+    return false;
+  }
+  applyRegistryCorsHeaders(response);
+  response.setHeader("Access-Control-Allow-Methods", "GET, OPTIONS");
+  response.setHeader(
+    "Access-Control-Allow-Headers",
+    "Authorization, Content-Type",
+  );
+  response.statusCode = 204;
+  response.end();
+  return true;
+}
+
+/** rs/cors preflight predicate: OPTIONS carrying Access-Control-Request-Method. */
+export function isRpcPreflight(request: LaneRequest): boolean {
+  return (
+    request.method === "OPTIONS" &&
+    typeof request.headers["access-control-request-method"] === "string"
+  );
+}
+
+/**
+ * Answers an RPC-lane preflight in rs/cors v1.7 shape: 200, Origin echoed,
+ * requested method and headers echoed, credentials allowed, Max-Age 600.
+ */
+export function handleRpcPreflight(
+  request: LaneRequest,
+  response: LaneResponse,
+): void {
+  const origin = request.headers["origin"];
+  response.setHeader("Vary", [
+    "Origin",
+    "Access-Control-Request-Method",
+    "Access-Control-Request-Headers",
+  ]);
+  if (typeof origin === "string") {
+    response.setHeader("Access-Control-Allow-Origin", origin);
+    response.setHeader("Access-Control-Allow-Credentials", "true");
+    const requestedMethod = request.headers["access-control-request-method"];
+    if (typeof requestedMethod === "string") {
+      response.setHeader(
+        "Access-Control-Allow-Methods",
+        requestedMethod.toUpperCase(),
+      );
+    }
+    const requestedHeaders = request.headers["access-control-request-headers"];
+    if (typeof requestedHeaders === "string" && requestedHeaders !== "") {
+      response.setHeader("Access-Control-Allow-Headers", requestedHeaders);
+    }
+    response.setHeader("Access-Control-Max-Age", RPC_PREFLIGHT_MAX_AGE_SECONDS);
+  }
+  response.statusCode = 200;
+  response.end();
+}
+
+/**
+ * Stamps actual-request (non-preflight) CORS headers on an RPC-lane
+ * response when the request is cross-origin: Origin echoed + credentials,
+ * as rs/cors handleActualRequest does for the Go wrapper.
+ */
+export function applyRpcCorsHeaders(
+  request: LaneRequest,
+  response: LaneResponse,
+): void {
+  response.setHeader("Vary", "Origin");
+  const origin = request.headers["origin"];
+  if (typeof origin === "string") {
+    response.setHeader("Access-Control-Allow-Origin", origin);
+    response.setHeader("Access-Control-Allow-Credentials", "true");
+  }
+}