compact-agent 1.10.1 → 1.11.0

package/resources/ecc/skills/springboot-patterns/SKILL.md

@@ -0,0 +1,314 @@
+---
+name: springboot-patterns
+description: Spring Boot architecture patterns, REST API design, layered services, data access, caching, async processing, and logging. Use for Java Spring Boot backend work.
+origin: ECC
+---
+
+# Spring Boot Development Patterns
+
+Spring Boot architecture and API patterns for scalable, production-grade services.
+
+## When to Activate
+
+- Building REST APIs with Spring MVC or WebFlux
+- Structuring controller → service → repository layers
+- Configuring Spring Data JPA, caching, or async processing
+- Adding validation, exception handling, or pagination
+- Setting up profiles for dev/staging/production environments
+- Implementing event-driven patterns with Spring Events or Kafka
+
+## REST API Structure
+
+```java
+@RestController
+@RequestMapping("/api/markets")
+@Validated
+class MarketController {
+  private final MarketService marketService;
+
+  MarketController(MarketService marketService) {
+    this.marketService = marketService;
+  }
+
+  @GetMapping
+  ResponseEntity<Page<MarketResponse>> list(
+      @RequestParam(defaultValue = "0") int page,
+      @RequestParam(defaultValue = "20") int size) {
+    Page<Market> markets = marketService.list(PageRequest.of(page, size));
+    return ResponseEntity.ok(markets.map(MarketResponse::from));
+  }
+
+  @PostMapping
+  ResponseEntity<MarketResponse> create(@Valid @RequestBody CreateMarketRequest request) {
+    Market market = marketService.create(request);
+    return ResponseEntity.status(HttpStatus.CREATED).body(MarketResponse.from(market));
+  }
+}
+```
+
+## Repository Pattern (Spring Data JPA)
+
+```java
+public interface MarketRepository extends JpaRepository<MarketEntity, Long> {
+  @Query("select m from MarketEntity m where m.status = :status order by m.volume desc")
+  List<MarketEntity> findActive(@Param("status") MarketStatus status, Pageable pageable);
+}
+```
+
+## Service Layer with Transactions
+
+```java
+@Service
+public class MarketService {
+  private final MarketRepository repo;
+
+  public MarketService(MarketRepository repo) {
+    this.repo = repo;
+  }
+
+  @Transactional
+  public Market create(CreateMarketRequest request) {
+    MarketEntity entity = MarketEntity.from(request);
+    MarketEntity saved = repo.save(entity);
+    return Market.from(saved);
+  }
+}
+```
+
+## DTOs and Validation
+
+```java
+public record CreateMarketRequest(
+    @NotBlank @Size(max = 200) String name,
+    @NotBlank @Size(max = 2000) String description,
+    @NotNull @FutureOrPresent Instant endDate,
+    @NotEmpty List<@NotBlank String> categories) {}
+
+public record MarketResponse(Long id, String name, MarketStatus status) {
+  static MarketResponse from(Market market) {
+    return new MarketResponse(market.id(), market.name(), market.status());
+  }
+}
+```
+
+## Exception Handling
+
+```java
+@ControllerAdvice
+class GlobalExceptionHandler {
+  @ExceptionHandler(MethodArgumentNotValidException.class)
+  ResponseEntity<ApiError> handleValidation(MethodArgumentNotValidException ex) {
+    String message = ex.getBindingResult().getFieldErrors().stream()
+        .map(e -> e.getField() + ": " + e.getDefaultMessage())
+        .collect(Collectors.joining(", "));
+    return ResponseEntity.badRequest().body(ApiError.validation(message));
+  }
+
+  @ExceptionHandler(AccessDeniedException.class)
+  ResponseEntity<ApiError> handleAccessDenied() {
+    return ResponseEntity.status(HttpStatus.FORBIDDEN).body(ApiError.of("Forbidden"));
+  }
+
+  @ExceptionHandler(Exception.class)
+  ResponseEntity<ApiError> handleGeneric(Exception ex) {
+    // Log unexpected errors with stack traces
+    return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
+        .body(ApiError.of("Internal server error"));
+  }
+}
+```
+
+## Caching
+
+Requires `@EnableCaching` on a configuration class.
+
+```java
+@Service
+public class MarketCacheService {
+  private final MarketRepository repo;
+
+  public MarketCacheService(MarketRepository repo) {
+    this.repo = repo;
+  }
+
+  @Cacheable(value = "market", key = "#id")
+  public Market getById(Long id) {
+    return repo.findById(id)
+        .map(Market::from)
+        .orElseThrow(() -> new EntityNotFoundException("Market not found"));
+  }
+
+  @CacheEvict(value = "market", key = "#id")
+  public void evict(Long id) {}
+}
+```
+
+## Async Processing
+
+Requires `@EnableAsync` on a configuration class.
+
+```java
+@Service
+public class NotificationService {
+  @Async
+  public CompletableFuture<Void> sendAsync(Notification notification) {
+    // send email/SMS
+    return CompletableFuture.completedFuture(null);
+  }
+}
+```
+
+## Logging (SLF4J)
+
+```java
+@Service
+public class ReportService {
+  private static final Logger log = LoggerFactory.getLogger(ReportService.class);
+
+  public Report generate(Long marketId) {
+    log.info("generate_report marketId={}", marketId);
+    try {
+      // logic
+    } catch (Exception ex) {
+      log.error("generate_report_failed marketId={}", marketId, ex);
+      throw ex;
+    }
+    return new Report();
+  }
+}
+```
+
+## Middleware / Filters
+
+```java
+@Component
+public class RequestLoggingFilter extends OncePerRequestFilter {
+  private static final Logger log = LoggerFactory.getLogger(RequestLoggingFilter.class);
+
+  @Override
+  protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response,
+      FilterChain filterChain) throws ServletException, IOException {
+    long start = System.currentTimeMillis();
+    try {
+      filterChain.doFilter(request, response);
+    } finally {
+      long duration = System.currentTimeMillis() - start;
+      log.info("req method={} uri={} status={} durationMs={}",
+          request.getMethod(), request.getRequestURI(), response.getStatus(), duration);
+    }
+  }
+}
+```
+
+## Pagination and Sorting
+
+```java
+PageRequest page = PageRequest.of(pageNumber, pageSize, Sort.by("createdAt").descending());
+Page<Market> results = marketService.list(page);
+```
+
+## Error-Resilient External Calls
+
+```java
+public <T> T withRetry(Supplier<T> supplier, int maxRetries) {
+  int attempts = 0;
+  while (true) {
+    try {
+      return supplier.get();
+    } catch (Exception ex) {
+      attempts++;
+      if (attempts >= maxRetries) {
+        throw ex;
+      }
+      try {
+        Thread.sleep((long) Math.pow(2, attempts) * 100L);
+      } catch (InterruptedException ie) {
+        Thread.currentThread().interrupt();
+        throw ex;
+      }
+    }
+  }
+}
+```
+
+## Rate Limiting (Filter + Bucket4j)
+
+**Security Note**: The `X-Forwarded-For` header is untrusted by default because clients can spoof it.
+Only use forwarded headers when:
+1. Your app is behind a trusted reverse proxy (nginx, AWS ALB, etc.)
+2. You have registered `ForwardedHeaderFilter` as a bean
+3. You have configured `server.forward-headers-strategy=NATIVE` or `FRAMEWORK` in application properties
+4. Your proxy is configured to overwrite (not append to) the `X-Forwarded-For` header
+
+When `ForwardedHeaderFilter` is properly configured, `request.getRemoteAddr()` will automatically
+return the correct client IP from the forwarded headers. Without this configuration, use
+`request.getRemoteAddr()` directly—it returns the immediate connection IP, which is the only
+trustworthy value.
+
+```java
+@Component
+public class RateLimitFilter extends OncePerRequestFilter {
+  private final Map<String, Bucket> buckets = new ConcurrentHashMap<>();
+
+  /*
+   * SECURITY: This filter uses request.getRemoteAddr() to identify clients for rate limiting.
+   *
+   * If your application is behind a reverse proxy (nginx, AWS ALB, etc.), you MUST configure
+   * Spring to handle forwarded headers properly for accurate client IP detection:
+   *
+   * 1. Set server.forward-headers-strategy=NATIVE (for cloud platforms) or FRAMEWORK in
+   *    application.properties/yaml
+   * 2. If using FRAMEWORK strategy, register ForwardedHeaderFilter:
+   *
+   *    @Bean
+   *    ForwardedHeaderFilter forwardedHeaderFilter() {
+   *        return new ForwardedHeaderFilter();
+   *    }
+   *
+   * 3. Ensure your proxy overwrites (not appends) the X-Forwarded-For header to prevent spoofing
+   * 4. Configure server.tomcat.remoteip.trusted-proxies or equivalent for your container
+   *
+   * Without this configuration, request.getRemoteAddr() returns the proxy IP, not the client IP.
+   * Do NOT read X-Forwarded-For directly—it is trivially spoofable without trusted proxy handling.
+   */
+  @Override
+  protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response,
+      FilterChain filterChain) throws ServletException, IOException {
+    // Use getRemoteAddr() which returns the correct client IP when ForwardedHeaderFilter
+    // is configured, or the direct connection IP otherwise. Never trust X-Forwarded-For
+    // headers directly without proper proxy configuration.
+    String clientIp = request.getRemoteAddr();
+
+    Bucket bucket = buckets.computeIfAbsent(clientIp,
+        k -> Bucket.builder()
+            .addLimit(Bandwidth.classic(100, Refill.greedy(100, Duration.ofMinutes(1))))
+            .build());
+
+    if (bucket.tryConsume(1)) {
+      filterChain.doFilter(request, response);
+    } else {
+      response.setStatus(HttpStatus.TOO_MANY_REQUESTS.value());
+    }
+  }
+}
+```
+
+## Background Jobs
+
+Use Spring’s `@Scheduled` or integrate with queues (e.g., Kafka, SQS, RabbitMQ). Keep handlers idempotent and observable.
+
+## Observability
+
+- Structured logging (JSON) via Logback encoder
+- Metrics: Micrometer + Prometheus/OTel
+- Tracing: Micrometer Tracing with OpenTelemetry or Brave backend
+
+## Production Defaults
+
+- Prefer constructor injection, avoid field injection
+- Enable `spring.mvc.problemdetails.enabled=true` for RFC 7807 errors (Spring Boot 3+)
+- Configure HikariCP pool sizes for workload, set timeouts
+- Use `@Transactional(readOnly = true)` for queries
+- Enforce null-safety via `@NonNull` and `Optional` where appropriate
+
+**Remember**: Keep controllers thin, services focused, repositories simple, and errors handled centrally. Optimize for maintainability and testability.

