Refresh Token

<dependency>
    <groupId>top.continew.starter</groupId>
    <artifactId>continew-starter-auth-refresh-token</artifactId>
</dependency>

--- ### Sa-Token 配置（JWT 模式为本模块前置条件）
sa-token:
  jwt-secret-key: ${SA_TOKEN_JWT_SECRET}

--- ### Refresh Token 配置
continew-starter:
  refresh-token:
    # 服务端密钥（必填，≥ 32 字符）：派生令牌指纹密钥与轮换快照加密密钥
    # 生产环境必须通过环境变量注入高熵随机值，且禁止与 JWT 密钥复用
    secret: ${REFRESH_TOKEN_SECRET}
    # Cookie 传输（COOKIE 模式相关）
    cookie-name: refresh_token
    cookie-path: /
    # 生产环境必须开启；关闭时启动告警，需显式设置 cookie-insecure-allowed=true 确认知情
    cookie-secure: ${COOKIE_SECURE:false}
    cookie-same-site: Lax
    # 跨源前端 Origin 白名单（同源请求无需配置），支持 http[s]://*.example.com 子域通配符
    cookie-allowed-origins:
      - https://admin.example.com
    # 轮换宽限期（幂等重放窗口，秒）与待恢复快照窗口（秒）
    rotation-grace-period: 30
    rotation-pending-period: 60
    # 刷新限流：单个 IP / 单个会话在窗口内的最大请求数，0 表示交由网关限流
    ip-rate-limit: 60
    ip-rate-limit-period: 60
    session-rate-limit: 10
    session-rate-limit-period: 60
    # 反向代理场景：可信代理地址与 X-Forwarded-For 跳数（0 表示不解析转发地址）
    trusted-proxy-addresses: [ ]
    trusted-proxy-hops: 0

public class UserContext implements RefreshSessionPrincipal {

    @Override
    public Long getUserId() { return id; }

    @Override
    public String getUsername() { return username; }

    @Override
    public String getNickname() { return nickname; }

    @Override
    public Long getTenantId() { return tenantId; } // 无租户场景返回 null

    @Override
    public String getIp() { return ip; }

    @Override
    public String getAddress() { return address; }

    @Override
    public String getBrowser() { return browser; }

    @Override
    public String getOs() { return os; }
}

new RefreshClientPolicy(
    "web",                          // clientId：客户端 ID
    "WEB",                          // clientType：客户端类型（同类型互斥登录的维度）
    30 * 24 * 60 * 60L,             // refreshTokenTimeout：Refresh Token 有效期（秒）
    RefreshTokenModeEnum.COOKIE,    // refreshTokenMode：COOKIE / BODY
    true,                           // concurrent：是否允许并发登录
    SessionReplacementScope.CURRENT_CLIENT_TYPE, // 顶人下线范围（另可选 ALL_CLIENT_TYPES）
    5,                              // maxLoginCount：最大登录数量（-1 不限制）
    LogoutReasonEnum.REPLACED       // overflowLogoutMode：被挤下线时的提示语
);

LoginResp loginResp = refreshTokenService.executeLoginPolicy(user.getId(),
    client.getClientId(), tenantId, securityVersion -> {
        // ① 锁内最终复查：重载用户/客户端状态、校验租户可用性
        UserDO latestUser = userService.reloadAndCheck(user.getId());
        // ② 组装登录尝试：携带当前请求的两类凭证（用于覆盖旧 Cookie 的会话清理）
        return new LoginAttempt<>(latestUser.getId(), toClientPolicy(client),
            StpUtil.getTokenValue(),                      // 当前 Access Token
            refreshTokenService.resolve(null, request),   // 当前 Refresh Token（Cookie）
            // ③ 新令牌签发函数：真正执行 StpUtil.login 并创建 Refresh Session
            () -> doIssue(latestUser, client, tenantId, request, response, securityVersion));
    });

