@rstreamlabs/tunnels 3.8.3 → 3.10.1

package/dist/index.js

@@ -5,6 +5,14 @@ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __esm = (fn, res, err) => function __init() {
+  if (err) throw err[0];
+  try {
+    return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+  } catch (e) {
+    throw err = [e], e;
+  }
+};
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
@@ -27,6 +35,116 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
+// src/node-engine-http.ts
+var node_engine_http_exports = {};
+__export(node_engine_http_exports, {
+  NodeEngineHTTP: () => NodeEngineHTTP
+});
+var import_node_https, import_node_https2, responseHeaders, responseBody, NodeEngineHTTP;
+var init_node_engine_http = __esm({
+  "src/node-engine-http.ts"() {
+    "use strict";
+    import_node_https = require("https");
+    import_node_https2 = require("https");
+    responseHeaders = (response) => {
+      const headers = new Headers();
+      for (const [name, value] of Object.entries(response.headers)) {
+        if (Array.isArray(value))
+          for (const item of value) headers.append(name, item);
+        else if (value !== void 0) headers.set(name, value);
+      }
+      return headers;
+    };
+    responseBody = (response) => {
+      const state = { ended: false };
+      return new ReadableStream({
+        start(controller) {
+          response.on("data", (chunk) => {
+            controller.enqueue(new Uint8Array(chunk));
+            response.pause();
+          });
+          response.once("end", () => {
+            if (!state.ended) {
+              state.ended = true;
+              controller.close();
+            }
+          });
+          response.once("error", (error) => {
+            if (!state.ended) {
+              state.ended = true;
+              controller.error(error);
+            }
+          });
+          response.once("aborted", () => {
+            if (!state.ended) {
+              state.ended = true;
+              controller.error(new Error("Engine response was interrupted."));
+            }
+          });
+        },
+        pull() {
+          response.resume();
+        },
+        cancel() {
+          state.ended = true;
+          response.destroy();
+        }
+      });
+    };
+    NodeEngineHTTP = class {
+      constructor(tls) {
+        this.tls = tls;
+      }
+      tls;
+      agent = new import_node_https.Agent({
+        keepAlive: true,
+        maxSockets: 16,
+        maxFreeSockets: 4,
+        maxTotalSockets: 16
+      });
+      fetch = async (input, init) => {
+        const incoming = new Request(input, init);
+        const url = new URL(incoming.url);
+        if (url.protocol !== "https:" || url.username || url.password)
+          throw new Error(
+            "Engine HTTP requests require HTTPS without URL credentials."
+          );
+        const body = incoming.body ? new Uint8Array(await incoming.arrayBuffer()) : void 0;
+        incoming.signal.throwIfAborted();
+        return new Promise((resolve, reject) => {
+          const outgoing = (0, import_node_https2.request)(
+            url,
+            {
+              ...this.tls,
+              servername: url.hostname,
+              agent: this.agent,
+              method: incoming.method,
+              headers: Object.fromEntries(incoming.headers),
+              signal: incoming.signal
+            },
+            (response) => {
+              const status = response.statusCode ?? 502;
+              const empty = incoming.method === "HEAD" || [204, 205, 304].includes(status);
+              if (empty) response.resume();
+              resolve(
+                new Response(empty ? null : responseBody(response), {
+                  status,
+                  headers: responseHeaders(response)
+                })
+              );
+            }
+          );
+          outgoing.once("error", reject);
+          outgoing.end(body);
+        });
+      };
+      close() {
+        this.agent.destroy();
+      }
+    };
+  }
+});
+
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
@@ -84,7 +202,9 @@ __export(index_exports, {
   resolveTunnelsCredentials: () => resolveTunnelsCredentials,
   resolveTunnelsEngine: () => resolveTunnelsEngine,
   resolveTunnelsRegion: () => resolveTunnelsRegion,
+  resolveWebTTYBrowserEndpoint: () => resolveWebTTYBrowserEndpoint,
   resolveWebTTYControlRequestParamsSchema: () => resolveWebTTYControlRequestParamsSchema,
+  resolveWebTTYServerTransport: () => resolveWebTTYServerTransport,
   signWebhookPayload: () => signWebhookPayload,
   streamEndpointSchema: () => streamEndpointSchema,
   streamEntrySchema: () => streamEntrySchema,
@@ -94,6 +214,7 @@ __export(index_exports, {
   streamWebTTYMetadataSchema: () => streamWebTTYMetadataSchema,
   tunnelFilterSchema: () => tunnelFilterSchema,
   turnCredentialModeSchema: () => turnCredentialModeSchema,
+  validateTURNCredentialsRequest: () => validateTURNCredentialsRequest,
   webTTYCapabilitiesSchema: () => webTTYCapabilitiesSchema,
   webTTYContextMetadataSchema: () => webTTYContextMetadataSchema,
   webTTYControlRequestSchema: () => webTTYControlRequestSchema,
@@ -114,6 +235,7 @@ __export(index_exports, {
   webTTYTransportSchema: () => webTTYTransportSchema,
   webhookEventsSchema: () => webhookEventsSchema,
   webttyServerSchema: () => webttyServerSchema,
+  webttyTransportSchema: () => webttyTransportSchema,
   wsEventsSchema: () => wsEventsSchema
 });
 module.exports = __toCommonJS(index_exports);
@@ -1298,6 +1420,19 @@ var watchParamsSchema = z7.object({
   tunnels: tunnelFilterSchema.optional()
 });
 var enginePermissions = {
+  "turn.credentials.create": {
+    name: "TURN Credentials: Create",
+    description: "Issue short-lived TURN credentials through either the Control plane or Engine API.",
+    rules: [
+      {
+        resource: [
+          "api.turn-server.credentials",
+          "engine.turn-server.credentials"
+        ],
+        action: "create"
+      }
+    ]
+  },
   "tunnels.resources.read-only": {
     name: "Discovery: Read-Only",
     description: "Read active clients, active tunnels, and live state events.",
@@ -1377,13 +1512,13 @@ var engineOpenApiDocument = {
       }
     }
   ],
-  security: [
-    {
-      bearerAuth: []
-    }
-  ],
+  security: [{ bearerAuth: [] }, { mutualTLS: [] }],
   components: {
     securitySchemes: {
+      mutualTLS: {
+        type: "mutualTLS",
+        description: "EE project API only, on the dedicated authority returned by anonymous HTTPS discovery. Present one registered client certificate without a bearer or query token. Ordinary browser-facing hosts never request a client certificate."
+      },
       bearerAuth: {
         type: "http",
         scheme: "bearer",
@@ -1451,6 +1586,64 @@ var engineOpenApiDocument = {
       Forbidden: errorResponse("The token is not authorized.")
     },
     schemas: {
+      EngineDiscovery: {
+        type: "object",
+        required: ["version", "projectEndpoint", "mtlsApiUrl", "capabilities"],
+        properties: {
+          version: { type: "integer", const: 1 },
+          projectEndpoint: { type: "string" },
+          mtlsApiUrl: {
+            type: "string",
+            format: "uri",
+            example: "https://project.mtls.engine.example/api"
+          },
+          capabilities: {
+            type: "array",
+            items: { type: "string" },
+            examples: [["engine-api-mtls", "turn-credentials-v2"]]
+          }
+        }
+      },
+      CreateTURNCredentials: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          ttlSeconds: {
+            type: "integer",
+            minimum: 1,
+            maximum: 3600,
+            default: 600
+          }
+        }
+      },
+      TURNCredentials: {
+        type: "object",
+        required: ["username", "credential", "urls", "ttl"],
+        properties: {
+          username: {
+            type: "string",
+            maxLength: 512,
+            description: "Opaque short-lived v2 issued identity. Do not parse in clients."
+          },
+          credential: {
+            type: "string",
+            maxLength: 1024,
+            description: "Short-lived TURN password."
+          },
+          urls: {
+            type: "array",
+            minItems: 1,
+            maxItems: 16,
+            items: { type: "string", maxLength: 2048 }
+          },
+          ttl: {
+            type: "integer",
+            minimum: 1,
+            maximum: 3600,
+            description: "Effective remaining lifetime in seconds, clipped to identity, source credential and certificate expiry."
+          }
+        }
+      },
       Client: jsonSchemaFor(clientSchema),
       Event: jsonSchemaFor(wsEventsSchema),
       ListClientsParams: jsonSchemaFor(listClientsParamsSchema),
@@ -1485,6 +1678,133 @@ var engineOpenApiDocument = {
     "read-managed-webtty-recordings": ["webtty.logs.read-only"]
   },
   paths: {
+    "/.well-known/rstream/engine": {
+      get: {
+        tags: ["Discovery"],
+        summary: "Discover the dedicated project mTLS API.",
+        operationId: "get_engine_discovery",
+        description: "Anonymous GET on the ordinary project Engine authority. Follow the returned HTTPS URL; do not infer an mTLS hostname. Cache per client using Cache-Control (normally one hour). No certificate, bearer token, cookie or redirect is required. Available only where an explicit EE mapping is configured.",
+        security: [],
+        responses: {
+          "200": {
+            description: "Project-bound discovery. Capabilities describe enabled server features; callers still need the corresponding rights.",
+            headers: {
+              "Cache-Control": {
+                schema: { type: "string" },
+                example: "public, max-age=3600"
+              }
+            },
+            content: {
+              "application/json": {
+                schema: { $ref: "#/components/schemas/EngineDiscovery" }
+              }
+            }
+          },
+          "404": {
+            description: "Dedicated mTLS API is not configured on this authority."
+          }
+        }
+      }
+    },
+    "/api/turn-server/credentials": {
+      post: {
+        tags: ["TURN"],
+        summary: "Issue short-lived project TURN credentials.",
+        operationId: "create_engine_turn_credentials",
+        description: "EE managed projects. Same request and response contract as Control plane project TURN issuance. Empty body is valid. Issued credentials require turn.credentials.create only; turn.relay.allocate applies to local PAT/APP derivation. Issuance does not allocate a relay and does not bypass relay quotas or revocation checks.",
+        security: [{ bearerAuth: [] }, { mutualTLS: [] }],
+        requestBody: {
+          required: false,
+          content: {
+            "application/json": {
+              schema: { $ref: "#/components/schemas/CreateTURNCredentials" }
+            }
+          }
+        },
+        responses: {
+          "200": {
+            description: "Short-lived project TURN credentials.",
+            headers: {
+              "Cache-Control": {
+                schema: { type: "string" },
+                example: "no-store"
+              }
+            },
+            content: {
+              "application/json": {
+                schema: { $ref: "#/components/schemas/TURNCredentials" }
+              }
+            }
+          },
+          "400": {
+            description: "Malformed, unknown or out-of-range request fields; body exceeds 4 KiB.",
+            headers: {
+              "Cache-Control": {
+                schema: { type: "string" },
+                example: "no-store"
+              }
+            }
+          },
+          "401": {
+            description: "Missing, invalid, expired or mixed authentication proofs.",
+            headers: {
+              "Cache-Control": {
+                schema: { type: "string" },
+                example: "no-store"
+              }
+            }
+          },
+          "403": {
+            description: "Missing turn.credentials.create permission, workspace membership or project resource scope.",
+            headers: {
+              "Cache-Control": {
+                schema: { type: "string" },
+                example: "no-store"
+              }
+            }
+          },
+          "404": {
+            description: "Project not found.",
+            headers: {
+              "Cache-Control": {
+                schema: { type: "string" },
+                example: "no-store"
+              }
+            }
+          },
+          "409": {
+            description: "Project or serving infrastructure is inactive.",
+            headers: {
+              "Cache-Control": {
+                schema: { type: "string" },
+                example: "no-store"
+              }
+            }
+          },
+          "429": {
+            description: "Rate limit exceeded; do not retry through another issuer.",
+            headers: {
+              "Cache-Control": {
+                schema: { type: "string" },
+                example: "no-store"
+              }
+            }
+          },
+          "503": {
+            description: "Authentication backend, serving metadata or issued keyring unavailable.",
+            headers: {
+              "Cache-Control": {
+                schema: { type: "string" },
+                example: "no-store"
+              }
+            }
+          }
+        },
+        "x-rstream-required-rules": [
+          { resource: "engine.turn-server.credentials", action: "create" }
+        ]
+      }
+    },
     "/api/openapi.json": {
       get: {
         tags: ["Discovery"],
@@ -1511,7 +1831,7 @@ var engineOpenApiDocument = {
         summary: "List visible engine clients.",
         operationId: "list_engine_clients",
         parameters: [{ $ref: "#/components/parameters/ListClientsParams" }],
-        security: [{ bearerAuth: [] }],
+        security: [{ bearerAuth: [] }, { mutualTLS: [] }],
         responses: {
           "200": jsonArrayResponse(
             "Visible clients.",
@@ -1530,7 +1850,7 @@ var engineOpenApiDocument = {
         summary: "List visible engine tunnels.",
         operationId: "list_engine_tunnels",
         parameters: [{ $ref: "#/components/parameters/ListTunnelsParams" }],
-        security: [{ bearerAuth: [] }],
+        security: [{ bearerAuth: [] }, { mutualTLS: [] }],
         responses: {
           "200": jsonArrayResponse(
             "Visible tunnels. Fine-grained list scopes may filter objects and project fields.",
@@ -1550,7 +1870,7 @@ var engineOpenApiDocument = {
         summary: "Subscribe to visible engine state through Server-Sent Events.",
         operationId: "watch_engine_events_sse",
         parameters: [{ $ref: "#/components/parameters/WatchParams" }],
-        security: [{ bearerAuth: [] }],
+        security: [{ bearerAuth: [] }, { mutualTLS: [] }],
         responses: {
           "200": streamResponse(
             "SSE stream. Each event is emitted as a data line containing a JSON Event object."
@@ -1569,7 +1889,7 @@ var engineOpenApiDocument = {
         summary: "Subscribe to visible engine state through a WebSocket upgrade.",
         operationId: "watch_engine_events_websocket",
         parameters: [{ $ref: "#/components/parameters/WatchParams" }],
-        security: [{ bearerAuth: [] }],
+        security: [{ bearerAuth: [] }, { mutualTLS: [] }],
         responses: {
           "101": {
             description: "WebSocket connection accepted. Frames contain JSON Event objects."
@@ -1593,6 +1913,113 @@ var engineOpenApiJson = `${JSON.stringify(
 
 // src/resolution.ts
 var import_rstream3 = require("@rstreamlabs/rstream");
+
+// src/http-lifetime.ts
+var requestLifetime = (parents, milliseconds) => {
+  const controller = new AbortController();
+  const signals = parents.filter((signal) => signal != null);
+  const listeners = signals.map((signal) => ({
+    signal,
+    abort: () => controller.abort(signal.reason)
+  }));
+  for (const listener of listeners) {
+    if (listener.signal.aborted) listener.abort();
+    else
+      listener.signal.addEventListener("abort", listener.abort, { once: true });
+  }
+  const timer = setTimeout(
+    () => controller.abort(
+      new DOMException("Engine request timed out.", "TimeoutError")
+    ),
+    milliseconds
+  );
+  return {
+    signal: controller.signal,
+    stopTimer: () => clearTimeout(timer),
+    abort: () => controller.abort(
+      new DOMException("Engine request closed.", "AbortError")
+    ),
+    close: () => {
+      clearTimeout(timer);
+      for (const listener of listeners)
+        listener.signal.removeEventListener("abort", listener.abort);
+    }
+  };
+};
+var readChunks = async (reader, limit, chunks, size) => {
+  const result = await reader.read();
+  if (result.done) return chunks;
+  const total = size + result.value.byteLength;
+  if (total > limit) {
+    await reader.cancel();
+    throw new Error("HTTP response exceeds the size limit.");
+  }
+  chunks.push(result.value);
+  return readChunks(reader, limit, chunks, total);
+};
+var readBoundedText = async (response, limit) => {
+  if (Number(response.headers.get("content-length")) > limit) {
+    await response.body?.cancel();
+    throw new Error("HTTP response exceeds the size limit.");
+  }
+  if (!response.body) return "";
+  const reader = response.body.getReader();
+  const chunks = await readChunks(reader, limit, [], 0).finally(
+    () => reader.releaseLock()
+  );
+  const bytes = new Uint8Array(
+    chunks.reduce((size, chunk) => size + chunk.byteLength, 0)
+  );
+  chunks.reduce((offset, chunk) => {
+    bytes.set(chunk, offset);
+    return offset + chunk.byteLength;
+  }, 0);
+  return new TextDecoder().decode(bytes);
+};
+var waitWithSignal = async (promise, signal) => {
+  if (!signal) return promise;
+  if (signal.aborted) {
+    void promise.catch(() => void 0);
+    signal.throwIfAborted();
+  }
+  return new Promise((resolve, reject) => {
+    const abort = () => reject(signal.reason);
+    signal.addEventListener("abort", abort, { once: true });
+    void promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
+  });
+};
+
+// src/control-plane-fetch.ts
+function createBoundedControlPlaneFetch(timeoutMilliseconds, parent, fetch2 = globalThis.fetch, maxResponseBytes = 16384) {
+  return async (input, init) => {
+    const request2 = new Request(input, init);
+    const headers = new Headers(request2.headers);
+    headers.set("Connection", "close");
+    const lifetime = requestLifetime(
+      [parent, request2.signal],
+      timeoutMilliseconds
+    );
+    try {
+      lifetime.signal.throwIfAborted();
+      const response = await fetch2(input, {
+        ...init,
+        redirect: "manual",
+        headers,
+        signal: lifetime.signal
+      });
+      const responseBody2 = response.body === null ? null : await readBoundedText(response, maxResponseBytes);
+      return new Response(responseBody2, {
+        headers: Object.fromEntries(response.headers.entries()),
+        status: response.status,
+        statusText: response.statusText
+      });
+    } finally {
+      lifetime.close();
+    }
+  };
+}
+
+// src/resolution.ts
 var import_rstream4 = require("@rstreamlabs/rstream");
 var import_rstream5 = require("@rstreamlabs/rstream");
 var import_rstream6 = require("@rstreamlabs/rstream");
@@ -1726,6 +2153,12 @@ async function resolveManagedTunnelsProject(config) {
     );
   }
   const controlPlane = new import_rstream7.RstreamClient({
+    fetch: createBoundedControlPlaneFetch(
+      1e4,
+      void 0,
+      globalThis.fetch,
+      1024 * 1024
+    ),
     apiUrl: resolveTunnelsAPIURL(config.apiUrl),
     controlPlaneHeaders: config.controlPlaneHeaders,
     credentials
@@ -1766,62 +2199,231 @@ var RstreamTunnelsResource = class {
 };
 
 // src/tunnels.ts
-var import_rstream12 = require("@rstreamlabs/rstream");
-var import_rstream13 = require("@rstreamlabs/rstream");
 var import_rstream14 = require("@rstreamlabs/rstream");
+var import_rstream15 = require("@rstreamlabs/rstream");
 
-// src/turn.ts
+// src/engine-http.ts
 var import_rstream8 = require("@rstreamlabs/rstream");
-var import_rstream9 = require("@rstreamlabs/rstream");
-var import_rstream10 = require("@rstreamlabs/rstream");
-var import_turn = require("@rstreamlabs/rstream/turn");
-
-// src/control-plane-fetch.ts
-function createRequestLifetime(parent, timeoutMilliseconds) {
-  const controller = new AbortController();
-  const abort = () => controller.abort(parent.reason);
-  if (parent.aborted) {
-    abort();
-  } else {
-    parent.addEventListener("abort", abort, { once: true });
-  }
-  const timeout = setTimeout(
-    () => controller.abort(new Error("Control plane request timed out.")),
-    timeoutMilliseconds
-  );
-  return {
-    close: () => {
-      clearTimeout(timeout);
-      parent.removeEventListener("abort", abort);
-    },
-    signal: controller.signal
-  };
-}
-function createBoundedControlPlaneFetch(timeoutMilliseconds) {
-  return async (input, init) => {
-    const request = new Request(input, init);
-    const headers = new Headers(request.headers);
-    headers.set("Connection", "close");
-    const lifetime = createRequestLifetime(request.signal, timeoutMilliseconds);
+var import_zod = require("zod");
+var discoverySchema = import_zod.z.object({
+  version: import_zod.z.literal(1),
+  projectEndpoint: import_zod.z.string(),
+  mtlsApiUrl: import_zod.z.string(),
+  capabilities: import_zod.z.array(import_zod.z.string()).max(32)
+});
+var hasClientCertificate = (tls) => tls?.cert !== void 0 || tls?.key !== void 0;
+var validateMTLSURL = (target, source) => {
+  const url = new URL(target);
+  if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash || url.pathname !== "/api" || url.hostname.split(".")[0] !== source.hostname.split(".")[0])
+    throw new Error("Invalid discovered mTLS Engine API URL.");
+  normalizeEngineAddress(url.host);
+  return url.href;
+};
+var discoveryCacheMilliseconds = (response) => {
+  const cache = response.headers.get("cache-control") ?? "";
+  if (/\bno-(?:store|cache)\b/i.test(cache)) return 0;
+  const seconds = cache.match(/\bmax-age\s*=\s*"?(\d+)/i)?.[1];
+  return Math.min(seconds === void 0 ? 3600 : Number(seconds), 86400) * 1e3;
+};
+var EngineHTTP = class {
+  constructor(options) {
+    this.options = options;
+    if (hasClientCertificate(options.tls) && (!options.tls?.cert || !options.tls?.key))
+      throw new Error("mTLS requires both a certificate and its private key.");
+  }
+  options;
+  closed = new AbortController();
+  authenticated;
+  anonymous;
+  discovery;
+  flight;
+  get usesMTLS() {
+    return hasClientCertificate(this.options.tls);
+  }
+  async close() {
+    this.closed.abort(new Error("Engine HTTP client is closed."));
+    this.discovery = void 0;
+    await Promise.all([
+      this.authenticated?.then((client) => client.close()),
+      this.anonymous?.then((client) => client.close())
+    ]);
+  }
+  async transport(anonymous) {
+    this.closed.signal.throwIfAborted();
+    if (!anonymous && this.options.fetch) return this.options.fetch;
+    if (!this.options.tls) return globalThis.fetch;
+    if (anonymous) {
+      this.anonymous ??= Promise.resolve().then(() => (init_node_engine_http(), node_engine_http_exports)).then(
+        ({ NodeEngineHTTP: NodeEngineHTTP2 }) => new NodeEngineHTTP2({
+          ca: this.options.tls?.ca,
+          rejectUnauthorized: true
+        })
+      );
+      return (await this.anonymous).fetch;
+    }
+    this.authenticated ??= Promise.resolve().then(() => (init_node_engine_http(), node_engine_http_exports)).then(
+      ({ NodeEngineHTTP: NodeEngineHTTP2 }) => new NodeEngineHTTP2(this.options.tls ?? {})
+    );
+    return (await this.authenticated).fetch;
+  }
+  async apiURL(engine, signal) {
+    this.closed.signal.throwIfAborted();
+    signal?.throwIfAborted();
+    const source = new URL(`https://${normalizeEngineAddress(engine)}`);
+    if (!this.usesMTLS) return `https://${normalizeEngineAddress(engine)}/api`;
+    if (this.options.mtlsApiUrl)
+      return validateMTLSURL(this.options.mtlsApiUrl, source);
+    if (this.discovery?.source === source.origin && this.discovery.expiresAt > Date.now())
+      return this.discovery.url;
+    const flight = this.flight?.source === source.origin ? this.flight : { source: source.origin, promise: this.discover(source) };
+    this.flight = flight;
+    try {
+      const discovery = await waitWithSignal(flight.promise, signal);
+      this.discovery = discovery;
+      return discovery.url;
+    } finally {
+      void flight.promise.then(
+        () => {
+          if (this.flight === flight) this.flight = void 0;
+        },
+        () => {
+          if (this.flight === flight) this.flight = void 0;
+        }
+      );
+    }
+  }
+  async discover(source) {
+    const lifetime = requestLifetime([this.closed.signal], 5e3);
+    try {
+      const fetch2 = await this.transport(true);
+      const response = await fetch2(
+        new URL("/.well-known/rstream/engine", source),
+        {
+          method: "GET",
+          credentials: "omit",
+          redirect: "manual",
+          signal: lifetime.signal
+        }
+      );
+      if (!response.ok) {
+        await response.body?.cancel();
+        throw new import_rstream8.RstreamHTTPError(
+          response.status,
+          "mTLS Engine discovery failed."
+        );
+      }
+      const text = await readBoundedText(response, 16384);
+      const value = JSON.parse(text);
+      const document = discoverySchema.parse(value);
+      if (document.projectEndpoint !== source.hostname.split(".")[0] || !document.capabilities.includes("engine-api-mtls"))
+        throw new Error(
+          "Engine discovery does not advertise mTLS for this project."
+        );
+      return {
+        source: source.origin,
+        url: validateMTLSURL(document.mtlsApiUrl, source),
+        expiresAt: Date.now() + discoveryCacheMilliseconds(response)
+      };
+    } finally {
+      lifetime.close();
+    }
+  }
+  async eventStream(engine, options) {
+    const lifetime = requestLifetime(
+      [this.closed.signal, options.signal],
+      1e4
+    );
     try {
-      const response = await globalThis.fetch(request, {
+      const base = await this.apiURL(engine, lifetime.signal);
+      const headers = new Headers(options.headers);
+      if (this.usesMTLS && headers.has("authorization"))
+        throw new Error("Use a token or mTLS, not both.");
+      headers.set("Accept", "text/event-stream");
+      const fetch2 = await this.transport(false);
+      const response = await fetch2(`${base}/sse`, {
+        method: "GET",
         headers,
+        credentials: "omit",
+        redirect: "manual",
         signal: lifetime.signal
       });
-      const responseBody = response.body === null ? null : new Uint8Array(await response.arrayBuffer());
-      return new Response(responseBody, {
-        headers: Object.fromEntries(response.headers.entries()),
+      if (!response.ok)
+        throw new import_rstream8.RstreamHTTPError(
+          response.status,
+          await readBoundedText(response, 16384)
+        );
+      if (!response.headers.get("content-type")?.startsWith("text/event-stream"))
+        throw new Error("Engine returned an invalid event stream.");
+      lifetime.stopTimer();
+      return {
+        response,
+        close: () => {
+          lifetime.abort();
+          lifetime.close();
+        }
+      };
+    } catch (error) {
+      lifetime.abort();
+      lifetime.close();
+      if (!(error instanceof import_rstream8.RstreamHTTPError)) this.discovery = void 0;
+      throw error;
+    }
+  }
+  async response(engine, path, options = {}, maxBytes = 16 * 1024 * 1024) {
+    if (!path.startsWith("/") || path.startsWith("//") || path.includes("\\"))
+      throw new Error("Engine request path must be a relative absolute path.");
+    const lifetime = requestLifetime(
+      [this.closed.signal, options.signal],
+      1e4
+    );
+    try {
+      const base = await this.apiURL(engine, lifetime.signal);
+      const url = new URL(`${base}${path}`);
+      if (url.origin !== new URL(base).origin || !url.pathname.startsWith("/api/") || url.username || url.password)
+        throw new Error(
+          "Engine request path must remain inside the Engine API."
+        );
+      const headers = new Headers(options.headers);
+      if (this.usesMTLS && (headers.has("authorization") || url.searchParams.has("rstream.token")))
+        throw new Error("Use a token or mTLS, not both.");
+      const fetch2 = await this.transport(false);
+      const response = await fetch2(`${base}${path}`, {
+        ...options,
+        headers,
+        credentials: "omit",
+        redirect: "manual",
+        signal: lifetime.signal
+      });
+      const text = await readBoundedText(
+        response,
+        response.ok ? maxBytes : 16384
+      );
+      if (!response.ok) throw new import_rstream8.RstreamHTTPError(response.status, text);
+      return new Response([204, 205].includes(response.status) ? null : text, {
         status: response.status,
-        statusText: response.statusText
+        headers: response.headers
       });
+    } catch (error) {
+      if (!(error instanceof import_rstream8.RstreamHTTPError)) this.discovery = void 0;
+      throw error;
     } finally {
       lifetime.close();
     }
-  };
-}
+  }
+};
+
+// src/tunnels.ts
+var import_rstream16 = require("@rstreamlabs/rstream");
+var import_rstream17 = require("@rstreamlabs/rstream");
 
 // src/turn.ts
-var z8 = __toESM(require("zod"));
+var import_rstream9 = require("@rstreamlabs/rstream");
+var import_rstream10 = require("@rstreamlabs/rstream");
+var import_rstream11 = require("@rstreamlabs/rstream");
+var import_rstream12 = require("@rstreamlabs/rstream");
+var import_rstream13 = require("@rstreamlabs/rstream");
+var import_turn = require("@rstreamlabs/rstream/turn");
+var z9 = __toESM(require("zod"));
 var import_crypto = __toESM(require("crypto"));
 var defaultTURNPort = 3478;
 var defaultTURNSPort = 5349;
@@ -1830,20 +2432,31 @@ var maxTURNCredentialTTLSeconds = 60 * 60;
 var maxTURNKeyringBytes = 8 * 1024;
 var defaultAPIRequestTimeoutMilliseconds = 1e4;
 var maxAPIRequestTimeoutMilliseconds = 6e4;
-var turnTokenClaimsSchema = z8.object({
-  exp: z8.number().int().optional(),
-  iat: z8.number().int().optional(),
-  token_endpoint: z8.string().regex(/^[0-9a-f]{8}$/i).optional(),
-  tokendpoint: z8.string().regex(/^[0-9a-f]{8}$/i).optional(),
-  type: z8.enum(["app", "auth", "pat"])
+var turnTokenClaimsSchema = z9.object({
+  permissions: z9.array(z9.string()).nullable().optional(),
+  exp: z9.number().int().optional(),
+  iat: z9.number().int().optional(),
+  token_endpoint: z9.string().regex(/^[A-Za-z0-9_.-]{1,128}$/).optional(),
+  tokendpoint: z9.string().regex(/^[A-Za-z0-9_.-]{1,128}$/).optional(),
+  type: z9.enum(["app", "auth", "pat"])
 });
-var turnCredentialModeSchema = z8.enum(["api", "app", "pat"]);
+var turnCredentialModeSchema = z9.enum([
+  "auto",
+  "api",
+  "engine",
+  "app",
+  "pat"
+]);
 function normalizeOptionalString2(value) {
   const normalized = value?.trim();
   return normalized ? normalized : void 0;
 }
 function normalizeClusterDomain(clusterDomain) {
   const normalized = normalizeOptionalString2(clusterDomain);
+  if (normalized && (normalized.length > 253 || !normalized.split(".").every(
+    (label) => /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/i.test(label)
+  )))
+    throw new Error("TURN domain and realm must be valid DNS names.");
   return normalized?.toLowerCase();
 }
 function normalizeNow(now) {
@@ -1958,14 +2571,27 @@ function requireOption(value, message) {
   }
   throw new Error(message);
 }
-function resolveMode(credentials, mode) {
-  if (mode !== void 0) {
-    return turnCredentialModeSchema.parse(mode);
-  }
-  if ((0, import_rstream8.isClientCredentials)(credentials)) {
-    return "app";
+function automaticPATClaims(token) {
+  try {
+    return parseTURNTokenClaims(token);
+  } catch {
+    return void 0;
   }
-  return "api";
+}
+function resolveMode(options) {
+  const requested = turnCredentialModeSchema.parse(options.mode ?? "auto");
+  if (requested !== "auto") return requested;
+  if (options.client?.usesMTLS || hasClientCertificate(options.tls))
+    return "engine";
+  const claims = (0, import_rstream11.isTokenCredentials)(options.credentials) ? automaticPATClaims(options.credentials.token) : void 0;
+  if (claims?.token_endpoint && claims.tokendpoint && claims.token_endpoint !== claims.tokendpoint)
+    throw new Error("Conflicting PAT token endpoints.");
+  const localTarget = options.projectEndpoint && (options.clusterDomain || options.turnDomain && options.turnRealm);
+  if (!localTarget) return "auto";
+  if ((0, import_rstream9.isClientCredentials)(options.credentials)) return "app";
+  if (claims?.type === "pat" && claims.exp !== void 0 && (claims.token_endpoint || claims.tokendpoint) && (claims.permissions === null || claims.permissions?.includes("turn.relay.allocate")))
+    return "pat";
+  return "auto";
 }
 async function readBoundedTURNKeyring(reader, chunks = [], size = 0) {
   const result = await reader.read();
@@ -1985,7 +2611,7 @@ async function readBoundedTURNKeyring(reader, chunks = [], size = 0) {
 }
 function parseTURNServerPublicKeyHex(value) {
   const normalized = value.trim();
-  if (normalized.length === 0 || normalized.length % 2 !== 0 || !/^[0-9a-f]+$/i.test(normalized)) {
+  if (normalized.length === 0 || normalized.length > maxTURNKeyringBytes || normalized.length % 2 !== 0 || !/^[0-9a-f]+$/i.test(normalized)) {
     throw new Error("TURN keyring must contain hexadecimal DER key material.");
   }
   try {
@@ -2008,6 +2634,10 @@ function parseTURNServerPublicKeyHex(value) {
   }
 }
 function parseAPPPrivateKey(value) {
+  if (value.length > 16384 || value.length % 2 !== 0 || !/^[0-9a-f]+$/i.test(value))
+    throw new Error(
+      "TURN APP client secret must contain hexadecimal DER key material."
+    );
   try {
     const key = import_crypto.default.createPrivateKey({
       key: Buffer.from(value, "hex"),
@@ -2043,19 +2673,38 @@ async function loadTURNServerPublicKeyHex(clusterDomain, options) {
     `/keyrings/turn/${clusterDomain}.spki.der.hex`,
     keyringBaseURL
   );
-  const response = await fetch(url, { redirect: "manual" });
-  if (response.status >= 300 && response.status < 400) {
+  if (url.protocol !== "https:" || url.username || url.password)
     throw new Error(
-      "TURN keyring request was redirected; redirects are refused."
+      "TURN keyring requests require HTTPS without URL credentials."
     );
+  const lifetime = requestLifetime(
+    [options.signal],
+    normalizeAPIRequestTimeoutMilliseconds(options.requestTimeoutMilliseconds)
+  );
+  try {
+    const response = await fetch(url, {
+      redirect: "manual",
+      credentials: "omit",
+      signal: lifetime.signal
+    });
+    if (response.status >= 300 && response.status < 400) {
+      await response.body?.cancel();
+      throw new Error(
+        "TURN keyring request was redirected; redirects are refused."
+      );
+    }
+    if (!response.ok) {
+      await response.body?.cancel();
+      throw new Error(`TURN keyring request returned HTTP ${response.status}.`);
+    }
+    if (!response.body) {
+      throw new Error("TURN keyring response body is missing.");
+    }
+    const reader = response.body.getReader();
+    return (await readBoundedTURNKeyring(reader).finally(() => reader.releaseLock())).trim();
+  } finally {
+    lifetime.close();
   }
-  if (!response.ok) {
-    throw new Error(`TURN keyring request returned HTTP ${response.status}.`);
-  }
-  if (!response.body) {
-    throw new Error("TURN keyring response body is missing.");
-  }
-  return (await readBoundedTURNKeyring(response.body.getReader())).trim();
 }
 async function createAPITURNCredentials(options) {
   const projectId = normalizeOptionalString2(options.projectId);
@@ -2069,11 +2718,21 @@ async function createAPITURNCredentials(options) {
     options.requestTimeoutMilliseconds
   );
   const params = createAPITURNCredentialsParams(options.ttlSeconds);
-  const request = options.fetch ?? createBoundedControlPlaneFetch(requestTimeoutMilliseconds);
-  const client = new import_rstream10.RstreamClient({
+  const request2 = createBoundedControlPlaneFetch(
+    requestTimeoutMilliseconds,
+    options.signal,
+    options.fetch
+  );
+  const client = new import_rstream12.RstreamClient({
+    controlPlaneHeaders: options.controlPlaneHeaders,
     apiUrl: options.apiUrl,
-    credentials: options.credentials,
-    fetch: request
+    credentials: (0, import_rstream9.isClientCredentials)(options.credentials) ? {
+      token: (0, import_rstream10.createClientCredentialsToken)(options.credentials, {
+        expiresInSeconds: 60,
+        claims: { permissions: ["turn.credentials.create"] }
+      }).token
+    } : options.credentials,
+    fetch: request2
   });
   if (projectId) {
     return await client.tunnels.projects.createTurnCredentials(
@@ -2116,6 +2775,8 @@ function createPATTURNCredentials(options) {
   const claimsTokenEndpoint = normalizeOptionalString2(
     claims.token_endpoint ?? claims.tokendpoint
   );
+  if (claims.token_endpoint && claims.tokendpoint && claims.token_endpoint !== claims.tokendpoint)
+    throw new Error("Conflicting PAT token endpoints.");
   const configuredTokenEndpoint = normalizeOptionalString2(
     options.tokenEndpoint
   );
@@ -2125,6 +2786,8 @@ function createPATTURNCredentials(options) {
       "TURN PAT mode requires a PAT token carrying a token endpoint."
     );
   }
+  requireTURNReference(projectEndpoint);
+  requireTURNReference(tokenEndpoint);
   if (configuredTokenEndpoint !== void 0 && claimsTokenEndpoint !== void 0 && claimsTokenEndpoint !== configuredTokenEndpoint) {
     throw new Error("Token endpoint does not match the PAT token.");
   }
@@ -2169,6 +2832,8 @@ async function createAPPTURNCredentials(options) {
   if (!clientId) {
     throw new Error("Client ID is required for TURN APP mode.");
   }
+  requireTURNReference(projectEndpoint);
+  requireTURNReference(clientId);
   const clientSecret = normalizeOptionalString2(options.clientSecret);
   if (!clientSecret) {
     throw new Error("Client secret is required for TURN APP mode.");
@@ -2201,32 +2866,47 @@ async function createAPPTURNCredentials(options) {
     username
   });
 }
-async function createTURNCredentials(options) {
+async function createTURNCredentialsForLifetime(options) {
   const credentials = options.credentials;
-  const mode = resolveMode(credentials, options.mode);
+  const mode = resolveMode(options);
   const projectEndpoint = normalizeOptionalString2(options.projectEndpoint);
-  if (mode === "api") {
+  if (mode === "engine") return createEngineTURNCredentials(options);
+  if (options.client?.usesMTLS || hasClientCertificate(options.tls))
+    throw new Error(
+      "Certificate authentication requires automatic or Engine TURN mode."
+    );
+  if (mode === "api" || mode === "auto") {
     const controlPlaneCredentials = options.controlPlaneCredentials ?? credentials;
     if (!controlPlaneCredentials) {
+      if (mode === "auto" && (options.client || options.engine))
+        return createEngineTURNCredentials(options);
       throw new Error(
         "Control-plane credentials are required for TURN API mode."
       );
     }
-    return await createAPITURNCredentials({
-      apiUrl: options.apiUrl,
-      credentials: controlPlaneCredentials,
-      fetch: options.fetch,
-      projectEndpoint,
-      projectId: options.projectId,
-      requestTimeoutMilliseconds: options.requestTimeoutMilliseconds,
-      ttlSeconds: options.ttlSeconds
-    });
+    try {
+      return await createAPITURNCredentials({
+        controlPlaneHeaders: options.controlPlaneHeaders,
+        apiUrl: options.apiUrl,
+        credentials: controlPlaneCredentials,
+        fetch: options.fetch,
+        projectEndpoint,
+        projectId: options.projectId,
+        requestTimeoutMilliseconds: mode === "auto" ? Math.min(options.requestTimeoutMilliseconds ?? 1e4, 5e3) : options.requestTimeoutMilliseconds,
+        signal: options.signal,
+        ttlSeconds: options.ttlSeconds
+      });
+    } catch (error) {
+      if (mode !== "auto" || !projectEndpoint || !(options.client?.configuredEngine || options.engine) || !turnEngineFallbackAllowed(error, options.signal))
+        throw error;
+      return createEngineTURNCredentials(options);
+    }
   }
   const legacyDomain = normalizeClusterDomain(options.clusterDomain);
   const turnDomain = normalizeClusterDomain(options.turnDomain) ?? legacyDomain ?? (projectEndpoint && options.engine ? deriveClusterDomainFromEngine(projectEndpoint, options.engine) : void 0);
   const turnRealm = normalizeClusterDomain(options.turnRealm) ?? legacyDomain;
   if (mode === "pat") {
-    if (!(0, import_rstream9.isTokenCredentials)(credentials)) {
+    if (!(0, import_rstream11.isTokenCredentials)(credentials)) {
       throw new Error("A PAT token is required for TURN PAT mode.");
     }
     return createPATTURNCredentials({
@@ -2250,10 +2930,12 @@ async function createTURNCredentials(options) {
       turnsPort: options.turnsPort
     });
   }
-  if (!(0, import_rstream8.isClientCredentials)(credentials)) {
+  if (!(0, import_rstream9.isClientCredentials)(credentials)) {
     throw new Error("Client credentials are required for TURN APP mode.");
   }
   return await createAPPTURNCredentials({
+    signal: options.signal,
+    requestTimeoutMilliseconds: options.requestTimeoutMilliseconds,
     apiUrl: options.apiUrl,
     clientId: credentials.clientId,
     clientSecret: credentials.clientSecret,
@@ -2277,25 +2959,139 @@ async function createTURNCredentials(options) {
     turnsPort: options.turnsPort
   });
 }
+function requireTURNReference(value) {
+  if (!/^[A-Za-z0-9_.-]{1,128}$/.test(value) || value === "-")
+    throw new Error("Invalid TURN project or credential reference.");
+}
+function turnEngineFallbackAllowed(error, signal) {
+  if (signal?.aborted) return false;
+  if (error instanceof import_rstream13.RstreamHTTPError)
+    return [502, 503, 504].includes(error.status);
+  if (error instanceof DOMException && error.name === "TimeoutError")
+    return true;
+  if (typeof error !== "object" || error === null) return false;
+  if ("code" in error && typeof error.code === "string")
+    return [
+      "ENOTFOUND",
+      "EAI_AGAIN",
+      "ECONNREFUSED",
+      "ECONNRESET",
+      "ETIMEDOUT",
+      "EHOSTUNREACH",
+      "ENETUNREACH",
+      "UND_ERR_CONNECT_TIMEOUT",
+      "UND_ERR_HEADERS_TIMEOUT",
+      "UND_ERR_SOCKET"
+    ].includes(error.code);
+  return "cause" in error && error.cause !== error ? turnEngineFallbackAllowed(error.cause, signal) : false;
+}
+async function createEngineTURNCredentials(options) {
+  const client = options.client ?? new RstreamTunnelsClient({
+    credentials: options.credentials,
+    tls: options.tls,
+    mtlsApiUrl: options.mtlsApiUrl,
+    engine: options.engine,
+    projectEndpoint: options.projectEndpoint,
+    projectId: options.projectId
+  });
+  try {
+    const engine = await client.getEngine();
+    const endpoint = new URL(`https://${engine}`).hostname.split(".")[0];
+    if (options.projectEndpoint && options.projectEndpoint !== endpoint || options.projectId && !options.projectEndpoint)
+      throw new Error("TURN project endpoint must match the Engine client.");
+    if (options.engine && options.engine !== engine)
+      throw new Error("TURN Engine must match the reusable client.");
+    const value = await client.request(
+      "/turn-server/credentials",
+      {
+        method: "POST",
+        signal: options.signal,
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(
+          createAPITURNCredentialsParams(options.ttlSeconds)
+        )
+      },
+      16384
+    );
+    return import_turn.turnCredentialsSchema.parse(value);
+  } finally {
+    if (!options.client) await client.close();
+  }
+}
+function validateTURNCredentialsRequest(options) {
+  normalizeTTLSeconds(options.ttlSeconds);
+  turnCredentialModeSchema.parse(options.mode ?? "auto");
+  return normalizeAPIRequestTimeoutMilliseconds(
+    options.requestTimeoutMilliseconds
+  );
+}
+async function createTURNCredentials(options) {
+  const lifetime = requestLifetime(
+    [options.signal],
+    validateTURNCredentialsRequest(options)
+  );
+  try {
+    lifetime.signal.throwIfAborted();
+    if ((options.client?.usesMTLS || hasClientCertificate(options.tls)) && options.credentials)
+      throw new Error("Use a token or mTLS, not both.");
+    if (options.client && options.credentials && !sameTURNCredentials(options.client.credentials, options.credentials))
+      throw new Error(
+        "TURN credentials must match the reusable Engine client."
+      );
+    return await waitWithSignal(
+      createTURNCredentialsForLifetime({
+        ...options,
+        credentials: options.credentials ?? options.client?.credentials,
+        signal: lifetime.signal
+      }),
+      lifetime.signal
+    );
+  } finally {
+    lifetime.close();
+  }
+}
+function sameTURNCredentials(left, right) {
+  if ((0, import_rstream11.isTokenCredentials)(left) && (0, import_rstream11.isTokenCredentials)(right))
+    return left.token === right.token;
+  return (0, import_rstream9.isClientCredentials)(left) && (0, import_rstream9.isClientCredentials)(right) && left.clientId === right.clientId && left.clientSecret === right.clientSecret;
+}
 
 // src/turn-resource.ts
-var import_rstream11 = require("@rstreamlabs/rstream");
 var RstreamTURNResource = class {
   client;
   constructor(client) {
     this.client = client;
   }
   async createCredentials(options = {}) {
+    const lifetime = requestLifetime(
+      [options.signal],
+      validateTURNCredentialsRequest(options)
+    );
+    try {
+      lifetime.signal.throwIfAborted();
+      return await waitWithSignal(
+        this.createForLifetime({ ...options, signal: lifetime.signal }),
+        lifetime.signal
+      );
+    } finally {
+      lifetime.close();
+    }
+  }
+  async createForLifetime(options) {
     const credentials = options.credentials ?? this.client.credentials;
-    const localMode = options.mode === "app" || options.mode === "pat" || options.mode === void 0 && (0, import_rstream11.isClientCredentials)(credentials);
-    const target = localMode && (options.turnDomain === void 0 || options.turnRealm === void 0) && options.clusterDomain === void 0 ? await this.client.getTURNTarget() : void 0;
-    const engine = options.engine ?? (options.clusterDomain === void 0 && options.turnDomain === void 0 && target === void 0 ? await this.client.getEngine().catch(() => void 0) : void 0);
+    const localMode = options.mode === "app" || options.mode === "pat";
+    const target = localMode && !this.client.usesMTLS && (options.turnDomain === void 0 || options.turnRealm === void 0) && options.clusterDomain === void 0 ? await this.client.getTURNTarget() : void 0;
     return await createTURNCredentials({
+      client: this.client,
+      signal: options.signal,
       apiUrl: options.apiUrl ?? this.client.apiUrl,
+      fetch: options.fetch,
+      requestTimeoutMilliseconds: options.requestTimeoutMilliseconds,
       clusterDomain: options.clusterDomain,
+      controlPlaneHeaders: options.controlPlaneHeaders ?? this.client.controlPlaneHeaders,
       controlPlaneCredentials: options.controlPlaneCredentials ?? this.client.controlPlaneCredentials,
       credentials,
-      engine,
+      engine: options.engine,
       keyringBaseUrl: options.keyringBaseUrl,
       mode: options.mode,
       now: options.now,
@@ -2464,31 +3260,52 @@ var engineAuthTokenScopes = {
 var RstreamTunnelsClient = class {
   config;
   managedProject;
+  http;
   constructor(config) {
     this.config = config;
+    if (hasClientCertificate(config?.tls) && config?.credentials)
+      throw new Error("Use a token or mTLS, not both.");
+    this.http = new EngineHTTP(config ?? {});
   }
   get apiUrl() {
     return resolveTunnelsAPIURL(this.config?.apiUrl);
   }
   get credentials() {
+    if (this.http.usesMTLS) return void 0;
     return resolveTunnelsCredentials(this.config?.credentials);
   }
   get controlPlaneCredentials() {
+    if (this.http.usesMTLS) return void 0;
     return resolveControlPlaneCredentials(
       this.config?.controlPlaneCredentials,
       this.credentials
     );
   }
+  get controlPlaneHeaders() {
+    return this.config?.controlPlaneHeaders;
+  }
   get projectEndpoint() {
     return this.config?.projectEndpoint;
   }
+  get configuredEngine() {
+    return this.config?.engine ?? (0, import_rstream17.readEnvironment)().engine;
+  }
+  get usesMTLS() {
+    return this.http.usesMTLS;
+  }
+  async close() {
+    await this.http.close();
+  }
+  async getEngineAPIURL(signal) {
+    return this.http.apiURL(await this.getEngine(), signal);
+  }
   async getEngine() {
     const region = resolveTunnelsRegion(this.config?.region);
     const projectEndpoint = normalizeOptionalString3(
       this.config?.projectEndpoint
     );
     if (region !== void 0) {
-      if (normalizeOptionalString3(this.config?.engine) !== void 0 || (0, import_rstream14.readEnvironment)().engine !== void 0) {
+      if (normalizeOptionalString3(this.config?.engine) !== void 0 || (0, import_rstream17.readEnvironment)().engine !== void 0) {
         throw new Error(
           "Region selection cannot be combined with an explicit engine override."
         );
@@ -2500,17 +3317,17 @@ var RstreamTunnelsClient = class {
       }
       const project = await this.getManagedProject();
       if (project !== void 0) {
-        const engine = (0, import_rstream12.getTunnelsProjectEngine)(project, region);
+        const engine = (0, import_rstream14.getTunnelsProjectEngine)(project, region);
         if (engine) return normalizeEngineAddress(engine);
       }
       throw new Error(
         "Failed to resolve the selected regional engine from the managed tunnels project."
       );
     }
-    if (projectEndpoint !== void 0 && normalizeOptionalString3(this.config?.engine) === void 0 && (0, import_rstream14.readEnvironment)().engine === void 0) {
+    if (projectEndpoint !== void 0 && normalizeOptionalString3(this.config?.engine) === void 0 && (0, import_rstream17.readEnvironment)().engine === void 0) {
       const project = await this.getManagedProject();
       if (project !== void 0) {
-        const engine = (0, import_rstream12.getTunnelsProjectEngine)(project);
+        const engine = (0, import_rstream14.getTunnelsProjectEngine)(project);
         if (engine) {
           return normalizeEngineAddress(engine);
         }
@@ -2551,6 +3368,10 @@ var RstreamTunnelsClient = class {
     };
   }
   async getManagedProject() {
+    if (this.usesMTLS)
+      throw new Error(
+        "mTLS project resolution requires the configured Engine address; the Control plane does not accept certificates."
+      );
     const projectEndpoint = normalizeOptionalString3(
       this.config?.projectEndpoint
     );
@@ -2626,7 +3447,7 @@ var RstreamTunnelsClient = class {
     if (!credentials) {
       return void 0;
     }
-    if (!(0, import_rstream13.isClientCredentials)(credentials)) {
+    if (!(0, import_rstream16.isClientCredentials)(credentials)) {
       return credentials.token;
     }
     const tokenParams = await this.getEngineAuthTokenParams();
@@ -2635,26 +3456,37 @@ var RstreamTunnelsClient = class {
       engine
     })).token;
   }
-  async request(path, options) {
+  async openEventStream(signal) {
+    const engine = await this.getEngine();
+    const token = await this.getToken(engine);
+    return this.http.eventStream(engine, {
+      signal,
+      headers: token ? { Authorization: `Bearer ${token}` } : void 0
+    });
+  }
+  async request(path, options, maxResponseBytes) {
     const engine = normalizeEngineAddress(await this.getEngine());
     if (!path.startsWith("/") || path.startsWith("//")) {
       throw new Error("Engine request path must be a relative absolute path.");
     }
-    const url = `https://${engine}/api${path}`;
     const headers = new Headers(options?.headers || {});
-    const token = await this.getToken(engine);
+    const credentials = this.credentials;
+    const token = path === "/turn-server/credentials" && (0, import_rstream16.isClientCredentials)(credentials) ? (0, import_rstream15.createClientCredentialsToken)(credentials, {
+      expiresInSeconds: 60,
+      claims: { permissions: ["turn.credentials.create"] }
+    }).token : await this.getToken(engine);
     if (token) {
       headers.set("Authorization", `Bearer ${token}`);
     }
-    const response = await fetch(url, {
-      ...options,
-      headers,
-      redirect: options?.redirect ?? "manual"
-    });
-    if (!response.ok) {
-      const errorText = await response.text();
-      throw new Error(`HTTP error ${response.status}: ${errorText}`);
-    }
+    const response = await this.http.response(
+      engine,
+      path,
+      {
+        ...options,
+        headers
+      },
+      maxResponseBytes
+    );
     return await response.json();
   }
 };
@@ -2751,6 +3583,8 @@ function hasWatchOnlyPermissions(permissions) {
   );
 }
 var Watch = class {
+  abort = new AbortController();
+  closeStream;
   connection = null;
   connectionState = "preparing";
   config;
@@ -2765,7 +3599,32 @@ var Watch = class {
     }
     this.connectionState = "connecting";
     try {
+      if (this.config.client?.usesMTLS) {
+        if (this.config.auth !== void 0)
+          throw new Error("Watch: Use a token or mTLS, not both.");
+        if (normalizeTransport(this.config.transport) !== "sse")
+          throw new Error(
+            "Watch: Node.js certificate authentication currently requires SSE."
+          );
+        const stream = await this.config.client.openEventStream(
+          this.abort.signal
+        );
+        if (this.abort.signal.aborted) {
+          stream.close();
+          this.abort.signal.throwIfAborted();
+        }
+        this.closeStream = stream.close;
+        if (!stream.response.body)
+          throw new Error("Watch: Engine event stream is empty.");
+        this.connectionState = "connected";
+        this.events.onConnect?.();
+        void this.readCertificateEvents(stream.response.body).finally(
+          () => this.disconnect()
+        );
+        return;
+      }
       const token = typeof this.config.auth === "function" ? await this.config.auth() : this.config.auth;
+      if (!token) throw new Error("Watch: Authentication is required.");
       validateWatchQueryToken(token);
       const engine = await resolveTunnelsEngine({
         apiUrl: this.config.apiUrl,
@@ -2804,10 +3663,39 @@ var Watch = class {
         };
       }
     } catch (error) {
-      this.connectionState = "preparing";
+      this.closeStream?.();
+      this.closeStream = void 0;
+      this.connectionState = this.abort.signal.aborted ? "closed" : "preparing";
       throw error;
     }
   }
+  async readCertificateEvents(body) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    const state = { buffered: "" };
+    try {
+      while (!this.abort.signal.aborted) {
+        const chunk = await reader.read();
+        if (chunk.done) return;
+        state.buffered += decoder.decode(chunk.value, { stream: true });
+        const frames = state.buffered.split(/\r?\n\r?\n/);
+        state.buffered = frames.pop() ?? "";
+        if (state.buffered.length > 1024 * 1024)
+          throw new Error("Watch event exceeds the size limit.");
+        for (const frame of frames) {
+          if (frame.length > 1024 * 1024)
+            throw new Error("Watch event exceeds the size limit.");
+          const data = frame.split(/\r?\n/).filter((line) => line.startsWith("data:")).map((line) => line.slice(5).replace(/^ /, "")).join("\n");
+          if (data) this.handleMessage(data);
+          if (this.abort.signal.aborted) return;
+        }
+      }
+    } catch {
+      this.disconnect();
+    } finally {
+      reader.releaseLock();
+    }
+  }
   handleMessage(data) {
     try {
       const parsed = wsEventsSchema.parse(JSON.parse(data));
@@ -2817,6 +3705,9 @@ var Watch = class {
     }
   }
   disconnect() {
+    this.abort.abort();
+    this.closeStream?.();
+    this.closeStream = void 0;
     if (this.connection) {
       this.connection.onerror = null;
       this.connection.onmessage = null;
@@ -2832,8 +3723,8 @@ var Watch = class {
 };
 
 // src/webtty.ts
-var z9 = __toESM(require("zod"));
-var osFamilySchema = z9.enum([
+var z10 = __toESM(require("zod"));
+var osFamilySchema = z10.enum([
   "linux",
   "macos",
   "windows",
@@ -2841,45 +3732,55 @@ var osFamilySchema = z9.enum([
   "openbsd",
   "freebsd"
 ]);
-var webttyCapabilitySchema = z9.enum(["exec", "fs"]);
-var webttyFSModeSchema = z9.enum(["read-write", "read-only"]);
-var webttyEncryptionPolicySchema = z9.enum([
+var webttyCapabilitySchema = z10.enum(["exec", "fs"]);
+var webttyFSModeSchema = z10.enum(["read-write", "read-only"]);
+var webttyEncryptionPolicySchema = z10.enum([
   "disabled",
   "explicit_key",
   "workspace_managed"
 ]);
-var webttyServerSchema = z9.object({
-  tunnel_id: z9.string(),
-  tunnel_name: z9.string().optional(),
-  target: z9.string().optional(),
-  rstream_url: z9.string().optional(),
-  status: z9.string().optional(),
-  publish: z9.boolean().optional(),
-  workspace_id: z9.string().optional(),
-  project_id: z9.string().optional(),
-  tunnel_protocol: z9.enum(["http", "webtty"]),
-  managed: z9.boolean(),
-  host: z9.string(),
-  token_auth: z9.boolean(),
-  server_id: z9.string().optional(),
-  server_name: z9.string().optional(),
-  host_key_id: z9.string().optional(),
-  e2e: z9.enum(["disabled", "required"]).optional(),
-  client_proof: z9.enum(["none", "required"]).optional(),
+var webttyTransportSchema = z10.enum([
+  "plain",
+  "websocket",
+  "webtransport"
+]);
+var webttyServerSchema = z10.object({
+  tunnel_id: z10.string(),
+  tunnel_name: z10.string().optional(),
+  target: z10.string().optional(),
+  rstream_url: z10.string().optional(),
+  status: z10.string().optional(),
+  publish: z10.boolean().optional(),
+  workspace_id: z10.string().optional(),
+  project_id: z10.string().optional(),
+  tunnel_protocol: z10.enum(["http", "webtty"]).optional(),
+  tunnel_type: z10.enum(["bytestream", "datagram"]).optional(),
+  http_version: z10.string().optional(),
+  transport: webttyTransportSchema.optional(),
+  transport_error: z10.string().optional(),
+  managed: z10.boolean(),
+  host: z10.string(),
+  token_auth: z10.boolean(),
+  server_id: z10.string().optional(),
+  server_name: z10.string().optional(),
+  host_key_id: z10.string().optional(),
+  e2e: z10.enum(["disabled", "required"]).optional(),
+  client_proof: z10.enum(["none", "required"]).optional(),
   encryption_policy: webttyEncryptionPolicySchema.optional(),
-  capabilities: z9.array(webttyCapabilitySchema).optional(),
-  exec_path: z9.string().optional(),
-  fs_path: z9.string().optional(),
+  capabilities: z10.array(webttyCapabilitySchema).optional(),
+  exec_path: z10.string().optional(),
+  fs_path: z10.string().optional(),
   fs_mode: webttyFSModeSchema.optional(),
+  fs_backend: z10.enum(["webdav", "webrtc"]).optional(),
   os_family: osFamilySchema.optional(),
-  arch: z9.string().optional(),
-  os_id: z9.string().optional(),
-  os_version_id: z9.string().optional(),
-  os_version_codename: z9.string().optional(),
-  os_pretty_name: z9.string().optional(),
-  kernel_release: z9.string().optional(),
-  hostname: z9.string().optional(),
-  labels: z9.record(z9.string(), z9.string().optional()).optional()
+  arch: z10.string().optional(),
+  os_id: z10.string().optional(),
+  os_version_id: z10.string().optional(),
+  os_version_codename: z10.string().optional(),
+  os_pretty_name: z10.string().optional(),
+  kernel_release: z10.string().optional(),
+  hostname: z10.string().optional(),
+  labels: z10.record(z10.string(), z10.string().optional()).optional()
 });
 function isWebTTYCapability(value) {
   return webttyCapabilitySchema.safeParse(value).success;
@@ -2897,11 +3798,12 @@ function webTTYCapabilitiesForLabels(labels) {
 function webTTYHasCapability(capabilities, capability) {
   return capabilities.includes(capability);
 }
-function parser(tunnel) {
+function parser(tunnel, includePrivate) {
   if (tunnel.status !== "online") return null;
-  if (tunnel.publish !== true) return null;
+  if (tunnel.publish !== true && !includePrivate) return null;
   const managedProtocol = tunnel.protocol === "webtty";
-  if (tunnel.protocol !== "http" && !managedProtocol) return null;
+  if (tunnel.protocol !== void 0 && tunnel.protocol !== "http" && !managedProtocol)
+    return null;
   const tunnelLabels = tunnel.labels ?? {};
   if (!managedProtocol && tunnelLabels["application-protocol"] !== "rstream.webtty") {
     return null;
@@ -2929,8 +3831,11 @@ function parser(tunnel) {
     workspace_id: tunnel.workspace_id,
     project_id: tunnel.project_id,
     tunnel_protocol: tunnel.protocol,
+    tunnel_type: tunnel.type,
+    http_version: tunnel.http_version,
+    ...webTTYTransportMetadata(tunnelLabels["rstream.webtty.transport"]),
     managed: managedProtocol,
-    host: formatTunnelHost(tunnel),
+    host: formatTunnelHost(tunnel) ?? "",
     token_auth: tunnel.token_auth === true,
     server_id: serverId || void 0,
     server_name: serverName || void 0,
@@ -2941,6 +3846,7 @@ function parser(tunnel) {
     capabilities,
     exec_path: webTTYHasCapability(capabilities, "exec") ? tunnelLabels["rstream.webtty.exec.path"] ?? "/" : void 0,
     fs_path: webTTYHasCapability(capabilities, "fs") ? tunnelLabels["rstream.webtty.fs.path"] ?? "/fs" : void 0,
+    fs_backend: webTTYHasCapability(capabilities, "fs") ? tunnelLabels["rstream.webtty.fs.backend"] ?? "webdav" : void 0,
     fs_mode: webTTYHasCapability(capabilities, "fs") ? tunnelLabels["rstream.webtty.fs.mode"] ?? "read-write" : void 0,
     os_family: tunnelLabels["rstream.webtty.os_family"],
     arch: tunnelLabels["rstream.webtty.arch"],
@@ -2956,8 +3862,54 @@ function parser(tunnel) {
   if (!parsed.success) return null;
   return parsed.data;
 }
-function parseWebTTYServers(tunnels) {
-  return tunnels.map((tunnel) => parser(tunnel)).filter((server) => server !== null);
+function parseWebTTYServers(tunnels, options = {}) {
+  return tunnels.map((tunnel) => parser(tunnel, options.includePrivate === true)).filter((server) => server !== null);
+}
+function webTTYTransportMetadata(value) {
+  if (value === void 0) return {};
+  const parsed = webttyTransportSchema.safeParse(value);
+  if (!parsed.success)
+    return {
+      transport_error: "Server advertises an invalid WebTTY transport."
+    };
+  return { transport: parsed.data };
+}
+function resolveWebTTYServerTransport(server, requested) {
+  if (server.transport_error !== void 0)
+    throw new Error(server.transport_error);
+  const advertised = server.transport ?? (server.tunnel_type === "datagram" ? "webtransport" : void 0);
+  if (advertised !== void 0 && server.tunnel_type !== void 0 && advertised === "webtransport" !== (server.tunnel_type === "datagram")) {
+    throw new Error(
+      `Server WebTTY transport ${advertised} conflicts with tunnel type ${server.tunnel_type}.`
+    );
+  }
+  if (advertised === "webtransport" && server.http_version !== void 0 && server.http_version !== "h3") {
+    throw new Error("Server WebTransport requires HTTP/3.");
+  }
+  if (requested !== void 0 && advertised !== void 0 && requested !== advertised) {
+    throw new Error(
+      `Requested WebTTY transport ${requested} conflicts with server transport ${advertised}.`
+    );
+  }
+  return advertised ?? requested ?? "websocket";
+}
+function resolveWebTTYBrowserEndpoint(server) {
+  const transport = resolveWebTTYServerTransport(server);
+  if (transport === "plain")
+    throw new Error(
+      "Plain WebTTY requires a native client; this server cannot be opened in a browser."
+    );
+  if (server.publish === false || server.host === "")
+    throw new Error(
+      "Private WebTTY requires a native client and its rstrm:// address."
+    );
+  const url = new URL(
+    `${transport === "webtransport" ? "https" : "wss"}://${server.host}`
+  );
+  const execPath = server.exec_path?.trim();
+  if (execPath)
+    url.pathname = execPath.startsWith("/") ? execPath : `/${execPath}`;
+  return { url: url.toString(), transport };
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
@@ -3015,7 +3967,9 @@ function parseWebTTYServers(tunnels) {
   resolveTunnelsCredentials,
   resolveTunnelsEngine,
   resolveTunnelsRegion,
+  resolveWebTTYBrowserEndpoint,
   resolveWebTTYControlRequestParamsSchema,
+  resolveWebTTYServerTransport,
   signWebhookPayload,
   streamEndpointSchema,
   streamEntrySchema,
@@ -3025,6 +3979,7 @@ function parseWebTTYServers(tunnels) {
   streamWebTTYMetadataSchema,
   tunnelFilterSchema,
   turnCredentialModeSchema,
+  validateTURNCredentialsRequest,
   webTTYCapabilitiesSchema,
   webTTYContextMetadataSchema,
   webTTYControlRequestSchema,
@@ -3045,5 +4000,6 @@ function parseWebTTYServers(tunnels) {
   webTTYTransportSchema,
   webhookEventsSchema,
   webttyServerSchema,
+  webttyTransportSchema,
   wsEventsSchema
 });