lum_ccc_fplugin/docs/ccc_fplugin_architecture_de...

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<void> cccInit()``
* ``Future<List<String>> listProviders()``
* ``Future<Uint8List> encryptAead(...)``
* ``Future<Uint8List> decryptAead(...)``
* ``Future<Uint8List> deriveKey(...)``
* ``Future<Uint8List> hash(...)``
* ``Future<CccSelfTestResult> 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)

----