spec/runner: extend with multi-peer, from_any, auth-aware router, compute steps

Builds on the runner skeleton with the features needed for the larger
plan set:

  - Multi-peer plans: declare named peers via top-level `peers:`,
    dispatch each step to one of them via per-step `peer:`. Single-peer
    plans omit both and use an implicit "default" peer (zero-config).
  - {{$name}} placeholder substitution on the send side, so a step can
    echo router-assigned ids (e.g. INVOCATION id captured from a prior
    expect) into outgoing messages.
  - `from_any: [peerA, peerB]` step type with `capture_source` — race
    Recv on multiple peers via reflect.Select, capture which one
    delivered. Unblocks plans where the spec leaves dispatch order
    unspecified (e.g. shared registration with invoke=random).
  - `peer: "{{$captured_name}}"` — placeholder substitution in the peer
    field, so a follow-up step targets whichever peer was selected.
  - Auth-aware router setup via plan-declared `auth:` block. Runner
    builds a static keystore over in-line user maps and wires
    Anonymous / Ticket / WAMP-CRA authenticators into the per-test
    realm config. Default unchanged when `auth:` is absent.
  - Compute step type with wampcra_sign helper — runs HMAC-SHA256 over
    a captured challenge and stores the base64 signature back into
    captures so a subsequent AUTHENTICATE step can use it.

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

Author: Marko Petzold

spec/runner/auth.go

