diff --git a/README.md b/README.md index b7e0cec..241b041 100644 --- a/README.md +++ b/README.md @@ -28,6 +28,7 @@ Codex Quick Install · Pi Quick Install · Skills · + Sandbox Contract · Invocation · Architecture · Credits @@ -146,6 +147,27 @@ Profiles automatically include required companion skills and can be combined wit The npm installer and the full Claude Code/Codex/OpenCode plugins are alternative activation paths. Claude Code users should prefer the namespaced plugin because the selective installer currently targets the portable `.agents/skills` location used by Codex, OpenCode, and Pi. If a full plugin is already active, selectively copying the same skills does not reduce that plugin's loaded catalog. +## Sandbox Capability Contract + +The package assigns every bundled skill a default least-capability profile and an explicit set of allowed escalations. Inspect the complete contract or resolve one skill from the CLI: + +```bash +opencode-power-pack sandbox doctor +opencode-power-pack sandbox resolve --skill code-review +opencode-power-pack sandbox resolve --sandbox-profile publish --json +``` + +| Sandbox profile | Workspace | Network and credentials | External side effects | +|---|---|---|---| +| `observe` | Read | Denied | Denied | +| `develop` | Write | Denied | Denied | +| `network-read` | Write | Explicitly approved | Denied | +| `publish` | Write | Explicitly approved | Explicit confirmation required | + +This first contract version reports `advisory` enforcement. It describes the capability boundary that host adapters must enforce, but it does not isolate commands or replace the permissions configured by Codex, Claude Code, OpenCode, or Pi. `sandbox doctor` therefore reports `Backend: not-configured` and `Strict ready: no` instead of implying a stronger guarantee. + +Selective installations include a generated `SANDBOX_POLICY.json` beside each copied `SKILL.md`. The file is self-describing and preserves the skill's default profile even when the central package is not present. It remains advisory until an enforcement backend and host adapter are active. + ## Why This Exists Claude Code, Codex, OpenCode, and Pi read `SKILL.md` workflows, but many valuable workflows originated as Claude-specific commands and agents. Copying those artifacts directly does not preserve their orchestration, permissions, or subagent behavior. @@ -453,6 +475,13 @@ opencode-power-pack +-- package.json | +-- declares skills/ as a Pi package for pi install | ++-- sandbox/contract.json +| +-- maps all fifty-four skills to versioned capability profiles +| +-- records allowed escalation paths without claiming enforcement +| ++-- bin/sandbox/policy.mjs +| +-- validates, resolves, and reports the shared capability contract +| +-- .opencode/plugins/opencode-power-pack.js | +-- registers skills/ in config.skills.paths | +-- registers code-explorer as a read-only subagent @@ -480,6 +509,7 @@ The packaged agents deny edits, external network access, and nested tasks. `code | Portable and host-native subagent orchestration | Proprietary or non-redistributable plugins | | Licensed adaptations with immutable provenance | Automatic trust of third-party skill catalogs | | Explicit permission boundaries and regression tests | Supporting OpenCode versions older than 1.18.7 or obsolete Codex plugin formats | +| Versioned sandbox capability contracts and honest enforcement reporting | Treating advisory metadata as an OS security boundary | ## Contributing @@ -494,6 +524,7 @@ Before opening a PR: ```bash npm test +npm run test:sandbox npm run smoke:opencode npm pack --dry-run ``` diff --git a/bin/opencode-power-pack.mjs b/bin/opencode-power-pack.mjs index b4b85ce..30d7988 100755 --- a/bin/opencode-power-pack.mjs +++ b/bin/opencode-power-pack.mjs @@ -11,10 +11,17 @@ import { readdir, rename, rm, + writeFile, } from "node:fs/promises"; import os from "node:os"; import path from "node:path"; import { fileURLToPath } from "node:url"; +import { + loadSandboxContract, + portableSkillPolicy, + resolveSandboxProfile, + sandboxDoctorReport, +} from "./sandbox/policy.mjs"; const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."); const USAGE = `OpenCode Power Pack selective skill installer @@ -24,6 +31,9 @@ Usage: npx @waybarrios/opencode-power-pack install [options] npx @waybarrios/opencode-power-pack install --profile [options] npx @waybarrios/opencode-power-pack install --all [options] + npx @waybarrios/opencode-power-pack sandbox doctor [--json] + npx @waybarrios/opencode-power-pack sandbox resolve --skill [--json] + npx @waybarrios/opencode-power-pack sandbox resolve --sandbox-profile [--json] Options: --profile Install a curated profile. Repeatable. @@ -119,7 +129,13 @@ export function resolveSelection({ skillNames = [], profileNames = [], all = fal return [...selected].sort((left, right) => left.localeCompare(right)); } -async function replaceDirectoryWithRollback(source, destination, force, packageRoot) { +async function replaceDirectoryWithRollback( + source, + destination, + force, + packageRoot, + sandboxContract, +) { const parent = path.dirname(destination); const name = path.basename(destination); const lock = `${destination}.opp-lock`; @@ -150,6 +166,11 @@ async function replaceDirectoryWithRollback(source, destination, force, packageR path.join(staged, "THIRD_PARTY_NOTICES.md"), ); await cp(path.join(packageRoot, "LICENSES"), path.join(staged, "LICENSES"), { recursive: true }); + await writeFile( + path.join(staged, "SANDBOX_POLICY.json"), + `${JSON.stringify(portableSkillPolicy(sandboxContract, name), null, 2)}\n`, + "utf8", + ); if (force && await pathExists(destination)) { backup = path.join(parent, `.opp-backup-${name}-${randomUUID()}`); await rename(destination, backup); @@ -227,6 +248,7 @@ export async function installSkills({ packageRoot = PACKAGE_ROOT, }) { if (!dryRun) await mkdir(destination, { recursive: true }); + const sandboxContract = await loadSandboxContract(packageRoot); const results = []; for (const skillName of skillNames) { @@ -243,7 +265,13 @@ export async function installSkills({ continue; } - const warnings = await replaceDirectoryWithRollback(source, target, force, packageRoot); + const warnings = await replaceDirectoryWithRollback( + source, + target, + force, + packageRoot, + sandboxContract, + ); results.push({ name: skillName, status: exists ? "updated" : "installed", @@ -310,6 +338,82 @@ function printCatalog(catalog, skills, write) { } } +export function parseSandboxArgs(args) { + const [command, ...rest] = args; + if (!command) throw new Error("Choose a sandbox command: doctor or resolve."); + if (!["doctor", "resolve"].includes(command)) { + throw new Error(`Unknown sandbox command: ${command}`); + } + + const options = { command, json: false }; + for (let index = 0; index < rest.length; index += 1) { + const value = rest[index]; + if (value === "--json") { + options.json = true; + } else if (value === "--skill" || value === "--sandbox-profile") { + if (command !== "resolve") throw new Error(`${value} is only valid with sandbox resolve.`); + const target = rest[index + 1]; + if (!target || target.startsWith("-")) throw new Error(`${value} requires a value.`); + const key = value === "--skill" ? "skillName" : "profileName"; + if (options[key]) throw new Error(`${value} may be provided only once.`); + options[key] = target; + index += 1; + } else { + throw new Error(`Unknown sandbox option: ${value}`); + } + } + if (command === "resolve" && !options.skillName && !options.profileName) { + throw new Error("sandbox resolve requires --skill or --sandbox-profile."); + } + if (command === "resolve" && options.skillName && options.profileName) { + throw new Error("Choose exactly one of --skill or --sandbox-profile."); + } + return options; +} + +function printSandboxResolution(resolution, write) { + if (resolution.skill) write(`Skill: ${resolution.skill}\n`); + write(`Profile: ${resolution.profile.name}\n`); + write(`Description: ${resolution.profile.description}\n`); + write(`Risk level: ${resolution.profile.riskLevel}\n`); + write(`Enforcement: ${resolution.profile.enforcementLevel}\n`); + write("Capabilities:\n"); + for (const [name, value] of Object.entries(resolution.profile.capabilities)) { + write(` ${name.padEnd(20)} ${value}\n`); + } + if (resolution.allowedEscalations) { + const names = resolution.allowedEscalations.map((profile) => profile.name); + write(`Allowed escalations: ${names.length > 0 ? names.join(", ") : "none"}\n`); + } + write("Warning: advisory metadata does not isolate commands or tools.\n"); +} + +function printSandboxDoctor(report, write) { + write(`Sandbox contract: ${report.ok ? "valid" : "invalid"}\n`); + write(`Schema version: ${report.schemaVersion}\n`); + write(`Profiles: ${report.profiles}\n`); + write(`Assigned skills: ${report.assignedSkills}/${report.packagedSkills}\n`); + write(`Enforcement: ${report.enforcementLevel}\n`); + write(`Backend: ${report.backend}\n`); + write(`Strict ready: ${report.strictReady ? "yes" : "no"}\n`); + for (const warning of report.warnings) write(`Warning: ${warning}\n`); +} + +export async function runSandboxCommand(args, context) { + const options = parseSandboxArgs(args); + const skills = await discoverSkills(context.packageRoot); + const availableSkillNames = skills.map((skill) => skill.name); + const contract = await loadSandboxContract(context.packageRoot, availableSkillNames); + const result = options.command === "doctor" + ? sandboxDoctorReport(contract, availableSkillNames) + : resolveSandboxProfile(contract, options); + + if (options.json) context.write(`${JSON.stringify(result, null, 2)}\n`); + else if (options.command === "doctor") printSandboxDoctor(result, context.write); + else printSandboxResolution(result, context.write); + return 0; +} + export async function main(args = process.argv.slice(2), context = {}) { const write = context.write || ((text) => process.stdout.write(text)); const cwd = context.cwd || process.cwd(); @@ -322,6 +426,10 @@ export async function main(args = process.argv.slice(2), context = {}) { return 0; } + if (command === "sandbox") { + return runSandboxCommand(rest, { packageRoot, write }); + } + const catalog = await loadCatalog(packageRoot); const skills = await discoverSkills(packageRoot); @@ -372,8 +480,10 @@ export function isDirectInvocation(argvEntry, moduleUrl = import.meta.url) { const invokedDirectly = isDirectInvocation(process.argv[1]); if (invokedDirectly) { - main().catch((error) => { - process.stderr.write(`Error: ${error.message}\n`); - process.exitCode = 1; - }); + main() + .then((exitCode) => { process.exitCode = exitCode; }) + .catch((error) => { + process.stderr.write(`Error: ${error.message}\n`); + process.exitCode = 1; + }); } diff --git a/bin/sandbox/policy.mjs b/bin/sandbox/policy.mjs new file mode 100644 index 0000000..6f95550 --- /dev/null +++ b/bin/sandbox/policy.mjs @@ -0,0 +1,205 @@ +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 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) { + validateSandboxContract(contract, availableSkillNames); + return { + ok: true, + schemaVersion: contract.schemaVersion, + enforcementLevel: contract.enforcementLevel, + backend: "not-configured", + strictReady: false, + profiles: Object.keys(contract.profiles).length, + assignedSkills: Object.keys(contract.skills).length, + packagedSkills: availableSkillNames.length, + warnings: [ + "Capability profiles are advisory until an enforcement backend and host adapter are active.", + ], + }; +} diff --git a/package.json b/package.json index 7460f10..d748947 100644 --- a/package.json +++ b/package.json @@ -21,6 +21,7 @@ ".codex-plugin", ".opencode", "bin", + "sandbox", "assets", "skillsets.json", "UPSTREAMS.json", @@ -29,6 +30,7 @@ ], "scripts": { "test": "node --test", + "test:sandbox": "node --test tests/sandbox-policy.test.mjs", "prepublishOnly": "npm test", "eval:behavioral": "node scripts/behavioral-evals.mjs run", "eval:behavioral:accept": "node scripts/behavioral-evals.mjs accept", diff --git a/sandbox/contract.json b/sandbox/contract.json new file mode 100644 index 0000000..feb86d6 --- /dev/null +++ b/sandbox/contract.json @@ -0,0 +1,269 @@ +{ + "$schema": "./contract.schema.json", + "schemaVersion": 1, + "enforcementLevel": "advisory", + "profiles": { + "observe": { + "description": "Inspect and analyze the workspace without modifying it or using the network.", + "riskLevel": 0, + "capabilities": { + "workspace": "read", + "temporaryFiles": "write", + "network": "deny", + "credentials": "deny", + "externalSideEffects": "deny" + } + }, + "develop": { + "description": "Modify the workspace and temporary files without network access or external side effects.", + "riskLevel": 1, + "capabilities": { + "workspace": "write", + "temporaryFiles": "write", + "network": "deny", + "credentials": "deny", + "externalSideEffects": "deny" + } + }, + "network-read": { + "description": "Use explicitly approved network destinations and credentials for retrieval without external mutations.", + "riskLevel": 2, + "capabilities": { + "workspace": "write", + "temporaryFiles": "write", + "network": "explicit", + "credentials": "explicit", + "externalSideEffects": "deny" + } + }, + "publish": { + "description": "Perform explicitly confirmed external mutations using narrowly scoped network and credential access.", + "riskLevel": 3, + "capabilities": { + "workspace": "write", + "temporaryFiles": "write", + "network": "explicit", + "credentials": "explicit", + "externalSideEffects": "confirm" + } + } + }, + "skills": { + "agentic-actions-auditor": { + "defaultProfile": "observe", + "allowedEscalations": ["network-read"] + }, + "agents-md-improver": { + "defaultProfile": "develop", + "allowedEscalations": [] + }, + "agents-md-revise": { + "defaultProfile": "develop", + "allowedEscalations": [] + }, + "ai-slop": { + "defaultProfile": "observe", + "allowedEscalations": [] + }, + "code-architect": { + "defaultProfile": "observe", + "allowedEscalations": [] + }, + "code-explorer": { + "defaultProfile": "observe", + "allowedEscalations": [] + }, + "code-quality": { + "defaultProfile": "develop", + "allowedEscalations": ["network-read"] + }, + "code-review": { + "defaultProfile": "observe", + "allowedEscalations": ["network-read", "publish"] + }, + "code-reviewer": { + "defaultProfile": "observe", + "allowedEscalations": [] + }, + "codeql": { + "defaultProfile": "develop", + "allowedEscalations": ["network-read"] + }, + "design-patterns": { + "defaultProfile": "observe", + "allowedEscalations": [] + }, + "differential-review": { + "defaultProfile": "develop", + "allowedEscalations": ["network-read"] + }, + "feature-dev": { + "defaultProfile": "develop", + "allowedEscalations": ["network-read"] + }, + "fp-check": { + "defaultProfile": "observe", + "allowedEscalations": [] + }, + "frontend-design": { + "defaultProfile": "develop", + "allowedEscalations": ["network-read"] + }, + "hf-cli": { + "defaultProfile": "network-read", + "allowedEscalations": ["publish"] + }, + "hf-cloud-aws-context-discovery": { + "defaultProfile": "network-read", + "allowedEscalations": [] + }, + "hf-cloud-python-env-setup": { + "defaultProfile": "develop", + "allowedEscalations": ["network-read"] + }, + "hf-cloud-sagemaker-deployment-planner": { + "defaultProfile": "network-read", + "allowedEscalations": ["publish"] + }, + "hf-cloud-sagemaker-iam-preflight": { + "defaultProfile": "network-read", + "allowedEscalations": ["publish"] + }, + "hf-cloud-sagemaker-production-defaults": { + "defaultProfile": "publish", + "allowedEscalations": [] + }, + "hf-cloud-serving-image-selection": { + "defaultProfile": "network-read", + "allowedEscalations": ["publish"] + }, + "hf-mem": { + "defaultProfile": "observe", + "allowedEscalations": ["network-read"] + }, + "huggingface-best": { + "defaultProfile": "network-read", + "allowedEscalations": [] + }, + "huggingface-community-evals": { + "defaultProfile": "network-read", + "allowedEscalations": ["publish"] + }, + "huggingface-datasets": { + "defaultProfile": "network-read", + "allowedEscalations": ["publish"] + }, + "huggingface-gradio": { + "defaultProfile": "develop", + "allowedEscalations": ["network-read", "publish"] + }, + "huggingface-llm-trainer": { + "defaultProfile": "publish", + "allowedEscalations": [] + }, + "huggingface-local-models": { + "defaultProfile": "network-read", + "allowedEscalations": [] + }, + "huggingface-lora-space-builder": { + "defaultProfile": "publish", + "allowedEscalations": [] + }, + "huggingface-paper-publisher": { + "defaultProfile": "publish", + "allowedEscalations": [] + }, + "huggingface-papers": { + "defaultProfile": "network-read", + "allowedEscalations": ["publish"] + }, + "huggingface-spaces": { + "defaultProfile": "publish", + "allowedEscalations": [] + }, + "huggingface-tool-builder": { + "defaultProfile": "develop", + "allowedEscalations": ["network-read", "publish"] + }, + "huggingface-trackio": { + "defaultProfile": "publish", + "allowedEscalations": [] + }, + "huggingface-vision-trainer": { + "defaultProfile": "publish", + "allowedEscalations": [] + }, + "huggingface-zerogpu": { + "defaultProfile": "publish", + "allowedEscalations": [] + }, + "insecure-defaults": { + "defaultProfile": "observe", + "allowedEscalations": [] + }, + "mcp-builder": { + "defaultProfile": "develop", + "allowedEscalations": ["network-read"] + }, + "paper-summarizer": { + "defaultProfile": "observe", + "allowedEscalations": ["network-read"] + }, + "sarif-parsing": { + "defaultProfile": "develop", + "allowedEscalations": [] + }, + "security-review": { + "defaultProfile": "observe", + "allowedEscalations": ["network-read", "publish"] + }, + "security-threat-model": { + "defaultProfile": "develop", + "allowedEscalations": [] + }, + "semgrep": { + "defaultProfile": "develop", + "allowedEscalations": ["network-read"] + }, + "semgrep-rule-creator": { + "defaultProfile": "develop", + "allowedEscalations": [] + }, + "semgrep-rule-variant-creator": { + "defaultProfile": "develop", + "allowedEscalations": [] + }, + "sharp-edges": { + "defaultProfile": "observe", + "allowedEscalations": [] + }, + "skill-creator": { + "defaultProfile": "develop", + "allowedEscalations": ["network-read"] + }, + "supply-chain-risk-auditor": { + "defaultProfile": "develop", + "allowedEscalations": ["network-read"] + }, + "train-sentence-transformers": { + "defaultProfile": "publish", + "allowedEscalations": [] + }, + "transformers-js": { + "defaultProfile": "develop", + "allowedEscalations": ["network-read"] + }, + "trl-training": { + "defaultProfile": "publish", + "allowedEscalations": [] + }, + "variant-analysis": { + "defaultProfile": "observe", + "allowedEscalations": [] + }, + "vuln-report": { + "defaultProfile": "observe", + "allowedEscalations": ["develop"] + } + } +} diff --git a/sandbox/contract.schema.json b/sandbox/contract.schema.json new file mode 100644 index 0000000..2447f77 --- /dev/null +++ b/sandbox/contract.schema.json @@ -0,0 +1,109 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://github.com/waybarrios/opencode-power-pack/sandbox/contract.schema.json", + "title": "OpenCode Power Pack sandbox capability contract", + "type": "object", + "additionalProperties": false, + "required": [ + "$schema", + "schemaVersion", + "enforcementLevel", + "profiles", + "skills" + ], + "properties": { + "$schema": { + "const": "./contract.schema.json" + }, + "schemaVersion": { + "const": 1 + }, + "enforcementLevel": { + "const": "advisory" + }, + "profiles": { + "type": "object", + "minProperties": 1, + "propertyNames": { + "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" + }, + "additionalProperties": { + "$ref": "#/$defs/profile" + } + }, + "skills": { + "type": "object", + "minProperties": 1, + "propertyNames": { + "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" + }, + "additionalProperties": { + "$ref": "#/$defs/skillAssignment" + } + } + }, + "$defs": { + "profile": { + "type": "object", + "additionalProperties": false, + "required": ["description", "riskLevel", "capabilities"], + "properties": { + "description": { + "type": "string", + "minLength": 1 + }, + "riskLevel": { + "type": "integer", + "minimum": 0 + }, + "capabilities": { + "type": "object", + "additionalProperties": false, + "required": [ + "workspace", + "temporaryFiles", + "network", + "credentials", + "externalSideEffects" + ], + "properties": { + "workspace": { + "enum": ["read", "write"] + }, + "temporaryFiles": { + "enum": ["deny", "write"] + }, + "network": { + "enum": ["deny", "explicit"] + }, + "credentials": { + "enum": ["deny", "explicit"] + }, + "externalSideEffects": { + "enum": ["deny", "confirm"] + } + } + } + } + }, + "skillAssignment": { + "type": "object", + "additionalProperties": false, + "required": ["defaultProfile", "allowedEscalations"], + "properties": { + "defaultProfile": { + "type": "string", + "minLength": 1 + }, + "allowedEscalations": { + "type": "array", + "uniqueItems": true, + "items": { + "type": "string", + "minLength": 1 + } + } + } + } + } +} diff --git a/tests/package-surface.test.mjs b/tests/package-surface.test.mjs index 6aa2308..5da75f2 100644 --- a/tests/package-surface.test.mjs +++ b/tests/package-surface.test.mjs @@ -6,6 +6,7 @@ import { existsSync, mkdirSync, mkdtempSync, + readFileSync, readdirSync, rmSync, writeFileSync, @@ -52,6 +53,9 @@ test("published package relies on native commands and ships every skill", () => "focused review metadata is published", ); assert.ok(packaged.has("bin/opencode-power-pack.mjs"), "selective installer is published"); + assert.ok(packaged.has("bin/sandbox/policy.mjs"), "sandbox policy resolver is published"); + assert.ok(packaged.has("sandbox/contract.json"), "sandbox contract is published"); + assert.ok(packaged.has("sandbox/contract.schema.json"), "sandbox schema is published"); assert.ok(packaged.has("skillsets.json"), "selective profiles are published"); for (const prefix of ["evals/", "scripts/", "tests/", "docs/superpowers/"]) { assert.equal( @@ -121,6 +125,27 @@ test("packed npm artifact exposes a working selective-installer executable", () assert.match(output, /Profiles:/); assert.match(output, /recommended/); assert.match(output, /code-review/); + const sandboxOutput = execFileSync(executable, ["sandbox", "doctor"], { + cwd: installRoot, + encoding: "utf8", + }); + assert.match(sandboxOutput, /Sandbox contract: valid/); + assert.match(sandboxOutput, /Assigned skills: 54\/54/); + assert.match(sandboxOutput, /Strict ready: no/); + mkdirSync(join(installRoot, ".git")); + execFileSync(executable, ["install", "code-review", "--project"], { + cwd: installRoot, + encoding: "utf8", + }); + const installedPolicy = JSON.parse( + readFileSync( + join(installRoot, ".agents", "skills", "code-review", "SANDBOX_POLICY.json"), + "utf8", + ), + ); + assert.equal(installedPolicy.skill, "code-review"); + assert.equal(installedPolicy.profile.name, "observe"); + assert.equal(installedPolicy.enforcementLevel, "advisory"); } finally { rmSync(packedRoot, { recursive: true, force: true }); } diff --git a/tests/sandbox-policy.test.mjs b/tests/sandbox-policy.test.mjs new file mode 100644 index 0000000..4487b9e --- /dev/null +++ b/tests/sandbox-policy.test.mjs @@ -0,0 +1,202 @@ +import { test } from "node:test"; +import assert from "node:assert/strict"; +import { readFile } from "node:fs/promises"; +import path from "node:path"; +import { + discoverSkills, + main, + parseSandboxArgs, +} from "../bin/opencode-power-pack.mjs"; +import { + loadSandboxContract, + portableSkillPolicy, + resolveSandboxProfile, + sandboxDoctorReport, + validateSandboxContract, +} from "../bin/sandbox/policy.mjs"; + +const REPO = process.env.REPO || process.cwd(); + +function clone(value) { + return structuredClone(value); +} + +test("sandbox contract covers every packaged skill with four ordered profiles", async () => { + const skills = await discoverSkills(REPO); + const names = skills.map((skill) => skill.name); + const contract = await loadSandboxContract(REPO, names); + + assert.equal(contract.schemaVersion, 1); + assert.equal(contract.enforcementLevel, "advisory"); + assert.deepEqual(Object.keys(contract.profiles), [ + "observe", + "develop", + "network-read", + "publish", + ]); + assert.equal(Object.keys(contract.skills).length, names.length); + assert.deepEqual(Object.keys(contract.skills).sort(), names); + assert.deepEqual( + Object.values(contract.profiles).map((profile) => profile.riskLevel), + [0, 1, 2, 3], + ); +}); + +test("sandbox assignments preserve required writes and documented external modes", async () => { + const contract = await loadSandboxContract(REPO); + const expected = { + "differential-review": ["develop", ["network-read"]], + "security-threat-model": ["develop", []], + "supply-chain-risk-auditor": ["develop", ["network-read"]], + "security-review": ["observe", ["network-read", "publish"]], + "huggingface-community-evals": ["network-read", ["publish"]], + "huggingface-datasets": ["network-read", ["publish"]], + "huggingface-papers": ["network-read", ["publish"]], + "huggingface-tool-builder": ["develop", ["network-read", "publish"]], + }; + + for (const [skillName, [defaultProfile, allowedEscalations]] of Object.entries(expected)) { + assert.deepEqual(contract.skills[skillName], { defaultProfile, allowedEscalations }, skillName); + } +}); + +test("sandbox JSON schema mirrors the closed top-level contract", async () => { + const schema = JSON.parse( + await readFile(path.join(REPO, "sandbox", "contract.schema.json"), "utf8"), + ); + + assert.equal(schema.additionalProperties, false); + assert.deepEqual(schema.required, [ + "$schema", + "schemaVersion", + "enforcementLevel", + "profiles", + "skills", + ]); + assert.equal(schema.properties.schemaVersion.const, 1); + assert.equal(schema.properties.enforcementLevel.const, "advisory"); + assert.equal(schema.$defs.profile.additionalProperties, false); + assert.equal(schema.$defs.skillAssignment.additionalProperties, false); +}); + +test("sandbox validation rejects unknown fields, incomplete coverage, and unsafe escalations", async () => { + const skills = await discoverSkills(REPO); + const names = skills.map((skill) => skill.name); + const contract = await loadSandboxContract(REPO, names); + + const unknownField = clone(contract); + unknownField.unexpected = true; + assert.throws(() => validateSandboxContract(unknownField, names), /unknown field: unexpected/); + + const incomplete = clone(contract); + delete incomplete.skills[names[0]]; + assert.throws(() => validateSandboxContract(incomplete, names), /missing packaged skills/); + + const downwardEscalation = clone(contract); + downwardEscalation.skills["frontend-design"] = { + defaultProfile: "develop", + allowedEscalations: ["observe"], + }; + assert.throws(() => validateSandboxContract(downwardEscalation, names), /must increase riskLevel/); + + assert.throws( + () => resolveSandboxProfile(contract, { skillName: "__proto__" }), + /Unknown sandbox skill/, + ); + assert.throws( + () => resolveSandboxProfile(contract, { profileName: "toString" }), + /Unknown sandbox profile/, + ); +}); + +test("skill and direct-profile resolution report advisory capabilities explicitly", async () => { + const contract = await loadSandboxContract(REPO); + const skill = resolveSandboxProfile(contract, { skillName: "code-review" }); + + assert.equal(skill.skill, "code-review"); + assert.equal(skill.profile.name, "observe"); + assert.equal(skill.profile.enforcementLevel, "advisory"); + assert.deepEqual( + skill.allowedEscalations.map((profile) => profile.name), + ["network-read", "publish"], + ); + + const direct = resolveSandboxProfile(contract, { profileName: "publish" }); + assert.equal(direct.profile.capabilities.externalSideEffects, "confirm"); + assert.throws( + () => resolveSandboxProfile(contract, { skillName: "code-review", profileName: "observe" }), + /exactly one/, + ); +}); + +test("portable policies remain self-describing and never claim enforcement", async () => { + const contract = await loadSandboxContract(REPO); + const policy = portableSkillPolicy(contract, "huggingface-spaces"); + + assert.equal(policy.schemaVersion, 1); + assert.equal(policy.skill, "huggingface-spaces"); + assert.equal(policy.profile.name, "publish"); + assert.equal(policy.enforcementLevel, "advisory"); + assert.match(policy.warning, /advisory/i); +}); + +test("sandbox doctor reports complete coverage and no configured backend", async () => { + const skills = await discoverSkills(REPO); + const names = skills.map((skill) => skill.name); + const contract = await loadSandboxContract(REPO, names); + const report = sandboxDoctorReport(contract, names); + + assert.deepEqual(report, { + ok: true, + schemaVersion: 1, + enforcementLevel: "advisory", + backend: "not-configured", + strictReady: false, + profiles: 4, + assignedSkills: 54, + packagedSkills: 54, + warnings: [ + "Capability profiles are advisory until an enforcement backend and host adapter are active.", + ], + }); +}); + +test("sandbox CLI supports deterministic text and JSON output", async () => { + let output = ""; + const context = { + cwd: REPO, + home: REPO, + packageRoot: REPO, + write: (text) => { output += text; }, + }; + + assert.equal(await main(["sandbox", "doctor"], context), 0); + assert.match(output, /Assigned skills: 54\/54/); + assert.match(output, /Enforcement: advisory/); + assert.match(output, /Strict ready: no/); + + output = ""; + assert.equal( + await main(["sandbox", "resolve", "--skill", "code-review", "--json"], context), + 0, + ); + const resolution = JSON.parse(output); + assert.equal(resolution.skill, "code-review"); + assert.equal(resolution.profile.name, "observe"); + assert.equal(resolution.profile.enforcementLevel, "advisory"); +}); + +test("sandbox CLI parser fails closed on ambiguous and malformed selectors", () => { + assert.deepEqual(parseSandboxArgs(["doctor", "--json"]), { + command: "doctor", + json: true, + }); + assert.throws(() => parseSandboxArgs([]), /doctor or resolve/); + assert.throws(() => parseSandboxArgs(["missing"]), /Unknown sandbox command/); + assert.throws(() => parseSandboxArgs(["resolve"]), /requires --skill or --sandbox-profile/); + assert.throws( + () => parseSandboxArgs(["resolve", "--skill", "code-review", "--sandbox-profile", "observe"]), + /exactly one/, + ); + assert.throws(() => parseSandboxArgs(["doctor", "--skill", "code-review"]), /only valid/); +}); diff --git a/tests/selective-installer.test.mjs b/tests/selective-installer.test.mjs index 13e06a5..17c1ba6 100644 --- a/tests/selective-installer.test.mjs +++ b/tests/selective-installer.test.mjs @@ -118,6 +118,13 @@ test("installer copies only selected skills, skips existing skills, and replaces /Third-Party Notices/, ); assert.ok((await readdir(path.join(destination, "code-review", "LICENSES"))).length > 0); + const sandboxPolicy = JSON.parse( + await readFile(path.join(destination, "code-review", "SANDBOX_POLICY.json"), "utf8"), + ); + assert.equal(sandboxPolicy.skill, "code-review"); + assert.equal(sandboxPolicy.profile.name, "observe"); + assert.equal(sandboxPolicy.enforcementLevel, "advisory"); + assert.match(sandboxPolicy.warning, /advisory/i); const sentinel = path.join(destination, "code-review", "stale.txt"); await writeFile(sentinel, "stale", "utf8");