@flink-app/jwt-auth-plugin 2.0.0-alpha.96 → 2.0.0-alpha.98

package/CHANGELOG.md

@@ -1,5 +1,62 @@
 # @flink-app/jwt-auth-plugin
 
+## 2.0.0-alpha.98
+
+### Minor Changes
+
+-   2f4a132: feat: expose verified token on the request
+
+    The JWT auth plugin now populates `req.token` (the decoded, signature-verified
+    payload) and `req.rawToken` (the original token string) after successful
+    authentication. Handlers can read token claims such as `jti` directly instead of
+    re-extracting and re-decoding the bearer token with an unverified decode.
+
+    ```ts
+    // Before
+    const authHeader = req.headers.authorization;
+    const bearer = authHeader?.startsWith("Bearer ") ? authHeader.slice(7) : undefined;
+    const decoded = bearer ? (jsonwebtoken.decode(bearer) as { jti?: string }) : null;
+    const sessionId = decoded?.jti ?? legacySessionId(req.user._id);
+
+    // After
+    const { jti } = (req.token as { jti?: string }) ?? {};
+    const sessionId = jti ?? legacySessionId(req.user._id);
+    ```
+
+    `token` / `rawToken` are added as optional fields on the core `FlinkRequest`
+    type, populated by auth plugins that have a token concept.
+
+### Patch Changes
+
+-   Updated dependencies [2f4a132]
+    -   @flink-app/flink@2.0.0-alpha.98
+
+## 2.0.0-alpha.97
+
+### Minor Changes
+
+-   eed6bc1: Pass host application context to auth plugins.
+
+    `FlinkAuthPlugin.authenticateRequest` now receives the host app's context as an optional third argument. Flink core supplies it on every authenticated request, so auth plugins can access repos/services without the caller wiring up a lazy accessor or maintaining a module-level mutable reference.
+
+    For `@flink-app/jwt-auth-plugin`, this means `getUser` receives the context directly:
+
+    ```typescript
+    jwtAuthPlugin({
+        getUser: async (tokenData, req, ctx) => {
+            const user = await ctx?.repos.userRepo.getById(tokenData._id);
+            return user ? { username: user.username, _id: user._id } : null;
+        },
+    });
+    ```
+
+    The `getContext` option previously added in alpha.96 is no longer needed and has been removed — remove it from your `jwtAuthPlugin({ … })` call. The third `ctx` parameter on `getUser` is optional, so callbacks that ignore it are unaffected.
+
+### Patch Changes
+
+-   Updated dependencies [eed6bc1]
+    -   @flink-app/flink@2.0.0-alpha.97
+
 ## 2.0.0-alpha.96
 
 ### Patch Changes

package/dist/FlinkJwtAuthPlugin.d.ts

