webveil 0.0.0 → 0.1.1

package/dist/core/egress.js

@@ -0,0 +1,113 @@
+// egress seam — how outbound HTTP leaves the machine. Yields TWO artifacts off
+// the SAME undici dispatcher: the proxied `http` helper (see http.ts, handed to
+// backends) and an egress-bound WHATWG `fetch` (injected into distilly/fetch).
+//
+// CRITICAL anonymity invariant (docs/adr/0001): egress is fail-loud. A
+// configured proxy that cannot be built MUST throw — it must NEVER silently
+// fall back to un-proxied (direct) transport.
+import { Agent, ProxyAgent, fetch as undiciFetch } from 'undici';
+import { socksDispatcher } from 'fetch-socks';
+import { isUnixBaseUrl } from './baseurl.js';
+/** Thrown when a configured egress proxy cannot be built. Never swallowed. */
+export class EgressError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'EgressError';
+    }
+}
+/**
+ * Fail-loud guard for the false-confidence combo: a `unix:` (local-socket)
+ * backend `baseUrl` configured with a NON-direct egress (`http`/`socks5`). A
+ * Unix socket is inherently local, so proxying that hop is the same fake-
+ * anonymity footgun as proxying a loopback TCP baseUrl: webveil would route a
+ * pointless local call through the proxy while the backend (SearXNG) crawls the
+ * public web from the real IP, OUTSIDE webveil's egress. Refuse it and point at
+ * the real fix.
+ *
+ * OVERLAP SEAM (recorded): this is the loopback false-confidence family. The
+ * sibling task `fail-loud-on-proxied-loopback-backend` adds the broader guard
+ * for loopback TCP baseUrls (127.0.0.0/8, ::1, localhost). When it lands, fold
+ * THIS `unix:`-is-loopback-equivalent case into that single guard instead of
+ * keeping a parallel check here.
+ */
+export function assertEgressAllowsBaseUrl(cfg) {
+    if (cfg.egress.mode === 'direct')
+        return;
+    if (isUnixBaseUrl(cfg.baseUrl))
+        throw new EgressError(`egress ${cfg.egress.mode}: a unix: (local socket) baseUrl cannot be ` +
+            `proxied — it is inherently local, so proxying it gives fake ` +
+            `anonymity (SearXNG still crawls the web from your real IP). Set ` +
+            `egress=direct and proxy the backend itself (SearXNG's ` +
+            `outgoing.proxies), or use a remote backend.`);
+}
+function socksFromUrl(raw) {
+    const url = new URL(raw); // throws on a malformed proxy URL → fail loud
+    const protocol = url.protocol.replace(':', '');
+    if (protocol !== 'socks5' && protocol !== 'socks' && protocol !== 'socks5h')
+        throw new EgressError(`egress socks5: expected a socks5:// proxy url, got ${raw}`);
+    const port = Number(url.port);
+    if (!url.hostname || !Number.isInteger(port) || port <= 0)
+        throw new EgressError(`egress socks5: invalid host/port in ${raw}`);
+    return socksDispatcher({
+        type: 5,
+        host: url.hostname,
+        port,
+        userId: url.username || undefined,
+        password: url.password || undefined,
+    });
+}
+/**
+ * Build the undici Dispatcher for the config's egress mode:
+ *   - direct → undefined (undici uses its default, un-proxied transport)
+ *   - http   → ProxyAgent
+ *   - socks5 → socks dispatcher (undici Agent over a socks connector)
+ *
+ * Throws (fail loud) if a configured http/socks5 proxy cannot be built. It
+ * NEVER returns `undefined` (direct) as a fallback for a broken proxy.
+ */
+export function buildDispatcher(cfg) {
+    const egress = cfg.egress;
+    switch (egress.mode) {
+        case 'direct':
+            return undefined;
+        case 'http':
+            try {
+                if (!egress.url)
+                    throw new Error('missing proxy url');
+                return new ProxyAgent(egress.url);
+            }
+            catch (cause) {
+                throw new EgressError(`egress http: could not build proxy for ${egress.url}`, { cause });
+            }
+        case 'socks5':
+            try {
+                if (!egress.url)
+                    throw new Error('missing proxy url');
+                return socksFromUrl(egress.url);
+            }
+            catch (cause) {
+                if (cause instanceof EgressError)
+                    throw cause;
+                throw new EgressError(`egress socks5: could not build proxy for ${egress.url}`, { cause });
+            }
+        default: {
+            const exhaustive = egress;
+            throw new EgressError(`egress: unknown mode ${JSON.stringify(exhaustive)}`);
+        }
+    }
+}
+/**
+ * Build an egress-bound WHATWG `fetch`: undici's `fetch` closed over the
+ * dispatcher from buildDispatcher(cfg). This is the `fetch` injected into
+ * distilly/fetch so distilly never has egress of its own. Same fail-loud
+ * guarantee: a broken proxy throws HERE (before any I/O), never goes un-proxied.
+ */
+export function createEgressFetch(cfg) {
+    const dispatcher = buildDispatcher(cfg);
+    return ((input, init) => undiciFetch(input, {
+        ...(init ?? {}),
+        dispatcher,
+    }));
+}
+export { Agent, ProxyAgent };
+//# sourceMappingURL=egress.js.map

