fix(brainfs): refuse an in-brain file swapped in behind a symlink; in-brain test targets (#157)

Review round 1 on PR #168:

- ReadRegular/ReadRegularMax Lstat the path, then open it again by path;
  os.Root follows an in-root final symlink even with O_NOFOLLOW, so a
  symlink to another brain file swapped in between was read (8k-109k
  raw/ leaks in RebuildIndex, LoadInventory, IndexDoc). The opened handle
  must now be the same file as the Lstat (os.SameFile). This covers every
  ReadRegular caller, slices 1-3 included.
- Every symlink test pointed outside the brain, which os.Root refuses on
  its own. Each now has an in-brain case too: a static in-brain link per
  reader, AssertNoLeakFrom with an in-brain target, and brainfs unit tests
  for ReadDirRegular and the in-brain swap.
- brainfstest: swap links are relative (os.Root refuses every absolute
  link, so an absolute in-brain target tested nothing), and each swapper
  has its own temp name (two swappers on one path deadlocked on each
  other's FIFO).
- IndexDoc indexes only a clean wiki/ or knowledge/ path (callers pass
  caller-supplied paths).
- Rule 9: TestLoadInventoryReturnsErrNotRegularForASymlinkedTypeDir now
  asserts the error; the backfill test says it aborts on a symlinked root.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

ingestion/internal/brainfs/brainfs.go

@@ -114,7 +114,7 @@ func (b *Brain) ReadRegular(rel string) ([]byte, error) {
 	if !fi.Mode().IsRegular() {
 		return nil, fmt.Errorf("%s: %w", rel, ErrNotRegular)
 	}
-	return b.readOpened(rel)
+	return b.readOpenedMax(rel, -1, fi)
 }
 
 // readOpened opens rel non-blocking and reads it only if the OPENED handle is
@@ -128,7 +128,7 @@ func (b *Brain) ReadRegular(rel string) ([]byte, error) {
 // cannot create one; fs.protected_hardlinks=1 and the pod's secrets are on a
 // different filesystem from the brain volume, so a local caller cannot link
 // them in. Refusing Nlink > 1 is the next step if either changes.
-func (b *Brain) readOpened(rel string) ([]byte, error) { return b.readOpenedMax(rel, -1) }
+func (b *Brain) readOpened(rel string) ([]byte, error) { return b.readOpenedMax(rel, -1, nil) }
 
 // ReadRegularMax is ReadRegular with a size limit, checked on the opened
 // handle before reading (max < 0 means no limit).
@@ -140,10 +140,14 @@ func (b *Brain) ReadRegularMax(rel string, max int64) ([]byte, error) {
 	if !fi.Mode().IsRegular() {
 		return nil, fmt.Errorf("%s: %w", rel, ErrNotRegular)
 	}
-	return b.readOpenedMax(rel, max)
+	return b.readOpenedMax(rel, max, fi)
 }
 
-func (b *Brain) readOpenedMax(rel string, max int64) ([]byte, error) {
+// readOpenedMax opens rel and reads it if the opened handle is a regular file
+// and, when lfi is set, the same file the caller Lstat-ed: os.Root follows an
+// in-root final symlink even with O_NOFOLLOW, so a symlink to another brain
+// file swapped in between the Lstat and the open is refused only here.
+func (b *Brain) readOpenedMax(rel string, max int64, lfi fs.FileInfo) ([]byte, error) {
 	f, err := b.root.OpenFile(rel, os.O_RDONLY|syscall.O_NONBLOCK, 0)
 	if err != nil {
 		return nil, err
@@ -156,6 +160,9 @@ func (b *Brain) readOpenedMax(rel string, max int64) ([]byte, error) {
 	if !hfi.Mode().IsRegular() {
 		return nil, fmt.Errorf("%s: %w", rel, ErrNotRegular)
 	}
+	if lfi != nil && !os.SameFile(lfi, hfi) {
+		return nil, fmt.Errorf("%s: changed while opening: %w", rel, ErrNotRegular)
+	}
 	if max >= 0 && hfi.Size() > max {
 		return nil, fmt.Errorf("%s is %d bytes (limit %d): %w", rel, hfi.Size(), max, ErrTooLarge)
 	}

ingestion/internal/brainfs/brainfs_test.go

@@ -6,6 +6,8 @@ import (
 	"io/fs"
 	"os"
 	"path/filepath"
+	"sync"
+	"sync/atomic"
 	"syscall"
 	"testing"
 	"time"
@@ -189,3 +191,74 @@ func TestWalkRegularReportsASymlinkedIntermediateComponentOfTheWalkRoot(t *testi
 	require.Len(t, errs, 1)
 	assert.ErrorIs(t, errs[0], ErrNotRegular)
 }
+
+func TestReadDirRegularListsOnlyRegularFilesAndRefusesSymlinkedComponents(t *testing.T) {
+	dir := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "a", "b", "sub"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "a", "b", "n.md"), []byte("n"), 0o644))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "other.md"), []byte("o"), 0o644))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "other.md"), filepath.Join(dir, "a", "b", "l.md")))
+	require.NoError(t, syscall.Mkfifo(filepath.Join(dir, "a", "b", "f.md"), 0o644))
+	require.NoError(t, os.Symlink("a", filepath.Join(dir, "alias")))
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, "x"), 0o755))
+	require.NoError(t, os.Symlink(filepath.Join("..", "a"), filepath.Join(dir, "x", "mid")))
+	b, err := Open(dir)
+	require.NoError(t, err)
+	defer func() { _ = b.Close() }()
+
+	names, err := b.ReadDirRegular("a/b")
+	require.NoError(t, err)
+	assert.Equal(t, []string{"n.md"}, names)
+	for _, rel := range []string{"alias/b", "x/mid/b"} {
+		_, err := b.ReadDirRegular(rel)
+		assert.ErrorIs(t, err, ErrNotRegular, rel)
+	}
+}
+
+// A final component swapped for a symlink to another regular file in the
+// brain between the Lstat and the open: os.Root follows in-root links, so
+// only comparing the two (os.SameFile) refuses it.
+func TestReadRegularNeverReturnsAnInBrainFileSwappedInBehindASymlink(t *testing.T) {
+	dir := t.TempDir()
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "s.md"), []byte("zqsamefilesentinel"), 0o644))
+	p := filepath.Join(dir, "r.md")
+	require.NoError(t, os.WriteFile(p, []byte("inside"), 0o644))
+	b, err := Open(dir)
+	require.NoError(t, err)
+	defer func() { _ = b.Close() }()
+
+	var stop atomic.Bool
+	var wg sync.WaitGroup
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		tmp := p + ".swap"
+		for i := 0; !stop.Load(); i++ {
+			_ = os.Remove(tmp)
+			if i%2 == 0 {
+				_ = os.WriteFile(tmp, []byte("inside"), 0o644)
+			} else {
+				_ = os.Symlink("s.md", tmp)
+			}
+			_ = os.Rename(tmp, p)
+		}
+	}()
+	leaks, ok := 0, 0
+	for deadline := time.Now().Add(1500 * time.Millisecond); time.Now().Before(deadline); {
+		got, err := b.ReadRegular("r.md")
+		if err == nil {
+			ok++
+		}
+		if string(got) == "zqsamefilesentinel" {
+			leaks++
+		}
+		got, _ = b.ReadRegularMax("r.md", 1<<20)
+		if string(got) == "zqsamefilesentinel" {
+			leaks++
+		}
+	}
+	stop.Store(true)
+	wg.Wait()
+	assert.Zero(t, leaks)
+	assert.Positive(t, ok, "positive control: the regular file is read")
+}

