@pentoshi/clai 0.10.5 → 0.11.1

package/dist/tools/web/redact.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Header / cookie redaction and audit-log stripping for `web.fetch`.
+ *
+ * This module is the single source of truth for the
+ * {@link HeaderMap} format described in Requirement 2.21 (lower-cased keys,
+ * repeat values joined with `", "`, per-value 4096-char cap with the
+ * literal `[...truncated]` marker). It also implements the redaction rules
+ * required by 2.22 / 2.32 and the audit-log strip required by 5.11–5.13.
+ *
+ * See `.kiro/specs/web-search-and-fetch/design.md` "Redaction strategy"
+ * for the broader picture.
+ */
+import { type CookieInfo, type CookieSameSite, type HeaderMap } from "./types.js";
+/**
+ * Case-insensitive set of header names whose values are considered
+ * sensitive. Stored lower-cased so callers can match them against
+ * already-normalized {@link HeaderMap} keys without re-casing.
+ *
+ * Mirrors Requirement 5.12 / design "Redaction strategy".
+ */
+export declare const SENSITIVE_HEADERS: ReadonlySet<string>;
+/**
+ * Ordered list of `[name, value]` pairs, the most general header input
+ * shape. Repeats of the same name are preserved in the order observed and
+ * are joined by {@link applyToHeaders} per RFC 7230.
+ *
+ * Callers that have a Node `http.IncomingMessage.rawHeaders` array (a flat
+ * `string[]` of alternating name/value entries) can convert it with
+ *
+ * ```ts
+ * const pairs: HeaderEntries = [];
+ * for (let i = 0; i < raw.length; i += 2) pairs.push([raw[i]!, raw[i + 1]!]);
+ * ```
+ */
+export type HeaderEntries = ReadonlyArray<readonly [string, string]>;
+/**
+ * Reduced cookie shape produced by {@link stripForAudit}: only the
+ * non-secret public attributes named by Requirement 5.11 are kept. The
+ * cookie's `value`, `expires`, and `maxAge` fields are intentionally
+ * absent — the audit log never carries cookie values nor any field that
+ * could leak session lifetime back to a third party.
+ */
+export interface AuditSafeCookie {
+    name: string;
+    domain?: string;
+    path?: string;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: CookieSameSite;
+}
+/**
+ * Output shape of {@link stripForAudit}: a header map with every
+ * sensitive header dropped and a cookies list with every value-bearing
+ * field removed. Both fields are always present (possibly empty) so the
+ * caller can spread them into an audit payload without `undefined` checks.
+ */
+export interface AuditSafePayload {
+    headers: HeaderMap;
+    cookies: AuditSafeCookie[];
+}
+/**
+ * Normalize a set of HTTP response headers into the canonical
+ * {@link HeaderMap} format documented in Requirement 2.21.
+ *
+ * Steps applied, in order:
+ * 1. Lower-case every header name.
+ * 2. Join repeated values for the same name with `", "` (RFC 7230).
+ * 3. If `redactSensitive=true` and the lower-cased name is in
+ *    {@link SENSITIVE_HEADERS}, replace the joined value with the literal
+ *    {@link REDACTED_PLACEHOLDER}.
+ * 4. Otherwise, if the joined value's character length exceeds
+ *    {@link MAX_HEADER_VALUE_LENGTH}, slice it to the cap and append
+ *    {@link TRUNCATION_MARKER}.
+ *
+ * Accepts either a flat {@link HeaderMap} (already deduplicated by the
+ * caller) or a list of `[name, value]` pairs ({@link HeaderEntries}). The
+ * pair form preserves repeats — a `Set-Cookie` header that appears three
+ * times will produce three entries that this function joins. The flat-map
+ * form is convenient for callers that already have a `Record<string,
+ * string>`; in that case there are no repeats to join.
+ *
+ * The function is the single source of truth for the
+ * {@link HeaderMap} format. Both the user-facing fetch result and the
+ * audit-log path go through it (the audit path additionally calls
+ * {@link stripForAudit} to drop sensitive entries entirely).
+ */
+export declare function applyToHeaders(input: HeaderMap | HeaderEntries, redactSensitive: boolean): HeaderMap;
+/**
+ * Apply the cookie-value redaction rule from Requirement 2.32.
+ *
+ * Returns a fresh array of fresh {@link CookieInfo} objects so the caller
+ * can mutate the result without aliasing the inputs:
+ * - When `redactSensitive=true`: every entry's `value` is replaced with
+ *   the literal {@link REDACTED_PLACEHOLDER}; all other attributes
+ *   (`name`, `domain`, `path`, `expires`, `maxAge`, `httpOnly`, `secure`,
+ *   `sameSite`) are preserved unchanged.
+ * - When `redactSensitive=false`: every entry is shallow-copied verbatim.
+ */
+export declare function applyToCookies(cookies: readonly CookieInfo[], redactSensitive: boolean): CookieInfo[];
+/**
+ * Build the audit-log-safe view of a fetch's headers and cookies.
+ *
+ * Always-on guarantees, regardless of `redactSensitive`:
+ * - Every {@link SENSITIVE_HEADERS} entry is removed from the returned
+ *   header map (key and value both gone). The value never appears in any
+ *   form, including as `[REDACTED]` — the audit log simply does not
+ *   advertise that the header was present (Requirement 5.12).
+ * - Every cookie is reduced to the {@link AuditSafeCookie} shape:
+ *   `{name, domain, path, httpOnly, secure, sameSite}`. Cookie values,
+ *   `expires`, and `maxAge` are dropped (Requirements 5.11, 5.12).
+ *
+ * The remaining (non-sensitive) headers are passed through with their
+ * keys lower-cased so the caller does not need to re-normalize. Header
+ * values are not re-truncated here — they have already been processed by
+ * {@link applyToHeaders} on the way into `metadata.headers`.
+ *
+ * Both arguments are tolerant of `undefined` so the caller can hand off
+ * an optional `metadata.headers` / `metadata.cookies` directly.
+ */
+export declare function stripForAudit(headers: HeaderMap | undefined, cookies: readonly CookieInfo[] | undefined): AuditSafePayload;

