FIPS 140-3 validated password hashing — ADR, packaging, and build pipeline

.dockerignore

@@ -3,3 +3,10 @@ apps/frontend/tests
 apps/backend/test
 test
 **/node_modules
+
+# VitePress documentation site (ADR-005 §2.1) — the app image builds from
+# explicit COPY paths, so docs/ never entered it implicitly; this makes the
+# exclusion explicit. NOTE: shipping the BUILT docs inside the app image for
+# offline/airgapped use (Aaron, 2026-08-11) is a separate packaging change and
+# will need this entry narrowed (source + node_modules out, built output in).
+docs

.git-blame-ignore-revs

@@ -0,0 +1,13 @@
+# Commits that changed formatting only, and should be skipped by `git blame`.
+#
+# Enable locally (once per clone):
+#   git config blame.ignoreRevsFile .git-blame-ignore-revs
+#
+# GitHub honours this file automatically in its blame view.
+#
+# Add the full 40-character SHA of a pure-formatting commit below, one per line,
+# with a comment naming it. Only add commits that changed NOTHING but formatting
+# — if a commit mixes formatting with behavior, blame must not skip it.
+
+# (none yet — the initial `yarn format` adoption commit belongs here once the
+#  repo-wide Prettier reformat lands)

.github/workflows/build-rpm.yml

