lum_ccc_rust/docs/encryption_implementation_phases.rst

====================================================================
LetUsMsg Encryption Architecture – Phased Implementation Plan
====================================================================

:Project: LetUsMsg
:Date: 2026-02-20
:Status: Phase 0 COMPLETED · Phase 1 COMPLETED · Phase 2 COMPLETED
:Codename: Hydra Apocalypse Ratchet
:Reference: ``encryption_implementation_normal-ccc.rst``, ``encryption_implementation_ultra-ccc.rst``


Phase Progress Status
=====================

.. list-table::
   :header-rows: 1
   :widths: 10 40 15

   * - Phase
     - Title
     - Status
   * - 0
     - Security Baseline Hardening
     - **COMPLETED**
   * - 1
     - Normal Mode v1 (Classical + Hybrid-Ready)
     - **COMPLETED**
   * - 2
     - Ratchet Core (Forward Secrecy / Post-Compromise Security)
     - **COMPLETED**
   * - 3
     - Full Normal Mode Target Parity
     - Not started
   * - 4
     - Native Crypto Provider (wolfSSL FFI + Capability Matrix)
     - Not started
   * - 5
     - Ultra Secret Mode (Triple-Compound Ratchet)
     - Not started
   * - 6
     - Encrypted Channel Blob + Invite Crypto
     - Not started
   * - 7
     - Verification, Audit, and Deployment Hardening
     - Not started



Executive Summary
=================

This document is the single implementation-facing plan for the LetUsMsg
Hydra Apocalypse Ratchet encryption system. The full cryptographic
specifications for each mode live in dedicated companion documents:

- **Normal mode** (default): see ``encryption_implementation_normal-ccc.rst``
- **Ultra Secret mode** (opt-in): see ``encryption_implementation_ultra-ccc.rst``

The target architecture is **dual-mode per channel**:

- **Normal mode**: highly configurable, post-quantum hybrid Double Ratchet.
  User-chosen primitives and providers. Fast, highly secure, PQ-ready
  migration path. Stronger than Signal's 2026 PQ Triple Ratchet by design.

- **Ultra Secret mode**: Triple-Compound Ratchet (inner hybrid ratchet +
  massive 16–24 layer secret cascade + per-message sequence mutation).
  Maximum defense-in-depth for threat models that assume nation-state
  primitive compromise.

Both modes share the **CCCData** model as the single source of truth for
per-channel encryption configuration.

Threat model:

- Possible hidden weaknesses / backdoors in individual primitives.
- Harvest-now-decrypt-later quantum risk.
- Targeted high-budget cryptanalysis.
- Chosen / known-plaintext amplification in messaging systems.



Design Principles
=================

- **Defense in depth**: multiple independent primitive families where practical.
- **Forward secrecy + post-compromise security** via ratcheting.
- **Per-group uniqueness** and **per-message mutation**.
- **Dependent one-way key derivation** (HKDF / KMAC family).
- **Conservative ordering** in cascade layers.
- **User cryptographic sovereignty**: every primitive, provider, and parameter
  is user-selected at channel creation time through CCCData.
- **Length-hiding padding**:

  - Normal mode: minimal overhead (16–32 bytes).
  - Ultra mode: pad to 64-byte boundary + 32–64 bytes random-derived padding.

- **Ephemeral relay compatibility**: larger ciphertext overhead is acceptable
  given the stateless-RAM relay architecture.
- **Background-isolate execution**: all crypto / network / storage runs off
  the main UI isolate (``worker_manager`` pool).



What Exists Now (update according to progress)
==============================================

* Current: (Post Phase 0 + Phase 1 + Phase 2 Progress)


CCC Infrastructure (20 files in ``flutter_src/lib/ccc/``)
----------------------------------------------------------

