@rstreamlabs/tunnels 3.8.3 → 3.10.1

package/README.md

@@ -340,3 +340,57 @@ npm --workspace @rstreamlabs/tunnels run type-check
 npm --workspace @rstreamlabs/tunnels run lint
 npm --workspace @rstreamlabs/tunnels run build
 ```
+
+## Building
+
+`npm run build` emits declarations with TypeScript before bundling them. This
+keeps inferred schema property order deterministic; per-module declaration
+emission during asynchronous bundling can otherwise change published archive
+bytes between identical builds. `.generated/types/` is temporary build output. The watch
+command continues to infer declarations directly for development.
+
+## Certificate-only Engine access
+
+Node.js clients may reuse a certificate identity for Engine inventory, TURN
+issuance and SSE watch streams:
+
+```ts
+const client = new RstreamTunnelsClient({
+  engine: "<project-engine-host>:443",
+  tls: { cert: deviceCertificatePEM, key: devicePrivateKeyPEM },
+});
+try {
+  const turn = await client.turn.createCredentials({ ttlSeconds: 600 });
+  const tunnels = await client.tunnels.list();
+} finally {
+  await client.close();
+}
+```
+
+Grant the enrolled credential `turn.credentials.create` and the required Engine
+permissions, restricted to its project. Do not also pass token credentials.
+The client anonymously discovers `/.well-known/rstream/engine` and caches its
+project-bound HTTPS `mtlsApiUrl` in memory, normally for one hour. Discovery uses
+verified server TLS without the certificate, cookies, Control plane headers or
+redirects. Optional `mtlsApiUrl` config provides an explicit deployment override;
+no shared YAML change is required. The ordinary browser host never requests a
+client certificate. Browser/token behavior is unchanged.
+
+Node.js uses HTTPS/TCP. Certificate watch streams use SSE with this reusable
+client; the WebSocket watch adapter rejects certificate mode. The Engine itself
+also implements HTTP/3, which the Go SDK supports for API/SSE calls.
+
+Automatic TURN mode prefers eligible local PAT/APP derivation with known relay
+metadata, then the Control plane, and finally the configured Engine on network
+unavailability or HTTP 502/503/504. Certificate mode goes directly to Engine.
+Auth, TLS verification, schema, throttling and caller cancellation errors never
+cause fallback. Explicit `api`, `engine`, `pat` and `app` modes remain available.
+The default total budget is ten seconds; the automatic Control plane phase gets
+at most five seconds. APP API proofs are locally signed with issuance-only rights.
+
+Both managed APIs return `{username, credential, urls, ttl}`; TTL is effective
+remaining seconds, clipped to all backing-proof expirations. Issuance needs
+`turn.credentials.create`; local derivation needs `turn.relay.allocate`. Relay
+membership, scope, revocation and quotas are still checked. Treat the returned
+username/password as opaque and renew before expiry. See the shared PAT/APP
+fixtures and real HTTPS tests in `test/mtls.test.cjs`.

package/dist/{chunk-3VBF43NB.mjs → chunk-DQN5T7CI.mjs}

@@ -1000,6 +1000,19 @@ var watchParamsSchema = z7.object({
   tunnels: tunnelFilterSchema.optional()
 });
 var enginePermissions = {
+  "turn.credentials.create": {
+    name: "TURN Credentials: Create",
+    description: "Issue short-lived TURN credentials through either the Control plane or Engine API.",
+    rules: [
+      {
+        resource: [
+          "api.turn-server.credentials",
+          "engine.turn-server.credentials"
+        ],
+        action: "create"
+      }
+    ]
+  },
   "tunnels.resources.read-only": {
     name: "Discovery: Read-Only",
     description: "Read active clients, active tunnels, and live state events.",
@@ -1079,13 +1092,13 @@ var engineOpenApiDocument = {
       }
     }
   ],
-  security: [
-    {
-      bearerAuth: []
-    }
-  ],
+  security: [{ bearerAuth: [] }, { mutualTLS: [] }],
   components: {
     securitySchemes: {
+      mutualTLS: {
+        type: "mutualTLS",
+        description: "EE project API only, on the dedicated authority returned by anonymous HTTPS discovery. Present one registered client certificate without a bearer or query token. Ordinary browser-facing hosts never request a client certificate."
+      },
       bearerAuth: {
         type: "http",
         scheme: "bearer",
@@ -1153,6 +1166,64 @@ var engineOpenApiDocument = {
       Forbidden: errorResponse("The token is not authorized.")
     },
     schemas: {
+      EngineDiscovery: {
+        type: "object",
+        required: ["version", "projectEndpoint", "mtlsApiUrl", "capabilities"],
+        properties: {
+          version: { type: "integer", const: 1 },
+          projectEndpoint: { type: "string" },
+          mtlsApiUrl: {
+            type: "string",
+            format: "uri",
+            example: "https://project.mtls.engine.example/api"
+          },
+          capabilities: {
+            type: "array",
+            items: { type: "string" },
+            examples: [["engine-api-mtls", "turn-credentials-v2"]]
+          }
+        }
+      },
+      CreateTURNCredentials: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          ttlSeconds: {
+            type: "integer",
+            minimum: 1,
+            maximum: 3600,
+            default: 600
+          }
+        }
+      },
+      TURNCredentials: {
+        type: "object",
+        required: ["username", "credential", "urls", "ttl"],
+        properties: {
+          username: {
+            type: "string",
+            maxLength: 512,
+            description: "Opaque short-lived v2 issued identity. Do not parse in clients."
+          },
+          credential: {
+            type: "string",
+            maxLength: 1024,
+            description: "Short-lived TURN password."
+          },
+          urls: {
+            type: "array",
+            minItems: 1,
+            maxItems: 16,
+            items: { type: "string", maxLength: 2048 }
+          },
+          ttl: {
+            type: "integer",
+            minimum: 1,
+            maximum: 3600,
+            description: "Effective remaining lifetime in seconds, clipped to identity, source credential and certificate expiry."
+          }
+        }
+      },
       Client: jsonSchemaFor(clientSchema),
       Event: jsonSchemaFor(wsEventsSchema),
       ListClientsParams: jsonSchemaFor(listClientsParamsSchema),
@@ -1187,6 +1258,133 @@ var engineOpenApiDocument = {
     "read-managed-webtty-recordings": ["webtty.logs.read-only"]
   },
   paths: {
+    "/.well-known/rstream/engine": {
+      get: {
+        tags: ["Discovery"],
+        summary: "Discover the dedicated project mTLS API.",
+        operationId: "get_engine_discovery",
+        description: "Anonymous GET on the ordinary project Engine authority. Follow the returned HTTPS URL; do not infer an mTLS hostname. Cache per client using Cache-Control (normally one hour). No certificate, bearer token, cookie or redirect is required. Available only where an explicit EE mapping is configured.",
+        security: [],
+        responses: {
+          "200": {
+            description: "Project-bound discovery. Capabilities describe enabled server features; callers still need the corresponding rights.",
+            headers: {
+              "Cache-Control": {
+                schema: { type: "string" },
+                example: "public, max-age=3600"
+              }
+            },
+            content: {
+              "application/json": {
+                schema: { $ref: "#/components/schemas/EngineDiscovery" }
+              }
+            }
+          },
+          "404": {
+            description: "Dedicated mTLS API is not configured on this authority."
+          }
+        }
+      }
+    },
+    "/api/turn-server/credentials": {
+      post: {
+        tags: ["TURN"],
+        summary: "Issue short-lived project TURN credentials.",
+        operationId: "create_engine_turn_credentials",
+        description: "EE managed projects. Same request and response contract as Control plane project TURN issuance. Empty body is valid. Issued credentials require turn.credentials.create only; turn.relay.allocate applies to local PAT/APP derivation. Issuance does not allocate a relay and does not bypass relay quotas or revocation checks.",
+        security: [{ bearerAuth: [] }, { mutualTLS: [] }],
+        requestBody: {
+          required: false,
+          content: {
+            "application/json": {
+              schema: { $ref: "#/components/schemas/CreateTURNCredentials" }
+            }
+          }
+        },
+        responses: {
+          "200": {
+            description: "Short-lived project TURN credentials.",
+            headers: {
+              "Cache-Control": {
+                schema: { type: "string" },
+                example: "no-store"
+              }
+            },
+            content: {
+              "application/json": {
+                schema: { $ref: "#/components/schemas/TURNCredentials" }
+              }
+            }
+          },
+          "400": {
+            description: "Malformed, unknown or out-of-range request fields; body exceeds 4 KiB.",
+            headers: {
+              "Cache-Control": {
+                schema: { type: "string" },
+                example: "no-store"
+              }
+            }
+          },
+          "401": {
+            description: "Missing, invalid, expired or mixed authentication proofs.",
+            headers: {
+              "Cache-Control": {
+                schema: { type: "string" },
+                example: "no-store"
+              }
+            }
+          },
+          "403": {
+            description: "Missing turn.credentials.create permission, workspace membership or project resource scope.",
+            headers: {
+              "Cache-Control": {
+                schema: { type: "string" },
+                example: "no-store"
+              }
+            }
+          },
+          "404": {
+            description: "Project not found.",
+            headers: {
+              "Cache-Control": {
+                schema: { type: "string" },
+                example: "no-store"
+              }
+            }
+          },
+          "409": {
+            description: "Project or serving infrastructure is inactive.",
+            headers: {
+              "Cache-Control": {
+                schema: { type: "string" },
+                example: "no-store"
+              }
+            }
+          },
+          "429": {
+            description: "Rate limit exceeded; do not retry through another issuer.",
+            headers: {
+              "Cache-Control": {
+                schema: { type: "string" },
+                example: "no-store"
+              }
+            }
+          },
+          "503": {
+            description: "Authentication backend, serving metadata or issued keyring unavailable.",
+            headers: {
+              "Cache-Control": {
+                schema: { type: "string" },
+                example: "no-store"
+              }
+            }
+          }
+        },
+        "x-rstream-required-rules": [
+          { resource: "engine.turn-server.credentials", action: "create" }
+        ]
+      }
+    },
     "/api/openapi.json": {
       get: {
         tags: ["Discovery"],
@@ -1213,7 +1411,7 @@ var engineOpenApiDocument = {
         summary: "List visible engine clients.",
         operationId: "list_engine_clients",
         parameters: [{ $ref: "#/components/parameters/ListClientsParams" }],
-        security: [{ bearerAuth: [] }],
+        security: [{ bearerAuth: [] }, { mutualTLS: [] }],
         responses: {
           "200": jsonArrayResponse(
             "Visible clients.",
@@ -1232,7 +1430,7 @@ var engineOpenApiDocument = {
         summary: "List visible engine tunnels.",
         operationId: "list_engine_tunnels",
         parameters: [{ $ref: "#/components/parameters/ListTunnelsParams" }],
-        security: [{ bearerAuth: [] }],
+        security: [{ bearerAuth: [] }, { mutualTLS: [] }],
         responses: {
           "200": jsonArrayResponse(
             "Visible tunnels. Fine-grained list scopes may filter objects and project fields.",
@@ -1252,7 +1450,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: [] }],
+        security: [{ bearerAuth: [] }, { mutualTLS: [] }],
         responses: {
           "200": streamResponse(
             "SSE stream. Each event is emitted as a data line containing a JSON Event object."
@@ -1271,7 +1469,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: [] }],
+        security: [{ bearerAuth: [] }, { mutualTLS: [] }],
         responses: {
           "101": {
             description: "WebSocket connection accepted. Frames contain JSON Event objects."