mcp4openapi 0.2.8 → 0.3.1

package/dist/src/validation/argument-normalizer.js

@@ -0,0 +1,70 @@
+export function normalizeArguments(toolDef, args) {
+    const normalized = { ...args };
+    for (const [paramName, paramDef] of Object.entries(toolDef.parameters)) {
+        const value = normalized[paramName];
+        if (value === undefined) {
+            continue;
+        }
+        const mappedEntries = normalizeObjectEntries(paramDef, value);
+        if (mappedEntries !== undefined) {
+            normalized[paramName] = mappedEntries;
+            continue;
+        }
+        const mappedArrayItems = normalizeArrayItems(paramDef, value);
+        if (mappedArrayItems !== undefined) {
+            normalized[paramName] = mappedArrayItems;
+        }
+    }
+    return normalized;
+}
+export function applyParameterDefaults(toolDef, args) {
+    const normalized = { ...args };
+    for (const [paramName, paramDef] of Object.entries(toolDef.parameters)) {
+        if (normalized[paramName] === undefined && paramDef.default !== undefined) {
+            normalized[paramName] = paramDef.default;
+        }
+    }
+    return normalized;
+}
+function normalizeObjectEntries(paramDef, value) {
+    if (!paramDef.object_entries_to_array) {
+        return undefined;
+    }
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return undefined;
+    }
+    const { key_field, value_field, wrap_value_field } = paramDef.object_entries_to_array;
+    const entries = Object.entries(value);
+    return entries.map(([key, entryValue]) => ({
+        [key_field]: key,
+        [value_field]: wrapObjectValue(entryValue, wrap_value_field),
+    }));
+}
+function wrapObjectValue(value, wrapValueField) {
+    if (!wrapValueField) {
+        return value;
+    }
+    if (typeof value === 'object' && value !== null) {
+        return value;
+    }
+    return { [wrapValueField]: value };
+}
+function normalizeArrayItems(paramDef, value) {
+    if (!paramDef.array_item_to_object) {
+        return undefined;
+    }
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    const { key_field } = paramDef.array_item_to_object;
+    return value.map(item => {
+        if (typeof item === 'object' && item !== null && !Array.isArray(item)) {
+            return item;
+        }
+        if (['string', 'number', 'boolean'].includes(typeof item)) {
+            return { [key_field]: item };
+        }
+        return item;
+    });
+}
+//# sourceMappingURL=argument-normalizer.js.map

package/dist/src/validation/argument-normalizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"argument-normalizer.js","sourceRoot":"","sources":["../../../src/validation/argument-normalizer.ts"],"names":[],"mappings":"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"}

package/dist/src/validation/jsonrpc-validator.d.ts

@@ -0,0 +1,27 @@
+/**
+ * JSON-RPC message validation utilities
+ *
+ * Why: Eliminates code duplication between http-transport.ts and mcp-server.ts
+ * These functions validate JSON-RPC 2.0 message types used in MCP protocol.
+ */
+/**
+ * Check if message is an initialize request
+ */
+export declare function isInitializeRequest(message: unknown): boolean;
+/**
+ * Check if message is a tool call request
+ */
+export declare function isToolCallRequest(message: unknown): boolean;
+/**
+ * Check if message is a tools/list request
+ */
+export declare function isToolsListRequest(message: unknown): boolean;
+/**
+ * Check if message is a valid JSON-RPC request object
+ */
+export declare function isJsonRpcRequest(message: unknown): boolean;
+/**
+ * Check if message is a valid JSON-RPC response object
+ */
+export declare function isJsonRpcResponse(message: unknown): boolean;
+//# sourceMappingURL=jsonrpc-validator.d.ts.map

package/dist/src/validation/jsonrpc-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonrpc-validator.d.ts","sourceRoot":"","sources":["../../../src/validation/jsonrpc-validator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAI7D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAI3D;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAI5D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAS1D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAS3D"}

package/dist/src/validation/jsonrpc-validator.js

