@flink-app/flink 2.0.0-alpha.97 → 2.0.0-alpha.99

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # @flink-app/flink
 
+## 2.0.0-alpha.99
+
+### Minor Changes
+
+-   ed9cd2c: Extend `onError` callback to also fire for request validation (400 Bad request) and response validation (500 Bad response) failures, in addition to handler-thrown errors. Streaming handler errors continue to be delivered via `stream.error()` and do not trigger `onError`.
+
+    The callback context now also includes the app context as `ctx`, so handlers can use repos/plugins (e.g. `context.ctx.repos.errorLogRepo`) from within `onError`. `FlinkOptions` is now generic over the app context (`FlinkOptions<C>`) with a default of `FlinkContext`, keeping existing usages backward compatible.
+
+## 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.
+
 ## 2.0.0-alpha.97
 
 ### Minor Changes

package/dist/src/FlinkApp.d.ts

@@ -64,7 +64,7 @@ export declare const autoRegisteredServices: {
     serviceInstanceName: string;
     Service: any;
 }[];
-export interface FlinkOptions {
+export interface FlinkOptions<C extends FlinkContext = FlinkContext> {
     /**
      * Name of application, will only show in logs and in HTTP header.
      */
@@ -215,17 +215,26 @@ export interface FlinkOptions {
         format?: string;
     };
     /**
-     * Optional callback invoked when an error occurs in a handler.
+     * Optional callback invoked when an error occurs while serving a request.
      * The error response and request context are passed for custom
      * error logging or monitoring. This is a side-effect only and
      * will not modify the response flow.
      *
+     * Invoked for:
+     * - Handler-thrown errors (FlinkErrors and unhandled exceptions)
+     * - Request validation failures (400 Bad request)
+     * - Response validation failures (500 Bad response)
+     *
+     * Not invoked for errors in streaming (SSE/NDJSON) handlers, which are
+     * delivered to the client via `stream.error()` instead.
+     *
      * Supports both synchronous and asynchronous callbacks. Any errors
      * thrown or rejected by the callback will be caught and logged
-     * without affecting the error response to the client.
+     * without affecting the error response to the client. Async callbacks
+     * are fire-and-forget — they are not awaited before the response is sent.
      *
      * @param error - The error response with status and error details
-     * @param context - Request context including method, path, and request ID
+     * @param context - Request context including method, path, request ID and the app context
      *
      * @example
      * ```ts
@@ -241,12 +250,14 @@ export interface FlinkOptions {
      *   }
      * }
      *
-     * // Asynchronous callback
+     * // Asynchronous callback using the app context
      * onError: async (error, context) => {
      *   if (error.status >= 500) {
-     *     await monitoringService.reportError({
-     *       error,
-     *       context
+     *     await context.ctx.repos.errorLogRepo.create({
+     *       status: error.status,
+     *       detail: error.error?.detail,
+     *       route: `${context.method} ${context.path}`,
+     *       reqId: context.reqId,
      *     });
      *   }
      * }
@@ -257,6 +268,7 @@ export interface FlinkOptions {
         method: HttpMethod;
         path: string;
         reqId: string;
+        ctx: C;
     }) => void | Promise<void>;
 }
 export interface HandlerConfig {
@@ -317,7 +329,7 @@ export declare class FlinkApp<C extends FlinkContext> {
     private allInstanceScheduler?;
     private leaderElection?;
     private accessLog;
-    constructor(opts: FlinkOptions);
+    constructor(opts: FlinkOptions<C>);
     get ctx(): C;
     start(): Promise<this>;
     stop(): Promise<void>;
@@ -400,6 +412,12 @@ export declare class FlinkApp<C extends FlinkContext> {
      */
     private initPluginDb;
     private authenticate;
+    /**
+     * Invokes the optional onError callback in a fire-and-forget manner.
+     * Any error thrown or rejected by the callback is caught and logged so
+     * it never affects the error response sent to the client.
+     */
+    private invokeOnError;
     getRegisteredRoutes(): string[];
     private get isSchedulingEnabled();
     private get leaderElectionConfig();

package/dist/src/FlinkApp.js

@@ -451,7 +451,7 @@ var FlinkApp = /** @class */ (function () {
                 }
             }
             this.expressApp[method](routeProps.path, function (req, res) { return __awaiter(_this, void 0, void 0, function () {
-                var valid, formattedErrors, data, normalizedQuery, _i, _a, _b, key, value, stream, handlerRes, flinkReq_1, err_1, errorResponse, result, detail, valid, formattedErrors;
+                var valid, formattedErrors, errorResponse, data, normalizedQuery, _i, _a, _b, key, value, stream, handlerRes, flinkReq_1, err_1, errorResponse, detail, errorResponse, valid, formattedErrors, errorResponse;
                 var _this = this;
                 var _c;
                 return __generator(this, function (_d) {
@@ -470,14 +470,16 @@ var FlinkApp = /** @class */ (function () {
                                 if (!valid) {
                                     formattedErrors = (0, utils_1.formatValidationErrors)(validateReq_1.errors, req.body);
                                     FlinkLog_1.log.warn("[".concat(req.reqId, "] ").concat(methodAndRoute_1, ": Bad request\n").concat(formattedErrors));
-                                    return [2 /*return*/, res.status(400).json({
-                                            status: 400,
-                                            error: {
-                                                id: (0, uuid_1.v4)(),
-                                                title: "Bad request",
-                                                detail: formattedErrors,
-                                            },
-                                        })];
+                                    errorResponse = {
+                                        status: 400,
+                                        error: {
+                                            id: (0, uuid_1.v4)(),
+                                            title: "Bad request",
+                                            detail: formattedErrors,
+                                        },
+                                    };
+                                    this.invokeOnError(errorResponse, req, method, routeProps.path);
+                                    return [2 /*return*/, res.status(400).json(errorResponse)];
                                 }
                             }
                             // Skip mock API for streaming handlers
@@ -568,26 +570,7 @@ var FlinkApp = /** @class */ (function () {
                                 console.error(err_1);
                                 errorResponse = (0, FlinkErrors_1.internalServerError)(err_1);
                             }
-                            // Invoke onError callback if provided
-                            if (this.onError) {
-                                try {
-                                    result = this.onError(errorResponse, {
-                                        req: req,
-                                        method: method,
-                                        path: routeProps.path,
-                                        reqId: req.reqId,
-                                    });
-                                    // Handle async callbacks - don't wait for them
-                                    if (result instanceof Promise) {
-                                        result.catch(function (callbackErr) {
-                                            FlinkLog_1.log.error("onError callback rejected with: ".concat(callbackErr));
-                                        });
-                                    }
-                                }
-                                catch (callbackErr) {
-                                    FlinkLog_1.log.error("onError callback threw an exception: ".concat(callbackErr));
-                                }
-                            }
+                            this.invokeOnError(errorResponse, req, method, routeProps.path);
                             return [2 /*return*/, res.status(errorResponse.status || 500).json(errorResponse)];
                         case 6:
                             // Skip response handling for streaming handlers (stream controls response lifecycle)
@@ -603,10 +586,12 @@ var FlinkApp = /** @class */ (function () {
                                     if (handlerRes.status !== 204) {
                                         detail = "Response schema is defined but handler returned no data";
                                         FlinkLog_1.log.warn("[".concat(req.reqId, "] ").concat(methodAndRoute_1, ": Bad response - ").concat(detail));
-                                        return [2 /*return*/, res.status(500).json({
-                                                status: 500,
-                                                error: { id: (0, uuid_1.v4)(), title: "Bad response", detail: detail },
-                                            })];
+                                        errorResponse = {
+                                            status: 500,
+                                            error: { id: (0, uuid_1.v4)(), title: "Bad response", detail: detail },
+                                        };
+                                        this.invokeOnError(errorResponse, req, method, routeProps.path);
+                                        return [2 /*return*/, res.status(500).json(errorResponse)];
                                     }
                                 }
                                 else {
@@ -614,14 +599,16 @@ var FlinkApp = /** @class */ (function () {
                                     if (!valid) {
                                         formattedErrors = (0, utils_1.formatValidationErrors)(validateRes_1.errors, handlerRes.data);
                                         FlinkLog_1.log.warn("[".concat(req.reqId, "] ").concat(methodAndRoute_1, ": Bad response\n").concat(formattedErrors));
-                                        return [2 /*return*/, res.status(500).json({
-                                                status: 500,
-                                                error: {
-                                                    id: (0, uuid_1.v4)(),
-                                                    title: "Bad response",
-                                                    detail: formattedErrors,
-                                                },
-                                            })];
+                                        errorResponse = {
+                                            status: 500,
+                                            error: {
+                                                id: (0, uuid_1.v4)(),
+                                                title: "Bad response",
+                                                detail: formattedErrors,
+                                            },
+                                        };
+                                        this.invokeOnError(errorResponse, req, method, routeProps.path);
+                                        return [2 /*return*/, res.status(500).json(errorResponse)];
                                     }
                                 }
                             }
@@ -1306,6 +1293,34 @@ var FlinkApp = /** @class */ (function () {
             });
         });
     };
+    /**
+     * Invokes the optional onError callback in a fire-and-forget manner.
+     * Any error thrown or rejected by the callback is caught and logged so
+     * it never affects the error response sent to the client.
+     */
+    FlinkApp.prototype.invokeOnError = function (errorResponse, req, method, path) {
+        if (!this.onError) {
+            return;
+        }
+        try {
+            var result = this.onError(errorResponse, {
+                req: req,
+                method: method,
+                path: path,
+                reqId: req.reqId,
+                ctx: this.ctx,
+            });
+            // Handle async callbacks - don't wait for them
+            if (result instanceof Promise) {
+                result.catch(function (callbackErr) {
+                    FlinkLog_1.log.error("onError callback rejected with: ".concat(callbackErr));
+                });
+            }
+        }
+        catch (callbackErr) {
+            FlinkLog_1.log.error("onError callback threw an exception: ".concat(callbackErr));
+        }
+    };
     FlinkApp.prototype.getRegisteredRoutes = function () {
         return Array.from(this.handlerRouteCache.values());
     };

package/dist/src/FlinkHttpHandler.d.ts

@@ -93,11 +93,18 @@ export interface StreamWriter<T = any> {
  * userPermissions is populated by auth plugins during authentication and contains
  * the resolved permissions array based on the plugin's configuration (roles, dynamic
  * roles, custom permissions, etc.)
+ *
+ * token / rawToken are populated by auth plugins that have a token concept (e.g. JWT).
+ * `token` is the decoded, signature-verified payload; `rawToken` is the original token
+ * string that authenticated the request (Bearer header or custom tokenExtractor output).
+ * Both are optional and only set once authentication succeeds.
  */
 export type FlinkRequest<T = any, P = Params, Q = Query> = Request<P, any, T, Q> & {
     reqId: string;
     user?: any;
     userPermissions?: string[];
+    token?: any;
+    rawToken?: string;
 };
 /**
  * Route props to control routing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flink-app/flink",
-  "version": "2.0.0-alpha.97",
+  "version": "2.0.0-alpha.99",
   "description": "Typescript only framework for creating REST-like APIs on top of Express and mongodb",
   "types": "dist/src/index.d.ts",
   "main": "dist/src/index.js",

package/spec/FlinkApp.onError.invocation.spec.ts

@@ -0,0 +1,151 @@
+import { FlinkApp } from "../src/FlinkApp";
+import { FlinkContext } from "../src/FlinkContext";
+import { FlinkError } from "../src/FlinkErrors";
+import { GetHandler, Handler, HttpMethod } from "../src/FlinkHttpHandler";
+import { FlinkResponse } from "../src/FlinkResponse";
+
+const request = require("supertest");
+
+interface TestContext extends FlinkContext {}
+
+const reqSchema = {
+    type: "object",
+    properties: {
+        name: { type: "string" },
+    },
+    required: ["name"],
+    additionalProperties: false,
+};
+
+const resSchema = {
+    type: "object",
+    properties: {
+        id: { type: "string" },
+    },
+    required: ["id"],
+};
+
+describe("FlinkApp onError invocation", () => {
+    let app: FlinkApp<TestContext>;
+    let calls: { error: FlinkResponse<FlinkError>; context: any }[];
+
+    const onError = (error: FlinkResponse<FlinkError>, context: any) => {
+        calls.push({ error, context });
+    };
+
+    beforeEach(() => {
+        calls = [];
+    });
+
+    afterEach(async () => {
+        if (app && app.started) {
+            await app.stop();
+        }
+    });
+
+    it("should invoke onError for request validation 400s", async () => {
+        const handler: Handler<TestContext, any, any> = async () => {
+            return { data: { id: "ok" } };
+        };
+
+        app = new FlinkApp<TestContext>({ name: "test-onerror-req", port: 4210, onError });
+        await app.start();
+
+        app.addHandler({
+            default: handler,
+            Route: { method: HttpMethod.post, path: "/test", reqSchema },
+        });
+
+        const response = await request(app.expressApp).post("/test").send({ wrong: "field" });
+
+        expect(response.status).toBe(400);
+        expect(calls.length).toBe(1);
+        expect(calls[0].error.status).toBe(400);
+        expect(calls[0].error.error?.title).toBe("Bad request");
+        expect(calls[0].context.method).toBe(HttpMethod.post);
+        expect(calls[0].context.path).toBe("/test");
+        expect(calls[0].context.reqId).toBeDefined();
+    });
+
+    it("should invoke onError for response validation 500s (invalid shape)", async () => {
+        const handler: GetHandler<TestContext, any> = async () => {
+            return { data: { wrongField: 123 } }; // missing required "id"
+        };
+
+        app = new FlinkApp<TestContext>({ name: "test-onerror-res", port: 4211, onError });
+        await app.start();
+
+        app.addHandler({
+            default: handler,
+            Route: { method: HttpMethod.get, path: "/test", resSchema },
+        });
+
+        const response = await request(app.expressApp).get("/test");
+
+        expect(response.status).toBe(500);
+        expect(calls.length).toBe(1);
+        expect(calls[0].error.status).toBe(500);
+        expect(calls[0].error.error?.title).toBe("Bad response");
+    });
+
+    it("should invoke onError for response validation 500s (no data)", async () => {
+        const handler: GetHandler<TestContext, any> = async () => {
+            return { status: 200 } as any; // no data
+        };
+
+        app = new FlinkApp<TestContext>({ name: "test-onerror-nodata", port: 4212, onError });
+        await app.start();
+
+        app.addHandler({
+            default: handler,
+            Route: { method: HttpMethod.get, path: "/test", resSchema },
+        });
+
+        const response = await request(app.expressApp).get("/test");
+
+        expect(response.status).toBe(500);
+        expect(calls.length).toBe(1);
+        expect(calls[0].error.status).toBe(500);
+        expect(calls[0].error.error?.title).toBe("Bad response");
+    });
+
+    it("should still invoke onError for handler-thrown errors", async () => {
+        const handler: GetHandler<TestContext, any> = async () => {
+            throw new Error("boom");
+        };
+
+        app = new FlinkApp<TestContext>({ name: "test-onerror-throw", port: 4213, onError });
+        await app.start();
+
+        app.addHandler({
+            default: handler,
+            Route: { method: HttpMethod.get, path: "/test" },
+        });
+
+        const response = await request(app.expressApp).get("/test");
+
+        expect(response.status).toBe(500);
+        expect(calls.length).toBe(1);
+        expect(calls[0].error.status).toBe(500);
+    });
+
+    it("should pass the app context (ctx) to the callback", async () => {
+        const handler: GetHandler<TestContext, any> = async () => {
+            throw new Error("boom");
+        };
+
+        app = new FlinkApp<TestContext>({ name: "test-onerror-ctx", port: 4214, onError });
+        await app.start();
+
+        app.addHandler({
+            default: handler,
+            Route: { method: HttpMethod.get, path: "/test" },
+        });
+
+        await request(app.expressApp).get("/test");
+
+        expect(calls.length).toBe(1);
+        expect(calls[0].context.ctx).toBeDefined();
+        expect(calls[0].context.ctx).toBe(app.ctx);
+    });
+});

package/src/FlinkApp.ts

@@ -99,7 +99,7 @@ export const autoRegisteredServices: {
     Service: any;
 }[] = [];
 
-export interface FlinkOptions {
+export interface FlinkOptions<C extends FlinkContext = FlinkContext> {
     /**
      * Name of application, will only show in logs and in HTTP header.
      */
@@ -269,17 +269,26 @@ export interface FlinkOptions {
     };
 
     /**
-     * Optional callback invoked when an error occurs in a handler.
+     * Optional callback invoked when an error occurs while serving a request.
      * The error response and request context are passed for custom
      * error logging or monitoring. This is a side-effect only and
      * will not modify the response flow.
      *
+     * Invoked for:
+     * - Handler-thrown errors (FlinkErrors and unhandled exceptions)
+     * - Request validation failures (400 Bad request)
+     * - Response validation failures (500 Bad response)
+     *
+     * Not invoked for errors in streaming (SSE/NDJSON) handlers, which are
+     * delivered to the client via `stream.error()` instead.
+     *
      * Supports both synchronous and asynchronous callbacks. Any errors
      * thrown or rejected by the callback will be caught and logged
-     * without affecting the error response to the client.
+     * without affecting the error response to the client. Async callbacks
+     * are fire-and-forget — they are not awaited before the response is sent.
      *
      * @param error - The error response with status and error details
-     * @param context - Request context including method, path, and request ID
+     * @param context - Request context including method, path, request ID and the app context
      *
      * @example
      * ```ts
@@ -295,12 +304,14 @@ export interface FlinkOptions {
      *   }
      * }
      *
-     * // Asynchronous callback
+     * // Asynchronous callback using the app context
      * onError: async (error, context) => {
      *   if (error.status >= 500) {
-     *     await monitoringService.reportError({
-     *       error,
-     *       context
+     *     await context.ctx.repos.errorLogRepo.create({
+     *       status: error.status,
+     *       detail: error.error?.detail,
+     *       route: `${context.method} ${context.path}`,
+     *       reqId: context.reqId,
      *     });
      *   }
      * }
@@ -313,6 +324,7 @@ export interface FlinkOptions {
             method: HttpMethod;
             path: string;
             reqId: string;
+            ctx: C;
         }
     ) => void | Promise<void>;
 }
@@ -362,7 +374,7 @@ export class FlinkApp<C extends FlinkContext> {
     private schedulingOptions?: FlinkOptions["scheduling"];
     private disableHttpServer = false;
     private expressServer: any; // for simplicity, we don't want to import types from express/node here
-    private onError?: FlinkOptions["onError"];
+    private onError?: FlinkOptions<C>["onError"];
 
     private repos: { [x: string]: FlinkRepo<C, any> } = {};
     private services: { [x: string]: FlinkService<C> } = {};
@@ -383,7 +395,7 @@ export class FlinkApp<C extends FlinkContext> {
 
     private accessLog: { enabled: boolean; format: string };
 
-    constructor(opts: FlinkOptions) {
+    constructor(opts: FlinkOptions<C>) {
         // Load config file and initialize logging
         const { loadFlinkConfig } = require("./utils/loadFlinkConfig");
         const flinkConfig = loadFlinkConfig();
@@ -713,14 +725,18 @@ export class FlinkApp<C extends FlinkContext> {
                         const formattedErrors = formatValidationErrors(validateReq.errors, req.body);
                         log.warn(`[${req.reqId}] ${methodAndRoute}: Bad request\n${formattedErrors}`);
 
-                        return res.status(400).json({
+                        const errorResponse: FlinkResponse<FlinkError> = {
                             status: 400,
                             error: {
                                 id: v4(),
                                 title: "Bad request",
                                 detail: formattedErrors,
                             },
-                        });
+                        };
+
+                        this.invokeOnError(errorResponse, req as FlinkRequest, method!, routeProps.path);
+
+                        return res.status(400).json(errorResponse);
                     }
                 }
 
@@ -813,26 +829,7 @@ export class FlinkApp<C extends FlinkContext> {
                         errorResponse = internalServerError(err as any);
                     }
 
-                    // Invoke onError callback if provided
-                    if (this.onError) {
-                        try {
-                            const result = this.onError(errorResponse, {
-                                req: req as FlinkRequest,
-                                method: method!,
-                                path: routeProps.path,
-                                reqId: req.reqId,
-                            });
-
-                            // Handle async callbacks - don't wait for them
-                            if (result instanceof Promise) {
-                                result.catch((callbackErr) => {
-                                    log.error(`onError callback rejected with: ${callbackErr}`);
-                                });
-                            }
-                        } catch (callbackErr) {
-                            log.error(`onError callback threw an exception: ${callbackErr}`);
-                        }
-                    }
+                    this.invokeOnError(errorResponse, req as FlinkRequest, method!, routeProps.path);
 
                     return res.status(errorResponse.status || 500).json(errorResponse);
                 }
@@ -853,10 +850,15 @@ export class FlinkApp<C extends FlinkContext> {
                             const detail =
                                 "Response schema is defined but handler returned no data";
                             log.warn(`[${req.reqId}] ${methodAndRoute}: Bad response - ${detail}`);
-                            return res.status(500).json({
+
+                            const errorResponse: FlinkResponse<FlinkError> = {
                                 status: 500,
                                 error: { id: v4(), title: "Bad response", detail },
-                            });
+                            };
+
+                            this.invokeOnError(errorResponse, req as FlinkRequest, method!, routeProps.path);
+
+                            return res.status(500).json(errorResponse);
                         }
                     } else {
                         const valid = validateRes(JSON.parse(JSON.stringify(handlerRes.data)));
@@ -865,14 +867,18 @@ export class FlinkApp<C extends FlinkContext> {
                             const formattedErrors = formatValidationErrors(validateRes.errors, handlerRes.data);
                             log.warn(`[${req.reqId}] ${methodAndRoute}: Bad response\n${formattedErrors}`);
 
-                            return res.status(500).json({
+                            const errorResponse: FlinkResponse<FlinkError> = {
                                 status: 500,
                                 error: {
                                     id: v4(),
                                     title: "Bad response",
                                     detail: formattedErrors,
                                 },
-                            });
+                            };
+
+                            this.invokeOnError(errorResponse, req as FlinkRequest, method!, routeProps.path);
+
+                            return res.status(500).json(errorResponse);
                         }
                     }
                 }
@@ -1583,6 +1589,36 @@ export class FlinkApp<C extends FlinkContext> {
         return await this.auth.authenticateRequest(req as FlinkRequest, permissions, this._ctx);
     }
 
+    /**
+     * Invokes the optional onError callback in a fire-and-forget manner.
+     * Any error thrown or rejected by the callback is caught and logged so
+     * it never affects the error response sent to the client.
+     */
+    private invokeOnError(errorResponse: FlinkResponse<FlinkError>, req: FlinkRequest, method: HttpMethod, path: string) {
+        if (!this.onError) {
+            return;
+        }
+
+        try {
+            const result = this.onError(errorResponse, {
+                req,
+                method,
+                path,
+                reqId: req.reqId,
+                ctx: this.ctx,
+            });
+
+            // Handle async callbacks - don't wait for them
+            if (result instanceof Promise) {
+                result.catch((callbackErr) => {
+                    log.error(`onError callback rejected with: ${callbackErr}`);
+                });
+            }
+        } catch (callbackErr) {
+            log.error(`onError callback threw an exception: ${callbackErr}`);
+        }
+    }
+
     public getRegisteredRoutes() {
         return Array.from(this.handlerRouteCache.values());
     }

package/src/FlinkHttpHandler.ts

@@ -104,11 +104,18 @@ export interface StreamWriter<T = any> {
  * userPermissions is populated by auth plugins during authentication and contains
  * the resolved permissions array based on the plugin's configuration (roles, dynamic
  * roles, custom permissions, etc.)
+ *
+ * token / rawToken are populated by auth plugins that have a token concept (e.g. JWT).
+ * `token` is the decoded, signature-verified payload; `rawToken` is the original token
+ * string that authenticated the request (Bearer header or custom tokenExtractor output).
+ * Both are optional and only set once authentication succeeds.
  */
 export type FlinkRequest<T = any, P = Params, Q = Query> = Request<P, any, T, Q> & {
     reqId: string;
     user?: any;
     userPermissions?: string[]; // Resolved permissions from auth plugin
+    token?: any; // Decoded, verified token payload (set by auth plugin)
+    rawToken?: string; // Raw token string that authenticated the request
 };
 
 /**