@sun-asterisk/sunlint 1.3.39 → 1.3.41

package/skill-assets/sunlint-code-quality/rules/php/C033-separate-data-access.md

@@ -0,0 +1,79 @@
+---
+title: Separate Processing And Data Access
+impact: HIGH
+impactDescription: enables testable business logic and cleaner architecture
+tags: separation, repository, service, architecture, quality, php
+---
+
+## Separate Processing And Data Access
+
+Mixing business logic with database queries (SQL or ORM calls) creates tight coupling. This makes unit testing difficult because it forces a dependency on a real database and violates the Single Responsibility Principle.
+
+**Incorrect (mixed concerns in Service):**
+
+```php
+class OrderService {
+    public function calculateDiscount($userId) {
+        // Business logic mixed with database queries
+        $user = DB::table('users')->where('id', $userId)->first();
+        $orderCount = DB::table('orders')->where('user_id', $userId)->count();
+        
+        $discount = 0;
+        if ($orderCount > 10) $discount += 5;
+        if ($user->is_premium) $discount += 10;
+        
+        return $discount;
+    }
+}
+```
+
+**Correct (separated Service and Repository layers):**
+
+```php
+/**
+ * Repository - Handles Data Access only
+ */
+class UserRepository {
+    public function findById($id): ?User {
+        return User::find($id);
+    }
+}
+
+class OrderRepository {
+    public function getCountByUserId($userId): int {
+        return Order::where('user_id', $userId)->count();
+    }
+}
+
+/**
+ * Service - Handles Business Logic only
+ */
+class DiscountService {
+    public function __construct(
+        private UserRepository $userRepo,
+        private OrderRepository $orderRepo
+    ) {}
+
+    public function calculateDiscount(int $userId): int {
+        $user = $this->userRepo->findById($userId);
+        $orderCount = $this->orderRepo->getCountByUserId($userId);
+        
+        return $this->compute(user, $orderCount);
+    }
+
+    private function compute(?User $user, int $count): int {
+        $discount = 0;
+        if ($count > 10) $discount += 5;
+        if ($user?->is_premium) $discount += 10;
+        return $discount;
+    }
+}
+```
+
+**Why separate them?**
+- **Mockability**: You can test the `DiscountService` by mocking the repositories without touching a real database.
+- **Maintainability**: If the database schema changes, you only update the Repository, not the business logic.
+- **Reusability**: Different services can use the same repository methods.
+- **Clarity**: High-level business rules are not obscured by low-level data access details.
+
+**Tools:** Architectural review, PHPUnit (Mocking), Laravel Repository Pattern

package/skill-assets/sunlint-code-quality/rules/php/C035-error-context-logging.md

@@ -0,0 +1,54 @@
+---
+title: Log All Relevant Context On Errors
+impact: HIGH
+impactDescription: enables rapid debugging and incident resolution
+tags: error-handling, logging, context, debugging, quality, php
+---
+
+## Log All Relevant Context On Errors
+
+When an error occurs, simply logging the message "An error occurred" is insufficient. Effective debugging requires structured logs that include the error cause and the state of the application at that moment.
+
+**Incorrect (minimal context):**
+
+```php
+Log::error('Error occurred');
+Log::error($e->getMessage()); // Missing stack trace and context
+```
+
+**Correct (structured logging with Monolog/Laravel Context):**
+
+```php
+try {
+    $this->paymentService->process($order);
+} catch (\Throwable $e) {
+    Log::error('Order processing failed', [
+        // The Exception itself (Monolog handles the stack trace)
+        'exception' => $e,
+        
+        // Business Context
+        'order_id' => $order->id,
+        'user_id' => auth()->id(),
+        'amount' => $order->amount,
+        
+        // Request Metadata
+        'url' => request()->fullUrl(),
+        'method' => request()->method(),
+        'ip' => request()->ip(),
+        
+        // Performance/Timing
+        'duration_ms' => round((microtime(true) - $startTime) * 1000, 2),
+    ]);
+    
+    throw $e; // Re-throw if necessary
+}
+```
+
+**Essential Context to Include:**
+1. **The Exception**: Pass the entire exception object to the logger so it can extract the message, file, line, and full stack trace.
+2. **Entity Identifiers**: IDs of the users, orders, or products involved.
+3. **Correlation IDs**: Use unique request IDs (e.g., from `X-Request-ID` header) to trace a single request across multiple logs.
+4. **Input State**: A summary of the input that lead to the error (excluding sensitive data like passwords).
+5. **Environment**: App environment (`production`, `staging`) and server name.
+
+**Tools:** Monolog, Sentry, Laravel Logging, New Relic, ELK Stack

