暂存提交

auth/JWT-JWKS-CONTRACT.md

@@ -0,0 +1,76 @@
+# 国内与海外 JWT/JWKS 冻结契约
+
+## 双轨边界
+
+### 国内现有链路
+
+- 登录、刷新、退出和代登录接口保持原契约，不修改 `TokenResponse`。
+- 签名算法保持 `HS256`，继续使用 `JWT_SECRET`。
+- Access Token 默认有效期保持 24 分钟，Refresh Token 默认有效期保持 7 天。
+- 业务服务继续使用国内 HMAC 验签与 Redis 会话校验，账号停用、退出和 Token 版本失效规则不变。
+- 国内 Token 保持现有 snake_case 声明，不增加海外 `aud`，也不要求配置 RSA/JWK。
+
+### 海外尾程链路
+
+- 海外能力默认关闭：`OVERSEAS_JWT_ENABLED=false`。
+- 已通过国内 HS256 与 Redis 校验的登录用户调用 `POST /api/auth/overseas/token`，兑换独立的海外短时 Token。
+- 海外 Token 使用 `RS256`，默认有效期 15 分钟，不签发 Refresh Token。
+- 尾程必须配置 `baiyue.security.jwt-mode=jwks` 和 `baiyue.security.session-mode=claims`，只做 JWKS 验签和本地安全投影校验，不创建或访问国内 Redis 会话校验器。
+- 海外功能未启用时，兑换接口返回“海外认证未启用”；JWKS Controller、海外签发服务和 `overseasJwtEncoder` 均不创建，Auth 仍可正常启动并签发国内 HS256 Token。
+
+## 海外签发契约
+
+- `issuer`：`auth-service`
+- `audience`：`lastleg-api`
+- 算法白名单：仅 `RS256`
+- Access Token 默认有效期：15 分钟
+- 兑换接口：`POST /api/auth/overseas/token`
+- JWKS 路径：`/api/auth/.well-known/jwks.json`
+- Auth 直连地址：`http://{auth-host}:9100/api/auth/.well-known/jwks.json`
+- JWKS HTTP 缓存：5 分钟，响应 `Cache-Control: public, max-age=300`
+
+海外 Token 的 JSON 声明名称和类型固定如下：
+
+| 声明 | JSON 类型 | 说明 |
+|---|---|---|
+| `sub` | string | 用户 ID 的字符串形式 |
+| `jti` | string | Token 唯一标识 |
+| `iat` | number | 签发时间 |
+| `exp` | number | 过期时间 |
+| `aud` | string array | 固定包含 `lastleg-api` |
+| `userId` | number | 认证用户 ID |
+| `tenantId` | number | 当前客户 ID；平台账号为平台作用域值 |
+| `appCode` | string | `PLATFORM` 或 `MERCHANT` |
+| `roles` | string array | 当前角色编码快照 |
+| `authorities` | string array | 当前权限编码快照 |
+| `permissionVersion` | number | IAM 单调权限版本 |
+
+海外 Token 从 V1 起只使用上述 camelCase 自定义声明，不读取国内 snake_case 声明。
+
+## 海外配置
+
+```yaml
+baiyue:
+  security:
+    overseas-jwt:
+      enabled: ${OVERSEAS_JWT_ENABLED:false}
+      issuer: ${OVERSEAS_JWT_ISSUER:auth-service}
+      audience: ${OVERSEAS_JWT_AUDIENCE:lastleg-api}
+      rsa-jwk-set: ${OVERSEAS_JWT_RSA_JWK_SET:}
+      current-kid: ${OVERSEAS_JWT_CURRENT_KID:}
+      access-token-ttl: ${OVERSEAS_ACCESS_TOKEN_TTL:15m}
+```
+
+只有显式启用海外能力时才校验 `OVERSEAS_JWT_RSA_JWK_SET` 和 `OVERSEAS_JWT_CURRENT_KID`。启用后配置不合法必须启动失败，避免错误密钥签发。
+
+## 密钥轮换
+
+- JWK Set 只允许 RSA 密钥。
+- `OVERSEAS_JWT_CURRENT_KID` 必须指向唯一的当前签名私钥，JWT Header 写入该 `kid`。
+- 非当前密钥只能保留公钥；JWKS 只发布公钥，不得输出私钥参数。
+- 轮换时同时发布当前公钥和上一公钥，上一公钥至少保留 20 分钟，即 15 分钟最大 Token 生命周期加 5 分钟 JWKS 缓存。
+- 重叠期结束后移除上一公钥，禁止复用历史 `kid`。
+
+## IAM 安全事件
+
+安全事件的 `eventType`、版本、状态枚举和 payload 以 `iam/SECURITY-EVENT-AUDIT.md` 为唯一契约。尾程维护用户状态、客户状态和权限版本的本地投影，请求期间不反向同步访问国内 IAM。

