@dbx-tools/cli-tunnel 0.6.50 → 0.6.52

package/src/plugin.ts

@@ -17,7 +17,7 @@
  */
 
 import { Plugin, toPlugin, type BasePluginConfig, type PluginManifest } from "@databricks/appkit";
-import { brand, env, log, string } from "@dbx-tools/shared-core";
+import { brand, env, log, object, string } from "@dbx-tools/shared-core";
 import type { AuthStatus } from "@dbx-tools/shared-email";
 import { looksLikeEmail, matchesAllowlist } from "./allowlist.ts";
 import {
@@ -30,6 +30,7 @@ import {
 } from "./env.ts";
 import { CodeStore, signSession, verifySession } from "./otp.ts";
 import { RateLimiter } from "./rate-limit.ts";
+import { KEY_TTL_SECONDS, resolveSessionCutoff, signingKey } from "./signing-key.ts";
 
 const logger = log.logger("tunnel:auth");
 
@@ -62,12 +63,27 @@ export interface AuthGateConfig extends BasePluginConfig {
    * what the platform code-detection heuristics key on.
    */
   message?: string;
-  /** Session lifetime (seconds). Env TUNNEL_AUTH_SESSION_TTL. Default 43200 (12h). */
+  /**
+   * Session lifetime (seconds). Env TUNNEL_AUTH_SESSION_TTL. Default 2592000 (30d).
+   *
+   * Matched to the cache-backed signing key's own 30-day TTL (see
+   * `./signing-key.ts`): the cookie and the key that validates it should expire
+   * together, or one silently outlives the other.
+   */
   sessionTtlSeconds?: number;
   /** One-time-code lifetime (seconds). Env TUNNEL_AUTH_CODE_TTL. Default 600 (10m). */
   codeTtlSeconds?: number;
   /** Max verify attempts per issued code. Default 5. */
   maxAttempts?: number;
+  /**
+   * Force-clear cutoff: every session issued BEFORE it stops verifying, so moving
+   * it forward signs everyone out. Env TUNNEL_AUTH_SESSION_CUTOFF.
+   *
+   * Anything `object.toDate` accepts: a `Date`, `2026-08-02`, an ISO instant,
+   * epoch seconds/millis, or a relative duration (`-30d`, `7 days ago`). Unset
+   * means no cutoff.
+   */
+  sessionCutoff?: string | number | Date;
   /** Deliver a code to an address. Wired by the app to the email plugin. */
   sendCode?: (email: string, code: string, opts: SendCodeOptions) => Promise<void>;
 }
@@ -95,6 +111,8 @@ export interface ResolvedAuthGateConfig {
   sessionTtlSeconds: number;
   codeTtlSeconds: number;
   maxAttempts: number;
+  /** Force-clear cutoff in epoch ms; `0` when unset. */
+  sessionCutoffMs: number;
 }
 
 const DEFAULTS = {
@@ -107,7 +125,8 @@ const DEFAULTS = {
   // is the fallback when nothing is configured.
   brandName: brand.defaultBrandContext.name,
   message: "Your verification code is:",
-  sessionTtlSeconds: 43200,
+  // 30 days, the same window the cache-backed signing key is stored for.
+  sessionTtlSeconds: KEY_TTL_SECONDS,
   codeTtlSeconds: 600,
   maxAttempts: 5,
 };
@@ -130,6 +149,7 @@ export function resolveAuthGateConfig(config: AuthGateConfig): ResolvedAuthGateC
     ),
     codeTtlSeconds: env.positiveInt(config.codeTtlSeconds, CODE_TTL_ENV, DEFAULTS.codeTtlSeconds),
     maxAttempts: config.maxAttempts ?? DEFAULTS.maxAttempts,
+    sessionCutoffMs: resolveSessionCutoff(config.sessionCutoff),
   };
 }
 
@@ -171,9 +191,14 @@ export class AuthGatePlugin extends Plugin<AuthGateConfig> {
   override async setup(): Promise<void> {
     this.resolved = resolveAuthGateConfig(this.config);
     this.codes = new CodeStore(this.resolved.codeTtlSeconds, this.resolved.maxAttempts);
+    // Resolve the signing key HERE rather than lazily on the first sign-in, so a
+    // cache that cannot hold it (and the resulting "sessions won't survive a
+    // restart" warning) shows up in the startup log, not hours later.
+    const { cutoffMs } = await signingKey(this.resolved.sessionCutoffMs);
     logger.info("ready", {
       patterns: this.resolved.allow.length,
       sessionTtlSeconds: this.resolved.sessionTtlSeconds,
+      ...object.optional("sessionCutoff", cutoffMs > 0 ? new Date(cutoffMs).toISOString() : null),
     });
   }
 

package/src/signing-key.ts

@@ -0,0 +1,201 @@
+/**
+ * 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.ts";
+
+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;
+
+/** What the cache stores: the key plus when it was minted, for observability. */
+interface StoredKey {
+  /** Base64url of the raw key bytes. */
+  secret: string;
+  /** When this key was generated, ISO-8601. */
+  createdAt: string;
+}
+
+/**
+ * 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?: string | number | Date): number {
+  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: number): number {
+  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: number): string {
+  return `${KEY_PREFIX}${cutoffMs}`;
+}
+
+function decode(stored: StoredKey): Uint8Array {
+  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: number): Promise<Uint8Array> {
+  const cache = CacheManager.getInstanceSync();
+  const key = cacheKey(cutoffMs);
+
+  const existing = await cache.get<StoredKey>(key);
+  if (existing?.secret) {
+    logger.info("reusing cached signing key", { createdAt: existing.createdAt });
+    return decode(existing);
+  }
+
+  const minted: StoredKey = {
+    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<StoredKey>(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);
+}
+
+/** A resolved key plus the cutoff it is scoped to. */
+export interface SigningKey {
+  key: Uint8Array;
+  /** Force-clear cutoff in ms; `0` when unset. Tokens older than this are refused. */
+  cutoffMs: number;
+}
+
+let pending: Promise<SigningKey> | undefined;
+
+/**
+ * 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?: string | number | Date): Promise<SigningKey> {
+  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(): void {
+  pending = undefined;
+}