@alanwang-merit/meritdata-platform-skill-package 1.0.0

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

@@ -0,0 +1,181 @@
+# 与 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/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: meritdata-platform-sso
+description: |
+  SSO 单点登录。OAuth2/CAS 接入、Token 管理、过滤器配置、跳转登录、退出登录、Token 刷新、跨域。
+  触发场景：新二开模块接入平台 SSO；需要统一登录态；对接第三方 OAuth（微信/钉钉/企业微信）。
+  何时不用：纯前端登录 → 用 frontend；权限点控制 → L3 资源授权（待建）。
+metadata:
+  version: "1.0.0"
+  author: petroleum+rd
+  source: petroleum+rd
+  date_added: "2026-09-07"
+  last_modified: "2026-09-07"
+  risk: high
+  layer: L2
+  sub-layer: L2-C
+  stack: java
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# SSO 单点登录（sso）
+
+## 触发
+- 新二开模块需要接入平台 SSO
+- 需要对接第三方 OAuth（微信/钉钉/企业微信）
+- 需要 Token 刷新 / 跨域登录
+- 需要统一退出登录
+
+## 不触发
+- 纯前端样式调整 → 用 `meritdata-platform-frontend`
+- 资源/数据权限控制 → L3 资源授权（待建）
+- 已登录态使用 → 用 `meritdata-platform-entities` 获取 UserDTO
+
+## 前置约束
+- Token **禁止**写入 URL（详见 [rules/security-rules.md](../../rules/security-rules.md)）
+- 认证失败提示信息**不能过于详细**（不能区分"密码错误"vs"用户不存在"）
+- 敏感操作（修改密码/绑定手机）必须二次认证
+
+## 路由
+- SSO 接入流程 + Token 管理 → [references/sso-guide.md](references/sso-guide.md)
+- 第三方 OAuth 接入 → [references/oauth-providers.md](references/oauth-providers.md)
+- 过滤器配置 + 拦截规则 → [references/filter-config.md](references/filter-config.md)

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

@@ -0,0 +1,391 @@
+# 过滤器与拦截器配置（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)