@omnicross/core 0.1.10 → 0.2.1

package/dist/completion.cjs

@@ -9,82 +9,86 @@
 
 
 
-var _chunkTIT74RILcjs = require('./chunk-TIT74RIL.cjs');
+var _chunkVSYQ6XYNcjs = require('./chunk-VSYQ6XYN.cjs');
+require('./chunk-E4QHVXV5.cjs');
 require('./chunk-HQP3K7PU.cjs');
 require('./chunk-QVOB2DNX.cjs');
-require('./chunk-P7EM6BND.cjs');
-require('./chunk-ZQQUD66M.cjs');
-require('./chunk-5LNYGCIW.cjs');
-require('./chunk-CMVXX7ON.cjs');
+require('./chunk-7ZHBN75N.cjs');
+require('./chunk-GBHYAGX3.cjs');
+require('./chunk-3OPYJG76.cjs');
+require('./chunk-ZAPN7XA6.cjs');
+require('./chunk-KIQ2HA2A.cjs');
+require('./chunk-NOITAVHA.cjs');
+require('./chunk-QWNUOR7F.cjs');
+require('./chunk-POUTD5AM.cjs');
+require('./chunk-6DDYNS2B.cjs');
 require('./chunk-5RSZYQJH.cjs');
-require('./chunk-56QD3YW6.cjs');
-require('./chunk-QUSEZNYS.cjs');
+require('./chunk-32SRZFFP.cjs');
 require('./chunk-2E42SAW3.cjs');
 require('./chunk-5UK3KLE2.cjs');
-require('./chunk-IIRPUVPH.cjs');
-require('./chunk-GBHYAGX3.cjs');
-require('./chunk-3OPYJG76.cjs');
-require('./chunk-3SCOLIPT.cjs');
+require('./chunk-MXI2PWIC.cjs');
 require('./chunk-RPII3E6Z.cjs');
 require('./chunk-6RPZADX3.cjs');
 require('./chunk-J3QQ6JS5.cjs');
 require('./chunk-UIBD2YY5.cjs');
 require('./chunk-R3HK6R4B.cjs');
+require('./chunk-KQBLZMP6.cjs');
+
+
+var _chunkOIKREZVQcjs = require('./chunk-OIKREZVQ.cjs');
 require('./chunk-QXD4MV2X.cjs');
 require('./chunk-NYUNU75A.cjs');
 require('./chunk-OTZC4TNH.cjs');
-require('./chunk-YWL7YZWS.cjs');
+require('./chunk-7LRTPNFL.cjs');
 require('./chunk-YNJNTCSQ.cjs');
 require('./chunk-SVNDB62D.cjs');
 require('./chunk-6QQG7YG3.cjs');
 require('./chunk-25GXJCEZ.cjs');
-require('./chunk-MUHWHQVM.cjs');
-
-
-var _chunkQ27JY5RGcjs = require('./chunk-Q27JY5RG.cjs');
+require('./chunk-FX325I5Q.cjs');
+require('./chunk-AEOZIDEB.cjs');
+require('./chunk-HCOQQAZE.cjs');
 require('./chunk-APYG5QD7.cjs');
 require('./chunk-L74VDN4A.cjs');
+require('./chunk-XSVNC2UD.cjs');
 require('./chunk-4YINUUKQ.cjs');
-require('./chunk-4VZX5F4T.cjs');
+require('./chunk-T6NWPIYZ.cjs');
 require('./chunk-QBZJ7P2T.cjs');
 require('./chunk-4IH4EL7M.cjs');
 
 
 
 
+var _chunkJMJBSACDcjs = require('./chunk-JMJBSACD.cjs');
 
 
+var _chunkGMMT7RVNcjs = require('./chunk-GMMT7RVN.cjs');
+require('./chunk-UNEFIWXI.cjs');
 
 
 
 
-var _chunkA2YMUCBTcjs = require('./chunk-A2YMUCBT.cjs');
-require('./chunk-UWDW6PN3.cjs');
-require('./chunk-FCR77GYM.cjs');
-require('./chunk-AEOZIDEB.cjs');
-require('./chunk-XSVNC2UD.cjs');
-require('./chunk-GDIXXKF2.cjs');
-require('./chunk-OC6DOOFX.cjs');
-require('./chunk-RICPANBY.cjs');
-require('./chunk-77USGNRW.cjs');
-require('./chunk-AOFWNWLT.cjs');
-require('./chunk-RJUONLUQ.cjs');
-require('./chunk-235MXAGX.cjs');
-require('./chunk-HVBBDBS3.cjs');
-require('./chunk-NKVZ6Z3Y.cjs');
 
 
 
