@frontmcp/auth 1.9.1 → 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);
@@ -867,7 +1130,8 @@ var JwksService = class {
    *   1) inline jwks (if provided) → cache & return
    *   2) cached & fresh (TTL)      → return
    *   3) explicit jwksUri          → fetch, cache, return
-   *   4) discover jwks_uri         → the issuer's OAuth authorization server
+   *   4) `<issuer>/.well-known/jwks.json` → fetch, cache, return
+   *   5) discover jwks_uri         → the issuer's OAuth authorization server
    *      metadata (RFC 8414), else its OpenID configuration (OpenID Connect
    *      Discovery 1.0 §4, where Google, Okta, Auth0 and Entra publish it),
    *      then fetch jwks_uri, cache, return
@@ -881,11 +1145,42 @@ 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;
     }
     const issuer = trimSlash(ref.issuerUrl);
+    const fromWellKnown = await this.tryFetchJwks(ref.id, `${issuer}/.well-known/jwks.json`);
+    if (fromWellKnown?.keys?.length) return fromWellKnown;
     for (const document of ["oauth-authorization-server", "openid-configuration"]) {
       const meta = await this.tryFetchAsMeta(`${issuer}/.well-known/${document}`);
       const uri = meta && typeof meta === "object" && meta["jwks_uri"] ? String(meta["jwks_uri"]) : void 0;
@@ -894,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;
   }
   // ===========================================================================
