@dbx-tools/cli-tunnel 0.6.49 → 0.6.51

package/src/plugin.ts

@@ -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, resolveSessionEpoch, signingKey } from "./signing-key.ts";
 
 const logger = log.logger("tunnel:auth");
 
@@ -62,12 +63,26 @@ 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 date: every session issued BEFORE it stops verifying, so moving
+   * it forward signs everyone out. Env TUNNEL_AUTH_SESSION_EPOCH.
+   *
+   * Any `Date`-parseable value (`2026-08-02`, an ISO timestamp) or bare epoch
+   * seconds / millis. Unset means no cutoff.
+   */
+  sessionEpoch?: 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 +110,8 @@ export interface ResolvedAuthGateConfig {
   sessionTtlSeconds: number;
   codeTtlSeconds: number;
   maxAttempts: number;
+  /** Force-clear cutoff in epoch ms; `0` when unset. */
+  sessionEpochMs: number;
 }
 
 const DEFAULTS = {
@@ -107,7 +124,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 +148,7 @@ export function resolveAuthGateConfig(config: AuthGateConfig): ResolvedAuthGateC
     ),
     codeTtlSeconds: env.positiveInt(config.codeTtlSeconds, CODE_TTL_ENV, DEFAULTS.codeTtlSeconds),
     maxAttempts: config.maxAttempts ?? DEFAULTS.maxAttempts,
+    sessionEpochMs: resolveSessionEpoch(config.sessionEpoch),
   };
 }
 
@@ -171,9 +190,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 { epochMs } = await signingKey(this.resolved.sessionEpochMs);
     logger.info("ready", {
       patterns: this.resolved.allow.length,
       sessionTtlSeconds: this.resolved.sessionTtlSeconds,
+      ...(epochMs > 0 ? { sessionEpoch: new Date(epochMs).toISOString() } : {}),
     });
   }
 

package/src/signing-key.ts

@@ -0,0 +1,212 @@
+/**
+ * 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 resolveSessionEpoch} reads a date from `TUNNEL_AUTH_SESSION_EPOCH` (or
+ * `--session-epoch`), 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 epoch 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 } from "@dbx-tools/shared-core";
+import { JWT_SECRET_ENV, SESSION_EPOCH_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 epoch as epoch MILLISECONDS, or `0` when unset.
+ *
+ * Accepts anything `Date` parses (`2026-08-02`, an ISO timestamp) plus a bare
+ * epoch-seconds / epoch-millis number, so a value pasted from `date +%s` works.
+ * 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 resolveSessionEpoch(configured?: string | number | Date): number {
+  const raw = configured ?? env.text(SESSION_EPOCH_ENV) ?? undefined;
+  if (raw === undefined || raw === null || raw === "") return 0;
+  return clampToPast(parseEpoch(raw));
+}
+
+/** Parse the accepted epoch spellings to ms, or `0` when unusable. */
+function parseEpoch(raw: string | number | Date): number {
+  if (raw instanceof Date) return Number.isNaN(raw.getTime()) ? 0 : raw.getTime();
+
+  const text = String(raw).trim();
+  // A bare number is a timestamp, not a date string: `Date.parse("1785...")`
+  // would read it as a YEAR. Values below ~1e11 are seconds (any millis
+  // timestamp since 1973 is larger), which is what `date +%s` prints.
+  if (/^\d+$/.test(text)) {
+    const numeric = Number(text);
+    return numeric < 1e11 ? numeric * 1000 : numeric;
+  }
+  const parsed = Date.parse(text);
+  if (Number.isNaN(parsed)) {
+    logger.warn(`ignoring unparseable ${env.name(SESSION_EPOCH_ENV)}`, { value: text });
+    return 0;
+  }
+  return parsed;
+}
+
+/**
+ * Hold the cutoff at "now", because a FUTURE epoch 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(epochMs: number): number {
+  const now = Date.now();
+  if (epochMs <= now) return epochMs;
+  logger.warn(`${env.name(SESSION_EPOCH_ENV)} is in the future - clamping to now`, {
+    configured: new Date(epochMs).toISOString(),
+  });
+  return now;
+}
+
+/** The cache key for one epoch, so moving the epoch orphans every earlier key. */
+function cacheKey(epochMs: number): string {
+  return `${KEY_PREFIX}${epochMs}`;
+}
+
+function decode(stored: StoredKey): Uint8Array {
+  return new Uint8Array(Buffer.from(stored.secret, "base64url"));
+}
+
+/**
+ * Load the signing key for `epochMs` 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(epochMs: number): Promise<Uint8Array> {
+  const cache = CacheManager.getInstanceSync();
+  const key = cacheKey(epochMs);
+
+  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 epoch it is scoped to. */
+export interface SigningKey {
+  key: Uint8Array;
+  /** Force-clear epoch in ms; `0` when unset. Tokens older than this are refused. */
+  epochMs: number;
+}
+
+let pending: Promise<SigningKey> | undefined;
+
+/**
+ * The signing key for this gate, resolved once per process.
+ *
+ * Resolved ONCE, so `configuredEpoch` 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(configuredEpoch?: string | number | Date): Promise<SigningKey> {
+  pending ??= (async () => {
+    const epochMs = resolveSessionEpoch(configuredEpoch);
+    const configured = env.text(JWT_SECRET_ENV);
+    if (configured) {
+      return { key: new TextEncoder().encode(configured), epochMs };
+    }
+    try {
+      return { key: await loadFromCache(epochMs), epochMs };
+    } 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)), epochMs };
+    }
+  })();
+  return pending;
+}
+
+/** Reset the per-process key (tests, or after changing the env in-process). */
+export function resetSigningKey(): void {
+  pending = undefined;
+}