@boo-labs/server 0.0.0-stage → 1.0.0

package/source/application/configurations/ServerConfiguration/Options/CORSOptions/CORSOptionsValue.mjs

@@ -0,0 +1,158 @@
+// @ts-check
+/**
+ * @file Defines the CORSOptionsValue value object.
+ *
+ * @description Normalizes and validates CORS middleware configuration used
+ * by CORSMiddleware. When options are omitted, the value is undefined.
+ *
+ * @module CORSOptionsValue
+ */
+
+// ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// » IMPORT LOCAL MODULES
+import { assertCORSOptions } from '#shared/validations/ServerConfiguration/CORSOptions';
+
+// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Domain error thrown by server configuration validation.
+ *
+ * @typedef {import('#shared/errors/ServerConfigurationError').default} ServerConfigurationError
+ */
+
+/**
+ * Represents the CORS options accepted by the server configuration.
+ *
+ * @typedef  {object}               CORSOptionsInput
+ * @property {true|string|string[]} [origin]               - Allowed origin(s). Defaults to `'*'`.
+ * @property {string[]}             [methods]              - Allowed HTTP methods for preflight responses. Defaults to a standard set.
+ * @property {string[]}             [allowedHeaders]       - Headers the client is allowed to send. When omitted, the value of Access-Control-Request-Headers is reflected.
+ * @property {string[]}             [exposedHeaders]       - Headers the client is allowed to read from the response.
+ * @property {boolean}              [credentials]          - Whether the response may include credentials. Defaults to `false`.
+ * @property {number}               [maxAge]               - How long (in seconds) the preflight response may be cached.
+ * @property {boolean}              [preflightContinue]    - Whether to call `next()` on successful preflight instead of ending the response. Defaults to `false`.
+ * @property {number}               [optionsSuccessStatus] - Status code used for successful preflight responses. Defaults to `204`.
+ */
+
+/**
+ * Represents the normalized CORS options.
+ *
+ * @typedef  {object}                       CORSOptionsData
+ * @property {true|string|string[]}         origin               - Allowed origin(s).
+ * @property {Readonly<string[]>}           methods              - Allowed HTTP methods for preflight responses.
+ * @property {Readonly<string[]>|undefined} allowedHeaders       - Headers the client is allowed to send, or `undefined` to reflect the request headers.
+ * @property {Readonly<string[]>|undefined} exposedHeaders       - Headers the client is allowed to read from the response.
+ * @property {boolean}                      credentials          - Whether the response may include credentials.
+ * @property {number|undefined}             maxAge               - How long (in seconds) the preflight response may be cached.
+ * @property {boolean}                      preflightContinue    - Whether to call `next()` on successful preflight instead of ending the response.
+ * @property {number}                       optionsSuccessStatus - Status code used for successful preflight responses.
+ */
+
+// ━━ CONSTANTS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Default allowed origin.
+ *
+ * @type {true|string|string[]}
+ */
+const DEFAULT_ORIGIN = '*';
+
+/**
+ * Default allowed HTTP methods for preflight responses.
+ *
+ * @type {readonly string[]}
+ */
+const DEFAULT_METHODS = Object.freeze(['GET', 'HEAD', 'PUT', 'PATCH', 'POST', 'DELETE']);
+
+/**
+ * Default credentials behavior.
+ *
+ * @type {boolean}
+ */
+const DEFAULT_CREDENTIALS = false;
+
+/**
+ * Default preflight continuation behavior.
+ *
+ * @type {boolean}
+ */
+const DEFAULT_PREFLIGHT_CONTINUE = false;
+
+/**
+ * Default status code used for successful preflight responses.
+ *
+ * @type {number}
+ */
+const DEFAULT_OPTIONS_SUCCESS_STATUS = 204;
+
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Immutable value object representing normalized CORS middleware options.
+ *
+ * @classdesc Validates and normalizes CORS middleware options.
+ */
+class CORSOptionsValue {
+  /**
+   * The normalized CORS options.
+   *
+   * @type {Readonly<CORSOptionsData>|undefined}
+   */
+  #value;
+
+  /**
+   * Creates a new {@link CORSOptionsValue}.
+   *
+   * @param {CORSOptionsInput} [options] - The CORS middleware options.
+   * @throws {ServerConfigurationError} If `options` is invalid.
+   * @example
+   * ```js
+   * const options = new CORSOptionsValue({ origin: true, credentials: true });
+   *
+   * options.value;
+   * // => {
+   * //   origin: true,
+   * //   methods: ['GET', 'HEAD', 'PUT', 'PATCH', 'POST', 'DELETE'],
+   * //   allowedHeaders: undefined,
+   * //   exposedHeaders: undefined,
+   * //   credentials: true,
+   * //   maxAge: undefined,
+   * //   preflightContinue: false,
+   * //   optionsSuccessStatus: 204,
+   * // }
+   * ```
+   */
+  constructor(options) {
+    assertCORSOptions(options);
+
+    this.#value =
+      options === undefined
+        ? options
+        : Object.freeze({
+            origin: options.origin ?? DEFAULT_ORIGIN,
+            methods: Object.freeze([...(options.methods ?? DEFAULT_METHODS)]),
+            allowedHeaders:
+              options.allowedHeaders === undefined
+                ? undefined
+                : Object.freeze([...options.allowedHeaders]),
+            exposedHeaders:
+              options.exposedHeaders === undefined
+                ? undefined
+                : Object.freeze([...options.exposedHeaders]),
+            credentials: options.credentials ?? DEFAULT_CREDENTIALS,
+            maxAge: options.maxAge,
+            preflightContinue: options.preflightContinue ?? DEFAULT_PREFLIGHT_CONTINUE,
+            optionsSuccessStatus: options.optionsSuccessStatus ?? DEFAULT_OPTIONS_SUCCESS_STATUS,
+          });
+  }
+
+  /**
+   * The normalized CORS options.
+   *
+   * @readonly
+   * @type {Readonly<CORSOptionsData>|undefined}
+   */
+  get value() {
+    return this.#value;
+  }
+}
+
+// ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+export default CORSOptionsValue;

