feat(validation): add per-source request validation

- Add Mware.validator factory and Validator middleware running source contracts
- Add Reason mapper turning validation throws into 422 with reason cause
- Add Source extractor reading body, cookies, headers, json, params, query
- Add standalone Validator.check and Validator.read helpers
- Add validated reserved state key to stateKeys and reservedStateKeys
- Add validation interfaces: schema, source extractor, validated data
- Export Validator and re-export Define, Loader, contract types from root

Author: NeaByteLab

src/core/Handler.ts

@@ -13,15 +13,17 @@ export class Handler {
     worker: Handler.stateKey<Types.WorkerRunHandle>('worker'),
     session: Handler.stateKey<Types.DataRecord | null>('session'),
     setSession: Handler.stateKey<(data: Types.DataRecord) => Promise<void>>('setSession'),
-    clearSession: Handler.stateKey<() => void>('clearSession')
+    clearSession: Handler.stateKey<() => void>('clearSession'),
+    validated: Handler.stateKey<Types.DataRecord>('validated')
   } as const
   /** Reserved framework state key names, not writable by public setState */
   static readonly reservedStateKeys: ReadonlySet<string> = new Set([
     'view',
     'worker',
     'session',
     'setSession',
-    'clearSession'
+    'clearSession',
+    'validated'
   ])
 
   /**

src/index.ts

@@ -1,5 +1,10 @@
 /** Public API for Deserve HTTP server. */
-export { Context } from '@core/Context.ts'
-export { Mware, WrapMware } from '@middleware/index.ts'
-export { Router } from '@routing/Router.ts'
 export type * from '@interfaces/index.ts'
+export { Context } from '@core/index.ts'
+export { Mware, WrapMware } from '@middleware/index.ts'
+export { Router } from '@routing/index.ts'
+export { Validator } from '@validation/index.ts'
+
+/** Re-exports Typebox contract helpers. */
+export type * from '@neabyte/typebox'
+export { Define, Loader } from '@neabyte/typebox'

src/interfaces/Routing.ts

@@ -95,6 +95,8 @@ export interface StateKeysMap {
   readonly setSession: Types.StateKey<(data: Types.DataRecord) => Promise<void>>
   /** Key for the session clearer */
   readonly clearSession: Types.StateKey<() => void>
+  /** Key for validated request data */
+  readonly validated: Types.StateKey<Types.DataRecord>
 }
 
 /** Route entry for type-safe dispatch. */

src/interfaces/Validation.ts

@@ -0,0 +1,41 @@
+import type * as Types from '@interfaces/index.ts'
+import type * as Core from '@core/index.ts'
+import type { ContractFn } from '@neabyte/typebox'
+
+/** Per-source validation contract schema. */
+export interface ValidationSchema {
+  /** Contract for raw request body */
+  readonly body?: ContractFn
+  /** Contract for parsed request cookies */
+  readonly cookies?: ContractFn
+  /** Contract for request header record */
+  readonly headers?: ContractFn
+  /** Contract for parsed JSON body */
+  readonly json?: ContractFn
+  /** Contract for matched route params */
+  readonly params?: ContractFn
+  /** Contract for query string record */
+  readonly query?: ContractFn
+}
+
+/**
+ * Extract raw data from a source.
+ * @description Reads one validation source from the context.
+ * @param ctx - Request context instance
+ * @returns Source value, possibly async
+ */
+export type SourceExtractor = (ctx: Core.Context) => Types.MaybeAsync<unknown>
+
+/**
+ * Validated output mapped from a schema.
+ * @description Maps each source to its contract output type.
+ * @template SchemaType - Validation schema being validated
+ */
+export type ValidatedData<SchemaType extends ValidationSchema> = {
+  readonly [Key in keyof SchemaType]: SchemaType[Key] extends (input: never) => infer OutputType
+    ? Awaited<OutputType>
+    : never
+}
+
+/** Allowed validation source key. */
+export type ValidationSource = keyof ValidationSchema

src/interfaces/index.ts

@@ -4,3 +4,4 @@ export * from '@interfaces/Middleware.ts'
 export * from '@interfaces/Observability.ts'
 export * from '@interfaces/Rendering.ts'
 export * from '@interfaces/Routing.ts'
+export * from '@interfaces/Validation.ts'

src/middleware/Loaders.ts

@@ -6,4 +6,5 @@ export * from '@middleware/CSRF.ts'
 export * from '@middleware/IP.ts'
 export * from '@middleware/SecHeaders.ts'
 export * from '@middleware/Session.ts'
+export * from '@middleware/Validator.ts'
 export * from '@middleware/WebSocket.ts'

src/middleware/Validator.ts

