@boo-labs/server 0.0.0-stage → 1.0.1

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

@@ -0,0 +1,299 @@
+// @ts-check
+/**
+ * @file CSRF options validation utilities.
+ *
+ * @description Validates CSRF middleware options used by
+ * ServerConfiguration. Enforces the SameSite=None → Secure relationship.
+ *
+ * @module Validation/ServerConfiguration/CSRFOptions
+ */
+
+// ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// » IMPORT LOCAL MODULES
+import Validation from '#shared/outcome/Validation';
+import ServerConfigurationError from '#shared/errors/ServerConfigurationError';
+
+// ━━ CONSTANTS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Valid values for the SameSite cookie attribute.
+ *
+ * @private
+ * @type {readonly string[]}
+ */
+const SAME_SITE_VALUES = Object.freeze(['Strict', 'Lax', 'None']);
+
+// ━━ 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);
+}
+
+/**
+ * Determines whether a value is a non-empty string.
+ *
+ * @private
+ * @param {unknown} value - Value to inspect.
+ * @returns {value is string} `true` if the value is a non-empty string.
+ */
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.length > 0;
+}
+
+/**
+ * Determines whether every item in an array is a non-empty string.
+ *
+ * @private
+ * @param {unknown[]} values - Array of values to inspect.
+ * @returns {boolean} `true` if every item is a non-empty string.
+ */
+function everyNonEmptyString(values) {
+  return values.every(isNonEmptyString);
+}
+
+/**
+ * Validates CSRF 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. `cookieName`, if present, must be a non-empty string.
+ * 4. `headerName`, if present, must be a non-empty string.
+ * 5. `safeMethods`, if present, must be an array of non-empty strings.
+ * 6. `tokenBytes`, if present, must be a positive integer.
+ * 7. `path`, if present, must be a non-empty string.
+ * 8. `domain`, if present, must be a non-empty string.
+ * 9. `secure`, if present, must be a boolean.
+ * 10. `sameSite`, if present, must be `'Strict'`, `'Lax'`, or `'None'`.
+ * 11. `sameSite: 'None'` requires an effective `secure: true`.
+ *
+ * @param {unknown} options - CSRF options to validate.
+ * @returns {Validation} Validation result.
+ * @example
+ * ```js
+ * const validation = validateCSRFOptions({ cookieName: 'csrf' });
+ *
+ * console.log(validation.ok);
+ * // => true
+ * ```
+ *
+ * @example
+ * ```js
+ * const validation = validateCSRFOptions({ tokenBytes: 0 });
+ *
+ * console.log(validation.ok);
+ * // => false
+ * ```
+ */
+export function validateCSRFOptions(options) {
+  if (options === undefined) {
+    return Validation.success();
+  }
+
+  if (!isPlainObject(options)) {
+    return Validation.failure({
+      error: ServerConfigurationError,
+      code: 'INVALID_CSRF_OPTIONS',
+      custom: true,
+      options: { values: { received: typeof options } },
+    });
+  }
+
+  if ('cookieName' in options) {
+    const { cookieName } = options;
+
+    if (typeof cookieName !== 'string') {
+      return Validation.failure({
+        error: ServerConfigurationError,
+        code: 'INVALID_CSRF_COOKIE_NAME_TYPE',
+        custom: true,
+        options: { values: { received: typeof cookieName } },
+      });
+    }
+
+    if (cookieName.length === 0) {
+      return Validation.failure({
+        error: ServerConfigurationError,
+        code: 'INVALID_CSRF_COOKIE_NAME_VALUE',
+        custom: true,
+        options: { details: { cookieName } },
+      });
+    }
+  }
+
+  if ('headerName' in options) {
+    const { headerName } = options;
+
+    if (typeof headerName !== 'string') {
+      return Validation.failure({
+        error: ServerConfigurationError,
+        code: 'INVALID_CSRF_HEADER_NAME_TYPE',
+        custom: true,
+        options: { values: { received: typeof headerName } },
+      });
+    }
+
+    if (headerName.length === 0) {
+      return Validation.failure({
+        error: ServerConfigurationError,
+        code: 'INVALID_CSRF_HEADER_NAME_VALUE',
+        custom: true,
+        options: { details: { headerName } },
+      });
+    }
+  }
+
+  if ('safeMethods' in options) {
+    const { safeMethods } = options;
+
+    if (!Array.isArray(safeMethods)) {
+      return Validation.failure({
+        error: ServerConfigurationError,
+        code: 'INVALID_CSRF_SAFE_METHODS_TYPE',
+        custom: true,
+        options: { values: { received: typeof safeMethods } },
+      });
+    }
+
+    if (!everyNonEmptyString(safeMethods)) {
+      return Validation.failure({
+        error: ServerConfigurationError,
+        code: 'INVALID_CSRF_SAFE_METHODS_ITEM',
+        custom: true,
+        options: { details: { safeMethods } },
+      });
+    }
+  }
+
+  if ('tokenBytes' in options) {
+    const { tokenBytes } = options;
+
+    if (typeof tokenBytes !== 'number') {
+      return Validation.failure({
+        error: ServerConfigurationError,
+        code: 'INVALID_CSRF_TOKEN_BYTES_TYPE',
+        custom: true,
+        options: { values: { received: typeof tokenBytes } },
+      });
+    }
+
+    if (!Number.isInteger(tokenBytes) || tokenBytes <= 0) {
+      return Validation.failure({
+        error: ServerConfigurationError,
+        code: 'INVALID_CSRF_TOKEN_BYTES_RANGE',
+        custom: true,
+        options: { details: { tokenBytes } },
+      });
+    }
+  }
+
+  if ('path' in options) {
+    const { path } = options;
+
+    if (typeof path !== 'string') {
+      return Validation.failure({
+        error: ServerConfigurationError,
+        code: 'INVALID_CSRF_PATH_TYPE',
+        custom: true,
+        options: { values: { received: typeof path } },
+      });
+    }
+
+    if (path.length === 0) {
+      return Validation.failure({
+        error: ServerConfigurationError,
+        code: 'INVALID_CSRF_PATH_VALUE',
+        custom: true,
+        options: { details: { path } },
+      });
+    }
+  }
+
+  if ('domain' in options) {
+    const { domain } = options;
+
+    if (typeof domain !== 'string') {
+      return Validation.failure({
+        error: ServerConfigurationError,
+        code: 'INVALID_CSRF_DOMAIN_TYPE',
+        custom: true,
+        options: { values: { received: typeof domain } },
+      });
+    }
+
+    if (domain.length === 0) {
+      return Validation.failure({
+        error: ServerConfigurationError,
+        code: 'INVALID_CSRF_DOMAIN_VALUE',
+        custom: true,
+        options: { details: { domain } },
+      });
+    }
+  }
+
+  if ('secure' in options) {
+    const { secure } = options;
+
+    if (typeof secure !== 'boolean') {
+      return Validation.failure({
+        error: ServerConfigurationError,
+        code: 'INVALID_CSRF_SECURE_TYPE',
+        custom: true,
+        options: { values: { received: typeof secure } },
+      });
+    }
+  }
+
+  if ('sameSite' in options) {
+    const { sameSite } = options;
+
+    if (sameSite !== undefined && !SAME_SITE_VALUES.includes(String(sameSite))) {
+      return Validation.failure({
+        error: ServerConfigurationError,
+        code: 'INVALID_CSRF_SAME_SITE_VALUE',
+        custom: true,
+        options: { details: { sameSite } },
+      });
+    }
+  }
+
+  // Effective values (after defaults) are used for the cross-field rule.
+  const effectiveSameSite = options.sameSite ?? 'Lax';
+  const effectiveSecure = options.secure ?? true;
+
+  if (effectiveSameSite === 'None' && effectiveSecure === false) {
+    return Validation.failure({
+      error: ServerConfigurationError,
+      code: 'CSRF_NONE_REQUIRES_SECURE',
+      custom: true,
+    });
+  }
+
+  return Validation.success();
+}
+
+/**
+ * Asserts that CSRF options are valid.
+ *
+ * @param {unknown} options - CSRF options to validate.
+ * @throws {ServerConfigurationError} If `options` is not a plain object.
+ * @throws {ServerConfigurationError} If any option is invalid.
+ * @throws {ServerConfigurationError} If `sameSite: 'None'` is used without `secure: true`.
+ * @example
+ * ```js
+ * assertCSRFOptions({ cookieName: 'csrf' });
+ * ```
+ */
+export function assertCSRFOptions(options) {
+  const validation = validateCSRFOptions(options);
+
+  if (!validation.ok) {
+    throw validation.error;
+  }
+}

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

