@flink-app/jwt-auth-plugin 2.0.0-alpha.104 → 2.0.0-alpha.106

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @flink-app/jwt-auth-plugin
 
+## 2.0.0-alpha.106
+
+### Patch Changes
+
+-   @flink-app/flink@2.0.0-alpha.106
+
+## 2.0.0-alpha.105
+
+### Minor Changes
+
+-   6b11000: Custom auth-failure responses. `FlinkAuthPlugin.authenticateRequest` may now return a `FlinkResponse` (in addition to `boolean`) to replace the default `401 Unauthorized` — status (defaults to 401), error object, and headers (applied to the HTTP response, stripped from the JSON body, `reqId` injected). The jwt-auth-plugin exposes this via a new `onAuthFailure({ reason, error }, req, ctx)` option, called with a typed reason (`missing_token` | `invalid_token` | `no_user` | `permission_denied`; `invalid_token` carries the underlying decode error) — return a `FlinkResponse` to shape the failure or void to keep the 401. Fully backward compatible: existing plugins returning booleans behave unchanged.
+
+### Patch Changes
+
+-   Updated dependencies [6b11000]
+    -   @flink-app/flink@2.0.0-alpha.105
+
 ## 2.0.0-alpha.104
 
 ### Patch Changes

package/dist/FlinkJwtAuthPlugin.d.ts

@@ -1,4 +1,4 @@
-import { FlinkAuthPlugin, FlinkAuthUser, FlinkRequest } from "@flink-app/flink";
+import { FlinkAuthPlugin, FlinkAuthUser, FlinkRequest, FlinkResponse } from "@flink-app/flink";
 import jwtSimple from "jwt-simple";
 /**
  * Custom token extraction callback.
@@ -20,6 +20,31 @@ export type TokenExtractor = (req: FlinkRequest) => string | null | undefined;
  * @returns true if user has required permissions, false otherwise
  */
 export type PermissionChecker = (user: FlinkAuthUser, routePermissions: string[]) => Promise<boolean> | boolean;
+/**
+ * Why an authentication attempt was rejected.
+ *
+ * - `missing_token`: no token found on the request (after tokenExtractor / Bearer fallback)
+ * - `invalid_token`: token could not be decoded/verified (expired, bad signature, malformed)
+ * - `no_user`: token was valid but `getUser` returned null/undefined (e.g. revoked session)
+ * - `permission_denied`: user is authenticated but lacks the route's permissions
+ */
+export type AuthFailureReason = "missing_token" | "invalid_token" | "no_user" | "permission_denied";
+export interface AuthFailure {
+    reason: AuthFailureReason;
+    /**
+     * The underlying error for `invalid_token` (whatever jwt decode threw, e.g.
+     * "Token expired" / "Signature verification failed"). Undefined otherwise.
+     */
+    error?: unknown;
+}
+/**
+ * Custom auth-failure response callback.
+ *
+ * Called whenever authentication is rejected. Return a `FlinkResponse` to have Flink
+ * send exactly that response (status, error object, headers such as `Set-Cookie`)
+ * 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>;
 /**
  * Custom token TTL resolver callback.
  *
@@ -91,6 +116,24 @@ export interface JwtAuthPluginOptions {
      * ```
      */
     useDynamicRoles?: boolean;
