@pentoshi/clai 0.10.5 → 0.11.0

package/dist/tools/web/search.js

@@ -0,0 +1,389 @@
+/**
+ * `web.search` registry handler.
+ *
+ * Resolves the active {@link SearchProviderId}, looks up the API key (if
+ * needed), dispatches a single outbound request via the registered
+ * adapter, validates each returned hit per Requirement 7.3, truncates to
+ * `maxResults`, and emits exactly one structured audit-log entry per
+ * invocation (Requirement 5.5).
+ *
+ * Error handling mirrors the design's error matrix: timeouts (1.8),
+ * missing keys (3.4), provider auth failures (6.1), rate limiting (6.2),
+ * network failures (6.3), parse failures (6.5), 5xx (6.6), and other
+ * non-2xx (1.9). Every failure surfaces as `ok=false` with a categorical
+ * `error.kind` and a human-readable message that names the active
+ * provider.
+ *
+ * Per Requirement 6.7 the handler issues exactly one outbound request
+ * attempt — there is no retry on transient failure.
+ *
+ * The provider modules register themselves into the shared
+ * {@link searchProviders} registry on import; we eagerly import them
+ * here so `web.search` can be invoked without any lazy-load surprises.
+ */
+import { auditLog } from "../../store/logs.js";
+import { getActiveSearchProvider } from "../../store/config.js";
+import { getSearchProviderKey } from "../../store/keys.js";
+import { buildSearchAuditPayload } from "./audit.js";
+import { searchProviders, } from "./providers/provider.js";
+// Importing the provider modules below ensures their side-effect
+// registration into `searchProviders` runs before the handler is
+// invoked. (DDG → keyless default; Brave / Tavily → optional.)
+import "./providers/duckduckgo.js";
+import "./providers/brave.js";
+import "./providers/tavily.js";
+import { DEFAULT_MAX_RESULTS, MAX_MAX_RESULTS, MAX_QUERY_LENGTH, MAX_SNIPPET_LENGTH, MAX_TITLE_LENGTH, MIN_MAX_RESULTS, MIN_QUERY_LENGTH, SEARCH_TIMEOUT_MS, } from "./types.js";
+/**
+ * Run `web.search`. Always emits a single audit-log entry. Never
+ * throws — every failure mode surfaces as `ok=false`.
+ */
+export async function webSearch(args, options = {}) {
+    // Validate args before resolving the provider so a malformed call
+    // never appears in the audit log under a real provider's id.
+    const validated = validateArgs(args);
+    if (!validated.ok) {
+        const provider = options.provider ?? safeProvider();
+        const outcome = {
+            ok: false,
+            provider,
+            results: [],
+            error: {
+                kind: "validation",
+                provider,
+                message: validated.message,
+            },
+        };
+        void emitAudit(outcome, validated.queryLength);
+        return errorResult(outcome);
+    }
+    const trimmedQuery = validated.query;
+    const maxResults = validated.maxResults;
+    // Resolve the active provider (Requirement 3.5: defaults to
+    // DuckDuckGo when no key configured).
+    const providerId = options.provider ?? safeProvider();
+    const provider = options.providerOverride ?? searchProviders[providerId];
+    if (!provider) {
+        const outcome = {
+            ok: false,
+            provider: providerId,
+            results: [],
+            error: {
+                kind: "validation",
+                provider: providerId,
+                message: `Unknown search provider "${providerId}". Set a supported provider via \`clai search-provider <id>\`.`,
+            },
+        };
+        void emitAudit(outcome, trimmedQuery.length);
+        return errorResult(outcome);
+    }
+    // Resolve API key (env > keychain > fallback file).
+    let apiKey;
+    if (provider.needsApiKey) {
+        apiKey = await (options.resolveKey
+            ? options.resolveKey(providerId)
+            : (await getSearchProviderKey(providerId)).value);
+        if (!apiKey || apiKey.length === 0) {
+            const outcome = {
+                ok: false,
+                provider: providerId,
+                results: [],
+                error: {
+                    kind: "missing-key",
+                    provider: providerId,
+                    message: `${provider.displayName} requires an API key. Run \`clai set ${providerId} <KEY>\`.`,
+                },
+            };
+            void emitAudit(outcome, trimmedQuery.length);
+            return errorResult(outcome);
+        }
+    }
+    // Arm the 15-second invocation timeout (Requirement 1.8) and
+    // propagate any caller-supplied AbortSignal so SIGINT etc. still
+    // collapse the in-flight request.
+    const timeoutMs = options.timeoutMs ?? SEARCH_TIMEOUT_MS;
+    const controller = new AbortController();
+    const onCallerAbort = () => controller.abort();
+    if (options.signal) {
+        if (options.signal.aborted)
+            controller.abort();
+        else
+            options.signal.addEventListener("abort", onCallerAbort);
+    }
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    // Do not pin the event loop on the timeout.
+    timer.unref?.();
+    // Dispatch (Requirement 6.7: exactly one attempt, no retry).
+    let raw;
+    try {
+        raw = await provider.search(trimmedQuery, maxResults, { ...(apiKey !== undefined ? { apiKey } : {}) }, controller.signal);
+    }
+    catch (err) {
+        clearTimeout(timer);
+        if (options.signal)
+            options.signal.removeEventListener("abort", onCallerAbort);
+        const outcome = controller.signal.aborted
+            ? buildTimeoutOutcome(provider.id, timeoutMs)
+            : buildNetworkOutcome(provider.id, err);
+        void emitAudit(outcome, trimmedQuery.length);
+        return errorResult(outcome);
+    }
+    finally {
+        clearTimeout(timer);
+        if (options.signal)
+            options.signal.removeEventListener("abort", onCallerAbort);
+    }
+    // Map provider HTTP status to a categorical WebSearchErrorKind.
+    const httpError = classifyHttpStatus(provider.id, raw);
+    if (httpError) {
+        const outcome = {
+            ok: false,
+            provider: provider.id,
+            results: [],
+            error: httpError,
+        };
+        void emitAudit(outcome, trimmedQuery.length);
+        return errorResult(outcome);
+    }
+    // 2xx with parseError surfaces as a `parse` failure (Requirement 6.5).
+    if (raw.parseError) {
+        const outcome = {
+            ok: false,
+            provider: provider.id,
+            results: [],
+            error: {
+                kind: "parse",
+                provider: provider.id,
+                message: `${provider.displayName}: response parse error (${raw.parseError})`,
+            },
+        };
+        void emitAudit(outcome, trimmedQuery.length);
+        return errorResult(outcome);
+    }
+    // Filter and validate hits per Requirement 7.3, then truncate.
+    const filtered = [];
+    for (const hit of raw.hits) {
+        if (filtered.length >= maxResults)
+            break;
+        const normalised = normaliseHit(hit);
+        if (!normalised)
+            continue;
+        filtered.push(normalised);
+    }
+    const outcome = {
+        ok: true,
+        provider: provider.id,
+        results: filtered,
+    };
+    void emitAudit(outcome, trimmedQuery.length);
+    return successResult(outcome);
+}
+/**
+ * Synchronous validation of {@link WebSearchArgs} per Requirements 1.1,
+ * 1.2, 1.5, 1.6. Returns the trimmed query and a concrete `maxResults`
+ * value so downstream code does not need to re-derive defaults.
+ */
+function validateArgs(args) {
+    const rawQuery = args?.query;
+    if (typeof rawQuery !== "string") {
+        return {
+            ok: false,
+            message: "query must be a string",
+            queryLength: 0,
+        };
+    }
+    const trimmed = rawQuery.trim();
+    const len = trimmed.length;
+    if (len < MIN_QUERY_LENGTH || len > MAX_QUERY_LENGTH) {
+        return {
+            ok: false,
+            message: `query length must be between ${MIN_QUERY_LENGTH} and ${MAX_QUERY_LENGTH} characters after trimming (got ${len})`,
+            queryLength: len,
+        };
+    }
+    let maxResults = DEFAULT_MAX_RESULTS;
+    if (args.maxResults !== undefined) {
+        if (typeof args.maxResults !== "number" ||
+            !Number.isInteger(args.maxResults) ||
+            args.maxResults < MIN_MAX_RESULTS ||
+            args.maxResults > MAX_MAX_RESULTS) {
+            return {
+                ok: false,
+                message: `maxResults must be an integer in [${MIN_MAX_RESULTS}, ${MAX_MAX_RESULTS}]`,
+                queryLength: len,
+            };
+        }
+        maxResults = args.maxResults;
+    }
+    return { ok: true, query: trimmed, maxResults, queryLength: len };
+}
+// ---------------------------------------------------------------------------
+// Hit normalisation (Requirement 7.3)
+// ---------------------------------------------------------------------------
+const URL_INVALID_CHARS_RE = /[\s\u0000-\u001f\u007f]/;
+function normaliseHit(hit) {
+    const url = typeof hit.url === "string" ? hit.url : "";
+    if (url.length === 0)
+        return undefined;
+    if (URL_INVALID_CHARS_RE.test(url))
+        return undefined;
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return undefined;
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        return undefined;
+    }
+    const title = typeof hit.title === "string" ? hit.title.trim() : "";
+    if (title.length === 0)
+        return undefined;
+    const clampedTitle = title.slice(0, MAX_TITLE_LENGTH);
+    const snippet = typeof hit.snippet === "string" ? hit.snippet : "";
+    const clampedSnippet = snippet.slice(0, MAX_SNIPPET_LENGTH);
+    return {
+        title: clampedTitle,
+        url,
+        snippet: clampedSnippet,
+    };
+}
+// ---------------------------------------------------------------------------
+// Error helpers
+// ---------------------------------------------------------------------------
+/**
+ * Map provider HTTP status codes to a {@link WebSearchErrorKind} per the
+ * design's error matrix. Returns `undefined` when the status is in the
+ * 2xx range so the caller can move on to body classification.
+ */
+function classifyHttpStatus(id, raw) {
+    const provider = searchProviders[id];
+    const displayName = provider?.displayName ?? id;
+    const { status } = raw;
+    if (status >= 200 && status < 300)
+        return undefined;
+    if (status === 401 || status === 403) {
+        return {
+            kind: "auth",
+            provider: id,
+            status,
+            message: `${displayName} authentication failed (HTTP ${status}). Run \`clai set ${id}\` to update the key.`,
+        };
+    }
+    if (status === 429) {
+        return {
+            kind: "rate-limit",
+            provider: id,
+            status,
+            message: `${displayName} rate-limited (HTTP 429). Retry later.`,
+        };
+    }
+    if (status >= 500 && status < 600) {
+        return {
+            kind: "server",
+            provider: id,
+            status,
+            message: `${displayName} server error (HTTP ${status}).`,
+        };
+    }
+    if (status === 0) {
+        return {
+            kind: "network",
+            provider: id,
+            message: `${displayName}: provider returned no response (status=0).`,
+        };
+    }
+    return {
+        kind: "http",
+        provider: id,
+        status,
+        message: `${displayName}: HTTP ${status}.`,
+    };
+}
+function buildTimeoutOutcome(id, timeoutMs) {
+    const display = searchProviders[id]?.displayName ?? id;
+    return {
+        ok: false,
+        provider: id,
+        results: [],
+        error: {
+            kind: "timeout",
+            provider: id,
+            message: `${display}: timeout after ${Math.round(timeoutMs / 1000)}s`,
+        },
+    };
+}
+function buildNetworkOutcome(id, err) {
+    const display = searchProviders[id]?.displayName ?? id;
+    const detail = err instanceof Error ? err.message : String(err);
+    return {
+        ok: false,
+        provider: id,
+        results: [],
+        error: {
+            kind: "network",
+            provider: id,
+            message: `${display}: network failure (${detail})`,
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Audit + ToolResult
+// ---------------------------------------------------------------------------
+async function emitAudit(outcome, queryLength) {
+    try {
+        await auditLog("tool.web_search", buildSearchAuditPayload(outcome, queryLength));
+    }
+    catch {
+        // never let audit failures bubble up
+    }
+}
+/**
+ * Best-effort active-provider lookup that never throws even when the
+ * config store is mid-migration or unreadable. Falls back to
+ * `"duckduckgo"` so a fresh install still works keylessly per
+ * Requirement 3.5.
+ */
+function safeProvider() {
+    try {
+        return getActiveSearchProvider();
+    }
+    catch {
+        return "duckduckgo";
+    }
+}
+/**
+ * Compose a successful {@link ToolResult}. The output starts with a one
+ * line summary so the agent sees the result count and provider before
+ * the JSON, then includes the structured `{results: [...]}` block.
+ */
+function successResult(outcome) {
+    if (outcome.results.length === 0) {
+        // Requirement 1.7 / 7.4: literal "No results found." string.
+        return {
+            ok: true,
+            output: "No results found.",
+            exitCode: 0,
+        };
+    }
+    const summary = `${outcome.provider}: ${outcome.results.length} result${outcome.results.length === 1 ? "" : "s"}`;
+    const json = JSON.stringify({ results: outcome.results }, null, 2);
+    return {
+        ok: true,
+        output: `${summary}\n\n${json}`,
+        exitCode: 0,
+    };
+}
+function errorResult(outcome) {
+    const head = outcome.error?.message ?? "web.search failed";
+    const json = JSON.stringify({
+        error: outcome.error,
+        provider: outcome.provider,
+    }, null, 2);
+    return {
+        ok: false,
+        output: `${head}\n\n${json}`,
+        exitCode: 1,
+    };
+}
+//# sourceMappingURL=search.js.map

package/dist/tools/web/search.js.map

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

package/dist/tools/web/ssrf-guard.d.ts

@@ -0,0 +1,85 @@
+/**
+ * SSRF guard — classifies an address (or a hostname literal) as belonging
+ * to a private/loopback/link-local/cloud-metadata/CGNAT range.
+ *
+ * The structured {@link classify} / {@link classifyHost} helpers are used
+ * by the `web.fetch` pipeline (synchronous classifier branch + per-hop
+ * resolution check) and by the safety classifier in
+ * `src/safety/classifier.ts`.
+ *
+ * The boolean {@link isBlockedAddress} re-export preserves the legacy shape
+ * used by `src/tools/http.ts` so existing `http.fetch` semantics are
+ * unchanged.
+ *
+ * Per the design (see `.kiro/specs/web-search-and-fetch/design.md`,
+ * "Sequencing of changes" step 2 and "Safety classifier integration"), this
+ * module is the single source of truth for address classification — both
+ * the legacy `http.fetch` SSRF check and the new `web.fetch` checks
+ * delegate here.
+ */
+/**
+ * Categorical address class returned by {@link classify} and
+ * {@link classifyHost} when the input belongs to a non-public range.
+ *
+ * Mappings:
+ * - `loopback`         — 127.0.0.0/8, IPv6 `::1`, and the
+ *                         `localhost` / `ip6-localhost` hostname literals.
+ * - `rfc1918`          — 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, and
+ *                         IPv6 ULA `fc00::/7` (the IPv6 private-use range,
+ *                         grouped here as RFC1918's IPv6 cousin).
+ * - `ipv4-link-local`  — 169.254.0.0/16 except the cloud-metadata literal.
+ * - `ipv6-link-local`  — `fe80::/10`.
+ * - `cloud-metadata`   — `169.254.169.254` (IPv4 EC2/AWS, GCP, Azure
+ *                         metadata) and `fd00:ec2::254` (IPv6 EC2 metadata).
+ * - `cgnat`            — 100.64.0.0/10 (RFC 6598 carrier-grade NAT).
+ */
+export type AddressClass = "loopback" | "rfc1918" | "ipv4-link-local" | "ipv6-link-local" | "cloud-metadata" | "cgnat";
+/** Result shape returned by {@link classify} and {@link classifyHost}. */
+export interface AddressClassification {
+    class: AddressClass;
+}
+/**
+ * Return `true` iff `url` parses as an absolute URL whose scheme is exactly
+ * `http:` or `https:`. Returns `false` for any other scheme (including
+ * `ftp:`, `file:`, `data:`, `javascript:`, `gopher:`), for empty strings,
+ * for malformed inputs that fail `new URL()` parsing, and for non-string
+ * inputs.
+ *
+ * This is the synchronous half of the "scheme allowlist" check enforced
+ * by the `web.fetch` pipeline (see Requirement 5.4 / 2.1). It is the
+ * single source of truth for the scheme allow-list so the safety
+ * classifier branch and the fetch-core argument validator stay in sync.
+ */
+export declare function isAllowedScheme(url: string): boolean;
+/**
+ * Classify a literal IP address (IPv4 or IPv6).
+ *
+ * Returns `{ class }` when the address falls into one of the
+ * {@link AddressClass} buckets, or `null` when the input is a
+ * globally-routable address (or fails to parse as either family).
+ *
+ * The check is fully synchronous and never performs DNS.
+ */
+export declare function classify(ip: string): AddressClassification | null;
+/**
+ * Classify a hostname or IP literal without performing DNS resolution.
+ *
+ * - For literal IPv4/IPv6 addresses (with or without surrounding `[…]`
+ *   brackets), this delegates to {@link classify}.
+ * - For known-bad hostname literals (`localhost`, `localhost.localdomain`,
+ *   `ip6-localhost`, `ip6-loopback`), this returns `{ class: "loopback" }`.
+ * - For every other hostname, this returns `null` (the caller is
+ *   responsible for the DNS-resolved second pass; see
+ *   `src/tools/web/fetch-core.ts`).
+ */
+export declare function classifyHost(hostname: string): AddressClassification | null;
+/**
+ * Legacy boolean shape preserved for the existing `http.fetch` SSRF check.
+ *
+ * Returns `true` whenever {@link classifyHost} would return a non-null
+ * classification, plus a small additional set of historically-blocked
+ * ranges (currently `0.0.0.0/8`, the "this network" range) that are kept
+ * for backward compatibility with the previous `http.ts` implementation
+ * but are not enumerated in the public {@link AddressClass} list.
+ */
+export declare function isBlockedAddress(host: string): boolean;