saad-crypto 0.1.0__py3-none-any.whl

saad_crypto-0.1.0.dist-info/METADATA

@@ -0,0 +1,69 @@
+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

saad_crypto-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+saad_crypto-0.1.0.dist-info/licenses/LICENSE,sha256=tbdbgQF1xdCmFlAk89JMNdkQlsgTESzrpnF9t_oC9Fk,1061
+saad_tools/__init__.py,sha256=_VXy4KePPAFJtwAqgdwiqZkbnshw_CmQ7yGQVEsnRoo,358
+saad_tools/crypto.py,sha256=UcVrTWqOxkXzuBiFwPrA_WsitKtUReuFx5IY_9ZkBpU,6235
+saad_tools/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+saad_crypto-0.1.0.dist-info/METADATA,sha256=Mguyqo0Nt0BYOLBQN8dW-_fvZJ2O5GPhFHNB2bIIv1Y,2979
+saad_crypto-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+saad_crypto-0.1.0.dist-info/top_level.txt,sha256=RfPV8YGp8DPXUMaCBWlzhJ5iHZcE0UW0kkMzrt2GWiE,11
+saad_crypto-0.1.0.dist-info/RECORD,,

saad_crypto-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

saad_crypto-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Saad
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

saad_crypto-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+saad_tools

saad_tools/__init__.py

@@ -0,0 +1,5 @@
+"""Practical authenticated encryption and password-protected secret storage."""
+from .crypto import CryptoError, InvalidPassword, Vault, decrypt, decrypt_text, encrypt, encrypt_text, generate_key
+
+__version__ = "0.1.0"
+__all__ = ["CryptoError", "InvalidPassword", "Vault", "decrypt", "decrypt_text", "encrypt", "encrypt_text", "generate_key", "__version__"]

saad_tools/crypto.py

