Metadata-Version: 2.4
Name: keybraid
Version: 4.0.0
Summary: KeyBraid — cross-platform hybrid post-quantum master-secret encryption
Project-URL: Homepage, https://github.com/YOUR_ORG/keybraid
Project-URL: Repository, https://github.com/YOUR_ORG/keybraid
Project-URL: Documentation, https://github.com/YOUR_ORG/keybraid/tree/main/python
Project-URL: Bug Tracker, https://github.com/YOUR_ORG/keybraid/issues
Author: KeyBraid contributors
License-Expression: MIT
License-File: LICENSE
Keywords: cross-platform,encryption,hkdf,sha3,xchacha20
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.10
Requires-Dist: argon2-cffi>=23.0.0
Requires-Dist: cryptography>=49.0.0
Requires-Dist: pynacl>=1.5.0
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Description-Content-Type: text/markdown

# KeyBraid for Python

Cross-platform master-secret encryption. Encrypt on Python, decrypt on Node.js, Flutter, or Java — and vice versa.

- **Cipher:** XChaCha20-Poly1305 (AES-256-GCM fallback)
- **Key derivation:** HKDF-SHA3-512 → SHA3-512 final key
- **Spec:** [../spec/SPEC-v3.md](../spec/SPEC-v3.md)

## Requirements

- Python 3.10+
- [uv](https://docs.astral.sh/uv/) (recommended) or pip

## Installation

```bash
cd python
uv sync --extra dev
```

## Quick start

```python
from keybraid import decrypt, encrypt, derive_key1, derive_key2, key_fingerprint

package, master_secret = encrypt("secret message")
plain = decrypt(package, master_secret)

key1 = derive_key1(master_secret)
key2 = derive_key2(master_secret)
fp = key_fingerprint(master_secret)
```

## Optional password protection

```python
from keybraid import protect_master_secret

protected, salt = protect_master_secret(master_secret, "user-password")
package, _ = encrypt("data", protected)
```

## API reference

| Function | Description |
|----------|-------------|
| `generate_master_secret()` | Random 256-char Base62 master secret |
| `derive_key1(master_secret)` | Deterministic Key1 |
| `derive_key2(master_secret)` | Deterministic Key2 |
| `encrypt(plain_text, master_secret=None)` | Returns `(EncryptedPackage, master_secret)` |
| `decrypt(package, master_secret)` | Returns plaintext |
| `key_fingerprint(master_secret)` | SHA3-256 fingerprint (Base64) |
| `protect_master_secret(master_secret, password)` | Argon2id-protected master secret |

## Encrypted package

```json
{
  "version": "v3",
  "algorithm": "XChaCha20-Poly1305",
  "nonce": "...",
  "ciphertext": "...",
  "tag": "..."
}
```

## Tests

```bash
uv run pytest -q
uv run python scripts/vectors_v3.py
```

Cross-platform vectors: `../spec/test-vectors-v3.json`

## Security

- Store `master_secret` separately from the encrypted package.
- Each `encrypt()` without a master secret generates a new random master secret.
