@xenterprises/fastify-xauth-jwks 1.0.0

package/KEYS_GENERATION.md

@@ -0,0 +1,359 @@
+# Generating JWKS Keys
+
+This guide shows how to generate and use cryptographic keys with xAuthJWSK for local development and testing.
+
+## Quick Start: Using Node.js
+
+### 1. Generate RSA Key Pair
+
+Create a file called `generate-keys.js`:
+
+```javascript
+import * as jose from 'jose';
+import fs from 'fs';
+
+async function generateKeys() {
+  // Generate RSA key pair
+  const { publicKey, privateKey } = await jose.generateKeyPair('RS256');
+
+  // Export keys to JWK format
+  const publicJwk = await jose.exportSPKI(publicKey);
+  const privateJwk = await jose.exportPKCS8(privateKey);
+
+  // Create JWKS (public keys only - safe to share)
+  const jwks = {
+    keys: [
+      {
+        ...(await jose.exportJWK(publicKey)),
+        use: 'sig',
+        alg: 'RS256',
+        kid: 'dev-key-' + Date.now(),
+      },
+    ],
+  };
+
+  // Save files
+  fs.writeFileSync('private-key.pem', privateJwk);
+  fs.writeFileSync('public-key.pem', publicJwk);
+  fs.writeFileSync('jwks.json', JSON.stringify(jwks, null, 2));
+
+  console.log('✅ Keys generated successfully!');
+  console.log('   - private-key.pem  (Keep secret - for signing tokens)');
+  console.log('   - public-key.pem   (Safe to share)');
+  console.log('   - jwks.json        (Use in xAuthJWSK config)');
+  console.log(`\nKey ID: ${jwks.keys[0].kid}`);
+}
+
+generateKeys().catch(console.error);
+```
+
+Run it:
+
+```bash
+node generate-keys.js
+```
+
+Output files:
+- **private-key.pem** - Use this to sign test tokens
+- **public-key.pem** - Public key format
+- **jwks.json** - JWKS format for xAuthJWSK
+
+### 2. Using the JWKS in xAuthJWSK
+
+```javascript
+import Fastify from 'fastify';
+import xAuthJWSK from '@xenterprises/fastify-xauth-jwks';
+import localJwks from './jwks.json' assert { type: 'json' };
+
+const fastify = Fastify();
+
+await fastify.register(xAuthJWSK, {
+  paths: {
+    api: {
+      pathPattern: '/api',
+      jwksData: localJwks,  // Use local JWKS
+    }
+  }
+});
+
+// Routes now protected with JWT validation against local keys
+fastify.get('/api/data', (request) => {
+  return { userId: request.auth.userId };
+});
+
+await fastify.listen({ port: 3000 });
+```
+
+### 3. Create Test Tokens
+
+Create a file called `create-token.js`:
+
+```javascript
+import * as jose from 'jose';
+import fs from 'fs';
+
+async function createToken() {
+  // Read private key
+  const privateKeyPem = fs.readFileSync('private-key.pem', 'utf8');
+  const privateKey = await jose.importPKCS8(privateKeyPem, 'RS256');
+
+  // Read JWKS to get key ID
+  const jwks = JSON.parse(fs.readFileSync('jwks.json', 'utf8'));
+  const kid = jwks.keys[0].kid;
+
+  // Create token
+  const token = await new jose.SignJWT({
+    sub: 'user-123',
+    name: 'Test User',
+    email: 'test@example.com',
+    roles: ['admin'],
+    iat: Math.floor(Date.now() / 1000),
+    exp: Math.floor(Date.now() / 1000) + 3600, // 1 hour
+  })
+    .setProtectedHeader({
+      alg: 'RS256',
+      kid: kid,  // Must match key ID in JWKS
+      typ: 'JWT',
+    })
+    .sign(privateKey);
+
+  console.log('🎫 Test Token:');
+  console.log(token);
+  console.log('\n📋 Usage:');
+  console.log('curl -H "Authorization: Bearer ' + token + '" http://localhost:3000/api/data');
+}
+
+createToken().catch(console.error);
+```
+
+Run it:
+
+```bash
+node create-token.js
+```
+
+### 4. Test the Protected Route
+
+```bash
+# Get token
+TOKEN=$(node create-token.js | grep -A 100 "Test Token:" | tail -1)
+
+# Call protected endpoint
+curl -H "Authorization: Bearer $TOKEN" http://localhost:3000/api/data
+```
+
+## Using OpenSSL (Alternative)
+
+If you prefer command-line tools:
+
+### Generate RSA Key Pair
+
+```bash
+# Generate private key
+openssl genrsa -out private-key.pem 2048
+
+# Extract public key
+openssl rsa -in private-key.pem -pubout -out public-key.pem
+```
+
+### Convert to JWKS Format
+
+Create `keys-to-jwks.js`:
+
+```javascript
+import * as jose from 'jose';
+import fs from 'fs';
+
+async function convertToJwks() {
+  const publicKeyPem = fs.readFileSync('public-key.pem', 'utf8');
+  const publicKey = await jose.importSPKI(publicKeyPem, 'RS256');
+
+  const jwks = {
+    keys: [
+      {
+        ...(await jose.exportJWK(publicKey)),
+        use: 'sig',
+        alg: 'RS256',
+        kid: 'dev-key-' + Date.now(),
+      },
+    ],
+  };
+
+  fs.writeFileSync('jwks.json', JSON.stringify(jwks, null, 2));
+  console.log('✅ JWKS generated from existing keys');
+}
+
+convertToJwks().catch(console.error);
+```
+
+## Key Algorithms
+
+### RS256 (Recommended)
+
+Asymmetric RSA signature. Use this for:
+- Development and testing
+- Multiple independent services
+- Key rotation scenarios
+
+```javascript
+const { publicKey, privateKey } = await jose.generateKeyPair('RS256');
+```
+
+### HS256
+
+Symmetric HMAC. Use this only for:
+- Single monolithic application
+- When performance is critical
+- Development with shared secret
+
+```javascript
+const secret = jose.base64url.decode('your-secret-here');
+const key = await jose.importJWK({ kty: 'oct', k: jose.base64url.encode(secret) });
+```
+
+## JWKS File Format
+
+Here's what a typical JWKS looks like:
+
+```json
+{
+  "keys": [
+    {
+      "kty": "RSA",
+      "use": "sig",
+      "alg": "RS256",
+      "kid": "dev-key-1702000000000",
+      "n": "very-long-base64-number...",
+      "e": "AQAB",
+      "crv": null,
+      "x": null,
+      "y": null,
+      "d": null,
+      "p": null,
+      "q": null,
+      "dp": null,
+      "dq": null,
+      "qi": null,
+      "oth": null,
+      "ext": true,
+      "key_ops": [],
+      "x5c": null,
+      "x5t": null,
+      "x5t#S256": null,
+      "x5u": null
+    }
+  ]
+}
+```
+
+**Key fields:**
+- `kty` - Key type (`RSA`, `EC`, `oct`)
+- `use` - Key usage (`sig` for signing, `enc` for encryption)
+- `alg` - Algorithm (`RS256`, `ES256`, `HS256`)
+- `kid` - Key ID (must match token header `kid`)
+- `n`, `e` - RSA components (modulus, exponent)
+- `x`, `y` - EC coordinates (for elliptic curve)
+- `k` - Symmetric key (for HMAC)
+
+## Token Header Format
+
+Tokens signed with your keys should have headers like:
+
+```json
+{
+  "alg": "RS256",
+  "kid": "dev-key-1702000000000",
+  "typ": "JWT"
+}
+```
+
+The `kid` (Key ID) **must match** a key in your JWKS.
+
+## Best Practices
+
+### ✅ DO
+
+- Generate unique keys for each environment (dev, staging, prod)
+- Rotate keys periodically
+- Keep private keys in `.env` or secrets manager (not in code)
+- Use strong algorithms (RS256, ES256)
+- Set appropriate expiration times on tokens
+- Log key rotations for audit trails
+
+### ❌ DON'T
+
+- Commit private keys to git
+- Use HS256 with static shared secrets
+- Reuse the same key for years
+- Put keys in public URLs
+- Share JWKS files containing private key material
+- Use weak algorithms (HS256 with short secrets)
+
+## Example: Development Workflow
+
+```bash
+# 1. Generate keys
+node generate-keys.js
+
+# 2. Add to .gitignore
+echo "private-key.pem" >> .gitignore
+echo "*.token" >> .gitignore
+
+# 3. Start server with local JWKS
+node server.js
+
+# 4. Create test token in another terminal
+TOKEN=$(node create-token.js | grep "Bearer" | awk '{print $NF}')
+echo $TOKEN > test.token
+
+# 5. Test endpoint
+curl -H "Authorization: Bearer $(cat test.token)" http://localhost:3000/api/data
+
+# 6. Decode and inspect token
+node -e "console.log(require('util').inspect(JSON.parse(Buffer.from(process.argv[1].split('.')[1], 'base64').toString()), false, 10))" "$(cat test.token)"
+```
+
+## Rotating Keys
+
+To rotate keys with zero downtime:
+
+1. **Generate new key pair**
+   ```bash
+   node generate-keys.js
+   ```
+
+2. **Add new key to JWKS** (keep old keys)
+   ```json
+   {
+     "keys": [
+       { "kid": "old-key-...", ... },
+       { "kid": "new-key-...", ... }
+     ]
+   }
+   ```
+
+3. **Start signing new tokens with new key**
+4. **Wait for old tokens to expire**
+5. **Remove old keys from JWKS** after expiration period
+
+xAuthJWSK will accept tokens signed with any key in the JWKS, enabling smooth rotation.
+
+## Troubleshooting
+
+### "Invalid token" errors
+
+1. Check `kid` in token header matches JWKS
+2. Verify token hasn't expired (`exp` claim)
+3. Ensure private key used to sign matches public key in JWKS
+
+### "JWKS format error"
+
+1. Validate JSON syntax: `cat jwks.json | jq .`
+2. Ensure `keys` is an array
+3. Check required fields: `kty`, `use`, `alg`, `kid`
+
+### "Cannot verify token"
+
+1. Make sure token was signed with corresponding private key
+2. Check algorithm matches (`alg` in token header vs JWKS)
+3. Verify public key `n` and `e` values match original key

