@dbx-tools/cli-tunnel 0.6.51 → 0.6.52

package/src/signing-key.ts

@@ -31,11 +31,11 @@
  *
  * ## 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
+ * {@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 epoch is also asserted against each token's `iat`, so 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.
  *
@@ -44,8 +44,8 @@
 
 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";
+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");
 
@@ -73,59 +73,48 @@ interface StoredKey {
 }
 
 /**
- * Resolve the force-clear epoch as epoch MILLISECONDS, or `0` when unset.
+ * 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.
  *
- * 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;
+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;
-  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 });
+  const date = object.toDate(raw);
+  if (!date) {
+    logger.warn(`ignoring unparseable ${env.name(SESSION_CUTOFF_ENV)}`, { value: String(raw) });
     return 0;
   }
-  return parsed;
+  return clampToPast(date.getTime());
 }
 
 /**
- * Hold the cutoff at "now", because a FUTURE epoch would refuse the sessions it
+ * 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(epochMs: number): number {
+function clampToPast(cutoffMs: 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(),
+  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 epoch, so moving the epoch orphans every earlier key. */
-function cacheKey(epochMs: number): string {
-  return `${KEY_PREFIX}${epochMs}`;
+/** 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 {
@@ -133,12 +122,12 @@ function decode(stored: StoredKey): Uint8Array {
 }
 
 /**
- * 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.
+ * 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(epochMs: number): Promise<Uint8Array> {
+async function loadFromCache(cutoffMs: number): Promise<Uint8Array> {
   const cache = CacheManager.getInstanceSync();
-  const key = cacheKey(epochMs);
+  const key = cacheKey(cutoffMs);
 
   const existing = await cache.get<StoredKey>(key);
   if (existing?.secret) {
@@ -164,11 +153,11 @@ async function loadFromCache(epochMs: number): Promise<Uint8Array> {
   return decode(settled);
 }
 
-/** A resolved key plus the epoch it is scoped to. */
+/** A resolved key plus the cutoff 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;
+  /** Force-clear cutoff in ms; `0` when unset. Tokens older than this are refused. */
+  cutoffMs: number;
 }
 
 let pending: Promise<SigningKey> | undefined;
@@ -176,7 +165,7 @@ 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
+ * 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.
  *
@@ -186,21 +175,21 @@ let pending: Promise<SigningKey> | undefined;
  * 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> {
+export function signingKey(configuredCutoff?: string | number | Date): Promise<SigningKey> {
   pending ??= (async () => {
-    const epochMs = resolveSessionEpoch(configuredEpoch);
+    const cutoffMs = resolveSessionCutoff(configuredCutoff);
     const configured = env.text(JWT_SECRET_ENV);
     if (configured) {
-      return { key: new TextEncoder().encode(configured), epochMs };
+      return { key: new TextEncoder().encode(configured), cutoffMs };
     }
     try {
-      return { key: await loadFromCache(epochMs), epochMs };
+      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)), epochMs };
+      return { key: new Uint8Array(randomBytes(KEY_BYTES)), cutoffMs };
     }
   })();
   return pending;