-var _chunkNZYN7C3Pcjs = require('./chunk-NZYN7C3P.cjs');
 
 
 
+var _chunkA2YMUCBTcjs = require('./chunk-A2YMUCBT.cjs');
+require('./chunk-GDIXXKF2.cjs');
+require('./chunk-VXRTQZF2.cjs');
+require('./chunk-WX2E2G7H.cjs');
+require('./chunk-77USGNRW.cjs');
+require('./chunk-IUL4VWNU.cjs');
+require('./chunk-4Z3ZLLC2.cjs');
+require('./chunk-235MXAGX.cjs');
+require('./chunk-HVBBDBS3.cjs');
+require('./chunk-NKVZ6Z3Y.cjs');
+require('./chunk-UPQIWJIE.cjs');
+require('./chunk-G4CZIUIB.cjs');
 
-var _chunkJMJBSACDcjs = require('./chunk-JMJBSACD.cjs');
 
 
-var _chunkGMMT7RVNcjs = require('./chunk-GMMT7RVN.cjs');
-require('./chunk-UNEFIWXI.cjs');
+var _chunkMPXOKQJPcjs = require('./chunk-MPXOKQJP.cjs');
 
 
 
@@ -112,4 +116,4 @@ require('./chunk-UNEFIWXI.cjs');
 
 
 
-exports.BuiltinToolExecutor = _chunkNZYN7C3Pcjs.BuiltinToolExecutor; exports.CompletionService = _chunkTIT74RILcjs.CompletionService; exports.NATIVE_SEARCH_TOOL_NAMES = _chunkGMMT7RVNcjs.NATIVE_SEARCH_TOOL_NAMES; exports.addOpenRouterProviderToRequest = _chunkTIT74RILcjs.addOpenRouterProviderToRequest; exports.applyAugmentation = _chunkJMJBSACDcjs.applyAugmentation; exports.attachStreamEventBuffer = _chunkTIT74RILcjs.attach; exports.buildAnthropicApiUrl = _chunkA2YMUCBTcjs.buildAnthropicApiUrl; exports.buildAzureOpenAIApiUrl = _chunkA2YMUCBTcjs.buildAzureOpenAIApiUrl; exports.buildGeminiApiUrl = _chunkA2YMUCBTcjs.buildGeminiApiUrl; exports.buildNativeSearchAugmentation = _chunkJMJBSACDcjs.buildNativeSearchAugmentation; exports.buildOpenAIApiUrl = _chunkA2YMUCBTcjs.buildOpenAIApiUrl; exports.buildOpenAIResponseApiUrl = _chunkA2YMUCBTcjs.buildOpenAIResponseApiUrl; exports.buildProviderApiUrl = _chunkA2YMUCBTcjs.buildProviderApiUrl; exports.convertMessageToAnthropic = _chunkTIT74RILcjs.convertMessageToAnthropic; exports.convertMessageToGemini = _chunkTIT74RILcjs.convertMessageToGemini; exports.convertMessageToOpenAI = _chunkTIT74RILcjs.convertMessageToOpenAI; exports.detectNativeSearch = _chunkJMJBSACDcjs.detectNativeSearch; exports.emitStreamEvent = _chunkTIT74RILcjs.emit; exports.getBuiltinSearchTools = _chunkNZYN7C3Pcjs.getBuiltinSearchTools; exports.getOpenRouterProviderConfig = _chunkTIT74RILcjs.getOpenRouterProviderConfig; exports.getProviderHeaders = _chunkQ27JY5RGcjs.getProviderHeaders; exports.normalizeAzureEndpoint = _chunkA2YMUCBTcjs.normalizeAzureEndpoint; exports.registerStreamEventBuffer = _chunkTIT74RILcjs.register; exports.releaseStreamEventBuffer = _chunkTIT74RILcjs.release; exports.resolveApiFormat = _chunkA2YMUCBTcjs.resolveApiFormat; exports.resolveProviderEndpoint = _chunkA2YMUCBTcjs.resolveProviderEndpoint;
+exports.BuiltinToolExecutor = _chunkMPXOKQJPcjs.BuiltinToolExecutor; exports.CompletionService = _chunkVSYQ6XYNcjs.CompletionService; exports.NATIVE_SEARCH_TOOL_NAMES = _chunkGMMT7RVNcjs.NATIVE_SEARCH_TOOL_NAMES; exports.addOpenRouterProviderToRequest = _chunkVSYQ6XYNcjs.addOpenRouterProviderToRequest; exports.applyAugmentation = _chunkJMJBSACDcjs.applyAugmentation; exports.attachStreamEventBuffer = _chunkVSYQ6XYNcjs.attach; exports.buildAnthropicApiUrl = _chunkA2YMUCBTcjs.buildAnthropicApiUrl; exports.buildAzureOpenAIApiUrl = _chunkA2YMUCBTcjs.buildAzureOpenAIApiUrl; exports.buildGeminiApiUrl = _chunkA2YMUCBTcjs.buildGeminiApiUrl; exports.buildNativeSearchAugmentation = _chunkJMJBSACDcjs.buildNativeSearchAugmentation; exports.buildOpenAIApiUrl = _chunkA2YMUCBTcjs.buildOpenAIApiUrl; exports.buildOpenAIResponseApiUrl = _chunkA2YMUCBTcjs.buildOpenAIResponseApiUrl; exports.buildProviderApiUrl = _chunkA2YMUCBTcjs.buildProviderApiUrl; exports.convertMessageToAnthropic = _chunkVSYQ6XYNcjs.convertMessageToAnthropic; exports.convertMessageToGemini = _chunkVSYQ6XYNcjs.convertMessageToGemini; exports.convertMessageToOpenAI = _chunkVSYQ6XYNcjs.convertMessageToOpenAI; exports.detectNativeSearch = _chunkJMJBSACDcjs.detectNativeSearch; exports.emitStreamEvent = _chunkVSYQ6XYNcjs.emit; exports.getBuiltinSearchTools = _chunkMPXOKQJPcjs.getBuiltinSearchTools; exports.getOpenRouterProviderConfig = _chunkVSYQ6XYNcjs.getOpenRouterProviderConfig; exports.getProviderHeaders = _chunkOIKREZVQcjs.getProviderHeaders; exports.normalizeAzureEndpoint = _chunkA2YMUCBTcjs.normalizeAzureEndpoint; exports.registerStreamEventBuffer = _chunkVSYQ6XYNcjs.register; exports.releaseStreamEventBuffer = _chunkVSYQ6XYNcjs.release; exports.resolveApiFormat = _chunkA2YMUCBTcjs.resolveApiFormat; exports.resolveProviderEndpoint = _chunkA2YMUCBTcjs.resolveProviderEndpoint;