package/resources/ecc/skills/springboot-security/SKILL.md

@@ -0,0 +1,272 @@
+---
+name: springboot-security
+description: Spring Security best practices for authn/authz, validation, CSRF, secrets, headers, rate limiting, and dependency security in Java Spring Boot services.
+origin: ECC
+---
+
+# Spring Boot Security Review
+
+Use when adding auth, handling input, creating endpoints, or dealing with secrets.
+
+## When to Activate
+
+- Adding authentication (JWT, OAuth2, session-based)
+- Implementing authorization (@PreAuthorize, role-based access)
+- Validating user input (Bean Validation, custom validators)
+- Configuring CORS, CSRF, or security headers
+- Managing secrets (Vault, environment variables)
+- Adding rate limiting or brute-force protection
+- Scanning dependencies for CVEs
+
+## Authentication
+
+- Prefer stateless JWT or opaque tokens with revocation list
+- Use `httpOnly`, `Secure`, `SameSite=Strict` cookies for sessions
+- Validate tokens with `OncePerRequestFilter` or resource server
+
+```java
+@Component
+public class JwtAuthFilter extends OncePerRequestFilter {
+  private final JwtService jwtService;
+
+  public JwtAuthFilter(JwtService jwtService) {
+    this.jwtService = jwtService;
+  }
+
+  @Override
+  protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response,
+      FilterChain chain) throws ServletException, IOException {
+    String header = request.getHeader(HttpHeaders.AUTHORIZATION);
+    if (header != null && header.startsWith("Bearer ")) {
+      String token = header.substring(7);
+      Authentication auth = jwtService.authenticate(token);
+      SecurityContextHolder.getContext().setAuthentication(auth);
+    }
+    chain.doFilter(request, response);
+  }
+}
+```
+
+## Authorization
+
+- Enable method security: `@EnableMethodSecurity`
+- Use `@PreAuthorize("hasRole('ADMIN')")` or `@PreAuthorize("@authz.canEdit(#id)")`
+- Deny by default; expose only required scopes
+
+```java
+@RestController
+@RequestMapping("/api/admin")
+public class AdminController {
+
+  @PreAuthorize("hasRole('ADMIN')")
+  @GetMapping("/users")
+  public List<UserDto> listUsers() {
+    return userService.findAll();
+  }
+
+  @PreAuthorize("@authz.isOwner(#id, authentication)")
+  @DeleteMapping("/users/{id}")
+  public ResponseEntity<Void> deleteUser(@PathVariable Long id) {
+    userService.delete(id);
+    return ResponseEntity.noContent().build();
+  }
+}
+```
+
+## Input Validation
+
+- Use Bean Validation with `@Valid` on controllers
+- Apply constraints on DTOs: `@NotBlank`, `@Email`, `@Size`, custom validators
+- Sanitize any HTML with a whitelist before rendering
+
+```java
+// BAD: No validation
+@PostMapping("/users")
+public User createUser(@RequestBody UserDto dto) {
+  return userService.create(dto);
+}
+
+// GOOD: Validated DTO
+public record CreateUserDto(
+    @NotBlank @Size(max = 100) String name,
+    @NotBlank @Email String email,
+    @NotNull @Min(0) @Max(150) Integer age
+) {}
+
+@PostMapping("/users")
+public ResponseEntity<UserDto> createUser(@Valid @RequestBody CreateUserDto dto) {
+  return ResponseEntity.status(HttpStatus.CREATED)
+      .body(userService.create(dto));
+}
+```
+
+## SQL Injection Prevention
+
+- Use Spring Data repositories or parameterized queries
+- For native queries, use `:param` bindings; never concatenate strings
+
+```java
+// BAD: String concatenation in native query
+@Query(value = "SELECT * FROM users WHERE name = '" + name + "'", nativeQuery = true)
+
+// GOOD: Parameterized native query
+@Query(value = "SELECT * FROM users WHERE name = :name", nativeQuery = true)
+List<User> findByName(@Param("name") String name);
+
+// GOOD: Spring Data derived query (auto-parameterized)
+List<User> findByEmailAndActiveTrue(String email);
+```
+
+## Password Encoding
+
+- Always hash passwords with BCrypt or Argon2 — never store plaintext
+- Use `PasswordEncoder` bean, not manual hashing
+
+```java
+@Bean
+public PasswordEncoder passwordEncoder() {
+  return new BCryptPasswordEncoder(12); // cost factor 12
+}
+
+// In service
+public User register(CreateUserDto dto) {
+  String hashedPassword = passwordEncoder.encode(dto.password());
+  return userRepository.save(new User(dto.email(), hashedPassword));
+}
+```
+
+## CSRF Protection
+
+- For browser session apps, keep CSRF enabled; include token in forms/headers
+- For pure APIs with Bearer tokens, disable CSRF and rely on stateless auth
+
+```java
+http
+  .csrf(csrf -> csrf.disable())
+  .sessionManagement(sm -> sm.sessionCreationPolicy(SessionCreationPolicy.STATELESS));
+```
+
+## Secrets Management
+
+- No secrets in source; load from env or vault
+- Keep `application.yml` free of credentials; use placeholders
+- Rotate tokens and DB credentials regularly
+
+```yaml
+# BAD: Hardcoded in application.yml
+spring:
+  datasource:
+    password: mySecretPassword123
+
+# GOOD: Environment variable placeholder
+spring:
+  datasource:
+    password: ${DB_PASSWORD}
+
+# GOOD: Spring Cloud Vault integration
+spring:
+  cloud:
+    vault:
+      uri: https://vault.example.com
+      token: ${VAULT_TOKEN}
+```
+
+## Security Headers
+
+```java
+http
+  .headers(headers -> headers
+    .contentSecurityPolicy(csp -> csp
+      .policyDirectives("default-src 'self'"))
+    .frameOptions(HeadersConfigurer.FrameOptionsConfig::sameOrigin)
+    .xssProtection(Customizer.withDefaults())
+    .referrerPolicy(rp -> rp.policy(ReferrerPolicyHeaderWriter.ReferrerPolicy.NO_REFERRER)));
+```
+
+## CORS Configuration
+
+- Configure CORS at the security filter level, not per-controller
+- Restrict allowed origins — never use `*` in production
+
+```java
+@Bean
+public CorsConfigurationSource corsConfigurationSource() {
+  CorsConfiguration config = new CorsConfiguration();
+  config.setAllowedOrigins(List.of("https://app.example.com"));
+  config.setAllowedMethods(List.of("GET", "POST", "PUT", "DELETE"));
+  config.setAllowedHeaders(List.of("Authorization", "Content-Type"));
+  config.setAllowCredentials(true);
+  config.setMaxAge(3600L);
+
+  UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
+  source.registerCorsConfiguration("/api/**", config);
+  return source;
+}
+
+// In SecurityFilterChain:
+http.cors(cors -> cors.configurationSource(corsConfigurationSource()));
+```
+
+## Rate Limiting
+
+- Apply Bucket4j or gateway-level limits on expensive endpoints
+- Log and alert on bursts; return 429 with retry hints
+
+```java
+// Using Bucket4j for per-endpoint rate limiting
+@Component
+public class RateLimitFilter extends OncePerRequestFilter {
+  private final Map<String, Bucket> buckets = new ConcurrentHashMap<>();
+
+  private Bucket createBucket() {
+    return Bucket.builder()
+        .addLimit(Bandwidth.classic(100, Refill.intervally(100, Duration.ofMinutes(1))))
+        .build();
+  }
+
+  @Override
+  protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response,
+      FilterChain chain) throws ServletException, IOException {
+    String clientIp = request.getRemoteAddr();
+    Bucket bucket = buckets.computeIfAbsent(clientIp, k -> createBucket());
+
+    if (bucket.tryConsume(1)) {
+      chain.doFilter(request, response);
+    } else {
+      response.setStatus(HttpStatus.TOO_MANY_REQUESTS.value());
+      response.getWriter().write("{\"error\": \"Rate limit exceeded\"}");
+    }
+  }
+}
+```
+
+## Dependency Security
+
+- Run OWASP Dependency Check / Snyk in CI
+- Keep Spring Boot and Spring Security on supported versions
+- Fail builds on known CVEs
+
+## Logging and PII
+
+- Never log secrets, tokens, passwords, or full PAN data
+- Redact sensitive fields; use structured JSON logging
+
+## File Uploads
+
+- Validate size, content type, and extension
+- Store outside web root; scan if required
+
+## Checklist Before Release
+
+- [ ] Auth tokens validated and expired correctly
+- [ ] Authorization guards on every sensitive path
+- [ ] All inputs validated and sanitized
+- [ ] No string-concatenated SQL
+- [ ] CSRF posture correct for app type
+- [ ] Secrets externalized; none committed
+- [ ] Security headers configured
+- [ ] Rate limiting on APIs
+- [ ] Dependencies scanned and up to date
+- [ ] Logs free of sensitive data
+
+**Remember**: Deny by default, validate inputs, least privilege, and secure-by-configuration first.