@adapt-toolkit/mufl 0.10.4 → 0.10.6

package/mufl_stdlib/cryptography/address_document_types.mm

@@ -33,7 +33,16 @@ library address_document_types loads library key_utils
             $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
-            $e2e_bundle->t_e2e_bundle+ // AD-v2: E2E double-ratchet prekey bundle (NIL for v1 identities)
+            // AD-v2 E2E double-ratchet prekey bundle (NIL for v1). Typed `any+`, NOT the nested
+            // t_e2e_bundle metadef, so a meta _value_id / SAFE-cast of t_address_document does NOT
+            // recursively reduce t_e2e_bundle at EVERY AD op (pin_registrar, verify_identity_bundle,
+            // peer_ads, cluster AD handling — dozens of sites). That nested reduction, summed across a
+            // full daemon packet + the migration core, blew the per-unit meta-fuel ceiling
+            // (meta.mm:2604 via actor.mu pin_registrar). Every read already casts it — e2e.mm
+            // `(identity $e2e_bundle) SAFE(t_e2e_bundle)`, a2a_messaging `(...as any) $e2e_bundle safe
+            // t_e2e_bundle` — so validation is unchanged and the wire/_value_id bytes are identical
+            // (value-hash, type-agnostic). Same pattern as transaction e2e_signed_message $e2e_envelope.
+            $e2e_bundle->any+
             /* $code_id->hash_code */
         ),
         $authorizations -> crypto_signature(,)

package/mufl_stdlib/cryptography/e2e.mm

@@ -227,12 +227,44 @@ loads libraries key_storage, address_document_types
         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)
+        // core 0.9.0 migration (spec §5.5): ONE staged rotation per peer — a FRESH session
+        // established for the bilateral migration commit, held aside so the LIVE session
+        // (m_sessions[cid]) keeps decrypting legacy e2e traffic until commit_rotation promotes
+        // it. Packet-state, NEVER exported (INV-4) — same secrecy class as m_sessions.
+        m_staged   IS (global_id ->> bin) = (,).
+        // Decode-seam migration hook (spec §5.5): "is a migration FSM entry pending for this
+        // cid?" Core (a2a_messaging) registers the real predicate via set_mig_pending_hook at
+        // init; the DEFAULT is FALSE, so with no core wiring the decode seam behaves EXACTLY
+        // as 0.8.0 (an inbound pre-key on a live session self-heals by replacing — the correct
+        // behavior when there is no migration to protect). When TRUE, an inbound pre-key on a
+        // live session STAGES instead of replacing, so the live session survives until the
+        // bilateral commit promotes the staged one. This is the load-bearing distinction that
+        // closes the unilateral-live-session-reset path without breaking pre-key self-heal.
+        m_mig_pending IS (global_id -> bool) = fn (_: global_id) -> bool { return FALSE. }.
 
         fn account (_) -> bin
         {
             if m_account == NIL { m_account -> create_account(). }
             return m_account as bin.
         }
+
+        // The idempotent pre-key re-delivery result (a live- or staged-session replay). No
+        // plaintext, no state change — the session lives; the wrapper drops it (or, for a
+        // staged-session match, routes it to the core replay-commit hook).
+        fn replayed (_) -> e2e_result
+        {
+            return ( $ok -> FALSE, $plaintext -> NIL, $session -> NIL, $account -> NIL,
+                     $error -> ( $code -> "replayed_handshake",
+                                 $detail -> "pre-key re-delivers an already-established session" ) ).
+        }
+    }
+
+    // Core (a2a_messaging) registers the migration-pending predicate here at init so the decode
+    // seam can distinguish a MIGRATION rotation (stage the fresh session) from a self-heal pre-key
+    // (replace, 0.8.0). Idempotent; the default predicate is FALSE (pure 0.8.0 decode behavior).
+    fn set_mig_pending_hook (hook: (global_id -> bool)) -> nil
+    {
+        m_mig_pending -> hook.
     }
 
     // Our own published AD-v2 prekey bundle (from our lazily-created account) — embedded in
@@ -273,26 +305,138 @@ loads libraries key_storage, address_document_types
     // against this to reject an unknown/downgraded dialect (S2). Pure read.
     fn wire_pv (_) -> int { return m_wire_pv. }
 
