@frontmcp/auth 1.9.2 → 1.9.4

package/index.js

@@ -25,6 +25,245 @@ var __copyProps = (to, from, except, desc) => {
 };
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
+// libs/auth/src/cimd/cimd-redis.cache.ts
+var cimd_redis_cache_exports = {};
+__export(cimd_redis_cache_exports, {
+  RedisCimdCache: () => RedisCimdCache
+});
+var import_utils43, import_utils44, RedisCimdCache;
+var init_cimd_redis_cache = __esm({
+  "libs/auth/src/cimd/cimd-redis.cache.ts"() {
+    "use strict";
+    import_utils43 = require("@frontmcp/utils");
+    import_utils44 = require("@frontmcp/utils");
+    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 import_utils43.RedisStorageAdapter(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 = (0, import_utils44.sha256Hex)(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) {
   return {
@@ -90,6 +329,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"() {
@@ -962,6 +1214,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;
@@ -982,6 +1235,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
@@ -1042,6 +1297,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 = (0, import_jose.createLocalJWKSet)(jwks);
         const issuerConstraint = this.issuerConstraintFor(p);
@@ -1224,6 +1482,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;
@@ -1239,10 +1526,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;
   }
   // ===========================================================================
@@ -2209,7 +2492,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) {
@@ -5200,7 +5484,49 @@ var VercelKvSessionStore = class {
 };
 
 // libs/auth/src/session/orchestrated-token.store.ts
+var import_utils30 = require("@frontmcp/utils");
+
+// libs/auth/src/session/orchestrated-token.crypto.ts
 var import_utils29 = require("@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 = (0, import_utils29.hkdfSha256)(masterKey, HKDF_SALT, info, 32);
+  cache.set(compositeKey, derived);
+  return derived;
+}
+function encryptRecord(key, record) {
+  const plaintext = JSON.stringify(record);
+  const iv = (0, import_utils29.randomBytes)(12);
+  const { ciphertext, tag } = (0, import_utils29.encryptAesGcm)(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 = (0, import_utils29.decryptAesGcm)(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();
@@ -5212,9 +5538,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();
@@ -5242,7 +5571,7 @@ var InMemoryOrchestratedTokenStore = class {
     }
     const info = new TextEncoder().encode(`orchestrated-token:${compositeKey}`);
     const salt = new TextEncoder().encode("frontmcp-token-store");
-    const derivedKey = (0, import_utils29.hkdfSha256)(this.encryptionKey, salt, info, 32);
+    const derivedKey = (0, import_utils30.hkdfSha256)(this.encryptionKey, salt, info, 32);
     this.derivedKeys.set(compositeKey, derivedKey);
     return derivedKey;
   }
@@ -5252,8 +5581,8 @@ var InMemoryOrchestratedTokenStore = class {
   async encryptRecord(compositeKey, record) {
     const key = await this.deriveKeyForRecord(compositeKey);
     const plaintext = JSON.stringify(record);
-    const iv = (0, import_utils29.randomBytes)(12);
-    const { ciphertext, tag } = (0, import_utils29.encryptAesGcm)(key, new TextEncoder().encode(plaintext), iv);
+    const iv = (0, import_utils30.randomBytes)(12);
+    const { ciphertext, tag } = (0, import_utils30.encryptAesGcm)(key, new TextEncoder().encode(plaintext), iv);
     return JSON.stringify({
       iv: Buffer.from(iv).toString("base64url"),
       tag: Buffer.from(tag).toString("base64url"),
@@ -5269,7 +5598,7 @@ var InMemoryOrchestratedTokenStore = class {
     const ivBytes = Buffer.from(iv, "base64url");
     const tagBytes = Buffer.from(tag, "base64url");
     const ciphertextBytes = Buffer.from(data, "base64url");
-    const plaintext = (0, import_utils29.decryptAesGcm)(key, ciphertextBytes, ivBytes, tagBytes);
+    const plaintext = (0, import_utils30.decryptAesGcm)(key, ciphertextBytes, ivBytes, tagBytes);
     return JSON.parse(new TextDecoder().decode(plaintext));
   }
   /**
@@ -5295,18 +5624,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
@@ -5399,7 +5730,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);
       }
     }
@@ -5439,74 +5771,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
-var import_utils30 = require("@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 = (0, import_utils30.hkdfSha256)(masterKey, HKDF_SALT, info, 32);
-  cache.set(compositeKey, derived);
-  return derived;
-}
-function encryptRecord(key, record) {
-  const plaintext = JSON.stringify(record);
-  const iv = (0, import_utils30.randomBytes)(12);
-  const { ciphertext, tag } = (0, import_utils30.encryptAesGcm)(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 = (0, import_utils30.decryptAesGcm)(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. */
@@ -5514,6 +5820,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;
@@ -5523,7 +5830,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);
@@ -5540,7 +5847,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);
@@ -5566,12 +5873,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) {
@@ -5582,35 +5914,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);
-    }
-  }
-  /**
-   * 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);
+      copiedKeys.push(oldComposite);
     }
+    return copiedKeys;
   }
-  // ============================================
-  // Internals
-  // ============================================
   async getRecord(authorizationId, providerId) {
     const compositeKey = this.compositeKey(authorizationId, providerId);
     const stored = await this.storage.get(this.storageKey(compositeKey));
@@ -5633,7 +5950,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;
     }
@@ -7085,7 +7403,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);
@@ -7847,14 +8165,14 @@ var cimdConfigSchema = import_lazy_zod9.z.object({
 init_cimd_cache();
 
 // libs/auth/src/cimd/cimd.service.ts
-var import_utils43 = require("@frontmcp/utils");
+var import_utils45 = require("@frontmcp/utils");
 init_cimd_cache();
 var CimdService = class {
   config;
   cacheConfig;
   securityConfig;
   networkConfig;
-  cache;
+  cacheBackend;
   logger;
   /**
    * Whether CIMD is enabled.
@@ -7874,7 +8192,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,
@@ -7886,6 +8203,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.
    *
@@ -7912,7 +8257,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 {
@@ -7930,8 +8276,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,
@@ -7961,11 +8307,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");
     }
   }
@@ -7973,8 +8320,9 @@ var CimdService = class {
    * Get cache statistics.
    */
   async getCacheStats() {
+    const cache = await this.cache();
     return {
-      size: await this.cache.size()
+      size: await cache.size()
     };
   }
   /**
@@ -7986,7 +8334,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;
@@ -8009,9 +8358,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,
@@ -8022,7 +8371,7 @@ var CimdService = class {
             httpStatus: 304
           });
         }
-        if ((0, import_utils43.isRedirectResponse)(response)) {
+        if ((0, import_utils45.isRedirectResponse)(response)) {
           const location = response.headers.get("location");
           if (!location) {
             throw new CimdFetchError(clientId, "Redirect response missing Location header", {
@@ -8519,7 +8868,7 @@ var tokenRefreshConfigSchema = import_lazy_zod10.z.object({
    * Refresh token before expiry by this many seconds
    * @default 60
    */
-  skewSeconds: import_lazy_zod10.z.number().default(60)
+  skewSeconds: import_lazy_zod10.z.number().nonnegative().default(60)
 });
 var skippedAppBehaviorSchema = import_lazy_zod10.z.enum(["anonymous", "require-auth"]);
 var consentConfigSchema = import_lazy_zod10.z.object({
@@ -8632,7 +8981,7 @@ var publicAuthOptionsSchema = import_lazy_zod11.z.object({
    * Anonymous session TTL in seconds
    * @default 3600 (1 hour)
    */
-  sessionTtl: import_lazy_zod11.z.number().default(3600),
+  sessionTtl: import_lazy_zod11.z.number().int().positive().default(3600),
   /**
    * Scopes granted to anonymous sessions
    * @default ['anonymous']
@@ -9702,7 +10051,7 @@ var CredentialCache = class {
 var AUTH_PROVIDERS_ACCESSOR = /* @__PURE__ */ Symbol.for("frontmcp:AUTH_PROVIDERS_ACCESSOR");
 
 // libs/auth/src/vault/auth-providers.accessor.impl.ts
-var import_utils46 = require("@frontmcp/utils");
+var import_utils48 = require("@frontmcp/utils");
 var AuthProvidersAccessorImpl = class {
   constructor(registry, vault, cache, loader, context, logger) {
     this.registry = registry;
@@ -9917,7 +10266,7 @@ var AuthProvidersAccessorImpl = class {
         return { [credential.headerName]: credential.key };
       case "basic": {
         const value = `${credential.username}:${credential.password}`;
-        const encoded = credential.encodedValue ?? (0, import_utils46.base64Encode)(new TextEncoder().encode(value));
+        const encoded = credential.encodedValue ?? (0, import_utils48.base64Encode)(new TextEncoder().encode(value));
         return { Authorization: `Basic ${encoded}` };
       }
       case "custom":
@@ -10477,7 +10826,7 @@ var LazyCredentialLoader = class {
 };
 
 // libs/auth/src/authorities/authorities.context.ts
-var import_utils47 = require("@frontmcp/utils");
+var import_utils49 = require("@frontmcp/utils");
 function resolveDotPath(obj, path) {
   if (path in obj) {
     return obj[path];
@@ -10520,7 +10869,7 @@ function signedInSubject(rawSub, mappedSub) {
 }
 var runtimeEnv = new Proxy(
   {},
-  { get: (_target, name) => typeof name === "string" ? (0, import_utils47.getEnv)(name) : void 0 }
+  { get: (_target, name) => typeof name === "string" ? (0, import_utils49.getEnv)(name) : void 0 }
 );
 var AuthoritiesContextBuilder = class {
   claimsMapping;
@@ -11625,8 +11974,16 @@ var AuthoritiesEvaluatorRegistry = class {
 };
 
 // libs/auth/src/authorities/authorities.errors.ts
+var import_utils50 = require("@frontmcp/utils");
 var FORBIDDEN_CODE = -32003;
 var AuthorityDeniedError = class extends Error {
+  /**
+   * `instanceof AuthorityDeniedError` also recognises a denial from another copy of this package in the
+   * process, so every copy of `@frontmcp/sdk` answers it as a FORBIDDEN error (#802).
+   */
+  static [Symbol.hasInstance](value) {
+    return (0, import_utils50.isBrandedInstance)(this, value);
+  }
   /** MCP error code for JSON-RPC responses */
   mcpErrorCode = FORBIDDEN_CODE;
   /** HTTP status code equivalent */
@@ -11671,6 +12028,7 @@ var AuthorityDeniedError = class extends Error {
     };
   }
 };
+(0, import_utils50.brandClass)(AuthorityDeniedError, "@frontmcp/auth:AuthorityDeniedError");
 
 // libs/auth/src/fetch/fetch-credential-middleware.ts
 var bearerApplier = {