start-vibing-stacks 2.2.0 → 2.3.0

package/stacks/php/skills/security-scan-php/SKILL.md

@@ -1,80 +1,198 @@
-# PHP Security Scan
+# Laravel Security Scan
 
-## OWASP Top 10 for PHP
+## OWASP Top 10 for Laravel
 
 ### A01 - Broken Access Control
 
 ```php
-// ❌ NEVER trust user input for authorization
-$userId = $_GET['user_id'];
+// WRONG: Trust user input for authorization
+$userId = $request->input('user_id');
 $user = User::find($userId);
 
-// ✅ Use authenticated session
-$user = Auth::user();
+// CORRECT: Use authenticated session
+$user = $request->user();
+
+// CORRECT: Scope queries by authenticated user
+$query = Resource::query();
+if (!$request->user()->isAdmin()) {
+    $query->where('user_id', $request->user()->id);
+}
 ```
 
+**Rules:**
+- NEVER return unscoped queries — always filter by authenticated user
+- Use Policies for authorization logic
+- Use Form Requests with `authorize()` method
+- Use Route Model Binding with scoping
+
 ### A02 - Cryptographic Failures
 
 ```php
-// ❌ NEVER
+// WRONG
 md5($password);
 sha1($password);
 
-// ✅ ALWAYS
-password_hash($password, PASSWORD_BCRYPT, ['cost' => 12]);
-password_verify($input, $hash);
+// CORRECT (Laravel handles this via Hash facade)
+Hash::make($password);
+Hash::check($input, $hashedPassword);
+
+// For API tokens: use Laravel Sanctum
+// Table: users_access_tokens (UUIDs + Soft Deletes)
+// All token actions logged via Loggable trait
 ```
 
 ### A03 - Injection
 
 ```php
-// ❌ SQL Injection
-$db->query("SELECT * FROM users WHERE id = {$_GET['id']}");
+// WRONG: SQL Injection via DB::raw
+$users = DB::select("SELECT * FROM users WHERE id = {$id}");
+DB::raw("WHERE name = '{$name}'");
 
-// ✅ Prepared statements (PDO)
-$stmt = $db->prepare("SELECT * FROM users WHERE id = :id");
-$stmt->execute([':id' => $id]);
+// CORRECT: Eloquent (preferred)
+$user = User::findOrFail($id);
 
-// ✅ Prepared statements (MySQLi)
-$stmt = $db->prepare("SELECT * FROM users WHERE id = ?");
-$stmt->bind_param('i', $id);
-$stmt->execute();
+// CORRECT: Query Builder with bindings
+$users = DB::table('users')->where('name', $name)->get();
+
+// CORRECT: Raw with parameter binding (last resort)
+$results = DB::select('SELECT * FROM users WHERE id = ?', [$id]);
 ```
 
 ### A07 - XSS Prevention
 
 ```php
-// ❌ Raw output
-echo $userInput;
+// WRONG: Unescaped output in Blade
+{!! $userInput !!}
 
-// ✅ Always escape
-echo htmlspecialchars($userInput, ENT_QUOTES, 'UTF-8');
+// CORRECT: Auto-escaped (Blade default)
+{{ $userInput }}
 
-// ✅ In templates (Blade)
-{{ $userInput }}  // Auto-escaped
-{!! $trustedHtml !!}  // Only for trusted content
+// Only use {!! !!} for TRUSTED, pre-sanitized HTML
+{!! $trustedHtmlFromCMS !!}
 ```
 
