Преглед изворни кода

test(auth.session.mutex): S-cfc-301 TDD-RED 契约级单测 — 多端登录/会话互斥(SC-P-85/缺口G-5)预期红

- 新增 AuthSessionMutexContractRedTest(纯 Mockito + 反射 + 真实 JwtConfig,无 Spring/DB/外部服务)
- 断言契约所需行为缺失:users.token_version 载体 / User.tokenVersion 字段 /
  JwtConfig 签发携带 tokenVersion claim / UserService 版本旋转入口 /
  JwtInterceptor 注入互斥校验器 / verifyToken 拒旧版本 401 / AuthController 登出端点 /
  异常设备风控入口 均未落地 → 10 run, 9 fail(红)
Sisyphus пре 3 дана
родитељ
комит
d15d5e28b2

+ 356 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/AuthSessionMutexContractRedTest.java

@@ -0,0 +1,356 @@
+package com.etotem.cfc.unit;
+
+import com.etotem.cfc.common.Result;
+import com.etotem.cfc.config.JwtConfig;
+import com.etotem.cfc.config.JwtInterceptor;
+import com.etotem.cfc.controller.auth.AuthController;
+import com.etotem.cfc.entity.User;
+import com.etotem.cfc.mapper.UserMapper;
+import com.etotem.cfc.service.UserService;
+import io.jsonwebtoken.Jwts;
+import io.jsonwebtoken.SignatureAlgorithm;
+import io.jsonwebtoken.security.Keys;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import org.springframework.mock.web.MockHttpServletRequest;
+
+import javax.crypto.SecretKey;
+import java.io.InputStream;
+import java.lang.reflect.Field;
+import java.lang.reflect.Method;
+import java.lang.reflect.Modifier;
+import java.nio.charset.StandardCharsets;
+import java.util.Collections;
+import java.util.Date;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Scanner;
+import java.util.regex.Pattern;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+/**
+ * 契约级单测:多端登录/会话互斥(能力键 {@code auth.session.mutex},S-cfc-301,TDD-RED 阶段)。
+ *
+ * <p><b>契约溯源</b></p>
+ * <ul>
+ *   <li>需求:{@code tests/user-scenarios/应用场景总览.md} SC-P-85(业务域 L,多端登录/会话互斥)——
+ *       目标同账号多设备;流程:新设备登录 → 旧设备踢下线/二次验证;边界:异常设备风控;退出清 token。
+ *       模块:{@code AuthController}。同因 SC-X-17(跨端会话互斥)。</li>
+ *   <li>设计:{@code docs/superpowers/api/API_REFERENCE.md} §4.1 认证与用户 {@code /api/auth}
+ *       (登录/登出 token 生命周期);模块 {@code AuthController}。</li>
+ *   <li>契约缺口锚点(API_REFERENCE §4.63.10 SC-P-85 → 缺口 G-5;§4.65.7 SC-X-17 → 缺口 X-G-2):
+ *       <b>无 token 互斥/单点踢下线(无 tokenVersion/kickout/blacklist/会话注册表;JWT 无状态)</b>。</li>
+ * </ul>
+ *
+ * <p><b>契约目标(GREEN 需实现,当前 src/main 未落地 → 本测试预期失败/红)</b></p>
+ * <ul>
+ *   <li><b>互斥载体</b>:{@code users.token_version}(会话版本号)列 + {@code User.tokenVersion} 字段,
+ *       每次成功登录/签发 token 递增(旧 token 全部失效 = 旧设备被踢)。</li>
+ *   <li><b>token 携带会话版本</b>:{@code JwtConfig} 签发的 JWT claims 必须含 {@code tokenVersion}
+ *       (对应 {@code users.token_version}),并有版本 claim 常量/读取入口。</li>
+ *   <li><b>校验接入互斥</b>:{@code JwtInterceptor}(受保护路径)与 {@code AuthController.verifyToken}
+ *       须校验 token 内 {@code tokenVersion} 与当前 {@code users.token_version} 一致,不一致 → 401
+ *       (旧设备被踢下线)。</li>
+ *   <li><b>登录旋转版本</b>:登录族(phone-login / wechat-login / silent-login / sso-login /
+ *       switch-role)签发新 token 前须递增会话版本,使旧 token 全部失效。</li>
+ *   <li><b>退出清 token</b>:{@code AuthController} 应提供登出端点(退出清 token → 会话失效)。</li>
+ *   <li><b>异常设备风控</b>:登录族应具备异常设备风控入口(异常设备二次验证)。</li>
+ * </ul>
+ *
+ * <p><b>实现现状(本分支 src/main 核实)</b>:{@code schema.sql} 无 {@code token_version} /
+ * {@code user_session} / {@code kickout}(0 命中);{@code User} 实体无 {@code tokenVersion} 字段
+ * (0 命中);{@code JwtConfig} 无版本 claim 常量(0 个 {@code static final String});
+ * {@code AuthController} 无 {@code logout} 端点(0 命中);全仓无 {@code DeviceRisk} 载体。</p>
+ *
+ * <p><b>测试风格</b>:纯 Mockito + 反射 + 真实 {@code JwtConfig}(无 Spring 容器 / 无 DB /
+ * 无外部微信服务),与同批 RED 契约测试({@code TeamProfitHookContractTest} /
+ * {@code TeamStarMultiplierContractTest} / {@code TeamProfitPipelineContractTest} /
+ * {@code FamilyJoinValidationRulesContractTest})一致——能编译通过、能运行、断言失败(红),
+ * 且失败断言原文清晰可贴,GREEN 阶段实现后自动转绿。</p>
+ */
+class AuthSessionMutexContractRedTest {
+
+    /** 契约要求存在的 users.token_version 列(会话版本号载体) */
+    private static final String COLUMN_TOKEN_VERSION = "token_version";
+
+    /** 契约要求 User 实体存在的会话版本字段 */
+    private static final String FIELD_TOKEN_VERSION = "tokenVersion";
+
+    /** 契约要求 JWT claims 携带的会话版本 claim 键 */
+    private static final String CLAIM_TOKEN_VERSION = "tokenVersion";
+
+    /** 契约要求的登出端点路径(退出清 token) */
+    private static final String LOGOUT_PATH = "logout";
+
+    /** 测试用 JWT 密钥(≥32 字节,与 JwtConfig.getSigningKey 的 hmacShaKeyFor 分支一致) */
+    private static final String TEST_SECRET =
+            "session-mutex-contract-test-secret-key-0123456789abcdef";
+    private static final long TEST_EXPIRATION_MS = 3_600_000L;
+    private static final Long USER_ID = 100L;
+
+    // ------------------------------------------------------------------
+    // 正常流 N1:会话互斥载体 users.token_version + User.tokenVersion
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("正常流-N1-a:schema.sql 的 users 表应含 token_version 列(会话版本号载体)")
+    void schemaSql_usersHasTokenVersionColumn() {
+        String schema = readSchemaSql();
+        assertTrue(schema.contains(COLUMN_TOKEN_VERSION),
+                "[auth.session.mutex] schema.sql 的 users 表缺少 " + COLUMN_TOKEN_VERSION
+                        + " 列:契约要求以 users.token_version 作为会话版本号载体,"
+                        + "每次登录递增、旧 token 全部失效(SC-P-85 缺口 G-5)。");
+    }
+
+    @Test
+    @DisplayName("正常流-N1-b:User 实体应含 tokenVersion 字段(映射 users.token_version)")
+    void userEntity_hasTokenVersionField() {
+        boolean hasField = false;
+        for (Field f : User.class.getDeclaredFields()) {
+            if (FIELD_TOKEN_VERSION.equals(f.getName())) {
+                hasField = true;
+                break;
+            }
+        }
+        assertTrue(hasField,
+                "[auth.session.mutex] User 实体缺少 " + FIELD_TOKEN_VERSION
+                        + " 字段:契约要求承载会话版本号(对应 users.token_version),"
+                        + "供 JwtInterceptor / AuthController.verifyToken 比对踢出旧设备(SC-P-85)。");
+    }
+
+    // ------------------------------------------------------------------
+    // 正常流 N2:token 签发应携带会话版本 claim
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("正常流-N2:JwtConfig 签发的 token claims 应含 tokenVersion(会话版本)")
+    void jwtConfig_issuedTokenCarriesTokenVersionClaim() throws Exception {
+        JwtConfig jwtConfig = realJwtConfig();
+        String token = jwtConfig.generateToken(USER_ID, Collections.singletonList("parent"));
+        Object versionClaim = jwtConfig.parseToken(token).get(CLAIM_TOKEN_VERSION);
+        assertNotNull(versionClaim,
+                "[auth.session.mutex] JwtConfig.generateToken 签发的 JWT claims 缺少 "
+                        + CLAIM_TOKEN_VERSION + ":契约要求每次签发携带当前 users.token_version,"
+                        + "校验层据此识别并踢出旧设备 token(SC-P-85 缺口 G-5)。");
+    }
+
+    @Test
+    @DisplayName("正常流-N2-b:JwtConfig 应声明会话版本 claim 常量/读取入口")
+    void jwtConfig_declaresTokenVersionClaimAccessor() {
+        Class<?> clazz = JwtConfig.class;
+        boolean hasConstant = false;
+        for (Field f : clazz.getDeclaredFields()) {
+            if (Modifier.isPublic(f.getModifiers()) && Modifier.isStatic(f.getModifiers())
+                    && Modifier.isFinal(f.getModifiers())
+                    && f.getType() == String.class
+                    && f.getName().toUpperCase().contains("VERSION")) {
+                hasConstant = true;
+                break;
+            }
+        }
+        boolean hasAccessor = false;
+        for (Method m : clazz.getDeclaredMethods()) {
+            if (m.getName().toLowerCase().contains("tokenversion")
+                    || m.getName().toLowerCase().contains("sessionversion")) {
+                hasAccessor = true;
+                break;
+            }
+        }
+        assertTrue(hasConstant || hasAccessor,
+                "[auth.session.mutex] JwtConfig 应声明会话版本 claim 常量(如 CLAIM_TOKEN_VERSION)"
+                        + "或读取入口(如 getTokenVersion(Claims)):校验层须从 JWT 中读出会话版本"
+                        + "与 users.token_version 比对(SC-P-85 缺口 G-5)。");
+    }
+
+    // ------------------------------------------------------------------
+    // 正常流 N3:登录族签发新 token 前应递增会话版本(旧设备被踢)
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("正常流-N3:UserService 登录/签发入口应提供会话版本旋转方法")
+    void userService_loginRotatesTokenVersion() {
+        Pattern rotate = Pattern.compile(
+                "(?i).*(tokenversion|sessionversion|kickout|expireoldsession|issuesession|"
+                        + "rotatesession|invalidatesession|bump.*version|advance.*version).*");
+        boolean found = false;
+        for (Method m : UserService.class.getDeclaredMethods()) {
+            if (rotate.matcher(m.getName()).matches()) {
+                found = true;
+                break;
+            }
+        }
+        assertTrue(found,
+                "[auth.session.mutex] UserService 应提供会话版本旋转方法(如 incrementTokenVersion/"
+                        + "rotateSession/expireOldSessions):登录族(phone/wechat/silent/sso-login/"
+                        + "switch-role)签发新 token 前须递增 users.token_version,旧 token 全部失效"
+                        + "(新设备登录 → 旧设备踢下线,SC-P-85)。");
+    }
+
+    // ------------------------------------------------------------------
+    // 正常流 N4:校验接入互斥(JwtInterceptor + AuthController.verifyToken)
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("正常流-N4-a:JwtInterceptor 应注入会话互斥校验器(旧版本 token → 401)")
+    void jwtInterceptor_injectsSessionMutexChecker() {
+        boolean injected = false;
+        for (Field f : JwtInterceptor.class.getDeclaredFields()) {
+            String type = f.getType().getName().toLowerCase();
+            String name = f.getName().toLowerCase();
+            if (type.contains("mutex") || type.contains("session") || type.contains("version")
+                    || name.contains("sessionmutex") || name.contains("sessionregistry")
+                    || name.contains("tokenversion")) {
+                injected = true;
+                break;
+            }
+        }
+        assertTrue(injected,
+                "[auth.session.mutex] JwtInterceptor 应注入会话互斥校验器(会话注册表/版本校验服务):"
+                        + "受保护路径解析 token 后须校验会话版本一致,不一致 → 401(旧设备被踢,SC-P-85)。");
+    }
+
+    @Test
+    @DisplayName("正常流-N4-b:AuthController.verifyToken 对旧会话版本 token 应返回 401")
+    void authController_verifyToken_rejectsStaleSession() throws Exception {
+        // 构造一个携带 tokenVersion=1 的合法 token(当前 users.token_version 已推进 > 1 → 会话已过期)
+        SecretKey key = Keys.hmacShaKeyFor(TEST_SECRET.getBytes(StandardCharsets.UTF_8));
+        Date now = new Date();
+        Map<String, Object> claims = new HashMap<>();
+        claims.put("userId", USER_ID);
+        claims.put("role", "parent");
+        claims.put("roles", Collections.singletonList("parent"));
+        claims.put(CLAIM_TOKEN_VERSION, 1L);
+        String staleToken = Jwts.builder()
+                .setClaims(claims)
+                .setSubject(String.valueOf(USER_ID))
+                .setIssuedAt(now)
+                .setExpiration(new Date(now.getTime() + TEST_EXPIRATION_MS))
+                .signWith(key, SignatureAlgorithm.HS256)
+                .compact();
+
+        // 真实 JwtConfig + mock UserMapper 注入 AuthController(verifyToken 只依赖这两个)
+        JwtConfig jwtConfig = realJwtConfig();
+        UserMapper userMapper = mock(UserMapper.class);
+        User user = new User();
+        user.setId(USER_ID);
+        user.setFamilyId(null);
+        when(userMapper.selectById(USER_ID)).thenReturn(user);
+        AuthController controller = new AuthController();
+        inject(controller, "jwtConfig", jwtConfig);
+        inject(controller, "userMapper", userMapper);
+
+        MockHttpServletRequest request = new MockHttpServletRequest();
+        request.setMethod("POST");
+        request.setRequestURI("/api/auth/verify");
+        request.addHeader("Authorization", "Bearer " + staleToken);
+
+        Result<Map<String, Object>> result = controller.verifyToken(request);
+
+        assertEquals(401, result.getCode().intValue(),
+                "[auth.session.mutex] AuthController.verifyToken 对旧会话版本 token 应返回 401"
+                        + "(会话已过期/旧设备被踢),当前返回 code=" + result.getCode()
+                        + ",未实现会话版本校验(SC-P-85 缺口 G-5)。");
+    }
+
+    // ------------------------------------------------------------------
+    // 边界流 B1:退出清 token(AuthController 登出端点)
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("边界流-B1:AuthController 应声明登出端点(退出清 token)")
+    void authController_declaresLogoutEndpoint() {
+        boolean hasLogout = false;
+        for (Method m : AuthController.class.getDeclaredMethods()) {
+            if (LOGOUT_PATH.equals(m.getName())
+                    || m.getName().toLowerCase().contains(LOGOUT_PATH)) {
+                hasLogout = true;
+                break;
+            }
+        }
+        assertTrue(hasLogout,
+                "[auth.session.mutex] AuthController 缺少登出端点(logout):SC-P-85 边界要求"
+                        + "「退出清 token」——登出须使当前会话失效(递增会话版本/移除会话注册表),"
+                        + "而非仅前端清除本地存储(缺口 G-5)。");
+    }
+
+    // ------------------------------------------------------------------
+    // 边界流 B2:异常设备风控(异常设备二次验证)
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("边界流-B2:登录族应具备异常设备风控入口(异常设备二次验证)")
+    void loginFlow_declaresDeviceRiskGuard() {
+        boolean hasRiskGuard = loadClass("com.etotem.cfc.service.DeviceRiskService") != null;
+        if (!hasRiskGuard) {
+            Pattern risk = Pattern.compile("(?i).*(devicerisk|abnormaldevice|deviceverify|"
+                    + "riskdevice|suspiciousdevice).*");
+            for (Method m : UserService.class.getDeclaredMethods()) {
+                if (risk.matcher(m.getName()).matches()) {
+                    hasRiskGuard = true;
+                    break;
+                }
+            }
+        }
+        assertTrue(hasRiskGuard,
+                "[auth.session.mutex] 登录族缺少异常设备风控入口(DeviceRiskService 或 deviceRisk/"
+                        + "isAbnormalDevice 方法):SC-P-85 边界「异常设备风控」要求对异常设备触发"
+                        + "二次验证/拦截(缺口 G-5)。");
+    }
+
+    // ------------------------------------------------------------------
+    // 权限流(不适用):会话互斥属认证层(JwtInterceptor),无角色维度
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("权限流:会话互斥为认证层机制,无角色权限维度,权限流不适用")
+    void permissionFlow_notApplicable() {
+        // 说明性用例:契约 AC 为「新设备登录 → 旧设备踢下线/二次验证 + 退出清 token」,
+        // 由 JwtInterceptor 认证层统一执行,不区分角色(parent/child/teacher),无授权维度。
+        // 不产生断言失败;仅为三流覆盖标注「不适用」。
+        assertTrue(true, "权限流不适用:auth.session.mutex 为认证层会话互斥,无角色权限维度。");
+    }
+
+    // ------------------------------------------------------------------
+    // 辅助
+    // ------------------------------------------------------------------
+
+    private JwtConfig realJwtConfig() throws Exception {
+        JwtConfig cfg = new JwtConfig();
+        inject(cfg, "secret", TEST_SECRET);
+        inject(cfg, "expiration", TEST_EXPIRATION_MS);
+        return cfg;
+    }
+
+    private void inject(Object target, String fieldName, Object value) throws Exception {
+        Field f = target.getClass().getDeclaredField(fieldName);
+        f.setAccessible(true);
+        f.set(target, value);
+    }
+
+    private Class<?> loadClass(String name) {
+        try {
+            return Class.forName(name, false, Thread.currentThread().getContextClassLoader());
+        } catch (ClassNotFoundException e) {
+            return null;
+        }
+    }
+
+    private String readSchemaSql() {
+        try (InputStream is = getClass().getClassLoader().getResourceAsStream("schema.sql")) {
+            if (is == null) {
+                return "";
+            }
+            try (Scanner scanner = new Scanner(is, StandardCharsets.UTF_8.name())) {
+                scanner.useDelimiter("\\A");
+                return scanner.hasNext() ? scanner.next() : "";
+            }
+        } catch (Exception e) {
+            return "";
+        }
+    }
+}