@flink-app/jwt-auth-plugin 0.12.1-alpha.40 → 0.12.1-alpha.41

package/dist/FlinkJwtAuthPlugin.d.ts

@@ -1,5 +1,25 @@
-import { FlinkAuthPlugin, FlinkAuthUser } from "@flink-app/flink";
+import { FlinkAuthPlugin, FlinkAuthUser, FlinkRequest } from "@flink-app/flink";
 import jwtSimple from "jwt-simple";
+/**
+ * Custom token extraction callback.
+ *
+ * Return values:
+ * - `string`: Token found, use this token
+ * - `null`: No token found, authentication should fail
+ * - `undefined`: Skip custom extraction, use default Bearer token extraction
+ */
+export type TokenExtractor = (req: FlinkRequest) => string | null | undefined;
+/**
+ * Custom permission validation callback.
+ *
+ * Called after getUser to validate if the user has required permissions.
+ * Useful for dynamic permissions stored in database.
+ *
+ * @param user - The authenticated user object returned from getUser
+ * @param routePermissions - Array of permissions required by the route
+ * @returns true if user has required permissions, false otherwise
+ */
+export type PermissionChecker = (user: FlinkAuthUser, routePermissions: string[]) => Promise<boolean> | boolean;
 export interface JwtAuthPluginOptions {
     secret: string;
     algo?: jwtSimple.TAlgorithm;
@@ -9,6 +29,29 @@ export interface JwtAuthPluginOptions {
     rolePermissions: {
         [role: string]: string[];
     };
+    /**
+     * Optional custom token extraction callback.
+     *
+     * Allows conditional token extraction based on request properties (path, method, headers, etc.).
+     * Return `undefined` to fall back to default Bearer token extraction.
+     */
+    tokenExtractor?: TokenExtractor;
+    /**
+     * Optional custom permission checker for dynamic permissions.
+     *
+     * When provided, replaces static rolePermissions checking.
+     * Called after getUser with the full user object.
+     *
+     * Example:
+     * ```typescript
+     * checkPermissions: async (user, routePermissions) => {
+     *   return routePermissions.every(perm =>
+     *     user.permissions?.includes(perm)
+     *   );
+     * }
+     * ```
+     */
+    checkPermissions?: PermissionChecker;
 }
 export interface JwtAuthPlugin extends FlinkAuthPlugin {
     /**
@@ -38,4 +81,5 @@ export interface JwtAuthPlugin extends FlinkAuthPlugin {
 /**
  * Configures and creates authentication plugin.
  */
-export declare function jwtAuthPlugin({ secret, getUser, rolePermissions, algo, passwordPolicy, tokenTTL, }: JwtAuthPluginOptions): JwtAuthPlugin;
+export declare function jwtAuthPlugin({ secret, getUser, rolePermissions, algo, passwordPolicy, tokenTTL, //Defaults to hundred year
+tokenExtractor, checkPermissions, }: JwtAuthPluginOptions): JwtAuthPlugin;

package/dist/FlinkJwtAuthPlugin.js

@@ -65,7 +65,8 @@ var defaultPasswordPolicy = /^(?=.*[A-Za-z])(?=.*\d)[A-Za-z\d]{8,}$/;
  */
 function jwtAuthPlugin(_a) {
     var _this = this;
-    var secret = _a.secret, getUser = _a.getUser, rolePermissions = _a.rolePermissions, _b = _a.algo, algo = _b === void 0 ? "HS256" : _b, _c = _a.passwordPolicy, passwordPolicy = _c === void 0 ? defaultPasswordPolicy : _c, _d = _a.tokenTTL, tokenTTL = _d === void 0 ? 1000 * 60 * 60 * 24 * 365 * 100 : _d;
+    var secret = _a.secret, getUser = _a.getUser, rolePermissions = _a.rolePermissions, _b = _a.algo, algo = _b === void 0 ? "HS256" : _b, _c = _a.passwordPolicy, passwordPolicy = _c === void 0 ? defaultPasswordPolicy : _c, _d = _a.tokenTTL, tokenTTL = _d === void 0 ? 1000 * 60 * 60 * 24 * 365 * 100 : _d, //Defaults to hundred year
+    tokenExtractor = _a.tokenExtractor, checkPermissions = _a.checkPermissions;
     return {
         authenticateRequest: function (req, permissions) { return __awaiter(_this, void 0, void 0, function () {
             return __generator(this, function (_a) {
@@ -73,6 +74,8 @@ function jwtAuthPlugin(_a) {
                         algo: algo,
                         secret: secret,
                         getUser: getUser,
+                        tokenExtractor: tokenExtractor,
+                        checkPermissions: checkPermissions,
                     })];
             });
         }); },
@@ -84,13 +87,25 @@ function jwtAuthPlugin(_a) {
 exports.jwtAuthPlugin = jwtAuthPlugin;
 function authenticateRequest(req_1, routePermissions_1, rolePermissions_1, _a) {
     return __awaiter(this, arguments, void 0, function (req, routePermissions, rolePermissions, _b) {
-        var token, decodedToken, permissionsArr, validPerms, user;
-        var secret = _b.secret, algo = _b.algo, getUser = _b.getUser;
+        var token, decodedToken, permissionsArr, validPerms, user, hasPermission;
+        var secret = _b.secret, algo = _b.algo, getUser = _b.getUser, tokenExtractor = _b.tokenExtractor, checkPermissions = _b.checkPermissions;
         return __generator(this, function (_c) {
             switch (_c.label) {
                 case 0:
-                    token = getTokenFromReq(req);
-                    if (!token) return [3 /*break*/, 2];
+                    if (tokenExtractor) {
+                        token = tokenExtractor(req);
+                        // If tokenExtractor returns undefined, fall back to default
+                        if (token === undefined) {
+                            token = getTokenFromReq(req);
+                        }
+                        // If it returns null, token stays null (no default fallback)
+                        // If it returns string, token is the string
+                    }
+                    else {
+                        // No custom extractor, use default
+                        token = getTokenFromReq(req);
+                    }
+                    if (!token) return [3 /*break*/, 4];
                     decodedToken = void 0;
                     try {
                         decodedToken = jwt_simple_1.default.decode(token, secret, false, algo);
@@ -99,9 +114,10 @@ function authenticateRequest(req_1, routePermissions_1, rolePermissions_1, _a) {
                         flink_1.log.debug("[JWT AUTH PLUGIN] Failed to decode token: ".concat(err));
                         decodedToken = null;
                     }
-                    if (!decodedToken) return [3 /*break*/, 2];
+                    if (!decodedToken) return [3 /*break*/, 4];
                     permissionsArr = Array.isArray(routePermissions) ? routePermissions : [routePermissions];
-                    if (permissionsArr && permissionsArr.length > 0) {
+                    // Static permission check - only if custom checker NOT provided
+                    if (!checkPermissions && permissionsArr && permissionsArr.length > 0) {
                         validPerms = (0, PermissionValidator_1.hasValidPermissions)(decodedToken.roles || [], rolePermissions, permissionsArr);
                         if (!validPerms) {
                             return [2 /*return*/, false];
@@ -114,9 +130,19 @@ function authenticateRequest(req_1, routePermissions_1, rolePermissions_1, _a) {
                         flink_1.log.debug("[JWT AUTH PLUGIN] User not returned from getUser callback");
                         return [2 /*return*/, false];
                     }
+                    if (!(checkPermissions && permissionsArr && permissionsArr.length > 0)) return [3 /*break*/, 3];
+                    return [4 /*yield*/, checkPermissions(user, permissionsArr)];
+                case 2:
+                    hasPermission = _c.sent();
+                    if (!hasPermission) {
+                        flink_1.log.debug("[JWT AUTH PLUGIN] Custom permission check failed");
+                        return [2 /*return*/, false];
+                    }
+                    _c.label = 3;
+                case 3:
                     req.user = user;
                     return [2 /*return*/, true];
-                case 2: return [2 /*return*/, false];
+                case 4: return [2 /*return*/, false];
             }
         });
     });

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@flink-app/jwt-auth-plugin",
-    "version": "0.12.1-alpha.40",
+    "version": "0.12.1-alpha.41",
     "description": "Flink plugin for JWT auth",
     "scripts": {
         "test": "node --preserve-symlinks -r ts-node/register -- node_modules/jasmine/bin/jasmine --config=./spec/support/jasmine.json",
@@ -31,5 +31,5 @@
         "tsc-watch": "^4.2.9",
         "typescript": "5.4.5"
     },
-    "gitHead": "456502f273fe9473df05b71a803f3eda1a2f8931"
+    "gitHead": "76b54ee31f2c10c8c8f18af91facf5322b14ebf5"
 }

package/readme.md

@@ -10,6 +10,8 @@ A Flink authentication plugin that provides JWT (JSON Web Token) based authentic
 - Configurable password policies
 - Token expiration support
 - Bearer token authentication
+- Custom token extraction (query params, cookies, custom headers)
+- Dynamic permission checking (database-backed permissions)
 
 ## Installation
 
@@ -69,6 +71,8 @@ start();
 | `algo` | `jwtSimple.TAlgorithm` | No | `"HS256"` | JWT signing algorithm |
 | `passwordPolicy` | `RegExp` | No | `/^(?=.*[A-Za-z])(?=.*\d)[A-Za-z\d]{8,}$/` | Regex to validate password strength |
 | `tokenTTL` | `number` | No | `1000 * 60 * 60 * 24 * 365 * 100` (100 years) | Token time-to-live in milliseconds |
+| `tokenExtractor` | `(req: FlinkRequest) => string \| null \| undefined` | No | - | Custom token extraction function. Return `string` for token, `null` for no token, `undefined` to fallback to Bearer |
+| `checkPermissions` | `(user: FlinkAuthUser, routePermissions: string[]) => Promise<boolean> \| boolean` | No | - | Custom permission validator for dynamic permissions from database. Replaces static `rolePermissions` when provided |
 
 ### Default Password Policy
 
@@ -89,6 +93,355 @@ jwtAuthPlugin({
 })
 ```
 
+## Custom Token Extraction
+
+By default, the plugin extracts JWT tokens from the `Authorization` header as Bearer tokens:
+
+```
+Authorization: Bearer <token>
+```
+
+However, you can customize token extraction using the `tokenExtractor` option. This is useful for:
+- Mobile apps that pass tokens in query parameters
+- Cookie-based authentication for web routes
+- Custom header schemes for specific endpoints
+- Different auth methods for different route patterns
+
+### Token Extractor Return Values
+
+The `tokenExtractor` callback supports three return values:
+
+- **`string`**: Token found, use this token for authentication
+- **`null`**: No token found, authentication should fail (no fallback to default Bearer)
+- **`undefined`**: Skip custom extraction, use default Bearer token extraction
+
+### Example: Query Parameter for Public API Routes
+
+```typescript
+jwtAuthPlugin({
+  secret: process.env.JWT_SECRET!,
+  getUser: async (tokenData) => { /* ... */ },
+  rolePermissions: { /* ... */ },
+  tokenExtractor: (req) => {
+    // Allow query param tokens only for public API routes
+    if (req.path?.startsWith('/api/public/') && req.method === 'GET') {
+      return req.query?.token as string || null;
+    }
+    // All other routes use default Bearer token
+    return undefined;
+  }
+})
+```
+
+**Usage:**
+```
+GET /api/public/data?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+```
+
+### Example: Cookie-Based Auth for Web, Bearer for API
+
+```typescript
+jwtAuthPlugin({
+  secret: process.env.JWT_SECRET!,
+  getUser: async (tokenData) => { /* ... */ },
+  rolePermissions: { /* ... */ },
+  tokenExtractor: (req) => {
+    // Web routes use session cookie
+    if (req.path?.startsWith('/web/')) {
+      return req.cookies?.session_token || null;
+    }
+    // API routes use Bearer token (default)
+    return undefined;
+  }
+})
+```
+
+### Example: Custom Header for Webhooks
+
+```typescript
+jwtAuthPlugin({
+  secret: process.env.JWT_SECRET!,
+  getUser: async (tokenData) => { /* ... */ },
+  rolePermissions: { /* ... */ },
+  tokenExtractor: (req) => {
+    // Webhook endpoints use custom header
+    if (req.path?.startsWith('/webhooks/')) {
+      return req.headers['x-webhook-signature'] as string || null;
+    }
+    // Other routes use Bearer token
+    return undefined;
+  }
+})
+```
+
+### Example: Method-Based Extraction
+
+```typescript
+jwtAuthPlugin({
+  secret: process.env.JWT_SECRET!,
+  getUser: async (tokenData) => { /* ... */ },
+  rolePermissions: { /* ... */ },
+  tokenExtractor: (req) => {
+    // Special handling for PATCH requests
+    if (req.method === 'PATCH') {
+      return req.headers['x-patch-token'] as string || null;
+    }
+    // All other methods use Bearer
+    return undefined;
+  }
+})
+```
+
+### Example: Multiple Fallbacks
+
+```typescript
+jwtAuthPlugin({
+  secret: process.env.JWT_SECRET!,
+  getUser: async (tokenData) => { /* ... */ },
+  rolePermissions: { /* ... */ },
+  tokenExtractor: (req) => {
+    // Try cookie first for browser requests
+    if (req.headers['user-agent']?.includes('Mozilla')) {
+      const cookieToken = req.cookies?.auth_token;
+      if (cookieToken) return cookieToken;
+    }
+
+    // Try query param for mobile apps
+    if (req.query?.token) {
+      return req.query.token as string;
+    }
+
+    // Fall back to default Bearer token extraction
+    return undefined;
+  }
+})
+```
+
+### Important Notes
+
+- When `tokenExtractor` returns `undefined`, the plugin falls back to extracting from `Authorization: Bearer <token>`
+- When it returns `null`, authentication fails immediately (useful to enforce specific auth methods for certain routes)
+- When it returns a `string`, that token is validated using the same JWT verification logic
+- The callback has access to `req.path`, `req.method`, `req.headers`, `req.query`, `req.cookies`, etc.
+
+## Dynamic Permissions with Database
+
+By default, the plugin uses static `rolePermissions` defined at configuration time. However, you can implement dynamic permissions that are fetched from the database on each request using the `checkPermissions` callback.
+
+### When to Use Dynamic Permissions
+
+Use `checkPermissions` when:
+- Permissions are stored in the database per user or per role
+- Permissions can change without restarting the application
+- Different organizations/tenants have different permission sets
+- You need fine-grained, user-specific permissions
+
+### How It Works
+
+When you provide `checkPermissions`:
+1. Token is extracted and decoded (same as before)
+2. Static `rolePermissions` check is **skipped**
+3. `getUser` is called - this is where you fetch permissions from DB
+4. `checkPermissions` is called with the user object and required route permissions
+5. If `checkPermissions` returns `true`, authentication succeeds
+
+### Basic Example
+
+```typescript
+jwtAuthPlugin({
+  secret: process.env.JWT_SECRET!,
+
+  getUser: async (tokenData) => {
+    // Fetch user from database
+    const user = await ctx.repos.userRepo.getById(tokenData.userId);
+
+    // Fetch user's permissions from database
+    const permissions = await ctx.repos.permissionRepo.getUserPermissions(user._id);
+
+    return {
+      id: user._id,
+      username: user.username,
+      roles: user.roles,
+      permissions,  // Attach permissions to user object
+    };
+  },
+
+  // rolePermissions can be empty when using dynamic permissions
+  rolePermissions: {},
+
+  // Custom permission checker
+  checkPermissions: async (user, routePermissions) => {
+    // User must have ALL required permissions
+    return routePermissions.every(perm =>
+      user.permissions?.includes(perm)
+    );
+  },
+})
+```
+
+### Multi-Tenant Example
+
+```typescript
+jwtAuthPlugin({
+  secret: process.env.JWT_SECRET!,
+
+  getUser: async (tokenData) => {
+    const user = await ctx.repos.userRepo.getById(tokenData.userId);
+
+    // Fetch permissions based on user's organization
+    const permissions = await ctx.repos.permissionRepo.getOrgPermissions(
+      user._id,
+      user.organizationId
+    );
+
+    return {
+      id: user._id,
+      username: user.username,
+      organizationId: user.organizationId,
+      permissions,
+    };
+  },
+
+  rolePermissions: {},
+
+  checkPermissions: async (user, routePermissions) => {
+    return routePermissions.every(perm =>
+      user.permissions?.includes(perm)
+    );
+  },
+})
+```
+
+### Hybrid: Role-Based + User-Specific Permissions
+
+```typescript
+jwtAuthPlugin({
+  secret: process.env.JWT_SECRET!,
+
+  getUser: async (tokenData) => {
+    const user = await ctx.repos.userRepo.getById(tokenData.userId);
+
+    // Get base permissions from roles
+    const rolePerms = await ctx.repos.roleRepo.getRolePermissions(user.roles);
+
+    // Get user-specific permission overrides
+    const userPerms = await ctx.repos.permissionRepo.getUserPermissions(user._id);
+
+    // Combine both
+    const allPermissions = [...new Set([...rolePerms, ...userPerms])];
+
+    return {
+      id: user._id,
+      username: user.username,
+      roles: user.roles,
+      permissions: allPermissions,
+    };
+  },
+
+  rolePermissions: {},
+
+  checkPermissions: async (user, routePermissions) => {
+    return routePermissions.every(perm =>
+      user.permissions?.includes(perm)
+    );
+  },
+})
+```
+
+### Permission with Wildcards
+
+```typescript
+checkPermissions: async (user, routePermissions) => {
+  // Support wildcard permissions
+  if (user.permissions?.includes("*")) {
+    return true; // User has all permissions
+  }
+
+  // Check specific permissions
+  return routePermissions.every(perm =>
+    user.permissions?.includes(perm)
+  );
+}
+```
+
+### Permission with OR Logic
+
+```typescript
+checkPermissions: async (user, routePermissions) => {
+  // User needs ANY of the route permissions (OR logic)
+  return routePermissions.some(perm =>
+    user.permissions?.includes(perm)
+  );
+}
+```
+
+### Caching Permissions for Performance
+
+To reduce database load, you can cache permissions:
+
+```typescript
+const permissionCache = new Map();
+const CACHE_TTL = 5 * 60 * 1000; // 5 minutes
+
+jwtAuthPlugin({
+  secret: process.env.JWT_SECRET!,
+
+  getUser: async (tokenData) => {
+    const user = await ctx.repos.userRepo.getById(tokenData.userId);
+
+    // Check cache first
+    const cacheKey = `perms:${user._id}`;
+    const cached = permissionCache.get(cacheKey);
+
+    if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
+      return {
+        id: user._id,
+        username: user.username,
+        permissions: cached.permissions,
+      };
+    }
+
+    // Fetch from DB
+    const permissions = await ctx.repos.permissionRepo.getUserPermissions(user._id);
+
+    // Cache it
+    permissionCache.set(cacheKey, {
+      permissions,
+      timestamp: Date.now(),
+    });
+
+    return {
+      id: user._id,
+      username: user.username,
+      permissions,
+    };
+  },
+
+  rolePermissions: {},
+  checkPermissions: async (user, routePermissions) => {
+    return routePermissions.every(perm => user.permissions?.includes(perm));
+  },
+})
+```
+
+### Dynamic Permissions Notes
+
+- **Backward Compatible**: If you don't provide `checkPermissions`, static `rolePermissions` are used (existing behavior)
+- **Performance**: `checkPermissions` is called on every authenticated request, so ensure `getUser` is optimized (consider caching)
+- **User Object**: The `user` parameter in `checkPermissions` is the exact object returned from `getUser`
+- **Public Routes**: If a route has no permissions (`[]`), `checkPermissions` is NOT called
+- **Sync or Async**: `checkPermissions` can return `Promise<boolean>` or `boolean`
+
+### Troubleshooting Dynamic Permissions
+
+**Issue**: Too many database queries
+
+**Solution**: Implement permission caching in `getUser` or use an in-memory cache like Redis
+
+**Issue**: Permissions not updating after database change
+
+**Solution**: Clear permission cache or reduce cache TTL
+
 ## Context API
 
 Once configured, the plugin provides the following methods via the `auth` context:
@@ -542,6 +895,15 @@ Implement rate limiting on authentication endpoints to prevent brute force attac
 ```typescript
 import { JwtAuthPlugin, JwtAuthPluginOptions } from "@flink-app/jwt-auth-plugin";
 
+// Token extractor callback type
+type TokenExtractor = (req: FlinkRequest) => string | null | undefined;
+
+// Permission checker callback type
+type PermissionChecker = (
+  user: FlinkAuthUser,
+  routePermissions: string[]
+) => Promise<boolean> | boolean;
+
 // Plugin options
 interface JwtAuthPluginOptions {
   secret: string;
@@ -552,6 +914,8 @@ interface JwtAuthPluginOptions {
   rolePermissions: {
     [role: string]: string[];
   };
+  tokenExtractor?: TokenExtractor;
+  checkPermissions?: PermissionChecker;
 }
 
 // Plugin interface

package/spec/FlinkJwtAuthPlugin.spec.ts

@@ -126,4 +126,447 @@ describe("FlinkJwtAuthPlugin", () => {
 
     expect(decoded.id).toBe("123");
   });
+
+  describe("tokenExtractor", () => {
+    it("should use custom token extractor when it returns a string", async () => {
+      const secret = "secret";
+      const userId = "123";
+      const customToken = jwtSimple.encode(
+        { id: userId, roles: ["user"] },
+        secret
+      );
+
+      const plugin = jwtAuthPlugin({
+        secret,
+        getUser: async ({ id }: { id: string }) => {
+          expect(id).toBe(userId);
+          return {
+            id,
+            username: "username",
+          };
+        },
+        rolePermissions: {
+          user: ["*"],
+        },
+        tokenExtractor: (req) => {
+          // Extract from query param
+          return req.query?.token as string;
+        },
+      });
+
+      const mockRequest = {
+        headers: {},
+        query: {
+          token: customToken,
+        },
+      } as unknown as FlinkRequest;
+
+      const authenticated = await plugin.authenticateRequest(mockRequest, "foo");
+
+      expect(authenticated).toBeTruthy();
+    });
+
+    it("should fail auth when tokenExtractor returns null", async () => {
+      const plugin = jwtAuthPlugin({
+        secret: "secret",
+        getUser: async (id: string) => {
+          fail(); // Should not be called
+          return {
+            id,
+            username: "username",
+          };
+        },
+        rolePermissions: {
+          user: ["*"],
+        },
+        tokenExtractor: (req) => {
+          // Explicitly no token for this route
+          return null;
+        },
+      });
+
+      const mockRequest = {
+        headers: {
+          authorization: "Bearer some-valid-token",
+        },
+      } as FlinkRequest;
+
+      const authenticated = await plugin.authenticateRequest(mockRequest, "foo");
+
+      expect(authenticated).toBeFalse();
+    });
+
+    it("should fall back to Bearer token when tokenExtractor returns undefined", async () => {
+      const secret = "secret";
+      const userId = "123";
+      const encodedToken = jwtSimple.encode(
+        { id: userId, roles: ["user"] },
+        secret
+      );
+
+      const plugin = jwtAuthPlugin({
+        secret,
+        getUser: async ({ id }: { id: string }) => {
+          expect(id).toBe(userId);
+          return {
+            id,
+            username: "username",
+          };
+        },
+        rolePermissions: {
+          user: ["*"],
+        },
+        tokenExtractor: (req) => {
+          // Return undefined to fall back to default
+          return undefined;
+        },
+      });
+
+      const mockRequest = {
+        headers: {
+          authorization: "Bearer " + encodedToken,
+        },
+      } as FlinkRequest;
+
+      const authenticated = await plugin.authenticateRequest(mockRequest, "foo");
+
+      expect(authenticated).toBeTruthy();
+    });
+
+    it("should support conditional extraction based on path", async () => {
+      const secret = "secret";
+      const userId = "123";
+      const queryToken = jwtSimple.encode(
+        { id: userId, roles: ["user"] },
+        secret
+      );
+      const bearerToken = jwtSimple.encode(
+        { id: userId, roles: ["user"] },
+        secret
+      );
+
+      const plugin = jwtAuthPlugin({
+        secret,
+        getUser: async ({ id }: { id: string }) => {
+          return {
+            id,
+            username: "username",
+          };
+        },
+        rolePermissions: {
+          user: ["*"],
+        },
+        tokenExtractor: (req) => {
+          // Use query param for public API routes only
+          if (req.path?.startsWith("/api/public/")) {
+            return req.query?.token as string || null;
+          }
+          // Fall back to Bearer for other routes
+          return undefined;
+        },
+      });
+
+      // Test public route with query param
+      const publicRequest = {
+        path: "/api/public/data",
+        headers: {},
+        query: {
+          token: queryToken,
+        },
+      } as unknown as FlinkRequest;
+
+      const publicAuth = await plugin.authenticateRequest(publicRequest, "foo");
+      expect(publicAuth).toBeTruthy();
+
+      // Test non-public route with Bearer token
+      const privateRequest = {
+        path: "/api/private/data",
+        headers: {
+          authorization: "Bearer " + bearerToken,
+        },
+      } as unknown as FlinkRequest;
+
+      const privateAuth = await plugin.authenticateRequest(privateRequest, "foo");
+      expect(privateAuth).toBeTruthy();
+    });
+
+    it("should use default Bearer extraction when no tokenExtractor provided", async () => {
+      const secret = "secret";
+      const userId = "123";
+      const encodedToken = jwtSimple.encode(
+        { id: userId, roles: ["user"] },
+        secret
+      );
+
+      const plugin = jwtAuthPlugin({
+        secret,
+        getUser: async ({ id }: { id: string }) => {
+          return {
+            id,
+            username: "username",
+          };
+        },
+        rolePermissions: {
+          user: ["*"],
+        },
+        // No tokenExtractor provided
+      });
+
+      const mockRequest = {
+        headers: {
+          authorization: "Bearer " + encodedToken,
+        },
+      } as FlinkRequest;
+
+      const authenticated = await plugin.authenticateRequest(mockRequest, "foo");
+
+      expect(authenticated).toBeTruthy();
+    });
+  });
+
+  describe("checkPermissions callback", () => {
+    it("should use custom permission checker when provided", async () => {
+      const secret = "secret";
+      const userId = "123";
+      const encodedToken = jwtSimple.encode(
+        { id: userId, roles: ["user"] },
+        secret
+      );
+
+      const plugin = jwtAuthPlugin({
+        secret,
+        getUser: async ({ id }: { id: string }) => {
+          return {
+            id,
+            username: "testuser",
+            permissions: ["read", "write", "delete"],
+          };
+        },
+        rolePermissions: {
+          user: [], // Empty - custom checker will handle this
+        },
+        checkPermissions: async (user, routePermissions) => {
+          // Check if user has all required permissions
+          return routePermissions.every((perm) =>
+            user.permissions?.includes(perm)
+          );
+        },
+      });
+
+      const mockRequest = {
+        headers: {
+          authorization: "Bearer " + encodedToken,
+        },
+      } as FlinkRequest;
+
+      const authenticated = await plugin.authenticateRequest(mockRequest, [
+        "read",
+        "write",
+      ]);
+
+      expect(authenticated).toBeTruthy();
+      expect(mockRequest.user?.permissions).toEqual([
+        "read",
+        "write",
+        "delete",
+      ]);
+    });
+
+    it("should fail auth when custom checker returns false", async () => {
+      const secret = "secret";
+      const userId = "123";
+      const encodedToken = jwtSimple.encode(
+        { id: userId, roles: ["user"] },
+        secret
+      );
+
+      const plugin = jwtAuthPlugin({
+        secret,
+        getUser: async ({ id }: { id: string }) => {
+          return {
+            id,
+            username: "testuser",
+            permissions: ["read"], // Only has read
+          };
+        },
+        rolePermissions: {},
+        checkPermissions: async (user, routePermissions) => {
+          return routePermissions.every((perm) =>
+            user.permissions?.includes(perm)
+          );
+        },
+      });
+
+      const mockRequest = {
+        headers: {
+          authorization: "Bearer " + encodedToken,
+        },
+      } as FlinkRequest;
+
+      // Route requires write, but user only has read
+      const authenticated = await plugin.authenticateRequest(mockRequest, [
+        "read",
+        "write",
+      ]);
+
+      expect(authenticated).toBeFalse();
+    });
+
+    it("should use static rolePermissions when checkPermissions not provided (backward compat)", async () => {
+      const secret = "secret";
+      const userId = "123";
+      const encodedToken = jwtSimple.encode(
+        { id: userId, roles: ["admin"] },
+        secret
+      );
+
+      const plugin = jwtAuthPlugin({
+        secret,
+        getUser: async ({ id }: { id: string }) => {
+          return {
+            id,
+            username: "admin",
+          };
+        },
+        rolePermissions: {
+          admin: ["read", "write", "delete"],
+        },
+        // No checkPermissions provided - uses static
+      });
+
+      const mockRequest = {
+        headers: {
+          authorization: "Bearer " + encodedToken,
+        },
+      } as FlinkRequest;
+
+      const authenticated = await plugin.authenticateRequest(
+        mockRequest,
+        "write"
+      );
+
+      expect(authenticated).toBeTruthy();
+    });
+
+    it("should support synchronous permission checker", async () => {
+      const secret = "secret";
+      const userId = "123";
+      const encodedToken = jwtSimple.encode(
+        { id: userId, roles: ["user"] },
+        secret
+      );
+
+      const plugin = jwtAuthPlugin({
+        secret,
+        getUser: async ({ id }: { id: string }) => {
+          return {
+            id,
+            username: "testuser",
+            permissions: ["read"],
+          };
+        },
+        rolePermissions: {},
+        // Synchronous checker (not async)
+        checkPermissions: (user, routePermissions) => {
+          return routePermissions.every((perm) =>
+            user.permissions?.includes(perm)
+          );
+        },
+      });
+
+      const mockRequest = {
+        headers: {
+          authorization: "Bearer " + encodedToken,
+        },
+      } as FlinkRequest;
+
+      const authenticated = await plugin.authenticateRequest(
+        mockRequest,
+        "read"
+      );
+
+      expect(authenticated).toBeTruthy();
+    });
+
+    it("should pass when route has no permissions and custom checker provided", async () => {
+      const secret = "secret";
+      const userId = "123";
+      const encodedToken = jwtSimple.encode(
+        { id: userId, roles: ["user"] },
+        secret
+      );
+
+      let checkerCalled = false;
+
+      const plugin = jwtAuthPlugin({
+        secret,
+        getUser: async ({ id }: { id: string }) => {
+          return { id, username: "testuser" };
+        },
+        rolePermissions: {},
+        checkPermissions: async (user, routePermissions) => {
+          checkerCalled = true;
+          return true;
+        },
+      });
+
+      const mockRequest = {
+        headers: {
+          authorization: "Bearer " + encodedToken,
+        },
+      } as FlinkRequest;
+
+      // Empty permissions (public route)
+      const authenticated = await plugin.authenticateRequest(mockRequest, []);
+
+      expect(authenticated).toBeTruthy();
+      expect(checkerCalled).toBeFalse(); // Checker should not be called for public routes
+    });
+
+    it("should handle database-fetched permissions in getUser", async () => {
+      const secret = "secret";
+      const userId = "123";
+      const encodedToken = jwtSimple.encode(
+        { id: userId, roles: ["user"] },
+        secret
+      );
+
+      // Simulate DB permissions
+      const dbPermissions: { [key: string]: string[] } = {
+        "123": ["read", "write", "custom_permission"],
+      };
+
+      const plugin = jwtAuthPlugin({
+        secret,
+        getUser: async ({ id }: { id: string }) => {
+          // Simulate fetching permissions from DB
+          const permissions = dbPermissions[id] || [];
+          return {
+            id,
+            username: "testuser",
+            permissions,
+          };
+        },
+        rolePermissions: {},
+        checkPermissions: async (user, routePermissions) => {
+          return routePermissions.every((perm) =>
+            user.permissions?.includes(perm)
+          );
+        },
+      });
+
+      const mockRequest = {
+        headers: {
+          authorization: "Bearer " + encodedToken,
+        },
+      } as FlinkRequest;
+
+      const authenticated = await plugin.authenticateRequest(mockRequest, [
+        "custom_permission",
+      ]);
+
+      expect(authenticated).toBeTruthy();
+      expect(mockRequest.user?.permissions).toContain("custom_permission");
+    });
+  });
 });

package/src/FlinkJwtAuthPlugin.ts

@@ -9,6 +9,31 @@ import { hasValidPermissions } from "./PermissionValidator";
  */
 const defaultPasswordPolicy = /^(?=.*[A-Za-z])(?=.*\d)[A-Za-z\d]{8,}$/;
 
+/**
+ * Custom token extraction callback.
+ *
+ * Return values:
+ * - `string`: Token found, use this token
+ * - `null`: No token found, authentication should fail
+ * - `undefined`: Skip custom extraction, use default Bearer token extraction
+ */
+export type TokenExtractor = (req: FlinkRequest) => string | null | undefined;
+
+/**
+ * Custom permission validation callback.
+ *
+ * Called after getUser to validate if the user has required permissions.
+ * Useful for dynamic permissions stored in database.
+ *
+ * @param user - The authenticated user object returned from getUser
+ * @param routePermissions - Array of permissions required by the route
+ * @returns true if user has required permissions, false otherwise
+ */
+export type PermissionChecker = (
+    user: FlinkAuthUser,
+    routePermissions: string[]
+) => Promise<boolean> | boolean;
+
 export interface JwtAuthPluginOptions {
     secret: string;
     algo?: jwtSimple.TAlgorithm;
@@ -18,6 +43,29 @@ export interface JwtAuthPluginOptions {
     rolePermissions: {
         [role: string]: string[];
     };
+    /**
+     * Optional custom token extraction callback.
+     *
+     * Allows conditional token extraction based on request properties (path, method, headers, etc.).
+     * Return `undefined` to fall back to default Bearer token extraction.
+     */
+    tokenExtractor?: TokenExtractor;
+    /**
+     * Optional custom permission checker for dynamic permissions.
+     *
+     * When provided, replaces static rolePermissions checking.
+     * Called after getUser with the full user object.
+     *
+     * Example:
+     * ```typescript
+     * checkPermissions: async (user, routePermissions) => {
+     *   return routePermissions.every(perm =>
+     *     user.permissions?.includes(perm)
+     *   );
+     * }
+     * ```
+     */
+    checkPermissions?: PermissionChecker;
 }
 
 export interface JwtAuthPlugin extends FlinkAuthPlugin {
@@ -55,6 +103,8 @@ export function jwtAuthPlugin({
     algo = "HS256",
     passwordPolicy = defaultPasswordPolicy,
     tokenTTL = 1000 * 60 * 60 * 24 * 365 * 100, //Defaults to hundred year
+    tokenExtractor,
+    checkPermissions,
 }: JwtAuthPluginOptions): JwtAuthPlugin {
     return {
         authenticateRequest: async (req, permissions) =>
@@ -62,6 +112,8 @@ export function jwtAuthPlugin({
                 algo,
                 secret,
                 getUser,
+                tokenExtractor,
+                checkPermissions,
             }),
         createToken: (payload, roles) => createToken({ ...payload, roles }, { algo, secret, tokenTTL }),
         createPasswordHashAndSalt: (password: string) => createPasswordHashAndSalt(password, passwordPolicy),
@@ -73,9 +125,26 @@ async function authenticateRequest(
     req: FlinkRequest,
     routePermissions: string | string[],
     rolePermissions: { [x: string]: string[] },
-    { secret, algo, getUser }: Pick<JwtAuthPluginOptions, "algo" | "secret" | "getUser">
+    { secret, algo, getUser, tokenExtractor, checkPermissions }: Pick<
+        JwtAuthPluginOptions,
+        "algo" | "secret" | "getUser" | "tokenExtractor" | "checkPermissions"
+    >
 ) {
-    const token = getTokenFromReq(req);
+    let token: string | null | undefined;
+
+    if (tokenExtractor) {
+        token = tokenExtractor(req);
+
+        // If tokenExtractor returns undefined, fall back to default
+        if (token === undefined) {
+            token = getTokenFromReq(req);
+        }
+        // If it returns null, token stays null (no default fallback)
+        // If it returns string, token is the string
+    } else {
+        // No custom extractor, use default
+        token = getTokenFromReq(req);
+    }
 
     if (token) {
         let decodedToken;
@@ -90,7 +159,8 @@ async function authenticateRequest(
         if (decodedToken) {
             const permissionsArr = Array.isArray(routePermissions) ? routePermissions : [routePermissions];
 
-            if (permissionsArr && permissionsArr.length > 0) {
+            // Static permission check - only if custom checker NOT provided
+            if (!checkPermissions && permissionsArr && permissionsArr.length > 0) {
                 const validPerms = hasValidPermissions(decodedToken.roles || [], rolePermissions, permissionsArr);
 
                 if (!validPerms) {
@@ -105,6 +175,16 @@ async function authenticateRequest(
                 return false;
             }
 
+            // Custom permission check - only if provided
+            if (checkPermissions && permissionsArr && permissionsArr.length > 0) {
+                const hasPermission = await checkPermissions(user, permissionsArr);
+
+                if (!hasPermission) {
+                    log.debug("[JWT AUTH PLUGIN] Custom permission check failed");
+                    return false;
+                }
+            }
+
             req.user = user;
             return true;
         }