webctx 0.2.9 → 0.2.10

package/AGENTS.md

@@ -48,6 +48,7 @@ Preserve these commands unless the user explicitly asks to change them:
 
 - `webctx search <query> [--exclude domain1,domain2] [--keyword phrase]`
 - `webctx status` and `webctx providers enable|disable <brave|tavily|exa>`
+- `webctx keys list|add|remove` for macOS Keychain-managed additional search keys; `BRAVE_API_KEYS`, `TAVILY_API_KEYS`, and `EXA_API_KEYS` also work via environment variables
 - `webctx read-link <url>`
 - `webctx map-site <url>`
 - `webctx --version`
@@ -55,6 +56,7 @@ Preserve these commands unless the user explicitly asks to change them:
 Behavioral expectations:
 
 - `search` combines enabled Brave, Tavily, and Exa results, then re-ranks them with duplicate-aware scoring; an unavailable Exa can fall back to quoted-phrase Brave/Tavily queries for `--keyword` (not a strict text filter).
+- Search key rotation tries plural credentials first, legacy singular credentials afterward; failover applies only to credential/quota/rate/server/transport failures, never bad requests. Keep Firecrawl paid operations outside this rotation.
 - `read-link` keeps the current GitHub raw-content and `.md` fast paths. Firecrawl uses its built-in 30-minute cache, automatic and enhanced proxies, then browser extraction as a final fallback.
 - `map-site` keeps the current Firecrawl map request settings.
 - The CLI should remain agent-friendly and emit plain markdown/text output.

package/README.md

@@ -115,6 +115,17 @@ webctx providers enable brave
 
 Provider settings persist across runs, independently of environment variables and Keychain credentials. The settings file lives in the OS user config directory (`webctx/config.json`); set `WEBCTX_CONFIG_FILE` to override its location. Disabled providers are never queried. `status` only reports key presence, **not** live credit balances or API health.
 
+Multiple keys per provider are supported. Add extra keys on macOS without placing secrets in command arguments or plaintext config files:
+
+```bash
+webctx keys list                         # count configured and managed keys (never prints them)
+pbpaste | webctx keys add exa --stdin    # securely store a copied new key in macOS Keychain
+webctx keys remove exa 1                # remove the newest Keychain-managed Exa key
+webctx providers enable exa
+```
+
+Or supply `BRAVE_API_KEYS`, `TAVILY_API_KEYS`, or `EXA_API_KEYS` as comma-separated keys (or JSON arrays) in the environment or `.env.local`, alongside the corresponding singular `*_API_KEY`. Keys in the plural list are attempted first, then the legacy single key. On a key-specific authentication, quota/credit, rate-limit, or server error, the next key is tried automatically; invalid requests are not retried. Manage only keys/accounts you are authorized to use and honor each provider's usage restrictions. The Firecrawl/Alexandria integration is separate and **is not included in automatic key rotation**, especially for paid operations.
+
 `--keyword` prefers Exa's strict include-text filter when available. If Exa is disabled, unconfigured, or fails, Brave/Tavily search for the quoted phrase instead; the output explicitly notes that this fallback cannot guarantee the phrase appears in the page text. Firecrawl is a separate reading/site-map/Alexandria integration, not one of these three search providers.
 
 ## Map a site