package/dist/completion.d.cts

@@ -1,9 +1,9 @@
 export { A as ApiFormat, C as CompletionOptions, a as CompletionResult, N as NATIVE_SEARCH_TOOL_NAMES, b as NativeSearchAugmentation, c as NativeSearchDetectionResult, d as NativeSearchProvider, e as NativeSearchUserConfig, S as StreamCallbacks } from './types-BScIHmPr.cjs';
-export { C as CompletionService, V as VisionFallbackProvider } from './CompletionService-kNA17cfI.cjs';
+export { C as CompletionService, V as VisionFallbackProvider } from './CompletionService-BniP7j88.cjs';
 export { buildAnthropicApiUrl, buildAzureOpenAIApiUrl, buildGeminiApiUrl, buildOpenAIApiUrl, buildOpenAIResponseApiUrl, buildProviderApiUrl, normalizeAzureEndpoint, resolveApiFormat, resolveProviderEndpoint } from './completion/url-builder.cjs';
 import { LLMProvider, OpenRouterProviderRouting } from '@omnicross/contracts/llm-config';
 import { SimpleChatMessage, AnthropicMessage, OpenAIMessage } from '@omnicross/contracts/completion-types';
-export { B as BuiltinToolExecutor, g as getBuiltinSearchTools } from './BuiltinToolExecutor-CS2WpXhM.cjs';
+export { B as BuiltinToolExecutor, g as getBuiltinSearchTools } from './BuiltinToolExecutor-BHgH-EaZ.cjs';
 export { applyAugmentation, buildNativeSearchAugmentation, detectNativeSearch } from './completion/NativeSearchInjector.cjs';
 import '@omnicross/contracts/message-blocks';
 import './usage-event-sink-BX7FE1NL.cjs';
@@ -11,7 +11,7 @@ import './logger-4GvQNzhE.cjs';
 import './ports/provider-config-source.cjs';
 import './transformer/types.cjs';
 import './transformer/TransformerService.cjs';
-import './provider-proxy/types.cjs';
+import './types-BSIJdsyl.cjs';
 import 'node:http';
 import '@omnicross/contracts/usage-stats-types';
 import '@omnicross/contracts/subscription-types';