@@ -1864,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) {
@@ -3935,7 +4227,8 @@ function deriveTypedUser(claims) {
     ...claims,
     iss: extractClaimValue(claims, "iss", isString) ?? "",
     sid: extractClaimValue(claims, "sid", isString),
-    sub: extractClaimValue(claims, "sub", isString) ?? "",
+    // RFC 9068 §2.2: a client-credentials token names the client as its subject; some IdPs only put it in client_id / azp
+    sub: extractClaimValue(claims, "sub", isString) ?? extractClaimValue(claims, "client_id", isString) ?? extractClaimValue(claims, "azp", isString) ?? "",
     exp: extractClaimValue(claims, "exp", isNumber),
     iat: extractClaimValue(claims, "iat", isNumber),
     aud: extractClaimValue(claims, "aud", isStringOrStringArray),
@@ -4881,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();
@@ -4893,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();
@@ -4923,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;
   }
@@ -4933,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"),
@@ -4950,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));
   }
   /**
@@ -4976,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
@@ -5080,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);
       }
     }
@@ -5120,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. */
@@ -5195,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;
@@ -5204,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);
@@ -5221,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);
@@ -5247,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) {
@@ -5263,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);
-    }
-  }
-  /**
-   * 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));
@@ -5314,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;
     }
@@ -6766,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);
@@ -7535,7 +7862,7 @@ var CimdService = class {
   cacheConfig;
   securityConfig;
   networkConfig;
-  cache;
+  cacheBackend;
   logger;
   /**
    * Whether CIMD is enabled.
@@ -7555,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,
@@ -7567,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.
    *
@@ -7593,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 {
@@ -7611,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,
@@ -7642,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");
     }
   }
@@ -7654,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()
     };
   }
   /**
@@ -7667,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;
@@ -7690,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,
@@ -8200,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({
@@ -8313,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']
@@ -8760,9 +9118,17 @@ function detectAuthProviders(parentAuth, apps) {
       `Invalid auth configuration: Parent uses transparent mode but apps have their own auth providers. Transparent mode passes tokens through without modification, which is incompatible with multi-provider setups. Change parent auth to local or remote mode to properly manage tokens for each provider. Detected providers: ${[...providers.keys()].join(", ")}`
     );
   }
-  if (uniqueProviderCount > 1 && parentAuth && isPublicMode(parentAuth)) {
-    warnings.push(
-      `Parent uses public mode but apps have auth providers configured. App-level auth will be used, but consider using local or remote mode at parent for unified auth management.`
+  const sharedEndpointUnenforced = !parentAuth || isPublicMode(parentAuth) || isStaticMode(parentAuth);
+  const unenforcedAppIds = apps.filter((app) => app.auth && !isPublicMode(app.auth) && !staticParentEnforces(parentAuth, app.auth)).map((app) => app.id);
+  if (sharedEndpointUnenforced && unenforcedAppIds.length > 0) {
+    validationErrors.push(
+      `App-level auth is not enforced on the shared endpoint of a server in ${parentAuth?.mode ?? "public"} mode, so the tools of ${unenforcedAppIds.join(", ")} would be served without it. Serve the app on its own endpoint with standalone: true or splitByApp: true, or run the server in local or remote mode with incrementalAuth enabled, which checks each tool call against the apps the caller has authorized (without incrementalAuth, local and remote mode do not check app grants per tool call).`
+    );
+  }
+  const tokenMintingAppIds = apps.filter((app) => app.remoteAuthMode === "forward" && !(parentAuth && isTransparentMode(parentAuth))).map((app) => app.id);
+  if (tokenMintingAppIds.length > 0) {
+    validationErrors.push(
+      `remoteAuth: { mode: 'forward' } on ${tokenMintingAppIds.join(", ")} would send the remote a token this server minted or holds itself: only a server in transparent mode receives its callers' tokens from the identity provider. Use remoteAuth: { mode: 'static', credentials } (or transportOptions.headers) for the remote, or run the server in transparent mode.`
     );
   }
   return {
@@ -8775,6 +9141,14 @@ function detectAuthProviders(parentAuth, apps) {
     warnings
   };
 }
+function staticParentEnforces(parentAuth, appAuth) {
+  if (!parentAuth || !isStaticMode(parentAuth) || !isStaticMode(appAuth)) return false;
+  const parent = staticAuthOptionsSchema.safeParse(parentAuth);
+  const app = staticAuthOptionsSchema.safeParse(appAuth);
+  if (!parent.success || !app.success) return false;
+  const sameChallenge = parent.data.header.toLowerCase() === app.data.header.toLowerCase() && parent.data.scheme === app.data.scheme;
+  return sameChallenge && parent.data.tokens.every((token) => app.data.tokens.includes(token));
+}
 function getProviderUrl(options) {
   if (isTransparentMode(options)) {
     return options.provider;
@@ -9115,6 +9489,16 @@ function isLoopbackRedirectUri(uri) {
   return false;
 }
 
+// libs/auth/src/utils/token-scopes.utils.ts
+function scopesFromClaims(claims) {
+  const scopes = [claims?.scope, claims?.scp].flatMap((claim) => {
+    if (typeof claim === "string") return claim.split(/\s+/).filter(Boolean);
+    if (Array.isArray(claim)) return claim.filter((scope) => typeof scope === "string");
+    return [];
+  });
+  return [...new Set(scopes)];
+}
+
 // libs/auth/src/vault/auth-providers.types.ts
 import { z as z19 } from "@frontmcp/lazy-zod";
 var credentialScopeSchema = z19.enum(["global", "user", "session"]);
@@ -10132,6 +10516,7 @@ var LazyCredentialLoader = class {
 };
 
 // libs/auth/src/authorities/authorities.context.ts
+import { getEnv as getEnv4 } from "@frontmcp/utils";
 function resolveDotPath(obj, path) {
   if (path in obj) {
     return obj[path];
@@ -10172,6 +10557,10 @@ function signedInSubject(rawSub, mappedSub) {
   if (rawSub !== void 0 && isAnonymousSubject(rawSub)) return void 0;
   return [mappedSub, rawSub].find((candidate) => !isAnonymousSubject(candidate));
 }
+var runtimeEnv = new Proxy(
+  {},
+  { get: (_target, name) => typeof name === "string" ? getEnv4(name) : void 0 }
+);
 var AuthoritiesContextBuilder = class {
   claimsMapping;
   claimsResolver;
@@ -10184,7 +10573,7 @@ var AuthoritiesContextBuilder = class {
   /**
    * Build an evaluation context from AuthInfo and tool input.
    */
