@nestia/core 14.0.0 → 14.0.2

package/src/adaptors/WebSocketAdaptor.ts

@@ -1,5 +1,9 @@
 /// <reference path="../typings/get-function-location.d.ts" />
-import { INestApplication, VersioningType } from "@nestjs/common";
+import {
+  HttpException,
+  INestApplication,
+  VersioningType,
+} from "@nestjs/common";
 import {
   HOST_METADATA,
   MODULE_PATH,
@@ -14,23 +18,62 @@ import { Module } from "@nestjs/core/injector/module";
 import getFunctionLocation from "get-function-location";
 import { IncomingMessage, Server } from "http";
 import path from "path";
-import { Path } from "path-parser";
 import { Duplex } from "stream";
 import { WebSocketAcceptor } from "tgrid";
 import typia from "typia";
+import { fileURLToPath } from "url";
 import WebSocket from "ws";
 
 import { IWebSocketRouteReflect } from "../decorators/internal/IWebSocketRouteReflect";
+import { resolve_request_body } from "../decorators/internal/validate_request_body";
 import { ArrayUtil } from "../utils/ArrayUtil";
 import { VersioningStrategy } from "../utils/VersioningStrategy";
+import { RoutePathMatcher } from "./internal/RoutePathMatcher";
 
+/**
+ * Serves the `@WebSocketRoute()` methods of a NestJS application over
+ * WebSocket.
+ *
+ * Call {@link upgrade} after the application has been created. It finds the
+ * routes, checks them, and takes over the HTTP server's `upgrade` events. A
+ * handshake whose path matches no route is rejected with close code 1002.
+ *
+ * @evidence contracts/common.md#principled-implementation Routes are matched by paths built from the global prefix, the version, the module prefix, the controller path, and the method path, joined and normalized the same way for every combination; the adapter answers upgrade events itself through a `ws` server in no-server mode and removes its listeners when the HTTP server closes.
+ * @evidence contracts/common.md#clear-and-simple-design A class with one static factory, one `close` property, and the private handler; discovery, method checks, termination, and close reasons are module-private functions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The global prefix, versioning options, and module graph are read from `app.config` and `app.container`, which NestJS keeps internal because `INestApplication` has no public accessor for them; this is the limitation of the adapter, not a fixture-specific branch.
+ * @evidence contracts/common.md#meaningful-documentation The comment states when to call it and what happens to an unmatched handshake.
+ * @evidence contracts/portability.md#os-neutral-implementation Diagnostic source URLs are converted by fileURLToPath before path.relative uses native paths; route matching uses HTTP path segments separately from filesystem paths. No filesystem case policy is inferred from the OS.
+ */
 export class WebSocketAdaptor {
+  /**
+   * Creates the adapter for the application: it visits every controller,
+   * validates the WebSocket routes, and starts listening for upgrade events.
+   *
+   * All route errors of the application are collected and thrown together, with
+   * the controller, method, source location, and reasons of each.
+   *
+   * @evidence contracts/common.md#principled-implementation Controller data-method descriptors are checked before any handshake is served, with child properties shadowing inherited methods and accessors never executed, and all defects are reported in one error, so a misconfigured route fails at start and not at the first client; source locations come from `get-function-location`, converted with `fileURLToPath` so a `file:` URL becomes the path on every platform.
+   * @evidence contracts/common.md#clear-and-simple-design One asynchronous factory that awaits the visitor and hands the operator list to the private constructor.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The visitor reports through the same error path for every controller; no controller or route name is special-cased.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the collected error report and the effect on the server.
+   * @evidence contracts/portability.md#os-neutral-implementation Diagnostic source URLs are converted by fileURLToPath before path.relative uses native paths; route matching uses HTTP path segments separately from filesystem paths. No filesystem case policy is inferred from the OS.
+   */
   public static async upgrade(
     app: INestApplication,
   ): Promise<WebSocketAdaptor> {
     return new this(app, await visitApplication(app));
   }
 
+  /**
+   * Stops the adapter: removes its listeners from the HTTP server and closes
+   * the WebSocket server.
+   *
+   * @evidence contracts/common.md#principled-implementation The listeners are removed before the `ws` server closes, so no upgrade event reaches a closing server, and the returned promise resolves when the server has closed.
+   * @evidence contracts/common.md#clear-and-simple-design An arrow property so the same function value can be registered and unregistered as the HTTP server's close listener.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It releases exactly what the adapter registered.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what is released.
+   * @evidence contracts/portability.md#os-neutral-implementation Diagnostic source URLs are converted by fileURLToPath before path.relative uses native paths; route matching uses HTTP path segments separately from filesystem paths. No filesystem case policy is inferred from the OS.
+   */
   public readonly close = async (): Promise<void> =>
     new Promise((resolve) => {
       this.http.off("close", this.close);
@@ -62,25 +105,19 @@ export class WebSocketAdaptor {
           })();
           for (const op of this.operators) {
             const params: Record<string, string> | null = op.parser.test(path);
-            if (params !== null)
-              try {
-                await op.handler({ params, acceptor });
-              } catch (error) {
-                if (
-                  acceptor.state === WebSocketAcceptor.State.OPEN ||
-                  acceptor.state === WebSocketAcceptor.State.ACCEPTING
-                )
-                  await acceptor.reject(
-                    1008,
-                    error instanceof Error
-                      ? JSON.stringify({ ...error })
-                      : "unknown error",
-                  );
-              } finally {
-                return;
-              }
+            if (params === null) continue;
+            try {
+              await op.handler({ params, acceptor });
+            } catch (error) {
+              await terminate({ acceptor, socket: client, error });
+            }
+            return;
           }
-          await acceptor.reject(1002, `WebSocket API not found`);
+          await terminate({
+            acceptor,
+            socket: client,
+            error: new WebSocketRejection(1002, "WebSocket API not found"),
+          });
         },
       ),
     );
