webveil 0.0.0 → 0.1.1

package/src/core/fetch.ts

@@ -0,0 +1,132 @@
+// core fetch: the plain, framework-agnostic `fetch()` BOTH frontends (the incur
+// CLI/MCP and the pi extension) call. Returns clean, size-bounded markdown with
+// distilly's `truncated` flag.
+//
+// Flow (per URL): pick the content source (a backend's own `/extract`
+// (tavily-compat) when the configured backend provides one, OTHERWISE the
+// default distilly Extractor seam, urlToMarkdown over webveil's egress). The
+// SSRF guard lives INSIDE the egress-bound fetch injected into distilly, so it
+// covers distilly's rule-rewritten requests too (docs/adr/0001).
+//
+// LIST-READY INTERNALS (story 12): the work happens in `fetchAll(urls, …)`, a
+// list-processing internal, so a future `web_batch_fetch` tool is a trivial add
+// with no redesign. The public `fetch()` is a thin single-URL wrapper over it.
+
+import {resolveConfig as defaultResolveConfig} from './config.js';
+import type {Config, ResolveOptions} from './config.js';
+import {createEgressFetch as defaultCreateEgressFetch} from './egress.js';
+import type {EgressFetch} from './egress.js';
+import {guardEgressFetch as defaultGuardEgressFetch} from './security.js';
+import {createHttp as defaultCreateHttp} from './http.js';
+import {buildDispatcher as defaultBuildDispatcher} from './egress.js';
+import type {Dispatcher} from './egress.js';
+import {extract as defaultExtract} from './extract.js';
+import type {ExtractDeps} from './extract.js';
+import {getBackend as defaultGetBackend} from './backends/registry.js';
+import type {
+	Backend,
+	FetchOptions,
+	FetchResult,
+	Http,
+} from './backends/types.js';
+
+/**
+ * Collaborators, seamed so the core is testable WITHOUT real config files,
+ * undici, network, or distilly: a test injects fakes to assert the
+ * backend-`/extract`-vs-distilly branch, the list path, and that the guarded
+ * egress fetch (never a global) is what reaches distilly. Defaults wire the real
+ * modules.
+ */
+export interface FetchDeps {
+	resolveConfig?: (options?: ResolveOptions) => Config;
+	getBackend?: (name: string, config: Config) => Backend;
+	buildDispatcher?: (config: Config) => Dispatcher | undefined;
+	createHttp?: (dispatcher: Dispatcher | undefined) => Http;
+	createEgressFetch?: (config: Config) => EgressFetch;
+	guardEgressFetch?: (fetch: EgressFetch, config: Config) => EgressFetch;
+	extract?: (
+		url: string,
+		config: Config,
+		options: {size?: Config['fetchSize']},
+		deps: ExtractDeps,
+	) => Promise<FetchResult>;
+}
+
+/** Per-call fetch options plus the config-resolution knobs (cwd/env/global). */
+export interface FetchCoreOptions extends FetchOptions, ResolveOptions {}
+
+/**
+ * Fetch a LIST of urls to clean, size-bounded markdown, in order. This is the
+ * list-ready internal (story 12): the single-URL `fetch()` below is a thin
+ * wrapper over it, so a future `web_batch_fetch` reuses this directly.
+ *
+ * Each url goes through the SAME content-source choice: a backend's own
+ * `/extract` (if the configured backend implements `fetch`) OR the default
+ * distilly Extractor with the GUARDED egress fetch injected.
+ */
+export async function fetchAll(
+	urls: string[],
+	options: FetchCoreOptions = {},
+	deps: FetchDeps = {},
+): Promise<FetchResult[]> {
+	const resolveConfig = deps.resolveConfig ?? defaultResolveConfig;
+	const getBackend = deps.getBackend ?? defaultGetBackend;
+	const buildDispatcher = deps.buildDispatcher ?? defaultBuildDispatcher;
+	const createHttp = deps.createHttp ?? defaultCreateHttp;
+	const createEgressFetch = deps.createEgressFetch ?? defaultCreateEgressFetch;
+	const guardEgressFetch = deps.guardEgressFetch ?? defaultGuardEgressFetch;
+	const extract = deps.extract ?? defaultExtract;
+
+	const config = resolveConfig({
+		cwd: options.cwd,
+		env: options.env,
+		globalPath: options.globalPath,
+	});
+
+	const backend = getBackend(config.backend, config);
+
+	// A backend that provides its own `/extract` (tavily-compat) OVERRIDES the
+	// distilly Extractor; it is handed only the proxied http helper (built from
+	// the SAME dispatcher as the egress fetch), so it cannot bypass egress.
+	if (backend.fetch) {
+		const http = createHttp(buildDispatcher(config));
+		const backendFetch = backend.fetch.bind(backend);
+		return runAll(urls, (url) =>
+			backendFetch(url, http, {size: options.size, signal: options.signal}),
+		);
+	}
+
+	// Default path: distilly Extractor over webveil's egress. Build the
+	// egress-bound fetch ONCE, wrap it with the SSRF guard, and inject THAT into
+	// distilly (never a global fetch). The guard covers distilly's rule-rewritten
+	// requests too. A configured-but-unbuildable proxy throws at build time
+	// (fail-loud), before any I/O.
+	const guardedFetch = guardEgressFetch(createEgressFetch(config), config);
+	const extractDeps: ExtractDeps = {createEgressFetch: () => guardedFetch};
+	return runAll(urls, (url) =>
+		extract(url, config, {size: options.size}, extractDeps),
+	);
+}
+
+/** Run a per-url worker over the list in order, collecting the results. */
+async function runAll(
+	urls: string[],
+	work: (url: string) => Promise<FetchResult>,
+): Promise<FetchResult[]> {
+	const out: FetchResult[] = [];
+	for (const url of urls) out.push(await work(url));
+	return out;
+}
+
+/**
+ * Fetch ONE url to clean, size-bounded markdown (`{ markdown, truncated, … }`).
+ * A thin single-URL wrapper over the list-ready `fetchAll` (story 12).
+ */
+export async function fetch(
+	url: string,
+	options: FetchCoreOptions = {},
+	deps: FetchDeps = {},
+): Promise<FetchResult> {
+	const [result] = await fetchAll([url], options, deps);
+	return result!;
+}

