@xenterprises/fastify-xauth-jwks 1.0.0

package/DEVELOPMENT.md

@@ -0,0 +1,385 @@
+# Development Guide - xAuthJWSK
+
+Quick reference for developing with xAuthJWSK locally using test tokens.
+
+## 🚀 Quick Start (30 seconds)
+
+### 1. Start the demo server (uses local JWKS by default)
+
+```bash
+cd server
+node app.js
+```
+
+You'll see:
+```
+🚀 xAuthJWSK Demo Server Started!
+
+Mode: 🏠 LOCAL (Development)
+     Using example-jwks.json - perfect for testing!
+     Generate test tokens: node server/generate-demo-token.js [path] [userId] [role]
+```
+
+### 2. Generate a test token (in another terminal)
+
+```bash
+cd server
+node generate-demo-token.js admin user-123 admin
+```
+
+Output:
+```
+🎫 Generated Test Token:
+
+eyJhbGciOiJSUzI1NiIsImtpZCI6ImRlbW8ta2V5LWFkbWluIiwidHlwIjoiSldUIn0...
+
+📋 Token Details:
+   Path:     admin
+   User ID:  user-123
+   Role:     admin
+   Expires:  1 hour
+
+🔗 Usage Examples:
+
+# cURL:
+curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiI..." \
+  http://localhost:3000/admin/dashboard
+```
+
+### 3. Test the protected endpoint
+
+```bash
+# Replace TOKEN with actual token from step 2
+TOKEN="eyJhbGciOiJSUzI1NiI..."
+
+curl -H "Authorization: Bearer $TOKEN" \
+  http://localhost:3000/admin/dashboard
+```
+
+Response:
+```json
+{
+  "message": "Admin Dashboard",
+  "userId": "user-123",
+  "user": {
+    "sub": "user-123",
+    "userId": "user-123",
+    "name": "Test User (admin)",
+    "email": "user-123@example.com",
+    "roles": ["admin"],
+    "iat": 1702000000,
+    "exp": 1702003600
+  },
+  "authenticatedVia": "admin"
+}
+```
+
+## 📝 Generate Test Tokens
+
+### Different paths and roles
+
+```bash
+# Admin with admin role
+node server/generate-demo-token.js admin user-123 admin
+
+# Portal user with user role
+node server/generate-demo-token.js portal user-456 user
+
+# Partner with default user role
+node server/generate-demo-token.js partner partner-789
+```
+
+### Decode a token (inspect claims)
+
+```bash
+# Extract the payload (middle part) and decode
+TOKEN="eyJhbGciOiJSUzI1NiI...eyJzdWIiOiJ1c2VyLTEyMyI...abc123"
+
+# Extract payload and decode
+node -e "console.log(JSON.stringify(JSON.parse(Buffer.from('$TOKEN'.split('.')[1], 'base64').toString()), null, 2))"
+```
+
+## 🏗️ Architecture
+
+### Local JWKS Mode (Development)
+
+```
+┌─────────────────────────────────────┐
+│ server/app.js                       │
+├─────────────────────────────────────┤
+│ USE_LOCAL_JWKS=true (default)       │
+│ Reads: example-jwks.json            │
+└────────────┬────────────────────────┘
+             │
+             ↓
+┌─────────────────────────────────────┐
+│ xAuthJWSK Plugin                    │
+├─────────────────────────────────────┤
+│ paths: {                            │
+│   admin: {                          │
+│     jwksData: exampleJwks ← LOCAL   │
+│   }                                 │
+│ }                                   │
+└────────────┬────────────────────────┘
+             │
+             ↓
+┌─────────────────────────────────────┐
+│ Test Token                          │
+├─────────────────────────────────────┤
+│ Signed with: private key            │
+│ Verified against: jwksData          │
+│ No network calls needed!            │
+└─────────────────────────────────────┘
+```
+
+### Remote JWKS Mode (Production)
+
+```
+USE_LOCAL_JWKS=false
+ADMIN_JWKS_URL=https://auth.example.com/.well-known/jwks.json
+  ↓
+xAuthJWSK fetches remote JWKS
+  ↓
+Validates tokens against remote keys
+```
+
+## 🔧 Server Configuration
+
+### Use Local JWKS (Default)
+
+```bash
+# Default - no env vars needed
+node app.js
+
+# Explicit
+USE_LOCAL_JWKS=true node app.js
+```
+
+### Use Remote JWKS URLs
+
+```bash
+export ADMIN_JWKS_URL="https://auth.example.com/admin/.well-known/jwks.json"
+export PORTAL_JWKS_URL="https://auth.example.com/portal/.well-known/jwks.json"
+export PARTNER_JWKS_URL="https://auth.example.com/partner/.well-known/jwks.json"
+
+node app.js
+```
+
+## 🧪 Testing Workflows
+
+### Test Missing Token
+
+```bash
+curl http://localhost:3000/admin/dashboard
+# Response: 401 Access token required
+```
+
+### Test Invalid Token
+
+```bash
+curl -H "Authorization: Bearer invalid-token" \
+  http://localhost:3000/admin/dashboard
+# Response: 401 Invalid token
+```
+
+### Test Excluded Paths (no token needed)
+
+```bash
+# These don't require tokens
+curl http://localhost:3000/admin/health
+curl http://localhost:3000/admin/status
+
+# Response: 200 OK
+```
+
+### Test Role-Based Access
+
+```bash
+# Generate user token (not admin)
+TOKEN=$(node server/generate-demo-token.js admin user-456 user | grep "Bearer" -A 1 | head -1)
+
+# Try admin-only endpoint
+curl -H "Authorization: Bearer $TOKEN" \
+  http://localhost:3000/admin/settings
+# Response: 403 Insufficient permissions (requireRole('admin') failed)
+```
+
+### Test Token Expiration
+
+Check expiration in generated tokens:
+
+```bash
+# Token has exp claim set to 1 hour from now
+# After 1 hour, the same token will fail validation
+```
+
+## 🔐 Key Management
+
+### Current Demo Key
+
+The demo uses a single RSA key defined in `generate-demo-token.js`:
+- Kid: `demo-key-admin`
+- Algorithm: RS256
+- Public key: stored in `example-jwks.json`
+- Private key: used only to sign test tokens
+
+### Generate Your Own Keys
+
+For production or custom development:
+
+```bash
+node generate-keys.js
+```
+
+See [KEYS_GENERATION.md](./KEYS_GENERATION.md) for details.
+
+## 🔍 Debugging
+
+### View Cache Statistics
+
+```bash
+curl http://localhost:3000/admin/cache/stats
+```
+
+Response:
+```json
+{
+  "cacheStats": {
+    "admin": {
+      "size": 2,
+      "enabled": true,
+      "ttl": 300000
+    },
+    "portal": {
+      "size": 0,
+      "enabled": true,
+      "ttl": 300000
+    },
+    "partner": {
+      "size": 0,
+      "enabled": true,
+      "ttl": 600000
+    }
+  }
+}
+```
+
+### View Validator Configuration
+
+```bash
+curl http://localhost:3000/admin/validators
+```
+
+### Decode Token (server-side)
+
+```bash
+TOKEN="eyJhbGciOiJSUzI1NiI..."
+
+curl -X POST http://localhost:3000/debug/decode-token \
+  -H "Content-Type: application/json" \
+  -d "{\"token\": \"$TOKEN\"}"
+```
+
+### Extract Token from Header
+
+```bash
+curl -X POST http://localhost:3000/debug/extract-token \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+## 📊 Endpoints for Development
+
+### Public (no token needed)
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| GET | `/` | API info |
+| GET | `/health` | Health check |
+| POST | `/debug/decode-token` | Decode JWT payload |
+| POST | `/debug/extract-token` | Extract Bearer token |
+| GET | `/admin/validators` | View validator configs |
+
+### Protected - Admin Path
+
+| Method | Path | Notes |
+|--------|------|-------|
+| GET | `/admin/dashboard` | Requires token |
+| GET | `/admin/health` | Excluded (no token needed) |
+| GET | `/admin/status` | Excluded (no token needed) |
+| GET | `/admin/users` | List users |
+| GET | `/admin/settings` | Requires `admin` role |
+| POST | `/admin/cache/clear` | Clear JWT cache |
+| GET | `/admin/cache/stats` | View cache stats |
+
+### Protected - Portal Path
+
+| Method | Path | Notes |
+|--------|------|-------|
+| GET | `/portal/dashboard` | Requires token |
+| GET | `/portal/profile` | User profile |
+| GET | `/portal/public/docs` | Excluded (no token needed) |
+| GET | `/portal/public/pricing` | Excluded (no token needed) |
+
+### Protected - Partner Path
+
+| Method | Path | Notes |
+|--------|------|-------|
+| GET | `/partner/api/data` | Partner data |
+| GET | `/partner/api/webhooks` | Partner webhooks |
+
+## 🐛 Troubleshooting
+
+### "Invalid token" on all requests
+
+1. Check token is valid:
+   ```bash
+   node -e "console.log(JSON.stringify(JSON.parse(Buffer.from('TOKEN'.split('.')[1], 'base64').toString()), null, 2))" | jq .
+   ```
+
+2. Check token hasn't expired:
+   ```bash
+   node -e "const token = 'TOKEN'; const exp = JSON.parse(Buffer.from(token.split('.')[1], 'base64').toString()).exp; console.log('Expires:', new Date(exp * 1000).toISOString(), 'Valid:', exp * 1000 > Date.now());"
+   ```
+
+3. Check kid matches:
+   ```bash
+   # Token header kid
+   node -e "const token = 'TOKEN'; const header = JSON.parse(Buffer.from(token.split('.')[0], 'base64').toString()); console.log('Token kid:', header.kid);"
+
+   # JWKS kids
+   cat example-jwks.json | jq '.keys[].kid'
+   ```
+
+### "Local JWKS not working"
+
+1. Check `example-jwks.json` exists:
+   ```bash
+   ls -la server/example-jwks.json
+   ```
+
+2. Validate JWKS JSON:
+   ```bash
+   cat server/example-jwks.json | jq .
+   ```
+
+3. Ensure server is using local mode:
+   ```bash
+   # Should say "🏠 LOCAL (Development)"
+   node app.js | head -10
+   ```
+
+### Cache not working
+
+Check cache is enabled:
+```bash
+curl http://localhost:3000/admin/cache/stats | jq .
+```
+
+If `enabled: false`, restart server or check `enablePayloadCache` config.
+
+## 📚 Related Documentation
+
+- [KEYS_GENERATION.md](./KEYS_GENERATION.md) - Generate your own keys
+- [QUICK_START.md](./QUICK_START.md) - Production setup
+- [CACHING.md](./CACHING.md) - Caching configuration
+- [JOSE_UTILITIES.md](./JOSE_UTILITIES.md) - Token inspection utilities

package/JOSE_UTILITIES.md

@@ -0,0 +1,204 @@
+# Jose Utilities Reference
+
+xAuthJWSK re-exports useful jose functions for advanced JWT manipulation without requiring a separate jose import.
+
+## Available Utilities
+
+### decodeToken(token)
+
+Decode JWT payload without verification. Useful for inspecting claims without validation overhead.
+
+**⚠️ Warning**: This does NOT verify the signature. Use only for inspection, never trust the claims without verification.
+
+```javascript
+import { decodeToken } from '@xenterprises/fastify-xauth-jwks/utils';
+
+const token = request.headers.authorization?.split(' ')[1];
+const payload = decodeToken(token);
+
+console.log(payload.sub);      // User ID
+console.log(payload.exp);      // Expiration time
+console.log(payload.roles);    // User roles
+```
+
+**Use Cases:**
+- Inspecting token expiration before full validation
+- Checking user ID in headers before processing
+- Debugging JWT content
+- Conditional routing based on claims
+
+**Example: Check Token Expiration**
+
+```javascript
+import { decodeToken } from '@xenterprises/fastify-xauth-jwks/utils';
+
+fastify.addHook('onRequest', async (request, reply) => {
+  const token = extractToken(request);
+  if (!token) return;
+
+  const payload = decodeToken(token);
+
+  // Check if token is about to expire
+  if (payload.exp && Date.now() / 1000 > payload.exp - 60) {
+    // Token expires in less than 1 minute
+    request.tokenAboutToExpire = true;
+  }
+});
+```
+
+### decodeHeader(token)
+
+Decode JWT header without verification. Useful for inspecting algorithm, key ID, and other header claims.
+
+```javascript
+import { decodeHeader } from '@xenterprises/fastify-xauth-jwks/utils';
+
+const token = request.headers.authorization?.split(' ')[1];
+const header = decodeHeader(token);
+
+console.log(header.alg);       // Algorithm (HS256, RS256, etc.)
+console.log(header.kid);       // Key ID
+console.log(header.typ);       // Type (JWT)
+```
+
+**Use Cases:**
+- Finding which key signed the token (kid)
+- Verifying algorithm matches expected value
+- Debugging JWT issues
+- Routing tokens to different validators
+
+**Example: Check Key ID**
+
+```javascript
+import { decodeHeader, extractToken } from '@xenterprises/fastify-xauth-jwks/utils';
+
+fastify.addHook('onRequest', async (request, reply) => {
+  const token = extractToken(request);
+  if (!token) return;
+
+  const header = decodeHeader(token);
+
+  // Route to different validator based on key ID
+  if (header.kid === 'old-key') {
+    request.oldKeyWarning = true;
+  }
+});
+```
+
+**Example: Validate Algorithm**
+
+```javascript
+import { decodeHeader, extractToken } from '@xenterprises/fastify-xauth-jwks/utils';
+
+fastify.addHook('onRequest', async (request, reply) => {
+  const token = extractToken(request);
+  if (!token) return;
+
+  const header = decodeHeader(token);
+
+  // Only accept RS256, reject HS256
+  if (header.alg === 'HS256') {
+    return reply.code(401).send({ error: 'Insecure algorithm' });
+  }
+});
+```
+
+## When to Use vs When NOT to Use
+
+### ✅ DO use decodeToken/decodeHeader for:
+
+- Pre-validation inspection of claims
+- Extracting metadata from token headers
+- Conditional routing decisions
+- Token debugging and inspection
+- Displaying token info to user (read-only)
+
+### ❌ DON'T use decodeToken/decodeHeader for:
+
+- Making authorization decisions (trust signature verification via xAuthJWSK)
+- Verifying user identity without validation
+- Accepting claims as fact without verification
+- Security-critical decisions
+
+## Complete Example
+
+```javascript
+import Fastify from 'fastify';
+import xAuthJWSK from '@xenterprises/fastify-xauth-jwks';
+import { decodeToken, decodeHeader, extractToken } from '@xenterprises/fastify-xauth-jwks/utils';
+
+const fastify = Fastify();
+
+await fastify.register(xAuthJWSK, {
+  paths: {
+    api: {
+      pathPattern: "/api",
+      jwksUrl: "https://your-auth.com/.well-known/jwks.json",
+    }
+  }
+});
+
+// Pre-validation inspection
+fastify.addHook('onRequest', async (request, reply) => {
+  const token = extractToken(request);
+  if (!token) return;
+
+  const header = decodeHeader(token);
+
+  // Log key ID for audit
+  request.keyId = header.kid;
+
+  const payload = decodeToken(token);
+
+  // Check expiration before full validation
+  const expiresIn = (payload.exp * 1000) - Date.now();
+  if (expiresIn < 60000) {
+    request.tokenWarnings = ['Token expires in less than 1 minute'];
+  }
+});
+
+// Protected routes use request.auth (after xAuthJWSK validation)
+fastify.get('/api/profile', (request) => {
+  return {
+    userId: request.auth.userId,     // Verified via signature
+    warnings: request.tokenWarnings,  // From pre-validation
+    keyId: request.keyId              // From pre-validation
+  };
+});
+```
+
+## Performance Considerations
+
+- `decodeToken()` and `decodeHeader()` are **very fast** (no crypto operations)
+- Use liberally for inspection and logging
+- They complete in microseconds (vs milliseconds for signature verification)
+- Safe to call in every request without performance impact
+
+## Error Handling
+
+Both functions throw if token is malformed:
+
+```javascript
+import { decodeToken } from '@xenterprises/fastify-xauth-jwks/utils';
+
+try {
+  const payload = decodeToken(badToken);
+} catch (error) {
+  // Invalid JWT format
+  console.error('Malformed token:', error.message);
+}
+```
+
+## No Other Jose Exports
+
+xAuthJWSK intentionally does NOT export:
+- `SignJWT`, `CompactSign` - Not needed (tokens come from auth provider)
+- `generateKeyPair`, `generateSecret` - Not needed (use auth provider)
+- `importJWK`, `importPKCS8` - Not needed (JWKS are fetched remotely)
+- Encryption functions - Out of scope for validation only
+
+This keeps the module slim and focused. If you need advanced jose features, import jose directly:
+
+```javascript
+import * as jose from 'jose';
+```