@aegis-scan/skills 0.5.0 → 0.5.1

package/skills/compliance/aegis-native/brutaler-anwalt/references/stack-patterns/nest/auth-pattern.md

@@ -0,0 +1,265 @@
+---
+license: MIT (snippet)
+provider: NestJS + Passport (Open-Source)
+last-checked: 2026-05-05
+purpose: NestJS Auth-Pattern mit Passport-Strategy + DSGVO-konformer Session-Verwaltung.
+---
+
+# NestJS — Auth-Pattern (Passport + DSGVO-Sessions)
+
+## Trigger / Detection
+
+Repo enthaelt:
+- `@nestjs/passport`, `@nestjs/jwt` in Dependencies
+- `*Strategy.ts` (LocalStrategy, JwtStrategy, OAuth2Strategy)
+- `AuthModule`, `AuthService`, `AuthGuard`
+- Optional: `bcrypt` / `argon2` fuer Password-Hashing
+- Optional: `@nestjs/throttler` fuer Rate-Limiting
+
+## Default-Verhalten (was passiert ohne Konfiguration)
+
+- Passport-Default speichert Session-IDs ohne `Secure;HttpOnly`
+- JWT ohne Expiry-Default → permanente Tokens
+- Login-Fehler-Messages leaken User-Existence ("user not found" vs "wrong password")
+- Login-Endpoint ohne Rate-Limit → Brute-Force-Vektor
+- Failed-Login-Logs enthalten Klartext-Passwort wenn falsches Logging-Level
+
+## Compliance-Risiken
+
+| Risiko | Norm | Severity | Fix |
+|---|---|---|---|
+| Session-Cookie ohne Secure-Flag | Art. 32 DSGVO | KRITISCH | `cookie: { secure: true, httpOnly: true, sameSite: 'lax' }` |
+| JWT ohne Expiry | Art. 32 DSGVO | KRITISCH | `signOptions: { expiresIn: '15m' }` + Refresh |
+| User-Enumeration via Error-Messages | DSGVO Art. 32 | HOCH | Generisches "Login-Daten ungueltig" |
+| Klartext-Passwort in Logs | Art. 5 lit. f DSGVO | KRITISCH | Logging-Filter / Pino-Redact |
+| Brute-Force-Schutz fehlt | Art. 32 DSGVO | HOCH | `@nestjs/throttler` + IP-Hash-Block |
+| Login-Logs ohne Anonymisierung | Art. 5 lit. f | MITTEL | IP-Hash + Truncate UserAgent |
+
+## Code-Pattern (sanitized)
+
+```typescript
+// File: src/auth/strategies/jwt.strategy.ts
+import { Injectable, UnauthorizedException } from '@nestjs/common';
+import { PassportStrategy } from '@nestjs/passport';
+import { ExtractJwt, Strategy } from 'passport-jwt';
+
+@Injectable()
+export class JwtStrategy extends PassportStrategy(Strategy) {
+  constructor() {
+    super({
+      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
+      ignoreExpiration: false,  // KRITISCH: niemals true
+      secretOrKey: process.env.JWT_SECRET!,  // mind. 32 Bytes random
+      issuer: '<placeholder-domain>',
+      audience: '<placeholder-domain>',
+    });
+  }
+
+  async validate(payload: { sub: string; email: string; iat: number }) {
+    if (!payload.sub) throw new UnauthorizedException();
+    return { id: payload.sub, email: payload.email };
+  }
+}
+```
+
+```typescript
+// File: src/auth/auth.service.ts
+import { Injectable, UnauthorizedException, Logger } from '@nestjs/common';
+import { JwtService } from '@nestjs/jwt';
+import { InjectRepository } from '@nestjs/typeorm';
+import { Repository } from 'typeorm';
+import * as argon2 from 'argon2';
+import { User } from '../users/user.entity';
+import { LoginAttempt } from './login-attempt.entity';
+
+@Injectable()
+export class AuthService {
+  private readonly logger = new Logger(AuthService.name);
+
+  constructor(
+    @InjectRepository(User) private readonly users: Repository<User>,
+    @InjectRepository(LoginAttempt) private readonly attempts: Repository<LoginAttempt>,
+    private readonly jwt: JwtService,
+  ) {}
+
+  async login(email: string, password: string, ipHash: string) {
+    // Generic-Error: user-enumeration verhindern
+    const user = await this.users.findOne({ where: { email } });
+    const valid = user ? await argon2.verify(user.passwordHash, password) : false;
+
+    // Audit-Log (egal ob Erfolg)
+    await this.attempts.save({
+      ipHash,
+      success: valid,
+      timestamp: new Date(),
+      // NIE: email, password
+    });
+
+    if (!user || !valid) {
+      // Konstante Antwortzeit (timing-attack-Schutz)
+      await this.delay(200);
+      throw new UnauthorizedException('Login-Daten ungueltig');
+    }
+
+    const token = this.jwt.sign(
+      { sub: user.id, email: user.email },
+      { expiresIn: '15m' },
+    );
+
+    const refresh = this.jwt.sign(
+      { sub: user.id, type: 'refresh' },
+      { expiresIn: '7d' },
+    );
+
+    return { token, refresh, expiresIn: 900 };
+  }
+
+  async logout(userId: string) {
+    // Refresh-Token-Invalidation (in DB-Tabelle)
+    await this.users.update(userId, { tokenVersion: () => 'token_version + 1' });
+  }
+
+  private delay(ms: number): Promise<void> {
+    return new Promise(r => setTimeout(r, ms));
+  }
+}
+```
+
+```typescript
+// File: src/auth/auth.controller.ts
+import {
+  Body, Controller, Post, UseGuards, Req, Res, HttpCode,
+} from '@nestjs/common';
+import { Response, Request } from 'express';
+import { Throttle } from '@nestjs/throttler';
+import { IsEmail, IsString, MinLength } from 'class-validator';
+import * as crypto from 'crypto';
+import { AuthService } from './auth.service';
+import { JwtAuthGuard } from './jwt-auth.guard';
+
+class LoginDto {
+  @IsEmail() email!: string;
+  @IsString() @MinLength(8) password!: string;
+}
+
+@Controller('auth')
+export class AuthController {
+  constructor(private readonly auth: AuthService) {}
+
+  @Post('login')
+  @HttpCode(200)
+  @Throttle({ default: { limit: 5, ttl: 60_000 } })  // 5/min pro IP
+  async login(@Body() dto: LoginDto, @Req() req: Request, @Res({ passthrough: true }) res: Response) {
+    const ip = req.headers['x-forwarded-for']?.toString().split(',')[0]?.trim()
+      ?? req.socket.remoteAddress ?? '';
+    const ipHash = crypto.createHash('sha256').update(ip).digest('hex').slice(0, 16);
+
+    const { token, refresh, expiresIn } = await this.auth.login(dto.email, dto.password, ipHash);
+
+    res.cookie('refresh', refresh, {
+      httpOnly: true,
+      secure: process.env.NODE_ENV === 'production',
+      sameSite: 'lax',
+      maxAge: 7 * 24 * 60 * 60 * 1000,
+      path: '/auth/refresh',
+    });
+
+    return { token, expiresIn };
+  }
+
+  @Post('logout')
+  @HttpCode(204)
+  @UseGuards(JwtAuthGuard)
+  async logout(@Req() req: any, @Res({ passthrough: true }) res: Response) {
+    await this.auth.logout(req.user.id);
+    res.clearCookie('refresh', { path: '/auth/refresh' });
+  }
+}
+```
+
+```typescript
+// File: src/auth/auth.module.ts
+import { Module } from '@nestjs/common';
+import { JwtModule } from '@nestjs/jwt';
+import { PassportModule } from '@nestjs/passport';
+import { ThrottlerModule } from '@nestjs/throttler';
+import { AuthService } from './auth.service';
+import { AuthController } from './auth.controller';
+import { JwtStrategy } from './strategies/jwt.strategy';
+
+@Module({
+  imports: [
+    PassportModule,
+    JwtModule.register({
+      secret: process.env.JWT_SECRET,
+      signOptions: { expiresIn: '15m', issuer: '<placeholder-domain>' },
+    }),
+    ThrottlerModule.forRoot([{ ttl: 60_000, limit: 100 }]),
+  ],
+  providers: [AuthService, JwtStrategy],
+  controllers: [AuthController],
+})
+export class AuthModule {}
+```
+
+## AVV / DPA
+
+- Datenbank (User-Tabelle, Login-Attempts) — AVV mit EU-Region
+- Mailer (E-Mail-Verifizierung, Password-Reset) — AVV
+- Optional: SSO-Provider (Auth0 EU, Keycloak self-host) — AVV mit Drittland-TIA
+
+## DSE-Wording-Vorlage
+
+```markdown
+### Login und Authentifizierung
+
+Bei der Anmeldung verarbeiten wir folgende Daten:
+
+- E-Mail-Adresse (zur Identifizierung)
+- Passwort (gespeichert als Argon2-Hash, niemals im Klartext)
+- Hash der IP-Adresse (zur Brute-Force-Erkennung)
+- User-Agent (zur Erkennung verdaechtiger Aktivitaeten)
+- Login-Zeitpunkt
+
+**Rechtsgrundlage:** Art. 6 Abs. 1 lit. b DSGVO (Vertragserfuellung) +
+Art. 6 Abs. 1 lit. f DSGVO (Sicherheit, berechtigtes Interesse).
+**Speicherdauer:**
+- User-Account: bis Loeschung durch Sie
+- Login-Attempts (anonymisiert): 90 Tage
+- Session-Cookies: 7 Tage (Refresh-Token), 15 Minuten (Access-Token)
+```
+
+## Verify-Commands (Live-Probe)
+
+```bash
+# 1. Login mit falschen Credentials = Generic Error
+curl -X POST https://<placeholder-domain>/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"email":"nonexistent@example.com","password":"WRONG"}' -i
+# Erwartung: 401 mit "Login-Daten ungueltig" (NICHT "User not found")
+
+# 2. Rate-Limit nach 5 Versuchen
+for i in {1..6}; do
+  curl -X POST https://<placeholder-domain>/auth/login \
+    -H "Content-Type: application/json" \
+    -d '{"email":"test@example.com","password":"wrong"}' -s -o /dev/null -w "%{http_code}\n"
+done
+# Erwartung: 401, 401, 401, 401, 401, 429
+
+# 3. Refresh-Cookie HttpOnly + Secure
+curl -X POST https://<placeholder-domain>/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"email":"<placeholder-user>","password":"<placeholder-password>"}' -i \
+  | grep -i "set-cookie:.*refresh"
+# Erwartung: HttpOnly; Secure; SameSite=Lax
+
+# 4. JWT-Expiry funktioniert
+# Token decoden, exp-Feld pruefen → max +900 Sekunden
+```
+
+## Cross-References
+
+- AEGIS-Scanner: `auth-flow-checker.ts`, `jwt-config-checker.ts`, `bcrypt-argon-checker.ts`, `rate-limit-checker.ts`
+- Skill-Reference: `references/dsgvo.md` Art. 32 (Sicherheit)
+- BSI-Grundschutz: ORP.4 Identitaets- und Berechtigungsmanagement
+- Audit-Pattern: `references/audit-patterns.md` Phase 9 (Auth-Audit)

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

