Files
Wayner Barrios ab74f6a2ce Add a fail-closed native sandbox runner for portable skill execution
Pin Anthropic's sandbox runtime and translate trusted skill profiles into lightweight, on-demand filesystem, network, credential, and process-tree restrictions. Add readiness diagnostics, secure command and Git workspace discovery, signal-safe cleanup, Linux and macOS integration coverage, packaged-runtime checks, and practical compatibility guidance for Codex, Claude Code, OpenCode, and Pi.
2026-08-16 13:43:54 -05:00

228 lines
9.0 KiB
JavaScript

import { readFile } from "node:fs/promises";
import path from "node:path";
const TOP_LEVEL_KEYS = new Set([
"$schema",
"schemaVersion",
"enforcementLevel",
"profiles",
"skills",
]);
const PROFILE_KEYS = new Set(["description", "riskLevel", "capabilities"]);
const CAPABILITY_KEYS = new Set([
"workspace",
"temporaryFiles",
"network",
"credentials",
"externalSideEffects",
]);
const ASSIGNMENT_KEYS = new Set(["defaultProfile", "allowedEscalations"]);
function isObject(value) {
return value !== null && typeof value === "object" && !Array.isArray(value);
}
function assertObject(value, label) {
if (!isObject(value)) throw new TypeError(`${label} must be an object.`);
}
function assertExactKeys(value, expected, label) {
for (const key of Object.keys(value)) {
if (!expected.has(key)) throw new TypeError(`${label} has unknown field: ${key}`);
}
for (const key of expected) {
if (!Object.hasOwn(value, key)) throw new TypeError(`${label} is missing field: ${key}`);
}
}
function assertChoice(value, choices, label) {
if (!choices.includes(value)) {
throw new TypeError(`${label} must be one of: ${choices.join(", ")}.`);
}
}
function ownEntry(object, key) {
return Object.hasOwn(object, key) ? object[key] : undefined;
}
export function validateSandboxContract(contract, availableSkillNames) {
assertObject(contract, "Sandbox contract");
assertExactKeys(contract, TOP_LEVEL_KEYS, "Sandbox contract");
if (contract.$schema !== "./contract.schema.json") {
throw new TypeError("Sandbox contract must reference ./contract.schema.json.");
}
if (contract.schemaVersion !== 1) {
throw new TypeError(`Unsupported sandbox contract schema version: ${contract.schemaVersion}`);
}
if (contract.enforcementLevel !== "advisory") {
throw new TypeError("PR 1 sandbox contracts must report advisory enforcement.");
}
assertObject(contract.profiles, "Sandbox profiles");
const profileEntries = Object.entries(contract.profiles);
if (profileEntries.length === 0) throw new TypeError("Sandbox contract must define profiles.");
for (const [name, profile] of profileEntries) {
if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) {
throw new TypeError(`Invalid sandbox profile name: ${name}`);
}
assertObject(profile, `Sandbox profile ${name}`);
assertExactKeys(profile, PROFILE_KEYS, `Sandbox profile ${name}`);
if (typeof profile.description !== "string" || profile.description.trim() === "") {
throw new TypeError(`Sandbox profile ${name} requires a description.`);
}
if (!Number.isInteger(profile.riskLevel) || profile.riskLevel < 0) {
throw new TypeError(`Sandbox profile ${name} requires a non-negative integer riskLevel.`);
}
assertObject(profile.capabilities, `Sandbox profile ${name} capabilities`);
assertExactKeys(profile.capabilities, CAPABILITY_KEYS, `Sandbox profile ${name} capabilities`);
assertChoice(profile.capabilities.workspace, ["read", "write"], `${name}.workspace`);
assertChoice(profile.capabilities.temporaryFiles, ["deny", "write"], `${name}.temporaryFiles`);
assertChoice(profile.capabilities.network, ["deny", "explicit"], `${name}.network`);
assertChoice(profile.capabilities.credentials, ["deny", "explicit"], `${name}.credentials`);
assertChoice(
profile.capabilities.externalSideEffects,
["deny", "confirm"],
`${name}.externalSideEffects`,
);
}
assertObject(contract.skills, "Sandbox skill assignments");
const assignmentEntries = Object.entries(contract.skills);
if (assignmentEntries.length === 0) {
throw new TypeError("Sandbox contract must assign skills.");
}
for (const [skillName, assignment] of assignmentEntries) {
if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(skillName)) {
throw new TypeError(`Invalid sandbox skill name: ${skillName}`);
}
assertObject(assignment, `Sandbox assignment ${skillName}`);
assertExactKeys(assignment, ASSIGNMENT_KEYS, `Sandbox assignment ${skillName}`);
const defaultProfile = ownEntry(contract.profiles, assignment.defaultProfile);
if (!defaultProfile) {
throw new TypeError(`${skillName} references unknown profile: ${assignment.defaultProfile}`);
}
if (!Array.isArray(assignment.allowedEscalations)) {
throw new TypeError(`${skillName}.allowedEscalations must be an array.`);
}
const seen = new Set();
for (const escalationName of assignment.allowedEscalations) {
if (typeof escalationName !== "string" || escalationName.trim() === "") {
throw new TypeError(`${skillName} has an invalid escalation profile.`);
}
if (seen.has(escalationName)) {
throw new TypeError(`${skillName} repeats escalation profile: ${escalationName}`);
}
seen.add(escalationName);
const escalation = ownEntry(contract.profiles, escalationName);
if (!escalation) {
throw new TypeError(`${skillName} references unknown escalation: ${escalationName}`);
}
if (escalationName === assignment.defaultProfile) {
throw new TypeError(`${skillName} repeats its default profile as an escalation.`);
}
if (escalation.riskLevel <= defaultProfile.riskLevel) {
throw new TypeError(`${skillName} escalation ${escalationName} must increase riskLevel.`);
}
}
}
if (availableSkillNames) {
const available = new Set(availableSkillNames);
const assigned = new Set(Object.keys(contract.skills));
const missing = [...available].filter((name) => !assigned.has(name)).sort();
const unknown = [...assigned].filter((name) => !available.has(name)).sort();
if (missing.length > 0) {
throw new TypeError(`Sandbox assignments missing packaged skills: ${missing.join(", ")}`);
}
if (unknown.length > 0) {
throw new TypeError(`Sandbox assignments reference unknown skills: ${unknown.join(", ")}`);
}
}
return contract;
}
export async function loadSandboxContract(packageRoot, availableSkillNames) {
const source = await readFile(path.join(packageRoot, "sandbox", "contract.json"), "utf8");
return validateSandboxContract(JSON.parse(source), availableSkillNames);
}
function resolvedProfile(contract, profileName) {
const profile = ownEntry(contract.profiles, profileName);
if (!profile) throw new Error(`Unknown sandbox profile: ${profileName}`);
return {
name: profileName,
description: profile.description,
riskLevel: profile.riskLevel,
capabilities: { ...profile.capabilities },
enforcementLevel: contract.enforcementLevel,
};
}
export function resolveSandboxProfile(contract, { skillName, profileName }) {
if ((skillName ? 1 : 0) + (profileName ? 1 : 0) !== 1) {
throw new Error("Choose exactly one of --skill or --sandbox-profile.");
}
if (profileName) return { profile: resolvedProfile(contract, profileName) };
const assignment = ownEntry(contract.skills, skillName);
if (!assignment) throw new Error(`Unknown sandbox skill: ${skillName}`);
return {
skill: skillName,
profile: resolvedProfile(contract, assignment.defaultProfile),
allowedEscalations: assignment.allowedEscalations.map((name) => resolvedProfile(contract, name)),
};
}
export function resolveSandboxExecutionProfile(contract, { skillName, profileName }) {
if (!skillName) throw new Error("sandbox exec requires --skill.");
const resolution = resolveSandboxProfile(contract, { skillName });
if (!profileName || profileName === resolution.profile.name) return resolution.profile;
const escalation = resolution.allowedEscalations.find((profile) => profile.name === profileName);
if (!escalation) {
throw new Error(`Skill ${skillName} does not permit sandbox profile: ${profileName}`);
}
return escalation;
}
export function portableSkillPolicy(contract, skillName) {
const resolution = resolveSandboxProfile(contract, { skillName });
return {
schemaVersion: contract.schemaVersion,
source: "@waybarrios/opencode-power-pack",
enforcementLevel: contract.enforcementLevel,
warning: "This capability policy is advisory until an enforcement backend and host adapter are active.",
skill: resolution.skill,
profile: resolution.profile,
allowedEscalations: resolution.allowedEscalations,
};
}
export function sandboxDoctorReport(contract, availableSkillNames, runtimeStatus) {
validateSandboxContract(contract, availableSkillNames);
const status = runtimeStatus || {
backend: "not-configured",
runnerReady: false,
executionLevel: "advisory",
errors: [],
warnings: [],
};
return {
ok: true,
schemaVersion: contract.schemaVersion,
enforcementLevel: contract.enforcementLevel,
backend: status.backend,
runnerReady: status.runnerReady,
executionLevel: status.executionLevel,
strictReady: false,
profiles: Object.keys(contract.profiles).length,
assignedSkills: Object.keys(contract.skills).length,
packagedSkills: availableSkillNames.length,
warnings: [
...status.errors.map((error) => `Runtime unavailable: ${error}`),
...status.warnings,
"Skill metadata remains advisory until a host adapter routes commands through sandbox exec.",
],
};
}