Class JsonSecurity

java.lang.Object
cloud.opencode.base.json.security.JsonSecurity
public final class JsonSecurity extends Object
JSON Security - Security Utilities for JSON Processing JSON 安全 - JSON 处理的安全工具

This class provides security features including data masking, depth/size validation, and secure parsing options.

此类提供安全特性，包括数据脱敏、深度/大小验证和安全解析选项。

Features | 特性:

  • Data masking for sensitive fields - 敏感字段的数据脱敏
  • Depth and size limits to prevent DoS - 深度和大小限制以防止 DoS
  • Dangerous key detection - 危险键检测
  • XSS prevention - XSS 防护

Example | 示例:

// Mask sensitive data
String masked = JsonSecurity.mask("13812345678", JsonMask.MaskType.PHONE);
// Result: "138****5678"

// Validate JSON depth
JsonSecurity.validateDepth(jsonNode, 50);

// Sanitize for XSS
String safe = JsonSecurity.sanitizeForHtml(jsonString);

Features | 主要功能:

  • Data masking for sensitive fields (phone, email, ID card, etc.) - 敏感字段数据脱敏
  • JSON depth and size validation against DoS attacks - JSON深度和大小验证防止DoS攻击
  • XSS prevention via HTML sanitization - 通过HTML净化防止XSS
  • Dangerous key detection for injection prevention - 危险键检测防止注入

Security | 安全性:

  • Thread-safe: Yes (immutable record) - 线程安全: 是（不可变记录）
  • Null-safe: Partial (validates inputs) - 空值安全: 部分（验证输入）
Since:
JDK 25, opencode-base-json V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Field Details

    • DEFAULT_MAX_DEPTH

      public static final int DEFAULT_MAX_DEPTH
      Default maximum depth 默认最大深度
      See Also:

    • DEFAULT_MAX_STRING_LENGTH

      public static final int DEFAULT_MAX_STRING_LENGTH
      Default maximum string length 默认最大字符串长度
      See Also:

    • DEFAULT_MAX_ENTRIES

      public static final int DEFAULT_MAX_ENTRIES
      Default maximum entries 默认最大条目数
      See Also:

  • Method Details

    • mask

      public static String mask(String value, JsonMask.MaskType type)
      Masks a string value based on mask type. 根据脱敏类型对字符串值进行脱敏。
      Parameters:
      value - the value to mask - 要脱敏的值
      type - the mask type - 脱敏类型
      Returns:
      the masked value - 脱敏后的值

    • mask

      public static String mask(String value, JsonMask.MaskType type, char maskChar)
      Masks a string value with custom mask character. 使用自定义脱敏字符对字符串值进行脱敏。
      Parameters:
      value - the value to mask - 要脱敏的值
      type - the mask type - 脱敏类型
      maskChar - the mask character - 脱敏字符
      Returns:
      the masked value - 脱敏后的值

    • mask

      public static String mask(String value, int prefixLength, int suffixLength, char maskChar)
      Masks a value with custom prefix/suffix lengths. 使用自定义前缀/后缀长度对值进行脱敏。
      Parameters:
      value - the value to mask - 要脱敏的值
      prefixLength - visible prefix length - 可见前缀长度
      suffixLength - visible suffix length - 可见后缀长度
      maskChar - the mask character - 脱敏字符
      Returns:
      the masked value - 脱敏后的值

    • maskWithPattern

      public static String maskWithPattern(String value, String pattern, String replacement)
      Masks a value using regex pattern. 使用正则表达式模式对值进行脱敏。

      Note: This method validates the pattern and escapes special characters in the replacement to prevent ReDoS and injection attacks.

      注意：此方法验证模式并转义替换字符串中的特殊字符以防止ReDoS和注入攻击。

      Parameters:
      value - the value to mask - 要脱敏的值
      pattern - the regex pattern - 正则表达式模式
      replacement - the replacement - 替换内容
      Returns:
      the masked value - 脱敏后的值
      Throws:
      IllegalArgumentException - if pattern is invalid | 如果模式无效则抛出异常

    • validateDepth

      public static void validateDepth(JsonNode node, int maxDepth)
      Validates JSON depth. 验证 JSON 深度。
      Parameters:
      node - the JSON node - JSON 节点
      maxDepth - maximum allowed depth - 最大允许深度
      Throws:
      OpenJsonProcessingException - if depth exceeds limit - 如果深度超过限制

    • validateSize

      public static void validateSize(JsonNode node, int maxSize)
      Validates JSON size (total entries). 验证 JSON 大小（总条目数）。
      Parameters:
      node - the JSON node - JSON 节点
      maxSize - maximum allowed entries - 最大允许条目数
      Throws:
      OpenJsonProcessingException - if size exceeds limit - 如果大小超过限制

    • calculateDepth

      public static int calculateDepth(JsonNode node)
      Calculates the depth of a JSON tree. 计算 JSON 树的深度。
      Parameters:
      node - the JSON node - JSON 节点
      Returns:
      the depth - 深度

    • calculateSize

      public static int calculateSize(JsonNode node)
      Calculates the total size (entries) of a JSON tree. 计算 JSON 树的总大小（条目数）。
      Parameters:
      node - the JSON node - JSON 节点
      Returns:
      the size - 大小

    • findDangerousKeys

      public static List<String> findDangerousKeys(JsonNode node)
      Checks for dangerous property keys. 检查危险的属性键。
      Parameters:
      node - the JSON node - JSON 节点
      Returns:
      list of dangerous keys found - 找到的危险键列表

    • hasDangerousKeys

      public static boolean hasDangerousKeys(JsonNode node)
      Checks if JSON contains dangerous keys. 检查 JSON 是否包含危险键。
      Parameters:
      node - the JSON node - JSON 节点
      Returns:
      true if dangerous keys found - 如果发现危险键则返回 true

    • sanitizeForHtml

      public static String sanitizeForHtml(String value)
      Sanitizes a string for safe HTML output. 净化字符串以安全输出 HTML。
      Parameters:
      value - the value to sanitize - 要净化的值
      Returns:
      the sanitized value - 净化后的值

    • sanitizeForHtml

      public static JsonNode sanitizeForHtml(JsonNode node)
      Sanitizes all string values in a JSON tree for HTML output. 净化 JSON 树中所有字符串值以安全输出 HTML。
      Parameters:
      node - the JSON node - JSON 节点
      Returns:
      sanitized copy of the node - 净化后的节点副本

    • validate

      public static void validate(JsonNode node, JsonSecurity.SecurityOptions options)
      Validates a JSON node against security options. 根据安全选项验证 JSON 节点。
      Parameters:
      node - the JSON node - JSON 节点
      options - the security options - 安全选项
      Throws:
      OpenJsonProcessingException - if validation fails - 如果验证失败