@sun-asterisk/sunlint 1.3.48 → 1.3.49

package/skill-assets/sunlint-code-quality/rules/java/J014-hardcoded-crypto-key.md

@@ -0,0 +1,108 @@
+---
+title: Never Hardcode Cryptographic Keys or Initialization Vectors
+impact: HIGH
+impactDescription: hardcoded crypto keys or IVs give attackers permanent access to all encrypted data — compromised keys cannot be rotated without code changes
+tags: security, cryptography, java, secrets
+---
+
+## Never Hardcode Cryptographic Keys or Initialization Vectors
+
+Hardcoding cryptographic keys, passwords, secrets, or initialization vectors (IVs) directly in source code is a critical security vulnerability (OWASP A02: Cryptographic Failures). Once the code is in source control or compiled into a binary, the key is permanently exposed. Attackers who access the binary, source code, or logs can decrypt all data protected by that key.
+
+**Incorrect (hardcoded key/IV):**
+
+```java
+import javax.crypto.SecretKey;
+import javax.crypto.spec.SecretKeySpec;
+import javax.crypto.spec.IvParameterSpec;
+
+public class EncryptionService {
+    // CRITICAL VULNERABILITY: key is hardcoded in source code
+    private static final byte[] SECRET_KEY = "MySuperSecretKey".getBytes(); // 16 bytes = AES-128
+    private static final byte[] IV = "InitVector123456".getBytes();          // hardcoded IV
+
+    public byte[] encrypt(byte[] data) throws Exception {
+        SecretKey key = new SecretKeySpec(SECRET_KEY, "AES");
+        IvParameterSpec ivSpec = new IvParameterSpec(IV);
+        Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5Padding");
+        cipher.init(Cipher.ENCRYPT_MODE, key, ivSpec);
+        return cipher.doFinal(data);
+    }
+}
+
+// Also bad: hardcoded passwords for key derivation
+public class KeyDerivation {
+    private static final String PASSWORD = "hardcoded_password_123"; // exposed in binary
+    private static final byte[] SALT = "fixed_salt".getBytes();      // static salt defeats PBKDF2
+}
+```
+
+**Correct (keys from secure storage):**
+
+```java
+import javax.crypto.*;
+import javax.crypto.spec.*;
+import java.security.SecureRandom;
+
+public class EncryptionService {
+    private final SecretKey key;
+
+    // Inject key via constructor — loaded from secure storage, not hardcoded
+    public EncryptionService(SecretKey key) {
+        this.key = key;
+    }
+
+    public EncryptedData encrypt(byte[] data) throws Exception {
+        // Always generate a random IV per encryption operation
+        byte[] iv = new byte[16];
+        new SecureRandom().nextBytes(iv);  // cryptographically random
+        IvParameterSpec ivSpec = new IvParameterSpec(iv);
+
+        Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5Padding");
+        cipher.init(Cipher.ENCRYPT_MODE, key, ivSpec);
+        byte[] ciphertext = cipher.doFinal(data);
+
+        return new EncryptedData(iv, ciphertext); // store IV alongside ciphertext
+    }
+}
+
+// Key loading from environment or secrets manager
+public class KeyLoader {
+    public SecretKey loadKeyFromEnv() {
+        String base64Key = System.getenv("AES_SECRET_KEY"); // from environment
+        if (base64Key == null) {
+            throw new IllegalStateException("AES_SECRET_KEY environment variable not set");
+        }
+        byte[] keyBytes = Base64.getDecoder().decode(base64Key);
+        return new SecretKeySpec(keyBytes, "AES");
+    }
+
+    // Or use Java KeyStore (JKS/PKCS12):
+    public SecretKey loadKeyFromKeystore(String keystorePath, char[] storePassword,
+                                          String alias, char[] keyPassword) throws Exception {
+        KeyStore ks = KeyStore.getInstance("PKCS12");
+        try (InputStream fis = new FileInputStream(keystorePath)) {
+            ks.load(fis, storePassword);
+        }
+        return (SecretKey) ks.getKey(alias, keyPassword);
+    }
+}
+```
+
+**Secure key management options:**
+
+| Method | Description |
+|--------|-------------|
+| Environment variables | Simple, good for containers (`AES_SECRET_KEY`) |
+| Java KeyStore (JKS/PKCS12) | Standard Java key storage |
+| AWS Secrets Manager / KMS | Cloud-managed, auditable |
+| HashiCorp Vault | Enterprise secret management |
+| Google Cloud Secret Manager | GCP-native secrets |
+
+**Additional rules:**
+- Always use a **random IV** per encryption — never a fixed IV.
+- IVs need not be secret but must be unique per encryption.
+- Use AES-GCM instead of AES-CBC where possible (provides authentication).
+- Key length: AES-128 minimum, AES-256 recommended.
+
+**Tools:** PMD (`HardCodedCryptoKey`, `InsecureCryptoIv`), SonarQube (`S2068`, `S3329`), SpotBugs (`HardCodedKey`)

