@flink-app/flink 0.14.3 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,65 @@
 # @flink-app/flink
 
+## 1.0.0
+
+### Minor Changes
+
+-   Align minor version, from now all packages in monorepo will have same version
+-   5c2ff97: Add schema validation bypass options to RouteProps
+
+    Handlers can now control schema validation behavior via the new `validation` property in `RouteProps`:
+
+    -   `ValidationMode.Validate` (default): Validate both request and response
+    -   `ValidationMode.SkipValidation`: Skip both request and response validation
+    -   `ValidationMode.ValidateRequest`: Validate only request, skip response validation
+    -   `ValidationMode.ValidateResponse`: Validate only response, skip request validation
+
+    This is useful for handlers that need custom validation logic or want to bypass validation for performance reasons. The feature is opt-in and defaults to existing behavior.
+
+    **Security Considerations:**
+
+    ⚠️ Use validation bypass options carefully:
+
+    -   `SkipValidation` and `ValidateRequest: false` allow unvalidated data to reach handlers, which can introduce security risks
+    -   Only skip validation when you have implemented custom validation logic or the endpoint is internal/trusted
+    -   Suitable use cases include: webhook handlers with custom signature verification, performance-critical internal endpoints, or handlers using alternative validation methods
+    -   When skipping response validation, ensure your code returns consistent data shapes to avoid breaking API contracts
+
+    Example usage:
+
+    ```typescript
+    // Skip validation for webhook with custom verification
+    export const Route: RouteProps = {
+        path: "/webhook",
+        validation: ValidationMode.SkipValidation,
+    };
+
+    // Validate request but allow flexible response during development
+    export const Route: RouteProps = {
+        path: "/api/debug",
+        validation: ValidationMode.ValidateRequest,
+    };
+    ```
+
+### Patch Changes
+
+-   ee21c29: Normalize query parameters to predictable string types
+
+    Query parameters are now automatically normalized to `string | string[]` types before reaching handlers:
+
+    -   Single values: converted to strings (e.g., `?page=1` → `{ page: "1" }`)
+    -   Repeated parameters: converted to string arrays (e.g., `?tag=a&tag=b` → `{ tag: ["a", "b"] }`)
+    -   All types (numbers, booleans, etc.) from Express parser are converted to strings
+
+    **Breaking Change (Minor):**
+
+    -   `Query` type changed from `{ [x: string]: string | string[] | undefined }` to `Record<string, string | string[]>`
+    -   `Params` type changed from `Request["params"]` to explicit `Record<string, string>`
+    -   Removed `undefined` from query/param types since normalization ensures values are never undefined
+    -   Updated OAuth and OIDC plugin query type definitions to satisfy new Query constraint
+
+    This ensures predictable query and path parameter handling regardless of Express parser configuration. Handlers can reliably parse string values as needed using `Number()`, `parseInt()`, boolean comparisons, etc.
+
 ## 0.14.3
 
 ### Patch Changes

package/dist/src/FlinkApp.js

@@ -62,6 +62,7 @@ var ms_1 = __importDefault(require("ms"));
 var toad_scheduler_1 = require("toad-scheduler");
 var uuid_1 = require("uuid");
 var FlinkErrors_1 = require("./FlinkErrors");
+var FlinkHttpHandler_1 = require("./FlinkHttpHandler");
 var FlinkLog_1 = require("./FlinkLog");
 var mock_data_generator_1 = __importDefault(require("./mock-data-generator"));
 var utils_1 = require("./utils");