@@ -0,0 +1,257 @@
+package runner
+
+import (
+	"errors"
+	"fmt"
+	"time"
+
+	"github.com/gammazero/nexus/v3/router/auth"
+	"github.com/gammazero/nexus/v3/wamp"
+	"github.com/gammazero/nexus/v3/wamp/crsign"
+)
+
+// ComputeSpec is a non-wire side-step that derives a value from
+// captures and stores it back into captures. Currently only
+// `wampcra_sign` is implemented; future helpers (e.g. cryptosign,
+// hex/base64 transforms) can extend this struct.
+type ComputeSpec struct {
+	WAMPCRASign *WAMPCRASignSpec `yaml:"wampcra_sign,omitempty"`
+}
+
+// WAMPCRASignSpec computes an HMAC-SHA256 signature over a previously
+// captured challenge string, using the given secret. The result
+// (base64-encoded) lands in captures under `Capture` so a later
+// `send: [5, "{{$signature}}", {}]` AUTHENTICATE step can use it.
+//
+// Example:
+//
+//	- expect: [4, "wampcra", {challenge: "{{$challenge:string}}"}]
+//	- compute:
+//	    wampcra_sign:
+//	      challenge: "{{$challenge}}"
+//	      secret: "alice-secret"
+//	      capture: signature
+//	- send: [5, "{{$signature}}", {}]
+type WAMPCRASignSpec struct {
+	// Challenge is the challenge string emitted by the router in
+	// CHALLENGE.Extra.challenge. Use a placeholder like "{{$challenge}}"
+	// to pull a previously captured value.
+	Challenge string `yaml:"challenge"`
+	// Secret is the user's WAMP-CRA secret as bytes (utf-8 string).
+	Secret string `yaml:"secret"`
+	// Capture is the placeholder name to store the computed signature
+	// under. The signature is the base64 HMAC-SHA256 string.
+	Capture string `yaml:"capture"`
+}
+
+// runCompute executes a Compute step, resolving placeholders in its
+// inputs against captures and writing the output back.
+func runCompute(spec *ComputeSpec, captures map[string]any) error {
+	if spec == nil {
+		return errors.New("nil compute spec")
+	}
+	if spec.WAMPCRASign != nil {
+		s := spec.WAMPCRASign
+		if s.Capture == "" {
+			return errors.New("wampcra_sign requires `capture` name")
+		}
+		challenge, err := resolveStringPlaceholder(s.Challenge, captures)
+		if err != nil {
+			return fmt.Errorf("wampcra_sign challenge: %w", err)
+		}
+		captures[s.Capture] = crsign.SignChallenge(challenge, []byte(s.Secret))
+		return nil
+	}
+	return errors.New("compute step has no operation set")
+}
+
+// resolveStringPlaceholder yields s as-is, OR if s is a "{{$name}}"
+// placeholder, the captured value (must be a string).
+func resolveStringPlaceholder(s string, captures map[string]any) (string, error) {
+	if !isPlaceholder(s) {
+		return s, nil
+	}
+	body := s[3 : len(s)-2] // strip {{$ and }}
+	name := body
+	if i := indexByte(body, ':'); i != -1 {
+		name = body[:i]
+	}
+	val, ok := captures[name]
+	if !ok {
+		return "", fmt.Errorf("placeholder %q references uncaptured name", s)
+	}
+	str, ok := val.(string)
+	if !ok {
+		return "", fmt.Errorf("placeholder %q resolved to non-string %T", s, val)
+	}
+	return str, nil
+}
+
+func indexByte(s string, c byte) int {
+	for i := 0; i < len(s); i++ {
+		if s[i] == c {
+			return i
+		}
+	}
+	return -1
+}
+
+// AuthSpec is the on-disk YAML auth declaration for a plan. All fields
+// are optional. If the whole block is absent (Auth==nil), the runner
+// uses the legacy default (anonymous-only, role="anonymous").
+//
+// Example:
+//
+//	auth:
+//	  anonymous: { role: anonymous }
+//	  ticket:
+//	    users:
+//	      tester: { ticket: "ticket-X-1234", role: "user" }
+//	  wampcra:
+//	    users:
+//	      jdoe: { secret: "squeemishosafradge", role: "user" }
+type AuthSpec struct {
+	Anonymous *AnonymousSpec `yaml:"anonymous,omitempty"`
+	Ticket    *TicketSpec    `yaml:"ticket,omitempty"`
+	WAMPCRA   *WAMPCRASpec   `yaml:"wampcra,omitempty"`
+}
+
+// AnonymousSpec configures anonymous auth. Empty role defaults to "anonymous".
+type AnonymousSpec struct {
+	Role string `yaml:"role,omitempty"`
+}
+
+// TicketSpec configures ticket-based dynamic CR auth with a static
+// authid → ticket+role map (see test/spec_auth_ticket_test.go for the
+// runtime semantics).
+type TicketSpec struct {
+	Users map[string]TicketUser `yaml:"users"`
+}
+
+type TicketUser struct {
+	Ticket string `yaml:"ticket"`
+	Role   string `yaml:"role"`
+}
+
+// WAMPCRASpec configures WAMP-CRA auth with a static authid → secret+role map.
+type WAMPCRASpec struct {
+	Users map[string]WAMPCRAUser `yaml:"users"`
+}
+
+type WAMPCRAUser struct {
+	Secret string `yaml:"secret"`
+	Role   string `yaml:"role"`
+}
+
+// staticKeyStore implements auth.KeyStore over an in-memory user map
+// loaded from a plan's AuthSpec. It supports both ticket and wampcra
+// authmethods on the same authid, picking the right key by method.
+type staticKeyStore struct {
+	tickets  map[string]TicketUser  // authid → ticket user
+	wampcras map[string]WAMPCRAUser // authid → wampcra user
+}
+
+func (ks *staticKeyStore) AuthKey(authid, authmethod string) ([]byte, error) {
+	switch authmethod {
+	case "ticket":
+		u, ok := ks.tickets[authid]
+		if !ok {
+			return nil, errors.New("no ticket user: " + authid)
+		}
+		return []byte(u.Ticket), nil
+	case "wampcra":
+		u, ok := ks.wampcras[authid]
+		if !ok {
+			return nil, errors.New("no wampcra user: " + authid)
+		}
+		return []byte(u.Secret), nil
+	}
+	return nil, errors.New("unsupported authmethod: " + authmethod)
+}
+
+func (ks *staticKeyStore) AuthRole(authid string) (string, error) {
+	if u, ok := ks.tickets[authid]; ok {
+		return u.Role, nil
+	}
+	if u, ok := ks.wampcras[authid]; ok {
+		return u.Role, nil
+	}
+	return "", errors.New("no such user: " + authid)
+}
+
+func (ks *staticKeyStore) PasswordInfo(string) (string, int, int) { return "", 0, 0 }
+func (ks *staticKeyStore) Provider() string                       { return "spec-runner-static" }
+
+// buildAuthenticators converts an AuthSpec into the list of
+// authenticators to wire into the per-plan router. Returns whether
+// anonymous auth should be enabled on the realm and the role to assign
+// to anonymous sessions (empty = use realm's default).
+func buildAuthenticators(spec *AuthSpec) (anonOn bool, anonRole string, auths []auth.Authenticator) {
+	if spec == nil {
+		// Legacy default: anonymous auth, anonymous role.
+		return true, "", nil
+	}
+
+	ks := &staticKeyStore{
+		tickets:  map[string]TicketUser{},
+		wampcras: map[string]WAMPCRAUser{},
+	}
+	hasTicketUsers := spec.Ticket != nil && len(spec.Ticket.Users) > 0
+	hasWAMPCRAUsers := spec.WAMPCRA != nil && len(spec.WAMPCRA.Users) > 0
+
+	if hasTicketUsers {
+		for id, u := range spec.Ticket.Users {
+			ks.tickets[id] = u
+		}
+		auths = append(auths, auth.NewTicketAuthenticator(ks, time.Second))
+	}
+	if hasWAMPCRAUsers {
+		for id, u := range spec.WAMPCRA.Users {
+			ks.wampcras[id] = u
+		}
+		auths = append(auths, auth.NewCRAuthenticator(ks, time.Second))
+	}
+	if spec.Anonymous != nil {
+		anonOn = true
+		anonRole = spec.Anonymous.Role
+	}
+	return anonOn, anonRole, auths
+}
+
+// roleListForRealm returns the roles a per-plan realm needs to declare
+// so that authenticated sessions can be assigned to them. Pulls every
+// role mentioned in the auth spec, plus "anonymous" if anonymous auth
+// is enabled (defaulting role for anon).
+func roleListForRealm(spec *AuthSpec) []string {
+	if spec == nil {
+		return []string{"anonymous"}
+	}
+	seen := map[string]struct{}{}
+	add := func(r string) {
+		if r == "" {
+			r = "anonymous"
+		}
+		seen[r] = struct{}{}
+	}
+	if spec.Anonymous != nil {
+		add(spec.Anonymous.Role)
+	}
+	if spec.Ticket != nil {
+		for _, u := range spec.Ticket.Users {
+			add(u.Role)
+		}
+	}
+	if spec.WAMPCRA != nil {
+		for _, u := range spec.WAMPCRA.Users {
+			add(u.Role)
+		}
+	}
+	out := make([]string, 0, len(seen))
+	for r := range seen {
+		out = append(out, r)
+	}
+	return out
+}
+
+// suppress unused warnings for wamp import if these helpers grow.
+var _ = wamp.URI("")

