[chore] document settings.toml trust model + path-containment guard (#246)

* [chore] add fileutil.ContainedJoin path-containment helper

Exported helper that joins a name onto a base directory and rejects any
name that nets outside the base via "..". Uses filepath.Clean(base) +
prefix check to avoid an uncoverable filepath.Rel error branch, keeping
coverage at 100% for the new file.

* [chore] guard copy_files and lockfile paths with ContainedJoin

CopyEntries and HashLockfile now call fileutil.ContainedJoin before
building paths, rejecting any config-supplied name that escapes the
worktree via "..". Defense-in-depth: the same config already grants
shell execution via post_create/install, so this is belt-and-suspenders
rather than a primary security boundary.

* [chore] document settings.toml trust model in README

Add a "Trust model" section explaining that post_create and
deps.modules[].install run verbatim via sh -c. Cloning an untrusted
repo and running rimba add executes that repo's shell scripts — this
was previously undocumented. Also notes the defense-in-depth path
constraint on copy_files and lockfile, and why worktree_dir is exempt.

* [chore] address review: ErrPathEscapes sentinel + validate dstPath

- Export ErrPathEscapes sentinel so callers can use errors.Is instead
  of substring matching on the error string
- Apply ContainedJoin to dstPath in CopyEntries as well; was previously
  safe via srcPath short-circuit, now explicitly guarded on both paths
- Update nolint comment and path_test.go to use errors.Is

* [chore] assert errors.Is(ErrPathEscapes) in traversal tests

hash_test.go and copy_test.go were checking the error string but not
the wrapped sentinel. Mirror the pattern from path_test.go: assert
errors.Is(err, fileutil.ErrPathEscapes) so any regression in the
wrapping chain is caught at test time, not only via string matching.

Author: lugassawan

README.md

@@ -22,6 +22,7 @@
 - [Quick Start](#quick-start)
 - [Commands](#commands)
 - [Configuration](#configuration)
+- [Trust model](#trust-model)
 - [Troubleshooting](#troubleshooting)
 - [Contributing](CONTRIBUTING.md)
 - [License](#license)
@@ -141,6 +142,17 @@ agent = 'claude'
 
 Running `rimba init --agents` or `rimba init -g` additionally creates or patches MCP server config files in client tools (`.mcp.json`, `.cursor/mcp.json`, `~/.claude/settings.json`, and others). See [docs/configuration.md#mcp-server-registration](docs/configuration.md#mcp-server-registration) for the full list of patched files and entry format.
 
+## Trust model
+
+**`.rimba/settings.toml` is trusted-author input.** The following fields execute shell commands verbatim via `sh -c`:
+
+- `post_create` — runs after a worktree is created (e.g. `rimba add`)
+- `deps.modules[].install` — runs when installing dependencies into a worktree
+
+**Cloning an untrusted repository and running `rimba add` executes that repo's `post_create` and `install` shell scripts.** Always review `.rimba/settings.toml` before running rimba in a repository you do not control.
+
+As a defense-in-depth measure, the `copy_files` entries and `deps.modules[].lockfile` paths are validated to stay within the worktree directory — paths that escape via `..` are rejected with an error. Note that `worktree_dir` is intentionally not subject to this constraint, because its default value (`../<repo>-worktrees`) is itself a `../`-relative path.
+
 ## Global flags
 
 | Flag | Description |

internal/deps/hash.go

@@ -4,7 +4,8 @@ import (
 	"crypto/sha256"
 	"fmt"
 	"os"
-	"path/filepath"
+
+	"github.com/lugassawan/rimba/internal/fileutil"
 )
 
 // ModuleWithHash pairs a Module with its lockfile hash.
@@ -16,7 +17,11 @@ type ModuleWithHash struct {
 // HashLockfile computes the SHA-256 hex digest of a lockfile.
 // Returns an empty string if the file doesn't exist.
 func HashLockfile(worktreePath, lockfile string) (string, error) {
-	data, err := os.ReadFile(filepath.Join(worktreePath, lockfile))
+	path, err := fileutil.ContainedJoin(worktreePath, lockfile)
+	if err != nil {
+		return "", err
+	}
+	data, err := os.ReadFile(path)
 	if err != nil {
 		if os.IsNotExist(err) {
 			return "", nil

internal/deps/hash_test.go

@@ -1,7 +1,11 @@
 package deps
 
 import (
+	"errors"
+	"strings"
 	"testing"
+
+	"github.com/lugassawan/rimba/internal/fileutil"
 )
 
 const testLockfile = "lock.yaml"
@@ -57,6 +61,21 @@ func TestHashLockfileDifferentContent(t *testing.T) {
 	}
 }
 
+func TestHashLockfileRejectsTraversal(t *testing.T) {
+	dir := t.TempDir()
+
+	_, err := HashLockfile(dir, "../outside")
+	if err == nil {
+		t.Fatal("HashLockfile with traversal path: expected error, got nil")
+	}
+	if !errors.Is(err, fileutil.ErrPathEscapes) {
+		t.Fatalf("error %v does not wrap fileutil.ErrPathEscapes", err)
+	}
+	if !strings.Contains(err.Error(), "contains ..") {
+		t.Fatalf("error %q does not contain %q", err.Error(), "contains ..")
+	}
+}
+
 func TestHashModules(t *testing.T) {
 	dir := t.TempDir()
 	writeFile(t, dir, LockfilePnpm, "lockfile content")

internal/fileutil/copy.go

@@ -15,8 +15,14 @@ const copyErrFmt = "copy %s: %w"
 func CopyEntries(src, dst string, entries []string) (copied []string, skippedSymlinks []string, err error) {
 	copied = make([]string, 0, len(entries))
 	for _, name := range entries {
-		srcPath := filepath.Join(src, name)
-		dstPath := filepath.Join(dst, name)
+		srcPath, err := ContainedJoin(src, name)
+		if err != nil {
+			return copied, skippedSymlinks, fmt.Errorf(copyErrFmt, name, err)
+		}
+		dstPath, err := ContainedJoin(dst, name)
+		if err != nil {
+			return copied, skippedSymlinks, fmt.Errorf(copyErrFmt, name, err)
+		}
 
 		ok, syms, copyErr := copyEntry(srcPath, dstPath, name)
 		if copyErr != nil {
@@ -125,7 +131,7 @@ func copyFile(src, dst string) (retErr error) {
 		return err
 	}
 
-	out, err := os.OpenFile(filepath.Clean(dst), os.O_WRONLY|os.O_CREATE|os.O_TRUNC, info.Mode()) //nolint:gosec // dst is derived from config copy_files, not user input
+	out, err := os.OpenFile(filepath.Clean(dst), os.O_WRONLY|os.O_CREATE|os.O_TRUNC, info.Mode()) //nolint:gosec // dst validated by ContainedJoin before copyEntry is called
 	if err != nil {
 		return err
 	}

internal/fileutil/copy_test.go

@@ -1,6 +1,7 @@
 package fileutil_test
 
 import (
+	"errors"
 	"os"
 	"path/filepath"
 	"reflect"
@@ -610,6 +611,25 @@ func TestCopyEntriesDirCopyFileError(t *testing.T) {
 	}
 }
 
+func TestCopyEntriesRejectsTraversal(t *testing.T) {
+	src := t.TempDir()
+	dst := t.TempDir()
+
+	copied, _, err := fileutil.CopyEntries(src, dst, []string{"../escape"})
+	if err == nil {
+		t.Fatalf("CopyEntries with traversal path: expected error, got nil (copied=%v)", copied)
+	}
+	if !errors.Is(err, fileutil.ErrPathEscapes) {
+		t.Fatalf("error %v does not wrap fileutil.ErrPathEscapes", err)
+	}
+	if !strings.Contains(err.Error(), "contains ..") {
+		t.Fatalf("error %q does not contain %q", err.Error(), "contains ..")
+	}
+	if len(copied) != 0 {
+		t.Errorf("copied = %v, want empty on traversal error", copied)
+	}
+}
+
 func TestCopyEntriesRecursiveCopyDirError(t *testing.T) {
 	src := t.TempDir()
 	dst := t.TempDir()

internal/fileutil/path.go

@@ -0,0 +1,23 @@
+package fileutil
+
+import (
+	"errors"
+	"fmt"
+	"path/filepath"
+	"strings"
+)
+
+// ErrPathEscapes is returned by ContainedJoin when a name escapes the base directory.
+var ErrPathEscapes = errors.New("path escapes base directory")
+
+// ContainedJoin joins name onto base and verifies the result stays within base.
+// A name that nets back inside base (e.g. "sub/../file") is allowed; one that
+// escapes via ".." is rejected. base must be a cleaned directory path.
+func ContainedJoin(base, name string) (string, error) {
+	base = filepath.Clean(base)
+	joined := filepath.Join(base, name)
+	if joined != base && !strings.HasPrefix(joined, base+string(filepath.Separator)) {
+		return "", fmt.Errorf("path %q contains ..: %w", name, ErrPathEscapes)
+	}
+	return joined, nil
+}

internal/fileutil/path_test.go

@@ -0,0 +1,54 @@
+package fileutil_test
+
+import (
+	"errors"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/lugassawan/rimba/internal/fileutil"
+)
+
+func TestContainedJoin(t *testing.T) {
+	base := t.TempDir()
+
+	tests := []struct {
+		name    string
+		input   string
+		wantErr bool
+	}{
+		{name: "simple file", input: "file.txt"},
+		{name: "nested file", input: "sub/file.txt"},
+		{name: "net-inside traversal", input: "sub/../file.txt"},
+		{name: "escape one level", input: "../x", wantErr: true},
+		{name: "escape two levels", input: "../../x", wantErr: true},
+		{name: "escape after descent", input: "a/../../x", wantErr: true},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got, err := fileutil.ContainedJoin(base, tc.input)
+			if tc.wantErr {
+				if err == nil {
+					t.Fatalf("ContainedJoin(%q, %q) = %q, nil; want error", base, tc.input, got)
+				}
+				if !errors.Is(err, fileutil.ErrPathEscapes) {
+					t.Fatalf("error %v is not ErrPathEscapes", err)
+				}
+				if !strings.Contains(err.Error(), "contains ..") {
+					t.Fatalf("error %q does not contain %q", err.Error(), "contains ..")
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("ContainedJoin(%q, %q) unexpected error: %v", base, tc.input, err)
+			}
+			if !strings.HasPrefix(got, base) {
+				t.Fatalf("result %q is not inside base %q", got, base)
+			}
+			if got != filepath.Join(base, tc.input) {
+				t.Fatalf("ContainedJoin(%q, %q) = %q; want %q", base, tc.input, got, filepath.Join(base, tc.input))
+			}
+		})
+	}
+}