Metadata-Version: 2.4
Name: zeroizepy
Version: 1.2.0
Summary: A Python library for secure file deletion, in-memory secret handling and cryptographic erasure.
Home-page: https://github.com/xavenordu/Xavpy-library
Author: Ordu Stephen Chinedu
Author-email: Ordu Stephen Chinedu <fordstphn@gmail.com>
License: MIT License
        
        Copyright (c) 2025 xavenordu
        
        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.
        
Project-URL: Homepage, https://github.com/xavenordu/Xavpy-library
Project-URL: Documentation, https://github.com/xavenordu/Xavpy-library
Project-URL: Repository, https://github.com/xavenordu/Xavpy-library
Project-URL: Bug Tracker, https://github.com/xavenordu/Xavpy-library/issues
Project-URL: Changelog, https://github.com/xavenordu/Xavpy-library/blob/main/CHANGELOG.md
Keywords: security,privacy,encryption,secure deletion,data sanitization,cryptography
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: System :: Archiving
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: psutil>=5.9.0
Requires-Dist: cryptography>=41.0.0
Provides-Extra: crypto
Requires-Dist: pynacl>=1.5.0; extra == "crypto"
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: hypothesis>=6.0.0; extra == "dev"
Requires-Dist: cryptography>=41.0.0; extra == "dev"
Dynamic: license-file

# ZeroizePy

High-assurance secure deletion, secure memory handling and cryptographic erasure for Python.

ZeroizePy provides a modern, cross-platform suite of primitives for handling sensitive data safely.
It is designed for applications that require defense-in-depth: password managers, HSM glue code, data-at-rest protection, secure messaging and high-security Python systems.

It includes:

* Locked, zeroizable RAM (SecureMemory)
* Secure file wiping (multi-pass overwrite, free-space wiping)
* Cryptographic erasure (destroy a key → destroy the data)
* AES-GCM authenticated encryption helpers
* Secure temporary sessions (auto-delete on exit)

---

## Installation

```bash
pip install zeroizepy
```

---

# Quick Start (Hello World)

```python
from zeroizepy.file import secure_delete
from zeroizepy.crypto import CryptoKey, encrypt_data

# Securely delete a file
secure_delete("secret.txt", passes=3)

# Encrypt something with a secure key
key = CryptoKey.generate(32)
ct = encrypt_data(b"hello world", key)
print("Encrypted:", ct.ciphertext.hex())
```

---

# Overview of Protection Layers

ZeroizePy implements five protection layers:

1. **Secure Memory**
   * Explicitly zeroizable buffers
   * Locked RAM (non-swappable when libsodium is available)
   * Safe handling for sensitive in-process secrets
   * Guaranteed wipe on .close() or context exit

2. **File Wiping**
   * Multi-pass secure deletion: random or fixed patterns (`secure_delete()`)
   * Full overwrite of file contents before unlinking
   * Free-space wiping (`wipe_free_space()`) to overwrite unallocated disk blocks
   * Symlink-aware deletion controls

3. **Cryptographic Erasure**
   * AES-GCM encryption with authenticated metadata (`CryptoKey`)
   * `CryptoKey` objects that can be destroyed in memory
   * Destroy the key → all encrypted data irreversibly lost
   * Designed for SSDs, COW filesystems, and other overwrite-hostile storage

4. **Secure Temporary Sessions**
   * `SecureSession` tracks temporary files, memory regions and secrets
   * Automatically zeroes memory and deletes files on exit
   * Ideal for one-shot secure operations

5. **OS-Level Erase Wrappers (Advanced)**
   * Interfaces for: hdparm, NVMe Secure Erase, APFS diskutil, BitLocker
   * Extremely dangerous and destructive if misused — disabled by default
   * Intended for expert operators only

---

# Quick Examples

## Cryptography Module

### Generate Key, Encrypt, and Cryptographically Erase

