@dbx-tools/cli 0.9.58 → 0.9.61

package/src/tunnel/cli.ts

@@ -0,0 +1,218 @@
+/**
+ * `dbx tunnel` - front a command with a public portr tunnel and passwordless gate.
+ *
+ * This is the WRAPPER path, and it exists for one case: a project that does not
+ * use `@dbx-tools/appkit`'s `createApp`, and therefore cannot register
+ * `tunnelInterceptor()` + the `authGate` plugin in-process. An AppKit app should
+ * still take the plugin path - one process, no proxy hop, no duplicated header
+ * handling.
+ *
+ * The wrapper claims the PUBLIC port (`DATABRICKS_APP_PORT`, the port the
+ * platform and portr route to), moves the wrapped app to a private one, and
+ * reverse-proxies between them so the gate sits in front of traffic it would
+ * otherwise have no way to intercept. Everything else is delegated: the gate
+ * config comes from `plugin.resolveAuthGateConfig`, the portr lifecycle from
+ * `portr.*` - both the same functions the in-process path uses.
+ *
+ * Ships no bin. `@dbx-tools/cli` mounts `buildProgram()` as `dbx tunnel` lazily,
+ * so `dbx dev` pays for none of this, and `--insecure` / `status` / `install`
+ * never load AppKit or the SMTP stack either (the gate app is behind a dynamic
+ * import).
+ *
+ * @module
+ */
+
+import { createServer } from "node:net";
+import { AppKitChildProcess } from "@dbx-tools/appkit/child-process";
+import { addArgs, parseArgs } from "@dbx-tools/cli-args";
+import { log } from "@dbx-tools/shared-core";
+import { frp, interceptor, portr } from "@dbx-tools/tunnel";
+import { Command, CommanderError } from "commander";
+
+import { resolveTunnelOptions, TunnelOptionsSchema, type TunnelOptions } from "./options.ts";
+import { startProxy } from "./proxy.ts";
+
+export { CommanderError };
+
+const logger = log.logger("tunnel");
+
+/**
+ * A free loopback port, from the OS rather than a random guess: binding `0` and
+ * reading back what was assigned is the only way to know the port is actually
+ * available, so two tunnels can run side by side without colliding.
+ */
+function freePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const probe = createServer();
+    probe.on("error", reject);
+    probe.listen(0, "127.0.0.1", () => {
+      const address = probe.address();
+      const port = typeof address === "object" && address ? address.port : 0;
+      probe.close(() => (port > 0 ? resolve(port) : reject(new Error("no free port"))));
+    });
+  });
+}
+
+/**
+ * Tie the wrapper's lifetime to its children's, in both directions: a child that
+ * exits takes the wrapper down with its code, and a signal to the wrapper is
+ * forwarded before it leaves. Without this a crashed app leaves a portr tunnel
+ * serving a dead port, which looks like a hang rather than a failure.
+ */
+function supervise(children: readonly AppKitChildProcess[]): void {
+  let stopping = false;
+  const stop = (code: number): void => {
+    if (stopping) return;
+    stopping = true;
+    void Promise.allSettled(children.map((child) => child.shutdown())).then(() => {
+      process.exit(code);
+    });
+  };
+  for (const child of children) {
+    void child.process?.on("exit", (code) => stop(code ?? 1));
+  }
+  for (const signal of ["SIGTERM", "SIGINT", "SIGHUP"] as const) {
+    process.on(signal, () => stop(0));
+  }
+}
+
+async function run(raw: TunnelOptions, command: readonly string[]): Promise<void> {
+  const [executable, ...args] = command;
+  const resolved = resolveTunnelOptions(raw);
+  const children: AppKitChildProcess[] = [];
+
+  // Two upstream modes:
+  //   - WRAP: a command after `--`. The wrapper spawns it on a private loopback
+  //     port and is the only thing that talks to it.
+  //   - ATTACH: no command, but `--app-port` names an already-running upstream
+  //     (e.g. a local reverse proxy). The gate fronts it without spawning a
+  //     child. This is what lets the gate sit on an interface in front of a
+  //     separately-supervised stack.
+  let appPort: number;
+  if (executable) {
+    appPort = resolved.appPort ?? (await freePort());
+    const app = new AppKitChildProcess(
+      [
+        executable,
+        args,
+        {
+          env: {
+            ...process.env,
+            DATABRICKS_APP_PORT: String(appPort),
+            PORT: String(appPort),
+            HOST: "127.0.0.1",
+          },
+          stdin: "inherit",
+          stdout: "inherit",
+          stderr: "inherit",
+        },
+      ],
+      { gracefulTimeoutMs: 10_000 },
+    );
+    void app.start();
+    children.push(app);
+  } else if (resolved.appPort) {
+    appPort = resolved.appPort;
+    logger.info("attaching gate to existing upstream", { appPort });
+  } else {
+    throw new CommanderError(
+      1,
+      "tunnel.no-upstream",
+      "no command given (pass it after `--`) and no --app-port to attach to",
+    );
+  }
+
+  // Dynamic import: the gate is the only thing here that needs AppKit + SMTP, so
+  // an `--insecure` run never loads either.
+  const gate = resolved.gate.insecure
+    ? undefined
+    : await (
+        await import("./app.ts")
+      ).startGateApp({
+        ...resolved.gateConfig,
+        publicDomain: resolved.gate.publicDomain ?? `localhost:${resolved.publicPort}`,
+      });
+  if (!gate) logger.warn("running OPEN - no gate is in front of this tunnel");
+
+  await startProxy({
+    publicPort: resolved.publicPort,
+    appPort,
+    gate,
+    forwardHeaders: resolved.gate.forwardHeaders,
+    gatePaths: resolved.gate.gatePaths,
+    brandName: resolved.gate.brandName,
+    bindHosts: resolved.bindHosts,
+  });
+
+  if ((resolved.transport === "portr" || resolved.transport === "both") && resolved.portr) {
+    const portrEnv = await portr.installPortr();
+    await portr.writePortrConfig(resolved.portr, portrEnv);
+    children.push(await portr.startPortr(resolved.portr, portrEnv));
+  }
+  if ((resolved.transport === "frp" || resolved.transport === "both") && resolved.frp) {
+    const frpEnv = await frp.installFrp();
+    const configPath = await frp.writeFrpConfig(resolved.frp, frpEnv);
+    children.push(frp.startFrp(resolved.frp, frpEnv, configPath));
+  }
+  const activeTunnelCount = children.length - (executable ? 1 : 0);
+  if (!activeTunnelCount) {
+    logger.info("no selected public tunnel is configured", {
+      transport: resolved.transport,
+      publicPort: resolved.publicPort,
+    });
+  }
+  supervise(children);
+}
+
+/** The `dbx tunnel` program. No side effects until parsed. */
+export function buildProgram(name = "dbx tunnel"): Command {
+  const program = addArgs(
+    new Command()
+      .name(name)
+      .description("Front a command with a public tunnel and passwordless auth"),
+    TunnelOptionsSchema,
+  );
+
+  // `run` is the DEFAULT action as well as a named subcommand, preserving the old
+  // wrapper's ergonomics (`dbx tunnel --allow x -- bun src/server.ts`) while
+  // leaving somewhere for `status` and `install` to live.
+  program
+    .argument("[command...]", "the command to wrap, after `--`")
+    .action(async (command: string[]) => {
+      await run(parseArgs(program, TunnelOptionsSchema), command);
+    });
+
+  const runCommand = addArgs(
+    program.command("run").description("Wrap a command (the default action)"),
+    TunnelOptionsSchema,
+  );
+  runCommand
+    .argument("<command...>", "the command to wrap, after `--`")
+    .action(async (command: string[]) => {
+      await run(parseArgs(runCommand, TunnelOptionsSchema), command);
+    });
+
+  // Worth its own command: the most common failure is a tunnel that silently
+  // does nothing because no token or domain resolved, and this prints exactly
+  // what would happen without starting anything.
+  const statusCommand = addArgs(
+    program.command("status").description("Resolve the configuration and print it"),
+    TunnelOptionsSchema,
+  );
+  statusCommand.action(() => {
+    const resolved = resolveTunnelOptions(parseArgs(statusCommand, TunnelOptionsSchema));
+    process.stdout.write(`${JSON.stringify(resolved, null, 2)}\n`);
+  });
+
+  program
+    .command("install")
+    .argument("[transport]", "portr, frp, or both", "portr")
+    .description("Install public tunnel client binaries and exit")
+    .action(async (transport: string) => {
+      const parsed = interceptor.TunnelTransportSchema.parse(transport);
+      if (parsed === "portr" || parsed === "both") await portr.installPortr();
+      if (parsed === "frp" || parsed === "both") await frp.installFrp();
+    });
+
+  return program;
+}