.. list-table::
   :header-rows: 1
   :widths: 35 65

   * - File
     - Purpose
   * - ``crypto_abstract.dart``
     - ``CryptoAbstract<T>`` interface, ``CryptoContext``, ``CryptoProviderMode`` enum
   * - ``crypto_ccc.dart``
     - ``CryptoCcc`` – production provider backed by ``CryptoIsolateManager``
   * - ``crypto_plaintext.dart``
     - ``CryptoPlaintext`` – testing/dev-only plaintext alias (blocked in prod)
   * - ``crypto_wolfssl.dart``
     - ``CryptoWolfSsl`` – scaffold only, throws ``UnimplementedError`` (Phase 4)
   * - ``ccc_iso_manager.dart``
     - ``CryptoIsolateManager`` – 4-worker pool, encrypt/decrypt dispatch, metrics
   * - ``ccc_iso.dart``
     - Isolate worker with 6 implemented primitives (see below)
   * - ``ccc_iso_operation.dart``
     - ``CryptoOperation`` value object (channel, sequence, cipher, priority)
   * - ``ccc_iso_operation_id.dart``
     - Sequence-based fast operation ID generator
   * - ``ccc_iso_result.dart``
     - ``CryptoResult`` + ``CryptoMetrics`` (timing, throughput, error rate)
   * - ``ccc_key_schedule.dart``
     - ``CccKeySchedule`` – Phase 1 deterministic root-key + per-message key derivation
   * - ``ccc_channel_profile.dart``
     - ``ChannelCccProfile`` – per-channel combo/iteration/mode resolution + route planning
   * - ``ccc_provider_spec.dart``
     - ``CccProviderCatalog``, ``CccCipherCapability``, execution-mode routing
   * - ``ccc_kdf.dart``
     - ``CccKdfFunction`` enum (SHA-256/384/512, BLAKE2b-512) + normalization
   * - ``cipher_constants.dart``
     - 35+ cipher constants, ``PHASE1_SEQUENCE``, ``BASIC_*_SEQUENCE``, ``DUAL_AEAD_SEQUENCE``,
       ``TRIPLE_AEAD_SEQUENCE``, ``COMBO_NAMES``, ``COMBO_SEQUENCES``
   * - ``copious_cipher_chain.dart``
     - ``CopiousCipherChain`` – high-level facade with round-trip testing
   * - ``attachment_crypto_context.dart``
     - Lightweight context carrier for attachment encrypt/decrypt
   * - ``enc_dec_json.dart``
     - ``EncDecJson`` – plaintext JSON codec retained for testing
   * - ``ratchet_engine.dart``
     - ``RatchetEngine`` – symmetric ratchet core: init, advance, checkpoint, old-message derivation
   * - ``ratchet_state_manager.dart``
     - ``RatchetStateManager`` – Hive CRUD for ``RatchetState``, channel-level cleanup


Implemented Primitives (via ``cryptography`` package)
-----------------------------------------------------
All implemented in the isolate worker (``ccc_iso.dart``):

- AES-256-GCM (AEAD)
- ChaCha20-Poly1305 (AEAD)
- XChaCha20-Poly1305 (AEAD, 24-byte nonce)
- HMAC-SHA512 (authentication layer)
- BLAKE2b (integrity hash)
- Argon2id (key derivation, reserved – not in default Phase 1 chain)

Default ``PHASE1_SEQUENCE`` (5 layers, combo 0):
``AES-256-GCM → ChaCha20-Poly1305 → XChaCha20-Poly1305 → HMAC-SHA512 → BLAKE2b``

User-selectable combos:

- **Combo 5** – Basic: AES-256-GCM (single AEAD)
- **Combo 6** – Basic: ChaCha20-Poly1305 (single AEAD)
- **Combo 7** – Basic: XChaCha20-Poly1305 (single AEAD, 24-byte nonce)
- **Combo 8** – Dual AEAD: AES-256-GCM + ChaCha20-Poly1305
- **Combo 9** – Triple AEAD: AES + ChaCha20 + XChaCha20


Derived-Key Encryption (Real E2E)
---------------------------------
All AEAD / HMAC layers now support **derived-key mode** when the key
schedule parameter ``phase1_root_key_b64`` is present in cipher params.

Key derivation formula per layer::

    layer_key = SHA-512(root_key_bytes || "|lk|{layerIndex}|c|{cipherConstant}"),
                truncated to cipher's key length (32 B for AEADs, 64 B for HMAC)

Output format comparison:

.. list-table::
   :header-rows: 1
   :widths: 20 40 40

   * - Layer Type
     - Legacy (random key in blob)
     - Derived-key (real E2E)
   * - AEAD (AES/ChaCha/XChaCha)
     - ``[32B key][nonce][ct][16B MAC]``
     - ``[nonce][ct][16B MAC]``
   * - HMAC-SHA512
     - ``[64B key][data][64B MAC]``
     - ``[data][64B MAC]``
   * - BLAKE2b
     - ``[data][64B hash]`` (keyless)
     - ``[data][64B hash]`` (unchanged)

Size savings for standard 5-layer combo: **160 bytes per message**
(3×32 B AEAD keys + 64 B HMAC key no longer embedded).

Legacy mode (random keys embedded) is retained for backwards compatibility
when ``phase1_root_key_b64`` is absent in params.


AEAD Associated Data
--------------------
All AEAD layers bind canonicalized associated data including:
channel UUID, KDF function, CCC combo, CCC iterations.

Phase 1 exclusions (both stripped by the isolate worker before AEAD binding):

- **direction**: sender uses ``'out'``, receiver uses ``'in'`` for the same
  ciphertext, so it cannot be bound.
