bazis 0.119.0 → 0.121.0

package/core/http/HttpContext/HttpContext.ts

@@ -42,7 +42,10 @@ export class HttpContext {
     readonly apiVersion?: string,
     /** Optional maximum request body size enforced while reading body streams. */
     private readonly maxBodyBytes?: number,
-    /** Remote peer address reported by Bun (not a forwarded header). */
+    /**
+     * The client's address: the connection's, or with `http.trustedProxies`
+     * the address a trusted proxy forwarded in `X-Forwarded-For`.
+     */
     readonly clientIp?: string,
     /** Validator captured by the owning HTTP server. */
     readonly modelValidator?: ModelValidator,
@@ -52,6 +55,8 @@ export class HttpContext {
      * `undefined` without `language`.
      */
     readonly language?: string,
+    /** The address of the TCP connection itself (nginx behind a proxy), never a header. */
+    readonly peerIp?: string,
   ) {}
 
   get method(): string {

package/core/http/HttpContext/clientAddress.ts

@@ -0,0 +1,100 @@
+import { isIP } from "node:net";
+import { HttpSetupError } from "../Errors/HttpError";
+
+/** Addresses and subnets whose `X-Forwarded-For` is believed (`http.trustedProxies`). */
+export interface TrustedProxies {
+  trusts(address: string): boolean;
+}
+
+interface Subnet {
+  readonly family: 4 | 6;
+  readonly base: bigint;
+  readonly mask: bigint;
+}
+
+/**
+ * Compiles `http.trustedProxies`: IP addresses (`127.0.0.1`, `::1`) and
+ * subnets (`10.0.0.0/8`, `fd00::/8`). An invalid entry stops the start.
+ */
+export function trustedProxies(entries: readonly string[]): TrustedProxies {
+  const subnets = entries.map((entry) => {
+    const subnet = parseSubnet(entry);
+    if (subnet === undefined) {
+      throw new HttpSetupError(`http.trustedProxies: ${JSON.stringify(entry)} is not an IP address or a subnet such as "10.0.0.0/8".`);
+    }
+    return subnet;
+  });
+  return Object.freeze({
+    trusts(address: string): boolean {
+      const parsed = parseAddress(address);
+      return parsed !== undefined && subnets.some((subnet) => subnet.family === parsed.family && (parsed.value & subnet.mask) === subnet.base);
+    },
+  });
+}
+
+/**
+ * The client's address. A connection from a trusted proxy is resolved through
+ * `X-Forwarded-For` from the right: trusted hops are skipped and the first
+ * untrusted address is the client, so entries a client sent itself in front
+ * are never believed. A connection from any other address keeps that address:
+ * a client reaching the app directly cannot forge it. A malformed entry stops
+ * the walk at the last address known for sure.
+ */
+export function clientAddress(peer: string | undefined, forwardedFor: string | null | undefined, trusted: TrustedProxies | undefined): string | undefined {
+  if (peer === undefined) return undefined;
+  const direct = normalizeAddress(peer);
+  if (trusted === undefined || !trusted.trusts(direct) || !forwardedFor) return direct;
+  let current = direct;
+  const hops = forwardedFor.split(",").map((hop) => hop.trim());
+  for (let index = hops.length - 1; index >= 0; index -= 1) {
+    const hop = hops[index]!;
+    if (isIP(hop) === 0) return current;
+    current = normalizeAddress(hop);
+    if (!trusted.trusts(current)) return current;
+  }
+  return current;
+}
+
+/** `::ffff:127.0.0.1` (IPv4 over a dual-stack socket) is `127.0.0.1`; IPv6 is lower-case. */
+function normalizeAddress(address: string): string {
+  const mapped = address.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/iu);
+  return mapped ? mapped[1]! : address.toLowerCase();
+}
+
+function parseSubnet(entry: string): Subnet | undefined {
+  const [address, prefixText, extra] = entry.trim().split("/");
+  if (extra !== undefined || address === undefined) return undefined;
+  const parsed = parseAddress(address);
+  if (parsed === undefined) return undefined;
+  const bits = parsed.family === 4 ? 32 : 128;
+  const prefix = prefixText === undefined ? bits : /^\d+$/u.test(prefixText) ? Number(prefixText) : NaN;
+  if (!Number.isInteger(prefix) || prefix < 0 || prefix > bits) return undefined;
+  const mask = prefix === 0 ? 0n : ((1n << BigInt(prefix)) - 1n) << BigInt(bits - prefix);
+  return { family: parsed.family, base: parsed.value & mask, mask };
+}
+
+function parseAddress(text: string): { readonly family: 4 | 6; readonly value: bigint } | undefined {
+  const address = normalizeAddress(text.trim());
+  const family = isIP(address);
+  if (family === 4) {
+    return { family: 4, value: address.split(".").reduce((value, part) => (value << 8n) | BigInt(Number(part)), 0n) };
+  }
+  if (family !== 6) return undefined;
+  const [head = "", tail] = address.split("::");
+  const groups = (part: string) => (part === "" ? [] : part.split(":"));
+  const left = groups(head);
+  const right = tail === undefined ? [] : groups(tail);
+  // An embedded IPv4 tail (::ffff:… already normalized away, but 64:ff9b::1.2.3.4 is valid).
+  const expand = (items: string[]) => items.flatMap((item) => (item.includes(".") ? ipv4Groups(item) : [item]));
+  const leftGroups = expand(left);
+  const rightGroups = expand(right);
+  const missing = 8 - leftGroups.length - rightGroups.length;
+  const all = tail === undefined ? leftGroups : [...leftGroups, ...Array.from({ length: missing }, () => "0"), ...rightGroups];
+  if (all.length !== 8) return undefined;
+  return { family: 6, value: all.reduce((value, group) => (value << 16n) | BigInt(parseInt(group, 16)), 0n) };
+}
+
+function ipv4Groups(address: string): string[] {
+  const [a, b, c, d] = address.split(".").map(Number) as [number, number, number, number];
+  return [((a << 8) | b).toString(16), ((c << 8) | d).toString(16)];
+}

package/core/http/HttpServer.ts

@@ -23,6 +23,7 @@ import { HTTP_ERROR_HOOK, ROUTE_MIDDLEWARE_COMPOSER, SERVER_MIDDLEWARE, sortByOr
 import type { HealthEndpointOptions, RouteMiddlewareComposer, HttpModuleOptions, HttpServerOptions } from "./options";
 import { WEBSOCKET_UPGRADE, type WebSocketUpgrade } from "./WebSocketUpgrade";
 import { HttpSetupError } from "./Errors/HttpError";
+import { clientAddress, trustedProxies, type TrustedProxies } from "./HttpContext/clientAddress";
 import { EN_HTTP_MESSAGES, formatMessage, languageHeaders, type HttpMessageKey, type MessageParams, type SelectedLanguage } from "./Errors/messages";
 import { getModelValidator, type ModelValidator } from "./Binding/modelValidator";
 
@@ -43,6 +44,12 @@ function json(status: number, body: unknown, headers?: Record<string, string>):
   });
 }
 