auth/src/main/java/com/baiyue/auth/client/AuthorizationSnapshot.java

@@ -20,4 +20,5 @@ public class AuthorizationSnapshot {
     private String clientType;
     private Set<String> roles;
     private Set<String> permissions;
+    private Long permissionVersion;
 }

auth/src/main/java/com/baiyue/auth/config/AuthSecurityConfig.java

@@ -1,6 +1,5 @@
 package com.baiyue.auth.config;
 
-import com.nimbusds.jose.jwk.source.ImmutableSecret;
 import com.baiyue.common.security.JwtAuthenticationFilter;
 import org.springframework.boot.context.properties.EnableConfigurationProperties;
 import org.springframework.context.annotation.Bean;
@@ -10,14 +9,11 @@ import org.springframework.security.config.http.SessionCreationPolicy;
 import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
 import org.springframework.security.crypto.password.PasswordEncoder;
 import org.springframework.security.oauth2.jose.jws.MacAlgorithm;
-import org.springframework.security.oauth2.jwt.JwtEncoder;
-import org.springframework.security.oauth2.jwt.NimbusJwtEncoder;
 import org.springframework.security.web.SecurityFilterChain;
 import org.springframework.security.web.AuthenticationEntryPoint;
 import org.springframework.security.web.access.AccessDeniedHandler;
 import org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter;
 
-import java.nio.charset.StandardCharsets;
 
 /**
  * 认证服务安全配置，集中声明密码编码器、JWT 编码器以及认证接口的安全过滤链。
@@ -31,6 +27,7 @@ public class AuthSecurityConfig {
         "/api/auth/refresh",
         "/api/auth/logout",
         "/api/auth/impersonations/exchange",
+        "/api/auth/.well-known/jwks.json",
         "/actuator/health",
         "/v3/api-docs/**",
         "/swagger-ui/**",
@@ -40,13 +37,6 @@ public class AuthSecurityConfig {
     @Bean
     PasswordEncoder passwordEncoder() { return new BCryptPasswordEncoder(12); }
 
-    @Bean
-    JwtEncoder jwtEncoder(AuthSecurityProperties properties) {
-        byte[] secret = properties.jwtSecret().getBytes(StandardCharsets.UTF_8);
-        if (secret.length < 32) throw new IllegalStateException("JWT_SECRET 至少需要 32 字节");
-        return new NimbusJwtEncoder(new ImmutableSecret<>(secret));
-    }
-
     @Bean
     SecurityFilterChain authSecurityFilterChain(HttpSecurity http,
                                                 JwtAuthenticationFilter jwtFilter,

auth/src/main/java/com/baiyue/auth/config/DomesticJwtConfiguration.java

@@ -0,0 +1,22 @@
+package com.baiyue.auth.config;
+
+import com.nimbusds.jose.jwk.source.ImmutableSecret;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.context.annotation.Primary;
+import org.springframework.security.oauth2.jwt.JwtEncoder;
+import org.springframework.security.oauth2.jwt.NimbusJwtEncoder;
+
+import java.nio.charset.StandardCharsets;
+
+/** 国内现有 HS256 编码器，始终为认证服务主编码器。 */
+@Configuration(proxyBeanMethods = false)
+public class DomesticJwtConfiguration {
+    @Bean("jwtEncoder")
+    @Primary
+    JwtEncoder jwtEncoder(AuthSecurityProperties properties) {
+        byte[] secret = properties.jwtSecret().getBytes(StandardCharsets.UTF_8);
+        if (secret.length < 32) throw new IllegalStateException("JWT_SECRET 至少需要 32 字节");
+        return new NimbusJwtEncoder(new ImmutableSecret<>(secret));
+    }
+}

