feat(057): profile config entity + ProfileScope context (T001-T007)

Foundational phase for in-proxy profiles (Spec 057, GH #55). No behaviour
change yet — adds the config entity + validation and the request-scoped scope
primitive; the /mcp/p/ routing and filter sites come next.

- internal/config/profiles.go: ProfileConfig{Name,Servers} + ValidateProfiles
  (fatal: slug pattern ^[a-z0-9][a-z0-9_-]{0,62}$, reserved {all,code,call,p},
  duplicate name; warn-skip: unknown server, empty servers). EffectiveServers
  helper. (T003)
- internal/config/config.go: Config.Profiles []ProfileConfig `json:",omitempty"`
  after Servers (SC-004 byte-identical when absent); Validate() runs
  ValidateProfiles, fails on fatal, stashes warnings; ProfileWarnings() accessor
  for the boot path to log. (T004)
- internal/profile/context.go: ProfileScope{Name, servers set} with nil-receiver
  allow-all Allows(), WithProfileScope/ProfileScopeFromContext (mirrors
  internal/auth/context.go). (T007)
- Tests red-first: profiles_test.go (validation table + round-trip, T002/T005),
  profile/context_test.go (membership, nil allow-all, empty deny-all,
  context round-trip, T006).

Both editions build; go vet clean.

Related #55

Co-Authored-By: Paperclip <noreply@paperclip.ing>

Author: Dumbris

internal/config/config.go

@@ -107,6 +107,10 @@ type Config struct {
 	EnableTray  bool            `json:"enable_tray,omitempty" mapstructure:"tray"`
 	DebugSearch bool            `json:"debug_search" mapstructure:"debug-search"`
 	Servers     []*ServerConfig `json:"mcpServers" mapstructure:"servers"`
+	// Profiles are optional named, server-scoped views exposed at /mcp/p/<name>
+	// (Spec 057). Absent/empty is fully supported — /mcp is unchanged and configs
+	// without this key serialize byte-identically (SC-004).
+	Profiles []ProfileConfig `json:"profiles,omitempty" mapstructure:"profiles"`
 	// Deprecated: TopK is superseded by ToolsLimit and has no runtime effect. Kept for backward compatibility.
 	TopK               int      `json:"top_k,omitempty" mapstructure:"top-k"`
 	ToolsLimit         int      `json:"tools_limit" mapstructure:"tools-limit"`
@@ -140,6 +144,10 @@ type Config struct {
 	// Internal field to track if API key was explicitly set in config
 	apiKeyExplicitlySet bool `json:"-"`
 
+	// profileWarnings holds non-fatal Spec 057 profile diagnostics (unknown /
+	// empty servers) captured during Validate(), for the boot path to log.
+	profileWarnings []string `json:"-"`
+
 	// Prompts settings
 	EnablePrompts bool `json:"enable_prompts" mapstructure:"enable-prompts"`
 
@@ -1553,6 +1561,15 @@ func (c *Config) Validate() error {
 		return fmt.Errorf("%s", errors[0].Error())
 	}
 
+	// Validate profiles (Spec 057): fatal rules (invalid/reserved/duplicate slug)
+	// fail the load; soft rules (unknown/empty servers) are stashed as warnings
+	// for the boot path to log via its logger (see ProfileWarnings).
+	profileWarnings, profileErr := ValidateProfiles(c)
+	if profileErr != nil {
+		return profileErr
+	}
+	c.profileWarnings = profileWarnings
+
 	// Handle API key generation if not configured
 	// Empty string means authentication disabled, nil means auto-generate
 	if c.APIKey == "" {

internal/config/profiles.go

@@ -0,0 +1,109 @@
+package config
+
+import (
+	"fmt"
+	"regexp"
+)
+
+// ProfileConfig is a named, stateless view over a subset of the configured
+// upstream servers, addressable at /mcp/p/<name> (Spec 057). The Name is used
+// verbatim as the URL slug. Servers references mcpServers[].name; unknown names
+// warn-and-skip rather than fail (FR-015).
+type ProfileConfig struct {
+	Name    string   `json:"name"`    // URL slug, validated
+	Servers []string `json:"servers"` // references to mcpServers[].name
+}
+
+// profileSlugPattern is the allowed profile-name form (FR-007): lowercase
+// alphanumeric start, then up to 62 more of [a-z0-9_-] — max 63 chars total.
+var profileSlugPattern = regexp.MustCompile(`^[a-z0-9][a-z0-9_-]{0,62}$`)
+
+// reservedProfileSlugs are URL path segments that collide with existing /mcp
+// routes (/mcp/code, /mcp/call) or the /mcp/p prefix itself, plus "all"
+// reserved for a future explicit all-servers profile (FR-007).
+var reservedProfileSlugs = map[string]struct{}{
+	"all":  {},
+	"code": {},
+	"call": {},
+	"p":    {},
+}
+
+// ValidateProfiles enforces the Spec 057 profile rules (data-model.md). Fatal
+// rules (invalid/reserved/duplicate slug) return an error that points at the
+// offending entry; soft rules (unknown server, empty server list) return
+// human-readable warnings without failing the load. A nil/empty Profiles slice
+// is fully valid (returns no warnings, no error) — preserving zero-config
+// behaviour (SC-004).
+func ValidateProfiles(cfg *Config) (warnings []string, err error) {
+	if cfg == nil || len(cfg.Profiles) == 0 {
+		return nil, nil
+	}
+
+	// Build the set of known server names for membership checks.
+	known := make(map[string]struct{}, len(cfg.Servers))
+	for _, s := range cfg.Servers {
+		if s != nil {
+			known[s.Name] = struct{}{}
+		}
+	}
+
+	seen := make(map[string]int, len(cfg.Profiles)) // slug -> first index
+	for i, p := range cfg.Profiles {
+		// Fatal: slug format.
+		if !profileSlugPattern.MatchString(p.Name) {
+			return warnings, fmt.Errorf("profiles[%d]: invalid profile name %q: must match %s (lowercase alphanumeric, '-'/'_', 1-63 chars)", i, p.Name, profileSlugPattern.String())
+		}
+		// Fatal: reserved slug.
+		if _, reserved := reservedProfileSlugs[p.Name]; reserved {
+			return warnings, fmt.Errorf("profiles[%d]: profile name %q is reserved and cannot be used", i, p.Name)
+		}
+		// Fatal: duplicate name (name both occurrences).
+		if first, dup := seen[p.Name]; dup {
+			return warnings, fmt.Errorf("profiles[%d]: duplicate profile name %q (already defined at profiles[%d])", i, p.Name, first)
+		}
+		seen[p.Name] = i
+
+		// Warning: empty server list (legal deny-all).
+		if len(p.Servers) == 0 {
+			warnings = append(warnings, fmt.Sprintf("profile %q has no servers; it will expose zero tools (deny-all placeholder)", p.Name))
+			continue
+		}
+		// Warning: unknown server references (warn-and-skip).
+		for _, srv := range p.Servers {
+			if _, ok := known[srv]; !ok {
+				warnings = append(warnings, fmt.Sprintf("profile %q references unknown server %q; it will be skipped", p.Name, srv))
+			}
+		}
+	}
+
+	return warnings, nil
+}
+
+// ProfileWarnings returns the non-fatal profile diagnostics captured by the most
+// recent Validate() call (unknown-server and empty-server warnings). The boot
+// path logs these via its logger; an empty result means no warnings.
+func (c *Config) ProfileWarnings() []string {
+	return c.profileWarnings
+}
+
+// EffectiveServers returns the profile's server list filtered to those that
+// actually exist in cfg (the warn-skip result). Order is preserved and unknown
+// names are dropped. Used by the profile middleware to build the request scope.
+func (p ProfileConfig) EffectiveServers(cfg *Config) []string {
+	if cfg == nil {
+		return nil
+	}
+	known := make(map[string]struct{}, len(cfg.Servers))
+	for _, s := range cfg.Servers {
+		if s != nil {
+			known[s.Name] = struct{}{}
+		}
+	}
+	out := make([]string, 0, len(p.Servers))
+	for _, srv := range p.Servers {
+		if _, ok := known[srv]; ok {
+			out = append(out, srv)
+		}
+	}
+	return out
+}

internal/config/profiles_test.go

@@ -0,0 +1,123 @@
+package config
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+func anyContains(ss []string, sub string) bool {
+	for _, s := range ss {
+		if strings.Contains(s, sub) {
+			return true
+		}
+	}
+	return false
+}
+
+// TestValidateProfiles covers the data-model.md validation table (Spec 057):
+// fatal slug/reserved/duplicate rules and warn-skip for unknown/empty servers.
+func TestValidateProfiles(t *testing.T) {
+	mk := func(profiles []ProfileConfig, servers ...string) *Config {
+		var sc []*ServerConfig
+		for _, s := range servers {
+			sc = append(sc, &ServerConfig{Name: s})
+		}
+		return &Config{Servers: sc, Profiles: profiles}
+	}
+
+	t.Run("valid profile passes with no error or warning", func(t *testing.T) {
+		warnings, err := ValidateProfiles(mk([]ProfileConfig{{Name: "research", Servers: []string{"fs", "web"}}}, "fs", "web"))
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if len(warnings) != 0 {
+			t.Errorf("expected no warnings, got %v", warnings)
+		}
+	})
+
+	fatal := []struct {
+		name     string
+		profiles []ProfileConfig
+	}{
+		{"uppercase slug", []ProfileConfig{{Name: "Research", Servers: []string{"fs"}}}},
+		{"leading dash", []ProfileConfig{{Name: "-x", Servers: []string{"fs"}}}},
+		{"contains space", []ProfileConfig{{Name: "a b", Servers: []string{"fs"}}}},
+		{"too long (64)", []ProfileConfig{{Name: strings.Repeat("a", 64), Servers: []string{"fs"}}}},
+		{"reserved all", []ProfileConfig{{Name: "all", Servers: []string{"fs"}}}},
+		{"reserved code", []ProfileConfig{{Name: "code", Servers: []string{"fs"}}}},
+		{"reserved call", []ProfileConfig{{Name: "call", Servers: []string{"fs"}}}},
+		{"reserved p", []ProfileConfig{{Name: "p", Servers: []string{"fs"}}}},
+	}
+	for _, tc := range fatal {
+		t.Run("fatal: "+tc.name, func(t *testing.T) {
+			_, err := ValidateProfiles(mk(tc.profiles, "fs"))
+			if err == nil {
+				t.Errorf("expected fatal error for %s", tc.name)
+			}
+		})
+	}
+
+	t.Run("boundary: 63-char slug is valid", func(t *testing.T) {
+		_, err := ValidateProfiles(mk([]ProfileConfig{{Name: strings.Repeat("a", 63), Servers: []string{"fs"}}}, "fs"))
+		if err != nil {
+			t.Errorf("63-char slug must be valid, got %v", err)
+		}
+	})
+
+	t.Run("fatal: duplicate name names the slug", func(t *testing.T) {
+		_, err := ValidateProfiles(mk([]ProfileConfig{
+			{Name: "dup", Servers: []string{"fs"}},
+			{Name: "dup", Servers: []string{"web"}},
+		}, "fs", "web"))
+		if err == nil || !strings.Contains(err.Error(), "dup") {
+			t.Errorf("expected duplicate-name error mentioning 'dup', got %v", err)
+		}
+	})
+
+	t.Run("warn-skip: unknown server warns, does not fail", func(t *testing.T) {
+		warnings, err := ValidateProfiles(mk([]ProfileConfig{{Name: "x", Servers: []string{"fs", "ghost"}}}, "fs"))
+		if err != nil {
+			t.Fatalf("unknown server must warn-and-skip, not fail: %v", err)
+		}
+		if !anyContains(warnings, "ghost") {
+			t.Errorf("expected a warning naming the unknown server 'ghost', got %v", warnings)
+		}
+	})
+
+	t.Run("warn: empty servers is a legal deny-all", func(t *testing.T) {
+		warnings, err := ValidateProfiles(mk([]ProfileConfig{{Name: "locked", Servers: nil}}))
+		if err != nil {
+			t.Fatalf("empty servers is legal (deny-all): %v", err)
+		}
+		if !anyContains(warnings, "locked") {
+			t.Errorf("expected a warning naming the empty profile 'locked', got %v", warnings)
+		}
+	})
+}
+
+// TestProfilesRoundTrip covers SC-004: absent profiles serialize away (omitempty)
+// so existing configs are byte-identical; present profiles round-trip losslessly.
+func TestProfilesRoundTrip(t *testing.T) {
+	noProfiles := &Config{Listen: "127.0.0.1:8080"}
+	b, err := json.Marshal(noProfiles)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(string(b), "profiles") {
+		t.Errorf("absent profiles must not appear in JSON (omitempty): %s", b)
+	}
+
+	withProfiles := &Config{Profiles: []ProfileConfig{{Name: "research", Servers: []string{"fs", "web"}}}}
+	b2, err := json.Marshal(withProfiles)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var back Config
+	if err := json.Unmarshal(b2, &back); err != nil {
+		t.Fatal(err)
+	}
+	if len(back.Profiles) != 1 || back.Profiles[0].Name != "research" || len(back.Profiles[0].Servers) != 2 {
+		t.Errorf("profiles did not round-trip losslessly: %+v", back.Profiles)
+	}
+}

internal/profile/context.go

@@ -0,0 +1,67 @@
+// Package profile carries request-scoped in-proxy profile filtering (Spec 057).
+//
+// A profile is a named, stateless view over a subset of the configured upstream
+// servers, addressable at /mcp/p/<slug>. A ProfileScope is resolved once by the
+// profile middleware from the request URL and injected into the request context;
+// the scope filters which servers a request may see/call. It is an independent,
+// auth-type-agnostic primitive that composes with (but does not depend on) the
+// Spec 028 agent-token scope — an unauthenticated /mcp/p/<slug> connection runs
+// as an admin AuthContext yet must still be profile-filtered.
+package profile
+
+import "context"
+
+// ProfileScope is the immutable, request-scoped set of servers a profile exposes.
+// It is resolved by profileMiddleware from the /mcp/p/<slug> URL and never mutated
+// for the lifetime of a request.
+type ProfileScope struct {
+	// Name is the resolved profile slug, used in rejection messages and activity
+	// metadata (FR-012).
+	Name string
+	// servers is the effective set after unknown-server warn-skip. A non-nil but
+	// empty set is a legal "deny everything" profile.
+	servers map[string]struct{}
+}
+
+// NewProfileScope builds a scope for the named profile over the given effective
+// server set. The returned scope is always non-nil (an empty/nil server list is
+// a legal profile that allows nothing).
+func NewProfileScope(name string, servers []string) *ProfileScope {
+	set := make(map[string]struct{}, len(servers))
+	for _, s := range servers {
+		set[s] = struct{}{}
+	}
+	return &ProfileScope{Name: name, servers: set}
+}
+
+// Allows reports whether the named server is visible under this scope.
+//
+// A nil receiver means the request did not enter via /mcp/p/<slug> (it used /mcp,
+// /mcp/code, or /mcp/call) and therefore is not profile-filtered — every server
+// is allowed (FR-010). A non-nil scope allows only servers in its set; the empty
+// server name is never allowed for a real scope.
+func (p *ProfileScope) Allows(serverName string) bool {
+	if p == nil {
+		return true
+	}
+	if serverName == "" {
+		return false
+	}
+	_, ok := p.servers[serverName]
+	return ok
+}
+
+// profileScopeKey is an unexported context key avoiding cross-package collisions.
+type profileScopeKey struct{}
+
+// WithProfileScope returns a context carrying the given ProfileScope.
+func WithProfileScope(ctx context.Context, p *ProfileScope) context.Context {
+	return context.WithValue(ctx, profileScopeKey{}, p)
+}
+
+// ProfileScopeFromContext extracts the ProfileScope, or nil when the request did
+// not enter via a profile URL (no filtering).
+func ProfileScopeFromContext(ctx context.Context) *ProfileScope {
+	p, _ := ctx.Value(profileScopeKey{}).(*ProfileScope)
+	return p
+}