@rstreamlabs/tunnels 3.9.0 → 3.10.1

package/dist/index.mjs

@@ -48,7 +48,7 @@ import {
   webTTYTransportSchema,
   webhookEventsSchema,
   wsEventsSchema
-} from "./chunk-3VBF43NB.mjs";
+} from "./chunk-DQN5T7CI.mjs";
 
 // src/auth-resource.ts
 import { createAuthTokenParamsSchema } from "@rstreamlabs/rstream/auth-token";
@@ -230,6 +230,113 @@ var RstreamClientsResource = class {
 
 // src/resolution.ts
 import { DEFAULT_API_URL } from "@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 request = new Request(input, init);
+    const headers = new Headers(request.headers);
+    headers.set("Connection", "close");
+    const lifetime = requestLifetime(
+      [parent, request.signal],
+      timeoutMilliseconds
+    );
+    try {
+      lifetime.signal.throwIfAborted();
+      const response = await fetch2(input, {
+        ...init,
+        redirect: "manual",
+        headers,
+        signal: lifetime.signal
+      });
+      const responseBody = response.body === null ? null : await readBoundedText(response, maxResponseBytes);
+      return new Response(responseBody, {
+        headers: Object.fromEntries(response.headers.entries()),
+        status: response.status,
+        statusText: response.statusText
+      });
+    } finally {
+      lifetime.close();
+    }
+  };
+}
+
+// src/resolution.ts
 import { getTunnelsProjectEngine } from "@rstreamlabs/rstream";
 import { isTokenCredentials } from "@rstreamlabs/rstream";
 import { readEnvironment } from "@rstreamlabs/rstream";
@@ -363,6 +470,12 @@ async function resolveManagedTunnelsProject(config) {
     );
   }
   const controlPlane = new RstreamClient({
+    fetch: createBoundedControlPlaneFetch(
+      1e4,
+      void 0,
+      globalThis.fetch,
+      1024 * 1024
+    ),
     apiUrl: resolveTunnelsAPIURL(config.apiUrl),
     controlPlaneHeaders: config.controlPlaneHeaders,
     credentials
@@ -404,61 +517,230 @@ var RstreamTunnelsResource = class {
 
 // src/tunnels.ts
 import { getTunnelsProjectEngine as getTunnelsProjectEngine2 } from "@rstreamlabs/rstream";
-import { isClientCredentials as isClientCredentials4 } from "@rstreamlabs/rstream";
-import { readEnvironment as readEnvironment2 } from "@rstreamlabs/rstream";
-
-// src/turn.ts
-import { isClientCredentials as isClientCredentials2 } from "@rstreamlabs/rstream";
-import { isTokenCredentials as isTokenCredentials2 } from "@rstreamlabs/rstream";
-import { RstreamClient as RstreamClient2 } from "@rstreamlabs/rstream";
-import { turnCredentialsSchema } from "@rstreamlabs/rstream/turn";
+import { createClientCredentialsToken as createClientCredentialsToken3 } from "@rstreamlabs/rstream";
 
-// 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);
+// src/engine-http.ts
+import { RstreamHTTPError } from "@rstreamlabs/rstream";
+import { z } from "zod";
+var discoverySchema = z.object({
+  version: z.literal(1),
+  projectEndpoint: z.string(),
+  mtlsApiUrl: z.string(),
+  capabilities: z.array(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 ??= import("./node-engine-http-6DJZZEME.mjs").then(
+        ({ NodeEngineHTTP }) => new NodeEngineHTTP({
+          ca: this.options.tls?.ca,
+          rejectUnauthorized: true
+        })
+      );
+      return (await this.anonymous).fetch;
+    }
+    this.authenticated ??= import("./node-engine-http-6DJZZEME.mjs").then(
+      ({ NodeEngineHTTP }) => new NodeEngineHTTP(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 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 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 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 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 RstreamHTTPError)) this.discovery = void 0;
+      throw error;
     } finally {
       lifetime.close();
     }
-  };
-}
+  }
+};
+
+// src/tunnels.ts
+import { isClientCredentials as isClientCredentials3 } from "@rstreamlabs/rstream";
+import { readEnvironment as readEnvironment2 } from "@rstreamlabs/rstream";
 
 // src/turn.ts
-import * as z from "zod";
+import { isClientCredentials as isClientCredentials2 } from "@rstreamlabs/rstream";
+import { createClientCredentialsToken as createClientCredentialsToken2 } from "@rstreamlabs/rstream";
+import { isTokenCredentials as isTokenCredentials2 } from "@rstreamlabs/rstream";
+import { RstreamClient as RstreamClient2 } from "@rstreamlabs/rstream";
+import { RstreamHTTPError as RstreamHTTPError2 } from "@rstreamlabs/rstream";
+import { turnCredentialsSchema } from "@rstreamlabs/rstream/turn";
+import * as z2 from "zod";
 import crypto from "crypto";
 var defaultTURNPort = 3478;
 var defaultTURNSPort = 5349;