package/dist/core/egress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"egress.js","sourceRoot":"","sources":["../../src/core/egress.ts"],"names":[],"mappings":"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"}

package/dist/core/extract.d.ts

@@ -0,0 +1,45 @@
+import type { Config, FetchSize } from './config.js';
+import { type EgressFetch } from './egress.js';
+import type { FetchResult } from './backends/types.js';
+/** The shape distilly's `urlToMarkdown` returns (the bits we surface). */
+interface UrlToMarkdownResult {
+    markdown: string;
+    truncated: boolean;
+}
+/** distilly's networked entrypoint, narrowed to what the seam injects/uses. */
+type UrlToMarkdown = (url: string | URL, options: {
+    fetch: EgressFetch;
+    size?: FetchSize;
+}) => Promise<UrlToMarkdownResult>;
+/** Per-call extractor options. */
+export interface ExtractOptions {
+    /**
+     * Page-size budget for THIS call. Overrides the config's `fetchSize` when
+     * given. webveil's `s`/`m`/`l`/`f` preset maps STRAIGHT to distilly's `size`
+     * (the two enums are identical), so this is passed through verbatim.
+     */
+    size?: FetchSize;
+}
+/**
+ * Seams the extractor's collaborators so it is testable WITHOUT real network or
+ * undici: tests inject a spy `urlToMarkdown` and/or a spy egress fetch to assert
+ * distilly is called with the egress fetch (never a global). Defaults wire the
+ * real `distilly/fetch` + `createEgressFetch`.
+ */
+export interface ExtractDeps {
+    /** distilly's networked `urlToMarkdown` (default: the real `distilly/fetch`). */
+    urlToMarkdown?: UrlToMarkdown;
+    /** Builds the egress-bound fetch from config (default: createEgressFetch). */
+    createEgressFetch?: (config: Config) => EgressFetch;
+}
+/**
+ * Extract a URL to clean, budget-bounded markdown via distilly over webveil's
+ * egress. Builds the egress-bound `fetch` (fail-loud on an unbuildable proxy),
+ * injects it into distilly's `urlToMarkdown`, maps the `s`/`m`/`l`/`f` preset to
+ * distilly's `size`, and surfaces distilly's `truncated`.
+ *
+ * @returns `{ url, markdown, truncated }` (a `FetchResult` without a `title`).
+ */
+export declare function extract(url: string, config: Config, options?: ExtractOptions, deps?: ExtractDeps): Promise<FetchResult>;
+export {};
+//# sourceMappingURL=extract.d.ts.map

