@ngxtm/devkit 3.4.0 → 3.4.1

package/rules/java/spring-data-jpa/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: Spring Data JPA
+description: Entity mapping, repositories, transactions, queries, auditing, and fetching strategies.
+metadata:
+  labels: [java, spring-boot, jpa, database, hibernate]
+  triggers:
+    files: ['**/*Entity.java', '**/*Repository.java', '**/*Jpa*.java']
+    keywords: [Entity, Id, Repository, JpaRepository, Transactional, Query, ManyToOne, OneToMany, ManyToMany, JoinColumn]
+---
+
+# Spring Data JPA Standards
+
+## Entity Definition
+
+```java
+@Entity
+@Table(name = "users")
+@Getter @Setter
+@NoArgsConstructor
+public class User {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+
+    @Column(nullable = false, length = 100)
+    private String name;
+
+    @Column(nullable = false, unique = true)
+    private String email;
+
+    @Column(nullable = false)
+    private String passwordHash;
+
+    @Enumerated(EnumType.STRING)
+    @Column(nullable = false)
+    private UserStatus status = UserStatus.ACTIVE;
+
+    @OneToMany(mappedBy = "user", cascade = CascadeType.ALL, orphanRemoval = true)
+    private List<Order> orders = new ArrayList<>();
+
+    @CreatedDate
+    @Column(nullable = false, updatable = false)
+    private LocalDateTime createdAt;
+
+    @LastModifiedDate
+    private LocalDateTime updatedAt;
+
+    // Business methods
+    public void addOrder(Order order) {
+        orders.add(order);
+        order.setUser(this);
+    }
+
+    public void removeOrder(Order order) {
+        orders.remove(order);
+        order.setUser(null);
+    }
+}
+```
+
+## Repository
+
+```java
+public interface UserRepository extends JpaRepository<User, Long> {
+
+    // Derived query methods
+    Optional<User> findByEmail(String email);
+
+    List<User> findByStatus(UserStatus status);
+
+    boolean existsByEmail(String email);
+
+    // JPQL query
+    @Query("SELECT u FROM User u WHERE u.status = :status AND u.createdAt > :since")
+    List<User> findActiveUsersSince(
+        @Param("status") UserStatus status,
+        @Param("since") LocalDateTime since
+    );
+
+    // Native query
+    @Query(value = "SELECT * FROM users WHERE email LIKE %:domain", nativeQuery = true)
+    List<User> findByEmailDomain(@Param("domain") String domain);
+
+    // Modifying query
+    @Modifying
+    @Query("UPDATE User u SET u.status = :status WHERE u.id = :id")
+    int updateStatus(@Param("id") Long id, @Param("status") UserStatus status);
+
+    // Projection
+    @Query("SELECT u.id as id, u.name as name, u.email as email FROM User u")
+    List<UserSummary> findAllSummaries();
+
+    // Pagination
+    Page<User> findByStatus(UserStatus status, Pageable pageable);
+
+    // Specification (dynamic queries)
+    List<User> findAll(Specification<User> spec);
+}
+
+// Projection interface
+public interface UserSummary {
+    Long getId();
+    String getName();
+    String getEmail();
+}
+```
+
+## Transactions
+
+```java
+@Service
+@RequiredArgsConstructor
+public class OrderService {
+
+    private final OrderRepository orderRepository;
+    private final InventoryService inventoryService;
+
+    @Transactional
+    public Order createOrder(CreateOrderRequest request) {
+        Order order = new Order();
+        // ... setup order
+
+        for (OrderItem item : request.items()) {
+            inventoryService.decreaseStock(item.productId(), item.quantity());
+        }
+
+        return orderRepository.save(order);
+    }
+
+    @Transactional(readOnly = true)
+    public Order findById(Long id) {
+        return orderRepository.findById(id)
+            .orElseThrow(() -> new OrderNotFoundException(id));
+    }
+
+    @Transactional(propagation = Propagation.REQUIRES_NEW)
+    public void processPayment(Long orderId) {
+        // Runs in new transaction
+    }
+
+    @Transactional(
+        isolation = Isolation.SERIALIZABLE,
+        timeout = 30,
+        rollbackFor = PaymentException.class,
+        noRollbackFor = NotificationException.class
+    )
+    public void processWithOptions(Long orderId) {
+        // Custom transaction settings
+    }
+}
+```
+
+## Relationships
+
+```java
+// Many-to-One (owning side)
+@Entity
+public class Order {
+    @ManyToOne(fetch = FetchType.LAZY)
+    @JoinColumn(name = "user_id", nullable = false)
+    private User user;
+}
+
+// One-to-Many (inverse side)
+@Entity
+public class User {
+    @OneToMany(mappedBy = "user", cascade = CascadeType.ALL, orphanRemoval = true)
+    private List<Order> orders = new ArrayList<>();
+}
+
+// Many-to-Many
+@Entity
+public class Student {
+    @ManyToMany
+    @JoinTable(
+        name = "student_courses",
+        joinColumns = @JoinColumn(name = "student_id"),
+        inverseJoinColumns = @JoinColumn(name = "course_id")
+    )
+    private Set<Course> courses = new HashSet<>();
+}
+
+// One-to-One
+@Entity
+public class User {
+    @OneToOne(mappedBy = "user", cascade = CascadeType.ALL, orphanRemoval = true)
+    private UserProfile profile;
+}
+```
+
+## Auditing
+
+```java
+@Configuration
+@EnableJpaAuditing
+public class JpaConfig {}
+
+@MappedSuperclass
+@EntityListeners(AuditingEntityListener.class)
+public abstract class BaseEntity {
+
+    @CreatedDate
+    @Column(nullable = false, updatable = false)
+    private LocalDateTime createdAt;
+
+    @LastModifiedDate
+    private LocalDateTime updatedAt;
+
+    @CreatedBy
+    @Column(updatable = false)
+    private String createdBy;
+
+    @LastModifiedBy
+    private String updatedBy;
+}
+
+@Component
+public class AuditorAwareImpl implements AuditorAware<String> {
+    @Override
+    public Optional<String> getCurrentAuditor() {
+        return Optional.ofNullable(SecurityContextHolder.getContext().getAuthentication())
+            .map(Authentication::getName);
+    }
+}
+```
+
+## Best Practices
+
+1. **Use @ManyToOne with LAZY** - avoid N+1 queries
+2. **Fetch eagerly with JOIN FETCH** when needed
+3. **Use @Transactional(readOnly = true)** for read operations
+4. **Avoid @ManyToMany** - use explicit join table entity
+5. **Use projections** for read-only queries
+6. **Paginate large result sets**
+
+## References
+
+- [Entity Mapping](references/entity-mapping.md) - Inheritance, embeddables, converters
+- [Repository Patterns](references/repository-patterns.md) - Specifications, custom repos
+- [Fetching Strategies](references/fetching-strategies.md) - N+1, EntityGraph, batch

