@alanwang-merit/meritdata-platform-skill-package 1.0.10 → 1.0.12

package/skills/meritdata-platform-sm-crypto/references/migration.md

@@ -1,181 +0,0 @@
-# 与 RSA/AES 迁移指南（sm-crypto）
-
-> 从 RSA/AES 迁移到 SM2/SM4 的策略。
-
----
-
-## 1. 为什么迁移
-
-| 维度 | 国际算法 | 国密算法 |
-|------|---------|---------|
-| 合规 | 通用场景 | **国产合规要求**（金融、政务、关键基础设施） |
-| 性能 | 成熟稳定 | SM2 比 RSA 快（密钥短） |
-| 安全 | 长期验证 | 等同强度，国产可控 |
-
-**触发迁移的场景**：
-- 项目进入金融/政务领域
-- 监管要求国产密码
-- 客户明确要求
-- 信创替代
-
-## 2. 迁移策略
-
-### 2.1 双轨运行
-
-**不直接切换**，而是新旧算法共存：
-
-```
-业务请求 → { RSA 验签 | SM2 验签 } → 任一通过
-业务响应 → { AES 加密 | SM4 加密 } → 接收方选择
-```
-
-### 2.2 灰度切换
-
-```java
-public String decrypt(String cipher, String algorithm) {
-    if ("SM4".equals(algorithm)) {
-        return sm4Decrypt(cipher);
-    } else if ("AES".equals(algorithm)) {
-        return aesDecrypt(cipher);
-    }
-    throw new IllegalArgumentException("Unsupported: " + algorithm);
-}
-```
-
-### 2.3 平滑过渡
-
-阶段 1：新数据用 SM 加密（旧数据仍用 RSA/AES）
-阶段 2：旧数据生命周期结束后，全部切到 SM
-阶段 3：移除 RSA/AES 代码
-
-## 3. 协议层迁移
-
-### 3.1 HTTPS
-
-| 类型 | 说明 |
-|------|------|
-| RSA SSL | 传统，主流浏览器支持 |
-| SM2 SSL | 国密证书，需要国密浏览器/客户端 |
-
-**建议**：
-- 通用 HTTPS 保留 RSA
-- 内部系统/政府对接用 SM2 SSL
-
-### 3.2 报文签名
-
-```java
-// 旧：RSA
-String sign = RSAUtils.sign(data, privateKey);
-
-// 新：SM2
-String sign = Sm2Utils.sign(data, sm2PrivateKey);
-
-// 双轨：带算法标识
-String sign = algorithm.equals("SM2")
-    ? Sm2Utils.sign(data, sm2PrivateKey)
-    : RSAUtils.sign(data, rsaPrivateKey);
-```
-
-## 4. 算法对比与映射
-
-### 4.1 非对称
-
-| 场景 | RSA | SM2 |
-|------|-----|-----|
-| 密钥长度 | 2048 / 4096 | 256 |
-| 签名性能 | 100ms 级 | 1ms 级 |
-| 等价安全 | RSA 2048 ≈ SM2 256 | - |
-
-**迁移注意**：
-- SM2 密钥短，存储更省
-- 签名验签比 RSA 快 50-100 倍
-- 标准曲线（sm2p256v1）
-
-### 4.2 对称
-
-| 场景 | AES | SM4 |
-|------|-----|-----|
-| 密钥长度 | 128 / 192 / 256 | 128 |
-| 分组 | 128 | 128 |
-| 模式 | CBC / GCM | CBC / GCM |
-
-**迁移注意**：
-- 密钥长度匹配（推荐 AES-128 ↔ SM4-128）
-- IV 处理一致
-- GCM 模式需要认证加密（推荐）
-
-### 4.3 摘要
-
-| 场景 | SHA-256 | SM3 |
-|------|---------|-----|
-| 输出长度 | 256 | 256 |
-| 性能 | 成熟 | 等同 |
-
-**迁移注意**：
-- 输出长度一致，可直接替换
-- HMAC 模式对应 HMAC-SM3
-
-## 5. 兼容方案：算法协商
-
-### 5.1 协议字段
-
-```json
-{
-  "algorithm": "SM4",
-  "cipherText": "xxx",
-  "iv": "yyy"
-}
-```
-
-### 5.2 自适应解析
-
-```java
-public String decrypt(JSONObject message) {
-    String algorithm = message.getString("algorithm");
-    String cipher = message.getString("cipherText");
-    String iv = message.getString("iv");
-
-    switch (algorithm) {
-        case "SM4":
-            return sm4Decrypt(cipher, iv);
-        case "AES":
-            return aesDecrypt(cipher, iv);
-        default:
-            throw new UnsupportedAlgorithmException(algorithm);
-    }
-}
-```
-
-## 6. 迁移检查清单
-
-- [ ] 评估业务场景是否必须国产化
-- [ ] 调研上下游是否支持 SM 算法
-- [ ] 设计双轨协议（algorithm 字段）
-- [ ] 实现双轨加解密
-- [ ] 灰度切换（新数据用 SM）
-- [ ] 等待旧数据生命周期结束
-- [ ] 移除旧算法代码
-
-## 8. ❌ 反模式
-
-### 8.1 ❌ 直接切换无过渡
-
-```java
-// ❌ 错：直接换 SM 算法，旧 RSA 加密的数据全部失效
-String sign = Sm2Utils.sign(data, sm2PrivateKey);  // 旧客户端验签失败
-```
-
-### 8.2 ❌ 国密和国际混用同一字段
-
-```java
-// ❌ 错：同一字段既可能是 RSA 签名也可能是 SM2 签名
-String sign;  // 接收方不知道算法
-```
-
-✅ 显式带 algorithm 字段。
-
-## 9. 关联阅读
-
-- [guide.md](guide.md) — 国密算法基础
-- [key-management.md](key-management.md) — 密钥管理
-- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-sso/references/filter-config.md