package/src/core/http.ts

@@ -0,0 +1,62 @@
+// http helper — the proxied `http` handed to backends. fetchJson / fetchText
+// apply the egress dispatcher + a per-request timeout + abort. Distinct from the
+// egress-bound WHATWG `fetch` (egress.ts), but bound to the SAME dispatcher, so
+// a backend physically cannot bypass the configured egress.
+
+import {type Dispatcher, fetch as undiciFetch} from 'undici';
+import type {Http, HttpRequestOptions} from './backends/types.js';
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+async function request(
+	dispatcher: Dispatcher | undefined,
+	url: string,
+	options: HttpRequestOptions = {},
+): Promise<Response> {
+	const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), timeoutMs);
+	if (options.signal)
+		options.signal.addEventListener('abort', () => controller.abort(), {
+			once: true,
+		});
+	try {
+		const res = await undiciFetch(url, {
+			method: options.method,
+			headers: options.headers,
+			body: options.body,
+			signal: controller.signal,
+			dispatcher,
+		} as never);
+		return res as unknown as Response;
+	} finally {
+		clearTimeout(timer);
+	}
+}
+
+/**
+ * Build the proxied http helper over a given dispatcher. Both methods throw on a
+ * non-2xx response so a backend never silently consumes an error body.
+ */
+export function createHttp(dispatcher: Dispatcher | undefined): Http {
+	return {
+		async fetchJson<T = unknown>(
+			url: string,
+			options?: HttpRequestOptions,
+		): Promise<T> {
+			const res = await request(dispatcher, url, options);
+			if (!res.ok)
+				throw new Error(`http ${res.status} ${res.statusText} for ${url}`);
+			return (await res.json()) as T;
+		},
+		async fetchText(
+			url: string,
+			options?: HttpRequestOptions,
+		): Promise<string> {
+			const res = await request(dispatcher, url, options);
+			if (!res.ok)
+				throw new Error(`http ${res.status} ${res.statusText} for ${url}`);
+			return await res.text();
+		},
+	};
+}

package/src/core/search.ts