+    // =====================================================================================
+    // STAGED ROTATION (core 0.9.0 migration, spec §5.5) — additive. The facade above cannot
+    // express a bilateral key rotation: encrypt_to reuses m_sessions[cid] unconditionally and
+    // an inbound pre-key unilaterally replaces the live session. These APIs add a STAGED slot
+    // so a live session is NEVER clobbered without an explicit commit. Exactly-once by
+    // construction: commit_rotation is the SOLE promotion point; a lost staged secret is
+    // abandoned + superseded by a fresh rotation, never re-derived (INV-4 / plan invariant 4).
+    // =====================================================================================
+
+    // MIGRATION SEND (initiator): create a FRESH outbound session to `peer` EVEN WHEN a live
+    // session already exists (deliberately NOT encrypt_to's lazy-establish-if-absent path) and
+    // hold it STAGED. m_sessions[cid] is untouched — it keeps decrypting legacy traffic until
+    // commit_rotation. Returns the fresh session's stable id (the epoch binds to THIS id). The
+    // account may rotate (prekey consumption); that is peer-independent bookkeeping, committed
+    // immediately (validated under empty-OTK v1, plan B gate 2).
+    fn stage_outbound_rotation (cid: global_id, peer: t_e2e_bundle) -> bin
+    {
+        est = create_outbound_session (account()) peer.
+        m_account    -> est $account.
+        m_staged cid -> est $session.
+        return session_id (est $session).
+    }
+
+    // Encrypt on the STAGED session (PRE_KEY until the peer replies on it); the ratchet advance
+    // commits to the STAGED slot ONLY — the live session is never advanced here. Same S1
+    // sender/recipient emsig binding + envelope structure as encrypt_to, so the far-side decode
+    // hook verifies identically; the envelope carries the STAGED session_id.
+    fn encrypt_staged (cid: global_id, plaintext: bin) -> e2e_signed_message
+    {
+        e = encrypt ((m_staged cid) as bin) plaintext.
+        m_staged cid -> e $session.             // commit the ratchet advance on the STAGED slot
+        env = ( $session_id -> (session_id (e $session)), $olm_type -> (e $olm_type),
+                $ciphertext -> (e $ciphertext), $pv -> m_wire_pv ).
+        sig_context = ( $from -> _get_container_id(), $to -> cid, $envelope -> env ).
+        return ( $e2e_envelope -> env,
+                 $emsignature -> (key_storage::default_sign (_value_id sig_context)) ).
+    }
+
+    // MIGRATION inbound (responder): establish an inbound session from a pre-key INTO the STAGED
+    // slot, leaving m_sessions[cid] untouched. Returns the typed e2e_result (its $plaintext is
+    // the inner commit tx for the caller to dispatch). On the establish path the account rotates;
+    // committed immediately (peer-independent). A typed failure ($ok=FALSE) stages nothing.
+    fn stage_inbound_rotation (from_cid: global_id, sender_ik: bin, ciphertext: bin) -> e2e_result
+    {
+        r = decrypt (account()) NIL sender_ik 0 ciphertext.   // olm_type 0 = establish; NIL session = fresh
+        if r $ok
+        {
+            m_staged from_cid -> (r $session) as bin.
+            if (r $account) != NIL { m_account -> (r $account) as bin. }
+        }
+        return r.
+    }
+
+    // Promote the STAGED session to ACTIVE atomically: it replaces the live session and the old
+    // one is DROPPED (the owner's fresh-key requirement). Returns the new session's id, or NIL
+    // if nothing is staged (idempotent — a duplicate/lost-confirm commit is a safe no-op). The
+    // account is already committed. This is the SOLE session-promotion point (plan invariant 4).
+    fn commit_rotation (cid: global_id) -> bin+
+    {
+        st IS bin+ = m_staged cid.
+        if st == NIL { return NIL. }
+        m_sessions cid -> st as bin.
+        delete m_staged cid.
+        return session_id (st as bin).
+    }
+
+    // Drop a staged rotation WITHOUT promoting (a rejected/aborted/superseded migration).
+    // Idempotent. The live session is untouched — legacy transport continues.
+    fn discard_rotation (cid: global_id) -> nil
+    {
+        if (m_staged cid) != NIL { delete m_staged cid. }
+    }
+
+    // Pure reads — the byte-comparable session-id evidence the core FSM gates on (staged for the
+    // commit/confirm equality checks; active as the replayed-commit authentication evidence,
+    // spec §5.5 lost-confirm path). NIL when the respective slot is empty.
+    fn staged_session_id (cid: global_id) -> bin+
+    {
+        s IS bin+ = m_staged cid.
+        if s == NIL { return NIL. }
+        return session_id (s as bin).
+    }
+    fn active_session_id (cid: global_id) -> bin+
+    {
+        s IS bin+ = m_sessions cid.
+        if s == NIL { return NIL. }
+        return session_id (s as bin).
+    }
+
     // 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)
