configcrypt 1.0.1

A simple, secure, cross-platform file encryption tool with CLI, GUI, and Python API

🔐 ConfigCrypt - 文件加密工具

安全 · 简洁 · 高效

一个简单、安全、跨平台的文件加密工具，支持命令行、图形界面和Python API三种使用方式。

快速开始 · 功能特性 · 安装 · 使用文档 · API文档

---

📖 简介

ConfigCrypt 是一个基于 Fernet (对称加密) 和 PBKDF2 (密钥派生) 的文件加密工具。它可以帮助您安全地加密配置文件、密钥、凭证等敏感数据，并提供直观的图形界面和强大的命令行工具。

为什么选择 ConfigCrypt？

• 🔒 安全可靠 - 使用行业标准的加密算法（Fernet + PBKDF2-HMAC-SHA256）
• 🎨 界面美观 - 黑底暗金色高级UI设计
• 🖥️ 跨平台 - 完美支持 Windows、macOS、Linux
• 🔑 Keychain集成 - 主密码安全存储在系统密钥链
• 📦 多种接口 - CLI命令行、GUI图形界面、Python Library API
• 📄 格式支持 - 原生支持 JSON、YAML、ENV 格式解析
• 🚀 零配置 - 开箱即用，无需复杂设置

---

✨ 功能特性

🎯 核心功能

• 文件加密/解密 - 支持任意文件类型加密
• 主密码管理 - 基于系统Keychain的安全密码存储
• 格式解析 - 解密后自动解析 JSON/YAML/ENV 格式
• 操作历史 - 记录所有加密/解密操作
• 文件拖拽 - GUI支持拖拽文件加密
• 编辑器集成 - 解密后直接打开编辑器

🎨 界面特点

• 黑底暗金色配色 - 低调奢华的视觉体验
• 上下分割布局 - 拖拽区 + 操作历史
• 智能文件识别 - 自动识别 .enc 加密文件
• 实时反馈 - 密码强度、操作进度实时显示

---

🚀 快速开始

1. 安装

pip install configcrypt

2. 初始化（设置主密码）

cc init

3. 加密文件

# 加密文件（会删除原文件）
cc encrypt config.json

# 保留原文件
cc encrypt config.json --keep

# 指定输出路径
cc encrypt config.json --out encrypted_config.enc

4. 解密文件

# 解密文件
cc decrypt config.json.enc

# 解密并打开编辑器
cc decrypt config.json.enc --open

# 指定编辑器
cc decrypt config.json.enc --open --editor notepad

5. 使用GUI

# 启动图形界面（推荐方式）
python run.py

# 或者双击 Windows 启动文件
🔐 启动ConfigCrypt.bat

---

📦 安装

方式一：通过 pip 安装（推荐）

pip install configcrypt

方式二：从源码安装

# 克隆仓库
git clone https://github.com/yourusername/configcrypt.git
cd configcrypt

# 安装依赖
pip install -e .

系统要求

• Python: 3.8 或更高版本
• 操作系统: Windows 10+, macOS 10.14+, Linux (主流发行版)

依赖包

• cryptography - 加密引擎
• keyring - 系统Keychain集成
• click - CLI命令行框架
• PySide6 - GUI图形界面
• pyyaml - YAML格式支持
• python-dotenv - ENV格式支持

---

📚 使用文档

CLI 命令行

初始化主密码

cc init

首次使用时需要设置主密码。密码要求：

• 至少8个字符
• 支持任意字符组合
• 系统会显示密码强度（弱/中/强）

加密文件

# 基本用法
cc encrypt <文件路径>

# 常用选项
cc encrypt config.json              # 加密文件（删除原文件）
cc encrypt config.json --keep       # 保留原文件
cc encrypt config.json --out secret.enc  # 指定输出路径

加密后的文件：

• 文件名：原文件名.enc
• 格式：[16字节盐值] + [Fernet加密数据]
• 扩展名：.enc

解密文件

# 基本用法
cc decrypt <加密文件路径>

# 常用选项
cc decrypt config.json.enc                    # 解密文件
cc decrypt config.json.enc --out config.json  # 指定输出路径
cc decrypt config.json.enc --open             # 解密后打开编辑器
cc decrypt config.json.enc --open --editor code  # 指定编辑器(VS Code)

