@rstreamlabs/tunnels 1.0.6 → 1.0.8

package/dist/index.js

@@ -48,6 +48,7 @@ __export(index_exports, {
   authTokenScopesSchema: () => authTokenScopesSchema,
   authTokenTunnelGrantSchema: () => authTokenTunnelGrantSchema,
   authTokenTunnelsScopesSchema: () => authTokenTunnelsScopesSchema,
+  clientFilterSchema: () => clientFilterSchema,
   clientSchema: () => clientSchema,
   createAPITURNCredentials: () => createAPITURNCredentials,
   createAPPTURNCredentials: () => createAPPTURNCredentials,
@@ -56,14 +57,18 @@ __export(index_exports, {
   createAuthTokenResponseSchema: () => createAuthTokenResponseSchema,
   createPATTURNCredentials: () => createPATTURNCredentials,
   createTURNCredentials: () => createTURNCredentials,
+  engineOpenApiDocument: () => engineOpenApiDocument,
+  engineOpenApiJson: () => engineOpenApiJson,
   eventSchema: () => eventSchema,
   formatTunnelHost: () => formatTunnelHost,
   listClientsParamsSchema: () => listClientsParamsSchema,
   listClientsResponseSchema: () => listClientsResponseSchema,
   listTunnelsParamsSchema: () => listTunnelsParamsSchema,
   listTunnelsResponseSchema: () => listTunnelsResponseSchema,
+  normalizeEngineAddress: () => normalizeEngineAddress,
   parseWebTTYServers: () => parseWebTTYServers,
   resolveControlPlaneCredentials: () => resolveControlPlaneCredentials,
+  resolveManagedTunnelsProject: () => resolveManagedTunnelsProject,
   resolveTunnelsAPIURL: () => resolveTunnelsAPIURL,
   resolveTunnelsCredentials: () => resolveTunnelsCredentials,
   resolveTunnelsEngine: () => resolveTunnelsEngine,
@@ -71,6 +76,7 @@ __export(index_exports, {
   streamSummarySchema: () => streamSummarySchema,
   streamTLSInfoSchema: () => streamTLSInfoSchema,
   tokenSchema: () => tokenSchema,
+  tunnelFilterSchema: () => tunnelFilterSchema,
   tunnelSchema: () => tunnelSchema,
   turnCredentialModeSchema: () => turnCredentialModeSchema,
   webhookEventsSchema: () => webhookEventsSchema,
@@ -86,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) {
@@ -122,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
@@ -165,16 +171,22 @@ var tunnelSchema = z2.object({
   rstream_auth: z2.boolean().optional(),
   challenge_mode: z2.boolean().optional()
 });
+var tunnelFilterSchema = tunnelSchema.pick({
+  id: true,
+  name: true,
+  type: true,
+  status: true,
+  client_id: true,
+  user_id: true,
+  publish: true,
+  protocol: true,
+  hostname: true,
+  http_version: true,
+  labels: true
+}).partial();
 var listTunnelsParamsSchema = z2.object({
-  limit: z2.number().optional(),
-  filters: tunnelSchema.pick({
-    status: true,
-    client_id: true,
-    hostname: true,
-    protocol: true,
-    publish: true,
-    labels: true
-  }).partial().optional()
+  limit: z2.number().int().min(1).optional(),
+  filters: tunnelFilterSchema.optional()
 });
 var listTunnelsResponseSchema = z2.array(tunnelSchema);
 function formatTunnelHost(tunnel) {
@@ -209,7 +221,7 @@ var authTokenTunnelsScopesSchema = z3.object({
           creation_date: true
         })
       ).optional()
-    })
+    }).strict()
   ]).optional(),
   // Scopes for connecting to tunnels
   connect: z3.union([
@@ -221,7 +233,7 @@ var authTokenTunnelsScopesSchema = z3.object({
           path: z3.string().optional()
         })
       ).optional()
-    })
+    }).strict()
   ]).optional(),
   // Scopes for listing tunnels
   list: z3.union([
@@ -229,17 +241,32 @@ 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({
   workspaces: z3.array(nonEmptyStringSchema).min(1).optional(),
   projects: z3.array(nonEmptyStringSchema).min(1).optional(),
-  scopes: authTokenScopesSchema.optional()
+  scopes: authTokenScopesSchema
 }).strict().superRefine((grant, ctx) => {
   if (grant.workspaces !== void 0 && grant.projects !== void 0) {
     ctx.addIssue({
@@ -248,6 +275,13 @@ var authTokenTunnelGrantSchema = z3.object({
       path: ["projects"]
     });
   }
+  if (grant.workspaces === void 0 && grant.projects === void 0) {
+    ctx.addIssue({
+      code: z3.ZodIssueCode.custom,
+      message: "A grant must target workspaces or projects.",
+      path: ["workspaces"]
+    });
+  }
 });
 var authTokenCommonSchema = {
   aud: z3.union([z3.string(), z3.array(z3.string())]).optional(),
@@ -283,10 +317,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: z3.array(authTokenTunnelGrantSchema).min(1).optional(),
   metadata: z3.unknown().optional()
   // Additional metadata
 }).strict().superRefine((params, ctx) => {
@@ -297,6 +330,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()
@@ -323,12 +363,12 @@ var RstreamAuthResource = class {
   }
 };
 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, {
@@ -337,19 +377,36 @@ 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];
   }
   if (params.scopes) {
-    return [{ scopes: params.scopes }];
+    return [{ ...normalizeTunnelGrantTarget(options), scopes: params.scopes }];
   }
   return void 0;
 }
+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] };
+  }
+  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"));
@@ -371,15 +428,32 @@ var clientSchema = z4.object({
   protocol_version: z4.string().optional(),
   labels: z4.record(z4.string(), z4.string()).optional()
 });
