@frontmcp/auth 1.9.2 → 1.9.3

package/esm/index.mjs

@@ -1,6 +1,7 @@
 var __frontmcpModule = typeof process !== "undefined" && typeof process.getBuiltinModule === "function" ? process.getBuiltinModule("module") : undefined;
 const require = __frontmcpModule ? __frontmcpModule.createRequire(import.meta.url || 'file:///') : undefined;
 // __frontmcpCreateRequire
+var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
   get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
@@ -16,6 +17,249 @@ var __esm = (fn, res, err) => function __init() {
     throw err = [e], e;
   }
 };
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// libs/auth/src/cimd/cimd-redis.cache.ts
+var cimd_redis_cache_exports = {};
+__export(cimd_redis_cache_exports, {
+  RedisCimdCache: () => RedisCimdCache
+});
+import { RedisStorageAdapter as RedisStorageAdapter3 } from "@frontmcp/utils";
+import { sha256Hex as sha256Hex5 } from "@frontmcp/utils";
+var RedisCimdCache;
+var init_cimd_redis_cache = __esm({
+  "libs/auth/src/cimd/cimd-redis.cache.ts"() {
+    "use strict";
+    init_cimd_cache();
+    RedisCimdCache = class {
+      redis;
+      keyPrefix;
+      config;
+      constructor(config) {
+        if (!config.redis) {
+          throw new Error("Redis configuration is required for RedisCimdCache");
+        }
+        this.config = {
+          defaultTtlMs: config.defaultTtlMs ?? 36e5,
+          maxTtlMs: config.maxTtlMs ?? 864e5,
+          minTtlMs: config.minTtlMs ?? 6e4
+        };
+        this.keyPrefix = config.redis.keyPrefix ?? "cimd:";
+        const redisOptions = {};
+        if (config.redis.url) {
+          redisOptions.url = config.redis.url;
+        } else if (config.redis.host) {
+          redisOptions.config = {
+            host: config.redis.host,
+            port: config.redis.port,
+            password: config.redis.password,
+            db: config.redis.db,
+            tls: config.redis.tls
+          };
+        }
+        this.redis = new RedisStorageAdapter3(redisOptions);
+      }
+      /**
+       * Connect to Redis.
+       * Must be called before using any cache operations.
+       */
+      async connect() {
+        await this.redis.connect();
+      }
+      /**
+       * Generate a Redis key for a client ID.
+       * Uses SHA-256 hash to handle URLs with special characters.
+       */
+      cacheKey(clientId) {
+        const hash = sha256Hex5(clientId);
+        return `${this.keyPrefix}${hash}`;
+      }
+      /**
+       * Get a cached entry by client_id.
+       *
+       * @param clientId - The client_id URL
+       * @returns The cached entry if valid, or undefined
+       */
+      async get(clientId) {
+        const key = this.cacheKey(clientId);
+        const data = await this.redis.get(key);
+        if (!data) {
+          return void 0;
+        }
+        try {
+          const entry = JSON.parse(data);
+          if (entry.expiresAt < Date.now()) {
+            return void 0;
+          }
+          return entry;
+        } catch {
+          await this.redis.delete(key);
+          return void 0;
+        }
+      }
+      /**
+       * Get a stale entry for conditional revalidation.
+       *
+       * @param clientId - The client_id URL
+       * @returns The stale entry (even if expired), or undefined if not cached
+       */
+      async getStale(clientId) {
+        const key = this.cacheKey(clientId);
+        const data = await this.redis.get(key);
+        if (!data) {
+          return void 0;
+        }
+        try {
+          return JSON.parse(data);
+        } catch {
+          return void 0;
+        }
+      }
+      /**
+       * Store a document in the cache.
+       *
+       * @param clientId - The client_id URL
+       * @param document - The metadata document
+       * @param headers - HTTP response headers
+       */
+      async set(clientId, document, headers) {
+        const cacheHeaders = extractCacheHeaders(headers);
+        const { ttlMs, etag, lastModified } = parseCacheHeaders(cacheHeaders, this.config);
+        const now = Date.now();
+        const entry = {
+          document,
+          expiresAt: now + ttlMs,
+          etag,
+          lastModified,
+          cachedAt: now
+        };
+        const key = this.cacheKey(clientId);
+        const value = JSON.stringify(entry);
+        const redisTtlSeconds = Math.ceil((ttlMs + this.config.maxTtlMs * 2) / 1e3);
+        await this.redis.set(key, value, { ttlSeconds: redisTtlSeconds });
+      }
+      /**
+       * Update an existing cache entry (after 304 Not Modified).
+       *
+       * @param clientId - The client_id URL
+       * @param headers - New HTTP headers with updated cache directives
+       */
+      async revalidate(clientId, headers) {
+        const key = this.cacheKey(clientId);
+        const data = await this.redis.get(key);
+        if (!data) {
+          return false;
+        }
+        try {
+          const existing = JSON.parse(data);
+          const cacheHeaders = extractCacheHeaders(headers);
+          const { ttlMs, etag, lastModified } = parseCacheHeaders(cacheHeaders, this.config);
+          existing.expiresAt = Date.now() + ttlMs;
+          if (etag) existing.etag = etag;
+          if (lastModified) existing.lastModified = lastModified;
+          const value = JSON.stringify(existing);
+          const redisTtlSeconds = Math.ceil((ttlMs + this.config.maxTtlMs * 2) / 1e3);
+          await this.redis.set(key, value, { ttlSeconds: redisTtlSeconds });
+          return true;
+        } catch {
+          return false;
+        }
+      }
+      /**
+       * Delete a cache entry.
+       *
+       * @param clientId - The client_id URL
+       * @returns true if an entry was deleted
+       */
+      async delete(clientId) {
+        const key = this.cacheKey(clientId);
+        return this.redis.delete(key);
+      }
+      /**
+       * Get conditional request headers for a cached entry.
+       *
+       * @param clientId - The client_id URL
+       * @returns Headers for conditional request, or undefined if not cached
+       */
+      async getConditionalHeaders(clientId) {
+        const key = this.cacheKey(clientId);
+        const data = await this.redis.get(key);
+        if (!data) {
+          return void 0;
+        }
+        try {
+          const entry = JSON.parse(data);
+          const headers = {};
+          if (entry.etag) {
+            headers["If-None-Match"] = entry.etag;
+          }
+          if (entry.lastModified) {
+            headers["If-Modified-Since"] = entry.lastModified;
+          }
+          return Object.keys(headers).length > 0 ? headers : void 0;
+        } catch {
+          return void 0;
+        }
+      }
+      /**
+       * Clear all cached entries.
+       * Uses Redis SCAN to find and delete all keys with our prefix.
+       */
+      async clear() {
+        const keys = await this.redis.keys(`${this.keyPrefix}*`);
+        if (keys.length > 0) {
+          await this.redis.mdelete(keys);
+        }
+      }
+      /**
+       * Get the number of cached entries.
+       * Uses Redis SCAN to count keys with our prefix.
+       */
+      async size() {
+        const keys = await this.redis.keys(`${this.keyPrefix}*`);
+        return keys.length;
+      }
+      /**
+       * Remove expired entries.
+       *
+       * Note: Redis handles expiration automatically via TTL.
+       * This method is primarily for explicit cleanup of entries that are
+       * well past their HTTP cache expiration but still within Redis TTL.
+       *
+       * @returns Number of entries removed
+       */
+      async cleanup() {
+        const now = Date.now();
+        let removed = 0;
+        const keys = await this.redis.keys(`${this.keyPrefix}*`);
+        for (const key of keys) {
+          const data = await this.redis.get(key);
+          if (!data) continue;
+          try {
+            const entry = JSON.parse(data);
+            if (entry.expiresAt + this.config.maxTtlMs * 2 < now) {
+              await this.redis.delete(key);
+              removed++;
+            }
+          } catch {
+            await this.redis.delete(key);
+            removed++;
+          }
+        }
+        return removed;
+      }
+      /**
+       * Close the Redis connection.
+       */
+      async close() {
+        await this.redis.disconnect();
+      }
+    };
+  }
+});
 
 // libs/auth/src/cimd/cimd.cache.ts
 function extractCacheHeaders(headers) {
@@ -82,6 +326,19 @@ function parseCacheControlHeader(value) {
   }
   return result;
 }