package/skill-assets/sunlint-code-quality/rules/java/J015-optional-instead-of-null.md

@@ -0,0 +1,109 @@
+---
+title: Use Optional Instead of Returning null for Absent Values
+impact: MEDIUM
+impactDescription: returning null from methods forces callers to guess whether null is possible, leading to unchecked NullPointerExceptions
+tags: null-safety, design, java, clean-code
+---
+
+## Use Optional Instead of Returning null for Absent Values
+
+`null` is the most common source of `NullPointerException` in Java. When a method may or may not return a value (as opposed to returning a collection), use `java.util.Optional<T>` to make the "absence" explicit in the API contract. `Optional` forces callers to consciously handle the absent case.
+
+This is described in *Effective Java* Item 55: *"Return Optionals Judiciously."*
+
+**Incorrect (returning null):**
+
+```java
+// Caller cannot tell from the signature whether null is possible
+public User findUserByEmail(String email) {
+    return userRepository.findByEmail(email); // may return null — not obvious
+}
+
+public String getPreferredLanguage(Long userId) {
+    UserPreferences prefs = preferencesRepo.findByUser(userId);
+    if (prefs == null) return null; // unclear API contract
+    return prefs.getLanguage();
+}
+
+// Callers must remember to null-check:
+User user = userService.findUserByEmail("a@b.com");
+user.getName(); // NPE if forgotten
+```
+
+**Correct (using Optional):**
+
+```java
+import java.util.Optional;
+
+// Method signature clearly states: "this might not exist"
+public Optional<User> findUserByEmail(String email) {
+    User user = userRepository.findByEmail(email);
+    return Optional.ofNullable(user); // wraps null into empty Optional
+}
+
+public Optional<String> getPreferredLanguage(Long userId) {
+    return Optional.ofNullable(preferencesRepo.findByUser(userId))
+        .map(UserPreferences::getLanguage);
+}
+```
+
+**Handling Optional at call sites:**
+
+```java
+// Option 1: provide a default value
+String name = userService.findUserByEmail("a@b.com")
+    .map(User::getName)
+    .orElse("Guest");
+
+// Option 2: throw a meaningful exception if absent
+User user = userService.findUserByEmail("a@b.com")
+    .orElseThrow(() -> new UserNotFoundException("User not found: " + email));
+
+// Option 3: only proceed if present
+userService.findUserByEmail("a@b.com")
+    .ifPresent(user -> sendWelcomeEmail(user));
+
+// Option 4: ifPresentOrElse (Java 9+)
+userService.findUserByEmail("a@b.com")
+    .ifPresentOrElse(
+        user -> logger.info("Found user: {}", user.getId()),
+        () -> logger.info("User not found")
+    );
+
+// Option 5: transform and fall back
+String language = getPreferredLanguage(userId)
+    .filter(lang -> supportedLanguages.contains(lang))
+    .orElse("en");
+```
+
+**When NOT to use Optional:**
+
+```java
+// 1. Do NOT use Optional for fields — use null or default values
+public class User {
+    private Optional<String> middleName; // bad: not serializable, adds overhead
+    private String middleName;           // good: use null or ""
+}
+
+// 2. Do NOT use Optional for method parameters — use overloading or @Nullable
+public void createUser(Optional<String> role) { ... } // bad
+public void createUser(String role) { ... }           // good: role can be nullable
+public void createUser() { ... }                      // good: overload for absent role
+
+// 3. Do NOT use Optional for collections — return empty collection instead
+public Optional<List<Order>> getOrders() { ... }       // bad: double-wrap
+public List<Order> getOrders() { ... }                 // good: return empty list
+
+// 4. Do NOT use Optional.get() without checking — defeats the purpose
+user.get().getName(); // same as null, throws NoSuchElementException
+```
+
+**Optional factory methods:**
+
+```java
+Optional.of(value)          // value must be non-null; throws NPE if null
+Optional.ofNullable(value)  // safe: wraps null into empty Optional
+Optional.empty()            // explicitly empty
+```
+
+**Tools:** IntelliJ Inspections (`OptionalUsedAsFieldOrParameterType`), SonarQube (`S3553`, `S2789`), PMD

