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:

Nested Class Summary

Nested Classes

Modifier and Type

Class

Description

static final record

JsonSecurity.SecurityOptions

Security options for JSON parsing.
Field Summary

Fields

Modifier and Type

Field

Description

static final int

DEFAULT_MAX_DEPTH

Default maximum depth 默认最大深度

static final int

DEFAULT_MAX_ENTRIES

Default maximum entries 默认最大条目数

static final int

DEFAULT_MAX_STRING_LENGTH

Default maximum string length 默认最大字符串长度
Method Summary

Modifier and Type

Method

Description

static int

calculateDepth(JsonNode node)

Calculates the depth of a JSON tree.

static int

calculateSize(JsonNode node)

Calculates the total size (entries) of a JSON tree.

static Set<String>

dangerousKeys()

Returns the canonical immutable set of dangerous keys.

static List<String>

findDangerousKeys(JsonNode node)

Checks for dangerous property keys.

static boolean

hasDangerousKeys(JsonNode node)

Checks if JSON contains dangerous keys.

static boolean

isDangerousKey(String key)

O(1) single-key dangerous-key check, intended for streaming parsers that need to test each object key as it is read.

static String

mask(String value, int prefixLength, int suffixLength, char maskChar)

Masks a value with custom prefix/suffix lengths.

static String

mask(String value, JsonMask.MaskType type)

Masks a string value based on mask type.

static String

mask(String value, JsonMask.MaskType type, char maskChar)

Masks a string value with custom mask character.

static String

maskWithPattern(String value, String pattern, String replacement)

Masks a value using regex pattern.

static JsonNode

sanitizeForHtml(JsonNode node)

Sanitizes all string values in a JSON tree for HTML output.

static String

sanitizeForHtml(String value)

Sanitizes a string for safe HTML output.

static void

validate(JsonNode node, JsonSecurity.SecurityOptions options)

Validates a JSON node against security options.

static void

validateDepth(JsonNode node, int maxDepth)

Validates JSON depth.

static void

validateSize(JsonNode node, int maxSize)

Validates JSON size (total entries).

Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details
- DEFAULT_MAX_DEPTH
  public static final int DEFAULT_MAX_DEPTH
  
  Default maximum depth 默认最大深度
  
  See Also:
  
  Constant Field Values
- DEFAULT_MAX_STRING_LENGTH
  public static final int DEFAULT_MAX_STRING_LENGTH
  
  Default maximum string length 默认最大字符串长度
  
  See Also:
  
  Constant Field Values
- DEFAULT_MAX_ENTRIES
  public static final int DEFAULT_MAX_ENTRIES
  
  Default maximum entries 默认最大条目数
  
  See Also:
  
  Constant Field Values
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
- isDangerousKey
  
  public static boolean isDangerousKey(String key)
  
  O(1) single-key dangerous-key check, intended for streaming parsers that need to test each object key as it is read. O(1) 单键危险性检查，供流式解析器在每次读取对象 key 后调用。
  
  Parameters:
  
  key - the object key to check - 要检查的对象键
  
  Returns:
  
  true if key is a known dangerous key - 如果键是已知危险键则返回 true
  
  Since:
  
  opencode-base-json V1.0.4
- dangerousKeys
  
  public static Set<String> dangerousKeys()
  
  Returns the canonical immutable set of dangerous keys. Use this set to extend or compare custom dangerous-key policies. 返回危险键的规范不可变集合。可用于扩展或比对自定义危险键策略。
  
  Returns:
  
  the immutable dangerous-key set - 不可变危险键集合
  
  Since:
  
  opencode-base-json V1.0.4
- 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 - 如果验证失败

Class JsonSecurity

Nested Class Summary

Field Summary

Method Summary

Methods inherited from class Object

Field Details

DEFAULT_MAX_DEPTH

DEFAULT_MAX_STRING_LENGTH

DEFAULT_MAX_ENTRIES

Method Details

mask

mask

mask

maskWithPattern

validateDepth

validateSize

calculateDepth

calculateSize

findDangerousKeys

hasDangerousKeys

isDangerousKey

dangerousKeys

sanitizeForHtml

sanitizeForHtml

validate