@xenterprises/fastify-xauth-jwks 1.0.0

package/server/generate-demo-token.js

@@ -0,0 +1,232 @@
+#!/usr/bin/env node
+
+/**
+ * Generate demo JWT tokens for testing xAuthJWSK
+ *
+ * Usage:
+ *   node generate-demo-token.js [pathName] [userId] [role]
+ *
+ * Examples:
+ *   node generate-demo-token.js admin user-123 admin
+ *   node generate-demo-token.js portal user-456 user
+ *   node generate-demo-token.js partner partner-789
+ */
+
+import * as jose from 'jose';
+
+// Demo JWKS keys - these are public keys only
+// In production, private keys would be stored securely
+const demoKeys = {
+  admin: {
+    kid: 'demo-key-admin',
+    // This is a demo key for testing ONLY - never use in production
+    privateKeyPem: `-----BEGIN PRIVATE KEY-----
+MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDGOUJEGqRBZ4Gl
+oxZXYTaHovXNyqbGbRbdnkFszA/2N9gQn9ke8x1Xx9hpYNXzHMaovtn19BovttmZ
+XNhw/PRerkv9WYTxXsrQnUjczUjczVTNzNT0xM01M1MzQzM1M9T1M9M1TzU0MzU0
+M1MzQzMzQ0M1MzMzM1M1QzMzMzM1RDMzM1M1QzMzM1M1QzMzM1M1M1MzMzM1M1Mz
+MzM1M1MzMzM1M1MzMzMzUzMzMzM1M1MzMzMzUzMzMzM1M1MzMzMzUzMzMzM1M1Mz
+MzMzUzMzMzM1M1MzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMz
+MzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMz
+MzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMz
+AgMBAAECggEAQQECDQwVFBcWGRgbHBwdHR4eHx8gICEhISIiIiIjIyMjIyMkJCQk
+JCQlJSUlJSUlJSYmJiYmJiYmJiYnJycnJycnJycnJycnJycnJycnJycnJycnJycnJ
+yckJycnJycnJycoJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJyc
+nJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+cnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJycnJy
+-----END PRIVATE KEY-----`,
+  },
+};
+
+async function generateToken() {
+  const args = process.argv.slice(2);
+  const pathName = args[0] || 'admin';
+  const userId = args[1] || 'user-' + Math.random().toString(36).substring(7);
+  const role = args[2] || 'user';
+
+  const keyConfig = demoKeys[pathName];
+  if (!keyConfig) {
+    console.error(`❌ No demo key for path: ${pathName}`);
+    console.error(`   Available paths: ${Object.keys(demoKeys).join(', ')}`);
+    process.exit(1);
+  }
+
+  try {
+    // Import private key
+    const privateKey = await jose.importPKCS8(
+      keyConfig.privateKeyPem,
+      'RS256'
+    );
+
+    // Create JWT
+    const token = await new jose.SignJWT({
+      sub: userId,
+      userId: userId,
+      name: `Test User (${pathName})`,
+      email: `${userId}@example.com`,
+      roles: [role],
+      iat: Math.floor(Date.now() / 1000),
+      exp: Math.floor(Date.now() / 1000) + 3600, // 1 hour
+    })
+      .setProtectedHeader({
+        alg: 'RS256',
+        kid: `demo-key-${pathName}`,
+        typ: 'JWT',
+      })
+      .sign(privateKey);
+
+    console.log('🎫 Generated Test Token:\n');
+    console.log(token);
+    console.log('\n📋 Token Details:');
+    console.log(`   Path:     ${pathName}`);
+    console.log(`   User ID:  ${userId}`);
+    console.log(`   Role:     ${role}`);
+    console.log(`   Expires:  1 hour`);
+    console.log('\n🔗 Usage Examples:\n');
+    console.log('# cURL:');
+    console.log(`curl -H "Authorization: Bearer ${token}" \\`);
+    console.log(`  http://localhost:3000/${pathName}/dashboard\n`);
+    console.log('# JavaScript fetch:');
+    console.log(`fetch('http://localhost:3000/${pathName}/dashboard', {`);
+    console.log(`  headers: { Authorization: 'Bearer ${token}' }`);
+    console.log(`})\n`);
+    console.log('# Decode token (for inspection):');
+    console.log(`node -e "console.log(JSON.stringify(JSON.parse(Buffer.from('${token}'.split('.')[1], 'base64').toString()), null, 2))"\n`);
+  } catch (error) {
+    console.error('❌ Error generating token:', error.message);
+    process.exit(1);
+  }
+}
+
+generateToken();

