michael/michaelschiemer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: DockerSecretsResolver - don't normalize absolute paths like /var/www/html/...
Some checks failed
Deploy Application / deploy (push) Has been cancelled
Details

Browse Source
This commit is contained in:
Michael Schiemer
2025-11-24 21:28:25 +01:00
parent 4eb7134853
commit 77abc65cd7
1327 changed files with 91915 additions and 9909 deletions
Download Patch File Download Diff File Expand all files Collapse all files

365
docs/framework/csrf-protection.md Normal file
View File

@@ -0,0 +1,365 @@
# CSRF Protection System
## Übersicht
Das CSRF (Cross-Site Request Forgery) Protection System bietet robusten Schutz gegen CSRF-Angriffe durch:
- **Atomare Session-Updates**: Verhindert Race Conditions bei parallelen Requests
- **Vereinfachte Token-Generierung**: Immer neue Token, keine Wiederverwendung
- **Robuste HTML-Verarbeitung**: DOM-basierte Token-Ersetzung mit Regex-Fallback
- **Einheitliche API**: Konsistente Endpunkte für PHP und JavaScript
## Architektur
### Komponenten
1. **CsrfProtection**: Verwaltet Token-Generierung und Validierung
2. **SessionManager**: Bietet atomare Session-Updates mit Locking
3. **FormDataResponseProcessor**: Ersetzt Token-Platzhalter in HTML
4. **CsrfMiddleware**: Validiert Token bei state-changing Requests
5. **API Controllers**: Bereitstellen Token-Endpunkte für JavaScript
### Session-Locking
Das System verwendet Session-Locking, um Race Conditions zu verhindern:
- **FileSessionStorage**: Datei-basiertes Locking mit `flock()`
- **RedisSessionStorage**: Redis `SET NX EX` für atomares Locking
- **InMemorySessionStorage**: In-Memory-Locking für Tests
### Optimistic Locking
SessionData verwendet Versionsnummern für Optimistic Locking:
- Jede Änderung inkrementiert die Version
- Bei Konflikten wird automatisch retried
- Verhindert Datenverlust bei parallelen Updates
## Token-Generierung
### Vereinfachte Strategie
**Wichtig**: Das System generiert **immer neue Token** - keine Wiederverwendung.
```php
// Generiert immer einen neuen Token
$token = $session->csrf->generateToken($formId);
```
### Token-Verwaltung
- **Maximal 3 Token pro Form-ID**: Älteste werden automatisch entfernt
- **Token-Lifetime**: 2 Stunden (7200 Sekunden)
- **Re-Submit Window**: 30 Sekunden für erneute Submissions
- **Automatisches Cleanup**: Abgelaufene Token werden entfernt
### Token-Format
- **Länge**: 64 Zeichen
- **Format**: Hexadezimal (0-9, a-f)
- **Beispiel**: `f677a410facd19e4e004e41e24fa1c8abbe2379a91abcf8642de23a6988ba8b`
## HTML-Verarbeitung
### DOM-basierte Ersetzung
Der `FormDataResponseProcessor` verwendet DOM-basierte Verarbeitung für robuste Token-Ersetzung:
```php
// Automatische Ersetzung von Platzhaltern
$html = $processor->process($html, $session);
```
### Platzhalter-Format
```html
<input type="hidden" name="_token" value="___TOKEN_FORMID___">
```
### Fallback-Mechanismus
Bei DOM-Parsing-Fehlern fällt das System automatisch auf Regex-basierte Ersetzung zurück.
## API-Endpunkte
### Token-Generierung
**GET/POST `/api/csrf/token`**
Generiert einen neuen CSRF-Token für eine Form.
**Parameter:**
- `action` (optional): Form-Action URL (Standard: `/`)
- `method` (optional): HTTP-Methode (Standard: `post`)
- `form_id` (optional): Explizite Form-ID
**Response:**
```json
{
"form_id": "form_abc123def456",
"token": "64-character-hex-token",
"expires_in": 7200,
"headers": {
"X-CSRF-Form-ID": "form_abc123def456",
"X-CSRF-Token": "64-character-hex-token"
}
}
```
### Token-Refresh
**GET `/api/csrf/refresh`**
Generiert einen neuen Token für eine bestehende Form-ID.
**Parameter:**
- `form_id` (erforderlich): Form-ID
**Response:**
```json
{
"form_id": "form_abc123def456",
"token": "64-character-hex-token",
"expires_in": 7200,
"headers": {
"X-CSRF-Form-ID": "form_abc123def456",
"X-CSRF-Token": "64-character-hex-token"
}
}
```
### Token-Informationen
**GET `/api/csrf/info`**
Gibt Informationen über aktive Token zurück.
**Parameter:**
- `form_id` (erforderlich): Form-ID
**Response:**
```json
{
"form_id": "form_abc123def456",
"active_tokens": 2,
"max_tokens_per_form": 3,
"token_lifetime_seconds": 7200,
"resubmit_window_seconds": 30
}
```
## JavaScript-Integration
### CsrfManager
Der `CsrfManager` verwaltet Token automatisch:
```javascript
import { CsrfManager } from './modules/security/CsrfManager.js';
const csrfManager = CsrfManager.create({
endpoint: '/api/csrf/token',
autoRefresh: true,
refreshInterval: 30 * 60 * 1000 // 30 Minuten
});
// Token abrufen
const token = csrfManager.getToken();
// Token-Header für Requests
const headers = csrfManager.getTokenHeader();
```
### Manuelle Token-Anfrage
```javascript
// Token für spezifische Form generieren
const response = await fetch('/api/csrf/token?action=/submit&method=post');
const data = await response.json();
const token = data.token;
const formId = data.form_id;
```
### AJAX-Requests
```javascript
// Token in Request-Body
fetch('/api/submit', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-CSRF-Form-ID': formId,
'X-CSRF-Token': token
},
body: JSON.stringify({
_form_id: formId,
_token: token,
// ... weitere Daten
})
});
```
## Validierung
### Middleware
Die `CsrfMiddleware` validiert automatisch Token für:
- POST Requests
- PUT Requests
- DELETE Requests
- PATCH Requests
GET Requests werden nicht validiert.
### Validierungsprozess
1. **Token-Extraktion**: Aus Request-Body oder Headers
2. **Form-ID-Extraktion**: Aus Request-Body oder Headers
3. **Session-Lookup**: Token in Session suchen
4. **Validierung**: Token-Match und Expiration prüfen
5. **Markierung**: Token als verwendet markieren
### Fehlerbehandlung
Bei Validierungsfehlern wird eine `CsrfValidationFailedException` geworfen mit:
- Fehlgrund (missing token, invalid token, expired, etc.)
- Session-ID
- Anzahl verfügbarer Token
- Liste verfügbarer Form-IDs
## Best Practices
### Form-IDs
- Verwende konsistente Form-IDs für dieselben Formulare
- Form-IDs werden automatisch aus Action und Method generiert
- Explizite Form-IDs können über `form_id` Parameter gesetzt werden
### Token-Refresh
- Token sollten vor Ablauf erneuert werden
- Automatischer Refresh alle 30 Minuten empfohlen
- Bei langen Formularen manuell vor Submit refreshen
### Fehlerbehandlung
```php
try {
// Form-Verarbeitung
} catch (CsrfValidationFailedException $e) {
// Token ungültig - Benutzer sollte Seite neu laden
return redirect()->back()->with('error', 'Session expired. Please try again.');
}
```
### Testing
```php
// Token generieren
$token = $session->csrf->generateToken('test-form');
// Token validieren
$isValid = $session->csrf->validateToken('test-form', $token);
// Mit Debug-Informationen
$result = $session->csrf->validateTokenWithDebug('test-form', $token);
if (!$result['valid']) {
$reason = $result['debug']['reason'];
// ...
}
```
## Troubleshooting
### Token wird nicht akzeptiert
1. **Prüfe Token-Länge**: Muss genau 64 Zeichen sein
2. **Prüfe Form-ID**: Muss mit generierter Form-ID übereinstimmen
3. **Prüfe Session**: Token muss in Session vorhanden sein
4. **Prüfe Expiration**: Token darf nicht abgelaufen sein
### Race Conditions
Das System verwendet atomare Session-Updates, um Race Conditions zu verhindern. Bei Problemen:
1. Prüfe Session-Storage-Konfiguration
2. Prüfe Locking-Mechanismus (File/Redis)
3. Prüfe Logs für Version-Conflicts
### HTML-Verarbeitung
Bei Problemen mit Token-Ersetzung:
1. Prüfe Platzhalter-Format: `___TOKEN_FORMID___`
2. Prüfe HTML-Struktur (DOM-Parsing kann bei malformed HTML fehlschlagen)
3. Prüfe Logs für Fallback auf Regex
## Migration
### Von altem System
Das neue System ist vollständig kompatibel mit dem alten System:
- Alte Token werden weiterhin akzeptiert
- Alte API-Endpunkte funktionieren weiterhin
- Keine Breaking Changes
### Neue Features nutzen
1. Verwende `/api/csrf/token` statt `/api/csrf-token`
2. Nutze atomare Session-Updates für kritische Operationen
3. Verwende DOM-basierte HTML-Verarbeitung (automatisch)
## Performance
### Optimierungen
- **Token-Cleanup**: Automatisch nach 5 Minuten
- **Maximal 3 Token**: Begrenzt Session-Größe
- **Locking-Timeout**: 5 Sekunden Standard-Timeout
- **Optimistic Locking**: Reduziert Lock-Contention
### Monitoring
- Token-Anzahl pro Form-ID überwachen
- Session-Lock-Contention überwachen
- Token-Validierungs-Fehlerrate überwachen
## Sicherheit
### Schutz-Mechanismen
1. **Token-Rotation**: Neue Token nach jeder Generierung
2. **Expiration**: Token laufen nach 2 Stunden ab
3. **Single-Use**: Token können innerhalb von 30 Sekunden wiederverwendet werden
4. **Session-Binding**: Token sind an Session gebunden
### Angriffs-Vektoren
Das System schützt gegen:
- **CSRF-Angriffe**: Token-Validierung verhindert unautorisierte Requests
- **Token-Replay**: Expiration und Single-Use verhindern Replay
- **Session-Hijacking**: Session-Binding verhindert Token-Diebstahl
## Referenz
### Klassen
- `App\Framework\Http\Session\CsrfProtection`
- `App\Framework\Http\Session\SessionManager`
- `App\Framework\View\Response\FormDataResponseProcessor`
- `App\Framework\Http\Middlewares\CsrfMiddleware`
- `App\Application\Api\CsrfController`
- `App\Application\Controller\CsrfController`
### Konstanten
- `CsrfProtection::TOKEN_LIFETIME` = 7200 (2 Stunden)
- `CsrfProtection::MAX_TOKENS_PER_FORM` = 3
- `CsrfProtection::RE_SUBMIT_WINDOW` = 30 (Sekunden)

