feat(profiles): per-agent-token profile_pin + server-side enforcement (Profiles v2 T3, MCP-3242)

Reviewed and accepted by CEO (Claude) and KimiReviewer. All CI passes. MCP-3427 review thread.

Author: Dumbris

cmd/mcpproxy/token_cmd.go

@@ -23,6 +23,7 @@ var (
 	tokenServers     string
 	tokenPermissions string
 	tokenExpires     string
+	tokenProfilePin  string
 )
 
 // GetTokenCommand returns the token parent command.
@@ -73,6 +74,7 @@ Examples:
 	cmd.Flags().StringVar(&tokenServers, "servers", "", "Comma-separated list of allowed server names, or \"*\" for all (required)")
 	cmd.Flags().StringVar(&tokenPermissions, "permissions", "", "Comma-separated permission tiers: read, write, destructive (required, must include read)")
 	cmd.Flags().StringVar(&tokenExpires, "expires", "30d", "Token expiry duration (e.g., 7d, 30d, 90d, 365d)")
+	cmd.Flags().StringVar(&tokenProfilePin, "profile-pin", "", "Pin this token to a profile; it can only operate in that profile (cannot switch via set_profile or /mcp/p/<other>)")
 	_ = cmd.MarkFlagRequired("name")
 	_ = cmd.MarkFlagRequired("servers")
 	_ = cmd.MarkFlagRequired("permissions")
@@ -160,6 +162,9 @@ func runTokenCreate(_ *cobra.Command, _ []string) error {
 		"permissions":     permissions,
 		"expires_in":      tokenExpires,
 	}
