@dbx-tools/tunnel 0.6.60

package/lib/src/signing-key.js

@@ -0,0 +1,170 @@
+/**
+ * The gate's HS256 session-signing key, persisted in AppKit's cache.
+ *
+ * The key decides whether a session COOKIE still verifies. Before this module the
+ * fallback was `randomBytes(32)` per process, so every restart invalidated every
+ * outstanding cookie and each signed-in user had to request a new code - painful
+ * for a tunnel, which restarts whenever the app it wraps does. Now the key is
+ * stored in the cache AppKit already configured (memory, or Lakebase when the
+ * host wires a persistent `CacheStorage`), so with persistent storage a restart
+ * keeps sessions alive for {@link KEY_TTL_SECONDS}.
+ *
+ * An explicitly configured `TUNNEL_AUTH_JWT_SECRET` still wins outright. That is
+ * the right answer for a fleet: an operator-held secret needs no shared cache and
+ * no convergence, and it survives a cache flush.
+ *
+ * ## get / generate / get
+ *
+ * Two instances booting at once both miss, so both would generate - and the loser
+ * would sign cookies with a key the winner rejects. Resolution is a re-READ after
+ * the write: whatever the cache holds afterwards is the key everyone adopts, so
+ * the instances converge on ONE value instead of trusting the one they minted.
+ * (`set` is not conditional in the cache API - there is no `setnx` to lean on -
+ * and this runs once per process, so the extra round-trip is free.)
+ *
+ * A pathological interleave can still cost a key: if A writes between B's write
+ * and B's re-read, B adopts A's key while A adopts its own. The cost is bounded -
+ * a cookie minted in that window fails to verify and the holder signs in again -
+ * and it cannot produce a key one instance TRUSTS but another rejects for longer
+ * than the window itself. Set `TUNNEL_AUTH_JWT_SECRET` to remove the race
+ * entirely.
+ *
+ * ## Forcing every session to end
+ *
+ * {@link resolveSessionCutoff} reads a date from `TUNNEL_AUTH_SESSION_CUTOFF` (or
+ * `--session-cutoff`), and that date is part of the cache KEY. Moving it forward
+ * makes every prior key unreachable, so every cookie signed against it stops
+ * verifying - the log-everyone-out switch, without having to find and flush a
+ * cache entry. The cutoff is also asserted against each token's `iat`, so a
+ * cookie that predates it is refused even if it was signed with the key that is
+ * somehow still current.
+ *
+ * @module
+ */
+import { randomBytes } from "node:crypto";
+import { CacheManager } from "@databricks/appkit";
+import { env, log, object } from "@dbx-tools/shared-core";
+import { JWT_SECRET_ENV, SESSION_CUTOFF_ENV } from "./env.js";
+const logger = log.logger("tunnel:signing-key");
+/**
+ * How long a cached signing key lives: 30 days.
+ *
+ * This is the ceiling on how long a session cookie can stay valid across
+ * restarts, so it is deliberately >= the default session TTL - a key that expired
+ * before the cookies it signed would log everyone out for no reason.
+ */
+export const KEY_TTL_SECONDS = 30 * 24 * 60 * 60;
+/** Cache-key prefix for the signing key, namespaced away from other cache use. */
+const KEY_PREFIX = "tunnel:auth:signing-key:";
+/** Bytes of entropy in a generated key (256-bit, matching HS256's hash width). */
+const KEY_BYTES = 32;
+/**
+ * Resolve the force-clear cutoff as epoch MILLISECONDS, or `0` when unset.
+ *
+ * Accepts whatever `object.toDate` accepts - a `Date`, `2026-08-02`, an ISO
+ * instant, epoch seconds or millis from `date +%s`, or a relative duration
+ * (`-30d`, `7 days ago`), which is the spelling an operator reaching for this
+ * usually wants: sign out everyone who signed in more than a month ago.
+ *
+ * An UNPARSEABLE value is ignored with a warning rather than throwing: this is
+ * the switch that logs a fleet back in, and failing to boot over a typo is worse
+ * than not rotating.
+ */
+export function resolveSessionCutoff(configured) {
+    const raw = configured ?? env.text(SESSION_CUTOFF_ENV) ?? undefined;
+    if (raw === undefined || raw === null || raw === "")
+        return 0;
+    const date = object.toDate(raw);
+    if (!date) {
+        logger.warn(`ignoring unparseable ${env.name(SESSION_CUTOFF_ENV)}`, { value: String(raw) });
+        return 0;
+    }
+    return clampToPast(date.getTime());
+}
+/**
+ * Hold the cutoff at "now", because a FUTURE cutoff 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, with the fix hidden behind understanding this flag. Clamped, a
+ * future date means what an operator setting it always meant: clear everything
+ * outstanding, then carry on.
+ */
+function clampToPast(cutoffMs) {
+    const now = Date.now();
+    if (cutoffMs <= now)
+        return cutoffMs;
+    logger.warn(`${env.name(SESSION_CUTOFF_ENV)} is in the future - clamping to now`, {
+        configured: new Date(cutoffMs).toISOString(),
+    });
+    return now;
+}
+/** The cache key for one cutoff, so moving the cutoff orphans every earlier key. */
+function cacheKey(cutoffMs) {
+    return `${KEY_PREFIX}${cutoffMs}`;
+}
+function decode(stored) {
+    return new Uint8Array(Buffer.from(stored.secret, "base64url"));
+}
+/**
+ * Load the signing key for `cutoffMs` from the cache, minting and storing one
+ * when absent. See the module docs for why the write is followed by a re-read.
+ */
+async function loadFromCache(cutoffMs) {
+    const cache = CacheManager.getInstanceSync();
+    const key = cacheKey(cutoffMs);
+    const existing = await cache.get(key);
+    if (existing?.secret) {
+        logger.info("reusing cached signing key", { createdAt: existing.createdAt });
+        return decode(existing);
+    }
+    const minted = {
+        secret: Buffer.from(randomBytes(KEY_BYTES)).toString("base64url"),
+        createdAt: new Date().toISOString(),
+    };
+    await cache.set(key, minted, { ttl: KEY_TTL_SECONDS });
+    // Re-read rather than trusting `minted`: another instance that raced this boot
+    // may have written first, and adopting whatever is stored is what makes the two
+    // converge on one key.
+    const settled = (await cache.get(key)) ?? minted;
+    logger.info("stored a new signing key", {
+        createdAt: settled.createdAt,
+        ttlSeconds: KEY_TTL_SECONDS,
+        adopted: settled.createdAt === minted.createdAt ? "own" : "concurrent-instance",
+    });
+    return decode(settled);
+}
+let pending;
+/**
+ * The signing key for this gate, resolved once per process.
+ *
+ * Resolved ONCE, so `configuredCutoff` is honoured only on the first call - the
+ * plugin's `setup()` passes its resolved value there, before any request can
+ * reach the lazy path.
+ *
+ * `TUNNEL_AUTH_JWT_SECRET` when set, else the cache-backed key. A cache that is
+ * unavailable degrades to an ephemeral per-process key (the previous behaviour)
+ * rather than refusing to sign: 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.
+ */
+export function signingKey(configuredCutoff) {
+    pending ??= (async () => {
+        const cutoffMs = resolveSessionCutoff(configuredCutoff);
+        const configured = env.text(JWT_SECRET_ENV);
+        if (configured) {
+            return { key: new TextEncoder().encode(configured), cutoffMs };
+        }
+        try {
+            return { key: await loadFromCache(cutoffMs), cutoffMs };
+        }
+        catch (error) {
+            logger.warn(`no ${env.name(JWT_SECRET_ENV)} and the cache is unavailable - using an ephemeral per-process key; sessions will not survive a restart`, { error });
+            return { key: new Uint8Array(randomBytes(KEY_BYTES)), cutoffMs };
+        }
+    })();
+    return pending;
+}
+/** Reset the per-process key (tests, or after changing the env in-process). */
+export function resetSigningKey() {
+    pending = undefined;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2lnbmluZy1rZXkuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvc2lnbmluZy1rZXkudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUE7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OztHQTBDRztBQUVILE9BQU8sRUFBRSxXQUFXLEVBQUUsTUFBTSxhQUFhLENBQUM7QUFDMUMsT0FBTyxFQUFFLFlBQVksRUFBRSxNQUFNLG9CQUFvQixDQUFDO0FBQ2xELE9BQU8sRUFBRSxHQUFHLEVBQUUsR0FBRyxFQUFFLE1BQU0sRUFBRSxNQUFNLHdCQUF3QixDQUFDO0FBQzFELE9BQU8sRUFBRSxjQUFjLEVBQUUsa0JBQWtCLEVBQUUsTUFBTSxVQUFVLENBQUM7QUFFOUQsTUFBTSxNQUFNLEdBQUcsR0FBRyxDQUFDLE1BQU0sQ0FBQyxvQkFBb0IsQ0FBQyxDQUFDO0FBRWhEOzs7Ozs7R0FNRztBQUNILE1BQU0sQ0FBQyxNQUFNLGVBQWUsR0FBRyxFQUFFLEdBQUcsRUFBRSxHQUFHLEVBQUUsR0FBRyxFQUFFLENBQUM7QUFFakQsa0ZBQWtGO0FBQ2xGLE1BQU0sVUFBVSxHQUFHLDBCQUEwQixDQUFDO0FBRTlDLGtGQUFrRjtBQUNsRixNQUFNLFNBQVMsR0FBRyxFQUFFLENBQUM7QUFVckI7Ozs7Ozs7Ozs7O0dBV0c7QUFDSCxNQUFNLFVBQVUsb0JBQW9CLENBQUMsVUFBbUM7SUFDdEUsTUFBTSxHQUFHLEdBQUcsVUFBVSxJQUFJLEdBQUcsQ0FBQyxJQUFJLENBQUMsa0JBQWtCLENBQUMsSUFBSSxTQUFTLENBQUM7SUFDcEUsSUFBSSxHQUFHLEtBQUssU0FBUyxJQUFJLEdBQUcsS0FBSyxJQUFJLElBQUksR0FBRyxLQUFLLEVBQUU7UUFBRSxPQUFPLENBQUMsQ0FBQztJQUU5RCxNQUFNLElBQUksR0FBRyxNQUFNLENBQUMsTUFBTSxDQUFDLEdBQUcsQ0FBQyxDQUFDO0lBQ2hDLElBQUksQ0FBQyxJQUFJLEVBQUUs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LE9BQU8sS0FBSyxDQUFDLEtBQUssSUFBSSxFQUFFO1FBQ3RCLE1BQU0sUUFBUSxHQUFHLG9CQUFvQixDQUFDLGdCQUFnQixDQUFDLENBQUM7UUFDeEQsTUFBTSxVQUFVLEdBQUcsR0FBRyxDQUFDLElBQUksQ0FBQyxjQUFjLENBQUMsQ0FBQztRQUM1QyxJQUFJLFVBQVUsRUFBRSxDQUFDO1lBQ2YsT0FBTyxFQUFFLEdBQUcsRUFBRSxJQUFJLFdBQVcsRUFBRSxDQUFDLE1BQU0sQ0FBQyxVQUFVLENBQUMsRUFBRSxRQUFRLEVBQUUsQ0FBQztRQUNqRSxDQUFDO1FBQ0QsSUFBSSxDQUFDO1lBQ0gsT0FBTyxFQUFFLEdBQUcsRUFBRSxNQUFNLGFBQWEsQ0FBQyxRQUFRLENBQUMsRUFBRSxRQUFRLEVBQUUsQ0FBQztRQUMxRCxDQUFDO1FBQUMsT0FBTyxLQUFLLEVBQUUsQ0FBQztZQUNmLE1BQU0sQ0FBQyxJQUFJLENBQ1QsTUFBTSxHQUFHLENBQUMsSUFBSSxDQUFDLGNBQWMsQ0FBQyx5R0FBeUcsRUFDdkksRUFBRSxLQUFLLEVBQUUsQ0FDVixDQUFDO1lBQ0YsT0FBTyxFQUFFLEdBQUcsRUFBRSxJQUFJLFVBQVUsQ0FBQyxXQUFXLENBQUMsU0FBUyxDQUFDLENBQUMsRUFBRSxRQUFRLEVBQUUsQ0FBQztRQUNuRSxDQUFDO0lBQ0gsQ0FBQyxDQUFDLEVBQUUsQ0FBQztJQUNMLE9BQU8sT0FBTyxDQUFDO0FBQ2pCLENBQUM7QUFFRCwrRUFBK0U7QUFDL0UsTUFBTSxVQUFVLGVBQWU7SUFDN0IsT0FBTyxHQUFHLFNBQVMsQ0FBQztBQUN0QixDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiLyoqXG4gKiBUaGUgZ2F0ZSdzIEhTMjU2IHNlc3Npb24tc2lnbmluZyBrZXksIHBlcnNpc3RlZCBpbiBBcHBLaXQncyBjYWNoZS5cbiAqXG4gKiBUaGUga2V5IGRlY2lkZXMgd2hldGhlciBhIHNlc3Npb24gQ09PS0lFIHN0aWxsIHZlcmlmaWVzLiBCZWZvcmUgdGhpcyBtb2R1bGUgdGhlXG4gKiBmYWxsYmFjayB3YXMgYHJhbmRvbUJ5dGVzKDMyKWAgcGVyIHByb2Nlc3MsIHNvIGV2ZXJ5IHJlc3RhcnQgaW52YWxpZGF0ZWQgZXZlcnlcbiAqIG91dHN0YW5kaW5nIGNvb2tpZSBhbmQgZWFjaCBzaWduZWQtaW4gdXNlciBoYWQgdG8gcmVxdWVzdCBhIG5ldyBjb2RlIC0gcGFpbmZ1bFxuICogZm9yIGEgdHVubmVsLCB3aGljaCByZXN0YXJ0cyB3aGVuZXZlciB0aGUgYXBwIGl0IHdyYXBzIGRvZXMuIE5vdyB0aGUga2V5IGlzXG4gKiBzdG9yZWQgaW4gdGhlIGNhY2hlIEFwcEtpdCBhbHJlYWR5IGNvbmZpZ3VyZWQgKG1lbW9yeSwgb3IgTGFrZWJhc2Ugd2hlbiB0aGVcbiAqIGhvc3Qgd2lyZXMgYSBwZXJzaXN0ZW50IGBDYWNoZVN0b3JhZ2VgKSwgc28gd2l0aCBwZXJzaXN0ZW50IHN0b3JhZ2UgYSByZXN0YXJ0XG4gKiBrZWVwcyBzZXNzaW9ucyBhbGl2ZSBmb3Ige0BsaW5rIEtFWV9UVExfU0VDT05EU30uXG4gKlxuICogQW4gZXhwbGljaXRseSBjb25maWd1cmVkIGBUVU5ORUxfQVVUSF9KV1RfU0VDUkVUYCBzdGlsbCB3aW5zIG91dHJpZ2h0LiBUaGF0IGlzXG4gKiB0aGUgcmlnaHQgYW5zd2VyIGZvciBhIGZsZWV0OiBhbiBvcGVyYXRvci1oZWxkIHNlY3JldCBuZWVkcyBubyBzaGFyZWQgY2FjaGUgYW5kXG4gKiBubyBjb252ZXJnZW5jZSwgYW5kIGl0IHN1cnZpdmVzIGEgY2FjaGUgZmx1c2guXG4gKlxuICogIyMgZ2V0IC8gZ2VuZXJhdGUgLyBnZXRcbiAqXG4gKiBUd28gaW5zdGFuY2VzIGJvb3RpbmcgYXQgb25jZSBib3RoIG1pc3MsIHNvIGJvdGggd291bGQgZ2VuZXJhdGUgLSBhbmQgdGhlIGxvc2VyXG4gKiB3b3VsZCBzaWduIGNvb2tpZXMgd2l0aCBhIGtleSB0aGUgd2lubmVyIHJlamVjdHMuIFJlc29sdXRpb24gaXMgYSByZS1SRUFEIGFmdGVyXG4gKiB0aGUgd3JpdGU6IHdoYXRldmVyIHRoZSBjYWNoZSBob2xkcyBhZnRlcndhcmRzIGlzIHRoZSBrZXkgZXZlcnlvbmUgYWRvcHRzLCBzb1xuICogdGhlIGluc3RhbmNlcyBjb252ZXJnZSBvbiBPTkUgdmFsdWUgaW5zdGVhZCBvZiB0cnVzdGluZyB0aGUgb25lIHRoZXkgbWludGVkLlxuICogKGBzZXRgIGlzIG5vdCBjb25kaXRpb25hbCBpbiB0aGUgY2FjaGUgQVBJIC0gdGhlcmUgaXMgbm8gYHNldG54YCB0byBsZWFuIG9uIC1cbiAqIGFuZCB0aGlzIHJ1bnMgb25jZSBwZXIgcHJvY2Vzcywgc28gdGhlIGV4dHJhIHJvdW5kLXRyaXAgaXMgZnJlZS4pXG4gKlxuICogQSBwYXRob2xvZ2ljYWwgaW50ZXJsZWF2ZSBjYW4gc3RpbGwgY29zdCBhIGtleTogaWYgQSB3cml0ZXMgYmV0d2VlbiBCJ3Mgd3JpdGVcbiAqIGFuZCBCJ3MgcmUtcmVhZCwgQiBhZG9wdHMgQSdzIGtleSB3aGlsZSBBIGFkb3B0cyBpdHMgb3duLiBUaGUgY29zdCBpcyBib3VuZGVkIC1cbiAqIGEgY29va2llIG1pbnRlZCBpbiB0aGF0IHdpbmRvdyBmYWlscyB0byB2ZXJpZnkgYW5kIHRoZSBob2xkZXIgc2lnbnMgaW4gYWdhaW4gLVxuICogYW5kIGl0IGNhbm5vdCBwcm9kdWNlIGEga2V5IG9uZSBpbnN0YW5jZSBUUlVTVFMgYnV0IGFub3RoZXIgcmVqZWN0cyBmb3IgbG9uZ2VyXG4gKiB0aGFuIHRoZSB3aW5kb3cgaXRzZWxmLiBTZXQgYFRVTk5FTF9BVVRIX0pXVF9TRUNSRVRgIHRvIHJlbW92ZSB0aGUgcmFjZVxuICogZW50aXJlbHkuXG4gKlxuICogIyMgRm9yY2luZyBldmVyeSBzZXNzaW9uIHRvIGVuZFxuICpcbiAqIHtAbGluayByZXNvbHZlU2Vzc2lvbkN1dG9mZn0gcmVhZHMgYSBkYXRlIGZyb20gYFRVTk5FTF9BVVRIX1NFU1NJT05fQ1VUT0ZGYCAob3JcbiAqIGAtLXNlc3Npb24tY3V0b2ZmYCksIGFuZCB0aGF0IGRhdGUgaXMgcGFydCBvZiB0aGUgY2FjaGUgS0VZLiBNb3ZpbmcgaXQgZm9yd2FyZFxuICogbWFrZXMgZXZlcnkgcHJpb3Iga2V5IHVucmVhY2hhYmxlLCBzbyBldmVyeSBjb29raWUgc2lnbmVkIGFnYWluc3QgaXQgc3RvcHNcbiAqIHZlcmlmeWluZyAtIHRoZSBsb2ctZXZlcnlvbmUtb3V0IHN3aXRjaCwgd2l0aG91dCBoYXZpbmcgdG8gZmluZCBhbmQgZmx1c2ggYVxuICogY2FjaGUgZW50cnkuIFRoZSBjdXRvZmYgaXMgYWxzbyBhc3NlcnRlZCBhZ2FpbnN0IGVhY2ggdG9rZW4ncyBgaWF0YCwgc28gYVxuICogY29va2llIHRoYXQgcHJlZGF0ZXMgaXQgaXMgcmVmdXNlZCBldmVuIGlmIGl0IHdhcyBzaWduZWQgd2l0aCB0aGUga2V5IHRoYXQgaXNcbiAqIHNvbWVob3cgc3RpbGwgY3VycmVudC5cbiAqXG4gKiBAbW9kdWxlXG4gKi9cblxuaW1wb3J0IHsgcmFuZG9tQnl0ZXMgfSBmcm9tIFwibm9kZTpjcnlwdG9cIjtcbmltcG9ydCB7IENhY2hlTWFuYWdlciB9IGZyb20gXCJAZGF0YWJyaWNrcy9hcHBraXRcIjtcbmltcG9ydCB7IGVudiwgbG9nLCBvYmplY3QgfSBmcm9tIFwiQGRieC10b29scy9zaGFyZWQtY29yZVwiO1xuaW1wb3J0IHsgSldUX1NFQ1JFVF9FTlYsIFNFU1NJT05fQ1VUT0ZGX0VOViB9IGZyb20gXCIuL2Vudi50c1wiO1xuXG5jb25zdCBsb2dnZXIgPSBsb2cubG9nZ2VyKFwidHVubmVsOnNpZ25pbmcta2V5XCIpO1xuXG4vKipcbiAqIEhvdyBsb25nIGEgY2FjaGVkIHNpZ25pbmcga2V5IGxpdmVzOiAzMCBkYXlzLlxuICpcbiAqIFRoaXMgaXMgdGhlIGNlaWxpbmcgb24gaG93IGxvbmcgYSBzZXNzaW9uIGNvb2tpZSBjYW4gc3RheSB2YWxpZCBhY3Jvc3NcbiAqIHJlc3RhcnRzLCBzbyBpdCBpcyBkZWxpYmVyYXRlbHkgPj0gdGhlIGRlZmF1bHQgc2Vzc2lvbiBUVEwgLSBhIGtleSB0aGF0IGV4cGlyZWRcbiAqIGJlZm9yZSB0aGUgY29va2llcyBpdCBzaWduZWQgd291bGQgbG9nIGV2ZXJ5b25lIG91dCBmb3Igbm8gcmVhc29uLlxuICovXG5leHBvcnQgY29uc3QgS0VZX1RUTF9TRUNPTkRTID0gMzAgKiAyNCAqIDYwICogNjA7XG5cbi8qKiBDYWNoZS1rZXkgcHJlZml4IGZvciB0aGUgc2lnbmluZyBrZXksIG5hbWVzcGFjZWQgYXdheSBmcm9tIG90aGVyIGNhY2hlIHVzZS4gKi9cbmNvbnN0IEtFWV9QUkVGSVggPSBcInR1bm5lbDphdXRoOnNpZ25pbmcta2V5OlwiO1xuXG4vKiogQnl0ZXMgb2YgZW50cm9weSBpbiBhIGdlbmVyYXRlZCBrZXkgKDI1Ni1iaXQsIG1hdGNoaW5nIEhTMjU2J3MgaGFzaCB3aWR0aCkuICovXG5jb25zdCBLRVlfQllURVMgPSAzMjtcblxuLyoqIFdoYXQgdGhlIGNhY2hlIHN0b3JlczogdGhlIGtleSBwbHVzIHdoZW4gaXQgd2FzIG1pbnRlZCwgZm9yIG9ic2VydmFiaWxpdHkuICovXG5pbnRlcmZhY2UgU3RvcmVkS2V5IHtcbiAgLyoqIEJhc2U2NHVybCBvZiB0aGUgcmF3IGtleSBieXRlcy4gKi9cbiAgc2VjcmV0OiBzdHJpbmc7XG4gIC8qKiBXaGVuIHRoaXMga2V5IHdhcyBnZW5lcmF0ZWQsIElTTy04NjAxLiAqL1xuICBjcmVhdGVkQXQ6IHN0cmluZztcbn1cblxuLyoqXG4gKiBSZXNvbHZlIHRoZSBmb3JjZS1jbGVhciBjdXRvZmYgYXMgZXBvY2ggTUlMTElTRUNPTkRTLCBvciBgMGAgd2hlbiB1bnNldC5cbiAqXG4gKiBBY2NlcHRzIHdoYXRldmVyIGBvYmplY3QudG9EYXRlYCBhY2NlcHRzIC0gYSBgRGF0ZWAsIGAyMDI2LTA4LTAyYCwgYW4gSVNPXG4gKiBpbnN0YW50LCBlcG9jaCBzZWNvbmRzIG9yIG1pbGxpcyBmcm9tIGBkYXRlICslc2AsIG9yIGEgcmVsYXRpdmUgZHVyYXRpb25cbiAqIChgLTMwZGAsIGA3IGRheXMgYWdvYCksIHdoaWNoIGlzIHRoZSBzcGVsbGluZyBhbiBvcGVyYXRvciByZWFjaGluZyBmb3IgdGhpc1xuICogdXN1YWxseSB3YW50czogc2lnbiBvdXQgZXZlcnlvbmUgd2hvIHNpZ25lZCBpbiBtb3JlIHRoYW4gYSBtb250aCBhZ28uXG4gKlxuICogQW4gVU5QQVJTRUFCTEUgdmFsdWUgaXMgaWdub3JlZCB3aXRoIGEgd2FybmluZyByYXRoZXIgdGhhbiB0aHJvd2luZzogdGhpcyBpc1xuICogdGhlIHN3aXRjaCB0aGF0IGxvZ3MgYSBmbGVldCBiYWNrIGluLCBhbmQgZmFpbGluZyB0byBib290IG92ZXIgYSB0eXBvIGlzIHdvcnNlXG4gKiB0aGFuIG5vdCByb3RhdGluZy5cbiAqL1xuZXhwb3J0IGZ1bmN0aW9uIHJlc29sdmVTZXNzaW9uQ3V0b2ZmKGNvbmZpZ3VyZWQ/OiBzdHJpbmcgfCBudW1iZXIgfCBEYXRlKTogbnVtYmVyIHtcbiAgY29uc3QgcmF3ID0gY29uZmlndXJlZCA/PyBlbnYudGV4dChTRVNTSU9OX0NVVE9GRl9FTlYpID8/IHVuZGVmaW5lZDtcbiAgaWYgKHJhdyA9PT0gdW5kZWZpbmVkIHx8IHJhdyA9PT0gbnVsbCB8fCByYXcgPT09IFwiXCIpIHJldHVybiAwO1xuXG4gIGNvbnN0IGRhdGUgPSBvYmplY3QudG9EYXRlKHJhdyk7XG4gIGlmICghZGF0ZSkge1xuICAgIGxvZ2dlci53YXJuKGBpZ25vcmluZyB1bnBhcnNlYWJsZSAke2Vudi5uYW1lKFNFU1NJT05fQ1VUT0ZGX0VOVil9YCwgeyB2YWx1ZTogU3RyaW5nKHJhdykgfSk7XG4gICAgcmV0dXJuIDA7XG4gIH1cbiAgcmV0dXJuIGNsYW1wVG9QYXN0KGRhdGUuZ2V0VGltZSgpKTtcbn1cblxuLyoqXG4gKiBIb2xkIHRoZSBjdXRvZmYgYXQgXCJub3dcIiwgYmVjYXVzZSBhIEZVVFVSRSBjdXRvZmYgd291bGQgcmVmdXNlIHRoZSBzZXNzaW9ucyBpdFxuICogaXMgYWJvdXQgdG8gbWludCBhcyB3ZWxsIGFzIHRoZSBvbGQgb25lcyAtIGFuIGFwcCBub2JvZHkgY2FuIHNpZ24gaW4gdG8sIGZyb20gYVxuICogbWlzdHlwZWQgeWVhciwgd2l0aCB0aGUgZml4IGhpZGRlbiBiZWhpbmQgdW5kZXJzdGFuZGluZyB0aGlzIGZsYWcuIENsYW1wZWQsIGFcbiAqIGZ1dHVyZSBkYXRlIG1lYW5zIHdoYXQgYW4gb3BlcmF0b3Igc2V0dGluZyBpdCBhbHdheXMgbWVhbnQ6IGNsZWFyIGV2ZXJ5dGhpbmdcbiAqIG91dHN0YW5kaW5nLCB0aGVuIGNhcnJ5IG9uLlxuICovXG5mdW5jdGlvbiBjbGFtcFRvUGFzdChjdXRvZmZNczogbnVtYmVyKTogbnVtYmVyIHtcbiAgY29uc3Qgbm93ID0gRGF0ZS5ub3coKTtcbiAgaWYgKGN1dG9mZk1zIDw9IG5vdykgcmV0dXJuIGN1dG9mZk1zO1xuICBsb2dnZXIud2FybihgJHtlbnYubmFtZShTRVNTSU9OX0NVVE9GRl9FTlYpfSBpcyBpbiB0aGUgZnV0dXJlIC0gY2xhbXBpbmcgdG8gbm93YCwge1xuICAgIGNvbmZpZ3VyZWQ6IG5ldyBEYXRlKGN1dG9mZk1zKS50b0lTT1N0cmluZygpLFxuICB9KTtcbiAgcmV0dXJuIG5vdztcbn1cblxuLyoqIFRoZSBjYWNoZSBrZXkgZm9yIG9uZSBjdXRvZmYsIHNvIG1vdmluZyB0aGUgY3V0b2ZmIG9ycGhhbnMgZXZlcnkgZWFybGllciBrZXkuICovXG5mdW5jdGlvbiBjYWNoZUtleShjdXRvZmZNczogbnVtYmVyKTogc3RyaW5nIHtcbiAgcmV0dXJuIGAke0tFWV9QUkVGSVh9JHtjdXRvZmZNc31gO1xufVxuXG5mdW5jdGlvbiBkZWNvZGUoc3RvcmVkOiBTdG9yZWRLZXkpOiBVaW50OEFycmF5IHtcbiAgcmV0dXJuIG5ldyBVaW50OEFycmF5KEJ1ZmZlci5mcm9tKHN0b3JlZC5zZWNyZXQsIFwiYmFzZTY0dXJsXCIpKTtcbn1cblxuLyoqXG4gKiBMb2FkIHRoZSBzaWduaW5nIGtleSBmb3IgYGN1dG9mZk1zYCBmcm9tIHRoZSBjYWNoZSwgbWludGluZyBhbmQgc3RvcmluZyBvbmVcbiAqIHdoZW4gYWJzZW50LiBTZWUgdGhlIG1vZHVsZSBkb2NzIGZvciB3aHkgdGhlIHdyaXRlIGlzIGZvbGxvd2VkIGJ5IGEgcmUtcmVhZC5cbiAqL1xuYXN5bmMgZnVuY3Rpb24gbG9hZEZyb21DYWNoZShjdXRvZmZNczogbnVtYmVyKTogUHJvbWlzZTxVaW50OEFycmF5PiB7XG4gIGNvbnN0IGNhY2hlID0gQ2FjaGVNYW5hZ2VyLmdldEluc3RhbmNlU3luYygpO1xuICBjb25zdCBrZXkgPSBjYWNoZUtleShjdXRvZmZNcyk7XG5cbiAgY29uc3QgZXhpc3RpbmcgPSBhd2FpdCBjYWNoZS5nZXQ8U3RvcmVkS2V5PihrZXkpO1xuICBpZiAoZXhpc3Rpbmc/LnNlY3JldCkge1xuICAgIGxvZ2dlci5pbmZvKFwicmV1c2luZyBjYWNoZWQgc2lnbmluZyBrZXlcIiwgeyBjcmVhdGVkQXQ6IGV4aXN0aW5nLmNyZWF0ZWRBdCB9KTtcbiAgICByZXR1cm4gZGVjb2RlKGV4aXN0aW5nKTtcbiAgfVxuXG4gIGNvbnN0IG1pbnRlZDogU3RvcmVkS2V5ID0ge1xuICAgIHNlY3JldDogQnVmZmVyLmZyb20ocmFuZG9tQnl0ZXMoS0VZX0JZVEVTKSkudG9TdHJpbmcoXCJiYXNlNjR1cmxcIiksXG4gICAgY3JlYXRlZEF0OiBuZXcgRGF0ZSgpLnRvSVNPU3RyaW5nKCksXG4gIH07XG4gIGF3YWl0IGNhY2hlLnNldChrZXksIG1pbnRlZCwgeyB0dGw6IEtFWV9UVExfU0VDT05EUyB9KTtcblxuICAvLyBSZS1yZWFkIHJhdGhlciB0aGFuIHRydXN0aW5nIGBtaW50ZWRgOiBhbm90aGVyIGluc3RhbmNlIHRoYXQgcmFjZWQgdGhpcyBib290XG4gIC8vIG1heSBoYXZlIHdyaXR0ZW4gZmlyc3QsIGFuZCBhZG9wdGluZyB3aGF0ZXZlciBpcyBzdG9yZWQgaXMgd2hhdCBtYWtlcyB0aGUgdHdvXG4gIC8vIGNvbnZlcmdlIG9uIG9uZSBrZXkuXG4gIGNvbnN0IHNldHRsZWQgPSAoYXdhaXQgY2FjaGUuZ2V0PFN0b3JlZEtleT4oa2V5KSkgPz8gbWludGVkO1xuICBsb2dnZXIuaW5mbyhcInN0b3JlZCBhIG5ldyBzaWduaW5nIGtleVwiLCB7XG4gICAgY3JlYXRlZEF0OiBzZXR0bGVkLmNyZWF0ZWRBdCxcbiAgICB0dGxTZWNvbmRzOiBLRVlfVFRMX1NFQ09ORFMsXG4gICAgYWRvcHRlZDogc2V0dGxlZC5jcmVhdGVkQXQgPT09IG1pbnRlZC5jcmVhdGVkQXQgPyBcIm93blwiIDogXCJjb25jdXJyZW50LWluc3RhbmNlXCIsXG4gIH0pO1xuICByZXR1cm4gZGVjb2RlKHNldHRsZWQpO1xufVxuXG4vKiogQSByZXNvbHZlZCBrZXkgcGx1cyB0aGUgY3V0b2ZmIGl0IGlzIHNjb3BlZCB0by4gKi9cbmV4cG9ydCBpbnRlcmZhY2UgU2lnbmluZ0tleSB7XG4gIGtleTogVWludDhBcnJheTtcbiAgLyoqIEZvcmNlLWNsZWFyIGN1dG9mZiBpbiBtczsgYDBgIHdoZW4gdW5zZXQuIFRva2VucyBvbGRlciB0aGFuIHRoaXMgYXJlIHJlZnVzZWQuICovXG4gIGN1dG9mZk1zOiBudW1iZXI7XG59XG5cbmxldCBwZW5kaW5nOiBQcm9taXNlPFNpZ25pbmdLZXk+IHwgdW5kZWZpbmVkO1xuXG4vKipcbiAqIFRoZSBzaWduaW5nIGtleSBmb3IgdGhpcyBnYXRlLCByZXNvbHZlZCBvbmNlIHBlciBwcm9jZXNzLlxuICpcbiAqIFJlc29sdmVkIE9OQ0UsIHNvIGBjb25maWd1cmVkQ3V0b2ZmYCBpcyBob25vdXJlZCBvbmx5IG9uIHRoZSBmaXJzdCBjYWxsIC0gdGhlXG4gKiBwbHVnaW4ncyBgc2V0dXAoKWAgcGFzc2VzIGl0cyByZXNvbHZlZCB2YWx1ZSB0aGVyZSwgYmVmb3JlIGFueSByZXF1ZXN0IGNhblxuICogcmVhY2ggdGhlIGxhenkgcGF0aC5cbiAqXG4gKiBgVFVOTkVMX0FVVEhfSldUX1NFQ1JFVGAgd2hlbiBzZXQsIGVsc2UgdGhlIGNhY2hlLWJhY2tlZCBrZXkuIEEgY2FjaGUgdGhhdCBpc1xuICogdW5hdmFpbGFibGUgZGVncmFkZXMgdG8gYW4gZXBoZW1lcmFsIHBlci1wcm9jZXNzIGtleSAodGhlIHByZXZpb3VzIGJlaGF2aW91cilcbiAqIHJhdGhlciB0aGFuIHJlZnVzaW5nIHRvIHNpZ246IHRoZSBrZXkgb25seSB2YWxpZGF0ZXMgYW4gQUxSRUFEWS1pc3N1ZWQgc2Vzc2lvbixcbiAqIHNvIGxvc2luZyBpdCBjb3N0cyBzZXNzaW9ucywgbmV2ZXIgYWRtaXNzaW9uIC0gYSBjYWxsZXIgc3RpbGwgbmVlZHMgYSBjb2RlXG4gKiBkZWxpdmVyZWQgdG8gYW4gYWxsb3ctbGlzdGVkIGFkZHJlc3MuXG4gKi9cbmV4cG9ydCBmdW5jdGlvbiBzaWduaW5nS2V5KGNvbmZpZ3VyZWRDdXRvZmY/OiBzdHJpbmcgfCBudW1iZXIgfCBEYXRlKTogUHJvbWlzZTxTaWduaW5nS2V5PiB7XG4gIHBlbmRpbmcgPz89IChhc3luYyAoKSA9PiB7XG4gICAgY29uc3QgY3V0b2ZmTXMgPSByZXNvbHZlU2Vzc2lvbkN1dG9mZihjb25maWd1cmVkQ3V0b2ZmKTtcbiAgICBjb25zdCBjb25maWd1cmVkID0gZW52LnRleHQoSldUX1NFQ1JFVF9FTlYpO1xuICAgIGlmIChjb25maWd1cmVkKSB7XG4gICAgICByZXR1cm4geyBrZXk6IG5ldyBUZXh0RW5jb2RlcigpLmVuY29kZShjb25maWd1cmVkKSwgY3V0b2ZmTXMgfTtcbiAgICB9XG4gICAgdHJ5IHtcbiAgICAgIHJldHVybiB7IGtleTogYXdhaXQgbG9hZEZyb21DYWNoZShjdXRvZmZNcyksIGN1dG9mZk1zIH07XG4gICAgfSBjYXRjaCAoZXJyb3IpIHtcbiAgICAgIGxvZ2dlci53YXJuKFxuICAgICAgICBgbm8gJHtlbnYubmFtZShKV1RfU0VDUkVUX0VOVil9IGFuZCB0aGUgY2FjaGUgaXMgdW5hdmFpbGFibGUgLSB1c2luZyBhbiBlcGhlbWVyYWwgcGVyLXByb2Nlc3Mga2V5OyBzZXNzaW9ucyB3aWxsIG5vdCBzdXJ2aXZlIGEgcmVzdGFydGAsXG4gICAgICAgIHsgZXJyb3IgfSxcbiAgICAgICk7XG4gICAgICByZXR1cm4geyBrZXk6IG5ldyBVaW50OEFycmF5KHJhbmRvbUJ5dGVzKEtFWV9CWVRFUykpLCBjdXRvZmZNcyB9O1xuICAgIH1cbiAgfSkoKTtcbiAgcmV0dXJuIHBlbmRpbmc7XG59XG5cbi8qKiBSZXNldCB0aGUgcGVyLXByb2Nlc3Mga2V5ICh0ZXN0cywgb3IgYWZ0ZXIgY2hhbmdpbmcgdGhlIGVudiBpbi1wcm9jZXNzKS4gKi9cbmV4cG9ydCBmdW5jdGlvbiByZXNldFNpZ25pbmdLZXkoKTogdm9pZCB7XG4gIHBlbmRpbmcgPSB1bmRlZmluZWQ7XG59XG4iXX0=

package/lib/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["../src/allowlist.ts","../src/app.ts","../src/env.ts","../src/headers.ts","../src/interceptor.ts","../src/otp.ts","../src/plugin.ts","../src/portr.ts","../src/proxy.ts","../src/rate-limit.ts","../src/signing-key.ts","../index.ts"],"version":"5.9.3"}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@dbx-tools/tunnel",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reggie-db/dbx-tools.git",
+    "directory": "packages/node/tunnel"
+  },
+  "scripts": {
+    "build": "projen build",
+    "compile": "projen compile",
+    "default": "projen default",
+    "package": "projen package",
+    "post-compile": "projen post-compile",
+    "pre-compile": "projen pre-compile",
+    "prepack": "projen prepack",
+    "test": "projen test",
+    "watch": "projen watch",
+    "projen": "projen"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "@types/node": "^24.6.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@databricks/appkit": "^0.43.0",
+    "@dbx-tools/appkit": "0.6.60",
+    "@dbx-tools/core": "0.6.60",
+    "@dbx-tools/email": "0.6.60",
+    "@dbx-tools/shared-core": "0.6.60",
+    "@dbx-tools/shared-email": "0.6.60",
+    "http-proxy-3": "^1.23.3",
+    "jose": "^6.2.3"
+  },
+  "main": "./lib/index.js",
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public",
+    "main": "./lib/index.js",
+    "types": "./lib/index.d.ts",
+    "exports": {
+      ".": {
+        "types": "./lib/index.d.ts",
+        "default": "./lib/index.js"
+      },
+      "./package.json": "./package.json"
+    }
+  },
+  "version": "0.6.60",
+  "types": "./lib/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "lib"
+  ],
+  "dbxToolsConfig": {
+    "tags": [
+      "node"
+    ]
+  },
+  "//": "~~ Generated by projen. To modify, edit .projenrc.js and run \"bunx projen\"."
+}

