@dbx-tools/cli-tunnel 0.6.45

package/src/cli.ts

@@ -0,0 +1,176 @@
+/**
+ * `dbx-tools-tunnel` / `dbxt-tunnel` CLI.
+ *
+ * Wraps a Databricks App start command with a public portr tunnel and an
+ * email-OTP access gate. Everything after `--` is the REAL app start command:
+ *
+ *   dbxt-tunnel --subject "Here's your OTP" --allow databricks.com -- bun src/server.ts
+ *
+ * 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).
+ *   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.
+ *
+ * @module
+ */
+
+import { type ChildProcess, spawn } from "node:child_process";
+import { log } from "@dbx-tools/shared-core";
+import { Command, CommanderError } from "commander";
+import { startGateApp } from "./app.ts";
+import type { AuthGateConfig } from "./plugin.ts";
+import { installPortr, resolvePortrConfig, startPortr, writePortrConfig } from "./portr.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);
+}
+
+interface TunnelOpts {
+  subject?: string;
+  allow?: string;
+  subdomain?: string;
+  publicDomain?: string;
+  brandName?: string;
+  message?: string;
+  sessionTtl?: string;
+  codeTtl?: string;
+  insecure?: boolean;
+}
+
+/** Build the commander program. `--` separates flags from the app start command. */
+function program(): Command {
+  return new Command()
+    .name("dbx-tools-tunnel")
+    .description("Front a Databricks App with a public portr tunnel + email-OTP gate")
+    .option("--subject <text>", "Subject line for the code email (env AUTH_SUBJECT)")
+    .option(
+      "--allow <patterns>",
+      "Comma/space-separated allow-list: domain / glob / /regex/ (env EMAIL_AUTH_ALLOW)",
+    )
+    .option("--subdomain <name>", "portr subdomain (else derived from PUBLIC_DOMAIN)")
+    .option("--public-domain <host>", "portr <subdomain>.<server> (env PUBLIC_DOMAIN)")
+    .option("--brand-name <name>", "Product name in the email + login copy (env AUTH_BRAND_NAME)")
+    .option("--message <text>", "Line shown above the code in the email (env AUTH_MESSAGE)")
+    .option("--session-ttl <seconds>", "Session lifetime (env AUTH_SESSION_TTL)")
+    .option("--code-ttl <seconds>", "One-time-code lifetime (env AUTH_CODE_TTL)")
+    .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");
+}
+
+/** 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();
+  };
+  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));
+  }
+}
+
+/** 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 `--`");
+  }
+
+  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,
+  };
+
+  // 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" },
+    stdio: "inherit",
+  });
+
+  // 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 = opts.insecure || /^(1|true|yes|on)$/i.test(process.env.TUNNEL_INSECURE ?? "");
+  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;
+    }
+  }
+
+  // 3. Start the gate proxy on the public port (open when `gate` is undefined).
+  await startProxy({ publicPort, appPort, gate });
+
+  // 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 env = installPortr();
+    writePortrConfig(portrConfig, env);
+    children.push(startPortr(portrConfig, env));
+  } else {
+    logger.info("no PORTR_TOKEN/PUBLIC_DOMAIN - serving the gate proxy without a public tunnel");
+  }
+
+  // Any child exit (or a signal) tears the whole thing down.
+  superviseExit(children);
+}

package/src/otp.ts

@@ -0,0 +1,150 @@
+/**
+ * One-time-code store + session JWT for the email-OTP tunnel gate.
+ *
+ * The code store is backed by AppKit's `CacheManager` (auto-configured to memory,
+ * or Lakebase when the app wires a persistent `CacheStorage`), so TTL EXPIRY and
+ * eviction are the cache's job - no hand-rolled Map or timers. A 6-digit code is
+ * generated with `crypto.randomInt` and stored as a SHA-256 hash with an attempt
+ * counter (never the plaintext, never in the JWT); `verify` is constant-time on
+ * the hash, and the entry is deleted on success or once attempts are exhausted.
+ *
+ * The session JWT is a short-lived HS256 token (via `jose`) carrying only the
+ * email. Its signing key comes from `AUTH_JWT_SECRET`; when unset the gate FAILS
+ * OPEN with an ephemeral per-process key (sessions reset on restart) rather than
+ * refusing service - a Databricks App is already access-limited, so an unset
+ * secret degrades to "sessions don't survive restarts", not "nobody can log in".
+ *
+ * @module
+ */
+
+import { createHash, randomBytes, randomInt, timingSafeEqual } from "node:crypto";
+import { CacheManager } from "@databricks/appkit";
+import { log } from "@dbx-tools/shared-core";
+import { jwtVerify, SignJWT } from "jose";
+
+const logger = log.logger("tunnel:otp");
+
+/** JWT issuer/audience so a token minted for this gate isn't accepted elsewhere. */
+const JWT_AUD = "dbx-tools-tunnel-auth";
+
+/** Cache-key prefix for pending codes, namespaced away from any other cache use. */
+const CODE_PREFIX = "tunnel:otp:";
+
+/** SHA-256 hex of a value. */
+function sha256(value: string): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+/** Constant-time compare of two equal-length hex digests. */
+function safeEqualHex(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(Buffer.from(a, "hex"), Buffer.from(b, "hex"));
+}
+
+interface CodeEntry {
+  hash: string;
+  attempts: number;
+}
+
+/** Result of {@link CodeStore.verify}. */
+export type VerifyOutcome = "ok" | "invalid" | "expired" | "too-many-attempts";
+
+/**
+ * Pending one-time codes, stored in AppKit's cache keyed by lowercased email.
+ * Expiry is the cache's TTL (no manual clock); a miss means expired-or-never.
+ */
+export class CodeStore {
+  constructor(
+    private readonly ttlSeconds: number,
+    private readonly maxAttempts: number,
+  ) {}
+
+  private cache(): CacheManager {
+    return CacheManager.getInstanceSync();
+  }
+
+  private key(email: string): string {
+    return `${CODE_PREFIX}${email.toLowerCase()}`;
+  }
+
+  /**
+   * Generate, store (hashed, with the cache TTL), and RETURN a fresh 6-digit
+   * code. The caller emails the returned plaintext; only the hash is retained.
+   * Replaces any pending code for the address.
+   */
+  async issue(email: string): Promise<string> {
+    const code = String(randomInt(0, 1_000_000)).padStart(6, "0");
+    const entry: CodeEntry = { hash: sha256(code), attempts: 0 };
+    await this.cache().set(this.key(email), entry, { ttl: this.ttlSeconds });
+    return code;
+  }
+
+  /**
+   * Check `code` for `email`. A cache miss is `expired` (TTL elapsed or never
+   * issued). Deletes the entry on success or when attempts are exhausted, so a
+   * code is single-use and can't be brute-forced past the cap. An attempt
+   * increments the stored counter (re-persisted with a fresh TTL window).
+   */
+  async verify(email: string, code: string): Promise<VerifyOutcome> {
+    const key = this.key(email);
+    const entry = await this.cache().get<CodeEntry>(key);
+    if (!entry) return "expired";
+    const attempts = entry.attempts + 1;
+    if (safeEqualHex(entry.hash, sha256(code))) {
+      await this.cache().delete(key);
+      return "ok";
+    }
+    if (attempts >= this.maxAttempts) {
+      await this.cache().delete(key);
+      return "too-many-attempts";
+    }
+    await this.cache().set(key, { ...entry, attempts }, { ttl: this.ttlSeconds });
+    return "invalid";
+  }
+}
+
+/**
+ * Resolve the HS256 signing key. Prefers `AUTH_JWT_SECRET`; when unset, mints an
+ * ephemeral per-process key (fail-open) and warns once. Memoized.
+ */
+let cachedKey: Uint8Array | undefined;
+function signingKey(): Uint8Array {
+  if (cachedKey) return cachedKey;
+  const secret = process.env.AUTH_JWT_SECRET?.trim();
+  if (secret) {
+    cachedKey = new TextEncoder().encode(secret);
+  } else {
+    logger.warn(
+      "AUTH_JWT_SECRET is not set - using an ephemeral per-process key; sessions will not survive a restart",
+    );
+    cachedKey = randomBytes(32);
+  }
+  return cachedKey;
+}
+
+/** Reset the memoized key (tests, or after changing the env in-process). */
+export function resetSigningKey(): void {
+  cachedKey = undefined;
+}
+
+/** Mint a short-lived session JWT for `email`, expiring in `ttlSeconds`. */
+export async function signSession(email: string, ttlSeconds: number): Promise<string> {
+  return new SignJWT({ email })
+    .setProtectedHeader({ alg: "HS256" })
+    .setSubject(email)
+    .setAudience(JWT_AUD)
+    .setIssuedAt()
+    .setExpirationTime(`${ttlSeconds}s`)
+    .sign(signingKey());
+}
+
+/** Validate a session JWT, returning the email it was minted for, or `undefined`. */
+export async function verifySession(token: string | undefined): Promise<string | undefined> {
+  if (!token) return undefined;
+  try {
+    const { payload } = await jwtVerify(token, signingKey(), { audience: JWT_AUD });
+    return typeof payload.email === "string" ? payload.email : undefined;
+  } catch {
+    return undefined;
+  }
+}

