@dbx-tools/cli-tunnel 0.6.59 → 0.6.86

package/README.md

@@ -1,364 +1 @@
-# @dbx-tools/cli-tunnel
-
-Front an app with a public tunnel and an email one-time-code access gate.
-
-Built on [portr](https://github.com/amalshaji/portr). Run this CLI when an app
-needs to be reachable from outside its network - a stakeholder demo, a webhook
-sender that has to reach a dev build, an OAuth redirect that cannot point at
-`localhost` - without publishing the app to anyone who learns the URL. It is
-shaped for Databricks Apps (it honours the `DATABRICKS_APP_PORT` contract and
-lets the platform's own front door through ungated) but the gate itself is
-platform-neutral. The CLI wraps the app's real start command: it
-moves the app onto a private loopback port, binds the public port with a gate
-proxy, and brings the tunnel up alongside it. Access is granted per email
-address against an allow-list, verified by a code sent over
-[`@dbx-tools/email`](../../node/email).
-
-**Key features:**
-
-- Wraps an unmodified start command - everything after `--` runs as-is, so the
-  app needs no tunnel-specific code:
-  `dbxt-tunnel --allow example.com -- bun src/server.ts`.
-- Branded from the repo-wide brand context: the code email's accent colour, font,
-  logo, and display name come from the app's own `branding/brand.yaml` (via
-  `@dbx-tools/core`'s `loadBrandContext()`), falling back to the dbx-tools
-  default - so the sign-in email looks like the app it fronts with nothing to
-  configure. `--brand-name` overrides just the name.
-- Conventional one-time-code copy, so platform autofill works: the email is
-  `Your verification code is: / <code> / This code expires in N minutes`, and the
-  code input carries `autocomplete="one-time-code"`. iOS, Gmail, Outlook, and
-  Android detect a code from that shape and offer it directly from the
-  notification; novel phrasing is what breaks the detection. Both MIME parts carry
-  the code as visible text, never an image, and no trailer follows the copy.
-- The code rides in the SUBJECT and the preheader, not only the body:
-  `123456 is your verification code`. Mobile autofill reads an incoming
-  NOTIFICATION, and a notification contains the sender, the subject, and a short
-  snippet - nothing else - so a code that lives only in the body is unreachable
-  however cleanly the body is shaped. See
-  [Why the code is in the subject](#why-the-code-is-in-the-subject).
-- The two MIME parts are built separately, on purpose. The HTML part is the full
-  branded template with the code as a large styled heading; the `text/plain` part
-  is authored directly, keeping the prompt and the code on ONE line
-  (`Your verification code is: 123456`) because that is the shape client code
-  detection reads most reliably. A generated text part cannot hold it - the text
-  part is a rendering of the HTML, so the heading's CSS margin arrives as blank
-  lines and autofill stops being offered while the HTML still looks perfect. See
-  `codeEmailTextBody` in the `app` module.
-- The sign-in code is SYSTEM mail: it sends from `no-reply@EMAIL_DOMAIN` (or
-  `EMAIL_SYSTEM_FROM`), never a person's address, since a reply to a
-  machine-generated code reaches nobody. `EMAIL_FROM` is not required - see
-  [`@dbx-tools/email`](../../node/email#sender-addresses).
-- Email one-time-code gate: a 6-digit code stored as a SHA-256 hash with an
-  attempt counter, verified in constant time, in AppKit's `CacheManager` (Lakebase
-  when a database is bound to the deployment, else memory) so TTL expiry and
-  eviction are the cache's job.
-- The gate resolves Lakebase for itself, so its cache is actually persistent. The
-  gate is its own tiny AppKit app with no `lakebase()` plugin (it has no server to
-  mount routes on), and AppKit only chooses Lakebase for the cache when a pool can
-  be built from `LAKEBASE_ENDPOINT` **and** `PGHOST` **and** `PGDATABASE` - while a
-  Databricks App `postgres` binding supplies only the first. The gate fills in the
-  rest at boot, and skips entirely when nothing is bound rather than creating
-  infrastructure on someone else's behalf.
-- HS256 session JWT (via `jose`) carrying only the email, signed with a key that
-  is PERSISTED in AppKit's cache for 30 days - so a signed-in browser stays signed
-  in across the restarts a tunnel sees whenever the app it wraps reloads. An
-  operator-held `TUNNEL_AUTH_JWT_SECRET` still wins. `TUNNEL_AUTH_SESSION_CUTOFF`
-  is the log-everyone-out switch, and takes a relative duration (`-30d`) as
-  readily as a date.
-- Allow-list patterns in three shapes, matched in order: a domain shortcut
-  (`example.com`, `@example.com`), a shell-style glob (`*@example.com`), or a
-  regex literal (`/^ops-.*@example\.com$/`). An empty list allows nobody.
-- Per-email and per-IP fixed-window rate limiting, plus anti-enumeration: a code
-  request always answers `{ ok: true }`, whether or not the address is allowed.
-- Inbound `x-` headers are stripped by default and re-allowed by pattern, so a
-  public caller cannot spoof the headers the app trusts - above all
-  `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
-  `--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.
-- 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.
-- Supervised teardown - the app child, the portr child, and this process are tied
-  together, so if any one exits the whole tunnel comes down.
-- Fails fast when email is not configured for SMTP, because a gate that cannot
-  send codes locks everyone out. `--insecure` is the explicit opt-out.
-
-## Why This Over An Ad-Hoc Tunnel
-
-A bare tunnel (`ngrok`, `portr` on its own) makes the app reachable by anyone
-with the URL. This package keeps the tunnel but puts a gate in front of it,
-reusing what the app already has: AppKit's cache for code storage, the
-`@dbx-tools/email` transport for delivery, and the app's own `From` policy. There
-is nothing to add to the app itself - no route, no middleware, no auth library.
-
-## Run It
-
-```sh
-dbxt-tunnel \
-  --allow "example.com, *@partner.example" \
-  --brand-name "Acme Ops" \
-  -- bun src/server.ts
-```
-
-The package installs two equivalent commands, `dbx-tools-tunnel` and the shorter
-`dbxt-tunnel`. Neither matches the package name, so a one-off run has to name the
-command explicitly:
-
-```sh
-npx --package @dbx-tools/cli-tunnel dbx-tools-tunnel --help
-```
-
-Everything after `--` is the real start command. The CLI sets
-`DATABRICKS_APP_PORT` to a random private port for that child and binds the
-original public port itself.
-
-## Options
-
-Every flag has an environment fallback, so a deployment can configure the gate
-with no change to its start command.
-
-| Flag                | Env                          | Default                        |
-| ------------------- | ---------------------------- | ------------------------------ |
-| `--allow`           | `TUNNEL_AUTH_ALLOW`          | empty (allow nobody)           |
-| `--subject`         | `TUNNEL_AUTH_SUBJECT`        | `Your verification code`       |
-| `--brand-name`      | `TUNNEL_AUTH_BRAND_NAME`     | the brand context `name`       |
-| `--message`         | `TUNNEL_AUTH_MESSAGE`        | `Your verification code is:`   |
-| `--session-ttl`     | `TUNNEL_AUTH_SESSION_TTL`    | `2592000` (30 days)            |
-| `--code-ttl`        | `TUNNEL_AUTH_CODE_TTL`       | `600` (10 minutes)             |
-| `--session-cutoff`  | `TUNNEL_AUTH_SESSION_CUTOFF` | unset (no cutoff)              |
-| `--subdomain`       | -                            | derived from the public domain |
-| `--public-domain`   | `TUNNEL_PUBLIC_DOMAIN`       | -                              |
-| `--forward-headers` | `TUNNEL_FORWARD_HEADERS`     | the built-in `x-` allow-list   |
-| `--insecure`        | `TUNNEL_INSECURE`            | off (the gate is required)     |
-| -                   | `TUNNEL_AUTH_JWT_SECRET`     | an ephemeral per-process key   |
-
-Every variable is `TUNNEL_`-prefixed because the gate runs as a WRAPPER: it and
-the app it wraps share one environment, so a generic name is one the app may
-already be using. The earlier unprefixed spellings - `AUTH_SUBJECT`,
-`AUTH_BRAND_NAME`, `AUTH_MESSAGE`, `AUTH_SESSION_TTL`, `AUTH_CODE_TTL`,
-`AUTH_JWT_SECRET`, `EMAIL_AUTH_ALLOW`, `PUBLIC_DOMAIN`, plus
-`TUNNEL_AUTH_SESSION_EPOCH` from before the cutoff rename - are still read as
-deprecated aliases, with the `TUNNEL_` name winning when both are set, so an
-existing deployment needs no coordinated rename. `PORTR_TOKEN` / `PORTR_SERVER`
-keep their names: that namespace belongs to portr itself, as does
-`DATABRICKS_APP_PORT`, which the platform sets and the gate honours.
-
-`--allow` and `TUNNEL_AUTH_ALLOW` are UNIONED rather than one overriding the
-other, so a deployment-wide allow-list and a per-invocation addition both grant
-access.
-
-## Sessions That Survive A Restart
-
-The signing key decides whether an already-issued session COOKIE still verifies,
-so where that key comes from is what decides whether a restart signs everyone out.
-Resolution order:
-
-1. **`TUNNEL_AUTH_JWT_SECRET`**, when set. The right answer for a fleet: an
-   operator-held secret needs no shared cache, and it survives a cache flush.
-2. **A key persisted in AppKit's cache for 30 days.** With a persistent
-   `CacheStorage` (Lakebase) the key outlives the process, so cookies stay valid
-   across restarts - which a tunnel does often, since it restarts whenever the app
-   it wraps reloads. On the default in-memory cache the key is per-process, the
-   same as having no secret at all.
-
-   Getting that persistence is not automatic, and the gate does the work at boot
-   via `lakebaseResolver.applyLakebaseEnv()`: it turns `LAKEBASE_ENDPOINT` into the
-   `PGHOST` / `PGDATABASE` / `PGUSER` the cache's pool also needs. Without them
-   AppKit cannot build the pool, silently uses an in-memory cache, and every
-   redeploy signs everyone out - so the startup log says which one you got
-   (`lakebase resolved for the gate cache`, or `the gate cache stays in memory`).
-   Bind a `postgres` resource to the app to get the persistent path.
-
-3. **An ephemeral per-process key**, when there is no secret and no reachable
-   cache. Sessions do not survive a restart, but the gate still serves: the key
-   only validates an ALREADY-issued session, so losing it costs sessions, never
-   admission. A caller still needs a code delivered to an allow-listed address.
-
-The cached key is read, generated-and-stored, then **re-read**. Two instances
-booting together both miss the cache, so both generate; adopting whatever is
-STORED afterwards is what makes them converge on one key instead of each trusting
-the one it minted. Set `TUNNEL_AUTH_JWT_SECRET` to remove the race entirely.
-
-`TUNNEL_AUTH_SESSION_TTL` defaults to the same 30 days the key is stored for, on
-purpose - a key that expired before the cookies it signed would sign everyone out
-for no reason.
-
-## Why The Code Is In The Subject
-
-The subject line the gate SENDS is `123456 is your verification code` -
-`--subject` is the template the code is spliced into, not the literal line.
-
-Mobile autofill does not read the email; it reads the NOTIFICATION. iOS scans
-incoming notification text for a code and offers to fill it - natively for
-Messages and Mail, and since iOS 26 for any app's notification, which is what
-finally made Gmail work. A notification carries the sender, the subject, and a
-short snippet. That is all. A code sitting in the body is invisible to it no
-matter how carefully the body is formatted, which is why a perfectly shaped
-`text/plain` part alone produced no prompt in Gmail.
-
-So the code goes in both strings a notification actually shows:
-
-- **The subject**, code FIRST, because a notification and an inbox row both
-  truncate: `123456 is your verification code` survives the cut wherever it lands,
-  and keeps the code in the same sentence as the words the heuristics look for.
-  A subject that does not use the conventional `Your ...` phrasing is treated as
-  deliberate and only prefixed (`123456 - Acme Ops access`).
-- **The preheader**, the hidden snippet a client shows beside the subject and puts
-  in the notification body, repeating the prompt with the code
-  (`Your verification code is: 123456`).
-
-The body keeps the code as a large styled heading regardless, for a recipient
-reading the mail rather than a notification. This is deliberately NOT Apple's
-domain-bound `@domain #code` trailer, which binds a code to a single origin;
-subject + preheader works across clients and needs no origin.
-
-### Signing everyone out
-
-`--session-cutoff` / `TUNNEL_AUTH_SESSION_CUTOFF` invalidates every session issued
-before a given moment:
-
-```sh
-dbxt-tunnel --session-cutoff -30d -- bun src/server.ts
-dbxt-tunnel --session-cutoff 2026-08-02 -- bun src/server.ts
-TUNNEL_AUTH_SESSION_CUTOFF="now" dbxt-tunnel -- bun src/server.ts
-```
-
-The value goes through `@dbx-tools/shared-core`'s `object.toDate`, so a date, an
-ISO instant, epoch seconds or millis from `date +%s`, and a relative duration
-(`-30d`, `12 hours ago`) all work - the relative spelling being the one an
-operator usually wants, since "sign out anything older than a month" needs no
-timestamp arithmetic. It works two ways at once, so it holds however the key was
-resolved: the cutoff is part of the key's CACHE KEY (moving it orphans the
-previous key), and it is also checked against each token's `iat` (which is what
-makes it bite when `TUNNEL_AUTH_JWT_SECRET` is set and there is no key to
-rotate).
-
-A FUTURE date is clamped to now, because an unclamped one would refuse the
-sessions it is about to mint as well as the old ones - an app nobody can sign in
-to, from a mistyped year. An unparseable value is ignored with a warning rather
-than failing startup: this is the switch that gets a fleet back in.
-
-## Inbound Header Policy
-
-Tunnel traffic arrives from the public internet, so every header on it is
-attacker-controlled - and the headers an app trusts are exactly the ones a caller
-must not be able to write, because the app cannot tell a header the Databricks
-front door set from one a browser typed.
-
-Enumerating headers to remove is a losing game (a deny-list is only correct until
-the platform adds a header), so the policy is inverted: **every `x-`-prefixed
-request header is stripped from tunnel traffic unless a pattern allows it.** A
-header nobody thought about is removed rather than trusted. Non-`x-` headers -
-`content-type`, `accept`, `authorization`, `cookie` - are the app's normal input
-and pass through untouched.
-
-The default allow-list covers the `x-` namespaces this repo's own client sends
-and its own server reads, so a dbx-tools app works behind the tunnel with no
-configuration:
-
-| Pattern            | Why                                                 |
-| ------------------ | --------------------------------------------------- |
-| `x-mastra-*`       | thread and model routing for `@dbx-tools/ui-mastra` |
-| `x-mlflow-*`       | MLflow trace correlation for feedback               |
-| `x-requested-with` | the conventional AJAX marker                        |
-
-Add an app's own headers with `--forward-headers` /`TUNNEL_FORWARD_HEADERS`. 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:
-
-```sh
-dbxt-tunnel --forward-headers "x-acme-*, /^x-trace-/, x-tenant" -- bun src/server.ts
-```
-
-Some headers no pattern can forward. These decide who a request is and where it
-came from, and on tunnel traffic only the gate may answer that:
-
-| Header                                | Why it is never forwarded                                                                                                                                |
-| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `x-forwarded-access-token`            | OBO auth. A pasted workspace token would make every call in the app run as its owner; a verified email proves nothing about who a credential belongs to. |
-| `x-forwarded-user`, `-email`          | Caller identity. The gate sets these itself, from a verified session.                                                                                    |
-| `x-forwarded-preferred-username`      | Display identity from the IdP.                                                                                                                           |
-| `x-forwarded-host`, `-proto`, `-port` | Original host/scheme/port. Spoofing them poisons absolute URLs the app builds, or makes a plaintext request look like TLS.                               |
-| `x-forwarded-for`, `x-real-ip`        | Client IP. Spoofing forges the audit trail and gives a caller a fresh rate-limit bucket per request.                                                     |
-| `x-request-id`                        | Request correlation UUID. Forged or colliding ids make logs unreliable.                                                                                  |
-
-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.
-
-## Use The Gate As A Plugin
-
-The gate is an AppKit plugin, so an app that wants the OTP flow without the
-tunnel can mount it directly. It registers no routes - it exposes handlers the
-caller invokes - and it takes a `sendCode` callback because delivering mail is
-the one thing it cannot resolve on its own:
-
-```ts
-import { createApp } from "@dbx-tools/appkit";
-import { authGate } from "@dbx-tools/cli-tunnel/plugin";
-import { brand, email, sender, transport } from "@dbx-tools/email";
-
-const handle = await 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),
-        );
-      },
-    }),
-  ],
-});
-
-// 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. When the tunnel
-CLI boots the gate it 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.
-
-## Modules
-
-- `cli` - argv parsing, the wrapped-command split at `--`, and process
-  supervision.
-- `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.
-- `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.
-- `allowlist` - email domain / glob / regex matching and `looksLikeEmail`.
-- `headers` - the inbound-header allow-list: `toHeaderPolicy()`,
-  `DEFAULT_FORWARD_HEADERS`, and the `PROTECTED_HEADERS` no pattern can forward.
-- `rate-limit` - the in-memory fixed-window limiter (single-instance only; not
-  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
-login surface is in [`@dbx-tools/ui-email`](../../ui/email).
+# replace this

package/index.ts

@@ -2,27 +2,10 @@
 // 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.ts";
 export * as app from "./src/app.ts";
 export * as cli from "./src/cli.ts";
-export * as env from "./src/env.ts";
-export * as headers from "./src/headers.ts";
-export * as otp from "./src/otp.ts";
-export * as plugin from "./src/plugin.ts";
-export * as portr from "./src/portr.ts";
+export * as options from "./src/options.ts";
 export * as proxy from "./src/proxy.ts";
-export * as rateLimit from "./src/rate-limit.ts";
-export * as signingKey from "./src/signing-key.ts";
 export { CommanderError } from "./src/cli.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 { PROTECTED_HEADERS, DEFAULT_FORWARD_HEADERS } from "./src/headers.ts";
-export type { HeaderPolicy } from "./src/headers.ts";
-export { CodeStore } from "./src/otp.ts";
-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 { TunnelOptions, ResolvedTunnelOptions } from "./src/options.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,24 +1,7 @@
-export * as allowlist from "./src/allowlist.ts";
 export * as app from "./src/app.ts";
 export * as cli from "./src/cli.ts";
-export * as env from "./src/env.ts";
-export * as headers from "./src/headers.ts";
-export * as otp from "./src/otp.ts";
-export * as plugin from "./src/plugin.ts";
-export * as portr from "./src/portr.ts";
+export * as options from "./src/options.ts";
 export * as proxy from "./src/proxy.ts";
-export * as rateLimit from "./src/rate-limit.ts";
-export * as signingKey from "./src/signing-key.ts";
 export { CommanderError } from "./src/cli.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 { PROTECTED_HEADERS, DEFAULT_FORWARD_HEADERS } from "./src/headers.ts";
-export type { HeaderPolicy } from "./src/headers.ts";
-export { CodeStore } from "./src/otp.ts";
-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 { TunnelOptions, ResolvedTunnelOptions } from "./src/options.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

@@ -1,22 +1,9 @@
 // GENERATED by projen watch - DO NOT EDIT.
 // 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 cli from "./src/cli.js";
-export * as env from "./src/env.js";
-export * as headers from "./src/headers.js";
-export * as otp from "./src/otp.js";
-export * as plugin from "./src/plugin.js";
-export * as portr from "./src/portr.js";
+export * as options from "./src/options.js";
 export * as proxy from "./src/proxy.js";
-export * as rateLimit from "./src/rate-limit.js";
-export * as signingKey from "./src/signing-key.js";
 export { CommanderError } from "./src/cli.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 { 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,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSwyQ0FBMkM7QUFDM0MsbURBQW1EO0FBQ25ELHdFQUF3RTtBQUV4RSxPQUFPLEtBQUssU0FBUyxNQUFNLG9CQUFvQixDQUFDO0FBQ2hELE9BQU8sS0FBSyxHQUFHLE1BQU0sY0FBYyxDQUFDO0FBQ3BDLE9BQU8sS0FBSyxHQUFHLE1BQU0sY0FBYyxDQUFDO0FBQ3BDLE9BQU8sS0FBSyxHQUFHLE1BQU0sY0FBYyxDQUFDO0FBQ3BDLE9BQU8sS0FBSyxPQUFPLE1BQU0sa0JBQWtCLENBQUM7QUFDNUMsT0FBTyxLQUFLLEdBQUcsTUFBTSxjQUFjLENBQUM7QUFDcEMsT0FBTyxLQUFLLE1BQU0sTUFBTSxpQkFBaUIsQ0FBQztBQUMxQyxPQUFPLEtBQUssS0FBSyxNQUFNLGdCQUFnQixDQUFDO0FBQ3hDLE9BQU8sS0FBSyxLQUFLLE1BQU0sZ0JBQWdCLENBQUM7QUFDeEMsT0FBTyxLQUFLLFNBQVMsTUFBTSxxQkFBcUIsQ0FBQztBQUNqRCxPQUFPLEtBQUssVUFBVSxNQUFNLHNCQUFzQixDQUFDO0FBQ25ELE9BQU8sRUFBRSxjQUFjLEVBQUUsTUFBTSxjQUFjLENBQUM7QUFDOUMsT0FBTyxFQUFFLFNBQVMsRUFBRSxXQUFXLEVBQUUsY0FBYyxFQUFFLFdBQVcsRUFBRSxlQUFlLEVBQUUsWUFBWSxFQUFFLGNBQWMsRUFBRSxrQkFBa0IsRUFBRSxpQkFBaUIsRUFBRSxZQUFZLEVBQUUsbUJBQW1CLEVBQUUsTUFBTSxjQUFjLENBQUM7QUFDNU0sT0FBTyxFQUFFLGlCQUFpQixFQUFFLHVCQUF1QixFQUFFLE1BQU0sa0JBQWtCLENBQUM7QUFFOUUsT0FBTyxFQUFFLFNBQVMsRUFBRSxNQUFNLGNBQWMsQ0FBQztBQUV6QyxPQUFPLEVBQUUsY0FBYyxFQUFFLFFBQVEsRUFBRSxNQUFNLGlCQUFpQixDQUFDO0FBSTNELE9BQU8sRUFBRSxXQUFXLEVBQUUsTUFBTSxxQkFBcUIsQ0FBQztBQUNsRCxPQUFPLEVBQUUsZUFBZSxFQUFFLE1BQU0sc0JBQXNCLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyIvLyBHRU5FUkFURUQgYnkgcHJvamVuIHdhdGNoIC0gRE8gTk9UIEVESVQuXG4vLyBSZWdlbmVyYXRlZCBmcm9tIHRoZSBleHBvcnRpbmcgbW9kdWxlcyBpbiAuL3NyYy5cbi8vIEhhbmQgZWRpdHMgYXJlIG92ZXJ3cml0dGVuIG9uIHRoZSBuZXh0IHdhdGNoOyB0aGlzIGZpbGUgaXMgcmVhZC1vbmx5LlxuXG5leHBvcnQgKiBhcyBhbGxvd2xpc3QgZnJvbSBcIi4vc3JjL2FsbG93bGlzdC50c1wiO1xuZXhwb3J0ICogYXMgYXBwIGZyb20gXCIuL3NyYy9hcHAudHNcIjtcbmV4cG9ydCAqIGFzIGNsaSBmcm9tIFwiLi9zcmMvY2xpLnRzXCI7XG5leHBvcnQgKiBhcyBlbnYgZnJvbSBcIi4vc3JjL2Vudi50c1wiO1xuZXhwb3J0ICogYXMgaGVhZGVycyBmcm9tIFwiLi9zcmMvaGVhZGVycy50c1wiO1xuZXhwb3J0ICogYXMgb3RwIGZyb20gXCIuL3NyYy9vdHAudHNcIjtcbmV4cG9ydCAqIGFzIHBsdWdpbiBmcm9tIFwiLi9zcmMvcGx1Z2luLnRzXCI7XG5leHBvcnQgKiBhcyBwb3J0ciBmcm9tIFwiLi9zcmMvcG9ydHIudHNcIjtcbmV4cG9ydCAqIGFzIHByb3h5IGZyb20gXCIuL3NyYy9wcm94eS50c1wiO1xuZXhwb3J0ICogYXMgcmF0ZUxpbWl0IGZyb20gXCIuL3NyYy9yYXRlLWxpbWl0LnRzXCI7XG5leHBvcnQgKiBhcyBzaWduaW5nS2V5IGZyb20gXCIuL3NyYy9zaWduaW5nLWtleS50c1wiO1xuZXhwb3J0IHsgQ29tbWFuZGVyRXJyb3IgfSBmcm9tIFwiLi9zcmMvY2xpLnRzXCI7XG5leHBvcnQgeyBBTExPV19FTlYsIFNVQkpFQ1RfRU5WLCBCUkFORF9OQU1FX0VOViwgTUVTU0FHRV9FTlYsIFNFU1NJT05fVFRMX0VOViwgQ09ERV9UVExfRU5WLCBKV1RfU0VDUkVUX0VOViwgU0VTU0lPTl9DVVRPRkZfRU5WLCBQVUJMSUNfRE9NQUlOX0VOViwgSU5TRUNVUkVfRU5WLCBGT1JXQVJEX0hFQURFUlNfRU5WIH0gZnJvbSBcIi4vc3JjL2Vudi50c1wiO1xuZXhwb3J0IHsgUFJPVEVDVEVEX0hFQURFUlMsIERFRkFVTFRfRk9SV0FSRF9IRUFERVJTIH0gZnJvbSBcIi4vc3JjL2hlYWRlcnMudHNcIjtcbmV4cG9ydCB0eXBlIHsgSGVhZGVyUG9saWN5IH0gZnJvbSBcIi4vc3JjL2hlYWRlcnMudHNcIjtcbmV4cG9ydCB7IENvZGVTdG9yZSB9IGZyb20gXCIuL3NyYy9vdHAudHNcIjtcbmV4cG9ydCB0eXBlIHsgVmVyaWZ5T3V0Y29tZSB9IGZyb20gXCIuL3NyYy9vdHAudHNcIjtcbmV4cG9ydCB7IEF1dGhHYXRlUGx1Z2luLCBhdXRoR2F0ZSB9IGZyb20gXCIuL3NyYy9wbHVnaW4udHNcIjtcbmV4cG9ydCB0eXBlIHsgQXV0aEdhdGVDb25maWcsIFNlbmRDb2RlT3B0aW9ucywgUmVzb2x2ZWRBdXRoR2F0ZUNvbmZpZywgQXV0aEdhdGVBcGkgfSBmcm9tIFwiLi9zcmMvcGx1Z2luLnRzXCI7XG5leHBvcnQgdHlwZSB7IFBvcnRyQ29uZmlnIH0gZnJvbSBcIi4vc3JjL3BvcnRyLnRzXCI7XG5leHBvcnQgdHlwZSB7IFByb3h5T3B0aW9ucyB9IGZyb20gXCIuL3NyYy9wcm94eS50c1wiO1xuZXhwb3J0IHsgUmF0ZUxpbWl0ZXIgfSBmcm9tIFwiLi9zcmMvcmF0ZS1saW1pdC50c1wiO1xuZXhwb3J0IHsgS0VZX1RUTF9TRUNPTkRTIH0gZnJvbSBcIi4vc3JjL3NpZ25pbmcta2V5LnRzXCI7XG5leHBvcnQgdHlwZSB7IFNpZ25pbmdLZXkgfSBmcm9tIFwiLi9zcmMvc2lnbmluZy1rZXkudHNcIjtcbiJdfQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSwyQ0FBMkM7QUFDM0MsbURBQW1EO0FBQ25ELHdFQUF3RTtBQUV4RSxPQUFPLEtBQUssR0FBRyxNQUFNLGNBQWMsQ0FBQztBQUNwQyxPQUFPLEtBQUssR0FBRyxNQUFNLGNBQWMsQ0FBQztBQUNwQyxPQUFPLEtBQUssT0FBTyxNQUFNLGtCQUFrQixDQUFDO0FBQzVDLE9BQU8sS0FBSyxLQUFLLE1BQU0sZ0JBQWdCLENBQUM7QUFDeEMsT0FBTyxFQUFFLGNBQWMsRUFBRSxNQUFNLGNBQWMsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbIi8vIEdFTkVSQVRFRCBieSBwcm9qZW4gd2F0Y2ggLSBETyBOT1QgRURJVC5cbi8vIFJlZ2VuZXJhdGVkIGZyb20gdGhlIGV4cG9ydGluZyBtb2R1bGVzIGluIC4vc3JjLlxuLy8gSGFuZCBlZGl0cyBhcmUgb3ZlcndyaXR0ZW4gb24gdGhlIG5leHQgd2F0Y2g7IHRoaXMgZmlsZSBpcyByZWFkLW9ubHkuXG5cbmV4cG9ydCAqIGFzIGFwcCBmcm9tIFwiLi9zcmMvYXBwLnRzXCI7XG5leHBvcnQgKiBhcyBjbGkgZnJvbSBcIi4vc3JjL2NsaS50c1wiO1xuZXhwb3J0ICogYXMgb3B0aW9ucyBmcm9tIFwiLi9zcmMvb3B0aW9ucy50c1wiO1xuZXhwb3J0ICogYXMgcHJveHkgZnJvbSBcIi4vc3JjL3Byb3h5LnRzXCI7XG5leHBvcnQgeyBDb21tYW5kZXJFcnJvciB9IGZyb20gXCIuL3NyYy9jbGkudHNcIjtcbmV4cG9ydCB0eXBlIHsgVHVubmVsT3B0aW9ucywgUmVzb2x2ZWRUdW5uZWxPcHRpb25zIH0gZnJvbSBcIi4vc3JjL29wdGlvbnMudHNcIjtcbmV4cG9ydCB0eXBlIHsgUHJveHlPcHRpb25zIH0gZnJvbSBcIi4vc3JjL3Byb3h5LnRzXCI7XG4iXX0=

package/lib/src/app.d.ts

@@ -1,130 +1,19 @@
 /**
- * The tunnel gate's tiny AppKit "app" - `createApp` WITHOUT a `server()` plugin.
+ * The GATE half of the wrapper: a server-less AppKit app whose only job is to
+ * expose the `authGate` handlers the proxy calls.
  *
- * 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`.
+ * The in-process plugin path (`authGate` in the app's own `plugins`) has a real
+ * HTTP server to mount routes on. A wrapper does not - the app it fronts is a
+ * separate process it must not reach into - so the gate's login routes live on
+ * the proxy instead, and this app exists purely to give the plugin the runtime it
+ * needs: a `CacheManager` for the one-time-code store and signing key, and the
+ * sibling `email` plugin's transport for delivering a code.
  *
- * 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.
+ * Lazily imported by `cli.ts`, so `dbx tunnel --insecure` (and `install` /
+ * `status`) never load AppKit, the Databricks SDK, or the SMTP stack.
  *
  * @module
  */
-import { type AuthGateApi, type AuthGateConfig, type SendCodeOptions } from "./plugin.ts";
-/**
- * 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 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).
- */
-export declare function codeEmailHtmlBody(code: string, opts: CodeCopy): string;
-/**
- * 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 declare function codeEmailTextBody(code: string, opts: CodeCopy): string;
-/**
- * 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 declare function codeEmailSubject(code: string, subject: string): string;
-/**
- * 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 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.
- */
+import { type AuthGateApi, type AuthGateConfig } from "@dbx-tools/tunnel";
+/** Boot the gate app and return the handlers the proxy authenticates against. */
 export declare function startGateApp(config: AuthGateConfig): Promise<AuthGateApi>;
-export {};