@xenterprises/fastify-xauth-jwks 1.0.0

package/README.md

@@ -0,0 +1,73 @@
+# xAuthJWSK
+
+**Lightweight, zero-config path-based JWT/JWKS validation for Fastify v5.**
+
+Protect multiple API paths with independent JWKS providers. Simple, fast, and production-ready.
+
+## Features
+
+✅ **Path-Based Protection** - Protect `/admin`, `/portal`, `/api` with different JWKS providers
+✅ **Bearer Token Validation** - Automatic JWT validation against remote JWKS endpoints
+✅ **Local or Remote JWKS** - Use remote URLs for production or local JWKS data for development
+✅ **Dual-Level Caching** - JWKS cache (30 min) + JWT payload cache (5 min)
+✅ **Excluded Paths** - Skip auth for health checks, docs, etc.
+✅ **Zero Dependencies** - Only uses `jose` and `fastify-plugin`
+✅ **Slim & Focused** - ~200 lines of core code, no bloat
+✅ **Configurable** - All caching parameters customizable
+✅ **Request Isolation** - Each path has separate validator & cache
+
+## Installation
+
+```bash
+npm install @xenterprises/fastify-xauth-jwks
+```
+
+## Quick Example
+
+```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",
+    }
+  }
+});
+
+fastify.get('/admin/users', (request) => {
+  return { userId: request.auth.userId };
+});
+
+fastify.listen({ port: 3000 });
+```
+
+## Documentation
+
+**Getting Started:**
+- **[QUICK_START.md](./QUICK_START.md)** - Get started in 5 minutes
+- **[CONFIGURATION.md](./CONFIGURATION.md)** - Complete configuration reference (all options + examples)
+
+**Examples & Guides:**
+- **[AUTHENTICATION_EXAMPLE.md](./AUTHENTICATION_EXAMPLE.md)** - Email/password auth with JWT signing
+- **[DEVELOPMENT.md](./DEVELOPMENT.md)** - Local development with test tokens
+- **[KEYS_GENERATION.md](./KEYS_GENERATION.md)** - Generate JWKS keys and test tokens
+
+**Advanced:**
+- **[CACHING.md](./CACHING.md)** - Configure caching for performance
+- **[JOSE_UTILITIES.md](./JOSE_UTILITIES.md)** - Advanced JWT inspection
+
+## Tests
+
+```bash
+npm test
+# 49/49 tests passing ✅
+```
+
+## License
+
+ISC

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@xenterprises/fastify-xauth-jwks",
+  "type": "module",
+  "version": "1.0.0",
+  "description": "Fastify plugin for path-based JWT/JWKS validation. Protect multiple paths with independent JWKS providers.",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./utils": "./src/utils/index.js"
+  },
+  "scripts": {
+    "start": "fastify start -l info server/app.js",
+    "dev": "fastify start -w -l info -P server/app.js",
+    "test": "node --test test/xAuth.test.js test/utils.test.js test/integration.test.js"
+  },
+  "keywords": [
+    "fastify",
+    "jwt",
+    "jwks",
+    "jose",
+    "validation",
+    "path-based"
+  ],
+  "author": "Tim Mushen",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/xenterprises/fastify-xauth-jwks"
+  },
+  "bugs": {
+    "url": "https://github.com/xenterprises/fastify-xauth-jwks/issues"
+  },
+  "homepage": "https://github.com/xenterprises/fastify-xauth-jwks#readme",
+  "dependencies": {
+    "fastify-plugin": "^5.0.0",
+    "jose": "^5.9.6"
+  },
+  "devDependencies": {
+    "fastify": "^5.1.0"
+  },
+  "peerDependencies": {
+    "fastify": "^5.0.0"
+  }
+}

package/server/app.js