package/src/index.js

@@ -0,0 +1,9 @@
+// src/index.js
+
+/**
+ * Main exports for xAuth plugin
+ */
+
+export { default } from "./xAuth.js";
+export { default as xAuth } from "./xAuth.js";
+export * as utils from "./utils/index.js";

package/src/services/pathValidator.js

@@ -0,0 +1,175 @@
+// src/services/pathValidator.js
+import * as jose from "jose";
+import { extractToken } from "../utils/index.js";
+
+export async function createPathValidator(fastify, pathName, config) {
+  const {
+    pathPattern = `/${pathName}`,
+    jwksUrl,
+    jwksData,
+    excludedPaths = [],
+    // JWKS caching configuration
+    jwksCooldownDuration = 30000, // 30 seconds between refetches
+    jwksCacheMaxAge = 1800000, // 30 minutes cache duration
+    // JWT payload caching configuration
+    enablePayloadCache = true,
+    payloadCacheTTL = 300000, // 5 minutes default
+  } = config;
+
+  // Validate configuration
+  if (!jwksUrl && !jwksData) {
+    throw new Error(`${pathName}: Either jwksUrl or jwksData is required`);
+  }
+
+  if (jwksUrl && jwksData) {
+    throw new Error(`${pathName}: Cannot specify both jwksUrl and jwksData`);
+  }
+
+  // Create JWKS for token verification
+  let jwks;
+  if (jwksUrl) {
+    // Remote JWKS endpoint
+    jwks = jose.createRemoteJWKSet(new URL(jwksUrl), {
+      cooldownDuration: jwksCooldownDuration,
+      cacheMaxAge: jwksCacheMaxAge,
+    });
+  } else {
+    // Local JWKS data - can be either:
+    // 1. Full JWKS object: { keys: [...] }
+    // 2. Single JWK key: { kty: "RSA", ... } (will be wrapped in JWKS format)
+    const jwksFormatted = jwksData.keys ? jwksData : { keys: [jwksData] };
+    jwks = jose.createLocalJWKSet(jwksFormatted);
+  }
+
+  // JWT payload cache (token -> {payload, expiresAt})
+  const payloadCache = new Map();
+
+  // Build full excluded paths
+  const fullExcludedPaths = excludedPaths.map((path) => {
+    if (path.startsWith("/")) {
+      return `${pathPattern}${path}`;
+    }
+    return `${pathPattern}/${path}`;
+  });
+
+  // JWT verification function with optional payload caching
+  async function verifyJWT(accessToken) {
+    try {
+      if (!accessToken || typeof accessToken !== "string") {
+        fastify.log.error(`[${pathName}] Invalid token format`);
+        return null;
+      }
+
+      // Check payload cache first if enabled
+      if (enablePayloadCache) {
+        const cached = payloadCache.get(accessToken);
+        if (cached && cached.expiresAt > Date.now()) {
+          return cached.payload;
+        } else if (cached) {
+          // Expired, remove from cache
+          payloadCache.delete(accessToken);
+        }
+      }
+
+      const { payload } = await jose.jwtVerify(accessToken, jwks);
+
+      if (!payload || !payload.sub) {
+        fastify.log.error(`[${pathName}] Invalid token payload`);
+        return null;
+      }
+
+      // Cache the payload if enabled
+      if (enablePayloadCache) {
+        payloadCache.set(accessToken, {
+          payload,
+          expiresAt: Date.now() + payloadCacheTTL,
+        });
+      }
+
+      return payload;
+    } catch (error) {
+      fastify.log.error(`[${pathName}] Token verification failed:`, error.message);
+      return null;
+    }
+  }
+
+  // Cache cleanup function (optional, for manual cache management)
+  function clearPayloadCache() {
+    payloadCache.clear();
+  }
+
+  // Get cache stats (for monitoring)
+  function getPayloadCacheStats() {
+    return {
+      size: payloadCache.size,
+      enabled: enablePayloadCache,
+      ttl: payloadCacheTTL,
+    };
+  }
+
+  // Authentication middleware
+  fastify.addHook("onRequest", async (request, reply) => {
+    const url = request.url;
+
+    // Only protect paths matching this pattern
+    if (!url.startsWith(pathPattern)) {
+      return;
+    }
+
+    // Skip excluded paths
+    if (fullExcludedPaths.some((path) => url.startsWith(path))) {
+      return;
+    }
+
+    try {
+      // Get token from header
+      const token = extractToken(request);
+      if (!token) {
+        return reply.code(401).send({
+          error: "Access token required",
+          path: pathName,
+        });
+      }
+
+      // Verify token
+      const payload = await verifyJWT(token);
+
+      if (!payload) {
+        return reply.code(401).send({
+          error: "Invalid token",
+          path: pathName,
+        });
+      }
+
+      // Set user info on request
+      request.user = payload;
+      request.auth = {
+        path: pathName,
+        userId: payload.sub,
+        payload,
+      };
+    } catch (err) {
+      fastify.log.error(`[${pathName}] Authentication failed:`, err);
+      return reply.code(401).send({
+        error: "Authentication failed",
+        path: pathName,
+      });
+    }
+  });
+
+  // Return validator info and methods
+  return {
+    name: pathName,
+    pathPattern,
+    jwksUrl,
+    verifyJWT,
+    clearPayloadCache,
+    getPayloadCacheStats,
+    config: {
+      jwksCooldownDuration,
+      jwksCacheMaxAge,
+      enablePayloadCache,
+      payloadCacheTTL,
+    },
+  };
+}