@@ -0,0 +1,212 @@
+name: Build RPM
+
+# One workflow for both purposes, following redis/memtier_benchmark:
+# every PR and master push proves the RPM still builds and installs, and a
+# published release additionally uploads the artifacts. Publishing steps are
+# gated on the event rather than split into a second workflow, so the thing
+# that ships is the thing CI exercised.
+
+on:
+  pull_request:
+    paths:
+      - 'packaging/**'
+      - 'VERSION'
+      - '.github/workflows/build-rpm.yml'
+  push:
+    branches: [master]
+    paths:
+      - 'packaging/**'
+      - 'VERSION'
+      - '.github/workflows/build-rpm.yml'
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      heimdall_cli_ref:
+        description: 'heimdall-cli ref to build against (tag, branch, or SHA)'
+        required: false
+        default: 'main'
+
+env:
+  # Release builds must pin a tag. Everything else tracks main.
+  # This value is what the RPM records as the CLI it shipped.
+  HEIMDALL_CLI_REF: ${{ inputs.heimdall_cli_ref || 'main' }}
+
+jobs:
+  build:
+    name: ${{ matrix.distro }} / ${{ matrix.arch }}
+    runs-on: ${{ matrix.runner }}
+    container: ${{ matrix.image }}
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - distro: el8
+            image: rockylinux:8
+            arch: x86_64
+            runner: ubuntu-latest
+          - distro: el9
+            image: rockylinux:9
+            arch: x86_64
+            runner: ubuntu-latest
+          # Native ARM runners — free for public repositories, and roughly
+          # 5-10x faster than QEMU emulation for a Node + Go build. The Go CLI
+          # is compiled natively here rather than cross-compiled.
+          - distro: el8
+            image: rockylinux:8
+            arch: aarch64
+            runner: ubuntu-24.04-arm
+          - distro: el9
+            image: rockylinux:9
+            arch: aarch64
+            runner: ubuntu-24.04-arm
+
+    steps:
+      # A bare Rocky container has neither git nor make. actions/checkout needs
+      # git, and every subsequent step goes through the Makefile — including
+      # `make deps`, which is what installs the real build dependencies. Both
+      # have to be bootstrapped here or `make deps` cannot run itself.
+      - name: Bootstrap git and make
+        run: |
+          dnf install -y git make
+          git --version
+          make --version | head -1
+
+      - uses: actions/checkout@v6
+        with:
+          # Full history and tags: `make sources` archives the tag matching the
+          # VERSION file. A shallow clone has no tags and the build would fail.
+          fetch-depth: 0
+          fetch-tags: true
+
+      - name: Mark workspace safe
+        run: git config --global --add safe.directory "$GITHUB_WORKSPACE"
+
+      - name: Install build dependencies
+        working-directory: packaging/rpm
+        run: make deps
+
+      - name: Install Go (for the heimdall-cli build)
+        run: dnf install -y golang
+
+      - name: Verify spec and repository versions agree
+        working-directory: packaging/rpm
+        run: make check-version
+
+      # Releases build from the tag matching VERSION. CI builds from HEAD,
+      # because on a feature branch the tag for an in-progress version does not
+      # exist yet. DEV=1 makes that explicit rather than silently producing an
+      # RPM that claims to be a release.
+      - name: Build RPM
+        working-directory: packaging/rpm
+        env:
+          HEIMDALL_CLI_REF: ${{ env.HEIMDALL_CLI_REF }}
+        run: |
+          if [ "${GITHUB_EVENT_NAME}" = "release" ]; then
+            make rpm
+          else
+            make rpm DEV=1
+          fi
+
+      - name: Lint the built packages (advisory)
+        working-directory: packaging/rpm
+        continue-on-error: true
+        run: make lint-rpm
+
+      - name: Record what was built
+        working-directory: packaging/rpm
+        run: |
+          find rpmbuild/RPMS rpmbuild/SRPMS -name '*.rpm' -printf '%f\n' | sort
+          echo "heimdall-cli ref: ${HEIMDALL_CLI_REF}"
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: rpm-${{ matrix.distro }}-${{ matrix.arch }}
+          path: |
+            packaging/rpm/rpmbuild/RPMS/**/*.rpm
+            packaging/rpm/rpmbuild/SRPMS/*.rpm
+          retention-days: 7
+          if-no-files-found: error
+
+  # The highest-value check: install into a clean container with NO build
+  # dependencies pre-installed, so a missing Requires: fails here rather than on
+  # a customer's host. Verifies %files claims via rpm -ql.
+  smoke-test:
+    name: install ${{ matrix.distro }} / ${{ matrix.arch }}
+    needs: build
+    runs-on: ${{ matrix.runner }}
+    container: ${{ matrix.image }}
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - {distro: el8, image: rockylinux:8, arch: x86_64, runner: ubuntu-latest}
+          - {distro: el9, image: rockylinux:9, arch: x86_64, runner: ubuntu-latest}
+          - {distro: el8, image: rockylinux:8, arch: aarch64, runner: ubuntu-24.04-arm}
+          - {distro: el9, image: rockylinux:9, arch: aarch64, runner: ubuntu-24.04-arm}
+
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: rpm-${{ matrix.distro }}-${{ matrix.arch }}
+          path: rpms
+
+      - name: Install the package and its dependencies
+        run: |
+          dnf install -y epel-release || true
+          rpm_file=$(find rpms -name "heimdall-server-*.${{ matrix.arch }}.rpm" | head -1)
+          test -n "$rpm_file" || { echo "::error::no binary RPM found"; exit 1; }
+          echo "Installing $rpm_file"
+          dnf install -y "$rpm_file"
+
+      - name: Verify the package contents match its manifest
+        run: |
+          rpm -q heimdall-server
+          rpm -V heimdall-server || true   # config file changes are expected
+          echo "--- files ---"
+          rpm -ql heimdall-server | head -40
+          echo "--- heimdall-cli is present and reports provenance ---"
+          test -x /usr/bin/heimdall-cli
+          /usr/bin/heimdall-cli --version
+
+      - name: Verify the unit file is valid
+        run: |
+          dnf install -y systemd
+          systemd-analyze verify /usr/lib/systemd/system/heimdall-server.service || true
+
+  publish:
+    name: Attach RPMs to the release
+    needs: [build, smoke-test]
+    if: github.event_name == 'release'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write      # upload release assets
+      id-token: write      # build provenance attestation
+      attestations: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          pattern: rpm-*
+          path: rpms
+          merge-multiple: true
+
+      - name: List artifacts
+        run: find rpms -name '*.rpm' -printf '%f\n' | sort
+
+      # The modern equivalent of GPG-signing in CI: a signed, verifiable
+      # statement of what built these artifacts and from where. Same
+      # supply-chain story as npm provenance, without a release key in secrets.
+      - uses: actions/attest-build-provenance@v4
+        with:
+          subject-path: 'rpms/**/*.rpm'
+
+      # Pinned to a commit SHA: this is a third-party action holding
+      # contents: write, and a mutable tag can be repointed at any time.
+      - uses: softprops/action-gh-release@3d0d9888cb7fd7b750713d6e236d1fcb99157228  # v3.0.2
+        with:
+          files: rpms/**/*.rpm
+          fail_on_unmatched_files: true

.github/workflows/hdfconverter-tests.yml

