@nuvin/agent-core 0.0.0-rc.19 → 0.0.0-rc.20

package/dist/tools/safe-fetch.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Resolves a hostname to its IP addresses. Mirrors the shape of
+ * `node:dns/promises` `lookup(host, { all: true })` but is injectable so the
+ * SSRF guard can be tested without real DNS.
+ */
+export type SafeFetchLookup = (hostname: string) => Promise<Array<{
+    address: string;
+    family: number;
+}>>;
+export interface SafeFetchOptions {
+    lookup?: SafeFetchLookup;
+    fetchImpl?: typeof fetch;
+    maxRedirects?: number;
+}
+export declare const defaultLookup: SafeFetchLookup;
+/**
+ * True when an IP literal points at a non-public destination (loopback,
+ * private, link-local, CGNAT, multicast, reserved). Fails closed on anything
+ * unparseable so a bypass cannot slip through as "not blocked".
+ */
+export declare function isBlockedAddress(ip: string): boolean;
+/**
+ * Validate that a URL is safe for the server to fetch: http(s) only, no
+ * embedded credentials, and a destination that does not resolve to a private
+ * or otherwise non-public address. Literal IPs are range-checked directly;
+ * hostnames are resolved and rejected if ANY resolved address is non-public.
+ * Throws ToolExecutionError on rejection; returns the parsed URL on success.
+ */
+export declare function assertPublicUrl(value: string, options?: SafeFetchOptions): Promise<URL>;
+/**
+ * SSRF-hardened fetch: validates the target (and every redirect hop) against
+ * {@link assertPublicUrl} before connecting, following redirects manually so a
+ * 30x into a private/metadata address cannot be transparently followed.
+ */
+export declare function safeFetch(value: string, init?: RequestInit, options?: SafeFetchOptions): Promise<Response>;
+//# sourceMappingURL=safe-fetch.d.ts.map

package/dist/tools/web-fetch-tool.d.ts

@@ -1,6 +1,9 @@
+import { type SafeFetchLookup } from "./safe-fetch.ts";
 export interface WebFetchToolOptions {
     timeoutMs?: number;
     name?: string;
+    /** DNS resolver used by the SSRF guard. Injectable for tests. */
+    lookup?: SafeFetchLookup;
 }
 export declare function createWebFetchTool(options?: WebFetchToolOptions): import("../shared/types.ts").ToolDefinition<{
     url: string;

package/dist/tools/web-search-tool.d.ts

@@ -1,3 +1,4 @@
+import { type SafeFetchLookup } from "./safe-fetch.ts";
 export interface GoogleCseEngineOptions {
     googleCseKey: string;
     googleCseCx: string;
@@ -14,6 +15,8 @@ export type WebSearchEngine = GoogleCseEngineOptions | OllamaEngineOptions | Tav
 export interface WebSearchToolOptions {
     engines: WebSearchEngine[];
     name?: string;
+    /** DNS resolver used by the SSRF guard when hydrating result pages. Injectable for tests. */
+    lookup?: SafeFetchLookup;
 }
 export declare function createWebSearchTool(options: WebSearchToolOptions): import("../shared/types.ts").ToolDefinition<{
     query: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuvin/agent-core",
-  "version": "0.0.0-rc.19",
+  "version": "0.0.0-rc.20",
   "private": false,
   "description": "Core agent, model, format, and tool primitives for Nuvin",
   "license": "Apache-2.0",