package/skill-assets/sunlint-code-quality/rules/php/C041-no-hardcoded-secrets.md

@@ -0,0 +1,59 @@
+---
+title: No Hardcoded Secrets In Repo
+impact: HIGH
+impactDescription: prevents credential exposure and security breaches
+tags: secrets, credentials, security, git, quality, php
+---
+
+## No Hardcoded Secrets In Repo
+
+Hardcoding secrets (API keys, database passwords, private tokens) directly in the source code exposes them to anyone with repository access. Once committed, these secrets remain in the Git history even if deleted later.
+
+**Incorrect (secrets in code):**
+
+```php
+// Hardcoded API key
+$stripeSecret = 'sk_live_51P...';
+
+// Hardcoded database credentials
+$conn = mysqli_connect("localhost", "root", "password123", "my_db");
+
+// Using plain text secrets in config files committed to VCS
+return [
+    'aws_key' => 'AKIA...',
+    'aws_secret' => 'base64_encoded_secret...'
+];
+```
+
+**Correct (environment variables or secrets manager):**
+
+```php
+// Using environment variables (via .env file not in VCS)
+$stripeSecret = getenv('STRIPE_SECRET_KEY');
+
+// In Laravel (using config which pulls from .env)
+$stripeSecret = config('services.stripe.secret');
+
+// Validation at startup or in Service Providers
+if (empty($stripeSecret)) {
+    throw new \RuntimeException('STRIPE_SECRET_KEY is required but not set.');
+}
+```
+
+**.gitignore configuration:**
+Ensure sensitive files are never committed:
+```gitignore
+# .gitignore
+.env
+.env.production
+auth.json
+*.key
+*.pem
+```
+
+**Prevention Strategy:**
+1. Use `.env.example` to list required keys without values.
+2. Use a Secrets Manager (AWS, HashiCorp Vault) for production environments.
+3. Rotate secrets immediately if they are accidentally committed.
+
+**Tools:** Gitleaks, TruffleHog, SonarQube, pre-commit hooks

package/skill-assets/sunlint-code-quality/rules/php/C042-boolean-naming.md

@@ -0,0 +1,52 @@
+---
+title: Boolean Names Is/Has/Should
+impact: HIGH
+impactDescription: makes conditions instantly readable
+tags: naming, booleans, readability, quality, php
+---
+
+## Boolean Names Is/Has/Should
+
+Boolean variables and methods should use prefixes like `is`, `has`, `should`, `can`, or `will`. This makes conditions and logic flows instantly readable and distinguishes booleans from other data types.
+
+**Incorrect (unclear boolean names):**
+
+```php
+$active = ($user->status === 'active');
+$admin = checkAdminRole($user);
+$items = (count($cart) > 0);
+$refresh = needsRefresh();
+
+if ($active) { ... } // Unclear if $active is an object, string, or boolean
+```
+
+**Correct (boolean prefixes):**
+
+```php
+$isActive = ($user->status === 'active');
+$isAdmin = checkAdminRole($user);
+$hasItems = (count($cart) > 0);
+$shouldRefresh = needsRefresh();
+$canEdit = hasPermission($user, 'edit');
+
+if ($isActive) { ... } // Instantly readable context
+```
+
+**Common Boolean prefixes:**
+
+| Prefix | Use Case | Example |
+|--------|----------|---------|
+| `is` | State or identity | `$isEnabled`, `$isActive`, `$isOwner` |
+| `has` | Possession or existence | `$hasPermission`, `$hasErrors`, `$hasAttachment` |
+| `should` | Boolean logic for decisions | `$shouldRetry`, `$shouldRedirect`, `$shouldSave` |
+| `can` | Permissions or capabilities | `$canDelete`, `$canViewAdmin`, `$canUpload` |
+| `will` | Future state or intent | `$willExpire`, `$willAutoRenew` |
+
+**Best Practice for Methods:**
+Always prefer naming boolean-returning methods with these prefixes as well:
+```php
+public function isActive(): bool { ... }
+public function hasPermission(string $perm): bool { ... }
+```
+
+**Tools:** PHPStan (check-naming-conventions), PR review