@@ -0,0 +1,58 @@
+/**
+ * JSON-RPC message validation utilities
+ *
+ * Why: Eliminates code duplication between http-transport.ts and mcp-server.ts
+ * These functions validate JSON-RPC 2.0 message types used in MCP protocol.
+ */
+/**
+ * Check if message is an initialize request
+ */
+export function isInitializeRequest(message) {
+    if (typeof message !== 'object' || message === null)
+        return false;
+    const req = message;
+    return req.method === 'initialize';
+}
+/**
+ * Check if message is a tool call request
+ */
+export function isToolCallRequest(message) {
+    if (typeof message !== 'object' || message === null)
+        return false;
+    const req = message;
+    return req.method === 'tools/call';
+}
+/**
+ * Check if message is a tools/list request
+ */
+export function isToolsListRequest(message) {
+    if (typeof message !== 'object' || message === null)
+        return false;
+    const req = message;
+    return req.method === 'tools/list';
+}
+/**
+ * Check if message is a valid JSON-RPC request object
+ */
+export function isJsonRpcRequest(message) {
+    if (typeof message !== 'object' || message === null)
+        return false;
+    const req = message;
+    return (typeof req.jsonrpc === 'string' &&
+        req.jsonrpc === '2.0' &&
+        typeof req.method === 'string' &&
+        'id' in req);
+}
+/**
+ * Check if message is a valid JSON-RPC response object
+ */
+export function isJsonRpcResponse(message) {
+    if (typeof message !== 'object' || message === null)
+        return false;
+    const resp = message;
+    return (typeof resp.jsonrpc === 'string' &&
+        resp.jsonrpc === '2.0' &&
+        'id' in resp &&
+        ('result' in resp || 'error' in resp));
+}
+//# sourceMappingURL=jsonrpc-validator.js.map

package/dist/src/validation/jsonrpc-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonrpc-validator.js","sourceRoot":"","sources":["../../../src/validation/jsonrpc-validator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAgB;IAClD,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAClE,MAAM,GAAG,GAAG,OAAkC,CAAC;IAC/C,OAAO,GAAG,CAAC,MAAM,KAAK,YAAY,CAAC;AACrC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAgB;IAChD,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAClE,MAAM,GAAG,GAAG,OAAkC,CAAC;IAC/C,OAAO,GAAG,CAAC,MAAM,KAAK,YAAY,CAAC;AACrC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAgB;IACjD,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAClE,MAAM,GAAG,GAAG,OAAkC,CAAC;IAC/C,OAAO,GAAG,CAAC,MAAM,KAAK,YAAY,CAAC;AACrC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAgB;IAC/C,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAClE,MAAM,GAAG,GAAG,OAAkC,CAAC;IAC/C,OAAO,CACL,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ;QAC/B,GAAG,CAAC,OAAO,KAAK,KAAK;QACrB,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ;QAC9B,IAAI,IAAI,GAAG,CACZ,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAgB;IAChD,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAClE,MAAM,IAAI,GAAG,OAAkC,CAAC;IAChD,OAAO,CACL,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ;QAChC,IAAI,CAAC,OAAO,KAAK,KAAK;QACtB,IAAI,IAAI,IAAI;QACZ,CAAC,QAAQ,IAAI,IAAI,IAAI,OAAO,IAAI,IAAI,CAAC,CACtC,CAAC;AACJ,CAAC"}

package/dist/src/validation/schema-validator.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Request body schema validator
+ *
+ * Why: Catch invalid requests before sending to API. Better error messages for users.
+ * Validates against OpenAPI schema definitions.
+ */
+import type { SchemaInfo, OperationInfo } from '../types/openapi.js';
+export interface ValidationResult {
+    valid: boolean;
+    errors?: ValidationError[];
+}
+export interface ValidationError {
+    path: string;
+    message: string;
+    schema: SchemaInfo;
+    value: unknown;
+}
+export declare class SchemaValidator {
+    /**
+     * Validate request body against OpenAPI schema
+     *
+     * Why: Prevents sending malformed requests. OpenAPI schema is the source of truth.
+     */
+    validateRequestBody(operation: OperationInfo, body: unknown): ValidationResult;
+    /**
+     * Recursively validate data against schema
+     */
+    private validateAgainstSchema;
+}
+//# sourceMappingURL=schema-validator.d.ts.map

package/dist/src/validation/schema-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-validator.d.ts","sourceRoot":"","sources":["../../../src/validation/schema-validator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGrE,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,eAAe,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,UAAU,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,qBAAa,eAAe;IAC1B;;;;OAIG;IACH,mBAAmB,CACjB,SAAS,EAAE,aAAa,EACxB,IAAI,EAAE,OAAO,GACZ,gBAAgB;IAgBnB;;OAEG;IACH,OAAO,CAAC,qBAAqB;CA2H9B"}