package/dist/core/extract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["../../src/core/extract.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAC,MAAM,EAAE,SAAS,EAAC,MAAM,aAAa,CAAC;AACnD,OAAO,EAAoB,KAAK,WAAW,EAAC,MAAM,aAAa,CAAC;AAChE,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,qBAAqB,CAAC;AAErD,0EAA0E;AAC1E,UAAU,mBAAmB;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;CACnB;AAED,+EAA+E;AAC/E,KAAK,aAAa,GAAG,CACpB,GAAG,EAAE,MAAM,GAAG,GAAG,EACjB,OAAO,EAAE;IAAC,KAAK,EAAE,WAAW,CAAC;IAAC,IAAI,CAAC,EAAE,SAAS,CAAA;CAAC,KAC3C,OAAO,CAAC,mBAAmB,CAAC,CAAC;AAElC,kCAAkC;AAClC,MAAM,WAAW,cAAc;IAC9B;;;;OAIG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;CACjB;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC3B,iFAAiF;IACjF,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,8EAA8E;IAC9E,iBAAiB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,WAAW,CAAC;CACpD;AAED;;;;;;;GAOG;AACH,wBAAsB,OAAO,CAC5B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,cAAmB,EAC5B,IAAI,GAAE,WAAgB,GACpB,OAAO,CAAC,WAAW,CAAC,CAYtB"}

package/dist/core/extract.js

@@ -0,0 +1,36 @@
+// Extractor seam — turn a URL into clean, size-bounded markdown by calling
+// distilly's NETWORKED `urlToMarkdown` (the `distilly/fetch` entrypoint),
+// INJECTING webveil's egress-bound `fetch` as the only transport. distilly's
+// network Rules (github/mdn/react.dev/vuejs.org) rewrite a matching URL to its
+// raw `.md`/API source and fetch THAT over our egress — shorter, cleaner output;
+// non-matching URLs run through distilly's pure core. See docs/adr/0001.
+//
+// THE HARD INVARIANT (load-bearing for anonymity): webveil ALWAYS injects its
+// egress-bound `fetch` here and NEVER lets distilly use a global/default fetch.
+// distilly throws if none is injected — the desired fail-loud. And the egress
+// fetch itself throws (before any I/O) when a configured proxy is unbuildable
+// (egress.ts), so a broken proxy can never become an un-proxied request.
+//
+// This is the DEFAULT extractor; a backend's own `/extract` (tavily-compat) may
+// override it (wired in the core-fetch task).
+import { urlToMarkdown as distillyUrlToMarkdown } from 'distilly/fetch';
+import { createEgressFetch } from './egress.js';
+/**
+ * Extract a URL to clean, budget-bounded markdown via distilly over webveil's
+ * egress. Builds the egress-bound `fetch` (fail-loud on an unbuildable proxy),
+ * injects it into distilly's `urlToMarkdown`, maps the `s`/`m`/`l`/`f` preset to
+ * distilly's `size`, and surfaces distilly's `truncated`.
+ *
+ * @returns `{ url, markdown, truncated }` (a `FetchResult` without a `title`).
+ */
+export async function extract(url, config, options = {}, deps = {}) {
+    const urlToMarkdown = deps.urlToMarkdown ?? distillyUrlToMarkdown;
+    const buildFetch = deps.createEgressFetch ?? createEgressFetch;
+    // Build the egress-bound fetch FIRST: a configured-but-unbuildable proxy
+    // throws here, before any network access (never an un-proxied request).
+    const fetch = buildFetch(config);
+    const size = options.size ?? config.fetchSize;
+    const { markdown, truncated } = await urlToMarkdown(url, { fetch, size });
+    return { url, markdown, truncated };
+}
+//# sourceMappingURL=extract.js.map

