router/realm: expose target realm URI to authenticators

Adds the realm URI to the HELLO Details dict (under the
"nexus.session.realm" key) before invoking the realm's authenticator.
The HELLO carries the realm as a separate message field from Details,
so without this dynamic authenticators that share one instance across
multiple realms cannot tell which realm a client is requesting and
have no way to route their lookup per-realm.

Key is namespaced under "nexus." to avoid collision with future
WAMP-spec details fields, mirroring how nexus already namespaces
"transport.auth.*" entries.

Pinned by TestRealmExposesURIToAuthenticator (a stub Authenticator
that records the details it receives and asserts the key is present
with the right value).

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

Author: Marko Petzold

router/realm.go

@@ -37,6 +37,8 @@ type testamentBucket struct {
 // authentication and authorization. WAMP messages are only routed within a
 // Realm.
 type realm struct {
+	uri wamp.URI
+
 	broker *broker
 	dealer *dealer
 
@@ -99,6 +101,7 @@ func newRealm(config *RealmConfig, broker *broker, dealer *dealer, logger stdlog
 	}
 
 	r := &realm{
+		uri:         config.URI,
 		broker:      broker,
 		dealer:      dealer,
 		authorizer:  config.Authorizer,
@@ -740,6 +743,14 @@ func (r *realm) authClient(sid wamp.ID, client wamp.Peer, details wamp.Dict) (*w
 		return nil, errors.New("could not authenticate with any method")
 	}
 
+	// Expose the target realm URI to the authenticator. The HELLO carries
+	// the realm as a separate message field from Details, so without this
+	// dynamic authenticators that share one instance across multiple realms
+	// can't tell which realm the client is requesting. Key is namespaced
+	// under "nexus." to avoid collision with future WAMP-spec details
+	// fields (mirrors how nexus already namespaces "transport.auth.*").
+	details["nexus.session.realm"] = string(r.uri)
+
 	// Return welcome message or error.
 	welcome, err := authr.Authenticate(sid, details, client)
 	if err != nil {

router/realm_authenticator_test.go

@@ -0,0 +1,93 @@
+package router //nolint:testpackage
+
+import (
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+
+	"github.com/gammazero/nexus/v3/router/auth"
+	"github.com/gammazero/nexus/v3/transport"
+	"github.com/gammazero/nexus/v3/wamp"
+)
+
+// captureRealmAuthenticator is a stub authenticator that records the
+// details dict it receives, then returns a WELCOME. Used to verify that
+// the realm injects "nexus.session.realm" into the details before
+// calling Authenticate.
+type captureRealmAuthenticator struct {
+	gotDetails wamp.Dict
+}
+
+func (a *captureRealmAuthenticator) Authenticate(sid wamp.ID, details wamp.Dict, _ wamp.Peer) (*wamp.Welcome, error) {
+	// Copy the dict so the caller can't mutate our recorded view via the
+	// returned welcome.
+	a.gotDetails = wamp.Dict{}
+	for k, v := range details {
+		a.gotDetails[k] = v
+	}
+	return &wamp.Welcome{
+		ID:      sid,
+		Details: wamp.Dict{"authrole": "tester"},
+	}, nil
+}
+
+func (a *captureRealmAuthenticator) AuthMethod() string { return "capture-realm" }
+
+// TestRealmExposesURIToAuthenticator pins that realm.authClient injects
+// the target realm URI into the HELLO Details under the
+// "nexus.session.realm" key before invoking the authenticator. Dynamic
+// authenticators that share one instance across multiple realms (e.g.
+// a single auth-server delegate) rely on this to route per-realm.
+func TestRealmExposesURIToAuthenticator(t *testing.T) {
+	const realmURI = wamp.URI("nexus.test.realm.with.auth.capture")
+
+	captor := &captureRealmAuthenticator{}
+
+	r, err := NewRouter(&Config{
+		RealmConfigs: []*RealmConfig{
+			{
+				URI:              realmURI,
+				StrictURI:        false,
+				Authenticators:   []auth.Authenticator{captor},
+				RequireLocalAuth: true, // LinkedPeers are local — opt into auth
+			},
+		},
+	}, logger)
+	require.NoError(t, err)
+	// Router shutdown also disposes attached peers; do NOT call peer.Close
+	// manually here — main's localPeer panics on double-close.
+	t.Cleanup(func() { r.Close() })
+
+	client, server := transport.LinkedPeers()
+
+	go func() { _ = r.Attach(server) }()
+
+	hello := &wamp.Hello{
+		Realm: realmURI,
+		Details: wamp.Dict{
+			"authmethods": wamp.List{"capture-realm"},
+			"roles":       wamp.Dict{"caller": wamp.Dict{}},
+		},
+	}
+	client.Send() <- hello
+
+	select {
+	case msg := <-client.Recv():
+		_, ok := msg.(*wamp.Welcome)
+		require.True(t, ok, "expected WELCOME, got %T", msg)
+	case <-time.After(2 * time.Second):
+		t.Fatal("timeout waiting for WELCOME")
+	}
+
+	require.NotNil(t, captor.gotDetails, "Authenticate was never called")
+	got, ok := captor.gotDetails["nexus.session.realm"]
+	require.True(t, ok, "nexus.session.realm missing from authenticator details (got: %v)", captor.gotDetails)
+	require.Equal(t, string(realmURI), got,
+		"nexus.session.realm should equal the HELLO target realm")
+
+	// Sanity: the underscore-prefixed key from the previous internal
+	// shape is NOT what we use anymore — guards against drift.
+	_, oldKey := captor.gotDetails["_realm"]
+	require.False(t, oldKey, "legacy _realm key should not be set")
+}