+    /**
+     * Optional custom auth-failure responses.
+     *
+     * Called with the failure reason whenever authentication is rejected
+     * (missing/invalid token, no user, permission denied). Return a `FlinkResponse`
+     * to replace the default `401 Unauthorized` — e.g. a 403 with a domain error code
+     * and a `Set-Cookie` header clearing a stale cookie. Return void to keep the 401.
+     *
+     * Example:
+     * ```typescript
+     * onAuthFailure: ({ reason }) => {
+     *   if (reason === "permission_denied") {
+     *     return { status: 403, error: { id: uuid(), code: "PERMISSION_DENIED", title: "Permission denied" } };
+     *   }
+     * }
+     * ```
+     */
+    onAuthFailure?: AuthFailureHandler;
     /**
      * Optional dynamic token TTL resolver.
      *
@@ -130,4 +173,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, }: JwtAuthPluginOptions): JwtAuthPlugin;
+export declare function jwtAuthPlugin({ secret, getUser, rolePermissions, algo, passwordPolicy, tokenTTL, tokenExtractor, checkPermissions, useDynamicRoles, resolveTokenTTL, onAuthFailure, }: 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;
+    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;
     return {
         authenticateRequest: function (req, permissions, ctx) { return __awaiter(_this, void 0, void 0, function () {
             return __generator(this, function (_a) {
@@ -76,6 +76,7 @@ function jwtAuthPlugin(_a) {
                         tokenExtractor: tokenExtractor,
                         checkPermissions: checkPermissions,
                         useDynamicRoles: useDynamicRoles,
+                        onAuthFailure: onAuthFailure,
                     })];
             });
         }); },
@@ -86,11 +87,29 @@ 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 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;
+        var fail, token, decodedToken, decodeError, permissionsArr, validPerms, user, validPerms, hasPermission;
+        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;
         return __generator(this, function (_c) {
             switch (_c.label) {
                 case 0:
+                    fail = function (reason, error) { return __awaiter(_this, void 0, void 0, function () {
+                        var failureRes;
+                        return __generator(this, function (_a) {
+                            switch (_a.label) {
+                                case 0:
+                                    if (!onAuthFailure) return [3 /*break*/, 2];
+                                    return [4 /*yield*/, onAuthFailure({ reason: reason, error: error }, req, ctx)];
+                                case 1:
+                                    failureRes = _a.sent();
+                                    if (failureRes) {
+                                        return [2 /*return*/, failureRes];
+                                    }
+                                    _a.label = 2;
+                                case 2: return [2 /*return*/, false];
+                            }
+                        });
+                    }); };
                     if (tokenExtractor) {
                         token = tokenExtractor(req);
                         // If tokenExtractor returns undefined, fall back to default
@@ -104,22 +123,28 @@ function authenticateRequest(req_1, routePermissions_1, rolePermissions_1, ctx_1
                         // No custom extractor, use default
                         token = getTokenFromReq(req);
                     }
-                    if (!token) return [3 /*break*/, 4];
+                    if (!token) {
+                        return [2 /*return*/, fail("missing_token")];
+                    }
                     decodedToken = void 0;
+                    decodeError = void 0;
                     try {
                         decodedToken = jwt_simple_1.default.decode(token, secret, false, algo);
                     }
                     catch (err) {
                         flink_1.log.debug("[JWT AUTH PLUGIN] Failed to decode token: ".concat(err));
+                        decodeError = err;
                         decodedToken = null;
                     }
-                    if (!decodedToken) return [3 /*break*/, 4];
+                    if (!decodedToken) {
+                        return [2 /*return*/, fail("invalid_token", decodeError)];
+                    }
                     permissionsArr = Array.isArray(routePermissions) ? routePermissions : [routePermissions];
                     // Static permission check - only if custom checker NOT provided AND not using dynamic roles
                     if (!checkPermissions && !useDynamicRoles && permissionsArr && permissionsArr.length > 0) {
                         validPerms = (0, PermissionValidator_1.hasValidPermissions)(decodedToken.roles || [], rolePermissions, permissionsArr);
                         if (!validPerms) {
-                            return [2 /*return*/, false];
+                            return [2 /*return*/, fail("permission_denied")];
                         }
                     }
                     return [4 /*yield*/, getUser(decodedToken, req, ctx)];
@@ -127,14 +152,14 @@ function authenticateRequest(req_1, routePermissions_1, rolePermissions_1, ctx_1
                     user = _c.sent();
                     if (!user) {
                         flink_1.log.debug("[JWT AUTH PLUGIN] User not returned from getUser callback");
-                        return [2 /*return*/, false];
+                        return [2 /*return*/, fail("no_user")];
                     }
                     // Dynamic roles: check permissions using roles from user object
                     if (!checkPermissions && useDynamicRoles && permissionsArr && permissionsArr.length > 0) {
                         validPerms = (0, PermissionValidator_1.hasValidPermissions)(user.roles || [], rolePermissions, permissionsArr);
                         if (!validPerms) {
                             flink_1.log.debug("[JWT AUTH PLUGIN] Dynamic role permission check failed");
-                            return [2 /*return*/, false];
+                            return [2 /*return*/, fail("permission_denied")];
                         }
                     }
                     if (!(checkPermissions && permissionsArr && permissionsArr.length > 0)) return [3 /*break*/, 3];
@@ -143,7 +168,7 @@ function authenticateRequest(req_1, routePermissions_1, rolePermissions_1, ctx_1
                     hasPermission = _c.sent();
                     if (!hasPermission) {
                         flink_1.log.debug("[JWT AUTH PLUGIN] Custom permission check failed");
-                        return [2 /*return*/, false];
+                        return [2 /*return*/, fail("permission_denied")];
                     }
                     _c.label = 3;
                 case 3:
@@ -159,7 +184,6 @@ function authenticateRequest(req_1, routePermissions_1, rolePermissions_1, ctx_1
                         checkPermissions: checkPermissions,
                     });
                     return [2 /*return*/, true];
-                case 4: return [2 /*return*/, false];
             }
         });
     });

