@dbx-tools/cli-tunnel 0.6.45 → 0.6.47

package/package.json

@@ -6,8 +6,8 @@
     "directory": "packages/cli/tunnel"
   },
   "bin": {
-    "dbx-tools-tunnel": "./bin/dbx-tools-tunnel.ts",
-    "dbxt-tunnel": "./bin/dbx-tools-tunnel.ts"
+    "dbx-tools-tunnel": "./lib/bin/dbx-tools-tunnel.js",
+    "dbxt-tunnel": "./lib/bin/dbx-tools-tunnel.js"
   },
   "scripts": {
     "build": "projen build",
@@ -29,15 +29,16 @@
   "dependencies": {
     "@clack/prompts": "^1.7.0",
     "@databricks/appkit": "^0.43.0",
-    "@dbx-tools/appkit": "0.6.45",
-    "@dbx-tools/email": "0.6.45",
-    "@dbx-tools/shared-core": "0.6.45",
-    "@dbx-tools/shared-email": "0.6.45",
+    "@dbx-tools/appkit": "0.6.47",
+    "@dbx-tools/core": "0.6.47",
+    "@dbx-tools/email": "0.6.47",
+    "@dbx-tools/shared-core": "0.6.47",
+    "@dbx-tools/shared-email": "0.6.47",
     "commander": "^15.0.0",
     "http-proxy-3": "^1.23.3",
     "jose": "^6.2.3"
   },
-  "main": "index.ts",
+  "main": "./lib/index.js",
   "license": "UNLICENSED",
   "publishConfig": {
     "access": "public",
@@ -87,19 +88,46 @@
       "./package.json": "./package.json"
     }
   },
