birc-generator 0.9.0 → 1.0.0

package/project-docs/PROJECT.md.hbs

@@ -58,16 +58,29 @@ DB → Entity → Mapper → XxxResponse → Result<T>
 ## 統一規範
 
 - 例外丟 `ProjectException` 子類（例如 `NotFoundException`），由 `ExceptionHandleController` 轉成回應。Controller 不手動 try-catch 包錯誤訊息。
-- 整組骨架用 `birc make`；單層用 `birc make:entity` / `make:model` / `make:mapper` / `make:service` / `make:controller` / `make:exception`。`make:entity` 只生 Entity 與 DAO；`--migration` / `--seed` 同 `make:model`（已有 Entity 就跳過，只補 SQL / Seeder）。`--dto` 與 `--mapper` 一併生 Mapper 與 DTO。`make:model` 可加 `--migration` / `--seed` / `--controller`。`make` 也可加 `--migration` / `--seed`。`make:seeder BookSeeder` 生 Java Seeder。`--soft-delete` 用 Hibernate `@SoftDelete` 的 `deleted_at`，查詢自動排除已刪；不要自寫 `@SQLDelete`。預設是初稿，完整範例加 `--example` 或 `--fields`。`make:migration create_{table}_table` 讀對應 Entity 欄位寫進 SQL。`--seed` 生 Java Seeder，用 DAO 塞資料；`birc seed` 才執行。清空資料庫用 `birc db:wipe`。不要複製其他 Entity 的程式碼來改名。
+- 整組骨架用 `birc make`；單層用 `birc make:entity` / `make:model` / `make:mapper` / `make:service` / `make:controller` / `make:exception`。`make:entity` 只生 Entity 與 DAO；`--migration` / `--seed` 同 `make:model`（已有 Entity 就跳過，只補 SQL / Seeder）。`--dto` 與 `--mapper` 一併生 Mapper 與 DTO。`make:model` 可加 `--migration` / `--seed` / `--controller`。`make` 也可加 `--migration` / `--seed`（已有 Java 就跳過，只補缺的檔與 SQL / Seeder）。`make:seeder BookSeeder` 生 Java Seeder。`--soft-delete` 用 Hibernate `@SoftDelete` 的 `deleted_at`，查詢自動排除已刪；不要自寫 `@SQLDelete`。預設是初稿，完整範例加 `--example` 或 `--fields`。`make:migration create_{table}_table` 讀對應 Entity 欄位寫進 SQL。`--seed` 生 Java Seeder，用 DAO 塞資料；`birc seed` 才執行。清空資料庫用 `birc db:wipe`。不要複製其他 Entity 的程式碼來改名。
 - 欄位驗證用專案內 `validation/ValidGroup`。CRUD 用 `Create` / `Update`。`Delete` 給「刪除還要帶原因、確認碼、樂觀鎖 version」的 body。`Submit` 給草稿可少填、送審要全填（活動送審就是這組）。Controller 的 `@Validated` 與欄位 `groups` 對同一組。
 - email / sso / oauth / validGroup 用 `birc add`，不要從別的專案抄設定。
 - 格式化走 Spotless（`./gradlew spotlessApply`），不要另裝 Checkstyle。
 - CORS 只改 `CORS_ALLOWED_ORIGIN_PATTERNS`（逗號分隔 Origin，不要尾斜線、不要 `*`）。`SecurityConfig` 已經用 `http.cors()` 接 `CorsConfigurationSource`。不要在 `WebMvcConfigurer` 加 `addCorsMappings`，Spring Security 會擋 preflight。空白 = 不開放跨來源。
+- API 文件用 `API_DOCS_ENABLED` 一個開關控制，`SecurityConfig` 的 `API_DOCS_PATHS` 與 springdoc 的 `enabled` 都讀它。正式環境設 `false`。不要把 swagger 路徑手動塞回 `PUBLIC_PATHS`。
+- 要改 `SecurityFilterChain`（放行路徑、加 filter）就寫一個實作 `SecurityCustomizer` 的 `@Component`，不要改 `SecurityConfig` 本體。放行路徑一定要走 `publicPaths()`：Spring Security 不允許在 `anyRequest()` 之後再加 matcher。
 
 ## 已啟用的功能模組
 
 見 `.bircrc.json` 的 `features` 欄位。要加新的模組用 `birc add`。
 