auth/src/main/java/com/baiyue/auth/config/OverseasJwtConfiguration.java

@@ -0,0 +1,37 @@
+package com.baiyue.auth.config;
+
+import com.nimbusds.jose.jwk.JWKSet;
+import com.nimbusds.jose.jwk.RSAKey;
+import com.nimbusds.jose.jwk.source.ImmutableJWKSet;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.boot.context.properties.EnableConfigurationProperties;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.security.oauth2.jwt.JwtEncoder;
+import org.springframework.security.oauth2.jwt.NimbusJwtEncoder;
+
+@Configuration(proxyBeanMethods = false)
+@EnableConfigurationProperties(OverseasJwtProperties.class)
+@ConditionalOnProperty(name = "baiyue.security.overseas-jwt.enabled", havingValue = "true")
+public class OverseasJwtConfiguration {
+    @Bean("overseasJwtEncoder")
+    JwtEncoder overseasJwtEncoder(OverseasJwtProperties properties) {
+        try {
+            JWKSet set = JWKSet.parse(properties.rsaJwkSet());
+            RSAKey current = set.getKeyByKeyId(properties.currentKid()) instanceof RSAKey rsa ? rsa : null;
+            if (current == null || !current.isPrivate()) {
+                throw new IllegalStateException("海外 current-kid 必须指向包含私钥的 RSA 密钥");
+            }
+            if (set.getKeys().stream().anyMatch(jwk -> !(jwk instanceof RSAKey))) {
+                throw new IllegalStateException("海外 JWK Set 只能包含 RSA 密钥");
+            }
+            if (set.getKeys().stream().anyMatch(jwk -> !properties.currentKid().equals(jwk.getKeyID())
+                    && jwk instanceof RSAKey rsa && rsa.isPrivate())) {
+                throw new IllegalStateException("海外非当前密钥只能配置公钥");
+            }
+            return new NimbusJwtEncoder(new ImmutableJWKSet<>(set));
+        } catch (java.text.ParseException exception) {
+            throw new IllegalStateException("海外 RSA JWK Set 配置无效", exception);
+        }
+    }
+}

auth/src/main/java/com/baiyue/auth/config/OverseasJwtProperties.java

@@ -0,0 +1,10 @@
+package com.baiyue.auth.config;
+
+import org.springframework.boot.context.properties.ConfigurationProperties;
+
+import java.time.Duration;
+
+/** 海外尾程 RS256 短时令牌配置，默认关闭。 */
+@ConfigurationProperties(prefix = "baiyue.security.overseas-jwt")
+public record OverseasJwtProperties(boolean enabled, String issuer, String audience,
+                                    String rsaJwkSet, String currentKid, Duration accessTokenTtl) { }

auth/src/main/java/com/baiyue/auth/controller/AuthController.java

@@ -23,6 +23,8 @@ import com.baiyue.auth.dto.AccountManagementDtos.ChangePasswordRequest;
 import com.baiyue.auth.dto.AccountManagementDtos.ForcedPasswordChangeRequest;
 import com.baiyue.auth.dto.AccountManagementDtos;
 import com.baiyue.auth.service.AccountManagementService;