- **message_sequence**: the sender encrypts before the relay assigns
  ``server_seq``, so the receiver's relay sequence would mismatch.  Sequence
  binding will be re-enabled in Phase 2 when the ratchet provides
  agreed-upon per-message counters.


Message + Attachment Pipeline Integration
-----------------------------------------
- ``ProcBgMsg`` selects ``CryptoCcc`` or ``CryptoPlaintext`` at runtime.
- Production builds reject plaintext mode.
- ``_buildCryptoContext()`` resolves channel → ``ChannelCccProfile`` → ``CccKeySchedule.buildMessageParams()`` → full ``CryptoContext``.
- Attachment paths in ``proc_bg_actions.dart`` use the same ``ChannelCccProfile`` + ``CccKeySchedule`` pipeline.


Provider Routing Infrastructure
--------------------------------
- 4 providers defined: ``cryptography`` (available), ``wolfssl`` / ``openssl`` / ``boringssl`` (scaffold, ``available: false``).
- 3 execution modes: ``strict`` (no fallback), ``efficient`` (ranked by score), ``auto`` (capability-based).
- 10 combo patterns (0–9) in ``ChannelCccProfile`` mapping to different
  provider/cipher combinations.  Combos 1–4 are multi-provider scaffolds;
  combos 5–9 are user-selectable single/dual/triple AEAD configurations.
- Iteration expansion (1–16x repetition of cipher sequence).


Test Suites (11 files, 82 tests)
--------------------------------
.. list-table::
   :header-rows: 1
   :widths: 35 65

   * - Test File
     - Coverage
   * - ``ccc_phase0_security_test.dart``
     - Ciphertext ≠ plaintext, tamper-fail, nonce uniqueness (legacy mode)
   * - ``ccc_key_schedule_test.dart``
     - Deterministic keys, sequence variation, KDF selection, CCCData round-trip
   * - ``ccc_channel_profile_test.dart``
     - Default profiles, combo-specific mapping (0–9), iteration clamping/expansion, modes,
       unknown combo fallback
   * - ``ccc_associated_data_test.dart``
     - AD tampering, KDF mismatch, channel mismatch, combo mismatch, Phase 1 sequence tolerance
   * - ``ccc_e2e_roundtrip_test.dart``
     - Sender→receiver roundtrip (default + custom CCC), cross-channel rejection,
       empty/large payloads, nonce uniqueness, tamper rejection, all 4 KDFs, combo mismatch
   * - ``ccc_derived_key_test.dart``
     - Derived-key ciphertext size savings, all combos 5–9 roundtrip, minimal overhead
       (combo 5), root-key isolation between channels, iterated derived-key roundtrip,
       cross-combo rejection, tamper detection, large payload triple AEAD, empty payload,
       combo metadata consistency
   * - ``ccc_ratchet_engine_test.dart``
     - RatchetEngine determinism, forward-only chain, checkpoint accuracy, old-message
       derivation, KDF function selection, RatchetState data model, asymmetric stub (28 tests)
   * - ``ccc_ratchet_roundtrip_test.dart``
     - Phase 2 ratchet E2E roundtrip: single/multi-message, all single-cipher combos,
       multi-layer combos, large payload (11 tests)
   * - ``ccc_ratchet_3party_test.dart``
     - 3-party group N-party state model: chain isolation, cross-sender misuse detection,
       receiver agreement, interleaved multi-message, independent counters (10 tests)
   * - ``ccc_ratchet_state_test.dart``
     - RatchetState data model, Hive serialization round-trip, empty/large counters,
       multi-state box, overwrite semantics (9 tests)
   * - ``ccc_ratchet_state_manager_test.dart``
     - RatchetStateManager CRUD: open/close, save/load, exists, delete, deleteChannel,
       listForChannel, lazy reopen, key isolation (17 tests)


Data Model (``CCCData`` in Hive)
---------------------------------

Current persisted fields:

- ``combo`` (int) – cipher chain combination pattern
- ``iterrations`` (int) – encryption rounds
- ``executionMode`` (String) – strict / efficient / auto
- ``kdfFunction`` (int) – KDF selector (1=SHA-256, 2=SHA-384, 3=SHA-512, 4=BLAKE2b-512)
- ``ratchetFrequency`` (int) – asymmetric ratchet trigger cadence (default 50)
- ``symmetricRatchetEveryMessage`` (bool) – advance chain per message (default true)
- ``rekeyInterval`` (int) – full rekey interval (reserved, default 0)
- ``checkpointInterval`` (int) – checkpoint every N messages (default 500)

Reserved non-persisted fields: ``passHash``, ``comboHash``, ``pubpvt``, ``pub``
(all ``Uint8List?``, for future key-exchange integration).


