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

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

@@ -1 +1 @@
-0x0a58f9915f686950072a4786249d396ecbf2194a39ac835effe8ea1a7c76f324  anon-rpc-worker.js
+0xd8bef626ec8511d7a468bca5137880680ca2da20d2ea4d9c981a2a3d0c86ba1e  anon-rpc-worker.js

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

@@ -3,29 +3,40 @@
     "arch": "x64",
     "os": "linux"
   },
-  "gitCommit": "ef019a716d7994820d7d63d6de3e60ae8f71e80d",
+  "gitCommit": "fee8d69861a112c65f0cbb0b848a7726ec12f01a",
   "gitTreeClean": true,
   "inputs": {
     "bootstrapKeccak": "0x6567e3ad5e1b1ac81529391c890d2652695d3ec139d56625170384794085fb74",
-    "lockfileSha256": "0398a97b0a813b2a5305a745bac0233cea4bd9c8c4a3b084873d0e091383a825",
+    "lockfileSha256": "0a205a04cd3b6d861b8fedef8b8e6cd6356642e5f2cd9752ce0e2f403fbae426",
     "snapshotBlock": 316207920,
-    "snapshotKeccak": "0xa351960e2c268b9665d1aabec87feaa132d30ade773aef64ef495ec25c94fbb2",
+    "snapshotKeccak": "0x1090f071896b6ef41ddfd40d4ebcd20fae85a66468f82497e19a635488014681",
+    "tlsWasmKeccak": "0x60b29cd4fca7ee2f31fbcff2dca25e64939e4b71a4629ffcfea1b89546f501ce",
+    "tlsWasmSha256": "f74e8cfbed7be33ef1a9158b7b66e454b4ca0849bcb8956487fd13da47e4f4d2",
     "wasmKeccak": "0x6ff418a78fc022d34dff00a867e173269413fb6887c9d6bf8e6505d4dcfffe2d",
     "wasmSha256": "5171416972ea4499fd4b4ea8bcadf002f4c10f10ed42cafb0d5a426121da9c4f"
   },
   "output": {
-    "bytes": 924847,
-    "keccak256": "0x0a58f9915f686950072a4786249d396ecbf2194a39ac835effe8ea1a7c76f324",
-    "sha256": "479f10a34d113a551312f3adf2e6952f3ab8bc7a4ff98c470e13f9543a44131f"
+    "bytes": 1820668,
+    "keccak256": "0xd8bef626ec8511d7a468bca5137880680ca2da20d2ea4d9c981a2a3d0c86ba1e",
+    "sha256": "4b7b69cd6f45c364cd87ff75f5f8cacdebea2cd852d5384c47215bb88d56f35a"
   },
   "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": "v25.5.0",
+    "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.2.0"
+  "version": "0.4.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hisoka-io/anon-rpc-worker",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "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,7 +25,7 @@
     "ethers": "6.16.0",
     "typescript": "5.9.3",
     "vitest": "1.6.1",