+var clientFilterSchema = clientSchema.pick({
+  id: true,
+  status: true,
+  user_id: true,
+  agent: true,
+  channel: true,
+  version: true,
+  os: true,
+  arch: true,
+  protocol_version: true,
+  labels: true
+}).partial();
 var listClientsParamsSchema = z4.object({
-  limit: z4.number().optional(),
-  filters: clientSchema.pick({
-    labels: true
-  }).partial().optional()
+  limit: z4.number().int().min(1).optional(),
+  filters: clientFilterSchema.optional()
 });
 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) {
@@ -393,9 +467,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);
   }
 };
@@ -664,28 +741,389 @@ var webhookEventsSchema = z6.union([
 ]);
 var eventSchema = z6.union([wsEventsSchema, webhookEventsSchema]);
 
+// src/openapi.ts
+var z7 = __toESM(require("zod"));
+var jsonContentType = "application/json";
+var openApiContentType = "application/vnd.oai.openapi+json;version=3.1";
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function dropSchemaKeyword(value) {
+  if (!isRecord(value)) return value;
+  return Object.fromEntries(
+    Object.entries(value).filter(([key]) => key !== "$schema")
+  );
+}
+function jsonSchemaFor(schema) {
+  return dropSchemaKeyword(
+    z7.toJSONSchema(schema, {
+      unrepresentable: "any",
+      override: (ctx) => {
+        if (ctx.zodSchema instanceof z7.ZodDate) {
+          ctx.jsonSchema.type = "string";
+          ctx.jsonSchema.format = "date-time";
+        }
+      }
+    })
+  );
+}
+function jsonArrayResponse(description, itemSchemaRef) {
+  return {
+    description,
+    content: {
+      [jsonContentType]: {
+        schema: {
+          type: "array",
+          items: {
+            $ref: itemSchemaRef
+          }
+        }
+      }
+    }
+  };
+}
+function streamResponse(description) {
+  return {
+    description,
+    content: {
+      "text/event-stream": {
+        schema: {
+          type: "string"
+        }
+      }
+    }
+  };
+}
+function errorResponse(description) {
+  return {
+    description
+  };
+}
+function queryJsonParameter(name, description, schemaRef, examples) {
+  return {
+    name,
+    in: "query",
+    required: false,
+    description,
+    content: {
+      [jsonContentType]: {
+        schema: {
+          $ref: schemaRef
+        },
+        ...examples ? { examples } : {}
+      }
+    }
+  };
+}
+var readEngineStateRule = {
+  resource: ["engine.tunnels", "engine.streams"],
+  action: "read"
+};
+var readEngineStateRules = [readEngineStateRule];
+var readEngineStreamsRules = [
+  {
+    resource: "engine.streams",
+    action: "read"
+  }
+];
+var watchParamsSchema = z7.object({
+  clients: clientFilterSchema.optional(),
+  tunnels: tunnelFilterSchema.optional()
+});
+var enginePermissions = {
+  "tunnels.resources.read-only": {
+    name: "Discovery: Read-Only",
+    description: "Read active clients, active tunnels, and live state events.",
+    rules: [readEngineStateRule]
+  },
+  "tunnels.tunnels.create-delete": {
+    name: "Tunnels: Create and Delete",
+    description: "Create and close tunnels through the CLI, SDK, or engine control channel.",
+    rules: [
+      {
+        resource: "engine.tunnels",
+        action: ["create", "delete"]
+      }
+    ]
+  },
+  "tunnels.streams.create-delete": {
+    name: "Connections: Create and Delete",
+    description: "Open and close private tunnel streams and WebTTY connections.",
+    rules: [
+      {
+        resource: "engine.streams",
+        action: ["create", "delete"]
+      }
+    ]
+  }
+};
+var engineOpenApiDocument = {
+  openapi: "3.1.0",
+  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."
+  },
+  servers: [
+    {
+      url: "https://{engine}",
+      description: "Project-scoped rstream engine endpoint.",
+      variables: {
+        engine: {
+          default: "project-endpoint.cluster-host:443",
+          description: "Use the engine value returned by project discovery or configured in RSTREAM_ENGINE."
+        }
+      }
+    }
+  ],
+  security: [
+    {
+      bearerAuth: []
+    }
+  ],
+  components: {
+    securitySchemes: {
+      bearerAuth: {
+        type: "http",
+        scheme: "bearer",
+        bearerFormat: "rstream token",
+        description: "Preferred authentication mechanism. Send an OAuth-issued rstream access token or compatible rstream credential in Authorization: Bearer <token>."
+      }
+    },
+    parameters: {
+      ListClientsParams: queryJsonParameter(
+        "params",
+        "JSON-encoded ListClientsParams object.",
+        "#/components/schemas/ListClientsParams",
+        {
+          filterByAgent: {
+            value: {
+              limit: 10,
+              filters: {
+                agent: "rstream",
+                channel: "stable"
+              }
+            }
+          }
+        }
+      ),
+      ListTunnelsParams: queryJsonParameter(
+        "params",
+        "JSON-encoded ListTunnelsParams object.",
+        "#/components/schemas/ListTunnelsParams",
+        {
+          filterByLabels: {
+            value: {
+              filters: {
+                labels: {
+                  service: "ssh",
+                  env: "prod"
+                }
+              }
+            }
+          }
+        }
+      ),
+      WatchParams: queryJsonParameter(
+        "params",
+        "JSON-encoded WatchParams object. The same shape is accepted by SSE and WebSocket transports.",
+        "#/components/schemas/WatchParams",
+        {
+          watchTaggedTunnels: {
+            value: {
+              clients: {
+                agent: "rstream"
+              },
+              tunnels: {
+                labels: {
+                  service: "ssh"
+                }
+              }
+            }
+          }
+        }
+      )
+    },
+    responses: {
+      BadRequest: errorResponse("Request validation failed."),
+      Unauthorized: errorResponse("Authentication is required."),
+      Forbidden: errorResponse("The token is not authorized.")
+    },
+    schemas: {
+      Client: jsonSchemaFor(clientSchema),
+      Event: jsonSchemaFor(wsEventsSchema),
+      ListClientsParams: jsonSchemaFor(listClientsParamsSchema),
+      ListTunnelsParams: jsonSchemaFor(listTunnelsParamsSchema),
+      TunnelListItem: jsonSchemaFor(tunnelSchema),
+      WatchParams: jsonSchemaFor(watchParamsSchema)
+    }
+  },
+  "x-rstream-agent-authentication": {
+    oauth_authorization_server_metadata: "https://rstream.io/.well-known/oauth-authorization-server",
+    oauth_protected_resource_metadata: "https://rstream.io/.well-known/oauth-protected-resource",
+    scope_selection: "Use x-rstream-required-rules to understand backend authorization checks. Choose OAuth scopes from x-rstream-permissions or use the task bundles in x-rstream-use-case-permissions."
+  },
+  "x-rstream-permissions": enginePermissions,
+  "x-rstream-use-case-permissions": {
+    "inspect-engine-state": ["tunnels.resources.read-only"],
+    "expose-service-from-cli": [
+      "tunnels.resources.read-only",
+      "tunnels.tunnels.create-delete"
+    ],
+    "connect-private-tunnel": [
+      "tunnels.resources.read-only",
+      "tunnels.streams.create-delete"
+    ],
+    "operate-webtty": [
+      "tunnels.resources.read-only",
+      "tunnels.tunnels.create-delete",
+      "tunnels.streams.create-delete"
+    ]
+  },
+  paths: {
+    "/api/openapi.json": {
+      get: {
+        tags: ["Discovery"],
+        summary: "Return this OpenAPI description.",
+        operationId: "get_engine_openapi",
+        security: [],
+        responses: {
+          "200": {
+            description: "OpenAPI document.",
+            content: {
+              [openApiContentType]: {
+                schema: {
+                  type: "object"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/clients": {
+      get: {
+        tags: ["Runtime inventory"],
+        summary: "List visible engine clients.",
+        operationId: "list_engine_clients",
+        parameters: [{ $ref: "#/components/parameters/ListClientsParams" }],
+        security: [{ bearerAuth: [] }],
+        responses: {
+          "200": jsonArrayResponse(
+            "Visible clients.",
+            "#/components/schemas/Client"
+          ),
+          "400": { $ref: "#/components/responses/BadRequest" },
+          "401": { $ref: "#/components/responses/Unauthorized" },
+          "403": { $ref: "#/components/responses/Forbidden" }
+        },
+        "x-rstream-required-rules": readEngineStreamsRules
+      }
+    },
+    "/api/tunnels": {
+      get: {
+        tags: ["Runtime inventory"],
+        summary: "List visible engine tunnels.",
+        operationId: "list_engine_tunnels",
+        parameters: [{ $ref: "#/components/parameters/ListTunnelsParams" }],
+        security: [{ bearerAuth: [] }],
+        responses: {
+          "200": jsonArrayResponse(
+            "Visible tunnels. Fine-grained list scopes may filter objects and project fields.",
+            "#/components/schemas/TunnelListItem"
+          ),
+          "400": { $ref: "#/components/responses/BadRequest" },
+          "401": { $ref: "#/components/responses/Unauthorized" },
+          "403": { $ref: "#/components/responses/Forbidden" }
+        },
+        "x-rstream-required-rules": readEngineStateRules,
+        "x-rstream-token-metadata-scope": "metadata.scopes.tunnels.list"
+      }
+    },
+    "/api/sse": {
+      get: {
+        tags: ["Runtime watch"],
+        summary: "Subscribe to visible engine state through Server-Sent Events.",
+        operationId: "watch_engine_events_sse",
+        parameters: [{ $ref: "#/components/parameters/WatchParams" }],
+        security: [{ bearerAuth: [] }],
+        responses: {
+          "200": streamResponse(
+            "SSE stream. Each event is emitted as a data line containing a JSON Event object."
+          ),
+          "400": { $ref: "#/components/responses/BadRequest" },
+          "401": { $ref: "#/components/responses/Unauthorized" },
+          "403": { $ref: "#/components/responses/Forbidden" }
+        },
+        "x-rstream-event-schema": "#/components/schemas/Event",
+        "x-rstream-required-rules": readEngineStateRules
+      }
+    },
+    "/api/websocket": {
+      get: {
+        tags: ["Runtime watch"],
+        summary: "Subscribe to visible engine state through a WebSocket upgrade.",
+        operationId: "watch_engine_events_websocket",
+        parameters: [{ $ref: "#/components/parameters/WatchParams" }],
+        security: [{ bearerAuth: [] }],
+        responses: {
+          "101": {
+            description: "WebSocket connection accepted. Frames contain JSON Event objects."
+          },
+          "400": { $ref: "#/components/responses/BadRequest" },
+          "401": { $ref: "#/components/responses/Unauthorized" },
+          "403": { $ref: "#/components/responses/Forbidden" }
+        },
+        "x-rstream-event-schema": "#/components/schemas/Event",
+        "x-rstream-required-rules": readEngineStateRules
+      }
+    }
+  }
+};
+var engineOpenApiJson = `${JSON.stringify(
+  engineOpenApiDocument,
+  null,
+  2
+)}
+`;
+
 // src/resolution.ts
 var import_rstream3 = require("@rstreamlabs/rstream");
 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;
@@ -719,37 +1157,22 @@ 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."
@@ -759,8 +1182,36 @@ async function resolveTunnelsEngine(config) {
     "Engine URL is not defined. Provide an engine, use RSTREAM_ENGINE, or configure a managed project endpoint with control-plane 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) {
@@ -774,65 +1225,76 @@ 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");
 var import_rstream9 = require("@rstreamlabs/rstream");
 var import_rstream10 = require("@rstreamlabs/rstream");
 var import_rstream11 = require("@rstreamlabs/rstream");
-var z7 = __toESM(require("zod"));
+var z8 = __toESM(require("zod"));
 var import_crypto = __toESM(require("crypto"));
 var defaultTURNPort = 3478;
 var defaultTURNSPort = 5349;
-var defaultTURNCredentialTTLSeconds = 24 * 60 * 60;
-var turnTokenClaimsSchema = z7.object({
-  token_endpoint: z7.string().optional(),
-  type: z7.string()
+var defaultTURNCredentialTTLSeconds = 10 * 60;
+var maxTURNCredentialTTLSeconds = 60 * 60;
+var turnTokenClaimsSchema = z8.object({
+  exp: z8.number().int().optional(),
+  iat: z8.number().int().optional(),
+  token_endpoint: z8.string().regex(/^[0-9a-f]{8}$/i).optional(),
+  type: z8.enum(["app", "auth", "pat"])
 });
-var turnCredentialModeSchema = z7.enum(["api", "app", "pat"]);
-function normalizeOptionalString(value) {
+var turnCredentialModeSchema = z8.enum(["api", "app", "pat"]);
+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);
@@ -850,16 +1312,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."
@@ -893,17 +1371,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
@@ -915,8 +1387,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."
@@ -943,11 +1415,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.");
   }
@@ -955,14 +1427,17 @@ 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.");
+  }
+  if (claims.token_endpoint !== void 0 && claims.token_endpoint !== 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(
@@ -977,7 +1452,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
   });
@@ -987,15 +1462,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.");
   }
@@ -1007,7 +1482,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",
@@ -1037,7 +1512,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) {
@@ -1068,6 +1543,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
@@ -1117,6 +1596,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
@@ -1126,6 +1606,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);
@@ -1133,31 +1648,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");
     }
@@ -1175,8 +1685,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;
   }
@@ -1196,6 +1714,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,
@@ -1204,6 +1737,57 @@ 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);
   }