-## Security Checklist
+### A08 - Insecure Deserialization
+
+```php
+// WRONG: Unserialize user data
+$data = unserialize($request->input('data'));
+
+// CORRECT: Use JSON with Model casts
+protected $casts = [
+    'metadata' => 'array',
+    'settings' => 'array',
+];
+
+// CORRECT: Defensive JSON handling
+$data = is_string($model->data) 
+    ? json_decode($model->data, true) 
+    : $model->data;
+```
+
+## Laravel-Specific Security
+
+### Mass Assignment Protection
+
+```php
+// WRONG: No protection
+$user = User::create($request->all());
+
+// CORRECT: Define $fillable
+class User extends Model {
+    protected $fillable = ['name', 'email'];
+}
+
+// CORRECT: Use Form Request validated data
+$user = User::create($request->validated());
+```
+
+### Environment Variables
+
+```php
+// WRONG: env() outside config files (null when cached)
+$apiKey = env('API_KEY');
 
-- [ ] All SQL uses prepared statements
-- [ ] All output is escaped (htmlspecialchars)
-- [ ] CSRF tokens on all forms
-- [ ] Passwords use password_hash/verify
-- [ ] File uploads validated (type, size, extension)
-- [ ] Sessions use httpOnly + secure cookies
-- [ ] Input validated before processing
-- [ ] No `eval()`, `exec()` with user input
-- [ ] No `extract()` on user data
-- [ ] Headers: X-Content-Type-Options, X-Frame-Options, CSP
+// CORRECT: Use config files
+// config/services.php
+'stripe' => ['key' => env('STRIPE_KEY')],
+
+// In code:
+$apiKey = config('services.stripe.key');
+```
+
+### CSRF & Authentication
+
+```php
+// Blade forms — CSRF automatic
+<form method="POST">
+    @csrf
+    ...
+</form>
+
+// API routes — use Sanctum middleware
+Route::middleware('auth:sanctum')->group(function () {
+    Route::apiResource('users', UserController::class);
+});
+```
+
+### File Upload Validation
+
+```php
+public function rules(): array
+{
+    return [
+        'avatar' => [
+            'required',
+            'image',
+            'mimes:jpg,jpeg,png,webp',
+            'max:2048', // 2MB
+            'dimensions:max_width=2000,max_height=2000',
+        ],
+    ];
+}
+```
+
+## Octane Security Considerations
+
+```php
+// WRONG: Static state leaks user data between requests
+class AuthService {
+    private static ?User $currentUser = null; // LEAKS!
+}
+
+// WRONG: Superglobals are stale in Octane
+$token = $_SERVER['HTTP_AUTHORIZATION'];
+
+// CORRECT: Use Request object
+$token = $request->bearerToken();
+$user = $request->user();
+```
+
+## Security Checklist
 
-## Sensitive Data Patterns (FORBIDDEN)
+- [ ] All queries use Eloquent or Query Builder (no raw SQL with user input)
+- [ ] All Blade output uses `{{ }}` (auto-escaped)
+- [ ] CSRF protection on all forms (`@csrf`)
+- [ ] Passwords use `Hash::make()` / `Hash::check()`
+- [ ] File uploads validated (type, size, dimensions)
+- [ ] API routes protected with Sanctum middleware
+- [ ] Models define `$fillable` (no `$guarded = []`)
+- [ ] Queries scoped by authenticated user (unless admin)
+- [ ] No `env()` calls outside config files
+- [ ] No static state in services (Octane-safe)
+- [ ] No superglobals (`$_GET`, `$_POST`, `$_SESSION`)
+- [ ] Sensitive headers set (X-Content-Type-Options, X-Frame-Options, CSP)
+- [ ] Rate limiting on authentication endpoints
+
+## Sensitive Patterns (FORBIDDEN)
 
 | Pattern | Risk |
 |---------|------|
-| `$_GET` used directly in SQL | SQL Injection |
-| `echo $_POST[...]` | XSS |
+| `DB::raw()` with user input | SQL Injection |
+| `{!! $userInput !!}` | XSS |
 | `md5()` / `sha1()` for passwords | Weak hashing |
-| `eval($userInput)` | RCE |
-| `include $_GET['page']` | LFI/RFI |
-| `serialize()` user data | Object injection |
+| Dynamic code execution | RCE |
+| `unserialize()` on user data | Object injection |
+| `$request->all()` without `$fillable` | Mass assignment |
+| `env()` in runtime code | Null after config cache |
+| Static user state in services | Data leaks in Octane |

package/stacks/php/stack.json

@@ -27,13 +27,20 @@
       "name": "Laravel 12 + Octane (RoadRunner) + Inertia.js",
       "icon": "🚀",
       "detectFiles": ["artisan", "rr.yaml"],