package/src/plugin.ts

@@ -0,0 +1,200 @@
+/**
+ * `authGate()` - the AppKit plugin behind the tunnel's email-OTP gate.
+ *
+ * It has NO routes of its own: the tunnel PROXY (not an HTTP server) calls the
+ * handlers this plugin exposes via {@link AuthGatePlugin.exports}. The plugin
+ * owns the allow-list, the per-email/per-IP rate limiters, the CacheManager-backed
+ * one-time-code store, and the session JWT. `createApp` (with no `server()`) is
+ * used only to auto-init `CacheManager` + prime the sibling `email` transport;
+ * this plugin is where the gate logic lives.
+ *
+ * Options come from CLI flags OR env, with sensible defaults - see
+ * {@link resolveAuthGateConfig}. The one runtime dependency the plugin can't
+ * resolve itself is HOW to email the code, so it takes a `sendCode` callback the
+ * app wires to the email plugin.
+ *
+ * @module
+ */
+
+import { Plugin, toPlugin, type BasePluginConfig, type PluginManifest } from "@databricks/appkit";
+import { log, string } from "@dbx-tools/shared-core";
+import type { AuthStatus } from "@dbx-tools/shared-email";
+import { looksLikeEmail, matchesAllowlist } from "./allowlist.ts";
+import { CodeStore, signSession, verifySession } from "./otp.ts";
+import { RateLimiter } from "./rate-limit.ts";
+
+const logger = log.logger("tunnel:auth");
+
+/** Options for the {@link authGate} plugin (all resolvable from env - see below). */
+export interface AuthGateConfig extends BasePluginConfig {
+  /** Allow-list patterns (domain / glob / `/regex/`). Empty = allow nobody. Env EMAIL_AUTH_ALLOW. */
+  allow?: string | string[];
+  /** Subject line for the code email. Env AUTH_SUBJECT. */
+  subject?: string;
+  /** Product/brand name used in the email + login copy. Env AUTH_BRAND_NAME. */
+  brandName?: string;
+  /** One-line message shown above the code in the email. Env AUTH_MESSAGE. */
+  message?: string;
+  /** Session lifetime (seconds). Env AUTH_SESSION_TTL. Default 43200 (12h). */
+  sessionTtlSeconds?: number;
+  /** One-time-code lifetime (seconds). Env AUTH_CODE_TTL. Default 600 (10m). */
+  codeTtlSeconds?: number;
+  /** Max verify attempts per issued code. Default 5. */
+  maxAttempts?: number;
+  /** Deliver a code to an address. Wired by the app to the email plugin. */
+  sendCode?: (email: string, code: string, opts: SendCodeOptions) => Promise<void>;
+}
+
+/** Branding/messaging passed to {@link AuthGateConfig.sendCode}. */
+export interface SendCodeOptions {
+  subject: string;
+  brandName: string;
+  message: string;
+}
+
+/** Resolved gate config with env fallbacks + defaults applied. */
+export interface ResolvedAuthGateConfig {
+  allow: string[];
+  subject: string;
+  brandName: string;
+  message: string;
+  sessionTtlSeconds: number;
+  codeTtlSeconds: number;
+  maxAttempts: number;
+}
+
+const DEFAULTS = {
+  subject: "Your sign-in code",
+  brandName: "This app",
+  message: "Your one-time sign-in code is:",
+  sessionTtlSeconds: 43200,
+  codeTtlSeconds: 600,
+  maxAttempts: 5,
+};
+
+/** Positive finite number from a value / env string, else the fallback. */
+function num(value: number | undefined, env: string | undefined, fallback: number): number {
+  const raw = value ?? (env ? Number(env) : undefined);
+  return typeof raw === "number" && Number.isFinite(raw) && raw > 0 ? raw : fallback;
+}
+
+/** Merge {@link AuthGateConfig} over env over defaults into a resolved config. */
+export function resolveAuthGateConfig(config: AuthGateConfig): ResolvedAuthGateConfig {
+  return {
+    allow: [...string.parseList(config.allow), ...string.parseList(process.env.EMAIL_AUTH_ALLOW)],
+    subject: config.subject ?? process.env.AUTH_SUBJECT?.trim() ?? DEFAULTS.subject,
+    brandName: config.brandName ?? process.env.AUTH_BRAND_NAME?.trim() ?? DEFAULTS.brandName,
+    message: config.message ?? process.env.AUTH_MESSAGE?.trim() ?? DEFAULTS.message,
+    sessionTtlSeconds: num(
+      config.sessionTtlSeconds,
+      process.env.AUTH_SESSION_TTL,
+      DEFAULTS.sessionTtlSeconds,
+    ),
+    codeTtlSeconds: num(config.codeTtlSeconds, process.env.AUTH_CODE_TTL, DEFAULTS.codeTtlSeconds),
+    maxAttempts: config.maxAttempts ?? DEFAULTS.maxAttempts,
+  };
+}
+
+/** The handlers the proxy calls in-process (returned by {@link AuthGatePlugin.exports}). */
+export interface AuthGateApi {
+  /** Handle a code request. Always resolves `{ ok: true }` (anti-enumeration). */
+  request(email: string, ip: string): Promise<{ ok: true; retryAfter?: number }>;
+  /** Handle a code verification. On success returns the session token to cookie. */
+  verify(
+    email: string,
+    code: string,
+    ip: string,
+  ): Promise<{ ok: boolean; token?: string; retryAfter?: number }>;
+  /** Resolve the authenticated email for a session token, or undefined. */
+  session(token: string | undefined): Promise<string | undefined>;
+  /** Session TTL in seconds (for the cookie Max-Age). */
+  readonly sessionTtlSeconds: number;
+  /** The gate status payload (`enabled` is always true when this plugin runs). */
+  status(token: string | undefined): Promise<AuthStatus>;
+}
+
+/** AppKit plugin owning the email-OTP gate's logic (no HTTP routes; proxy-driven). */
+export class AuthGatePlugin extends Plugin<AuthGateConfig> {
+  static manifest = {
+    name: "authGate",
+    displayName: "Auth Gate",
+    description: "Email one-time-password access gate for a public tunnel.",
+    stability: "beta",
+    resources: { required: [], optional: [] },
+  } satisfies PluginManifest<"authGate">;
+
+  private resolved!: ResolvedAuthGateConfig;
+  private codes!: CodeStore;
+  // Requesting a code is email-spam-prone; verifying is a brute-force surface.
+  // Per-email AND per-IP so neither axis alone is a bypass.
+  private readonly requestLimiter = new RateLimiter(5, 15 * 60 * 1000);
+  private readonly verifyLimiter = new RateLimiter(10, 15 * 60 * 1000);
+
+  override async setup(): Promise<void> {
+    this.resolved = resolveAuthGateConfig(this.config);
+    this.codes = new CodeStore(this.resolved.codeTtlSeconds, this.resolved.maxAttempts);
+    logger.info("ready", {
+      patterns: this.resolved.allow.length,
+      sessionTtlSeconds: this.resolved.sessionTtlSeconds,
+    });
+  }
+
+  override exports(): AuthGateApi {
+    return {
+      sessionTtlSeconds: this.resolved.sessionTtlSeconds,
+      request: (email, ip) => this.handleRequest(email, ip),
+      verify: (email, code, ip) => this.handleVerify(email, code, ip),
+      session: (token) => verifySession(token),
+      status: async (token) => ({
+        authenticated: Boolean(await verifySession(token)),
+        email: (await verifySession(token)) ?? undefined,
+        enabled: true,
+      }),
+    };
+  }
+
+  private async handleRequest(
+    email: string,
+    ip: string,
+  ): Promise<{ ok: true; retryAfter?: number }> {
+    const address = email.trim().toLowerCase();
+    const byIp = this.requestLimiter.hit(`ip:${ip}`);
+    const byEmail = this.requestLimiter.hit(`email:${address}`);
+    if (!byIp.allowed || !byEmail.allowed) {
+      return { ok: true, retryAfter: byIp.retryAfter ?? byEmail.retryAfter };
+    }
+    if (looksLikeEmail(address) && matchesAllowlist(address, this.resolved.allow)) {
+      const code = await this.codes.issue(address);
+      try {
+        await this.config.sendCode?.(address, code, {
+          subject: this.resolved.subject,
+          brandName: this.resolved.brandName,
+          message: this.resolved.message,
+        });
+      } catch (error) {
+        logger.warn("failed to send OTP email", { error });
+      }
+    }
+    return { ok: true };
+  }
+
+  private async handleVerify(
+    email: string,
+    code: string,
+    ip: string,
+  ): Promise<{ ok: boolean; token?: string; retryAfter?: number }> {
+    const address = email.trim().toLowerCase();
+    const byIp = this.verifyLimiter.hit(`ip:${ip}`);
+    const byEmail = this.verifyLimiter.hit(`email:${address}`);
+    if (!byIp.allowed || !byEmail.allowed) {
+      return { ok: false, retryAfter: byIp.retryAfter ?? byEmail.retryAfter };
+    }
+    if ((await this.codes.verify(address, code.trim())) !== "ok") return { ok: false };
+    this.requestLimiter.reset(`email:${address}`);
+    this.verifyLimiter.reset(`email:${address}`);
+    return { ok: true, token: await signSession(address, this.resolved.sessionTtlSeconds) };
+  }
+}
+
+/** Factory: `authGate({ allow, subject, ... })` for an AppKit `plugins` array. */
+export const authGate = toPlugin(AuthGatePlugin);

