@xenterprises/fastify-xauth-jwks 1.0.0

package/CACHING.md

@@ -0,0 +1,282 @@
+# xAuthJWSK Caching Documentation
+
+xAuthJWSK implements intelligent two-level caching for optimal performance:
+
+## 1. JWKS Caching (Automatic)
+
+JWKS endpoints are cached by the `jose` library to reduce external API calls.
+
+### Configuration
+
+```javascript
+{
+  paths: {
+    admin: {
+      pathPattern: "/admin",
+      jwksUrl: "https://your-auth.com/.well-known/jwks.json",
+      // JWKS caching configuration
+      jwksCooldownDuration: 30000,    // 30 seconds (default)
+      jwksCacheMaxAge: 1800000,       // 30 minutes (default)
+    }
+  }
+}
+```
+
+### Parameters
+
+- **`jwksCooldownDuration`** (ms): Minimum time between JWKS endpoint refetches
+  - Default: 30 seconds
+  - Use case: Prevents hammering the JWKS endpoint if validation fails
+
+- **`jwksCacheMaxAge`** (ms): Maximum time to cache JWKS keys
+  - Default: 30 minutes (1800000ms)
+  - Use case: Balance between freshness and performance
+
+### Example: High-Traffic Setup
+
+```javascript
+{
+  paths: {
+    api: {
+      pathPattern: "/api",
+      jwksUrl: "https://your-auth.com/.well-known/jwks.json",
+      jwksCooldownDuration: 60000,    // 1 minute
+      jwksCacheMaxAge: 3600000,       // 1 hour
+    }
+  }
+}
+```
+
+## 2. JWT Payload Caching (Optional)
+
+JWT payloads are optionally cached to avoid redundant verification of the same token.
+
+### Configuration
+
+```javascript
+{
+  paths: {
+    admin: {
+      pathPattern: "/admin",
+      jwksUrl: "https://your-auth.com/.well-known/jwks.json",
+      // JWT payload caching configuration
+      enablePayloadCache: true,       // enabled by default
+      payloadCacheTTL: 300000,        // 5 minutes (default)
+    }
+  }
+}
+```
+
+### Parameters
+
+- **`enablePayloadCache`** (boolean): Enable/disable JWT payload caching
+  - Default: `true`
+  - Use case: Set to `false` for maximum freshness or if tokens change frequently
+
+- **`payloadCacheTTL`** (ms): Time to live for cached JWT payloads
+  - Default: 5 minutes (300000ms)
+  - Must be shorter than or equal to JWT token expiration
+  - Use case: Tokens are typically short-lived (15 mins), so 5-10 mins is ideal
+
+### Example: High-Security Setup
+
+```javascript
+{
+  paths: {
+    admin: {
+      pathPattern: "/admin",
+      jwksUrl: "https://your-auth.com/.well-known/jwks.json",
+      enablePayloadCache: true,
+      payloadCacheTTL: 60000,        // 1 minute (very fresh)
+    }
+  }
+}
+```
+
+## 3. Cache Management
+
+Each validator exposes cache management methods:
+
+### Get Cache Statistics
+
+```javascript
+const validator = fastify.xAuth.validators.admin;
+const stats = validator.getPayloadCacheStats();
+
+console.log(stats);
+// {
+//   size: 42,                    // number of cached tokens
+//   enabled: true,               // cache enabled?
+//   ttl: 300000                  // cache TTL in ms
+// }
+```
+
+### Clear Cache Manually
+
+```javascript
+const validator = fastify.xAuth.validators.admin;
+validator.clearPayloadCache();  // clears all cached payloads
+```
+
+### Access Configuration
+
+```javascript
+const validator = fastify.xAuth.validators.admin;
+console.log(validator.config);
+// {
+//   jwksCooldownDuration: 30000,
+//   jwksCacheMaxAge: 1800000,
+//   enablePayloadCache: true,
+//   payloadCacheTTL: 300000
+// }
+```
+
+## Performance Recommendations
+
+### High-Traffic Applications (>1000 req/s)
+
+```javascript
+{
+  paths: {
+    api: {
+      pathPattern: "/api",
+      jwksUrl: "https://your-auth.com/.well-known/jwks.json",
+      // Aggressive caching
+      jwksCooldownDuration: 60000,    // 1 minute
+      jwksCacheMaxAge: 3600000,       // 1 hour
+      enablePayloadCache: true,
+      payloadCacheTTL: 600000,        // 10 minutes
+    }
+  }
+}
+```
+
+**Expected impact:**
+- JWKS requests: ~60-100 per day (instead of per second)
+- Token verifications: Cached payloads skip signature verification
+- Latency: ~1ms cached vs ~10-50ms uncached
+
+### Medium-Traffic Applications (100-1000 req/s)
+
+```javascript
+{
+  paths: {
+    api: {
+      pathPattern: "/api",
+      jwksUrl: "https://your-auth.com/.well-known/jwks.json",
+      // Balanced caching (recommended defaults)
+      jwksCooldownDuration: 30000,    // 30 seconds
+      jwksCacheMaxAge: 1800000,       // 30 minutes
+      enablePayloadCache: true,
+      payloadCacheTTL: 300000,        // 5 minutes
+    }
+  }
+}
+```
+
+### Low-Traffic / High-Security (< 100 req/s)
+
+```javascript
+{
+  paths: {
+    admin: {
+      pathPattern: "/admin",
+      jwksUrl: "https://your-auth.com/.well-known/jwks.json",
+      // Minimal caching for fresh tokens
+      jwksCooldownDuration: 10000,    // 10 seconds
+      jwksCacheMaxAge: 300000,        // 5 minutes
+      enablePayloadCache: true,
+      payloadCacheTTL: 60000,         // 1 minute
+    }
+  }
+}
+```
+
+## Cache Invalidation
+
+### Automatic TTL Expiration
+
+Cached payloads automatically expire after `payloadCacheTTL` milliseconds. Expired entries are removed on next access.
+
+### Manual Invalidation
+
+Clear cache when you need to force token re-verification:
+
+```javascript
+// Clear specific path cache
+fastify.xAuth.validators.admin.clearPayloadCache();
+
+// Clear all path caches
+for (const validator of Object.values(fastify.xAuth.validators)) {
+  validator.clearPayloadCache();
+}
+```
+
+## Monitoring
+
+Monitor cache effectiveness:
+
+```javascript
+const monitorCache = () => {
+  for (const [name, validator] of Object.entries(fastify.xAuth.validators)) {
+    const stats = validator.getPayloadCacheStats();
+    console.log(`${name}: ${stats.size} cached tokens`);
+  }
+};
+
+// Check every minute
+setInterval(monitorCache, 60000);
+```
+
+## Troubleshooting
+
+### Tokens not being validated immediately
+
+If token permissions change, the cache may still return old payloads. Solution:
+
+1. Reduce `payloadCacheTTL` to match permission change frequency
+2. Manually clear cache when permissions update: `clearPayloadCache()`
+3. Disable cache if updates are very frequent: `enablePayloadCache: false`
+
+### JWKS endpoint being hammered
+
+If seeing many requests to JWKS endpoint:
+
+1. Increase `jwksCacheMaxAge` (max 1 hour recommended)
+2. Increase `jwksCooldownDuration` (min 30 seconds)
+3. Ensure JWKS endpoint is returning proper Cache-Control headers
+
+### Memory growth
+
+Large `payloadCache` size indicates many unique tokens. Solutions:
+
+1. Reduce `payloadCacheTTL` to expire entries faster
+2. Disable cache: `enablePayloadCache: false`
+3. Manually clear periodically: `validator.clearPayloadCache()`
+
+## Best Practices
+
+1. **Match TTL to token lifetime**: If tokens live 15 minutes, cache should be 5-10 minutes
+2. **Monitor cache size**: Watch for memory growth in `getPayloadCacheStats()`
+3. **Test in production**: Verify cache hit rates work for your traffic patterns
+4. **Clear on deployments**: Reset cache when deploying auth changes
+5. **Use defaults**: The defaults are optimized for most use cases
+
+## Technical Details
+
+### JWKS Cache
+
+- Implemented by `jose.createRemoteJWKSet()`
+- Automatically fetches new keys if current key ID not found
+- Respects HTTP cache headers from endpoint
+
+### Payload Cache
+
+- Simple Map-based LRU-like cache (expires by TTL)
+- Token string is the cache key
+- Stores full JWT payload + expiration timestamp
+- Automatic cleanup on access (lazy deletion)
+
+### No External Dependencies
+
+All caching is built-in using standard JavaScript Map and timers. No external cache library required.