package/dist/core/extract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract.js","sourceRoot":"","sources":["../../src/core/extract.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,0EAA0E;AAC1E,6EAA6E;AAC7E,+EAA+E;AAC/E,iFAAiF;AACjF,yEAAyE;AACzE,EAAE;AACF,8EAA8E;AAC9E,gFAAgF;AAChF,8EAA8E;AAC9E,8EAA8E;AAC9E,yEAAyE;AACzE,EAAE;AACF,gFAAgF;AAChF,8CAA8C;AAE9C,OAAO,EAAC,aAAa,IAAI,qBAAqB,EAAC,MAAM,gBAAgB,CAAC;AAEtE,OAAO,EAAC,iBAAiB,EAAmB,MAAM,aAAa,CAAC;AAsChE;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAC5B,GAAW,EACX,MAAc,EACd,UAA0B,EAAE,EAC5B,OAAoB,EAAE;IAEtB,MAAM,aAAa,GAAG,IAAI,CAAC,aAAa,IAAI,qBAAqB,CAAC;IAClE,MAAM,UAAU,GAAG,IAAI,CAAC,iBAAiB,IAAI,iBAAiB,CAAC;IAE/D,yEAAyE;IACzE,wEAAwE;IACxE,MAAM,KAAK,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;IAEjC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,MAAM,CAAC,SAAS,CAAC;IAE9C,MAAM,EAAC,QAAQ,EAAE,SAAS,EAAC,GAAG,MAAM,aAAa,CAAC,GAAG,EAAE,EAAC,KAAK,EAAE,IAAI,EAAC,CAAC,CAAC;IACtE,OAAO,EAAC,GAAG,EAAE,QAAQ,EAAE,SAAS,EAAC,CAAC;AACnC,CAAC"}

package/dist/core/fetch.d.ts

@@ -0,0 +1,42 @@
+import type { Config, ResolveOptions } from './config.js';
+import type { EgressFetch } from './egress.js';
+import type { Dispatcher } from './egress.js';
+import type { ExtractDeps } from './extract.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 declare function fetchAll(urls: string[], options?: FetchCoreOptions, deps?: FetchDeps): Promise<FetchResult[]>;
+/**
+ * Fetch ONE url to clean, size-bounded markdown (`{ markdown, truncated, … }`).
+ * A thin single-URL wrapper over the list-ready `fetchAll` (story 12).
+ */
+export declare function fetch(url: string, options?: FetchCoreOptions, deps?: FetchDeps): Promise<FetchResult>;
+//# sourceMappingURL=fetch.d.ts.map

package/dist/core/fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../../src/core/fetch.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAC,MAAM,EAAE,cAAc,EAAC,MAAM,aAAa,CAAC;AAExD,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,aAAa,CAAC;AAI7C,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,aAAa,CAAC;AAE5C,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,cAAc,CAAC;AAE9C,OAAO,KAAK,EACX,OAAO,EACP,YAAY,EACZ,WAAW,EACX,IAAI,EACJ,MAAM,qBAAqB,CAAC;AAE7B;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACzB,aAAa,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,cAAc,KAAK,MAAM,CAAC;IACrD,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;IACvD,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,UAAU,GAAG,SAAS,CAAC;IAC7D,UAAU,CAAC,EAAE,CAAC,UAAU,EAAE,UAAU,GAAG,SAAS,KAAK,IAAI,CAAC;IAC1D,iBAAiB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,WAAW,CAAC;IACpD,gBAAgB,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,KAAK,WAAW,CAAC;IACvE,OAAO,CAAC,EAAE,CACT,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,OAAO,EAAE;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC,WAAW,CAAC,CAAA;KAAC,EACrC,IAAI,EAAE,WAAW,KACb,OAAO,CAAC,WAAW,CAAC,CAAC;CAC1B;AAED,gFAAgF;AAChF,MAAM,WAAW,gBAAiB,SAAQ,YAAY,EAAE,cAAc;CAAG;AAEzE;;;;;;;;GAQG;AACH,wBAAsB,QAAQ,CAC7B,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,GAAE,gBAAqB,EAC9B,IAAI,GAAE,SAAc,GAClB,OAAO,CAAC,WAAW,EAAE,CAAC,CAsCxB;AAYD;;;GAGG;AACH,wBAAsB,KAAK,CAC1B,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,gBAAqB,EAC9B,IAAI,GAAE,SAAc,GAClB,OAAO,CAAC,WAAW,CAAC,CAGtB"}

package/dist/core/fetch.js

