========================================
Copius Cipher Chain Cryptography Library
========================================

Overview
========
``ccc_dart_plugin`` is the **Flutter/Dart bridge layer** for the CCC
cryptographic system.

It exposes the Rust-based ``ccc_rust`` crypto providers to Flutter
applications via ``flutter_rust_bridge`` while maintaining strict
architectural separation from both:

* The Rust crypto implementation
* The LetUsMsg application

This repository contains:

* A small Rust bridge crate referencing ``ccc_rust`` via a git tag
* Generated ``flutter_rust_bridge`` bindings
* A Flutter plugin scaffold (iOS / Android / macOS / Linux / Windows)
* A clean Dart API surface for applications

This plugin does **not** implement cryptography itself.
All cryptographic logic remains in ``ccc_rust``.

Using FFI instead of platform channels allows Flutter to call hardware-grade, 
memory-safe Rust cryptography directly, delivering native performance, 
lower overhead, and stronger security isolation without reimplementing crypto in Dart.


===================================  ==========================  ===========================
Repository                           What ships                  Depends on
===================================  ==========================  ===========================
``ccc_rust``                         Pure Rust crypto library    wolfSSL (vendored)
``ccc_dart_plugin``                  Flutter plugin + Dart API   ``ccc_rust`` (git/semver)
``letusmsg`` (existing app)          App integration             ``ccc_dart_plugin`` package
===================================  ==========================  ===========================


Guiding Principles
------------------
1. **Strict Layer Isolation**
   - Rust crypto code lives only in ``ccc_rust``.
   - Flutter-specific code lives only here.
   - The app layer never calls Rust directly.

2. **Zero Crypto Logic in Dart**
   - No encryption, hashing, KDF, MAC, or KEM logic in Dart.
   - Dart is orchestration only.

3. **1-to-1 Algorithm Mapping**
   - Rust enum discriminants match the integer constants in
     ``cipher_constants.dart`` exactly.
   - No translation layer or remapping table in Dart.

4. **Provider-Agnostic by Design**
   - The Dart API does not hard-code wolfSSL.
   - Providers are discovered at runtime via ``CccProviderCatalog``.

5. **Deterministic FFI Contracts**
   - All bridge-exposed types are explicit and versioned.
   - No implicit conversions or dynamic typing across FFI.

6. **Security First**
   - All key material originates and remains in Rust memory.
   - Dart never stores raw private keys.
   - Sensitive buffers are zeroized in Rust.

7. **Reproducible Builds**
   - ``ccc_rust`` is referenced by git tag (e.g., ``v0.1.0``).
   - No floating branch dependencies.

8. **Test Before Integration**
   - Bridge-level roundtrip tests must pass before app integration.
   - Self-test and conformance results are exposed to Flutter.



Main
====

Responsibilities
----------------
* Register providers (e.g., WolfSslProvider)
* Expose thin wrappers over trait methods
* Convert Rust errors → structured Dart exceptions
* Expose capability catalog
* Expose self-test and benchmark results

No crypto algorithms are implemented here.


Security Model
--------------
* All cryptographic primitives execute in Rust.
* Private keys never leave Rust memory unencrypted.
* Dart receives only opaque byte arrays.
* All sensitive buffers are zeroized in Rust.
* Capability reporting is runtime-probed, not compile-time assumed.

The plugin layer introduces **no new cryptographic primitives** and
no security policy decisions.


Future Extensions
-----------------
* Multi-provider selection logic
* Dynamic provider priority scoring
* Optional secure enclave integration
* Streaming AEAD APIs
* PQ KEM exposure (ML-KEM, Classic McEliece Phase 5)