* fix(contracts)!: require absolute local paths for remaining caller-supplied file inputs Follow-up to the session snapshot/export tightening: the same invisible server-cwd resolution applied to open_binary target paths (parseBinaryTarget(path, process.cwd())), import_evidence_bundle bundle reads, firmware input files (resolve(raw)), browser executable launch paths (resolve-then-spawn), Electron executable/application/root paths (realpath on raw input), and the expected server path check. Each field gains the shared isAbsoluteLocalPath refinement plus a catalog-visible description, since JSON Schema cannot express the rule. Examples, scenario fixtures, and contract tests updated to absolute paths; new schema cases cover rejection/acceptance/omission per field. Explicitly unchanged (verified rooted or out of scope): inspect_plist paths (resolved against the target bundle dir), firmware output_directory (already provider-enforced), filesystem observation paths (resolved against the caller-supplied working_directory), keyed-archive member paths (archive-relative), JS evidence member paths (evidence-relative under root_alias), provider-internal execution schemas, CLI-only doctor flows, and CLI options (own resolve against the operator cwd). * fix(cli): resolve operator-relative paths before shared absolute-path validation The contract tightening rejects relative paths, but three CLI commands forward operator-relative input into the shared schemas: firmware commands pass raw args to FirmwareAnalysisService, and the Electron/browser scenario commands validate parsed scenario JSON directly. CLI paths are relative to the operator shell, so resolve them against the working directory first: resolve() in firmwareCommands, and a shared resolveCliJsonPaths JSON key-path helper (cliJsonInput) applied in electronCommands and cliBrowserScenarioCommands. MCP behavior is unchanged — MCP callers must still send absolute paths. Covers the regression with a relative-path firmware CLI acceptance test (asserts provider-stage capability_unavailable, not a validation error) and unit tests for the helper.
324 lines
8.5 KiB
TypeScript
324 lines
8.5 KiB
TypeScript
import { z } from "zod";
|
|
|
|
import { isAbsoluteLocalPath } from "./localPath.js";
|
|
import { browserNetworkContentSelectionSchema } from "./browserNetworkEvidence.js";
|
|
|
|
import {
|
|
browserEndpointSchema,
|
|
browserOriginSchema,
|
|
} from "./browserObservation.js";
|
|
|
|
export const scenarioIdentifierSchema = z
|
|
.string()
|
|
.regex(/^[A-Za-z][A-Za-z0-9._-]*$/u);
|
|
|
|
const browserExecutablePathSchema = z
|
|
.string()
|
|
.trim()
|
|
.min(1)
|
|
.refine(isAbsoluteLocalPath, {
|
|
message:
|
|
"executable_path must be an absolute local filesystem path (for example /opt/chromium/chrome or C:\\chromium\\chrome.exe)",
|
|
});
|
|
|
|
const browserScenarioBaseUrlSchema = z
|
|
.string()
|
|
.min(1)
|
|
.transform((value, context) => {
|
|
let url: URL;
|
|
try {
|
|
url = new URL(value);
|
|
} catch (cause: unknown) {
|
|
// Invalid input is reported through the zod issue.
|
|
void cause;
|
|
context.addIssue({ code: "custom", message: "Invalid browser URL" });
|
|
return z.NEVER;
|
|
}
|
|
if (
|
|
(url.protocol !== "http:" && url.protocol !== "https:") ||
|
|
url.username !== "" ||
|
|
url.password !== ""
|
|
) {
|
|
context.addIssue({
|
|
code: "custom",
|
|
message: "Browser URLs must be HTTP(S) and omit credentials",
|
|
});
|
|
return z.NEVER;
|
|
}
|
|
return url.toString();
|
|
});
|
|
|
|
export const browserScenarioValueSchema = z.discriminatedUnion("source", [
|
|
z.strictObject({
|
|
source: z.literal("literal"),
|
|
value: z.string(),
|
|
}),
|
|
z.strictObject({
|
|
source: z.literal("secret"),
|
|
secret_id: scenarioIdentifierSchema,
|
|
}),
|
|
]);
|
|
export type BrowserScenarioValue = z.infer<typeof browserScenarioValueSchema>;
|
|
|
|
const queryEntrySchema = z.strictObject({
|
|
name: z.string().min(1),
|
|
value: browserScenarioValueSchema,
|
|
});
|
|
|
|
/** URL with ordinary inline details and optional structured secret query references. */
|
|
export const browserScenarioUrlSchema = z.strictObject({
|
|
url: browserScenarioBaseUrlSchema,
|
|
query: z.array(queryEntrySchema).default([]),
|
|
});
|
|
export type BrowserScenarioUrl = z.infer<typeof browserScenarioUrlSchema>;
|
|
|
|
export const browserScenarioBrowserSchema = z.discriminatedUnion("mode", [
|
|
z.strictObject({
|
|
mode: z.literal("launch"),
|
|
executable_path: browserExecutablePathSchema.describe(
|
|
"Absolute local filesystem path for the browser executable; relative paths are rejected.",
|
|
),
|
|
headless: z
|
|
.boolean()
|
|
.default(true)
|
|
.describe(
|
|
"Run without a visible browser window; defaults to true and can be disabled when the host supports a display.",
|
|
),
|
|
}),
|
|
z.strictObject({
|
|
mode: z.literal("connect"),
|
|
cdp_endpoint: browserEndpointSchema,
|
|
target_id: z.string().trim().min(1),
|
|
}),
|
|
]);
|
|
|
|
export const browserScenarioEnvironmentSchema = z
|
|
.strictObject({
|
|
viewport: z
|
|
.strictObject({
|
|
width: z.number().int().positive().default(1_280),
|
|
height: z.number().int().positive().default(720),
|
|
device_scale_factor: z.number().positive().default(1),
|
|
})
|
|
.default({ width: 1_280, height: 720, device_scale_factor: 1 }),
|
|
locale: z
|
|
.string()
|
|
.min(2)
|
|
.regex(/^[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*$/u)
|
|
.default("en-US"),
|
|
timezone: z
|
|
.string()
|
|
.min(1)
|
|
.regex(/^[A-Za-z0-9_+-]+(?:\/[A-Za-z0-9_+-]+)*$/u)
|
|
.default("UTC"),
|
|
color_scheme: z.enum(["light", "dark", "no-preference"]).default("light"),
|
|
reduced_motion: z.enum(["reduce", "no-preference"]).default("reduce"),
|
|
service_workers: z.enum(["allow", "block"]).default("block"),
|
|
})
|
|
.default({
|
|
viewport: { width: 1_280, height: 720, device_scale_factor: 1 },
|
|
locale: "en-US",
|
|
timezone: "UTC",
|
|
color_scheme: "light",
|
|
reduced_motion: "reduce",
|
|
service_workers: "block",
|
|
})
|
|
.describe(
|
|
"Optional deterministic browser settings. Defaults to 1280x720, en-US, UTC, light mode, reduced motion, and blocked service workers.",
|
|
);
|
|
|
|
const locatorSchema = z.discriminatedUnion("kind", [
|
|
z.strictObject({
|
|
kind: z.literal("test_id"),
|
|
value: z.string().min(1),
|
|
}),
|
|
z.strictObject({
|
|
kind: z.literal("role"),
|
|
role: z.enum([
|
|
"button",
|
|
"checkbox",
|
|
"combobox",
|
|
"dialog",
|
|
"link",
|
|
"listbox",
|
|
"menuitem",
|
|
"option",
|
|
"radio",
|
|
"slider",
|
|
"spinbutton",
|
|
"switch",
|
|
"tab",
|
|
"textbox",
|
|
]),
|
|
name: z.string().min(1),
|
|
}),
|
|
z.strictObject({
|
|
kind: z.literal("css"),
|
|
selector: z.string().min(1),
|
|
}),
|
|
]);
|
|
|
|
const stepBase = {
|
|
step_id: scenarioIdentifierSchema,
|
|
timeout_ms: z
|
|
.number()
|
|
.int()
|
|
.min(1)
|
|
.optional()
|
|
.describe(
|
|
"Optional action deadline in milliseconds; omitted means wait until completion or request cancellation.",
|
|
),
|
|
};
|
|
|
|
export const browserScenarioActionSchema = z.discriminatedUnion("action", [
|
|
z.strictObject({
|
|
...stepBase,
|
|
action: z.literal("goto"),
|
|
destination: browserScenarioUrlSchema,
|
|
wait_until: z.enum(["commit", "domcontentloaded", "load"]),
|
|
}),
|
|
z.strictObject({
|
|
...stepBase,
|
|
action: z.literal("click"),
|
|
locator: locatorSchema,
|
|
button: z.enum(["left", "middle", "right"]).default("left"),
|
|
click_count: z.number().int().positive().default(1),
|
|
}),
|
|
z.strictObject({
|
|
...stepBase,
|
|
action: z.literal("fill"),
|
|
locator: locatorSchema,
|
|
value: browserScenarioValueSchema,
|
|
}),
|
|
z.strictObject({
|
|
...stepBase,
|
|
action: z.literal("press"),
|
|
locator: locatorSchema,
|
|
key: z.string().min(1),
|
|
}),
|
|
z.strictObject({
|
|
...stepBase,
|
|
action: z.literal("select_option"),
|
|
locator: locatorSchema,
|
|
value: browserScenarioValueSchema,
|
|
}),
|
|
z.strictObject({
|
|
...stepBase,
|
|
action: z.enum(["check", "uncheck"]),
|
|
locator: locatorSchema,
|
|
}),
|
|
z.strictObject({
|
|
...stepBase,
|
|
action: z.literal("wait_for"),
|
|
locator: locatorSchema,
|
|
state: z.enum(["attached", "detached", "visible", "hidden"]),
|
|
}),
|
|
z.strictObject({
|
|
step_id: scenarioIdentifierSchema,
|
|
action: z.literal("wait_for_timeout"),
|
|
duration_ms: z
|
|
.number()
|
|
.int()
|
|
.min(1)
|
|
.describe(
|
|
"Wait this many milliseconds; the wait ends early on cancellation.",
|
|
),
|
|
}),
|
|
]);
|
|
export type BrowserScenarioAction = z.infer<typeof browserScenarioActionSchema>;
|
|
|
|
const storageEntrySchema = z.strictObject({
|
|
name: z.string().min(1),
|
|
value: browserScenarioValueSchema,
|
|
});
|
|
|
|
export const browserScenarioStorageSchema = z
|
|
.strictObject({
|
|
cookies: z
|
|
.array(
|
|
z.strictObject({
|
|
name: z.string().min(1),
|
|
value: browserScenarioValueSchema,
|
|
destination: browserScenarioUrlSchema,
|
|
http_only: z.boolean(),
|
|
secure: z.boolean(),
|
|
same_site: z.enum(["Strict", "Lax", "None"]),
|
|
}),
|
|
)
|
|
.default([]),
|
|
local_storage: z
|
|
.array(
|
|
z.strictObject({
|
|
origin: browserOriginSchema,
|
|
entries: z.array(storageEntrySchema),
|
|
}),
|
|
)
|
|
.default([]),
|
|
session_storage: z
|
|
.array(
|
|
z.strictObject({
|
|
origin: browserOriginSchema,
|
|
entries: z.array(storageEntrySchema),
|
|
}),
|
|
)
|
|
.default([]),
|
|
})
|
|
.default({ cookies: [], local_storage: [], session_storage: [] })
|
|
.describe(
|
|
"Optional initial cookies, local storage, or session storage. Defaults to empty; every supplied value and origin must be declared and within the allowed origins.",
|
|
);
|
|
|
|
export const browserScenarioSecretSchema = z.strictObject({
|
|
secret_id: scenarioIdentifierSchema,
|
|
environment_variable: z
|
|
.string()
|
|
.min(1)
|
|
.refine(
|
|
(name) => !name.includes("=") && !name.includes("\0"),
|
|
"Environment variable names cannot contain '=' or NUL",
|
|
),
|
|
});
|
|
|
|
const snapshotKindSchema = z.enum([
|
|
"screenshot",
|
|
"dom",
|
|
"accessibility",
|
|
"url",
|
|
"history",
|
|
"storage",
|
|
]);
|
|
|
|
export const browserScenarioCaptureSchema = z
|
|
.strictObject({
|
|
after_each_step: z.array(snapshotKindSchema).default([]),
|
|
at_end: z.array(snapshotKindSchema).default(["url"]),
|
|
events: z
|
|
.array(
|
|
z.enum([
|
|
"console",
|
|
"page-errors",
|
|
"network",
|
|
"websockets",
|
|
"frames",
|
|
"workers",
|
|
"popups",
|
|
"downloads",
|
|
]),
|
|
)
|
|
.default([]),
|
|
network: browserNetworkContentSelectionSchema,
|
|
})
|
|
.default({
|
|
after_each_step: [],
|
|
at_end: ["url"],
|
|
events: [],
|
|
network: {
|
|
request_body: false,
|
|
response_body: false,
|
|
header_values: false,
|
|
},
|
|
})
|
|
.describe(
|
|
"Optional retained artifacts and event families. Defaults to only a final sanitized URL; request screenshots, DOM, accessibility, history, storage, and event capture explicitly.",
|
|
);
|