package/source/application/configurations/ServerConfiguration/Options/CORSOptions/index.mjs

@@ -0,0 +1,87 @@
+// @ts-check
+/**
+ * @file Defines the CORSOptions middleware configuration option.
+ *
+ * @description CORSOptions wraps a normalized CORSOptionsValue into the
+ * middleware configuration option hierarchy.
+ *
+ * @module CORSOptions
+ */
+
+// ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// » IMPORT LOCAL MODULES
+import MiddlewareOption from '../MiddlewareOption.mjs';
+import CORSOptionsValue from './CORSOptionsValue.mjs';
+
+// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Represents the CORS options accepted by the server configuration.
+ *
+ * @typedef {import('./CORSOptionsValue.mjs').CORSOptionsInput} CORSOptionsInput
+ */
+
+/**
+ * Represents the normalized CORS options.
+ *
+ * @typedef {import('./CORSOptionsValue.mjs').CORSOptionsData} CORSOptionsData
+ */
+
+/**
+ * Represents one middleware configuration consumed by the exchange layer builder.
+ *
+ * @typedef {import('../MiddlewareOption.mjs').MiddlewareConfiguration} MiddlewareConfiguration
+ */
+
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Middleware configuration option wrapping a normalized CORS configuration.
+ *
+ * @augments {MiddlewareOption<CORSOptionsData|undefined>}
+ */
+class CORSOptions extends MiddlewareOption {
+  /**
+   * Creates a new {@link CORSOptions}.
+   *
+   * @param {CORSOptionsInput} [options] - The CORS middleware options.
+   * @example
+   * ```js
+   * const CORSOptions = new CORSOptions({
+   *   origin: true,
+   *   methods: ['GET', 'HEAD', 'PUT', 'PATCH', 'POST', 'DELETE'],
+   *   credentials: true,
+   *   maxAge: 86400,
+   *   preflightContinue: false,
+   *   optionsSuccessStatus: 204,
+   * });
+   * ```
+   */
+  constructor(options) {
+    super('cors', new CORSOptionsValue(options));
+  }
+
+  /**
+   * Composes the CORS middleware configuration consumed by the exchange
+   * layer builder.
+   *
+   * CORS is a cross-cutting concern applied to every request regardless of
+   * pathname or method, so both `pathnamePattern` and `method` are
+   * `undefined`.
+   *
+   * @returns {MiddlewareConfiguration} The composed middleware configuration.
+   * @example
+   * ```js
+   * const configuration = CORSOptions.compose();
+   * ```
+   */
+  compose() {
+    return {
+      name: this.name,
+      options: this.value,
+      pathnamePattern: undefined,
+      method: undefined,
+    };
+  }
+}
+
+// ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+export default CORSOptions;

