@dbx-tools/tunnel 0.6.60 → 0.6.62

package/src/gate.ts

@@ -0,0 +1,249 @@
+/**
+ * The tunnel's in-app AUTH GATE - Express middleware + login routes the
+ * {@link AuthGatePlugin} registers on the app's OWN server via `this.context`.
+ *
+ * This replaces the old standalone reverse-proxy (`proxy.ts`): the app is now the
+ * process, so there is nothing to forward to. Instead the gate is middleware that
+ * either short-circuits (401, or answers the open login routes) or calls `next()`
+ * to let the app's real handlers run. It is the "stands in for AppKit auth" path:
+ * a portr caller proves an email via OTP, and on success the gate injects the
+ * identity headers AppKit reads, so a gated request runs like a front-door one.
+ *
+ * WHICH TRAFFIC IS GATED - the `Host` header, not the socket. portr's client
+ * forwards with Go's `httputil.NewSingleHostReverseProxy` and a `Director` that
+ * PRESERVES the original `Host`, so tunnel requests arrive with
+ * `Host: <subdomain>.<server>` (the public domain). A local process hitting the
+ * app directly sends `Host: 127.0.0.1:<port>` / `localhost`. So ONLY requests whose
+ * `Host` matches the configured public domain are gated; the platform front door
+ * and any other local client pass through untouched. There is no portr-injected
+ * identifying header and no TCP/source-IP signal to use instead (the client dials
+ * the target over plain loopback).
+ *
+ * @module
+ */
+
+import { http, json, log, token } from "@dbx-tools/shared-core";
+import { authRequestSchema, authVerifySchema, SESSION_COOKIE_NAME } from "@dbx-tools/shared-email";
+import type { Request, RequestHandler, Response } from "express";
+import { toHeaderPolicy } from "./headers.ts";
+import type { AuthGateApi } from "./plugin.ts";
+
+const logger = log.logger("tunnel:gate");
+
+/** Route prefix the login flow lives under (open, answered in-process). */
+export const AUTH_PREFIX = "/api/email/auth";
+
+/** Options for {@link mountGate}. */
+export interface GateOptions {
+  /** The in-process gate API (session/request/verify/status). */
+  gate: AuthGateApi;
+  /**
+   * The public `<subdomain>.<server>` that identifies portr traffic by `Host`.
+   * When absent, no request is ever classified as tunnel traffic and the gate is
+   * inert (everything passes through) - a tunnel with no public domain gates
+   * nothing.
+   */
+  publicDomain?: string;
+  /**
+   * Extra `x-` request headers tunnel traffic may forward (unioned with the
+   * built-in allow-list). Every other `x-` header is stripped from tunnel traffic.
+   */
+  forwardHeaders?: readonly string[];
+}
+
+/**
+ * True when the request's `Host` is the tunnel's public domain - i.e. it came in
+ * over portr. Case-insensitive; the optional `:port` is ignored. When no public
+ * domain is configured, nothing is tunnel traffic.
+ */
+export function isTunnelHost(req: Request, publicDomain: string | undefined): boolean {
+  if (!publicDomain) return false;
+  const host = (req.headers.host ?? "").toLowerCase().split(":")[0];
+  return host === publicDomain.toLowerCase().split(":")[0];
+}
+
+/** The session cookie for a verified email, as a Set-Cookie string. */
+function sessionCookie(value: string, maxAgeSeconds: number): string {
+  return [
+    `${SESSION_COOKIE_NAME}=${value}`,
+    "Path=/",
+    "HttpOnly",
+    "SameSite=Lax",
+    `Max-Age=${maxAgeSeconds}`,
+    // Real enforcement in production: the session cookie must be Secure so it is
+    // never sent over plaintext. Local dev (http) omits it so the cookie works.
+    process.env.NODE_ENV === "production" ? "Secure" : "",
+  ]
+    .filter(Boolean)
+    .join("; ");
+}
+
+/**
+ * Client IP for rate-limiting: the RIGHTMOST `x-forwarded-for` entry (the value
+ * the nearest trusted hop - portr - wrote), else the socket address. Reading the
+ * rightmost, not the leftmost, stops a caller minting a fresh rate-limit bucket by
+ * varying the header. Called before {@link stripHeaders}.
+ */
+function clientIp(req: Request): 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 the app's
+ * handlers run, so the app never sees `dbx_auth` (it is the gate's concern).
+ * Preserves other cookies; deletes the header when it becomes empty.
+ */
+function stripSessionCookie(req: Request): 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 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.
+ *
+ * What the gate CANNOT set is {@link token.ACCESS_TOKEN_HEADER}: an OTP session
+ * proves an email, not possession of a Databricks credential. Its absence is what
+ * `@dbx-tools/appkit`'s `identity: "auto"` detects, so a gated request runs as the
+ * app service principal instead of throwing.
+ */
+function injectIdentity(req: Request, email: string): void {
+  req.headers[token.USER_ID_HEADER] = email;
+  req.headers[token.USER_EMAIL_HEADER] = email;
+}
+
+function sendJson(res: Response, status: number, body: unknown, setCookie?: string): void {
+  if (setCookie) res.setHeader("set-cookie", setCookie);
+  res.status(status).json(body);
+}
+
+/** Read the raw request body as text (AppKit parses JSON, but the gate routes
+ * are mounted before that runs for tunnel traffic, so read defensively). */
+function readBody(req: Request): Promise<string> {
+  // AppKit's json body-parser may have already populated req.body; prefer it.
+  if (req.body !== undefined && req.body !== null) {
+    return Promise.resolve(typeof req.body === "string" ? req.body : JSON.stringify(req.body));
+  }
+  return new Promise((resolve) => {
+    let data = "";
+    req.on("data", (chunk) => (data += chunk));
+    req.on("end", () => resolve(data));
+    req.on("error", () => resolve(data));
+  });
+}
+
+/**
+ * Register the login routes and the gating middleware on the app's Express
+ * instance. Called from {@link AuthGatePlugin} with the router AppKit hands
+ * `injectRoutes`, plus `this.context.addMiddleware` for the global gate.
+ *
+ * `addRoute`/`addMiddleware` are used (via the passed callbacks) because the login
+ * routes live at an ABSOLUTE path (`/api/email/auth/*`, the client's contract),
+ * not under the plugin's `/api/authGate` base.
+ */
+export function mountGate(
+  opts: GateOptions,
+  addRoute: (method: "get" | "post", path: string, handler: RequestHandler) => void,
+  addMiddleware: (path: string, handler: RequestHandler) => void,
+): void {
+  const { gate, publicDomain, forwardHeaders } = opts;
+  const headerPolicy = toHeaderPolicy(forwardHeaders);
+  logger.debug("gate mounted", { publicDomain, forward: headerPolicy.patterns });
+
+  const applyHeaderPolicy = (req: Request): void => {
+    const removed = headerPolicy.apply(req.headers as Record<string, unknown>);
+    if (removed.length) logger.debug("stripped inbound headers", { removed });
+  };
+
+  // --- Login routes (open on tunnel traffic; answered in-process) ---
+
+  const statusHandler = (async (req, res) => {
+    // A local or front-door caller is never gated, so the honest answer is that
+    // the gate does not apply - not the session state of a cookie it would never
+    // check. Without this, a browser on `localhost` renders the OTP login screen
+    // for a request that would have passed through untouched.
+    if (!isTunnelHost(req, publicDomain)) {
+      sendJson(res, 200, { authenticated: false, enabled: false });
+      return;
+    }
+    const cookie = http.parseCookies(req.headers.cookie ?? null)[SESSION_COOKIE_NAME];
+    sendJson(res, 200, await gate.status(cookie));
+  }) as RequestHandler;
+
+  const requestHandler = (async (req, res) => {
+    const parsed = authRequestSchema.safeParse(json.parseRecord(await readBody(req)));
+    if (!parsed.success) return sendJson(res, 200, { ok: true }); // anti-enumeration
+    sendJson(res, 200, await gate.request(parsed.data.email, clientIp(req)));
+  }) as RequestHandler;
+
+  const verifyHandler = (async (req, res) => {
+    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;
+    sendJson(
+      res,
+      200,
+      { ok: result.ok, ...(result.retryAfter ? { retryAfter: result.retryAfter } : {}) },
+      cookie,
+    );
+  }) as RequestHandler;
+
+  const logoutHandler = ((_req, res) => {
+    sendJson(res, 200, { ok: true }, `${SESSION_COOKIE_NAME}=; Path=/; HttpOnly; Max-Age=0`);
+  }) as RequestHandler;
+
+  addRoute("get", `${AUTH_PREFIX}/status`, statusHandler);
+  addRoute("post", `${AUTH_PREFIX}/request`, requestHandler);
+  addRoute("post", `${AUTH_PREFIX}/verify`, verifyHandler);
+  addRoute("post", `${AUTH_PREFIX}/logout`, logoutHandler);
+
+  // --- The gate middleware (runs before static + the app's /api handlers) ---
+
+  const gateMiddleware = (async (req, res, next) => {
+    // Not tunnel traffic (platform front door, or any other local caller): the
+    // request is already authenticated (or is not ours to gate). Pass through.
+    if (!isTunnelHost(req, publicDomain)) return next();
+
+    const path = (req.url ?? "/").split("?")[0] ?? "/";
+
+    // The login flow is open so the browser can render <AuthGate> and sign in.
+    if (path.startsWith(AUTH_PREFIX)) return next();
+
+    // Anti-spoof: only the gate may assert identity on tunnel traffic.
+    applyHeaderPolicy(req);
+
+    // Static (non-API) loads freely so the SPA can render; drop the gate cookie.
+    if (!path.startsWith("/api/")) {
+      stripSessionCookie(req);
+      return next();
+    }
+
+    // Every other /api/* needs a valid OTP session.
+    const cookie = http.parseCookies(req.headers.cookie ?? null)[SESSION_COOKIE_NAME];
+    const email = await gate.session(cookie);
+    if (!email) {
+      sendJson(res, 401, { error: "authentication required", loginPath: AUTH_PREFIX });
+      return;
+    }
+    injectIdentity(req, email);
+    stripSessionCookie(req);
+    next();
+  }) as RequestHandler;
+
+  addMiddleware("/", gateMiddleware);
+}

package/src/interceptor.ts

@@ -16,16 +16,16 @@
  *   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.
+ * The email-OTP GATE is a separate concern: it is the `authGate` AppKit plugin,
+ * which registers the login routes + a gating middleware on the app's own server.
+ * Register it in the app's `plugins` for gated traffic. This interceptor is only
+ * the portr half - "update the host, bind portr" - the smallest useful unit.
  *
  * @module
  */
 
 import type { Interceptor, InterceptorContext } from "@dbx-tools/appkit";
-import { log } from "@dbx-tools/shared-core";
+import { log, object } from "@dbx-tools/shared-core";
 import { installPortr, resolvePortrConfig, startPortr, writePortrConfig } from "./portr.ts";
 
 const logger = log.logger("tunnel:interceptor");
@@ -46,7 +46,7 @@ export interface TunnelInterceptorOptions {
 
 /** 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);
+  return port ?? object.toNumber(process.env.DATABRICKS_APP_PORT) ?? 8000;
 }
 
 /**

package/src/plugin.ts

@@ -19,21 +19,68 @@
 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 type { RequestHandler } from "express";
 import { looksLikeEmail, matchesAllowlist } from "./allowlist.ts";
 import {
   ALLOW_ENV,
   BRAND_NAME_ENV,
   CODE_TTL_ENV,
+  FORWARD_HEADERS_ENV,
+  INSECURE_ENV,
   MESSAGE_ENV,
+  PUBLIC_DOMAIN_ENV,
   SESSION_TTL_ENV,
   SUBJECT_ENV,
 } from "./env.ts";
+import { mountGate, type GateOptions } from "./gate.ts";
 import { CodeStore, signSession, verifySession } from "./otp.ts";
 import { RateLimiter } from "./rate-limit.ts";
+import { ensureEmailAvailable, sendCode as defaultSendCode } from "./send-code.ts";
 import { KEY_TTL_SECONDS, resolveSessionCutoff, signingKey } from "./signing-key.ts";
 
 const logger = log.logger("tunnel:auth");
 
+interface GateServerApplication {
+  get(path: string, handler: RequestHandler): unknown;
+  post(path: string, handler: RequestHandler): unknown;
+  use(path: string, handler: RequestHandler): unknown;
+}
+
+interface GateMountContext {
+  addRoute(method: string, path: string, handler: RequestHandler): void;
+  addMiddleware(path: string, handler: RequestHandler): void;
+  getPlugins(): ReadonlyMap<string, unknown>;
+}
+
+function serverApplication(context: GateMountContext): GateServerApplication | undefined {
+  const server = context.getPlugins().get("server") as
+    { serverApplication?: Partial<GateServerApplication> } | undefined;
+  const application = server?.serverApplication;
+  return application &&
+    typeof application.get === "function" &&
+    typeof application.post === "function" &&
+    typeof application.use === "function"
+    ? (application as GateServerApplication)
+    : undefined;
+}
+
+export function mountGateOnContext(context: GateMountContext, options: GateOptions): void {
+  const application = serverApplication(context);
+  if (application) {
+    mountGate(
+      options,
+      (method, path, handler) => application[method](path, handler),
+      (path, handler) => application.use(path, handler),
+    );
+    return;
+  }
+  mountGate(
+    options,
+    (method, path, handler) => context.addRoute(method, path, handler),
+    (path, handler) => context.addMiddleware(path, handler),
+  );
+}
+
 /** 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. */
@@ -50,7 +97,7 @@ export interface AuthGateConfig extends BasePluginConfig {
    * 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`.
+   * autofill reads. See `codeEmailSubject` in `./code-email.ts`.
    */
   subject?: string;
   /**
@@ -89,8 +136,31 @@ export interface AuthGateConfig extends BasePluginConfig {
    * means no cutoff.
    */
   sessionCutoff?: string | number | Date;
-  /** Deliver a code to an address. Wired by the app to the email plugin. */
+  /**
+   * Deliver a code to an address. Defaults to sending through the host app's
+   * shared `@dbx-tools/email` transport (see `./send-code`); override to wire a
+   * different delivery path.
+   */
   sendCode?: (email: string, code: string, opts: SendCodeOptions) => Promise<void>;
+  /**
+   * The public `<subdomain>.<server>` that identifies portr traffic by its `Host`
+   * header. Only requests whose `Host` matches this are gated; everything else
+   * (the platform front door, other local callers) passes through. Env
+   * `TUNNEL_PUBLIC_DOMAIN`. When absent, the gate is inert (nothing is tunnel
+   * traffic).
+   */
+  publicDomain?: string;
+  /**
+   * Extra `x-` request headers tunnel traffic may forward (literal / glob /
+   * `/regex/`), unioned with the built-in allow-list. Env `TUNNEL_FORWARD_HEADERS`.
+   */
+  forwardHeaders?: string | string[];
+  /**
+   * Run OPEN with no gate (env `TUNNEL_INSECURE=true`). The login routes and gate
+   * middleware are not mounted, and the SMTP fail-fast is skipped. Use only when
+   * the tunnel is deliberately public.
+   */
+  insecure?: boolean;
 }
 
 /** Branding/messaging passed to {@link AuthGateConfig.sendCode}. */
@@ -118,6 +188,12 @@ export interface ResolvedAuthGateConfig {
   maxAttempts: number;
   /** Force-clear cutoff in epoch ms; `0` when unset. */
   sessionCutoffMs: number;
+  /** Public domain that identifies portr traffic by `Host`; `undefined` = inert. */
+  publicDomain?: string;
+  /** Extra `x-` headers tunnel traffic may forward (unioned with the defaults). */
+  forwardHeaders: string[];
+  /** Run OPEN with no gate. */
+  insecure: boolean;
 }
 
 const DEFAULTS = {
@@ -125,8 +201,7 @@ const DEFAULTS = {
   // 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
+  // `branding/brand.yaml` overrides it by passing `brandName`; the shared default
   // is the fallback when nothing is configured.
   brandName: brand.defaultBrandContext.name,
   message: "Your verification code is:",
@@ -155,10 +230,16 @@ export function resolveAuthGateConfig(config: AuthGateConfig): ResolvedAuthGateC
     codeTtlSeconds: env.positiveInt(config.codeTtlSeconds, CODE_TTL_ENV, DEFAULTS.codeTtlSeconds),
     maxAttempts: config.maxAttempts ?? DEFAULTS.maxAttempts,
     sessionCutoffMs: resolveSessionCutoff(config.sessionCutoff),
+    publicDomain: env.string(config.publicDomain, PUBLIC_DOMAIN_ENV) ?? undefined,
+    forwardHeaders: [
+      ...string.parseList(config.forwardHeaders),
+      ...string.parseList(env.text(FORWARD_HEADERS_ENV)),
+    ],
+    insecure: env.boolean(config.insecure, INSECURE_ENV) ?? false,
   };
 }
 
-/** The handlers the proxy calls in-process (returned by {@link AuthGatePlugin.exports}). */
+/** The handlers the gate middleware 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 }>;
@@ -176,7 +257,13 @@ export interface AuthGateApi {
   status(token: string | undefined): Promise<AuthStatus>;
 }
 
-/** AppKit plugin owning the email-OTP gate's logic (no HTTP routes; proxy-driven). */
+/**
+ * AppKit plugin owning the email-OTP gate. On `setup()` it registers the login
+ * routes (`/api/email/auth/*`) and a gating middleware on the app's OWN Express
+ * server via `this.context`, so a public portr caller must prove an email before
+ * reaching the app's `/api/*` - see `./gate`. Front-door (platform) traffic and
+ * other local callers pass through untouched (the gate keys on the `Host` header).
+ */
 export class AuthGatePlugin extends Plugin<AuthGateConfig> {
   static manifest = {
     name: "authGate",
@@ -200,13 +287,56 @@ export class AuthGatePlugin extends Plugin<AuthGateConfig> {
     // 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);
+
+    if (this.resolved.insecure) {
+      logger.warn("insecure mode - the tunnel runs OPEN with no email-OTP gate");
+    } else {
+      // `server()` is deferred, so it does not exist during this plugin's setup.
+      // At `setup:complete` the Express app exists but has not injected plugin
+      // routes or static handling yet, which is the one point the gate can mount
+      // ahead of every protected route.
+      this.context?.onLifecycle("setup:complete", async () => {
+        this.mountGateRoutes();
+        // Fail fast once the sibling email plugin has primed its transport: a
+        // gate that cannot email a code lets nobody in.
+        await ensureEmailAvailable();
+      });
+    }
+
     logger.info("ready", {
       patterns: this.resolved.allow.length,
       sessionTtlSeconds: this.resolved.sessionTtlSeconds,
+      publicDomain: this.resolved.publicDomain ?? null,
+      insecure: this.resolved.insecure,
       ...object.optional("sessionCutoff", cutoffMs > 0 ? new Date(cutoffMs).toISOString() : null),
     });
   }
 
+  /**
+   * Register the login routes (`/api/email/auth/*`) and the gating middleware on
+   * the app's OWN Express server. At `setup:complete`, the deferred server plugin
+   * has constructed its Express app but has not injected plugin routes or static
+   * handling, so direct registration puts the gate first. The context's buffered
+   * route API remains a fallback for compatible non-standard server plugins.
+   */
+  private mountGateRoutes(): void {
+    const context = this.context;
+    if (!context) {
+      logger.warn("no plugin context - the OTP gate cannot mount its routes");
+      return;
+    }
+    mountGateOnContext(context, {
+      gate: this.exports(),
+      publicDomain: this.resolved.publicDomain,
+      forwardHeaders: this.resolved.forwardHeaders,
+    });
+  }
+
+  /** The code sender: the configured `sendCode`, else the shared-transport default. */
+  private get sendCode(): NonNullable<AuthGateConfig["sendCode"]> {
+    return this.config.sendCode ?? defaultSendCode;
+  }
+
   override exports(): AuthGateApi {
     return {
       sessionTtlSeconds: this.resolved.sessionTtlSeconds,
@@ -234,7 +364,7 @@ export class AuthGatePlugin extends Plugin<AuthGateConfig> {
     if (looksLikeEmail(address) && matchesAllowlist(address, this.resolved.allow)) {
       const code = await this.codes.issue(address);
       try {
-        await this.config.sendCode?.(address, code, {
+        await this.sendCode(address, code, {
           subject: this.resolved.subject,
           brandName: this.resolved.brandName,
           message: this.resolved.message,

package/src/send-code.ts

@@ -0,0 +1,112 @@
+/**
+ * The default `sendCode` for the {@link AuthGatePlugin}: deliver the OTP through
+ * the host app's ALREADY-PRIMED `@dbx-tools/email` transport, as the system
+ * sender (a verification code is machine-generated and unanswerable, so it must
+ * not arrive from a person's address inviting a reply).
+ *
+ * `@dbx-tools/email` is an OPTIONAL dependency of the tunnel - a tunnel used
+ * without the gate needs no mail. So it is imported LAZILY here; a missing module
+ * surfaces only when a gate actually tries to send a code, and
+ * {@link ensureEmailAvailable} turns that into a clear fail-fast at boot.
+ *
+ * @module
+ */
+
+import { log } from "@dbx-tools/shared-core";
+import {
+  codeEmailHtmlBody,
+  codeEmailPreview,
+  codeEmailSubject,
+  codeEmailTextBody,
+} from "./code-email.ts";
+import type { AuthGateConfig, SendCodeOptions } from "./plugin.ts";
+
+const logger = log.logger("tunnel:send-code");
+
+/** The slice of `@dbx-tools/email` the gate uses, resolved lazily. */
+interface EmailModule {
+  sender: { resolveSystemSenderAddress: (config: unknown) => string };
+  transport: {
+    getEmailRuntime: () => { config: { mode: string } };
+    sendEmail: (
+      message: { to: string[]; subject: string; body: string },
+      from: string,
+      onBehalfOf: undefined,
+      extra: { text: string; preview: string },
+    ) => Promise<void>;
+  };
+}
+
+let cached: EmailModule | undefined;
+
+/**
+ * Import `@dbx-tools/email` lazily. Throws a clear, actionable error when the
+ * optional dependency is absent - the caller (a gate that is NOT insecure) treats
+ * that as fatal, since a gate that cannot email a code lets nobody in.
+ */
+async function loadEmail(): Promise<EmailModule> {
+  if (cached) return cached;
+  try {
+    const mod = (await import("@dbx-tools/email")) as unknown as EmailModule;
+    cached = mod;
+    return mod;
+  } catch (cause) {
+    throw new Error(
+      "the OTP gate needs @dbx-tools/email to send codes, but it is not installed. " +
+        "Add @dbx-tools/email to the app, or run the tunnel with --insecure / TUNNEL_INSECURE=true.",
+      { cause },
+    );
+  }
+}
+
+/**
+ * Fail fast when the gate cannot deliver codes: the optional email module must be
+ * importable AND configured for SMTP (real delivery). `mode: "file"` (outbox) or a
+ * throwing runtime means no code reaches a real inbox, so a gate on that config
+ * would silently admit nobody. Called from the plugin's `setup:complete` unless
+ * insecure.
+ */
+export async function ensureEmailAvailable(): Promise<void> {
+  const { transport } = await loadEmail();
+  if (transport.getEmailRuntime().config.mode !== "smtp") {
+    throw new Error(
+      "email is not configured for SMTP delivery - the OTP gate cannot send codes. " +
+        "Set SMTP_HOST/SMTP_USER/SMTP_PASSWORD, or pass --insecure / TUNNEL_INSECURE=true.",
+    );
+  }
+}
+
+/**
+ * The default code sender: render the OTP email (code in the subject + preheader
+ * for mobile autofill; see `codeEmailSubject`) and send it through the shared
+ * transport as the system sender.
+ */
+export const sendCode: NonNullable<AuthGateConfig["sendCode"]> = async (
+  to: string,
+  code: string,
+  opts: SendCodeOptions,
+): Promise<void> => {
+  const { sender, transport } = await loadEmail();
+  const from = sender.resolveSystemSenderAddress(transport.getEmailRuntime().config);
+  await sendEmailWith(transport, to, code, opts, from);
+};
+
+function sendEmailWith(
+  transport: EmailModule["transport"],
+  to: string,
+  code: string,
+  opts: SendCodeOptions,
+  from: string,
+): Promise<void> {
+  logger.debug("sending code email", { to });
+  return transport.sendEmail(
+    {
+      to: [to],
+      subject: codeEmailSubject(code, opts.subject),
+      body: codeEmailHtmlBody(code, opts),
+    },
+    from,
+    undefined,
+    { text: codeEmailTextBody(code, opts), preview: codeEmailPreview(code, opts) },
+  );
+}