j3g
/
lum_ccc_fplugin
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
lum_ccc_fplugin/docs/ccc_rust_milestone2_phases.rst

644 lines
20 KiB
ReStructuredText
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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<core type>`` 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<u8>``)
- ✅
* - 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 ``<pthread.h>`` 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.
----
Reference in New Issue View Git Blame Copy Permalink