Metadata-Version: 2.4
Name: opaque-logger
Version: 0.1.1
Summary: Deterministic Data Masking Engine with Mathematical Validation - No AI Guessing
Author-email: Samuel Silva <samuelsilvass@github.com>
License: MIT
Project-URL: Homepage, https://github.com/SamuelSilvass/OPAQUE
Project-URL: Documentation, https://github.com/SamuelSilvass/OPAQUE#readme
Project-URL: Repository, https://github.com/SamuelSilvass/OPAQUE
Project-URL: Issues, https://github.com/SamuelSilvass/OPAQUE/issues
Keywords: security,gdpr,lgpd,masking,logging,data-protection,cpf,cnpj,pii,privacy
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cryptography>=41.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Dynamic: license-file

<div align="center">

# 🛡️ OPAQUE

### **Deterministic Data Masking Engine**

*Don't guess if it's a CPF. Prove it mathematically.*

[![Tests](https://img.shields.io/badge/tests-24%20passed-brightgreen?style=for-the-badge)](https://github.com/SamuelSilvass/OPAQUE)
[![Python](https://img.shields.io/badge/python-3.8%2B-blue?style=for-the-badge&logo=python)](https://www.python.org/)
[![PyPI](https://img.shields.io/badge/PyPI-opaque--logger-blue?style=for-the-badge&logo=pypi)](https://pypi.org/project/opaque-logger/)
[![License](https://img.shields.io/badge/license-MIT-green?style=for-the-badge)](LICENSE)

[🇺🇸 English](docs/README_EN.md) | [🇧🇷 Português](docs/README_PT.md) | [🇪🇸 Español](docs/README_ES.md)

---

### **The only data masking library that uses MATH, not AI**

</div>

## 🎯 Why OPAQUE?

Unlike AI-based solutions that **guess**, OPAQUE **validates** using mathematical algorithms:

| Feature | AI Solutions | OPAQUE |
|---------|-------------|---------|
| **Validation** | Neural networks (guessing) | Mathematical algorithms (proof) |
| **False Positives** | Common | Zero |
| **Performance** | Slow (GPU required) | Ultra-fast (pure math) |
| **Debuggability** | Black box | Deterministic hashing |
| **Reversibility** | No | Yes (Vault Mode) |

## ✨ Key Features

<table>
<tr>
<td width="50%">

### 🔐 **Mathematical Validation**
- **CPF**: Mod 11 algorithm
- **CNPJ**: Weighted Mod 11
- **Credit Cards**: Luhn algorithm
- **Pix**: Format validation

</td>
<td width="50%">

### 🏦 **Vault Mode**
- AES-256 encryption
- Reversible for debugging
- CLI decryption tool
- Master key protection

</td>
</tr>
<tr>
<td width="50%">

### 🍯 **Honeytokens**
- Intrusion detection
- Bait data alerts
- Real-time monitoring
- Security integration

</td>
<td width="50%">

### ⚡ **Circuit Breaker**
- Flood protection
- Auto-recovery
- Resource optimization
- Server stability

</td>
</tr>
</table>

## 🚀 Quick Start

### Installation

```bash
pip install opaque-logger
```

### Basic Usage

```python
import logging
from opaque import OpaqueLogger, Validators

# Configure
OpaqueLogger.setup_defaults(
    rules=[Validators.BR.CPF, Validators.BR.CNPJ],
    obfuscation_method="HASH"
)

# Integrate
logging.setLoggerClass(OpaqueLogger)
logger = logging.getLogger("app")

# Log securely
logger.info("User CPF: 529.982.247-25")
# Output: User CPF: [HASH-3A4C]
```

## 📊 Performance Benchmarks

```
Sanitization:     1,000+ messages/sec
CPF Validation:   65,000+ ops/sec
CNPJ Validation:  68,000+ ops/sec
Credit Card:      122,000+ ops/sec
Vault Encryption: 22,000+ ops/sec
```

## 🧪 Test Coverage

```bash
pytest -v
```

**Results:** ✅ **24/24 tests passing** (100% success rate)

## 📚 Examples

<details>
<summary><b>🔹 Vault Mode (Reversible Encryption)</b></summary>

```python
OpaqueLogger.setup_defaults(
    obfuscation_method="VAULT",
    vault_key="your-master-key"
)

logger.info("Processing CPF 529.982.247-25")
# Output: Processing CPF [VAULT:gAAAAABl...]

# Decrypt later
python -m opaque.cli reveal "[VAULT:gAAAAABl...]" --key=your-master-key
# Output: 🔓 REVEALED DATA: 529.982.247-25
```

</details>

<details>
<summary><b>🔹 Honeytokens (Intrusion Detection)</b></summary>

```python
OpaqueLogger.setup_defaults(
    honeytokens=["999.888.777-66"]  # Bait CPF
)

logger.info("Access with CPF 999.888.777-66")
# Stderr: 🚨 ALERTA VERMELHO: HONEYTOKEN DETECTED
# Output: Access with CPF [HONEYTOKEN TRIGGERED]
```

</details>

<details>
<summary><b>🔹 Crash Handler (Traceback Sanitization)</b></summary>

```python
from opaque import install_crash_handler

install_crash_handler()

# Now all crashes sanitize sensitive data
password = "secret123"
cpf = "529.982.247-25"
raise ValueError(f"Error: {cpf}")
# Traceback shows: ValueError: Error: [HASH-3A4C]
# Locals show: password = [REDACTED_SECRET_KEY]
```

</details>

<details>
<summary><b>🔹 Compliance Scanning</b></summary>

```bash
python -m opaque.cli scan ./src --output=report.html
# Output: 🛡️ Security Score: 98%
```

</details>

## 🏗️ Architecture

```
┌─────────────────────────────────────────────────────┐
│                   OPAQUE Engine                     │
├─────────────────────────────────────────────────────┤
│  1. Regex Pattern Matching (Context-Aware)         │
│  2. Mathematical Validation (Mod 11, Luhn)         │
│  3. Honeytoken Detection                            │
│  4. Circuit Breaker Check                           │
│  5. Obfuscation (Hash/Vault/Mask)                  │
└─────────────────────────────────────────────────────┘
```

## 🌍 Supported Validators

### 🇧🇷 Brazil
- ✅ **CPF** - Individual taxpayer ID
- ✅ **CNPJ** - Company taxpayer ID  
- ✅ **Pix** - Instant payment keys

### 💳 Finance
- ✅ **Credit Cards** - Visa, Mastercard, Amex, etc.

### 🔜 Coming Soon
- CNH (Driver's License)
- Renavam (Vehicle Registration)
- Mercosul License Plates

## 📖 Documentation

| Language | Link |
|----------|------|
| 🇺🇸 English | [Complete Guide](docs/README_EN.md) |
| 🇧🇷 Português | [Guia Completo](docs/README_PT.md) |
| 🇪🇸 Español | [Guía Completa](docs/README_ES.md) |

## 🤝 Contributing

We welcome contributions! See our [Contributing Guide](CONTRIBUTING.md).

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🔗 Links

- **PyPI Package**: [opaque-logger](https://pypi.org/project/opaque-logger/)
- **Issues**: [GitHub Issues](https://github.com/SamuelSilvass/OPAQUE/issues)
- **Changelog**: [CHANGELOG.md](CHANGELOG.md)

---

<div align="center">

### **Built with precision by Samuel Silva**

*Protecting data with mathematics, not magic* ✨

[![GitHub Stars](https://img.shields.io/github/stars/SamuelSilvass/OPAQUE?style=social)](https://github.com/SamuelSilvass/OPAQUE)
[![GitHub Forks](https://img.shields.io/github/forks/SamuelSilvass/OPAQUE?style=social)](https://github.com/SamuelSilvass/OPAQUE/fork)

</div>