@@ -1224,16 +1808,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);
@@ -1242,7 +1830,8 @@ var RstreamTunnelsClient = class {
     }
     const response = await fetch(url, {
       ...options,
-      headers
+      headers,
+      redirect: options?.redirect ?? "manual"
     });
     if (!response.ok) {
       const errorText = await response.text();
@@ -1251,8 +1840,68 @@ 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 (!Array.isArray(token.tunnelsGrants) || token.tunnelsGrants.length === 0) {
+    return false;
+  }
+  return token.tunnelsGrants.every((grant) => {
+    const tunnels = grant.scopes?.tunnels;
+    if (tunnels === void 0) {
+      return false;
+    }
+    return tunnels.list !== void 0 && tunnels.create === void 0 && tunnels.connect === void 0;
+  });
+}
+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";
@@ -1267,45 +1916,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() {
@@ -1324,7 +1984,7 @@ var Watch = class {
 };
 
 // src/webtty.ts
-var z8 = __toESM(require("zod"));
+var z9 = __toESM(require("zod"));
 var osFamilies = [
   "linux",
   "macos",
@@ -1333,25 +1993,25 @@ var osFamilies = [
   "openbsd",
   "freebsd"
 ];
-var webttyServerSchema = z8.object({
-  tunnel_id: z8.string(),
-  host: z8.string(),
-  token_auth: z8.boolean(),
-  os_family: z8.enum(osFamilies).optional(),
-  arch: z8.string().optional(),
-  os_id: z8.string().optional(),
+var webttyServerSchema = z9.object({
+  tunnel_id: z9.string(),
+  host: z9.string(),
+  token_auth: z9.boolean(),
+  os_family: z9.enum(osFamilies).optional(),
+  arch: z9.string().optional(),
+  os_id: z9.string().optional(),
   // /etc/os-release::ID (ubuntu, debian, rocky, etc.)
-  os_version_id: z8.string().optional(),
+  os_version_id: z9.string().optional(),
   // /etc/os-release::VERSION_ID (24.04, 22.04, 11, 10.0.19045, ...)
-  os_version_codename: z8.string().optional(),
+  os_version_codename: z9.string().optional(),
   // /etc/os-release::VERSION_CODENAME (jammy, noble...)
-  os_pretty_name: z8.string().optional(),
+  os_pretty_name: z9.string().optional(),
   // /etc/os-release::PRETTY_NAME
-  kernel_release: z8.string().optional(),
+  kernel_release: z9.string().optional(),
   // uname -r
-  hostname: z8.string().optional(),
+  hostname: z9.string().optional(),
   // uname -n
-  labels: z8.record(z8.string(), z8.string().optional()).optional()
+  labels: z9.record(z9.string(), z9.string().optional()).optional()
 });
 function parser(tunnel) {
   if (tunnel.status !== "online") return null;
@@ -1409,6 +2069,7 @@ function parseWebTTYServers(tunnels) {
   authTokenScopesSchema,
   authTokenTunnelGrantSchema,
   authTokenTunnelsScopesSchema,
+  clientFilterSchema,
   clientSchema,
   createAPITURNCredentials,
   createAPPTURNCredentials,
@@ -1417,14 +2078,18 @@ function parseWebTTYServers(tunnels) {
   createAuthTokenResponseSchema,
   createPATTURNCredentials,
   createTURNCredentials,
+  engineOpenApiDocument,
+  engineOpenApiJson,
   eventSchema,
   formatTunnelHost,
   listClientsParamsSchema,
   listClientsResponseSchema,
   listTunnelsParamsSchema,
   listTunnelsResponseSchema,
+  normalizeEngineAddress,
   parseWebTTYServers,
   resolveControlPlaneCredentials,
+  resolveManagedTunnelsProject,
   resolveTunnelsAPIURL,
   resolveTunnelsCredentials,
   resolveTunnelsEngine,
@@ -1432,6 +2097,7 @@ function parseWebTTYServers(tunnels) {
   streamSummarySchema,
   streamTLSInfoSchema,
   tokenSchema,
+  tunnelFilterSchema,
   tunnelSchema,
   turnCredentialModeSchema,
   webhookEventsSchema,