@dbx-tools/tunnel 0.6.60 → 0.6.61

package/README.md

@@ -18,8 +18,8 @@ so the app and portr live and die as one (concurrently-style - signals pass
 through, either death tears the pair down). The app is the process; the tunnel
 rides along inside it. Access is granted per email address against an allow-list,
 verified by a code sent over [`@dbx-tools/email`](../../node/email); the gate
-itself is the `authGate` AppKit plugin plus the `startProxy` reverse-proxy, both
-exported here for an app that wants to gate the tunnelled traffic.
+itself is the `authGate` AppKit plugin, which registers the login routes and a
+gating middleware on the app's OWN Express server (no separate proxy process).
 
 **Key features:**
 
@@ -83,18 +83,22 @@ exported here for an app that wants to gate the tunnelled traffic.
   `x-forwarded-access-token`, which would otherwise let anyone drive the app's
   workspace calls with a pasted token. Add an app's own headers with
   `TUNNEL_FORWARD_HEADERS`.
-- Platform traffic passes through UNGATED. The gate distinguishes the portr
-  client (a loopback source address, same container) from the hosting platform's
-  front door (a non-loopback container-network address), so health checks and the
-  workspace UI keep working while public tunnel traffic is gated.
+- Only PORTR traffic is gated. The gate identifies tunnel requests by their
+  `Host` header (`TUNNEL_PUBLIC_DOMAIN`), which portr's client preserves from the
+  public visitor. Platform front-door traffic and any other local caller carry a
+  different `Host` and pass through UNGATED, so health checks and the workspace UI
+  keep working. (There is no portr-injected identifying header and no source-IP
+  signal - the client dials the app over plain loopback - so `Host` is the signal.)
 - SPA-aware gating: static assets and the login routes stay open so the browser
   can load the client and render the login form; every other `/api/*` needs a
-  valid session cookie or gets `401`. WebSocket upgrades are gated the same way.
+  valid session cookie or gets `401`. A WebSocket handshake is an ordinary `GET`
+  and runs through the same gate.
 - Supervised teardown - `tunnelInterceptor` binds portr through the `createApp`
   interceptor context, so the app and the tunnel are tied together: if either
   exits, `bindProcess` brings the whole set down and passes signals through.
 - The gate fails fast when email is not configured for SMTP, because a gate that
-  cannot send codes locks everyone out (see `startGateApp` in the `app` module).
+  cannot send codes locks everyone out. `@dbx-tools/email` is an OPTIONAL peer
+  dependency, imported lazily; the app that mounts the gate provides it.
 
 ## Why This Over An Ad-Hoc Tunnel
 
@@ -109,24 +113,35 @@ supervise and no wrapper command to thread flags through.
 
 ```ts
 import { createApp } from "@dbx-tools/appkit";
+import { email } from "@dbx-tools/email";
 import { server } from "@databricks/appkit";
-import { interceptor } from "@dbx-tools/tunnel";
+import { interceptor, plugin } from "@dbx-tools/tunnel";
 
 const { tunnelInterceptor } = interceptor;
+const { authGate } = plugin;
 
 await createApp.createApp({
-  plugins: [server({ host, staticPath })],
+  plugins: [
+    server({ host, staticPath }),
+    // Delivers the OTP codes; the gate reuses this shared transport.
+    email(),
+    // The OTP gate: login routes + a gating middleware on THIS server. Gates only
+    // portr traffic (Host === TUNNEL_PUBLIC_DOMAIN); the platform front door passes
+    // through. Inert when no tunnel domain is configured.
+    authGate({}),
+  ],
   // Applies DATABRICKS_HOST, launches portr at the app's public port, and binds
   // it to the app. No-op when no PORTR_TOKEN / TUNNEL_PUBLIC_DOMAIN is set.
   interceptor: tunnelInterceptor(),
 });
 ```
 
-`tunnelInterceptor(opts)` takes optional `publicDomain` / `subdomain` / `port`;
-each falls back to env (and `port` to the `DATABRICKS_APP_PORT` contract), so a
-deployment usually passes nothing and configures through the environment. The
-OTP gate is a separate concern - see [Use The Gate](#use-the-gate) to mount
-`authGate` + `startProxy` for gated traffic.
+Two pieces, one process: `tunnelInterceptor()` runs portr (a child, bound to the
+app), and `authGate()` is the in-app gate. `tunnelInterceptor(opts)` takes optional
+`publicDomain` / `subdomain` / `port`, each falling back to env (and `port` to the
+`DATABRICKS_APP_PORT` contract); `authGate` reads `TUNNEL_AUTH_ALLOW` /
+`TUNNEL_PUBLIC_DOMAIN` from the environment, so a deployment usually passes nothing.
+See [Use The Gate](#use-the-gate) for the gate on its own.
 
 ## Options
 
@@ -274,7 +289,7 @@ configuration:
 | `x-requested-with` | the conventional AJAX marker                        |
 
 Add an app's own headers with `TUNNEL_FORWARD_HEADERS` (or `forwardHeaders` on
-`startProxy`). Each entry is a literal name, a shell-style glob, or a `/regex/` -
+`authGate`). Each entry is a literal name, a shell-style glob, or a `/regex/` -
 the same three shapes the email allow-list takes - and the configured list is
 UNIONED with the defaults, so extending it never silently breaks the built-in
 surfaces:
@@ -299,63 +314,52 @@ The identity headers are AppKit's OBO contract; the rest are the
 [`X-Forwarded-*` set Databricks Apps documents passing to an
 app](https://docs.databricks.com/aws/en/dev-tools/databricks-apps/http-headers),
 plus the conventional `x-forwarded-proto`/`-port`/`x-real-ip` a library may read
-anyway. Dropping the transport headers costs nothing: the proxy re-adds them from
-the real socket after the policy runs, so the app sees the honest values instead
-of the caller's claim. Rate limiting reads the client IP before stripping, and
-takes the **rightmost** `x-forwarded-for` entry - the only one a proxy appended
-rather than a client supplied.
+anyway. Dropping the transport headers costs nothing: `xfwd` re-adds them from the
+real socket after the policy runs, so the app sees the honest values instead of the
+caller's claim. Rate limiting reads the client IP before stripping, and takes the
+**rightmost** `x-forwarded-for` entry - the only one portr appended rather than a
+client supplied.
 
 ## Use The Gate
 
-The gate is an AppKit plugin, so an app that wants the OTP flow can mount it
-directly - with or without the portr tunnel. It registers no routes - it exposes
-handlers the caller invokes (drive them from the `startProxy` reverse-proxy, or
-your own server) - and it takes a `sendCode` callback because delivering mail is
-the one thing it cannot resolve on its own:
+`authGate()` is the gate. Register it in your app's `createApp` plugins and it
+mounts the `/api/email/auth/*` login routes plus a gating middleware on your app's
+own server (via AppKit's `this.context`). By default it delivers codes through the
+app's shared `@dbx-tools/email` transport - so the minimal wiring is just an
+`allow` list (or `TUNNEL_AUTH_ALLOW`):
 
 ```ts
 import { createApp } from "@dbx-tools/appkit";
+import { email } from "@dbx-tools/email";
 import { authGate } from "@dbx-tools/tunnel";
-import { brand, email, sender, transport } from "@dbx-tools/email";
 
-const handle = await createApp({
+await createApp.createApp({
   plugins: [
-    email({ brand: brand.defaultEmailBrand }),
-    authGate({
-      allow: ["example.com"],
-      sendCode: async (to, code, opts) => {
-        const runtime = transport.getEmailRuntime();
-        await transport.sendEmail(
-          {
-            to: [to],
-            subject: opts.subject,
-            body: `${opts.message}\n\n## ${code}`,
-          },
-          // The app's configured sender; a code email has no on-behalf-of user.
-          sender.resolveSenderAddress(runtime.config, undefined),
-        );
-      },
-    }),
+    server({ host, staticPath }),
+    email(), // the gate reuses this transport to send codes
+    authGate({ allow: ["example.com"] }),
   ],
 });