@@ -107,10 +144,10 @@ const visitApplication = async (
       return versioning === undefined || versioning.type !== VersioningType.URI
         ? undefined
         : {
+            // as NestJS's RoutePathFactory.getVersionPrefix(): `false` is no
+            // prefix at all, and only an absent one is the default "v"
             prefix:
-              versioning.prefix === undefined || versioning.prefix === false
-                ? "v"
-                : versioning.prefix,
+              versioning.prefix === false ? "" : (versioning.prefix ?? "v"),
             defaultVersion: versioning.defaultVersion,
           };
     })(),
@@ -209,8 +246,7 @@ const visitController = async (props: {
     modulePrefix: props.modulePrefix,
   };
   for (const mk of getOwnPropertyNames(controller.prototype).filter(
-    (key) =>
-      key !== "constructor" && typeof controller.prototype[key] === "function",
+    (key) => key !== "constructor",
   )) {
     const errorMessages: string[] = [];
     visitMethod({
@@ -231,7 +267,9 @@ const visitController = async (props: {
         ...file,
         source: path.relative(
           process.cwd(),
-          file.source.replace("file:///", ""),
+          file.source.startsWith("file:")
+            ? fileURLToPath(file.source)
+            : file.source,
         ),
       });
     }
@@ -282,16 +320,16 @@ const visitMethod = (props: {
       ].join("\n"),
     );
 
-  const versions: string[] = VersioningStrategy.merge(props.config.versioning)([
-    ...(props.controller.versions ?? []),
-    ...VersioningStrategy.cast(
+  const versions: string[] = VersioningStrategy.merge(props.config.versioning)({
+    controller: props.controller.versions,
+    method: VersioningStrategy.cast(
       Reflect.getMetadata(VERSION_METADATA, props.method.value),
     ),
-  ]);
+  });
   for (const v of versions)
     for (const cp of wrapPaths(props.controller.prefixes))
       for (const mp of wrapPaths(route.paths)) {
-        const parser: Path = new Path(
+        const parser: RoutePathMatcher = new RoutePathMatcher(
           "/" +
             [
               props.config.globalPrefix ?? "",
@@ -344,16 +382,21 @@ const visitMethod = (props: {
                 else if (p.category === "driver")
                   args.push(input.acceptor.getDriver());
                 else if (p.category === "header") {
-                  const error: Error | null = p.validate(input.acceptor.header);
-                  if (error !== null) throw error;
-                  args.push(input.acceptor.header);
+                  const result = resolve_request_body(
+                    p.validate,
+                    input.acceptor.header,
+                  );
+                  if (!result.success) throw result.error;
+                  args.push(result.data);
                 } else if (p.category === "param")
                   args.push(p.assert(input.params[p.field]!));
                 else if (p.category === "query") {
+                  // the query is all after the first "?", which it may hold too
+                  const index: number = input.acceptor.path.indexOf("?");
                   const query: any | Error = p.validate(
                     new URLSearchParams(
-                      input.acceptor.path.indexOf("?") !== -1
-                        ? input.acceptor.path.split("?")[1]
+                      index !== -1
+                        ? input.acceptor.path.substring(index + 1)
                         : "",
                     ),
                   );
@@ -361,13 +404,8 @@ const visitMethod = (props: {
                   args.push(query);
                 }
             } catch (exp) {
-              await input.acceptor.reject(
-                1003,
-                exp instanceof Error
-                  ? JSON.stringify({ ...exp })
-                  : "unknown error",
-              );
-              return;
+              // an invalid handshake: rejected before the handler runs
+              throw new WebSocketRejection(1003, exp);
             }
             await props.method.value.call(props.controller.instance, ...args);
           },
@@ -375,16 +413,128 @@ const visitMethod = (props: {
       }
 };
 
+/**
+ * A handshake rejected on purpose, with its close code: 1002 for no route, 1003
+ * for a header, param, or query failing its type.
+ */
+class WebSocketRejection {
+  public constructor(
+    public readonly code: number,
+    public readonly cause: unknown,
+  ) {}
+}
+
+/**
+ * Ends a WebSocket request that failed, so the client always learns it: a
+ * handshake not accepted yet is rejected, 1008 for an error of the route
+ * itself, and an accepted connection is closed with 1011. When tgrid refuses
+ * either, as it does while `accept()` is still running, the socket is closed
+ * directly. Nothing escapes, as the upgrade callback has no one to catch it.
+ */
+const terminate = async (props: {
+  acceptor: WebSocketAcceptor<any, any, any>;
+  socket: WebSocket;
+  error: unknown;
+}): Promise<void> => {
+  const reason: string = closeReason(
+    props.error instanceof WebSocketRejection ? props.error.cause : props.error,
+  );
+  const state: WebSocketAcceptor.State = props.acceptor.state;
+  if (
+    state === WebSocketAcceptor.State.REJECTING ||
+    state === WebSocketAcceptor.State.CLOSING ||
+    state === WebSocketAcceptor.State.CLOSED
+  )
+    return; // the route already ends the connection itself
+  const code: number =
+    state !== WebSocketAcceptor.State.NONE
+      ? 1011
+      : props.error instanceof WebSocketRejection
+        ? props.error.code
+        : 1008;
+  try {
+    if (state === WebSocketAcceptor.State.NONE)
+      return await props.acceptor.reject(code, reason);
+    else if (state === WebSocketAcceptor.State.OPEN)
+      return await props.acceptor.close(code, reason);
+  } catch {}
+  try {
+    props.socket.close(code, reason);
+  } catch {
+    props.socket.terminate();
+  }
+};
+
+/**
+ * The reason a close frame carries: the error's message, cut to the 123 bytes
+ * of UTF-8 a close reason may hold, never inside a character. A longer reason
+ * makes `ws` throw instead of closing, and the client waits forever.
+ *
+ * A validator's `BadRequestException` carries a generic message, so the
+ * property it names is preferred: typia's `reason` from an assertion, or the
+ * first of the `errors` from a validation.
+ */
+const closeReason = (error: unknown): string => {
+  const message: string =
+    invalidProperty(error) ??
+    (error instanceof Error
+      ? error.message
+      : typeof error === "string"
+        ? error
+        : "unknown error");
+  const encoded: Buffer = Buffer.from(message, "utf8");
+  if (encoded.length <= MAX_CLOSE_REASON_BYTES) return message;
+  let end: number = MAX_CLOSE_REASON_BYTES;
+  // back off continuation bytes (10xxxxxx) to a character boundary
+  while (end > 0 && (encoded[end]! & 0xc0) === 0x80) --end;
+  return encoded.subarray(0, end).toString("utf8");
+};
+
+const invalidProperty = (error: unknown): string | null => {
+  if (!(error instanceof HttpException)) return null;
+  const response: unknown = error.getResponse();
+  if (typeof response !== "object" || response === null) return null;
+  const { reason, errors } = response as {
+    reason?: unknown;
+    errors?: unknown;
+  };
+  if (typeof reason === "string") return reason;
+  if (Array.isArray(errors) && errors.length !== 0) {
+    const first: { path?: unknown; expected?: unknown } = errors[0];
+    if (typeof first?.path === "string" && typeof first.expected === "string")
+      return [
+        `invalid type on ${first.path}, expect to be ${first.expected}`,
+        errors.length > 1 ? ` (and ${errors.length - 1} more)` : "",
+      ].join("");
+  }
+  return null;
+};
+
+/**
+ * RFC 6455 §5.5: a control frame's payload is at most 125 bytes, 2 of them the
+ * code.
+ */
+const MAX_CLOSE_REASON_BYTES: number = 123;
+
 const wrapPaths = (value: string[]) => (value.length === 0 ? [""] : value);
 const getOwnPropertyNames = (prototype: any): string[] => {
-  const result: Set<string> = new Set();
-  const iterate = (m: any) => {
-    if (m === null) return;
-    for (const k of Object.getOwnPropertyNames(m)) result.add(k);
-    iterate(Object.getPrototypeOf(m));
-  };
-  iterate(prototype);
-  return Array.from(result);
+  const visited: Set<string> = new Set();
+  const result: string[] = [];
+  for (
+    let current = prototype;
+    current !== null;
+    current = Object.getPrototypeOf(current)
+  )
+    for (const key of Object.getOwnPropertyNames(current)) {
+      if (visited.has(key)) continue;
+      visited.add(key);
+      if (
+        typeof Object.getOwnPropertyDescriptor(current, key)?.value ===
+        "function"
+      )
+        result.push(key);
+    }
+  return result;
 };
 
 interface Entry<T> {
@@ -402,7 +552,7 @@ interface IController {
   modulePrefix: string;
 }
 interface IOperator {
-  parser: Path;
+  parser: RoutePathMatcher;
   handler: (props: {
     params: Record<string, string>;
     acceptor: WebSocketAcceptor<any, any, any>;

package/src/adaptors/internal/RoutePathMatcher.ts

@@ -0,0 +1,91 @@
+import { Token, match, parse } from "path-to-regexp";
+
+/**
+ * A WebSocket route's path, matched as NestJS 11's Express router matches an
+ * HTTP route: path-to-regexp 8's syntax, where `\:` is a literal colon, `*name`
+ * a wildcard, and `{...}` an optional group; find-my-way's (Fastify) literal
+ * colon `::` is read too, as `@nestia/sdk` reads it when it builds the SDK's
+ * URL.
+ *
+ * @internal
+ */
+export class RoutePathMatcher {
+  /** The names of the path's parameters and wildcards, in order. */
+  public readonly params: string[];
+
+  private readonly match_: (
+    path: string,
+  ) => false | { params: Partial<Record<string, string | string[]>> };
+
+  public constructor(private readonly path: string) {
+    const route: string = fromFastifyColons(path);
+    this.params = names(parse(route).tokens);
+    this.match_ = match(route, {
+      decode: (value: string) => {
+        try {
+          return decodeURIComponent(value);
+        } catch {
+          return value;
+        }
+      },
+    });
+  }
+
+  /**
+   * The parameters of a matching request path, or `null`. A wildcard's segments
+   * are joined by `/`, and an optional parameter absent is left out.
+   */
+  public test(path: string): Record<string, string> | null {
+    const matched = this.match_(path);
+    if (matched === false) return null;
+    const output: Record<string, string> = {};
+    for (const [key, value] of Object.entries(matched.params))
+      if (value !== undefined)
+        output[key] = Array.isArray(value) ? value.join("/") : value;
+    return output;
+  }
+
+  public toString(): string {
+    return this.path;
+  }
+}
+
+const names = (tokens: Token[]): string[] =>
+  tokens.flatMap((token) =>
+    token.type === "param" || token.type === "wildcard"
+      ? [token.name]
+      : token.type === "group"
+        ? names(token.tokens)
+        : [],
+  );
+
+/**
+ * A route with find-my-way's (Fastify) literal colon `::` spelled as
+ * path-to-regexp's `\:`. find-my-way reads `::` as a colon in static text
+ * alone: after a parameter it is part of the parameter's name, so it is left as
+ * is there, and path-to-regexp then rejects the route, as no parameter of that
+ * name is what the handler reads.
+ *
+ * @internal
+ */
+const fromFastifyColons = (route: string): string => {
+  let output: string = "";
+  for (let i: number = 0; i < route.length; ) {
+    if (route[i] === "\\") {
+      output += route.slice(i, i + 2);
+      i += 2;
+    } else if (route.startsWith("::", i)) {
+      output += "\\:";
+      i += 2;
+    } else if (route[i] === ":") {
+      const name: string = /^:[A-Za-z0-9_$]*/.exec(route.slice(i))![0];
+      output += name;
+      i += name.length;
+      if (route.startsWith("::", i)) {
+        output += "::";
+        i += 2;
+      }
+    } else output += route[i++];
+  }
+  return output;
+};

package/src/adaptors/internal/external_context.ts

@@ -0,0 +1,81 @@
+import { ContextId, ContextIdFactory, NestContainer } from "@nestjs/core";
+import { ExternalExceptionFilterContext } from "@nestjs/core/exceptions/external-exception-filter-context";
+import { GuardsConsumer, GuardsContextCreator } from "@nestjs/core/guards";
+import { ExternalContextCreator } from "@nestjs/core/helpers/external-context-creator";
+import {
+  InterceptorsConsumer,
+  InterceptorsContextCreator,
+} from "@nestjs/core/interceptors";
+import { PipesConsumer, PipesContextCreator } from "@nestjs/core/pipes";
+import { REQUEST_CONTEXT_ID } from "@nestjs/core/router/request/request-constants";
+
+/**
+ * The creator of NestJS's enhancer pipeline (guards, interceptors, pipes, and
+ * exception filters) for the controllers of one module.
+ *
+ * `ExternalContextCreator` looks the module up among those providing the class,
+ * and a controller is provided by none, so its enhancers would not resolve: the
+ * module is named here instead.
+ *
+ * @internal
+ */
+export const create_external_context_creator = (
+  container: NestContainer,
+  moduleKey: string,
+): ExternalContextCreator => new ControllerContextCreator(container, moduleKey);
+
+class ControllerContextCreator extends ExternalContextCreator {
+  public constructor(
+    private readonly owner: NestContainer,
+    private readonly moduleKey: string,
+  ) {
+    super(
+      new GuardsContextCreator(owner, owner.applicationConfig),
+      new GuardsConsumer(),
+      new InterceptorsContextCreator(owner, owner.applicationConfig),
+      new InterceptorsConsumer(),
+      owner.getModules(),
+      new PipesContextCreator(owner, owner.applicationConfig),
+      new PipesConsumer(),
+      new ExternalExceptionFilterContext(owner, owner.applicationConfig),
+    );
+  }
+
+  public override getContextModuleKey(): string {
+    return this.moduleKey;
+  }
+
+  public override registerRequestProvider<T = any>(
+    request: T,
+    contextId: ContextId,
+  ): void {
+    this.owner.registerRequestProvider(request, contextId);
+  }
+}
+
+/**
+ * The context a request-scoped provider is built in for this request, the one
+ * NestJS's router attaches to it, registering the request as `REQUEST`.
+ *
+ * @internal
+ */
+export const get_request_context_id = (
+  container: NestContainer,
+  request: any,
+  durable: boolean,
+): ContextId => {
+  const contextId: ContextId = ContextIdFactory.getByRequest(request);
+  if (!request[REQUEST_CONTEXT_ID]) {
+    Object.defineProperty(request, REQUEST_CONTEXT_ID, {
+      value: contextId,
+      enumerable: false,
+      writable: false,
+      configurable: false,
+    });
+    container.registerRequestProvider(
+      durable ? contextId.payload : Object.assign(request, contextId.payload),
+      contextId,
+    );
+  }
+  return contextId;
+};

package/src/decorators/DynamicModule.ts

@@ -11,6 +11,11 @@ import { load_controllers } from "./internal/load_controller";
  * controller classes dynamically just by specifying their directory path.
  *
  * @author Jeongho Nam - https://github.com/samchon
+ * @evidence contracts/common.md#principled-implementation The namespace builds a Nest module whose controllers are found on disk at startup instead of listed in code, using the shared loader.
+ * @evidence contracts/common.md#clear-and-simple-design One function that delegates discovery to `load_controllers` and decorates a class with the result.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Paths are caller input, and no controller name is assumed.
+ * @evidence contracts/common.md#meaningful-documentation The comment describes the purpose and the path forms.
+ * @evidence contracts/portability.md#os-neutral-implementation Controller discovery delegates native path handling to SourceFinder and conversion of import paths to file URLs to load_controllers; module metadata contains controller constructors rather than filesystem identities.
  */
 export namespace DynamicModule {
   /**
@@ -23,7 +28,14 @@ export namespace DynamicModule {
    *
    * @param path Path of controllers
    * @param metadata Additional metadata except controllers
+   * @param isTsNode Select TypeScript source files explicitly; otherwise
+   *   compiled JavaScript is tried first, with a source fallback under `ttsx`.
    * @returns Module instance
+   * @evidence contracts/common.md#principled-implementation Controllers are loaded from the paths, given as a path, a list, or include and exclude lists, and then a class decorated with `@Module` and those controllers is returned, so Nest treats the result as an ordinary module.
+   * @evidence contracts/common.md#clear-and-simple-design A short function whose discovery details live in `load_controllers`.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It calls Nest's public `Module` decorator with the metadata; nothing is patched.
+   * @evidence contracts/common.md#meaningful-documentation The comment documents the path forms and the `isTsNode` option.
+   * @evidence contracts/portability.md#os-neutral-implementation Controller discovery delegates native path handling to SourceFinder and conversion of import paths to file URLs to load_controllers; module metadata contains controller constructors rather than filesystem identities.
    */
   export async function mount(
     path: string | string[] | { include: string[]; exclude?: string[] },

package/src/decorators/EncryptedBody.ts

@@ -10,7 +10,7 @@ import type { FastifyRequest } from "fastify";
 
 import { IRequestBodyValidator } from "../options/IRequestBodyValidator";
 import { Singleton } from "../utils/Singleton";
-import { ENCRYPTION_METADATA_KEY } from "./internal/EncryptedConstant";
+import { get_encryption_password } from "./internal/get_encryption_password";
 import { get_text_body } from "./internal/get_text_body";
 import { headers_to_object } from "./internal/headers_to_object";
 import { is_media_type } from "./internal/is_media_type";
@@ -20,22 +20,30 @@ import { validate_request_body } from "./internal/validate_request_body";
  * Encrypted body decorator.
  *
  * `EncryptedBody` is a decorator function getting `application/json` typed data
- * from request body which has been encrypted by AES-128/256 algorithm. Also,
- * `EncryptedBody` validates the request body data type through
- * [typia](https://github.com/samchon/typia) ad the validation speed is maximum
- * 15,000x times faster than `class-validator`.
+ * from request body which has been encrypted by AES-128/192/256 algorithm.
+ * Also, `EncryptedBody` validates the request body data type through
+ * [typia](https://github.com/samchon/typia) using the declared TypeScript
+ * type.
  *
  * For reference, when the request body data is not following the promised type
  * `T`, `BadRequestException` error (status code: 400) would be thrown. Also,
- * `EncryptedRoute` decrypts request body using those options.
+ * This decorator decrypts the request body using these options.
  *
- * - AES-128/256
+ * - AES-128/192/256
  * - CBC mode
  * - PKCS #5 Padding
  * - Base64 Encoding
  *
+ * Successful validator data becomes the decorated argument, including copies
+ * returned by clone validators after decryption and JSON parsing.
+ *
  * @author Jeongho Nam - https://github.com/samchon
  * @returns Parameter decorator
+ * @evidence contracts/common.md#principled-implementation The body must be `text/plain` ciphertext; it is decrypted with the password of the controller or module, the plain text is parsed as JSON and validated by the transformed validator, and a decryption or parse failure becomes a 400 with one fixed message that does not echo the ciphertext and does not tell the two failures apart; a key or initialization vector the cipher itself refuses is the server's configuration, independent of the request, and is thrown as it is.
+ * @evidence contracts/common.md#clear-and-simple-design One parameter decorator composes shared text reading, password lookup and validator resolution; the successfully resolved data becomes the argument without repeating validation or changing decryption error handling.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The algorithm comes from `AesPkcs5` of the fetcher, the same one the client uses, and no key is embedded; a missing password is an error rather than a plain pass-through.
+ * @evidence contracts/common.md#meaningful-documentation The comment describes the protocol and the requirement of a password on the controller or module, and the private decode helper documents why every decryption failure collapses into one response.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Ciphertext parsing, AES decryption and request validation operate on HTTP values, with no native filesystem or subprocess boundary.
  */
 export function EncryptedBody<T>(
   validator?: IRequestBodyValidator<T>,
@@ -52,7 +60,7 @@ export function EncryptedBody<T>(
       throw new BadRequestException(`Request body type is not "text/plain".`);
 
     const param: IEncryptionPassword | IEncryptionPassword.Closure | undefined =
-      Reflect.getMetadata(ENCRYPTION_METADATA_KEY, context.getClass());
+      get_encryption_password(context.getClass());
     if (!param)
       throw new Error(
         "Error on nestia.core.EncryptedBody(): no encryption password is given.",
@@ -70,9 +78,9 @@ export function EncryptedBody<T>(
 
     // PARSE AND VALIDATE DATA
     const data: any = decode(body, password.key, password.iv);
-    const error: Error | null = checker(data);
-    if (error !== null) throw error;
-    return data;
+    const result = checker.resolve(data);
+    if (!result.success) throw result.error;
+    return result.data;
   })();
 }
 
@@ -89,9 +97,13 @@ export function EncryptedBody<T>(
  *
  * Both failure modes must therefore collapse into one indistinguishable
  * `BadRequestException` (identical status, message, and body). Only the
- * downstream type validation of an already-parsed body may report its own
- * distinct error, because reaching it requires plaintext the attacker cannot
- * forge without already knowing it.
+ * downstream type validation of an already-parsed body reports its own distinct
+ * error. AES-CBC provides no authentication; collapsing parse and padding
+ * errors does not establish ciphertext authenticity.
+ *
+ * A key or initialization vector the cipher refuses is thrown as it is. It says
+ * nothing about the body, so it opens no oracle, and it is a defect of the
+ * server's configuration that a 400 would blame on the client.
  *
  * @internal
  */
@@ -99,10 +111,22 @@ const decode = (body: string, key: string, iv: string): unknown => {
   try {
     return JSON.parse(AesPkcs5.decrypt(body, key, iv));
   } catch (exp) {
-    if (exp instanceof Error)
+    // A password the cipher itself refuses is the server's configuration, which
+    // no request body can influence, so it is no oracle and no client's fault.
+    if (exp instanceof Error && PASSWORD_ERRORS.has((exp as any).code))
+      throw exp;
+    else if (exp instanceof Error)
       throw new BadRequestException(
         "Failed to decrypt the request body. Check your body content or encryption password.",
       );
     else throw exp;
   }
 };
+
+/** The error codes of a key or an initialization vector the cipher refuses. */
+const PASSWORD_ERRORS: Set<unknown> = new Set([
+  "ERR_INVALID_ARG_TYPE",
+  "ERR_CRYPTO_INVALID_IV",
+  "ERR_CRYPTO_INVALID_KEYLEN",
+  "ERR_CRYPTO_UNKNOWN_CIPHER",
+]);