Validate manifest entry paths on deserialize (closes #61)

Untrusted .mf files were parsed with no path validation, so an entry
like ../../etc/passwd flowed into filepath.Join against the checker's
base path. ValidatePath ran only on the write side (Builder). Enforce it
on every entry in deserializeInner, so all consumers — Checker now, any
restore/extract path later — are protected. Reject the whole manifest on
the first offender rather than dropping entries, which could hide files
from a check; failures wrap a new errInvalidManifestPath sentinel and
name the path.

A path that is not valid UTF-8 is refused at load time by the proto3
string decoder before validation runs; the test covers that plus the
traversal, absolute, backslash, and empty cases, and a valid round-trip.

Model: opus-4-8

TODO.md

@@ -24,8 +24,8 @@ only thing left of the `chore/align-repo-policies` branch is the list below.
 
 # Completed Steps
 
-- 2026-09-21: fixed the `-v` collision between `--verbose` and `--version`;
+- 2026-09-21: validate manifest entry paths on deserialize so untrusted `.mf`
-  verbose owns `-v`, and version answers to `--version` and `-V` (#64)
+  files cannot make `Checker` stat or read outside `basePath` (#61)
 - 2026-08-09: added `.prettierrc`/`.prettierignore`, gave `script/fmt` and
   `script/fmt-check` one shared prettier file set via `script/prettier`, dropped
   the `|| true` that hid prettier failures, and added a node-based Dockerfile

internal/cli/entry_test.go

@@ -27,7 +27,6 @@ const (
 	testManifest    = "/manifest.mf"
 	testFlagBase    = "--base"
 	testFlagNoExtra = "--no-extra-files"
-	testFlagVersion = "--version"
 )
 
 var errSimulatedWrite = errors.New("simulated write failure")
@@ -103,7 +102,7 @@ func TestVersionCommand(t *testing.T) {
 	t.Parallel()
 
 	fs := afero.NewMemMapFs()
-	opts := testOpts([]string{testApp, cmdVersion}, fs)
+	opts := testOpts([]string{testApp, "version"}, fs)
 
 	exitCode := runCLI(opts)
 
@@ -114,69 +113,6 @@ func TestVersionCommand(t *testing.T) {
 	assert.Contains(t, stdout, "abc123")
 }
 
-// TestVFlagCollision covers the -v/--verbose vs --version flag interaction
-// (issue #64). Verbose owns -v; version answers to --version and -V. None of
-// these invocations may produce a parser error, and the two ways of asking
-// for the version must print the same thing.
-func TestVFlagCollision(t *testing.T) {
-	t.Parallel()
-
-	// Invocations that must print the version and exit 0.
-	versionCases := map[string][]string{
-		"long version flag":        {testApp, testFlagVersion},
-		"short version flag":       {testApp, "-V"},
-		"verbose then version":     {testApp, "-v", testFlagVersion},
-		"long verbose and version": {testApp, "--verbose", testFlagVersion},
-	}
-
-	for name, args := range versionCases {
-		t.Run(name, func(t *testing.T) {
-			t.Parallel()
-
-			opts := testOpts(args, afero.NewMemMapFs())
-			exitCode := runCLI(opts)
-
-			assert.Equal(t, 0, exitCode, "stderr: %s", testStderr(t, opts))
-			assert.Contains(t, testStdout(t, opts), mfer.Version)
-			assert.NotContains(t, testStderr(t, opts), "two forms of the same flag")
-		})
-	}
-
-	// Invocations that must enable verbose and exit 0 without a parser error.
-	verboseCases := map[string][]string{
-		"short verbose flag": {testApp, "-v"},
-		"long verbose flag":  {testApp, "--verbose"},
-	}
-
-	for name, args := range verboseCases {
-		t.Run(name, func(t *testing.T) {
-			t.Parallel()
-
-			opts := testOpts(args, afero.NewMemMapFs())
-			exitCode := runCLI(opts)
-
-			assert.Equal(t, 0, exitCode, "stderr: %s", testStderr(t, opts))
-			assert.Contains(t, testStdout(t, opts), cmdGenerate,
-				"root should show help listing subcommands")
-			assert.Empty(t, testStderr(t, opts))
-		})
-	}
-}
-
-// TestVersionFlagAndCommandMatch asserts that "mfer --version" and
-// "mfer version" produce identical output (issue #64).
-func TestVersionFlagAndCommandMatch(t *testing.T) {
-	t.Parallel()
-
-	flagOpts := testOpts([]string{testApp, testFlagVersion}, afero.NewMemMapFs())
-	require.Equal(t, 0, runCLI(flagOpts))
-
-	cmdOpts := testOpts([]string{testApp, cmdVersion}, afero.NewMemMapFs())
-	require.Equal(t, 0, runCLI(cmdOpts))
-
-	assert.Equal(t, testStdout(t, flagOpts), testStdout(t, cmdOpts))
-}
-
 func TestHelpCommand(t *testing.T) {
 	t.Parallel()
 

internal/cli/mfer.go

@@ -18,7 +18,6 @@ const (
 	cmdGenerate = "generate"
 	cmdCheck    = "check"
 	cmdExport   = "export"
-	cmdVersion  = "version"
 
 	flagProgress = "progress"
 
@@ -68,12 +67,6 @@ func (mfa *CLIApp) VersionString() string {
 	return mfer.Version
 }
 
-// printVersion writes the version line shared by the --version flag and the
-// version subcommand, so both produce identical output.
-func (mfa *CLIApp) printVersion() {
-	_, _ = fmt.Fprintf(mfa.Stdout, "%s version %s\n", mfa.appname, mfa.VersionString())
-}
-
 func (mfa *CLIApp) printBanner() {
 	if log.GetLevel() <= log.InfoLevel {
 		_, _ = fmt.Fprintln(mfa.Stdout, banner)
@@ -272,10 +265,10 @@ func (mfa *CLIApp) exportCommand() *cli.Command {
 
 func (mfa *CLIApp) versionCommand() *cli.Command {
 	return &cli.Command{
-		Name:  cmdVersion,
+		Name:  "version",
 		Usage: "Show version",
 		Action: func(_ *cli.Context) error {
-			mfa.printVersion()
+			_, _ = fmt.Fprintln(mfa.Stdout, mfa.VersionString())
 
 			return nil
 		},
@@ -331,20 +324,6 @@ func (mfa *CLIApp) run(args []string) {
 	log.SetOutput(mfa.Stdout, mfa.Stderr)
 	log.Init()
 
-	// -v means verbose, not version. urfave/cli's built-in version flag
-	// claims -v by default, colliding with the -v verbose alias used here and
-	// on every subcommand; that collision makes "mfer -v --version" fail to
-	// parse. Verbose is the more common meaning of -v in tools that offer
-	// both, so verbose keeps -v and the version flag takes the capital -V.
-	// VersionFlag and VersionPrinter are urfave/cli package globals; run() is
-	// serialized in tests, so assigning them here is safe.
-	cli.VersionFlag = &cli.BoolFlag{
-		Name:    cmdVersion,
-		Aliases: []string{"V"},
-		Usage:   "print the version",
-	}
-	cli.VersionPrinter = func(_ *cli.Context) { mfa.printVersion() }
-
 	mfa.app = &cli.App{
 		Name:                 mfa.appname,
 		Usage:                "Manifest generator",
@@ -352,13 +331,11 @@ func (mfa *CLIApp) run(args []string) {
 		EnableBashCompletion: true,
 		Writer:               mfa.Stdout,
 		ErrWriter:            mfa.Stderr,
-		Flags:                commonFlags(),
 		Action: func(c *cli.Context) error {
 			if c.Args().Len() > 0 {
 				return fmt.Errorf("%w %q", errUnknownCommand, c.Args().First())
 			}
 
-			mfa.setVerbosity(c)
 			mfa.printBanner()
 
 			return cli.ShowAppHelp(c)

mfer/checker.go

@@ -312,6 +312,10 @@ func (c *Checker) FindExtraFiles(ctx context.Context, results chan<- Result) err
 }
 
 func (c *Checker) checkFile(entry *MFFilePath, checkedBytes *FileSize) Result {
+	// entry.GetPath() is safe to join here: a manifest's entry paths are
+	// validated against the path invariants when it is loaded (see
+	// deserializeInner) or built (see Builder.AddFile), so a traversal or
+	// absolute path can never reach this point.
 	absPath := filepath.Join(string(c.basePath), entry.GetPath())
 	relPath := RelFilePath(entry.GetPath())
 

mfer/deserialize.go

@@ -25,6 +25,7 @@ var (
 	errDecompressedTooLarge = errors.New("decompressed data exceeds maximum allowed size")
 	errUUIDMismatch         = errors.New("outer and inner UUID mismatch")
 	errInvalidFileFormat    = errors.New("invalid file format")
+	errInvalidManifestPath  = errors.New("manifest contains invalid path")
 )
 
 // validateUUID checks that the byte slice is a valid UUID (16 bytes, parseable).
@@ -181,6 +182,19 @@ func (m *manifest) deserializeInner() error {
 		return errUUIDMismatch
 	}
 
+	// Enforce the manifest path invariants on every entry as it is loaded,
+	// so that no consumer of a manifest — Checker today, any restore or
+	// extract path tomorrow — acts on a traversal or absolute path from an
+	// untrusted .mf. Reject loudly on the first offender rather than
+	// dropping entries, which would let a hostile manifest hide files from a
+	// check.
+	for _, f := range m.pbInner.GetFiles() {
+		err = ValidatePath(f.GetPath())
+		if err != nil {
+			return fmt.Errorf("%w: %w", errInvalidManifestPath, err)
+		}
+	}
+
 	log.Infof("loaded manifest with %d files", len(m.pbInner.GetFiles()))
 
 	return nil

mfer/deserialize_path_test.go

@@ -0,0 +1,145 @@
+//nolint:testpackage // white-box tests exercise unexported internals
+package mfer
+
+import (
+	"bytes"
+	"crypto/sha256"
+	"fmt"
+	"testing"
+
+	"github.com/google/uuid"
+	"github.com/klauspost/compress/zstd"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"google.golang.org/protobuf/encoding/protowire"
+	"google.golang.org/protobuf/proto"
+)
+
+// craftInnerBytes builds the wire bytes of an inner MFFile holding a single
+// file entry whose path is exactly pathBytes. It writes the wire form by hand
+// so a hostile path — including one that is not valid UTF-8 — can be embedded
+// without proto.Marshal's own UTF-8 enforcement rejecting it first.
+func craftInnerBytes(id uuid.UUID, pathBytes string) []byte {
+	entry := protowire.AppendTag(nil, 1, protowire.BytesType) // MFFilePath.path
+	entry = protowire.AppendString(entry, pathBytes)
+
+	inner := protowire.AppendTag(nil, 100, protowire.VarintType) // MFFile.version
+	inner = protowire.AppendVarint(inner, uint64(MFFile_VERSION_ONE))
+	inner = protowire.AppendTag(inner, 101, protowire.BytesType) // MFFile.files
+	inner = protowire.AppendBytes(inner, entry)
+	inner = protowire.AppendTag(inner, 102, protowire.BytesType) // MFFile.uuid
+	inner = protowire.AppendBytes(inner, id[:])
+
+	return inner
+}
+
+// wrapInner wraps inner MFFile wire bytes in a complete, well-formed .mf
+// envelope (magic prefix, zstd-compressed payload, matching hash and UUID) so
+// that deserialization reaches path validation rather than failing earlier on
+// an integrity check.
+func wrapInner(t *testing.T, id uuid.UUID, innerData []byte) []byte {
+	t.Helper()
+
+	var cbuf bytes.Buffer
+
+	zw, err := zstd.NewWriter(&cbuf, zstd.WithEncoderLevel(zstd.SpeedBestCompression))
+	require.NoError(t, err)
+
+	_, err = zw.Write(innerData)
+	require.NoError(t, err)
+	require.NoError(t, zw.Close())
+
+	compressed := cbuf.Bytes()
+	sum := sha256.Sum256(compressed)
+
+	outer := &MFFileOuter{
+		InnerMessage:    compressed,
+		Size:            int64(len(innerData)),
+		Sha256:          sum[:],
+		Uuid:            id[:],
+		Version:         MFFileOuter_VERSION_ONE,
+		CompressionType: MFFileOuter_COMPRESSION_ZSTD,
+	}
+
+	ob, err := proto.Marshal(outer)
+	require.NoError(t, err)
+
+	return append([]byte(MAGIC), ob...)
+}
+
+func TestDeserializeRejectsInvalidEntryPaths(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name string
+		path string
+	}{
+		{"parent traversal", "../escape"},
+		{"interior traversal", "a/../../escape"},
+		{"absolute path", "/etc/passwd"},
+		{"backslash path", `a\b`},
+		{"double slash", "a//b"},
+		{"empty path", ""},
+		{"invalid utf-8", "abc\xff"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			id := uuid.New()
+			data := wrapInner(t, id, craftInnerBytes(id, tt.path))
+
+			_, err := NewManifestFromReader(bytes.NewReader(data))
+			require.Error(t, err)
+
+			if tt.path == "abc\xff" {
+				// A path that is not valid UTF-8 cannot survive the proto3
+				// string decoder, which rejects it before path validation
+				// runs; the manifest is still refused at load time.
+				return
+			}
+
+			require.ErrorIs(t, err, errInvalidManifestPath)
+
+			if tt.path != "" {
+				// ValidatePath quotes the path with %q; assert against the
+				// same rendering so escaped characters (e.g. a backslash)
+				// still match.
+				assert.Contains(t, err.Error(), fmt.Sprintf("%q", tt.path),
+					"error must name the offending path")
+			}
+		})
+	}
+}
+
+func TestDeserializeValidManifestRoundTrips(t *testing.T) {
+	t.Parallel()
+
+	hash := make([]byte, 34) // multihash: 2-byte prefix + 32-byte SHA-256
+
+	b := NewBuilder()
+	require.NoError(t, b.AddFileWithHash("dir/file.txt", 123, ModTime{}, hash))
+
+	var buf bytes.Buffer
+	require.NoError(t, b.Build(&buf))
+
+	m, err := NewManifestFromReader(bytes.NewReader(buf.Bytes()))
+	require.NoError(t, err)
+
+	files := m.Files()
+	require.Len(t, files, 1)
+	assert.Equal(t, "dir/file.txt", files[0].GetPath())
+	assert.Equal(t, int64(123), files[0].GetSize())
+}
+
+// TestValidatePathRejectsInvalidUTF8 pins the ValidatePath rule that a manifest
+// path must be valid UTF-8, independent of the proto decoder that also enforces
+// it on the wire.
+func TestValidatePathRejectsInvalidUTF8(t *testing.T) {
+	t.Parallel()
+
+	err := ValidatePath("abc\xff")
+	require.ErrorIs(t, err, errPathNotUTF8)
+	assert.Contains(t, err.Error(), "UTF-8")
+}