+import com.baiyue.auth.service.OverseasTokenService;
+import org.springframework.beans.factory.ObjectProvider;
 import org.springframework.security.access.prepost.PreAuthorize;
 
 /**
@@ -38,6 +40,18 @@ public class AuthController {
     private MerchantRegistrationService registrationService;
     @Resource
     private AccountManagementService accountManagementService;
+    @Resource
+    private ObjectProvider<OverseasTokenService> overseasTokens;
+
+    @PostMapping("/overseas/token")
+    @PreAuthorize("isAuthenticated()")
+    @Operation(summary = "兑换海外尾程访问令牌", description = "使用已通过国内会话校验的身份兑换 15 分钟 RS256 海外令牌。")
+    public ApiResponse<OverseasTokenService.OverseasTokenResponse> exchangeOverseasToken(
+            @AuthenticationPrincipal AuthenticatedUser user) {
+        OverseasTokenService service = overseasTokens.getIfAvailable();
+        if (service == null) throw new BizException(ResultCode.SERVICE_UNAVAILABLE, "海外认证未启用");
+        return ApiResponse.success(service.exchange(user.userId()));
+    }
 
     @PutMapping("/password")
     @PreAuthorize("isAuthenticated()")

auth/src/main/java/com/baiyue/auth/controller/JwksController.java

@@ -0,0 +1,31 @@
+package com.baiyue.auth.controller;
+
+import com.baiyue.auth.config.OverseasJwtProperties;
+import com.nimbusds.jose.jwk.JWKSet;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.security.SecurityRequirements;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.http.CacheControl;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.util.Map;
+import java.util.concurrent.TimeUnit;
+
+/** 仅在海外 JWT 显式启用后发布 RSA 公钥。 */
+@RestController
+@ConditionalOnProperty(name = "baiyue.security.overseas-jwt.enabled", havingValue = "true")
+public class JwksController {
+    private final OverseasJwtProperties properties;
+
+    public JwksController(OverseasJwtProperties properties) { this.properties = properties; }
+
+    @GetMapping("/api/auth/.well-known/jwks.json")
+    @SecurityRequirements
+    @Operation(summary = "获取海外 JWT 公钥集", description = "仅发布当前和轮换期上一把 RSA 公钥，不包含私钥。")
+    public ResponseEntity<Map<String, Object>> jwks() throws Exception {
+        return ResponseEntity.ok().cacheControl(CacheControl.maxAge(5, TimeUnit.MINUTES).cachePublic())
+            .body(JWKSet.parse(properties.rsaJwkSet()).toPublicJWKSet().toJSONObject());
+    }
+}

auth/src/main/java/com/baiyue/auth/service/AuthService.java

@@ -30,7 +30,6 @@ import java.time.LocalDateTime;
 import java.util.Base64;
 import java.util.UUID;
 import java.time.Duration;
