borgmcp-server 0.1.1

package/src/https-server.ts

@@ -0,0 +1,962 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { createServer, type Server as HttpsServer } from "node:https";
+import type { AddressInfo, Socket } from "node:net";
+import { createHash, X509Certificate } from "node:crypto";
+
+import { resolveBindOptions, type BindOptionsInput } from "./network-policy.js";
+import type { CoordinationRequest, CoordinationResponse } from "./coordination-api.js";
+import type { Principal } from "./principal.js";
+
+export interface ProtocolInfoDocument {
+  readonly protocol_version: string;
+  readonly package: {
+    readonly name: "borgmcp-shared";
+    readonly version: string;
+  };
+  readonly capabilities: readonly string[];
+  readonly limits: {
+    readonly max_request_bytes: number;
+    readonly max_log_message_bytes: number;
+    readonly max_read_page_size: number;
+    readonly max_replay_page_size: number;
+  };
+}
+
+export interface ServiceLimits {
+  readonly maxConnections: number;
+  readonly maxConnectionsPerAddress: number;
+  readonly maxRequestsPerWindow: number;
+  readonly maxRequestsPerAddressWindow: number;
+  readonly maxRequestsGlobalWindow: number;
+  readonly rateLimitWindowMs: number;
+  readonly maxRateLimitEntries: number;
+  readonly maxStreamsPerCredential: number;
+  readonly maxHeaderBytes: number;
+  readonly maxRequestBodyBytes: number;
+  readonly maxRequestsPerSocket: number;
+  readonly requestTimeoutMs: number;
+  readonly tlsHandshakeTimeoutMs: number;
+  readonly headersTimeoutMs: number;
+  readonly keepAliveTimeoutMs: number;
+  readonly handlerTimeoutMs: number;
+}
+
+export const DEFAULT_SERVICE_LIMITS: ServiceLimits = {
+  maxConnections: 100,
+  maxConnectionsPerAddress: 25,
+  maxRequestsPerWindow: 120,
+  maxRequestsPerAddressWindow: 600,
+  maxRequestsGlobalWindow: 5_000,
+  rateLimitWindowMs: 60_000,
+  maxRateLimitEntries: 1_024,
+  maxStreamsPerCredential: 8,
+  maxHeaderBytes: 16_384,
+  maxRequestBodyBytes: 65_536,
+  maxRequestsPerSocket: 100,
+  requestTimeoutMs: 15_000,
+  tlsHandshakeTimeoutMs: 10_000,
+  headersTimeoutMs: 10_000,
+  keepAliveTimeoutMs: 5_000,
+  handlerTimeoutMs: 5_000,
+};
+
+export interface RequestHandlerContext {
+  readonly protocolInfo: ProtocolInfoDocument;
+  readonly authorizeProtocol: (
+    authorization: string | undefined,
+    signal: AbortSignal,
+  ) => Promise<boolean | "missing" | "invalid" | "revoked">;
+  readonly exchangeEnrollment?: (
+    body: unknown,
+  ) => Promise<{ readonly status: 201 | 400 | 401 | 507; readonly body?: unknown }>;
+  readonly authorizeCoordination?: (
+    authorization: string | undefined,
+    signal: AbortSignal,
+  ) => Promise<Principal | "missing" | "invalid" | "revoked">;
+  readonly handleCoordination?: (request: CoordinationRequest) => Promise<CoordinationResponse>;
+}
+
+export interface HttpsServerOptions {
+  readonly bind?: BindOptionsInput;
+  readonly tls: {
+    readonly key: string | Buffer;
+    readonly cert: string | Buffer;
+    readonly ca?: string | Buffer;
+  };
+  readonly protocolInfo: ProtocolInfoDocument;
+  readonly authorizeProtocol: RequestHandlerContext["authorizeProtocol"];
+  readonly exchangeEnrollment?: RequestHandlerContext["exchangeEnrollment"];
+  readonly authorizeCoordination?: RequestHandlerContext["authorizeCoordination"];
+  readonly handleCoordination?: RequestHandlerContext["handleCoordination"];
+  readonly limits?: ServiceLimits;
+  readonly testHooks?: {
+    readonly identifyRemoteAddress?: (socket: Socket) => string;
+  };
+}
+
+export interface RunningServer {
+  readonly origin: string;
+  readonly limits: ServiceLimits;
+  readonly close: () => Promise<void>;
+}
+
+export async function startHttpsServer(options: HttpsServerOptions): Promise<RunningServer> {
+  if (options.handleCoordination !== undefined && options.authorizeCoordination === undefined) {
+    throw new Error("Coordination routes require server-derived principal authentication.");
+  }
+  const bind = resolveBindOptions(options.bind ?? {});
+  const limits = options.limits ?? DEFAULT_SERVICE_LIMITS;
+  validateLimits(limits);
+  validateTlsCertificate(options.tls.cert, bind.host, bind.mode, options.tls.ca);
+  const handlerContext = createRequestHandlerContext(options);
+
+  const server = createServer(
+    {
+      key: options.tls.key,
+      cert: options.tls.cert,
+      minVersion: "TLSv1.3",
+      maxHeaderSize: limits.maxHeaderBytes,
+      requestTimeout: limits.requestTimeoutMs,
+      handshakeTimeout: limits.tlsHandshakeTimeoutMs,
+      headersTimeout: limits.headersTimeoutMs,
+      keepAliveTimeout: limits.keepAliveTimeoutMs,
+    },
+    createRequestListener(handlerContext, limits, options.testHooks?.identifyRemoteAddress),
+  );
+
+  const acceptedSockets = applyServerLimits(server, limits);
+  server.on("secureConnection", (socket) => socket.disableRenegotiation());
+  server.on("tlsClientError", (_error, socket) => socket.destroy());
+  server.on("clientError", (_error, socket) => socket.end("HTTP/1.1 400 Bad Request\r\n\r\n"));
+  server.on("checkContinue", (_request, response) => sendEmpty(response, 417, true));
+
+  try {
+    await listen(server, bind.port, bind.host);
+  } catch (error) {
+    server.closeAllConnections();
+    try {
+      server.close();
+    } catch {
+      // Preserve the originating listen failure.
+    }
+    throw error;
+  }
+  const address = server.address() as AddressInfo;
+  const displayHost = address.family === "IPv6" ? `[${address.address}]` : address.address;
+  let closePromise: Promise<void> | undefined;
+
+  return {
+    origin: `https://${displayHost}:${address.port}`,
+    limits,
+    close: () => {
+      closePromise ??= close(server, acceptedSockets);
+      return closePromise;
+    },
+  };
+}
+
+export function createRequestHandlerContext(
+  options: HttpsServerOptions,
+): RequestHandlerContext {
+  return Object.freeze({
+    protocolInfo: options.protocolInfo,
+    authorizeProtocol: options.authorizeProtocol,
+    ...(options.exchangeEnrollment === undefined
+      ? {}
+      : { exchangeEnrollment: options.exchangeEnrollment }),
+    ...(options.authorizeCoordination === undefined
+      ? {}
+      : { authorizeCoordination: options.authorizeCoordination }),
+    ...(options.handleCoordination === undefined
+      ? {}
+      : { handleCoordination: options.handleCoordination }),
+  });
+}
+
+function createRequestListener(
+  context: RequestHandlerContext,
+  limits: ServiceLimits,
+  identifyRemoteAddress: (socket: Socket) => string = (socket) => socket.remoteAddress ?? "unknown",
+): (request: IncomingMessage, response: ServerResponse) => void {
+  const admissionLimiter = new PreAuthAdmissionLimiter(limits);
+  const credentialRateLimiter = new RequestRateLimiter(limits, limits.maxRequestsPerWindow);
+  const streamQuota = new ConcurrentQuota(limits.maxStreamsPerCredential);
+  return (request, response) => {
+    const controller = new AbortController();
+    response.once("close", () => controller.abort());
+    let timer: NodeJS.Timeout | undefined;
+    const deadline = new Promise<"deadline">((resolve) => {
+      timer = setTimeout(() => {
+        controller.abort();
+        resolve("deadline");
+      }, limits.handlerTimeoutMs);
+      timer.unref();
+    });
+    const handled = handleRequest(
+      request,
+      response,
+      context,
+      limits,
+      admissionLimiter,
+      credentialRateLimiter,
+      streamQuota,
+      identifyRemoteAddress,
+      controller.signal,
+    )
+      .then(() => "handled" as const);
+
+    void Promise.race([handled, deadline])
+      .then((outcome) => {
+        if (outcome === "deadline") sendEmpty(response, 503, true);
+      })
+      .catch(() => sendEmpty(response, 500, true))
+      .finally(() => {
+        if (timer !== undefined) clearTimeout(timer);
+      });
+  };
+}
+
+async function handleRequest(
+  request: IncomingMessage,
+  response: ServerResponse,
+  context: RequestHandlerContext,
+  limits: ServiceLimits,
+  admissionLimiter: PreAuthAdmissionLimiter,
+  credentialRateLimiter: RequestRateLimiter,
+  streamQuota: ConcurrentQuota,
+  identifyRemoteAddress: (socket: Socket) => string,
+  signal: AbortSignal,
+): Promise<void> {
+  const addressIdentity = `address:${identifyRemoteAddress(request.socket)}`;
+  const preAuthRetry = admissionLimiter.consume(addressIdentity);
+  if (preAuthRetry !== null) {
+    request.resume();
+    sendRateLimited(response, preAuthRetry);
+    return;
+  }
+  if (request.headers.origin !== undefined) {
+    request.resume();
+    sendEmpty(response, 403, true);
+    return;
+  }
+
+  const path = parseRequestPath(request.url);
+
+  const requestBody = await readRequestBody(request, limits.maxRequestBodyBytes);
+  if (requestBody === "oversized") {
+    if (isCoordinationPath(path)) {
+      sendJson(response, 413, protocolError("CONTENT_TOO_LARGE", "Request body is too large."), true);
+    } else {
+      sendEmpty(response, 413, true);
+    }
+    return;
+  }
+
+  if (path === "/healthz") {
+    if (requestBody.length !== 0) return sendEmpty(response, 400, true);
+    sendEmpty(response, request.method === "GET" ? 204 : 405);
+    return;
+  }
+
+  if (path === "/api/protocol") {
+    if (requestBody.length !== 0) return sendEmpty(response, 400, true);
+    const authorized = await context.authorizeProtocol(request.headers.authorization, signal);
+    if (signal.aborted) return;
+    if (authorized !== true) {
+      const code = authorized === "revoked"
+        ? "SESSION_REVOKED"
+        : authorized === "missing" || request.headers.authorization === undefined
+          ? "AUTH_MISSING"
+          : "AUTH_INVALID";
+      sendJson(response, 401, protocolError(code, "Authentication failed."));
+      return;
+    }
+    const credentialRetry = consumeAuthenticatedRateLimit(
+      request.headers.authorization,
+      credentialRateLimiter,
+    );
+    if (credentialRetry !== null) return sendRateLimited(response, credentialRetry);
+    if (request.method !== "GET") {
+      sendEmpty(response, 405);
+      return;
+    }
+    sendJson(response, 200, {
+      protocol_version: "1",
+      request_id: "protocol-info",
+      payload: context.protocolInfo,
+    });
+    return;
+  }
+
+  if (path === "/api/enrollment/exchange") {
+    if (request.method !== "POST" || context.exchangeEnrollment === undefined) {
+      sendEmpty(response, 405);
+      return;
+    }
+    let decoded: unknown;
+    if (requestBody.length === 0) {
+      decoded = undefined;
+    } else {
+      try {
+        decoded = JSON.parse(requestBody.toString("utf8"));
+      } catch {
+        decoded = undefined;
+      }
+    }
+    const result = await context.exchangeEnrollment(decoded);
+    if (signal.aborted) return;
+    if (result.body === undefined) sendEmpty(response, result.status, result.status === 400);
+    else if (result.status === 400) sendJson(response, 400, result.body, true);
+    else if (result.status === 401 || result.status === 507) sendJson(response, result.status, result.body);
+    else sendJson(response, 201, result.body);
+    return;
+  }
+
+  if (isCoordinationPath(path) && context.handleCoordination !== undefined) {
+    let decoded: unknown;
+    if (requestBody.length === 0) {
+      decoded = undefined;
+    } else {
+      try {
+        decoded = JSON.parse(requestBody.toString("utf8"));
+      } catch {
+        decoded = undefined;
+      }
+    }
+    const authorization = request.headers.authorization;
+    const authorizeCoordination = context.authorizeCoordination;
+    if (authorizeCoordination === undefined) {
+      sendJson(response, 500, protocolError("INTERNAL_ERROR", "Coordination authentication is unavailable."), true);
+      return;
+    }
+    const authentication = await authorizeCoordination(authorization, signal);
+    if (signal.aborted) return;
+    if (typeof authentication === "string") {
+      const code = authentication === "revoked"
+        ? "SESSION_REVOKED"
+        : authentication === "missing" || authorization === undefined ? "AUTH_MISSING" : "AUTH_INVALID";
+      sendJson(response, 401, protocolError(code, "Authentication failed."));
+      return;
+    }
+    const clientIdentity = `client:${authentication.kind === "drone-session"
+      ? authentication.clientId
+      : authentication.id}`;
+    const credentialRetry = credentialRateLimiter.consume(clientIdentity);
+    if (credentialRetry !== null) return sendRateLimited(response, credentialRetry);
+    const cursor = parseCursorParameter(request.url, path);
+    if (cursor === INVALID_COORDINATION_QUERY) {
+      sendJson(response, 400, protocolError("INVALID_INPUT", "Invalid query parameters."), true);
+      return;
+    }
+    const result = await context.handleCoordination({
+      method: request.method ?? "",
+      path,
+      principal: authentication,
+      ...(decoded === undefined ? {} : { body: decoded }),
+      ...(cursor === undefined ? {} : { cursor }),
+      signal,
+    });
+    if (signal.aborted) {
+      if (result.stream !== undefined) await closeRejectedStream(result.stream);
+      return;
+    }
+    if (result.stream !== undefined) {
+      const release = streamQuota.acquire(credentialIdentity(authorization) ?? addressIdentity);
+      if (release === null) {
+        await closeRejectedStream(result.stream);
+        sendRateLimited(response, 1);
+      }
+      else await startEventStream(response, result.stream, release);
+    } else if (result.body === undefined) {
+      sendEmpty(response, result.status);
+    } else {
+      sendJson(response, result.status, result.body, result.status === 400 || result.status === 413);
+    }
+    return;
+  }
+
+  sendEmpty(response, 404);
+}
+
+async function closeRejectedStream(stream: AsyncIterable<string>): Promise<void> {
+  const iterator = stream[Symbol.asyncIterator]();
+  try {
+    await iterator.return?.();
+  } catch {
+    // Quota rejection must not expose stream cleanup failures.
+  }
+}
+
+async function readRequestBody(
+  request: IncomingMessage,
+  maxBytes: number,
+): Promise<Buffer | "oversized"> {
+  const declaredLength = request.headers["content-length"];
+  if (declaredLength !== undefined) {
+    if (!/^\d+$/u.test(declaredLength)) {
+      request.resume();
+      return "oversized";
+    }
+    if (Number(declaredLength) > maxBytes) {
+      request.resume();
+      return "oversized";
+    }
+  }
+
+  let bytes = 0;
+  const chunks: Buffer[] = [];
+  for await (const chunk of request) {
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    bytes += buffer.length;
+    if (bytes > maxBytes) {
+      request.resume();
+      return "oversized";
+    }
+    chunks.push(buffer);
+  }
+  return Buffer.concat(chunks, bytes);
+}
+
+function parseRequestPath(value: string | undefined): string | null {
+  if (value === undefined || !value.startsWith("/") || value.startsWith("//")) return null;
+  try {
+    return new URL(value, "https://local.invalid").pathname;
+  } catch {
+    return null;
+  }
+}
+
+function sendEmpty(response: ServerResponse, status: number, closeConnection = false): void {
+  if (response.headersSent || response.destroyed) return;
+  response.writeHead(status, {
+    "cache-control": "no-store",
+    ...(closeConnection ? { connection: "close" } : {}),
+    "content-length": "0",
+  });
+  response.end();
+}
+
+function sendRateLimited(response: ServerResponse, retryAfter: number): void {
+  if (response.headersSent || response.destroyed) return;
+  response.writeHead(429, {
+    "cache-control": "no-store",
+    connection: "close",
+    "content-length": "0",
+    "retry-after": retryAfter.toString(),
+  });
+  response.end();
+}
+
+function sendJson(
+  response: ServerResponse,
+  status: number,
+  value: unknown,
+  closeConnection = false,
+): void {
+  const body = JSON.stringify(value);
+  response.writeHead(status, {
+    "cache-control": "no-store",
+    ...(closeConnection ? { connection: "close" } : {}),
+    "content-length": Buffer.byteLength(body).toString(),
+    "content-type": "application/json; charset=utf-8",
+    "x-content-type-options": "nosniff",
+  });
+  response.end(body);
+}
+
+async function startEventStream(
+  response: ServerResponse,
+  stream: AsyncIterable<string>,
+  releaseQuota: () => void,
+): Promise<void> {
+  if (response.destroyed || response.writableEnded || response.headersSent) {
+    releaseQuota();
+    await closeRejectedStream(stream);
+    return;
+  }
+  try {
+    response.writeHead(200, {
+      "cache-control": "no-store",
+      connection: "keep-alive",
+      "content-type": "text/event-stream; charset=utf-8",
+      "x-accel-buffering": "no",
+      "x-content-type-options": "nosniff",
+    });
+  } catch (error) {
+    releaseQuota();
+    await closeRejectedStream(stream);
+    throw error;
+  }
+  void (async () => {
+    try {
+      for await (const chunk of stream) {
+        if (response.destroyed || response.writableEnded) break;
+        if (!response.write(chunk)) await waitForDrain(response);
+      }
+    } catch {
+      // Stream failures terminate the connection without exposing internals.
+    } finally {
+      releaseQuota();
+      if (!response.destroyed && !response.writableEnded) response.end();
+    }
+  })();
+}
+
+function waitForDrain(response: ServerResponse): Promise<void> {
+  return new Promise((resolve) => {
+    const finish = (): void => {
+      response.off("drain", finish);
+      response.off("close", finish);
+      response.off("error", finish);
+      resolve();
+    };
+    response.once("drain", finish);
+    response.once("close", finish);
+    response.once("error", finish);
+  });
+}
+
+function protocolError(code: string, message: string): object {
+  return { protocol_version: "1", error: { code, message } };
+}
+
+const INVALID_COORDINATION_QUERY = Symbol("invalid-coordination-query");
+
+function parseCursorParameter(
+  value: string | undefined,
+  path: string,
+): string | undefined | typeof INVALID_COORDINATION_QUERY {
+  if (value === undefined) return undefined;
+  try {
+    const parsed = new URL(value, "https://local.invalid");
+    const keys = [...parsed.searchParams.keys()];
+    if (!path.endsWith("/stream")) {
+      return keys.length === 0 ? undefined : INVALID_COORDINATION_QUERY;
+    }
+    if (keys.some((key) => key !== "cursor")) return INVALID_COORDINATION_QUERY;
+    const values = parsed.searchParams.getAll("cursor");
+    if (values.length === 0) return undefined;
+    return values.length === 1 && values[0]!.length > 0
+      ? values[0]
+      : INVALID_COORDINATION_QUERY;
+  } catch {
+    return INVALID_COORDINATION_QUERY;
+  }
+}
+
+function isCoordinationPath(path: string | null): path is string {
+  return path === "/api/client/attach" || path === "/api/cubes" ||
+    path?.startsWith("/api/cubes/") === true;
+}
+
+function applyServerLimits(server: HttpsServer, limits: ServiceLimits): Set<Socket> {
+  server.maxConnections = limits.maxConnections;
+  server.maxRequestsPerSocket = limits.maxRequestsPerSocket;
+  server.requestTimeout = limits.requestTimeoutMs;
+  server.headersTimeout = limits.headersTimeoutMs;
+  server.keepAliveTimeout = limits.keepAliveTimeoutMs;
+  server.setTimeout(
+    Math.min(limits.handlerTimeoutMs * 2, 2_147_483_647),
+    (socket) => socket.destroy(),
+  );
+  const addressConnections = new ConcurrentQuota(limits.maxConnectionsPerAddress);
+  const acceptedSockets = new Set<Socket>();
+  server.on("connection", (socket) => {
+    const tracked = socket as Socket;
+    acceptedSockets.add(tracked);
+    tracked.once("close", () => acceptedSockets.delete(tracked));
+    const identity = tracked.remoteAddress ?? "unknown";
+    const release = addressConnections.acquire(identity);
+    if (release === null) {
+      socket.destroy();
+      return;
+    }
+    socket.once("close", release);
+  });
+  return acceptedSockets;
+}
+
+function validateLimits(limits: ServiceLimits): void {
+  for (const [name, value] of Object.entries(limits)) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+      throw new Error(`${name} must be a positive safe integer.`);
+    }
+  }
+  if (limits.headersTimeoutMs > limits.requestTimeoutMs) {
+    throw new Error("headersTimeoutMs must not exceed requestTimeoutMs.");
+  }
+  if (limits.tlsHandshakeTimeoutMs > limits.requestTimeoutMs) {
+    throw new Error("tlsHandshakeTimeoutMs must not exceed requestTimeoutMs.");
+  }
+  if (limits.maxConnectionsPerAddress > limits.maxConnections) {
+    throw new Error("maxConnectionsPerAddress must not exceed maxConnections.");
+  }
+  if (limits.maxStreamsPerCredential > limits.maxConnectionsPerAddress) {
+    throw new Error("maxStreamsPerCredential must not exceed maxConnectionsPerAddress.");
+  }
+  if (limits.maxRequestsPerWindow > limits.maxRequestsPerAddressWindow) {
+    throw new Error("maxRequestsPerWindow must not exceed maxRequestsPerAddressWindow.");
+  }
+  if (limits.maxRequestsPerAddressWindow > limits.maxRequestsGlobalWindow) {
+    throw new Error("maxRequestsPerAddressWindow must not exceed maxRequestsGlobalWindow.");
+  }
+}
+
+export function validateTlsCertificate(
+  certificate: string | Buffer,
+  host: string,
+  mode: "loopback" | "lan",
+  caCertificate?: string | Buffer,
+): void {
+  const [parsed, ...intermediates] = parseCertificateBundle(certificate);
+  if (parsed === undefined) throw new Error("TLS certificate is missing.");
+  const now = Date.now();
+  if (now < parsed.validFromDate.getTime() || now > parsed.validToDate.getTime()) {
+    throw new Error("TLS certificate is outside its validity period.");
+  }
+  if (parsed.ca) {
+    throw new Error("TLS certificate must be a non-CA leaf certificate.");
+  }
+  if (parsed.checkIP(host) === undefined) {
+    throw new Error("TLS certificate does not cover the bind address.");
+  }
+  const serverAuthOid = "1.3.6.1.5.5.7.3.1";
+  if (parsed.keyUsage.length > 0 && !parsed.keyUsage.includes(serverAuthOid)) {
+    throw new Error("TLS certificate does not permit server authentication.");
+  }
+  if (caCertificate === undefined) {
+    if (mode === "lan") throw new Error("A private LAN bind requires an explicit TLS trust anchor.");
+    return;
+  }
+  const [trustAnchor, ...additionalIntermediates] = parseCertificateBundle(caCertificate);
+  if (trustAnchor === undefined) throw new Error("TLS trust anchor is missing.");
+  validateCertificateAuthority(trustAnchor, now, "TLS trust anchor");
+  if (!trustAnchor.verify(trustAnchor.publicKey)) {
+    throw new Error("TLS trust anchor must be self-signed.");
+  }
+  const chain = [...intermediates, ...additionalIntermediates];
+  for (const intermediate of chain) validateCertificateAuthority(intermediate, now, "TLS intermediate");
+  const path = findCertificatePath(parsed, trustAnchor, chain, new Set(), 0);
+  if (path === null) {
+    throw new Error("TLS certificate is not signed by the configured trust anchor.");
+  }
+  validatePathLengthConstraints(path);
+}
+
+function parseCertificateBundle(value: string | Buffer): X509Certificate[] {
+  const text = typeof value === "string" ? value : value.toString("utf8");
+  const pem = text.match(/-----BEGIN CERTIFICATE-----[\s\S]*?-----END CERTIFICATE-----/gu);
+  return pem === null ? [new X509Certificate(value)] : pem.map((certificate) => new X509Certificate(certificate));
+}
+
+function validateCertificateAuthority(certificate: X509Certificate, now: number, label: string): void {
+  if (!certificate.ca) throw new Error(`${label} must be a CA certificate.`);
+  if (now < certificate.validFromDate.getTime() || now > certificate.validToDate.getTime()) {
+    throw new Error(`${label} is outside its validity period.`);
+  }
+  const constraints = readCaConstraints(certificate);
+  if (!constraints.basicConstraintsCritical || !constraints.ca || !constraints.keyCertSign) {
+    throw new Error(`${label} lacks required CA constraints or certificate-signing usage.`);
+  }
+}
+
+function findCertificatePath(
+  certificate: X509Certificate,
+  trustAnchor: X509Certificate,
+  intermediates: readonly X509Certificate[],
+  visited: Set<string>,
+  depth: number,
+): X509Certificate[] | null {
+  if (depth > 8) return null;
+  if (isIssuedBy(certificate, trustAnchor)) return [certificate, trustAnchor];
+  for (const intermediate of intermediates) {
+    if (visited.has(intermediate.fingerprint256) || !isIssuedBy(certificate, intermediate)) continue;
+    visited.add(intermediate.fingerprint256);
+    const path = findCertificatePath(intermediate, trustAnchor, intermediates, visited, depth + 1);
+    if (path !== null) return [certificate, ...path];
+    visited.delete(intermediate.fingerprint256);
+  }
+  return null;
+}
+
+function isIssuedBy(certificate: X509Certificate, issuer: X509Certificate): boolean {
+  return certificate.checkIssued(issuer) && certificate.verify(issuer.publicKey);
+}
+
+function validatePathLengthConstraints(path: readonly X509Certificate[]): void {
+  for (let index = 1; index < path.length; index += 1) {
+    const authority = path[index]!;
+    const { pathLength } = readCaConstraints(authority);
+    if (pathLength === null) continue;
+    const subordinateAuthorities = path.slice(1, index)
+      .filter((certificate) => certificate.subject !== certificate.issuer).length;
+    if (subordinateAuthorities > pathLength) {
+      throw new Error("TLS certificate chain exceeds a CA path-length constraint.");
+    }
+  }
+}
+
+interface CaConstraints {
+  readonly basicConstraintsCritical: boolean;
+  readonly ca: boolean;
+  readonly pathLength: number | null;
+  readonly keyCertSign: boolean;
+}
+
+function readCaConstraints(certificate: X509Certificate): CaConstraints {
+  const extensions = readCertificateExtensions(certificate.raw);
+  const basic = extensions.get("551d13");
+  const keyUsage = extensions.get("551d0f");
+  if (basic === undefined || keyUsage === undefined) {
+    return { basicConstraintsCritical: false, ca: false, pathLength: null, keyCertSign: false };
+  }
+  const basicSequence = readDerElement(basic.value, 0, basic.value.length);
+  if (basicSequence.tag !== 0x30 || basicSequence.end !== basic.value.length) throw new Error("Invalid CA constraints.");
+  const basicChildren = readDerChildren(basic.value, basicSequence);
+  const caElement = basicChildren.find((element) => element.tag === 0x01);
+  const pathElement = basicChildren.find((element) => element.tag === 0x02);
+  const usageBits = readDerElement(keyUsage.value, 0, keyUsage.value.length);
+  if (usageBits.tag !== 0x03 || usageBits.end !== keyUsage.value.length ||
+      usageBits.contentStart + 1 >= usageBits.end) throw new Error("Invalid CA key usage.");
+  return {
+    basicConstraintsCritical: basic.critical,
+    ca: caElement !== undefined && basic.value[caElement.contentStart] !== 0,
+    pathLength: pathElement === undefined ? null : readDerInteger(basic.value, pathElement),
+    keyCertSign: (keyUsage.value[usageBits.contentStart + 1]! & 0x04) !== 0,
+  };
+}
+
+function readCertificateExtensions(certificate: Buffer): Map<string, { critical: boolean; value: Buffer }> {
+  const outer = readDerElement(certificate, 0, certificate.length);
+  const outerChildren = readDerChildren(certificate, outer);
+  const tbs = outerChildren[0];
+  if (outer.tag !== 0x30 || tbs?.tag !== 0x30) throw new Error("Invalid X.509 certificate encoding.");
+  const extensionWrapper = readDerChildren(certificate, tbs).find((element) => element.tag === 0xa3);
+  if (extensionWrapper === undefined) return new Map();
+  const wrapperChildren = readDerChildren(certificate, extensionWrapper);
+  const extensionSequence = wrapperChildren[0];
+  if (extensionSequence?.tag !== 0x30) throw new Error("Invalid X.509 extension encoding.");
+  const result = new Map<string, { critical: boolean; value: Buffer }>();
+  for (const extension of readDerChildren(certificate, extensionSequence)) {
+    if (extension.tag !== 0x30) throw new Error("Invalid X.509 extension encoding.");
+    const fields = readDerChildren(certificate, extension);
+    const oid = fields[0];
+    const hasCriticalField = fields[1]?.tag === 0x01;
+    const critical = hasCriticalField && certificate[fields[1]!.contentStart] !== 0;
+    const value = fields[hasCriticalField ? 2 : 1];
+    if (oid?.tag !== 0x06 || value?.tag !== 0x04) throw new Error("Invalid X.509 extension encoding.");
+    result.set(
+      certificate.subarray(oid.contentStart, oid.end).toString("hex"),
+      { critical, value: certificate.subarray(value.contentStart, value.end) },
+    );
+  }
+  return result;
+}
+
+interface DerElement {
+  readonly tag: number;
+  readonly contentStart: number;
+  readonly end: number;
+}
+
+function readDerElement(data: Buffer, offset: number, limit: number): DerElement {
+  if (offset + 2 > limit) throw new Error("Invalid DER encoding.");
+  const tag = data[offset]!;
+  const firstLength = data[offset + 1]!;
+  let length = firstLength;
+  let contentStart = offset + 2;
+  if ((firstLength & 0x80) !== 0) {
+    const lengthBytes = firstLength & 0x7f;
+    if (lengthBytes === 0 || lengthBytes > 4 || contentStart + lengthBytes > limit) {
+      throw new Error("Invalid DER encoding.");
+    }
+    length = 0;
+    for (let index = 0; index < lengthBytes; index += 1) {
+      length = (length * 256) + data[contentStart + index]!;
+    }
+    contentStart += lengthBytes;
+  }
+  const end = contentStart + length;
+  if (end > limit || end < contentStart) throw new Error("Invalid DER encoding.");
+  return { tag, contentStart, end };
+}
+
+function readDerChildren(data: Buffer, parent: DerElement): DerElement[] {
+  const children: DerElement[] = [];
+  let offset = parent.contentStart;
+  while (offset < parent.end) {
+    const child = readDerElement(data, offset, parent.end);
+    children.push(child);
+    offset = child.end;
+  }
+  if (offset !== parent.end) throw new Error("Invalid DER encoding.");
+  return children;
+}
+
+function readDerInteger(data: Buffer, element: DerElement): number {
+  if (element.tag !== 0x02 || element.contentStart === element.end ||
+      (data[element.contentStart]! & 0x80) !== 0) throw new Error("Invalid DER integer.");
+  let value = 0;
+  for (let offset = element.contentStart; offset < element.end; offset += 1) {
+    value = (value * 256) + data[offset]!;
+    if (!Number.isSafeInteger(value)) throw new Error("DER integer exceeds policy.");
+  }
+  return value;
+}
+
+export class RequestRateLimiter {
+  readonly #limits: Pick<ServiceLimits, "maxRequestsPerWindow" | "rateLimitWindowMs" | "maxRateLimitEntries">;
+  readonly #clock: () => number;
+  readonly #maxRequests: number;
+  readonly #buckets = new Map<string, { count: number; resetAt: number }>();
+
+  constructor(limits: ServiceLimits, maxRequests = limits.maxRequestsPerWindow, clock: () => number = Date.now) {
+    this.#limits = limits;
+    this.#maxRequests = maxRequests;
+    this.#clock = clock;
+  }
+
+  consume(identity: string): number | null {
+    const reservation = this.reserve(identity);
+    reservation.commit();
+    return reservation.retryAfter;
+  }
+
+  reserve(identity: string): RateLimitReservation {
+    const now = this.#clock();
+    const existing = this.#buckets.get(identity);
+    if (existing !== undefined && existing.resetAt > now) {
+      if (existing.count >= this.#maxRequests) {
+        return rejectedReservation(Math.max(1, Math.ceil((existing.resetAt - now) / 1_000)));
+      }
+      existing.count += 1;
+      return acceptedReservation(() => { existing.count -= 1; });
+    }
+    if (existing !== undefined) this.#buckets.delete(identity);
+    for (const [key, bucket] of this.#buckets) {
+      if (bucket.resetAt <= now) this.#buckets.delete(key);
+    }
+    if (this.#buckets.size >= this.#limits.maxRateLimitEntries) {
+      return rejectedReservation(Math.max(1, Math.ceil(this.#limits.rateLimitWindowMs / 1_000)));
+    }
+    const bucket = { count: 1, resetAt: now + this.#limits.rateLimitWindowMs };
+    this.#buckets.set(identity, bucket);
+    return acceptedReservation(() => {
+      if (this.#buckets.get(identity) === bucket) this.#buckets.delete(identity);
+    });
+  }
+}
+
+export class PreAuthAdmissionLimiter {
+  readonly #global: RequestRateLimiter;
+  readonly #address: RequestRateLimiter;
+
+  constructor(limits: ServiceLimits, clock: () => number = Date.now) {
+    this.#global = new RequestRateLimiter(limits, limits.maxRequestsGlobalWindow, clock);
+    this.#address = new RequestRateLimiter(limits, limits.maxRequestsPerAddressWindow, clock);
+  }
+
+  consume(addressIdentity: string): number | null {
+    const address = this.#address.reserve(addressIdentity);
+    if (address.retryAfter !== null) return address.retryAfter;
+    const global = this.#global.reserve("global");
+    if (global.retryAfter !== null) {
+      address.rollback();
+      return global.retryAfter;
+    }
+    address.commit();
+    global.commit();
+    return null;
+  }
+}
+
+interface RateLimitReservation {
+  readonly retryAfter: number | null;
+  readonly commit: () => void;
+  readonly rollback: () => void;
+}
+
+function acceptedReservation(undo: () => void): RateLimitReservation {
+  let active = true;
+  return {
+    retryAfter: null,
+    commit: () => { active = false; },
+    rollback: () => {
+      if (!active) return;
+      active = false;
+      undo();
+    },
+  };
+}
+
+function rejectedReservation(retryAfter: number): RateLimitReservation {
+  return { retryAfter, commit: () => undefined, rollback: () => undefined };
+}
+
+export class ConcurrentQuota {
+  readonly #limit: number;
+  readonly #counts = new Map<string, number>();
+
+  constructor(limit: number) {
+    this.#limit = limit;
+  }
+
+  acquire(identity: string): (() => void) | null {
+    const count = this.#counts.get(identity) ?? 0;
+    if (count >= this.#limit) return null;
+    this.#counts.set(identity, count + 1);
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      const remaining = (this.#counts.get(identity) ?? 1) - 1;
+      if (remaining <= 0) this.#counts.delete(identity);
+      else this.#counts.set(identity, remaining);
+    };
+  }
+}
+
+function credentialIdentity(authorization: string | undefined): string | null {
+  if (authorization === undefined) return null;
+  return `credential:${createHash("sha256").update(authorization).digest("base64url")}`;
+}
+
+function consumeAuthenticatedRateLimit(
+  authorization: string | undefined,
+  rateLimiter: RequestRateLimiter,
+): number | null {
+  const identity = credentialIdentity(authorization);
+  return identity === null ? null : rateLimiter.consume(identity);
+}
+
+function listen(server: HttpsServer, port: number, host: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const onError = (error: Error): void => {
+      server.off("listening", onListening);
+      reject(error);
+    };
+    const onListening = (): void => {
+      server.off("error", onError);
+      resolve();
+    };
+    server.once("error", onError);
+    server.once("listening", onListening);
+    server.listen(port, host);
+  });
+}
+
+async function close(server: HttpsServer, acceptedSockets: Set<Socket>): Promise<void> {
+  const socketClosures = [...acceptedSockets].map((socket) => new Promise<void>((resolve) => {
+    socket.once("close", () => resolve());
+  }));
+  const listenerClosure = new Promise<void>((resolve, reject) => {
+    server.close((error) => {
+      if (error !== undefined) reject(error);
+      else resolve();
+    });
+  });
+  for (const socket of acceptedSockets) socket.destroy();
+  server.closeAllConnections();
+  await Promise.all([listenerClosure, ...socketClosures]);
+  if (acceptedSockets.size !== 0) throw new Error("HTTPS socket closure could not be confirmed.");
+}