@@ -0,0 +1,140 @@
+// core search — the plain, framework-agnostic `search()` BOTH frontends (the
+// incur CLI/MCP and the pi extension) call. It owns the wiring and the
+// caller-facing post-processing; the per-source parsing lives in the backend.
+//
+// Flow: resolve config → build the egress dispatcher → bind the proxied `http`
+// helper to it → select the backend from the registry → call the backend with
+// ONLY that proxied helper → normalize (dedup + clamp) the SearchResult[].
+//
+// The egress invariant (docs/adr/0001): the backend is handed only the
+// dispatcher-bound `http` helper, so it physically cannot reach a global fetch
+// and bypass the configured egress. A configured-but-unbuildable proxy throws at
+// buildDispatcher (fail-loud), never silently un-proxied.
+
+import {resolveConfig as defaultResolveConfig} from './config.js';
+import type {Config, ResolveOptions} from './config.js';
+import {
+	buildDispatcher as defaultBuildDispatcher,
+	assertEgressAllowsBaseUrl as defaultAssertEgressAllowsBaseUrl,
+} from './egress.js';
+import type {Dispatcher} from './egress.js';
+import {resolveBackendTransport as defaultResolveBackendTransport} from './baseurl.js';
+import type {BackendTransport} from './baseurl.js';
+import {createHttp as defaultCreateHttp} from './http.js';
+import {getBackend as defaultGetBackend} from './backends/registry.js';
+import type {Http, SearchOptions, SearchResult} from './backends/types.js';
+
+/**
+ * Default cap on returned results when the caller does not pass `maxResults`.
+ * Keeps an agent's context small by default; a caller can raise/lower it per
+ * call. (Recorded decision: there is no configured default, so the core sets
+ * one; see the task's Decisions block.)
+ */
+const DEFAULT_MAX_RESULTS = 10;
+
+/**
+ * Collaborators, seamed so the core is testable WITHOUT real config files,
+ * undici, or network: a test injects a fake `getBackend`/`createHttp` to assert
+ * the backend is handed only the proxied helper, and a fake backend returning
+ * duplicate/over-limit hits to assert dedup + clamp. Defaults wire the real
+ * config/egress/http/registry modules.
+ */
+export interface SearchDeps {
+	resolveConfig?: (options?: ResolveOptions) => Config;
+	buildDispatcher?: (config: Config) => Dispatcher | undefined;
+	assertEgressAllowsBaseUrl?: (config: Config) => void;
+	resolveBackendTransport?: (baseUrl: string) => BackendTransport;
+	createHttp?: (dispatcher: Dispatcher | undefined) => Http;
+	getBackend?: (
+		name: string,
+		config: Config,
+	) => {
+		search: (
+			query: string,
+			http: Http,
+			options?: SearchOptions,
+		) => Promise<SearchResult[]>;
+	};
+}
+
+/** Per-call search options plus the config-resolution knobs (cwd/env/global). */
+export interface SearchCoreOptions extends SearchOptions, ResolveOptions {}
+
+/** Dedup by url (the hit's identity), preserving first-seen order. */
+function dedup(results: SearchResult[]): SearchResult[] {
+	const seen = new Set<string>();
+	const out: SearchResult[] = [];
+	for (const r of results) {
+		if (seen.has(r.url)) continue;
+		seen.add(r.url);
+		out.push(r);
+	}
+	return out;
+}
+
+/**
+ * Search the configured backend over the configured egress and return
+ * normalized `SearchResult[]` (deduped by url, then clamped to `maxResults`).
+ *
+ * Dedup runs BEFORE the clamp so the caller gets up to `maxResults` UNIQUE hits,
+ * not a window that duplicates eat into; for the same reason the backend is NOT
+ * asked to pre-clamp (only the abort signal is forwarded).
+ */
+export async function search(
+	query: string,
+	options: SearchCoreOptions = {},
+	deps: SearchDeps = {},
+): Promise<SearchResult[]> {
+	const resolveConfig = deps.resolveConfig ?? defaultResolveConfig;
+	const buildDispatcher = deps.buildDispatcher ?? defaultBuildDispatcher;
+	const assertEgressAllowsBaseUrl =
+		deps.assertEgressAllowsBaseUrl ?? defaultAssertEgressAllowsBaseUrl;
+	const resolveBackendTransport =
+		deps.resolveBackendTransport ?? defaultResolveBackendTransport;
+	const createHttp = deps.createHttp ?? defaultCreateHttp;
+	const getBackend = deps.getBackend ?? defaultGetBackend;
+
+	const config = resolveConfig({
+		cwd: options.cwd,
+		env: options.env,
+		globalPath: options.globalPath,
+	});
+
+	// Fail loud on the false-confidence combo (a local `unix:` socket baseUrl
+	// behind a proxy egress) BEFORE any transport is built.
+	assertEgressAllowsBaseUrl(config);
+
+	// Resolve the BACKEND-hop transport. For a normal TCP baseUrl this is a no-op
+	// (no per-hop dispatcher); for a `unix:` baseUrl it yields a socket-bound
+	// `Agent` and a synthetic `http://localhost…` base the backend builds on. The
+	// socket transport is scoped to THIS hop only and is NEVER bound into the
+	// shared config-wide egress dispatcher, so `web_fetch` egress is unaffected.
+	const transport = resolveBackendTransport(config.baseUrl);
+
+	// Build the egress dispatcher FIRST: a configured-but-unbuildable proxy throws
+	// here, before any network access (never an un-proxied request). For a socket
+	// baseUrl the per-hop socket dispatcher overrides the (direct/undefined) one.
+	const dispatcher = transport.dispatcher ?? buildDispatcher(config);
+	const http = createHttp(dispatcher);
+
+	// The backend stays transport-unaware: it receives a config whose baseUrl is
+	// always a real `http(s):` base (the `unix:` form is rewritten away here).
+	const backendConfig: Config =
+		transport.baseUrl === config.baseUrl
+			? config
+			: {...config, baseUrl: transport.baseUrl};
+	const backend = getBackend(backendConfig.backend, backendConfig);
+	// Hand the backend ONLY the proxied helper (no maxResults: dedup happens
+	// here, over the full set, so the clamp below is over UNIQUE results).
+	let raw: SearchResult[];
+	try {
+		raw = await backend.search(query, http, {signal: options.signal});
+	} finally {
+		// Best-effort close of the per-hop socket Agent (the shared egress
+		// dispatcher, owned by config, is NOT touched here).
+		if (transport.dispatcher) void transport.dispatcher.close();
+	}
+
+	const maxResults = options.maxResults ?? DEFAULT_MAX_RESULTS;
+	return dedup(raw).slice(0, maxResults);
+}

