# Portability: UNIVERSAL
# Last validated: 2026-05-17
# Next review: 2027-05-17

--------------------------------------------------------------------------------
SECRETS
--------------------------------------------------------------------------------

HANDLER NAME
------------

SECRETS HANDLER (SQ076) — Management of API keys, passwords and sensitive
Credentials with file authoritative matching between file system and database.


DESCRIPTION
------------

The Secrets Handler provides secure storage and query of sensitive data.
All secrets are stored in the database (bach.db:secrets) and optionally in a
saved to local JSON file. The authority lies with the file: missing that
file, all secrets are deleted from the DB (ENT-44).

Storage location secrets file: ~/.bach/bach_secrets.json (configurable via
system_config with the key 'secrets_file_path').

Each secret can be given a description, category and timestamp.


OPERATIONS
-----------

bach secrets list
    Shows all saved secrets. The value is for security reasons
    not displayed, only key, category, description, source and creation time
    time. Sorting by category and key.

bach secrets get <key>
    Gets the value of a specific Secret and displays Key, Description
    and value. Error if Secret does not exist.

bach secrets set <key> <value> [<description>] [<category>]
    Saves or updates a secret. The value is both in the DB
    as well as written to the Secrets file (bi-directional sync).
    Parameters:
        <key>: Unique identifier (e.g. 'telegram_api_key')
        <value>: The secret value
        <description> (optional): description, default: empty
        <category> (optional): Category, default: 'general'

bach secrets delete <key>
    Deletes a secret from the DB and file. Error if Secret does not exist.

bach secrets sync
    Manual comparison from file to database (File -> DB).
    File authority: If the file is missing, the DB is emptied.
    Entries with prefix '_example_' are skipped.


EXAMPLES
---------

Save new secret (with category):
    bach secrets set telegram_api_key "12345:ABCDEFG..." "Telegram Bot" "api"

Retrieve secret:
    bach secrets get telegram_api_key

List all secrets:
    bach secrets list

Delete secret:
    bach secrets delete telegram_api_key

Manual sync after file change:
    bach secrets sync

Override the secrets file (USB stick):
    bach settings set secrets_file_path /media/usb/my_secrets.json


FILES
-------

hub/secrets_handler.py
    Handler implementation CLI entry point: handle_secrets_command().
    Class SecretsHandler manages DB connection and file sync.

data/bach.db
    SQLite database with table 'secrets' (key, value, description, category,
    source, created_at, updated_at, id).

~/.bach/bach_secrets.json
    User-side JSON file with all secrets (structure: meta, secrets,
    notes). Auto-generated by sync. Manual edits are retained.

core/database.py
    Database connection utility (fallback to direct sqlite3 connection,
    if import fails).


SEE ALSO
----------

bach settings — Konfiguration von system_config Eintraegen
core/database — database architecture
BACH-KONZEPTE/ENT-44 — File-authoritarian synchronization
