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

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

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

SECRETS HANDLER (SQ076) — Управление ключами API, паролями и конфиденциальной информацией.
Учетные данные с авторитетным сопоставлением файлов между файловой системой и базой данных.


ОПИСАНИЕ
------------

Обработчик секретов обеспечивает безопасное хранение и запрос конфиденциальных данных.
Все секреты хранятся в базе данных (bach.db:secrets) и, при необходимости, в
сохраняется в локальный файл JSON. Авторитет принадлежит файлу: этого не хватает
файл, все секреты удаляются из базы данных (ENT-44).

Файл секретов места хранения: ~/.bach/bach_secrets.json (настраивается через
system_config с ключом 'secrets_file_path').

Каждому секрету может быть присвоено описание, категория и временная метка.


ОПЕРАЦИИ
-----------

bach secrets list
    Показывает все сохраненные секреты. Значение указано из соображений безопасности.
    не отображается, только ключ, категория, описание, источник и время создания
    время. Сортировка по категориям и ключам.

bach secrets get <key>
    Получает значение определенного секрета и отображает ключ, описание.
    и ценность. Ошибка, если секрет не существует.

bach secrets set <key> <value> [<description>] [<category>]
    Сохраняет или обновляет секрет. Значение находится в БД
    а также записывается в файл секретов (двунаправленная синхронизация).
    Параметры:
        <ключ>: уникальный идентификатор (например, «telegram_api_key»).
        <значение>: секретное значение.
        <description> (необязательно): описание, по умолчанию: пусто.
        <категория> (необязательно): Категория, по умолчанию: «Общие»

bach secrets delete <key>
    Удаляет секрет из БД и файла. Ошибка, если секрет не существует.

bach secrets sync
    Ручное сравнение файла с базой данных (Файл -> БД).
    Авторитет файла: если файл отсутствует, база данных очищается.
    Записи с префиксом '_example_' пропускаются.


ПРИМЕРЫ
---------

Сохранить новый секрет (с категорией):
    bach secrets set telegram_api_key "12345:ABCDEFG..." "Telegram Bot" "api"

Получить секрет:
    bach secrets get telegram_api_key

Перечислить все секреты:
    bach secrets list

Удалить секрет:
    bach secrets delete telegram_api_key

Ручная синхронизация после изменения файла:
    bach secrets sync

Переопределить файл секретов (USB-накопитель):
    bach settings set secrets_file_path /media/usb/my_secrets.json


ФАЙЛЫ
-------

hub/secrets_handler.py
    Точка входа CLI реализации обработчика: handle_secrets_command().
    Класс SecretsHandler управляет подключением к БД и синхронизацией файлов.

data/bach.db
    База данных SQLite с таблицей «секреты» (ключ, значение, описание, категория,
    источник, созданный_at, обновленный_at, идентификатор).

~/.bach/bach_secrets.json
    Пользовательский файл JSON со всеми секретами (структура: мета, секреты,
    примечания). Создается автоматически при синхронизации. Ручные изменения сохраняются.

core/database.py
    Утилита подключения к базе данных (переход к прямому соединению sqlite3,
    если импорт не удался).


СМОТРИ ТАКЖЕ
----------

bach settings — Konfiguration von system_config Eintraegen
core/database — архитектура базы данных
BACH-KONZEPTE/ENT-44 — Файлово-авторитарная синхронизация