-    "@hisoka-io/nox-client": "0.6.0",
+    "@hisoka-io/nox-client": "0.8.0",
     "@hisoka-io/nox-wasm": "0.2.0"
   },
   "publishConfig": {

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. */
@@ -31,6 +50,12 @@ export interface NoxWorkerConfig {
   readonly logLevel: LogLevel;
   /** Per attempt for small and medium reads. */
   readonly attemptTimeoutMs: number;
+  /**
+   * Resendable reads: a second copy goes out on another route when no reply
+   * arrived after this long (raised to the observed p95 reply time); the
+   * first reply wins. 0 turns hedging off.
+   */
+  readonly hedgeAfterMs: number;
   /** Whole call, from acceptance: waiting for ready, sending, attempts. */
   readonly callDeadlineMs: number;
   readonly maxConcurrentCalls: number;
@@ -43,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({
@@ -55,6 +98,7 @@ export const CONFIG_DEFAULTS: NoxWorkerConfig = Object.freeze({
   trust: "auto",
   logLevel: "info",
   attemptTimeoutMs: 12_000,
+  hedgeAfterMs: 3_000,
   callDeadlineMs: 25_000,
   maxConcurrentCalls: 16,
   maxRequestBytes: 1_048_576,
@@ -64,11 +108,23 @@ 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",
+  tlsSpares: 1,
+  tlsSpareTtlMs: 20_000,
+  tlsKeepAliveMs: 30_000,
+  tlsMaxCallsPerSession: 100,
+  tlsOpenTimeoutMs: 5_000,
+  tlsCopyAfterMs: 2_500,
+  tlsGapMs: 800,
+  tlsMaxCopies: 3,
 });
 
 /** Inclusive integer ranges of the numeric fields. */
 export const CONFIG_RANGES = Object.freeze({
   attemptTimeoutMs: [3_000, 60_000],
+  hedgeAfterMs: [0, 60_000],
   callDeadlineMs: [3_000, 120_000],
   maxConcurrentCalls: [1, 64],
   maxRequestBytes: [1_024, 4_194_304],
@@ -76,6 +132,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. */
@@ -83,6 +147,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]);
@@ -158,6 +224,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");
@@ -178,6 +246,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,9 +12,13 @@
  * 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,
+  RESEND_FAST,
   eligiblePinnedMembers,
   pinnedKpsAddresses,
   verifyBootstrap,
@@ -40,7 +44,19 @@ import {
   type BootRetryCode,
   type FailedCode,
 } from "./errors.js";
-import { mapClientError, prepareRequest, sendPrepared, type CallBudget, type NoxHttpPort } from "./fetch-map.js";
+import {
+  mapClientError,
+  prepareRequest,
+  sendPrepared,
+  type CallBudget,
+  type NoxHttpPort,
+  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,
@@ -53,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;
@@ -67,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`. */
@@ -148,6 +166,9 @@ 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;
   private readonly sleep: (ms: number) => Promise<void>;
@@ -220,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);
@@ -239,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");
@@ -262,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);
@@ -291,11 +339,20 @@ class NoxWorker {
       log: this.sdkLogSink(),
       timeoutMs: cfg.attemptTimeoutMs,
       surbFormat: cfg.surbFormat,
+      // Interactive latency: hedge at about p95, resend at once on a lost
+      // reply, transport resends of their own, same-entry resends for a
+      // single bridge (ARCHITECTURE §4.7).
+      resend: { ...RESEND_FAST, hedgeAfterMs: cfg.hedgeAfterMs },
       kps: {
         dial: kpsDial,
         pinned,
         topologySources: cfg.topologySources,
         claimIntervalMs: cfg.claimIntervalMs,
+        // A warm standby entry. Claims share the primary connection: a second
+        // claim connection per entry measured mixed live and doubles per-IP
+        // connections at the relay.
+        claimLane: false,
+        standby: true,
         discovery: this.discoveryOptions(cfg, bootstrap, learned),
         ...(deprioritize.length === 0 ? {} : { deprioritize }),
       },
@@ -340,6 +397,8 @@ class NoxWorker {
     return {
       bootstrap,
       chain: cfg.discovery === "chain",
+      // Wallet calls first: the first registry check waits for the first call (bounded).
+      firstCheckDeferMs: DISCOVERY_FIRST_CHECK_MAX_DEFER_MS,
       onVerified: (state) => this.onVerified(state),
       ...(cfg.gateways === undefined ? {} : { gateways: cfg.gateways }),
       ...(cfg.bridges === undefined ? {} : { bridges: cfg.bridges }),
@@ -447,8 +506,20 @@ class NoxWorker {
     const budget = new CallControl(call.requestInit?.signal, cfg.callDeadlineMs, this.now);
     try {
       const prepared = await prepareRequest(call.url, call.requestInit, cfg, budget.signal);
+      const local = this.answers.lookup(prepared);
+      if (local !== undefined) {
+        this.log.debug("call.done", {
+          seq,
+          jsonrpcMethod: prepared.profile.method ?? null,
+          ms: this.now() - started,
+          outcome: "ok",
+          local: local.kind,
+        });
+        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", {
           seq,
@@ -467,9 +538,30 @@ 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();
     }
   }
 
+  /**
+   * Send a memo call (`eth_chainId`, `net_version`) once more through the
+   * mixnet on a fresh route, in the background; the answer is kept only when
+   * both agree (see `LocalAnswers`).
+   */
+  private verifyAnswer(prepared: PreparedRequest, client: NoxClientPort, cfg: NoxWorkerConfig): void {
+    const budget = new CallControl(undefined, cfg.callDeadlineMs, this.now);
+    sendPrepared(prepared, client, cfg, budget, this.tunnels)
+      .then(
+        (response) => {
+          this.answers.observe(prepared, response);
+        },
+        (error: unknown) => {
+          this.log.debug("local.verify.failed", { code: errorCode(mapClientError(error)) ?? "error" });
+        },
+      )
+      .finally(() => budget.dispose());
+  }
+
   private waitReady(signal: AbortSignal): Promise<NoxClientPort> {
     if (this.client !== undefined) return Promise.resolve(this.client);
     if (this.failed || this.stopped) {

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);