支持的编辑器：

• Windows: notepad, notepad++, code
• macOS: code, subl, open -e
• Linux: code, gedit, nano, vim

查看状态

cc status

显示信息：

• Keychain状态（可用/不可用）
• 主密码状态（已设置/未设置）
• 密码强度

修改主密码

cc reset-password

需要：

1. 验证当前密码
2. 输入新密码
3. 确认新密码

---

GUI 图形界面

启动GUI

Windows:

# 方式1：双击启动文件
🔐 启动ConfigCrypt.bat

# 方式2：命令行启动
python run.py

macOS / Linux:

python run.py

主界面功能

上半部分 - 拖拽区：

• 拖拽文件到此处进行加密/解密
• 左侧红色按钮：加密
• 右侧绿色按钮：解密
• 中间锁图标：视觉标识

下半部分 - 操作历史：

• 显示所有加密/解密操作记录
• 列：时间、操作、文件、输出、状态
• 刷新按钮：🔄 刷新历史
• 清除按钮：🗑️ 清除所有历史

首次启动

首次启动会弹出"欢迎向导"，引导您设置主密码。

加密流程

1. 点击"加密"按钮或拖拽明文文件
2. 选择文件
3. 在对话框中选择是否删除原文件
4. 选择输出位置
5. 等待加密完成

解密流程

1. 点击"解密"按钮或拖拽 .enc 文件
2. 输入主密码验证
3. 选择是否打开编辑器
4. 选择输出位置
5. 等待解密完成

菜单功能

• 文件菜单

  • 打开文件 (Ctrl+O)
  • 退出 (Ctrl+Q)

• 查看菜单

  • 显示/隐藏历史面板

• 设置菜单

  • 首选项（修改主密码）

• 帮助菜单

  • 关于

---

Library API

ConfigCrypt 也可以作为Python库在其他项目中使用。

基本用法

from configcrypt import VaultAPI

# 创建API实例
api = VaultAPI()

# 解密文件为字符串
content = api.decrypt_file("config.json.enc")
print(content)

# 解密JSON文件
config = api.decrypt_json("config.json.enc")
print(config["api_key"])

# 解密YAML文件
settings = api.decrypt_yaml("settings.yaml.enc")
print(settings["database"]["host"])

# 解密ENV文件
env_vars = api.decrypt_env(".env.enc")
print(env_vars["API_KEY"])

使用自定义密码

from configcrypt import VaultAPI

# 使用自定义密码（不从Keychain读取）
api = VaultAPI(password="your_password_here")

data = api.decrypt_json("config.json.enc")

API方法

decrypt_file(file_path: str | Path) -> str

解密文件并返回字符串内容。

content = api.decrypt_file("secret.txt.enc")

decrypt_json(file_path: str | Path) -> dict

解密JSON文件并返回字典。

data = api.decrypt_json("config.json.enc")
print(data["key"])

decrypt_yaml(file_path: str | Path) -> dict

解密YAML文件并返回字典。

config = api.decrypt_yaml("settings.yaml.enc")
print(config["database"])

decrypt_env(file_path: str | Path) -> dict

解密ENV文件并返回键值对字典。

env = api.decrypt_env(".env.enc")
print(env["DATABASE_URL"])

异常处理

from configcrypt import VaultAPI
from configcrypt.core.exceptions import (
    DecryptionError,
    InvalidTokenError,
    ParseError,
)

api = VaultAPI()

try:
    data = api.decrypt_json("config.json.enc")
except DecryptionError:
    print("密码错误或文件损坏")
except InvalidTokenError:
    print("文件已被篡改")
except ParseError as e:
    print(f"JSON解析失败: {e}")
except FileNotFoundError:
    print("文件不存在")

---

🔒 安全性

加密算法

• 对称加密: Fernet (AES-128-CBC + HMAC-SHA256)
• 密钥派生: PBKDF2-HMAC-SHA256（200,000轮迭代）
• 盐值: 每次加密生成16字节随机盐值
• 完整性: HMAC验证，防止篡改

