# Portabilität: UNIVERSAL
# Version: 1.0.0
# Zuletzt validiert: 2026-03-04

================================================================================
SECRETS
================================================================================

HANDLER-NAME
============

SECRETS-HANDLER (SQ076) — Verwaltung von API-Keys, Passwörtern und sensiblen
Credentials mit Datei-autoritärem Abgleich zwischen Dateisystem und Datenbank.


BESCHREIBUNG
============

Der Secrets-Handler bietet sichere Speicherung und Abfrage von sensiblen Daten.
Alle Secrets werden in der Datenbank (bach.db:secrets) und optional in einer
lokalen JSON-Datei gespeichert. Die Autorität liegt bei der Datei: Fehlt die
Datei, werden alle Secrets aus der DB gelöscht (ENT-44).

Speicherort Secrets-Datei: ~/.bach/bach_secrets.json (konfigurierbar über
system_config mit dem Schlüssel 'secrets_file_path').

Jedes Secret kann mit Beschreibung, Kategorie und Zeitstempel versehen werden.


OPERATIONEN
===========

bach secrets list
    Zeigt alle gespeicherten Secrets an. Der Wert wird aus Sicherheitsgründen
    nicht angezeigt, nur Key, Kategorie, Beschreibung, Quelle und Erstellungs-
    zeit. Sortierung nach Kategorie und Key.

bach secrets get <key>
    Ruft den Wert eines spezifischen Secret ab und zeigt Key, Beschreibung
    und Wert an. Fehler wenn Secret nicht existiert.

bach secrets set <key> <value> [<description>] [<category>]
    Speichert oder aktualisiert ein Secret. Der Wert wird sowohl in der DB
    als auch in die Secrets-Datei geschrieben (bi-direktionaler Sync).
    Parameter:
        <key>: Eindeutiger Bezeichner (z.B. 'telegram_api_key')
        <value>: Der geheime Wert
        <description> (optional): Beschreibung, Standard: leer
        <category> (optional): Kategorie, Standard: 'general'

bach secrets delete <key>
    Löscht ein Secret aus DB und Datei. Fehler wenn Secret nicht existiert.

bach secrets sync
    Manueller Abgleich von Datei zu Datenbank (Datei -> DB).
    Datei-Autorität: Fehlt die Datei, wird die DB geleert.
    Einträge mit Prefix '_example_' werden übersprungen.


BEISPIELE
=========

Neues Secret speichern (mit Kategorie):
    bach secrets set telegram_api_key "12345:ABCDEFG..." "Telegram Bot" "api"

Secret abrufen:
    bach secrets get telegram_api_key

Alle Secrets auflisten:
    bach secrets list

Secret löschen:
    bach secrets delete telegram_api_key

Manueller Sync nach Datei-Änderung:
    bach secrets sync

Override der Secrets-Datei (USB-Stick):
    bach settings set secrets_file_path /media/usb/my_secrets.json


DATEIEN
=======

hub/secrets_handler.py
    Handler-Implementierung. CLI-Einstiegspunkt: handle_secrets_command().
    Klasse SecretsHandler verwaltet DB-Verbindung und Datei-Sync.

data/bach.db
    SQLite-Datenbank mit Tabelle 'secrets' (key, value, description, category,
    source, created_at, updated_at, id).

~/.bach/bach_secrets.json
    Nutzer-seitige JSON-Datei mit allen Secrets (Struktur: meta, secrets,
    notes). Auto-generiert durch Sync. Manuelle Edits bleiben erhalten.

core/database.py
    Datenbankverbindungs-Utility (Fallback auf direkte sqlite3-Verbindung,
    falls Import fehlschlaegt).


SIEHE AUCH
==========

bach settings — Konfiguration von system_config Einträgen
core/database — Datenbank-Architektur
BACH-KONZEPTE/ENT-44 — Datei-autoritäre Synchronisation