-import java.util.List;
 
 /**
  * 统一认证应用服务，编排密码校验、IAM 权限快照加载、小 JWT 签发、刷新令牌轮换与注销事务。
@@ -109,8 +108,7 @@ public class AuthService {
         String jwtId = UUID.randomUUID().toString();
         Instant expiresAt = issuedAt.plus(properties.accessTokenTtl());
         JwtClaimsSet claims = JwtClaimsSet.builder()
-            .issuer(properties.issuer()).audience(List.of(properties.audience()))
-            .id(jwtId).issuedAt(issuedAt).expiresAt(expiresAt)
+            .issuer(properties.issuer()).id(jwtId).issuedAt(issuedAt).expiresAt(expiresAt)
             .subject(account.getId().toString())
             .claim("user_id", account.getId())
             .claim("username", account.getUsername())
@@ -121,12 +119,6 @@ public class AuthService {
             .claim("client_type", authorization.getClientType())
             .claim("token_version", account.getTokenVersion())
             .claim("password_change_required", Boolean.TRUE.equals(account.getPasswordChangeRequired()))
-            .claim("userId", account.getId())
-            .claim("tenantId", account.getDefaultTenantId())
-            .claim("appCode", account.getDefaultAppCode())
-            .claim("roles", authorization.getRoles())
-            .claim("authorities", authorization.getPermissions())
-            .claim("permissionVersion", account.getTokenVersion())
             .build();
         String accessToken = jwtEncoder.encode(JwtEncoderParameters.from(
             signingHeader(), claims)).getTokenValue();
@@ -175,17 +167,12 @@ public class AuthService {
         Instant issuedAt = Instant.now();
         Instant expiresAt = issuedAt.plus(Duration.ofMinutes(15));
         String jwtId = UUID.randomUUID().toString();
-        JwtClaimsSet claims = JwtClaimsSet.builder().issuer(properties.issuer())
-                .audience(List.of(properties.audience())).id(jwtId)
+        JwtClaimsSet claims = JwtClaimsSet.builder().issuer(properties.issuer()).id(jwtId)
                 .issuedAt(issuedAt).expiresAt(expiresAt).subject(account.getId().toString())
                 .claim("user_id", account.getId()).claim("username", account.getUsername())
                 .claim("tenant_id", account.getDefaultTenantId()).claim("operator_tenant_id", account.getOperatorTenantId())
                 .claim("membership_id", account.getDefaultMembershipId()).claim("app_code", "MERCHANT")
                 .claim("client_type", authorization.getClientType()).claim("token_version", account.getTokenVersion())
-                .claim("userId", account.getId()).claim("tenantId", account.getDefaultTenantId())
-                .claim("appCode", "MERCHANT").claim("roles", authorization.getRoles())
-                .claim("authorities", authorization.getPermissions())
-                .claim("permissionVersion", account.getTokenVersion())
                 .claim("impersonated", true).claim("impersonation_id", ticket.ticketId())
                 .claim("actor_user_id", ticket.actorUserId()).claim("actor_membership_id", ticket.actorMembershipId())
                 .claim("password_change_required", Boolean.TRUE.equals(account.getPasswordChangeRequired())).build();

auth/src/main/java/com/baiyue/auth/service/OverseasTokenService.java

@@ -0,0 +1,56 @@
+package com.baiyue.auth.service;
+
+import com.baiyue.auth.client.AuthorizationLoader;
+import com.baiyue.auth.client.AuthorizationSnapshot;
+import com.baiyue.auth.config.OverseasJwtProperties;
+import com.baiyue.auth.entity.AuthAccount;
+import com.baiyue.auth.repository.AuthAccountRepository;
+import com.baiyue.common.core.api.ResultCode;
+import com.baiyue.common.core.exception.BizException;
+import jakarta.annotation.Resource;
+import org.springframework.beans.factory.annotation.Qualifier;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.security.oauth2.jose.jws.SignatureAlgorithm;
+import org.springframework.security.oauth2.jwt.JwtClaimsSet;
+import org.springframework.security.oauth2.jwt.JwtEncoder;
+import org.springframework.security.oauth2.jwt.JwtEncoderParameters;
+import org.springframework.security.oauth2.jwt.JwsHeader;
+import org.springframework.stereotype.Service;
+
+import java.time.Instant;
+import java.util.List;
+import java.util.UUID;
+
+/** 将已经通过国内 HMAC 与 Redis 校验的会话兑换为海外 RS256 短时令牌。 */
+@Service
+@ConditionalOnProperty(name = "baiyue.security.overseas-jwt.enabled", havingValue = "true")
+public class OverseasTokenService {
+    @Resource private AuthAccountRepository accounts;
+    @Resource private AuthorizationLoader authorizationLoader;
+    @Resource private OverseasJwtProperties properties;
+    @Resource @Qualifier("overseasJwtEncoder") private JwtEncoder encoder;
+
+    public OverseasTokenResponse exchange(long authenticatedUserId) {
+        AuthAccount account = accounts.findById(authenticatedUserId);
+        if (account == null || !"ACTIVE".equals(account.getAccountStatus())) {
+            throw new BizException(ResultCode.UNAUTHORIZED, "账号不可用");
+        }
+        AuthorizationSnapshot authorization = authorizationLoader.load(account);
+        Instant issuedAt = Instant.now();
+        Instant expiresAt = issuedAt.plus(properties.accessTokenTtl());
+        JwtClaimsSet claims = JwtClaimsSet.builder()
+            .issuer(properties.issuer()).audience(List.of(properties.audience()))
+            .subject(account.getId().toString()).id(UUID.randomUUID().toString())
+            .issuedAt(issuedAt).expiresAt(expiresAt)
+            .claim("userId", account.getId()).claim("tenantId", account.getDefaultTenantId())
+            .claim("appCode", account.getDefaultAppCode()).claim("roles", authorization.getRoles())
+            .claim("authorities", authorization.getPermissions())
+            .claim("permissionVersion", authorization.getPermissionVersion() == null ? 0L : authorization.getPermissionVersion())
+            .build();
+        String token = encoder.encode(JwtEncoderParameters.from(
+            JwsHeader.with(SignatureAlgorithm.RS256).keyId(properties.currentKid()).build(), claims)).getTokenValue();
+        return new OverseasTokenResponse("Bearer", token, properties.accessTokenTtl().toSeconds());
+    }
+
+    public record OverseasTokenResponse(String tokenType, String accessToken, long expiresIn) { }
+}

