diff --git a/.vscode/settings.json b/.vscode/settings.json index ad8fd9c..b01ecdd 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -3,5 +3,6 @@ "cargo check": true, "flutter_rust_bridge_codegen": true, "rustup": true - } + }, + "java.configuration.updateBuildConfiguration": "interactive" } \ No newline at end of file diff --git a/docs/ccc_fplugin_build_windows.rst b/docs/ccc_fplugin_build_windows.rst new file mode 100644 index 0000000..266a3c0 --- /dev/null +++ b/docs/ccc_fplugin_build_windows.rst @@ -0,0 +1,477 @@ +CCC Flutter Plugin — Windows Build & Test Guide +=============================================== + +:Created: 2026-03-16 +:Status: Pending (Phase 4.5 and Phase 6.8) +:Relates to: ``docs/ccc_fplugin_phases.rst`` §§ 4.5, 6.8 +:Platform: Windows 10 / Windows 11 — x86_64 + +Overview +-------- + +The ``ccc_cryptography`` Flutter plugin is feature-complete on macOS, iOS, +and Android. All 16 integration tests pass on those three platforms. + +Two Windows-specific tasks remain open in the Milestone 2 verification gate: + +* **Phase 4.5** — ``flutter build windows`` succeeds +* **Phase 6.8** — all 16 integration tests pass on a Windows host + +This guide provides the step-by-step procedure for a developer on a Windows +machine to complete those two tasks and tick off the remaining gate items. + +Related Documents +~~~~~~~~~~~~~~~~~ + +* ``docs/ccc_fplugin_phases.rst`` — master phase tracker (tasks 4.5, 6.8, + and the Milestone 2 Verification Gate) +* ``docs/ccc_fplugin_architecture_design.rst`` — plugin architecture +* ``docs/README_DEV.rst`` — FRB v2 + Cargokit background + +---- + +Platform Status Summary +----------------------- + +============================== ========= ==================== +Platform Build Integration Tests +============================== ========= ==================== +iOS (aarch64-apple-ios) ✅ 17.1 MB ✅ 16/16 passed +Android (arm64, armv7, x86_64) ✅ 44.6 MB ✅ 16/16 passed +macOS (aarch64-apple-darwin) ✅ 44.5 MB ✅ 16/16 passed +Linux (x86_64-linux-gnu) ⏳ deferred ⏳ deferred +**Windows (x86_64-msvc)** **⏳ TBD** **⏳ TBD** +============================== ========= ==================== + +---- + +Prerequisites +------------- + +Install the following on the Windows host before proceeding. + +1. Visual Studio 2022 +~~~~~~~~~~~~~~~~~~~~~ + +Install **Visual Studio 2022** (Community edition or higher) with the +following workloads and components: + +* **Desktop development with C++** + + * MSVC v143 — VS 2022 C++ x64/x86 build tools (selected by default) + * Windows 11 SDK (10.0.22000 or later) — or Windows 10 SDK ≥ 10.0.20348 + * CMake tools for Windows (or install CMake ≥ 3.14 separately) + +.. note:: + ``windows/CMakeLists.txt`` requires ``cmake_minimum_required(VERSION 3.14)``. + The CMake bundled with VS 2022 satisfies this requirement. + +2. Flutter SDK +~~~~~~~~~~~~~~ + +Install Flutter (stable channel) and verify:: + + flutter doctor + +All items relevant to Windows desktop must be green. Enable Windows desktop +if not already done:: + + flutter config --enable-windows-desktop + +3. Rust Toolchain (MSVC ABI — not GNU) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Install ``rustup`` from https://rustup.rs. During installation select the +**MSVC** ABI, which is the default when Visual Studio is detected. + +.. warning:: + The GNU ABI toolchain (``*-pc-windows-gnu``) does **not** link against + the MSVC C runtime and will fail when building wolfSSL. + Only ``x86_64-pc-windows-msvc`` is supported. + +Verify the active toolchain is MSVC:: + + rustup show + +Add the Windows target if not already present:: + + rustup target add x86_64-pc-windows-msvc + +4. LLVM / Clang +~~~~~~~~~~~~~~~ + +wolfSSL's ``build.rs`` uses ``bindgen`` to generate Rust FFI bindings from +C headers. ``bindgen`` requires a Clang/libclang installation at build time. + +Install LLVM (≥ 14) using one of the following methods: + +* **winget** (preferred):: + + winget install LLVM.LLVM + +* **Chocolatey**:: + + choco install llvm + +* **Installer** from https://llvm.org/releases — check + "Add LLVM to the system PATH" during install. + +After installation, set ``LIBCLANG_PATH`` (see § Environment Variables). + +5. Git with SSH Access to the Internal Repository +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The bridge crate depends on ``ccc_rust`` hosted at the internal SSH server. +Ensure Git is installed and the SSH key for ``git@10.0.5.109`` is present:: + + ssh -T git@10.0.5.109 + +Confirm authentication succeeds before proceeding. + +---- + +Rust Target Setup +----------------- + +Add the Windows MSVC target to the active toolchain:: + + rustup target add x86_64-pc-windows-msvc + +Verify it is listed:: + + rustup target list --installed + +Expected output includes ``x86_64-pc-windows-msvc``. + +---- + +Dependency Configuration +------------------------ + +The bridge crate at ``rust/Cargo.toml`` currently uses **local macOS path +dependencies** that resolve to ``/Volumes/LUM/...``. These paths do not +exist on a Windows machine and must be replaced before building. + +Two options are available: + +Option A — Local Clone (Development) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Clone ``lum_ccc_rust`` to a Windows path, then set path deps accordingly:: + + git clone ssh://git@10.0.5.109/j3g/lum_ccc_rust.git C:\src\lum_ccc_rust + +Edit ``rust/Cargo.toml``:: + + ccc-crypto-core = { path = "C:/src/lum_ccc_rust/crates/ccc-crypto-core" } + ccc-crypto-wolfssl = { path = "C:/src/lum_ccc_rust/crates/ccc-crypto-wolfssl" } + +Option B — Git/SSH Dependencies (Recommended) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Switch to the git/SSH dependencies that are already present (commented out) +in ``rust/Cargo.toml``. + +**Remove** the local macOS path lines:: + + ccc-crypto-core = { path = "/Volumes/LUM/source/letusmsg_proj/app/lum_ccc_rust/crates/ccc-crypto-core" } + ccc-crypto-wolfssl = { path = "/Volumes/LUM/source/letusmsg_proj/app/lum_ccc_rust/crates/ccc-crypto-wolfssl" } + +**Uncomment** the git lines:: + + ccc-crypto-core = { git = "ssh://git@10.0.5.109/j3g/lum_ccc_rust.git", rev = "b1873b2" } + ccc-crypto-wolfssl = { git = "ssh://git@10.0.5.109/j3g/lum_ccc_rust.git", rev = "b1873b2" } + +Pre-fetch the dependency to confirm SSH access works:: + + cd rust + cargo fetch + +.. note:: + Before cutting the ``v0.1.0`` tag, replace the commit hash with the + exact release tag — see the Milestone 2 Verification Gate in + ``docs/ccc_fplugin_phases.rst``. + +---- + +Environment Variables +--------------------- + +Set the following before running the build. Use PowerShell or set them +permanently in System Properties → Advanced → Environment Variables. + +LIBCLANG_PATH +~~~~~~~~~~~~~ + +Required by ``bindgen`` (used in wolfSSL's ``build.rs``) to locate +``libclang.dll``. + +PowerShell:: + + $env:LIBCLANG_PATH = "C:\Program Files\LLVM\bin" + +CMD:: + + set LIBCLANG_PATH=C:\Program Files\LLVM\bin + +Verify ``libclang.dll`` is present:: + + dir "$env:LIBCLANG_PATH\libclang.dll" + +Optionally, make it permanent via ``.cargo/config.toml`` in the project root:: + + [env] + LIBCLANG_PATH = "C:\\Program Files\\LLVM\\bin" + +BINDGEN_EXTRA_CLANG_ARGS (if needed) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +On Android, wolfSSL's ``build.rs`` required extra Clang arguments to find +system headers; that fix was applied in Phase 4.6 via +``BINDGEN_EXTRA_CLANG_ARGS_`` in Cargokit's Android environment. +A similar issue may occur on Windows if bindgen cannot locate MSVC headers. + +If the build fails with errors about missing ``stddef.h`` or similar standard +headers, add:: + + $env:BINDGEN_EXTRA_CLANG_ARGS = "--target=x86_64-pc-windows-msvc -fms-extensions -fms-compatibility" + +See the Troubleshooting section for full details. + +---- + +Phase 4.5 — Build Verification +------------------------------- + +Run from the ``example/`` directory:: + + cd example + flutter build windows --release + +Expected result: + +* Build completes with no errors. +* The compiled ``.exe`` and the Cargokit-built ``.dll`` are placed in:: + + example\build\windows\x64\runner\Release\ + +* Record the output directory size for the verification gate entry. + +.. note:: + Cargokit invokes ``cargo build --target x86_64-pc-windows-msvc`` + automatically during ``flutter build windows``. The first build compiles + wolfSSL from source and may take several minutes. + +On success, update ``docs/ccc_fplugin_phases.rst`` task 4.5 to ✅ and record +the build output size. + +---- + +Phase 6.8 — Integration Tests on Windows +----------------------------------------- + +Run from the ``example/`` directory:: + + cd example + flutter test integration_test/ccc_crypto_test.dart -d windows + +Expected result: **16/16 tests passed**. + +The 16 tests and their coverage:: + + [5.1] AEAD roundtrip — AES-256-GCM encrypt/decrypt (1 KB) + [5.2] AEAD roundtrip — ChaCha20-Poly1305 encrypt/decrypt (1 KB) + [5.3] AEAD tamper — modified ciphertext → CccAuthenticationFailed + [5.4] KDF known-vector — HKDF-SHA256 vs RFC 5869 Test Case 1 (42 bytes) + [5.5] MAC roundtrip — HMAC-SHA256 compute + verify returns true + [5.6] MAC tamper — modified data → verify returns false + [5.7] Hash known-vector — SHA-256/384/512 ("abc" test vector) + [5.8] KEM roundtrip — X25519 keygen/encap/decap; shared secrets match + [5.9] KEM roundtrip — X448 keygen/encap/decap; shared secrets match + [5.10] Provider catalog — listProviders() non-empty; getCapabilities() returns scores + [5.11] Self-test — runSelfTest() returns structured report + [5.12] Error handling — invalid key/nonce lengths → correct CccException subtypes + [5.13] Algorithm ID mapping — catalog IDs match Rust enum discriminants (AES-GCM=12, ...) + +.. note:: + Test 5.11 (self-test) is expected to report AEAD length-mismatch failures + for AES-256-GCM and ChaCha20-Poly1305. This is a known upstream bug in + ``ccc_rust`` (the self-test vectors do not account for the appended auth + tag in encrypt output). It is not Windows-specific and the test still + passes overall. See Phase 5 known issues in ``docs/ccc_fplugin_phases.rst``. + +On success, update ``docs/ccc_fplugin_phases.rst`` task 6.8 to ✅ and mark +the corresponding Milestone 2 Verification Gate item. + +---- + +Windows Verification Checklist +------------------------------- + +Complete this checklist on the Windows host. Items map directly to the +open entries in the Milestone 2 Verification Gate in +``docs/ccc_fplugin_phases.rst``. + +.. list-table:: + :header-rows: 1 + :widths: 5 80 15 + + * - # + - Item + - Status + * - W-1 + - ``rustup target add x86_64-pc-windows-msvc`` installed and listed + - ☐ + * - W-2 + - ``rust/Cargo.toml`` updated — local macOS paths replaced with + git/SSH deps (or Windows local paths) + - ☐ + * - W-3 + - ``LIBCLANG_PATH`` set and ``libclang.dll`` reachable at that path + - ☐ + * - W-4 + - ``SSH -T git@10.0.5.109`` succeeds (SSH key loaded) + - ☐ + * - W-5 + - ``flutter build windows --release`` succeeds; output size recorded + - ☐ + * - W-6 + - Native ``.dll`` present and bundled in the release output directory + - ☐ + * - W-7 + - ``flutter test integration_test/ccc_crypto_test.dart -d windows`` + — 16/16 passed + - ☐ + * - W-8 + - Tasks 4.5 and 6.8 marked ✅ in ``docs/ccc_fplugin_phases.rst`` + - ☐ + * - W-9 + - Milestone 2 Verification Gate Windows items checked + - ☐ + +---- + +Troubleshooting +--------------- + +bindgen / libclang not found +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Symptom**:: + + error: failed to run custom build command for `ccc-crypto-wolfssl` + thread 'main' panicked at '... Unable to find libclang ...' + +**Fix:** Set ``LIBCLANG_PATH`` to the LLVM ``bin/`` directory containing +``libclang.dll``. Typical path after winget install:: + + C:\Program Files\LLVM\bin + +MSVC headers not found during bindgen +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Symptom:** bindgen reports it cannot find ``stddef.h``, ``stdint.h``, or +similar MSVC standard headers during the wolfSSL ``build.rs`` run. + +**Fix:** Ensure the MSVC C++ workload is installed in VS 2022, then add:: + + $env:BINDGEN_EXTRA_CLANG_ARGS = "--target=x86_64-pc-windows-msvc -fms-extensions -fms-compatibility" + +This mirrors the ``BINDGEN_EXTRA_CLANG_ARGS`` fix applied for Android +in Phase 4.6. If the issue persists, check that the VS 2022 "Windows +SDK" component is installed (bindgen needs its ``include/`` headers). + +GNU toolchain conflict +~~~~~~~~~~~~~~~~~~~~~~ + +**Symptom:** Linker errors referencing ``libgcc``, ``mingw``, or +``crt2.obj`` symbols. + +**Fix:** Confirm the active Rust toolchain is MSVC:: + + rustup show + +If the default is ``stable-x86_64-pc-windows-gnu``, override it for +this project:: + + rustup override set stable-x86_64-pc-windows-msvc + +CMake not found +~~~~~~~~~~~~~~~ + +**Symptom:** Cargokit or ``flutter build windows`` fails reporting +"CMake not found" or similar. + +**Fix:** Ensure CMake is in ``PATH``. VS 2022 installs CMake to:: + + C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\IDE\CommonExtensions\Microsoft\CMake\CMake\bin + +Add it to ``PATH``, or install the standalone CMake distribution and +check "Add CMake to PATH" during setup. Verify:: + + cmake --version + +Windows long path errors +~~~~~~~~~~~~~~~~~~~~~~~~ + +wolfSSL's source tree and Cargo's registry can produce paths exceeding +Windows' 260-character default limit. + +**Fix:** Enable long path support (requires an elevated PowerShell):: + + New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" ` + -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force + +And configure Git:: + + git config --global core.longpaths true + +cargo fetch fails — SSH key not found +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Symptom**:: + + error: failed to authenticate when downloading repository + Caused by: ... no auth methods succeeded + +**Fix:** Ensure the SSH agent has the correct key loaded:: + + ssh-add $env:USERPROFILE\.ssh\id_ed25519 # adjust key filename + +Or configure ``~/.ssh/config``:: + + Host 10.0.5.109 + User git + IdentityFile ~/.ssh/id_ed25519 + +flutter build windows fails — missing flutter_windows.dll +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Symptom:** The built executable fails to run (not a build error). + +**Fix:** Always use ``flutter build windows --release`` for testing; +never copy just the ``.exe``. The ``Release\`` folder must be kept +intact — it contains ``flutter_windows.dll`` and ``data/``. + +---- + +After Completion +---------------- + +Once both Phase 4.5 and Phase 6.8 are verified: + +1. Update ``docs/ccc_fplugin_phases.rst``: + + * Mark tasks 4.5 and 6.8 ✅ + * Check the corresponding Milestone 2 Verification Gate entries + +2. If the ``ccc_rust`` dependency commit hash is still floating, pin it + to the final ``v0.1.0`` tag of that repository. + +3. Proceed with the remaining Phase 6 tasks (6.9 example app update, + 6.10 CHANGELOG, 6.11 final review, 6.12 ``v0.1.0`` tag). + +Linux (Phase 4.4 / Phase 6.7) follows the same general pattern as Windows +but substitutes ``x86_64-unknown-linux-gnu`` as the Rust target and uses +a Clang package from the system package manager (e.g., ``apt install clang``). +No ``LIBCLANG_PATH`` override is typically needed on Linux. diff --git a/docs/ccc_rust_milestone2_phases.rst b/docs/ccc_fplugin_phases.rst similarity index 99% rename from docs/ccc_rust_milestone2_phases.rst rename to docs/ccc_fplugin_phases.rst index daff6ad..feb5177 100644 --- a/docs/ccc_rust_milestone2_phases.rst +++ b/docs/ccc_fplugin_phases.rst @@ -516,7 +516,7 @@ Known upstream issue: Phase 6 — Integration Tests & Polish -------------------------------------- -:Status: Not Started +:Status: In Progress :Depends on: Phase 4, Phase 5 **Goal:** End-to-end validation on real devices/simulators, example diff --git a/docs/ccc_rust_milestone2_session_state_OLD.rst b/docs/ccc_rust_milestone2_session_state_OLD.rst deleted file mode 100644 index e3121a6..0000000 --- a/docs/ccc_rust_milestone2_session_state_OLD.rst +++ /dev/null @@ -1,127 +0,0 @@ -===================================================== -CCC Rust Milestone 2 — Session State (Planning) -===================================================== - -:Status: Not started -:Date: 2026-02-26 -:Repository target: ``ccc_cryptography`` (plugin repo) -:Depends on: ``ccc_rust`` Milestone 1 complete - -Related Documents -================= - -* Milestone 1 completion record: - ``docs/ccc_rust_milestone1.rst`` - -Overview -======== - -This document tracks Milestone 2 execution state for Flutter plugin + bridge work. -Milestone 2 begins with Milestone 1 already verified and complete. - -Current Gate Preconditions -========================== - -* ``[x]`` Milestone 1 verification gate passed. -* ``[x]`` Conformance vectors passed in Rust workspace. -* ``[x]`` Rust target builds validated (iOS + Android). - -Milestone 2 Work Checklist -========================== - -Phase 1 — Repository + Scaffold -------------------------------- - -* ``[ ]`` Create/confirm ``ccc_cryptography`` repository and branch strategy. -* ``[ ]`` Create Flutter plugin scaffold (``pubspec.yaml``, ``ios/``, ``android/``, ``macos/``). -* ``[ ]`` Add Rust bridge crate with ``crate-type = ["cdylib", "staticlib"]``. -* ``[ ]`` Wire dependency on ``ccc_rust`` pinned tag/revision. - -Phase 2 — Bridge API Surface ----------------------------- - -* ``[ ]`` Define DTOs: - - * ``CapabilitiesDto`` - * ``KemKeyPairDto`` - * ``KemEncapDto`` - * ``SelfTestDto`` - * ``AlgoTestResultDto`` - -* ``[ ]`` Implement bridge entry points: - - * ``ccc_init`` - * ``ccc_list_providers`` - * ``ccc_capabilities`` / ``ccc_available_algorithms`` - * ``ccc_aead_encrypt`` / ``ccc_aead_decrypt`` - * ``ccc_kdf_derive`` - * ``ccc_mac_compute`` / ``ccc_mac_verify`` - * ``ccc_hash`` - * ``ccc_kem_generate_keypair`` - * ``ccc_kem_encapsulate`` / ``ccc_kem_decapsulate`` - * ``ccc_self_test`` - -Phase 3 — FRB Codegen + Build Integration ------------------------------------------ - -* ``[ ]`` Add ``flutter_rust_bridge`` configuration + codegen scripts. -* ``[ ]`` Run FRB codegen and commit generated artifacts. -* ``[ ]`` Verify plugin compiles for iOS. -* ``[ ]`` Verify plugin compiles for Android. -* ``[ ]`` Verify plugin compiles for macOS. - -Phase 4 — Dart API Layer ------------------------- - -* ``[ ]`` Implement ``CccCrypto`` service API wrapper. -* ``[ ]`` Implement ``CccSelfTest`` wrapper. -* ``[ ]`` Implement runtime ``CccProviderCatalog`` population. -* ``[ ]`` Ensure algorithm ID mapping remains 1:1 with Rust discriminants. - -Phase 5 — Integration + Validation ----------------------------------- - -* ``[ ]`` Add integration tests for AEAD roundtrip (at least AES-GCM and ChaCha20). -* ``[ ]`` Add integration tests for KEM keygen/encap/decap flow. -* ``[ ]`` Add integration tests for self-test API. -* ``[ ]`` Run on iOS simulator. -* ``[ ]`` Run on Android emulator/device. - -Milestone 2 TODO Queue -====================== - -Immediate TODOs (next session) ------------------------------- - -* ``[ ]`` Decide exact Milestone 2 repository location/URL and baseline branch. -* ``[ ]`` Pin ``ccc_rust`` dependency to a reproducible reference (tag or commit hash). -* ``[ ]`` Define FRB module layout and generated file commit policy. -* ``[ ]`` Draft DTO type mapping table (Rust type -> bridge DTO -> Dart model). - -Backlog TODOs -------------- - -* ``[ ]`` Add CI job matrix for iOS/macOS/Android plugin builds. -* ``[ ]`` Add versioning/release policy for plugin package. -* ``[ ]`` Add troubleshooting notes for NDK/Xcode toolchains. - -Milestone 2 Verification Gate -============================= - -All of the following must pass before declaring Milestone 2 complete: - -* ``[ ]`` FRB bridge API compiles and loads in Flutter plugin. -* ``[ ]`` Generated Dart bindings are committed and reproducible. -* ``[ ]`` ``flutter build ios`` succeeds. -* ``[ ]`` ``flutter build apk`` succeeds. -* ``[ ]`` ``flutter build macos`` succeeds. -* ``[ ]`` Integration test suite passes on iOS simulator. -* ``[ ]`` Integration test suite passes on Android emulator/device. -* ``[ ]`` Plugin package is tagged/released at ``v0.1.0`` (or agreed target version). - -Notes -===== - -* Milestone 2 is the first place where ``flutter_rust_bridge`` is allowed. -* Milestone 1 Rust workspace remains bridge-free and should not be modified - for Dart/plugin scaffolding. diff --git a/docs/ccc_rust_plan_phases.rst b/docs/ccc_rust_plan_phases.rst index 044a78c..e4c4898 100644 --- a/docs/ccc_rust_plan_phases.rst +++ b/docs/ccc_rust_plan_phases.rst @@ -21,10 +21,14 @@ Three-Milestone Overview Milestone Repository Status ============= =================================== ============================ **1 (this)** ``ccc_rust`` Complete -**2** ``ccc_cryptography`` Not started +**2** ``ccc_cryptography`` In Progress **3** ``letusmsg`` (existing app) Not started ============= =================================== ============================ +.. note:: + Milestone 2 status updated 2026-03-16. Phases 1–5 complete; + Phase 6 in progress (macOS/iOS/Android passing; Linux + Windows deferred). + Milestone 1 Verification Gate is now passing. Milestone 2 may begin when scheduled. Milestone 3 does not start until the Milestone 2 gate passes.