+        staged   IS bin+ = m_staged   from_cid.
+
+        if olm_type == 0
         {
-            return ( $ok -> FALSE, $plaintext -> NIL, $session -> NIL, $account -> NIL,
-                     $error -> ( $code -> "replayed_handshake",
-                                 $detail -> "pre-key re-delivers an already-established session" ) ).
+            // 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-running
+            // the inner tx AND overwriting the (possibly advanced) session. session_matches is a
+            // pure read; a genuine NEW handshake (different ephemeral) does not match.
+            //  (a) matches the LIVE session — idempotent re-delivery, drop recoverably.
+            if existing != NIL && (session_matches (existing as bin) ciphertext)
+            { return replayed(). }
+            //  (b) matches the STAGED session — a redelivered migration COMMIT after we already
+            //      staged it (the lost-confirm case, spec §5.5). The wrapper turns this typed
+            //      error into a re-confirm via core mig_handle_replayed_commit; NO inner
+            //      re-dispatch, NO re-establish. active_session_id is the authenticated evidence.
+            if staged != NIL && (session_matches (staged as bin) ciphertext)
+            { return replayed(). }
+            //  DECODE-SEAM (§5.5, the load-bearing security change): a genuinely NEW pre-key on a
+            //  cid that ALREADY holds a live session, WHILE a migration is pending, STAGES the
+            //  fresh session instead of unilaterally replacing the live one. m_sessions[cid] is
+            //  untouched until commit_rotation promotes the staged session. With NO pending
+            //  migration the hook is FALSE and we fall through to the 0.8.0 path (a live-session
+            //  pre-key self-heals by replacing — correct when there is no migration to protect).
+            if existing != NIL && (m_mig_pending from_cid)
+            { return stage_inbound_rotation from_cid sender_ik ciphertext. }
         }
+        // Normal ratchet (olm_type=1) that decrypts on the STAGED session: the initiator reading
+        // the peer's confirm on the fresh session BEFORE it promotes (decode-seam). Try staged
+        // first; a typed failure (the message was for the live session) falls through below.
+        if olm_type == 1 && staged != NIL
+        {
+            rs = decrypt (account()) staged sender_ik 1 ciphertext.
+            if rs $ok { m_staged from_cid -> (rs $session) as bin.  return rs. }
+        }
+        // Default 0.8.0 path: establish (first-contact / self-heal) or decrypt on the LIVE session,
+        // committing the advance (and, on establish, the rotated account).
         r = decrypt (account()) (m_sessions from_cid) sender_ik olm_type ciphertext.
         if r $ok
         {
@@ -301,4 +445,64 @@ loads libraries key_storage, address_document_types
         }
         return r.
     }
