Skip to content

armgit / eve

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.mdx
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.js
const 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.mjs
index 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 34
violations.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;