feat(tar): add deterministic mtime for tar archives

- Add Mtime field to TarOptions struct for deterministic file timestamps
- Add WithMtime() option function to set mtime
- Update BuildTarCommand() to use --mtime flag when Mtime is set
- Add getDeterministicMtime() helper that reuses getGitCommitTimestamp()
- Update all 10 BuildTarCommand() call sites to use deterministic mtime
- Add comprehensive unit tests for tar mtime functionality

This ensures tar archives have deterministic file modification times based on
git commit timestamps, using the same timestamp source as SBOM normalization.
This improves build reproducibility by eliminating timestamp variations in
tar archive metadata.

The --mtime flag sets all file timestamps in the archive to the git commit
time, making builds more deterministic while preserving the ability to use
SOURCE_DATE_EPOCH for fully reproducible builds.

Co-authored-by: Ona <no-reply@ona.com>

Author: leodido

pkg/leeway/build.go

@@ -1518,6 +1518,12 @@ func (p *Package) buildYarn(buildctx *buildContext, wd, result string) (bld *pac
 		Commands: commands,
 	}
 
+	// Get deterministic mtime for tar archives
+	mtime, err := p.getDeterministicMtime()
+	if err != nil {
+		return nil, err
+	}
+
 	// let's prepare for packaging
 	var (
 		pkgCommands [][]string
@@ -1546,6 +1552,7 @@ func (p *Package) buildYarn(buildctx *buildContext, wd, result string) (bld *pac
 				WithOutputFile(result),
 				WithWorkingDir("_mirror"),
 				WithCompression(!buildctx.DontCompress),
+				WithMtime(mtime),
 			),
 		}...)
 		resultDir = "_mirror"
