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

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
 
@@ -64,11 +66,14 @@ start();
 | Option | Type | Required | Default | Description |
 |--------|------|----------|---------|-------------|
 | `secret` | `string` | Yes | - | Secret key used to sign and verify JWT tokens. Keep this secure! |
-| `getUser` | `(tokenData: any) => Promise<FlinkAuthUser>` | Yes | - | Async function that retrieves user data from token payload |
+| `getUser` | `(tokenData: any, req: FlinkRequest) => Promise<FlinkAuthUser>` | Yes | - | Async function that retrieves user data from token payload. Has access to the full request object for context (headers, path, etc.) |
 | `rolePermissions` | `{ [role: string]: string[] }` | Yes | - | Maps roles to their allowed permissions |
 | `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 |
+| `useDynamicRoles` | `boolean` | No | `false` | When `true`, uses roles from the user object returned by `getUser` instead of roles from the token. Useful for multi-tenant scenarios where user roles vary by organization |
 
 ### Default Password Policy
 
@@ -89,6 +94,687 @@ 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
+
+## Multi-Tenant & Dynamic Roles
+
+The JWT auth plugin supports multi-tenant scenarios where users have different roles depending on the organization or context they're accessing. This is achieved through the `useDynamicRoles` option combined with the `req` parameter in `getUser`.
+
+### When to Use Dynamic Roles
+
+Use `useDynamicRoles: true` when:
+- Users belong to multiple organizations with different roles in each
+- User roles are determined by request context (headers, subdomain, path)
+- Roles need to be fetched from the database based on the current context
+- The same user token should grant different permissions in different contexts
+
+### How It Works
+
+1. **Default behavior** (`useDynamicRoles: false`):
+   - Roles from the JWT token are used for permission checking
+   - `getUser` can modify the user object, but token roles are what matter for permissions
+
+2. **Dynamic roles** (`useDynamicRoles: true`):
+   - Permission checking uses roles from the user object returned by `getUser`
+   - Token roles are ignored for permission checks
+   - `getUser` can fetch organization-specific roles from the database
+
+### Basic Multi-Tenant Example
+
+```typescript
+jwtAuthPlugin({
+  secret: process.env.JWT_SECRET!,
+  useDynamicRoles: true,
+
+  getUser: async (tokenData, req) => {
+    const user = await ctx.repos.userRepo.getById(tokenData.userId);
+
+    // Get organization from request header
+    const orgId = req.headers['x-organization-id'] as string;
+
+    // Fetch user's role in this specific organization
+    const membership = await ctx.repos.orgMemberRepo.findOne({
+      userId: user._id,
+      organizationId: orgId
+    });
+
+    return {
+      id: user._id,
+      username: user.username,
+      organizationId: orgId,
+      roles: [membership.role], // Org-specific role
+    };
+  },
+
+  rolePermissions: {
+    admin: ["read", "write", "delete", "manage_users"],
+    user: ["read", "write"],
+    guest: ["read"],
+  },
+})
+```
+
+**Usage:**
+```bash
+# User is admin in org1
+curl -H "Authorization: Bearer <token>" \
+     -H "X-Organization-ID: org1" \
+     https://api.example.com/users
+# ✓ Has admin permissions in org1
+
+# Same user is regular user in org2
+curl -H "Authorization: Bearer <token>" \
+     -H "X-Organization-ID: org2" \
+     https://api.example.com/users
+# ✓ Has user permissions in org2 (cannot manage users)
+```
+
+### Subdomain-Based Organizations
+
+```typescript
+jwtAuthPlugin({
+  secret: process.env.JWT_SECRET!,
+  useDynamicRoles: true,
+
+  getUser: async (tokenData, req) => {
+    // Extract org from subdomain (acme.yourapp.com -> "acme")
+    const host = req.headers.host || '';
+    const orgSubdomain = host.split('.')[0];
+
+    const membership = await ctx.repos.orgMemberRepo.findOne({
+      userId: tokenData.userId,
+      organizationSlug: orgSubdomain
+    });
+
+    if (!membership) {
+      return null; // User not member of this org
+    }
+
+    return {
+      id: tokenData.userId,
+      username: tokenData.username,
+      organizationSlug: orgSubdomain,
+      roles: [membership.role],
+    };
+  },
+
+  rolePermissions: {
+    owner: ["*"], // All permissions
+    admin: ["read", "write", "delete", "manage_users"],
+    member: ["read", "write"],
+  },
+})
+```
+
+### Path-Based Organization Context
+
+```typescript
+// Routes like: /orgs/:orgId/projects
+jwtAuthPlugin({
+  secret: process.env.JWT_SECRET!,
+  useDynamicRoles: true,
+
+  getUser: async (tokenData, req) => {
+    // Extract org from path: /orgs/org123/projects
+    const pathMatch = req.path?.match(/^\/orgs\/([^\/]+)/);
+    const orgId = pathMatch?.[1];
+
+    if (!orgId) {
+      // Not an org-specific route, use default role
+      return {
+        id: tokenData.userId,
+        username: tokenData.username,
+        roles: ["user"],
+      };
+    }
+
+    const membership = await ctx.repos.orgMemberRepo.findOne({
+      userId: tokenData.userId,
+      organizationId: orgId
+    });
+
+    return {
+      id: tokenData.userId,
+      username: tokenData.username,
+      organizationId: orgId,
+      roles: [membership.role],
+    };
+  },
+
+  rolePermissions: {
+    admin: ["read", "write", "delete"],
+    member: ["read", "write"],
+    viewer: ["read"],
+  },
+})
+```
+
+### Combining Multiple Role Sources
+
+```typescript
+jwtAuthPlugin({
+  secret: process.env.JWT_SECRET!,
+  useDynamicRoles: true,
+
+  getUser: async (tokenData, req) => {
+    const user = await ctx.repos.userRepo.getById(tokenData.userId);
+    const orgId = req.headers['x-organization-id'] as string;
+
+    // Get org-specific role
+    const orgMembership = await ctx.repos.orgMemberRepo.findOne({
+      userId: user._id,
+      organizationId: orgId
+    });
+
+    // Get global role from user
+    const globalRole = user.globalRole; // e.g., "super_admin"
+
+    // Combine roles (super admins have all permissions everywhere)
+    const roles = globalRole === 'super_admin'
+      ? ['super_admin']
+      : [orgMembership.role];
+
+    return {
+      id: user._id,
+      username: user.username,
+      organizationId: orgId,
+      globalRole,
+      roles,
+    };
+  },
+
+  rolePermissions: {
+    super_admin: ["*"], // Global super admins
+    org_admin: ["read", "write", "delete", "manage_members"],
+    org_member: ["read", "write"],
+    org_guest: ["read"],
+  },
+})
+```
+
+### Performance Considerations
+
+Since `getUser` is called on every authenticated request, consider caching:
+
+```typescript
+const roleCache = new Map();
+const CACHE_TTL = 5 * 60 * 1000; // 5 minutes
+
+jwtAuthPlugin({
+  secret: process.env.JWT_SECRET!,
+  useDynamicRoles: true,
+
+  getUser: async (tokenData, req) => {
+    const orgId = req.headers['x-organization-id'] as string;
+    const cacheKey = `${tokenData.userId}:${orgId}`;
+
+    // Check cache
+    const cached = roleCache.get(cacheKey);
+    if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
+      return cached.user;
+    }
+
+    // Fetch from DB
+    const membership = await ctx.repos.orgMemberRepo.findOne({
+      userId: tokenData.userId,
+      organizationId: orgId
+    });
+
+    const user = {
+      id: tokenData.userId,
+      username: tokenData.username,
+      organizationId: orgId,
+      roles: [membership.role],
+    };
+
+    // Cache it
+    roleCache.set(cacheKey, {
+      user,
+      timestamp: Date.now(),
+    });
+
+    return user;
+  },
+
+  rolePermissions: {
+    admin: ["read", "write", "delete"],
+    member: ["read", "write"],
+  },
+})
+```
+
+### Request Context Access
+
+The `getUser` callback receives the full request object, giving you access to:
+
+```typescript
+getUser: async (tokenData, req) => {
+  // Available request properties:
+  req.path          // "/api/users"
+  req.method        // "GET", "POST", etc.
+  req.headers       // { "x-organization-id": "org1", ... }
+  req.query         // { page: "1", limit: "10" }
+  req.body          // Request body (if applicable)
+  req.params        // URL parameters
+  req.cookies       // Cookies (if cookie-parser middleware is used)
+
+  // Use any combination to determine context
+  const orgId = req.headers['x-organization-id']
+    || req.query.org
+    || req.params.orgId;
+
+  // Fetch and return user with context-specific roles
+  // ...
+}
+```
+
+### Migration from Static Roles
+
+If you have an existing app with static roles, you can migrate gradually:
+
+**Before (static roles):**
+```typescript
+jwtAuthPlugin({
+  secret: process.env.JWT_SECRET!,
+  getUser: async (tokenData, req) => {
+    const user = await ctx.repos.userRepo.getById(tokenData.userId);
+    return {
+      id: user._id,
+      username: user.username,
+      // Token roles are used
+    };
+  },
+  rolePermissions: {
+    admin: ["read", "write", "delete"],
+    user: ["read", "write"],
+  },
+})
+```
+
+**After (dynamic multi-tenant roles):**
+```typescript
+jwtAuthPlugin({
+  secret: process.env.JWT_SECRET!,
+  useDynamicRoles: true, // ← Enable dynamic roles
+  getUser: async (tokenData, req) => { // ← Now has req parameter
+    const user = await ctx.repos.userRepo.getById(tokenData.userId);
+    const orgId = req.headers['x-organization-id'];
+
+    // Fetch org-specific role
+    const membership = await ctx.repos.orgMemberRepo.findOne({
+      userId: user._id,
+      organizationId: orgId
+    });
+
+    return {
+      id: user._id,
+      username: user.username,
+      organizationId: orgId,
+      roles: [membership.role], // ← Dynamic role
+    };
+  },
+  rolePermissions: {
+    admin: ["read", "write", "delete"],
+    user: ["read", "write"],
+  },
+})
+```
+
+### Important Notes
+
+- **Backward Compatible**: Setting `useDynamicRoles: false` (default) maintains existing behavior
+- **Token Still Required**: Dynamic roles don't bypass token validation - the token must be valid
+- **Organization Validation**: Always validate that the user has access to the requested organization
+- **Error Handling**: Return `null` from `getUser` if user doesn't have access to the organization
+- **Cache Invalidation**: Remember to invalidate role cache when user roles change in the database
+
 ## Context API
 
 Once configured, the plugin provides the following methods via the `auth` context:
@@ -542,6 +1228,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 +1247,8 @@ interface JwtAuthPluginOptions {
   rolePermissions: {
     [role: string]: string[];
   };
+  tokenExtractor?: TokenExtractor;
+  checkPermissions?: PermissionChecker;
 }
 
 // Plugin interface