feat(mnp): unified handshake with mutual authentication

Phase 11.5.4/5/7/8 — findings C6 (WebRTC half), C3, L4, M1, M9.

New meshbay_common/handshake.py is the single implementation of authorization
and proof: JWT verify, scope, denylist, mandatory group_id, membership, hosting.
The handshake previously existed three times over and only the newest copy
enforced the GEK proof.

C3 — mutual authentication. Authentication ran one way: the client proved
itself, the node proved nothing. handshake_ack.node_pk was never verified
against anything and per-chunk signatures had been dropped in Phase 9.15, so a
peer that had hijacked signaling (C2) or been substituted by the hub could
accept the client's proof, ignore it, and serve a forged index, forged chat
history and a forged is_node_admin flag. The client now sends a nonce; the node
answers with its own GEK proof over that nonce AND an Ed25519 signature over
the transcript; the browser verifies both and refuses otherwise. It also
refuses an unchallenged handshake_ack, which previously let a peer skip proving
anything at all.

L4 — the proof was nonce ‖ offer_fp ‖ answer_fp: bare concatenation, and a
missing fingerprint silently degraded it to nonce-only, dropping MitM detection
(NS5). Every field is now length-prefixed and domain-separated, the role is
bound so a client proof cannot be replayed as a node proof, and an absent
channel binding is refused rather than tolerated.

M1 — group_id was optional; omitting it skipped the membership check entirely
and fell back to the node's first group. Now mandatory.
M9 — node-scoped daemon tokens are refused on the client path.

NOT DONE: quic_server.py still runs its own JWT-only handshake, so C6 remains
open — a forged or stolen token reaches a node over QUIC and can inject chat
without holding the GEK. quic_binding() is written and unit-tested but unwired.
11.5.6 (whether the certificate-hash anchor works with aioquic, or an RFC 5705
exporter is reachable) is unproven. 11.5.8 TOFU pinning of pk_node is not done:
the client verifies the node's signature but does not yet remember which key it
saw last.

Adds packages/meshbay-common/tests/test_handshake.py (18 tests) covering the
properties every transport must inherit. WebRTC test helpers rewritten around
the shared module; _make_jwt now defaults to the test group, since group_id is
mandatory.

Tests: 24 webrtc, 176+ node+common.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

1 files changed, 80 insertions, 42 deletions

diff --git a/packages/meshbay-node/tests/test_webrtc_transport.py b/packages/meshbay-node/tests/test_webrtc_transport.py
index d57f4f5..59b48ac 100644
--- a/packages/meshbay-node/tests/test_webrtc_transport.py
+++ b/packages/meshbay-node/tests/test_webrtc_transport.py
@@ -19,7 +19,9 @@ import jwt
 import msgpack
 import pytest
 from cryptography.hazmat.primitives import serialization
-from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey, Ed25519PublicKey,
+)
 from aiortc import RTCPeerConnection, RTCSessionDescription
 
 from meshbay_common import MNP_VERSION
@@ -32,6 +34,12 @@ from meshbay_common.crypto import (
 )
 from meshbay_common.webcrypto import chunk_key_aes, decrypt_chunk_aes
 from meshbay_common.protocol import MNP
+TEST_GROUP = "g"
+
+from meshbay_common.handshake import (
+    NONCE_LEN, ROLE_CLIENT, ROLE_NODE, handshake_transcript,
+    make_proof, verify_proof, webrtc_binding,
+)
 from meshbay_common.adminop import (
     OP_FILE_DELETE,
     OP_GEK_BUNDLE_STORE,
@@ -77,6 +85,9 @@ def _hub_pk_pem(sk_hub):
 
 
 def _make_jwt(sk_hub, groups=None, pk_user="test"):
+    # group_id is mandatory now (M1), so the default token must be a member
+    # of the group the tests connect to. Tests that exercise refusal pass
+    # groups=[...] explicitly.
     sk_pem = sk_hub.private_bytes(
         serialization.Encoding.PEM,
         serialization.PrivateFormat.PKCS8,
@@ -87,7 +98,7 @@ def _make_jwt(sk_hub, groups=None, pk_user="test"):
         "iss": "test-hub", "sub": "user-001",
         "pk_user": pk_user, "hub_id": "test-hub",
         "jti": "test-jti-webrtc", "iat": now, "exp": now + 3600,
-        "groups": groups or [],
+        "groups": groups if groups is not None else [TEST_GROUP],
     }, sk_pem, algorithm="EdDSA")
 
 
