feat: default control plane and API_TOKEN tunnel auth

Default SPAWNDOCK_CONTROL_PLANE to production when unset; allow WebSocket
auth via API_TOKEN query param alongside legacy device secret.

Made-with: Cursor

Author: ilyar

README.md

@@ -39,11 +39,14 @@ npx @spawn-dock/dev-tunnel \
 ```bash
 export SPAWNDOCK_CONTROL_PLANE=http://your-server:3000
 export SPAWNDOCK_PROJECT_SLUG=my-app
-export SPAWNDOCK_DEVICE_SECRET=your-device-secret
+export API_TOKEN=your-shared-api-token
 export SPAWNDOCK_PORT=3000
 npx @spawn-dock/dev-tunnel
 ```
 
+`API_TOKEN` is the preferred auth mode for standalone package usage.
+`SPAWNDOCK_DEVICE_SECRET` remains supported for bootstrap-generated project credentials.
+
 ## Configuration Priority
 
 CLI arguments > Environment variables > `spawndock.dev-tunnel.json` > legacy `spawndock.config.json`

package-lock.json

@@ -26,6 +26,14 @@ describe("resolveConfig", () => {
     expect(() => resolveConfig([])).toThrow("Missing");
   });
 
+  it("allows auth via API_TOKEN without device secret", () => {
+    vi.stubEnv("SPAWNDOCK_PROJECT_SLUG", "my-app");
+    vi.stubEnv("API_TOKEN", "shared_token");
+    const config = resolveConfig([]);
+    expect(config.controlPlane).toBe("https://spawn-dock.w3voice.net");
+    expect(config.apiToken).toBe("shared_token");
+  });
+
   it("defaults port to 3000", () => {
     const config = resolveConfig([
       "--control-plane", "http://localhost:8787",

src/__tests__/config.test.ts

@@ -15,4 +15,17 @@ describe("buildWsUrl", () => {
       "wss://api.example.com/tunnel/connect?protocolVersion=1&token=secret123",
     );
   });
+
+  it("includes apiToken query param when API_TOKEN is used", () => {
+    const url = buildWsUrl({
+      controlPlane: "https://api.example.com",
+      projectSlug: "demo",
+      apiToken: "shared_token",
+      port: 3000,
+    });
+
+    expect(url).toBe(
+      "wss://api.example.com/tunnel/connect?protocolVersion=1&apiToken=shared_token",
+    );
+  });
 });

src/__tests__/tunnel.test.ts

@@ -4,7 +4,8 @@ import { resolve } from "node:path";
 export interface TunnelConfig {
   controlPlane: string;
   projectSlug: string;
-  deviceSecret: string;
+  deviceSecret?: string;
+  apiToken?: string;
   port: number;
   previewPath?: string;
   telegramMiniAppUrl?: string;
@@ -42,6 +43,10 @@ function normalizeConfig(data: unknown): Partial<TunnelConfig> {
       : typeof record.deviceToken === "string"
         ? record.deviceToken
         : undefined;
+  const apiToken =
+    typeof record.apiToken === "string"
+      ? record.apiToken
+      : undefined;
   const port =
     typeof record.port === "number"
       ? record.port
@@ -53,7 +58,7 @@ function normalizeConfig(data: unknown): Partial<TunnelConfig> {
   const telegramMiniAppUrl =
     typeof record.telegramMiniAppUrl === "string" ? record.telegramMiniAppUrl : undefined;
 
-  return { controlPlane, projectSlug, deviceSecret, port, previewPath, telegramMiniAppUrl };
+  return { controlPlane, projectSlug, deviceSecret, apiToken, port, previewPath, telegramMiniAppUrl };
 }
 
 function readConfigFile(dir: string): Partial<TunnelConfig> {
@@ -139,20 +144,24 @@ export function resolveConfig(
     controlPlane: process.env.SPAWNDOCK_CONTROL_PLANE,
     projectSlug: process.env.SPAWNDOCK_PROJECT_SLUG,
     deviceSecret: process.env.SPAWNDOCK_DEVICE_SECRET,
+    apiToken: process.env.API_TOKEN || process.env.SPAWNDOCK_API_TOKEN,
     port: readNumber(process.env.SPAWNDOCK_PORT),
   };
 
   // Priority: CLI > Env > File
-  const controlPlane = args.controlPlane ?? env.controlPlane ?? file.controlPlane;
+  const controlPlane = args.controlPlane ?? env.controlPlane ?? file.controlPlane ?? "https://spawn-dock.w3voice.net";
   const projectSlug = args.projectSlug ?? env.projectSlug ?? file.projectSlug;
   const deviceSecret = args.deviceSecret ?? env.deviceSecret ?? file.deviceSecret;
+  const apiToken = env.apiToken ?? file.apiToken;
   const port = args.port ?? env.port ?? file.port ?? 3000;
   const previewPath = file.previewPath;
   const telegramMiniAppUrl = file.telegramMiniAppUrl;
 
   if (!controlPlane) throw new Error("Missing --control-plane or SPAWNDOCK_CONTROL_PLANE");
   if (!projectSlug) throw new Error("Missing --project-slug or SPAWNDOCK_PROJECT_SLUG");
-  if (!deviceSecret) throw new Error("Missing --device-secret or SPAWNDOCK_DEVICE_SECRET");
+  if (!deviceSecret && !apiToken) {
+    throw new Error("Missing authentication: set API_TOKEN (preferred) or --device-secret");
+  }
 
-  return { controlPlane, projectSlug, deviceSecret, port, previewPath, telegramMiniAppUrl };
+  return { controlPlane, projectSlug, deviceSecret, apiToken, port, previewPath, telegramMiniAppUrl };
 }

src/config.ts

@@ -45,7 +45,12 @@ export function buildWsUrl(config: TunnelConfig): string {
   const currentPath = url.pathname.replace(/\/+$/, "");
   url.pathname = currentPath.length === 0 ? "/tunnel/connect" : `${currentPath}/tunnel/connect`;
   url.searchParams.set("protocolVersion", "1");
-  url.searchParams.set("token", config.deviceSecret);
+  if (config.deviceSecret && config.deviceSecret.length > 0) {
+    url.searchParams.set("token", config.deviceSecret);
+  }
+  if (config.apiToken && config.apiToken.length > 0) {
+    url.searchParams.set("apiToken", config.apiToken);
+  }
   return url.toString();
 }