package/dist/src/validation/schema-validator.js

@@ -0,0 +1,128 @@
+/**
+ * Request body schema validator
+ *
+ * Why: Catch invalid requests before sending to API. Better error messages for users.
+ * Validates against OpenAPI schema definitions.
+ */
+import { isEmail, isUri } from './validation-utils.js';
+export class SchemaValidator {
+    /**
+     * Validate request body against OpenAPI schema
+     *
+     * Why: Prevents sending malformed requests. OpenAPI schema is the source of truth.
+     */
+    validateRequestBody(operation, body) {
+        if (!operation.requestBody?.content['application/json']?.schema) {
+            return { valid: true };
+        }
+        const schema = operation.requestBody.content['application/json'].schema;
+        const errors = [];
+        this.validateAgainstSchema(body, schema, '', errors);
+        return {
+            valid: errors.length === 0,
+            errors: errors.length > 0 ? errors : undefined,
+        };
+    }
+    /**
+     * Recursively validate data against schema
+     */
+    validateAgainstSchema(data, schema, path, errors) {
+        // Null/undefined handling
+        if (data === null || data === undefined) {
+            if (schema.type && schema.type !== 'null') {
+                errors.push({
+                    path: path || '(root)',
+                    message: `Expected ${schema.type}, got ${data}`,
+                    schema,
+                    value: data,
+                });
+            }
+            return;
+        }
+        // Type validation
+        if (schema.type) {
+            const actualType = Array.isArray(data) ? 'array' : typeof data;
+            // OpenAPI 'integer' is a subtype of 'number' with format constraint
+            const expectedType = schema.type === 'integer' ? 'number' : schema.type;
+            if (actualType !== expectedType) {
+                errors.push({
+                    path: path || '(root)',
+                    message: `Expected ${schema.type}, got ${actualType}`,
+                    schema,
+                    value: data,
+                });
+                return; // Stop validation if type is wrong
+            }
+            // Additional integer validation: check it's actually an integer
+            if (schema.type === 'integer' && typeof data === 'number') {
+                if (!Number.isInteger(data)) {
+                    errors.push({
+                        path: path || '(root)',
+                        message: `Expected integer, got number`,
+                        schema,
+                        value: data,
+                    });
+                }
+            }
+        }
+        // Enum validation
+        // Note: Using 'as any' here is safe - we're checking if value exists in enum array
+        // TypeScript doesn't know the enum values at compile time
+        if (schema.enum && !schema.enum.includes(data)) {
+            errors.push({
+                path: path || '(root)',
+                message: `Value must be one of: ${schema.enum.join(', ')}`,
+                schema,
+                value: data,
+            });
+        }
+        // Object properties validation
+        if (schema.type === 'object' && schema.properties) {
+            const obj = data;
+            // Check required properties
+            for (const required of schema.required || []) {
+                if (obj[required] === undefined) {
+                    errors.push({
+                        path: path ? `${path}.${required}` : required,
+                        message: 'Required property is missing',
+                        schema,
+                        value: undefined,
+                    });
+                }
+            }
+            // Validate each property
+            for (const [key, value] of Object.entries(obj)) {
+                if (schema.properties[key]) {
+                    this.validateAgainstSchema(value, schema.properties[key], path ? `${path}.${key}` : key, errors);
+                }
+                // Note: Not validating additionalProperties (too strict for most APIs)
+            }
+        }
+        // Array items validation
+        if (schema.type === 'array' && schema.items && Array.isArray(data)) {
+            data.forEach((item, index) => {
+                this.validateAgainstSchema(item, schema.items, `${path}[${index}]`, errors);
+            });
+        }
+        // String format validation (basic)
+        if (schema.type === 'string' && schema.format && typeof data === 'string') {
+            if (schema.format === 'email' && !isEmail(data)) {
+                errors.push({
+                    path: path || '(root)',
+                    message: 'Invalid email format',
+                    schema,
+                    value: data,
+                });
+            }
+            if (schema.format === 'uri' && !isUri(data)) {
+                errors.push({
+                    path: path || '(root)',
+                    message: 'Invalid URI format',
+                    schema,
+                    value: data,
+                });
+            }
+        }
+    }
+}
+//# sourceMappingURL=schema-validator.js.map

