Initial commit

Author: sknr

.gitignore

@@ -0,0 +1,17 @@
+# IDE specific
+.idea/
+
+### Hugo template
+# Generated files by hugo
+/resources/_gen/
+/assets/jsconfig.json
+hugo_stats.json
+
+# Executable may be added to repository
+hugo.exe
+hugo.darwin
+hugo.linux
+
+# Temporary lock file while building
+/.hugo_build.lock
+

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "themes/hugo-book"]
+	path = themes/hugo-book
+	url = https://github.com/alex-shpak/hugo-book

Makefile

@@ -0,0 +1,20 @@
+DOCKER_IMAGE := hugomods/hugo:exts
+DOCKER_RUN_CMD := docker compose run --rm
+
+all: clean build
+
+up:
+	docker compose up server
+
+down:
+	docker compose down --remove-orphans
+
+build:
+	$(DOCKER_RUN_CMD) server build --minify
+
+clean:
+	rm -rf ./public
+	rm -rf ./resources/_gen
+
+shell:
+	$(DOCKER_RUN_CMD) server /bin/sh

archetypes/default.md

@@ -0,0 +1,5 @@
++++
+date = '{{ .Date }}'
+draft = true
+title = '{{ replace .File.ContentBaseName "-" " " | title }}'
++++

content/de/_index.md

