@boo-labs/server 0.0.0-stage → 1.0.0

package/source/shared/validations/ServerConfiguration/RateLimitOptions/index.mjs

@@ -0,0 +1,229 @@
+// @ts-check
+/**
+ * @file Rate limit options validation utilities.
+ *
+ * @description Validates rate limit middleware options used by
+ * ServerConfiguration, including window duration, request budget,
+ * rejection response, and header emission.
+ *
+ * @module Validation/ServerConfiguration/RateLimitOptions
+ */
+
+// ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// » IMPORT LOCAL MODULES
+import Validation from '#shared/outcome/Validation';
+import ServerConfigurationError from '#shared/errors/ServerConfigurationError';
+
+// ━━ CONSTANTS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Minimum valid HTTP status code for a rate-limit rejection.
+ *
+ * @private
+ * @type {number}
+ */
+const MIN_STATUS_CODE = 400;
+
+/**
+ * Maximum valid HTTP status code for a rate-limit rejection.
+ *
+ * @private
+ * @type {number}
+ */
+const MAX_STATUS_CODE = 599;
+
+// ━━ FUNCTIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Determines whether a value is a non-null plain object.
+ *
+ * @private
+ * @param {unknown} value - Value to inspect.
+ * @returns {value is Record<string, unknown>} `true` if the value is a plain object.
+ */
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Validates rate limit options.
+ *
+ * Validation is performed in the following order:
+ *
+ * 1. `options` may be `undefined`, in which case validation succeeds.
+ * 2. `options` must be a plain object.
+ * 3. `windowMs`, if present, must be a number.
+ * 4. `windowMs`, if present, must be a positive integer.
+ * 5. `max`, if present, must be a number.
+ * 6. `max`, if present, must be a positive integer.
+ * 7. `statusCode`, if present, must be a number.
+ * 8. `statusCode`, if present, must be an integer between 400 and 599.
+ * 9. `message`, if present, must be a plain object.
+ * 10. `standardHeaders`, if present, must be a boolean.
+ * 11. `legacyHeaders`, if present, must be a boolean.
+ *
+ * @param {unknown} options - Rate limit options to validate.
+ * @returns {Validation} Validation result.
+ * @example
+ * ```js
+ * const validation = validateRateLimitOptions({ windowMs: 60_000, max: 100 });
+ *
+ * console.log(validation.ok);
+ * // => true
+ * ```
+ *
+ * @example
+ * ```js
+ * const validation = validateRateLimitOptions({ windowMs: -1 });
+ *
+ * console.log(validation.ok);
+ * // => false
+ * ```
+ */
+export function validateRateLimitOptions(options) {
+  if (options === undefined) {
+    return Validation.success();
+  }
+
+  if (!isPlainObject(options)) {
+    return Validation.failure({
+      error: ServerConfigurationError,
+      code: 'INVALID_RATE_LIMIT_OPTIONS',
+      custom: true,
+      options: { values: { received: typeof options } },
+    });
+  }
+
+  if ('windowMs' in options) {
+    const { windowMs } = options;
+
+    if (typeof windowMs !== 'number') {
+      return Validation.failure({
+        error: ServerConfigurationError,
+        code: 'INVALID_RATE_LIMIT_WINDOW_MS_TYPE',
+        custom: true,
+        options: { values: { received: typeof windowMs } },
+      });
+    }
+
+    if (!Number.isInteger(windowMs) || windowMs <= 0) {
+      return Validation.failure({
+        error: ServerConfigurationError,
+        code: 'INVALID_RATE_LIMIT_WINDOW_MS_RANGE',
+        custom: true,
+        options: { details: { windowMs } },
+      });
+    }
+  }
+
+  if ('max' in options) {
+    const { max } = options;
+
+    if (typeof max !== 'number') {
+      return Validation.failure({
+        error: ServerConfigurationError,
+        code: 'INVALID_RATE_LIMIT_MAX_TYPE',
+        custom: true,
+        options: { values: { received: typeof max } },
+      });
+    }
+
+    if (!Number.isInteger(max) || max <= 0) {
+      return Validation.failure({
+        error: ServerConfigurationError,
+        code: 'INVALID_RATE_LIMIT_MAX_RANGE',
+        custom: true,
+        options: { details: { max } },
+      });
+    }
+  }
+
+  if ('statusCode' in options) {
+    const { statusCode } = options;
+
+    if (typeof statusCode !== 'number') {
+      return Validation.failure({
+        error: ServerConfigurationError,
+        code: 'INVALID_RATE_LIMIT_STATUS_CODE_TYPE',
+        custom: true,
+        options: { values: { received: typeof statusCode } },
+      });
+    }
+
+    if (
+      !Number.isInteger(statusCode) ||
+      statusCode < MIN_STATUS_CODE ||
+      statusCode > MAX_STATUS_CODE
+    ) {
+      return Validation.failure({
+        error: ServerConfigurationError,
+        code: 'INVALID_RATE_LIMIT_STATUS_CODE_RANGE',
+        custom: true,
+        options: { details: { statusCode } },
+      });
+    }
+  }
+
+  if ('message' in options) {
+    const { message } = options;
+
+    if (!isPlainObject(message)) {
+      return Validation.failure({
+        error: ServerConfigurationError,
+        code: 'INVALID_RATE_LIMIT_MESSAGE_TYPE',
+        custom: true,
+        options: { values: { received: typeof message } },
+      });
+    }
+  }
+
+  if ('standardHeaders' in options) {
+    const { standardHeaders } = options;
+
+    if (typeof standardHeaders !== 'boolean') {
+      return Validation.failure({
+        error: ServerConfigurationError,
+        code: 'INVALID_RATE_LIMIT_STANDARD_HEADERS_TYPE',
+        custom: true,
+        options: { values: { received: typeof standardHeaders } },
+      });
+    }
+  }
+
+  if ('legacyHeaders' in options) {
+    const { legacyHeaders } = options;
+
+    if (typeof legacyHeaders !== 'boolean') {
+      return Validation.failure({
+        error: ServerConfigurationError,
+        code: 'INVALID_RATE_LIMIT_LEGACY_HEADERS_TYPE',
+        custom: true,
+        options: { values: { received: typeof legacyHeaders } },
+      });
+    }
+  }
+
+  return Validation.success();
+}
+
+/**
+ * Asserts that rate limit options are valid.
+ *
+ * @param {unknown} options - Rate limit options to validate.
+ * @throws {ServerConfigurationError} If `options` is not a plain object.
+ * @throws {ServerConfigurationError} If `windowMs` is not a positive integer.
+ * @throws {ServerConfigurationError} If `max` is not a positive integer.
+ * @throws {ServerConfigurationError} If `statusCode` is not an integer between 400 and 599.
+ * @throws {ServerConfigurationError} If `message` is not a plain object.
+ * @throws {ServerConfigurationError} If `standardHeaders` is not a boolean.
+ * @throws {ServerConfigurationError} If `legacyHeaders` is not a boolean.
+ * @example
+ * ```js
+ * assertRateLimitOptions({ windowMs: 60_000, max: 100 });
+ * ```
+ */
+export function assertRateLimitOptions(options) {
+  const validation = validateRateLimitOptions(options);
+
+  if (!validation.ok) {
+    throw validation.error;
+  }
+}