package/QUICK_START.md

@@ -0,0 +1,334 @@
+# xAuthJWSK Quick Start
+
+Lightweight path-based JWT/JWKS validation for Fastify v5.
+
+## Installation
+
+```bash
+npm install @xenterprises/fastify-xauth-jwks
+```
+
+## Basic Usage
+
+```javascript
+import Fastify from 'fastify';
+import xAuthJWSK from '@xenterprises/fastify-xauth-jwks';
+
+const fastify = Fastify();
+
+await fastify.register(xAuthJWSK, {
+  paths: {
+    admin: {
+      pathPattern: "/admin",
+      jwksUrl: "https://your-auth.com/.well-known/jwks.json",
+    }
+  }
+});
+
+// All routes under /admin now require Bearer tokens
+fastify.get('/admin/users', (request) => {
+  return {
+    userId: request.auth.userId,      // from JWT 'sub' claim
+    payload: request.auth.payload,    // full JWT payload
+    path: request.auth.path,          // 'admin'
+  };
+});
+```
+
+## Multiple Paths
+
+Protect different paths with different JWKS providers:
+
+```javascript
+await fastify.register(xAuthJWSK, {
+  paths: {
+    admin: {
+      pathPattern: "/admin",
+      jwksUrl: "https://your-auth.com/admin/.well-known/jwks.json",
+    },
+    portal: {
+      pathPattern: "/portal",
+      jwksUrl: "https://your-auth.com/portal/.well-known/jwks.json",
+    }
+  }
+});
+```
+
+## Local JWKS (Development/Testing)
+
+Use local JWKS data instead of remote endpoints. `jwksData` accepts either a full JWKS object or a single JWK key:
+
+### Option 1: Full JWKS Object (multiple keys)
+
+```javascript
+import localJwks from './jwks.json' assert { type: 'json' };
+
+await fastify.register(xAuthJWSK, {
+  paths: {
+    api: {
+      pathPattern: "/api",
+      jwksData: localJwks,  // { keys: [...] }
+    }
+  }
+});
+```
+
+### Option 2: Single JWK Key (for token signing AND validation)
+
+Perfect for email/password auth, passwordless flows, or self-contained services:
+
+```javascript
+import { exportSPKI, exportJWK, generateKeyPair } from 'jose';
+
+const { publicKey } = await generateKeyPair('RS256');
+const publicJwk = await exportJWK(publicKey);
+
+await fastify.register(xAuthJWSK, {
+  paths: {
+    api: {
+      pathPattern: "/api",
+      jwksData: {  // Single JWK - automatically wrapped in JWKS format
+        ...publicJwk,
+        use: "sig",
+        alg: "RS256",
+        kid: "my-key-id"
+      }
+    }
+  }
+});
+```
+
+### Option 3: Inline JWKS Object
+
+```javascript
+await fastify.register(xAuthJWSK, {
+  paths: {
+    api: {
+      pathPattern: "/api",
+      jwksData: {
+        keys: [
+          {
+            kty: "RSA",
+            use: "sig",
+            kid: "your-key-id",
+            n: "...",
+            e: "AQAB"
+          }
+        ]
+      }
+    }
+  }
+});
+```
+
+**Key Points:**
+- `jwksData` accepts both `{ keys: [...] }` (full JWKS) and single JWK objects
+- Single keys are automatically wrapped in JWKS format internally
+- Perfect for self-contained services that sign AND validate their own tokens
+- Use `jwksUrl` for production (remote endpoints) or `jwksData` for development/testing (local data)
+- Cannot use both `jwksUrl` and `jwksData` simultaneously
+
+## Excluded Paths
+
+Skip authentication for specific routes:
+
+```javascript
+await fastify.register(xAuthJWSK, {
+  paths: {
+    api: {
+      pathPattern: "/api",
+      jwksUrl: "https://your-auth.com/.well-known/jwks.json",
+      excludedPaths: ["/health", "/status", "/docs"],
+    }
+  }
+});
+
+// These do NOT require tokens
+fastify.get('/api/health', () => ({ ok: true }));
+fastify.get('/api/status', () => ({ status: 'active' }));
+```
+
+## Caching Configuration
+
+### Default Caching (Recommended)
+
+```javascript
+{
+  paths: {
+    api: {
+      pathPattern: "/api",
+      jwksUrl: "https://your-auth.com/.well-known/jwks.json",
+      // Default: JWKS cached 30 mins, tokens cached 5 mins
+    }
+  }
+}
+```
+
+### Custom Caching
+
+```javascript
+{
+  paths: {
+    api: {
+      pathPattern: "/api",
+      jwksUrl: "https://your-auth.com/.well-known/jwks.json",
+      // JWKS caching
+      jwksCooldownDuration: 60000,       // 1 min between JWKS refetches
+      jwksCacheMaxAge: 3600000,          // 1 hour JWKS cache
+      // JWT payload caching
+      enablePayloadCache: true,          // cache token payloads
+      payloadCacheTTL: 600000,           // 10 min token cache
+    }
+  }
+}
+```
+
+### Disable Caching
+
+```javascript
+{
+  paths: {
+    admin: {
+      pathPattern: "/admin",
+      jwksUrl: "https://your-auth.com/.well-known/jwks.json",
+      enablePayloadCache: false,         // no token payload caching
+    }
+  }
+}
+```
+
+## Accessing User Info
+
+In any protected route:
+
+```javascript
+fastify.get('/admin/profile', (request) => {
+  const userId = request.auth.userId;          // JWT 'sub' claim
+  const tokenPayload = request.auth.payload;   // full JWT payload
+  const pathName = request.auth.path;          // 'admin'
+
+  return { userId, tokenPayload, pathName };
+});
+```
+
+## Cache Management
+
+```javascript
+const validator = fastify.xAuth.validators.admin;
+
+// Get cache stats
+const stats = validator.getPayloadCacheStats();
+console.log(stats);  // { size: 42, enabled: true, ttl: 300000 }
+
+// Clear cache manually
+validator.clearPayloadCache();
+
+// Access configuration
+console.log(validator.config);
+```
+
+## Utilities
+
+Import helper functions:
+
+```javascript
+import { extractToken, hasRole, hasPermission } from '@xenterprises/fastify-xauth-jwks/utils';
+
+// Extract token from Authorization header
+const token = extractToken(request);
+
+// Check roles (if JWT includes 'roles' claim)
+if (hasRole(request.user, 'admin')) {
+  // user is admin
+}
+
+// Check permissions (if JWT includes 'permissions' claim)
+if (hasPermission(request.user, 'users:write')) {
+  // user can write users
+}
+
+// Get user ID
+const userId = getUserId(request);
+
+// Get auth path name
+const pathName = getAuthEndpoint(request);
+```
+
+## Error Responses
+
+### Missing Token
+```javascript
+{
+  statusCode: 401,
+  error: "Access token required",
+  path: "admin"
+}
+```
+
+### Invalid Token
+```javascript
+{
+  statusCode: 401,
+  error: "Invalid token",
+  path: "admin"
+}
+```
+
+## Performance Tips
+
+1. **Enable caching** (default): Reduces verification overhead by ~90%
+2. **Increase `jwksCacheMaxAge`** for stable JWKS endpoints (up to 1 hour)
+3. **Match `payloadCacheTTL`** to your token lifetime (usually 5-15 mins)
+4. **Monitor cache** with `getPayloadCacheStats()` in production
+
+## Examples
+
+### Simple API Protection
+
+```javascript
+await fastify.register(xAuthJWSK, {
+  paths: {
+    api: {
+      pathPattern: "/api",
+      jwksUrl: "https://auth.example.com/.well-known/jwks.json",
+    }
+  }
+});
+
+fastify.get('/api/data', (request) => ({ data: 'sensitive' }));
+```
+
+### Multiple Environments
+
+```javascript
+await fastify.register(xAuthJWSK, {
+  paths: {
+    admin: {
+      pathPattern: "/admin",
+      jwksUrl: process.env.ADMIN_JWKS_URL,
+    },
+    portal: {
+      pathPattern: "/portal",
+      jwksUrl: process.env.PORTAL_JWKS_URL,
+    }
+  }
+});
+```
+
+### High-Traffic Setup
+
+```javascript
+await fastify.register(xAuthJWSK, {
+  paths: {
+    api: {
+      pathPattern: "/api",
+      jwksUrl: "https://auth.example.com/.well-known/jwks.json",
+      jwksCooldownDuration: 60000,
+      jwksCacheMaxAge: 3600000,
+      payloadCacheTTL: 600000,
+    }
+  }
+});
+```
+
+See [CACHING.md](./CACHING.md) for detailed caching documentation.