What Is Not Yet Implemented
---------------------------
- Asymmetric (KEM) ratchet activation (stub in place, Phase 3).
- PQ KEM integration (ML-KEM / Kyber, Classic McEliece, BIKE / HQC).
- X448 key exchange.
- Ascon-AEAD-128a.
- KMAC256 plumbing in key schedule.
- ``dart:ffi`` native crypto bridge (wolfSSL / BoringSSL / libsodium).
- Full modular CCCData with user-selectable providers / algorithms (per Normal-CCC spec).
- Encrypted channel blob for invite sharing.
- Ultra Secret mode cascade / sequence ratchet.
- Length-hiding padding per ``CCCData.blockSize`` + ``minPaddingBytes``.
- Channel creation UI for crypto sovereignty settings.



Phased Implementation Plan
==========================

Phase 0 – Security Baseline Hardening: **COMPLETED**
-----------------------------------------------------

Objectives:

- Replace encode/decode placeholder usage in message path.
- Keep plaintext mode available for development/testing only.
- Introduce cryptographic interface boundaries for provider swap.

Deliverables (all completed):

- ``EncDecJson`` retained as plaintext/testing implementation.
- Legacy ``passthroughMode`` removed from ``CryptoIsolateManager``.
- ``CryptoAbstract`` provider boundary with ``CryptoPlaintext``, ``CryptoCcc``,
  and ``CryptoWolfSsl`` scaffold.
- ``ChannelCccProfile`` for per-channel CCC plan with provider chain + cipher route.
- Channel-derived CCC context threaded through message + attachment encrypt/decrypt.
- Baseline security tests (ciphertext ≠ plaintext, tamper-fail, nonce uniqueness).


Phase 1 – Normal Mode v1 (Classical + Hybrid-Ready): **COMPLETED**
---------------------------------------------------------------------

Objectives:

- Deliver production-safe Normal mode with current available primitives.
- Integrate message encryption + attachment encryption under a consistent
  channel/message key schedule.
- Enforce AEAD associated-data binding for replay/tamper protection.

Deliverables:

- [x] ``CccKeySchedule`` – deterministic channel root-key derivation +
  per-message key material derivation with selectable KDF function.
- [x] ``ProcBgMsg`` crypto context generation wired to ``ChannelCccProfile`` +
  ``CccKeySchedule.buildMessageParams()``.
- [x] Unified BG attachment crypto context in ``proc_bg_actions`` –
  attachment read/write paths use key-schedule-enriched params.
- [x] AEAD associated-data binding enforced in isolate worker layers
  (AES-GCM / ChaCha20-Poly1305 / XChaCha20-Poly1305).
- [x] Negative security guards passing:

  - decrypt fails when associated data is modified,
  - decrypt fails when ``kdfFunction`` changes,
  - decrypt fails when channel context changes,
  - decrypt fails when ``ccc_combo`` changes.

  Phase 1 note: ``message_sequence`` and ``direction`` are excluded from
  AEAD binding because the sender cannot know the relay-assigned
  ``server_seq`` at encryption time, and direction differs between
  sender/receiver.  Sequence binding will be re-enabled in Phase 2
  when the ratchet provides agreed-upon counters.

- [x] Production builds reject plaintext mode at runtime.
- [x] E2E roundtrip verification: sender encrypt → receiver decrypt
  succeeds across default and custom CCCData, all 4 KDFs, empty and
  large payloads (``ccc_e2e_roundtrip_test.dart``, 9 tests).
- [x] All outbound/inbound messages encrypted/decrypted through worker crypto
  (key-schedule integration verified end-to-end).
- [x] **Derived-key encryption** – AEAD/HMAC layers derive per-layer keys
  from ``phase1_root_key_b64`` via ``SHA-512(rootKey || domain-label)``.
  Keys are never embedded in ciphertext (real E2E: only channel members
  who compute the same root key can decrypt).
- [x] **Combo 5-9 (Basic through Triple AEAD)** – user-selectable single,
  dual, and triple AEAD configurations for crypto sovereignty.
- [x] Constant-time MAC/hash verification (``_verifyMacBytes``).

Exit Criteria:

- All outbound/inbound messages encrypted/decrypted through worker crypto.
- Attachments + message payloads use one coherent key derivation model.
- No pass-through encryption mode in production builds.

Remaining Work: **ALL DONE – Phase 1 CLOSED 2026-02-19**

- [x] **Live relay E2E smoke test** – ``test_manual/ccc_relay_e2e_test.dart``
  confirmed: combo 0 (228 B) and combo 8 Dual-AEAD (284 B) encrypt → relay →
  decrypt both passed against a real localhost relay2 gRPC instance.