@@ -0,0 +1,76 @@
+// 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 { createEgressFetch as defaultCreateEgressFetch } 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 { extract as defaultExtract } from './extract.js';
+import { getBackend as defaultGetBackend } from './backends/registry.js';
+/**
+ * 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, options = {}, deps = {}) {
+    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 = { 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, work) {
+    const out = [];
+    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, options = {}, deps = {}) {
+    const [result] = await fetchAll([url], options, deps);
+    return result;
+}
+//# sourceMappingURL=fetch.js.map

package/dist/core/fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.js","sourceRoot":"","sources":["../../src/core/fetch.ts"],"names":[],"mappings":"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"}

package/dist/core/http.d.ts

@@ -0,0 +1,8 @@
+import { type Dispatcher } from 'undici';
+import type { Http } from './backends/types.js';
+/**
+ * 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 declare function createHttp(dispatcher: Dispatcher | undefined): Http;
+//# sourceMappingURL=http.d.ts.map

package/dist/core/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/core/http.ts"],"names":[],"mappings":"AAKA,OAAO,EAAC,KAAK,UAAU,EAAuB,MAAM,QAAQ,CAAC;AAC7D,OAAO,KAAK,EAAC,IAAI,EAAqB,MAAM,qBAAqB,CAAC;AA8BlE;;;GAGG;AACH,wBAAgB,UAAU,CAAC,UAAU,EAAE,UAAU,GAAG,SAAS,GAAG,IAAI,CAqBnE"}

package/dist/core/http.js

@@ -0,0 +1,49 @@
+// 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 { fetch as undiciFetch } from 'undici';
+const DEFAULT_TIMEOUT_MS = 30_000;
+async function request(dispatcher, url, options = {}) {
+    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,
+        });
+        return res;
+    }
+    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) {
+    return {
+        async fetchJson(url, options) {
+            const res = await request(dispatcher, url, options);
+            if (!res.ok)
+                throw new Error(`http ${res.status} ${res.statusText} for ${url}`);
+            return (await res.json());
+        },
+        async fetchText(url, options) {
+            const res = await request(dispatcher, url, options);
+            if (!res.ok)
+                throw new Error(`http ${res.status} ${res.statusText} for ${url}`);
+            return await res.text();
+        },
+    };
+}
+//# sourceMappingURL=http.js.map

package/dist/core/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/core/http.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,iFAAiF;AACjF,gFAAgF;AAChF,4DAA4D;AAE5D,OAAO,EAAkB,KAAK,IAAI,WAAW,EAAC,MAAM,QAAQ,CAAC;AAG7D,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAElC,KAAK,UAAU,OAAO,CACrB,UAAkC,EAClC,GAAW,EACX,UAA8B,EAAE;IAEhC,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,kBAAkB,CAAC;IAC1D,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,SAAS,CAAC,CAAC;IAC9D,IAAI,OAAO,CAAC,MAAM;QACjB,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE;YAClE,IAAI,EAAE,IAAI;SACV,CAAC,CAAC;IACJ,IAAI,CAAC;QACJ,MAAM,GAAG,GAAG,MAAM,WAAW,CAAC,GAAG,EAAE;YAClC,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,MAAM,EAAE,UAAU,CAAC,MAAM;YACzB,UAAU;SACD,CAAC,CAAC;QACZ,OAAO,GAA0B,CAAC;IACnC,CAAC;YAAS,CAAC;QACV,YAAY,CAAC,KAAK,CAAC,CAAC;IACrB,CAAC;AACF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,UAAkC;IAC5D,OAAO;QACN,KAAK,CAAC,SAAS,CACd,GAAW,EACX,OAA4B;YAE5B,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,UAAU,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;YACpD,IAAI,CAAC,GAAG,CAAC,EAAE;gBACV,MAAM,IAAI,KAAK,CAAC,QAAQ,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,UAAU,QAAQ,GAAG,EAAE,CAAC,CAAC;YACpE,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAM,CAAC;QAChC,CAAC;QACD,KAAK,CAAC,SAAS,CACd,GAAW,EACX,OAA4B;YAE5B,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,UAAU,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;YACpD,IAAI,CAAC,GAAG,CAAC,EAAE;gBACV,MAAM,IAAI,KAAK,CAAC,QAAQ,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,UAAU,QAAQ,GAAG,EAAE,CAAC,CAAC;YACpE,OAAO,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;QACzB,CAAC;KACD,CAAC;AACH,CAAC"}

package/dist/core/search.d.ts

@@ -0,0 +1,34 @@
+import type { Config, ResolveOptions } from './config.js';
+import type { Dispatcher } from './egress.js';
+import type { BackendTransport } from './baseurl.js';
+import type { Http, SearchOptions, SearchResult } from './backends/types.js';
+/**
+ * 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 {
+}
+/**
+ * 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 declare function search(query: string, options?: SearchCoreOptions, deps?: SearchDeps): Promise<SearchResult[]>;
+//# sourceMappingURL=search.d.ts.map

package/dist/core/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/core/search.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAC,MAAM,EAAE,cAAc,EAAC,MAAM,aAAa,CAAC;AAKxD,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,aAAa,CAAC;AAE5C,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,cAAc,CAAC;AAGnD,OAAO,KAAK,EAAC,IAAI,EAAE,aAAa,EAAE,YAAY,EAAC,MAAM,qBAAqB,CAAC;AAU3E;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IAC1B,aAAa,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,cAAc,KAAK,MAAM,CAAC;IACrD,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,UAAU,GAAG,SAAS,CAAC;IAC7D,yBAAyB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACrD,uBAAuB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,gBAAgB,CAAC;IAChE,UAAU,CAAC,EAAE,CAAC,UAAU,EAAE,UAAU,GAAG,SAAS,KAAK,IAAI,CAAC;IAC1D,UAAU,CAAC,EAAE,CACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,KACV;QACJ,MAAM,EAAE,CACP,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,IAAI,EACV,OAAO,CAAC,EAAE,aAAa,KACnB,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;KAC7B,CAAC;CACF;AAED,iFAAiF;AACjF,MAAM,WAAW,iBAAkB,SAAQ,aAAa,EAAE,cAAc;CAAG;AAc3E;;;;;;;GAOG;AACH,wBAAsB,MAAM,CAC3B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,iBAAsB,EAC/B,IAAI,GAAE,UAAe,GACnB,OAAO,CAAC,YAAY,EAAE,CAAC,CAqDzB"}

package/dist/core/search.js

@@ -0,0 +1,92 @@
+// 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 { buildDispatcher as defaultBuildDispatcher, assertEgressAllowsBaseUrl as defaultAssertEgressAllowsBaseUrl, } from './egress.js';
+import { resolveBackendTransport as defaultResolveBackendTransport } from './baseurl.js';
+import { createHttp as defaultCreateHttp } from './http.js';
+import { getBackend as defaultGetBackend } from './backends/registry.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;
+/** Dedup by url (the hit's identity), preserving first-seen order. */
+function dedup(results) {
+    const seen = new Set();
+    const out = [];
+    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, options = {}, deps = {}) {
+    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 = 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;
+    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);
+}
+//# sourceMappingURL=search.js.map

package/dist/core/search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../../src/core/search.ts"],"names":[],"mappings":"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"}

package/dist/core/security.d.ts

@@ -0,0 +1,35 @@
+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 declare class SsrfError extends Error {
+    constructor(message: string);
+}
+/**
+ * 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 declare function isPrivateIp(ip: string): boolean;
+/**
+ * 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 declare function assertPublicUrl(url: string, config: Config): Promise<void>;
+/**
+ * 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 declare function guardEgressFetch(fetch: EgressFetch, config: Config): EgressFetch;
+//# sourceMappingURL=security.d.ts.map

package/dist/core/security.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"security.d.ts","sourceRoot":"","sources":["../../src/core/security.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,aAAa,CAAC;AACxC,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,aAAa,CAAC;AAE7C,iFAAiF;AACjF,qBAAa,SAAU,SAAQ,KAAK;gBACvB,OAAO,EAAE,MAAM;CAI3B;AAOD;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAK/C;AAuCD;;;;;GAKG;AACH,wBAAsB,eAAe,CACpC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,CAAC,CAsBf;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC/B,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,MAAM,GACZ,WAAW,CAWb"}