feat(membership): room discovery — GET /members/{endpoint}/rooms + ListMyRooms

A peer invited to an encrypted room needs to find it: the control plane is
pull-based (no server push of invitations), so add a discovery endpoint that
lists every room an endpoint belongs to, with the room's metadata and the
endpoint's role.

- store.ListRoomsForEndpoint: JOIN members+rooms, ordered by room id, empty
  slice (not error) for an endpoint in no rooms.
- membershipd: GET /members/{endpoint}/rooms returns {room_id, subject, epoch,
  policy, role}[].
- client.ListMyRooms + RoomRef: a bot polls this to discover and then Join +
  Subscribe rooms it was invited to.

Tests: store-level (owner in N rooms, member in one, unknown endpoint → []) and
client-level e2e through the embedded harness (B discovers a room A invited it
to, without prior knowledge of the room id; owner sees role=owner).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

pkg/client/client.go

@@ -231,8 +231,48 @@ type blobResp struct {
 	Hash string `json:"hash"`
 }
 
+type memberRoomJSON struct {
+	RoomID  string     `json:"room_id"`
+	Subject string     `json:"subject"`
+	Epoch   int        `json:"epoch"`
+	Policy  policyJSON `json:"policy"`
+	Role    string     `json:"role"`
+}
+
 // ---- room operations ------------------------------------------------------
 
+// RoomRef is a room this peer belongs to, returned by ListMyRooms. It is the
+// unit of room discovery: a peer that was invited to a new room finds it here
+// and can then Join (fetch the sealed key) and Subscribe.
+type RoomRef struct {
+	RoomID  string
+	Subject string
+	Epoch   int
+	Policy  room.Policy
+	Role    string
+}
+
+// ListMyRooms returns every room this peer is currently a member of. A peer
+// polls this to discover rooms it has been invited to (the control plane is
+// pull-based: there is no server push of invitations).
+func (c *Client) ListMyRooms() ([]RoomRef, error) {
+	var resp []memberRoomJSON
+	if err := c.doJSON("GET", "/members/"+c.endpoint+"/rooms", nil, &resp); err != nil {
+		return nil, err
+	}
+	out := make([]RoomRef, 0, len(resp))
+	for _, r := range resp {
+		out = append(out, RoomRef{
+			RoomID:  r.RoomID,
+			Subject: r.Subject,
+			Epoch:   r.Epoch,
+			Policy:  room.Policy{Encrypt: r.Policy.Encrypt, Persist: r.Policy.Persist, SignMsgs: r.Policy.SignMsgs},
+			Role:    r.Role,
+		})
+	}
+	return out, nil
+}
+
 // newRoomKey returns 32 random bytes for a symmetric room key.
 func newRoomKey() ([]byte, error) {
 	k := make([]byte, 32)

pkg/client/client_test.go

@@ -402,6 +402,59 @@ func TestThreadedReplyAndReaction(t *testing.T) {
 	}
 }
 
+// TestListMyRoomsDiscovery verifies room discovery: an invited peer finds the
+// room via ListMyRooms (without being told its id), and a peer in no rooms gets
+// an empty list. This is what lets a bot discover rooms it was invited to.
+func TestListMyRoomsDiscovery(t *testing.T) {
+	h := newHarness(t)
+	waitHealth(t, h.ctrlURL)
+
+	a, err := client.New(h.natsURL, h.ctrlURL, mustIdentity(t))
+	if err != nil {
+		t.Fatalf("connect A: %v", err)
+	}
+	defer a.Close()
+	b, err := client.New(h.natsURL, h.ctrlURL, mustIdentity(t))
+	if err != nil {
+		t.Fatalf("connect B: %v", err)
+	}
+	defer b.Close()
+
+	// B is in no rooms yet.
+	if rooms, err := b.ListMyRooms(); err != nil || len(rooms) != 0 {
+		t.Fatalf("B should start in no rooms, got %v err=%v", rooms, err)
+	}
+
+	roomID, err := a.CreateRoom("room.discovery", room.ModeMatrix)
+	if err != nil {
+		t.Fatalf("A create room: %v", err)
+	}
+	if err := a.Invite(roomID, b.Endpoint()); err != nil {
+		t.Fatalf("A invite B: %v", err)
+	}
+
+	// B discovers the room it was invited to, with its policy, without prior knowledge of the id.
+	rooms, err := b.ListMyRooms()
+	if err != nil {
+		t.Fatalf("B ListMyRooms: %v", err)
+	}
+	if len(rooms) != 1 || rooms[0].RoomID != roomID {
+		t.Fatalf("B should discover exactly room %s, got %+v", roomID, rooms)
+	}
+	if rooms[0].Subject != "room.discovery" || !rooms[0].Policy.Encrypt || rooms[0].Role != "member" {
+		t.Fatalf("discovered room metadata wrong: %+v", rooms[0])
+	}
+
+	// A sees the same room as its owner.
+	aRooms, err := a.ListMyRooms()
+	if err != nil {
+		t.Fatalf("A ListMyRooms: %v", err)
+	}
+	if len(aRooms) != 1 || aRooms[0].Role != "owner" {
+		t.Fatalf("A should own exactly one room, got %+v", aRooms)
+	}
+}
+
 // ---- test helpers ---------------------------------------------------------
 
 type collector struct {