@@ -0,0 +1,204 @@
+// @ts-check
+/**
+ * @file Compress options validation utilities.
+ *
+ * @description Validates compression middleware options used by
+ * ServerConfiguration, including size threshold, compression level, and
+ * compressible media types.
+ *
+ * @module Validation/ServerConfiguration/CompressOptions
+ */
+
+// ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// » IMPORT LOCAL MODULES
+import Validation from '#shared/outcome/Validation';
+import ServerConfigurationError from '#shared/errors/ServerConfigurationError';
+
+// ━━ CONSTANTS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Minimum valid compression level.
+ *
+ * `-1` delegates to the zlib default for the selected algorithm.
+ *
+ * @private
+ * @type {number}
+ */
+const MIN_LEVEL = -1;
+
+/**
+ * Maximum valid compression level.
+ *
+ * Brotli accepts up to `11`; gzip accepts up to `9`. The widest range is
+ * used here so that brotli levels are not rejected.
+ *
+ * @private
+ * @type {number}
+ */
+const MAX_LEVEL = 11;
+
+// ━━ 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);
+}
+
+/**
+ * Determines whether a value is a non-empty string.
+ *
+ * @private
+ * @param {unknown} value - Value to inspect.
+ * @returns {value is string} `true` if the value is a non-empty string.
+ */
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.length > 0;
+}
+
+/**
+ * Determines whether every item in an array is a non-empty string.
+ *
+ * @private
+ * @param {unknown[]} values - Array of values to inspect.
+ * @returns {boolean} `true` if every item is a non-empty string.
+ */
+function everyNonEmptyString(values) {
+  return values.every(isNonEmptyString);
+}
+
+/**
+ * Validates compression 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. `threshold`, if present, must be a non-negative integer.
+ * 4. `level`, if present, must be an integer between `-1` and `11`.
+ * 5. `types`, if present, must be an array of non-empty strings.
+ *
+ * @param {unknown} options - Compression options to validate.
+ * @returns {Validation} Validation result.
+ * @example
+ * ```js
+ * const validation = validateCompressOptions({ threshold: 1024, level: 6 });
+ *
+ * console.log(validation.ok);
+ * // => true
+ * ```
+ *
+ * @example
+ * ```js
+ * const validation = validateCompressOptions({ threshold: -1 });
+ *
+ * console.log(validation.ok);
+ * // => false
+ * ```
+ */
+export function validateCompressOptions(options) {
+  if (options === undefined) {
+    return Validation.success();
+  }
+
+  if (!isPlainObject(options)) {
+    return Validation.failure({
+      error: ServerConfigurationError,
+      code: 'INVALID_COMPRESS_OPTIONS',
+      custom: true,
+      options: { values: { received: typeof options } },
+    });
+  }
+
+  if ('threshold' in options) {
+    const { threshold } = options;
+
+    if (typeof threshold !== 'number') {
+      return Validation.failure({
+        error: ServerConfigurationError,
+        code: 'INVALID_COMPRESS_THRESHOLD_TYPE',
+        custom: true,
+        options: { values: { received: typeof threshold } },
+      });
+    }
+
+    if (!Number.isInteger(threshold) || threshold < 0) {
+      return Validation.failure({
+        error: ServerConfigurationError,
+        code: 'INVALID_COMPRESS_THRESHOLD_RANGE',
+        custom: true,
+        options: { details: { threshold } },
+      });
+    }
+  }
+
+  if ('level' in options) {
+    const { level } = options;
+
+    if (typeof level !== 'number') {
+      return Validation.failure({
+        error: ServerConfigurationError,
+        code: 'INVALID_COMPRESS_LEVEL_TYPE',
+        custom: true,
+        options: { values: { received: typeof level } },
+      });
+    }
+
+    if (!Number.isInteger(level) || level < MIN_LEVEL || level > MAX_LEVEL) {
+      return Validation.failure({
+        error: ServerConfigurationError,
+        code: 'INVALID_COMPRESS_LEVEL_RANGE',
+        custom: true,
+        options: { details: { level } },
+      });
+    }
+  }
+
+  if ('types' in options) {
+    const { types } = options;
+
+    if (!Array.isArray(types)) {
+      return Validation.failure({
+        error: ServerConfigurationError,
+        code: 'INVALID_COMPRESS_TYPES_TYPE',
+        custom: true,
+        options: { values: { received: typeof types } },
+      });
+    }
+
+    if (!everyNonEmptyString(types)) {
+      return Validation.failure({
+        error: ServerConfigurationError,
+        code: 'INVALID_COMPRESS_TYPES_ITEM',
+        custom: true,
+        options: { details: { types } },
+      });
+    }
+  }
+
+  return Validation.success();
+}
+
+/**
+ * Asserts that compression options are valid.
+ *
+ * @param {unknown} options - Compression options to validate.
+ * @throws {ServerConfigurationError} If `options` is not a plain object.
+ * @throws {ServerConfigurationError} If `threshold` is not a non-negative integer.
+ * @throws {ServerConfigurationError} If `level` is not an integer between `-1` and `11`.
+ * @throws {ServerConfigurationError} If `types` is not an array of non-empty strings.
+ * @example
+ * ```js
+ * assertCompressOptions({ threshold: 1024, level: 6 });
+ * ```
+ */
+export function assertCompressOptions(options) {
+  const validation = validateCompressOptions(options);
+
+  if (!validation.ok) {
+    throw validation.error;
+  }
+}

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