-
-// The gate exposes handlers rather than routes - call them from your own server.
-const status = await handle.authGate.status(sessionCookieValue);
 ```
 
-`sendCode` is the one thing the plugin cannot resolve on its own. The `app`
-module's `startGateApp()` wires this same callback and derives the email styling
-from the brand context, so mounting the plugin directly is the only case that
-needs it by hand.
+Override `sendCode` only to deliver through something other than the shared
+transport; the default builds the OTP email (code in the subject + preheader for
+mobile autofill) and sends it as the system sender. `@dbx-tools/email` is an
+OPTIONAL peer dependency - a tunnel without the gate needs no mail - so the app
+that mounts `authGate` must include it (or run `TUNNEL_INSECURE=true` to skip the
+gate); a missing transport fails fast at boot.
 
 ## Modules
 
 - `interceptor` - `tunnelInterceptor()`, the `createApp` interceptor that applies
   `DATABRICKS_HOST`, launches portr, and binds it to the app.
-- `plugin` - `authGate()`, its config/env resolution, and the `AuthGateApi`
-  handlers the proxy calls in-process.
-- `proxy` - the public-port reverse proxy: loopback-vs-platform classification,
-  open login routes, session enforcement, and WebSocket forwarding.
+- `plugin` - `authGate()`, its config/env resolution, the `AuthGateApi` handlers,
+  and the `setup()` that mounts the gate on the app's server.
+- `gate` - the login routes + gating middleware (`mountGate`, `isTunnelHost`):
+  `Host`-based tunnel classification, session enforcement, and identity injection.
+- `send-code` - the default OTP delivery through the shared email transport
+  (lazily imported) and the SMTP fail-fast.
+- `code-email` - pure builders for the code email's subject/preheader/bodies.
 - `otp` - the `CacheManager`-backed code store and the session JWT.
 - `signingKey` - the cache-persisted HS256 session key (30-day TTL, get/generate/
   re-read convergence) and the `TUNNEL_AUTH_SESSION_CUTOFF` force-clear cutoff.
@@ -366,7 +370,6 @@ needs it by hand.
   distributed).
 - `portr` - portr install, config rendering, and child launch.
 - `env` - the environment-variable names, each with its deprecated aliases.
-- `app` - boots the minimal gate AppKit app and returns the `AuthGateApi`.
 
 Browser-safe login wire schemas (the request/verify payloads and the session
 cookie name) live in [`@dbx-tools/shared-email`](../../shared/email); the React

package/index.ts

@@ -3,17 +3,21 @@
 // Hand edits are overwritten on the next watch; this file is read-only.
 
 export * as allowlist from "./src/allowlist.ts";
-export * as app from "./src/app.ts";
+export * as codeEmail from "./src/code-email.ts";
 export * as env from "./src/env.ts";
+export * as gate from "./src/gate.ts";
 export * as headers from "./src/headers.ts";
 export * as interceptor from "./src/interceptor.ts";
 export * as otp from "./src/otp.ts";
 export * as plugin from "./src/plugin.ts";
 export * as portr from "./src/portr.ts";
-export * as proxy from "./src/proxy.ts";
 export * as rateLimit from "./src/rate-limit.ts";
+export * as sendCode from "./src/send-code.ts";
 export * as signingKey from "./src/signing-key.ts";
+export type { CodeCopy } from "./src/code-email.ts";
 export { ALLOW_ENV, SUBJECT_ENV, BRAND_NAME_ENV, MESSAGE_ENV, SESSION_TTL_ENV, CODE_TTL_ENV, JWT_SECRET_ENV, SESSION_CUTOFF_ENV, PUBLIC_DOMAIN_ENV, INSECURE_ENV, FORWARD_HEADERS_ENV } from "./src/env.ts";
+export { AUTH_PREFIX } from "./src/gate.ts";
+export type { GateOptions } from "./src/gate.ts";
 export { PROTECTED_HEADERS, DEFAULT_FORWARD_HEADERS } from "./src/headers.ts";
 export type { HeaderPolicy } from "./src/headers.ts";
 export type { TunnelInterceptorOptions } from "./src/interceptor.ts";
@@ -22,7 +26,6 @@ export type { VerifyOutcome } from "./src/otp.ts";
 export { AuthGatePlugin, authGate } from "./src/plugin.ts";
 export type { AuthGateConfig, SendCodeOptions, ResolvedAuthGateConfig, AuthGateApi } from "./src/plugin.ts";
 export type { PortrConfig } from "./src/portr.ts";
-export type { ProxyOptions } from "./src/proxy.ts";
 export { RateLimiter } from "./src/rate-limit.ts";
 export { KEY_TTL_SECONDS } from "./src/signing-key.ts";
 export type { SigningKey } from "./src/signing-key.ts";

package/lib/index.d.ts

@@ -1,15 +1,19 @@
 export * as allowlist from "./src/allowlist.ts";
-export * as app from "./src/app.ts";
+export * as codeEmail from "./src/code-email.ts";
 export * as env from "./src/env.ts";
+export * as gate from "./src/gate.ts";
 export * as headers from "./src/headers.ts";
 export * as interceptor from "./src/interceptor.ts";
 export * as otp from "./src/otp.ts";
 export * as plugin from "./src/plugin.ts";
 export * as portr from "./src/portr.ts";
-export * as proxy from "./src/proxy.ts";
 export * as rateLimit from "./src/rate-limit.ts";
+export * as sendCode from "./src/send-code.ts";
 export * as signingKey from "./src/signing-key.ts";
+export type { CodeCopy } from "./src/code-email.ts";
 export { ALLOW_ENV, SUBJECT_ENV, BRAND_NAME_ENV, MESSAGE_ENV, SESSION_TTL_ENV, CODE_TTL_ENV, JWT_SECRET_ENV, SESSION_CUTOFF_ENV, PUBLIC_DOMAIN_ENV, INSECURE_ENV, FORWARD_HEADERS_ENV } from "./src/env.ts";
+export { AUTH_PREFIX } from "./src/gate.ts";
+export type { GateOptions } from "./src/gate.ts";
 export { PROTECTED_HEADERS, DEFAULT_FORWARD_HEADERS } from "./src/headers.ts";
 export type { HeaderPolicy } from "./src/headers.ts";
 export type { TunnelInterceptorOptions } from "./src/interceptor.ts";
@@ -18,7 +22,6 @@ export type { VerifyOutcome } from "./src/otp.ts";
 export { AuthGatePlugin, authGate } from "./src/plugin.ts";
 export type { AuthGateConfig, SendCodeOptions, ResolvedAuthGateConfig, AuthGateApi } from "./src/plugin.ts";
 export type { PortrConfig } from "./src/portr.ts";
-export type { ProxyOptions } from "./src/proxy.ts";
 export { RateLimiter } from "./src/rate-limit.ts";
 export { KEY_TTL_SECONDS } from "./src/signing-key.ts";
 export type { SigningKey } from "./src/signing-key.ts";

package/lib/index.js

@@ -2,20 +2,22 @@
 // Regenerated from the exporting modules in ./src.
 // Hand edits are overwritten on the next watch; this file is read-only.
 export * as allowlist from "./src/allowlist.js";
-export * as app from "./src/app.js";
+export * as codeEmail from "./src/code-email.js";
 export * as env from "./src/env.js";
+export * as gate from "./src/gate.js";
 export * as headers from "./src/headers.js";
 export * as interceptor from "./src/interceptor.js";
 export * as otp from "./src/otp.js";
 export * as plugin from "./src/plugin.js";
 export * as portr from "./src/portr.js";
-export * as proxy from "./src/proxy.js";
 export * as rateLimit from "./src/rate-limit.js";
+export * as sendCode from "./src/send-code.js";
 export * as signingKey from "./src/signing-key.js";
 export { ALLOW_ENV, SUBJECT_ENV, BRAND_NAME_ENV, MESSAGE_ENV, SESSION_TTL_ENV, CODE_TTL_ENV, JWT_SECRET_ENV, SESSION_CUTOFF_ENV, PUBLIC_DOMAIN_ENV, INSECURE_ENV, FORWARD_HEADERS_ENV } from "./src/env.js";
+export { AUTH_PREFIX } from "./src/gate.js";
 export { PROTECTED_HEADERS, DEFAULT_FORWARD_HEADERS } from "./src/headers.js";
 export { CodeStore } from "./src/otp.js";
 export { AuthGatePlugin, authGate } from "./src/plugin.js";
 export { RateLimiter } from "./src/rate-limit.js";
 export { KEY_TTL_SECONDS } from "./src/signing-key.js";
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSwyQ0FBMkM7QUFDM0MsbURBQW1EO0FBQ25ELHdFQUF3RTtBQUV4RSxPQUFPLEtBQUssU0FBUyxNQUFNLG9CQUFvQixDQUFDO0FBQ2hELE9BQU8sS0FBSyxHQUFHLE1BQU0sY0FBYyxDQUFDO0FBQ3BDLE9BQU8sS0FBSyxHQUFHLE1BQU0sY0FBYyxDQUFDO0FBQ3BDLE9BQU8sS0FBSyxPQUFPLE1BQU0sa0JBQWtCLENBQUM7QUFDNUMsT0FBTyxLQUFLLFdBQVcsTUFBTSxzQkFBc0IsQ0FBQztBQUNwRCxPQUFPLEtBQUssR0FBRyxNQUFNLGNBQWMsQ0FBQztBQUNwQyxPQUFPLEtBQUssTUFBTSxNQUFNLGlCQUFpQixDQUFDO0FBQzFDLE9BQU8sS0FBSyxLQUFLLE1BQU0sZ0JBQWdCLENBQUM7QUFDeEMsT0FBTyxLQUFLLEtBQUssTUFBTSxnQkFBZ0IsQ0FBQztBQUN4QyxPQUFPLEtBQUssU0FBUyxNQUFNLHFCQUFxQixDQUFDO0FBQ2pELE9BQU8sS0FBSyxVQUFVLE1BQU0sc0JBQXNCLENBQUM7QUFDbkQsT0FBTyxFQUFFLFNBQVMsRUFBRSxXQUFXLEVBQUUsY0FBYyxFQUFFLFdBQVcsRUFBRSxlQUFlLEVBQUUsWUFBWSxFQUFFLGNBQWMsRUFBRSxrQkFBa0IsRUFBRSxpQkFBaUIsRUFBRSxZQUFZLEVBQUUsbUJBQW1CLEVBQUUsTUFBTSxjQUFjLENBQUM7QUFDNU0sT0FBTyxFQUFFLGlCQUFpQixFQUFFLHVCQUF1QixFQUFFLE1BQU0sa0JBQWtCLENBQUM7QUFHOUUsT0FBTyxFQUFFLFNBQVMsRUFBRSxNQUFNLGNBQWMsQ0FBQztBQUV6QyxPQUFPLEVBQUUsY0FBYyxFQUFFLFFBQVEsRUFBRSxNQUFNLGlCQUFpQixDQUFDO0FBSTNELE9BQU8sRUFBRSxXQUFXLEVBQUUsTUFBTSxxQkFBcUIsQ0FBQztBQUNsRCxPQUFPLEVBQUUsZUFBZSxFQUFFLE1BQU0sc0JBQXNCLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyIvLyBHRU5FUkFURUQgYnkgcHJvamVuIHdhdGNoIC0gRE8gTk9UIEVESVQuXG4vLyBSZWdlbmVyYXRlZCBmcm9tIHRoZSBleHBvcnRpbmcgbW9kdWxlcyBpbiAuL3NyYy5cbi8vIEhhbmQgZWRpdHMgYXJlIG92ZXJ3cml0dGVuIG9uIHRoZSBuZXh0IHdhdGNoOyB0aGlzIGZpbGUgaXMgcmVhZC1vbmx5LlxuXG5leHBvcnQgKiBhcyBhbGxvd2xpc3QgZnJvbSBcIi4vc3JjL2FsbG93bGlzdC50c1wiO1xuZXhwb3J0ICogYXMgYXBwIGZyb20gXCIuL3NyYy9hcHAudHNcIjtcbmV4cG9ydCAqIGFzIGVudiBmcm9tIFwiLi9zcmMvZW52LnRzXCI7XG5leHBvcnQgKiBhcyBoZWFkZXJzIGZyb20gXCIuL3NyYy9oZWFkZXJzLnRzXCI7XG5leHBvcnQgKiBhcyBpbnRlcmNlcHRvciBmcm9tIFwiLi9zcmMvaW50ZXJjZXB0b3IudHNcIjtcbmV4cG9ydCAqIGFzIG90cCBmcm9tIFwiLi9zcmMvb3RwLnRzXCI7XG5leHBvcnQgKiBhcyBwbHVnaW4gZnJvbSBcIi4vc3JjL3BsdWdpbi50c1wiO1xuZXhwb3J0ICogYXMgcG9ydHIgZnJvbSBcIi4vc3JjL3BvcnRyLnRzXCI7XG5leHBvcnQgKiBhcyBwcm94eSBmcm9tIFwiLi9zcmMvcHJveHkudHNcIjtcbmV4cG9ydCAqIGFzIHJhdGVMaW1pdCBmcm9tIFwiLi9zcmMvcmF0ZS1saW1pdC50c1wiO1xuZXhwb3J0ICogYXMgc2lnbmluZ0tleSBmcm9tIFwiLi9zcmMvc2lnbmluZy1rZXkudHNcIjtcbmV4cG9ydCB7IEFMTE9XX0VOViwgU1VCSkVDVF9FTlYsIEJSQU5EX05BTUVfRU5WLCBNRVNTQUdFX0VOViwgU0VTU0lPTl9UVExfRU5WLCBDT0RFX1RUTF9FTlYsIEpXVF9TRUNSRVRfRU5WLCBTRVNTSU9OX0NVVE9GRl9FTlYsIFBVQkxJQ19ET01BSU5fRU5WLCBJTlNFQ1VSRV9FTlYsIEZPUldBUkRfSEVBREVSU19FTlYgfSBmcm9tIFwiLi9zcmMvZW52LnRzXCI7XG5leHBvcnQgeyBQUk9URUNURURfSEVBREVSUywgREVGQVVMVF9GT1JXQVJEX0hFQURFUlMgfSBmcm9tIFwiLi9zcmMvaGVhZGVycy50c1wiO1xuZXhwb3J0IHR5cGUgeyBIZWFkZXJQb2xpY3kgfSBmcm9tIFwiLi9zcmMvaGVhZGVycy50c1wiO1xuZXhwb3J0IHR5cGUgeyBUdW5uZWxJbnRlcmNlcHRvck9wdGlvbnMgfSBmcm9tIFwiLi9zcmMvaW50ZXJjZXB0b3IudHNcIjtcbmV4cG9ydCB7IENvZGVTdG9yZSB9IGZyb20gXCIuL3NyYy9vdHAudHNcIjtcbmV4cG9ydCB0eXBlIHsgVmVyaWZ5T3V0Y29tZSB9IGZyb20gXCIuL3NyYy9vdHAudHNcIjtcbmV4cG9ydCB7IEF1dGhHYXRlUGx1Z2luLCBhdXRoR2F0ZSB9IGZyb20gXCIuL3NyYy9wbHVnaW4udHNcIjtcbmV4cG9ydCB0eXBlIHsgQXV0aEdhdGVDb25maWcsIFNlbmRDb2RlT3B0aW9ucywgUmVzb2x2ZWRBdXRoR2F0ZUNvbmZpZywgQXV0aEdhdGVBcGkgfSBmcm9tIFwiLi9zcmMvcGx1Z2luLnRzXCI7XG5leHBvcnQgdHlwZSB7IFBvcnRyQ29uZmlnIH0gZnJvbSBcIi4vc3JjL3BvcnRyLnRzXCI7XG5leHBvcnQgdHlwZSB7IFByb3h5T3B0aW9ucyB9IGZyb20gXCIuL3NyYy9wcm94eS50c1wiO1xuZXhwb3J0IHsgUmF0ZUxpbWl0ZXIgfSBmcm9tIFwiLi9zcmMvcmF0ZS1saW1pdC50c1wiO1xuZXhwb3J0IHsgS0VZX1RUTF9TRUNPTkRTIH0gZnJvbSBcIi4vc3JjL3NpZ25pbmcta2V5LnRzXCI7XG5leHBvcnQgdHlwZSB7IFNpZ25pbmdLZXkgfSBmcm9tIFwiLi9zcmMvc2lnbmluZy1rZXkudHNcIjtcbiJdfQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSwyQ0FBMkM7QUFDM0MsbURBQW1EO0FBQ25ELHdFQUF3RTtBQUV4RSxPQUFPLEtBQUssU0FBUyxNQUFNLG9CQUFvQixDQUFDO0FBQ2hELE9BQU8sS0FBSyxTQUFTLE1BQU0scUJBQXFCLENBQUM7QUFDakQsT0FBTyxLQUFLLEdBQUcsTUFBTSxjQUFjLENBQUM7QUFDcEMsT0FBTyxLQUFLLElBQUksTUFBTSxlQUFlLENBQUM7QUFDdEMsT0FBTyxLQUFLLE9BQU8sTUFBTSxrQkFBa0IsQ0FBQztBQUM1QyxPQUFPLEtBQUssV0FBVyxNQUFNLHNCQUFzQixDQUFDO0FBQ3BELE9BQU8sS0FBSyxHQUFHLE1BQU0sY0FBYyxDQUFDO0FBQ3BDLE9BQU8sS0FBSyxNQUFNLE1BQU0saUJBQWlCLENBQUM7QUFDMUMsT0FBTyxLQUFLLEtBQUssTUFBTSxnQkFBZ0IsQ0FBQztBQUN4QyxPQUFPLEtBQUssU0FBUyxNQUFNLHFCQUFxQixDQUFDO0FBQ2pELE9BQU8sS0FBSyxRQUFRLE1BQU0sb0JBQW9CLENBQUM7QUFDL0MsT0FBTyxLQUFLLFVBQVUsTUFBTSxzQkFBc0IsQ0FBQztBQUVuRCxPQUFPLEVBQUUsU0FBUyxFQUFFLFdBQVcsRUFBRSxjQUFjLEVBQUUsV0FBVyxFQUFFLGVBQWUsRUFBRSxZQUFZLEVBQUUsY0FBYyxFQUFFLGtCQUFrQixFQUFFLGlCQUFpQixFQUFFLFlBQVksRUFBRSxtQkFBbUIsRUFBRSxNQUFNLGNBQWMsQ0FBQztBQUM1TSxPQUFPLEVBQUUsV0FBVyxFQUFFLE1BQU0sZUFBZSxDQUFDO0FBRTVDLE9BQU8sRUFBRSxpQkFBaUIsRUFBRSx1QkFBdUIsRUFBRSxNQUFNLGtCQUFrQixDQUFDO0FBRzlFLE9BQU8sRUFBRSxTQUFTLEVBQUUsTUFBTSxjQUFjLENBQUM7QUFFekMsT0FBTyxFQUFFLGNBQWMsRUFBRSxRQUFRLEVBQUUsTUFBTSxpQkFBaUIsQ0FBQztBQUczRCxPQUFPLEVBQUUsV0FBVyxFQUFFLE1BQU0scUJBQXFCLENBQUM7QUFDbEQsT0FBTyxFQUFFLGVBQWUsRUFBRSxNQUFNLHNCQUFzQixDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiLy8gR0VORVJBVEVEIGJ5IHByb2plbiB3YXRjaCAtIERPIE5PVCBFRElULlxuLy8gUmVnZW5lcmF0ZWQgZnJvbSB0aGUgZXhwb3J0aW5nIG1vZHVsZXMgaW4gLi9zcmMuXG4vLyBIYW5kIGVkaXRzIGFyZSBvdmVyd3JpdHRlbiBvbiB0aGUgbmV4dCB3YXRjaDsgdGhpcyBmaWxlIGlzIHJlYWQtb25seS5cblxuZXhwb3J0ICogYXMgYWxsb3dsaXN0IGZyb20gXCIuL3NyYy9hbGxvd2xpc3QudHNcIjtcbmV4cG9ydCAqIGFzIGNvZGVFbWFpbCBmcm9tIFwiLi9zcmMvY29kZS1lbWFpbC50c1wiO1xuZXhwb3J0ICogYXMgZW52IGZyb20gXCIuL3NyYy9lbnYudHNcIjtcbmV4cG9ydCAqIGFzIGdhdGUgZnJvbSBcIi4vc3JjL2dhdGUudHNcIjtcbmV4cG9ydCAqIGFzIGhlYWRlcnMgZnJvbSBcIi4vc3JjL2hlYWRlcnMudHNcIjtcbmV4cG9ydCAqIGFzIGludGVyY2VwdG9yIGZyb20gXCIuL3NyYy9pbnRlcmNlcHRvci50c1wiO1xuZXhwb3J0ICogYXMgb3RwIGZyb20gXCIuL3NyYy9vdHAudHNcIjtcbmV4cG9ydCAqIGFzIHBsdWdpbiBmcm9tIFwiLi9zcmMvcGx1Z2luLnRzXCI7XG5leHBvcnQgKiBhcyBwb3J0ciBmcm9tIFwiLi9zcmMvcG9ydHIudHNcIjtcbmV4cG9ydCAqIGFzIHJhdGVMaW1pdCBmcm9tIFwiLi9zcmMvcmF0ZS1saW1pdC50c1wiO1xuZXhwb3J0ICogYXMgc2VuZENvZGUgZnJvbSBcIi4vc3JjL3NlbmQtY29kZS50c1wiO1xuZXhwb3J0ICogYXMgc2lnbmluZ0tleSBmcm9tIFwiLi9zcmMvc2lnbmluZy1rZXkudHNcIjtcbmV4cG9ydCB0eXBlIHsgQ29kZUNvcHkgfSBmcm9tIFwiLi9zcmMvY29kZS1lbWFpbC50c1wiO1xuZXhwb3J0IHsgQUxMT1dfRU5WLCBTVUJKRUNUX0VOViwgQlJBTkRfTkFNRV9FTlYsIE1FU1NBR0VfRU5WLCBTRVNTSU9OX1RUTF9FTlYsIENPREVfVFRMX0VOViwgSldUX1NFQ1JFVF9FTlYsIFNFU1NJT05fQ1VUT0ZGX0VOViwgUFVCTElDX0RPTUFJTl9FTlYsIElOU0VDVVJFX0VOViwgRk9SV0FSRF9IRUFERVJTX0VOViB9IGZyb20gXCIuL3NyYy9lbnYudHNcIjtcbmV4cG9ydCB7IEFVVEhfUFJFRklYIH0gZnJvbSBcIi4vc3JjL2dhdGUudHNcIjtcbmV4cG9ydCB0eXBlIHsgR2F0ZU9wdGlvbnMgfSBmcm9tIFwiLi9zcmMvZ2F0ZS50c1wiO1xuZXhwb3J0IHsgUFJPVEVDVEVEX0hFQURFUlMsIERFRkFVTFRfRk9SV0FSRF9IRUFERVJTIH0gZnJvbSBcIi4vc3JjL2hlYWRlcnMudHNcIjtcbmV4cG9ydCB0eXBlIHsgSGVhZGVyUG9saWN5IH0gZnJvbSBcIi4vc3JjL2hlYWRlcnMudHNcIjtcbmV4cG9ydCB0eXBlIHsgVHVubmVsSW50ZXJjZXB0b3JPcHRpb25zIH0gZnJvbSBcIi4vc3JjL2ludGVyY2VwdG9yLnRzXCI7XG5leHBvcnQgeyBDb2RlU3RvcmUgfSBmcm9tIFwiLi9zcmMvb3RwLnRzXCI7XG5leHBvcnQgdHlwZSB7IFZlcmlmeU91dGNvbWUgfSBmcm9tIFwiLi9zcmMvb3RwLnRzXCI7XG5leHBvcnQgeyBBdXRoR2F0ZVBsdWdpbiwgYXV0aEdhdGUgfSBmcm9tIFwiLi9zcmMvcGx1Z2luLnRzXCI7XG5leHBvcnQgdHlwZSB7IEF1dGhHYXRlQ29uZmlnLCBTZW5kQ29kZU9wdGlvbnMsIFJlc29sdmVkQXV0aEdhdGVDb25maWcsIEF1dGhHYXRlQXBpIH0gZnJvbSBcIi4vc3JjL3BsdWdpbi50c1wiO1xuZXhwb3J0IHR5cGUgeyBQb3J0ckNvbmZpZyB9IGZyb20gXCIuL3NyYy9wb3J0ci50c1wiO1xuZXhwb3J0IHsgUmF0ZUxpbWl0ZXIgfSBmcm9tIFwiLi9zcmMvcmF0ZS1saW1pdC50c1wiO1xuZXhwb3J0IHsgS0VZX1RUTF9TRUNPTkRTIH0gZnJvbSBcIi4vc3JjL3NpZ25pbmcta2V5LnRzXCI7XG5leHBvcnQgdHlwZSB7IFNpZ25pbmdLZXkgfSBmcm9tIFwiLi9zcmMvc2lnbmluZy1rZXkudHNcIjtcbiJdfQ==

package/lib/src/{app.d.ts → code-email.d.ts}

@@ -1,30 +1,18 @@
 /**
- * The tunnel gate's tiny AppKit "app" - `createApp` WITHOUT a `server()` plugin.
+ * Pure builders for the OTP code email's copy - subject, preheader, and the HTML
+ * and text bodies. No transport, no `@dbx-tools/email` import, so this module is
+ * safe to load whether or not the optional email dependency is present; the actual
+ * send lives in `./send-code`.
  *
- * There is no HTTP server here: the tunnel proxy is the server, and it calls the
- * gate handlers in-process. `createApp` is used only for what it auto-wires:
- *   - `CacheManager` (Lakebase when this process can reach it, else memory) -
- *     which the OTP `CodeStore` and the session signing key use for storage + TTL
- *     eviction;
- *   - the `email()` transport (SMTP / outbox), primed from env, so `sendCode` can
- *     deliver the one-time code;
- *   - dbx-tools auto-configuration + branding via `@dbx-tools/appkit`.
- *
- * It returns the {@link AuthGateApi} the proxy drives. `sendCode` is wired here
- * (the plugin can't resolve HOW to send on its own) to the email plugin's
- * transport. A sign-in code is SYSTEM mail - no on-behalf-of user asked for it
- * and no reply to it reaches anyone - so it sends from the email config's
- * do-not-reply address (`no-reply@EMAIL_DOMAIN` unless EMAIL_SYSTEM_FROM names
- * another).
- *
- * FAIL FAST: a gate that can't email a code is useless, so if email does not
- * resolve to SMTP mode (real delivery), this throws - unless `insecure` is set
- * (`--insecure` / `TUNNEL_INSECURE=true`), in which case the caller runs the
- * tunnel OPEN with no gate.
+ * The shapes here are load-bearing for mobile autofill: the code rides in the
+ * SUBJECT and the PREHEADER (the whole of a push notification), and the text part
+ * keeps the prompt and code on ONE line. See each function for why.
  *
  * @module
  */
-import { type AuthGateApi, type AuthGateConfig, type SendCodeOptions } from "./plugin.ts";
+import type { SendCodeOptions } from "./plugin.ts";
+/** The parts of {@link SendCodeOptions} the code email's copy is built from. */
+export type CodeCopy = Pick<SendCodeOptions, "message" | "codeTtlSeconds">;
 /**
  * A code TTL as the plain phrase the email states ("10 minutes", "45 seconds").
  *
@@ -33,8 +21,6 @@ import { type AuthGateApi, type AuthGateConfig, type SendCodeOptions } from "./p
  * never told the code lives longer than it does.
  */
 export declare function expiresIn(seconds: number): string;
-/** The parts of {@link SendCodeOptions} the code email's copy is built from. */
-type CodeCopy = Pick<SendCodeOptions, "message" | "codeTtlSeconds">;
 /**
  * The HTML part's source: the full branded template, with the code as a large
  * styled heading (`## ` is what makes it prominent in an inbox).
