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

587 lines
18 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 Not Started Phase 2
4 Platform Build Verification Not Started Phase 3
5 Unit Tests Not Started Phase 3
6 Integration Tests & Polish Not Started 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: Not Started
:Depends on: Phase 2
**Goal:** Build the clean Dart API layer that application code will
consume, wired to the FRB-generated bindings.
Tasks
~~~~~
.. list-table::
:header-rows: 1
:widths: 5 60 15
* - #
- Task
- Status
* - 3.1
- Create ``lib/ccc_crypto.dart`` — primary entry point class
``CccCrypto`` with all public methods:
``cccInit``, ``listProviders``, ``getCapabilities``,
``encryptAead``, ``decryptAead``, ``deriveKey``,
``computeMac``, ``verifyMac``, ``hash``,
``kemGenerateKeypair``, ``kemEncapsulate``, ``kemDecapsulate``,
``runSelfTest``
- ☐
* - 3.2
- Create ``lib/ccc_provider_catalog.dart`` — ``CccProviderCatalog``
(provider name, algorithms, efficiency/reliability scores)
- ☐
* - 3.3
- Create ``lib/ccc_self_test.dart`` — ``CccSelfTestResult``
(per-algorithm pass/fail, overall status, diagnostics)
- ☐
* - 3.4
- Create ``lib/ccc_exceptions.dart`` — structured exception
classes (``CccUnsupportedAlgorithm``, ``CccInvalidKey``,
``CccInvalidNonce``, ``CccAuthenticationFailed``,
``CccInternalError``)
- ☐
* - 3.5
- Create ``lib/ccc_algorithm_ids.dart`` — algorithm ID constants
matching Rust enum discriminants 1-to-1 (values from
``cipher_constants.dart``); no remapping
- ☐
* - 3.6
- Wire all Dart API methods to FRB-generated bindings
- ☐
* - 3.7
- Create barrel export file ``lib/ccc_cryptography.dart``
re-exporting the public API
- ☐
* - 3.8
- Remove old placeholder Dart code (``sum``, ``sumAsync``)
- ☐
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.
----
Phase 4 — Platform Build Verification
---------------------------------------
:Status: Not Started
:Depends on: Phase 3
**Goal:** Verify the Rust bridge crate cross-compiles and links
correctly on all five target platforms.
Tasks
~~~~~
.. list-table::
:header-rows: 1
:widths: 5 60 15
* - #
- Task
- Status
* - 4.1
- Build for **iOS** (``aarch64-apple-ios``,
``aarch64-apple-ios-sim``)
- ☐
* - 4.2
- Build for **Android** (``aarch64-linux-android``,
``x86_64-linux-android``)
- ☐
* - 4.3
- Build for **macOS** (``aarch64-apple-darwin``,
``x86_64-apple-darwin``)
- ☐
* - 4.4
- Build for **Linux** (``x86_64-unknown-linux-gnu``)
- ☐
* - 4.5
- Build for **Windows** (``x86_64-pc-windows-msvc``)
- ☐
* - 4.6
- Fix any platform-specific linker or NDK issues
- ☐
* - 4.7
- Verify ``flutter run`` launches on at least one
physical/emulated device per platform
- ☐
Exit Criteria
~~~~~~~~~~~~~
* ``flutter build`` succeeds for all five platforms.
* Native library is bundled correctly in each platform's output.
----
Phase 5 — Unit Tests
---------------------
:Status: Not Started
:Depends on: Phase 3
**Goal:** Verify correctness of the bridge and Dart API via
Dart-side unit tests.
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 vectors
- ☐
* - 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
- ☐
* - 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 overall pass
with per-algorithm results
- ☐
* - 5.12
- Error handling tests — verify each ``CccException`` subtype
is thrown for the corresponding error condition
(unsupported algorithm, invalid key, invalid nonce)
- ☐
* - 5.13
- Algorithm ID mapping test — verify Dart constants match
Rust enum discriminants (1-to-1, no drift)
- ☐
Exit Criteria
~~~~~~~~~~~~~
* All unit tests pass on host platform (macOS).
* No Dart-side crypto logic introduced by tests.
----
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
- ☐
* - 6.2
- Integration test: KEM keygen → encap → decap roundtrip
- ☐
* - 6.3
- Integration test: self-test API returns all-pass
- ☐
* - 6.4
- Run integration tests on iOS simulator
- ☐
* - 6.5
- Run integration tests on Android emulator
- ☐
* - 6.6
- Run integration tests on macOS
- ☐
* - 6.7
- Run integration tests on Linux
- ☐
* - 6.8
- Run integration tests on Windows
- ☐
* - 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.*
* ``[ ]`` FRB bridge API compiles and loads in Flutter plugin
* ``[ ]`` Generated Dart bindings are committed and reproducible
* ``[ ]`` All unit tests pass on host platform (macOS)
* ``[ ]`` ``flutter build ios`` succeeds
* ``[ ]`` ``flutter build apk`` succeeds
* ``[ ]`` ``flutter build macos`` succeeds
* ``[ ]`` ``flutter build linux`` succeeds
* ``[ ]`` ``flutter build windows`` succeeds
* ``[ ]`` Integration tests pass on iOS simulator
* ``[ ]`` Integration tests pass on Android emulator/device
* ``[ ]`` Integration tests pass on macOS
* ``[ ]`` Integration tests pass on Linux
* ``[ ]`` Integration tests pass on Windows
* ``[ ]`` No Dart-side crypto logic present
* ``[ ]`` 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