test(unixfs): lock in CID profile behavior (IPIP-550)

config/import.go

@@ -45,9 +45,14 @@ const (
 	DAGLayoutBalanced = "balanced" // balanced DAG layout (default)
 	DAGLayoutTrickle  = "trickle"  // trickle DAG layout
 
-	DefaultUnixFSHAMTDirectorySizeEstimation = HAMTSizeEstimationLinks // legacy behavior
-	DefaultUnixFSDAGLayout                   = DAGLayoutBalanced       // balanced DAG layout
-	DefaultUnixFSIncludeEmptyDirs            = true                    // include empty directories
+	// PBNodeFieldOrder values for Import.UnixFSPBNodeFieldOrder
+	PBNodeFieldOrderLinksFirst = "links-first" // canonical DAG-PB order (default)
+	PBNodeFieldOrderDataFirst  = "data-first"  // streaming-friendly order (IPIP-550)
+
+	DefaultUnixFSHAMTDirectorySizeEstimation = HAMTSizeEstimationLinks    // legacy behavior
+	DefaultUnixFSDAGLayout                   = DAGLayoutBalanced          // balanced DAG layout
+	DefaultUnixFSIncludeEmptyDirs            = true                       // include empty directories
+	DefaultUnixFSPBNodeFieldOrder            = PBNodeFieldOrderLinksFirst // keeps existing CIDs
 )
 
 var (
@@ -69,6 +74,7 @@ type Import struct {
 	UnixFSHAMTDirectorySizeThreshold  OptionalBytes
 	UnixFSHAMTDirectorySizeEstimation OptionalString // "links", "block", or "disabled"
 	UnixFSDAGLayout                   OptionalString // "balanced" or "trickle"
+	UnixFSPBNodeFieldOrder            OptionalString // "links-first" or "data-first"
 	BatchMaxNodes                     OptionalInteger
 	BatchMaxSize                      OptionalInteger
 	FastProvideRoot                   Flag
@@ -174,6 +180,18 @@ func ValidateImportConfig(cfg *Import) error {
 		}
 	}
 
+	// Validate UnixFSPBNodeFieldOrder
+	if !cfg.UnixFSPBNodeFieldOrder.IsDefault() {
+		order := cfg.UnixFSPBNodeFieldOrder.WithDefault(DefaultUnixFSPBNodeFieldOrder)
+		switch order {
+		case PBNodeFieldOrderLinksFirst, PBNodeFieldOrderDataFirst:
+			// valid
+		default:
+			return fmt.Errorf("Import.UnixFSPBNodeFieldOrder must be %q or %q, got %q",
+				PBNodeFieldOrderLinksFirst, PBNodeFieldOrderDataFirst, order)
+		}
+	}
+
 	return nil
 }
 
@@ -241,6 +259,16 @@ func (i *Import) HAMTSizeEstimationMode() uio.SizeEstimationMode {
 	}
 }
 
+// PBNodeFieldOrderMode returns the boxo PBNodeFieldOrder based on the config value.
+func (i *Import) PBNodeFieldOrderMode() merkledag.PBNodeFieldOrder {
+	switch i.UnixFSPBNodeFieldOrder.WithDefault(DefaultUnixFSPBNodeFieldOrder) {
+	case PBNodeFieldOrderDataFirst:
+		return merkledag.PBNodeDataFirst
+	default:
+		return merkledag.PBNodeLinksFirst
+	}
+}
+
 // UnixFSSplitterFunc returns a SplitterGen function based on Import.UnixFSChunker.
 // The returned function creates a Splitter for the configured chunking strategy.
 // The chunker string is parsed once when this method is called, not on each use.

config/profile.go

@@ -354,19 +354,7 @@ See https://specs.ipfs.tech/ipips/ipip-0499/. Alias: legacy-cid-v0`,
 Uses CIDv1, raw leaves, sha2-256, 1 MiB chunks, 1024 links per file node,
 256 HAMT fanout, and block-based size estimation for HAMT threshold.
 See https://specs.ipfs.tech/ipips/ipip-0499/`,
