@rstreamlabs/tunnels 1.0.7 → 1.0.9

package/dist/index.js

@@ -65,8 +65,10 @@ __export(index_exports, {
   listClientsResponseSchema: () => listClientsResponseSchema,
   listTunnelsParamsSchema: () => listTunnelsParamsSchema,
   listTunnelsResponseSchema: () => listTunnelsResponseSchema,
+  normalizeEngineAddress: () => normalizeEngineAddress,
   parseWebTTYServers: () => parseWebTTYServers,
   resolveControlPlaneCredentials: () => resolveControlPlaneCredentials,
+  resolveManagedTunnelsProject: () => resolveManagedTunnelsProject,
   resolveTunnelsAPIURL: () => resolveTunnelsAPIURL,
   resolveTunnelsCredentials: () => resolveTunnelsCredentials,
   resolveTunnelsEngine: () => resolveTunnelsEngine,
@@ -90,9 +92,9 @@ var import_rstream = require("@rstreamlabs/rstream");
 var z = __toESM(require("zod"));
 var StringFilter = z.union([
   z.string(),
-  z.object({ exact: z.string() }),
-  z.object({ oneof: z.array(z.string()) }),
-  z.object({ regex: z.string() })
+  z.object({ exact: z.string() }).strict(),
+  z.object({ oneof: z.array(z.string()) }).strict(),
+  z.object({ regex: z.string() }).strict()
 ]);
 function transform(field) {
   if (field instanceof z.ZodOptional) {
@@ -126,7 +128,7 @@ function select(base) {
     return [key, z.boolean().optional()];
   });
   const shape = Object.fromEntries(entries);
-  return z.object(shape);
+  return z.object(shape).strict();
 }
 
 // src/tunnel.ts
@@ -160,8 +162,7 @@ var tunnelSchema = z2.object({
   tls_alpns: z2.array(z2.string()).optional(),
   tls_min_version: z2.string().optional(),
   tls_ciphers: z2.array(z2.string()).optional(),
-  mtls: z2.boolean().optional(),
-  mtls_ca_cert_pem: z2.string().optional(),
+  mtls_auth: z2.boolean().optional(),
   http_version: z2.enum(["http/1.1", "h2", "h2c", "h3"]).optional(),
   http_use_tls: z2.boolean().optional(),
   upstream_tls: z2.boolean().optional(),
@@ -219,7 +220,7 @@ var authTokenTunnelsScopesSchema = z3.object({
           creation_date: true
         })
       ).optional()
-    })
+    }).strict()
   ]).optional(),
   // Scopes for connecting to tunnels
   connect: z3.union([
@@ -231,7 +232,7 @@ var authTokenTunnelsScopesSchema = z3.object({
           path: z3.string().optional()
         })
       ).optional()
-    })
+    }).strict()
   ]).optional(),
   // Scopes for listing tunnels
   list: z3.union([
@@ -239,14 +240,29 @@ var authTokenTunnelsScopesSchema = z3.object({
     z3.object({
       filters: filters(tunnelSchema).optional(),
       select: select(tunnelSchema).optional()
-    })
+    }).strict()
   ]).optional()
+}).strict().superRefine((scopes, ctx) => {
+  if (scopes.create === void 0 && scopes.connect === void 0 && scopes.list === void 0) {
+    ctx.addIssue({
+      code: z3.ZodIssueCode.custom,
+      message: "At least one tunnel scope action is required."
+    });
+  }
 });
 var authTokenScopesSchema = z3.object({
   tunnels: authTokenTunnelsScopesSchema.optional()
   // Scopes related to tunnels
+}).strict().superRefine((scopes, ctx) => {
+  if (scopes.tunnels === void 0) {
+    ctx.addIssue({
+      code: z3.ZodIssueCode.custom,
+      message: "Tunnel scopes are required.",
+      path: ["tunnels"]
+    });
+  }
 });