@@ -0,0 +1,26 @@
+---
+bookFlatSection: true
+title: "Secure Webhook Token (SWT) Dokumentation"
+---
+
+# Secure Webhook Token (SWT) Dokumentation
+
+Diese Dokumentation beschreibt die IETF Draft Spezifikation für Secure Webhook Tokens (SWT) basierend auf [`draft-knauer-secure-webhook-token-00`](https://datatracker.ietf.org/doc/draft-knauer-secure-webhook-token/).
+
+Secure Webhook Token (SWT) ist eine spezialisierte Implementierung von JSON Web Tokens (JWT), die für die sichere Autorisierung von Webhook-Anfragen entwickelt wurde.
+
+## Hauptfunktionen
+
+- **Standardisiert**: Basiert auf bewährten JWT-Standards
+- **Sicher**: Integrierte Replay-Schutz und Hash-Validierung  
+- **Flexibel**: Unterstützt verschiedene Übertragungsmethoden
+- **Effizient**: Optimiert für verschiedene Payload-Größen
+
+## Navigation
+
+Diese Dokumentation ist in folgende Bereiche unterteilt:
+
+- **Überblick und Grundlagen**: Einführung in SWT-Konzepte
+- **Spezifikation**: Detaillierte technische Spezifikation
+- **Implementierung**: Praktische Implementierungsbeispiele
+- **Sicherheit**: Sicherheitsrichtlinien und Best Practices

content/de/docs/swt/_index.md

@@ -0,0 +1,6 @@
+---
+weight: 10
+bookFlatSection: false
+bookCollapseSection: false
+title: "SWT"
+---

content/de/docs/swt/fehlerbehandlung.md

@@ -0,0 +1,280 @@
+---
+weight: 30
+title: "Fehlerbehandlung"
+---
+
+# Fehlerbehandlung
+
+## Häufige Validierungsfehler
+
+| Fehler | Ursache | Lösung |
+|--------|---------|--------|
+| `Token expired` | Token ist abgelaufen | Neues Token anfordern |
+| `Invalid signature` | Falscher Schlüssel oder manipuliertes Token | Schlüssel überprüfen |
+| `Hash mismatch` | Payload wurde verändert | Originale Payload verwenden |
+| `Missing claims` | Pflicht-Claims fehlen | Token-Struktur korrigieren |
+| `Token not yet valid` | nbf-Claim liegt in der Zukunft | Clock-Synchronisation prüfen |
+| `Replay attack detected` | JTI bereits verwendet | Neues Token generieren |
+
+## Beispiel-Fehlerbehandlung
+
+```javascript
+app.post('/webhook', (req, res) => {
+  try {
+    const token = req.headers.authorization?.replace('Bearer ', '');
+    const validatedToken = validateSWT(token, req.body, SECRET_KEY);
+    
+    // Webhook verarbeiten
+    processWebhook(validatedToken.webhook, req.body);
+    
+    res.status(200).json({ status: 'success' });
+  } catch (error) {
+    console.error('Webhook-Validierung fehlgeschlagen:', error.message);
+    
+    // Spezifische Fehlerbehandlung
+    if (error.message.includes('expired')) {
+      return res.status(401).json({ 
+        error: 'TOKEN_EXPIRED',
+        message: 'Token ist abgelaufen'
+      });
+    }
+    
+    if (error.message.includes('signature')) {
+      return res.status(401).json({ 
+        error: 'INVALID_SIGNATURE',
+        message: 'Token-Signatur ungültig'
+      });
+    }
+    
+    if (error.message.includes('Hash')) {
+      return res.status(400).json({ 
+        error: 'PAYLOAD_MISMATCH',
+        message: 'Payload wurde verändert'
+      });
+    }
+    
+    // Allgemeiner Fehler
+    res.status(401).json({ 
+      error: 'UNAUTHORIZED', 
+      message: 'Token-Validierung fehlgeschlagen'
+    });
+  }
+});
+```
+
+## Erweiterte Fehlerbehandlung
+
+### Fehlerklassen definieren
+
+```javascript
+class SWTError extends Error {
+  constructor(message, code, statusCode = 401) {
+    super(message);
+    this.name = 'SWTError';
+    this.code = code;
+    this.statusCode = statusCode;
+  }
+}
+
+class TokenExpiredError extends SWTError {
+  constructor() {
+    super('Token ist abgelaufen', 'TOKEN_EXPIRED', 401);
+  }
+}
+
+class InvalidSignatureError extends SWTError {
+  constructor() {
+    super('Token-Signatur ungültig', 'INVALID_SIGNATURE', 401);
+  }
+}
+
+class PayloadMismatchError extends SWTError {
+  constructor() {
+    super('Payload-Hash stimmt nicht überein', 'PAYLOAD_MISMATCH', 400);
+  }
+}
+
+class ReplayAttackError extends SWTError {
+  constructor() {
+    super('Token bereits verwendet', 'REPLAY_ATTACK', 401);
+  }
+}
+```
+
+### Verbesserte Validierungsfunktion
+
+```javascript
+function validateSWT(token, payload, secret) {
+  try {
+    const decoded = jwt.verify(token, secret);
+    
+    // Pflicht-Claims prüfen
+    const requiredClaims = ['webhook', 'iss', 'exp', 'nbf', 'iat', 'jti'];
+    for (const claim of requiredClaims) {
+      if (!decoded[claim]) {
+        throw new SWTError(`Fehlender Pflicht-Claim: ${claim}`, 'MISSING_CLAIM', 400);
+      }
+    }
+    
+    // Zeitvalidierung
+    const now = Math.floor(Date.now() / 1000);
+    if (decoded.exp <= now) {
+      throw new TokenExpiredError();
+    }
+    if (decoded.nbf > now) {
+      throw new SWTError('Token noch nicht gültig', 'TOKEN_NOT_YET_VALID', 401);
+    }
+    
+    // Payload-Hash validieren
+    if (payload && decoded.webhook.hash) {
+      const [algorithm, expectedHash] = decoded.webhook.hash.split(':');
+      const actualHash = crypto.createHash(algorithm)
+                              .update(JSON.stringify(payload))
+                              .digest('hex');
+      
+      if (actualHash !== expectedHash) {
+        throw new PayloadMismatchError();
+      }
+    }
+    
+    return decoded;
+  } catch (error) {
+    if (error instanceof SWTError) {
+      throw error;
+    }
+    
+    if (error.name === 'TokenExpiredError') {
+      throw new TokenExpiredError();
+    }
+    
+    if (error.name === 'JsonWebTokenError') {
+      throw new InvalidSignatureError();
+    }
+    
+    throw new SWTError('Unbekannter Validierungsfehler', 'VALIDATION_ERROR', 500);
+  }
+}
+```
+
+## Logging und Monitoring
+
+### Strukturiertes Logging
+
+```javascript
+const winston = require('winston');
+
+const logger = winston.createLogger({
+  level: 'info',
+  format: winston.format.combine(
+    winston.format.timestamp(),
+    winston.format.errors({ stack: true }),
+    winston.format.json()
+  ),
+  transports: [
+    new winston.transports.File({ filename: 'webhook-errors.log', level: 'error' }),
+    new winston.transports.File({ filename: 'webhook-combined.log' })
+  ]
+});
+
+function logWebhookEvent(event, details, level = 'info') {
+  logger.log({
+    level: level,
+    message: 'Webhook Event',
+    event: event,
+    details: details,
+    timestamp: new Date().toISOString()
+  });
+}
+
+// Verwendung
+try {
+  const validatedToken = validateSWT(token, req.body, SECRET_KEY);
+  logWebhookEvent('webhook_validated', {
+    event: validatedToken.webhook.event,
+    jti: validatedToken.jti,
+    issuer: validatedToken.iss
+  });
+} catch (error) {
+  logWebhookEvent('webhook_validation_failed', {
+    error: error.message,
+    code: error.code,
+    ip: req.ip,
+    userAgent: req.get('User-Agent')
+  }, 'error');
+}
+```
+
+### Metriken und Alerting
+
+```javascript
+const prometheus = require('prom-client');
+
+// Metriken definieren
+const webhookValidationCounter = new prometheus.Counter({
+  name: 'webhook_validation_total',
+  help: 'Total number of webhook validations',
+  labelNames: ['status', 'error_type']
+});
+
+const webhookValidationDuration = new prometheus.Histogram({
+  name: 'webhook_validation_duration_seconds',
+  help: 'Duration of webhook validation',
+  buckets: [0.1, 0.5, 1, 2, 5]
+});
+
+// Metriken verwenden
+app.post('/webhook', async (req, res) => {
+  const startTime = Date.now();
+  
+  try {
+    const validatedToken = validateSWT(token, req.body, SECRET_KEY);
+    
+    webhookValidationCounter.inc({ status: 'success', error_type: 'none' });
+    processWebhook(validatedToken.webhook, req.body);
+    
+    res.status(200).json({ status: 'success' });
+  } catch (error) {
+    webhookValidationCounter.inc({ 
+      status: 'error', 
+      error_type: error.code || 'unknown' 
+    });
+    
+    res.status(error.statusCode || 500).json({
+      error: error.code || 'UNKNOWN_ERROR',
+      message: error.message
+    });
+  } finally {
+    const duration = (Date.now() - startTime) / 1000;
+    webhookValidationDuration.observe(duration);
+  }
+});
+```
+
+## Rate Limiting
+
+```javascript
+const rateLimit = require('express-rate-limit');
+
+const webhookLimiter = rateLimit({
+  windowMs: 15 * 60 * 1000, // 15 Minuten
+  max: 100, // Maximal 100 Requests pro IP
+  message: {
+    error: 'RATE_LIMIT_EXCEEDED',
+    message: 'Zu viele Webhook-Anfragen'
+  },
+  standardHeaders: true,
+  legacyHeaders: false,
+  skip: (req) => {
+    // Authentifizierte Requests weniger limitieren
+    const token = req.headers.authorization?.replace('Bearer ', '');
+    try {
+      jwt.verify(token, SECRET_KEY);
+      return false; // Nicht skippen, aber weniger streng limitieren
+    } catch {
+      return false;
+    }
+  }
+});
+
+app.use('/webhook', webhookLimiter);
+```

content/de/docs/swt/implementations/_index.md

@@ -0,0 +1,29 @@
+---
+weight: 40
+bookFlatSection: false
+bookCollapseSection: false
+bookToc: false
+title: "Implementierungen"
+---
+
+# Implementierungen
+
+{{% hint danger %}}
+**Contribution wanted!**
+
+Wenn du eine Library für eine andere Sprache kennst oder eine erstellt hast, lass es mich wissen und ich trage sie hier ein.
+{{% /hint %}}
+
+Hier ist eine Liste mit Implementierungen in verschiedenen Programmiersprachen.
+
+## Go
+
+- [SecureWebhookToken (SWT)](https://github.com/securewebhooktoken/swt)
+
+## JS
+
+ - ???
+
+## Python
+
+- ???