@dbx-tools/cli-tunnel 0.6.48 → 0.6.49

package/src/cli.ts

@@ -26,9 +26,10 @@
  */
 
 import { type ChildProcess, spawn } from "node:child_process";
-import { log } from "@dbx-tools/shared-core";
+import { env, log } from "@dbx-tools/shared-core";
 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 { startProxy } from "./proxy.ts";
@@ -52,6 +53,7 @@ interface TunnelOpts {
   sessionTtl?: string;
   codeTtl?: string;
   insecure?: boolean;
+  forwardHeaders?: string;
 }
 
 /** Build the commander program. `--` separates flags from the app start command. */
@@ -59,20 +61,24 @@ 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 AUTH_SUBJECT)")
+    .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 EMAIL_AUTH_ALLOW)",
+      "Comma/space-separated allow-list: domain / glob / /regex/ (env TUNNEL_AUTH_ALLOW)",
     )
-    .option("--subdomain <name>", "portr subdomain (else derived from PUBLIC_DOMAIN)")
-    .option("--public-domain <host>", "portr <subdomain>.<server> (env PUBLIC_DOMAIN)")
+    .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 AUTH_BRAND_NAME; defaults to the brand context 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(
+      "--forward-headers <patterns>",
+      "Extra x- request headers tunnel traffic may forward: literal / glob / /regex/ (env TUNNEL_FORWARD_HEADERS)",
     )
