ExoCrypt 1.2.0__tar.gz

exocrypt-1.2.0/ExoCrypt.egg-info/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: ExoCrypt
+Version: 1.2.0
+Summary: Chunked authenticated encryption for files and Python project bundles
+License: MIT
+Keywords: encryption,python,AES-GCM,Argon2id,file-protection,CLI
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography>=42.0.0
+Requires-Dist: argon2-cffi>=23.1.0
+Dynamic: license-file
+
+# ExoCrypt 1.2.0
+
+ExoCrypt protects files and Python project bundles using **Argon2id + AES-256-GCM**.
+
+## What's new in 1.2.0
+
+- New authenticated chunked format v3 for file encryption/decryption.
+- Large files are processed in 1 MiB chunks without loading the whole file into memory.
+- Each chunk is authenticated separately; reordered, altered, missing, or appended chunks are rejected.
+- Argon2id key derivation (64 MiB memory, 3 passes, parallelism 4).
+- Fresh random 16-byte salt and 8-byte nonce prefix for every encryption; a unique per-chunk nonce is derived from the prefix and chunk counter.
+- Atomic output files; partial plaintext is removed if authentication fails.
+- Still reads legacy v1 (ExoCrypt 1.0.x) and v2 (ExoCrypt 1.1.x) files.
+- Project bundles are encrypted using the v3 format.
+
+## Install
+
+Python 3.10+:
+
+```bash
+python -m pip install -e .
+```
+
+Dependencies: `cryptography>=42.0.0` and `argon2-cffi>=23.1.0`.
+
+## CLI
+
+```bash
+exocrypt protect main.py
+exocrypt unprotect main.py.exc -o restored.py
+exocrypt verify main.py.exc
+exocrypt project ./my_project -o my_project.exc
+exocrypt unproject my_project.exc -o ./restored_project
+exocrypt --version
+```
+
+The CLI prompts for passwords instead of asking you to put them in shell history.
+
+## Python API
+
+```python
+from exocrypt import encrypt_file, decrypt_file, verify_file
+
+encrypt_file("main.py", "main.py.exc", "a long unique password")
+assert verify_file("main.py.exc", "a long unique password")
+decrypt_file("main.py.exc", "restored.py", "a long unique password")
+```
+
+For in-memory bytes:
+
+```python
+from exocrypt import encrypt_bytes, decrypt_bytes
+
+encrypted = encrypt_bytes(b"secret content", "a long unique password")
+assert decrypt_bytes(encrypted, "a long unique password") == b"secret content"
+```
+
+## Security notes
+
+- No encryption can be guaranteed impossible to decrypt forever.
+- AES-256-GCM and Argon2id are established algorithms. ExoCrypt does not depend on keeping its algorithm secret.
+- Use a long, unique password. Weak passwords may be guessed offline.
+- A different implementation can decrypt files if it implements this documented format and has the correct password.
+- If code is decrypted and executed on a device controlled by someone else, the plaintext may be inspected while it runs. Encryption at rest does not make running code permanently unreadable.
+- Keep a secure backup of both your original files and the password. There is no password recovery backdoor.
+- The chunked file API limits memory usage; the in-memory `encrypt_bytes` / `decrypt_bytes` functions naturally hold the byte payload in memory.
+- Project bundling currently builds a ZIP in memory before encrypting it, so very large directory trees can still use more memory during `project` operations.
+
+## Tests
+
+```bash
+python -m pip install -e .
+python -m unittest discover -s tests -v
+```
+
+## License
+
+MIT

exocrypt-1.2.0/ExoCrypt.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+ExoCrypt.egg-info/PKG-INFO
+ExoCrypt.egg-info/SOURCES.txt
+ExoCrypt.egg-info/dependency_links.txt
+ExoCrypt.egg-info/entry_points.txt
+ExoCrypt.egg-info/requires.txt
+ExoCrypt.egg-info/top_level.txt
+exocrypt/__init__.py
+exocrypt/__main__.py
+exocrypt/cli.py
+exocrypt/core.py
+exocrypt/project.py
+tests/test_core.py
+tests/test_project.py

exocrypt-1.2.0/ExoCrypt.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

exocrypt-1.2.0/ExoCrypt.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+exocrypt = exocrypt.cli:main

exocrypt-1.2.0/ExoCrypt.egg-info/requires.txt

@@ -0,0 +1,2 @@
+cryptography>=42.0.0
+argon2-cffi>=23.1.0

exocrypt-1.2.0/ExoCrypt.egg-info/top_level.txt

@@ -0,0 +1 @@
+exocrypt

exocrypt-1.2.0/LICENSE

@@ -0,0 +1,17 @@
+MIT License
+
+Copyright (c) 2026 ExoCrypt contributors
+
+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.

