@xenterprises/fastify-xauth-jwks 1.1.2 → 1.2.0

package/LICENSE

@@ -0,0 +1,60 @@
+PROPRIETARY SOFTWARE LICENSE
+
+Copyright (c) 2024-2026 X Enterprises LLC. All Rights Reserved.
+
+This software and associated documentation files (the "Software") are the
+exclusive property of X Enterprises LLC, a Washington limited liability
+company.
+
+TERMS AND CONDITIONS
+
+1. OWNERSHIP
+   All rights, title, and interest in and to the Software, including all
+   intellectual property rights, are and shall remain the exclusive property
+   of X Enterprises LLC.
+
+2. RESTRICTIONS
+   Without the prior written consent of X Enterprises LLC, you may not:
+   - Copy, modify, or distribute the Software
+   - Reverse engineer, decompile, or disassemble the Software
+   - Sublicense, sell, lease, or otherwise transfer the Software
+   - Remove or alter any proprietary notices or labels
+
+3. AUTHORIZED USE
+   Use of this Software is limited to authorized employees, contractors, and
+   agents of X Enterprises LLC, solely for purposes approved by X Enterprises
+   LLC.
+
+4. NO WARRANTY
+   THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL
+   X ENTERPRISES LLC BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY,
+   WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF,
+   OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+   SOFTWARE.
+
+5. LIMITATION OF LIABILITY
+   IN NO EVENT SHALL X ENTERPRISES LLC BE LIABLE FOR ANY INDIRECT, INCIDENTAL,
+   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+   PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
+   OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+   WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
+   OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+   ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+6. GOVERNING LAW
+   This license shall be governed by and construed in accordance with the laws
+   of the State of Washington, United States, without regard to its conflict
+   of law provisions.
+
+7. TERMINATION
+   This license is effective until terminated. X Enterprises LLC may terminate
+   this license at any time without notice. Upon termination, you must destroy
+   all copies of the Software in your possession.
+
+For licensing inquiries, contact: legal@x.enterprises
+
+---
+X Enterprises LLC
+Bothell, Washington, United States

package/README.md

@@ -1,20 +1,6 @@
-# xAuthJWSK
+# @xenterprises/fastify-xauth-jwks
 
-**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
+Path-based JWT/JWKS validation for Fastify v5. Protect multiple API paths with independent JWKS providers.
 
 ## Installation
 
@@ -22,52 +8,203 @@ Protect multiple API paths with independent JWKS providers. Simple, fast, and pr
 npm install @xenterprises/fastify-xauth-jwks
 ```
 
-## Quick Example
+## Quick Start
 
 ```javascript
-import Fastify from 'fastify';
-import xAuthJWSK from '@xenterprises/fastify-xauth-jwks';
+import Fastify from "fastify";
+import xAuth from "@xenterprises/fastify-xauth-jwks";
 
 const fastify = Fastify();
 
-await fastify.register(xAuthJWSK, {
+await fastify.register(xAuth, {
   paths: {
     admin: {
       pathPattern: "/admin",
       jwksUrl: "https://your-auth.com/.well-known/jwks.json",
-    }
-  }
+      excludedPaths: ["/health"],
+    },
+    portal: {
+      pathPattern: "/portal",
+      jwksUrl: "https://your-auth.com/.well-known/jwks.json",
+    },
+  },
 });
 