-  "version": "0.6.45",
-  "types": "index.ts",
+  "version": "0.6.47",
+  "types": "./lib/index.d.ts",
   "type": "module",
   "exports": {
-    ".": "./index.ts",
-    "./allowlist": "./src/allowlist.ts",
-    "./app": "./src/app.ts",
-    "./cli": "./src/cli.ts",
-    "./otp": "./src/otp.ts",
-    "./plugin": "./src/plugin.ts",
-    "./portr": "./src/portr.ts",
-    "./proxy": "./src/proxy.ts",
-    "./rate-limit": "./src/rate-limit.ts",
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./allowlist": {
+      "types": "./lib/src/allowlist.d.ts",
+      "default": "./lib/src/allowlist.js"
+    },
+    "./app": {
+      "types": "./lib/src/app.d.ts",
+      "default": "./lib/src/app.js"
+    },
+    "./cli": {
+      "types": "./lib/src/cli.d.ts",
+      "default": "./lib/src/cli.js"
+    },
+    "./otp": {
+      "types": "./lib/src/otp.d.ts",
+      "default": "./lib/src/otp.js"
+    },
+    "./plugin": {
+      "types": "./lib/src/plugin.d.ts",
+      "default": "./lib/src/plugin.js"
+    },
+    "./portr": {
+      "types": "./lib/src/portr.d.ts",
+      "default": "./lib/src/portr.js"
+    },
+    "./proxy": {
+      "types": "./lib/src/proxy.d.ts",
+      "default": "./lib/src/proxy.js"
+    },
+    "./rate-limit": {
+      "types": "./lib/src/rate-limit.d.ts",
+      "default": "./lib/src/rate-limit.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [

package/src/allowlist.ts

@@ -3,11 +3,11 @@
  *
  * Each pattern in the configured list is one of three shapes, tried in order:
  *
- *   - **domain shortcut** - `databricks.com` or `@databricks.com`: matches any
+ *   - **domain shortcut** - `example.com` or `@example.com`: matches any
  *     address whose domain equals it (case-insensitive). The leading `@` is
  *     optional and stripped.
- *   - **glob** - contains `*` or `?`, e.g. `*.databricks.com` or
- *     `*@databricks.com`: matched against the WHOLE address with shell-style
+ *   - **glob** - contains `*` or `?`, e.g. `*.example.com` or
+ *     `*@example.com`: matched against the WHOLE address with shell-style
  *     wildcards (`*` = any run, `?` = one char).
  *   - **regex** - wrapped in slashes, `/.../ [flags]`: compiled and tested
  *     against the whole address. An invalid regex never matches (it is skipped

package/src/app.ts

@@ -23,15 +23,31 @@
  */
 
 import { createApp as createAppNs } from "@dbx-tools/appkit";
-import { email, sender, transport } from "@dbx-tools/email";
-import { log } from "@dbx-tools/shared-core";
+import { brand as nodeBrand } from "@dbx-tools/core";
+import { brand as emailBrand, email, sender, transport } from "@dbx-tools/email";
+import { log, string } from "@dbx-tools/shared-core";
 import { authGate, type AuthGateApi, type AuthGateConfig } from "./plugin.ts";
 
 const logger = log.logger("tunnel:app");
 
+/**
+ * A code TTL as the plain phrase the email states ("10 minutes", "45 seconds").
+ *
+ * Whole minutes read as minutes; anything else stays in seconds rather than
+ * rounding, so a 90-second TTL is not advertised as "1 minute" and a recipient is
+ * never told the code lives longer than it does.
+ */
+export function expiresIn(seconds: number): string {
+  return seconds >= 60 && seconds % 60 === 0
+    ? string.pluralize(seconds / 60, "minute")
+    : string.pluralize(seconds, "second");
+}
+
 const { createApp } = createAppNs;
 const { resolveSenderAddress } = sender;
 const { getEmailRuntime, sendEmail } = transport;
+const { emailBrandFromContext } = emailBrand;
+const { loadBrandContext } = nodeBrand;
 
 /**
  * Boot the gate app and return the API the proxy calls. Throws when email is not
@@ -40,6 +56,13 @@ const { getEmailRuntime, sendEmail } = transport;
  * fall back to insecure/open mode when the operator opted in.
  */
 export async function startGateApp(config: AuthGateConfig): Promise<AuthGateApi> {
+  // The host app's own brand (`branding/brand.yaml` discovered from cwd) or the
+  // dbx-tools default. This is the ONE brand source for the gate: it styles the
+  // code email (accent band, font, logo) via the email plugin AND supplies the
+  // display name the copy uses, so a deployment that themes its app themes its
+  // sign-in email with it. An explicit `brandName` still wins (see below).
+  const context = await loadBrandContext();
+
   // `sendCode` delivers the OTP through the email plugin's SHARED transport, which
   // the `email()` plugin primes during its `setup()` (awaited by `createApp`
   // below). Using the module-level `sendEmail` avoids a circular dependency on the
@@ -51,12 +74,21 @@ export async function startGateApp(config: AuthGateConfig): Promise<AuthGateApi>
       {
         to: [to],
         subject: opts.subject,
+        // Deliberately the conventional one-time-code layout: the prompt line,
+        // then the bare code ALONE on the next line, then the expiry. iOS, Gmail,
+        // Outlook, and Android all detect a code from this shape and offer to
+        // autofill it, and anything more decorative is what breaks that. The code
+        // stays visible TEXT in both MIME parts (the email plugin renders the
+        // HTML and plain-text alternatives from one React Email tree), never an
+        // image, so a client that scrapes the text part still finds it.
         body: [
           opts.message,
           "",
           `## ${code}`,
           "",
-          "It expires shortly. If you didn't request this, ignore this email.",
+          `This code expires in ${expiresIn(opts.codeTtlSeconds)}.`,
+          "",
+          "If you did not request this code, you can ignore this email.",
         ].join("\n"),
       },
       from,
@@ -65,7 +97,20 @@ export async function startGateApp(config: AuthGateConfig): Promise<AuthGateApi>
 
   // `createApp` namespaces each plugin's exports on the handle by manifest name;
   // `handle.authGate` is the in-process gate API the proxy drives.
-  const handle = await createApp({ plugins: [email(), authGate({ ...config, sendCode })] });
+  const handle = await createApp({
+    plugins: [
+      // Brand the code email from the resolved context, the same bridge every
+      // other dbx-tools email surface uses (accent + font inlined, logo only when
+      // it is a fetchable URL - a package-export path cannot load in an inbox).
+      email({ brand: emailBrandFromContext(context) }),
+      // `brandName` falls back to the resolved context's display name, so the
+      // email copy names the app rather than a generic placeholder. Spelled as an
+      // explicit `??` rather than a key before `...config`: commander sets
+      // `brandName` on the options object whether or not the flag was passed, so
+      // spreading it would clobber the context name with `undefined`.
+      authGate({ ...config, brandName: config.brandName ?? context.name, sendCode }),
+    ],
+  });
 
   // Fail fast: the gate needs SMTP to email codes. `getEmailRuntime()` resolves to
   // `mode: "file"` (outbox) or throws when no SMTP creds are configured - neither

package/src/cli.ts

@@ -1,14 +1,16 @@
 /**
  * `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:
+ * Wraps an app's start command with a public portr tunnel and an email-OTP
+ * access gate. Everything after `--` is the REAL app start command:
  *
- *   dbxt-tunnel --subject "Here's your OTP" --allow databricks.com -- bun src/server.ts
+ *   dbxt-tunnel --subject "Here's your OTP" --allow example.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).
+ *      `DATABRICKS_APP_PORT` set to it (so the app binds loopback-private). That
+ *      variable name is the Databricks Apps runtime contract; the gate itself is
+ *      platform-neutral and honours whatever port it finds there.
  *   2. Boot the tiny gate AppKit app (no server): inits `CacheManager` + the
  *      email transport, yields the in-process gate API.
  *   3. Start the gate PROXY on the ORIGINAL public port, forwarding to the app.
@@ -56,7 +58,7 @@ interface TunnelOpts {
 function program(): Command {
   return new Command()
     .name("dbx-tools-tunnel")
-    .description("Front a Databricks App with a public portr tunnel + email-OTP gate")
+    .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(
       "--allow <patterns>",
@@ -64,7 +66,10 @@ function program(): Command {
     )
     .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(
+      "--brand-name <name>",
+      "Display name in the code email copy (env AUTH_BRAND_NAME; defaults to the brand context 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)")

package/src/otp.ts

@@ -9,10 +9,13 @@
  * 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".
+ * email. Its signing key comes from `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
+ * allow-listed address, because the signing key only validates an ALREADY-issued
+ * session. Set it in any deployment running more than one instance, or sessions
+ * minted by one will not verify on another.
  *
  * @module
  */

package/src/plugin.ts

@@ -17,7 +17,7 @@
  */
 
 import { Plugin, toPlugin, type BasePluginConfig, type PluginManifest } from "@databricks/appkit";
-import { log, string } from "@dbx-tools/shared-core";
+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 { CodeStore, signSession, verifySession } from "./otp.ts";
@@ -29,11 +29,30 @@ const logger = log.logger("tunnel:auth");
 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 line for the code email. Env 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.
+   */
   subject?: string;
-  /** Product/brand name used in the email + login copy. Env AUTH_BRAND_NAME. */
+  /**
+   * Display name used in the code email copy. Env 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;
-  /** One-line message shown above the code in the email. Env AUTH_MESSAGE. */
+  /**
+   * Line shown immediately above the code in the email. Env 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). */
   sessionTtlSeconds?: number;
@@ -50,6 +69,13 @@ 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. */
@@ -64,33 +90,39 @@ export interface ResolvedAuthGateConfig {
 }
 
 const DEFAULTS = {
-  subject: "Your sign-in code",
-  brandName: "This app",
-  message: "Your one-time sign-in code is:",
+  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:",
   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 {
+    // 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: 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(
+    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,
+    sessionTtlSeconds: env.positiveInt(
       config.sessionTtlSeconds,
-      process.env.AUTH_SESSION_TTL,
+      "AUTH_SESSION_TTL",
       DEFAULTS.sessionTtlSeconds,
     ),
-    codeTtlSeconds: num(config.codeTtlSeconds, process.env.AUTH_CODE_TTL, DEFAULTS.codeTtlSeconds),
+    codeTtlSeconds: env.positiveInt(
+      config.codeTtlSeconds,
+      "AUTH_CODE_TTL",
+      DEFAULTS.codeTtlSeconds,
+    ),
     maxAttempts: config.maxAttempts ?? DEFAULTS.maxAttempts,
   };
 }
@@ -170,6 +202,7 @@ export class AuthGatePlugin extends Plugin<AuthGateConfig> {
           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 });

package/src/portr.ts

@@ -1,8 +1,9 @@
 /**
  * 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`.
+ * 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 `PUBLIC_DOMAIN` (`<subdomain>.<server>`)
  * + `PORTR_TOKEN` and points portr at the PUBLIC port (the proxy listens there).

package/src/proxy.ts

@@ -7,9 +7,11 @@
  *
  *   - **portr client** (same container, connects over LOOPBACK) - the public
  *     tunnel. This is what the gate protects.
- *   - **Databricks control plane / front door** (reaches 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 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.
@@ -126,10 +128,11 @@ export function startProxy({ publicPort, appPort, gate }: ProxyOptions): Promise
   };
 
   /**
-   * Present an OTP-authenticated caller to the app the SAME way the Databricks
-   * front door does: set `x-forwarded-user` / `x-forwarded-email` to the verified
-   * address (AppKit reads `x-forwarded-user` for the OBO user id). Any inbound
-   * copies are overwritten so a client can't spoof identity through the gate.
+   * 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.
    */
   const injectIdentity = (req: IncomingMessage, email: string): void => {
     req.headers["x-forwarded-user"] = email;
@@ -139,8 +142,8 @@ export function startProxy({ publicPort, appPort, gate }: ProxyOptions): Promise
   const server = createServer(async (req, res) => {
     const path = (req.url ?? "/").split("?")[0]!;
 
-    // Insecure/open mode (no gate) OR non-loopback traffic (the Databricks front
-    // door / control plane): forward ungated.
+    // 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;
@@ -198,7 +201,7 @@ export function startProxy({ publicPort, appPort, gate }: ProxyOptions): Promise
     const token = http.parseCookies(req.headers.cookie ?? null)[SESSION_COOKIE_NAME];
     const email = await gate.session(token);
     if (email) {
-      // Present the OTP user like the Databricks front door, and drop the gate
+      // 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);