@agent-native/core 0.14.8 → 0.15.1

package/dist/tools/fetch-tool.js

@@ -0,0 +1,178 @@
+/**
+ * Fetch tool — outbound HTTP for automations and agent use.
+ *
+ * Supports ${keys.NAME} reference substitution in URL, headers, and body.
+ * Values are resolved server-side AFTER the model emits the tool call —
+ * the raw secret never enters the model's context.
+ */
+import { collectSecretValues, MAX_TOOL_PROXY_RESPONSE_SIZE, normalizeToolProxyMethod, readResponseTextWithLimit, redactSecrets, redactString, sanitizeOutboundHeaders, } from "./proxy-security.js";
+import { isBlockedToolUrlWithDns } from "./url-safety.js";
+const DEFAULT_TIMEOUT_MS = 15_000;
+/**
+ * Create the fetch tool entry for the agent tool registry.
+ */
+export function createFetchToolEntry(opts = {}) {
+    return {
+        "web-request": {
+            tool: {
+                description: `Make an outbound HTTP request to EXTERNAL APIs, webhooks, and services only. Supports \${keys.NAME} placeholders in url, headers, and body — these are resolved server-side from the user's saved keys (the raw value never enters your context). Example: \${keys.SLACK_WEBHOOK} in the url field. IMPORTANT: Never use this to call internal /_agent-native/ endpoints or localhost action URLs — use the registered action tools directly (e.g. \`log-meal\`, \`bigquery\`, \`hubspot-deals\`). Actions are already available as native tools; calling them via HTTP is slower and bypasses validation.`,
+                parameters: {
+                    type: "object",
+                    properties: {
+                        url: {
+                            type: "string",
+                            description: 'Full URL. May contain ${keys.NAME} references, e.g. "${keys.SLACK_WEBHOOK}".',
+                        },
+                        method: {
+                            type: "string",
+                            description: "HTTP method. Default: GET.",
+                            enum: ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"],
+                        },
+                        headers: {
+                            type: "string",
+                            description: 'JSON object of headers. May contain ${keys.NAME} references. Example: \'{"Authorization": "Bearer ${keys.API_TOKEN}"}\'.',
+                        },
+                        body: {
+                            type: "string",
+                            description: "Request body (for POST/PUT/PATCH). May contain ${keys.NAME} references.",
+                        },
+                        timeout_ms: {
+                            type: "number",
+                            description: `Timeout in milliseconds. Default: ${DEFAULT_TIMEOUT_MS}. Max: 30000.`,
+                        },
+                    },
+                    required: ["url"],
+                },
+            },
+            run: async (args) => {
+                const startTime = Date.now();
+                const rawUrl = args.url;
+                const method = normalizeToolProxyMethod(args.method || "GET");
+                if (!method) {
+                    return "Unsupported HTTP method. Allowed methods: GET, POST, PUT, PATCH, DELETE, HEAD.";
+                }
+                const rawHeaders = args.headers || "{}";
+                const rawBody = args.body;
+                const timeoutMs = Math.min(Number(args.timeout_ms) || DEFAULT_TIMEOUT_MS, 30_000);
+                // Resolve key references
+                let resolvedUrl = rawUrl;
+                let resolvedHeaders = rawHeaders;
+                let resolvedBody = rawBody;
+                const allUsedKeys = [];
+                const allSecretValues = [];
+                if (opts.resolveKeys) {
+                    try {
+                        const urlResult = await opts.resolveKeys(rawUrl);
+                        resolvedUrl = urlResult.resolved;
+                        allUsedKeys.push(...urlResult.usedKeys);
+                        allSecretValues.push(...(urlResult.secretValues ?? []));
+                        const headerResult = await opts.resolveKeys(rawHeaders);
+                        resolvedHeaders = headerResult.resolved;
+                        allUsedKeys.push(...headerResult.usedKeys);
+                        allSecretValues.push(...(headerResult.secretValues ?? []));
+                        if (rawBody) {
+                            const bodyResult = await opts.resolveKeys(rawBody);
+                            resolvedBody = bodyResult.resolved;
+                            allUsedKeys.push(...bodyResult.usedKeys);
+                            allSecretValues.push(...(bodyResult.secretValues ?? []));
+                        }
+                    }
+                    catch (err) {
+                        return `Error resolving key references: ${err?.message ?? err}`;
+                    }
+                }
+                const secretValues = collectSecretValues(allSecretValues);
+                // Block SSRF targets regardless of key usage
+                if (await isBlockedToolUrlWithDns(resolvedUrl)) {
+                    return `Requests to private/internal addresses are not allowed: "${rawUrl}".`;
+                }
+                // Validate URL against per-key allowlists
+                if (opts.validateUrl && allUsedKeys.length > 0) {
+                    try {
+                        const allowed = await opts.validateUrl(resolvedUrl, allUsedKeys);
+                        if (!allowed) {
+                            return `URL "${rawUrl}" is not in the allowlist for the referenced keys. Check your key settings.`;
+                        }
+                    }
+                    catch (err) {
+                        return `URL validation error: ${err?.message ?? err}`;
+                    }
+                }
+                // Parse headers
+                let headers;
+                try {
+                    headers = sanitizeOutboundHeaders(JSON.parse(resolvedHeaders));
+                }
+                catch {
+                    return `Invalid headers JSON: ${rawHeaders}`;
+                }
+                // Make the request
+                const controller = new AbortController();
+                const timeout = setTimeout(() => controller.abort(), timeoutMs);
+                try {
+                    const fetchOpts = {
+                        method,
+                        headers,
+                        signal: controller.signal,
+                        redirect: "manual",
+                    };
+                    if (resolvedBody && ["POST", "PUT", "PATCH"].includes(method)) {
+                        fetchOpts.body = resolvedBody;
+                        if (!headers["content-type"] && !headers["Content-Type"]) {
+                            headers["Content-Type"] = "application/json";
+                        }
+                    }
+                    const response = await fetch(resolvedUrl, fetchOpts);
+                    const elapsed = Date.now() - startTime;
+                    if (response.status >= 300 && response.status < 400) {
+                        const location = response.headers.get("location");
+                        const redirectUrl = location
+                            ? new URL(location, resolvedUrl).href
+                            : null;
+                        if (redirectUrl && (await isBlockedToolUrlWithDns(redirectUrl))) {
+                            return "Redirect to private/internal address blocked.";
+                        }
+                        if (redirectUrl && opts.validateUrl && allUsedKeys.length > 0) {
+                            const allowed = await opts.validateUrl(redirectUrl, allUsedKeys);
+                            if (!allowed) {
+                                return "Redirect URL is not in the allowlist for the referenced keys.";
+                            }
+                        }
+                        return `HTTP ${response.status} ${response.statusText}\n\nRedirect: ${redirectUrl ? redactString(redirectUrl, secretValues) : "(none)"}`;
+                    }
+                    let body;
+                    try {
+                        const result = await readResponseTextWithLimit(response, MAX_TOOL_PROXY_RESPONSE_SIZE);
+                        body = result.text;
+                    }
+                    catch {
+                        body = "(could not read response body)";
+                    }
+                    body = redactString(body, secretValues);
+                    // Truncate very long responses for the agent
+                    if (body.length > 8000) {
+                        body = body.slice(0, 8000) + "\n... (truncated)";
+                    }
+                    // Audit log
+                    console.log(`[fetch-tool] ${method} ${rawUrl} → ${response.status} (${elapsed}ms, keys: ${allUsedKeys.join(",") || "none"})`);
+                    return `HTTP ${response.status} ${response.statusText}\n\n${body}`;
+                }
+                catch (err) {
+                    const elapsed = Date.now() - startTime;
+                    if (err?.name === "AbortError") {
+                        console.log(`[fetch-tool] ${method} ${rawUrl} → TIMEOUT (${elapsed}ms)`);
+                        return `Request timed out after ${timeoutMs}ms.`;
+                    }
+                    const message = redactSecrets(err?.message ?? String(err), secretValues);
+                    console.log(`[fetch-tool] ${method} ${rawUrl} → ERROR: ${message} (${elapsed}ms)`);
+                    return `Request failed: ${message}`;
+                }
+                finally {
+                    clearTimeout(timeout);
+                }
+            },
+            readOnly: true,
+        },
+    };
+}
+//# sourceMappingURL=fetch-tool.js.map