@@ -23,6 +23,10 @@ import './pipeline/SubscriptionAuthSource.cjs';
 import './pipeline/SubscriptionAuthStrategy.cjs';
 import './ports/web-search-backend.cjs';
 import '@omnicross/contracts/websearch-types';
+import './frontends-Doz0RaWu.cjs';
+import '@omnicross/contracts/search-types';
+import './runtime-t8AZacFF.cjs';
+import '@omnicross/contracts/image-generation-types';
 import '@omnicross/contracts/mcp-types';
 import '@omnicross/contracts/endpoint-resolver';
 

package/dist/completion.d.ts

@@ -1,9 +1,9 @@
 export { A as ApiFormat, C as CompletionOptions, a as CompletionResult, N as NATIVE_SEARCH_TOOL_NAMES, b as NativeSearchAugmentation, c as NativeSearchDetectionResult, d as NativeSearchProvider, e as NativeSearchUserConfig, S as StreamCallbacks } from './types-BScIHmPr.js';
-export { C as CompletionService, V as VisionFallbackProvider } from './CompletionService-C3BX0Ovy.js';
+export { C as CompletionService, V as VisionFallbackProvider } from './CompletionService-BqrKPwfA.js';
 export { buildAnthropicApiUrl, buildAzureOpenAIApiUrl, buildGeminiApiUrl, buildOpenAIApiUrl, buildOpenAIResponseApiUrl, buildProviderApiUrl, normalizeAzureEndpoint, resolveApiFormat, resolveProviderEndpoint } from './completion/url-builder.js';
 import { LLMProvider, OpenRouterProviderRouting } from '@omnicross/contracts/llm-config';
 import { SimpleChatMessage, AnthropicMessage, OpenAIMessage } from '@omnicross/contracts/completion-types';
-export { B as BuiltinToolExecutor, g as getBuiltinSearchTools } from './BuiltinToolExecutor-BluWyeob.js';
+export { B as BuiltinToolExecutor, g as getBuiltinSearchTools } from './BuiltinToolExecutor-Bi1LmiTP.js';
 export { applyAugmentation, buildNativeSearchAugmentation, detectNativeSearch } from './completion/NativeSearchInjector.js';
 import '@omnicross/contracts/message-blocks';
 import './usage-event-sink-BX7FE1NL.js';
@@ -11,7 +11,7 @@ import './logger-4GvQNzhE.js';
 import './ports/provider-config-source.js';
 import './transformer/types.js';
 import './transformer/TransformerService.js';
-import './provider-proxy/types.js';
+import './types-By9Tg6-I.js';
 import 'node:http';
 import '@omnicross/contracts/usage-stats-types';
 import '@omnicross/contracts/subscription-types';
@@ -23,6 +23,10 @@ import './pipeline/SubscriptionAuthSource.js';
 import './pipeline/SubscriptionAuthStrategy.js';
 import './ports/web-search-backend.js';
 import '@omnicross/contracts/websearch-types';
+import './frontends-Doz0RaWu.js';
+import '@omnicross/contracts/search-types';
+import './runtime-t8AZacFF.js';
+import '@omnicross/contracts/image-generation-types';
 import '@omnicross/contracts/mcp-types';
 import '@omnicross/contracts/endpoint-resolver';
 

package/dist/completion.js

@@ -9,45 +9,60 @@ import {
   getOpenRouterProviderConfig,
   register,
   release
-} from "./chunk-FEBAQI5A.js";
+} from "./chunk-LKDAN4D7.js";
+import "./chunk-MZEGQSKQ.js";
 import "./chunk-VVEHS2LI.js";
 import "./chunk-WTQMX2Q6.js";
-import "./chunk-NGYOO5TO.js";
-import "./chunk-HKB656B4.js";
-import "./chunk-55FMGZ3L.js";
-import "./chunk-45FHEOKW.js";
+import "./chunk-EYGBM2VC.js";
+import "./chunk-MZNPGW5Q.js";
+import "./chunk-DK4A7DLE.js";
+import "./chunk-2C3TTBS7.js";
+import "./chunk-HN74IGEO.js";
+import "./chunk-V53ZEFXC.js";
+import "./chunk-7PIUVCKK.js";
+import "./chunk-EUZRH544.js";
+import "./chunk-LFEH7CEO.js";
 import "./chunk-FU7EAR73.js";
-import "./chunk-CCVRRJOX.js";
-import "./chunk-6D4W22P4.js";
+import "./chunk-QIIAMBTM.js";
 import "./chunk-FXR6N3SR.js";
 import "./chunk-AQDON6MB.js";
