Metadata-Version: 2.4
Name: seigr-toolset-crypto
Version: 0.3.1
Summary: Post-classical cryptographic engine with intelligent security profiles and high-performance streaming
Home-page: https://github.com/Seigr-lab/SeigrToolsetCrypto
Author: Sergi Saldaña-Massó - Seigr Lab
Author-email: sergism@gmail.com
Project-URL: Homepage, https://github.com/Seigr-lab/SeigrToolsetCrypto
Project-URL: Documentation, https://github.com/Seigr-lab/SeigrToolsetCrypto#readme
Project-URL: Source, https://github.com/Seigr-lab/SeigrToolsetCrypto
Project-URL: Sponsor, https://github.com/sponsors/Seigr-lab
Project-URL: Changelog, https://github.com/Seigr-lab/SeigrToolsetCrypto/blob/main/CHANGELOG.md
Keywords: cryptography,seigr,entropy,intelligent,security,profiles,adaptive,streaming,post-classical,ai
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Information Technology
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Security
Classifier: Topic :: System :: Systems Administration
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Seigr Toolset Crypto (STC)

[![Sponsor Seigr-lab](https://img.shields.io/badge/Sponsor-Seigr--lab-forestgreen?style=flat&logo=github)](https://github.com/sponsors/Seigr-lab)
[![Version](https://img.shields.io/badge/version-0.3.1-blue)](https://github.com/Seigr-lab/SeigrToolsetCrypto/releases)
[![License](https://img.shields.io/badge/license-ANTI--CAPITALIST-red)](LICENSE)

**Post-classical cryptographic engine with intelligent security profiles and adaptive protection**

## Overview

STC v0.3.1 is a production-ready cryptographic system that combines post-classical security with intelligent user experience. It rejects traditional symmetric/asymmetric paradigms, implementing advanced cryptographic techniques with AI-powered security optimization:

### 🧠 **NEW in v0.3.1: Intelligent Security**

- **Smart Security Profiles** - Auto-detects file types and applies optimal security
- **19+ Specialized Profiles** - Financial, Medical, Legal, Technical, and more
- **AI Content Analysis** - Analyzes file content to recommend perfect security settings
- **Adaptive Security** - Automatically responds to threat patterns
- **Command-Line Interface** - Simple encryption without programming

### 🔒 **Core Cryptographic Engine**

- **Continuous Entropy Lattice (CEL)** - Self-evolving entropy field with health monitoring
- **Probabilistic Hashing Engine (PHE)** - Multi-path hashing with adaptive difficulty scaling
- **Contextual Key Emergence (CKE)** - Ephemeral keys reconstructed from context intersections
- **Data-State Folding (DSF)** - Encryption via multidimensional tensor folding
- **Polymorphic Cryptographic Flow (PCF)** - Context-adaptive algorithmic morphing
- **Enhanced Decoy Polymorphism** - Variable-size decoy vectors with timing randomization
- **State Management** - Encrypted persistence with plausible deniability

## Architecture

```
core/
├── cel/       # Continuous Entropy Lattice
├── phe/       # Probabilistic Hashing Engine  
├── cke/       # Contextual Key Emergence
├── dsf/       # Data-State Folding
├── pcf/       # Polymorphic Cryptographic Flow
├── state/     # State persistence and reconstruction
└── profiles/  # 🆕 Intelligent Security Profiles
    ├── security_profiles.py      # 5 basic profiles (Document, Media, etc.)
    ├── intelligent_profiles.py   # 19+ AI-powered profiles  
    ├── adaptive_security.py      # Threat-responsive security
    └── content_optimizers.py     # Profile-specific optimizations

interfaces/
├── api/       # Programmatic interface
├── cli/       # 🆕 Enhanced command-line tools
└── bindings/  # Future cross-language bindings

utils/         # Mathematical primitives + TLV varint encoding
tests/         # Validation and integrity checks (100+ tests)
```

## ⚡ Performance & Usability (v0.3.1)

### 🚀 **Ultra-Fast Streaming (NEW)**

- **High-Performance Streaming**: >100GB files at 50+ MB/s
- **Constant Memory Usage**: Only 7MB RAM regardless of file size
- **Upfront Validation**: 3-5x faster decryption via early decoy validation
- **Auto-Optimization**: Perfect settings chosen automatically per file type

### 🎯 **Intelligent Performance (NEW)**

- **Smart Profile Selection**: Optimal speed/security balance per file type
- **Content-Aware Optimization**: Different settings for photos vs documents vs credentials
- **Adaptive Security**: Increases protection automatically when threats detected
- **One-Command Usage**: `stc-cli encrypt --intelligent` handles everything

### 📊 **Benchmark Results**

- **Document files**: ~0.8s encryption, ~200KB metadata (balanced profile)
- **Media files**: ~0.5s encryption, ~150KB metadata (speed-optimized profile)  
- **Credential files**: ~2.0s encryption, ~500KB metadata (maximum security profile)
- **Large streaming**: 50-100 MB/s throughput, constant 7MB memory

> **Design Philosophy**: Intelligence over configuration. STC automatically chooses optimal settings based on what you're encrypting, eliminating complex parameter tuning while maximizing both security and performance.

> **Version History**:
>
> - **v0.3.1**: Intelligent profiles + high-performance streaming + CLI interface
> - v0.3.0: Security-first with 2.9x optimized performance (smaller decoy lattices)
> - v0.2.1: 1.95x faster than v0.2.0, 65% smaller metadata via varint encoding
> - v0.2.0: 76x faster than v0.1.0 via systematic optimizations

## Installation

### From PyPI (Recommended)

```bash
pip install seigr-toolset-crypto==0.3.1
```

### From GitHub Release

Download the latest release from [Releases](https://github.com/Seigr-lab/SeigrToolsetCrypto/releases):

```bash
# Install from wheel (recommended)
pip install seigr_toolset_crypto-0.3.1-py3-none-any.whl

# Or install from source tarball
pip install seigr_toolset_crypto-0.3.1.tar.gz
```

### From Source (Development)

```bash
git clone https://github.com/Seigr-lab/SeigrToolsetCrypto.git
cd SeigrToolsetCrypto
pip install -e .
```

### Requirements

- Python 3.9+
- NumPy 1.24.0+

## 🚀 Get Started in 30 Seconds

### Option 1: Complete Beginner (No Programming)

```bash
# Install STC
pip install seigr-toolset-crypto==0.3.1

# Encrypt any file - STC figures out everything automatically
stc-cli encrypt --input my_file.pdf --intelligent --password "my_password"

# That's it! STC analyzed your file and applied perfect security settings
```

### Option 2: See What STC Detects

```bash
# Ask STC what it thinks about your file
stc-cli analyze --input my_document.pdf

# Output example:
# 📄 File: my_document.pdf (2.1 MB)
# 🔍 Content Type: financial_document  
# 🎯 Recommended Profile: FINANCIAL_DATA
# 📊 Confidence Score: 0.94
# 🛡️ Security Level: high
# 📝 Reason: Contains financial data patterns including account numbers
```

### Option 3: I'm a Developer

```python
# Install and import
pip install seigr-toolset-crypto==0.3.1

from core.profiles import get_profile_for_file
from stc import STCContext

# Let STC choose optimal settings
profile = get_profile_for_file("my_file.pdf")  # Auto-detects "document"
ctx = STCContext("my-app")
encrypted, metadata = ctx.encrypt_file("my_file.pdf", "password", intelligent_profile=profile)
```

## Detailed Examples

### 🚀 **Easiest Way: Command Line (NEW in v0.3.1)**

```bash
# Encrypt any file - STC automatically detects type and applies perfect security
stc-cli encrypt --input my_document.pdf --intelligent --password "my_password"

# Decrypt  
stc-cli decrypt --input my_document.pdf.enc --password "my_password"

# Get smart recommendations for any file
stc-cli analyze --input family_photo.jpg
# Output: "Detected: MEDIA, Recommended: media profile, Reason: Large image file optimized for speed"
```

### 🧠 **Smart Profiles: Auto-Detection (NEW)**

```python
from core.profiles import get_profile_for_file, get_optimized_parameters
from stc import STCContext

# STC automatically detects what you're encrypting
profile = get_profile_for_file("tax_return.pdf")     # Returns "document"
profile = get_profile_for_file("family_photo.jpg")   # Returns "media" 
profile = get_profile_for_file("passwords.txt")      # Returns "credentials"

# Get perfect parameters automatically
params = get_optimized_parameters(profile, file_size=2048000)

# Encrypt with optimized settings
ctx = STCContext("my-app")
encrypted, metadata = ctx.encrypt_file("tax_return.pdf", "password", profile_params=params)
```

### 🤖 **AI Content Analysis (ADVANCED)**

```python
from core.profiles import IntelligentSecurityProfileManager

# AI analyzes file content and recommends perfect security
result = IntelligentSecurityProfileManager.analyze_and_recommend(
    file_path="sensitive_document.pdf"
)

print(f"🔍 Detected: {result['content_type']}")           # "financial_document"  
print(f"🎯 Recommended: {result['recommended_profile']}")  # "FINANCIAL_DATA"
print(f"📊 Confidence: {result['confidence_score']:.2f}") # 0.94
print(f"📝 Reason: {result['analysis_reason']}")          # "Contains tax information and account numbers"
```

### 🛠️ **Traditional Programming (Full Control)**

```python
from interfaces.api.stc_api import STCContext

# Manual approach for developers
ctx = STCContext('my-unique-seed')
encrypted, metadata = ctx.encrypt("Secret message", password="strong_password")
decrypted = ctx.decrypt(encrypted, metadata, password="strong_password")
print(decrypted)  # "Secret message"
```

### 🏥 **Real-World Examples**

```bash
# Secure family photos for cloud backup
stc-cli encrypt-folder --input "Family Photos" --profile media --password "family_2024"

# Maximum security for financial documents  
stc-cli encrypt --input "tax_return.pdf" --profile credentials --password "tax_secure_2024"

# Fast backup encryption
stc-cli encrypt --input "system_backup.tar.gz" --profile backup --password "backup_2024"
```

### 🔬 **Advanced: Custom Intelligence**

```python
# AI with custom compliance requirements
result = IntelligentSecurityProfileManager.analyze_and_recommend(
    file_path="patient_record.pdf",
    compliance_requirements=["HIPAA"],
    security_priority="maximum"
)

# Adaptive security that responds to threats
from core.profiles import AdaptiveSecurityManager
adaptive = AdaptiveSecurityManager()
adaptive.detect_threat("brute_force_attempt")  # Auto-increases security
```

### Basic API (No Password)

```python
from interfaces.api import stc_api

# Initialize STC context
context = stc_api.initialize(seed="your-seed-phrase")

# Encrypt data (uses seed as password)
encrypted, metadata = context.encrypt("sensitive information")

# Decrypt data
decrypted = context.decrypt(encrypted, metadata)
print(decrypted)  # "sensitive information"

# Generate probabilistic hash
hash_result = context.hash("data to hash")
```

### Quick API (One-liners)

```python
from interfaces.api import stc_api

# Quick encrypt - returns encrypted data, metadata, and context
encrypted, metadata, context = stc_api.quick_encrypt(
    "sensitive data", 
    seed="your-seed"
)

# Quick decrypt - reconstructs context from metadata
decrypted = stc_api.quick_decrypt(
    encrypted, 
    metadata, 
    seed="your-seed"
)
```

## Usage

### Advanced: Custom Parameters

```python
from interfaces.api.stc_api import STCContext

# Custom lattice and security parameters
context = STCContext(
    seed="your-seed",
    lattice_size=128,      # Default: 128 (optimized in v0.2.0)
    depth=6,               # Default: 6 (optimized in v0.2.0)
    morph_interval=100,    # PCF morphing interval
    adaptive_morphing=True,  # v0.3.0: CEL-delta-driven intervals
    adaptive_difficulty='balanced'  # v0.3.0: 'fast', 'balanced', 'paranoid'
)

# Encrypt with custom context and v0.3.0 features
encrypted, metadata = context.encrypt(
    "data",
    password="password123",
    use_decoys=True,           # v0.3.0: Enabled by default
    num_decoys=3,              # v0.3.0: Default count
    variable_decoy_sizes=True  # v0.3.0: Polymorphic decoys
)

# Derive keys
key = context.derive_key(length=32)

# Hash data
hash_value = context.hash("data")
```

### State Management

```python
# Save context state
state = context.save_state()

# Load state (for resuming)
context.load_state(state)

# Get context status
status = context.get_status()
print(status)
```

## Features

### 🆕 v0.3.1 "Intelligent Security & High-Performance Streaming"

#### 🧠 **Intelligent Security Profiles**

- ✅ **5 Basic Profiles** - Document, Media, Credentials, Backup, Custom
- ✅ **19+ AI Profiles** - Financial, Medical, Legal, Technical, Government, etc.
- ✅ **Auto-Detection** - Analyzes file type/content and recommends perfect profile
- ✅ **Content Analysis** - Detects sensitive patterns (SSN, credit cards, medical terms)
- ✅ **Adaptive Security** - Automatically responds to detected threats
- ✅ **Compliance Ready** - HIPAA, GDPR, SOX-compliant profiles available

#### ⚡ **High-Performance Streaming**

- ✅ **Ultra-Fast Streaming** - >100GB files at 50+ MB/s throughput
- ✅ **Constant Memory** - Only 7MB RAM usage regardless of file size
- ✅ **Upfront Validation** - 3-5x faster decryption via early decoy verification
- ✅ **Streaming Integration** - Works seamlessly with all security profiles

#### 🖥️ **Command-Line Interface**

- ✅ **Simple Commands** - `stc-cli encrypt --intelligent` handles everything
- ✅ **Batch Operations** - Encrypt/decrypt entire folders
- ✅ **Smart Recommendations** - `stc-cli analyze` gives perfect suggestions
- ✅ **No Programming Required** - Accessible to non-technical users

### v0.3.0 "Adaptive Security & Transparency"

- ✅ **Entropy Health API** - Quality scoring, threshold enforcement, detailed metrics
- ✅ **Enhanced Decoy Polymorphism** - Variable sizes (32×3 to 96×5), randomized counts
- ✅ **Context-Adaptive Morphing** - CEL-delta-driven intervals (50/100/200 ops)
- ✅ **Adaptive Difficulty Scaling** - Oracle attack detection, dynamic path scaling
- ✅ **Security-First Design** - All features enabled by default

### Core Features (v0.2.0+)

- ✅ **Password-based encryption** with MAC verification
- ✅ **Metadata encryption** using ephemeral keys
- ✅ **Binary TLV format** for compact metadata storage
- ✅ **CEL entropy amplification** with timing chains and multi-tier feedback
- ✅ **PHE multi-path hashing** (3-15 parallel paths, adaptive)
- ✅ **Entropy quality auditing** and collision monitoring

### Current Performance (v0.3.1)

- **Intelligent Profiles**: Auto-optimized performance per file type
- **Streaming**: 50-100 MB/s throughput, 7MB constant memory
- **Document Profile**: ~0.8s encryption, ~200KB metadata (balanced)
- **Media Profile**: ~0.5s encryption, ~150KB metadata (speed-optimized)
- **Credentials Profile**: ~2.0s encryption, ~500KB metadata (maximum security)

### Production Readiness (v0.3.1)

- ✅ **100+ Tests Passing** - Comprehensive test coverage
- ✅ **Intelligent Defaults** - Perfect settings chosen automatically
- ✅ **Non-Technical Friendly** - Command-line interface for anyone
- ✅ **Enterprise Features** - Compliance profiles, audit trails, threat response
- ⚠️ **Security Audit Pending** - Formal cryptographic review in progress

See [CHANGELOG.md](CHANGELOG.md) for detailed version history and [docs/PERFORMANCE.md](docs/PERFORMANCE.md) for optimization details.

## Why Choose STC v0.3.1?

### 🧠 **Intelligence Over Configuration**

- **Zero Configuration**: `stc-cli encrypt --intelligent` handles everything automatically
- **AI Content Analysis**: Detects what you're encrypting and applies perfect security
- **Smart Recommendations**: Always know the optimal settings for your files
- **Adaptive Security**: Automatically responds to threats and attack patterns

### ⚡ **Performance Without Compromise**

- **Intelligent Optimization**: Different profiles for documents, photos, credentials, backups
- **High-Speed Streaming**: >100GB files at 50+ MB/s with only 7MB RAM
- **Perfect Balance**: Optimal speed/security ratio automatically chosen per file type
- **Enterprise Ready**: HIPAA, GDPR, SOX compliance profiles available

### 🛡️ **Advanced Security Made Simple**

- **Post-Classical Cryptography**: No XOR, no block ciphers, no legacy vulnerabilities
- **Adaptive Polymorphism**: Security evolves based on usage patterns
- **Threat Response**: Automatically increases protection when attacks detected
- **Self-Sovereign**: No cloud dependencies, complete user control

### 👥 **For Everyone**

- **Non-Programmers**: Simple command-line interface, no coding required
- **Developers**: Rich Python API with intelligent profile integration
- **Enterprises**: Compliance-ready profiles, audit trails, centralized management
- **Security Professionals**: Advanced cryptographic techniques with intelligent optimization

## Core Principles

1. **Intelligence over complexity** - STC chooses optimal settings automatically
2. **Security by default** - Maximum protection without manual configuration
3. **Performance through intelligence** - Smart optimization, not feature reduction
4. **Universal accessibility** - From command-line to enterprise API
5. **Adaptive protection** - Security evolves with threats and usage patterns
6. **Self-sovereign control** - No external dependencies, complete user ownership

## Examples

See `examples/` directory for practical demonstrations:

- **`password_manager/`** - Secure credential storage with intelligent profiles
- **`config_encryption/`** - Configuration file encryption with auto-detection
- **`entropy_health/`** - Entropy monitoring and quality threshold examples
- **`validation/`** - Security profile validation and testing examples

Also see comprehensive user manual at `docs/user_manual/` with step-by-step guides for:

- **Security Profiles** - Auto-detection and smart recommendations
- **Command-Line Usage** - Simple encryption without programming
- **Intelligent Profiles** - AI-powered content analysis
- **Real-World Scenarios** - Complete examples for common use cases

Run examples:

```bash
cd examples/password_manager
python password_manager.py

cd examples/config_encryption
python config_example.py

cd examples/entropy_health
python entropy_monitoring.py
```

## Testing

Run the full test suite:

```bash
# Run all tests
python -m pytest tests/ -v

# Run specific test modules
python -m pytest tests/test_cel.py -v
python -m pytest tests/test_phe.py -v
python -m pytest tests/test_integration_v031.py -v
python -m pytest tests/test_intelligent_security_system.py -v
```

All 100+ tests pass in v0.3.1 (including intelligent security system tests).

## Development Status

**v0.3.1** - Production-ready with intelligent security and high-performance streaming

### 🎯 **What's New in v0.3.1**

- ✅ **Intelligent Security Profiles** - 19+ AI-powered profiles with content analysis
- ✅ **High-Performance Streaming** - >100GB files, 50+ MB/s, 7MB constant memory
- ✅ **Command-Line Interface** - Simple encryption for non-programmers
- ✅ **Adaptive Security** - Automatic threat response and optimization
- ✅ **100+ Tests** - Comprehensive validation including intelligent features

### Roadmap

- **v0.3.2**: Additional intelligent profiles, enhanced CLI features
- **v0.4.0**: Hardware acceleration (SIMD/GPU), formal verification
- **v1.0.0**: Security audit, quantum resistance, stable API

## Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new features
4. Submit a pull request

See [docs/](docs/) for architecture and API documentation.

## License

ANTI-CAPITALIST SOFTWARE LICENSE (v 1.4) - See LICENSE file for details

---

## Citation

If you use STC in research, please cite:

```bibtex
@software{seigr_toolset_crypto,
  title = {Seigr Toolset Crypto: Intelligent Post-Classical Cryptographic Engine},
  author = {Seigr-lab},
  year = {2025},
  version = {0.3.1},
  url = {https://github.com/Seigr-lab/SeigrToolsetCrypto}
}
```
