# Security Policy

## Supported Versions

| Version | Supported          |
| ------- | ------------------ |
| 0.1.x   | :white_check_mark: |

## Reporting a Vulnerability

**DO NOT** open a public issue for security vulnerabilities.

Instead, please report security issues privately to:

**Email**: security@example.com (replace with actual contact)

### What to Include

1. **Description** of the vulnerability
2. **Steps to reproduce** the issue
3. **Potential impact** assessment
4. **Suggested fix** (if you have one)

### Response Timeline

- **Initial response**: Within 48 hours
- **Status update**: Within 7 days
- **Fix timeline**: Depends on severity
  - Critical: 1-7 days
  - High: 7-30 days
  - Medium: 30-90 days

## Security Best Practices

### For Users

1. **Use strong passwords**
   - Minimum 16 characters
   - Mix uppercase, lowercase, numbers, symbols
   - Don't reuse passwords

2. **Protect encryption keys**
   - Never hardcode passwords in source
   - Use environment variables or secure vaults
   - Don't store passwords with encrypted data

3. **Verify integrity**
   - Always handle decryption errors properly
   - Authentication failures indicate wrong password OR tampering
   - Never ignore `ValueError` exceptions

4. **Keep updated**
   - Update to latest version regularly
   - Monitor security advisories
   - Check `CHANGELOG.md` for security fixes

### For Developers

1. **Dependency management**
   - Run `cargo audit` regularly
   - Update dependencies for security patches
   - Review dependency changes

2. **Code review**
   - All crypto code must be reviewed
   - Use `cargo clippy` and address warnings
   - Run test suite before commits

3. **Testing**
   - Write tests for security-critical code
   - Test error conditions
   - Verify authentication failures work correctly

## Known Limitations

### Out of Scope

This library **does NOT** protect against:

1. **Compromised runtime environment**
   - Malware on the system
   - Keyloggers
   - Memory dumps from compromised OS

2. **Physical attacks**
   - Cold boot attacks
   - Physical access to hardware
   - Side-channel attacks on hardware

3. **Social engineering**
   - Phishing for passwords
   - Social manipulation
   - Insider threats

4. **Weak passwords**
   - Dictionary words
   - Short passwords
   - Common patterns

### By Design

1. **Key derivation is slow** (~50ms)
   - This is intentional (Argon2id security property)
   - Prevents brute force attacks
   - Do NOT try to "optimize" this away

2. **No key recovery**
   - Lost password = lost data
   - No backdoors or recovery mechanisms
   - This is a feature, not a bug

3. **No compression**
   - Library doesn't compress before encryption
   - Compress your data first if needed
   - Prevents compression-based attacks

## Cryptographic Details

### Algorithms

- **XChaCha20-Poly1305**: Modern AEAD cipher
  - Published: 2018
  - Security: 256-bit security
  - Status: Widely reviewed, no known vulnerabilities

- **Argon2id**: Password hashing
  - Published: 2015
  - Security: Memory-hard (64 MiB)
  - Status: Winner of Password Hashing Competition

### Implementation

- Uses [RustCrypto](https://github.com/RustCrypto) libraries
- Audited implementations
- Constant-time operations where relevant
- No unsafe crypto patterns

### Parameters

```rust
// Argon2id
Memory: 64 MiB (65536 KiB)
Time: 3 iterations
Parallelism: 4 lanes
Output: 32 bytes

// XChaCha20-Poly1305
Key size: 256 bits
Nonce size: 192 bits
Tag size: 128 bits
```

## Audit Status

- **Last audit**: Not yet audited
- **Planned audit**: TBD
- **Audit firm**: TBD

**Note**: This library has not undergone formal security audit. Use at your own risk for production systems. Consider getting a professional security audit before use in critical applications.

## Disclosure Policy

When a vulnerability is fixed:

1. **Private notification** to reporter
2. **Patch release** published to PyPI
3. **Public disclosure** 7 days after patch
4. **CVE assigned** if applicable
5. **Security advisory** published on GitHub

## Contact

- **General questions**: Open a GitHub issue
- **Security issues**: security@example.com
- **Urgent issues**: Include [URGENT] in subject line

---

**Thank you** for helping keep Irene Cipher secure!
