@flink-app/jwt-auth-plugin 2.0.0-alpha.112 → 2.0.0-alpha.114

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @flink-app/jwt-auth-plugin
 
+## 2.0.0-alpha.114
+
+### Minor Changes
+
+-   5f11719: Response headers from a successful authentication. `FlinkAuthPlugin.authenticateRequest` may now return `{ authenticated: true, headers }` (in addition to `true | false | FlinkResponse`) to proceed to the handler _and_ contribute headers to the response — the seat auth plugins previously lacked for cross-cutting concerns discovered during authentication, such as re-issuing a sliding session cookie. The headers are applied to whatever response Flink ends up sending, including handler and framework errors, and a handler's own `FlinkResponse.headers` win on conflict. Core also exports `isAuthSuccess()` and `getAuthSuccessHeaders()` for code that consumes an auth result itself.
+
+    The jwt-auth-plugin exposes this as `onAuthSuccess(user, req, ctx)`, the counterpart to `onAuthFailure`: called only on successful authentication, just before the handler runs — return `{ headers }` to add them to the response, or void to leave it untouched.
+
+    Fully backward compatible: plugins returning `true` behave exactly as before.
+
+### Patch Changes
+
+-   Updated dependencies [5f11719]
+    -   @flink-app/flink@2.0.0-alpha.114
+
+## 2.0.0-alpha.113
+
+### Patch Changes
+
+-   Updated dependencies [4a8b81a]
+    -   @flink-app/flink@2.0.0-alpha.113
+
 ## 2.0.0-alpha.112
 
 ### Patch Changes

package/dist/FlinkJwtAuthPlugin.d.ts

@@ -45,6 +45,27 @@ export interface AuthFailure {
  * instead of the default `401 Unauthorized`. Return void/undefined to keep the default.
  */
 export type AuthFailureHandler = (failure: AuthFailure, req: FlinkRequest, ctx?: any) => FlinkResponse | void | Promise<FlinkResponse | void>;
+/**
+ * What an auth-success callback may contribute to the response.
+ */
+export interface AuthSuccessResult {
+    /**
+     * Headers to merge into whatever response Flink ends up sending for this
+     * request, e.g. a `Set-Cookie` for a renewed session. Headers set by the
+     * handler itself win on conflict.
+     */
+    headers?: Record<string, string>;
+}
+/**
+ * Custom auth-success callback, the counterpart to `onAuthFailure`.
+ *
+ * Called only when authentication succeeded, right before the handler runs, with
+ * the user resolved by `getUser`. Return `{ headers }` to have Flink apply those
+ * headers to the response - the seat for cross-cutting concerns discovered during
+ * authentication, such as re-issuing a sliding session cookie. Return void to
+ * leave the response untouched.
+ */
+export type AuthSuccessHandler = (user: FlinkAuthUser, req: FlinkRequest, ctx?: any) => AuthSuccessResult | void | Promise<AuthSuccessResult | void>;
 /**
  * Custom token TTL resolver callback.
  *
@@ -134,6 +155,25 @@ export interface JwtAuthPluginOptions {
      * ```
      */
     onAuthFailure?: AuthFailureHandler;
+    /**
+     * Optional callback invoked on successful authentication.
+     *
+     * Called with the authenticated user just before the handler runs, and never
+     * for rejected requests. Return `{ headers }` to contribute headers to the
+     * response, e.g. a re-signed session cookie when the presented token is
+     * running low on lifetime. Headers set by the handler win on conflict.
+     *
+     * Example:
+     * ```typescript
+     * onAuthSuccess: (user, req) => {
+     *   const renewed = renewCookieIfExpiring(req);
+     *   if (renewed) {
+     *     return { headers: { "set-cookie": renewed } };
+     *   }
+     * }
+     * ```
+     */
+    onAuthSuccess?: AuthSuccessHandler;
     /**
      * Optional dynamic token TTL resolver.
      *
@@ -173,4 +213,4 @@ export interface JwtAuthPlugin extends FlinkAuthPlugin {
 /**
  * Configures and creates authentication plugin.
  */
-export declare function jwtAuthPlugin({ secret, getUser, rolePermissions, algo, passwordPolicy, tokenTTL, tokenExtractor, checkPermissions, useDynamicRoles, resolveTokenTTL, onAuthFailure, }: JwtAuthPluginOptions): JwtAuthPlugin;
+export declare function jwtAuthPlugin({ secret, getUser, rolePermissions, algo, passwordPolicy, tokenTTL, tokenExtractor, checkPermissions, useDynamicRoles, resolveTokenTTL, onAuthFailure, onAuthSuccess, }: JwtAuthPluginOptions): JwtAuthPlugin;

package/dist/FlinkJwtAuthPlugin.js

@@ -65,7 +65,7 @@ var defaultPasswordPolicy = /^(?=.*[A-Za-z])(?=.*\d)[A-Za-z\d]{8,}$/;
  */
 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, onAuthFailure = _a.onAuthFailure;
+    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, onAuthFailure = _a.onAuthFailure, onAuthSuccess = _a.onAuthSuccess;
     return {
         authenticateRequest: function (req, permissions, ctx) { return __awaiter(_this, void 0, void 0, function () {
             return __generator(this, function (_a) {
@@ -77,6 +77,7 @@ function jwtAuthPlugin(_a) {
                         checkPermissions: checkPermissions,
                         useDynamicRoles: useDynamicRoles,
                         onAuthFailure: onAuthFailure,
+                        onAuthSuccess: onAuthSuccess,
                     })];
             });
         }); },