@@ -0,0 +1,102 @@
+// @ts-check
+/**
+ * @file Cookie parser options validation utilities.
+ *
+ * @description Validates cookie parser middleware options used by
+ * ServerConfiguration.
+ *
+ * @module Validation/ServerConfiguration/CookieParserOptions
+ */
+
+// ━━ 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 cookie parser 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. `decode`, if present, must be a boolean.
+ *
+ * @param {unknown} options - Cookie parser options to validate.
+ * @returns {Validation} Validation result.
+ * @example
+ * ```js
+ * const validation = validateCookieParserOptions({ decode: true });
+ *
+ * console.log(validation.ok);
+ * // => true
+ * ```
+ *
+ * @example
+ * ```js
+ * const validation = validateCookieParserOptions({ decode: 'yes' });
+ *
+ * console.log(validation.ok);
+ * // => false
+ * ```
+ */
+export function validateCookieParserOptions(options) {
+  if (options === undefined) {
+    return Validation.success();
+  }
+
+  if (!isPlainObject(options)) {
+    return Validation.failure({
+      error: ServerConfigurationError,
+      code: 'INVALID_COOKIE_PARSER_OPTIONS',
+      custom: true,
+      options: { values: { received: typeof options } },
+    });
+  }
+
+  if ('decode' in options) {
+    const { decode } = options;
+
+    if (typeof decode !== 'boolean') {
+      return Validation.failure({
+        error: ServerConfigurationError,
+        code: 'INVALID_COOKIE_PARSER_DECODE_TYPE',
+        custom: true,
+        options: { values: { received: typeof decode } },
+      });
+    }
+  }
+
+  return Validation.success();
+}
+
+/**
+ * Asserts that cookie parser options are valid.
+ *
+ * @param {unknown} options - Cookie parser options to validate.
+ * @throws {ServerConfigurationError} If `options` is not a plain object.
+ * @throws {ServerConfigurationError} If `decode` is not a boolean.
+ * @example
+ * ```js
+ * assertCookieParserOptions({ decode: true });
+ * ```
+ */
+export function assertCookieParserOptions(options) {
+  const validation = validateCookieParserOptions(options);
+
+  if (!validation.ok) {
+    throw validation.error;
+  }
+}