- [x] ``_runtimeProviderMode`` flipped to ``CryptoProviderMode.ccc``
  (``proc_bg_msg.dart``).  Combo 0 channels continue as plaintext pass-through
  at the cipher layer for backwards compatibility.
- [x] ``crypto_mode_guard`` restored to ``isDeveloperMode`` gate.


Phase 2 – Ratchet Core (Forward Secrecy / Post-Compromise Security): **COMPLETED**
-------------------------------------------------------------------------------------

:Reference: ``normal_mode_ratchet_implementation.rst``

Objectives:

- Implement the symmetric Double Ratchet for per-message forward secrecy.
- Add ``RatchetState`` persistence model to Hive for per-channel per-sender
  chain keys and counters.
- Integrate ratchet key derivation into the existing ``ProcBgMsg`` →
  ``CryptoCcc`` → isolate worker pipeline (replacing Phase 1 static keys).
- Maintain full backwards compatibility with pre-ratchet channels.
- Provide checkpoint-based random-access decryption for old messages.
- Build infrastructure for asymmetric (KEM) ratchet step (activated Phase 3).

Implementation Notes:

- The isolate worker (``ccc_iso.dart``) requires **zero changes** — it already
  derives per-layer keys from a root key.  The ratchet simply provides a
  different root key for each message.
- ``RatchetEngine`` is a pure-logic class with static methods that operate
  on ``RatchetState`` + ``CCCData``.  It runs on the background isolate.
- Sender counter (``sc``) is embedded inside the encrypted payload — invisible
  to relay, authenticated by AEAD.
- Checkpoints every 500 messages (configurable) allow O(500) chain replay
  instead of O(N) from genesis when decrypting old messages.

Deliverables:

- [x] ``RatchetState`` Hive model (typeId 18) with chain keys, counters,
  checkpoints, channel/sender identifiers.
- [x] ``RatchetEngine`` core: ``initializeFromRoot()``, ``advanceSending()``,
  ``advanceReceiving()``, ``deriveKeyForOldMessage()``, KDF helpers.
- [x] ``RatchetStateManager``: Hive box lifecycle, CRUD, channel deletion
  cleanup.
- [x] ``CCCData`` extended with ratchet fields: ``ratchetFrequency``,
  ``symmetricRatchetEveryMessage``, ``rekeyInterval``, ``checkpointInterval``.
- [x] ``ProcBgMsg`` integration: ratchet-derived keys replace static
  ``CccKeySchedule`` keys in encrypt/decrypt path.
- [x] Sender counter (``sc``) field in wire payload (inside encrypted data)
  + ``sender_counter`` proto field on ``Message``/``MessageOne``.
- [x] Channel lifecycle hooks: ratchet init on create/invite-accept,
  cleanup on channel delete, lazy init for unknown senders on receive.
- [x] Asymmetric ratchet stub (``performAsymmetricRatchet()`` no-op, called
  at configured frequency, ``rk`` payload field reserved for Phase 3).
- [x] ``MsgDataOutCache`` schema extended with ``senderCounter`` +
  ``senderUuid`` for offline retry ratchet metadata preservation.
- [x] Test suite: ``ccc_ratchet_state_test.dart``,
  ``ccc_ratchet_state_manager_test.dart``, ``ccc_ratchet_engine_test.dart``,
  ``ccc_ratchet_roundtrip_test.dart``, ``ccc_ratchet_3party_test.dart``.

Remaining Work: **ALL DONE – Phase 2 CLOSED**

Exit Criteria:

- Every message uses a unique ratchet-derived key (no two messages share the
  same base_message_key).
- Forward secrecy verified: advancing the chain and deleting old keys means
  past messages cannot be derived from current state.
- Checkpoint-based old-message decryption works within 500-step replay bound.
- Pre-ratchet channels fall back to Phase 1 static key schedule without errors.
- All existing Phase 0/1 tests continue to pass.
- New ratchet test suite passes (determinism, forward-only, E2E round-trip).
- Sender counter survives round-trip through encrypt → relay → decrypt.



Phase 3 – Full Normal Mode Target Parity
-----------------------------------------

Objectives:

- Reach the full Normal-mode design target from the Normal-CCC spec.
- Deliver user-facing crypto sovereignty (provider/algorithm selection UI).
- Complete Normal mode using the existing ``cryptography`` Dart package (no FFI required).

**Phase 3a – Implemented (current sprint)**:

- **Expanded CCCData model** — 6 new HiveFields (8–13):

  - ``rekeyMode`` (HF 8, String, default ``'manual'``).
  - ``minPaddingBytes`` (HF 9, int, default 32).
  - ``blockSize`` (HF 10, int, default 256).
  - ``groupId`` (HF 11, ``List<int>?``, nullable for legacy).
  - ``createdAt`` (HF 12, int, default 0).
  - ``creatorDeviceId`` (HF 13, ``List<int>?``, nullable).
  - ``fromMap()``, ``toMap()``, ``blank()``, ``equals()`` all updated.
  - Hive codegen regenerated.