spec/runner/matcher.go

@@ -136,6 +136,65 @@ func matchPlaceholder(path, ph string, actual any, captures map[string]any) erro
 	return nil
 }
 
+// substituteCaptures walks a YAML-loaded list and replaces any string
+// shaped like "{{$name}}" or "{{$name:type}}" with the captured value
+// from a previous `expect` step. Used on the send side so a plan can
+// echo back ids the router assigned (e.g. yield to an INVOCATION id
+// captured from a prior INVOCATION expect).
+//
+// Returns an error if a placeholder references a name that hasn't been
+// captured yet.
+func substituteCaptures(v any, captures map[string]any) (any, error) {
+	switch x := v.(type) {
+	case string:
+		if !isPlaceholder(x) {
+			return x, nil
+		}
+		body := strings.TrimSuffix(strings.TrimPrefix(x, "{{$"), "}}")
+		name, _, _ := strings.Cut(body, ":")
+		if name == "" {
+			return nil, fmt.Errorf("send placeholder %q has no name to substitute", x)
+		}
+		val, ok := captures[name]
+		if !ok {
+			return nil, fmt.Errorf("send placeholder %q references uncaptured name", x)
+		}
+		return val, nil
+	case []any:
+		out := make([]any, len(x))
+		for i, item := range x {
+			r, err := substituteCaptures(item, captures)
+			if err != nil {
+				return nil, err
+			}
+			out[i] = r
+		}
+		return out, nil
+	case map[string]any:
+		out := make(map[string]any, len(x))
+		for k, val := range x {
+			r, err := substituteCaptures(val, captures)
+			if err != nil {
+				return nil, err
+			}
+			out[k] = r
+		}
+		return out, nil
+	case map[any]any:
+		out := make(map[string]any, len(x))
+		for k, val := range x {
+			r, err := substituteCaptures(val, captures)
+			if err != nil {
+				return nil, err
+			}
+			out[fmt.Sprint(k)] = r
+		}
+		return out, nil
+	default:
+		return v, nil
+	}
+}
+
 // asInt accepts int, int64, float64 (YAML/JSON numeric forms) and returns
 // the int64 value.
 func asInt(v any) (int64, error) {