Land scoped stage artifact access

This commit is contained in:
2026-10-18 12:03:02 +01:00
9 changed files with 325 additions and 13 deletions
+20
View File
@@ -0,0 +1,20 @@
# Scoped stage artifact access
## What this item changed
The server now derives one exact artifact capability for an OpenCode or Pi
model-stage visit: its own directory is writable when the edit tool is present,
and its own plus completed earlier visit directories in the same run are
readable when a file-reading tool is present. No artifact root, sibling, future
visit, other run, traversal path, or symlink escape is granted. The scope is
empty if the runner cannot validate its artifact root.
Pi retains its lease and explicit extension policy; unrestricted shell remains
outside this file-tool boundary and is not an OS sandbox.
## Shared documents this change makes stale
- `docs/stage-artifacts.md` and `internal/author/skill/references/operations.md`
should explain that model-stage artifact directories are usable by the
supported file tools only within the exact same-run visit scope, not as a
general external-directory permission.
+55
View File
@@ -105,6 +105,61 @@ func TestArtifactsScanMissingDirectoryIsEmpty(t *testing.T) {
}
}
func TestArtifactAccessUsesOnlyCurrentAndEarlierVisits(t *testing.T) {
root := t.TempDir()
r := &runner{artifactsRoot: root}
for _, directory := range []string{"7/1", "7/2", "7/3", "8/1"} {
if err := os.MkdirAll(filepath.Join(root, directory), 0700); err != nil {
t.Fatal(err)
}
}
access := r.artifactAccess(7, 2, []string{"1", "3", "../8/1"}, filepath.Join(root, "7", "2"))
current, _ := filepath.EvalSymlinks(filepath.Join(root, "7", "2"))
prior, _ := filepath.EvalSymlinks(filepath.Join(root, "7", "1"))
if access.Write != current || len(access.Read) != 2 || access.Read[0] != access.Write || access.Read[1] != prior {
t.Fatalf("artifact scope = %#v", access)
}
if got := r.artifactAccess(7, 2, nil, filepath.Join(root, "8", "1")); got.Write != "" || len(got.Read) != 0 {
t.Fatalf("other-run current scope accepted: %#v", got)
}
if got := r.artifactAccess(7, 2, nil, filepath.Join(root, "7", "3")); got.Write != "" || len(got.Read) != 0 {
t.Fatalf("sibling current scope accepted: %#v", got)
}
if err := os.WriteFile(filepath.Join(root, "7", "4"), []byte("not a directory"), 0600); err != nil {
t.Fatal(err)
}
if got := r.artifactAccess(7, 4, nil, filepath.Join(root, "7", "4")); got.Write != "" || len(got.Read) != 0 {
t.Fatalf("file current scope accepted: %#v", got)
}
if err := os.Symlink(filepath.Join(root, "7", "2"), filepath.Join(root, "7", "5")); err != nil {
t.Fatal(err)
}
if got := r.artifactAccess(7, 5, nil, filepath.Join(root, "7", "5")); got.Write != "" || len(got.Read) != 0 {
t.Fatalf("symlinked current scope accepted: %#v", got)
}
}
func TestRunnerPassesDerivedArtifactAccessToAgentClient(t *testing.T) {
root := t.TempDir()
for _, directory := range []string{"7/1", "7/2"} {
if err := os.MkdirAll(filepath.Join(root, directory), 0700); err != nil {
t.Fatal(err)
}
}
r := &runner{artifactsRoot: root}
client := r.agentClient(7, 2, []string{"1", "3"}, t.TempDir(), filepath.Join(root, "7", "2"), &stage.OperationLog{}, nil, []string{"read", "edit"})
if client.ArtifactAccess.Write == "" || len(client.ArtifactAccess.Read) != 2 {
t.Fatalf("runner did not pass scoped artifact access: %#v", client.ArtifactAccess)
}
if client.ArtifactAccess.Read[1] == filepath.Join(root, "7", "3") {
t.Fatal("runner passed a future visit to the client")
}
piClient := r.piClient(7, 2, []string{"1", "3"}, "pi", t.TempDir(), filepath.Join(root, "7", "2"), nil, []string{"read", "edit"})
if piClient.ArtifactAccess.Write != client.ArtifactAccess.Write || len(piClient.ArtifactAccess.Read) != len(client.ArtifactAccess.Read) || piClient.ArtifactAccess.Read[1] != client.ArtifactAccess.Read[1] {
t.Fatalf("runner passed different artifact scope to Pi client: %#v", piClient.ArtifactAccess)
}
}
// runWithArtifact executes one real run whose stage writes a file into the
// runner-provided artifacts directory. It returns the live handler and the
// recorded step so tests can serve the artifact over the real HTTP endpoint.
+64 -3
View File
@@ -580,7 +580,8 @@ type runState struct {
capturedSeen map[string]bool
// completed counts the run's finished steps, so a delta can report the
// running total without re-reading the store.
completed int
completed int
artifactDirs []string
}
func newRunState(key string, input stage.Values) *runState {
@@ -606,10 +607,67 @@ func rebuildRunState(detail *protocol.RunDetail, decided protocol.RunStep) *runS
// Seed the UI-surface accumulator from the persisted evidence so a
// resumed run reaches the same skip decision with no extra query.
state.recordChanges(step.FileChanges, step.Artifacts)
// Only completed, recorded visits are eligible for a later stage's
// review capability. The path is reconstructed by the runner below.
if step.Status == "completed" {
state.artifactDirs = append(state.artifactDirs, filepath.Join("", strconv.Itoa(step.Sequence)))
}
}
return state
}
// artifactAccess derives exact visit directories; it never consumes a path from
// a definition or model result. An unreadable or symlinked root fails closed.
func (r *runner) artifactAccess(runID int64, sequence int, prior []string, current string) stage.ArtifactAccess {
root, err := filepath.EvalSymlinks(r.artifactsRoot)
if err != nil {
return stage.ArtifactAccess{}
}
runRoot := filepath.Join(root, strconv.FormatInt(runID, 10))
visitDirectory := func(visit int) (string, bool) {
if visit <= 0 {
return "", false
}
directory := filepath.Join(runRoot, strconv.Itoa(visit))
resolved, err := filepath.EvalSymlinks(directory)
if err != nil || resolved != directory {
return "", false
}
info, err := os.Stat(resolved)
if err != nil || !info.IsDir() {
return "", false
}
return resolved, true
}
access := stage.ArtifactAccess{}
if directory, ok := visitDirectory(sequence); ok {
resolved, err := filepath.EvalSymlinks(current)
if err != nil || resolved != directory {
return access
}
access.Write = directory
access.Read = append(access.Read, directory)
}
for _, priorSequence := range prior {
visit, err := strconv.Atoi(priorSequence)
if err != nil || visit <= 0 || visit >= sequence {
continue
}
if directory, ok := visitDirectory(visit); ok {
access.Read = append(access.Read, directory)
}
}
return access
}
func (r *runner) agentClient(runID int64, sequence int, prior []string, workspace, artifactsDir string, operations *stage.OperationLog, writePaths, tools []string) *stage.AgentClient {
return &stage.AgentClient{OpenCodeClient: stage.OpenCodeClient{Directory: workspace, Operations: operations, ArtifactsDir: artifactsDir}, WritePaths: writePaths, Tools: tools, ArtifactAccess: r.artifactAccess(runID, sequence, prior, artifactsDir)}
}
func (r *runner) piClient(runID int64, sequence int, prior []string, executable, workspace, artifactsDir string, writePaths, tools []string) *stage.PiClient {
return &stage.PiClient{Executable: executable, Directory: workspace, Tools: tools, WritePaths: writePaths, ArtifactsDir: artifactsDir, ArtifactAccess: r.artifactAccess(runID, sequence, prior, artifactsDir)}
}
// serverChangedFilesField is the reserved run-input memory field under which the
// runner publishes the server-captured changed paths. A stage selects it with
// `"server_changed_files":"input.server_changed_files"`, alongside another
@@ -977,7 +1035,7 @@ func (r *runner) runLoop(ctx context.Context, id int64, graph protocol.Graph, na
}
}
operations := &stage.OperationLog{}
client := &stage.AgentClient{OpenCodeClient: stage.OpenCodeClient{Directory: workspace, Operations: operations, ArtifactsDir: artifactsDir}, WritePaths: request.WritePaths, Tools: tools}
client := r.agentClient(id, sequence, state.artifactDirs, workspace, artifactsDir, operations, request.WritePaths, tools)
client.OnSession = func(session string, active bool) error {
c, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
@@ -1033,7 +1091,7 @@ func (r *runner) runLoop(ctx context.Context, id int64, graph protocol.Graph, na
err = fmt.Errorf("Pi is not configured on execution server")
return
}
piClient = &stage.PiClient{Executable: profile.Executable, Directory: workspace, Tools: tools, WritePaths: request.WritePaths, ArtifactsDir: artifactsDir}
piClient = r.piClient(id, sequence, state.artifactDirs, profile.Executable, workspace, artifactsDir, request.WritePaths, tools)
piClient.OnOwnership = func(session, reference string, active bool) error {
c, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
@@ -1148,6 +1206,9 @@ func (r *runner) runLoop(ctx context.Context, id int64, graph protocol.Graph, na
state.recordChanges(step.FileChanges, step.Artifacts)
if step.Status == "completed" {
state.completed++
if artifactsDir != "" {
state.artifactDirs = append(state.artifactDirs, strconv.Itoa(sequence))
}
}
// Step finished: report its outcome, routing target, diagnostic and the
// artifacts recorded for the visit, plus the run's running step count.
+10 -7
View File
@@ -14,13 +14,16 @@ import (
// before any prompt is admitted, so restart recovery can interrupt the agent.
type AgentClient struct {
OpenCodeClient
WritePaths []string
Tools []string // nil is the legacy manual approval bundle; empty denies all
OnSession func(string, bool) error
SessionID string
Transcript string
Policy ToolPolicy
WorkStarted bool
WritePaths []string
Tools []string // nil is the legacy manual approval bundle; empty denies all
// ArtifactAccess is supplied only by the runner. Write is this visit's
// directory; Read contains this and completed earlier visits in the same run.
ArtifactAccess ArtifactAccess
OnSession func(string, bool) error
SessionID string
Transcript string
Policy ToolPolicy
WorkStarted bool
}
func (c OpenCodeClient) Interrupt(ctx context.Context, id string) error {
+2 -1
View File
@@ -28,6 +28,7 @@ type PiClient struct {
// ArtifactsDir is exported to the spawned Pi process as
// PIPELINES_ARTIFACTS_DIR so its tools can write stage artifacts.
ArtifactsDir string
ArtifactAccess ArtifactAccess
Policy ToolPolicy
OnSession func(string, bool) error
OnOwnership func(string, string, bool) error
@@ -128,7 +129,7 @@ func (c *PiClient) Generate(ctx context.Context, config ModelConfig, prompt stri
if err != nil {
return "", err
}
policy := map[string]any{"directory": c.Directory, "tools": tools, "paths": c.WritePaths, "edit": c.Policy.Edit, "shell": c.Policy.Shell}
policy := map[string]any{"directory": c.Directory, "tools": tools, "paths": c.WritePaths, "edit": c.Policy.Edit, "shell": c.Policy.Shell, "artifact_write": c.ArtifactAccess.Write, "artifact_read": c.ArtifactAccess.Read}
if c.WritePaths == nil {
policy["paths"] = []string{}
}
+33 -2
View File
@@ -8,6 +8,24 @@ export function permit(policy, tool, args) {
if (policy.shell !== null && !policy.shell.includes(args.command)) return "Shell command is not permitted";
return null;
}
const artifact = (absolute, write) => {
const permitted = write ? [policy.artifact_write] : policy.artifact_read;
for (const directory of permitted) {
if (typeof directory !== "string" || !path.isAbsolute(directory)) continue;
let parent = absolute;
while (!fs.existsSync(parent)) {
const next = path.dirname(parent);
if (next === parent) break;
parent = next;
}
if (!fs.existsSync(parent)) continue;
const resolved = fs.realpathSync(parent);
const target = path.join(resolved, path.relative(parent, absolute));
const root = fs.realpathSync(directory);
if (target === root || target.startsWith(root + path.sep)) return true;
}
return false;
};
if (tool === "edit" || tool === "write") {
if (typeof args.path !== "string") return "Missing file path";
if (args.path.startsWith("~") || args.path.startsWith("@")) return "Use a literal path, not a harness path shortcut";
@@ -20,7 +38,10 @@ export function permit(policy, tool, args) {
}
const resolved = fs.realpathSync(parent);
const root = fs.realpathSync(policy.directory);
if (resolved !== root && !resolved.startsWith(root + path.sep)) return "Edit escapes run directory";
if (resolved !== root && !resolved.startsWith(root + path.sep)) {
if (!artifact(absolute, true)) return "Edit escapes run directory";
return null;
}
const relative = path.relative(path.resolve(policy.directory), absolute).split(path.sep).join("/");
const canonical = path.relative(root, path.join(resolved, path.relative(parent, absolute))).split(path.sep).join("/");
if (relative.startsWith("../") || path.isAbsolute(relative)) return "Edit escapes run directory";
@@ -31,9 +52,19 @@ export function permit(policy, tool, args) {
});
if (policy.edit !== null && (!matches(relative) || !matches(canonical))) return "Edit is outside stage patterns";
}
if (tool === "read" && typeof args.path === "string") {
if (["read", "grep", "find"].includes(tool) && typeof args.path === "string") {
const name = path.basename(args.path);
if (/^(.*\.env(?:\..*)?|pipelines\.db.*)$/.test(name)) return "Protected file cannot be read";
const absolute = path.resolve(policy.directory, args.path);
let parent = absolute;
while (!fs.existsSync(parent)) {
const next = path.dirname(parent);
if (next === parent) return "Cannot resolve read path";
parent = next;
}
const resolved = fs.realpathSync(parent);
const root = fs.realpathSync(policy.directory);
if (resolved !== root && !resolved.startsWith(root + path.sep) && !artifact(absolute, false)) return "Read escapes run directory";
}
return null;
}
+72
View File
@@ -0,0 +1,72 @@
package stage
import (
"encoding/json"
"os"
"os/exec"
"path/filepath"
"testing"
)
func TestPiPolicyArtifactScope(t *testing.T) {
if _, err := exec.LookPath("node"); err != nil {
t.Skip("node is required to exercise the Pi policy extension")
}
root := t.TempDir()
workspace := filepath.Join(root, "workspace")
current := filepath.Join(root, "artifacts [7]", "2")
prior := filepath.Join(root, "artifacts [7]", "1")
sibling := filepath.Join(root, "artifacts [7]", "3")
for _, directory := range []string{workspace, current, prior, sibling} {
if err := os.MkdirAll(directory, 0700); err != nil {
t.Fatal(err)
}
}
policy := map[string]any{
"directory": workspace,
"tools": []string{"read", "grep", "find", "edit"},
"paths": []string{},
"edit": nil,
"shell": nil,
"artifact_write": current,
"artifact_read": []string{current, prior},
}
policyJSON, err := json.Marshal(policy)
if err != nil {
t.Fatal(err)
}
policyFile := filepath.Join(root, "policy.mjs")
if err := os.WriteFile(policyFile, piPolicy, 0600); err != nil {
t.Fatal(err)
}
script := `const { permit } = await import(process.argv[1]);
const policy = JSON.parse(process.argv[2]);
const checks = JSON.parse(process.argv[3]);
console.log(JSON.stringify(checks.map(([tool, path]) => permit(policy, tool, {path}))));`
checks := [][2]string{
{"edit", filepath.Join(current, "report.md")},
{"edit", filepath.Join(prior, "report.md")},
{"read", filepath.Join(prior, "report.md")},
{"grep", filepath.Join(prior, "report.md")},
{"find", filepath.Join(current, "reports")},
{"read", filepath.Join(sibling, "report.md")},
{"grep", filepath.Join(root, "other-run", "1", "report.md")},
{"find", filepath.Join(current, "..", "3", "report.md")},
{"read", filepath.Join(prior, ".env")},
}
checksJSON, err := json.Marshal(checks)
if err != nil {
t.Fatal(err)
}
output, err := exec.Command("node", "--input-type=module", "--eval", script, "file://"+policyFile, string(policyJSON), string(checksJSON)).Output()
if err != nil {
t.Fatal(err)
}
var got []any
if err := json.Unmarshal(output, &got); err != nil {
t.Fatal(err)
}
if len(got) != len(checks) || got[0] != nil || got[1] == nil || got[2] != nil || got[3] != nil || got[4] != nil || got[5] == nil || got[6] == nil || got[7] == nil || got[8] == nil {
t.Fatalf("Pi artifact policy results = %#v", got)
}
}
+34
View File
@@ -7,6 +7,13 @@ import (
"strings"
)
// ArtifactAccess is runtime-only, server-derived access to artifact visits.
// Empty fields deliberately grant nothing outside the workspace.
type ArtifactAccess struct {
Write string
Read []string
}
// ToolNames validates model-stage permissions, not general graph semantics.
// A present empty block explicitly denies all tools.
func ToolNames(def Definition) ([]string, bool, error) {
@@ -128,12 +135,39 @@ func (c *AgentClient) permissionRules() []map[string]string {
}
}
}
// OpenCode V2 resolves an external file to its containing directory and
// checks external_directory against <directory>/*. Do not grant a parent:
// each visit is deliberately an independent capability.
readArtifacts := false
writeArtifacts := false
for _, tool := range tools {
readArtifacts = readArtifacts || tool == "read" || tool == "glob" || tool == "grep"
writeArtifacts = writeArtifacts || tool == "edit"
}
if readArtifacts {
for _, directory := range c.ArtifactAccess.Read {
if artifactDirectory(directory) {
allow("external_directory", filepath.ToSlash(filepath.Join(directory, "*")))
}
}
}
if writeArtifacts && artifactDirectory(c.ArtifactAccess.Write) {
allow("external_directory", filepath.ToSlash(filepath.Join(c.ArtifactAccess.Write, "*")))
allow("edit", filepath.ToSlash(filepath.Join(c.ArtifactAccess.Write, "*")))
}
for _, pattern := range []string{"../*", "*/../*"} {
rules = append(rules, map[string]string{"action": "external_directory", "resource": pattern, "effect": "deny"})
}
for _, pattern := range []string{"*.env", "*.env.*", "pipelines.db*"} {
rules = append(rules, map[string]string{"action": "read", "resource": pattern, "effect": "deny"})
}
return rules
}
func artifactDirectory(directory string) bool {
return directory != "" && filepath.IsAbs(directory) && filepath.Clean(directory) == directory && !strings.ContainsAny(directory, "*?\\")
}
func matchesEditPolicy(patterns []string, path string) bool {
for _, pattern := range patterns {
// OpenCode resource wildcards match across directory separators.
+35
View File
@@ -139,3 +139,38 @@ func TestDefaultEditScopeIsLanguageIndependentRunDirectory(t *testing.T) {
t.Fatal("external directories were enabled")
}
}
func TestArtifactPermissionsAreExactAndToolScoped(t *testing.T) {
current := "/artifacts/run [7]/2"
prior := "/artifacts/run [7]/1"
sibling := "/artifacts/run 7/3"
otherRun := "/artifacts/run 8/1"
client := &AgentClient{OpenCodeClient: OpenCodeClient{Directory: "/repo"}, Tools: []string{"read", "edit"}, ArtifactAccess: ArtifactAccess{Write: current, Read: []string{current, prior}}}
rules := client.permissionRules()
for _, path := range []string{current + "/report.md", prior + "/report.md"} {
if permissionEffect(rules, "external_directory", path) != "allow" {
t.Fatalf("artifact directory denied: %q", path)
}
}
if permissionEffect(rules, "edit", current+"/report.md") != "allow" || permissionEffect(rules, "edit", prior+"/report.md") != "deny" {
t.Fatal("artifact writes were not limited to the current visit")
}
for _, path := range []string{sibling + "/report.md", otherRun + "/report.md", current + "/../3/report.md", "/artifacts/run 7/20/report.md"} {
if permissionEffect(rules, "external_directory", path) != "deny" {
t.Fatalf("unapproved artifact scope allowed: %q", path)
}
}
client.Tools = []string{}
if permissionEffect(client.permissionRules(), "external_directory", current+"/report.md") != "deny" {
t.Fatal("no-tool stage gained artifact access")
}
client.Tools = []string{"read"}
rules = client.permissionRules()
if permissionEffect(rules, "external_directory", prior+"/report.md") != "allow" || permissionEffect(rules, "edit", current+"/report.md") != "deny" {
t.Fatal("read-only artifact stage gained write access")
}
client.ArtifactAccess = ArtifactAccess{}
if permissionEffect(client.permissionRules(), "external_directory", current+"/report.md") != "deny" {
t.Fatal("missing artifact scope enabled an external directory")
}
}