FIX: stupid dumb ass shit, i'm pissed, cargo failing to auth to private git repo

.vscode/settings.json

@@ -3,5 +3,6 @@
     "cargo check": true,
     "flutter_rust_bridge_codegen": true,
     "rustup": true
-  }
+  },
+  "java.configuration.updateBuildConfiguration": "interactive"
 }

android/build.gradle.bak

@@ -29,24 +29,45 @@ android {
         namespace 'com.flutter_rust_bridge.ccc_cryptography'
     }
 
+    compileSdk = flutter.compileSdkVersion  // 36
+    ndkVersion = flutter.ndkVersion         // 28.2.13676358
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+        isCoreLibraryDesugaringEnabled = true
+    }
+
+    kotlinOptions {
+        jvmTarget = JavaVersion.VERSION_17.toString()
+    }
+
+    defaultConfig {
+        applicationId = "com.letusmsg.app.ccc_cryptography"
+        targetSdk = flutter.targetSdkVersion         // 36
+        versionCode = flutter.versionCode            // from pubspec.yaml, 2025.8.19+2 == 2
+        versionName = flutter.versionName            // from pubspec.yaml, 2025.8.19+2 == 2025.8.19
+        minSdk = flutter.minSdkVersion               // 24
+    }
+
     // Bumping the plugin compileSdkVersion requires all clients of this plugin
     // to bump the version in their app.
-    compileSdkVersion 33
+    // compileSdkVersion 33
 
     // Use the NDK version
     // declared in /android/app/build.gradle file of the Flutter project.
     // Replace it with a version number if this plugin requires a specfic NDK version.
     // (e.g. ndkVersion "23.1.7779620")
-    ndkVersion android.ndkVersion
+    // ndkVersion android.ndkVersion
 
-    compileOptions {
-        sourceCompatibility JavaVersion.VERSION_1_8
-        targetCompatibility JavaVersion.VERSION_1_8
-    }
+    // compileOptions {
+    //     sourceCompatibility JavaVersion.VERSION_1_8
+    //     targetCompatibility JavaVersion.VERSION_1_8
+    // }
 
-    defaultConfig {
-        minSdkVersion 19
-    }
+    // defaultConfig {
+    //     minSdkVersion 19
+    // }
 }
 
 apply from: "../cargokit/gradle/plugin.gradle"

android/build.gradle.kts

@@ -0,0 +1,53 @@
+import com.android.build.gradle.LibraryExtension
+import org.gradle.kotlin.dsl.configure
+import org.gradle.kotlin.dsl.withGroovyBuilder
+
+group = "com.flutter_rust_bridge.ccc_cryptography"
+version = "1.0"
+
+buildscript {
+    repositories {
+        google()
+        mavenCentral()
+    }
+
+    dependencies {
+        classpath("com.android.tools.build:gradle:7.3.0")
+    }
+}
+
+rootProject.allprojects {
+    repositories {
+        google()
+        mavenCentral()
+    }
+}
+
+apply(plugin = "com.android.library")
+apply(from = "../cargokit/gradle/plugin.gradle")
+
+configure<LibraryExtension> {
+    if (project.extensions.extraProperties.has("android") || project.extensions.findByName("android") != null) {
+        namespace = "com.flutter_rust_bridge.ccc_cryptography"
+    }
+
+    compileSdk = flutter.compileSdkVersion
+    ndkVersion = flutter.ndkVersion
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+
+    defaultConfig {
+        minSdk = flutter.minSdkVersion
+        targetSdk = flutter.targetSdkVersion
+    }
+}
+
+extensions.configure<Any>("cargokit") {
+    withGroovyBuilder {
+        setProperty("manifestDir", "../rust")
+        setProperty("libname", "ccc_cryptography")
+    }
+}

docs/ccc_fplugin_build_linux.rst