@@ -52,6 +52,11 @@ jobs:
       - name: Start Mock Sonarqube Server
         run: yarn run cypress-test mock-json &
 
+      - name: Validate there are no changes between the Tailwind source and the generated assets
+        run: |
+          yarn hdf-converters prebuild
+          yarn hdf-converters validate-generated
+
       - name: Run unit tests
         run: yarn hdf-converters test:ci
         env:

.github/workflows/push-to-npm.yml

@@ -33,6 +33,23 @@ jobs:
       - name: Pack all items that are published as packages
         run: yarn pack:all
 
+      # The published packages rewrite "main" from src/index.ts to lib/index.js
+      # in prepack and restore it in postpack. Yarn 1 has no try/finally around
+      # those lifecycle scripts, so a failed pack skips the restore and leaves a
+      # mutated manifest behind. Running --parallel across three packages means
+      # one failure can strand another package's manifest. Fail loudly here
+      # rather than publish a tarball built from a corrupted tree.
+      - name: Verify manifests were restored after pack
+        run: |
+          if ! git diff --exit-code -- '*package.json'; then
+            echo "::error::package.json was left modified after pack:all — a prepack rewrite was not restored by postpack. Do not publish from this tree."
+            exit 1
+          fi
+          if git ls-files --others --exclude-standard | grep -q 'package.json.orig'; then
+            echo "::error::A stray package.json.orig remains after pack:all — postpack did not run."
+            exit 1
+          fi
+
       - name: Publish Heimdall Lite to NPM
         if: always()
         run: npx -y npm@latest publish --access public apps/frontend/mitre-heimdall-lite*.tgz

.gitignore

@@ -72,3 +72,25 @@ certs/*.pem
 
 # Database Content
 data/*
+
+# prepack/postpack manifest backup.
+# The published packages rewrite "main" from src/index.ts to lib/index.js at
+# pack time (npm has never supported publishConfig manifest overrides, and
+# npm 13 will hard-error on them, so the rewrite is the only option).
+# Yarn 1's pack has no try/finally around the lifecycle scripts, so a failed
+# pack skips postpack and strands this file next to a mutated package.json.
+package.json.orig
+
+# VitePress documentation site (ADR-005). docs/ is deliberately OUTSIDE the yarn
+# workspaces globs ("apps/*", "libs/*", "test"), so it has its own package.json
+# and yarn.lock and root `yarn install` never sees it. Bare `node_modules` above
+# already covers docs/node_modules; VitePress's cache and build output do not.
+docs/node_modules
+docs/.vitepress/cache
+docs/.vitepress/dist
+
+# Playwright MCP writes console logs and page snapshots into the repository as
+# it drives the browser — one directory per session, created unconditionally
+# and never cleaned up. Live-test evidence belongs in card notes, not in the
+# tree, so this is ignored rather than committed.
+.playwright-mcp/

.prettierignore

@@ -0,0 +1,33 @@
+# Prettier owns formatting for SOURCE. Everything below is either build output,
+# third-party/generated content, or fixture data that is compared byte-for-byte
+# by tests — reformatting any of it changes meaning, not just appearance.
+
+# Build output and dependencies
+**/dist
+**/lib
+**/node_modules
+yarn.lock
+package-lock.json
+
+# Test fixture corpora. 365 MB across 249 files; the mapper specs read these
+# with readFileSync/JSON.parse and compare results against them, so reformatting
+# would both take enormous time and risk changing what the tests assert.
+libs/hdf-converters/sample_jsons/
+
+# Generated assets guarded by the `validate-generated` script, which fails the
+# build if their committed bytes change (tailwind style.css + the embedded
+# strings derived from it).
+libs/hdf-converters/data/
+
+# Generated sources — same set the ESLint config ignores, kept in sync.
+libs/inspecjs/src/generated_parsers/
+libs/hdf-converters/src/ckl-mapper/jsonixMapping.ts
+
+# Static data tables, not code: giant literal maps with no logic. Formatting
+# them produces enormous diffs and zero benefit.
+**/*MappingData.ts
+apps/frontend/src/utilities/cci_util.ts
+
+# The documentation site is an isolated project (ADR-005 §2.1) with its own
+# package.json and toolchain; it is not formatted by the application's tooling.
+docs/

.prettierrc.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://json.schemastore.org/prettierrc",
+  "singleQuote": true
+}