From 725c020b6ed1c85117ec56fa8f53755afe3b2760 Mon Sep 17 00:00:00 2001
From: Nan Liu <liunan@microsoft.com>
Date: Wed, 15 Jul 2026 19:04:04 +0000
Subject: [PATCH] feat(sources): add opt-in %fedora_upstream_* provenance
 macros

Add a build.emit-upstream-provenance flag that, for Fedora upstream components, injects %fedora_upstream_version and %fedora_upstream_release macros into the component's generated macros file. Values are read from the pristine upstream Fedora spec on disk (before overlays) and the Release tag's %{?dist} is expanded to the resolved Fedora dist tag. Nothing is stored in the lock file; the macros are derived fresh at render/build time from the pinned upstream commit. Opt-in so only components that reference the macros (e.g. grub2 SBAT) get a macros file. User-defined macros of the same name win.
---
 docs/user/reference/config/components.md      |  35 ++++
 internal/app/azldev/cmds/component/build.go   |   3 +
 .../app/azldev/cmds/component/diffsources.go  |   3 +-
 .../cmds/component/history_customizations.go  |   7 +
 .../cmds/component/history_internal_test.go   |  23 ++-
 .../azldev/cmds/component/preparesources.go   |   3 +
 internal/app/azldev/cmds/component/render.go  |   1 +
 .../app/azldev/core/sources/sourceprep.go     |  44 ++++-
 .../core/sources/upstream_provenance.go       | 165 ++++++++++++++++
 .../upstream_provenance_internal_test.go      | 183 ++++++++++++++++++
 internal/projectconfig/build.go               |  22 +++
 internal/projectconfig/build_test.go          |  41 ++++
 ...ainer_config_generate-schema_stdout_1.snap |   5 +
 ...shots_config_generate-schema_stdout_1.snap |   5 +
 schemas/azldev.schema.json                    |   5 +
 15 files changed, 531 insertions(+), 14 deletions(-)
 create mode 100644 internal/app/azldev/core/sources/upstream_provenance.go
 create mode 100644 internal/app/azldev/core/sources/upstream_provenance_internal_test.go

diff --git a/docs/user/reference/config/components.md b/docs/user/reference/config/components.md
index 678669512..04f81f212 100644
--- a/docs/user/reference/config/components.md
+++ b/docs/user/reference/config/components.md
@@ -159,6 +159,7 @@ The `[components.<name>.build]` section controls build-time options for a compon
 | Without options | `without` | string array | No | Build conditionals to disable (`--without <option>` passed to rpmbuild) |
 | Macro definitions | `defines` | map of string to string | No | RPM macro definitions (`--define '<name> <value>'` passed to rpmbuild) |
 | Undefined macros | `undefines` | string array | No | RPM macro names to undefine (`--undefine '<name>'` passed to rpmbuild) |
