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

package/readme.md

@@ -94,6 +94,44 @@ jwtAuthPlugin({
 })
 ```
 
+## Permission Matching Semantics
+
+The static `rolePermissions` map supports three forms of matching:
+
+1. **Exact match** — `"car.read"` in a role's scope list matches a route declaring `permissions: ["car.read"]`.
+2. **Role superuser** — a role whose scope list contains `"*"` is granted every permission unconditionally.
+3. **Route allows any authenticated user** — a route declaring `permissions: ["*"]` accepts any role as long as the user is authenticated.
+4. **Suffix wildcard scopes** — a scope entry ending in `.*` (e.g. `"license.subscription.*"`) matches any required route permission whose literal string starts with the prefix including the trailing dot.
+
+### Suffix wildcard scopes
+
+```typescript
+rolePermissions: {
+  restricted: [
+    "license.subscription.*", // matches license.subscription.get, license.subscription.cancel, ...
+    "license.unsubscribe",    // exact match
+  ],
+  admin: ["*"],               // every permission (superuser)
+}
+```
+
+Matching rules:
+
+| Scope entry                  | Route permission                       | Result      |
+| ---------------------------- | -------------------------------------- | ----------- |
+| `"license.subscription.*"`   | `"license.subscription.get"`           | match       |
+| `"license.subscription.*"`   | `"license.subscription.cancel"`        | match       |
+| `"license.subscription.*"`   | `"license.subscription"` (no suffix)   | **no match** — wildcard requires a segment after the prefix |
+| `"license.subscription.*"`   | `"license.subscriptions.get"`          | **no match** — segment-boundary safety, prevents accidental escalation through similarly-named scopes |
+| `"a.b.c.*"`                  | `"a.b.c.x.y"`                          | match       |
+
+Notes:
+
+- The wildcard is **segment-scoped**, not substring-scoped. `foo.*` matches `foo.bar` and `foo.bar.baz` but never `foobar.x`.
+- Only a **trailing** `.*` is special. Infix forms like `*.get` or `foo.*.bar` are not supported.
+- Wildcard scopes can be mixed freely with exact-match entries in the same role.
+- All required route permissions must be matched (the check is `every`), so a single wildcard can cover multiple required scopes only if they all fall under its prefix.
+
 ## Custom Token Extraction
 
 By default, the plugin extracts JWT tokens from the `Authorization` header as Bearer tokens:
@@ -443,6 +481,282 @@ jwtAuthPlugin({
 
 **Solution**: Clear permission cache or reduce cache TTL
 
+## `req.token` & `req.rawToken` - Accessing Token Claims
+
+After successful authentication the plugin attaches the verified token to the request:
+
+- **`req.token`** - the decoded, **signature-verified** token payload (claims). Same object passed to `getUser`.
+- **`req.rawToken`** - the original token string that authenticated the request (Bearer header or custom `tokenExtractor` output).
+
+This lets handlers read token claims (e.g. `jti`, custom session ids) without re-extracting and re-decoding the bearer token themselves - and without an unverified decode.
+
+```typescript
+const handler: Handler<Ctx, any, any> = async ({ req }) => {
+  // Read claims straight off the verified token
+  const { jti } = (req.token as { jti?: string }) ?? {};
+  const sessionId = jti ?? legacySessionId(req.user._id);
+
+  // Forward the raw token to a downstream service if needed
+  await downstream.call({ headers: { authorization: `Bearer ${req.rawToken}` } });
+
+  return { data: { sessionId } };
+};
+```
+
+**Notes:**
+
+- Both fields are only set once authentication **succeeds** (a rejected request never reaches the handler).
+- `req.token` is the exact decoded payload, including framework-added claims like `iat` and `exp`.
+- Signature is verified during decode; unlike a bare `jsonwebtoken.decode(...)`, you don't need to (and shouldn't) re-verify.
+- `req.rawToken` reflects whatever `tokenExtractor` returned, so it works for cookie/query-based tokens too.
+
+## `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/spec/FlinkJwtAuthPlugin.spec.ts

@@ -102,6 +102,62 @@ describe("FlinkJwtAuthPlugin", () => {
     expect(authenticated).toBeTruthy();
   });
 