@@ -91,40 +77,3 @@ export declare function codeEmailSubject(code: string, subject: string): string;
  * it recognizes.
  */
 export declare function codeEmailPreview(code: string, opts: CodeCopy): string;
-/**
- * Fill in the Lakebase connection env AppKit's cache needs, so `CacheManager`
- * chooses PERSISTENT storage instead of memory.
- *
- * This is what makes the gate's session signing key and outstanding one-time
- * codes survive a restart. `applyLakebaseEnv` is the SHARED helper AppKit
- * auto-configuration uses, so the gate gets exactly the env a pool needs -
- * `LAKEBASE_ENDPOINT`, `PGHOST`, `PGDATABASE`, and `PGUSER` - rather than a
- * hand-rolled subset. All four matter: `createLakebasePool()` throws without any
- * one of them, and a Databricks App `postgres` resource binding supplies only the
- * first. Without them the pool cannot be built, the cache silently degrades to
- * in-memory, and every redeploy signs out every user (the exact symptom this
- * exists to prevent).
- *
- * It is called here rather than left to `createApp`'s `autoConfigure` because that
- * gates on a `lakebase()` plugin being registered - and this app registers none,
- * having no server to mount Lakebase routes on. Calling the helper directly also
- * lets the gate be stricter than `autoConfigure` is:
- *
- *   - It runs ONLY when a Lakebase env var is present. A tunnel is a wrapper
- *     around someone else's app and must not invent infrastructure, so with
- *     nothing bound it skips rather than falling through the resolver's
- *     list-or-CREATE-a-project path.
- *   - `autoCreate: false` for the same reason, in case a project happens to exist.
- *   - Every failure is a WARNING, never a throw. The cache is an optimization for
- *     session durability; admission still requires a code delivered to an
- *     allow-listed address, so a gate with a memory cache is safe, just forgetful.
- */
-export declare function resolveCacheStorageEnv(): Promise<boolean>;
-/**
- * Boot the gate app and return the API the proxy calls. Throws when email is not
- * in SMTP mode (no way to deliver a code) so a misconfigured gate fails fast at
- * startup rather than silently accepting nobody; the caller may catch this and
- * fall back to insecure/open mode when the operator opted in.
- */
-export declare function startGateApp(config: AuthGateConfig): Promise<AuthGateApi>;
-export {};

