From 31aec05f99e71ac59e60e3727863c25538620282 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Sun, 18 Oct 2026 12:02:37 +0100 Subject: [PATCH] Scope stage artifact access by run visit Derive validated same-run visit artifact capabilities in the runner and pass them to OpenCode and Pi clients. Permit supported file tools to read completed prior visits and write only the current visit, preserving workspace, secret, database, and shell restrictions.\n\nChecked packaged templates and authoring skill references: neither needs updating in this item; docs/notes/scoped-artifact-access.md records the shared documentation staleness for the docs-fold writer. --- docs/notes/scoped-artifact-access.md | 20 ++++++++ internal/server/artifacts_test.go | 55 +++++++++++++++++++++ internal/server/runner.go | 67 ++++++++++++++++++++++++-- internal/stage/agent.go | 17 ++++--- internal/stage/pi.go | 3 +- internal/stage/pi_policy.mjs | 35 +++++++++++++- internal/stage/pi_policy_test.go | 72 ++++++++++++++++++++++++++++ internal/stage/tools.go | 34 +++++++++++++ internal/stage/tools_test.go | 35 ++++++++++++++ 9 files changed, 325 insertions(+), 13 deletions(-) create mode 100644 docs/notes/scoped-artifact-access.md create mode 100644 internal/stage/pi_policy_test.go diff --git a/docs/notes/scoped-artifact-access.md b/docs/notes/scoped-artifact-access.md new file mode 100644 index 00000000..75943280 --- /dev/null +++ b/docs/notes/scoped-artifact-access.md @@ -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. diff --git a/internal/server/artifacts_test.go b/internal/server/artifacts_test.go index 573b851b..6c4c7804 100644 --- a/internal/server/artifacts_test.go +++ b/internal/server/artifacts_test.go @@ -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. diff --git a/internal/server/runner.go b/internal/server/runner.go index 0c532247..11471617 100644 --- a/internal/server/runner.go +++ b/internal/server/runner.go @@ -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. diff --git a/internal/stage/agent.go b/internal/stage/agent.go index e0c3974d..d3109d20 100644 --- a/internal/stage/agent.go +++ b/internal/stage/agent.go @@ -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 { diff --git a/internal/stage/pi.go b/internal/stage/pi.go index 6d93e4d7..3e0b1bf1 100644 --- a/internal/stage/pi.go +++ b/internal/stage/pi.go @@ -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{} } diff --git a/internal/stage/pi_policy.mjs b/internal/stage/pi_policy.mjs index aec60e93..03be3440 100644 --- a/internal/stage/pi_policy.mjs +++ b/internal/stage/pi_policy.mjs @@ -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; } diff --git a/internal/stage/pi_policy_test.go b/internal/stage/pi_policy_test.go new file mode 100644 index 00000000..6b1018a6 --- /dev/null +++ b/internal/stage/pi_policy_test.go @@ -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) + } +} diff --git a/internal/stage/tools.go b/internal/stage/tools.go index 566519cb..77477987 100644 --- a/internal/stage/tools.go +++ b/internal/stage/tools.go @@ -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 /*. 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. diff --git a/internal/stage/tools_test.go b/internal/stage/tools_test.go index fa561166..ed823bc1 100644 --- a/internal/stage/tools_test.go +++ b/internal/stage/tools_test.go @@ -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") + } +}