- **Length-hiding padding** in ``ccc_iso.dart``:

  - ``_applyPadding(plaintext, params)``: pads to next multiple of
    ``blockSize`` with at least ``minPaddingBytes`` random bytes.
    Format: ``[plaintext][random_padding][4-byte LE padding_length]``.
  - ``_stripPadding(paddedData)``: reads trailer, validates, strips.
    Falls back gracefully for pre-Phase-3 legacy data.
  - Wired through ``ChannelCccProfile.fromCccData()`` → isolate params.
  - 16 tests (unit + E2E integration) all passing.

- **Asymmetric ratchet activation** — X25519 via ``cryptography`` package:

  - ``RatchetState`` expanded with DH key fields (HiveFields 8–11):
    ``dhPrivateKey``, ``dhPublicKey``, ``remoteDhPublicKey``,
    ``lastAsymmetricRatchetCounter``.
  - ``RatchetEngine.performAsymmetricRatchet()``: generates fresh X25519
    keypair, mixes public-key entropy into chain via KDF
    (``KDF(chainKey || pubKeyBytes, "asymmetric-reset|channelUuid")``).
    Group-compatible: all receivers apply same public key bytes.
  - ``RatchetEngine.applyRemoteAsymmetricRatchet()``: receive-side method
    that applies the same chain reset from the payload ``rk`` field.
  - ``RatchetAdvanceResult.asymmetricRatchetPublicKey``: 32-byte X25519
    public key returned when asymmetric step fires (null otherwise).
  - ``advanceSending()`` wired to capture and propagate the public key.
  - DH private key stored for potential Phase 4 pairwise DH enhancement.
  - 12 dedicated asymmetric ratchet tests (unit + E2E) all passing.
  - All 53 existing ratchet tests continue to pass.

**Phase 3b – Remaining (future sprints)**:

- ``CryptoSelection`` Hive model (provider + algorithm + priority).

- ``enabledProviders``: user-selected list.
  Per-category configs: ``kemConfigs``, ``aeadConfigs``, ``kdfConfigs``, ``hashConfigs``.

- Hybrid KEM/DH integration (target: X448 + ML-KEM-1024 Kyber, when pure-Dart packages available).

- Ascon-AEAD-128a added to negotiated AEAD profile (deferred — no pure-Dart impl exists).

- Round-robin AEAD encryption using ``aeadConfigs`` from CCCData.

- Channel creation UI:

  - Provider picker + category lists for KEM, AEAD, KDF, Hash.
  - Defaults pre-selected and highlighted (best-in-class).
  - Advanced mode toggle for power users.

- Ratchet cadence + negotiation policy finalized and versioned.

- ProcBgMsg integration: embed ``rk`` field in encrypted payload on send,
  extract and call ``applyRemoteAsymmetricRatchet()`` on receive.

Exit Criteria:

- Interop tests pass across supported device matrix.
- Performance / battery within defined budget.
- Channel creation with custom CCCData works end-to-end.
- Confirm message sequence tracking survives connection drops and app restart
  (live device testing against relay server).
- Edge-case testing with real relay: out-of-order delivery, duplicate messages.


Phase 4 – Native Crypto Provider (wolfSSL FFI + Capability Matrix)
------------------------------------------------------------------

Objectives:

- Add native provider to unlock full target primitive set and stronger
  cross-platform guarantees.
- Enable multi-provider diversity (user can mix wolfSSL + BoringSSL +
  libsodium in the same channel per CCCData configuration).

Deliverables:

- ``dart:ffi`` bridge package (workspace local module):

  - Platform builds: iOS, macOS, Android, Linux, Windows.
  - Deterministic API surface for AEAD / KDF / KEM.
  - Secure memory handling and zeroization APIs.
  - Runtime self-test and capability reporting.

- Provider implementations:

  - ``CryptoWolfSsl`` – preferred when capabilities available.
  - ``CryptoCcc`` (``cryptography`` package) – fallback / transitional.
  - Additional provider scaffolds: ``CryptoBoringssl``, ``CryptoLibsodium``.

- ``CccProviderCatalog`` populated with real capability metadata:

  - ``available``: runtime/provider readiness per platform.
  - ``deterministicIo``: identical I/O contract flag for safe cross-provider fallback.
  - ``efficiencyScore`` / ``reliabilityScore``: populated from benchmark suite
    (``normalize(throughputMBps / latencyMs)`` , ``normalize((1 - errorRate) * 100)``).

