Merge pull request #41 from yyyCode/harden/device-fingerprint-layer

harden: 设备指纹防构造加固（第 1~3 层）

Author: yyyCode

.github/workflows/ci.yml

@@ -250,9 +250,10 @@ jobs:
         with:
           name: gateway-jar
           path: gateway
-      - name: Deploy via Docker（构建镜像 + 重启容器 + 注入 JWT secret）
+      - name: Deploy via Docker（构建镜像 + 重启容器 + 注入 JWT / 设备令牌 secret）
         env:
           OPENBLOG_JWT_SECRET: ${{ secrets.OPENBLOG_JWT_SECRET }}
+          OPENBLOG_DEVICE_TOKEN_SECRET: ${{ secrets.OPENBLOG_DEVICE_TOKEN_SECRET }}
         run: |
           set -euo pipefail
           TARGET_DIR="/www/wwwroot/java/openblog-gateway"
@@ -273,8 +274,9 @@ jobs:
           cp "$JAR_FILE" "$TARGET_JAR"
           cp deploy/gateway/Dockerfile deploy/gateway/docker-compose.yml deploy/gateway/.dockerignore "$TARGET_DIR/"
 
-          # 4. JWT secret 写入服务器 .env（compose 自动加载）
-          printf 'OPENBLOG_JWT_SECRET=%s\n' "$OPENBLOG_JWT_SECRET" > "$TARGET_DIR/.env"
+          # 4. JWT / 设备令牌 secret 写入服务器 .env（compose 自动加载）
+          printf 'OPENBLOG_JWT_SECRET=%s\nOPENBLOG_DEVICE_TOKEN_SECRET=%s\n' \
+            "$OPENBLOG_JWT_SECRET" "$OPENBLOG_DEVICE_TOKEN_SECRET" > "$TARGET_DIR/.env"
 
           # 5. Docker 构建并启动容器
           cd "$TARGET_DIR"

OpenBlog-business/src/main/java/com/yqz/openblog/config/AuthSecurityProperties.java

