@dbx-tools/tunnel 0.6.60

package/src/env.ts

@@ -0,0 +1,72 @@
+/**
+ * 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"];
+
+/**
+ * Force-clear cutoff: every session issued BEFORE it stops verifying. Anything
+ * `object.toDate` accepts - a date, an ISO instant, epoch seconds/millis, or a
+ * relative duration (`-30d`, `7 days ago`).
+ */
+export const SESSION_CUTOFF_ENV: EnvKey = [
+  "TUNNEL_AUTH_SESSION_CUTOFF",
+  "TUNNEL_AUTH_SESSION_EPOCH",
+];
+
+/** 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/interceptor.ts

@@ -0,0 +1,105 @@
+/**
+ * `tunnelInterceptor()` - the {@link Interceptor} that fronts an app with a public
+ * portr tunnel, consuming the {@link InterceptorContext} `@dbx-tools/appkit`'s
+ * `createApp` hands it.
+ *
+ * This is the in-process replacement for the old `dbxt-tunnel -- <cmd>` wrapper.
+ * Instead of the tunnel being the main process that spawns the app as a child, the
+ * APP is the main process and hands this interceptor its context. The interceptor:
+ *
+ *   1. applies the workspace host the context computed to `process.env`
+ *      (`DATABRICKS_HOST`), so portr and any later SDK call agree on the workspace;
+ *   2. installs + launches portr, pointed at the app's PUBLIC port;
+ *   3. `bindProcess`es portr so the app and the tunnel live and die as one -
+ *      signals pass through and either death tears the pair down (the
+ *      concurrently-style supervision that used to be `superviseExit`);
+ *   4. registers an AppKit `shutdown` lifecycle handler so an orderly app shutdown
+ *      also stops portr.
+ *
+ * The email-OTP GATE is a separate concern: it is the {@link authGate} AppKit
+ * plugin plus the {@link startProxy} reverse-proxy, both exported from this package
+ * for an app that wants to gate the tunnelled traffic. This interceptor is only the
+ * portr half - "update the host, bind portr" - matching the smallest useful unit.
+ *
+ * @module
+ */
+
+import type { Interceptor, InterceptorContext } from "@dbx-tools/appkit";
+import { log } from "@dbx-tools/shared-core";
+import { installPortr, resolvePortrConfig, startPortr, writePortrConfig } from "./portr.ts";
+
+const logger = log.logger("tunnel:interceptor");
+
+/** Options for {@link tunnelInterceptor} (each also resolvable from env). */
+export interface TunnelInterceptorOptions {
+  /** portr `<subdomain>.<server>` to serve on. Env `TUNNEL_PUBLIC_DOMAIN`. */
+  publicDomain?: string;
+  /** portr subdomain (else derived from {@link publicDomain}). */
+  subdomain?: string;
+  /**
+   * The PUBLIC port portr forwards to - the port the app itself listens on.
+   * Defaults to the Databricks Apps runtime contract `DATABRICKS_APP_PORT`
+   * (then `8000`), which is the port the platform routes to.
+   */
+  port?: number;
+}
+
+/** Resolve the public port portr should target: explicit, else the Apps contract. */
+function resolvePublicPort(port?: number): number {
+  return port ?? Number(process.env.DATABRICKS_APP_PORT ?? 8000);
+}
+
+/**
+ * Build the tunnel {@link Interceptor}. Pass it to `createApp({ interceptor })`.
+ *
+ * A no-op (logs and returns) when no portr tunnel is configured - no `PORTR_TOKEN`
+ * or no resolvable `<subdomain>.<server>` - so an app can register it
+ * unconditionally and only actually tunnels where the deployment wired portr.
+ *
+ * @example
+ * import { createApp } from "@dbx-tools/appkit";
+ * import { tunnelInterceptor } from "@dbx-tools/tunnel";
+ *
+ * await createApp({
+ *   plugins: [server({ host, staticPath })],
+ *   interceptor: tunnelInterceptor(),
+ * });
+ */
+export function tunnelInterceptor(options: TunnelInterceptorOptions = {}): Interceptor {
+  return (ctx: InterceptorContext): void => {
+    // 1. Apply the computed workspace host so portr + the SDK agree. The context
+    //    already resolved it (from the env / auto-config); set it only when it is
+    //    known and not already present, so an explicit env wins.
+    if (ctx.env.databricksHost) {
+      process.env.DATABRICKS_HOST ??= ctx.env.databricksHost;
+    }
+
+    // 2. Resolve portr wiring. No token / domain -> no tunnel; leave the app alone.
+    //    `resolvePortrConfig` already falls back to TUNNEL_PUBLIC_DOMAIN itself, so
+    //    the explicit option is passed straight through.
+    const port = resolvePublicPort(options.port);
+    const portrConfig = resolvePortrConfig({
+      publicDomain: options.publicDomain,
+      subdomain: options.subdomain,
+      port,
+    });
+    if (!portrConfig) {
+      logger.info("no PORTR_TOKEN/TUNNEL_PUBLIC_DOMAIN - the app runs without a public tunnel");
+      return;
+    }
+
+    // 3. Install + launch portr, then bind it: the app and portr now share a fate.
+    const portrEnv = installPortr();
+    writePortrConfig(portrConfig, portrEnv);
+    const portr = startPortr(portrConfig, portrEnv);
+    ctx.bindProcess(portr);
+
+    // 4. An orderly AppKit shutdown also stops portr (belt-and-suspenders with the
+    //    signal pass-through `bindProcess` already installed).
+    ctx.onLifecycle("shutdown", () => {
+      if (!portr.killed) portr.kill("SIGTERM");
+    });
+
+    logger.info(`tunnel bound: portr -> :${port} (${portrConfig.subdomain}.${portrConfig.server})`);
+  };
+}