package/skill-assets/sunlint-code-quality/rules/php/C052-controller-parsing.md

@@ -0,0 +1,66 @@
+---
+title: Separate Parsing From Controllers
+impact: HIGH
+impactDescription: keeps controllers thin and focused on HTTP orchestration
+tags: controller, parsing, transformation, patterns, quality, php
+---
+
+## Separate Parsing From Controllers
+
+Controllers should be "thin" and focus only on orchestrating HTTP concerns: receiving requests, calling services, and returning responses. Complex data transformation or parsing logic should be extracted into dedicated classes like Resources, Transformers, or Mappers.
+
+**Incorrect (transformation logic in Controller):**
+
+```php
+class UserController extends Controller {
+    public function show($id) {
+        $user = User::findOrFail($id);
+        
+        // Complex transformation in controller
+        return response()->json([
+            'id' => $user->id,
+            'full_name' => $user->first_name . ' ' . $user->last_name,
+            'email' => strtolower($user->email),
+            'member_since' => $user->created_at->format('Y-m-d'),
+            'can_delete' => $user->id !== auth()->id()
+        ]);
+    }
+}
+```
+
+**Correct (using a Resource or Transformer):**
+
+```php
+/**
+ * Using Laravel API Resources (Recommended)
+ */
+class UserResource extends JsonResource {
+    public function toArray($request) {
+        return [
+            'id' => $this->id,
+            'full_name' => $this->first_name . ' ' . $this->last_name,
+            'email' => strtolower($this->email),
+            'member_since' => $this->created_at->format('Y-m-d'),
+            'can_delete' => $this->id !== auth()->id()
+        ];
+    }
+}
+
+/**
+ * Clean Controller
+ */
+class UserController extends Controller {
+    public function show($id) {
+        $user = User::findOrFail($id);
+        return new UserResource($user);
+    }
+}
+```
+
+**Benefits:**
+- **Reusability**: Use the same transformation logic in different controllers or for nested relationships.
+- **Maintainability**: Changing the API response format only requires editing one resource class.
+- **Testability**: You can unit test the Resource/Transformer class independently of the HTTP request.
+- **Separation of Concerns**: Controllers handle "How to respond", Resources handle "What the response looks like".
+
+**Tools:** Laravel API Resources, league/fractal, Spatie Data Transfer Objects, PR review

package/skill-assets/sunlint-code-quality/rules/php/C060-superclass-logic.md

