From d24854483fecd21dec2fc1c425f7cc108d53fd64 Mon Sep 17 00:00:00 2001 From: ValueOn AG Date: Sat, 23 Aug 2025 01:48:01 +0200 Subject: [PATCH] updates --- poweron/appdoc/app_keymanagement.html | 462 ++++++++++++++++++++++++++ poweron/appdoc/doc_system.html | 62 ++-- 2 files changed, 481 insertions(+), 43 deletions(-) create mode 100644 poweron/appdoc/app_keymanagement.html 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:

+
    +
  1. Key-Format erkennen: DEV_ENC: oder PROD_ENC: Prefix parsen
    2. +
  2. Master Key laden: Entsprechenden Master Key aus Storage laden
    3. +
  3. Environment-Check: Sicherstellen, dass Key in richtiger Umgebung entschlüsselt wird
    4. +
  4. Decryption: Key mit Master Key entschlüsseln
    5. +
  5. Metadata parsen: Limits und Tracking-Informationen extrahieren
    6. +
+
+ +

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

+
+

Das Encryption Tool bietet:

+
    +
  • Lokale Nutzung: Funktioniert ohne Internetzugang
    • +
  • Automatische File-Auswahl: Repository, Instanz, Key-Name auswählen
    • +
  • Copy/Paste Integration: Key direkt einfügen und verschlüsseln
    • +
  • Automatisches Speichern: Verschlüsselter Key wird im richtigen File gespeichert
    • +
  • Environment-Aware: Erkennt automatisch ob DEV oder PROD
    • +
+
+ +

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:

+
    +
  1. File Loading: config.ini und .env Files laden
    2. +
  2. Environment Detection: Dev/Prod automatisch erkennen
    3. +
  3. Master Key Loading: Entsprechenden Master Key laden
    4. +
  4. Key Scanning: Alle verschlüsselten Keys identifizieren
    5. +
  5. Decryption: Keys mit Master Key entschlüsseln
    6. +
  6. Metadata Parsing: Limits und Tracking-Informationen extrahieren
    7. +
  7. Variable Setup: Entschlüsselte Keys als Variablen verfügbar machen
    8. +
+
+ +

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:

+
    +
  1. Code auf GitHub main: Trigger für automatisches Deployment
    2. +
  2. Key-Validierung: Alle Keys werden auf Gültigkeit geprüft
    3. +
  3. Environment-Matching: Richtige .env Files werden für Ziel-Umgebung geladen
    4. +
  4. Key-Decryption: Keys werden in Ziel-Umgebung entschlüsselt
    5. +
  5. App-Start: Anwendung startet mit entschlüsselten Keys
    6. +
+
+
+ +
+

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:

+
    +
  1. Master Key generieren: Lokalen Development Master Key erstellen
    2. +
  2. Tool installieren: Encryption Tool lokal installieren
    3. +
  3. Repository registrieren: Lokale Repositories im Tool registrieren
    4. +
  4. Test-Key erstellen: Ersten verschlüsselten Key erstellen
    5. +
+
+ +

7.2 Täglicher Workflow

+
+

Entwickler-Alltag:

+
    +
  1. Neuen Key benötigen: API Key für neuen Customer
    2. +
  2. Tool starten: Encryption Tool öffnen
    3. +
  3. Kontext wählen: Repository, Instanz, Key-Name auswählen
    4. +
  4. Key einfügen: Plain-Text Key per Copy/Paste einfügen
    5. +
  5. Automatische Verschlüsselung: Tool verschlüsselt und speichert
    6. +
  6. Code verwenden: getConfig() kann Key sofort nutzen
    7. +
+
+ +

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

+ +
+

9.1 Encryption Tool

+
    +
  • Zweck: Neue Keys verschlüsseln und in richtige Files speichern
    • +
  • Input: Repository, Instanz, Key-Name, Plain-Text Key
    • +
  • Output: Verschlüsselter Key im richtigen .env File
    • +
  • Lokale Nutzung: Funktioniert ohne Internetzugang
    • +
+
+ +
+

9.2 getConfig() Funktion

+
    +
  • Zweck: Config Files laden und Keys entschlüsseln
    • +
  • Input: config.ini und .env Files
    • +
  • Output: Entschlüsselte Keys als Variablen
    • +
  • Integration: Wird beim App-Start aufgerufen
    • +
+
+ +
+

9.3 Master Key Storage

+
    +
  • Development: Lokal auf Entwickler-Maschine
    • +
  • Production: Auf eigener V-Domäne
    • +
  • Keine Provider: Vollständige Kontrolle
    • +
  • Environment-Separation: Absolute Trennung Dev/Prod
    • +
+
+
+ + \ No newline at end of file diff --git a/poweron/appdoc/doc_system.html b/poweron/appdoc/doc_system.html index fcdb33e..8fdd58d 100644 --- a/poweron/appdoc/doc_system.html +++ b/poweron/appdoc/doc_system.html @@ -307,19 +307,19 @@ class UserConnection(BaseModel, ModelMixin):
⚠️ 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:

+ +

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