@hisoka-io/anon-rpc-worker 0.2.0 → 0.4.0

package/src/tls/transport.ts

@@ -0,0 +1,257 @@
+/**
+ * The transport of each fetch hop (E2E TLS design §5): a TLS tunnel, the
+ * exit's `HttpRequest` path, or a refusal. The choice is made before any
+ * byte of the hop leaves the worker, from the URL and the capability data
+ * only: exits skipped after failed opens still count, and a call that started
+ * on a tunnel never continues in plaintext, so dropping tunnel traffic gives
+ * a `network-error`, never a downgrade. Under `"preferred"`, a topology in
+ * which no exit advertises `tunnel_v1` sends calls in plaintext.
+ */
+import { TUNNEL_PART_MAX_DATA, type DecodedHttpResponse, type TunnelRejectCodeV1 } from "@hisoka-io/nox-client";
+import type { TlsSetting } from "../config.js";
+import { CALL_CODES, NoxWorkerError, callError } from "../errors.js";
+import {
+  MAX_REQUEST_HEADER_BYTES,
+  mapClientError,
+  type CallBudget,
+  type PreparedRequest,
+  type TunnelHop,
+} from "../fetch-map.js";
+import { describeError, type WorkerLogger } from "../log.js";
+import { TLS_PORT } from "./channel.js";
+import { tlsErrorCode, type NoxTlsBindings } from "./module.js";
+import { NoTunnelExitError, type TlsPool } from "./pool.js";
+import {
+  TunnelOpenTimeoutError,
+  TunnelProtocolError,
+  TunnelRejectedError,
+  TunnelTimeoutError,
+} from "./tunnel.js";
+
+/** Reply blocks per exchange the exits accept by default (`max_surbs_per_exchange`). */
+export const MAX_SURBS_PER_EXCHANGE = 32;
+/** Parts in one 1 MiB exit window (`max_window_bytes`). */
+export const WINDOW_PARTS = 32;
+/** Reply blocks for an exchange of unknown reply size. */
+export const MIN_REQUEST_SURBS = 2;
+
+/** Why a URL cannot go through a tunnel (logged as `tls.fallback{reason}`). */
+export type FallbackReason = "http-url" | "port" | "ip-literal" | "host-name" | "no-tunnel-exit";
+
+/** What a tunnel needs from a URL. */
+export interface TunnelTarget {
+  readonly host: string;
+  /** Path and query, the HTTP request target. */
+  readonly target: string;
+  /** `Authorization` from URL credentials, when the URL carries any. */
+  readonly authorization: string | undefined;
+}
+
+/** Longest DNS name the exit accepts. */
+const MAX_HOST_BYTES = 253;
+const DNS_NAME_RE = /^[a-z0-9-]+(?:\.[a-z0-9-]+)*$/u;
+const IPV4_RE = /^\d{1,3}(?:\.\d{1,3}){3}$/u;
+
+/** The tunnel target of `url`, or why it has none. */
+export function tunnelTarget(url: URL): TunnelTarget | FallbackReason {
+  if (url.protocol !== "https:") return "http-url";
+  if (url.port !== "" && Number(url.port) !== TLS_PORT) return "port";
+  const host = url.hostname;
+  if (host.startsWith("[") || IPV4_RE.test(host)) return "ip-literal";
+  if (host.length > MAX_HOST_BYTES || !DNS_NAME_RE.test(host)) return "host-name";
+  const authorization = url.username === "" && url.password === ""
+    ? undefined
+    : `Basic ${base64(new TextEncoder().encode(`${decodeURIComponent(url.username)}:${decodeURIComponent(url.password)}`))}`;
+  return { host, target: `${url.pathname}${url.search}`, authorization };
+}
+
+/**
+ * The transport of one hop under `setting` (the §5 table). `hop` counts
+ * redirects; `startedOnTunnel` is true once an earlier hop of the call used
+ * a tunnel. Throws the call's rejection when the hop may not leave.
+ */
+export function chooseTransport(
+  setting: TlsSetting,
+  url: URL,
+  tunnelExitKnown: boolean,
+  hop: number,
+  startedOnTunnel: boolean,
+): { readonly via: "tunnel" } | { readonly via: "http"; readonly reason: FallbackReason | undefined } {
+  if (setting === "off" && !startedOnTunnel) return { via: "http", reason: undefined };
+  const target = tunnelTarget(url);
+  const reason = typeof target === "string" ? target : tunnelExitKnown ? undefined : "no-tunnel-exit";
+  if (reason === undefined) return { via: "tunnel" };
+  if (startedOnTunnel) {
+    throw callError(
+      CALL_CODES.networkError,
+      `Redirect refused: this call started on a TLS tunnel and the target cannot use one (${reason})`,
+    );
+  }
+  if (setting === "preferred") return { via: "http", reason };
+  if (reason === "no-tunnel-exit") throw callError(CALL_CODES.networkError, "No exit offers TLS tunnels");
+  const message = "TLS tunnels reach https hosts by name on port 443";
+  throw hop === 0
+    ? callError(CALL_CODES.unsupported, `${message} (tls is "required")`)
+    : callError(CALL_CODES.networkError, `Redirect refused: ${message} (tls is "required")`);
+}
+
+/** Reply blocks for the exchange that carries a request expecting `expectedBytes`. */
+export function requestSurbs(expectedBytes: number | undefined): number {
+  if (expectedBytes === undefined || expectedBytes <= 0) return MIN_REQUEST_SURBS;
+  const wanted = Math.ceil(expectedBytes / TUNNEL_PART_MAX_DATA) + 1;
+  return Math.max(MIN_REQUEST_SURBS, Math.min(wanted, MAX_SURBS_PER_EXCHANGE, WINDOW_PARTS + 1));
+}
+
+const PERMISSION_CODES: ReadonlySet<TunnelRejectCodeV1> = new Set(["PortNotAllowed", "HostNotAllowed", "DestinationBlocked"]);
+const PROTOCOL_CODES: ReadonlySet<TunnelRejectCodeV1> = new Set(["NotTls", "Malformed", "OutOfOrder"]);
+const TLS_PROTOCOL_CODES: ReadonlySet<string> = new Set([
+  "TLS_ALERT_RECEIVED",
+  "TLS_DECRYPT_FAILED",
+  "TLS_PEER_MISBEHAVED",
+  "TLS_PEER_INCOMPATIBLE",
+  "TLS_PROTOCOL",
+  "TLS_IO",
+  "TLS_CLOSED",
+  "HTTP_RESPONSE_MALFORMED",
+  "HTTP_RESPONSE_TRUNCATED",
+]);
+
+/** A tunnel or TLS failure as a call rejection (the §5 error table). */
+export function mapTlsError(error: unknown): NoxWorkerError {
+  if (error instanceof NoxWorkerError) return error;
+  const detail = describeError(error);
+  if (error instanceof TunnelRejectedError) {
+    if (PERMISSION_CODES.has(error.code)) {
+      return callError(CALL_CODES.permissionDenied, `The tunnel exit refuses this destination (${error.code})`, error);
+    }
+    if (PROTOCOL_CODES.has(error.code)) return callError(CALL_CODES.protocolError, detail, error);
+    if (error.code === "ByteLimit") return callError(CALL_CODES.tooLarge, detail, error);
+    return callError(CALL_CODES.networkError, detail, error);
+  }
+  if (error instanceof TunnelTimeoutError) return callError(CALL_CODES.timeout, detail, error);
+  if (error instanceof TunnelOpenTimeoutError || error instanceof NoTunnelExitError) {
+    return callError(CALL_CODES.networkError, detail, error);
+  }
+  if (error instanceof TunnelProtocolError) return callError(CALL_CODES.protocolError, detail, error);
+  const code = tlsErrorCode(error);
+  if (code === "TLS_CERTIFICATE_REJECTED") return callError(CALL_CODES.networkError, detail, error);
+  if (code === "HTTP_RESPONSE_TOO_LARGE") return callError(CALL_CODES.tooLarge, detail, error);
+  if (code === "HTTP_REQUEST_INVALID" || code === "TLS_INVALID_SERVER_NAME") {
+    return callError(CALL_CODES.unsupported, detail, error);
+  }
+  if (code !== undefined && TLS_PROTOCOL_CODES.has(code)) return callError(CALL_CODES.protocolError, detail, error);
+  return mapClientError(error);
+}
+
+/** Response headers that describe the TLS connection itself. */
+const CONNECTION_HEADERS = new Set(["connection", "keep-alive", "transfer-encoding", "te", "trailer", "upgrade", "proxy-connection"]);
+
+/** Tunnel exchanges for fetch hops. */
+export class TlsTransport implements TunnelHop {
+  constructor(
+    private readonly pool: TlsPool,
+    private readonly bindings: NoxTlsBindings,
+    private readonly settings: { readonly tls: TlsSetting; readonly tlsSession: string; readonly maxResponseBytes: number },
+    private readonly log: WorkerLogger,
+    private readonly now: () => number,
+  ) {}
+
+  /** `chooseTransport` with this worker's setting and exits; logs a fallback. */
+  route(request: PreparedRequest, hop: number, startedOnTunnel: boolean): "tunnel" | "http" {
+    const choice = chooseTransport(this.settings.tls, new URL(request.url), this.pool.offersTunnels(), hop, startedOnTunnel);
+    if (choice.via === "http" && choice.reason !== undefined) this.log.info("tls.fallback", { reason: choice.reason });
+    return choice.via;
+  }
+
+  /**
+   * One hop through a TLS tunnel. A tunnel lost before the response (the
+   * exit no longer knows the session, a silent exit, a spare the upstream
+   * closed) is retried once on a new tunnel for a resendable read, or for
+   * any request whose only copy the exit refused before writing it
+   * (`UnknownSession`, `Expired`, `UpstreamClosed`).
+   */
+  async exchange(request: PreparedRequest, budget: CallBudget): Promise<DecodedHttpResponse> {
+    const target = tunnelTarget(new URL(request.url));
+    if (typeof target === "string") throw callError(CALL_CODES.internalError, `A ${target} URL reached the tunnel path`);
+    const http = this.encode(request, target);
+    const resendable = request.profile.retryable;
+    for (let attempt = 0; ; attempt++) {
+      const deadlineAt = this.now() + budget.remainingMs();
+      let channel;
+      try {
+        channel = await this.pool.acquire(target.host, { deadlineAt, signal: budget.signal });
+      } catch (error) {
+        if (budget.signal.aborted) throw budget.signal.reason;
+        throw mapTlsError(error);
+      }
+      try {
+        const reply = await channel.request({
+          http,
+          headRequest: request.method === "HEAD",
+          maxHeadBytes: MAX_REQUEST_HEADER_BYTES,
+          maxBodyBytes: this.settings.maxResponseBytes,
+          surbs: requestSurbs(request.profile.expectedResponseBytes),
+          deadlineAt,
+          signal: budget.signal,
+          background: false,
+        });
+        this.pool.release(channel, true);
+        return {
+          status: reply.status,
+          headers: reply.headers.filter(([name]) => !CONNECTION_HEADERS.has(name.toLowerCase())),
+          body: reply.body,
+          truncated: false,
+        };
+      } catch (error) {
+        this.pool.release(channel, false);
+        if (budget.signal.aborted) throw budget.signal.reason;
+        if (attempt > 0 || budget.remainingMs() <= 0 || !retriable(error, resendable)) throw mapTlsError(error);
+        this.log.info("tls.retry", { reason: error instanceof Error ? error.name : "error" });
+      }
+    }
+  }
+
+  private encode(request: PreparedRequest, target: TunnelTarget): Uint8Array {
+    const headers: string[] = [];
+    let hasAuthorization = false;
+    for (const [name, value] of request.headers) {
+      if (name.toLowerCase() === "authorization") hasAuthorization = true;
+      headers.push(name, value);
+    }
+    if (target.authorization !== undefined && !hasAuthorization) headers.push("authorization", target.authorization);
+    const contentType = request.headers.find(([name]) => name.toLowerCase() === "content-type")?.[1];
+    const json = request.body.length > 0 && (request.profile.method !== undefined || contentType?.toLowerCase().includes("json") === true);
+    try {
+      return this.bindings.encodeRequest(
+        request.method,
+        target.host,
+        target.target,
+        headers,
+        request.body,
+        this.settings.tlsSession === "keep-alive",
+        json,
+      );
+    } catch (error) {
+      throw mapTlsError(error);
+    }
+  }
+}
+
+/** Whether a failed tunnel hop may run again on a new tunnel. */
+function retriable(error: unknown, resendable: boolean): boolean {
+  if (error instanceof TunnelRejectedError) {
+    const unwritten = error.code === "UnknownSession" || error.code === "Expired" || error.code === "UpstreamClosed";
+    if (unwritten && error.soleCopy) return true;
+    return resendable && unwritten;
+  }
+  if (!resendable) return false;
+  if (error instanceof TunnelTimeoutError || error instanceof TunnelOpenTimeoutError) return true;
+  // A spare the upstream had already closed: the stream ended before any response byte.
+  return tlsErrorCode(error) === "HTTP_RESPONSE_TRUNCATED";
+}
+
+function base64(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}