package/skill-assets/sunlint-code-quality/rules/php-laravel/AGENTS.md

@@ -0,0 +1,124 @@
+# Laravel Framework — SunLint Agent Guide
+
+> Priority directives for AI agents working on Laravel projects.
+> Rule files: `.agent/skills/sunlint-code-quality/rules/`
+
+---
+
+## Critical Patterns — Apply Every Time
+
+### Validation
+- **Always** use `php artisan make:request` → `FormRequest` class, never `$request->validate()` in controller
+- In the controller use `$request->validated()` — never `$request->all()` or `$request->input()` wholesale
+- See: `LV001-form-request-validation.md`
+
+### N+1 Queries
+- **Always** check: does this controller/service access a relation in a loop or collection?
+- If yes → add `->with(['relation'])` to the query **before** the loop
+- Use `->withCount('relation')` instead of `->relation->count()` in loops  
+- See: `LV002-eager-load-no-n-plus-1.md`
+
+### Mass Assignment
+- Every new Model must define explicit `$fillable = [...]`
+- **Never**: `protected $guarded = []`
+- **Never**: `Model::create($request->all())` — use `$request->validated()`
+- See: `LV004-fillable-mass-assignment.md`
+
+### Passwords
+- `Hash::make($password)` to store, `Hash::check($plain, $hash)` to verify
+- **Never** `md5()`, `sha1()`, or raw `password_hash()` for passwords
+- See: `LV007-hash-passwords.md`
+
+### Authorization
+- **Never** `if ($user->role === 'admin')` scattered in controllers
+- Generate a Policy: `php artisan make:policy ModelPolicy --model=Model`
+- Use `$this->authorize('action', $model)` or Form Request `authorize()`
+- See: `LV005-policies-gates-authorization.md`
+
+---
+
+## Architecture Patterns
+
+### Controller responsibility
+Controllers do exactly 3 things: validate input → call service → return response.
+No business logic, no DB queries, no calculations in controllers.
+```php
+// Controller
+public function store(StoreOrderRequest $request): JsonResponse
+{
+    $order = $this->orderService->placeOrder($request->user(), $request->validated());
+    return OrderResource::make($order)->response()->setStatusCode(201);
+}
+```
+See: `LV012-service-layer.md`
+
+### API Responses
+- Always use `php artisan make:resource` → never `->toArray()`, `->toJson()` or raw `response()->json($model)`
+- Sensitive columns (`password`, `remember_token`) must be in `$hidden` on the model
+- See: `LV009-api-resources.md`
+
+### Configuration
+- `env()` appears **only** in `config/*.php` files — never in app code (breaks after `config:cache`)
+- App code always uses `config('key.sub_key')` with optional default
+- See: `LV003-config-not-env.md`
+
+### Heavy Operations (email, API calls, reports)
+- Any external call or operation > ~200ms → `Job::dispatch()->onQueue('name')`
+- Job class implements `ShouldQueue`, handles `failed()` method
+- See: `LV006-queue-heavy-tasks.md`
+
+### Large Data Sets
+- No `Model::all()` or unbounded `->get()` in commands/jobs
+- Use `->chunkById(500, fn($batch) => ...)` or `->cursor()` for iteration
+- See: `LV010-chunk-large-datasets.md`
+
+### Multi-step Writes
+- Any sequence of 2+ DB writes that must be atomic → wrap in `DB::transaction(fn() => { ... })`
+- dispatch jobs inside transactions: `Job::dispatch($model)->afterCommit()`
+- See: `LV011-db-transactions.md`
+
+### Route Model Binding
+- Route params matching a Model name auto-resolve — no manual `findOrFail()`
+- `Route::get('/posts/{post}', ...)` → controller receives `Post $post` directly
+- See: `LV008-route-model-binding.md`
+
+### Dependency Injection
+- Register services in `AppServiceProvider::register()` as singletons/bindings
+- Controllers receive via constructor — never `new Service()` inside a method
+- See: `LV014-service-container.md`
+
+---
+
+## Run Commands
+
+```bash
+php artisan make:request  StoreXxxRequest   # validation
+php artisan make:policy   XxxPolicy --model=Xxx
+php artisan make:resource XxxResource
+php artisan make:job      ProcessXxx
+php artisan make:service  XxxService        # (if using stubs)
+
+php artisan test --filter ClassName         # run specific test
+php artisan test --coverage                 # coverage report
+php artisan config:cache                    # validate no env() in app code
+php artisan route:list --path=api           # audit routes
+php artisan telescope:install               # install query/request debugger
+```
+
+---
+
+## What NOT to do (quick reference)
+
+| ❌ Wrong | ✅ Correct |
+|---|---|
+| `$request->validate([...])` in controller | `FormRequest` class |
+| `$request->all()` | `$request->validated()` |
+| `Post::all()` | `Post::with([...])->paginate(20)` |
+| `$post->comments->count()` in loop | `Post::withCount('comments')` |
+| `env('KEY')` in service | `config('prefix.key')` |
+| `$guarded = []` | `$fillable = ['col1', 'col2']` |
+| `if ($user->role === 'admin')` | `$this->authorize('action', $model)` |
+| `md5($password)` | `Hash::make($password)` |
+| `response()->json($model)` | `ModelResource::make($model)` |
+| `Mail::send()` in controller | `SendMailJob::dispatch()->onQueue(...)` |
+| `new OrderService()` in controller | Constructor DI auto-resolved by container |