-var authTokenTunnelGrantSchema = z3.object({
+var authTokenTunnelGrantLeafSchema = z3.object({
   workspaces: z3.array(nonEmptyStringSchema).min(1).optional(),
   projects: z3.array(nonEmptyStringSchema).min(1).optional(),
   scopes: authTokenScopesSchema.optional()
@@ -258,11 +274,25 @@ var authTokenTunnelGrantSchema = z3.object({
       path: ["projects"]
     });
   }
+  if (grant.workspaces === void 0 && grant.projects === void 0 && grant.scopes === void 0) {
+    ctx.addIssue({
+      code: z3.ZodIssueCode.custom,
+      message: "A grant must target workspaces, projects, or scopes.",
+      path: ["workspaces"]
+    });
+  }
 });
+var authTokenTunnelGrantSchema = z3.lazy(
+  () => z3.union([
+    authTokenTunnelGrantLeafSchema,
+    z3.object({ AND: z3.array(authTokenTunnelGrantSchema).min(1) }).strict(),
+    z3.object({ OR: z3.array(authTokenTunnelGrantSchema).min(1) }).strict()
+  ])
+);
 var authTokenCommonSchema = {
   aud: z3.union([z3.string(), z3.array(z3.string())]).optional(),
   exp: z3.number().optional(),
-  tunnelsGrants: z3.array(authTokenTunnelGrantSchema).optional(),
+  tunnelsGrants: authTokenTunnelGrantSchema.optional(),
   iat: z3.number().optional(),
   iss: z3.string().optional(),
   jti: z3.string().optional(),
@@ -281,6 +311,7 @@ var authTokenSchema = z3.union([
   }).strict(),
   z3.object({
     type: z3.literal("pat"),
+    tokendpoint: z3.string().optional(),
     token_endpoint: z3.string().optional(),
     ...authTokenCommonSchema
   }).strict(),
@@ -293,10 +324,9 @@ var authTokenSchema = z3.union([
 ]);
 var tokenSchema = authTokenSchema;
 var createAuthTokenParamsSchema = z3.object({
-  expires_in: z3.number().default(60),
-  // 1 minute
+  expires_in: z3.number().int().min(1).max(3600).default(60),
   scopes: authTokenScopesSchema.optional(),
-  tunnelsGrants: z3.array(authTokenTunnelGrantSchema).optional(),
+  tunnelsGrants: authTokenTunnelGrantSchema.optional(),
   metadata: z3.unknown().optional()
   // Additional metadata
 }).strict().superRefine((params, ctx) => {
@@ -307,6 +337,13 @@ var createAuthTokenParamsSchema = z3.object({
       path: ["tunnelsGrants"]
     });
   }
+  if (params.scopes === void 0 && params.tunnelsGrants === void 0) {
+    ctx.addIssue({
+      code: z3.ZodIssueCode.custom,
+      message: "Explicit scopes or tunnelsGrants are required.",
+      path: ["scopes"]
+    });
+  }
 });
 var createAuthTokenResponseSchema = z3.object({
   token: z3.string()
@@ -327,18 +364,38 @@ var RstreamAuthResource = class {
       );
     }
     const engine = options?.engine ?? await this.client.getEngine().catch(() => void 0);
+    const scopedOptions = await this.resolveScopeOptions(params, options);
     return createAuthTokenFromClientCredentials(credentials, params, {
-      engine
+      engine,
+      ...scopedOptions
     });
   }
+  async resolveScopeOptions(params, options) {
+    const tokenParams = createAuthTokenParamsSchema.parse(params);
+    if (options?.projectScoped === false) {
+      return options ?? {};
+    }
+    if (options?.projectId !== void 0 || options?.workspaceId !== void 0) {
+      return options;
+    }
+    if (tokenParams.scopes === void 0 && !tunnelGrantsNeedDefaultTarget(tokenParams.tunnelsGrants)) {
+      return options ?? {};
+    }
+    const target = await this.client.getEngineAuthTokenTarget();
+    return {
+      ...options,
+      projectId: target.projects?.[0],
+      workspaceId: target.workspaces?.[0]
+    };
+  }
 };
 function createAuthTokenFromClientCredentials(credentials, params, options) {
-  const tokenParams = createAuthTokenParamsSchema.parse(params ?? {});
+  const tokenParams = createAuthTokenParamsSchema.parse(params);
   const payload = {
     metadata: {
       engine: options?.engine
     },
-    tunnelsGrants: normalizeAuthTokenTunnelGrants(tokenParams),
+    tunnelsGrants: normalizeAuthTokenTunnelGrants(tokenParams, options),
     permissions: null
   };
   const { token } = (0, import_rstream.createClientCredentialsToken)(credentials, {
@@ -347,19 +404,92 @@ function createAuthTokenFromClientCredentials(credentials, params, options) {
   });
   return { token };
 }
-function normalizeAuthTokenTunnelGrants(params) {
-  if (!params) {
-    return void 0;
-  }
+function normalizeAuthTokenTunnelGrants(params, options) {
   const tunnelsGrants = params.tunnelsGrants;
   if (tunnelsGrants !== void 0) {
-    return [...tunnelsGrants];
+    return applyDefaultTunnelGrantTarget(tunnelsGrants, options);
   }
   if (params.scopes) {
-    return [{ scopes: params.scopes }];
+    return { ...normalizeTunnelGrantTarget(options), scopes: params.scopes };
   }
   return void 0;
 }
+function applyDefaultTunnelGrantTarget(grants, options, inheritedTarget = false) {
+  if (options?.projectScoped === false) {
+    return grants;
+  }
+  if ("AND" in grants) {
+    const branchHasTarget = inheritedTarget || grants.AND.some((grant) => tunnelGrantTreeHasTarget(grant));
+    return {
+      AND: grants.AND.map(
+        (grant) => applyDefaultTunnelGrantTarget(grant, options, branchHasTarget)
+      )
+    };
+  }
+  if ("OR" in grants) {
+    return {
+      OR: grants.OR.map(
+        (grant) => applyDefaultTunnelGrantTarget(grant, options, inheritedTarget)
+      )
+    };
+  }
+  if (grants.scopes === void 0 || tunnelGrantHasTarget(grants) || inheritedTarget) {
+    return grants;
+  }
+  return { ...normalizeTunnelGrantTarget(options), scopes: grants.scopes };
+}
+function tunnelGrantsNeedDefaultTarget(grants, inheritedTarget = false) {
+  if (grants === void 0) {
+    return false;
+  }
+  if ("AND" in grants) {
+    const branchHasTarget = inheritedTarget || grants.AND.some((grant) => tunnelGrantTreeHasTarget(grant));
+    return grants.AND.some(
+      (grant) => tunnelGrantsNeedDefaultTarget(grant, branchHasTarget)
+    );
+  }
+  if ("OR" in grants) {
+    return grants.OR.some(
+      (grant) => tunnelGrantsNeedDefaultTarget(grant, inheritedTarget)
+    );
+  }
+  return grants.scopes !== void 0 && !tunnelGrantHasTarget(grants) && !inheritedTarget;
+}
+function tunnelGrantHasTarget(grant) {
+  return grant.projects !== void 0 || grant.workspaces !== void 0;
+}
+function tunnelGrantTreeHasTarget(grants) {
+  if ("AND" in grants) {
+    return grants.AND.some((grant) => tunnelGrantTreeHasTarget(grant));
+  }
+  if ("OR" in grants) {
+    return grants.OR.some((grant) => tunnelGrantTreeHasTarget(grant));
+  }
+  return tunnelGrantHasTarget(grants);
+}
+function normalizeTunnelGrantTarget(options) {
+  const projectId = normalizeOptionalString(options?.projectId);
+  const workspaceId = normalizeOptionalString(options?.workspaceId);
+  if (projectId !== void 0 && workspaceId !== void 0) {
+    throw new Error("Use either projectId or workspaceId, not both.");
+  }
+  if (projectId !== void 0) {
+    return { projects: [projectId] };
+  }
+  if (workspaceId !== void 0) {
+    return { workspaces: [workspaceId] };
+  }
+  if (options?.projectScoped === false) {
+    return {};
+  }
+  throw new Error(
+    "Project ID or workspace ID is required when using scope-only tunnel grants."
+  );
+}
+function normalizeOptionalString(value) {
+  const normalized = value?.trim();
+  return normalized ? normalized : void 0;
+}
 
 // src/client.ts
 var z4 = __toESM(require("zod"));
@@ -400,6 +530,13 @@ var listClientsParamsSchema = z4.object({
 var listClientsResponseSchema = z4.array(clientSchema);
 
 // src/clients-resource.ts
+function clientPathId(id) {
+  const normalized = id.trim();
+  if (!normalized) {
+    throw new Error("Client ID is required.");
+  }
+  return encodeURIComponent(normalized);
+}
 var RstreamClientsResource = class {
   client;
   constructor(client) {
@@ -413,9 +550,12 @@ var RstreamClientsResource = class {
     return listClientsResponseSchema.parse(response);
   }
   async get(id) {
-    const response = await this.client.request(`/clients/${id}`, {
-      method: "GET"
-    });
+    const response = await this.client.request(
+      `/clients/${clientPathId(id)}`,
+      {
+        method: "GET"
+      }
+    );
     return clientSchema.parse(response);
   }
 };
@@ -563,7 +703,7 @@ var routedTunnelSchema = z5.object({
   httpUseTls: z5.boolean().optional(),
   upstreamTls: z5.boolean().optional(),
   tokenAuth: z5.boolean().optional(),
-  mtls: z5.boolean().optional()
+  mtls_auth: z5.boolean().optional()
 });
 var routingSchema = z5.discriminatedUnion("decision", [
   z5.object({ decision: z5.literal("routed"), tunnel: routedTunnelSchema }),
@@ -805,7 +945,7 @@ var engineOpenApiDocument = {
   info: {
     title: "rstream Engine API",
     version: "1.0.0",
-    description: "Operational data-plane API exposed by rstream-engine. This surface is scoped to the authenticated engine or project endpoint and covers live clients, live tunnels, and state-change streams."
+    description: "Operational Engine API exposed by rstream-engine. This surface is scoped to the authenticated engine or project endpoint and covers live clients, live tunnels, and state-change streams."
   },
   servers: [
     {
@@ -831,12 +971,6 @@ var engineOpenApiDocument = {
         scheme: "bearer",
         bearerFormat: "rstream token",
         description: "Preferred authentication mechanism. Send an OAuth-issued rstream access token or compatible rstream credential in Authorization: Bearer <token>."
-      },
-      queryToken: {
-        type: "apiKey",
-        in: "query",
-        name: "rstream.token",
-        description: "Fallback authentication mechanism for transports where setting Authorization is impractical. Prefer bearerAuth whenever possible."
       }
     },
     parameters: {
@@ -956,7 +1090,7 @@ var engineOpenApiDocument = {
         summary: "List visible engine clients.",
         operationId: "list_engine_clients",
         parameters: [{ $ref: "#/components/parameters/ListClientsParams" }],
-        security: [{ bearerAuth: [] }, { queryToken: [] }],
+        security: [{ bearerAuth: [] }],
         responses: {
           "200": jsonArrayResponse(
             "Visible clients.",
@@ -975,7 +1109,7 @@ var engineOpenApiDocument = {
         summary: "List visible engine tunnels.",
         operationId: "list_engine_tunnels",
         parameters: [{ $ref: "#/components/parameters/ListTunnelsParams" }],
-        security: [{ bearerAuth: [] }, { queryToken: [] }],
+        security: [{ bearerAuth: [] }],
         responses: {
           "200": jsonArrayResponse(
             "Visible tunnels. Fine-grained list scopes may filter objects and project fields.",
@@ -995,7 +1129,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: [] }, { queryToken: [] }],
+        security: [{ bearerAuth: [] }],
         responses: {
           "200": streamResponse(
             "SSE stream. Each event is emitted as a data line containing a JSON Event object."
@@ -1014,7 +1148,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: [] }, { queryToken: [] }],
+        security: [{ bearerAuth: [] }],
         responses: {
           "101": {
             description: "WebSocket connection accepted. Frames contain JSON Event objects."
@@ -1042,22 +1176,37 @@ var import_rstream4 = require("@rstreamlabs/rstream");
 var import_rstream5 = require("@rstreamlabs/rstream");
 var import_rstream6 = require("@rstreamlabs/rstream");
 var import_rstream7 = require("@rstreamlabs/rstream");
-var import_jsonwebtoken = __toESM(require("jsonwebtoken"));
 function trimOptionalString(value) {
   const normalized = value?.trim();
   return normalized ? normalized : void 0;
 }
-function getEngineFromToken(token) {
-  if (!token) {
-    return void 0;
+var dnsLabelPattern = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/i;
+function validateHostname(hostname) {
+  if (!hostname || hostname.length > 253 || hostname.includes("..")) {
+    return false;
   }
-  const parsed = authTokenSchema.safeParse(
-    import_jsonwebtoken.default.decode(token, { complete: false })
-  );
-  if (!parsed.success) {
-    return void 0;
+  return hostname.split(".").every((label) => label === "localhost" || dnsLabelPattern.test(label));
+}
+function normalizeEngineAddress(engine) {
+  const normalized = engine.trim();
+  if (!normalized || /^[a-z][a-z0-9+.-]*:\/\//i.test(normalized) || /[/?#@\\\s]/.test(normalized)) {
+    throw new Error("Engine must be a host[:port] value.");
+  }
+  const explicitPort = normalized.match(/:(\d+)$/)?.[1];
+  const url = new URL(`https://${normalized}`);
+  if (url.username || url.password || url.pathname !== "/" || url.search || url.hash) {
+    throw new Error("Engine must be a host[:port] value.");
+  }
+  if (!validateHostname(url.hostname)) {
+    throw new Error("Engine must use a valid hostname.");
+  }
+  if (explicitPort) {
+    const port = Number(explicitPort);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+      throw new Error("Engine port must be an integer between 1 and 65535.");
+    }
   }
-  return trimOptionalString(parsed.data.metadata?.engine);
+  return `${url.hostname.toLowerCase()}${explicitPort ? `:${explicitPort}` : ""}`;
 }
 function resolveTunnelsAPIURL(apiUrl) {
   return trimOptionalString(apiUrl) ?? (0, import_rstream6.readEnvironment)().apiUrl ?? import_rstream3.DEFAULT_API_URL;
@@ -1091,48 +1240,61 @@ function resolveControlPlaneCredentials(controlPlaneCredentials, credentials, au
 async function resolveTunnelsEngine(config) {
   const explicitEngine = trimOptionalString(config.engine);
   if (explicitEngine) {
-    return explicitEngine;
+    return normalizeEngineAddress(explicitEngine);
   }
   const environmentEngine = (0, import_rstream6.readEnvironment)().engine;
   if (environmentEngine) {
-    return environmentEngine;
+    return normalizeEngineAddress(environmentEngine);
   }
   const token = trimOptionalString(config.token) ?? ((0, import_rstream5.isTokenCredentials)(config.credentials) ? config.credentials.token : void 0);
-  const tokenEngine = getEngineFromToken(token);
-  if (tokenEngine) {
-    return tokenEngine;
-  }
   const projectEndpoint = trimOptionalString(config.projectEndpoint);
   if (projectEndpoint) {
-    const credentials = resolveControlPlaneCredentials(
-      config.controlPlaneCredentials,
-      config.credentials,
+    const project = await resolveManagedTunnelsProject({
+      ...config,
       token
-    );
-    if (credentials === void 0) {
-      throw new Error(
-        "Control-plane credentials are required to resolve a managed project endpoint."
-      );
-    }
-    const controlPlane = new import_rstream7.RstreamClient({
-      apiUrl: resolveTunnelsAPIURL(config.apiUrl),
-      credentials
     });
-    const project = await controlPlane.tunnels.projects.resolveByEndpoint(projectEndpoint);
     const engine = (0, import_rstream4.getTunnelsProjectEngine)(project);
     if (engine) {
-      return engine;
+      return normalizeEngineAddress(engine);
     }
     throw new Error(
       "Failed to resolve the engine address from the managed tunnels project."
     );
   }
   throw new Error(
-    "Engine URL is not defined. Provide an engine, use RSTREAM_ENGINE, or configure a managed project endpoint with control-plane access."
+    "Engine URL is not defined. Provide an engine, use RSTREAM_ENGINE, or configure a managed project endpoint with Control plane API access."
   );
 }
+async function resolveManagedTunnelsProject(config) {
+  const projectEndpoint = trimOptionalString(config.projectEndpoint);
+  if (!projectEndpoint) {
+    throw new Error("Managed project endpoint is required.");
+  }
+  const credentials = resolveControlPlaneCredentials(
+    config.controlPlaneCredentials,
+    config.credentials,
+    config.token
+  );
+  if (credentials === void 0) {
+    throw new Error(
+      "Control-plane credentials are required to resolve a managed project endpoint."
+    );
+  }
+  const controlPlane = new import_rstream7.RstreamClient({
+    apiUrl: resolveTunnelsAPIURL(config.apiUrl),
+    credentials
+  });
+  return await controlPlane.tunnels.projects.resolveByEndpoint(projectEndpoint);
+}
 
 // src/tunnels-resource.ts
+function tunnelPathId(id) {
+  const normalized = id.trim();
+  if (!normalized) {
+    throw new Error("Tunnel ID is required.");
+  }
+  return encodeURIComponent(normalized);
+}
 var RstreamTunnelsResource = class {
   client;
   constructor(client) {
@@ -1146,15 +1308,20 @@ var RstreamTunnelsResource = class {
     return listTunnelsResponseSchema.parse(response);
   }
   async get(id) {
-    const response = await this.client.request(`/tunnels/${id}`, {
-      method: "GET"
-    });
+    const response = await this.client.request(
+      `/tunnels/${tunnelPathId(id)}`,
+      {
+        method: "GET"
+      }
+    );
     return tunnelSchema.parse(response);
   }
 };
 
 // src/tunnels.ts
 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");
@@ -1165,46 +1332,53 @@ var z8 = __toESM(require("zod"));
 var import_crypto = __toESM(require("crypto"));
 var defaultTURNPort = 3478;
 var defaultTURNSPort = 5349;
-var defaultTURNCredentialTTLSeconds = 24 * 60 * 60;
+var defaultTURNCredentialTTLSeconds = 10 * 60;
+var maxTURNCredentialTTLSeconds = 60 * 60;
 var turnTokenClaimsSchema = z8.object({
-  token_endpoint: z8.string().optional(),
-  type: z8.string()
+  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 turnCredentialModeSchema = z8.enum(["api", "app", "pat"]);
-function normalizeOptionalString(value) {
+function normalizeOptionalString2(value) {
   const normalized = value?.trim();
   return normalized ? normalized : void 0;
 }
 function normalizeClusterDomain(clusterDomain) {
-  const normalized = normalizeOptionalString(clusterDomain);
+  const normalized = normalizeOptionalString2(clusterDomain);
   return normalized?.toLowerCase();
 }
 function normalizeNow(now) {
-  if (now instanceof Date) {
-    return Math.floor(now.getTime() / 1e3);
+  if (now === void 0) {
+    return Math.floor(Date.now() / 1e3);
   }
-  if (typeof now === "number" && Number.isFinite(now)) {
-    return Math.floor(now);
+  const timestamp = now instanceof Date ? now.getTime() / 1e3 : now;
+  if (!Number.isFinite(timestamp)) {
+    throw new Error("TURN timestamp must be finite.");
   }
-  return Math.floor(Date.now() / 1e3);
+  return Math.floor(timestamp);
 }
 function normalizeTTLSeconds(ttlSeconds) {
-  if (typeof ttlSeconds === "number" && Number.isFinite(ttlSeconds) && ttlSeconds > 0) {
-    return Math.floor(ttlSeconds);
+  const ttl = ttlSeconds ?? defaultTURNCredentialTTLSeconds;
+  if (!Number.isInteger(ttl) || ttl < 1 || ttl > maxTURNCredentialTTLSeconds) {
+    throw new Error("TURN TTL must be an integer between 1 and 3600 seconds.");
   }
-  return defaultTURNCredentialTTLSeconds;
+  return ttl;
 }
-function normalizeTURNPort(port) {
-  if (typeof port === "number" && Number.isFinite(port) && port > 0) {
-    return Math.floor(port);
+function normalizePort(port, fallback, name) {
+  const normalized = port ?? fallback;
+  if (!Number.isInteger(normalized) || normalized < 1 || normalized > 65535) {
+    throw new Error(`${name} must be an integer between 1 and 65535.`);
   }
-  return defaultTURNPort;
+  return normalized;
+}
+function normalizeTURNPort(port) {
+  return normalizePort(port, defaultTURNPort, "TURN port");
 }
 function normalizeTURNSPort(port) {
-  if (typeof port === "number" && Number.isFinite(port) && port > 0) {
-    return Math.floor(port);
-  }
-  return defaultTURNSPort;
+  return normalizePort(port, defaultTURNSPort, "TURNS port");
 }
 function createTURNURLs(clusterDomain, turnPort, turnsPort) {
   const normalizedTURNPort = normalizeTURNPort(turnPort);
@@ -1222,16 +1396,32 @@ function parseTURNTokenClaims(token) {
   if (!payloadPart) {
     throw new Error("Invalid token format.");
   }
-  const payload = Buffer.from(payloadPart, "base64url").toString("utf8");
-  const parsed = turnTokenClaimsSchema.safeParse(JSON.parse(payload));
+  let decoded;
+  try {
+    const payload = Buffer.from(payloadPart, "base64url").toString("utf8");
+    decoded = JSON.parse(payload);
+  } catch {
+    throw new Error("Invalid token format.");
+  }
+  const parsed = turnTokenClaimsSchema.safeParse(decoded);
   if (!parsed.success) {
     throw new Error("Invalid token format.");
   }
   return parsed.data;
 }
+function requirePATExpiration(claims, now) {
+  const exp = claims.exp;
+  if (typeof exp !== "number") {
+    throw new Error("TURN PAT mode requires a PAT token with expiration.");
+  }
+  if (exp <= now) {
+    throw new Error("TURN PAT mode requires a non-expired PAT token.");
+  }
+  return exp;
+}
 function deriveClusterDomainFromEngine(projectEndpoint, engine) {
-  const normalizedProjectEndpoint = normalizeOptionalString(projectEndpoint);
-  const normalizedEngine = normalizeOptionalString(engine);
+  const normalizedProjectEndpoint = normalizeOptionalString2(projectEndpoint);
+  const normalizedEngine = normalizeOptionalString2(engine);
   if (!normalizedProjectEndpoint || !normalizedEngine) {
     throw new Error(
       "Failed to derive the cluster domain from the engine address."
@@ -1265,17 +1455,11 @@ function resolveMode(credentials, mode) {
   if ((0, import_rstream8.isClientCredentials)(credentials)) {
     return "app";
   }
-  if ((0, import_rstream9.isTokenCredentials)(credentials)) {
-    const claims = parseTURNTokenClaims(credentials.token);
-    if (claims.type === "pat" && normalizeOptionalString(claims.token_endpoint)) {
-      return "pat";
-    }
-  }
   return "api";
 }
 async function loadTURNServerPublicKeyHex(clusterDomain, options) {
-  const configuredKey = normalizeOptionalString(options.keyringBaseUrl);
-  const keyringBaseURL = configuredKey ?? normalizeOptionalString(options.apiUrl) ?? "https://rstream.io";
+  const configuredKey = normalizeOptionalString2(options.keyringBaseUrl);
+  const keyringBaseURL = configuredKey ?? normalizeOptionalString2(options.apiUrl) ?? "https://rstream.io";
   const url = new URL(
     `/keyrings/turn/${clusterDomain}.spki.der.hex`,
     keyringBaseURL
@@ -1287,8 +1471,8 @@ async function loadTURNServerPublicKeyHex(clusterDomain, options) {
   return (await response.text()).trim();
 }
 async function createAPITURNCredentials(options) {
-  const projectId = normalizeOptionalString(options.projectId);
-  const projectEndpoint = normalizeOptionalString(options.projectEndpoint);
+  const projectId = normalizeOptionalString2(options.projectId);
+  const projectEndpoint = normalizeOptionalString2(options.projectEndpoint);
   if (!projectId && !projectEndpoint) {
     throw new Error(
       "Project ID or project endpoint is required for TURN API mode."
@@ -1315,11 +1499,11 @@ function createPATTURNCredentials(options) {
   if (!clusterDomain) {
     throw new Error("Cluster domain is required for TURN PAT mode.");
   }
-  const projectEndpoint = normalizeOptionalString(options.projectEndpoint);
+  const projectEndpoint = normalizeOptionalString2(options.projectEndpoint);
   if (!projectEndpoint) {
     throw new Error("Project endpoint is required for TURN PAT mode.");
   }
-  const token = normalizeOptionalString(options.token);
+  const token = normalizeOptionalString2(options.token);
   if (!token) {
     throw new Error("Token is required for TURN PAT mode.");
   }
@@ -1327,14 +1511,18 @@ function createPATTURNCredentials(options) {
   if (claims.type !== "pat") {
     throw new Error("TURN PAT mode requires a PAT token.");
   }
-  const tokenEndpoint = normalizeOptionalString(claims.token_endpoint);
+  const tokenEndpoint = normalizeOptionalString2(options.tokenEndpoint);
   if (!tokenEndpoint) {
-    throw new Error(
-      "TURN PAT mode requires a PAT token carrying a token endpoint."
-    );
+    throw new Error("Token endpoint is required for TURN PAT mode.");
+  }
+  const claimsTokenEndpoint = claims.token_endpoint ?? claims.tokendpoint;
+  if (claimsTokenEndpoint !== void 0 && claimsTokenEndpoint !== tokenEndpoint) {
+    throw new Error("Token endpoint does not match the PAT token.");
   }
+  const now = normalizeNow(options.now);
   const ttlSeconds = normalizeTTLSeconds(options.ttlSeconds);
-  const exp = normalizeNow(options.now) + ttlSeconds;
+  const exp = Math.min(now + ttlSeconds, requirePATExpiration(claims, now));
+  const ttl = exp - now;
   const username = `v1:${exp}:pat:${projectEndpoint}:${tokenEndpoint}`;
   const tokenHash = import_crypto.default.createHash("sha256").update(token, "utf8").digest();
   const key = Buffer.from(
@@ -1349,7 +1537,7 @@ function createPATTURNCredentials(options) {
   const credential = import_crypto.default.createHmac("sha256", key).update(username, "utf8").digest("base64");
   return import_rstream11.turnCredentialsSchema.parse({
     credential,
-    ttl: ttlSeconds,
+    ttl,
     urls: createTURNURLs(clusterDomain, options.turnPort, options.turnsPort),
     username
   });
@@ -1359,15 +1547,15 @@ async function createAPPTURNCredentials(options) {
   if (!clusterDomain) {
     throw new Error("Cluster domain is required for TURN APP mode.");
   }
-  const projectEndpoint = normalizeOptionalString(options.projectEndpoint);
+  const projectEndpoint = normalizeOptionalString2(options.projectEndpoint);
   if (!projectEndpoint) {
     throw new Error("Project endpoint is required for TURN APP mode.");
   }
-  const clientId = normalizeOptionalString(options.clientId);
+  const clientId = normalizeOptionalString2(options.clientId);
   if (!clientId) {
     throw new Error("Client ID is required for TURN APP mode.");
   }
-  const clientSecret = normalizeOptionalString(options.clientSecret);
+  const clientSecret = normalizeOptionalString2(options.clientSecret);
   if (!clientSecret) {
     throw new Error("Client secret is required for TURN APP mode.");
   }
@@ -1379,7 +1567,7 @@ async function createAPPTURNCredentials(options) {
     format: "der",
     type: "pkcs8"
   });
-  const serverPublicKeyHex = normalizeOptionalString(options.serverPublicKeyHex) ?? await loadTURNServerPublicKeyHex(clusterDomain, options);
+  const serverPublicKeyHex = normalizeOptionalString2(options.serverPublicKeyHex) ?? await loadTURNServerPublicKeyHex(clusterDomain, options);
   const serverPublicKey = import_crypto.default.createPublicKey({
     key: Buffer.from(serverPublicKeyHex, "hex"),
     format: "der",
@@ -1409,7 +1597,7 @@ async function createAPPTURNCredentials(options) {
 async function createTURNCredentials(options) {
   const credentials = options.credentials;
   const mode = resolveMode(credentials, options.mode);
-  const projectEndpoint = normalizeOptionalString(options.projectEndpoint);
+  const projectEndpoint = normalizeOptionalString2(options.projectEndpoint);
   if (mode === "api") {
     const controlPlaneCredentials = options.controlPlaneCredentials ?? credentials;
     if (!controlPlaneCredentials) {
@@ -1440,6 +1628,10 @@ async function createTURNCredentials(options) {
         "Project endpoint is required for TURN PAT mode."
       ),
       token: credentials.token,
+      tokenEndpoint: requireOption(
+        normalizeOptionalString2(options.tokenEndpoint),
+        "Token endpoint is required for TURN PAT mode."
+      ),
       ttlSeconds: options.ttlSeconds,
       turnPort: options.turnPort,
       turnsPort: options.turnsPort
@@ -1489,6 +1681,7 @@ var RstreamTURNResource = class {
       projectEndpoint: options.projectEndpoint ?? this.client.projectEndpoint,
       projectId: options.projectId,
       serverPublicKeyHex: options.serverPublicKeyHex,
+      tokenEndpoint: options.tokenEndpoint,
       ttlSeconds: options.ttlSeconds,
       turnPort: options.turnPort,
       turnsPort: options.turnsPort
@@ -1498,6 +1691,41 @@ var RstreamTURNResource = class {
 
 // src/webhooks-resource.ts
 var import_crypto2 = __toESM(require("crypto"));
+var SIGNATURE_HEX_BYTES = 32;
+var signatureHexSchema = /^[0-9a-fA-F]{64}$/;
+var timestampSchema = /^\d+$/;
+function parseSignatureTimestamp(timestamp) {
+  if (!timestampSchema.test(timestamp)) {
+    throw new Error("Invalid signature timestamp");
+  }
+  const parsed = Number(timestamp);
+  if (!Number.isSafeInteger(parsed)) {
+    throw new Error("Invalid signature timestamp");
+  }
+  return parsed;
+}
+function normalizeTolerance(tolerance) {
+  if (!Number.isFinite(tolerance) || !Number.isInteger(tolerance) || tolerance < 0) {
+    throw new Error("Invalid signature tolerance");
+  }
+  return tolerance;
+}
+function readSignature(signature) {
+  if (!signatureHexSchema.test(signature)) {
+    return void 0;
+  }
+  const parsed = Buffer.from(signature, "hex");
+  return parsed.length === SIGNATURE_HEX_BYTES ? parsed : void 0;
+}
+function signatureMatches(signature, expected) {
+  const parsed = readSignature(signature);
+  return parsed === void 0 ? false : import_crypto2.default.timingSafeEqual(parsed, expected);
+}
+function assertSecretConfigured(secret) {
+  if (secret.trim().length === 0) {
+    throw new Error("Webhook signing secret is required");
+  }
+}
 var RstreamWebhookResource = class {
   async event(payload, header, secret, tolerance = 300, receivedAt = Date.now()) {
     const payloadBuffer = Buffer.isBuffer(payload) ? payload : Buffer.from(payload);
@@ -1505,31 +1733,26 @@ var RstreamWebhookResource = class {
     if (!signatureHeader) {
       throw new Error("No signature header");
     }
+    assertSecretConfigured(secret);
     const elements = signatureHeader.split(",").map((element) => element.trim());
     const timestamp = elements.find((element) => element.startsWith("t="))?.substring(2);
     const signatures = elements.filter((element) => element.startsWith("v1=")).map((element) => element.substring(3));
     if (!timestamp || signatures.length === 0) {
       throw new Error("Invalid signature header format");
     }
-    const timestampNum = parseInt(timestamp, 10);
+    const timestampNum = parseSignatureTimestamp(timestamp);
+    const signatureTolerance = normalizeTolerance(tolerance);
     const now = Math.floor(receivedAt / 1e3);
-    if (Math.abs(now - timestampNum) > tolerance) {
+    if (Math.abs(now - timestampNum) > signatureTolerance) {
       throw new Error(
         `Webhook signature timestamp outside tolerance: ${now}, ${timestampNum}`
       );
     }
     const signedPayload = `${timestamp}.${payloadBuffer.toString("utf8")}`;
-    const expectedSignature = import_crypto2.default.createHmac("sha256", secret).update(signedPayload).digest("hex");
-    const signatureMatched = signatures.some((signature) => {
-      try {
-        return import_crypto2.default.timingSafeEqual(
-          Buffer.from(signature),
-          Buffer.from(expectedSignature)
-        );
-      } catch {
-        return false;
-      }
-    });
+    const expectedSignature = import_crypto2.default.createHmac("sha256", secret).update(signedPayload).digest();
+    const signatureMatched = signatures.some(
+      (signature) => signatureMatches(signature, expectedSignature)
+    );
     if (!signatureMatched) {
       throw new Error("Signature verification failed");
     }
@@ -1547,8 +1770,16 @@ var RstreamWebhookResource = class {
 };
 
 // src/tunnels.ts
+var engineAuthTokenScopes = {
+  tunnels: {
+    connect: true,
+    create: true,
+    list: true
+  }
+};
 var RstreamTunnelsClient = class {
   config;
+  managedProject;
   constructor(config) {
     this.config = config;
   }
@@ -1568,6 +1799,21 @@ var RstreamTunnelsClient = class {
     return this.config?.projectEndpoint;
   }
   async getEngine() {
+    const projectEndpoint = normalizeOptionalString3(
+      this.config?.projectEndpoint
+    );
+    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_rstream12.getTunnelsProjectEngine)(project);
+        if (engine) {
+          return normalizeEngineAddress(engine);
+        }
+      }
+      throw new Error(
+        "Failed to resolve the engine address from the managed tunnels project."
+      );
+    }
     return await resolveTunnelsEngine({
       apiUrl: this.config?.apiUrl,
       controlPlaneCredentials: this.controlPlaneCredentials,
@@ -1576,6 +1822,55 @@ var RstreamTunnelsClient = class {
       projectEndpoint: this.config?.projectEndpoint
     });
   }
+  async getManagedProject() {
+    const projectEndpoint = normalizeOptionalString3(
+      this.config?.projectEndpoint
+    );
+    if (projectEndpoint === void 0) {
+      return void 0;
+    }
+    if (this.managedProject === void 0) {
+      this.managedProject = resolveManagedTunnelsProject({
+        apiUrl: this.config?.apiUrl,
+        controlPlaneCredentials: this.controlPlaneCredentials,
+        credentials: this.credentials,
+        projectEndpoint
+      }).catch((error) => {
+        this.managedProject = void 0;
+        throw error;
+      });
+    }
+    return await this.managedProject;
+  }
+  async getEngineAuthTokenParams() {
+    const target = await this.getEngineAuthTokenTarget();
+    return {
+      tunnelsGrants: {
+        ...target,
+        scopes: engineAuthTokenScopes
+      }
+    };
+  }
+  async getEngineAuthTokenTarget() {
+    const projectId = normalizeOptionalString3(this.config?.projectId);
+    const workspaceId = normalizeOptionalString3(this.config?.workspaceId);
+    if (projectId !== void 0 && workspaceId !== void 0) {
+      throw new Error("Use either projectId or workspaceId, not both.");
+    }
+    if (projectId !== void 0) {
+      return { projects: [projectId] };
+    }
+    if (workspaceId !== void 0) {
+      return { workspaces: [workspaceId] };
+    }
+    const project = await this.getManagedProject();
+    if (project !== void 0) {
+      return { projects: [project.id] };
+    }
+    throw new Error(
+      "Application credentials require projectId, workspaceId, or projectEndpoint to create scoped engine tokens."
+    );
+  }
   get auth() {
     return new RstreamAuthResource(this);
   }
@@ -1596,16 +1891,20 @@ var RstreamTunnelsClient = class {
     if (!credentials) {
       return void 0;
     }
-    if (!(0, import_rstream12.isClientCredentials)(credentials)) {
+    if (!(0, import_rstream13.isClientCredentials)(credentials)) {
       return credentials.token;
     }
-    return (await this.auth.createAuthToken(void 0, {
+    const tokenParams = await this.getEngineAuthTokenParams();
+    return (await this.auth.createAuthToken(tokenParams, {
       credentials,
       engine
     })).token;
   }
   async request(path, options) {
-    const engine = await this.getEngine();
+    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);
@@ -1614,7 +1913,8 @@ var RstreamTunnelsClient = class {
     }
     const response = await fetch(url, {
       ...options,
-      headers
+      headers,
+      redirect: options?.redirect ?? "manual"
     });
     if (!response.ok) {
       const errorText = await response.text();
@@ -1623,8 +1923,96 @@ var RstreamTunnelsClient = class {
     return await response.json();
   }
 };
+function normalizeOptionalString3(value) {
+  const normalized = value?.trim();
+  return normalized ? normalized : void 0;
+}
 
 // src/watch.ts
+var import_jsonwebtoken = __toESM(require("jsonwebtoken"));
+var maxWatchTokenLifetimeSeconds = 3600;
+var watchTokenIssuedAtSkewSeconds = 300;
+function normalizeTransport(transport) {
+  if (transport === void 0) {
+    return "sse";
+  }
+  if (transport === "sse" || transport === "websocket") {
+    return transport;
+  }
+  throw new Error("Watch: Unsupported transport.");
+}
+function validateWatchQueryToken(token) {
+  const parsed = authTokenSchema.safeParse(import_jsonwebtoken.default.decode(token));
+  if (!parsed.success || parsed.data.type === "pat") {
+    throw new Error(
+      "Watch requires a short-lived auth or app token for URL-based authentication."
+    );
+  }
+  const iat = parsed.data.iat;
+  const exp = parsed.data.exp;
+  const now = Math.floor(Date.now() / 1e3);
+  if (typeof iat !== "number" || typeof exp !== "number" || !Number.isInteger(iat) || !Number.isInteger(exp) || exp <= iat || exp <= now || exp > now + maxWatchTokenLifetimeSeconds || iat > now + watchTokenIssuedAtSkewSeconds || exp - iat > maxWatchTokenLifetimeSeconds) {
+    throw new Error(
+      "Watch requires a token with a bounded lifetime of at most 3600 seconds."
+    );
+  }
+  if (!hasWatchOnlyTunnelGrants(parsed.data)) {
+    throw new Error(
+      "Watch requires a fine-grained token limited to tunnel list grants for URL-based authentication."
+    );
+  }
+}
+function hasWatchOnlyTunnelGrants(token) {
+  if (!hasWatchOnlyPermissions(token.permissions)) {
+    return false;
+  }
+  if (token.tunnelsGrants === void 0) {
+    return false;
+  }
+  return hasWatchOnlyTunnelGrant(token.tunnelsGrants);
+}
+function hasWatchOnlyTunnelGrant(grant) {
+  return watchGrantBranches(grant).every(
+    (branch) => branch.hasList && !branch.hasMutationOrConnect
+  );
+}
+function watchGrantBranches(grant) {
+  if ("AND" in grant) {
+    return grant.AND.reduce(
+      (branches, child) => combineWatchGrantBranches(branches, child),
+      [{ hasList: false, hasMutationOrConnect: false }]
+    );
+  }
+  if ("OR" in grant) {
+    return grant.OR.flatMap(watchGrantBranches);
+  }
+  const tunnels = grant.scopes?.tunnels;
+  if (tunnels === void 0) {
+    return [{ hasList: false, hasMutationOrConnect: false }];
+  }
+  return [
+    {
+      hasList: tunnels.list !== void 0,
+      hasMutationOrConnect: tunnels.create !== void 0 || tunnels.connect !== void 0
+    }
+  ];
+}
+function combineWatchGrantBranches(branches, child) {
+  return branches.flatMap(
+    (branch) => watchGrantBranches(child).map((childBranch) => ({
+      hasList: branch.hasList || childBranch.hasList,
+      hasMutationOrConnect: branch.hasMutationOrConnect || childBranch.hasMutationOrConnect
+    }))
+  );
+}
+function hasWatchOnlyPermissions(permissions) {
+  if (!Array.isArray(permissions)) {
+    return true;
+  }
+  return permissions.every(
+    (permission) => permission === "tunnels.resources.read-only" || permission === "network.resources.read-only"
+  );
+}
 var Watch = class {
   connection = null;
   connectionState = "preparing";
@@ -1639,45 +2027,56 @@ var Watch = class {
       throw new Error("Watch: Connection already started or closed.");
     }
     this.connectionState = "connecting";
-    const token = typeof this.config.auth === "function" ? await this.config.auth() : this.config.auth;
-    const engine = await resolveTunnelsEngine({
-      apiUrl: this.config.apiUrl,
-      controlPlaneCredentials: this.config.controlPlaneCredentials,
-      engine: this.config.engine,
-      projectEndpoint: this.config.projectEndpoint,
-      token
-    });
-    const transport = this.config.transport ?? "sse";
-    const base = `https://${engine}`;
-    if (transport === "sse") {
-      const url = new URL(`/api/sse`, base);
-      url.searchParams.set("rstream.token", token);
-      this.connection = new EventSource(url.toString());
-    } else {
-      const url = new URL(`/api/websocket`, base);
-      url.searchParams.set("rstream.token", token);
-      url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
-      this.connection = new WebSocket(url.toString());
-    }
-    this.connection.onopen = () => {
-      this.connectionState = "connected";
-      this.events.onConnect?.();
-    };
-    this.connection.onmessage = (msg) => {
-      const parsed = wsEventsSchema.parse(JSON.parse(msg.data));
-      this.events.onEvent?.(parsed);
-    };
-    this.connection.onerror = () => {
-      if (this.connectionState !== "closed") {
-        this.disconnect();
+    try {
+      const token = typeof this.config.auth === "function" ? await this.config.auth() : this.config.auth;
+      validateWatchQueryToken(token);
+      const engine = await resolveTunnelsEngine({
+        apiUrl: this.config.apiUrl,
+        controlPlaneCredentials: this.config.controlPlaneCredentials,
+        engine: this.config.engine,
+        projectEndpoint: this.config.projectEndpoint,
+        token
+      });
+      const transport = normalizeTransport(this.config.transport);
+      const base = `https://${engine}`;
+      if (transport === "sse") {
+        const url = new URL(`/api/sse`, base);
+        url.searchParams.set("rstream.token", token);
+        this.connection = new EventSource(url.toString());
+      } else {
+        const url = new URL(`/api/websocket`, base);
+        url.searchParams.set("rstream.token", token);
+        url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+        this.connection = new WebSocket(url.toString());
       }
-    };
-    if (this.connection instanceof WebSocket) {
-      this.connection.onclose = () => {
+      this.connection.onopen = () => {
+        this.connectionState = "connected";
+        this.events.onConnect?.();
+      };
+      this.connection.onmessage = (msg) => this.handleMessage(msg.data);
+      this.connection.onerror = () => {
         if (this.connectionState !== "closed") {
           this.disconnect();
         }
       };
+      if (this.connection instanceof WebSocket) {
+        this.connection.onclose = () => {
+          if (this.connectionState !== "closed") {
+            this.disconnect();
+          }
+        };
+      }
+    } catch (error) {
+      this.connectionState = "preparing";
+      throw error;
+    }
+  }
+  handleMessage(data) {
+    try {
+      const parsed = wsEventsSchema.parse(JSON.parse(data));
+      this.events.onEvent?.(parsed);
+    } catch {
+      this.disconnect();
     }
   }
   disconnect() {
@@ -1798,8 +2197,10 @@ function parseWebTTYServers(tunnels) {
   listClientsResponseSchema,
   listTunnelsParamsSchema,
   listTunnelsResponseSchema,
+  normalizeEngineAddress,
   parseWebTTYServers,
   resolveControlPlaneCredentials,
+  resolveManagedTunnelsProject,
   resolveTunnelsAPIURL,
   resolveTunnelsCredentials,
   resolveTunnelsEngine,