主密码存储

• Windows: Windows Credential Manager
• macOS: macOS Keychain
• Linux: Secret Service (如 GNOME Keyring)

安全建议

1. ✅ 使用强密码 - 至少8个字符，包含大小写字母、数字、符号
2. ✅ 定期更换密码 - 建议每3-6个月更换一次
3. ✅ 备份加密文件 - 加密文件丢失无法恢复
4. ✅ 保护主密码 - 忘记主密码无法解密文件
5. ⚠️ 不要共享密码 - 主密码仅自己知道

---

📁 支持的文件格式

ConfigCrypt 支持加密任何文件，但对以下格式提供原生解析支持：

格式	扩展名	Library API	说明
JSON	.json	decrypt_json()	自动解析为Python字典
YAML	.yaml, .yml	decrypt_yaml()	自动解析为Python字典
ENV	.env	decrypt_env()	自动解析为键值对字典
文本	.txt, .md, 等	decrypt_file()	返回字符串内容
其他	任意格式	decrypt_file()	返回原始字节内容

---

🎯 使用场景

1. 配置文件加密

# 加密API密钥配置
cc encrypt config.json --keep

# 提交到Git（只提交.enc文件）
git add config.json.enc
git commit -m "Add encrypted config"

2. 环境变量保护

# 加密.env文件
cc encrypt .env

# 在应用中使用
python
>>> from configcrypt import VaultAPI
>>> api = VaultAPI()
>>> env = api.decrypt_env(".env.enc")
>>> import os
>>> os.environ.update(env)

3. 数据库凭证

# database.yaml
database:
  host: localhost
  port: 5432
  username: admin
  password: secret_password_123

cc encrypt database.yaml

from configcrypt import VaultAPI

api = VaultAPI()
db_config = api.decrypt_yaml("database.yaml.enc")

# 使用数据库配置
conn = psycopg2.connect(
    host=db_config["database"]["host"],
    port=db_config["database"]["port"],
    user=db_config["database"]["username"],
    password=db_config["database"]["password"]
)

4. 私钥保护

# 加密SSH私钥
cc encrypt ~/.ssh/id_rsa --out ~/.ssh/id_rsa.enc

# 解密使用
cc decrypt ~/.ssh/id_rsa.enc --out ~/.ssh/id_rsa_temp
ssh -i ~/.ssh/id_rsa_temp user@server
rm ~/.ssh/id_rsa_temp

---

❓ 常见问题 (FAQ)

Q1: 忘记主密码怎么办？

A: 很遗憾，主密码忘记后无法恢复。ConfigCrypt不存储主密码的任何形式，只存储在系统Keychain中。如果忘记密码，已加密的文件将无法解密。

建议：

• 设置一个您能记住的强密码
• 将密码记录在安全的地方（如密码管理器）
• 定期备份未加密的文件

Q2: 可以在多台电脑上使用吗？

A: 可以，但需要在每台电脑上使用相同的主密码。ConfigCrypt的主密码存储在本地系统Keychain中，不同电脑的Keychain是独立的。

建议：

• 在所有电脑上设置相同的主密码
• 或者使用 Library API 时手动指定密码

Q3: 加密文件可以分享给他人吗？

A: 可以，但对方需要：

1. 安装ConfigCrypt
2. 知道您的主密码
3. 在他们的系统上设置相同的主密码

更安全的方式：

• 使用非对称加密（如GPG）进行文件共享
• ConfigCrypt主要用于个人敏感文件保护

Q4: 加密文件可以移动或重命名吗？

A: 可以！加密文件可以随意移动、重命名、复制。只要文件内容没有被修改，就可以正常解密。

Q5: GUI和CLI可以混用吗？

A: 完全可以！GUI和CLI使用相同的加密引擎和主密码（从Keychain读取）。您可以用CLI加密，用GUI解密，反之亦然。

Q6: 支持批量加密吗？

A: 当前版本不支持批量加密。您可以使用脚本循环调用CLI命令：

for file in *.json; do
    cc encrypt "$file" --keep
done

Q7: 如何卸载ConfigCrypt？

pip uninstall configcrypt

清理数据：