package/dist/tools/web/redact.js

@@ -0,0 +1,155 @@
+/**
+ * Header / cookie redaction and audit-log stripping for `web.fetch`.
+ *
+ * This module is the single source of truth for the
+ * {@link HeaderMap} format described in Requirement 2.21 (lower-cased keys,
+ * repeat values joined with `", "`, per-value 4096-char cap with the
+ * literal `[...truncated]` marker). It also implements the redaction rules
+ * required by 2.22 / 2.32 and the audit-log strip required by 5.11–5.13.
+ *
+ * See `.kiro/specs/web-search-and-fetch/design.md` "Redaction strategy"
+ * for the broader picture.
+ */
+import { MAX_HEADER_VALUE_LENGTH, REDACTED_PLACEHOLDER, TRUNCATION_MARKER, } from "./types.js";
+/**
+ * Case-insensitive set of header names whose values are considered
+ * sensitive. Stored lower-cased so callers can match them against
+ * already-normalized {@link HeaderMap} keys without re-casing.
+ *
+ * Mirrors Requirement 5.12 / design "Redaction strategy".
+ */
+export const SENSITIVE_HEADERS = new Set([
+    "cookie",
+    "set-cookie",
+    "authorization",
+    "proxy-authorization",
+]);
+/**
+ * Normalize a set of HTTP response headers into the canonical
+ * {@link HeaderMap} format documented in Requirement 2.21.
+ *
+ * Steps applied, in order:
+ * 1. Lower-case every header name.
+ * 2. Join repeated values for the same name with `", "` (RFC 7230).
+ * 3. If `redactSensitive=true` and the lower-cased name is in
+ *    {@link SENSITIVE_HEADERS}, replace the joined value with the literal
+ *    {@link REDACTED_PLACEHOLDER}.
+ * 4. Otherwise, if the joined value's character length exceeds
+ *    {@link MAX_HEADER_VALUE_LENGTH}, slice it to the cap and append
+ *    {@link TRUNCATION_MARKER}.
+ *
+ * Accepts either a flat {@link HeaderMap} (already deduplicated by the
+ * caller) or a list of `[name, value]` pairs ({@link HeaderEntries}). The
+ * pair form preserves repeats — a `Set-Cookie` header that appears three
+ * times will produce three entries that this function joins. The flat-map
+ * form is convenient for callers that already have a `Record<string,
+ * string>`; in that case there are no repeats to join.
+ *
+ * The function is the single source of truth for the
+ * {@link HeaderMap} format. Both the user-facing fetch result and the
+ * audit-log path go through it (the audit path additionally calls
+ * {@link stripForAudit} to drop sensitive entries entirely).
+ */
+export function applyToHeaders(input, redactSensitive) {
+    // Group repeated header names. Ordering is preserved by the Map.
+    const grouped = new Map();
+    const entries = Array.isArray(input)
+        ? input
+        : Object.entries(input);
+    for (const [name, value] of entries) {
+        if (typeof name !== "string" || typeof value !== "string")
+            continue;
+        const key = name.toLowerCase();
+        const existing = grouped.get(key);
+        if (existing) {
+            existing.push(value);
+        }
+        else {
+            grouped.set(key, [value]);
+        }
+    }
+    const out = {};
+    for (const [key, values] of grouped) {
+        if (redactSensitive && SENSITIVE_HEADERS.has(key)) {
+            // The redacted placeholder is shorter than the cap and is a fixed
+            // marker; do not run it through the truncator.
+            out[key] = REDACTED_PLACEHOLDER;
+            continue;
+        }
+        const joined = values.join(", ");
+        out[key] =
+            joined.length > MAX_HEADER_VALUE_LENGTH
+                ? joined.slice(0, MAX_HEADER_VALUE_LENGTH) + TRUNCATION_MARKER
+                : joined;
+    }
+    return out;
+}
+/**
+ * Apply the cookie-value redaction rule from Requirement 2.32.
+ *
+ * Returns a fresh array of fresh {@link CookieInfo} objects so the caller
+ * can mutate the result without aliasing the inputs:
+ * - When `redactSensitive=true`: every entry's `value` is replaced with
+ *   the literal {@link REDACTED_PLACEHOLDER}; all other attributes
+ *   (`name`, `domain`, `path`, `expires`, `maxAge`, `httpOnly`, `secure`,
+ *   `sameSite`) are preserved unchanged.
+ * - When `redactSensitive=false`: every entry is shallow-copied verbatim.
+ */
+export function applyToCookies(cookies, redactSensitive) {
+    if (!redactSensitive) {
+        return cookies.map((c) => ({ ...c }));
+    }
+    return cookies.map((c) => ({ ...c, value: REDACTED_PLACEHOLDER }));
+}
+/**
+ * Build the audit-log-safe view of a fetch's headers and cookies.
+ *
+ * Always-on guarantees, regardless of `redactSensitive`:
+ * - Every {@link SENSITIVE_HEADERS} entry is removed from the returned
+ *   header map (key and value both gone). The value never appears in any
+ *   form, including as `[REDACTED]` — the audit log simply does not
+ *   advertise that the header was present (Requirement 5.12).
+ * - Every cookie is reduced to the {@link AuditSafeCookie} shape:
+ *   `{name, domain, path, httpOnly, secure, sameSite}`. Cookie values,
+ *   `expires`, and `maxAge` are dropped (Requirements 5.11, 5.12).
+ *
+ * The remaining (non-sensitive) headers are passed through with their
+ * keys lower-cased so the caller does not need to re-normalize. Header
+ * values are not re-truncated here — they have already been processed by
+ * {@link applyToHeaders} on the way into `metadata.headers`.
+ *
+ * Both arguments are tolerant of `undefined` so the caller can hand off
+ * an optional `metadata.headers` / `metadata.cookies` directly.
+ */
+export function stripForAudit(headers, cookies) {
+    const safeHeaders = {};
+    if (headers) {
+        for (const [key, value] of Object.entries(headers)) {
+            if (typeof key !== "string" || typeof value !== "string")
+                continue;
+            const lower = key.toLowerCase();
+            if (SENSITIVE_HEADERS.has(lower))
+                continue;
+            safeHeaders[lower] = value;
+        }
+    }
+    const safeCookies = [];
+    if (cookies) {
+        for (const c of cookies) {
+            const entry = { name: c.name };
+            if (c.domain !== undefined)
+                entry.domain = c.domain;
+            if (c.path !== undefined)
+                entry.path = c.path;
+            if (c.httpOnly !== undefined)
+                entry.httpOnly = c.httpOnly;
+            if (c.secure !== undefined)
+                entry.secure = c.secure;
+            if (c.sameSite !== undefined)
+                entry.sameSite = c.sameSite;
+            safeCookies.push(entry);
+        }
+    }
+    return { headers: safeHeaders, cookies: safeCookies };
+}
+//# sourceMappingURL=redact.js.map

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

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

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

