@aegis-scan/skills 0.5.0 → 0.5.2

package/skills/compliance/aegis-native/brutaler-anwalt/references/stack-patterns/laravel/agb-versioning-pattern.md

@@ -0,0 +1,305 @@
+---
+license: MIT (snippet)
+provider: Laravel + Spatie/Versionable (Open-Source)
+last-checked: 2026-05-05
+purpose: Laravel AGB-/DSE-Versioning-Pattern fuer Nachweis von Vertragsversionen je User.
+---
+
+# Laravel — AGB/DSE-Versioning Pattern
+
+## Trigger / Detection
+
+Repo enthaelt:
+- `spatie/laravel-versionable` oder `tightenco/ziggy-versionable` Package
+- Models mit `Versionable` Trait
+- Tabellen `agb_versions`, `privacy_versions`, `consent_versions`
+- Optional: User-Tabelle mit `current_agb_version` Column
+
+## Default-Verhalten (was passiert ohne Konfiguration)
+
+- AGB-aenderungen erfolgen direkt in `resources/views/legal/agb.blade.php` ohne Versionierung
+- User-Akzeptanz wird beim Signup gespeichert, aber Version unbekannt
+- Bei spaeteren AGB-aenderungen kein Re-Confirm-Workflow → Vertrag-Drift
+- Audit-Trail "Welcher User akzeptierte welche Version wann" fehlt
+- DSE-aenderung ohne Banner-Re-Show → User merkt es nicht
+
+## Compliance-Risiken
+
+| Risiko | Norm | Severity | Fix |
+|---|---|---|---|
+| Kein Versions-Nachweis | Art. 5 Abs. 2 DSGVO Rechenschaft | KRITISCH | Versions-Tabelle mit Hash + Date |
+| AGB-Drift ohne Re-Confirm | § 305 BGB Wirksamkeit | KRITISCH | Banner bei jeder Major-Version |
+| Privacy-Update ohne Notification | Art. 13/14 DSGVO | HOCH | E-Mail + Banner-Force-Show |
+| Hash-Manipulation moeglich | Art. 32 DSGVO | MITTEL | Append-Only Tabelle + DB-Trigger |
+| Keine Diff-Sichtbarkeit fuer User | Art. 12 DSGVO Klarheit | MITTEL | Diff-Page `/datenschutz/diff?from=2.0&to=2.3` |
+
+## Code-Pattern (sanitized)
+
+```php
+// File: database/migrations/2026_05_05_create_legal_versions.php
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration {
+    public function up(): void
+    {
+        Schema::create('legal_versions', function (Blueprint $table) {
+            $table->id();
+            $table->string('section', 32);  // 'agb', 'privacy', 'cookie'
+            $table->string('version', 16);  // '2.3'
+            $table->text('content');
+            $table->string('content_hash', 64);  // SHA-256
+            $table->string('author', 100);
+            $table->timestamp('published_at');
+            $table->boolean('is_major')->default(false);
+            $table->timestamps();
+
+            $table->unique(['section', 'version']);
+            $table->index(['section', 'published_at']);
+        });
+
+        Schema::create('user_legal_acceptances', function (Blueprint $table) {
+            $table->id();
+            $table->foreignId('user_id')->constrained()->cascadeOnDelete();
+            $table->foreignId('legal_version_id')->constrained();
+            $table->string('ip_hash', 16);
+            $table->string('user_agent', 200);
+            $table->timestamp('accepted_at');
+            $table->timestamps();
+
+            $table->unique(['user_id', 'legal_version_id']);
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('user_legal_acceptances');
+        Schema::dropIfExists('legal_versions');
+    }
+};
+```
+
+```php
+// File: app/Models/LegalVersion.php
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Model;
+
+class LegalVersion extends Model
+{
+    protected $fillable = ['section', 'version', 'content', 'content_hash', 'author', 'published_at', 'is_major'];
+
+    protected $casts = [
+        'published_at' => 'datetime',
+        'is_major' => 'boolean',
+    ];
+
+    public function acceptances()
+    {
+        return $this->hasMany(UserLegalAcceptance::class);
+    }
+
+    protected static function booted()
+    {
+        // Append-Only: kein Update, kein Delete
+        static::updating(function () {
+            throw new \RuntimeException('LegalVersion ist append-only (Beweisfunktion)');
+        });
+        static::deleting(function () {
+            throw new \RuntimeException('LegalVersion ist append-only');
+        });
+
+        // Hash automatisch berechnen
+        static::creating(function (self $model) {
+            $model->content_hash = hash('sha256', $model->content);
+        });
+    }
+
+    public static function latest(string $section): ?self
+    {
+        return self::where('section', $section)
+            ->orderByDesc('published_at')
+            ->first();
+    }
+}
+```
+
+```php
+// File: app/Models/UserLegalAcceptance.php
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Model;
+
+class UserLegalAcceptance extends Model
+{
+    protected $fillable = ['user_id', 'legal_version_id', 'ip_hash', 'user_agent', 'accepted_at'];
+
+    protected $casts = ['accepted_at' => 'datetime'];
+
+    protected static function booted()
+    {
+        static::updating(function () {
+            throw new \RuntimeException('Acceptance ist append-only');
+        });
+        static::deleting(function () {
+            // Erlaubt nur Cascade von User::forceDelete (Hard-Delete-Cron)
+            if (!app()->runningInConsole()) {
+                throw new \RuntimeException('Acceptance darf nur via Cron geloescht werden');
+            }
+        });
+    }
+}
+```
+
+```php
+// File: app/Http/Middleware/EnforceLatestLegal.php
+<?php
+
+namespace App\Http\Middleware;
+
+use Closure;
+use Illuminate\Http\Request;
+use App\Models\LegalVersion;
+use App\Models\UserLegalAcceptance;
+
+class EnforceLatestLegal
+{
+    public function handle(Request $request, Closure $next)
+    {
+        $user = $request->user();
+        if (!$user) return $next($request);
+
+        // Pruefe nur major-versions
+        $latestAgb = LegalVersion::latest('agb');
+        $latestPrivacy = LegalVersion::latest('privacy');
+
+        $missingAcceptances = [];
+
+        foreach (['agb' => $latestAgb, 'privacy' => $latestPrivacy] as $section => $version) {
+            if (!$version || !$version->is_major) continue;
+
+            $accepted = UserLegalAcceptance::where('user_id', $user->id)
+                ->where('legal_version_id', $version->id)
+                ->exists();
+
+            if (!$accepted) {
+                $missingAcceptances[] = $section;
+            }
+        }
+
+        if (!empty($missingAcceptances) && !$request->is('legal/accept*')) {
+            return redirect()->route('legal.accept-required', [
+                'sections' => implode(',', $missingAcceptances),
+            ]);
+        }
+
+        return $next($request);
+    }
+}
+```
+
+```php
+// File: app/Http/Controllers/LegalAcceptanceController.php
+<?php
+
+namespace App\Http\Controllers;
+
+use Illuminate\Http\Request;
+use App\Models\LegalVersion;
+use App\Models\UserLegalAcceptance;
+
+class LegalAcceptanceController extends Controller
+{
+    public function accept(Request $request)
+    {
+        $request->validate([
+            'sections' => 'required|array',
+            'sections.*' => 'in:agb,privacy,cookie',
+        ]);
+
+        $user = $request->user();
+        $ipHash = substr(hash('sha256', $request->ip() . config('app.ip_hash_salt')), 0, 16);
+
+        foreach ($request->input('sections') as $section) {
+            $version = LegalVersion::latest($section);
+            if (!$version) continue;
+
+            UserLegalAcceptance::firstOrCreate([
+                'user_id' => $user->id,
+                'legal_version_id' => $version->id,
+            ], [
+                'ip_hash' => $ipHash,
+                'user_agent' => substr($request->userAgent() ?? '', 0, 200),
+                'accepted_at' => now(),
+            ]);
+        }
+
+        return response()->noContent();
+    }
+}
+```
+
+## AVV / DPA
+
+- Datenbank — append-only-Garantie via DB-Trigger optional ergaenzen
+- Mailer fuer Notification-Mails — AVV
+- Diff-Service (sofern external z.B. Diff2HTML) — kein AVV wenn nur public-Texte verglichen werden
+
+## DSE-Wording-Vorlage
+
+```markdown
+### Versions-Historie und Aktualisierungen
+
+Wir versionieren unsere Datenschutzerklaerung und AGB nachvollziehbar:
+
+**Aktuelle Versionen:**
+- Datenschutzerklaerung: Version <placeholder-version>, Stand <placeholder-date>
+- AGB: Version <placeholder-version>, Stand <placeholder-date>
+
+**Frueher veroeffentlichte Versionen:** auf Anfrage verfuegbar (E-Mail an
+<placeholder-email>) — wir koennen den genauen Wortlaut zum Zeitpunkt
+Ihrer Registrierung jederzeit nachweisen (SHA-256-Hash gespeichert).
+
+**Bei wesentlichen aenderungen** (Major-Version) bitten wir Sie beim
+naechsten Login um erneute Zustimmung. Bis zur Bestaetigung wird Ihr
+Account auf den Bestaetigungs-Workflow umgeleitet.
+
+**Rechtsgrundlage:** § 305 BGB (Wirksame Einbeziehung von AGB) i.V.m.
+Art. 5 Abs. 2 DSGVO (Rechenschaftspflicht).
+```
+
+## Verify-Commands (Live-Probe)
+
+```bash
+# 1. Hash-Wirksamkeit pruefen
+php artisan tinker
+# > $v = LegalVersion::first(); hash('sha256', $v->content) === $v->content_hash;
+# Erwartung: true
+
+# 2. Append-only-Schutz
+# > $v->content = 'modified'; $v->save();
+# Erwartung: RuntimeException
+
+# 3. Re-Confirm-Workflow
+# Setze neue is_major-Version, login als User, navigiere zu /dashboard
+# Erwartung: Redirect zu /legal/accept-required?sections=agb
+
+# 4. Audit-Log-Vollstaendigkeit
+# DB-Query: SELECT user_id, legal_version_id, accepted_at FROM user_legal_acceptances WHERE user_id = '<test>';
+# Erwartung: Eintrag pro Major-Version
+```
+
+## Cross-References
+
+- AEGIS-Scanner: `legal-versioning-checker.ts`, `audit-trail-checker.ts`
+- Skill-Reference: `references/dsgvo.md` Art. 5 Abs. 2 (Rechenschaft), Art. 13/14 (Information)
+- BGB: § 305 (Einbeziehung AGB)
+- BGH-Rechtsprechung: `references/bgh-urteile.md`
+- Audit-Pattern: `references/audit-patterns.md` Phase 1 (DSE-Vollstaendigkeit), Phase 8 (Re-Confirm)