-		Transform: func(c *Config) error {
-			c.Import.CidVersion = *NewOptionalInteger(1)
-			c.Import.UnixFSRawLeaves = True
-			c.Import.UnixFSChunker = *NewOptionalString("size-1048576") // 1 MiB
-			c.Import.HashFunction = *NewOptionalString("sha2-256")
-			c.Import.UnixFSFileMaxLinks = *NewOptionalInteger(1024)
-			c.Import.UnixFSDirectoryMaxLinks = *NewOptionalInteger(0)
-			c.Import.UnixFSHAMTDirectoryMaxFanout = *NewOptionalInteger(256)
-			c.Import.UnixFSHAMTDirectorySizeThreshold = *NewOptionalBytes("256KiB")
-			c.Import.UnixFSHAMTDirectorySizeEstimation = *NewOptionalString(HAMTSizeEstimationBlock)
-			c.Import.UnixFSDAGLayout = *NewOptionalString(DAGLayoutBalanced)
-			return nil
-		},
+		Transform: applyUnixFSv12025,
 	},
 	"autoconf-on": {
 		Description: `Sets configuration to use implicit defaults from remote autoconf service.
@@ -462,5 +450,22 @@ func applyUnixFSv02015(c *Config) error {
 	c.Import.UnixFSHAMTDirectorySizeThreshold = *NewOptionalBytes("256KiB")
 	c.Import.UnixFSHAMTDirectorySizeEstimation = *NewOptionalString(HAMTSizeEstimationLinks)
 	c.Import.UnixFSDAGLayout = *NewOptionalString(DAGLayoutBalanced)
+	c.Import.UnixFSPBNodeFieldOrder = *NewOptionalString(PBNodeFieldOrderLinksFirst)
+	return nil
+}
+
+// applyUnixFSv12025 applies the unixfs-v1-2025 import settings from IPIP-499.
+func applyUnixFSv12025(c *Config) error {
+	c.Import.CidVersion = *NewOptionalInteger(1)
+	c.Import.UnixFSRawLeaves = True
+	c.Import.UnixFSChunker = *NewOptionalString("size-1048576") // 1 MiB
+	c.Import.HashFunction = *NewOptionalString("sha2-256")
+	c.Import.UnixFSFileMaxLinks = *NewOptionalInteger(1024)
+	c.Import.UnixFSDirectoryMaxLinks = *NewOptionalInteger(0)
+	c.Import.UnixFSHAMTDirectoryMaxFanout = *NewOptionalInteger(256)
+	c.Import.UnixFSHAMTDirectorySizeThreshold = *NewOptionalBytes("256KiB")
+	c.Import.UnixFSHAMTDirectorySizeEstimation = *NewOptionalString(HAMTSizeEstimationBlock)
+	c.Import.UnixFSDAGLayout = *NewOptionalString(DAGLayoutBalanced)
+	c.Import.UnixFSPBNodeFieldOrder = *NewOptionalString(PBNodeFieldOrderLinksFirst)
 	return nil
 }

core/node/groups.go

@@ -10,6 +10,7 @@ import (
 
 	blockstore "github.com/ipfs/boxo/blockstore"
 	offline "github.com/ipfs/boxo/exchange/offline"
+	merkledag "github.com/ipfs/boxo/ipld/merkledag"
 	uio "github.com/ipfs/boxo/ipld/unixfs/io"
 	util "github.com/ipfs/boxo/util"
 	"github.com/ipfs/go-log/v2"
@@ -453,6 +454,7 @@ func IPFS(ctx context.Context, bcfg *BuildCfg) fx.Option {
 	uio.HAMTShardingSize = int(shardSizeThreshold)
 	uio.DefaultShardWidth = int(shardMaxFanout)
 	uio.HAMTSizeEstimation = cfg.Import.HAMTSizeEstimationMode()
+	merkledag.DefaultPBNodeFieldOrder = cfg.Import.PBNodeFieldOrderMode()
 
 	providerStrategy := cfg.Provide.Strategy.WithDefault(config.DefaultProvideStrategy)
 

docs/changelogs/v0.43.md

@@ -521,11 +521,17 @@ Bitswap over HTTP no longer probes every connected HTTP provider with `GET/HEAD
 
 `go-libp2p-kad-dht` v0.42.0, first shipped in Kubo v0.43.0, turned every DHT provider record write, and every delete made by the provider's garbage collection, into an individual, fsynced datastore operation. On nodes announcing many CIDs this showed up as constant disk activity ([#11432](https://github.com/ipfs/kubo/issues/11432)). This release batches these writes and deletes again, 256 records at a time, restoring the disk write rate from before v0.43.0. Nothing changes on the wire or in the datastore layout; upgrading is all that is needed.
 
+#### 🔒 Hardened CID profiles, new low-level knob
+
+The `unixfs-v0-2015` and `unixfs-v1-2025` profiles now pin the `PBNode` field order (`links-first`) explicitly, and regression tests lock in the exact bytes and CIDs they produce. Reading blocks in either field order is formalized in [IPIP-550](https://github.com/ipfs/specs/pull/550) and tested by [gateway-conformance v0.14.1](https://github.com/ipfs/gateway-conformance/releases/tag/v0.14.1). Nothing changes by default.
+
+For writers that need `Data`-first output (streaming readers can then parse HAMT shards without buffering all links first), there is a new opt-in [`Import.UnixFSPBNodeFieldOrder`](https://github.com/ipfs/kubo/blob/master/docs/config.md#importunixfspbnodefieldorder) option. No profile enables it. Opting in changes the CIDs of newly added directories, HAMT shards, and multi-chunk files, and MFS re-encodes the directories that `ipfs files` operations rewrite; enable it only when consumers of your CIDs expect the new order.
+
 #### 📦️ Dependency updates
 
-- update `boxo` to [v0.42.2](https://github.com/ipfs/boxo/releases/tag/v0.42.2)
+- update `boxo` to [v0.42.3-0.20260904132258-02026ddcf262](https://github.com/ipfs/boxo/commit/02026ddcf262) (includes [ipfs/boxo#1212](https://github.com/ipfs/boxo/pull/1212)) <!-- TODO: switch to a tagged boxo release before kubo v0.43.1 is tagged -->
 - update `go-libp2p-kad-dht` to [v0.42.2](https://github.com/libp2p/go-libp2p-kad-dht/releases/tag/v0.42.2)
-- update `gateway-conformance` to [v0.14.0](https://github.com/ipfs/gateway-conformance/releases/tag/v0.14.0)
+- update `gateway-conformance` to [v0.14.1](https://github.com/ipfs/gateway-conformance/releases/tag/v0.14.1)
 
 ### 📝 Changelog
 

docs/config.md

@@ -255,6 +255,7 @@ config file at runtime.
     - [`Import.UnixFSHAMTDirectorySizeThreshold`](#importunixfshamtdirectorysizethreshold)
     - [`Import.UnixFSHAMTDirectorySizeEstimation`](#importunixfshamtdirectorysizeestimation)
     - [`Import.UnixFSDAGLayout`](#importunixfsdaglayout)
+    - [`Import.UnixFSPBNodeFieldOrder`](#importunixfspbnodefieldorder)
   - [`Version`](#version)
     - [`Version.AgentSuffix`](#versionagentsuffix)
     - [`Version.SwarmCheckEnabled`](#versionswarmcheckenabled)
@@ -4284,6 +4285,32 @@ Default: `balanced`
 
 Type: `optionalString`
 
+### `Import.UnixFSPBNodeFieldOrder`
+
+Controls the order of the top-level `PBNode` protobuf fields written when
+creating `dag-pb` nodes.
+
+Accepted values:
+
+- `links-first` (default): canonical DAG-PB order, `Links` before `Data`.
+- `data-first`: `Data` before `Links`, so streaming readers can process
+  UnixFS metadata (for example HAMT fanout) before reading links. Changes
+  the CID of every written `dag-pb` node that has both fields.
+
+Only writes are affected; reading accepts both orders regardless of this
+setting. This is a low-level opt-in: no configuration profile enables
+`data-first`, and the `unixfs-v0-2015` and `unixfs-v1-2025` profiles set
+`links-first` explicitly. Enable `data-first` only when every consumer of
+your CIDs expects it, and note that MFS directories rewritten by
+`ipfs files` operations are re-encoded and get new CIDs. See
+[IPIP-550](https://github.com/ipfs/specs/pull/550) for details.
+
+Commands affected: `ipfs add`, `ipfs files` (MFS), `ipfs object patch`
+
+Default: `links-first`
+
+Type: `optionalString`
+
 ## `Version`
 
 Options to configure agent version announced to the swarm, and leveraging

docs/examples/kubo-as-a-library/go.mod

@@ -7,7 +7,7 @@ go 1.26.5
 replace github.com/ipfs/kubo => ./../../..
 
 require (
-	github.com/ipfs/boxo v0.42.3-0.20260827015437-63cae36adc96
+	github.com/ipfs/boxo v0.42.3-0.20260904132258-02026ddcf262
 	github.com/ipfs/kubo v0.0.0-00010101000000-000000000000
 	github.com/libp2p/go-libp2p v0.49.0
 	github.com/multiformats/go-multiaddr v0.16.1

docs/examples/kubo-as-a-library/go.sum

@@ -268,8 +268,8 @@ github.com/ipfs-shipyard/nopfs/ipfs v0.25.0 h1:OqNqsGZPX8zh3eFMO8Lf8EHRRnSGBMqcd
 github.com/ipfs-shipyard/nopfs/ipfs v0.25.0/go.mod h1:BxhUdtBgOXg1B+gAPEplkg/GpyTZY+kCMSfsJvvydqU=
 github.com/ipfs/bbloom v0.1.0 h1:nIWwfIE3AaG7RCDQIsrUonGCOTp7qSXzxH7ab/ss964=
 github.com/ipfs/bbloom v0.1.0/go.mod h1:lDy3A3i6ndgEW2z1CaRFvDi5/ZTzgM1IxA/pkL7Wgts=
-github.com/ipfs/boxo v0.42.3-0.20260827015437-63cae36adc96 h1:8oZfkjCQcllUpAJFRskYHZbUiaMV6SqGCc+FJIuD93M=
-github.com/ipfs/boxo v0.42.3-0.20260827015437-63cae36adc96/go.mod h1:TCEs4l6Q6kfd1SUdYEzcxvC8JE1gc+6dObSs/6kOsb8=
+github.com/ipfs/boxo v0.42.3-0.20260904132258-02026ddcf262 h1:ccv4Wuz0qtHE52U0r4r2+NpnFbPYJp8riL6vTX6i3ic=
+github.com/ipfs/boxo v0.42.3-0.20260904132258-02026ddcf262/go.mod h1:TCEs4l6Q6kfd1SUdYEzcxvC8JE1gc+6dObSs/6kOsb8=
 github.com/ipfs/go-bitfield v1.1.0 h1:fh7FIo8bSwaJEh6DdTWbCeZ1eqOaOkKFI74SCnsWbGA=
 github.com/ipfs/go-bitfield v1.1.0/go.mod h1:paqf1wjq/D2BBmzfTVFlJQ9IlFOZpg422HL0HqsGWHU=
 github.com/ipfs/go-block-format v0.2.4 h1:pgsT9i8zB4YQkBIQRrBwqbQiXPogRCiQnfxd2bC4koI=

go.mod

@@ -22,7 +22,7 @@ require (
 	github.com/hashicorp/go-version v1.9.0
 	github.com/ipfs-shipyard/nopfs v0.0.14
 	github.com/ipfs-shipyard/nopfs/ipfs v0.25.0
-	github.com/ipfs/boxo v0.42.3-0.20260827015437-63cae36adc96
+	github.com/ipfs/boxo v0.42.3-0.20260904132258-02026ddcf262
 	github.com/ipfs/go-block-format v0.2.4
 	github.com/ipfs/go-cid v0.6.2
 	github.com/ipfs/go-cidutil v0.1.2

go.sum

@@ -340,8 +340,8 @@ github.com/ipfs-shipyard/nopfs/ipfs v0.25.0 h1:OqNqsGZPX8zh3eFMO8Lf8EHRRnSGBMqcd
 github.com/ipfs-shipyard/nopfs/ipfs v0.25.0/go.mod h1:BxhUdtBgOXg1B+gAPEplkg/GpyTZY+kCMSfsJvvydqU=
 github.com/ipfs/bbloom v0.1.0 h1:nIWwfIE3AaG7RCDQIsrUonGCOTp7qSXzxH7ab/ss964=
 github.com/ipfs/bbloom v0.1.0/go.mod h1:lDy3A3i6ndgEW2z1CaRFvDi5/ZTzgM1IxA/pkL7Wgts=
-github.com/ipfs/boxo v0.42.3-0.20260827015437-63cae36adc96 h1:8oZfkjCQcllUpAJFRskYHZbUiaMV6SqGCc+FJIuD93M=
-github.com/ipfs/boxo v0.42.3-0.20260827015437-63cae36adc96/go.mod h1:TCEs4l6Q6kfd1SUdYEzcxvC8JE1gc+6dObSs/6kOsb8=
+github.com/ipfs/boxo v0.42.3-0.20260904132258-02026ddcf262 h1:ccv4Wuz0qtHE52U0r4r2+NpnFbPYJp8riL6vTX6i3ic=
+github.com/ipfs/boxo v0.42.3-0.20260904132258-02026ddcf262/go.mod h1:TCEs4l6Q6kfd1SUdYEzcxvC8JE1gc+6dObSs/6kOsb8=
 github.com/ipfs/go-bitfield v1.1.0 h1:fh7FIo8bSwaJEh6DdTWbCeZ1eqOaOkKFI74SCnsWbGA=
 github.com/ipfs/go-bitfield v1.1.0/go.mod h1:paqf1wjq/D2BBmzfTVFlJQ9IlFOZpg422HL0HqsGWHU=
 github.com/ipfs/go-block-format v0.2.4 h1:pgsT9i8zB4YQkBIQRrBwqbQiXPogRCiQnfxd2bC4koI=

test/cli/cid_profiles_test.go

@@ -1,6 +1,7 @@
 package cli
 
 import (
+	"encoding/hex"
 	"encoding/json"
 	"os"
 	"path/filepath"
@@ -623,6 +624,54 @@ func hamtSeedForProfile(exp cidProfileExpectations) string {
 	}
 }
 
+// TestUnixFSPBNodeFieldOrder verifies the opt-in Import.UnixFSPBNodeFieldOrder
+// setting writes PBNode messages with the Data field before Links (IPIP-550,
+// https://github.com/ipfs/specs/pull/550), reproducing the byte-exact
+// fixtures from the IPIP, while the unixfs-v1-2025 profile pins the legacy
+// links-first encoding and its CIDs.
+func TestUnixFSPBNodeFieldOrder(t *testing.T) {
+	t.Parallel()
+
+	// Fixtures from the IPIP-550 test fixtures table: a directory holding
+	// hello.txt ("hello\n" raw leaf), encoded in both PBNode field orders.
+	const (
+		dirDataFirstCID  = "bafybeigqvyloizmfcdy6scaxnyltftzptaruqa3hnnplfzsbf4sqteiwlm"
+		dirLinksFirstCID = "bafybeigdcg7pksx2zk5336vrfsktjodlr4rbfz37qr3koc5xboxe5ekv24"
+		dirDataFirstHex  = "0a02080112330a24015512205891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03120968656c6c6f2e7478741806"
+	)
+
+	addFixtureDir := func(t *testing.T, node *harness.Node) string {
+		dir := filepath.Join(node.Dir, "fixture")
+		require.NoError(t, os.Mkdir(dir, 0o755))
+		require.NoError(t, os.WriteFile(filepath.Join(dir, "hello.txt"), []byte("hello\n"), 0o644))
+		return node.IPFS("add", "-r", "-Q", dir).Stdout.Trimmed()
+	}
+
+	t.Run("data-first setting writes Data field before Links", func(t *testing.T) {
+		t.Parallel()
+		node := harness.NewT(t).NewNode().Init("--profile=unixfs-v1-2025")
+		node.IPFS("config", "Import.UnixFSPBNodeFieldOrder", "data-first")
+		node.StartDaemon()
+		defer node.StopDaemon()
+
+		cidStr := addFixtureDir(t, node)
+		require.Equal(t, dirDataFirstCID, cidStr, "expected data-first directory CID from IPIP-550 fixtures")
+
+		block := node.IPFS("block", "get", cidStr).Stdout.Bytes()
+		require.Equal(t, dirDataFirstHex, hex.EncodeToString(block), "expected byte-exact data-first block from IPIP-550 fixtures")
+	})
+
+	t.Run("unixfs-v1-2025 keeps legacy Links-first order", func(t *testing.T) {
+		t.Parallel()
+		node := harness.NewT(t).NewNode().Init("--profile=unixfs-v1-2025")
+		node.StartDaemon()
+		defer node.StopDaemon()
+
+		cidStr := addFixtureDir(t, node)
+		require.Equal(t, dirLinksFirstCID, cidStr, "expected legacy links-first directory CID from IPIP-550 fixtures")
+	})
+}
+
 // TestDefaultMatchesExpectedProfile verifies that default ipfs add behavior
 // matches the expected profile (currently unixfs-v0-2015).
 func TestDefaultMatchesExpectedProfile(t *testing.T) {

test/dependencies/go.mod

@@ -136,7 +136,7 @@ require (
 	github.com/huin/goupnp v1.3.0 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
 	github.com/ipfs/bbloom v0.1.0 // indirect
-	github.com/ipfs/boxo v0.42.3-0.20260827015437-63cae36adc96 // indirect
+	github.com/ipfs/boxo v0.42.3-0.20260904132258-02026ddcf262 // indirect
 	github.com/ipfs/go-bitfield v1.1.0 // indirect
 	github.com/ipfs/go-block-format v0.2.4 // indirect
 	github.com/ipfs/go-cid v0.6.2 // indirect

test/dependencies/go.sum

@@ -299,8 +299,8 @@ github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2
 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
 github.com/ipfs/bbloom v0.1.0 h1:nIWwfIE3AaG7RCDQIsrUonGCOTp7qSXzxH7ab/ss964=
 github.com/ipfs/bbloom v0.1.0/go.mod h1:lDy3A3i6ndgEW2z1CaRFvDi5/ZTzgM1IxA/pkL7Wgts=
-github.com/ipfs/boxo v0.42.3-0.20260827015437-63cae36adc96 h1:8oZfkjCQcllUpAJFRskYHZbUiaMV6SqGCc+FJIuD93M=
-github.com/ipfs/boxo v0.42.3-0.20260827015437-63cae36adc96/go.mod h1:TCEs4l6Q6kfd1SUdYEzcxvC8JE1gc+6dObSs/6kOsb8=
+github.com/ipfs/boxo v0.42.3-0.20260904132258-02026ddcf262 h1:ccv4Wuz0qtHE52U0r4r2+NpnFbPYJp8riL6vTX6i3ic=
+github.com/ipfs/boxo v0.42.3-0.20260904132258-02026ddcf262/go.mod h1:TCEs4l6Q6kfd1SUdYEzcxvC8JE1gc+6dObSs/6kOsb8=
 github.com/ipfs/go-bitfield v1.1.0 h1:fh7FIo8bSwaJEh6DdTWbCeZ1eqOaOkKFI74SCnsWbGA=
 github.com/ipfs/go-bitfield v1.1.0/go.mod h1:paqf1wjq/D2BBmzfTVFlJQ9IlFOZpg422HL0HqsGWHU=
 github.com/ipfs/go-block-format v0.2.4 h1:pgsT9i8zB4YQkBIQRrBwqbQiXPogRCiQnfxd2bC4koI=