@adapt-toolkit/mufl 0.10.2 → 0.10.4

package/meta/meta.mm

@@ -2496,8 +2496,20 @@ library meta {
         names_root "::_crypto_verify_hash_signature" -> function [hash_code,crypto_signature,publickey_sign] truenil. 
         names_root "::_crypto_encrypt_message" -> function [secretkey_encrypt,publickey_encrypt,bin] crypto_message. 
         names_root "::_crypto_decrypt_message" -> function [secretkey_encrypt,publickey_encrypt,crypto_message] bin.
-        names_root "::_crypto_get_key_id" -> function [ crypto ] bin. 
-        names_root "::_crypto_get_key_id_target" -> function [ crypto_message ] bin. 
+        names_root "::_crypto_get_key_id" -> function [ crypto ] bin.
+        names_root "::_crypto_get_key_id_target" -> function [ crypto_message ] bin.
+        // adapt-e2e-core (Olm / X3DH + Double-Ratchet) engine primitives (domain_e2e).
+        // All pickle-in/pickle-out; the trailing bin is the 32-byte pickle_key.
+        names_root "::_e2e_account_create" -> function [bin] bin.
+        names_root "::_e2e_account_gen_otks" -> function [bin, int, bin] bin.
+        names_root "::_e2e_account_gen_fallback" -> function [bin, bin] bin.
+        names_root "::_e2e_account_bundle" -> function [bin, bin] bin.
+        names_root "::_e2e_session_outbound" -> function [bin, bin, bin, bin] (record::type ($session->bin, $account->bin)).
+        names_root "::_e2e_session_inbound" -> function [bin, bin, bin, bin] (record::type ($session->bin, $account->bin, $plaintext->bin)).
+        names_root "::_e2e_encrypt" -> function [bin, bin, bin] (record::type ($msg->bin, $msg_type->int, $session->bin)).
+        names_root "::_e2e_decrypt" -> function [bin, int, bin, bin] (record::type ($plaintext->bin, $session->bin)).
+        names_root "::_e2e_session_id" -> function [bin, bin] bin.
+        names_root "::_e2e_matches_inbound" -> function [bin, bin, bin] int.
         names_root "::_construct_blinded_dictionary" -> functor::make_any_x_ret_blinded_0 (immutable::set (immutable::array basics::any) ). 
         names_root "::_construct_blinded_dictionary_custom" -> functor::make_any_x_y_ret_blinded_0 (immutable::set (immutable::array basics::any) ) (immutable::type str any).
         names_root "::_construct_blinded_with_absence" -> functor::make_any_x_y_ret_blinded_0 (immutable::set (immutable::array basics::any) ) (immutable::set (immutable::array basics::any) ).

package/mufl_stdlib/config.mufl

@@ -19,6 +19,7 @@ config script {
                 $key_storage_api->#"cryptography/key_storage_api.mm",
                 $key_storage->#"cryptography/key_storage.mm",
                 $key_utils->#"cryptography/key_utils.mm",
+                $e2e->#"cryptography/e2e.mm",
                 $registration_proof->#"cryptography/registration_proof.mm",
                 $attestation_document->#"cryptography/attestation/attestation_document.mm",
                 $container_associated_data->#"cryptography/attestation/container_associated_data.mm",
@@ -63,6 +64,7 @@ config script {
                 $key_storage_api->#"cryptography/key_storage_api.mm",
                 $key_storage->#"cryptography/key_storage.mm",
                 $key_utils->#"cryptography/key_utils.mm",
+                $e2e->#"cryptography/e2e.mm",
                 $registration_proof->#"cryptography/registration_proof.mm",
                 $attestation_document->#"cryptography/attestation/attestation_document.mm",
                 $container_associated_data->#"cryptography/attestation/container_associated_data.mm",

package/mufl_stdlib/cryptography/address_document.mm

@@ -23,7 +23,7 @@ and address document is a record of keys that are attested to belong to a certai
 
 */ 
 
-library address_document loads libraries address_document_types, key_storage, key_utils, transaction_queue, current_transaction_info uses transactions
+library address_document loads libraries address_document_types, key_storage, key_utils, transaction_queue, current_transaction_info, e2e uses transactions
 {
     using key_utils. 
     using address_document_types.
@@ -43,11 +43,11 @@ library address_document loads libraries address_document_types, key_storage, ke
     */ 
 
     hidden { 
-        m_current_version IS int = 1. 
-        m_authorizing_containers IS t_container_id(,) = (,). 
+        m_current_version IS int = 2.   // AD-v2: identity embeds the E2E prekey bundle ($e2e_bundle)
+        m_authorizing_containers IS t_container_id(,) = (,).
         m_ad_signatures IS (t_container_id ->> crypto_signature) = (,).
-        m_max_allowed_number_of_authorizations = 10. 
-        m_valid_versions = (1,). 
+        m_max_allowed_number_of_authorizations = 10.
+        m_valid_versions = (1, 2).   // accept v1 (no bundle) and v2 (bundle) peers — dual-support
         m_my_address_document IS t_address_document+ = NIL. 
     }
 
@@ -146,9 +146,18 @@ library address_document loads libraries address_document_types, key_storage, ke
 
     produce_my_address_document = fn (_) -> t_address_document
     {
-        my_identity = key_storage::get_my_identity(). 
-        signatures IS crypto_signature(,) = (,). 
-        hash = _value_id my_identity. 
+        base_identity = key_storage::get_my_identity().
+        // AD-v2: embed our E2E prekey bundle into the identity so peers can open outbound
+        // sessions to us and the far-side decode hook can read our identity key. Rebuild the
+        // record explicitly (no in-place mutation) and compute the hash AFTER embedding, so
+        // the self-signature — and every authorizing-container signature over _value_id
+        // identity — commits to the bundle (belt-and-suspenders with each per-key $sig).
+        my_identity = ( $key_list     -> (base_identity $key_list),
+                        $default_keys -> (base_identity $default_keys),
+                        $container_id -> (base_identity $container_id),
+                        $e2e_bundle   -> e2e::my_public_bundle() ).
+        signatures IS crypto_signature(,) = (,).
+        hash = _value_id my_identity.
 
         sc my_identity $key_list -- (key -> ) ?? key_get_function key == $SIGN { 
             sig = key_storage::sign hash (_crypto_get_key_id key). 

package/mufl_stdlib/cryptography/address_document_types.mm

@@ -1,16 +1,41 @@
 library address_document_types loads library key_utils
 {
     using key_utils.
-    metadef t_address_document: 
-    ( 
+
+    // AD-v2 E2E prekey bundle (double-ratchet / Olm handshake material), published inside
+    // the container identity so a peer can open an outbound session to us and so the
+    // decode-level receive hook can read the sender's identity key. adapt OWNS this type;
+    // the ours-mufl-core companion registers it in a2a_versions (class-B versioned, $pv
+    // discriminator + try_narrow). Each prekey carries a host Ed25519 signature over the
+    // key bytes — belt-and-suspenders alongside the AD root signature that already binds
+    // the whole identity (including this bundle).
+    //
+    // v1 posture (empty one-time keys): the underlying engine (vodozemac) exposes an
+    // identity keypair + a reusable *fallback* key + one-time keys — there is NO distinct
+    // signed prekey. So v1 publishes $fallback (the establishment prekey) with an EMPTY
+    // $one_time_keys list, and leaves $signed_prekey NIL. The field is kept optional for
+    // forward-compat (a real rotated SPK can be added later with no re-shape).
+    metadef t_e2e_prekey: ( $id -> int, $key -> bin, $sig -> crypto_signature ).
+    metadef t_e2e_bundle:
+    (
+        $ik_curve      -> bin,             // Curve25519 identity key (the sender_ik peers establish against)
+        $ik_ed         -> bin,             // Ed25519 identity key
+        $signed_prekey -> t_e2e_prekey+,   // NIL under empty-OTK v1 (no distinct SPK in the engine)
+        $one_time_keys -> t_e2e_prekey[],  // EMPTY [] in v1 (one-time-key reuse impossible)
+        $fallback      -> t_e2e_prekey     // reusable establishment prekey, host-signed
+    ).
+
+    metadef t_address_document:
+    (
         $version->int, // version of the address document
         $identity -> t_container_identity: // specifies the identity of the container
         (
             $key_list->t_publickey(,), // list of keys active with this container
             $default_keys->t_function->>t_key_id, // exactly two keys, one for signing, one for encryption, that are the default keys for this container
-            $container_id->t_container_id // id of the container
-            /* $code_id->hash_code */ 
-        ), 
+            $container_id->t_container_id, // id of the container
+            $e2e_bundle->t_e2e_bundle+ // AD-v2: E2E double-ratchet prekey bundle (NIL for v1 identities)
+            /* $code_id->hash_code */
+        ),
         $authorizations -> crypto_signature(,)
     ).
 }

package/mufl_stdlib/cryptography/e2e.mm

@@ -0,0 +1,304 @@
+/*
+** e2e — the end-to-end (Double-Ratchet / Olm) encryption library.
+**
+** Wraps the domain_e2e engine primitives (_e2e_*, over the adapt-e2e-core C-ABI)
+** behind ergonomic functions that return a CLEAN VALUE or a TYPED ERROR — a caller
+** never sees a raw crate return code. The recoverable failures (a tampered or
+** wrong-session ciphertext, an exhausted one-time key, a corrupt inbound pickle)
+** arrive from the primitives as PROVISIONAL aborts carrying a stable "e2e:*" token;
+** we catch them here and fold them into an `e2e_result`. Fatal faults (a
+** length/version/seed contract breach, a crate-internal error or panic) stay
+** provisional-uncatchable and abort the transaction — they are never returned as data.
+**
+** This module is the STATELESS transform core (pickle-in / pickle-out): every fn
+** takes the opaque state blob(s) and returns the new one(s). The adapt-owned,
+** packet-state SEND/RECEIVE facade (single Olm-session owner; encrypt_to / the
+** __t_wrapper decode-receive) is built on top of these transforms.
+**
+** pickle_key is derived INTERNALLY from this packet's root SIGN secret — never a
+** caller concern, never persisted, never exported.
+*/
+library e2e
+loads libraries key_storage, address_document_types
+{
+    using key_storage.
+    using address_document_types.
+
+    // A typed, caller-facing error. $code is one of the stable strings below;
+    // $detail carries the underlying engine text for logs (never parsed by callers).
+    //   "no_session"       — a normal (olm_type=1) message but no session for the sender
+    //   "tampered"         — ciphertext failed authentication (flipped bits / wrong key)
+    //   "session_mismatch" — a pre-key message for a different session than we hold
+    //   "otk_exhausted"    — the peer's one-time key was already consumed
+    //   "internal"         — an unexpected provisional token (should-never-happen)
+    // (A malformed/corrupt pickle is NOT recoverable — it aborts the tx fatally, since it
+    //  can indicate local state corruption, not just a bad inbound message. See e2e_core.cpp.)
+    metadef e2e_error: ( $code -> str, $detail -> str ).
+
+    // The public prekey material a peer needs to open an outbound session to us is the
+    // AD-v2 t_e2e_bundle (address_document_types) — identity keys + a host-signed fallback
+    // prekey, empty one-time-key list under v1. A peer establishes via $fallback $key.
+
+    // The unified inbound result. On $ok=TRUE, $plaintext + $session are present, and
+    // $account is present ONLY on the establish path (a pre-key message rotates the
+    // account by consuming a prekey) — a normal-message decrypt leaves $account NIL, so
+    // the caller must overwrite its stored account ONLY when this field is non-NIL.
+    // On $ok=FALSE, $error is present and the message should be DROPPED (session lives).
+    metadef e2e_result:
+    (
+        $ok        -> bool,
+        $plaintext -> bin+,
+        $session   -> bin+,
+        $account   -> bin+,
+        $error     -> e2e_error+
+    ).
+
+    hidden
+    {
+        // The 32-byte AEAD pickle key that seals every account/session blob. Derived
+        // ONCE per boot from the packet's stable root SIGN secret (survives key roll /
+        // reseed) with domain separation, then memoised. _value_id yields a HashCode;
+        // _hash_code_to_binary lowers it to the 32-byte binary the primitives require.
+        // NEVER persisted, NEVER exported — re-derived from the identity on each boot.
+        m_pickle_key IS bin+ = NIL.
+
+        fn pickle_key (_) -> bin
+        {
+            if m_pickle_key == NIL
+            {
+                secret = key_storage::export_identity_signing_secret().
+                m_pickle_key -> _hash_code_to_binary
+                                    (_value_id ($purpose -> "adapt/e2e/pickle/v1", $seed -> secret)).
+            }
+            return m_pickle_key as bin.   // narrow bin+ -> bin (guaranteed set above)
+        }
+
+        // Map a caught provisional token (a string that CONTAINS one of the primitives'
+        // "e2e:*" markers, wrapped in the "EVAL_ERROR: " prefix + best-effort frame
+        // trace) to a typed error. Substring match is robust to that wrapping.
+        fn has_token (haystack: str, needle: str) -> bool
+        {
+            return (_str_find haystack needle 0) >= 0.
+        }
+
+        fn map_error (err: str+) -> e2e_error
+        {
+            text = err as str.           // the caught message (guaranteed non-NIL: success paths RETURN)
+            if has_token text "e2e:tampered"         { return ( $code -> "tampered",         $detail -> text ). }
+            if has_token text "e2e:session_mismatch" { return ( $code -> "session_mismatch", $detail -> text ). }
+            if has_token text "e2e:otk_exhausted"    { return ( $code -> "otk_exhausted",    $detail -> text ). }
+            // A provisional abort with no known e2e marker should be impossible (only the
+            // e2e primitives raise provisionals inside decrypt's body). Surface it as
+            // "internal" WITH the full text, so it is typed but never silently lost.
+            return ( $code -> "internal", $detail -> text ).
+        }
+    }
+
+    // Create a fresh identity account: identity keys + a reusable fallback key, and
+    // (empty-OTK v1 posture) NO one-time keys — so a pre-key handshake rests on the
+    // reusable fallback key. This makes one-time-key reuse *impossible* (none are
+    // published), but the tradeoff is real: initial-message forward secrecy now rests
+    // on the multi-use fallback rather than single-use one-time keys, so it is WEAKER
+    // for the first message(s) until the Double Ratchet advances. Steady-state FS/PCS
+    // after the first round-trip is unaffected. (See /tmp/e2e-otk-options.md.) The app
+    // persists the returned blob.
+    fn create_account (_) -> bin
+    {
+        a = _e2e_account_create (pickle_key()).
+        return _e2e_account_gen_fallback a (pickle_key()).
+    }
+
+    // Our published AD-v2 prekey bundle, for a peer to open an outbound session to us and
+    // for the decode-level receive hook on the far side to read our identity key. Built
+    // FRESH from the account's raw public bundle (never mutates the immutable engine blob),
+    // with a host Ed25519 signature over the fallback key bytes (belt-and-suspenders with
+    // the AD root signature). Under empty-OTK v1 there are no one-time keys and no distinct
+    // signed prekey, so a peer establishes via $fallback $key.
+    fn my_bundle (account: bin) -> t_e2e_bundle
+    {
+        b = _e2e_account_bundle account (pickle_key()).
+        // Raw bundle layout (crate src/mgmt/bundle.rs):
+        //   ik_curve[0:32] ik_ed[32:64] fb_count(u8)@64 fb_id(u32 LE)[65:69] fb_key[69:101]
+        //   otk_count(u32 LE)@101 ...   (empty-OTK v1 => otk_count 0, no otk entries).
+        // Offset 69 is the fallback key ONLY when a fallback is present (fb_count@64 == 1).
+        // Guard it: without this, an account with no fallback would slice the wrong bytes
+        // (or overrun). Accounts made by create_account always carry one, but my_bundle is
+        // public and must not emit a garbage "fallback" key for an arbitrary account blob.
+        abort "e2e::my_bundle: account has no fallback key (empty-OTK v1 requires one)" WHEN (b 64) != 1.
+        fb_key = _binary_slice b 69 32.
+        return
+        (
+            $ik_curve      -> (_binary_slice b 0 32),
+            $ik_ed         -> (_binary_slice b 32 32),
+            $signed_prekey -> NIL,                    // v1: engine exposes no distinct signed prekey
+            $one_time_keys -> [],                     // empty-OTK v1 (one-time-key reuse impossible)
+            // vodozemac fallback key-id is not surfaced in v1 ($id -> 0): the receiver
+            // establishes from material inside the pre-key ciphertext and the sender uses
+            // only the key bytes, so the id is functionally unused here.
+            $fallback      -> ( $id  -> 0,
+                                $key -> fb_key,
+                                $sig -> (key_storage::default_sign (_value_id fb_key)) )
+        ).
+    }
+
+    // Establish an OUTBOUND session to a peer from the peer's published AD-v2 bundle (picks
+    // the fallback prekey under empty-OTK v1). Returns the new session and the
+    // (possibly rotated) account — the app persists BOTH.
+    fn create_outbound_session (account: bin, peer: t_e2e_bundle) -> ( $session -> bin, $account -> bin )
+    {
+        r = _e2e_session_outbound account (peer $ik_curve) (peer $fallback $key) (pickle_key()).
+        return ( $session -> r $session, $account -> r $account ).
+    }
+
+    // Encrypt a plaintext on an established session. Returns the ciphertext, its
+    // olm_type (0=pre-key until the peer replies, 1=normal thereafter), and the
+    // advanced session — the app persists $session (the ratchet step).
+    fn encrypt (session: bin, plaintext: bin) -> ( $ciphertext -> bin, $olm_type -> int, $session -> bin )
+    {
+        r = _e2e_encrypt session plaintext (pickle_key()).
+        return ( $ciphertext -> r $msg, $olm_type -> r $msg_type, $session -> r $session ).
+    }
+
+    // The ONE unified inbound call. The library decides establish-vs-decrypt from
+    // olm_type + session presence and maps every recoverable failure to a typed
+    // e2e_result — the caller NEVER branches on olm_type or handles a return code.
+    //   olm_type=0            -> (re)establish an inbound session from the pre-key message;
+    //                            yields plaintext + new session + rotated account.
+    //   olm_type=1, session   -> decrypt on the existing session; yields plaintext + session.
+    //   olm_type=1, NO session-> typed "no_session" (drop; the sender's pre-key repeat self-heals).
+    fn decrypt (account: bin, session: bin+, sender_ik: bin, olm_type: int, ciphertext: bin) -> e2e_result
+    {
+        if olm_type == 1 && session == NIL
+        {
+            return ( $ok -> FALSE, $plaintext -> NIL, $session -> NIL, $account -> NIL,
+                     $error -> ( $code -> "no_session",
+                                 $detail -> "normal (olm_type=1) message but no established session for sender" ) ).
+        }
+
+        WHEN provisional abort err
+        {
+            if olm_type == 0
+            {
+                r = _e2e_session_inbound account sender_ik ciphertext (pickle_key()).
+                return ( $ok -> TRUE, $plaintext -> r $plaintext, $session -> r $session,
+                         $account -> r $account, $error -> NIL ).
+            }
+            r = _e2e_decrypt (session as bin) 1 ciphertext (pickle_key()).
+            return ( $ok -> TRUE, $plaintext -> r $plaintext, $session -> r $session,
+                     $account -> NIL, $error -> NIL ).
+        }
+        // Reached ONLY when the body provisional-aborted (both success branches RETURN):
+        // `err` holds the token text → typed drop, the session survives.
+        return ( $ok -> FALSE, $plaintext -> NIL, $session -> NIL, $account -> NIL,
+                 $error -> (map_error err) ).
+    }
+
+    // Idempotent re-delivery check: TRUE iff `session` is the channel that this pre-key
+    // ciphertext would establish (so a re-sent handshake can be recognised and dropped
+    // by the stateful facade before re-establishing). Pure read.
+    fn session_matches (session: bin, ciphertext: bin) -> bool
+    {
+        return (_e2e_matches_inbound session ciphertext (pickle_key())) == 1.
+    }
+
+    // The session's stable 32-byte id (shared by both ends of a channel). Pure read.
+    fn session_id (session: bin) -> bin
+    {
+        return _e2e_session_id session (pickle_key()).
+    }
+
+    // =====================================================================================
+    // STATEFUL FACADE — adapt is the SINGLE owner of the Olm account + per-peer sessions.
+    // Because RECEIVE happens transparently at the __t_wrapper decode seam (adapt-owned
+    // packet-state, committed in the guaranteed-mutating decode tx), SEND must be adapt-owned
+    // too — one Olm session cannot have two owners or the ratchet desyncs. So the ours-mcp
+    // layer never holds session state: it calls encrypt_to to send and the decode hook calls
+    // decrypt_and_commit to receive. Both mutate this library's packet-state.
+    // =====================================================================================
+
+    // The E2E message envelope (opaque ciphertext + routing stamp) and its outer
+    // sender-authentication signature. NEW additive variant — the existing plain/signed/
+    // encrypted envelopes are untouched. The $e2e_envelope field is the decode MARKER.
+    metadef t_e2e_envelope: ( $session_id -> bin, $olm_type -> int, $ciphertext -> bin, $pv -> int ).
+    metadef e2e_signed_message: ( $e2e_envelope -> t_e2e_envelope, $emsignature -> crypto_signature ).
+
+    hidden
+    {
+        m_account  IS bin+ = NIL.               // this packet's Olm account (lazy first-use)
+        m_sessions IS (global_id ->> bin) = (,). // per-peer session pickle, keyed by contact id
+        m_wire_pv  = 8.                          // wire dialect stamp ($pv) for v1 (matches wire8)
+
+        fn account (_) -> bin
+        {
+            if m_account == NIL { m_account -> create_account(). }
+            return m_account as bin.
+        }
+    }
+
+    // Our own published AD-v2 prekey bundle (from our lazily-created account) — embedded in
+    // our address document ($identity.$e2e_bundle) so a peer can open an outbound session to
+    // us and the far-side decode hook can read our identity key.
+    fn my_public_bundle (_) -> t_e2e_bundle
+    {
+        return my_bundle (account()).
+    }
+
+    // SEND: encrypt tx_body (already serialized to bin by the caller) to a peer, lazily
+    // establishing the outbound session from the peer's bundle on first send, ADVANCING +
+    // COMMITTING our session, and returning the fully-built, sender-signed envelope ready to
+    // relay. ours-mcp send collapses to: action::send cid (e2e::encrypt_to cid body peer).
+    fn encrypt_to (cid: global_id, plaintext: bin, peer: t_e2e_bundle) -> e2e_signed_message
+    {
+        if (m_sessions cid) == NIL
+        {
+            est = create_outbound_session (account()) peer.
+            m_account   -> est $account.
+            m_sessions cid -> est $session.
+        }
+        e = encrypt ((m_sessions cid) as bin) plaintext.
+        m_sessions cid -> e $session.           // commit the ratchet advance
+        env = ( $session_id -> (session_id (e $session)), $olm_type -> (e $olm_type),
+                $ciphertext -> (e $ciphertext), $pv -> m_wire_pv ).
+        // S1: bind the SENDER ($from = us) and RECIPIENT ($to = cid) into the emsig pre-image,
+        // alongside the wire-versioned $env (which carries $pv). This authenticates the routing,
+        // so a captured envelope cannot be reflected to a third party or re-targeted. The envelope
+        // STRUCTURE is unchanged (adapt signs here; the adapt decode hook verifies over the same
+        // reconstructed context) — no companion/wire-corpus change.
+        sig_context = ( $from -> _get_container_id(), $to -> cid, $envelope -> env ).
+        return ( $e2e_envelope -> env,
+                 $emsignature -> (key_storage::default_sign (_value_id sig_context)) ).
+    }
+
+    // The supported wire dialect stamp ($pv) — the receiver validates an inbound envelope's $pv
+    // against this to reject an unknown/downgraded dialect (S2). Pure read.
+    fn wire_pv (_) -> int { return m_wire_pv. }
+
+    // RECEIVE: decrypt an inbound envelope for a known sender and COMMIT the advanced session
+    // (and, on the establish path only, the rotated account). Returns the typed e2e_result.
+    // The caller (the __t_wrapper decode hook) authenticates $emsignature FIRST and supplies
+    // the sender's e2e identity key (read from the same AD identity it origin-binds against).
+    fn decrypt_and_commit (from_cid: global_id, sender_ik: bin, olm_type: int, ciphertext: bin) -> e2e_result
+    {
+        // Pre-key (establish) REPLAY guard. v1 publishes a MULTI-USE fallback key (empty OTK
+        // list), so a replayed olm_type=0 pre-key would re-establish successfully — re-executing
+        // the inner transaction AND overwriting the live (possibly advanced) session. If we
+        // already hold a session for this sender and THIS pre-key is the same handshake that
+        // established it, it is an idempotent re-delivery: drop it recoverably (no re-establish,
+        // no re-deliver, session untouched). session_matches is a pure read on the existing
+        // session; a genuine NEW handshake (different ephemeral) does not match and re-establishes.
+        existing IS bin+ = m_sessions from_cid.
+        if olm_type == 0 && existing != NIL && (session_matches (existing as bin) ciphertext)
+        {
+            return ( $ok -> FALSE, $plaintext -> NIL, $session -> NIL, $account -> NIL,
+                     $error -> ( $code -> "replayed_handshake",
+                                 $detail -> "pre-key re-delivers an already-established session" ) ).
+        }
+        r = decrypt (account()) (m_sessions from_cid) sender_ik olm_type ciphertext.
+        if r $ok
+        {
+            m_sessions from_cid -> (r $session) as bin.        // commit the ratchet advance
+            if (r $account) != NIL { m_account -> (r $account) as bin. }  // establish path rotates the account
+        }
+        return r.
+    }
+}

package/mufl_stdlib/cryptography/key_storage.mm

@@ -10,7 +10,15 @@ library key_storage loads library key_utils {
         _read_or_abort -> read.
     }
 
-    using key_utils. 
+    // Deserialize untrusted external bytes (a decrypted peer payload) through the injected
+    // D_Code-FILTERED reader — the same defence decrypt_message applies to peer crypto_messages.
+    // Used by the E2E decode hook to turn a decrypted Olm plaintext back into an inner t_trn.
+    read_external = fn (data: bin) -> any
+    {
+        return _read_or_abort data.
+    }
+
+    using key_utils.
     metadef t_keypair_info: 
     (
         $function->t_function, 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adapt-toolkit/mufl",
-  "version": "0.10.2",
+  "version": "0.10.4",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
   "description": "The MUFL toolchain: prebuilt `mufl` (REPL) and `mufl-compile` (compiler) engine binaries plus the MUFL stdlib, meta, and transactions trees they need at run time. Linux x64 only; the binaries are proprietary (AEFL) — see LICENSE and NOTICE.",

package/transactions/__t_wrapper.mm

@@ -3,16 +3,21 @@
 // to create a function that takes a string that contains JSON that encodes the value of that type
 // and performs all the necessary runtime checks.
 
-library __t_wrapper loads libraries transaction, key_storage, transaction_queue, identity_proof_document_types {
+library __t_wrapper loads libraries transaction, key_storage, transaction_queue, identity_proof_document_types, e2e {
 
     metadef t_trn: ($name->str, $targ->any).
-    metadef t_trn_extended: ($trn->t_trn, $is_signed->bool, $is_encrypted->bool).
+    metadef t_trn_extended: ($trn->t_trn, $is_signed->bool, $is_encrypted->bool, $is_e2e->bool+).
     metadef t_trn_message_info: (
         $decoded_envelope -> transaction::envelope::external::decoded_type || t_trn,
         $decoded_message -> t_trn,
         $is_signed -> bool,
         $is_encrypted -> bool,
-        $has_envelope -> bool
+        $has_envelope -> bool,
+        // TRUE only for a decoded E2E (double-ratchet) envelope. The C++ transaction driver
+        // uses it to enforce the reject-readonly-E2E invariant (an E2E tx is never readonly,
+        // so the committing ratchet-advance always seals) and to drop a benign recoverable
+        // failure (empty $name) without poisoning the channel.
+        $is_e2e -> bool+
     ).
 
     hidden {
@@ -25,7 +30,11 @@ library __t_wrapper loads libraries transaction, key_storage, transaction_queue,
             return key_storage::check_signature hash signature.
         }
 
-        check_origin_binding = fn (envelope: any) -> publickey_sign {
+        // Verify the enveloped sender's identity proof commits to $from and returns BOTH the
+        // origin-bound SIGN key (for signature checks) AND the parsed identity — the latter so
+        // the E2E decode hook can read the sender's e2e identity key ($e2e_bundle $ik_curve)
+        // off the SAME origin-bound identity, with no separate peer store.
+        check_origin_binding = fn (envelope: any) -> ( $sign_key -> publickey_sign, $identity -> any ) {
             ip_raw = envelope $ip_document.
             abort "Missing identity document on external message" WHEN ip_raw == NIL.
             ip = ip_raw SAFE(identity_proof_document_types::t_identity_proof_document) abort "Invalid identity proof document" WHEN IS NIL.
@@ -41,10 +50,13 @@ library __t_wrapper loads libraries transaction, key_storage, transaction_queue,
             }
             abort "SIGN key not found in identity key_list" WHEN sign_pub == NIL.
             abort "Origin address does not commit to signing key" WHEN (key_storage::address_of_key sign_pub?) != (envelope $from).
-            return sign_pub?.
+            return ( $sign_key -> sign_pub?, $identity -> identity ).
         }
 
-        decode_message_with_keys = fn (message: any, origin_sign_key: publickey_sign+) -> t_trn_extended {
+        // origin_sign_key / from_cid / sender_ik are the origin-bound sender key, the sender's
+        // container id ($from), and the sender's e2e identity key ($e2e_bundle $ik_curve) — all
+        // NIL for non-enveloped (internal) messages, which never carry $e2e_envelope.
+        decode_message_with_keys = fn (message: any, origin_sign_key: publickey_sign+, from_cid: global_id+, to_cid: global_id+, sender_ik: bin+) -> t_trn_extended {
             if message $encrypted_message {
                 is_ptsignature IS bool = TRUE.
                 signature IS crypto_signature+ = NIL.
@@ -58,12 +70,52 @@ library __t_wrapper loads libraries transaction, key_storage, transaction_queue,
                 decrypted_message = decrypt_message encrypted_message.
                 res = decrypted_message SAFE(t_trn).
                 if is_ptsignature && (check_signature signature? decrypted_message) {
-                    return ($trn -> res, $is_signed -> TRUE, $is_encrypted -> TRUE).
+                    return ($trn -> res, $is_signed -> TRUE, $is_encrypted -> TRUE, $is_e2e -> FALSE).
                 } elif (!is_ptsignature && check_signature signature? encrypted_message) {
-                    return ($trn -> res, $is_signed -> TRUE, $is_encrypted -> TRUE).
+                    return ($trn -> res, $is_signed -> TRUE, $is_encrypted -> TRUE, $is_e2e -> FALSE).
                 } else {
                     abort "Signature verification failed." WHEN TRUE.
-                    return ($trn -> ($name -> "", $targ -> NIL), $is_signed -> FALSE, $is_encrypted -> FALSE).
+                    return ($trn -> ($name -> "", $targ -> NIL), $is_signed -> FALSE, $is_encrypted -> FALSE, $is_e2e -> FALSE).
+                }
+            } elif message $e2e_envelope {
+                // === E2E (double-ratchet) decode hook — transparent decrypt at the decode seam ===
+                // The inner transaction rides as opaque Olm ciphertext; here we authenticate the
+                // sender, decrypt+commit the ratchet in this (guaranteed-mutating) decode tx, and
+                // hand the plaintext inner t_trn back to the driver. $is_e2e=TRUE lets the C++
+                // driver enforce reject-readonly-E2E (post-findTransaction, where the inner tx's
+                // readonly flag is known) and drop a benign failure (empty $name) cleanly.
+                env = message $e2e_envelope.
+                // Outer sender authentication: $emsignature over the SENDER+RECIPIENT+envelope
+                // context (S1) by the SAME SIGN key check_origin_binding tied to $from. E2E is
+                // enveloped-only, so origin_sign_key, $from, $to and the sender's e2e key must all
+                // be present. from_cid/to_cid are the outer envelope's $from/$to.
+                abort "E2E envelope requires an origin-bound sender key" WHEN origin_sign_key == NIL.
+                abort "E2E envelope missing sender container id" WHEN from_cid == NIL.
+                abort "E2E envelope missing recipient container id" WHEN to_cid == NIL.
+                abort "E2E sender published no e2e bundle" WHEN sender_ik == NIL.
+                // S2: reject an unknown/downgraded wire dialect before any decrypt/commit.
+                abort "E2E envelope wire-version mismatch" WHEN ((env $pv) as int) != (e2e::wire_pv()).
+                emsig = (message $emsignature) SAFE(crypto_signature) abort "Missing E2E envelope signature" WHEN IS NIL.
+                // S1: recompute the signed context from the ACTUAL outer $from/$to + envelope, so a
+                // captured envelope cannot be reflected to a third party or re-targeted.
+                sig_context = ( $from -> from_cid?, $to -> to_cid?, $envelope -> env ).
+                abort "E2E envelope signature verification failed"
+                    WHEN (_crypto_verify_hash_signature (_value_id sig_context |) emsig? origin_sign_key?) != TRUE.
+                r = e2e::decrypt_and_commit from_cid? sender_ik? ((env $olm_type) as int) ((env $ciphertext) as bin).
+                if r $ok {
+                    // The plaintext is the peer's inner t_trn serialized with _write. Deserialize
+                    // with the D_Code-FILTERED external reader (untrusted ingress) that key_storage
+                    // owns — the same defence the encrypted_message path relies on.
+                    inner = key_storage::read_external (r $plaintext |).
+                    inner_trn = (inner SAFE(t_trn)) abort "E2E: decrypted payload is not a transaction" WHEN IS NIL.
+                    return ($trn -> inner_trn?, $is_signed -> TRUE, $is_encrypted -> TRUE, $is_e2e -> TRUE).
+                } else {
+                    // Recoverable failure (no_session | tampered | session_mismatch): deliver a
+                    // benign no-op. An empty $name + $is_e2e signals the driver to drop silently
+                    // without poisoning the channel (a failed decrypt commits no state, so the
+                    // session is untouched). $is_signed stays TRUE (the emsig verified) so the
+                    // enveloped-must-be-signed guard below does not abort.
+                    return ($trn -> ($name -> "", $targ -> NIL), $is_signed -> TRUE, $is_encrypted -> TRUE, $is_e2e -> TRUE).
                 }
             } elif message $trn {
                 tn = message $trn.
@@ -73,16 +125,16 @@ library __t_wrapper loads libraries transaction, key_storage, transaction_queue,
                 } else {
                     abort "Signature verification failed for message." WHEN ((check_signature signature? tn) == NIL).
                 }
-                return ($trn -> (tn safe(t_trn)), $is_signed -> TRUE, $is_encrypted -> FALSE).
+                return ($trn -> (tn safe(t_trn)), $is_signed -> TRUE, $is_encrypted -> FALSE, $is_e2e -> FALSE).
             } else {
-                return ($trn -> (message safe(t_trn)), $is_signed -> FALSE, $is_encrypted -> FALSE).
+                return ($trn -> (message safe(t_trn)), $is_signed -> FALSE, $is_encrypted -> FALSE, $is_e2e -> FALSE).
             }
         }
     }
 
     fn decode_message (message: any) -> t_trn_extended
     {
-        return decode_message_with_keys message NIL.
+        return decode_message_with_keys message NIL NIL NIL NIL.
     }
 
     /*
@@ -112,10 +164,19 @@ library __t_wrapper loads libraries transaction, key_storage, transaction_queue,
         has_envelope is bool = FALSE.
         message is any = NIL.
         origin_sign_key IS publickey_sign+ = NIL.
+        from_cid IS global_id+ = NIL.       // the sender's container id ($from), enveloped only
+        to_cid IS global_id+ = NIL.         // the recipient's container id ($to), enveloped only (S1)
+        sender_ik IS bin+ = NIL.            // the sender's e2e identity key, read off the origin-bound identity
 
         // This is the case of external message packed into the transaction envelope
         if envelope $body != NIL {
-            origin_sign_key -> check_origin_binding envelope.
+            check_origin_binding envelope => ($sign_key -> ob_key, $identity -> ob_identity).
+            origin_sign_key -> ob_key.
+            from_cid -> (envelope $from) as global_id.
+            if (envelope $to) { to_cid -> (envelope $to) as global_id. }
+            // AD-v2 peers publish an $e2e_bundle in their identity; a v1 peer has none (and
+            // cannot send E2E). Read the sender's identity key for the E2E establish path.
+            if (ob_identity $e2e_bundle) { sender_ik -> ((ob_identity $e2e_bundle $ik_curve) as bin). }
             message -> envelope $body.
             has_envelope -> TRUE.
         } else {
@@ -123,7 +184,7 @@ library __t_wrapper loads libraries transaction, key_storage, transaction_queue,
             has_envelope -> FALSE.
         }
 
-        decode_message_with_keys message origin_sign_key => ($trn -> decoded_message, $is_signed -> is_signed, $is_encrypted -> is_encrypted).
+        decode_message_with_keys message origin_sign_key from_cid to_cid sender_ik => ($trn -> decoded_message, $is_signed -> is_signed, $is_encrypted -> is_encrypted, $is_e2e -> is_e2e).
 
         abort "Unsigned external message rejected: enveloped messages must be signed." WHEN has_envelope && (!is_signed).
 
@@ -134,7 +195,8 @@ library __t_wrapper loads libraries transaction, key_storage, transaction_queue,
                 $decoded_message -> decoded_message,
                 $is_signed -> is_signed,
                 $is_encrypted -> is_encrypted,
-                $has_envelope -> has_envelope
+                $has_envelope -> has_envelope,
+                $is_e2e -> is_e2e
             ) safe t_trn_message_info.
         } else {
             return (
@@ -142,7 +204,8 @@ library __t_wrapper loads libraries transaction, key_storage, transaction_queue,
                 $decoded_message -> decoded_message,
                 $is_signed -> is_signed,
                 $is_encrypted -> is_encrypted,
-                $has_envelope -> has_envelope
+                $has_envelope -> has_envelope,
+                $is_e2e -> is_e2e
             ) safe t_trn_message_info.
         }
     }

package/transactions/config.mufl

@@ -14,7 +14,8 @@ config script {
                 $key_storage->#"../mufl_stdlib",
                 $transaction_queue->#"../mufl_stdlib",
                 $key_utils->#"../mufl_stdlib",
-                $identity_proof_document_types->#"../mufl_stdlib"
+                $identity_proof_document_types->#"../mufl_stdlib",
+                $e2e->#"../mufl_stdlib"
             ),
             $applications->(,)
         )