package/source/application/configurations/ServerConfiguration/Options/CSRFOptions/CSRFOptionsValue.mjs

@@ -0,0 +1,178 @@
+// @ts-check
+/**
+ * @file Defines the CSRFOptionsValue value object.
+ *
+ * @description Normalizes and validates CSRF middleware configuration used
+ * by CsrfMiddleware. When options are omitted, the value is undefined and the
+ * middleware is not registered.
+ *
+ * @module CSRFOptionsValue
+ */
+
+// ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// » IMPORT LOCAL MODULES
+import { assertCSRFOptions } from '#shared/validations/ServerConfiguration/CSRFOptions';
+
+// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Domain error thrown by server configuration validation.
+ *
+ * @typedef {import('#shared/errors/ServerConfigurationError').default} ServerConfigurationError
+ */
+
+/**
+ * Represents the CSRF options accepted by the server configuration.
+ *
+ * @typedef  {object}                CSRFOptionsInput
+ * @property {string}                [cookieName]     - Name of the CSRF cookie.
+ * @property {string}                [headerName]     - Name of the request header that must carry the token.
+ * @property {string[]}              [safeMethods]    - HTTP methods that skip CSRF validation.
+ * @property {number}                [tokenBytes]     - Number of random bytes used to generate the token.
+ * @property {string}                [path]           - Cookie Path attribute.
+ * @property {string}                [domain]         - Cookie Domain attribute.
+ * @property {boolean}               [secure]         - Whether the cookie is marked Secure.
+ * @property {'Strict'|'Lax'|'None'} [sameSite]       - Cookie SameSite attribute.
+ */
+
+/**
+ * Represents the normalized CSRF options.
+ *
+ * @typedef  {object}                CSRFOptionsData
+ * @property {string}                cookieName      - Name of the CSRF cookie.
+ * @property {string}                headerName      - Name of the request header that must carry the token.
+ * @property {Readonly<string[]>}    safeMethods     - HTTP methods that skip CSRF validation.
+ * @property {number}                tokenBytes      - Number of random bytes used to generate the token.
+ * @property {string}                path            - Cookie Path attribute.
+ * @property {string|undefined}      domain          - Cookie Domain attribute.
+ * @property {boolean}               secure          - Whether the cookie is marked Secure.
+ * @property {'Strict'|'Lax'|'None'} sameSite        - Cookie SameSite attribute.
+ */
+
+// ━━ CONSTANTS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Default CSRF cookie name.
+ *
+ * @type {string}
+ */
+const DEFAULT_COOKIE_NAME = 'csrf-token';
+
+/**
+ * Default request header name.
+ *
+ * @type {string}
+ */
+const DEFAULT_HEADER_NAME = 'x-csrf-token';
+
+/**
+ * Default safe HTTP methods.
+ *
+ * @type {readonly string[]}
+ */
+const DEFAULT_SAFE_METHODS = Object.freeze(['GET', 'HEAD', 'OPTIONS']);
+
+/**
+ * Default number of random bytes used to generate the token.
+ *
+ * @type {number}
+ */
+const DEFAULT_TOKEN_BYTES = 32;
+
+/**
+ * Default cookie path attribute.
+ *
+ * @type {string}
+ */
+const DEFAULT_PATH = '/';
+
+/**
+ * Default Secure attribute.
+ *
+ * @type {boolean}
+ */
+const DEFAULT_SECURE = true;
+
+/**
+ * Default SameSite attribute.
+ *
+ * @type {'Strict'|'Lax'|'None'}
+ */
+const DEFAULT_SAME_SITE = 'Lax';
+
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Immutable value object representing normalized CSRF middleware options.
+ *
+ * @classdesc Validates and normalizes CSRF middleware options. When options
+ * are provided, defaults are applied for any omitted property. When options
+ * are omitted, the value is undefined.
+ *
+ * @example
+ * ```js
+ * const options = new CSRFOptionsValue({ cookieName: 'csrf' });
+ *
+ * options.value;
+ * // => {
+ * //   cookieName: 'csrf',
+ * //   headerName: 'x-csrf-token',
+ * //   safeMethods: ['GET', 'HEAD', 'OPTIONS'],
+ * //   tokenBytes: 32,
+ * //   path: '/',
+ * //   domain: undefined,
+ * //   secure: true,
+ * //   sameSite: 'Lax',
+ * // }
+ * ```
+ *
+ * @example
+ * ```js
+ * const options = new CSRFOptionsValue();
+ *
+ * options.value;
+ * // => undefined
+ * ```
+ */
+class CSRFOptionsValue {
+  /**
+   * The normalized CSRF options.
+   *
+   * @type {Readonly<CSRFOptionsData>|undefined}
+   */
+  #value;
+
+  /**
+   * Creates a new {@link CSRFOptionsValue}.
+   *
+   * @param {CSRFOptionsInput} [options] - The CSRF middleware options.
+   * @throws {ServerConfigurationError} If `options` is invalid.
+   */
+  constructor(options) {
+    assertCSRFOptions(options);
+
+    this.#value =
+      options === undefined
+        ? options
+        : Object.freeze({
+            cookieName: options.cookieName ?? DEFAULT_COOKIE_NAME,
+            headerName: options.headerName ?? DEFAULT_HEADER_NAME,
+            safeMethods: Object.freeze([...(options.safeMethods ?? DEFAULT_SAFE_METHODS)]),
+            tokenBytes: options.tokenBytes ?? DEFAULT_TOKEN_BYTES,
+            path: options.path ?? DEFAULT_PATH,
+            domain: options.domain,
+            secure: options.secure ?? DEFAULT_SECURE,
+            sameSite: options.sameSite ?? DEFAULT_SAME_SITE,
+          });
+  }
+
+  /**
+   * The normalized CSRF options.
+   *
+   * @readonly
+   * @type {Readonly<CSRFOptionsData>|undefined}
+   */
+  get value() {
+    return this.#value;
+  }
+}
+
+// ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+export default CSRFOptionsValue;