@@ -123,35 +134,58 @@ def _extract_dtls_fp(sdp: str) -> bytes:
     return b""
 
 
-async def _handshake_with_gek_proof(channel, received, sk_hub, gek, groups=None,
-                                    browser_pc=None):
-    """Send handshake, handle GEK challenge, return handshake_ack."""
-    token = _make_jwt(sk_hub, groups=groups)
+async def _do_mnp_handshake(channel, received, token, gek, pc, group_id):
+    """
+    Client half of the unified handshake (11.5.4): client nonce, length-prefixed
+    role-bound transcript, and verification of the node's own proof + signature.
+    """
+    nonce_c = os.urandom(NONCE_LEN)
     channel.send(_pack({
-        "type": MNP.HANDSHAKE,
-        "v": MNP_VERSION,
-        "token": token,
+        "type": MNP.HANDSHAKE, "v": MNP_VERSION,
+        "token": token, "group_id": group_id,
+        "nonce": base64.b64encode(nonce_c).decode(),
     }))
     msg = await asyncio.wait_for(received.get(), timeout=5.0)
-    if msg["type"] == MNP.HANDSHAKE_CHALLENGE:
-        nonce = base64.b64decode(msg["nonce"])
-        offer_fp = b""
-        answer_fp = b""
-        if browser_pc:
-            offer_fp = _extract_dtls_fp(browser_pc.localDescription.sdp)
-            answer_fp = _extract_dtls_fp(browser_pc.remoteDescription.sdp)
-        proof = hmac.new(gek, nonce + offer_fp + answer_fp, hashlib.sha256).digest()
-        channel.send(_pack({
-            "type": MNP.HANDSHAKE_RESPONSE,
-            "v": MNP_VERSION,
-            "proof": base64.b64encode(proof).decode(),
-        }))
-        msg = await asyncio.wait_for(received.get(), timeout=5.0)
+    if msg["type"] != MNP.HANDSHAKE_CHALLENGE:
+        return msg
+
+    nonce_s = base64.b64decode(msg["nonce"])
+    binding = webrtc_binding(
+        _extract_dtls_fp(pc.localDescription.sdp),
+        _extract_dtls_fp(pc.remoteDescription.sdp),
+    )
+    proof = make_proof(gek, ROLE_CLIENT, group_id, nonce_c, nonce_s, binding)
+    channel.send(_pack({
+        "type": MNP.HANDSHAKE_RESPONSE, "v": MNP_VERSION,
+        "proof": base64.b64encode(proof).decode(),
+    }))
+    ack = await asyncio.wait_for(received.get(), timeout=5.0)
+
+    if ack.get("type") == MNP.HANDSHAKE_ACK:
+        # The client must authenticate the node too (C3).
+        assert verify_proof(
+            gek, base64.b64decode(ack["proof"]), ROLE_NODE,
+            group_id, nonce_c, nonce_s, binding), "node proof invalid"
+        transcript = handshake_transcript(
+            ROLE_NODE, group_id, nonce_c, nonce_s, binding)
+        Ed25519PublicKey.from_public_bytes(
+            base64.b64decode(ack["node_pk"])
+        ).verify(base64.b64decode(ack["sig"]), transcript)
+    return ack
+
+
+async def _handshake_with_gek_proof(channel, received, sk_hub, gek, groups=None,
+                                    browser_pc=None, group_id=TEST_GROUP):
+    """Send handshake, handle GEK challenge, return handshake_ack."""
+    token = _make_jwt(sk_hub, groups=groups or [group_id])
+    msg = await _do_mnp_handshake(
+        channel, received, token, gek, browser_pc, group_id)
     assert msg["type"] == MNP.HANDSHAKE_ACK
     return msg
 
 