package/src/tunnel/options.ts

@@ -0,0 +1,169 @@
+/**
+ * Flag -> config -> default resolution for `dbx tunnel`.
+ *
+ * The point of this module is that it does almost NOTHING itself: every gate
+ * setting is handed straight to `@dbx-tools/tunnel`'s own
+ * `plugin.resolveAuthGateConfig`, which is the same function the in-process
+ * plugin path calls. The CLI therefore cannot drift from the plugin on a default,
+ * an env name, or a coercion rule - a flag is just a value passed where the
+ * plugin's `config` object would go, and `config.*` fills the rest in from the
+ * environment, a `.env` file, or `databricks.yml`.
+ *
+ * @module
+ */
+
+import { configUtils } from "@dbx-tools/core";
+import { options as sharedOptions, stringUtils } from "@dbx-tools/shared-core";
+import { type AuthGateConfig, frp, interceptor, plugin, portr } from "@dbx-tools/tunnel";
+import { z } from "zod";
+
+const text = (description: string) => z.string().trim().min(1).optional().describe(description);
+const port = (description: string) =>
+  sharedOptions.tcpPortOrZeroSchema.optional().describe(description);
+const list = (description: string) =>
+  z
+    .preprocess(
+      (value) => (typeof value === "string" ? stringUtils.parseList(value) : value),
+      z.array(z.string().trim().min(1)),
+    )
+    .optional()
+    .describe(description);
+
+export const TunnelOptionsSchema = z
+  .object({
+    transport: interceptor.TunnelTransportSchema.optional()
+      .describe("Public tunnel transport.")
+      .meta({ env: "TUNNEL_TRANSPORT" }),
+    publicDomain: text("Public tunnel domain.").meta({ env: "TUNNEL_PUBLIC_DOMAIN" }),
+    subdomain: text("Portr subdomain."),
+    port: port("Public listener port.").meta({
+      env: sharedOptions.databricksEnvironmentNames.appPort,
+    }),
+    appPort: port("Private wrapped application port.").meta({
+      env: ["TUNNEL_APP_PORT", "APP_PORT"],
+    }),
+    allow: list("Email allow-list patterns.").meta({ env: "TUNNEL_AUTH_ALLOW" }),
+    subject: text("Verification email subject.").meta({ env: "TUNNEL_AUTH_SUBJECT" }),
+    brandName: text("Verification email brand name.").meta({ env: "TUNNEL_AUTH_BRAND_NAME" }),
+    message: text("Verification email message.").meta({ env: "TUNNEL_AUTH_MESSAGE" }),
+    sessionTtlSeconds: z.coerce
+      .number<number>()
+      .positive()
+      .optional()
+      .describe("Session lifetime in seconds.")
+      .meta({ env: "TUNNEL_AUTH_SESSION_TTL" }),
+    codeTtlSeconds: z.coerce
+      .number<number>()
+      .positive()
+      .optional()
+      .describe("One-time-code lifetime in seconds.")
+      .meta({ env: "TUNNEL_AUTH_CODE_TTL" }),
+    sessionCutoff: text("Invalidate sessions issued before this value.").meta({
+      env: "TUNNEL_AUTH_SESSION_CUTOFF",
+    }),
+    storage: z
+      .enum(["auto", "lakebase", "sqlite"])
+      .optional()
+      .describe("Authentication database mode.")
+      .meta({ env: "TUNNEL_AUTH_STORAGE" }),
+    sqlitePath: text("Local authentication SQLite file.").meta({
+      env: "TUNNEL_AUTH_SQLITE_PATH",
+    }),
+    forwardHeaders: list("Additional forwarded request header patterns.").meta({
+      env: "TUNNEL_FORWARD_HEADERS",
+    }),
+    gatePaths: list("Additional path prefixes requiring authentication.").meta({
+      env: "TUNNEL_GATE_PATHS",
+    }),
+    bindHosts: list("Interface IPs the gate listens on."),
+    insecure: z
+      .boolean()
+      .optional()
+      .describe("Run without an authentication gate.")
+      .meta({ env: "TUNNEL_INSECURE" }),
+    frpServer: text("FRP control host.").meta({ env: "FRP_SERVER" }),
+    frpPublicDomain: text("FRP public HTTP domain.").meta({
+      env: "TUNNEL_FRP_PUBLIC_DOMAIN",
+    }),
+    frpServerPort: port("FRP control port.").meta({ env: "FRP_SERVER_PORT" }),
+    frpProtocol: text("FRP transport protocol.").meta({ env: "FRP_PROTOCOL" }),
+    frpToken: text("FRP authentication token.").meta({ env: ["FRP_TOKEN", "TUNNEL_TOKEN"] }),
+    frpProxyName: text("FRP proxy registration name.").meta({ env: "FRP_PROXY_NAME" }),
+  })
+  .strict()
+  .describe("Public tunnel wrapper command-line options.");
+
+export type TunnelOptions = z.output<typeof TunnelOptionsSchema>;
+
+/** Fully resolved listener, gate, and transport settings used to start a tunnel. */
+export interface ResolvedTunnelOptions {
+  /** The port the wrapper itself listens on - what portr forwards to. */
+  publicPort: number;
+  /** The private port the wrapped app is told to bind. Unset means "pick one". */
+  appPort?: number;
+  /** Interface IPs the gate listens on. Empty means the default (0.0.0.0). */
+  bindHosts: string[];
+  transport: interceptor.TunnelTransport;
+  /**
+   * The gate config as the `authGate` PLUGIN takes it - flags only, nothing
+   * resolved. Passed straight to the plugin so it applies its own fallbacks
+   * exactly once, in the one place that owns them.
+   */
+  gateConfig: AuthGateConfig;
+  /** The same config after the plugin's resolution, for `status` and for routing. */
+  gate: plugin.ResolvedAuthGateConfig;
+  portr: ReturnType<typeof portr.resolvePortrConfig>;
+  frp: ReturnType<typeof frp.resolveFrpConfig>;
+}
+
+/** Resolve CLI flag values through the owning tunnel and auth-gate configuration rules. */
+export function resolveTunnelOptions(options: TunnelOptions): ResolvedTunnelOptions {
+  // The Databricks Apps runtime contract: the platform routes to
+  // DATABRICKS_APP_PORT, so the WRAPPER claims it and the wrapped app is moved
+  // to a private one.
+  const publicPort = configUtils.port(options.port, "DATABRICKS_APP_PORT", 8000);
+  const appPort = configUtils.port(options.appPort, "APP_PORT", 0, { prefix: "TUNNEL" });
+  const gateConfig: AuthGateConfig = {
+    allow: options.allow,
+    subject: options.subject,
+    brandName: options.brandName,
+    message: options.message,
+    // Coerced, not resolved: the plugin owns the env name and the default for
+    // these, so the flag is passed through as the `config` value it expects and
+    // only needs a string -> number nudge on the way.
+    sessionTtlSeconds: options.sessionTtlSeconds,
+    codeTtlSeconds: options.codeTtlSeconds,
+    sessionCutoff: options.sessionCutoff,
+    storage: options.storage,
+    sqlitePath: options.sqlitePath,
+    forwardHeaders: options.forwardHeaders,
+    gatePaths: options.gatePaths,
+    insecure: options.insecure,
+    publicDomain: options.publicDomain,
+    publicDomains: options.frpPublicDomain ? [options.frpPublicDomain] : undefined,
+  };
+  const gate = plugin.resolveAuthGateConfig(gateConfig);
+  const transport = interceptor.resolveTunnelTransport(options.transport);
+  return {
+    publicPort,
+    ...(appPort > 0 ? { appPort } : {}),
+    bindHosts: options.bindHosts ?? [],
+    transport,
+    gateConfig,
+    gate,
+    portr: portr.resolvePortrConfig({
+      publicDomain: gate.publicDomain,
+      subdomain: options.subdomain,
+      port: publicPort,
+    }),
+    frp: frp.resolveFrpConfig({
+      publicDomain: options.frpPublicDomain,
+      server: options.frpServer,
+      serverPort: options.frpServerPort,
+      protocol: options.frpProtocol,
+      token: options.frpToken,
+      proxyName: options.frpProxyName,
+      port: publicPort,
+    }),
+  };
+}