package/dist/src/validation/schema-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-validator.js","sourceRoot":"","sources":["../../../src/validation/schema-validator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAcvD,MAAM,OAAO,eAAe;IAC1B;;;;OAIG;IACH,mBAAmB,CACjB,SAAwB,EACxB,IAAa;QAEb,IAAI,CAAC,SAAS,CAAC,WAAW,EAAE,OAAO,CAAC,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;YAChE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;QACzB,CAAC;QAED,MAAM,MAAM,GAAG,SAAS,CAAC,WAAW,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC,MAAM,CAAC;QACxE,MAAM,MAAM,GAAsB,EAAE,CAAC;QAErC,IAAI,CAAC,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC;QAErD,OAAO;YACL,KAAK,EAAE,MAAM,CAAC,MAAM,KAAK,CAAC;YAC1B,MAAM,EAAE,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS;SAC/C,CAAC;IACJ,CAAC;IAED;;OAEG;IACK,qBAAqB,CAC3B,IAAa,EACb,MAAkB,EAClB,IAAY,EACZ,MAAyB;QAEzB,0BAA0B;QAC1B,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACxC,IAAI,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;gBAC1C,MAAM,CAAC,IAAI,CAAC;oBACV,IAAI,EAAE,IAAI,IAAI,QAAQ;oBACtB,OAAO,EAAE,YAAY,MAAM,CAAC,IAAI,SAAS,IAAI,EAAE;oBAC/C,MAAM;oBACN,KAAK,EAAE,IAAI;iBACZ,CAAC,CAAC;YACL,CAAC;YACD,OAAO;QACT,CAAC;QAED,kBAAkB;QAClB,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;YAChB,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,IAAI,CAAC;YAC/D,oEAAoE;YACpE,MAAM,YAAY,GAAG,MAAM,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC;YAExE,IAAI,UAAU,KAAK,YAAY,EAAE,CAAC;gBAChC,MAAM,CAAC,IAAI,CAAC;oBACV,IAAI,EAAE,IAAI,IAAI,QAAQ;oBACtB,OAAO,EAAE,YAAY,MAAM,CAAC,IAAI,SAAS,UAAU,EAAE;oBACrD,MAAM;oBACN,KAAK,EAAE,IAAI;iBACZ,CAAC,CAAC;gBACH,OAAO,CAAC,mCAAmC;YAC7C,CAAC;YAED,gEAAgE;YAChE,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAC1D,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;oBAC5B,MAAM,CAAC,IAAI,CAAC;wBACV,IAAI,EAAE,IAAI,IAAI,QAAQ;wBACtB,OAAO,EAAE,8BAA8B;wBACvC,MAAM;wBACN,KAAK,EAAE,IAAI;qBACZ,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;QACH,CAAC;QAED,kBAAkB;QAClB,mFAAmF;QACnF,0DAA0D;QAC1D,IAAI,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAW,CAAC,EAAE,CAAC;YACtD,MAAM,CAAC,IAAI,CAAC;gBACV,IAAI,EAAE,IAAI,IAAI,QAAQ;gBACtB,OAAO,EAAE,yBAAyB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;gBAC1D,MAAM;gBACN,KAAK,EAAE,IAAI;aACZ,CAAC,CAAC;QACL,CAAC;QAED,+BAA+B;QAC/B,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;YAClD,MAAM,GAAG,GAAG,IAA+B,CAAC;YAE5C,4BAA4B;YAC5B,KAAK,MAAM,QAAQ,IAAI,MAAM,CAAC,QAAQ,IAAI,EAAE,EAAE,CAAC;gBAC7C,IAAI,GAAG,CAAC,QAAQ,CAAC,KAAK,SAAS,EAAE,CAAC;oBAChC,MAAM,CAAC,IAAI,CAAC;wBACV,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,QAAQ,EAAE,CAAC,CAAC,CAAC,QAAQ;wBAC7C,OAAO,EAAE,8BAA8B;wBACvC,MAAM;wBACN,KAAK,EAAE,SAAS;qBACjB,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;YAED,yBAAyB;YACzB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC/C,IAAI,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;oBAC3B,IAAI,CAAC,qBAAqB,CACxB,KAAK,EACL,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,EACtB,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,EAC7B,MAAM,CACP,CAAC;gBACJ,CAAC;gBACD,uEAAuE;YACzE,CAAC;QACH,CAAC;QAED,yBAAyB;QACzB,IAAI,MAAM,CAAC,IAAI,KAAK,OAAO,IAAI,MAAM,CAAC,KAAK,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YACnE,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;gBAC3B,IAAI,CAAC,qBAAqB,CACxB,IAAI,EACJ,MAAM,CAAC,KAAM,EACb,GAAG,IAAI,IAAI,KAAK,GAAG,EACnB,MAAM,CACP,CAAC;YACJ,CAAC,CAAC,CAAC;QACL,CAAC;QAED,mCAAmC;QACnC,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,IAAI,MAAM,CAAC,MAAM,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC1E,IAAI,MAAM,CAAC,MAAM,KAAK,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;gBAChD,MAAM,CAAC,IAAI,CAAC;oBACV,IAAI,EAAE,IAAI,IAAI,QAAQ;oBACtB,OAAO,EAAE,sBAAsB;oBAC/B,MAAM;oBACN,KAAK,EAAE,IAAI;iBACZ,CAAC,CAAC;YACL,CAAC;YACD,IAAI,MAAM,CAAC,MAAM,KAAK,KAAK,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC5C,MAAM,CAAC,IAAI,CAAC;oBACV,IAAI,EAAE,IAAI,IAAI,QAAQ;oBACtB,OAAO,EAAE,oBAAoB;oBAC7B,MAAM;oBACN,KAAK,EAAE,IAAI;iBACZ,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;CAEF"}

