@rstreamlabs/tunnels 3.8.0 → 3.8.2

package/README.md

@@ -161,14 +161,19 @@ const turn = await createTURNCredentials({
     clientSecret: process.env.RSTREAM_CLIENT_SECRET!,
   },
   projectEndpoint: "project-endpoint",
-  clusterDomain: "cluster.example.rstream.test",
+  turnDomain: "regional.example.rstream.test",
+  turnRealm: "global.example.rstream.test",
   ttlSeconds: 600,
 });
 ```
 
 TURN credentials are short-lived. `ttlSeconds` is optional, defaults to 600 for
 local derivation, and must be an integer between 1 and 3600 seconds. PAT-backed
-credentials are additionally capped by the PAT expiration.
+credentials are additionally capped by the PAT expiration. `turnDomain` is the
+relay hostname used in ICE URLs; `turnRealm` is the authentication scope used
+for key derivation. A managed client resolves both values from project
+metadata. Lower-level local derivation keeps them explicit because a regional
+relay can belong to a different global realm.
 
 ## Webhooks
 

package/dist/index.d.mts

@@ -239,26 +239,30 @@ interface CreateAPITURNCredentialsOptions {
     ttlSeconds?: number;
 }
 interface CreatePATTURNCredentialsOptions {
-    clusterDomain: string;
+    clusterDomain?: string;
     now?: Date | number;
     projectEndpoint: string;
     token: string;
-    tokenEndpoint: string;
+    tokenEndpoint?: string;
     ttlSeconds?: number;
+    turnDomain?: string;
     turnPort?: number;
+    turnRealm?: string;
     turnsPort?: number;
 }
 interface CreateAPPTURNCredentialsOptions {
     apiUrl?: string;
     clientId: string;
     clientSecret: string;
-    clusterDomain: string;
+    clusterDomain?: string;
     keyringBaseUrl?: string;
     now?: Date | number;
     projectEndpoint: string;
     serverPublicKeyHex?: string;
     ttlSeconds?: number;
+    turnDomain?: string;
     turnPort?: number;
+    turnRealm?: string;
     turnsPort?: number;
 }
 interface CreateTURNCredentialsOptions {
@@ -275,7 +279,9 @@ interface CreateTURNCredentialsOptions {
     serverPublicKeyHex?: string;
     tokenEndpoint?: string;
     ttlSeconds?: number;
+    turnDomain?: string;
     turnPort?: number;
+    turnRealm?: string;
     turnsPort?: number;
 }
 declare function createAPITURNCredentials(options: CreateAPITURNCredentialsOptions): Promise<TURNCredentials>;
@@ -5782,6 +5788,12 @@ declare class RstreamTunnelsClient {
     get controlPlaneCredentials(): RstreamCredentials | undefined;
     get projectEndpoint(): string | undefined;
     getEngine(): Promise<string>;
+    getTURNTarget(): Promise<{
+        turnDomain: string;
+        turnPort: number;
+        turnRealm: string;
+        turnsPort: number;
+    }>;
     private getManagedProject;
     private getEngineAuthTokenParams;
     getEngineAuthTokenTarget(): Promise<{

package/dist/index.d.ts

@@ -239,26 +239,30 @@ interface CreateAPITURNCredentialsOptions {
     ttlSeconds?: number;
 }
 interface CreatePATTURNCredentialsOptions {
-    clusterDomain: string;
+    clusterDomain?: string;
     now?: Date | number;
     projectEndpoint: string;
     token: string;
-    tokenEndpoint: string;
+    tokenEndpoint?: string;
     ttlSeconds?: number;
+    turnDomain?: string;
     turnPort?: number;
+    turnRealm?: string;
     turnsPort?: number;
 }
 interface CreateAPPTURNCredentialsOptions {
     apiUrl?: string;
     clientId: string;
     clientSecret: string;
-    clusterDomain: string;
+    clusterDomain?: string;
     keyringBaseUrl?: string;
     now?: Date | number;
     projectEndpoint: string;
     serverPublicKeyHex?: string;
     ttlSeconds?: number;
+    turnDomain?: string;
     turnPort?: number;
+    turnRealm?: string;
     turnsPort?: number;
 }
 interface CreateTURNCredentialsOptions {
@@ -275,7 +279,9 @@ interface CreateTURNCredentialsOptions {
     serverPublicKeyHex?: string;
     tokenEndpoint?: string;
     ttlSeconds?: number;
+    turnDomain?: string;
     turnPort?: number;
+    turnRealm?: string;
     turnsPort?: number;
 }
 declare function createAPITURNCredentials(options: CreateAPITURNCredentialsOptions): Promise<TURNCredentials>;
@@ -5782,6 +5788,12 @@ declare class RstreamTunnelsClient {
     get controlPlaneCredentials(): RstreamCredentials | undefined;
     get projectEndpoint(): string | undefined;
     getEngine(): Promise<string>;
+    getTURNTarget(): Promise<{
+        turnDomain: string;
+        turnPort: number;
+        turnRealm: string;
+        turnsPort: number;
+    }>;
     private getManagedProject;
     private getEngineAuthTokenParams;
     getEngineAuthTokenTarget(): Promise<{

package/dist/index.js

@@ -1766,9 +1766,9 @@ var RstreamTunnelsResource = class {
 };
 
 // src/tunnels.ts
-var import_rstream11 = require("@rstreamlabs/rstream");
 var import_rstream12 = require("@rstreamlabs/rstream");
 var import_rstream13 = require("@rstreamlabs/rstream");
+var import_rstream14 = require("@rstreamlabs/rstream");
 
 // src/turn.ts
 var import_rstream8 = require("@rstreamlabs/rstream");
@@ -1781,6 +1781,7 @@ var defaultTURNPort = 3478;
 var defaultTURNSPort = 5349;
 var defaultTURNCredentialTTLSeconds = 10 * 60;
 var maxTURNCredentialTTLSeconds = 60 * 60;
+var maxTURNKeyringBytes = 8 * 1024;
 var turnTokenClaimsSchema = z8.object({
   exp: z8.number().int().optional(),
   iat: z8.number().int().optional(),
@@ -1830,14 +1831,14 @@ function normalizeTURNPort(port) {
 function normalizeTURNSPort(port) {
   return normalizePort(port, defaultTURNSPort, "TURNS port");
 }
-function createTURNURLs(clusterDomain, turnPort, turnsPort) {
+function createTURNURLs(turnDomain, turnPort, turnsPort) {
   const normalizedTURNPort = normalizeTURNPort(turnPort);
   const normalizedTURNSPort = normalizeTURNSPort(turnsPort);
   return [
-    `turn:${clusterDomain}:${normalizedTURNPort}?transport=udp`,
-    `turn:${clusterDomain}:${normalizedTURNPort}?transport=tcp`,
-    `turns:${clusterDomain}:${normalizedTURNSPort}?transport=udp`,
-    `turns:${clusterDomain}:${normalizedTURNSPort}?transport=tcp`
+    `turn:${turnDomain}:${normalizedTURNPort}?transport=udp`,
+    `turn:${turnDomain}:${normalizedTURNPort}?transport=tcp`,
+    `turns:${turnDomain}:${normalizedTURNSPort}?transport=udp`,
+    `turns:${turnDomain}:${normalizedTURNSPort}?transport=tcp`
   ];
 }
 function parseTURNTokenClaims(token) {
@@ -1909,6 +1910,75 @@ function resolveMode(credentials, mode) {
   }
   return "api";
 }
+async function readBoundedTURNKeyring(reader, chunks = [], size = 0) {
+  const result = await reader.read();
+  if (result.done) {
+    return Buffer.concat(chunks, size).toString("utf8");
+  }
+  const nextSize = size + result.value.byteLength;
+  if (nextSize > maxTURNKeyringBytes) {
+    await reader.cancel();
+    throw new Error("TURN keyring response exceeds the 8 KiB limit.");
+  }
+  return await readBoundedTURNKeyring(
+    reader,
+    [...chunks, result.value],
+    nextSize
+  );
+}
+function parseTURNServerPublicKeyHex(value) {
+  const normalized = value.trim();
+  if (normalized.length === 0 || normalized.length % 2 !== 0 || !/^[0-9a-f]+$/i.test(normalized)) {
+    throw new Error("TURN keyring must contain hexadecimal DER key material.");
+  }
+  try {
+    const key = import_crypto.default.createPublicKey({
+      key: Buffer.from(normalized, "hex"),
+      format: "der",
+      type: "spki"
+    });
+    if (key.asymmetricKeyType !== "ec") {
+      throw new Error("TURN keyring public key must be an EC key.");
+    }
+    return key;
+  } catch (error) {
+    if (error instanceof Error && error.message.startsWith("TURN keyring")) {
+      throw error;
+    }
+    throw new Error("TURN keyring contains an invalid DER public key.", {
+      cause: error
+    });
+  }
+}
+function parseAPPPrivateKey(value) {
+  try {
+    const key = import_crypto.default.createPrivateKey({
+      key: Buffer.from(value, "hex"),
+      format: "der",
+      type: "pkcs8"
+    });
+    if (key.asymmetricKeyType !== "ec") {
+      throw new Error("TURN APP client secret must contain an EC private key.");
+    }
+    return key;
+  } catch (error) {
+    if (error instanceof Error && error.message.startsWith("TURN APP")) {
+      throw error;
+    }
+    throw new Error("TURN APP client secret contains an invalid private key.", {
+      cause: error
+    });
+  }
+}
+function requireMatchingCurve(privateKey, publicKey) {
+  const privateCurve = privateKey.asymmetricKeyDetails?.namedCurve;
+  const publicCurve = publicKey.asymmetricKeyDetails?.namedCurve;
+  if (!privateCurve || privateCurve !== publicCurve) {
+    throw new Error(
+      "TURN APP client and server keys must use the same named curve."
+    );
+  }
+}
 async function loadTURNServerPublicKeyHex(clusterDomain, options) {
   const configuredKey = normalizeOptionalString2(options.keyringBaseUrl);
   const keyringBaseURL = configuredKey ?? normalizeOptionalString2(options.apiUrl) ?? "https://rstream.io";
@@ -1916,11 +1986,19 @@ async function loadTURNServerPublicKeyHex(clusterDomain, options) {
     `/keyrings/turn/${clusterDomain}.spki.der.hex`,
     keyringBaseURL
   );
-  const response = await fetch(url);
+  const response = await fetch(url, { redirect: "manual" });
+  if (response.status >= 300 && response.status < 400) {
+    throw new Error(
+      "TURN keyring request was redirected; redirects are refused."
+    );
+  }
   if (!response.ok) {
-    throw new Error("Failed to load TURN keyring.");
+    throw new Error(`TURN keyring request returned HTTP ${response.status}.`);
   }
-  return (await response.text()).trim();
+  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);
@@ -1952,9 +2030,14 @@ async function createAPITURNCredentials(options) {
   );
 }
 function createPATTURNCredentials(options) {
-  const clusterDomain = normalizeClusterDomain(options.clusterDomain);
-  if (!clusterDomain) {
-    throw new Error("Cluster domain is required for TURN PAT mode.");
+  const legacyDomain = normalizeClusterDomain(options.clusterDomain);
+  const turnDomain = normalizeClusterDomain(options.turnDomain) ?? legacyDomain;
+  const turnRealm = normalizeClusterDomain(options.turnRealm) ?? legacyDomain;
+  if (!turnDomain) {
+    throw new Error("TURN domain is required for TURN PAT mode.");
+  }
+  if (!turnRealm) {
+    throw new Error("TURN realm is required for TURN PAT mode.");
   }
   const projectEndpoint = normalizeOptionalString2(options.projectEndpoint);
   if (!projectEndpoint) {
@@ -1968,12 +2051,19 @@ function createPATTURNCredentials(options) {
   if (claims.type !== "pat") {
     throw new Error("TURN PAT mode requires a PAT token.");
   }
-  const tokenEndpoint = normalizeOptionalString2(options.tokenEndpoint);
+  const claimsTokenEndpoint = normalizeOptionalString2(
+    claims.token_endpoint ?? claims.tokendpoint
+  );
+  const configuredTokenEndpoint = normalizeOptionalString2(
+    options.tokenEndpoint
+  );
+  const tokenEndpoint = configuredTokenEndpoint ?? claimsTokenEndpoint;
   if (!tokenEndpoint) {
-    throw new Error("Token endpoint is required for TURN PAT mode.");
+    throw new Error(
+      "TURN PAT mode requires a PAT token carrying a token endpoint."
+    );
   }
-  const claimsTokenEndpoint = claims.token_endpoint ?? claims.tokendpoint;
-  if (claimsTokenEndpoint !== void 0 && claimsTokenEndpoint !== tokenEndpoint) {
+  if (configuredTokenEndpoint !== void 0 && claimsTokenEndpoint !== void 0 && claimsTokenEndpoint !== configuredTokenEndpoint) {
     throw new Error("Token endpoint does not match the PAT token.");
   }
   const now = normalizeNow(options.now);
@@ -1986,7 +2076,7 @@ function createPATTURNCredentials(options) {
     import_crypto.default.hkdfSync(
       "sha256",
       tokenHash,
-      Buffer.from(clusterDomain, "utf8"),
+      Buffer.from(turnRealm, "utf8"),
       Buffer.from("turn-pat-v1", "utf8"),
       32
     )
@@ -1995,14 +2085,19 @@ function createPATTURNCredentials(options) {
   return import_turn.turnCredentialsSchema.parse({
     credential,
     ttl,
-    urls: createTURNURLs(clusterDomain, options.turnPort, options.turnsPort),
+    urls: createTURNURLs(turnDomain, options.turnPort, options.turnsPort),
     username
   });
 }
 async function createAPPTURNCredentials(options) {
-  const clusterDomain = normalizeClusterDomain(options.clusterDomain);
-  if (!clusterDomain) {
-    throw new Error("Cluster domain is required for TURN APP mode.");
+  const legacyDomain = normalizeClusterDomain(options.clusterDomain);
+  const turnDomain = normalizeClusterDomain(options.turnDomain) ?? legacyDomain;
+  const turnRealm = normalizeClusterDomain(options.turnRealm) ?? legacyDomain;
+  if (!turnDomain) {
+    throw new Error("TURN domain is required for TURN APP mode.");
+  }
+  if (!turnRealm) {
+    throw new Error("TURN realm is required for TURN APP mode.");
   }
   const projectEndpoint = normalizeOptionalString2(options.projectEndpoint);
   if (!projectEndpoint) {
@@ -2019,17 +2114,10 @@ async function createAPPTURNCredentials(options) {
   const ttlSeconds = normalizeTTLSeconds(options.ttlSeconds);
   const exp = normalizeNow(options.now) + ttlSeconds;
   const username = `v1:${exp}:app:${projectEndpoint}:${clientId}`;
-  const clientPrivateKey = import_crypto.default.createPrivateKey({
-    key: Buffer.from(clientSecret, "hex"),
-    format: "der",
-    type: "pkcs8"
-  });
-  const serverPublicKeyHex = normalizeOptionalString2(options.serverPublicKeyHex) ?? await loadTURNServerPublicKeyHex(clusterDomain, options);
-  const serverPublicKey = import_crypto.default.createPublicKey({
-    key: Buffer.from(serverPublicKeyHex, "hex"),
-    format: "der",
-    type: "spki"
-  });
+  const clientPrivateKey = parseAPPPrivateKey(clientSecret);
+  const serverPublicKeyHex = normalizeOptionalString2(options.serverPublicKeyHex) ?? await loadTURNServerPublicKeyHex(turnRealm, options);
+  const serverPublicKey = parseTURNServerPublicKeyHex(serverPublicKeyHex);
+  requireMatchingCurve(clientPrivateKey, serverPublicKey);
   const sharedSecret = import_crypto.default.diffieHellman({
     privateKey: clientPrivateKey,
     publicKey: serverPublicKey
@@ -2038,7 +2126,7 @@ async function createAPPTURNCredentials(options) {
     import_crypto.default.hkdfSync(
       "sha256",
       sharedSecret,
-      Buffer.from(clusterDomain, "utf8"),
+      Buffer.from(turnRealm, "utf8"),
       Buffer.from("turn-app-v1", "utf8"),
       32
     )
@@ -2047,7 +2135,7 @@ async function createAPPTURNCredentials(options) {
   return import_turn.turnCredentialsSchema.parse({
     credential,
     ttl: ttlSeconds,
-    urls: createTURNURLs(clusterDomain, options.turnPort, options.turnsPort),
+    urls: createTURNURLs(turnDomain, options.turnPort, options.turnsPort),
     username
   });
 }
@@ -2070,28 +2158,31 @@ async function createTURNCredentials(options) {
       ttlSeconds: options.ttlSeconds
     });
   }
-  const clusterDomain = normalizeClusterDomain(options.clusterDomain) ?? (projectEndpoint && options.engine ? deriveClusterDomainFromEngine(projectEndpoint, options.engine) : void 0);
+  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)) {
       throw new Error("A PAT token is required for TURN PAT mode.");
     }
     return createPATTURNCredentials({
-      clusterDomain: requireOption(
-        clusterDomain,
-        "Cluster domain is required for TURN PAT mode."
-      ),
       now: options.now,
       projectEndpoint: requireOption(
         projectEndpoint,
         "Project endpoint is required for TURN PAT mode."
       ),
       token: credentials.token,
-      tokenEndpoint: requireOption(
-        normalizeOptionalString2(options.tokenEndpoint),
-        "Token endpoint is required for TURN PAT mode."
-      ),
+      tokenEndpoint: options.tokenEndpoint,
       ttlSeconds: options.ttlSeconds,
+      turnDomain: requireOption(
+        turnDomain,
+        "TURN domain is required for TURN PAT mode."
+      ),
       turnPort: options.turnPort,
+      turnRealm: requireOption(
+        turnRealm,
+        "TURN realm is required for TURN PAT mode."
+      ),
       turnsPort: options.turnsPort
     });
   }
@@ -2102,10 +2193,6 @@ async function createTURNCredentials(options) {
     apiUrl: options.apiUrl,
     clientId: credentials.clientId,
     clientSecret: credentials.clientSecret,
-    clusterDomain: requireOption(
-      clusterDomain,
-      "Cluster domain is required for TURN APP mode."
-    ),
     keyringBaseUrl: options.keyringBaseUrl,
     now: options.now,
     projectEndpoint: requireOption(
@@ -2114,24 +2201,36 @@ async function createTURNCredentials(options) {
     ),
     serverPublicKeyHex: options.serverPublicKeyHex,
     ttlSeconds: options.ttlSeconds,
+    turnDomain: requireOption(
+      turnDomain,
+      "TURN domain is required for TURN APP mode."
+    ),
     turnPort: options.turnPort,
+    turnRealm: requireOption(
+      turnRealm,
+      "TURN realm is required for TURN APP mode."
+    ),
     turnsPort: options.turnsPort
   });
 }
 
 // src/turn-resource.ts
+var import_rstream11 = require("@rstreamlabs/rstream");
 var RstreamTURNResource = class {
   client;
   constructor(client) {
     this.client = client;
   }
   async createCredentials(options = {}) {
-    const engine = options.engine ?? (options.clusterDomain === void 0 ? await this.client.getEngine().catch(() => void 0) : void 0);
+    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);
     return await createTURNCredentials({
       apiUrl: options.apiUrl ?? this.client.apiUrl,
       clusterDomain: options.clusterDomain,
       controlPlaneCredentials: options.controlPlaneCredentials ?? this.client.controlPlaneCredentials,
-      credentials: options.credentials ?? this.client.credentials,
+      credentials,
       engine,
       keyringBaseUrl: options.keyringBaseUrl,
       mode: options.mode,
@@ -2141,8 +2240,10 @@ var RstreamTURNResource = class {
       serverPublicKeyHex: options.serverPublicKeyHex,
       tokenEndpoint: options.tokenEndpoint,
       ttlSeconds: options.ttlSeconds,
-      turnPort: options.turnPort,
-      turnsPort: options.turnsPort
+      turnDomain: options.turnDomain ?? target?.turnDomain,
+      turnPort: options.turnPort ?? target?.turnPort,
+      turnRealm: options.turnRealm ?? target?.turnRealm,
+      turnsPort: options.turnsPort ?? target?.turnsPort
     });
   }
 };
@@ -2323,7 +2424,7 @@ var RstreamTunnelsClient = class {
       this.config?.projectEndpoint
     );
     if (region !== void 0) {
-      if (normalizeOptionalString3(this.config?.engine) !== void 0 || (0, import_rstream13.readEnvironment)().engine !== void 0) {
+      if (normalizeOptionalString3(this.config?.engine) !== void 0 || (0, import_rstream14.readEnvironment)().engine !== void 0) {
         throw new Error(
           "Region selection cannot be combined with an explicit engine override."
         );
@@ -2335,17 +2436,17 @@ var RstreamTunnelsClient = class {
       }
       const project = await this.getManagedProject();
       if (project !== void 0) {
-        const engine = (0, import_rstream11.getTunnelsProjectEngine)(project, region);
+        const engine = (0, import_rstream12.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_rstream13.readEnvironment)().engine === void 0) {
+    if (projectEndpoint !== void 0 && normalizeOptionalString3(this.config?.engine) === void 0 && (0, import_rstream14.readEnvironment)().engine === void 0) {
       const project = await this.getManagedProject();
       if (project !== void 0) {
-        const engine = (0, import_rstream11.getTunnelsProjectEngine)(project);
+        const engine = (0, import_rstream12.getTunnelsProjectEngine)(project);
         if (engine) {
           return normalizeEngineAddress(engine);
         }
@@ -2364,6 +2465,27 @@ var RstreamTunnelsClient = class {
       region: this.config?.region
     });
   }
+  async getTURNTarget() {
+    const project = await this.getManagedProject();
+    if (project === void 0) {
+      throw new Error(
+        "Managed project endpoint is required to resolve the TURN target."
+      );
+    }
+    const turnDomain = project.turnDomain?.trim() || project.domain.trim();
+    const turnRealm = project.turnRealm?.trim();
+    if (!turnRealm) {
+      throw new Error(
+        "Managed project metadata does not expose the TURN realm; use API credential mode or provide turnRealm explicitly."
+      );
+    }
+    return {
+      turnDomain,
+      turnPort: project.turnPort,
+      turnRealm,
+      turnsPort: project.turnsPort
+    };
+  }
   async getManagedProject() {
     const projectEndpoint = normalizeOptionalString3(
       this.config?.projectEndpoint
@@ -2440,7 +2562,7 @@ var RstreamTunnelsClient = class {
     if (!credentials) {
       return void 0;
     }
-    if (!(0, import_rstream12.isClientCredentials)(credentials)) {
+    if (!(0, import_rstream13.isClientCredentials)(credentials)) {
       return credentials.token;
     }
     const tokenParams = await this.getEngineAuthTokenParams();

package/dist/index.mjs

@@ -404,7 +404,7 @@ var RstreamTunnelsResource = class {
 
 // src/tunnels.ts
 import { getTunnelsProjectEngine as getTunnelsProjectEngine2 } from "@rstreamlabs/rstream";
-import { isClientCredentials as isClientCredentials3 } from "@rstreamlabs/rstream";
+import { isClientCredentials as isClientCredentials4 } from "@rstreamlabs/rstream";
 import { readEnvironment as readEnvironment2 } from "@rstreamlabs/rstream";
 
 // src/turn.ts
@@ -418,6 +418,7 @@ var defaultTURNPort = 3478;
 var defaultTURNSPort = 5349;
 var defaultTURNCredentialTTLSeconds = 10 * 60;
 var maxTURNCredentialTTLSeconds = 60 * 60;
+var maxTURNKeyringBytes = 8 * 1024;
 var turnTokenClaimsSchema = z.object({
   exp: z.number().int().optional(),
   iat: z.number().int().optional(),
@@ -467,14 +468,14 @@ function normalizeTURNPort(port) {
 function normalizeTURNSPort(port) {
   return normalizePort(port, defaultTURNSPort, "TURNS port");
 }
-function createTURNURLs(clusterDomain, turnPort, turnsPort) {
+function createTURNURLs(turnDomain, turnPort, turnsPort) {
   const normalizedTURNPort = normalizeTURNPort(turnPort);
   const normalizedTURNSPort = normalizeTURNSPort(turnsPort);
   return [
-    `turn:${clusterDomain}:${normalizedTURNPort}?transport=udp`,
-    `turn:${clusterDomain}:${normalizedTURNPort}?transport=tcp`,
-    `turns:${clusterDomain}:${normalizedTURNSPort}?transport=udp`,
-    `turns:${clusterDomain}:${normalizedTURNSPort}?transport=tcp`
+    `turn:${turnDomain}:${normalizedTURNPort}?transport=udp`,
+    `turn:${turnDomain}:${normalizedTURNPort}?transport=tcp`,
+    `turns:${turnDomain}:${normalizedTURNSPort}?transport=udp`,
+    `turns:${turnDomain}:${normalizedTURNSPort}?transport=tcp`
   ];
 }
 function parseTURNTokenClaims(token) {
@@ -546,6 +547,75 @@ function resolveMode(credentials, mode) {
   }
   return "api";
 }
+async function readBoundedTURNKeyring(reader, chunks = [], size = 0) {
+  const result = await reader.read();
+  if (result.done) {
+    return Buffer.concat(chunks, size).toString("utf8");
+  }
+  const nextSize = size + result.value.byteLength;
+  if (nextSize > maxTURNKeyringBytes) {
+    await reader.cancel();
+    throw new Error("TURN keyring response exceeds the 8 KiB limit.");
+  }
+  return await readBoundedTURNKeyring(
+    reader,
+    [...chunks, result.value],
+    nextSize
+  );
+}
+function parseTURNServerPublicKeyHex(value) {
+  const normalized = value.trim();
+  if (normalized.length === 0 || normalized.length % 2 !== 0 || !/^[0-9a-f]+$/i.test(normalized)) {
+    throw new Error("TURN keyring must contain hexadecimal DER key material.");
+  }
+  try {
+    const key = crypto.createPublicKey({
+      key: Buffer.from(normalized, "hex"),
+      format: "der",
+      type: "spki"
+    });
+    if (key.asymmetricKeyType !== "ec") {
+      throw new Error("TURN keyring public key must be an EC key.");
+    }
+    return key;
+  } catch (error) {
+    if (error instanceof Error && error.message.startsWith("TURN keyring")) {
+      throw error;
+    }
+    throw new Error("TURN keyring contains an invalid DER public key.", {
+      cause: error
+    });
+  }
+}
+function parseAPPPrivateKey(value) {
+  try {
+    const key = crypto.createPrivateKey({
+      key: Buffer.from(value, "hex"),
+      format: "der",
+      type: "pkcs8"
+    });
+    if (key.asymmetricKeyType !== "ec") {
+      throw new Error("TURN APP client secret must contain an EC private key.");
+    }
+    return key;
+  } catch (error) {
+    if (error instanceof Error && error.message.startsWith("TURN APP")) {
+      throw error;
+    }
+    throw new Error("TURN APP client secret contains an invalid private key.", {
+      cause: error
+    });
+  }
+}
+function requireMatchingCurve(privateKey, publicKey) {
+  const privateCurve = privateKey.asymmetricKeyDetails?.namedCurve;
+  const publicCurve = publicKey.asymmetricKeyDetails?.namedCurve;
+  if (!privateCurve || privateCurve !== publicCurve) {
+    throw new Error(
+      "TURN APP client and server keys must use the same named curve."
+    );
+  }
+}
 async function loadTURNServerPublicKeyHex(clusterDomain, options) {
   const configuredKey = normalizeOptionalString2(options.keyringBaseUrl);
   const keyringBaseURL = configuredKey ?? normalizeOptionalString2(options.apiUrl) ?? "https://rstream.io";
@@ -553,11 +623,19 @@ async function loadTURNServerPublicKeyHex(clusterDomain, options) {
     `/keyrings/turn/${clusterDomain}.spki.der.hex`,
     keyringBaseURL
   );
-  const response = await fetch(url);
+  const response = await fetch(url, { redirect: "manual" });
+  if (response.status >= 300 && response.status < 400) {
+    throw new Error(
+      "TURN keyring request was redirected; redirects are refused."
+    );
+  }
   if (!response.ok) {
-    throw new Error("Failed to load TURN keyring.");
+    throw new Error(`TURN keyring request returned HTTP ${response.status}.`);
   }
-  return (await response.text()).trim();
+  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);
@@ -589,9 +667,14 @@ async function createAPITURNCredentials(options) {
   );
 }
 function createPATTURNCredentials(options) {
-  const clusterDomain = normalizeClusterDomain(options.clusterDomain);
-  if (!clusterDomain) {
-    throw new Error("Cluster domain is required for TURN PAT mode.");
+  const legacyDomain = normalizeClusterDomain(options.clusterDomain);
+  const turnDomain = normalizeClusterDomain(options.turnDomain) ?? legacyDomain;
+  const turnRealm = normalizeClusterDomain(options.turnRealm) ?? legacyDomain;
+  if (!turnDomain) {
+    throw new Error("TURN domain is required for TURN PAT mode.");
+  }
+  if (!turnRealm) {
+    throw new Error("TURN realm is required for TURN PAT mode.");
   }
   const projectEndpoint = normalizeOptionalString2(options.projectEndpoint);
   if (!projectEndpoint) {
@@ -605,12 +688,19 @@ function createPATTURNCredentials(options) {
   if (claims.type !== "pat") {
     throw new Error("TURN PAT mode requires a PAT token.");
   }
-  const tokenEndpoint = normalizeOptionalString2(options.tokenEndpoint);
+  const claimsTokenEndpoint = normalizeOptionalString2(
+    claims.token_endpoint ?? claims.tokendpoint
+  );
+  const configuredTokenEndpoint = normalizeOptionalString2(
+    options.tokenEndpoint
+  );
+  const tokenEndpoint = configuredTokenEndpoint ?? claimsTokenEndpoint;
   if (!tokenEndpoint) {
-    throw new Error("Token endpoint is required for TURN PAT mode.");
+    throw new Error(
+      "TURN PAT mode requires a PAT token carrying a token endpoint."
+    );
   }
-  const claimsTokenEndpoint = claims.token_endpoint ?? claims.tokendpoint;
-  if (claimsTokenEndpoint !== void 0 && claimsTokenEndpoint !== tokenEndpoint) {
+  if (configuredTokenEndpoint !== void 0 && claimsTokenEndpoint !== void 0 && claimsTokenEndpoint !== configuredTokenEndpoint) {
     throw new Error("Token endpoint does not match the PAT token.");
   }
   const now = normalizeNow(options.now);
@@ -623,7 +713,7 @@ function createPATTURNCredentials(options) {
     crypto.hkdfSync(
       "sha256",
       tokenHash,
-      Buffer.from(clusterDomain, "utf8"),
+      Buffer.from(turnRealm, "utf8"),
       Buffer.from("turn-pat-v1", "utf8"),
       32
     )
@@ -632,14 +722,19 @@ function createPATTURNCredentials(options) {
   return turnCredentialsSchema.parse({
     credential,
     ttl,
-    urls: createTURNURLs(clusterDomain, options.turnPort, options.turnsPort),
+    urls: createTURNURLs(turnDomain, options.turnPort, options.turnsPort),
     username
   });
 }
 async function createAPPTURNCredentials(options) {
-  const clusterDomain = normalizeClusterDomain(options.clusterDomain);
-  if (!clusterDomain) {
-    throw new Error("Cluster domain is required for TURN APP mode.");
+  const legacyDomain = normalizeClusterDomain(options.clusterDomain);
+  const turnDomain = normalizeClusterDomain(options.turnDomain) ?? legacyDomain;
+  const turnRealm = normalizeClusterDomain(options.turnRealm) ?? legacyDomain;
+  if (!turnDomain) {
+    throw new Error("TURN domain is required for TURN APP mode.");
+  }
+  if (!turnRealm) {
+    throw new Error("TURN realm is required for TURN APP mode.");
   }
   const projectEndpoint = normalizeOptionalString2(options.projectEndpoint);
   if (!projectEndpoint) {
@@ -656,17 +751,10 @@ async function createAPPTURNCredentials(options) {
   const ttlSeconds = normalizeTTLSeconds(options.ttlSeconds);
   const exp = normalizeNow(options.now) + ttlSeconds;
   const username = `v1:${exp}:app:${projectEndpoint}:${clientId}`;
-  const clientPrivateKey = crypto.createPrivateKey({
-    key: Buffer.from(clientSecret, "hex"),
-    format: "der",
-    type: "pkcs8"
-  });
-  const serverPublicKeyHex = normalizeOptionalString2(options.serverPublicKeyHex) ?? await loadTURNServerPublicKeyHex(clusterDomain, options);
-  const serverPublicKey = crypto.createPublicKey({
-    key: Buffer.from(serverPublicKeyHex, "hex"),
-    format: "der",
-    type: "spki"
-  });
+  const clientPrivateKey = parseAPPPrivateKey(clientSecret);
+  const serverPublicKeyHex = normalizeOptionalString2(options.serverPublicKeyHex) ?? await loadTURNServerPublicKeyHex(turnRealm, options);
+  const serverPublicKey = parseTURNServerPublicKeyHex(serverPublicKeyHex);
+  requireMatchingCurve(clientPrivateKey, serverPublicKey);
   const sharedSecret = crypto.diffieHellman({
     privateKey: clientPrivateKey,
     publicKey: serverPublicKey
@@ -675,7 +763,7 @@ async function createAPPTURNCredentials(options) {
     crypto.hkdfSync(
       "sha256",
       sharedSecret,
-      Buffer.from(clusterDomain, "utf8"),
+      Buffer.from(turnRealm, "utf8"),
       Buffer.from("turn-app-v1", "utf8"),
       32
     )
@@ -684,7 +772,7 @@ async function createAPPTURNCredentials(options) {
   return turnCredentialsSchema.parse({
     credential,
     ttl: ttlSeconds,
-    urls: createTURNURLs(clusterDomain, options.turnPort, options.turnsPort),
+    urls: createTURNURLs(turnDomain, options.turnPort, options.turnsPort),
     username
   });
 }
@@ -707,28 +795,31 @@ async function createTURNCredentials(options) {
       ttlSeconds: options.ttlSeconds
     });
   }
-  const clusterDomain = normalizeClusterDomain(options.clusterDomain) ?? (projectEndpoint && options.engine ? deriveClusterDomainFromEngine(projectEndpoint, options.engine) : void 0);
+  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 (!isTokenCredentials2(credentials)) {
       throw new Error("A PAT token is required for TURN PAT mode.");
     }
     return createPATTURNCredentials({
-      clusterDomain: requireOption(
-        clusterDomain,
-        "Cluster domain is required for TURN PAT mode."
-      ),
       now: options.now,
       projectEndpoint: requireOption(
         projectEndpoint,
         "Project endpoint is required for TURN PAT mode."
       ),
       token: credentials.token,
-      tokenEndpoint: requireOption(
-        normalizeOptionalString2(options.tokenEndpoint),
-        "Token endpoint is required for TURN PAT mode."
-      ),
+      tokenEndpoint: options.tokenEndpoint,
       ttlSeconds: options.ttlSeconds,
+      turnDomain: requireOption(
+        turnDomain,
+        "TURN domain is required for TURN PAT mode."
+      ),
       turnPort: options.turnPort,
+      turnRealm: requireOption(
+        turnRealm,
+        "TURN realm is required for TURN PAT mode."
+      ),
       turnsPort: options.turnsPort
     });
   }
@@ -739,10 +830,6 @@ async function createTURNCredentials(options) {
     apiUrl: options.apiUrl,
     clientId: credentials.clientId,
     clientSecret: credentials.clientSecret,
-    clusterDomain: requireOption(
-      clusterDomain,
-      "Cluster domain is required for TURN APP mode."
-    ),
     keyringBaseUrl: options.keyringBaseUrl,
     now: options.now,
     projectEndpoint: requireOption(
@@ -751,24 +838,36 @@ async function createTURNCredentials(options) {
     ),
     serverPublicKeyHex: options.serverPublicKeyHex,
     ttlSeconds: options.ttlSeconds,
+    turnDomain: requireOption(
+      turnDomain,
+      "TURN domain is required for TURN APP mode."
+    ),
     turnPort: options.turnPort,
+    turnRealm: requireOption(
+      turnRealm,
+      "TURN realm is required for TURN APP mode."
+    ),
     turnsPort: options.turnsPort
   });
 }
 
 // src/turn-resource.ts
+import { isClientCredentials as isClientCredentials3 } from "@rstreamlabs/rstream";
 var RstreamTURNResource = class {
   client;
   constructor(client) {
     this.client = client;
   }
   async createCredentials(options = {}) {
-    const engine = options.engine ?? (options.clusterDomain === void 0 ? await this.client.getEngine().catch(() => void 0) : void 0);
+    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);
     return await createTURNCredentials({
       apiUrl: options.apiUrl ?? this.client.apiUrl,
       clusterDomain: options.clusterDomain,
       controlPlaneCredentials: options.controlPlaneCredentials ?? this.client.controlPlaneCredentials,
-      credentials: options.credentials ?? this.client.credentials,
+      credentials,
       engine,
       keyringBaseUrl: options.keyringBaseUrl,
       mode: options.mode,
@@ -778,8 +877,10 @@ var RstreamTURNResource = class {
       serverPublicKeyHex: options.serverPublicKeyHex,
       tokenEndpoint: options.tokenEndpoint,
       ttlSeconds: options.ttlSeconds,
-      turnPort: options.turnPort,
-      turnsPort: options.turnsPort
+      turnDomain: options.turnDomain ?? target?.turnDomain,
+      turnPort: options.turnPort ?? target?.turnPort,
+      turnRealm: options.turnRealm ?? target?.turnRealm,
+      turnsPort: options.turnsPort ?? target?.turnsPort
     });
   }
 };
@@ -1001,6 +1102,27 @@ var RstreamTunnelsClient = class {
       region: this.config?.region
     });
   }
+  async getTURNTarget() {
+    const project = await this.getManagedProject();
+    if (project === void 0) {
+      throw new Error(
+        "Managed project endpoint is required to resolve the TURN target."
+      );
+    }
+    const turnDomain = project.turnDomain?.trim() || project.domain.trim();
+    const turnRealm = project.turnRealm?.trim();
+    if (!turnRealm) {
+      throw new Error(
+        "Managed project metadata does not expose the TURN realm; use API credential mode or provide turnRealm explicitly."
+      );
+    }
+    return {
+      turnDomain,
+      turnPort: project.turnPort,
+      turnRealm,
+      turnsPort: project.turnsPort
+    };
+  }
   async getManagedProject() {
     const projectEndpoint = normalizeOptionalString3(
       this.config?.projectEndpoint
@@ -1077,7 +1199,7 @@ var RstreamTunnelsClient = class {
     if (!credentials) {
       return void 0;
     }
-    if (!isClientCredentials3(credentials)) {
+    if (!isClientCredentials4(credentials)) {
       return credentials.token;
     }
     const tokenParams = await this.getEngineAuthTokenParams();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rstreamlabs/tunnels",
-  "version": "3.8.0",
+  "version": "3.8.2",
   "description": "JS/TS SDK for the rstream Engine API and tunnel runtime APIs.",
   "author": "@uartnet <hello@rstream.io>",
   "repository": {
@@ -47,7 +47,7 @@
     "typescript-config": "*"
   },
   "dependencies": {
-    "@rstreamlabs/rstream": "3.8.0",
+    "@rstreamlabs/rstream": "3.8.1",
     "@types/jsonwebtoken": "^9.0.10",
     "jsonwebtoken": "^9.0.3",
     "zod": "^4.4.3"