fix: reject project list/use for CI-scoped keys with clear errors (#308)

* fix(cli): reject project list/use for CI-scoped keys with clear errors

Validate credentials before cross-project commands, omit X-Team-ID on
ListProjects, improve login and MCP flows for single-project CI keys,
and strip legacy workspace/team keys on profile save.

Co-Authored-By: Claude <noreply@anthropic.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(cli): address review feedback on login prefix and --type validation

Only show CI-scoped login prefix when validate confirms no user_id; validate
--type before the credentials check so invalid flags fail offline (fixes CI).

Co-Authored-By: Claude <noreply@anthropic.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

* chore(acceptance): move destination and gateway tags to slice 2

Rebalance CI matrix runtimes (~5.3 min slice 0 vs ~3 min slice 2). Move
ConnectionListResponse to helpers so gateway tests compile without
connection_list in the same build.

Co-Authored-By: Claude <noreply@anthropic.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

* refactor(cli): align project-scoped credential errors with API

Rename ErrProjectScopedCredentials (ErrCIScopedCredentials alias), update
messages for single-project scope, and match CLI_PROJECT_SCOPED from API.

Co-Authored-By: Claude <noreply@anthropic.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

Author: 3 people

.github/workflows/test-acceptance.yml

@@ -14,13 +14,13 @@ jobs:
         include:
           - slice: "0"
             api_key_secret: HOOKDECK_CLI_TESTING_API_KEY
-            tags: "basic connection source destination gateway mcp listen project_use connection_list connection_upsert connection_error_hints connection_oauth_aws connection_update"
+            tags: "basic connection source mcp listen project_use connection_list connection_upsert connection_error_hints connection_oauth_aws connection_update"
           - slice: "1"
             api_key_secret: HOOKDECK_CLI_TESTING_API_KEY_2
             tags: "request event"
           - slice: "2"
             api_key_secret: HOOKDECK_CLI_TESTING_API_KEY_3
-            tags: "attempt metrics issue transformation"
+            tags: "attempt metrics issue transformation destination gateway"
     runs-on: ubuntu-latest
     env:
       ACCEPTANCE_SLICE: ${{ matrix.slice }}

pkg/cmd/project_list.go

@@ -60,6 +60,10 @@ func (lc *projectListCmd) runProjectListCmd(cmd *cobra.Command, args []string) e
 		}
 	}
 
+	if err := project.EnsureUserAssociatedCredentials(&Config); err != nil {
+		return err
+	}
+
 	projects, err := project.ListProjects(&Config)
 	if err != nil {
 		return err

pkg/cmd/project_use.go

@@ -52,6 +52,10 @@ func (lc *projectUseCmd) runProjectUseCmd(cmd *cobra.Command, args []string) err
 		return err
 	}
 
+	if err := project.EnsureUserAssociatedCredentials(&Config); err != nil {
+		return err
+	}
+
 	projects, err := project.ListProjects(&Config)
 	if err != nil {
 		return err

pkg/config/profile.go

@@ -30,9 +30,34 @@ func (p *Profile) SaveProfile() error {
 	}
 	p.Config.viper.Set(p.getConfigField("project_type"), projectType)
 	p.Config.viper.Set(p.getConfigField("guest_url"), p.GuestURL)
+
+	if err := p.removeLegacyConfigKeys(); err != nil {
+		return err
+	}
+
 	return p.Config.writeConfig()
 }
 