-async def _setup_peer(transport, sk_hub, gek, peer_id, jwt_sub="user-001", sk_user=None):
+async def _setup_peer(transport, sk_hub, gek, peer_id, jwt_sub="user-001", sk_user=None,
+                      group_id=TEST_GROUP):
     """Create a peer connection, perform handshake with GEK proof, return (pc, channel, queue)."""
     pc = RTCPeerConnection()
     q = asyncio.Queue()
@@ -199,21 +233,10 @@ async def _setup_peer(transport, sk_hub, gek, peer_id, jwt_sub="user-001", sk_us
         "iss": "test-hub", "sub": jwt_sub,
         "pk_user": pk_user, "hub_id": "test-hub",
         "jti": f"jti-{peer_id}", "iat": now, "exp": now + 3600,
-        "groups": [],
+        "groups": [group_id], "scope": "user",
     }, sk_h_pem, algorithm="EdDSA")
 
-    ch.send(_pack({"type": MNP.HANDSHAKE, "v": MNP_VERSION, "token": token}))
-    msg = await asyncio.wait_for(q.get(), timeout=5.0)
-    if msg["type"] == MNP.HANDSHAKE_CHALLENGE:
-        nonce = base64.b64decode(msg["nonce"])
-        offer_fp = _extract_dtls_fp(pc.localDescription.sdp)
-        answer_fp = _extract_dtls_fp(pc.remoteDescription.sdp)
-        proof = hmac.new(gek, nonce + offer_fp + answer_fp, hashlib.sha256).digest()
-        ch.send(_pack({
-            "type": MNP.HANDSHAKE_RESPONSE, "v": MNP_VERSION,
-            "proof": base64.b64encode(proof).decode(),
-        }))
-        msg = await asyncio.wait_for(q.get(), timeout=5.0)
+    msg = await _do_mnp_handshake(ch, q, token, gek, pc, group_id)
     assert msg["type"] == MNP.HANDSHAKE_ACK
     return pc, ch, q
 
@@ -696,6 +719,8 @@ async def test_webrtc_wrong_gek_proof_rejected(sk_node, sk_hub, gek, shared_dir)
     token = _make_jwt(sk_hub)
     channel.send(_pack({
         "type": MNP.HANDSHAKE, "v": MNP_VERSION, "token": token,
+        "group_id": TEST_GROUP,
+        "nonce": base64.b64encode(os.urandom(NONCE_LEN)).decode(),
     }))
 
     challenge = await asyncio.wait_for(received.get(), timeout=5.0)