@@ -0,0 +1,483 @@
+CCC Flutter Plugin — Linux Build & Test Guide
+=============================================
+
+:Created: 2026-03-16
+:Status: Pending (Phase 4.4 and Phase 6.7)
+:Relates to: ``docs/ccc_fplugin_phases.rst`` §§ 4.4, 6.7
+:Platform: Linux — x86_64 (Ubuntu 22.04 LTS or later recommended)
+
+Overview
+--------
+
+The ``ccc_cryptography`` Flutter plugin is feature-complete on macOS, iOS,
+and Android.  All 16 integration tests pass on those three platforms.
+
+Two Linux-specific tasks remain open in the Milestone 2 verification gate:
+
+* **Phase 4.4** — ``flutter build linux`` succeeds
+* **Phase 6.7** — all 16 integration tests pass on a Linux host
+
+This guide provides the step-by-step procedure for a developer on a Linux
+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.4, 6.7,
+  and the Milestone 2 Verification Gate)
+* ``docs/ccc_fplugin_architecture_design.rst`` — plugin architecture
+* ``docs/ccc_fplugin_build_windows.rst`` — equivalent guide for Windows
+* ``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)**    **⏳ TBD**  **⏳ TBD**
+Windows (x86_64-msvc)           ⏳ deferred ⏳ deferred
+==============================  =========  ====================
+
+----
+
+Prerequisites
+-------------
+
+Install the following on the Linux host before proceeding.
+Commands shown assume **Ubuntu 22.04 LTS** (or Debian-compatible).
+Adjust package names for other distributions as needed.
+
+1. System Build Tools
+~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+  sudo apt update
+  sudo apt install -y \
+    build-essential \
+    cmake \
+    ninja-build \
+    pkg-config \
+    libgtk-3-dev \
+    git \
+    curl \
+    unzip
+
+``libgtk-3-dev`` is required by the Flutter Linux embedding.
+``cmake`` must be ≥ 3.10 (``linux/CMakeLists.txt`` minimum requirement).
+
+Verify::
+
+  cmake --version   # ≥ 3.10
+
+2. Clang / libclang
+~~~~~~~~~~~~~~~~~~~~
+
+wolfSSL's ``build.rs`` uses ``bindgen`` to generate Rust FFI bindings from
+C headers.  ``bindgen`` requires ``libclang`` at build time.
+
+::
+
+  sudo apt install -y clang libclang-dev
+
+Verify::
+
+  clang --version
+  llvm-config --version   # optional, confirms LLVM installation
+
+On Ubuntu 22.04 the default APT package installs Clang 14 and places
+``libclang.so`` in a path that ``bindgen`` finds automatically — no
+``LIBCLANG_PATH`` override is required in the typical case.
+
+3. Flutter SDK
+~~~~~~~~~~~~~~
+
+Follow the official Flutter Linux installation:
+https://docs.flutter.dev/get-started/install/linux
+
+After installation::
+
+  flutter doctor
+
+All items relevant to Linux desktop must be green.  Enable Linux desktop
+if not already done::
+
+  flutter config --enable-linux-desktop
+
+4. Rust Toolchain
+~~~~~~~~~~~~~~~~~
+
+Install ``rustup``::
+
+  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+  source "$HOME/.cargo/env"
+
+Verify the stable toolchain is active::
+
+  rustup show
+
+Add the Linux target if not already present::
+
+  rustup target add x86_64-unknown-linux-gnu
+
+5. SSH Access to the Internal Repository
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The bridge crate depends on ``ccc_rust`` hosted at the internal SSH server.
+Ensure the SSH key for ``git@10.0.5.109`` is present and loaded::
+
+  ssh -T git@10.0.5.109
+
+Confirm authentication succeeds before proceeding.
+
+----
+
+Rust Target Setup
+-----------------
+
+Add the Linux GNU target to the active toolchain::
+
+  rustup target add x86_64-unknown-linux-gnu
+
+Verify it is listed::
+
+  rustup target list --installed
+
+Expected output includes ``x86_64-unknown-linux-gnu``.
+
+----
+
+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 Linux machine and must be replaced before building.
+
+Two options are available:
+
+Option A — Local Clone (Development)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Clone ``lum_ccc_rust`` to a local path, then set path deps accordingly::
+
+  git clone ssh://git@10.0.5.109/j3g/lum_ccc_rust.git ~/src/lum_ccc_rust
+
+Edit ``rust/Cargo.toml``::
+
+  ccc-crypto-core    = { path = "/home/<user>/src/lum_ccc_rust/crates/ccc-crypto-core" }
+  ccc-crypto-wolfssl = { path = "/home/<user>/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
+---------------------
+
+Linux with the APT-installed ``clang`` + ``libclang-dev`` packages typically
+requires **no environment variable overrides** — bindgen locates
+``libclang.so`` via ``llvm-config`` automatically.
+
+LIBCLANG_PATH (if needed)
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If the build fails with a bindgen error about ``libclang`` not found, set
+``LIBCLANG_PATH`` explicitly::
+
+  export LIBCLANG_PATH=$(llvm-config --libdir)
+
+Add to ``~/.bashrc`` or ``~/.profile`` to make it permanent.
+
+To use ``.cargo/config.toml`` instead::
+
+  [env]
+  LIBCLANG_PATH = "/usr/lib/llvm-14/lib"
+
+Verify the library is present::
+
+  ls $LIBCLANG_PATH/libclang.so*
+
+BINDGEN_EXTRA_CLANG_ARGS (if needed)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If bindgen cannot locate system headers (e.g. ``stddef.h`` errors), add::
+
+  export BINDGEN_EXTRA_CLANG_ARGS="--target=x86_64-unknown-linux-gnu"
+
+This mirrors the ``BINDGEN_EXTRA_CLANG_ARGS`` fix applied for Android
+in Phase 4.6.  On Ubuntu 22.04 with standard clang, this is not expected
+to be necessary.
+
+----
+
+Phase 4.4 — Build Verification
+-------------------------------
+
+Run from the ``example/`` directory::
+
+  cd example
+  flutter build linux --release
+
+Expected result:
+
+* Build completes with no errors.
+* The compiled binary and Cargokit-built ``.so`` are placed in::
+
+    example/build/linux/x64/release/bundle/
+
+* Record the output bundle size for the verification gate entry.
+
+.. note::
+   Cargokit invokes ``cargo build --target x86_64-unknown-linux-gnu``
+   automatically during ``flutter build linux``.  The first build compiles
+   wolfSSL from source and may take several minutes.
+
+On success, update ``docs/ccc_fplugin_phases.rst`` task 4.4 to ✅ and record
+the build output bundle size.
+
+----
+
+Phase 6.7 — Integration Tests on Linux
+----------------------------------------
+
+Run from the ``example/`` directory::
+
+  cd example
+  flutter test integration_test/ccc_crypto_test.dart -d linux
+
+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 Linux-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.7 to ✅ and mark
+the corresponding Milestone 2 Verification Gate item.
+
+----
+
+Linux Verification Checklist
+-----------------------------
+
+Complete this checklist on the Linux 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
+   * - L-1
+     - ``rustup target add x86_64-unknown-linux-gnu`` installed and listed
+     - ☐
+   * - L-2
+     - ``rust/Cargo.toml`` updated — local macOS paths replaced with
+       git/SSH deps (or Linux local paths)
+     - ☐
+   * - L-3
+     - ``clang`` and ``libclang-dev`` installed; bindgen resolves
+       ``libclang.so`` without manual override
+     - ☐
+   * - L-4
+     - ``ssh -T git@10.0.5.109`` succeeds (SSH key loaded)
+     - ☐
+   * - L-5
+     - ``flutter build linux --release`` succeeds; bundle size recorded
+     - ☐
+   * - L-6
+     - Native ``.so`` present in the release bundle directory
+     - ☐
+   * - L-7
+     - ``flutter test integration_test/ccc_crypto_test.dart -d linux``
+       — 16/16 passed
+     - ☐
+   * - L-8
+     - Tasks 4.4 and 6.7 marked ✅ in ``docs/ccc_fplugin_phases.rst``
+     - ☐
+   * - L-9
+     - Milestone 2 Verification Gate Linux 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:** Install ``clang`` and ``libclang-dev``::
+
+  sudo apt install -y clang libclang-dev
+
+Then set ``LIBCLANG_PATH`` if bindgen still cannot find it::
+
+  export LIBCLANG_PATH=$(llvm-config --libdir)
+
+If multiple LLVM versions are installed, specify the one in use::
+
+  export LIBCLANG_PATH=/usr/lib/llvm-14/lib
+
+Missing system headers during bindgen
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Symptom:** bindgen reports it cannot find ``stddef.h``, ``stdint.h``,
+or similar C standard headers.
+
+**Fix:** Install the Linux headers package::
+
+  sudo apt install -y linux-libc-dev
+
+If the error persists, set::
+
+  export BINDGEN_EXTRA_CLANG_ARGS="--target=x86_64-unknown-linux-gnu"
+
+GTK development headers not found
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Symptom:** ``flutter build linux`` fails with errors about missing
+``gtk/gtk.h`` or ``pkg-config`` not finding ``gtk+-3.0``.
+
+**Fix:**::
+
+  sudo apt install -y libgtk-3-dev pkg-config
+
+cmake not found or too old
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Symptom:** Cargokit or ``flutter build linux`` fails with "CMake not
+found" or "CMake version 3.10 or later required".
+
+**Fix:**::
+
+  sudo apt install -y cmake
+
+Ubuntu 22.04 ships CMake 3.22 which satisfies the ≥ 3.10 requirement.
+If on an older distro, install via the Kitware APT repository or snap::
+
+  sudo snap install cmake --classic
+
+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::
+
+  eval "$(ssh-agent -s)"
+  ssh-add ~/.ssh/id_ed25519   # adjust key filename
+
+Or configure ``~/.ssh/config``::
+
+  Host 10.0.5.109
+      User git
+      IdentityFile ~/.ssh/id_ed25519
+
+flutter build linux fails — display not found
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Symptom:** Running integration tests on a headless server fails with
+a display-related error (Flutter Linux requires a display server).
+
+**Fix:** Use a virtual framebuffer::
+
+  sudo apt install -y xvfb
+  Xvfb :99 -screen 0 1280x1024x24 &
+  export DISPLAY=:99
+  flutter test integration_test/ccc_crypto_test.dart -d linux
+
+Alternatively, run on a machine with a desktop environment, or use a
+remote desktop session.
+
+ninja not found
+~~~~~~~~~~~~~~~~
+
+**Symptom:** CMake generates a build but ``ninja`` is not found.
+
+**Fix:**::
+
+  sudo apt install -y ninja-build
+
+----
+
+After Completion
+----------------
+
+Once both Phase 4.4 and Phase 6.7 are verified:
+
+1. Update ``docs/ccc_fplugin_phases.rst``:
+
+   * Mark tasks 4.4 and 6.7 ✅
+   * 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).
+
+Windows (Phase 4.5 / Phase 6.8) follows the same general pattern but
+substitutes ``x86_64-pc-windows-msvc`` as the Rust target.  LLVM must
+be installed manually on Windows, and ``LIBCLANG_PATH`` is always required.
+See ``docs/ccc_fplugin_build_windows.rst`` for full details.

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_<target>`` 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.

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

