fix(hub): present a node-audience token in the handshake, not the hub session token

A member authenticated to a node in the MNP handshake with its hub *session*
token — scope=user, valid at the hub API for hours. A node operator is in the
threat model, so this handed them a live hub credential for the member: enough
to enumerate the member's other groups, act as them, and (before the previous
commit closed it) take the account over. The node genuinely needs a hub-signed
membership assertion, so the fix is to make that a separate credential that
opens nothing at the hub API.

Two audiences signed by the one hub key (meshbay_common/tokens.py):
- HUB_API_AUD — session tokens (login, device-auth, node-auth, refresh), used
  for hub calls and signaling. decode_access_token now binds this audience, so
  an MNP token cannot be replayed against the hub API.
- MNP_AUD — a short-lived token a member presents to a node and nothing else,
  from POST /v1/nodes/mnp-token. authorize_token now binds this audience, so a
  session token presented to a node is refused. This closes the disclosure.

The node's own self-decode (hub_client.py) reads its node token with
audience=HUB_API_AUD. The client fetches the MNP token inside transport.connect()
(and on every reconnect) using the session token, so callers are unchanged and
signaling keeps using the session token.

No regression to a long session: the MNP token is checked once, at the
handshake, before any proof — a film already playing is not re-authenticated, so
a 15-minute token does not interrupt a 4-hour film; reconnects refetch a fresh
one. Denylist and membership checks are unchanged (the MNP token carries
sub/jti/groups).

Tests: authorize_token refuses a session/no-audience token and accepts an MNP
token; the hub API refuses an MNP token; POST /v1/nodes/mnp-token is minted only
for a member's own session. Verified red-before/green-after; common, node and
hub suites green (the pre-existing test_cli_golden failure is an argparse/pytest
prog artifact unrelated to this change).

Still to do before deploy (B2): bump the MNP version and client.minimum so a
stale desktop client is told to update rather than getting a handshake refusal,
update docs/MESHBAY_DESIGN.md and MESHBAY_NODE_PROTOCOL.md, and validate against
a real node locally, then deploy hub+node+SPA atomically.

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

3 files changed, 65 insertions, 3 deletions

diff --git a/packages/meshbay-common/src/meshbay_common/handshake.py b/packages/meshbay-common/src/meshbay_common/handshake.py
index 73e0b2e..2393df1 100644
--- a/packages/meshbay-common/src/meshbay_common/handshake.py
+++ b/packages/meshbay-common/src/meshbay_common/handshake.py
@@ -63,6 +63,7 @@ from typing import Any, Protocol
 import jwt
 
 from meshbay_common import MNP_VERSION
+from meshbay_common.tokens import MNP_AUD
 
 HANDSHAKE_PREFIX = b"meshbay:mnp:handshake:v1"
 CHALLENGE_PREFIX = b"meshbay:mnp:challenge:v1"