@@ -0,0 +1,163 @@
+"""Authenticated encryption helpers for saad_tools."""
+from __future__ import annotations
+
+import base64
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+from cryptography.exceptions import InvalidTag
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from cryptography.hazmat.primitives.kdf.scrypt import Scrypt
+
+_FORMAT = "saad_tools.v1"
+_SALT_SIZE = 16
+_NONCE_SIZE = 12
+_KEY_SIZE = 32
+_SCRYPT_N = 2**15
+_SCRYPT_R = 8
+_SCRYPT_P = 1
+
+
+class CryptoError(Exception):
+    """Base exception for saad_tools errors."""
+
+
+class InvalidPassword(CryptoError):
+    """Raised when a vault password cannot decrypt the vault."""
+
+
+def _derive_key(password: str, salt: bytes) -> bytes:
+    if not isinstance(password, str) or len(password) < 12:
+        raise ValueError("password must be a string of at least 12 characters")
+    return Scrypt(salt=salt, length=_KEY_SIZE, n=_SCRYPT_N, r=_SCRYPT_R, p=_SCRYPT_P).derive(password.encode())
+
+
+def encrypt(data: bytes, key: bytes, *, associated_data: bytes | None = None) -> bytes:
+    """Encrypt bytes using AES-256-GCM; returns nonce+ciphertext+tag."""
+    if len(key) != _KEY_SIZE:
+        raise ValueError("key must be exactly 32 bytes")
+    if not isinstance(data, bytes):
+        raise TypeError("data must be bytes")
+    nonce = os.urandom(_NONCE_SIZE)
+    return nonce + AESGCM(key).encrypt(nonce, data, associated_data)
+
+
+def decrypt(token: bytes, key: bytes, *, associated_data: bytes | None = None) -> bytes:
+    """Decrypt and authenticate a token produced by :func:`encrypt`."""
+    if len(key) != _KEY_SIZE:
+        raise ValueError("key must be exactly 32 bytes")
+    if len(token) <= _NONCE_SIZE:
+        raise CryptoError("ciphertext is too short")
+    try:
+        return AESGCM(key).decrypt(token[:_NONCE_SIZE], token[_NONCE_SIZE:], associated_data)
+    except InvalidTag as exc:
+        raise CryptoError("ciphertext authentication failed") from exc
+
+
+def encrypt_text(text: str, key: bytes, *, associated_data: bytes | None = None) -> str:
+    """Encrypt UTF-8 text and return URL-safe base64."""
+    return base64.urlsafe_b64encode(encrypt(text.encode("utf-8"), key, associated_data=associated_data)).decode("ascii")
+
+
+def decrypt_text(token: str, key: bytes, *, associated_data: bytes | None = None) -> str:
+    """Decrypt URL-safe base64 text produced by :func:`encrypt_text`."""
+    try:
+        raw = base64.urlsafe_b64decode(token.encode("ascii"))
+    except Exception as exc:
+        raise CryptoError("invalid encoded ciphertext") from exc
+    return decrypt(raw, key, associated_data=associated_data).decode("utf-8")
+
+
+class Vault:
+    """A password-protected JSON vault for small application secrets.
+
+    The password is never stored. The vault file contains only a random salt,
+    an encrypted payload, and authentication metadata. File permissions are
+    restricted to the current user where supported.
+    """
+
+    def __init__(self, path: str | os.PathLike[str], password: str, *, create: bool = False):
+        self.path = Path(path).expanduser()
+        self._password = password
+        if self.path.exists():
+            self._items = self._load()
+        elif create:
+            self._items = {}
+            self._save()
+        else:
+            raise FileNotFoundError(self.path)
+
+    def _load(self) -> dict[str, Any]:
+        try:
+            envelope = json.loads(self.path.read_text(encoding="utf-8"))
+            salt = base64.b64decode(envelope["salt"])
+            key = _derive_key(self._password, salt)
+            payload = decrypt(base64.b64decode(envelope["data"]), key, associated_data=_FORMAT.encode())
+            obj = json.loads(payload.decode("utf-8"))
+            if envelope.get("format") != _FORMAT or not isinstance(obj, dict):
+                raise ValueError
+            return obj
+        except (KeyError, ValueError, TypeError, json.JSONDecodeError, CryptoError, InvalidPassword) as exc:
+            raise InvalidPassword("unable to open vault; password or file may be incorrect") from exc
+
+    def _save(self) -> None:
+        salt = os.urandom(_SALT_SIZE)
+        key = _derive_key(self._password, salt)
+        data = encrypt(json.dumps(self._items, ensure_ascii=False, sort_keys=True).encode(), key, associated_data=_FORMAT.encode())
+        envelope = {"format": _FORMAT, "salt": base64.b64encode(salt).decode(), "data": base64.b64encode(data).decode()}
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = self.path.with_name(self.path.name + ".tmp")
+        tmp.write_text(json.dumps(envelope, separators=(",", ":")), encoding="utf-8")
+        try:
+            os.chmod(tmp, 0o600)
+        except OSError:
+            pass
+        os.replace(tmp, self.path)
+
+    def set(self, name: str, value: str) -> None:
+        """Store or replace a string secret."""
+        if not name or not isinstance(name, str) or not isinstance(value, str):
+            raise ValueError("name and value must be non-empty strings")
+        self._items[name] = value
+        self._save()
+
+    def get(self, name: str) -> str:
+        """Retrieve a secret."""
+        try:
+            value = self._items[name]
+        except KeyError as exc:
+            raise KeyError(name) from exc
+        if not isinstance(value, str):
+            raise CryptoError("vault entry is not a string")
+        return value
+
+    def delete(self, name: str) -> None:
+        """Delete a secret and persist the vault."""
+        del self._items[name]
+        self._save()
+
+    def names(self) -> tuple[str, ...]:
+        """Return stored secret names without revealing values."""
+        return tuple(sorted(self._items))
+
+    def __enter__(self) -> "Vault":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self._password = ""
+        self._items.clear()
+
+
+__all__ = ["CryptoError", "InvalidPassword", "Vault", "decrypt", "decrypt_text", "encrypt", "encrypt_text"]
+
+# Explicitly expose a key generator for applications that need envelope keys.
+def generate_key() -> bytes:
+    """Generate a random 256-bit AES key."""
+    return AESGCM.generate_key(bit_length=256)
+
+__all__.append("generate_key")
+
+# Keep Any import used for JSON-compatible values in the public implementation.
+_ = Any