package/dist/tools/fetch-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-tool.js","sourceRoot":"","sources":["../../src/tools/fetch-tool.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Fetch tool — outbound HTTP for automations and agent use.\n *\n * Supports ${keys.NAME} reference substitution in URL, headers, and body.\n * Values are resolved server-side AFTER the model emits the tool call —\n * the raw secret never enters the model's context.\n */\n\nimport type { ActionEntry } from \"../agent/production-agent.js\";\nimport {\n  collectSecretValues,\n  MAX_TOOL_PROXY_RESPONSE_SIZE,\n  normalizeToolProxyMethod,\n  readResponseTextWithLimit,\n  redactSecrets,\n  redactString,\n  sanitizeOutboundHeaders,\n} from \"./proxy-security.js\";\nimport { isBlockedToolUrlWithDns } from \"./url-safety.js\";\n\nconst DEFAULT_TIMEOUT_MS = 15_000;\n\nexport interface FetchToolOptions {\n  /** Resolve ${keys.NAME} references. Injected by the plugin at setup time. */\n  resolveKeys?: (text: string) => Promise<{\n    resolved: string;\n    usedKeys: string[];\n    secretValues?: string[];\n  }>;\n  /** Validate URL against per-key allowlists. */\n  validateUrl?: (url: string, usedKeys: string[]) => Promise<boolean>;\n}\n\n/**\n * Create the fetch tool entry for the agent tool registry.\n */\nexport function createFetchToolEntry(\n  opts: FetchToolOptions = {},\n): Record<string, ActionEntry> {\n  return {\n    \"web-request\": {\n      tool: {\n        description: `Make an outbound HTTP request to EXTERNAL APIs, webhooks, and services only. Supports \\${keys.NAME} placeholders in url, headers, and body — these are resolved server-side from the user's saved keys (the raw value never enters your context). Example: \\${keys.SLACK_WEBHOOK} in the url field. IMPORTANT: Never use this to call internal /_agent-native/ endpoints or localhost action URLs — use the registered action tools directly (e.g. \\`log-meal\\`, \\`bigquery\\`, \\`hubspot-deals\\`). Actions are already available as native tools; calling them via HTTP is slower and bypasses validation.`,\n        parameters: {\n          type: \"object\" as const,\n          properties: {\n            url: {\n              type: \"string\",\n              description:\n                'Full URL. May contain ${keys.NAME} references, e.g. \"${keys.SLACK_WEBHOOK}\".',\n            },\n            method: {\n              type: \"string\",\n              description: \"HTTP method. Default: GET.\",\n              enum: [\"GET\", \"POST\", \"PUT\", \"PATCH\", \"DELETE\", \"HEAD\"],\n            },\n            headers: {\n              type: \"string\",\n              description:\n                'JSON object of headers. May contain ${keys.NAME} references. Example: \\'{\"Authorization\": \"Bearer ${keys.API_TOKEN}\"}\\'.',\n            },\n            body: {\n              type: \"string\",\n              description:\n                \"Request body (for POST/PUT/PATCH). May contain ${keys.NAME} references.\",\n            },\n            timeout_ms: {\n              type: \"number\",\n              description: `Timeout in milliseconds. Default: ${DEFAULT_TIMEOUT_MS}. Max: 30000.`,\n            },\n          },\n          required: [\"url\"],\n        },\n      },\n      run: async (args: Record<string, string>) => {\n        const startTime = Date.now();\n        const rawUrl = args.url;\n        const method = normalizeToolProxyMethod(args.method || \"GET\");\n        if (!method) {\n          return \"Unsupported HTTP method. Allowed methods: GET, POST, PUT, PATCH, DELETE, HEAD.\";\n        }\n        const rawHeaders = args.headers || \"{}\";\n        const rawBody = args.body;\n        const timeoutMs = Math.min(\n          Number(args.timeout_ms) || DEFAULT_TIMEOUT_MS,\n          30_000,\n        );\n\n        // Resolve key references\n        let resolvedUrl = rawUrl;\n        let resolvedHeaders = rawHeaders;\n        let resolvedBody = rawBody;\n        const allUsedKeys: string[] = [];\n        const allSecretValues: string[] = [];\n\n        if (opts.resolveKeys) {\n          try {\n            const urlResult = await opts.resolveKeys(rawUrl);\n            resolvedUrl = urlResult.resolved;\n            allUsedKeys.push(...urlResult.usedKeys);\n            allSecretValues.push(...(urlResult.secretValues ?? []));\n\n            const headerResult = await opts.resolveKeys(rawHeaders);\n            resolvedHeaders = headerResult.resolved;\n            allUsedKeys.push(...headerResult.usedKeys);\n            allSecretValues.push(...(headerResult.secretValues ?? []));\n\n            if (rawBody) {\n              const bodyResult = await opts.resolveKeys(rawBody);\n              resolvedBody = bodyResult.resolved;\n              allUsedKeys.push(...bodyResult.usedKeys);\n              allSecretValues.push(...(bodyResult.secretValues ?? []));\n            }\n          } catch (err: any) {\n            return `Error resolving key references: ${err?.message ?? err}`;\n          }\n        }\n        const secretValues = collectSecretValues(allSecretValues);\n\n        // Block SSRF targets regardless of key usage\n        if (await isBlockedToolUrlWithDns(resolvedUrl)) {\n          return `Requests to private/internal addresses are not allowed: \"${rawUrl}\".`;\n        }\n\n        // Validate URL against per-key allowlists\n        if (opts.validateUrl && allUsedKeys.length > 0) {\n          try {\n            const allowed = await opts.validateUrl(resolvedUrl, allUsedKeys);\n            if (!allowed) {\n              return `URL \"${rawUrl}\" is not in the allowlist for the referenced keys. Check your key settings.`;\n            }\n          } catch (err: any) {\n            return `URL validation error: ${err?.message ?? err}`;\n          }\n        }\n\n        // Parse headers\n        let headers: Record<string, string>;\n        try {\n          headers = sanitizeOutboundHeaders(JSON.parse(resolvedHeaders));\n        } catch {\n          return `Invalid headers JSON: ${rawHeaders}`;\n        }\n\n        // Make the request\n        const controller = new AbortController();\n        const timeout = setTimeout(() => controller.abort(), timeoutMs);\n\n        try {\n          const fetchOpts: RequestInit = {\n            method,\n            headers,\n            signal: controller.signal,\n            redirect: \"manual\",\n          };\n          if (resolvedBody && [\"POST\", \"PUT\", \"PATCH\"].includes(method)) {\n            fetchOpts.body = resolvedBody;\n            if (!headers[\"content-type\"] && !headers[\"Content-Type\"]) {\n              headers[\"Content-Type\"] = \"application/json\";\n            }\n          }\n\n          const response = await fetch(resolvedUrl, fetchOpts);\n          const elapsed = Date.now() - startTime;\n\n          if (response.status >= 300 && response.status < 400) {\n            const location = response.headers.get(\"location\");\n            const redirectUrl = location\n              ? new URL(location, resolvedUrl).href\n              : null;\n            if (redirectUrl && (await isBlockedToolUrlWithDns(redirectUrl))) {\n              return \"Redirect to private/internal address blocked.\";\n            }\n            if (redirectUrl && opts.validateUrl && allUsedKeys.length > 0) {\n              const allowed = await opts.validateUrl(redirectUrl, allUsedKeys);\n              if (!allowed) {\n                return \"Redirect URL is not in the allowlist for the referenced keys.\";\n              }\n            }\n            return `HTTP ${response.status} ${response.statusText}\\n\\nRedirect: ${\n              redirectUrl ? redactString(redirectUrl, secretValues) : \"(none)\"\n            }`;\n          }\n\n          let body: string;\n          try {\n            const result = await readResponseTextWithLimit(\n              response,\n              MAX_TOOL_PROXY_RESPONSE_SIZE,\n            );\n            body = result.text;\n          } catch {\n            body = \"(could not read response body)\";\n          }\n          body = redactString(body, secretValues);\n\n          // Truncate very long responses for the agent\n          if (body.length > 8000) {\n            body = body.slice(0, 8000) + \"\\n... (truncated)\";\n          }\n\n          // Audit log\n          console.log(\n            `[fetch-tool] ${method} ${rawUrl} → ${response.status} (${elapsed}ms, keys: ${allUsedKeys.join(\",\") || \"none\"})`,\n          );\n\n          return `HTTP ${response.status} ${response.statusText}\\n\\n${body}`;\n        } catch (err: any) {\n          const elapsed = Date.now() - startTime;\n          if (err?.name === \"AbortError\") {\n            console.log(\n              `[fetch-tool] ${method} ${rawUrl} → TIMEOUT (${elapsed}ms)`,\n            );\n            return `Request timed out after ${timeoutMs}ms.`;\n          }\n          const message = redactSecrets(\n            err?.message ?? String(err),\n            secretValues,\n          );\n          console.log(\n            `[fetch-tool] ${method} ${rawUrl} → ERROR: ${message} (${elapsed}ms)`,\n          );\n          return `Request failed: ${message}`;\n        } finally {\n          clearTimeout(timeout);\n        }\n      },\n      readOnly: true,\n    },\n  };\n}\n"]}