+  it("should expose decoded token on req.token and raw string on req.rawToken", async () => {
+    const secret = "secret";
+    const userId = "123";
+    const encodedToken = jwtSimple.encode(
+      { id: userId, jti: "session-abc", roles: ["user"] },
+      secret
+    );
+
+    const plugin = jwtAuthPlugin({
+      secret,
+      getUser: async ({ id }: { id: string }, req) => ({ id, username: "username" }),
+      rolePermissions: {
+        user: ["*"],
+      },
+    });
+
+    const mockRequest = {
+      headers: {
+        authorization: "Bearer " + encodedToken,
+      },
+    } as FlinkRequest;
+
+    const authenticated = await plugin.authenticateRequest(mockRequest, "foo");
+
+    expect(authenticated).toBeTruthy();
+    expect(mockRequest.rawToken).toBe(encodedToken);
+    expect(mockRequest.token?.jti).toBe("session-abc");
+    expect(mockRequest.token?.id).toBe(userId);
+  });
+
+  it("should set req.rawToken to the tokenExtractor output, not just Bearer", async () => {
+    const secret = "secret";
+    const customToken = jwtSimple.encode(
+      { id: "1", jti: "from-query", roles: ["user"] },
+      secret
+    );
+
+    const plugin = jwtAuthPlugin({
+      secret,
+      getUser: async ({ id }: { id: string }, req) => ({ id, username: "username" }),
+      rolePermissions: { user: ["*"] },
+      tokenExtractor: (req) => 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();
+    expect(mockRequest.rawToken).toBe(customToken);
+    expect(mockRequest.token?.jti).toBe("from-query");
+  });
+
   it("should generate token", async () => {
     const secret = "secret";
     const plugin = jwtAuthPlugin({
@@ -813,4 +869,110 @@ describe("FlinkJwtAuthPlugin", () => {
       expect(capturedHeaders["x-custom-header"]).toBe("custom-value");
     });
   });
+
+  describe("resolveTokenTTL", () => {
+    it("should use resolved TTL when callback returns a number", async () => {
+      const secret = "secret";
+      const ttl = 1000 * 60 * 60 * 8; // 8 hours
+
+      const plugin = jwtAuthPlugin({
+        secret,
+        getUser: async () => ({ id: "1", username: "u" }),
+        rolePermissions: {},
+        resolveTokenTTL: () => ttl,
+      });
+
+      const token = await plugin.createToken({ id: "1" }, ["admin"]);
+      const decoded = jwtSimple.decode(token, secret);
+      const expectedExp = Math.floor((Date.now() + ttl) / 1000);
+
+      expect(decoded.exp).toBeCloseTo(expectedExp, -1);
+    });
+
+    it("should fall back to static tokenTTL when callback returns undefined", async () => {
+      const secret = "secret";
+      const staticTTL = 1000 * 60 * 60 * 2; // 2 hours
+
+      const plugin = jwtAuthPlugin({
+        secret,
+        getUser: async () => ({ id: "1", username: "u" }),
+        rolePermissions: {},
+        tokenTTL: staticTTL,
+        resolveTokenTTL: () => undefined,
+      });
+
+      const token = await plugin.createToken({ id: "1" }, ["user"]);
+      const decoded = jwtSimple.decode(token, secret);
+      const expectedExp = Math.floor((Date.now() + staticTTL) / 1000);
+
+      expect(decoded.exp).toBeCloseTo(expectedExp, -1);
+    });
+
+    it("should fall back to default TTL when neither option is provided", async () => {
+      const secret = "secret";
+      const hundredYears = 1000 * 60 * 60 * 24 * 365 * 100;
+
+      const plugin = jwtAuthPlugin({
+        secret,
+        getUser: async () => ({ id: "1", username: "u" }),
+        rolePermissions: {},
+      });
+
+      const token = await plugin.createToken({ id: "1" }, ["user"]);
+      const decoded = jwtSimple.decode(token, secret);
+      const expectedExp = Math.floor((Date.now() + hundredYears) / 1000);
+
+      expect(decoded.exp).toBeCloseTo(expectedExp, -1);
+    });
+
+    it("should receive roles and payload in callback", async () => {
+      const secret = "secret";
+      let capturedRoles: string[] | undefined;
+      let capturedPayload: any;
+
+      const plugin = jwtAuthPlugin({
+        secret,
+        getUser: async () => ({ id: "1", username: "u" }),
+        rolePermissions: {},
+        resolveTokenTTL: (roles, payload) => {
+          capturedRoles = roles;
+          capturedPayload = payload;
+          return 60000;
+        },
+      });
+
+      await plugin.createToken({ id: "user-1", email: "a@b.com" }, ["admin", "editor"]);
+
+      expect(capturedRoles).toEqual(["admin", "editor"]);
+      expect(capturedPayload?.id).toBe("user-1");
+      expect(capturedPayload?.email).toBe("a@b.com");
+    });
+
+    it("should produce different TTLs for different roles", async () => {
+      const secret = "secret";
+
+      const plugin = jwtAuthPlugin({
+        secret,
+        getUser: async () => ({ id: "1", username: "u" }),
+        rolePermissions: {},
+        resolveTokenTTL: (roles) => {
+          if (roles.includes("admin")) return 1000 * 60 * 60; // 1 hour
+          return 1000 * 60 * 60 * 24 * 30; // 30 days
+        },
+      });
+
+      const adminToken = await plugin.createToken({ id: "1" }, ["admin"]);
+      const userToken = await plugin.createToken({ id: "2" }, ["user"]);
+
+      const adminDecoded = jwtSimple.decode(adminToken, secret);
+      const userDecoded = jwtSimple.decode(userToken, secret);
+
+      // User token should expire much later than admin token
+      expect(userDecoded.exp).toBeGreaterThan(adminDecoded.exp);
+
+      // Difference should be roughly 30 days minus 1 hour ≈ 29.96 days in seconds
+      const diffSeconds = userDecoded.exp - adminDecoded.exp;
+      expect(diffSeconds).toBeGreaterThan(29 * 24 * 60 * 60);
+    });
+  });
 });

package/spec/PermissionValidator.spec.ts

@@ -69,4 +69,96 @@ describe("PermissionValidator", () => {
     const valid = hasValidPermissions([], {}, ["*"]);
     expect(valid).toBe(false);
   });
+
+  describe("suffix wildcard scopes", () => {
+    it("should match a single-segment suffix under the wildcard", () => {
+      const valid = hasValidPermissions(
+        ["user"],
+        { user: ["a.*"] },
+        ["a.b"]
+      );
+      expect(valid).toBe(true);
+    });
+
+    it("should match a multi-segment suffix under the wildcard", () => {
+      const valid = hasValidPermissions(
+        ["user"],
+        { user: ["a.*"] },
+        ["a.b.c"]
+      );
+      expect(valid).toBe(true);
+    });
+
+    it("should NOT match the wildcard prefix without a trailing segment", () => {
+      const valid = hasValidPermissions(
+        ["user"],
+        { user: ["a.*"] },
+        ["a"]
+      );
+      expect(valid).toBe(false);
+    });
+
+    it("should NOT match across a segment boundary (privilege escalation guard)", () => {
+      const valid = hasValidPermissions(
+        ["user"],
+        { user: ["a.*"] },
+        ["ab.c"]
+      );
+      expect(valid).toBe(false);
+    });
+
+    it("should allow mixing wildcard and exact scopes when the required perm hits the exact one", () => {
+      const valid = hasValidPermissions(
+        ["user"],
+        { user: ["a.*", "b.get"] },
+        ["b.get"]
+      );
+      expect(valid).toBe(true);
+    });
+
+    it("should deny when the required perm matches neither the wildcard nor the exact entry", () => {
+      const valid = hasValidPermissions(
+        ["user"],
+        { user: ["a.*", "b.get"] },
+        ["b.put"]
+      );
+      expect(valid).toBe(false);
+    });
+
+    it("should still honor route '*' when the role only has a suffix wildcard", () => {
+      const valid = hasValidPermissions(
+        ["user"],
+        { user: ["a.*"] },
+        ["*"]
+      );
+      expect(valid).toBe(true);
+    });
+
+    it("should match deeply nested prefixes", () => {
+      const valid = hasValidPermissions(
+        ["user"],
+        { user: ["a.b.c.*"] },
+        ["a.b.c.x.y"]
+      );
+      expect(valid).toBe(true);
+    });
+
+    it("should allow a single wildcard to cover multiple required perms", () => {
+      const valid = hasValidPermissions(
+        ["user"],
+        { user: ["a.*"] },
+        ["a.b", "a.c"]
+      );
+      expect(valid).toBe(true);
+    });
+
+    it("should deny when one required perm is outside the wildcard namespace", () => {
+      const valid = hasValidPermissions(
+        ["user"],
+        { user: ["a.*"] },
+        ["a.b", "c.d"]
+      );
+      expect(valid).toBe(false);
+    });
+  });
 });