@cyanheads/mcp-ts-core 0.13.6 → 0.13.8

package/dist/utils/security/sanitization.d.ts

@@ -4,9 +4,9 @@
  * and numbers, as well as redacting sensitive fields from data intended for logging.
  *
  * Several methods (`sanitizeHtml`, `sanitizeString`, `sanitizeUrl`, `sanitizeNumber`) are
- * **async** because they lazy-load optional peer dependencies (`sanitize-html`, `validator`)
- * on first use. If a required peer dependency is not installed, these methods throw a
- * `McpError` with `JsonRpcErrorCode.ConfigurationError`.
+ * **async**. HTML handling lazy-loads the optional `sanitize-html` peer on first use and throws
+ * a `McpError` with `JsonRpcErrorCode.ConfigurationError` when it is not installed; URL and
+ * number validation are built in.
  *
  * Path sanitization (`sanitizePath`) is synchronous but only available in Node.js environments.
  *
@@ -208,22 +208,21 @@ export declare class Sanitization {
     /**
      * Sanitizes a string according to its intended usage context.
      *
-     * This method is **async** because it lazy-loads `sanitize-html` and/or `validator`
-     * depending on the requested context.
+     * This method is **async** because the HTML-stripping contexts lazy-load `sanitize-html`.
      *
      * | `context`      | Behavior |
      * |----------------|----------|
      * | `'text'`       | Strips all HTML tags and attributes (default). |
      * | `'html'`       | Runs full HTML sanitization via `sanitizeHtml` (respects `allowedTags`/`allowedAttributes`). |
      * | `'attribute'`  | Strips all tags and attributes — safe for use inside an HTML attribute value. |
-     * | `'url'`        | Validates the URL with `validator.isURL` (http/https only); returns `''` if invalid. |
+     * | `'url'`        | Validates the URL as `sanitizeUrl` does (http/https only); returns `''` if invalid. |
      * | `'javascript'` | **Disallowed.** Always throws `McpError`. |
      *
      * @param input - The string to sanitize. Returns `''` immediately if falsy.
      * @param options - Context and optional allowlist overrides.
      * @returns Promise resolving to the sanitized string, or `''` for invalid URLs.
      * @throws {McpError} With `ValidationError` if `context` is `'javascript'`.
-     * @throws {McpError} With `ConfigurationError` if a required peer dep is not installed.
+     * @throws {McpError} With `ConfigurationError` if `sanitize-html` is needed and not installed.
      * @example
      * ```ts
      * await sanitization.sanitizeString('<b>hello</b>', { context: 'text' });
@@ -240,17 +239,19 @@ export declare class Sanitization {
     /**
      * Validates and sanitizes a URL string.
      *
-     * This method is **async** because it lazy-loads the `validator` peer dependency on first call.
+     * Async for API stability; validation is built in and needs no peer dependency.
      *
-     * Validation requires a protocol and host. Even if a protocol appears in `allowedProtocols`,
-     * the pseudo-protocols `javascript:`, `data:`, and `vbscript:` are always rejected.
+     * Validation requires a protocol and host. Hosts may be domains, single-label names such as
+     * `localhost`, IPv4 dotted quads, or bracketed IPv6 literals. Whitespace, `<`, and `>` are
+     * rejected anywhere, as are URLs over 2084 characters. Even if a protocol appears in
+     * `allowedProtocols`, the pseudo-protocols `javascript:`, `data:`, and `vbscript:` are always
+     * rejected.
      *
      * @param input - The URL string to sanitize. Leading/trailing whitespace is trimmed.
      * @param allowedProtocols - URL schemes that are permitted. Defaults to `['http', 'https']`.
      * @returns Promise resolving to the trimmed, validated URL string.
      * @throws {McpError} With `ValidationError` if the URL is invalid, uses a disallowed protocol,
      *   or uses a blocked pseudo-protocol (`javascript:`, `data:`, `vbscript:`).
-     * @throws {McpError} With `ConfigurationError` if `validator` is not installed.
      * @example
      * ```ts
      * await sanitization.sanitizeUrl('https://example.com/path');
@@ -324,10 +325,10 @@ export declare class Sanitization {
     /**
      * Validates a numeric input and optionally clamps it to a range.
      *
-     * This method is **async** because string inputs are validated using the `validator` peer
-     * dependency, which is lazy-loaded on first call. Numeric inputs bypass the lazy load.
+     * Async for API stability; validation is built in and needs no peer dependency.
      *
-     * - String inputs: trimmed and checked with `validator.isNumeric`, then parsed with `parseFloat`.
+     * - String inputs: trimmed, required to be a plain decimal (optional sign and fraction, no
+     *   exponent or separators), then parsed with `parseFloat`.
      * - Number inputs: used directly.
      * - `NaN` and `Infinity` are always rejected.
      * - If `min` or `max` are provided, the value is silently clamped (a debug log is emitted).
@@ -337,7 +338,6 @@ export declare class Sanitization {
      * @param max - Inclusive upper bound. If the value is above this, it is clamped to `max`.
      * @returns Promise resolving to the validated (and potentially clamped) number.
      * @throws {McpError} With `ValidationError` if the input is not numeric, is `NaN`, or is `Infinity`.
-     * @throws {McpError} With `ConfigurationError` if `validator` is not installed (string input only).
      * @example
      * ```ts
      * await sanitization.sanitizeNumber('42.5');
@@ -378,6 +378,37 @@ export declare class Sanitization {
      * ```
      */
     sanitizeForLogging(input: unknown): unknown;
+    /**
+     * Redacts, serializes, and caps a value for a log field: {@link sanitizeForLogging},
+     * then `JSON.stringify`, then truncation to at most `maxBytes` UTF-8 bytes.
+     *
+     * Redaction runs first, so a cut can never keep the prefix of a secret the
+     * redactor would have replaced. The cut lands on a character boundary — never
+     * inside a multi-byte sequence or between the halves of a surrogate pair — so
+     * the result is always well-formed. It is a prefix of the whole serialization,
+     * so a truncated payload is no longer valid JSON; `truncated` says so.
+     *
+     * Returned as a string rather than an object because the logger drops values
+     * nested past its sanitize depth, which would silently strip the deep parts of
+     * a payload. A value `JSON.stringify` rejects (a `bigint`) yields
+     * `'[Log Serialization Failed]'` rather than throwing into the caller's path.
+     *
+     * Key-name redaction only: a secret inside a free-form string value (a query,
+     * a message) is serialized as-is.
+     *
+     * @param value - The value to serialize.
+     * @param maxBytes - Maximum UTF-8 byte length of `text`.
+     * @returns `text`, the serialized and possibly truncated payload, and `truncated`.
+     * @example
+     * ```ts
+     * sanitization.serializeForLogging({ query: 'q', apiKey: 'sk-1' }, 16_384);
+     * // => { text: '{"query":"q","apiKey":"[REDACTED]"}', truncated: false }
+     * ```
+     */
+    serializeForLogging(value: unknown, maxBytes: number): {
+        text: string;
+        truncated: boolean;
+    };
     /**
      * Recursively redacts sensitive fields in an object or array in place.
      * @param obj - The object or array to redact.

package/dist/utils/security/sanitization.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sanitization.d.ts","sourceRoot":"","sources":["../../../src/utils/security/sanitization.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sanitization.d.ts","sourceRoot":"","sources":["../../../src/utils/security/sanitization.ts"],"names":[],"mappings":"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"}

package/dist/utils/security/sanitization.js

@@ -11,13 +11,52 @@ async function loadSanitizeHtml() {
     })).default;
     return _sanitizeHtmlFn;
 }
-let _validator;
-async function loadValidator() {
-    _validator ??= (await import('validator').catch(() => {
-        throw configurationError('Install "validator" to use input validation: bun add validator');
-    })).default;
-    return _validator;
+const URL_MAX_LENGTH = 2084;
+const URL_FORBIDDEN_CHARS = /[\s<>]/;
+const URL_AUTHORITY = /^[a-z][a-z0-9+.-]*:(?:\/\/)?([^/?#]*)/i;
+const URL_HOST_LABEL = String.raw `[\p{L}\p{N}_](?:[\p{L}\p{M}\p{N}_-]*[\p{L}\p{M}\p{N}_])?`;
+const URL_HOST = new RegExp(String.raw `^(?:${URL_HOST_LABEL}(?:\.${URL_HOST_LABEL})*\.?|\[[0-9a-f:.]+\])$`, 'iu');
+const IPV4_HOST = /^\d+\.\d+\.\d+\.\d+$/;
+/**
+ * Validates `input` as an absolute URL with a host, using a scheme from `protocols`.
+ *
+ * Rejects whitespace, `<`, or `>` anywhere, inputs over 2084 characters, and hosts outside
+ * letters, digits, `_`, and non-edge `-` labels (or a bracketed IPv6 literal). The host is
+ * checked as written and must match the host the WHATWG parser resolves, so inputs that read
+ * as one host but fetch another (a backslash before `@`, an obfuscated IPv4 form such as
+ * `2130706433` or `127.1`) are refused. Single-label hosts such as `localhost` are accepted.
+ */
+function isAllowedUrl(input, protocols) {
+    if (!input || input.length > URL_MAX_LENGTH || URL_FORBIDDEN_CHARS.test(input))
+        return false;
+    const url = URL.parse(input);
+    if (!url || !protocols.some((protocol) => `${protocol.toLowerCase()}:` === url.protocol)) {
+        return false;
+    }
+    const authority = URL_AUTHORITY.exec(input)?.[1] ?? '';
+    const host = authority.slice(authority.lastIndexOf('@') + 1).replace(/:\d*$/, '');
+    if (!URL_HOST.test(host))
+        return false;
+    // The host as written must be the host the parser resolved — `http://evil.com\@good.com`
+    // reads as good.com but parses (and fetches) as evil.com.
+    if (URL.parse(`${url.protocol}//${host}`)?.hostname !== url.hostname)
+        return false;
+    return !IPV4_HOST.test(url.hostname) || url.hostname === host;
 }
+/** A plain decimal: optional sign, optional fraction, no exponent or separators. */
+const NUMERIC_STRING = /^[+-]?([0-9]*\.)?[0-9]+$/;
+/** `data.reason` + recovery shared by every `sanitizeNumber` rejection. */
+const INVALID_NUMBER = {
+    reason: 'invalid_number',
+    recovery: {
+        hint: 'Provide a finite decimal number, such as 42 or -3.5, without an exponent or thousands separators.',
+    },
+};
+const PATH_REJECTION_HINTS = {
+    invalid_path: 'Provide a non-empty path string that contains no null bytes.',
+    path_traversal: 'Provide a relative path that stays inside the permitted directory, with no `..` segments climbing out of it.',
+    absolute_path_disallowed: 'Provide a relative path instead of an absolute one.',
+};
 // Dynamically import 'path' only in Node.js environments.
 // Top-level await ensures the module is loaded before any sanitizePath call.
 let pathModule;
@@ -253,22 +292,21 @@ export class Sanitization {
     /**
      * Sanitizes a string according to its intended usage context.
      *
-     * This method is **async** because it lazy-loads `sanitize-html` and/or `validator`
-     * depending on the requested context.
+     * This method is **async** because the HTML-stripping contexts lazy-load `sanitize-html`.
      *
      * | `context`      | Behavior |
      * |----------------|----------|
      * | `'text'`       | Strips all HTML tags and attributes (default). |
      * | `'html'`       | Runs full HTML sanitization via `sanitizeHtml` (respects `allowedTags`/`allowedAttributes`). |
      * | `'attribute'`  | Strips all tags and attributes — safe for use inside an HTML attribute value. |
-     * | `'url'`        | Validates the URL with `validator.isURL` (http/https only); returns `''` if invalid. |
+     * | `'url'`        | Validates the URL as `sanitizeUrl` does (http/https only); returns `''` if invalid. |
      * | `'javascript'` | **Disallowed.** Always throws `McpError`. |
      *
      * @param input - The string to sanitize. Returns `''` immediately if falsy.
      * @param options - Context and optional allowlist overrides.
      * @returns Promise resolving to the sanitized string, or `''` for invalid URLs.
      * @throws {McpError} With `ValidationError` if `context` is `'javascript'`.
-     * @throws {McpError} With `ConfigurationError` if a required peer dep is not installed.
+     * @throws {McpError} With `ConfigurationError` if `sanitize-html` is needed and not installed.
      * @example
      * ```ts
      * await sanitization.sanitizeString('<b>hello</b>', { context: 'text' });
@@ -301,26 +339,21 @@ export class Sanitization {
                 return sanitizeHtmlFn(input, { allowedTags: [], allowedAttributes: {} });
             }
             case 'url': {
-                const v = await loadValidator();
-                if (!v.isURL(input, {
-                    protocols: ['http', 'https'],
-                    require_protocol: true,
-                    require_host: true,
-                })) {
+                if (!isAllowedUrl(input, ['http', 'https'])) {
                     logger.warning('Potentially invalid URL detected during string sanitization (context: url)', requestContextService.createRequestContext({
                         operation: 'Sanitization.sanitizeString.urlWarning',
                         additionalContext: { invalidUrlAttempt: input },
                     }));
                     return '';
                 }
-                return v.trim(input);
+                return input.trim();
             }
             case 'javascript':
                 logger.error('Attempted JavaScript sanitization via sanitizeString, which is disallowed.', requestContextService.createRequestContext({
                     operation: 'Sanitization.sanitizeString.jsAttempt',
                     additionalContext: { inputSnippet: input.substring(0, 50) },
                 }));
-                throw validationError('JavaScript sanitization is not supported through sanitizeString due to security risks.');
+                throw validationError('JavaScript sanitization is not supported through sanitizeString due to security risks.', { reason: 'unsupported_sanitize_context' });
             default: {
                 const sanitizeHtmlFn = await loadSanitizeHtml();
                 return sanitizeHtmlFn(input, { allowedTags: [], allowedAttributes: {} });
@@ -330,17 +363,19 @@ export class Sanitization {
     /**
      * Validates and sanitizes a URL string.
      *
-     * This method is **async** because it lazy-loads the `validator` peer dependency on first call.
+     * Async for API stability; validation is built in and needs no peer dependency.
      *
-     * Validation requires a protocol and host. Even if a protocol appears in `allowedProtocols`,
-     * the pseudo-protocols `javascript:`, `data:`, and `vbscript:` are always rejected.
+     * Validation requires a protocol and host. Hosts may be domains, single-label names such as
+     * `localhost`, IPv4 dotted quads, or bracketed IPv6 literals. Whitespace, `<`, and `>` are
+     * rejected anywhere, as are URLs over 2084 characters. Even if a protocol appears in
+     * `allowedProtocols`, the pseudo-protocols `javascript:`, `data:`, and `vbscript:` are always
+     * rejected.
      *
      * @param input - The URL string to sanitize. Leading/trailing whitespace is trimmed.
      * @param allowedProtocols - URL schemes that are permitted. Defaults to `['http', 'https']`.
      * @returns Promise resolving to the trimmed, validated URL string.
      * @throws {McpError} With `ValidationError` if the URL is invalid, uses a disallowed protocol,
      *   or uses a blocked pseudo-protocol (`javascript:`, `data:`, `vbscript:`).
-     * @throws {McpError} With `ConfigurationError` if `validator` is not installed.
      * @example
      * ```ts
      * await sanitization.sanitizeUrl('https://example.com/path');
@@ -353,28 +388,31 @@ export class Sanitization {
      * // throws McpError (ValidationError)
      * ```
      */
-    async sanitizeUrl(input, allowedProtocols = ['http', 'https']) {
-        try {
-            const v = await loadValidator();
-            const trimmedInput = input.trim();
-            if (!v.isURL(trimmedInput, {
-                protocols: allowedProtocols,
-                require_protocol: true,
-                require_host: true,
-            })) {
-                throw new Error('Invalid URL format or protocol not in allowed list.');
+    sanitizeUrl(input, allowedProtocols = ['http', 'https']) {
+        return Promise.try(() => {
+            try {
+                const trimmedInput = input.trim();
+                if (!isAllowedUrl(trimmedInput, allowedProtocols)) {
+                    throw new Error('Invalid URL format or protocol not in allowed list.');
+                }
+                const lowercasedInput = trimmedInput.toLowerCase();
+                if (lowercasedInput.startsWith('javascript:') ||
+                    lowercasedInput.startsWith('data:') ||
+                    lowercasedInput.startsWith('vbscript:')) {
+                    throw new Error('Disallowed pseudo-protocol (javascript:, data:, or vbscript:) in URL.');
+                }
+                return trimmedInput;
             }
-            const lowercasedInput = trimmedInput.toLowerCase();
-            if (lowercasedInput.startsWith('javascript:') ||
-                lowercasedInput.startsWith('data:') ||
-                lowercasedInput.startsWith('vbscript:')) {
-                throw new Error('Disallowed pseudo-protocol (javascript:, data:, or vbscript:) in URL.');
+            catch (error) {
+                throw validationError(error instanceof Error ? error.message : 'Invalid or unsafe URL provided.', {
+                    input,
+                    reason: 'invalid_url',
+                    recovery: {
+                        hint: `Provide an absolute URL with a host and no whitespace or angle brackets, using one of these schemes: ${allowedProtocols.join(', ')}.`,
+                    },
+                });
             }
-            return trimmedInput;
-        }
-        catch (error) {
-            throw validationError(error instanceof Error ? error.message : 'Invalid or unsafe URL provided.', { input });
-        }
+        });
     }
     /**
      * Sanitizes a file path, preventing path traversal attacks and normalizing format.
@@ -418,11 +456,16 @@ export class Sanitization {
             ...(resolvedRootDir && { rootDir: resolvedRootDir }),
         };
         let wasAbsoluteInitially = false;
+        const rejectPath = (message, reason) => validationError(message, {
+            input: originalInput,
+            reason,
+            recovery: { hint: PATH_REJECTION_HINTS[reason] },
+        });
         try {
             if (!input || typeof input !== 'string')
-                throw new Error('Invalid path input: must be a non-empty string.');
+                throw rejectPath('Invalid path input: must be a non-empty string.', 'invalid_path');
             if (input.includes('\0'))
-                throw new Error('Path contains null byte, which is disallowed.');
+                throw rejectPath('Path contains null byte, which is disallowed.', 'invalid_path');
             let normalized = path.normalize(input);
             wasAbsoluteInitially = path.isAbsolute(normalized);
             if (effectiveOptions.toPosix) {
@@ -432,18 +475,18 @@ export class Sanitization {
             if (resolvedRootDir) {
                 const fullPath = path.resolve(resolvedRootDir, normalized);
                 if (!fullPath.startsWith(resolvedRootDir + path.sep) && fullPath !== resolvedRootDir) {
-                    throw new Error('Path traversal detected: attempts to escape the defined root directory.');
+                    throw rejectPath('Path traversal detected: attempts to escape the defined root directory.', 'path_traversal');
                 }
                 finalSanitizedPath = path.relative(resolvedRootDir, fullPath);
                 finalSanitizedPath = finalSanitizedPath === '' ? '.' : finalSanitizedPath;
                 if (path.isAbsolute(finalSanitizedPath) && !effectiveOptions.allowAbsolute) {
-                    throw new Error('Path resolved to absolute outside root when absolute paths are disallowed.');
+                    throw rejectPath('Path resolved to absolute outside root when absolute paths are disallowed.', 'path_traversal');
                 }
             }
             else {
                 if (path.isAbsolute(normalized)) {
                     if (!effectiveOptions.allowAbsolute) {
-                        throw new Error('Absolute paths are disallowed by current options.');
+                        throw rejectPath('Absolute paths are disallowed by current options.', 'absolute_path_disallowed');
                     }
                     else {
                         finalSanitizedPath = normalized;
@@ -454,7 +497,7 @@ export class Sanitization {
                     const currentWorkingDir = path.resolve('.');
                     if (!resolvedAgainstCwd.startsWith(currentWorkingDir + path.sep) &&
                         resolvedAgainstCwd !== currentWorkingDir) {
-                        throw new Error('Relative path traversal detected (escapes current working directory context).');
+                        throw rejectPath('Relative path traversal detected (escapes current working directory context).', 'path_traversal');
                     }
                     finalSanitizedPath = normalized;
                 }
@@ -478,7 +521,9 @@ export class Sanitization {
                     errorMessage: error instanceof Error ? error.message : String(error),
                 },
             }));
-            throw validationError(error instanceof Error ? error.message : 'Invalid or unsafe path provided.', { input: originalInput });
+            if (error instanceof McpError)
+                throw error;
+            throw rejectPath(error instanceof Error ? error.message : 'Invalid or unsafe path provided.', 'invalid_path');
         }
     }
     /**
@@ -525,6 +570,8 @@ export class Sanitization {
                 throw validationError(`JSON string exceeds maximum allowed size of ${maxSize} bytes.`, {
                     actualSize: computeBytes(input),
                     maxSize,
+                    reason: 'json_too_large',
+                    recovery: { hint: `Send a JSON payload of at most ${maxSize} bytes.` },
                 });
             }
             return JSON.parse(input);
@@ -534,16 +581,18 @@ export class Sanitization {
                 throw error;
             throw validationError(error instanceof Error ? error.message : 'Invalid JSON format.', {
                 inputPreview: input.length > 100 ? `${input.substring(0, 100)}...` : input,
+                reason: 'invalid_json',
+                recovery: { hint: 'Send the value as a well-formed JSON string.' },
             });
         }
     }
     /**
      * Validates a numeric input and optionally clamps it to a range.
      *
-     * This method is **async** because string inputs are validated using the `validator` peer
-     * dependency, which is lazy-loaded on first call. Numeric inputs bypass the lazy load.
+     * Async for API stability; validation is built in and needs no peer dependency.
      *
-     * - String inputs: trimmed and checked with `validator.isNumeric`, then parsed with `parseFloat`.
+     * - String inputs: trimmed, required to be a plain decimal (optional sign and fraction, no
+     *   exponent or separators), then parsed with `parseFloat`.
      * - Number inputs: used directly.
      * - `NaN` and `Infinity` are always rejected.
      * - If `min` or `max` are provided, the value is silently clamped (a debug log is emitted).
@@ -553,7 +602,6 @@ export class Sanitization {
      * @param max - Inclusive upper bound. If the value is above this, it is clamped to `max`.
      * @returns Promise resolving to the validated (and potentially clamped) number.
      * @throws {McpError} With `ValidationError` if the input is not numeric, is `NaN`, or is `Infinity`.
-     * @throws {McpError} With `ConfigurationError` if `validator` is not installed (string input only).
      * @example
      * ```ts
      * await sanitization.sanitizeNumber('42.5');
@@ -566,50 +614,58 @@ export class Sanitization {
      * // throws McpError (ValidationError)
      * ```
      */
-    async sanitizeNumber(input, min, max) {
-        let value;
-        if (typeof input === 'string') {
-            const v = await loadValidator();
-            const trimmedInput = input.trim();
-            if (trimmedInput === '' || !v.isNumeric(trimmedInput)) {
-                throw validationError('Invalid number format: input is empty or not numeric.', { input });
+    sanitizeNumber(input, min, max) {
+        return Promise.try(() => {
+            let value;
+            if (typeof input === 'string') {
+                const trimmedInput = input.trim();
+                if (!NUMERIC_STRING.test(trimmedInput)) {
+                    throw validationError('Invalid number format: input is empty or not numeric.', {
+                        input,
+                        ...INVALID_NUMBER,
+                    });
+                }
+                value = parseFloat(trimmedInput);
             }
-            value = parseFloat(trimmedInput);
-        }
-        else if (typeof input === 'number') {
-            value = input;
-        }
-        else {
-            throw validationError('Invalid input type: expected number or string.', {
-                input: String(input),
-            });
-        }
-        if (Number.isNaN(value) || !Number.isFinite(value)) {
-            throw validationError('Invalid number value (NaN or Infinity).', { input });
-        }
-        let clamped = false;
-        const originalValueForLog = value;
-        if (min !== undefined && value < min) {
-            value = min;
-            clamped = true;
-        }
-        if (max !== undefined && value > max) {
-            value = max;
-            clamped = true;
-        }
-        if (clamped) {
-            logger.debug('Number clamped to range.', requestContextService.createRequestContext({
-                operation: 'Sanitization.sanitizeNumber.clamped',
-                additionalContext: {
-                    originalInput: String(input),
-                    parsedValue: originalValueForLog,
-                    minValue: min,
-                    maxValue: max,
-                    clampedValue: value,
-                },
-            }));
-        }
-        return value;
+            else if (typeof input === 'number') {
+                value = input;
+            }
+            else {
+                throw validationError('Invalid input type: expected number or string.', {
+                    input: String(input),
+                    ...INVALID_NUMBER,
+                });
+            }
+            if (Number.isNaN(value) || !Number.isFinite(value)) {
+                throw validationError('Invalid number value (NaN or Infinity).', {
+                    input,
+                    ...INVALID_NUMBER,
+                });
+            }
+            let clamped = false;
+            const originalValueForLog = value;
+            if (min !== undefined && value < min) {
+                value = min;
+                clamped = true;
+            }
+            if (max !== undefined && value > max) {
+                value = max;
+                clamped = true;
+            }
+            if (clamped) {
+                logger.debug('Number clamped to range.', requestContextService.createRequestContext({
+                    operation: 'Sanitization.sanitizeNumber.clamped',
+                    additionalContext: {
+                        originalInput: String(input),
+                        parsedValue: originalValueForLog,
+                        minValue: min,
+                        maxValue: max,
+                        clampedValue: value,
+                    },
+                }));
+            }
+            return value;
+        });
     }
     /**
      * Produces a log-safe deep clone of `input` with sensitive field values replaced by `'[REDACTED]'`.
@@ -655,6 +711,57 @@ export class Sanitization {
             return '[Log Sanitization Failed]';
         }
     }
+    /**
+     * Redacts, serializes, and caps a value for a log field: {@link sanitizeForLogging},
+     * then `JSON.stringify`, then truncation to at most `maxBytes` UTF-8 bytes.
+     *
+     * Redaction runs first, so a cut can never keep the prefix of a secret the
+     * redactor would have replaced. The cut lands on a character boundary — never
+     * inside a multi-byte sequence or between the halves of a surrogate pair — so
+     * the result is always well-formed. It is a prefix of the whole serialization,
+     * so a truncated payload is no longer valid JSON; `truncated` says so.
+     *
+     * Returned as a string rather than an object because the logger drops values
+     * nested past its sanitize depth, which would silently strip the deep parts of
+     * a payload. A value `JSON.stringify` rejects (a `bigint`) yields
+     * `'[Log Serialization Failed]'` rather than throwing into the caller's path.
+     *
+     * Key-name redaction only: a secret inside a free-form string value (a query,
+     * a message) is serialized as-is.
+     *
+     * @param value - The value to serialize.
+     * @param maxBytes - Maximum UTF-8 byte length of `text`.
+     * @returns `text`, the serialized and possibly truncated payload, and `truncated`.
+     * @example
+     * ```ts
+     * sanitization.serializeForLogging({ query: 'q', apiKey: 'sk-1' }, 16_384);
+     * // => { text: '{"query":"q","apiKey":"[REDACTED]"}', truncated: false }
+     * ```
+     */
+    serializeForLogging(value, maxBytes) {
+        let json;
+        try {
+            json = JSON.stringify(this.sanitizeForLogging(value)) ?? 'undefined';
+        }
+        catch {
+            return { text: '[Log Serialization Failed]', truncated: false };
+        }
+        // Counted by hand rather than with `TextEncoder.encodeInto`, whose fill of a
+        // short buffer differs by runtime (Node stops up to two bytes early). A
+        // high surrogate starts a 4-byte pair and is sliced only with its partner;
+        // `JSON.stringify` escapes lone surrogates, so none reach here.
+        let bytes = 0;
+        for (let i = 0; i < json.length; i++) {
+            const unit = json.charCodeAt(i);
+            const width = unit < 0x80 ? 1 : unit < 0x800 ? 2 : unit >= 0xd800 && unit < 0xdc00 ? 4 : 3;
+            if (bytes + width > maxBytes)
+                return { text: json.slice(0, i), truncated: true };
+            bytes += width;
+            if (width === 4)
+                i++;
+        }
+        return { text: json, truncated: false };
+    }
     /**
      * Recursively redacts sensitive fields in an object or array in place.
      * @param obj - The object or array to redact.