@dbx-tools/tunnel 0.6.60

package/src/plugin.ts

@@ -0,0 +1,269 @@
+/**
+ * `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 { brand, env, log, object, string } from "@dbx-tools/shared-core";
+import type { AuthStatus } from "@dbx-tools/shared-email";
+import { looksLikeEmail, matchesAllowlist } from "./allowlist.ts";
+import {
+  ALLOW_ENV,
+  BRAND_NAME_ENV,
+  CODE_TTL_ENV,
+  MESSAGE_ENV,
+  SESSION_TTL_ENV,
+  SUBJECT_ENV,
+} from "./env.ts";
+import { CodeStore, signSession, verifySession } from "./otp.ts";
+import { RateLimiter } from "./rate-limit.ts";
+import { KEY_TTL_SECONDS, resolveSessionCutoff, signingKey } from "./signing-key.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 TUNNEL_AUTH_ALLOW. */
+  allow?: string | string[];
+  /**
+   * Subject line for the code email. Env TUNNEL_AUTH_SUBJECT.
+   *
+   * Defaults to "Your verification code". The wording of the subject and
+   * {@link message} is deliberately the conventional phrasing rather than
+   * anything branded: iOS, Gmail, Outlook, and Android all detect a one-time
+   * code from this shape and offer to autofill it, and a novel phrasing is what
+   * breaks that detection.
+   *
+   * This is the subject TEMPLATE, not the literal line sent: the code is spliced
+   * into it (`"123456 is your verification code"`) because a push notification
+   * shows only the subject and preheader, and that notification is what mobile
+   * autofill reads. See `codeEmailSubject` in `./app.ts`.
+   */
+  subject?: string;
+  /**
+   * Display name used in the code email copy. Env TUNNEL_AUTH_BRAND_NAME.
+   *
+   * Defaults to the brand context's `name` - the app's own `branding/brand.yaml`
+   * when it has one, else the dbx-tools default. Set this only to override the
+   * brand for this gate.
+   */
+  brandName?: string;
+  /**
+   * Line shown immediately above the code in the email. Env TUNNEL_AUTH_MESSAGE.
+   *
+   * Keep the code on its OWN line directly after this text - that adjacency is
+   * what the platform code-detection heuristics key on.
+   */
+  message?: string;
+  /**
+   * Session lifetime (seconds). Env TUNNEL_AUTH_SESSION_TTL. Default 2592000 (30d).
+   *
+   * Matched to the cache-backed signing key's own 30-day TTL (see
+   * `./signing-key.ts`): the cookie and the key that validates it should expire
+   * together, or one silently outlives the other.
+   */
+  sessionTtlSeconds?: number;
+  /** One-time-code lifetime (seconds). Env TUNNEL_AUTH_CODE_TTL. Default 600 (10m). */
+  codeTtlSeconds?: number;
+  /** Max verify attempts per issued code. Default 5. */
+  maxAttempts?: number;
+  /**
+   * Force-clear cutoff: every session issued BEFORE it stops verifying, so moving
+   * it forward signs everyone out. Env TUNNEL_AUTH_SESSION_CUTOFF.
+   *
+   * Anything `object.toDate` accepts: a `Date`, `2026-08-02`, an ISO instant,
+   * epoch seconds/millis, or a relative duration (`-30d`, `7 days ago`). Unset
+   * means no cutoff.
+   */
+  sessionCutoff?: string | number | Date;
+  /** 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;
+  /**
+   * Lifetime of the code being sent, in seconds - the RESOLVED
+   * {@link AuthGateConfig.codeTtlSeconds}, so the email can state the real
+   * expiry ("This code expires in 10 minutes") instead of a vague "shortly"
+   * that drifts from the configured TTL.
+   */
+  codeTtlSeconds: number;
+}
+
+/** 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;
+  /** Force-clear cutoff in epoch ms; `0` when unset. */
+  sessionCutoffMs: number;
+}
+
+const DEFAULTS = {
+  subject: "Your verification code",
+  // The repo-wide brand context's display name, NOT a hardcoded product string:
+  // this name is what the recipient reads in the code email, so it has to be the
+  // same identity the rest of the app presents. A host with its own
+  // `branding/brand.yaml` overrides it by passing `brandName` (see
+  // {@link startGateApp}, which resolves the on-disk context); the shared default
+  // is the fallback when nothing is configured.
+  brandName: brand.defaultBrandContext.name,
+  message: "Your verification code is:",
+  // 30 days, the same window the cache-backed signing key is stored for.
+  sessionTtlSeconds: KEY_TTL_SECONDS,
+  codeTtlSeconds: 600,
+  maxAttempts: 5,
+};
+
+/** Merge {@link AuthGateConfig} over env over defaults into a resolved config. */
+export function resolveAuthGateConfig(config: AuthGateConfig): ResolvedAuthGateConfig {
+  return {
+    // Both sources are unioned rather than one overriding: a deployment-wide
+    // TUNNEL_AUTH_ALLOW and a per-invocation `--allow` should both grant access.
+    // Hence `parseList` on each rather than `env.list`, which stops at the first
+    // source that yields anything.
+    allow: [...string.parseList(config.allow), ...string.parseList(env.text(ALLOW_ENV))],
+    subject: env.string(config.subject, SUBJECT_ENV) ?? DEFAULTS.subject,
+    brandName: env.string(config.brandName, BRAND_NAME_ENV) ?? DEFAULTS.brandName,
+    message: env.string(config.message, MESSAGE_ENV) ?? DEFAULTS.message,
+    sessionTtlSeconds: env.positiveInt(
+      config.sessionTtlSeconds,
+      SESSION_TTL_ENV,
+      DEFAULTS.sessionTtlSeconds,
+    ),
+    codeTtlSeconds: env.positiveInt(config.codeTtlSeconds, CODE_TTL_ENV, DEFAULTS.codeTtlSeconds),
+    maxAttempts: config.maxAttempts ?? DEFAULTS.maxAttempts,
+    sessionCutoffMs: resolveSessionCutoff(config.sessionCutoff),
+  };
+}
+
+/** 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);
+    // Resolve the signing key HERE rather than lazily on the first sign-in, so a
+    // cache that cannot hold it (and the resulting "sessions won't survive a
+    // restart" warning) shows up in the startup log, not hours later.
+    const { cutoffMs } = await signingKey(this.resolved.sessionCutoffMs);
+    logger.info("ready", {
+      patterns: this.resolved.allow.length,
+      sessionTtlSeconds: this.resolved.sessionTtlSeconds,
+      ...object.optional("sessionCutoff", cutoffMs > 0 ? new Date(cutoffMs).toISOString() : null),
+    });
+  }
+
+  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,
+          codeTtlSeconds: this.resolved.codeTtlSeconds,
+        });
+      } 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,113 @@
+/**
+ * portr install + config + launch for the tunnel CLI.
+ *
+ * Some hosts (Databricks Apps among them) mount the container's `$HOME` read-only
+ * on cold start, so the portr binary and its config are placed under a writable,
+ * cwd-rooted `.home` unconditionally - it costs nothing where `$HOME` is writable.
+ * The install is idempotent (the installer skips when the on-PATH binary is
+ * current). The config is rendered from `TUNNEL_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 { env, log } from "@dbx-tools/shared-core";
+import { PUBLIC_DOMAIN_ENV } from "./env.ts";
+
+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 `TUNNEL_PUBLIC_DOMAIN` + `PORTR_TOKEN`, or an
+ * explicit `subdomain`. The 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 {
+  // PORTR_* is upstream portr's own namespace, so it keeps its name.
+  const token = env.string(opts.token, "PORTR_TOKEN");
+  const domain = env.string(opts.publicDomain, PUBLIC_DOMAIN_ENV);
+  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 ??= env.text("PORTR_SERVER") ?? undefined;
+  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"));
+}

package/src/proxy.ts

@@ -0,0 +1,299 @@
+/**
+ * The tunnel gate reverse-proxy.
+ *
+ * Binds the PUBLIC port (the container's `DATABRICKS_APP_PORT`) and forwards to
+ * the real app on a private loopback port. It is the single front door for both
+ * traffic paths into the container:
+ *
+ *   - **portr client** (same container, connects over LOOPBACK) - the public
+ *     tunnel. This is what the gate protects.
+ *   - **the hosting platform's front door** (Databricks Apps' control plane, or
+ *     any other host reaching the `0.0.0.0` port from a NON-loopback
+ *     container-network address) - passed through UNGATED, per the rule "if it's
+ *     not from the portr client, let it in". The platform already authenticates
+ *     that path; the gate exists for the tunnel, which nothing else protects.
+ *
+ * The distinguisher is the connection's source address: a loopback
+ * `req.socket.remoteAddress` is the portr client; anything else is the platform.
+ *
+ * For portr traffic the gate is a standard SPA gate: static assets + the login
+ * flow (`/api/email/auth/*`, answered IN-PROCESS by this proxy via the
+ * {@link AuthGateApi}) are open so the browser can load the client and render the
+ * `<AuthGate>`; every other `/api/*` needs a valid session cookie or gets 401.
+ * WebSocket upgrades are gated the same way and forwarded with `http-proxy-3`.
+ *
+ * @module
+ */
+
+import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
+import type { Socket } from "node:net";
+import { http, json, log, token } from "@dbx-tools/shared-core";
+import { authRequestSchema, authVerifySchema, SESSION_COOKIE_NAME } from "@dbx-tools/shared-email";
+import ProxyModule from "http-proxy-3";
+import { toHeaderPolicy, type HeaderPolicy } from "./headers.ts";
+import type { AuthGateApi } from "./plugin.ts";
+
+const logger = log.logger("tunnel:proxy");
+
+/** Route prefix the login flow lives under (open, answered in-process). */
+const AUTH_PREFIX = "/api/email/auth";
+
+/** True when a socket address is loopback (the portr client, same container). */
+function isLoopback(addr: string | undefined): boolean {
+  if (!addr) return false;
+  // Normalize IPv4-mapped IPv6 (`::ffff:127.0.0.1`) and bare IPv6 loopback.
+  const a = addr.replace(/^::ffff:/, "");
+  return a === "127.0.0.1" || a.startsWith("127.") || a === "::1" || a === "localhost";
+}
+
+/** Read the whole request body as text (small JSON payloads only). */
+function readBody(req: IncomingMessage): Promise<string> {
+  return new Promise((resolve) => {
+    let data = "";
+    req.on("data", (chunk) => (data += chunk));
+    req.on("end", () => resolve(data));
+    req.on("error", () => resolve(data));
+  });
+}
+
+function sendJson(res: ServerResponse, status: number, body: unknown, setCookie?: string): void {
+  const headers: Record<string, string> = { "content-type": "application/json" };
+  if (setCookie) headers["set-cookie"] = setCookie;
+  res.writeHead(status, headers);
+  res.end(JSON.stringify(body));
+}
+
+/** Options for {@link startProxy}. */
+export interface ProxyOptions {
+  /** Public port to listen on (the container's DATABRICKS_APP_PORT). */
+  publicPort: number;
+  /** Private port the real app listens on (loopback). */
+  appPort: number;
+  /**
+   * The in-process gate API, or `undefined` to run OPEN (insecure mode): every
+   * request - including portr traffic - is forwarded ungated. Used when the
+   * operator passed `--insecure` / `TUNNEL_INSECURE=true`.
+   */
+  gate?: AuthGateApi;
+  /**
+   * Extra `x-` request headers tunnel traffic may forward, as literals, globs, or
+   * `/regex/`es - unioned with {@link DEFAULT_FORWARD_HEADERS}. Every other `x-`
+   * header is stripped, and {@link PROTECTED_HEADERS} is stripped regardless. See
+   * `./headers.ts` for why the policy is an allow-list.
+   */
+  forwardHeaders?: readonly string[];
+}
+
+/** Start the gate proxy. Resolves once it is listening. */
+export function startProxy({
+  publicPort,
+  appPort,
+  gate,
+  forwardHeaders,
+}: ProxyOptions): Promise<void> {
+  const proxy = ProxyModule.createProxyServer({
+    target: { host: "127.0.0.1", port: appPort },
+    ws: true,
+    xfwd: true,
+  });
+  proxy.on("error", (err: Error, _req: unknown, res: unknown) => {
+    logger.warn("upstream proxy error", { error: err.message });
+    const r = res as ServerResponse | undefined;
+    if (r && "writeHead" in r && !r.headersSent) {
+      sendJson(r, 502, { error: "upstream unavailable" });
+    }
+  });
+
+  // Compiled once: the inbound-header allow-list applied to every gated request.
+  const headerPolicy = toHeaderPolicy(forwardHeaders);
+  logger.debug("inbound header policy", { forward: headerPolicy.patterns });
+
+  /** The session cookie for a verified email, as a Set-Cookie string. */
+  const sessionCookie = (token: string, maxAgeSeconds: number): string =>
+    [
+      `${SESSION_COOKIE_NAME}=${token}`,
+      "Path=/",
+      "HttpOnly",
+      "SameSite=Lax",
+      `Max-Age=${maxAgeSeconds}`,
+      process.env.NODE_ENV === "production" ? "Secure" : "",
+    ]
+      .filter(Boolean)
+      .join("; ");
+
+  /**
+   * Client IP for rate-limiting: the portr client's forwarded XFF, else the socket.
+   *
+   * Deliberately the RIGHTMOST `x-forwarded-for` entry, not the leftmost. The
+   * list grows left-to-right as each hop appends, so the last entry is the one
+   * the nearest trusted proxy (portr) wrote and every earlier entry is a value
+   * the caller could have sent. Reading the leftmost lets a client vary one
+   * header to get a fresh rate-limit bucket per request, which defeats both the
+   * per-IP code-request and verify-attempt limiters. Called BEFORE
+   * {@link HeaderPolicy.apply} strips the header, so the honest hop value is
+   * still available here.
+   */
+  const clientIp = (req: IncomingMessage): string => {
+    const forwarded = req.headers["x-forwarded-for"];
+    const chain = (Array.isArray(forwarded) ? forwarded.join(",") : (forwarded ?? ""))
+      .split(",")
+      .map((entry) => entry.trim())
+      .filter(Boolean);
+    return chain.at(-1) ?? req.socket.remoteAddress ?? "unknown";
+  };
+
+  /**
+   * Remove the gate's session cookie from the `Cookie` header before forwarding,
+   * so the app never sees `dbx_auth` (it is the proxy's concern, not the app's).
+   * Preserves any other cookies. Removes the header entirely when it becomes empty.
+   */
+  const stripSessionCookie = (req: IncomingMessage): void => {
+    const raw = req.headers.cookie;
+    if (!raw) return;
+    const kept = raw
+      .split(";")
+      .map((c) => c.trim())
+      .filter((c) => c && !c.startsWith(`${SESSION_COOKIE_NAME}=`));
+    if (kept.length) req.headers.cookie = kept.join("; ");
+    else delete req.headers.cookie;
+  };
+
+  /**
+   * Present an OTP-authenticated caller to the app the SAME way a platform front
+   * door does: set the front door's own identity headers to the verified address
+   * (AppKit reads {@link token.USER_ID_HEADER} for the OBO user id), so the app
+   * needs no gate-specific code path. The names come from
+   * `@dbx-tools/shared-core`'s `token` module - the same constants AppKit-side
+   * code reads them by - rather than being re-spelled here.
+   *
+   * What the gate CANNOT set is {@link token.ACCESS_TOKEN_HEADER}: an OTP session
+   * proves an email address, not possession of a Databricks credential, and
+   * there is no way to mint one for the caller. Its absence is exactly what
+   * `@dbx-tools/appkit`'s `identity` `"auto"` mode detects, so a gated request
+   * runs as the app's service principal instead of throwing.
+   */
+  const injectIdentity = (req: IncomingMessage, email: string): void => {
+    req.headers[token.USER_ID_HEADER] = email;
+    req.headers[token.USER_EMAIL_HEADER] = email;
+  };
+
+  /**
+   * Apply the inbound-header policy to a tunnel request: every `x-` header the
+   * allow-list does not name is deleted, and the platform identity/transport set
+   * is deleted regardless. See `./headers.ts` for the reasoning; the
+   * security-critical case is {@link token.ACCESS_TOKEN_HEADER}, which the gate
+   * never sets but an app running `identity: "auto"` treats as proof the request
+   * can do OBO.
+   *
+   * `xfwd: true` on the proxy re-adds `x-forwarded-for`/`-proto`/`-port`/`-host`
+   * afterwards from the real socket, so the app still sees those - it just sees
+   * the honest values rather than the caller's claim.
+   */
+  const applyHeaderPolicy = (req: IncomingMessage): void => {
+    const removed = headerPolicy.apply(req.headers as Record<string, unknown>);
+    if (removed.length) logger.debug("stripped inbound headers", { removed });
+  };
+
+  const server = createServer(async (req, res) => {
+    const path = (req.url ?? "/").split("?")[0]!;
+
+    // Insecure/open mode (no gate) OR non-loopback traffic (the hosting
+    // platform's front door / control plane): forward ungated.
+    if (!gate || !isLoopback(req.socket.remoteAddress)) {
+      proxy.web(req, res);
+      return;
+    }
+
+    // --- portr traffic: the gate applies ---
+
+    // The login flow is answered IN-PROCESS (the app has no server to forward to).
+    if (path === `${AUTH_PREFIX}/status`) {
+      const token = http.parseCookies(req.headers.cookie ?? null)[SESSION_COOKIE_NAME];
+      sendJson(res, 200, await gate.status(token));
+      return;
+    }
+    if (path === `${AUTH_PREFIX}/request` && req.method === "POST") {
+      const parsed = authRequestSchema.safeParse(json.parseRecord(await readBody(req)));
+      if (!parsed.success) return sendJson(res, 200, { ok: true }); // anti-enumeration
+      return sendJson(res, 200, await gate.request(parsed.data.email, clientIp(req)));
+    }
+    if (path === `${AUTH_PREFIX}/verify` && req.method === "POST") {
+      const parsed = authVerifySchema.safeParse(json.parseRecord(await readBody(req)));
+      if (!parsed.success) return sendJson(res, 200, { ok: false });
+      const result = await gate.verify(parsed.data.email, parsed.data.code, clientIp(req));
+      const cookie =
+        result.ok && result.token ? sessionCookie(result.token, gate.sessionTtlSeconds) : undefined;
+      return sendJson(
+        res,
+        200,
+        { ok: result.ok, ...(result.retryAfter ? { retryAfter: result.retryAfter } : {}) },
+        cookie,
+      );
+    }
+    if (path === `${AUTH_PREFIX}/logout` && req.method === "POST") {
+      return sendJson(
+        res,
+        200,
+        { ok: true },
+        `${SESSION_COOKIE_NAME}=; Path=/; HttpOnly; Max-Age=0`,
+      );
+    }
+
+    // Anti-spoof: apply the inbound-header allow-list to portr traffic - only the
+    // gate may assert identity, and it does so below for a verified session.
+    applyHeaderPolicy(req);
+
+    // Static (non-API) loads freely so the SPA + <AuthGate> can render. Strip the
+    // session cookie so it never leaks to the static handler.
+    if (!path.startsWith("/api/")) {
+      stripSessionCookie(req);
+      proxy.web(req, res);
+      return;
+    }
+
+    // Every other /api/* requires a valid session.
+    const token = http.parseCookies(req.headers.cookie ?? null)[SESSION_COOKIE_NAME];
+    const email = await gate.session(token);
+    if (email) {
+      // Present the OTP user like a platform front door, and drop the gate
+      // cookie so the app sees a clean, front-door-shaped request.
+      injectIdentity(req, email);
+      stripSessionCookie(req);
+      proxy.web(req, res);
+    } else {
+      sendJson(res, 401, { error: "authentication required", loginPath: AUTH_PREFIX });
+    }
+  });
+
+  // WebSocket upgrades: forward front-door traffic untouched; gate loopback
+  // (portr) API upgrades the same way as HTTP (strip cookie + inject identity).
+  server.on("upgrade", (req: IncomingMessage, socket: Socket, head: Buffer) => {
+    if (!gate || !isLoopback(req.socket.remoteAddress)) {
+      proxy.ws(req, socket, head);
+      return;
+    }
+    applyHeaderPolicy(req);
+    if (!(req.url ?? "").startsWith("/api/")) {
+      stripSessionCookie(req);
+      proxy.ws(req, socket, head);
+      return;
+    }
+    const token = http.parseCookies(req.headers.cookie ?? null)[SESSION_COOKIE_NAME];
+    void gate.session(token).then((email) => {
+      if (!email) {
+        socket.destroy();
+        return;
+      }
+      injectIdentity(req, email);
+      stripSessionCookie(req);
+      proxy.ws(req, socket, head);
+    });
+  });
+
+  return new Promise((resolve) => {
+    server.listen(publicPort, "0.0.0.0", () => {
+      logger.info(`gate proxy on 0.0.0.0:${publicPort} -> app 127.0.0.1:${appPort}`);
+      resolve();
+    });
+  });
+}