-import "./chunk-WNKWAEUR.js";
-import "./chunk-MZNPGW5Q.js";
-import "./chunk-DK4A7DLE.js";
-import "./chunk-XXFYLL7R.js";
+import "./chunk-ECZ3ZE2C.js";
 import "./chunk-XTEI64OU.js";
 import "./chunk-XX6NQJMA.js";
 import "./chunk-GFIZ6LQI.js";
 import "./chunk-OE6TDIWW.js";
 import "./chunk-DRWHTIIZ.js";
+import "./chunk-X335TJNS.js";
+import {
+  getProviderHeaders
+} from "./chunk-HOMUGKHR.js";
 import "./chunk-JWC6APFQ.js";
 import "./chunk-5ERIZW3D.js";
 import "./chunk-PO3XB56Z.js";
-import "./chunk-N7OOJI5V.js";
+import "./chunk-V2UKUTJ3.js";
 import "./chunk-23S5OPIO.js";
 import "./chunk-AVYJ4YBN.js";
 import "./chunk-OPRS4IQZ.js";
 import "./chunk-2JYRIADS.js";
-import "./chunk-DE2SRBFZ.js";
-import {
-  getProviderHeaders
-} from "./chunk-ZY6KU6P3.js";
+import "./chunk-6OKXH2TW.js";
+import "./chunk-WNY4WMRF.js";
+import "./chunk-N76KU6F5.js";
 import "./chunk-WLYIIEAF.js";
 import "./chunk-TKJMZBAH.js";
+import "./chunk-OZFM4X3S.js";
 import "./chunk-3QFXFCHG.js";
-import "./chunk-EBLFCNPY.js";
+import "./chunk-U47LQXPB.js";
 import "./chunk-AQ5TNQB7.js";
 import "./chunk-XEKD23J5.js";