@@ -10,6 +10,7 @@ public class AuthSecurityProperties {
 
     private Slider slider = new Slider();
     private LoginLockout loginLockout = new LoginLockout();
+    private DeviceLockout deviceLockout = new DeviceLockout();
     private EmailCode emailCode = new EmailCode();
 
     public Slider getSlider() {
@@ -28,6 +29,14 @@ public void setLoginLockout(LoginLockout loginLockout) {
         this.loginLockout = loginLockout;
     }
 
+    public DeviceLockout getDeviceLockout() {
+        return deviceLockout;
+    }
+
+    public void setDeviceLockout(DeviceLockout deviceLockout) {
+        this.deviceLockout = deviceLockout;
+    }
+
     public EmailCode getEmailCode() {
         return emailCode;
     }
@@ -111,6 +120,60 @@ public void setLockoutSeconds(int lockoutSeconds) {
         }
     }
 
+    /**
+     * 设备级失败封禁（按设备指纹计，与 IP 锁互补）。
+     * 指纹是网关校验过的弱信号：挡「换 IP 但设备固定」的爆破；设备指纹非权威身份，
+     * 对「每请求换指纹」的脚本无效——那由网关层（指纹轮换守卫 + 签名设备令牌）负责。
+     * 误伤面比 IP 锁小（只锁定单一指纹），故默认开启；IP 锁因 NAT 误伤在生产关闭。
+     */
+    public static class DeviceLockout {
+        private boolean enabled = true;
+        /**
+         * 同一设备（指纹）在窗口内允许的最大失败次数（仅统计密码错误）。
+         */
+        private int maxFailuresPerFp = 5;
+        /**
+         * 失败计数滑动窗口（秒）。
+         */
+        private int failureWindowSeconds = 300;
+        /**
+         * 触发锁定后的禁止登录时长（秒）。
+         */
+        private int lockoutSeconds = 900;
+
+        public boolean isEnabled() {
+            return enabled;
+        }
+
+        public void setEnabled(boolean enabled) {
+            this.enabled = enabled;
+        }
+
+        public int getMaxFailuresPerFp() {
+            return maxFailuresPerFp;
+        }
+
+        public void setMaxFailuresPerFp(int maxFailuresPerFp) {
+            this.maxFailuresPerFp = maxFailuresPerFp;
+        }
+
+        public int getFailureWindowSeconds() {
+            return failureWindowSeconds;
+        }
+
+        public void setFailureWindowSeconds(int failureWindowSeconds) {
+            this.failureWindowSeconds = failureWindowSeconds;
+        }
+
+        public int getLockoutSeconds() {
+            return lockoutSeconds;
+        }
+
+        public void setLockoutSeconds(int lockoutSeconds) {
+            this.lockoutSeconds = lockoutSeconds;
+        }
+    }
+
     public static class EmailCode {
         /**
          * 验证码有效时间（秒），默认 5 分钟。

OpenBlog-business/src/main/java/com/yqz/openblog/user/service/AccountDeviceService.java

@@ -0,0 +1,61 @@
+package com.yqz.openblog.user.service;
+
+import com.yqz.openblog.redis.core.RedisKeys;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.data.redis.core.StringRedisTemplate;
+import org.springframework.stereotype.Service;
+
+import java.time.Duration;
+
+/**
+ * 账号 ↔ 设备指纹绑定记录（设备指纹防构造第 3 层）。
+ * <p>
+ * 登录成功后把本次指纹记为该账号的「已知设备」（Redis SET，值=已过网关格式校验的指纹）。
+ * 目的不是立刻拦截（新设备二次验证不在本期），而是留下可观测的绑定事实：日志可见「新设备首次登录」，
+ * 后续演进（新设备 + 新 IP → 二次验证、异常设备告警）以本集合为基线。
+ * <p>
+ * 契约：只作记录，不做判定——Redis 故障仅打 warn、绝不阻断登录（与全局 fail-open 一致）。
+ */
+@Service
+public class AccountDeviceService {
+
+    private static final Logger log = LoggerFactory.getLogger(AccountDeviceService.class);
+    /** 已知设备集合保留时长：指纹是弱信号，按 90 天滑动保留即可。 */
+    private static final Duration DEVICE_TTL = Duration.ofDays(90);
+
+    private final StringRedisTemplate redisTemplate;
+
+    public AccountDeviceService(StringRedisTemplate redisTemplate) {
+        this.redisTemplate = redisTemplate;
+    }
+
+    /**
+     * 登录成功后把指纹记为该账号已知设备。
+     *
+     * @param userId 账号 id
+     * @param fp     已通过格式校验（{@code ^[A-Za-z0-9-]{16,64}$}）的设备指纹；null/空则跳过
+     */
+    public void recordLogin(Long userId, String fp) {
+        if (userId == null || fp == null || fp.isBlank()) {
+            return;
+        }
+        try {
+            String key = RedisKeys.accountDevices(userId);
+            Long added = redisTemplate.opsForSet().add(key, fp);
+            // 每次登录都滚动续 TTL：活跃账号的"已知设备"集合不会因 90 天静默消失；停用 90 天后自然过期清理
+            redisTemplate.expire(key, DEVICE_TTL);
+            if (added != null && added > 0) {
+                log.info("account first-seen device login: userId={} fp={}", userId, mask(fp));
+            }
+        } catch (RuntimeException e) {
+            // Redis 不可用 → 仅记录失败，登录放行（fail-open）
+            log.warn("record account device failed, allow login: userId={} err={}", userId, e.toString());
+        }
+    }
+
+    /** 日志脱敏：只留首 6 + 末 2 字符，指纹也是标识符，不全量落日志。 */
+    private static String mask(String fp) {
+        return fp.length() <= 8 ? fp : fp.substring(0, 6) + ".." + fp.substring(fp.length() - 2);
+    }
+}

OpenBlog-business/src/main/java/com/yqz/openblog/user/service/AuthService.java

@@ -41,6 +41,7 @@ public class AuthService {
     private final CurrentUser currentUser;
     private final SliderVerificationService sliderVerificationService;
     private final LoginLockoutService loginLockoutService;
+    private final AccountDeviceService accountDeviceService;
     private final MediaService mediaService;
     private final EmailValidator emailValidator;
     private final EmailCodeService emailCodeService;
@@ -53,6 +54,7 @@ public AuthService(UserMapper userMapper,
                         CurrentUser currentUser,
                         SliderVerificationService sliderVerificationService,
                         LoginLockoutService loginLockoutService,
+                        AccountDeviceService accountDeviceService,
                         MediaService mediaService,
                         EmailValidator emailValidator,
                         EmailCodeService emailCodeService) {
@@ -64,6 +66,7 @@ public AuthService(UserMapper userMapper,
         this.currentUser = currentUser;
         this.sliderVerificationService = sliderVerificationService;
         this.loginLockoutService = loginLockoutService;
+        this.accountDeviceService = accountDeviceService;
         this.mediaService = mediaService;
         this.emailValidator = emailValidator;
         this.emailCodeService = emailCodeService;
@@ -119,7 +122,10 @@ public AuthResponse register(RegisterRequest req) {
 
     public AuthResponse login(LoginRequest req) {
         String ipSeg = currentIpKeySegment();
+        // 设备维度（指纹经网关格式校验透传；缺失/非法 → null 不参与设备锁，仅 IP 兜底）
+        String fp = currentDeviceFingerprint();
         loginLockoutService.assertNotLocked(ipSeg);
+        loginLockoutService.assertNotDeviceLocked(fp);
         sliderVerificationService.verifyAndConsume(req.getSliderChallengeId());
 
         User user = userMapper.selectOne(Wrappers.lambdaQuery(User.class).eq(User::getUsername, req.getAccount()));
@@ -128,6 +134,7 @@ public AuthResponse login(LoginRequest req) {
         }
         if (user == null) {
             loginLockoutService.recordPasswordFailure(ipSeg);
+            loginLockoutService.recordDevicePasswordFailure(fp);
             throw new BizException(clientErrorCode(), "账号或密码错误");
         }
 
@@ -136,14 +143,19 @@ public AuthResponse login(LoginRequest req) {
         }
         if ("BANNED".equals(user.getStatus())) {
             loginLockoutService.recordPasswordFailure(ipSeg);
+            loginLockoutService.recordDevicePasswordFailure(fp);
             throw new BizException(4011, "账号已被封禁");
         }
         if (!passwordEncoder.matches(req.getPassword(), user.getPasswordHash())) {
             loginLockoutService.recordPasswordFailure(ipSeg);
+            loginLockoutService.recordDevicePasswordFailure(fp);
             throw new BizException(clientErrorCode(), "账号或密码错误");
         }
 
         loginLockoutService.clearFailures(ipSeg);
+        loginLockoutService.clearDeviceFailures(fp);
+        // 第 3 层：指纹记为该账号的已知设备（fail-open，Redis 故障不阻断登录）
+        accountDeviceService.recordLogin(user.getId(), fp);
 
         String accessToken = jwtService.generateAccessToken(user.getId(), user.getRole().name());
         String refreshToken = jwtService.generateRefreshToken(user.getId());
@@ -314,5 +326,21 @@ private String currentIpKeySegment() {
         String ip = ClientIpResolver.resolve(request);
         return ClientIpResolver.toRedisKeySegment(ip);
     }
+
+    /** 设备指纹 key 片段：网关已正则校验并透传 X-Device-Fingerprint；此处防御性复检，
+     * 缺失/非法一律返回 null（该请求不参与设备锁 / 设备记录，仅 IP 维度兜底）。 */
+    private String currentDeviceFingerprint() {
+        var attrs = RequestContextHolder.getRequestAttributes();
+        if (!(attrs instanceof ServletRequestAttributes sra)) {
+            return null;
+        }
+        String raw = sra.getRequest().getHeader("X-Device-Fingerprint");
+        if (raw == null) {
+            return null;
+        }
+        String fp = raw.trim();
+        // 与网关一致：32 位 hex 为常态；限 16~64 位字母数字-，防注入与超长 Redis key
+        return fp.matches("^[A-Za-z0-9-]{16,64}$") ? fp : null;
+    }
 }
 

OpenBlog-business/src/main/java/com/yqz/openblog/user/service/LoginLockoutService.java

@@ -71,4 +71,49 @@ public void clearFailures(String ipKeySegment) {
         redisOps.delete(RedisKeys.loginFail(ipKeySegment));
         redisOps.delete(RedisKeys.loginLock(ipKeySegment));
     }
+
+    // ==================== 设备维度（与 IP 维度互补，见 AuthSecurityProperties.DeviceLockout） ====================
+    // fpKeySegment 传 null（无指纹设备）一律跳过：该设备不参与设备锁，仍受 IP 锁兜底。
+
+    public void assertNotDeviceLocked(String fpKeySegment) {
+        if (fpKeySegment == null || !authSecurityProperties.getDeviceLockout().isEnabled()) {
+            return;
+        }
+        if (redisOps.hasKey(RedisKeys.deviceLock(fpKeySegment))) {
+            throw new BizException(4292, "该设备登录尝试过于频繁，请稍后再试");
+        }
+    }
+
+    /**
+     * 密码校验失败时调用（设备指纹维度）。
+     */
+    public void recordDevicePasswordFailure(String fpKeySegment) {
+        if (fpKeySegment == null || !authSecurityProperties.getDeviceLockout().isEnabled()) {
+            return;
+        }
+        var cfg = authSecurityProperties.getDeviceLockout();
+        String failKey = RedisKeys.deviceFail(fpKeySegment);
+        Long c = redisOps.increment(failKey).orElse(null);
+        if (c == null) {
+            return;
+        }
+        if (c == 1L) {
+            redisOps.expire(failKey, Duration.ofSeconds(Math.max(30, cfg.getFailureWindowSeconds())));
+        }
+        if (c >= cfg.getMaxFailuresPerFp()) {
+            redisOps.set(RedisKeys.deviceLock(fpKeySegment), "1",
+                    Duration.ofSeconds(Math.max(60, cfg.getLockoutSeconds())));
+        }
+    }
+
+    /**
+     * 登录成功时清除该设备的失败计数与锁定（若存在）。
+     */
+    public void clearDeviceFailures(String fpKeySegment) {
+        if (fpKeySegment == null || !authSecurityProperties.getDeviceLockout().isEnabled()) {
+            return;
+        }
+        redisOps.delete(RedisKeys.deviceFail(fpKeySegment));
+        redisOps.delete(RedisKeys.deviceLock(fpKeySegment));
+    }
 }

OpenBlog-business/src/main/resources/application.yaml

@@ -105,6 +105,14 @@ openblog:
       max-failures-per-ip: 5
       failure-window-seconds: 300
       lockout-seconds: 900
+    # 设备级失败封禁：按设备指纹计（与 IP 锁互补，挡「换 IP 但设备固定」爆破）。
+    # 默认开：只锁定单一指纹、误伤面远小于 IP 锁（IP 锁因 NAT 误伤在此关闭）。
+    # 指纹是弱信号，对「每请求换指纹」脚本无效——由网关层指纹轮换守卫 + 签名设备令牌负责。
+    device-lockout:
+      enabled: true
+      max-failures-per-fp: 5
+      failure-window-seconds: 300
+      lockout-seconds: 900
     email-code:
       code-ttl-seconds: 300
       resend-cooldown-seconds: 60