auth/src/main/resources/application.yml

@@ -39,6 +39,13 @@ baiyue.security:
   refresh-token-ttl: ${REFRESH_TOKEN_TTL:7d}
   max-login-failures: ${MAX_LOGIN_FAILURES:5}
   lock-duration: ${LOGIN_LOCK_DURATION:15m}
+  overseas-jwt:
+    enabled: ${OVERSEAS_JWT_ENABLED:false}
+    issuer: ${OVERSEAS_JWT_ISSUER:auth-service}
+    audience: ${OVERSEAS_JWT_AUDIENCE:lastleg-api}
+    rsa-jwk-set: ${OVERSEAS_JWT_RSA_JWK_SET:}
+    current-kid: ${OVERSEAS_JWT_CURRENT_KID:}
+    access-token-ttl: ${OVERSEAS_ACCESS_TOKEN_TTL:15m}
 
 baiyue.clients:
   iam:

auth/src/test/java/com/baiyue/auth/client/AuthorizationLoaderTest.java

@@ -72,6 +72,6 @@ class AuthorizationLoaderTest {
 
     private AuthorizationSnapshot snapshot(Long userId, Long tenantId, Long membershipId, String appCode) {
         return new AuthorizationSnapshot(userId, tenantId, membershipId, appCode, appCode,
-                Set.of("MERCHANT_ADMIN"), Set.of("merchant:profile:view"));
+                Set.of("MERCHANT_ADMIN"), Set.of("merchant:profile:view"), 1L);
     }
 }

auth/src/test/java/com/baiyue/auth/config/AuthTokenTtlConfigurationContractTest.java

@@ -15,8 +15,9 @@ class AuthTokenTtlConfigurationContractTest {
             Path.of("..", "config", "nacos", "cn", "auth-service.yml"), StandardCharsets.UTF_8);
 
         assertThat(configuration)
-            .contains("access-token-ttl: ${ACCESS_TOKEN_TTL:15m}")
+            .contains("access-token-ttl: ${ACCESS_TOKEN_TTL:24m}")
             .contains("refresh-token-ttl: ${REFRESH_TOKEN_TTL:7d}")
+            .contains("access-token-ttl: ${OVERSEAS_ACCESS_TOKEN_TTL:15m}")
             .doesNotContain("access-token-ttl: ${ACCESS_TOKEN_TTL:7d}");
     }
 }

auth/src/test/java/com/baiyue/auth/config/DualTrackJwtConfigurationTest.java

@@ -0,0 +1,29 @@
+package com.baiyue.auth.config;
+
+import org.junit.jupiter.api.Test;
+import org.springframework.boot.autoconfigure.AutoConfigurations;
+import org.springframework.boot.test.context.runner.ApplicationContextRunner;
+import org.springframework.security.oauth2.jwt.JwtEncoder;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class DualTrackJwtConfigurationTest {
+    private final ApplicationContextRunner runner = new ApplicationContextRunner()
+        .withConfiguration(AutoConfigurations.of(DomesticJwtConfiguration.class, OverseasJwtConfiguration.class))
+        .withBean(AuthSecurityProperties.class, () -> new AuthSecurityProperties(
+            "domestic-secret-at-least-32-bytes-long", "auth-service", "lastleg-api",
+            java.time.Duration.ofMinutes(24), java.time.Duration.ofDays(7), 5,
+            java.time.Duration.ofMinutes(15)))
+        .withPropertyValues(
+            "baiyue.security.overseas-jwt.enabled=false");
+
+    @Test
+    void startsDomesticEncoderWithoutRsaConfiguration() {
+        runner.run(context -> {
+            assertThat(context).hasNotFailed();
+            assertThat(context).hasBean("jwtEncoder");
+            assertThat(context).doesNotHaveBean("overseasJwtEncoder");
+            assertThat(context).hasSingleBean(JwtEncoder.class);
+        });
+    }
+}

auth/src/test/java/com/baiyue/auth/controller/JwksControllerTest.java

