@dbx-tools/cli-tunnel 0.6.59 → 0.6.86

package/src/cli.ts

@@ -1,201 +1,191 @@
 /**
- * `dbx-tools-tunnel` / `dbxt-tunnel` CLI.
+ * `dbx tunnel` - front a command with a public portr tunnel and an email-OTP gate.
  *
- * Wraps an app's start command with a public portr tunnel and an email-OTP
- * access gate. Everything after `--` is the REAL app start command:
+ * 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.
  *
- *   dbxt-tunnel --subject "Here's your OTP" --allow example.com -- bun src/server.ts
+ * 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.
  *
- * Boot sequence:
- *   1. Pick a random PRIVATE port and spawn the app command with
- *      `DATABRICKS_APP_PORT` set to it (so the app binds loopback-private). That
- *      variable name is the Databricks Apps runtime contract; the gate itself is
- *      platform-neutral and honours whatever port it finds there.
- *   2. Boot the tiny gate AppKit app (no server): inits `CacheManager` + the
- *      email transport, yields the in-process gate API.
- *   3. Start the gate PROXY on the ORIGINAL public port, forwarding to the app.
- *   4. Install + run portr pointed at the public port (when a tunnel is
- *      configured; otherwise the proxy still gates nothing and forwards).
- *
- * Supervision: the app child, portr child, and this process are tied together -
- * if ANY exits, everything comes down (concurrently-style `killOthers`).
- *
- * Options come from flags OR env; see the option definitions below.
+ * 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 { type ChildProcess, spawn } from "node:child_process";
-import { env, log } from "@dbx-tools/shared-core";
+import { createServer } from "node:net";
+import { log } from "@dbx-tools/shared-core";
+import { portr } from "@dbx-tools/tunnel";
 import { Command, CommanderError } from "commander";
-import { startGateApp } from "./app.ts";
-import { FORWARD_HEADERS_ENV, INSECURE_ENV } from "./env.ts";
-import type { AuthGateConfig } from "./plugin.ts";
-import { installPortr, resolvePortrConfig, startPortr, writePortrConfig } from "./portr.ts";
+import { resolveTunnelOptions, type TunnelOptions } from "./options.ts";
 import { startProxy } from "./proxy.ts";
 
 export { CommanderError };
 
 const logger = log.logger("tunnel");
 
-/** A random ephemeral port for the app to bind (the proxy fronts the public one). */
-function randomPort(): number {
-  return 20000 + Math.floor(Math.random() * 20000);
-}
+/** How long a child gets to exit on SIGTERM before the wrapper leaves anyway. */
+const SHUTDOWN_GRACE_MS = 3_000;
 