257
docs/framework/data-attributes-reference.md Normal file
View File

@@ -0,0 +1,257 @@
# Data Attributes Reference
Complete reference for all `data-*` HTML attributes used in the framework, organized by feature area.
## Overview
All data attributes are centrally managed through PHP Enums and JavaScript Constants to ensure:
- **Type Safety**: IDE autocomplete and compile-time checks
- **Consistency**: Unified naming conventions
- **Refactoring**: Easy renaming across the entire codebase
- **Documentation**: Central overview of all attributes
## Structure
Attributes are organized into specialized Enums/Constants by feature area:
- **LiveComponent Core** (`LiveComponentCoreAttribute` / `LiveComponentCoreAttributes`)
- **LiveComponent Features** (`LiveComponentFeatureAttribute` / `LiveComponentFeatureAttributes`)
- **LiveComponent Lazy Loading** (`LiveComponentLazyAttribute` / `LiveComponentLazyAttributes`)
- **Admin Tables** (`AdminTableAttribute` / `AdminTableAttributes`)
- **Bulk Operations** (`BulkOperationAttribute` / `BulkOperationAttributes`)
- **Action Handler** (`ActionHandlerAttribute` / `ActionHandlerAttributes`)
- **Form Data** (`FormDataAttribute` / `FormDataAttributes`)
- **State Management** (`StateDataAttribute` / `StateDataAttributes`)
- **UI Enhancements** (`UIDataAttribute` / `UIDataAttributes`)
- **Module System** (`ModuleDataAttribute` / `ModuleDataAttributes`)
## Usage
### PHP Backend
```php
use App\Framework\View\ValueObjects\LiveComponentCoreAttribute;
use App\Framework\View\Dom\ElementNode;
// Get attribute name
$attr = LiveComponentCoreAttribute::LIVE_COMPONENT->value();
// Returns: "data-live-component"
// Convert to CSS selector
$selector = LiveComponentCoreAttribute::LIVE_COMPONENT->toSelector();
// Returns: "[data-live-component]"
// Convert to JavaScript dataset key
$datasetKey = LiveComponentCoreAttribute::LIVE_COMPONENT->toDatasetKey();
// Returns: "liveComponent"
// Use directly in methods (no ->value() needed!)
$element = new ElementNode('div');
$element->setAttribute(LiveComponentCoreAttribute::LIVE_COMPONENT, 'my-component');
$element->hasAttribute(LiveComponentCoreAttribute::LIVE_COMPONENT); // true
$value = $element->getAttribute(LiveComponentCoreAttribute::LIVE_COMPONENT); // "my-component"
// For array keys, ->value() is still required (PHP limitation)
$attributes = [
LiveComponentCoreAttribute::LIVE_COMPONENT->value() => 'my-component',
LiveComponentCoreAttribute::STATE->value() => '{}',
];
```
### JavaScript Frontend
```javascript
import { LiveComponentCoreAttributes, toDatasetKey } from '/assets/js/core/DataAttributes.js';
// Get attribute name
const attr = LiveComponentCoreAttributes.LIVE_COMPONENT;
// Returns: "data-live-component"
// Use in getAttribute
element.getAttribute(LiveComponentCoreAttributes.LIVE_COMPONENT);
// Use in dataset (with helper)
element.dataset[toDatasetKey(LiveComponentCoreAttributes.LIVE_COMPONENT)];
// Use in querySelector
document.querySelector(`[${LiveComponentCoreAttributes.LIVE_COMPONENT}]`);
```
## LiveComponent Core Attributes
Core data-* attributes for component identification, state, security, and real-time communication.
| Attribute | Enum Case | Description |
|-----------|-----------|-------------|
| `data-live-component` | `LIVE_COMPONENT` | Component root element identifier |
| `data-component-id` | `COMPONENT_ID` | Unique component instance ID |
| `data-live-id` | `LIVE_ID` | Alternative component ID |
| `data-state` | `STATE` | Component state (JSON) |
| `data-live-state` | `LIVE_STATE` | Alternative state attribute |
| `data-live-content` | `LIVE_CONTENT` | Component content container |
| `data-live-action` | `LIVE_ACTION` | Action name to trigger |
| `data-csrf-token` | `CSRF_TOKEN` | Component-specific CSRF token |
| `data-sse-channel` | `SSE_CHANNEL` | Server-Sent Events channel |
| `data-poll-interval` | `POLL_INTERVAL` | Polling interval in milliseconds |
| `data-live-upload` | `LIVE_UPLOAD` | File upload handler |
| `data-live-dropzone` | `LIVE_DROPZONE` | File dropzone handler |
| `data-live-polite` | `LIVE_POLITE` | Accessibility politeness level |
## LiveComponent Feature Attributes
Advanced feature attributes (data-lc-*) for data binding, fragments, URL management, transitions, and triggers.
| Attribute | Enum Case | Description |
|-----------|-----------|-------------|
| `data-lc-model` | `LC_MODEL` | Two-way data binding |
| `data-lc-fragment` | `LC_FRAGMENT` | Fragment identifier |
| `data-lc-fragments` | `LC_FRAGMENTS` | Comma-separated fragment list |
| `data-lc-key` | `LC_KEY` | Element key for DOM matching |
| `data-lc-boost` | `LC_BOOST` | Progressive enhancement |
| `data-lc-push-url` | `LC_PUSH_URL` | Push URL to browser history |
| `data-lc-replace-url` | `LC_REPLACE_URL` | Replace URL without history entry |
| `data-lc-target` | `LC_TARGET` | Target element selector |
| `data-lc-swap` | `LC_SWAP` | DOM swap strategy |
| `data-lc-swap-transition` | `LC_SWAP_TRANSITION` | Transition animation |
| `data-lc-keep-focus` | `LC_KEEP_FOCUS` | Preserve focus after update |
| `data-lc-scroll` | `LC_SCROLL` | Enable scrolling |
| `data-lc-scroll-target` | `LC_SCROLL_TARGET` | Scroll target selector |
| `data-lc-scroll-behavior` | `LC_SCROLL_BEHAVIOR` | Scroll behavior (smooth/instant) |
| `data-lc-indicator` | `LC_INDICATOR` | Loading indicator selector |
| `data-lc-trigger-delay` | `LC_TRIGGER_DELAY` | Trigger delay in milliseconds |
| `data-lc-trigger-throttle` | `LC_TRIGGER_THROTTLE` | Trigger throttle in milliseconds |
| `data-lc-trigger-once` | `LC_TRIGGER_ONCE` | Trigger only once |
| `data-lc-trigger-changed` | `LC_TRIGGER_CHANGED` | Trigger only on value change |
| `data-lc-trigger-from` | `LC_TRIGGER_FROM` | Trigger from another element |
| `data-lc-trigger-load` | `LC_TRIGGER_LOAD` | Trigger on page load |
## LiveComponent Lazy Loading Attributes
Attributes for lazy loading and island rendering of LiveComponents.
| Attribute | Enum Case | Description |
|-----------|-----------|-------------|
| `data-live-component-lazy` | `LIVE_COMPONENT_LAZY` | Lazy-loaded component ID |
| `data-live-component-island` | `LIVE_COMPONENT_ISLAND` | Island component ID |
| `data-island-component` | `ISLAND_COMPONENT` | Mark as island component |
| `data-lazy-priority` | `LAZY_PRIORITY` | Loading priority (high/normal/low) |
| `data-lazy-threshold` | `LAZY_THRESHOLD` | Intersection observer threshold |
| `data-lazy-placeholder` | `LAZY_PLACEHOLDER` | Placeholder text |
## Admin Table Attributes
Data attributes for admin table functionality including sorting, pagination, searching, and column configuration.
| Attribute | Enum Case | Description |
|-----------|-----------|-------------|
| `data-resource` | `RESOURCE` | Resource name |
| `data-api-endpoint` | `API_ENDPOINT` | API endpoint URL |
| `data-sortable` | `SORTABLE` | Enable sorting |
| `data-searchable` | `SEARCHABLE` | Enable searching |
| `data-paginated` | `PAGINATED` | Enable pagination |
| `data-per-page` | `PER_PAGE` | Items per page |
| `data-column` | `COLUMN` | Column identifier |
| `data-sort-dir` | `SORT_DIR` | Sort direction (asc/desc) |
| `data-page` | `PAGE` | Page number |
| `data-table-search` | `TABLE_SEARCH` | Search container selector |
| `data-table-pagination` | `TABLE_PAGINATION` | Pagination container selector |
## Bulk Operation Attributes
Data attributes for bulk operations on admin tables.
| Attribute | Enum Case | Description |
|-----------|-----------|-------------|
| `data-bulk-operations` | `BULK_OPERATIONS` | Enable bulk operations |
| `data-bulk-toolbar` | `BULK_TOOLBAR` | Toolbar container selector |
| `data-bulk-count` | `BULK_COUNT` | Selected count element selector |
| `data-bulk-buttons` | `BULK_BUTTONS` | Action buttons container selector |
| `data-bulk-initialized` | `BULK_INITIALIZED` | Initialization flag |
| `data-bulk-select-all` | `BULK_SELECT_ALL` | Select all checkbox |
| `data-bulk-item-id` | `BULK_ITEM_ID` | Item ID for bulk selection |
| `data-bulk-action` | `BULK_ACTION` | Bulk action name |
| `data-bulk-method` | `BULK_METHOD` | HTTP method for bulk action |
| `data-bulk-confirm` | `BULK_CONFIRM` | Confirmation message |
## Action Handler Attributes
Data attributes for the ActionHandler system.
| Attribute | Enum Case | Description |
|-----------|-----------|-------------|
| `data-action` | `ACTION` | Action name |
| `data-action-handler` | `ACTION_HANDLER` | Handler name |
| `data-action-url` | `ACTION_URL` | Direct action URL |
| `data-action-method` | `ACTION_METHOD` | HTTP method |
| `data-action-type` | `ACTION_TYPE` | Action type (e.g., "window") |
| `data-action-handler-container` | `ACTION_HANDLER_CONTAINER` | Container selector |
| `data-action-confirm` | `ACTION_CONFIRM` | Confirmation message |
| `data-action-loading-text` | `ACTION_LOADING_TEXT` | Loading text |
| `data-action-success-toast` | `ACTION_SUCCESS_TOAST` | Success message |
| `data-action-error-toast` | `ACTION_ERROR_TOAST` | Error message |
**Note**: `data-action-param-*` is a pattern (not an enum case) for dynamic parameters.
## Form Data Attributes
Data attributes for form handling and validation.
| Attribute | Enum Case | Description |
|-----------|-----------|-------------|
| `data-field` | `FIELD` | Form field identifier |
| `data-selected-if` | `SELECTED_IF` | Conditional selection |
| `data-checked-if` | `CHECKED_IF` | Conditional check |
**Note**: `data-param-*` is a pattern (not an enum case) for dynamic parameters.
## State Management Attributes
Data attributes for client-side state management and data binding.
| Attribute | Enum Case | Description |
|-----------|-----------|-------------|
| `data-bind` | `BIND` | Bind to state key |
| `data-bind-attr` | `BIND_ATTR` | Bind attribute to state |
| `data-bind-attr-name` | `BIND_ATTR_NAME` | Attribute name for binding |
| `data-bind-class` | `BIND_CLASS` | Bind class to state |
| `data-bind-input` | `BIND_INPUT` | Two-way input binding |
| `data-persistent` | `PERSISTENT` | Persist state in localStorage |
## UI Enhancement Attributes
Data attributes for UI enhancements including loading states, optimistic updates, confirmations, modals, themes, and other UI features.
| Attribute | Enum Case | Description |
|-----------|-----------|-------------|
| `data-loading` | `LOADING` | Enable loading state |
| `data-loading-text` | `LOADING_TEXT` | Loading text |
| `data-original-text` | `ORIGINAL_TEXT` | Original text (for restoration) |
| `data-optimistic` | `OPTIMISTIC` | Enable optimistic updates |
| `data-rollback` | `ROLLBACK` | Rollback flag |
| `data-confirm-ok` | `CONFIRM_OK` | Confirm OK button |
| `data-confirm-cancel` | `CONFIRM_CANCEL` | Confirm cancel button |
| `data-close-modal` | `CLOSE_MODAL` | Close modal button |
| `data-tag` | `TAG` | Tag identifier |
| `data-theme` | `THEME` | Theme name |
| `data-theme-icon` | `THEME_ICON` | Theme icon selector |
| `data-mobile-menu-open` | `MOBILE_MENU_OPEN` | Mobile menu state |
| `data-section-id` | `SECTION_ID` | Section identifier |
| `data-tab` | `TAB` | Tab identifier |
| `data-view-mode` | `VIEW_MODE` | View mode |
| `data-asset-id` | `ASSET_ID` | Asset identifier |
## Module System Attributes
Data attributes for the JavaScript module initialization system.
| Attribute | Enum Case | Description |
|-----------|-----------|-------------|
| `data-module` | `MODULE` | Module name |
| `data-options` | `OPTIONS` | Module options (JSON) |
## Related Documentation
- [LiveComponents API Reference](../livecomponents/api-reference.md)
- [Action Handler Guide](../javascript/action-handler-guide.md)
- [Framework Architecture](../README.md)