@@ -467,20 +749,31 @@ var maxTURNCredentialTTLSeconds = 60 * 60;
 var maxTURNKeyringBytes = 8 * 1024;
 var defaultAPIRequestTimeoutMilliseconds = 1e4;
 var maxAPIRequestTimeoutMilliseconds = 6e4;
-var turnTokenClaimsSchema = z.object({
-  exp: z.number().int().optional(),
-  iat: z.number().int().optional(),
-  token_endpoint: z.string().regex(/^[0-9a-f]{8}$/i).optional(),
-  tokendpoint: z.string().regex(/^[0-9a-f]{8}$/i).optional(),
-  type: z.enum(["app", "auth", "pat"])
+var turnTokenClaimsSchema = z2.object({
+  permissions: z2.array(z2.string()).nullable().optional(),
+  exp: z2.number().int().optional(),
+  iat: z2.number().int().optional(),
+  token_endpoint: z2.string().regex(/^[A-Za-z0-9_.-]{1,128}$/).optional(),
+  tokendpoint: z2.string().regex(/^[A-Za-z0-9_.-]{1,128}$/).optional(),
+  type: z2.enum(["app", "auth", "pat"])
 });
-var turnCredentialModeSchema = z.enum(["api", "app", "pat"]);
+var turnCredentialModeSchema = z2.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) {
@@ -595,14 +888,27 @@ function requireOption(value, message) {
   }
   throw new Error(message);
 }
-function resolveMode(credentials, mode) {
-  if (mode !== void 0) {
-    return turnCredentialModeSchema.parse(mode);
-  }
-  if (isClientCredentials2(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 = isTokenCredentials2(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 (isClientCredentials2(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();
@@ -622,7 +928,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 {
@@ -645,6 +951,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 = crypto.createPrivateKey({
       key: Buffer.from(value, "hex"),
@@ -680,19 +990,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);
@@ -706,10 +1035,20 @@ async function createAPITURNCredentials(options) {
     options.requestTimeoutMilliseconds
   );
   const params = createAPITURNCredentialsParams(options.ttlSeconds);
-  const request = options.fetch ?? createBoundedControlPlaneFetch(requestTimeoutMilliseconds);
+  const request = createBoundedControlPlaneFetch(
+    requestTimeoutMilliseconds,
+    options.signal,
+    options.fetch
+  );
   const client = new RstreamClient2({
+    controlPlaneHeaders: options.controlPlaneHeaders,
     apiUrl: options.apiUrl,
-    credentials: options.credentials,
+    credentials: isClientCredentials2(options.credentials) ? {
+      token: createClientCredentialsToken2(options.credentials, {
+        expiresInSeconds: 60,
+        claims: { permissions: ["turn.credentials.create"] }
+      }).token
+    } : options.credentials,
     fetch: request
   });
   if (projectId) {
@@ -753,6 +1092,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
   );
@@ -762,6 +1103,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.");
   }
@@ -806,6 +1149,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.");
@@ -838,26 +1183,41 @@ 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);
@@ -891,6 +1251,8 @@ async function createTURNCredentials(options) {
     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,
@@ -914,25 +1276,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 RstreamHTTPError2)
+    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 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 (isTokenCredentials2(left) && isTokenCredentials2(right))
+    return left.token === right.token;
+  return isClientCredentials2(left) && isClientCredentials2(right) && left.clientId === right.clientId && left.clientSecret === right.clientSecret;
+}
 
 // src/turn-resource.ts
-import { isClientCredentials as isClientCredentials3 } from "@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 && isClientCredentials3(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,
@@ -1101,24 +1577,45 @@ 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 ?? readEnvironment2().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(
@@ -1188,6 +1685,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
     );
@@ -1263,7 +1764,7 @@ var RstreamTunnelsClient = class {
     if (!credentials) {
       return void 0;
     }
-    if (!isClientCredentials4(credentials)) {
+    if (!isClientCredentials3(credentials)) {
       return credentials.token;
     }
     const tokenParams = await this.getEngineAuthTokenParams();
@@ -1272,26 +1773,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" && isClientCredentials3(credentials) ? createClientCredentialsToken3(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();
   }
 };
@@ -1388,6 +1900,8 @@ function hasWatchOnlyPermissions(permissions) {
   );
 }
 var Watch = class {
+  abort = new AbortController();
+  closeStream;
   connection = null;
   connectionState = "preparing";
   config;
@@ -1402,7 +1916,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,
@@ -1441,10 +1980,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));
@@ -1454,6 +2022,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;
@@ -1469,8 +2040,8 @@ var Watch = class {
 };
 
 // src/webtty.ts
-import * as z2 from "zod";
-var osFamilySchema = z2.enum([
+import * as z3 from "zod";
+var osFamilySchema = z3.enum([
   "linux",
   "macos",
   "windows",
@@ -1478,55 +2049,55 @@ var osFamilySchema = z2.enum([
   "openbsd",
   "freebsd"
 ]);
-var webttyCapabilitySchema = z2.enum(["exec", "fs"]);
-var webttyFSModeSchema = z2.enum(["read-write", "read-only"]);
-var webttyEncryptionPolicySchema = z2.enum([
+var webttyCapabilitySchema = z3.enum(["exec", "fs"]);
+var webttyFSModeSchema = z3.enum(["read-write", "read-only"]);
+var webttyEncryptionPolicySchema = z3.enum([
   "disabled",
   "explicit_key",
   "workspace_managed"
 ]);
-var webttyTransportSchema = z2.enum([
+var webttyTransportSchema = z3.enum([
   "plain",
   "websocket",
   "webtransport"
 ]);
-var webttyServerSchema = z2.object({
-  tunnel_id: z2.string(),
-  tunnel_name: z2.string().optional(),
-  target: z2.string().optional(),
-  rstream_url: z2.string().optional(),
-  status: z2.string().optional(),
-  publish: z2.boolean().optional(),
-  workspace_id: z2.string().optional(),
-  project_id: z2.string().optional(),
-  tunnel_protocol: z2.enum(["http", "webtty"]).optional(),
-  tunnel_type: z2.enum(["bytestream", "datagram"]).optional(),
-  http_version: z2.string().optional(),
+var webttyServerSchema = z3.object({
+  tunnel_id: z3.string(),
+  tunnel_name: z3.string().optional(),
+  target: z3.string().optional(),
+  rstream_url: z3.string().optional(),
+  status: z3.string().optional(),
+  publish: z3.boolean().optional(),
+  workspace_id: z3.string().optional(),
+  project_id: z3.string().optional(),
+  tunnel_protocol: z3.enum(["http", "webtty"]).optional(),
+  tunnel_type: z3.enum(["bytestream", "datagram"]).optional(),
+  http_version: z3.string().optional(),
   transport: webttyTransportSchema.optional(),
-  transport_error: z2.string().optional(),
-  managed: z2.boolean(),
-  host: z2.string(),
-  token_auth: z2.boolean(),
-  server_id: z2.string().optional(),
-  server_name: z2.string().optional(),
-  host_key_id: z2.string().optional(),
-  e2e: z2.enum(["disabled", "required"]).optional(),
-  client_proof: z2.enum(["none", "required"]).optional(),
+  transport_error: z3.string().optional(),
+  managed: z3.boolean(),
+  host: z3.string(),
+  token_auth: z3.boolean(),
+  server_id: z3.string().optional(),
+  server_name: z3.string().optional(),
+  host_key_id: z3.string().optional(),
+  e2e: z3.enum(["disabled", "required"]).optional(),
+  client_proof: z3.enum(["none", "required"]).optional(),
   encryption_policy: webttyEncryptionPolicySchema.optional(),
-  capabilities: z2.array(webttyCapabilitySchema).optional(),
-  exec_path: z2.string().optional(),
-  fs_path: z2.string().optional(),
+  capabilities: z3.array(webttyCapabilitySchema).optional(),
+  exec_path: z3.string().optional(),
+  fs_path: z3.string().optional(),
   fs_mode: webttyFSModeSchema.optional(),
-  fs_backend: z2.enum(["webdav", "webrtc"]).optional(),
+  fs_backend: z3.enum(["webdav", "webrtc"]).optional(),
   os_family: osFamilySchema.optional(),
-  arch: z2.string().optional(),
-  os_id: z2.string().optional(),
-  os_version_id: z2.string().optional(),
-  os_version_codename: z2.string().optional(),
-  os_pretty_name: z2.string().optional(),
-  kernel_release: z2.string().optional(),
-  hostname: z2.string().optional(),
-  labels: z2.record(z2.string(), z2.string().optional()).optional()
+  arch: z3.string().optional(),
+  os_id: z3.string().optional(),
+  os_version_id: z3.string().optional(),
+  os_version_codename: z3.string().optional(),
+  os_pretty_name: z3.string().optional(),
+  kernel_release: z3.string().optional(),
+  hostname: z3.string().optional(),
+  labels: z3.record(z3.string(), z3.string().optional()).optional()
 });
 function isWebTTYCapability(value) {
   return webttyCapabilitySchema.safeParse(value).success;
@@ -1724,6 +2295,7 @@ export {
   streamWebTTYMetadataSchema,
   tunnelFilterSchema,
   turnCredentialModeSchema,
+  validateTURNCredentialsRequest,
   webTTYCapabilitiesSchema,
   webTTYContextMetadataSchema,
   webTTYControlRequestSchema,