docs/ccc_rust_app_integration_phases.rst

@@ -0,0 +1,593 @@
+CCC Cryptography Plugin — Milestone 3 App Integration
+======================================================
+
+:Created: 2026-03-16
+:Status: Ready to Begin (API frozen; Windows + Linux tests deferred)
+:Audience: LetUsMsg application team
+:Plugin package: ``ccc_cryptography``
+:Plugin version: ``0.0.1`` (pre-tag; ``v0.1.0`` tag pending)
+:Milestone: 3 of 3
+
+Overview
+--------
+
+This document describes how the **LetUsMsg** application integrates the
+``ccc_cryptography`` Flutter plugin.
+
+Milestone 2 delivered a fully tested Flutter/Dart crypto plugin backed by
+``ccc_rust`` (wolfSSL).  All 16 integration tests pass on macOS, iOS, and
+Android.  Windows and Linux platform builds are deferred but do not block
+app integration — the Dart API is frozen.
+
+**The single rule for Milestone 3:** consume the published Dart API only.
+No Rust changes, no bridge changes, no modifications to the plugin source.
+
+Related Documents
+~~~~~~~~~~~~~~~~~
+
+* ``docs/ccc_fplugin_phases.rst`` — Milestone 2 phase completion status
+* ``docs/ccc_fplugin_architecture_design.rst`` — Plugin architecture
+* ``docs/ccc_fplugin_build_windows.rst`` — Windows build guide (deferred)
+
+----
+
+Open Items (not blocking M3 start)
+-----------------------------------
+
+The following Milestone 2 tasks are open but do not affect the Dart API:
+
+* ``flutter build windows`` / integration tests on Windows — deferred
+* ``flutter build linux`` / integration tests on Linux — deferred
+* ``CHANGELOG.md`` not yet updated
+* ``ccc_rust`` dependency commit not yet pinned to the final ``v0.1.0`` tag
+* Plugin not yet tagged ``v0.1.0``
+
+These will be resolved in parallel.  The app may begin integration against
+the current commit.  When the ``v0.1.0`` tag is cut, update the git ref in
+the app's ``pubspec.yaml``.
+
+----
+
+Phase Overview
+--------------
+
+======  ============================================  ==========  ============
+Phase   Title                                         Status      Depends on
+======  ============================================  ==========  ============
+M3-1    Add plugin dependency                         Not started —
+M3-2    App startup initialisation                    Not started M3-1
+M3-3    Replace AEAD crypto stubs                     Not started M3-2
+M3-4    Replace KDF stubs                             Not started M3-2
+M3-5    Replace MAC stubs                             Not started M3-2
+M3-6    Replace Hash stubs                            Not started M3-2
+M3-7    Replace KEM stubs                             Not started M3-2
+M3-8    Provider catalog integration                  Not started M3-2
+M3-9    Self-test debug UI                            Not started M3-2
+M3-10   Exception handling audit                      Not started M3-3–7
+M3-11   End-to-end app testing                        Not started M3-3–9
+======  ============================================  ==========  ============
+
+----
+
+Phase M3-1 — Add Plugin Dependency
+------------------------------------
+
+Add the plugin to the LetUsMsg ``pubspec.yaml``::
+
+  dependencies:
+    ccc_cryptography:
+      git:
+        url: ssh://git@10.0.5.109/j3g/ccc_fplugin.git
+        ref: main   # replace with "v0.1.0" once tagged
+
+Then fetch::
+
+  flutter pub get
+
+.. note::
+   The plugin is not published to pub.dev.  It is consumed as a git
+   dependency.  When the ``v0.1.0`` tag is cut, change ``ref: main``
+   to ``ref: v0.1.0`` and pin the dependency.
+
+----
+
+Phase M3-2 — App Startup Initialisation
+-----------------------------------------
+
+``CccCrypto.init()`` must be called **once** at application startup,
+before any cryptographic operation.  It registers the wolfSSL provider
+and initialises the FRB runtime.  It is safe to call multiple times
+(idempotent), but should be called exactly once in practice.
+
+Typical placement is in ``main()`` before ``runApp()``::
+
+  import 'package:ccc_cryptography/ccc_cryptography.dart';
+
+  Future<void> main() async {
+    WidgetsFlutterBinding.ensureInitialized();
+    await CccCrypto.init();
+    runApp(const MyApp());
+  }
+
+Exit criteria:
+
+* ``CccCrypto.init()`` called before any crypto operation in the app
+* No ``CccInternalError`` thrown at startup (provider registered OK)
+
+----
+
+Phase M3-3 — Replace AEAD Crypto Stubs
+-----------------------------------------
+
+Replace existing encrypt/decrypt stubs with ``CccCrypto.encryptAead``
+and ``CccCrypto.decryptAead``.
+
+API signatures
+~~~~~~~~~~~~~~
+
+.. code-block:: dart
+
+  // Encrypt — returns ciphertext with authentication tag appended
+  Future<Uint8List> CccCrypto.encryptAead({
+    required CccAeadAlgorithm algorithm,
+    required Uint8List key,
+    required Uint8List nonce,
+    required Uint8List plaintext,
+    Uint8List? aad,          // optional associated data; defaults to empty
+  });
+
+  // Decrypt — strips and verifies tag internally
+  // Throws CccAuthenticationFailed if tag does not verify
+  Future<Uint8List> CccCrypto.decryptAead({
+    required CccAeadAlgorithm algorithm,
+    required Uint8List key,
+    required Uint8List nonce,
+    required Uint8List ciphertext,   // ciphertext + tag as returned by encryptAead
+    Uint8List? aad,
+  });
+
+Algorithm enum and key/nonce sizes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+=========================  =====  =======  =====  ========
+``CccAeadAlgorithm``       ID     Key      Nonce  Tag
+=========================  =====  =======  =====  ========
+``aesGcm256``              12     32 B     12 B   16 B
+``chaCha20Poly1305``       13     32 B     12 B   16 B
+``xChaCha20Poly1305``      14     32 B     24 B   16 B
+``ascon128a``              15     16 B     16 B   16 B
+=========================  =====  =======  =====  ========
+
+.. important::
+   The returned ciphertext from ``encryptAead`` is
+   ``len(plaintext) + 16 bytes`` (plaintext + 16-byte tag concatenated).
+   Pass the entire slice to ``decryptAead`` — do not strip the tag
+   manually.
+
+Example
+~~~~~~~
+
+.. code-block:: dart
+
+  final key   = ... // 32 bytes, from KDF or secure RNG
+  final nonce = ... // 12 bytes, non-repeating per (key, message) pair
+
+  final ciphertext = await CccCrypto.encryptAead(
+    algorithm: CccAeadAlgorithm.aesGcm256,
+    key: key,
+    nonce: nonce,
+    plaintext: message,
+  );
+
+  final plaintext = await CccCrypto.decryptAead(
+    algorithm: CccAeadAlgorithm.aesGcm256,
+    key: key,
+    nonce: nonce,
+    ciphertext: ciphertext,   // full slice including tag
+  );
+
+----
+
+Phase M3-4 — Replace KDF Stubs
+---------------------------------
+
+API signature
+~~~~~~~~~~~~~
+
+.. code-block:: dart
+
+  Future<Uint8List> CccCrypto.deriveKey({
+    required CccKdfAlgorithm algorithm,
+    required Uint8List ikm,     // input key material
+    Uint8List? salt,             // optional; defaults to empty
+    Uint8List? info,             // optional context; defaults to empty
+    required int length,         // desired output length in bytes
+  });
+
+Algorithm enum
+~~~~~~~~~~~~~~
+
+==========================  =====  ==========
+``CccKdfAlgorithm``         ID     Notes
+==========================  =====  ==========
+``sha256``                  1      HKDF-SHA256
+``sha384``                  2      HKDF-SHA384
+``sha512``                  3      HKDF-SHA512
+``blake2b512``              4      BLAKE2b-512 KDF
+==========================  =====  ==========
+
+Example — derive a 32-byte session key via HKDF-SHA256
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: dart
+
+  final sessionKey = await CccCrypto.deriveKey(
+    algorithm: CccKdfAlgorithm.sha256,
+    ikm: sharedSecret,
+    salt: sessionSalt,
+    info: Uint8List.fromList(utf8.encode('letusmsg-session-v1')),
+    length: 32,
+  );
+
+----
+
+Phase M3-5 — Replace MAC Stubs
+---------------------------------
+
+API signatures
+~~~~~~~~~~~~~~
+
+.. code-block:: dart
+
+  Future<Uint8List> CccCrypto.computeMac({
+    required CccMacAlgorithm algorithm,
+    required Uint8List key,
+    required Uint8List data,
+  });
+
+  // Returns true if valid, false otherwise — never throws for tampered data
+  Future<bool> CccCrypto.verifyMac({
+    required CccMacAlgorithm algorithm,
+    required Uint8List key,
+    required Uint8List data,
+    required Uint8List mac,
+  });
+
+Algorithm enum
+~~~~~~~~~~~~~~
+
+========================  =====
+``CccMacAlgorithm``       ID
+========================  =====
+``hmacSha256``            30
+``hmacSha512``            32
+``blake2bMac``            33
+========================  =====
+
+.. note::
+   ``verifyMac`` uses a constant-time comparison in Rust to prevent
+   timing attacks.  Do not compare MAC tags in Dart.
+
+----
+
+Phase M3-6 — Replace Hash Stubs
+----------------------------------
+
+API signature
+~~~~~~~~~~~~~
+
+.. code-block:: dart
+
+  Future<Uint8List> CccCrypto.hash({
+    required CccHashAlgorithm algorithm,
+    required Uint8List data,
+  });
+
+Algorithm enum
+~~~~~~~~~~~~~~
+
+========================  =====
+``CccHashAlgorithm``      ID
+========================  =====
+``sha256``                40
+``sha384``                41
+``sha512``                42
+``blake2b512``            43
+``sha3_256``              44
+========================  =====
+
+----
+
+Phase M3-7 — Replace KEM Stubs
+---------------------------------
+
+API signatures
+~~~~~~~~~~~~~~
+
+.. code-block:: dart
+
+  // Key generation
+  Future<CccKemKeyPair> CccCrypto.kemGenerateKeypair({
+    required CccKemAlgorithm algorithm,
+  });
+  // CccKemKeyPair { Uint8List publicKey; Uint8List privateKey; }
+
+  // Encapsulation — sender uses recipient's public key
+  Future<CccKemEncapResult> CccCrypto.kemEncapsulate({
+    required CccKemAlgorithm algorithm,
+    required Uint8List publicKey,
+  });
+  // CccKemEncapResult { Uint8List ciphertext; Uint8List sharedSecret; }
+
+  // Decapsulation — recipient recovers shared secret
+  Future<Uint8List> CccCrypto.kemDecapsulate({
+    required CccKemAlgorithm algorithm,
+    required Uint8List privateKey,
+    required Uint8List ciphertext,
+  });
+
+Algorithm enum
+~~~~~~~~~~~~~~
+
+==========================  =====  ==============================
+``CccKemAlgorithm``         ID     Notes
+==========================  =====  ==============================
+``x25519``                  50     Available
+``x448``                    51     Available
+``mlKem768``                52     Deferred (not compiled in v0.1)
+``mlKem1024``               53     Deferred
+``classicMcEliece``         54     Deferred
+==========================  =====  ==============================
+
+.. warning::
+   ``privateKey`` in ``CccKemKeyPair`` is Dart-side memory.
+   Discard it as soon as decapsulation is complete.
+   Do not persist or log private keys.
+
+----
+
+Phase M3-8 — Provider Catalog Integration
+-------------------------------------------
+
+``CccProviderCatalog`` exposes runtime algorithm availability so the
+app can adapt its UI and protocol negotiation to what the provider
+actually supports.
+
+API
+~~~
+
+.. code-block:: dart
+
+  // One-shot fetch; cache the result for the session lifetime
+  final catalog = await CccCrypto.getCapabilities();
+
+  catalog.providerName          // "wolfssl"
+  catalog.aead                  // List<CccAlgorithmInfo>
+  catalog.availableAead         // filtered: only available == true
+  catalog.kdf / .availableKdf
+  catalog.mac / .availableMac
+  catalog.hash / .availableHash
+  catalog.kem / .availableKem
+
+  // CccAlgorithmInfo fields:
+  //   int     id                 (matches enum discriminant)
+  //   String  name               (e.g. "AES-256-GCM")
+  //   bool    available
+  //   bool    deterministicIo
+  //   int     efficiencyScore    (0–100)
+  //   int     reliabilityScore   (0–100)
+
+Also available — synchronous provider list::
+
+  final List<String> providers = CccCrypto.listProviders();
+  // ["wolfssl"]
+
+Suggested app usage
+~~~~~~~~~~~~~~~~~~~~
+
+* Cache the ``CccProviderCatalog`` in a top-level service singleton
+  after ``CccCrypto.init()``.
+* Use ``availableAead``, ``availableKem`` etc. to populate algorithm
+  selection UI and protocol negotiation logic.
+* Use ``efficiencyScore`` / ``reliabilityScore`` to recommend a default
+  algorithm when the user has no preference.
+
+----
+
+Phase M3-9 — Self-Test Debug UI
+----------------------------------
+
+Expose ``CccCrypto.runSelfTest()`` in a developer/debug settings screen
+to give field visibility into provider health.
+
+API
+~~~
+
+.. code-block:: dart
+
+  final CccSelfTestResult result = await CccCrypto.runSelfTest();
+
+  result.providerName   // "wolfssl"
+  result.allPassed      // bool — false if any algorithm fails
+  result.results        // List<CccAlgorithmTestResult>
+  result.failures       // filtered: only failed results
+
+  // CccAlgorithmTestResult fields:
+  //   int     algoId
+  //   String  algoName
+  //   bool    passed
+  //   String? errorMessage   // null on pass
+
+Known caveat
+~~~~~~~~~~~~
+
+The ``ccc_rust`` AEAD self-test vectors currently miscount the output
+length (they do not account for the appended 16-byte authentication tag).
+This causes ``AES-256-GCM`` and ``ChaCha20-Poly1305`` to report failures
+in the self-test report even though those algorithms work correctly.
+This is a known upstream bug in ``ccc_rust`` and does not affect
+production encrypt/decrypt operations.  The debug UI should note this
+when displaying AEAD self-test failures.
+
+----
+
+Phase M3-10 — Exception Handling Audit
+-----------------------------------------
+
+All ``CccCrypto`` methods throw typed subclasses of ``CccException``
+(a ``sealed class``).  The full hierarchy:
+
+.. code-block:: dart
+
+  sealed class CccException implements Exception {
+    final String message;
+  }
+
+  class CccUnsupportedAlgorithm extends CccException { ... }
+  class CccInvalidKey           extends CccException { ... }
+  class CccInvalidNonce         extends CccException { ... }
+  class CccAuthenticationFailed extends CccException { ... }
+  class CccInvalidInput         extends CccException { ... }
+  class CccFeatureNotCompiled   extends CccException { ... }
+  class CccInternalError        extends CccException { ... }
+
+Handling guidelines
+~~~~~~~~~~~~~~~~~~~~
+
+* Catch ``CccAuthenticationFailed`` specifically — it is the signal
+  for a tampered or corrupted message.  Do not silently discard it.
+* Catch ``CccUnsupportedAlgorithm`` at the protocol negotiation layer
+  to fall back gracefully.
+* Catch ``CccInvalidKey`` / ``CccInvalidNonce`` at the key-management
+  layer — these indicate a programming error (wrong buffer size) and
+  should be surfaced in development, not silently swallowed.
+* ``CccInternalError`` is unexpected; log it and surface a generic
+  "crypto failure" error to the user.
+
+Dart 3 exhaustive switch example
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: dart
+
+  try {
+    final ct = await CccCrypto.encryptAead(...);
+  } on CccException catch (e) {
+    switch (e) {
+      case CccAuthenticationFailed():
+        // message tampered
+      case CccInvalidKey():
+        // bad key — developer error
+      case CccInvalidNonce():
+        // bad nonce — developer error
+      case CccUnsupportedAlgorithm():
+        // negotiate fallback
+      case CccFeatureNotCompiled():
+        // algorithm not built in
+      case CccInvalidInput():
+        // bad input data
+      case CccInternalError():
+        // log and surface generic error
+    }
+  }
+
+Audit checklist
+~~~~~~~~~~~~~~~~
+
+For every call-site that replaces an existing crypto stub, verify:
+
+* ``CccAuthenticationFailed`` is caught and handled (not re-thrown as
+  a generic error)
+* Key / nonce sizes match the table in Phase M3-3 (wrong sizes →
+  ``CccInvalidKey`` / ``CccInvalidNonce``)
+* No raw ``CccException`` is exposed to end-users — wrap in
+  app-level error types
+
+----
+
+Phase M3-11 — End-to-End App Testing
+---------------------------------------
+
+Run the existing LetUsMsg integration test suite after all stubs are
+replaced to confirm no regressions.
+
+Additionally verify:
+
+* App startup completes with ``CccCrypto.init()`` — no crash or timeout
+* Encrypt → transmit → decrypt roundtrip succeeds on iOS, Android, macOS
+* Provider catalog loads and populates the settings UI correctly
+* Self-test screen shows expected results (note AEAD caveat above)
+* No ``CccException`` surfaces to end-users under normal operation
+* Private key material is not logged or persisted anywhere in the app
+
+----
+
+Hard Boundaries for Milestone 3
+---------------------------------
+
+The following are **forbidden** during app integration:
+
+* Modifying any file in the ``ccc_cryptography`` plugin repository
+* Implementing cryptographic logic in Dart
+* Calling ``ccc_rust`` or ``flutter_rust_bridge`` APIs directly
+* Depending on internal generated files
+  (e.g. ``src/rust/api/crypto.dart``, ``frb_generated.dart``)
+* Persisting or logging raw private keys (``CccKemKeyPair.privateKey``)
+
+The app must depend **only** on the public barrel export::
+
+  import 'package:ccc_cryptography/ccc_cryptography.dart';
+
+----
+
+Algorithm ID Quick Reference
+------------------------------
+
+These IDs match the ``cipher_constants.dart`` integer constants in the
+existing app exactly — no translation layer is needed.
+
+=========================  =====  ============================
+Algorithm                  ID     Category
+=========================  =====  ============================
+``aesGcm256``              12     AEAD
+``chaCha20Poly1305``       13     AEAD
+``xChaCha20Poly1305``      14     AEAD
+``ascon128a``              15     AEAD
+``sha256`` (KDF)           1      KDF (HKDF-SHA256)
+``sha384`` (KDF)           2      KDF (HKDF-SHA384)
+``sha512`` (KDF)           3      KDF (HKDF-SHA512)
+``blake2b512`` (KDF)       4      KDF
+``hmacSha256``             30     MAC
+``hmacSha512``             32     MAC
+``blake2bMac``             33     MAC
+``sha256`` (Hash)          40     Hash
+``sha384`` (Hash)          41     Hash
+``sha512`` (Hash)          42     Hash
+``blake2b512`` (Hash)      43     Hash
+``sha3_256``               44     Hash
+``x25519``                 50     KEM
+``x448``                   51     KEM
+``mlKem768``               52     KEM (deferred)
+``mlKem1024``              53     KEM (deferred)
+``classicMcEliece``        54     KEM (deferred)
+=========================  =====  ============================
+
+----
+
+Milestone 3 Completion Gate
+----------------------------
+
+*All items must be checked before Milestone 3 is considered complete.*
+
+* ``[ ]`` Plugin added to LetUsMsg ``pubspec.yaml``
+* ``[ ]`` ``CccCrypto.init()`` called at app startup
+* ``[ ]`` All AEAD crypto stubs replaced (Phase M3-3)
+* ``[ ]`` All KDF stubs replaced (Phase M3-4)
+* ``[ ]`` All MAC stubs replaced (Phase M3-5)
+* ``[ ]`` All Hash stubs replaced (Phase M3-6)
+* ``[ ]`` All KEM stubs replaced (Phase M3-7)
+* ``[ ]`` Provider catalog surface integrated (Phase M3-8)
+* ``[ ]`` Self-test debug UI surface integrated (Phase M3-9)
+* ``[ ]`` Exception handling audit complete (Phase M3-10)
+* ``[ ]`` End-to-end app tests pass on iOS, Android, macOS (Phase M3-11)
+* ``[ ]`` No raw private keys exposed, logged, or persisted
+* ``[ ]`` Plugin dep pinned to ``v0.1.0`` git tag (when cut)

