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

--------------------------------------------------------------------------------
SECRETOS
--------------------------------------------------------------------------------

NOMBRE DEL MANEJADOR
------------

SECRETOS MANEJADOR (SQ076) — Gestión de claves API, contraseñas y datos confidenciales
Credenciales con coincidencia autorizada de archivos entre el sistema de archivos y la base de datos.


DESCRIPCIÓN
------------

El Secrets Handler proporciona almacenamiento seguro y consulta de datos confidenciales.
Todos los secretos se almacenan en la base de datos (bach.db:secrets) y opcionalmente en un
guardado en un archivo JSON local. La autoridad está en el expediente: falta eso
archivo, todos los secretos se eliminan de la base de datos (ENT-44).

Archivo de secretos de ubicación de almacenamiento: ~/.bach/bach_secrets.json (configurable a través de
system_config con la clave 'secrets_file_path').

A cada secreto se le puede dar una descripción, categoría y marca de tiempo.


OPERACIONES
-----------

bach secrets list
    Muestra todos los secretos guardados. El valor es por razones de seguridad.
    no se muestra, solo clave, categoría, descripción, fuente y hora de creación
    tiempo. Ordenando por categoría y clave.

bach secrets get <key>
    Obtiene el valor de un secreto específico y muestra clave y descripción.
    y valor. Error si el secreto no existe.

bach secrets set <key> <value> [<description>] [<category>]
    Guarda o actualiza un secreto. El valor está ambos en la base de datos.
    así como escrito en el archivo Secrets (sincronización bidireccional).
    Parámetros:
        <key>: Identificador único (por ejemplo, 'telegram_api_key')
        <valor>: El valor secreto
        <descripción> (opcional): descripción, predeterminado: vacío
        <categoría> (opcional): Categoría, predeterminado: 'general'

bach secrets delete <key>
    Elimina un secreto de la base de datos y el archivo. Error si el secreto no existe.

bach secrets sync
    Comparación manual de archivo a base de datos (Archivo -> DB).
    Autoridad del archivo: si falta el archivo, se vacía la base de datos.
    Las entradas con el prefijo '_example_' se omiten.


EJEMPLOS
---------

Guardar nuevo secreto (con categoría):
    bach secrets set telegram_api_key "12345:ABCDEFG..." "Telegram Bot" "api"

Recuperar secreto:
    bach secrets get telegram_api_key

Enumerar todos los secretos:
    bach secrets list

Eliminar secreto:
    bach secrets delete telegram_api_key

Sincronización manual después del cambio de archivo:
    bach secrets sync

Anular el archivo de secretos (memoria USB):
    bach settings set secrets_file_path /media/usb/my_secrets.json


ARCHIVOS
-------

hub/secrets_handler.py
    Punto de entrada CLI de implementación del controlador: handle_secrets_command().
    Class SecretsHandler gestiona la conexión a la base de datos y la sincronización de archivos.

data/bach.db
    Base de datos SQLite con tabla 'secretos' (clave, valor, descripción, categoría,
    fuente, creado_at, actualizado_at, id).

~/.bach/bach_secrets.json
    Archivo JSON del lado del usuario con todos los secretos (estructura: meta, secretos,
    notas). Generado automáticamente por sincronización. Se conservan las ediciones manuales.

core/database.py
    Utilidad de conexión a la base de datos (respaldo a la conexión directa sqlite3,
    si la importación falla).


VER TAMBIÉN
----------

bach settings — Konfiguration von system_config Eintraegen
core/database — arquitectura de base de datos
BACH-KONZEPTE/ENT-44 — Sincronización autoritaria de archivos
