Metadata-Version: 2.4
Name: saad-crypto
Version: 0.1.0
Summary: Authenticated encryption and password-protected secret storage for Python
Author: Saad
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cryptography>=42.0
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Dynamic: license-file

# saad_tools

مكتبة بايثون صغيرة للتشفير الموثّق وتخزين الأسرار في خزنة محمية بكلمة مرور.

> **تنبيه أمني مهم:** التشفير يحمي البيانات والمفاتيح المخزنة، لكنه لا يستطيع منع نسخ كود بايثون الذي يجب توزيعه وتشغيله على جهاز المستخدم. إذا كان الهدف حماية منطق تجاري سري، فالحل الأقوى هو إبقاء المنطق على خادم API وعدم شحنه إلى العميل، أو استخدام خدمة إدارة أسرار/وحدة HSM. لا تضع كلمة مرور الخزنة داخل الكود أو مستودع Git.

## التثبيت

```bash
pip install saad_tools
```

## تشفير البيانات

```python
from saad_tools import decrypt_text, encrypt_text, generate_key

key = generate_key()  # خزّنها في مدير أسرار، لا في المصدر
ciphertext = encrypt_text("رسالة سرية", key)
plaintext = decrypt_text(ciphertext, key)
```

التشفير المستخدم هو **AES-256-GCM** مع nonce عشوائي لكل عملية، لذلك يكتشف التعديل أو كلمة المرور/المفتاح الخاطئ.

## خزنة الأسرار

```python
from saad_tools import Vault

vault = Vault("~/.config/myapp/vault.json", "كلمة مرور طويلة وفريدة", create=True)
vault.set("database_password", "...secret...")
password = Vault("~/.config/myapp/vault.json", "كلمة مرور طويلة وفريدة").get("database_password")
```

الخزنة تستخدم **scrypt** لاشتقاق مفتاح من كلمة المرور، ثم AES-256-GCM لتشفير المحتوى. لا تُحفظ كلمة المرور في الملف. يحاول البرنامج جعل صلاحيات الملف `0600` على الأنظمة التي تدعم ذلك.

## تطوير محلي

```bash
python -m pip install -e ".[test]"
pytest
python -m build
```

## الحالة

الإصدار الحالي `0.1.0` تجريبي. قبل استخدامه في إنتاج حساس، راجع إدارة كلمات المرور، النسخ الاحتياطي، صلاحيات نظام الملفات، وسياسة تدوير المفاتيح. لا تحذف الخزنة الأصلية قبل اختبار النسخة الاحتياطية.

## الترخيص

MIT