-      "default": true
+      "default": true,
+      "skills": [
+        "laravel-patterns",
+        "laravel-octane"
+      ]
     },
     {
       "id": "laravel",
       "name": "Laravel 12 (standard)",
       "icon": "🏗️",
-      "detectFiles": ["artisan", "bootstrap/app.php"]
+      "detectFiles": ["artisan", "bootstrap/app.php"],
+      "skills": [
+        "laravel-patterns"
+      ]
     }
   ],
   "databases": [
@@ -46,12 +53,20 @@
       "id": "react-inertia",
       "name": "ReactJS 19 + Inertia.js + TailwindCSS 4",
       "icon": "⚛️",
-      "default": true
+      "default": true,
+      "frameworks": ["laravel", "laravel-octane"]
     },
     {
       "id": "blade",
       "name": "Blade + TailwindCSS 4",
-      "icon": "🖼️"
+      "icon": "🖼️",
+      "frameworks": ["laravel", "laravel-octane"]
+    },
+    {
+      "id": "livewire",
+      "name": "Livewire + Alpine.js",
+      "icon": "⚡",
+      "frameworks": ["laravel", "laravel-octane"]
     },
     {
       "id": "none",
@@ -68,8 +83,6 @@
     "phpstan-analysis",
     "composer-workflow",
     "security-scan-php",
-    "laravel-patterns",
-    "laravel-octane",
     "api-design"
   ],
   "requirements": [

package/templates/CLAUDE-php.md

@@ -16,6 +16,8 @@
 |-----------|------------|
 | Language | PHP >= 8.3 |
 | Framework | {{FRAMEWORK}} |
+| Server | Octane + RoadRunner |
+| Frontend | ReactJS 19+ / Inertia.js / TailwindCSS 4+ |
 | Database | {{DATABASE}} |
 | Package Manager | Composer |
 | Static Analysis | PHPStan (level 6) |
@@ -26,41 +28,104 @@
 
 ```
 project/
-├── src/              # Application source (PSR-4: App\)
-├── public/           # Web root (index.php)
-├── config/           # Configuration files
+├── app/
+│   ├── Console/         # Artisan commands
+│   ├── Exceptions/      # Exception handlers
+│   ├── Http/
+│   │   ├── Controllers/ # Thin controllers (Inertia::render + Services)
+│   │   ├── Middleware/  # HTTP middleware (HandleInertiaRequests)
+│   │   └── Requests/   # Form request validation
+│   ├── Models/          # Eloquent models (UUIDs, $fillable)
+│   ├── Providers/       # Service providers
+│   ├── Services/        # Business logic (single responsibility)
+│   │   └── Helpers/     # Extracted logic for complex services
+│   ├── Support/         # Helper classes (InertiaShare)
+│   ├── Traits/          # Shared traits (Loggable, FormatsDatesForApi)
+│   └── Jobs/            # Queue jobs (idempotent, chunked)
+├── bootstrap/           # Framework bootstrap
+├── config/              # Configuration (immutable at runtime)
+│   └── translations_inertia.php  # Per-page translation mapping
+├── database/
+│   ├── factories/       # Model factories
+│   ├── migrations/      # Incremental migrations ONLY
+│   └── seeders/         # Database seeders
+├── lang/
+│   ├── en/              # English translations
+│   └── pt/              # Portuguese translations
+├── public/              # Web root (index.php)
+├── resources/
+│   ├── views/           # Blade root template (app.blade.php)
+│   ├── css/             # Stylesheets (TailwindCSS)
+│   └── js/
+│       ├── Pages/       # React page components (mapped by Inertia)
+│       ├── Components/  # Reusable React components
+│       ├── Layouts/     # Page layouts (Authenticated, Guest)
+│       ├── Icons/       # SVG icons (import with ?react)
+│       └── Utils/
+│           └── translate.js  # __() translation helper
+├── routes/
+│   ├── api.php          # API routes (RESTful + action endpoints)
+│   └── web.php          # Web routes (Inertia pages)
+├── storage/             # Logs, cache, uploads
 ├── tests/
-│   ├── Unit/         # PHPUnit unit tests
-│   └── Feature/      # Feature/integration tests
-├── storage/          # Logs, cache, uploads
-├── .claude/          # AI agent configuration
-├── composer.json     # Dependencies
-├── phpstan.neon      # Static analysis config
-└── CLAUDE.md         # This file
+│   ├── Unit/            # PHPUnit unit tests
+│   └── Feature/         # Feature/integration tests
+├── .claude/             # AI agent configuration
+├── artisan              # CLI entry point
+├── rr.yaml              # RoadRunner config (Octane)
+├── composer.json        # Dependencies
+├── phpstan.neon         # Static analysis config
+└── CLAUDE.md            # This file
 ```
 
 ## Critical Rules
 
-- **PHP >= 8.3** — use modern features (readonly, enums, typed constants)
+- **PHP >= 8.3** — readonly, enums, typed constants, match expressions
 - **`declare(strict_types=1)`** in EVERY PHP file
-- **PSR-4 autoloading** — no manual includes
-- **Prepared statements** — NEVER concatenate SQL
-- **Type everything** — properties, params, returns
-- **htmlspecialchars()** — all user output
-- **password_hash/verify** — NEVER md5/sha1
+- **Octane-safe code** — no static state, no globals, no `die()`/`exit()`
+- **Dependency Injection** — use DI over `app()` or `resolve()`
+- **Thin controllers** — delegate business logic to Service classes
+- **Form Requests** — validate input in dedicated request classes
+- **Type everything** — properties, params, returns (no `mixed` without justification)
+- **UUIDs** — all new models use `HasUuids` trait as primary key
+- **Mass assignment** — always define `$fillable` on models
+- **Auditing** — critical models use `Loggable` trait
+- **Eloquent only** — no raw SQL unless strictly justified with parameter binding
+- **Config immutable** — never use `config()` to SET values at runtime
+- **Request object** — use `$request->input()`, never `$_GET`/`$_POST`/`$_SESSION`
 
 ## FORBIDDEN
 
+### Backend
+
+| Action | Reason |
+|--------|--------|
+| Dynamic code execution functions | Remote code execution risk |
+| `DB::raw()` with user input | SQL injection risk |
+| `{!! $userInput !!}` | XSS — use `{{ }}` instead |
+| Mass assignment without `$fillable` | Uncontrolled field injection |
+| Business logic in controllers | Move to Service classes |
+| `env()` outside config files | Returns null when config is cached |
+| `static` properties on services | Memory leaks in Octane workers |
+| Global variables / superglobals | Stale state in Octane |
+| `die()` / `exit()` | Kills the Octane worker process |
+| `config(['key' => 'val'])` at runtime | Affects all concurrent requests |
+| `migrate:fresh` / `db:wipe` / `db:reset` | Destroys production data |
+| `app()` / `resolve()` in constructors | Use constructor DI instead |
+| `Inertia::render()` after POST/PUT/DELETE | Use `redirect()->route()` instead |
+
+### Frontend (React)
+
 | Action | Reason |
 |--------|--------|
-| `eval()` | Remote code execution risk |
-| `mysql_*` functions | Deprecated, use PDO |
-| `extract($_POST)` | Variable injection |
-| `include $_GET[...]` | Local file inclusion |
-| SQL without prepared statements | SQL injection |
-| `echo $userInput` without escape | XSS |
-| `md5($password)` | Weak hashing |
-| PHP < 8.3 syntax | Version requirement |
+| `__()` inside JSX / render | Hook violation — define as CONST before hooks |
+| `fetch()` / `axios` for page data | Bypasses Inertia — use props from controller |
+| `<a href>` for internal links | Full page reload — use `<Link>` |
+| `window.location` for navigation | Full reload — use `router.visit()` |
+| Inline SVGs in JSX | Bloats components — use SVG files with `?react` |
+| Raw `console.log` | Uncontrolled — use debug constant pattern |
+| Inline Tailwind class soup | Unreadable — use STYLES const object |
+| `axios.post()` for forms | No CSRF/errors — use `useForm().post()` |
 
 ## Quality Gates
 
@@ -68,21 +133,35 @@ project/
 vendor/bin/phpstan analyse --level=6   # Static analysis
 vendor/bin/phpunit                      # Tests
 vendor/bin/php-cs-fixer fix --dry-run   # Code style
+php artisan test                        # Laravel test runner
 ```
 
-## HTTP Requests
+## Database
 
-All database queries MUST use prepared statements:
+Use Eloquent ORM and Query Builder. Raw queries only when strictly necessary with parameter binding:
 
 ```php
-$stmt = $pdo->prepare("SELECT * FROM users WHERE id = :id");
-$stmt->execute([':id' => $userId]);
+// Eloquent (preferred)
+$user = User::findOrFail($id);
+
+// Query Builder
+$users = DB::table('users')->where('active', true)->get();
+
+// Raw query (last resort — always bind parameters)
+$results = DB::select('SELECT * FROM users WHERE id = ?', [$id]);
 ```
 
+## Migration Safety
+
+- **ALWAYS** use incremental migrations (`make:migration`)
+- **NEVER** execute `migrate:fresh`, `migrate:refresh`, `db:wipe`, `db:reset`
+- If a migration fails, fix the file or create a new one
+- Assume all environments contain critical data
+
 ## Workflow
 
 1. Create feature branch
-2. Implement with types, strict mode
+2. Implement with types, strict mode, Octane-safe patterns
 3. Run PHPStan + PHPUnit
 4. Update domains & CLAUDE.md
 5. Commit → merge to main