@rstreamlabs/tunnels 1.0.0

package/dist/index.mjs

@@ -0,0 +1,1287 @@
+// src/auth-resource.ts
+import { createClientCredentialsToken } from "@rstreamlabs/rstream";
+import { isClientCredentials } from "@rstreamlabs/rstream";
+var RstreamAuthResource = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  async createAuthToken(params, options) {
+    const credentials = options?.credentials || this.client.credentials;
+    if (!isClientCredentials(credentials)) {
+      throw new Error(
+        "Application credentials (client id, client secret) are required to create an auth token."
+      );
+    }
+    const engine = options?.engine ?? await this.client.getEngine().catch(() => void 0);
+    return createAuthTokenFromClientCredentials(credentials, params, {
+      engine
+    });
+  }
+};
+function createAuthTokenFromClientCredentials(credentials, params, options) {
+  const payload = {
+    metadata: {
+      engine: options?.engine,
+      scopes: params?.scopes
+    },
+    permissions: null,
+    project_id: params?.project_id,
+    workspace_id: params?.workspace_id
+  };
+  const { token } = createClientCredentialsToken(credentials, {
+    claims: payload,
+    expiresInSeconds: params?.expires_in
+  });
+  return { token };
+}
+
+// src/zod.ts
+import * as z from "zod";
+var StringFilter = z.union([
+  z.string(),
+  z.object({ exact: z.string() }),
+  z.object({ oneof: z.array(z.string()) }),
+  z.object({ regex: z.string() })
+]);
+function transform(field) {
+  if (field instanceof z.ZodOptional) {
+    return z.optional(transform(field.unwrap()));
+  }
+  if (field instanceof z.ZodString) {
+    return z.optional(StringFilter);
+  }
+  if (field instanceof z.ZodRecord) {
+    return z.optional(z.record(field.keyType, transform(field.valueType)));
+  }
+  return z.optional(field);
+}
+function filters(base) {
+  const entries = Object.entries(base.shape).map(([key, field]) => [
+    key,
+    transform(field)
+  ]);
+  const shape = Object.fromEntries(entries);
+  const node = z.lazy(
+    () => z.union([
+      z.object(shape),
+      z.object({ AND: z.array(node) }),
+      z.object({ OR: z.array(node) })
+    ])
+  );
+  return node;
+}
+function select(base) {
+  const entries = Object.entries(base.shape).map(([key]) => {
+    return [key, z.boolean().optional()];
+  });
+  const shape = Object.fromEntries(entries);
+  return z.object(shape);
+}
+
+// src/tunnel.ts
+import * as z2 from "zod";
+var tunnelSchema = z2.object({
+  // common properties
+  client_id: z2.string(),
+  user_id: z2.string().optional(),
+  workspace_id: z2.string().optional(),
+  project_id: z2.string().optional(),
+  cluster_id: z2.string().optional(),
+  plan: z2.string().optional(),
+  provider: z2.string().optional(),
+  region: z2.string().optional(),
+  status: z2.enum(["online", "offline"]),
+  // tunnel properties
+  id: z2.string(),
+  creation_date: z2.union([z2.string().datetime(), z2.date()]).optional(),
+  name: z2.string().optional(),
+  type: z2.enum(["bytestream", "datagram"]).optional(),
+  publish: z2.boolean().optional(),
+  protocol: z2.enum(["tls", "dtls", "quic", "http"]).optional(),
+  labels: z2.record(z2.string(), z2.string()).optional(),
+  geo_ip: z2.array(z2.string()).optional(),
+  trusted_ips: z2.array(z2.string()).optional(),
+  host: z2.string().optional(),
+  tls_mode: z2.enum(["passthrough", "terminated"]).optional(),
+  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(),
+  http_version: z2.enum(["http/1.1", "h2", "h2c", "h3"]).optional(),
+  http_use_tls: z2.boolean().optional(),
+  token_auth: z2.boolean().optional(),
+  rstream_auth: z2.boolean().optional(),
+  challenge_mode: z2.boolean().optional()
+});
+var listTunnelsParamsSchema = z2.object({
+  limit: z2.number().optional(),
+  filters: tunnelSchema.pick({
+    status: true,
+    client_id: true,
+    protocol: true,
+    publish: true,
+    labels: true
+  }).partial().optional()
+});
+var listTunnelsResponseSchema = z2.array(tunnelSchema);
+
+// src/auth.ts
+import * as z3 from "zod";
+var authTokenPermissionsSchema = z3.array(z3.string());
+var authTokenTunnelsScopesSchema = z3.object({
+  // Scopes for creating tunnels
+  create: z3.union([
+    z3.boolean(),
+    z3.object({
+      filters: filters(
+        tunnelSchema.omit({
+          client_id: true,
+          user_id: true,
+          workspace_id: true,
+          project_id: true,
+          cluster_id: true,
+          plan: true,
+          provider: true,
+          region: true,
+          status: true,
+          id: true,
+          creation_date: true
+        })
+      ).optional()
+    })
+  ]).optional(),
+  // Scopes for connecting to tunnels
+  connect: z3.union([
+    z3.boolean(),
+    z3.object({
+      filters: filters(tunnelSchema).optional(),
+      params: filters(
+        z3.object({
+          path: z3.string().optional()
+        })
+      ).optional()
+    })
+  ]).optional(),
+  // Scopes for listing tunnels
+  list: z3.union([
+    z3.boolean(),
+    z3.object({
+      filters: filters(tunnelSchema).optional(),
+      select: select(tunnelSchema).optional()
+    })
+  ]).optional()
+});
+var authTokenScopesSchema = z3.object({
+  tunnels: authTokenTunnelsScopesSchema.optional()
+  // Scopes related to tunnels
+});
+var authTokenSchema = z3.union([
+  z3.object({
+    type: z3.literal("auth"),
+    userId: z3.string(),
+    permissions: authTokenPermissionsSchema.nullable()
+  }),
+  z3.object({
+    type: z3.literal("pat"),
+    token_endpoint: z3.string().optional()
+  }),
+  z3.object({
+    type: z3.literal("app"),
+    clientId: z3.string(),
+    permissions: authTokenPermissionsSchema.nullable()
+  })
+]).and(
+  z3.object({
+    workspace_id: z3.string().optional(),
+    project_id: z3.string().optional(),
+    metadata: z3.object({
+      engine: z3.string().optional(),
+      scopes: authTokenScopesSchema.optional()
+    }).optional()
+  })
+);
+var tokenSchema = authTokenSchema;
+var createAuthTokenParamsSchema = z3.object({
+  expires_in: z3.number().default(60),
+  // 1 minute
+  workspace_id: z3.string().optional(),
+  project_id: z3.string().optional(),
+  scopes: authTokenScopesSchema.optional(),
+  metadata: z3.unknown().optional()
+  // Additional metadata
+});
+var createAuthTokenResponseSchema = z3.object({
+  token: z3.string()
+});
+
+// src/client.ts
+import * as z4 from "zod";
+var clientSchema = z4.object({
+  id: z4.string(),
+  status: z4.enum(["online", "offline"]),
+  user_id: z4.string().optional(),
+  workspace_id: z4.string().optional(),
+  project_id: z4.string().optional(),
+  cluster_id: z4.string().optional(),
+  plan: z4.string().optional(),
+  provider: z4.string().optional(),
+  region: z4.string().optional(),
+  agent: z4.string().optional(),
+  channel: z4.string().optional(),
+  version: z4.string().optional(),
+  os: z4.string().optional(),
+  arch: z4.string().optional(),
+  protocol_version: z4.string().optional(),
+  labels: z4.record(z4.string(), z4.string()).optional()
+});
+var listClientsParamsSchema = z4.object({
+  limit: z4.number().optional(),
+  filters: clientSchema.pick({
+    labels: true
+  }).partial().optional()
+});
+var listClientsResponseSchema = z4.array(clientSchema);
+
+// src/clients-resource.ts
+var RstreamClientsResource = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  async list(params) {
+    const path = params === void 0 ? "/clients" : `/clients?params=${encodeURIComponent(JSON.stringify(params))}`;
+    const response = await this.client.request(path, {
+      method: "GET"
+    });
+    return listClientsResponseSchema.parse(response);
+  }
+  async get(id) {
+    const response = await this.client.request(`/clients/${id}`, {
+      method: "GET"
+    });
+    return clientSchema.parse(response);
+  }
+};
+
+// src/stream.ts
+import * as z5 from "zod";
+var nonEmptyStringSchema = z5.string().min(1);
+var isoDateTimeSchema = z5.string().datetime();
+var ipAddressSchema = z5.string();
+var intNonNegSchema = z5.number().int().nonnegative();
+var numNonNegSchema = z5.number().nonnegative();
+var geolocationSchema = z5.object({
+  country: z5.string().optional(),
+  region: z5.string().optional()
+});
+var endpointSchema = z5.object({
+  ip: ipAddressSchema.optional(),
+  geolocation: geolocationSchema.optional()
+});
+var httpHeadersSchema = z5.record(
+  z5.string(),
+  z5.union([z5.string(), z5.array(z5.string())])
+);
+var httpProtocolSchema = z5.enum(["http/1.1", "h2", "h2c", "h3"]);
+var httpRequestSchema = z5.object({
+  method: nonEmptyStringSchema,
+  scheme: z5.string().min(1).optional(),
+  host: nonEmptyStringSchema.optional(),
+  path: nonEmptyStringSchema.optional(),
+  query: z5.string().optional(),
+  url: nonEmptyStringSchema.optional(),
+  headers: httpHeadersSchema.optional(),
+  userAgent: z5.string().optional()
+});
+var httpResponseSchema = z5.object({
+  status: z5.number().int().min(100).max(999),
+  headers: httpHeadersSchema.optional()
+});
+var httpRequestStageSchema = z5.object({
+  protocol: httpProtocolSchema.optional(),
+  request: httpRequestSchema
+});
+var httpResponseStageSchema = z5.object({
+  protocol: httpProtocolSchema.optional(),
+  response: httpResponseSchema
+});
+var tokenSourceSchema = z5.enum([
+  "authorization",
+  "query",
+  "client",
+  "unknown"
+]);
+var tokenTypeSchema = z5.enum(["auth", "pat", "app", "unknown"]);
+var firewallRuleSchema = z5.discriminatedUnion("kind", [
+  z5.object({ kind: z5.literal("none") }),
+  z5.object({ kind: z5.literal("mtls") }),
+  z5.object({
+    kind: z5.literal("rstream_auth"),
+    source: z5.literal("rstream_auth")
+  }),
+  z5.object({
+    kind: z5.literal("token"),
+    source: tokenSourceSchema.optional(),
+    tokenType: tokenTypeSchema.optional()
+  })
+]);
+var unauthorizedSourceSchema = z5.object({
+  source: tokenSourceSchema
+});
+var unauthorizedReasonSchema = (shape) => z5.object(shape).merge(unauthorizedSourceSchema);
+var unauthorizedSchema = z5.discriminatedUnion("reason", [
+  unauthorizedReasonSchema({
+    reason: z5.literal("missing_token")
+  }),
+  unauthorizedReasonSchema({
+    reason: z5.literal("invalid_token")
+  }),
+  unauthorizedReasonSchema({
+    reason: z5.literal("expired_token")
+  }),
+  unauthorizedReasonSchema({
+    reason: z5.literal("invalid_secret")
+  }),
+  unauthorizedReasonSchema({
+    reason: z5.literal("user_mismatch")
+  }),
+  unauthorizedReasonSchema({
+    reason: z5.literal("policy_denied"),
+    policy: z5.enum(["ip", "geo", "mtls", "challenge", "other"]),
+    value: z5.string().optional()
+  })
+]);
+var failureSchema = z5.discriminatedUnion("kind", [
+  z5.object({
+    kind: z5.literal("timeout"),
+    timeoutMs: intNonNegSchema.optional(),
+    message: z5.string().optional()
+  }),
+  z5.object({
+    kind: z5.literal("unauthorized"),
+    why: unauthorizedSchema,
+    message: z5.string().optional()
+  }),
+  z5.object({
+    kind: z5.literal("not_found"),
+    resource: z5.enum(["tunnel", "client", "route"]),
+    message: z5.string().optional()
+  }),
+  z5.object({
+    kind: z5.literal("refused"),
+    reason: z5.enum(["capacity", "policy", "unsupported", "other"]),
+    message: z5.string().optional()
+  }),
+  z5.object({ kind: z5.literal("io"), message: z5.string().optional() }),
+  z5.object({ kind: z5.literal("internal"), message: z5.string().optional() })
+]);
+var firewallSchema = z5.discriminatedUnion("decision", [
+  z5.object({ decision: z5.literal("allowed"), rule: firewallRuleSchema }),
+  z5.object({
+    decision: z5.literal("denied"),
+    rule: firewallRuleSchema,
+    failure: failureSchema
+  })
+]);
+var routedTunnelSchema = z5.object({
+  tunnelId: nonEmptyStringSchema.optional(),
+  tunnelName: z5.string().optional(),
+  protocol: z5.string().optional(),
+  published: z5.boolean().optional(),
+  type: z5.string().optional(),
+  tlsMode: z5.string().optional(),
+  httpVersion: z5.string().optional(),
+  httpUseTls: z5.boolean().optional(),
+  tokenAuth: z5.boolean().optional(),
+  mtls: z5.boolean().optional()
+});
+var routingSchema = z5.discriminatedUnion("decision", [
+  z5.object({ decision: z5.literal("routed"), tunnel: routedTunnelSchema }),
+  z5.object({ decision: z5.literal("not_routed"), failure: failureSchema })
+]);
+var streamConnectedMetricsSchema = z5.object({
+  establish_ms: numNonNegSchema,
+  duration_ms: numNonNegSchema,
+  upstream_bytes: intNonNegSchema,
+  downstream_bytes: intNonNegSchema
+});
+var streamFailedMetricsSchema = z5.object({
+  time_to_fail_ms: numNonNegSchema.optional(),
+  establish_ms: numNonNegSchema.optional()
+});
+var terminationSchema = z5.object({
+  by: z5.enum(["downstream", "upstream", "server", "unknown"]),
+  reason: z5.enum(["closed", "reset", "timeout", "error", "unknown"]),
+  message: z5.string().optional()
+});
+var responseConnectedSchema = z5.object({
+  outcome: z5.literal("connected"),
+  established_at: isoDateTimeSchema,
+  upstream: endpointSchema.optional(),
+  metrics: streamConnectedMetricsSchema,
+  termination: terminationSchema.optional(),
+  http: httpResponseStageSchema.optional()
+});
+var responseFailedSchema = z5.object({
+  outcome: z5.literal("failed"),
+  failure: failureSchema,
+  upstream: endpointSchema.optional(),
+  metrics: streamFailedMetricsSchema.optional(),
+  termination: terminationSchema.optional(),
+  http: httpResponseStageSchema.optional()
+});
+var responseSchema = z5.discriminatedUnion("outcome", [
+  responseConnectedSchema,
+  responseFailedSchema
+]);
+var streamSummarySchema = z5.object({
+  workspace_id: nonEmptyStringSchema.optional(),
+  project_id: nonEmptyStringSchema.optional(),
+  cluster_id: nonEmptyStringSchema.optional(),
+  user_id: nonEmptyStringSchema.optional(),
+  client_id: nonEmptyStringSchema.optional(),
+  tunnel_id: nonEmptyStringSchema.optional(),
+  stream_id: nonEmptyStringSchema,
+  created_at: isoDateTimeSchema,
+  terminated_at: isoDateTimeSchema,
+  request: z5.object({
+    downstream: endpointSchema,
+    http: httpRequestStageSchema.optional()
+  }),
+  firewall: firewallSchema,
+  routing: routingSchema,
+  response: responseSchema
+});
+
+// src/event.ts
+import * as z6 from "zod";
+var isoDateTimeSchema2 = z6.string().datetime();
+var initialStateSchema = z6.object({
+  snapshot_at: isoDateTimeSchema2,
+  clients: z6.array(clientSchema),
+  tunnels: z6.array(tunnelSchema)
+});
+var eventBaseSchema = z6.object({
+  id: z6.string().optional(),
+  created_at: isoDateTimeSchema2.optional(),
+  user_id: z6.string().optional(),
+  workspace_id: z6.string().optional(),
+  project_id: z6.string().optional(),
+  cluster_id: z6.string().optional()
+});
+var withEventBase = (shape) => z6.object(shape).merge(eventBaseSchema).passthrough();
+var stateInitialEventSchema = withEventBase({
+  type: z6.literal("state.initial"),
+  object: initialStateSchema
+});
+var streamSummaryEventSchema = withEventBase({
+  type: z6.literal("stream.summary"),
+  object: streamSummarySchema
+});
+var commonEventsSchema = [
+  withEventBase({
+    type: z6.literal("client.created"),
+    object: clientSchema
+  }),
+  withEventBase({
+    type: z6.literal("client.updated"),
+    object: clientSchema
+  }),
+  withEventBase({
+    type: z6.literal("client.deleted"),
+    object: clientSchema
+  }),
+  withEventBase({
+    type: z6.literal("tunnel.created"),
+    object: tunnelSchema
+  }),
+  withEventBase({
+    type: z6.literal("tunnel.updated"),
+    object: tunnelSchema
+  }),
+  withEventBase({
+    type: z6.literal("tunnel.deleted"),
+    object: tunnelSchema
+  })
+];
+var wsEventsSchema = z6.union([
+  stateInitialEventSchema,
+  ...commonEventsSchema
+]);
+var webhookEventsSchema = z6.union([
+  ...commonEventsSchema,
+  streamSummaryEventSchema
+]);
+var eventSchema = z6.union([wsEventsSchema, webhookEventsSchema]);
+
+// src/resolution.ts
+import { DEFAULT_API_URL } from "@rstreamlabs/rstream";
+import { getTunnelsProjectEngine } from "@rstreamlabs/rstream";
+import { isTokenCredentials } from "@rstreamlabs/rstream";
+import { readEnvironment } from "@rstreamlabs/rstream";
+import { RstreamClient } from "@rstreamlabs/rstream";
+import jwt from "jsonwebtoken";
+function trimOptionalString(value) {
+  const normalized = value?.trim();
+  return normalized ? normalized : void 0;
+}
+function getEngineFromToken(token) {
+  if (!token) {
+    return void 0;
+  }
+  const parsed = authTokenSchema.safeParse(
+    jwt.decode(token, { complete: false })
+  );
+  if (!parsed.success) {
+    return void 0;
+  }
+  return trimOptionalString(parsed.data.metadata?.engine);
+}
+function resolveTunnelsAPIURL(apiUrl) {
+  return trimOptionalString(apiUrl) ?? readEnvironment().apiUrl ?? DEFAULT_API_URL;
+}
+function resolveTunnelsCredentials(credentials) {
+  if (credentials !== void 0) {
+    return credentials;
+  }
+  const token = readEnvironment().token;
+  if (!token) {
+    return void 0;
+  }
+  return { token };
+}
+function resolveControlPlaneCredentials(controlPlaneCredentials, credentials, authToken) {
+  if (controlPlaneCredentials !== void 0) {
+    return controlPlaneCredentials;
+  }
+  if (credentials !== void 0) {
+    return credentials;
+  }
+  if (authToken) {
+    return { token: authToken };
+  }
+  const environmentToken = readEnvironment().token;
+  if (!environmentToken) {
+    return void 0;
+  }
+  return { token: environmentToken };
+}
+async function resolveTunnelsEngine(config) {
+  const explicitEngine = trimOptionalString(config.engine);
+  if (explicitEngine) {
+    return explicitEngine;
+  }
+  const environmentEngine = readEnvironment().engine;
+  if (environmentEngine) {
+    return environmentEngine;
+  }
+  const token = trimOptionalString(config.token) ?? (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,
+      token
+    );
+    if (credentials === void 0) {
+      throw new Error(
+        "Control-plane credentials are required to resolve a managed project endpoint."
+      );
+    }
+    const controlPlane = new RstreamClient({
+      apiUrl: resolveTunnelsAPIURL(config.apiUrl),
+      credentials
+    });
+    const project = await controlPlane.tunnels.projects.resolveByEndpoint(projectEndpoint);
+    const engine = getTunnelsProjectEngine(project);
+    if (engine) {
+      return 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."
+  );
+}
+
+// src/tunnels-resource.ts
+var RstreamTunnelsResource = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  async list(params) {
+    const path = params === void 0 ? "/tunnels" : `/tunnels?params=${encodeURIComponent(JSON.stringify(params))}`;
+    const response = await this.client.request(path, {
+      method: "GET"
+    });
+    return listTunnelsResponseSchema.parse(response);
+  }
+  async get(id) {
+    const response = await this.client.request(`/tunnels/${id}`, {
+      method: "GET"
+    });
+    return tunnelSchema.parse(response);
+  }
+};
+
+// src/tunnels.ts
+import { isClientCredentials as isClientCredentials3 } from "@rstreamlabs/rstream";
+
+// src/turn.ts
+import { isClientCredentials as isClientCredentials2 } from "@rstreamlabs/rstream";
+import { isTokenCredentials as isTokenCredentials2 } from "@rstreamlabs/rstream";
+import { RstreamClient as RstreamClient2 } from "@rstreamlabs/rstream";
+import { turnCredentialsSchema } from "@rstreamlabs/rstream";
+import * as z7 from "zod";
+import crypto from "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 turnCredentialModeSchema = z7.enum(["api", "app", "pat"]);
+function normalizeOptionalString(value) {
+  const normalized = value?.trim();
+  return normalized ? normalized : void 0;
+}
+function normalizeClusterDomain(clusterDomain) {
+  const normalized = normalizeOptionalString(clusterDomain);
+  return normalized?.toLowerCase();
+}
+function normalizeNow(now) {
+  if (now instanceof Date) {
+    return Math.floor(now.getTime() / 1e3);
+  }
+  if (typeof now === "number" && Number.isFinite(now)) {
+    return Math.floor(now);
+  }
+  return Math.floor(Date.now() / 1e3);
+}
+function normalizeTTLSeconds(ttlSeconds) {
+  if (typeof ttlSeconds === "number" && Number.isFinite(ttlSeconds) && ttlSeconds > 0) {
+    return Math.floor(ttlSeconds);
+  }
+  return defaultTURNCredentialTTLSeconds;
+}
+function normalizeTURNPort(port) {
+  if (typeof port === "number" && Number.isFinite(port) && port > 0) {
+    return Math.floor(port);
+  }
+  return defaultTURNPort;
+}
+function normalizeTURNSPort(port) {
+  if (typeof port === "number" && Number.isFinite(port) && port > 0) {
+    return Math.floor(port);
+  }
+  return defaultTURNSPort;
+}
+function createTURNURLs(clusterDomain, turnPort, turnsPort) {
+  const normalizedTURNPort = normalizeTURNPort(turnPort);
+  const normalizedTURNSPort = normalizeTURNSPort(turnsPort);
+  return [
+    `turn:${clusterDomain}:${normalizedTURNPort}?transport=udp`,
+    `turn:${clusterDomain}:${normalizedTURNPort}?transport=tcp`,
+    `turns:${clusterDomain}:${normalizedTURNSPort}?transport=udp`,
+    `turns:${clusterDomain}:${normalizedTURNSPort}?transport=tcp`
+  ];
+}
+function parseTURNTokenClaims(token) {
+  const parts = token.split(".");
+  const payloadPart = parts.at(1);
+  if (!payloadPart) {
+    throw new Error("Invalid token format.");
+  }
+  const payload = Buffer.from(payloadPart, "base64url").toString("utf8");
+  const parsed = turnTokenClaimsSchema.safeParse(JSON.parse(payload));
+  if (!parsed.success) {
+    throw new Error("Invalid token format.");
+  }
+  return parsed.data;
+}
+function deriveClusterDomainFromEngine(projectEndpoint, engine) {
+  const normalizedProjectEndpoint = normalizeOptionalString(projectEndpoint);
+  const normalizedEngine = normalizeOptionalString(engine);
+  if (!normalizedProjectEndpoint || !normalizedEngine) {
+    throw new Error(
+      "Failed to derive the cluster domain from the engine address."
+    );
+  }
+  const url = new URL(`https://${normalizedEngine}`);
+  const prefix = `${normalizedProjectEndpoint}.`;
+  if (!url.hostname.startsWith(prefix)) {
+    throw new Error(
+      "Failed to derive the cluster domain from the engine address."
+    );
+  }
+  const clusterDomain = url.hostname.slice(prefix.length);
+  if (!clusterDomain) {
+    throw new Error(
+      "Failed to derive the cluster domain from the engine address."
+    );
+  }
+  return clusterDomain;
+}
+function requireOption(value, message) {
+  if (value) {
+    return value;
+  }
+  throw new Error(message);
+}
+function resolveMode(credentials, mode) {
+  if (mode !== void 0) {
+    return turnCredentialModeSchema.parse(mode);
+  }
+  if (isClientCredentials2(credentials)) {
+    return "app";
+  }
+  if (isTokenCredentials2(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 url = new URL(
+    `/keyrings/turn/${clusterDomain}.spki.der.hex`,
+    keyringBaseURL
+  );
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error("Failed to load TURN keyring.");
+  }
+  return (await response.text()).trim();
+}
+async function createAPITURNCredentials(options) {
+  const projectId = normalizeOptionalString(options.projectId);
+  const projectEndpoint = normalizeOptionalString(options.projectEndpoint);
+  if (!projectId && !projectEndpoint) {
+    throw new Error(
+      "Project ID or project endpoint is required for TURN API mode."
+    );
+  }
+  const client = new RstreamClient2({
+    apiUrl: options.apiUrl,
+    credentials: options.credentials
+  });
+  if (projectId) {
+    return await client.tunnels.projects.createTurnCredentials(projectId);
+  }
+  if (!projectEndpoint) {
+    throw new Error(
+      "Project ID or project endpoint is required for TURN API mode."
+    );
+  }
+  return await client.tunnels.projects.createTurnCredentialsByEndpoint(
+    projectEndpoint
+  );
+}
+function createPATTURNCredentials(options) {
+  const clusterDomain = normalizeClusterDomain(options.clusterDomain);
+  if (!clusterDomain) {
+    throw new Error("Cluster domain is required for TURN PAT mode.");
+  }
+  const projectEndpoint = normalizeOptionalString(options.projectEndpoint);
+  if (!projectEndpoint) {
+    throw new Error("Project endpoint is required for TURN PAT mode.");
+  }
+  const token = normalizeOptionalString(options.token);
+  if (!token) {
+    throw new Error("Token is required for TURN PAT mode.");
+  }
+  const claims = parseTURNTokenClaims(token);
+  if (claims.type !== "pat") {
+    throw new Error("TURN PAT mode requires a PAT token.");
+  }
+  const tokenEndpoint = normalizeOptionalString(claims.token_endpoint);
+  if (!tokenEndpoint) {
+    throw new Error(
+      "TURN PAT mode requires a PAT token carrying a token endpoint."
+    );
+  }
+  const ttlSeconds = normalizeTTLSeconds(options.ttlSeconds);
+  const exp = normalizeNow(options.now) + ttlSeconds;
+  const username = `v1:${exp}:pat:${projectEndpoint}:${tokenEndpoint}`;
+  const tokenHash = crypto.createHash("sha256").update(token, "utf8").digest();
+  const key = Buffer.from(
+    crypto.hkdfSync(
+      "sha256",
+      tokenHash,
+      Buffer.from(clusterDomain, "utf8"),
+      Buffer.from("turn-pat-v1", "utf8"),
+      32
+    )
+  );
+  const credential = crypto.createHmac("sha256", key).update(username, "utf8").digest("base64");
+  return turnCredentialsSchema.parse({
+    credential,
+    ttl: ttlSeconds,
+    urls: createTURNURLs(clusterDomain, options.turnPort, options.turnsPort),
+    username
+  });
+}
+async function createAPPTURNCredentials(options) {
+  const clusterDomain = normalizeClusterDomain(options.clusterDomain);
+  if (!clusterDomain) {
+    throw new Error("Cluster domain is required for TURN APP mode.");
+  }
+  const projectEndpoint = normalizeOptionalString(options.projectEndpoint);
+  if (!projectEndpoint) {
+    throw new Error("Project endpoint is required for TURN APP mode.");
+  }
+  const clientId = normalizeOptionalString(options.clientId);
+  if (!clientId) {
+    throw new Error("Client ID is required for TURN APP mode.");
+  }
+  const clientSecret = normalizeOptionalString(options.clientSecret);
+  if (!clientSecret) {
+    throw new Error("Client secret is required for TURN APP mode.");
+  }
+  const ttlSeconds = normalizeTTLSeconds(options.ttlSeconds);
+  const exp = normalizeNow(options.now) + ttlSeconds;
+  const username = `v1:${exp}:app:${projectEndpoint}:${clientId}`;
+  const clientPrivateKey = crypto.createPrivateKey({
+    key: Buffer.from(clientSecret, "hex"),
+    format: "der",
+    type: "pkcs8"
+  });
+  const serverPublicKeyHex = normalizeOptionalString(options.serverPublicKeyHex) ?? await loadTURNServerPublicKeyHex(clusterDomain, options);
+  const serverPublicKey = crypto.createPublicKey({
+    key: Buffer.from(serverPublicKeyHex, "hex"),
+    format: "der",
+    type: "spki"
+  });
+  const sharedSecret = crypto.diffieHellman({
+    privateKey: clientPrivateKey,
+    publicKey: serverPublicKey
+  });
+  const key = Buffer.from(
+    crypto.hkdfSync(
+      "sha256",
+      sharedSecret,
+      Buffer.from(clusterDomain, "utf8"),
+      Buffer.from("turn-app-v1", "utf8"),
+      32
+    )
+  );
+  const credential = crypto.createHmac("sha256", key).update(username, "utf8").digest("base64");
+  return turnCredentialsSchema.parse({
+    credential,
+    ttl: ttlSeconds,
+    urls: createTURNURLs(clusterDomain, options.turnPort, options.turnsPort),
+    username
+  });
+}
+async function createTURNCredentials(options) {
+  const credentials = options.credentials;
+  const mode = resolveMode(credentials, options.mode);
+  const projectEndpoint = normalizeOptionalString(options.projectEndpoint);
+  if (mode === "api") {
+    const controlPlaneCredentials = options.controlPlaneCredentials ?? credentials;
+    if (!controlPlaneCredentials) {
+      throw new Error(
+        "Control-plane credentials are required for TURN API mode."
+      );
+    }
+    return await createAPITURNCredentials({
+      apiUrl: options.apiUrl,
+      credentials: controlPlaneCredentials,
+      projectEndpoint,
+      projectId: options.projectId
+    });
+  }
+  const clusterDomain = normalizeClusterDomain(options.clusterDomain) ?? (projectEndpoint && options.engine ? deriveClusterDomainFromEngine(projectEndpoint, options.engine) : void 0);
+  if (mode === "pat") {
+    if (!isTokenCredentials2(credentials)) {
+      throw new Error("A PAT token is required for TURN PAT mode.");
+    }
+    return createPATTURNCredentials({
+      clusterDomain: requireOption(
+        clusterDomain,
+        "Cluster domain is required for TURN PAT mode."
+      ),
+      now: options.now,
+      projectEndpoint: requireOption(
+        projectEndpoint,
+        "Project endpoint is required for TURN PAT mode."
+      ),
+      token: credentials.token,
+      ttlSeconds: options.ttlSeconds,
+      turnPort: options.turnPort,
+      turnsPort: options.turnsPort
+    });
+  }
+  if (!isClientCredentials2(credentials)) {
+    throw new Error("Client credentials are required for TURN APP mode.");
+  }
+  return await createAPPTURNCredentials({
+    apiUrl: options.apiUrl,
+    clientId: credentials.clientId,
+    clientSecret: credentials.clientSecret,
+    clusterDomain: requireOption(
+      clusterDomain,
+      "Cluster domain is required for TURN APP mode."
+    ),
+    keyringBaseUrl: options.keyringBaseUrl,
+    now: options.now,
+    projectEndpoint: requireOption(
+      projectEndpoint,
+      "Project endpoint is required for TURN APP mode."
+    ),
+    serverPublicKeyHex: options.serverPublicKeyHex,
+    ttlSeconds: options.ttlSeconds,
+    turnPort: options.turnPort,
+    turnsPort: options.turnsPort
+  });
+}
+
+// src/turn-resource.ts
+var RstreamTURNResource = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  async createCredentials(options = {}) {
+    const engine = options.engine ?? (options.clusterDomain === void 0 ? await this.client.getEngine().catch(() => void 0) : void 0);
+    return await createTURNCredentials({
+      apiUrl: options.apiUrl ?? this.client.apiUrl,
+      clusterDomain: options.clusterDomain,
+      controlPlaneCredentials: options.controlPlaneCredentials ?? this.client.controlPlaneCredentials,
+      credentials: options.credentials ?? this.client.credentials,
+      engine,
+      keyringBaseUrl: options.keyringBaseUrl,
+      mode: options.mode,
+      now: options.now,
+      projectEndpoint: options.projectEndpoint ?? this.client.projectEndpoint,
+      projectId: options.projectId,
+      serverPublicKeyHex: options.serverPublicKeyHex,
+      ttlSeconds: options.ttlSeconds,
+      turnPort: options.turnPort,
+      turnsPort: options.turnsPort
+    });
+  }
+};
+
+// src/webhooks-resource.ts
+import crypto2 from "crypto";
+var RstreamWebhookResource = class {
+  async event(payload, header, secret, tolerance = 300, receivedAt = Date.now()) {
+    const payloadBuffer = Buffer.isBuffer(payload) ? payload : Buffer.from(payload);
+    const signatureHeader = Array.isArray(header) ? header[0] : header.toString();
+    if (!signatureHeader) {
+      throw new Error("No signature header");
+    }
+    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 now = Math.floor(receivedAt / 1e3);
+    if (Math.abs(now - timestampNum) > tolerance) {
+      throw new Error(
+        `Webhook signature timestamp outside tolerance: ${now}, ${timestampNum}`
+      );
+    }
+    const signedPayload = `${timestamp}.${payloadBuffer.toString("utf8")}`;
+    const expectedSignature = crypto2.createHmac("sha256", secret).update(signedPayload).digest("hex");
+    const signatureMatched = signatures.some((signature) => {
+      try {
+        return crypto2.timingSafeEqual(
+          Buffer.from(signature),
+          Buffer.from(expectedSignature)
+        );
+      } catch {
+        return false;
+      }
+    });
+    if (!signatureMatched) {
+      throw new Error("Signature verification failed");
+    }
+    try {
+      return webhookEventsSchema.parse(
+        JSON.parse(payloadBuffer.toString("utf8"))
+      );
+    } catch (error) {
+      throw new Error(
+        `Failed to parse webhook payload: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
+      );
+    }
+  }
+};
+
+// src/tunnels.ts
+var RstreamTunnelsClient = class {
+  config;
+  constructor(config) {
+    this.config = config;
+  }
+  get apiUrl() {
+    return resolveTunnelsAPIURL(this.config?.apiUrl);
+  }
+  get credentials() {
+    return resolveTunnelsCredentials(this.config?.credentials);
+  }
+  get controlPlaneCredentials() {
+    return resolveControlPlaneCredentials(
+      this.config?.controlPlaneCredentials,
+      this.credentials
+    );
+  }
+  get projectEndpoint() {
+    return this.config?.projectEndpoint;
+  }
+  async getEngine() {
+    return await resolveTunnelsEngine({
+      apiUrl: this.config?.apiUrl,
+      controlPlaneCredentials: this.controlPlaneCredentials,
+      credentials: this.credentials,
+      engine: this.config?.engine,
+      projectEndpoint: this.config?.projectEndpoint
+    });
+  }
+  get auth() {
+    return new RstreamAuthResource(this);
+  }
+  get clients() {
+    return new RstreamClientsResource(this);
+  }
+  get tunnels() {
+    return new RstreamTunnelsResource(this);
+  }
+  get webhooks() {
+    return new RstreamWebhookResource();
+  }
+  get turn() {
+    return new RstreamTURNResource(this);
+  }
+  async getToken(engine) {
+    const credentials = this.credentials;
+    if (!credentials) {
+      return void 0;
+    }
+    if (!isClientCredentials3(credentials)) {
+      return credentials.token;
+    }
+    return (await this.auth.createAuthToken(void 0, {
+      credentials,
+      engine
+    })).token;
+  }
+  async request(path, options) {
+    const engine = await this.getEngine();
+    const url = `https://${engine}/api${path}`;
+    const headers = new Headers(options?.headers || {});
+    const token = await this.getToken(engine);
+    if (token) {
+      headers.set("Authorization", `Bearer ${token}`);
+    }
+    const response = await fetch(url, {
+      ...options,
+      headers
+    });
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`HTTP error ${response.status}: ${errorText}`);
+    }
+    return await response.json();
+  }
+};
+
+// src/watch.ts
+var Watch = class {
+  connection = null;
+  connectionState = "preparing";
+  config;
+  events;
+  constructor(config, events) {
+    this.config = config;
+    this.events = events;
+  }
+  async connect() {
+    if (this.connectionState !== "preparing") {
+      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();
+      }
+    };
+    if (this.connection instanceof WebSocket) {
+      this.connection.onclose = () => {
+        if (this.connectionState !== "closed") {
+          this.disconnect();
+        }
+      };
+    }
+  }
+  disconnect() {
+    if (this.connection) {
+      this.connection.onerror = null;
+      this.connection.onmessage = null;
+      this.connection.onopen = null;
+      this.connection.close();
+      this.connection = null;
+    }
+    if (this.connectionState !== "closed") {
+      this.connectionState = "closed";
+      this.events.onClose?.();
+    }
+  }
+};
+
+// src/webtty.ts
+import * as z8 from "zod";
+var osFamilies = [
+  "linux",
+  "macos",
+  "windows",
+  "netbsd",
+  "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(),
+  // /etc/os-release::ID (ubuntu, debian, rocky, etc.)
+  os_version_id: z8.string().optional(),
+  // /etc/os-release::VERSION_ID (24.04, 22.04, 11, 10.0.19045, ...)
+  os_version_codename: z8.string().optional(),
+  // /etc/os-release::VERSION_CODENAME (jammy, noble...)
+  os_pretty_name: z8.string().optional(),
+  // /etc/os-release::PRETTY_NAME
+  kernel_release: z8.string().optional(),
+  // uname -r
+  hostname: z8.string().optional(),
+  // uname -n
+  labels: z8.record(z8.string(), z8.string().optional()).optional()
+});
+function parser(tunnel) {
+  if (tunnel.status !== "online") return null;
+  if (tunnel.publish !== true) return null;
+  if (tunnel.protocol !== "http") return null;
+  const tunnelLabels = tunnel.labels ?? {};
+  if (tunnelLabels["application-protocol"] !== "rstream.webtty") {
+    return null;
+  }
+  const labels = {};
+  for (const [key, value] of Object.entries(tunnelLabels)) {
+    if (!key.startsWith("rstream.webtty.label.")) continue;
+    const labelKey = key.slice("rstream.webtty.label.".length);
+    if (labelKey.length === 0) continue;
+    labels[labelKey] = value;
+  }
+  const candidate = {
+    tunnel_id: tunnel.id,
+    host: tunnel.host,
+    token_auth: tunnel.token_auth === true,
+    os_family: tunnelLabels["rstream.webtty.os_family"],
+    arch: tunnelLabels["rstream.webtty.arch"],
+    os_id: tunnelLabels["rstream.webtty.os_id"],
+    os_version_id: tunnelLabels["rstream.webtty.os_version_id"],
+    os_version_codename: tunnelLabels["rstream.webtty.os_version_codename"],
+    os_pretty_name: tunnelLabels["rstream.webtty.os_pretty_name"],
+    kernel_release: tunnelLabels["rstream.webtty.kernel_release"],
+    hostname: tunnelLabels["rstream.webtty.hostname"],
+    labels: Object.keys(labels).length > 0 ? labels : void 0
+  };
+  const parsed = webttyServerSchema.safeParse(candidate);
+  if (!parsed.success) return null;
+  return parsed.data;
+}
+function parseWebTTYServers(tunnels) {
+  return tunnels.map((tunnel) => parser(tunnel)).filter((server) => server !== null);
+}
+export {
+  RstreamAuthResource,
+  RstreamAuthResource as RstreamAuthRessource,
+  RstreamTunnelsClient as RstreamClient,
+  RstreamClientsResource,
+  RstreamClientsResource as RstreamClientsRessource,
+  RstreamTURNResource,
+  RstreamTunnelsClient,
+  RstreamTunnelsResource,
+  RstreamTunnelsResource as RstreamTunnelsRessource,
+  RstreamWebhookResource,
+  RstreamWebhookResource as RstreamWebhookRessource,
+  RstreamTunnelsClient as Tunnels,
+  Watch,
+  authTokenPermissionsSchema,
+  authTokenSchema,
+  authTokenScopesSchema,
+  authTokenTunnelsScopesSchema,
+  clientSchema,
+  createAPITURNCredentials,
+  createAPPTURNCredentials,
+  createAuthTokenFromClientCredentials,
+  createAuthTokenParamsSchema,
+  createAuthTokenResponseSchema,
+  createPATTURNCredentials,
+  createTURNCredentials,
+  eventSchema,
+  listClientsParamsSchema,
+  listClientsResponseSchema,
+  listTunnelsParamsSchema,
+  listTunnelsResponseSchema,
+  parseWebTTYServers,
+  resolveControlPlaneCredentials,
+  resolveTunnelsAPIURL,
+  resolveTunnelsCredentials,
+  resolveTunnelsEngine,
+  streamSummarySchema,
+  tokenSchema,
+  tunnelSchema,
+  turnCredentialModeSchema,
+  webhookEventsSchema,
+  webttyServerSchema,
+  wsEventsSchema
+};