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

--------------------------------------------------------------------------------
秘密
--------------------------------------------------------------------------------

处理程序名称
------------

秘密处理程序 (SQ076) — API 密钥、密码和敏感信息的管理
文件系统和数据库之间具有文件权威匹配的凭证。


描述
------------

Secrets Handler 提供敏感数据的安全存储和查询。
所有秘密都存储在数据库（bach.db:secrets）中，并且可以选择存储在
保存到本地 JSON 文件。权威在于文件：缺少该文件
文件中，所有机密都将从数据库中删除 (ENT-44)。

存储位置机密文件：~/.bach/bach_secrets.json（可通过配置
system_config 带有键“secrets_file_path”）。

每个秘密都可以给出描述、类别和时间戳。


操作
-----------

bach secrets list
    显示所有保存的秘密。该值是出于安全原因
    不显示，仅显示关键字、类别、描述、来源和创建时间
    时间。按类别和键排序。

bach secrets get <key>
    获取特定 Secret 的值并显示 Key、Description
    和价值。如果 Secret 不存在，则出错。

bach secrets set <key> <value> [<description>] [<category>]
    保存或更新秘密。该值都在数据库中
    以及写入 Secrets 文件（双向同步）。
    参数：
        <key>：唯一标识符（例如“telegram_api_key”）
        <value>：秘密值
        <description>（可选）：描述，默认：空
        <category>（可选）：类别，默认：'general'

bach secrets delete <key>
    从数据库和文件中删除机密。如果 Secret 不存在，则出错。

bach secrets sync
    从文件到数据库的手动比较（文件 -> DB）。
    文件权限：如果文件丢失，则DB被清空。
    带有前缀“_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


FILES
-------

hub/secrets_handler.py
    处理程序实现 CLI 入口点：handle_secrets_command()。
    SecretsHandler 类管理数据库连接和文件同步。

data/bach.db
    SQLite 数据库，包含表“秘密”（键、值、描述、类别、
    源、created_at、updated_at、id）。

~/.bach/bach_secrets.json
    包含所有秘密的用户端 JSON 文件（结构：元、秘密、
    注释）。通过同步自动生成。保留手动编辑。

core/database.py
    数据库连接实用程序（回退到直接 sqlite3 连接，
    如果导入失败）。


另请参见
----------

bach settings — Konfiguration von system_config Eintraegen
core/database — 数据库架构
BACH-KONZEPTE/ENT-44 — 文件独裁同步