+
+    // ⚠ MUST STAY BYTE-IDENTICAL to __t_wrapper.mm's inline e2e decode (S2 wire-pv + S1 emsig
+    // over ($from,$to,$envelope) + decrypt_and_commit, currently ~lines 96-104). Plan-F folds the
+    // wrapper's inline copy into THIS fn (single call) when the SDK bundle is regenerated (A); until
+    // then the two are a REVIEWED-IDENTICAL pair guarded by the mig-gate decode negative matrix
+    // (bad wire_pv / tampered emsig / wrong $to → abort; replay → !ok). Do NOT edit one without the
+    // other. See MigrationReview point-1 ruling (2026-07-15).
+    // The single AUTHENTICATED inbound-e2e entry for the core-migration boxed-envelope path
+    // (a2a_messaging handle_e2e_migrate_commit/_confirm). At plan-F the __t_wrapper decode hook
+    // folds its inline S1/S2 into THIS fn too (one audited implementation); until then the two are
+    // the reviewed-identical pair the ⚠ note above governs. S2 (wire dialect)
+    // then S1 (emsig over the SENDER + RECIPIENT + envelope context, so a captured envelope cannot
+    // be reflected to a third party or re-targeted) — both FORGERY aborts — then decrypt_and_commit
+    // (which owns the decode-seam staging + pre-key replay guards). The caller supplies the
+    // origin-bound sender SIGN key and e2e identity key (read from the SAME AD it origin-binds).
+    fn recv_authenticated_envelope (from_cid: global_id, to_cid: global_id, origin_sign_key: publickey_sign, sender_ik: bin, env: t_e2e_envelope, emsig: crypto_signature) -> e2e_result
+    {
+        // S2: reject an unknown/downgraded wire dialect before any decrypt/commit.
+        abort "E2E envelope wire-version mismatch" WHEN ((env $pv) as int) != wire_pv().
+        // S1: recompute the signed context from the ACTUAL $from/$to + envelope.
+        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.
+        return decrypt_and_commit from_cid sender_ik ((env $olm_type) as int) ((env $ciphertext) as bin).
+    }
+
+    // Core-migration boxed-envelope decode (a2a_messaging C.3, spec §5.5). The SDK wire schema has
+    // no e2e_signed_message transaction variant yet (a coordinated plan-F SDK-bundle regen), so the
+    // migration commit/confirm carry the staged-session Olm ciphertext as $targ INSIDE the legacy
+    // box; the handler drives the e2e decode here instead of the __t_wrapper decode-seam. SECURITY:
+    // identical S1/S2 auth to the wrapper (via recv_authenticated_envelope). The caller MUST pass
+    // from_cid = the box's AUTHENTICATED sender_id and peer_ad = THAT cid's verified AD; we re-bind
+    // here — (a) AD.container_id == from_cid, (b) the origin SIGN key's address == from_cid, (c) S1
+    // $from == from_cid — so a relay CANNOT box a captured envelope (its signed $from != the relay's
+    // box $from → S1 fails). to_cid = my container id (S1 $to binding: a commit addressed to a
+    // different recipient cannot be replayed into my session).
+    fn decode_migration_envelope (from_cid: global_id, to_cid: global_id, peer_ad: t_address_document, env: t_e2e_envelope, emsig: crypto_signature) -> e2e_result
+    {
+        identity = peer_ad $identity.
+        abort "e2e migration: peer AD container id does not match the box sender" WHEN (identity $container_id) != from_cid.
+        // origin-bound sender SIGN key — the SAME derivation as __t_wrapper check_origin_binding.
+        sign_key_id = identity $default_keys $SIGN.
+        sign_pub IS publickey_sign+ = NIL.
+        sc identity $key_list -- (k->) {
+            if _crypto_get_key_id k == sign_key_id {
+                sign_pub -> k SAFE(publickey_sign).
+                break.
+            }
+        }
+        abort "e2e migration: SIGN key not found in sender identity key_list" WHEN sign_pub == NIL.
+        // DEFENSE-IN-DEPTH (do NOT delete as dead code): the sign-key-origin and bundle-presence
+        // aborts below are already guaranteed for a peer_ads[from_cid] AD by the offer/ack
+        // verify_identity_bundle (origin-binding via PoP+cid-bind) + GATE3 bundle-presence, which a
+        // peer MUST clear before it can reach commit. They become load-bearing if that upstream
+        // verify is ever weakened. (Not driven by the mig-gate guard — would need a forged AD.)
+        abort "e2e migration: sender origin address does not commit to signing key" WHEN (address_of_key sign_pub?) != from_cid.
+        bundle = (identity $e2e_bundle) SAFE(t_e2e_bundle).
+        abort "e2e migration: sender published no e2e bundle" WHEN bundle == NIL.
+        return recv_authenticated_envelope from_cid to_cid sign_pub? (bundle? $ik_curve) env emsig.
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adapt-toolkit/mufl",
-  "version": "0.10.4",
+  "version": "0.10.6",
   "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

@@ -176,7 +176,11 @@ library __t_wrapper loads libraries transaction, key_storage, transaction_queue,
             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). }
+            if (ob_identity $e2e_bundle) {
+                ob_bundle = (ob_identity $e2e_bundle) SAFE(address_document_types::t_e2e_bundle)
+                    abort "Invalid E2E bundle in sender identity" WHEN IS NIL.
+                sender_ik -> ob_bundle? $ik_curve.
+            }
             message -> envelope $body.
             has_envelope -> TRUE.
         } else {