@@ -1,391 +0,0 @@
-# 过滤器与拦截器配置（filter-config）
-
-> SSO 登录态校验、CSRF、XSS、SQL 注入等过滤器的标准配置。
-
----
-
-## 1. 过滤器 vs 拦截器
-
-| 维度 | Filter（过滤器） | Interceptor（拦截器） |
-|------|----------------|---------------------|
-| 规范 | Servlet 规范 | Spring MVC |
-| 范围 | 所有请求 | Controller 请求 |
-| 时机 | 在 DispatcherServlet 之前 | 在 Controller 之前 |
-| 用途 | 编码、XSS、跨域 | 登录态、权限 |
-
----
-
-## 2. SSO 登录过滤器
-
-### 2.1 Filter 实现
-
-```java
-@Slf4j
-public class SsoAuthFilter implements Filter {
-
-    @Autowired
-    private SsoTokenValidator tokenValidator;
-
-    private static final List<String> WHITE_LIST = Arrays.asList(
-        "/api/v1/auth/login",
-        "/api/v1/auth/callback",
-        "/api/v1/public/",
-        "/swagger-ui/",
-        "/v3/api-docs/"
-    );
-
-    @Override
-    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException {
-        HttpServletRequest req = (HttpServletRequest) request;
-        HttpServletResponse resp = (HttpServletResponse) response;
-
-        // 1. 白名单放行
-        String uri = req.getRequestURI();
-        if (isWhiteListed(uri)) {
-            chain.doFilter(request, response);
-            return;
-        }
-
-        // 2. 提取 token
-        String token = extractToken(req);
-        if (StringUtils.isBlank(token)) {
-            writeError(resp, 401, "未登录");
-            return;
-        }
-
-        // 3. 验证 token
-        try {
-            UserDTO user = tokenValidator.validateAndGetUser(token);
-            SecurityUtils.setCurrentUser(user);
-            chain.doFilter(request, response);
-        } catch (TokenExpiredException e) {
-            writeError(resp, 401, "Token 已过期");
-        } catch (Exception e) {
-            log.warn("Token 验证失败：{}", e.getMessage());
-            writeError(resp, 401, "Token 无效");
-        } finally {
-            SecurityUtils.clear();
-        }
-    }
-
-    private String extractToken(HttpServletRequest request) {
-        // 优先从 Header 取
-        String bearerToken = request.getHeader("Authorization");
-        if (bearerToken != null && bearerToken.startsWith("Bearer ")) {
-            return bearerToken.substring(7);
-        }
-
-        // 其次从 cookie 取
-        Cookie[] cookies = request.getCookies();
-        if (cookies != null) {
-            for (Cookie cookie : cookies) {
-                if ("sso_token".equals(cookie.getName())) {
-                    return cookie.getValue();
-                }
-            }
-        }
-
-        return null;
-    }
-
-    private boolean isWhiteListed(String uri) {
-        return WHITE_LIST.stream().anyMatch(uri::startsWith);
-    }
-
-    private void writeError(HttpServletResponse response, int code, String message) throws IOException {
-        response.setStatus(code);
-        response.setContentType("application/json");
-        response.getWriter().write(JSON.toJSONString(ApiResponse.error(code, message)));
-    }
-}
-```
-
-### 2.2 注册 Filter
-
-```java
-@Configuration
-public class FilterConfig {
-
-    @Bean
-    public FilterRegistrationBean<SsoAuthFilter> ssoAuthFilter() {
-        FilterRegistrationBean<SsoAuthFilter> registration = new FilterRegistrationBean<>();
-        registration.setFilter(new SsoAuthFilter());
-        registration.addUrlPatterns("/api/*");
-        registration.setOrder(1);
-        return registration;
-    }
-}
-```
-
----
-
-## 3. CORS 跨域过滤器
-
-### 3.1 简单配置（Spring 6+）
-
-```java
-@Configuration
-public class CorsConfig {
-
-    @Bean
-    public CorsConfigurationSource corsConfigurationSource() {
-        CorsConfiguration config = new CorsConfiguration();
-        config.setAllowedOrigins(Arrays.asList(
-            "https://app.example.com",
-            "https://admin.example.com"
-        ));
-        config.setAllowedMethods(Arrays.asList("GET", "POST", "PUT", "DELETE", "OPTIONS"));
-        config.setAllowedHeaders(Arrays.asList("*"));
-        config.setAllowCredentials(true);
-        config.setMaxAge(3600L);
-
-        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
-        source.registerCorsConfiguration("/api/**", config);
-        return source;
-    }
-}
-```
-
-### 3.2 ❌ 反例
-
-```java
-// ❌ 错：允许所有来源 + 所有方法 → XSRF 风险
-config.setAllowedOrigins(Arrays.asList("*"));
-config.setAllowedMethods(Arrays.asList("*"));
-```
-
-✅ 生产环境必须**明确指定来源**。
-
----
-
-## 4. XSS 过滤器
-
-### 4.1 输入过滤
-
-```java
-public class XssFilter implements Filter {
-
-    @Override
-    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException {
-        HttpServletRequest req = (HttpServletRequest) request;
-        XssHttpServletRequestWrapper wrappedRequest = new XssHttpServletRequestWrapper(req);
-        chain.doFilter(wrappedRequest, response);
-    }
-}
-
-public class XssHttpServletRequestWrapper extends HttpServletRequestWrapper {
-
-    public XssHttpServletRequestWrapper(HttpServletRequest request) {
-        super(request);
-    }
-
-    @Override
-    public String getParameter(String name) {
-        return sanitize(super.getParameter(name));
-    }
-
-    @Override
-    public String[] getParameterValues(String name) {
-        String[] values = super.getParameterValues(name);
-        if (values == null) return null;
-        return Arrays.stream(values).map(this::sanitize).toArray(String[]::new);
-    }
-
-    @Override
-    public String getHeader(String name) {
-        return sanitize(super.getHeader(name));
-    }
-
-    private String sanitize(String value) {
-        if (value == null) return null;
-        // 转义 < > & " '
-        return value.replaceAll("<", "&lt;")
-                     .replaceAll(">", "&gt;")
-                     .replaceAll("\"", "&quot;")
-                     .replaceAll("'", "&#x27;")
-                     .replaceAll("&", "&amp;");
-    }
-}
-```
-
-### 4.2 ❌ 反例：不过滤
-
-```java
-// ❌ 错：直接渲染用户输入
-@GetMapping("/comment")
-public String getComment(@RequestParam String content) {
-    return "<div>" + content + "</div>";  // XSS 攻击
-}
-```
-
-### 4.3 推荐：前端输出转义
-
-```vue
-<!-- ✅ Vue 默认转义 -->
-<div>{{ content }}</div>
-
-<!-- ❌ 错：v-html 不过滤 -->
-<div v-html="content"></div>
-```
-
----
-
-## 5. SQL 注入防护
-
-### 5.1 必须用 PreparedStatement
-
-```java
-// ❌ 错：SQL 拼接
-String sql = "SELECT * FROM t_user WHERE name = '" + name + "'";
-
-// ✅ 正确：PreparedStatement
-String sql = "SELECT * FROM t_user WHERE name = ?";
-PreparedStatement ps = connection.prepareStatement(sql);
-ps.setString(1, name);
-```
-
-### 5.2 MyBatis #{} vs ${}
-
-```xml
-<!-- ✅ 正确：#{} 预编译 -->
-<select id="findByName" resultType="User">
-    SELECT * FROM t_user WHERE name = #{name}
-</select>
-
-<!-- ❌ 错：${} 字符串替换 → 注入风险 -->
-<select id="findByName" resultType="User">
-    SELECT * FROM t_user WHERE name = '${name}'
-</select>
-```
-
-### 5.3 JPA NamedQuery
-
-```java
-// ✅ 正确：NamedQuery 参数绑定
-@NamedQuery(name = "User.findByName", query = "SELECT u FROM User u WHERE u.name = :name")
-
-// ✅ 正确：方法命名自动生成
-List<User> findByName(String name);
-
-// ❌ 错：拼接 JPQL
-em.createQuery("SELECT u FROM User u WHERE u.name = '" + name + "'");
-```
-
----
-
-## 6. CSRF 防护
-
-### 6.1 场景
-
-攻击者诱导用户访问已登录的银行网站，转账给攻击者。
-
-### 6.2 Spring Security CSRF 开启
-
-```java
-@Configuration
-@EnableWebSecurity
-public class SecurityConfig {
-
-    @Bean
-    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
-        http
-            .csrf(csrf -> csrf
-                .csrfTokenRepository(CookieCsrfTokenRepository.withHttpOnlyFalse())
-            )
-            .authorizeHttpRequests(auth -> auth
-                .requestMatchers("/api/v1/auth/**").permitAll()
-                .anyRequest().authenticated()
-            );
-        return http.build();
-    }
-}
-```
-
-### 6.3 前后端分离场景
-
-```java
-// 前后端分离 + JWT → 通常禁用 CSRF（用 Token 而非 Cookie 维持会话）
-http.csrf(csrf -> csrf.disable());
-```
-
-但如果用 Cookie 维持会话，**必须开启 CSRF**。
-
----
-
-## 7. 限流过滤器
-
-### 7.1 基于 IP 限流
-
-```java
-@Component
-public class RateLimitFilter implements Filter {
-
-    private final RateLimiter limiter = RateLimiter.create(100);  // 100 QPS
-
-    @Override
-    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException {
-        if (!limiter.tryAcquire()) {
-            ((HttpServletResponse) response).setStatus(429);
-            response.getWriter().write("请求过于频繁");
-            return;
-        }
-        chain.doFilter(request, response);
-    }
-}
-```
-
-### 7.2 基于用户限流
-
-```java
-public class UserRateLimitFilter implements Filter {
-
-    private final LoadingCache<String, RateLimiter> userLimiters = Caffeine.newBuilder()
-        .expireAfterAccess(Duration.ofMinutes(10))
-        .maximumSize(10_000)
-        .build(userId -> RateLimiter.create(10));  // 每用户 10 QPS
-
-    @Override
-    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException {
-        UserDTO user = SecurityUtils.getCurrentUser();
-        if (user != null) {
-            RateLimiter limiter = userLimiters.get(user.getId());
-            if (!limiter.tryAcquire()) {
-                writeError(response, 429, "请求过于频繁");
-                return;
-            }
-        }
-        chain.doFilter(request, response);
-    }
-}
-```
-
----
-
-## 8. 过滤器顺序
-
-```
-HTTP Request
-  ↓
-[1] CORS 过滤器           ← 处理跨域
-  ↓
-[2] XSS 过滤器            ← 清洗输入
-  ↓
-[3] 限流过滤器            ← 防止过载
-  ↓
-[4] SSO 登录过滤器        ← 验证登录态
-  ↓
-[5] Spring MVC DispatcherServlet
-  ↓
-[6] 拦截器（权限校验）
-  ↓
-[7] Controller
-```
-
----
-
-## 9. 关联阅读
-
-- [sso-guide.md](sso-guide.md) — SSO 主流程
-- [oauth-providers.md](oauth-providers.md) — 第三方 OAuth
-- [rules/security-rules.md](../../rules/security-rules.md) — 安全规范
-- [SKILL.md](../SKILL.md)