@xenterprises/fastify-xauth-jwks 1.0.0

package/CONFIGURATION.md

@@ -0,0 +1,545 @@
+# Configuration Reference - xAuthJWSK
+
+Complete guide to all configuration options for path-based JWT/JWKS validation.
+
+## Table of Contents
+
+1. [Plugin Options](#plugin-options)
+2. [Path Configuration](#path-configuration)
+3. [Configuration Examples](#configuration-examples)
+4. [Environment Variables](#environment-variables)
+5. [Production Checklist](#production-checklist)
+
+---
+
+## Plugin Options
+
+The xAuthJWSK plugin accepts a single option object:
+
+```javascript
+await fastify.register(xAuthJWSK, {
+  paths: {
+    // Path configurations go here
+  }
+});
+```
+
+### Root Options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `paths` | `Object` | Yes | Object mapping path names to path configurations |
+
+---
+
+## Path Configuration
+
+Each path in the `paths` object defines a protected route group with its own JWKS provider.
+
+### Basic Structure
+
+```javascript
+paths: {
+  [pathName]: {
+    // Required
+    pathPattern: string,
+    [jwksUrl | jwksData]: one required,
+
+    // Optional
+    active: boolean,
+    excludedPaths: string[],
+    enablePayloadCache: boolean,
+    payloadCacheTTL: number,
+    jwksCacheMaxAge: number,
+    jwksCooldownDuration: number,
+  }
+}
+```
+
+### Configuration Properties
+
+#### `pathPattern` (required, string)
+
+The URL path prefix to protect. All routes matching this pattern will require authentication.
+
+**Examples:**
+```javascript
+pathPattern: "/admin"       // Protects /admin and /admin/*
+pathPattern: "/api/v1"      // Protects /api/v1 and /api/v1/*
+pathPattern: "/portal"      // Protects /portal and /portal/*
+```
+
+#### `jwksUrl` (required*, string)
+
+Remote JWKS endpoint URL for production use. Fetches public keys from a remote server.
+
+**When to use:**
+- Production environments
+- Multi-tenant systems
+- Third-party authentication providers
+- Key rotation needed without server restart
+
+**Example:**
+```javascript
+jwksUrl: "https://auth.example.com/.well-known/jwks.json"
+```
+
+**Note:** Cannot be used simultaneously with `jwksData`. Choose one.
+
+#### `jwksData` (required*, object)
+
+Local JWKS data for development/testing or self-contained services. Can be either:
+1. Full JWKS object: `{ keys: [...] }`
+2. Single JWK key: `{ kty: "RSA", ... }`
+
+**When to use:**
+- Development and local testing
+- Self-contained microservices
+- Both signing and validating tokens
+- Avoiding external dependencies
+
+**Example - Full JWKS:**
+```javascript
+import jwks from './keys.json' assert { type: 'json' };
+
+jwksData: jwks  // { keys: [{...}, {...}] }
+```
+
+**Example - Single JWK (for signing + validation):**
+```javascript
+import { exportJWK, generateKeyPair } from 'jose';
+
+const { publicKey } = await generateKeyPair('RS256');
+const publicJwk = await exportJWK(publicKey);
+
+jwksData: {
+  ...publicJwk,
+  use: 'sig',
+  alg: 'RS256',
+  kid: 'my-key-id'
+}
+```
+
+**Note:** Cannot be used simultaneously with `jwksUrl`. Choose one.
+
+#### `active` (optional, boolean, default: `true`)
+
+Whether this path configuration is active. Set to `false` to disable without removing configuration.
+
+**Example:**
+```javascript
+active: false  // This path won't be registered
+```
+
+#### `excludedPaths` (optional, string[], default: `[]`)
+
+Routes under this path pattern that do NOT require authentication.
+
+**Use for:**
+- Health checks: `/health`, `/status`
+- Public documentation: `/docs`, `/swagger`
+- Public endpoints: `/public`, `/info`
+
+**Example:**
+```javascript
+excludedPaths: ["/health", "/status", "/docs"]
+
+// These routes do NOT require tokens:
+// GET /admin/health      ✅ No token needed
+// GET /admin/status      ✅ No token needed
+// GET /admin/docs        ✅ No token needed
+// GET /admin/dashboard   ❌ Token required
+```
+
+#### `enablePayloadCache` (optional, boolean, default: `true`)
+
+Whether to cache decoded JWT payloads to reduce verification overhead.
+
+**Effect:**
+- `true`: Tokens cached for `payloadCacheTTL` milliseconds (faster, ~90% reduction)
+- `false`: Every token is verified and decoded (slower, fresh on every request)
+
+**When to disable:**
+- Permissions changing frequently
+- Immediate revocation needed
+- Low-traffic endpoints
+
+**Example:**
+```javascript
+enablePayloadCache: true  // Default - recommended
+```
+
+#### `payloadCacheTTL` (optional, number, default: `300000`)
+
+JWT payload cache time-to-live in milliseconds (only if `enablePayloadCache: true`).
+
+**Common values:**
+- `60000` - 1 minute (very short, frequent refreshes)
+- `300000` - 5 minutes (default, good balance)
+- `600000` - 10 minutes (longer cache, better performance)
+- `1800000` - 30 minutes (very long, stable services)
+
+**Example:**
+```javascript
+payloadCacheTTL: 300000  // 5 minutes
+```
+
+**Recommendation:** Match to your JWT expiration time (usually 5-60 minutes).
+
+#### `jwksCacheMaxAge` (optional, number, default: `1800000`)
+
+JWKS cache time-to-live in milliseconds (only for remote `jwksUrl`).
+
+**When JWKS is cached:**
+- Keys are fetched once, then reused
+- Reduces external API calls
+- Faster token verification
+
+**When to adjust:**
+- Frequent key rotation: Lower value (60000 = 1 minute)
+- Stable keys: Higher value (3600000 = 1 hour)
+
+**Common values:**
+- `300000` - 5 minutes (frequent rotation)
+- `1800000` - 30 minutes (default, balanced)
+- `3600000` - 1 hour (stable production keys)
+
+**Example:**
+```javascript
+jwksCacheMaxAge: 1800000  // 30 minutes
+```
+
+**Note:** Only applies to `jwksUrl` (remote), not `jwksData` (local).
+
+#### `jwksCooldownDuration` (optional, number, default: `60000`)
+
+Cooldown between JWKS refetch attempts after a key mismatch (only for `jwksUrl`).
+
+**When used:**
+- Token signed with unknown `kid` (key ID)
+- Plugin will wait before retrying
+
+**Example:**
+```javascript
+jwksCooldownDuration: 60000  // 1 minute between refetches
+```
+
+---
+
+## Configuration Examples
+
+### Example 1: Simple Development Setup
+
+```javascript
+import Fastify from 'fastify';
+import xAuthJWSK from '@xenterprises/fastify-xauth-jwks';
+import localJwks from './keys.json' assert { type: 'json' };
+
+const fastify = Fastify();
+
+await fastify.register(xAuthJWSK, {
+  paths: {
+    api: {
+      pathPattern: "/api",
+      jwksData: localJwks,
+      excludedPaths: ["/health", "/docs"]
+    }
+  }
+});
+
+fastify.get('/api/data', (request) => ({ data: 'sensitive' }));
+await fastify.listen({ port: 3000 });
+```
+
+### Example 2: Production with Remote JWKS
+
+```javascript
+await fastify.register(xAuthJWSK, {
+  paths: {
+    admin: {
+      pathPattern: "/admin",
+      jwksUrl: "https://auth.example.com/.well-known/jwks.json",
+      jwksCacheMaxAge: 3600000,  // 1 hour
+      jwksCooldownDuration: 60000  // 1 minute
+    },
+    api: {
+      pathPattern: "/api",
+      jwksUrl: "https://auth.example.com/.well-known/jwks.json",
+      payloadCacheTTL: 300000,  // 5 minutes
+      enablePayloadCache: true
+    }
+  }
+});
+```
+
+### Example 3: Self-Signed Token Service
+
+```javascript
+import { generateKeyPair, exportJWK, exportPKCS8 } from 'jose';
+
+// Generate keys
+const { publicKey, privateKey } = await generateKeyPair('RS256');
+const publicJwk = await exportJWK(publicKey);
+const privateKeyPem = await exportPKCS8(privateKey);
+
+// Register plugin with public key for validation
+await fastify.register(xAuthJWSK, {
+  paths: {
+    api: {
+      pathPattern: "/api",
+      jwksData: {
+        ...publicJwk,
+        use: 'sig',
+        alg: 'RS256',
+        kid: 'self-signed-key'
+      }
+    }
+  }
+});
+
+// Use private key for signing (in application code)
+fastify.post('/login', async (request) => {
+  const token = await new jose.SignJWT({
+    sub: user.id,
+    email: user.email
+  })
+    .setProtectedHeader({ alg: 'RS256', kid: 'self-signed-key' })
+    .sign(privateKey);
+
+  return { token };
+});
+```
+
+### Example 4: Multiple Paths with Fallback
+
+```javascript
+const config = {
+  paths: {
+    admin: {
+      pathPattern: "/admin",
+      // Use environment variable or local fallback
+      ...(process.env.ADMIN_JWKS_URL
+        ? { jwksUrl: process.env.ADMIN_JWKS_URL }
+        : { jwksData: localJwks.admin }
+      ),
+      enablePayloadCache: true,
+      payloadCacheTTL: 300000
+    },
+    portal: {
+      pathPattern: "/portal",
+      ...(process.env.PORTAL_JWKS_URL
+        ? { jwksUrl: process.env.PORTAL_JWKS_URL }
+        : { jwksData: localJwks.portal }
+      ),
+      excludedPaths: ["/public"],
+      enablePayloadCache: true
+    },
+    partner: {
+      pathPattern: "/partner",
+      jwksUrl: process.env.PARTNER_JWKS_URL,
+      enablePayloadCache: false  // Refresh every request
+    }
+  }
+};
+
+await fastify.register(xAuthJWSK, config);
+```
+
+### Example 5: High-Traffic Production Setup
+
+```javascript
+await fastify.register(xAuthJWSK, {
+  paths: {
+    api: {
+      pathPattern: "/api",
+      jwksUrl: "https://auth.example.com/.well-known/jwks.json",
+      // JWKS optimization
+      jwksCacheMaxAge: 3600000,         // 1 hour cache
+      jwksCooldownDuration: 60000,      // 1 min between refetches
+      // Token cache optimization
+      enablePayloadCache: true,
+      payloadCacheTTL: 600000,          // 10 min token cache
+      // Excluded endpoints
+      excludedPaths: ["/health", "/status", "/metrics"]
+    }
+  }
+});
+```
+
+---
+
+## Environment Variables
+
+Common patterns for environment-based configuration:
+
+```bash
+# Development
+USE_LOCAL_JWKS=true
+LOCAL_JWKS_PATH=./keys.json
+
+# Production
+ADMIN_JWKS_URL=https://auth.example.com/admin/.well-known/jwks.json
+PORTAL_JWKS_URL=https://auth.example.com/portal/.well-known/jwks.json
+PARTNER_JWKS_URL=https://auth.example.com/partner/.well-known/jwks.json
+
+# Cache tuning
+JWKS_CACHE_MAX_AGE=3600000
+PAYLOAD_CACHE_TTL=300000
+```
+
+**Usage:**
+```javascript
+await fastify.register(xAuthJWSK, {
+  paths: {
+    admin: {
+      pathPattern: "/admin",
+      ...(process.env.USE_LOCAL_JWKS === 'true'
+        ? { jwksData: localJwks }
+        : { jwksUrl: process.env.ADMIN_JWKS_URL }
+      ),
+      jwksCacheMaxAge: Number(process.env.JWKS_CACHE_MAX_AGE) || 1800000,
+      payloadCacheTTL: Number(process.env.PAYLOAD_CACHE_TTL) || 300000
+    }
+  }
+});
+```
+
+---
+
+## Production Checklist
+
+### Before Deploying to Production
+
+- [ ] **Use `jwksUrl`** - Not local `jwksData`
+- [ ] **Enable caching** - `enablePayloadCache: true` (default)
+- [ ] **Set JWKS cache high** - `jwksCacheMaxAge: 3600000` (1 hour typical)
+- [ ] **Configure TTL appropriately** - Match your token expiration time
+- [ ] **Exclude health endpoints** - `excludedPaths: ["/health", "/status"]`
+- [ ] **Test key rotation** - Verify keys update correctly
+- [ ] **Monitor cache stats** - Use `getPayloadCacheStats()` regularly
+- [ ] **Set up alerts** - Watch for authentication failures
+- [ ] **Load test** - Verify performance with caching enabled
+- [ ] **Use HTTPS** - Always use TLS in production
+- [ ] **Store secrets securely** - Use environment variables or vaults
+- [ ] **Implement token refresh** - Short-lived access tokens + refresh tokens
+
+### Monitoring
+
+```javascript
+// Get cache statistics
+const stats = fastify.xAuth.validators.admin.getPayloadCacheStats();
+console.log(stats);
+// { size: 245, enabled: true, ttl: 300000 }
+
+// Monitor hit rate
+// cache.size = current tokens in cache
+// If size grows constantly, increase payloadCacheTTL
+// If size stays low, decrease (or monitor if legitimate)
+```
+
+### Performance Tuning
+
+| Scenario | Setting |
+|----------|---------|
+| **High request volume** | Increase `payloadCacheTTL` to 600000+ |
+| **Frequent key rotation** | Decrease `jwksCacheMaxAge` to 300000 |
+| **Real-time permission changes** | Set `enablePayloadCache: false` |
+| **Stable JWKS keys** | Increase `jwksCacheMaxAge` to 3600000 |
+
+---
+
+## Common Configuration Patterns
+
+### Pattern 1: Minimal Configuration
+
+```javascript
+await fastify.register(xAuthJWSK, {
+  paths: {
+    api: {
+      pathPattern: "/api",
+      jwksUrl: "https://auth.example.com/.well-known/jwks.json"
+    }
+  }
+});
+// Uses all defaults: 30 min JWKS cache, 5 min token cache, enabled
+```
+
+### Pattern 2: Development vs Production
+
+```javascript
+const isDevelopment = process.env.NODE_ENV === 'development';
+
+await fastify.register(xAuthJWSK, {
+  paths: {
+    api: {
+      pathPattern: "/api",
+      ...(isDevelopment
+        ? { jwksData: require('./keys.json') }
+        : { jwksUrl: process.env.JWKS_URL }
+      ),
+      enablePayloadCache: !isDevelopment
+    }
+  }
+});
+```
+
+### Pattern 3: Strict Admin + Relaxed User API
+
+```javascript
+await fastify.register(xAuthJWSK, {
+  paths: {
+    admin: {
+      pathPattern: "/admin",
+      jwksUrl: "https://auth.example.com/.well-known/jwks.json",
+      enablePayloadCache: false  // No cache - strict/fresh
+    },
+    api: {
+      pathPattern: "/api",
+      jwksUrl: "https://auth.example.com/.well-known/jwks.json",
+      payloadCacheTTL: 600000  // 10 min cache - relaxed
+    }
+  }
+});
+```
+
+---
+
+## Configuration Validation
+
+The plugin validates configuration on registration:
+
+```javascript
+// ❌ Missing both jwksUrl and jwksData
+paths: {
+  api: {
+    pathPattern: "/api"
+    // Error: At least one of jwksUrl or jwksData is required
+  }
+}
+
+// ❌ Both jwksUrl and jwksData specified
+paths: {
+  api: {
+    pathPattern: "/api",
+    jwksUrl: "https://...",
+    jwksData: { ... }
+    // Error: Cannot use both jwksUrl and jwksData
+  }
+}
+
+// ❌ Missing pathPattern
+paths: {
+  api: {
+    jwksUrl: "https://..."
+    // Error: pathPattern is required
+  }
+}
+
+// ✅ Valid configuration
+paths: {
+  api: {
+    pathPattern: "/api",
+    jwksUrl: "https://auth.example.com/.well-known/jwks.json"
+  }
+}
+```