The Open Framework for Building Agents
fix(eve): safe-by-default frontmatter parsing and https-pinned OpenAPI connections (#633)
Mukund Sarma89f13e0ac6e9
diff --git a/.changeset/openapi-spec-safe-frontmatter.md b/.changeset/openapi-spec-safe-frontmatter.mdnew file mode 100644index 000000000..8657a5790--- /dev/null+++ b/.changeset/openapi-spec-safe-frontmatter.md@@ -0,0 +1,9 @@+---+"eve": patch+---++Hardened frontmatter parsing and OpenAPI connection loading.++All frontmatter parsing now runs through a single safe-by-default helper with gray-matter's code-capable engines disabled, so a `---js` / `---javascript` fence throws instead of being `eval()`d. Previously only authored markdown (skills, schedules, instructions) was hardened; the eval YAML loader and the OpenAPI spec loader used gray-matter's defaults and would execute such a fence. This closes that path for OpenAPI specs, which are fetched over the network. Parsing untrusted frontmatter as code is now opt-in only, and a direct import of the bundled gray-matter outside the wrapper fails CI.++OpenAPI spec URLs and the resolved base URL are now required to use `https` (plain `http` is still allowed for loopback hosts during local development), so neither the spec fetch nor the credentialed operation calls run over cleartext; the spec transport is also re-checked after redirects.diff --git a/docs/connections/openapi.mdx b/docs/connections/openapi.mdxindex 073eb0d1c..98e4d373e 100644--- a/docs/connections/openapi.mdx+++ b/docs/connections/openapi.mdx@@ -23,7 +23,7 @@ export default defineOpenAPIConnection({Each operation becomes `<connection>__<operationId>`, for example `petstore__getInventory`. When an operation has no `operationId`, eve derives a deterministic `<method>_<sanitized-path>` name instead.-`spec` can be an HTTPS URL that eve fetches at runtime, or an inline parsed OpenAPI object. Prefer a URL when the provider owns the contract and updates it; prefer an inline object for private APIs, generated specs you pin in source control, or small hand-authored contracts.+`spec` can be a URL that eve fetches at runtime, or an inline parsed OpenAPI object. A spec URL must use `https` (plain `http` is allowed only for loopback hosts such as `localhost` during local development), and eve re-checks the transport after any redirects. Prefer a URL when the provider owns the contract and updates it; prefer an inline object for private APIs, generated specs you pin in source control, or small hand-authored contracts.## Base URL and servers@@ -34,6 +34,8 @@ eve resolves operation paths against `baseUrl` when you provide one. Otherwise,Use `baseUrl` when the spec is missing server data, points at the wrong environment, uses a relative server URL you do not want, or needs to be pinned for this agent.+The resolved base URL must use `https` too (loopback hosts may use `http` for local development), since operation calls carry the connection's credentials.+```ts title="agent/connections/crm.ts"import { defineOpenAPIConnection } from "eve/connections";diff --git a/packages/eve/src/evals/loaders/yaml.ts b/packages/eve/src/evals/loaders/yaml.tsindex 423998b0f..7bb16d803 100644--- a/packages/eve/src/evals/loaders/yaml.ts+++ b/packages/eve/src/evals/loaders/yaml.ts@@ -1,7 +1,7 @@import { readFile } from "node:fs/promises";import { isAbsolute, resolve } from "node:path";-import matter from "#compiled/gray-matter/index.js";+import { parseFrontmatter } from "#internal/helpers/gray-matter.js";/*** Loads a YAML file and returns its top-level mapping as a plain object.@@ -26,7 +26,5 @@ export async function loadYaml(filePath: string): Promise<Record<string, unknown// we wrap the content so gray-matter sees the entire file as frontmatter.const needsWrapper = !raw.trimStart().startsWith("---");const input = needsWrapper ? `---\n${raw}\n---` : raw;- const parsed = matter(input);-- return (parsed.data ?? {}) as Record<string, unknown>;+ return parseFrontmatter(input).data;}diff --git a/packages/eve/src/internal/helpers/gray-matter.test.ts b/packages/eve/src/internal/helpers/gray-matter.test.tsnew file mode 100644index 000000000..439ec08eb--- /dev/null+++ b/packages/eve/src/internal/helpers/gray-matter.test.ts@@ -0,0 +1,33 @@+import { describe, expect, it } from "vitest";++import { hasFrontmatter, parseFrontmatter } from "#internal/helpers/gray-matter.js";++describe("parseFrontmatter", () => {+ it("parses YAML frontmatter into data and body", () => {+ const doc = parseFrontmatter("---\ntitle: T\n---\nhello");+ expect(doc.data).toEqual({ title: "T" });+ expect(doc.content.trim()).toBe("hello");+ });++ it("rejects a JavaScript frontmatter fence by default without evaluating it", () => {+ const marker = "eve_gray_matter_default_marker";+ const source = `---js\n(globalThis[${JSON.stringify(marker)}] = true)\n---\n`;++ expect(() => parseFrontmatter(source)).toThrow(/JavaScript frontmatter is not supported/);+ expect((globalThis as Record<string, unknown>)[marker]).toBeUndefined();+ });++ it("evaluates a JavaScript fence only when allowCodeEngines is opted in", () => {+ const marker = "eve_gray_matter_optin_marker";+ const source = `---js\n(globalThis[${JSON.stringify(marker)}] = true)\n---\n`;++ parseFrontmatter(source, { allowCodeEngines: true });+ expect((globalThis as Record<string, unknown>)[marker]).toBe(true);+ delete (globalThis as Record<string, unknown>)[marker];+ });++ it("detects a leading frontmatter delimiter", () => {+ expect(hasFrontmatter("---\ntitle: T\n---\n")).toBe(true);+ expect(hasFrontmatter("no frontmatter")).toBe(false);+ });+});diff --git a/packages/eve/src/internal/helpers/gray-matter.ts b/packages/eve/src/internal/helpers/gray-matter.tsnew file mode 100644index 000000000..641cfb1e7--- /dev/null+++ b/packages/eve/src/internal/helpers/gray-matter.ts@@ -0,0 +1,57 @@+import matter, { type GrayMatterFile } from "#compiled/gray-matter/index.js";++/**+ * gray-matter ships built-in `javascript`/`js` frontmatter engines that+ * `eval()` the frontmatter body, so a document whose opening fence is+ * `---js` (or `---javascript`) executes that body the instant it is parsed —+ * before any validation runs. eve treats frontmatter strictly as data, so+ * these options disable the code-capable engines and pin the default language+ * to YAML. Pinning `language` alone is not enough: gray-matter reads the+ * language named after the opening fence and uses it in preference to the+ * option, so the engines must be replaced as well.+ */+function rejectJavaScriptFrontmatter(): never {+ throw new Error("JavaScript frontmatter is not supported.");+}++const SAFE_GRAY_MATTER_OPTIONS = {+ language: "yaml",+ engines: {+ javascript: rejectJavaScriptFrontmatter,+ js: rejectJavaScriptFrontmatter,+ },+} as const;++/** Options for {@link parseFrontmatter}. */+export interface ParseFrontmatterOptions {+ /**+ * Opt in to gray-matter's built-in code-capable engines, so a `---js` /+ * `---javascript` frontmatter fence is `eval()`d while parsing. This runs+ * arbitrary code the instant the document is read, so only enable it for+ * input you fully control and trust. Defaults to `false`, which rejects a+ * JavaScript frontmatter fence instead of evaluating it.+ */+ readonly allowCodeEngines?: boolean;+}++/**+ * Parses a document's YAML frontmatter and body.+ *+ * Safe by default: the code-capable frontmatter engines are disabled, so a+ * `---js` fence throws rather than executing. This is the only supported way+ * to run gray-matter in eve — callers must not import the bundled module+ * directly, so that untrusted input can never reach an evaluating engine by+ * accident. Pass `{ allowCodeEngines: true }` to deliberately opt back into+ * evaluation for trusted input.+ */+export function parseFrontmatter(+ source: string,+ options: ParseFrontmatterOptions = {},+): GrayMatterFile<string> {+ return options.allowCodeEngines ? matter(source) : matter(source, SAFE_GRAY_MATTER_OPTIONS);+}++/** Reports whether a document opens with a frontmatter delimiter. */+export function hasFrontmatter(source: string): boolean {+ return matter.test(source);+}diff --git a/packages/eve/src/internal/helpers/markdown.ts b/packages/eve/src/internal/helpers/markdown.tsindex 2b29ec025..6a01bd316 100644--- a/packages/eve/src/internal/helpers/markdown.ts+++ b/packages/eve/src/internal/helpers/markdown.ts@@ -1,5 +1,4 @@-import grayMatter from "#compiled/gray-matter/index.js";-+import { parseFrontmatter, hasFrontmatter } from "#internal/helpers/gray-matter.js";import {normalizeScheduleDefinition,normalizeSkillDefinition,@@ -12,27 +11,6 @@ import type { InstructionsDefinition } from "#public/definitions/instructions.jsconst CLOSED_FRONTMATTER_PATTERN = /^---\r?\n[\s\S]*?\r?\n---(?:\r?\n|$)/;-/**- * gray-matter ships a built-in `javascript` frontmatter engine that runs- * `eval()` on the frontmatter body, so a document whose opening fence is- * `---javascript` (or `---js`) would execute arbitrary code the instant it is- * parsed — before any of eve's validators run. Authored markdown (skills,- * schedules, instructions) is treated as data, so we disable the code-capable- * engines and pin the default language to YAML; a JavaScript frontmatter fence- * now throws instead of evaluating.- */-function rejectJavaScriptFrontmatter(): never {- throw new Error("JavaScript frontmatter is not supported.");-}--const SAFE_GRAY_MATTER_OPTIONS = {- language: "yaml",- engines: {- javascript: rejectJavaScriptFrontmatter,- js: rejectJavaScriptFrontmatter,- },-};-/*** Parsed markdown document with optional YAML frontmatter.*/@@ -56,7 +34,7 @@ interface ParsedMarkdownDocument {* Parses markdown with optional YAML frontmatter.*/function parseMarkdownDocument(source: string): ParsedMarkdownDocument {- if (!grayMatter.test(source)) {+ if (!hasFrontmatter(source)) {return {hasFrontmatter: false,frontmatter: {},@@ -70,7 +48,7 @@ function parseMarkdownDocument(source: string): ParsedMarkdownDocument {};try {- document = grayMatter(source, SAFE_GRAY_MATTER_OPTIONS);+ document = parseFrontmatter(source);} catch (error) {if (startsWithFrontmatterFence(source) && !hasClosedFrontmatterFence(source)) {throw new Error("Markdown frontmatter is missing a closing delimiter.");diff --git a/packages/eve/src/runtime/connections/openapi-client.test.ts b/packages/eve/src/runtime/connections/openapi-client.test.tsindex 9d6bf5c47..e193fdc5f 100644--- a/packages/eve/src/runtime/connections/openapi-client.test.ts+++ b/packages/eve/src/runtime/connections/openapi-client.test.ts@@ -522,6 +522,73 @@ describe("OpenApiConnectionClient", () => {expect(String(calledUrl)).toBe("https://api.example.com/v1/projects/prj_1");});+ it("refuses to fetch a spec over http", async () => {+ const fetchMock = vi.fn(async () => new Response(null, { status: 200 }));+ vi.stubGlobal("fetch", fetchMock);++ const client = new OpenApiConnectionClient(+ makeConnection({ spec: "http://specs.example.com/openapi.json", url: "" }),+ );++ await expect(client.getToolMetadata()).rejects.toThrow(/must use https for its spec/);+ expect(fetchMock).not.toHaveBeenCalled();+ });++ it("allows http specs from loopback hosts for local development", async () => {+ const fetchMock = vi.fn(+ async () =>+ new Response(JSON.stringify(SPEC), {+ status: 200,+ headers: { "content-type": "application/json" },+ }),+ );+ vi.stubGlobal("fetch", fetchMock);++ const client = new OpenApiConnectionClient(+ makeConnection({+ spec: "http://localhost:3000/openapi.json",+ url: "https://api.example.com",+ }),+ );++ await expect(client.getToolMetadata()).resolves.toBeDefined();+ });++ it("refuses a spec redirected onto an insecure transport", async () => {+ const fetchMock = vi.fn(async () => {+ const response = new Response(JSON.stringify(SPEC), {+ status: 200,+ headers: { "content-type": "application/json" },+ });+ Object.defineProperty(response, "redirected", { value: true });+ Object.defineProperty(response, "url", { value: "http://attacker.example.com/spec" });+ return response;+ });+ vi.stubGlobal("fetch", fetchMock);++ const client = new OpenApiConnectionClient(+ makeConnection({ spec: "https://specs.example.com/openapi.json", url: "" }),+ );++ await expect(client.getToolMetadata()).rejects.toThrow(/must use https for its spec/);+ });++ it("refuses an http base URL so operation calls never carry auth over cleartext", async () => {+ const client = new OpenApiConnectionClient(+ makeConnection({ spec: SPEC, url: "http://api.example.com" }),+ );++ await expect(client.getToolMetadata()).rejects.toThrow(/must use https for its base/);+ });++ it("allows a loopback http base URL for local development", async () => {+ const client = new OpenApiConnectionClient(+ makeConnection({ spec: SPEC, url: "http://localhost:3000" }),+ );++ await expect(client.getToolMetadata()).resolves.toBeDefined();+ });+it("resolves a relative server URL against the spec URL", async () => {const doc: Record<string, unknown> = {openapi: "3.0.3",diff --git a/packages/eve/src/runtime/connections/openapi-client.ts b/packages/eve/src/runtime/connections/openapi-client.tsindex c35ced847..bdb6a475c 100644--- a/packages/eve/src/runtime/connections/openapi-client.ts+++ b/packages/eve/src/runtime/connections/openapi-client.ts@@ -25,6 +25,7 @@ import type {ConnectionToolMetadata,} from "#runtime/connections/types.js";import { isObject } from "#shared/guards.js";+import { isLoopbackHostname } from "#shared/network-address.js";interface OpenApiToolCache {readonly metadata: readonly ConnectionToolMetadata[];@@ -184,16 +185,17 @@ export class OpenApiConnectionClient implements ConnectionClient {*/#resolveBaseUrl(document: Record<string, unknown>): string {const explicit = this.#connection.url;- if (typeof explicit === "string" && explicit.trim().length > 0) {- return explicit;- }- const fromServers = extractServerUrl(document, this.#connection.spec);- if (fromServers !== undefined) {- return fromServers;+ const baseUrl =+ typeof explicit === "string" && explicit.trim().length > 0+ ? explicit+ : extractServerUrl(document, this.#connection.spec);+ if (baseUrl === undefined) {+ throw new Error(+ `OpenAPI connection "${this.#connection.connectionName}" has no base URL: set "baseUrl" or ensure the document declares an absolute "servers" entry or Swagger "host".`,+ );}- throw new Error(- `OpenAPI connection "${this.#connection.connectionName}" has no base URL: set "baseUrl" or ensure the document declares an absolute "servers" entry or Swagger "host".`,- );+ assertSecureUrl(baseUrl, this.#connection.connectionName, "base");+ return baseUrl;}async #loadDocument(): Promise<Record<string, unknown>> {@@ -208,6 +210,8 @@ export class OpenApiConnectionClient implements ConnectionClient {return spec;}+ assertSecureUrl(spec, this.#connection.connectionName, "spec");+let response: Response;try {response = await fetch(spec, {@@ -218,6 +222,9 @@ export class OpenApiConnectionClient implements ConnectionClient {`OpenAPI connection "${this.#connection.connectionName}" failed to fetch its spec from "${spec}": ${String(error)}`,);}+ if (response.redirected) {+ assertSecureUrl(response.url, this.#connection.connectionName, "spec");+ }if (!response.ok) {throw new Error(`OpenAPI connection "${this.#connection.connectionName}" failed to fetch its spec from "${spec}": HTTP ${response.status}.`,@@ -465,6 +472,37 @@ function joinPath(baseUrl: string, path: string): string {return `${trimmedBase}${trimmedPath}`;}+/**+ * Requires a connection URL to be transport-secure. The spec body configures+ * tool calls and every operation request carries the connection's resolved+ * auth, so both are only trusted over `https`. Plain `http` is permitted for+ * loopback hosts to keep local development ergonomic.+ *+ * The spec fetch is checked on the configured URL and again on the final URL+ * after any redirects. Only those two endpoints are enforced — `fetch` follows+ * intermediate redirect hops internally, so a chain through a cleartext hop is+ * not observable here.+ */+function assertSecureUrl(rawUrl: string, connectionName: string, kind: string): void {+ let url: URL;+ try {+ url = new URL(rawUrl);+ } catch {+ throw new Error(+ `OpenAPI connection "${connectionName}" has an invalid ${kind} URL "${rawUrl}".`,+ );+ }+ if (url.protocol === "https:") {+ return;+ }+ if (url.protocol === "http:" && isLoopbackHostname(url.hostname)) {+ return;+ }+ throw new Error(+ `OpenAPI connection "${connectionName}" must use https for its ${kind} (got "${url.protocol}//${url.host}").`,+ );+}+async function readResponseBody(response: Response): Promise<unknown> {const text = await response.text();if (text.length === 0) {diff --git a/packages/eve/src/runtime/connections/openapi-spec.test.ts b/packages/eve/src/runtime/connections/openapi-spec.test.tsnew file mode 100644index 000000000..724f0701b--- /dev/null+++ b/packages/eve/src/runtime/connections/openapi-spec.test.ts@@ -0,0 +1,24 @@+import { describe, expect, it } from "vitest";++import { parseSpecDocument } from "#runtime/connections/openapi-spec.js";++describe("parseSpecDocument", () => {+ it("parses JSON specs", () => {+ expect(parseSpecDocument('{"openapi":"3.0.0"}')).toEqual({ openapi: "3.0.0" });+ });++ it("parses YAML specs", () => {+ expect(parseSpecDocument("openapi: 3.0.0\ninfo:\n title: T")).toEqual({+ openapi: "3.0.0",+ info: { title: "T" },+ });+ });++ it("does not evaluate a JavaScript frontmatter fence", () => {+ const marker = "eve_openapi_spec_js_marker";+ const body = `---js\n(globalThis[${JSON.stringify(marker)}] = true)\n---\n`;++ expect(() => parseSpecDocument(body)).toThrow(/JavaScript frontmatter is not supported/);+ expect((globalThis as Record<string, unknown>)[marker]).toBeUndefined();+ });+});diff --git a/packages/eve/src/runtime/connections/openapi-spec.ts b/packages/eve/src/runtime/connections/openapi-spec.tsindex a52877871..b39a70456 100644--- a/packages/eve/src/runtime/connections/openapi-spec.ts+++ b/packages/eve/src/runtime/connections/openapi-spec.ts@@ -1,4 +1,4 @@-import matter from "#compiled/gray-matter/index.js";+import { parseFrontmatter } from "#internal/helpers/gray-matter.js";import { isArray } from "#runtime/connections/openapi-schema.js";import { isObject } from "#shared/guards.js";@@ -19,8 +19,7 @@ export function parseSpecDocument(text: string): unknown {}const body = text.replace(/^\uFEFF/, "");const wrapped = body.trimStart().startsWith("---") ? body : `---\n${body}\n---`;- const parsed = matter(wrapped);- return parsed.data ?? {};+ return parseFrontmatter(wrapped).data;}/**diff --git a/scripts/guard-invariants.mjs b/scripts/guard-invariants.mjsindex 8bdd7851d..5cb140d98 100644--- a/scripts/guard-invariants.mjs+++ b/scripts/guard-invariants.mjs@@ -82,6 +82,11 @@* `queue-namespace.ts`. The generated agent bootstrap installs the* agent-scoped namespace before queue-producing APIs can run.* rule 34 — `phase` stays a runtime-only dependency. No file under the Eve\n * logo renderer's GPU/runtime boundary (render/, shaders/, or the\n * offline render harness) may import the `phase` package. This keeps\n * the mechanical separation between the lifecycle layer and the GPU\n * renderer enforceable.+ * rule 35 — No direct `#compiled/gray-matter` imports outside the+ * `internal/helpers/gray-matter.ts` wrapper. gray-matter's default+ * engines `eval()` a `---js` frontmatter fence, so every call must+ * route through `parseFrontmatter`, which is safe by default. A+ * direct import lets untrusted input reach an evaluating engine.** Baselines for rules with pre-existing violations live in* `guard-invariants-baseline.json`. Counts and allowlists in that file@@ -170,6 +175,7 @@ function isTsLike(relPath) {* rule27: Violation[];* rule28: Violation[];* rule33: Violation[];+ * rule35: Violation[];* symlinks: string[];* }} state*/@@ -197,6 +203,7 @@ async function scanRepo(state) {checkRule27(posix, lines, state.rule27);checkRule28(posix, lines, state.rule28);checkRule33(posix, lines, state.rule33);+ checkRule35(posix, lines, state.rule35);}}@@ -290,6 +297,33 @@ function checkRule33(posix, lines, violations) {});}+// ---------- Rule 35: direct gray-matter imports ----------++const GRAY_MATTER_SPECIFIER_RE = /["']#compiled\/gray-matter(?:\/[^"']+)?["']/;+const GRAY_MATTER_FACADE = "packages/eve/src/internal/helpers/gray-matter.ts";++/**+ * @param {string} posix+ * @param {string[]} lines+ * @param {Violation[]} violations+ */+function checkRule35(posix, lines, violations) {+ if (posix === GRAY_MATTER_FACADE) return;+ lines.forEach((line, idx) => {+ const isImport =+ /^(?:import|export)\b|^}\s*from\b|\b(?:import|require)\s*\(/.test(line.trimStart()) &&+ GRAY_MATTER_SPECIFIER_RE.test(line);+ if (isImport) {+ violations.push({+ rule: 35,+ file: posix,+ line: idx + 1,+ message: `imports "#compiled/gray-matter" directly. gray-matter's default engines eval() a \`---js\` frontmatter fence, so parse through parseFrontmatter() from "#internal/helpers/gray-matter.js" instead — it is safe by default and takes an explicit { allowCodeEngines: true } opt-in for trusted input.`,+ });+ }+ });+}+// ---------- Rule 19: AsyncLocalStorage instances ----------const NEW_ALS_RE = /new\s+AsyncLocalStorage\s*[<(]/;@@ -846,7 +880,6 @@ async function checkRule34PhaseBoundary() {return violations;}-/*** @returns {Promise<Set<string>>}*/@@ -1024,6 +1057,7 @@ async function main() {rule27: /** @type {Violation[]} */ ([]),rule28: /** @type {Violation[]} */ ([]),rule33: /** @type {Violation[]} */ ([]),+ rule35: /** @type {Violation[]} */ ([]),symlinks: /** @type {string[]} */ ([]),};@@ -1112,6 +1146,9 @@ async function main() {// Rule 34violations.push(...(await checkRule34PhaseBoundary()));+ // Rule 35+ violations.push(...state.rule35);+if (violations.length === 0) {process.stdout.write("[eve:guard:invariants] ok — all mechanical lints passed.\n");return;