package/src/otp.ts

@@ -0,0 +1,137 @@
+/**
+ * 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 an HS256 token (via `jose`) carrying only the email. Its
+ * signing key is resolved by `./signing-key.ts`: `TUNNEL_AUTH_JWT_SECRET` when
+ * set, else a key persisted in the cache for 30 days so cookies survive the
+ * restarts a tunnel sees whenever the app it wraps reloads. A cookie signed
+ * before `TUNNEL_AUTH_SESSION_CUTOFF` is refused here as well as being orphaned
+ * by the cache key, so the force-clear switch holds even for a still-current key.
+ *
+ * @module
+ */
+
+import { createHash, randomInt, timingSafeEqual } from "node:crypto";
+import { CacheManager } from "@databricks/appkit";
+import { jwtVerify, SignJWT } from "jose";
+import { signingKey } from "./signing-key.ts";
+
+/** 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";
+  }
+}
+
+/** Mint a session JWT for `email`, expiring in `ttlSeconds`. */
+export async function signSession(email: string, ttlSeconds: number): Promise<string> {
+  const { key } = await signingKey();
+  return new SignJWT({ email })
+    .setProtectedHeader({ alg: "HS256" })
+    .setSubject(email)
+    .setAudience(JWT_AUD)
+    .setIssuedAt()
+    .setExpirationTime(`${ttlSeconds}s`)
+    .sign(key);
+}
+
+/** 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 { key, cutoffMs } = await signingKey();
+    const { payload } = await jwtVerify(token, key, { audience: JWT_AUD });
+    // Belt and braces with the cutoff-scoped cache key: that alone already
+    // orphans older keys, but an operator who moved the cutoff while
+    // TUNNEL_AUTH_JWT_SECRET is set has no key rotation to rely on, and this
+    // check is what makes the switch work in that case too.
+    // Compared in whole SECONDS because `iat` has no finer resolution: against a
+    // millisecond cutoff, a cookie minted in the same second as it would be
+    // refused depending on sub-second rounding.
+    if (cutoffMs > 0 && (payload.iat === undefined || payload.iat < Math.floor(cutoffMs / 1000))) {
+      return undefined;
+    }
+    return typeof payload.email === "string" ? payload.email : undefined;
+  } catch {
+    return undefined;
+  }
+}