@@ -0,0 +1,255 @@
+---
+license: MIT (snippet)
+provider: NestJS (Open-Source)
+last-checked: 2026-05-05
+purpose: NestJS Guards-Pattern fuer Consent-Validation auf Controller-Ebene.
+---
+
+# NestJS — Consent-Guard Pattern
+
+## Trigger / Detection
+
+Repo enthaelt:
+- `@nestjs/core`, `@nestjs/common` in `package.json`
+- `*.module.ts`, `*.controller.ts`, `*.service.ts` Dateien
+- `@UseGuards(...)` Decorator-Verwendung
+- Optional: `@nestjs/passport`, `@nestjs/jwt`, `cookie-parser` Middleware
+
+## Default-Verhalten (was passiert ohne Konfiguration)
+
+- NestJS hat keinen Default-Consent-Guard
+- Tracker-Module global im `AppModule` registriert → laufen vor Consent
+- `@Body()` ohne `ValidationPipe` akzeptiert beliebige Payloads
+- Cookies-Read via `@Req()` ohne Type-Safety → silent failures
+
+## Compliance-Risiken
+
+| Risiko | Norm | Severity | Fix |
+|---|---|---|---|
+| Tracker-Service auto-instantiiert | § 25 TDDDG | KRITISCH | Lazy-Module nach Consent-Event |
+| Endpoints ohne Consent-Guard | § 25 TDDDG | HOCH | `@UseGuards(ConsentGuard)` |
+| Body unvalidated | Art. 25 DSGVO | MITTEL | Global `ValidationPipe` |
+| Cookie-Parse-Errors verschluckt | DSGVO Art. 7 (Nachweis) | MITTEL | Custom Decorator mit Validation |
+| Drittland-Tracker direkt eingebunden | Art. 44 DSGVO | KRITISCH | EU-Provider + AVV |
+
+## Code-Pattern (sanitized)
+
+```typescript
+// File: src/consent/consent.types.ts
+export type Consent = {
+  necessary: true;
+  analytics: boolean;
+  marketing: boolean;
+  timestamp?: string;
+  version: string;
+};
+
+export const DEFAULT_CONSENT: Consent = {
+  necessary: true,
+  analytics: false,
+  marketing: false,
+  version: '1.0',
+};
+```
+
+```typescript
+// File: src/consent/consent.decorator.ts
+import { createParamDecorator, ExecutionContext } from '@nestjs/common';
+import type { Request } from 'express';
+import { DEFAULT_CONSENT, Consent } from './consent.types';
+
+export const UserConsent = createParamDecorator(
+  (_data: unknown, ctx: ExecutionContext): Consent => {
+    const req = ctx.switchToHttp().getRequest<Request>();
+    const raw = req.cookies?.['cookie-consent'];
+    if (!raw) return { ...DEFAULT_CONSENT };
+    try {
+      const parsed = JSON.parse(raw);
+      return { ...DEFAULT_CONSENT, ...parsed };
+    } catch {
+      return { ...DEFAULT_CONSENT };
+    }
+  },
+);
+```
+
+```typescript
+// File: src/consent/consent.guard.ts
+import { CanActivate, ExecutionContext, Injectable, SetMetadata } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { DEFAULT_CONSENT, Consent } from './consent.types';
+
+export const REQUIRES_CONSENT = 'requiresConsent';
+export const RequiresConsent = (category: keyof Omit<Consent, 'necessary' | 'timestamp' | 'version'>) =>
+  SetMetadata(REQUIRES_CONSENT, category);
+
+@Injectable()
+export class ConsentGuard implements CanActivate {
+  constructor(private reflector: Reflector) {}
+
+  canActivate(ctx: ExecutionContext): boolean {
+    const required = this.reflector.get<keyof Consent>(REQUIRES_CONSENT, ctx.getHandler());
+    if (!required) return true;
+
+    const req = ctx.switchToHttp().getRequest();
+    const raw = req.cookies?.['cookie-consent'];
+    if (!raw) return false;
+    try {
+      const consent = { ...DEFAULT_CONSENT, ...JSON.parse(raw) };
+      return consent[required] === true;
+    } catch {
+      return false;
+    }
+  }
+}
+```
+
+```typescript
+// File: src/consent/consent.controller.ts
+import { Body, Controller, Post, Res, HttpCode, BadRequestException } from '@nestjs/common';
+import { Response } from 'express';
+import { IsBoolean, IsOptional } from 'class-validator';
+import { ConsentService } from './consent.service';
+
+class ConsentDto {
+  @IsBoolean() analytics!: boolean;
+  @IsBoolean() marketing!: boolean;
+  @IsOptional() @IsBoolean() necessary?: boolean;
+}
+
+@Controller('api/consent-log')
+export class ConsentController {
+  constructor(private readonly consentService: ConsentService) {}
+
+  @Post()
+  @HttpCode(204)
+  async logConsent(@Body() dto: ConsentDto, @Res({ passthrough: true }) res: Response) {
+    const final = {
+      necessary: true as const,
+      analytics: dto.analytics,
+      marketing: dto.marketing,
+      timestamp: new Date().toISOString(),
+      version: '1.0' as const,
+    };
+
+    await this.consentService.logConsent(final, res.req);
+
+    res.cookie('cookie-consent', JSON.stringify(final), {
+      httpOnly: false,
+      secure: process.env.NODE_ENV === 'production',
+      sameSite: 'lax',
+      maxAge: 12 * 30 * 24 * 60 * 60 * 1000,
+      path: '/',
+    });
+  }
+}
+```
+
+```typescript
+// File: src/consent/consent.service.ts
+import { Injectable } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { Repository } from 'typeorm';
+import * as crypto from 'crypto';
+import { ConsentLog } from './consent-log.entity';
+import { Consent } from './consent.types';
+
+@Injectable()
+export class ConsentService {
+  constructor(
+    @InjectRepository(ConsentLog) private readonly repo: Repository<ConsentLog>,
+  ) {}
+
+  async logConsent(consent: Consent, req: any): Promise<void> {
+    const ip = req.headers['x-forwarded-for']?.toString().split(',')[0]?.trim()
+      ?? req.socket?.remoteAddress
+      ?? '';
+    const ipHash = crypto
+      .createHash('sha256')
+      .update(ip + (process.env.IP_HASH_SALT ?? ''))
+      .digest('hex')
+      .slice(0, 16);
+
+    await this.repo.save({
+      ipHash,
+      userAgent: (req.headers['user-agent'] ?? '').slice(0, 200),
+      consent: JSON.stringify(consent),
+      timestamp: new Date(),
+    });
+  }
+}
+```
+
+```typescript
+// File: src/tracking/tracking.controller.ts (Beispiel-Verwendung)
+import { Body, Controller, Post, UseGuards, HttpCode } from '@nestjs/common';
+import { ConsentGuard, RequiresConsent } from '../consent/consent.guard';
+
+@Controller('api/track')
+export class TrackingController {
+  @Post()
+  @HttpCode(204)
+  @UseGuards(ConsentGuard)
+  @RequiresConsent('analytics')
+  async track(@Body() event: any) {
+    // Wird nur ausgefuehrt wenn analytics: true im Cookie
+  }
+}
+```
+
+## AVV / DPA
+
+- Datenbank (TypeORM/Prisma → Postgres-EU) — AVV
+- Hosting-Provider — Art. 28 DSGVO
+- Logging-Service (sofern extern) — AVV
+- Tracker-Forward-Provider — AVV mit EU-Hosting
+
+## DSE-Wording-Vorlage
+
+```markdown
+### Consent-Logging
+
+Wir protokollieren Ihre Cookie-Einwilligung serverseitig zur Erfuellung der
+Nachweispflicht (Art. 7 Abs. 1 DSGVO). Protokolliert werden:
+
+- Hash Ihrer IP-Adresse (SHA-256 mit Salt, gekuerzt)
+- User-Agent (Browser-String, max. 200 Zeichen)
+- Zeitstempel
+- Gewaehlte Cookie-Kategorien
+
+**Speicherdauer:** 6 Jahre (Verjaehrungsfrist Schadensersatz-Anspruch
+DSGVO).
+**Zweck:** Beweisfunktion bei Streitigkeiten ueber Einwilligung.
+**Keine Personalisierung:** Das Log ist nicht mit Ihrem Account verknuepft.
+```
+
+## Verify-Commands (Live-Probe)
+
+```bash
+# 1. Tracking-Endpoint blockt ohne Consent-Cookie
+curl -X POST https://<placeholder-domain>/api/track \
+  -H "Content-Type: application/json" -d '{"event":"pageview"}' -i
+# Erwartung: 403 (ConsentGuard refuses)
+
+# 2. Mit Consent-Cookie: 204
+curl -X POST https://<placeholder-domain>/api/track \
+  -H "Content-Type: application/json" \
+  -H 'Cookie: cookie-consent=%7B%22analytics%22%3Atrue%7D' \
+  -d '{"event":"pageview"}' -i
+# Erwartung: 204
+
+# 3. Consent-Log persistiert
+# DB-Query: SELECT COUNT(*) FROM consent_log WHERE timestamp > now() - interval '1 hour';
+
+# 4. Validation-Pipe blockt invalid Payload
+curl -X POST https://<placeholder-domain>/api/consent-log \
+  -H "Content-Type: application/json" -d '{"analytics":"yes"}' -i
+# Erwartung: 400 mit ValidationError
+```
+
+## Cross-References
+
+- AEGIS-Scanner: `consent-flow-checker.ts`, `nestjs-guard-checker.ts`, `cookie-flags-checker.ts`
+- Skill-Reference: `references/dsgvo.md` § 25 TDDDG, Art. 7 DSGVO
+- BGH-Rechtsprechung: `references/bgh-urteile.md` BGH I ZR 7/16
+- Audit-Pattern: `references/audit-patterns.md` Phase 2 (Cookie-Audit)