ingestion/internal/brainfs/brainfstest/brainfstest.go

@@ -7,6 +7,7 @@
 package brainfstest
 
 import (
+	"fmt"
 	"os"
 	"path/filepath"
 	"strings"
@@ -35,6 +36,8 @@ func Outside(t *testing.T) string {
 	return p
 }
 
+var swapSeq atomic.Int64
+
 // StartSwap renames, in a loop, a regular note (content inside) and either
 // a symlink to outside or a FIFO into path, until the test ends. FIFOs get a
 // writer held open until the swapper exits, so a reader that skips the
@@ -47,7 +50,15 @@ func StartSwap(t *testing.T, path, inside, outside string, fifo bool) {
 	wg.Add(1)
 	go func() {
 		defer wg.Done()
-		tmp := path + ".swap"
+		// A name of its own: swappers on one path share a test, and one
+		// opening another's FIFO for write would block forever.
+		tmp := fmt.Sprintf("%s.swap%d", path, swapSeq.Add(1))
+		// A relative link: os.Root refuses every absolute link on its own, so
+		// an absolute in-brain target would test nothing.
+		link := outside
+		if rel, err := filepath.Rel(filepath.Dir(path), outside); err == nil {
+			link = rel
+		}
 		var writers []*os.File
 		defer func() {
 			for _, w := range writers {
@@ -66,7 +77,7 @@ func StartSwap(t *testing.T, path, inside, outside string, fifo bool) {
 					}
 				}
 			default:
-				_ = os.Symlink(outside, tmp)
+				_ = os.Symlink(link, tmp)
 			}
 			_ = os.Rename(tmp, path)
 		}
@@ -74,11 +85,33 @@ func StartSwap(t *testing.T, path, inside, outside string, fifo bool) {
 	t.Cleanup(func() { stop.Store(true); wg.Wait() })
 }
 
+// WriteSentinelAt writes a file carrying Sentinel at p (creating its
+// directory), for an in-brain symlink target.
+func WriteSentinelAt(t *testing.T, p string) string {
+	t.Helper()
+	if err := os.MkdirAll(filepath.Dir(p), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(p, []byte(outsideContent), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	return p
+}
+
 // AssertNoLeak loops read for d while a symlink swapper runs on path, and
-// fails if any output contains Sentinel.
+// fails if any output contains Sentinel. The symlink points outside the
+// brain; os.Root refuses that on its own, so pair it with AssertNoLeakFrom
+// and an in-brain target.
 func AssertNoLeak(t *testing.T, path, inside string, d time.Duration, read func() string) {
 	t.Helper()
-	StartSwap(t, path, inside, Outside(t), false)
+	AssertNoLeakFrom(t, path, inside, Outside(t), d, read)
+}
+
+// AssertNoLeakFrom is AssertNoLeak with the symlink pointing at target, e.g.
+// a file elsewhere in the brain written with WriteSentinelAt.
+func AssertNoLeakFrom(t *testing.T, path, inside, target string, d time.Duration, read func() string) {
+	t.Helper()
+	StartSwap(t, path, inside, target, false)
 	leaks, iters := 0, 0
 	for deadline := time.Now().Add(d); time.Now().Before(deadline); iters++ {
 		leaks += strings.Count(read(), Sentinel)