• 删除 ~/.configcrypt/ 目录（操作历史）
• 从系统Keychain中删除ConfigCrypt条目

Q8: 加密文件占用多大空间？

加密文件大小 ≈ 原文件大小 + 60字节（盐值16字节 + Fernet开销）

---

🛠️ 开发与测试

从源码安装

# 克隆仓库
git clone <repository-url>
cd configcrypt

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 安装开发依赖
pip install -e ".[dev]"

运行测试

# 运行所有测试
pytest

# 运行单元测试
pytest tests/unit/

# 运行集成测试
pytest tests/integration/

# 运行属性测试（基于 Hypothesis）
pytest tests/unit/test_properties.py

# 查看测试覆盖率
pytest --cov=configcrypt --cov-report=html
open htmlcov/index.html  # 查看覆盖率报告

手动测试

# CLI测试
python -c "from configcrypt.cli import main; main()" -- init
python -c "from configcrypt.cli import main; main()" -- encrypt test.txt

# GUI测试
python run.py

# API测试
python tests/integration/test_api_integration.py

项目结构

configcrypt/
├── src/configcrypt/          # 源代码
│   ├── __init__.py        # 包初始化（导出 VaultAPI）
│   ├── core/              # 核心加密引擎
│   │   ├── vault.py       # Vault 和 VaultAPI 类
│   │   ├── keychain_store.py  # Keychain 集成
│   │   ├── format_parser.py   # 格式解析器 (JSON/YAML/ENV)
│   │   ├── editor_launcher.py # 编辑器启动
│   │   └── exceptions.py      # 自定义异常
│   ├── cli/               # 命令行界面
│   │   └── commands.py    # CLI 命令（init/encrypt/decrypt/等）
│   └── gui/               # 图形界面
│       ├── app.py         # GUI 应用入口
│       ├── main_window.py # 主窗口
│       ├── dialogs.py     # 对话框集合
│       ├── history_panel.py   # 历史记录面板
│       └── history.py     # 历史记录管理
├── tests/                 # 测试目录
│   ├── unit/              # 单元测试
│   ├── cli/               # CLI 测试
│   ├── gui/               # GUI 测试
│   ├── integration/       # 集成测试
│   └── reports/           # 测试报告
├── run.py                 # GUI 启动脚本
├── pyproject.toml         # 项目配置
├── README.md              # 项目文档
├── LICENSE                # MIT 许可证
└── CHANGELOG.md           # 版本历史

---

📄 许可证

本项目采用 MIT License 开源协议。

---

🤝 贡献

欢迎贡献代码、报告问题、提出建议！

报告问题

如果您发现 bug 或有功能建议，请创建 Issue 并提供：

• 详细的问题描述
• 复现步骤
• 您的系统环境（操作系统、Python 版本）
• 错误信息或截图

开发贡献

1. Fork 本仓库
2. 创建您的特性分支 (git checkout -b feature/amazing-feature)
3. 编写代码和测试
4. 确保所有测试通过 (pytest)
5. 提交您的更改 (git commit -m 'Add some amazing feature')
6. 推送到分支 (git push origin feature/amazing-feature)
7. 开启 Pull Request

代码规范

• 遵循 PEP 8 风格指南
• 添加适当的类型注解
• 为新功能编写测试
• 更新相关文档

---

📞 联系方式

• 项目: ConfigCrypt File Encryption Tool
• 版本: v1.0.0
• 许可证: MIT License

---

🙏 致谢

感谢以下开源项目：

• cryptography - 加密库
• keyring - Keychain集成
• PySide6 - GUI框架
• click - CLI框架

---

⭐ 功能特色

• ✅ 测试覆盖率 90%+ - 包含单元测试、CLI测试、GUI测试、集成测试
• ✅ 属性测试 - 使用 Hypothesis 进行基于属性的测试
• ✅ CI/CD - GitHub Actions 自动化测试（Windows/macOS/Linux）
• ✅ 类型注解 - 完整的类型提示，支持 IDE 智能提示
• ✅ 文档完善 - 详细的 README、API 文档、测试报告

---

ConfigCrypt - 让文件加密变得简单安全

Made with ❤️ using Python