start-vibing-stacks 2.1.1 → 2.3.0

package/stacks/frontend/react-inertia/skills/react-standards/SKILL.md

@@ -0,0 +1,267 @@
+# React 19+ Standards (with Inertia.js)
+
+## Version Requirements
+
+- **ReactJS >= 19** — MANDATORY
+- **TailwindCSS >= 4** — MANDATORY
+- **Inertia.js >= 2** — MANDATORY
+
+## Translation Pattern (via Inertia shared props)
+
+```tsx
+import __ from '@/Utils/translate';
+
+// CORRECT: Translations as CONST at the top, BEFORE hooks
+const LABELS = {
+    title: __('dashboard.title'),
+    save: __('common.save'),
+    cancel: __('common.cancel'),
+    errorRequired: __('errors.field_required'),
+    welcome: __('dashboard.welcome', { name: 'User' }),
+};
+
+export default function Dashboard() {
+    const [data, setData] = useState(null);
+
+    return <h1>{LABELS.title}</h1>;
+}
+
+// WRONG: __() inside JSX (Hook violation — usePage() is called internally)
+return <h1>{__('dashboard.title')}</h1>; // NEVER
+```
+
+**Rules:**
+- Translations in `CONST` variables before state hooks
+- New strings must be added to `lang/en/*.php` AND `lang/pt/*.php`
+- Error strings centralized in `lang/*/errors.php`
+- Use replacements for dynamic values: `__('key', { name: value })`
+
+## Debug Logging
+
+```tsx
+const ENABLE_DASHBOARD_DEBUG = false;
+
+const debugLog = (...args: unknown[]) => {
+    if (ENABLE_DASHBOARD_DEBUG) console.log('[Dashboard]', ...args);
+};
+
+export default function Dashboard() {
+    debugLog('Rendering with data:', data);
+}
+```
+
+**Rule:** Never leave raw `console.log`. Always use controlled debug pattern.
+
+## TailwindCSS Class Organization
+
+```tsx
+// CORRECT: Classes as CONST — clean JSX
+const STYLES = {
+    container: 'flex flex-col gap-4 p-6 bg-white rounded-lg shadow-sm',
+    title: 'text-2xl font-bold text-gray-900',
+    button: 'px-4 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700 transition',
+    grid: 'grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6',
+};
+
+export default function Dashboard() {
+    return (
+        <div className={STYLES.container}>
+            <h1 className={STYLES.title}>{LABELS.title}</h1>
+        </div>
+    );
+}
+
+// WRONG: Inline class soup
+<div className="flex flex-col gap-4 p-6 bg-white rounded-lg shadow-sm"> // NEVER
+```
+
+## SVG Icons
+
+```tsx
+// CORRECT: Separate files, import with ?react
+import CheckIcon from '@/Icons/CheckIcon.svg?react';
+import { CheckIcon, AlertIcon } from '@/Icons';
+
+// WRONG: Inline SVG (bloats JSX)
+<svg viewBox="0 0 24 24">...</svg> // NEVER
+```
+
+**Structure:**
+```
+resources/js/Icons/
+├── index.js           # Barrel export
+├── CheckIcon.svg
+├── AlertIcon.svg
+└── SpinnerIcon.svg
+```
+
+## Inertia.js Hooks & Navigation
+
+### Accessing Shared Props
+
+```tsx
+import { usePage } from '@inertiajs/react';
+
+export default function Header() {
+    const { auth, locale, flash } = usePage().props;
+
+    return (
+        <nav>
+            <span>{auth.user?.name}</span>
+            {flash.success && <Alert>{flash.success}</Alert>}
+        </nav>
+    );
+}
+```
+
+### Forms with useForm
+
+```tsx
+import { useForm } from '@inertiajs/react';
+
+export default function CreateOrder() {
+    const { data, setData, post, processing, errors } = useForm({
+        product_id: '',
+        quantity: 1,
+        notes: '',
+    });
+
+    const handleSubmit = (e) => {
+        e.preventDefault();
+        post(route('orders.store'));
+    };
+
+    return (
+        <form onSubmit={handleSubmit}>
+            <Input
+                value={data.product_id}
+                onChange={(e) => setData('product_id', e.target.value)}
+                error={errors.product_id}
+            />
+            <Button type="submit" loading={processing}>
+                {processing ? <LoadingSpinner /> : LABELS.save}
+            </Button>
+        </form>
+    );
+}
+```
+
+**Rules:**
+- Use `useForm` for ALL form submissions (handles CSRF, errors, loading)
+- `processing` boolean for button loading states
+- `errors` object maps to Form Request validation errors
+- Never use `fetch()` or `axios` for form submissions
+
+### Navigation
+
+```tsx
+import { Link, router } from '@inertiajs/react';
+
+// SPA links (no full page reload)
+<Link href={route('orders.index')}>Orders</Link>
+
+// Programmatic navigation
+router.visit(route('dashboard'));
+
+// Partial reload (only refresh specific props)
+router.reload({ only: ['stats', 'recentOrders'] });
+```
+
+## Loading States
+
+```tsx
+// CORRECT: Always show loading feedback
+export default function DataTable() {
+    const [loading, setLoading] = useState(true);
+
+    if (loading) {
+        return <SectionLoader />;
+    }
+
+    return <Table data={data} />;
+}
+
+// Button loading (from useForm)
+<Button onClick={handleSave} disabled={processing}>
+    {processing ? <LoadingSpinner /> : LABELS.save}
+</Button>
+```
+
+**Rule:** Every data-heavy section needs a loading state.
+
+## Modal Data Flow
+
+```tsx
+interface EditModalProps {
+    item: Item;
+    isOpen: boolean;
+    onClose: () => void;
+    onUpdated: () => void;
+}
+
+function EditModal({ item, isOpen, onClose, onUpdated }: EditModalProps) {
+    const { data, setData, put, processing } = useForm({
+        name: item.name,
+    });
+
+    const handleSave = (e) => {
+        e.preventDefault();
+        put(route('items.update', item.id), {
+            onSuccess: () => {
+                onUpdated();
+                onClose();
+            },
+        });
+    };
+}
+
+// Parent: use router.reload for refresh after modal mutation
+<EditModal
+    item={selectedItem}
+    isOpen={showModal}
+    onClose={() => setShowModal(false)}
+    onUpdated={() => router.reload({ only: ['items'] })}
+/>
+```
+
+## Third-Party Libraries (Charts)
+
+```tsx
+// CORRECT: Let React handle re-rendering
+{chartData && (
+    <ApexChart
+        key={JSON.stringify(chartData)}
+        options={chartOptions}
+        series={chartData}
+        type="area"
+    />
+)}
+
+// WRONG: Manual DOM manipulation
+const chartRef = useRef(null);
+chartRef.current.updateSeries(newData); // NEVER
+
+// Memoize expensive computations
+const processedData = useMemo(() => {
+    return heavyTransform(rawData);
+}, [rawData]);
+```
+
+**Rules:**
+- No `useRef` for updating third-party components
+- Conditional rendering: `data && <Component />`
+- `useMemo` for expensive computations
+- Loading states before rendering charts
+
+## Forbidden Patterns
+
+| Pattern | Reason | Use Instead |
+|---------|--------|-------------|
+| `fetch()` / `axios` for pages | Bypasses Inertia | `Inertia::render()` props |
+| `__()` inside JSX | Hook violation | CONST at top |
+| Inline SVGs | Bloats components | SVG files + `?react` |
+| `<a href>` for internal links | Full reload | `<Link href>` |
+| `window.location` | Full reload | `router.visit()` |
+| Raw `console.log` | Uncontrolled | Debug constant pattern |
+| Inline Tailwind soup | Unreadable | STYLES const object |
+| `axios.post()` for forms | No CSRF/errors | `useForm().post()` |

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