-interface TunnelOpts {
-  subject?: string;
-  allow?: string;
-  subdomain?: string;
-  publicDomain?: string;
-  brandName?: string;
-  message?: string;
-  sessionTtl?: string;
-  codeTtl?: string;
-  sessionCutoff?: string;
-  insecure?: boolean;
-  forwardHeaders?: string;
+/**
+ * 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"))));
+    });
+  });
 }
 
-/** Build the commander program. `--` separates flags from the app start command. */
-function program(): Command {
-  return new Command()
-    .name("dbx-tools-tunnel")
-    .description("Front an app with a public portr tunnel + email-OTP gate")
-    .option("--subject <text>", "Subject line for the code email (env TUNNEL_AUTH_SUBJECT)")
-    .option(
-      "--allow <patterns>",
-      "Comma/space-separated allow-list: domain / glob / /regex/ (env TUNNEL_AUTH_ALLOW)",
-    )
-    .option("--subdomain <name>", "portr subdomain (else derived from TUNNEL_PUBLIC_DOMAIN)")
-    .option("--public-domain <host>", "portr <subdomain>.<server> (env TUNNEL_PUBLIC_DOMAIN)")
-    .option(
-      "--brand-name <name>",
-      "Display name in the code email copy (env TUNNEL_AUTH_BRAND_NAME; defaults to the brand context name)",
-    )
-    .option("--message <text>", "Line shown above the code in the email (env TUNNEL_AUTH_MESSAGE)")
-    .option("--session-ttl <seconds>", "Session lifetime (env TUNNEL_AUTH_SESSION_TTL)")
-    .option("--code-ttl <seconds>", "One-time-code lifetime (env TUNNEL_AUTH_CODE_TTL)")
-    .option(
-      "--session-cutoff <when>",
-      "Invalidate sessions issued before this point, signing everyone out: a date, ISO instant, epoch seconds, or relative duration like -30d (env TUNNEL_AUTH_SESSION_CUTOFF)",
-    )
-    .option(
-      "--forward-headers <patterns>",
-      "Extra x- request headers tunnel traffic may forward: literal / glob / /regex/ (env TUNNEL_FORWARD_HEADERS)",
-    )
-    .option(
-      "--insecure",
-      "Run the tunnel OPEN with no gate (env TUNNEL_INSECURE=true). Otherwise the CLI fails fast when email SMTP is not configured.",
-    )
-    .allowExcessArguments(true)
-    .helpOption("-h, --help", "Show help");
+/**
+ * Every gate/portr flag. Declared on the root command AND on `run`/`status` so
+ * `dbx tunnel --allow x -- cmd` and `dbx tunnel run --allow x -- cmd` behave
+ * identically - commander does not inherit options downward.
+ */
+function addOptions(command: Command): Command {
+  return command
+    .option("--public-domain <host>", "portr public domain (<subdomain>.<server>)")
+    .option("--subdomain <name>", "portr subdomain (else derived from the public domain)")
+    .option("--port <port>", "public port the wrapper listens on")
+    .option("--app-port <port>", "private port the wrapped app is told to bind")
+    .option("--allow <patterns...>", "email allow-list (domain / glob / /regex/)")
+    .option("--subject <text>", "verification email subject")
+    .option("--brand-name <name>", "verification email brand name")
+    .option("--message <text>", "verification email message")
+    .option("--session-ttl <seconds>", "session lifetime")
+    .option("--code-ttl <seconds>", "one-time-code lifetime")
+    .option("--session-cutoff <when>", "invalidate every session issued before this")
+    .option("--forward-headers <patterns...>", "extra x- headers tunnel traffic may forward")
+    .option("--insecure", "run open, with no gate");
 }
 
-/** Tie a child's exit to full teardown: any exit brings the whole tunnel down. */
-function superviseExit(children: ChildProcess[]): void {
-  let shuttingDown = false;
-  const shutdown = (code: number): void => {
-    if (shuttingDown) return;
-    shuttingDown = true;
-    for (const child of children) {
-      if (!child.killed) child.kill("SIGTERM");
-    }
-    // Give children a moment, then exit with the first non-zero code seen.
-    setTimeout(() => process.exit(code), 3000).unref();
+/**
+ * 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 ChildProcess[]): void {
+  let stopping = false;
+  const stop = (code: number): void => {
+    if (stopping) return;
+    stopping = true;
+    for (const child of children) if (!child.killed) child.kill("SIGTERM");
+    setTimeout(() => process.exit(code), SHUTDOWN_GRACE_MS).unref();
   };
-  for (const child of children) {
-    child.on("exit", (code) => {
-      logger.warn(`child exited (${code ?? "signal"}); bringing tunnel down`);
-      shutdown(code ?? 1);
-    });
-  }
-  for (const sig of ["SIGTERM", "SIGINT", "SIGHUP"] as const) {
-    process.on(sig, () => shutdown(0));
+  for (const child of children) child.on("exit", (code) => stop(code ?? 1));
+  for (const signal of ["SIGTERM", "SIGINT", "SIGHUP"] as const) {
+    process.on(signal, () => stop(0));
   }
 }
 
-/** Parse argv and run the tunnel. */
-export async function runCli(argv: string[]): Promise<void> {
-  // Split flags from the wrapped command at the first `--`.
-  const sep = argv.indexOf("--");
-  const flags = sep >= 0 ? argv.slice(0, sep) : argv;
-  const command = sep >= 0 ? argv.slice(sep + 1) : [];
-
-  const prog = program();
-  prog.parse(flags);
-  const opts = prog.opts<TunnelOpts>();
-
-  if (command.length === 0) {
-    throw new CommanderError(1, "tunnel.no-command", "no start command given after `--`");
+async function run(raw: TunnelOptions, command: readonly string[]): Promise<void> {
+  const [executable, ...args] = command;
+  if (!executable) {
+    throw new CommanderError(1, "tunnel.no-command", "no command given - pass it after `--`");
   }
-
-  const publicPort = Number(process.env.DATABRICKS_APP_PORT ?? 8000);
-  const appPort = randomPort();
-
-  const gateConfig: AuthGateConfig = {
-    allow: opts.allow,
-    subject: opts.subject,
-    brandName: opts.brandName,
-    message: opts.message,
-    sessionTtlSeconds: opts.sessionTtl ? Number(opts.sessionTtl) : undefined,
-    codeTtlSeconds: opts.codeTtl ? Number(opts.codeTtl) : undefined,
-    sessionCutoff: opts.sessionCutoff,
-  };
-
-  // 1. Spawn the wrapped app with the PRIVATE port. It binds loopback; only the
-  //    proxy reaches it.
-  logger.info(`spawning app on private port ${appPort}: ${command.join(" ")}`);
-  const [cmd, ...args] = command;
-  const app = spawn(cmd!, args, {
-    env: { ...process.env, DATABRICKS_APP_PORT: String(appPort), HOST: "127.0.0.1" },
+  const resolved = resolveTunnelOptions(raw);
+
+  // The wrapped app must not be reachable from outside: it binds loopback on a
+  // private port, and the wrapper is the only thing that talks to it. An
+  // unresolved `--app-port` becomes a free ephemeral port rather than a fixed
+  // guess, so two tunnels can run side by side.
+  const appPort = resolved.appPort ?? (await freePort());
+  const app = spawn(executable, args, {
+    env: {
+      ...process.env,
+      DATABRICKS_APP_PORT: String(appPort),
+      PORT: String(appPort),
+      HOST: "127.0.0.1",
+    },
     stdio: "inherit",
   });
+  const children: ChildProcess[] = [app];
 
-  // 2. Boot the gate app (cache + email transport + gate API). `startGateApp`
-  //    FAILS FAST when email can't send codes (no SMTP). Insecure mode
-  //    (`--insecure` / TUNNEL_INSECURE) skips the gate and runs the tunnel open.
-  const insecure = env.boolean(opts.insecure, INSECURE_ENV) ?? false;
-  let gate: Awaited<ReturnType<typeof startGateApp>> | undefined;
-  if (insecure) {
-    logger.warn("insecure mode - tunnel runs OPEN with no email-OTP gate");
-  } else {
-    try {
-      gate = await startGateApp(gateConfig);
-    } catch (error) {
-      // Fail fast: don't silently expose an ungated tunnel. The operator must fix
-      // SMTP or explicitly opt into `--insecure`.
-      logger.error("cannot start the OTP gate", { error: (error as Error).message });
-      throw error;
-    }
-  }
+  // 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);
+  if (!gate) logger.warn("running OPEN - no gate is in front of this tunnel");
 
-  // 3. Start the gate proxy on the public port (open when `gate` is undefined).
-  //    `forwardHeaders` only ADDS to the built-in allow-list; see `./headers.ts`.
   await startProxy({
-    publicPort,
+    publicPort: resolved.publicPort,
     appPort,
     gate,
-    forwardHeaders: env.list(opts.forwardHeaders, FORWARD_HEADERS_ENV),
+    forwardHeaders: resolved.gate.forwardHeaders,
   });
 
-  // 4. Install + run portr when a tunnel is configured.
-  const portrConfig = resolvePortrConfig({
-    publicDomain: opts.publicDomain,
-    subdomain: opts.subdomain,
-    port: publicPort,
-  });
-  const children: ChildProcess[] = [app];
-  if (portrConfig) {
-    const portrEnv = installPortr();
-    writePortrConfig(portrConfig, portrEnv);
-    children.push(startPortr(portrConfig, portrEnv));
+  if (resolved.portr) {
+    const portrEnv = await portr.installPortr();
+    await portr.writePortrConfig(resolved.portr, portrEnv);
+    children.push(await portr.startPortr(resolved.portr, portrEnv));
   } else {
-    logger.info(
-      "no PORTR_TOKEN/TUNNEL_PUBLIC_DOMAIN - serving the gate proxy without a public tunnel",
-    );
+    logger.info("no PORTR_TOKEN / TUNNEL_PUBLIC_DOMAIN - serving locally only", {
+      publicPort: resolved.publicPort,
+    });
   }
+  supervise(children);
+}
+
+/** The `dbx tunnel` program. No side effects until parsed. */
+export function buildProgram(name = "dbx tunnel"): Command {
+  const program = addOptions(
+    new Command()
+      .name(name)
+      .description("Front a command with a portr tunnel and an email-OTP gate"),
+  );
+
+  // `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[], _options: TunnelOptions, cmd: Command) => {
+      await run(cmd.opts<TunnelOptions>(), command);
+    });
+
+  addOptions(
+    program.command("run").description("Wrap a command (the default action)"),
+  )
+    .argument("<command...>", "the command to wrap, after `--`")
+    .action(async (command: string[], _options: TunnelOptions, cmd: Command) => {
+      await run(cmd.opts<TunnelOptions>(), 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.
+  addOptions(
+    program.command("status").description("Resolve the configuration and print it"),
+  ).action((_options: TunnelOptions, cmd: Command) => {
+    const resolved = resolveTunnelOptions(cmd.opts<TunnelOptions>());
+    process.stdout.write(`${JSON.stringify(resolved, null, 2)}\n`);
+  });
+
+  program
+    .command("install")
+    .description("Install the portr binary and exit")
+    .action(async () => {
+      await portr.installPortr();
+    });
 
-  // Any child exit (or a signal) tears the whole thing down.
-  superviseExit(children);
+  return program;
 }

package/src/options.ts

@@ -0,0 +1,85 @@
+/**
+ * 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 { config } from "@dbx-tools/core";
+import { object } from "@dbx-tools/shared-core";
+import { type AuthGateConfig, plugin, portr } from "@dbx-tools/tunnel";
+
+/** Raw commander flag values (every numeric flag arrives as a string). */
+export interface TunnelOptions {
+  publicDomain?: string;
+  subdomain?: string;
+  port?: string | number;
+  appPort?: string | number;
+  allow?: string[];
+  subject?: string;
+  brandName?: string;
+  message?: string;
+  sessionTtl?: string | number;
+  codeTtl?: string | number;
+  sessionCutoff?: string;
+  forwardHeaders?: string[];
+  insecure?: boolean;
+}
+
+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;
+  /**
+   * 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>;
+}
+
+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 = config.positiveInt(options.port, "DATABRICKS_APP_PORT", 8000);
+  const appPort = config.positiveInt(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: object.toNumber(options.sessionTtl),
+    codeTtlSeconds: object.toNumber(options.codeTtl),
+    sessionCutoff: options.sessionCutoff,
+    forwardHeaders: options.forwardHeaders,
+    insecure: options.insecure,
+    publicDomain: options.publicDomain,
+  };
+  const gate = plugin.resolveAuthGateConfig(gateConfig);
+  return {
+    publicPort,
+    ...(appPort > 0 ? { appPort } : {}),
+    gateConfig,
+    gate,
+    portr: portr.resolvePortrConfig({
+      publicDomain: gate.publicDomain,
+      subdomain: options.subdomain,
+      port: publicPort,
+    }),
+  };
+}