+	if tokenProfilePin != "" {
+		body["profile_pin"] = tokenProfilePin
+	}
 
 	bodyJSON, err := json.Marshal(body)
 	if err != nil {
@@ -209,6 +214,9 @@ func runTokenCreate(_ *cobra.Command, _ []string) error {
 	printField("  Name:        ", result, "name")
 	printListField("  Servers:     ", result, "allowed_servers")
 	printListField("  Permissions: ", result, "permissions")
+	if pin := getMapString(result, "profile_pin"); pin != "" {
+		fmt.Printf("  Profile Pin: %s\n", pin)
+	}
 	printField("  Expires:     ", result, "expires_at")
 
 	return nil
@@ -257,9 +265,9 @@ func runTokenList(_ *cobra.Command, _ []string) error {
 	}
 
 	// Table format
-	fmt.Printf("%-20s %-14s %-25s %-20s %-8s %-25s\n",
-		"NAME", "PREFIX", "SERVERS", "PERMISSIONS", "REVOKED", "EXPIRES")
-	fmt.Println(strings.Repeat("-", 115))
+	fmt.Printf("%-20s %-14s %-25s %-20s %-8s %-12s %-25s\n",
+		"NAME", "PREFIX", "SERVERS", "PERMISSIONS", "REVOKED", "PROFILE PIN", "EXPIRES")
+	fmt.Println(strings.Repeat("-", 128))
 
 	for _, t := range tokens {
 		tok, ok := t.(map[string]interface{})
@@ -276,15 +284,20 @@ func runTokenList(_ *cobra.Command, _ []string) error {
 		serverList := joinInterfaceSlice(tok, "allowed_servers", 23)
 		permList := joinInterfaceSlice(tok, "permissions", 0)
 
+		pin := getMapString(tok, "profile_pin")
+		if pin == "" {
+			pin = "-"
+		}
+
 		expiresAt := getMapString(tok, "expires_at")
 		if expiresAt != "" {
 			if t, parseErr := time.Parse(time.RFC3339, expiresAt); parseErr == nil {
 				expiresAt = t.Format("2006-01-02 15:04")
 			}
 		}
 
-		fmt.Printf("%-20s %-14s %-25s %-20s %-8s %-25s\n",
-			name, prefix, serverList, permList, revoked, expiresAt)
+		fmt.Printf("%-20s %-14s %-25s %-20s %-8s %-12s %-25s\n",
+			name, prefix, serverList, permList, revoked, pin, expiresAt)
 	}
 
 	return nil
@@ -335,6 +348,9 @@ func runTokenShow(_ *cobra.Command, args []string) error {
 	printField("Token Prefix:   ", result, "token_prefix")
 	printListField("Servers:        ", result, "allowed_servers")
 	printListField("Permissions:    ", result, "permissions")
+	if pin := getMapString(result, "profile_pin"); pin != "" {
+		fmt.Printf("Profile Pin:    %s\n", pin)
+	}
 	if revoked, ok := result["revoked"].(bool); ok {
 		fmt.Printf("Revoked:        %v\n", revoked)
 	}

docs/features/agent-tokens.md

@@ -176,6 +176,38 @@ Server scoping is enforced at two levels:
 1. **Tool discovery** (`retrieve_tools`) — only returns tools from allowed servers
 2. **Tool execution** (`call_tool_*`) — blocks calls to out-of-scope servers
 
+## Profile Pinning
+
+A [profile](./profiles.md) scopes tool discovery and calls to a named subset of upstream servers. With `--profile-pin`, you can **bind a token to a single profile** so it can never operate outside it — regardless of the URL it connects to or any `set_profile` call it makes.
+
+```bash
+# This token can ONLY ever see/use the "research" profile
+mcpproxy token create \
+  --name research-agent \
+  --servers "*" \
+  --permissions read \
+  --profile-pin research
+```
+
+Server-side enforcement (no client cooperation required):
+
+- **`set_profile("other")` is rejected** — a pinned token cannot switch its session to a different profile (switching to its own pinned profile, or clearing, is allowed).
+- **`/mcp/p/<other>` returns `403`** — connecting to any profile URL other than the pinned one is forbidden; the pinned profile's own URL works.
+- **The pin is the highest-precedence resolver source**, above an explicit `/mcp/p/<slug>` URL scope and above a session `set_profile` selection.
+
+Resolution precedence (highest wins):
+
+```
+1. agent-token profile_pin   (server-enforced; this section)
+2. /mcp/p/<slug> URL scope    (per-request override)
+3. set_profile session state  (base /mcp endpoint default for the session)
+4. none                        (no profile filtering — all allowed servers)
+```
+
+**Validation & config changes**: the pinned slug must name a configured profile at creation time (creation is rejected otherwise). If the profile is later removed from the configuration, requests are **warn-skipped** rather than hard-failed — the pin still blocks switching away, so the token can never silently widen its scope, but profile filtering falls through to the next precedence tier. Pinning composes with server scoping and permission tiers: a request must satisfy **all** of them.
+
+The pin is shown by `token list` (PROFILE PIN column) and `token show` (Profile Pin field), and is preserved across `token regenerate`.
+
 ## Managing Tokens
 
 ### List All Tokens
@@ -304,3 +336,4 @@ mcpproxy serve --require-mcp-auth    # Enforce /mcp authentication
 | `--servers` | Yes | — | Comma-separated server names or `"*"` |
 | `--permissions` | Yes | — | Comma-separated: `read`, `write`, `destructive` |
 | `--expires` | No | `30d` | Expiry duration (e.g., `7d`, `90d`, `365d`) |
+| `--profile-pin` | No | — | Pin the token to a single profile (see [Profile Pinning](#profile-pinning)) |

internal/auth/agent_token.go

@@ -42,7 +42,8 @@ type AgentToken struct {
 	CreatedAt      time.Time  `json:"created_at"`
 	LastUsedAt     *time.Time `json:"last_used_at,omitempty"`
 	Revoked        bool       `json:"revoked"`
-	UserID         string     `json:"user_id,omitempty"` // Owner user ID (server edition)
+	UserID         string     `json:"user_id,omitempty"`     // Owner user ID (server edition)
+	ProfilePin     string     `json:"profile_pin,omitempty"` // Profile this token is pinned to (Profiles v2 T3)
 }
 
 // IsExpired returns true if the token has passed its expiry time.

internal/auth/context.go

@@ -17,6 +17,7 @@ type AuthContext struct {
 	TokenPrefix    string   // First 12 chars of raw token (empty for admin)
 	AllowedServers []string // Servers this token can access (nil = all for admin)
 	Permissions    []string // Permission tiers (nil = all for admin)
+	ProfilePin     string   // Profile this agent token is pinned to (Profiles v2 T3; empty if unpinned)
 
 	// Multi-user OAuth fields (server edition). Empty for non-user auth types.
 	UserID      string // User's unique ULID identifier

internal/httpapi/tokens.go

@@ -38,6 +38,7 @@ type createTokenRequest struct {
 	AllowedServers []string `json:"allowed_servers"`
 	Permissions    []string `json:"permissions"`
 	ExpiresIn      string   `json:"expires_in"`
+	ProfilePin     string   `json:"profile_pin,omitempty"`
 }
 
 // createTokenResponse is the JSON response for POST /api/v1/tokens.
@@ -48,6 +49,7 @@ type createTokenResponse struct {
 	Permissions    []string  `json:"permissions"`
 	ExpiresAt      time.Time `json:"expires_at"`
 	CreatedAt      time.Time `json:"created_at"`
+	ProfilePin     string    `json:"profile_pin,omitempty"`
 }
 
 // tokenInfoResponse is the JSON response for GET endpoints (no secret).
@@ -60,6 +62,7 @@ type tokenInfoResponse struct {
 	CreatedAt      time.Time  `json:"created_at"`
 	LastUsedAt     *time.Time `json:"last_used_at,omitempty"`
 	Revoked        bool       `json:"revoked"`
+	ProfilePin     string     `json:"profile_pin,omitempty"`
 }
 
 // regenerateTokenResponse is the JSON response for POST /api/v1/tokens/{name}/regenerate.
@@ -148,6 +151,16 @@ func (s *Server) handleCreateToken(w http.ResponseWriter, r *http.Request) {
 		req.AllowedServers = []string{"*"}
 	}
 
+	// Validate profile_pin (Profiles v2 T3): the slug must name a configured
+	// profile at creation time. Later config changes are warn-skipped at request
+	// time by the resolver, not hard-failed here.
+	if req.ProfilePin != "" {
+		if err := s.validateProfilePin(req.ProfilePin); err != nil {
+			s.writeError(w, r, http.StatusBadRequest, err.Error())
+			return
+		}
+	}
+
 	// Generate token
 	rawToken, err := auth.GenerateToken()
 	if err != nil {
@@ -171,6 +184,7 @@ func (s *Server) handleCreateToken(w http.ResponseWriter, r *http.Request) {
 		Permissions:    req.Permissions,
 		ExpiresAt:      expiresAt,
 		CreatedAt:      now,
+		ProfilePin:     req.ProfilePin,
 	}
 
 	if err := s.tokenStore.CreateAgentToken(agentToken, rawToken, hmacKey); err != nil {
@@ -191,6 +205,7 @@ func (s *Server) handleCreateToken(w http.ResponseWriter, r *http.Request) {
 		Permissions:    req.Permissions,
 		ExpiresAt:      expiresAt,
 		CreatedAt:      now,
+		ProfilePin:     req.ProfilePin,
 	}
 
 	s.writeJSON(w, http.StatusCreated, contracts.NewSuccessResponse(resp))
@@ -350,6 +365,26 @@ func validateTokenPermissions(perms []string) error {
 	return auth.ValidatePermissions(perms)
 }
 
+// validateProfilePin checks that the given profile slug names a profile in the
+// current configuration (Profiles v2 T3). It errors if profiles are unavailable
+// or the slug is unknown, so a token cannot be pinned to a non-existent profile.
+func (s *Server) validateProfilePin(slug string) error {
+	cfg, err := s.controller.GetConfig()
+	if err != nil || cfg == nil {
+		return fmt.Errorf("cannot validate profile_pin: configuration unavailable")
+	}
+	for i := range cfg.Profiles {
+		if cfg.Profiles[i].Name == slug {
+			return nil
+		}
+	}
+	available := make([]string, 0, len(cfg.Profiles))
+	for i := range cfg.Profiles {
+		available = append(available, cfg.Profiles[i].Name)
+	}
+	return fmt.Errorf("unknown profile_pin %q (available: %s)", slug, strings.Join(available, ", "))
+}
+
 // parseExpiry parses an expiry duration string and returns the absolute expiry time.
 // Accepted formats: "30d" (days), "720h" (hours), or any Go duration string.
 // Maximum allowed duration is 365 days. Empty string defaults to 30 days.
@@ -434,5 +469,6 @@ func tokenToInfoResponse(t auth.AgentToken) tokenInfoResponse {
 		CreatedAt:      t.CreatedAt,
 		LastUsedAt:     t.LastUsedAt,
 		Revoked:        t.Revoked,
+		ProfilePin:     t.ProfilePin,
 	}
 }

internal/httpapi/tokens_test.go

@@ -115,8 +115,9 @@ func (m *mockTokenStore) RegenerateAgentToken(name string, _ string, _ []byte) (
 
 type mockTokenController struct {
 	baseController
-	apiKey  string
-	servers []string
+	apiKey   string
+	servers  []string
+	profiles []string
 }
 
 func (m *mockTokenController) GetCurrentConfig() interface{} {
@@ -125,6 +126,14 @@ func (m *mockTokenController) GetCurrentConfig() interface{} {
 	}
 }
 
+func (m *mockTokenController) GetConfig() (*config.Config, error) {
+	cfg := &config.Config{APIKey: m.apiKey}
+	for _, name := range m.profiles {
+		cfg.Profiles = append(cfg.Profiles, config.ProfileConfig{Name: name})
+	}
+	return cfg, nil
+}
+
 func (m *mockTokenController) GetAllServers() ([]map[string]interface{}, error) {
 	result := make([]map[string]interface{}, 0, len(m.servers))
 	for _, name := range m.servers {
@@ -153,6 +162,21 @@ func newTestTokenServer(t *testing.T, store *mockTokenStore, servers []string) *
 	return srv
 }
 
+// newTestTokenServerWithProfiles is like newTestTokenServer but also configures
+// the controller's known profiles (for profile_pin validation tests).
+func newTestTokenServerWithProfiles(t *testing.T, store *mockTokenStore, servers, profiles []string) *Server {
+	t.Helper()
+	logger := zap.NewNop().Sugar()
+	ctrl := &mockTokenController{
+		apiKey:   "test-api-key",
+		servers:  servers,
+		profiles: profiles,
+	}
+	srv := NewServer(ctrl, logger, nil)
+	srv.SetTokenStore(store, t.TempDir())
+	return srv
+}
+
 func doRequest(t *testing.T, srv *Server, method, path string, body interface{}) *httptest.ResponseRecorder {
 	t.Helper()
 	var reqBody *bytes.Reader
@@ -220,6 +244,55 @@ func TestCreateToken_Success(t *testing.T) {
 	assert.Equal(t, "my-agent", stored.Name)
 }
 
+func TestCreateToken_ProfilePin(t *testing.T) {
+	store := newMockTokenStore()
+	srv := newTestTokenServerWithProfiles(t, store, []string{"server1"}, []string{"research", "deploy"})
+
+	body := createTokenRequest{
+		Name:           "pinned-agent",
+		AllowedServers: []string{"server1"},
+		Permissions:    []string{"read"},
+		ProfilePin:     "research",
+	}
+
+	w := doRequest(t, srv, http.MethodPost, "/api/v1/tokens", body)
+	require.Equal(t, http.StatusCreated, w.Code, "expected 201; body=%s", w.Body.String())
+
+	var resp createTokenResponse
+	decodeSuccess(t, w, &resp)
+	assert.Equal(t, "research", resp.ProfilePin, "profile_pin must be echoed on create")
+
+	// Stored record carries the pin.
+	stored, err := store.GetAgentTokenByName("pinned-agent")
+	require.NoError(t, err)
+	require.NotNil(t, stored)
+	assert.Equal(t, "research", stored.ProfilePin)
+
+	// GET surfaces the pin.
+	g := doRequest(t, srv, http.MethodGet, "/api/v1/tokens/pinned-agent", nil)
+	require.Equal(t, http.StatusOK, g.Code)
+	var info tokenInfoResponse
+	decodeSuccess(t, g, &info)
+	assert.Equal(t, "research", info.ProfilePin, "profile_pin must be surfaced on read")
+}
+
+func TestCreateToken_ProfilePinUnknownRejected(t *testing.T) {
+	store := newMockTokenStore()
+	srv := newTestTokenServerWithProfiles(t, store, []string{"server1"}, []string{"research"})
+
+	body := createTokenRequest{
+		Name:        "bad-pin",
+		Permissions: []string{"read"},
+		ProfilePin:  "ghost",
+	}
+
+	w := doRequest(t, srv, http.MethodPost, "/api/v1/tokens", body)
+	assert.Equal(t, http.StatusBadRequest, w.Code, "unknown profile_pin must be rejected at creation")
+
+	_, err := store.GetAgentTokenByName("bad-pin")
+	require.NoError(t, err)
+}
+
 func TestCreateToken_DefaultPermissions(t *testing.T) {
 	store := newMockTokenStore()
 	srv := newTestTokenServer(t, store, nil)