@@ -754,6 +779,8 @@ async def test_webrtc_dtls_channel_binding_detects_mitm(sk_node, sk_hub, gek, sh
     token = _make_jwt(sk_hub)
     channel.send(_pack({
         "type": MNP.HANDSHAKE, "v": MNP_VERSION, "token": token,
+        "group_id": TEST_GROUP,
+        "nonce": base64.b64encode(os.urandom(NONCE_LEN)).decode(),
     }))
 
     challenge = await asyncio.wait_for(received.get(), timeout=5.0)
@@ -1159,8 +1186,10 @@ async def test_gek_bundle_fetch_during_handshake(sk_node, sk_hub, gek, shared_di
 
     # Step 1: Send handshake with group_id so _pending_group is set
     token = _make_jwt(sk_hub, groups=["g"])
+    nonce_c = os.urandom(NONCE_LEN)
     channel.send(_pack({
         "type": MNP.HANDSHAKE, "v": MNP_VERSION, "token": token, "group_id": "g",
+        "nonce": base64.b64encode(nonce_c).decode(),
     }))
     msg = await asyncio.wait_for(received.get(), timeout=5.0)
     assert msg["type"] == MNP.HANDSHAKE_CHALLENGE
@@ -1175,11 +1204,12 @@ async def test_gek_bundle_fetch_during_handshake(sk_node, sk_hub, gek, shared_di
     recovered_gek = unwrap_gek(bundle_resp, sk_x_raw, pk_x_raw)
     assert recovered_gek == gek
 
-    nonce = base64.b64decode(msg["nonce"])
-    offer_fp = _extract_dtls_fp(browser_pc.localDescription.sdp)
-    answer_fp = _extract_dtls_fp(browser_pc.remoteDescription.sdp)
-    proof = hmac.new(recovered_gek, nonce + offer_fp + answer_fp,
-                     hashlib.sha256).digest()
+    nonce_s = base64.b64decode(msg["nonce"])
+    binding = webrtc_binding(
+        _extract_dtls_fp(browser_pc.localDescription.sdp),
+        _extract_dtls_fp(browser_pc.remoteDescription.sdp),
+    )
+    proof = make_proof(recovered_gek, ROLE_CLIENT, "g", nonce_c, nonce_s, binding)
 
     # Step 4: Complete handshake
     channel.send(_pack({
@@ -1264,8 +1294,10 @@ async def test_keypair_bundle_store_and_fetch(sk_node, sk_hub, gek, shared_dir,
     await asyncio.wait_for(ready.wait(), timeout=5.0)
 
     token = _make_jwt(sk_hub, groups=["g"])
+    nonce_c = os.urandom(NONCE_LEN)
     channel.send(_pack({
         "type": MNP.HANDSHAKE, "v": MNP_VERSION, "token": token, "group_id": "g",
+        "nonce": base64.b64encode(nonce_c).decode(),
     }))
     msg = await asyncio.wait_for(received.get(), timeout=5.0)
     assert msg["type"] == MNP.HANDSHAKE_CHALLENGE
@@ -1331,8 +1363,10 @@ async def test_keypair_bundle_fetch_not_found(sk_node, sk_hub, gek, shared_dir,
     await asyncio.wait_for(ready.wait(), timeout=5.0)
 
     token = _make_jwt(sk_hub, groups=["g"])
+    nonce_c = os.urandom(NONCE_LEN)
     channel.send(_pack({
         "type": MNP.HANDSHAKE, "v": MNP_VERSION, "token": token, "group_id": "g",
+        "nonce": base64.b64encode(nonce_c).decode(),
     }))
     msg = await asyncio.wait_for(received.get(), timeout=5.0)
     assert msg["type"] == MNP.HANDSHAKE_CHALLENGE
@@ -1448,6 +1482,8 @@ async def test_webrtc_no_gek_connection_refused(sk_node, sk_hub, shared_dir):
     token = _make_jwt(sk_hub)
     channel.send(_pack({
         "type": MNP.HANDSHAKE, "v": MNP_VERSION, "token": token,
+        "group_id": TEST_GROUP,
+        "nonce": base64.b64encode(os.urandom(NONCE_LEN)).decode(),
     }))
 
     msg = await asyncio.wait_for(received.get(), timeout=5.0)
@@ -1507,8 +1543,10 @@ async def test_gek_bundle_fetch_not_found(sk_node, sk_hub, gek, shared_dir, tmp_
     await asyncio.wait_for(ready.wait(), timeout=5.0)
 
     token = _make_jwt(sk_hub, groups=["g"])
+    nonce_c = os.urandom(NONCE_LEN)
     channel.send(_pack({
         "type": MNP.HANDSHAKE, "v": MNP_VERSION, "token": token, "group_id": "g",
+        "nonce": base64.b64encode(nonce_c).decode(),
     }))
     msg = await asyncio.wait_for(received.get(), timeout=5.0)
     assert msg["type"] == MNP.HANDSHAKE_CHALLENGE