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

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @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

package/dist/FlinkJwtAuthPlugin.js

@@ -148,6 +148,10 @@ function authenticateRequest(req_1, routePermissions_1, rolePermissions_1, ctx_1
                     _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.97",
+  "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.97"
+    "@flink-app/flink": "2.0.0-alpha.98"
   },
   "peerDependencies": {
-    "@flink-app/flink": ">=2.0.0-alpha.97"
+    "@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

@@ -250,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,