release: nix flake with tag-pinned hashes, reproducible tarballs (milestone 40)

flake.nix fetches the release tarballs and carries their SRI hashes in a generated block. The cut tool builds the release locally with the toolchain gates.yml pins, in a normalized nine-variable environment, writes the hashes into flake.nix, and commits it with build.zig.zon as the single bump commit. The package job verifies the pins on the bump commit and the publish job verifies them again on the tag, before anything is uploaded.

The tarballs are written by dist_stage (std.tar.Writer, flate gzip) instead of the runner's tar and gzip, and -ffile-prefix-map keeps checkout paths out of the C objects; two checkouts at different absolute paths produce byte-identical archives. nxdns version, /api/version and the admin footer report the version only: the bump commit cannot know its own sha.

.gitea/workflows/gates.yml

@@ -44,6 +44,11 @@ env:
   # Exact patch, not a floating "24" (milestone-14 ruling 12): the bundled npm
   # and the emitted bundle change under a floating major.
   NODE_VERSION: "24.19.0"
+  # The npm the cut runs and the npm CI runs must be one version: npm writes the
+  # admin bundle whose bytes the release hashes are pinned to before CI ever
+  # rebuilds them. setup-node installs the npm that ships with the node above,
+  # so this pin is asserted, not installed.
+  NPM_VERSION: "11.17.0"
   # There is deliberately no CI_VERSION literal here. Ruling 2 allows the
   # version to exist in the tag and in build.zig.zon and nowhere else, and
   # ruling 5 makes verify-dist fail when the version under build disagrees with
@@ -126,9 +131,25 @@ jobs:
           cache: npm
           cache-dependency-path: admin/package-lock.json
 
+      # The bundle is a release input whose hash is pinned before this run
+      # exists, so a runner on a different node or npm must fail here rather
+      # than emit different bytes further down.
+      - name: Assert the pinned Node and npm
+        run: |
+          test "$(node --version)" = "v${NODE_VERSION:?}"
+          test "$(npm --version)" = "${NPM_VERSION:?}"
+          test ! -e /nonexistent/npmrc-user
+          test ! -e /nonexistent/npmrc-global
+
+      # `npm ci` and `npm run build` run under the same normalized environment
+      # the cut builds the bundle in: exactly nine variables, a file mode from
+      # the umask, a C locale, UTC, and a zero build timestamp. Each of those
+      # can move the bytes the release hashes cover. The format, lint,
+      # typecheck and test steps below stay ambient on purpose: only the
+      # bundle's bytes are pinned, and those checks emit nothing that ships.
       - name: Install dependencies
         working-directory: admin
-        run: npm ci
+        run: env -i PATH="$PATH" HOME="$HOME" LC_ALL=C LANG=C TZ=UTC SOURCE_DATE_EPOCH=0 CI=true npm_config_userconfig=/nonexistent/npmrc-user npm_config_globalconfig=/nonexistent/npmrc-global sh -c 'umask 022 && npm ci'
 
       - name: Check formatting
         working-directory: admin
@@ -148,7 +169,7 @@ jobs:
 
       - name: Build
         working-directory: admin
-        run: npm run build
+        run: env -i PATH="$PATH" HOME="$HOME" LC_ALL=C LANG=C TZ=UTC SOURCE_DATE_EPOCH=0 CI=true npm_config_userconfig=/nonexistent/npmrc-user npm_config_globalconfig=/nonexistent/npmrc-global sh -c 'umask 022 && npm run build'
 
       # The licence inventory has to cover every package whose bytes ship, and
       # the lockfile does not answer that question: it lists what could be
@@ -191,7 +212,12 @@ jobs:
       version: ${{ steps.zon-version.outputs.version }}
 
     steps:
+      # Depth 2, not the default 1: the pin check at the foot of this job runs
+      # only on the commit that changed build.zig.zon, and answering that
+      # question needs HEAD's first parent. No other job here reads a parent.
       - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+        with:
+          fetch-depth: 2
 
       - name: Set up Zig
         uses: mlugg/setup-zig@d1434d08867e3ee9daa34448df10607b98908d29 # v2.2.1
@@ -243,7 +269,6 @@ jobs:
           set -euo pipefail
           zig build dist \
             -Dversion-string="$CI_VERSION" \
-            -Dgit-commit="$GITHUB_SHA" \
             -Dadmin-dist=admin-dist-ci \
             -Doptimize=ReleaseSafe
 
@@ -259,10 +284,55 @@ jobs:
           set -euo pipefail
           zig build verify-dist \
             -Dversion-string="$CI_VERSION" \
-            -Dgit-commit="$GITHUB_SHA" \
             -Dadmin-dist=admin-dist-ci \
             -Doptimize=ReleaseSafe
 
+      # The cut writes the release hashes into flake.nix before it makes the
+      # bump commit, so the bump commit is the one commit whose pins nothing has
+      # verified yet — the tag's own run (release.yml) is the next chance, and by
+      # then the tag is public. This step is that first chance.
+      #
+      # It is deliberately NOT part of verify-dist. Every other commit on master
+      # builds the same build.zig.zon version from a different tree, so its bytes
+      # legitimately differ from the pins and a check there would fail the whole
+      # branch. The commit is identified by the version it declares, not by its
+      # message: a message is a string anyone can write, and the pins follow
+      # the manifest.
+      #
+      # A root commit has no first parent. That is an error rather than a skip:
+      # this repository has history, so `HEAD^` failing means the checkout is
+      # shallower than the depth 2 declared above and the question went
+      # unanswered, which must never read as "nothing to check".
+      #
+      # The predicate is the declared VERSION, not the file: build.zig.zon also
+      # carries the dependency pins, and updating a sqlite or mbedTLS hash
+      # changes the file without cutting a release. Such a commit builds the
+      # same version from a different tree, so its bytes are not the pinned
+      # ones and this check would fail it.
+      #
+      # HEAD's version is CI_VERSION, parsed out of the working tree by the
+      # container gate tool. The parent's is read with `sed`, because that tool
+      # reads `build.zig.zon` at a fixed path and has no mode for a blob out of
+      # history. An empty parse is a failure, not a bump: it means the manifest
+      # moved and the question went unanswered.
+      - name: Verify the flake pins on a version bump
+        run: |
+          set -euo pipefail
+          parent="$(git rev-parse --verify HEAD^)"
+          parent_version="$(git show "$parent":build.zig.zon | sed -n 's/^[[:space:]]*\.version = "\([^"]*\)".*/\1/p')"
+          if [ -z "$parent_version" ]; then
+            echo "cannot read .version out of $parent:build.zig.zon" >&2
+            exit 1
+          fi
+          if [ "$parent_version" != "$CI_VERSION" ]; then
+            zig build verify-pins \
+              -Dversion-string="$CI_VERSION" \
+              -Dadmin-dist=admin-dist-ci \
+              -Doptimize=ReleaseSafe
+          else
+            echo "skipped: $GITHUB_SHA declares version $CI_VERSION and $parent already declared $parent_version, so it is not a version bump and its bytes are not the ones flake.nix pins"
+          fi
+
       # deploy/docker/Dockerfile copies both of these trees and nothing else
       # out of zig-out/dist: the binary comes from dist/bin/<triple>/, and
       # /LICENSE and /THIRD-PARTY-NOTICES come from the matching dist/stage/