package/package.json

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

package/spec/FlinkJwtAuthPlugin.spec.ts

@@ -976,3 +976,124 @@ describe("FlinkJwtAuthPlugin", () => {
     });
   });
 });
+
+describe("FlinkJwtAuthPlugin onAuthFailure", () => {
+  const secret = "secret";
+
+  const makePlugin = (
+    onAuthFailure: any,
+    overrides: any = {}
+  ) =>
+    jwtAuthPlugin({
+      secret,
+      getUser: async ({ id }: { id: string }) => ({ id, username: "username" }),
+      rolePermissions: { user: ["foo"] },
+      onAuthFailure,
+      ...overrides,
+    });
+
+  const reqWith = (authorization: string) =>
+    ({ headers: { authorization } } as FlinkRequest);
+
+  it("reports missing_token and passes the returned FlinkResponse through", async () => {
+    const failures: any[] = [];
+    const plugin = makePlugin((failure: any) => {
+      failures.push(failure);
+      return { status: 403, error: { id: "1", code: "MUST_BE_LOGGED_IN", title: "Permission denied" } };
+    });
+
+    const res = await plugin.authenticateRequest(reqWith(""), "foo");
+
+    expect(failures).toEqual([{ reason: "missing_token", error: undefined }]);
+    expect(res).toEqual({ status: 403, error: { id: "1", code: "MUST_BE_LOGGED_IN", title: "Permission denied" } } as any);
+  });
+
+  it("reports invalid_token with the underlying decode error", async () => {
+    const failures: any[] = [];
+    const plugin = makePlugin((failure: any) => {
+      failures.push(failure);
+      return { status: 403, error: { id: "2", code: "auth-service.403.1", title: "Invalid JWT token" } };
+    });
+
+    const expired = jwtSimple.encode({ id: "123", roles: ["user"], exp: Date.now() / 1000 - 60 }, secret);
+    const res: any = await plugin.authenticateRequest(reqWith("Bearer " + expired), "foo");
+
+    expect(failures.length).toBe(1);
+    expect(failures[0].reason).toBe("invalid_token");
+    expect(String(failures[0].error)).toContain("Token expired");
+    expect(res.status).toBe(403);
+  });
+
+  it("reports no_user when getUser returns null", async () => {
+    const failures: any[] = [];
+    const plugin = jwtAuthPlugin({
+      secret,
+      getUser: async () => null,
+      rolePermissions: { user: ["foo"] },
+      onAuthFailure: (failure) => {
+        failures.push(failure);
+      },
+    });
+
+    const token = jwtSimple.encode({ id: "123", roles: ["user"] }, secret);
+    const res = await plugin.authenticateRequest(reqWith("Bearer " + token), "foo");
+
+    expect(failures.map((f) => f.reason)).toEqual(["no_user"]);
+    // Callback returned void -> default behaviour (false -> 401 in core)
+    expect(res).toBeFalse();
+  });
+
+  it("reports permission_denied from the static role check", async () => {
+    const failures: any[] = [];
+    const plugin = makePlugin((failure: any) => {
+      failures.push(failure);
+    });
+
+    const token = jwtSimple.encode({ id: "123", roles: ["user"] }, secret);
+    const res = await plugin.authenticateRequest(reqWith("Bearer " + token), "bar");
+
+    expect(failures.map((f) => f.reason)).toEqual(["permission_denied"]);
+    expect(res).toBeFalse();
+  });
+
+  it("reports permission_denied from a custom checkPermissions", async () => {
+    const failures: any[] = [];
+    const plugin = makePlugin(
+      (failure: any) => {
+        failures.push(failure);
+        return { status: 403, error: { id: "3", code: "PERMISSION_DENIED", title: "Permission denied" } };
+      },
+      { checkPermissions: async () => false }
+    );
+
+    const token = jwtSimple.encode({ id: "123", roles: ["user"] }, secret);
+    const res: any = await plugin.authenticateRequest(reqWith("Bearer " + token), "foo");
+
+    expect(failures.map((f) => f.reason)).toEqual(["permission_denied"]);
+    expect(res.error.code).toBe("PERMISSION_DENIED");
+  });
+
+  it("keeps returning plain false when no onAuthFailure is configured", async () => {
+    const plugin = jwtAuthPlugin({
+      secret,
+      getUser: async ({ id }: { id: string }) => ({ id, username: "username" }),
+      rolePermissions: { user: ["foo"] },
+    });
+
+    expect(await plugin.authenticateRequest(reqWith(""), "foo")).toBeFalse();
+    expect(await plugin.authenticateRequest(reqWith("Bearer garbage"), "foo")).toBeFalse();
+  });
+
+  it("does not invoke onAuthFailure on successful auth", async () => {
+    const failures: any[] = [];
+    const plugin = makePlugin((failure: any) => {
+      failures.push(failure);
+    });
+
+    const token = jwtSimple.encode({ id: "123", roles: ["user"] }, secret);
+    const res = await plugin.authenticateRequest(reqWith("Bearer " + token), "foo");
+
+    expect(res).toBeTrue();
+    expect(failures).toEqual([]);
+  });
+});