@@ -0,0 +1,54 @@
+---
+title: Do Not Ignore Superclass Logic
+impact: HIGH
+impactDescription: ensures proper inheritance behavior and prevents breaking base logic
+tags: inheritance, override, superclass, oop, quality, php
+---
+
+## Do Not Ignore Superclass Logic
+
+When overriding methods in a subclass, ensure that you are not accidentally bypassing critical logic defined in the base class. Unless you intentionally want to replace the entire behavior, you should generally call the parent implementation.
+
+**Incorrect (ignoring superclass logic):**
+
+```php
+class BaseService {
+    public function save($entity) {
+        $this->validate($entity);
+        $this->beforeSave($entity);
+        $this->repository->persist($entity);
+        $this->afterSave($entity);
+    }
+}
+
+class UserService extends BaseService {
+    public function save($user) {
+        // Completely bypasses validation and hooks!
+        $this->repository->persist($user);
+    }
+}
+```
+
+**Correct (calling parent implementation):**
+
+```php
+class UserService extends BaseService {
+    public function save($user) {
+        // Add subclass-specific logic
+        $user->updated_at = now();
+
+        // Call superclass logic to ensure hooks and validation run
+        parent::save($user);
+
+        // Add more specific logic
+        $this->notifyAdmins($user);
+    }
+}
+```
+
+**When is it acceptable to skip `parent::method()`?**
+- When the base implementation is explicitly designed to be replaced.
+- When the base implementation is an empty placeholder or default behavior that does not apply.
+- **Action**: Always document the reason why the parent logic is being intentionally bypassed.
+
+**Tools:** PHPStan (check for missing parent calls), Psalm, PR review

package/skill-assets/sunlint-code-quality/rules/php/C067-no-hardcoded-config.md