exocrypt-1.2.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: ExoCrypt
+Version: 1.2.0
+Summary: Chunked authenticated encryption for files and Python project bundles
+License: MIT
+Keywords: encryption,python,AES-GCM,Argon2id,file-protection,CLI
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography>=42.0.0
+Requires-Dist: argon2-cffi>=23.1.0
+Dynamic: license-file
+
+# ExoCrypt 1.2.0
+
+ExoCrypt protects files and Python project bundles using **Argon2id + AES-256-GCM**.
+
+## What's new in 1.2.0
+
+- New authenticated chunked format v3 for file encryption/decryption.
+- Large files are processed in 1 MiB chunks without loading the whole file into memory.
+- Each chunk is authenticated separately; reordered, altered, missing, or appended chunks are rejected.
+- Argon2id key derivation (64 MiB memory, 3 passes, parallelism 4).
+- Fresh random 16-byte salt and 8-byte nonce prefix for every encryption; a unique per-chunk nonce is derived from the prefix and chunk counter.
+- Atomic output files; partial plaintext is removed if authentication fails.
+- Still reads legacy v1 (ExoCrypt 1.0.x) and v2 (ExoCrypt 1.1.x) files.
+- Project bundles are encrypted using the v3 format.
+
+## Install
+
+Python 3.10+:
+
+```bash
+python -m pip install -e .
+```
+
+Dependencies: `cryptography>=42.0.0` and `argon2-cffi>=23.1.0`.
+
+## CLI
+
+```bash
+exocrypt protect main.py
+exocrypt unprotect main.py.exc -o restored.py
+exocrypt verify main.py.exc
+exocrypt project ./my_project -o my_project.exc
+exocrypt unproject my_project.exc -o ./restored_project
+exocrypt --version
+```
+
+The CLI prompts for passwords instead of asking you to put them in shell history.
+
+## Python API
+
+```python
+from exocrypt import encrypt_file, decrypt_file, verify_file
+
+encrypt_file("main.py", "main.py.exc", "a long unique password")
+assert verify_file("main.py.exc", "a long unique password")
+decrypt_file("main.py.exc", "restored.py", "a long unique password")
+```
+
+For in-memory bytes:
+
+```python
+from exocrypt import encrypt_bytes, decrypt_bytes
+
+encrypted = encrypt_bytes(b"secret content", "a long unique password")
+assert decrypt_bytes(encrypted, "a long unique password") == b"secret content"
+```
+
+## Security notes
+
+- No encryption can be guaranteed impossible to decrypt forever.
+- AES-256-GCM and Argon2id are established algorithms. ExoCrypt does not depend on keeping its algorithm secret.
+- Use a long, unique password. Weak passwords may be guessed offline.
+- A different implementation can decrypt files if it implements this documented format and has the correct password.
+- If code is decrypted and executed on a device controlled by someone else, the plaintext may be inspected while it runs. Encryption at rest does not make running code permanently unreadable.
+- Keep a secure backup of both your original files and the password. There is no password recovery backdoor.
+- The chunked file API limits memory usage; the in-memory `encrypt_bytes` / `decrypt_bytes` functions naturally hold the byte payload in memory.
+- Project bundling currently builds a ZIP in memory before encrypting it, so very large directory trees can still use more memory during `project` operations.
+
+## Tests
+
+```bash
+python -m pip install -e .
+python -m unittest discover -s tests -v
+```
+
+## License
+
+MIT

exocrypt-1.2.0/README.md

@@ -0,0 +1,78 @@
+# ExoCrypt 1.2.0
+
+ExoCrypt protects files and Python project bundles using **Argon2id + AES-256-GCM**.
+
+## What's new in 1.2.0
+
+- New authenticated chunked format v3 for file encryption/decryption.
+- Large files are processed in 1 MiB chunks without loading the whole file into memory.
+- Each chunk is authenticated separately; reordered, altered, missing, or appended chunks are rejected.
+- Argon2id key derivation (64 MiB memory, 3 passes, parallelism 4).
+- Fresh random 16-byte salt and 8-byte nonce prefix for every encryption; a unique per-chunk nonce is derived from the prefix and chunk counter.
+- Atomic output files; partial plaintext is removed if authentication fails.
+- Still reads legacy v1 (ExoCrypt 1.0.x) and v2 (ExoCrypt 1.1.x) files.
+- Project bundles are encrypted using the v3 format.
+
+## Install
+
+Python 3.10+:
+
+```bash
+python -m pip install -e .
+```
+
+Dependencies: `cryptography>=42.0.0` and `argon2-cffi>=23.1.0`.
+
+## CLI
+
+```bash
+exocrypt protect main.py
+exocrypt unprotect main.py.exc -o restored.py
+exocrypt verify main.py.exc
+exocrypt project ./my_project -o my_project.exc
+exocrypt unproject my_project.exc -o ./restored_project
+exocrypt --version
+```
+
+The CLI prompts for passwords instead of asking you to put them in shell history.
+
+## Python API
+
+```python
+from exocrypt import encrypt_file, decrypt_file, verify_file
+
+encrypt_file("main.py", "main.py.exc", "a long unique password")
+assert verify_file("main.py.exc", "a long unique password")
+decrypt_file("main.py.exc", "restored.py", "a long unique password")
+```
+
+For in-memory bytes:
+
+```python
+from exocrypt import encrypt_bytes, decrypt_bytes
+
+encrypted = encrypt_bytes(b"secret content", "a long unique password")
+assert decrypt_bytes(encrypted, "a long unique password") == b"secret content"
+```
+
+## Security notes
+
+- No encryption can be guaranteed impossible to decrypt forever.
+- AES-256-GCM and Argon2id are established algorithms. ExoCrypt does not depend on keeping its algorithm secret.
+- Use a long, unique password. Weak passwords may be guessed offline.
+- A different implementation can decrypt files if it implements this documented format and has the correct password.
+- If code is decrypted and executed on a device controlled by someone else, the plaintext may be inspected while it runs. Encryption at rest does not make running code permanently unreadable.
+- Keep a secure backup of both your original files and the password. There is no password recovery backdoor.
+- The chunked file API limits memory usage; the in-memory `encrypt_bytes` / `decrypt_bytes` functions naturally hold the byte payload in memory.
+- Project bundling currently builds a ZIP in memory before encrypting it, so very large directory trees can still use more memory during `project` operations.
+
+## Tests
+
+```bash
+python -m pip install -e .
+python -m unittest discover -s tests -v
+```
+
+## License
+
+MIT

