feat(docs): update architecture and development guidelines; enhance form components with built-in authorization system and improve routing documentation

2025-08-25 09:31:40 +02:00
parent 990331cd74
commit 0831905443
14 changed files with 789 additions and 58 deletions
--- a/.cursor/rules/security-patterns.mdc
+++ b/.cursor/rules/security-patterns.mdc
@@ -1,7 +1,7 @@
 ---
-description: 
-globs: 
-alwaysApply: false
+description: Security architecture, authentication, authorization patterns, and enhanced form component security
+globs: app/Policies/*.php, app/View/Components/Forms/*.php, app/Http/Middleware/*.php, resources/views/**/*.blade.php
+alwaysApply: true
 ---
 # Coolify Security Architecture & Patterns

@@ -63,6 +63,170 @@ class User extends Authenticatable

 ## Authorization & Access Control

+### Enhanced Form Component Authorization System
+
+Coolify now features a **centralized authorization system** built into all form components (`Input`, `Select`, `Textarea`, `Checkbox`, `Button`) that automatically handles permission-based UI control.
+
+#### Component Authorization Parameters
+```php
+// Available on all form components
+public ?string $canGate = null;        // Gate name (e.g., 'update', 'view', 'delete')
+public mixed $canResource = null;      // Resource to check against (model instance)
+public bool $autoDisable = true;       // Auto-disable if no permission (default: true)
+```
+
+#### Smart Authorization Logic
+```php
+// Automatic authorization handling in component constructor
+if ($this->canGate && $this->canResource && $this->autoDisable) {
+    $hasPermission = Gate::allows($this->canGate, $this->canResource);
+    
+    if (! $hasPermission) {
+        $this->disabled = true;
+        // For Checkbox: also disables instantSave
+    }
+}
+```
+
+#### Usage Examples
+
+**✅ Recommended Pattern (Single Line):**
+```html
+<!-- Input with automatic authorization -->
+<x-forms.input 
+    canGate="update" 
+    :canResource="$application" 
+    id="application.name" 
+    label="Application Name" />
+
+<!-- Select with automatic authorization -->
+<x-forms.select 
+    canGate="update" 
+    :canResource="$application" 
+    id="application.build_pack" 
+    label="Build Pack">
+    <option value="nixpacks">Nixpacks</option>
+    <option value="static">Static</option>
+</x-forms.select>
+
+<!-- Checkbox with automatic instantSave control -->
+<x-forms.checkbox 
+    instantSave 
+    canGate="update" 
+    :canResource="$application" 
+    id="application.settings.is_static" 
+    label="Is Static Site?" />
+
+<!-- Button with automatic disable -->
+<x-forms.button 
+    canGate="update" 
+    :canResource="$application" 
+    type="submit">
+    Save Configuration
+</x-forms.button>
+```
+
+**❌ Old Pattern (Verbose, Deprecated):**
+```html
+<!-- DON'T use this repetitive pattern anymore -->
+@can('update', $application)
+    <x-forms.input id="application.name" label="Application Name" />
+    <x-forms.button type="submit">Save</x-forms.button>
+@else
+    <x-forms.input disabled id="application.name" label="Application Name" />
+@endcan
+```
+
+#### Advanced Usage with Custom Control
+
+**Custom Authorization Logic:**
+```html
+<!-- Disable auto-control, use custom logic -->
+<x-forms.input 
+    canGate="update" 
+    :canResource="$application" 
+    autoDisable="false"
+    :disabled="$application->is_deployed || !Gate::allows('update', $application)"
+    id="advanced.setting" 
+    label="Advanced Setting" />
+```
+
+**Multiple Permission Checks:**
+```html
+<!-- Complex permission requirements -->
+<x-forms.checkbox 
+    canGate="deploy" 
+    :canResource="$application" 
+    autoDisable="false"
+    :disabled="!$application->canDeploy() || !auth()->user()->hasAdvancedPermissions()"
+    id="deployment.setting" 
+    label="Advanced Deployment Setting" />
+```
+
+#### Supported Gates and Resources
+
+**Common Gates:**
+- `view` - Read access to resource
+- `update` - Modify resource configuration
+- `deploy` - Deploy/restart resource
+- `delete` - Remove resource
+- `createAnyResource` - Create new resources
+
+**Resource Types:**
+- `Application` - Application instances
+- `Service` - Docker Compose services  
+- `Server` - Server instances
+- `Project` - Project containers
+- `Environment` - Environment contexts
+- `Database` - Database instances
+
+#### Benefits
+
+**🔥 Massive Code Reduction:**
+- **90% less code** for authorization-protected forms
+- **Single line** instead of 6-12 lines per form element
+- **No more @can/@else blocks** cluttering templates
+
+**🛡️ Consistent Security:**
+- **Unified authorization logic** across all form components
+- **Automatic disabling** for unauthorized users
+- **Smart behavior** (like disabling instantSave on checkboxes)
+
+**🎨 Better UX:**
+- **Consistent disabled styling** across all components
+- **Proper visual feedback** for restricted access
+- **Clean, professional interface**
+
+#### Implementation Details
+
+**Component Enhancement:**
+```php
+// Enhanced in all form components
+use Illuminate\Support\Facades\Gate;
+
+public function __construct(
+    // ... existing parameters
+    public ?string $canGate = null,
+    public mixed $canResource = null,
+    public bool $autoDisable = true,
+) {
+    // Handle authorization-based disabling
+    if ($this->canGate && $this->canResource && $this->autoDisable) {
+        $hasPermission = Gate::allows($this->canGate, $this->canResource);
+        
+        if (! $hasPermission) {
+            $this->disabled = true;
+            // For Checkbox: $this->instantSave = false;
+        }
+    }
+}
+```
+
+**Backward Compatibility:**
+- All existing form components continue to work unchanged
+- New authorization parameters are optional
+- Legacy @can/@else patterns still function but are discouraged
+
 ### Team-Based Multi-Tenancy
 - **[Team.php](mdc:app/Models/Team.php)** - Multi-tenant organization structure (8.9KB, 308 lines)
 - **[TeamInvitation.php](mdc:app/Models/TeamInvitation.php)** - Secure team collaboration