package/src/allowlist.ts

@@ -0,0 +1,60 @@
+/**
+ * Unified access allow-list matching for the email-OTP gate.
+ *
+ * Each pattern in the configured list is one of three shapes:
+ *
+ *   - **domain shortcut** - `example.com` or `@example.com`: matches any
+ *     address whose domain equals it. This is the gate's OWN semantic (a bare
+ *     value means "the domain", not "the whole address"), so it is handled here.
+ *   - **glob** - contains `*` or `?`, e.g. `*@example.com`: matched against the
+ *     WHOLE address with shell-style wildcards.
+ *   - **regex** - wrapped in slashes, `/.../ [flags]`: tested against the whole
+ *     address. An invalid regex never matches (it is skipped with a warning
+ *     rather than throwing).
+ *
+ * Only the first shape is this module's business: the glob and regex shapes are
+ * delegated to `@dbx-tools/shared-core`'s {@link pattern.toPattern}, which is
+ * where that compilation lives for every allow-list in the repo (the tunnel's
+ * inbound-header policy uses the same one). Matching is case-insensitive
+ * throughout.
+ *
+ * An EMPTY list matches nobody (fail closed): an app that enables the gate but
+ * configures no patterns lets no one in, which is the safe default.
+ *
+ * @module
+ */
+
+import { pattern } from "@dbx-tools/shared-core";
+
+/** True when `email` matches a single allow-list `pattern`. */
+function matchesPattern(email: string, entry: string): boolean {
+  const trimmed = entry.trim();
+  if (!trimmed) return false;
+  const address = email.trim().toLowerCase();
+
+  // A bare value with no wildcard and no regex delimiters is a DOMAIN shortcut,
+  // the one shape shared-core cannot infer: there it would mean whole-string
+  // equality against the address, which is never what an operator writing
+  // `example.com` in an access list intends.
+  if (!trimmed.startsWith("/") && !trimmed.includes("*") && !trimmed.includes("?")) {
+    const domain = trimmed.replace(/^@/, "").toLowerCase();
+    const at = address.lastIndexOf("@");
+    return at >= 0 && address.slice(at + 1) === domain;
+  }
+
+  return pattern.toPattern(trimmed)?.(address) ?? false;
+}
+
+/**
+ * True when `email` is allowed by ANY pattern in `patterns`. An empty (or
+ * missing) list allows nobody - the gate fails closed.
+ */
+export function matchesAllowlist(email: string, patterns: readonly string[] | undefined): boolean {
+  if (!email || !patterns || patterns.length === 0) return false;
+  return patterns.some((entry) => matchesPattern(email, entry));
+}
+
+/** Rough shape check so a clearly-invalid address is rejected before any work. */
+export function looksLikeEmail(value: string): boolean {
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value.trim());
+}

