@flink-app/jwt-auth-plugin 1.0.0 → 2.0.0-alpha.48

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @flink-app/jwt-auth-plugin
 
+## 2.0.0-alpha.48
+
+### Minor Changes
+
+-   AI features
+
 ## 1.0.0
 
 ### Minor Changes

package/dist/FlinkJwtAuthPlugin.js

@@ -149,6 +149,12 @@ function authenticateRequest(req_1, routePermissions_1, rolePermissions_1, _a) {
                     _c.label = 3;
                 case 3:
                     req.user = user;
+                    // Populate userPermissions from resolved permissions
+                    req.userPermissions = computeUserPermissions(user, decodedToken, {
+                        useDynamicRoles: useDynamicRoles,
+                        rolePermissions: rolePermissions,
+                        checkPermissions: checkPermissions,
+                    });
                     return [2 /*return*/, true];
                 case 4: return [2 /*return*/, false];
             }
@@ -211,3 +217,40 @@ function validatePassword(password, passwordHash, salt) {
         });
     });
 }
+/**
+ * Compute user permissions based on auth plugin configuration
+ *
+ * Strategies (in order):
+ * 1. User object has permissions directly (from getUser callback)
+ * 2. Dynamic roles - map user.roles to permissions
+ * 3. Static roles from token - map token.roles to permissions
+ * 4. No permissions available - return empty array
+ */
+function computeUserPermissions(user, decodedToken, config) {
+    // Strategy 1: User object has permissions directly (from getUser callback)
+    if (user.permissions && Array.isArray(user.permissions)) {
+        return user.permissions;
+    }
+    // Strategy 2: Dynamic roles - map user.roles to permissions
+    if (config.useDynamicRoles && user.roles && Array.isArray(user.roles)) {
+        return flattenRolesToPermissions(user.roles, config.rolePermissions);
+    }
+    // Strategy 3: Static roles from token - map token.roles to permissions
+    if (decodedToken.roles && Array.isArray(decodedToken.roles)) {
+        return flattenRolesToPermissions(decodedToken.roles, config.rolePermissions);
+    }
+    // Strategy 4: No permissions available
+    return [];
+}
+/**
+ * Convert roles to permissions using rolePermissions mapping
+ */
+function flattenRolesToPermissions(roles, roleMap) {
+    var perms = new Set();
+    for (var _i = 0, roles_1 = roles; _i < roles_1.length; _i++) {
+        var role = roles_1[_i];
+        var rolePerms = roleMap[role] || [];
+        rolePerms.forEach(function (p) { return perms.add(p); });
+    }
+    return Array.from(perms);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flink-app/jwt-auth-plugin",
-  "version": "1.0.0",
+  "version": "2.0.0-alpha.48",
   "description": "Flink plugin for JWT auth",
   "author": "joel@frost.se",
   "license": "MIT",
@@ -19,7 +19,7 @@
     "@types/node": "22.13.10",
     "ts-node": "^10.9.2",
     "tsc-watch": "^4.2.9",
-    "@flink-app/flink": "1.0.0"
+    "@flink-app/flink": "2.0.0-alpha.48"
   },
   "gitHead": "4243e3b3cd6d4e1ca001a61baa8436bf2bbe4113",
   "scripts": {

package/readme.md

@@ -443,6 +443,253 @@ jwtAuthPlugin({
 
 **Solution**: Clear permission cache or reduce cache TTL
 
+## `req.userPermissions` - AI Permissions Integration
+
+Starting in **v1.1.0**, the JWT auth plugin automatically populates `req.userPermissions` with the resolved permissions array. This field is specifically designed for use with Flink's AI agents and tools system, providing a standardized way to handle permissions across handlers, agents, and tools.
+
+### Why `req.userPermissions`?
+
+**Before v1.1.0**: Tools and agents had to manually convert roles to permissions or query the database in permission functions, leading to:
+- Duplicated role-to-permission mapping logic
+- Performance issues (N tools × M agent steps = many DB queries)
+- No support for multi-tenant permission contexts
+- Inconsistent permission resolution across the app
+
+**After v1.1.0**: The auth plugin populates `req.userPermissions` once during authentication, and this resolved array is passed through to agents and tools:
+- ✅ Single source of truth for permissions
+- ✅ Performance optimization (computed once per request)
+- ✅ Reuses all auth plugin features (roles, dynamic roles, custom checkers)
+- ✅ Consistent permission checking across handlers, agents, and tools
+
+### How It Works
+
+The JWT auth plugin automatically populates `req.userPermissions` based on the configuration strategy:
+
+**Strategy 1: Direct permissions from user object**
+
+```typescript
+jwtAuthPlugin({
+  secret: process.env.JWT_SECRET,
+  getUser: async (tokenData) => {
+    const user = await userRepo.getById(tokenData.userId);
+    return {
+      id: user.id,
+      permissions: user.permissions, // Direct permissions array
+    };
+  },
+  rolePermissions: {},
+});
+
+// Result: req.userPermissions = user.permissions
+```
+
+**Strategy 2: Static role mapping**
+
+```typescript
+jwtAuthPlugin({
+  secret: process.env.JWT_SECRET,
+  getUser: async (tokenData) => {
+    return { id: tokenData.userId };
+  },
+  rolePermissions: {
+    admin: ["car:read", "car:create", "car:delete"],
+    user: ["car:read"],
+    premium: ["car:read", "car:create", "premium-features"],
+  },
+});
+
+// JWT token has roles: ["user", "premium"]
+// Result: req.userPermissions = ["car:read", "car:create", "premium-features"]
+```
+
+**Strategy 3: Dynamic roles (multi-tenant)**
+
+```typescript
+jwtAuthPlugin({
+  secret: process.env.JWT_SECRET,
+  useDynamicRoles: true,
+  getUser: async (tokenData, req) => {
+    const orgId = req.headers['x-organization-id'];
+    const membership = await orgMembershipRepo.getByUserAndOrg(
+      tokenData.userId,
+      orgId
+    );
+    return {
+      id: tokenData.userId,
+      roles: [membership.role], // Org-specific role
+    };
+  },
+  rolePermissions: {
+    admin: ["car:read", "car:create", "car:delete"],
+    user: ["car:read"],
+  },
+});
+
+// Same user, different orgs → different permissions
+// Org A: admin role → req.userPermissions = ["car:read", "car:create", "car:delete"]
+// Org B: user role → req.userPermissions = ["car:read"]
+```
+
+### Using with AI Agents and Tools
+
+Pass `req.userPermissions` to agents in your handlers:
+
+```typescript
+// Handler
+const handler: Handler<AppCtx, RequestBody, ResponseBody> = async ({ req, ctx }) => {
+  const agent = ctx.agents.carAgent
+    .withUser(req.user)
+    .withPermissions(req.userPermissions); // Pass resolved permissions
+
+  return await agent.execute({ message: req.body.message });
+};
+
+// Agent
+export default class CarAgent extends FlinkAgent<AppCtx> {
+  description = "Expert in car models";
+  instructions = "You are a car expert...";
+  tools = ["get-cars-tool", "create-car-tool"];
+  permissions = "car:access"; // Agent-level permission
+}
+
+// Tool
+export const Tool: FlinkToolProps = {
+  id: "create-car",
+  description: "Create a new car",
+  permissions: "car:create", // Tool-level permission
+  inputSchema: z.object({
+    brand: z.string(),
+    model: z.string(),
+  }),
+};
+```
+
+**What happens:**
+1. Auth plugin resolves permissions → `req.userPermissions = ["car:access", "car:read", "car:create"]`
+2. Agent checks if user has `"car:access"` → ✅ allowed
+3. LLM only sees tools user has permission for (`"create-car"` is shown, others hidden)
+4. Tool execution checks `"car:create"` permission → ✅ allowed
+
+### Permission Resolution Priority
+
+The plugin computes `req.userPermissions` in this order:
+
+1. **Direct permissions**: If `user.permissions` exists (from `getUser`), use it directly
+2. **Dynamic roles**: If `useDynamicRoles: true`, map `user.roles` to permissions via `rolePermissions`
+3. **Static roles**: Map token roles to permissions via `rolePermissions`
+4. **Empty array**: If no permissions found, return `[]`
+
+### Backward Compatibility
+
+`req.userPermissions` is **optional** - existing apps continue to work:
+
+- If not using AI agents/tools → field is populated but not used
+- Tools/agents fall back to `user.permissions` if `req.userPermissions` is not passed
+- No breaking changes to existing code
+
+### Performance Benefits
+
+**Before** (function-based permissions without `userPermissions`):
+```typescript
+// Permission checked N times (once per tool use)
+permissions: async (input, user) => {
+  const perms = await fetchUserPermissions(user.id); // DB query per tool!
+  return perms.includes("car:create");
+}
+```
+
+**After** (using `userPermissions`):
+```typescript
+// Permissions computed ONCE during authentication
+req.userPermissions = ["car:read", "car:create"]; // Happens once
+
+// Tools check the array (fast O(1) lookup)
+permissions: "car:create"
+```
+
+**Result**: Single DB query/computation per request, regardless of how many tools or agent steps are used.
+
+### Example: Complete Integration
+
+```typescript
+// 1. Configure JWT auth plugin
+jwtAuthPlugin({
+  secret: process.env.JWT_SECRET,
+  rolePermissions: {
+    admin: ["car:read", "car:create", "car:delete", "premium-features"],
+    user: ["car:read"],
+    premium: ["car:read", "car:create", "premium-features"],
+  },
+  getUser: async (tokenData) => {
+    const user = await userRepo.getById(tokenData.userId);
+    return {
+      id: user.id,
+      email: user.email,
+      // Roles from DB or token will be mapped to permissions automatically
+    };
+  },
+});
+
+// 2. Handler passes userPermissions to agent
+const handler: Handler<AppCtx, { question: string }, { answer: string }> = async ({
+  req,
+  ctx,
+}) => {
+  const agent = ctx.agents.carAgent
+    .withUser(req.user)
+    .withPermissions(req.userPermissions); // Resolved permissions passed here
+
+  const response = await agent.execute({ message: req.body.question });
+  return { data: { answer: response.message } };
+};
+
+// 3. Agent defines permissions
+export default class CarAgent extends FlinkAgent<AppCtx> {
+  description = "Car inventory expert";
+  instructions = "Help users with car-related queries";
+  tools = ["get-cars", "create-car", "premium-report"];
+  permissions = "car:read"; // User must have car:read
+}
+
+// 4. Tools define individual permissions
+export const GetCarsTool: FlinkToolProps = {
+  id: "get-cars",
+  description: "Search car inventory",
+  permissions: "car:read", // Basic read access
+  inputSchema: z.object({ brand: z.string().optional() }),
+};
+
+export const CreateCarTool: FlinkToolProps = {
+  id: "create-car",
+  description: "Add new car to inventory",
+  permissions: "car:create", // Requires create permission
+  inputSchema: z.object({ brand: z.string(), model: z.string() }),
+};
+
+export const PremiumReportTool: FlinkToolProps = {
+  id: "premium-report",
+  description: "Generate advanced analytics",
+  permissions: ["car:read", "premium-features"], // Requires BOTH
+  inputSchema: z.object({ carId: z.string() }),
+};
+```
+
+**Flow**:
+1. User with JWT token containing `roles: ["user", "premium"]` makes a request
+2. Auth plugin resolves: `req.userPermissions = ["car:read", "car:create", "premium-features"]`
+3. Handler passes `req.userPermissions` to agent
+4. Agent checks `"car:read"` → ✅ user has it
+5. Agent filters tools:
+   - `get-cars` (requires `"car:read"`) → ✅ shown to LLM
+   - `create-car` (requires `"car:create"`) → ✅ shown to LLM
+   - `premium-report` (requires `["car:read", "premium-features"]`) → ✅ shown to LLM (has both)
+6. LLM can use all three tools
+
+If user only had `roles: ["user"]`:
+- `req.userPermissions = ["car:read"]`
+- Only `get-cars` tool would be shown to LLM
+- LLM cannot hallucinate using `create-car` or `premium-report` (they're hidden)
+
 ## 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`.

package/src/FlinkJwtAuthPlugin.ts

@@ -219,6 +219,14 @@ async function authenticateRequest(
             }
 
             req.user = user;
+
+            // Populate userPermissions from resolved permissions
+            req.userPermissions = computeUserPermissions(user, decodedToken, {
+                useDynamicRoles,
+                rolePermissions,
+                checkPermissions,
+            });
+
             return true;
         }
     }
@@ -261,3 +269,52 @@ async function validatePassword(password: string, passwordHash: string, salt: st
     const hashCandidate = await encrypt(password, salt);
     return hashCandidate === passwordHash;
 }
+
+/**
+ * Compute user permissions based on auth plugin configuration
+ *
+ * Strategies (in order):
+ * 1. User object has permissions directly (from getUser callback)
+ * 2. Dynamic roles - map user.roles to permissions
+ * 3. Static roles from token - map token.roles to permissions
+ * 4. No permissions available - return empty array
+ */
+function computeUserPermissions(
+    user: any,
+    decodedToken: any,
+    config: {
+        useDynamicRoles?: boolean;
+        rolePermissions: { [x: string]: string[] };
+        checkPermissions?: PermissionChecker;
+    }
+): string[] {
+    // Strategy 1: User object has permissions directly (from getUser callback)
+    if (user.permissions && Array.isArray(user.permissions)) {
+        return user.permissions;
+    }
+
+    // Strategy 2: Dynamic roles - map user.roles to permissions
+    if (config.useDynamicRoles && user.roles && Array.isArray(user.roles)) {
+        return flattenRolesToPermissions(user.roles, config.rolePermissions);
+    }
+
+    // Strategy 3: Static roles from token - map token.roles to permissions
+    if (decodedToken.roles && Array.isArray(decodedToken.roles)) {
+        return flattenRolesToPermissions(decodedToken.roles, config.rolePermissions);
+    }
+
+    // Strategy 4: No permissions available
+    return [];
+}
+
+/**
+ * Convert roles to permissions using rolePermissions mapping
+ */
+function flattenRolesToPermissions(roles: string[], roleMap: Record<string, string[]>): string[] {
+    const perms = new Set<string>();
+    for (const role of roles) {
+        const rolePerms = roleMap[role] || [];
+        rolePerms.forEach((p) => perms.add(p));
+    }
+    return Array.from(perms);
+}