diff --git a/poweron/appdoc/app_keymanagement.html b/poweron/appdoc/app_keymanagement.html
new file mode 100644
index 0000000..d86019c
--- /dev/null
+++ b/poweron/appdoc/app_keymanagement.html
@@ -0,0 +1,462 @@
+
+
+
+
+
+ Key Management - Praktische Umsetzung & Werkzeuge
+
+
+
+ Key Management - Praktische Umsetzung & Werkzeuge
+
+
+
1. Kern-Anforderungen & Prinzipien
+
+
+
🔒 Grundprinzipien
+
+ - Keine Plain-Text Keys im Code: Keys werden nur verschlüsselt gespeichert
+ - Lokale Entwicklung: Keys können lokal ohne Internetzugang entschlüsselt werden
+ - Absolute Dev/Prod Trennung: Keine Überschneidung zwischen Development und Production
+ - Minimaler Aufwand: Neue Keys direkt im Code erfassen können
+ - Keine Provider-Abhängigkeit: Master Keys werden bei uns gespeichert
+
+
+
+
1.1 File-Struktur
+
+ repository/
+ ├── config.ini # Generische Konfiguration
+ ├── .env # Instanz-spezifische Umgebungsvariablen
+ ├── .env.development # Development-spezifische Keys
+ ├── .env.production # Production-spezifische Keys
+ └── src/
+ └── utils/
+ └── config.py # getConfig() Funktion
+
+
+
1.2 Key-Format
+
+
Verschlüsselte Keys haben folgendes Format:
+
+ - Development Keys:
DEV_ENC:eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+ - Production Keys:
PROD_ENC:eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+ - Metadata:
PROD_ENC:encrypted_value|LIMIT:1000/hour|TRACK:true
+
+
+
+
2. Master Key Management
+
+
2.1 Master Key Storage - Eigene V-Domäne
+
+
Master Keys werden bei uns gespeichert:
+
+ - Development Master Key: Lokal auf Entwickler-Maschine (~/.keytool/dev-master.key)
+ - Production Master Key: Auf eigener V-Domäne (z.B. keys.internal.company.com)
+ - Keine Cloud-Provider: Vollständige Kontrolle über Key-Storage
+ - HSM-Backed: Hardware Security Module für Production Keys
+
+
+
+
2.2 Master Key Nutzung für Decryption
+
+
Workflow für Key-Decryption:
+
+ - Key-Format erkennen: DEV_ENC: oder PROD_ENC: Prefix parsen
+ - Master Key laden: Entsprechenden Master Key aus Storage laden
+ - Environment-Check: Sicherstellen, dass Key in richtiger Umgebung entschlüsselt wird
+ - Decryption: Key mit Master Key entschlüsseln
+ - Metadata parsen: Limits und Tracking-Informationen extrahieren
+
+
+
+
2.3 Environment-Separation
+
+
🔐 Strikte Trennung:
+
+ - Development: Kann nur DEV_ENC: Keys entschlüsseln
+ - Production: Kann nur PROD_ENC: Keys entschlüsseln
+ - Cross-Decryption: Wird blockiert - Security Feature
+ - Automatische Erkennung: Environment wird automatisch erkannt
+
+
+
+
3. Encryption Tool - Lokale Nutzung
+
+
3.1 Tool-Funktionalität
+
+
+
3.2 Tool-Workflow
+
+
Schritt 1: Repository & Instanz auswählen
+
Tool zeigt verfügbare Repositories und deren Instanzen an
+
+
+
+
Schritt 2: Key-Name definieren
+
Neuen Key-Namen eingeben (z.B. API_KEY_CUSTOMER_001)
+
+
+
+
Schritt 3: Plain-Text Key einfügen
+
Key per Copy/Paste einfügen
+
+
+
+
Schritt 4: Automatische Verschlüsselung
+
Tool verschlüsselt Key und speichert ihn im richtigen File
+
+
+
3.3 Tool-Integration
+
+
Integration in den Entwickler-Workflow:
+
+ - Command Line Tool:
keytool encrypt --repo=repo-name --instance=dev --key=API_KEY --value=plaintext
+ - IDE Integration: Plugin für VS Code/IntelliJ
+ - Git Hooks: Automatische Validierung vor Commit
+ - CI/CD Integration: Automatische Key-Validierung bei Deployment
+
+
+
+
4. getConfig() Funktion - Praktische Umsetzung
+
+
4.1 Funktionalität
+
+
Die getConfig() Funktion:
+
+ - Config Loading: Lädt config.ini und .env Files beim App-Start
+ - Automatische Decryption: Entschlüsselt alle verschlüsselten Keys
+ - Environment Detection: Erkennt automatisch Development/Production
+ - Variable Access: Stellt entschlüsselte Keys als Variablen zur Verfügung
+ - Metadata Handling: Verarbeitet Limits und Tracking-Informationen
+
+
+
+
4.2 Implementierungs-Logik
+
+
getConfig() Workflow:
+
+ - File Loading: config.ini und .env Files laden
+ - Environment Detection: Dev/Prod automatisch erkennen
+ - Master Key Loading: Entsprechenden Master Key laden
+ - Key Scanning: Alle verschlüsselten Keys identifizieren
+ - Decryption: Keys mit Master Key entschlüsseln
+ - Metadata Parsing: Limits und Tracking-Informationen extrahieren
+ - Variable Setup: Entschlüsselte Keys als Variablen verfügbar machen
+
+
+
+
4.3 Usage im Code
+
+# In der Anwendung
+from utils.config import getConfig
+
+config = getConfig()
+
+# Zugriff auf entschlüsselte Keys
+api_key = config.get('API_KEY_CUSTOMER_001')
+db_password = config.get('DB_PASSWORD')
+
+# Mit Customer-Context
+customer_api_key = config.get('API_KEY', customer_id='CUSTOMER_001')
+
+
+
5. Repository & Instanz Management
+
+
5.1 Multi-Repository Struktur
+
+
Verwaltung vieler Repositories:
+
+ - Zentrale Registry: Alle Repositories und Instanzen werden zentral verwaltet
+ - Instanz-spezifische .env Files: Jede Instanz hat eigene .env Datei
+ - Automatische Synchronisation: Keys werden automatisch zwischen Repositories synchronisiert
+ - Versionierung: Alle Key-Änderungen werden versioniert
+
+
+
+
5.2 Instanz-spezifische Konfiguration
+
+ repository/
+ ├── .env.development # Development Keys
+ ├── .env.staging # Staging Keys
+ ├── .env.production # Production Keys
+ └── .env.local # Lokale Override Keys
+
+
+
5.3 Deployment-Integration
+
+
Automatisches Deployment:
+
+ - Code auf GitHub main: Trigger für automatisches Deployment
+ - Key-Validierung: Alle Keys werden auf Gültigkeit geprüft
+ - Environment-Matching: Richtige .env Files werden für Ziel-Umgebung geladen
+ - Key-Decryption: Keys werden in Ziel-Umgebung entschlüsselt
+ - App-Start: Anwendung startet mit entschlüsselten Keys
+
+
+
+
6. Sicherheits-Features
+
+
6.1 Key-Validierung
+
+
🔒 Automatische Sicherheits-Checks:
+
+ - Plain-Text Detection: Blockiert Commits mit unverschlüsselten Keys
+ - Environment-Mismatch: Verhindert PROD Keys in DEV Umgebung
+ - Key-Rotation: Automatische Warnung bei veralteten Keys
+ - Usage-Tracking: Überwachung von Key-Nutzung (nur Production)
+
+
+
+
6.2 Git Integration
+
+
Git Hooks und CI/CD:
+
+ - Pre-commit Hook: Prüft auf Plain-Text Keys
+ - Pre-push Hook: Validiert Key-Format und Environment
+ - CI/CD Pipeline: Automatische Key-Validierung bei jedem Build
+ - Deployment Check: Verhindert Deployment mit ungültigen Keys
+
+
+
7. Praktische Implementierung
+
+
7.1 Tool-Setup
+
+
Entwickler-Setup:
+
+ - Master Key generieren: Lokalen Development Master Key erstellen
+ - Tool installieren: Encryption Tool lokal installieren
+ - Repository registrieren: Lokale Repositories im Tool registrieren
+ - Test-Key erstellen: Ersten verschlüsselten Key erstellen
+
+
+
+
7.2 Täglicher Workflow
+
+
Entwickler-Alltag:
+
+ - Neuen Key benötigen: API Key für neuen Customer
+ - Tool starten: Encryption Tool öffnen
+ - Kontext wählen: Repository, Instanz, Key-Name auswählen
+ - Key einfügen: Plain-Text Key per Copy/Paste einfügen
+ - Automatische Verschlüsselung: Tool verschlüsselt und speichert
+ - Code verwenden: getConfig() kann Key sofort nutzen
+
+
+
+
7.3 Key-Rotation
+
+
✨ Einfache Key-Rotation:
+
+ - Automatische Erkennung: Tool erkennt Keys die rotiert werden müssen
+ - One-Command Rotation: Alle Keys einer Instanz mit einem Befehl rotieren
+ - Grace Period: Alte Keys bleiben 24h gültig für Übergang
+ - Automatische Benachrichtigung: Team wird über Rotation informiert
+
+
+
+
8. Monitoring & Alerts
+
+
8.1 Key-Monitoring
+
+
Überwachung der Keys:
+
+ - Key-Age: Tage bis zur Rotation
+ - Usage-Patterns: Wie oft werden Keys verwendet
+ - Environment-Mismatches: PROD Keys in DEV Umgebung
+ - Plain-Text Detection: Unverschlüsselte Keys im Code
+
+
+
+
8.2 Alert-System
+
+
Automatische Benachrichtigungen:
+
+ - Rotation Due: Key muss in 7 Tagen rotiert werden
+ - Security Violation: PROD Key in DEV Umgebung
+ - Plain-Text Alert: Unverschlüsselter Key im Code gefunden
+ - Usage Anomaly: Ungewöhnliche Key-Nutzung
+
+
+
+
9. Zusammenfassung der Werkzeuge
+
+
+
+
+
+
+
⚠️ Critical Rule: All timestamp fields MUST include "UTC timestamp in seconds" in their description
- for the automatic conversion system to work correctly.
+ for consistency and documentation purposes.
- 1.6 Automatic Timestamp Conversion
+ 1.6 Direct Float Storage
- The system automatically converts timestamp fields using the ModelMixin.to_dict() method:
+ The system now stores all timestamp fields directly as float values in the database:
def to_dict(self) -> Dict[str, Any]:
"""
Convert a Pydantic model to a dictionary.
Handles both Pydantic v1 and v2.
- Properly serializes datetime fields to ISO format strings.
+ All timestamp fields remain as float values.
Returns:
Dict[str, Any]: Dictionary representation of the model
@@ -330,44 +330,20 @@ def to_dict(self) -> Dict[str, Any]:
else:
data: Dict[str, Any] = self.dict() # Pydantic v1
- # Convert datetime fields to ISO format strings
- for key, value in data.items():
- if isinstance(value, datetime):
- data[key] = value.isoformat()
- elif isinstance(value, (int, float)) and self._is_timestamp_field(key):
- # Handle timestamp fields based on field metadata
- try:
- data[key] = datetime.fromtimestamp(value).isoformat()
- except (ValueError, TypeError):
- # If conversion fails, keep the original value
- pass
-
- return data
-
-def _is_timestamp_field(self, field_name: str) -> bool:
- """
- Check if a field is a timestamp field based on field metadata.
- Looks for 'UTC timestamp' in the field description.
- """
- try:
- # Get field info from Pydantic model
- if hasattr(self, 'model_fields'):
- # Pydantic v2
- field_info = self.model_fields.get(field_name)
- if field_info and field_info.description:
- return 'UTC timestamp' in field_info.description
- elif hasattr(self, '__fields__'):
- # Pydantic v1
- field_info = self.__fields__.get(field_name)
- if field_info and field_info.field_info and field_info.field_info.description:
- return 'UTC timestamp' in field_info.field_info.description
- except Exception:
- pass
+ # All fields (including timestamps) remain in their original format
+ # No conversions needed - timestamps are already float
- # Fallback: return False for safety
- return False
+ return data
+ Key Benefits:
+
+ - No unnecessary conversions between float and string
+ - Direct database storage as float values
+ - Consistent data types across the entire system
+ - Better performance without string parsing
+
+
1.7 Utility Functions
Backend Utilities (Python)
@@ -447,7 +423,7 @@ def migrate_timestamp_field(value):
| Backend Models |
COMPLETED |
- 11 models, 15 timestamp fields standardized |
+ 11 models, 15 timestamp fields standardized as float |
| Backend APIs |
@@ -460,9 +436,9 @@ def migrate_timestamp_field(value):
All utilities expect float timestamps |
- | Database Migration |
- NOT REQUIRED |
- Database will be cleaned before testing |
+ Database Storage |
+ COMPLETED |
+ All timestamps stored as float (no string conversion) |
| Testing & Validation |