@hisoka-io/anon-rpc-worker 0.3.0 → 0.4.1

package/dist/anon-rpc-worker.js.keccak256

@@ -1 +1 @@
-0x24604525d220bcc7e39f2dbc22966a814600a63ada51baafad5dd0bcc1d28549  anon-rpc-worker.js
+0xd9fa04b080a33062680a27cad828196bfb04615a0ebc76bcbffedb6dcbe838d4  anon-rpc-worker.js

package/dist/anon-rpc-worker.provenance.json

@@ -3,29 +3,40 @@
     "arch": "x64",
     "os": "linux"
   },
-  "gitCommit": "6bddd851c5b1f4e5508f4718e2ea9b4db626b17f",
+  "gitCommit": "66bce4af274b4be457ef11336ba9cb6d9200efd1",
   "gitTreeClean": true,
   "inputs": {
     "bootstrapKeccak": "0x6567e3ad5e1b1ac81529391c890d2652695d3ec139d56625170384794085fb74",
     "lockfileSha256": "0a205a04cd3b6d861b8fedef8b8e6cd6356642e5f2cd9752ce0e2f403fbae426",
     "snapshotBlock": 316207920,
-    "snapshotKeccak": "0xa351960e2c268b9665d1aabec87feaa132d30ade773aef64ef495ec25c94fbb2",
-    "wasmKeccak": "0x6ff418a78fc022d34dff00a867e173269413fb6887c9d6bf8e6505d4dcfffe2d",
-    "wasmSha256": "5171416972ea4499fd4b4ea8bcadf002f4c10f10ed42cafb0d5a426121da9c4f"
+    "snapshotKeccak": "0x1090f071896b6ef41ddfd40d4ebcd20fae85a66468f82497e19a635488014681",
+    "tlsWasmKeccak": "0x60b29cd4fca7ee2f31fbcff2dca25e64939e4b71a4629ffcfea1b89546f501ce",
+    "tlsWasmSha256": "f74e8cfbed7be33ef1a9158b7b66e454b4ca0849bcb8956487fd13da47e4f4d2",
+    "wasmKeccak": "0x91060e59264ba44c3f16181caff1adcf16193a1e57d6ba4dd3531b192ac42de4",
+    "wasmSha256": "6db306a34ef50e9198f4ad6f31c6ffd9feafe459c24b8a29895824c7138241c8"
   },
   "output": {
-    "bytes": 961799,
-    "keccak256": "0x24604525d220bcc7e39f2dbc22966a814600a63ada51baafad5dd0bcc1d28549",
-    "sha256": "0458b19258dffcfb9ce23d584096f3df06532080390d34ee71b201b6b78dbbac"
+    "bytes": 1831246,
+    "keccak256": "0xd9fa04b080a33062680a27cad828196bfb04615a0ebc76bcbffedb6dcbe838d4",
+    "sha256": "9544fb10390eb135d4f6b9a32de674ea859e4977514afed4772cb4642d62ed19"
   },
   "package": "@hisoka-io/anon-rpc-worker",