@@ -0,0 +1,40 @@
+package com.baiyue.auth.controller;
+
+import com.baiyue.auth.config.OverseasJwtProperties;
+import com.nimbusds.jose.JWSAlgorithm;
+import com.nimbusds.jose.jwk.JWKSet;
+import com.nimbusds.jose.jwk.KeyUse;
+import com.nimbusds.jose.jwk.RSAKey;
+import com.nimbusds.jose.util.Base64URL;
+import org.junit.jupiter.api.Test;
+
+import java.math.BigInteger;
+import java.time.Duration;
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class JwksControllerTest {
+    @Test
+    void publishesOnlyPublicKeyMaterialForCurrentAndPreviousKeys() throws Exception {
+        RSAKey current = key("current", true);
+        RSAKey previous = key("previous", false);
+        String json = new JWKSet(List.of(current, previous)).toString(false);
+        var properties = new OverseasJwtProperties(true, "auth-service", "lastleg-api", json,
+            "current", Duration.ofMinutes(15));
+
+        var body = new JwksController(properties).jwks().getBody();
+        String published = new com.fasterxml.jackson.databind.ObjectMapper().writeValueAsString(body);
+
+        assertThat(published).contains("current", "previous", "\"n\"", "\"e\"")
+            .doesNotContain("\"d\"", "\"p\"", "\"q\"", "\"dp\"", "\"dq\"", "\"qi\"");
+    }
+
+    private RSAKey key(String kid, boolean privatePart) {
+        RSAKey.Builder builder = new RSAKey.Builder(
+            Base64URL.encode(BigInteger.valueOf(3233)), Base64URL.encode(BigInteger.valueOf(17)))
+            .keyID(kid).keyUse(KeyUse.SIGNATURE).algorithm(JWSAlgorithm.RS256);
+        if (privatePart) builder.privateExponent(Base64URL.encode(BigInteger.valueOf(2753)));
+        return builder.build();
+    }
+}

auth/src/test/java/com/baiyue/auth/service/AuthServiceSmallJwtTest.java

@@ -47,7 +47,7 @@ class AuthServiceSmallJwtTest {
     }
 
     @Test