package/src/utils/index.js

@@ -0,0 +1,145 @@
+// src/utils/index.js
+import { decodeJwt, decodeProtectedHeader } from "jose";
+
+/**
+ * Extract JWT token from Authorization header
+ * @param {object} request - Fastify request object
+ * @returns {string|null} - JWT token or null
+ */
+export function extractToken(request) {
+  const authHeader = request.headers.authorization;
+
+  if (!authHeader || !authHeader.startsWith("Bearer ")) {
+    return null;
+  }
+
+  return authHeader.slice(7);
+}
+
+/**
+ * Check if user has specific role
+ * @param {object} user - User payload from JWT
+ * @param {string|Array<string>} roles - Role(s) to check
+ * @returns {boolean}
+ */
+export function hasRole(user, roles) {
+  if (!user || !user.roles) {
+    return false;
+  }
+
+  const userRoles = Array.isArray(user.roles) ? user.roles : [user.roles];
+  const requiredRoles = Array.isArray(roles) ? roles : [roles];
+
+  return requiredRoles.some((role) => userRoles.includes(role));
+}
+
+/**
+ * Check if user has specific permission
+ * @param {object} user - User payload from JWT
+ * @param {string|Array<string>} permissions - Permission(s) to check
+ * @returns {boolean}
+ */
+export function hasPermission(user, permissions) {
+  if (!user || !user.permissions) {
+    return false;
+  }
+
+  const userPermissions = Array.isArray(user.permissions)
+    ? user.permissions
+    : [user.permissions];
+  const requiredPermissions = Array.isArray(permissions) ? permissions : [permissions];
+
+  return requiredPermissions.some((permission) => userPermissions.includes(permission));
+}
+
+/**
+ * Get user ID from request
+ * @param {object} request - Fastify request object
+ * @returns {string|null}
+ */
+export function getUserId(request) {
+  return request.auth?.userId || request.user?.sub || null;
+}
+
+/**
+ * Get auth endpoint name from request
+ * @param {object} request - Fastify request object
+ * @returns {string|null}
+ */
+export function getAuthEndpoint(request) {
+  return request.auth?.endpoint || null;
+}
+
+/**
+ * Create role check decorator for Fastify routes
+ * @param {string|Array<string>} roles - Required role(s)
+ * @returns {Function} - Fastify preHandler hook
+ */
+export function requireRole(roles) {
+  return async function (request, reply) {
+    if (!hasRole(request.user, roles)) {
+      return reply.code(403).send({
+        error: "Forbidden",
+        message: "Insufficient permissions",
+      });
+    }
+  };
+}
+
+/**
+ * Create permission check decorator for Fastify routes
+ * @param {string|Array<string>} permissions - Required permission(s)
+ * @returns {Function} - Fastify preHandler hook
+ */
+export function requirePermission(permissions) {
+  return async function (request, reply) {
+    if (!hasPermission(request.user, permissions)) {
+      return reply.code(403).send({
+        error: "Forbidden",
+        message: "Insufficient permissions",
+      });
+    }
+  };
+}
+
+/**
+ * Create endpoint check decorator for Fastify routes
+ * @param {string} endpointName - Required endpoint name
+ * @returns {Function} - Fastify preHandler hook
+ */
+export function requireEndpoint(endpointName) {
+  return async function (request, reply) {
+    if (getAuthEndpoint(request) !== endpointName) {
+      return reply.code(403).send({
+        error: "Forbidden",
+        message: `Must authenticate via ${endpointName} endpoint`,
+      });
+    }
+  };
+}
+
+// ============================================================================
+// Re-exported jose utilities for advanced use cases
+// ============================================================================
+
+/**
+ * Decode JWT payload without verification
+ * Useful for inspecting token claims before processing
+ * @param {string} token - JWT token
+ * @returns {object} - Decoded payload
+ * @example
+ * const payload = decodeToken('eyJ...');
+ * console.log(payload.sub, payload.exp);
+ */
+export { decodeJwt as decodeToken };
+
+/**
+ * Decode JWT header without verification
+ * Useful for inspecting algorithm and key ID
+ * @param {string} token - JWT token
+ * @returns {object} - Decoded header
+ * @example
+ * const header = decodeHeader('eyJ...');
+ * console.log(header.alg, header.kid);
+ */
+export { decodeProtectedHeader as decodeHeader };

package/src/xAuth.js

@@ -0,0 +1,36 @@
+// src/xAuth.js
+import fp from "fastify-plugin";
+import { createPathValidator } from "./services/pathValidator.js";
+
+async function xAuthPlugin(fastify, options) {
+  const { paths = {} } = options;
+
+  if (Object.keys(paths).length === 0) {
+    throw new Error("At least one protected path configuration is required");
+  }
+
+  // Create xAuth namespace
+  const xAuth = {
+    validators: {},
+  };
+
+  // Setup validator for each path
+  for (const [pathName, pathConfig] of Object.entries(paths)) {
+    if (pathConfig.active === false) {
+      continue;
+    }
+
+    // Create path validator with JWKS
+    const validator = await createPathValidator(fastify, pathName, pathConfig);
+
+    // Store validator in xAuth namespace
+    xAuth.validators[pathName] = validator;
+  }
+
+  // Decorate Fastify with xAuth namespace
+  fastify.decorate("xAuth", xAuth);
+}
+
+export default fp(xAuthPlugin, {
+  name: "xAuth",
+});