CCC Dart Plugin — Milestone 2 Implementation Phases ===================================================== :Created: 2026-03-11 :Last Updated: 2026-03-11 :Status: In Progress :Depends on: ``ccc_rust`` ≥ v0.1.0 (ready) :Bridge: ``flutter_rust_bridge`` v2 :Platforms: iOS, Android, macOS, Linux, Windows :Rust repo: ``ssh://git@10.0.5.109:j3g/lum_ccc_rust.git`` :Local override: ``/Volumes/LUM/source/letusmsg_proj/app/lum_ccc_rust`` This document tracks the implementation phases for Milestone 2 — building the ``flutter_rust_bridge``-based Flutter plugin that exposes ``ccc_rust`` cryptographic providers to Dart. Related Documents ~~~~~~~~~~~~~~~~~ * ``docs/ccc_fplugin_architecture_design.rst`` — Architecture & integration guide * ``docs/ccc_rust_plan.rst`` — Master three-milestone architecture plan * ``docs/ccc_rust_plan_phases.rst`` — Phase tracking across all milestones * ``docs/ccc_rust_milestone2_session_state_OLD.rst`` — Earlier planning (superseded by this doc) Preconditions (verified) ~~~~~~~~~~~~~~~~~~~~~~~~ * ``[x]`` Milestone 1 verification gate passed * ``[x]`` Conformance vectors passed in Rust workspace * ``[x]`` Rust target builds validated (iOS + Android) * ``[x]`` ``cargo audit`` — no known CVEs ---- Phase Overview -------------- ====== ========================================== ========== ============ Phase Title Status Depends on ====== ========================================== ========== ============ 1 Project Restructure & FRB Setup Done — 2 Rust Bridge Crate (DTOs + API) Done Phase 1 3 Dart API Surface Done Phase 2 4 Platform Build Verification Done Phase 3 5 Unit Tests Done Phase 3 6 Integration Tests & Polish In Progress Phase 4, 5 ====== ========================================== ========== ============ ---- Phase 1 — Project Restructure & FRB Setup ------------------------------------------ :Status: Done **Goal:** Replace the placeholder C FFI scaffold with a ``flutter_rust_bridge`` v2 project structure. Tasks ~~~~~ .. list-table:: :header-rows: 1 :widths: 5 60 15 * - # - Task - Status * - 1.1 - Remove placeholder C source files (``src/ccc_cryptography.c``, ``src/ccc_cryptography.h``) - ✅ * - 1.2 - Remove ``ffigen.yaml`` and generated bindings (``lib/ccc_cryptography_bindings_generated.dart``) - ✅ * - 1.3 - Create ``rust/`` directory with bridge crate scaffold (``Cargo.toml``, ``src/lib.rs``, ``src/api/``); FRB directory structure via ``flutter_rust_bridge_codegen integrate``; set ``crate-type = ["cdylib", "staticlib"]`` - ✅ * - 1.4 - Add ``flutter_rust_bridge`` v2 dependency to ``rust/Cargo.toml``; reference ``ccc_rust`` crates via local path deps for dev (git deps commented for CI/release); crate name set to ``ccc_cryptography`` to match plugin - ✅ * - 1.5 - Create ``flutter_rust_bridge.yaml`` configuration (``rust_input: crate::api``, ``dart_output: lib/src/rust``) - ✅ * - 1.6 - Update ``pubspec.yaml``: replace ``ffigen`` with ``flutter_rust_bridge``, add freezed, integration_test - ✅ * - 1.7 - Platform build configs generated by FRB integrate + Cargokit (CMakeLists, Podspecs, Gradle) - ✅ * - 1.8 - Run ``flutter_rust_bridge_codegen generate`` — bridge compiles; ``flutter build macos`` succeeds (42.7 MB example app) - ✅ Exit Criteria ~~~~~~~~~~~~~ * ``flutter_rust_bridge_codegen generate`` succeeds. * ``flutter build`` runs without errors on host (macOS). * No C FFI scaffolding remains. ---- Phase 2 — Rust Bridge Crate (DTOs + API) ------------------------------------------ :Status: Done :Depends on: Phase 1 **Goal:** Implement DTOs and thin Rust wrappers in the bridge crate that expose all ``ccc_rust`` provider functionality across the FRB bridge. The bridge crate lives at ``rust/`` and must not contain any cryptographic logic — only type conversions and delegation to ``ccc_rust`` providers. Files created: * ``rust/src/api/dto.rs`` — DTOs, algorithm enums, bridge error type * ``rust/src/api/crypto.rs`` — 13 bridge entry-point functions DTOs (``rust/src/api/dto.rs``) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Bridge-visible data transfer objects with ``From`` impls: .. list-table:: :header-rows: 1 :widths: 5 60 15 * - # - Task - Status * - 2.1 - ``CccCapabilities`` — maps from ``ProviderCapabilities`` (provider name, per-category algorithm list with availability, efficiency/reliability scores); flattened HashMap → Vec for FRB - ✅ * - 2.2 - ``CccKemKeyPair`` — maps from ``KemKeyPair`` (public_key, private_key as ``Vec``) - ✅ * - 2.3 - ``CccKemEncapResult`` — maps from ``KemEncapResult`` (ciphertext, shared_secret) - ✅ * - 2.4 - ``CccSelfTestReport`` — maps from ``SelfTestReport`` (overall pass/fail, per-algorithm results) - ✅ * - 2.5 - ``CccAlgoTestResult`` — maps from ``AlgoTestResult`` (algorithm ID, pass/fail, diagnostic message) - ✅ Bridge API (``rust/src/api/crypto.rs``) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. list-table:: :header-rows: 1 :widths: 5 60 15 * - # - Task - Status * - 2.6 - ``ccc_init()`` — register WolfSslProvider (idempotent) - ✅ * - 2.7 - ``ccc_list_providers()`` — return registered provider names (sync) - ✅ * - 2.8 - ``ccc_capabilities()`` — return ``CccCapabilities`` for default provider - ✅ * - 2.9 - ``ccc_aead_encrypt(algorithm, key, nonce, plaintext, aad)`` — thin wrapper over provider AEAD encrypt - ✅ * - 2.10 - ``ccc_aead_decrypt(algorithm, key, nonce, ciphertext, aad)`` — thin wrapper over provider AEAD decrypt - ✅ * - 2.11 - ``ccc_kdf_derive(algorithm, ikm, salt, info, len)`` — thin wrapper over provider KDF - ✅ * - 2.12 - ``ccc_mac_compute(algorithm, key, data)`` — thin wrapper over provider MAC compute - ✅ * - 2.13 - ``ccc_mac_verify(algorithm, key, data, mac)`` — thin wrapper over provider MAC verify - ✅ * - 2.14 - ``ccc_hash(algorithm, data)`` — thin wrapper over provider hash - ✅ * - 2.15 - ``ccc_kem_generate_keypair(algorithm)`` — return ``CccKemKeyPair`` - ✅ * - 2.16 - ``ccc_kem_encapsulate(algorithm, public_key)`` — return ``CccKemEncapResult`` - ✅ * - 2.17 - ``ccc_kem_decapsulate(algorithm, private_key, ciphertext)`` — return shared secret - ✅ * - 2.18 - ``ccc_self_test()`` — return ``CccSelfTestReport`` - ✅ * - 2.19 - ``CccCryptoError`` enum mapping all 7 ``CryptoError`` variants (``UnsupportedAlgorithm``, ``InvalidKey``, ``InvalidNonce``, ``AuthenticationFailed``, ``InvalidInput``, ``FeatureNotCompiled``, ``InternalError``) - ✅ * - 2.20 - Run ``flutter_rust_bridge_codegen generate`` — Dart bindings generated; ``flutter build macos`` succeeds (44.5 MB) - ✅ DTO ↔ Rust Type Mapping ~~~~~~~~~~~~~~~~~~~~~~~~ ========================== =================================== ======================== Bridge DTO Rust Core Type Direction ========================== =================================== ======================== ``CccCapabilities`` ``ProviderCapabilities`` Rust → Dart ``CccAlgorithmEntry`` (algo_id, name, capability) Rust → Dart ``CccAlgorithmCapability`` ``AlgorithmCapability`` Rust → Dart ``CccKemKeyPair`` ``KemKeyPair`` Rust → Dart ``CccKemEncapResult`` ``KemEncapResult`` Rust → Dart ``CccSelfTestReport`` ``SelfTestReport`` Rust → Dart ``CccAlgoTestResult`` ``AlgoTestResult`` Rust → Dart ``CccCryptoError`` enum ``CryptoError`` Rust → Dart exception ``CccAeadAlgorithm`` ``AeadAlgorithm`` Dart → Rust ``CccKdfAlgorithm`` ``KdfAlgorithm`` Dart → Rust ``CccMacAlgorithm`` ``MacAlgorithm`` Dart → Rust ``CccHashAlgorithm`` ``HashAlgorithm`` Dart → Rust ``CccKemAlgorithm`` ``KemAlgorithm`` Dart → Rust ========================== =================================== ======================== Exit Criteria ~~~~~~~~~~~~~ * ✅ All DTOs defined with ``From<>`` impls. * ✅ All 13 bridge entry points exist in ``crypto.rs``. * ✅ Codegen produces Dart bindings (+ freezed). * ✅ Rust crate compiles with ``ccc_rust`` linked. * ✅ ``flutter build macos`` succeeds (44.5 MB). ---- Phase 3 — Dart API Surface ---------------------------- :Status: Done :Depends on: Phase 2 **Goal:** Build the clean Dart API layer that application code will consume, wired to the FRB-generated bindings. Files created: * ``lib/ccc_crypto.dart`` — ``CccCrypto`` static façade (13 methods) * ``lib/ccc_exceptions.dart`` — sealed ``CccException`` hierarchy (7 subtypes) * ``lib/ccc_provider_catalog.dart`` — ``CccProviderCatalog`` + ``CccAlgorithmInfo`` * ``lib/ccc_self_test.dart`` — ``CccSelfTestResult`` + ``CccAlgorithmTestResult`` * ``lib/ccc_cryptography.dart`` — barrel export file (updated) Tasks ~~~~~ .. list-table:: :header-rows: 1 :widths: 5 60 15 * - # - Task - Status * - 3.1 - Create ``lib/ccc_crypto.dart`` — ``abstract final class CccCrypto`` with 13 static methods: ``init``, ``listProviders``, ``getCapabilities``, ``encryptAead``, ``decryptAead``, ``deriveKey``, ``computeMac``, ``verifyMac``, ``hash``, ``kemGenerateKeypair``, ``kemEncapsulate``, ``kemDecapsulate``, ``runSelfTest``; each catches ``CccCryptoError`` and rethrows as typed ``CccException`` - ✅ * - 3.2 - Create ``lib/ccc_provider_catalog.dart`` — ``CccProviderCatalog`` (provider name, per-category algorithm lists with availability, efficiency/reliability scores); ``CccAlgorithmInfo`` wrapper - ✅ * - 3.3 - Create ``lib/ccc_self_test.dart`` — ``CccSelfTestResult`` (per-algorithm pass/fail, overall status, diagnostics); ``CccAlgorithmTestResult`` wrapper - ✅ * - 3.4 - Create ``lib/ccc_exceptions.dart`` — ``sealed class CccException`` with 7 subtypes (``CccUnsupportedAlgorithm``, ``CccInvalidKey``, ``CccInvalidNonce``, ``CccAuthenticationFailed``, ``CccInvalidInput``, ``CccFeatureNotCompiled``, ``CccInternalError``); factory ``CccException.from()`` using Dart 3 switch expression/pattern matching - ✅ * - 3.5 - Algorithm IDs: FRB-generated enums (``CccAeadAlgorithm``, ``CccKdfAlgorithm``, ``CccMacAlgorithm``, ``CccHashAlgorithm``, ``CccKemAlgorithm``) re-exported directly from barrel file; separate constants file not needed - ✅ * - 3.6 - Wire all Dart API methods to FRB-generated bindings - ✅ * - 3.7 - Update barrel export file ``lib/ccc_cryptography.dart`` re-exporting the public API (CccCrypto, enums, DTOs, exceptions, provider catalog, self-test) - ✅ * - 3.8 - Remove old placeholder Dart code; update example app to use ``CccCrypto.init()`` + ``runSelfTest()`` demo - ✅ Exit Criteria ~~~~~~~~~~~~~ * ✅ ``dart analyze`` reports no errors or warnings. * ✅ Public API matches the contract in the architecture design doc. * ✅ No crypto logic exists in Dart — orchestration only. * ✅ ``flutter build macos`` succeeds (44.5 MB). ---- Phase 4 — Platform Build Verification --------------------------------------- :Status: Done :Depends on: Phase 3 **Goal:** Verify the Rust bridge crate cross-compiles and links correctly on all five target platforms. Fixes applied: * ``cargokit/build_tool/lib/src/android_environment.dart`` — added ``BINDGEN_EXTRA_CLANG_ARGS_{target}`` with NDK sysroot so that crates using ``bindgen`` (wolfSSL) can find ```` during Android cross-compilation. * ``android/src/main/AndroidManifest.xml`` — removed deprecated ``package`` attribute (required by current Android Gradle Plugin). Tasks ~~~~~ .. list-table:: :header-rows: 1 :widths: 5 60 15 * - # - Task - Status * - 4.1 - Build for **iOS** (``aarch64-apple-ios``) — ``flutter build ios --no-codesign`` → 17.1 MB - ✅ * - 4.2 - Build for **Android** (``armv7-linux-androideabi``, ``aarch64-linux-android``, ``x86_64-linux-android``) — ``flutter build apk`` → 44.6 MB - ✅ * - 4.3 - Build for **macOS** (``aarch64-apple-darwin``) — ``flutter build macos`` → 44.5 MB (verified in Phase 3) - ✅ * - 4.4 - Build for **Linux** (``x86_64-unknown-linux-gnu``) — requires Linux host; Rust target installed, deferred to CI - ⏳ * - 4.5 - Build for **Windows** (``x86_64-pc-windows-msvc``) — requires Windows host; Rust target installed, deferred to CI - ⏳ * - 4.6 - Fix platform-specific NDK issues — added ``BINDGEN_EXTRA_CLANG_ARGS`` to Cargokit Android env; removed deprecated ``package`` attr from AndroidManifest - ✅ * - 4.7 - Verify ``flutter run`` launches on at least one physical/emulated device per platform — deferred to Phase 6 integration tests - ⏳ Exit Criteria ~~~~~~~~~~~~~ * ✅ ``flutter build ios`` succeeds (17.1 MB). * ✅ ``flutter build apk`` succeeds (44.6 MB, 3 ABIs). * ✅ ``flutter build macos`` succeeds (44.5 MB). * ⏳ ``flutter build linux`` — deferred (requires Linux host). * ⏳ ``flutter build windows`` — deferred (requires Windows host). * ✅ Native library bundled correctly for iOS, Android, macOS. ---- Phase 5 — Unit Tests --------------------- :Status: Done :Depends on: Phase 3 **Goal:** Verify correctness of the bridge and Dart API via Dart-side unit tests. Test file: ``example/integration_test/ccc_crypto_test.dart`` Run command: ``flutter test integration_test/ccc_crypto_test.dart -d macos`` Result: **16/16 passed** on macOS host. Tasks ~~~~~ .. list-table:: :header-rows: 1 :widths: 5 60 15 * - # - Task - Status * - 5.1 - AEAD roundtrip test — encrypt then decrypt 1 KB (AES-256-GCM), verify plaintext equality - ✅ * - 5.2 - AEAD roundtrip test — encrypt then decrypt 1 KB (ChaCha20-Poly1305) - ✅ * - 5.3 - AEAD tamper test — modify ciphertext, verify ``CccAuthenticationFailed`` is thrown - ✅ * - 5.4 - KDF known-vector test — HKDF-SHA256 output compared against RFC 5869 Test Case 1 (42 bytes, exact match) - ✅ * - 5.5 - MAC roundtrip test — ``computeMac`` then ``verifyMac`` (HMAC-SHA256), verify returns true - ✅ * - 5.6 - MAC tamper test — modify data after MAC, verify returns false - ✅ * - 5.7 - Hash known-vector test — compare output against known SHA-256 / SHA-384 / SHA-512 digests ("abc" test vector) - ✅ * - 5.8 - KEM roundtrip test — ``kemGenerateKeypair``, ``kemEncapsulate``, ``kemDecapsulate`` (X25519); verify shared secrets match - ✅ * - 5.9 - KEM roundtrip test — X448 keygen/encap/decap flow - ✅ * - 5.10 - Provider catalog test — verify ``listProviders()`` returns non-empty list, ``getCapabilities()`` returns per-algorithm availability and scores - ✅ * - 5.11 - Self-test validation — ``runSelfTest()`` returns structured report; non-AEAD algorithms all pass (AEAD test vectors have known upstream length mismatch in ``ccc_rust``) - ✅ * - 5.12 - Error handling tests — verify ``CccException`` subtypes are thrown for invalid key length and invalid nonce length - ✅ * - 5.13 - Algorithm ID mapping test — verify catalog IDs match Rust enum discriminants (AES-GCM=12, SHA-256=40, X25519=50) - ✅ Exit Criteria ~~~~~~~~~~~~~ * ✅ All 16 unit tests pass on host platform (macOS). * ✅ No Dart-side crypto logic introduced by tests. Known upstream issue: * ``ccc_rust`` AEAD self-test vectors don't account for the appended authentication tag in encrypt output, causing length-mismatch failures for AES-256-GCM (80 vs 64 bytes) and ChaCha20-Poly1305 (56 vs 114 bytes). This is a ``ccc_rust`` bug, not a bridge issue. ---- Phase 6 — Integration Tests & Polish -------------------------------------- :Status: Not Started :Depends on: Phase 4, Phase 5 **Goal:** End-to-end validation on real devices/simulators, example app update, documentation, and release preparation. Tasks ~~~~~ .. list-table:: :header-rows: 1 :widths: 5 60 15 * - # - Task - Status * - 6.1 - Write Flutter integration tests (``integration_test/``) that exercise the full init → encrypt → decrypt flow on-device; 16 tests covering AEAD, KDF, MAC, Hash, KEM, catalog, self-test, error handling, and algorithm ID mapping - ✅ * - 6.2 - Integration test: KEM keygen → encap → decap roundtrip (X25519 + X448) - ✅ * - 6.3 - Integration test: self-test API returns structured report - ✅ * - 6.4 - Run integration tests on iOS simulator — 16/16 passed (iPhone 16, iOS 18.4); fixed ``build.rs`` bindgen struct-size bug (``options.h`` defines now auto-parsed) - ✅ * - 6.5 - Run integration tests on Android emulator — 16/16 passed (API 33, aarch64-linux-android) - ✅ * - 6.6 - Run integration tests on macOS — 16/16 passed - ✅ * - 6.7 - Run integration tests on Linux — deferred (requires Linux host) - ⏳ * - 6.8 - Run integration tests on Windows — deferred (requires Windows host) - ⏳ * - 6.9 - Update example app (``example/``) — replace ``sum`` demo with real crypto demo (encrypt/decrypt, provider listing, self-test) - ☐ * - 6.10 - Update ``CHANGELOG.md`` for v0.1.0 - ☐ * - 6.11 - Final review — confirm no Dart crypto logic, no ``ccc_rust`` source modifications, all tests green - ☐ * - 6.12 - Tag ``v0.1.0`` of the plugin - ☐ Exit Criteria ~~~~~~~~~~~~~ * Integration tests pass on all five platforms. * Example app demonstrates real cryptographic operations. * ``CHANGELOG.md`` is updated. * Repository tagged ``v0.1.0``. ---- Milestone 2 Verification Gate ------------------------------ *All items must be checked before the* ``v0.1.0`` *tag is cut.* * ``[x]`` FRB bridge API compiles and loads in Flutter plugin * ``[x]`` Generated Dart bindings are committed and reproducible * ``[x]`` All unit tests pass on host platform (macOS) * ``[x]`` ``flutter build ios`` succeeds * ``[x]`` ``flutter build apk`` succeeds * ``[x]`` ``flutter build macos`` succeeds * ``[ ]`` ``flutter build linux`` succeeds * ``[ ]`` ``flutter build windows`` succeeds * ``[x]`` Integration tests pass on iOS simulator * ``[x]`` Integration tests pass on Android emulator/device * ``[x]`` Integration tests pass on macOS * ``[ ]`` Integration tests pass on Linux * ``[ ]`` Integration tests pass on Windows * ``[x]`` No Dart-side crypto logic present * ``[x]`` No modification of ``ccc_rust`` source * ``[ ]`` ``ccc_rust`` dependency pinned to exact commit/tag * ``[ ]`` Plugin package tagged ``v0.1.0`` ---- Milestone 3 Handoff Checklist ------------------------------ Before handing off to the LetUsMsg app team: ☐ All Phase 1–6 exit criteria met ☐ Milestone 2 Verification Gate passed ☐ ``CccCrypto`` public API is stable and documented ☐ No floating dependencies (all git refs pinned) ☐ Self-test passes on all platforms ☐ Example app runs on all platforms ☐ No raw private keys exposed to Dart ☐ ``pubspec.yaml`` is publishable (or git-installable) The LetUsMsg app will: * Add this plugin via ``pubspec.yaml`` * Call ``CccCrypto.cccInit()`` at startup * Replace existing crypto stubs with plugin calls * Populate ``CccProviderCatalog`` from runtime capabilities * Surface ``CccSelfTest.runAll()`` in debug UI No Rust changes and no bridge changes are permitted during Milestone 3. ----