/** 新令牌签发函数 */
private LoginResp doIssue(UserDO user, ClientResp client, Long tenantId, /* ... */) {
    String sessionId = refreshTokenService.newSessionId();
    // Sa-Token 只管短期 Access Token；并发/顶人/最大登录数由本模块执行
    SaLoginParameter param = new SaLoginParameter();
    param.setTimeout(accessTokenTimeout);
    // 关键：sid 必须写入 Access Token 的扩展声明，刷新时服务端据此核对两类凭证同源
    param.setExtraData(Map.of(AuthSessionConstants.SESSION_ID_CLAIM, sessionId));
    StpUtil.login(user.getId(), param);
    String accessToken = StpUtil.getTokenValue();
    // 创建 Refresh Session：COOKIE 模式写入 HttpOnly Cookie，BODY 模式返回明文给客户端
    String refreshToken = refreshTokenService.issue(sessionId, userContext, clientPolicy,
        securityVersion, response, accessToken, accessTokenTimeout);
    return LoginResp.builder().accessToken(accessToken).build(); // BODY 模式补充 refreshToken
}

@SaIgnore
@TenantIgnore
@PostMapping("/refresh")
public LoginResp refresh(@RequestBody(required = false) RefreshTokenReq req,
    HttpServletRequest request, HttpServletResponse response) {
    // ① 提取令牌：Cookie 与请求体同时出现时直接拒绝（传输边界）
    String rawRefreshToken = refreshTokenService.resolve(req == null ? null
        : req.getRefreshToken(), request);
    // ② 按可信客户端地址限流（解析不可信 Token 之前执行，防锁争抢）
    refreshTokenService.checkRequestRateLimit(request);
    // ③ Cookie 模式校验请求 Origin（CSRF），并核对 UA 等请求一致性
    refreshTokenService.validateRequest(rawRefreshToken, request);
    // ④ 原子轮换：签发适配由业务方提供
    return refreshTokenService.rotate(rawRefreshToken, response,
        session -> refreshAccessTokenIssuer.issue(session, request, response));
}

@Component
@RequiredArgsConstructor
public class RefreshAccessTokenIssuerImpl implements RefreshAccessTokenIssuer {

    @Override
    public IssuedAccessToken issue(RefreshSession session, HttpServletRequest request,
        HttpServletResponse response) {
        // 签发前复查：客户端/用户/租户是否仍可用（禁用、过期、凭证变更在此拦截）
        ClientResp client = clientService.getByClientId(session.getClientId());
        if (client == null || DisEnableStatusEnum.DISABLE.equals(client.getStatus())) {
            throw RefreshTokenException.unauthorized("登录状态已失效，请重新登录");
        }
        // 按会话中固化的租户上下文重新登录 Sa-Token，生成新 Access Token
        LoginResp resp = authTokenService.issueByRefreshSession(session, request, response);
        return new IssuedAccessToken(resp.getAccessToken(), resp.getExpiresIn(),
            resp.getTenantId());
    }
}

// ① Cookie 模式先校验请求来源（防止跨站伪造注销）
refreshTokenService.validateCookieOrigin(request);
// ② 提取并校验令牌（失败时 clearCookie 清理残留 Cookie）
String refreshToken = refreshTokenService.resolve(req.getRefreshToken(), request);
refreshTokenService.validateRequest(refreshToken, request);
// ③ 撤销 Refresh Session（含实时 WebSocket 下线通知）
refreshTokenService.revokeCurrent(StpUtil.getTokenValue(), refreshToken);
// ④ 注销 Sa-Token 侧的 Access Token 并清理 Cookie
StpUtil.logoutByTokenValue(accessToken);
refreshTokenService.clearCookie(response);

// 查询：tenantId 为空时查询全部租户
List<SessionView> sessions = sessionQueryService.listSessions(tenantId);
sessionQueryService.getSession(sessionId);

// 撤销：按用户 / 租户 / 客户端 / 会话 ID
sessionInvalidationService.invalidateUser(userId);     // 改密、禁用后调用
sessionInvalidationService.invalidateTenant(tenantId); // 租户禁用、套餐变更后调用
sessionInvalidationService.invalidateClient(clientId); // 客户端配置变更后调用
sessionInvalidationService.revokeSession(sessionId);   // 管理端强制下线

@AuthPolicyWriteLocked(TenantArgumentPolicyLockTargetResolver.class)
@CacheEvict(cacheNames = "TenantServiceImpl.update", key = "#req.id")
public void update(UpdateTenantReq req, Long id) { /* ... */ }