package/source/shared/validations/ServerConfiguration/RequestOptions/index.mjs

@@ -0,0 +1,132 @@
+// @ts-check
+/**
+ * @file Request options validation utilities.
+ *
+ * @description Validates request options used by ServerConfiguration,
+ * including body limit and proxy trust constraints.
+ *
+ * @module Validation/ServerConfiguration/RequestOptions
+ */
+
+// ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// » IMPORT LOCAL MODULES
+import Validation from '#shared/outcome/Validation';
+import ServerConfigurationError from '#shared/errors/ServerConfigurationError';
+
+// ━━ FUNCTIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Determines whether a value is a non-null plain object.
+ *
+ * @private
+ * @param {unknown} value - Value to inspect.
+ * @returns {value is Record<string, unknown>} `true` if the value is a plain object.
+ */
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Validates request options.
+ *
+ * Validation is performed in the following order:
+ *
+ * 1. `options` may be `undefined`, in which case validation succeeds.
+ * 2. `options` must be a plain object.
+ * 3. `bodyLimit`, if defined, must be a positive safe integer.
+ * 4. `trustProxy`, if defined, must be a boolean or a non-negative integer.
+ *
+ * @param {unknown} options - Request options to validate.
+ * @returns {Validation} Validation result.
+ */
+export function validateRequestOptions(options) {
+  if (options === undefined) {
+    return Validation.success();
+  }
+
+  if (!isPlainObject(options)) {
+    return Validation.failure({
+      error: ServerConfigurationError,
+      code: 'INVALID_REQUEST_OPTIONS',
+      custom: true,
+      options: { values: { received: typeof options } },
+    });
+  }
+
+  if ('bodyLimit' in options) {
+    const { bodyLimit } = options;
+
+    if (bodyLimit !== undefined) {
+      if (typeof bodyLimit !== 'number') {
+        return Validation.failure({
+          error: ServerConfigurationError,
+          code: 'INVALID_BODY_LIMIT_TYPE',
+          custom: true,
+          options: { values: { received: typeof bodyLimit } },
+        });
+      }
+
+      if (!Number.isSafeInteger(bodyLimit) || bodyLimit <= 0) {
+        return Validation.failure({
+          error: ServerConfigurationError,
+          code: 'INVALID_BODY_LIMIT_RANGE',
+          custom: true,
+          options: { details: { bodyLimit } },
+        });
+      }
+    }
+  }
+
+  if ('trustProxy' in options) {
+    const { trustProxy } = options;
+
+    if (trustProxy !== undefined) {
+      const isBoolean = typeof trustProxy === 'boolean';
+      const isNumber = typeof trustProxy === 'number';
+
+      if (!isBoolean && !isNumber) {
+        return Validation.failure({
+          error: ServerConfigurationError,
+          code: 'INVALID_TRUST_PROXY_TYPE',
+          custom: true,
+          options: { values: { received: typeof trustProxy } },
+        });
+      }
+
+      if (isNumber && (!Number.isInteger(trustProxy) || trustProxy < 0)) {
+        return Validation.failure({
+          error: ServerConfigurationError,
+          code: 'INVALID_TRUST_PROXY_RANGE',
+          custom: true,
+          options: { details: { trustProxy } },
+        });
+      }
+    }
+  }
+
+  return Validation.success();
+}
+
+/**
+ * Asserts that request options are valid.
+ *
+ * @param {unknown} options - Request options to validate.
+ * @throws {ServerConfigurationError} If `options` is not a plain object.
+ * @throws {ServerConfigurationError} If `bodyLimit` is defined and is not a number.
+ * @throws {ServerConfigurationError} If `bodyLimit` is defined and is not a positive safe integer.
+ * @throws {ServerConfigurationError} If `trustProxy` is defined and is not a boolean or number.
+ * @throws {ServerConfigurationError} If numeric `trustProxy` is defined and is negative or not an integer.
+ * @example
+ * ```js
+ * assertRequestOptions({
+ *   bodyLimit: 10 * 1024 * 1024,
+ *   trustProxy: true,
+ * });
+ * ```
+ */
+export function assertRequestOptions(options) {
+  const validation = validateRequestOptions(options);
+
+  if (!validation.ok) {
+    throw validation.error;
+  }
+}

