CCC Dart Plugin — Architecture & Integration Guide ==================================================== :Status: Milestone 2 (Planned) :Depends on: ``ccc_rust`` ≥ v0.1.0 :Target: Flutter (iOS, Android, macOS) :Bridge: ``flutter_rust_bridge`` v2 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 (Milestone 1) * The LetUsMsg application (Milestone 3) 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) * A clean Dart API surface for applications This plugin does **not** implement cryptography itself. All cryptographic logic remains in ``ccc_rust``. ---- Architecture Positioning ------------------------- ============= =================================== =========================== Layer Repository Responsibility ============= =================================== =========================== Milestone 1 ``ccc_rust`` Pure Rust crypto providers Milestone 2 ``ccc_dart_plugin`` Flutter bridge + Dart API Milestone 3 ``letusmsg`` App integration ============= =================================== =========================== Hard Boundary Rules ~~~~~~~~~~~~~~~~~~~ * This repo **must not modify crypto logic** from ``ccc_rust``. * This repo **must not fork or duplicate algorithm definitions**. * All algorithm enums and discriminants originate in ``ccc_rust``. * All provider capability logic remains in Rust. * The app must depend only on the published Dart package — not directly on Rust. ---- 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. ---- Repository Structure -------------------- :: ccc_dart_plugin/ ├── pubspec.yaml ├── lib/ │ ├── ccc_crypto.dart │ ├── ccc_provider_catalog.dart │ ├── ccc_self_test.dart │ └── src/ │ └── frb_generated.dart ├── rust/ │ ├── Cargo.toml │ └── src/ │ ├── lib.rs │ └── api.rs ├── flutter_rust_bridge.yaml ├── ios/ ├── android/ ├── macos/ └── test/ └── roundtrip_test.dart ---- Rust Bridge Crate ------------------ ``rust/Cargo.toml``: .. code-block:: toml [package] name = "ccc_dart_bridge" version = "0.1.0" edition = "2021" [dependencies] ccc-crypto-core = { git = "https://github.com/letusmsg/ccc_rust", tag = "v0.1.0" } ccc-crypto-wolfssl = { git = "https://github.com/letusmsg/ccc_rust", tag = "v0.1.0" } flutter_rust_bridge = "2" 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. ---- Dart API Surface ---------------- CccCrypto ~~~~~~~~~ Primary entry point. Methods: * ``Future cccInit()`` * ``Future> listProviders()`` * ``Future encryptAead(...)`` * ``Future decryptAead(...)`` * ``Future deriveKey(...)`` * ``Future hash(...)`` * ``Future runSelfTest()`` CccProviderCatalog ~~~~~~~~~~~~~~~~~~ Represents runtime provider capabilities: * Provider name * Available algorithms * Efficiency score * Reliability score CccSelfTest ~~~~~~~~~~~ Wraps ``SelfTestReport`` from Rust and exposes: * Pass/fail per algorithm * Overall status * Diagnostic messages ---- Initialization Flow ------------------- 1. Flutter app starts. 2. ``CccCrypto.cccInit()`` is called. 3. Rust bridge: - Registers WolfSslProvider - Runs capability probe - Runs self-test (optional at startup) 4. Provider catalog is cached. 5. App queries provider capabilities. ---- Error Handling Strategy ----------------------- Rust ``CryptoError`` is mapped to structured Dart exceptions: ====================== ============================ Rust Error Dart Exception ====================== ============================ UnsupportedAlgorithm CccUnsupportedAlgorithm InvalidKey CccInvalidKey InvalidNonce CccInvalidNonce AuthenticationFailed CccAuthenticationFailed InternalError CccInternalError ====================== ============================ Errors never cross the bridge as raw strings alone. ---- Testing Requirements -------------------- Before tagging ``v0.1.0`` of this plugin: * Rust bridge builds for: - iOS (aarch64-apple-ios) - Android (arm64 + x86_64) - macOS (aarch64) * Flutter integration tests: - AEAD roundtrip encrypt/decrypt - HKDF known-vector test - X25519 key agreement test * ``CccSelfTest.runAll()`` returns success * No Dart-side crypto logic present * No modification of ``ccc_rust`` source ---- Milestone 3 Handoff Contract ----------------------------- The LetUsMsg app will: * Add this plugin via ``pubspec.yaml`` * Call ``CccCrypto.cccInit()`` at startup * Replace existing crypto stubs with plugin calls * Surface provider catalog in debug UI No Rust changes are permitted during Milestone 3. ---- Versioning Strategy ------------------- * ``ccc_rust`` tagged independently (e.g., ``v0.1.0``). * ``ccc_dart_plugin`` references exact git tag. * Breaking Rust API changes require: - New Rust tag - Plugin update - New plugin version Semantic versioning applies independently to both repositories. ---- 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 ----------------- Planned enhancements after Milestone 2: * Multi-provider selection logic * Dynamic provider priority scoring * Optional secure enclave integration * Streaming AEAD APIs * PQ KEM exposure (ML-KEM, Classic McEliece Phase 5) ----