@@ -274,8 +275,15 @@ def authorize_token(
     """
     try:
         decoded = jwt.decode(token, hub_pk_pem, algorithms=["EdDSA"],
-                             leeway=JWT_LEEWAY_SECONDS)
+                             leeway=JWT_LEEWAY_SECONDS,
+                             audience=MNP_AUD,
+                             options={"require": ["exp", "sub", "scope"]})
     except Exception as exc:
+        # An audience mismatch lands here too: a hub *session* token
+        # (aud=HUB_API_AUD) presented to a node is refused. That is the point —
+        # the credential a member hands a node must not be one that also opens
+        # the hub API (see meshbay_common.tokens). A member presents the
+        # short-lived MNP token instead.
         raise HandshakeError(f"Invalid JWT: {exc}") from exc
 
     # A node-scoped daemon token must not be usable as a client token (M9).
diff --git a/packages/meshbay-common/src/meshbay_common/tokens.py b/packages/meshbay-common/src/meshbay_common/tokens.py
new file mode 100644
index 0000000..c393be5
--- /dev/null
+++ b/packages/meshbay-common/src/meshbay_common/tokens.py
@@ -0,0 +1,28 @@
+"""Token audiences — one hub key, two purposes, never interchangeable.
+
+The hub signs everything with one Ed25519 key, but a token has to say what it is
+*for*, or a credential minted for one purpose is honoured for another. Two
+audiences settle it:
+
+- ``HUB_API_AUD`` — a session token, presented to the **hub API** (``hubFetch``,
+  signaling). Carried by the browser and the desktop client, and by a node for
+  its own hub calls.
+- ``MNP_AUD`` — a short-lived token a member presents to a **node** in the MNP
+  handshake, and to nothing else. It authorises the member to that node
+  (``sub``, ``groups``, ``jti``) and is **useless at the hub API**.
+
+The reason this exists: a member hands whatever token it holds to every node it
+connects to (the handshake authenticates with it). If that were the session
+token, a node operator — who is in the threat model — would hold a live hub
+credential for the member and could act as them at the hub. Separating the
+audiences means the credential a node receives opens nothing at the hub, and the
+credential the hub API accepts is never disclosed to a node.
+
+The hub API decode (:func:`meshbay_hub.auth.decode_access_token`) binds
+``HUB_API_AUD``; the node handshake decode
+(:func:`meshbay_common.handshake.authorize_token`) binds ``MNP_AUD``. Each
+rejects the other's audience.
+"""
+
+HUB_API_AUD = "meshbay:hub-api"
+MNP_AUD = "meshbay:mnp"
diff --git a/packages/meshbay-common/tests/test_handshake.py b/packages/meshbay-common/tests/test_handshake.py
index ad615a9..8f385bb 100644
--- a/packages/meshbay-common/tests/test_handshake.py
+++ b/packages/meshbay-common/tests/test_handshake.py
@@ -28,6 +28,7 @@ from meshbay_common.handshake import (
     verify_proof,
     webrtc_binding,
 )
+from meshbay_common.tokens import HUB_API_AUD, MNP_AUD
 
 GEK = b"\x11" * 32
 GROUP = "g" * 32
@@ -59,8 +60,14 @@ def _token(sk_pem, **over):
         "iss": "test-hub", "sub": "user-1", "jti": "jti-1",
         "iat": now, "exp": now + 3600,
         "groups": [GROUP], "scope": "user", "pk_user": "pk",
+        # A member presents an MNP-audience token to a node. A hub session token
+        # (aud=HUB_API_AUD) is refused here — see test_a_hub_session_token_is_refused.
+        "aud": MNP_AUD,
     }
     payload.update(over)
+    # A None override omits the claim entirely (e.g. aud=None → no audience),
+    # rather than encoding a null value.
+    payload = {k: v for k, v in payload.items() if v is not None}
     return jwt.encode(payload, sk_pem, algorithm="EdDSA")
 
 
@@ -96,6 +103,23 @@ def test_node_scoped_token_refused_on_client_path(hub_key):
         authorize_token(token, pk_pem, group_id=GROUP)
 
 
+def test_a_hub_session_token_is_refused_by_a_node(hub_key):
+    """The core of the audience split: a member hands whatever token it presents
+    to the node operator, so it must not be the hub session token (aud=HUB_API_AUD),
+    which opens the hub API. Only the MNP-audience token is accepted here."""
+    sk_pem, pk_pem = hub_key
+    session_token = _token(sk_pem, aud=HUB_API_AUD)
+    with pytest.raises(HandshakeError):
+        authorize_token(session_token, pk_pem, group_id=GROUP)
+
+
+def test_a_token_with_no_audience_is_refused(hub_key):
+    sk_pem, pk_pem = hub_key
+    no_aud = _token(sk_pem, aud=None)
+    with pytest.raises(HandshakeError):
+        authorize_token(no_aud, 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"):
@@ -236,7 +260,8 @@ def test_membership_refusal_carries_a_code_a_client_can_act_on():
     pem_pub = sk.public_key().public_bytes(
         serialization.Encoding.PEM, serialization.PublicFormat.SubjectPublicKeyInfo)
 
-    token = _jwt.encode({"sub": "u1", "jti": "j1", "scope": "user", "groups": []},
+    token = _jwt.encode({"sub": "u1", "jti": "j1", "scope": "user", "groups": [],
+                         "exp": int(time.time()) + 3600, "aud": MNP_AUD},
                         pem_priv, algorithm="EdDSA")
 
     with pytest.raises(HandshakeError) as excinfo:
@@ -265,7 +290,8 @@ def test_a_group_this_node_does_not_host_is_refused_with_a_code():
 
     group = "g" * 32
     token = _jwt.encode(
-        {"sub": "u1", "jti": "j1", "scope": "user", "groups": [group]},
+        {"sub": "u1", "jti": "j1", "scope": "user", "groups": [group],
+         "exp": int(time.time()) + 3600, "aud": MNP_AUD},
         pem_priv, algorithm="EdDSA")
 
     # A member of the group, on a node that does not host it.