- Initial PQ-ready integration:

  - ML-KEM path stubs wired to key agreement flow.

Exit Criteria:

- Provider conformance tests pass identical test vectors across providers.
- Crash-safe fallback path works when native backend unavailable.
- At least two providers pass full AEAD + KDF test vector suite.


Phase 5 – Ultra Secret Mode (Triple-Compound Ratchet)
------------------------------------------------------

Objectives:

- Implement the Hydra Apocalypse Ratchet Ultra Mode as specified in
  ``encryption_implementation_ultra-ccc.rst``.
- Deliver Layers A/B/C with controlled rollout and strict guardrails.

Deliverables:

- **CCCData Ultra-specific extensions** (per Ultra-CCC spec):

  - ``cascadeLength`` (16–24, default 20).
  - ``cascadePoolSize`` (48–64, default 56).
  - ``cascadeOrdering`` (``'strongest_first'``, ``'random'``, ``'user_defined'``).
  - ``cascadeReKeyAfter`` (re-key inner root after cascade, default true).
  - ``sequenceRatchetStrength`` (bits for permutation seed, default 256).

- **Layer A – Inner PQ Hybrid Ratchet**:

  - Hybrid KEM: X448 + ML-KEM-1024 + Classic McEliece profile.
  - Inner AEAD stack: AES-GCM + ChaCha20-Poly1305 + Ascon (round-robin from ``aeadConfigs``).
  - Aggressive ratchet cadence: every 20–50 messages.

- **Layer B – Massive Secret Cascade**:

  - Build cascade pool: 48–64 unique ``(provider, algorithm)`` pairs from
    all ``enabledProviders`` across symmetric, AEAD, PQ-KEM, PQ-signature, hash categories.
  - Per-group secret permutation: select 16–24 layers from pool.
  - Per-layer key derivation:

    .. code-block:: text

       layer_key_i = HKDF-Expand(
           prk = current_root_key,
           info = "cascade-layer-" || group_id || sequence_index_i || epoch
       )

  - ``cascadeEncrypt()`` / ``cascadeDecrypt()`` dispatcher.

- **Layer C – Sequence Ratchet**:

  - Per-message sequence seed mutation (deterministic, never sent on wire):

    .. code-block:: text

       seq_seed = KMAC256(base_key, "seq-seed" || group_id || sender_counter)
       cascade_sequence = deterministicPermutation(seq_seed, pool_size, length)

  - Fisher-Yates shuffle with ChaCha20-seeded CSPRNG.
  - Optional inner root re-key after cascade: ``KMAC256(cascade_ct + old_root)``.

- **UltraRatchet** class with full cascade pool builder + deterministic permutation.

- Ultra Mode message flow:

  1. Load CCCData + build cascade pool.
  2. Advance inner ratchet → ``base_message_key`` + ``seqSeed``.
  3. Generate secret cascade sequence (16–24 layers).
  4. Pad plaintext (``blockSize`` boundary + ``minPaddingBytes`` random from KDF).
  5. Inner AEAD round-robin on padded plaintext → ``innerCt``.
  6. Cascade encrypt ``innerCt`` → ``cascadeCt``.
  7. Optional inner root re-key.
  8. Outer AEAD on ``cascadeCt`` → ``finalData``.
  9. Build ``RelayMessage`` → send via gRPC.

- UI/UX:

  - Ultra toggle in channel creation + advanced cascade settings tabs.
  - Battery/performance warning indicators.
  - Security mode clarity (lock icon / visual differentiation).

Exit Criteria:

- Fuzzing + adversarial test suite for cascade dispatcher / sequence engine.
- Regression suite validates decrypt reliability under reordering / loss.
- 4-layer cascade tested first, then scaled to full 20-layer.
- Performance benchmarking on real devices with battery impact documented.


Phase 6 – Encrypted Channel Blob + Invite Crypto
-------------------------------------------------

Objectives:

- Secure channel sharing via a single encrypted blob containing all crypto state.
- Eliminate any plaintext crypto metadata in invite flow.

Deliverables:

- Serialize entire ``CCCData`` + ``groupMasterSeed`` (512-bit) + initial ratchet
  states into a single encrypted blob.