package/src/tls/tunnel.ts

@@ -0,0 +1,360 @@
+/**
+ * One TLS tunnel through one Nox exit (E2E TLS design §2.5): the exit holds a
+ * TCP connection to the upstream and relays TLS records both ways; this side
+ * numbers the writes, reorders the reply parts and decides when to send
+ * another copy.
+ *
+ * - Stop-and-wait: one unconfirmed `seq` at a time. Any part or rejection for
+ *   a `seq` confirms it.
+ * - Every copy of a `seq` carries identical `data` (the exit writes each `seq`
+ *   once), goes to the same exit, and avoids the previous copy's entry and mix.
+ * - Downstream bytes are numbered from 0; parts are reordered by offset and
+ *   only contiguous bytes reach TLS. `ackOffset` is the contiguous point.
+ * - Another copy goes out on `NeedSurbs` or `Expired`, and, at most
+ *   `maxCopies` times per exchange, after silence or a gap that stays open.
+ * - `fin` is a hint: only the TLS session and HTTP framing decide that a
+ *   response is complete.
+ */
+import {
+  decodeTunnelReplyV1,
+  TUNNEL_ID_LEN,
+  type TopologyNode,
+  type TunnelRejectCodeV1,
+  type TunnelReplyV1,
+  type TunnelRequestV1,
+  type TunnelSendHandle,
+  type TunnelSendOptions,
+} from "@hisoka-io/nox-client";
+
+/** The slice of `NoxClient` tunnels use. */
+export interface TunnelPort {
+  tunnelExits(): TopologyNode[];
+  tunnelSend(exit: TopologyNode, request: TunnelRequestV1, options: TunnelSendOptions): TunnelSendHandle;
+}
+
+/** Copy timing; `copyAfterMs` is read at each use (it follows the observed p95). */
+export interface CopyPolicy {
+  copyAfterMs(): number;
+  readonly gapMs: number;
+  readonly maxCopies: number;
+}
+
+/** Longest hold the exit honours (`max_hold_ms`). */
+export const MAX_HOLD_MS = 30_000;
+/** Shortest hold the exit honours (`min_hold_ms`). */
+export const MIN_HOLD_MS = 1_000;
+/** A copy keeps listening this long past its hold, for parts still in the mixnet. */
+export const REPLY_GRACE_MS = 5_000;
+
+/** The exit refused an exchange. */
+export class TunnelRejectedError extends Error {
+  constructor(
+    readonly code: TunnelRejectCodeV1,
+    readonly retryable: boolean,
+    readonly seq: number,
+    /** True when exactly one copy of `seq` went out, so this rejection proves it was never written. */
+    readonly soleCopy: boolean,
+    detail: string,
+  ) {
+    super(`The tunnel exit refused seq ${seq}: ${code}${detail === "" ? "" : ` (${detail})`}`);
+    this.name = "TunnelRejectedError";
+  }
+}
+
+/** No part of an open arrived within the open timeout. */
+export class TunnelOpenTimeoutError extends Error {
+  constructor(readonly afterMs: number) {
+    super(`The tunnel exit did not answer the open within ${afterMs} ms`);
+    this.name = "TunnelOpenTimeoutError";
+  }
+}
+
+/** The exchange ran out of time before its job was done. */
+export class TunnelTimeoutError extends Error {
+  constructor(readonly seq: number, readonly confirmed: boolean) {
+    super(`Tunnel exchange seq ${seq} did not finish before the call deadline${confirmed ? "" : " (no reply at all)"}`);
+    this.name = "TunnelTimeoutError";
+  }
+}
+
+/** A reply part that does not decode: the exit or the path is broken. */
+export class TunnelProtocolError extends Error {
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = "TunnelProtocolError";
+  }
+}
+
+export interface ExchangeSpec {
+  /** TLS records to write upstream. */
+  readonly data: Uint8Array;
+  /** Reply blocks per copy. */
+  readonly surbs: number;
+  /** Half-close the upstream after writing. */
+  readonly close?: boolean;
+  /** Absolute time (ms) the exchange must finish by. */
+  readonly deadlineAt: number;
+  /** Spares and teardowns: not a wallet call. */
+  readonly background: boolean;
+  /** Aborts the exchange; its reason is the rejection. */
+  readonly signal?: AbortSignal;
+  /** Fail with `TunnelOpenTimeoutError` when nothing at all arrived in this long. */
+  readonly openTimeoutMs?: number;
+  /** Checked after each delivery: true ends the exchange. */
+  satisfied(): boolean;
+}
+
+/** How an exchange ended: its job was done, or the upstream ended the stream. */
+export type ExchangeOutcome = "satisfied" | "eof";
+
+export interface TunnelDeps {
+  readonly now: () => number;
+  readonly randomBytes: (length: number) => Uint8Array;
+}
+
+/**
+ * A tunnel to `host:port` through `exit`. `deliver` receives contiguous
+ * downstream bytes in order (it feeds the TLS session and may throw).
+ */
+export class Tunnel {
+  readonly id: Uint8Array;
+  private nextSeq = 0;
+  private contiguous = 0n;
+  private readonly held = new Map<bigint, Uint8Array>();
+  private eofAt: bigint | undefined;
+  private ended = false;
+
+  constructor(
+    private readonly port: TunnelPort,
+    readonly exit: TopologyNode,
+    readonly host: string,
+    readonly tcpPort: number,
+    private readonly policy: CopyPolicy,
+    private readonly deps: TunnelDeps,
+    private readonly deliver: (bytes: Uint8Array) => void,
+  ) {
+    this.id = deps.randomBytes(TUNNEL_ID_LEN);
+  }
+
+  /** True once the upstream stream ended (every byte up to the exit's EOF delivered). */
+  get eof(): boolean {
+    return this.ended;
+  }
+
+  /** Short id prefix for debug logs. */
+  get label(): string {
+    return Array.from(this.id.slice(0, 4), (byte) => byte.toString(16).padStart(2, "0")).join("");
+  }
+
+  /** Sequence number the next exchange will use. */
+  get seq(): number {
+    return this.nextSeq;
+  }
+
+  /**
+   * Run one exchange: a new `seq` carrying `spec.data`, copies as needed,
+   * until `spec.satisfied()`, the end of the stream, a rejection, the
+   * deadline or an abort.
+   */
+  exchange(spec: ExchangeSpec): Promise<ExchangeOutcome> {
+    const seq = this.nextSeq++;
+    const base = {
+      tunnelId: this.id,
+      seq,
+      open: seq === 0 ? { host: this.host, port: this.tcpPort } : null,
+      data: spec.data,
+      close: spec.close === true,
+    };
+    const startedAt = this.deps.now();
+    const listeners = new AbortController();
+
+    return new Promise<ExchangeOutcome>((resolve, reject) => {
+      let settled = false;
+      let confirmed = false;
+      let copiesSent = 0;
+      let timedCopies = 0;
+      let lastRoute: { entryId: string; mixId: string } | undefined;
+      let silenceTimer: ReturnType<typeof setTimeout> | undefined;
+      let gapTimer: ReturnType<typeof setTimeout> | undefined;
+      let openTimer: ReturnType<typeof setTimeout> | undefined;
+      let deadlineTimer: ReturnType<typeof setTimeout> | undefined;
+
+      const finish = (outcome: ExchangeOutcome | Error): void => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(silenceTimer);
+        clearTimeout(gapTimer);
+        clearTimeout(openTimer);
+        clearTimeout(deadlineTimer);
+        spec.signal?.removeEventListener("abort", onAbort);
+        listeners.abort();
+        if (outcome instanceof Error) reject(outcome);
+        else resolve(outcome);
+      };
+
+      const armSilence = (): void => {
+        clearTimeout(silenceTimer);
+        silenceTimer = setTimeout(() => timedCopy(), this.policy.copyAfterMs());
+      };
+
+      const timedCopy = (): void => {
+        if (settled) return;
+        if (timedCopies >= this.policy.maxCopies) return;
+        timedCopies += 1;
+        send();
+      };
+
+      const send = (): void => {
+        if (settled) return;
+        const remaining = spec.deadlineAt - this.deps.now();
+        if (remaining <= 0) {
+          finish(new TunnelTimeoutError(seq, confirmed));
+          return;
+        }
+        const holdMs = Math.max(MIN_HOLD_MS, Math.min(MAX_HOLD_MS, remaining));
+        const request: TunnelRequestV1 = { ...base, ackOffset: this.contiguous, holdMs };
+        // A copy steers clear of the previous copy's entry and mix.
+        const avoid = lastRoute === undefined ? new Set<string>() : new Set([lastRoute.entryId, lastRoute.mixId]);
+        let handle: TunnelSendHandle;
+        try {
+          handle = this.port.tunnelSend(this.exit, request, {
+            surbs: spec.surbs,
+            timeoutMs: holdMs + REPLY_GRACE_MS,
+            signal: listeners.signal,
+            avoid,
+            background: spec.background,
+            onReply: (body) => onPart(body),
+          });
+        } catch (error) {
+          finish(error instanceof Error ? error : new Error(String(error)));
+          return;
+        }
+        copiesSent += 1;
+        lastRoute = { entryId: handle.entryId, mixId: handle.mixId };
+        // A copy that could not be uploaded counts as silence: try another entry.
+        handle.done.catch(() => {
+          if (!settled && !listeners.signal.aborted && !confirmed) timedCopy();
+        });
+        armSilence();
+      };
+
+      const onPart = (body: Uint8Array): "more" | "done" => {
+        if (settled) return "done";
+        let reply: TunnelReplyV1;
+        try {
+          reply = decodeTunnelReplyV1(body);
+        } catch (error) {
+          finish(new TunnelProtocolError("A tunnel reply part does not decode", { cause: error }));
+          return "done";
+        }
+        // A late part of an earlier exchange: already superseded.
+        if (reply.seq !== seq) return "more";
+        confirmed = true;
+        clearTimeout(openTimer);
+        if (reply.kind === "Rejected") {
+          finish(new TunnelRejectedError(reply.code, reply.retryable, seq, copiesSent === 1, reply.detail));
+          return "done";
+        }
+        try {
+          this.accept(reply.offset, reply.data);
+        } catch (error) {
+          finish(error instanceof Error ? error : new Error(String(error)));
+          return "done";
+        }
+        if (reply.fin === "Eof") this.eofAt ??= reply.offset + BigInt(reply.data.length);
+        if (this.eofAt !== undefined && this.contiguous >= this.eofAt) this.ended = true;
+        if (spec.satisfied()) {
+          finish("satisfied");
+          return "done";
+        }
+        if (this.ended) {
+          finish("eof");
+          return "done";
+        }
+        if (this.held.size === 0) {
+          clearTimeout(gapTimer);
+          gapTimer = undefined;
+        } else if (gapTimer === undefined) {
+          gapTimer = setTimeout(() => {
+            gapTimer = undefined;
+            if (this.held.size > 0) timedCopy();
+          }, this.policy.gapMs);
+        }
+        if (reply.fin === "NeedSurbs" || reply.fin === "Expired") send();
+        else armSilence();
+        return "more";
+      };
+
+      const onAbort = (): void => finish(spec.signal?.reason instanceof Error ? spec.signal.reason : new Error("Tunnel exchange aborted"));
+      deadlineTimer = setTimeout(
+        () => finish(new TunnelTimeoutError(seq, confirmed)),
+        Math.max(0, spec.deadlineAt - startedAt),
+      );
+      if (spec.signal?.aborted === true) {
+        onAbort();
+        return;
+      }
+      spec.signal?.addEventListener("abort", onAbort, { once: true });
+      if (spec.openTimeoutMs !== undefined) {
+        const openTimeoutMs = spec.openTimeoutMs;
+        openTimer = setTimeout(() => {
+          if (!confirmed) finish(new TunnelOpenTimeoutError(openTimeoutMs));
+        }, openTimeoutMs);
+      }
+      send();
+    });
+  }
+
+  /**
+   * Close the upstream write side after `data` (a close_notify), without
+   * reply blocks and without waiting. Only after the last exchange was
+   * confirmed, so the `seq` stays in step with the exit.
+   */
+  teardown(data: Uint8Array, deadlineAt: number): Promise<void> {
+    const seq = this.nextSeq++;
+    const holdMs = Math.max(MIN_HOLD_MS, Math.min(MAX_HOLD_MS, deadlineAt - this.deps.now()));
+    const request: TunnelRequestV1 = {
+      tunnelId: this.id,
+      seq,
+      open: null,
+      ackOffset: this.contiguous,
+      data,
+      close: true,
+      holdMs,
+    };
+    try {
+      return this.port.tunnelSend(this.exit, request, { surbs: 0, timeoutMs: holdMs, background: true }).done;
+    } catch (error) {
+      return Promise.reject(error);
+    }
+  }
+
+  /** Place one part: deliver what is contiguous, hold what lies beyond a gap. */
+  private accept(offset: bigint, data: Uint8Array): void {
+    const end = offset + BigInt(data.length);
+    if (end <= this.contiguous) return;
+    if (offset > this.contiguous) {
+      const existing = this.held.get(offset);
+      if (existing === undefined || existing.length < data.length) this.held.set(offset, data);
+      return;
+    }
+    this.push(data.subarray(Number(this.contiguous - offset)));
+    for (;;) {
+      let advanced = false;
+      for (const [heldOffset, heldData] of this.held) {
+        if (heldOffset > this.contiguous) continue;
+        this.held.delete(heldOffset);
+        const heldEnd = heldOffset + BigInt(heldData.length);
+        if (heldEnd > this.contiguous) this.push(heldData.subarray(Number(this.contiguous - heldOffset)));
+        advanced = true;
+      }
+      if (!advanced) return;
+    }
+  }
+
+  private push(bytes: Uint8Array): void {
+    if (bytes.length === 0) return;
+    this.contiguous += BigInt(bytes.length);
+    this.deliver(bytes);
+  }
+}