@@ -0,0 +1,55 @@
+---
+title: Do Not Hardcode Configuration
+impact: HIGH
+impactDescription: enables environment-specific deployments without code changes
+tags: configuration, environment, deployment, quality, php
+---
+
+## Do Not Hardcode Configuration
+
+Configuration values that vary between environments (Staging, Production, Local) should never be hardcoded in the source code. Hardcoding these values requires code changes and deployments for simple configuration updates and prevents the creation of portable builds.
+
+**Incorrect (hardcoded config):**
+
+```php
+// Hardcoded API URLs and limits
+$apiUrl = 'https://api.production.example.com';
+$timeout = 30;
+$maxUploadSize = 10485760; // 10MB
+```
+
+**Correct (externalized config):**
+
+```php
+/**
+ * Use Environment Variables (.env)
+ */
+
+// In plain PHP
+$apiUrl = getenv('API_URL') ?: 'http://localhost:8000';
+$timeout = (int)(getenv('API_TIMEOUT') ?: 30);
+
+// In Laravel (Recommended: use config files that pull from env)
+// config/services.php
+return [
+    'external_api' => [
+        'url' => env('EXTERNAL_API_URL', 'https://api.staging.example.com'),
+        'timeout' => env('EXTERNAL_API_TIMEOUT', 30),
+    ]
+];
+
+// Usage in Service
+$url = config('services.external_api.url');
+```
+
+**Why externalize configuration?**
+- **Portability**: The same code can run in Dev, Staging, and Production by changing only the `.env` file or environment variables.
+- **Security**: Sensitive configuration (like API keys) is kept out of the codebase (see rule **C041**).
+- **Flexibility**: Change values (like timeouts or feature flags) without re-deploying or re-building the application code.
+
+**Best Practices:**
+1. Provide sensible defaults for local development.
+2. Validate required configuration at application startup.
+3. Use a single source of truth for configuration (e.g., Laravel's `config/` directory).
+
+**Tools:** PHP Dotenv (`vlucas/phpdotenv`), Laravel/Symfony Config components, PR review

package/skill-assets/sunlint-code-quality/rules/php/S003-open-redirect.md

@@ -0,0 +1,60 @@
+---
+title: URL Redirects Must Be In Allow List
+impact: LOW
+impactDescription: prevents open redirect vulnerabilities
+tags: redirect, url, allow-list, validation, security, php
+---
+
+## URL Redirects Must Be In Allow List
+
+Open redirect vulnerabilities allow attackers to redirect users to malicious sites, often used in phishing attacks. This occurs when an application takes a URL as input and redirects the user to that URL without proper validation.
+
+**Incorrect (unvalidated redirect URL):**
+
+```php
+// Open redirect vulnerability
+$url = $_GET['url'];
+header("Location: " . $url); // Attacker: ?url=https://malicious-site.com
+exit;
+
+// Partial validation (can be bypassed)
+if (strpos($_GET['url'], 'example.com') !== false) {
+    header("Location: " . $_GET['url']); // Bypass: https://attacker.com?example.com
+    exit;
+}
+```
+
+**Correct (allow list validation):**
+
+```php
+// 1. Using an allow list of hosts
+$url = $_GET['url'] ?? '/';
+$parsed = parse_url($url);
+$allowedHosts = ['example.com', 'sun-asterisk.vn'];
+
+if (isset($parsed['host'])) {
+    if (!in_array($parsed['host'], $allowedHosts)) {
+        header("Location: /error?msg=Invalid+Redirect");
+        exit;
+    }
+}
+
+// 2. Ensuring relative redirect only
+if (strpos($url, '/') === 0 && strpos($url, '//') !== 0) {
+    // This is a relative path starting with / but not // (which is an absolute URL)
+    header("Location: " . $url);
+    exit;
+}
+
+// 3. Using Laravel's safe redirect
+return redirect()->away($url); // If host is trusted, or:
+return redirect()->intended('/dashboard'); // Safer
+```
+
+**Protection strategies:**
+1. Maintain an allow list of trusted domains.
+2. Force redirects to be relative URLs (starting with a single `/`).
+3. Always validate the host part using `parse_url()`.
+4. Use framework-specific security helpers (e.g., Laravel's `redirect()`).
+
+**Tools:** SonarQube (S5144), Semgrep, PHPStan, Manual Review

package/skill-assets/sunlint-code-quality/rules/php/S004-no-log-credentials.md

@@ -0,0 +1,67 @@
+---
+title: Do Not Log Credentials Or Tokens
+impact: MEDIUM
+impactDescription: prevents credential exposure in logs
+tags: logging, credentials, tokens, secrets, security, php
+---
+
+## Do Not Log Credentials Or Tokens
+
+Logs are frequently stored in plaintext and accessible by many developers or automated tools. Including sensitive credentials (passwords, API tokens, session IDs) in logs can lead to account takeovers if the logs are ever compromised or accidentally exposed.
+
+**Incorrect (logging sensitive data):**
+
+```php
+// Logging user credentials
+Log::info('Login attempt', [
+    'username' => $request->username,
+    'password' => $request->password // NEVER!
+]);
+
+// Logging all request headers
+Log::debug('Request headers', $request->headers->all());
+// Authorization header contains Bearer tokens!
+
+// Logging full request body
+Log::info('Incoming form data', $request->all());
+// May contain password, credit_card, or secret_key
+```
+
+**Correct (sanitized logging):**
+
+```php
+// 1. Omit sensitive fields explicitly
+Log::info('Login attempt', [
+    'username' => $request->username,
+    // password excluded
+]);
+
+// 2. Redact sensitive headers
+$headers = $request->headers->all();
+if (isset($headers['authorization'])) {
+    $headers['authorization'] = '[REDACTED]';
+}
+Log::debug('Request headers', $headers);
+
+// 3. Use an allowlist or a masking helper
+function sanitizeForLog(array $data): array {
+    $sensitive = ['password', 'token', 'secret', 'credit_card', 'api_key'];
+    foreach ($sensitive as $field) {
+        if (isset($data[$field])) {
+            $data[$field] = '[REDACTED]';
+        }
+    }
+    return $data;
+}
+
+Log::info('Request data', sanitizeForLog($request->all()));
+```
+
+**Never log:**
+- Passwords (plaintext or hashes)
+- API keys, JWT tokens, OAuth tokens
+- Credit card numbers, CVVs
+- Session IDs (`PHPSESSID`)
+- Personal Identifiable Information (PII) like SSNs where not required
+
+**Tools:** Monolog (custom formatters), PHPStan, SonarQube, Log analysis tools

package/skill-assets/sunlint-code-quality/rules/php/S005-server-authorization.md

@@ -0,0 +1,57 @@
+---
+title: Enforce Authorization At Trusted Service Layer
+impact: CRITICAL
+impactDescription: prevents client-side authorization bypass and unauthorized access
+tags: authorization, server-side, middleware, access-control, security, php
+---
+
+## Enforce Authorization At Trusted Service Layer
+
+Client-side authorization (e.g., hiding a button in JavaScript) is a UI enhancement only and can be easily bypassed by an attacker using the browser console or intercepting network requests. All access control checks must be enforced on the server-side, using trusted data from the authenticated session.
+
+**Incorrect (client-side or trusting client-provided state):**
+
+```php
+// 1. Trusting a hidden field or POST data for permissions
+function deleteUser($userId) {
+    if ($_POST['is_admin'] == '1') { // VULNERABLE: Client can send is_admin=1
+        DB::table('users')->where('id', $userId)->delete();
+    }
+}
+
+// 2. Trusting a role stored in a cookie (that is not a secure session)
+if ($_COOKIE['role'] === 'admin') {
+    // ...
+}
+```
+
+**Correct (server-side authorization):**
+
+```php
+// 1. Using Middleware (Laravel example)
+Route::delete('/users/{id}', [UserController::class, 'destroy'])
+    ->middleware('can:delete-users'); // Server-side check via Policy/Gate
+
+// 2. Explicit checking in Controller against session user
+public function destroy($id) {
+    $user = Auth::user(); // Trusted data from session
+    
+    // Using a Policy (Recommended)
+    if ($user->cannot('delete', User::find($id))) {
+        abort(403, 'Unauthorized action.');
+    }
+    
+    // ... delete logic
+}
+
+// 3. Using Symfony Voters
+// $this->denyAccessUnlessGranted('POST_EDIT', $post);
+```
+
+**Never trust:**
+- Client-side checks (JavaScript logic).
+- Hidden form fields or request body parameters for defining user "roles" or "powers".
+- URL parameters for access control (e.g. `?is_admin=true`).
+- Browser storage (LocalStorage/SessionStorage) for authorization state.
+
+**Tools:** Laravel Middleware/Gates/Policies, Symfony Voters, PHPUnit (testing auth logic), SonarQube

package/skill-assets/sunlint-code-quality/rules/php/S006-default-credentials.md

@@ -0,0 +1,61 @@
+---
+title: Do Not Use Default Credentials
+impact: CRITICAL
+impactDescription: prevents trivial compromise via known credentials
+tags: credentials, default, passwords, configuration, security, php
+---
+
+## Do Not Use Default Credentials
+
+Default credentials (e.g., `admin/admin`, `root/root`) are publicly known and are the first thing attackers or automated bots try when probing a system. Using them in any environment (even staging) exposes the system to trivial compromise.
+
+**Incorrect (default or hardcoded credentials):**
+
+```php
+// Application config with defaults
+return [
+    'db' => [
+        'username' => 'root',
+        'password' => 'root', // Default!
+    ],
+    'admin' => [
+        'user' => 'admin',
+        'password' => 'admin' // Default!
+    ]
+];
+
+// Docker Compose Example with defaults
+// POSTGRES_PASSWORD: password
+```
+
+**Correct (externalized and unique credentials):**
+
+```php
+// Use environment variables or Secrets Manager
+return [
+    'db' => [
+        'username' => getenv('DB_USERNAME'),
+        'password' => getenv('DB_PASSWORD'),
+    ],
+];
+
+// Validation during application boot (e.g. in Laravel AppServiceProvider)
+if (config('app.env') === 'production') {
+    $pass = config('database.connections.mysql.password');
+    $defaults = ['admin', 'password', 'root', '123456'];
+    
+    if (in_array(strtolower($pass), $defaults)) {
+        throw new \RuntimeException('Production is using default/weak credentials. Deployment blocked.');
+    }
+}
+```
+
+**Never use common defaults:**
+- `admin / admin`
+- `root / root`
+- `guest / guest`
+- `postgres / postgres`
+- `admin / 123456`
+- Any empty passwords in networked environments.
+
+**Tools:** Gitleaks, TruffleHog, OWASP ZAP (to check for default admin pages), SonarQube