package/src/core/security.ts

@@ -0,0 +1,141 @@
+// SSRF guard: the security seam wrapped AROUND the egress-bound `fetch`, so it
+// covers BOTH webveil's own GETs AND distilly's rule-rewritten requests (see
+// docs/adr/0001: the guard lives inside the egress fetch). Adapts the range
+// classification + DNS-resolve approach of leing2021/pi-search's `security.ts`.
+//
+// THE RELAXATION RULE (load-bearing, recorded in the task's Decisions): the
+// guard BLOCKS private/loopback/link-local/etc. addresses on DIRECT egress, and
+// RELAXES ENTIRELY under a proxy egress (`http` | `socks5`). Tor/Mullvad
+// legitimately reach private-looking addresses (e.g. `10.64.0.1`), AND a local
+// DNS lookup for a proxied request would itself be a deanonymizing leak, so
+// under a proxy we neither block nor resolve locally; the proxy owns egress.
+
+import {lookup} from 'node:dns/promises';
+import {isIP} from 'node:net';
+import type {Config} from './config.js';
+import type {EgressFetch} from './egress.js';
+
+/** Thrown when the SSRF guard refuses a request to a private/blocked address. */
+export class SsrfError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = 'SsrfError';
+	}
+}
+
+/** A proxy egress owns egress + DNS, so the local SSRF guard relaxes for it. */
+function egressIsProxy(config: Config): boolean {
+	return config.egress.mode === 'http' || config.egress.mode === 'socks5';
+}
+
+/**
+ * Is this LITERAL IP private / non-public? Covers the ranges that must never be
+ * reachable from a direct-egress web fetch:
+ *   IPv4: 0.0.0.0/8, 10/8 (RFC1918), 127/8 (loopback), 169.254/16 (link-local,
+ *     incl. the 169.254.169.254 cloud metadata endpoint), 172.16/12 (RFC1918),
+ *     192.168/16 (RFC1918), 100.64/10 (CGNAT), 192.0.0/24, 192.0.2/24,
+ *     198.18/15, 198.51.100/24, 203.0.113/24, 224/4 (multicast), 240/4
+ *     (reserved).
+ *   IPv6: ::1 (loopback), :: (unspecified), fc00::/7 (ULA), fe80::/10
+ *     (link-local), ff00::/8 (multicast), plus IPv4-mapped (::ffff:a.b.c.d,
+ *     re-checked as IPv4). Default-deny: anything outside global unicast
+ *     (2000::/3) is treated as non-public.
+ */
+export function isPrivateIp(ip: string): boolean {
+	const kind = isIP(ip);
+	if (kind === 4) return isPrivateIpv4(ip);
+	if (kind === 6) return isPrivateIpv6(ip);
+	return false; // not a literal IP; hostname handling resolves it first
+}
+
+function isPrivateIpv4(ip: string): boolean {
+	const parts = ip.split('.').map((p) => Number(p));
+	if (
+		parts.length !== 4 ||
+		parts.some((n) => !Number.isInteger(n) || n < 0 || n > 255)
+	)
+		return true; // malformed → treat as non-public (fail closed)
+	const [a, b] = parts as [number, number, number, number];
+	if (a === 0 || a === 10 || a === 127) return true;
+	if (a === 169 && b === 254) return true; // link-local incl. cloud metadata
+	if (a === 172 && b >= 16 && b <= 31) return true; // 172.16/12
+	if (a === 192 && b === 168) return true; // 192.168/16
+	if (a === 100 && b >= 64 && b <= 127) return true; // 100.64/10 CGNAT
+	if (a === 192 && b === 0) return true; // 192.0.0/24 + 192.0.2/24
+	if (a === 198 && (b === 18 || b === 19)) return true; // 198.18/15 benchmark
+	if (a === 198 && b === 51) return true; // 198.51.100/24 TEST-NET-2
+	if (a === 203 && b === 0) return true; // 203.0.113/24 TEST-NET-3
+	if (a >= 224) return true; // 224/4 multicast + 240/4 reserved
+	return false;
+}
+
+function isPrivateIpv6(ip: string): boolean {
+	const lower = ip.toLowerCase();
+	if (lower === '::1' || lower === '::') return true; // loopback / unspecified
+	// IPv4-mapped (::ffff:a.b.c.d): re-check the embedded IPv4.
+	const mapped = lower.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+	if (mapped) return isPrivateIpv4(mapped[1]!);
+	const head = lower.split(':')[0] ?? '';
+	const first = parseInt(head || '0', 16);
+	if (Number.isNaN(first)) return true; // fail closed on anything unparseable
+	if ((first & 0xfe00) === 0xfc00) return true; // fc00::/7 ULA
+	if ((first & 0xffc0) === 0xfe80) return true; // fe80::/10 link-local
+	if ((first & 0xff00) === 0xff00) return true; // ff00::/8 multicast
+	// Default-deny: only global unicast 2000::/3 is public.
+	return (first & 0xe000) !== 0x2000;
+}
+
+/**
+ * Assert a URL is safe to fetch under THIS config's egress. Under a proxy egress
+ * it always passes (the proxy owns egress + DNS). Under direct egress it rejects
+ * a literal private IP and, for a hostname, resolves it locally and rejects if it
+ * maps to a private IP (so a name pointing at 127.0.0.1 / metadata is caught).
+ */
+export async function assertPublicUrl(
+	url: string,
+	config: Config,
+): Promise<void> {
+	if (egressIsProxy(config)) return; // proxy owns egress + DNS; relax entirely
+	let parsed: URL;
+	try {
+		parsed = new URL(url);
+	} catch {
+		throw new SsrfError(`webveil SSRF: malformed url ${url}`);
+	}
+	const host = parsed.hostname.replace(/^\[|\]$/g, ''); // strip IPv6 brackets
+	if (isIP(host)) {
+		if (isPrivateIp(host))
+			throw new SsrfError(`webveil SSRF: blocked private address ${host}`);
+		return;
+	}
+	// A hostname: resolve it locally (safe on direct egress) and check every
+	// address it maps to, so a name pointing at a private IP is also blocked.
+	const addrs = await lookup(host, {all: true});
+	for (const {address} of addrs)
+		if (isPrivateIp(address))
+			throw new SsrfError(
+				`webveil SSRF: ${host} resolves to private address ${address}`,
+			);
+}
+
+/**
+ * Wrap an egress-bound `fetch` with the SSRF guard. The returned fetch checks
+ * EVERY request URL (so it covers distilly's rule-rewritten requests too, not
+ * only webveil's own GET) before delegating to the underlying egress fetch.
+ * This is what `core.fetch()` injects into distilly. See docs/adr/0001.
+ */
+export function guardEgressFetch(
+	fetch: EgressFetch,
+	config: Config,
+): EgressFetch {
+	return (async (input: RequestInfo | URL, init?: RequestInit) => {
+		const url =
+			typeof input === 'string'
+				? input
+				: input instanceof URL
+					? input.href
+					: input.url;
+		await assertPublicUrl(url, config);
+		return fetch(input as never, init as never);
+	}) as EgressFetch;
+}