docs/ccc_rust_milestone2_session_state_OLD.rst

@@ -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.

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.

pubspec.yaml

@@ -1,7 +1,7 @@
 name: ccc_cryptography
 description: "Copius Cipher Chain Cryptography"
 publish_to: 'none'
-version: 0.0.1
+version: 0.2.0
 
 environment:
   sdk: ^3.10.1
@@ -10,18 +10,18 @@ environment:
 dependencies:
   flutter:
     sdk: flutter
-  plugin_platform_interface: ^2.0.2
-  flutter_rust_bridge: 2.11.1
-  freezed_annotation: ^2.4.1
-  meta: ^1.11.0
+  plugin_platform_interface: ^2.1.8
+  flutter_rust_bridge: 2.11.1  # pinned to match codegen version in frb_generated.dart, 2.12.0 is not compatible at this time
+  freezed_annotation: ^3.1.0
+  meta: ^1.17.0  #1.18.2 latest not allowed because of compatibility issues with other dependencies
 
 dev_dependencies:
-  ffi: ^2.1.3
+  ffi: ^2.2.0
   flutter_test:
     sdk: flutter
   flutter_lints: ^6.0.0
-  build_runner: ^2.4.8
-  freezed: ^2.5.2
+  build_runner: ^2.13.1
+  freezed: ^3.2.5
   integration_test:
     sdk: flutter
 

rust/.cargo/config.toml

@@ -0,0 +1,2 @@
+[net]
+git-fetch-with-cli = true

rust/Cargo.toml

@@ -1,16 +1,18 @@
 [package]
 name = "ccc_cryptography"
-version = "0.1.0"
+version = "0.2.0"
 edition = "2021"
 
 [lib]
 crate-type = ["cdylib", "staticlib"]
 
 [dependencies]
-# Local dev paths — switch to git deps for CI/release:
-# 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" }
-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" }
+ccc-crypto-core = { git = "ssh://git@10.0.5.109/j3g/lum_ccc_rust.git", branch = "trunk" }
+ccc-crypto-wolfssl = { git = "ssh://git@10.0.5.109/j3g/lum_ccc_rust.git", branch = "trunk" }
+
+# For local development, you can uncomment the following lines and comment out the git dependencies above:
+# 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" }
+
 flutter_rust_bridge = "=2.11.1"
 log = "0.4"