package/src/FlinkJwtAuthPlugin.ts

@@ -1,4 +1,4 @@
-import { FlinkAuthPlugin, FlinkAuthUser, FlinkRequest, log } from "@flink-app/flink";
+import { FlinkAuthPlugin, FlinkAuthUser, FlinkRequest, FlinkResponse, log } from "@flink-app/flink";
 import jwtSimple from "jwt-simple";
 import { encrypt, genSalt } from "./BcryptUtils";
 import { hasValidPermissions } from "./PermissionValidator";
@@ -34,6 +34,38 @@ export type PermissionChecker = (
     routePermissions: string[]
 ) => Promise<boolean> | boolean;
 
+/**
+ * Why an authentication attempt was rejected.
+ *
+ * - `missing_token`: no token found on the request (after tokenExtractor / Bearer fallback)
+ * - `invalid_token`: token could not be decoded/verified (expired, bad signature, malformed)
+ * - `no_user`: token was valid but `getUser` returned null/undefined (e.g. revoked session)
+ * - `permission_denied`: user is authenticated but lacks the route's permissions
+ */
+export type AuthFailureReason = "missing_token" | "invalid_token" | "no_user" | "permission_denied";
+
+export interface AuthFailure {
+    reason: AuthFailureReason;
+    /**
+     * The underlying error for `invalid_token` (whatever jwt decode threw, e.g.
+     * "Token expired" / "Signature verification failed"). Undefined otherwise.
+     */
+    error?: unknown;
+}
+
+/**
+ * Custom auth-failure response callback.
+ *
+ * Called whenever authentication is rejected. Return a `FlinkResponse` to have Flink
+ * send exactly that response (status, error object, headers such as `Set-Cookie`)
+ * 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>;
+
 /**
  * Custom token TTL resolver callback.
  *
@@ -106,6 +138,24 @@ export interface JwtAuthPluginOptions {
      * ```
      */
     useDynamicRoles?: boolean;