+  "tls": {
+    "extraRoots": 0,
+    "webpkiRoots": "1.0.9",
+    "webpkiRootsReleased": "2026-07-18"
+  },
   "toolchain": {
+    "clang": "19.1.7",
     "esbuild": "0.27.3",
     "node": "v22.23.3",
     "pins": {
       "BINARYEN_SHA256_AARCH64": "ad560204426015a815faa45693c83bef7d58677d38a39422c272a30ba4b6da2a",
       "BINARYEN_SHA256_X86_64": "3dc677006555b355ea2da5e82602065a161d5e83eaefd3f759afa00b96e83212",
       "BINARYEN_VERSION": "117",
+      "CLANG_PACKAGE_VERSION": "1:19.1.7-3~deb12u1",
+      "CLANG_VERSION": "19.1.7",
+      "DEBIAN_SNAPSHOT": "20261001T000000Z",
       "NODE_IMAGE": "docker.io/library/node:22.23.3-bookworm-slim@sha256:43ac6c60b8f89723f746e8a92ce91abd5017e627ce1ddfe4238355d3a30b772c",
       "NODE_VERSION": "22.23.3",
       "RUST_IMAGE": "docker.io/library/rust:1.95.0-slim-bookworm@sha256:d7482085ff5b415f84dba5647ae71606650bdef00db7aeb69f4b3d170c3e4082",
@@ -44,5 +55,5 @@
     "wasmPack": "0.13.1",
     "wasmPinsChecked": true
   },
-  "version": "0.3.0"
+  "version": "0.4.1"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hisoka-io/anon-rpc-worker",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Nox mixnet worker for the anon-rpc standard, built as one reproducible classic-script bundle with a pinned NoxRegistry snapshot",
   "license": "Apache-2.0",
   "repository": {
@@ -25,8 +25,8 @@
     "ethers": "6.16.0",
     "typescript": "5.9.3",
     "vitest": "1.6.1",
-    "@hisoka-io/nox-client": "0.7.0",
-    "@hisoka-io/nox-wasm": "0.2.0"
+    "@hisoka-io/nox-client": "0.9.0",
+    "@hisoka-io/nox-wasm": "0.3.0"
   },
   "publishConfig": {
     "access": "public"

package/snapshot/capabilities.json

@@ -3,21 +3,24 @@
   "members": {
     "0x03a42846c18b99c453a49d7fce69f336f865c48b": [
       "paid_v2",
-      "surb_v2"
+      "surb_v2",
+      "tunnel_v1"
     ],
     "0x074a13b271b73eb5c0c44e2037d035e7eef4a462": [
       "surb_v2"
     ],
     "0x1efa385556a6e8643df0033048ba1dd67ec43f93": [
       "paid_v2",
-      "surb_v2"
+      "surb_v2",
+      "tunnel_v1"
     ],
     "0x3e98ee4572741fd932e031ac60e79f7c012758be": [
       "surb_v2"
     ],
     "0x6774ca4baf6fff84f02898a3dee4299ed1f5ab4e": [
       "paid_v2",
-      "surb_v2"
+      "surb_v2",
+      "tunnel_v1"
     ],
     "0x74486dc1ac551e5cd3f4eef80727cc9d50d3abe9": [
       "surb_v2"
@@ -35,5 +38,5 @@
       "surb_v2"
     ]
   },
-  "source": "Capability hints reviewed for the release snapshot. Taken from the liveness section of the public seed topology (https://api.hisoka.io/seed/topology, fleet build 0.4.0-rc.4+b30e46d3ab9d2d707de37011a10639a4c15232ce), re-read at block 315566145 on 2026-10-04 with identical hints for all 10 members. Hints are untrusted by design and only choose between reply-block formats."
+  "source": "Capability hints reviewed for the release snapshot. Taken from the liveness section of the public seed topology (https://api.hisoka.io/seed/topology, fleet build 0.4.0-rc.9+3ef92f06f8265700b7b07e9e21e8f6dff0f47a09), read at block 317672566 on 2026-10-10 with all 10 members online; the three exits advertise tunnel_v1. Hints are untrusted by design: they choose between reply-block formats and pick tunnel exits (tunnel_v1), where a false hint costs one open timeout and plaintext stays out of reach."
 }

package/snapshot/nox-snapshot.json

@@ -9,7 +9,8 @@
       "address": "0x03a42846c18b99c453a49d7fce69f336f865c48b",
       "capabilities": [
         "paid_v2",
-        "surb_v2"
+        "surb_v2",
+        "tunnel_v1"
       ],
       "frozen": false,
       "ingressUrl": "https://nox-7.hisoka.io",
@@ -40,7 +41,8 @@
       "address": "0x1efa385556a6e8643df0033048ba1dd67ec43f93",
       "capabilities": [
         "paid_v2",
-        "surb_v2"
+        "surb_v2",
+        "tunnel_v1"
       ],
       "frozen": false,
       "ingressUrl": "https://nox-10.hisoka.io",
@@ -71,7 +73,8 @@
       "address": "0x6774ca4baf6fff84f02898a3dee4299ed1f5ab4e",
       "capabilities": [
         "paid_v2",
-        "surb_v2"
+        "surb_v2",
+        "tunnel_v1"
       ],
       "frozen": false,
       "ingressUrl": "https://nox-6.hisoka.io",

package/snapshot/nox-snapshot.json.keccak256

@@ -1 +1 @@
-0xa351960e2c268b9665d1aabec87feaa132d30ade773aef64ef495ec25c94fbb2  nox-snapshot.json
+0x1090f071896b6ef41ddfd40d4ebcd20fae85a66468f82497e19a635488014681  nox-snapshot.json

package/src/config.ts

@@ -15,6 +15,25 @@ export type SurbFormatSetting = "auto" | "v1" | "v2";
 /** `"chain"`: registry reads through the mixnet (S1). `"snapshot"`: the pinned snapshot is the only membership source. */
 export type DiscoverySetting = "chain" | "snapshot";
 
+/**
+ * End-to-end TLS (README "End-to-end TLS"):
+ * - `"required"`: https calls to a host name on port 443 go through TLS
+ *   tunnels, so exits relay ciphertext only; every other call is refused and
+ *   nothing ever falls back to the exit's `HttpRequest` path.
+ * - `"preferred"`: tunnels where a tunnel exit is known and the URL allows
+ *   one, `HttpRequest` otherwise. An operator who withholds `tunnel_v1` gets
+ *   plaintext, so only `"required"` holds against the operator.
+ * - `"off"`: every call is an exit `HttpRequest` (worker 0.3 behaviour).
+ */
+export type TlsSetting = "required" | "preferred" | "off";
+
+/**
+ * `"per-call"`: one TLS session per call (with `tlsSpares` handshaken spares
+ * per recent host). `"keep-alive"`: calls to one host share a session on one
+ * exit, which links them at the exit and at the provider.
+ */
+export type TlsSessionSetting = "per-call" | "keep-alive";
+
 export interface NoxWorkerConfig {
   readonly v: 1;
   /** KPS addresses (`<ip>:<port>:<certhash>`) tried first, in place of the bundle's default anchors. */
@@ -49,6 +68,24 @@ export interface NoxWorkerConfig {
   readonly topologySources: number;
   /** One echo through a full route before `signalReady`. */
   readonly warmup: boolean;
+  readonly tls: TlsSetting;
+  readonly tlsSession: TlsSessionSetting;
+  /** Per-call mode: handshaken, unused sessions kept per recently used host. */
+  readonly tlsSpares: number;
+  /** An unused spare is torn down after this long. */
+  readonly tlsSpareTtlMs: number;
+  /** Keep-alive mode: a session serves calls for this long after it opened. */
+  readonly tlsKeepAliveMs: number;
+  /** Keep-alive mode: calls per session. */
+  readonly tlsMaxCallsPerSession: number;
+  /** An exit that does not answer a tunnel open in this long is skipped for a while. */
+  readonly tlsOpenTimeoutMs: number;
+  /** Another copy of the current exchange when nothing arrived for this long (raised to the observed p95). */
+  readonly tlsCopyAfterMs: number;
+  /** Another copy when a gap in the reply stream stays open this long. */
+  readonly tlsGapMs: number;
+  /** Copies per exchange sent for silence or a gap. */
+  readonly tlsMaxCopies: number;
 }
 
 export const CONFIG_DEFAULTS: NoxWorkerConfig = Object.freeze({
@@ -71,6 +108,21 @@ export const CONFIG_DEFAULTS: NoxWorkerConfig = Object.freeze({
   bootRetryMaxMs: 60_000,
   topologySources: 2,
   warmup: false,
+  // Founder decisions D1/D2 (E2E TLS design §8): the most private settings until decided.
+  tls: "required",
+  tlsSession: "per-call",
+  // Spare policy measured from India on 2026-10-15: the upstream RPC hosts close an idle TLS connection 15.0 s
+  // after the handshake, and spares used 14.2 s or more after their handshake had been closed (one wasted exchange,
+  // then a retry on a new session). A 12 s TTL kept every spare live (0 retries in 70 calls); a second spare per
+  // host raised spare use at a 1 s gap from 16/30 to 23/30 calls.
+  tlsSpares: 2,
+  tlsSpareTtlMs: 12_000,
+  tlsKeepAliveMs: 30_000,
+  tlsMaxCallsPerSession: 100,
+  tlsOpenTimeoutMs: 5_000,
+  tlsCopyAfterMs: 2_500,
+  tlsGapMs: 800,
+  tlsMaxCopies: 3,
 });
 
 /** Inclusive integer ranges of the numeric fields. */
@@ -84,6 +136,14 @@ export const CONFIG_RANGES = Object.freeze({
   claimIntervalMs: [50, 2_000],
   bootRetryMaxMs: [5_000, 300_000],
   topologySources: [1, 4],
+  tlsSpares: [0, 4],
+  tlsSpareTtlMs: [1_000, 50_000],
+  tlsKeepAliveMs: [1_000, 50_000],
+  tlsMaxCallsPerSession: [1, 1_000],
+  tlsOpenTimeoutMs: [1_000, 30_000],
+  tlsCopyAfterMs: [500, 30_000],
+  tlsGapMs: [100, 10_000],
+  tlsMaxCopies: [1, 5],
 } as const satisfies Record<string, readonly [number, number]>);
 
 /** `gateways` and `bridges` list length bounds. */
@@ -91,6 +151,8 @@ export const GATEWAYS_RANGE = Object.freeze([1, 16] as const);
 
 const SURB_FORMATS: readonly SurbFormatSetting[] = ["auto", "v1", "v2"];
 const DISCOVERY_SETTINGS: readonly DiscoverySetting[] = ["chain", "snapshot"];
+const TLS_SETTINGS: readonly TlsSetting[] = ["required", "preferred", "off"];
+const TLS_SESSION_SETTINGS: readonly TlsSessionSetting[] = ["per-call", "keep-alive"];
 /** Names reserved for later stages (PROPOSAL §2.5): refused so they are never reused differently. */
 const RESERVED_KEYS = new Set(["checkpoint"]);
 const KNOWN_KEYS = new Set<string>([...Object.keys(CONFIG_DEFAULTS), ...RESERVED_KEYS]);
@@ -166,6 +228,8 @@ export function parseConfig(raw: unknown): NoxWorkerConfig {
     }
     out.discovery = discovery as DiscoverySetting;
   }
+  out.tls = pickOne(raw, "tls", TLS_SETTINGS, out.tls);
+  out.tlsSession = pickOne(raw, "tlsSession", TLS_SESSION_SETTINGS, out.tlsSession);
   const fail = (detail: string): ConfigError => new ConfigError(`config.${detail}`);
   if (raw["gateways"] !== undefined && raw["bridges"] !== undefined) {
     throw new ConfigError("config.gateways and config.bridges exclude each other: with bridges the worker dials only bridges");
@@ -186,6 +250,15 @@ export function parseConfig(raw: unknown): NoxWorkerConfig {
   return Object.freeze(out);
 }
 
+function pickOne<T extends string>(raw: Record<string, unknown>, field: string, allowed: readonly T[], fallback: T): T {
+  const value = raw[field];
+  if (value === undefined) return fallback;
+  if (typeof value !== "string" || !(allowed as readonly string[]).includes(value)) {
+    throw new ConfigError(`config.${field} must be one of ${allowed.join(", ")}`);
+  }
+  return value as T;
+}
+
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
   const proto = Object.getPrototypeOf(value) as unknown;

package/src/core.ts

@@ -12,7 +12,9 @@
  * call `signalFailed`; transient ones retry forever with back-off while
  * `ready` stays pending. After ready the SDK checks NoxRegistry through the
  * mixnet in the background (S1); each verified check refreshes the
- * learned-anchor cache.
+ * learned-anchor cache. With `tls` other than `"off"` the embedded TLS module
+ * is compiled at boot too, off the first call's path, and https calls go
+ * through TLS tunnels (src/tls/).
  */
 import {
   DISCOVERY_FIRST_CHECK_MAX_DEFER_MS,
@@ -51,6 +53,10 @@ import {
   type PreparedRequest,
 } from "./fetch-map.js";
 import { LocalAnswers } from "./local-answers.js";
+import type { NoxTlsBindings } from "./tls/module.js";
+import { TlsPool } from "./tls/pool.js";
+import { TlsTransport } from "./tls/transport.js";
+import type { TunnelPort } from "./tls/tunnel.js";
 import { createLogger, describeError, errorCode, type LogLevel, type WorkerLogger } from "./log.js";
 import {
   LearnedCacheWriter,
@@ -63,7 +69,7 @@ import {
 } from "./storage.js";
 
 /** The slice of `NoxClient` the worker uses. */
-export interface NoxClientPort extends NoxHttpPort {
+export interface NoxClientPort extends NoxHttpPort, TunnelPort {
   readonly nodes: readonly { readonly id: string }[];
   sendEcho(data: Uint8Array): Promise<Uint8Array>;
   disconnect(): void;
@@ -77,6 +83,8 @@ export interface WorkerDeps {
   readonly bootstrap: unknown;
   /** Initialise the embedded WASM and return its bindings; throws when WebAssembly is blocked. */
   loadWasm(): Promise<NoxWasmBindings>;
+  /** Initialise the embedded TLS module (only when `tls` is not `"off"`). */
+  loadTls(): Promise<NoxTlsBindings>;
   /** `NoxClient.connect`. */
   connect(config: NoxClientConfig): Promise<NoxClientPort>;
   /** Milliseconds since the epoch. Default `Date.now`. */
@@ -158,6 +166,8 @@ class NoxWorker {
   private cacheTimer: ReturnType<typeof setInterval> | undefined;
   private learnedWriter: LearnedCacheWriter | undefined;
   private callSeq = 0;
+  private tlsPool: TlsPool | undefined;
+  private tunnels: TlsTransport | undefined;
   private readonly answers = new LocalAnswers();
   private readonly now: () => number;
   private readonly random: () => number;
@@ -231,6 +241,21 @@ class NoxWorker {
     }
     this.log.info("boot.wasm");
 
+    let tls: NoxTlsBindings | undefined;
+    if (cfg.tls !== "off") {
+      try {
+        tls = await this.deps.loadTls();
+      } catch (error) {
+        this.fail(
+          FAILED_CODES.wasmBlocked,
+          `The TLS module could not be compiled or instantiated (${describeError(error)}); ` +
+            "the embedder's Content-Security-Policy must allow 'wasm-unsafe-eval'",
+        );
+        return;
+      }
+      this.log.info("boot.tls", { mode: cfg.tls, session: cfg.tlsSession, roots: tls.info.webpkiRoots });
+    }
+
     void this.acceptLoop(cfg);
 
     const snapshotId = snapshotIdentity(pinned);
@@ -250,6 +275,15 @@ class NoxWorker {
       return;
     }
     this.client = client;
+    if (tls !== undefined) {
+      this.tlsPool = new TlsPool(client, tls, cfg, {
+        now: this.now,
+        random: this.random,
+        randomBytes: (length) => crypto.getRandomValues(new Uint8Array(length)),
+        log: this.log,
+      });
+      this.tunnels = new TlsTransport(this.tlsPool, tls, cfg, this.log, this.now);
+    }
     this.startRemovalCache(pinned, snapshotId, stored);
     this.api.signalReady();
     this.log.info("ready");
@@ -273,6 +307,9 @@ class NoxWorker {
   private shutdown(reason: NoxWorkerError): void {
     if (this.cacheTimer !== undefined) clearInterval(this.cacheTimer);
     this.cacheTimer = undefined;
+    this.tlsPool?.close();
+    this.tlsPool = undefined;
+    this.tunnels = undefined;
     this.client?.disconnect();
     this.client = undefined;
     for (const waiter of this.readyWaiters) waiter.reject(reason);
@@ -481,7 +518,7 @@ class NoxWorker {
         return local.response;
       }
       const client = await this.waitReady(budget.signal);
-      const response = await sendPrepared(prepared, client, cfg, budget);
+      const response = await sendPrepared(prepared, client, cfg, budget, this.tunnels);
       if (this.answers.observe(prepared, response) === "verify") this.verifyAnswer(prepared, client, cfg);
       if (this.log.enabled("debug")) {
         this.log.debug("call.done", {
@@ -501,6 +538,8 @@ class NoxWorker {
       throw final;
     } finally {
       budget.dispose();
+      // Spares open only once a wallet call settled (background work never delays the first call).
+      this.tlsPool?.enableBackground();
     }
   }
 
@@ -511,7 +550,7 @@ class NoxWorker {
    */
   private verifyAnswer(prepared: PreparedRequest, client: NoxClientPort, cfg: NoxWorkerConfig): void {
     const budget = new CallControl(undefined, cfg.callDeadlineMs, this.now);
-    sendPrepared(prepared, client, cfg, budget)
+    sendPrepared(prepared, client, cfg, budget, this.tunnels)
       .then(
         (response) => {
           this.answers.observe(prepared, response);

package/src/embed-modules.d.ts

@@ -13,3 +13,19 @@ declare module "nox-embed:bootstrap" {
   const bootstrap: unknown;
   export default bootstrap;
 }
+
+declare module "nox-embed:tls" {
+  /** Initialise the embedded nox-tls module (no fetch; the bytes are in the bundle). */
+  export default function init(): Promise<void>;
+  export const TlsClientConfig: import("./tls/module.js").NoxTlsExports["TlsClientConfig"];
+  export const TlsClientSession: import("./tls/module.js").NoxTlsExports["TlsClientSession"];
+  export const HttpResponseParser: import("./tls/module.js").NoxTlsExports["HttpResponseParser"];
+  export const encodeHttpRequest: import("./tls/module.js").NoxTlsExports["encodeHttpRequest"];
+  export const buildInfo: import("./tls/module.js").NoxTlsExports["buildInfo"];
+}
+
+declare module "nox-embed:tls-root" {
+  /** A test bed's CA certificate (DER), trusted next to the compiled-in roots; `null` in every release build. */
+  const extraRootDer: Uint8Array | null;
+  export default extraRootDer;
+}

package/src/errors.ts

@@ -54,8 +54,14 @@ export const CALL_CODES = Object.freeze({
   tooLarge: "too-large",
   /** Not an absolute http(s) URL, or an invalid method, header or redirect mode. */
   unsupported: "unsupported",
-  /** The exit's reply could not be decoded or is not a valid HTTP response. */
+  /**
+   * The exit's reply could not be decoded or is not a valid HTTP response; or
+   * TLS through a tunnel failed its own checks (a refused record, an alert, a
+   * failed record authentication, a body cut short).
+   */
   protocolError: "protocol-error",
+  /** The tunnel exit's policy refuses the destination (port, host name or a blocked address). */
+  permissionDenied: "permission-denied",
   /** An unexpected exception (a bug). */
   internalError: "internal-error",
 } as const);

package/src/fetch-map.ts

@@ -27,6 +27,13 @@ export interface NoxHttpPort {
   ): Promise<Uint8Array>;
 }
 
+/** TLS tunnels for fetch hops (src/tls/transport.ts). */
+export interface TunnelHop {
+  /** `"tunnel"` or `"http"` for this hop; throws the call's rejection when the hop may not leave. */
+  route(request: PreparedRequest, hop: number, startedOnTunnel: boolean): "tunnel" | "http";
+  exchange(request: PreparedRequest, budget: CallBudget): Promise<DecodedHttpResponse>;
+}
+
 /** Limits from the worker config. */
 export interface FetchSettings {
   readonly attemptTimeoutMs: number;
@@ -185,17 +192,27 @@ export interface CallBudget {
  * need time and writes are never resent (ARCHITECTURE §4.7). The SDK still
  * resends any request whose packet was certainly never sent (a KPS dial or
  * stream-open failure) through another entry.
+ *
+ * With `tunnels`, each hop first asks it for its transport: a hop that goes
+ * through a TLS tunnel is exchanged there, and once one hop did, every later
+ * hop must too.
  */
 export async function sendPrepared(
   request: PreparedRequest,
   port: NoxHttpPort,
   settings: FetchSettings,
   budget: CallBudget,
+  tunnels?: TunnelHop,
 ): Promise<AnonFetchResponse> {
   if (budget.remainingMs() <= 0) throw callError(CALL_CODES.timeout, "The call deadline passed before sending");
   let current = request;
+  let onTunnel = false;
   for (let hop = 0; ; hop++) {
-    const reply = await exchange(current, port, settings, budget);
+    const via = tunnels?.route(current, hop, onTunnel) ?? "http";
+    const reply = tunnels !== undefined && via === "tunnel"
+      ? await tunnels.exchange(current, budget)
+      : await exchange(current, port, settings, budget);
+    if (via === "tunnel") onTunnel = true;
     checkStatus(reply);
     if (!REDIRECT_STATUSES.has(reply.status) || current.redirect === "manual") {
       return finishResponse(reply, current, settings);

package/src/tls/channel.ts

@@ -0,0 +1,183 @@
+/**
+ * A TLS session to one host over one tunnel: the handshake exchange, then
+ * HTTP/1.1 requests. Completeness of a response comes from HTTP framing or,
+ * for a close-delimited body, from TLS close_notify; an exit that ends the
+ * stream early produces a truncation error, never a short response.
+ */
+import type { TopologyNode } from "@hisoka-io/nox-client";
+import type { HttpParserLike, HttpReplyHead, NoxTlsBindings, TlsSessionLike } from "./module.js";
+import { Tunnel, TunnelProtocolError, type CopyPolicy, type TunnelDeps, type TunnelPort } from "./tunnel.js";
+
+/** Reply blocks for the handshake exchange: one carries the server flight, the other is the exit's reserve. */
+export const HANDSHAKE_SURBS = 2;
+/** The TLS port every tunnel uses. */
+export const TLS_PORT = 443;
+
+export interface ExchangeTiming {
+  readonly deadlineAt: number;
+  readonly signal?: AbortSignal;
+  readonly background: boolean;
+}
+
+export interface RequestSpec extends ExchangeTiming {
+  /** The encoded HTTP/1.1 request. */
+  readonly http: Uint8Array;
+  readonly headRequest: boolean;
+  readonly maxHeadBytes: number;
+  readonly maxBodyBytes: number;
+  /** Reply blocks for the exchange that carries the request. */
+  readonly surbs: number;
+}
+
+export class TlsChannel {
+  readonly tunnel: Tunnel;
+  readonly openedAt: number;
+  /** Requests sent on this session. */
+  calls = 0;
+  /** Milliseconds spent in the TLS module processing the server's handshake flight. */
+  handshakeCpuMs = 0;
+  /** False once a response asked to close or the stream ended. */
+  private keepAlive = true;
+  private parser: HttpParserLike | undefined;
+  private parserDone = false;
+  private freed = false;
+  private readonly tls: TlsSessionLike;
+
+  constructor(
+    port: TunnelPort,
+    exit: TopologyNode,
+    readonly host: string,
+    policy: CopyPolicy,
+    deps: TunnelDeps,
+    private readonly bindings: NoxTlsBindings,
+  ) {
+    this.tls = bindings.newSession(host);
+    this.openedAt = deps.now();
+    this.tunnel = new Tunnel(port, exit, host, TLS_PORT, policy, deps, (bytes) => this.onBytes(bytes));
+  }
+
+  get exit(): TopologyNode {
+    return this.tunnel.exit;
+  }
+
+  /** TLS version negotiated (`TLSv1_3`, `TLSv1_2`). */
+  get protocol(): string {
+    return this.tls.protocol();
+  }
+
+  /** The session can carry another request. */
+  get reusable(): boolean {
+    return !this.freed && this.keepAlive && !this.tunnel.eof && !this.tls.isClosed();
+  }
+
+  /**
+   * Seq 0: open the tunnel with the ClientHello and process the server's
+   * flight. Afterwards the client's next flight (the TLS 1.3 Finished) waits
+   * in the session until the first request, which travels with it.
+   */
+  async handshake(timing: ExchangeTiming & { readonly openTimeoutMs: number }): Promise<void> {
+    const hello = this.tls.takeOutgoing();
+    const outcome = await this.tunnel.exchange({
+      data: hello,
+      surbs: HANDSHAKE_SURBS,
+      deadlineAt: timing.deadlineAt,
+      background: timing.background,
+      openTimeoutMs: timing.openTimeoutMs,
+      ...(timing.signal === undefined ? {} : { signal: timing.signal }),
+      satisfied: () => this.tls.wantsWrite() || !this.tls.isHandshaking(),
+    });
+    if (outcome === "eof") throw new TunnelProtocolError("The upstream closed the connection during the TLS handshake");
+  }
+
+  /** One HTTP request and its complete response. */
+  async request(spec: RequestSpec): Promise<HttpReplyHead> {
+    this.calls += 1;
+    const parser = this.bindings.newParser(spec.headRequest, spec.maxHeadBytes, spec.maxBodyBytes);
+    this.parser = parser;
+    this.parserDone = false;
+    try {
+      this.tls.writePlaintext(spec.http);
+      for (;;) {
+        const data = this.tls.takeOutgoing();
+        const outcome = await this.tunnel.exchange({
+          data,
+          surbs: spec.surbs,
+          deadlineAt: spec.deadlineAt,
+          background: spec.background,
+          ...(spec.signal === undefined ? {} : { signal: spec.signal }),
+          satisfied: () => this.parserDone || this.tls.wantsWrite(),
+        });
+        if (outcome === "eof") {
+          this.keepAlive = false;
+          this.tls.pushTransportEof();
+          this.feedParser(this.tls.takePlaintext());
+          if (!this.parserDone) {
+            parser.finishOnClose(this.tls.closeNotifyReceived());
+            this.parserDone = true;
+          }
+        }
+        if (this.parserDone) break;
+      }
+      const response = parser.response();
+      if (response === null) throw new TunnelProtocolError("The HTTP parser finished without a response");
+      if (!response.keepAlive) this.keepAlive = false;
+      return response;
+    } finally {
+      this.parser = undefined;
+      parser.free();
+    }
+  }
+
+  /**
+   * Close the tunnel: close_notify when the TLS session can still send one,
+   * and the acknowledgement of every byte received, so the exit drops the
+   * session at once. Nothing waits for it.
+   */
+  teardown(deadlineAt: number): Promise<void> {
+    if (this.freed) return Promise.resolve();
+    this.keepAlive = false;
+    const data = this.tunnel.eof ? new Uint8Array(0) : this.closeNotify();
+    this.free();
+    return this.tunnel.teardown(data, deadlineAt);
+  }
+
+  /** The close_notify record, or nothing when the session can no longer send one. */
+  private closeNotify(): Uint8Array {
+    try {
+      this.tls.close();
+      return this.tls.takeOutgoing();
+    } catch {
+      return new Uint8Array(0);
+    }
+  }
+
+  /** Release the TLS session's WebAssembly memory. */
+  free(): void {
+    if (this.freed) return;
+    this.freed = true;
+    this.tls.free();
+  }
+
+  private onBytes(bytes: Uint8Array): void {
+    if (this.tls.isHandshaking()) {
+      const started = performance.now();
+      this.tls.pushIncoming(bytes);
+      this.handshakeCpuMs += performance.now() - started;
+    } else {
+      this.tls.pushIncoming(bytes);
+    }
+    this.feedParser(this.tls.takePlaintext());
+    if (this.tls.closeNotifyReceived() && this.parser !== undefined && !this.parserDone) {
+      this.parser.finishOnClose(true);
+      this.parserDone = true;
+    }
+  }
+
+  private feedParser(plaintext: Uint8Array): void {
+    if (plaintext.length === 0) return;
+    if (this.parser === undefined || this.parserDone) {
+      throw new TunnelProtocolError(`The upstream sent ${plaintext.length} bytes with no request outstanding`);
+    }
+    this.parserDone = this.parser.push(plaintext);
+  }
+}