fix(api): POST /v1/search names unknown providers instead of opaque 400 (#10849)

[diegosouzapw]

Closes #10849

Root cause

v1SearchSchema.provider (src/shared/validation/schemas/apiV1.ts) was a hard-coded z.enum([...17 catalog ids]). Any provider id outside that literal list (e.g. grok, or short aliases like brave/serper) failed Zod validation inside validateBody() before the route's own, better-designed check (resolveSearchProvider() in open-sse/config/searchRegistry.ts) ever ran. validateBody() also always hard-codes message: "Invalid request" on failure, with the real Zod issue only in details[] — but route.ts was building the 400 response from validation.error.message alone, dropping details and hiding which field/value actually failed.

Downstream, resolveSearchProvider() already returns null for unknown ids and the route already replies Unknown search provider: <id> — but that branch was unreachable for anything outside the enum. Additionally, SEARCH_PROVIDER_ALIASES only mapped jina-ai/jina → jina-search; no short aliases existed for the other providers (brave → brave-search, etc.), so even after relaxing the enum those ids would still fail with an unnamed error.

Fix

• src/shared/validation/schemas/apiV1.ts: v1SearchSchema.provider is now z.string().min(1).optional() (documented with a comment listing the known catalog ids) instead of a hard-coded enum, so resolveSearchProvider() is the single runtime source of truth for provider validity.
• open-sse/config/searchRegistry.ts: extended SEARCH_PROVIDER_ALIASES with short-form aliases mirroring the existing jina/jina-ai pattern — brave, serper, perplexity, exa, tavily, google-pse, linkup, ollama, searchapi, youcom, searxng, zai, duckduckgo.
• src/shared/validation/helpers.ts: added formatValidationMessage(), which builds a "<field>: <message>" string from the first Zod issue instead of the generic "Invalid request", for routes (like /v1/search) that reply with a single message string via errorResponse().
• src/app/api/v1/search/route.ts: uses formatValidationMessage() when schema validation fails, so a genuinely bad field (e.g. search_type: "bogus") also gets a named message instead of an opaque one.
• Aligned two existing tests (tests/unit/firecrawl-search.test.ts, tests/unit/search-registry.test.ts) that encoded the old (buggy) schema-level-rejection contract — they now assert the corrected contract: the schema accepts any non-empty string, and resolveSearchProvider() is the runtime gate for unknown/legacy ids.

Regression test (TDD)

tests/unit/search-provider-opaque-400-10849.test.ts — reproduces the bug against the unfixed code (confirmed RED: both provider: "grok" and provider: "brave" returned the opaque "Invalid request" message), then confirms GREEN after the fix:

• unknown provider id → Unknown search provider: grok
• short alias brave → resolves like the existing jina aliases (no opaque 400)
• a genuinely invalid field (search_type: "bogus") → field-named message, not opaque

Run: node --import tsx/esm --test tests/unit/search-provider-opaque-400-10849.test.ts → 3/3 passing.

Validation

• npm run typecheck:core — clean
• node scripts/check/check-complexity.mjs / check-cognitive-complexity.mjs / check-file-size.mjs — all OK (no regression vs baseline)
• node scripts/check/check-changelog-integrity.mjs — OK
• npx eslint --suppressions-location config/quality/eslint-suppressions.json <changed files> — clean
• Sibling test files exercising the touched schema/route/registry: tests/unit/search-route.test.ts, tests/unit/search-registry.test.ts, tests/unit/firecrawl-search.test.ts, tests/unit/jina-complete-provider.test.ts, tests/unit/9201-search-proxy-bypass.test.ts — all passing after the fix (2 pre-existing schema-level assertions updated to the corrected contract, see above)
• tests/unit/hard-session-lease-bypass-inventory.test.ts fails on this branch, but the failure is unrelated pre-existing drift: git diff origin/release/v3.8.50 -- tests/unit/hard-session-lease-bypass-inventory.test.ts is empty (the test file is untouched by this PR) and the src/app/api/v1/search/route.ts call-site count in the failing assertion is identical (2) between actual and expected — the mismatch is entirely in unrelated routes (classify, images/edits, segment, videos/generations, geminiWeb).

⚠️ base-red inherited: #9985