package/source/application/configurations/ServerConfiguration/Options/CSRFOptions/index.mjs

@@ -0,0 +1,80 @@
+// @ts-check
+/**
+ * @file Defines the CSRFOptions middleware configuration option.
+ *
+ * @description CSRFOptions wraps a normalized CSRFOptionsValue into the
+ * middleware configuration option hierarchy.
+ *
+ * @module CSRFOptions
+ */
+
+// ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// » IMPORT LOCAL MODULES
+import MiddlewareOption from '../MiddlewareOption.mjs';
+import CSRFOptionsValue from './CSRFOptionsValue.mjs';
+
+// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Represents the CSRF options accepted by the server configuration.
+ *
+ * @typedef {import('./CSRFOptionsValue.mjs').CSRFOptionsInput} CSRFOptionsInput
+ */
+
+/**
+ * Represents the normalized CSRF options.
+ *
+ * @typedef {import('./CSRFOptionsValue.mjs').CSRFOptionsData} CSRFOptionsData
+ */
+
+/**
+ * Represents one middleware configuration consumed by the exchange layer builder.
+ *
+ * @typedef {import('../MiddlewareOption.mjs').MiddlewareConfiguration} MiddlewareConfiguration
+ */
+
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Middleware configuration option wrapping a normalized CSRF configuration.
+ *
+ * @augments {MiddlewareOption<CSRFOptionsData|undefined>}
+ */
+class CSRFOptions extends MiddlewareOption {
+  /**
+   * Creates a new {@link CSRFOptions}.
+   *
+   * @param {CSRFOptionsInput} [options] - The CSRF middleware options.
+   * @example
+   * ```js
+   * const CSRFOptions = new CSRFOptions({ cookieName: 'csrf' });
+   * ```
+   */
+  constructor(options) {
+    super('csrf', new CSRFOptionsValue(options));
+  }
+
+  /**
+   * Composes the CSRF middleware configuration consumed by the exchange
+   * layer builder.
+   *
+   * CSRF protection is a cross-cutting concern applied to every request
+   * regardless of pathname or method, so both `pathnamePattern` and `method`
+   * are `undefined`.
+   *
+   * @returns {MiddlewareConfiguration} The composed middleware configuration.
+   * @example
+   * ```js
+   * const configuration = CSRFOptions.compose();
+   * ```
+   */
+  compose() {
+    return {
+      name: this.name,
+      options: this.value,
+      pathnamePattern: undefined,
+      method: undefined,
+    };
+  }
+}
+
+// ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+export default CSRFOptions;