package/skill-assets/sunlint-code-quality/rules/php-laravel/LV001-form-request-validation.md

@@ -0,0 +1,64 @@
+---
+title: Use Form Request Classes for Validation
+impact: HIGH
+impactDescription: keeps controllers thin, centralizes validation logic and authorization, enables reuse
+tags: validation, form-request, controller, laravel, clean-architecture
+---
+
+## Use Form Request Classes for Validation
+
+Putting `$request->validate()` directly in controller actions mixes concerns, prevents reuse, and inflates controllers. Form Requests encapsulate validation + authorization as a dedicated class.
+
+**Wrong:**
+
+```php
+// Controller bloated with validation logic
+public function store(Request $request)
+{
+    $request->validate([
+        'name'  => 'required|string|max:255',
+        'email' => 'required|email|unique:users',
+        'age'   => 'required|integer|min:18',
+    ]);
+
+    User::create($request->all());
+}
+```
+
+**Correct:**
+
+```bash
+# Generate a Form Request
+php artisan make:request StoreUserRequest
+```
+
+```php
+// app/Http/Requests/StoreUserRequest.php
+class StoreUserRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return $this->user()->can('create', User::class);
+    }
+
+    public function rules(): array
+    {
+        return [
+            'name'  => 'required|string|max:255',
+            'email' => 'required|email|unique:users',
+            'age'   => 'required|integer|min:18',
+        ];
+    }
+}
+
+// Controller is now thin
+public function store(StoreUserRequest $request)
+{
+    User::create($request->validated()); // never $request->all()
+}
+```
+
+**Key points:**
+- Always use `$request->validated()` not `$request->all()` — only returns fields that passed validation
+- Authorization logic belongs in `authorize()`, not the controller
+- One Form Request per action (StoreUserRequest, UpdateUserRequest are separate)