package/dist/src/validation/validation-utils.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Validation utilities for common data types
+ *
+ * Why: Provides reusable validation functions for email, URI, and other formats
+ * Centralizes validation logic and ensures consistency across the application
+ */
+/**
+ * Validates that a property name is safe to use as dynamic object key.
+ * Prevents prototype pollution attacks.
+ */
+export declare function isSafePropertyName(name: string): boolean;
+/**
+ * Escape special regex characters in a string.
+ * Prevents ReDoS attacks when using dynamic strings in RegExp.
+ */
+export declare function escapeRegExp(str: string): string;
+/**
+ * Redact specific header from headers object (case-insensitive)
+ */
+export declare function redactHeader(headers: unknown, headerName: string): Record<string, unknown>;
+/**
+ * Redact query parameter from URL string
+ */
+export declare function redactQueryParam(url: string | undefined, paramName: string): string;
+/**
+ * Redact parameter from params object
+ */
+export declare function redactParam(params: unknown, paramName: string): Record<string, unknown>;
+/**
+ * Validates if a string is a valid email address
+ */
+export declare function isEmail(value: string): boolean;
+/**
+ * Validates if a string is a valid URI
+ */
+export declare function isUri(value: string): boolean;
+/**
+ * Escape HTML special characters to prevent XSS attacks
+ *
+ * Why: User-provided strings in error messages must be sanitized
+ * before being returned in JSON responses that might be rendered as HTML.
+ *
+ * Uses escape-html library for reliable HTML entity escaping.
+ *
+ * @param str - String to escape (can be undefined or null)
+ * @returns Escaped string safe for HTML rendering, empty string if input is falsy
+ */
+export declare function escapeHtmlSafe(str: string | undefined | null): string;
+//# sourceMappingURL=validation-utils.d.ts.map

package/dist/src/validation/validation-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation-utils.d.ts","sourceRoot":"","sources":["../../../src/validation/validation-utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAqBH;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAExD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,OAAO,EAChB,UAAU,EAAE,MAAM,GACjB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAYzB;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,SAAS,EAAE,MAAM,GAChB,MAAM,CAiCR;AAED;;GAEG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,OAAO,EACf,SAAS,EAAE,MAAM,GAChB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CASzB;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAG9C;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAO5C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CAGrE"}

package/dist/src/validation/validation-utils.js