```python
from zeroizepy.crypto import CryptoKey, encrypt_data, decrypt_data, cryptographic_erase_key
from zeroizepy.utils import secure_clear

key = CryptoKey.generate(32)

with open("secret.txt", "rb") as f:
    plaintext = bytearray(f.read())

ct = encrypt_data(plaintext, key)

with open("secret.enc", "wb") as f:
    f.write(ct.nonce + ct.ciphertext)

secure_clear(plaintext)

recovered = decrypt_data(ct, key)
print("Recovered:", recovered.decode())

cryptographic_erase_key(key)
```

### Encrypt/Decrypt with AAD

```python
key = CryptoKey.generate()
pt = b"SENSITIVE-DATA"
aad = b"context-info"

ct = encrypt_data(pt, key, associated_data=aad)
recovered = decrypt_data(ct, key, associated_data=aad)
print(recovered)
```

---

## Secure Memory

```python
from zeroizepy.memory import SecureMemory, secret_bytes

s = SecureMemory.alloc(32)
s.write(b"supersecret")
print(s.read(11))
s.zero()
s.close()

sec = secret_bytes(b"topsecret")
print(sec.read(9))
sec.close()
```

---

## File Wiping

```python
from zeroizepy.file import secure_delete, wipe_free_space

secure_delete("secret.txt", passes=3, pattern="random")
wipe_free_space("/tmp", dry_run=True)
```

---

## Secure Session

```python
from zeroizepy.session import SecureSession

with SecureSession() as session:
    temp_file = session.create_temp_file(".txt")
    secret = session.create_secret(b"password123")

    with open(temp_file, "wb") as f:
        f.write(secret.get_bytes())
# On exit: memory zeroed, temp files deleted
```

---

# Limitations & Security Notes

## Cross-Platform Notes

| Feature                        | POSIX (Linux/macOS)                            | Windows                                                                        |
| ------------------------------ | ---------------------------------------------- | ------------------------------------------------------------------------------ |
| Symlink Handling               | Fully supported; `follow_symlinks` honored     | Some behaviors differ; tests skipped where behavior differs                    |
| Sparse File Detection          | Heuristics applied                             | Sparse heuristics differ; warnings may differ                                  |
| `chmod(0)` Permission Model    | Enforced; deletion may raise `FileAccessError` | Behavior differs; some tests skipped                                           |
| SecureMemory Zeroing           | Zeroing observable in tests                    | Observing zeroing is unreliable due to Python memory copies and OS protections |
| Memory Locking                 | `mlock` available (libsodium recommended)      | `VirtualLock` less effective; libsodium strongly preferred                     |

* Immutable Python objects (`bytes`, `str`) cannot be zeroed. Prefer `bytearray` or `memoryview`
* Libsodium recommended for locked memory
* Always use `.close()` or context manager for memory zeroing
* File system or OS limitations may prevent complete erasure on SSDs or COW filesystems

---

# Threat Model

ZeroizePy provides high-assurance secure deletion primitives, but only within realistic limits of modern operating systems.

### ZeroizePy Defends Against:

* Forensic recovery of overwritten files
* Accidental retention of plaintext in process memory
* Recovery after cryptographic key destruction
* Undeleted temp files and leaked memory buffers
* Users mistakenly loading sensitive data into Python `bytes`

### ZeroizePy cannot defend against:

* Full-disk snapshots (btrfs, ZFS, VM snapshots)
* SSD wear-leveling remapping (overwriting does not guarantee physical erasure)
* Kernel-level memory scanners
* DMA attacks or root access attackers
* Malware that runs inside the same Python process
* Cloud-provider persistent block-level backups you do not control

### Partial Mitigations

| Risk                     | What ZeroizePy Does                        |
|---------------------------|-------------------------------------------|
| SSD wear-leveling         | Recommend crypto-erasure                  |
| Python copies memory      | Encourages bytearray/memoryview           |
| OS won’t allow locked pages | Falls back with warnings                 |
| Hard failures during deletion | Raises FileAccessError                  |

---

# Testing

```bash
pytest
```

Some tests skip on Windows due to OS differences.

---

# License

MIT License — free for commercial, open-source, academic, and integrated use.
