JSON for Hash now has to be Base16

Ericson2314 · Ericson2314 · commit 949a9fa1fda2 · 2025-11-10T16:12:33.000-05:00
Fix #14532. As discussed on the call today: 1. We'll stick with `format = "base16"` and `hash = "<hash>"`, not do `base16 = "<hash>"`, in order to be forward compatible with supporting more versioning formats. The motivation we discussed for someday *possibly* doing this is making it easier to write very slap-dash lang2nix tools that create (not consume) derivations with dynamic derivations. 2. We will remove support for non-base16 (and make that the default, not base64) in `Hash`, so this is strictly forward contingency, *not* yet something we support. (And also not something we have concrete plans to start supporting.)
diff --git a/doc/manual/source/protocols/json/hash.md b/doc/manual/source/protocols/json/hash.md
@@ -2,28 +2,16 @@
 
 ## Examples
 
-### SHA-256 with Base64 encoding
-
-```json
-{{#include schema/hash-v1/sha256-base64.json}}
-```
-
-### SHA-256 with Base16 (hexadecimal) encoding
+### SHA-256
 
 ```json
 {{#include schema/hash-v1/sha256-base16.json}}
 ```
 
-### SHA-256 with Nix32 encoding
-
-```json
-{{#include schema/hash-v1/sha256-nix32.json}}
-```
-
-### BLAKE3 with Base64 encoding
+### BLAKE3
 
 ```json
-{{#include schema/hash-v1/blake3-base64.json}}
+{{#include schema/hash-v1/blake3-base16.json}}
 ```
 
 <!-- need to convert YAML to JSON first
diff --git a/doc/manual/source/protocols/json/schema/hash-v1.yaml b/doc/manual/source/protocols/json/schema/hash-v1.yaml
@@ -12,18 +12,14 @@ properties:
   format:
     type: string
     enum:
-    - base64
-    - nix32
     - base16
-    - sri
     title: Hash format
     description: |
       The encoding format of the hash value.
 