@@ -335,24 +336,28 @@ var FlinkApp = /** @class */ (function () {
             }
             var validateReq_1;
             var validateRes_1;
-            if (schema.reqSchema) {
+            // Determine validation mode (default to Validate if not specified)
+            var validationMode = routeProps.validation || FlinkHttpHandler_1.ValidationMode.Validate;
+            // Compile request schema if validation mode requires it
+            if (schema.reqSchema && validationMode !== FlinkHttpHandler_1.ValidationMode.SkipValidation && validationMode !== FlinkHttpHandler_1.ValidationMode.ValidateResponse) {
                 validateReq_1 = ajv.compile(schema.reqSchema);
             }
-            if (schema.resSchema) {
+            // Compile response schema if validation mode requires it
+            if (schema.resSchema && validationMode !== FlinkHttpHandler_1.ValidationMode.SkipValidation && validationMode !== FlinkHttpHandler_1.ValidationMode.ValidateRequest) {
                 validateRes_1 = ajv.compile(schema.resSchema);
             }
             this.expressApp[method](routeProps.path, function (req, res) { return __awaiter(_this, void 0, void 0, function () {
-                var valid, formattedErrors, data, handlerRes, err_1, errorResponse, result, valid, formattedErrors;
-                return __generator(this, function (_a) {
-                    switch (_a.label) {
+                var valid, formattedErrors, data, normalizedQuery, _i, _a, _b, key, value, handlerRes, err_1, errorResponse, result, valid, formattedErrors;
+                return __generator(this, function (_c) {
+                    switch (_c.label) {
                         case 0:
                             if (!routeProps.permissions) return [3 /*break*/, 2];
                             return [4 /*yield*/, this.authenticate(req, routeProps.permissions)];
                         case 1:
-                            if (!(_a.sent())) {
+                            if (!(_c.sent())) {
                                 return [2 /*return*/, res.status(401).json((0, FlinkErrors_1.unauthorized)())];
                             }
-                            _a.label = 2;
+                            _c.label = 2;
                         case 2:
                             if (validateReq_1) {
                                 valid = validateReq_1(req.body);
@@ -378,9 +383,28 @@ var FlinkApp = /** @class */ (function () {
                                 });
                                 return [2 /*return*/];
                             }
-                            _a.label = 3;
+                            // Normalize query parameters to predictable string or string[] types
+                            // Express query parser can produce numbers, booleans, objects, etc.
+                            // We normalize everything to strings or string arrays for consistency
+                            if (req.query && typeof req.query === "object") {
+                                normalizedQuery = {};
+                                for (_i = 0, _a = Object.entries(req.query); _i < _a.length; _i++) {
+                                    _b = _a[_i], key = _b[0], value = _b[1];
+                                    if (Array.isArray(value)) {
+                                        // Handle array values (e.g., ?tag=a&tag=b)
+                                        normalizedQuery[key] = value.map(function (v) { return String(v); });
+                                    }
+                                    else if (value !== undefined && value !== null) {
+                                        // Convert single values to strings
+                                        normalizedQuery[key] = String(value);
+                                    }
+                                    // Skip undefined/null values - they won't appear in the normalized query
+                                }
+                                req.query = normalizedQuery;
+                            }
+                            _c.label = 3;
                         case 3:
-                            _a.trys.push([3, 5, , 6]);
+                            _c.trys.push([3, 5, , 6]);
                             return [4 /*yield*/, handler({
                                     req: req,
                                     ctx: this.ctx,
@@ -388,10 +412,10 @@ var FlinkApp = /** @class */ (function () {
                                 })];
                         case 4:
                             // 👇 This is where the actual handler gets invoked
-                            handlerRes = _a.sent();
+                            handlerRes = _c.sent();
                             return [3 /*break*/, 6];
                         case 5:
-                            err_1 = _a.sent();
+                            err_1 = _c.sent();
                             errorResponse = void 0;
                             // duck typing to check if it is a FlinkError
                             if (typeof err_1.status === "number" && err_1.status >= 400 && err_1.status < 600 && err_1.error) {

package/dist/src/FlinkHttpHandler.d.ts

@@ -10,18 +10,52 @@ export declare enum HttpMethod {
     delete = "delete",
     patch = "patch"
 }
-type Params = Request["params"];
+/**
+ * Validation mode for handler request and response schemas.
+ *
+ * Controls whether request and/or response data is validated against JSON schemas.
+ *
+ * **Security Note:** Skipping validation can introduce security risks. Only use
+ * SkipValidation or ValidateResponse when you have implemented custom validation
+ * or the endpoint is internal/trusted.
+ *
+ * - Validate: Validate both request and response (default behavior)
+ * - SkipValidation: Skip both request and response validation
+ * - ValidateRequest: Validate only request, skip response validation
+ * - ValidateResponse: Validate only response, skip request validation
+ *
+ * @example
+ * ```typescript
+ * // Skip validation for webhook with custom signature verification
+ * export const Route: RouteProps = {
+ *   path: "/webhook",
+ *   validation: ValidationMode.SkipValidation
+ * };
+ *
+ * // Validate request but allow flexible response during development
+ * export const Route: RouteProps = {
+ *   path: "/api/data",
+ *   validation: ValidationMode.ValidateRequest
+ * };
+ * ```
+ */
+export declare enum ValidationMode {
+    Validate = "Validate",
+    SkipValidation = "SkipValidation",
+    ValidateRequest = "ValidateRequest",
+    ValidateResponse = "ValidateResponse"
+}
+type Params = Record<string, string>;
 /**
  * Query type for request query parameters.
- * Does currently not allow nested objects, although
- * underlying express Request does allow it.
  *
- * Uses index signature to allow both Record types and interface types
- * to be assignable to Query without requiring explicit index signatures.
+ * All query parameter values are normalized to strings or string arrays:
+ * - Single values: string (e.g., ?name=John becomes { name: "John" })
+ * - Multiple values: string[] (e.g., ?tag=a&tag=b becomes { tag: ["a", "b"] })
+ *
+ * Does not allow nested objects, although underlying Express Request does allow it.
  */
-type Query = {
-    [x: string]: string | string[] | undefined;
-};
+type Query = Record<string, string | string[]>;
 /**
  * Flink request extends express Request but adds reqId and user object.
  */
@@ -82,6 +116,26 @@ export interface RouteProps {
      * to avoid conflicts you can set a negative order.
      */
     order?: number;
+    /**
+     * Validation mode for request and response schemas.
+     *
+     * Controls schema validation behavior for this handler. Use with caution as
+     * skipping validation can introduce security vulnerabilities.
+     *
+     * **Options:**
+     * - Validate: Validate both request and response (default)
+     * - SkipValidation: Skip both request and response validation
+     * - ValidateRequest: Validate only request, skip response validation
+     * - ValidateResponse: Validate only response, skip request validation
+     *
+     * **When to skip validation:**
+     * - Webhook handlers with custom signature verification
+     * - Performance-critical internal endpoints
+     * - Handlers using alternative validation methods (e.g., Zod, Joi)
+     *
+     * @default ValidationMode.Validate
+     */
+    validation?: ValidationMode;
 }
 /**
  * Http handler function that handlers implements in order to

package/dist/src/FlinkHttpHandler.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HttpMethod = void 0;
+exports.ValidationMode = exports.HttpMethod = void 0;
 var HttpMethod;
 (function (HttpMethod) {
     HttpMethod["get"] = "get";
@@ -9,3 +9,39 @@ var HttpMethod;
     HttpMethod["delete"] = "delete";
     HttpMethod["patch"] = "patch";
 })(HttpMethod || (exports.HttpMethod = HttpMethod = {}));
+/**
+ * Validation mode for handler request and response schemas.
+ *
+ * Controls whether request and/or response data is validated against JSON schemas.
+ *
+ * **Security Note:** Skipping validation can introduce security risks. Only use
+ * SkipValidation or ValidateResponse when you have implemented custom validation
+ * or the endpoint is internal/trusted.
+ *
+ * - Validate: Validate both request and response (default behavior)
+ * - SkipValidation: Skip both request and response validation
+ * - ValidateRequest: Validate only request, skip response validation
+ * - ValidateResponse: Validate only response, skip request validation
+ *
+ * @example
+ * ```typescript
+ * // Skip validation for webhook with custom signature verification
+ * export const Route: RouteProps = {
+ *   path: "/webhook",
+ *   validation: ValidationMode.SkipValidation
+ * };
+ *
+ * // Validate request but allow flexible response during development
+ * export const Route: RouteProps = {
+ *   path: "/api/data",
+ *   validation: ValidationMode.ValidateRequest
+ * };
+ * ```
+ */
+var ValidationMode;
+(function (ValidationMode) {
+    ValidationMode["Validate"] = "Validate";
+    ValidationMode["SkipValidation"] = "SkipValidation";
+    ValidationMode["ValidateRequest"] = "ValidateRequest";
+    ValidationMode["ValidateResponse"] = "ValidateResponse";
+})(ValidationMode || (exports.ValidationMode = ValidationMode = {}));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flink-app/flink",
-  "version": "0.14.3",
+  "version": "1.0.0",
   "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",
@@ -50,7 +50,9 @@
     "@types/mkdirp": "^1.0.1",
     "@types/morgan": "^1.9.4",
     "@types/node": "22.13.10",
+    "@types/supertest": "^6.0.3",
     "mongodb": "^6.15.0",
+    "supertest": "^7.2.2",
     "ts-node": "^10.9.2"
   },
   "peerDependencies": {

package/spec/FlinkApp.query.spec.ts

@@ -0,0 +1,107 @@
+import { FlinkApp } from "../src/FlinkApp";
+import { FlinkContext } from "../src/FlinkContext";
+import { GetHandler, HttpMethod } from "../src/FlinkHttpHandler";
+
+const request = require("supertest");
+
+interface TestContext extends FlinkContext {}
+
+describe("Query parameter normalization", () => {
+    let app: FlinkApp<TestContext>;
+
+    afterEach(async () => {
+        if (app && app.started) {
+            await app.stop();
+        }
+    });
+
+    it("should normalize query params to strings", async () => {
+        const handler: GetHandler<TestContext, any> = async ({ req }) => {
+            return { status: 200, data: { query: req.query } };
+        };
+
+        app = new FlinkApp<TestContext>({ name: "test-query-norm", port: 4000 });
+        await app.start();
+
+        app.addHandler({
+            default: handler,
+            Route: { method: HttpMethod.get, path: "/test" },
+        });
+
+        const response = await request(app.expressApp).get("/test?name=John&age=25");
+
+        expect(response.status).toBe(200);
+        expect(response.body.data.query.name).toBe("John");
+        expect(response.body.data.query.age).toBe("25");
+        expect(typeof response.body.data.query.name).toBe("string");
+        expect(typeof response.body.data.query.age).toBe("string");
+    });
+
+    it("should normalize array query params to string arrays", async () => {
+        const handler: GetHandler<TestContext, any> = async ({ req }) => {
+            return { status: 200, data: { query: req.query } };
+        };
+
+        app = new FlinkApp<TestContext>({ name: "test-query-array", port: 4001 });
+        await app.start();
+
+        app.addHandler({
+            default: handler,
+            Route: { method: HttpMethod.get, path: "/test-array" },
+        });
+
+        const response = await request(app.expressApp).get("/test-array?tag=a&tag=b&tag=c");
+
+        expect(response.status).toBe(200);
+        expect(Array.isArray(response.body.data.query.tag)).toBe(true);
+        expect(response.body.data.query.tag).toEqual(["a", "b", "c"]);
+        response.body.data.query.tag.forEach((tag: string) => {
+            expect(typeof tag).toBe("string");
+        });
+    });
+
+    it("should normalize numeric values to strings", async () => {
+        const handler: GetHandler<TestContext, any> = async ({ req }) => {
+            return { status: 200, data: { query: req.query } };
+        };
+
+        app = new FlinkApp<TestContext>({ name: "test-query-numbers", port: 4002 });
+        await app.start();
+
+        app.addHandler({
+            default: handler,
+            Route: { method: HttpMethod.get, path: "/test-numbers" },
+        });
+
+        const response = await request(app.expressApp).get("/test-numbers?count=100&price=99.99");
+
+        expect(response.status).toBe(200);
+        expect(response.body.data.query.count).toBe("100");
+        expect(response.body.data.query.price).toBe("99.99");
+        expect(typeof response.body.data.query.count).toBe("string");
+        expect(typeof response.body.data.query.price).toBe("string");
+    });
+
+    it("should allow handlers to parse strings as needed", async () => {
+        const handler: GetHandler<TestContext, any> = async ({ req }) => {
+            const page = Number(req.query.page) || 1;
+            const active = req.query.active === "true";
+
+            return { status: 200, data: { page, active } };
+        };
+
+        app = new FlinkApp<TestContext>({ name: "test-query-parsing", port: 4003 });
+        await app.start();
+
+        app.addHandler({
+            default: handler,
+            Route: { method: HttpMethod.get, path: "/test-parsing" },
+        });
+
+        const response = await request(app.expressApp).get("/test-parsing?page=2&active=true");
+
+        expect(response.status).toBe(200);
+        expect(response.body.data.page).toBe(2);
+        expect(response.body.data.active).toBe(true);
+    });
+});

package/spec/FlinkApp.validationMode.spec.ts

@@ -0,0 +1,155 @@
+import { FlinkApp } from "../src/FlinkApp";
+import { FlinkContext } from "../src/FlinkContext";
+import { Handler, RouteProps, ValidationMode } from "../src/FlinkHttpHandler";
+
+interface TestContext extends FlinkContext {}
+
+// Test schemas
+interface ValidRequest {
+    name: string;
+    age: number;
+}
+
+interface ValidResponse {
+    message: string;
+    status: string;
+}
+
+describe("FlinkApp validation modes", () => {
+    let app: FlinkApp<TestContext>;
+
+    beforeEach(async () => {
+        app = new FlinkApp<TestContext>({
+            name: "validation-test-app",
+            debug: false,
+        });
+    });
+
+    afterEach(async () => {
+        if (app && app.started) {
+            await app.stop();
+        }
+    });
+
+    describe("ValidationMode enum", () => {
+        it("should have all validation mode values", () => {
+            expect(ValidationMode.Validate).toBe("Validate");
+            expect(ValidationMode.SkipValidation).toBe("SkipValidation");
+            expect(ValidationMode.ValidateRequest).toBe("ValidateRequest");
+            expect(ValidationMode.ValidateResponse).toBe("ValidateResponse");
+        });
+    });
+
+    describe("RouteProps validation property", () => {
+        it("should accept validation property with ValidationMode.Validate", () => {
+            const route: RouteProps = {
+                path: "/test",
+                validation: ValidationMode.Validate,
+            };
+
+            expect(route.validation).toBe(ValidationMode.Validate);
+        });
+
+        it("should accept validation property with ValidationMode.SkipValidation", () => {
+            const route: RouteProps = {
+                path: "/test",
+                validation: ValidationMode.SkipValidation,
+            };
+
+            expect(route.validation).toBe(ValidationMode.SkipValidation);
+        });
+
+        it("should accept validation property with ValidationMode.ValidateRequest", () => {
+            const route: RouteProps = {
+                path: "/test",
+                validation: ValidationMode.ValidateRequest,
+            };
+
+            expect(route.validation).toBe(ValidationMode.ValidateRequest);
+        });
+
+        it("should accept validation property with ValidationMode.ValidateResponse", () => {
+            const route: RouteProps = {
+                path: "/test",
+                validation: ValidationMode.ValidateResponse,
+            };
+
+            expect(route.validation).toBe(ValidationMode.ValidateResponse);
+        });
+
+        it("should be optional and default to undefined", () => {
+            const route: RouteProps = {
+                path: "/test",
+            };
+
+            expect(route.validation).toBeUndefined();
+        });
+    });
+
+    describe("Handler type compatibility", () => {
+        it("should allow handlers with validation modes to compile", () => {
+            // This test verifies TypeScript compilation
+
+            const handler: Handler<TestContext, ValidRequest, ValidResponse> = async ({ ctx, req }) => {
+                return {
+                    status: 200,
+                    data: {
+                        message: "success",
+                        status: "ok",
+                    },
+                };
+            };
+
+            expect(handler).toBeDefined();
+            expect(typeof handler).toBe("function");
+        });
+
+        it("should allow route props with different validation modes", () => {
+            const routes: RouteProps[] = [
+                { path: "/test1", validation: ValidationMode.Validate },
+                { path: "/test2", validation: ValidationMode.SkipValidation },
+                { path: "/test3", validation: ValidationMode.ValidateRequest },
+                { path: "/test4", validation: ValidationMode.ValidateResponse },
+                { path: "/test5" }, // No validation specified
+            ];
+
+            expect(routes.length).toBe(5);
+            expect(routes[0].validation).toBe(ValidationMode.Validate);
+            expect(routes[1].validation).toBe(ValidationMode.SkipValidation);
+            expect(routes[2].validation).toBe(ValidationMode.ValidateRequest);
+            expect(routes[3].validation).toBe(ValidationMode.ValidateResponse);
+            expect(routes[4].validation).toBeUndefined();
+        });
+    });
+
+    describe("Backward compatibility", () => {
+        it("should not break existing code without validation property", () => {
+            const route: RouteProps = {
+                path: "/legacy",
+                permissions: ["admin"],
+            };
+
+            // TypeScript should compile this without errors
+            expect(route.path).toBe("/legacy");
+            expect(route.validation).toBeUndefined();
+        });
+
+        it("should allow all existing RouteProps properties with validation", () => {
+            const route: RouteProps = {
+                path: "/test",
+                permissions: ["admin", "user"],
+                skipAutoRegister: true,
+                docs: "Test endpoint",
+                order: -1,
+                validation: ValidationMode.SkipValidation,
+            };
+
+            expect(route.path).toBe("/test");
+            expect(route.permissions).toEqual(["admin", "user"]);
+            expect(route.skipAutoRegister).toBe(true);
+            expect(route.docs).toBe("Test endpoint");
+            expect(route.order).toBe(-1);
+            expect(route.validation).toBe(ValidationMode.SkipValidation);
+        });
+    });
+});

package/src/FlinkApp.ts

@@ -12,7 +12,7 @@ import { v4 } from "uuid";
 import { FlinkAuthPlugin } from "./auth/FlinkAuthPlugin";
 import { FlinkContext } from "./FlinkContext";
 import { FlinkError, internalServerError, notFound, unauthorized } from "./FlinkErrors";
-import { FlinkRequest, Handler, HandlerFile, HttpMethod, QueryParamMetadata, RouteProps } from "./FlinkHttpHandler";
+import { FlinkRequest, Handler, HandlerFile, HttpMethod, QueryParamMetadata, RouteProps, ValidationMode } from "./FlinkHttpHandler";
 import { FlinkJobFile } from "./FlinkJob";
 import { log } from "./FlinkLog";
 import { FlinkPlugin } from "./FlinkPlugin";
@@ -535,11 +535,16 @@ export class FlinkApp<C extends FlinkContext> {
             let validateReq: ValidateFunction<any> | undefined;
             let validateRes: ValidateFunction<any> | undefined;
 
-            if (schema.reqSchema) {
+            // Determine validation mode (default to Validate if not specified)
+            const validationMode = routeProps.validation || ValidationMode.Validate;
+
+            // Compile request schema if validation mode requires it
+            if (schema.reqSchema && validationMode !== ValidationMode.SkipValidation && validationMode !== ValidationMode.ValidateResponse) {
                 validateReq = ajv.compile(schema.reqSchema);
             }
 
-            if (schema.resSchema) {
+            // Compile response schema if validation mode requires it
+            if (schema.resSchema && validationMode !== ValidationMode.SkipValidation && validationMode !== ValidationMode.ValidateRequest) {
                 validateRes = ajv.compile(schema.resSchema);
             }
 
@@ -580,6 +585,24 @@ export class FlinkApp<C extends FlinkContext> {
                     return;
                 }
 
+                // Normalize query parameters to predictable string or string[] types
+                // Express query parser can produce numbers, booleans, objects, etc.
+                // We normalize everything to strings or string arrays for consistency
+                if (req.query && typeof req.query === "object") {
+                    const normalizedQuery: Record<string, string | string[]> = {};
+                    for (const [key, value] of Object.entries(req.query)) {
+                        if (Array.isArray(value)) {
+                            // Handle array values (e.g., ?tag=a&tag=b)
+                            normalizedQuery[key] = value.map((v) => String(v));
+                        } else if (value !== undefined && value !== null) {
+                            // Convert single values to strings
+                            normalizedQuery[key] = String(value);
+                        }
+                        // Skip undefined/null values - they won't appear in the normalized query
+                    }
+                    req.query = normalizedQuery;
+                }
+
                 let handlerRes: FlinkResponse<any>;
 
                 try {

package/src/FlinkHttpHandler.ts

@@ -12,19 +12,54 @@ export enum HttpMethod {
     patch = "patch",
 }
 
-type Params = Request["params"];
+/**
+ * Validation mode for handler request and response schemas.
+ *
+ * Controls whether request and/or response data is validated against JSON schemas.
+ *
+ * **Security Note:** Skipping validation can introduce security risks. Only use
+ * SkipValidation or ValidateResponse when you have implemented custom validation
+ * or the endpoint is internal/trusted.
+ *
+ * - Validate: Validate both request and response (default behavior)
+ * - SkipValidation: Skip both request and response validation
+ * - ValidateRequest: Validate only request, skip response validation
+ * - ValidateResponse: Validate only response, skip request validation
+ *
+ * @example
+ * ```typescript
+ * // Skip validation for webhook with custom signature verification
+ * export const Route: RouteProps = {
+ *   path: "/webhook",
+ *   validation: ValidationMode.SkipValidation
+ * };
+ *
+ * // Validate request but allow flexible response during development
+ * export const Route: RouteProps = {
+ *   path: "/api/data",
+ *   validation: ValidationMode.ValidateRequest
+ * };
+ * ```
+ */
+export enum ValidationMode {
+    Validate = "Validate",
+    SkipValidation = "SkipValidation",
+    ValidateRequest = "ValidateRequest",
+    ValidateResponse = "ValidateResponse",
+}
+
+type Params = Record<string, string>;
 
 /**
  * Query type for request query parameters.
- * Does currently not allow nested objects, although
- * underlying express Request does allow it.
  *
- * Uses index signature to allow both Record types and interface types
- * to be assignable to Query without requiring explicit index signatures.
+ * All query parameter values are normalized to strings or string arrays:
+ * - Single values: string (e.g., ?name=John becomes { name: "John" })
+ * - Multiple values: string[] (e.g., ?tag=a&tag=b becomes { tag: ["a", "b"] })
+ *
+ * Does not allow nested objects, although underlying Express Request does allow it.
  */
-type Query = {
-    [x: string]: string | string[] | undefined;
-};
+type Query = Record<string, string | string[]>;
 
 /**
  * Flink request extends express Request but adds reqId and user object.
@@ -91,6 +126,27 @@ export interface RouteProps {
      * to avoid conflicts you can set a negative order.
      */
     order?: number;
+
+    /**
+     * Validation mode for request and response schemas.
+     *
+     * Controls schema validation behavior for this handler. Use with caution as
+     * skipping validation can introduce security vulnerabilities.
+     *
+     * **Options:**
+     * - Validate: Validate both request and response (default)
+     * - SkipValidation: Skip both request and response validation
+     * - ValidateRequest: Validate only request, skip response validation
+     * - ValidateResponse: Validate only response, skip request validation
+     *
+     * **When to skip validation:**
+     * - Webhook handlers with custom signature verification
+     * - Performance-critical internal endpoints
+     * - Handlers using alternative validation methods (e.g., Zod, Joi)
+     *
+     * @default ValidationMode.Validate
+     */
+    validation?: ValidationMode;
 }
 
 /**