From 3ce051e134a432417fcaca4e8b5775d98f614a31 Mon Sep 17 00:00:00 2001
From: Christophe Besson <cbesson@gmail.com>
Date: Thu, 13 Aug 2026 10:42:20 +0200
Subject: fix(node): group isolation, upload confinement, GEK seizure, admin
 challenge
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Phase 11.5 — findings H1, C5a, H2, C5b, H5 (see second-review.md).

Batched together because the node-side changes share webrtc_server.py and
cannot be separated into working commits.

H1 — cross-group chat leak. chat_store, the peer registry and the display-name
cache were read from the shared transport context, and daemon.py hoisted the
FIRST group's chat store onto it. On a node hosting several groups every
group's messages went to one database, chat_history served them back to members
of every other group, and chat broadcast reached all peers regardless of group.
All three now resolve through _group_ctx().

C5a — upload confinement. Uploads landed in the shared root under a
client-chosen name and overwrote whatever was there. Any member could destroy
the operator's files, and by becoming the recorded uploader of the replaced
file could then delete it through the uploader path, bypassing the Ed25519
admin challenge. Uploads now go to a per-user quarantine (.uploads/{user_id}/),
refuse to overwrite, and enforce chunk ordering, a filename allowlist and a
size cap.

H2 — stored XSS in the node admin UI. Filenames chosen by any group member were
interpolated raw into the localhost UI, which has no authentication, so script
execution there equals control of the node admin API. Now html.escape()
throughout, textContent in the audit table, plus CSP/nosniff/no-referrer. The
CSP contains exfiltration but cannot stop injected inline script — escaping is
the fix.

C5b — group key seizure. gek_bundle_store wrote whatever any member sent and
auto-activated bundles addressed to the node operator. The operator's X25519
public key is public (the node publishes it in handshake_ack), so any member
could wrap a key of their choosing for it and take over the group, locking
every legitimate member out. Storing now requires an operator signature and
_try_activate_gek is removed: nothing arriving over MNP can set a live GEK.

H5 — unbound signing oracle. The node challenged with 32 raw random bytes and
the client signed them blind, so a signature named no operation, subject, node
or time. New meshbay_common/adminop.py defines a length-prefixed,
domain-separated transcript; both sides build it independently and the client
refuses to sign when the announced op/subject do not match its request.

BREAKING: a group admin who does not operate the node can no longer store GEK
bundles on it. Invites must be performed by the node operator.

Adds tests/test_security_regressions.py. Verified against pre-fix source via
git stash. Three pre-existing tests asserted the vulnerable behaviour as a
feature and were inverted: gek auto-activation, and the transport-wide
chat_store in test_daemon.

Tests: 109 node, 132 hub+common.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../tests/test_security_regressions.py             | 372 +++++++++++++++++++++
 1 file changed, 372 insertions(+)
 create mode 100644 packages/meshbay-node/tests/test_security_regressions.py

(limited to 'packages/meshbay-node/tests/test_security_regressions.py')

diff --git a/packages/meshbay-node/tests/test_security_regressions.py b/packages/meshbay-node/tests/test_security_regressions.py
new file mode 100644
index 0000000..a480d21
--- /dev/null
+++ b/packages/meshbay-node/tests/test_security_regressions.py
@@ -0,0 +1,372 @@
+"""
+Phase 11.5 security regression tests.
+
+Each test here encodes a finding from `second-review.md`. They are negative tests:
+they assert that an attack does NOT work. The pre-11.5 code passed 209 feature
+tests while every one of these attacks succeeded — the suite only ever exercised
+happy paths, never an authorization boundary.
+
+If one of these starts failing, a fix has been reverted. Do not "fix" the test.
+"""
+
+import base64
+from pathlib import Path
+
+import pytest
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+from meshbay_common.protocol import IndexEntry
+from meshbay_node.indexer.group_index import GroupIndex
+from meshbay_node.transport.webrtc_server import WebRTCPeerSession
+
+
+def _safe_name_re():
+    """
+    Imported lazily so that a missing allowlist fails the two tests that need it,
+    rather than aborting collection of the whole module and hiding every other
+    finding's result.
+    """
+    from meshbay_node.transport.webrtc_server import SAFE_UPLOAD_NAME
+    return SAFE_UPLOAD_NAME
+
+
+# ── C1: the unauthenticated HTTP file API must stay deleted ───────────────────
+
+def test_http_file_api_is_gone():
+    """
+    C1: transport/http_server.py served GET /index and GET /file/{id} on 0.0.0.0
+    with no authentication, for private groups too. It was deleted rather than
+    patched. Re-adding any module that serves file bytes outside the MNP handshake
+    reintroduces a full confidentiality bypass.
+    """
+    with pytest.raises(ImportError):
+        import meshbay_node.transport.http_server  # noqa: F401
+
+    import meshbay_node.transport as transport
+    assert not hasattr(transport, "create_http_app")
+
+
+def test_tcp_transport_is_gone():
+    """C6: the TCP+TLS server accepted a bare JWT with no GEK proof."""
+    with pytest.raises(ImportError):
+        import meshbay_node.transport.server  # noqa: F401
+
+    import meshbay_node.transport as transport
+    assert not hasattr(transport, "ChunkServer")
+
+
+def test_daemon_exposes_no_plaintext_listener():
+    """
+    C1: the daemon must not bind anything that serves content without a handshake.
+    NodeConfig no longer carries an HTTP port at all.
+    """
+    from meshbay_node.config import NodeConfig, GroupConfig
+
+    assert "http_port" not in NodeConfig.__dataclass_fields__
+    assert "http_port" not in GroupConfig.__dataclass_fields__
+    assert "port" not in NodeConfig.__dataclass_fields__
+
+
+# ── C5a: upload filename allowlist ───────────────────────────────────────────
+
+@pytest.mark.parametrize("name", [
+    "../../etc/passwd",
+    "..\\windows\\system32",
+    "/absolute/path",
+    "<img src=x onerror=alert(1)>",          # the H2 stored-XSS vector
+    'name";DROP TABLE x;--',
+    ".hidden",
+    "",
+    "a" * 200,
+    "file\x00.mp4",
+    "sub/dir/file.mp4",
+])
+def test_upload_rejects_unsafe_filenames(name):
+    """C5a/H2: only a conservative allowlist may reach the filesystem."""
+    assert not _safe_name_re().match(name), f"should be rejected: {name!r}"
+
+
+@pytest.mark.parametrize("name", [
+    "movie.mp4",
+    "My Holiday Video.mkv",
+    "report-2026.pdf",
+    "track_01.flac",
+])
+def test_upload_accepts_ordinary_filenames(name):
+    """The allowlist must not break normal use."""
+    assert _safe_name_re().match(name), f"should be accepted: {name!r}"
+
+
+def _session(tmp_path: Path, user_id: str) -> WebRTCPeerSession:
+    """A peer session wired to a real shared root, with sending stubbed out."""
+    shared_root = tmp_path / "shared"
+    shared_root.mkdir(exist_ok=True)
+    index = GroupIndex(group_id="g" * 32, sk_node=Ed25519PrivateKey.generate())
+    ctx = {"shared_root": shared_root, "index": index, "sk_node": index.sk_node}
+
+    session = WebRTCPeerSession.__new__(WebRTCPeerSession)
+    session._ctx = ctx
+    session._group_id = None
+    session._user_id = user_id
+    session._pk_user = ""
+    session._uploads = {}
+    session.sent = []
+    session._send = session.sent.append
+    session._audit = lambda *a, **k: None
+    return session
+
+
+def test_upload_cannot_overwrite_another_members_file(tmp_path):
+    """
+    C5a: uploads used to land in the shared root under a client-chosen name and
+    overwrite whatever was there. That let any member destroy the operator's files,
+    and — by becoming the recorded uploader of the replaced file — delete them
+    through the uploader path, bypassing the Ed25519 admin challenge entirely.
+    """
+    victim = _session(tmp_path, "victim-user")
+    shared_root = victim._ctx["shared_root"]
+
+    original = shared_root / "important.mp4"
+    original.write_bytes(b"operator's original content")
+
+    attacker = _session(tmp_path, "attacker-user")
+    attacker._do_file_upload({
+        "filename": "important.mp4",
+        "chunk_index": 0,
+        "total_chunks": 1,
+        "data": base64.b64encode(b"attacker content").decode(),
+    })
+
+    assert original.read_bytes() == b"operator's original content"
+    uploaded = shared_root / ".uploads" / "attacker-user" / "important.mp4"
+    assert uploaded.exists(), "upload should be quarantined, not dropped"
+    assert uploaded.read_bytes() == b"attacker content"
+
+
+def test_upload_rejects_out_of_order_chunks(tmp_path):
+    """C5a: chunk_index > 0 used to append blindly to any .part file on disk."""
+    session = _session(tmp_path, "user-1")
+    session._do_file_upload({
+        "filename": "movie.mp4", "chunk_index": 3, "total_chunks": 5,
+        "data": base64.b64encode(b"spliced").decode(),
+    })
+    assert any(m.get("type") == "error" for m in session.sent)
+
+
+def test_upload_second_attempt_cannot_replace_own_completed_file(tmp_path):
+    """C5a: even the original uploader goes through a fresh name, not an overwrite."""
+    session = _session(tmp_path, "user-1")
+    payload = {"filename": "movie.mp4", "chunk_index": 0, "total_chunks": 1,
+               "data": base64.b64encode(b"first").decode()}
+    session._do_file_upload(dict(payload))
+    session.sent.clear()
+
+    session._do_file_upload(dict(payload))
+    assert any(m.get("type") == "error" for m in session.sent)
+    stored = session._ctx["shared_root"] / ".uploads" / "user-1" / "movie.mp4"
+    assert stored.read_bytes() == b"first"
+
+
+# ── H1: group isolation ──────────────────────────────────────────────────────
+
+def test_chat_store_and_peers_are_per_group(tmp_path):
+    """
+    H1: chat_store and the peer registry were read from the shared transport
+    context, so on a multi-group node every group's messages went to the first
+    group's database and were served back to members of every other group.
+    """
+    index_a = GroupIndex(group_id="a" * 32, sk_node=Ed25519PrivateKey.generate())
+    index_b = GroupIndex(group_id="b" * 32, sk_node=Ed25519PrivateKey.generate())
+    groups = {
+        "a" * 32: {"chat_store": "STORE_A", "index": index_a, "shared_root": tmp_path},
+        "b" * 32: {"chat_store": "STORE_B", "index": index_b, "shared_root": tmp_path},
+    }
+    ctx = {"groups": groups}
+
+    sess_a = WebRTCPeerSession.__new__(WebRTCPeerSession)
+    sess_a._ctx, sess_a._group_id, sess_a._user_id = ctx, "a" * 32, "alice"
+
+    sess_b = WebRTCPeerSession.__new__(WebRTCPeerSession)
+    sess_b._ctx, sess_b._group_id, sess_b._user_id = ctx, "b" * 32, "bob"
+
+    assert sess_a._group_ctx()["chat_store"] == "STORE_A"
+    assert sess_b._group_ctx()["chat_store"] == "STORE_B"
+
+    sess_a._peer_registry()["alice"] = sess_a
+    sess_b._peer_registry()["bob"] = sess_b
+
+    # Alice's broadcast target set must not contain Bob, who is in another group.
+    assert "bob" not in sess_a._peer_registry()
+    assert "alice" not in sess_b._peer_registry()
+
+    sess_a._user_names()["alice"] = "Alice"
+    assert "alice" not in sess_b._user_names()
+
+
+def test_daemon_sets_no_global_chat_store(tmp_path):
+    """H1: the daemon must not hoist one group's chat store onto the transport."""
+    source = (Path(__file__).parent.parent
+              / "src" / "meshbay_node" / "daemon.py").read_text()
+    assert '_ctx["chat_store"]' not in source, (
+        "daemon must not assign a transport-wide chat_store — it leaks chat "
+        "across groups (H1)"
+    )
+
+
+# ── H2: node admin UI escaping ───────────────────────────────────────────────
+
+def test_gek_bundle_store_requires_admin_challenge(tmp_path):
+    """
+    C5b: gek_bundle_store used to write whatever any authenticated member sent.
+    It must now answer with a challenge and store nothing until a valid
+    node-operator signature arrives.
+    """
+    session = _session(tmp_path, "ordinary-member")
+    session._group_id = None
+    session._admin_ops = {}
+    session._ctx["admin_pk_ed25519"] = Ed25519PrivateKey.generate().public_key()
+
+    stored = []
+
+    class _Store:
+        async def store(self, *args):
+            stored.append(args)
+
+    session._ctx["bundle_store"] = _Store()
+    session._do_gek_bundle_store({
+        "user_id": "victim", "group_id": "g" * 32,
+        "pk_eph_b64": "AA==", "nonce_b64": "AA==", "wrapped_b64": "AA==",
+    })
+
+    assert stored == [], "bundle written without operator authorization (C5b)"
+    assert any(m.get("type") == "admin_challenge" for m in session.sent)
+
+
+def test_gek_bundle_store_refused_without_pinned_admin_key(tmp_path):
+    """C5b: deny by default — no pinned key means no privileged operation."""
+    session = _session(tmp_path, "ordinary-member")
+    session._group_id = None
+    session._admin_ops = {}
+    session._ctx["bundle_store"] = object()
+
+    session._do_gek_bundle_store({
+        "user_id": "victim", "group_id": "g" * 32,
+        "pk_eph_b64": "AA==", "nonce_b64": "AA==", "wrapped_b64": "AA==",
+    })
+    assert any(m.get("type") == "error" for m in session.sent)
+
+
+def test_gek_auto_activation_is_gone():
+    """
+    C5b: the node used to unwrap and adopt any bundle addressed to the operator.
+    Since the operator's X25519 public key is public, any member could hand the
+    node a GEK of their choosing. Nothing arriving over MNP may set a live GEK.
+    """
+    source = (Path(__file__).parent.parent / "src" / "meshbay_node"
+              / "transport" / "webrtc_server.py").read_text()
+    assert "_try_activate_gek" not in source
+    assert 'unwrap_gek_aes' not in source, (
+        "the MNP path must not unwrap a GEK — activation is local-admin only"
+    )
+
+
+# ── H5: admin challenge is bound, not a blind signing oracle ─────────────────
+
+def _transcript(**kw):
+    from meshbay_common.adminop import admin_transcript
+    base = dict(op="file_delete", node_pk_b64="NODEPK", group_id="g" * 32,
+                subject="file-1", nonce=b"\x01" * 32, ts=1_700_000_000)
+    base.update(kw)
+    return admin_transcript(**base)
+
+
+def test_admin_transcript_is_domain_separated():
+    """H5: signatures here can never be valid in another MeshBay protocol."""
+    assert _transcript().startswith(b"meshbay:admin:v1")
+
+
+@pytest.mark.parametrize("field,value", [
+    ("op", "gek_bundle_store"),
+    ("subject", "file-2"),
+    ("node_pk_b64", "OTHERNODE"),
+    ("group_id", "h" * 32),
+    ("nonce", b"\x02" * 32),
+    ("ts", 1_700_000_001),
+])
+def test_admin_transcript_binds_every_field(field, value):
+    """
+    H5: a signature must not carry over to another operation, subject, node,
+    group, challenge or moment in time.
+    """
+    assert _transcript() != _transcript(**{field: value}), (
+        f"transcript ignores {field} — signature would be reusable"
+    )
+
+
+def test_admin_transcript_is_unambiguous():
+    """
+    H5/L4: fields are length-prefixed. With plain concatenation a crafted subject
+    could impersonate the following field and two different operations would
+    produce identical signed bytes.
+    """
+    a = _transcript(subject="file-1", group_id="g")
+    b = _transcript(subject="1", group_id="gfile-")
+    assert a != b, "concatenation is ambiguous — length prefixes missing"
+
+
+def test_admin_signature_does_not_transfer_between_operations(tmp_path):
+    """
+    H5: the concrete attack. A signature collected to delete a file must not
+    authorize storing a GEK bundle.
+    """
+    from meshbay_common.adminop import OP_FILE_DELETE, OP_GEK_BUNDLE_STORE
+
+    sk_admin = Ed25519PrivateKey.generate()
+    delete_transcript = _transcript(op=OP_FILE_DELETE)
+    signature = sk_admin.sign(delete_transcript)
+
+    store_transcript = _transcript(op=OP_GEK_BUNDLE_STORE)
+    with pytest.raises(Exception):
+        sk_admin.public_key().verify(signature, store_transcript)
+
+
+def test_admin_challenge_expires(tmp_path):
+    """H5: a stale challenge must not be usable."""
+    import time as _time
+    from meshbay_common.adminop import ADMIN_CHALLENGE_TTL, OP_FILE_DELETE
+
+    session = _session(tmp_path, "operator")
+    session._group_id = None
+    session._admin_ops = {
+        "op-1": {
+            "op": OP_FILE_DELETE, "subject": "file-1", "nonce": b"\x00" * 32,
+            "ts": int(_time.time()) - ADMIN_CHALLENGE_TTL - 5, "payload": {},
+        }
+    }
+    session._do_admin_response({"op_id": "op-1", "signature": ""})
+    assert any(m.get("type") == "error" and "expired" in m.get("detail", "").lower()
+               for m in session.sent)
+
+
+def test_admin_ui_escapes_filenames(tmp_path):
+    """
+    H2: filenames are chosen by any group member and were rendered into the
+    localhost admin UI unescaped, giving script execution against an
+    unauthenticated admin API.
+    """
+    from meshbay_node.ui.app import _render_page
+
+    payload = '<img src=x onerror="fetch(1)">'
+    index = GroupIndex(group_id="g" * 32, sk_node=Ed25519PrivateKey.generate())
+    index.add_entry(IndexEntry(
+        id="0" * 64, name=payload, path="", size=1, type="video", added_at=0,
+    ))
+
+    html = _render_page({
+        "status": "running",
+        "groups_ctx": {"g" * 32: {"index": index, "shared_root": tmp_path}},
+        "indexes": {"g" * 32: index},
+    })
+
+    assert payload not in html, "filename rendered unescaped — stored XSS (H2)"
+    assert "&lt;img" in html, "filename should appear escaped"
-- 
cgit v1.2.3


From 9df71bd1e5244743fae8c1b2bda41143f0748d9d Mon Sep 17 00:00:00 2001
From: Christophe Besson <cbesson@gmail.com>
Date: Thu, 13 Aug 2026 11:00:39 +0200
Subject: fix: swarm privacy, revocation persistence, keystore KDF, audit
 integrity
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Phase 11.5 hardening batch — H7, H4, M2, M6, M7, L1, L3, L6.

H7 — private content hashes leaked to the hub. The daemon registered blake3
hashes for every group it hosted, private ones included, giving the hub a
content fingerprint of every private file and letting anyone confirm whether a
known file exists in the network. The leak was dormant only because the routes
were declared on the groups router with a full path and mounted at
/v1/groups/v1/swarm/* — the node's calls 404'd into a swallowed exception.
Fixing the path alone would have activated the leak, so both land together:
registration is gated on group visibility, the routes moved to a real
/v1/swarm router, and the lookup now requires authentication.

H4 — revocation was advisory. Group revocations were signed and broadcast by
the hub and then dropped by the node, whose handler understood only "user" and
"jti", so "suspend a group" enforced nothing. The denylist was also in-memory
only, so a restart silently un-revoked everyone. Now persisted to
data_dir/denylist.json, group targets honoured on both transports, and live
sessions for a revoked group are closed.

M2 — the node keystore, which protects the node's Ed25519 and X25519 private
keys, was still deriving at 64 MB long after the hub's password verifier moved
to 256 MB; the docs recorded the bump as done, true for the hub only. Raising
the constant alone would have made every existing keystore permanently
undecryptable, so envelopes now record the parameters they were written with
and pre-M2 files continue to open under the legacy profile.

M6 — registration inserted its audit row with a NULL user_id and then ran
UPDATE ip_logs SET user_id=<new> WHERE user_id IS NULL, claiming every
unattributed row in the table: failed logins for other usernames, concurrent
registrations. In logs retained a year for legal requests, that attributed
other people's connections to the wrong account.

M7 — X-Forwarded-For was trusted unconditionally at four call sites, so anyone
could forge the IP written to the compliance log and evade per-IP rate limits.
New netutil.client_ip honours the header only from a trusted proxy and takes
the rightmost hop (the one our proxy appended); no direct header reads remain.

L1 dead GEK_REQUEST/GEK_RESPONSE constants removed; L3 peer errors no longer
echo exception text (paths, internal state); L6 email sanity-checked instead of
accepting any string — deliberately not RFC 5322, to avoid a new dependency.

test_daemon_index_change_pushes_to_peers asserted that a PRIVATE group's hashes
are registered with the hub. Split: private asserts not-called (index push to
members still asserted), and a new test proves public groups still register.
That is the fourth pre-existing test found asserting a vulnerability as
intended behaviour, after gek auto-activation, the transport-wide chat_store
and the blind admin challenge.

Tests: 116 node, 132 hub+common. Regression suite now 43.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../meshbay-common/src/meshbay_common/crypto.py    |  40 +++++--
 .../meshbay-common/src/meshbay_common/protocol.py  |   6 +-
 packages/meshbay-hub/src/meshbay_hub/api/groups.py |  37 +++++--
 .../meshbay-hub/src/meshbay_hub/api/moderation.py  |   8 +-
 .../meshbay-hub/src/meshbay_hub/api/netutil.py     |  34 ++++++
 packages/meshbay-hub/src/meshbay_hub/api/nodes.py  |  12 +--
 packages/meshbay-hub/src/meshbay_hub/api/users.py  |  47 ++++++---
 packages/meshbay-hub/src/meshbay_hub/app.py        |   3 +-
 packages/meshbay-node/src/meshbay_node/daemon.py   |  36 ++++++-
 packages/meshbay-node/src/meshbay_node/keystore.py |  25 ++++-
 .../src/meshbay_node/transport/quic_server.py      |  58 +++++++++-
 .../src/meshbay_node/transport/webrtc_server.py    |   9 +-
 packages/meshbay-node/tests/test_daemon.py         |  40 ++++++-
 .../tests/test_security_regressions.py             | 117 +++++++++++++++++++++
 14 files changed, 406 insertions(+), 66 deletions(-)
 create mode 100644 packages/meshbay-hub/src/meshbay_hub/api/netutil.py

(limited to 'packages/meshbay-node/tests/test_security_regressions.py')

diff --git a/packages/meshbay-common/src/meshbay_common/crypto.py b/packages/meshbay-common/src/meshbay_common/crypto.py
index 682e1c0..b2ff3c0 100644
--- a/packages/meshbay-common/src/meshbay_common/crypto.py
+++ b/packages/meshbay-common/src/meshbay_common/crypto.py
@@ -168,21 +168,45 @@ def unwrap_gek_aes(bundle: dict, sk_recipient: bytes, pk_recipient: bytes) -> by
 
 # ── Keystore (local key storage) ──────────────────────────────────────────────
 
-# Argon2id parameters — calibrate to ~500ms on target hardware before production.
-# POC measured 78ms with these; increase memory_cost to 262144 (256MB) for prod.
+# Argon2id parameters for the node keystore.
+#
+# Finding M2: these sat at 64 MB long after the hub's password verifier was raised
+# to 256 MB, and the docs recorded the bump as done — true for the hub, false here.
+# The keystore protects the node's Ed25519 and X25519 private keys, so it is the
+# more valuable target of the two.
+#
+# Parameters are recorded in each keystore envelope, so raising them does not
+# invalidate existing files: LEGACY_* is used when an envelope predates the field.
 ARGON2_ITERATIONS   = 3
-ARGON2_MEMORY_COST  = 65536   # 64 MB — increase to 262144 for production
+ARGON2_MEMORY_COST  = 262144   # 256 MB
 ARGON2_LANES        = 4
 ARGON2_KEY_LENGTH   = 32
 
-def derive_keystore_key(password: str, salt: bytes) -> bytes:
-    """Derive AES-256 key from password using Argon2id."""
+LEGACY_ARGON2_ITERATIONS  = 3
+LEGACY_ARGON2_MEMORY_COST = 65536    # 64 MB — keystores written before M2
+LEGACY_ARGON2_LANES       = 4
+
+
+def derive_keystore_key(
+    password: str,
+    salt: bytes,
+    *,
+    iterations: int | None = None,
+    memory_cost: int | None = None,
+    lanes: int | None = None,
+) -> bytes:
+    """
+    Derive an AES-256 key from a password using Argon2id.
+
+    Parameters default to the current production values; callers pass the values
+    recorded in an existing envelope when opening an older keystore.
+    """
     return Argon2id(
         salt=salt,
         length=ARGON2_KEY_LENGTH,
-        iterations=ARGON2_ITERATIONS,
-        lanes=ARGON2_LANES,
-        memory_cost=ARGON2_MEMORY_COST,
+        iterations=ARGON2_ITERATIONS if iterations is None else iterations,
+        lanes=ARGON2_LANES if lanes is None else lanes,
+        memory_cost=ARGON2_MEMORY_COST if memory_cost is None else memory_cost,
     ).derive(password.encode())
 
 def encrypt_keystore(plaintext: bytes, key: bytes) -> tuple[bytes, bytes, bytes]:
diff --git a/packages/meshbay-common/src/meshbay_common/protocol.py b/packages/meshbay-common/src/meshbay_common/protocol.py
index 55dcdde..d86b4ef 100644
--- a/packages/meshbay-common/src/meshbay_common/protocol.py
+++ b/packages/meshbay-common/src/meshbay_common/protocol.py
@@ -29,8 +29,10 @@ class MNP:
     CHAT_ATTACHMENT = "chat_attach"      # attachment metadata
     CHAT_HISTORY    = "chat_hist"       # request message history
     CHAT_HISTORY_RESPONSE = "chat_hist_resp"  # history response with messages
-    GEK_REQUEST     = "gek_req"         # browser requests group GEK
-    GEK_RESPONSE    = "gek_resp"        # node delivers GEK over secure channel
+    # GEK_REQUEST / GEK_RESPONSE were removed (NS3, and finding L1): the node must
+    # never serve the GEK in plaintext. Members obtain it by unwrapping their own
+    # ECIES bundle. The constants lingered after the handlers were deleted, leaving
+    # the wire contract looking as though the endpoint still existed.
     FILE_UPLOAD      = "file_upload"       # client pushes file chunk to node
     FILE_UPLOAD_ACK  = "file_upload_ack"   # node acknowledges chunk receipt
     FILE_DELETE      = "file_delete"       # client requests file deletion
diff --git a/packages/meshbay-hub/src/meshbay_hub/api/groups.py b/packages/meshbay-hub/src/meshbay_hub/api/groups.py
index 88af764..000f3f7 100644
--- a/packages/meshbay-hub/src/meshbay_hub/api/groups.py
+++ b/packages/meshbay-hub/src/meshbay_hub/api/groups.py
@@ -6,6 +6,7 @@ from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from meshbay_hub.api.deps import get_current_user, require_user_scope
+from meshbay_hub.api.netutil import client_ip
 from meshbay_hub.db.engine import get_db
 from meshbay_hub.db.models import (
     FederatedGroup, Group, GroupMember,
@@ -14,6 +15,10 @@ from meshbay_hub.db.models import (
 
 router = APIRouter(prefix="/v1/groups", tags=["groups"])
 
+# Swarm endpoints live at /v1/swarm/*. They were previously declared on the groups
+# router with a full path, which mounted them at /v1/groups/v1/swarm/* (H7).
+swarm_router = APIRouter(prefix="/v1/swarm", tags=["swarm"])
+
 
 @router.get("/mine")
 async def my_groups(
@@ -117,13 +122,21 @@ class SwarmRegisterRequest(BaseModel):
     endpoint:     str    # "ip:port"
 
 
-@router.post("/v1/swarm/register", status_code=201)
+@swarm_router.post("/register", status_code=201)
 async def swarm_register(
     body: SwarmRegisterRequest,
     current_user: User = Depends(get_current_user),
     db: AsyncSession = Depends(get_db),
 ):
-    """Node registers itself as a source for a content hash (public swarm)."""
+    """
+    Node registers itself as a source for a PUBLIC content hash.
+
+    Finding H7: the node registered hashes for every group it hosted, private ones
+    included, and this route was mounted at /v1/groups/v1/swarm/register — so the
+    node's calls 404'd and the leak was masked by a routing bug rather than
+    prevented. Nodes now filter by group visibility before calling, and the path is
+    correct, so the filter has to be right.
+    """
     from meshbay_hub.csam import check_content_hash
     if check_content_hash(body.content_hash):
         raise HTTPException(status_code=451, detail="Content blocked")
@@ -144,12 +157,18 @@ async def swarm_register(
     return {"status": "registered", "hash": body.content_hash}
 
 
-@router.get("/v1/swarm/{content_hash}")
+@swarm_router.get("/{content_hash}")
 async def swarm_sources(
     content_hash: str,
+    current_user: User = Depends(get_current_user),
     db: AsyncSession = Depends(get_db),
 ):
-    """Return list of nodes that can serve a content hash."""
+    """
+    Return nodes that can serve a content hash.
+
+    Authenticated (H7): an open endpoint lets anyone probe whether a given file
+    exists anywhere in the network and which node holds it.
+    """
     from datetime import datetime, timezone, timedelta
     cutoff = datetime.now(timezone.utc) - timedelta(minutes=30)
     result = await db.execute(
@@ -214,7 +233,7 @@ async def join_group(
 
     db.add(GroupMember(group_id=group_id, user_id=current_user.id))
     db.add(IPLog(user_id=current_user.id, event="group_join",
-                 ip_address=_ip(request), detail=group.name))
+                 ip_address=client_ip(request), detail=group.name))
     await db.commit()
     return {"status": "joined", "group_id": group_id, "name": group.name}
 
@@ -246,7 +265,7 @@ async def create_group(
 
     db.add(GroupMember(group_id=group.id, user_id=current_user.id))
     db.add(IPLog(user_id=current_user.id, event="group_create",
-                 ip_address=_ip(request), detail=body.name))
+                 ip_address=client_ip(request), detail=body.name))
     await db.commit()
     await db.refresh(group)
     return {"group_id": group.id, "name": group.name}
@@ -304,13 +323,9 @@ async def delete_group(
     from sqlalchemy import delete as sa_delete
     await db.execute(sa_delete(GroupMember).where(GroupMember.group_id == group_id))
     db.add(IPLog(user_id=current_user.id, event="group_delete",
-                 ip_address=_ip(request), detail=group.name))
+                 ip_address=client_ip(request), detail=group.name))
     await db.delete(group)
     await db.commit()
     return {"status": "deleted", "group_id": group_id}
 
 
-def _ip(request: Request) -> str:
-    fwd = request.headers.get("X-Forwarded-For")
-    return fwd.split(",")[0].strip() if fwd else (
-        request.client.host if request.client else "unknown")
diff --git a/packages/meshbay-hub/src/meshbay_hub/api/moderation.py b/packages/meshbay-hub/src/meshbay_hub/api/moderation.py
index 6bb007b..853f255 100644
--- a/packages/meshbay-hub/src/meshbay_hub/api/moderation.py
+++ b/packages/meshbay-hub/src/meshbay_hub/api/moderation.py
@@ -28,6 +28,7 @@ from sqlalchemy import func, select
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from meshbay_hub.api.deps import get_current_user, require_admin
+from meshbay_hub.api.netutil import client_ip
 from meshbay_hub.db.engine import get_db
 from meshbay_hub.db.models import ContentBlocklist, ContentReport, User
 
@@ -64,7 +65,7 @@ async def report_content(
     if len(body.content_hash) != 64 or not all(c in "0123456789abcdef" for c in body.content_hash):
         raise HTTPException(status_code=422, detail="content_hash must be 64 hex chars (blake3)")
 
-    ip = _ip(request)
+    ip = client_ip(request)
 
     # Count existing reports for this hash
     count_result = await db.execute(
@@ -193,8 +194,3 @@ async def admin_remove_blocklist(
     await db.commit()
     return {"status": "unblocked", "hash": content_hash}
 
-
-def _ip(request: Request) -> str:
-    fwd = request.headers.get("X-Forwarded-For")
-    return fwd.split(",")[0].strip() if fwd else (
-        request.client.host if request.client else "unknown")
diff --git a/packages/meshbay-hub/src/meshbay_hub/api/netutil.py b/packages/meshbay-hub/src/meshbay_hub/api/netutil.py
new file mode 100644
index 0000000..aa8344a
--- /dev/null
+++ b/packages/meshbay-hub/src/meshbay_hub/api/netutil.py
@@ -0,0 +1,34 @@
+"""
+Client address resolution for the audit log and rate limiting.
+
+Finding M7: every call site did
+
+    fwd = request.headers.get("X-Forwarded-For")
+    return fwd.split(",")[0].strip() if fwd else request.client.host
+
+which trusts a header the client controls. Anyone could forge the IP written into
+the compliance log — the log that exists specifically to answer legal requests —
+and sidestep per-IP rate limiting at the same time.
+
+X-Forwarded-For is only consulted when the immediate peer is a trusted proxy, and
+then the *rightmost* entry is used: that is the one our own proxy appended, whereas
+the leftmost is whatever the client sent.
+"""
+
+from fastapi import Request
+
+# Caddy terminates TLS on the same host and proxies to 127.0.0.1:8000.
+TRUSTED_PROXIES = frozenset({"127.0.0.1", "::1", "localhost"})
+
+
+def client_ip(request: Request) -> str:
+    peer = request.client.host if request.client else ""
+
+    if peer in TRUSTED_PROXIES:
+        forwarded = request.headers.get("X-Forwarded-For")
+        if forwarded:
+            hops = [h.strip() for h in forwarded.split(",") if h.strip()]
+            if hops:
+                return hops[-1]
+
+    return peer or "unknown"
diff --git a/packages/meshbay-hub/src/meshbay_hub/api/nodes.py b/packages/meshbay-hub/src/meshbay_hub/api/nodes.py
index 321e43c..7738875 100644
--- a/packages/meshbay-hub/src/meshbay_hub/api/nodes.py
+++ b/packages/meshbay-hub/src/meshbay_hub/api/nodes.py
@@ -13,6 +13,7 @@ from sqlalchemy.ext.asyncio import AsyncSession
 from meshbay_hub.auth import issue_access_token
 from meshbay_hub.api.deps import get_current_user
 from meshbay_hub.api.middleware import limiter
+from meshbay_hub.api.netutil import client_ip
 from meshbay_hub.db.engine import get_db
 from meshbay_hub.db.models import GroupMember, IPLog, Node, User
 
@@ -59,7 +60,7 @@ async def node_auth(
         sig = base64.b64decode(body.signature)
         pk.verify(sig, message)
     except (InvalidSignature, Exception):
-        db.add(IPLog(event="node_auth_fail", ip_address=_ip(request), detail=body.username))
+        db.add(IPLog(event="node_auth_fail", ip_address=client_ip(request), detail=body.username))
         await db.commit()
         raise HTTPException(status_code=401, detail="Invalid signature")
 
@@ -70,7 +71,7 @@ async def node_auth(
     access_token = issue_access_token(
         user.id, user.pk_node_ed25519, ttl=3600, groups=group_ids, scope="node")
 
-    db.add(IPLog(user_id=user.id, event="node_auth", ip_address=_ip(request)))
+    db.add(IPLog(user_id=user.id, event="node_auth", ip_address=client_ip(request)))
     await db.commit()
 
     return {
@@ -101,7 +102,7 @@ async def announce_node(
     db.add(IPLog(
         user_id=current_user.id,
         event="node_announce",
-        ip_address=_ip(request),
+        ip_address=client_ip(request),
         detail=body.endpoint_hint,
     ))
     await db.commit()
@@ -128,8 +129,3 @@ async def get_node(
     }
 
 
-def _ip(request: Request) -> str:
-    fwd = request.headers.get("X-Forwarded-For")
-    if fwd:
-        return fwd.split(",")[0].strip()
-    return request.client.host if request.client else "unknown"
diff --git a/packages/meshbay-hub/src/meshbay_hub/api/users.py b/packages/meshbay-hub/src/meshbay_hub/api/users.py
index 53238de..5a0f9dc 100644
--- a/packages/meshbay-hub/src/meshbay_hub/api/users.py
+++ b/packages/meshbay-hub/src/meshbay_hub/api/users.py
@@ -5,7 +5,7 @@ import uuid
 from datetime import datetime, timezone, timedelta
 
 from fastapi import APIRouter, Depends, HTTPException, Request, status
-from pydantic import BaseModel, EmailStr, field_validator
+from pydantic import BaseModel, field_validator
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
@@ -22,6 +22,7 @@ from meshbay_hub.auth import (
     verify_password,
 )
 from meshbay_hub.api.middleware import limiter
+from meshbay_hub.api.netutil import client_ip
 from meshbay_hub.config import HubConfig
 from meshbay_hub.db.engine import get_db
 from meshbay_hub.db.models import GroupMember, IPLog, RefreshToken, User
@@ -62,6 +63,24 @@ class RegisterRequest(BaseModel):
             raise ValueError("username: only letters, digits, -, _, .")
         return v
 
+    @field_validator("email")
+    @classmethod
+    def email_valid(cls, v: str) -> str:
+        """
+        Sanity-check the address (L6): the field was plain `str`, so any junk was
+        accepted and stored encrypted forever. Deliberately not RFC 5322 — full
+        validation would pull in the email-validator dependency for little gain,
+        and the address is only ever used for recovery and legal contact.
+        """
+        v = v.strip()
+        local, sep, domain = v.partition("@")
+        if (not sep or not local or not domain
+                or "." not in domain
+                or len(v) > 254
+                or any(c.isspace() or ord(c) < 32 for c in v)):
+            raise ValueError("invalid email address")
+        return v
+
 
 class LoginRequest(BaseModel):
     username: str
@@ -106,21 +125,24 @@ async def register(
         hub_id=hub_id,
     )
     db.add(user)
+    # flush assigns user.id so the log row can be attributed directly.
+    #
+    # Finding M6: this used to insert the row with a NULL user_id and then run
+    #   UPDATE ip_logs SET user_id = <new user> WHERE user_id IS NULL
+    # which claimed *every* unattributed row in the table — failed logins for other
+    # usernames, other registrations racing this one — and stamped them with the
+    # account just created. For logs retained a year to answer legal requests, that
+    # attributed other people's connections to the wrong person.
+    await db.flush()
     db.add(IPLog(
+        user_id=user.id,
         event="account_create",
-        ip_address=_client_ip(request),
+        ip_address=client_ip(request),
         detail=body.username,
     ))
     await db.commit()
     await db.refresh(user)
 
-    # Set user_id in IPLog after commit
-    await db.execute(
-        IPLog.__table__.update()
-        .where(IPLog.user_id == None)  # noqa: E711
-        .values(user_id=user.id))
-    await db.commit()
-
     return {"user_id": user.id}
 
 
@@ -135,7 +157,7 @@ async def login(
         select(User).where(User.username == body.username))
     user = result.scalar_one_or_none()
 
-    ip = _client_ip(request)
+    ip = client_ip(request)
 
     if not body.auth_key and not body.password:
         raise HTTPException(status_code=401, detail="No credentials provided")
@@ -358,8 +380,3 @@ async def get_user_pubkeys(
     return resp
 
 
-def _client_ip(request: Request) -> str:
-    forwarded = request.headers.get("X-Forwarded-For")
-    if forwarded:
-        return forwarded.split(",")[0].strip()
-    return request.client.host if request.client else "unknown"
diff --git a/packages/meshbay-hub/src/meshbay_hub/app.py b/packages/meshbay-hub/src/meshbay_hub/app.py
index 7011bf0..668ae24 100644
--- a/packages/meshbay-hub/src/meshbay_hub/app.py
+++ b/packages/meshbay-hub/src/meshbay_hub/app.py
@@ -25,7 +25,7 @@ from meshbay_hub.api.hub        import router as hub_router
 from meshbay_hub.api.users      import router as users_router, set_config as users_set_config
 from meshbay_hub.api.deps       import set_admin_usernames
 from meshbay_hub.api.nodes      import router as nodes_router
-from meshbay_hub.api.groups     import router as groups_router
+from meshbay_hub.api.groups     import router as groups_router, swarm_router
 from meshbay_hub.api.revocation  import router as revocation_router
 from meshbay_hub.api.moderation  import router as moderation_router
 from meshbay_hub.api.federation  import router as federation_router
@@ -110,6 +110,7 @@ def create_app(cfg: HubConfig | None = None) -> FastAPI:
     app.include_router(users_router)
     app.include_router(nodes_router)
     app.include_router(groups_router)
+    app.include_router(swarm_router)
     app.include_router(revocation_router)
     app.include_router(moderation_router)
     app.include_router(federation_router)
diff --git a/packages/meshbay-node/src/meshbay_node/daemon.py b/packages/meshbay-node/src/meshbay_node/daemon.py
index c75c721..7dedad8 100644
--- a/packages/meshbay-node/src/meshbay_node/daemon.py
+++ b/packages/meshbay-node/src/meshbay_node/daemon.py
@@ -107,7 +107,9 @@ class NodeDaemon:
         }
         self._quic_server = None
         self._webrtc = None
-        self._denylist = Denylist() if Denylist else None
+        # Persisted so a restart does not silently un-revoke everyone (H4)
+        self._denylist = (
+            Denylist(path=config.data_dir / "denylist.json") if Denylist else None)
         self._chat_stores: dict[str, ChatStore] = {}
         self._audit_store: AuditStore | None = None
         self._bundle_store: BundleStore | None = None
@@ -205,6 +207,7 @@ class NodeDaemon:
                     "gek": gek,
                     "shared_root": shared_root,
                     "index": indexer.index,
+                    "visibility": group_cfg.visibility,
                 }
 
             if not groups_ctx:
@@ -310,8 +313,15 @@ class NodeDaemon:
                         tid = payload.get("target_id", "")
                         if target == "user":
                             denylist.deny_user(tid)
+                        elif target == "group":
+                            # H4: previously dropped on the floor, so "suspend a
+                            # group" was a hub-only gesture that no node enforced.
+                            denylist.deny_group(tid)
+                            self._drop_group_sessions(tid)
                         elif target == "jti":
                             denylist.deny_jti(tid)
+                        else:
+                            log.warning("Unknown revocation target: %r", target)
                     except Exception as e:
                         log.warning("Invalid revocation token: %s", e)
 
@@ -343,9 +353,15 @@ class NodeDaemon:
                      "yes" if self._webrtc else "no",
                      "yes" if self._quic_server else "no")
 
-            # 11. Initial swarm registration
+            # 11. Initial swarm registration — PUBLIC groups only.
+            # Finding H7: registering every group's hashes hands the hub a content
+            # fingerprint of every private file on the node, which is exactly the
+            # metadata the "hub stores no content metadata" claim rules out. It also
+            # lets anyone confirm whether a known file exists in the network.
             endpoint = f"webrtc:{self._config.node.quic_port}"
             for gctx in groups_ctx.values():
+                if gctx.get("visibility") != "public":
+                    continue
                 hashes = [e.id for e in gctx["index"].entries]
                 if hashes:
                     asyncio.ensure_future(self._register_swarm(hashes, endpoint))
@@ -462,13 +478,25 @@ class NodeDaemon:
             if pushed:
                 log.info("Index pushed to %d WebRTC peers", pushed)
 
-        # 11.9 — Register file hashes with hub swarm table
-        if self._hub and self._state.get("endpoint_hint"):
+        # 11.9 — Register file hashes with hub swarm table (public groups only, H7)
+        group_cfg = next(
+            (g for g in self._config.groups if g.id == group_id), None)
+        if (self._hub and self._state.get("endpoint_hint")
+                and group_cfg and group_cfg.visibility == "public"):
             hashes = [e.id for e in idx.entries]
             if hashes:
                 endpoint = f"webrtc:{self._config.node.quic_port}"
                 asyncio.ensure_future(self._register_swarm(hashes, endpoint))
 
+    def _drop_group_sessions(self, group_id: str) -> None:
+        """Close live sessions for a revoked group (H4)."""
+        if not self._webrtc or not group_id:
+            return
+        for session in list(self._webrtc._sessions.values()):
+            if session._group_id == group_id:
+                asyncio.ensure_future(session.close())
+                log.info("Dropped session for revoked group %s", group_id[:8])
+
     async def _register_swarm(self, hashes: list[str], endpoint: str) -> None:
         try:
             n = await self._hub.register_swarm(hashes, endpoint)
diff --git a/packages/meshbay-node/src/meshbay_node/keystore.py b/packages/meshbay-node/src/meshbay_node/keystore.py
index 3777af0..59fc719 100644
--- a/packages/meshbay-node/src/meshbay_node/keystore.py
+++ b/packages/meshbay-node/src/meshbay_node/keystore.py
@@ -39,6 +39,12 @@ from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
 from cryptography.hazmat.primitives.asymmetric.x25519 import X25519PrivateKey
 
 from meshbay_common.crypto import (
+    ARGON2_ITERATIONS,
+    ARGON2_LANES,
+    ARGON2_MEMORY_COST,
+    LEGACY_ARGON2_ITERATIONS,
+    LEGACY_ARGON2_LANES,
+    LEGACY_ARGON2_MEMORY_COST,
     decrypt_keystore,
     derive_keystore_key,
     encrypt_keystore,
@@ -173,7 +179,18 @@ def load_keystore(
     tag  = base64.b64decode(envelope["tag_b64"])
     ct   = base64.b64decode(envelope["ciphertext_b64"])
 
-    aes_key = derive_keystore_key(pwd, salt)
+    # Envelopes written before M2 carry no parameters and used the 64 MB profile.
+    params = envelope.get("argon2", {
+        "iterations":  LEGACY_ARGON2_ITERATIONS,
+        "memory_cost": LEGACY_ARGON2_MEMORY_COST,
+        "lanes":       LEGACY_ARGON2_LANES,
+    })
+    aes_key = derive_keystore_key(
+        pwd, salt,
+        iterations=params.get("iterations"),
+        memory_cost=params.get("memory_cost"),
+        lanes=params.get("lanes"),
+    )
     try:
         plaintext = decrypt_keystore(iv, ct, tag, aes_key)
     except Exception:
@@ -205,6 +222,12 @@ def _write_keystore(path: Path, keys: NodeKeys, password: str) -> None:
     envelope = {
         "version":         KEYSTORE_VERSION,
         "argon2_salt_b64": base64.b64encode(salt).decode(),
+        # Recorded so parameters can be raised later without orphaning this file.
+        "argon2": {
+            "iterations":  ARGON2_ITERATIONS,
+            "memory_cost": ARGON2_MEMORY_COST,
+            "lanes":       ARGON2_LANES,
+        },
         "iv_b64":          base64.b64encode(iv).decode(),
         "tag_b64":         base64.b64encode(tag).decode(),
         "ciphertext_b64":  base64.b64encode(ct).decode(),
diff --git a/packages/meshbay-node/src/meshbay_node/transport/quic_server.py b/packages/meshbay-node/src/meshbay_node/transport/quic_server.py
index ede756e..7bb6ce5 100644
--- a/packages/meshbay-node/src/meshbay_node/transport/quic_server.py
+++ b/packages/meshbay-node/src/meshbay_node/transport/quic_server.py
@@ -50,22 +50,69 @@ ALPN       = ["meshbay-mnp"]
 
 
 class Denylist:
-    """Shared denylist for revoked users and invalidated JWTs."""
+    """
+    Denylist for revoked users, groups and invalidated JWTs.
 
-    def __init__(self):
+    Finding H4: revocations used to live only in memory, so a node restart silently
+    un-revoked everyone, and group revocations were dropped entirely — the hub
+    signed and broadcast them but the node's handler only understood "user" and
+    "jti". Now persisted to disk and group targets are honoured.
+    """
+
+    def __init__(self, path: Path | None = None):
         self.user_ids: set[str] = set()
+        self.group_ids: set[str] = set()
         self.jtis: set[str] = set()
+        self._path = path
+        self._load()
 
-    def is_denied(self, user_id: str, jti: str) -> bool:
-        return user_id in self.user_ids or jti in self.jtis
+    def is_denied(self, user_id: str, jti: str, group_id: str = "") -> bool:
+        return (user_id in self.user_ids
+                or jti in self.jtis
+                or (bool(group_id) and group_id in self.group_ids))
 
     def deny_user(self, user_id: str) -> None:
         self.user_ids.add(user_id)
         log.info("Denied user: %s", user_id[:8])
+        self._save()
+
+    def deny_group(self, group_id: str) -> None:
+        self.group_ids.add(group_id)
+        log.info("Denied group: %s", group_id[:8])
+        self._save()
 
     def deny_jti(self, jti: str) -> None:
         self.jtis.add(jti)
         log.info("Denied jti: %s", jti[:8])
+        self._save()
+
+    def _load(self) -> None:
+        if not self._path or not self._path.exists():
+            return
+        try:
+            import json
+            data = json.loads(self._path.read_text())
+            self.user_ids = set(data.get("users", []))
+            self.group_ids = set(data.get("groups", []))
+            self.jtis = set(data.get("jtis", []))
+            log.info("Denylist loaded: %d users, %d groups, %d jtis",
+                     len(self.user_ids), len(self.group_ids), len(self.jtis))
+        except Exception as e:
+            log.warning("Could not load denylist from %s: %s", self._path, e)
+
+    def _save(self) -> None:
+        if not self._path:
+            return
+        try:
+            import json
+            self._path.parent.mkdir(parents=True, exist_ok=True)
+            self._path.write_text(json.dumps({
+                "users": sorted(self.user_ids),
+                "groups": sorted(self.group_ids),
+                "jtis": sorted(self.jtis),
+            }))
+        except Exception as e:
+            log.warning("Could not persist denylist to %s: %s", self._path, e)
 
 
 # ── Wire helpers ──────────────────────────────────────────────────────────────
@@ -156,7 +203,8 @@ class _MNPServerProtocol(QuicConnectionProtocol):
             return
 
         denylist = self._ctx.get("denylist")
-        if denylist and denylist.is_denied(decoded.get("sub", ""), decoded.get("jti", "")):
+        if denylist and denylist.is_denied(
+                decoded.get("sub", ""), decoded.get("jti", ""), group_id):
             self._send(stream_id, {"type": "error", "detail": "Token revoked"})
             self._quic.close()
             return
diff --git a/packages/meshbay-node/src/meshbay_node/transport/webrtc_server.py b/packages/meshbay-node/src/meshbay_node/transport/webrtc_server.py
index 9fb9ef2..43e6fdc 100644
--- a/packages/meshbay-node/src/meshbay_node/transport/webrtc_server.py
+++ b/packages/meshbay-node/src/meshbay_node/transport/webrtc_server.py
@@ -241,8 +241,10 @@ class WebRTCPeerSession:
             else:
                 log.warning("Unknown MNP message type on DataChannel: %s", mtype)
         except Exception as e:
-            log.error("Error handling %s on DataChannel: %s", mtype, e)
-            self._send({"type": "error", "detail": str(e)})
+            # Log the detail locally; send the peer a generic message. Exception
+            # text here carries filesystem paths and internal state (finding L3).
+            log.error("Error handling %s on DataChannel: %s", mtype, e, exc_info=True)
+            self._send({"type": "error", "detail": "Request failed"})
 
     def _audit(self, event: str, detail: str = "") -> None:
         audit = self._ctx.get("audit_store")
@@ -269,7 +271,8 @@ class WebRTCPeerSession:
             return
 
         denylist = self._ctx.get("denylist")
-        if denylist and denylist.is_denied(decoded.get("sub", ""), decoded.get("jti", "")):
+        if denylist and denylist.is_denied(
+                decoded.get("sub", ""), decoded.get("jti", ""), group_id):
             self._send({"type": "error", "detail": "Token revoked"})
             return
 
diff --git a/packages/meshbay-node/tests/test_daemon.py b/packages/meshbay-node/tests/test_daemon.py
index 9ebf945..0698104 100644
--- a/packages/meshbay-node/tests/test_daemon.py
+++ b/packages/meshbay-node/tests/test_daemon.py
@@ -228,10 +228,46 @@ async def test_daemon_index_change_pushes_to_peers(tmp_path, shared_dir, gek, hu
     assert msg["group_id"] == "a" * 32
     assert len(msg["entries"]) == indexer.index.count
 
+    # Finding H7: this group is private, so its content hashes must NOT be
+    # registered with the hub. The test previously asserted the opposite —
+    # publishing a fingerprint of every private file was treated as expected
+    # behaviour. Index push to members is unaffected (asserted above).
+    await asyncio.sleep(0.1)
+    daemon._hub.register_swarm.assert_not_called()
+
+@pytest.mark.asyncio
+async def test_daemon_index_change_registers_swarm_for_public_group(
+        tmp_path, shared_dir, gek, hub_pk_pem):
+    """Public groups still register content hashes with the hub swarm (H7)."""
+    config = Config(
+        hub=HubConfig(url="http://localhost:9999", username="testuser"),
+        node=NodeConfig(quic_port=29010, ui_port=28000),
+        groups=[GroupConfig(
+            id="a" * 32,
+            name="public-group",
+            shared_dir=str(shared_dir),
+            visibility="public",
+            quic_port=29010,
+        )],
+        keystore=KeystoreConfig(path=tmp_path / "keystore.enc"),
+        data_dir=tmp_path / "data",
+    )
+    daemon = NodeDaemon(config)
+    daemon._hub = AsyncMock()
+    daemon._hub.register_swarm = AsyncMock(return_value=2)
+    daemon._state["endpoint_hint"] = "node123"
+
+    indexer = DirectoryIndexer(
+        root=shared_dir, group_id="a" * 32,
+        sk_node=Ed25519PrivateKey.generate(), gek=gek)
+    await indexer.initial_scan()
+
+    await daemon._on_index_change(indexer)
+
     await asyncio.sleep(0.1)
     daemon._hub.register_swarm.assert_called_once()
-    call_args = daemon._hub.register_swarm.call_args
-    assert len(call_args[0][0]) == indexer.index.count
+    assert len(daemon._hub.register_swarm.call_args[0][0]) == indexer.index.count
+
 
 @pytest.mark.asyncio
 async def test_daemon_index_change_skips_other_group_peers(
diff --git a/packages/meshbay-node/tests/test_security_regressions.py b/packages/meshbay-node/tests/test_security_regressions.py
index a480d21..9552848 100644
--- a/packages/meshbay-node/tests/test_security_regressions.py
+++ b/packages/meshbay-node/tests/test_security_regressions.py
@@ -348,6 +348,123 @@ def test_admin_challenge_expires(tmp_path):
                for m in session.sent)
 
 
+def test_denylist_persists_and_honours_groups(tmp_path):
+    """
+    H4: revocations lived only in memory, so a node restart silently un-revoked
+    everyone, and 'group' targets were dropped entirely — the hub signed and
+    broadcast them, the node's handler understood only 'user' and 'jti'.
+    """
+    from meshbay_node.transport import Denylist
+
+    path = tmp_path / "denylist.json"
+    first = Denylist(path=path)
+    first.deny_group("g-revoked")
+    first.deny_user("u-revoked")
+    first.deny_jti("j-revoked")
+
+    # A fresh instance stands in for a daemon restart.
+    reloaded = Denylist(path=path)
+    assert reloaded.is_denied("", "", "g-revoked"), "group revocation not honoured"
+    assert reloaded.is_denied("u-revoked", "")
+    assert reloaded.is_denied("", "j-revoked")
+    assert not reloaded.is_denied("someone", "other", "g-allowed")
+
+
+def test_swarm_registration_skips_private_groups():
+    """
+    H7: the daemon registered content hashes for every group, private included,
+    handing the hub a fingerprint of every private file. The bug was masked by a
+    mis-mounted route, so fixing the route without this filter would have turned a
+    dormant leak into a live one.
+    """
+    source = (Path(__file__).parent.parent / "src" / "meshbay_node"
+              / "daemon.py").read_text()
+    assert 'visibility' in source and '_register_swarm' in source
+    # Both registration sites must gate on public visibility.
+    for marker in ['gctx.get("visibility") != "public"',
+                   'group_cfg.visibility == "public"']:
+        assert marker in source, f"swarm registration not gated: {marker}"
+
+
+def test_keystore_argon2_is_production_strength():
+    """M2: the keystore protects the node's private keys and sat at 64 MB."""
+    from meshbay_common.crypto import ARGON2_MEMORY_COST
+    assert ARGON2_MEMORY_COST >= 262144
+
+
+def test_keystore_records_argon2_params_for_migration(tmp_path):
+    """
+    M2: raising the parameters must not orphan existing keystores, so each
+    envelope records the parameters it was written with.
+    """
+    import json
+    from meshbay_node.keystore import create_keystore, load_keystore
+
+    path = tmp_path / "keystore.enc"
+    created = create_keystore(path=path, password="correct horse battery")
+    envelope = json.loads(path.read_text())
+    assert envelope["argon2"]["memory_cost"] >= 262144
+
+    reopened = load_keystore(path=path, password="correct horse battery")
+    assert reopened.pk_ed25519_b64 == created.pk_ed25519_b64
+
+
+def test_legacy_keystore_still_opens(tmp_path):
+    """M2: a keystore written under the 64 MB profile must still unlock."""
+    import base64 as _b64
+    import json
+    import msgpack
+    from cryptography.hazmat.primitives.asymmetric.x25519 import X25519PrivateKey
+    from meshbay_common.crypto import (
+        LEGACY_ARGON2_ITERATIONS, LEGACY_ARGON2_LANES, LEGACY_ARGON2_MEMORY_COST,
+        derive_keystore_key, encrypt_keystore, pk_to_b64, sk_to_b64,
+    )
+    from meshbay_node.keystore import load_keystore
+
+    sk_ed, sk_x = Ed25519PrivateKey.generate(), X25519PrivateKey.generate()
+    payload = msgpack.packb({
+        "sk_ed25519_b64": sk_to_b64(sk_ed),
+        "sk_x25519_b64": sk_to_b64(sk_x),
+    }, use_bin_type=True)
+
+    salt = b"\x01" * 16
+    key = derive_keystore_key(
+        "legacy-pass", salt,
+        iterations=LEGACY_ARGON2_ITERATIONS,
+        memory_cost=LEGACY_ARGON2_MEMORY_COST,
+        lanes=LEGACY_ARGON2_LANES,
+    )
+    iv, ct, tag = encrypt_keystore(payload, key)
+
+    path = tmp_path / "legacy.enc"
+    # No "argon2" key — exactly how pre-M2 envelopes look.
+    path.write_text(json.dumps({
+        "version": 1,
+        "argon2_salt_b64": _b64.b64encode(salt).decode(),
+        "iv_b64": _b64.b64encode(iv).decode(),
+        "tag_b64": _b64.b64encode(tag).decode(),
+        "ciphertext_b64": _b64.b64encode(ct).decode(),
+    }))
+
+    keys = load_keystore(path=path, password="legacy-pass")
+    assert keys.pk_ed25519_b64 == pk_to_b64(sk_ed.public_key())
+    assert keys.pk_x25519_b64 == pk_to_b64(sk_x.public_key())
+
+
+def test_dead_gek_protocol_constants_removed():
+    """L1: the node never serves a GEK; the message types should not suggest it."""
+    from meshbay_common.protocol import MNP
+    assert not hasattr(MNP, "GEK_REQUEST")
+    assert not hasattr(MNP, "GEK_RESPONSE")
+
+
+def test_peer_errors_do_not_leak_internals():
+    """L3: exception text carries filesystem paths and internal state."""
+    source = (Path(__file__).parent.parent / "src" / "meshbay_node"
+              / "transport" / "webrtc_server.py").read_text()
+    assert '"detail": str(e)' not in source
+
+
 def test_admin_ui_escapes_filenames(tmp_path):
     """
     H2: filenames are chosen by any group member and were rendered into the
-- 
cgit v1.2.3


From b86be704df752f2fd3086fcca43b7f4de78389d1 Mon Sep 17 00:00:00 2001
From: Christophe Besson <cbesson@gmail.com>
Date: Thu, 13 Aug 2026 11:18:24 +0200
Subject: fix: resource limits, signaling authz, node admin UI token
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Phase 11.5 — findings H6, C4 (partial), and milestone 11.5.3.

H6 — resource exhaustion. Several paths let one peer degrade or stall a node:

  * the DataChannel frame limit was a flat 64 MB applied BEFORE authentication,
    so an unauthenticated peer could announce a huge frame and dribble bytes
    into it. Unauthenticated peers now get 64 KB; the large budget is granted
    only after the GEK proof, where it is needed for uploads.
  * _do_stream_segment ran subprocess.run(..., timeout=30) directly in the event
    loop, stalling the entire daemon — every peer, every group — for up to
    thirty seconds per request. Now async, with a timeout and process kill.
  * ffmpeg was spawned per stream request with no cap. Both streaming paths now
    share a transport-wide semaphore.
  * POST /v1/nodes/{id}/webrtc/offer was reachable by any authenticated user for
    any node, with no membership check and no rate limit, making the target node
    allocate an aiortc PeerConnection and gather ICE on demand — remote resource
    exhaustion against a third party's machine. Now rate limited, capped per
    user, SDP size bounded, and the caller must share an active group with the
    node. That also closes the H4 gap where signaling ignored group status.
  * POST /v1/nodes/{id}/incoming took peer_ip verbatim, so any user could make an
    arbitrary node emit UDP packets to an address of their choosing. The probe
    target must now match the caller's own source address.

C4 (partial) — the pre-proof bundle window. GEK and keypair bundle fetches are
served before the GEK proof by necessity: the client needs its wrapped bundle in
order to compute the proof. That window is a disclosure surface a hub can reach
by forging a JWT. Bounded to 4 fetches per session and audited as
"pre_proof_fetch". The real fix is removing remote keypair bundles entirely,
which belongs to the native client (Phase 13.3).

11.5.3 — the node admin UI was unauthenticated because it binds loopback. But
any local process can reach it, and so can a page in the operator's browser via
DNS rebinding — and this API re-initialises group keys and reads the audit log.
H2 showed script execution there equals full control. Now gated by a per-run
token, printed at startup, accepted as ?t= or X-MeshBay-Token.

One test needed rewriting rather than adding: the first version asserted
"subprocess.run(" was absent from the source, which also matched the comment
documenting the old behaviour. It now parses the AST and checks the property.

Tests: 121 node, 142 hub+common. Regression suite 47 node + 10 hub.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../meshbay-hub/src/meshbay_hub/api/revocation.py  |  18 ++-
 .../meshbay-hub/src/meshbay_hub/api/signaling.py   |  56 ++++++++-
 packages/meshbay-hub/tests/test_node_ws_auth.py    |  80 +++++++++++++
 packages/meshbay-node/src/meshbay_node/daemon.py   |   9 +-
 .../src/meshbay_node/transport/webrtc_server.py    | 128 +++++++++++++++++----
 packages/meshbay-node/src/meshbay_node/ui/app.py   |  46 ++++++--
 .../tests/test_security_regressions.py             |  75 ++++++++++++
 7 files changed, 380 insertions(+), 32 deletions(-)

(limited to 'packages/meshbay-node/tests/test_security_regressions.py')

diff --git a/packages/meshbay-hub/src/meshbay_hub/api/revocation.py b/packages/meshbay-hub/src/meshbay_hub/api/revocation.py
index 0f1ddba..2e3323c 100644
--- a/packages/meshbay-hub/src/meshbay_hub/api/revocation.py
+++ b/packages/meshbay-hub/src/meshbay_hub/api/revocation.py
@@ -33,7 +33,7 @@ import time
 import uuid
 from typing import Any
 
-from fastapi import APIRouter, Depends, HTTPException, WebSocket, WebSocketDisconnect
+from fastapi import APIRouter, Depends, HTTPException, Request, WebSocket, WebSocketDisconnect
 from pydantic import BaseModel
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
@@ -274,12 +274,28 @@ class IncomingRequest(BaseModel):
 async def notify_incoming(
     node_id: str,
     body: IncomingRequest,
+    request: Request,
     current_user: User = Depends(get_current_user),
 ):
     """
     Signal a node that a client wants to connect (NAT punch coordination).
     Hub forwards the request via WebSocket; node punches NAT and replies punch_ready.
+
+    Finding H6: peer_ip was taken verbatim, so any authenticated user could make an
+    arbitrary node emit UDP packets to an address of their choosing — a small
+    reflection primitive using someone else's machine. The probe target must now be
+    the caller's own source address.
     """
+    from meshbay_hub.api.netutil import client_ip
+
+    caller_ip = client_ip(request)
+    if body.peer_ip != caller_ip:
+        raise HTTPException(
+            status_code=403,
+            detail="peer_ip must match the requesting address")
+    if not (1 <= body.peer_port <= 65535):
+        raise HTTPException(status_code=422, detail="Invalid peer_port")
+
     ws = _connected_nodes.get(node_id)
     if not ws:
         raise HTTPException(status_code=404, detail="Node not connected")
diff --git a/packages/meshbay-hub/src/meshbay_hub/api/signaling.py b/packages/meshbay-hub/src/meshbay_hub/api/signaling.py
index bd343c9..8f84163 100644
--- a/packages/meshbay-hub/src/meshbay_hub/api/signaling.py
+++ b/packages/meshbay-hub/src/meshbay_hub/api/signaling.py
@@ -17,11 +17,15 @@ import json
 import logging
 import uuid
 
-from fastapi import APIRouter, Depends, HTTPException
+from fastapi import APIRouter, Depends, HTTPException, Request
 from pydantic import BaseModel
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
 
 from meshbay_hub.api.deps import get_current_user
-from meshbay_hub.db.models import User
+from meshbay_hub.api.middleware import limiter
+from meshbay_hub.db.engine import get_db
+from meshbay_hub.db.models import Group, GroupMember, User
 
 log = logging.getLogger(__name__)
 
@@ -41,25 +45,66 @@ class WebRTCOfferResponse(BaseModel):
     peer_id: str
 
 
+MAX_SDP_BYTES = 16 * 1024          # an SDP offer is ~2 KB
+MAX_PENDING_PER_USER = 3           # concurrent in-flight offers per account
+
+_pending_per_user: dict[str, int] = {}
+
+
 @router.post("/{node_id}/webrtc/offer", response_model=WebRTCOfferResponse)
+@limiter.limit("30/minute")
 async def webrtc_offer(
     node_id: str,
     body: WebRTCOfferRequest,
+    request: Request,
     current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
 ):
     """
     Browser sends WebRTC SDP offer for a node. Hub relays via WebSocket.
     Returns the node's SDP answer once received.
+
+    Finding H6: this was reachable by any authenticated user, for any node, with no
+    rate limit and no membership check. Each call makes the node allocate an
+    aiortc RTCPeerConnection and gather ICE, so it was a remote resource-exhaustion
+    primitive against an arbitrary third party's machine.
+
+    Finding H4: it also ignored group status, so "suspend a group" did not stop new
+    connections from being brokered to nodes hosting it.
     """
-    from meshbay_hub.api.revocation import _connected_nodes
+    from meshbay_hub.api.revocation import _connected_nodes, _node_groups
+
+    if len(body.sdp) > MAX_SDP_BYTES:
+        raise HTTPException(status_code=413, detail="SDP too large")
 
     ws = _connected_nodes.get(node_id)
     if not ws:
         raise HTTPException(status_code=404, detail="Node not connected")
 
+    # The caller must share at least one active group with the target node.
+    node_group_ids = set(_node_groups.get(node_id, []))
+    if node_group_ids:
+        result = await db.execute(
+            select(GroupMember.group_id).where(
+                GroupMember.user_id == current_user.id,
+                GroupMember.group_id.in_(node_group_ids),
+            ))
+        shared = [gid for (gid,) in result.all()]
+        if not shared:
+            raise HTTPException(status_code=403, detail="Not a member of any group on this node")
+
+        active = await db.execute(
+            select(Group.id).where(Group.id.in_(shared), Group.status == "active"))
+        if not active.first():
+            raise HTTPException(status_code=403, detail="Group is not active")
+
+    if _pending_per_user.get(current_user.id, 0) >= MAX_PENDING_PER_USER:
+        raise HTTPException(status_code=429, detail="Too many pending connections")
+
     peer_id = str(uuid.uuid4())
     answer_future: asyncio.Future = asyncio.get_event_loop().create_future()
     _webrtc_answers[peer_id] = answer_future
+    _pending_per_user[current_user.id] = _pending_per_user.get(current_user.id, 0) + 1
 
     try:
         await ws.send_text(json.dumps({
@@ -83,6 +128,11 @@ async def webrtc_offer(
         )
     finally:
         _webrtc_answers.pop(peer_id, None)
+        remaining = _pending_per_user.get(current_user.id, 1) - 1
+        if remaining > 0:
+            _pending_per_user[current_user.id] = remaining
+        else:
+            _pending_per_user.pop(current_user.id, None)
 
 
 def handle_webrtc_answer(msg: dict) -> None:
diff --git a/packages/meshbay-hub/tests/test_node_ws_auth.py b/packages/meshbay-hub/tests/test_node_ws_auth.py
index 6db95d7..9ec251d 100644
--- a/packages/meshbay-hub/tests/test_node_ws_auth.py
+++ b/packages/meshbay-hub/tests/test_node_ws_auth.py
@@ -149,6 +149,86 @@ async def test_ws_group_claims_cannot_widen_beyond_membership(client):
     assert groups == [own_group], "node advertised a group it is not a member of"
 
 
+@pytest.mark.asyncio
+async def test_signaling_rejects_non_member(client):
+    """
+    H6/H4: POST /v1/nodes/{id}/webrtc/offer was reachable by any authenticated
+    user for any node, with no membership check and no rate limit. Each call makes
+    the target node allocate an aiortc PeerConnection and gather ICE, so it was a
+    remote resource-exhaustion primitive against a third party's machine.
+    """
+    from meshbay_hub.api import revocation as rev
+
+    owner = await _make_user(client, "owner8")
+    outsider = await _make_user(client, "outsider8")
+    node_id = await _announce_node(client, owner)
+
+    r = await client.post(
+        "/v1/groups",
+        json={"name": "private-g", "visibility": "private", "join_policy": "invite"},
+        headers={"Authorization": f"Bearer {owner['token']}"},
+    )
+    group_id = r.json()["group_id"]
+
+    # Pretend the node is connected and hosting that group.
+    class _FakeWS:
+        async def send_text(self, _):
+            raise AssertionError("offer relayed to node despite non-membership")
+
+    rev._connected_nodes[node_id] = _FakeWS()
+    rev._node_groups[node_id] = [group_id]
+    try:
+        resp = await client.post(
+            f"/v1/nodes/{node_id}/webrtc/offer",
+            json={"sdp": "v=0", "ice_candidates": []},
+            headers={"Authorization": f"Bearer {outsider['token']}"},
+        )
+        assert resp.status_code == 403, resp.text
+    finally:
+        rev._connected_nodes.pop(node_id, None)
+        rev._node_groups.pop(node_id, None)
+
+
+@pytest.mark.asyncio
+async def test_signaling_rejects_oversized_sdp(client):
+    """H6: an SDP offer is ~2 KB; unbounded input is a memory amplifier."""
+    user = await _make_user(client, "user9")
+    resp = await client.post(
+        "/v1/nodes/whatever/webrtc/offer",
+        json={"sdp": "v=0" + ("x" * 200_000), "ice_candidates": []},
+        headers={"Authorization": f"Bearer {user['token']}"},
+    )
+    assert resp.status_code == 413
+
+
+@pytest.mark.asyncio
+async def test_incoming_rejects_foreign_peer_ip(client):
+    """
+    H6: peer_ip was taken verbatim, letting any user make an arbitrary node emit
+    UDP packets to an address of their choosing — reflection via someone else's
+    machine. The probe target must be the caller's own address.
+    """
+    from meshbay_hub.api import revocation as rev
+
+    owner = await _make_user(client, "owner10")
+    node_id = await _announce_node(client, owner)
+
+    class _FakeWS:
+        async def send_text(self, _):
+            raise AssertionError("punch relayed with attacker-chosen peer_ip")
+
+    rev._connected_nodes[node_id] = _FakeWS()
+    try:
+        resp = await client.post(
+            f"/v1/nodes/{node_id}/incoming",
+            json={"peer_ip": "198.51.100.7", "peer_port": 9999},
+            headers={"Authorization": f"Bearer {owner['token']}"},
+        )
+        assert resp.status_code == 403, resp.text
+    finally:
+        rev._connected_nodes.pop(node_id, None)
+
+
 @pytest.mark.asyncio
 async def test_ws_node_may_narrow_its_group_set(client):
     """A node hosting a subset of the operator's groups may say so."""
diff --git a/packages/meshbay-node/src/meshbay_node/daemon.py b/packages/meshbay-node/src/meshbay_node/daemon.py
index 7dedad8..fa8c0ee 100644
--- a/packages/meshbay-node/src/meshbay_node/daemon.py
+++ b/packages/meshbay-node/src/meshbay_node/daemon.py
@@ -26,6 +26,7 @@ import asyncio
 import base64
 import json
 import logging
+import os
 import signal
 import sys
 from pathlib import Path
@@ -130,6 +131,11 @@ class NodeDaemon:
         # 2. Start admin UI early (so operator can copy node key before hub login)
         self._state["pk_node_ed25519"] = keys.pk_ed25519_b64
         self._state["config"] = self._config
+        # Per-run token for the local admin UI (11.5.3). Not a password: it keeps
+        # other local processes and rebound browser pages out of an API that can
+        # re-initialise group keys.
+        ui_token = base64.urlsafe_b64encode(os.urandom(18)).decode().rstrip("=")
+        self._state["ui_token"] = ui_token
         from meshbay_node.ui import create_ui_app
         ui_app = create_ui_app(self._state)
         ui_cfg = uvicorn.Config(
@@ -140,7 +146,8 @@ class NodeDaemon:
         )
         ui_server = uvicorn.Server(ui_cfg)
         self._tasks.append(asyncio.create_task(ui_server.serve()))
-        log.info("Admin UI at http://localhost:%d", self._config.node.ui_port)
+        log.info("Admin UI at http://127.0.0.1:%d/?t=%s",
+                 self._config.node.ui_port, ui_token)
 
         # 3. Hub connection (Ed25519 auth — retries until node key is linked)
         hub_cfg = HubConfig(
diff --git a/packages/meshbay-node/src/meshbay_node/transport/webrtc_server.py b/packages/meshbay-node/src/meshbay_node/transport/webrtc_server.py
index 43e6fdc..190d580 100644
--- a/packages/meshbay-node/src/meshbay_node/transport/webrtc_server.py
+++ b/packages/meshbay-node/src/meshbay_node/transport/webrtc_server.py
@@ -64,6 +64,16 @@ MAX_MSG = 64 * 1024 * 1024
 # node sovereignty and defeated the delete authorization (overwrite a file, become its
 # recorded uploader, then delete it legitimately).
 MAX_UPLOAD_BYTES = 4 * 1024 * 1024 * 1024   # 4 GB per file
+
+# Budget for an unauthenticated peer: enough for a handshake and a bundle fetch,
+# nowhere near enough to be a memory-exhaustion primitive (H6).
+PRE_HANDSHAKE_MAX_MSG = 64 * 1024
+# ffmpeg is spawned per stream request; without a cap any member can fork-bomb
+# the node by requesting many streams at once (H6).
+MAX_CONCURRENT_TRANSCODES = 2
+# Bundle fetches are served in the pre-proof window (C4). Bounded and audited
+# until the native client removes remote keypair bundles entirely.
+MAX_PRE_PROOF_FETCHES = 4
 UPLOAD_DIR_NAME = ".uploads"
 # Conservative allowlist: also what keeps markup out of filenames, which the node admin
 # UI used to render unescaped (finding H2).
@@ -137,10 +147,18 @@ def _pack(obj: dict) -> bytes:
 
 
 class _DataChannelBuffer:
-    """Accumulate DataChannel messages and extract length-prefixed msgpack."""
+    """
+    Accumulate DataChannel messages and extract length-prefixed msgpack.
+
+    Finding H6: the limit was a flat 64 MB applied even before the handshake, so an
+    unauthenticated peer could announce a 64 MB frame and dribble bytes into it,
+    holding that much memory per connection. Until a peer has proved GEK
+    possession it gets a small budget; the large one is for file uploads.
+    """
 
-    def __init__(self):
+    def __init__(self, max_message: int = MAX_MSG):
         self._buf = bytearray()
+        self.max_message = max_message
 
     def feed(self, data: bytes):
         self._buf.extend(data)
@@ -148,7 +166,7 @@ class _DataChannelBuffer:
     def messages(self):
         while len(self._buf) >= 4:
             length = struct.unpack(">I", self._buf[:4])[0]
-            if length > MAX_MSG:
+            if length > self.max_message:
                 raise ValueError(f"Message too large: {length}")
             if len(self._buf) < 4 + length:
                 break
@@ -180,7 +198,8 @@ class WebRTCPeerSession:
         self._pc = pc
         self._ctx = node_ctx
         self._channel: RTCDataChannel | None = None
-        self._buffer = _DataChannelBuffer()
+        self._buffer = _DataChannelBuffer(max_message=PRE_HANDSHAKE_MAX_MSG)
+        self._pre_proof_fetches = 0
         self._user_id: str | None = None
         self._group_id: str | None = None
         self._peer_id: str = peer_id
@@ -210,10 +229,24 @@ class WebRTCPeerSession:
                 self._do_handshake(msg)
             elif mtype == MNP.HANDSHAKE_RESPONSE:
                 self._do_handshake_response(msg)
-            elif mtype == MNP.GEK_BUNDLE_FETCH and self._gek_challenge is not None:
-                asyncio.ensure_future(self._do_gek_bundle_fetch())
-            elif mtype == MNP.KEYPAIR_BUNDLE_FETCH and self._gek_challenge is not None:
-                asyncio.ensure_future(self._do_keypair_bundle_fetch())
+            elif mtype in (MNP.GEK_BUNDLE_FETCH, MNP.KEYPAIR_BUNDLE_FETCH) \
+                    and self._gek_challenge is not None:
+                # Served before the GEK proof by necessity: the client needs its
+                # wrapped bundle in order to compute the proof. That window is a
+                # disclosure surface (C4) — a hub that forges a JWT reaches it — so
+                # it is bounded and audited here, and closed properly when clients
+                # stop storing keypair bundles on other people's nodes.
+                self._pre_proof_fetches += 1
+                if self._pre_proof_fetches > MAX_PRE_PROOF_FETCHES:
+                    self._audit_auth_failed(
+                        getattr(self, "_pending_group", ""), "pre-proof fetch flood")
+                    self._send({"type": "error", "detail": "Too many requests"})
+                    return
+                self._audit_pre_proof_fetch(mtype)
+                if mtype == MNP.GEK_BUNDLE_FETCH:
+                    asyncio.ensure_future(self._do_gek_bundle_fetch())
+                else:
+                    asyncio.ensure_future(self._do_keypair_bundle_fetch())
             elif self._user_id is None:
                 self._send({"type": "error", "detail": "Handshake required"})
             elif mtype == MNP.INDEX_SYNC:
@@ -357,6 +390,9 @@ class WebRTCPeerSession:
         self._complete_handshake()
 
     def _complete_handshake(self) -> None:
+        # Authenticated peers may send large frames (file uploads); unauthenticated
+        # ones may not (H6).
+        self._buffer.max_message = MAX_MSG
         self._user_id = self._pending_sub
         self._group_id = self._pending_group
         self._username = self._pending_username
@@ -496,6 +532,20 @@ class WebRTCPeerSession:
             "detail": "keypair_bundle_stored",
         })
 
+    def _audit_pre_proof_fetch(self, mtype: str) -> None:
+        """Record bundle access made before the GEK proof (C4)."""
+        audit = self._ctx.get("audit_store")
+        if not audit:
+            return
+        self._remote_ip = self._remote_ip or _get_remote_ip(self._pc)
+        asyncio.ensure_future(audit.log_event(
+            user_id=getattr(self, "_pending_sub", "unknown"),
+            event="pre_proof_fetch",
+            ip=self._remote_ip,
+            group_id=getattr(self, "_pending_group", "") or "",
+            detail=mtype,
+        ))
+
     def _audit_auth_failed(self, group_id: str, reason: str) -> None:
         audit = self._ctx.get("audit_store")
         if audit:
@@ -574,6 +624,17 @@ class WebRTCPeerSession:
             self._audit("file_download", entry.name)
 
     def _do_stream_segment(self, msg: dict) -> None:
+        asyncio.ensure_future(self._do_stream_segment_async(msg))
+
+    async def _do_stream_segment_async(self, msg: dict) -> None:
+        """
+        Legacy HLS segment extraction (superseded by stream_req/MSE).
+
+        Finding H6: this ran subprocess.run(..., timeout=30) directly inside the
+        event loop, so a single request stalled the whole daemon — every peer,
+        every group — for up to thirty seconds. Now async and under the same
+        transcode semaphore as _stream_video.
+        """
         ctx = self._group_ctx()
         file_id = msg["file_id"]
         segment_index = msg["segment_index"]
@@ -589,21 +650,34 @@ class WebRTCPeerSession:
             self._send({"type": "error", "detail": "File not on disk"})
             return
 
-        import subprocess
+        sem = self._ctx.get("_transcode_sem")
+        if sem is None:
+            sem = asyncio.Semaphore(MAX_CONCURRENT_TRANSCODES)
+            self._ctx["_transcode_sem"] = sem
+
         try:
-            result = subprocess.run(
-                ["ffmpeg", "-hide_banner", "-loglevel", "error",
-                 "-ss", str(segment_index * segment_duration),
-                 "-i", str(file_path),
-                 "-t", str(segment_duration),
-                 "-c:v", "copy", "-c:a", "copy",
-                 "-f", "mpegts", "pipe:1"],
-                capture_output=True, timeout=30,
-            )
-            if result.returncode != 0 or not result.stdout:
+            async with sem:
+                proc = await asyncio.create_subprocess_exec(
+                    "ffmpeg", "-hide_banner", "-loglevel", "error",
+                    "-ss", str(segment_index * segment_duration),
+                    "-i", str(file_path),
+                    "-t", str(segment_duration),
+                    "-c:v", "copy", "-c:a", "copy",
+                    "-f", "mpegts", "pipe:1",
+                    stdout=asyncio.subprocess.PIPE,
+                    stderr=asyncio.subprocess.DEVNULL,
+                )
+                try:
+                    stdout, _ = await asyncio.wait_for(proc.communicate(), timeout=30)
+                except asyncio.TimeoutError:
+                    proc.kill()
+                    await proc.wait()
+                    self._send({"type": "error", "detail": "Segment extraction timed out"})
+                    return
+            if proc.returncode != 0 or not stdout:
                 self._send({"type": "error", "detail": "Segment extraction failed"})
                 return
-            segment_data = result.stdout
+            segment_data = stdout
         except Exception:
             self._send({"type": "error", "detail": "Segment extraction failed"})
             return
@@ -963,6 +1037,20 @@ class WebRTCPeerSession:
 
     async def _stream_video(self, msg: dict) -> None:
         """Stream a video file as fMP4 segments via MSE-compatible output."""
+        # One ffmpeg per request with no cap lets any member exhaust the node's
+        # CPU and process table (H6). The semaphore lives on the transport context
+        # so it is shared across all peers, not per-session.
+        sem = self._ctx.get("_transcode_sem")
+        if sem is None:
+            sem = asyncio.Semaphore(MAX_CONCURRENT_TRANSCODES)
+            self._ctx["_transcode_sem"] = sem
+        if sem.locked() and sem._value <= 0:
+            self._send({"type": "error", "detail": "Server busy, retry shortly"})
+            return
+        async with sem:
+            await self._stream_video_inner(msg)
+
+    async def _stream_video_inner(self, msg: dict) -> None:
         ctx = self._group_ctx()
         file_id = msg.get("file_id", "")
         entry = ctx["index"].get_entry(file_id)
diff --git a/packages/meshbay-node/src/meshbay_node/ui/app.py b/packages/meshbay-node/src/meshbay_node/ui/app.py
index d2c3429..21e4445 100644
--- a/packages/meshbay-node/src/meshbay_node/ui/app.py
+++ b/packages/meshbay-node/src/meshbay_node/ui/app.py
@@ -9,7 +9,7 @@ FastAPI app providing:
   - API endpoints for all data (JSON)
 
 Served only on 127.0.0.1 — not exposed to the network.
-No authentication required (localhost only).
+Gated by a per-run session token (11.5.3) — printed at daemon startup.
 """
 
 import base64
@@ -36,6 +36,28 @@ def create_ui_app(state: dict) -> FastAPI:
         redoc_url=None,
     )
 
+    @app.middleware("http")
+    async def _require_session_token(request, call_next):
+        """
+        Gate the admin UI behind a per-run token (11.5.3).
+
+        "localhost only" is weaker than it sounds: any process on the machine can
+        reach it, and a page in the operator's browser can reach it too via DNS
+        rebinding. Since this API can re-initialise a group's GEK and read the
+        audit log, an unauthenticated loopback service is a privilege boundary
+        waiting to be crossed. The token is printed at startup and accepted as
+        ?t= or the X-MeshBay-Token header.
+        """
+        from fastapi.responses import PlainTextResponse
+
+        token = state.get("ui_token")
+        if token:
+            supplied = (request.query_params.get("t")
+                        or request.headers.get("X-MeshBay-Token"))
+            if supplied != token:
+                return PlainTextResponse("Forbidden", status_code=403)
+        return await call_next(request)
+
     @app.middleware("http")
     async def _security_headers(request, call_next):
         """
@@ -340,7 +362,7 @@ def create_ui_app(state: dict) -> FastAPI:
 
     @app.get("/audit", response_class=HTMLResponse)
     async def audit_page():
-        return _render_audit_page()
+        return _render_audit_page(state.get("ui_token", ""))
 
     return app
 
@@ -356,6 +378,7 @@ def _fmt_size(n: int) -> str:
 
 
 def _render_page(state: dict) -> str:
+    token_js = json.dumps(state.get("ui_token", ""))
     status = state.get("status", "starting")
     indexes = state.get("indexes", {})
     groups_ctx = state.get("groups_ctx", {})
@@ -552,13 +575,14 @@ def _render_page(state: dict) -> str:
   </div>
 </div>
 <script>
+const TOKEN = {token_js};
 async function initGEK(groupId) {{
   const btn = document.getElementById('gek-btn-' + groupId.slice(0,8));
   const status = document.getElementById('gek-status-' + groupId.slice(0,8));
   if (btn) btn.disabled = true;
   if (status) status.textContent = 'Initializing...';
   try {{
-    const resp = await fetch('/api/groups/' + groupId + '/gek', {{ method: 'POST' }});
+    const resp = await fetch('/api/groups/' + groupId + '/gek?t=' + TOKEN, {{ method: 'POST' }});
     const data = await resp.json();
     if (resp.ok) {{
       if (status) status.textContent = 'GEK initialized — wrapped for '
@@ -582,8 +606,11 @@ setTimeout(()=>location.reload(), 10000);
 </html>"""
 
 
-def _render_audit_page() -> str:
-    return """<!DOCTYPE html>
+def _render_audit_page(token: str = "") -> str:
+    return _AUDIT_HTML.replace("__TOKEN__", json.dumps(token))
+
+
+_AUDIT_HTML = """<!DOCTYPE html>
 <html lang="en">
 <head>
 <meta charset="utf-8">
@@ -619,7 +646,7 @@ def _render_audit_page() -> str:
 <body>
 <div class="container">
   <h1>Audit Log</h1>
-  <nav><a href="/">Dashboard</a><a href="/audit">Audit Log</a></nav>
+  <nav><a id="navHome" href="/">Dashboard</a><a id="navAudit" href="/audit">Audit Log</a></nav>
 
   <div class="filters">
     <select id="eventFilter">
@@ -648,10 +675,11 @@ def _render_audit_page() -> str:
   </table>
 </div>
 <script>
+const TOKEN = __TOKEN__;
 async function load() {
   const ev = document.getElementById('eventFilter').value;
   const limit = document.getElementById('limitSelect').value;
-  let url = '/api/audit?limit=' + limit;
+  let url = '/api/audit?limit=' + limit + (TOKEN ? '&t=' + TOKEN : '');
   if (ev) url += '&event=' + ev;
   const r = await fetch(url);
   const data = await r.json();
@@ -677,6 +705,10 @@ async function load() {
     return tr;
   }));
 }
+for (const [id, href] of [['navHome','/'],['navAudit','/audit']]) {
+  const el = document.getElementById(id);
+  if (el && TOKEN) el.href = href + '?t=' + TOKEN;
+}
 document.getElementById('eventFilter').onchange = load;
 document.getElementById('limitSelect').onchange = load;
 let debounceTimer;
diff --git a/packages/meshbay-node/tests/test_security_regressions.py b/packages/meshbay-node/tests/test_security_regressions.py
index 9552848..a6d69c6 100644
--- a/packages/meshbay-node/tests/test_security_regressions.py
+++ b/packages/meshbay-node/tests/test_security_regressions.py
@@ -10,6 +10,7 @@ If one of these starts failing, a fix has been reverted. Do not "fix" the test.
 """
 
 import base64
+import struct
 from pathlib import Path
 
 import pytest
@@ -465,6 +466,80 @@ def test_peer_errors_do_not_leak_internals():
     assert '"detail": str(e)' not in source
 
 
+def test_pre_handshake_message_budget_is_small():
+    """
+    H6: the frame limit was a flat 64 MB applied before authentication, so an
+    unauthenticated peer could announce a huge frame and dribble bytes into it.
+    """
+    from meshbay_node.transport.webrtc_server import (
+        MAX_MSG, PRE_HANDSHAKE_MAX_MSG, _DataChannelBuffer,
+    )
+    assert PRE_HANDSHAKE_MAX_MSG <= 1024 * 1024
+    assert PRE_HANDSHAKE_MAX_MSG < MAX_MSG
+
+    buf = _DataChannelBuffer(max_message=PRE_HANDSHAKE_MAX_MSG)
+    buf.feed(struct.pack(">I", PRE_HANDSHAKE_MAX_MSG + 1) + b"x")
+    with pytest.raises(ValueError):
+        list(buf.messages())
+
+
+def test_stream_segment_is_not_synchronous():
+    """
+    H6: _do_stream_segment ran subprocess.run(timeout=30) inside the event loop,
+    stalling every peer on the node for up to thirty seconds per request.
+
+    Asserts the property (the worker is a coroutine, ffmpeg is spawned through
+    asyncio) rather than grepping for "subprocess.run" — which also matches the
+    comment that documents the old behaviour.
+    """
+    import ast
+    import inspect
+    from meshbay_node.transport.webrtc_server import WebRTCPeerSession
+
+    assert inspect.iscoroutinefunction(WebRTCPeerSession._do_stream_segment_async)
+
+    source = (Path(__file__).parent.parent / "src" / "meshbay_node"
+              / "transport" / "webrtc_server.py").read_text()
+    tree = ast.parse(source)
+    blocking = [
+        node for node in ast.walk(tree)
+        if isinstance(node, ast.Call)
+        and isinstance(node.func, ast.Attribute)
+        and node.func.attr == "run"
+        and isinstance(node.func.value, ast.Name)
+        and node.func.value.id == "subprocess"
+    ]
+    assert not blocking, "blocking subprocess.run() in the event loop"
+    assert "_transcode_sem" in source, "ffmpeg spawns must be capped"
+
+
+def test_pre_proof_fetches_are_bounded():
+    """C4: the pre-proof bundle window is a disclosure surface; bound it."""
+    from meshbay_node.transport.webrtc_server import MAX_PRE_PROOF_FETCHES
+    assert 0 < MAX_PRE_PROOF_FETCHES <= 10
+
+
+def test_node_admin_ui_requires_token():
+    """
+    11.5.3: "localhost only" is not authentication. Any local process — or a
+    rebound browser page — could re-initialise a group's GEK and read the audit log.
+    """
+    from fastapi.testclient import TestClient
+    from meshbay_node.ui.app import create_ui_app
+
+    app = create_ui_app({"status": "running", "groups_ctx": {},
+                         "indexes": {}, "ui_token": "secret-token"})
+    client = TestClient(app)
+
+    assert client.get("/api/status").status_code == 403
+    assert client.get("/api/status?t=wrong").status_code == 403
+    assert client.get("/api/config?t=wrong").status_code == 403
+    assert client.get("/api/status?t=secret-token").status_code == 200
+    assert client.get(
+        "/api/status", headers={"X-MeshBay-Token": "secret-token"}
+    ).status_code == 200
+
+
 def test_admin_ui_escapes_filenames(tmp_path):
     """
     H2: filenames are chosen by any group member and were rendered into the
-- 
cgit v1.2.3


From e13659f8f3166b5a9a4155314941bc149fec2721 Mon Sep 17 00:00:00 2001
From: Christophe Besson <cbesson@gmail.com>
Date: Thu, 13 Aug 2026 11:46:12 +0200
Subject: feat(mnp): unified handshake with mutual authentication
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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>
---
 .../meshbay-common/src/meshbay_common/handshake.py | 203 +++++++++++++++++++++
 packages/meshbay-common/tests/test_handshake.py    | 199 ++++++++++++++++++++
 .../meshbay-hub/src/meshbay_hub/static/crypto.js   |  66 ++++++-
 .../src/meshbay_hub/static/transport.js            |  54 ++++--
 .../src/meshbay_node/transport/webrtc_server.py    | 144 +++++++++------
 .../tests/test_security_regressions.py             |  15 +-
 .../meshbay-node/tests/test_webrtc_transport.py    | 122 ++++++++-----
 7 files changed, 680 insertions(+), 123 deletions(-)
 create mode 100644 packages/meshbay-common/src/meshbay_common/handshake.py
 create mode 100644 packages/meshbay-common/tests/test_handshake.py

(limited to 'packages/meshbay-node/tests/test_security_regressions.py')

diff --git a/packages/meshbay-common/src/meshbay_common/handshake.py b/packages/meshbay-common/src/meshbay_common/handshake.py
new file mode 100644
index 0000000..73a2858
--- /dev/null
+++ b/packages/meshbay-common/src/meshbay_common/handshake.py
@@ -0,0 +1,203 @@
+"""
+Unified MNP handshake — one implementation, every transport.
+
+Finding C6: the handshake existed three times over (WebRTC, QUIC, TCP), and only
+the newest copy enforced the GEK proof. QUIC and TCP accepted a bare JWT, so a
+forged or stolen token reached the node and could inject chat messages without
+ever holding the group key. TCP is gone (11.5.2); QUIC and WebRTC now share this
+module, and a parity test fails if either skips a step.
+
+The sequence:
+
+    client → node   handshake            {token, group_id, nonce_c}
+    node            authorize_token()    JWT, scope, denylist, membership, hosting
+    node → client   handshake_challenge  {nonce_s}
+    client → node   handshake_response   {proof}
+    node            verify client proof  HMAC(GEK, client transcript)
+    node → client   handshake_ack        {proof, sig, node_pk, is_node_admin}
+    client          verify node proof    HMAC(GEK, node transcript) + Ed25519
+
+Two properties this adds over the previous design:
+
+**Mutual authentication (C3).** Authentication used to run 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 node now proves GEK possession over a
+client-chosen nonce *and* signs the transcript with its long-term key, so the
+client can pin it.
+
+**Unambiguous transcripts (L4).** The old proof was `nonce ‖ offer_fp ‖ answer_fp`
+— bare concatenation, and a missing fingerprint silently degraded it to nonce-only.
+Every field is now length-prefixed and domain-separated, the role is bound so a
+client proof can never be replayed as a node proof, and an empty channel binding is
+refused rather than tolerated.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+import jwt
+
+HANDSHAKE_PREFIX = b"meshbay:mnp:handshake:v1"
+
+ROLE_CLIENT = "client"
+ROLE_NODE = "node"
+
+NONCE_LEN = 32
+
+
+class HandshakeError(Exception):
+    """Refusal, with a message safe to hand to the peer."""
+
+
+class DenylistLike(Protocol):
+    def is_denied(self, user_id: str, jti: str, group_id: str = "") -> bool: ...
+
+
+@dataclass
+class AuthorizedPeer:
+    user_id: str
+    group_id: str
+    username: str
+    pk_user: str
+    jti: str
+
+
+def handshake_transcript(
+    role: str,
+    group_id: str,
+    nonce_client: bytes,
+    nonce_node: bytes,
+    binding: bytes,
+) -> bytes:
+    """
+    Bytes covered by a handshake proof.
+
+    `binding` ties the proof to the concrete connection: the two DTLS fingerprints
+    for WebRTC, the TLS certificate hashes for QUIC. Without it a proof captured on
+    one connection is replayable on another (NS5).
+    """
+    fields = [
+        role.encode(),
+        group_id.encode(),
+        nonce_client,
+        nonce_node,
+        binding,
+    ]
+    out = bytearray(HANDSHAKE_PREFIX)
+    for field in fields:
+        out += len(field).to_bytes(4, "big")
+        out += field
+    return bytes(out)
+
+
+def make_proof(
+    gek: bytes,
+    role: str,
+    group_id: str,
+    nonce_client: bytes,
+    nonce_node: bytes,
+    binding: bytes,
+) -> bytes:
+    if not binding:
+        # An empty binding means the transport could not identify the channel.
+        # Proceeding would silently drop MitM detection (L4).
+        raise HandshakeError("Channel binding unavailable")
+    if not gek:
+        raise HandshakeError("Group encryption not initialized")
+    transcript = handshake_transcript(
+        role, group_id, nonce_client, nonce_node, binding)
+    return hmac.new(gek, transcript, hashlib.sha256).digest()
+
+
+def verify_proof(
+    gek: bytes,
+    proof: bytes,
+    role: str,
+    group_id: str,
+    nonce_client: bytes,
+    nonce_node: bytes,
+    binding: bytes,
+) -> bool:
+    try:
+        expected = make_proof(
+            gek, role, group_id, nonce_client, nonce_node, binding)
+    except HandshakeError:
+        return False
+    return hmac.compare_digest(proof, expected)
+
+
+def authorize_token(
+    token: str,
+    hub_pk_pem: bytes,
+    *,
+    group_id: str,
+    hosted_groups: Any | None = None,
+    denylist: DenylistLike | None = None,
+    require_scope: str | None = "user",
+) -> AuthorizedPeer:
+    """
+    Everything decided from the JWT, before any proof is exchanged.
+
+    Raises HandshakeError with a peer-safe message. Deliberately strict about
+    `group_id`: it used to be optional, and omitting it skipped the membership
+    check entirely and fell back to the node's first group (M1).
+    """
+    try:
+        decoded = jwt.decode(token, hub_pk_pem, algorithms=["EdDSA"])
+    except Exception as exc:
+        raise HandshakeError(f"Invalid JWT: {exc}") from exc
+
+    # A node-scoped daemon token must not be usable as a client token (M9).
+    if require_scope is not None and decoded.get("scope", "user") != require_scope:
+        raise HandshakeError("Wrong token scope")
+
+    user_id = decoded.get("sub", "")
+    jti = decoded.get("jti", "")
+    if not user_id:
+        raise HandshakeError("Token has no subject")
+
+    if not group_id:
+        raise HandshakeError("group_id is required")
+
+    if denylist is not None and denylist.is_denied(user_id, jti, group_id):
+        raise HandshakeError("Token revoked")
+
+    if group_id not in decoded.get("groups", []):
+        raise HandshakeError("Not a member of this group")
+
+    if hosted_groups is not None and group_id not in hosted_groups:
+        raise HandshakeError("Group not hosted on this node")
+
+    return AuthorizedPeer(
+        user_id=user_id,
+        group_id=group_id,
+        username=decoded.get("username", ""),
+        pk_user=decoded.get("pk_user", ""),
+        jti=jti,
+    )
+
+
+def webrtc_binding(offer_fp: bytes, answer_fp: bytes) -> bytes:
+    """Channel binding for WebRTC: both DTLS certificate fingerprints."""
+    return (len(offer_fp).to_bytes(4, "big") + offer_fp
+            + len(answer_fp).to_bytes(4, "big") + answer_fp)
+
+
+def quic_binding(server_cert_der: bytes) -> bytes:
+    """
+    Channel binding for QUIC.
+
+    QUIC has no DTLS fingerprint to reuse, so the anchor is a hash of the server's
+    self-signed certificate — the same value a client pins as the node identity.
+    An RFC 5705 exporter would be stronger; aioquic does not currently expose one
+    (11.5.6).
+    """
+    digest = hashlib.sha256(server_cert_der).digest()
+    return len(digest).to_bytes(4, "big") + digest
diff --git a/packages/meshbay-common/tests/test_handshake.py b/packages/meshbay-common/tests/test_handshake.py
new file mode 100644
index 0000000..ba8788a
--- /dev/null
+++ b/packages/meshbay-common/tests/test_handshake.py
@@ -0,0 +1,199 @@
+"""
+Unified handshake — properties every transport must inherit (11.5.4/5, C6, C3, L4).
+
+These test the shared module rather than any one transport. The point of the module
+is that WebRTC and QUIC cannot drift apart again: the handshake existed three times
+over and only the newest copy enforced the GEK proof.
+"""
+
+import time
+
+import jwt
+import pytest
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+from meshbay_common.handshake import (
+    HANDSHAKE_PREFIX,
+    NONCE_LEN,
+    ROLE_CLIENT,
+    ROLE_NODE,
+    AuthorizedPeer,
+    HandshakeError,
+    authorize_token,
+    handshake_transcript,
+    make_proof,
+    quic_binding,
+    verify_proof,
+    webrtc_binding,
+)
+
+GEK = b"\x11" * 32
+GROUP = "g" * 32
+NONCE_C = b"\x01" * NONCE_LEN
+NONCE_S = b"\x02" * NONCE_LEN
+BINDING = webrtc_binding(b"\xaa" * 32, b"\xbb" * 32)
+
+
+# ── Token authorization ───────────────────────────────────────────────────────
+
+@pytest.fixture
+def hub_key():
+    sk = Ed25519PrivateKey.generate()
+    pem = sk.private_bytes(
+        serialization.Encoding.PEM,
+        serialization.PrivateFormat.PKCS8,
+        serialization.NoEncryption(),
+    )
+    pub = sk.public_key().public_bytes(
+        serialization.Encoding.PEM,
+        serialization.PublicFormat.SubjectPublicKeyInfo,
+    )
+    return pem, pub
+
+
+def _token(sk_pem, **over):
+    now = int(time.time())
+    payload = {
+        "iss": "test-hub", "sub": "user-1", "jti": "jti-1",
+        "iat": now, "exp": now + 3600,
+        "groups": [GROUP], "scope": "user", "pk_user": "pk",
+    }
+    payload.update(over)
+    return jwt.encode(payload, sk_pem, algorithm="EdDSA")
+
+
+def test_valid_token_authorizes(hub_key):
+    sk_pem, pk_pem = hub_key
+    peer = authorize_token(_token(sk_pem), pk_pem, group_id=GROUP)
+    assert isinstance(peer, AuthorizedPeer)
+    assert peer.user_id == "user-1"
+
+
+def test_group_id_is_mandatory(hub_key):
+    """
+    M1: group_id used to be optional, and omitting it skipped the membership check
+    entirely while falling back to the node's first group.
+    """
+    sk_pem, pk_pem = hub_key
+    with pytest.raises(HandshakeError, match="group_id"):
+        authorize_token(_token(sk_pem), pk_pem, group_id="")
+
+
+def test_non_member_refused(hub_key):
+    sk_pem, pk_pem = hub_key
+    token = _token(sk_pem, groups=["other-group"])
+    with pytest.raises(HandshakeError, match="Not a member"):
+        authorize_token(token, pk_pem, group_id=GROUP)
+
+
+def test_node_scoped_token_refused_on_client_path(hub_key):
+    """M9: a daemon's node-scoped token must not be usable as a client token."""
+    sk_pem, pk_pem = hub_key
+    token = _token(sk_pem, scope="node")
+    with pytest.raises(HandshakeError, match="scope"):
+        authorize_token(token, pk_pem, group_id=GROUP)
+
+
+def test_unhosted_group_refused(hub_key):
+    sk_pem, pk_pem = hub_key
+    with pytest.raises(HandshakeError, match="not hosted"):
+        authorize_token(_token(sk_pem), pk_pem, group_id=GROUP,
+                        hosted_groups={"some-other-group"})
+
+
+def test_denylisted_token_refused(hub_key):
+    sk_pem, pk_pem = hub_key
+
+    class _Deny:
+        def is_denied(self, user_id, jti, group_id=""):
+            return group_id == GROUP
+
+    with pytest.raises(HandshakeError, match="revoked"):
+        authorize_token(_token(sk_pem), pk_pem, group_id=GROUP, denylist=_Deny())
+
+
+def test_forged_token_refused(hub_key):
+    _, pk_pem = hub_key
+    other = Ed25519PrivateKey.generate().private_bytes(
+        serialization.Encoding.PEM,
+        serialization.PrivateFormat.PKCS8,
+        serialization.NoEncryption(),
+    )
+    with pytest.raises(HandshakeError, match="Invalid JWT"):
+        authorize_token(_token(other), pk_pem, group_id=GROUP)
+
+
+# ── Proof transcript ──────────────────────────────────────────────────────────
+
+def test_transcript_is_domain_separated():
+    assert handshake_transcript(
+        ROLE_CLIENT, GROUP, NONCE_C, NONCE_S, BINDING
+    ).startswith(HANDSHAKE_PREFIX)
+
+
+def test_client_proof_is_not_a_node_proof():
+    """
+    C3: the node proves itself with the same key over the same connection. Without
+    the role bound in, a client's proof would satisfy the node check and vice
+    versa, so an impersonating peer could simply echo it back.
+    """
+    client = make_proof(GEK, ROLE_CLIENT, GROUP, NONCE_C, NONCE_S, BINDING)
+    assert not verify_proof(GEK, client, ROLE_NODE, GROUP, NONCE_C, NONCE_S, BINDING)
+
+    node = make_proof(GEK, ROLE_NODE, GROUP, NONCE_C, NONCE_S, BINDING)
+    assert not verify_proof(GEK, node, ROLE_CLIENT, GROUP, NONCE_C, NONCE_S, BINDING)
+    assert client != node
+
+
+@pytest.mark.parametrize("field,value", [
+    ("group_id", "other-group"),
+    ("nonce_client", b"\x09" * NONCE_LEN),
+    ("nonce_node", b"\x09" * NONCE_LEN),
+    ("binding", webrtc_binding(b"\xcc" * 32, b"\xdd" * 32)),
+])
+def test_proof_binds_every_field(field, value):
+    base = dict(role=ROLE_CLIENT, group_id=GROUP, nonce_client=NONCE_C,
+                nonce_node=NONCE_S, binding=BINDING)
+    proof = make_proof(GEK, **base)
+    altered = dict(base, **{field: value})
+    assert not verify_proof(GEK, proof, **altered), (
+        f"proof ignores {field} — replayable across connections")
+
+
+def test_proof_requires_channel_binding():
+    """
+    L4/NS5: the old transcript was nonce ‖ offer_fp ‖ answer_fp, and a missing
+    fingerprint silently degraded it to nonce-only, dropping MitM detection.
+    """
+    with pytest.raises(HandshakeError, match="binding"):
+        make_proof(GEK, ROLE_CLIENT, GROUP, NONCE_C, NONCE_S, b"")
+
+    assert not verify_proof(
+        GEK, b"\x00" * 32, ROLE_CLIENT, GROUP, NONCE_C, NONCE_S, b"")
+
+
+def test_proof_requires_gek():
+    with pytest.raises(HandshakeError):
+        make_proof(b"", ROLE_CLIENT, GROUP, NONCE_C, NONCE_S, BINDING)
+
+
+def test_wrong_gek_fails():
+    proof = make_proof(GEK, ROLE_CLIENT, GROUP, NONCE_C, NONCE_S, BINDING)
+    assert not verify_proof(
+        b"\x22" * 32, proof, ROLE_CLIENT, GROUP, NONCE_C, NONCE_S, BINDING)
+
+
+def test_transcript_is_unambiguous():
+    """
+    L4: with bare concatenation, a crafted group id could impersonate the
+    following field and two different handshakes would produce identical bytes.
+    """
+    a = handshake_transcript(ROLE_CLIENT, "gg", NONCE_C, NONCE_S, BINDING)
+    b = handshake_transcript(ROLE_CLIENT, "g", b"g" + NONCE_C, NONCE_S, BINDING)
+    assert a != b
+
+
+def test_bindings_differ_by_transport():
+    """A WebRTC proof must not be replayable on a QUIC connection."""
+    assert webrtc_binding(b"\xaa" * 32, b"\xbb" * 32) != quic_binding(b"cert-der")
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/crypto.js b/packages/meshbay-hub/src/meshbay_hub/static/crypto.js
index 2346fa2..d18eeae 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/crypto.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/crypto.js
@@ -268,22 +268,70 @@ function adminTranscript(op, nodePkB64, groupId, subject, nonceB64, ts) {
 
 // ── GEK proof (HMAC-SHA256 for handshake challenge) ─────────────────────────
 
-async function hmacGEK(gekRaw, nonceB64, offerFp, answerFp) {
-  const nonce = b64decode(nonceB64);
-  const data = concatBuffers([
-    nonce,
-    offerFp || new Uint8Array(0),
-    answerFp || new Uint8Array(0),
+// Mirrors meshbay_common/handshake.py. Every field length-prefixed and the role
+// bound in, so a client proof can never be replayed as a node proof and a missing
+// fingerprint cannot silently degrade the proof to nonce-only (L4).
+const HANDSHAKE_PREFIX = new TextEncoder().encode('meshbay:mnp:handshake:v1');
+
+function _lenPrefixed(parts) {
+  let total = 0;
+  for (const p of parts) total += 4 + p.length;
+  const out = new Uint8Array(total);
+  const view = new DataView(out.buffer);
+  let off = 0;
+  for (const p of parts) {
+    view.setUint32(off, p.length, false);
+    off += 4;
+    out.set(p, off);
+    off += p.length;
+  }
+  return out;
+}
+
+function webrtcBinding(offerFp, answerFp) {
+  if (!offerFp || !offerFp.length || !answerFp || !answerFp.length) {
+    throw new Error('Channel binding unavailable — refusing to handshake');
+  }
+  return _lenPrefixed([offerFp, answerFp]);
+}
+
+function handshakeTranscript(role, groupId, nonceClient, nonceNode, binding) {
+  const enc = new TextEncoder();
+  const body = _lenPrefixed([
+    enc.encode(role), enc.encode(groupId), nonceClient, nonceNode, binding,
   ]);
+  const out = new Uint8Array(HANDSHAKE_PREFIX.length + body.length);
+  out.set(HANDSHAKE_PREFIX, 0);
+  out.set(body, HANDSHAKE_PREFIX.length);
+  return out;
+}
+
+async function handshakeProof(gekRaw, role, groupId, nonceClient, nonceNode, binding) {
+  const transcript = handshakeTranscript(role, groupId, nonceClient, nonceNode, binding);
   const key = await crypto.subtle.importKey(
     'raw', gekRaw, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
-  const sig = await crypto.subtle.sign('HMAC', key, data);
-  return b64encode(new Uint8Array(sig));
+  const sig = await crypto.subtle.sign('HMAC', key, transcript);
+  return new Uint8Array(sig);
+}
+
+function constantTimeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a[i] ^ b[i];
+  return diff === 0;
+}
+
+/** Verify the node's Ed25519 signature over the handshake transcript (C3). */
+async function verifyNodeSignature(nodePkB64, sigB64, transcript) {
+  const raw = b64decode(nodePkB64);
+  const key = await crypto.subtle.importKey('raw', raw, { name: 'Ed25519' }, false, ['verify']);
+  return crypto.subtle.verify('Ed25519', key, b64decode(sigB64), transcript);
 }
 
 // Export for use in app.js
 window.MeshBayCrypto = {
   importGEK, deriveChunkKey, decryptChunk, decryptChunkBin, decryptFile,
   generateGEK, wrapGEK, unwrapGEK, encryptChunk, b64encode, b64decode,
-  hmacGEK, adminTranscript,
+  adminTranscript, handshakeTranscript, handshakeProof, webrtcBinding,
+  verifyNodeSignature, constantTimeEqual,
 };
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/transport.js b/packages/meshbay-hub/src/meshbay_hub/static/transport.js
index d636085..18faea1 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/transport.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/transport.js
@@ -129,11 +129,16 @@ class MeshBayTransport {
 
     await channelReady;
 
+    // The client nonce is what makes the NODE's proof fresh (C3) — without it a
+    // recorded handshake_ack could be replayed by an impersonating peer.
+    this._nonceClient = crypto.getRandomValues(new Uint8Array(32));
+
     const reply = await this._sendAndWait({
       type: 'handshake',
       v: '0.1',
       token: jwtToken,
       group_id: groupId || '',
+      nonce: window.MeshBayCrypto.b64encode(this._nonceClient),
     });
 
     if (reply.type === 'handshake_challenge') {
@@ -190,28 +195,53 @@ class MeshBayTransport {
         throw new Error('Node requires GEK proof but no GEK available');
       }
 
-      let proof = '';
-      if (gekRaw) {
-        const offerFp = _extractDtlsFingerprint(this._pc.localDescription.sdp);
-        const answerFp = _extractDtlsFingerprint(this._rawAnswerSdp);
-        proof = await window.MeshBayCrypto.hmacGEK(gekRaw, reply.nonce, offerFp, answerFp);
-      }
+      const C = window.MeshBayCrypto;
+      // Node's answer SDP carries ITS fingerprint; our offer carries ours. Throws
+      // if either is missing rather than proceeding with an unbound proof (L4).
+      const binding = C.webrtcBinding(
+        _extractDtlsFingerprint(this._pc.localDescription.sdp),
+        _extractDtlsFingerprint(this._rawAnswerSdp),
+      );
+      const nonceNode = C.b64decode(reply.nonce);
+      const gid = groupId || '';
+
+      const proof = await C.handshakeProof(
+        gekRaw, 'client', gid, this._nonceClient, nonceNode, binding);
+
       const ack = await this._sendAndWait({
         type: 'handshake_response',
         v: '0.1',
-        proof,
+        proof: C.b64encode(proof),
       });
       if (ack.type !== 'handshake_ack') {
         throw new Error('GEK proof rejected: ' + (ack.detail || JSON.stringify(ack)));
       }
-      return ack;
-    }
 
-    if (reply.type !== 'handshake_ack') {
-      throw new Error('MNP handshake rejected: ' + (reply.detail || JSON.stringify(reply)));
+      // Authenticate the NODE before trusting anything it says (C3). Until this
+      // ran, node_pk was decorative: a peer that had hijacked signaling could
+      // accept our proof, ignore it, and serve a forged index, chat history and
+      // is_node_admin flag.
+      const expected = await C.handshakeProof(
+        gekRaw, 'node', gid, this._nonceClient, nonceNode, binding);
+      if (!ack.proof || !C.constantTimeEqual(C.b64decode(ack.proof), expected)) {
+        throw new Error('Node failed to prove GEK possession — refusing connection');
+      }
+      const transcript = C.handshakeTranscript(
+        'node', gid, this._nonceClient, nonceNode, binding);
+      if (!ack.node_pk || !ack.sig
+          || !await C.verifyNodeSignature(ack.node_pk, ack.sig, transcript)) {
+        throw new Error('Node signature invalid — refusing connection');
+      }
+      this.nodePk = ack.node_pk;
+
+      return ack;
     }
 
-    return reply;
+    // A node that answers a handshake with anything other than a challenge is not
+    // running the mutual protocol. Accepting a bare handshake_ack here would let a
+    // peer skip proving GEK possession entirely (C3/C6).
+    throw new Error(
+      'MNP handshake rejected: ' + (reply.detail || `unexpected ${reply.type}`));
   }
 
   async fetchIndex() {
diff --git a/packages/meshbay-node/src/meshbay_node/transport/webrtc_server.py b/packages/meshbay-node/src/meshbay_node/transport/webrtc_server.py
index 190d580..34a96bd 100644
--- a/packages/meshbay-node/src/meshbay_node/transport/webrtc_server.py
+++ b/packages/meshbay-node/src/meshbay_node/transport/webrtc_server.py
@@ -43,6 +43,17 @@ from cryptography.hazmat.primitives.asymmetric.ed25519 import (
 )
 
 from meshbay_common import MNP_VERSION
+from meshbay_common.handshake import (
+    NONCE_LEN,
+    ROLE_CLIENT,
+    ROLE_NODE,
+    HandshakeError,
+    authorize_token,
+    handshake_transcript,
+    make_proof,
+    verify_proof,
+    webrtc_binding,
+)
 from meshbay_common.adminop import (
     ADMIN_CHALLENGE_TTL,
     OP_FILE_DELETE,
@@ -207,6 +218,7 @@ class WebRTCPeerSession:
         self._username: str = ""
         self._pk_user: str = ""
         self._gek_challenge: bytes | None = None
+        self._nonce_client: bytes = b""
         self._admin_ops: dict[str, dict] = {}   # op_id → pending admin operation
         self._uploads: dict[str, dict] = {}   # filename → {next_index, bytes}
 
@@ -293,58 +305,65 @@ class WebRTCPeerSession:
                 detail=detail,
             ))
 
+    def _channel_binding(self) -> bytes:
+        """Both DTLS fingerprints, so a proof is valid on this connection only."""
+        offer_fp = b""
+        answer_fp = b""
+        if self._pc.remoteDescription:
+            offer_fp = _extract_dtls_fingerprint(self._pc.remoteDescription.sdp)
+        if self._pc.localDescription:
+            answer_fp = _extract_dtls_fingerprint(self._pc.localDescription.sdp)
+        if not offer_fp or not answer_fp:
+            return b""
+        return webrtc_binding(offer_fp, answer_fp)
+
     def _do_handshake(self, msg: dict) -> None:
-        token = msg.get("token", "")
         group_id = msg.get("group_id", "")
         try:
-            decoded = jwt.decode(token, self._ctx["hub_pk_pem"], algorithms=["EdDSA"])
-        except Exception as e:
-            self._send({"type": "error", "detail": f"Invalid JWT: {e}"})
-            self._audit_auth_failed(group_id, str(e))
-            return
-
-        denylist = self._ctx.get("denylist")
-        if denylist and denylist.is_denied(
-                decoded.get("sub", ""), decoded.get("jti", ""), group_id):
-            self._send({"type": "error", "detail": "Token revoked"})
-            return
-
-        if group_id and group_id not in decoded.get("groups", []):
-            self._send({"type": "error", "detail": "Not a member of this group"})
+            peer = authorize_token(
+                msg.get("token", ""),
+                self._ctx["hub_pk_pem"],
+                group_id=group_id,
+                hosted_groups=self._ctx.get("groups"),
+                denylist=self._ctx.get("denylist"),
+            )
+        except HandshakeError as refusal:
+            # HandshakeError messages are authored to be peer-safe, unlike arbitrary
+            # exception text (L3) — the client needs to know *why* it was refused.
+            self._send({"type": "error", "detail": str(refusal)})
+            self._audit_auth_failed(group_id, str(refusal))
             return
 
-        if group_id and "groups" in self._ctx and group_id not in self._ctx["groups"]:
-            self._send({"type": "error", "detail": "Group not hosted on this node"})
+        try:
+            self._nonce_client = base64.b64decode(msg.get("nonce", ""))
+        except Exception:
+            self._nonce_client = b""
+        if len(self._nonce_client) < NONCE_LEN:
+            # The client nonce is what makes the NODE's proof fresh (C3). Without
+            # it a recorded ack could be replayed by an impersonating peer.
+            self._send({"type": "error", "detail": "Client nonce required"})
             return
 
-        # Store decoded JWT data but DO NOT set self._user_id yet —
-        # the user is not authenticated until they prove GEK possession.
-        self._pending_sub = decoded["sub"]
-        self._pending_group = group_id
-        self._pending_username = decoded.get("username", "")
-        self._pending_pk_user = decoded.get("pk_user", "")
+        # Decoded, but NOT authenticated: that happens on the GEK proof.
+        self._pending_sub = peer.user_id
+        self._pending_group = peer.group_id
+        self._pending_username = peer.username
+        self._pending_pk_user = peer.pk_user
 
-        ctx = self._ctx
-        if "groups" in ctx and group_id:
-            gctx = ctx["groups"].get(group_id, ctx)
-        else:
-            gctx = ctx
-        gek = gctx.get("gek")
-
-        nonce = os.urandom(32)
-        self._gek_challenge = nonce
-        challenge = {
-            "type": MNP.HANDSHAKE_CHALLENGE,
-            "v": MNP_VERSION,
-            "nonce": base64.b64encode(nonce).decode(),
-        }
-        if not gek:
+        gctx = self._ctx["groups"][peer.group_id] if "groups" in self._ctx else self._ctx
+        if not gctx.get("gek"):
             self._send({
                 "type": "error",
                 "detail": "Group encryption not initialized — contact node operator",
             })
             return
-        self._send(challenge)
+
+        self._gek_challenge = os.urandom(NONCE_LEN)
+        self._send({
+            "type": MNP.HANDSHAKE_CHALLENGE,
+            "v": MNP_VERSION,
+            "nonce": base64.b64encode(self._gek_challenge).decode(),
+        })
 
     def _do_handshake_response(self, msg: dict) -> None:
         if not self._gek_challenge or not hasattr(self, "_pending_sub"):
@@ -352,44 +371,38 @@ class WebRTCPeerSession:
             return
 
         group_id = self._pending_group
-        ctx = self._ctx
-        if "groups" in ctx and group_id:
-            gctx = ctx["groups"].get(group_id, ctx)
-        else:
-            gctx = ctx
+        gctx = self._ctx["groups"][group_id] if "groups" in self._ctx else self._ctx
         gek = gctx.get("gek")
-
         if not gek:
             self._send({"type": "error", "detail": "Group encryption not initialized"})
             self._gek_challenge = None
             return
 
-        proof = msg.get("proof", "")
         try:
-            proof_bytes = base64.b64decode(proof)
+            proof_bytes = base64.b64decode(msg.get("proof", ""))
         except Exception:
             self._send({"type": "error", "detail": "Invalid proof encoding"})
             return
 
-        offer_fp = b""
-        answer_fp = b""
-        if self._pc.remoteDescription:
-            offer_fp = _extract_dtls_fingerprint(self._pc.remoteDescription.sdp)
-        if self._pc.localDescription:
-            answer_fp = _extract_dtls_fingerprint(self._pc.localDescription.sdp)
+        binding = self._channel_binding()
+        if not binding:
+            # Refuse rather than fall back to an unbound proof (L4).
+            self._send({"type": "error", "detail": "Channel binding unavailable"})
+            self._gek_challenge = None
+            self._audit_auth_failed(group_id, "no channel binding")
+            return
 
-        data = self._gek_challenge + offer_fp + answer_fp
-        expected = hmac.new(gek, data, hashlib.sha256).digest()
-        if not hmac.compare_digest(proof_bytes, expected):
+        if not verify_proof(gek, proof_bytes, ROLE_CLIENT, group_id,
+                            self._nonce_client, self._gek_challenge, binding):
             self._send({"type": "error", "detail": "GEK proof failed"})
             self._gek_challenge = None
             self._audit_auth_failed(group_id, "GEK HMAC mismatch")
             return
 
+        self._complete_handshake(gek, binding)
         self._gek_challenge = None
-        self._complete_handshake()
 
-    def _complete_handshake(self) -> None:
+    def _complete_handshake(self, gek: bytes, binding: bytes) -> None:
         # Authenticated peers may send large frames (file uploads); unauthenticated
         # ones may not (H6).
         self._buffer.max_message = MAX_MSG
@@ -404,10 +417,25 @@ class WebRTCPeerSession:
         log.info("WebRTC handshake OK — user=%s group=%s",
                  self._user_id[:8],
                  self._group_id[:8] if self._group_id else "none")
+        # The node proves itself too (C3): possession of the GEK over the client's
+        # nonce, plus a signature over the same transcript with its long-term key.
+        # Previously the client received an unverifiable node_pk and trusted
+        # is_node_admin from whoever answered — so a peer that had hijacked
+        # signaling could serve a forged index, chat history and permissions.
+        node_transcript = handshake_transcript(
+            ROLE_NODE, self._group_id or "", self._nonce_client,
+            self._gek_challenge or b"", binding)
+        node_proof = make_proof(
+            gek, ROLE_NODE, self._group_id or "", self._nonce_client,
+            self._gek_challenge or b"", binding)
+
         ack = {
             "type": MNP.HANDSHAKE_ACK,
             "v": MNP_VERSION,
             "node_pk": pk_to_b64(self._ctx["sk_node"].public_key()),
+            "proof": base64.b64encode(node_proof).decode(),
+            "sig": base64.b64encode(
+                self._ctx["sk_node"].sign(node_transcript)).decode(),
             "is_node_admin": bool(node_user_id and self._user_id == node_user_id),
         }
         if node_user_id:
diff --git a/packages/meshbay-node/tests/test_security_regressions.py b/packages/meshbay-node/tests/test_security_regressions.py
index a6d69c6..9299bf4 100644
--- a/packages/meshbay-node/tests/test_security_regressions.py
+++ b/packages/meshbay-node/tests/test_security_regressions.py
@@ -460,10 +460,21 @@ def test_dead_gek_protocol_constants_removed():
 
 
 def test_peer_errors_do_not_leak_internals():
-    """L3: exception text carries filesystem paths and internal state."""
+    """
+    L3: arbitrary exception text carries filesystem paths and internal state, so
+    the catch-all handler must not relay it.
+
+    Deliberately narrow: HandshakeError messages ARE sent to the peer, because a
+    client needs to know why it was refused, and those strings are authored for
+    that purpose. The check targets the generic `except Exception as e` path.
+    """
     source = (Path(__file__).parent.parent / "src" / "meshbay_node"
               / "transport" / "webrtc_server.py").read_text()
-    assert '"detail": str(e)' not in source
+    assert '"detail": str(e)' not in source, (
+        "generic exception text relayed to peer — use a fixed message"
+    )
+    # And the catch-all must still exist, sending something opaque.
+    assert '"detail": "Request failed"' in source
 
 
 def test_pre_handshake_message_budget_is_small():
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
-- 
cgit v1.2.3


From f15efd23f66c521ca9206789482bb38e7326eeb4 Mon Sep 17 00:00:00 2001
From: Christophe Besson <cbesson@gmail.com>
Date: Fri, 14 Aug 2026 01:27:21 +0200
Subject: feat(node)!: the node wraps the group key — closes H3 and M3
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The invite flow fetched the invitee's pk_x25519 from the hub and wrapped the
GEK for whatever came back (app.js:1466, and gek-init did the same server-side).
The hub is the key directory, so a hub answering with its own key was handed the
group key by an honest member following the protocol exactly. No forgery, no
injection, nothing for the client to notice. That was H3.

The fix is not safety numbers. Nobody reads the directory any more:

  - the node holds the GEK and wraps it itself, on every connection, for the
    X25519 key the joiner signed with their Ed25519 identity in one transcript
    (meshbay:join:v1), so the identity key vouches for the encryption key;
  - identities are bound to accounts by a one-time code the hub never sees —
    40 bits, single use, one account, bounded per connection AND node-wide;
  - the node's own roster decides who may receive the key. Hub membership lets
    someone reach a node; it no longer gets them anything. A hub that invents an
    account and mints it a token is answered not_authorized_for_group.

Safety numbers would have made substitution detectable by a human who checks, at
the moment there is nothing to check against — first contact. Removing the lookup
makes it impossible, and costs the user one code to pass along.

M3 falls out of the same work. The daemon auto-pinned its own keystore key as
admin_pk_ed25519 while the browser signs with the user identity key, so every
privileged operation failed closed with a signature error that looked like a bug
somewhere else; the demo only worked because a deploy script overwrote the value.
Authority now comes from the roster, established locally by `operator pair`.
Asking the hub for the operator's key — the obvious-looking fix — would have let
the hub install itself as node administrator.

BREAKING: gek_bundle_store is deleted, not gated. No member hands the node key
material at all, so C5b becomes structural rather than an authorization to check.
Existing stored bundles are still served, so current deployments keep working.

Also:
  - join_policy (invite|open) is read from node.toml, never from the hub — a hub
    able to declare a group open would be handed its key. Unknown group ⇒ invite.
  - admin signatures are verified against the roster on every check, so unpinning
    takes effect without a restart. admin_pk_ed25519 stays readable as legacy.
  - two C5b tests were rewritten, deliberately: they asserted that
    gek_bundle_store demanded an operator signature, and the message is gone. They
    now assert the stronger property. The file says not to fix these tests, so
    this is the record of why they changed.
  - a slice-1 bug found while writing slice 2: connect() never passed skEdB64, so
    pairing would have failed at runtime with no test able to catch it.

Tests: 152 node+common here, including an end-to-end DataChannel run where a
member who has never held the group key redeems a code in the pre-proof window
and receives the key wrapped for a key only they can open.

Design: docs/invite-pairing-v1.md

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 docs/invite-pairing-v1.md                          | 526 +++++++++++++++++++++
 .../meshbay-common/src/meshbay_common/adminop.py   |   9 +-
 packages/meshbay-common/src/meshbay_common/join.py |  63 +++
 .../meshbay-common/src/meshbay_common/protocol.py  |   8 +-
 .../meshbay-common/tests/test_js_python_parity.py  |  65 ++-
 packages/meshbay-hub/src/meshbay_hub/static/app.js | 137 +++++-
 .../meshbay-hub/src/meshbay_hub/static/crypto.js   |  27 +-
 .../meshbay-hub/src/meshbay_hub/static/i18n.js     |  16 +
 .../meshbay-hub/src/meshbay_hub/static/style.css   |  15 +
 .../src/meshbay_hub/static/transport.js            | 178 ++++++-
 packages/meshbay-node/src/meshbay_node/config.py   |  16 +-
 packages/meshbay-node/src/meshbay_node/daemon.py   | 231 ++++++---
 packages/meshbay-node/src/meshbay_node/roster.py   | 372 +++++++++++++++
 .../src/meshbay_node/transport/webrtc_server.py    | 413 +++++++++++++---
 packages/meshbay-node/src/meshbay_node/ui/app.py   | 110 +++--
 packages/meshbay-node/tests/test_roster_pairing.py | 504 ++++++++++++++++++++
 .../tests/test_security_regressions.py             |  58 ++-
 .../meshbay-node/tests/test_webrtc_transport.py    | 178 ++++---
 18 files changed, 2639 insertions(+), 287 deletions(-)
 create mode 100644 docs/invite-pairing-v1.md
 create mode 100644 packages/meshbay-common/src/meshbay_common/join.py
 create mode 100644 packages/meshbay-node/src/meshbay_node/roster.py
 create mode 100644 packages/meshbay-node/tests/test_roster_pairing.py

(limited to 'packages/meshbay-node/tests/test_security_regressions.py')

diff --git a/docs/invite-pairing-v1.md b/docs/invite-pairing-v1.md
new file mode 100644
index 0000000..56fccbe
--- /dev/null
+++ b/docs/invite-pairing-v1.md
@@ -0,0 +1,526 @@
+# MeshBay — Invitation and Pairing (design)
+
+> Status: **proposal, not implemented.** Written 2026-08-13.
+> Supersedes the invite flow described in `meshbay-draft-v5.md` §5.1 and the
+> Phase 12.1 milestone in `devel-phases-next.md`, if adopted.
+>
+> Closes **H3** for the path where it is actually exploitable, and dissolves **M3**
+> rather than patching it. Follows the v5 convention: every claim names the
+> adversary it holds against.
+
+---
+
+## 1. What is wrong today
+
+Two problems, one visible to users and one invisible.
+
+### 1.1 The workflow problem
+
+An invite runs entirely inside the inviter's browser (`app.js:1391-1420`):
+
+1. fetch the invitee's `pk_x25519` from the hub — `GET /v1/users/{name}/pubkeys`
+2. take the raw GEK out of the live transport connection
+3. wrap the GEK for that key and push the bundle to the node over MNP
+4. add the member on the hub
+
+Step 2 requires the inviter to be **connected to the node with the group key in
+hand**. Step 3 requires the node to accept the bundle, which since C5b means the
+signature must be the node operator's (`webrtc_server.py:1023-1035`). Together:
+
+- only the node operator can invite — v5 §5.1 records this as deliberate
+- the operator must be at a browser, connected, at the moment of the invite
+- a group admin who does not run the node cannot add anyone, ever
+
+That is not a workflow. It is the reason the demo needs `demo.py set-admin-pk`.
+
+### 1.2 The security problem (H3)
+
+Step 1 asks the **hub** which key belongs to `bob`. The hub stores those keys as
+mutable columns on the user row (`api/users.py:352-354`) and serves them with no
+signature and no history. A hub that answers with a key it holds is handed the GEK
+by an honest inviter following the protocol exactly. Nothing forged, nothing
+injected, and nothing in the client notices.
+
+The account is unique and the account is right. The **key attached to the account**
+is what the hub controls.
+
+### 1.3 M3, underneath both
+
+The daemon auto-pins its own keystore key as the admin key (`daemon.py:470-474`);
+the browser signs with the user identity key (`app.js:1416`). They differ, so
+invites and deletions fail closed with a signature error that looks like a bug
+elsewhere. The demo works only because a deploy script writes the browser key into
+`node.toml`.
+
+The tempting fix — have the daemon fetch the operator's key from the hub — turns M3
+into a second H3: the hub would then be able to install itself as node
+administrator. **The node must never learn authority from the hub.**
+
+---
+
+## 2. Principle
+
+Three rules. Everything below follows from them.
+
+1. **The node wraps the group key.** The node already holds the GEK — it encrypts
+   and serves the content. So it, not the inviter's browser, produces each member's
+   bundle. No member ever handles another member's key material.
+2. **A key is bound to an identity by a one-time pairing code, then pinned.** The
+   code travels out of band (the inviter sends it to the invitee the way they
+   already talk). The hub never sees it and therefore cannot claim to be the
+   invitee.
+3. **The node keeps its own roster.** Hub membership is an input, not an
+   authorization. Otherwise a hub that invents an account and mints a token for it
+   collects the GEK on connect.
+
+Human cost of the whole scheme: **one code per person, once per node**, plus one
+code for the operator at install. No fingerprint comparison, no per-member
+signature ceremony, no operator required to be online when someone joins.
+
+---
+
+## 3. Flows
+
+### 3.1 Operator pairing (once per node, replaces M3)
+
+```
+operator (SSH)   meshbay-node operator pair
+node             prints   PAIR-CODE: K7M2-QX4P     (also written to data_dir/pair-code)
+operator (SPA)   Settings → "Pair this browser with my node" → types the code
+SPA → node       join_request {role_hint: operator, code, pk_ed25519, pk_x25519, sig}
+node             code valid, unused, unexpired → pins the keys, role = operator
+node             writes the pin to its roster DB, prints it in `status`
+```
+
+The operator types 8 characters into their own browser. Nothing is pasted, nothing
+is copied out of a terminal, no browser is needed on the node host, and the hub is
+not involved at any point. `admin_pk_ed25519` in `node.toml` becomes a legacy
+fallback, still read, no longer required.
+
+### 3.2 Invite (one click, operator or delegate)
+
+```
+grenet (SPA)     Groups → Members → "Invite bob"
+SPA → node       admin_request {op: invite_create, group_id, invitee: bob, ttl}
+node → SPA       admin_challenge  (structured transcript, H5 — the SPA shows one
+                                   line: "authorize bob to join <group>")
+SPA → node       admin_response {sig}       ← signed silently with grenet's key
+node             creates invite: code, group, invitee, expiry; status = pending
+node → SPA       invite_created {code: "R3H8-TB6V", expires_at}
+grenet           sends the code to bob however they already talk
+SPA → hub        POST /v1/groups/{id}/members/bob   (membership, unchanged)
+```
+
+Grenet's browser signs, but grenet does not *inspect* a signature — one click, one
+confirmation line, one code to pass on. Same gesture as any invite link on any
+platform.
+
+### 3.3 Join (fully automatic, operator may be asleep)
+
+```
+bob (SPA)        opens the group; client has no GEK for it
+bob → node       handshake {token, group_id, nonce_c}          (pre-proof window)
+node → bob       handshake_challenge {nonce_s}
+bob → node       join_request {group_id, pk_ed25519, pk_x25519, code, sig}
+node             1. rate-limit + attempt count on this connection
+                 2. code matches a pending invite for this user_id and group
+                 3. identity not already pinned to a different key
+                 4. pin (user_id → pk_ed25519, pk_x25519), mark invite used,
+                    member status = active
+                 5. wrap the ACTIVE GEK for pk_x25519  (ECIES, as today)
+node → bob       join_result {ok, pk_eph_b64, nonce_b64, wrapped_b64}
+bob              unwraps the GEK, completes the normal GEK proof, session proceeds
+```
+
+On every later connection bob sends `join_request` **without** a code; the node
+recognises the pinned identity, re-wraps the current GEK and answers. So GEK
+rotation propagates by itself, and a revoked member simply stops being served.
+
+### 3.4 Open-join groups: no code (decided 2026-08-13)
+
+A group whose hub-side `join_policy` is `"open"` (`groups.py:227-228`) admits anyone
+who asks. A pairing code there protects nothing — the hub can create an account,
+join through the front door and be a legitimate member — so it is pure friction.
+For those groups the node pins on first contact (TOFU, `pinned_via = 'tofu'`) and
+wraps the GEK immediately.
+
+Note the axis. `visibility` (public/private) controls **discoverability** and swarm
+hash registration (H7); `join_policy` (open/request/invite) controls **admission**.
+Only the second one decides whether a code is required. A `visibility = "public"`
+group with `join_policy = "invite"` keeps the code — being findable is not being
+open.
+
+**Stated plainly, per the v5 convention:** in an open-join group the hub can obtain
+the GEK, because it can become a member legitimately. That is a property of open
+joining, not of this design — it is equally true today. Content in such a group is
+protected from the network and from non-members, and from nobody else. The docs
+must say so, and the SPA should say so when someone sets `join_policy = "open"` on
+a group that already holds content.
+
+---
+
+## 4. Why a pairing code, and not something lighter
+
+The choice is forced by one question: when bob connects for the first time, what
+stops the hub from being bob?
+
+| Option | What the hub can do | Verdict |
+|---|---|---|
+| Node wraps for the key the peer presents, no binding | Forge a JWT for bob, present its own key, receive the GEK | **Worse than today** — today a forged JWT yields a bundle wrapped to bob's real key, which is useless |
+| Bind to the key the inviter fetched from the hub | Substitute at invite time — H3 unchanged, just relocated into the node | No |
+| TOFU: first connection wins | Race the real bob with a forged token; small window, total consequence | No |
+| Safety-number comparison at invite | Nothing — but it needs two humans reading digits at the worst moment | Correct, unusable as the default |
+| **One-time pairing code** | Nothing: the code never reaches the hub | **Adopted** |
+
+The code is the cheapest thing that binds an identity to a key without the
+directory. It is also the familiar shape — invite links work this way everywhere.
+
+**Boundary, stated honestly:** for a browser client the SPA is served by the hub, so
+a hub that ships malicious client code can read the code out of the page. That is
+**T3, accepted permanently** by decision D1 and unchanged by this design. The code
+defeats a hub that *lies in its directory* — a silent, undetectable, per-request
+attack — not one that *rewrites the client*, which is an artifact and is what the
+native client (Phase 13) removes. Do not blur the two in the docs.
+
+---
+
+## 5. Protocol
+
+### 5.1 New MNP messages (`meshbay_common/protocol.py`)
+
+```
+JOIN_REQUEST  = "join_request"    # client → node, served in the pre-proof window
+JOIN_RESULT   = "join_result"     # node → client
+INVITE_CREATE = "invite_create"   # inviter → node (admin op, see 5.3)
+INVITE_RESULT = "invite_result"   # node → inviter, carries the code once
+```
+
+`join_request`:
+
+| Field | Meaning |
+|---|---|
+| `group_id` | mandatory, as everywhere since 11.5.4 |
+| `pk_ed25519`, `pk_x25519` | the caller's own keys, base64 raw |
+| `code` | first pairing with this node only; omitted when `join_policy == "open"` (§3.4) |
+| `role_hint` | `operator` or absent; the node trusts the *code*, not the hint |
+| `sig` | Ed25519 over the transcript below |
+
+### 5.2 Join transcript
+
+```
+"meshbay:join:v1" ‖ len‖node_pk ‖ len‖group_id ‖ len‖user_id
+                  ‖ len‖pk_ed25519 ‖ len‖pk_x25519 ‖ len‖nonce_s ‖ len‖ts
+```
+
+Length-prefixed and domain-separated per 11.5.21. `nonce_s` is the handshake nonce
+the node just issued, so a `join_request` cannot be replayed onto another
+connection. `pk_x25519` is inside the signature, so the Ed25519 key vouches for the
+X25519 key it is paired with — this is what makes "wrap for the presented key" safe.
+
+The **code is never signed and never echoed** — it is a bearer secret, compared
+against a stored hash and destroyed on use.
+
+### 5.3 Invite creation reuses the existing admin machinery
+
+New op in `meshbay_common/adminop.py`, alongside `OP_FILE_DELETE` and
+`OP_GEK_BUNDLE_STORE`:
+
+```
+OP_INVITE_CREATE = "invite_create"
+"meshbay:admin:v1" ‖ len‖op ‖ len‖node_pk ‖ len‖group_id ‖ len‖subject ‖ len‖nonce ‖ len‖ts
+                                                    subject = invitee user_id
+```
+
+Authorized by the pinned **operator** role, or by a **delegate** (§6.2). TTL 120 s,
+same as every other admin op. The client rebuilds the transcript and refuses to
+sign if the subject is not the person the user typed — H5's rule, unchanged.
+
+### 5.4 Code format
+
+8 characters, Crockford base32 (no `I`, `L`, `O`, `U`), rendered `XXXX-XXXX` — 40
+bits. Single use, default TTL 24 h, stored only as `sha256(code)` — a password KDF
+would be pointless over 40 uniformly random bits, and `blake3` is not a node
+dependency. Guessing is
+bounded by: 5 attempts per connection, a node-wide limiter on failed
+`join_request`s, and the fact that a code is valid for exactly one `user_id` in one
+group. A brute-force attempt is an audit-log event, not a silent grind.
+
+---
+
+## 6. Node state
+
+### 6.1 Schema (new tables, `roster.py`, same SQLite file style as `bundle_store.py`)
+
+```sql
+CREATE TABLE identities (          -- one row per person, not per group
+    user_id    TEXT PRIMARY KEY,
+    username   TEXT NOT NULL,
+    pk_ed25519 TEXT NOT NULL,
+    pk_x25519  TEXT NOT NULL,
+    pinned_at  TEXT NOT NULL,
+    pinned_via TEXT NOT NULL       -- 'code' | 'tofu' | 'legacy-config' | 'operator-reset'
+);
+
+CREATE TABLE members (
+    group_id    TEXT NOT NULL,
+    user_id     TEXT NOT NULL,
+    role        TEXT NOT NULL,     -- 'operator' | 'delegate' | 'member'
+    status      TEXT NOT NULL,     -- 'pending' | 'active' | 'revoked'
+    approved_by TEXT NOT NULL,     -- user_id whose signature created the invite
+    approved_at TEXT NOT NULL,
+    PRIMARY KEY (group_id, user_id)
+);
+
+CREATE TABLE invites (
+    code_hash  TEXT PRIMARY KEY,
+    group_id   TEXT NOT NULL,
+    user_id    TEXT NOT NULL,
+    role       TEXT NOT NULL,
+    created_by TEXT NOT NULL,
+    expires_at TEXT NOT NULL,
+    used_at    TEXT
+);
+```
+
+Identity is pinned **per node, not per group**: someone already paired for one group
+needs no code for the next one. The operator's pairing is the same mechanism with
+`role = 'operator'` and no group.
+
+### 6.2 Delegation — **deferred** (decided 2026-08-13)
+
+A `delegate` row would let a group admin who is not the node operator create invites
+without the operator being involved again. Not needed while the operator is the
+inviter (the demo, and every single-operator deployment), so it is **not built in
+v1**.
+
+The `role` column reserves the value and `invite_create` authorization is written as
+a role check rather than an equality test against the operator, so adding it later
+is a roster row and a CLI command — no protocol change, no migration.
+
+### 6.3 What the node stops doing
+
+- `gek_bundle_store` **no longer accepts member-supplied bundles at all.** Nothing
+  arriving over MNP contributes key material. C5b's rule is not merely preserved,
+  it becomes structural — the message can be deleted from the client path entirely.
+- Per-member rows in `gek_bundles` are no longer written. The node wraps on demand.
+  The node's own `_node_{user_id}` bundle stays: that is how the daemon reloads its
+  GEK across restarts.
+- **Consequence worth having:** revocation starts working for key delivery. A
+  stored bundle today survives revocation; on-demand wrapping does not. (Rotating
+  the GEK after a revocation is still required — the ex-member has the old key.)
+
+---
+
+## 7. Security analysis
+
+### 7.1 Against each adversary
+
+| Attack | Today | With this design |
+|---|---|---|
+| Hub substitutes the invitee's key at invite time (**H3**) | Succeeds silently, hub gets the GEK | **Fails** — no key is ever fetched from the directory |
+| Hub forges a JWT for a real member | Gets a bundle wrapped to the member's real key: useless | Unchanged: no code, no pin match → refused |
+| Hub invents an account and adds it to the group | Blocked only accidentally, by the bundle requirement | **Blocked by the roster** — no invite, no code, no GEK |
+| Hub substitutes the *operator's* key (M3's tempting fix) | n/a | **Impossible** — the node pins by code, never asks the hub |
+| Member wraps a GEK of their choosing for the operator (**C5b**) | Blocked by operator signature | **Impossible** — the message no longer exists |
+| Member replays a `join_request` from another connection | n/a | Bound to `nonce_s` |
+| Member presents someone else's `pk_x25519` | n/a | Signed by the paired `pk_ed25519`, mismatch refused |
+| Ex-member reconnects after revocation | Stored bundle still unwraps | Not served; GEK rotation still needed |
+| Third party guesses a code | n/a | 40 bits, single use, per-user, rate-limited, audited |
+| Hub joins an **open-join** group and collects the GEK | Succeeds | Still succeeds — inherent to open joining (§3.4), must be documented, not hidden |
+
+### 7.2 What this does **not** fix
+
+- **T3** — the hub serves the SPA and can read the code out of the page. Accepted
+  (D1); removed only by the native client plus reproducible builds.
+- **C4** — the keypair-bundle pre-proof window is untouched. A first-time joiner
+  still needs their own identity keys before they can sign anything; that material
+  belongs on the user's device (Phase 13.3).
+- **The node operator reads everything.** Inherent to the model.
+- **The hub still knows who is in which group.** Membership is hub-side; the roster
+  only decides who receives the key.
+- **A member can still leak the GEK out of band.** Nothing prevents that, and
+  nothing in the current design pretends to.
+
+---
+
+## 8. Failure modes and edge cases
+
+| Case | Behaviour |
+|---|---|
+| Code lost or expired | Inviter clicks "Invite" again; the old invite is superseded and its hash deleted |
+| Bob pairs, then loses his keys and runs `regenerateKeys` | Pin mismatch → join refused with a clear message; needs a fresh invite (operator or delegate re-issues). This is the intended blocking warning, moved to the moment it matters |
+| Bob is in two groups on the same node | One pin, one code, ever |
+| Node reinstalled / roster lost | Everyone re-pairs. Same class of event as losing the keystore; `status` must say so plainly |
+| Operator pairs a second browser | New `operator pair` code; both browsers valid, both listed in `status` |
+| Two people race one code | Single-use row, `used_at` set under a transaction; the loser gets a plain refusal |
+| Invite created while the node is offline | Not possible — invites are created on the node. The SPA must say "node offline, cannot invite" instead of failing obscurely |
+| Member connects while the group has no active GEK | `join_result {ok: false, reason: "no_gek"}`; the operator runs `gek-init` |
+| Legacy deployment with `admin_pk_ed25519` set | Read at startup and inserted as an `identities` row with `pinned_via = 'legacy-config'`; no migration needed for the current demo |
+
+---
+
+## 9. Operator surface
+
+```
+meshbay-node operator pair                  # print a pairing code for a browser
+meshbay-node member list [--group G]        # roster: who is pinned, role, status
+meshbay-node member invite bob [--group G]  # same as the SPA button, from SSH
+meshbay-node member revoke bob [--group G]  # stop serving the GEK to bob
+meshbay-node member unpin bob               # force re-pairing after a key rotation
+```
+
+`--group` is optional whenever the node hosts exactly one group.
+
+`meshbay-node status` gains a line per group: pinned identities, pending invites,
+and — when nothing is paired — the exact command to fix it. Everything an operator
+needs is reachable over SSH with no browser on the host, per the standing
+constraint. This absorbs milestones 14.3 and 14.4.
+
+---
+
+## 9bis. Implementation status
+
+**Slices 1 and 2 landed 2026-08-13/14.** Not yet exercised against a live
+deployment — the operator tests after slice 3, so the slices are written to be
+coherent with each other rather than individually demo-able.
+
+### Slice 1 — roster and operator pairing (M3)
+
+| Shipped | Where |
+|---|---|
+| `identities` / `members` / `invites`, codes, single-use redemption | `meshbay_node/roster.py` |
+| `join_transcript` — both public keys signed together | `meshbay_common/join.py` |
+| `join_request` / `join_result` handler, valid pre-proof and post-handshake | `transport/webrtc_server.py` |
+| Admin authority read from the roster on every check, `admin_pk_ed25519` kept as legacy | `webrtc_server._verify_admin_sig` |
+| **Auto-pin of the keystore key deleted** (M3) | `daemon._legacy_admin_pk` |
+| `meshbay-node operator pair`, roster in `status` | `daemon.main`, `ui/app.py` |
+| Pairing form in the group's Members tab | `app.js`, `transport.js` |
+
+### Slice 2 — the node wraps the key (H3)
+
+| Shipped | Where |
+|---|---|
+| Node wraps the GEK for the key the joiner proved, on every connection | `webrtc_server._join_ok` |
+| Roster decides who may receive it — hub membership alone does not | `Roster.is_authorized` |
+| `invite_create` admin op; the SPA shows a code instead of handling keys | `adminop.py`, `app.js` |
+| **`gek_bundle_store` deleted** — no member ever hands the node key material | `protocol.py`, `webrtc_server.py` |
+| **`gek-init` no longer fetches member keys from the hub** — it was H3 with the node as victim | `ui/app.py` |
+| Open-join groups admit without a code; policy read from `node.toml` | `config.py`, `_group_join_policy` |
+| Client asks for the key when it has none; prompts for a code when required | `transport.js`, `app.js` |
+
+**Tests: 148 node, 174 hub/common** (from 121/168 before this work). The end-to-end
+one worth knowing about is `test_invite_then_join_delivers_the_gek`: over a real
+DataChannel, the operator gets a code, and a member who has never held the group
+key redeems it in the pre-proof window and receives the key wrapped for a key only
+they can open.
+
+### Deliberate departures from this document
+
+| Written | Built | Why |
+|---|---|---|
+| `blake3(code)` | `sha256(code)` | 40 uniformly random bits; blake3 is not a node dependency |
+| Pairing in Settings | Pairing in the group's Members tab | that is where a live node connection exists |
+| — | `gek-init` rewritten | not in the plan: it wrapped the GEK for keys fetched from the hub, which is the same substitution the design closes |
+
+Two C5b tests were rewritten rather than kept: they asserted that
+`gek_bundle_store` demanded an operator signature, and that message no longer
+exists. They now assert the stronger property — that no member can hand the node
+key material at all, and that the retired message reaches no handler.
+
+### Slice 3 — the operator surface
+
+| Shipped | Where |
+|---|---|
+| `member list` / `invite` / `revoke` / `unpin`, all over SSH, no browser | `daemon.main` |
+| Roster endpoints behind the per-run session token (11.5.3) | `ui/app.py` |
+| Roster section in the local admin UI, every value escaped (H2) | `ui/app.py._render_roster` |
+| `_daemon_api` / `_resolve_group` — one loopback call path for every command | `daemon.py` |
+| Codes written to `data_dir/invite-code` and `data_dir/pair-code` | `roster.write_code_file` |
+
+Revocation tells the operator what it does **not** do: the ex-member stops
+receiving the key on their next connection, but they still hold the current one,
+so the message ends with the `gek-init` command that rotates it.
+
+`member revoke`/`unpin` resolve a username against the roster and refuse an
+unknown one rather than acting on nobody — a typo must not look like success.
+
+**Tests: 158 node, 174 hub/common** (from 121/168 before this work).
+
+### Code lifetimes (settled 2026-08-14)
+
+| Code | Default | Configurable via |
+|---|---|---|
+| Member invitation | **7 days** | `[node] invite_ttl_hours` |
+| Operator pairing | 24 h | `[node] pair_ttl_hours` |
+
+They differ because the acts differ: an invitation waits for someone to read their
+messages, a pairing code is typed during the SSH session that printed it. The
+longer window costs little — single use, one account, never seen by the hub, and
+40 bits do not fall to guessing in a week against the node-wide lockout.
+
+---
+
+## 10. Work to do
+
+### Node
+- `roster.py` — new module, the three tables and their queries
+- `transport/webrtc_server.py` — `join_request` / `join_result` in the pre-proof
+  window (beside the existing bundle fetches, `:243-258`); delete member-supplied
+  `gek_bundle_store`; `OP_INVITE_CREATE` in the admin-op dispatch
+- `transport/quic_server.py` — same handler via the shared path (11.5.4 parity test
+  must cover `join_request`)
+- `daemon.py` — `_resolve_admin_pk` → roster lookup with the legacy config fallback;
+  new CLI commands; `status` output
+- `ui/app.py` — roster and invites in the local admin UI, escaped as per 11.5.16
+
+### Common
+- `protocol.py` — four message constants
+- `adminop.py` — `OP_INVITE_CREATE`
+- `handshake.py` — expose `nonce_s` to the join transcript builder
+
+### Hub
+- **No change.** Membership endpoints stay as they are. Worth stating in the commit
+  message: the fix for H3 removes a hub responsibility rather than adding one.
+
+### SPA
+- Invite dialog shows the code and a copy button, instead of doing crypto
+- Settings gains "Pair this browser with my node" (code entry)
+- `join_request` on connect when no GEK is held; drop the wrap-and-store path
+- Delete the `pubkeys` fetch from the invite flow — the line that is H3
+
+### Tests (negative assertions, per §10 of v5)
+```
+test_join_requires_code_first_time      — unpinned identity without a code is refused
+test_join_rejects_key_swap              — pinned user presenting a new key is refused
+test_join_replay_across_connections     — join_request bound to nonce_s
+test_invite_requires_operator_role
+test_gek_never_wrapped_for_hub_supplied_key  — the H3 regression test
+test_revoked_member_gets_no_gek
+test_code_bruteforce_bounded
+test_open_join_group_pins_on_first_contact   — no code required, TOFU pin recorded
+test_invite_group_still_requires_code        — public visibility does not skip it
+```
+
+### Docs to rewrite
+- `meshbay-draft-v5.md` §2 (H3 row in the claims table), §5.1 (the "a group admin
+  who does not run the node can no longer invite" consequence is reversed), §9
+  (H3 moves to closed; note what remains open — T3, C4)
+- `devel-phases-next.md` — Phase 12.1 becomes this; 14.3/14.4 absorbed
+- `second-review.md` — H3 and M3 marked closed by this design
+- `QE/deploy/README.md` — `demo.py set-admin-pk` retired in favour of `operator pair`
+
+---
+
+## 11. Decisions
+
+Settled 2026-08-13 with the operator:
+
+| # | Question | Decision |
+|---|---|---|
+| 1 | Groups that skip the pairing code | **`join_policy == "open"` only** — asked as "public groups"; corrected to the admission axis, since `visibility` governs discoverability, not entry (§3.4) |
+| 2 | Delegation (group admin ≠ node operator) | **Deferred.** Role value reserved, authorization written as a role check so it drops in later (§6.2) |
+| 3 | Code TTL and length | 24 h, 40 bits, `XXXX-XXXX`. Default unless the first real use says otherwise |
+| 4 | `gek_bundle_store` from members | Deleted, not disabled — it is the C5b surface and keeping it dead-but-present invites its return |
+
+Items 3 and 4 are defaults chosen for v1, not constraints; both are one-line changes
+if the deployment argues against them.
diff --git a/packages/meshbay-common/src/meshbay_common/adminop.py b/packages/meshbay-common/src/meshbay_common/adminop.py
index 71446ca..2d90102 100644
--- a/packages/meshbay-common/src/meshbay_common/adminop.py
+++ b/packages/meshbay-common/src/meshbay_common/adminop.py
@@ -34,7 +34,12 @@ ADMIN_TRANSCRIPT_PREFIX = b"meshbay:admin:v1"
 
 # Operations that require node-operator authority.
 OP_FILE_DELETE = "file_delete"
-OP_GEK_BUNDLE_STORE = "gek_bundle_store"
+OP_INVITE_CREATE = "invite_create"
+# OP_GEK_BUNDLE_STORE is gone. Members no longer hand the node key material at
+# all: the node holds the GEK and wraps it itself, for a key the recipient proved
+# they hold (see `join.py` and docs/invite-pairing-v1.md). The operation existed
+# only to make member-supplied bundles safe, and deleting the message is a
+# stronger guarantee than authorizing it.
 
 # A challenge older than this is refused, so a signature captured from a stale
 # exchange cannot be replayed later.
@@ -53,7 +58,7 @@ def admin_transcript(
     Build the exact byte string signed for an admin operation.
 
     `subject` identifies what is being acted on: a file_id for OP_FILE_DELETE, the
-    target user_id for OP_GEK_BUNDLE_STORE.
+    invitee's user_id for OP_INVITE_CREATE.
     """
     fields = [
         op.encode(),
diff --git a/packages/meshbay-common/src/meshbay_common/join.py b/packages/meshbay-common/src/meshbay_common/join.py
new file mode 100644
index 0000000..6ee543f
--- /dev/null
+++ b/packages/meshbay-common/src/meshbay_common/join.py
@@ -0,0 +1,63 @@
+"""
+Join and pairing transcript (MNP).
+
+A client proves, in one signature, that the X25519 key it wants the group key
+wrapped for belongs to the Ed25519 identity the node pins. Both keys travel inside
+the transcript, so the identity key vouches for the encryption key it is paired
+with — that is what makes "wrap the GEK for the key the peer presented" safe.
+
+Why this exists at all (H3): the invite flow used to fetch the invitee's public key
+from the hub and wrap the group key for whatever came back. The hub is the key
+directory, so a hub answering with its own key was handed the GEK by an honest
+inviter following the protocol exactly. The key now comes from the peer over an
+authenticated channel and is bound to an identity by a one-time pairing code the
+hub never sees. See `docs/invite-pairing-v1.md`.
+
+Fields are length-prefixed and domain-separated, per L4 — the same rule as
+`handshake.py` and `adminop.py`. `nonce_node` is the handshake nonce the node just
+issued, so a signed join cannot be lifted onto another connection.
+"""
+
+from __future__ import annotations
+
+JOIN_PREFIX = b"meshbay:join:v1"
+
+# A join older than this is refused. Same value as the admin challenge: both are
+# interactive exchanges that complete in milliseconds.
+JOIN_TTL = 120  # seconds
+
+ROLE_OPERATOR = "operator"
+ROLE_DELEGATE = "delegate"   # reserved; delegation is deferred (§6.2 of the design)
+ROLE_MEMBER = "member"
+
+
+def join_transcript(
+    node_pk_b64: str,
+    group_id: str,
+    user_id: str,
+    pk_ed25519_b64: str,
+    pk_x25519_b64: str,
+    nonce_node: bytes,
+    ts: int,
+) -> bytes:
+    """
+    Bytes signed by a client asking to be pinned by, or recognised on, a node.
+
+    `group_id` is empty for operator pairing, which is node-wide rather than
+    per-group. The node builds this from its own state and the values in the
+    message; nothing signed is ever taken from the wire unverified.
+    """
+    fields = [
+        node_pk_b64.encode(),
+        group_id.encode(),
+        user_id.encode(),
+        pk_ed25519_b64.encode(),
+        pk_x25519_b64.encode(),
+        nonce_node,
+        str(ts).encode(),
+    ]
+    out = bytearray(JOIN_PREFIX)
+    for field in fields:
+        out += len(field).to_bytes(4, "big")
+        out += field
+    return bytes(out)
diff --git a/packages/meshbay-common/src/meshbay_common/protocol.py b/packages/meshbay-common/src/meshbay_common/protocol.py
index d86b4ef..510813a 100644
--- a/packages/meshbay-common/src/meshbay_common/protocol.py
+++ b/packages/meshbay-common/src/meshbay_common/protocol.py
@@ -46,12 +46,18 @@ class MNP:
     HANDSHAKE_RESPONSE   = "handshake_response"    # client → node: HMAC(GEK, nonce)
     ADMIN_CHALLENGE      = "admin_challenge"       # node → client: Ed25519 sign challenge
     ADMIN_RESPONSE       = "admin_response"        # client → node: Ed25519 signature
-    GEK_BUNDLE_STORE     = "gek_bundle_store"      # client → node: store wrapped GEK for a user
+    # GEK_BUNDLE_STORE was removed with the invite redesign: the node wraps the GEK
+    # itself, for a key the recipient proved possession of, so no member ever hands
+    # the node key material (C5b, and the H3 substitution it enabled).
     GEK_BUNDLE_FETCH     = "gek_bundle_fetch"      # client → node: request own wrapped GEK
     GEK_BUNDLE_RESP      = "gek_bundle_resp"       # node → client: wrapped GEK bundle
     KEYPAIR_BUNDLE_STORE = "keypair_bundle_store"  # client → node: store encrypted keypair bundle
     KEYPAIR_BUNDLE_FETCH = "keypair_bundle_fetch"  # client → node: request own keypair bundle
     KEYPAIR_BUNDLE_RESP  = "keypair_bundle_resp"   # node → client: encrypted keypair bundle
+    JOIN_REQUEST         = "join_request"          # client → node: pair/recognise this identity
+    JOIN_RESULT          = "join_result"           # node → client: outcome + wrapped GEK
+    INVITE_CREATE        = "invite_create"         # operator → node: issue a pairing code
+    INVITE_RESULT        = "invite_result"         # node → operator: the code, once
 
 
 # ── Index entry ───────────────────────────────────────────────────────────────
diff --git a/packages/meshbay-common/tests/test_js_python_parity.py b/packages/meshbay-common/tests/test_js_python_parity.py
index 9adac51..340ea3e 100644
--- a/packages/meshbay-common/tests/test_js_python_parity.py
+++ b/packages/meshbay-common/tests/test_js_python_parity.py
@@ -22,6 +22,7 @@ import pytest
 
 from meshbay_common.adminop import admin_transcript
 from meshbay_common.handshake import handshake_transcript, webrtc_binding
+from meshbay_common.join import join_transcript
 
 CRYPTO_JS = (Path(__file__).resolve().parents[2]
              / "meshbay-hub" / "src" / "meshbay_hub" / "static" / "crypto.js")
@@ -52,6 +53,18 @@ ADMIN_VECTORS = [
     ("file_delete", "Tk9ERVBL", "café", "fichier é.mp4", "04" * 32, 1_700_000_002),
 ]
 
+# (node_pk_b64, group_id, user_id, pk_ed b64, pk_x b64, nonce hex, ts)
+JOIN_VECTORS = [
+    # Operator pairing: group_id is empty and must stay distinguishable from a
+    # request that names a group.
+    ("Tk9ERVBL", "", "grenet", "QUFB", "QkJC", "01" * 32, 1_700_000_000),
+    ("Tk9ERVBL", "g" * 32, "grenet", "QUFB", "QkJC", "01" * 32, 1_700_000_000),
+    # Identical to the previous vector except that the two keys are swapped —
+    # they are adjacent fields, so this isolates the ordering.
+    ("Tk9ERVBL", "g" * 32, "grenet", "QkJC", "QUFB", "01" * 32, 1_700_000_000),
+    ("Tk9ERVBL", "café", "utilisateur-é", "QUFB", "QkJC", "03" * 32, 0),
+]
+
 _HARNESS = r"""
 const fs = require('fs');
 
@@ -62,7 +75,8 @@ globalThis.crypto = globalThis.crypto || {};
 
 const src = fs.readFileSync(process.argv[2], 'utf8');
 const load = new Function(
-  src + '\nreturn { handshakeTranscript, adminTranscript, webrtcBinding, b64encode };');
+  src + '\nreturn { handshakeTranscript, adminTranscript, joinTranscript, '
+      + 'webrtcBinding, b64encode };');
 const M = load();
 
 const hex = (s) => {
@@ -74,7 +88,7 @@ const toHex = (u8) =>
   Array.from(u8).map(b => b.toString(16).padStart(2, '0')).join('');
 
 const input = JSON.parse(fs.readFileSync(process.argv[3], 'utf8'));
-const out = { handshake: [], admin: [] };
+const out = { handshake: [], admin: [], join: [] };
 
 for (const v of input.handshake) {
   const binding = M.webrtcBinding(hex(v.offer_fp), hex(v.answer_fp));
@@ -87,6 +101,11 @@ for (const v of input.admin) {
     v.op, v.node_pk, v.group_id, v.subject, M.b64encode(hex(v.nonce)), v.ts)));
 }
 
+for (const v of input.join) {
+  out.join.push(toHex(M.joinTranscript(
+    v.node_pk, v.group_id, v.user_id, v.pk_ed, v.pk_x, hex(v.nonce), v.ts)));
+}
+
 process.stdout.write(JSON.stringify(out));
 """
 
@@ -110,6 +129,11 @@ def js_output(tmp_path_factory):
              "subject": s, "nonce": n, "ts": ts}
             for op, pk, g, s, n, ts in ADMIN_VECTORS
         ],
+        "join": [
+            {"node_pk": pk, "group_id": g, "user_id": u,
+             "pk_ed": pe, "pk_x": px, "nonce": n, "ts": ts}
+            for pk, g, u, pe, px, n, ts in JOIN_VECTORS
+        ],
     }))
 
     proc = subprocess.run(
@@ -164,6 +188,43 @@ def test_admin_transcript_parity(idx, vector, js_output):
     )
 
 
+@pytest.mark.parametrize("idx,vector", list(enumerate(JOIN_VECTORS)))
+def test_join_transcript_parity(idx, vector, js_output):
+    """
+    A mismatch here means no browser can pair with a node and no member can be
+    recognised — the node would reject every signature as invalid, and, as with
+    the other two, nothing else in the suite crosses this boundary.
+    """
+    node_pk, group_id, user_id, pk_ed, pk_x, nonce, ts = vector
+
+    expected = join_transcript(
+        node_pk_b64=node_pk,
+        group_id=group_id,
+        user_id=user_id,
+        pk_ed25519_b64=pk_ed,
+        pk_x25519_b64=pk_x,
+        nonce_node=bytes.fromhex(nonce),
+        ts=ts,
+    )
+    assert js_output["join"][idx] == expected.hex(), (
+        f"crypto.js and meshbay_common.join disagree for user={user_id!r} "
+        f"group={group_id!r}"
+    )
+
+
+def test_join_transcript_binds_the_two_keys_in_order(js_output):
+    """
+    The X25519 key is trusted only because the Ed25519 identity signed it, so the
+    two must not be interchangeable: swapping them has to produce different bytes.
+    """
+    assert js_output["join"][1] != js_output["join"][2]
+
+
+def test_operator_pairing_is_distinguishable_from_a_group_join(js_output):
+    """An empty group_id (node-wide operator authority) must not collide."""
+    assert js_output["join"][0] != js_output["join"][1]
+
+
 def test_length_prefixing_actually_disambiguates(js_output):
     """
     The reason both sides length-prefix: two different field splits must not collide.
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/app.js b/packages/meshbay-hub/src/meshbay_hub/static/app.js
index a006dfe..1ef878a 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/app.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/app.js
@@ -68,6 +68,9 @@ async function getAllCachedIndexes() {
 let _sessionKeys = null;
 let _bundleKey = null;
 let _pendingBundlePush = null;
+// A one-time pairing code the user just typed, consumed by the next connection
+// attempt. Deliberately not persisted: it is single-use and short-lived.
+let _pendingJoinCode = null;
 
 function _openKeyDB() {
   return new Promise((resolve, reject) => {
@@ -778,9 +781,23 @@ function GroupPage({ groupId, group, token, username, userId }) {
   const [uploading, setUploading] = useState(false);
   const [menuOpen, setMenuOpen] = useState(null);
   const [isNodeAdmin, setIsNodeAdmin] = useState(false);
+  const [needsCode, setNeedsCode] = useState(false);
+  const [codeInput, setCodeInput] = useState('');
+  const [retryKey, setRetryKey] = useState(0);
   const transportRef = useRef(null);
   const gekRef = useRef(null);
 
+  const submitJoinCode = useCallback((e) => {
+    e.preventDefault();
+    const code = codeInput.trim();
+    if (!code) return;
+    _pendingJoinCode = code;
+    setCodeInput('');
+    setNeedsCode(false);
+    setError('');
+    setRetryKey(k => k + 1);
+  }, [codeInput]);
+
   useEffect(() => {
     if (menuOpen === null) return;
     const close = () => setMenuOpen(null);
@@ -812,9 +829,12 @@ function GroupPage({ groupId, group, token, username, userId }) {
           return;
         }
 
-        // Session keys for P2P GEK bundle fetch (node delivers wrapped GEK)
+        // Session keys for the P2P key exchange. skEdB64 belongs here too: the
+        // node identifies us by the Ed25519 identity, and join_request signs both
+        // public keys with it — without it we can neither join nor pair.
         const sessionKeys = _sessionKeys ? {
           skXB64: _sessionKeys.skXB64,
+          skEdB64: _sessionKeys.skEdB64,
           pkXB64: _sessionKeys.pkXB64,
         } : null;
 
@@ -824,7 +844,9 @@ function GroupPage({ groupId, group, token, username, userId }) {
         transportRef.current = transport;
 
         const ack = await transport.connect(
-          nodeId, token, groupId, null, sessionKeys, _bundleKey, username);
+          nodeId, token, groupId, null, sessionKeys, _bundleKey, username,
+          userId, _pendingJoinCode);
+        _pendingJoinCode = null;
         if (cancelled) return;
         setIsNodeAdmin(!!ack.is_node_admin);
 
@@ -881,6 +903,10 @@ function GroupPage({ groupId, group, token, username, userId }) {
         cacheGroupIndex(groupId, group ? group.name : groupId, freshEntries);
       } catch (err) {
         if (!cancelled) {
+          // The node has never seen this browser for this account: it needs a
+          // one-time code from the operator before it will hand over the group
+          // key. Not an error to shout about — a step in joining.
+          if (err.reason === 'code_required') setNeedsCode(true);
           setError(err.message);
           setStatus('error');
         }
@@ -902,7 +928,7 @@ function GroupPage({ groupId, group, token, username, userId }) {
         transportRef.current = null;
       }
     };
-  }, [groupId, token]);
+  }, [groupId, token, retryKey]);
 
   const downloadFile = useCallback(async (entry) => {
     const transport = transportRef.current;
@@ -1079,6 +1105,17 @@ function GroupPage({ groupId, group, token, username, userId }) {
         `}
       </div>
       ${error && html`<div class="error-msg" style="margin-bottom:12px">${error}</div>`}
+      ${needsCode && html`
+        <form class="invite-form" style="margin-bottom:12px" onSubmit=${submitJoinCode}>
+          <h4>${t('group.join_code_title')}</h4>
+          <p class="settings-hint">${t('group.join_code_hint')}</p>
+          <div style="display:flex;gap:8px">
+            <input type="text" placeholder="XXXX-XXXX" style="font-family:monospace"
+              value=${codeInput} onInput=${e => setCodeInput(e.target.value)} required />
+            <button class="admin-btn" type="submit">${t('group.join_code_btn')}</button>
+          </div>
+        </form>
+      `}
       ${dlState && html`
         <div class="dl-bar">
           <span class="dl-name">${dlState.name}</span>
@@ -1224,7 +1261,8 @@ function GroupPage({ groupId, group, token, username, userId }) {
 
         ${tab === 'members' && html`
           <${MembersPanel} groupId=${groupId} group=${group} token=${token}
-            transportRef=${transportRef} gekRef=${gekRef} />
+            transportRef=${transportRef} gekRef=${gekRef}
+            isNodeAdmin=${isNodeAdmin} userId=${userId} />
         `}
       `}
       ${status === 'offline' && html`
@@ -1365,13 +1403,41 @@ function _b64ToU8(b64) {
 
 // ── Members Panel ────────────────────────────────────────────────────────
 
-function MembersPanel({ groupId, group, token, transportRef, gekRef }) {
+function MembersPanel({ groupId, group, token, transportRef, gekRef,
+                       isNodeAdmin, userId }) {
   const [members, setMembers] = useState([]);
   const [adminId, setAdminId] = useState('');
   const [loading, setLoading] = useState(true);
   const [inviteUser, setInviteUser] = useState('');
   const [inviting, setInviting] = useState(false);
   const [error, setError] = useState('');
+  const [inviteCode, setInviteCode] = useState(null);
+  const [pairCode, setPairCode] = useState('');
+  const [pairStatus, setPairStatus] = useState('');
+  const [pairing, setPairing] = useState(false);
+
+  // Pairing lives here rather than in Settings because this is where a live
+  // connection to the node exists — and it is offered only when the node itself
+  // says this account is its operator (is_node_admin comes from the authenticated
+  // handshake_ack, not from the hub).
+  const doPair = useCallback(async (e) => {
+    e.preventDefault();
+    const code = pairCode.trim();
+    if (!code) return;
+    setPairing(true);
+    setPairStatus('');
+    try {
+      const transport = transportRef && transportRef.current;
+      if (!transport || !transport.connected) throw new Error('Not connected to the node');
+      await transport.pairOperator(userId, code);
+      setPairCode('');
+      setPairStatus('paired');
+    } catch (err) {
+      setPairStatus(err.message);
+    } finally {
+      setPairing(false);
+    }
+  }, [pairCode, transportRef, userId]);
 
   const loadMembers = useCallback(() => {
     setLoading(true);
@@ -1393,36 +1459,34 @@ function MembersPanel({ groupId, group, token, transportRef, gekRef }) {
     if (!inviteUser.trim()) return;
     setInviting(true);
     setError('');
+    setInviteCode(null);
     try {
       const transport = transportRef && transportRef.current;
       const username = inviteUser.trim();
-
-      // Fetch invitee's public keys (hub = public key directory)
-      const pubkeys = await hubFetch(`/v1/users/${username}/pubkeys`, { token });
-      const pkXBytes = Uint8Array.from(atob(pubkeys.pk_x25519), c => c.charCodeAt(0));
-
-      // Get raw GEK from the active transport connection
-      if (!transport || !transport.connected || !transport.gekRaw) {
-        throw new Error('Not connected to node or no GEK available');
+      if (!transport || !transport.connected) {
+        throw new Error('Not connected to the node — it must be online to invite');
       }
-      const gekBytes = transport.gekRaw;
 
-      // Wrap GEK for invitee and store on node via P2P.
-      // The node requires the operator's Ed25519 signature to accept the bundle
-      // (C5b), so inviting from a browser that is not the node operator's will be
-      // refused by the node — deliberately: only the operator decides what is
-      // stored on their machine.
+      // The hub is asked for the account id, and nothing else. It is no longer
+      // asked for the invitee's public key: the node wraps the group key itself,
+      // for a key the invitee proves possession of when they connect (H3). A hub
+      // that answered with the wrong account here would produce an invite whose
+      // code it never learns — the code goes to a human, out of band.
+      const account = await hubFetch(`/v1/users/${username}/pubkeys`, { token });
+
       const signFn = (_sessionKeys && window.MeshBayKeys)
         ? (transcript) => window.MeshBayKeys.signBytes(_sessionKeys.skEdB64, transcript)
         : null;
-      const bundle = await window.MeshBayCrypto.wrapGEK(gekBytes, pkXBytes);
-      await transport.storeGekBundle(pubkeys.user_id, groupId, bundle, signFn);
+      const result = await transport.createInvite(
+        account.user_id, groupId, username, signFn);
 
-      // Add member on hub (membership management only)
+      // Membership on the hub is what lets them reach the node at all; the code
+      // is what gets them the key.
       await hubFetch(`/v1/groups/${groupId}/members/${username}`, {
         method: 'POST', token, body: {},
       });
 
+      setInviteCode({ username, code: result.code, expires: result.expires_at });
       setInviteUser('');
       loadMembers();
     } catch (err) {
@@ -1430,7 +1494,7 @@ function MembersPanel({ groupId, group, token, transportRef, gekRef }) {
     } finally {
       setInviting(false);
     }
-  }, [groupId, token, inviteUser, loadMembers]);
+  }, [groupId, token, inviteUser, loadMembers, transportRef]);
 
   if (loading) return html`<p class="page-message">${t('explore.loading')}</p>`;
 
@@ -1461,6 +1525,15 @@ function MembersPanel({ groupId, group, token, transportRef, gekRef }) {
         <form class="invite-form" onSubmit=${doInvite}>
           <h4>${t('members.invite_title')}</h4>
           ${error && html`<p class="error-msg">${error}</p>`}
+          ${inviteCode && html`
+            <div class="success-msg" style="margin-bottom:8px">
+              <p>${t('members.invite_code_ready', { user: inviteCode.username })}</p>
+              <p style="font-family:monospace;font-size:1.4em;letter-spacing:2px;margin:6px 0">
+                ${inviteCode.code}
+              </p>
+              <p>${t('members.invite_code_hint')}</p>
+            </div>
+          `}
           <div style="display:flex;gap:8px">
             <input type="text" placeholder="${t('members.username_placeholder')}"
               value=${inviteUser} onInput=${e => setInviteUser(e.target.value)} required />
@@ -1470,6 +1543,24 @@ function MembersPanel({ groupId, group, token, transportRef, gekRef }) {
           </div>
         </form>
       `}
+      ${isNodeAdmin && html`
+        <form class="invite-form" onSubmit=${doPair}>
+          <h4>${t('members.pair_title')}</h4>
+          <p class="settings-hint">${t('members.pair_hint')}</p>
+          ${pairStatus && html`
+            <p class=${pairStatus === 'paired' ? 'success-msg' : 'error-msg'}>
+              ${pairStatus === 'paired' ? t('members.pair_success') : pairStatus}
+            </p>
+          `}
+          <div style="display:flex;gap:8px">
+            <input type="text" placeholder="XXXX-XXXX" style="font-family:monospace"
+              value=${pairCode} onInput=${e => setPairCode(e.target.value)} required />
+            <button class="admin-btn" type="submit" disabled=${pairing}>
+              ${pairing ? '...' : t('members.pair_btn')}
+            </button>
+          </div>
+        </form>
+      `}
     </div>
   `;
 }
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/crypto.js b/packages/meshbay-hub/src/meshbay_hub/static/crypto.js
index d18eeae..21bf05d 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/crypto.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/crypto.js
@@ -314,6 +314,31 @@ async function handshakeProof(gekRaw, role, groupId, nonceClient, nonceNode, bin
   return new Uint8Array(sig);
 }
 
+// ── Join / pairing transcript ───────────────────────────────────────────────
+
+// Mirrors meshbay_common/join.py. Signing both of our public keys together binds
+// the X25519 key to the Ed25519 identity the node pins, so the node can safely
+// wrap the group key for a key that came over the wire instead of one fetched
+// from the hub's directory (H3). nonce_node ties it to this connection.
+const JOIN_PREFIX = new TextEncoder().encode('meshbay:join:v1');
+
+function joinTranscript(nodePkB64, groupId, userId, pkEdB64, pkXB64, nonceNode, ts) {
+  const enc = new TextEncoder();
+  const body = _lenPrefixed([
+    enc.encode(nodePkB64),
+    enc.encode(groupId),
+    enc.encode(userId),
+    enc.encode(pkEdB64),
+    enc.encode(pkXB64),
+    nonceNode,
+    enc.encode(String(ts)),
+  ]);
+  const out = new Uint8Array(JOIN_PREFIX.length + body.length);
+  out.set(JOIN_PREFIX, 0);
+  out.set(body, JOIN_PREFIX.length);
+  return out;
+}
+
 function constantTimeEqual(a, b) {
   if (a.length !== b.length) return false;
   let diff = 0;
@@ -333,5 +358,5 @@ window.MeshBayCrypto = {
   importGEK, deriveChunkKey, decryptChunk, decryptChunkBin, decryptFile,
   generateGEK, wrapGEK, unwrapGEK, encryptChunk, b64encode, b64decode,
   adminTranscript, handshakeTranscript, handshakeProof, webrtcBinding,
-  verifyNodeSignature, constantTimeEqual,
+  joinTranscript, verifyNodeSignature, constantTimeEqual,
 };
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/i18n.js b/packages/meshbay-hub/src/meshbay_hub/static/i18n.js
index b0de4b9..c279fd1 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/i18n.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/i18n.js
@@ -240,6 +240,22 @@ const en = {
   'members.invite_title': 'Invite member',
   'members.username_placeholder': 'Username',
   'members.invite_btn': 'Invite',
+  'members.pair_title': 'Pair this browser with your node',
+  'members.pair_hint': 'Your node only accepts operator actions — invites, file '
+    + 'deletion — from a browser it has been paired with. Run '
+    + '`meshbay-node operator pair` on the node and type the code here. The code '
+    + 'never passes through the hub, which is what stops the hub from claiming to '
+    + 'be you.',
+  'members.pair_btn': 'Pair',
+  'members.pair_success': 'This browser is now paired with the node.',
+  'members.invite_code_ready': 'Invitation code for {user} — send it to them the way '
+    + 'you normally talk. It works once, and it never passes through the hub.',
+  'members.invite_code_hint': 'They enter it the first time they open this group. '
+    + 'You do not need to be online then.',
+  'group.join_code_title': 'This node needs to recognise you',
+  'group.join_code_hint': 'Ask whoever invited you for the one-time code, and enter '
+    + 'it here. After that this browser is recognised and you will not be asked again.',
+  'group.join_code_btn': 'Join',
 
   'notif.title': 'Notifications',
   'notif.empty': 'No notifications',
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/style.css b/packages/meshbay-hub/src/meshbay_hub/static/style.css
index e430201..81c4130 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/style.css
+++ b/packages/meshbay-hub/src/meshbay_hub/static/style.css
@@ -316,6 +316,21 @@ button:disabled { opacity: 0.5; cursor: not-allowed; }
   font-size: 0.85em;
 }
 
+.success-msg {
+  background: #16a34a20;
+  color: var(--success);
+  border: 1px solid var(--success);
+  border-radius: 6px;
+  padding: 8px 12px;
+  font-size: 0.85em;
+}
+
+.settings-hint {
+  font-size: 0.85em;
+  color: var(--text-dim);
+  margin-bottom: 8px;
+}
+
 /* ── Group cards (9.7 prep) ───────────────────────────────────────────────── */
 
 .group-grid {
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/transport.js b/packages/meshbay-hub/src/meshbay_hub/static/transport.js
index 50304f3..0bffeae 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/transport.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/transport.js
@@ -26,6 +26,31 @@ async function _pkFromSk(skPkcs8B64) {
   return pad ? b64 + '='.repeat(4 - pad) : b64;
 }
 
+async function _pkEdFromSk(skPkcs8B64) {
+  const raw = Uint8Array.from(atob(skPkcs8B64), c => c.charCodeAt(0));
+  const sk = await crypto.subtle.importKey('pkcs8', raw, { name: 'Ed25519' }, true, ['sign']);
+  const jwk = await crypto.subtle.exportKey('jwk', sk);
+  const b64 = jwk.x.replace(/-/g, '+').replace(/_/g, '/');
+  const pad = b64.length % 4;
+  return pad ? b64 + '='.repeat(4 - pad) : b64;
+}
+
+const JOIN_REFUSALS = {
+  code_required: 'This node does not know this browser yet. Ask the node operator '
+    + 'for a pairing code (meshbay-node operator pair).',
+  code_invalid: 'That pairing code is not valid — it may be mistyped, expired, '
+    + 'already used, or issued for a different account.',
+  key_changed: 'This account is already paired with a different key on this node. '
+    + 'If you reset your keys, the operator must unpin you before pairing again.',
+  not_authorized_for_group: 'The node does not list you as a member of this group. '
+    + 'Being a member on the hub is not enough — ask the operator for an invite.',
+  no_gek: 'This group has no key yet. The node operator must run '
+    + '`meshbay-node gek-init` for it.',
+  signature_invalid: 'The node rejected the signature over your keys.',
+  stale_request: 'Your clock is too far from the node\'s — check the system time.',
+  group_mismatch: 'The node refused a request naming a different group.',
+};
+
 class MeshBayTransport {
   constructor(hubUrl, accessToken) {
     this._hubUrl = hubUrl;
@@ -53,11 +78,14 @@ class MeshBayTransport {
 
   get sessionKeys() { return this._sessionKeys; }
 
-  async connect(nodeId, jwtToken, groupId, gekRaw, sessionKeys, bundleKey, username) {
+  async connect(nodeId, jwtToken, groupId, gekRaw, sessionKeys, bundleKey, username,
+                userId, joinCode) {
     this._gekRaw = gekRaw || null;
     this._sessionKeys = sessionKeys || null;
     this._bundleKey = bundleKey || null;
     this._username = username || null;
+    this._userId = userId || null;
+    this._joinError = null;
     this._pc = new RTCPeerConnection({
       iceServers: [{ urls: 'stun:stun.l.google.com:19302' }],
     });
@@ -191,8 +219,22 @@ class MeshBayTransport {
         }
       }
 
+      // No stored bundle: ask the node to recognise us and wrap the key itself.
+      // This is the normal path for anyone who joined after the invite redesign —
+      // no bundle is pre-stored for members any more. A code is needed only the
+      // first time this node sees this account.
+      if (!gekRaw && this._sessionKeys && userId) {
+        try {
+          gekRaw = await this.joinGroup(userId, groupId, joinCode);
+        } catch (e) {
+          // The UI turns this into "ask the operator for an invite code".
+          this._joinError = e;
+        }
+      }
+
       if (!gekRaw) {
-        throw new Error('Node requires GEK proof but no GEK available');
+        throw this._joinError
+          || new Error('Node requires GEK proof but no GEK available');
       }
 
       const C = window.MeshBayCrypto;
@@ -203,6 +245,9 @@ class MeshBayTransport {
         _extractDtlsFingerprint(this._rawAnswerSdp),
       );
       const nonceNode = C.b64decode(reply.nonce);
+      // Kept for the life of the connection: a join_request is signed over it,
+      // which is what stops one being lifted onto another connection.
+      this._nonceNode = nonceNode;
       const gid = groupId || '';
 
       const proof = await C.handshakeProof(
@@ -249,6 +294,59 @@ class MeshBayTransport {
       'MNP handshake rejected: ' + (reply.detail || `unexpected ${reply.type}`));
   }
 
+  /**
+   * Pair this browser with the node using a one-time code (M3, and the same
+   * substitution as H3).
+   *
+   * The node has no way to know which key belongs to its operator unless someone
+   * tells it locally — asking the hub would let the hub name itself node
+   * administrator. The code comes from `meshbay-node operator pair`, over SSH, and
+   * the hub never sees it.
+   */
+  async pairOperator(userId, code) {
+    if (!this._connected) throw new Error('Not connected to the node');
+    if (!userId) throw new Error('Missing user id');
+    if (!this._sessionKeys || !this._sessionKeys.skEdB64 || !this._sessionKeys.skXB64) {
+      throw new Error('Identity keys unavailable in this browser — sign in again');
+    }
+    if (!this._nonceNode || !this.nodePk) {
+      throw new Error('Handshake incomplete — reconnect and retry');
+    }
+
+    const C = window.MeshBayCrypto;
+    // Both public keys are derived from OUR OWN secret keys, never read back from
+    // the hub: signing a public key the directory handed us would reintroduce the
+    // substitution this whole mechanism exists to close.
+    const pkEdB64 = await _pkEdFromSk(this._sessionKeys.skEdB64);
+    const pkXB64 = await _pkFromSk(this._sessionKeys.skXB64);
+    const ts = Math.floor(Date.now() / 1000);
+
+    // group_id is empty: operator authority is node-wide, not per group.
+    const transcript = C.joinTranscript(
+      this.nodePk, '', userId, pkEdB64, pkXB64, this._nonceNode, ts);
+    const sig = await window.MeshBayKeys.signBytes(this._sessionKeys.skEdB64, transcript);
+
+    const resp = await this._sendAndWait({
+      type: 'join_request',
+      v: '0.1',
+      group_id: '',
+      pk_ed25519: pkEdB64,
+      pk_x25519: pkXB64,
+      code: code || '',
+      ts,
+      sig,
+    });
+
+    if (resp.type === 'error') throw new Error(resp.detail || 'Pairing refused');
+    if (resp.type !== 'join_result' || !resp.ok) {
+      const reason = resp.reason || 'unknown';
+      const err = new Error(JOIN_REFUSALS[reason] || `Pairing refused: ${reason}`);
+      err.reason = reason;
+      throw err;
+    }
+    return resp;
+  }
+
   async fetchIndex() {
     const msg = await this._sendAndWait({ type: 'index_sync', v: '0.1' });
     if (msg.type === 'error') throw new Error(msg.detail);
@@ -364,30 +462,84 @@ class MeshBayTransport {
   }
 
   /**
-   * Store a wrapped GEK bundle on the node for a member.
+   * Ask the node for a one-time pairing code admitting `userId` to this group.
+   *
+   * This replaces wrapping the group key in the browser. We no longer fetch the
+   * invitee's public key from the hub, so the hub can no longer answer with its own
+   * and be handed the group key (H3). The node wraps the key later, itself, for a
+   * key the invitee proves possession of.
    *
-   * Node-operator operation: the node answers with an admin challenge and only the
-   * pinned operator key is accepted. Any member used to be able to write bundles —
-   * including one addressed to the operator, which the node then auto-adopted as the
-   * live group key (finding C5b).
+   * Returns {code, expires_at} — the code is displayed once and passed to the
+   * invitee out of band.
    */
-  async storeGekBundle(userId, groupId, bundle, signFn) {
+  async createInvite(userId, groupId, username, signFn) {
     const msg = await this._sendAndWait({
-      type: 'gek_bundle_store',
+      type: 'invite_create',
       v: '0.1',
       user_id: userId,
       group_id: groupId,
-      pk_eph_b64: bundle.pk_eph_b64,
-      nonce_b64: bundle.nonce_b64,
-      wrapped_b64: bundle.wrapped_b64,
+      username: username || '',
     });
     if (msg.type === 'error') throw new Error(msg.detail);
     if (msg.type === 'admin_challenge') {
-      return this._authorizeAdminOp(msg, 'gek_bundle_store', userId, signFn);
+      return this._authorizeAdminOp(msg, 'invite_create', userId, signFn);
     }
     return msg;
   }
 
+  /**
+   * Ask the node to recognise us and hand over the group key.
+   *
+   * Sent when we hold no GEK for a group. `code` is needed only the first time
+   * this node sees this account (and not at all in an open-join group).
+   */
+  async joinGroup(userId, groupId, code) {
+    if (!this._sessionKeys || !this._sessionKeys.skEdB64 || !this._sessionKeys.skXB64) {
+      throw new Error('Identity keys unavailable in this browser — sign in again');
+    }
+    if (!this._nonceNode || !this.nodePk) {
+      throw new Error('Handshake incomplete — reconnect and retry');
+    }
+
+    const C = window.MeshBayCrypto;
+    const pkEdB64 = await _pkEdFromSk(this._sessionKeys.skEdB64);
+    const pkXB64 = await _pkFromSk(this._sessionKeys.skXB64);
+    const ts = Math.floor(Date.now() / 1000);
+
+    const transcript = C.joinTranscript(
+      this.nodePk, groupId || '', userId, pkEdB64, pkXB64, this._nonceNode, ts);
+    const sig = await window.MeshBayKeys.signBytes(this._sessionKeys.skEdB64, transcript);
+
+    const resp = await this._sendAndWait({
+      type: 'join_request',
+      v: '0.1',
+      group_id: groupId || '',
+      pk_ed25519: pkEdB64,
+      pk_x25519: pkXB64,
+      code: code || '',
+      ts,
+      sig,
+    });
+
+    if (resp.type === 'error') throw new Error(resp.detail || 'Join refused');
+    if ((resp.type !== 'join_result' || !resp.ok) || !resp.gek) {
+      const reason = resp.reason || 'unknown';
+      const err = new Error(JOIN_REFUSALS[reason] || `Join refused: ${reason}`);
+      // The UI reacts to `code_required` by asking for one; everything else is
+      // shown as-is.
+      err.reason = reason;
+      throw err;
+    }
+
+    // Unwrap with our own secret key — the node wrapped for the public key we
+    // just proved we hold, so nobody else can open this.
+    const skXRaw = Uint8Array.from(atob(this._sessionKeys.skXB64), c => c.charCodeAt(0));
+    const myPkX = Uint8Array.from(atob(pkXB64), c => c.charCodeAt(0));
+    const gekRaw = await C.unwrapGEK(resp, skXRaw, myPkX);
+    this._gekRaw = gekRaw;
+    return gekRaw;
+  }
+
   async storeKeypairBundle(bundleEnc) {
     const msg = await this._sendAndWait({
       type: 'keypair_bundle_store',
diff --git a/packages/meshbay-node/src/meshbay_node/config.py b/packages/meshbay-node/src/meshbay_node/config.py
index b681355..04cb1d3 100644
--- a/packages/meshbay-node/src/meshbay_node/config.py
+++ b/packages/meshbay-node/src/meshbay_node/config.py
@@ -44,7 +44,10 @@ id          = ""
 name        = "Public Archive"
 shared_dir  = "/home/user/Archive"
 quic_port   = 19012
-visibility  = "public"
+visibility  = "public"       # discoverable on the hub
+# join_policy = "open"       # anyone the hub says is a member gets the group key,
+                             # with no pairing code. Only for groups where that is
+                             # genuinely intended: it means the hub can join too.
 
 [keystore]
 # unlock_file = "~/.config/meshbay/unlock.key"
@@ -74,7 +77,15 @@ class GroupConfig:
     id:         str = ""
     name:       str = ""
     shared_dir: str = ""
-    visibility: str = "private"   # public|private
+    visibility: str = "private"   # public|private — discoverability, not admission
+    # Admission. "invite" (default) means a newcomer needs a one-time pairing code
+    # before the node wraps the group key for them; "open" means the node pins
+    # whoever turns up first (TOFU) and serves them.
+    #
+    # Deliberately read from THIS file and never from the hub: a hub that could
+    # declare a group open would walk into any group it liked. Being findable
+    # (`visibility`) and being open (`join_policy`) are different questions.
+    join_policy: str = "invite"   # invite|open
     quic_port:  int = 19010       # QUIC MNP port
 
 
@@ -127,6 +138,7 @@ def load_config(path: Path = DEFAULT_CONFIG_PATH) -> Config:
                     name=g.get("name", ""),
                     shared_dir=g.get("shared_dir", ""),
                     visibility=g.get("visibility", "private"),
+                    join_policy=g.get("join_policy", "invite"),
                     quic_port=g.get("quic_port", cfg.node.quic_port),
                 ))
         # Back-compat: single [group] section
diff --git a/packages/meshbay-node/src/meshbay_node/daemon.py b/packages/meshbay-node/src/meshbay_node/daemon.py
index 46a1716..7f84abe 100644
--- a/packages/meshbay-node/src/meshbay_node/daemon.py
+++ b/packages/meshbay-node/src/meshbay_node/daemon.py
@@ -45,7 +45,8 @@ from meshbay_node.chat.store import ChatStore
 from meshbay_node.config import Config, DEFAULT_CONFIG_PATH, load_config, write_example_config
 from meshbay_node.hub_client import HubClient, HubConfig
 from meshbay_node.indexer import DirectoryIndexer
-from meshbay_node.keystore import NodeKeys, load_or_create_keystore
+from meshbay_node.keystore import load_or_create_keystore
+from meshbay_node.roster import Roster
 from meshbay_node.transport import (
     Denylist,
     QUIC_AVAILABLE,
@@ -117,6 +118,7 @@ class NodeDaemon:
         self._chat_stores: dict[str, ChatStore] = {}
         self._audit_store: AuditStore | None = None
         self._bundle_store: BundleStore | None = None
+        self._roster: Roster | None = None
         self._indexers: list[DirectoryIndexer] = []
         self._tasks: list[asyncio.Task] = []
         self._hub: HubClient | None = None
@@ -174,6 +176,14 @@ class NodeDaemon:
             await self._bundle_store.open()
             log.info("Bundle store opened: %s", data_dir / "bundles.db")
 
+            # 4b. Roster — who this node recognises and which keys are theirs.
+            # Node authority is established here, locally, and never learned from
+            # the hub: a hub that could name the operator's key could install
+            # itself as node administrator.
+            self._roster = Roster(db_path=data_dir / "roster.db")
+            await self._roster.open()
+            await self._roster.purge_expired()
+
             # X25519 key material for GEK unwrapping
             from cryptography.hazmat.primitives import serialization
             sk_x_raw = keys.sk_x25519.private_bytes(
@@ -223,6 +233,9 @@ class NodeDaemon:
                     "shared_root": shared_root,
                     "index": indexer.index,
                     "visibility": group_cfg.visibility,
+                    # Admission policy comes from node.toml, never from the hub:
+                    # a hub that could declare a group open would be handed its key.
+                    "join_policy": group_cfg.join_policy,
                 }
 
             if not groups_ctx:
@@ -272,12 +285,20 @@ class NodeDaemon:
                 self._webrtc._ctx["pk_x25519_raw"] = pk_x_raw
                 self._webrtc._ctx["pk_x25519_b64"] = keys.pk_x25519_b64
 
-                admin_pk = self._resolve_admin_pk(keys)
+                self._webrtc._ctx["roster"] = self._roster
+                admin_pk = self._legacy_admin_pk()
+                paired = await self._roster.has_operator() if self._roster else False
                 if admin_pk:
                     self._webrtc._ctx["admin_pk_ed25519"] = admin_pk
-                    log.info("Admin Ed25519 key pinned for node sovereignty")
+                self._webrtc._ctx["has_admin_authority"] = paired
+                if paired or admin_pk:
+                    sources = ([] if not paired else ["paired operator"]) + \
+                              ([] if not admin_pk else ["node.toml admin_pk"])
+                    log.info("Node authority: %s", " + ".join(sources))
                 else:
-                    log.warning("No admin_pk_ed25519 — admin operations disabled")
+                    log.warning(
+                        "No operator paired — invites and file deletion are "
+                        "refused. Run: meshbay-node operator pair")
                 log.info("WebRTC transport ready")
             else:
                 log.warning("WebRTC not available (aiortc not installed)")
@@ -358,6 +379,8 @@ class NodeDaemon:
             self._state["groups_ctx"] = groups_ctx
             self._state["audit_store"] = self._audit_store
             self._state["bundle_store"] = self._bundle_store
+            self._state["roster"] = self._roster
+            self._state["node_user_id"] = session.user_id
             self._state["webrtc"] = self._webrtc
             self._state["hub"] = hub
             self._state["pk_x25519_raw"] = pk_x_raw
@@ -457,21 +480,25 @@ class NodeDaemon:
         log.warning("No unwrappable GEK bundle found for group %s", group_id[:8])
         return None
 
-    def _resolve_admin_pk(self, keys: NodeKeys) -> Ed25519PublicKey | None:
-        """Resolve the admin Ed25519 public key: config → auto-pin from node keystore."""
-        if self._config.admin_pk_ed25519:
-            try:
-                raw = base64.b64decode(self._config.admin_pk_ed25519)
-                return Ed25519PublicKey.from_public_bytes(raw)
-            except Exception as e:
-                log.error("Invalid admin_pk_ed25519 in config: %s", e)
-                return None
-
-        pk = keys.sk_ed25519.public_key()
-        from meshbay_common.crypto import pk_to_b64
-        pk_b64 = pk_to_b64(pk)
-        log.info("Auto-pinning admin key from node keystore: %s", pk_b64[:16])
-        return pk
+    def _legacy_admin_pk(self) -> Ed25519PublicKey | None:
+        """
+        The pre-roster way of naming the operator: `admin_pk_ed25519` in node.toml.
+
+        Still honoured so a deployment configured that way keeps working, but no
+        longer the only path — and the auto-pin that used to stand in for it is
+        gone. It pinned the node's *keystore* key while the browser signed with the
+        user's *identity* key, so admin operations failed closed with a signature
+        error that looked like a bug elsewhere (finding M3). An operator now pairs
+        a browser with `meshbay-node operator pair`.
+        """
+        if not self._config.admin_pk_ed25519:
+            return None
+        try:
+            raw = base64.b64decode(self._config.admin_pk_ed25519)
+            return Ed25519PublicKey.from_public_bytes(raw)
+        except Exception as e:
+            log.error("Invalid admin_pk_ed25519 in config: %s", e)
+            return None
 
     async def _on_index_change(self, indexer: DirectoryIndexer) -> None:
         """Called when a DirectoryIndexer detects file changes."""
@@ -554,6 +581,9 @@ class NodeDaemon:
         if self._bundle_store:
             await self._bundle_store.close()
 
+        if self._roster:
+            await self._roster.close()
+
         for store in self._chat_stores.values():
             await store.close()
 
@@ -570,6 +600,60 @@ class NodeDaemon:
         log.info("Node stopped")
 
 
+# ── CLI helpers ───────────────────────────────────────────────────────────────
+
+def _daemon_api(cfg: Config, path: str, method: str = "GET",
+                timeout: int = 30) -> dict:
+    """
+    Call the daemon's loopback API.
+
+    The daemon owns the roster, the hub session and the live group contexts, so
+    the CLI asks it to act rather than opening its databases behind its back. It
+    also means every operator action goes through the same authorization as the
+    admin UI (the per-run session token, 11.5.3).
+    """
+    import json as _json
+    import urllib.error
+    import urllib.parse
+    import urllib.request
+
+    token_file = cfg.data_dir / "ui-token"
+    if not token_file.exists():
+        print("Node is not running — start it with: meshbay-node")
+        sys.exit(1)
+
+    sep = "&" if "?" in path else "?"
+    url = (f"http://127.0.0.1:{cfg.node.ui_port}{path}"
+           f"{sep}t={token_file.read_text().strip()}")
+    try:
+        req = urllib.request.Request(url, method=method)
+        with urllib.request.urlopen(req, timeout=timeout) as r:
+            return _json.loads(r.read())
+    except urllib.error.HTTPError as e:
+        body = e.read().decode()[:300]
+        try:
+            detail = _json.loads(body).get("error", body)
+        except Exception:
+            detail = body
+        print(f"failed: {detail}")
+        sys.exit(1)
+    except Exception as e:
+        print(f"failed: {e}")
+        sys.exit(1)
+
+
+def _resolve_group(cfg: Config, group: str | None) -> str:
+    """The group argument, or the only configured one."""
+    if group:
+        return group
+    configured = [g.id for g in cfg.groups if g.id]
+    if len(configured) == 1:
+        return configured[0]
+    print("--group is required (several groups configured)"
+          if configured else "no group configured in node.toml")
+    sys.exit(1)
+
+
 # ── Entry point ───────────────────────────────────────────────────────────────
 
 def main() -> None:
@@ -577,19 +661,23 @@ def main() -> None:
 
     parser = argparse.ArgumentParser(description="MeshBay Node daemon")
     parser.add_argument("command", nargs="?",
-                        choices=["init", "status", "ui", "gek-init", "calibrate-argon2"],
+                        choices=["init", "status", "ui", "gek-init", "operator",
+                                 "calibrate-argon2"],
                         help="init: write example config | status: node state and keys "
-                             "| ui: print the admin UI URL | calibrate-argon2: benchmark")
+                             "| ui: print the admin UI URL | operator pair: pair a "
+                             "browser with this node | calibrate-argon2: benchmark")
+    parser.add_argument("subcommand", nargs="?",
+                        help="'pair' for the operator command")
     parser.add_argument("--config", type=Path, default=None,
                         help="Config file path")
     parser.add_argument("--group", default=None,
-                        help="group id for gek-init (optional if only one is configured)")
+                        help="group id (optional if only one is configured)")
     parser.add_argument("--log-level", default="INFO",
                         choices=["DEBUG", "INFO", "WARNING", "ERROR"])
     args = parser.parse_args()
 
     # Query commands print a report; library logging would interleave with it.
-    quiet = args.command in ("status", "ui", "gek-init")
+    quiet = args.command in ("status", "ui", "gek-init", "operator")
     logging.basicConfig(
         level=logging.ERROR if quiet else getattr(logging, args.log_level),
         format="%(asctime)s %(levelname)-8s %(name)s: %(message)s",
@@ -649,50 +737,79 @@ def main() -> None:
             for g in cfg.groups:
                 print(f"  group      {g.name} [{g.visibility}] {g.id or '<no id>'}")
                 print(f"             {g.shared_dir or '<no shared_dir>'}")
-        if not cfg.admin_pk_ed25519:
-            print("admin key    NOT pinned — file deletion and member invites will be")
-            print("             refused (node.toml: admin_pk_ed25519)")
-        return
-
-    if args.command == "gek-init":
-        import json as _json
-        import urllib.error
-        import urllib.request
+        # Node authority: the roster is the source of truth, node.toml the legacy
+        # form. Read the DB directly so this reports correctly while the daemon is
+        # stopped — the state an operator is most often in when checking.
+        import asyncio as _asyncio
 
-        cfg = load_config(args.config or DEFAULT_CONFIG_PATH)
-        group_id = args.group
-        if not group_id:
-            if len(cfg.groups) == 1:
-                group_id = cfg.groups[0].id
-            else:
-                print("--group is required (several groups configured)")
-                sys.exit(1)
+        from meshbay_node.roster import Roster as _Roster
 
-        token_file = cfg.data_dir / "ui-token"
-        if not token_file.exists():
-            print("Node is not running — start it with: meshbay-node")
-            sys.exit(1)
+        async def _read_roster() -> tuple[list, int]:
+            r = _Roster(db_path=cfg.data_dir / "roster.db")
+            await r.open()
+            try:
+                return (await r.list_members()), len(await r.list_invites())
+            finally:
+                await r.close()
 
-        # The daemon holds the hub session and the live group contexts, so the CLI
-        # asks it to do the work rather than duplicating it. Same operation as the
-        # admin UI button — an operator on a headless host should never need a
-        # browser on that host to initialise a group key.
-        url = (f"http://127.0.0.1:{cfg.node.ui_port}/api/groups/{group_id}/gek"
-               f"?t={token_file.read_text().strip()}")
         try:
-            req = urllib.request.Request(url, method="POST")
-            with urllib.request.urlopen(req, timeout=60) as r:
-                out = _json.loads(r.read())
-        except urllib.error.HTTPError as e:
-            print(f"failed: {e.code} {e.read().decode()[:300]}")
-            sys.exit(1)
+            members, pending = _asyncio.run(_read_roster())
+        except Exception as e:
+            members, pending = [], 0
+            print(f"roster       <unreadable: {e}>")
+
+        operators = [m for m in members if m["role"] == "operator"
+                     and m["status"] == "active"]
+        if operators:
+            for op in operators:
+                print(f"operator     {op.get('username') or op['user_id'][:8]}"
+                      f"  key {(op.get('pk_ed25519') or '')[:16]}…"
+                      f"  paired {op.get('pinned_at', '?')}")
+        elif cfg.admin_pk_ed25519:
+            print("operator     node.toml admin_pk_ed25519 (legacy)")
+            print("             run `meshbay-node operator pair` to replace it")
+        else:
+            print("operator     NONE PAIRED — file deletion and member invites are")
+            print("             refused. Run: meshbay-node operator pair")
+        if pending:
+            print(f"invites      {pending} pending code(s)")
+        return
+
+    if args.command == "gek-init":
+        cfg = load_config(args.config or DEFAULT_CONFIG_PATH)
+        group_id = _resolve_group(cfg, args.group)
+        out = _daemon_api(cfg, f"/api/groups/{group_id}/gek",
+                          method="POST", timeout=60)
 
         print(f"GEK ready for {group_id}")
-        print(f"  wrapped for {out.get('wrapped_count')}/{out.get('total_members')} members")
+        print(f"  {out.get('authorized_members', 0)} authorized member(s) — each "
+              f"receives the key on connect")
         for err in out.get("errors") or []:
             print(f"  ! {err}")
         return
 
+    if args.command == "operator":
+        if args.subcommand != "pair":
+            print("usage: meshbay-node operator pair")
+            sys.exit(1)
+
+        cfg = load_config(args.config or DEFAULT_CONFIG_PATH)
+        out = _daemon_api(cfg, "/api/operator/pair", method="POST")
+
+        from meshbay_node.roster import write_code_file
+        path = write_code_file(cfg.data_dir, out["code"], out.get("expires_at", ""))
+
+        print(f"PAIRING CODE   {out['code']}")
+        print(f"valid until    {out.get('expires_at', '?')}")
+        print()
+        print("Sign in to the web app as this node's operator, open one of your")
+        print("groups, go to the Members tab and enter the code there.")
+        print("It works once, for that account only, and authorizes invites and")
+        print("file deletion from that browser.")
+        print()
+        print(f"also written to {path}")
+        return
+
     if args.command == "ui":
         cfg = load_config(args.config or DEFAULT_CONFIG_PATH)
         token_file = cfg.data_dir / "ui-token"
diff --git a/packages/meshbay-node/src/meshbay_node/roster.py b/packages/meshbay-node/src/meshbay_node/roster.py
new file mode 100644
index 0000000..f231792
--- /dev/null
+++ b/packages/meshbay-node/src/meshbay_node/roster.py
@@ -0,0 +1,372 @@
+"""
+Node roster — who this node recognises, and which keys are theirs.
+
+The node keeps its own answer to "may this person have the group key", derived from
+what the operator authorized locally. It is deliberately NOT derived from the hub:
+the hub decides group membership, and a hub that invents an account and mints a
+token for it would otherwise collect the GEK on connect. Hub membership is an input
+to the decision; it is not the decision.
+
+Three tables:
+
+  identities — one row per person, not per group. Someone paired for one group
+               needs no code for the next one on the same node.
+  members    — role and status per (group, user).
+  invites    — one-time pairing codes, stored as a hash. The code itself exists
+               only in the operator's hands and the invitee's.
+
+The code is what binds a public key to an account without asking the hub
+(finding H3). See `docs/invite-pairing-v1.md`.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import os
+import secrets
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+import aiosqlite
+
+log = logging.getLogger(__name__)
+
+# Crockford base32 without I, L, O and U: no character pair a human can confuse
+# when reading a code aloud or typing it from a phone screen.
+_ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+CODE_LEN = 8                      # 8 × 5 bits = 40 bits of entropy
+DEFAULT_INVITE_TTL = 24 * 3600    # seconds
+
+_SCHEMA = """\
+CREATE TABLE IF NOT EXISTS identities (
+    user_id    TEXT PRIMARY KEY,
+    username   TEXT NOT NULL,
+    pk_ed25519 TEXT NOT NULL,
+    pk_x25519  TEXT NOT NULL,
+    pinned_at  TEXT NOT NULL,
+    pinned_via TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS members (
+    group_id    TEXT NOT NULL,
+    user_id     TEXT NOT NULL,
+    role        TEXT NOT NULL,
+    status      TEXT NOT NULL,
+    approved_by TEXT NOT NULL,
+    approved_at TEXT NOT NULL,
+    PRIMARY KEY (group_id, user_id)
+);
+
+CREATE TABLE IF NOT EXISTS invites (
+    code_hash  TEXT PRIMARY KEY,
+    group_id   TEXT NOT NULL,
+    user_id    TEXT NOT NULL,
+    role       TEXT NOT NULL,
+    created_by TEXT NOT NULL,
+    created_at TEXT NOT NULL,
+    expires_at TEXT NOT NULL,
+    used_at    TEXT
+);
+"""
+
+
+def generate_code() -> str:
+    """A fresh pairing code, formatted for a human to read out: XXXX-XXXX."""
+    raw = "".join(secrets.choice(_ALPHABET) for _ in range(CODE_LEN))
+    return f"{raw[:4]}-{raw[4:]}"
+
+
+def normalize_code(code: str) -> str:
+    """
+    Fold what a human typed onto what was generated.
+
+    Crockford's rules: case-insensitive, dashes and spaces are decoration, and the
+    excluded letters map onto the digits they resemble. Someone reading a code over
+    the phone should not be able to get it wrong in a way we could have absorbed.
+    """
+    out = []
+    for ch in code.upper():
+        if ch in "- \t":
+            continue
+        if ch in "IL":
+            out.append("1")
+        elif ch == "O":
+            out.append("0")
+        elif ch == "U":
+            out.append("V")
+        else:
+            out.append(ch)
+    return "".join(out)
+
+
+def hash_code(code: str) -> str:
+    """
+    Store codes hashed: a stolen roster DB must not yield usable invitations.
+
+    SHA-256 rather than a password KDF on purpose — the input is 40 bits of
+    uniformly random secret, not a human-chosen string, so there is nothing for a
+    slow hash to defend.
+    """
+    return hashlib.sha256(normalize_code(code).encode()).hexdigest()
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+class Roster:
+    def __init__(self, db_path: Path):
+        self._db_path = db_path
+        self._db: aiosqlite.Connection | None = None
+
+    async def open(self) -> None:
+        self._db_path.parent.mkdir(parents=True, exist_ok=True)
+        self._db = await aiosqlite.connect(str(self._db_path))
+        self._db.row_factory = aiosqlite.Row
+        # WAL: the CLI writes invites (`operator pair`) while the daemon reads them.
+        await self._db.execute("PRAGMA journal_mode=WAL")
+        await self._db.executescript(_SCHEMA)
+        await self._db.commit()
+
+    async def close(self) -> None:
+        if self._db:
+            await self._db.close()
+            self._db = None
+
+    # ── Identities ───────────────────────────────────────────────────────────
+
+    async def pin_identity(
+        self,
+        user_id: str,
+        username: str,
+        pk_ed25519: str,
+        pk_x25519: str,
+        via: str,
+    ) -> None:
+        assert self._db
+        await self._db.execute(
+            "INSERT OR REPLACE INTO identities "
+            "(user_id, username, pk_ed25519, pk_x25519, pinned_at, pinned_via) "
+            "VALUES (?, ?, ?, ?, ?, ?)",
+            (user_id, username, pk_ed25519, pk_x25519, _now(), via),
+        )
+        await self._db.commit()
+
+    async def get_identity(self, user_id: str) -> dict | None:
+        assert self._db
+        async with self._db.execute(
+            "SELECT * FROM identities WHERE user_id = ?", (user_id,)
+        ) as cur:
+            row = await cur.fetchone()
+        return dict(row) if row else None
+
+    async def unpin(self, user_id: str) -> bool:
+        assert self._db
+        cur = await self._db.execute(
+            "DELETE FROM identities WHERE user_id = ?", (user_id,))
+        await self._db.commit()
+        return cur.rowcount > 0
+
+    async def list_identities(self) -> list[dict]:
+        assert self._db
+        async with self._db.execute(
+            "SELECT * FROM identities ORDER BY pinned_at"
+        ) as cur:
+            return [dict(r) for r in await cur.fetchall()]
+
+    # ── Authority ────────────────────────────────────────────────────────────
+
+    async def operator_pks(self) -> list[str]:
+        """
+        Base64 Ed25519 keys allowed to authorize admin operations on this node.
+
+        Read fresh on every check rather than cached: an unpin must take effect at
+        once, and this runs only on admin operations, which are rare.
+        """
+        assert self._db
+        async with self._db.execute(
+            "SELECT i.pk_ed25519 FROM identities i "
+            "JOIN members m ON m.user_id = i.user_id "
+            "WHERE m.role = 'operator' AND m.status = 'active'"
+        ) as cur:
+            return [r["pk_ed25519"] for r in await cur.fetchall()]
+
+    async def has_operator(self) -> bool:
+        return bool(await self.operator_pks())
+
+    async def is_authorized(self, group_id: str, user_id: str) -> bool:
+        """
+        May this person be handed the group key?
+
+        The node's own answer, not the hub's. Hub membership is what lets someone
+        reach the node; this is what decides whether the key is wrapped for them —
+        otherwise a hub that invents an account and mints a token for it would be
+        served the GEK on connect.
+
+        An operator is authorized for every group this node hosts: their authority
+        is node-wide and is recorded with an empty group_id.
+        """
+        assert self._db
+        async with self._db.execute(
+            "SELECT 1 FROM members WHERE user_id = ? AND status = 'active' "
+            "AND (group_id = ? OR (group_id = '' AND role = 'operator')) LIMIT 1",
+            (user_id, group_id),
+        ) as cur:
+            return await cur.fetchone() is not None
+
+    # ── Members ──────────────────────────────────────────────────────────────
+
+    async def set_member(
+        self,
+        group_id: str,
+        user_id: str,
+        role: str,
+        status: str,
+        approved_by: str,
+    ) -> None:
+        assert self._db
+        await self._db.execute(
+            "INSERT OR REPLACE INTO members "
+            "(group_id, user_id, role, status, approved_by, approved_at) "
+            "VALUES (?, ?, ?, ?, ?, ?)",
+            (group_id, user_id, role, status, approved_by, _now()),
+        )
+        await self._db.commit()
+
+    async def get_member(self, group_id: str, user_id: str) -> dict | None:
+        assert self._db
+        async with self._db.execute(
+            "SELECT * FROM members WHERE group_id = ? AND user_id = ?",
+            (group_id, user_id),
+        ) as cur:
+            row = await cur.fetchone()
+        return dict(row) if row else None
+
+    async def list_members(self, group_id: str | None = None) -> list[dict]:
+        assert self._db
+        sql = (
+            "SELECT m.*, i.username, i.pk_ed25519, i.pinned_at, i.pinned_via "
+            "FROM members m LEFT JOIN identities i ON i.user_id = m.user_id"
+        )
+        args: tuple = ()
+        if group_id is not None:
+            sql += " WHERE m.group_id = ?"
+            args = (group_id,)
+        async with self._db.execute(sql + " ORDER BY m.approved_at", args) as cur:
+            return [dict(r) for r in await cur.fetchall()]
+
+    async def set_status(self, group_id: str, user_id: str, status: str) -> bool:
+        assert self._db
+        cur = await self._db.execute(
+            "UPDATE members SET status = ? WHERE group_id = ? AND user_id = ?",
+            (status, group_id, user_id),
+        )
+        await self._db.commit()
+        return cur.rowcount > 0
+
+    # ── Invites ──────────────────────────────────────────────────────────────
+
+    async def create_invite(
+        self,
+        group_id: str,
+        user_id: str,
+        role: str,
+        created_by: str,
+        ttl: int = DEFAULT_INVITE_TTL,
+    ) -> str:
+        """
+        Issue a one-time code. Returns it in the clear — this is the only moment it
+        exists outside the operator's hands; only its hash is kept.
+
+        Any earlier unused invite for the same person and group is dropped, so
+        re-inviting supersedes rather than accumulating valid codes.
+        """
+        assert self._db
+        await self._db.execute(
+            "DELETE FROM invites WHERE group_id = ? AND user_id = ? AND used_at IS NULL",
+            (group_id, user_id),
+        )
+        code = generate_code()
+        expires = datetime.now(timezone.utc) + timedelta(seconds=ttl)
+        await self._db.execute(
+            "INSERT INTO invites "
+            "(code_hash, group_id, user_id, role, created_by, created_at, expires_at) "
+            "VALUES (?, ?, ?, ?, ?, ?, ?)",
+            (hash_code(code), group_id, user_id, role, created_by, _now(),
+             expires.isoformat(timespec="seconds")),
+        )
+        await self._db.commit()
+        return code
+
+    async def consume_invite(self, code: str, user_id: str) -> dict | None:
+        """
+        Redeem a code for `user_id`, or return None.
+
+        Single use is enforced by the UPDATE's WHERE clause: two connections racing
+        the same code cannot both see `used_at IS NULL`, so exactly one wins.
+        """
+        assert self._db
+        code_hash = hash_code(code)
+        async with self._db.execute(
+            "SELECT * FROM invites WHERE code_hash = ?", (code_hash,)
+        ) as cur:
+            row = await cur.fetchone()
+        if not row:
+            return None
+
+        invite = dict(row)
+        if invite["used_at"] is not None:
+            return None
+        # A code is valid for exactly one account, so a leaked code cannot be
+        # redeemed by whoever finds it first.
+        if invite["user_id"] != user_id:
+            return None
+        if datetime.fromisoformat(invite["expires_at"]) < datetime.now(timezone.utc):
+            return None
+
+        cur = await self._db.execute(
+            "UPDATE invites SET used_at = ? WHERE code_hash = ? AND used_at IS NULL",
+            (_now(), code_hash),
+        )
+        await self._db.commit()
+        if cur.rowcount == 0:
+            return None
+        return invite
+
+    async def list_invites(self, include_used: bool = False) -> list[dict]:
+        assert self._db
+        sql = "SELECT * FROM invites"
+        if not include_used:
+            sql += " WHERE used_at IS NULL"
+        async with self._db.execute(sql + " ORDER BY created_at") as cur:
+            return [dict(r) for r in await cur.fetchall()]
+
+    async def purge_expired(self) -> int:
+        assert self._db
+        cur = await self._db.execute(
+            "DELETE FROM invites WHERE used_at IS NULL AND expires_at < ?",
+            (_now(),),
+        )
+        await self._db.commit()
+        return cur.rowcount
+
+
+async def open_roster(data_dir: Path) -> Roster:
+    roster = Roster(data_dir / "roster.db")
+    await roster.open()
+    return roster
+
+
+def write_code_file(data_dir: Path, code: str, expires_at: str) -> Path:
+    """
+    Leave the code in a file as well as on stdout.
+
+    An operator working over SSH may not be able to copy out of their terminal,
+    and a code that can only be read off a scrolled-away screen is a dead end.
+    """
+    path = data_dir / "pair-code"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(f"{code}\nexpires {expires_at}\n")
+    os.chmod(path, 0o600)
+    return path
diff --git a/packages/meshbay-node/src/meshbay_node/transport/webrtc_server.py b/packages/meshbay-node/src/meshbay_node/transport/webrtc_server.py
index 34a96bd..fe3ee2e 100644
--- a/packages/meshbay-node/src/meshbay_node/transport/webrtc_server.py
+++ b/packages/meshbay-node/src/meshbay_node/transport/webrtc_server.py
@@ -57,10 +57,16 @@ from meshbay_common.handshake import (
 from meshbay_common.adminop import (
     ADMIN_CHALLENGE_TTL,
     OP_FILE_DELETE,
-    OP_GEK_BUNDLE_STORE,
+    OP_INVITE_CREATE,
     admin_transcript,
 )
-from meshbay_common.crypto import pk_to_b64
+from meshbay_common.crypto import pk_to_b64, wrap_gek_aes
+from meshbay_common.join import (
+    JOIN_TTL,
+    ROLE_MEMBER,
+    ROLE_OPERATOR,
+    join_transcript,
+)
 from meshbay_common.webcrypto import chunk_key_aes, encrypt_chunk_aes
 from meshbay_common.protocol import MNP
 from meshbay_node.indexer import GroupIndex
@@ -85,6 +91,14 @@ MAX_CONCURRENT_TRANSCODES = 2
 # Bundle fetches are served in the pre-proof window (C4). Bounded and audited
 # until the native client removes remote keypair bundles entirely.
 MAX_PRE_PROOF_FETCHES = 4
+# Pairing codes carry 40 bits and are single-use, but a connection must not be
+# allowed to sit there guessing. Failures are audited, so a grind is visible.
+MAX_JOIN_ATTEMPTS = 5
+# Per-connection limits alone would not bind an attacker who can open connections
+# at will — and the adversary who can mint tokens for any account is the hub. So
+# failed pairings are also counted node-wide over a window.
+MAX_JOIN_FAILURES_WINDOW = 20
+JOIN_FAILURE_WINDOW = 600  # seconds
 UPLOAD_DIR_NAME = ".uploads"
 # Conservative allowlist: also what keeps markup out of filenames, which the node admin
 # UI used to render unescaped (finding H2).
@@ -218,6 +232,11 @@ class WebRTCPeerSession:
         self._username: str = ""
         self._pk_user: str = ""
         self._gek_challenge: bytes | None = None
+        # Same value as the GEK challenge, but kept for the life of the connection:
+        # a join_request is signed over it, and it must stay verifiable after the
+        # handshake clears the challenge (an operator pairs while already connected).
+        self._nonce_node: bytes = b""
+        self._join_attempts = 0
         self._nonce_client: bytes = b""
         self._admin_ops: dict[str, dict] = {}   # op_id → pending admin operation
         self._uploads: dict[str, dict] = {}   # filename → {next_index, bytes}
@@ -259,6 +278,12 @@ class WebRTCPeerSession:
                     asyncio.ensure_future(self._do_gek_bundle_fetch())
                 else:
                     asyncio.ensure_future(self._do_keypair_bundle_fetch())
+            elif mtype == MNP.JOIN_REQUEST and self._nonce_node:
+                # Valid both before the GEK proof (a new member has no GEK to prove
+                # with) and after it (an operator pairing a browser is already
+                # connected). Authority comes from the pairing code and the
+                # signature, never from the session state.
+                asyncio.ensure_future(self._do_join_request(msg))
             elif self._user_id is None:
                 self._send({"type": "error", "detail": "Handshake required"})
             elif mtype == MNP.INDEX_SYNC:
@@ -277,8 +302,8 @@ class WebRTCPeerSession:
                 self._do_file_delete(msg)
             elif mtype == MNP.ADMIN_RESPONSE:
                 self._do_admin_response(msg)
-            elif mtype == MNP.GEK_BUNDLE_STORE:
-                self._do_gek_bundle_store(msg)
+            elif mtype == MNP.INVITE_CREATE:
+                self._do_invite_create(msg)
             elif mtype == MNP.KEYPAIR_BUNDLE_STORE:
                 asyncio.ensure_future(self._do_keypair_bundle_store(msg))
             elif mtype == MNP.STREAM_REQUEST:
@@ -359,6 +384,7 @@ class WebRTCPeerSession:
             return
 
         self._gek_challenge = os.urandom(NONCE_LEN)
+        self._nonce_node = self._gek_challenge
         self._send({
             "type": MNP.HANDSHAKE_CHALLENGE,
             "v": MNP_VERSION,
@@ -472,49 +498,40 @@ class WebRTCPeerSession:
         else:
             self._send({"type": MNP.GEK_BUNDLE_RESP, "v": MNP_VERSION, "found": False})
 
-    def _do_gek_bundle_store(self, msg: dict) -> None:
+    def _do_invite_create(self, msg: dict) -> None:
         """
-        Request to store a wrapped GEK bundle for a target user.
-
-        Finding C5b: this used to write whatever any authenticated member sent, with
-        INSERT OR REPLACE semantics, and then auto-activate the bundle if it was
-        addressed to the node operator. Since the operator's X25519 public key is
-        public — the node even hands it out in handshake_ack — any member could wrap
-        a GEK of their own choosing for the operator and make the node adopt it,
-        locking every legitimate member out of the group and taking over the key.
-
-        Storing a bundle is now a node-operator operation gated by an Ed25519
-        challenge, and nothing arriving over MNP can activate a GEK: activation
-        happens only through the local admin UI or the CLI.
+        Issue a one-time pairing code for someone the operator wants to admit.
+
+        Replaces the old invite path, where the inviter fetched the invitee's
+        public key from the hub and wrapped the group key for whatever came back
+        (H3). The node now needs nothing but a name: it will wrap the key itself,
+        later, for a key the invitee proves they hold.
         """
-        bundle_store = self._ctx.get("bundle_store")
-        if not bundle_store:
-            self._send({"type": "error", "detail": "Bundle store not available"})
+        roster = self._ctx.get("roster")
+        if roster is None:
+            self._send({"type": "error", "detail": "Roster not available"})
             return
 
-        target_user_id = msg.get("user_id", "")
+        invitee_id = msg.get("user_id", "")
         group_id = msg.get("group_id") or self._group_id
-        pk_eph = msg.get("pk_eph_b64", "")
-        nonce = msg.get("nonce_b64", "")
-        wrapped = msg.get("wrapped_b64", "")
-
-        if not target_user_id or not pk_eph or not nonce or not wrapped or not group_id:
-            self._send({"type": "error", "detail": "Missing bundle fields"})
+        if not invitee_id or not group_id:
+            self._send({"type": "error", "detail": "Missing user_id or group_id"})
+            return
+        if group_id != self._group_id:
+            self._send({"type": "error", "detail": "Wrong group for this session"})
             return
 
-        if not self._ctx.get("admin_pk_ed25519"):
+        if not self._has_admin_authority():
             self._send({
                 "type": "error",
-                "detail": "No admin key pinned — bundle storage refused",
+                "detail": "No operator paired — run `meshbay-node operator pair`",
             })
             return
 
-        self._issue_admin_challenge(OP_GEK_BUNDLE_STORE, target_user_id, {
+        self._issue_admin_challenge(OP_INVITE_CREATE, invitee_id, {
             "group_id": group_id,
-            "user_id": target_user_id,
-            "pk_eph_b64": pk_eph,
-            "nonce_b64": nonce,
-            "wrapped_b64": wrapped,
+            "user_id": invitee_id,
+            "username": str(msg.get("username", ""))[:64],
         })
 
     async def _do_keypair_bundle_fetch(self) -> None:
@@ -560,6 +577,240 @@ class WebRTCPeerSession:
             "detail": "keypair_bundle_stored",
         })
 
+    # ── Pairing and join (H3, M3) ────────────────────────────────────────────
+
+    def _join_refuse(self, reason: str, audit_detail: str = "") -> None:
+        self._join_attempts += 1
+        # Node-wide window, shared across connections: reconnecting must not reset
+        # the budget.
+        now = time.time()
+        failures = [t for t in self._ctx.get("join_failures", [])
+                    if now - t < JOIN_FAILURE_WINDOW]
+        failures.append(now)
+        self._ctx["join_failures"] = failures
+        self._audit_join("join_refused", audit_detail or reason)
+        self._send({
+            "type": MNP.JOIN_RESULT,
+            "v": MNP_VERSION,
+            "ok": False,
+            "reason": reason,
+        })
+
+    def _audit_join(self, event: str, detail: str) -> None:
+        audit = self._ctx.get("audit_store")
+        if not audit:
+            return
+        self._remote_ip = self._remote_ip or _get_remote_ip(self._pc)
+        asyncio.ensure_future(audit.log_event(
+            user_id=self._user_id or getattr(self, "_pending_sub", "unknown"),
+            event=event,
+            ip=self._remote_ip,
+            username=self._username or getattr(self, "_pending_username", ""),
+            group_id=self._group_id or getattr(self, "_pending_group", "") or "",
+            detail=detail,
+        ))
+
+    async def _do_join_request(self, msg: dict) -> None:
+        """
+        Pin an identity, or recognise one already pinned.
+
+        The client signs its own Ed25519 and X25519 keys together with the node's
+        nonce, so the identity key vouches for the encryption key — that is what
+        will make it safe for the node to wrap the GEK for a key that arrived over
+        the wire instead of one fetched from the hub's directory (H3).
+
+        A first pairing needs a one-time code, which the hub never sees. Afterwards
+        the pin is the credential and a changed key is refused outright, the same
+        rule the client applies to `pk_node` (11.5.8).
+        """
+        roster = self._ctx.get("roster")
+        if roster is None:
+            self._send({"type": "error", "detail": "Roster not available"})
+            return
+
+        if self._join_attempts >= MAX_JOIN_ATTEMPTS:
+            self._send({"type": "error", "detail": "Too many attempts"})
+            return
+
+        now = time.time()
+        recent = [t for t in self._ctx.get("join_failures", [])
+                  if now - t < JOIN_FAILURE_WINDOW]
+        if len(recent) >= MAX_JOIN_FAILURES_WINDOW:
+            self._audit_join("join_throttled", f"{len(recent)} failures in window")
+            self._send({"type": "error", "detail": "Pairing temporarily locked"})
+            return
+
+        user_id = self._user_id or getattr(self, "_pending_sub", "")
+        username = self._username or getattr(self, "_pending_username", "")
+        if not user_id:
+            self._send({"type": "error", "detail": "Handshake required"})
+            return
+
+        pk_ed_b64 = msg.get("pk_ed25519", "")
+        pk_x_b64 = msg.get("pk_x25519", "")
+        code = msg.get("code", "")
+        ts = msg.get("ts", 0)
+
+        try:
+            pk_ed_raw = base64.b64decode(pk_ed_b64)
+            pk_x_raw = base64.b64decode(pk_x_b64)
+            if len(pk_ed_raw) != 32 or len(pk_x_raw) != 32:
+                raise ValueError
+            pk_ed = Ed25519PublicKey.from_public_bytes(pk_ed_raw)
+        except Exception:
+            self._join_refuse("invalid_keys")
+            return
+
+        if not isinstance(ts, int) or abs(time.time() - ts) > JOIN_TTL:
+            self._join_refuse("stale_request")
+            return
+
+        # An empty group_id means operator pairing, which is node-wide. Anything
+        # else must be the group this connection authenticated to — a signature
+        # obtained for one group must not name another.
+        group_id = msg.get("group_id", "") or ""
+        session_group = self._group_id or getattr(self, "_pending_group", "") or ""
+        if group_id and group_id != session_group:
+            self._join_refuse("group_mismatch")
+            return
+
+        transcript = join_transcript(
+            node_pk_b64=self._node_pk_b64(),
+            group_id=group_id,
+            user_id=user_id,
+            pk_ed25519_b64=pk_ed_b64,
+            pk_x25519_b64=pk_x_b64,
+            nonce_node=self._nonce_node,
+            ts=ts,
+        )
+        try:
+            sig = base64.b64decode(msg.get("sig", ""))
+        except Exception:
+            self._join_refuse("invalid_signature_encoding")
+            return
+        if not self._verify_sig(pk_ed, transcript, sig):
+            self._join_refuse("signature_invalid")
+            return
+
+        known = await roster.get_identity(user_id)
+        if known:
+            if known["pk_ed25519"] != pk_ed_b64 or known["pk_x25519"] != pk_x_b64:
+                # The blocking warning, raised where it matters: whoever this is
+                # holds a different key than the person the operator paired.
+                self._join_refuse(
+                    "key_changed",
+                    f"pinned={known['pk_ed25519'][:16]} presented={pk_ed_b64[:16]}")
+                return
+            member = await roster.get_member(group_id, user_id)
+            await self._join_ok(
+                user_id, pk_x_raw, session_group,
+                role=member["role"] if member else "",
+                recognised=True,
+            )
+            return
+
+        if not code:
+            if self._group_join_policy(session_group) == "open":
+                # An open-join group admits anyone the hub calls a member, so a
+                # code would protect nothing — the hub can walk in through the
+                # front door. Pin what turns up and say so in the audit log.
+                await self._pin_and_admit(
+                    roster, user_id, username, pk_ed_b64, pk_x_b64,
+                    group_id=session_group, role=ROLE_MEMBER,
+                    approved_by="open-join", via="tofu")
+                await self._join_ok(user_id, pk_x_raw, session_group,
+                                    role=ROLE_MEMBER, recognised=False)
+                return
+            self._join_refuse("code_required")
+            return
+
+        invite = await roster.consume_invite(code, user_id)
+        if not invite:
+            self._join_refuse("code_invalid")
+            return
+
+        await self._pin_and_admit(
+            roster, user_id, username, pk_ed_b64, pk_x_b64,
+            group_id=invite["group_id"], role=invite["role"],
+            approved_by=invite["created_by"], via="code")
+        await self._join_ok(user_id, pk_x_raw, invite["group_id"],
+                            role=invite["role"], recognised=False)
+
+    def _group_join_policy(self, group_id: str) -> str:
+        """
+        Admission policy for a group, read from the node's own configuration.
+
+        Never from the hub: a hub that could declare a group open would be handed
+        the key to it (§3.4 of docs/invite-pairing-v1.md).
+        """
+        gctx = (self._ctx.get("groups") or {}).get(group_id) or {}
+        return gctx.get("join_policy", "invite")
+
+    async def _pin_and_admit(
+        self, roster, user_id: str, username: str, pk_ed_b64: str, pk_x_b64: str,
+        *, group_id: str, role: str, approved_by: str, via: str,
+    ) -> None:
+        await roster.pin_identity(
+            user_id=user_id, username=username,
+            pk_ed25519=pk_ed_b64, pk_x25519=pk_x_b64, via=via,
+        )
+        await roster.set_member(
+            group_id=group_id, user_id=user_id, role=role,
+            status="active", approved_by=approved_by,
+        )
+        if role == ROLE_OPERATOR:
+            self._ctx["has_admin_authority"] = True
+
+        log.info("Identity pinned (%s): user=%s role=%s", via, user_id[:8], role)
+        self._audit_join("join_pinned", f"role={role} via={via}")
+
+    async def _join_ok(
+        self, user_id: str, pk_x_raw: bytes, group_id: str,
+        *, role: str, recognised: bool,
+    ) -> None:
+        """
+        Answer a join, wrapping the group key for the key the caller just proved.
+
+        This is the H3 fix. The inviter used to fetch the invitee's public key from
+        the hub and wrap the GEK for whatever came back, so a hub that answered
+        with its own key was handed the group key by an honest member following the
+        protocol exactly. The node now wraps for a key that arrived from its owner
+        over an authenticated channel, bound to a pinned identity.
+        """
+        reply = {
+            "type": MNP.JOIN_RESULT,
+            "v": MNP_VERSION,
+            "ok": True,
+            "recognised": recognised,
+            "role": role,
+        }
+
+        roster = self._ctx["roster"]
+        if group_id and not await roster.is_authorized(group_id, user_id):
+            # Pinned on this node, but not admitted to this group. Hub membership
+            # alone must not produce a key.
+            reply["gek"] = False
+            reply["reason"] = "not_authorized_for_group"
+            self._send(reply)
+            self._audit_join("join_no_gek", f"group={group_id[:8]} not authorized")
+            return
+
+        gctx = (self._ctx.get("groups") or {}).get(group_id) or {}
+        gek = gctx.get("gek")
+        if not gek:
+            reply["gek"] = False
+            reply["reason"] = "no_gek"
+            self._send(reply)
+            return
+
+        bundle = wrap_gek_aes(gek, pk_x_raw)
+        reply["gek"] = True
+        reply["pk_eph_b64"] = bundle["pk_eph_b64"]
+        reply["nonce_b64"] = bundle["nonce_b64"]
+        reply["wrapped_b64"] = bundle["wrapped_b64"]
+        self._send(reply)
+        self._audit_join("gek_wrapped", f"group={group_id[:8]}")
+
     def _audit_pre_proof_fetch(self, mtype: str) -> None:
         """Record bundle access made before the GEK proof (C4)."""
         audit = self._ctx.get("audit_store")
@@ -903,9 +1154,8 @@ class WebRTCPeerSession:
             self._send({"type": "error", "detail": "File not found"})
             return
 
-        admin_pk = self._ctx.get("admin_pk_ed25519")
         has_uploader_pk = bool(entry.uploader_pk)
-        if not admin_pk and not has_uploader_pk:
+        if not self._has_admin_authority() and not has_uploader_pk:
             self._send({"type": "error", "detail": "No authorized key for deletion"})
             return
 
@@ -956,6 +1206,43 @@ class WebRTCPeerSession:
         except Exception:
             return False
 
+    def _has_admin_authority(self) -> bool:
+        """
+        Cheap synchronous pre-check: is there anyone who could authorize this?
+
+        Only decides whether to issue a challenge at all — the gate is
+        `_verify_admin_sig`. The flag is set at startup and refreshed in-process
+        when an operator pairs.
+        """
+        return bool(self._ctx.get("admin_pk_ed25519")
+                    or self._ctx.get("has_admin_authority"))
+
+    async def _verify_admin_sig(self, transcript: bytes, sig: bytes) -> bool:
+        """
+        Check a signature against every key holding node-operator authority.
+
+        Read from the roster on each call rather than cached: revoking a paired
+        browser must take effect immediately, and admin operations are rare enough
+        that a SQLite read costs nothing. `admin_pk_ed25519` in node.toml is still
+        honoured so an existing deployment keeps working until its operator pairs
+        (M3) — it is the legacy form of the same statement.
+        """
+        legacy = self._ctx.get("admin_pk_ed25519")
+        if self._verify_sig(legacy, transcript, sig):
+            return True
+
+        roster = self._ctx.get("roster")
+        if roster is None:
+            return False
+        for pk_b64 in await roster.operator_pks():
+            try:
+                pk = Ed25519PublicKey.from_public_bytes(base64.b64decode(pk_b64))
+            except Exception:
+                continue
+            if self._verify_sig(pk, transcript, sig):
+                return True
+        return False
+
     def _do_admin_response(self, msg: dict) -> None:
         op_id = msg.get("op_id", "")
         sig_b64 = msg.get("signature", "")
@@ -985,14 +1272,15 @@ class WebRTCPeerSession:
         )
 
         if pending["op"] == OP_FILE_DELETE:
-            self._admin_exec_file_delete(pending, transcript, sig_bytes)
-        elif pending["op"] == OP_GEK_BUNDLE_STORE:
             asyncio.ensure_future(
-                self._admin_exec_bundle_store(pending, transcript, sig_bytes))
+                self._admin_exec_file_delete(pending, transcript, sig_bytes))
+        elif pending["op"] == OP_INVITE_CREATE:
+            asyncio.ensure_future(
+                self._admin_exec_invite_create(pending, transcript, sig_bytes))
         else:
             self._send({"type": "error", "detail": "Unknown admin operation"})
 
-    def _admin_exec_file_delete(
+    async def _admin_exec_file_delete(
         self, pending: dict, transcript: bytes, sig: bytes,
     ) -> None:
         file_id = pending["subject"]
@@ -1012,7 +1300,7 @@ class WebRTCPeerSession:
 
         # Node operator, or the user who uploaded this file — verified by the key
         # recorded at upload time, never by a JWT claim (the hub controls those).
-        if not (self._verify_sig(self._ctx.get("admin_pk_ed25519"), transcript, sig)
+        if not (await self._verify_admin_sig(transcript, sig)
                 or self._verify_sig(uploader_pk, transcript, sig)):
             self._send({"type": "error", "detail": "Signature verification failed"})
             self._audit("admin_auth_failed", f"file_delete:{file_id[:16]}")
@@ -1020,33 +1308,46 @@ class WebRTCPeerSession:
 
         self._exec_file_delete(ctx, file_id, entry)
 
-    async def _admin_exec_bundle_store(
+    async def _admin_exec_invite_create(
         self, pending: dict, transcript: bytes, sig: bytes,
     ) -> None:
         # Node operator only. A group admin who does not run the node has no
-        # authority over what this node stores (draft-v4 §4.2.x, deny by default).
-        if not self._verify_sig(self._ctx.get("admin_pk_ed25519"), transcript, sig):
+        # authority over who this node admits (deny by default). Delegation is
+        # designed but deferred — see §6.2 of docs/invite-pairing-v1.md.
+        if not await self._verify_admin_sig(transcript, sig):
             self._send({"type": "error", "detail": "Signature verification failed"})
-            self._audit("admin_auth_failed", f"gek_bundle_store:{pending['subject'][:16]}")
+            self._audit("admin_auth_failed", f"invite_create:{pending['subject'][:16]}")
             return
 
-        payload = pending["payload"]
-        bundle_store = self._ctx.get("bundle_store")
-        if not bundle_store:
-            self._send({"type": "error", "detail": "Bundle store not available"})
+        roster = self._ctx.get("roster")
+        if roster is None:
+            self._send({"type": "error", "detail": "Roster not available"})
             return
 
-        await bundle_store.store(
-            payload["group_id"], payload["user_id"],
-            payload["pk_eph_b64"], payload["nonce_b64"], payload["wrapped_b64"],
+        payload = pending["payload"]
+        code = await roster.create_invite(
+            group_id=payload["group_id"],
+            user_id=payload["user_id"],
+            role=ROLE_MEMBER,
+            created_by=self._user_id or "",
         )
-        log.info("GEK bundle stored: group=%s user=%s",
+        invites = await roster.list_invites()
+        expires = next(
+            (i["expires_at"] for i in invites
+             if i["user_id"] == payload["user_id"]
+             and i["group_id"] == payload["group_id"]), "")
+
+        log.info("Invite created: group=%s user=%s",
                  payload["group_id"][:8], payload["user_id"][:8])
-        self._audit("gek_bundle_store", f"target={payload['user_id'][:8]}")
+        self._audit("invite_create", f"target={payload['user_id'][:8]}")
+        # The code exists in the clear exactly here and in the operator's hands.
         self._send({
-            "type": "ack", "v": MNP_VERSION,
-            "detail": "gek_bundle_stored",
+            "type": MNP.INVITE_RESULT,
+            "v": MNP_VERSION,
+            "code": code,
+            "expires_at": expires,
             "user_id": payload["user_id"],
+            "username": payload.get("username", ""),
         })
 
     def _exec_file_delete(self, ctx: dict, file_id: str, entry) -> None:
diff --git a/packages/meshbay-node/src/meshbay_node/ui/app.py b/packages/meshbay-node/src/meshbay_node/ui/app.py
index 21e4445..e671b72 100644
--- a/packages/meshbay-node/src/meshbay_node/ui/app.py
+++ b/packages/meshbay-node/src/meshbay_node/ui/app.py
@@ -24,6 +24,7 @@ from fastapi.responses import HTMLResponse, JSONResponse
 
 from meshbay_node import __version__
 from meshbay_common.crypto import generate_gek, wrap_gek_aes
+from meshbay_common.join import ROLE_OPERATOR
 
 log = logging.getLogger(__name__)
 
@@ -217,11 +218,61 @@ def create_ui_app(state: dict) -> FastAPI:
             ],
         }
 
+    # ── Operator pairing (localhost only) ──────────────────────────────────
+
+    @app.post("/api/operator/pair")
+    async def operator_pair():
+        """
+        Issue a one-time code that pairs a browser as this node's operator.
+
+        The code is the whole point: it binds the operator's browser identity key
+        to their account without asking the hub, which is what stops a hub from
+        naming itself node administrator (M3, and the same substitution as H3).
+        It is returned once and stored only as a hash.
+        """
+        roster = state.get("roster")
+        user_id = state.get("node_user_id")
+        if not roster or not user_id:
+            return JSONResponse({"error": "Node not connected to hub yet"}, 503)
+
+        code = await roster.create_invite(
+            group_id="",                 # operator authority is node-wide
+            user_id=user_id,
+            role=ROLE_OPERATOR,
+            created_by="local-cli",
+        )
+        invites = await roster.list_invites()
+        expires = next((i["expires_at"] for i in invites
+                        if i["user_id"] == user_id and i["role"] == ROLE_OPERATOR), "")
+        return {"code": code, "expires_at": expires, "user_id": user_id}
+
+    @app.get("/api/roster")
+    async def api_roster():
+        roster = state.get("roster")
+        if not roster:
+            return {"identities": [], "members": [], "pending_invites": 0}
+        return {
+            "identities": await roster.list_identities(),
+            "members": await roster.list_members(),
+            "pending_invites": len(await roster.list_invites()),
+        }
+
     # ── GEK initialization (operator only, localhost) ──────────────────────
 
     @app.post("/api/groups/{group_id}/gek")
     async def init_gek(group_id: str):
-        """Generate GEK, wrap for all group members, store, and activate."""
+        """
+        Generate the group key and activate it.
+
+        It used to be wrapped here for every member, using public keys fetched from
+        the hub — which is H3 with the node as the victim instead of the inviter: a
+        hub answering with its own key was handed the group key by the node itself.
+
+        Nothing is pre-wrapped for members now. Each member's copy is produced when
+        they connect, for a key they proved they hold (`join_request`). Only the
+        node's own copy is stored, so the daemon can reload the key across restarts
+        without the operator's browser.
+        """
         groups_ctx = state.get("groups_ctx", {})
         if group_id not in groups_ctx:
             return JSONResponse({"error": "Group not hosted on this node"}, 404)
@@ -234,48 +285,15 @@ def create_ui_app(state: dict) -> FastAPI:
         if not bundle_store:
             return JSONResponse({"error": "Bundle store not available"}, 503)
 
-        await hub.ensure_fresh_token()
-        session = hub._session
-        members_resp = await hub._http.get(
-            f"/v1/groups/{group_id}/members",
-            headers=session.auth_headers,
-        )
-        if not members_resp.is_success:
-            return JSONResponse(
-                {"error": f"Failed to fetch members: {members_resp.status_code}"}, 502)
-        members = members_resp.json().get("members", [])
-        if not members:
-            return JSONResponse({"error": "No members in group"}, 400)
-
         existing_gek = groups_ctx[group_id].get("gek")
         gek = existing_gek or generate_gek()
+        errors: list[str] = []
 
-        wrapped_count = 0
-        errors = []
-        for member in members:
-            username = member["username"]
-            user_id = member["user_id"]
-            try:
-                pk_data = await hub.get_user_pubkeys(username)
-                pk_x_raw = base64.b64decode(pk_data["pk_x25519"])
-                bundle = wrap_gek_aes(gek, pk_x_raw)
-                await bundle_store.store(
-                    group_id, user_id,
-                    bundle["pk_eph_b64"], bundle["nonce_b64"], bundle["wrapped_b64"],
-                )
-                wrapped_count += 1
-                log.info("GEK wrapped for %s (%s)", username, user_id[:8])
-            except Exception as e:
-                errors.append(f"{username}: {e}")
-                log.warning("Failed to wrap GEK for %s: %s", username, e)
-
-        if wrapped_count == 0:
-            return JSONResponse(
-                {"error": "Failed to wrap GEK for any member", "details": errors}, 500)
+        roster = state.get("roster")
+        authorized = len(await roster.list_members(group_id)) if roster else 0
 
-        # Also store a copy wrapped for the node keystore X25519 key
-        # so the daemon can reload GEK on restart without the operator's browser keys
-        config = state.get("config")
+        # Store a copy wrapped for the node keystore X25519 key so the daemon can
+        # reload the GEK on restart without the operator's browser keys.
         node_user_id = hub._session.user_id if hub._session else None
         pk_x_node_raw = state.get("pk_x25519_raw")
         if pk_x_node_raw and node_user_id:
@@ -286,13 +304,14 @@ def create_ui_app(state: dict) -> FastAPI:
                     node_bundle["pk_eph_b64"], node_bundle["nonce_b64"],
                     node_bundle["wrapped_b64"],
                 )
-                log.info("GEK also wrapped for node keystore (daemon reload)")
+                log.info("GEK wrapped for node keystore (daemon reload)")
             except Exception as e:
+                errors.append(f"node keystore: {e}")
                 log.warning("Failed to wrap GEK for node keystore: %s", e)
 
         groups_ctx[group_id]["gek"] = gek
-        log.info("GEK initialized for group %s — wrapped for %d/%d members",
-                 group_id[:8], wrapped_count, len(members))
+        log.info("GEK initialized for group %s — %d authorized member(s) will "
+                 "receive it on connect", group_id[:8], authorized)
 
         webrtc = state.get("webrtc")
         if webrtc and "groups" in webrtc._ctx and group_id in webrtc._ctx["groups"]:
@@ -301,8 +320,7 @@ def create_ui_app(state: dict) -> FastAPI:
         return {
             "status": "ok",
             "group_id": group_id,
-            "wrapped_count": wrapped_count,
-            "total_members": len(members),
+            "authorized_members": authorized,
             "errors": errors,
         }
 
@@ -585,8 +603,8 @@ async function initGEK(groupId) {{
     const resp = await fetch('/api/groups/' + groupId + '/gek?t=' + TOKEN, {{ method: 'POST' }});
     const data = await resp.json();
     if (resp.ok) {{
-      if (status) status.textContent = 'GEK initialized — wrapped for '
-        + data.wrapped_count + '/' + data.total_members + ' members';
+      if (status) status.textContent = 'GEK initialized — '
+        + data.authorized_members + ' authorized member(s) get it on connect';
       if (status) status.style.color = '#22c55e';
       setTimeout(() => location.reload(), 2000);
     }} else {{
diff --git a/packages/meshbay-node/tests/test_roster_pairing.py b/packages/meshbay-node/tests/test_roster_pairing.py
new file mode 100644
index 0000000..e0492ae
--- /dev/null
+++ b/packages/meshbay-node/tests/test_roster_pairing.py
@@ -0,0 +1,504 @@
+"""
+Roster and operator pairing (M3, and the mechanism that will close H3).
+
+Negative assertions, per the posture set in Phase 11.5: each test states an attack
+or a mistake that must not work. The one to keep an eye on is
+`test_daemon_does_not_auto_pin_keystore_key` — the auto-pin is what made node
+sovereignty inert as shipped, and it fails closed, so nothing else in the suite
+notices if it comes back.
+
+See `docs/invite-pairing-v1.md`.
+"""
+
+import base64
+import time
+from pathlib import Path
+
+import pytest
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+from cryptography.hazmat.primitives.asymmetric.x25519 import X25519PrivateKey
+
+from meshbay_common.crypto import generate_gek, pk_to_b64, unwrap_gek_aes
+from meshbay_common.join import ROLE_MEMBER, ROLE_OPERATOR, join_transcript
+from meshbay_node.indexer.group_index import GroupIndex
+from meshbay_node.roster import Roster, hash_code, normalize_code
+from meshbay_node.transport.webrtc_server import WebRTCPeerSession
+
+
+# ── Fixtures ──────────────────────────────────────────────────────────────────
+
+@pytest.fixture
+async def roster(tmp_path):
+    r = Roster(db_path=tmp_path / "roster.db")
+    await r.open()
+    yield r
+    await r.close()
+
+
+def _keypair_full():
+    """(sk_ed, pk_ed_b64, pk_x_b64, sk_x) — the X25519 secret is needed to unwrap."""
+    sk_ed = Ed25519PrivateKey.generate()
+    sk_x = X25519PrivateKey.generate()
+    pk_ed_b64 = pk_to_b64(sk_ed.public_key())
+    pk_x_b64 = base64.b64encode(
+        sk_x.public_key().public_bytes(
+            encoding=serialization.Encoding.Raw,
+            format=serialization.PublicFormat.Raw,
+        )
+    ).decode()
+    return sk_ed, pk_ed_b64, pk_x_b64, sk_x
+
+
+def _keypair():
+    sk_ed, pk_ed_b64, pk_x_b64, _ = _keypair_full()
+    return sk_ed, pk_ed_b64, pk_x_b64
+
+
+def _session(tmp_path: Path, roster, user_id: str = "grenet",
+             group_id: str | None = None, gek: bytes | None = None,
+             join_policy: str = "invite") -> WebRTCPeerSession:
+    """A peer session with the join path wired and sending stubbed out."""
+    shared_root = tmp_path / "shared"
+    shared_root.mkdir(exist_ok=True)
+    index = GroupIndex(group_id="g" * 32, sk_node=Ed25519PrivateKey.generate())
+
+    session = WebRTCPeerSession.__new__(WebRTCPeerSession)
+    session._ctx = {
+        "shared_root": shared_root,
+        "index": index,
+        "sk_node": index.sk_node,
+        "roster": roster,
+    }
+    if group_id:
+        session._ctx["groups"] = {
+            group_id: {
+                "gek": gek,
+                "shared_root": shared_root,
+                "index": index,
+                "join_policy": join_policy,
+            },
+        }
+    session._group_id = group_id
+    session._user_id = user_id
+    session._username = user_id
+    session._pk_user = ""
+    session._uploads = {}
+    session._join_attempts = 0
+    session._nonce_node = b"\x11" * 32
+    session._remote_ip = ""
+    session.sent = []
+    session._send = session.sent.append
+    session._audit = lambda *a, **k: None
+    return session
+
+
+def _join_msg(session, sk_ed, pk_ed_b64, pk_x_b64, code="", user_id="grenet",
+              group_id="", nonce=None, ts=None):
+    ts = int(time.time()) if ts is None else ts
+    transcript = join_transcript(
+        node_pk_b64=session._node_pk_b64(),
+        group_id=group_id,
+        user_id=user_id,
+        pk_ed25519_b64=pk_ed_b64,
+        pk_x25519_b64=pk_x_b64,
+        nonce_node=nonce if nonce is not None else session._nonce_node,
+        ts=ts,
+    )
+    return {
+        "type": "join_request",
+        "group_id": group_id,
+        "pk_ed25519": pk_ed_b64,
+        "pk_x25519": pk_x_b64,
+        "code": code,
+        "ts": ts,
+        "sig": base64.b64encode(sk_ed.sign(transcript)).decode(),
+    }
+
+
+def _last(session):
+    return session.sent[-1] if session.sent else {}
+
+
+# ── Roster ────────────────────────────────────────────────────────────────────
+
+async def test_invite_is_single_use(roster):
+    code = await roster.create_invite("", "grenet", ROLE_OPERATOR, "local-cli")
+    assert await roster.consume_invite(code, "grenet") is not None
+    assert await roster.consume_invite(code, "grenet") is None, (
+        "a pairing code must not be redeemable twice")
+
+
+async def test_invite_is_bound_to_one_account(roster):
+    """A leaked code must be useless to whoever finds it."""
+    code = await roster.create_invite("", "grenet", ROLE_OPERATOR, "local-cli")
+    assert await roster.consume_invite(code, "eve") is None
+    assert await roster.consume_invite(code, "grenet") is not None
+
+
+async def test_expired_invite_is_refused(roster):
+    code = await roster.create_invite("", "grenet", ROLE_OPERATOR, "local-cli", ttl=-1)
+    assert await roster.consume_invite(code, "grenet") is None
+
+
+async def test_reinvite_supersedes_the_previous_code(roster):
+    first = await roster.create_invite("", "grenet", ROLE_OPERATOR, "local-cli")
+    second = await roster.create_invite("", "grenet", ROLE_OPERATOR, "local-cli")
+    assert await roster.consume_invite(first, "grenet") is None
+    assert await roster.consume_invite(second, "grenet") is not None
+
+
+async def test_codes_are_not_stored_in_the_clear(roster, tmp_path):
+    code = await roster.create_invite("", "grenet", ROLE_OPERATOR, "local-cli")
+    rows = await roster.list_invites()
+    assert rows and rows[0]["code_hash"] != normalize_code(code)
+    assert rows[0]["code_hash"] == hash_code(code)
+
+
+def test_code_normalization_absorbs_human_error():
+    """Someone reading a code aloud must not be able to get it wrong."""
+    assert normalize_code("k7m2-qx4p") == normalize_code("K7M2QX4P")
+    assert normalize_code("O1IL") == "0111"
+    assert normalize_code(" k7m2 qx4p ") == "K7M2QX4P"
+
+
+async def test_operator_pks_reflect_unpinning(roster):
+    _, pk_ed_b64, pk_x_b64 = _keypair()
+    await roster.pin_identity("grenet", "grenet", pk_ed_b64, pk_x_b64, "code")
+    await roster.set_member("", "grenet", ROLE_OPERATOR, "active", "local-cli")
+    assert await roster.operator_pks() == [pk_ed_b64]
+
+    await roster.unpin("grenet")
+    assert await roster.operator_pks() == [], (
+        "authority must disappear with the pin, without a daemon restart")
+
+
+# ── Join / pairing over MNP ───────────────────────────────────────────────────
+
+async def test_pairing_with_a_valid_code_pins_the_identity(tmp_path, roster):
+    session = _session(tmp_path, roster)
+    sk_ed, pk_ed_b64, pk_x_b64 = _keypair()
+    code = await roster.create_invite("", "grenet", ROLE_OPERATOR, "local-cli")
+
+    await session._do_join_request(
+        _join_msg(session, sk_ed, pk_ed_b64, pk_x_b64, code=code))
+
+    assert _last(session).get("ok") is True
+    pinned = await roster.get_identity("grenet")
+    assert pinned["pk_ed25519"] == pk_ed_b64
+    assert await roster.operator_pks() == [pk_ed_b64]
+
+
+async def test_pairing_without_a_code_is_refused(tmp_path, roster):
+    """Fails closed: an unknown identity gets nothing until someone authorizes it."""
+    session = _session(tmp_path, roster)
+    sk_ed, pk_ed_b64, pk_x_b64 = _keypair()
+
+    await session._do_join_request(_join_msg(session, sk_ed, pk_ed_b64, pk_x_b64))
+
+    assert _last(session).get("ok") is False
+    assert _last(session).get("reason") == "code_required"
+    assert await roster.get_identity("grenet") is None
+
+
+async def test_wrong_code_pins_nothing(tmp_path, roster):
+    session = _session(tmp_path, roster)
+    sk_ed, pk_ed_b64, pk_x_b64 = _keypair()
+    await roster.create_invite("", "grenet", ROLE_OPERATOR, "local-cli")
+
+    await session._do_join_request(
+        _join_msg(session, sk_ed, pk_ed_b64, pk_x_b64, code="ZZZZ-ZZZZ"))
+
+    assert _last(session).get("reason") == "code_invalid"
+    assert await roster.get_identity("grenet") is None
+
+
+async def test_signature_must_cover_the_presented_keys(tmp_path, roster):
+    """
+    The heart of it: the X25519 key is only trustworthy because the Ed25519
+    identity signed it. Swapping in another encryption key after signing must fail.
+    """
+    session = _session(tmp_path, roster)
+    sk_ed, pk_ed_b64, pk_x_b64 = _keypair()
+    code = await roster.create_invite("", "grenet", ROLE_OPERATOR, "local-cli")
+
+    msg = _join_msg(session, sk_ed, pk_ed_b64, pk_x_b64, code=code)
+    _, _, attacker_pk_x = _keypair()
+    msg["pk_x25519"] = attacker_pk_x
+
+    await session._do_join_request(msg)
+
+    assert _last(session).get("reason") == "signature_invalid"
+    assert await roster.get_identity("grenet") is None
+
+
+async def test_join_cannot_be_replayed_onto_another_connection(tmp_path, roster):
+    session = _session(tmp_path, roster)
+    sk_ed, pk_ed_b64, pk_x_b64 = _keypair()
+    code = await roster.create_invite("", "grenet", ROLE_OPERATOR, "local-cli")
+
+    # Signed against a nonce this connection never issued.
+    msg = _join_msg(session, sk_ed, pk_ed_b64, pk_x_b64, code=code,
+                    nonce=b"\x99" * 32)
+    await session._do_join_request(msg)
+
+    assert _last(session).get("reason") == "signature_invalid"
+    assert await roster.get_identity("grenet") is None
+
+
+async def test_pinned_identity_presenting_a_new_key_is_refused(tmp_path, roster):
+    """
+    11.5.8's rule, applied to people: a changed key is refused outright rather
+    than warned about, and clearing it is a deliberate operator action.
+    """
+    session = _session(tmp_path, roster)
+    _, old_pk_ed, old_pk_x = _keypair()
+    await roster.pin_identity("grenet", "grenet", old_pk_ed, old_pk_x, "code")
+
+    sk_ed2, new_pk_ed, new_pk_x = _keypair()
+    await session._do_join_request(
+        _join_msg(session, sk_ed2, new_pk_ed, new_pk_x, code="ANY-CODE"))
+
+    assert _last(session).get("reason") == "key_changed"
+    assert (await roster.get_identity("grenet"))["pk_ed25519"] == old_pk_ed
+
+
+async def test_attempts_are_bounded(tmp_path, roster):
+    session = _session(tmp_path, roster)
+    sk_ed, pk_ed_b64, pk_x_b64 = _keypair()
+    await roster.create_invite("", "grenet", ROLE_OPERATOR, "local-cli")
+
+    for _ in range(6):
+        await session._do_join_request(
+            _join_msg(session, sk_ed, pk_ed_b64, pk_x_b64, code="AAAA-AAAA"))
+
+    assert any(m.get("detail") == "Too many attempts" for m in session.sent), (
+        "a connection must not be able to sit there guessing codes")
+
+
+async def test_failures_are_counted_across_connections(tmp_path, roster):
+    """
+    The adversary who can mint a token for any account is the hub, and it can
+    reconnect at will — so a per-connection budget alone would bound nothing.
+    """
+    shared_ctx = None
+    for _ in range(6):
+        session = _session(tmp_path, roster)
+        if shared_ctx is None:
+            shared_ctx = session._ctx
+        else:
+            session._ctx = shared_ctx          # same node, new connection
+        sk_ed, pk_ed_b64, pk_x_b64 = _keypair()
+        for _ in range(4):
+            await session._do_join_request(
+                _join_msg(session, sk_ed, pk_ed_b64, pk_x_b64, code="AAAA-AAAA"))
+
+    assert any(m.get("detail") == "Pairing temporarily locked"
+               for m in session.sent), (
+        "reconnecting must not reset the pairing budget")
+
+
+async def test_group_id_cannot_name_another_group(tmp_path, roster):
+    session = _session(tmp_path, roster)
+    session._group_id = "a" * 32
+    sk_ed, pk_ed_b64, pk_x_b64 = _keypair()
+
+    await session._do_join_request(
+        _join_msg(session, sk_ed, pk_ed_b64, pk_x_b64, group_id="b" * 32))
+
+    assert _last(session).get("reason") == "group_mismatch"
+
+
+# ── H3: the node wraps the group key, and only for people it admitted ─────────
+
+GROUP = "g" * 32
+
+
+async def test_node_wraps_the_gek_for_the_key_the_member_proved(tmp_path, roster):
+    """
+    The H3 fix. Nobody fetches a public key from the hub: the node encrypts the
+    group key for the X25519 key the joiner signed with their pinned identity, so
+    a hub substituting a key of its own has nothing to substitute into.
+    """
+    gek = generate_gek()
+    session = _session(tmp_path, roster, user_id="bob", group_id=GROUP, gek=gek)
+    sk_ed, pk_ed_b64, pk_x_b64, sk_x = _keypair_full()
+
+    code = await roster.create_invite(GROUP, "bob", ROLE_MEMBER, "grenet")
+    await session._do_join_request(
+        _join_msg(session, sk_ed, pk_ed_b64, pk_x_b64, code=code,
+                  user_id="bob", group_id=GROUP))
+
+    reply = _last(session)
+    assert reply["ok"] is True and reply["gek"] is True
+
+    pk_x_raw = base64.b64decode(pk_x_b64)
+    sk_x_raw = sk_x.private_bytes(
+        encoding=serialization.Encoding.Raw,
+        format=serialization.PrivateFormat.Raw,
+        encryption_algorithm=serialization.NoEncryption(),
+    )
+    assert unwrap_gek_aes(reply, sk_x_raw, pk_x_raw) == gek
+
+
+async def test_hub_membership_alone_yields_no_key(tmp_path, roster):
+    """
+    A hub can invent an account, add it to a group and mint it a token. What it
+    cannot do is put it on the node's roster — so the key never leaves.
+    """
+    gek = generate_gek()
+    session = _session(tmp_path, roster, user_id="eve", group_id=GROUP, gek=gek)
+    sk_ed, pk_ed_b64, pk_x_b64 = _keypair()
+
+    # Pinned on this node (say, for another group) but never admitted to this one.
+    await roster.pin_identity("eve", "eve", pk_ed_b64, pk_x_b64, "code")
+
+    await session._do_join_request(
+        _join_msg(session, sk_ed, pk_ed_b64, pk_x_b64,
+                  user_id="eve", group_id=GROUP))
+
+    reply = _last(session)
+    assert reply.get("gek") is False
+    assert reply.get("reason") == "not_authorized_for_group"
+    assert "wrapped_b64" not in reply
+
+
+async def test_open_join_group_admits_without_a_code(tmp_path, roster):
+    """§3.4: where anyone may join, a code protects nothing and is not required."""
+    gek = generate_gek()
+    session = _session(tmp_path, roster, user_id="newcomer", group_id=GROUP,
+                       gek=gek, join_policy="open")
+    sk_ed, pk_ed_b64, pk_x_b64 = _keypair()
+
+    await session._do_join_request(
+        _join_msg(session, sk_ed, pk_ed_b64, pk_x_b64,
+                  user_id="newcomer", group_id=GROUP))
+
+    reply = _last(session)
+    assert reply["ok"] is True and reply["gek"] is True
+    pinned = await roster.get_identity("newcomer")
+    assert pinned["pinned_via"] == "tofu"
+
+
+async def test_invite_only_group_still_demands_a_code(tmp_path, roster):
+    """Being public (discoverable) is not being open (admitting anyone)."""
+    gek = generate_gek()
+    session = _session(tmp_path, roster, user_id="newcomer", group_id=GROUP,
+                       gek=gek, join_policy="invite")
+    sk_ed, pk_ed_b64, pk_x_b64 = _keypair()
+
+    await session._do_join_request(
+        _join_msg(session, sk_ed, pk_ed_b64, pk_x_b64,
+                  user_id="newcomer", group_id=GROUP))
+
+    assert _last(session).get("reason") == "code_required"
+    assert await roster.get_identity("newcomer") is None
+
+
+async def test_unknown_group_is_invite_only(tmp_path, roster):
+    """
+    Fail closed: a group whose policy the node cannot read is treated as
+    invite-only, never as open.
+    """
+    session = _session(tmp_path, roster, user_id="newcomer")
+    session._group_id = "unconfigured-group"
+    assert session._group_join_policy("unconfigured-group") == "invite"
+    assert session._group_join_policy("") == "invite"
+
+
+def test_join_policy_is_carried_from_node_config():
+    """
+    The policy reaches the transport from node.toml. If it ever came from the hub
+    instead, a hub could declare any group open and be handed its key.
+    """
+    daemon_src = (Path(__file__).parent.parent
+                  / "src" / "meshbay_node" / "daemon.py").read_text()
+    assert '"join_policy": group_cfg.join_policy' in daemon_src
+
+    config_src = (Path(__file__).parent.parent
+                  / "src" / "meshbay_node" / "config.py").read_text()
+    assert "join_policy" in config_src, "GroupConfig must carry the admission policy"
+
+
+async def test_revoked_member_stops_receiving_the_key(tmp_path, roster):
+    """
+    Wrapping on demand is what makes revocation work. A stored bundle survived
+    revocation; this does not. (Rotating the GEK is still required — the
+    ex-member has the old one.)
+    """
+    gek = generate_gek()
+    session = _session(tmp_path, roster, user_id="bob", group_id=GROUP, gek=gek)
+    sk_ed, pk_ed_b64, pk_x_b64 = _keypair()
+    await roster.pin_identity("bob", "bob", pk_ed_b64, pk_x_b64, "code")
+    await roster.set_member(GROUP, "bob", ROLE_MEMBER, "active", "grenet")
+
+    await session._do_join_request(
+        _join_msg(session, sk_ed, pk_ed_b64, pk_x_b64,
+                  user_id="bob", group_id=GROUP))
+    assert _last(session)["gek"] is True
+
+    await roster.set_status(GROUP, "bob", "revoked")
+    session.sent.clear()
+    await session._do_join_request(
+        _join_msg(session, sk_ed, pk_ed_b64, pk_x_b64,
+                  user_id="bob", group_id=GROUP))
+    assert _last(session).get("gek") is False
+
+
+# ── M3: where node authority comes from ───────────────────────────────────────
+
+async def test_admin_signature_verified_against_the_paired_key(tmp_path, roster):
+    session = _session(tmp_path, roster)
+    sk_ed, pk_ed_b64, pk_x_b64 = _keypair()
+    await roster.pin_identity("grenet", "grenet", pk_ed_b64, pk_x_b64, "code")
+    await roster.set_member("", "grenet", ROLE_OPERATOR, "active", "local-cli")
+
+    transcript = b"meshbay:admin:v1 whatever"
+    assert await session._verify_admin_sig(transcript, sk_ed.sign(transcript))
+
+    stranger = Ed25519PrivateKey.generate()
+    assert not await session._verify_admin_sig(
+        transcript, stranger.sign(transcript))
+
+
+async def test_unpinned_operator_loses_authority_immediately(tmp_path, roster):
+    """No caching: revoking a paired browser must not need a daemon restart."""
+    session = _session(tmp_path, roster)
+    sk_ed, pk_ed_b64, pk_x_b64 = _keypair()
+    await roster.pin_identity("grenet", "grenet", pk_ed_b64, pk_x_b64, "code")
+    await roster.set_member("", "grenet", ROLE_OPERATOR, "active", "local-cli")
+
+    transcript = b"meshbay:admin:v1 whatever"
+    assert await session._verify_admin_sig(transcript, sk_ed.sign(transcript))
+
+    await roster.unpin("grenet")
+    assert not await session._verify_admin_sig(transcript, sk_ed.sign(transcript))
+
+
+def test_daemon_does_not_auto_pin_keystore_key():
+    """
+    M3: the daemon used to auto-pin its own keystore key as the admin key, while
+    the browser signs with the user's identity key. Different keys, so every
+    privileged operation failed closed with a signature error that looked like a
+    bug elsewhere — and the demo only worked because a deploy script overwrote it.
+
+    Authority now comes from the roster, or from an explicit node.toml value.
+    """
+    source = (Path(__file__).parent.parent
+              / "src" / "meshbay_node" / "daemon.py").read_text()
+    assert "Auto-pinning admin key" not in source
+    assert "_resolve_admin_pk" not in source, (
+        "the auto-pin resolver is back — node authority must be established "
+        "locally by pairing, never inferred from the node's own keystore (M3)")
+
+
+def test_admin_authority_is_never_fetched_from_the_hub():
+    """
+    The fix M3 invites: ask the hub which key belongs to the operator. That would
+    hand a malicious hub the node — the same substitution as H3, one level deeper.
+    """
+    source = (Path(__file__).parent.parent
+              / "src" / "meshbay_node" / "daemon.py").read_text()
+    admin_region = source[source.find("_legacy_admin_pk"):]
+    assert "pubkeys" not in admin_region.split("def ")[1], (
+        "node authority must never be resolved through a hub lookup")
diff --git a/packages/meshbay-node/tests/test_security_regressions.py b/packages/meshbay-node/tests/test_security_regressions.py
index 9299bf4..6bb680c 100644
--- a/packages/meshbay-node/tests/test_security_regressions.py
+++ b/packages/meshbay-node/tests/test_security_regressions.py
@@ -216,16 +216,35 @@ def test_daemon_sets_no_global_chat_store(tmp_path):
 
 # ── H2: node admin UI escaping ───────────────────────────────────────────────
 
-def test_gek_bundle_store_requires_admin_challenge(tmp_path):
+def test_no_member_can_hand_the_node_key_material(tmp_path):
     """
-    C5b: gek_bundle_store used to write whatever any authenticated member sent.
-    It must now answer with a challenge and store nothing until a valid
-    node-operator signature arrives.
+    C5b, strengthened by the invite redesign (docs/invite-pairing-v1.md).
+
+    This test used to assert that `gek_bundle_store` answered with an admin
+    challenge and stored nothing without an operator signature. The message is now
+    gone entirely: the node holds the GEK and wraps it itself, so no member ever
+    submits key material, authorized or not. Deleting the path is a stronger
+    guarantee than gating it, which is why the assertion changed rather than the
+    behaviour regressing.
     """
+    from meshbay_common.protocol import MNP as _MNP
+
+    assert not hasattr(_MNP, "GEK_BUNDLE_STORE"), (
+        "the member-supplied bundle message is back — the node must never accept "
+        "key material over MNP (C5b)"
+    )
+
+    source = (Path(__file__).parent.parent
+              / "src" / "meshbay_node" / "transport" / "webrtc_server.py").read_text()
+    assert "_do_gek_bundle_store" not in source
+    assert "_admin_exec_bundle_store" not in source
+
+
+def test_unknown_message_stores_nothing(tmp_path):
+    """A peer sending the retired message must not reach any storage path."""
     session = _session(tmp_path, "ordinary-member")
     session._group_id = None
     session._admin_ops = {}
-    session._ctx["admin_pk_ed25519"] = Ed25519PrivateKey.generate().public_key()
 
     stored = []
 
@@ -234,27 +253,13 @@ def test_gek_bundle_store_requires_admin_challenge(tmp_path):
             stored.append(args)
 
     session._ctx["bundle_store"] = _Store()
-    session._do_gek_bundle_store({
+    session._handle_message({
+        "type": "gek_bundle_store",
         "user_id": "victim", "group_id": "g" * 32,
         "pk_eph_b64": "AA==", "nonce_b64": "AA==", "wrapped_b64": "AA==",
     })
 
-    assert stored == [], "bundle written without operator authorization (C5b)"
-    assert any(m.get("type") == "admin_challenge" for m in session.sent)
-
-
-def test_gek_bundle_store_refused_without_pinned_admin_key(tmp_path):
-    """C5b: deny by default — no pinned key means no privileged operation."""
-    session = _session(tmp_path, "ordinary-member")
-    session._group_id = None
-    session._admin_ops = {}
-    session._ctx["bundle_store"] = object()
-
-    session._do_gek_bundle_store({
-        "user_id": "victim", "group_id": "g" * 32,
-        "pk_eph_b64": "AA==", "nonce_b64": "AA==", "wrapped_b64": "AA==",
-    })
-    assert any(m.get("type") == "error" for m in session.sent)
+    assert stored == [], "a retired message type still reached the bundle store"
 
 
 def test_gek_auto_activation_is_gone():
@@ -287,7 +292,7 @@ def test_admin_transcript_is_domain_separated():
 
 
 @pytest.mark.parametrize("field,value", [
-    ("op", "gek_bundle_store"),
+    ("op", "invite_create"),
     ("subject", "file-2"),
     ("node_pk_b64", "OTHERNODE"),
     ("group_id", "h" * 32),
@@ -320,15 +325,15 @@ def test_admin_signature_does_not_transfer_between_operations(tmp_path):
     H5: the concrete attack. A signature collected to delete a file must not
     authorize storing a GEK bundle.
     """
-    from meshbay_common.adminop import OP_FILE_DELETE, OP_GEK_BUNDLE_STORE
+    from meshbay_common.adminop import OP_FILE_DELETE, OP_INVITE_CREATE
 
     sk_admin = Ed25519PrivateKey.generate()
     delete_transcript = _transcript(op=OP_FILE_DELETE)
     signature = sk_admin.sign(delete_transcript)
 
-    store_transcript = _transcript(op=OP_GEK_BUNDLE_STORE)
+    invite_transcript = _transcript(op=OP_INVITE_CREATE)
     with pytest.raises(Exception):
-        sk_admin.public_key().verify(signature, store_transcript)
+        sk_admin.public_key().verify(signature, invite_transcript)
 
 
 def test_admin_challenge_expires(tmp_path):
@@ -573,3 +578,4 @@ def test_admin_ui_escapes_filenames(tmp_path):
 
     assert payload not in html, "filename rendered unescaped — stored XSS (H2)"
     assert "&lt;img" in html, "filename should appear escaped"
+
diff --git a/packages/meshbay-node/tests/test_webrtc_transport.py b/packages/meshbay-node/tests/test_webrtc_transport.py
index 59b48ac..07bdbea 100644
--- a/packages/meshbay-node/tests/test_webrtc_transport.py
+++ b/packages/meshbay-node/tests/test_webrtc_transport.py
@@ -31,6 +31,7 @@ from meshbay_common.crypto import (
     wrap_gek,
     wrap_gek_aes,
     unwrap_gek,
+    unwrap_gek_aes,
 )
 from meshbay_common.webcrypto import chunk_key_aes, decrypt_chunk_aes
 from meshbay_common.protocol import MNP
@@ -42,10 +43,12 @@ from meshbay_common.handshake import (
 )
 from meshbay_common.adminop import (
     OP_FILE_DELETE,
-    OP_GEK_BUNDLE_STORE,
+    OP_INVITE_CREATE,
     admin_transcript,
 )
+from meshbay_common.join import ROLE_MEMBER, ROLE_OPERATOR, join_transcript
 from meshbay_node.bundle_store import BundleStore
+from meshbay_node.roster import Roster
 from meshbay_node.indexer import DirectoryIndexer
 from meshbay_node.transport.webrtc_server import WebRTCTransport
 
@@ -184,9 +187,30 @@ async def _handshake_with_gek_proof(channel, received, sk_hub, gek, groups=None,
     return msg
 
 
-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)."""
+def _token(sk_hub, jwt_sub, peer_id, group_id, pk_user="test"):
+    """A hub-issued user token, as the browser would present it."""
+    sk_h_pem = sk_hub.private_bytes(
+        serialization.Encoding.PEM,
+        serialization.PrivateFormat.PKCS8,
+        serialization.NoEncryption(),
+    )
+    now = int(time.time())
+    return jwt.encode({
+        "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": [group_id], "scope": "user",
+    }, sk_h_pem, algorithm="EdDSA")
+
+
+async def _open_channel(transport, peer_id):
+    """
+    Signaling only: a live DataChannel with no MNP handshake performed.
+
+    Separate from `_setup_peer` because someone joining a group for the first time
+    cannot complete the handshake — they have no GEK to prove — and the join has to
+    happen in that window.
+    """
     pc = RTCPeerConnection()
     q = asyncio.Queue()
     buf = bytearray()
@@ -215,6 +239,13 @@ async def _setup_peer(transport, sk_hub, gek, peer_id, jwt_sub="user-001", sk_us
     answer_sdp, _ = await transport.handle_offer(pc.localDescription.sdp, peer_id)
     await pc.setRemoteDescription(RTCSessionDescription(sdp=answer_sdp, type="answer"))
     await asyncio.wait_for(ready.wait(), timeout=5.0)
+    return pc, ch, q
+
+
+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, ch, q = await _open_channel(transport, peer_id)
 
     pk_user = "test"
     if sk_user:
@@ -223,18 +254,7 @@ async def _setup_peer(transport, sk_hub, gek, peer_id, jwt_sub="user-001", sk_us
                 serialization.Encoding.Raw, serialization.PublicFormat.Raw)
         ).decode()
 
-    sk_h_pem = sk_hub.private_bytes(
-        serialization.Encoding.PEM,
-        serialization.PrivateFormat.PKCS8,
-        serialization.NoEncryption(),
-    )
-    now = int(time.time())
-    token = jwt.encode({
-        "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": [group_id], "scope": "user",
-    }, sk_h_pem, algorithm="EdDSA")
+    token = _token(sk_hub, jwt_sub, peer_id, group_id, pk_user)
 
     msg = await _do_mnp_handshake(ch, q, token, gek, pc, group_id)
     assert msg["type"] == MNP.HANDSHAKE_ACK
@@ -1059,71 +1079,114 @@ def x25519_keypair():
 
 
 @pytest.mark.asyncio
-async def test_gek_bundle_store_and_fetch(sk_node, sk_hub, gek, shared_dir,
-                                          tmp_path, x25519_keypair):
-    """GEK bundle stored on node via DataChannel, then fetched during handshake."""
+async def test_invite_then_join_delivers_the_gek(sk_node, sk_hub, gek, shared_dir,
+                                                 tmp_path, x25519_keypair):
+    """
+    The whole invite flow over a real DataChannel, end to end.
+
+    The operator asks for a code; the invitee — who has never held the group key
+    and therefore cannot complete the GEK proof — redeems it in the pre-proof
+    window and the node wraps the key for the X25519 key they just proved they
+    hold. At no point is a public key fetched from the hub, which is the point:
+    that lookup was H3.
+    """
     hub_pk_pem = _hub_pk_pem(sk_hub)
     indexer = DirectoryIndexer(root=shared_dir, group_id="g", sk_node=sk_node, gek=gek)
     await indexer.initial_scan()
 
-    bundle_store = BundleStore(db_path=tmp_path / "bundles.db")
-    await bundle_store.open()
+    roster = Roster(db_path=tmp_path / "roster.db")
+    await roster.open()
 
     transport = WebRTCTransport(
         sk_node=sk_node, hub_pk_pem=hub_pk_pem, gek=gek,
         shared_root=shared_dir, index=indexer.index,
         stun_servers=[],
     )
-    transport._ctx["bundle_store"] = bundle_store
+    transport._ctx["roster"] = roster
+    transport._ctx["has_admin_authority"] = True
+    transport._ctx["groups"] = {
+        TEST_GROUP: {"gek": gek, "shared_root": shared_dir, "index": indexer.index},
+    }
 
-    # Storing a bundle is a node-operator operation (C5b): the node challenges and
-    # only the pinned admin key is accepted.
+    # A paired operator, as `meshbay-node operator pair` would have left it.
     sk_admin = Ed25519PrivateKey.generate()
-    transport._ctx["admin_pk_ed25519"] = sk_admin.public_key()
+    admin_pk_b64 = pk_to_b64(sk_admin.public_key())
+    await roster.pin_identity("user-001", "grenet", admin_pk_b64, "AA==", "code")
+    await roster.set_member("", "user-001", ROLE_OPERATOR, "active", "local-cli")
 
     pc_admin, ch_admin, q_admin = await _setup_peer(
         transport, sk_hub, gek, "peer-admin")
 
-    sk_x_raw, pk_x_raw = x25519_keypair
-    bundle = wrap_gek(gek, pk_x_raw)
-
+    # 1. The operator asks the node for an invitation code.
     ch_admin.send(_pack({
-        "type": MNP.GEK_BUNDLE_STORE,
-        "v": MNP_VERSION,
-        "user_id": "user-002",
-        "group_id": "g",
-        "pk_eph_b64": bundle["pk_eph_b64"],
-        "nonce_b64": bundle["nonce_b64"],
-        "wrapped_b64": bundle["wrapped_b64"],
+        "type": MNP.INVITE_CREATE, "v": MNP_VERSION,
+        "user_id": "user-002", "group_id": TEST_GROUP, "username": "bob",
     }))
-
     challenge_msg = await asyncio.wait_for(q_admin.get(), timeout=5.0)
     assert challenge_msg["type"] == MNP.ADMIN_CHALLENGE
-    assert challenge_msg["op"] == OP_GEK_BUNDLE_STORE
+    assert challenge_msg["op"] == OP_INVITE_CREATE
     assert challenge_msg["subject"] == "user-002"
 
-    signature = sk_admin.sign(_transcript_from(challenge_msg))
     ch_admin.send(_pack({
         "type": MNP.ADMIN_RESPONSE, "v": MNP_VERSION,
         "op_id": challenge_msg["op_id"],
-        "signature": base64.b64encode(signature).decode(),
+        "signature": base64.b64encode(
+            sk_admin.sign(_transcript_from(challenge_msg))).decode(),
     }))
+    invite = await asyncio.wait_for(q_admin.get(), timeout=5.0)
+    assert invite["type"] == MNP.INVITE_RESULT
+    code = invite["code"]
+    assert code and len(code) == 9        # XXXX-XXXX
 
-    ack = await asyncio.wait_for(q_admin.get(), timeout=5.0)
-    assert ack["type"] == "ack"
-    assert ack["detail"] == "gek_bundle_stored"
+    # 2. Bob connects. He cannot prove GEK possession — he has never had it — so
+    #    he redeems the code in the pre-proof window instead.
+    sk_x_raw, pk_x_raw = x25519_keypair
+    sk_bob_ed = Ed25519PrivateKey.generate()
+    pc_bob, ch_bob, q_bob = await _open_channel(transport, "peer-bob")
 
-    # Verify bundle was persisted
-    stored = await bundle_store.fetch("g", "user-002")
-    assert stored is not None
-    assert stored["pk_eph_b64"] == bundle["pk_eph_b64"]
+    nonce_c = os.urandom(NONCE_LEN)
+    ch_bob.send(_pack({
+        "type": MNP.HANDSHAKE, "v": MNP_VERSION,
+        "token": _token(sk_hub, "user-002", "peer-bob", TEST_GROUP),
+        "group_id": TEST_GROUP,
+        "nonce": base64.b64encode(nonce_c).decode(),
+    }))
+    challenge = await asyncio.wait_for(q_bob.get(), timeout=5.0)
+    assert challenge["type"] == MNP.HANDSHAKE_CHALLENGE
+    nonce_s = base64.b64decode(challenge["nonce"])
+
+    pk_ed_b64 = pk_to_b64(sk_bob_ed.public_key())
+    pk_x_b64 = base64.b64encode(pk_x_raw).decode()
+    ts = int(time.time())
+    transcript = join_transcript(
+        node_pk_b64=pk_to_b64(sk_node.public_key()),
+        group_id=TEST_GROUP, user_id="user-002",
+        pk_ed25519_b64=pk_ed_b64, pk_x25519_b64=pk_x_b64,
+        nonce_node=nonce_s, ts=ts,
+    )
+    ch_bob.send(_pack({
+        "type": MNP.JOIN_REQUEST, "v": MNP_VERSION,
+        "group_id": TEST_GROUP,
+        "pk_ed25519": pk_ed_b64, "pk_x25519": pk_x_b64,
+        "code": code, "ts": ts,
+        "sig": base64.b64encode(sk_bob_ed.sign(transcript)).decode(),
+    }))
 
-    # Unwrap to verify it's correct
-    recovered = unwrap_gek(stored, sk_x_raw, pk_x_raw)
-    assert recovered == gek
+    result = await asyncio.wait_for(q_bob.get(), timeout=5.0)
+    assert result["type"] == MNP.JOIN_RESULT
+    assert result["ok"] is True
+    assert result["gek"] is True
+    assert result["role"] == ROLE_MEMBER
 
-    await bundle_store.close()
+    # 3. The key really is the group key, and only Bob's secret opens it.
+    assert unwrap_gek_aes(result, sk_x_raw, pk_x_raw) == gek
+
+    # 4. The code is spent.
+    assert await roster.consume_invite(code, "user-002") is None
+
+    await roster.close()
     await pc_admin.close()
+    await pc_bob.close()
     await transport.close_all()
 
 
@@ -1420,10 +1483,13 @@ async def test_gek_not_auto_activated_on_bundle_store(sk_node, sk_hub, gek, shar
     pc_admin, ch_admin, q_admin = await _setup_peer(
         transport, sk_hub, gek, "peer-setup-admin")
 
-    # An ordinary member wraps a key of their choosing for the operator's public key.
+    # An ordinary member wraps a key of their choosing for the operator's public
+    # key and offers it to the node. The message that used to carry this no longer
+    # exists (the node wraps the GEK itself now), so it reaches no handler at all —
+    # a stronger outcome than the admin challenge this test used to assert.
     node_bundle = wrap_gek_aes(attacker_gek, pk_x_raw)
     ch_admin.send(_pack({
-        "type": MNP.GEK_BUNDLE_STORE,
+        "type": "gek_bundle_store",
         "v": MNP_VERSION,
         "user_id": "node-operator",
         "group_id": "g",
@@ -1432,12 +1498,8 @@ async def test_gek_not_auto_activated_on_bundle_store(sk_node, sk_hub, gek, shar
         "wrapped_b64": node_bundle["wrapped_b64"],
     }))
 
-    # The node demands an operator signature instead of storing and adopting it.
-    reply = await asyncio.wait_for(q_admin.get(), timeout=5.0)
-    assert reply["type"] == MNP.ADMIN_CHALLENGE
-    assert reply["op"] == OP_GEK_BUNDLE_STORE
-
-    await asyncio.sleep(0.2)
+    await asyncio.sleep(0.5)
+    assert q_admin.empty(), "the retired bundle message still gets a response"
 
     assert transport._ctx.get("gek") == gek, "group key was seized over MNP (C5b)"
     assert await bundle_store.fetch("g", "node-operator") is None
-- 
cgit v1.2.3


From 8f6e2f724fd24a077de11d4a3b3ae069d369324d Mon Sep 17 00:00:00 2001
From: Christophe Besson <cbesson@gmail.com>
Date: Fri, 14 Aug 2026 01:27:57 +0200
Subject: feat(node): operator surface — member list, invite, revoke, unpin
 over SSH
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A node admits people from its own roster, and until now a headless operator had
no way to put anyone on it: pairing worked from the CLI, everything else needed a
browser on a machine that does not have one. Absorbs milestones 14.3/14.4.

  member list                 who is admitted, role, status, when and how pinned
  member invite <username>     one-time code; the node wraps the key when they
                               connect, so nobody has to be online then
  member revoke <username>     stop serving them the key
  member unpin <username>      forget the pin so they can pair again after a reset

All of it goes through the daemon's loopback API with the per-run session token
(11.5.3) — _daemon_api() in daemon.py, which also replaced three hand-rolled
urllib blocks. `status` deliberately still reads the keystore, config and roster
directly, so it works while the daemon is stopped.

Two things the commands say out loud, because getting them wrong is silent:

  - revoke ends by telling the operator to rotate the key. The ex-member stops
    receiving it on their next connection, but they hold the current one, and
    "revoked" reads like it took the key back.
  - revoke/unpin refuse a username the roster does not know instead of acting on
    nobody. A typo must not look like success.

Code lifetimes now differ by what the act is: 7 days for an invitation, which
crosses a human conversation and gets answered whenever someone reads their
messages, and 24 h for operator pairing, which is typed during the SSH session
that printed it. Both configurable ([node] invite_ttl_hours, pair_ttl_hours). A
day was long enough for the second and not for the first — a code that dies over
a weekend means finding a browser to issue another one.

The roster is also in the local admin UI, escaped: usernames come from the hub
and land on the page that can re-key groups and read the audit log, so H2's rule
covers them exactly as it covers filenames.

Verified by driving the real CLI against a stub daemon over a socket, which is
how the "known: <nothing>" bug in the not-found path turned up.

Tests: 89 node here (roster, endpoints, CLI routing, TTL config).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 packages/meshbay-node/src/meshbay_node/config.py   |  14 ++
 packages/meshbay-node/src/meshbay_node/daemon.py   |  98 ++++++++++-
 packages/meshbay-node/src/meshbay_node/roster.py   |  24 ++-
 .../src/meshbay_node/transport/webrtc_server.py    |   2 +
 packages/meshbay-node/src/meshbay_node/ui/app.py   | 162 +++++++++++++++++-
 packages/meshbay-node/tests/test_roster_pairing.py | 190 +++++++++++++++++++++
 .../tests/test_security_regressions.py             |  23 +++
 7 files changed, 499 insertions(+), 14 deletions(-)

(limited to 'packages/meshbay-node/tests/test_security_regressions.py')

diff --git a/packages/meshbay-node/src/meshbay_node/config.py b/packages/meshbay-node/src/meshbay_node/config.py
index 04cb1d3..f3752ea 100644
--- a/packages/meshbay-node/src/meshbay_node/config.py
+++ b/packages/meshbay-node/src/meshbay_node/config.py
@@ -29,6 +29,11 @@ username = "myusername"
 quic_port = 19010  # QUIC (MNP) — LAN, port-forwarded, hub-less direct access
 ui_port  = 18000   # local admin UI (127.0.0.1 only)
 
+# One-time codes. An invitation waits for someone to read their messages; an
+# operator pairing code is typed during the SSH session that printed it.
+invite_ttl_hours = 168   # 7 days
+pair_ttl_hours   = 24
+
 # Browser and native clients reach this node over WebRTC DataChannel via hub
 # signaling — no inbound port to open. QUIC is the optional direct path.
 
@@ -70,6 +75,11 @@ class HubConfig:
 class NodeConfig:
     quic_port:  int = 19010
     ui_port:    int = 18000
+    # How long a one-time code stays usable. Invitations travel through a human
+    # conversation and are answered days later; operator pairing happens during
+    # the SSH session that printed it.
+    invite_ttl_hours: int = 168   # 7 days
+    pair_ttl_hours:   int = 24
 
 
 @dataclass
@@ -129,6 +139,10 @@ def load_config(path: Path = DEFAULT_CONFIG_PATH) -> Config:
         # in Phase 11.5 (findings C1, C6). Regenerate node.toml with `meshbay-node init`.
         cfg.node.quic_port = nd.get("quic_port", cfg.node.quic_port)
         cfg.node.ui_port   = nd.get("ui_port",   cfg.node.ui_port)
+        cfg.node.invite_ttl_hours = int(
+            nd.get("invite_ttl_hours", cfg.node.invite_ttl_hours))
+        cfg.node.pair_ttl_hours = int(
+            nd.get("pair_ttl_hours", cfg.node.pair_ttl_hours))
 
         # Multi-group: [[groups]] array
         if "groups" in raw:
diff --git a/packages/meshbay-node/src/meshbay_node/daemon.py b/packages/meshbay-node/src/meshbay_node/daemon.py
index 7f84abe..930dabc 100644
--- a/packages/meshbay-node/src/meshbay_node/daemon.py
+++ b/packages/meshbay-node/src/meshbay_node/daemon.py
@@ -286,6 +286,8 @@ class NodeDaemon:
                 self._webrtc._ctx["pk_x25519_b64"] = keys.pk_x25519_b64
 
                 self._webrtc._ctx["roster"] = self._roster
+                self._webrtc._ctx["invite_ttl"] = (
+                    self._config.node.invite_ttl_hours * 3600)
                 admin_pk = self._legacy_admin_pk()
                 paired = await self._roster.has_operator() if self._roster else False
                 if admin_pk:
@@ -662,12 +664,15 @@ def main() -> None:
     parser = argparse.ArgumentParser(description="MeshBay Node daemon")
     parser.add_argument("command", nargs="?",
                         choices=["init", "status", "ui", "gek-init", "operator",
-                                 "calibrate-argon2"],
+                                 "member", "calibrate-argon2"],
                         help="init: write example config | status: node state and keys "
                              "| ui: print the admin UI URL | operator pair: pair a "
-                             "browser with this node | calibrate-argon2: benchmark")
+                             "browser with this node | member list|invite|revoke|unpin "
+                             "| calibrate-argon2: benchmark")
     parser.add_argument("subcommand", nargs="?",
-                        help="'pair' for the operator command")
+                        help="'pair' for operator; list|invite|revoke|unpin for member")
+    parser.add_argument("target", nargs="?",
+                        help="username, for member invite|revoke|unpin")
     parser.add_argument("--config", type=Path, default=None,
                         help="Config file path")
     parser.add_argument("--group", default=None,
@@ -677,7 +682,7 @@ def main() -> None:
     args = parser.parse_args()
 
     # Query commands print a report; library logging would interleave with it.
-    quiet = args.command in ("status", "ui", "gek-init", "operator")
+    quiet = args.command in ("status", "ui", "gek-init", "operator", "member")
     logging.basicConfig(
         level=logging.ERROR if quiet else getattr(logging, args.log_level),
         format="%(asctime)s %(levelname)-8s %(name)s: %(message)s",
@@ -775,6 +780,91 @@ def main() -> None:
             print(f"invites      {pending} pending code(s)")
         return
 
+    if args.command == "member":
+        cfg = load_config(args.config or DEFAULT_CONFIG_PATH)
+        sub = args.subcommand or "list"
+
+        if sub == "list":
+            group = args.group or ""
+            out = _daemon_api(
+                cfg, f"/api/roster?group_id={group}" if group else "/api/roster")
+            identities = {i["user_id"]: i for i in out.get("identities", [])}
+
+            members = out.get("members", [])
+            if not members:
+                print("no members admitted yet")
+                print("invite someone:  meshbay-node member invite <username>")
+            for m in members:
+                ident = identities.get(m["user_id"], {})
+                scope = m["group_id"][:8] if m["group_id"] else "node-wide"
+                print(f"{(ident.get('username') or m['user_id'])[:20]:20} "
+                      f"{m['role']:9} {m['status']:8} {scope:10} "
+                      f"pinned {ident.get('pinned_at', '?')} "
+                      f"({ident.get('pinned_via', '?')})")
+
+            invites = out.get("invites", [])
+            if invites:
+                print()
+                for i in invites:
+                    print(f"pending invite  user {i['user_id'][:12]}  "
+                          f"group {(i['group_id'] or 'node-wide')[:8]}  "
+                          f"expires {i['expires_at']}")
+            return
+
+        if not args.target:
+            print(f"usage: meshbay-node member {sub} <username>")
+            sys.exit(1)
+
+        if sub == "invite":
+            group_id = _resolve_group(cfg, args.group)
+            out = _daemon_api(
+                cfg, f"/api/groups/{group_id}/invites?username={args.target}",
+                method="POST")
+            from meshbay_node.roster import write_code_file
+            path = write_code_file(cfg.data_dir, out["code"],
+                                   out.get("expires_at", ""), name="invite-code")
+            print(f"INVITATION CODE  {out['code']}")
+            print(f"valid until      {out.get('expires_at', '?')}")
+            print()
+            print(f"Send it to {args.target} however you normally talk. It works")
+            print("once, for that account only, and never passes through the hub.")
+            print("They enter it the first time they open the group — you do not")
+            print("need to be online then.")
+            print()
+            print(f"also written to {path}")
+            return
+
+        # revoke and unpin both name a person; the daemon resolves the account.
+        roster_out = _daemon_api(cfg, "/api/roster")
+        match = next((i for i in roster_out.get("identities", [])
+                      if i["username"] == args.target), None)
+        if not match:
+            known = ", ".join(i["username"]
+                              for i in roster_out.get("identities", []))
+            print(f"{args.target!r} is not pinned on this node")
+            print(f"known:  {known or 'nobody yet'}")
+            sys.exit(1)
+
+        if sub == "revoke":
+            group_id = _resolve_group(cfg, args.group)
+            out = _daemon_api(
+                cfg, f"/api/members/{match['user_id']}/revoke?group_id={group_id}",
+                method="POST")
+            print(f"{args.target} revoked from {group_id[:8]}")
+            print("They stop receiving the group key on their next connection.")
+            print("They still hold the current one — rotate it:")
+            print(f"  meshbay-node gek-init --group {group_id}")
+            return
+
+        if sub == "unpin":
+            _daemon_api(cfg, f"/api/members/{match['user_id']}/unpin", method="POST")
+            print(f"{args.target} unpinned — they can pair again with a new key")
+            print(f"issue a code:  meshbay-node member invite {args.target}")
+            return
+
+        print("usage: meshbay-node member list|invite|revoke|unpin")
+        sys.exit(1)
+
     if args.command == "gek-init":
         cfg = load_config(args.config or DEFAULT_CONFIG_PATH)
         group_id = _resolve_group(cfg, args.group)
diff --git a/packages/meshbay-node/src/meshbay_node/roster.py b/packages/meshbay-node/src/meshbay_node/roster.py
index f231792..dab1497 100644
--- a/packages/meshbay-node/src/meshbay_node/roster.py
+++ b/packages/meshbay-node/src/meshbay_node/roster.py
@@ -36,7 +36,22 @@ log = logging.getLogger(__name__)
 # when reading a code aloud or typing it from a phone screen.
 _ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"
 CODE_LEN = 8                      # 8 × 5 bits = 40 bits of entropy
-DEFAULT_INVITE_TTL = 24 * 3600    # seconds
+
+# Two different rhythms, so two different lifetimes.
+#
+# An invitation crosses a human conversation: it is sent by mail or message and
+# answered whenever the other person next looks. A day is not enough — the code
+# dies over a weekend and someone has to be at a browser, with the node online, to
+# issue another one.
+#
+# Operator pairing crosses an SSH session: the code is printed and typed minutes
+# later. There is no reason for it to outlive the sitting.
+#
+# The longer window costs little: a code is single use, bound to one account,
+# never seen by the hub, and 40 bits do not fall to guessing in a week against the
+# node-wide lockout.
+DEFAULT_INVITE_TTL = 7 * 24 * 3600   # seconds — member invitations
+DEFAULT_PAIR_TTL = 24 * 3600         # seconds — operator pairing
 
 _SCHEMA = """\
 CREATE TABLE IF NOT EXISTS identities (
@@ -358,14 +373,17 @@ async def open_roster(data_dir: Path) -> Roster:
     return roster
 
 
-def write_code_file(data_dir: Path, code: str, expires_at: str) -> Path:
+def write_code_file(data_dir: Path, code: str, expires_at: str,
+                    name: str = "pair-code") -> Path:
     """
     Leave the code in a file as well as on stdout.
 
     An operator working over SSH may not be able to copy out of their terminal,
     and a code that can only be read off a scrolled-away screen is a dead end.
+    Pairing and invitation codes go to different files so one does not overwrite
+    the other.
     """
-    path = data_dir / "pair-code"
+    path = data_dir / name
     path.parent.mkdir(parents=True, exist_ok=True)
     path.write_text(f"{code}\nexpires {expires_at}\n")
     os.chmod(path, 0o600)
diff --git a/packages/meshbay-node/src/meshbay_node/transport/webrtc_server.py b/packages/meshbay-node/src/meshbay_node/transport/webrtc_server.py
index fe3ee2e..10dfcb0 100644
--- a/packages/meshbay-node/src/meshbay_node/transport/webrtc_server.py
+++ b/packages/meshbay-node/src/meshbay_node/transport/webrtc_server.py
@@ -70,6 +70,7 @@ from meshbay_common.join import (
 from meshbay_common.webcrypto import chunk_key_aes, encrypt_chunk_aes
 from meshbay_common.protocol import MNP
 from meshbay_node.indexer import GroupIndex
+from meshbay_node.roster import DEFAULT_INVITE_TTL
 
 log = logging.getLogger(__name__)
 
@@ -1330,6 +1331,7 @@ class WebRTCPeerSession:
             user_id=payload["user_id"],
             role=ROLE_MEMBER,
             created_by=self._user_id or "",
+            ttl=self._ctx.get("invite_ttl", DEFAULT_INVITE_TTL),
         )
         invites = await roster.list_invites()
         expires = next(
diff --git a/packages/meshbay-node/src/meshbay_node/ui/app.py b/packages/meshbay-node/src/meshbay_node/ui/app.py
index e671b72..2f73868 100644
--- a/packages/meshbay-node/src/meshbay_node/ui/app.py
+++ b/packages/meshbay-node/src/meshbay_node/ui/app.py
@@ -24,7 +24,7 @@ from fastapi.responses import HTMLResponse, JSONResponse
 
 from meshbay_node import __version__
 from meshbay_common.crypto import generate_gek, wrap_gek_aes
-from meshbay_common.join import ROLE_OPERATOR
+from meshbay_common.join import ROLE_MEMBER, ROLE_OPERATOR
 
 log = logging.getLogger(__name__)
 
@@ -235,11 +235,14 @@ def create_ui_app(state: dict) -> FastAPI:
         if not roster or not user_id:
             return JSONResponse({"error": "Node not connected to hub yet"}, 503)
 
+        config = state.get("config")
+        ttl = (config.node.pair_ttl_hours if config else 24) * 3600
         code = await roster.create_invite(
             group_id="",                 # operator authority is node-wide
             user_id=user_id,
             role=ROLE_OPERATOR,
             created_by="local-cli",
+            ttl=ttl,
         )
         invites = await roster.list_invites()
         expires = next((i["expires_at"] for i in invites
@@ -247,16 +250,85 @@ def create_ui_app(state: dict) -> FastAPI:
         return {"code": code, "expires_at": expires, "user_id": user_id}
 
     @app.get("/api/roster")
-    async def api_roster():
+    async def api_roster(group_id: str = ""):
         roster = state.get("roster")
         if not roster:
-            return {"identities": [], "members": [], "pending_invites": 0}
+            return {"identities": [], "members": [], "invites": []}
         return {
             "identities": await roster.list_identities(),
-            "members": await roster.list_members(),
-            "pending_invites": len(await roster.list_invites()),
+            "members": await roster.list_members(group_id or None),
+            "invites": await roster.list_invites(),
         }
 
+    @app.post("/api/groups/{group_id}/invites")
+    async def create_invite(group_id: str, username: str):
+        """
+        Issue an invitation code from the CLI, without a browser.
+
+        The hub is asked for the account id and nothing else — never for a key.
+        A hub that answered with the wrong account would produce an invite whose
+        code it never learns, since the code goes to a human out of band.
+        """
+        roster = state.get("roster")
+        groups_ctx = state.get("groups_ctx", {})
+        if not roster:
+            return JSONResponse({"error": "Roster not available"}, 503)
+        if group_id not in groups_ctx:
+            return JSONResponse({"error": "Group not hosted on this node"}, 404)
+
+        hub = state.get("hub")
+        if not hub or not hub._session:
+            return JSONResponse({"error": "Hub not connected"}, 503)
+        try:
+            account = await hub.get_user_pubkeys(username)
+        except Exception as e:
+            return JSONResponse({"error": f"Unknown user {username!r}: {e}"}, 404)
+
+        config = state.get("config")
+        ttl = (config.node.invite_ttl_hours if config else 168) * 3600
+        code = await roster.create_invite(
+            group_id=group_id,
+            user_id=account["user_id"],
+            role=ROLE_MEMBER,
+            created_by="local-cli",
+            ttl=ttl,
+        )
+        invites = await roster.list_invites()
+        expires = next((i["expires_at"] for i in invites
+                        if i["user_id"] == account["user_id"]
+                        and i["group_id"] == group_id), "")
+        return {"code": code, "expires_at": expires,
+                "username": username, "user_id": account["user_id"]}
+
+    @app.post("/api/members/{user_id}/revoke")
+    async def revoke_member(user_id: str, group_id: str):
+        """
+        Stop serving the group key to someone.
+
+        Takes effect on their next connection: the key is wrapped on demand, so
+        there is no stored bundle left behind that would outlive this. Rotating
+        the group key is still required — they hold the current one.
+        """
+        roster = state.get("roster")
+        if not roster:
+            return JSONResponse({"error": "Roster not available"}, 503)
+        if not await roster.set_status(group_id, user_id, "revoked"):
+            return JSONResponse({"error": "No such member in that group"}, 404)
+        log.info("Member revoked: user=%s group=%s", user_id[:8], group_id[:8])
+        return {"status": "revoked", "user_id": user_id, "group_id": group_id,
+                "reminder": "rotate the group key: meshbay-node gek-init"}
+
+    @app.post("/api/members/{user_id}/unpin")
+    async def unpin_member(user_id: str):
+        """Forget a pinned identity, so the person can pair again with a new key."""
+        roster = state.get("roster")
+        if not roster:
+            return JSONResponse({"error": "Roster not available"}, 503)
+        if not await roster.unpin(user_id):
+            return JSONResponse({"error": "No such pinned identity"}, 404)
+        log.info("Identity unpinned: user=%s", user_id[:8])
+        return {"status": "unpinned", "user_id": user_id}
+
     # ── GEK initialization (operator only, localhost) ──────────────────────
 
     @app.post("/api/groups/{group_id}/gek")
@@ -376,7 +448,17 @@ def create_ui_app(state: dict) -> FastAPI:
 
     @app.get("/", response_class=HTMLResponse)
     async def root():
-        return _render_page(state)
+        # Roster reads are async and the page renderer is not, so gather here.
+        roster = state.get("roster")
+        roster_view = None
+        if roster:
+            identities = {i["user_id"]: i for i in await roster.list_identities()}
+            roster_view = {
+                "identities": identities,
+                "members": await roster.list_members(),
+                "invites": await roster.list_invites(),
+            }
+        return _render_page(state, roster_view)
 
     @app.get("/audit", response_class=HTMLResponse)
     async def audit_page():
@@ -395,7 +477,70 @@ def _fmt_size(n: int) -> str:
     return f"{n / (1024 * 1024 * 1024):.2f} GB"
 
 
-def _render_page(state: dict) -> str:
+def _render_roster(roster_view: dict | None) -> str:
+    """
+    Who this node recognises, and which keys are theirs.
+
+    Every value here is escaped: usernames come from the hub and pass through the
+    roster, so they are attacker-influenced text on the operator's own admin page
+    (the H2 rule applies to them exactly as it does to filenames).
+    """
+    if roster_view is None:
+        return '<p class="muted">Roster unavailable</p>'
+
+    identities = roster_view["identities"]
+    rows = ""
+    for m in roster_view["members"]:
+        ident = identities.get(m["user_id"], {})
+        scope = escape(m["group_id"][:8]) if m["group_id"] else "node-wide"
+        status_color = "#22c55e" if m["status"] == "active" else "#ef4444"
+        rows += (
+            f"<tr><td>{escape(str(ident.get('username') or m['user_id']))}</td>"
+            f"<td>{escape(str(m['role']))}</td>"
+            f"<td><span class='badge' style='background:{status_color}'>"
+            f"{escape(str(m['status']))}</span></td>"
+            f"<td>{scope}</td>"
+            f"<td><code>{escape(str(ident.get('pk_ed25519', ''))[:16])}…</code></td>"
+            f"<td>{escape(str(ident.get('pinned_at', '?')))} "
+            f"({escape(str(ident.get('pinned_via', '?')))})</td></tr>"
+        )
+    if not rows:
+        rows = ('<tr><td colspan="6" class="muted">Nobody admitted yet — '
+                'run <code>meshbay-node member invite &lt;username&gt;</code></td></tr>')
+
+    invite_rows = ""
+    for i in roster_view["invites"]:
+        invite_rows += (
+            f"<tr><td><code>{escape(str(i['user_id'])[:16])}</code></td>"
+            f"<td>{escape(str(i['group_id'][:8] or 'node-wide'))}</td>"
+            f"<td>{escape(str(i['role']))}</td>"
+            f"<td>{escape(str(i['expires_at']))}</td></tr>"
+        )
+    invites_html = ""
+    if invite_rows:
+        invites_html = f"""
+        <details style="margin-top:10px"><summary>Pending invitations</summary>
+        <table>
+          <thead><tr><th>Account</th><th>Group</th><th>Role</th><th>Expires</th></tr></thead>
+          <tbody>{invite_rows}</tbody>
+        </table>
+        </details>"""
+
+    return f"""
+    <table>
+      <thead><tr><th>User</th><th>Role</th><th>Status</th><th>Scope</th>
+                 <th>Identity key</th><th>Pinned</th></tr></thead>
+      <tbody>{rows}</tbody>
+    </table>
+    {invites_html}
+    <p class="muted" style="margin-top:8px">
+      Codes are issued from the CLI: <code>meshbay-node operator pair</code>,
+      <code>meshbay-node member invite &lt;username&gt;</code>. They never pass
+      through the hub.
+    </p>"""
+
+
+def _render_page(state: dict, roster_view: dict | None = None) -> str:
     token_js = json.dumps(state.get("ui_token", ""))
     status = state.get("status", "starting")
     indexes = state.get("indexes", {})
@@ -557,6 +702,9 @@ def _render_page(state: dict) -> str:
     <tbody>{peers_html}</tbody>
   </table>
 
+  <h2>Roster</h2>
+  {_render_roster(roster_view)}
+
   <h2>Groups</h2>
   {groups_html or '<p class="muted">No groups configured</p>'}
 
diff --git a/packages/meshbay-node/tests/test_roster_pairing.py b/packages/meshbay-node/tests/test_roster_pairing.py
index e0492ae..11704ce 100644
--- a/packages/meshbay-node/tests/test_roster_pairing.py
+++ b/packages/meshbay-node/tests/test_roster_pairing.py
@@ -445,6 +445,52 @@ async def test_revoked_member_stops_receiving_the_key(tmp_path, roster):
     assert _last(session).get("gek") is False
 
 
+# ── Code lifetimes ────────────────────────────────────────────────────────────
+
+async def test_invitations_outlive_pairing_codes(roster):
+    """
+    An invitation crosses a human conversation; a pairing code crosses an SSH
+    session. A day was long enough for the second and not for the first — a code
+    that dies over a weekend means someone has to be at a browser to reissue it.
+    """
+    from meshbay_node.roster import DEFAULT_INVITE_TTL, DEFAULT_PAIR_TTL
+
+    assert DEFAULT_INVITE_TTL == 7 * 24 * 3600
+    assert DEFAULT_PAIR_TTL == 24 * 3600
+    assert DEFAULT_INVITE_TTL > DEFAULT_PAIR_TTL
+
+
+def test_code_lifetimes_are_configurable(tmp_path):
+    """The operator decides, not the default."""
+    from meshbay_node.config import load_config
+
+    path = tmp_path / "node.toml"
+    path.write_text(
+        '[hub]\nurl = "https://example.org"\nusername = "grenet"\n'
+        "[node]\ninvite_ttl_hours = 72\npair_ttl_hours = 2\n"
+    )
+    cfg = load_config(path)
+    assert cfg.node.invite_ttl_hours == 72
+    assert cfg.node.pair_ttl_hours == 2
+
+    default = load_config(tmp_path / "missing.toml")
+    assert default.node.invite_ttl_hours == 168
+    assert default.node.pair_ttl_hours == 24
+
+
+async def test_expiry_is_enforced_at_redemption(tmp_path, roster):
+    """Purging is housekeeping; the check that matters happens on use."""
+    session = _session(tmp_path, roster)
+    sk_ed, pk_ed_b64, pk_x_b64 = _keypair()
+    code = await roster.create_invite("", "grenet", ROLE_OPERATOR, "local-cli", ttl=-1)
+
+    await session._do_join_request(
+        _join_msg(session, sk_ed, pk_ed_b64, pk_x_b64, code=code))
+
+    assert _last(session).get("reason") == "code_invalid"
+    assert await roster.get_identity("grenet") is None
+
+
 # ── M3: where node authority comes from ───────────────────────────────────────
 
 async def test_admin_signature_verified_against_the_paired_key(tmp_path, roster):
@@ -475,6 +521,150 @@ async def test_unpinned_operator_loses_authority_immediately(tmp_path, roster):
     assert not await session._verify_admin_sig(transcript, sk_ed.sign(transcript))
 
 
+# ── Operator surface (slice 3) ────────────────────────────────────────────────
+
+def _ui_client(tmp_path, roster, **extra):
+    from fastapi.testclient import TestClient
+
+    from meshbay_node.config import Config
+    from meshbay_node.ui.app import create_ui_app
+
+    state = {
+        "status": "running", "groups_ctx": {GROUP: {"gek": b"k" * 32}},
+        "indexes": {}, "ui_token": "tok", "roster": roster,
+        "node_user_id": "grenet", "config": Config(),
+    }
+    state.update(extra)
+    return TestClient(create_ui_app(state)), state
+
+
+async def test_revoke_endpoint_stops_authorization(tmp_path, roster):
+    client, _ = _ui_client(tmp_path, roster)
+    _, pk_ed_b64, pk_x_b64 = _keypair()
+    await roster.pin_identity("bob", "bob", pk_ed_b64, pk_x_b64, "code")
+    await roster.set_member(GROUP, "bob", ROLE_MEMBER, "active", "grenet")
+    assert await roster.is_authorized(GROUP, "bob")
+
+    resp = client.post(f"/api/members/bob/revoke?group_id={GROUP}&t=tok")
+    assert resp.status_code == 200
+    assert "gek-init" in resp.json()["reminder"], (
+        "revocation must remind the operator to rotate the key they still hold")
+    assert not await roster.is_authorized(GROUP, "bob")
+
+
+async def test_unpin_endpoint_allows_repairing(tmp_path, roster):
+    client, _ = _ui_client(tmp_path, roster)
+    _, pk_ed_b64, pk_x_b64 = _keypair()
+    await roster.pin_identity("bob", "bob", pk_ed_b64, pk_x_b64, "code")
+
+    assert client.post("/api/members/bob/unpin?t=tok").status_code == 200
+    assert await roster.get_identity("bob") is None
+    assert client.post("/api/members/bob/unpin?t=tok").status_code == 404
+
+
+async def test_operator_surface_needs_the_session_token(tmp_path, roster):
+    """11.5.3 applies to every one of these: they change who may hold the key."""
+    client, _ = _ui_client(tmp_path, roster)
+    for path in ("/api/roster",
+                 "/api/operator/pair",
+                 f"/api/members/bob/revoke?group_id={GROUP}",
+                 "/api/members/bob/unpin",
+                 f"/api/groups/{GROUP}/invites?username=bob"):
+        method = client.get if path == "/api/roster" else client.post
+        assert method(path).status_code == 403, f"{path} reachable without a token"
+
+
+async def test_cli_invite_asks_the_hub_for_an_account_never_a_key(tmp_path, roster):
+    """
+    The CLI resolves a username to an account id through the hub, and stops there.
+    A key fetched from the hub is what H3 was; an account id is not a secret and
+    a wrong one produces an invite whose code the hub never learns.
+    """
+    class _Hub:
+        _session = object()
+
+        async def get_user_pubkeys(self, username):
+            return {"user_id": f"id-of-{username}",
+                    "pk_x25519": "SHOULD-NOT-BE-USED",
+                    "pk_ed25519": "SHOULD-NOT-BE-USED"}
+
+    client, _ = _ui_client(tmp_path, roster, hub=_Hub())
+    resp = client.post(f"/api/groups/{GROUP}/invites?username=bob&t=tok")
+    assert resp.status_code == 200
+    body = resp.json()
+    assert body["user_id"] == "id-of-bob"
+
+    invites = await roster.list_invites()
+    assert [i["user_id"] for i in invites] == ["id-of-bob"]
+    # Whatever the hub said about keys was never stored anywhere.
+    assert "SHOULD-NOT-BE-USED" not in str(invites)
+    assert await roster.get_identity("id-of-bob") is None
+
+
+def _run_cli(monkeypatch, tmp_path, argv, responses):
+    """Drive the real CLI with the daemon API stubbed, capturing the calls."""
+    import sys as _sys
+
+    from meshbay_node import daemon as _daemon
+
+    calls = []
+
+    def fake_api(cfg, path, method="GET", timeout=30):
+        calls.append((method, path))
+        for key, value in responses.items():
+            if key in path:
+                return value
+        return {}
+
+    monkeypatch.setattr(_daemon, "_daemon_api", fake_api)
+
+    conf = tmp_path / "node.toml"
+    conf.write_text(
+        f'data_dir = "{tmp_path}"\n'
+        '[hub]\nurl = "https://example.org"\nusername = "grenet"\n'
+        f'[[groups]]\nid = "{GROUP}"\nname = "demo"\n'
+        f'shared_dir = "{tmp_path}"\n'
+    )
+    monkeypatch.setattr(_sys, "argv",
+                        ["meshbay-node", *argv, "--config", str(conf)])
+    try:
+        _daemon.main()
+    except SystemExit as e:
+        calls.append(("exit", e.code))
+    return calls
+
+
+def test_cli_member_commands_reach_the_right_endpoints(monkeypatch, tmp_path, capsys):
+    roster_reply = {"identities": [{"user_id": "u-bob", "username": "bob",
+                                    "pk_ed25519": "K", "pinned_at": "now",
+                                    "pinned_via": "code"}],
+                    "members": [{"group_id": GROUP, "user_id": "u-bob",
+                                 "role": "member", "status": "active"}],
+                    "invites": []}
+
+    calls = _run_cli(monkeypatch, tmp_path, ["member", "revoke", "bob"],
+                     {"/api/roster": roster_reply,
+                      "revoke": {"status": "revoked", "reminder": "gek-init"}})
+    assert ("POST", f"/api/members/u-bob/revoke?group_id={GROUP}") in calls
+    # The operator is told the revocation does not take back the key they hold.
+    assert "rotate" in capsys.readouterr().out.lower()
+
+    calls = _run_cli(monkeypatch, tmp_path, ["member", "unpin", "bob"],
+                     {"/api/roster": roster_reply, "unpin": {"status": "unpinned"}})
+    assert ("POST", "/api/members/u-bob/unpin") in calls
+
+
+def test_cli_refuses_to_act_on_someone_it_does_not_know(monkeypatch, tmp_path, capsys):
+    """A typo must not silently do nothing — or worse, act on the wrong person."""
+    calls = _run_cli(monkeypatch, tmp_path, ["member", "revoke", "nobody"],
+                     {"/api/roster": {"identities": [], "members": [],
+                                      "invites": []}})
+    assert ("exit", 1) in calls
+    assert not any(method == "POST" for method, _ in calls), (
+        "the CLI acted on the server despite not knowing who was meant")
+    assert "not pinned" in capsys.readouterr().out
+
+
 def test_daemon_does_not_auto_pin_keystore_key():
     """
     M3: the daemon used to auto-pin its own keystore key as the admin key, while
diff --git a/packages/meshbay-node/tests/test_security_regressions.py b/packages/meshbay-node/tests/test_security_regressions.py
index 6bb680c..dcd9cf6 100644
--- a/packages/meshbay-node/tests/test_security_regressions.py
+++ b/packages/meshbay-node/tests/test_security_regressions.py
@@ -579,3 +579,26 @@ def test_admin_ui_escapes_filenames(tmp_path):
     assert payload not in html, "filename rendered unescaped — stored XSS (H2)"
     assert "&lt;img" in html, "filename should appear escaped"
 
+
+def test_admin_ui_escapes_roster_usernames(tmp_path):
+    """
+    H2 again, for the roster: usernames originate at the hub and land on the
+    operator's own admin page, which can re-key groups and read the audit log.
+    """
+    from meshbay_node.ui.app import _render_page
+
+    payload = '<img src=x onerror="fetch(1)">'
+    html = _render_page(
+        {"status": "running", "groups_ctx": {}, "indexes": {}},
+        {
+            "identities": {"u1": {"user_id": "u1", "username": payload,
+                                  "pk_ed25519": "AAA", "pinned_at": "now",
+                                  "pinned_via": "code"}},
+            "members": [{"group_id": "", "user_id": "u1", "role": "operator",
+                         "status": "active"}],
+            "invites": [],
+        },
+    )
+
+    assert payload not in html, "username rendered unescaped — stored XSS (H2)"
+    assert "&lt;img" in html
-- 
cgit v1.2.3