package/src/portr.ts

@@ -0,0 +1,110 @@
+/**
+ * portr install + config + launch for the tunnel CLI.
+ *
+ * On a Databricks App the container's `$HOME` is read-only on cold start, so the
+ * portr binary and its config are placed under a writable, cwd-rooted `.home`.
+ * The install is idempotent (the installer skips when the on-PATH binary is
+ * current). The config is rendered from `PUBLIC_DOMAIN` (`<subdomain>.<server>`)
+ * + `PORTR_TOKEN` and points portr at the PUBLIC port (the proxy listens there).
+ *
+ * @module
+ */
+
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { delimiter, join } from "node:path";
+import { log } from "@dbx-tools/shared-core";
+
+const logger = log.logger("tunnel:portr");
+
+/** Resolved portr wiring, or `undefined` when no tunnel is configured. */
+export interface PortrConfig {
+  subdomain: string;
+  server: string;
+  token: string;
+  port: number;
+}
+
+/**
+ * Resolve portr config from `PUBLIC_DOMAIN` + `PORTR_TOKEN`, or an explicit
+ * `subdomain`. `PUBLIC_DOMAIN` is `<subdomain>.<server>` (e.g.
+ * `demo.apps.dbx.tools`). Returns `undefined` (no tunnel) when the token or a
+ * usable domain is absent.
+ */
+export function resolvePortrConfig(opts: {
+  publicDomain?: string;
+  subdomain?: string;
+  token?: string;
+  port: number;
+}): PortrConfig | undefined {
+  const token = opts.token ?? process.env.PORTR_TOKEN;
+  const domain = opts.publicDomain ?? process.env.PUBLIC_DOMAIN;
+  if (!token) return undefined;
+  let subdomain = opts.subdomain;
+  let server: string | undefined;
+  if (domain) {
+    subdomain ??= domain.split(".")[0];
+    server = domain.slice(domain.indexOf(".") + 1);
+  }
+  server ??= process.env.PORTR_SERVER;
+  if (!subdomain || !server || server === domain) return undefined;
+  return { subdomain, server, token, port: opts.port };
+}
+
+/** The writable home portr installs + configures under (Apps `$HOME` is read-only). */
+function portrHome(): string {
+  const home = join(process.cwd(), ".home");
+  mkdirSync(join(home, ".portr", "bin"), { recursive: true });
+  return home;
+}
+
+/** Install portr (idempotent) into the cwd-rooted home and return the child env. */
+export function installPortr(): NodeJS.ProcessEnv {
+  const home = portrHome();
+  const env: NodeJS.ProcessEnv = {
+    ...process.env,
+    HOME: home,
+    PORTR_AUTO_ADD_PATH: "no",
+    PATH: [join(home, ".portr", "bin"), process.env.PATH ?? ""].join(delimiter),
+  };
+  logger.info("installing portr (idempotent)");
+  const res = spawnSync("bash", ["-c", "curl -sSf https://install.portr.dev | sh"], {
+    env,
+    stdio: "inherit",
+  });
+  if (res.status !== 0) throw new Error("portr install failed");
+  return env;
+}
+
+/** Render `~/.portr/config.yaml` for the resolved tunnel. */
+export function writePortrConfig(config: PortrConfig, env: NodeJS.ProcessEnv): void {
+  const path = join(env.HOME!, ".portr", "config.yaml");
+  writeFileSync(
+    path,
+    [
+      `server_url: ${config.server}`,
+      `ssh_url: ${config.server}:4444`,
+      `secret_key: ${config.token}`,
+      "disable_dashboard: true",
+      "disable_tui: true",
+      "tunnels:",
+      `  - name: ${config.subdomain}`,
+      `    subdomain: ${config.subdomain}`,
+      `    port: ${config.port}`,
+      "",
+    ].join("\n"),
+  );
+}
+
+/** Launch `portr start` as a child process (caller supervises + kills it). */
+export function startPortr(config: PortrConfig, env: NodeJS.ProcessEnv): ReturnType<typeof spawn> {
+  // Reclaim the subdomain from any portr left by a previous boot in this container.
+  spawnSync("pkill", ["-x", "portr"], { stdio: "ignore" });
+  logger.info(`portr tunneling https://${config.subdomain}.${config.server} -> :${config.port}`);
+  return spawn("portr", ["start"], { env, stdio: "inherit" });
+}
+
+/** True when the installed portr binary path exists (post-install sanity). */
+export function portrInstalled(env: NodeJS.ProcessEnv): boolean {
+  return existsSync(join(env.HOME!, ".portr", "bin", "portr"));
+}