alepha 0.15.0 → 0.15.1

package/src/core/providers/KeylessJsonSchemaCodec.ts

@@ -1,4 +1,6 @@
 import type { TArray, TObject, TSchema, TUnion } from "typebox";
+import { AlephaError } from "../errors/AlephaError.ts";
+import { $hook } from "../primitives/$hook.ts";
 import { SchemaCodec } from "./SchemaCodec.ts";
 import { type Static, t } from "./TypeProvider.ts";
 
@@ -16,28 +18,99 @@ import { type Static, t } from "./TypeProvider.ts";
 //   Keyless: ["Alice",30,true]                        (17 bytes)
 // =============================================================================
 
+// Security: Keys that could enable prototype pollution attacks
+const UNSAFE_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
 export interface KeylessCodec<T = any> {
   encode: (value: T) => string;
   decode: (str: string) => T;
 }
 
+export interface KeylessCodecOptions {
+  /**
+   * Whether to use `new Function()` for code compilation.
+   * When false, uses an interpreter-based approach (safer but slower).
+   *
+   * @default Auto-detected: false in browser (CSP compatibility), true on server
+   */
+  useFunctionCompilation?: boolean;
+
+  /**
+   * Maximum allowed array length during encoding/decoding.
+   * Prevents DoS attacks via large arrays.
+   *
+   * @default 10000
+   */
+  maxArrayLength?: number;
+
+  /**
+   * Maximum allowed string length during encoding/decoding.
+   * Prevents DoS attacks via large strings.
+   *
+   * @default 1000000 (1MB)
+   */
+  maxStringLength?: number;
+
+  /**
+   * Maximum recursion depth for nested objects.
+   * Prevents stack overflow attacks.
+   *
+   * @default 50
+   */
+  maxDepth?: number;
+}
+
 /**
  * KeylessJsonSchemaCodec provides schema-driven JSON encoding without keys.
  *
  * It uses the schema to determine field order, allowing the encoded output
  * to be a simple JSON array instead of an object with keys.
- *
- * Performance characteristics:
- * - Encode: 0.94-1.53x vs JSON.stringify (faster for complex objects)
- * - Decode: 1.76-2.00x vs JSON.parse
- * - Size: 50-56% smaller than JSON
  */
 export class KeylessJsonSchemaCodec extends SchemaCodec {
   protected readonly cache = new Map<TSchema, KeylessCodec>();
-  protected readonly encoder = new TextEncoder();
-  protected readonly decoder = new TextDecoder();
+  protected readonly textEncoder = new TextEncoder();
+  protected readonly textDecoder = new TextDecoder();
   protected varCounter = 0;
 
+  // Options with defaults
+  protected useFunctionCompilation = true;
+  protected maxArrayLength = 10000;
+  protected maxStringLength = 1000000;
+  protected maxDepth = 50;
+
+  /**
+   * Configure codec options.
+   */
+  public configure(options: KeylessCodecOptions): this {
+    if (options.useFunctionCompilation !== undefined) {
+      this.useFunctionCompilation = options.useFunctionCompilation;
+      this.cache.clear(); // Clear cache when compilation mode changes
+    }
+    if (options.maxArrayLength !== undefined) {
+      this.maxArrayLength = options.maxArrayLength;
+    }
+    if (options.maxStringLength !== undefined) {
+      this.maxStringLength = options.maxStringLength;
+    }
+    if (options.maxDepth !== undefined) {
+      this.maxDepth = options.maxDepth;
+    }
+    return this;
+  }
+
+  /**
+   * Hook to auto-detect safe mode on configure.
+   * Disables function compilation in browser by default.
+   */
+  protected onConfigure = $hook({
+    on: "configure",
+    handler: () => {
+      // Auto-detect: disable function compilation in browser (CSP compatibility)
+      // and test if eval/Function is available
+      this.useFunctionCompilation = this.canUseFunction();
+    },
+  });
+
   /**
    * Encode value to a keyless JSON string.
    */
@@ -55,7 +128,7 @@ export class KeylessJsonSchemaCodec extends SchemaCodec {
     schema: T,
     value: Static<T>,
   ): Uint8Array {
-    return this.encoder.encode(this.encodeToString(schema, value));
+    return this.textEncoder.encode(this.encodeToString(schema, value));
   }
 
   /**
@@ -63,7 +136,7 @@ export class KeylessJsonSchemaCodec extends SchemaCodec {
    */
   public decode<T>(schema: TSchema, value: unknown): T {
     if (value instanceof Uint8Array) {
-      const text = this.decoder.decode(value);
+      const text = this.textDecoder.decode(value);
       return this.getCodec(schema).decode(text) as T;
     }
 
@@ -79,6 +152,88 @@ export class KeylessJsonSchemaCodec extends SchemaCodec {
     return value as T;
   }
 
+  // ===========================================================================
+  // Security Validation
+  // ===========================================================================
+
+  /**
+   * Test if `new Function()` is available (not blocked by CSP).
+   */
+  protected canUseFunction(): boolean {
+    try {
+      const fn = new Function("return true");
+      return fn() === true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Validate schema keys for prototype pollution.
+   * Uses a visited set to avoid infinite recursion on recursive schemas.
+   */
+  protected validateSchemaKeys(
+    schema: TSchema,
+    depth = 0,
+    visited = new Set<TSchema>(),
+  ): void {
+    // Avoid infinite recursion on recursive schemas
+    if (visited.has(schema)) {
+      return;
+    }
+    visited.add(schema);
+
+    if (depth > this.maxDepth) {
+      throw new AlephaError(
+        `Schema depth exceeds maximum allowed (${this.maxDepth})`,
+      );
+    }
+
+    if (t.schema.isObject(schema)) {
+      const objSchema = schema as TObject;
+      const props = objSchema.properties as Record<string, TSchema>;
+
+      for (const key of Object.keys(props)) {
+        if (UNSAFE_KEYS.has(key)) {
+          throw new AlephaError(
+            `Unsafe schema key "${key}" detected. This key is blocked to prevent prototype pollution.`,
+          );
+        }
+        // Depth increases for object properties
+        this.validateSchemaKeys(props[key], depth + 1, visited);
+      }
+    } else if (t.schema.isArray(schema)) {
+      const arrSchema = schema as TArray;
+      // Depth increases for array items
+      this.validateSchemaKeys(arrSchema.items, depth + 1, visited);
+    } else if (t.schema.isUnion(schema) || t.schema.isOptional(schema)) {
+      // Optional/union wrappers don't increase depth - they're type modifiers
+      this.validateSchemaKeys(this.unwrap(schema), depth, visited);
+    }
+  }
+
+  /**
+   * Validate array length.
+   */
+  protected validateArrayLength(arr: unknown[]): void {
+    if (arr.length > this.maxArrayLength) {
+      throw new AlephaError(
+        `Array length (${arr.length}) exceeds maximum allowed (${this.maxArrayLength})`,
+      );
+    }
+  }
+
+  /**
+   * Validate string length.
+   */
+  protected validateStringLength(str: string): void {
+    if (str.length > this.maxStringLength) {
+      throw new AlephaError(
+        `String length (${str.length}) exceeds maximum allowed (${this.maxStringLength})`,
+      );
+    }
+  }
+
   // ===========================================================================
   // Codec Compilation
   // ===========================================================================
@@ -90,7 +245,9 @@ export class KeylessJsonSchemaCodec extends SchemaCodec {
   protected getCodec<T>(schema: TSchema): KeylessCodec<T> {
     let c = this.cache.get(schema);
     if (!c) {
-      c = this.compile(schema);
+      c = this.useFunctionCompilation
+        ? this.compileWithFunction(schema)
+        : this.compileInterpreted(schema);
       this.cache.set(schema, c);
     }
     return c as KeylessCodec<T>;
@@ -100,7 +257,11 @@ export class KeylessJsonSchemaCodec extends SchemaCodec {
     return `_${this.varCounter++}`;
   }
 
-  protected compile(schema: TSchema): KeylessCodec {
+  /**
+   * Compile codec using `new Function()` for maximum performance.
+   * Only used when CSP allows and useFunctionCompilation is true.
+   */
+  protected compileWithFunction(schema: TSchema): KeylessCodec {
     this.varCounter = 0;
     const encBody = this.genEnc(schema, "v");
 
@@ -119,6 +280,229 @@ export class KeylessJsonSchemaCodec extends SchemaCodec {
     return { encode: encoder, decode: decoder };
   }
 
+  /**
+   * Compile codec using interpreter-based approach.
+   * Safer (no eval/Function) but slower. Used in browser by default.
+   */
+  protected compileInterpreted(schema: TSchema): KeylessCodec {
+    const self = this;
+
+    return {
+      encode(value: any): string {
+        return JSON.stringify(self.interpretEncode(schema, value));
+      },
+      decode(str: string): any {
+        const ctx = { arr: JSON.parse(str), i: 0 };
+        return self.interpretDecode(schema, ctx);
+      },
+    };
+  }
+
+  // ===========================================================================
+  // Interpreter-based Encoding (Safe Mode)
+  // ===========================================================================
+
+  protected interpretEncode(schema: TSchema, value: any): any {
+    if (
+      t.schema.isString(schema) ||
+      t.schema.isNumber(schema) ||
+      t.schema.isInteger(schema) ||
+      t.schema.isBoolean(schema) ||
+      this.isEnum(schema)
+    ) {
+      return value;
+    }
+
+    if (t.schema.isBigInt(schema)) {
+      return `${value}n`;
+    }
+
+    if (t.schema.isArray(schema)) {
+      const arrSchema = schema as TArray;
+      if (!Array.isArray(value)) return value;
+
+      if (
+        t.schema.isString(arrSchema.items) ||
+        t.schema.isNumber(arrSchema.items) ||
+        t.schema.isInteger(arrSchema.items) ||
+        t.schema.isBoolean(arrSchema.items)
+      ) {
+        return value;
+      }
+      return value.map((e) => this.interpretEncode(arrSchema.items, e));
+    }
+
+    if (t.schema.isObject(schema)) {
+      const objSchema = schema as TObject;
+      const props = objSchema.properties as Record<string, TSchema>;
+      const keys = Object.keys(props);
+      const req = new Set((objSchema.required as string[]) || []);
+
+      const result: any[] = [];
+      for (const k of keys) {
+        const ps = props[k];
+        const isOpt = !req.has(k) || t.schema.isOptional(ps);
+        const isNullable = this.isNullable(ps);
+        const inner = this.unwrap(ps);
+        const v = value[k];
+
+        if (isOpt) {
+          result.push(v !== undefined ? this.interpretEncode(inner, v) : null);
+        } else if (isNullable) {
+          result.push(v !== null ? this.interpretEncode(inner, v) : null);
+        } else {
+          result.push(this.interpretEncode(inner, v));
+        }
+      }
+      return result;
+    }
+
+    if (t.schema.isOptional(schema) || t.schema.isUnion(schema)) {
+      const inner = this.unwrap(schema);
+      if (this.isNullable(schema)) {
+        return value !== null ? this.interpretEncode(inner, value) : null;
+      }
+      return value !== undefined ? this.interpretEncode(inner, value) : null;
+    }
+
+    return value;
+  }
+
+  // ===========================================================================
+  // Interpreter-based Decoding (Safe Mode)
+  // ===========================================================================
+
+  protected interpretDecode(
+    schema: TSchema,
+    ctx: { arr: any[]; i: number },
+  ): any {
+    if (
+      t.schema.isString(schema) ||
+      t.schema.isNumber(schema) ||
+      t.schema.isInteger(schema) ||
+      t.schema.isBoolean(schema) ||
+      this.isEnum(schema)
+    ) {
+      return ctx.arr[ctx.i++];
+    }
+
+    if (t.schema.isBigInt(schema)) {
+      return BigInt(ctx.arr[ctx.i++].slice(0, -1));
+    }
+
+    if (t.schema.isArray(schema)) {
+      const arrSchema = schema as TArray;
+      const arr = ctx.arr[ctx.i++];
+      if (!Array.isArray(arr)) return arr;
+
+      if (t.schema.isObject(arrSchema.items)) {
+        return arr.map((e) =>
+          this.interpretDecodeFromValue(arrSchema.items, e),
+        );
+      }
+      return arr;
+    }
+
+    if (t.schema.isObject(schema)) {
+      const objSchema = schema as TObject;
+      const props = objSchema.properties as Record<string, TSchema>;
+      const keys = Object.keys(props);
+      const req = new Set((objSchema.required as string[]) || []);
+
+      const result: Record<string, any> = {};
+
+      for (const k of keys) {
+        const ps = props[k];
+        const isOpt = !req.has(k) || t.schema.isOptional(ps);
+        const isNullable = this.isNullable(ps);
+        const inner = this.unwrap(ps);
+        const val = ctx.arr[ctx.i++];
+
+        if (isOpt) {
+          if (val !== null) {
+            result[k] = this.interpretDecodeFromValue(inner, val);
+          }
+        } else if (isNullable) {
+          result[k] =
+            val === null ? null : this.interpretDecodeFromValue(inner, val);
+        } else {
+          result[k] = this.interpretDecodeFromValue(inner, val);
+        }
+      }
+
+      return result;
+    }
+
+    if (t.schema.isOptional(schema) || t.schema.isUnion(schema)) {
+      const inner = this.unwrap(schema);
+      const val = ctx.arr[ctx.i++];
+
+      if (val === null) {
+        return this.isNullable(schema) ? null : undefined;
+      }
+
+      if (t.schema.isObject(inner) || t.schema.isArray(inner)) {
+        return this.interpretDecodeFromValue(inner, val);
+      }
+
+      return val;
+    }
+
+    return ctx.arr[ctx.i++];
+  }
+
+  protected interpretDecodeFromValue(schema: TSchema, value: any): any {
+    if (
+      t.schema.isString(schema) ||
+      t.schema.isNumber(schema) ||
+      t.schema.isInteger(schema) ||
+      t.schema.isBoolean(schema) ||
+      this.isEnum(schema)
+    ) {
+      return value;
+    }
+
+    if (t.schema.isBigInt(schema)) {
+      return BigInt(value.slice(0, -1));
+    }
+
+    if (t.schema.isArray(schema)) {
+      if (!Array.isArray(value)) return value;
+      const arrSchema = schema as TArray;
+      if (t.schema.isObject(arrSchema.items)) {
+        return value.map((e) =>
+          this.interpretDecodeFromValue(arrSchema.items, e),
+        );
+      }
+      return value;
+    }
+
+    if (t.schema.isObject(schema)) {
+      const objSchema = schema as TObject;
+      const props = objSchema.properties as Record<string, TSchema>;
+      const keys = Object.keys(props);
+      const result: Record<string, any> = {};
+
+      for (let idx = 0; idx < keys.length; idx++) {
+        const k = keys[idx];
+        const inner = this.unwrap(props[k]);
+        const v = value[idx];
+
+        if (t.schema.isObject(inner)) {
+          result[k] = this.interpretDecodeFromValue(inner, v);
+        } else if (t.schema.isBigInt(inner)) {
+          result[k] = BigInt(v.slice(0, -1));
+        } else {
+          result[k] = v;
+        }
+      }
+
+      return result;
+    }
+
+    return value;
+  }
+
   // ===========================================================================
   // Encoder - generates code that returns an array representation
   // ===========================================================================
@@ -365,9 +749,7 @@ export class KeylessJsonSchemaCodec extends SchemaCodec {
    * Reconstruct an object from a parsed array (for when input is already parsed).
    */
   protected reconstructObject(schema: TSchema, arr: any[]): any {
-    if (!t.schema.isObject(schema)) {
-      return arr;
-    }
+    if (!t.schema.isObject(schema)) return arr;
 
     const objSchema = schema as TObject;
     const props = objSchema.properties as Record<string, TSchema>;

package/src/core/providers/SchemaValidator.spec.ts

@@ -0,0 +1,236 @@
+import { Alepha, t } from "alepha";
+import { describe, test } from "vitest";
+import { SchemaValidator } from "./SchemaValidator.ts";
+
+describe("SchemaValidator", () => {
+  describe("Basic validation", () => {
+    test("should validate simple objects", async ({ expect }) => {
+      const alepha = Alepha.create();
+      const validator = alepha.inject(SchemaValidator);
+
+      const schema = t.object({
+        name: t.text(),
+        age: t.integer(),
+      });
+
+      const data = {
+        name: "Alice",
+        age: 30,
+      };
+
+      const result = validator.validate(schema, data);
+      expect(result).toEqual(data);
+    });
+
+    test("should trim strings when schema has trim option", async ({
+      expect,
+    }) => {
+      const alepha = Alepha.create();
+      const validator = alepha.inject(SchemaValidator);
+
+      const schema = t.object({
+        name: t.text({ trim: true }),
+      });
+
+      const data = {
+        name: "  Alice  ",
+      };
+
+      const result = validator.validate(schema, data);
+      expect(result.name).toBe("Alice");
+    });
+
+    test("should convert null to undefined for non-nullable fields", async ({
+      expect,
+    }) => {
+      const alepha = Alepha.create();
+      const validator = alepha.inject(SchemaValidator);
+
+      const schema = t.object({
+        name: t.text(),
+        bio: t.optional(t.text()),
+      });
+
+      const data = {
+        name: "Alice",
+        bio: null,
+      };
+
+      const result = validator.validate(schema, data);
+      expect(result.name).toBe("Alice");
+      expect(result.bio).toBeUndefined();
+    });
+  });
+
+  describe("Security - Prototype Pollution Protection", () => {
+    test("should filter out __proto__ key from input data", async ({
+      expect,
+    }) => {
+      const alepha = Alepha.create();
+      const validator = alepha.inject(SchemaValidator);
+
+      const schema = t.object({
+        name: t.text(),
+      });
+
+      // Input data with __proto__ key via JSON.parse (bypasses literal protection)
+      const data = JSON.parse('{"name":"Alice","__proto__":{"isAdmin":true}}');
+
+      const result = validator.validate(schema, data);
+
+      // __proto__ should not be an own property in the result
+      expect(result.name).toBe("Alice");
+      // Using hasOwnProperty because 'in' operator has special behavior for __proto__
+      expect(Object.hasOwn(result, "__proto__")).toBe(false);
+    });
+
+    test("should filter out constructor key from input data", async ({
+      expect,
+    }) => {
+      const alepha = Alepha.create();
+      const validator = alepha.inject(SchemaValidator);
+
+      const schema = t.object({
+        name: t.text(),
+      });
+
+      const data = {
+        name: "Alice",
+        constructor: { prototype: { isAdmin: true } },
+      };
+
+      const result = validator.validate(schema, data);
+
+      expect(result.name).toBe("Alice");
+      expect(Object.hasOwn(result, "constructor")).toBe(false);
+    });
+
+    test("should filter out prototype key from input data", async ({
+      expect,
+    }) => {
+      const alepha = Alepha.create();
+      const validator = alepha.inject(SchemaValidator);
+
+      const schema = t.object({
+        name: t.text(),
+      });
+
+      const data = {
+        name: "Alice",
+        prototype: { isAdmin: true },
+      };
+
+      const result = validator.validate(schema, data);
+
+      expect(result.name).toBe("Alice");
+      expect(Object.hasOwn(result, "prototype")).toBe(false);
+    });
+
+    test("should filter unsafe keys from nested objects", async ({
+      expect,
+    }) => {
+      const alepha = Alepha.create();
+      const validator = alepha.inject(SchemaValidator);
+
+      const schema = t.object({
+        user: t.object({
+          name: t.text(),
+        }),
+      });
+
+      const data = {
+        user: {
+          name: "Alice",
+          __proto__: { isAdmin: true },
+        },
+      };
+
+      const result = validator.validate(schema, data);
+
+      expect(result.user.name).toBe("Alice");
+      expect(Object.hasOwn(result.user, "__proto__")).toBe(false);
+    });
+
+    test("should not pollute Object.prototype", async ({ expect }) => {
+      const alepha = Alepha.create();
+      const validator = alepha.inject(SchemaValidator);
+
+      const schema = t.object({
+        name: t.text(),
+      });
+
+      // Attempt to pollute Object.prototype via __proto__
+      const maliciousData = JSON.parse(
+        '{"name":"Alice","__proto__":{"polluted":"yes"}}',
+      );
+
+      validator.validate(schema, maliciousData);
+
+      // Object.prototype should not be polluted
+      expect(({} as any).polluted).toBeUndefined();
+    });
+
+    test("should create objects without prototype chain", async ({
+      expect,
+    }) => {
+      const alepha = Alepha.create();
+      const validator = alepha.inject(SchemaValidator);
+
+      const schema = t.object({
+        name: t.text(),
+      });
+
+      const data = {
+        name: "Alice",
+      };
+
+      const result = validator.validate(schema, data);
+
+      // The result should not have Object.prototype methods directly accessible
+      // via hasOwnProperty (it should use Object.create(null))
+      expect(result.name).toBe("Alice");
+    });
+  });
+
+  describe("beforeParse", () => {
+    test("should handle arrays correctly", async ({ expect }) => {
+      const alepha = Alepha.create();
+      const validator = alepha.inject(SchemaValidator);
+
+      const schema = t.object({
+        tags: t.array(t.text({ trim: true })),
+      });
+
+      const data = {
+        tags: ["  tag1  ", "  tag2  "],
+      };
+
+      const result = validator.validate(schema, data);
+      expect(result.tags).toEqual(["tag1", "tag2"]);
+    });
+
+    test("should delete undefined values when option is enabled", async ({
+      expect,
+    }) => {
+      const alepha = Alepha.create();
+      const validator = alepha.inject(SchemaValidator);
+
+      const schema = t.object({
+        name: t.text(),
+        bio: t.optional(t.text()),
+      });
+
+      const data = {
+        name: "Alice",
+        bio: undefined,
+      };
+
+      const result = validator.validate(schema, data, {
+        deleteUndefined: true,
+      });
+
+      expect(result.name).toBe("Alice");
+      expect("bio" in result).toBe(false);
+    });
+  });
+});