+    /**
+     * Optional custom auth-failure responses.
+     *
+     * Called with the failure reason whenever authentication is rejected
+     * (missing/invalid token, no user, permission denied). Return a `FlinkResponse`
+     * to replace the default `401 Unauthorized` — e.g. a 403 with a domain error code
+     * and a `Set-Cookie` header clearing a stale cookie. Return void to keep the 401.
+     *
+     * Example:
+     * ```typescript
+     * onAuthFailure: ({ reason }) => {
+     *   if (reason === "permission_denied") {
+     *     return { status: 403, error: { id: uuid(), code: "PERMISSION_DENIED", title: "Permission denied" } };
+     *   }
+     * }
+     * ```
+     */
+    onAuthFailure?: AuthFailureHandler;
     /**
      * Optional dynamic token TTL resolver.
      *
@@ -156,6 +206,7 @@ export function jwtAuthPlugin({
     checkPermissions,
     useDynamicRoles = false,
     resolveTokenTTL,
+    onAuthFailure,
 }: JwtAuthPluginOptions): JwtAuthPlugin {
     return {
         authenticateRequest: async (req, permissions, ctx) =>
@@ -166,6 +217,7 @@ export function jwtAuthPlugin({
                 tokenExtractor,
                 checkPermissions,
                 useDynamicRoles,
+                onAuthFailure,
             }),
         createToken: (payload, roles) => createToken({ ...payload, roles }, { algo, secret, tokenTTL, resolveTokenTTL }, roles),
         createPasswordHashAndSalt: (password: string) => createPasswordHashAndSalt(password, passwordPolicy),
@@ -178,11 +230,25 @@ async function authenticateRequest(
     routePermissions: string | string[],
     rolePermissions: { [x: string]: string[] },
     ctx: any,
-    { secret, algo, getUser, tokenExtractor, checkPermissions, useDynamicRoles }: Pick<
+    { secret, algo, getUser, tokenExtractor, checkPermissions, useDynamicRoles, onAuthFailure }: Pick<
         JwtAuthPluginOptions,
-        "algo" | "secret" | "getUser" | "tokenExtractor" | "checkPermissions" | "useDynamicRoles"
+        "algo" | "secret" | "getUser" | "tokenExtractor" | "checkPermissions" | "useDynamicRoles" | "onAuthFailure"
     >
-) {
+): Promise<boolean | FlinkResponse> {
+    /**
+     * 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> => {
+        if (onAuthFailure) {
+            const failureRes = await onAuthFailure({ reason, error }, req, ctx);
+            if (failureRes) {
+                return failureRes;
+            }
+        }
+        return false;
+    };
+
     let token: string | null | undefined;
 
     if (tokenExtractor) {
@@ -199,17 +265,27 @@ async function authenticateRequest(
         token = getTokenFromReq(req);
     }
 
-    if (token) {
+    if (!token) {
+        return fail("missing_token");
+    }
+
+    {
         let decodedToken;
+        let decodeError: unknown;
 
         try {
             decodedToken = jwtSimple.decode(token, secret, false, algo);
         } catch (err) {
             log.debug(`[JWT AUTH PLUGIN] Failed to decode token: ${err}`);
+            decodeError = err;
             decodedToken = null;
         }
 
-        if (decodedToken) {
+        if (!decodedToken) {
+            return fail("invalid_token", decodeError);
+        }
+
+        {
             const permissionsArr = Array.isArray(routePermissions) ? routePermissions : [routePermissions];
 
             // Static permission check - only if custom checker NOT provided AND not using dynamic roles
@@ -217,7 +293,7 @@ async function authenticateRequest(
                 const validPerms = hasValidPermissions(decodedToken.roles || [], rolePermissions, permissionsArr);
 
                 if (!validPerms) {
-                    return false;
+                    return fail("permission_denied");
                 }
             }
 
@@ -225,7 +301,7 @@ async function authenticateRequest(
 
             if (!user) {
                 log.debug("[JWT AUTH PLUGIN] User not returned from getUser callback");
-                return false;
+                return fail("no_user");
             }
 
             // Dynamic roles: check permissions using roles from user object
@@ -234,7 +310,7 @@ async function authenticateRequest(
 
                 if (!validPerms) {
                     log.debug("[JWT AUTH PLUGIN] Dynamic role permission check failed");
-                    return false;
+                    return fail("permission_denied");
                 }
             }
 
@@ -244,7 +320,7 @@ async function authenticateRequest(
 
                 if (!hasPermission) {
                     log.debug("[JWT AUTH PLUGIN] Custom permission check failed");
-                    return false;
+                    return fail("permission_denied");
                 }
             }
 
@@ -265,7 +341,6 @@ async function authenticateRequest(
             return true;
         }
     }
-    return false;
 }
 
 function getTokenFromReq(req: FlinkRequest) {