package/src/index.ts

@@ -0,0 +1,82 @@
+// webveil — anonymous-capable, self-hosted, account-free web search + fetch for agents.
+//
+// This is the public surface. The framework-agnostic core lives under src/core:
+//   - core/config.ts            : config seam (per-folder .pi/webveil.json + global + env)
+//   - core/egress.ts            : egress seam (direct | http | socks5/Tor) — dispatcher + egress fetch
+//   - core/http.ts              : the proxied `http` helper handed to backends
+//   - core/extract.ts           : Extractor seam (distilly/fetch + injected egress fetch)
+//   - core/backends/types.ts    : backend seam (the Backend interface + result shapes)
+//   - core/backends/registry.ts : name -> Backend dispatcher
+//   - core/backends/searxng.ts  : the keyless self-hosted SearXNG backend
+//   - core/backends/tavily-compat.ts : the generic Tavily-shaped backend (/search + /extract)
+//   - core/search.ts            : the framework-agnostic search() both frontends call
+//   - core/security.ts          : SSRF guard wrapped around the egress fetch
+//   - core/fetch.ts             : the framework-agnostic fetch() both frontends call
+//   - core/backends/custom.ts  : the local-command escape hatch (JSON stdin/stdout)
+//   - cli.ts                    : the incur CLI + MCP frontend (the `webveil` bin)
+// pi-webveil (sibling package) wraps the SAME core functions as registerTool
+// web_search / web_fetch, in-process, as an Ollama drop-in.
+
+// config seam
+export {resolveConfig} from './core/config.js';
+export type {
+	Config,
+	Egress,
+	FetchSize,
+	PartialConfig,
+	ResolveOptions,
+} from './core/config.js';
+
+// egress seam
+export {
+	buildDispatcher,
+	createEgressFetch,
+	EgressError,
+} from './core/egress.js';
+export type {Dispatcher, EgressFetch} from './core/egress.js';
+
+// http helper
+export {createHttp} from './core/http.js';
+
+// Extractor seam (distilly/fetch over webveil's egress)
+export {extract} from './core/extract.js';
+export type {ExtractOptions, ExtractDeps} from './core/extract.js';
+
+// SSRF guard (wrapped around the egress fetch; covers distilly's requests too)
+export {
+	assertPublicUrl,
+	guardEgressFetch,
+	isPrivateIp,
+	SsrfError,
+} from './core/security.js';
+
+// backend seam (the contract + result types)
+export type {
+	Backend,
+	Http,
+	HttpRequestOptions,
+	SearchResult,
+	FetchResult,
+	SearchOptions,
+	FetchOptions,
+} from './core/backends/types.js';
+
+// backend registry + implementations
+export {backendNames, getBackend} from './core/backends/registry.js';
+export type {BackendFactory} from './core/backends/registry.js';
+export {createSearxngBackend} from './core/backends/searxng.js';
+export {createTavilyCompatBackend} from './core/backends/tavily-compat.js';
+export {createCustomBackend} from './core/backends/custom.js';
+export type {SpawnFn} from './core/backends/custom.js';
+
+// core search (the framework-agnostic search() both frontends call)
+export {search} from './core/search.js';
+export type {SearchCoreOptions, SearchDeps} from './core/search.js';
+
+// core fetch (the framework-agnostic fetch() + list-ready fetchAll internal)
+export {fetch, fetchAll} from './core/fetch.js';
+export type {FetchCoreOptions, FetchDeps} from './core/fetch.js';
+
+// incur CLI + MCP frontend (the `webveil` bin builds and serves this)
+export {createCli} from './cli.js';
+export type {CliDeps} from './cli.js';