package/src/worker.ts

@@ -2,15 +2,19 @@
 // the anon-rpc harness runs with `anonRpcWorker` installed (SPEC §7).
 //
 // The bundle build resolves "@hisoka-io/nox-wasm" to an init that compiles the
-// embedded nox-wasm bytes (no .wasm fetch), "nox-embed:snapshot" to the
-// pinned registry snapshot and "nox-embed:bootstrap" to the discovery
-// bootstrap (default anchors, RPC providers, policy). Everything else lives in
-// core.ts.
+// embedded nox-wasm bytes (no .wasm fetch), "nox-embed:tls" to the same for
+// the embedded nox-tls module, "nox-embed:tls-root" to a test bed's extra CA
+// (null in release builds), "nox-embed:snapshot" to the pinned registry
+// snapshot and "nox-embed:bootstrap" to the discovery bootstrap (default
+// anchors, RPC providers, policy). Everything else lives in core.ts.
 import { NoxClient, type NoxWasmBindings } from "@hisoka-io/nox-client";
 import initNoxWasm, * as noxWasm from "@hisoka-io/nox-wasm";
 import bootstrap from "nox-embed:bootstrap";
 import snapshot from "nox-embed:snapshot";
+import initNoxTls, * as noxTls from "nox-embed:tls";
+import extraRoot from "nox-embed:tls-root";
 import { installUnhandledRejectionLog, runNoxWorker } from "./core.js";
+import { tlsBindings } from "./tls/module.js";
 import type { AnonRpcWorkerApi } from "./spec-types.js";
 
 declare const anonRpcWorker: AnonRpcWorkerApi;
@@ -24,5 +28,9 @@ void runNoxWorker(anonRpcWorker, {
     await initNoxWasm();
     return noxWasm as unknown as NoxWasmBindings;
   },
+  loadTls: async () => {
+    await initNoxTls();
+    return tlsBindings(noxTls, extraRoot);
+  },
   connect: (config) => NoxClient.connect(config),
 });