package/source/shared/validations/ServerConfiguration/ResponseOptions/index.mjs

@@ -0,0 +1,122 @@
+// @ts-check
+/**
+ * @file Response options validation utilities.
+ *
+ * @description Validates response options used by ServerConfiguration,
+ * including ETag generation and default charset settings.
+ *
+ * @module Validation/ServerConfiguration/ResponseOptions
+ */
+
+// ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// » IMPORT LOCAL MODULES
+import Validation from '#shared/outcome/Validation';
+import ServerConfigurationError from '#shared/errors/ServerConfigurationError';
+
+// ━━ FUNCTIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Determines whether a value is a non-null plain object.
+ *
+ * @private
+ * @param {unknown} value - Value to inspect.
+ * @returns {value is Record<string, unknown>} `true` if the value is a plain object.
+ */
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Validates response options.
+ *
+ * Validation is performed in the following order:
+ *
+ * 1. `options` may be `undefined`, in which case validation succeeds.
+ * 2. `options` must be a plain object.
+ * 3. `etag`, if defined, must be a boolean.
+ * 4. `defaultCharset`, if defined, must be a non-empty string.
+ *
+ * @param {unknown} options - Response options to validate.
+ * @returns {Validation} Validation result.
+ * @example
+ * ```js
+ * const validation = validateResponseOptions({ etag: true });
+ *
+ * console.log(validation.ok);
+ * // => true
+ * ```
+ */
+export function validateResponseOptions(options) {
+  if (options === undefined) {
+    return Validation.success();
+  }
+
+  if (!isPlainObject(options)) {
+    return Validation.failure({
+      error: ServerConfigurationError,
+      code: 'INVALID_RESPONSE_OPTIONS',
+      custom: true,
+      options: { values: { received: typeof options } },
+    });
+  }
+
+  if ('etag' in options) {
+    const { etag } = options;
+
+    if (etag !== undefined) {
+      if (typeof etag !== 'boolean') {
+        return Validation.failure({
+          error: ServerConfigurationError,
+          code: 'INVALID_ETAG_TYPE',
+          custom: true,
+          options: { values: { received: typeof etag } },
+        });
+      }
+    }
+  }
+
+  if ('defaultCharset' in options) {
+    const { defaultCharset } = options;
+
+    if (defaultCharset !== undefined) {
+      if (typeof defaultCharset !== 'string') {
+        return Validation.failure({
+          error: ServerConfigurationError,
+          code: 'INVALID_DEFAULT_CHARSET_TYPE',
+          custom: true,
+          options: { values: { received: typeof defaultCharset } },
+        });
+      }
+
+      if (defaultCharset.trim().length === 0) {
+        return Validation.failure({
+          error: ServerConfigurationError,
+          code: 'INVALID_DEFAULT_CHARSET_VALUE',
+          custom: true,
+          options: { details: { defaultCharset } },
+        });
+      }
+    }
+  }
+
+  return Validation.success();
+}
+
+/**
+ * Asserts that response options are valid.
+ *
+ * @param {unknown} options - Response options to validate.
+ * @throws {ServerConfigurationError} If `options` is not a plain object.
+ * @throws {ServerConfigurationError} If `etag` is defined and is not a boolean.
+ * @throws {ServerConfigurationError} If `defaultCharset` is defined and is not a string.
+ * @throws {ServerConfigurationError} If `defaultCharset` is defined and is an empty string.
+ * @example
+ * ```js
+ * assertResponseOptions({ etag: true, defaultCharset: 'utf-8' });
+ * ```
+ */
+export function assertResponseOptions(options) {
+  const validation = validateResponseOptions(options);
+  if (!validation.ok) {
+    throw validation.error;
+  }
+}