package/rules/java/spring-data-jpa/references/REFERENCE.md

@@ -0,0 +1,16 @@
+# Spring Data JPA References
+
+## References
+
+- [**Entity Mapping**](entity-mapping.md) - Inheritance strategies, embeddables, custom converters
+- [**Repository Patterns**](repository-patterns.md) - Specifications, custom implementations
+- [**Fetching Strategies**](fetching-strategies.md) - N+1 problem, EntityGraph, batch fetching
+
+## Quick Checks
+
+- [ ] Use LAZY fetch for @ManyToOne and @OneToMany
+- [ ] JOIN FETCH for eager loading in queries
+- [ ] @Transactional(readOnly = true) for reads
+- [ ] Projections for read-only partial data
+- [ ] Paginate large result sets
+- [ ] Avoid open-in-view (disabled by default in Spring Boot 3)

package/rules/java/spring-security/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: Spring Security
+description: Authentication, authorization, JWT, OAuth2, CSRF, CORS, and security filter chain.
+metadata:
+  labels: [java, spring-boot, security, authentication, authorization]
+  triggers:
+    files: ['**/*Security*.java', '**/*Config*.java', '**/*Auth*.java']
+    keywords: [SecurityFilterChain, HttpSecurity, Authentication, Authorization, csrf, jwt, OAuth2, UserDetails, PasswordEncoder]
+---
+
+# Spring Security Standards
+
+## Security Configuration (Spring Boot 3+)
+
+```java
+@Configuration
+@EnableWebSecurity
+@EnableMethodSecurity
+public class SecurityConfig {
+
+    @Bean
+    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
+        return http
+            .csrf(csrf -> csrf.disable())  // Disable for stateless API
+            .cors(cors -> cors.configurationSource(corsConfigurationSource()))
+            .sessionManagement(session ->
+                session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
+            .authorizeHttpRequests(auth -> auth
+                .requestMatchers("/api/auth/**").permitAll()
+                .requestMatchers("/api/public/**").permitAll()
+                .requestMatchers("/actuator/health").permitAll()
+                .requestMatchers("/api/admin/**").hasRole("ADMIN")
+                .anyRequest().authenticated()
+            )
+            .addFilterBefore(jwtAuthFilter, UsernamePasswordAuthenticationFilter.class)
+            .exceptionHandling(ex -> ex
+                .authenticationEntryPoint(authEntryPoint)
+                .accessDeniedHandler(accessDeniedHandler)
+            )
+            .build();
+    }
+
+    @Bean
+    public PasswordEncoder passwordEncoder() {
+        return new BCryptPasswordEncoder();
+    }
+
+    @Bean
+    public AuthenticationManager authenticationManager(
+            AuthenticationConfiguration config) throws Exception {
+        return config.getAuthenticationManager();
+    }
+}
+```
+
+## JWT Authentication Filter
+
+```java
+@Component
+@RequiredArgsConstructor
+public class JwtAuthenticationFilter extends OncePerRequestFilter {
+
+    private final JwtService jwtService;
+    private final UserDetailsService userDetailsService;
+
+    @Override
+    protected void doFilterInternal(
+            HttpServletRequest request,
+            HttpServletResponse response,
+            FilterChain filterChain) throws ServletException, IOException {
+
+        String authHeader = request.getHeader("Authorization");
+
+        if (authHeader == null || !authHeader.startsWith("Bearer ")) {
+            filterChain.doFilter(request, response);
+            return;
+        }
+
+        String jwt = authHeader.substring(7);
+        String username = jwtService.extractUsername(jwt);
+
+        if (username != null && SecurityContextHolder.getContext().getAuthentication() == null) {
+            UserDetails userDetails = userDetailsService.loadUserByUsername(username);
+
+            if (jwtService.isTokenValid(jwt, userDetails)) {
+                UsernamePasswordAuthenticationToken authToken =
+                    new UsernamePasswordAuthenticationToken(
+                        userDetails,
+                        null,
+                        userDetails.getAuthorities()
+                    );
+                authToken.setDetails(new WebAuthenticationDetailsSource().buildDetails(request));
+                SecurityContextHolder.getContext().setAuthentication(authToken);
+            }
+        }
+
+        filterChain.doFilter(request, response);
+    }
+}
+```
+
+## Method Security
+
+```java
+@Service
+public class UserService {
+
+    @PreAuthorize("hasRole('ADMIN')")
+    public void deleteUser(Long id) { }
+
+    @PreAuthorize("hasRole('ADMIN') or #id == authentication.principal.id")
+    public User updateUser(Long id, UpdateRequest request) { }
+
+    @PostAuthorize("returnObject.owner == authentication.name")
+    public Resource getResource(Long id) { }
+
+    @PreAuthorize("@securityService.canAccess(#id)")
+    public void accessResource(Long id) { }
+}
+
+@Component("securityService")
+public class SecurityService {
+    public boolean canAccess(Long resourceId) {
+        // Custom authorization logic
+        return true;
+    }
+}
+```
+
+## CORS Configuration
+
+```java
+@Bean
+public CorsConfigurationSource corsConfigurationSource() {
+    CorsConfiguration config = new CorsConfiguration();
+    config.setAllowedOrigins(List.of("http://localhost:3000", "https://example.com"));
+    config.setAllowedMethods(List.of("GET", "POST", "PUT", "DELETE", "OPTIONS"));
+    config.setAllowedHeaders(List.of("*"));
+    config.setAllowCredentials(true);
+    config.setMaxAge(3600L);
+
+    UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
+    source.registerCorsConfiguration("/api/**", config);
+    return source;
+}
+```
+
+## Best Practices
+
+1. **Use BCrypt** for password hashing (strength 10-12)
+2. **Stateless sessions** for REST APIs with JWT
+3. **Method security** for fine-grained authorization
+4. **Validate JWT** on every request
+5. **Short token expiry** with refresh token pattern
+6. **Never log sensitive data** (passwords, tokens)
+
+## References
+
+- [JWT Auth Flow](references/jwt-auth-flow.md) - Token service, refresh tokens
+- [OAuth2 Resource Server](references/oauth2-resource-server.md) - JWT decoder, claims
+- [Security Filter Chain](references/security-filter-chain.md) - Filter order, custom filters