package/src/app.ts

@@ -0,0 +1,292 @@
+/**
+ * The tunnel gate's tiny AppKit "app" - `createApp` WITHOUT a `server()` plugin.
+ *
+ * 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.
+ *
+ * @module
+ */
+
+import { createApp as createAppNs, lakebaseResolver } from "@dbx-tools/appkit";
+import { brand as nodeBrand } from "@dbx-tools/core";
+import { brand as emailBrand, email, sender, transport } from "@dbx-tools/email";
+import { env, log, string } from "@dbx-tools/shared-core";
+import { authGate, type AuthGateApi, type AuthGateConfig, type SendCodeOptions } from "./plugin.ts";
+
+const logger = log.logger("tunnel:app");
+
+/**
+ * A code TTL as the plain phrase the email states ("10 minutes", "45 seconds").
+ *
+ * Whole minutes read as minutes; anything else stays in seconds rather than
+ * rounding, so a 90-second TTL is not advertised as "1 minute" and a recipient is
+ * never told the code lives longer than it does.
+ */
+export function expiresIn(seconds: number): string {
+  return seconds >= 60 && seconds % 60 === 0
+    ? string.pluralize(seconds / 60, "minute")
+    : string.pluralize(seconds, "second");
+}
+
+/** The parts of {@link SendCodeOptions} the code email's copy is built from. */
+type CodeCopy = Pick<SendCodeOptions, "message" | "codeTtlSeconds">;
+
+/** The reassurance line closing both parts. */
+const IGNORE_LINE = "If you did not request this code, you can ignore this email.";
+
+/**
+ * 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: string, opts: CodeCopy): string {
+  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: string, opts: CodeCopy): string {
+  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: string, subject: string): string {
+  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: string, opts: CodeCopy): string {
+  return `${opts.message} ${code}`;
+}
+
+const { createApp } = createAppNs;
+const { applyLakebaseEnv } = lakebaseResolver;
+const { resolveSystemSenderAddress } = sender;
+const { getEmailRuntime, sendEmail } = transport;
+const { emailBrandFromContext } = emailBrand;
+const { loadBrandContext } = nodeBrand;
+
+/**
+ * Env vars whose presence means a Lakebase database was bound to this deployment.
+ * `LAKEBASE_ENDPOINT` is what a Databricks App `postgres` resource binding sets;
+ * `PGHOST` is the local/manual spelling.
+ */
+const LAKEBASE_ENV = ["LAKEBASE_ENDPOINT", "PGHOST"] as const;
+
+/**
+ * Upper bound on resolving the Lakebase connection. The gate is in the request
+ * path for every visitor, so a slow workspace API must not hold up boot
+ * indefinitely; a memory cache is a degraded gate, an unbooted one is no gate.
+ */
+const LAKEBASE_RESOLVE_TIMEOUT_MS = 60_000;
+
+/**
+ * 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 async function resolveCacheStorageEnv(): Promise<boolean> {
+  if (!env.text(LAKEBASE_ENV)) {
+    logger.info(
+      `no ${env.name(LAKEBASE_ENV)} - the gate cache stays in memory; sessions and codes will not survive a restart`,
+    );
+    return false;
+  }
+  try {
+    const { resolved, user } = await applyLakebaseEnv(
+      { autoCreate: false },
+      AbortSignal.timeout(LAKEBASE_RESOLVE_TIMEOUT_MS),
+    );
+    logger.info("lakebase resolved for the gate cache", {
+      host: resolved.host,
+      database: resolved.database,
+      endpoint: resolved.endpoint,
+      user,
+    });
+    return true;
+  } catch (error) {
+    logger.warn(
+      "could not resolve lakebase - the gate cache stays in memory; sessions and codes will not survive a restart",
+      { error },
+    );
+    return false;
+  }
+}
+
+/**
+ * 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 async function startGateApp(config: AuthGateConfig): Promise<AuthGateApi> {
+  // The host app's own brand (`branding/brand.yaml` discovered from cwd) or the
+  // dbx-tools default. This is the ONE brand source for the gate: it styles the
+  // code email (accent band, font, logo) via the email plugin AND supplies the
+  // display name the copy uses, so a deployment that themes its app themes its
+  // sign-in email with it. An explicit `brandName` still wins (see below).
+  const context = await loadBrandContext();
+
+  // Before `createApp`, because AppKit resolves the cache's storage during it and
+  // reads the connection out of `process.env` when it does. See the function's
+  // docs for why the gate resolves this itself.
+  await resolveCacheStorageEnv();
+
+  // `sendCode` delivers the OTP through the email plugin's SHARED transport, which
+  // the `email()` plugin primes during its `setup()` (awaited by `createApp`
+  // below). Using the module-level `sendEmail` avoids a circular dependency on the
+  // app handle's inferred type. The `From` is the SYSTEM sender: a verification
+  // code is machine-generated and unanswerable, so it must not arrive from a
+  // person's address inviting a reply.
+  const sendCode: NonNullable<AuthGateConfig["sendCode"]> = async (to, code, opts) => {
+    const from = resolveSystemSenderAddress(getEmailRuntime().config);
+    await sendEmail(
+      {
+        to: [to],
+        // The code rides in the SUBJECT and the preheader, not just the body:
+        // those two strings are the whole of a push notification, and a
+        // notification is what mobile autofill reads. See `codeEmailSubject`.
+        subject: codeEmailSubject(code, opts.subject),
+        body: codeEmailHtmlBody(code, opts),
+      },
+      from,
+      undefined,
+      { text: codeEmailTextBody(code, opts), preview: codeEmailPreview(code, opts) },
+    );
+  };
+
+  // `createApp` namespaces each plugin's exports on the handle by manifest name;
+  // `handle.authGate` is the in-process gate API the proxy drives.
+  //
+  // `autoConfigure: false` because {@link resolveCacheStorageEnv} above already
+  // ran the one piece of it this app wants (`applyLakebaseEnv`), on this app's
+  // terms - no auto-create, and a warning instead of a throw.
+  const handle = await createApp({
+    autoConfigure: false,
+    plugins: [
+      // Brand the code email from the resolved context, the same bridge every
+      // other dbx-tools email surface uses (accent + font inlined, logo only when
+      // it is a fetchable URL - a package-export path cannot load in an inbox).
+      email({ brand: emailBrandFromContext(context) }),
+      // `brandName` falls back to the resolved context's display name, so the
+      // email copy names the app rather than a generic placeholder. Spelled as an
+      // explicit `??` rather than a key before `...config`: commander sets
+      // `brandName` on the options object whether or not the flag was passed, so
+      // spreading it would clobber the context name with `undefined`.
+      authGate({ ...config, brandName: config.brandName ?? context.name, sendCode }),
+    ],
+  });
+
+  // Fail fast: the gate needs SMTP to email codes. `getEmailRuntime()` resolves to
+  // `mode: "file"` (outbox) or throws when no SMTP creds are configured - neither
+  // can deliver to a real inbox, so refuse to bring up a gate that lets nobody in.
+  if (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 to run the tunnel open.",
+    );
+  }
+
+  logger.info("gate app ready (no server; proxy-driven)");
+  return handle.authGate as AuthGateApi;
+}