+## 登入（有裝 auth 才有）
+
+`POST /api/auth/login` 收 `{"account":..,"password":..}`，成功時 JWT 在 **`X-Auth-Token` 回應標頭**，
+不在 body。之後的請求用 `Authorization: Bearer <token>` 帶。`GET /api/auth/me` 回目前使用者與權限代碼。
+
+- 帳號在 `auth_users` 表，`authorities` 是逗號分隔的權限代碼，跟 `@RequirePermission` 比對的是同一組字串，不加 `ROLE_` 前綴。
+- 密碼存 `PasswordEncoder` 編碼後的字串（預設 bcrypt，前綴 `{bcrypt}`），不要放明碼。
+- `JWT_SECRET` 放 `.env`，不要寫進 yml。沒設時啟動會看 `.env`，還是空的就產生一把寫進去；已有值不改。
+- 沒有 refresh token，過期就重新登入。要加請自己做，不要改 `JwtService` 的驗章邏輯來延長。
+- 未登入回 401、權限不足回 403。不要把兩者合併成同一種回應。
+
 ## SSO / Sentry
 
 在 `application.yml` 設定：

package/templates/aop/OperationLogAspect.hbs

@@ -24,6 +24,11 @@ public class OperationLogAspect {
     @Value("${operation-log.trust-forwarded-user:false}")
     private boolean trustForwardedUser;
 
+    // X-Forwarded-For 同樣可偽造。採信它等於讓呼叫端自己決定稽核日誌上的 IP，
+    // 事後要靠 log 追人就追錯對象。只有反向代理會覆寫此標頭時才打開。
+    @Value("${operation-log.trust-forwarded-for:false}")
+    private boolean trustForwardedFor;
+
     @Pointcut("@annotation({{basePackage}}.annotation.OperationLog)")
     public void operationLogPointcut() {
     }
@@ -86,9 +91,11 @@ public class OperationLogAspect {
         if (attributes == null) {
             return "unknown";
         }
-        String forwarded = attributes.getRequest().getHeader("X-Forwarded-For");
-        if (forwarded != null && !forwarded.isBlank() && !"unknown".equalsIgnoreCase(forwarded)) {
-            return forwarded.split(",")[0].trim();
+        if (trustForwardedFor) {
+            String forwarded = attributes.getRequest().getHeader("X-Forwarded-For");
+            if (forwarded != null && !forwarded.isBlank() && !"unknown".equalsIgnoreCase(forwarded)) {
+                return forwarded.split(",")[0].trim();
+            }
         }
         return attributes.getRequest().getRemoteAddr();
     }

package/templates/auth/AuthController.hbs

@@ -0,0 +1,73 @@
+package {{basePackage}}.controller;
+
+import jakarta.validation.Valid;
+import java.util.List;
+import lombok.RequiredArgsConstructor;
+import org.springframework.http.ResponseEntity;
+import org.springframework.security.authentication.AuthenticationManager;
+import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
+import org.springframework.security.core.Authentication;
+import org.springframework.security.core.GrantedAuthority;
+import org.springframework.security.core.AuthenticationException;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+import {{basePackage}}.dto.LoginRequest;
+import {{basePackage}}.exception.LoginFailedException;
+import {{basePackage}}.security.JwtService;
+import {{basePackage}}.web.Result;
+
+/**
+ * 登入。成功時 JWT 放在 X-Auth-Token 回應標頭，之後請求用 {@code Authorization: Bearer <token>}
+ * 帶回來。
+ *
+ * <p>
+ * body 只回帳號與權限代碼，不回 token——標頭與 body 各放一份會讓前端不知道 該信哪個，也容易被順手記進 log。
+ */
+@RestController
+@RequestMapping("/api/auth")
+@RequiredArgsConstructor
+public class AuthController {
+
+    public static final String TOKEN_HEADER = "X-Auth-Token";
+
+    private final AuthenticationManager authenticationManager;
+    private final JwtService jwtService;
+
+    @PostMapping("/login")
+    public ResponseEntity<Result<LoginResponse>> login(@Valid @RequestBody LoginRequest request) {
+        Authentication authentication;
+        try {
+            authentication = authenticationManager.authenticate(
+                    new UsernamePasswordAuthenticationToken(request.getAccount(), request.getPassword()));
+        } catch (AuthenticationException e) {
+            // 不要區分「帳號不存在」與「密碼錯誤」，那等於提供帳號列舉的管道。
+            throw new LoginFailedException();
+        }
+
+        List<String> authorities = authentication.getAuthorities().stream()
+                .map(GrantedAuthority::getAuthority)
+                .toList();
+        String token = jwtService.issue(authentication.getName(), authorities);
+
+        return ResponseEntity.ok()
+                .header(TOKEN_HEADER, token)
+                .body(Result.success(new LoginResponse(authentication.getName(), authorities)));
+    }
+
+    /**
+     * 目前登入者是誰、有哪些權限。前端拿它決定要不要顯示某個功能， 不要先打功能端點再等 403。
+     */
+    @GetMapping("/me")
+    public Result<LoginResponse> me(Authentication authentication) {
+        List<String> authorities = authentication.getAuthorities().stream()
+                .map(GrantedAuthority::getAuthority)
+                .toList();
+        return Result.success(new LoginResponse(authentication.getName(), authorities));
+    }
+
+    public record LoginResponse(String account, List<String> authorities) {
+    }
+}

package/templates/auth/AuthFlowTest.hbs

@@ -0,0 +1,112 @@
+package {{basePackage}};
+
+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 java.net.URI;
+import java.net.http.HttpClient;
+import java.net.http.HttpRequest;
+import java.net.http.HttpResponse;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.boot.test.web.server.LocalServerPort;
+import org.springframework.security.crypto.password.PasswordEncoder;
+import {{daoPackage}}.AuthUserDAO;
+import {{entityPackage}}.AuthUser;
+
+/**
+ * 登入流程只有整條走完才有意義：發得出 token、帶著它能過、沒帶會被擋。
+ * 任何一段斷掉，其它兩段各自「看起來正常」也沒有用。
+ */
+@SpringBootTest(
+        webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT,
+        // 測試 profile 沒有跑 Flyway（那些 SQL 是 MySQL 方言），改讓 Hibernate 依 Entity 建表。
+        properties = "spring.jpa.hibernate.ddl-auto=create-drop")
+class AuthFlowTest {
+
+    @LocalServerPort
+    private int port;
+
+    @Autowired
+    private AuthUserDAO authUserDAO;
+
+    @Autowired
+    private PasswordEncoder passwordEncoder;
+
+    @BeforeEach
+    void createUser() {
+        authUserDAO.findByAccount("tester").orElseGet(() -> {
+            AuthUser user = new AuthUser();
+            user.setAccount("tester");
+            user.setPassword(passwordEncoder.encode("secret"));
+            user.setAuthorities("user:read");
+            return authUserDAO.save(user);
+        });
+    }
+
+    private HttpResponse<String> login(String account, String password) throws Exception {
+        HttpRequest request = HttpRequest.newBuilder()
+                .uri(URI.create("http://localhost:" + port + "/api/auth/login"))
+                .header("Content-Type", "application/json")
+                .POST(HttpRequest.BodyPublishers.ofString(
+                        "{\"account\":\"" + account + "\",\"password\":\"" + password + "\"}"))
+                .build();
+        return HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
+    }
+
+    private HttpResponse<String> callMe(String token) throws Exception {
+        HttpRequest.Builder builder = HttpRequest.newBuilder()
+                .uri(URI.create("http://localhost:" + port + "/api/auth/me"))
+                .GET();
+        if (token != null) {
+            builder.header("Authorization", "Bearer " + token);
+        }
+        return HttpClient.newHttpClient().send(builder.build(), HttpResponse.BodyHandlers.ofString());
+    }
+
+    @Test
+    void loginReturnsTokenInHeader() throws Exception {
+        HttpResponse<String> response = login("tester", "secret");
+
+        assertEquals(200, response.statusCode());
+        String token = response.headers().firstValue("X-Auth-Token").orElse(null);
+        assertNotNull(token, "登入成功要在 X-Auth-Token 標頭帶 JWT");
+        assertTrue(token.split("\\.").length == 3, "X-Auth-Token 要是 JWT");
+    }
+
+    @Test
+    void tokenFromLoginPassesAuthenticationAndCarriesAuthorities() throws Exception {
+        // 防住：發得出 token 但 filter 沒掛進 chain，帶著它一樣進不來。
+        String token = login("tester", "secret").headers().firstValue("X-Auth-Token").orElseThrow();
+
+        HttpResponse<String> response = callMe(token);
+
+        assertEquals(200, response.statusCode());
+        assertTrue(response.body().contains("tester"));
+        // 權限代碼要原樣傳到 SecurityContext，@RequirePermission 比對的就是這組字串。
+        assertTrue(response.body().contains("user:read"));
+    }
+
+    @Test
+    void requestWithoutTokenIsRejected() throws Exception {
+        // 401 而不是 403：客戶端要能分出「請先登入」與「你沒這個權限」。
+        assertEquals(401, callMe(null).statusCode());
+    }
+
+    @Test
+    void forgedTokenIsRejected() throws Exception {
+        // 防住：簽章沒驗，任何人自己拼一段 JWT 就能當管理員。
+        String forged = "eyJhbGciOiJIUzI1NiJ9"
+                + ".eyJzdWIiOiJhZG1pbiIsImF1dGhvcml0aWVzIjpbImFkbWluIl19.not-a-real-signature";
+
+        assertEquals(401, callMe(forged).statusCode());
+    }
+
+    @Test
+    void wrongPasswordIsRejected() throws Exception {
+        assertEquals(401, login("tester", "wrong").statusCode());
+    }
+}

package/templates/auth/AuthSecurityCustomizer.hbs

@@ -0,0 +1,38 @@
+package {{basePackage}}.config;
+
+import java.util.List;
+import lombok.RequiredArgsConstructor;
+import org.springframework.http.HttpStatus;
+import org.springframework.security.config.annotation.web.builders.HttpSecurity;
+import org.springframework.security.web.authentication.HttpStatusEntryPoint;
+import org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter;
+import org.springframework.stereotype.Component;
+import {{basePackage}}.security.JwtAuthenticationFilter;
+
+/**
+ * 把 JWT filter 掛進 SecurityFilterChain，並放行登入端點。
+ *
+ * <p>這是 birc-generator 唯一會碰 SecurityFilterChain 的地方，而且是透過
+ * {@link SecurityCustomizer} 這個縫，沒有改寫 SecurityConfig。要再加別的
+ * 放行路徑或 filter，照這個檔案再寫一個 Component 就好。
+ */
+@Component
+@RequiredArgsConstructor
+public class AuthSecurityCustomizer implements SecurityCustomizer {
+
+    private final JwtAuthenticationFilter jwtAuthenticationFilter;
+
+    @Override
+    public List<String> publicPaths() {
+        return List.of("/api/auth/login");
+    }
+
+    @Override
+    public void customize(HttpSecurity http) throws Exception {
+        http.addFilterBefore(jwtAuthenticationFilter, UsernamePasswordAuthenticationFilter.class)
+                // 沒配 entry point 時 Spring Security 對未登入回 403，客戶端會分不出
+                // 「請先登入」與「你沒這個權限」。有了登入端點就該回 401。
+                .exceptionHandling(handling ->
+                        handling.authenticationEntryPoint(new HttpStatusEntryPoint(HttpStatus.UNAUTHORIZED)));
+    }
+}

package/templates/auth/AuthUser.hbs

@@ -0,0 +1,54 @@
+package {{entityPackage}};
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.GeneratedValue;
+import jakarta.persistence.GenerationType;
+import jakarta.persistence.Id;
+import jakarta.persistence.Table;
+import java.time.LocalDateTime;
+import lombok.Getter;
+import lombok.Setter;
+
+/**
+ * 登入用的使用者。
+ *
+ * <p>
+ * authorities 是逗號分隔的權限代碼（例如 {@code user:read,user:write}），跟
+ * {@code @RequirePermission} 比對的是同一組字串。一開始用一個欄位就夠；之後要做 角色與權限的多對多，再開新表、把這個欄位換掉。
+ *
+ * <p>
+ * password 存的是 {@code PasswordEncoder} 編碼後的字串（預設 bcrypt，前綴
+ * {@code {bcrypt}}），不要放明碼。
+ */
+@Entity
+@Getter
+@Setter
+@Table(name = "auth_users")
+public class AuthUser {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+
+    @Column(name = "account", nullable = false, unique = true, length = 50)
+    private String account;
+
+    @Column(name = "password", nullable = false, length = 100)
+    private String password;
+
+    @Column(name = "display_name", length = 50)
+    private String displayName;
+
+    @Column(name = "authorities", length = 500)
+    private String authorities;
+
+    @Column(name = "enabled", nullable = false)
+    private boolean enabled = true;
+
+    @Column(name = "created_at", insertable = false, updatable = false)
+    private LocalDateTime createdAt;
+
+    @Column(name = "updated_at", insertable = false, updatable = false)
+    private LocalDateTime updatedAt;
+}

package/templates/auth/AuthUserDAO.hbs

@@ -0,0 +1,9 @@
+package {{daoPackage}};
+
+import java.util.Optional;
+import {{entityPackage}}.AuthUser;
+
+public interface AuthUserDAO extends BaseDAO<AuthUser, Long> {
+
+    Optional<AuthUser> findByAccount(String account);
+}

package/templates/auth/JpaUserDetailsService.hbs

@@ -0,0 +1,47 @@
+package {{basePackage}}.security;
+
+import java.util.Arrays;
+import java.util.List;
+import lombok.RequiredArgsConstructor;
+import org.springframework.context.annotation.Primary;
+import org.springframework.security.core.authority.SimpleGrantedAuthority;
+import org.springframework.security.core.userdetails.UserDetails;
+import org.springframework.security.core.userdetails.UserDetailsService;
+import org.springframework.security.core.userdetails.UsernameNotFoundException;
+import org.springframework.stereotype.Service;
+import {{daoPackage}}.AuthUserDAO;
+
+/**
+ * 用 users 表取代 ApplicationConfig 裡那個空的 InMemoryUserDetailsManager。
+ * 標 {@code @Primary} 讓它蓋過骨架的預設，不用去改 ApplicationConfig。
+ */
+@Primary
+@Service
+@RequiredArgsConstructor
+public class JpaUserDetailsService implements UserDetailsService {
+
+    private final AuthUserDAO authUserDAO;
+
+    @Override
+    public UserDetails loadUserByUsername(String account) {
+        return authUserDAO.findByAccount(account)
+                .map(user -> org.springframework.security.core.userdetails.User.withUsername(user.getAccount())
+                        .password(user.getPassword())
+                        .authorities(toAuthorities(user.getAuthorities()))
+                        .disabled(!user.isEnabled())
+                        .build())
+                // 帳號不存在與密碼錯誤都要回同一種錯誤，否則等於提供帳號列舉的管道。
+                .orElseThrow(() -> new UsernameNotFoundException("帳號或密碼錯誤"));
+    }
+
+    private List<SimpleGrantedAuthority> toAuthorities(String raw) {
+        if (raw == null || raw.isBlank()) {
+            return List.of();
+        }
+        return Arrays.stream(raw.split(","))
+                .map(String::trim)
+                .filter(code -> !code.isEmpty())
+                .map(SimpleGrantedAuthority::new)
+                .toList();
+    }
+}

package/templates/auth/JwtAuthenticationFilter.hbs

@@ -0,0 +1,50 @@
+package {{basePackage}}.security;
+
+import jakarta.servlet.FilterChain;
+import jakarta.servlet.ServletException;
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.servlet.http.HttpServletResponse;
+import java.io.IOException;
+import lombok.RequiredArgsConstructor;
+import org.springframework.http.HttpHeaders;
+import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
+import org.springframework.security.core.authority.SimpleGrantedAuthority;
+import org.springframework.security.core.context.SecurityContextHolder;
+import org.springframework.security.web.authentication.WebAuthenticationDetailsSource;
+import org.springframework.stereotype.Component;
+import org.springframework.web.filter.OncePerRequestFilter;
+
+/**
+ * 從 Authorization: Bearer 取出 JWT，驗過就把 Authentication 放進 SecurityContext。
+ *
+ * <p>驗不過不丟例外也不回 401，只是不設 Authentication，讓後面的授權規則決定——
+ * 公開路徑仍然要能在帶著爛 token 的情況下正常回應。
+ */
+@Component
+@RequiredArgsConstructor
+public class JwtAuthenticationFilter extends OncePerRequestFilter {
+
+    private static final String BEARER_PREFIX = "Bearer ";
+
+    private final JwtService jwtService;
+
+    @Override
+    protected void doFilterInternal(
+            HttpServletRequest request, HttpServletResponse response, FilterChain filterChain)
+            throws ServletException, IOException {
+        String header = request.getHeader(HttpHeaders.AUTHORIZATION);
+        if (header != null && header.startsWith(BEARER_PREFIX)
+                && SecurityContextHolder.getContext().getAuthentication() == null) {
+            JwtService.AuthenticatedUser user = jwtService.parse(header.substring(BEARER_PREFIX.length()));
+            if (user != null) {
+                UsernamePasswordAuthenticationToken authentication = new UsernamePasswordAuthenticationToken(
+                        user.account(),
+                        null,
+                        user.authorities().stream().map(SimpleGrantedAuthority::new).toList());
+                authentication.setDetails(new WebAuthenticationDetailsSource().buildDetails(request));
+                SecurityContextHolder.getContext().setAuthentication(authentication);
+            }
+        }
+        filterChain.doFilter(request, response);
+    }
+}

package/templates/auth/JwtProperties.hbs

@@ -0,0 +1,35 @@
+package {{basePackage}}.config;
+
+import jakarta.validation.constraints.Min;
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.Size;
+import lombok.Getter;
+import lombok.Setter;
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.stereotype.Component;
+import org.springframework.validation.annotation.Validated;
+
+/**
+ * JWT 設定，對應 application.yml 的 birc.auth.*。
+ *
+ * <p>secret 從 JWT_SECRET 來。沒設時啟動會看專案根的 .env，還是空的就產生一把寫進去。
+ * 不要把值寫死在 yml：那會進 git，任何人都能自己簽管理員 token。HS256 要求金鑰
+ * 至少 256 bit，所以這裡擋 32 個字元以下。
+ */
+@Getter
+@Setter
+@Validated
+@Component
+@ConfigurationProperties(prefix = "birc.auth")
+public class JwtProperties {
+
+    @NotBlank
+    @Size(min = 32, message = "JWT_SECRET 至少要 32 個字元（HS256 需要 256 bit 金鑰）")
+    private String secret;
+
+    /**
+     * Token 有效秒數，預設 8 小時。這個骨架沒有 refresh token，過期就重新登入。
+     */
+    @Min(60)
+    private long expirationSeconds = 28800;
+}

package/templates/auth/JwtSecretEnvTest.hbs

@@ -0,0 +1,68 @@
+package {{basePackage}};
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.nio.file.Files;
+import java.nio.file.Path;
+import org.junit.jupiter.api.Test;
+import org.springframework.boot.SpringApplication;
+import org.springframework.core.env.StandardEnvironment;
+import {{basePackage}}.config.JwtSecretEnvironmentPostProcessor;
+
+/**
+ * 啟動時補 JWT_SECRET 只有「空的才寫、有了就不換」兩件事。換鑰匙等於所有已發出的 token 作廢。
+ */
+class JwtSecretEnvTest {
+
+    @Test
+    void writesSecretWhenDotEnvIsEmpty() throws Exception {
+        Path dir = Files.createTempDirectory("jwt-secret");
+        Path env = dir.resolve(".env");
+        Files.writeString(env, "JWT_SECRET=\n");
+        String previous = System.setProperty("user.dir", dir.toString());
+        try {
+            StandardEnvironment environment = new StandardEnvironment();
+            new JwtSecretEnvironmentPostProcessor().postProcessEnvironment(environment, new SpringApplication());
+
+            String secret = environment.getProperty("birc.auth.secret");
+            assertTrue(secret != null && secret.length() >= 32);
+            assertEquals(secret, readSecret(env));
+        } finally {
+            restoreUserDir(previous);
+        }
+    }
+
+    @Test
+    void keepsExistingSecret() throws Exception {
+        Path dir = Files.createTempDirectory("jwt-keep");
+        Path env = dir.resolve(".env");
+        String existing = "keep-this-secret-value-32chars-min";
+        Files.writeString(env, "JWT_SECRET=" + existing + "\n");
+        String previous = System.setProperty("user.dir", dir.toString());
+        try {
+            StandardEnvironment environment = new StandardEnvironment();
+            new JwtSecretEnvironmentPostProcessor().postProcessEnvironment(environment, new SpringApplication());
+
+            assertEquals(existing, environment.getProperty("birc.auth.secret"));
+            assertEquals(existing, readSecret(env));
+        } finally {
+            restoreUserDir(previous);
+        }
+    }
+
+    private static String readSecret(Path env) throws Exception {
+        String text = Files.readString(env);
+        int start = text.indexOf("JWT_SECRET=") + "JWT_SECRET=".length();
+        int end = text.indexOf('\n', start);
+        return (end < 0 ? text.substring(start) : text.substring(start, end)).trim();
+    }
+
+    private static void restoreUserDir(String previous) {
+        if (previous == null) {
+            System.clearProperty("user.dir");
+        } else {
+            System.setProperty("user.dir", previous);
+        }
+    }
+}

package/templates/auth/JwtSecretEnvironmentPostProcessor.hbs

@@ -0,0 +1,102 @@
+package {{basePackage}}.config;
+
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.security.SecureRandom;
+import java.util.Base64;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+import org.springframework.boot.EnvironmentPostProcessor;
+import org.springframework.boot.SpringApplication;
+import org.springframework.core.env.ConfigurableEnvironment;
+import org.springframework.core.env.MapPropertySource;
+
+/**
+ * 啟動時若 JWT_SECRET 還沒進 Environment，先看專案根的 .env；還是空的就產生一把寫進去。
+ * 已有值不改，否則重啟後舊 token 全部驗不過。
+ *
+ * <p>.env 本身不進 git。不要把產生出來的值抄進 application.yml。
+ */
+public class JwtSecretEnvironmentPostProcessor implements EnvironmentPostProcessor {
+
+    static final String PROPERTY_SOURCE = "bircJwtSecret";
+    private static final String ENV_KEY = "JWT_SECRET";
+    private static final String YML_KEY = "birc.auth.secret";
+    private static final int MIN_LENGTH = 32;
+    private static final Pattern LINE = Pattern.compile("^JWT_SECRET=(.*)$", Pattern.MULTILINE);
+
+    @Override
+    public void postProcessEnvironment(ConfigurableEnvironment environment, SpringApplication application) {
+        String existing = firstUsable(environment.getProperty(YML_KEY), environment.getProperty(ENV_KEY));
+        if (existing != null) {
+            return;
+        }
+
+        Path envFile = Path.of(System.getProperty("user.dir", "."), ".env");
+        String fromFile = readSecret(envFile);
+        String secret = firstUsable(fromFile);
+        if (secret == null) {
+            secret = generate();
+            try {
+                writeSecret(envFile, secret);
+            } catch (IOException ignored) {
+                // 這次啟動仍用剛產生的值；檔寫不進去下次會再產生。
+            }
+        }
+
+        Map<String, Object> values = new HashMap<>();
+        values.put(ENV_KEY, secret);
+        values.put(YML_KEY, secret);
+        environment.getPropertySources().addFirst(new MapPropertySource(PROPERTY_SOURCE, values));
+    }
+
+    private static String firstUsable(String... values) {
+        for (String value : values) {
+            if (value != null && value.trim().length() >= MIN_LENGTH) {
+                return value.trim();
+            }
+        }
+        return null;
+    }
+
+    private static String readSecret(Path envFile) {
+        if (!Files.isRegularFile(envFile)) {
+            return null;
+        }
+        try {
+            Matcher match = LINE.matcher(Files.readString(envFile, StandardCharsets.UTF_8));
+            return match.find() ? match.group(1).trim() : null;
+        } catch (IOException e) {
+            return null;
+        }
+    }
+
+    private static void writeSecret(Path envFile, String secret) throws IOException {
+        if (!Files.isRegularFile(envFile)) {
+            Files.writeString(envFile, ENV_KEY + "=" + secret + "\n", StandardCharsets.UTF_8);
+            return;
+        }
+        String text = Files.readString(envFile, StandardCharsets.UTF_8);
+        Matcher match = LINE.matcher(text);
+        String next;
+        if (!match.find()) {
+            String suffix = text.endsWith("\n") ? "" : "\n";
+            next = text + suffix + ENV_KEY + "=" + secret + "\n";
+        } else if (match.group(1).trim().isEmpty()) {
+            next = LINE.matcher(text).replaceFirst(ENV_KEY + "=" + Matcher.quoteReplacement(secret));
+        } else {
+            return;
+        }
+        Files.writeString(envFile, next, StandardCharsets.UTF_8);
+    }
+
+    private static String generate() {
+        byte[] bytes = new byte[48];
+        new SecureRandom().nextBytes(bytes);
+        return Base64.getEncoder().encodeToString(bytes);
+    }
+}