package/rules/java/spring-security/references/REFERENCE.md

@@ -0,0 +1,16 @@
+# Spring Security References
+
+## References
+
+- [**JWT Auth Flow**](jwt-auth-flow.md) - Token generation, validation, refresh pattern
+- [**OAuth2 Resource Server**](oauth2-resource-server.md) - JWT decoder, extracting claims
+- [**Security Filter Chain**](security-filter-chain.md) - Filter ordering, custom filters
+
+## Quick Checks
+
+- [ ] BCrypt password encoder (cost 10-12)
+- [ ] Stateless session for REST APIs
+- [ ] JWT validation on every request
+- [ ] CORS configured for allowed origins only
+- [ ] CSRF disabled only for stateless APIs
+- [ ] Method security for fine-grained authorization

package/rules/java/spring-security/references/jwt-auth-flow.md

@@ -0,0 +1,213 @@
+# JWT Authentication Flow
+
+## JWT Service
+
+```java
+@Service
+@RequiredArgsConstructor
+public class JwtService {
+
+    @Value("${jwt.secret}")
+    private String secretKey;
+
+    @Value("${jwt.access-token-expiration}")
+    private Duration accessTokenExpiration;
+
+    @Value("${jwt.refresh-token-expiration}")
+    private Duration refreshTokenExpiration;
+
+    public String generateAccessToken(UserDetails userDetails) {
+        return generateToken(userDetails, accessTokenExpiration, Map.of());
+    }
+
+    public String generateRefreshToken(UserDetails userDetails) {
+        return generateToken(userDetails, refreshTokenExpiration, Map.of("type", "refresh"));
+    }
+
+    private String generateToken(
+            UserDetails userDetails,
+            Duration expiration,
+            Map<String, Object> extraClaims) {
+
+        Instant now = Instant.now();
+        return Jwts.builder()
+            .claims(extraClaims)
+            .subject(userDetails.getUsername())
+            .issuedAt(Date.from(now))
+            .expiration(Date.from(now.plus(expiration)))
+            .signWith(getSigningKey())
+            .compact();
+    }
+
+    public String extractUsername(String token) {
+        return extractClaim(token, Claims::getSubject);
+    }
+
+    public <T> T extractClaim(String token, Function<Claims, T> claimsResolver) {
+        Claims claims = extractAllClaims(token);
+        return claimsResolver.apply(claims);
+    }
+
+    private Claims extractAllClaims(String token) {
+        return Jwts.parser()
+            .verifyWith(getSigningKey())
+            .build()
+            .parseSignedClaims(token)
+            .getPayload();
+    }
+
+    public boolean isTokenValid(String token, UserDetails userDetails) {
+        String username = extractUsername(token);
+        return username.equals(userDetails.getUsername()) && !isTokenExpired(token);
+    }
+
+    private boolean isTokenExpired(String token) {
+        return extractClaim(token, Claims::getExpiration).before(new Date());
+    }
+
+    private SecretKey getSigningKey() {
+        byte[] keyBytes = Decoders.BASE64.decode(secretKey);
+        return Keys.hmacShaKeyFor(keyBytes);
+    }
+}
+```
+
+## Authentication Controller
+
+```java
+@RestController
+@RequestMapping("/api/auth")
+@RequiredArgsConstructor
+public class AuthController {
+
+    private final AuthenticationManager authManager;
+    private final JwtService jwtService;
+    private final UserDetailsService userDetailsService;
+    private final RefreshTokenService refreshTokenService;
+
+    @PostMapping("/login")
+    public AuthResponse login(@Valid @RequestBody LoginRequest request) {
+        authManager.authenticate(
+            new UsernamePasswordAuthenticationToken(
+                request.email(),
+                request.password()
+            )
+        );
+
+        UserDetails userDetails = userDetailsService.loadUserByUsername(request.email());
+        String accessToken = jwtService.generateAccessToken(userDetails);
+        String refreshToken = jwtService.generateRefreshToken(userDetails);
+
+        refreshTokenService.save(request.email(), refreshToken);
+
+        return new AuthResponse(accessToken, refreshToken);
+    }
+
+    @PostMapping("/refresh")
+    public AuthResponse refresh(@Valid @RequestBody RefreshRequest request) {
+        String refreshToken = request.refreshToken();
+
+        if (!refreshTokenService.isValid(refreshToken)) {
+            throw new InvalidTokenException("Invalid refresh token");
+        }
+
+        String username = jwtService.extractUsername(refreshToken);
+        UserDetails userDetails = userDetailsService.loadUserByUsername(username);
+
+        String newAccessToken = jwtService.generateAccessToken(userDetails);
+        String newRefreshToken = jwtService.generateRefreshToken(userDetails);
+
+        refreshTokenService.revoke(refreshToken);
+        refreshTokenService.save(username, newRefreshToken);
+
+        return new AuthResponse(newAccessToken, newRefreshToken);
+    }
+
+    @PostMapping("/logout")
+    public void logout(@RequestHeader("Authorization") String authHeader) {
+        if (authHeader != null && authHeader.startsWith("Bearer ")) {
+            String token = authHeader.substring(7);
+            String username = jwtService.extractUsername(token);
+            refreshTokenService.revokeAllForUser(username);
+        }
+    }
+}
+
+public record LoginRequest(
+    @NotBlank @Email String email,
+    @NotBlank String password
+) {}
+
+public record RefreshRequest(
+    @NotBlank String refreshToken
+) {}
+
+public record AuthResponse(
+    String accessToken,
+    String refreshToken
+) {}
+```
+
+## Refresh Token Storage
+
+```java
+@Service
+@RequiredArgsConstructor
+public class RefreshTokenService {
+
+    private final RefreshTokenRepository repository;
+    private final JwtService jwtService;
+
+    public void save(String username, String token) {
+        RefreshToken refreshToken = new RefreshToken();
+        refreshToken.setUsername(username);
+        refreshToken.setToken(token);
+        refreshToken.setExpiresAt(
+            jwtService.extractClaim(token, Claims::getExpiration).toInstant()
+        );
+        repository.save(refreshToken);
+    }
+
+    public boolean isValid(String token) {
+        return repository.findByToken(token)
+            .map(rt -> rt.getExpiresAt().isAfter(Instant.now()))
+            .orElse(false);
+    }
+
+    public void revoke(String token) {
+        repository.deleteByToken(token);
+    }
+
+    public void revokeAllForUser(String username) {
+        repository.deleteAllByUsername(username);
+    }
+}
+
+@Entity
+@Table(name = "refresh_tokens")
+public class RefreshToken {
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+
+    @Column(nullable = false)
+    private String username;
+
+    @Column(nullable = false, unique = true)
+    private String token;
+
+    @Column(nullable = false)
+    private Instant expiresAt;
+
+    // getters, setters
+}
+```
+
+## Configuration
+
+```yaml
+jwt:
+  secret: ${JWT_SECRET}  # Base64 encoded, min 256 bits
+  access-token-expiration: 15m
+  refresh-token-expiration: 7d
+```