package/dist/tools/html-shell.d.ts

@@ -0,0 +1,45 @@
+export declare const TOOL_IFRAME_CSP = "default-src 'none'; script-src 'self' https://cdn.jsdelivr.net 'unsafe-eval' 'unsafe-inline'; style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net https://fonts.googleapis.com; font-src https://fonts.gstatic.com; connect-src 'self'; img-src 'self' data: blob:; media-src 'self' data: blob:; frame-src 'none'; object-src 'none'; base-uri 'none'; form-action 'none'; frame-ancestors 'self';";
+export declare const TOOL_IFRAME_META_CSP: string;
+/**
+ * SECURITY — TOOL CONTENT IS UNTRUSTED.
+ *
+ * `${content}` (line ~Body) interpolates raw HTML/JS authored by a user. This
+ * file is the boundary between framework-controlled HTML and user-controlled
+ * HTML. Two non-negotiable invariants for every change here:
+ *
+ *   1. The iframe MUST be rendered with a `sandbox` attribute that does NOT
+ *      include `allow-same-origin`. The viewer (`ToolViewer.tsx`,
+ *      `EmbeddedTool.tsx`) sets `sandbox="allow-scripts allow-forms"` — and
+ *      that is the only acceptable shape. Adding `allow-same-origin` would
+ *      give the tool full DOM access to the parent window via cross-frame
+ *      script.
+ *
+ *   2. Every reachable parent action must treat the postMessage payload as
+ *      hostile. The bridge in `iframe-bridge.ts` enforces a path allowlist,
+ *      header sanitization, and method allowlist; do not relax those gates
+ *      for "convenience" in this file or any caller.
+ *
+ * For the trust model rationale, see audit 05-tools-sandbox.md (C1) and the
+ * `tools` skill. When in doubt, fail closed.
+ */
+export interface ToolRenderBinding {
+    /** Email of the user who authored / owns the tool. */
+    authorEmail: string;
+    /** Email of the user currently viewing/running the tool. */
+    viewerEmail: string;
+    /** True when viewer === author. */
+    isAuthor: boolean;
+    /**
+     * Resolved role for the viewer ("owner" | "admin" | "editor" | "viewer").
+     *
+     * TODO(security, audit H4): the host-side bridge does not yet gate any
+     * helper based on this value — every viewer gets the same powers as the
+     * author. The role is plumbed through so a follow-up PR can constrain
+     * `appAction` / `dbExec` / `toolFetch` for non-author viewers (and
+     * eventually require an explicit consent step before running a shared
+     * tool, audit C1). For now this is metadata only.
+     */
+    role: "owner" | "admin" | "editor" | "viewer";
+}
+export declare function buildToolHtml(content: string, themeVars: string, isDark: boolean, toolId?: string, binding?: ToolRenderBinding): string;
+//# sourceMappingURL=html-shell.d.ts.map

package/dist/tools/html-shell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"html-shell.d.ts","sourceRoot":"","sources":["../../src/tools/html-shell.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,eAAe,8YACiX,CAAC;AAE9Y,eAAO,MAAM,oBAAoB,QAGhC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,WAAW,iBAAiB;IAChC,sDAAsD;IACtD,WAAW,EAAE,MAAM,CAAC;IACpB,4DAA4D;IAC5D,WAAW,EAAE,MAAM,CAAC;IACpB,mCAAmC;IACnC,QAAQ,EAAE,OAAO,CAAC;IAClB;;;;;;;;;OASG;IACH,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAC;CAC/C;AAED,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,OAAO,EACf,MAAM,CAAC,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,iBAAiB,GAC1B,MAAM,CA0fR"}