-    .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.",
@@ -143,7 +149,7 @@ export async function runCli(argv: string[]): Promise<void> {
   // 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 ?? "");
+  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");
@@ -159,7 +165,13 @@ export async function runCli(argv: string[]): Promise<void> {
   }
 
   // 3. Start the gate proxy on the public port (open when `gate` is undefined).
-  await startProxy({ publicPort, appPort, gate });
+  //    `forwardHeaders` only ADDS to the built-in allow-list; see `./headers.ts`.
+  await startProxy({
+    publicPort,
+    appPort,
+    gate,
+    forwardHeaders: env.list(opts.forwardHeaders, FORWARD_HEADERS_ENV),
+  });
 
   // 4. Install + run portr when a tunnel is configured.
   const portrConfig = resolvePortrConfig({
@@ -169,11 +181,13 @@ export async function runCli(argv: string[]): Promise<void> {
   });
   const children: ChildProcess[] = [app];
   if (portrConfig) {
-    const env = installPortr();
-    writePortrConfig(portrConfig, env);
-    children.push(startPortr(portrConfig, env));
+    const portrEnv = installPortr();
+    writePortrConfig(portrConfig, portrEnv);
+    children.push(startPortr(portrConfig, portrEnv));
   } else {
-    logger.info("no PORTR_TOKEN/PUBLIC_DOMAIN - serving the gate proxy without a public tunnel");
+    logger.info(
+      "no PORTR_TOKEN/TUNNEL_PUBLIC_DOMAIN - serving the gate proxy without a public tunnel",
+    );
   }
 
   // Any child exit (or a signal) tears the whole thing down.

package/src/env.ts

@@ -0,0 +1,62 @@
+/**
+ * Environment-variable names the tunnel reads.
+ *
+ * Every setting is `TUNNEL_`-prefixed, matching the repo convention of naming a
+ * variable after the package that owns it (`MASTRA_*`, `TEAMS_*`,
+ * `WEB_SEARCH_*`). The gate's original names were unprefixed (`AUTH_SUBJECT`,
+ * `PUBLIC_DOMAIN`, ...), which is a real hazard for a package that runs as a
+ * WRAPPER: the tunnel and the app it wraps share one environment, so a generic
+ * name is one the wrapped app may already use for something else, and
+ * `PUBLIC_DOMAIN` in particular reads like an app-wide setting rather than a
+ * portr detail. `EMAIL_AUTH_ALLOW` was worse than generic - it sat in
+ * `@dbx-tools/email`'s `EMAIL_*` namespace while configuring the gate, not email.
+ *
+ * Each entry is an {@link EnvKey} list, EARLIEST-WINS, whose first element is the
+ * current name and whose remaining elements are the deprecated originals. A
+ * deployment set up against the old names keeps working; nothing needs a
+ * coordinated rename. Read them through `env.string` / `env.positiveInt` /
+ * `env.list`, which accept the list directly.
+ *
+ * Not renamed:
+ *
+ *   - `DATABRICKS_APP_PORT` - the Databricks Apps runtime contract. The platform
+ *     sets it; the gate honours it.
+ *   - `PORTR_TOKEN` / `PORTR_SERVER` / `PORTR_AUTO_ADD_PATH` - upstream
+ *     [portr](https://github.com/amalshaji/portr)'s own namespace, and
+ *     `PORTR_AUTO_ADD_PATH` is passed straight to that binary. Renaming these
+ *     would rename someone else's contract.
+ *
+ * @module
+ */
+
+import type { EnvKey } from "@dbx-tools/shared-core";
+
+/** Access allow-list patterns (domain / glob / `/regex/`). */
+export const ALLOW_ENV: EnvKey = ["TUNNEL_AUTH_ALLOW", "EMAIL_AUTH_ALLOW"];
+
+/** Subject line for the code email. */
+export const SUBJECT_ENV: EnvKey = ["TUNNEL_AUTH_SUBJECT", "AUTH_SUBJECT"];
+
+/** Display name used in the code email copy. */
+export const BRAND_NAME_ENV: EnvKey = ["TUNNEL_AUTH_BRAND_NAME", "AUTH_BRAND_NAME"];
+
+/** Line shown immediately above the code in the email. */
+export const MESSAGE_ENV: EnvKey = ["TUNNEL_AUTH_MESSAGE", "AUTH_MESSAGE"];
+
+/** Session lifetime, in seconds. */
+export const SESSION_TTL_ENV: EnvKey = ["TUNNEL_AUTH_SESSION_TTL", "AUTH_SESSION_TTL"];
+
+/** One-time-code lifetime, in seconds. */
+export const CODE_TTL_ENV: EnvKey = ["TUNNEL_AUTH_CODE_TTL", "AUTH_CODE_TTL"];
+
+/** HS256 signing secret for the session JWT. */
+export const JWT_SECRET_ENV: EnvKey = ["TUNNEL_AUTH_JWT_SECRET", "AUTH_JWT_SECRET"];
+
+/** The public `<subdomain>.<server>` portr should serve on. */
+export const PUBLIC_DOMAIN_ENV: EnvKey = ["TUNNEL_PUBLIC_DOMAIN", "PUBLIC_DOMAIN"];
+
+/** Run the tunnel OPEN, with no gate. Ignored unless truthy. */
+export const INSECURE_ENV: EnvKey = "TUNNEL_INSECURE";
+
+/** Extra `x-` request headers tunnel traffic may forward. */
+export const FORWARD_HEADERS_ENV: EnvKey = "TUNNEL_FORWARD_HEADERS";

package/src/headers.ts

@@ -0,0 +1,155 @@
+/**
+ * Inbound header policy for tunnel traffic.
+ *
+ * Everything the gate forwards arrives from the PUBLIC internet through the
+ * portr client, so every header on it is attacker-controlled. The headers an app
+ * trusts are precisely the ones a caller must not be able to write, because the
+ * app cannot tell a header the Databricks front door set from one a browser
+ * typed.
+ *
+ * ## Policy shape: strip by default, allow by pattern
+ *
+ * Enumerating what to remove is a losing game - a deny-list is only correct until
+ * the platform adds a header or a library starts trusting another one - so the
+ * policy is inverted. EVERY `x-`-prefixed request header is dropped from tunnel
+ * traffic unless it matches a configured pattern. That fails CLOSED: a header
+ * nobody thought about is removed rather than trusted.
+ *
+ * The allow-list is zero-to-many literals, globs, or `/regex/`es, compiled by
+ * shared-core's {@link pattern.toPatternMatcher}, and is UNIONED with
+ * {@link DEFAULT_FORWARD_HEADERS} so extending it never silently breaks the
+ * built-in surfaces. Configure it with `forwardHeaders` /
+ * `TUNNEL_FORWARD_HEADERS`.
+ *
+ * Non-`x-` headers are untouched. Standard ones (`content-type`, `accept`,
+ * `authorization`, `cookie`, ...) are the app's normal input and the gate has no
+ * business rewriting them.
+ *
+ * ## The headers no pattern can forward
+ *
+ * {@link PROTECTED_HEADERS} is stripped BEFORE the allow-list is consulted, so a
+ * permissive pattern (`x-*`, or a careless `*`) cannot re-open impersonation:
+ *
+ * | Header                           | What an app does with it        | Why spoofing it matters |
+ * | -------------------------------- | ------------------------------- | ----------------------- |
+ * | `x-forwarded-access-token`       | OBO auth (AppKit `asUser`)      | Paste any workspace token and every call runs as its owner. The gate's verified email says nothing about who a pasted credential belongs to. |
+ * | `x-forwarded-user`               | Caller identity                 | Impersonate another user. The gate sets this itself, from a verified session. |
+ * | `x-forwarded-email`              | Caller identity                 | Same. |
+ * | `x-forwarded-preferred-username` | Display name from the IdP       | Same. |
+ * | `x-forwarded-host`               | The originally-requested host    | Poison absolute URLs the app builds (the classic reset-link attack). |
+ * | `x-forwarded-proto` / `-port`    | Original scheme / port          | Convince the app a plaintext request arrived over TLS. |
+ * | `x-forwarded-for`                | Client IP                       | Forge the audit trail, and fan out per-IP rate-limit keys (see below). |
+ * | `x-real-ip`                      | Client IP                       | Same. |
+ * | `x-request-id`                   | Request correlation UUID        | Forge or collide trace ids, making logs unreliable. |
+ *
+ * The identity four are AppKit's OBO contract; the rest are the `X-Forwarded-*`
+ * set the Databricks Apps reverse proxy documents passing to an app
+ * ({@link https://docs.databricks.com/aws/en/dev-tools/databricks-apps/http-headers}),
+ * plus the conventional `x-forwarded-proto`/`-port`/`x-real-ip` an app or one of
+ * its libraries may read even though the table omits them.
+ *
+ * Stripping the `x-forwarded-*` transport trio is safe because `http-proxy-3` is
+ * configured with `xfwd: true` and re-adds them AFTER this policy runs - from the
+ * real socket, not from the caller's claim. The app therefore sees the honest
+ * (loopback) values instead of whatever the internet asserted. The gate reads the
+ * client IP for rate limiting from the raw inbound headers BEFORE stripping, and
+ * takes the RIGHTMOST `x-forwarded-for` entry, which is the only one a proxy
+ * appended rather than a client supplied.
+ *
+ * @module
+ */
+
+import { pattern, token, type Predicate } from "@dbx-tools/shared-core";
+
+/**
+ * Headers the gate strips UNCONDITIONALLY, before the allow-list is consulted -
+ * the platform-shaped set documented in this module's table.
+ *
+ * These answer WHO a request is and WHERE it came from, and on tunnel traffic
+ * only the gate may answer that: it injects {@link token.USER_ID_HEADER} /
+ * {@link token.USER_EMAIL_HEADER} itself after verifying a session, and the proxy
+ * re-derives the transport headers from the real socket.
+ *
+ * The identity names come from the shared `token` constants, so a renamed wire
+ * contract cannot leave a stale spelling here. `x-forwarded-preferred-username`
+ * has no constant because nothing in this repo READS it - it is listed precisely
+ * so a host app that does read it cannot be fed one.
+ */
+export const PROTECTED_HEADERS: readonly string[] = [
+  token.ACCESS_TOKEN_HEADER,
+  token.USER_ID_HEADER,
+  token.USER_EMAIL_HEADER,
+  "x-forwarded-preferred-username",
+  "x-forwarded-host",
+  "x-forwarded-proto",
+  "x-forwarded-port",
+  "x-forwarded-for",
+  "x-real-ip",
+  "x-request-id",
+];
+
+/**
+ * The `x-` headers forwarded when a deployment configures nothing.
+ *
+ * These are the header NAMESPACES this repo's own UI sends and its own server
+ * reads - Mastra thread/model routing (`x-mastra-thread-id`, `x-mastra-model`)
+ * and MLflow trace correlation (`x-mlflow-trace-id`) - so a dbx-tools app keeps
+ * working behind the tunnel with no configuration.
+ *
+ * Deliberately GLOBS rather than the exact constants from
+ * `@dbx-tools/shared-mastra`: importing them would make the gate - a
+ * transport-level component that has no other opinion about Mastra - depend on
+ * an agent package for three strings, and a namespace glob also covers the next
+ * header those packages add. The namespaces are the stable part of the contract.
+ */
+export const DEFAULT_FORWARD_HEADERS: readonly string[] = [
+  "x-mastra-*",
+  "x-mlflow-*",
+  // Sent by fetch/XHR wrappers to mark an AJAX request; harmless and widely read.
+  "x-requested-with",
+];
+
+/** A compiled inbound-header policy. Build one with {@link toHeaderPolicy}. */
+export interface HeaderPolicy {
+  /** The allow-list entries backing this policy (for diagnostics and tests). */
+  readonly patterns: readonly string[];
+  /** Whether `name` survives on tunnel traffic. */
+  forwards(name: string): boolean;
+  /**
+   * Delete every disallowed header from a mutable Node header bag, returning the
+   * lower-cased names removed (for debug logging).
+   */
+  apply(headers: Record<string, unknown>): string[];
+}
+
+/**
+ * Compile the inbound-header policy. `configured` entries are UNIONED with
+ * {@link DEFAULT_FORWARD_HEADERS}; each may be a literal name, a glob
+ * (`x-myapp-*`), or a `/regex/`. Matching is case-insensitive.
+ */
+export function toHeaderPolicy(configured: readonly string[] = []): HeaderPolicy {
+  const patterns = [...DEFAULT_FORWARD_HEADERS, ...configured];
+  const allowed: Predicate<string> = pattern.toPatternMatcher(patterns);
+  const protectedNames = new Set(PROTECTED_HEADERS);
+
+  const forwards = (name: string): boolean => {
+    const lower = name.toLowerCase();
+    if (protectedNames.has(lower)) return false;
+    if (!lower.startsWith("x-")) return true;
+    return allowed(lower);
+  };
+
+  return {
+    patterns,
+    forwards,
+    apply: (headers) => {
+      const removed: string[] = [];
+      for (const name of Object.keys(headers)) {
+        if (forwards(name)) continue;
+        delete headers[name];
+        removed.push(name.toLowerCase());
+      }
+      return removed;
+    },
+  };
+}

package/src/otp.ts

@@ -9,7 +9,7 @@
  * 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 uses an
+ * email. Its signing key comes from `TUNNEL_AUTH_JWT_SECRET`; when unset the gate uses an
  * ephemeral per-process key rather than refusing service, so an unset secret
  * degrades to "sessions don't survive a restart", not "nobody can log in". Note
  * what this does NOT weaken: a caller still needs a code delivered to an
@@ -22,8 +22,9 @@
 
 import { createHash, randomBytes, randomInt, timingSafeEqual } from "node:crypto";
 import { CacheManager } from "@databricks/appkit";
-import { log } from "@dbx-tools/shared-core";
+import { env, log } from "@dbx-tools/shared-core";
 import { jwtVerify, SignJWT } from "jose";
+import { JWT_SECRET_ENV } from "./env.ts";
 
 const logger = log.logger("tunnel:otp");
 
@@ -107,18 +108,18 @@ export class CodeStore {
 }
 
 /**
- * Resolve the HS256 signing key. Prefers `AUTH_JWT_SECRET`; when unset, mints an
+ * Resolve the HS256 signing key. Prefers `TUNNEL_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();
+  const secret = env.text(JWT_SECRET_ENV);
   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",
+      `${JWT_SECRET_ENV[0]} is not set - using an ephemeral per-process key; sessions will not survive a restart`,
     );
     cachedKey = randomBytes(32);
   }

package/src/plugin.ts

@@ -20,6 +20,14 @@ import { Plugin, toPlugin, type BasePluginConfig, type PluginManifest } from "@d
 import { brand, env, log, 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";
 
@@ -27,10 +35,10 @@ 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-list patterns (domain / glob / `/regex/`). Empty = allow nobody. Env TUNNEL_AUTH_ALLOW. */
   allow?: string | string[];
   /**
-   * Subject line for the code email. Env AUTH_SUBJECT.
+   * 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
@@ -40,7 +48,7 @@ export interface AuthGateConfig extends BasePluginConfig {
    */
   subject?: string;
   /**
-   * Display name used in the code email copy. Env AUTH_BRAND_NAME.
+   * 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
@@ -48,15 +56,15 @@ export interface AuthGateConfig extends BasePluginConfig {
    */
   brandName?: string;
   /**
-   * Line shown immediately above the code in the email. Env AUTH_MESSAGE.
+   * 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 AUTH_SESSION_TTL. Default 43200 (12h). */
+  /** Session lifetime (seconds). Env TUNNEL_AUTH_SESSION_TTL. Default 43200 (12h). */
   sessionTtlSeconds?: number;
-  /** One-time-code lifetime (seconds). Env AUTH_CODE_TTL. Default 600 (10m). */
+  /** 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;
@@ -108,21 +116,19 @@ const DEFAULTS = {
 export function resolveAuthGateConfig(config: AuthGateConfig): ResolvedAuthGateConfig {
   return {
     // Both sources are unioned rather than one overriding: a deployment-wide
-    // EMAIL_AUTH_ALLOW and a per-invocation `--allow` should both grant access.
-    allow: [...string.parseList(config.allow), ...string.parseList(process.env.EMAIL_AUTH_ALLOW)],
-    subject: env.string(config.subject, "AUTH_SUBJECT") ?? DEFAULTS.subject,
-    brandName: env.string(config.brandName, "AUTH_BRAND_NAME") ?? DEFAULTS.brandName,
-    message: env.string(config.message, "AUTH_MESSAGE") ?? DEFAULTS.message,
+    // 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,
-      "AUTH_SESSION_TTL",
+      SESSION_TTL_ENV,
       DEFAULTS.sessionTtlSeconds,
     ),
-    codeTtlSeconds: env.positiveInt(
-      config.codeTtlSeconds,
-      "AUTH_CODE_TTL",
-      DEFAULTS.codeTtlSeconds,
-    ),
+    codeTtlSeconds: env.positiveInt(config.codeTtlSeconds, CODE_TTL_ENV, DEFAULTS.codeTtlSeconds),
     maxAttempts: config.maxAttempts ?? DEFAULTS.maxAttempts,
   };
 }

package/src/portr.ts

@@ -5,7 +5,7 @@
  * 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 `PUBLIC_DOMAIN` (`<subdomain>.<server>`)
+ * 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
@@ -14,7 +14,8 @@
 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";
+import { env, log } from "@dbx-tools/shared-core";
+import { PUBLIC_DOMAIN_ENV } from "./env.ts";
 
 const logger = log.logger("tunnel:portr");
 
@@ -27,8 +28,8 @@ export interface PortrConfig {
 }
 
 /**
- * Resolve portr config from `PUBLIC_DOMAIN` + `PORTR_TOKEN`, or an explicit
- * `subdomain`. `PUBLIC_DOMAIN` is `<subdomain>.<server>` (e.g.
+ * 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.
  */
@@ -38,8 +39,9 @@ export function resolvePortrConfig(opts: {
   token?: string;
   port: number;
 }): PortrConfig | undefined {
-  const token = opts.token ?? process.env.PORTR_TOKEN;
-  const domain = opts.publicDomain ?? process.env.PUBLIC_DOMAIN;
+  // 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;
@@ -47,7 +49,7 @@ export function resolvePortrConfig(opts: {
     subdomain ??= domain.split(".")[0];
     server = domain.slice(domain.indexOf(".") + 1);
   }
-  server ??= process.env.PORTR_SERVER;
+  server ??= env.text("PORTR_SERVER") ?? undefined;
   if (!subdomain || !server || server === domain) return undefined;
   return { subdomain, server, token, port: opts.port };
 }

package/src/proxy.ts

@@ -27,9 +27,10 @@
 
 import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
 import type { Socket } from "node:net";
-import { http, json, log } from "@dbx-tools/shared-core";
+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");
@@ -74,10 +75,22 @@ export interface ProxyOptions {
    * 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 }: ProxyOptions): Promise<void> {
+export function startProxy({
+  publicPort,
+  appPort,
+  gate,
+  forwardHeaders,
+}: ProxyOptions): Promise<void> {
   const proxy = ProxyModule.createProxyServer({
     target: { host: "127.0.0.1", port: appPort },
     ws: true,
@@ -91,6 +104,10 @@ export function startProxy({ publicPort, appPort, gate }: ProxyOptions): Promise
     }
   });
 
+  // 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 =>
     [
@@ -104,11 +121,25 @@ export function startProxy({ publicPort, appPort, gate }: ProxyOptions): Promise
       .filter(Boolean)
       .join("; ");
 
-  /** Client IP for rate-limiting: the portr-forwarded XFF, else the socket. */
+  /**
+   * 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 fwd = req.headers["x-forwarded-for"];
-    const first = Array.isArray(fwd) ? fwd[0] : fwd?.split(",")[0];
-    return (first ?? req.socket.remoteAddress ?? "unknown").trim();
+    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";
   };
 
   /**
@@ -129,14 +160,38 @@ export function startProxy({ publicPort, appPort, gate }: ProxyOptions): Promise
 
   /**
    * Present an OTP-authenticated caller to the app the SAME way a platform front
-   * door does: set `x-forwarded-user` / `x-forwarded-email` to the verified
-   * address (AppKit reads `x-forwarded-user` for the OBO user id), so the app
-   * needs no gate-specific code path. Any inbound copies are overwritten so a
-   * client can't spoof identity through the gate.
+   * 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["x-forwarded-user"] = email;
-    req.headers["x-forwarded-email"] = email;
+    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) => {
@@ -184,10 +239,9 @@ export function startProxy({ publicPort, appPort, gate }: ProxyOptions): Promise
       );
     }
 
-    // Anti-spoof: strip any inbound identity headers on portr traffic - only the
-    // gate may set them, below, for a verified session.
-    delete req.headers["x-forwarded-user"];
-    delete req.headers["x-forwarded-email"];
+    // 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.
@@ -218,8 +272,7 @@ export function startProxy({ publicPort, appPort, gate }: ProxyOptions): Promise
       proxy.ws(req, socket, head);
       return;
     }
-    delete req.headers["x-forwarded-user"];
-    delete req.headers["x-forwarded-email"];
+    applyHeaderPolicy(req);
     if (!(req.url ?? "").startsWith("/api/")) {
       stripSessionCookie(req);
       proxy.ws(req, socket, head);