+import {
+  applyAugmentation,
+  buildNativeSearchAugmentation,
+  detectNativeSearch
+} from "./chunk-Y7FO65VT.js";
+import {
+  NATIVE_SEARCH_TOOL_NAMES
+} from "./chunk-FMOBD2OQ.js";
+import "./chunk-HUZZZ3JL.js";
 import {
   buildAnthropicApiUrl,
   buildAzureOpenAIApiUrl,
@@ -59,32 +74,21 @@ import {
   resolveApiFormat,
   resolveProviderEndpoint
 } from "./chunk-H5JUT3KV.js";
-import "./chunk-GXEZ2R3E.js";
-import "./chunk-K5NM7VAH.js";
-import "./chunk-WNY4WMRF.js";
-import "./chunk-OZFM4X3S.js";
 import "./chunk-5NJLQ6T6.js";
-import "./chunk-2UTGX6FM.js";
-import "./chunk-S3DYFEBE.js";
+import "./chunk-4VVCXVB7.js";
+import "./chunk-R4VCO2CB.js";
 import "./chunk-WYVGULTQ.js";
-import "./chunk-N2EIM2XJ.js";
-import "./chunk-RJ5ZGNI3.js";
+import "./chunk-ZLNHPUFA.js";
+import "./chunk-VL5TUDTM.js";
 import "./chunk-3WD4HTR2.js";
 import "./chunk-MKF46GNZ.js";
 import "./chunk-GL6XM527.js";
+import "./chunk-LQYS2N47.js";
+import "./chunk-4JOU54M5.js";
 import {
   BuiltinToolExecutor,
   getBuiltinSearchTools
-} from "./chunk-CDHS2QDC.js";
-import {
-  applyAugmentation,
-  buildNativeSearchAugmentation,
-  detectNativeSearch
-} from "./chunk-Y7FO65VT.js";
-import {
-  NATIVE_SEARCH_TOOL_NAMES
-} from "./chunk-FMOBD2OQ.js";
-import "./chunk-HUZZZ3JL.js";
+} from "./chunk-Y4CRNHJO.js";
 export {
   BuiltinToolExecutor,
   CompletionService,

package/dist/egress-I46O_p5L.d.cts

@@ -0,0 +1,126 @@
+import { lookup } from 'node:dns';
+import { SearchProviderId, SearchProviderError } from '@omnicross/contracts/search-types';
+import { Dispatcher } from 'undici';
+
+/**
+ * The SSRF egress policy every search network path runs through
+ * (plan hard-constraint 7).
+ *
+ * 阶段4 introduces the first attacker-influenceable network surface in the
+ * search tree: a custom `apiHost`. Until now every search request went to one
+ * of two fixed engines, so a URL built from configuration could not be aimed at
+ * an internal address. It can now, which is why this module exists and why it
+ * guards BOTH the API transport and the HTTP slice's redirect walk rather than
+ * living inside one adapter.
+ *
+ * Two layers, because one is not enough:
+ *
+ * 1. {@link validateEgressUrl} — a URL-level check applied to the initial URL
+ *    and to EVERY redirect hop. It catches literal addresses and the named
+ *    loopback/metadata hosts before a request is built.
+ * 2. {@link createEgressGuardedDispatcher} — a connection-time check of every
+ *    address DNS resolves to. Layer 1 alone is a TOCTOU: `evil.example` passes
+ *    the URL check as a public name and then resolves to `127.0.0.1`. Validating
+ *    at the moment of use closes that rebinding window.
+ *
+ * The division of labour between them is worth stating, because it is the
+ * easiest thing to misread here: layer 1 can only judge what a URL SAYS, so it
+ * denies literal addresses and the two host names that are denied by name
+ * (`localhost`, `metadata.google.internal`). An ordinary internal name like
+ * `searx.internal.corp` carries no address and passes layer 1 exactly as a
+ * public name would — layer 2 is what asks where it actually points. Neither
+ * layer is redundant: layer 1 stops `http://169.254.169.254/` without a
+ * resolver, and layer 2 stops every name that lies.
+ *
+ * LIMITATION, stated here because it is a property of the design and not an
+ * oversight: layer 2 only applies to DIRECT connections. When a proxy
+ * dispatcher is in use the proxy resolves DNS, so the guarded lookup never
+ * runs; proxied paths keep layer 1 on every hop and nothing more. The
+ * precedence is asserted by a test rather than left to be discovered.
+ *
+ * Denial messages carry the HOSTNAME only. A search URL embeds the user's
+ * query and may carry userinfo credentials, and these errors are printed,
+ * logged, and returned to callers.
+ *
+ * @module search/egress
+ */
+
+/**
+ * The admin-level egress policy.
+ *
+ * Construction-level, never per-request: a per-request allowlist would let an
+ * attacker who can influence a search request also influence where it may go,
+ * which is the whole thing this module prevents.
+ */
+interface SearchEgressPolicy {
+    /**
+     * Hostnames permitted to resolve into an otherwise-denied address class.
+     *
+     * The escape hatch for an internal SearXNG deployment
+     * (`searx.internal.corp`). Matching is EXACT and case-insensitive — no
+     * wildcards, no suffix matching — because a suffix rule (`.corp`) is one
+     * attacker-registered subdomain away from admitting anything.
+     */
+    allowedPrivateHosts?: string[];
+}
+/** Permit every public host; permit nothing private. The production default. */
+declare const DEFAULT_SEARCH_EGRESS_POLICY: Readonly<SearchEgressPolicy>;
+/** Why a host was denied. Stamped into `details.egressClass` for diagnostics. */
+type EgressDenialReason = 'scheme' | 'malformed' | 'loopback' | 'unspecified' | 'link-local' | 'private' | 'unique-local' | 'metadata';
+/**
+ * Validate one request target against the policy.
+ *
+ * @param url - the target. A relative or unparseable value is a denial, not a
+ *   crash: a redirect `location` is attacker-controlled input.
+ * @returns the parsed URL, so callers can reuse it instead of re-parsing.
+ * @throws SearchProviderError code `policy_denied`, naming the hostname only.
+ */
+declare function validateEgressUrl(url: string | URL, policy?: SearchEgressPolicy, providerId?: SearchProviderId): URL;
+/**
+ * Classify a resolved ADDRESS for a hostname that already passed
+ * {@link validateEgressUrl}.
+ *
+ * Separate from the URL check because this is the rebinding defense: the
+ * hostname was public, the address it resolved to may not be. Allowlisting is
+ * by hostname, so an allowlisted name's private address is admitted here too —
+ * that is exactly what the SearXNG escape hatch means.
+ */
+declare function assertEgressAddressAllowed(address: string, hostname: string, policy?: SearchEgressPolicy, providerId?: SearchProviderId): void;
+/**
+ * The `policy_denied` error buried in a thrown value's `cause` chain, if any.
+ *
+ * undici reports a connect-time failure as a `TypeError: fetch failed` whose
+ * `cause` holds the real error, so a denial raised inside the guarded lookup
+ * reaches the caller wrapped. Without this the transport would classify a
+ * blocked rebinding attempt as `upstream_unavailable`.
+ *
+ * The depth cap assumes undici's wrapping stays SHALLOW — today it is two
+ * levels and this allows six. If a future undici (or an intermediate
+ * dispatcher) nests deeper, a blocked rebinding attempt would quietly
+ * reclassify as a transport failure: the request is still refused, but the
+ * security signal is lost. That is the failure mode to check if denials ever
+ * start reading as `upstream_unavailable`.
+ */
+declare function findEgressDenial(error: unknown): SearchProviderError | undefined;
+/** Node's `dns.lookup` shape — the seam a test replaces. */
+type EgressDnsLookup = typeof lookup;
+/**
+ * Wrap a resolver so every address it returns is validated before use.
+ *
+ * Always resolves with `all: true` and re-shapes the answer to whatever the
+ * caller asked for. Node's `net.connect` passes `all: true` under
+ * `autoSelectFamily` and `all: false` otherwise; validating only the address a
+ * single-answer lookup happened to pick would leave the others unchecked on the
+ * hosts where it matters most.
+ */
+declare function createEgressGuardedLookup(policy?: SearchEgressPolicy, lookupImpl?: EgressDnsLookup): EgressDnsLookup;
+/**
+ * An undici dispatcher that validates every resolved address before connecting.
+ *
+ * Cached per policy signature: a fresh `Agent` per request would leak
+ * connection pools. As in `search/http/proxy.ts`, a superseded dispatcher is
+ * never closed — a concurrent request may still be reading through it.
+ */
+declare function createEgressGuardedDispatcher(policy?: SearchEgressPolicy, lookupImpl?: EgressDnsLookup): Dispatcher;
+
+export { DEFAULT_SEARCH_EGRESS_POLICY as D, type EgressDenialReason as E, type SearchEgressPolicy as S, type EgressDnsLookup as a, assertEgressAddressAllowed as b, createEgressGuardedDispatcher as c, createEgressGuardedLookup as d, findEgressDenial as f, validateEgressUrl as v };

package/dist/egress-I46O_p5L.d.ts

@@ -0,0 +1,126 @@
+import { lookup } from 'node:dns';
+import { SearchProviderId, SearchProviderError } from '@omnicross/contracts/search-types';
+import { Dispatcher } from 'undici';
+
+/**
+ * The SSRF egress policy every search network path runs through
+ * (plan hard-constraint 7).
+ *
+ * 阶段4 introduces the first attacker-influenceable network surface in the
+ * search tree: a custom `apiHost`. Until now every search request went to one
+ * of two fixed engines, so a URL built from configuration could not be aimed at
+ * an internal address. It can now, which is why this module exists and why it
+ * guards BOTH the API transport and the HTTP slice's redirect walk rather than
+ * living inside one adapter.
+ *
+ * Two layers, because one is not enough:
+ *
+ * 1. {@link validateEgressUrl} — a URL-level check applied to the initial URL
+ *    and to EVERY redirect hop. It catches literal addresses and the named
+ *    loopback/metadata hosts before a request is built.
+ * 2. {@link createEgressGuardedDispatcher} — a connection-time check of every
+ *    address DNS resolves to. Layer 1 alone is a TOCTOU: `evil.example` passes
+ *    the URL check as a public name and then resolves to `127.0.0.1`. Validating
+ *    at the moment of use closes that rebinding window.
+ *
+ * The division of labour between them is worth stating, because it is the
+ * easiest thing to misread here: layer 1 can only judge what a URL SAYS, so it
+ * denies literal addresses and the two host names that are denied by name
+ * (`localhost`, `metadata.google.internal`). An ordinary internal name like
+ * `searx.internal.corp` carries no address and passes layer 1 exactly as a
+ * public name would — layer 2 is what asks where it actually points. Neither
+ * layer is redundant: layer 1 stops `http://169.254.169.254/` without a
+ * resolver, and layer 2 stops every name that lies.
+ *
+ * LIMITATION, stated here because it is a property of the design and not an
+ * oversight: layer 2 only applies to DIRECT connections. When a proxy
+ * dispatcher is in use the proxy resolves DNS, so the guarded lookup never
+ * runs; proxied paths keep layer 1 on every hop and nothing more. The
+ * precedence is asserted by a test rather than left to be discovered.
+ *
+ * Denial messages carry the HOSTNAME only. A search URL embeds the user's
+ * query and may carry userinfo credentials, and these errors are printed,
+ * logged, and returned to callers.
+ *
+ * @module search/egress
+ */
+
+/**
+ * The admin-level egress policy.
+ *
+ * Construction-level, never per-request: a per-request allowlist would let an
+ * attacker who can influence a search request also influence where it may go,
+ * which is the whole thing this module prevents.
+ */
+interface SearchEgressPolicy {
+    /**
+     * Hostnames permitted to resolve into an otherwise-denied address class.
+     *
+     * The escape hatch for an internal SearXNG deployment
+     * (`searx.internal.corp`). Matching is EXACT and case-insensitive — no
+     * wildcards, no suffix matching — because a suffix rule (`.corp`) is one
+     * attacker-registered subdomain away from admitting anything.
+     */
+    allowedPrivateHosts?: string[];
+}
+/** Permit every public host; permit nothing private. The production default. */
+declare const DEFAULT_SEARCH_EGRESS_POLICY: Readonly<SearchEgressPolicy>;
+/** Why a host was denied. Stamped into `details.egressClass` for diagnostics. */
+type EgressDenialReason = 'scheme' | 'malformed' | 'loopback' | 'unspecified' | 'link-local' | 'private' | 'unique-local' | 'metadata';
+/**
+ * Validate one request target against the policy.
+ *
+ * @param url - the target. A relative or unparseable value is a denial, not a
+ *   crash: a redirect `location` is attacker-controlled input.
+ * @returns the parsed URL, so callers can reuse it instead of re-parsing.
+ * @throws SearchProviderError code `policy_denied`, naming the hostname only.
+ */
+declare function validateEgressUrl(url: string | URL, policy?: SearchEgressPolicy, providerId?: SearchProviderId): URL;
+/**
+ * Classify a resolved ADDRESS for a hostname that already passed
+ * {@link validateEgressUrl}.
+ *
+ * Separate from the URL check because this is the rebinding defense: the
+ * hostname was public, the address it resolved to may not be. Allowlisting is
+ * by hostname, so an allowlisted name's private address is admitted here too —
+ * that is exactly what the SearXNG escape hatch means.
+ */
+declare function assertEgressAddressAllowed(address: string, hostname: string, policy?: SearchEgressPolicy, providerId?: SearchProviderId): void;
+/**
+ * The `policy_denied` error buried in a thrown value's `cause` chain, if any.
+ *
+ * undici reports a connect-time failure as a `TypeError: fetch failed` whose
+ * `cause` holds the real error, so a denial raised inside the guarded lookup
+ * reaches the caller wrapped. Without this the transport would classify a
+ * blocked rebinding attempt as `upstream_unavailable`.
+ *
+ * The depth cap assumes undici's wrapping stays SHALLOW — today it is two
+ * levels and this allows six. If a future undici (or an intermediate
+ * dispatcher) nests deeper, a blocked rebinding attempt would quietly
+ * reclassify as a transport failure: the request is still refused, but the
+ * security signal is lost. That is the failure mode to check if denials ever
+ * start reading as `upstream_unavailable`.
+ */
+declare function findEgressDenial(error: unknown): SearchProviderError | undefined;
+/** Node's `dns.lookup` shape — the seam a test replaces. */
+type EgressDnsLookup = typeof lookup;
+/**
+ * Wrap a resolver so every address it returns is validated before use.
+ *
+ * Always resolves with `all: true` and re-shapes the answer to whatever the
+ * caller asked for. Node's `net.connect` passes `all: true` under
+ * `autoSelectFamily` and `all: false` otherwise; validating only the address a
+ * single-answer lookup happened to pick would leave the others unchecked on the
+ * hosts where it matters most.
+ */
+declare function createEgressGuardedLookup(policy?: SearchEgressPolicy, lookupImpl?: EgressDnsLookup): EgressDnsLookup;
+/**
+ * An undici dispatcher that validates every resolved address before connecting.
+ *
+ * Cached per policy signature: a fresh `Agent` per request would leak
+ * connection pools. As in `search/http/proxy.ts`, a superseded dispatcher is
+ * never closed — a concurrent request may still be reading through it.
+ */
+declare function createEgressGuardedDispatcher(policy?: SearchEgressPolicy, lookupImpl?: EgressDnsLookup): Dispatcher;
+
+export { DEFAULT_SEARCH_EGRESS_POLICY as D, type EgressDenialReason as E, type SearchEgressPolicy as S, type EgressDnsLookup as a, assertEgressAddressAllowed as b, createEgressGuardedDispatcher as c, createEgressGuardedLookup as d, findEgressDenial as f, validateEgressUrl as v };