fix(web-search): assess the bridge search endpoint as a destination (#4519)

src/config.ts

@@ -507,9 +507,15 @@ export function requestPacingConfigError(value: unknown): string | null {
 /**
  * Bounds for the opt-in passthrough web-search bridge (`providers.<name>.webSearchBridge`,
  * #3761). Strict for the same reason `retryOn429` is: a misspelled key here would silently
- * leave the bridge disarmed while the operator believes they enabled it. `endpoint` is only
- * shape-checked here; `planPassthroughWebSearchBridge` re-validates the origin before any key
- * is sent to it, because config validation is not an authorization boundary.
+ * leave the bridge disarmed while the operator believes they enabled it.
+ *
+ * `endpoint` names the destination that receives this provider's API key, so it gets the same
+ * literal destination assessment `baseUrl` gets (#4519) — see `providerWebSearchBridgeConfigError`
+ * below. This schema itself still only shape-checks: it is `.catch(undefined)` at the provider
+ * row, and a hand-edited config file never reaches the error function at all. The authorization
+ * boundary is therefore `resolveOllamaWebSearchEndpoint`, which runs the same assessment and is
+ * the only reader of this field in the tree; config validation is where an operator is told why,
+ * not what makes the value safe.
  */
 const providerWebSearchBridgeSchema = z.object({
   enabled: z.boolean().optional(),
@@ -519,7 +525,11 @@ const providerWebSearchBridgeSchema = z.object({
   endpoint: z.string().min(1).optional(),
 }).strict();
 
-export function providerWebSearchBridgeConfigError(value: unknown): string | null {
+export function providerWebSearchBridgeConfigError(
+  value: unknown,
+  providerName: string,
+  provider: Pick<OcxProviderConfig, "allowPrivateNetwork">,
+): string | null {
   if (value === undefined) return null;
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     return "webSearchBridge must be a plain object";
@@ -541,6 +551,17 @@ export function providerWebSearchBridgeConfigError(value: unknown): string | nul
     if (url.protocol !== "https:" && url.protocol !== "http:") {
       return "webSearchBridge.endpoint must be an absolute http(s) URL";
     }
+    // Same classifier baseUrl uses, so a metadata address is refused outright and loopback or
+    // private space needs the provider's allowPrivateNetwork opt-in (or a registry entry that is
+    // local by definition, which is what keeps a self-hosted Ollama working). Literal-only and
+    // synchronous, exactly as at the baseUrl boundary: no DNS is resolved here.
+    const destinationError = providerDestinationConfigError(providerName, {
+      baseUrl: endpoint,
+      allowPrivateNetwork: provider.allowPrivateNetwork,
+    });
+    if (destinationError) {
+      return destinationError.replace(/^baseUrl/, "webSearchBridge.endpoint");
+    }
   }
   return null;
 }

src/server/auth-cors.ts

@@ -766,7 +766,7 @@ export function providerManagementConfigError(
   if (requestPacingError) {
     return `provider ${JSON.stringify(redactSecretString(name))} ${requestPacingError}`;
   }
-  const webSearchBridgeError = providerWebSearchBridgeConfigError(raw.webSearchBridge);
+  const webSearchBridgeError = providerWebSearchBridgeConfigError(raw.webSearchBridge, name, typed);
   if (webSearchBridgeError) {
     return `provider ${JSON.stringify(redactSecretString(name))} ${webSearchBridgeError}`;
   }

src/server/responses/core.ts

@@ -6251,6 +6251,7 @@ async function handleResponsesInner(
         openAiSidecar,
       );
       const webSearchBridgePlan = planPassthroughWebSearchBridge(parsed, route.provider, {
+        providerName: route.providerName,
         isPassthrough: true,
         stream: parsed.stream === true,
         auth: webSearchBridgeAuth,

src/web-search/passthrough-bridge.ts

@@ -64,11 +64,53 @@ import {
   resolveSidecarBackend,
   xaiSearchOptionsFromConfig,
 } from "./sidecar-providers";
+import { providerDestinationConfigError } from "../lib/destination-policy";
+import { redactSecretString } from "../lib/redact";
 
 /** Canonical Ollama Cloud origin. The only origin the "ollama" backend derives on its own. */
 export const OLLAMA_CLOUD_ORIGIN = "https://ollama.com";
 const OLLAMA_WEB_SEARCH_PATH = "/api/web_search";
 
+/**
+ * Providers already warned about a destination-refused bridge endpoint. The planner runs per
+ * request, so without this a refused endpoint would warn on every turn. Keyed on provider plus
+ * endpoint so that editing the config warns again; the key itself is never logged.
+ */
+const warnedRefusedBridgeEndpoints = new Set<string>();
+/** Bound the dedupe set so a pathological config cannot grow it without limit. */
+const MAX_WARNED_REFUSED_ENDPOINTS = 64;
+
+/**
+ * A refused endpoint disarms the bridge, and the refusal itself has to stay silent at the point of
+ * use -- returning undefined is what keeps the key unspent. But silence alone made a real
+ * configuration fail invisibly: a provider keyed under a CUSTOM name (say "my-ollama") pointing at
+ * a loopback endpoint used to arm, and the destination policy now refuses it because only the
+ * registry ids are local by default. The config file never reaches
+ * "providerWebSearchBridgeConfigError", so nothing else would tell the operator. One warning per
+ * provider and endpoint gives them the remedy without leaking the destination: the URL is
+ * deliberately omitted and the provider name is redacted, because a provider key is
+ * caller-controlled and can be token-shaped.
+ */
+function warnRefusedBridgeEndpointOnce(providerName: string, endpoint: string): void {
+  const key = providerName + "\u0000" + endpoint;
+  if (warnedRefusedBridgeEndpoints.has(key)) return;
+  if (warnedRefusedBridgeEndpoints.size >= MAX_WARNED_REFUSED_ENDPOINTS) {
+    warnedRefusedBridgeEndpoints.clear();
+  }
+  warnedRefusedBridgeEndpoints.add(key);
+  console.warn(
+    "[web-search] provider " + JSON.stringify(redactSecretString(providerName))
+    + " webSearchBridge.endpoint was refused by destination policy, so the bridge stays disarmed."
+    + " Set allowPrivateNetwork:true for an intentionally local endpoint, or key the provider under"
+    + " its registry id (ollama, vllm, lm-studio, litellm).",
+  );
+}
+
+/** Test seam: the dedupe is process-wide, so a test that asserts the warning must reset it. */
+export function resetRefusedBridgeEndpointWarningsForTests(): void {
+  warnedRefusedBridgeEndpoints.clear();
+}
+
 const DEFAULT_BRIDGE_MAX_SEARCHES = 3;
 const DEFAULT_BRIDGE_TIMEOUT_MS = 60_000;
 /** Queries honored from one call's "queries" array; the rest are ignored rather than billed. */
@@ -123,13 +165,33 @@ function originOf(value: string | undefined): string | undefined {
  * that receives this provider's API key. Without one, the origin must be canonical Ollama Cloud
  * -- a renamed row pointing at an arbitrary host must not silently receive the key just because
  * its adapter happens to be openai-responses.
+ *
+ * Naming a destination is not the same as it being an allowed one. The endpoint therefore gets the
+ * same literal destination assessment "baseUrl" already gets (#4519): metadata addresses are
+ * refused outright, and loopback/private need the provider's "allowPrivateNetwork" opt-in or a
+ * registry entry that is local by definition, so a local Ollama on 127.0.0.1 keeps working. This
+ * is the ONLY reader of "webSearchBridge.endpoint" in the tree, which is what lets it act as the
+ * authorization boundary for a config file the operator edited by hand -- that path never reaches
+ * "providerWebSearchBridgeConfigError", so a value that survives file load simply cannot be spent.
+ * The refusal returns undefined rather than an error, because disarming is what keeps the key
+ * unspent -- but it is not silent: see warnRefusedBridgeEndpointOnce for why a custom-named local
+ * provider has to be told, once, that its endpoint was refused and how to re-authorize it.
  */
 export function resolveOllamaWebSearchEndpoint(
+  providerName: string,
   provider: OcxProviderConfig,
 ): string | undefined {
   const configured = provider.webSearchBridge?.endpoint;
   if (configured !== undefined) {
-    return originOf(configured) === undefined ? undefined : configured;
+    if (originOf(configured) === undefined) return undefined;
+    if (providerDestinationConfigError(providerName, {
+      baseUrl: configured,
+      allowPrivateNetwork: provider.allowPrivateNetwork,
+    })) {
+      warnRefusedBridgeEndpointOnce(providerName, configured);
+      return undefined;
+    }
+    return configured;
   }
   return originOf(provider.baseUrl) === OLLAMA_CLOUD_ORIGIN
     ? OLLAMA_CLOUD_ORIGIN + OLLAMA_WEB_SEARCH_PATH
@@ -211,6 +273,12 @@ export function planPassthroughWebSearchBridge(
   parsed: OcxParsedRequest,
   provider: OcxProviderConfig,
   options: {
+    /**
+     * Registry key for this provider. Required rather than optional: the destination assessment
+     * consults the registry's local-by-default entries, and an absent name would silently pick a
+     * different answer than the operator configured.
+     */
+    providerName: string;
     isPassthrough: boolean;
     stream: boolean;
     auth?: PassthroughWebSearchBridgeAuth;
@@ -239,7 +307,7 @@ export function planPassthroughWebSearchBridge(
     ? bridge.timeoutMs!
     : DEFAULT_BRIDGE_TIMEOUT_MS;
   if (backend === "ollama") {
-    const endpoint = resolveOllamaWebSearchEndpoint(provider);
+    const endpoint = resolveOllamaWebSearchEndpoint(options.providerName, provider);
     if (!endpoint) return undefined;
     return { backend, endpoint, maxSearches, timeoutMs };
   }

structure/runtime.md

@@ -261,6 +261,25 @@ value import of the barrel; the barrel re-exports it.
 `tests/web-search/web-search-passthrough-bridge.test.ts` covers the mismatch and matching cases for
 anthropic, xai, and gemini, plus the unset-backend default.
 
+`providers.<name>.webSearchBridge.endpoint` names the destination that receives that provider's own
+API key, so it carries the same literal destination assessment as `baseUrl`:
+`providerDestinationConfigError` runs both at management write time, inside
+`providerWebSearchBridgeConfigError`, and at plan time inside `resolveOllamaWebSearchEndpoint`.
+Metadata destinations are refused unconditionally; loopback, localhost, and private space need the
+provider's `allowPrivateNetwork` opt-in or a registry entry that is local by default, which is what
+keeps a self-hosted Ollama on `127.0.0.1` working. Both checks are synchronous and literal-only and
+resolve no DNS, so a hostname that resolves into metadata or private space is a disclosed residual
+rather than a blocked case. That residual is strictly larger than `baseUrl`'s: `baseUrl` also runs
+the async `providerDestinationResolvedError` at management write, which the endpoint does not, and
+parity there would still leave the hand-edited-file path uncovered because the plan-time boundary is
+synchronous. The plan-time check is the
+authorization boundary rather than a second opinion: a hand-edited config file, `ocx config set`,
+and `ocx config import` all reach `configSchema` only and never call
+`providerWebSearchBridgeConfigError`, and `resolveOllamaWebSearchEndpoint` is the only reader of
+this field in the tree, so a value that survives file load still cannot be spent. It refuses
+silently by design; config-time is where the operator is told why. The planner requires the
+provider name for that assessment, so `planPassthroughWebSearchBridge` takes it explicitly.
+
 ## Remote Hub hardening ownership
 
 `src/remote/protocol.ts` owns pure interval/feature negotiation. `src/remote/hub-state.ts` owns the `GET|HEAD /v1/hub-state` contract, its caps, and the parser both sides share. `src/client/hub-client.ts` owns bounded, schema-validated remote catalog consumption, hub-state reads, and key-id probes; `src/client/hub-state.ts` owns the resolution and the owner-stamped 0600 cache, and a failed read reports "unavailable" rather than degrading to the client's own local provider and login state. `src/client/hub-relay.ts` is a fixed-authority management relay with URL, header, body, redirect, and stream bounds. The public data listener remains the direct client→hub path; the loopback management ingress never serves data-plane routes.