1. 安全输入组件概述：设计原则、攻击面与核心接口

安全输入组件是 Material 3 设计系统中负责接收、验证、净化用户输入的前端控件集合。在移动端与 Web 混合架构下，攻击者常通过输入通道注入恶意载荷，因此组件必须在输入边界实施防御。本章从设计原则、典型攻击面和接口契约三个维度建立安全输入的认知基础。

1.1 Material 3 安全输入设计原则

1.2 常见攻击面：XSS 与 SQL 注入

在输入组件需要防御的数十种攻击中，跨站脚本（XSS）和SQL 注入是两种最普遍、破坏力最强的入口攻击。下表对比了二者的触发机制与组件层防御重点。

1.3 组件核心接口定义

安全输入组件对外暴露三个核心接口：校验器（Validator）、净化器（Sanitizer）、安全值（SecureValue）。下面给出接口的类型签名与职责描述。

// 校验器：判断输入是否满足安全与业务约束
interface IValidator {
  // 返回值 true=通过，false=拒绝；message 提供拒绝原因
  validate(raw: string): { valid: boolean; message?: string };
}

// 净化器：将原始输入转换为安全的内部表示
interface ISanitizer {
  // 返回净化后的字符串；若无法净化则抛出异常
  sanitize(raw: string): string;
}

// 安全值：组件对外输出的最终安全数据
interface ISecureValue<T> {
  readonly raw: string;       // 原始输入（仅审计用）
  readonly cleaned: string;   // 净化后的安全字符串
  readonly parsed: T;         // 根据上下文解析后的类型（如 Int、Email）
  readonly timestamp: number; // 输入时间戳
}

1.4 安全输入组件架构流程

下图展示了从用户输入到安全输出的完整处理链路，核心节点对应上述三个接口的协作关系。

流程说明：

• 原始输入进入组件后首先到达 IValidator，执行白名单、长度、格式校验；
• 若校验失败，组件直接返回拒绝状态并携带错误提示，不进入后续阶段；
• 若校验通过，原始输入转发至 ISanitizer 执行上下文编码与边界截断；
• 净化后的安全字符串最终封装为 ISecureValue 输出，其中同时保留原始值（仅用于审计）与解析后的类型值。

1.5 接口调用示例

以下代码展示一个 安全邮箱输入组件 的接口实例化与调用方式：

// 1. 实现邮箱校验器
class EmailValidator implements IValidator {
  private pattern = /^[^\s@]+@[^\s@]+\.[^\s@]{2,}$/;

  validate(raw: string): { valid: boolean; message?: string } {
    if (raw.length > 254) {
      return { valid: false, message: "邮箱长度超过上限（254字符）" };
    }
    if (!this.pattern.test(raw)) {
      return { valid: false, message: "邮箱格式不合法" };
    }
    return { valid: true };
  }
}

// 2. 实现邮箱净化器（仅保留 ASCII 可见字符并转义 HTML）
class EmailSanitizer implements ISanitizer {
  sanitize(raw: string): string {
    // 白名单：仅允许字母、数字、@、.、-、_
    const allowed = raw.replace(/[^a-zA-Z0-9@.\-_]/g, "");
    // HTML 转义（预防反射型 XSS）
    return allowed
      .replace(/&/g, "&")
      .replace(/</g, "&lt;")
      .replace(/>/g, "&gt;")
      .replace(/"/g, "&quot;");
  }
}

// 3. 组件中使用
const validator = new EmailValidator();
const sanitizer = new EmailSanitizer();

function handleInput(rawEmail: string): ISecureValue<string> {
  const { valid, message } = validator.validate(rawEmail);
  if (!valid) {
    throw new Error(`输入拒绝: ${message}`);
  }
  const cleaned = sanitizer.sanitize(rawEmail);
  return {
    raw: rawEmail,
    cleaned,
    parsed: cleaned.toLowerCase(),
    timestamp: Date.now(),
  };
}

1.6 配置方法与调试要点

调试时建议开启 logRejected: true，并通过结构化日志观察拒绝模式：

// 审计日志格式示例（JSON）
{
  "event": "INPUT_REJECTED",
  "component": "SecureEmailInput",
  "reason": "邮箱格式不合法",
  "rawHash": "a1b2c3d4e5f6...",
  "timestamp": 1712889600000
}

1.7 常见错误与规避

• 只校验未净化：校验通过后直接将原始值用于渲染或查询，绕过转义阶段 → 必须在校验后串联 Sanitizer。
• 黑名单过滤：仅屏蔽已知危险关键字（如 script、OR 1=1），攻击者可通过编码绕过 → 使用白名单 + 上下文转义。
• 异常信息泄露：校验失败时返回 "SQL 语法错误 near 'OR 1=1'" 等调试信息 → 对外只返回通用错误提示，详细日志写入服务端。
• 混淆前端与后端职责：前端组件执行了净化，后端就不再校验 → 深度防御要求两端独立实现，前端失效时后端仍是安全兜底。