package/lib/src/code-email.js

@@ -0,0 +1,108 @@
+/**
+ * Pure builders for the OTP code email's copy - subject, preheader, and the HTML
+ * and text bodies. No transport, no `@dbx-tools/email` import, so this module is
+ * safe to load whether or not the optional email dependency is present; the actual
+ * send lives in `./send-code`.
+ *
+ * The shapes here are load-bearing for mobile autofill: the code rides in the
+ * SUBJECT and the PREHEADER (the whole of a push notification), and the text part
+ * keeps the prompt and code on ONE line. See each function for why.
+ *
+ * @module
+ */
+import { string } from "@dbx-tools/shared-core";
+/** The reassurance line closing both parts. */
+const IGNORE_LINE = "If you did not request this code, you can ignore this email.";
+/**
+ * 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) {
+    return seconds >= 60 && seconds % 60 === 0
+        ? string.pluralize(seconds / 60, "minute")
+        : string.pluralize(seconds, "second");
+}
+/**
+ * The HTML part's source: the full branded template, with the code as a large
+ * styled heading (`## ` is what makes it prominent in an inbox).
+ */
+export function codeEmailHtmlBody(code, opts) {
+    return [
+        opts.message,
+        "",
+        `## ${code}`,
+        "",
+        `This code expires in ${expiresIn(opts.codeTtlSeconds)}.`,
+        "",
+        IGNORE_LINE,
+    ].join("\n");
+}
+/**
+ * The `text/plain` part, supplied EXPLICITLY rather than rendered from the tree
+ * above. Both parts say the same thing; only the line layout differs.
+ *
+ * The prompt and the code share ONE line ("Your verification code is: 123456").
+ * That single-line shape is what iOS, Gmail, Outlook, and Android code detection
+ * keys on most reliably - the heuristics look for a code in the same sentence as
+ * a recognized prompt, so splitting them across lines makes detection dependent
+ * on the client, and any blank line between them defeats it outright.
+ *
+ * The GENERATED text part cannot hold that shape at all: it is a rendering of the
+ * HTML, so it carries the brand header/footer and turns the code heading's CSS
+ * margin into blank lines, arriving as `prompt\n\n\ncode`.
+ *
+ * The code is visible text in BOTH parts, never an image, so a client scraping
+ * either one finds it. No trailer line follows the copy - Apple's domain-bound
+ * `@domain #code` footer is deliberately NOT emitted, since it constrains the
+ * code to one origin and is not what the broadly-compatible shape needs.
+ */
+export function codeEmailTextBody(code, opts) {
+    return [
+        `${opts.message} ${code}`,
+        `This code expires in ${expiresIn(opts.codeTtlSeconds)}.`,
+        "",
+        IGNORE_LINE,
+    ].join("\n");
+}
+/**
+ * The SUBJECT line, with the code in it: `"123456 is your verification code"`.
+ *
+ * The code has to be here, not only in the body, because of what mobile autofill
+ * actually reads. iOS offers a code from an incoming NOTIFICATION - natively for
+ * Messages and Mail, and since iOS 26 for any app's notification text, which is
+ * what finally made Gmail work - and a notification contains the sender, the
+ * subject, and a short snippet. Nothing else. A code that lives in the body is
+ * invisible to it, however cleanly the body is formatted, which is why a perfectly
+ * shaped `text/plain` part still produced no autofill prompt in Gmail.
+ *
+ * `<code> is your <thing>` rather than `<thing>: <code>` because the leading code
+ * survives TRUNCATION: a notification and an inbox list both cut the subject, and
+ * the platform heuristics want the code in the same sentence as a recognized
+ * prompt ("code", "verification"). Putting it first keeps both intact no matter
+ * where the cut lands.
+ *
+ * `subject` is the configured line ("Your verification code"), lower-cased at its
+ * first word so the sentence reads naturally, and left ALONE when it does not look
+ * like the conventional phrasing - an operator who set a deliberate subject gets
+ * theirs with the code prefixed, not a mangled hybrid.
+ */
+export function codeEmailSubject(code, subject) {
+    const trimmed = subject.trim();
+    const conventional = /^your\s+/i.exec(trimmed);
+    const rest = conventional ? trimmed.slice(conventional[0].length) : trimmed;
+    return conventional ? `${code} is your ${rest}` : `${code} - ${trimmed}`;
+}
+/**
+ * The PREHEADER: the snippet beside the subject in an inbox list, and the body of
+ * the push notification. Carries the code for the same reason the subject does -
+ * it is the other half of what a notification shows - and repeats the prompt
+ * wording so a heuristic scanning the snippet alone finds a code next to a phrase
+ * it recognizes.
+ */
+export function codeEmailPreview(code, opts) {
+    return `${opts.message} ${code}`;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY29kZS1lbWFpbC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9jb2RlLWVtYWlsLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOzs7Ozs7Ozs7OztHQVdHO0FBRUgsT0FBTyxFQUFFLE1BQU0sRUFBRSxNQUFNLHdCQUF3QixDQUFDO0FBTWhELCtDQUErQztBQUMvQyxNQUFNLFdBQVcsR0FBRyw4REFBOEQsQ0FBQztBQUVuRjs7Ozs7O0dBTUc7QUFDSCxNQUFNLFVBQVUsU0FBUyxDQUFDLE9BQWU7SUFDdkMsT0FBTyxPQUFPLElBQUksRUFBRSxJQUFJLE9BQU8sR0FBRyxFQUFFLEtBQUssQ0FBQztRQUN4QyxDQUFDLENBQUMsTUFBTSxDQUFDLFNBQVMsQ0FBQyxPQUFPLEdBQUcsRUFBRSxFQUFFLFFBQVEsQ0FBQztRQUMxQyxDQUFDLENBQUMsTUFBTSxDQUFDLFNBQVMsQ0FBQyxPQUFPLEVBQUUsUUFBUSxDQUFDLENBQUM7QUFDMUMsQ0FBQztBQUVEOzs7R0FHRztBQUNILE1BQU0sVUFBVSxpQkFBaUIsQ0FBQyxJQUFZLEVBQUUsSUFBYztJQUM1RCxPQUFPO1FBQ0wsSUFBSSxDQUFDLE9BQU87UUFDWixFQUFFO1FBQ0YsTUFBTSxJQUFJLEVBQUU7UUFDWixFQUFFO1FBQ0Ysd0JBQXdCLFNBQVMsQ0FBQyxJQUFJLENBQUMsY0FBYyxDQUFDLEdBQUc7UUFDekQsRUFBRTtRQUNGLFdBQVc7S0FDWixDQUFDLElBQUksQ0FBQyxJQUFJLENBQUMsQ0FBQztBQUNmLENBQUM7QUFFRDs7Ozs7Ozs7Ozs7Ozs7Ozs7O0dBa0JHO0FBQ0gsTUFBTSxVQUFVLGlCQUFpQixDQUFDLElBQVksRUFBRSxJQUFjO0lBQzVELE9BQU87UUFDTCxHQUFHLElBQUksQ0FBQyxPQUFPLElBQUksSUFBSSxFQUFFO1FBQ3pCLHdCQUF3QixTQUFTLENBQUMsSUFBSSxDQUFDLGNBQWMsQ0FBQyxHQUFHO1FBQ3pELEVBQUU7UUFDRixXQUFXO0tBQ1osQ0FBQyxJQUFJLENBQUMsSUFBSSxDQUFDLENBQUM7QUFDZixDQUFDO0FBRUQ7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OztHQXFCRztBQUNILE1BQU0sVUFBVSxnQkFBZ0IsQ0FBQyxJQUFZLEVBQUUsT0FBZTtJQUM1RCxNQUFNLE9BQU8sR0FBRyxPQUFPLENBQUMsSUFBSSxFQUFFLENBQUM7SUFDL0IsTUFBTSxZQUFZLEdBQUcsV0FBVyxDQUFDLElBQUksQ0FBQyxPQUFPLENBQUMsQ0FBQztJQUMvQyxNQUFNLElBQUksR0FBRyxZQUFZLENBQUMsQ0FBQyxDQUFDLE9BQU8sQ0FBQyxLQUFLLENBQUMsWUFBWSxDQUFDLENBQUMsQ0FBQyxDQUFDLE1BQU0sQ0FBQyxDQUFDLENBQUMsQ0FBQyxPQUFPLENBQUM7SUFDNUUsT0FBTyxZQUFZLENBQUMsQ0FBQyxDQUFDLEdBQUcsSUFBSSxZQUFZLElBQUksRUFBRSxDQUFDLENBQUMsQ0FBQyxHQUFHLElBQUksTUFBTSxPQUFPLEVBQUUsQ0FBQztBQUMzRSxDQUFDO0FBRUQ7Ozs7OztHQU1HO0FBQ0gsTUFBTSxVQUFVLGdCQUFnQixDQUFDLElBQVksRUFBRSxJQUFjO0lBQzNELE9BQU8sR0FBRyxJQUFJLENBQUMsT0FBTyxJQUFJLElBQUksRUFBRSxDQUFDO0FBQ25DLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyIvKipcbiAqIFB1cmUgYnVpbGRlcnMgZm9yIHRoZSBPVFAgY29kZSBlbWFpbCdzIGNvcHkgLSBzdWJqZWN0LCBwcmVoZWFkZXIsIGFuZCB0aGUgSFRNTFxuICogYW5kIHRleHQgYm9kaWVzLiBObyB0cmFuc3BvcnQsIG5vIGBAZGJ4LXRvb2xzL2VtYWlsYCBpbXBvcnQsIHNvIHRoaXMgbW9kdWxlIGlzXG4gKiBzYWZlIHRvIGxvYWQgd2hldGhlciBvciBub3QgdGhlIG9wdGlvbmFsIGVtYWlsIGRlcGVuZGVuY3kgaXMgcHJlc2VudDsgdGhlIGFjdHVhbFxuICogc2VuZCBsaXZlcyBpbiBgLi9zZW5kLWNvZGVgLlxuICpcbiAqIFRoZSBzaGFwZXMgaGVyZSBhcmUgbG9hZC1iZWFyaW5nIGZvciBtb2JpbGUgYXV0b2ZpbGw6IHRoZSBjb2RlIHJpZGVzIGluIHRoZVxuICogU1VCSkVDVCBhbmQgdGhlIFBSRUhFQURFUiAodGhlIHdob2xlIG9mIGEgcHVzaCBub3RpZmljYXRpb24pLCBhbmQgdGhlIHRleHQgcGFydFxuICoga2VlcHMgdGhlIHByb21wdCBhbmQgY29kZSBvbiBPTkUgbGluZS4gU2VlIGVhY2ggZnVuY3Rpb24gZm9yIHdoeS5cbiAqXG4gKiBAbW9kdWxlXG4gKi9cblxuaW1wb3J0IHsgc3RyaW5nIH0gZnJvbSBcIkBkYngtdG9vbHMvc2hhcmVkLWNvcmVcIjtcbmltcG9ydCB0eXBlIHsgU2VuZENvZGVPcHRpb25zIH0gZnJvbSBcIi4vcGx1Z2luLnRzXCI7XG5cbi8qKiBUaGUgcGFydHMgb2Yge0BsaW5rIFNlbmRDb2RlT3B0aW9uc30gdGhlIGNvZGUgZW1haWwncyBjb3B5IGlzIGJ1aWx0IGZyb20uICovXG5leHBvcnQgdHlwZSBDb2RlQ29weSA9IFBpY2s8U2VuZENvZGVPcHRpb25zLCBcIm1lc3NhZ2VcIiB8IFwiY29kZVR0bFNlY29uZHNcIj47XG5cbi8qKiBUaGUgcmVhc3N1cmFuY2UgbGluZSBjbG9zaW5nIGJvdGggcGFydHMuICovXG5jb25zdCBJR05PUkVfTElORSA9IFwiSWYgeW91IGRpZCBub3QgcmVxdWVzdCB0aGlzIGNvZGUsIHlvdSBjYW4gaWdub3JlIHRoaXMgZW1haWwuXCI7XG5cbi8qKlxuICogQSBjb2RlIFRUTCBhcyB0aGUgcGxhaW4gcGhyYXNlIHRoZSBlbWFpbCBzdGF0ZXMgKFwiMTAgbWludXRlc1wiLCBcIjQ1IHNlY29uZHNcIikuXG4gKlxuICogV2hvbGUgbWludXRlcyByZWFkIGFzIG1pbnV0ZXM7IGFueXRoaW5nIGVsc2Ugc3RheXMgaW4gc2Vjb25kcyByYXRoZXIgdGhhblxuICogcm91bmRpbmcsIHNvIGEgOTAtc2Vjb25kIFRUTCBpcyBub3QgYWR2ZXJ0aXNlZCBhcyBcIjEgbWludXRlXCIgYW5kIGEgcmVjaXBpZW50IGlzXG4gKiBuZXZlciB0b2xkIHRoZSBjb2RlIGxpdmVzIGxvbmdlciB0aGFuIGl0IGRvZXMuXG4gKi9cbmV4cG9ydCBmdW5jdGlvbiBleHBpcmVzSW4oc2Vjb25kczogbnVtYmVyKTogc3RyaW5nIHtcbiAgcmV0dXJuIHNlY29uZHMgPj0gNjAgJiYgc2Vjb25kcyAlIDYwID09PSAwXG4gICAgPyBzdHJpbmcucGx1cmFsaXplKHNlY29uZHMgLyA2MCwgXCJtaW51dGVcIilcbiAgICA6IHN0cmluZy5wbHVyYWxpemUoc2Vjb25kcywgXCJzZWNvbmRcIik7XG59XG5cbi8qKlxuICogVGhlIEhUTUwgcGFydCdzIHNvdXJjZTogdGhlIGZ1bGwgYnJhbmRlZCB0ZW1wbGF0ZSwgd2l0aCB0aGUgY29kZSBhcyBhIGxhcmdlXG4gKiBzdHlsZWQgaGVhZGluZyAoYCMjIGAgaXMgd2hhdCBtYWtlcyBpdCBwcm9taW5lbnQgaW4gYW4gaW5ib3gpLlxuICovXG5leHBvcnQgZnVuY3Rpb24gY29kZUVtYWlsSHRtbEJvZHkoY29kZTogc3RyaW5nLCBvcHRzOiBDb2RlQ29weSk6IHN0cmluZyB7XG4gIHJldHVybiBbXG4gICAgb3B0cy5tZXNzYWdlLFxuICAgIFwiXCIsXG4gICAgYCMjICR7Y29kZX1gLFxuICAgIFwiXCIsXG4gICAgYFRoaXMgY29kZSBleHBpcmVzIGluICR7ZXhwaXJlc0luKG9wdHMuY29kZVR0bFNlY29uZHMpfS5gLFxuICAgIFwiXCIsXG4gICAgSUdOT1JFX0xJTkUsXG4gIF0uam9pbihcIlxcblwiKTtcbn1cblxuLyoqXG4gKiBUaGUgYHRleHQvcGxhaW5gIHBhcnQsIHN1cHBsaWVkIEVYUExJQ0lUTFkgcmF0aGVyIHRoYW4gcmVuZGVyZWQgZnJvbSB0aGUgdHJlZVxuICogYWJvdmUuIEJvdGggcGFydHMgc2F5IHRoZSBzYW1lIHRoaW5nOyBvbmx5IHRoZSBsaW5lIGxheW91dCBkaWZmZXJzLlxuICpcbiAqIFRoZSBwcm9tcHQgYW5kIHRoZSBjb2RlIHNoYXJlIE9ORSBsaW5lIChcIllvdXIgdmVyaWZpY2F0aW9uIGNvZGUgaXM6IDEyMzQ1NlwiKS5cbiAqIFRoYXQgc2luZ2xlLWxpbmUgc2hhcGUgaXMgd2hhdCBpT1MsIEdtYWlsLCBPdXRsb29rLCBhbmQgQW5kcm9pZCBjb2RlIGRldGVjdGlvblxuICoga2V5cyBvbiBtb3N0IHJlbGlhYmx5IC0gdGhlIGhldXJpc3RpY3MgbG9vayBmb3IgYSBjb2RlIGluIHRoZSBzYW1lIHNlbnRlbmNlIGFzXG4gKiBhIHJlY29nbml6ZWQgcHJvbXB0LCBzbyBzcGxpdHRpbmcgdGhlbSBhY3Jvc3MgbGluZXMgbWFrZXMgZGV0ZWN0aW9uIGRlcGVuZGVudFxuICogb24gdGhlIGNsaWVudCwgYW5kIGFueSBibGFuayBsaW5lIGJldHdlZW4gdGhlbSBkZWZlYXRzIGl0IG91dHJpZ2h0LlxuICpcbiAqIFRoZSBHRU5FUkFURUQgdGV4dCBwYXJ0IGNhbm5vdCBob2xkIHRoYXQgc2hhcGUgYXQgYWxsOiBpdCBpcyBhIHJlbmRlcmluZyBvZiB0aGVcbiAqIEhUTUwsIHNvIGl0IGNhcnJpZXMgdGhlIGJyYW5kIGhlYWRlci9mb290ZXIgYW5kIHR1cm5zIHRoZSBjb2RlIGhlYWRpbmcncyBDU1NcbiAqIG1hcmdpbiBpbnRvIGJsYW5rIGxpbmVzLCBhcnJpdmluZyBhcyBgcHJvbXB0XFxuXFxuXFxuY29kZWAuXG4gKlxuICogVGhlIGNvZGUgaXMgdmlzaWJsZSB0ZXh0IGluIEJPVEggcGFydHMsIG5ldmVyIGFuIGltYWdlLCBzbyBhIGNsaWVudCBzY3JhcGluZ1xuICogZWl0aGVyIG9uZSBmaW5kcyBpdC4gTm8gdHJhaWxlciBsaW5lIGZvbGxvd3MgdGhlIGNvcHkgLSBBcHBsZSdzIGRvbWFpbi1ib3VuZFxuICogYEBkb21haW4gI2NvZGVgIGZvb3RlciBpcyBkZWxpYmVyYXRlbHkgTk9UIGVtaXR0ZWQsIHNpbmNlIGl0IGNvbnN0cmFpbnMgdGhlXG4gKiBjb2RlIHRvIG9uZSBvcmlnaW4gYW5kIGlzIG5vdCB3aGF0IHRoZSBicm9hZGx5LWNvbXBhdGlibGUgc2hhcGUgbmVlZHMuXG4gKi9cbmV4cG9ydCBmdW5jdGlvbiBjb2RlRW1haWxUZXh0Qm9keShjb2RlOiBzdHJpbmcsIG9wdHM6IENvZGVDb3B5KTogc3RyaW5nIHtcbiAgcmV0dXJuIFtcbiAgICBgJHtvcHRzLm1lc3NhZ2V9ICR7Y29kZX1gLFxuICAgIGBUaGlzIGNvZGUgZXhwaXJlcyBpbiAke2V4cGlyZXNJbihvcHRzLmNvZGVUdGxTZWNvbmRzKX0uYCxcbiAgICBcIlwiLFxuICAgIElHTk9SRV9MSU5FLFxuICBdLmpvaW4oXCJcXG5cIik7XG59XG5cbi8qKlxuICogVGhlIFNVQkpFQ1QgbGluZSwgd2l0aCB0aGUgY29kZSBpbiBpdDogYFwiMTIzNDU2IGlzIHlvdXIgdmVyaWZpY2F0aW9uIGNvZGVcImAuXG4gKlxuICogVGhlIGNvZGUgaGFzIHRvIGJlIGhlcmUsIG5vdCBvbmx5IGluIHRoZSBib2R5LCBiZWNhdXNlIG9mIHdoYXQgbW9iaWxlIGF1dG9maWxsXG4gKiBhY3R1YWxseSByZWFkcy4gaU9TIG9mZmVycyBhIGNvZGUgZnJvbSBhbiBpbmNvbWluZyBOT1RJRklDQVRJT04gLSBuYXRpdmVseSBmb3JcbiAqIE1lc3NhZ2VzIGFuZCBNYWlsLCBhbmQgc2luY2UgaU9TIDI2IGZvciBhbnkgYXBwJ3Mgbm90aWZpY2F0aW9uIHRleHQsIHdoaWNoIGlzXG4gKiB3aGF0IGZpbmFsbHkgbWFkZSBHbWFpbCB3b3JrIC0gYW5kIGEgbm90aWZpY2F0aW9uIGNvbnRhaW5zIHRoZSBzZW5kZXIsIHRoZVxuICogc3ViamVjdCwgYW5kIGEgc2hvcnQgc25pcHBldC4gTm90aGluZyBlbHNlLiBBIGNvZGUgdGhhdCBsaXZlcyBpbiB0aGUgYm9keSBpc1xuICogaW52aXNpYmxlIHRvIGl0LCBob3dldmVyIGNsZWFubHkgdGhlIGJvZHkgaXMgZm9ybWF0dGVkLCB3aGljaCBpcyB3aHkgYSBwZXJmZWN0bHlcbiAqIHNoYXBlZCBgdGV4dC9wbGFpbmAgcGFydCBzdGlsbCBwcm9kdWNlZCBubyBhdXRvZmlsbCBwcm9tcHQgaW4gR21haWwuXG4gKlxuICogYDxjb2RlPiBpcyB5b3VyIDx0aGluZz5gIHJhdGhlciB0aGFuIGA8dGhpbmc+OiA8Y29kZT5gIGJlY2F1c2UgdGhlIGxlYWRpbmcgY29kZVxuICogc3Vydml2ZXMgVFJVTkNBVElPTjogYSBub3RpZmljYXRpb24gYW5kIGFuIGluYm94IGxpc3QgYm90aCBjdXQgdGhlIHN1YmplY3QsIGFuZFxuICogdGhlIHBsYXRmb3JtIGhldXJpc3RpY3Mgd2FudCB0aGUgY29kZSBpbiB0aGUgc2FtZSBzZW50ZW5jZSBhcyBhIHJlY29nbml6ZWRcbiAqIHByb21wdCAoXCJjb2RlXCIsIFwidmVyaWZpY2F0aW9uXCIpLiBQdXR0aW5nIGl0IGZpcnN0IGtlZXBzIGJvdGggaW50YWN0IG5vIG1hdHRlclxuICogd2hlcmUgdGhlIGN1dCBsYW5kcy5cbiAqXG4gKiBgc3ViamVjdGAgaXMgdGhlIGNvbmZpZ3VyZWQgbGluZSAoXCJZb3VyIHZlcmlmaWNhdGlvbiBjb2RlXCIpLCBsb3dlci1jYXNlZCBhdCBpdHNcbiAqIGZpcnN0IHdvcmQgc28gdGhlIHNlbnRlbmNlIHJlYWRzIG5hdHVyYWxseSwgYW5kIGxlZnQgQUxPTkUgd2hlbiBpdCBkb2VzIG5vdCBsb29rXG4gKiBsaWtlIHRoZSBjb252ZW50aW9uYWwgcGhyYXNpbmcgLSBhbiBvcGVyYXRvciB3aG8gc2V0IGEgZGVsaWJlcmF0ZSBzdWJqZWN0IGdldHNcbiAqIHRoZWlycyB3aXRoIHRoZSBjb2RlIHByZWZpeGVkLCBub3QgYSBtYW5nbGVkIGh5YnJpZC5cbiAqL1xuZXhwb3J0IGZ1bmN0aW9uIGNvZGVFbWFpbFN1YmplY3QoY29kZTogc3RyaW5nLCBzdWJqZWN0OiBzdHJpbmcpOiBzdHJpbmcge1xuICBjb25zdCB0cmltbWVkID0gc3ViamVjdC50cmltKCk7XG4gIGNvbnN0IGNvbnZlbnRpb25hbCA9IC9eeW91clxccysvaS5leGVjKHRyaW1tZWQpO1xuICBjb25zdCByZXN0ID0gY29udmVudGlvbmFsID8gdHJpbW1lZC5zbGljZShjb252ZW50aW9uYWxbMF0ubGVuZ3RoKSA6IHRyaW1tZWQ7XG4gIHJldHVybiBjb252ZW50aW9uYWwgPyBgJHtjb2RlfSBpcyB5b3VyICR7cmVzdH1gIDogYCR7Y29kZX0gLSAke3RyaW1tZWR9YDtcbn1cblxuLyoqXG4gKiBUaGUgUFJFSEVBREVSOiB0aGUgc25pcHBldCBiZXNpZGUgdGhlIHN1YmplY3QgaW4gYW4gaW5ib3ggbGlzdCwgYW5kIHRoZSBib2R5IG9mXG4gKiB0aGUgcHVzaCBub3RpZmljYXRpb24uIENhcnJpZXMgdGhlIGNvZGUgZm9yIHRoZSBzYW1lIHJlYXNvbiB0aGUgc3ViamVjdCBkb2VzIC1cbiAqIGl0IGlzIHRoZSBvdGhlciBoYWxmIG9mIHdoYXQgYSBub3RpZmljYXRpb24gc2hvd3MgLSBhbmQgcmVwZWF0cyB0aGUgcHJvbXB0XG4gKiB3b3JkaW5nIHNvIGEgaGV1cmlzdGljIHNjYW5uaW5nIHRoZSBzbmlwcGV0IGFsb25lIGZpbmRzIGEgY29kZSBuZXh0IHRvIGEgcGhyYXNlXG4gKiBpdCByZWNvZ25pemVzLlxuICovXG5leHBvcnQgZnVuY3Rpb24gY29kZUVtYWlsUHJldmlldyhjb2RlOiBzdHJpbmcsIG9wdHM6IENvZGVDb3B5KTogc3RyaW5nIHtcbiAgcmV0dXJuIGAke29wdHMubWVzc2FnZX0gJHtjb2RlfWA7XG59XG4iXX0=

package/lib/src/gate.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 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 type { Request, RequestHandler } from "express";
+import type { AuthGateApi } from "./plugin.ts";
+/** Route prefix the login flow lives under (open, answered in-process). */
+export declare 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 declare function isTunnelHost(req: Request, publicDomain: string | undefined): boolean;
+/**
+ * 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 declare function mountGate(opts: GateOptions, addRoute: (method: "get" | "post", path: string, handler: RequestHandler) => void, addMiddleware: (path: string, handler: RequestHandler) => void): void;