@@ -0,0 +1,370 @@
+/**
+ * xAuthJWSK Demo Server
+ *
+ * Shows path-based JWT/JWKS validation with flexible configuration:
+ * - Development: Local JWKS data (example-jwks.json)
+ * - Production: Remote JWKS URLs (via environment variables)
+ *
+ * Environment Variables:
+ *   USE_LOCAL_JWKS=true          - Force local JWKS (dev mode)
+ *   ADMIN_JWKS_URL=https://...   - Admin path JWKS endpoint
+ *   PORTAL_JWKS_URL=https://...  - Portal path JWKS endpoint
+ *   PARTNER_JWKS_URL=https://... - Partner path JWKS endpoint
+ *   PORT=3000                    - Server port (default: 3000)
+ *
+ * Quick Start (Development):
+ *   npm run dev
+ *   node server/generate-demo-token.js admin user-123 admin
+ *   curl -H "Authorization: Bearer <TOKEN>" http://localhost:3000/admin/dashboard
+ *
+ * Production Setup:
+ *   export ADMIN_JWKS_URL="https://auth.example.com/.well-known/jwks.json"
+ *   export PORTAL_JWKS_URL="https://auth.example.com/.well-known/jwks.json"
+ *   npm start
+ */
+
+import Fastify from "fastify";
+import xAuthJWSK from "../src/xAuth.js";
+import { extractToken, decodeToken, decodeHeader, requireRole } from "../src/utils/index.js";
+import exampleJwks from "./example-jwks.json" assert { type: "json" };
+
+const fastify = Fastify({
+  logger: true,
+});
+
+// ============================================================================
+// Configuration Strategy
+// ============================================================================
+// Flexible configuration for both development and production:
+// - Development: Use local JWKS (example-jwks.json) - no external calls
+// - Production: Use remote JWKS URLs from environment variables
+const useLocalJwks = process.env.USE_LOCAL_JWKS === "true" || !process.env.ADMIN_JWKS_URL;
+
+// ============================================================================
+// Register xAuthJWSK Plugin
+// ============================================================================
+// Protect multiple API paths with independent JWKS providers
+// Each path can have different JWKS source, caching strategy, excluded paths
+// See CONFIGURATION.md for complete reference
+await fastify.register(xAuthJWSK, {
+  paths: {
+    // ========================================================================
+    // ADMIN API - Strict authentication (e.g., internal admin panel)
+    // ========================================================================
+    // Protected: /admin/*
+    // Excluded: /admin/health, /admin/status
+    // Use case: Internal dashboards, user management, sensitive operations
+    admin: {
+      pathPattern: "/admin",
+      // JWKS: Local OR remote (not both) - choose one
+      ...(useLocalJwks
+        ? { jwksData: exampleJwks }  // Development: local file
+        : { jwksUrl: process.env.ADMIN_JWKS_URL || "https://example.com/admin/.well-known/jwks.json" }),  // Production: env var
+      // Paths that don't require authentication (health checks, etc)
+      excludedPaths: ["/health", "/status"],
+      // Caching: Strict cache - refresh every 5 minutes
+      enablePayloadCache: true,
+      payloadCacheTTL: 300000,     // 5 min token payload cache
+      jwksCacheMaxAge: 1800000,    // 30 min JWKS cache (production keys rarely change)
+    },
+
+    // ========================================================================
+    // PORTAL API - User-facing (e.g., SaaS application)
+    // ========================================================================
+    // Protected: /portal/*
+    // Excluded: /portal/public/*, /portal/docs
+    // Use case: User dashboards, API access, profile management
+    portal: {
+      pathPattern: "/portal",
+      ...(useLocalJwks
+        ? { jwksData: exampleJwks }
+        : { jwksUrl: process.env.PORTAL_JWKS_URL || "https://example.com/portal/.well-known/jwks.json" }),
+      // Public endpoints (marketing pages, documentation)
+      excludedPaths: ["/public", "/docs"],
+      // Caching: Standard cache - balance performance and freshness
+      enablePayloadCache: true,
+      payloadCacheTTL: 300000,     // 5 min
+    },
+
+    // ========================================================================
+    // PARTNER API - Integration endpoint (e.g., webhooks, B2B integrations)
+    // ========================================================================
+    // Protected: /partner/*
+    // No excluded paths - all routes require authentication
+    // Use case: Partner integrations, webhooks, third-party API access
+    partner: {
+      pathPattern: "/partner",
+      ...(useLocalJwks
+        ? { jwksData: exampleJwks }
+        : { jwksUrl: process.env.PARTNER_JWKS_URL || "https://example.com/partner/.well-known/jwks.json" }),
+      // All routes require authentication - no exclusions
+      // Longer cache TTL - partner tokens typically valid longer
+      enablePayloadCache: true,
+      payloadCacheTTL: 600000,     // 10 min - partners have longer-lived tokens
+    },
+  },
+});
+
+// ============================================================================
+// Public Routes (No Authentication Required)
+// ============================================================================
+
+fastify.get("/", async () => {
+  return {
+    service: "xAuthJWSK Demo",
+    version: "1.0.0",
+    protectedPaths: Object.keys(fastify.xAuth.validators),
+    docs: "https://github.com/xenterprises/fastify-xauth-jwks",
+  };
+});
+
+fastify.get("/health", async () => {
+  return { status: "ok", timestamp: new Date().toISOString() };
+});
+
+// ============================================================================
+// Admin Routes (Protected by /admin)
+// ============================================================================
+
+fastify.get("/admin/health", async () => {
+  return { status: "healthy", service: "admin-api" };
+});
+
+fastify.get("/admin/status", async () => {
+  return { status: "operational", uptime: process.uptime() };
+});
+
+fastify.get("/admin/dashboard", async (request) => {
+  return {
+    message: "Admin Dashboard",
+    userId: request.auth.userId,
+    user: request.auth.payload,
+    authenticatedVia: request.auth.path,
+  };
+});
+
+fastify.get("/admin/users", async (request) => {
+  return {
+    message: "List of users",
+    adminId: request.auth.userId,
+    users: [
+      { id: "user_1", name: "John Doe", email: "john@example.com" },
+      { id: "user_2", name: "Jane Smith", email: "jane@example.com" },
+    ],
+  };
+});
+
+fastify.get("/admin/settings", {
+  preHandler: requireRole("admin"),
+  handler: async (request) => {
+    return {
+      message: "Admin settings (admin role required)",
+      adminId: request.auth.userId,
+      roles: request.user?.roles || [],
+    };
+  },
+});
+
+// Cache management endpoint
+fastify.post("/admin/cache/clear", async (request) => {
+  const validator = fastify.xAuth.validators.admin;
+  validator.clearPayloadCache();
+  return {
+    message: "Cache cleared",
+    stats: validator.getPayloadCacheStats(),
+  };
+});
+
+fastify.get("/admin/cache/stats", async (request) => {
+  const stats = {};
+  for (const [name, validator] of Object.entries(fastify.xAuth.validators)) {
+    stats[name] = validator.getPayloadCacheStats();
+  }
+  return { cacheStats: stats };
+});
+
+// ============================================================================
+// Portal Routes (Protected by /portal)
+// ============================================================================
+
+fastify.get("/portal/dashboard", async (request) => {
+  return {
+    message: "Portal Dashboard",
+    userId: request.auth.userId,
+    user: request.auth.payload,
+  };
+});
+
+fastify.get("/portal/profile", async (request) => {
+  return {
+    message: "User Profile",
+    userId: request.auth.userId,
+    email: request.user?.email,
+    name: request.user?.name,
+  };
+});
+
+fastify.get("/portal/public/docs", async () => {
+  return {
+    message: "API Documentation",
+    endpoints: ["GET /portal/dashboard", "GET /portal/profile", "POST /portal/update"],
+  };
+});
+
+fastify.get("/portal/public/pricing", async () => {
+  return {
+    plans: [
+      { tier: "free", price: 0 },
+      { tier: "pro", price: 29 },
+      { tier: "enterprise", price: 299 },
+    ],
+  };
+});
+
+// ============================================================================
+// Partner Routes (Protected by /partner)
+// ============================================================================
+
+fastify.get("/partner/api/data", async (request) => {
+  return {
+    message: "Partner API Data",
+    partnerId: request.auth.userId,
+    data: { status: "connected", lastSync: new Date().toISOString() },
+  };
+});
+
+fastify.get("/partner/api/webhooks", async (request) => {
+  return {
+    message: "Partner Webhooks",
+    partnerId: request.auth.userId,
+    webhooks: [
+      { id: "wh_1", event: "user.created", url: "https://partner.example.com/webhooks" },
+    ],
+  };
+});
+
+// ============================================================================
+// Token Inspection Endpoints (No Auth Required - for debugging)
+// ============================================================================
+
+fastify.post("/debug/decode-token", async (request, reply) => {
+  const { token } = request.body;
+
+  if (!token) {
+    return reply.code(400).send({ error: "Token required" });
+  }
+
+  try {
+    const header = decodeHeader(token);
+    const payload = decodeToken(token);
+
+    return {
+      header,
+      payload,
+      warning: "⚠️ This is UNVERIFIED token data. Only for debugging. Do NOT trust in production.",
+    };
+  } catch (error) {
+    return reply.code(400).send({ error: "Invalid token format" });
+  }
+});
+
+fastify.post("/debug/extract-token", async (request, reply) => {
+  const authHeader = request.headers.authorization;
+
+  if (!authHeader) {
+    return reply.code(400).send({ error: "Authorization header required" });
+  }
+
+  const token = extractToken(request);
+
+  if (!token) {
+    return reply.code(400).send({ error: "Invalid Bearer token format" });
+  }
+
+  try {
+    const payload = decodeToken(token);
+    return {
+      extracted: true,
+      userId: payload.sub,
+      expiresAt: new Date(payload.exp * 1000).toISOString(),
+      payload,
+    };
+  } catch (error) {
+    return reply.code(400).send({ error: "Failed to decode token" });
+  }
+});
+
+// ============================================================================
+// Validator Inspection Endpoint
+// ============================================================================
+
+fastify.get("/admin/validators", async (request) => {
+  const validators = {};
+  for (const [name, validator] of Object.entries(fastify.xAuth.validators)) {
+    validators[name] = {
+      name: validator.name,
+      pathPattern: validator.pathPattern,
+      jwksUrl: validator.jwksUrl,
+      config: validator.config,
+      cacheStats: validator.getPayloadCacheStats(),
+    };
+  }
+  return { validators };
+});
+
+// ============================================================================
+// Server Startup
+// ============================================================================
+
+const start = async () => {
+  try {
+    await fastify.listen({ port: process.env.PORT || 3000, host: "0.0.0.0" });
+
+    console.log("\n🚀 xAuthJWSK Demo Server Started!\n");
+    console.log(`Mode: ${useLocalJwks ? "🏠 LOCAL (Development)" : "☁️  REMOTE (Production)"}`);
+    if (useLocalJwks) {
+      console.log("     Using example-jwks.json - perfect for testing!");
+      console.log("     Generate test tokens: node server/generate-demo-token.js [path] [userId] [role]");
+    }
+    console.log("\nProtected Paths:");
+    for (const [name, validator] of Object.entries(fastify.xAuth.validators)) {
+      console.log(`\n  📍 ${name.toUpperCase()}`);
+      console.log(`     Path: ${validator.pathPattern}`);
+      console.log(`     JWKS: ${useLocalJwks ? "local (example-jwks.json)" : validator.jwksUrl}`);
+      console.log(`     Cache: ${validator.config.enablePayloadCache ? "enabled" : "disabled"}`);
+    }
+
+    console.log("\n\nPublic Endpoints:");
+    console.log("  GET  /                    - API info");
+    console.log("  GET  /health              - Health check");
+    console.log("  POST /debug/decode-token  - Decode JWT (debug only)");
+    console.log("  POST /debug/extract-token - Extract token from header");
+    console.log("  GET  /admin/validators    - View validator configs");
+
+    console.log("\n\nProtected Endpoints (require Bearer token):");
+    console.log("  GET  /admin/dashboard     - Admin dashboard");
+    console.log("  GET  /admin/users         - List users");
+    console.log("  GET  /admin/settings      - Settings (requires 'admin' role)");
+    console.log("  POST /admin/cache/clear   - Clear auth cache");
+    console.log("  GET  /admin/cache/stats   - View cache statistics");
+    console.log("  GET  /portal/dashboard    - Portal dashboard");
+    console.log("  GET  /portal/profile      - User profile");
+    console.log("  GET  /partner/api/data    - Partner data");
+
+    if (useLocalJwks) {
+      console.log("\n\n🧪 Testing with Local JWKS:");
+      console.log("  1. Generate a test token:");
+      console.log("     node server/generate-demo-token.js admin user-123 admin");
+      console.log("  2. Copy the token and test a protected endpoint:");
+      console.log("     curl -H \"Authorization: Bearer <TOKEN>\" http://localhost:3000/admin/dashboard");
+      console.log("  3. For more info, see KEYS_GENERATION.md and QUICK_START.md");
+    }
+
+    console.log("\n💡 Tip: Add '-H \"Authorization: Bearer YOUR_TOKEN\"' to protected requests\n");
+  } catch (err) {
+    fastify.log.error(err);
+    process.exit(1);
+  }
+};
+
+start();

package/server/example-jwks.json

@@ -0,0 +1,12 @@
+{
+  "keys": [
+    {
+      "kty": "RSA",
+      "use": "sig",
+      "alg": "RS256",
+      "kid": "demo-key-admin",
+      "n": "xjlCRBqkQWeBpaMWV2E2h6L1zcqmxm0W3Z5BbMwP9jfYEJ_ZHvMdV8fYaWDV8xzGqL7Z9fQaL7bXmVzYcPz0Xq5L_VmE8V7K0L1M2N3O4P5Q6R7S8T9U0V1W2X3Y4Z5A6B7C8D9E0F1G2H3I4J5K6L7M8N9O0P1Q2R3S4T5U6V7W8X9Y0Z1A2B3C4D5E6F7G8H9I0J1K2L3M4N5O6P7Q8R9S0T1U2V3W4X5Y6Z7A8B9C0D1E2F3G4H5I6J7K8L9M0N1O2P3Q4R5S6T7U8V9W0X1Y2Z3A4B5C6D7E8F9G0H1I2J3K4L5M6N7O8P9Q0R1S2T3U4V5W6X7Y8Z9",
+      "e": "AQAB"
+    }
+  ]
+}