@@ -0,0 +1,51 @@
+/**
+ * `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 type { ToolResult } from "../../types.js";
+import type { ToolRunOptions } from "../registry.js";
+import { type SearchProvider } from "./providers/provider.js";
+import "./providers/duckduckgo.js";
+import "./providers/brave.js";
+import "./providers/tavily.js";
+import { type SearchProviderId, type WebSearchArgs, type WebSearchErrorKind, type WebSearchOutcome } from "./types.js";
+/**
+ * Optional injection points for tests so the search dispatch can be
+ * exercised without invoking the real provider modules. Production
+ * callers never pass these.
+ */
+export interface WebSearchOptions extends ToolRunOptions {
+    /** Override the active provider lookup. */
+    provider?: SearchProviderId;
+    /** Override the registered {@link SearchProvider} for the active id. */
+    providerOverride?: SearchProvider;
+    /** Override the API-key resolver. Returns the raw key (or undefined). */
+    resolveKey?: (id: SearchProviderId) => Promise<string | undefined>;
+    /** Wall-clock timeout in milliseconds. Default: {@link SEARCH_TIMEOUT_MS}. */
+    timeoutMs?: number;
+}
+/**
+ * Run `web.search`. Always emits a single audit-log entry. Never
+ * throws — every failure mode surfaces as `ok=false`.
+ */
+export declare function webSearch(args: WebSearchArgs, options?: WebSearchOptions): Promise<ToolResult>;
+export type { WebSearchOutcome, WebSearchErrorKind };