+| Emit upstream provenance | `emit-upstream-provenance` | boolean | No | Inject `%fedora_upstream_version`/`%fedora_upstream_release` macros for Fedora upstream components (defaults to `false`) |
 | Check config | `check` | [CheckConfig](#check-configuration) | No | Configuration for the `%check` section of the spec |
 | Failure config | `failure` | [FailureConfig](#failure-configuration) | No | Configuration and policy regarding build failures |
 | Build hints | `hints` | [BuildHints](#build-hints) | No | Non-essential hints for how or when to build the component |
@@ -197,6 +198,40 @@ The `undefines` field removes macros that would otherwise be defined:
 undefines = ["fedora"]
 ```
 
+### Upstream Provenance Macros
+
+For components sourced from a Fedora upstream (`spec.type = "upstream"` with a Fedora `upstream-distro`), azldev can inject two macros into the component's build so the spec can record where it was derived from (useful for SBAT and similar provenance metadata). This is **opt-in** — enable it with `emit-upstream-provenance`:
+
+```toml
+[components.grub2.build]
+emit-upstream-provenance = true
+```
+
+| Macro | Description |
+|-------|-------------|
+| `%fedora_upstream_version` | The `Version` tag from the pristine upstream Fedora spec |
+| `%fedora_upstream_release` | The `Release` tag from the pristine upstream Fedora spec, with `%{?dist}` expanded to the Fedora dist tag (e.g. `.fc43`) |
+
+The values are read from the upstream spec **before** any azldev overlays are applied, so they reflect the true upstream Name-Version-Release, not the Azure Linux–modified spec. The macros are derived fresh at render/build time from the pinned upstream commit and emitted into the component's generated macros file (loaded via `%{load:...}`).
+
+Example: for a component pinned to Fedora 43's `grub2-2.12-5.fc43`, the spec can reference:
+
+```spec
+%sbat_generate_metadata ... derived from grub2 %{fedora_upstream_version}-%{fedora_upstream_release}
+```
+
+which expands to `grub2 2.12-5.fc43`.
+
+Notes:
+
+- The flag has no effect on local or SRPM components (they have no upstream provenance) or on non-Fedora upstreams; for those it is silently ignored.
+- If a component defines a macro of the same name via `build.defines`, the user-defined value wins — the injected value does not overwrite it.
+
+Limitations:
+
+- Tag values are read as plain text, not evaluated by rpm. Only `%{?dist}` is expanded. A literal tag like `Version: 2.12` is captured as-is, but a tag built from other macros like `Version: %{majorver}.%{minorver}` is captured with those macros unexpanded.
+- Listing `fedora_upstream_version` or `fedora_upstream_release` in `build.undefines` does **not** suppress the injected macros — they are layered on after `undefines` is applied. To disable them, set `emit-upstream-provenance = false` (or omit it) instead.
+
 ### Check Configuration
 
 The `check` field controls the `%check` section of the spec (the package's test suite).
diff --git a/internal/app/azldev/cmds/component/build.go b/internal/app/azldev/cmds/component/build.go
index 63824f204..bbf34788c 100644
--- a/internal/app/azldev/cmds/component/build.go
+++ b/internal/app/azldev/cmds/component/build.go
@@ -259,6 +259,9 @@ func BuildComponent(
 		)
 	}
 
+	preparerOpts = append(preparerOpts,
+		sources.WithUpstreamProvenance(sources.FedoraDistTag(distro.Ref.Name, distro.Version.ReleaseVer)))
+
 	sourcePreparer, err := sources.NewPreparer(sourceManager, env.FS(), env, env, preparerOpts...)
 	if err != nil {
 		return ComponentBuildResults{},
diff --git a/internal/app/azldev/cmds/component/diffsources.go b/internal/app/azldev/cmds/component/diffsources.go
index 4444f8bf6..8047bd9fe 100644
--- a/internal/app/azldev/cmds/component/diffsources.go
+++ b/internal/app/azldev/cmds/component/diffsources.go
@@ -97,7 +97,8 @@ func DiffComponentSources(env *azldev.Env, options *DiffSourcesOptions) (interfa
 		return nil, fmt.Errorf("failed to create source manager:\n%w", err)
 	}
 
-	preparer, err := sources.NewPreparer(sourceManager, env.FS(), env, env)
+	preparer, err := sources.NewPreparer(sourceManager, env.FS(), env, env,
+		sources.WithUpstreamProvenance(sources.FedoraDistTag(distro.Ref.Name, distro.Version.ReleaseVer)))
 	if err != nil {
 		return nil, fmt.Errorf("failed to create source preparer:\n%w", err)
 	}
diff --git a/internal/app/azldev/cmds/component/history_customizations.go b/internal/app/azldev/cmds/component/history_customizations.go
index 1e7f5be7e..dca357b60 100644
--- a/internal/app/azldev/cmds/component/history_customizations.go
+++ b/internal/app/azldev/cmds/component/history_customizations.go
@@ -116,6 +116,13 @@ func appendBuildItems(
 		items = append(items, CustomizationItem{Kind: "build.undefines", Value: macro})
 	}
 
+	if build.EmitUpstreamProvenance {
+		items = append(items, CustomizationItem{
+			Kind:  "build.emit-upstream-provenance",
+			Value: strconv.FormatBool(true),
+		})
+	}
+
 	if build.Check.Skip {
 		items = append(items, CustomizationItem{
 			Kind:        "build.check.skip",
diff --git a/internal/app/azldev/cmds/component/history_internal_test.go b/internal/app/azldev/cmds/component/history_internal_test.go
index 5a7a9e507..9e6a339e7 100644
--- a/internal/app/azldev/cmds/component/history_internal_test.go
+++ b/internal/app/azldev/cmds/component/history_internal_test.go
@@ -104,11 +104,12 @@ func TestCustomizationCollectorsCoverEveryFingerprintableField(t *testing.T) {
 		"ComponentConfig.Packages":    "appendPackageItems (opaque unit per package override)",
 
 		// ComponentBuildConfig.
-		"ComponentBuildConfig.With":      "build.with",
-		"ComponentBuildConfig.Without":   "build.without",
-		"ComponentBuildConfig.Defines":   "build.defines",
-		"ComponentBuildConfig.Undefines": "build.undefines",
-		"ComponentBuildConfig.Check":     "delegates to CheckConfig walk",
+		"ComponentBuildConfig.With":                   "build.with",
+		"ComponentBuildConfig.Without":                "build.without",
+		"ComponentBuildConfig.Defines":                "build.defines",
+		"ComponentBuildConfig.Undefines":              "build.undefines",
+		"ComponentBuildConfig.EmitUpstreamProvenance": "build.emit-upstream-provenance",
+		"ComponentBuildConfig.Check":                  "delegates to CheckConfig walk",
 
 		// CheckConfig.
 		"CheckConfig.Skip": "build.check.skip",
@@ -197,11 +198,12 @@ func TestCollectCustomizationsEmitsEveryKind(t *testing.T) {
 			{Type: projectconfig.ComponentOverlayAddSpecTag, Tag: "Release", Value: "1"},
 		},
 		Build: projectconfig.ComponentBuildConfig{
-			With:      []string{"feature"},
-			Without:   []string{"docs"},
-			Defines:   map[string]string{"macro": "value"},
-			Undefines: []string{"othermacro"},
-			Check:     projectconfig.CheckConfig{Skip: true, SkipReason: "flaky"},
+			With:                   []string{"feature"},
+			Without:                []string{"docs"},
+			Defines:                map[string]string{"macro": "value"},
+			Undefines:              []string{"othermacro"},
+			Check:                  projectconfig.CheckConfig{Skip: true, SkipReason: "flaky"},
+			EmitUpstreamProvenance: true,
 		},
 		Spec: projectconfig.SpecSource{
 			SourceType:     projectconfig.SpecSourceTypeUpstream,
@@ -228,6 +230,7 @@ func TestCollectCustomizationsEmitsEveryKind(t *testing.T) {
 		"build.defines",
 		"build.undefines",
 		"build.check.skip",
+		"build.emit-upstream-provenance",
 		"spec.source-type",
 		"spec.upstream-commit",
 		"spec.upstream-name",
diff --git a/internal/app/azldev/cmds/component/preparesources.go b/internal/app/azldev/cmds/component/preparesources.go
index f50c5be2a..ac48bdcac 100644
--- a/internal/app/azldev/cmds/component/preparesources.go
+++ b/internal/app/azldev/cmds/component/preparesources.go
@@ -161,6 +161,9 @@ func buildPreparerOptions(
 		)
 	}
 
+	opts = append(opts,
+		sources.WithUpstreamProvenance(sources.FedoraDistTag(distro.Ref.Name, distro.Version.ReleaseVer)))
+
 	if options.AllowNoHashes {
 		opts = append(opts, sources.WithAllowNoHashes())
 	}
diff --git a/internal/app/azldev/cmds/component/render.go b/internal/app/azldev/cmds/component/render.go
index 2f2cc54f2..de11f6e49 100644
--- a/internal/app/azldev/cmds/component/render.go
+++ b/internal/app/azldev/cmds/component/render.go
@@ -527,6 +527,7 @@ func prepareComponentSources(
 		sources.WithGitRepo(env, env.LockReader(), distro.Version.ReleaseVer),
 		sources.WithDirtyDetection(),
 		sources.WithSkipLookaside(),
+		sources.WithUpstreamProvenance(sources.FedoraDistTag(distro.Ref.Name, distro.Version.ReleaseVer)),
 	}
 
 	preparer, err := sources.NewPreparer(sourceManager, env.FS(), env, env, preparerOpts...)
diff --git a/internal/app/azldev/core/sources/sourceprep.go b/internal/app/azldev/core/sources/sourceprep.go
index c391ae611..0fd7b4484 100644
--- a/internal/app/azldev/core/sources/sourceprep.go
+++ b/internal/app/azldev/core/sources/sourceprep.go
@@ -111,6 +111,17 @@ func WithSkipLookaside() PreparerOption {
 	}
 }
 
+// WithUpstreamProvenance returns a [PreparerOption] that enables emission of
+// the %fedora_upstream_version and %fedora_upstream_release macros for Fedora
+// upstream components. distTag is the resolved %{?dist} expansion (e.g.
+// ".fc43", as produced by [FedoraDistTag]) used to expand the pristine Release
+// tag. Pass "" (e.g. for non-Fedora upstreams) to disable the macros.
+func WithUpstreamProvenance(distTag string) PreparerOption {
+	return func(p *sourcePreparerImpl) {
+		p.upstreamDistTag = distTag
+	}
+}
+
 // WithAllowNoHashes returns a [PreparerOption] that allows source file
 // references to omit their [projectconfig.SourceFileReference.Hash] value.
 // When set, any source file that lacks a hash will have its hash computed
@@ -163,6 +174,12 @@ type sourcePreparerImpl struct {
 	// releaseVer is the per-component resolved distro release version, not the
 	// project default. Set via [WithGitRepo].
 	releaseVer string
+
+	// upstreamDistTag is the resolved %{?dist} expansion (e.g. ".fc43") used to
+	// expand a Fedora upstream component's pristine Release tag when emitting
+	// the %fedora_upstream_* macros. Empty disables provenance macros. Set via
+	// [WithUpstreamProvenance].
+	upstreamDistTag string
 }
 
 // NewPreparer creates a new [SourcePreparer] instance. All positional arguments
@@ -908,7 +925,13 @@ func (p *sourcePreparerImpl) resolveSourceHash(
 // If the build configuration produces no macros, no file is written and an empty path is
 // returned. Otherwise, the path to the written macros file is returned.
 func (p *sourcePreparerImpl) writeMacrosFile(component components.Component, outputDir string) (string, error) {
-	contents := GenerateMacrosFileContents(component.GetConfig().Build)
+	macros := buildMacrosMap(component.GetConfig().Build)
+
+	// Layer Fedora upstream provenance macros on top, reading the pristine
+	// upstream spec that is already on disk (before overlays are applied).
+	p.addUpstreamProvenanceMacros(macros, component, outputDir)
+
+	contents := renderMacrosFile(macros)
 	if contents == "" {
 		return "", nil
 	}
@@ -948,8 +971,15 @@ func (p *sourcePreparerImpl) writeMacrosFile(component components.Component, out
 // If no macros remain after processing (empty config, or all macros removed via
 // undefines), an empty string is returned to signal that no macros file is needed.
 func GenerateMacrosFileContents(buildConfig projectconfig.ComponentBuildConfig) string {
-	// Build a unified map of all macros. Later definitions override earlier ones.
-	// Processing order: with flags -> without flags -> explicit defines.
+	return renderMacrosFile(buildMacrosMap(buildConfig))
+}
+
+// buildMacrosMap converts a build configuration's with/without/defines/undefines
+// into a unified macro name->value map. Later definitions override earlier ones;
+// processing order is: with flags -> without flags -> explicit defines ->
+// undefines. Upstream provenance macros are layered on separately by
+// [sourcePreparerImpl.addUpstreamProvenanceMacros].
+func buildMacrosMap(buildConfig projectconfig.ComponentBuildConfig) map[string]string {
 	macros := make(map[string]string)
 
 	// Convert 'with' flags to macros: FLAG -> _with_FLAG = 1
@@ -973,6 +1003,14 @@ func GenerateMacrosFileContents(buildConfig projectconfig.ComponentBuildConfig)
 		delete(macros, undef)
 	}
 
+	return macros
+}
+
+// renderMacrosFile serializes a fully-resolved macro map to RPM macros-file
+// format (%name value), sorted alphabetically for deterministic output and
+// prefixed with the standard auto-generated header. Returns "" when the map is
+// empty, signaling that no macros file is needed.
+func renderMacrosFile(macros map[string]string) string {
 	if len(macros) == 0 {
 		return ""
 	}
diff --git a/internal/app/azldev/core/sources/upstream_provenance.go b/internal/app/azldev/core/sources/upstream_provenance.go
new file mode 100644
index 000000000..9a1254c0f
--- /dev/null
+++ b/internal/app/azldev/core/sources/upstream_provenance.go
@@ -0,0 +1,165 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+package sources
+
+import (
+	"bytes"
+	"fmt"
+	"log/slog"
+	"strings"
+
+	"github.com/microsoft/azure-linux-dev-tools/internal/app/azldev/core/components"
+	"github.com/microsoft/azure-linux-dev-tools/internal/global/opctx"
+	"github.com/microsoft/azure-linux-dev-tools/internal/projectconfig"
+	"github.com/microsoft/azure-linux-dev-tools/internal/rpm/spec"
+	"github.com/microsoft/azure-linux-dev-tools/internal/utils/fileutils"
+)
+
+// Macro names emitted to carry upstream Fedora provenance into a component's
+// build. Specs may reference these (e.g. for SBAT) via %fedora_upstream_version
+// and %fedora_upstream_release.
+const (
+	fedoraUpstreamVersionMacro = "fedora_upstream_version"
+	fedoraUpstreamReleaseMacro = "fedora_upstream_release"
+)
+
+// distPlaceholder is the RPM %{?dist} token substituted with the resolved
+// Fedora dist tag when expanding a pristine upstream Release value.
+const distPlaceholder = "%{?dist}"
+
+// FedoraDistTag returns the RPM %{?dist} expansion for a Fedora distro
+// (".fc<releasever>", e.g. ".fc43"), or "" when the distro is not Fedora or the
+// release version is not a plain integer. Fedora dist tags are always ".fc<N>";
+// a non-numeric release version (e.g. "rawhide") has no well-defined dist tag,
+// so provenance is disabled rather than emitting an invalid value like
+// ".fcrawhide". Callers pass the result to [WithUpstreamProvenance].
+func FedoraDistTag(distroName, releaseVer string) string {
+	if !strings.EqualFold(distroName, "fedora") || !isNumericReleaseVer(releaseVer) {
+		return ""
+	}
+
+	return ".fc" + releaseVer
+}
+
+// isNumericReleaseVer reports whether s is a non-empty string of ASCII digits,
+// i.e. a Fedora numbered release like "43".
+func isNumericReleaseVer(s string) bool {
+	if s == "" {
+		return false
+	}
+
+	for _, r := range s {
+		if r < '0' || r > '9' {
+			return false
+		}
+	}
+
+	return true
+}
+
+// addUpstreamProvenanceMacros injects %fedora_upstream_version and
+// %fedora_upstream_release into macros for Fedora upstream components. The
+// values are read from the pristine upstream spec on disk (before overlays are
+// applied) and the Release tag's %{?dist} token is expanded to the resolved
+// Fedora dist tag.
+//
+// Best-effort: if the component is not a Fedora upstream, or the spec cannot be
+// located or parsed, no macros are added. User-defined macros take precedence —
+// an existing entry is never overwritten.
+func (p *sourcePreparerImpl) addUpstreamProvenanceMacros(
+	macros map[string]string, component components.Component, sourcesDir string,
+) {
+	// Only Fedora upstream components carry upstream provenance. Local and
+	// SRPM components have no upstream spec; their own identity is already
+	// available at build time via %{version}/%{release}.
+	if p.upstreamDistTag == "" {
+		return
+	}
+
+	config := component.GetConfig()
+
+	// Opt-in: the macros are only useful to specs that reference them, so they
+	// are emitted only for components that explicitly request them.
+	if !config.Build.EmitUpstreamProvenance {
+		return
+	}
+
+	if config.Spec.SourceType != projectconfig.SpecSourceTypeUpstream {
+		return
+	}
+
+	specPath, err := findSpecInDir(p.fs, component, sourcesDir)
+	if err != nil {
+		// The user opted in via emit-upstream-provenance, so surface the
+		// failure loudly enough to be visible in normal CI logs; still
+		// non-fatal so the render/build proceeds without the macros.
+		slog.Warn("Skipping upstream provenance macros; spec not found",
+			"component", component.GetName(), "error", err)
+
+		return
+	}
+
+	version, release, err := parseSpecVersionRelease(p.fs, specPath)
+	if err != nil {
+		slog.Warn("Skipping upstream provenance macros; failed to parse spec",
+			"component", component.GetName(), "error", err)
+
+		return
+	}
+
+	if version != "" {
+		setMacroIfAbsent(macros, fedoraUpstreamVersionMacro, version)
+	}
+
+	if release != "" {
+		setMacroIfAbsent(macros, fedoraUpstreamReleaseMacro,
+			strings.ReplaceAll(release, distPlaceholder, p.upstreamDistTag))
+	}
+}
+
+// setMacroIfAbsent sets macros[name]=value only when name is not already
+// present, so user-defined macros (e.g. from 'build.defines') win.
+func setMacroIfAbsent(macros map[string]string, name, value string) {
+	if _, exists := macros[name]; !exists {
+		macros[name] = value
+	}
+}
+
+// parseSpecVersionRelease reads the Version and Release tags from the base
+// package of the spec at specPath. Values are captured verbatim (no macro
+// expansion beyond the caller's later %{?dist} substitution). Missing tags
+// yield empty strings; it is not an error for a tag to be absent.
+func parseSpecVersionRelease(fs opctx.FS, specPath string) (version, release string, err error) {
+	data, err := fileutils.ReadFile(fs, specPath)
+	if err != nil {
+		return "", "", fmt.Errorf("failed to read spec %#q:\n%w", specPath, err)
+	}
+
+	parsed, err := spec.OpenSpec(bytes.NewReader(data))
+	if err != nil {
+		return "", "", fmt.Errorf("failed to parse spec %#q:\n%w", specPath, err)
+	}
+
+	// VisitTagsPackage("") iterates tags in the base (unnamed) package, where
+	// Name/Version/Release live for a well-formed spec.
+	visitErr := parsed.VisitTagsPackage("", func(tagLine *spec.TagLine, _ *spec.Context) error {
+		switch strings.ToLower(tagLine.Tag) {
+		case "version":
+			if version == "" {
+				version = strings.TrimSpace(tagLine.Value)
+			}
+		case "release":
+			if release == "" {
+				release = strings.TrimSpace(tagLine.Value)
+			}
+		}
+
+		return nil
+	})
+	if visitErr != nil {
+		return "", "", fmt.Errorf("failed to scan spec tags in %#q:\n%w", specPath, visitErr)
+	}
+
+	return version, release, nil
+}
diff --git a/internal/app/azldev/core/sources/upstream_provenance_internal_test.go b/internal/app/azldev/core/sources/upstream_provenance_internal_test.go
new file mode 100644
index 000000000..dc6993bce
--- /dev/null
+++ b/internal/app/azldev/core/sources/upstream_provenance_internal_test.go
@@ -0,0 +1,183 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+package sources
+
+import (
+	"path/filepath"
+	"testing"
+
+	"github.com/microsoft/azure-linux-dev-tools/internal/projectconfig"
+	"github.com/microsoft/azure-linux-dev-tools/internal/utils/fileperms"
+	"github.com/microsoft/azure-linux-dev-tools/internal/utils/fileutils"
+	"github.com/spf13/afero"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.uber.org/mock/gomock"
+)
+
+const provenanceWorkDir = "/prov-work"
+
+// writeProvenanceSpec writes a minimal spec file named "<name>.spec" into
+// provenanceWorkDir, including Version/Release tags only when the corresponding
+// value is non-empty.
+func writeProvenanceSpec(t *testing.T, memFS afero.Fs, name, version, release string) {
+	t.Helper()
+
+	require.NoError(t, fileutils.MkdirAll(memFS, provenanceWorkDir))
+
+	content := "Name: " + name + "\nSummary: test\nLicense: MIT\n"
+	if version != "" {
+		content += "Version: " + version + "\n"
+	}
+
+	if release != "" {
+		content += "Release: " + release + "\n"
+	}
+
+	specPath := filepath.Join(provenanceWorkDir, name+".spec")
+	require.NoError(t, fileutils.WriteFile(memFS, specPath, []byte(content), fileperms.PublicFile))
+}
+
+func TestFedoraDistTag(t *testing.T) {
+	assert.Equal(t, ".fc43", FedoraDistTag("fedora", "43"))
+	assert.Equal(t, ".fc43", FedoraDistTag("Fedora", "43"), "distro name match is case-insensitive")
+	assert.Empty(t, FedoraDistTag("azurelinux", "3.0"), "non-Fedora distros get no dist tag")
+	assert.Empty(t, FedoraDistTag("fedora", ""), "empty release version yields no dist tag")
+	assert.Empty(t, FedoraDistTag("fedora", "rawhide"), "non-numeric release version yields no dist tag")
+	assert.Empty(t, FedoraDistTag("fedora", "43.0"), "non-integer release version yields no dist tag")
+	assert.Empty(t, FedoraDistTag("", "43"))
+}
+
+func TestParseSpecVersionRelease(t *testing.T) {
+	memFS := afero.NewMemMapFs()
+	writeProvenanceSpec(t, memFS, "grub2", "2.12", "5%{?dist}")
+
+	version, release, err := parseSpecVersionRelease(memFS, filepath.Join(provenanceWorkDir, "grub2.spec"))
+	require.NoError(t, err)
+	assert.Equal(t, "2.12", version)
+	assert.Equal(t, "5%{?dist}", release, "release is captured verbatim, dist is expanded later")
+}
+
+func TestParseSpecVersionRelease_MissingFile(t *testing.T) {
+	_, _, err := parseSpecVersionRelease(afero.NewMemMapFs(), "/does-not-exist.spec")
+	require.Error(t, err)
+}
+
+func TestAddUpstreamProvenanceMacros_FedoraUpstream(t *testing.T) {
+	ctrl := gomock.NewController(t)
+	memFS := afero.NewMemMapFs()
+	writeProvenanceSpec(t, memFS, "grub2", "2.12", "5%{?dist}")
+
+	comp := mockComponent(ctrl, "grub2", upstreamCfg(true))
+
+	preparer := &sourcePreparerImpl{fs: memFS, upstreamDistTag: ".fc43"}
+	macros := map[string]string{}
+	preparer.addUpstreamProvenanceMacros(macros, comp, provenanceWorkDir)
+
+	assert.Equal(t, "2.12", macros[fedoraUpstreamVersionMacro])
+	assert.Equal(t, "5.fc43", macros[fedoraUpstreamReleaseMacro], "%{?dist} is expanded to the Fedora dist tag")
+}
+
+func TestAddUpstreamProvenanceMacros_LocalComponentSkipped(t *testing.T) {
+	ctrl := gomock.NewController(t)
+	memFS := afero.NewMemMapFs()
+	writeProvenanceSpec(t, memFS, "mytool", "1.0", "1%{?dist}")
+
+	comp := mockComponent(ctrl, "mytool", &projectconfig.ComponentConfig{
+		Spec:  projectconfig.SpecSource{SourceType: projectconfig.SpecSourceTypeLocal},
+		Build: projectconfig.ComponentBuildConfig{EmitUpstreamProvenance: true},
+	})
+
+	preparer := &sourcePreparerImpl{fs: memFS, upstreamDistTag: ".fc43"}
+	macros := map[string]string{}
+	preparer.addUpstreamProvenanceMacros(macros, comp, provenanceWorkDir)
+
+	assert.Empty(t, macros, "local components have no upstream provenance even when opted in")
+}
+
+func TestAddUpstreamProvenanceMacros_NonFedoraSkipped(t *testing.T) {
+	ctrl := gomock.NewController(t)
+	memFS := afero.NewMemMapFs()
+	writeProvenanceSpec(t, memFS, "grub2", "2.12", "5%{?dist}")
+
+	comp := mockComponent(ctrl, "grub2", upstreamCfg(true))
+
+	// Empty dist tag signals a non-Fedora upstream; no macros should be added.
+	preparer := &sourcePreparerImpl{fs: memFS, upstreamDistTag: ""}
+	macros := map[string]string{}
+	preparer.addUpstreamProvenanceMacros(macros, comp, provenanceWorkDir)
+
+	assert.Empty(t, macros)
+}
+
+func TestAddUpstreamProvenanceMacros_UserDefineWins(t *testing.T) {
+	ctrl := gomock.NewController(t)
+	memFS := afero.NewMemMapFs()
+	writeProvenanceSpec(t, memFS, "grub2", "2.12", "5%{?dist}")
+
+	comp := mockComponent(ctrl, "grub2", upstreamCfg(true))
+
+	preparer := &sourcePreparerImpl{fs: memFS, upstreamDistTag: ".fc43"}
+	macros := map[string]string{fedoraUpstreamVersionMacro: "user-override"}
+	preparer.addUpstreamProvenanceMacros(macros, comp, provenanceWorkDir)
+
+	assert.Equal(t, "user-override", macros[fedoraUpstreamVersionMacro], "existing user-defined macro is not overwritten")
+	assert.Equal(t, "5.fc43", macros[fedoraUpstreamReleaseMacro])
+}
+
+func TestAddUpstreamProvenanceMacros_MissingSpecBestEffort(t *testing.T) {
+	ctrl := gomock.NewController(t)
+	memFS := afero.NewMemMapFs()
+
+	comp := mockComponent(ctrl, "grub2", upstreamCfg(true))
+
+	// No spec on disk: capture is best-effort, so no macros and no panic/error.
+	preparer := &sourcePreparerImpl{fs: memFS, upstreamDistTag: ".fc43"}
+	macros := map[string]string{}
+	preparer.addUpstreamProvenanceMacros(macros, comp, provenanceWorkDir)
+
+	assert.Empty(t, macros)
+}
+
+func TestAddUpstreamProvenanceMacros_EmptyReleaseSkipped(t *testing.T) {
+	ctrl := gomock.NewController(t)
+	memFS := afero.NewMemMapFs()
+	writeProvenanceSpec(t, memFS, "pkg", "1.0", "")
+
+	comp := mockComponent(ctrl, "pkg", upstreamCfg(true))
+
+	preparer := &sourcePreparerImpl{fs: memFS, upstreamDistTag: ".fc43"}
+	macros := map[string]string{}
+	preparer.addUpstreamProvenanceMacros(macros, comp, provenanceWorkDir)
+
+	assert.Equal(t, "1.0", macros[fedoraUpstreamVersionMacro])
+
+	_, hasRelease := macros[fedoraUpstreamReleaseMacro]
+	assert.False(t, hasRelease, "no Release tag means no release macro is emitted")
+}
+
+func TestAddUpstreamProvenanceMacros_OptedOutSkipped(t *testing.T) {
+	ctrl := gomock.NewController(t)
+	memFS := afero.NewMemMapFs()
+	writeProvenanceSpec(t, memFS, "grub2", "2.12", "5%{?dist}")
+
+	// Fedora upstream with a parseable spec, but provenance emission is not
+	// enabled, so no macros should be added.
+	comp := mockComponent(ctrl, "grub2", upstreamCfg(false))
+
+	preparer := &sourcePreparerImpl{fs: memFS, upstreamDistTag: ".fc43"}
+	macros := map[string]string{}
+	preparer.addUpstreamProvenanceMacros(macros, comp, provenanceWorkDir)
+
+	assert.Empty(t, macros, "provenance macros require opt-in via build.emit-upstream-provenance")
+}
+
+// upstreamCfg returns a Fedora-upstream component config with provenance
+// emission toggled by emit.
+func upstreamCfg(emit bool) *projectconfig.ComponentConfig {
+	return &projectconfig.ComponentConfig{
+		Spec:  projectconfig.SpecSource{SourceType: projectconfig.SpecSourceTypeUpstream},
+		Build: projectconfig.ComponentBuildConfig{EmitUpstreamProvenance: emit},
+	}
+}
diff --git a/internal/projectconfig/build.go b/internal/projectconfig/build.go
index 385e3108d..5ea36f910 100644
--- a/internal/projectconfig/build.go
+++ b/internal/projectconfig/build.go
@@ -31,6 +31,11 @@ func (c *CheckConfig) Validate() error {
 
 // Encapsulates configuration for building a component. Configuration for how to acquire
 // or prepare the sources for a component are out of scope.
+//
+// HashInclude must be a value receiver because hashstructure's Includable interface is
+// invoked on the hashed value; Validate uses a pointer receiver by convention.
+//
+//nolint:recvcheck // value + pointer receivers are intentional (see doc comment above).
 type ComponentBuildConfig struct {
 	// Which features should be enabled via `with` options to the builder.
 	With []string `toml:"with,omitempty" json:"with,omitempty" jsonschema:"title=With options,description='with' options to pass to the builder."`
@@ -40,6 +45,12 @@ type ComponentBuildConfig struct {
 	Defines map[string]string `toml:"defines,omitempty" json:"defines,omitempty" jsonschema:"title=Macro definitions,description=Macro definitions to pass to the builder."`
 	// Undefine macros that would otherwise be defined by the component configuration.
 	Undefines []string `toml:"undefines,omitempty" json:"undefines,omitempty" jsonschema:"title=Undefined macros,description=Macro names to undefine when passing to the builder."`
+	// EmitUpstreamProvenance, when true, injects %fedora_upstream_version and
+	// %fedora_upstream_release macros (derived from the pristine upstream Fedora
+	// spec) into the component's generated macros file. Only effective for Fedora
+	// upstream components. Opt-in because the macros are only useful to specs that
+	// reference them (e.g. grub2's SBAT metadata).
+	EmitUpstreamProvenance bool `toml:"emit-upstream-provenance,omitempty" json:"emitUpstreamProvenance,omitempty" jsonschema:"title=Emit upstream provenance macros,description=Inject %fedora_upstream_version/release macros derived from the pristine upstream Fedora spec (Fedora upstream components only)."`
 	// Check section configuration.
 	Check CheckConfig `toml:"check,omitempty" json:"check,omitempty" jsonschema:"title=Check configuration,description=Configuration for the %check section"`
 	// Failure configuration and policy for this component's build.
@@ -48,6 +59,17 @@ type ComponentBuildConfig struct {
 	Hints ComponentBuildHints `toml:"hints,omitempty" json:"hints,omitempty" jsonschema:"title=Build hints,description=Non-essential hints for how or when to build the component." fingerprint:"-"`
 }
 
+// HashInclude implements the hashstructure [Includable] interface so that
+// [ComponentBuildConfig.EmitUpstreamProvenance] is omitted from the component
+// fingerprint when false or not set.
+func (c ComponentBuildConfig) HashInclude(field string, _ any) (bool, error) {
+	if field == "EmitUpstreamProvenance" {
+		return c.EmitUpstreamProvenance, nil
+	}
+
+	return true, nil
+}
+
 // ComponentBuildFailureConfig encapsulates configuration and policy regarding a component's
 // build failure.
 type ComponentBuildFailureConfig struct {
diff --git a/internal/projectconfig/build_test.go b/internal/projectconfig/build_test.go
index b6dafada8..7520abeb0 100644
--- a/internal/projectconfig/build_test.go
+++ b/internal/projectconfig/build_test.go
@@ -7,6 +7,7 @@ import (
 	"testing"
 
 	"github.com/microsoft/azure-linux-dev-tools/internal/projectconfig"
+	"github.com/mitchellh/hashstructure/v2"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
@@ -191,3 +192,43 @@ func TestComponentBuildConfig_Validate(t *testing.T) {
 		})
 	}
 }
+
+// TestComponentBuildConfig_HashInclude verifies the fingerprint override:
+// EmitUpstreamProvenance is included only when true (so enabling it is the only
+// thing that perturbs a component's hash), while all other fields are always
+// included.
+func TestComponentBuildConfig_HashInclude(t *testing.T) {
+	disabled := projectconfig.ComponentBuildConfig{}
+	enabled := projectconfig.ComponentBuildConfig{EmitUpstreamProvenance: true}
+
+	include, err := disabled.HashInclude("EmitUpstreamProvenance", nil)
+	require.NoError(t, err)
+	assert.False(t, include, "a false flag is omitted so it does not perturb the fingerprint")
+
+	include, err = enabled.HashInclude("EmitUpstreamProvenance", nil)
+	require.NoError(t, err)
+	assert.True(t, include, "a true flag is included so enabling it changes the fingerprint")
+
+	include, err = disabled.HashInclude("With", nil)
+	require.NoError(t, err)
+	assert.True(t, include, "unrelated fields are always included")
+}
+
+// TestComponentBuildConfig_ProvenanceFingerprint confirms that enabling
+// provenance changes the hashstructure fingerprint, so an opted-in component
+// rebuilds while others are unaffected.
+func TestComponentBuildConfig_ProvenanceFingerprint(t *testing.T) {
+	hash := func(c projectconfig.ComponentBuildConfig) uint64 {
+		h, err := hashstructure.Hash(c, hashstructure.FormatV2, &hashstructure.HashOptions{TagName: "fingerprint"})
+		require.NoError(t, err)
+
+		return h
+	}
+
+	disabled := projectconfig.ComponentBuildConfig{With: []string{"feature"}}
+	enabled := disabled
+	enabled.EmitUpstreamProvenance = true
+
+	assert.NotEqual(t, hash(disabled), hash(enabled),
+		"enabling provenance changes the fingerprint so the component rebuilds")
+}
diff --git a/scenario/__snapshots__/TestSnapshotsContainer_config_generate-schema_stdout_1.snap b/scenario/__snapshots__/TestSnapshotsContainer_config_generate-schema_stdout_1.snap
index 60b299449..21f2390d6 100755
--- a/scenario/__snapshots__/TestSnapshotsContainer_config_generate-schema_stdout_1.snap
+++ b/scenario/__snapshots__/TestSnapshotsContainer_config_generate-schema_stdout_1.snap
@@ -53,6 +53,11 @@
           "title": "Undefined macros",
           "description": "Macro names to undefine when passing to the builder."
         },
+        "emit-upstream-provenance": {
+          "type": "boolean",
+          "title": "Emit upstream provenance macros",
+          "description": "Inject %fedora_upstream_version/release macros derived from the pristine upstream Fedora spec (Fedora upstream components only)."
+        },
         "check": {
           "$ref": "#/$defs/CheckConfig",
           "title": "Check configuration",
diff --git a/scenario/__snapshots__/TestSnapshots_config_generate-schema_stdout_1.snap b/scenario/__snapshots__/TestSnapshots_config_generate-schema_stdout_1.snap
index 60b299449..21f2390d6 100755
--- a/scenario/__snapshots__/TestSnapshots_config_generate-schema_stdout_1.snap
+++ b/scenario/__snapshots__/TestSnapshots_config_generate-schema_stdout_1.snap
@@ -53,6 +53,11 @@
           "title": "Undefined macros",
           "description": "Macro names to undefine when passing to the builder."
         },
+        "emit-upstream-provenance": {
+          "type": "boolean",
+          "title": "Emit upstream provenance macros",
+          "description": "Inject %fedora_upstream_version/release macros derived from the pristine upstream Fedora spec (Fedora upstream components only)."
+        },
         "check": {
           "$ref": "#/$defs/CheckConfig",
           "title": "Check configuration",
diff --git a/schemas/azldev.schema.json b/schemas/azldev.schema.json
index 60b299449..21f2390d6 100644
--- a/schemas/azldev.schema.json
+++ b/schemas/azldev.schema.json
@@ -53,6 +53,11 @@
           "title": "Undefined macros",
           "description": "Macro names to undefine when passing to the builder."
         },
+        "emit-upstream-provenance": {
+          "type": "boolean",
+          "title": "Emit upstream provenance macros",
+          "description": "Inject %fedora_upstream_version/release macros derived from the pristine upstream Fedora spec (Fedora upstream components only)."
+        },
         "check": {
           "$ref": "#/$defs/CheckConfig",
           "title": "Check configuration",