package/src/tunnel/proxy.ts

@@ -0,0 +1,194 @@
+/**
+ * The reverse proxy that makes the wrapper path possible.
+ *
+ * The wrapper claims the PUBLIC port and the wrapped app runs as a child process
+ * on a private loopback port, so - unlike the in-process plugin - there is no
+ * middleware chain to insert the gate into. This proxy is that insertion point: it
+ * answers the login routes itself, applies the gate to everything else, and
+ * forwards what survives to the child.
+ *
+ * The gating DECISION is not reimplemented here. `@dbx-tools/tunnel`'s
+ * `gate.gateRequest` makes it - the same function the Express middleware calls -
+ * and this module only differs in how the outcome is written: a proxied request
+ * instead of `next()`, a `writeHead` instead of `res.json`. That is deliberate:
+ * two independent implementations of "which requests are gated and which headers
+ * are stripped" is the one way this package could become a security bug.
+ *
+ * @module
+ */
+
+import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
+import type { Socket } from "node:net";
+import { log } from "@dbx-tools/shared-core";
+import {
+  gate as tunnelGate,
+  headers as tunnelHeaders,
+  loginPage as tunnelLoginPage,
+  type AuthGateApi,
+} from "@dbx-tools/tunnel";
+import ProxyModule from "http-proxy-3";
+
+const logger = log.logger("tunnel:proxy");
+
+type UpgradeSocket = Socket & { destroySoon?: () => void };
+
+/** Listener, upstream application, and optional authentication settings for the wrapper proxy. */
+export interface ProxyOptions {
+  /** The port this proxy listens on - the port portr and the platform route to. */
+  publicPort: number;
+  /** The private loopback port the wrapped app listens on. */
+  appPort: number;
+  /** The gate handlers. Omitted (an `--insecure` run) forwards everything. */
+  gate?: AuthGateApi;
+  /** Extra `x-` headers tunnel traffic may forward. */
+  forwardHeaders?: readonly string[];
+  /** Path prefixes to gate beyond `/api/` (e.g. `/ws` for a WebSocket app). */
+  gatePaths?: readonly string[];
+  /** Brand name for the hosted login page shown on a denied browser navigation. */
+  brandName?: string;
+  /**
+   * Addresses to listen on. Defaults to a single `0.0.0.0` (every interface),
+   * the portr/platform case. Pass specific interface IPs to expose the gate on
+   * only those - e.g. an overlay/LAN address while loopback reaches the upstream
+   * directly and ungated.
+   */
+  bindHosts?: readonly string[];
+}
+
+function sendJson(
+  response: ServerResponse,
+  status: number,
+  body: unknown,
+  setCookie?: string,
+): void {
+  response.writeHead(status, {
+    "content-type": "application/json",
+    ...(setCookie ? { "set-cookie": setCookie } : {}),
+  });
+  response.end(JSON.stringify(body));
+}
+
+/**
+ * Hand every Better Auth and compatibility route to the shared gate runtime.
+ */
+async function handleAuthRoute(
+  request: IncomingMessage,
+  response: ServerResponse,
+  path: string,
+  gate: AuthGateApi,
+  brandName: string,
+): Promise<boolean> {
+  if (!tunnelGate.isAuthPath(path)) return false;
+  if (tunnelGate.wantsHostedLogin(request)) {
+    response.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+    response.end(
+      tunnelLoginPage.loginPageHtml({
+        brandName,
+        returnTo: tunnelGate.loginReturnTo(request),
+      }),
+    );
+    return true;
+  }
+  const result = await gate.handler(tunnelGate.webRequest(request));
+  await tunnelGate.sendWebResponse(response, result);
+  return true;
+}
+
+/**
+ * Start the proxy and resolve once it is listening.
+ *
+ * `publicDomain` is intentionally NOT passed to `gateRequest`: on this path every
+ * request arrived on the public port, so it IS tunnel traffic by construction -
+ * whereas the in-process gate shares a port with the platform front door and has
+ * to tell them apart by `Host`. Passing the request's own host keeps the shared
+ * decision function's contract satisfied without weakening it.
+ */
+export async function startProxy(options: ProxyOptions): Promise<void> {
+  const proxy = ProxyModule.createProxyServer({
+    target: `http://127.0.0.1:${options.appPort}`,
+    ws: true,
+    xfwd: true,
+  });
+  const headerPolicy = tunnelHeaders.toHeaderPolicy(options.forwardHeaders);
+  const gate = options.gate;
+
+  const decide = (request: IncomingMessage): Promise<tunnelGate.GateAction> =>
+    gate
+      ? tunnelGate.gateRequest(request, {
+          gate,
+          publicDomain: (request.headers.host ?? "").split(":")[0] || "localhost",
+          headerPolicy,
+          gatePaths: options.gatePaths,
+        })
+      : Promise.resolve<tunnelGate.GateAction>("pass");
+
+  const onRequest = (request: IncomingMessage, response: ServerResponse): void => {
+    void (async () => {
+      const path = (request.url ?? "/").split("?")[0] ?? "/";
+      const brandName = options.brandName ?? "this app";
+      if (gate && (await handleAuthRoute(request, response, path, gate, brandName))) return;
+      if ((await decide(request)) === "deny") {
+        // A denied browser navigation gets the hosted login page; anything else
+        // (an XHR, a /ws upgrade probe, a non-HTML fetch) gets the 401 JSON.
+        if (gate && tunnelGate.wantsLoginPage(request)) {
+          const html = tunnelLoginPage.loginPageHtml({
+            brandName,
+            returnTo: tunnelGate.requestReturnTo(request),
+          });
+          response.writeHead(401, { "content-type": "text/html; charset=utf-8" });
+          response.end(html);
+        } else {
+          sendJson(response, 401, tunnelGate.unauthorizedBody(request));
+        }
+        return;
+      }
+      proxy.web(request, response);
+    })().catch((error: unknown) => {
+      logger.error("proxy request failed", { error });
+      if (!response.headersSent) sendJson(response, 502, { error: "bad gateway" });
+      else response.end();
+    });
+  };
+
+  // A websocket upgrade cannot be answered with a 401 body, so a denied one is
+  // destroyed - the client sees the handshake fail, which is what a browser's
+  // WebSocket error handler expects.
+  const onUpgrade = (request: IncomingMessage, socket: Socket, head: Buffer): void => {
+    const upgradeSocket = socket as UpgradeSocket;
+    upgradeSocket.destroySoon ??= () => upgradeSocket.end();
+    const path = (request.url ?? "/").split("?", 1)[0] ?? "/";
+    if (tunnelGate.isAuthPath(path)) {
+      upgradeSocket.destroy();
+      return;
+    }
+    void decide(request)
+      .then((action) => {
+        if (action === "deny") upgradeSocket.destroy();
+        else proxy.ws(request, upgradeSocket, head);
+      })
+      .catch(() => upgradeSocket.destroy());
+  };
+
+  // One net.Server binds one address, so listen each host on its own server that
+  // shares the same handlers. Binding specific interface IPs (rather than the
+  // default 0.0.0.0) is what lets the gate front an overlay/LAN address while
+  // loopback reaches the upstream ungated.
+  const hosts = options.bindHosts?.length ? options.bindHosts : ["0.0.0.0"];
+  await Promise.all(
+    hosts.map(
+      (host) =>
+        new Promise<void>((resolve) => {
+          const server = createServer(onRequest);
+          server.on("upgrade", onUpgrade);
+          server.listen(options.publicPort, host, () => {
+            logger.info("proxy listening", {
+              host,
+              publicPort: options.publicPort,
+              appPort: options.appPort,
+            });
+            resolve();
+          });
+        }),
+    ),
+  );
+}