- Encrypt blob under a strong symmetric key derived from invite secret.
- Invite link contains only the encrypted blob (under recipient's public key).
- Recipient imports → verifies ``groupId`` → stores in Hive → both devices have
  identical crypto config.
- Signature algorithm for blob integrity verification.

Exit Criteria:

- Invite round-trip works across all platforms.
- Blob tampering detected and rejected.
- No crypto metadata leaked outside the encrypted blob.


Phase 7 – Verification, Audit, and Deployment Hardening
--------------------------------------------------------

Objectives:

- Reduce implementation-risk surface and prepare for external review.

Deliverables:

- Differential fuzzing of encrypt/decrypt and ratchet transitions.
- Property-based tests (no key/nonce reuse, deterministic state transitions).
- Independent code review checklist + cryptographic design review packet.
- Release gates tied to security metrics and failure budgets.
- Performance/battery profiling for Normal vs Ultra modes.
- Zeroization verification (sensitive key material cleared from memory).

Exit Criteria:

- External audit report with no critical findings.
- All property-based invariants hold under fuzz testing.
- Release criteria met for target platforms.



CCC Provider-Chain Model
========================

CCC is the channel-level crypto plan and state, not a single crypto provider.

- Each channel stores CCC data (inside ``ChannelData.ccc``).
- CCC derives one-or-more providers for the channel plan (e.g.
  ``cryptography``, ``wolfssl``, ``openssl``, ``boringssl``).
- Each provider declares which ciphers it contributes.
- The channel profile flattens this provider chain into a concrete cipher
  route for execution.


Execution Modes
---------------
- ``strict``:

  - Follows exact provider order declared by the channel CCC plan.
  - No fallback allowed.

- ``efficient``:

  - Prefers best-known efficient provider route from configured providers.
  - Fallback allowed when equivalent deterministic cipher I/O exists.

- ``auto``:

  - Dynamically picks route based on provider capability metadata.
  - Prefers currently available providers first.
  - Fallback allowed when equivalent deterministic cipher I/O exists.


Fallback Policy
---------------
- Allowed only in ``efficient`` and ``auto`` modes.
- Disabled in ``strict`` mode.
- Rule: equivalent ciphers (e.g. AES-GCM) must preserve identical input/output
  contract across providers to permit fallback.


Capability Metadata (``CccCipherCapability``)
---------------------------------------------
Per-provider/per-cipher metadata used by route planning:

- ``available``: runtime/provider readiness flag.
- ``deterministicIo``: identical I/O contract across providers (required for fallback).
- ``efficiencyScore`` (0–100): performance/cost ranking (``efficient`` mode primary input).
- ``reliabilityScore`` (0–100): stability/trust ranking (tie-break input).

Scores are placeholder (50) today. Benchmark suite will populate real values.



Implementation Notes and Constraints
=====================================

- Preserve current architecture: UI isolate remains responsive; crypto/network/storage
  stay on background isolates (``worker_manager``).
- Keep relay protocol versioned for crypto profile negotiation and migration.
- ``RelayMessage.data`` carries all E2EE content (timestamp, message JSON, padding,
  rekey payloads). Wire fields ``options`` and ``server_seq`` kept for backwards
  compatibility (will be removed later).
- Avoid hard dependency lock-in: provider abstraction first, library choice second.
- Avoid introducing Ultra-mode complexity before Normal mode exits Phase 3 criteria.
- All CCCData fields are user-editable at channel creation (defaults pre-selected).
- ``groupMasterSeed`` (512-bit) is generated per channel and never sent in plaintext.



Pros / Cons
============

Pros
----
- Strong hedge against single-primitive failure.
- Per-group / per-message mutation increases attacker cost dramatically.
- FS/PCS path preserved by ratchet-first implementation.
- Ephemeral relay architecture aligns with larger ciphertext overhead.
- User cryptographic sovereignty – no server/developer override.
- Modular provider system allows mixing libraries for maximum implementation diversity.

Cons / Risks
------------
- CPU/battery overhead increases significantly in Ultra mode.
- Multi-library/FFI surface increases audit complexity.
- Logic bugs in ratchet/cascade orchestration are a principal risk.
- Diminishing returns beyond roughly 20–24 cascade layers.
- CCCData complexity requires careful UI design to avoid user confusion.



Conclusion
==========

Phase 0 is complete: the provider abstraction boundary, isolate-backed crypto
pipeline, channel-scoped profiles, and baseline security tests are all in place.

Phase 1 is near completion: deterministic key schedule, AEAD associated-data
binding, and unified message + attachment crypto context are integrated and
tested. End-to-end relay-flow verification is the remaining gate.

The path forward:

1. Close Phase 1 with relay-flow E2E verification.
2. Phase 2: Double Ratchet for real forward secrecy (``NormalRatchet`` class).
3. Phase 3: Full Normal-mode target parity (hybrid KEM, Ascon, CCCData UI — pure-Dart providers).
4. Phase 4: wolfSSL FFI for native primitives + multi-provider diversity.
5. Phase 5: Ultra Secret mode with triple-compound ratchet.
6. Phase 6: Encrypted channel blob for secure invite sharing.
7. Phase 7: Audit, fuzzing, and deployment hardening.