+async function createCimdCache(config) {
+  const cacheType = config?.type ?? "memory";
+  if (cacheType === "redis") {
+    if (!config?.redis) {
+      throw new Error('Redis configuration is required when cache type is "redis"');
+    }
+    const { RedisCimdCache: RedisCimdCache2 } = await Promise.resolve().then(() => (init_cimd_redis_cache(), cimd_redis_cache_exports));
+    const cache = new RedisCimdCache2(config);
+    await cache.connect();
+    return cache;
+  }
+  return new InMemoryCimdCache(config);
+}
 var InMemoryCimdCache;
 var init_cimd_cache = __esm({
   "libs/auth/src/cimd/cimd.cache.ts"() {
@@ -620,6 +877,7 @@ var TRANSPARENT_JWT_ALGS = [
 ];
 var MAX_JWKS_FETCH_BYTES = 1048576;
 var MAX_JWKS_FETCH_HOPS = 3;
+var UNKNOWN_KID_REFETCH_COOLDOWN_MS = 6e4;
 var MISSING_EXP_ERROR = 'missing required "exp" claim';
 function isMissingExpError(error) {
   if (typeof error !== "object" || error === null) return false;
@@ -640,6 +898,8 @@ var JwksService = class {
   orchestratorKey;
   // Provider JWKS cache (providerId -> jwks + fetchedAt)
   providerJwks = /* @__PURE__ */ new Map();
+  // The last key refetch an unknown `kid` started, per provider (see refetchForUnknownKid)
+  unknownKidRefetches = /* @__PURE__ */ new Map();
   // Track if key has been initialized (for async loading)
   keyInitialized = false;
   // Promise guard to prevent concurrent key generation
@@ -700,6 +960,9 @@ var JwksService = class {
       let jwks;
       try {
         jwks = await this.getJwksForProvider(p);
+        if (kid && !p.jwks?.keys?.length && !jwks?.keys?.some((key) => key.kid === kid)) {
+          jwks = await this.refetchForUnknownKid(p) ?? jwks;
+        }
         if (!jwks?.keys?.length) continue;
         const JWKS = createLocalJWKSet(jwks);
         const issuerConstraint = this.issuerConstraintFor(p);
@@ -882,6 +1145,35 @@ var JwksService = class {
     if (cached && Date.now() - cached.fetchedAt < this.opts.providerJwksTtlMs) {
       return cached.jwks;
     }
+    const fetched = await this.fetchProviderJwks(ref);
+    if (fetched) return fetched;
+    const maxStaleMs = Math.max(this.opts.providerJwksTtlMs * 4, 6e4);
+    if (cached && Date.now() - cached.fetchedAt < maxStaleMs) {
+      return cached.jwks;
+    }
+    return void 0;
+  }
+  /**
+   * Fetch a provider's keys again for a token whose `kid` the cached keys don't have (a key the
+   * provider started using since), ahead of the cache's TTL. At most one refetch per provider per
+   * {@link UNKNOWN_KID_REFETCH_COOLDOWN_MS}: tokens that arrive meanwhile wait for the one in flight or
+   * use its result, so a flood of tokens with made-up `kid`s can't hammer the provider. Only freshly
+   * fetched keys are returned: a failed refetch never revives cached keys past the stale window.
+   */
+  refetchForUnknownKid(ref) {
+    let refetch = this.unknownKidRefetches.get(ref.id);
+    if (!refetch || Date.now() - refetch.startedAt >= UNKNOWN_KID_REFETCH_COOLDOWN_MS) {
+      refetch = { startedAt: Date.now(), done: this.fetchProviderJwks(ref) };
+      this.unknownKidRefetches.set(ref.id, refetch);
+    }
+    return refetch.done;
+  }
+  /**
+   * Fetch a provider's keys, and cache them: from `jwksUri`, else the conventional location, else
+   * the `jwks_uri` of the issuer's OAuth or OpenID metadata. Every URL goes through the same scheme
+   * and SSRF checks (`fetchJson`), `jwks_uri` included.
+   */
+  async fetchProviderJwks(ref) {
     if (ref.jwksUri) {
       const fromUri = await this.tryFetchJwks(ref.id, ref.jwksUri);
       if (fromUri?.keys?.length) return fromUri;
@@ -897,10 +1189,6 @@ var JwksService = class {
         if (fromMeta?.keys?.length) return fromMeta;
       }
     }
-    const maxStaleMs = Math.max(this.opts.providerJwksTtlMs * 4, 6e4);
-    if (cached && Date.now() - cached.fetchedAt < maxStaleMs) {
-      return cached.jwks;
-    }
     return void 0;
   }
   // ===========================================================================
@@ -1867,7 +2155,8 @@ function buildRefreshTokenRecord(params) {
     customClaims: params.customClaims,
     federatedLoginUsed: params.federatedLoginUsed,
     selectedProviderIds: params.selectedProviderIds,
-    skippedProviderIds: params.skippedProviderIds
+    skippedProviderIds: params.skippedProviderIds,
+    providerTokensId: params.providerTokensId
   };
 }
 function verifyPkce(codeVerifier, challenge) {
@@ -4885,7 +5174,49 @@ var VercelKvSessionStore = class {
 };
 
 // libs/auth/src/session/orchestrated-token.store.ts
-import { encryptAesGcm as encryptAesGcm4, decryptAesGcm as decryptAesGcm4, randomBytes as randomBytes7, hkdfSha256 as hkdfSha2563 } from "@frontmcp/utils";
+import { decryptAesGcm as decryptAesGcm5, encryptAesGcm as encryptAesGcm5, hkdfSha256 as hkdfSha2564, randomBytes as randomBytes8 } from "@frontmcp/utils";
+
+// libs/auth/src/session/orchestrated-token.crypto.ts
+import { decryptAesGcm as decryptAesGcm4, encryptAesGcm as encryptAesGcm4, hkdfSha256 as hkdfSha2563, randomBytes as randomBytes7 } from "@frontmcp/utils";
+function recordDropAt(record) {
+  if (!record.refreshToken) return record.expiresAt;
+  return Math.max(record.expiresAt ?? 0, record.updatedAt + REFRESH_TOKEN_TTL_MS);
+}
+function hasLiveAccessToken(record, refreshSkewMs = 0) {
+  if (record.expiresAt === void 0) return true;
+  return record.expiresAt - (record.refreshToken ? refreshSkewMs : 0) > Date.now();
+}
+var HKDF_SALT = new TextEncoder().encode("frontmcp-token-store");
+function deriveKeyForRecord(masterKey, compositeKey, cache) {
+  const cached = cache.get(compositeKey);
+  if (cached) {
+    return cached;
+  }
+  const info = new TextEncoder().encode(`orchestrated-token:${compositeKey}`);
+  const derived = hkdfSha2563(masterKey, HKDF_SALT, info, 32);
+  cache.set(compositeKey, derived);
+  return derived;
+}
+function encryptRecord(key, record) {
+  const plaintext = JSON.stringify(record);
+  const iv = randomBytes7(12);
+  const { ciphertext, tag } = encryptAesGcm4(key, new TextEncoder().encode(plaintext), iv);
+  return JSON.stringify({
+    iv: Buffer.from(iv).toString("base64url"),
+    tag: Buffer.from(tag).toString("base64url"),
+    data: Buffer.from(ciphertext).toString("base64url")
+  });
+}
+function decryptRecord(key, encrypted) {
+  const { iv, tag, data } = JSON.parse(encrypted);
+  const ivBytes = Buffer.from(iv, "base64url");
+  const tagBytes = Buffer.from(tag, "base64url");
+  const ciphertextBytes = Buffer.from(data, "base64url");
+  const plaintext = decryptAesGcm4(key, ciphertextBytes, ivBytes, tagBytes);
+  return JSON.parse(new TextDecoder().decode(plaintext));
+}
+
+// libs/auth/src/session/orchestrated-token.store.ts
 var InMemoryOrchestratedTokenStore = class {
   /** Token storage: Map<compositeKey, ProviderTokenRecord> */
   tokens = /* @__PURE__ */ new Map();
@@ -4897,9 +5228,12 @@ var InMemoryOrchestratedTokenStore = class {
   cleanupTimer;
   /** Default TTL for records */
   defaultTtlMs;
+  /** How long before its expiry a refreshable access token stops being returned */
+  refreshSkewMs;
   constructor(options = {}) {
     this.encryptionKey = options.encryptionKey;
     this.defaultTtlMs = options.defaultTtlMs;
+    this.refreshSkewMs = options.refreshSkewMs ?? 0;
     const cleanupIntervalMs = options.cleanupIntervalMs ?? 6e4;
     this.cleanupTimer = setInterval(() => {
       void this.cleanup();
@@ -4927,7 +5261,7 @@ var InMemoryOrchestratedTokenStore = class {
     }
     const info = new TextEncoder().encode(`orchestrated-token:${compositeKey}`);
     const salt = new TextEncoder().encode("frontmcp-token-store");
-    const derivedKey = hkdfSha2563(this.encryptionKey, salt, info, 32);
+    const derivedKey = hkdfSha2564(this.encryptionKey, salt, info, 32);
     this.derivedKeys.set(compositeKey, derivedKey);
     return derivedKey;
   }
@@ -4937,8 +5271,8 @@ var InMemoryOrchestratedTokenStore = class {
   async encryptRecord(compositeKey, record) {
     const key = await this.deriveKeyForRecord(compositeKey);
     const plaintext = JSON.stringify(record);
-    const iv = randomBytes7(12);
-    const { ciphertext, tag } = encryptAesGcm4(key, new TextEncoder().encode(plaintext), iv);
+    const iv = randomBytes8(12);
+    const { ciphertext, tag } = encryptAesGcm5(key, new TextEncoder().encode(plaintext), iv);
     return JSON.stringify({
       iv: Buffer.from(iv).toString("base64url"),
       tag: Buffer.from(tag).toString("base64url"),
@@ -4954,7 +5288,7 @@ var InMemoryOrchestratedTokenStore = class {
     const ivBytes = Buffer.from(iv, "base64url");
     const tagBytes = Buffer.from(tag, "base64url");
     const ciphertextBytes = Buffer.from(data, "base64url");
-    const plaintext = decryptAesGcm4(key, ciphertextBytes, ivBytes, tagBytes);
+    const plaintext = decryptAesGcm5(key, ciphertextBytes, ivBytes, tagBytes);
     return JSON.parse(new TextDecoder().decode(plaintext));
   }
   /**
@@ -4980,18 +5314,20 @@ var InMemoryOrchestratedTokenStore = class {
     } else {
       record = stored;
     }
-    if (record.expiresAt && record.expiresAt < Date.now()) {
+    const dropAt = recordDropAt(record);
+    if (dropAt && dropAt < Date.now()) {
       this.tokens.delete(key);
       return null;
     }
     return record;
   }
   /**
-   * Retrieve decrypted access token for a provider
+   * Retrieve decrypted access token for a provider, or null once it has expired (a record with a
+   * refresh token keeps that, to renew it)
    */
   async getAccessToken(authorizationId, providerId) {
     const record = await this.getRecord(authorizationId, providerId);
-    return record?.accessToken ?? null;
+    return record && hasLiveAccessToken(record, this.refreshSkewMs) ? record.accessToken : null;
   }
   /**
    * Retrieve decrypted refresh token for a provider
@@ -5084,7 +5420,8 @@ var InMemoryOrchestratedTokenStore = class {
       } else {
         record = stored;
       }
-      if (record?.expiresAt && record.expiresAt < now) {
+      const dropAt = record ? recordDropAt(record) : void 0;
+      if (dropAt && dropAt < now) {
         keysToDelete.push(key);
       }
     }
@@ -5124,74 +5461,48 @@ var InMemoryOrchestratedTokenStore = class {
    * @param toAuthId - Target authorization ID (e.g., "def456")
    */
   async migrateTokens(fromAuthId, toAuthId) {
-    const prefix = `${fromAuthId}:`;
-    const keysToMigrate = [];
-    for (const key of this.tokens.keys()) {
-      if (key.startsWith(prefix)) {
-        keysToMigrate.push(key);
-      }
+    for (const oldKey of await this.copyRecords(fromAuthId, toAuthId)) {
+      this.tokens.delete(oldKey);
+      this.derivedKeys.delete(oldKey);
     }
-    for (const oldKey of keysToMigrate) {
-      const providerId = oldKey.slice(prefix.length);
-      const newKey = this.buildKey(toAuthId, providerId);
+  }
+  /**
+   * Copy tokens from one authorization ID to another, keeping them under the source ID too.
+   */
+  async copyTokens(fromAuthId, toAuthId) {
+    await this.copyRecords(fromAuthId, toAuthId);
+  }
+  /** Copy every record of `fromAuthId` to `toAuthId`, skipping a corrupted one; returns the keys copied. */
+  async copyRecords(fromAuthId, toAuthId) {
+    const prefix = `${fromAuthId}:`;
+    const sourceKeys = [...this.tokens.keys()].filter((key) => key.startsWith(prefix));
+    const copiedKeys = [];
+    for (const oldKey of sourceKeys) {
       const stored = this.tokens.get(oldKey);
-      if (!stored) {
-        continue;
-      }
+      if (!stored) continue;
+      const newKey = this.buildKey(toAuthId, oldKey.slice(prefix.length));
       if (this.encryptionKey) {
         try {
           const record = await this.decryptRecord(oldKey, stored);
-          const encrypted = await this.encryptRecord(newKey, record);
-          this.tokens.set(newKey, encrypted);
+          this.tokens.set(newKey, await this.encryptRecord(newKey, record));
         } catch {
           continue;
         }
       } else {
         this.tokens.set(newKey, stored);
       }
-      this.tokens.delete(oldKey);
-      this.derivedKeys.delete(oldKey);
+      copiedKeys.push(oldKey);
     }
+    return copiedKeys;
   }
 };
 
-// libs/auth/src/session/orchestrated-token.crypto.ts
-import { decryptAesGcm as decryptAesGcm5, encryptAesGcm as encryptAesGcm5, hkdfSha256 as hkdfSha2564, randomBytes as randomBytes8 } from "@frontmcp/utils";
-var HKDF_SALT = new TextEncoder().encode("frontmcp-token-store");
-function deriveKeyForRecord(masterKey, compositeKey, cache) {
-  const cached = cache.get(compositeKey);
-  if (cached) {
-    return cached;
-  }
-  const info = new TextEncoder().encode(`orchestrated-token:${compositeKey}`);
-  const derived = hkdfSha2564(masterKey, HKDF_SALT, info, 32);
-  cache.set(compositeKey, derived);
-  return derived;
-}
-function encryptRecord(key, record) {
-  const plaintext = JSON.stringify(record);
-  const iv = randomBytes8(12);
-  const { ciphertext, tag } = encryptAesGcm5(key, new TextEncoder().encode(plaintext), iv);
-  return JSON.stringify({
-    iv: Buffer.from(iv).toString("base64url"),
-    tag: Buffer.from(tag).toString("base64url"),
-    data: Buffer.from(ciphertext).toString("base64url")
-  });
-}
-function decryptRecord(key, encrypted) {
-  const { iv, tag, data } = JSON.parse(encrypted);
-  const ivBytes = Buffer.from(iv, "base64url");
-  const tagBytes = Buffer.from(tag, "base64url");
-  const ciphertextBytes = Buffer.from(data, "base64url");
-  const plaintext = decryptAesGcm5(key, ciphertextBytes, ivBytes, tagBytes);
-  return JSON.parse(new TextDecoder().decode(plaintext));
-}
-
 // libs/auth/src/session/storage-orchestrated-token.store.ts
 var StorageOrchestratedTokenStore = class {
   storage;
   encryptionKey;
   defaultTtlMs;
+  refreshSkewMs;
   namespace;
   storageIsNamespaced;
   /** HKDF-derived subkey cache, keyed by composite key. */
@@ -5199,6 +5510,7 @@ var StorageOrchestratedTokenStore = class {
   constructor(storage, options = {}) {
     this.encryptionKey = options.encryptionKey;
     this.defaultTtlMs = options.defaultTtlMs;
+    this.refreshSkewMs = options.refreshSkewMs ?? 0;
     this.namespace = options.namespace ?? "otok";
     this.storageIsNamespaced = this.isNamespacedStorage(storage);
     this.storage = this.storageIsNamespaced ? storage.namespace(this.namespace) : storage;
@@ -5208,7 +5520,7 @@ var StorageOrchestratedTokenStore = class {
   // ============================================
   async getAccessToken(authorizationId, providerId) {
     const record = await this.getRecord(authorizationId, providerId);
-    return record?.accessToken ?? null;
+    return record && hasLiveAccessToken(record, this.refreshSkewMs) ? record.accessToken : null;
   }
   async getRefreshToken(authorizationId, providerId) {
     const record = await this.getRecord(authorizationId, providerId);
@@ -5225,7 +5537,7 @@ var StorageOrchestratedTokenStore = class {
       updatedAt: now
     };
     const value = this.encryptionKey ? encryptRecord(this.keyFor(compositeKey), record) : JSON.stringify(record);
-    await this.storage.set(this.storageKey(compositeKey), value, this.ttlOptions(record.expiresAt));
+    await this.storage.set(this.storageKey(compositeKey), value, this.ttlOptions(recordDropAt(record)));
   }
   async deleteTokens(authorizationId, providerId) {
     const compositeKey = this.compositeKey(authorizationId, providerId);
@@ -5251,12 +5563,37 @@ var StorageOrchestratedTokenStore = class {
     return providerIds;
   }
   async migrateTokens(fromAuthId, toAuthId) {
+    for (const oldComposite of await this.copyRecords(fromAuthId, toAuthId)) {
+      await this.storage.delete(this.storageKey(oldComposite));
+      this.derivedKeys.delete(oldComposite);
+    }
+  }
+  async copyTokens(fromAuthId, toAuthId) {
+    await this.copyRecords(fromAuthId, toAuthId);
+  }
+  /**
+   * Delete all tokens for an authorization id.
+   */
+  async deleteAllForAuthorization(authorizationId) {
+    const prefix = `${authorizationId}:`;
+    const compositeKeys = await this.listCompositeKeys(`${prefix}*`);
+    for (const compositeKey of compositeKeys) {
+      if (!compositeKey.startsWith(prefix)) continue;
+      await this.storage.delete(this.storageKey(compositeKey));
+      this.derivedKeys.delete(compositeKey);
+    }
+  }
+  // ============================================
+  // Internals
+  // ============================================
+  /** Copy every record of `fromAuthId` to `toAuthId`, skipping a corrupted one; returns the composite keys copied. */
+  async copyRecords(fromAuthId, toAuthId) {
     const prefix = `${fromAuthId}:`;
     const compositeKeys = await this.listCompositeKeys(`${prefix}*`);
+    const copiedKeys = [];
     for (const oldComposite of compositeKeys) {
       if (!oldComposite.startsWith(prefix)) continue;
-      const providerId = oldComposite.slice(prefix.length);
-      const newComposite = this.compositeKey(toAuthId, providerId);
+      const newComposite = this.compositeKey(toAuthId, oldComposite.slice(prefix.length));
       const stored = await this.storage.get(this.storageKey(oldComposite));
       if (stored === null) continue;
       if (this.encryptionKey) {
@@ -5267,35 +5604,20 @@ var StorageOrchestratedTokenStore = class {
           continue;
         }
         const value = encryptRecord(this.keyFor(newComposite), record);
-        await this.storage.set(this.storageKey(newComposite), value, this.ttlOptions(record.expiresAt));
+        await this.storage.set(this.storageKey(newComposite), value, this.ttlOptions(recordDropAt(record)));
       } else {
-        let expiresAt;
+        let dropAt;
         try {
-          expiresAt = JSON.parse(stored).expiresAt;
+          dropAt = recordDropAt(JSON.parse(stored));
         } catch {
-          expiresAt = void 0;
+          dropAt = void 0;
         }
-        await this.storage.set(this.storageKey(newComposite), stored, this.ttlOptions(expiresAt));
+        await this.storage.set(this.storageKey(newComposite), stored, this.ttlOptions(dropAt));
       }
-      await this.storage.delete(this.storageKey(oldComposite));
-      this.derivedKeys.delete(oldComposite);
+      copiedKeys.push(oldComposite);
     }
+    return copiedKeys;
   }
-  /**
-   * Delete all tokens for an authorization id.
-   */
-  async deleteAllForAuthorization(authorizationId) {
-    const prefix = `${authorizationId}:`;
-    const compositeKeys = await this.listCompositeKeys(`${prefix}*`);
-    for (const compositeKey of compositeKeys) {
-      if (!compositeKey.startsWith(prefix)) continue;
-      await this.storage.delete(this.storageKey(compositeKey));
-      this.derivedKeys.delete(compositeKey);
-    }
-  }
-  // ============================================
-  // Internals
-  // ============================================
   async getRecord(authorizationId, providerId) {
     const compositeKey = this.compositeKey(authorizationId, providerId);
     const stored = await this.storage.get(this.storageKey(compositeKey));
@@ -5318,7 +5640,8 @@ var StorageOrchestratedTokenStore = class {
         return null;
       }
     }
-    if (record.expiresAt && record.expiresAt < Date.now()) {
+    const dropAt = recordDropAt(record);
+    if (dropAt && dropAt < Date.now()) {
       await this.storage.delete(this.storageKey(compositeKey));
       return null;
     }
@@ -6770,7 +7093,7 @@ var OrchestratedAuthorization = class _OrchestratedAuthorization extends Authori
     const result = await this.#onTokenRefresh(providerId, refreshToken);
     await this.#tokenStore.storeTokens(this.id, providerId, {
       accessToken: result.accessToken,
-      refreshToken: result.refreshToken,
+      refreshToken: result.refreshToken ?? refreshToken,
       expiresAt: result.expiresIn ? Date.now() + result.expiresIn * 1e3 : void 0
     });
     const currentState = this.#providerStates.get(providerId);
@@ -7539,7 +7862,7 @@ var CimdService = class {
   cacheConfig;
   securityConfig;
   networkConfig;
-  cache;
+  cacheBackend;
   logger;
   /**
    * Whether CIMD is enabled.
@@ -7559,7 +7882,6 @@ var CimdService = class {
     this.cacheConfig = cimdCacheConfigSchema.parse(this.config.cache ?? {});
     this.securityConfig = cimdSecurityConfigSchema.parse(this.config.security ?? {});
     this.networkConfig = cimdNetworkConfigSchema.parse(this.config.network ?? {});
-    this.cache = new InMemoryCimdCache(this.cacheConfig);
     this.logger.debug("CimdService initialized", {
       enabled: this.config.enabled,
       cacheDefaultTtlMs: this.cacheConfig.defaultTtlMs,
@@ -7571,6 +7893,34 @@ var CimdService = class {
       );
     }
   }
+  /**
+   * Create the cache now (connecting to Redis with `cache.type: 'redis'`), so a misconfigured or
+   * unreachable cache fails at startup rather than on the first CIMD client.
+   */
+  async initialize() {
+    await this.cache();
+  }
+  /**
+   * The cache `cache.type` selects, created once through the `createCimdCache` factory. A failed
+   * creation is retried on the next use.
+   */
+  cache() {
+    if (!this.cacheBackend) {
+      this.cacheBackend = createCimdCache(this.cacheConfig).catch((error) => {
+        this.cacheBackend = void 0;
+        throw error;
+      });
+    }
+    return this.cacheBackend;
+  }
+  /** Close the cache's connection (Redis with `cache.type: 'redis'`), if one was created. */
+  async dispose() {
+    const backend = this.cacheBackend;
+    this.cacheBackend = void 0;
+    if (!backend) return;
+    const createdBackend = await backend.catch(() => void 0);
+    await createdBackend?.close?.();
+  }
   /**
    * Check if a client_id is a CIMD URL.
    *
@@ -7597,7 +7947,8 @@ var CimdService = class {
       };
     }
     validateClientIdUrl(clientId, this.securityConfig);
-    const cached = await this.cache.get(clientId);
+    const cache = await this.cache();
+    const cached = await cache.get(clientId);
     if (cached) {
       this.logger.debug(`Cache hit for CIMD client: ${clientId}`);
       return {
@@ -7615,8 +7966,8 @@ var CimdService = class {
     if (this.securityConfig.warnOnLocalhostRedirects && hasOnlyLocalhostRedirectUris(document.redirect_uris)) {
       this.logger.warn(`CIMD client "${clientId}" has only localhost redirect URIs - this may be a development client`);
     }
-    await this.cache.set(clientId, document, headers);
-    const entry = await this.cache.get(clientId);
+    await cache.set(clientId, document, headers);
+    const entry = await cache.get(clientId);
     return {
       isCimdClient: true,
       metadata: document,
@@ -7646,11 +7997,12 @@ var CimdService = class {
    * @param clientId - Optional client_id to clear; clears all if not provided
    */
   async clearCache(clientId) {
+    const cache = await this.cache();
     if (clientId) {
-      await this.cache.delete(clientId);
+      await cache.delete(clientId);
       this.logger.debug(`Cache cleared for: ${clientId}`);
     } else {
-      await this.cache.clear();
+      await cache.clear();
       this.logger.debug("Cache cleared");
     }
   }
@@ -7658,8 +8010,9 @@ var CimdService = class {
    * Get cache statistics.
    */
   async getCacheStats() {
+    const cache = await this.cache();
     return {
-      size: await this.cache.size()
+      size: await cache.size()
     };
   }
   /**
@@ -7671,7 +8024,8 @@ var CimdService = class {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), this.networkConfig.timeoutMs);
     try {
-      const conditionalHeaders = await this.cache.getConditionalHeaders(clientId);
+      const cache = await this.cache();
+      const conditionalHeaders = await cache.getConditionalHeaders(clientId);
       const originalOrigin = new URL(clientId).origin;
       const maxRedirects = this.networkConfig.maxRedirects;
       let currentUrl = clientId;
@@ -7694,9 +8048,9 @@ var CimdService = class {
           redirect: "manual"
         });
         if (response.status === 304) {
-          const staleEntry = await this.cache.getStale(clientId);
+          const staleEntry = await cache.getStale(clientId);
           if (staleEntry) {
-            await this.cache.revalidate(clientId, response.headers);
+            await cache.revalidate(clientId, response.headers);
             this.logger.debug(`CIMD document not modified: ${clientId}`);
             return {
               document: staleEntry.document,
@@ -8204,7 +8558,7 @@ var tokenRefreshConfigSchema = z10.object({
    * Refresh token before expiry by this many seconds
    * @default 60
    */
-  skewSeconds: z10.number().default(60)
+  skewSeconds: z10.number().nonnegative().default(60)
 });
 var skippedAppBehaviorSchema = z10.enum(["anonymous", "require-auth"]);
 var consentConfigSchema = z10.object({
@@ -8317,7 +8671,7 @@ var publicAuthOptionsSchema = z11.object({
    * Anonymous session TTL in seconds
    * @default 3600 (1 hour)
    */
-  sessionTtl: z11.number().default(3600),
+  sessionTtl: z11.number().int().positive().default(3600),
   /**
    * Scopes granted to anonymous sessions
    * @default ['anonymous']