package/skill-assets/sunlint-code-quality/rules/php-laravel/LV002-eager-load-no-n-plus-1.md

@@ -0,0 +1,58 @@
+---
+title: Eager Load Relationships to Prevent N+1 Queries
+impact: CRITICAL
+impactDescription: prevents N+1 query explosion that causes severe performance degradation in production
+tags: n+1, eager-loading, eloquent, performance, with, laravel
+---
+
+## Eager Load Relationships to Prevent N+1 Queries
+
+Accessing a relationship inside a loop without eager loading fires one query per iteration. With 1000 posts, that is 1001 queries. Always eager load with `with()` when you know you'll access the relationship.
+
+**Wrong:**
+
+```php
+// Executes 1 + N queries (one per post)
+$posts = Post::all();
+
+foreach ($posts as $post) {
+    echo $post->author->name;   // <- SELECT * FROM users WHERE id = ? (×N)
+    echo $post->category->name; // <- SELECT * FROM categories WHERE id = ? (×N)
+}
+```
+
+**Correct:**
+
+```php
+// Executes exactly 3 queries total
+$posts = Post::with(['author', 'category'])->get();
+
+foreach ($posts as $post) {
+    echo $post->author->name;
+    echo $post->category->name;
+}
+
+// Nested relationships
+$posts = Post::with(['author.profile', 'tags'])->get();
+
+// Selective columns to reduce memory
+$posts = Post::with(['author:id,name,avatar'])->get();
+
+// Conditional eager loading
+$posts = Post::with(['comments' => function ($q) {
+    $q->where('approved', true)->latest()->limit(5);
+}])->get();
+```
+
+**Detection signal:**
+- Any `->relationship` access inside a `foreach`, `map`, `each`, or `Collection` method without preceding `with()`
+- Use Laravel Telescope or Debugbar in development to detect N+1 — queries > 10 for a single request is a red flag
+
+**Also applies to:**
+```php
+// WRONG: counting without withCount
+$posts->each(fn($p) => $p->comments->count()); // N queries
+
+// CORRECT: withCount
+Post::withCount('comments')->get(); // 1 query
+```

package/skill-assets/sunlint-code-quality/rules/php-laravel/LV003-config-not-env.md

@@ -0,0 +1,54 @@
+---
+title: Use config() Helper, Never env() Outside Config Files
+impact: HIGH
+impactDescription: config caching (php artisan config:cache) breaks env() calls at runtime — app silently returns null
+tags: config, env, caching, laravel, environment
+---
+
+## Use config() Instead of env() Outside Config Files
+
+`env()` only works reliably before config is cached. Once you run `php artisan config:cache` (required in production), `env()` returns `null` everywhere except in `config/*.php` files.
+
+**Wrong:**
+
+```php
+// Service class — breaks after config:cache
+class PaymentService
+{
+    public function charge()
+    {
+        $key = env('STRIPE_SECRET'); // NULL in production!
+    }
+}
+
+// Controller
+public function show()
+{
+    $debug = env('APP_DEBUG'); // NULL after config:cache
+}
+```
+
+**Correct:**
+
+```php
+// 1. Define in config/services.php
+return [
+    'stripe' => [
+        'secret' => env('STRIPE_SECRET'),  // env() ONLY here
+    ],
+];
+
+// 2. Use config() everywhere else
+class PaymentService
+{
+    public function charge()
+    {
+        $key = config('services.stripe.secret'); // always works
+    }
+}
+
+// 3. With default fallback
+$debug = config('app.debug', false);
+```
+
+**Rule:** `env()` appears only in `config/` directory. Everywhere else → `config()`.