@@ -1574,13 +1581,15 @@ func (p *Package) buildYarn(buildctx *buildContext, wd, result string) (bld *pac
 				WithOutputFile(result),
 				WithWorkingDir("_pkg"),
 				WithCompression(!buildctx.DontCompress),
+				WithMtime(mtime),
 			),
 		}...)
 		resultDir = "_pkg"
 	} else if cfg.Packaging == YarnArchive {
 		pkgCommands = append(pkgCommands, BuildTarCommand(
 			WithOutputFile(result),
 			WithCompression(!buildctx.DontCompress),
+			WithMtime(mtime),
 		))
 	} else {
 		return nil, xerrors.Errorf("unknown Yarn packaging: %s", cfg.Packaging)
@@ -1760,11 +1769,18 @@ func (p *Package) buildGo(buildctx *buildContext, wd, result string) (res *packa
 		commands[PackageBuildPhaseBuild] = append(commands[PackageBuildPhaseBuild], buildCmd)
 	}
 
+	// Get deterministic mtime for tar archives
+	mtime, err := p.getDeterministicMtime()
+	if err != nil {
+		return nil, err
+	}
+
 	commands[PackageBuildPhasePackage] = append(commands[PackageBuildPhasePackage], []string{"rm", "-rf", "_deps"})
 	commands[PackageBuildPhasePackage] = append(commands[PackageBuildPhasePackage],
 		BuildTarCommand(
 			WithOutputFile(result),
 			WithCompression(!buildctx.DontCompress),
+			WithMtime(mtime),
 		),
 	)
 	if !cfg.DontTest && !buildctx.DontTest {
@@ -2059,6 +2075,12 @@ func (p *Package) buildDocker(buildctx *buildContext, wd, result string) (res *p
 			return subjects, containerDir, nil
 		}
 
+		// Get deterministic mtime for tar archives
+		mtime, err := p.getDeterministicMtime()
+		if err != nil {
+			return nil, err
+		}
+
 		// Create package with improved diagnostic logging
 		var pkgcmds [][]string
 
@@ -2078,6 +2100,7 @@ func (p *Package) buildDocker(buildctx *buildContext, wd, result string) (res *p
 			WithWorkingDir(containerDir),
 			WithSourcePaths(sourcePaths...),
 			WithCompression(!buildctx.DontCompress),
+			WithMtime(mtime),
 		))
 
 		commands[PackageBuildPhasePackage] = pkgcmds
@@ -2111,6 +2134,12 @@ func (p *Package) buildDocker(buildctx *buildContext, wd, result string) (res *p
 		encodedMetadata := base64.StdEncoding.EncodeToString(metadataContent)
 		pkgCommands = append(pkgCommands, []string{"sh", "-c", fmt.Sprintf("echo %s | base64 -d > %s", encodedMetadata, dockerMetadataFile)})
 
+		// Get deterministic mtime for tar archives
+		mtime, err := p.getDeterministicMtime()
+		if err != nil {
+			return nil, err
+		}
+
 		// Prepare for packaging
 		sourcePaths := []string{fmt.Sprintf("./%s", dockerImageNamesFiles), fmt.Sprintf("./%s", dockerMetadataFile)}
 		if p.C.W.Provenance.Enabled {
@@ -2126,6 +2155,7 @@ func (p *Package) buildDocker(buildctx *buildContext, wd, result string) (res *p
 			WithOutputFile(result),
 			WithSourcePaths(sourcePaths...),
 			WithCompression(!buildctx.DontCompress),
+			WithMtime(mtime),
 		)
 		pkgCommands = append(pkgCommands, archiveCmd)
 
@@ -2167,6 +2197,12 @@ func (p *Package) buildDocker(buildctx *buildContext, wd, result string) (res *p
 			)
 		}
 
+		// Get deterministic mtime for tar archives
+		mtime, err := p.getDeterministicMtime()
+		if err != nil {
+			return nil, err
+		}
+
 		// Package everything into final tar.gz
 		sourcePaths := []string{"./image.tar", fmt.Sprintf("./%s", dockerImageNamesFiles), "./docker-export-metadata.json"}
 		if len(cfg.Metadata) > 0 {
@@ -2187,6 +2223,7 @@ func (p *Package) buildDocker(buildctx *buildContext, wd, result string) (res *p
 			WithOutputFile(result),
 			WithSourcePaths(sourcePaths...),
 			WithCompression(!buildctx.DontCompress),
+			WithMtime(mtime),
 		)
 		pkgCommands = append(pkgCommands, archiveCmd)
 
@@ -2374,6 +2411,18 @@ func createDockerExportMetadata(wd, version string, cfg DockerPkgConfig) error {
 	return nil
 }
 
+// getDeterministicMtime returns the Unix timestamp to use for tar --mtime flag.
+// It uses the same timestamp source as SBOM normalization for consistency.
+func (p *Package) getDeterministicMtime() (int64, error) {
+	timestamp, err := getGitCommitTimestamp(p.C.Git().Commit)
+	if err != nil {
+		return 0, fmt.Errorf("failed to get deterministic timestamp for tar mtime (commit: %s): %w. "+
+			"Ensure git is available and the repository is not a shallow clone, or set SOURCE_DATE_EPOCH environment variable",
+			p.C.Git().Commit, err)
+	}
+	return timestamp.Unix(), nil
+}
+
 // Update buildGeneric to use compression arg helper
 func (p *Package) buildGeneric(buildctx *buildContext, wd, result string) (res *packageBuild, err error) {
 	cfg, ok := p.Config.(GenericPkgConfig)
@@ -2409,6 +2458,12 @@ func (p *Package) buildGeneric(buildctx *buildContext, wd, result string) (res *
 			}...)
 		}
 
+		// Get deterministic mtime for tar archives
+		mtime, err := p.getDeterministicMtime()
+		if err != nil {
+			return nil, err
+		}
+
 		// Use buildTarCommand directly which will handle compression internally
 		var tarCmd []string
 		if p.C.W.Provenance.Enabled || p.C.W.SBOM.Enabled {
@@ -2428,6 +2483,7 @@ func (p *Package) buildGeneric(buildctx *buildContext, wd, result string) (res *
 				WithOutputFile(result),
 				WithSourcePaths(sourcePaths...),
 				WithCompression(!buildctx.DontCompress),
+				WithMtime(mtime),
 			)
 			return &packageBuild{
 				Commands: map[PackageBuildPhase][][]string{
@@ -2450,6 +2506,7 @@ func (p *Package) buildGeneric(buildctx *buildContext, wd, result string) (res *
 		tarCmd = BuildTarCommand(
 			WithFilesFrom("/dev/null"),
 			WithCompression(!buildctx.DontCompress),
+			WithMtime(mtime),
 		)
 
 		return &packageBuild{
@@ -2489,13 +2546,20 @@ func (p *Package) buildGeneric(buildctx *buildContext, wd, result string) (res *
 		commands = append(commands, cfg.Test...)
 	}
 
+	// Get deterministic mtime for tar archives
+	mtime, err := p.getDeterministicMtime()
+	if err != nil {
+		return nil, err
+	}
+
 	return &packageBuild{
 		Commands: map[PackageBuildPhase][][]string{
 			PackageBuildPhaseBuild: commands,
 			PackageBuildPhasePackage: {
 				BuildTarCommand(
 					WithOutputFile(result),
 					WithCompression(!buildctx.DontCompress),
+					WithMtime(mtime),
 				),
 			},
 		},

pkg/leeway/compression.go

@@ -59,6 +59,9 @@ type TarOptions struct {
 
 	// ExcludePatterns specifies patterns to exclude
 	ExcludePatterns []string
+
+	// Mtime sets a deterministic modification time for all files in the archive (Unix timestamp)
+	Mtime int64
 }
 
 // WithOutputFile sets the output file path for the tar archive
@@ -117,6 +120,13 @@ func WithExcludePatterns(patterns ...string) func(*TarOptions) {
 	}
 }
 
+// WithMtime sets a deterministic modification time for all files in the archive
+func WithMtime(timestamp int64) func(*TarOptions) {
+	return func(opts *TarOptions) {
+		opts.Mtime = timestamp
+	}
+}
+
 // getCompressionCommand returns the appropriate compression command based on options
 func getCompressionCommand(algo CompressionAlgorithm, level int) string {
 	switch algo {
@@ -185,6 +195,11 @@ func BuildTarCommand(options ...func(*TarOptions)) []string {
 		cmd = append(cmd, "--sparse")
 	}
 
+	// Add deterministic mtime if specified
+	if opts.Mtime != 0 {
+		cmd = append(cmd, fmt.Sprintf("--mtime=@%d", opts.Mtime))
+	}
+
 	// Handle files-from case specially
 	if opts.FilesFrom != "" {
 		cmd = append(cmd, "--files-from", opts.FilesFrom)

pkg/leeway/compression_test.go

@@ -0,0 +1,165 @@
+package leeway
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestWithMtime(t *testing.T) {
+	tests := []struct {
+		name      string
+		mtime     int64
+		wantMtime int64
+	}{
+		{
+			name:      "positive timestamp",
+			mtime:     1234567890,
+			wantMtime: 1234567890,
+		},
+		{
+			name:      "zero timestamp",
+			mtime:     0,
+			wantMtime: 0,
+		},
+		{
+			name:      "recent timestamp",
+			mtime:     1700000000,
+			wantMtime: 1700000000,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			opts := &TarOptions{}
+			WithMtime(tt.mtime)(opts)
+
+			if opts.Mtime != tt.wantMtime {
+				t.Errorf("WithMtime() set Mtime = %d, want %d", opts.Mtime, tt.wantMtime)
+			}
+		})
+	}
+}
+
+func TestBuildTarCommand_WithMtime(t *testing.T) {
+	tests := []struct {
+		name          string
+		mtime         int64
+		wantMtimeFlag bool
+		wantFlag      string
+	}{
+		{
+			name:          "with mtime set",
+			mtime:         1234567890,
+			wantMtimeFlag: true,
+			wantFlag:      "--mtime=@1234567890",
+		},
+		{
+			name:          "with zero mtime (not set)",
+			mtime:         0,
+			wantMtimeFlag: false,
+			wantFlag:      "",
+		},
+		{
+			name:          "with recent mtime",
+			mtime:         1700000000,
+			wantMtimeFlag: true,
+			wantFlag:      "--mtime=@1700000000",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			var cmd []string
+			if tt.mtime != 0 {
+				cmd = BuildTarCommand(
+					WithOutputFile("test.tar.gz"),
+					WithMtime(tt.mtime),
+				)
+			} else {
+				cmd = BuildTarCommand(
+					WithOutputFile("test.tar.gz"),
+				)
+			}
+
+			// Check if --mtime flag is present
+			hasMtimeFlag := false
+			for _, arg := range cmd {
+				if strings.HasPrefix(arg, "--mtime=") {
+					hasMtimeFlag = true
+					if tt.wantMtimeFlag && arg != tt.wantFlag {
+						t.Errorf("BuildTarCommand() mtime flag = %s, want %s", arg, tt.wantFlag)
+					}
+					break
+				}
+			}
+
+			if tt.wantMtimeFlag && !hasMtimeFlag {
+				t.Errorf("BuildTarCommand() missing --mtime flag, want %s", tt.wantFlag)
+			}
+			if !tt.wantMtimeFlag && hasMtimeFlag {
+				t.Error("BuildTarCommand() has --mtime flag, want none")
+			}
+		})
+	}
+}
+
+func TestBuildTarCommand_MtimePosition(t *testing.T) {
+	// Test that --mtime flag appears before -cf flag
+	cmd := BuildTarCommand(
+		WithOutputFile("test.tar.gz"),
+		WithMtime(1234567890),
+	)
+
+	mtimeIdx := -1
+	cfIdx := -1
+
+	for i, arg := range cmd {
+		if strings.HasPrefix(arg, "--mtime=") {
+			mtimeIdx = i
+		}
+		if arg == "-cf" {
+			cfIdx = i
+		}
+	}
+
+	if mtimeIdx == -1 {
+		t.Error("BuildTarCommand() missing --mtime flag")
+	}
+	if cfIdx == -1 {
+		t.Error("BuildTarCommand() missing -cf flag")
+	}
+	if mtimeIdx >= cfIdx {
+		t.Errorf("BuildTarCommand() --mtime flag at index %d should appear before -cf at index %d", mtimeIdx, cfIdx)
+	}
+}
+
+func TestBuildTarCommand_MtimeWithOtherOptions(t *testing.T) {
+	// Test that mtime works correctly with other options
+	cmd := BuildTarCommand(
+		WithOutputFile("test.tar.gz"),
+		WithSourcePaths("file1.txt", "file2.txt"),
+		WithWorkingDir("/tmp"),
+		WithCompression(true),
+		WithMtime(1234567890),
+	)
+
+	// Verify command contains expected elements
+	cmdStr := strings.Join(cmd, " ")
+
+	expectedElements := []string{
+		"tar",
+		"--mtime=@1234567890",
+		"-cf",
+		"test.tar.gz",
+		"-C",
+		"/tmp",
+		"file1.txt",
+		"file2.txt",
+	}
+
+	for _, elem := range expectedElements {
+		if !strings.Contains(cmdStr, elem) {
+			t.Errorf("BuildTarCommand() missing expected element: %s\nFull command: %s", elem, cmdStr)
+		}
+	}
+}