Metadata-Version: 2.4
Name: qorechain-qoreseal
Version: 0.1.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Rust
Classifier: Topic :: Security :: Cryptography
Classifier: Typing :: Typed
License-File: LICENSE
License-File: NOTICE
Summary: ML-KEM-1024 (FIPS 203) encryption of data to QoreChain accounts: hybrid X25519 mode, multi-recipient envelopes, recipient cards and epoch keys.
Keywords: qorechain,ml-kem,fips-203,encryption,x25519,post-quantum
Author: QoreChain Association
License-Expression: Apache-2.0
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Changelog, https://github.com/qorechain/qoreseal/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/qorechain/qoreseal/tree/main/python
Project-URL: Homepage, https://github.com/qorechain/qoreseal
Project-URL: Issues, https://github.com/qorechain/qoreseal/issues
Project-URL: Repository, https://github.com/qorechain/qoreseal

# qorechain-qoreseal (Python)

ML-KEM-1024 (FIPS 203) encryption of data to QoreChain accounts, for Python 3.9+.
The package wraps the Rust implementation through UniFFI, so its output is
byte-identical to the TypeScript, Rust, Go, Swift and Kotlin packages; all of
them are checked against `vectors/qoreseal-v1.json`.

## Install

```sh
pip install qorechain-qoreseal
```

Wheels: macOS (arm64, x86_64), Linux (manylinux2014 x86_64, aarch64), Windows x86_64.

## Example

```python
import qoreseal as qs

alice = qs.generate_seal_keys()
bob = qs.generate_seal_keys()

envelope = qs.seal_envelope(
    "qorechain-diana", "invoice",
    [qs.recipient_of(alice), qs.recipient_of(bob)],
    b"amount due: 120 QOR",
    aad=b"invoice-42",
)
text = qs.envelope_to_text(envelope)  # "qoreseal:..."

plaintext = qs.open_envelope("qorechain-diana", "invoice", envelope, bob, aad=b"invoice-42")
assert plaintext == b"amount due: 120 QOR"
```

- `mode=qs.SealMode.MLKEM` uses the recipient's ML-KEM-1024 key alone; the default
  `HYBRID` adds X25519 and needs the recipient's card (`verify_recipient_card`).
- Keys from a mnemonic: `qs.derive_seal_keys(mnemonic)`; back up the mnemonic or
  `keys.seed`.
- Publish your key: `qs.build_register_kem_key_message(address, keys.mlkem_public_key)`,
  then sign the transaction hybrid (QoreSign). The KEM key registry is available
  on testnet; on mainnet from the v3.2.5 upgrade.
- Private groups: `qs.EpochKeyManager`, `qs.seal_batch`, `qs.open_batch`.

Errors raise `qs.QoreSealError.Failure` with a stable `code`.

## Limits

Only the payload is confidential: addresses, amounts, timing and sizes stay
public; no zero-knowledge proof is involved; envelopes are not signed; losing the
seed or mnemonic loses access to the data. The construction is pending external
review before 1.0.

## License

Apache-2.0.