-    void signsCrossRegionClaimsAndStoresSession() {
+    void signsDomesticHmacClaimsAndStoresSession() {
         AuthAccount account = new AuthAccount();
         account.setId(42L);
         account.setUsername("operator");
@@ -59,7 +59,7 @@ class AuthServiceSmallJwtTest {
         account.setDefaultAppCode("PLATFORM");
         account.setTokenVersion(1);
         AuthorizationSnapshot snapshot = new AuthorizationSnapshot(42L, 0L, 84L, "PLATFORM",
-                "WEB", Set.of("PLATFORM_ADMIN"), Set.of("platform:order:list"));
+                "WEB", Set.of("PLATFORM_ADMIN"), Set.of("platform:order:list"), 7L);
         Jwt encoded = org.mockito.Mockito.mock(Jwt.class);
 
         when(repository.findByUsername("operator")).thenReturn(account);
@@ -74,15 +74,10 @@ class AuthServiceSmallJwtTest {
         verify(jwtEncoder).encode(jwt.capture());
         assertThat(jwt.getValue().getClaims().getClaims())
                 .containsEntry("user_id", 42L)
-                .containsEntry("userId", 42L)
-                .containsEntry("tenantId", 0L)
-                .containsEntry("appCode", "PLATFORM")
-                .containsEntry("roles", Set.of("PLATFORM_ADMIN"))
-                .containsEntry("authorities", Set.of("platform:order:list"))
-                .containsEntry("permissionVersion", 1)
                 .containsEntry("membership_id", 84L)
-                .doesNotContainKeys("permissions", "scope");
-        assertThat(jwt.getValue().getClaims().getAudience()).containsExactly("lastleg-api");
+                .doesNotContainKeys("userId", "tenantId", "appCode", "roles", "authorities",
+                    "permissionVersion", "permissions", "scope");
+        assertThat(jwt.getValue().getClaims().getAudience()).isNull();
         assertThat(jwt.getValue().getJwsHeader().getAlgorithm()).isEqualTo(MacAlgorithm.HS256);
         assertThat(jwt.getValue().getJwsHeader().getKeyId()).isNull();
         verify(tokenSessionStore).store(any(), org.mockito.ArgumentMatchers.eq(42L),

auth/src/test/java/com/baiyue/auth/service/OverseasTokenServiceTest.java

@@ -0,0 +1,74 @@
+package com.baiyue.auth.service;
+
+import com.baiyue.auth.client.AuthorizationLoader;
+import com.baiyue.auth.client.AuthorizationSnapshot;
+import com.baiyue.auth.config.OverseasJwtProperties;
+import com.baiyue.auth.entity.AuthAccount;
+import com.baiyue.auth.repository.AuthAccountRepository;
+import jakarta.annotation.Resource;
+import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
+import org.springframework.boot.test.mock.mockito.MockBean;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.security.oauth2.jose.jws.SignatureAlgorithm;
+import org.springframework.security.oauth2.jwt.Jwt;
+import org.springframework.security.oauth2.jwt.JwtEncoder;
+import org.springframework.security.oauth2.jwt.JwtEncoderParameters;
+import org.springframework.test.context.junit.jupiter.SpringJUnitConfig;
+import org.springframework.test.context.TestPropertySource;
+
+import java.time.Duration;
+import java.util.Set;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+@SpringJUnitConfig(classes = {OverseasTokenService.class, OverseasTokenServiceTest.Config.class})
+@TestPropertySource(properties = "baiyue.security.overseas-jwt.enabled=true")
+class OverseasTokenServiceTest {
+    @MockBean private AuthAccountRepository accounts;
+    @MockBean private AuthorizationLoader authorizationLoader;
+    @MockBean(name = "overseasJwtEncoder") private JwtEncoder encoder;
+    @Resource private OverseasTokenService service;
+
+    @Configuration(proxyBeanMethods = false)
+    static class Config {
+        @Bean OverseasJwtProperties properties() {
+            return new OverseasJwtProperties(true, "auth-service", "lastleg-api", "{}", "current-kid",
+                Duration.ofMinutes(15));
+        }
+    }
+
+    @Test
+    void signsShortRs256TokenWithCrossRegionClaims() {
+        AuthAccount account = new AuthAccount();
+        account.setId(42L); account.setAccountStatus("ACTIVE"); account.setDefaultTenantId(100L);
+        account.setDefaultMembershipId(84L); account.setDefaultAppCode("MERCHANT");
+        AuthorizationSnapshot snapshot = new AuthorizationSnapshot(42L, 100L, 84L, "MERCHANT", "WEB",
+            Set.of("MERCHANT_ADMIN"), Set.of("merchant:order:list"), 7L);
+        Jwt encoded = org.mockito.Mockito.mock(Jwt.class);
+        when(accounts.findById(42L)).thenReturn(account);
+        when(authorizationLoader.load(account)).thenReturn(snapshot);
+        when(encoder.encode(any())).thenReturn(encoded);
+        when(encoded.getTokenValue()).thenReturn("overseas-token");
+
+        var response = service.exchange(42L);
+
+        ArgumentCaptor<JwtEncoderParameters> captor = ArgumentCaptor.forClass(JwtEncoderParameters.class);
+        verify(encoder).encode(captor.capture());
+        var parameters = captor.getValue();
+        assertThat(parameters.getJwsHeader().getAlgorithm()).isEqualTo(SignatureAlgorithm.RS256);
+        assertThat(parameters.getJwsHeader().getKeyId()).isEqualTo("current-kid");
+        assertThat(parameters.getClaims().getAudience()).containsExactly("lastleg-api");
+        assertThat(parameters.getClaims().getClaims())
+            .containsEntry("userId", 42L).containsEntry("tenantId", 100L)
+            .containsEntry("appCode", "MERCHANT").containsEntry("permissionVersion", 7L)
+            .containsEntry("roles", Set.of("MERCHANT_ADMIN"))
+            .containsEntry("authorities", Set.of("merchant:order:list"))
+            .doesNotContainKeys("user_id", "tenant_id", "app_code");
+        assertThat(response.expiresIn()).isEqualTo(900);
+    }
+}