@rstreamlabs/tunnels 1.0.6 → 1.0.7

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,6 +57,8 @@ __export(index_exports, {
   createAuthTokenResponseSchema: () => createAuthTokenResponseSchema,
   createPATTURNCredentials: () => createPATTURNCredentials,
   createTURNCredentials: () => createTURNCredentials,
+  engineOpenApiDocument: () => engineOpenApiDocument,
+  engineOpenApiJson: () => engineOpenApiJson,
   eventSchema: () => eventSchema,
   formatTunnelHost: () => formatTunnelHost,
   listClientsParamsSchema: () => listClientsParamsSchema,
@@ -71,6 +74,7 @@ __export(index_exports, {
   streamSummarySchema: () => streamSummarySchema,
   streamTLSInfoSchema: () => streamTLSInfoSchema,
   tokenSchema: () => tokenSchema,
+  tunnelFilterSchema: () => tunnelFilterSchema,
   tunnelSchema: () => tunnelSchema,
   turnCredentialModeSchema: () => turnCredentialModeSchema,
   webhookEventsSchema: () => webhookEventsSchema,
@@ -165,16 +169,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) {
@@ -371,11 +381,21 @@ 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);
 
@@ -664,6 +684,358 @@ 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>."
+      },
+      queryToken: {
+        type: "apiKey",
+        in: "query",
+        name: "rstream.token",
+        description: "Fallback authentication mechanism for transports where setting Authorization is impractical. Prefer bearerAuth whenever possible."
+      }
+    },
+    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: [] }, { queryToken: [] }],
+        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: [] }, { queryToken: [] }],
+        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: [] }, { queryToken: [] }],
+        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: [] }, { queryToken: [] }],
+        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");
@@ -789,16 +1161,16 @@ 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 turnTokenClaimsSchema = z8.object({
+  token_endpoint: z8.string().optional(),
+  type: z8.string()
 });
-var turnCredentialModeSchema = z7.enum(["api", "app", "pat"]);
+var turnCredentialModeSchema = z8.enum(["api", "app", "pat"]);
 function normalizeOptionalString(value) {
   const normalized = value?.trim();
   return normalized ? normalized : void 0;
@@ -1324,7 +1696,7 @@ var Watch = class {
 };
 
 // src/webtty.ts
-var z8 = __toESM(require("zod"));
+var z9 = __toESM(require("zod"));
 var osFamilies = [
   "linux",
   "macos",
@@ -1333,25 +1705,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 +1781,7 @@ function parseWebTTYServers(tunnels) {
   authTokenScopesSchema,
   authTokenTunnelGrantSchema,
   authTokenTunnelsScopesSchema,
+  clientFilterSchema,
   clientSchema,
   createAPITURNCredentials,
   createAPPTURNCredentials,
@@ -1417,6 +1790,8 @@ function parseWebTTYServers(tunnels) {
   createAuthTokenResponseSchema,
   createPATTURNCredentials,
   createTURNCredentials,
+  engineOpenApiDocument,
+  engineOpenApiJson,
   eventSchema,
   formatTunnelHost,
   listClientsParamsSchema,
@@ -1432,6 +1807,7 @@ function parseWebTTYServers(tunnels) {
   streamSummarySchema,
   streamTLSInfoSchema,
   tokenSchema,
+  tunnelFilterSchema,
   tunnelSchema,
   turnCredentialModeSchema,
   webhookEventsSchema,