package/source/shared/validations/ServerConfiguration/SecurityHeadersOptions/index.mjs

@@ -0,0 +1,137 @@
+// @ts-check
+/**
+ * @file Security headers options validation utilities.
+ *
+ * @description Validates security headers middleware options used by
+ * ServerConfiguration. Every recognized security header option must be a
+ * string or `false`.
+ *
+ * @module Validation/ServerConfiguration/SecurityHeadersOptions
+ */
+
+// ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// » IMPORT LOCAL MODULES
+import Validation from '#shared/outcome/Validation';
+import ServerConfigurationError from '#shared/errors/ServerConfigurationError';
+
+// ━━ CONSTANTS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Property names recognized as security header options.
+ *
+ * @private
+ * @type {readonly string[]}
+ */
+const SECURITY_HEADER_KEYS = Object.freeze([
+  'contentSecurityPolicy',
+  'crossOriginEmbedderPolicy',
+  'crossOriginOpenerPolicy',
+  'crossOriginResourcePolicy',
+  'originAgentCluster',
+  'permissionsPolicy',
+  'referrerPolicy',
+  'strictTransportSecurity',
+  'xContentTypeOptions',
+  'xDnsPrefetchControl',
+  'xDownloadOptions',
+  'xFrameOptions',
+  'xPermittedCrossDomainPolicies',
+  'xXssProtection',
+]);
+
+// ━━ FUNCTIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Determines whether a value is a non-null plain object.
+ *
+ * @private
+ * @param {unknown} value - Value to inspect.
+ * @returns {value is Record<string, unknown>} `true` if the value is a plain object.
+ */
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Validates security headers options.
+ *
+ * Validation is performed in the following order:
+ *
+ * 1. `options` may be `undefined`, in which case validation succeeds.
+ * 2. `options` must be a plain object.
+ * 3. Every recognized security header option present in `options` must be a
+ * string or `false`.
+ *
+ * Unknown properties are ignored.
+ *
+ * @param {unknown} options - Security headers options to validate.
+ * @returns {Validation} Validation result.
+ * @example
+ * ```js
+ * const validation = validateSecurityHeadersOptions({ xFrameOptions: 'DENY' });
+ *
+ * console.log(validation.ok);
+ * // => true
+ * ```
+ *
+ * @example
+ * ```js
+ * const validation = validateSecurityHeadersOptions({ xFrameOptions: 123 });
+ *
+ * console.log(validation.ok);
+ * // => false
+ * ```
+ */
+export function validateSecurityHeadersOptions(options) {
+  if (options === undefined) {
+    return Validation.success();
+  }
+
+  if (!isPlainObject(options)) {
+    return Validation.failure({
+      error: ServerConfigurationError,
+      code: 'INVALID_SECURITY_HEADERS_OPTIONS',
+      custom: true,
+      options: { values: { received: typeof options } },
+    });
+  }
+
+  for (const key of SECURITY_HEADER_KEYS) {
+    if (!(key in options)) {
+      continue;
+    }
+
+    const value = options[key];
+
+    if (typeof value !== 'string' && value !== false) {
+      return Validation.failure({
+        error: ServerConfigurationError,
+        code: 'INVALID_SECURITY_HEADERS_OPTION_TYPE',
+        custom: true,
+        options: {
+          values: { key, received: typeof value },
+          details: { key, value },
+        },
+      });
+    }
+  }
+
+  return Validation.success();
+}
+
+/**
+ * Asserts that security headers options are valid.
+ *
+ * @param {unknown} options - Security headers options to validate.
+ * @throws {ServerConfigurationError} If `options` is not a plain object.
+ * @throws {ServerConfigurationError} If a recognized security header option is not a string or `false`.
+ * @example
+ * ```js
+ * assertSecurityHeadersOptions({ xFrameOptions: 'DENY' });
+ * ```
+ */
+export function assertSecurityHeadersOptions(options) {
+  const validation = validateSecurityHeadersOptions(options);
+
+  if (!validation.ok) {
+    throw validation.error;
+  }
+}