+/** The client's address (after trusted proxies) and the connection's own. */
+interface ClientConnection {
+  readonly clientIp?: string;
+  readonly peerIp?: string;
+}
+
 /** HEAD responses must carry no body, only headers/status. */
 function stripBody(response: Response): Response {
   if (!response.body) return response;
@@ -82,6 +89,7 @@ export class HttpServer implements HostedService {
   private globalCors: CorsOptions | undefined;
   /** Body cap in bytes; `undefined` when the limit is disabled (`maxBodyBytes: 0`). */
   private readonly maxBodyBytes?: number;
+  private readonly trustedProxies?: TrustedProxies;
   private readonly requestScopeDisposeTimeoutMs?: number;
   private readonly responseCompletions = new Set<Promise<void>>();
   /** Absolute health-probe path, or `undefined` when disabled. */
@@ -112,6 +120,7 @@ export class HttpServer implements HostedService {
       throw new HttpSetupError("inspectableRedirects must be a boolean.");
     }
     this.maxBodyBytes = options.maxBodyBytes === 0 ? undefined : (options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES);
+    this.trustedProxies = options.trustedProxies === undefined || options.trustedProxies.length === 0 ? undefined : trustedProxies(options.trustedProxies);
     this.requestScopeDisposeTimeoutMs = options.requestScopeDisposeTimeoutMs === 0
       ? undefined
       : options.requestScopeDisposeTimeoutMs ?? DEFAULT_REQUEST_SCOPE_DISPOSE_TIMEOUT_MS;
@@ -376,11 +385,12 @@ export class HttpServer implements HostedService {
     }
   }
 
-  private async dispatch(incoming: Request, clientIp?: string): Promise<Response> {
+  private async dispatch(incoming: Request, peerIp?: string): Promise<Response> {
     const request = this.withAbsoluteUrl(incoming);
     let response: Response;
     try {
-      response = await this.handle(request, clientIp);
+      const client: ClientConnection = { clientIp: clientAddress(peerIp, request.headers.get("x-forwarded-for"), this.trustedProxies), peerIp };
+      response = await this.handle(request, client);
     } catch (error) {
       // Covers failures before a request context can be created. Normal route
       // and short-circuit failures are handled by the configured error boundary.
@@ -440,34 +450,34 @@ export class HttpServer implements HostedService {
     return new Request(new URL(request.url, `http://${host}:${server?.port ?? 80}`).href, request);
   }
 
-  private async handle(request: Request, clientIp?: string): Promise<Response> {
+  private async handle(request: Request, client: ClientConnection): Promise<Response> {
     const url = new URL(request.url);
 
     if (this.healthPath !== undefined && url.pathname === this.healthPath && isReadMethod(request.method)) {
-      return this.runShortCircuit(request, url, clientIp, () => this.healthResponse());
+      return this.runShortCircuit(request, url, client, () => this.healthResponse());
     }
 
     if (this.docs !== undefined) {
       const docsResponse = serveOpenApiDocs(this.docs, url.pathname, request.method);
       if (docsResponse !== undefined) {
-        return this.runShortCircuit(request, url, clientIp, () => docsResponse);
+        return this.runShortCircuit(request, url, client, () => docsResponse);
       }
     }
 
     if (isPreflight(request)) {
       const corsOptions = this.globalCors ?? this.routeCors(request, url);
       if (corsOptions !== undefined) {
-        return this.runShortCircuit(request, url, clientIp, () => preflightResponse(corsOptions, request));
+        return this.runShortCircuit(request, url, client, () => preflightResponse(corsOptions, request));
       }
     }
 
     const segments = parseRequestPath(url.pathname);
     if (!segments) {
       if (this.maxBodyBytes !== undefined && exceedsBodyLimit(request, this.maxBodyBytes)) {
-        return this.runShortCircuit(request, url, clientIp, () =>
+        return this.runShortCircuit(request, url, client, () =>
           this.errorJson(request, 413, "payloadTooLarge", { details: { maxBytes: this.maxBodyBytes } }));
       }
-      return this.runShortCircuit(request, url, clientIp, () => this.errorJson(request, 400, "malformedPath"));
+      return this.runShortCircuit(request, url, client, () => this.errorJson(request, 400, "malformedPath"));
     }
 
     const match = this.router!.match(request.method, segments, this.readVersion(request, url));
@@ -475,18 +485,18 @@ export class HttpServer implements HostedService {
       ? (match.action.maxBodyBytes ?? this.maxBodyBytes)
       : this.maxBodyBytes;
     if (effectiveMaxBodyBytes !== undefined && exceedsBodyLimit(request, effectiveMaxBodyBytes)) {
-      return this.runShortCircuit(request, url, clientIp, () =>
+      return this.runShortCircuit(request, url, client, () =>
         this.errorJson(request, 413, "payloadTooLarge", { details: { maxBytes: effectiveMaxBodyBytes } }));
     }
     if (match.kind === "not-found") {
-      return this.runShortCircuit(request, url, clientIp, () => this.errorJson(request, 404, "notFound"));
+      return this.runShortCircuit(request, url, client, () => this.errorJson(request, 404, "notFound"));
     }
     if (match.kind === "method-not-allowed") {
-      return this.runShortCircuit(request, url, clientIp, () =>
+      return this.runShortCircuit(request, url, client, () =>
         this.errorJson(request, 405, "methodNotAllowed", {}, { allow: match.allow.join(", ") }));
     }
     if (match.kind === "unsupported-version") {
-      return this.runShortCircuit(request, url, clientIp, () =>
+      return this.runShortCircuit(request, url, client, () =>
         this.errorJson(request, 400, "unsupportedApiVersion", { details: { supported: match.supported } }));
     }
 
@@ -498,9 +508,10 @@ export class HttpServer implements HostedService {
       scope,
       match.action.version,
       effectiveMaxBodyBytes,
-      clientIp,
+      client.clientIp,
       this.modelValidator,
       this.selected(request)?.language,
+      client.peerIp,
     );
     let scopeTransferred = false;
     try {
@@ -532,7 +543,7 @@ export class HttpServer implements HostedService {
   private async runShortCircuit(
     request: Request,
     url: URL,
-    clientIp: string | undefined,
+    client: ClientConnection,
     produce: () => Response | Promise<Response>,
   ): Promise<Response> {
     const scope = this.provider.createScope();
@@ -543,9 +554,10 @@ export class HttpServer implements HostedService {
       scope,
       undefined,
       this.maxBodyBytes,
-      clientIp,
+      client.clientIp,
       this.modelValidator,
       this.selected(request)?.language,
+      client.peerIp,
     );
     const terminal: HttpMiddleware = async (context) => {
       context.response = await produce();

package/core/http/Middleware/accessLog.ts

@@ -11,6 +11,8 @@ export interface AccessLogEntry {
   readonly durationMs: number;
   /** Correlation id from {@link createCorrelationIdMiddleware}, if present. */
   readonly requestId?: string;
+  /** `ctx.clientIp`: the client's address, through `http.trustedProxies`. */
+  readonly clientIp?: string;
 }
 
 export interface AccessLogOptions {
@@ -42,6 +44,7 @@ function resolveSink(options: AccessLogOptions): (entry: AccessLogEntry) => void
           status: entry.status,
           durationMs: entry.durationMs,
           ...(entry.requestId !== undefined ? { requestId: entry.requestId } : {}),
+          ...(entry.clientIp !== undefined ? { clientIp: entry.clientIp } : {}),
         },
       );
   }
@@ -75,6 +78,7 @@ export function accessLog(options: AccessLogOptions = {}): HttpMiddleware {
             status: ctx.response?.status ?? 0,
             durationMs: Math.round((performance.now() - startedAt) * 100) / 100,
             ...(typeof requestId === "string" ? { requestId } : {}),
+            ...(ctx.clientIp !== undefined ? { clientIp: ctx.clientIp } : {}),
           });
         }
       } catch (error) {

package/core/http/Middleware/rateLimit.ts

@@ -9,19 +9,11 @@ export interface RateLimitOptions {
   /** Max requests per key per window. */
   max: number;
   /**
-   * Request key (default: Bun's direct peer IP, falling back to a single shared
-   * bucket when unavailable). Plug your own: user id, API key, etc.
+   * Request key (default: `ctx.clientIp`, the client's address behind
+   * `http.trustedProxies`, falling back to a single shared bucket when it is
+   * unavailable). Plug your own: user id, API key, etc.
    */
   keyOf?: (ctx: HttpContext) => string;
-  /**
-   * Read the client address from `X-Forwarded-For` behind trusted proxies.
-   * `true` — one proxy: the last address, the one the proxy saw; a number —
-   * that many proxies: the address that many hops from the end. Earlier
-   * addresses are written by the client and are never used. Off by default.
-   */
-  trustProxy?: boolean | number;
-  /** Forwarded client-address header used when `trustProxy` is set. */
-  proxyHeader?: string;
   /** Hard cap for in-process buckets. New keys receive 429 when full. Default: 10,000. */
   maxBuckets?: number;
   /** Add `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` to responses. Default: true. */
@@ -46,18 +38,8 @@ export function rateLimit(options: RateLimitOptions): HttpMiddleware {
   const buckets = new Map<string, Bucket>();
   const maxBuckets = Math.floor(options.maxBuckets ?? 10_000);
   let nextExpiry = Number.POSITIVE_INFINITY;
-  const proxyHeader = options.proxyHeader ?? "x-forwarded-for";
-  const trustedHops = options.trustProxy === true ? 1 : options.trustProxy || 0;
   const withHeaders = options.headers !== false;
-  const keyOf = options.keyOf ?? ((ctx: HttpContext) => {
-    if (trustedHops > 0) {
-      const forwarded = forwardedClient(ctx.header(proxyHeader), trustedHops);
-      if (forwarded) {
-        return forwarded;
-      }
-    }
-    return ctx.clientIp ?? "*";
-  });
+  const keyOf = options.keyOf ?? ((ctx: HttpContext) => ctx.clientIp ?? "*");
   const limitHeaders = (remaining: number, resetSeconds: number): Record<string, string> => ({
     "ratelimit-limit": String(options.max),
     "ratelimit-remaining": String(remaining),
@@ -104,11 +86,6 @@ export function rateLimit(options: RateLimitOptions): HttpMiddleware {
  * trusted proxy appends the address it saw, so entries before them are
  * whatever the client sent.
  */
-function forwardedClient(header: string | undefined, hops: number): string | undefined {
-  const addresses = header?.split(",").map((address) => address.trim()).filter((address) => address.length > 0) ?? [];
-  return addresses[Math.max(0, addresses.length - hops)];
-}
-
 function setIfAbsent(response: Response, headers: Record<string, string>): void {
   try {
     for (const [name, value] of Object.entries(headers)) {
@@ -129,8 +106,11 @@ function assertRateLimitOptions(options: RateLimitOptions): void {
   if (options.maxBuckets !== undefined && (!Number.isSafeInteger(options.maxBuckets) || options.maxBuckets <= 0)) {
     throw new HttpSetupError("rateLimit maxBuckets must be a positive integer.");
   }
-  if (typeof options.trustProxy === "number" && (!Number.isSafeInteger(options.trustProxy) || options.trustProxy <= 0)) {
-    throw new HttpSetupError("rateLimit trustProxy must be true, false or the number of trusted proxies (a positive integer).");
+  // Counting hops trusted a forged header whenever the app was reachable
+  // directly; the server now decides from the connection's own address.
+  const moved = (["trustProxy", "proxyHeader"] as const).find((name) => Object.hasOwn(options, name));
+  if (moved !== undefined) {
+    throw new HttpSetupError(`rateLimit ${moved} was removed: list the proxies in http.trustedProxies (for example ["127.0.0.1"] for nginx); rateLimit then keys by ctx.clientIp.`);
   }
 }
 

package/core/http/SPEC.md

@@ -444,6 +444,11 @@ line per request: `[http] GET /api/users 200 12.3ms <request-id>`.
 | `logger` | `Logger` | the `LOGGER` from DI | Structured sink: `logger.info` per request |
 | `skip` | `(ctx) => boolean` | — | Return `true` to skip a request (e.g. noisy probes) |
 
+`AccessLogEntry`: `method`, `path`, `status`, `durationMs`, `requestId?` (from the
+correlation middleware) and `clientIp?` (`ctx.clientIp`, the client's address behind
+`http.trustedProxies`). The structured logger gets the same fields; the plain stdout
+line does not print the address.
+
 ### `createCorrelationIdMiddleware(options?)`
 
 Reads `x-request-id` or generates a UUID, stores it in `ctx.state`, echoes it on the
@@ -476,9 +481,7 @@ server fails at startup so it never opens credentialed allow-any-origin.
 | --- | --- | --- | --- |
 | `windowMs` | `number` | — | window size (ms) |
 | `max` | `number` | — | max requests per key per window |
-| `keyOf` | `(ctx) => string` | the direct peer IP, else one shared bucket | the bucket key |
-| `trustProxy` | `boolean` | `false` | trust the first forwarded hop |
-| `proxyHeader` | `string` | `x-forwarded-for` | the forwarded address header, only with `trustProxy` |
+| `keyOf` | `(ctx) => string` | `ctx.clientIp`, else one shared bucket | the bucket key |
 | `maxBuckets` | `number` | `10000` | hard cap of in-process buckets; new keys get 429 when full |
 
 Exceeding the limit → `TooManyRequestsError` (429 + `Retry-After`).
@@ -505,7 +508,8 @@ Exceeding the limit → `TooManyRequestsError` (429 + `Retry-After`).
 | `ctx.json()` | the JSON body (cached per request) |
 | `ctx.text()`, `ctx.formData()` | alternative bodies |
 | `ctx.apiVersion` | the API version when versioning is on |
-| `ctx.clientIp` | the direct peer IP, when available |
+| `ctx.clientIp` | the client's address: the connection's, or behind `http.trustedProxies` the one a trusted proxy forwarded in `X-Forwarded-For` |
+| `ctx.peerIp` | the address of the connection itself (the proxy), never a header |
 
 ### Passing data between middleware
 
@@ -996,6 +1000,7 @@ inline is handy when the route options are already one object `{ code: 201, midd
 | `Middleware/securityHeaders.ts` | default security headers |
 | `Middleware/cors.ts` | CORS + preflight helpers |
 | `Middleware/rateLimit.ts` | the in-memory rate limiter |
+| `HttpContext/clientAddress.ts` | `http.trustedProxies`: the client's address from `X-Forwarded-For` of a trusted proxy |
 | `correlation/` | `createCorrelationIdMiddleware` |
 | `middlewareTokens.ts` | `SERVER_MIDDLEWARE`, `ROUTE_MIDDLEWARE_COMPOSER`, `HTTP_ERROR_HOOK` |
 | `Routing/RouterBuilder.ts` | builds the chain at startup |

package/core/http/options.ts

@@ -110,6 +110,14 @@ export interface HttpModuleOptions {
    * Default: 1 MiB. `0` disables the framework check.
    */
   readonly maxBodyBytes?: number;
+  /**
+   * Proxies whose `X-Forwarded-For` names the client: IP addresses and subnets,
+   * for example `["127.0.0.1", "10.0.0.0/8"]` for nginx. Then `ctx.clientIp`
+   * is the client's address; a connection from any other address keeps its
+   * own (the header cannot be forged by reaching the app directly), and
+   * `ctx.peerIp` is always the connection's address. Default: none.
+   */
+  readonly trustedProxies?: readonly string[];
   /** Per-connection idle timeout in seconds (Bun.serve, 0–255). Default: Bun's. */
   readonly idleTimeoutSeconds?: number;
   /** Maximum wait for request-scope disposal. Default 5000ms; `0` restores an unbounded wait. */

package/core/infra/connectors/codex/CodexAppServerClient.ts

@@ -232,7 +232,7 @@ export class CodexAppServerClient implements CodexClient {
         if (method === "account/updated") this.modelCache = undefined;
       }, () => { this.clearLogin(); this.modelCache = undefined; });
       const initialized = await client.request("initialize", {
-        clientInfo: { name: "bazis", title: "Bazis", version: "0.119.0" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.121.0" }, capabilities: { experimentalApi: true },
       }, 15_000, signal);
       if (resolve(text(initialized.codexHome, 4096)) !== this.paths.home) throw new CodexError("PROTOCOL_ERROR");
       client.notify("initialized");

package/library/validation/README.md

@@ -42,11 +42,12 @@ More scenarios (complex conditions, async, nested objects) are in
 
 | File | Purpose |
 |---|---|
-| `Validator.ts` | public facade: the decorator + `validate`/`validateAsync`/`setDefaultMessages` |
+| `Validator.ts` | public facade: the decorator + `validate`/`validateAsync`/`ruleSet`/`setDefaultMessages` |
 | `ValidationError.ts` | one error: `property`, `value`, `message`, `code` |
 | `ValidationResult.ts` | the outcome: `isValid`, `errors`, `getErrorsFor`, `hasErrorsFor` |
 | `RuleEngine.ts` | the engine: one pass over the plan, sync/async, nested, cycle protection |
 | `RuleCompiler.ts` | compiles class rules into a plan + WeakMap cache (RegExp, enum Set) |
+| `RuleSet.ts` | rules as data without a class: `Validator.ruleSet({ field: options })` |
 | `MessageRegistry.ts` | message templates, placeholders, priority local > global > built-in; built-in texts are English, `RU_VALIDATION_MESSAGES` is a Russian set for `setDefaults` and `runApp({ language: "ru" })` |
 | `metadata.ts` | stores rules through `context.metadata` / `Symbol.metadata` |
 | `types/ValidatorOptions.ts` | all decorator options |

package/library/validation/RuleCompiler.ts

@@ -1,4 +1,4 @@
-import { rulesOf } from "./metadata";
+import { rulesOf, type FieldRule } from "./metadata";
 import type { ValidatorOptions } from "./types/ValidatorOptions";
 
 /**
@@ -69,9 +69,18 @@ export class RuleCompiler {
     if (!rules) {
       return undefined;
     }
+    const plan = RuleCompiler.compileRules(rules);
+    RuleCompiler.cache.set(ctor, plan);
+    return plan;
+  }
+
+  /**
+   * Compiles a rule list that is not tied to a class (see `RuleSet`). Not
+   * cached: the caller keeps the result for as long as the rules are valid.
+   */
+  static compileRules(rules: readonly FieldRule[]): CompiledRule[] {
     const plan = rules.map((rule) => RuleCompiler.compile(rule.property, rule.options));
     RuleCompiler.assignNestedCarriers(plan);
-    RuleCompiler.cache.set(ctor, plan);
     return plan;
   }
 

package/library/validation/RuleEngine.ts

@@ -49,6 +49,24 @@ export class RuleEngine {
     return new ValidationResult(errors);
   }
 
+  /** Synchronous validation of any object by a precompiled plan (see `RuleSet`). */
+  static validatePlan(plan: readonly CompiledRule[], value: object): ValidationResult {
+    const errors: ValidationError[] = [];
+    RuleEngine.run(plan, value, "", errors, undefined, undefined);
+    return new ValidationResult(errors);
+  }
+
+  /** Asynchronous validation of any object by a precompiled plan (see `RuleSet`). */
+  static async validatePlanAsync(plan: readonly CompiledRule[], value: object): Promise<ValidationResult> {
+    const errors: ValidationError[] = [];
+    const jobs: AsyncJob[] = [];
+    RuleEngine.run(plan, value, "", errors, jobs, undefined);
+    for (const job of jobs) {
+      await job();
+    }
+    return new ValidationResult(errors);
+  }
+
   /**
    * Asynchronous validation: all synchronous rules run immediately, async
    * `custom` functions run sequentially after them (deterministic error order).
@@ -75,6 +93,17 @@ export class RuleEngine {
     if (!plan) {
       return;
     }
+    RuleEngine.run(plan, instance, prefix, errors, jobs, seen);
+  }
+
+  private static run(
+    plan: readonly CompiledRule[],
+    instance: object,
+    prefix: string,
+    errors: ValidationError[],
+    jobs: AsyncJob[] | undefined,
+    seen: Set<object> | undefined,
+  ): void {
     for (const rule of plan) {
       RuleEngine.applyRule(rule, instance, prefix, errors, jobs, seen);
     }

package/library/validation/RuleSet.ts

@@ -0,0 +1,59 @@
+import { RuleCompiler, type CompiledRule } from "./RuleCompiler";
+import { RuleEngine } from "./RuleEngine";
+import type { ValidationResult } from "./ValidationResult";
+import type { FieldRule } from "./metadata";
+import type { ValidatorOptions } from "./types/ValidatorOptions";
+
+/** Field rules of a {@link RuleSet}: one options object or several, as several decorators on one field. */
+export type FieldRules = Readonly<Record<string, ValidatorOptions | readonly ValidatorOptions[]>>;
+
+/**
+ * Validation rules that are data, not a decorated class: for objects whose
+ * shape is known only at run time (rows of tables created by users, rules
+ * stored in a database). The same engine, options, codes and messages as
+ * `@Validator`; the rules are compiled once in the constructor.
+ *
+ * ```ts
+ * const rules = Validator.ruleSet({
+ *   title: { required: true, maxLength: 200 },
+ *   amount: [{ type: "number", min: 0 }, { integer: true }],
+ * });
+ * rules.validate({ title: "", amount: -1.5 }).errors;
+ * ```
+ *
+ * Only the named fields are read. A field name that exists on
+ * `Object.prototype` (`__proto__`, `constructor`, `toString`…) is rejected,
+ * so a plain object never yields an inherited value.
+ */
+export class RuleSet {
+  private readonly plan: readonly CompiledRule[];
+
+  constructor(rules: FieldRules) {
+    const list: FieldRule[] = [];
+    for (const property of Object.keys(rules)) {
+      if (property in Object.prototype) {
+        throw new TypeError(`RuleSet: field "${property}" is not allowed: it is a property of Object.prototype.`);
+      }
+      const options = rules[property]!;
+      for (const item of Array.isArray(options) ? options as readonly ValidatorOptions[] : [options as ValidatorOptions]) {
+        list.push({ property, options: item });
+      }
+    }
+    this.plan = RuleCompiler.compileRules(list);
+  }
+
+  /** Field names that have rules. */
+  get fields(): readonly string[] {
+    return [...new Set(this.plan.map((rule) => rule.property))];
+  }
+
+  /** Synchronous validation; an async `custom` adds an `asyncCustomInSyncCall` error. */
+  validate(value: object): ValidationResult {
+    return RuleEngine.validatePlan(this.plan, value);
+  }
+
+  /** Asynchronous validation: awaits async `custom` functions. */
+  validateAsync(value: object): Promise<ValidationResult> {
+    return RuleEngine.validatePlanAsync(this.plan, value);
+  }
+}

package/library/validation/SPEC.md

@@ -412,6 +412,34 @@ Validator.validate(new ChildDto());  // checks both id and extra
 Validator.validate(new BaseDto());   // only id
 ```
 
+### 4.13 Rules as data: `Validator.ruleSet`
+
+When the fields are known only at run time (a table created by a user, rules
+stored in a database), there is no class to decorate. `Validator.ruleSet`
+takes the same options per field name and compiles them once:
+
+```ts
+const rules = Validator.ruleSet({
+  title: { required: true, maxLength: 200 },
+  amount: [{ type: "number", min: 0 }, { integer: true }],   // like two decorators
+});
+
+rules.validate({ title: "", amount: -1.5 }).errors;
+// [amount: min, amount: integer] — "" is a value, so required passes
+await rules.validateAsync(row);   // when a rule has an async custom
+rules.fields;                     // ["title", "amount"]
+```
+
+- Codes, paths, `params` and messages are the same as with `@Validator`.
+- The plan is compiled in the constructor (RegExp, enum Set) and not cached
+  globally: keep the `RuleSet` while the rules are valid and build a new one
+  when they change.
+- Only the named fields are read. A field name that exists on
+  `Object.prototype` (`__proto__`, `constructor`, `toString`…) throws
+  `TypeError`, so a plain object never yields an inherited value.
+- `nested: true` validates a nested value only if it is an instance of a
+  decorated class, as with decorators.
+
 ---
 
 ## 5. Result: `ValidationResult` and `ValidationError`

package/library/validation/Validator.ts

@@ -1,5 +1,6 @@
 import { MessageRegistry } from "./MessageRegistry";
 import { RuleEngine } from "./RuleEngine";
+import { RuleSet, type FieldRules } from "./RuleSet";
 import type { ValidationResult } from "./ValidationResult";
 import { registerFieldRule } from "./metadata";
 import type { ValidatorOptions } from "./types/ValidatorOptions";
@@ -74,6 +75,18 @@ export const Validator = Object.assign(
     validateAsync(instance: object): Promise<ValidationResult> {
       return RuleEngine.validateAsync(instance);
     },
+    /**
+     * Rules as data, without a class: for objects whose fields are known only
+     * at run time. Compiled once; keep the result and reuse it.
+     *
+     * ```ts
+     * const rules = Validator.ruleSet({ title: { required: true, maxLength: 200 } });
+     * rules.validate(row).isValid;
+     * ```
+     */
+    ruleSet(rules: FieldRules): RuleSet {
+      return new RuleSet(rules);
+    },
 
     /**
      * Globally overrides the standard error messages.

package/library/validation/index.ts

@@ -8,6 +8,7 @@
  * methods `validate` / `validateAsync` / `setDefaultMessages`.
  */
 export { Validator } from "./Validator";
+export { RuleSet, type FieldRules } from "./RuleSet";
 export { modelValidatorAdapter } from "./modelValidatorAdapter";
 export { ValidationError } from "./ValidationError";
 export { ValidationResult } from "./ValidationResult";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bazis",
-  "version": "0.119.0",
+  "version": "0.121.0",
   "description": "Modular backend framework for Bun in TypeScript: DI wired by codegen, HTTP, a PostgreSQL ORM, JWT, WebSocket, agents and a CLI.",
   "license": "MIT",
   "author": "Alexander Alenin",