@@ -87,9 +88,9 @@ function jwtAuthPlugin(_a) {
 }
 function authenticateRequest(req_1, routePermissions_1, rolePermissions_1, ctx_1, _a) {
     return __awaiter(this, arguments, void 0, function (req, routePermissions, rolePermissions, ctx, _b) {
-        var fail, token, decodedToken, decodeError, permissionsArr, validPerms, user, validPerms, hasPermission;
+        var fail, token, decodedToken, decodeError, permissionsArr, validPerms, user, validPerms, hasPermission, successRes;
         var _this = this;
-        var secret = _b.secret, algo = _b.algo, getUser = _b.getUser, tokenExtractor = _b.tokenExtractor, checkPermissions = _b.checkPermissions, useDynamicRoles = _b.useDynamicRoles, onAuthFailure = _b.onAuthFailure;
+        var secret = _b.secret, algo = _b.algo, getUser = _b.getUser, tokenExtractor = _b.tokenExtractor, checkPermissions = _b.checkPermissions, useDynamicRoles = _b.useDynamicRoles, onAuthFailure = _b.onAuthFailure, onAuthSuccess = _b.onAuthSuccess;
         return __generator(this, function (_c) {
             switch (_c.label) {
                 case 0:
@@ -183,7 +184,15 @@ function authenticateRequest(req_1, routePermissions_1, rolePermissions_1, ctx_1
                         rolePermissions: rolePermissions,
                         checkPermissions: checkPermissions,
                     });
-                    return [2 /*return*/, true];
+                    if (!onAuthSuccess) return [3 /*break*/, 5];
+                    return [4 /*yield*/, onAuthSuccess(user, req, ctx)];
+                case 4:
+                    successRes = _c.sent();
+                    if (successRes === null || successRes === void 0 ? void 0 : successRes.headers) {
+                        return [2 /*return*/, { authenticated: true, headers: successRes.headers }];
+                    }
+                    _c.label = 5;
+                case 5: return [2 /*return*/, true];
             }
         });
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flink-app/jwt-auth-plugin",
-  "version": "2.0.0-alpha.112",
+  "version": "2.0.0-alpha.114",
   "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.112"
+    "@flink-app/flink": "2.0.0-alpha.114"
   },
   "peerDependencies": {
-    "@flink-app/flink": ">=2.0.0-alpha.112"
+    "@flink-app/flink": ">=2.0.0-alpha.114"
   },
   "gitHead": "4243e3b3cd6d4e1ca001a61baa8436bf2bbe4113",
   "scripts": {

package/readme.md

@@ -74,6 +74,7 @@ start();
 | `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 |
+| `onAuthSuccess` | `(user: FlinkAuthUser, req: FlinkRequest, ctx?: any) => AuthSuccessResult \| void` | No | - | Called on successful authentication, before the handler runs. Return `{ headers }` to add response headers, e.g. a renewed session cookie |
 
 ### Default Password Policy
 
@@ -481,6 +482,46 @@ jwtAuthPlugin({
 
 **Solution**: Clear permission cache or reduce cache TTL
 
+## `onAuthSuccess` - Response Headers From The Auth Step
+
+The counterpart to `onAuthFailure`. It is called **only** when authentication succeeded, right before
+the handler runs, with the user resolved by `getUser`. Return `{ headers }` and Flink applies them to
+whatever response it ends up sending for that request.
+
+This is the seat for cross-cutting concerns the *authentication step* discovers - the canonical one
+being a sliding session: re-sign the cookie JWT when the presented token is running low, and let the
+new cookie ride out on the same response.
+
+```typescript
+jwtAuthPlugin({
+  // ...
+  onAuthSuccess: (user, req, ctx) => {
+    const { exp } = (req.token as { exp?: number }) ?? {};
+    if (!exp) return;
+
+    const now = Math.floor(Date.now() / 1000);
+    if (exp - now > 10 * 60) return; // still fresh, leave the response alone
+
+    const renewed = jwtSimple.encode({ ...req.token, iat: now, exp: now + 30 * 60 }, secret);
+
+    return { headers: { "set-cookie": `jwt=${renewed}; Path=/; HttpOnly; Secure; SameSite=Lax` } };
+  },
+});
+```
+
+**Notes:**
+
+- Never called for a rejected request - missing/invalid token, `no_user` and permission denials all go
+  to `onAuthFailure` instead.
+- Headers apply to every response for that request, including handler errors and framework errors
+  (400 validation, 500 handler exceptions) - the session really was rotated server side.
+- A handler's own `FlinkResponse.headers` are applied afterwards and **win on conflict** for the same
+  header name. Headers that don't collide are kept.
+- Return void (or omit `headers`) to leave the response untouched - the plugin then returns plain
+  `true` exactly as before.
+- Custom auth plugins get the same primitive: `authenticateRequest` may return
+  `{ authenticated: true, headers }` in addition to `true | false | FlinkResponse`.
+
 ## `req.token` & `req.rawToken` - Accessing Token Claims
 
 After successful authentication the plugin attaches the verified token to the request:

package/spec/FlinkJwtAuthPlugin.spec.ts

@@ -1097,3 +1097,77 @@ describe("FlinkJwtAuthPlugin onAuthFailure", () => {
     expect(failures).toEqual([]);
   });
 });
+
+describe("FlinkJwtAuthPlugin onAuthSuccess", () => {
+  const secret = "secret";
+  const renewedCookie = "jwt=renewed; path=/; HttpOnly;";
+
+  const makePlugin = (onAuthSuccess: any, overrides: any = {}) =>
+    jwtAuthPlugin({
+      secret,
+      getUser: async ({ id }: { id: string }) => ({ id, username: "username" }),
+      rolePermissions: { user: ["foo"] },
+      onAuthSuccess,
+      ...overrides,
+    });
+
+  const reqWith = (authorization: string) =>
+    ({ headers: { authorization } } as FlinkRequest);
+
+  const validToken = () => jwtSimple.encode({ id: "123", roles: ["user"] }, secret);
+
+  it("returns the headers from onAuthSuccess as an authenticated result", async () => {
+    const seen: any[] = [];
+    const plugin = makePlugin((user: any, req: FlinkRequest) => {
+      seen.push({ user, hasReq: !!req });
+      return { headers: { "set-cookie": renewedCookie } };
+    });
+
+    const res: any = await plugin.authenticateRequest(reqWith("Bearer " + validToken()), "foo");
+
+    expect(res).toEqual({ authenticated: true, headers: { "set-cookie": renewedCookie } });
+    expect(seen).toEqual([{ user: { id: "123", username: "username" }, hasReq: true }]);
+  });
+
+  it("returns plain true when onAuthSuccess returns void", async () => {
+    const plugin = makePlugin(() => {});
+
+    const res = await plugin.authenticateRequest(reqWith("Bearer " + validToken()), "foo");
+
+    expect(res).toBeTrue();
+  });
+
+  it("supports an async onAuthSuccess", async () => {
+    const plugin = makePlugin(async () => ({ headers: { "set-cookie": renewedCookie } }));
+
+    const res: any = await plugin.authenticateRequest(reqWith("Bearer " + validToken()), "foo");
+
+    expect(res.authenticated).toBeTrue();
+    expect(res.headers["set-cookie"]).toBe(renewedCookie);
+  });
+
+  it("does not invoke onAuthSuccess for a rejected request", async () => {
+    const calls: any[] = [];
+    const plugin = makePlugin(() => {
+      calls.push("called");
+      return { headers: { "set-cookie": renewedCookie } };
+    });
+
+    // missing token, invalid token and permission denied
+    expect(await plugin.authenticateRequest(reqWith(""), "foo")).toBeFalse();
+    expect(await plugin.authenticateRequest(reqWith("Bearer garbage"), "foo")).toBeFalse();
+    expect(await plugin.authenticateRequest(reqWith("Bearer " + validToken()), "bar")).toBeFalse();
+
+    expect(calls).toEqual([]);
+  });
+
+  it("keeps returning plain true when no onAuthSuccess is configured", async () => {
+    const plugin = jwtAuthPlugin({
+      secret,
+      getUser: async ({ id }: { id: string }) => ({ id, username: "username" }),
+      rolePermissions: { user: ["foo"] },
+    });
+
+    expect(await plugin.authenticateRequest(reqWith("Bearer " + validToken()), "foo")).toBeTrue();
+  });
+});

package/src/FlinkJwtAuthPlugin.ts

@@ -1,4 +1,4 @@
-import { FlinkAuthPlugin, FlinkAuthUser, FlinkRequest, FlinkResponse, log } from "@flink-app/flink";
+import { FlinkAuthPlugin, FlinkAuthResult, FlinkAuthUser, FlinkRequest, FlinkResponse, log } from "@flink-app/flink";
 import jwtSimple from "jwt-simple";
 import { encrypt, genSalt } from "./BcryptUtils";
 import { hasValidPermissions } from "./PermissionValidator";
@@ -66,6 +66,33 @@ export type AuthFailureHandler = (
     ctx?: any
 ) => FlinkResponse | void | Promise<FlinkResponse | void>;
 
+/**
+ * What an auth-success callback may contribute to the response.
+ */
+export interface AuthSuccessResult {
+    /**
+     * Headers to merge into whatever response Flink ends up sending for this
+     * request, e.g. a `Set-Cookie` for a renewed session. Headers set by the
+     * handler itself win on conflict.
+     */
+    headers?: Record<string, string>;
+}
+
+/**
+ * Custom auth-success callback, the counterpart to `onAuthFailure`.
+ *
+ * Called only when authentication succeeded, right before the handler runs, with
+ * the user resolved by `getUser`. Return `{ headers }` to have Flink apply those
+ * headers to the response - the seat for cross-cutting concerns discovered during
+ * authentication, such as re-issuing a sliding session cookie. Return void to
+ * leave the response untouched.
+ */
+export type AuthSuccessHandler = (
+    user: FlinkAuthUser,
+    req: FlinkRequest,
+    ctx?: any
+) => AuthSuccessResult | void | Promise<AuthSuccessResult | void>;
+
 /**
  * Custom token TTL resolver callback.
  *
@@ -156,6 +183,25 @@ export interface JwtAuthPluginOptions {
      * ```
      */
     onAuthFailure?: AuthFailureHandler;
+    /**
+     * Optional callback invoked on successful authentication.
+     *
+     * Called with the authenticated user just before the handler runs, and never
+     * for rejected requests. Return `{ headers }` to contribute headers to the
+     * response, e.g. a re-signed session cookie when the presented token is
+     * running low on lifetime. Headers set by the handler win on conflict.
+     *
+     * Example:
+     * ```typescript
+     * onAuthSuccess: (user, req) => {
+     *   const renewed = renewCookieIfExpiring(req);
+     *   if (renewed) {
+     *     return { headers: { "set-cookie": renewed } };
+     *   }
+     * }
+     * ```
+     */
+    onAuthSuccess?: AuthSuccessHandler;
     /**
      * Optional dynamic token TTL resolver.
      *
@@ -207,6 +253,7 @@ export function jwtAuthPlugin({
     useDynamicRoles = false,
     resolveTokenTTL,
     onAuthFailure,
+    onAuthSuccess,
 }: JwtAuthPluginOptions): JwtAuthPlugin {
     return {
         authenticateRequest: async (req, permissions, ctx) =>
@@ -218,6 +265,7 @@ export function jwtAuthPlugin({
                 checkPermissions,
                 useDynamicRoles,
                 onAuthFailure,
+                onAuthSuccess,
             }),
         createToken: (payload, roles) => createToken({ ...payload, roles }, { algo, secret, tokenTTL, resolveTokenTTL }, roles),
         createPasswordHashAndSalt: (password: string) => createPasswordHashAndSalt(password, passwordPolicy),
@@ -230,16 +278,23 @@ async function authenticateRequest(
     routePermissions: string | string[],
     rolePermissions: { [x: string]: string[] },
     ctx: any,
-    { secret, algo, getUser, tokenExtractor, checkPermissions, useDynamicRoles, onAuthFailure }: Pick<
+    { secret, algo, getUser, tokenExtractor, checkPermissions, useDynamicRoles, onAuthFailure, onAuthSuccess }: Pick<
         JwtAuthPluginOptions,
-        "algo" | "secret" | "getUser" | "tokenExtractor" | "checkPermissions" | "useDynamicRoles" | "onAuthFailure"
+        | "algo"
+        | "secret"
+        | "getUser"
+        | "tokenExtractor"
+        | "checkPermissions"
+        | "useDynamicRoles"
+        | "onAuthFailure"
+        | "onAuthSuccess"
     >
-): Promise<boolean | FlinkResponse> {
+): Promise<FlinkAuthResult> {
     /**
      * Resolves a rejected authentication: lets `onAuthFailure` shape the response,
      * falls back to `false` (default 401) when no handler or no response is returned.
      */
-    const fail = async (reason: AuthFailureReason, error?: unknown): Promise<boolean | FlinkResponse> => {
+    const fail = async (reason: AuthFailureReason, error?: unknown): Promise<FlinkAuthResult> => {
         if (onAuthFailure) {
             const failureRes = await onAuthFailure({ reason, error }, req, ctx);
             if (failureRes) {
@@ -338,6 +393,17 @@ async function authenticateRequest(
                 checkPermissions,
             });
 
+            // Success hook runs only here, i.e. never for a rejected request, and may
+            // contribute headers (typically a renewed session cookie) that Flink applies
+            // to the response.
+            if (onAuthSuccess) {
+                const successRes = await onAuthSuccess(user, req, ctx);
+
+                if (successRes?.headers) {
+                    return { authenticated: true, headers: successRes.headers };
+                }
+            }
+
             return true;
         }
     }