@@ -145,7 +156,7 @@ FIRECRAWL_API_KEY=...
 GH_TOKEN=...
 ```
 
-- `BRAVE_API_KEY`, `TAVILY_API_KEY`, and `EXA_API_KEY` power normal `search`. Configure any one or more, and optionally disable providers you no longer want to query.
+- `BRAVE_API_KEY`, `TAVILY_API_KEY`, and `EXA_API_KEY` power normal `search`. The plural `*_API_KEYS` names supply additional fallback credentials. Configure any one or more, and optionally disable providers you no longer want to query.
 - `FIRECRAWL_API_KEY` powers `map-site`, page-crawl fallbacks, and Alexandria discovery/inspection/paid execution.
 - `GH_TOKEN` or `GITHUB_TOKEN` is optional. It increases GitHub capacity and unlocks reads such as blame, Discussions, some Actions job logs, private resources the token can access, and richer PR review state.
 

package/internal/app/app.go

@@ -27,6 +27,40 @@ func Run(args []string, stdout, stderr io.Writer) int {
 	}
 
 	tool := args[0]
+	if tool == "keys" {
+		if len(args) == 2 && args[1] == "list" {
+			loadEnvLocal()
+			if err := printProviderStatus(stdout); err != nil {
+				_, _ = fmt.Fprintln(stderr, err)
+				return 1
+			}
+			if err := printManagedSearchKeySlots(stdout); err != nil {
+				_, _ = fmt.Fprintln(stderr, err)
+				return 1
+			}
+			return 0
+		}
+		if len(args) == 4 && args[1] == "add" && args[3] == "--stdin" {
+			count, err := addManagedSearchKey(args[2], os.Stdin)
+			if err != nil {
+				_, _ = fmt.Fprintln(stderr, err)
+				return 1
+			}
+			_, _ = fmt.Fprintf(stdout, "Saved an additional %s API key in macOS Keychain (%d managed key(s)).\n", strings.ToLower(args[2]), count)
+			return 0
+		}
+		if len(args) == 4 && args[1] == "remove" {
+			count, err := removeManagedSearchKey(args[2], args[3])
+			if err != nil {
+				_, _ = fmt.Fprintln(stderr, err)
+				return 1
+			}
+			_, _ = fmt.Fprintf(stdout, "Removed managed %s API key (%d managed key(s) remain).\n", strings.ToLower(args[2]), count)
+			return 0
+		}
+		_, _ = fmt.Fprintln(stderr, "Usage: webctx keys list | keys add <brave|tavily|exa> --stdin | keys remove <provider> <managed-key-index>")
+		return 1
+	}
 	isProviderTool := tool == "status" || tool == "providers" || tool == "provider"
 	isProviderStatus := (tool == "status" && len(args) == 1) ||
 		((tool == "providers" || tool == "provider") && (len(args) == 1 || (len(args) == 2 && args[1] == "status")))
@@ -228,6 +262,9 @@ Usage:
   webctx search <query> [--exclude domain1,domain2] [--keyword phrase]
   webctx status
   webctx providers [status|enable <brave|tavily|exa>|disable <brave|tavily|exa>]
+  webctx keys list
+  webctx keys add <brave|tavily|exa> --stdin
+  webctx keys remove <brave|tavily|exa> <managed-key-index>
   webctx read-link <url> [--question 'what to find']
   webctx map-site <url> [--query topic] [--limit 30] [--offset 0] [--path-prefix /api] [--language en|all]
   webctx research [question] [--view sources|groups|operations] [--sources IDs] [--include inputs,output,examples] [--limit N] [--offset N]
@@ -241,6 +278,7 @@ Examples:
   webctx search "drizzle orm" --keyword "migration guide"
   webctx providers disable exa
   webctx providers enable exa
+  webctx keys add exa --stdin < /path/to/private/key.txt
   webctx research "podcast conversations about AI agents"
   webctx research --view sources --limit 5
   webctx inspect particle/podcasts/episodes/search

package/internal/app/app_test.go

@@ -88,6 +88,9 @@ func TestSearchMissingCredentialsErrorIsHelpful(t *testing.T) {
 	t.Setenv("BRAVE_API_KEY", "")
 	t.Setenv("TAVILY_API_KEY", "")
 	t.Setenv("EXA_API_KEY", "")
+	t.Setenv("BRAVE_API_KEYS", "")
+	t.Setenv("TAVILY_API_KEYS", "")
+	t.Setenv("EXA_API_KEYS", "")
 
 	text, err := Search(SearchParams{Query: "openai api"})
 	if err == nil {
@@ -180,6 +183,9 @@ func TestLoadKeychainEnvLoadsMissingOnly(t *testing.T) {
 	t.Setenv("BRAVE_API_KEY", "already-set")
 	t.Setenv("TAVILY_API_KEY", "")
 	t.Setenv("EXA_API_KEY", "")
+	t.Setenv("BRAVE_API_KEYS", "")
+	t.Setenv("TAVILY_API_KEYS", "")
+	t.Setenv("EXA_API_KEYS", "")
 	t.Setenv("FIRECRAWL_API_KEY", "")
 	t.Setenv("GH_TOKEN", "")
 	t.Setenv("GITHUB_TOKEN", "")

package/internal/app/providers.go

@@ -145,8 +145,12 @@ func printProviderStatus(out io.Writer) error {
 		if !config.enabled(p.name) {
 			state = "disabled"
 		}
-		if strings.TrimSpace(os.Getenv(p.key)) != "" {
+		count := len(searchKeysForProvider(p.name))
+		if count > 0 {
 			key = "key configured"
+			if count > 1 {
+				key = fmt.Sprintf("key configured (%d keys)", count)
+			}
 		}
 		_, _ = fmt.Fprintf(out, "  %-7s %-9s %s\n", p.name, state, key)
 	}

package/internal/app/providers_test.go

@@ -152,6 +152,9 @@ func searchTestEnv(t *testing.T) {
 	t.Setenv("BRAVE_API_KEY", "test-brave")
 	t.Setenv("TAVILY_API_KEY", "test-tavily")
 	t.Setenv("EXA_API_KEY", "test-exa")
+	t.Setenv("BRAVE_API_KEYS", "")
+	t.Setenv("TAVILY_API_KEYS", "")
+	t.Setenv("EXA_API_KEYS", "")
 	t.Setenv("FIRECRAWL_API_KEY", "")
 }
 

package/internal/app/scrape.go

@@ -21,7 +21,7 @@ type MarkdownResult struct {
 const keychainServiceName = "webctx"
 
 var (
-	credentialEnvKeys = []string{"BRAVE_API_KEY", "TAVILY_API_KEY", "EXA_API_KEY", "FIRECRAWL_API_KEY", "GH_TOKEN", "GITHUB_TOKEN"}
+	credentialEnvKeys = []string{"BRAVE_API_KEY", "BRAVE_API_KEYS", "TAVILY_API_KEY", "TAVILY_API_KEYS", "EXA_API_KEY", "EXA_API_KEYS", "FIRECRAWL_API_KEY", "GH_TOKEN", "GITHUB_TOKEN"}
 	getwdFunc         = os.Getwd
 	executableFunc    = os.Executable
 	keychainLookup    = lookupKeychainSecret

package/internal/app/search_keys.go

@@ -0,0 +1,233 @@
+package app
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/url"
+	"os"
+	"os/exec"
+	"runtime"
+	"slices"
+	"strconv"
+	"strings"
+)
+
+// A provider's legacy singular key remains supported. Additional keys are
+// checked first so newly provisioned keys take precedence over exhausted ones.
+// Plural values can be comma/newline-separated or a JSON string array (the
+// latter is how the macOS Keychain stores them).
+func searchKeysForProvider(name string) []string {
+	name = strings.ToLower(strings.TrimSpace(name))
+	if !validSearchProvider(name) {
+		return nil
+	}
+	prefix := strings.ToUpper(name) + "_API_KEY"
+	keys := parseSearchKeyList(os.Getenv(prefix + "S"))
+	if key := strings.TrimSpace(os.Getenv(prefix)); key != "" {
+		keys = append(keys, key)
+	}
+	return uniqueSearchKeys(keys)
+}
+
+func parseSearchKeyList(raw string) []string {
+	raw = strings.TrimSpace(raw)
+	if raw == "" {
+		return nil
+	}
+	if strings.HasPrefix(raw, "[") {
+		var keys []string
+		if json.Unmarshal([]byte(raw), &keys) != nil {
+			return nil // fail closed rather than sending malformed credential data
+		}
+		return uniqueSearchKeys(keys)
+	}
+	return uniqueSearchKeys(strings.FieldsFunc(raw, func(r rune) bool {
+		return r == ',' || r == '\n' || r == '\r'
+	}))
+}
+
+func uniqueSearchKeys(keys []string) []string {
+	seen := make(map[string]bool, len(keys))
+	unique := make([]string, 0, len(keys))
+	for _, key := range keys {
+		key = strings.TrimSpace(key)
+		if key != "" && !seen[key] {
+			seen[key] = true
+			unique = append(unique, key)
+		}
+	}
+	return unique
+}
+
+// Retrying with another key is appropriate for auth, quota, rate-limit, and
+// server/transport failures. Request validation errors or malformed successful
+// responses won't improve with another credential and should not be retried.
+func retryWithNextSearchKey(err error) bool {
+	var status *httpStatusError
+	if errors.As(err, &status) {
+		code := status.Code
+		// Brave Search rejects invalid subscription tokens with HTTP 422,
+		// rather than 401. Only retry that exact provider error code: a
+		// different 422 can indicate a bad query that no key can fix.
+		if code == 422 && strings.Contains(status.Message, "SUBSCRIPTION_TOKEN_INVALID") {
+			return true
+		}
+		return code == 401 || code == 402 || code == 403 || code == 408 || code == 429 || code == 432 || code >= 500
+	}
+	var transport *url.Error
+	return errors.As(err, &transport)
+}
+
+func redactSearchError(err error, keys []string) error {
+	if err == nil {
+		return nil
+	}
+	message := err.Error()
+	for _, key := range keys {
+		if key != "" {
+			message = strings.ReplaceAll(message, key, "[REDACTED]")
+		}
+	}
+	return errors.New(message)
+}
+
+func useSearchKeys(ctx context.Context, name string, attempt func(string) ([]byte, error)) ([]byte, error) {
+	keys := searchKeysForProvider(name)
+	if len(keys) == 0 {
+		return nil, fmt.Errorf("missing %s_API_KEY", strings.ToUpper(name))
+	}
+	var lastErr error
+	for index, key := range keys {
+		if ctx.Err() != nil {
+			return nil, ctx.Err()
+		}
+		body, err := attempt(key)
+		if err == nil {
+			return body, nil
+		}
+		lastErr = redactSearchError(err, keys)
+		if index+1 == len(keys) || !retryWithNextSearchKey(err) {
+			break
+		}
+	}
+	if len(keys) == 1 {
+		return nil, lastErr
+	}
+	return nil, fmt.Errorf("%s: search failed after trying available API keys (up to %d): %w", name, len(keys), lastErr)
+}
+
+var keychainStore = storeKeychainSecret
+
+// Additional keys are stored in one macOS Keychain entry per provider, without
+// exposing secrets in argv, config.json, logs, or CLI output. The security CLI
+// supports a prompt from stdin when -w is the final argument. It prompts for
+// the password twice, even when updating an entry, so feed matching lines.
+func storeKeychainSecret(account, secret string) error {
+	if runtime.GOOS != "darwin" {
+		return errors.New("key management requires macOS Keychain; on other platforms set PROVIDER_API_KEYS in the environment")
+	}
+	cmd := exec.Command("security", "add-generic-password", "-U", "-s", keychainServiceName, "-a", account, "-w")
+	cmd.Stdin = strings.NewReader(secret + "\n" + secret + "\n")
+	if err := cmd.Run(); err != nil {
+		return fmt.Errorf("could not save API keys to macOS Keychain: %w", err)
+	}
+	return nil
+}
+
+func managedKeychainAccount(name string) (string, error) {
+	name = strings.ToLower(strings.TrimSpace(name))
+	if !validSearchProvider(name) {
+		return "", fmt.Errorf("unknown search provider %q (choose brave, tavily, or exa)", name)
+	}
+	return strings.ToUpper(name) + "_API_KEYS", nil
+}
+
+func readManagedKeys(name string) ([]string, error) {
+	account, err := managedKeychainAccount(name)
+	if err != nil {
+		return nil, err
+	}
+	raw, err := keychainLookup(account)
+	if err != nil {
+		return nil, fmt.Errorf("could not read API keys from macOS Keychain: %w", err)
+	}
+	if raw == "" {
+		return nil, nil
+	}
+	var keys []string
+	if err := json.Unmarshal([]byte(raw), &keys); err != nil {
+		return nil, fmt.Errorf("the stored %s key list is not valid JSON; no keys were changed", name)
+	}
+	return uniqueSearchKeys(keys), nil
+}
+
+func writeManagedKeys(name string, keys []string) error {
+	account, err := managedKeychainAccount(name)
+	if err != nil {
+		return err
+	}
+	serialized, err := json.Marshal(uniqueSearchKeys(keys))
+	if err != nil {
+		return err
+	}
+	return keychainStore(account, string(serialized))
+}
+
+func addManagedSearchKey(name string, from io.Reader) (int, error) {
+	if _, err := managedKeychainAccount(name); err != nil {
+		return 0, err
+	}
+	input, err := io.ReadAll(io.LimitReader(from, 4097))
+	if err != nil {
+		return 0, fmt.Errorf("read API key from stdin: %w", err)
+	}
+	key := strings.TrimSpace(string(input))
+	if key == "" || len(input) > 4096 || strings.ContainsAny(key, "\r\n\t ") {
+		return 0, errors.New("API key must be a single nonempty token no longer than 4096 bytes")
+	}
+	keys, err := readManagedKeys(name)
+	if err != nil {
+		return 0, err
+	}
+	if slices.Contains(keys, key) {
+		return len(keys), nil
+	}
+	// Newest keys take priority, so an old exhausted legacy key is never
+	// attempted before a recently added working key.
+	keys = append([]string{key}, keys...)
+	if err := writeManagedKeys(name, keys); err != nil {
+		return 0, err
+	}
+	return len(keys), nil
+}
+
+func removeManagedSearchKey(name, rawIndex string) (int, error) {
+	keys, err := readManagedKeys(name)
+	if err != nil {
+		return 0, err
+	}
+	index, err := strconv.Atoi(rawIndex)
+	if err != nil || index < 1 || index > len(keys) {
+		return 0, fmt.Errorf("key index must be between 1 and %d (managed Keychain keys only)", len(keys))
+	}
+	keys = slices.Delete(keys, index-1, index)
+	if err := writeManagedKeys(name, keys); err != nil {
+		return 0, err
+	}
+	return len(keys), nil
+}
+
+func printManagedSearchKeySlots(out io.Writer) error {
+	_, _ = fmt.Fprintln(out, "\nManaged macOS Keychain keys (numbered newest-first; indexes start at 1):")
+	for _, provider := range searchProviderKeys {
+		keys, err := readManagedKeys(provider.name)
+		if err != nil {
+			return err
+		}
+		_, _ = fmt.Fprintf(out, "  %-7s %d managed\n", provider.name, len(keys))
+	}
+	return nil
+}

package/internal/app/search_keys_test.go

@@ -0,0 +1,227 @@
+package app
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+)
+
+func TestSearchKeyOrderDeduplicationAndMissingKeys(t *testing.T) {
+	t.Setenv("EXA_API_KEYS", ` ["new","new","old"] `)
+	t.Setenv("EXA_API_KEY", "old")
+	if got, want := searchKeysForProvider("exa"), []string{"new", "old"}; !reflect.DeepEqual(got, want) {
+		t.Fatalf("deduplication: got %v, want %v", got, want)
+	}
+	t.Setenv("EXA_API_KEYS", "new,another\n old\n")
+	if got, want := searchKeysForProvider("exa"), []string{"new", "another", "old"}; !reflect.DeepEqual(got, want) {
+		t.Fatalf("CSV/newline parsing: got %v, want %v", got, want)
+	}
+	t.Setenv("EXA_API_KEYS", `[invalid`)
+	t.Setenv("EXA_API_KEY", "")
+	if got := searchKeysForProvider("exa"); len(got) != 0 {
+		t.Fatalf("malformed JSON should not be used as credential: %v", got)
+	}
+	if got := searchKeysForProvider("unknown"); len(got) != 0 {
+		t.Fatalf("unknown provider should have no keys: %v", got)
+	}
+}
+
+func TestStatusReportsMultipleKeysWithoutRevealingThem(t *testing.T) {
+	t.Setenv("WEBCTX_CONFIG_FILE", filepath.Join(t.TempDir(), "webctx", "config.json"))
+	t.Setenv("EXA_API_KEYS", "extra-secret-a,extra-secret-b")
+	t.Setenv("EXA_API_KEY", "legacy-secret")
+	t.Setenv("BRAVE_API_KEY", "")
+	t.Setenv("BRAVE_API_KEYS", "")
+	t.Setenv("TAVILY_API_KEY", "")
+	t.Setenv("TAVILY_API_KEYS", "")
+	t.Setenv("FIRECRAWL_API_KEY", "")
+	var out, errOut bytes.Buffer
+	if code := Run([]string{"status"}, &out, &errOut); code != 0 {
+		t.Fatalf("status error: %s", errOut.String())
+	}
+	if !strings.Contains(out.String(), "exa     enabled   key configured (3 keys)") {
+		t.Fatalf("incorrect key count: %q", out.String())
+	}
+	for _, secret := range []string{"extra-secret-a", "extra-secret-b", "legacy-secret"} {
+		if strings.Contains(out.String()+errOut.String(), secret) {
+			t.Fatal("status exposed a configured API key")
+		}
+	}
+}
+
+func TestManagedSearchKeychainAddRemoveAndInputValidation(t *testing.T) {
+	oldLookup, oldStore := keychainLookup, keychainStore
+	t.Cleanup(func() { keychainLookup, keychainStore = oldLookup, oldStore })
+	managed := map[string]string{}
+	keychainLookup = func(account string) (string, error) { return managed[account], nil }
+	keychainStore = func(account, secret string) error { managed[account] = secret; return nil }
+
+	for _, candidate := range []string{"", "one two", "line1\nline2", strings.Repeat("z", 4097)} {
+		if _, err := addManagedSearchKey("exa", strings.NewReader(candidate)); err == nil {
+			t.Fatalf("invalid secret accepted")
+		}
+	}
+	if len(managed) != 0 {
+		t.Fatal("invalid keys must not modify Keychain")
+	}
+	if _, err := addManagedSearchKey("unknown", strings.NewReader("token")); err == nil {
+		t.Fatal("unknown provider accepted")
+	}
+	for _, pair := range []struct {
+		key   string
+		count int
+	}{{"older", 1}, {"newer", 2}, {"newer", 2}} {
+		count, err := addManagedSearchKey("exa", strings.NewReader(pair.key+"\n"))
+		if err != nil || count != pair.count {
+			t.Fatalf("add: count=%d error=%v", count, err)
+		}
+	}
+	list, err := readManagedKeys("exa")
+	if err != nil || !reflect.DeepEqual(list, []string{"newer", "older"}) {
+		t.Fatalf("priority order changed: %v %v", list, err)
+	}
+	if strings.Contains(managed["EXA_API_KEYS"], "[REDACTED]") {
+		t.Fatal("managed keys stored as placeholder instead of actual tokens")
+	}
+	if _, err := removeManagedSearchKey("exa", "3"); err == nil {
+		t.Fatal("out-of-range removal accepted")
+	}
+	if count, err := removeManagedSearchKey("exa", "1"); err != nil || count != 1 {
+		t.Fatalf("remove: count=%d error=%v", count, err)
+	}
+	if list, err := readManagedKeys("exa"); err != nil || !reflect.DeepEqual(list, []string{"older"}) {
+		t.Fatalf("wrong managed key removed: %v %v", list, err)
+	}
+	managed["EXA_API_KEYS"] = "{invalid"
+	if _, err := addManagedSearchKey("exa", strings.NewReader("another")); err == nil {
+		t.Fatal("malformed Keychain JSON silently overwritten")
+	}
+}
+
+func TestManagedSearchKeyCommandNeverPrintsSecrets(t *testing.T) {
+	oldLookup, oldStore, oldStdin := keychainLookup, keychainStore, os.Stdin
+	t.Cleanup(func() { keychainLookup, keychainStore, os.Stdin = oldLookup, oldStore, oldStdin })
+	keychainLookup = func(account string) (string, error) { return "", nil }
+	keychainStore = func(account, value string) error { return nil }
+	input, writer, err := os.Pipe()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := io.WriteString(writer, "sensitive-api-token\n"); err != nil {
+		t.Fatal(err)
+	}
+	_ = writer.Close()
+	os.Stdin = input
+	var out, errOut bytes.Buffer
+	code := Run([]string{"keys", "add", "exa", "--stdin"}, &out, &errOut)
+	_ = input.Close()
+	if code != 0 || strings.Contains(out.String()+errOut.String(), "sensitive-api-token") {
+		t.Fatalf("unsafe CLI output or command failed: code=%d out=%q err=%q", code, out.String(), errOut.String())
+	}
+}
+
+// Exercise the real HTTP request construction and key-selection order for all
+// three providers, without making network requests or disclosing API keys.
+func TestSearchProviderFallbackAcrossKeys(t *testing.T) {
+	t.Setenv("BRAVE_API_KEY", "legacy-brave")
+	t.Setenv("TAVILY_API_KEY", "legacy-tavily")
+	t.Setenv("EXA_API_KEY", "legacy-exa")
+	for _, name := range []string{"BRAVE", "TAVILY", "EXA"} {
+		t.Setenv(name+"_API_KEYS", "bad-"+strings.ToLower(name)+",good-"+strings.ToLower(name))
+	}
+	previous := http.DefaultClient.Transport
+	requests := map[string][]string{}
+	http.DefaultClient.Transport = roundTripFunc(func(req *http.Request) (*http.Response, error) {
+		provider, key := "", ""
+		switch req.URL.Host {
+		case "api.search.brave.com":
+			provider, key = "brave", req.Header.Get("x-subscription-token")
+		case "api.exa.ai":
+			provider, key = "exa", req.Header.Get("x-api-key")
+		case "api.tavily.com":
+			provider = "tavily"
+			var payload map[string]any
+			_ = json.NewDecoder(req.Body).Decode(&payload)
+			key, _ = payload["api_key"].(string)
+		default:
+			t.Errorf("unexpected host: %s", req.URL.Host)
+		}
+		requests[provider] = append(requests[provider], key)
+		if strings.HasPrefix(key, "bad-") {
+			code := http.StatusUnauthorized
+			switch provider {
+			case "brave":
+				return testHTTPResponse(req, 422, `{"error":{"code":"SUBSCRIPTION_TOKEN_INVALID"}}`, nil), nil
+			case "tavily":
+				code = 432
+			case "exa":
+				code = http.StatusPaymentRequired
+			}
+			return testHTTPResponse(req, code, `{"error":"credits exhausted"}`, nil), nil
+		}
+		if strings.HasPrefix(key, "good-") {
+			switch provider {
+			case "brave":
+				return testHTTPResponse(req, 200, `{"web":{"results":[{"url":"https://example.com/guide","title":"Brave result"}]}}`, nil), nil
+			case "tavily", "exa":
+				return testHTTPResponse(req, 200, `{"results":[{"url":"https://example.com/guide","title":"API result"}]}`, nil), nil
+			}
+		}
+		return testHTTPResponse(req, 500, "unexpected key", nil), nil
+	})
+	t.Cleanup(func() { http.DefaultClient.Transport = previous })
+
+	for _, test := range []struct {
+		provider string
+		call     func() (SearchResult, error)
+	}{
+		{"brave", func() (SearchResult, error) { return searchWithBrave(context.Background(), "test query") }},
+		{"tavily", func() (SearchResult, error) { return searchWithTavily(context.Background(), "test query", nil) }},
+		{"exa", func() (SearchResult, error) {
+			return searchWithExa(context.Background(), "test query", nil, "exact phrase")
+		}},
+	} {
+		results, err := test.call()
+		if err != nil || len(results.Docs) != 1 {
+			t.Fatalf("%s: search failed after key rotation: %v %+v", test.provider, err, results)
+		}
+		want := []string{"bad-" + test.provider, "good-" + test.provider}
+		if got := requests[test.provider]; !reflect.DeepEqual(got, want) {
+			t.Fatalf("%s: key rotation order got %v, want %v", test.provider, got, want)
+		}
+	}
+}
+
+func TestSearchKeyRetryDoesNotMaskBadInputOrLeakKeys(t *testing.T) {
+	t.Setenv("EXA_API_KEYS", "first-secret,second-secret")
+	t.Setenv("EXA_API_KEY", "")
+	previous := http.DefaultClient.Transport
+	count, code := 0, http.StatusBadRequest
+	http.DefaultClient.Transport = roundTripFunc(func(req *http.Request) (*http.Response, error) {
+		count++
+		return testHTTPResponse(req, code, fmt.Sprintf(`{"error":"key %s failed"}`, req.Header.Get("x-api-key")), nil), nil
+	})
+	t.Cleanup(func() { http.DefaultClient.Transport = previous })
+	_, err := searchWithExa(context.Background(), "test", nil, "")
+	if err == nil || count != 1 || strings.Contains(err.Error(), "first-secret") {
+		t.Fatalf("400 should not retry or leak a credential: count=%d error=%v", count, err)
+	}
+	count, code = 0, http.StatusUnprocessableEntity
+	_, err = searchWithExa(context.Background(), "test", nil, "")
+	if err == nil || count != 1 {
+		t.Fatalf("non-credential 422 should not retry: count=%d error=%v", count, err)
+	}
+	count, code = 0, http.StatusTooManyRequests
+	_, err = searchWithExa(context.Background(), "test", nil, "")
+	if err == nil || count != 2 || strings.Contains(err.Error(), "first-secret") || strings.Contains(err.Error(), "second-secret") || !strings.Contains(err.Error(), "up to 2") {
+		t.Fatalf("exhausted-key error is unsafe or not actionable: count=%d error=%v", count, err)
+	}
+}

package/internal/app/tools.go

@@ -72,7 +72,7 @@ func Search(params SearchParams) (string, error) {
 	searches := []namedSearch{}
 	keywordFallback := false
 	if strings.TrimSpace(truncatedKeyword) != "" {
-		if config.enabled("exa") && strings.TrimSpace(os.Getenv("EXA_API_KEY")) != "" {
+		if config.enabled("exa") && len(searchKeysForProvider("exa")) > 0 {
 			searches = append(searches, namedSearch{name: "Exa", fn: func(ctx context.Context) (SearchResult, error) {
 				return searchWithExa(ctx, params.Query, nil, truncatedKeyword)
 			}})
@@ -381,19 +381,17 @@ func missingCredentialsError(prefix string, keys []string, detail string) error
 }
 
 func searchWithBrave(ctx context.Context, query string) (SearchResult, error) {
-	apiKey := strings.TrimSpace(os.Getenv("BRAVE_API_KEY"))
-	if apiKey == "" {
-		return SearchResult{}, errors.New("missing BRAVE_API_KEY")
-	}
 	params := url.Values{}
 	params.Set("q", query)
 	params.Set("text_decorations", "false")
 	params.Set("result_filter", "web")
 	params.Set("limit", "20")
-	body, err := doRawRequest(ctx, http.MethodGet, "https://api.search.brave.com/res/v1/web/search?"+params.Encode(), map[string]string{
-		"Accept":               "application/json",
-		"x-subscription-token": apiKey,
-	}, nil)
+	body, err := useSearchKeys(ctx, "brave", func(apiKey string) ([]byte, error) {
+		return doRawRequest(ctx, http.MethodGet, "https://api.search.brave.com/res/v1/web/search?"+params.Encode(), map[string]string{
+			"Accept":               "application/json",
+			"x-subscription-token": apiKey,
+		}, nil)
+	})
 	if err != nil {
 		return SearchResult{}, err
 	}
@@ -420,22 +418,20 @@ func searchWithBrave(ctx context.Context, query string) (SearchResult, error) {
 }
 
 func searchWithTavily(ctx context.Context, query string, excludeDomains []string) (SearchResult, error) {
-	apiKey := strings.TrimSpace(os.Getenv("TAVILY_API_KEY"))
-	if apiKey == "" {
-		return SearchResult{}, errors.New("missing TAVILY_API_KEY")
-	}
 	requestBody := map[string]any{
-		"api_key":     apiKey,
 		"query":       query,
 		"max_results": 20,
 	}
 	if len(excludeDomains) > 0 {
 		requestBody["exclude_domains"] = excludeDomains
 	}
-	body, err := doJSONRequest(ctx, http.MethodPost, "https://api.tavily.com/search", map[string]string{
-		"Content-Type": "application/json",
-		"Accept":       "application/json",
-	}, requestBody)
+	body, err := useSearchKeys(ctx, "tavily", func(apiKey string) ([]byte, error) {
+		requestBody["api_key"] = apiKey
+		return doJSONRequest(ctx, http.MethodPost, "https://api.tavily.com/search", map[string]string{
+			"Content-Type": "application/json",
+			"Accept":       "application/json",
+		}, requestBody)
+	})
 	if err != nil {
 		return SearchResult{}, err
 	}
@@ -460,10 +456,6 @@ func searchWithTavily(ctx context.Context, query string, excludeDomains []string
 }
 
 func searchWithExa(ctx context.Context, query string, excludeDomains []string, includeKeyword string) (SearchResult, error) {
-	apiKey := strings.TrimSpace(os.Getenv("EXA_API_KEY"))
-	if apiKey == "" {
-		return SearchResult{}, errors.New("missing EXA_API_KEY")
-	}
 	requestBody := map[string]any{
 		"query":      query,
 		"type":       "auto",
@@ -478,11 +470,13 @@ func searchWithExa(ctx context.Context, query string, excludeDomains []string, i
 	if strings.TrimSpace(includeKeyword) != "" {
 		requestBody["includeText"] = []string{includeKeyword}
 	}
-	body, err := doJSONRequest(ctx, http.MethodPost, "https://api.exa.ai/search", map[string]string{
-		"Accept":       "application/json",
-		"Content-Type": "application/json",
-		"x-api-key":    apiKey,
-	}, requestBody)
+	body, err := useSearchKeys(ctx, "exa", func(apiKey string) ([]byte, error) {
+		return doJSONRequest(ctx, http.MethodPost, "https://api.exa.ai/search", map[string]string{
+			"Accept":       "application/json",
+			"Content-Type": "application/json",
+			"x-api-key":    apiKey,
+		}, requestBody)
+	})
 	if err != nil {
 		return SearchResult{}, err
 	}
@@ -684,13 +678,20 @@ func doRawRequest(ctx context.Context, method, rawURL string, headers map[string
 	}
 	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
 		if len(respBody) > 0 {
-			return nil, fmt.Errorf("API request failed: %s - %s", resp.Status, strings.TrimSpace(string(respBody)))
+			return nil, &httpStatusError{Code: resp.StatusCode, Message: fmt.Sprintf("API request failed: %s - %s", resp.Status, strings.TrimSpace(string(respBody)))}
 		}
-		return nil, fmt.Errorf("API request failed: %s", resp.Status)
+		return nil, &httpStatusError{Code: resp.StatusCode, Message: "API request failed: " + resp.Status}
 	}
 	return respBody, nil
 }
 
+type httpStatusError struct {
+	Code    int
+	Message string
+}
+
+func (e *httpStatusError) Error() string { return e.Message }
+
 func stringValue(v any) string {
 	if s, ok := v.(string); ok {
 		return s

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webctx",
-  "version": "0.2.9",
+  "version": "0.2.10",
   "description": "Go CLI for agent-friendly web research, structured-data discovery, and source-native querying",
   "license": "MIT",
   "author": "amxv",