@flink-app/flink 0.14.2 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,72 @@
 # @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
+
+-   52eba74: Fix Query type constraint to allow user-defined interfaces without explicit index signatures. The Query type now uses explicit index signature syntax, making it easier for developers to define query parameter interfaces for their handlers without TypeScript compilation errors.
+-   b37faa5: Improve schema validation error messages to show specific additional property names. When validation fails due to additional properties, the error now displays which properties are not allowed instead of a generic message.
+
 ## 0.14.2
 
 ### 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);
@@ -364,7 +369,7 @@ var FlinkApp = /** @class */ (function () {
                                             error: {
                                                 id: (0, uuid_1.v4)(),
                                                 title: "Bad request",
-                                                detail: "Schema did not validate ".concat(JSON.stringify(validateReq_1.errors)),
+                                                detail: formattedErrors,
                                             },
                                         })];
                                 }
@@ -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) {
@@ -442,7 +466,7 @@ var FlinkApp = /** @class */ (function () {
                                             error: {
                                                 id: (0, uuid_1.v4)(),
                                                 title: "Bad response",
-                                                detail: "Schema did not validate ".concat(JSON.stringify(validateRes_1.errors)),
+                                                detail: formattedErrors,
                                             },
                                         })];
                                 }

package/dist/src/FlinkHttpHandler.d.ts

@@ -10,13 +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.
+ *
+ * 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 = Record<string, string | string[] | undefined>;
+type Query = Record<string, string | string[]>;
 /**
  * Flink request extends express Request but adds reqId and user object.
  */
@@ -77,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/dist/src/utils.js

@@ -223,6 +223,9 @@ function formatValidationErrors(errors, data, maxDataLength) {
             else if (error.keyword === "type") {
                 formatted.push("  - Invalid type at ".concat(error.schemaPath, ": expected ").concat(error.params.type, ", got ").concat(typeof dataAtPath));
             }
+            else if (error.keyword === "additionalProperties") {
+                formatted.push("  - Additional property not allowed: ".concat(error.params.additionalProperty));
+            }
             else if (error.keyword === "anyOf" || error.keyword === "oneOf") {
                 formatted.push("  - ".concat(error.message));
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flink-app/flink",
-  "version": "0.14.2",
+  "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/spec/utils.spec.ts

@@ -148,6 +148,33 @@ describe("Utils", () => {
             expect(formatted).toContain('Missing required property: email');
             expect(formatted).toContain('Missing required property: age');
         });
+
+        it("should show specific additional property names", () => {
+            const errors = [
+                {
+                    instancePath: "",
+                    schemaPath: "#/additionalProperties",
+                    keyword: "additionalProperties",
+                    params: { additionalProperty: "extraField1" },
+                    message: "must NOT have additional properties",
+                },
+                {
+                    instancePath: "",
+                    schemaPath: "#/additionalProperties",
+                    keyword: "additionalProperties",
+                    params: { additionalProperty: "extraField2" },
+                    message: "must NOT have additional properties",
+                },
+            ];
+            const data = { name: "John", age: 30, extraField1: "value1", extraField2: "value2" };
+
+            const formatted = formatValidationErrors(errors, data);
+
+            // This formatted output is used in HTTP error responses (400/500) in the error.detail field
+            expect(formatted).toContain('Path: /');
+            expect(formatted).toContain('Additional property not allowed: extraField1');
+            expect(formatted).toContain('Additional property not allowed: extraField2');
+        });
     });
 });
 

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);
             }
 
@@ -562,7 +567,7 @@ export class FlinkApp<C extends FlinkContext> {
                             error: {
                                 id: v4(),
                                 title: "Bad request",
-                                detail: `Schema did not validate ${JSON.stringify(validateReq.errors)}`,
+                                detail: formattedErrors,
                             },
                         });
                     }
@@ -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 {
@@ -645,7 +668,7 @@ export class FlinkApp<C extends FlinkContext> {
                             error: {
                                 id: v4(),
                                 title: "Bad response",
-                                detail: `Schema did not validate ${JSON.stringify(validateRes.errors)}`,
+                                detail: formattedErrors,
                             },
                         });
                     }

package/src/FlinkHttpHandler.ts

@@ -12,14 +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.
+ *
+ * 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 = Record<string, string | string[] | undefined>;
+type Query = Record<string, string | string[]>;
 
 /**
  * Flink request extends express Request but adds reqId and user object.
@@ -86,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;
 }
 
 /**

package/src/utils.ts

@@ -165,6 +165,8 @@ export function formatValidationErrors(errors: any[] | null | undefined, data: a
                 formatted.push(`  - Missing required property: ${error.params.missingProperty}`);
             } else if (error.keyword === "type") {
                 formatted.push(`  - Invalid type at ${error.schemaPath}: expected ${error.params.type}, got ${typeof dataAtPath}`);
+            } else if (error.keyword === "additionalProperties") {
+                formatted.push(`  - Additional property not allowed: ${error.params.additionalProperty}`);
             } else if (error.keyword === "anyOf" || error.keyword === "oneOf") {
                 formatted.push(`  - ${error.message}`);
             } else {