package/skill-assets/sunlint-code-quality/rules/php-laravel/LV004-fillable-mass-assignment.md

@@ -0,0 +1,51 @@
+---
+title: Define $fillable — Never Use $guarded = []
+impact: CRITICAL
+impactDescription: disabling mass assignment protection allows attackers to write arbitrary model fields via crafted HTTP requests
+tags: mass-assignment, fillable, guarded, security, eloquent, laravel
+---
+
+## Define $fillable — Never Use $guarded = []
+
+Mass assignment attacks occur when a user passes unexpected fields (e.g. `is_admin=1`) that get written to the database. `$guarded = []` disables all protection.
+
+**Wrong:**
+
+```php
+class User extends Model
+{
+    protected $guarded = []; // All fields writable — DANGEROUS
+
+    // Or: no $fillable defined at all (same effect with $guarded=[])
+}
+
+// Attacker sends: POST /users { "name": "Bob", "is_admin": 1 }
+User::create($request->all()); // is_admin gets written!
+```
+
+**Correct:**
+
+```php
+class User extends Model
+{
+    // Explicit allowlist
+    protected $fillable = [
+        'name',
+        'email',
+        'password',
+    ];
+
+    // Fields like is_admin, email_verified_at are NOT here
+    // They are set explicitly:
+}
+
+// Controller
+User::create($request->validated()); // only validated+fillable fields written
+
+// When you must set a guarded field, use direct assignment:
+$user = new User($request->validated());
+$user->is_admin = false; // explicit, intentional
+$user->save();
+```
+
+**Also:** use `$request->validated()` not `$request->all()` so only schema-declared fields reach the model.

package/skill-assets/sunlint-code-quality/rules/php-laravel/LV005-policies-gates-authorization.md

@@ -0,0 +1,71 @@
+---
+title: Use Policies and Gates for Authorization
+impact: HIGH
+impactDescription: centralizes authorization logic, prevents scattered role checks, enables testing and auditing
+tags: authorization, policy, gate, roles, security, laravel
+---
+
+## Use Policies and Gates for Authorization
+
+Manual role checks scattered across controllers (`if ($user->role === 'admin')`) are fragile, hard to audit, and often inconsistently applied.
+
+**Wrong:**
+
+```php
+// Controller — authorization logic throughout
+public function update(Request $request, Post $post)
+{
+    if ($request->user()->id !== $post->user_id) {
+        abort(403);
+    }
+    if ($request->user()->role !== 'editor' && $request->user()->role !== 'admin') {
+        abort(403); // duplicated in show, destroy, etc.
+    }
+    $post->update($request->validated());
+}
+```
+
+**Correct:**
+
+```bash
+php artisan make:policy PostPolicy --model=Post
+```
+
+```php
+// app/Policies/PostPolicy.php
+class PostPolicy
+{
+    public function update(User $user, Post $post): bool
+    {
+        return $user->id === $post->user_id || $user->isEditor();
+    }
+
+    public function delete(User $user, Post $post): bool
+    {
+        return $user->id === $post->user_id || $user->isAdmin();
+    }
+}
+
+// Controller — thin and readable
+public function update(UpdatePostRequest $request, Post $post)
+{
+    $this->authorize('update', $post); // throws 403 if denied
+
+    $post->update($request->validated());
+}
+
+// Or in Form Request
+public function authorize(): bool
+{
+    return $this->user()->can('update', $this->route('post'));
+}
+```
+
+**Gates for non-model actions:**
+```php
+// AppServiceProvider
+Gate::define('access-reports', fn(User $u) => $u->hasRole('analyst'));
+
+// Anywhere
+if (Gate::denies('access-reports')) abort(403);
+```