@@ -0,0 +1,47 @@
+import type * as Types from '@interfaces/index.ts'
+import * as Core from '@core/index.ts'
+import * as Middleware from '@middleware/index.ts'
+import * as Validation from '@validation/index.ts'
+import type { ContractFn } from '@neabyte/typebox'
+
+/**
+ * Request validation middleware for sources.
+ * @description Runs source contracts, stores validated data on context.
+ */
+export class Validator {
+  /**
+   * Create validation middleware from schema.
+   * @description Validates each source contract, stores result on context.
+   * @param schema - Per-source validation contracts
+   * @returns Middleware that validates request sources
+   * @throws {Deno.errors.InvalidData} When schema has no source contract
+   * @throws {Deno.errors.InvalidData} When schema validates params, unavailable before routing
+   */
+  static create(schema: Types.ValidationSchema): Types.MiddlewareFn {
+    const entries = Object.entries(schema).filter(
+      (entry): entry is [Types.ValidationSource, ContractFn] => typeof entry[1] === 'function'
+    )
+    if (entries.length === 0) {
+      throw new Deno.errors.InvalidData('Validator requires at least one source contract')
+    }
+    if (entries.some(([source]) => source === 'params')) {
+      throw new Deno.errors.InvalidData(
+        'Validator cannot validate params in middleware, route params resolve after middleware runs, validate them inside the handler with Validator.check(contract, ctx.params())'
+      )
+    }
+    return Middleware.WrapMware('Validation error', async (ctx, next) => {
+      const existing = ctx.getState(Core.Handler.stateKeys.validated)
+      const validated: Types.DataRecord = { ...existing }
+      for (const [source, contract] of entries) {
+        const input = await Validation.Source.extract(source, ctx)
+        try {
+          validated[source] = contract(input as never)
+        } catch (error) {
+          throw Validation.Reason.toStatusError(error)
+        }
+      }
+      ctx[Core.InternalContext].setInternalState(Core.Handler.stateKeys.validated, validated)
+      return await next()
+    })
+  }
+}

src/middleware/index.ts

@@ -25,6 +25,9 @@ export const Mware = {
     Loader.SecHeaders.create(options),
   /** Session middleware factory */
   session: (options: Types.SessionOptions): Types.MiddlewareFn => Loader.Session.create(options),
+  /** Validation middleware factory */
+  validator: (schema: Types.ValidationSchema): Types.MiddlewareFn =>
+    Loader.Validator.create(schema),
   /** WebSocket upgrade middleware factory */
   websocket: (options?: Types.WebSocketOptions): Types.MiddlewareFn =>
     Loader.WebSocket.create(options)

src/validation/Reason.ts

@@ -0,0 +1,35 @@
+import type * as Types from '@interfaces/index.ts'
+import * as Core from '@core/index.ts'
+
+/**
+ * Validation error to status mapper.
+ * @description Maps validation throws to HTTP status errors.
+ */
+export class Reason {
+  /**
+   * Map a validation error to status.
+   * @description Preserves existing status, else maps client input to 422.
+   * @param error - Unknown value thrown during validation
+   * @returns StatusError carrying the resolved status code
+   */
+  static toStatusError(error: unknown): Types.StatusError {
+    if (Core.Handler.isErrorWithStatus(error)) {
+      return error
+    }
+    if (error instanceof Error && Array.isArray(error.cause)) {
+      const reasons = (error.cause as readonly unknown[]).filter(
+        (reason): reason is string => typeof reason === 'string'
+      )
+      const message = reasons.length > 0 ? reasons.join('; ') : 'Validation failed'
+      const statusError = Core.Handler.createStatusError(422, message)
+      Object.defineProperty(statusError, 'cause', {
+        value: reasons,
+        writable: false,
+        enumerable: false,
+        configurable: false
+      })
+      return statusError
+    }
+    return Core.Handler.createStatusError(422, 'Unprocessable request input')
+  }
+}

src/validation/Source.ts

@@ -0,0 +1,31 @@
+import type * as Types from '@interfaces/index.ts'
+import type * as Core from '@core/index.ts'
+
+/**
+ * Request source value extractor.
+ * @description Reads validation input from request sources.
+ */
+export class Source {
+  /** Extractor map per validation source */
+  private static readonly extractors: Readonly<
+    Record<Types.ValidationSource, Types.SourceExtractor>
+  > = {
+    body: (ctx) => ctx.body(),
+    cookies: (ctx) => ctx.cookie(),
+    headers: (ctx) => ctx.header(),
+    json: (ctx) => ctx.json(),
+    params: (ctx) => ctx.params(),
+    query: (ctx) => ctx.query()
+  }
+
+  /**
+   * Extract input value for source.
+   * @description Reads request data for the given source.
+   * @param source - Validation source name
+   * @param ctx - Request context instance
+   * @returns Extracted source value
+   */
+  static extract(source: Types.ValidationSource, ctx: Core.Context): Types.MaybeAsync<unknown> {
+    return Source.extractors[source](ctx)
+  }
+}