@@ -0,0 +1,431 @@
+# API Security — NSA-Level Hardening for Laravel + Octane
+
+**ALWAYS invoke when building APIs, auth endpoints, or handling user input.**
+
+## Security Layers
+
+```
+Internet → Cloudflare WAF → Rate Limiting → CORS → Auth Middleware
+  → Input Validation → Business Logic → Output Sanitization → Response
+
+Every layer is a wall. Assume the previous one failed.
+```
+
+## 1. Authentication (Sanctum + Octane)
+
+### Token-Based (API)
+
+```php
+// config/sanctum.php
+'expiration' => 60 * 24,     // 24h token expiry (MANDATORY)
+'token_prefix' => 'flk_',    // Prefix for easy log scanning
+
+// Issue token with abilities (least privilege)
+$token = $user->createToken('api-client', [
+    'read:leads',
+    'write:leads',
+    // NOT '*' — never wildcard abilities
+])->plainTextToken;
+
+// Middleware: check specific ability
+Route::middleware(['auth:sanctum', 'ability:read:leads'])->group(function () {
+    Route::get('/api/v1/leads', [LeadController::class, 'index']);
+});
+```
+
+### Token Rotation
+
+```php
+// Rotate on every sensitive action
+public function changePassword(Request $request): JsonResponse
+{
+    // ... change password logic
+
+    // Revoke ALL tokens (force re-login everywhere)
+    $request->user()->tokens()->delete();
+
+    // Issue fresh token
+    $newToken = $request->user()->createToken('session', ['*'])->plainTextToken;
+
+    return $this->success(['token' => $newToken]);
+}
+```
+
+### Octane Session Safety
+
+```php
+// app/Providers/AppServiceProvider.php
+use Laravel\Octane\Facades\Octane;
+
+public function boot(): void
+{
+    // MANDATORY: flush auth state between requests
+    Octane::prepare(function ($sandbox) {
+        $sandbox->forgetScopedInstances();
+        $sandbox->flushDatabaseConnections();
+    });
+}
+```
+
+## 2. Input Validation (Trust NOTHING)
+
+### FormRequest (Always)
+
+```php
+// app/Http/Requests/StoreLeadRequest.php
+class StoreLeadRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return $this->user()->tokenCan('write:leads');
+    }
+
+    public function rules(): array
+    {
+        return [
+            'name' => ['required', 'string', 'min:2', 'max:255'],
+            'email' => ['required', 'email:rfc,dns', 'max:320'],  // RFC + DNS check
+            'phone' => ['nullable', 'string', 'regex:/^\+?[1-9]\d{1,14}$/'],  // E.164
+            'domain_id' => ['required', 'uuid', 'exists:domains,id'],
+            'metadata' => ['nullable', 'json', 'max:10000'],  // Size limit on JSON
+            'tags' => ['nullable', 'array', 'max:10'],
+            'tags.*' => ['string', 'max:50', 'alpha_dash'],
+        ];
+    }
+
+    // Sanitize AFTER validation
+    public function validated($key = null, $default = null): array
+    {
+        $data = parent::validated($key, $default);
+        $data['email'] = strtolower(trim($data['email']));
+        $data['name'] = strip_tags($data['name']);
+        return $data;
+    }
+}
+```
+
+### SQL Injection Prevention
+
+```php
+// ✅ ALWAYS Eloquent or parameterized
+Lead::where('email', $request->validated('email'))->first();
+
+// ✅ Raw with bindings
+DB::select('SELECT * FROM leads WHERE email = ?', [$email]);
+
+// ❌ NEVER interpolate user input
+DB::select("SELECT * FROM leads WHERE email = '{$email}'");  // ❌ SQL INJECTION
+```
+
+### Mass Assignment Protection
+
+```php
+class Lead extends Model
+{
+    // Explicit fillable (whitelist approach)
+    protected $fillable = [
+        'name', 'email', 'phone', 'domain_id', 'metadata',
+    ];
+
+    // NEVER: protected $guarded = []; ← allows EVERYTHING
+}
+```
+
+## 3. Rate Limiting (Multi-Layer)
+
+```php
+// app/Providers/AppServiceProvider.php
+use Illuminate\Cache\RateLimiting\Limit;
+use Illuminate\Support\Facades\RateLimiter;
+
+public function boot(): void
+{
+    // Global API limit
+    RateLimiter::for('api', function ($request) {
+        return Limit::perMinute(60)->by($request->user()?->id ?: $request->ip());
+    });
+
+    // Strict limit on auth endpoints
+    RateLimiter::for('auth', function ($request) {
+        return [
+            Limit::perMinute(5)->by($request->ip()),           // 5/min per IP
+            Limit::perHour(20)->by($request->ip()),            // 20/hour per IP
+            Limit::perDay(50)->by($request->ip()),             // 50/day per IP
+        ];
+    });
+
+    // Strict limit on sensitive actions
+    RateLimiter::for('sensitive', function ($request) {
+        return Limit::perMinute(3)->by($request->user()->id);  // 3/min per user
+    });
+
+    // Webhook endpoints
+    RateLimiter::for('webhooks', function ($request) {
+        return Limit::perMinute(100)->by($request->ip());
+    });
+}
+
+// Routes
+Route::middleware('throttle:auth')->group(function () {
+    Route::post('/login', [AuthController::class, 'login']);
+    Route::post('/register', [AuthController::class, 'register']);
+    Route::post('/forgot-password', [AuthController::class, 'forgotPassword']);
+});
+
+Route::middleware('throttle:sensitive')->group(function () {
+    Route::post('/change-password', [AuthController::class, 'changePassword']);
+    Route::post('/change-email', [AuthController::class, 'changeEmail']);
+    Route::delete('/account', [AuthController::class, 'deleteAccount']);
+});
+```
+
+## 4. CORS (Restrictive)
+
+```php
+// config/cors.php
+return [
+    'paths' => ['api/*'],
+    'allowed_methods' => ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'],
+    'allowed_origins' => [
+        env('APP_URL'),                           // Only your domain
+        // NOT '*' — NEVER wildcard in production
+    ],
+    'allowed_headers' => [
+        'Content-Type', 'Authorization', 'X-Requested-With',
+        'X-Timezone', 'Accept', 'X-CSRF-TOKEN',
+    ],
+    'exposed_headers' => ['X-Request-ID', 'Retry-After'],
+    'max_age' => 86400,                           // 24h preflight cache
+    'supports_credentials' => true,
+];
+```
+
+## 5. Security Headers Middleware
+
+```php
+// app/Http/Middleware/SecurityHeaders.php
+class SecurityHeaders
+{
+    public function handle($request, Closure $next)
+    {
+        $response = $next($request);
+
+        return $response
+            ->header('X-Content-Type-Options', 'nosniff')
+            ->header('X-Frame-Options', 'DENY')
+            ->header('X-XSS-Protection', '0')  // Modern browsers use CSP instead
+            ->header('Referrer-Policy', 'strict-origin-when-cross-origin')
+            ->header('Permissions-Policy', 'camera=(), microphone=(), geolocation=()')
+            ->header('Strict-Transport-Security', 'max-age=31536000; includeSubDomains; preload')
+            ->header('X-Request-ID', $request->attributes->get('request_id', (string) Str::uuid()))
+            ->header('Content-Security-Policy', implode('; ', [
+                "default-src 'self'",
+                "script-src 'self' 'unsafe-inline' https://js.stripe.com",
+                "style-src 'self' 'unsafe-inline' https://fonts.googleapis.com",
+                "img-src 'self' data: https:",
+                "font-src 'self' https://fonts.gstatic.com",
+                "connect-src 'self' https://api.stripe.com",
+                "frame-src https://js.stripe.com",
+                "object-src 'none'",
+                "base-uri 'self'",
+            ]));
+    }
+}
+```
+
+## 6. Output Sanitization
+
+```php
+// app/Http/Resources/LeadResource.php
+class LeadResource extends JsonResource
+{
+    use FormatsDatesForApi;
+
+    public function toArray(Request $request): array
+    {
+        return [
+            'id' => $this->id,
+            'name' => e($this->name),           // HTML entity encode
+            'email' => $this->email,
+            'status' => $this->status->value,
+            'created_at' => $this->formatDateTime($this->created_at, $request),
+            // NEVER expose:
+            // 'password' → NEVER
+            // 'api_token' → NEVER
+            // 'ip_address' → only if admin
+            // 'remember_token' → NEVER
+        ];
+    }
+}
+
+// Model hidden attributes (defense in depth)
+class User extends Authenticatable
+{
+    protected $hidden = [
+        'password',
+        'remember_token',
+        'two_factor_secret',
+        'two_factor_recovery_codes',
+    ];
+}
+```
+
+## 7. Encryption at Rest
+
+```php
+// Encrypt sensitive data in database
+use Illuminate\Database\Eloquent\Casts\Attribute;
+
+class ApiCredential extends Model
+{
+    // Laravel encrypted cast (AES-256-CBC)
+    protected $casts = [
+        'api_key' => 'encrypted',
+        'api_secret' => 'encrypted',
+        'webhook_secret' => 'encrypted',
+    ];
+}
+
+// For searchable encrypted fields
+use Illuminate\Support\Facades\Crypt;
+
+class Lead extends Model
+{
+    // Store hash for lookup, encrypted value for display
+    protected static function booted(): void
+    {
+        static::creating(function ($lead) {
+            $lead->email_hash = hash('sha256', strtolower($lead->email));
+            $lead->email_encrypted = Crypt::encryptString($lead->email);
+        });
+    }
+}
+```
+
+## 8. Audit Logging
+
+```php
+// app/Traits/Auditable.php
+trait Auditable
+{
+    protected static function bootAuditable(): void
+    {
+        foreach (['created', 'updated', 'deleted'] as $event) {
+            static::$event(function ($model) use ($event) {
+                AuditLog::create([
+                    'auditable_type' => $model->getMorphClass(),
+                    'auditable_id' => $model->getKey(),
+                    'event' => $event,
+                    'old_values' => $event === 'updated' ? $model->getOriginal() : null,
+                    'new_values' => $event !== 'deleted' ? $model->getAttributes() : null,
+                    'user_id' => auth()->id(),
+                    'ip_address' => request()->ip(),
+                    'user_agent' => request()->userAgent(),
+                ]);
+            });
+        }
+    }
+}
+
+// Usage on sensitive models
+class Lead extends Model
+{
+    use HasUuids, Auditable;
+}
+```
+
+## 9. Brute Force Protection
+
+```php
+// app/Http/Controllers/Auth/LoginController.php
+public function login(LoginRequest $request): JsonResponse
+{
+    $key = 'login_attempts:' . $request->ip() . ':' . Str::lower($request->email);
+
+    // Check lockout (progressive delay)
+    $attempts = (int) Cache::get($key, 0);
+    if ($attempts >= 5) {
+        $lockoutMinutes = min(pow(2, $attempts - 5), 60);  // 1, 2, 4, 8, 16, 32, 60 min
+        $ttl = Cache::get("{$key}:lockout");
+        if ($ttl && now()->lt($ttl)) {
+            return $this->error('Too many attempts. Try again later.', 429);
+        }
+    }
+
+    if (!Auth::attempt($request->validated())) {
+        // Increment with exponential TTL
+        Cache::put($key, $attempts + 1, now()->addHours(1));
+        if ($attempts + 1 >= 5) {
+            $lockoutMinutes = min(pow(2, $attempts - 4), 60);
+            Cache::put("{$key}:lockout", now()->addMinutes($lockoutMinutes), now()->addMinutes($lockoutMinutes));
+        }
+
+        // Generic message (don't reveal if user exists)
+        return $this->error('Invalid credentials', 401);
+    }
+
+    // Reset on success
+    Cache::forget($key);
+    Cache::forget("{$key}:lockout");
+
+    $token = $request->user()->createToken('session')->plainTextToken;
+    return $this->success(['token' => $token]);
+}
+```
+
+## 10. Request ID Tracking
+
+```php
+// app/Http/Middleware/RequestId.php
+class RequestId
+{
+    public function handle($request, Closure $next)
+    {
+        $requestId = $request->header('X-Request-ID', (string) Str::uuid());
+        $request->attributes->set('request_id', $requestId);
+
+        // Add to all log entries in this request
+        Log::shareContext(['request_id' => $requestId]);
+
+        $response = $next($request);
+        $response->header('X-Request-ID', $requestId);
+
+        return $response;
+    }
+}
+```
+
+## Security Checklist — Before Deploy
+
+- [ ] All endpoints have auth middleware
+- [ ] All input validated via FormRequest
+- [ ] Rate limiting on auth + sensitive endpoints
+- [ ] CORS restricted to your domain only
+- [ ] Security headers middleware active
+- [ ] Sensitive fields `$hidden` on models
+- [ ] API keys encrypted at rest
+- [ ] Audit logging on sensitive models
+- [ ] Brute force protection on login
+- [ ] Request ID tracking in all logs
+- [ ] No `env()` in code (only `config()`)
+- [ ] No `*` in token abilities
+- [ ] No `$guarded = []` on models
+- [ ] CSP headers configured
+- [ ] HSTS enabled
+- [ ] Webhook signatures verified
+- [ ] Error responses don't expose internals
+
+## FORBIDDEN
+
+| ❌ Don't | ✅ Do |
+|---|---|
+| `$guarded = []` | Explicit `$fillable` |
+| `'allowed_origins' => ['*']` | Your domain only |
+| `createToken('x', ['*'])` | Specific abilities |
+| `"WHERE email = '$email'"` | Parameterized queries |
+| `dd($user)` in production | `Log::info()` structured |
+| Generic error messages with stack traces | Clean error + request_id for debugging |
+| Store API keys in plaintext | `'encrypted'` cast |
+| Same rate limit for all endpoints | Progressive: auth(5/min) < api(60/min) |
+| Trust `X-Forwarded-For` directly | Use trusted proxies config |
+| No token expiry | 24h max, rotate on sensitive actions |