+func (p *Profile) removeLegacyConfigKeys() error {
+	legacyKeys := []string{"workspace_id", "workspace_mode", "team_id", "team_mode"}
+	configFile := p.Config.viper.ConfigFileUsed()
+	var err error
+	for _, key := range legacyKeys {
+		p.Config.viper, err = removeKey(p.Config.viper, p.getConfigField(key))
+		if err != nil {
+			return err
+		}
+		p.Config.viper, err = removeKey(p.Config.viper, key)
+		if err != nil {
+			return err
+		}
+	}
+	if configFile != "" {
+		p.Config.viper.SetConfigFile(configFile)
+	}
+	return nil
+}
+
 func (p *Profile) RemoveProfile() error {
 	var err error
 	runtimeViper := p.Config.viper

pkg/config/profile_credentials_test.go

@@ -1,9 +1,12 @@
 package config
 
 import (
+	"os"
+	"path/filepath"
 	"testing"
 
 	"github.com/hookdeck/hookdeck-cli/pkg/hookdeck"
+	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
 
@@ -83,3 +86,39 @@ func TestProfile_ApplyCIClient(t *testing.T) {
 	require.Equal(t, ProjectTypeGateway, p.ProjectType)
 	require.Empty(t, p.GuestURL)
 }
+
+func TestSaveProfile_RemovesLegacyWorkspaceKeys(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "config.toml")
+	content := `profile = "default"
+workspace_id = "legacy_team"
+workspace_mode = "inbound"
+team_id = "legacy_team"
+team_mode = "inbound"
+
+[default]
+api_key = "hk_test_123456789012"
+project_id = "proj_new"
+project_mode = "inbound"
+workspace_id = "legacy_profile_team"
+workspace_mode = "inbound"
+team_id = "legacy_profile_team"
+team_mode = "inbound"
+`
+	require.NoError(t, os.WriteFile(path, []byte(content), 0600))
+
+	c, err := LoadConfigFromFile(path)
+	require.NoError(t, err)
+	c.Profile.Config = c
+
+	require.NoError(t, c.Profile.SaveProfile())
+
+	raw, err := os.ReadFile(path)
+	require.NoError(t, err)
+	tomlText := string(raw)
+	assert.NotContains(t, tomlText, "workspace_id")
+	assert.NotContains(t, tomlText, "workspace_mode")
+	assert.NotContains(t, tomlText, "team_id")
+	assert.NotContains(t, tomlText, "team_mode")
+	assert.Contains(t, tomlText, "project_id")
+}

pkg/gateway/mcp/server_test.go

@@ -39,6 +39,9 @@ func newTestClient(baseURL string, apiKey string) *hookdeck.Client {
 func connectInMemory(t *testing.T, client *hookdeck.Client) *mcpsdk.ClientSession {
 	t.Helper()
 	cfg := &config.Config{}
+	if client != nil && client.BaseURL != nil {
+		cfg.APIBaseURL = client.BaseURL.String()
+	}
 	srv := NewServer(client, cfg)
 
 	serverTransport, clientTransport := mcpsdk.NewInMemoryTransports()
@@ -92,6 +95,23 @@ func listResponse(models ...map[string]any) map[string]any {
 // mockAPI creates an httptest server that handles specific API paths.
 func mockAPI(t *testing.T, handlers map[string]http.HandlerFunc) *httptest.Server {
 	t.Helper()
+	if handlers == nil {
+		handlers = map[string]http.HandlerFunc{}
+	}
+	if _, ok := handlers["/2025-07-01/cli-auth/validate"]; !ok {
+		handlers["/2025-07-01/cli-auth/validate"] = func(w http.ResponseWriter, r *http.Request) {
+			json.NewEncoder(w).Encode(map[string]any{
+				"user_id":           "usr_test",
+				"user_name":         "Test User",
+				"user_email":        "u@example.com",
+				"organization_name": "Test Org",
+				"organization_id":   "org_test",
+				"team_id":           "proj_test123",
+				"team_name_no_org":  "Production",
+				"team_mode":         "console",
+			})
+		}
+	}
 	mux := http.NewServeMux()
 	for pattern, handler := range handlers {
 		mux.HandleFunc(pattern, handler)
@@ -1116,14 +1136,86 @@ func TestMetricsTool_UnknownAction(t *testing.T) {
 // ---------------------------------------------------------------------------
 
 func TestLoginTool_AlreadyAuthenticated(t *testing.T) {
-	client := newTestClient("https://api.hookdeck.com", "test-key")
+	api := mockAPI(t, map[string]http.HandlerFunc{
+		"/2025-07-01/cli-auth/validate": func(w http.ResponseWriter, r *http.Request) {
+			json.NewEncoder(w).Encode(map[string]any{
+				"user_id":           "usr_1",
+				"user_name":         "Test User",
+				"user_email":        "u@example.com",
+				"organization_name": "Org",
+				"organization_id":   "org_1",
+				"team_id":           "tm_1",
+				"team_name_no_org":  "Proj",
+				"team_mode":         "inbound",
+			})
+		},
+	})
+	client := newTestClient(api.URL, "test-key")
 	session := connectInMemory(t, client)
 
 	result := callTool(t, session, "hookdeck_login", map[string]any{})
 	assert.False(t, result.IsError)
 	assert.Contains(t, textContent(t, result), "Already authenticated")
 }
 
+func TestLoginTool_CIScopedKeyStartsLogin(t *testing.T) {
+	api := mockAPI(t, map[string]http.HandlerFunc{
+		"/2025-07-01/cli-auth/validate": func(w http.ResponseWriter, r *http.Request) {
+			json.NewEncoder(w).Encode(map[string]any{
+				"organization_name": "Org",
+				"organization_id":   "org_1",
+				"team_id":           "tm_ci",
+				"team_name_no_org":  "CI Project",
+				"team_mode":         "inbound",
+			})
+		},
+		"/2025-07-01/cli-auth": func(w http.ResponseWriter, r *http.Request) {
+			json.NewEncoder(w).Encode(map[string]any{
+				"browser_url": "https://hookdeck.com/auth?code=ci-upgrade",
+				"poll_url":    "http://" + r.Host + "/2025-07-01/cli-auth/poll?key=ci-upgrade",
+			})
+		},
+		"/2025-07-01/cli-auth/poll": func(w http.ResponseWriter, r *http.Request) {
+			json.NewEncoder(w).Encode(map[string]any{"claimed": false})
+		},
+	})
+	client := newTestClient(api.URL, "test-key")
+	session := connectInMemory(t, client)
+
+	result := callTool(t, session, "hookdeck_login", map[string]any{})
+	assert.False(t, result.IsError)
+	text := textContent(t, result)
+	assert.NotContains(t, text, "Already authenticated")
+	assert.Contains(t, text, "Login initiated")
+	assert.Contains(t, text, "scoped to one project")
+}
+
+func TestLoginTool_UnauthorizedKeyNoScopedPrefix(t *testing.T) {
+	api := mockAPI(t, map[string]http.HandlerFunc{
+		"/2025-07-01/cli-auth/validate": func(w http.ResponseWriter, r *http.Request) {
+			w.WriteHeader(http.StatusUnauthorized)
+			_, _ = w.Write([]byte("Unauthorized"))
+		},
+		"/2025-07-01/cli-auth": func(w http.ResponseWriter, r *http.Request) {
+			json.NewEncoder(w).Encode(map[string]any{
+				"browser_url": "https://hookdeck.com/auth?code=revoked",
+				"poll_url":    "http://" + r.Host + "/2025-07-01/cli-auth/poll?key=revoked",
+			})
+		},
+		"/2025-07-01/cli-auth/poll": func(w http.ResponseWriter, r *http.Request) {
+			json.NewEncoder(w).Encode(map[string]any{"claimed": false})
+		},
+	})
+	client := newTestClient(api.URL, "test-key")
+	session := connectInMemory(t, client)
+
+	result := callTool(t, session, "hookdeck_login", map[string]any{})
+	assert.False(t, result.IsError)
+	text := textContent(t, result)
+	assert.Contains(t, text, "Login initiated")
+	assert.NotContains(t, text, "scoped to one project")
+}
+
 func TestLoginTool_ReauthStartsFreshLogin(t *testing.T) {
 	api := mockAPI(t, map[string]http.HandlerFunc{
 		"/2025-07-01/cli-auth": func(w http.ResponseWriter, r *http.Request) {

pkg/gateway/mcp/tool_login.go

@@ -71,9 +71,19 @@ func handleLogin(srv *Server) mcpsdk.ToolHandler {
 			client.ProjectName = ""
 		}
 
-		// Already authenticated — nothing to do.
+		// Already authenticated with a user-associated key — nothing to do.
+		loginPrefix := ""
 		if client.APIKey != "" {
-			return TextResult("Already authenticated. All Hookdeck tools are available."), nil
+			lacks_user, err := project.CredentialsLackUserAssociation(client)
+			if err != nil && !hookdeck.IsUnauthorizedError(err) {
+				return ErrorResult(fmt.Sprintf("Failed to verify credentials: %s", err)), nil
+			}
+			if err == nil && !lacks_user {
+				return TextResult("Already authenticated. All Hookdeck tools are available."), nil
+			}
+			if err == nil && lacks_user {
+				loginPrefix = "Current credentials are scoped to one project; opening browser sign-in for full access.\n\n"
+			}
 		}
 
 		// If a login flow is already in progress, check its status.
@@ -187,7 +197,8 @@ func handleLogin(srv *Server) mcpsdk.ToolHandler {
 
 		// Return the URL immediately so the agent can show it to the user.
 		return TextResult(fmt.Sprintf(
-			"Login initiated. The user must open the following URL in their browser to authenticate:\n\n%s\n\nOnce the user completes authentication in the browser, all Hookdeck tools will become available.\nCall hookdeck_login again to check if authentication has completed.",
+			"%sLogin initiated. The user must open the following URL in their browser to authenticate:\n\n%s\n\nOnce the user completes authentication in the browser, all Hookdeck tools will become available.\nCall hookdeck_login again to check if authentication has completed.",
+			loginPrefix,
 			session.BrowserURL,
 		)), nil
 	}

pkg/gateway/mcp/tool_projects.go

@@ -43,6 +43,10 @@ type projectEntry struct {
 }
 
 func projectsList(client *hookdeck.Client) (*mcpsdk.CallToolResult, error) {
+	if err := project.EnsureUserAssociatedClient(client); err != nil {
+		return ErrorResult(listProjectsFailureMessage(err)), nil
+	}
+
 	projects, err := client.ListProjects()
 	if err != nil {
 		return ErrorResult(listProjectsFailureMessage(err)), nil
@@ -71,6 +75,10 @@ func projectsUse(client *hookdeck.Client, in input) (*mcpsdk.CallToolResult, err
 		return ErrorResult("project_id is required for the use action"), nil
 	}
 
+	if err := project.EnsureUserAssociatedClient(client); err != nil {
+		return ErrorResult(listProjectsFailureMessage(err)), nil
+	}
+
 	projects, err := client.ListProjects()
 	if err != nil {
 		return ErrorResult(listProjectsFailureMessage(err)), nil

pkg/gateway/mcp/tool_projects_errors.go

@@ -6,6 +6,7 @@ import (
 	"strings"
 
 	"github.com/hookdeck/hookdeck-cli/pkg/hookdeck"
+	"github.com/hookdeck/hookdeck-cli/pkg/project"
 )
 
 const listProjectsReauthHint = `This may happen if the stored key is a dashboard or single-project API key that cannot list all teams/projects. Try hookdeck_login with reauth: true so the user can sign in via the browser and replace the credential with a full CLI session, then retry hookdeck_projects.`
@@ -19,11 +20,18 @@ func listProjectsFailureMessage(err error) string {
 }
 
 func shouldSuggestReauthAfterListProjectsFailure(err error) bool {
+	if errors.Is(err, project.ErrProjectScopedCredentials) {
+		return true
+	}
 	var apiErr *hookdeck.APIError
 	if errors.As(err, &apiErr) {
 		if apiErr.StatusCode == http.StatusForbidden || apiErr.StatusCode == http.StatusUnauthorized {
 			return true
 		}
+		msg := strings.ToUpper(apiErr.Message)
+		if strings.Contains(msg, "CLI_PROJECT_SCOPED") || strings.Contains(msg, "CLI_USER_REQUIRED") {
+			return true
+		}
 		return strings.Contains(strings.ToLower(apiErr.Message), "fatal")
 	}
 	// ListProjects wraps some failures as plain fmt.Errorf with the status code

pkg/gateway/mcp/tool_projects_errors_test.go

@@ -5,6 +5,7 @@ import (
 	"testing"
 
 	"github.com/hookdeck/hookdeck-cli/pkg/hookdeck"
+	"github.com/hookdeck/hookdeck-cli/pkg/project"
 	"github.com/stretchr/testify/assert"
 )
 
@@ -14,6 +15,16 @@ func TestShouldSuggestReauthAfterListProjectsFailure(t *testing.T) {
 		err  error
 		want bool
 	}{
+		{
+			name: "project-scoped credentials",
+			err:  project.ErrProjectScopedCredentials,
+			want: true,
+		},
+		{
+			name: "APIError 403 CLI_PROJECT_SCOPED",
+			err:  &hookdeck.APIError{StatusCode: 403, Message: "CLI_PROJECT_SCOPED: cannot list all projects"},
+			want: true,
+		},
 		{
 			name: "APIError 403",
 			err:  &hookdeck.APIError{StatusCode: 403, Message: "not allowed"},