@@ -33,7 +33,15 @@ export type TokenTTLResolver = (roles: string[], payload: any) => number | undef
 export interface JwtAuthPluginOptions {
     secret: string;
     algo?: jwtSimple.TAlgorithm;
-    getUser: (tokenData: any, req: FlinkRequest) => Promise<FlinkAuthUser | null | undefined>;
+    /**
+     * @param ctx The host application's context, supplied by Flink core on
+     * each authenticated request. Lets the callback access repos/services
+     * that don't exist when the plugin is constructed (e.g. before
+     * `FlinkApp.start()` resolves) without forcing the consumer to keep a
+     * module-level mutable reference. Undefined only when invoked outside
+     * the normal request pipeline (e.g. unit tests).
+     */
+    getUser: (tokenData: any, req: FlinkRequest, ctx?: any) => Promise<FlinkAuthUser | null | undefined>;
     passwordPolicy?: RegExp;
     tokenTTL?: number;
     rolePermissions: {

package/dist/FlinkJwtAuthPlugin.js

@@ -67,9 +67,9 @@ 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, tokenTTL = _a.tokenTTL, tokenExtractor = _a.tokenExtractor, checkPermissions = _a.checkPermissions, _d = _a.useDynamicRoles, useDynamicRoles = _d === void 0 ? false : _d, resolveTokenTTL = _a.resolveTokenTTL;
     return {
-        authenticateRequest: function (req, permissions) { return __awaiter(_this, void 0, void 0, function () {
+        authenticateRequest: function (req, permissions, ctx) { return __awaiter(_this, void 0, void 0, function () {
             return __generator(this, function (_a) {
-                return [2 /*return*/, authenticateRequest(req, permissions, rolePermissions, {
+                return [2 /*return*/, authenticateRequest(req, permissions, rolePermissions, ctx, {
                         algo: algo,
                         secret: secret,
                         getUser: getUser,
@@ -84,8 +84,8 @@ function jwtAuthPlugin(_a) {
         validatePassword: validatePassword,
     };
 }
-function authenticateRequest(req_1, routePermissions_1, rolePermissions_1, _a) {
-    return __awaiter(this, arguments, void 0, function (req, routePermissions, rolePermissions, _b) {
+function authenticateRequest(req_1, routePermissions_1, rolePermissions_1, ctx_1, _a) {
+    return __awaiter(this, arguments, void 0, function (req, routePermissions, rolePermissions, ctx, _b) {
         var token, decodedToken, permissionsArr, validPerms, user, validPerms, hasPermission;
         var secret = _b.secret, algo = _b.algo, getUser = _b.getUser, tokenExtractor = _b.tokenExtractor, checkPermissions = _b.checkPermissions, useDynamicRoles = _b.useDynamicRoles;
         return __generator(this, function (_c) {
@@ -122,7 +122,7 @@ function authenticateRequest(req_1, routePermissions_1, rolePermissions_1, _a) {
                             return [2 /*return*/, false];
                         }
                     }
-                    return [4 /*yield*/, getUser(decodedToken, req)];
+                    return [4 /*yield*/, getUser(decodedToken, req, ctx)];
                 case 1:
                     user = _c.sent();
                     if (!user) {
@@ -148,6 +148,10 @@ function authenticateRequest(req_1, routePermissions_1, rolePermissions_1, _a) {
                     _c.label = 3;
                 case 3:
                     req.user = user;
+                    // Expose the verified token so handlers can read claims (e.g. jti)
+                    // without re-extracting and re-decoding (and without an unverified decode).
+                    req.token = decodedToken;
+                    req.rawToken = token;
                     // Populate userPermissions from resolved permissions
                     req.userPermissions = computeUserPermissions(user, decodedToken, {
                         useDynamicRoles: useDynamicRoles,

package/package.json

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

package/readme.md

@@ -481,6 +481,35 @@ 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.

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({

package/src/FlinkJwtAuthPlugin.ts

@@ -48,7 +48,15 @@ export type TokenTTLResolver = (roles: string[], payload: any) => number | undef
 export interface JwtAuthPluginOptions {
     secret: string;
     algo?: jwtSimple.TAlgorithm;
-    getUser: (tokenData: any, req: FlinkRequest) => Promise<FlinkAuthUser | null | undefined>;
+    /**
+     * @param ctx The host application's context, supplied by Flink core on
+     * each authenticated request. Lets the callback access repos/services
+     * that don't exist when the plugin is constructed (e.g. before
+     * `FlinkApp.start()` resolves) without forcing the consumer to keep a
+     * module-level mutable reference. Undefined only when invoked outside
+     * the normal request pipeline (e.g. unit tests).
+     */
+    getUser: (tokenData: any, req: FlinkRequest, ctx?: any) => Promise<FlinkAuthUser | null | undefined>;
     passwordPolicy?: RegExp;
     tokenTTL?: number;
     rolePermissions: {
@@ -150,8 +158,8 @@ export function jwtAuthPlugin({
     resolveTokenTTL,
 }: JwtAuthPluginOptions): JwtAuthPlugin {
     return {
-        authenticateRequest: async (req, permissions) =>
-            authenticateRequest(req, permissions, rolePermissions, {
+        authenticateRequest: async (req, permissions, ctx) =>
+            authenticateRequest(req, permissions, rolePermissions, ctx, {
                 algo,
                 secret,
                 getUser,
@@ -169,6 +177,7 @@ async function authenticateRequest(
     req: FlinkRequest,
     routePermissions: string | string[],
     rolePermissions: { [x: string]: string[] },
+    ctx: any,
     { secret, algo, getUser, tokenExtractor, checkPermissions, useDynamicRoles }: Pick<
         JwtAuthPluginOptions,
         "algo" | "secret" | "getUser" | "tokenExtractor" | "checkPermissions" | "useDynamicRoles"
@@ -212,7 +221,7 @@ async function authenticateRequest(
                 }
             }
 
-            const user = await getUser(decodedToken, req);
+            const user = await getUser(decodedToken, req, ctx);
 
             if (!user) {
                 log.debug("[JWT AUTH PLUGIN] User not returned from getUser callback");
@@ -241,6 +250,11 @@ async function authenticateRequest(
 
             req.user = user;
 
+            // Expose the verified token so handlers can read claims (e.g. jti)
+            // without re-extracting and re-decoding (and without an unverified decode).
+            req.token = decodedToken;
+            req.rawToken = token;
+
             // Populate userPermissions from resolved permissions
             req.userPermissions = computeUserPermissions(user, decodedToken, {
                 useDynamicRoles,