@@ -0,0 +1,139 @@
+/**
+ * Validation utilities for common data types
+ *
+ * Why: Provides reusable validation functions for email, URI, and other formats
+ * Centralizes validation logic and ensures consistency across the application
+ */
+import escapeHtml from 'escape-html';
+/** Property names that must never be used as dynamic object keys */
+const FORBIDDEN_PROPERTY_NAMES = new Set([
+    '__proto__',
+    'constructor',
+    'prototype',
+    '__defineGetter__',
+    '__defineSetter__',
+    '__lookupGetter__',
+    '__lookupSetter__',
+    'hasOwnProperty',
+    'isPrototypeOf',
+    'propertyIsEnumerable',
+    'toLocaleString',
+    'toString',
+    'valueOf',
+]);
+/**
+ * Validates that a property name is safe to use as dynamic object key.
+ * Prevents prototype pollution attacks.
+ */
+export function isSafePropertyName(name) {
+    return !FORBIDDEN_PROPERTY_NAMES.has(name);
+}
+/**
+ * Escape special regex characters in a string.
+ * Prevents ReDoS attacks when using dynamic strings in RegExp.
+ */
+export function escapeRegExp(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Redact specific header from headers object (case-insensitive)
+ */
+export function redactHeader(headers, headerName) {
+    if (!headers || typeof headers !== 'object')
+        return {};
+    const redacted = { ...headers };
+    for (const key of Object.keys(redacted)) {
+        if (key.toLowerCase() === headerName.toLowerCase()) {
+            redacted[key] = '[REDACTED]';
+        }
+    }
+    return redacted;
+}
+/**
+ * Redact query parameter from URL string
+ */
+export function redactQueryParam(url, paramName) {
+    if (!url)
+        return '';
+    // Enforce safe paramName (alphanumeric, underscore, dash) length <= 64
+    if (!/^[A-Za-z0-9_-]{1,64}$/.test(paramName)) {
+        return url; // Unsafe param name; return original unmodified
+    }
+    try {
+        const urlObj = new URL(url);
+        if (urlObj.searchParams.has(paramName)) {
+            urlObj.searchParams.set(paramName, '[REDACTED]');
+        }
+        return urlObj.toString();
+    }
+    catch {
+        // Fallback: manual parsing without dynamic RegExp to avoid ReDoS concerns
+        // Split on '?' then process query string key-value pairs
+        const qIndex = url.indexOf('?');
+        if (qIndex === -1)
+            return url;
+        const base = url.substring(0, qIndex);
+        const query = url.substring(qIndex + 1);
+        const parts = query.split('&');
+        const redactedParts = parts.map(part => {
+            const eqIndex = part.indexOf('=');
+            if (eqIndex === -1)
+                return part; // skip malformed segment
+            const key = part.substring(0, eqIndex);
+            if (key === paramName) {
+                // Encode [REDACTED] for consistency with URLSearchParams behavior
+                return key + '=%5BREDACTED%5D';
+            }
+            return part;
+        });
+        return base + '?' + redactedParts.join('&');
+    }
+}
+/**
+ * Redact parameter from params object
+ */
+export function redactParam(params, paramName) {
+    if (!params || typeof params !== 'object')
+        return {};
+    const redacted = { ...params };
+    if (paramName in redacted) {
+        redacted[paramName] = '[REDACTED]';
+    }
+    return redacted;
+}
+/**
+ * Validates if a string is a valid email address
+ */
+export function isEmail(value) {
+    // codeql[js/polynomial-redos] Simple validation; not intended to fully validate RFC emails.
+    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
+}
+/**
+ * Validates if a string is a valid URI
+ */
+export function isUri(value) {
+    try {
+        new URL(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Escape HTML special characters to prevent XSS attacks
+ *
+ * Why: User-provided strings in error messages must be sanitized
+ * before being returned in JSON responses that might be rendered as HTML.
+ *
+ * Uses escape-html library for reliable HTML entity escaping.
+ *
+ * @param str - String to escape (can be undefined or null)
+ * @returns Escaped string safe for HTML rendering, empty string if input is falsy
+ */
+export function escapeHtmlSafe(str) {
+    if (!str)
+        return '';
+    return escapeHtml(String(str));
+}
+//# sourceMappingURL=validation-utils.js.map

package/dist/src/validation/validation-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation-utils.js","sourceRoot":"","sources":["../../../src/validation/validation-utils.ts"],"names":[],"mappings":"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"}