package/source/application/configurations/ServerConfiguration/Options/CompressOptions/CompressOptionsValue.mjs

@@ -0,0 +1,126 @@
+// @ts-check
+/**
+ * @file Defines the CompressOptionsValue value object.
+ *
+ * @description Normalizes and validates compression middleware configuration
+ * used by CompressMiddleware. When options are omitted, the value is
+ * undefined and the middleware is not registered.
+ *
+ * @module CompressOptionsValue
+ */
+
+// ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// » IMPORT LOCAL MODULES
+import { assertCompressOptions } from '#shared/validations/ServerConfiguration/CompressOptions';
+
+// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Domain error thrown by server configuration validation.
+ *
+ * @typedef {import('#shared/errors/ServerConfigurationError').default} ServerConfigurationError
+ */
+
+/**
+ * Represents the compression options accepted by the server configuration.
+ *
+ * @typedef  {object}   CompressOptionsInput
+ * @property {number}   [threshold]          - Minimum body size in bytes required to compress. Use `0` to compress any non-empty body.
+ * @property {number}   [level]              - Compression level passed to the underlying zlib implementation.
+ * @property {string[]} [types]              - Compressible media types. When omitted, the default allow-list is used.
+ */
+
+/**
+ * Represents the normalized compression options.
+ *
+ * @typedef  {object}                       CompressOptionsData
+ * @property {number}                       threshold           - Minimum body size in bytes required to compress. Use `0` to compress any non-empty body.
+ * @property {number}                       level               - Compression level passed to the underlying zlib implementation.
+ * @property {Readonly<string[]>|undefined} types               - Compressible media types. When `undefined`, the default allow-list is used.
+ */
+
+// ━━ CONSTANTS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Default minimum body size in bytes required to compress.
+ *
+ * @type {number}
+ */
+const DEFAULT_THRESHOLD = 1024;
+
+/**
+ * Default compression level.
+ *
+ * `-1` delegates to the zlib default for the selected algorithm.
+ *
+ * @type {number}
+ */
+const DEFAULT_LEVEL = -1;
+
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Immutable value object representing normalized compression middleware
+ * options.
+ *
+ * @classdesc Validates and normalizes compression middleware options. When
+ * options are provided, defaults are applied for any omitted property. When
+ * options are omitted, the value is undefined.
+ *
+ * @example
+ * ```js
+ * const options = new CompressOptionsValue({ threshold: 2048, level: 6 });
+ *
+ * options.value;
+ * // => {
+ * //   threshold: 2048,
+ * //   level: 6,
+ * //   types: undefined,
+ * // }
+ * ```
+ *
+ * @example
+ * ```js
+ * const options = new CompressOptionsValue();
+ *
+ * options.value;
+ * // => undefined
+ * ```
+ */
+class CompressOptionsValue {
+  /**
+   * The normalized compression options.
+   *
+   * @type {Readonly<CompressOptionsData>|undefined}
+   */
+  #value;
+
+  /**
+   * Creates a new {@link CompressOptionsValue}.
+   *
+   * @param {CompressOptionsInput} [options] - The compression middleware options.
+   * @throws {ServerConfigurationError} If `options` is invalid.
+   */
+  constructor(options) {
+    assertCompressOptions(options);
+
+    this.#value =
+      options === undefined
+        ? options
+        : Object.freeze({
+            threshold: options.threshold ?? DEFAULT_THRESHOLD,
+            level: options.level ?? DEFAULT_LEVEL,
+            types: options.types === undefined ? undefined : Object.freeze([...options.types]),
+          });
+  }
+
+  /**
+   * The normalized compression options.
+   *
+   * @readonly
+   * @type {Readonly<CompressOptionsData>|undefined}
+   */
+  get value() {
+    return this.#value;
+  }
+}
+
+// ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+export default CompressOptionsValue;