fix(platform): accept absolute paths for any host and stop blaming the ceiling for a missing grant (#552)

Addresses #548 and #545.

#548: processScenarioSchema required a leading "/" for executable,
working_directory and filesystem_roots, so no process scenario could be
expressed on Windows at all. The report suggested node:path's isAbsolute, but
that answers for the host running the check: on Linux `C:\tools` is not
absolute, so a scenario captured on Windows would fail validation when it is
replayed, compared, or asserted in a test on another host. A boundary schema
must not vary with its evaluator, so the check accepts the POSIX form, a
Windows drive path and a UNC share everywhere. The rejection message now names
the constraint instead of leaving the caller to infer it from "invalid request".
The HTTP `path` field inside `checkpoints` is an URL path and is deliberately
left alone.

I checked whether this merely moved the failure downstream: containment is
enforced by isPathWithinRoot, which already uses host-aware path.relative, so
validation really was the only blocker.

#545: when a scope is inside the administrator ceiling but no grant was ever
issued, the denial still pointed at widening the ceiling -- advice that cannot
help, since the ceiling already permits the operation. The `missing` payload is
computed against candidate *grants*, so it describes what a grant must cover,
not a ceiling gap. `PermissionRemediation` gains a `grant` variant saying
exactly that, and PermissionAuthority selects it when the denial is not a
ceiling violation. An explicitly requested remediation is still honoured, and a
genuine ceiling violation still says "configure".
This commit is contained in:
morluto
2026-10-05 18:50:10 +08:00
committed by GitHub
parent 5b383b2ddd
commit e793e124a2
10 changed files with 219 additions and 13 deletions
+2 -2
View File
@@ -537,9 +537,9 @@
"mcp_prompts": 6
},
"digests": {
"tools_sha256": "3ff61716cd0a493b077570af265db57a5dd7dde8489cea91077b9402ce0e6de5",
"tools_sha256": "b22484858ac42d79f19926ff3cbe46a409c817740a2a7098c9df9d542e805ee7",
"prompts_sha256": "fa889fc671185ac9c968c6dc8309cf609e709cdc837dbbf39b7cdfadb84ac2d7",
"combined_sha256": "b446bd2412595907a480eb42b2d7e8a6ac32df9685dc79b844c3be9eb563a1c9",
"combined_sha256": "2bdfe5e63d5e41f19af4b42e701c0d9f2022415fe9ea6584d2cbb7094c55a48a",
"providers_sha256": "c5a88a49990fafc8244972ee8ff543fc19995eb79db960da55f6a311e15340d1"
}
}
@@ -1,5 +1,5 @@
{
"manifest_id": "ecm_81d6fa3644c733735382fec83f2fd5b9dbfbde9d1d914f1321597ca54b388c5c",
"manifest_id": "ecm_f54aca28e223fe07c31926bc79eaccc3664e1cc5459d65672df2e788b24ef9e8",
"verifier": {
"id": "rea-managed-conformance",
"version": "1"
@@ -13,7 +13,7 @@
"skill_digests": [
{
"skill_id": "reverse-engineer-anything",
"sha256": "ea76bbc02f0f34b7659cd2d41539f4095957ebd2d458c1a885a9dd7600396914"
"sha256": "7efe0bbed43114110279e3b8f49d29e3894f3e025cc6c1e630a8fbc6900d5186"
}
],
"claims": [
+1 -1
View File
@@ -4,7 +4,7 @@ description: Reverse engineer native, managed, Electron/JavaScript, packaged, an
metadata:
version: "23"
tool_count: 122
catalog_digest: "b446bd2412595907a480eb42b2d7e8a6ac32df9685dc79b844c3be9eb563a1c9"
catalog_digest: "2bdfe5e63d5e41f19af4b42e701c0d9f2022415fe9ea6584d2cbb7094c55a48a"
---
# REA
+11 -3
View File
@@ -282,9 +282,17 @@ export class PermissionAuthority {
const outsideAdministratorCeiling =
denied.reason === "outside_administrator_ceiling";
const requestedRemediation = options.remediation ?? "configure";
const remediation =
outsideAdministratorCeiling && requestedRemediation !== "restart"
? this.outsideCeilingRemediation
// Only a genuine ceiling violation can be fixed by widening configuration.
// When the scope is inside the ceiling but no grant was ever issued, the
// `missing` payload describes what a *grant* must cover, so pointing the
// caller at the ceiling sends them to edit configuration that already
// permits the operation. An explicitly requested remediation is honoured.
const remediation = outsideAdministratorCeiling
? requestedRemediation === "restart"
? requestedRemediation
: this.outsideCeilingRemediation
: requestedRemediation === "configure"
? "grant"
: requestedRemediation;
return err(
new PermissionRequiredError({
@@ -0,0 +1,99 @@
import { describe, expect, it } from "vitest";
import { PermissionAuthority } from "./PermissionAuthority.js";
import type { PermissionRequiredError } from "../domain/errors.js";
import {
createPermissionPolicy,
type PermissionRequest,
type PermissionScope,
} from "../domain/permissionPolicy.js";
// Ceiling paths must exist: the policy canonicalizes them with realpath.
const ceilingScope: PermissionScope = {
capability: "browser_automate",
roots: [],
executables: [process.execPath],
origins: ["http://127.0.0.1:3000"],
environment_names: [],
network: "external",
mount: false,
};
/** A request the administrator ceiling already fully covers. */
const coveredRequest = (
overrides: Partial<PermissionScope> = {},
): PermissionRequest => ({
...ceilingScope,
network: "loopback",
operation_identity: "browser-scenario-1",
...overrides,
});
/** Narrow to the permission-denial error, failing the test on any other error. */
const denied = async (
authority: PermissionAuthority,
request: PermissionRequest,
remediation?: "elicit",
): Promise<PermissionRequiredError> => {
const result = await authority.authorize(
request,
"write",
remediation === undefined ? {} : { remediation },
);
expect(result.ok).toBe(false);
if (result.ok) throw new Error("expected a denial");
if (result.error._tag !== "PermissionRequiredError")
throw new Error(`expected a permission denial, got ${result.error._tag}`);
return result.error;
};
describe("permission denial remediation", () => {
it("asks for a grant, not a wider ceiling, when the ceiling covers the scope", async () => {
const authority = new PermissionAuthority(
createPermissionPolicy([ceilingScope], []),
);
// The ceiling contains this scope, so widening it cannot help.
expect(await denied(authority, coveredRequest())).toMatchObject({
remediation: "grant",
});
});
it("denies an empty request as needing a grant, not a ceiling violation", async () => {
const authority = new PermissionAuthority(
createPermissionPolicy([ceilingScope], []),
);
expect(
await denied(authority, {
capability: "browser_automate",
roots: [],
executables: [],
origins: [],
environment_names: [],
network: "none",
mount: false,
operation_identity: "browser-scenario-1",
}),
).toMatchObject({ remediation: "grant" });
});
it("still points at configuration for a genuine ceiling violation", async () => {
const authority = new PermissionAuthority(
createPermissionPolicy([ceilingScope], []),
);
expect(
await denied(
authority,
coveredRequest({ origins: ["https://not-configured.example"] }),
),
).toMatchObject({ remediation: "configure" });
});
it("keeps an explicitly requested elicit remediation untouched", async () => {
const authority = new PermissionAuthority(
createPermissionPolicy([ceilingScope], []),
);
expect(await denied(authority, coveredRequest(), "elicit")).toMatchObject({
remediation: "elicit",
});
});
});
+2
View File
@@ -49,6 +49,8 @@ export const analysisErrorRemediationAction = (
return "Approve the exact missing scope, then retry the operation.";
case "restart":
return "Add the exact missing scope to the administrator configuration, then restart the registered MCP server or client.";
case "grant":
return "The administrator ceiling already covers this scope; issue a grant for it (a project grant, or the documented auto-grant setting for an unattended environment), then retry.";
}
}
return analysisErrorUserMessage(error);
+13 -1
View File
@@ -519,7 +519,19 @@ export interface AnalysisErrorProjection
}
/** One legal recovery path for a denied permission request. */
export type PermissionRemediation = "configure" | "elicit" | "restart";
/**
* Legal recovery path for a denied permission.
*
* `grant` is deliberately distinct from `configure`: a request can be denied
* because no grant was ever issued even though the administrator ceiling
* already covers it. Telling that caller to widen the ceiling sends them to
* edit configuration that is already correct.
*/
export type PermissionRemediation =
| "configure"
| "elicit"
| "restart"
| "grant";
/** Exact denied authority and its legal recovery path. */
export interface PermissionRequiredContext {
+61
View File
@@ -235,3 +235,64 @@ describe("process scenario large interaction inputs", () => {
);
});
});
describe("process scenario path portability", () => {
const base = { arguments: [], environment: {}, filesystem_roots: [] };
it.each([
["posix", "/usr/bin/node", "/tmp"],
["windows drive with backslashes", "C:\\tools\\node.exe", "C:\\work"],
["windows drive with forward slashes", "c:/tools/node.exe", "c:/work"],
["unc share", "\\\\server\\share\\node.exe", "\\\\server\\share"],
])(
"accepts a %s path on any host",
(_label, executable, working_directory) => {
const parsed = processScenarioSchema.safeParse({
...base,
executable,
working_directory,
});
expect(parsed.success).toBe(true);
},
);
it("accepts Windows filesystem roots", () => {
const parsed = processScenarioSchema.safeParse({
...base,
executable: "C:\\tools\\node.exe",
working_directory: "C:\\work",
filesystem_roots: ["C:\\data", "D:\\more"],
});
expect(parsed.success).toBe(true);
});
it.each([
["relative", "tools/node.exe"],
["dot relative", "./node.exe"],
["parent relative", "../node.exe"],
["bare filename", "node.exe"],
["empty", ""],
])("still rejects a %s path", (_label, executable) => {
const parsed = processScenarioSchema.safeParse({
...base,
executable,
working_directory: "/tmp",
});
expect(parsed.success).toBe(false);
});
it("names the constraint so a rejected path is actionable", () => {
const parsed = processScenarioSchema.safeParse({
...base,
executable: "tools/node.exe",
working_directory: "/tmp",
});
expect(parsed.success).toBe(false);
if (parsed.success) return;
const messages = parsed.error.issues
.map(({ message }) => message)
.join("\n");
expect(messages).toContain("must be absolute");
expect(messages).toContain("C:\\tools\\node.exe");
});
});
+27 -3
View File
@@ -108,20 +108,44 @@ export const processComparisonContract = (
reactive: reactiveScenarioCommitment(scenario.reactive),
});
/**
* True when `value` is an absolute path for *any* supported host.
*
* `node:path`'s `isAbsolute` answers for the machine running it: on Linux
* `C:\tools` is not absolute. A boundary schema must not vary with the host
* that evaluates it — a scenario captured on Windows has to stay valid when it
* is replayed, compared, or validated by a test on Linux. So this accepts the
* POSIX form, a Windows drive path, and a UNC share, on every host.
*/
export const isAbsoluteScenarioPath = (value: string): boolean =>
value.startsWith("/") ||
/^[A-Za-z]:[\\/]/u.test(value) ||
value.startsWith("\\\\");
/**
* An absolute path for the host that will run the scenario. The message names
* the constraint so a rejected path is actionable, instead of leaving the
* caller to infer it from a generic "invalid request".
*/
const absoluteScenarioPath = z.string().refine(isAbsoluteScenarioPath, {
message:
"Path must be absolute: a POSIX path such as /usr/bin/node, a Windows path such as C:\\tools\\node.exe, or a UNC path such as \\\\server\\share",
});
/**
* Boundary schema for one bounded process experiment.
* Defaults are part of the evidence contract and must remain deterministic.
*/
export const processScenarioSchema = z
.object({
executable: z.string().startsWith("/"),
executable: absoluteScenarioPath,
arguments: z.array(z.string()).default([]),
working_directory: z.string().startsWith("/"),
working_directory: absoluteScenarioPath,
environment: z.record(environmentName, z.string()).default({}),
inherit_environment: z.array(environmentName).default([]),
secret_aliases: z.array(environmentName).default([]),
network_access: z.literal("host").default("host"),
filesystem_roots: z.array(z.string().startsWith("/")).default([]),
filesystem_roots: z.array(absoluteScenarioPath).default([]),
terminal: z
.object({
columns: z.number().int().min(1).max(65_535).default(80),
File diff suppressed because one or more lines are too long