-fastify.get('/admin/users', (request) => {
-  return { userId: request.auth.userId };
+// Protected route - requires valid JWT
+fastify.get("/admin/dashboard", (request) => {
+  return { userId: request.auth.userId, user: request.user };
 });
 
-fastify.listen({ port: 3000 });
+// Excluded route - no auth required
+fastify.get("/admin/health", () => ({ status: "ok" }));
+
+// Public route - not under any protected path
+fastify.get("/public/info", () => ({ info: "open" }));
+
+await fastify.listen({ port: 3000 });
+```
+
+## Options
+
+The plugin accepts a single `paths` object where each key is a path name and each value is a path configuration:
+
+| Option | Type | Default | Required | Description |
+|---|---|---|---|---|
+| `paths` | `object` | — | Yes | Map of path name to path configuration. Must contain at least one entry. |
+
+### Path Configuration
+
+| Option | Type | Default | Required | Description |
+|---|---|---|---|---|
+| `pathPattern` | `string` | `/<pathName>` | No | URL prefix to protect. All routes starting with this prefix require authentication. |
+| `jwksUrl` | `string` | — | One of `jwksUrl` / `jwksData` | Remote JWKS endpoint URL for token verification. |
+| `jwksData` | `object` | — | One of `jwksUrl` / `jwksData` | Local JWKS data (`{ keys: [...] }`) or a single JWK object for development/testing. |
+| `active` | `boolean` | `true` | No | Set to `false` to skip registration of this path. |
+| `excludedPaths` | `string[]` | `[]` | No | Sub-paths that bypass authentication (e.g., `["/health", "/docs"]`). |
+| `jwksCooldownDuration` | `number` | `30000` | No | Minimum milliseconds between JWKS refetches (remote only). |
+| `jwksCacheMaxAge` | `number` | `1800000` | No | Maximum age in milliseconds for cached JWKS keys (remote only). |
+| `enablePayloadCache` | `boolean` | `true` | No | Cache verified JWT payloads in memory to avoid re-verification. |
+| `payloadCacheTTL` | `number` | `300000` | No | Time-to-live in milliseconds for cached JWT payloads. |
+
+## Decorated Properties
+
+After registration, the plugin decorates `fastify.xAuth`:
+
+| Property | Type | Description |
+|---|---|---|
+| `fastify.xAuth.validators` | `object` | Map of path name to validator object. |
+
+### Validator Object
+
+Each validator in `fastify.xAuth.validators.<name>` exposes:
+
+| Property / Method | Type | Description |
+|---|---|---|
+| `name` | `string` | Path name (e.g., `"admin"`). |
+| `pathPattern` | `string` | URL prefix being protected. |
+| `jwksUrl` | `string \| undefined` | Remote JWKS URL if configured. |
+| `config` | `object` | Caching configuration values. |
+| `verifyJWT(token)` | `async function` | Verify a JWT string. Returns the payload object or `null`. |
+| `clearPayloadCache()` | `function` | Clear the in-memory JWT payload cache. |
+| `getPayloadCacheStats()` | `function` | Returns `{ size, enabled, ttl }` for monitoring. |
+
+## Request Properties
+
+On authenticated requests, the plugin sets:
+
+| Property | Type | Description |
+|---|---|---|
+| `request.user` | `object` | Full JWT payload (claims). |
+| `request.auth.path` | `string` | Name of the path that authenticated this request. |
+| `request.auth.userId` | `string` | The `sub` claim from the JWT. |
+| `request.auth.payload` | `object` | Full JWT payload (same as `request.user`). |
+
+## Utility Exports
+
+Import from `@xenterprises/fastify-xauth-jwks/utils`:
+
+```javascript
+import {
+  extractToken,
+  hasRole,
+  hasPermission,
+  getUserId,
+  getAuthEndpoint,
+  requireRole,
+  requirePermission,
+  requireEndpoint,
+  decodeToken,
+  decodeHeader,
+} from "@xenterprises/fastify-xauth-jwks/utils";
 ```
 
-## Documentation
+| Utility | Signature | Description |
+|---|---|---|
+| `extractToken(request)` | `(req) => string \| null` | Extract Bearer token from Authorization header. |
+| `hasRole(user, roles)` | `(user, string \| string[]) => boolean` | Check if user has any of the specified roles (reads `user.roles`). |
+| `hasPermission(user, perms)` | `(user, string \| string[]) => boolean` | Check if user has any of the specified permissions (reads `user.permissions`). |
+| `getUserId(request)` | `(req) => string \| null` | Get user ID from `request.auth.userId` or `request.user.sub`. |
+| `getAuthEndpoint(request)` | `(req) => string \| null` | Get the auth path name from `request.auth.path`. |
+| `requireRole(roles)` | `(string \| string[]) => preHandler` | Fastify preHandler that returns 403 if user lacks the role. |
+| `requirePermission(perms)` | `(string \| string[]) => preHandler` | Fastify preHandler that returns 403 if user lacks the permission. |
+| `requireEndpoint(name)` | `(string) => preHandler` | Fastify preHandler that returns 403 if request was not authenticated by the named path. |
+| `decodeToken(token)` | `(string) => object` | Decode JWT payload without verification (re-export of `jose.decodeJwt`). |
+| `decodeHeader(token)` | `(string) => object` | Decode JWT header without verification (re-export of `jose.decodeProtectedHeader`). |
+
+### Usage with Route Hooks
+
+```javascript
+import { requireRole, requirePermission } from "@xenterprises/fastify-xauth-jwks/utils";
+
+fastify.get("/admin/settings", {
+  preHandler: requireRole("admin"),
+  handler: async (request) => ({ settings: "..." }),
+});
+
+fastify.delete("/admin/users/:id", {
+  preHandler: requirePermission("users:delete"),
+  handler: async (request) => ({ deleted: true }),
+});
+```
+
+## Environment Variables
+
+The plugin itself does not read environment variables. Your application should pass JWKS URLs from environment variables:
+
+| Variable | Required | Description |
+|---|---|---|
+| `ADMIN_JWKS_URL` | Per path | JWKS endpoint for admin path validation. |
+| `PORTAL_JWKS_URL` | Per path | JWKS endpoint for portal path validation. |
+
+Example:
+
+```javascript
+await fastify.register(xAuth, {
+  paths: {
+    admin: {
+      pathPattern: "/admin",
+      jwksUrl: process.env.ADMIN_JWKS_URL,
+    },
+  },
+});
+```
+
+## Error Reference
+
+| HTTP Status | Error | When |
+|---|---|---|
+| 401 | `Access token required` | No `Authorization: Bearer <token>` header present on a protected route. |
+| 401 | `Invalid token` | Token failed JWKS verification, is expired, or missing `sub` claim. |
+| 401 | `Authentication failed` | Unexpected error during authentication (logged server-side). |
+| 403 | `Insufficient permissions` | `requireRole` or `requirePermission` check failed. |
+| 403 | `Must authenticate via <name> endpoint` | `requireEndpoint` check failed. |
+
+Startup errors (thrown during plugin registration):
+
+| Error Message | Cause |
+|---|---|
+| `xAuth: options object is required` | No options passed to the plugin. |
+| `xAuth: 'paths' option is required and must contain at least one path configuration` | Empty or missing `paths` option. |
+| `<name>: Either jwksUrl or jwksData is required` | Path config missing both JWKS source options. |
+| `<name>: Cannot specify both jwksUrl and jwksData` | Path config has both JWKS source options. |
+
+## How It Works
+
+1. **Registration**: For each entry in `paths`, the plugin creates a path validator. Remote JWKS endpoints are set up via `jose.createRemoteJWKSet` with configurable caching; local JWKS data uses `jose.createLocalJWKSet`.
 
-**Getting Started:**
-- **[QUICK_START.md](./QUICK_START.md)** - Get started in 5 minutes
-- **[CONFIGURATION.md](./CONFIGURATION.md)** - Complete configuration reference (all options + examples)
+2. **Request Hook**: An `onRequest` hook checks every incoming request URL against each registered `pathPattern` using `String.startsWith()`. If the URL matches a protected path and is not in `excludedPaths`, the hook extracts the Bearer token and verifies it against the path's JWKS.
 
-**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
+3. **Caching**: Two levels of caching are used. JWKS keys are cached by the `jose` library with configurable cooldown and max age. JWT payloads can optionally be cached in a `Map` keyed by the raw token string, with configurable TTL.
 
-**Advanced:**
-- **[CACHING.md](./CACHING.md)** - Configure caching for performance
-- **[JOSE_UTILITIES.md](./JOSE_UTILITIES.md)** - Advanced JWT inspection
+4. **Request Decoration**: On successful verification, `request.user` is set to the full JWT payload and `request.auth` is set with the path name, user ID, and payload for downstream route handlers.
 
 ## Tests
 
 ```bash
 npm test
-# 49/49 tests passing ✅
+# 63 tests passing
 ```
 
 ## License
 
-ISC
+UNLICENSED

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xenterprises/fastify-xauth-jwks",
   "type": "module",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "description": "Fastify plugin for path-based JWT/JWKS validation. Protect multiple paths with independent JWKS providers.",
   "main": "src/index.js",
   "exports": {
@@ -22,7 +22,7 @@
     "path-based"
   ],
   "author": "Tim Mushen",
-  "license": "ISC",
+  "license": "UNLICENSED",
   "repository": {
     "type": "git",
     "url": "https://gitlab.com/x-enterprises/fastify-plugins/fastify-x-auth-jwks"

package/src/utils/index.js

@@ -67,7 +67,7 @@ export function getUserId(request) {
  * @returns {string|null}
  */
 export function getAuthEndpoint(request) {
-  return request.auth?.endpoint || null;
+  return request.auth?.path || null;
 }
 
 /**

package/src/xAuth.js

@@ -3,10 +3,16 @@ import fp from "fastify-plugin";
 import { createPathValidator } from "./services/pathValidator.js";
 
 async function xAuthPlugin(fastify, options) {
-  const { paths = {} } = options;
+  if (!options || typeof options !== "object") {
+    throw new Error("xAuth: options object is required");
+  }
+
+  const { paths } = options;
 
-  if (Object.keys(paths).length === 0) {
-    throw new Error("At least one protected path configuration is required");
+  if (!paths || typeof paths !== "object" || Object.keys(paths).length === 0) {
+    throw new Error(
+      "xAuth: 'paths' option is required and must contain at least one path configuration"
+    );
   }
 
   // Create xAuth namespace
@@ -33,4 +39,5 @@ async function xAuthPlugin(fastify, options) {
 
 export default fp(xAuthPlugin, {
   name: "xAuth",
+  fastify: ">=5.0.0",
 });

package/.gitlab-ci.yml

@@ -1,45 +0,0 @@
-# ============================================================================
-# GitLab CI/CD Pipeline - xAuthJWSK
-# ============================================================================
-# Runs tests on merge requests and commits to main/master
-
-stages:
-  - test
-
-variables:
-  NODE_ENV: test
-
-# ============================================================================
-# Shared Configuration
-# ============================================================================
-.shared_rules: &shared_rules
-  rules:
-    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
-    - if: '$CI_COMMIT_BRANCH == "main"'
-    - if: '$CI_COMMIT_BRANCH == "master"'
-    - if: '$CI_COMMIT_TAG'
-
-# ============================================================================
-# STAGE: TEST
-# ============================================================================
-test:
-  stage: test
-  image: node:20-alpine
-  <<: *shared_rules
-
-  cache:
-    key: ${CI_COMMIT_REF_SLUG}
-    paths:
-      - node_modules/
-
-  before_script:
-    - npm ci
-
-  script:
-    - echo "Running xAuthJWSK tests..."
-    - npm test
-    - npm audit --audit-level=high || true
-
-  retry:
-    max: 2
-    when: runner_system_failure