@xenterprises/fastify-xauth-jwks 1.0.0

package/AUTHENTICATION_EXAMPLE.md

@@ -0,0 +1,453 @@
+# Authentication Example: Email/Password with JWT Signing
+
+This example shows how to use xAuthJWSK for complete authentication workflows, including:
+- Token signing for user login
+- Token validation for protected routes
+- All using a single JWK key
+
+## Architecture
+
+```
+┌────────────────────────────────────────────┐
+│  Your Application                          │
+├────────────────────────────────────────────┤
+│                                            │
+│  Private Key (for signing)     ────────┐   │
+│                                        │   │
+│  Public Key (for validation) ──────┐   │   │
+│                                    │   │   │
+│  xAuthJWSK (validates)       ◄─────┴───┘   │
+│                                            │
+│  Login Route (signs tokens)  ───────────┐  │
+│  Protected Routes (verify)   ◄──────────┘  │
+│                                            │
+└────────────────────────────────────────────┘
+```
+
+## Step 1: Generate Your Key Pair
+
+```javascript
+// generate-auth-keys.js
+import * as jose from 'jose';
+import fs from 'fs';
+
+async function generateAuthKeys() {
+  // Generate RSA key pair
+  const { publicKey, privateKey } = await jose.generateKeyPair('RS256');
+
+  // Export keys
+  const publicJwk = await jose.exportJWK(publicKey);
+  const privateKeyPem = await jose.exportPKCS8(privateKey);
+
+  // Create JWK with metadata for validation
+  const publicJwk_with_metadata = {
+    ...publicJwk,
+    use: 'sig',
+    alg: 'RS256',
+    kid: `auth-key-${Date.now()}`
+  };
+
+  // Save files
+  fs.writeFileSync('auth-key-private.pem', privateKeyPem);
+  fs.writeFileSync('auth-key-public.json', JSON.stringify(publicJwk_with_metadata, null, 2));
+
+  console.log('✅ Authentication keys generated');
+  console.log('   Private: auth-key-private.pem (keep secret!)');
+  console.log('   Public:  auth-key-public.json');
+  console.log('   Kid:     ' + publicJwk_with_metadata.kid);
+}
+
+generateAuthKeys().catch(console.error);
+```
+
+Run it:
+```bash
+node generate-auth-keys.js
+```
+
+## Step 2: Configure xAuthJWSK with Public Key
+
+```javascript
+// server.js
+import Fastify from 'fastify';
+import xAuthJWSK from '@xenterprises/fastify-xauth-jwks';
+import publicKeyJwk from './auth-key-public.json' assert { type: 'json' };
+import * as jose from 'jose';
+import fs from 'fs';
+
+const fastify = Fastify();
+
+// Register xAuthJWSK with the PUBLIC key (for validation)
+await fastify.register(xAuthJWSK, {
+  paths: {
+    api: {
+      pathPattern: '/api',
+      jwksData: publicKeyJwk,  // Single JWK for validation
+      excludedPaths: ['/login', '/register']
+    }
+  }
+});
+
+// Load private key for signing
+const privateKeyPem = fs.readFileSync('auth-key-private.pem', 'utf8');
+const privateKey = await jose.importPKCS8(privateKeyPem, 'RS256');
+
+// ============================================================================
+// Authentication Routes
+// ============================================================================
+
+// Login endpoint - signs JWT tokens
+fastify.post('/api/login', async (request, reply) => {
+  const { email, password } = request.body;
+
+  // TODO: Validate email/password against database
+  if (!email || !password) {
+    return reply.code(400).send({ error: 'Email and password required' });
+  }
+
+  // Verify user credentials (example)
+  const user = await validateCredentials(email, password);
+  if (!user) {
+    return reply.code(401).send({ error: 'Invalid credentials' });
+  }
+
+  // Create JWT token
+  const token = await new jose.SignJWT({
+    sub: user.id,
+    email: user.email,
+    name: user.name,
+    roles: user.roles || ['user'],
+    iat: Math.floor(Date.now() / 1000),
+    exp: Math.floor(Date.now() / 1000) + 86400,  // 24 hours
+  })
+    .setProtectedHeader({
+      alg: 'RS256',
+      kid: publicKeyJwk.kid,
+      typ: 'JWT'
+    })
+    .sign(privateKey);
+
+  return {
+    token,
+    user: {
+      id: user.id,
+      email: user.email,
+      name: user.name
+    }
+  };
+});
+
+// Register endpoint - signs JWT for new users
+fastify.post('/api/register', async (request, reply) => {
+  const { email, password, name } = request.body;
+
+  // TODO: Validate and create user in database
+  const user = await createUser(email, password, name);
+
+  // Sign token for new user
+  const token = await new jose.SignJWT({
+    sub: user.id,
+    email: user.email,
+    name: user.name,
+    roles: ['user'],
+    iat: Math.floor(Date.now() / 1000),
+    exp: Math.floor(Date.now() / 1000) + 86400,
+  })
+    .setProtectedHeader({
+      alg: 'RS256',
+      kid: publicKeyJwk.kid,
+      typ: 'JWT'
+    })
+    .sign(privateKey);
+
+  return {
+    token,
+    user: { id: user.id, email: user.email, name: user.name }
+  };
+});
+
+// Protected route - uses xAuthJWSK for validation
+fastify.get('/api/profile', async (request) => {
+  // xAuthJWSK automatically validates and populates request.auth
+  return {
+    message: 'Your profile',
+    userId: request.auth.userId,
+    email: request.auth.payload.email,
+    name: request.auth.payload.name
+  };
+});
+
+// Token refresh endpoint
+fastify.post('/api/refresh', async (request) => {
+  // xAuthJWSK validates the token first
+  const oldToken = request.auth.payload;
+
+  // Create new token with updated expiration
+  const newToken = await new jose.SignJWT({
+    sub: oldToken.sub,
+    email: oldToken.email,
+    name: oldToken.name,
+    roles: oldToken.roles,
+    iat: Math.floor(Date.now() / 1000),
+    exp: Math.floor(Date.now() / 1000) + 86400,
+  })
+    .setProtectedHeader({
+      alg: 'RS256',
+      kid: publicKeyJwk.kid,
+      typ: 'JWT'
+    })
+    .sign(privateKey);
+
+  return { token: newToken };
+});
+
+// ============================================================================
+// Start Server
+// ============================================================================
+
+await fastify.listen({ port: 3000 });
+console.log('✅ Server running on http://localhost:3000');
+console.log('\nAuthentication Endpoints:');
+console.log('  POST /api/login     - Login with email/password');
+console.log('  POST /api/register  - Create new account');
+console.log('  GET  /api/profile   - View profile (requires token)');
+console.log('  POST /api/refresh   - Refresh token expiration');
+
+// Stub functions - implement with your database
+async function validateCredentials(email, password) {
+  // TODO: Query database, verify password hash, return user object
+  // Example implementation with a database:
+  // 1. Query user by email: const user = await db.users.findOne({ email });
+  // 2. Verify password: const valid = await bcrypt.compare(password, user.passwordHash);
+  // 3. Return null if invalid, otherwise return user object with id, email, name, roles
+
+  // For testing - replace with actual database query
+  if (email === 'user@example.com' && password === 'password123') {
+    return {
+      id: 'user-123',
+      email: email,
+      name: 'Test User',
+      roles: ['user']
+    };
+  }
+  return null;
+}
+
+async function createUser(email, password, name) {
+  // TODO: Create user in database with hashed password
+  // Example implementation:
+  // 1. Validate email doesn't already exist
+  // 2. Hash password with bcrypt: const hash = await bcrypt.hash(password, 10);
+  // 3. Create user in database with email, passwordHash, name
+  // 4. Return user object with id, email, name, roles
+
+  // For testing - replace with actual database creation
+  return {
+    id: 'user-' + Date.now(),
+    email: email,
+    name: name,
+    roles: ['user']
+  };
+}
+```
+
+## Step 3: Test the Authentication Flow
+
+```bash
+# 1. Register a new user
+curl -X POST http://localhost:3000/api/register \
+  -H "Content-Type: application/json" \
+  -d '{"email":"user@example.com","password":"secret123","name":"John Doe"}'
+
+# Response:
+# {
+#   "token": "eyJhbGciOiJSUzI1NiI...",
+#   "user": {
+#     "id": "user-1234567890",
+#     "email": "user@example.com",
+#     "name": "John Doe"
+#   }
+# }
+
+# 2. Login with credentials
+curl -X POST http://localhost:3000/api/login \
+  -H "Content-Type: application/json" \
+  -d '{"email":"user@example.com","password":"secret123"}'
+
+# Response: Same format as register
+
+# 3. Access protected endpoint with token
+TOKEN="eyJhbGciOiJSUzI1NiI..."
+
+curl http://localhost:3000/api/profile \
+  -H "Authorization: Bearer $TOKEN"
+
+# Response:
+# {
+#   "message": "Your profile",
+#   "userId": "user-1234567890",
+#   "email": "user@example.com",
+#   "name": "John Doe"
+# }
+
+# 4. Refresh token
+curl -X POST http://localhost:3000/api/refresh \
+  -H "Authorization: Bearer $TOKEN"
+
+# Response:
+# {
+#   "token": "eyJhbGciOiJSUzI1NiI..."  # New token with extended expiration
+# }
+```
+
+## Architecture Advantages
+
+### Single Key Management
+
+```javascript
+// One key for signing AND validation
+const publicKeyJwk = { ... };  // Use in xAuthJWSK for validation
+const privateKey = importPKCS8(...);  // Use for signing
+```
+
+### Self-Contained Service
+
+- No external auth provider needed
+- No network calls for token validation
+- Complete control over token claims
+- Easy to test and develop
+
+### Production Ready
+
+```bash
+# Set environment variables for private key
+export AUTH_PRIVATE_KEY=$(cat auth-key-private.pem)
+export AUTH_KEY_ID="prod-key-$(date +%s)"
+
+# Load from environment in production
+const privateKey = await jose.importPKCS8(
+  process.env.AUTH_PRIVATE_KEY,
+  'RS256'
+);
+```
+
+### Multiple Tokens per User
+
+```javascript
+// Create different tokens for different purposes
+const accessToken = await signToken({
+  type: 'access',
+  sub: user.id,
+  exp: Math.floor(Date.now() / 1000) + 3600  // 1 hour
+});
+
+const refreshToken = await signToken({
+  type: 'refresh',
+  sub: user.id,
+  exp: Math.floor(Date.now() / 1000) + 604800  // 7 days
+});
+```
+
+## Integration with Email/Password Flows
+
+### Registration Flow
+
+```
+User Registration Form
+        ↓
+POST /api/register (email, password, name)
+        ↓
+Hash password, create user record
+        ↓
+Sign JWT with private key
+        ↓
+Return token + user info
+        ↓
+Client stores token (localStorage, httpOnly cookie, etc)
+        ↓
+Client uses token for API requests
+```
+
+### Login Flow
+
+```
+User Login Form
+        ↓
+POST /api/login (email, password)
+        ↓
+Verify password hash against database
+        ↓
+Sign JWT with private key
+        ↓
+Return token + user info
+        ↓
+Client stores token
+        ↓
+Client uses token for API requests
+```
+
+### Protected Route Access
+
+```
+Client Request
+  Header: Authorization: Bearer <token>
+        ↓
+xAuthJWSK validates signature with PUBLIC key
+        ↓
+JWT claims extracted and attached to request.auth
+        ↓
+Route handler accesses request.auth.userId, payload, etc.
+        ↓
+Process request and return response
+```
+
+## Security Considerations
+
+✅ **DO:**
+- Keep private key in environment variables or secure key storage
+- Use HTTPS in production
+- Set reasonable token expiration times
+- Hash passwords before storing
+- Use httpOnly cookies for tokens (if web app)
+- Implement logout by invalidating tokens server-side
+
+❌ **DON'T:**
+- Commit private keys to version control
+- Use weak passwords or short token expiration
+- Store private key in client-side code
+- Trust token claims without signature verification (xAuthJWSK handles this)
+- Use same key for signing and client authentication
+
+## Scaling to Multiple Services
+
+If you need multiple services to validate tokens:
+
+```javascript
+// Service A: Signs tokens with private key
+const token = await signToken({ sub: user.id, ... });
+
+// Service B, C, D: Validate with public key
+await fastify.register(xAuthJWSK, {
+  paths: {
+    api: {
+      pathPattern: '/api',
+      jwksData: publicKeyJwk  // Same public key
+    }
+  }
+});
+
+// All services can verify tokens signed by Service A
+```
+
+## Complete Example Repository
+
+See the full working example in `server/` directory:
+- `app.js` - Demo server with protected routes
+- `generate-demo-token.js` - Token generation utility
+- `example-jwks.json` - Example public key
+
+Run it:
+```bash
+node server/app.js
+node server/generate-demo-token.js admin user-123 admin
+```