@frockbot/plugin-web 0.0.0 → 0.1.1

package/src/contract.ts

@@ -0,0 +1,218 @@
+// The provider-neutral web-search contract.
+//
+// The register (`docs/research/grokbot-computer.md:564`, row 47) names web
+// search as a first-class tool but records no schema, no bound, and no error
+// shape for it: none was ever measured. Everything here is FrockBot's own
+// contract, defined from first principles, and it is deliberately narrower
+// than any one provider's API so a second provider can satisfy it unchanged —
+// the two-provider check the constitution applies to the model interface.
+//
+// This module holds no transport. `plugin-provider-ollama-cloud` implements
+// {@link WebSearchV1} over `POST {apiBaseUrl}/api/web_search`; this Package
+// never imports it.
+import type { ToolDefinition, ToolSchema } from "@frockbot/kernel-contracts";
+
+export const WEB_SEARCH_TOOL_NAME_V1 = "web_search";
+
+/** Input bounds. A query longer than this is a paste, not a search. */
+export const WEB_SEARCH_MAX_QUERY_LENGTH_V1 = 400;
+export const WEB_SEARCH_MIN_RESULTS_V1 = 1;
+export const WEB_SEARCH_MAX_RESULTS_V1 = 10;
+export const WEB_SEARCH_DEFAULT_RESULTS_V1 = 5;
+
+/**
+ * Output bounds. A snippet is an orientation aid, not the page: a Bot that
+ * wants the page calls `web_fetch`. Truncating here keeps one search from
+ * spending a Turn's context, and keeps the durable `tool/result` small.
+ */
+export const WEB_SEARCH_MAX_SNIPPET_LENGTH_V1 = 1000;
+
+export interface WebSearchResultV1 {
+  title: string;
+  url: string;
+  snippet: string;
+}
+
+export interface WebSearchResponseV1 {
+  query: string;
+  results: WebSearchResultV1[];
+}
+
+export interface WebSearchRequestV1 {
+  query: string;
+  maxResults: number;
+}
+
+/**
+ * What one search runs under: the durable effect identity of the tool call and
+ * its cancellation signal. Both are kernel vocabulary, not provider
+ * vocabulary — a provider that needs a per-call credential lease keys it on
+ * `effectId`, and one that needs neither ignores both.
+ */
+export interface WebSearchExecutionV1 {
+  effectId: string;
+  signal: AbortSignal;
+}
+
+/** The narrow interface a search provider Package implements. */
+export interface WebSearchV1 {
+  search(
+    request: WebSearchRequestV1,
+    execution: WebSearchExecutionV1,
+  ): Promise<WebSearchResponseV1>;
+}
+
+export const WEB_SEARCH_INPUT_SCHEMA_V1: ToolSchema["inputSchema"] = {
+  type: "object",
+  properties: {
+    query: {
+      type: "string",
+      description: "What to search the public web for.",
+      minLength: 1,
+      maxLength: WEB_SEARCH_MAX_QUERY_LENGTH_V1,
+    },
+    max_results: {
+      type: "integer",
+      description: `How many results to return, ${WEB_SEARCH_MIN_RESULTS_V1}–${WEB_SEARCH_MAX_RESULTS_V1}. Defaults to ${WEB_SEARCH_DEFAULT_RESULTS_V1}.`,
+      minimum: WEB_SEARCH_MIN_RESULTS_V1,
+      maximum: WEB_SEARCH_MAX_RESULTS_V1,
+    },
+  },
+  required: ["query"],
+  additionalProperties: false,
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Decode the model's arguments at the tool seam. Throws with a plain reason. */
+export function decodeWebSearchInputV1(input: unknown): WebSearchRequestV1 {
+  if (!isRecord(input)) throw new Error("web_search input must be an object");
+  const query = typeof input.query === "string" ? input.query.trim() : "";
+  if (query.length === 0 || query.length > WEB_SEARCH_MAX_QUERY_LENGTH_V1) {
+    throw new Error(
+      `web_search query must be 1–${WEB_SEARCH_MAX_QUERY_LENGTH_V1} characters`,
+    );
+  }
+  const requested = input.max_results ?? WEB_SEARCH_DEFAULT_RESULTS_V1;
+  if (
+    typeof requested !== "number" ||
+    !Number.isSafeInteger(requested) ||
+    requested < WEB_SEARCH_MIN_RESULTS_V1 ||
+    requested > WEB_SEARCH_MAX_RESULTS_V1
+  ) {
+    throw new Error(
+      `web_search max_results must be an integer ${WEB_SEARCH_MIN_RESULTS_V1}–${WEB_SEARCH_MAX_RESULTS_V1}`,
+    );
+  }
+  return { query, maxResults: requested };
+}
+
+function boundedSnippet(value: unknown): string {
+  const text =
+    typeof value === "string" ? value.replace(/\s+/g, " ").trim() : "";
+  return text.slice(0, WEB_SEARCH_MAX_SNIPPET_LENGTH_V1);
+}
+
+/**
+ * Decode a provider's answer at the seam it crosses. Anything the provider
+ * adds is dropped, a result with no usable `url` is dropped, and the list is
+ * trimmed to what was asked for — the model never sees a provider's shape.
+ */
+export function decodeWebSearchResponseV1(
+  value: unknown,
+  request: WebSearchRequestV1,
+): WebSearchResponseV1 {
+  if (!isRecord(value)) throw new Error("web search response is invalid");
+  const rows = value.results;
+  if (!Array.isArray(rows)) throw new Error("web search response is invalid");
+  const results: WebSearchResultV1[] = [];
+  for (const row of rows) {
+    if (results.length >= request.maxResults) break;
+    if (!isRecord(row)) continue;
+    const url = typeof row.url === "string" ? row.url.trim() : "";
+    if (url.length === 0 || url.length > 2048) continue;
+    const title = typeof row.title === "string" ? row.title.trim() : "";
+    results.push({
+      title: title.slice(0, 300),
+      url,
+      // Ollama names the field `content`; the contract names it `snippet`.
+      snippet: boundedSnippet(row.snippet ?? row.content ?? row.description),
+    });
+  }
+  return { query: request.query, results };
+}
+
+/**
+ * The durable `tool/result` body. The kernel event carries `content: string`
+ * (`kernel-contracts/src/types.ts`), so every tool emits stable JSON rather
+ * than prose: a later reader parses it instead of re-reading a sentence.
+ */
+export function encodeWebSearchResultV1(response: WebSearchResponseV1): string {
+  return JSON.stringify(response);
+}
+
+/**
+ * Build the `web_search` tool over any {@link WebSearchV1}. The definition,
+ * its bounds, and its durable result shape live here so a second provider
+ * Package contributes the same tool by supplying transport alone.
+ *
+ * `idempotent: true`: a search is read-only, so recovery after eviction
+ * re-runs it rather than reconciling a recorded effect.
+ */
+export function createWebSearchToolDefinitionV1(
+  provider: WebSearchV1,
+): ToolDefinition {
+  return {
+    name: WEB_SEARCH_TOOL_NAME_V1,
+    // A general work tool: the reach an `executor` subagent has, and not the
+    // narrow reach of `browserUse`, `computerUse`, or the two video roles.
+    admission: { subagentRoles: ["executor"] },
+    description:
+      "Search the public web and return titles, URLs and short snippets. Use web_fetch to read a result in full.",
+    inputSchema: WEB_SEARCH_INPUT_SCHEMA_V1,
+    idempotent: true,
+    validate: (input: unknown) => {
+      try {
+        decodeWebSearchInputV1(input);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    execute: async (input, context) => {
+      let request: WebSearchRequestV1;
+      try {
+        request = decodeWebSearchInputV1(input);
+      } catch (error) {
+        return {
+          content: JSON.stringify({
+            error: "web-search-invalid-input",
+            message: error instanceof Error ? error.message : "invalid input",
+          }),
+          isError: true,
+        };
+      }
+      try {
+        const response = await provider.search(request, {
+          effectId: context.effectId,
+          signal: context.signal,
+        });
+        return { content: encodeWebSearchResultV1(response), isError: false };
+      } catch (error) {
+        return {
+          content: JSON.stringify({
+            error: "web-search-failed",
+            query: request.query,
+            message: (error instanceof Error
+              ? error.message
+              : "web search failed"
+            ).slice(0, 500),
+          }),
+          isError: true,
+        };
+      }
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from "./contract.js";
+export * from "./ssrf.js";
+export * from "./agent.js";
+export { default as manifest } from "./manifest.js";

package/src/manifest.ts

@@ -0,0 +1,3 @@
+import manifest from "../frockbot.json" with { type: "json" };
+
+export default manifest;

package/src/ssrf.test.ts

@@ -0,0 +1,174 @@
+import { describe, expect, test } from "bun:test";
+import {
+  classifyOutboundUrlV1,
+  classifyWebFetchUrlV1,
+  parseIpv4LiteralV1,
+  parseIpv6LiteralV1,
+  type SsrfRefusalReasonV1,
+} from "./ssrf.ts";
+
+/**
+ * The classifier's whole contract, as a table. Each row is a URL a model could
+ * plausibly hand `web_fetch` and the verdict the Bot's outbound boundary must
+ * reach. `undefined` means the URL is allowed.
+ */
+const TABLE: ReadonlyArray<[string, SsrfRefusalReasonV1 | undefined]> = [
+  // Allowed: ordinary public sites, in the shapes they actually arrive in.
+  ["https://example.com/", undefined],
+  ["https://example.com:443/a/b?c=d#e", undefined],
+  ["https://sub.example.co.uk/page", undefined],
+  ["https://example.test/index.html", undefined],
+  ["https://1.1.1.1/", undefined],
+  ["https://8.8.8.8/resolve", undefined],
+  ["https://[2606:4700:4700::1111]/", undefined],
+  ["https://xn--bcher-kva.example/", undefined],
+
+  // Rule 1: scheme.
+  ["http://example.com/", "ssrf-blocked-scheme"],
+  ["http://169.254.169.254/latest/meta-data", "ssrf-blocked-scheme"],
+  ["ftp://example.com/", "ssrf-blocked-scheme"],
+  ["file:///etc/passwd", "ssrf-blocked-scheme"],
+  ["data:text/html,<b>hi</b>", "ssrf-blocked-scheme"],
+  ["blob:https://example.com/abc", "ssrf-blocked-scheme"],
+
+  // Rule 2: port.
+  ["https://example.com:8080/", "ssrf-blocked-port"],
+  ["https://example.com:22/", "ssrf-blocked-port"],
+
+  // Rule 5: credentials in the URL.
+  ["https://user:pass@example.com/", "ssrf-blocked-credentials"],
+  ["https://user@example.com/", "ssrf-blocked-credentials"],
+
+  // Rule 3: names that are not the public internet.
+  ["https://localhost/", "ssrf-blocked-host"],
+  ["https://server.local/", "ssrf-blocked-host"],
+  ["https://printer.home.arpa/", "ssrf-blocked-host"],
+  ["https://api.localhost/", "ssrf-blocked-host"],
+  ["https://metadata.google.internal/computeMetadata/v1/", "ssrf-blocked-host"],
+  ["https://foo.internal/", "ssrf-blocked-host"],
+  ["https://redis/", "ssrf-blocked-host"],
+  ["https://metadata/", "ssrf-blocked-host"],
+
+  // Rule 4: IPv4, in every encoding the host parser accepts.
+  ["https://169.254.169.254/latest/meta-data", "ssrf-blocked-private-address"],
+  ["https://127.0.0.1/", "ssrf-blocked-private-address"],
+  ["https://0177.0.0.1/", "ssrf-blocked-private-address"],
+  ["https://2130706433/", "ssrf-blocked-private-address"],
+  ["https://0x7f000001/", "ssrf-blocked-private-address"],
+  ["https://0x7f.1/", "ssrf-blocked-private-address"],
+  ["https://127.1/", "ssrf-blocked-private-address"],
+  ["https://10.0.0.5/", "ssrf-blocked-private-address"],
+  ["https://172.16.0.1/", "ssrf-blocked-private-address"],
+  ["https://192.168.1.1/", "ssrf-blocked-private-address"],
+  ["https://100.64.0.1/", "ssrf-blocked-private-address"],
+  ["https://198.18.0.1/", "ssrf-blocked-private-address"],
+  ["https://192.0.0.1/", "ssrf-blocked-private-address"],
+  ["https://0.0.0.0/", "ssrf-blocked-private-address"],
+  ["https://255.255.255.255/", "ssrf-blocked-private-address"],
+  ["https://239.0.0.1/", "ssrf-blocked-private-address"],
+
+  // Rule 4: IPv6, including the mapped and compatible forms.
+  ["https://[::1]/", "ssrf-blocked-private-address"],
+  ["https://[::]/", "ssrf-blocked-private-address"],
+  ["https://[::ffff:127.0.0.1]/", "ssrf-blocked-private-address"],
+  ["https://[::ffff:8.8.8.8]/", "ssrf-blocked-private-address"],
+  ["https://[fd00::1]/", "ssrf-blocked-private-address"],
+  ["https://[fe80::1]/", "ssrf-blocked-private-address"],
+  ["https://[ff02::1]/", "ssrf-blocked-private-address"],
+
+  // Not URLs at all.
+  ["", "ssrf-invalid-url"],
+  ["not a url", "ssrf-invalid-url"],
+  ["/relative/path", "ssrf-invalid-url"],
+];
+
+describe("the web_fetch outbound classifier", () => {
+  for (const [candidate, expected] of TABLE) {
+    test(`${expected ?? "allows"} ${candidate || "(empty)"}`, () => {
+      const verdict = classifyWebFetchUrlV1(candidate);
+      if (expected === undefined) {
+        expect({ candidate, allowed: verdict.allowed }).toEqual({
+          candidate,
+          allowed: true,
+        });
+        return;
+      }
+      expect({
+        candidate,
+        reason: verdict.allowed ? undefined : verdict.reason,
+      }).toEqual({ candidate, reason: expected });
+    });
+  }
+
+  test("refuses a redirect that leaves the public internet", () => {
+    // The first hop is a legitimate public URL; the `Location` is not. Only
+    // re-running the classifier on the resolved target catches this, which is
+    // exactly what `web_fetch` does on every hop.
+    expect(classifyWebFetchUrlV1("https://redirector.example/go").allowed).toBe(
+      true,
+    );
+    const followed = classifyWebFetchUrlV1(
+      new URL(
+        "//169.254.169.254/latest/meta-data",
+        "https://redirector.example/go",
+      ).toString(),
+    );
+    expect(followed.allowed ? "allowed" : followed.reason).toBe(
+      "ssrf-blocked-private-address",
+    );
+  });
+
+  test("lets a caller that legitimately needs a port opt into one", () => {
+    // `web_fetch` refuses a non-default port; a User-named MCP endpoint on its
+    // own port is an ordinary deployment, so that caller opts in explicitly.
+    expect(
+      classifyWebFetchUrlV1("https://mcp.example.test:8443/mcp").allowed,
+    ).toBe(false);
+    expect(
+      classifyOutboundUrlV1("https://mcp.example.test:8443/mcp", {
+        allowNonDefaultPort: true,
+      }).allowed,
+    ).toBe(true);
+    // Opting into a port opts into nothing else.
+    const stillPrivate = classifyOutboundUrlV1("https://127.0.0.1:8443/", {
+      allowNonDefaultPort: true,
+    });
+    expect(stillPrivate.allowed ? "allowed" : stillPrivate.reason).toBe(
+      "ssrf-blocked-private-address",
+    );
+  });
+
+  test("never names a resolved address in a refusal", () => {
+    const verdict = classifyWebFetchUrlV1("https://169.254.169.254/");
+    expect(verdict.allowed).toBe(false);
+    if (verdict.allowed) return;
+    expect(verdict.message).not.toContain("169.254");
+  });
+
+  test("normalizes every IPv4 encoding to the same address", () => {
+    for (const candidate of [
+      "127.0.0.1",
+      "0177.0.0.1",
+      "2130706433",
+      "0x7f000001",
+      "127.1",
+    ]) {
+      expect({ candidate, octets: parseIpv4LiteralV1(candidate) }).toEqual({
+        candidate,
+        octets: [127, 0, 0, 1],
+      });
+    }
+    expect(parseIpv4LiteralV1("example.com")).toBeUndefined();
+    expect(parseIpv4LiteralV1("256.0.0.1")).toBeUndefined();
+  });
+
+  test("expands compressed and v4-embedded IPv6 literals", () => {
+    expect(parseIpv6LiteralV1("[::1]")).toEqual([
+      0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1,
+    ]);
+    expect(parseIpv6LiteralV1("::ffff:127.0.0.1")).toEqual([
+      0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 255, 255, 127, 0, 0, 1,
+    ]);
+    expect(parseIpv6LiteralV1("example.com")).toBeUndefined();
+  });
+});