AddFileWithHash rejects hashes that are not multihashes (closes #129)

AddFileWithHash took any non-empty bytes as a hash, so the builder could
write a manifest that mfer refuses to load. It now decodes the hash with
go-multihash and also requires a digest of at least 32 bytes, the SHA-256
length the reader's decoding-cost limit assumes: a valid but shorter
multihash, such as an empty identity hash or SHA-1, still makes a
manifest of one-character paths too costly to load. When mfer freshen
meets such a hash in an existing manifest, its error names the manifest
entry and says to regenerate the manifest with mfer generate. Test
fixtures whose stand-in hashes were not valid multihashes now use a
SHA-256 multihash.

Model: opus-5-5

.gitignore

@@ -8,7 +8,7 @@ vendor.tzst
 modcache.tzst
 
 # Generated manifest files
-.index.mf
+/index.mf
 
 # Secrets
 .env

README.md

@@ -36,12 +36,12 @@ Generate a manifest for a directory tree, verify it later, and fetch a published
 tree by URL:
 
 ```sh
-# Write .index.mf, a manifest of the files under the current directory.
+# Write index.mf, a manifest of the files under the current directory.
 bin/mfer gen .
 
 # Verify the files on disk against the manifest. Exits nonzero if any file
 # is missing or corrupted.
-bin/mfer check .index.mf
+bin/mfer check index.mf
 
 # Download and cryptographically verify a tree published over HTTP: mfer
 # fetches <url>/index.mf, then downloads every file it lists.

internal/cli/check.go

@@ -75,25 +75,22 @@ func safeRateUint64(rate float64) uint64 {
 	return uint64(rate)
 }
 
-// findManifest looks for a manifest file in the given directory.
-// It checks for index.mf and .index.mf, returning the first one found.
+// findManifest returns the path of the manifest with the default name in
+// dir, or an error if there is none.
 func findManifest(fs afero.Fs, dir string) (string, error) {
-	candidates := []string{"index.mf", ".index.mf"}
-	for _, name := range candidates {
-		path := filepath.Join(dir, name)
+	path := filepath.Join(dir, defaultManifestName)
 
-		exists, err := afero.Exists(fs, path)
-		if err != nil {
-			return "", err
-		}
-
-		if exists {
-			return path, nil
-		}
+	exists, err := afero.Exists(fs, path)
+	if err != nil {
+		return "", err
 	}
 
-	return "", fmt.Errorf(
-		"%w in %s (looked for index.mf and .index.mf)", errNoManifestFound, dir)
+	if !exists {
+		return "", fmt.Errorf("%w in %s (looked for %s)",
+			errNoManifestFound, dir, defaultManifestName)
+	}
+
+	return path, nil
 }
 
 // fetchManifestToTemp downloads a manifest URL to a temporary file and

internal/cli/entry_test.go

@@ -8,6 +8,7 @@ import (
 	"io"
 	"math/rand"
 	"os"
+	"path/filepath"
 	"slices"
 	"strings"
 	"sync"
@@ -27,7 +28,6 @@ const (
 	testFile1       = "/testdir/file1.txt"
 	testMF          = "/testdir/test.mf"
 	testOutput      = "/output.mf"
-	testOutputTmp   = "/output.mf.tmp"
 	testManifest    = "/manifest.mf"
 	testFlagBase    = "--base"
 	testFlagNoExtra = "--no-extra-files"
@@ -682,7 +682,7 @@ func TestGenerateAtomicWriteNoTempFileOnSuccess(t *testing.T) {
 	assert.True(t, exists, "output file should exist")
 
 	// Verify temp file does NOT exist
-	tmpExists, err := afero.Exists(fs, testOutputTmp)
+	tmpExists, err := afero.Exists(fs, manifestTempPath(testOutput))
 	require.NoError(t, err)
 	assert.False(t, tmpExists,
 		"temp file should not exist after successful generation")
@@ -714,7 +714,7 @@ func TestGenerateAtomicWriteOverwriteWithForce(t *testing.T) {
 		"manifest should be overwritten")
 
 	// Verify temp file does NOT exist
-	tmpExists, err := afero.Exists(fs, testOutputTmp)
+	tmpExists, err := afero.Exists(fs, manifestTempPath(testOutput))
 	require.NoError(t, err)
 	assert.False(t, tmpExists,
 		"temp file should not exist after successful generation")
@@ -743,6 +743,102 @@ func TestGenerateFailsWithoutForceWhenOutputExists(t *testing.T) {
 	assert.Equal(t, "existing", string(content), "original file should be preserved")
 }
 
+// manifestPaths returns the file paths listed by the manifest at path.
+func manifestPaths(t *testing.T, fs afero.Fs, path string) []string {
+	t.Helper()
+
+	manifest, err := mfer.NewManifestFromFile(&mfer.ManifestFromFileOptions{
+		Path: path,
+		Fs:   fs,
+	})
+	require.NoError(t, err)
+
+	paths := make([]string, 0, len(manifest.Files()))
+	for _, f := range manifest.Files() {
+		paths = append(paths, f.GetPath())
+	}
+
+	return paths
+}
+
+// TestGenerateLeavesOutputOutOfListing overwrites an output file inside the
+// scanned tree with --force: the old file is not listed, even when the tree
+// is named through a symlink, while a file named index.mf in a subdirectory
+// still is. The output file is recognized by file identity, which needs
+// the real filesystem.
+func TestGenerateLeavesOutputOutOfListing(t *testing.T) {
+	t.Parallel()
+
+	// Paths are relative to a temp dir holding data/tree and link, a
+	// symlink to data.
+	for name, tc := range map[string]struct{ input, output string }{
+		"default name":                 {"data/tree", "data/tree/index.mf"},
+		"other name in a subdirectory": {"data/tree", "data/tree/sub/listing.mf"},
+		"tree named through a symlink": {"link/tree", "data/tree/index.mf"},
+	} {
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+
+			root := t.TempDir()
+			tree := filepath.Join(root, "data", "tree")
+			output := filepath.Join(root, tc.output)
+
+			fs := afero.NewOsFs()
+			require.NoError(t, fs.MkdirAll(filepath.Join(tree, "sub"), 0o750))
+			require.NoError(t,
+				os.Symlink(filepath.Join(root, "data"), filepath.Join(root, "link")))
+			writeTestFile(t, fs, filepath.Join(tree, testFileTxt), "hello")
+			writeTestFile(t, fs, filepath.Join(tree, "sub", "index.mf"), "an ordinary file")
+			writeTestFile(t, fs, output, "previous manifest")
+
+			opts := testOpts([]string{
+				testApp, cmdGenerate, "-q", "--force", "-o", output, filepath.Join(root, tc.input),
+			}, fs)
+			require.Equal(t, 0, runCLI(opts), "stderr: %s", testStderr(t, opts))
+
+			assert.ElementsMatch(t, []string{testFileTxt, "sub/index.mf"},
+				manifestPaths(t, fs, output))
+		})
+	}
+}
+
+// TestGenerateDefaultOutputLeftOutOfListing runs gen with --force and no
+// other arguments, so it scans the current directory and writes the
+// relative path index.mf: the index.mf already there is not listed.
+//
+//nolint:paralleltest // changes the process-global working directory
+func TestGenerateDefaultOutputLeftOutOfListing(t *testing.T) {
+	chdirTemp(t)
+
+	fs := afero.NewOsFs()
+	writeTestFile(t, fs, testFileTxt, "hello")
+	writeTestFile(t, fs, "index.mf", "previous manifest")
+
+	opts := testOpts([]string{testApp, cmdGenerate, "-q", "--force"}, fs)
+	require.Equal(t, 0, runCLI(opts), "stderr: %s", testStderr(t, opts))
+
+	assert.Equal(t, []string{testFileTxt}, manifestPaths(t, fs, "index.mf"))
+}
+
+// TestGenerateLeavesLeftoverTempFileOutOfListing runs gen where an
+// interrupted run left its temp file beside the output: the leftover is
+// not listed, and gen does not fail when it overwrites it.
+func TestGenerateLeavesLeftoverTempFileOutOfListing(t *testing.T) {
+	t.Parallel()
+
+	root := t.TempDir()
+	output := filepath.Join(root, "index.mf")
+
+	fs := afero.NewOsFs()
+	writeTestFile(t, fs, filepath.Join(root, testFileTxt), "hello")
+	writeTestFile(t, fs, manifestTempPath(output), "part of a manifest")
+
+	opts := testOpts([]string{testApp, cmdGenerate, "-q", "-o", output, root}, fs)
+	require.Equal(t, 0, runCLI(opts), "stderr: %s", testStderr(t, opts))
+
+	assert.Equal(t, []string{testFileTxt}, manifestPaths(t, fs, output))
+}
+
 func TestGenerateAtomicWriteUsesTemp(t *testing.T) {
 	t.Parallel()
 
@@ -765,7 +861,7 @@ func TestGenerateAtomicWriteUsesTemp(t *testing.T) {
 	exists, _ := afero.Exists(fs, testOutput)
 	assert.True(t, exists, "output file should exist")
 
-	tmpExists, _ := afero.Exists(fs, testOutputTmp)
+	tmpExists, _ := afero.Exists(fs, manifestTempPath(testOutput))
 	assert.False(t, tmpExists, "temp file should be cleaned up")
 
 	// Verify manifest is valid (not empty)
@@ -831,7 +927,7 @@ func TestGenerateAtomicWriteCleansUpOnError(t *testing.T) {
 		"output file should not exist after failed generation (atomic write)")
 
 	// Temp file should also not exist
-	tmpExists, _ := afero.Exists(baseFs, testOutputTmp)
+	tmpExists, _ := afero.Exists(baseFs, manifestTempPath(testOutput))
 	assert.False(t, tmpExists,
 		"temp file should be cleaned up after failed generation")
 }

internal/cli/errmsg_test.go

@@ -78,7 +78,7 @@ func TestNoManifestFoundMessage(t *testing.T) {
 	_, err := findManifest(afero.NewMemMapFs(), "/tmp/x")
 	require.ErrorIs(t, err, errNoManifestFound)
 	assert.EqualError(t, err,
-		"no manifest found in /tmp/x (looked for index.mf and .index.mf)")
+		"no manifest found in /tmp/x (looked for index.mf)")
 }
 
 func TestVerifyRequiredSignerMessages(t *testing.T) {

internal/cli/fetch.go

@@ -313,7 +313,7 @@ func checkNoSymlinks(p string) error {
 
 // resolveManifestURL takes a URL and returns the manifest URL.
 // If the URL already ends with .mf, it's returned as-is.
-// Otherwise, index.mf is appended.
+// Otherwise, the default manifest name is appended.
 func resolveManifestURL(inputURL string) (string, error) {
 	parsed, err := url.Parse(inputURL)
 	if err != nil {
@@ -330,8 +330,7 @@ func resolveManifestURL(inputURL string) (string, error) {
 		parsed.Path += "/"
 	}
 
-	// Append index.mf
-	parsed.Path += "index.mf"
+	parsed.Path += defaultManifestName
 
 	return parsed.String(), nil
 }

internal/cli/freshen.go

@@ -7,6 +7,7 @@ import (
 	"fmt"
 	"io"
 	"io/fs"
+	"os"
 	"path/filepath"
 	"time"
 
@@ -56,7 +57,7 @@ type freshenEntry struct {
 type freshenScanner struct {
 	fs              afero.Fs
 	absBase         string
-	manifestBase    string
+	excluded        []fs.FileInfo // files left out of the listing
 	includeDotfiles bool
 	followSymlinks  bool
 	showProgress    bool
@@ -156,11 +157,6 @@ func (s *freshenScanner) walk(path string, info fs.FileInfo, walkErr error) erro
 			"freshen: failed to compute relative path for %s: %w", path, err)
 	}
 
-	// Skip the manifest file itself
-	if relPath == s.manifestBase || relPath == "."+s.manifestBase {
-		return nil
-	}
-
 	// Handle dotfiles
 	if !s.includeDotfiles && mfer.IsHiddenPath(filepath.ToSlash(relPath)) {
 		if info.IsDir() {
@@ -185,6 +181,12 @@ func (s *freshenScanner) walk(path string, info fs.FileInfo, walkErr error) erro
 		info = realInfo
 	}
 
+	for _, excluded := range s.excluded {
+		if os.SameFile(info, excluded) {
+			return nil
+		}
+	}
+
 	s.scanCount++
 
 	// Check against existing manifest
@@ -307,7 +309,7 @@ func (h *freshenHasher) processEntry(e *freshenEntry) error {
 func writeFreshenedManifest(
 	ctx context.Context, afs afero.Fs, builder *mfer.Builder, manifestPath string,
 ) error {
-	tmpPath := manifestPath + ".tmp"
+	tmpPath := manifestTempPath(manifestPath)
 
 	outFile, err := afs.Create(tmpPath)
 	if err != nil {
@@ -364,10 +366,22 @@ func (mfa *CLIApp) freshenScan(
 	startScan := time.Now()
 	showProgress := ctx.Bool("progress")
 
+	// Leave out the manifest and a temp file left by an interrupted run,
+	// as gen does. A path that cannot be stat'd, normally because no file
+	// is there, needs no leaving out.
+	var excluded []fs.FileInfo
+
+	for _, p := range []string{manifestPath, manifestTempPath(manifestPath)} {
+		info, err := mfa.Fs.Stat(p)
+		if err == nil {
+			excluded = append(excluded, info)
+		}
+	}
+
 	scanner := &freshenScanner{
 		fs:              mfa.Fs,
 		absBase:         absBase,
-		manifestBase:    filepath.Base(manifestPath),
+		excluded:        excluded,
 		includeDotfiles: ctx.Bool("include-dotfiles"),
 		followSymlinks:  ctx.Bool("follow-symlinks"),
 		showProgress:    showProgress,
@@ -615,7 +629,15 @@ func addExistingToBuilder(b *mfer.Builder, entry *mfer.MFFilePath) error {
 		return nil
 	}
 
-	return b.AddFileWithHash(mfer.RelFilePath(entry.GetPath()),
+	err := b.AddFileWithHash(mfer.RelFilePath(entry.GetPath()),
 		mfer.FileSize(entry.GetSize()), mfer.ModTime(mtime),
 		entry.GetHashes()[0].GetMultiHash())
+	if err != nil {
+		return fmt.Errorf(
+			"manifest entry %s: %w (regenerate the manifest with mfer generate)",
+			entry.GetPath(), err,
+		)
+	}
+
+	return nil
 }

internal/cli/freshen_test.go

@@ -4,10 +4,13 @@ package cli
 import (
 	"bytes"
 	"context"
+	"crypto/sha256"
 	"os"
+	"path/filepath"
 	"testing"
 	"time"
 
+	"github.com/multiformats/go-multihash"
 	"github.com/spf13/afero"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
@@ -29,7 +32,7 @@ func (s stubFileInfo) IsDir() bool        { return false }
 func (s stubFileInfo) Sys() any           { return nil }
 
 // setupFreshenDir populates /testdir with two files, scans it, and
-// writes the resulting manifest to /testdir/.index.mf.
+// writes the resulting manifest to /testdir/index.mf.
 func setupFreshenDir(t *testing.T, fs afero.Fs) {
 	t.Helper()
 
@@ -48,7 +51,7 @@ func setupFreshenDir(t *testing.T, fs afero.Fs) {
 
 	// Write manifest to filesystem
 	require.NoError(t,
-		afero.WriteFile(fs, "/testdir/.index.mf", manifestBuf.Bytes(), 0o644))
+		afero.WriteFile(fs, "/testdir/index.mf", manifestBuf.Bytes(), 0o644))
 }
 
 func TestFreshenUnchanged(t *testing.T) {
@@ -59,7 +62,7 @@ func TestFreshenUnchanged(t *testing.T) {
 
 	// Parse manifest to verify
 	manifest, err := mfer.NewManifestFromFile(&mfer.ManifestFromFileOptions{
-		Path: "/testdir/.index.mf",
+		Path: "/testdir/index.mf",
 		Fs:   fs,
 	})
 	require.NoError(t, err)
@@ -74,7 +77,7 @@ func TestFreshenWithChanges(t *testing.T) {
 
 	// Verify initial manifest has 2 files
 	manifest, err := mfer.NewManifestFromFile(&mfer.ManifestFromFileOptions{
-		Path: "/testdir/.index.mf",
+		Path: "/testdir/index.mf",
 		Fs:   fs,
 	})
 	require.NoError(t, err)
@@ -101,6 +104,64 @@ func TestFreshenWithChanges(t *testing.T) {
 	assert.Equal(t, "modified content2", string(content))
 }
 
+// TestFreshenLeavesManifestOutOfListing freshens a manifest kept in a
+// subdirectory of the tree it lists: the manifest is not listed, while an
+// ordinary file of the same name at the top of the tree is. The manifest
+// is recognized by file identity, which needs the real filesystem.
+func TestFreshenLeavesManifestOutOfListing(t *testing.T) {
+	t.Parallel()
+
+	root := t.TempDir()
+	manifestPath := filepath.Join(root, "sub", "listing.mf")
+
+	fs := afero.NewOsFs()
+	require.NoError(t, fs.MkdirAll(filepath.Join(root, "sub"), 0o750))
+	writeTestFile(t, fs, filepath.Join(root, testFileTxt), "hello")
+	writeTestFile(t, fs, filepath.Join(root, "listing.mf"), "an ordinary file")
+
+	opts := testOpts([]string{testApp, cmdGenerate, "-q", "-o", manifestPath, root}, fs)
+	require.Equal(t, 0, runCLI(opts), "stderr: %s", testStderr(t, opts))
+
+	// A new file gives freshen something to write.
+	writeTestFile(t, fs, filepath.Join(root, "added.txt"), "added")
+
+	opts = testOpts([]string{
+		testApp, "freshen", "-q", testFlagBase, root, manifestPath,
+	}, fs)
+	require.Equal(t, 0, runCLI(opts), "stderr: %s", testStderr(t, opts))
+
+	assert.ElementsMatch(t, []string{testFileTxt, "listing.mf", "added.txt"},
+		manifestPaths(t, fs, manifestPath))
+}
+
+// TestFreshenLeavesLeftoverTempFileOutOfListing freshens a manifest where
+// an interrupted run left its temp file beside it: the leftover is not
+// listed.
+func TestFreshenLeavesLeftoverTempFileOutOfListing(t *testing.T) {
+	t.Parallel()
+
+	root := t.TempDir()
+	manifestPath := filepath.Join(root, "index.mf")
+
+	fs := afero.NewOsFs()
+	writeTestFile(t, fs, filepath.Join(root, testFileTxt), "hello")
+
+	opts := testOpts([]string{testApp, cmdGenerate, "-q", "-o", manifestPath, root}, fs)
+	require.Equal(t, 0, runCLI(opts), "stderr: %s", testStderr(t, opts))
+
+	writeTestFile(t, fs, manifestTempPath(manifestPath), "part of a manifest")
+	// A new file gives freshen something to write.
+	writeTestFile(t, fs, filepath.Join(root, "added.txt"), "added")
+
+	opts = testOpts([]string{
+		testApp, "freshen", "-q", testFlagBase, root, manifestPath,
+	}, fs)
+	require.Equal(t, 0, runCLI(opts), "stderr: %s", testStderr(t, opts))
+
+	assert.ElementsMatch(t, []string{testFileTxt, "added.txt"},
+		manifestPaths(t, fs, manifestPath))
+}
+
 // TestFreshenRecordEntryMtimePresence pins the behavior of recordEntry
 // with respect to MFFilePath.Mtime, which is a message pointer with
 // proto3 field presence and may legitimately be absent.
@@ -175,21 +236,50 @@ func TestFreshenRecordEntryMtimePresence(t *testing.T) {
 func TestFreshenAddExistingRejectsMissingMtime(t *testing.T) {
 	t.Parallel()
 
+	hash, err := multihash.Encode(make([]byte, sha256.Size), multihash.SHA2_256)
+	require.NoError(t, err)
+
 	b := mfer.NewBuilder()
 	entry := &mfer.MFFilePath{
 		Path:  "file1.txt",
 		Size:  8,
 		Mtime: nil,
 		Hashes: []*mfer.MFFileChecksum{
-			{MultiHash: []byte{0x12, 0x20}},
+			{MultiHash: hash},
 		},
 	}
 
-	err := addExistingToBuilder(b, entry)
+	err = addExistingToBuilder(b, entry)
 	require.ErrorIs(t, err, errEntryMissingMtime)
 	assert.Contains(t, err.Error(), "file1.txt")
 }
 
+// TestFreshenAddExistingRejectsShortHash pins that an existing manifest
+// entry whose hash the builder refuses is reported as a problem with the
+// manifest, with the command that fixes it.
+func TestFreshenAddExistingRejectsShortHash(t *testing.T) {
+	t.Parallel()
+
+	sha1Hash, err := multihash.Encode(make([]byte, 20), multihash.SHA1)
+	require.NoError(t, err)
+
+	b := mfer.NewBuilder()
+	entry := &mfer.MFFilePath{
+		Path:  "old.txt",
+		Size:  8,
+		Mtime: &mfer.Timestamp{Seconds: 1_700_000_000},
+		Hashes: []*mfer.MFFileChecksum{
+			{MultiHash: sha1Hash},
+		},
+	}
+
+	err = addExistingToBuilder(b, entry)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "manifest entry old.txt")
+	assert.Contains(t, err.Error(), "mfer generate")
+	assert.Zero(t, b.FileCount())
+}
+
 // TestEntryMtime pins the presence semantics the callers depend on.
 func TestEntryMtime(t *testing.T) {
 	t.Parallel()

internal/cli/gen.go

@@ -89,11 +89,15 @@ func (mfa *CLIApp) collectInputPaths(args cli.Args) ([]string, error) {
 
 // buildScannerOptions constructs scanner options from the CLI flags.
 func (mfa *CLIApp) buildScannerOptions(ctx *cli.Context) *mfer.ScannerOptions {
+	output := ctx.String("output")
 	opts := &mfer.ScannerOptions{
 		IncludeDotfiles:   ctx.Bool("include-dotfiles"),
 		FollowSymLinks:    ctx.Bool("follow-symlinks"),
 		IncludeTimestamps: ctx.Bool("include-timestamps"),
 		Fs:                mfa.Fs,
+		// Neither a manifest being replaced nor a temp file left by an
+		// interrupted run belongs in the new manifest.
+		ExcludePaths: []string{output, manifestTempPath(output)},
 	}
 
 	// Set seed for deterministic UUID if provided
@@ -217,7 +221,7 @@ func (mfa *CLIApp) generateManifestOperation(ctx *cli.Context) error {
 	}
 
 	// Create temp file for atomic write
-	tmpPath := outputPath + ".tmp"
+	tmpPath := manifestTempPath(outputPath)
 
 	outFile, err := mfa.Fs.Create(tmpPath)
 	if err != nil {

internal/cli/manifest_loader.go

@@ -65,7 +65,7 @@ func (mfa *CLIApp) openManifestReader(pathOrURL string) (io.ReadCloser, error) {
 }
 
 // resolveManifestArg resolves the manifest path from CLI arguments.
-// HTTP(S) URLs are returned as-is. Directories are searched for index.mf/.index.mf.
+// HTTP(S) URLs are returned as-is. Directories are searched for index.mf.
 // If no argument is given, the current directory is searched.
 func (mfa *CLIApp) resolveManifestArg(ctx *cli.Context) (string, error) {
 	if ctx.Args().Len() > 0 {

internal/cli/mfer.go

@@ -25,8 +25,19 @@ const (
 	flagProgress = "progress"
 
 	manifestArgsUsage = "[manifest file]"
+
+	// defaultManifestName is the filename gen writes by default, the one
+	// looked for when a command is given a directory, and the one fetch
+	// appends to a directory URL.
+	defaultManifestName = "index.mf"
 )
 
+// manifestTempPath returns the temp file gen and freshen write a manifest
+// to before renaming it to out.
+func manifestTempPath(out string) string {
+	return out + ".tmp"
+}
+
 // errUnknownCommand indicates an unrecognized command argument.
 var errUnknownCommand = errors.New("unknown command")
 
@@ -156,7 +167,7 @@ func (mfa *CLIApp) generateCommand() *cli.Command {
 			},
 			&cli.StringFlag{
 				Name:    "output",
-				Value:   "./.index.mf",
+				Value:   defaultManifestName,
 				Aliases: []string{"o"},
 				Usage:   "Specify output filename",
 			},

mfer/builder.go

@@ -35,7 +35,8 @@ var (
 	errPathDotDot       = errors.New("contains '..' segment")
 	errSizeMismatch     = errors.New("size mismatch")
 	errNegativeSize     = errors.New("size cannot be negative")
-	errEmptyHash        = errors.New("hash cannot be nil or empty")
+	errHashNotMultihash = errors.New("hash is not a valid multihash")
+	errHashTooShort     = errors.New("hash digest is too short")
 )
 
 // ValidatePath checks that a file path conforms to manifest path invariants:
@@ -228,7 +229,8 @@ func (b *Builder) FileCount() int {
 
 // AddFileWithHash adds a file entry with a pre-computed hash.
 // This is useful when the hash is already known (e.g., from an existing manifest).
-// Returns an error if path is empty, size is negative, or hash is nil/empty.
+// Returns an error if path is invalid, size is negative, or hash is not a
+// multihash with a digest of at least 32 bytes, as long as SHA-256's.
 func (b *Builder) AddFileWithHash(
 	path RelFilePath,
 	size FileSize,
@@ -244,8 +246,19 @@ func (b *Builder) AddFileWithHash(
 		return errNegativeSize
 	}
 
-	if len(hash) == 0 {
-		return errEmptyHash
+	decoded, err := multihash.Decode(hash)
+	if err != nil {
+		return fmt.Errorf("%w: %w", errHashNotMultihash, err)
+	}
+
+	// The reader's limit on decoding cost (maxDecodedGrowth) assumes every
+	// hash is at least as long as a SHA-256 multihash, so a manifest of
+	// shorter ones could fail to load.
+	if len(decoded.Digest) < sha256.Size {
+		return fmt.Errorf(
+			"%w: %d bytes, at least %d needed",
+			errHashTooShort, len(decoded.Digest), sha256.Size,
+		)
 	}
 
 	entry := &MFFilePath{

mfer/builder_test.go

@@ -4,12 +4,14 @@ package mfer
 import (
 	"bytes"
 	"context"
+	"crypto/sha256"
 	"fmt"
 	"path/filepath"
 	"strings"
 	"testing"
 	"time"
 
+	"github.com/multiformats/go-multihash"
 	"github.com/spf13/afero"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
@@ -44,9 +46,10 @@ func TestBuilderAddFileWithHash(t *testing.T) {
 	t.Parallel()
 
 	b := NewBuilder()
-	hash := make([]byte, 34) // SHA256 multihash is 34 bytes
+	hash, err := multihash.Encode(make([]byte, sha256.Size), multihash.SHA2_256)
+	require.NoError(t, err)
 
-	err := b.AddFileWithHash("test.txt", 100, ModTime(time.Now()), hash)
+	err = b.AddFileWithHash("test.txt", 100, ModTime(time.Now()), hash)
 	require.NoError(t, err)
 	assert.Equal(t, 1, b.FileCount())
 }
@@ -54,12 +57,14 @@ func TestBuilderAddFileWithHash(t *testing.T) {
 func TestBuilderAddFileWithHashValidation(t *testing.T) {
 	t.Parallel()
 
+	sha256Hash, err := multihash.Encode(make([]byte, sha256.Size), multihash.SHA2_256)
+	require.NoError(t, err)
+
 	t.Run("empty path", func(t *testing.T) {
 		t.Parallel()
 
 		b := NewBuilder()
-		hash := make([]byte, 34)
-		err := b.AddFileWithHash("", 100, ModTime(time.Now()), hash)
+		err := b.AddFileWithHash("", 100, ModTime(time.Now()), sha256Hash)
 		require.Error(t, err)
 		assert.Contains(t, err.Error(), "path")
 	})
@@ -68,41 +73,58 @@ func TestBuilderAddFileWithHashValidation(t *testing.T) {
 		t.Parallel()
 
 		b := NewBuilder()
-		hash := make([]byte, 34)
-		err := b.AddFileWithHash("test.txt", -1, ModTime(time.Now()), hash)
+		err := b.AddFileWithHash("test.txt", -1, ModTime(time.Now()), sha256Hash)
 		require.Error(t, err)
 		assert.Contains(t, err.Error(), "size")
 	})
 
-	t.Run("nil hash", func(t *testing.T) {
-		t.Parallel()
-
-		b := NewBuilder()
-		err := b.AddFileWithHash("test.txt", 100, ModTime(time.Now()), nil)
-		require.Error(t, err)
-		assert.Contains(t, err.Error(), "hash")
-	})
-
-	t.Run("empty hash", func(t *testing.T) {
-		t.Parallel()
-
-		b := NewBuilder()
-		err := b.AddFileWithHash("test.txt", 100, ModTime(time.Now()), []byte{})
-		require.Error(t, err)
-		assert.Contains(t, err.Error(), "hash")
-	})
-
 	t.Run("valid inputs", func(t *testing.T) {
 		t.Parallel()
 
 		b := NewBuilder()
-		hash := make([]byte, 34)
-		err := b.AddFileWithHash("test.txt", 100, ModTime(time.Now()), hash)
+		err := b.AddFileWithHash("test.txt", 100, ModTime(time.Now()), sha256Hash)
 		require.NoError(t, err)
 		assert.Equal(t, 1, b.FileCount())
 	})
 }
 
+func TestBuilderAddFileWithHashRejectsBadHashes(t *testing.T) {
+	t.Parallel()
+
+	sha1Hash, err := multihash.Encode(make([]byte, 20), multihash.SHA1)
+	require.NoError(t, err)
+
+	truncatedHash, err := multihash.Encode(make([]byte, sha256.Size-1), multihash.SHA2_256)
+	require.NoError(t, err)
+
+	tests := []struct {
+		name string
+		hash Multihash
+		want error
+	}{
+		{"nil hash", nil, errHashNotMultihash},
+		{"empty hash", []byte{}, errHashNotMultihash},
+		{"one-byte hash", []byte{0x12}, errHashNotMultihash},
+		// A SHA-256 code and 32-byte length, then only two bytes of digest.
+		{"malformed multihash", []byte{0x12, 0x20, 0x01, 0x02}, errHashNotMultihash},
+		// A valid multihash, but its 20-byte SHA-1 digest is too short.
+		{"SHA-1 multihash", sha1Hash, errHashTooShort},
+		// A valid multihash whose 31-byte digest is one byte short.
+		{"31-byte digest", truncatedHash, errHashTooShort},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			b := NewBuilder()
+			err := b.AddFileWithHash("test.txt", 100, ModTime(time.Now()), tt.hash)
+			require.ErrorIs(t, err, tt.want)
+			assert.Equal(t, 0, b.FileCount())
+		})
+	}
+}
+
 func TestBuilderBuild(t *testing.T) {
 	t.Parallel()
 
@@ -358,7 +380,8 @@ func TestBuilderBuildRoundTrip(t *testing.T) {
 func TestBuilderBuildRoundTripLargeManifest(t *testing.T) {
 	t.Parallel()
 
-	hash := make([]byte, 34) // multihash: 2-byte prefix + 32-byte SHA-256
+	hash, err := multihash.Encode(make([]byte, sha256.Size), multihash.SHA2_256)
+	require.NoError(t, err)
 
 	b := NewBuilder()
 

mfer/checker_test.go

@@ -21,6 +21,8 @@ const (
 	testExistsFile   = "exists.txt"
 	testManifestPath = "/manifest.mf"
 	testDataDir      = "/data"
+	// testDataManifestPath is a manifest kept inside the checked tree.
+	testDataManifestPath = testDataDir + "/index.mf"
 )
 
 func TestStatusString(t *testing.T) {
@@ -464,7 +466,7 @@ func TestFindExtraFilesSkipsManifestAndDotfiles(t *testing.T) {
 	manifestFiles := map[string][]byte{
 		testFile1: []byte("in manifest"),
 	}
-	createTestManifest(t, fs, "/data/.index.mf", manifestFiles)
+	createTestManifest(t, fs, testDataManifestPath, manifestFiles)
 	createFilesOnDisk(t, fs, map[string][]byte{
 		testFile1: []byte("in manifest"),
 	})
@@ -476,7 +478,7 @@ func TestFindExtraFilesSkipsManifestAndDotfiles(t *testing.T) {
 	require.NoError(t, afero.WriteFile(fs, "/data/extra.txt", []byte("extra"), 0o644))
 
 	chk, err := NewChecker(&CheckerOptions{
-		ManifestPath: "/data/.index.mf",
+		ManifestPath: testDataManifestPath,
 		BasePath:     testDataDir,
 		Fs:           fs,
 	})
@@ -491,7 +493,7 @@ func TestFindExtraFilesSkipsManifestAndDotfiles(t *testing.T) {
 		extras = append(extras, r)
 	}
 
-	// Should only report extra.txt, not .hidden, .config/settings, or .index.mf
+	// Should only report extra.txt, not .hidden, .config/settings, or index.mf
 	for _, e := range extras {
 		t.Logf("extra: %s", e.Path)
 	}
@@ -656,7 +658,7 @@ func TestFindExtraFilesSkipsDotfiles(t *testing.T) {
 	files := map[string][]byte{
 		testFile1: []byte("in manifest"),
 	}
-	createTestManifest(t, fs, "/data/.index.mf", files)
+	createTestManifest(t, fs, testDataManifestPath, files)
 	createFilesOnDisk(t, fs, files)
 
 	// Add dotfiles and manifest file on disk
@@ -666,7 +668,7 @@ func TestFindExtraFilesSkipsDotfiles(t *testing.T) {
 		afero.WriteFile(fs, "/data/.git/config", []byte("git config"), 0o644))
 
 	chk, err := NewChecker(&CheckerOptions{
-		ManifestPath: "/data/.index.mf",
+		ManifestPath: testDataManifestPath,
 		BasePath:     testDataDir,
 		Fs:           fs,
 	})
@@ -695,11 +697,11 @@ func TestFindExtraFilesSkipsManifestFile(t *testing.T) {
 	files := map[string][]byte{
 		testFile1: []byte("content"),
 	}
-	createTestManifest(t, fs, "/data/index.mf", files)
+	createTestManifest(t, fs, testDataManifestPath, files)
 	createFilesOnDisk(t, fs, files)
 
 	chk, err := NewChecker(&CheckerOptions{
-		ManifestPath: "/data/index.mf",
+		ManifestPath: testDataManifestPath,
 		BasePath:     testDataDir,
 		Fs:           fs,
 	})

mfer/constants.go

@@ -36,7 +36,8 @@ const (
 	decodedMIMETypeSize  = 16
 
 	// Each file entry mfer writes holds a path of at least one byte, a
-	// 34-byte SHA-256 multihash and a modification time: at least 47 bytes,
+	// multihash at least as long as SHA-256's 34 bytes (AddFileWithHash
+	// refuses shorter ones) and a modification time: at least 47 bytes,
 	// counted at 336. So its manifests add up to at most about 7.15 times
 	// their size, and this limit is about 12% above that.
 	maxDecodedGrowth = 8

mfer/deserialize_path_test.go

@@ -13,6 +13,7 @@ import (
 
 	"github.com/google/uuid"
 	"github.com/klauspost/compress/zstd"
+	"github.com/multiformats/go-multihash"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 	"google.golang.org/protobuf/encoding/protowire"
@@ -205,7 +206,8 @@ func TestDeserializeDropsUnknownFields(t *testing.T) {
 func TestDeserializeLoadsDensestManifest(t *testing.T) {
 	t.Parallel()
 
-	hash := make([]byte, 34) // multihash: 2-byte prefix + 32-byte SHA-256
+	hash, err := multihash.Encode(make([]byte, sha256.Size), multihash.SHA2_256)
+	require.NoError(t, err)
 
 	b := NewBuilder()
 	b.SetIncludeTimestamps(true)
@@ -227,7 +229,8 @@ func TestDeserializeLoadsDensestManifest(t *testing.T) {
 func TestDeserializeValidManifestRoundTrips(t *testing.T) {
 	t.Parallel()
 
-	hash := make([]byte, 34) // multihash: 2-byte prefix + 32-byte SHA-256
+	hash, err := multihash.Encode(make([]byte, sha256.Size), multihash.SHA2_256)
+	require.NoError(t, err)
 
 	b := NewBuilder()
 	require.NoError(t, b.AddFileWithHash("dir/file.txt", 123, ModTime{}, hash))

mfer/scanner.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"io"
 	"io/fs"
+	"os"
 	"path"
 	"path/filepath"
 	"strings"
@@ -57,6 +58,8 @@ type ScannerOptions struct {
 	SigningOptions *SigningOptions
 	// Seed, if set, derives a deterministic UUID from this seed.
 	Seed string
+	// ExcludePaths lists files to leave out of the listing, matched with os.SameFile.
+	ExcludePaths []string
 }
 
 // FileEntry represents a file that has been enumerated.
@@ -75,6 +78,7 @@ type Scanner struct {
 	totalBytes FileSize // cached sum of all file sizes
 	options    *ScannerOptions
 	fs         afero.Fs
+	excluded   []fs.FileInfo // the files named in ExcludePaths that exist
 }
 
 // NewScanner creates a new Scanner with default options.
@@ -93,11 +97,22 @@ func NewScannerWithOptions(opts *ScannerOptions) *Scanner {
 		fs = afero.NewOsFs()
 	}
 
-	return &Scanner{
+	s := &Scanner{
 		files:   make([]*FileEntry, 0),
 		options: opts,
 		fs:      fs,
 	}
+
+	// A path that cannot be stat'd, normally because no file is there,
+	// needs no leaving out.
+	for _, p := range opts.ExcludePaths {
+		info, err := s.fs.Stat(p)
+		if err == nil {
+			s.excluded = append(s.excluded, info)
+		}
+	}
+
+	return s
 }
 
 // EnumerateFile adds a single file to the scanner, calling stat() to get metadata.
@@ -435,6 +450,12 @@ func (s *Scanner) enumerateFileWithInfo(
 		info = realInfo
 	}
 
+	for _, excluded := range s.excluded {
+		if os.SameFile(info, excluded) {
+			return nil
+		}
+	}
+
 	entry := &FileEntry{
 		Path:    RelFilePath(cleanPath),
 		AbsPath: AbsFilePath(absPath),