package/skills/compliance/aegis-native/brutaler-anwalt/references/stack-patterns/laravel/cookie-banner-pattern.md

@@ -0,0 +1,287 @@
+---
+license: MIT (snippet)
+provider: Laravel + Spatie/cookie-consent (Open-Source)
+last-checked: 2026-05-05
+purpose: Laravel Blade-Component fuer Cookie-Banner mit Spatie/Cookie-Consent-Package.
+---
+
+# Laravel — Cookie-Banner (Pattern)
+
+## Trigger / Detection
+
+Repo enthaelt:
+- `laravel/framework` in `composer.json`
+- `resources/views/**/*.blade.php` Templates
+- `app/Http/Controllers/*` Controller
+- Optional: `spatie/laravel-cookie-consent` Package
+
+## Default-Verhalten (was passiert ohne Konfiguration)
+
+- Laravel-Default-Cookie-Encryption gilt fuer alle Cookies — Performance-Hit
+- `cookie('name', $value)` ohne `secure(true)` → unsicher in Prod
+- Tracker-Scripts in Layout-Blade direkt eingebunden → laufen vor Consent
+- Session-Cookies ohne `same_site=lax` Default in alten Versionen
+- `csrf_token()` Cookie nicht vom Encryption-Bypass betroffen → korrekt
+
+## Compliance-Risiken
+
+| Risiko | Norm | Severity | Fix |
+|---|---|---|---|
+| Tracker-Script in `app.blade.php` Layout | § 25 TDDDG | KRITISCH | Conditional `@if(consent('analytics'))` |
+| Cookie-Encryption auf Consent-Cookie | DSGVO Art. 25 | NIEDRIG | EncryptCookies Middleware-Bypass |
+| `secure(false)` in Prod-Cookies | Art. 32 DSGVO | KRITISCH | `'secure' => env('APP_ENV') === 'production'` |
+| Session ohne `same_site=lax` | Art. 32 DSGVO | HOCH | `config/session.php` setzen |
+| Drittland-Tracker in `mix.js` | Art. 44 DSGVO | KRITISCH | EU-Provider + AVV |
+
+## Code-Pattern (sanitized)
+
+```php
+// File: config/cookie-consent.php
+<?php
+
+return [
+    'banner_view' => 'cookies.banner',
+    'cookie_name' => 'cookie_consent',
+    'cookie_lifetime' => 60 * 24 * 365,  // 12 Monate (Minuten)
+    'categories' => [
+        'necessary' => ['default' => true, 'locked' => true],
+        'analytics' => ['default' => false, 'locked' => false],
+        'marketing' => ['default' => false, 'locked' => false],
+    ],
+];
+```
+
+```php
+// File: app/Http/Middleware/ConsentCookie.php
+<?php
+
+namespace App\Http\Middleware;
+
+use Closure;
+use Illuminate\Http\Request;
+
+class ConsentCookie
+{
+    public function handle(Request $request, Closure $next)
+    {
+        $raw = $request->cookie('cookie_consent');
+        $consent = [
+            'necessary' => true,
+            'analytics' => false,
+            'marketing' => false,
+        ];
+
+        if ($raw) {
+            $parsed = json_decode($raw, true);
+            if (is_array($parsed)) {
+                $consent = array_merge($consent, $parsed);
+            }
+        }
+
+        $request->attributes->set('consent', $consent);
+        view()->share('consent', $consent);
+
+        return $next($request);
+    }
+}
+```
+
+```php
+// File: app/Http/Controllers/ConsentController.php
+<?php
+
+namespace App\Http\Controllers;
+
+use Illuminate\Http\Request;
+use App\Models\ConsentLog;
+
+class ConsentController extends Controller
+{
+    public function store(Request $request)
+    {
+        $validated = $request->validate([
+            'analytics' => 'required|boolean',
+            'marketing' => 'required|boolean',
+        ]);
+
+        $consent = [
+            'necessary' => true,
+            'analytics' => $validated['analytics'],
+            'marketing' => $validated['marketing'],
+            'version' => '1.0',
+            'timestamp' => now()->toIso8601String(),
+        ];
+
+        // Server-Log fuer Nachweispflicht
+        ConsentLog::create([
+            'ip_hash' => substr(hash('sha256', $request->ip() . config('app.ip_hash_salt')), 0, 16),
+            'user_agent' => substr($request->userAgent() ?? '', 0, 200),
+            'consent' => $consent,
+        ]);
+
+        return response()->noContent()
+            ->cookie(
+                'cookie_consent',
+                json_encode($consent),
+                60 * 24 * 365,        // 12 Monate (Minuten)
+                '/',                  // Path
+                null,                 // Domain
+                config('app.env') === 'production',  // Secure
+                false,                // HttpOnly = false (Banner-JS muss lesen)
+                false,                // Raw
+                'lax'                 // SameSite
+            );
+    }
+}
+```
+
+```blade
+{{-- File: resources/views/cookies/banner.blade.php --}}
+@if(! request()->cookie('cookie_consent'))
+<aside id="cookie-banner" role="dialog" aria-label="Cookie-Einwilligung" class="cookie-banner">
+    <p>
+        Wir nutzen Cookies fuer notwendige Funktionen und mit Ihrer Einwilligung
+        zusaetzlich fuer Webanalyse. Details:
+        <a href="{{ route('legal.privacy') }}">Datenschutzerklaerung</a>.
+    </p>
+    <div class="cookie-actions">
+        <button type="button" data-action="reject-all" class="btn-secondary">
+            Nur Notwendige
+        </button>
+        <button type="button" data-action="accept-all" class="btn-primary">
+            Alle akzeptieren
+        </button>
+    </div>
+</aside>
+
+<script>
+(function() {
+    const csrf = '{{ csrf_token() }}';
+    const submit = (analytics, marketing) => {
+        fetch('{{ route('consent.store') }}', {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-CSRF-TOKEN': csrf,
+            },
+            body: JSON.stringify({ analytics, marketing }),
+        }).then(() => {
+            document.getElementById('cookie-banner').remove();
+            if (analytics) loadAnalytics();
+        });
+    };
+
+    document.querySelector('[data-action="reject-all"]').onclick = () => submit(false, false);
+    document.querySelector('[data-action="accept-all"]').onclick = () => submit(true, true);
+
+    function loadAnalytics() {
+        const s = document.createElement('script');
+        s.src = 'https://<placeholder-eu-analytics-host>/script.js';
+        s.async = true;
+        document.head.appendChild(s);
+    }
+})();
+</script>
+@endif
+```
+
+```blade
+{{-- File: resources/views/layouts/app.blade.php --}}
+<!DOCTYPE html>
+<html lang="de">
+<head>
+    <meta charset="UTF-8">
+    <meta name="csrf-token" content="{{ csrf_token() }}">
+    <title>@yield('title', '<placeholder-site-name>')</title>
+    {{-- KEIN Tracker-Script hier — nur conditional nach Consent --}}
+    @if($consent['analytics'] ?? false)
+        <script src="https://<placeholder-eu-analytics-host>/script.js" async></script>
+    @endif
+</head>
+<body>
+    @yield('content')
+    @include('cookies.banner')
+</body>
+</html>
+```
+
+```php
+// File: app/Http/Kernel.php (Auszug)
+protected $middlewareGroups = [
+    'web' => [
+        \App\Http\Middleware\EncryptCookies::class,
+        // ...
+        \App\Http\Middleware\ConsentCookie::class,
+    ],
+];
+
+// File: app/Http/Middleware/EncryptCookies.php
+protected $except = [
+    'cookie_consent',  // Banner-JS muss lesen koennen → kein Encryption
+];
+```
+
+## AVV / DPA
+
+- Hosting-Provider — Art. 28 DSGVO
+- Datenbank-Provider (MySQL/Postgres) — AVV
+- Analytics-Provider (Plausible EU / Matomo) — AVV
+- Mailer (SES EU / Mailgun EU) — AVV
+
+## DSE-Wording-Vorlage
+
+```markdown
+### Cookies (Laravel)
+
+Diese Webseite verwendet folgende Cookies:
+
+**Notwendige Cookies (kein Opt-Out moeglich):**
+- `XSRF-TOKEN` — CSRF-Schutz, Session-Dauer
+- `<placeholder-app-name>_session` — Session-Management, Session-Dauer
+- `cookie_consent` — Speicherung Ihrer Einwilligung, 12 Monate
+
+**Analyse-Cookies (Opt-In):**
+- `<placeholder-analytics-cookie>` — Webanalyse, <placeholder-days> Tage
+- Anbieter: <placeholder-analytics-provider>, EU-Hosting
+
+**Marketing-Cookies (Opt-In):**
+- aktuell keine, ggf. zukuenftig
+
+**Rechtsgrundlage:** § 25 TDDDG i.V.m. Art. 6 Abs. 1 lit. a/f DSGVO.
+**Widerruf:** [Cookie-Einstellungen](#cookie-settings) im Footer.
+```
+
+## Verify-Commands (Live-Probe)
+
+```bash
+# 1. Banner sichtbar fuer neue Visitors
+curl -sS https://<placeholder-domain>/ | grep -ic "cookie-banner"
+
+# 2. cookie_consent in EncryptCookies-Bypass
+curl -X POST https://<placeholder-domain>/consent \
+  -H "Content-Type: application/json" \
+  -H "X-CSRF-TOKEN: <placeholder-csrf>" \
+  -d '{"analytics":false,"marketing":false}' -i \
+  | grep -i "set-cookie:.*cookie_consent"
+# Erwartung: Klartext-JSON, NICHT Laravel-encrypted
+
+# 3. Tracker-Script erst nach Consent
+curl -sS -H 'Cookie: cookie_consent=%7B%22analytics%22%3Afalse%7D' https://<placeholder-domain>/ \
+  | grep -ic "<placeholder-eu-analytics-host>"
+# Erwartung: 0
+
+curl -sS -H 'Cookie: cookie_consent=%7B%22analytics%22%3Atrue%7D' https://<placeholder-domain>/ \
+  | grep -ic "<placeholder-eu-analytics-host>"
+# Erwartung: >=1
+
+# 4. Session-Cookie mit Lax + Secure
+curl -sI https://<placeholder-domain>/ | grep -iE "set-cookie:.*session.*lax.*secure"
+```
+
+## Cross-References
+
+- AEGIS-Scanner: `cookie-flags-checker.ts`, `consent-flow-checker.ts`, `tracking-scan.ts`
+- Skill-Reference: `references/dsgvo.md` § 25 TDDDG, Art. 7 DSGVO
+- BGH-Rechtsprechung: `references/bgh-urteile.md` BGH I ZR 7/16
+- OLG Koeln 6 U 80/23 (Button-Gleichwertigkeit)
+- Audit-Pattern: `references/audit-patterns.md` Phase 2 (Cookie-Audit)