-  build(authInfo, input = {}, env = {}) {
+  build(authInfo, input = {}, env = runtimeEnv) {
     if (this.claimsResolver) {
       const resolved = this.claimsResolver(authInfo);
       return {
@@ -10254,9 +10643,9 @@ var FrontMcpAuthContextImpl = class {
   claims;
   roles;
   permissions;
-  constructor(source, claimsMapping) {
+  constructor(source, claimsMapping, claimsResolver) {
     const rawUser = resolveAuthUser(source);
-    const mappedSub = claimsMapping?.userId ? resolveDotPath(this.buildRawClaims(source), claimsMapping.userId) : void 0;
+    const mappedSub = !claimsResolver && claimsMapping?.userId ? resolveDotPath(this.buildRawClaims(source), claimsMapping.userId) : void 0;
     const signedInSub = signedInSubject(rawUser.sub, mappedSub);
     const sub = signedInSub ?? (typeof rawUser.sub === "string" ? rawUser.sub : "");
     this.user = Object.freeze({
@@ -10274,6 +10663,13 @@ var FrontMcpAuthContextImpl = class {
     this.scopes = Object.freeze(
       Array.isArray(source.scopes) ? source.scopes.filter((s) => typeof s === "string") : []
     );
+    if (claimsResolver) {
+      const resolved = claimsResolver(source);
+      this.claims = Object.freeze({ ...resolved.claims });
+      this.roles = Object.freeze([...toStringArray2(resolved.roles)]);
+      this.permissions = Object.freeze([...toStringArray2(resolved.permissions)]);
+      return;
+    }
     const rawClaims = this.buildRawClaims(source);
     this.claims = Object.freeze({ ...rawClaims });
     if (claimsMapping?.roles) {
@@ -10334,8 +10730,8 @@ var FrontMcpAuthContextImpl = class {
 };
 
 // libs/auth/src/context/frontmcp-auth-context.factory.ts
-function buildAuthContext(authInfo, claimsMapping, pipes) {
-  const base = new FrontMcpAuthContextImpl(authInfo, claimsMapping);
+function buildAuthContext(authInfo, claimsMapping, pipes, claimsResolver) {
+  const base = new FrontMcpAuthContextImpl(authInfo, claimsMapping, claimsResolver);
   if (!pipes || pipes.length === 0) {
     return base;
   }
@@ -10587,6 +10983,10 @@ function evaluateCondition(condition, envelope, ctx) {
   const expected = resolveValue(condition.value, ctx);
   return applyOperator(actual, condition.op, expected);
 }
+var REDACTED_ENV_VALUE = "[redacted]";
+function reportableActual(path, actual) {
+  return path === "env" || path.startsWith("env.") ? REDACTED_ENV_VALUE : actual;
+}
 function evaluateAbac(policy, ctx) {
   const envelope = buildContextEnvelope(ctx);
   if (policy.match) {
@@ -10594,10 +10994,11 @@ function evaluateAbac(policy, ctx) {
       const actual = resolveDotPath(envelope, path);
       const expected = resolveValue(expectedRaw, ctx);
       if (expected === void 0 || actual !== expected) {
+        const reported = reportableActual(path, actual);
         return {
           granted: false,
-          deniedBy: `attributes.match: '${path}' expected '${String(expected)}' but got '${String(actual)}'`,
-          denial: { kind: "attributes", path: "attributes.match", expected, actual },
+          deniedBy: `attributes.match: '${path}' expected '${String(expected)}' but got '${String(reported)}'`,
+          denial: { kind: "attributes", path: "attributes.match", expected, actual: reported },
           evaluatedPolicies: ["attributes.match"]
         };
       }
@@ -10608,7 +11009,7 @@ function evaluateAbac(policy, ctx) {
       const condition = policy.conditions[i];
       if (!evaluateCondition(condition, envelope, ctx)) {
         const expected = resolveValue(condition.value, ctx);
-        const actual = resolveDotPath(envelope, condition.path);
+        const actual = reportableActual(condition.path, resolveDotPath(envelope, condition.path));
         return {
           granted: false,
           deniedBy: `attributes.conditions: '${condition.path}' failed '${condition.op}' check against '${String(expected)}'`,
@@ -11347,6 +11748,21 @@ var basicApplier = {
 function isFrontMcpCredentials(creds) {
   return typeof creds === "object" && creds !== null && "provider" in creds && typeof creds.provider === "string" && creds.provider.length > 0;
 }
+function providerHeadersCredentials(resolveHeaders) {
+  return {
+    async applyCredentials(_url, init) {
+      const { credentials, ...cleanInit } = init;
+      if (!isFrontMcpCredentials(credentials)) {
+        return { init: typeof credentials === "string" ? init : cleanInit };
+      }
+      const headers = new Headers(cleanInit.headers);
+      for (const [name, value] of Object.entries(await resolveHeaders(credentials.provider))) {
+        headers.set(name, value);
+      }
+      return { init: { ...cleanInit, headers } };
+    }
+  };
+}
 var FetchCredentialMiddleware = class {
   constructor(tokenAccessor, appliers) {
     this.tokenAccessor = tokenAccessor;
@@ -11647,6 +12063,7 @@ export {
   privateKeyCredentialSchema,
   progressiveAuthStateSchema,
   providerConfigSchema,
+  providerHeadersCredentials,
   publicAccessConfigSchema,
   publicAuthOptionsSchema,
   queryApplier,
@@ -11664,6 +12081,7 @@ export {
   resourceIdRefSchema,
   resourceScopesFor,
   safeDecrypt,
+  scopesFromClaims,
   sealPendingLogin,
   secureStoreConfigSchema,
   secureStoreCustomBackendSchema,