-      - `base64` uses standard Base64 encoding [RFC 4648, section 4](https://datatracker.ietf.org/doc/html/rfc4648#section-4)
-      - `nix32` is Nix-specific base-32 encoding
-      - `base16` is lowercase hexadecimal
-      - `sri` is the [Subresource Integrity format](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity).
+      `base16` (lowercase hexadecimal) is the only format that is currently supported for JSON serialization.
+      This field exists primarily to reduce ambiguity about what the hash means.
+      It would also help us support other formats in the future, but there are no concrete plans to do so at this.
   hash:
     type: string
     title: Hash
diff --git a/src/json-schema-checks/meson.build b/src/json-schema-checks/meson.build
@@ -24,10 +24,8 @@ schemas = [
     'stem' : 'hash',
     'schema' : schema_dir / 'hash-v1.yaml',
     'files' : [
-      'sha256-base64.json',
       'sha256-base16.json',
-      'sha256-nix32.json',
-      'blake3-base64.json',
+      'blake3-base16.json',
     ],
   },
   {
diff --git a/src/libstore-tests/data/content-address/nar.json b/src/libstore-tests/data/content-address/nar.json
@@ -1,8 +1,8 @@
 {
   "hash": {
     "algorithm": "sha256",
-    "format": "base64",
-    "hash": "9vLqj0XYoFfJVmoz+ZR02i5camYE1zYSFlDicwxvsKM="
+    "format": "base16",
+    "hash": "f6f2ea8f45d8a057c9566a33f99474da2e5c6a6604d736121650e2730c6fb0a3"
   },
   "method": "nar"
 }
diff --git a/src/libstore-tests/data/content-address/text.json b/src/libstore-tests/data/content-address/text.json
@@ -1,8 +1,8 @@
 {
   "hash": {
     "algorithm": "sha256",
-    "format": "base64",
-    "hash": "8OTC92xYkW7CWPJGhRvqCR0U1CR6L8PhhpRGGxgW4Ts="
+    "format": "base16",
+    "hash": "f0e4c2f76c58916ec258f246851bea091d14d4247a2fc3e18694461b1816e13b"
   },
   "method": "text"
 }
diff --git a/src/libstore-tests/data/derivation/output-caFixedFlat.json b/src/libstore-tests/data/derivation/output-caFixedFlat.json
@@ -1,8 +1,8 @@
 {
   "hash": {
     "algorithm": "sha256",
-    "format": "base64",
-    "hash": "iUUXyRY8iW7DGirb0zwGgf1fRbLA7wimTJKgP7l/OQ8="
+    "format": "base16",
+    "hash": "894517c9163c896ec31a2adbd33c0681fd5f45b2c0ef08a64c92a03fb97f390f"
   },
   "method": "flat"
 }
diff --git a/src/libstore-tests/data/derivation/output-caFixedNAR.json b/src/libstore-tests/data/derivation/output-caFixedNAR.json
@@ -1,8 +1,8 @@
 {
   "hash": {
     "algorithm": "sha256",
-    "format": "base64",
-    "hash": "iUUXyRY8iW7DGirb0zwGgf1fRbLA7wimTJKgP7l/OQ8="
+    "format": "base16",
+    "hash": "894517c9163c896ec31a2adbd33c0681fd5f45b2c0ef08a64c92a03fb97f390f"
   },
   "method": "nar"
 }
diff --git a/src/libstore-tests/data/derivation/output-caFixedText.json b/src/libstore-tests/data/derivation/output-caFixedText.json
@@ -1,8 +1,8 @@
 {
   "hash": {
     "algorithm": "sha256",
-    "format": "base64",
-    "hash": "iUUXyRY8iW7DGirb0zwGgf1fRbLA7wimTJKgP7l/OQ8="
+    "format": "base16",
+    "hash": "894517c9163c896ec31a2adbd33c0681fd5f45b2c0ef08a64c92a03fb97f390f"
   },
   "method": "text"
 }
diff --git a/src/libstore-tests/data/nar-info/impure.json b/src/libstore-tests/data/nar-info/impure.json
@@ -2,23 +2,23 @@
   "ca": {
     "hash": {
       "algorithm": "sha256",
-      "format": "base64",
-      "hash": "EMIJ+giQ/gLIWoxmPKjno3zHZrxbGymgzGGyZvZBIdM="
+      "format": "base16",
+      "hash": "10c209fa0890fe02c85a8c663ca8e7a37cc766bc5b1b29a0cc61b266f64121d3"
     },
     "method": "nar"
   },
   "compression": "xz",
   "deriver": "/nix/store/g1w7hy3qg1w7hy3qg1w7hy3qg1w7hy3q-bar.drv",
   "downloadHash": {
     "algorithm": "sha256",
-    "format": "base64",
-    "hash": "FePFYIlMuycIXPZbWi7LGEiMmZSX9FMbaQenWBzm1Sc="
+    "format": "base16",
+    "hash": "15e3c560894cbb27085cf65b5a2ecb18488c999497f4531b6907a7581ce6d527"
   },
   "downloadSize": 4029176,
   "narHash": {
     "algorithm": "sha256",
-    "format": "base64",
-    "hash": "FePFYIlMuycIXPZbWi7LGEiMmZSX9FMbaQenWBzm1Sc="
+    "format": "base16",
+    "hash": "15e3c560894cbb27085cf65b5a2ecb18488c999497f4531b6907a7581ce6d527"
   },
   "narSize": 34878,
   "references": [
diff --git a/src/libstore-tests/data/nar-info/pure.json b/src/libstore-tests/data/nar-info/pure.json
@@ -2,15 +2,15 @@
   "ca": {
     "hash": {
       "algorithm": "sha256",
-      "format": "base64",
-      "hash": "EMIJ+giQ/gLIWoxmPKjno3zHZrxbGymgzGGyZvZBIdM="
+      "format": "base16",
+      "hash": "10c209fa0890fe02c85a8c663ca8e7a37cc766bc5b1b29a0cc61b266f64121d3"
     },
     "method": "nar"
   },
   "narHash": {
     "algorithm": "sha256",
-    "format": "base64",
-    "hash": "FePFYIlMuycIXPZbWi7LGEiMmZSX9FMbaQenWBzm1Sc="
+    "format": "base16",
+    "hash": "15e3c560894cbb27085cf65b5a2ecb18488c999497f4531b6907a7581ce6d527"
   },
   "narSize": 34878,
   "references": [
diff --git a/src/libstore-tests/data/path-info/empty_impure.json b/src/libstore-tests/data/path-info/empty_impure.json
@@ -3,8 +3,8 @@
   "deriver": null,
   "narHash": {
     "algorithm": "sha256",
-    "format": "base64",
-    "hash": "FePFYIlMuycIXPZbWi7LGEiMmZSX9FMbaQenWBzm1Sc="
+    "format": "base16",
+    "hash": "15e3c560894cbb27085cf65b5a2ecb18488c999497f4531b6907a7581ce6d527"
   },
   "narSize": 0,
   "references": [],
diff --git a/src/libstore-tests/data/path-info/empty_pure.json b/src/libstore-tests/data/path-info/empty_pure.json
@@ -2,8 +2,8 @@
   "ca": null,
   "narHash": {
     "algorithm": "sha256",
-    "format": "base64",
-    "hash": "FePFYIlMuycIXPZbWi7LGEiMmZSX9FMbaQenWBzm1Sc="
+    "format": "base16",
+    "hash": "15e3c560894cbb27085cf65b5a2ecb18488c999497f4531b6907a7581ce6d527"
   },
   "narSize": 0,
   "references": [],
diff --git a/src/libstore-tests/data/path-info/impure.json b/src/libstore-tests/data/path-info/impure.json
@@ -2,16 +2,16 @@
   "ca": {
     "hash": {
       "algorithm": "sha256",
-      "format": "base64",
-      "hash": "EMIJ+giQ/gLIWoxmPKjno3zHZrxbGymgzGGyZvZBIdM="
+      "format": "base16",
+      "hash": "10c209fa0890fe02c85a8c663ca8e7a37cc766bc5b1b29a0cc61b266f64121d3"
     },
     "method": "nar"
   },
   "deriver": "/nix/store/g1w7hy3qg1w7hy3qg1w7hy3qg1w7hy3q-bar.drv",
   "narHash": {
     "algorithm": "sha256",
-    "format": "base64",
-    "hash": "FePFYIlMuycIXPZbWi7LGEiMmZSX9FMbaQenWBzm1Sc="
+    "format": "base16",
+    "hash": "15e3c560894cbb27085cf65b5a2ecb18488c999497f4531b6907a7581ce6d527"
   },
   "narSize": 34878,
   "references": [
diff --git a/src/libstore-tests/data/path-info/pure.json b/src/libstore-tests/data/path-info/pure.json
@@ -2,15 +2,15 @@
   "ca": {
     "hash": {
       "algorithm": "sha256",
-      "format": "base64",
-      "hash": "EMIJ+giQ/gLIWoxmPKjno3zHZrxbGymgzGGyZvZBIdM="
+      "format": "base16",
+      "hash": "10c209fa0890fe02c85a8c663ca8e7a37cc766bc5b1b29a0cc61b266f64121d3"
     },
     "method": "nar"
   },
   "narHash": {
     "algorithm": "sha256",
-    "format": "base64",
-    "hash": "FePFYIlMuycIXPZbWi7LGEiMmZSX9FMbaQenWBzm1Sc="
+    "format": "base16",
+    "hash": "15e3c560894cbb27085cf65b5a2ecb18488c999497f4531b6907a7581ce6d527"
   },
   "narSize": 34878,
   "references": [
diff --git a/src/libutil-tests/data/hash/blake3-base16.json b/src/libutil-tests/data/hash/blake3-base16.json
@@ -0,0 +1,5 @@
+{
+  "algorithm": "blake3",
+  "format": "base16",
+  "hash": "9e70ee1449965fb62d049040a1ed06ec377430da6ec13173e7c4fffcd28be980"
+}
diff --git a/src/libutil-tests/data/hash/blake3-base64.json b/src/libutil-tests/data/hash/blake3-base64.json
diff --git a/src/libutil-tests/data/hash/simple.json b/src/libutil-tests/data/hash/simple.json
@@ -1,5 +1,5 @@
 {
   "algorithm": "sha256",
-  "format": "base64",
-  "hash": "8OTC92xYkW7CWPJGhRvqCR0U1CR6L8PhhpRGGxgW4Ts="
+  "format": "base16",
+  "hash": "f0e4c2f76c58916ec258f246851bea091d14d4247a2fc3e18694461b1816e13b"
 }
diff --git a/src/libutil-tests/hash.cc b/src/libutil-tests/hash.cc
@@ -215,9 +215,8 @@ struct HashJsonTest : virtual HashTest,
                       ::testing::WithParamInterface<std::pair<std::string_view, Hash>>
 {};
 
-struct HashJsonParseOnlyTest : virtual HashTest,
-                               JsonCharacterizationTest<Hash>,
-                               ::testing::WithParamInterface<std::pair<std::string_view, Hash>>
+struct HashJsonParseFailureTest : virtual HashTest,
+                                   ::testing::WithParamInterface<std::string_view>
 {};
 
 struct BLAKE3HashJsonTest : virtual HashTest,
@@ -238,10 +237,12 @@ TEST_P(HashJsonTest, to_json)
     writeJsonTest(name, value);
 }
 
-TEST_P(HashJsonParseOnlyTest, from_json)
+TEST_P(HashJsonParseFailureTest, from_json)
 {
-    auto & [name, expected] = GetParam();
-    readJsonTest(name, expected);
+    auto & name = GetParam();
+    auto path = goldenMaster(Path{name} + ".json");
+    auto encoded = json::parse(readFile(path));
+    ASSERT_THROW(nlohmann::adl_serializer<Hash>::from_json(encoded), Error);
 }
 
 TEST_P(BLAKE3HashJsonTest, from_json)
@@ -256,8 +257,8 @@ TEST_P(BLAKE3HashJsonTest, to_json)
     writeJsonTest(name, expected);
 }
 
-// Round-trip tests (from_json + to_json) for base64 format only
-// (to_json always outputs base64)
+// Round-trip tests (from_json + to_json) for base16 format only
+// (to_json always outputs base16)
 INSTANTIATE_TEST_SUITE_P(
     HashJSON,
     HashJsonTest,
@@ -267,31 +268,25 @@ INSTANTIATE_TEST_SUITE_P(
             hashString(HashAlgorithm::SHA256, "asdf"),
         },
         std::pair{
-            "sha256-base64",
+            "sha256-base16",
             hashString(HashAlgorithm::SHA256, "asdf"),
         }));
 
-// Parse-only tests for non-base64 formats
-// These verify C++ can deserialize other formats correctly
+// Failure tests for unsupported formats (base64, nix32, sri)
+// These verify that non-base16 formats are rejected
 INSTANTIATE_TEST_SUITE_P(
-    HashJSONParseOnly,
-    HashJsonParseOnlyTest,
+    HashJSONParseFailure,
+    HashJsonParseFailureTest,
     ::testing::Values(
-        std::pair{
-            "sha256-base16",
-            hashString(HashAlgorithm::SHA256, "asdf"),
-        },
-        std::pair{
-            "sha256-nix32",
-            hashString(HashAlgorithm::SHA256, "asdf"),
-        }));
+        "sha256-base64",
+        "sha256-nix32"));
 
-INSTANTIATE_TEST_SUITE_P(BLAKE3HashJSONParseOnly, BLAKE3HashJsonTest, ([] {
+INSTANTIATE_TEST_SUITE_P(BLAKE3HashJSON, BLAKE3HashJsonTest, ([] {
                              ExperimentalFeatureSettings mockXpSettings;
                              mockXpSettings.set("experimental-features", "blake3-hashes");
                              return ::testing::Values(
                                  std::pair{
-                                     "blake3-base64",
+                                     "blake3-base16",
                                      hashString(HashAlgorithm::BLAKE3, "asdf", mockXpSettings),
                                  });
                          }()));
diff --git a/src/libutil/hash.cc b/src/libutil/hash.cc
@@ -508,17 +508,24 @@ Hash adl_serializer<Hash>::from_json(const json & json, const ExperimentalFeatur
 {
     auto & obj = getObject(json);
     auto algo = parseHashAlgo(getString(valueAt(obj, "algorithm")), xpSettings);
-    auto format = parseHashFormat(getString(valueAt(obj, "format")));
+    auto formatStr = getString(valueAt(obj, "format"));
+    auto format = parseHashFormat(formatStr);
+
+    // Only base16 format is supported for JSON serialization
+    if (format != HashFormat::Base16) {
+        throw Error("hash format '%s' is not supported in JSON; only 'base16' is currently supported", formatStr);
+    }
+
     auto & hashS = getString(valueAt(obj, "hash"));
     return Hash::parseExplicitFormatUnprefixed(hashS, algo, format, xpSettings);
 }
 
 void adl_serializer<Hash>::to_json(json & json, const Hash & hash)
 {
     json = {
-        {"format", printHashFormat(HashFormat::Base64)},
+        {"format", printHashFormat(HashFormat::Base16)},
         {"algorithm", printHashAlgo(hash.algo)},
-        {"hash", hash.to_string(HashFormat::Base64, false)},
+        {"hash", hash.to_string(HashFormat::Base16, false)},
     };
 }
 
diff --git a/tests/functional/fixed.sh b/tests/functional/fixed.sh
@@ -15,13 +15,12 @@ nix-build fixed.nix -A bad --no-out-link && fail "should fail"
 # a side-effect.
 [[ -e $path ]]
 nix path-info --json "$path" | jq -e \
-    --arg hash "$(nix hash convert --to base64 "md5:8ddd8be4b179a529afa5f2ffae4b9858")" \
     '.[].ca == {
         method: "flat",
         hash: {
             algorithm: "md5",
-            format: "base64",
-            hash: $hash
+            format: "base16",
+            hash: "8ddd8be4b179a529afa5f2ffae4b9858"
         },
     }'
 
diff --git a/tests/functional/git-hashing/simple-common.sh b/tests/functional/git-hashing/simple-common.sh
@@ -49,12 +49,12 @@ try2 () {
 
     nix path-info --json "$path" | jq -e \
         --arg algo "$hashAlgo" \
-        --arg hash "$(nix hash convert --to base64 "$hashAlgo:$hashFromGit")" \
+        --arg hash "$hashFromGit" \
         '.[].ca == {
             method: "git",
             hash: {
                 algorithm: $algo,
-                format: "base64",
+                format: "base16",
                 hash: $hash
             },
         }'
diff --git a/tests/functional/path-info.sh b/tests/functional/path-info.sh

Original file line number	Diff line number	Diff line change
`@@ -1,8 +1,8 @@`
`1`	`1`	`{`
`2`	`2`	`"hash": {`
`3`	`3`	`"algorithm": "sha256",`
`4`		`- "format": "base64",`
`5`		`- "hash": "9vLqj0XYoFfJVmoz+ZR02i5camYE1zYSFlDicwxvsKM="`
	`4`	`+ "format": "base16",`
	`5`	`+ "hash": "f6f2ea8f45d8a057c9566a33f99474da2e5c6a6604d736121650e2730c6fb0a3"`
`6`	`6`	`},`
`7`	`7`	`"method": "nar"`
`8`	`8`	`}`