@dsalazardev/ai-hub-cli 0.0.0-stage → 0.1.0

package/skills/shared/spring-boot/SKILL.md

@@ -0,0 +1,350 @@
+---
+name: spring-boot
+description: "Use when building, reviewing, testing, securing or configuring a Spring Boot 4 / Framework 7 backend — controllers, services, Spring Data JPA, application.yml, SecurityFilterChain, slice tests. NOT plain modern-Java language work like records or virtual threads (that is `java`); NOT engine-level SQL schema/index/EXPLAIN (that is `postgresdb`)."
+tags: [java, spring, jpa, security, backend]
+recommends: [java, postgresdb, secure-coding, deployment]
+origin: ai-hub
+---
+
+# Spring Boot backends (Boot 4 / Framework 7)
+
+A Spring Boot app is **a thin web layer delegating to a transactional service layer over
+Spring Data JPA repositories** — wired by constructor injection, configured by typed
+`@ConfigurationProperties`, locked down by a `SecurityFilterChain` bean. Controllers
+validate input and delegate; they never own business logic, transactions, or persistence.
+Hold that shape and most "where does this go?" questions answer themselves.
+
+**Pinned stack** (verify against the project's `pom.xml`/`build.gradle` — do not assume):
+Spring Boot 4.0 (GA 2025-11-20), Spring Framework 7, Java 17 baseline / Java 25 LTS, Jakarta
+EE 11 (`jakarta.*`, never `javax.*`), Jackson 3, Spring Security 7, Spring Data JPA /
+Hibernate 7, JUnit 5 + Testcontainers, Maven 3.9 / Gradle.
+
+If you are typing `WebSecurityConfigurerAdapter`, `@MockBean`, field `@Autowired`,
+`authorizeRequests`, or `javax.persistence` — **stop**. Those are the previous generation.
+The modern idioms below replace every one of them.
+
+## Boundaries
+
+- Plain Java language work (records, sealed types, virtual threads, streams, pattern
+  matching) with no Spring -> [`../java/SKILL.md`](../java/SKILL.md).
+- Async Python FastAPI -> [`../fastapi/SKILL.md`](../fastapi/SKILL.md). NestJS/Node ->
+  [`../nestjs/SKILL.md`](../nestjs/SKILL.md). Django -> [`../django/SKILL.md`](../django/SKILL.md).
+- Engine-level SQL: schema/index design, `EXPLAIN`, partitioning, zero-downtime DDL ->
+  [`../postgresdb/SKILL.md`](../postgresdb/SKILL.md) (this skill drives the JPA layer above it).
+- Language-agnostic injection/authz/secret theory ->
+  [`../secure-coding/SKILL.md`](../secure-coding/SKILL.md).
+- Dockerfile/Compose/CI/CD mechanics -> [`../deployment/SKILL.md`](../deployment/SKILL.md)
+  (keep only a build note here).
+
+## Project layout
+
+Package by feature, not by layer — colocation keeps a change to one feature in one folder.
+
+```text
+com.acme.shop
+├── order/
+│   ├── OrderController.java       // @RestController — web edge
+│   ├── OrderService.java          // @Service — @Transactional unit of work
+│   ├── OrderRepository.java       // extends JpaRepository<Order, Long>
+│   ├── Order.java                 // @Entity (jakarta.persistence)
+│   └── dto/CreateOrderRequest.java, OrderResponse.java   // records, never entities
+├── config/AppProperties.java      // @ConfigurationProperties record
+├── security/SecurityConfig.java   // SecurityFilterChain bean
+└── ShopApplication.java           // @SpringBootApplication
+```
+
+## Controllers
+
+`@RestController` + DTO records, `@Valid` on the body (Bean Validation, `jakarta.validation`)
+so business code can assume valid data, `ResponseEntity` for 201/`Location`, a
+`@RestControllerAdvice` for one error envelope. The controller parses, validates, delegates
+and maps — any branch with business meaning belongs in the service, where it is transactional
+and unit-testable without MVC. Boot 4 adds first-class versioning via a `version` attribute
+on the mapping — one controller serves many versions, no path duplication.
+
+```java
+@RestController
+@RequestMapping("/api/users")
+class UserController {
+    private final UserService users;
+    UserController(UserService users) { this.users = users; }   // constructor injection
+
+    @PostMapping(version = "1")                                  // Boot 4 API versioning
+    ResponseEntity<UserResponse> create(@Valid @RequestBody CreateUserRequest req) {
+        UserResponse body = users.create(req);
+        URI location = URI.create("/api/users/" + body.id());
+        return ResponseEntity.created(location).body(body);     // 201 + Location
+    }
+}
+
+record CreateUserRequest(@NotBlank String name, @Email String email) {}
+record UserResponse(Long id, String name, String email) {}
+```
+
+```java
+@RestControllerAdvice
+class ApiExceptionHandler {
+    @ExceptionHandler(MethodArgumentNotValidException.class)
+    ResponseEntity<ApiError> onInvalid(MethodArgumentNotValidException e) {
+        var details = e.getBindingResult().getFieldErrors().stream()
+            .map(f -> f.getField() + ": " + f.getDefaultMessage()).toList();
+        return ResponseEntity.badRequest().body(new ApiError("validation_failed", "Invalid request", details));
+    }
+}
+record ApiError(String code, String message, List<String> details) {}
+```
+
+**Bad -> Good** — never return the entity; it leaks columns and lazy-loads in the serializer:
+
+```java
+// Bad: leaks columns; lazy fields blow up in the serializer after the tx closes.
+@GetMapping("/{id}") User get(@PathVariable Long id) { return repo.findById(id).orElseThrow(); }
+// Good: map to a DTO inside the transactional service.
+@GetMapping("/{id}") UserResponse get(@PathVariable Long id) { return users.get(id); }
+```
+
+## Service + transactions
+
+Constructor-injected, `final` fields, `@Transactional` on the write path, `readOnly = true`
+on queries (lets Hibernate skip dirty checking). `@Transactional` belongs on service methods,
+never on a controller or repository: the transaction must wrap the unit of work, not the HTTP
+request or a single query.
+
+```java
+@Service
+class UserService {
+    private final UserRepository repo;
+    private final PasswordEncoder encoder;
+    UserService(UserRepository repo, PasswordEncoder encoder) { this.repo = repo; this.encoder = encoder; }
+
+    @Transactional
+    UserResponse create(CreateUserRequest req) {
+        var user = repo.save(new User(req.name(), req.email(), encoder.encode(req.rawPassword())));
+        return new UserResponse(user.getId(), user.getName(), user.getEmail());
+    }
+
+    @Transactional(readOnly = true)
+    UserResponse get(Long id) {
+        return repo.findById(id).map(this::toResponse).orElseThrow(() -> new NotFoundException(id));
+    }
+}
+```
+
+Two traps that produce "my `@Transactional` isn't rolling back":
+- **Self-invocation.** Calling `this.other()` inside the same bean bypasses the proxy, so its
+  `@Transactional` is ignored. Split into another bean or accept the outer transaction.
+- **Checked exceptions don't roll back by default.** Spring rolls back on `RuntimeException`
+  only; use `@Transactional(rollbackFor = ...)` for checked ones.
+
+**Bad -> Good** — field injection vs constructor:
+
+```java
+// Bad: not testable with `new`, hides missing beans until runtime, allows final-less mutation.
+@Autowired private UserRepository repo;
+// Good:
+private final UserRepository repo;
+UserService(UserRepository repo) { this.repo = repo; }
+```
+
+## JPA persistence
+
+`jakarta.persistence` imports (never `javax`). Spring Data gives you derived queries for free
+and `@Query` for the rest; `Pageable`/`Page` for paging.
+
+```java
+import jakarta.persistence.*;
+
+@Entity @Table(name = "users")
+class User {
+    @Id @GeneratedValue(strategy = GenerationType.IDENTITY) private Long id;
+    private String name;
+    @Column(unique = true) private String email;
+    @OneToMany(mappedBy = "user") private List<Order> orders = new ArrayList<>();
+    // getters; protected no-arg ctor for Hibernate
+}
+
+interface UserRepository extends JpaRepository<User, Long> {
+    Optional<User> findByEmail(String email);                       // derived query
+    Page<User> findByNameContaining(String q, Pageable page);       // paginated
+
+    @Query("select u from User u join fetch u.orders where u.id = :id")
+    Optional<User> findWithOrders(@Param("id") Long id);            // fetch join kills N+1
+}
+```
+
+**N+1 symptom:** iterating a lazy collection issues one query per parent. Fix with a
+`join fetch`, an `@EntityGraph`, or `@BatchSize`. **`LazyInitializationException`** means you
+touched a lazy field after the transaction (and its Hibernate session) closed — map to a DTO
+*inside* the `@Transactional` service, or fetch eagerly for that path. Relationship/cascade
+depth, projections, Specifications, optimistic locking and migration tooling are in
+[`references/jpa.md`](references/jpa.md).
+
+## Configuration & profiles
+
+```yaml
+# application.yml — no secrets committed here; import them at boot.
+spring:
+  config:
+    import: "optional:configtree:/run/secrets/"   # mount real secrets at runtime
+  datasource:
+    url: ${DB_URL}
+    username: ${DB_USER}
+    password: ${DB_PASSWORD}
+app:
+  invite-ttl: 24h
+  max-orders-per-day: 50
+---
+spring:
+  config:
+    activate:
+      on-profile: dev
+app:
+  max-orders-per-day: 5
+```
+
+```java
+@ConfigurationProperties(prefix = "app")
+record AppProperties(Duration inviteTtl, int maxOrdersPerDay) {}   // typed, validated at startup
+// register once: @EnableConfigurationProperties(AppProperties.class) on a @Configuration
+```
+
+**Bad -> Good** — scattered `@Value("${app.max-orders-per-day}")` strings vs one injected
+`AppProperties` record. One typed binding beats string keys sprinkled across the codebase and
+fails fast on a missing/mistyped key instead of NPE-ing later.
+
+## Security
+
+A single `SecurityFilterChain` bean with the lambda DSL, stateless for token APIs, JWT via the
+resource server.
+
+```java
+@Configuration
+@EnableMethodSecurity                                            // enables @PreAuthorize
+class SecurityConfig {
+    @Bean
+    SecurityFilterChain api(HttpSecurity http) throws Exception {
+        http
+          .csrf(csrf -> csrf.disable())                          // OK: stateless token API, no cookies
+          .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
+          .authorizeHttpRequests(auth -> auth
+              .requestMatchers(HttpMethod.POST, "/api/users").permitAll()
+              .requestMatchers("/api/admin/**").hasRole("ADMIN")
+              .anyRequest().authenticated())
+          .oauth2ResourceServer(o -> o.jwt(Customizer.withDefaults()));
+        return http.build();
+    }
+
+    @Bean PasswordEncoder passwordEncoder() { return new BCryptPasswordEncoder(); }
+}
+```
+
+Order `requestMatchers` from most specific to least — the first match wins, so a broad
+`permitAll` placed early opens routes you meant to lock. Full JWT/OAuth2 client, method
+security, CORS, and CSRF posture (token vs cookie apps) live in
+[`references/security.md`](references/security.md). For the language-agnostic authz/secret
+principles behind these rules, see [`../secure-coding/SKILL.md`](../secure-coding/SKILL.md).
+
+## Testing
+
+Pick the narrowest slice that exercises what you changed — `@SpringBootTest` only when you
+genuinely need the full context:
+
+| Slice | Loads | Use for | Collaborators |
+|---|---|---|---|
+| `@WebMvcTest` | web layer + Security + MockMvc | one controller's HTTP contract | `@MockitoBean` the service |
+| `@DataJpaTest` | JPA + in-memory/TC DB, rolls back per test | repository queries, mappings | real repo, test DB |
+| `@SpringBootTest` | full context | end-to-end / integration | real beans, Testcontainers |
+
+`@MockBean`/`@SpyBean` are removed — use `@MockitoBean`/`@MockitoSpyBean` from
+`org.springframework.test.context.bean.override.mockito`.
+
+```java
+@WebMvcTest(UserController.class)
+class UserControllerTest {
+    @Autowired MockMvc mvc;
+    @MockitoBean UserService users;                              // not @MockBean
+
+    @Test void rejectsBlankName() throws Exception {
+        mvc.perform(post("/api/users").contentType(MediaType.APPLICATION_JSON)
+                .content("{\"name\":\"\",\"email\":\"a@b.co\"}"))
+           .andExpect(status().isBadRequest());
+    }
+}
+```
+
+Integration DB via Testcontainers + `@ServiceConnection` (auto-wires connection details, no
+`@DynamicPropertySource`):
+
+```java
+@TestConfiguration(proxyBeanMethods = false)
+class ContainersConfig {
+    @Bean @ServiceConnection
+    PostgreSQLContainer<?> postgres() { return new PostgreSQLContainer<>("postgres:17"); }
+}
+```
+
+Slice deep dive, container reuse, `MockMvcTester`/`WebTestClient`, and the CI gate are in
+[`references/testing.md`](references/testing.md).
+
+## HTTP clients & resilience
+
+Outbound calls: declare an `@HttpExchange` interface and register it — no manual
+`RestTemplate`/`HttpServiceProxyFactory` boilerplate.
+
+```java
+@HttpExchange("/v1")
+interface BillingClient {
+    @GetExchange("/invoices/{id}") Invoice invoice(@PathVariable String id);
+}
+// register: @ImportHttpServices(group = "billing", types = BillingClient.class) on a @Configuration
+```
+
+`RestClient` is the modern synchronous client for ad-hoc calls. For built-in resilience,
+`@Retryable` and `@ConcurrencyLimit` are core in Framework 7 — no extra Spring Retry
+dependency for the basics.
+
+## Anti-patterns
+
+| Anti-pattern | Why it's wrong | Do instead |
+|---|---|---|
+| Extend `WebSecurityConfigurerAdapter` | Removed in Security 6/7 | `SecurityFilterChain` bean + lambda DSL |
+| `@Autowired` on a field | Untestable, hides missing beans till runtime | constructor injection, `final` fields |
+| `@Transactional` on a `@RestController` | Tx must wrap the unit of work, not the request | put it on the service method |
+| Business branching in the controller | Not transactional, needs MVC to test | move the decision into the `@Service` |
+| Return the `@Entity` from a controller | Leaks columns, lazy-loads in serializer (LIE) | map to a DTO record inside the tx |
+| Request body reaching the service unvalidated | Business code can no longer assume valid data | `@Valid` + `jakarta.validation` at the edge |
+| Scattered `@Value("${...}")` config keys | String keys, no validation, fails late | one typed `@ConfigurationProperties` record |
+| Use `@MockBean` / `@SpyBean` | Replaced in Boot 4 | `@MockitoBean` / `@MockitoSpyBean` |
+| `import javax.persistence` / `javax.validation` | Jakarta EE 11 baseline | `jakarta.*` |
+| `authorizeRequests` / `antMatchers` | Gone in Security 6/7 | `authorizeHttpRequests` + `requestMatchers` |
+| `csrf().disable()` with no rationale | Silently opens cookie-session apps | disable only for stateless token APIs; comment why |
+| `@SpringBootTest` for one controller | Slow, loads everything | `@WebMvcTest` + `@MockitoBean` |
+| One 800-line `@Service` | Untestable, tangled transactions | split per use case / aggregate |
+| `catch (Exception e)` and echo `e.getMessage()` | Leaks internals, swallows bugs | `@RestControllerAdvice` + typed error envelope |
+| Serialize a lazy collection after the tx closes | `LazyInitializationException` / N+1 | fetch join or `@EntityGraph`, map in-tx |
+
+`scripts/verify.sh` greps a project for the legacy idioms above (read-only, best effort).
+
+## Quick reference
+
+| Task | Idiom |
+|---|---|
+| Inject a dependency | constructor arg, `final` field |
+| Expose an endpoint | `@RestController` + `@GetMapping`/`@PostMapping(version=)` |
+| Validate input | `@Valid @RequestBody` + `jakarta.validation` annotations |
+| Get by id | `repo.findById(id).orElseThrow(...)` in a `readOnly` tx |
+| Paginate | `Page<T> findBy...(..., Pageable page)` |
+| Custom query | `@Query("select ... join fetch ...")` |
+| Transaction boundary | `@Transactional` on the service method |
+| Hash a password | `PasswordEncoder` bean (`BCryptPasswordEncoder`) |
+| Lock down routes | `SecurityFilterChain` + `authorizeHttpRequests`/`requestMatchers` |
+| JWT API | `oauth2ResourceServer(o -> o.jwt(...))`, stateless session |
+| Mock a collaborator in a test | `@MockitoBean` |
+| Integration DB | Testcontainers `@Bean` + `@ServiceConnection` |
+
+## Project grounding
+
+If the repo has a `02-DOCS/` wiki, record stack decisions (Boot version, security posture,
+test strategy, migration tool) in `02-DOCS/wiki/stack/spring-boot.md` and link it from the
+`CLAUDE.md` Knowledge map. This is recorded, not gated — if there is no `02-DOCS/`, skip
+silently; you may suggest the project harness if the user wants persistent docs.

package/skills/shared/spring-boot/evals/README.md

@@ -0,0 +1,11 @@
+# Evals — spring-boot
+
+These cases are LLM-graded routing and capability checks, not a runtime test harness. Run them
+through the repo's eval runner against this skill's `description` + body. `should_trigger`
+asserts the router selects `spring-boot` (including the non-obvious symptom prompts like the
+`@Transactional` rollback and `LazyInitializationException` cases and the Spanish/Catalan
+phrasings); `should_not_trigger` asserts it prefers the named sibling instead (`java`,
+`fastapi`, `postgresdb`, `deployment`, `secure-coding`). The `capability` case is graded by
+checking the produced solution against the `must_include` rubric — each bullet is a modern
+Boot 4 idiom that must appear (and the corresponding legacy idiom must be absent). There is no
+compilation step here; `scripts/verify.sh` is the static lint that complements these grades.

package/skills/shared/spring-boot/evals/cases.yaml

@@ -0,0 +1,49 @@
+skill: spring-boot
+
+should_trigger:
+  - prompt: "Add a REST endpoint to create an order in our Spring Boot service."
+    why: "Core controller/service work — the central job of the skill."
+  - prompt: "My @Transactional method isn't rolling back when it throws, why?"
+    why: "Non-obvious proxy self-invocation + checked-exception-no-rollback trap; documented in the service/transactions section."
+  - prompt: "I get LazyInitializationException when the JSON serializer reads the response."
+    why: "Classic JPA fetch/session-boundary symptom; the fix is map-to-DTO-in-tx, a core rule here."
+  - prompt: "Migra esta config de seguridad, usa WebSecurityConfigurerAdapter y está deprecada."
+    why: "Spanish; SecurityFilterChain migration is an explicit modern-surface concern of the skill."
+  - prompt: "Set up a @WebMvcTest for the controller and mock the service."
+    why: "Slice testing + @MockitoBean — non-obvious that @MockBean is the wrong (removed) idiom."
+  - prompt: "Configura @ConfigurationProperties con perfiles para esta app."
+    why: "Catalan/Spanish; typed @ConfigurationProperties + profiles is a documented config surface."
+  - prompt: "We have N+1 selects on a lazy collection — how do I fetch-join it?"
+    why: "JPA fetch strategy / @EntityGraph, a documented depth area."
+
+should_not_trigger:
+  - prompt: "Refactor this instanceof ladder into a pattern-matching switch."
+    route_to: java
+    why: "Pure Java language feature, no Spring wiring involved."
+  - prompt: "Build the same API in FastAPI with async SQLAlchemy."
+    route_to: fastapi
+    why: "Structural twin but a different framework/ecosystem."
+  - prompt: "Design the Postgres indexes and run EXPLAIN on this slow query."
+    route_to: postgresdb
+    why: "Engine-level SQL; this skill drives the JPA layer above it, not index design."
+  - prompt: "Write the Dockerfile and GitHub Actions pipeline to deploy this jar."
+    route_to: deployment
+    why: "Container/CI mechanics, not Spring framework code."
+  - prompt: "Explain how SQL injection defenses work in general."
+    route_to: secure-coding
+    why: "Language-agnostic security theory, not the Spring security surface."
+
+capability:
+  - scenario: >
+      Implement a POST /api/v1/users endpoint backed by JPA: validate the request, run the
+      write in a service-layer transaction, add a SecurityFilterChain that permits the route,
+      and add a @WebMvcTest for the controller.
+    must_include:
+      - "Constructor injection with final fields (no field @Autowired)."
+      - "DTO records for request and response (never the @Entity exposed)."
+      - "@Transactional on the service method, not the controller."
+      - "SecurityFilterChain bean using authorizeHttpRequests + requestMatchers."
+      - "@WebMvcTest with the service supplied via @MockitoBean (not @MockBean)."
+      - "jakarta.* imports (validation/persistence), never javax.*."
+      - "@Valid at the controller edge."
+      - "ResponseEntity 201 Created with a Location header."

package/skills/shared/spring-boot/references/jpa.md

@@ -0,0 +1,94 @@
+# JPA persistence depth
+
+The SKILL.md covers entities, `JpaRepository`, derived/`@Query`, paging, and the N+1 /
+`LazyInitializationException` headline. This is the depth: relationships, fetch strategy,
+projections, Specifications, optimistic locking, and migrations. Engine-level SQL (index
+design, `EXPLAIN`, partitioning) is `../postgresdb/SKILL.md`'s job — this file stays on the
+JPA/Hibernate layer above it.
+
+## Relationships, cascade, fetch type
+
+- Default `@ManyToOne` is **EAGER**, `@OneToMany`/`@ManyToMany` are **LAZY**. Make
+  `@ManyToOne` lazy explicitly when you don't always need the parent:
+  `@ManyToOne(fetch = FetchType.LAZY)`.
+- Never put `CascadeType.ALL` on a `@ManyToOne` — you'll cascade-delete shared parents. Cascade
+  belongs on the owning side of a true parent/child aggregate (`@OneToMany`).
+- Map the relationship on **one** side and mark the other `mappedBy`. Two owning sides write
+  the join column twice.
+
+```java
+@Entity
+class Order {
+    @ManyToOne(fetch = FetchType.LAZY) @JoinColumn(name = "user_id")
+    private User user;
+    @OneToMany(mappedBy = "order", cascade = CascadeType.ALL, orphanRemoval = true)
+    private List<OrderLine> lines = new ArrayList<>();
+}
+```
+
+## N+1 detection and fixes
+
+**Detect.** Turn on SQL logging in a test profile and watch for a query repeated once per
+parent:
+
+```yaml
+logging.level.org.hibernate.SQL: DEBUG
+spring.jpa.properties.hibernate.generate_statistics: true   # logs query counts per session
+```
+
+**Fix, in order of preference:**
+
+1. **`join fetch`** in a `@Query` — best when you always need the association for that path.
+2. **`@EntityGraph`** on the repository method — declarative, reusable, no JPQL.
+   ```java
+   @EntityGraph(attributePaths = {"orders"})
+   Optional<User> findById(Long id);
+   ```
+3. **`@BatchSize(size = 50)`** on the collection/entity — turns N+1 into N/50 IN-queries when
+   you can't fetch-join (e.g. multiple bags).
+
+Do **not** "fix" N+1 by making everything EAGER — that just moves the cost to every query and
+risks cartesian-product blowups when fetch-joining two collections at once.
+
+## Projections — don't fetch what you won't return
+
+- **Interface projection:** declare an interface of getters; Spring builds a proxy selecting
+  only those columns.
+  ```java
+  interface UserSummary { Long getId(); String getName(); }
+  List<UserSummary> findByActiveTrue();
+  ```
+- **DTO/record projection** via constructor expression:
+  `@Query("select new com.acme.UserSummary(u.id, u.name) from User u")`.
+
+Projections sidestep `LazyInitializationException` entirely — there is no lazy proxy to touch.
+
+## Specifications (dynamic queries)
+
+For optional filters, prefer `JpaSpecificationExecutor` over building JPQL strings:
+
+```java
+interface OrderRepository extends JpaRepository<Order, Long>, JpaSpecificationExecutor<Order> {}
+
+Specification<Order> byStatus(Status s) {
+    return (root, q, cb) -> s == null ? null : cb.equal(root.get("status"), s);
+}
+// repo.findAll(byStatus(status).and(byUser(userId)), pageable);
+```
+
+## Optimistic locking
+
+Add a `@Version` field to detect concurrent updates; Hibernate increments it and throws
+`OptimisticLockingFailureException` on a stale write. Cheaper than pessimistic locks for
+low-contention web apps.
+
+```java
+@Version private long version;
+```
+
+## Migrations
+
+Let **Flyway** (`V1__init.sql`, `V2__add_index.sql`) or **Liquibase** own the schema; set
+`spring.jpa.hibernate.ddl-auto=validate` so Hibernate verifies but never mutates the schema.
+Never ship `ddl-auto=update` to production — it makes uncontrolled, unordered changes. The
+actual DDL/index design for those migration files is `../postgresdb/SKILL.md`.

package/skills/shared/spring-boot/references/security.md

@@ -0,0 +1,92 @@
+# Spring Security depth (Security 7)
+
+SKILL.md has the headline: one `SecurityFilterChain` bean, lambda DSL,
+`authorizeHttpRequests` + `requestMatchers`, stateless for token APIs. This is the depth.
+The language-agnostic authz/secret reasoning is `../secure-coding/SKILL.md`; this file is the
+Spring wiring.
+
+## JWT resource server (validate tokens minted elsewhere)
+
+```yaml
+spring:
+  security:
+    oauth2:
+      resourceserver:
+        jwt:
+          issuer-uri: https://issuer.example.com/   # discovers JWKS + validates iss/exp/sig
+```
+
+```java
+@Bean
+SecurityFilterChain api(HttpSecurity http) throws Exception {
+    http
+      .csrf(csrf -> csrf.disable())
+      .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
+      .authorizeHttpRequests(auth -> auth
+          .requestMatchers("/actuator/health", "/api/public/**").permitAll()
+          .anyRequest().authenticated())
+      .oauth2ResourceServer(o -> o.jwt(jwt -> jwt.jwtAuthenticationConverter(converter())));
+    return http.build();
+}
+```
+
+Map JWT scopes/claims to authorities with a `JwtAuthenticationConverter` (e.g. a `roles` claim
+-> `ROLE_*`) so `hasRole`/`@PreAuthorize` work against your token's shape.
+
+## OAuth2 client (call protected services on the user's behalf)
+
+`spring-boot-starter-oauth2-client` + `spring.security.oauth2.client.registration.*`. Pair it
+with an `@HttpExchange` client (see SKILL.md) so the access token is attached automatically by
+an `OAuth2ClientHttpRequestInterceptor`/exchange filter — no manual `Authorization` header.
+
+## Method security
+
+`@EnableMethodSecurity` (replaces the old `@EnableGlobalMethodSecurity`) turns on
+`@PreAuthorize`/`@PostAuthorize`:
+
+```java
+@PreAuthorize("hasRole('ADMIN') or #userId == authentication.name")
+UserResponse get(Long userId) { ... }
+```
+
+Use it for row-level / ownership checks the URL matcher can't express. URL matchers guard
+coarse routes; method security guards fine-grained access.
+
+## CORS
+
+Define one `CorsConfigurationSource` bean and reference it from the chain — never echo the
+request `Origin` blindly:
+
+```java
+@Bean CorsConfigurationSource cors() {
+    var c = new CorsConfiguration();
+    c.setAllowedOrigins(List.of("https://app.example.com"));   // explicit allowlist
+    c.setAllowedMethods(List.of("GET", "POST", "PUT", "DELETE"));
+    c.setAllowCredentials(true);
+    var src = new UrlBasedCorsConfigurationSource();
+    src.registerCorsConfiguration("/api/**", c);
+    return src;
+}
+// in the chain: .cors(Customizer.withDefaults())
+```
+
+`allowCredentials(true)` with `allowedOrigins("*")` is rejected by the spec — list real origins.
+
+## CSRF posture — the one decision people get wrong
+
+- **Token API, no cookies** (JWT in `Authorization`): CSRF is not exploitable, so
+  `csrf.disable()` is correct. Always leave a comment saying *why* it's disabled.
+- **Cookie/session app** (server-rendered, `JSESSIONID`): keep CSRF **enabled**; use the
+  `CookieCsrfTokenRepository` and send the token from the client. Disabling it here is a real
+  vulnerability.
+
+## Common pitfalls
+
+- **Matcher ordering:** first match wins. A broad `permitAll()` placed before a narrow
+  `hasRole()` opens the narrow route. Order most-specific-first.
+- **Forgetting `STATELESS`:** a "stateless" API that still creates sessions leaks `JSESSIONID`
+  cookies and breaks horizontal scaling.
+- **`permitAll` vs no rule:** `anyRequest().authenticated()` must be the catch-all; an
+  unmatched request with no terminal rule is a misconfiguration.
+- **Encoding passwords with the wrong bean:** use the injected `PasswordEncoder`
+  (`BCryptPasswordEncoder` or `DelegatingPasswordEncoder`), never `MessageDigest`/plain hashes.