exocrypt-1.2.0/exocrypt/__init__.py

@@ -0,0 +1,18 @@
+"""ExoCrypt: authenticated encryption for files and project bundles."""
+from .core import (
+    ExoCryptError,
+    encrypt_bytes,
+    decrypt_bytes,
+    encrypt_file,
+    decrypt_file,
+    verify_file,
+)
+from .project import protect_project, unprotect_project
+
+__version__ = "1.2.0"
+
+__all__ = [
+    "__version__", "ExoCryptError", "encrypt_bytes", "decrypt_bytes",
+    "encrypt_file", "decrypt_file", "verify_file",
+    "protect_project", "unprotect_project",
+]

exocrypt-1.2.0/exocrypt/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

exocrypt-1.2.0/exocrypt/cli.py

@@ -0,0 +1,86 @@
+"""Command-line interface for ExoCrypt."""
+from __future__ import annotations
+
+import argparse
+import getpass
+import sys
+from pathlib import Path
+
+from . import __version__
+from .core import encrypt_file, decrypt_file, verify_file, ExoCryptError
+from .project import protect_project, unprotect_project
+
+
+def _password(confirm=False):
+    first = getpass.getpass("Password: ")
+    if confirm:
+        second = getpass.getpass("Confirm password: ")
+        if first != second:
+            raise ValueError("passwords do not match")
+    if not first:
+        raise ValueError("password cannot be empty")
+    return first
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(
+        prog="exocrypt",
+        description="ExoCrypt 1.2.0 — chunked Argon2id + AES-256-GCM authenticated encryption."
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("protect", help="encrypt one file")
+    p.add_argument("source")
+    p.add_argument("-o", "--output")
+    p.add_argument("--overwrite", action="store_true")
+
+    p = sub.add_parser("unprotect", help="decrypt one file")
+    p.add_argument("source")
+    p.add_argument("-o", "--output", required=True)
+    p.add_argument("--overwrite", action="store_true")
+
+    p = sub.add_parser("verify", help="verify password and file integrity")
+    p.add_argument("source")
+
+    p = sub.add_parser("project", help="encrypt a whole project into one .exc file")
+    p.add_argument("source_dir")
+    p.add_argument("-o", "--output", required=True)
+    p.add_argument("--overwrite", action="store_true")
+
+    p = sub.add_parser("unproject", help="decrypt a project bundle into a directory")
+    p.add_argument("source")
+    p.add_argument("-o", "--output", required=True)
+    p.add_argument("--overwrite", action="store_true")
+    return parser
+
+
+def main(argv=None):
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "protect":
+            source = Path(args.source)
+            output = Path(args.output) if args.output else Path(str(source) + ".exc")
+            result = encrypt_file(source, output, _password(confirm=True), overwrite=args.overwrite)
+            print(f"Encrypted successfully (format v2): {result}")
+        elif args.command == "unprotect":
+            result = decrypt_file(args.source, args.output, _password(), overwrite=args.overwrite)
+            print(f"Decrypted successfully: {result}")
+        elif args.command == "verify":
+            verify_file(args.source, _password())
+            print("OK: password accepted and file authentication is valid.")
+        elif args.command == "project":
+            result = protect_project(args.source_dir, args.output, _password(confirm=True), overwrite=args.overwrite)
+            print(f"Project encrypted successfully (format v2): {result}")
+        elif args.command == "unproject":
+            result = unprotect_project(args.source, args.output, _password(), overwrite=args.overwrite)
+            print(f"Project extracted successfully: {result}")
+        return 0
+    except (OSError, ValueError, ExoCryptError) as exc:
+        print(f"exocrypt: error: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

exocrypt-1.2.0/exocrypt/core.py

@@ -0,0 +1,372 @@
+"""Versioned authenticated encryption: Argon2id + AES-256-GCM.
+
+Format v3 encrypts data in independently authenticated chunks, allowing large files
+to be processed without loading the entire file into memory. Format v1/v2 remain
+readable for backward compatibility.
+"""
+from __future__ import annotations
+
+import os
+import struct
+from pathlib import Path
+from typing import Union
+
+from argon2.low_level import Type, hash_secret_raw
+from cryptography.exceptions import InvalidTag
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
+
+PathLike = Union[str, os.PathLike]
+MAGIC = b"EXOCRYPT"
+FORMAT_VERSION = 3
+LEGACY_VERSION = 1
+PREVIOUS_VERSION = 2
+SALT_SIZE = 16
+NONCE_SIZE = 12
+NONCE_PREFIX_SIZE = 8
+KEY_SIZE = 32
+CHUNK_SIZE = 1024 * 1024
+MAX_COUNTER = 0xFFFFFFFF
+
+ARGON2_TIME_COST = 3
+ARGON2_MEMORY_COST = 65_536
+ARGON2_PARALLELISM = 4
+
+LEGACY_ITERATIONS_MIN = 100_000
+LEGACY_ITERATIONS_MAX = 5_000_000
+V1_HEADER_SIZE = len(MAGIC) + 1 + 4 + SALT_SIZE + NONCE_SIZE
+V2_HEADER_SIZE = len(MAGIC) + 1 + SALT_SIZE + NONCE_SIZE
+V3_HEADER_SIZE = len(MAGIC) + 1 + SALT_SIZE + NONCE_PREFIX_SIZE + 4
+FRAME_HEADER_SIZE = 5  # one flag byte + uint32 ciphertext length
+
+
+class ExoCryptError(Exception):
+    """Base error for ExoCrypt operations."""
+
+
+def _validate_password(password: str) -> bytes:
+    if not isinstance(password, str) or not password:
+        raise ValueError("password must be a non-empty string")
+    encoded = password.encode("utf-8")
+    if len(encoded) > 1024:
+        raise ValueError("password is too long (maximum 1024 UTF-8 bytes)")
+    return encoded
+
+
+def _derive_key_v3(password: str, salt: bytes) -> bytes:
+    return hash_secret_raw(
+        secret=_validate_password(password), salt=salt,
+        time_cost=ARGON2_TIME_COST, memory_cost=ARGON2_MEMORY_COST,
+        parallelism=ARGON2_PARALLELISM, hash_len=KEY_SIZE,
+        type=Type.ID, version=19,
+    )
+
+
+def _derive_key_v2(password: str, salt: bytes) -> bytes:
+    return _derive_key_v3(password, salt)
+
+
+def _derive_key_v1(password: str, salt: bytes, iterations: int) -> bytes:
+    raw = _validate_password(password)
+    if iterations < LEGACY_ITERATIONS_MIN or iterations > LEGACY_ITERATIONS_MAX:
+        raise ExoCryptError("invalid or unsupported legacy KDF iteration count")
+    kdf = PBKDF2HMAC(algorithm=hashes.SHA256(), length=KEY_SIZE,
+                     salt=salt, iterations=iterations)
+    return kdf.derive(raw)
+
+
+def _v3_header(salt: bytes, nonce_prefix: bytes) -> bytes:
+    return (MAGIC + bytes([FORMAT_VERSION]) + salt + nonce_prefix
+            + struct.pack(">I", CHUNK_SIZE))
+
+
+def _nonce(prefix: bytes, counter: int) -> bytes:
+    if counter > MAX_COUNTER:
+        raise ExoCryptError("file exceeds the supported chunk count")
+    return prefix + struct.pack(">I", counter)
+
+
+def _frame_aad(header: bytes, counter: int, final: bool, ciphertext_len: int) -> bytes:
+    return header + struct.pack(">I", counter) + bytes([1 if final else 0]) + struct.pack(">I", ciphertext_len)
+
+
+def _encrypt_v3_bytes(data: bytes, password: str) -> bytes:
+    salt, prefix = os.urandom(SALT_SIZE), os.urandom(NONCE_PREFIX_SIZE)
+    header = _v3_header(salt, prefix)
+    key = _derive_key_v3(password, salt)
+    aes = AESGCM(key)
+    output = bytearray(header)
+    counter = 0
+    for offset in range(0, len(data), CHUNK_SIZE):
+        chunk = data[offset:offset + CHUNK_SIZE]
+        final = offset + len(chunk) == len(data)
+        # Empty input uses an authenticated empty final frame.
+        ct_len = len(chunk) + 16
+        nonce = _nonce(prefix, counter)
+        aad = _frame_aad(header, counter, final, ct_len)
+        encrypted = aes.encrypt(nonce, chunk, aad)
+        output.extend(struct.pack(">BI", 1 if final else 0, len(encrypted)))
+        output.extend(encrypted)
+        counter += 1
+    if len(data) == 0:
+        ct_len = 16
+        encrypted = aes.encrypt(_nonce(prefix, 0), b"", _frame_aad(header, 0, True, ct_len))
+        output.extend(struct.pack(">BI", 1, len(encrypted)))
+        output.extend(encrypted)
+    return bytes(output)
+
+
+def _decrypt_v3_bytes(blob: bytes, password: str) -> bytes:
+    if len(blob) < V3_HEADER_SIZE:
+        raise ExoCryptError("file is too short or damaged")
+    offset = len(MAGIC) + 1
+    salt = blob[offset:offset + SALT_SIZE]; offset += SALT_SIZE
+    prefix = blob[offset:offset + NONCE_PREFIX_SIZE]; offset += NONCE_PREFIX_SIZE
+    chunk_size = struct.unpack(">I", blob[offset:offset + 4])[0]; offset += 4
+    if chunk_size != CHUNK_SIZE:
+        raise ExoCryptError("unsupported or invalid chunk size")
+    header = blob[:offset]
+    aes = AESGCM(_derive_key_v3(password, salt))
+    output = bytearray()
+    counter = 0
+    saw_final = False
+    while offset < len(blob):
+        if len(blob) - offset < FRAME_HEADER_SIZE:
+            raise ExoCryptError("truncated encrypted chunk header")
+        flag, ct_len = struct.unpack(">BI", blob[offset:offset + FRAME_HEADER_SIZE])
+        offset += FRAME_HEADER_SIZE
+        if flag not in (0, 1):
+            raise ExoCryptError("invalid encrypted chunk flag")
+        if ct_len < 16 or ct_len > CHUNK_SIZE + 16:
+            raise ExoCryptError("invalid encrypted chunk length")
+        if len(blob) - offset < ct_len:
+            raise ExoCryptError("truncated encrypted chunk")
+        ciphertext = blob[offset:offset + ct_len]; offset += ct_len
+        plain = aes.decrypt(_nonce(prefix, counter),
+                            ciphertext,
+                            _frame_aad(header, counter, flag == 1, ct_len))
+        if flag == 1:
+            if len(plain) > CHUNK_SIZE:
+                raise ExoCryptError("invalid final chunk size")
+            output.extend(plain)
+            saw_final = True
+            if offset != len(blob):
+                raise ExoCryptError("unexpected data after final chunk")
+            break
+        if len(plain) != CHUNK_SIZE:
+            raise ExoCryptError("invalid non-final chunk size")
+        output.extend(plain)
+        counter += 1
+        if counter > MAX_COUNTER:
+            raise ExoCryptError("file exceeds the supported chunk count")
+    if not saw_final:
+        raise ExoCryptError("encrypted file is missing its final authentication chunk")
+    return bytes(output)
+
+
+def encrypt_bytes(data: bytes, password: str) -> bytes:
+    """Encrypt bytes with the v3 chunked format (Argon2id + AES-256-GCM)."""
+    if not isinstance(data, bytes):
+        raise TypeError("data must be bytes")
+    return _encrypt_v3_bytes(data, password)
+
+
+def decrypt_bytes(blob: bytes, password: str) -> bytes:
+    """Decrypt v1, v2 and v3 ExoCrypt files."""
+    if not isinstance(blob, bytes):
+        raise TypeError("blob must be bytes")
+    if len(blob) < len(MAGIC) + 1 or blob[:len(MAGIC)] != MAGIC:
+        raise ExoCryptError("not a valid ExoCrypt file or file is too short")
+    version = blob[len(MAGIC)]
+    if version == FORMAT_VERSION:
+        try:
+            return _decrypt_v3_bytes(blob, password)
+        except InvalidTag as exc:
+            raise ExoCryptError("authentication failed: wrong password or file was modified") from exc
+    if version == PREVIOUS_VERSION:
+        if len(blob) < V2_HEADER_SIZE + 16:
+            raise ExoCryptError("file is too short or damaged")
+        offset = len(MAGIC) + 1
+        salt = blob[offset:offset + SALT_SIZE]; offset += SALT_SIZE
+        nonce = blob[offset:offset + NONCE_SIZE]; offset += NONCE_SIZE
+        header = blob[:offset]
+        try:
+            return AESGCM(_derive_key_v2(password, salt)).decrypt(nonce, blob[offset:], header)
+        except InvalidTag as exc:
+            raise ExoCryptError("authentication failed: wrong password or file was modified") from exc
+    if version == LEGACY_VERSION:
+        if len(blob) < V1_HEADER_SIZE + 16:
+            raise ExoCryptError("legacy file is too short or damaged")
+        offset = len(MAGIC) + 1
+        iterations = struct.unpack(">I", blob[offset:offset + 4])[0]; offset += 4
+        salt = blob[offset:offset + SALT_SIZE]; offset += SALT_SIZE
+        nonce = blob[offset:offset + NONCE_SIZE]; offset += NONCE_SIZE
+        header = blob[:offset]
+        try:
+            return AESGCM(_derive_key_v1(password, salt, iterations)).decrypt(nonce, blob[offset:], header)
+        except InvalidTag as exc:
+            raise ExoCryptError("authentication failed: wrong password or file was modified") from exc
+    raise ExoCryptError(f"unsupported ExoCrypt format version: {version}")
+
+
+def encrypt_file(source: PathLike, destination: PathLike, password: str, *, overwrite: bool = False) -> Path:
+    """Encrypt a file incrementally, keeping memory use bounded for large files."""
+    src, dst = Path(source), Path(destination)
+    if not src.is_file():
+        raise FileNotFoundError(f"source file not found: {src}")
+    if src.resolve() == dst.resolve():
+        raise ExoCryptError("source and destination must be different files")
+    if dst.exists() and not overwrite:
+        raise FileExistsError(f"destination already exists: {dst} (use overwrite=True to replace it)")
+    salt, prefix = os.urandom(SALT_SIZE), os.urandom(NONCE_PREFIX_SIZE)
+    header = _v3_header(salt, prefix)
+    aes = AESGCM(_derive_key_v3(password, salt))
+    temp = _temp_path(dst)
+    counter = 0
+    try:
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        with src.open("rb") as inp, temp.open("xb") as out:
+            out.write(header)
+            current = inp.read(CHUNK_SIZE)
+            if not current:
+                current = b""
+                encrypted = aes.encrypt(_nonce(prefix, 0), current, _frame_aad(header, 0, True, 16))
+                out.write(struct.pack(">BI", 1, len(encrypted)))
+                out.write(encrypted)
+            else:
+                while True:
+                    following = inp.read(CHUNK_SIZE)
+                    final = not following
+                    ct_len = len(current) + 16
+                    encrypted = aes.encrypt(_nonce(prefix, counter), current,
+                                             _frame_aad(header, counter, final, ct_len))
+                    out.write(struct.pack(">BI", 1 if final else 0, len(encrypted)))
+                    out.write(encrypted)
+                    counter += 1
+                    if final:
+                        break
+                    current = following
+            out.flush()
+            os.fsync(out.fileno())
+        os.replace(temp, dst)
+    finally:
+        try:
+            temp.unlink()
+        except FileNotFoundError:
+            pass
+    return dst
+
+
+def decrypt_file(source: PathLike, destination: PathLike, password: str, *, overwrite: bool = False) -> Path:
+    """Decrypt a v3 file incrementally; legacy v1/v2 files use the compatibility path."""
+    src, dst = Path(source), Path(destination)
+    if not src.is_file():
+        raise FileNotFoundError(f"encrypted file not found: {src}")
+    if src.resolve() == dst.resolve():
+        raise ExoCryptError("source and destination must be different files")
+    if dst.exists() and not overwrite:
+        raise FileExistsError(f"destination already exists: {dst} (use overwrite=True to replace it)")
+    with src.open("rb") as inp:
+        prefix_header = inp.read(len(MAGIC) + 1)
+        if prefix_header[:len(MAGIC)] != MAGIC:
+            raise ExoCryptError("not a valid ExoCrypt file")
+        version = prefix_header[-1]
+        if version != FORMAT_VERSION:
+            plain = decrypt_bytes(src.read_bytes(), password)
+            _atomic_write(dst, plain)
+            return dst
+        rest = inp.read(SALT_SIZE + NONCE_PREFIX_SIZE + 4)
+        if len(rest) != SALT_SIZE + NONCE_PREFIX_SIZE + 4:
+            raise ExoCryptError("file is too short or damaged")
+        header = prefix_header + rest
+        offset = 0
+        salt = rest[offset:offset + SALT_SIZE]; offset += SALT_SIZE
+        nonce_prefix = rest[offset:offset + NONCE_PREFIX_SIZE]; offset += NONCE_PREFIX_SIZE
+        chunk_size = struct.unpack(">I", rest[offset:offset + 4])[0]
+        if chunk_size != CHUNK_SIZE:
+            raise ExoCryptError("unsupported or invalid chunk size")
+        aes = AESGCM(_derive_key_v3(password, salt))
+        temp = _temp_path(dst)
+        counter = 0
+        saw_final = False
+        try:
+            dst.parent.mkdir(parents=True, exist_ok=True)
+            with temp.open("xb") as out:
+                while True:
+                    frame_header = inp.read(FRAME_HEADER_SIZE)
+                    if not frame_header:
+                        break
+                    if len(frame_header) != FRAME_HEADER_SIZE:
+                        raise ExoCryptError("truncated encrypted chunk header")
+                    flag, ct_len = struct.unpack(">BI", frame_header)
+                    if flag not in (0, 1) or ct_len < 16 or ct_len > CHUNK_SIZE + 16:
+                        raise ExoCryptError("invalid encrypted chunk header")
+                    ciphertext = inp.read(ct_len)
+                    if len(ciphertext) != ct_len:
+                        raise ExoCryptError("truncated encrypted chunk")
+                    aad = _frame_aad(header, counter, flag == 1, ct_len)
+                    plain = aes.decrypt(_nonce(nonce_prefix, counter), ciphertext, aad)
+                    if flag == 1:
+                        if len(plain) > CHUNK_SIZE:
+                            raise ExoCryptError("invalid final chunk size")
+                        out.write(plain)
+                        saw_final = True
+                        if inp.read(1):
+                            raise ExoCryptError("unexpected data after final chunk")
+                        break
+                    if len(plain) != CHUNK_SIZE:
+                        raise ExoCryptError("invalid non-final chunk size")
+                    out.write(plain)
+                    counter += 1
+                    if counter > MAX_COUNTER:
+                        raise ExoCryptError("file exceeds the supported chunk count")
+                if not saw_final:
+                    raise ExoCryptError("encrypted file is missing its final authentication chunk")
+                out.flush()
+                os.fsync(out.fileno())
+            os.replace(temp, dst)
+        except InvalidTag as exc:
+            raise ExoCryptError("authentication failed: wrong password or file was modified") from exc
+        finally:
+            try:
+                temp.unlink()
+            except FileNotFoundError:
+                pass
+    return dst
+
+
+def verify_file(source: PathLike, password: str) -> bool:
+    src = Path(source)
+    if not src.is_file():
+        raise FileNotFoundError(f"file not found: {src}")
+    # Full verification is performed, without leaving plaintext on disk.
+    with src.open("rb") as inp:
+        prefix = inp.read(len(MAGIC) + 1)
+    if len(prefix) == len(MAGIC) + 1 and prefix[:len(MAGIC)] == MAGIC and prefix[-1] == FORMAT_VERSION:
+        # Stream to a temporary destination and delete it immediately after successful authentication.
+        with __import__("tempfile").TemporaryDirectory() as td:
+            decrypt_file(src, Path(td) / "verified.bin", password, overwrite=True)
+    else:
+        decrypt_bytes(src.read_bytes(), password)
+    return True
+
+
+def _temp_path(destination: Path) -> Path:
+    return destination.with_name(destination.name + ".tmp-" + os.urandom(6).hex())
+
+
+def _atomic_write(destination: Path, data: bytes) -> None:
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    temp = _temp_path(destination)
+    try:
+        with temp.open("xb") as handle:
+            handle.write(data)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temp, destination)
+    finally:
+        try:
+            temp.unlink()
+        except FileNotFoundError:
+            pass

exocrypt-1.2.0/exocrypt/project.py

@@ -0,0 +1,96 @@
+"""Encrypt a directory into an authenticated encrypted ZIP bundle."""
+from __future__ import annotations
+
+import io
+import os
+import tempfile
+import zipfile
+from pathlib import Path
+
+from .core import encrypt_bytes, decrypt_bytes, _atomic_write, ExoCryptError
+
+
+def _safe_members(root: Path):
+    for path in sorted(root.rglob("*")):
+        if path.is_symlink():
+            raise ExoCryptError(f"symbolic links are not supported: {path}")
+        if path.is_file():
+            yield path
+
+
+def protect_project(source_dir, destination_file, password: str, *, overwrite: bool = False) -> Path:
+    source = Path(source_dir).resolve()
+    destination = Path(destination_file)
+    if not source.is_dir():
+        raise NotADirectoryError(f"project directory not found: {source}")
+    if destination.exists() and not overwrite:
+        raise FileExistsError(f"destination already exists: {destination}")
+    if destination.resolve().is_relative_to(source):
+        raise ExoCryptError("destination archive must be outside the source directory")
+
+    with tempfile.NamedTemporaryFile(suffix=".zip", delete=False) as temp:
+        temp_name = temp.name
+    try:
+        with zipfile.ZipFile(temp_name, "w", compression=zipfile.ZIP_DEFLATED) as archive:
+            for path in _safe_members(source):
+                archive.write(path, path.relative_to(source).as_posix())
+        zip_bytes = Path(temp_name).read_bytes()
+        _atomic_write(destination, encrypt_bytes(zip_bytes, password))
+    finally:
+        try:
+            os.unlink(temp_name)
+        except FileNotFoundError:
+            pass
+    return destination
+
+
+def unprotect_project(source_file, destination_dir, password: str, *, overwrite: bool = False) -> Path:
+    source = Path(source_file)
+    destination = Path(destination_dir)
+    if not source.is_file():
+        raise FileNotFoundError(f"encrypted project not found: {source}")
+    if destination.exists() and any(destination.iterdir()) and not overwrite:
+        raise FileExistsError(f"destination directory is not empty: {destination}")
+
+    plain_zip = decrypt_bytes(source.read_bytes(), password)
+
+    # Validate every ZIP entry before writing anything, preventing partial extraction
+    # when a later entry contains a traversal path or symbolic link.
+    with zipfile.ZipFile(io.BytesIO(plain_zip), "r") as archive:
+        infos = archive.infolist()
+        seen = set()
+        for member in infos:
+            name = member.filename
+            if not name or "\\x00" in name:
+                raise ExoCryptError("archive contains an invalid path")
+            target = (destination / name).resolve()
+            base = destination.resolve()
+            if target != base and base not in target.parents:
+                raise ExoCryptError("archive contains an unsafe path")
+            normalized = target.as_posix().casefold()
+            if normalized in seen:
+                raise ExoCryptError("archive contains duplicate paths")
+            seen.add(normalized)
+            mode = (member.external_attr >> 16) & 0o170000
+            if mode == 0o120000:
+                raise ExoCryptError("archive contains an unsupported symbolic link")
+            if member.flag_bits & 0x1:
+                raise ExoCryptError("encrypted ZIP entries are not supported")
+
+        destination.mkdir(parents=True, exist_ok=True)
+        for member in infos:
+            target = (destination / member.filename).resolve()
+            if member.is_dir():
+                target.mkdir(parents=True, exist_ok=True)
+            else:
+                target.parent.mkdir(parents=True, exist_ok=True)
+                # Open with exclusive creation unless overwrite was explicitly allowed.
+                if target.exists() and not overwrite:
+                    raise FileExistsError(f"destination file already exists: {target}")
+                with archive.open(member, "r") as src, target.open("wb") as dst:
+                    while True:
+                        chunk = src.read(1024 * 1024)
+                        if not chunk:
+                            break
+                        dst.write(chunk)
+    return destination

exocrypt-1.2.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ExoCrypt"
+version = "1.2.0"
+description = "Chunked authenticated encryption for files and Python project bundles"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+dependencies = [
+  "cryptography>=42.0.0",
+  "argon2-cffi>=23.1.0"
+]
+keywords = ["encryption", "python", "AES-GCM", "Argon2id", "file-protection", "CLI"]
+
+[project.scripts]
+exocrypt = "exocrypt.cli:main"
+
+[tool.setuptools]
+packages = ["exocrypt"]

exocrypt-1.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

exocrypt-1.2.0/tests/test_core.py

@@ -0,0 +1,74 @@
+import os
+import tempfile
+import unittest
+from pathlib import Path
+
+from exocrypt.core import encrypt_bytes, decrypt_bytes, ExoCryptError, encrypt_file, decrypt_file, verify_file, CHUNK_SIZE
+
+
+class EncryptionTests(unittest.TestCase):
+    def test_round_trip(self):
+        original = b"print('hello exocrypt')\n"
+        encrypted = encrypt_bytes(original, "a long test password 123!")
+        self.assertNotEqual(encrypted, original)
+        self.assertEqual(decrypt_bytes(encrypted, "a long test password 123!"), original)
+
+    def test_wrong_password_rejected(self):
+        encrypted = encrypt_bytes(b"secret", "correct password")
+        with self.assertRaises(ExoCryptError):
+            decrypt_bytes(encrypted, "incorrect password")
+
+    def test_tampering_detected(self):
+        encrypted = bytearray(encrypt_bytes(b"secret", "correct password"))
+        encrypted[-1] ^= 1
+        with self.assertRaises(ExoCryptError):
+            decrypt_bytes(bytes(encrypted), "correct password")
+
+    def test_file_helpers(self):
+        with tempfile.TemporaryDirectory() as temp:
+            root = Path(temp)
+            src = root / "sample.py"
+            enc = root / "sample.py.exc"
+            out = root / "restored.py"
+            src.write_text("print('ok')", encoding="utf-8")
+            encrypt_file(src, enc, "long enough password 123")
+            self.assertTrue(verify_file(enc, "long enough password 123"))
+            decrypt_file(enc, out, "long enough password 123")
+            self.assertEqual(out.read_text(encoding="utf-8"), "print('ok')")
+
+
+    def test_header_tampering_detected(self):
+        encrypted = bytearray(encrypt_bytes(b"secret", "correct password"))
+        encrypted[9] ^= 1
+        with self.assertRaises(ExoCryptError):
+            decrypt_bytes(bytes(encrypted), "correct password")
+
+    def test_empty_bytes_round_trip(self):
+        encrypted = encrypt_bytes(b"", "empty file password")
+        self.assertEqual(decrypt_bytes(encrypted, "empty file password"), b"")
+
+    def test_multiple_chunks_round_trip(self):
+        original = b"A" * (CHUNK_SIZE * 2 + 17)
+        encrypted = encrypt_bytes(original, "multi chunk password")
+        self.assertEqual(decrypt_bytes(encrypted, "multi chunk password"), original)
+
+    def test_streaming_file_multiple_chunks(self):
+        with tempfile.TemporaryDirectory() as temp:
+            root = Path(temp)
+            src = root / "large.bin"
+            enc = root / "large.bin.exc"
+            out = root / "restored.bin"
+            original = os.urandom(CHUNK_SIZE * 2 + 123)
+            src.write_bytes(original)
+            encrypt_file(src, enc, "stream password 123")
+            self.assertTrue(verify_file(enc, "stream password 123"))
+            decrypt_file(enc, out, "stream password 123")
+            self.assertEqual(out.read_bytes(), original)
+
+    def test_truncation_rejected(self):
+        encrypted = encrypt_bytes(b"some data", "truncation password")
+        with self.assertRaises(ExoCryptError):
+            decrypt_bytes(encrypted[:-3], "truncation password")
+
+if __name__ == "__main__":
+    unittest.main()

exocrypt-1.2.0/tests/test_project.py

@@ -0,0 +1,27 @@
+import tempfile
+import unittest
+from pathlib import Path
+
+from exocrypt.project import protect_project, unprotect_project
+from exocrypt.core import ExoCryptError
+
+
+class ProjectTests(unittest.TestCase):
+    def test_project_round_trip(self):
+        with tempfile.TemporaryDirectory() as temp:
+            root = Path(temp)
+            src = root / "source"
+            src.mkdir()
+            (src / "main.py").write_text("print('hello')", encoding="utf-8")
+            (src / "pkg").mkdir()
+            (src / "pkg" / "__init__.py").write_text("", encoding="utf-8")
+            encrypted = root / "project.exc"
+            restored = root / "restored"
+            protect_project(src, encrypted, "a long unique password 123")
+            unprotect_project(encrypted, restored, "a long unique password 123")
+            self.assertEqual((restored / "main.py").read_text(encoding="utf-8"), "print('hello')")
+            self.assertEqual((restored / "pkg" / "__init__.py").read_text(encoding="utf-8"), "")
+
+
+if __name__ == "__main__":
+    unittest.main()