From 30cd9063ab93ff00d677936dc7b1f3f2d29de947 Mon Sep 17 00:00:00 2001
From: Ron McCorkle <31546545+mack42@users.noreply.github.com>
Date: Sun, 19 Jul 2026 19:52:23 +0000
Subject: [PATCH 1/3] feat(release): sign and attest update artifacts

---
 .github/workflows/build-iso.yml | 81 ++++++++++++++++++++++++++++++++
 aifw-api/src/updates.rs         |  1 +
 aifw-core/src/updater.rs        | 83 ++++++++++++++++++++++++++-------
 3 files changed, 147 insertions(+), 18 deletions(-)

diff --git a/.github/workflows/build-iso.yml b/.github/workflows/build-iso.yml
index d6181cff..4606808d 100644
--- a/.github/workflows/build-iso.yml
+++ b/.github/workflows/build-iso.yml
@@ -12,9 +12,12 @@ on:
 
 permissions:
   contents: write
+  id-token: write
+  attestations: write
 
 env:
   FREEBSD_VERSION: "15.0"
+  MINISIGN_PUBLIC_KEY: ${{ vars.MINISIGN_PUBLIC_KEY }}
 
 jobs:
   build-ui:
@@ -85,6 +88,10 @@ jobs:
 
             echo "=== Building AiFw binaries ==="
             cd /home/runner/work/AiFw/AiFw
+            test -n "$MINISIGN_PUBLIC_KEY" || { echo "MINISIGN_PUBLIC_KEY repository variable is required" >&2; exit 1; }
+            mkdir -p freebsd/overlay/usr/local/etc/aifw
+            printf '%s\n' "$MINISIGN_PUBLIC_KEY" > freebsd/overlay/usr/local/etc/aifw/update-signing.pub
+            chmod 644 freebsd/overlay/usr/local/etc/aifw/update-signing.pub
             cargo build --release
 
             echo "=== Validating sudoers content (visudo -cf, #204) ==="
@@ -195,6 +202,47 @@ jobs:
             mkdir -p /home/runner/work/AiFw/AiFw/output
             cp /usr/obj/aifw-iso/output/* /home/runner/work/AiFw/AiFw/output/
 
+      - name: Generate ISO CycloneDX SBOM
+        uses: anchore/sbom-action@f8bdd1d8ac5e901a77a92f111440fdb1b593736b # v0.20.6
+        with:
+          path: output/aifw-*.iso.xz
+          format: cyclonedx-json
+          output-file: output/aifw-iso.cdx.json
+          upload-artifact: false
+
+      - name: Generate IMG CycloneDX SBOM
+        uses: anchore/sbom-action@f8bdd1d8ac5e901a77a92f111440fdb1b593736b # v0.20.6
+        with:
+          path: output/aifw-*.img.xz
+          format: cyclonedx-json
+          output-file: output/aifw-img.cdx.json
+          upload-artifact: false
+
+      - name: Generate update CycloneDX SBOM
+        uses: anchore/sbom-action@f8bdd1d8ac5e901a77a92f111440fdb1b593736b # v0.20.6
+        with:
+          path: output/aifw-update-*.tar.xz
+          format: cyclonedx-json
+          output-file: output/aifw-update.cdx.json
+          upload-artifact: false
+
+      - name: Sign update checksums
+        env:
+          MINISIGN_SECRET_KEY: ${{ secrets.MINISIGN_SECRET_KEY }}
+          MINISIGN_PASSWORD: ${{ secrets.MINISIGN_PASSWORD }}
+        run: |
+          set -euo pipefail
+          sudo apt-get update
+          sudo apt-get install -y minisign
+          key_file="$RUNNER_TEMP/minisign.key"
+          trap 'rm -f "$key_file"' EXIT
+          printf '%s' "$MINISIGN_SECRET_KEY" > "$key_file"
+          chmod 600 "$key_file"
+          for checksum in output/aifw-update-*.tar.xz.sha256; do
+            [ -f "$checksum" ] || continue
+            minisign -S -s "$key_file" -m "$checksum" -x "${checksum}.minisig"
+          done
+
       - name: Upload ISO artifact
         uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
         with:
@@ -263,6 +311,22 @@ jobs:
           name: boot-smoke-artifacts
           path: smoke-artifacts/
           retention-days: 7
+      - name: Upload SBOMs and signatures
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: supply-chain
+          path: |
+            output/*.cdx.json
+            output/*.minisig
+          retention-days: 5
+
+      - name: Attest release artifacts
+        uses: actions/attest-build-provenance@e8998f949152b193b063cb0ec769d69d929409be # v2.4.0
+        with:
+          subject-path: |
+            output/aifw-*.iso.xz
+            output/aifw-*.img.xz
+            output/aifw-update-*.tar.xz
 
   release:
     name: Create GitHub Release
@@ -296,6 +360,23 @@ jobs:
           name: components
           path: release-assets/
 
+      - name: Download supply-chain assets
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          name: supply-chain
+          path: release-assets/
+
+      - name: Verify update signatures before publication
+        env:
+          MINISIGN_PUBLIC_KEY: ${{ vars.MINISIGN_PUBLIC_KEY }}
+        run: |
+          set -euo pipefail
+          sudo apt-get update
+          sudo apt-get install -y minisign
+          for checksum in release-assets/aifw-update-*.tar.xz.sha256; do
+            minisign -Vm "$checksum" -x "${checksum}.minisig" -P "$MINISIGN_PUBLIC_KEY"
+          done
+
       - name: Extract version from tag
         id: version
         run: if [ -n "${{ inputs.version }}" ]; then
diff --git a/aifw-api/src/updates.rs b/aifw-api/src/updates.rs
index d0605ab7..d7810803 100644
--- a/aifw-api/src/updates.rs
+++ b/aifw-api/src/updates.rs
@@ -565,6 +565,7 @@ pub async fn aifw_update_status(
         published_at: String::new(),
         tarball_url: None,
         checksum_url: None,
+        checksum_signature_url: None,
         has_backup: std::path::Path::new("/usr/local/share/aifw/backup/version").exists(),
         backup_version: tokio::fs::read_to_string("/usr/local/share/aifw/backup/version")
             .await
diff --git a/aifw-core/src/updater.rs b/aifw-core/src/updater.rs
index 082c484e..75a2ed15 100644
--- a/aifw-core/src/updater.rs
+++ b/aifw-core/src/updater.rs
@@ -251,6 +251,9 @@ pub struct AifwUpdateInfo {
     pub tarball_url: Option<String>,
     /// Download URL of the tarball's SHA-256 checksum asset, if present
     pub checksum_url: Option<String>,
+    /// Download URL of the checksum's detached minisign signature.
+    #[serde(default)]
+    pub checksum_signature_url: Option<String>,
     /// True when a rollback backup exists on disk
     pub has_backup: bool,
     /// Version the on-disk backup was taken from, when known
@@ -343,24 +346,7 @@ pub async fn check_for_update(include_prereleases: bool) -> Result<AifwUpdateInf
     let notes = release["body"].as_str().unwrap_or("").to_string();
     let published = release["published_at"].as_str().unwrap_or("").to_string();
 
-    let assets = release["assets"].as_array();
-    let mut tarball_url = None;
-    let mut checksum_url = None;
-
-    if let Some(assets) = assets {
-        for asset in assets {
-            let name = asset["name"].as_str().unwrap_or("");
-            let url = asset["browser_download_url"].as_str().unwrap_or("");
-            if name.starts_with("aifw-update-")
-                && name.ends_with(".tar.xz")
-                && !name.ends_with(".sha256")
-            {
-                tarball_url = Some(url.to_string());
-            } else if name.starts_with("aifw-update-") && name.ends_with(".tar.xz.sha256") {
-                checksum_url = Some(url.to_string());
-            }
-        }
-    }
+    let (tarball_url, checksum_url, checksum_signature_url) = release_asset_urls(&release);
 
     let (has_backup, backup_version) = get_backup_info().await;
     let restart_pending = restart_pending().await;
@@ -374,6 +360,7 @@ pub async fn check_for_update(include_prereleases: bool) -> Result<AifwUpdateInf
         published_at: published,
         tarball_url,
         checksum_url,
+        checksum_signature_url,
         has_backup,
         backup_version,
         restart_pending,
@@ -855,10 +842,15 @@ pub async fn download_and_install(info: &AifwUpdateInfo) -> Result<String, Updat
         .checksum_url
         .as_deref()
         .ok_or(UpdaterError::NoTarball)?;
+    let signature_url = info
+        .checksum_signature_url
+        .as_deref()
+        .ok_or(UpdaterError::NoTarball)?;
 
     let tmp_dir = "/tmp/aifw-update";
     let tarball_path = std::path::PathBuf::from(format!("{}/update.tar.xz", tmp_dir));
     let checksum_path = format!("{}/update.tar.xz.sha256", tmp_dir);
+    let signature_path = format!("{}/update.tar.xz.sha256.minisig", tmp_dir);
 
     // Clean and create temp dir. NotFound is the normal clean-run case.
     if let Err(e) = tokio::fs::remove_dir_all(tmp_dir).await
@@ -877,6 +869,12 @@ pub async fn download_and_install(info: &AifwUpdateInfo) -> Result<String, Updat
         .ok_or_else(|| UpdaterError::Install("tarball_path is not UTF-8".into()))?;
     http_download(tarball_url, tarball_path_str).await?;
     http_download(checksum_url, &checksum_path).await?;
+    http_download(signature_url, &signature_path).await?;
+
+    // Publisher authenticity is checked before trusting the checksum. The
+    // public key is provisioned independently on the appliance, so replacing
+    // a release asset and its checksum is insufficient to authorize install.
+    verify_minisign_checksum(&checksum_path, &signature_path).await?;
 
     // Read and parse the expected hash from the downloaded checksum file
     let expected = tokio::fs::read_to_string(&checksum_path)
@@ -906,6 +904,20 @@ pub async fn download_and_install(info: &AifwUpdateInfo) -> Result<String, Updat
     ))
 }
 
+async fn verify_minisign_checksum(checksum: &str, signature: &str) -> Result<(), UpdaterError> {
+    const PUBKEY_PATH: &str = "/usr/local/etc/aifw/update-signing.pub";
+    let output = Command::new("minisign")
+        .args(["-Vm", checksum, "-x", signature, "-p", PUBKEY_PATH])
+        .output()
+        .await
+        .map_err(|e| UpdaterError::Download(format!("signature verification unavailable: {e}")))?;
+    if output.status.success() {
+        Ok(())
+    } else {
+        Err(UpdaterError::Checksum)
+    }
+}
+
 /// Services that may have had their rc.d script replaced by an update and
 /// therefore need a restart for the new script to take effect. Order
 /// matters for aifw_api (last) so HTTP stays up as long as possible.
@@ -1323,6 +1335,28 @@ fn extract_hash(checksum_content: &str) -> String {
     line.split_whitespace().next().unwrap_or("").to_string()
 }
 
+fn release_asset_urls(
+    release: &serde_json::Value,
+) -> (Option<String>, Option<String>, Option<String>) {
+    let mut tarball = None;
+    let mut checksum = None;
+    let mut signature = None;
+    if let Some(assets) = release["assets"].as_array() {
+        for asset in assets {
+            let name = asset["name"].as_str().unwrap_or("");
+            let url = asset["browser_download_url"].as_str().unwrap_or("");
+            if name.starts_with("aifw-update-") && name.ends_with(".tar.xz") {
+                tarball = Some(url.to_string());
+            } else if name.starts_with("aifw-update-") && name.ends_with(".tar.xz.sha256.minisig") {
+                signature = Some(url.to_string());
+            } else if name.starts_with("aifw-update-") && name.ends_with(".tar.xz.sha256") {
+                checksum = Some(url.to_string());
+            }
+        }
+    }
+    (tarball, checksum, signature)
+}
+
 async fn http_get(url: &str) -> Result<String, UpdaterError> {
     // Try fetch (FreeBSD) first, fall back to curl
     if let Ok(o) = Command::new("fetch").args(["-qo", "-", url]).output().await
@@ -1544,6 +1578,19 @@ mod tests {
         assert_eq!(extract_hash(input), "abc123def456");
     }
 
+    #[test]
+    fn release_assets_require_distinct_checksum_and_signature_sidecars() {
+        let release = serde_json::json!({"assets": [
+            {"name": "aifw-update-6.0.0-amd64.tar.xz", "browser_download_url": "tar"},
+            {"name": "aifw-update-6.0.0-amd64.tar.xz.sha256", "browser_download_url": "sum"},
+            {"name": "aifw-update-6.0.0-amd64.tar.xz.sha256.minisig", "browser_download_url": "sig"}
+        ]});
+        assert_eq!(
+            release_asset_urls(&release),
+            (Some("tar".into()), Some("sum".into()), Some("sig".into()))
+        );
+    }
+
     // Regression gate for #469: every overlay libexec script must carry the
     // execute bit in git. Eight aifw-sudo-* helpers were committed mode 644,
     // build-iso.sh's `cp -a` preserved that onto installed systems, and sudo

From 7cd3e517fe0d255e4788f1a3d62bf76486b3a257 Mon Sep 17 00:00:00 2001
From: TheDancingDeveloper <dancingdeveloper@proton.me>
Date: Wed, 22 Jul 2026 00:29:37 +0000
Subject: [PATCH 2/3] feat: enforce signed release verification end to end

---
 .github/workflows/build-iso.yml               | 87 +++++++++----------
 aifw-core/src/updater.rs                      | 10 ++-
 .../app/updates/components/FirmwareCard.tsx   | 21 ++++-
 aifw-ui/src/lib/api/updates.ts                |  1 +
 freebsd/build-iso.sh                          |  2 +-
 freebsd/deploy.sh                             |  2 +-
 freebsd/manifest.json                         |  2 +-
 7 files changed, 75 insertions(+), 50 deletions(-)

diff --git a/.github/workflows/build-iso.yml b/.github/workflows/build-iso.yml
index 4606808d..7e52f0aa 100644
--- a/.github/workflows/build-iso.yml
+++ b/.github/workflows/build-iso.yml
@@ -202,44 +202,30 @@ jobs:
             mkdir -p /home/runner/work/AiFw/AiFw/output
             cp /usr/obj/aifw-iso/output/* /home/runner/work/AiFw/AiFw/output/
 
-      - name: Generate ISO CycloneDX SBOM
+      - name: Generate release CycloneDX SBOM
         uses: anchore/sbom-action@f8bdd1d8ac5e901a77a92f111440fdb1b593736b # v0.20.6
         with:
-          path: output/aifw-*.iso.xz
-          format: cyclonedx-json
-          output-file: output/aifw-iso.cdx.json
-          upload-artifact: false
-
-      - name: Generate IMG CycloneDX SBOM
-        uses: anchore/sbom-action@f8bdd1d8ac5e901a77a92f111440fdb1b593736b # v0.20.6
-        with:
-          path: output/aifw-*.img.xz
+          path: output
           format: cyclonedx-json
-          output-file: output/aifw-img.cdx.json
+          output-file: output/aifw-release.cdx.json
           upload-artifact: false
 
-      - name: Generate update CycloneDX SBOM
-        uses: anchore/sbom-action@f8bdd1d8ac5e901a77a92f111440fdb1b593736b # v0.20.6
-        with:
-          path: output/aifw-update-*.tar.xz
-          format: cyclonedx-json
-          output-file: output/aifw-update.cdx.json
-          upload-artifact: false
-
-      - name: Sign update checksums
+      - name: Sign release checksums
         env:
           MINISIGN_SECRET_KEY: ${{ secrets.MINISIGN_SECRET_KEY }}
           MINISIGN_PASSWORD: ${{ secrets.MINISIGN_PASSWORD }}
         run: |
           set -euo pipefail
+          test -n "$MINISIGN_SECRET_KEY" || { echo "MINISIGN_SECRET_KEY is required" >&2; exit 1; }
+          test -n "$MINISIGN_PUBLIC_KEY" || { echo "MINISIGN_PUBLIC_KEY is required" >&2; exit 1; }
           sudo apt-get update
           sudo apt-get install -y minisign
           key_file="$RUNNER_TEMP/minisign.key"
           trap 'rm -f "$key_file"' EXIT
           printf '%s' "$MINISIGN_SECRET_KEY" > "$key_file"
+          printf '%s\n' "$MINISIGN_PUBLIC_KEY" > output/update-signing.pub
           chmod 600 "$key_file"
-          for checksum in output/aifw-update-*.tar.xz.sha256; do
-            [ -f "$checksum" ] || continue
+          for checksum in output/*.sha256; do
             minisign -S -s "$key_file" -m "$checksum" -x "${checksum}.minisig"
           done
 
@@ -271,6 +257,24 @@ jobs:
           path: output/aifw-components-*.json
           retention-days: 5
 
+      - name: Upload SBOMs and signatures
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: supply-chain
+          path: |
+            output/*.cdx.json
+            output/*.minisig
+            output/update-signing.pub
+          retention-days: 5
+
+      - name: Attest release artifacts
+        uses: actions/attest-build-provenance@e8998f949152b193b063cb0ec769d69d929409be # v2.4.0
+        with:
+          subject-path: |
+            output/aifw-*.iso.xz
+            output/aifw-*.img.xz
+            output/aifw-update-*.tar.xz
+
   smoke-boot:
     name: Appliance boot smoke (qemu)
     needs: build-iso
@@ -311,23 +315,6 @@ jobs:
           name: boot-smoke-artifacts
           path: smoke-artifacts/
           retention-days: 7
-      - name: Upload SBOMs and signatures
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
-        with:
-          name: supply-chain
-          path: |
-            output/*.cdx.json
-            output/*.minisig
-          retention-days: 5
-
-      - name: Attest release artifacts
-        uses: actions/attest-build-provenance@e8998f949152b193b063cb0ec769d69d929409be # v2.4.0
-        with:
-          subject-path: |
-            output/aifw-*.iso.xz
-            output/aifw-*.img.xz
-            output/aifw-update-*.tar.xz
-
   release:
     name: Create GitHub Release
     # smoke-boot gates the release: an image nobody booted never ships (#533).
@@ -366,15 +353,18 @@ jobs:
           name: supply-chain
           path: release-assets/
 
-      - name: Verify update signatures before publication
+      - name: Verify signatures before publication
         env:
           MINISIGN_PUBLIC_KEY: ${{ vars.MINISIGN_PUBLIC_KEY }}
         run: |
           set -euo pipefail
+          test -n "$MINISIGN_PUBLIC_KEY" || { echo "MINISIGN_PUBLIC_KEY is required" >&2; exit 1; }
           sudo apt-get update
           sudo apt-get install -y minisign
-          for checksum in release-assets/aifw-update-*.tar.xz.sha256; do
-            minisign -Vm "$checksum" -x "${checksum}.minisig" -P "$MINISIGN_PUBLIC_KEY"
+          public_key_file="$RUNNER_TEMP/minisign.pub"
+          printf '%s\n' "$MINISIGN_PUBLIC_KEY" > "$public_key_file"
+          for checksum in release-assets/*.sha256; do
+            minisign -Vm "$checksum" -x "${checksum}.minisig" -p "$public_key_file"
           done
 
       - name: Extract version from tag
@@ -416,6 +406,15 @@ jobs:
             ### Verify Downloads
 
             ```bash
-            sha256sum -c aifw-${{ steps.version.outputs.version }}-amd64.iso.sha256
-            sha256sum -c aifw-${{ steps.version.outputs.version }}-amd64.img.sha256
+            minisign -Vm aifw-${{ steps.version.outputs.version }}-amd64.iso.xz.sha256 \
+              -x aifw-${{ steps.version.outputs.version }}-amd64.iso.xz.sha256.minisig \
+              -p update-signing.pub
+            sha256sum -c aifw-${{ steps.version.outputs.version }}-amd64.iso.xz.sha256
+            ```
+
+            GitHub build provenance can also be verified with:
+
+            ```bash
+            gh attestation verify aifw-${{ steps.version.outputs.version }}-amd64.iso.xz \
+              --repo ${{ github.repository }}
             ```
diff --git a/aifw-core/src/updater.rs b/aifw-core/src/updater.rs
index 75a2ed15..eba7dba6 100644
--- a/aifw-core/src/updater.rs
+++ b/aifw-core/src/updater.rs
@@ -223,6 +223,12 @@ pub enum UpdaterError {
     /// Downloaded tarball didn't match its published SHA-256
     #[error("Checksum verification failed")]
     Checksum,
+    /// The release did not contain a detached signature for its checksum
+    #[error("Release checksum signature is missing")]
+    NoSignature,
+    /// The checksum's publisher signature could not be verified
+    #[error("Release signature verification failed")]
+    Signature,
     /// Extracting or installing the update failed
     #[error("Installation failed: {0}")]
     Install(String),
@@ -845,7 +851,7 @@ pub async fn download_and_install(info: &AifwUpdateInfo) -> Result<String, Updat
     let signature_url = info
         .checksum_signature_url
         .as_deref()
-        .ok_or(UpdaterError::NoTarball)?;
+        .ok_or(UpdaterError::NoSignature)?;
 
     let tmp_dir = "/tmp/aifw-update";
     let tarball_path = std::path::PathBuf::from(format!("{}/update.tar.xz", tmp_dir));
@@ -914,7 +920,7 @@ async fn verify_minisign_checksum(checksum: &str, signature: &str) -> Result<(),
     if output.status.success() {
         Ok(())
     } else {
-        Err(UpdaterError::Checksum)
+        Err(UpdaterError::Signature)
     }
 }
 
diff --git a/aifw-ui/src/app/updates/components/FirmwareCard.tsx b/aifw-ui/src/app/updates/components/FirmwareCard.tsx
index 6d3337e9..0a1ecf9c 100644
--- a/aifw-ui/src/app/updates/components/FirmwareCard.tsx
+++ b/aifw-ui/src/app/updates/components/FirmwareCard.tsx
@@ -55,6 +55,16 @@ export function FirmwareCard({
               </span>
             )}
           </div>
+          {info?.checksum_signature_url && (
+            <a
+              href={info.checksum_signature_url}
+              target="_blank"
+              rel="noreferrer"
+              className="text-xs text-blue-400 hover:text-blue-300 underline"
+            >
+              Verify signed checksum
+            </a>
+          )}
           <label className="flex items-center gap-2 pt-2 cursor-pointer select-none">
             <input
               type="checkbox"
@@ -80,7 +90,10 @@ export function FirmwareCard({
             {checking ? "Checking..." : "Check for Update"}
           </button>
 
-          {info?.update_available && info?.tarball_url && (
+          {info?.update_available &&
+            info?.tarball_url &&
+            info?.checksum_url &&
+            info?.checksum_signature_url && (
             <button
               onClick={onInstall}
               disabled={installing}
@@ -93,6 +106,12 @@ export function FirmwareCard({
             </button>
           )}
 
+          {info?.update_available && !info?.checksum_signature_url && (
+            <p className="max-w-56 text-xs text-red-400">
+              Installation blocked: this release has no signed checksum.
+            </p>
+          )}
+
           {info?.has_backup && (
             <button
               onClick={onRollback}
diff --git a/aifw-ui/src/lib/api/updates.ts b/aifw-ui/src/lib/api/updates.ts
index 187a9e21..7c484d13 100644
--- a/aifw-ui/src/lib/api/updates.ts
+++ b/aifw-ui/src/lib/api/updates.ts
@@ -39,6 +39,7 @@ export interface AifwUpdateInfo {
   published_at: string;
   tarball_url: string | null;
   checksum_url: string | null;
+  checksum_signature_url: string | null;
   has_backup: boolean;
   backup_version: string | null;
   // True when the on-disk version differs from the running binary —
diff --git a/freebsd/build-iso.sh b/freebsd/build-iso.sh
index 29e04534..bab3f9c4 100755
--- a/freebsd/build-iso.sh
+++ b/freebsd/build-iso.sh
@@ -113,7 +113,7 @@ cp /etc/resolv.conf "$STAGEDIR/etc/resolv.conf"
 # Bootstrap pkg and install required packages
 chroot "$STAGEDIR" /bin/sh -c '
     env ASSUME_ALWAYS_YES=yes pkg bootstrap -f
-    pkg install -y wireguard-tools sudo unbound curl strongswan
+    pkg install -y wireguard-tools sudo unbound curl strongswan minisign
 '
 
 umount "$STAGEDIR/dev"
diff --git a/freebsd/deploy.sh b/freebsd/deploy.sh
index 08d7a4cd..971ec8ea 100755
--- a/freebsd/deploy.sh
+++ b/freebsd/deploy.sh
@@ -37,7 +37,7 @@ if ! command -v cargo >/dev/null 2>&1; then
 fi
 
 # --- Ensure dependencies ---
-for pkg in sudo unbound curl wireguard-tools strongswan; do
+for pkg in sudo unbound curl wireguard-tools strongswan minisign; do
     if ! pkg info -q "$pkg" 2>/dev/null; then
         echo "Installing $pkg..."
         pkg install -y "$pkg"
diff --git a/freebsd/manifest.json b/freebsd/manifest.json
index 1e77fe3d..4676a0e5 100644
--- a/freebsd/manifest.json
+++ b/freebsd/manifest.json
@@ -6,7 +6,7 @@
     "local": ["aifw", "aifw-daemon", "aifw-api", "aifw-ids", "aifw-tui", "aifw-setup"]
   },
 
-  "packages": ["curl", "strongswan", "sudo", "unbound", "wireguard-tools"],
+  "packages": ["curl", "minisign", "strongswan", "sudo", "unbound", "wireguard-tools"],
   "_packages_comment": "OS packages required at runtime. build-iso.sh installs them into the image; deploy.sh ensures them on the dev VM; the in-app updater installs any that are missing during upgrade. A workspace test (aifw-core packaging_tests) asserts the build scripts stay in sync with this list.",
 
   "external_repos": [

From c65aa37c12b8e62ec698134863ec3bd7910e6b45 Mon Sep 17 00:00:00 2001
From: mack42 <ronmccorkle@outlook.com>
Date: Tue, 21 Jul 2026 21:45:26 -0400
Subject: [PATCH 3/3] fix: compile in the update-signing key, sign local
 releases, self-heal minisign (#542)

- Commit the minisign public key and compile it into the updater via
  include_str!, so appliances upgraded from builds that never shipped
  /usr/local/etc/aifw/update-signing.pub still enforce signatures; the
  on-disk copy is provisioned/refreshed at install time for operators.
- Auto-install minisign via the pkg sudo helper when verification runs
  on an appliance whose running updater predates the manifest entry;
  a missing/unrunnable minisign now surfaces as VerifyUnavailable
  instead of a misleading Download error.
- release.sh (the local publish gate) signs every *.sha256 with
  ~/.minisign/aifw-update.key, verifies against the committed public
  key, refuses to publish unsigned, and uploads .minisig sidecars plus
  update-signing.pub.
- CI: pipe MINISIGN_PASSWORD to minisign stdin (it never read the env
  var); verify signatures against the committed key in both the sign
  step and the release job; drop vars.MINISIGN_PUBLIC_KEY provisioning.
- SBOM scans the source tree (Cargo.lock, aifw-ui/package-lock.json)
  instead of xz blobs syft cannot open; SBOM added to provenance
  subjects.
- Remove stale uncompressed-image .sha256 files after xz so
  unverifiable checksums are never signed or published.
- Document key management, rotation, and compromise response in
  freebsd/RELEASE-SIGNING.md.
---
 .github/workflows/build-iso.yml               |  41 ++++---
 aifw-core/src/updater.rs                      | 107 ++++++++++++++++--
 freebsd/RELEASE-SIGNING.md                    |  74 ++++++++++++
 .../usr/local/etc/aifw/update-signing.pub     |   2 +
 freebsd/release.sh                            |  36 +++++-
 5 files changed, 236 insertions(+), 24 deletions(-)
 create mode 100644 freebsd/RELEASE-SIGNING.md
 create mode 100644 freebsd/overlay/usr/local/etc/aifw/update-signing.pub

diff --git a/.github/workflows/build-iso.yml b/.github/workflows/build-iso.yml
index 7e52f0aa..caf2a38c 100644
--- a/.github/workflows/build-iso.yml
+++ b/.github/workflows/build-iso.yml
@@ -17,7 +17,6 @@ permissions:
 
 env:
   FREEBSD_VERSION: "15.0"
-  MINISIGN_PUBLIC_KEY: ${{ vars.MINISIGN_PUBLIC_KEY }}
 
 jobs:
   build-ui:
@@ -88,10 +87,6 @@ jobs:
 
             echo "=== Building AiFw binaries ==="
             cd /home/runner/work/AiFw/AiFw
-            test -n "$MINISIGN_PUBLIC_KEY" || { echo "MINISIGN_PUBLIC_KEY repository variable is required" >&2; exit 1; }
-            mkdir -p freebsd/overlay/usr/local/etc/aifw
-            printf '%s\n' "$MINISIGN_PUBLIC_KEY" > freebsd/overlay/usr/local/etc/aifw/update-signing.pub
-            chmod 644 freebsd/overlay/usr/local/etc/aifw/update-signing.pub
             cargo build --release
 
             echo "=== Validating sudoers content (visudo -cf, #204) ==="
@@ -194,6 +189,10 @@ jobs:
               if [ -f "$f" ] && [ ! -f "${f}.xz" ]; then
                 xz -T0 -9 "$f"
                 sha256 "${f}.xz" > "${f}.xz.sha256"
+                # build-iso.sh hashed the uncompressed file, which no
+                # longer exists after xz — drop its checksum so we never
+                # sign or publish a sum nobody can verify.
+                rm -f "${f}.sha256"
               fi
             done
             cd /home/runner/work/AiFw/AiFw
@@ -202,10 +201,15 @@ jobs:
             mkdir -p /home/runner/work/AiFw/AiFw/output
             cp /usr/obj/aifw-iso/output/* /home/runner/work/AiFw/AiFw/output/
 
+      # Scan the SOURCE tree, not output/: the release artifacts are
+      # xz-compressed images syft cannot see inside, so an SBOM of output/
+      # would be an empty inventory. The source scan covers Cargo.lock and
+      # aifw-ui/package-lock.json — the dependency set actually compiled
+      # into this release.
       - name: Generate release CycloneDX SBOM
         uses: anchore/sbom-action@f8bdd1d8ac5e901a77a92f111440fdb1b593736b # v0.20.6
         with:
-          path: output
+          path: .
           format: cyclonedx-json
           output-file: output/aifw-release.cdx.json
           upload-artifact: false
@@ -217,16 +221,23 @@ jobs:
         run: |
           set -euo pipefail
           test -n "$MINISIGN_SECRET_KEY" || { echo "MINISIGN_SECRET_KEY is required" >&2; exit 1; }
-          test -n "$MINISIGN_PUBLIC_KEY" || { echo "MINISIGN_PUBLIC_KEY is required" >&2; exit 1; }
           sudo apt-get update
           sudo apt-get install -y minisign
           key_file="$RUNNER_TEMP/minisign.key"
           trap 'rm -f "$key_file"' EXIT
           printf '%s' "$MINISIGN_SECRET_KEY" > "$key_file"
-          printf '%s\n' "$MINISIGN_PUBLIC_KEY" > output/update-signing.pub
           chmod 600 "$key_file"
+          pubkey=freebsd/overlay/usr/local/etc/aifw/update-signing.pub
+          cp "$pubkey" output/update-signing.pub
           for checksum in output/*.sha256; do
-            minisign -S -s "$key_file" -m "$checksum" -x "${checksum}.minisig"
+            # minisign reads the key password from stdin when there is no
+            # tty; harmless if the key is passwordless.
+            printf '%s\n' "${MINISIGN_PASSWORD:-}" | \
+              minisign -S -s "$key_file" -m "$checksum" -x "${checksum}.minisig"
+            # Verify against the COMMITTED public key immediately: catches a
+            # rotated/mismatched MINISIGN_SECRET_KEY before anything ships,
+            # since appliances verify with the key compiled from this file.
+            minisign -Vm "$checksum" -x "${checksum}.minisig" -p "$pubkey"
           done
 
       - name: Upload ISO artifact
@@ -274,6 +285,7 @@ jobs:
             output/aifw-*.iso.xz
             output/aifw-*.img.xz
             output/aifw-update-*.tar.xz
+            output/aifw-release.cdx.json
 
   smoke-boot:
     name: Appliance boot smoke (qemu)
@@ -354,17 +366,16 @@ jobs:
           path: release-assets/
 
       - name: Verify signatures before publication
-        env:
-          MINISIGN_PUBLIC_KEY: ${{ vars.MINISIGN_PUBLIC_KEY }}
         run: |
           set -euo pipefail
-          test -n "$MINISIGN_PUBLIC_KEY" || { echo "MINISIGN_PUBLIC_KEY is required" >&2; exit 1; }
           sudo apt-get update
           sudo apt-get install -y minisign
-          public_key_file="$RUNNER_TEMP/minisign.pub"
-          printf '%s\n' "$MINISIGN_PUBLIC_KEY" > "$public_key_file"
+          # The committed key from checkout — the same file compiled into
+          # the appliance updater — not a copy that traveled with the
+          # artifacts being verified.
+          pubkey=freebsd/overlay/usr/local/etc/aifw/update-signing.pub
           for checksum in release-assets/*.sha256; do
-            minisign -Vm "$checksum" -x "${checksum}.minisig" -p "$public_key_file"
+            minisign -Vm "$checksum" -x "${checksum}.minisig" -p "$pubkey"
           done
 
       - name: Extract version from tag
diff --git a/aifw-core/src/updater.rs b/aifw-core/src/updater.rs
index eba7dba6..18cac5fb 100644
--- a/aifw-core/src/updater.rs
+++ b/aifw-core/src/updater.rs
@@ -229,6 +229,11 @@ pub enum UpdaterError {
     /// The checksum's publisher signature could not be verified
     #[error("Release signature verification failed")]
     Signature,
+    /// minisign could not be located or executed, so the signature could
+    /// not be checked at all (distinct from a signature that checked and
+    /// failed — the operator fixes this one with `pkg install minisign`)
+    #[error("Signature verification unavailable: {0}")]
+    VerifyUnavailable(String),
     /// Extracting or installing the update failed
     #[error("Installation failed: {0}")]
     Install(String),
@@ -637,6 +642,32 @@ pub async fn install_from_path(
         }
     }
 
+    // Keep the operator-facing copy of the release-signing public key in
+    // sync with the running build (it changes only on key rotation).
+    // Verification itself uses the compiled-in key, so this is best-effort.
+    let on_disk_pubkey = tokio::fs::read_to_string(PUBKEY_PATH).await.ok();
+    if on_disk_pubkey.as_deref() != Some(EMBEDDED_PUBKEY) {
+        let staged = "/tmp/aifw-update-signing.pub";
+        let stage_ok = tokio::fs::write(staged, EMBEDDED_PUBKEY).await.is_ok();
+        if stage_ok {
+            if let Some(err) = step_failure(
+                &crate::sudo::install(
+                    Some("0644"),
+                    Some("root"),
+                    Some("wheel"),
+                    staged,
+                    PUBKEY_PATH,
+                )
+                .await,
+            ) {
+                warn!(error = %err, "update: could not provision update-signing.pub");
+            }
+            if let Err(e) = tokio::fs::remove_file(staged).await {
+                debug!(error = %e, "update: staged pubkey cleanup failed");
+            }
+        }
+    }
+
     let manifest = load_manifest();
 
     // Install rc.d scripts. Same reasoning as binaries above: iterate the
@@ -878,8 +909,8 @@ pub async fn download_and_install(info: &AifwUpdateInfo) -> Result<String, Updat
     http_download(signature_url, &signature_path).await?;
 
     // Publisher authenticity is checked before trusting the checksum. The
-    // public key is provisioned independently on the appliance, so replacing
-    // a release asset and its checksum is insufficient to authorize install.
+    // public key is compiled into the running binary, so replacing a release
+    // asset and its checksum is insufficient to authorize an install.
     verify_minisign_checksum(&checksum_path, &signature_path).await?;
 
     // Read and parse the expected hash from the downloaded checksum file
@@ -910,16 +941,62 @@ pub async fn download_and_install(info: &AifwUpdateInfo) -> Result<String, Updat
     ))
 }
 
+/// On-disk copy of the release-signing public key. Informational only —
+/// provisioned for operators who want to run `minisign -Vm` by hand.
+/// Verification always uses the compiled-in key below, so an appliance
+/// upgraded from a build that never shipped this file still enforces.
+const PUBKEY_PATH: &str = "/usr/local/etc/aifw/update-signing.pub";
+
+/// Release-signing public key, compiled in from the repo. Trust is pinned
+/// to the running build: a key rotation ships a release signed with the
+/// OLD key that embeds the NEW key, so every appliance crosses over by
+/// installing that release (see freebsd/RELEASE-SIGNING.md).
+const EMBEDDED_PUBKEY: &str =
+    include_str!("../../freebsd/overlay/usr/local/etc/aifw/update-signing.pub");
+
+/// The base64 key line of the embedded minisign public key (the line after
+/// the "untrusted comment:" header), suitable for `minisign -P`.
+fn embedded_pubkey_b64() -> Result<&'static str, UpdaterError> {
+    EMBEDDED_PUBKEY
+        .lines()
+        .map(str::trim)
+        .rfind(|l| !l.is_empty() && !l.starts_with("untrusted comment:"))
+        .filter(|l| l.starts_with("RW"))
+        .ok_or_else(|| {
+            UpdaterError::VerifyUnavailable(
+                "embedded update-signing public key is malformed".into(),
+            )
+        })
+}
+
 async fn verify_minisign_checksum(checksum: &str, signature: &str) -> Result<(), UpdaterError> {
-    const PUBKEY_PATH: &str = "/usr/local/etc/aifw/update-signing.pub";
-    let output = Command::new("minisign")
-        .args(["-Vm", checksum, "-x", signature, "-p", PUBKEY_PATH])
-        .output()
-        .await
-        .map_err(|e| UpdaterError::Download(format!("signature verification unavailable: {e}")))?;
+    let pubkey = embedded_pubkey_b64()?;
+    let args = ["-Vm", checksum, "-x", signature, "-P", pubkey];
+
+    let mut result = Command::new("minisign").args(args).output().await;
+    if matches!(&result, Err(e) if e.kind() == std::io::ErrorKind::NotFound) {
+        // An appliance upgraded from a pre-signing build doesn't have
+        // minisign yet: the OLD updater that installed this build worked
+        // from its own embedded package list, which predates the minisign
+        // entry in the manifest. The pkg sudo grant does exist on such
+        // appliances, so install it here rather than failing the upgrade.
+        info!("minisign not found; installing via pkg");
+        if let Some(err) = step_failure(&crate::sudo::pkg("install", &["-y", "minisign"]).await) {
+            return Err(UpdaterError::VerifyUnavailable(format!(
+                "minisign is not installed and installing it failed: {err}"
+            )));
+        }
+        result = Command::new("minisign").args(args).output().await;
+    }
+    let output = result
+        .map_err(|e| UpdaterError::VerifyUnavailable(format!("failed to run minisign: {e}")))?;
     if output.status.success() {
         Ok(())
     } else {
+        warn!(
+            stderr = %String::from_utf8_lossy(&output.stderr),
+            "release checksum signature rejected"
+        );
         Err(UpdaterError::Signature)
     }
 }
@@ -1584,6 +1661,20 @@ mod tests {
         assert_eq!(extract_hash(input), "abc123def456");
     }
 
+    // The compiled-in signing key is the trust root for every self-update:
+    // if the committed .pub file is reformatted into something this parser
+    // rejects, all appliances fail closed on the next release.
+    #[test]
+    fn embedded_update_signing_pubkey_parses() {
+        let key = embedded_pubkey_b64().expect("embedded public key must parse");
+        assert!(
+            key.starts_with("RW"),
+            "minisign keys are RW-prefixed: {key}"
+        );
+        assert!(!key.contains(char::is_whitespace));
+        assert_eq!(key.len(), 56, "Ed25519 minisign pubkey is 56 base64 chars");
+    }
+
     #[test]
     fn release_assets_require_distinct_checksum_and_signature_sidecars() {
         let release = serde_json::json!({"assets": [
diff --git a/freebsd/RELEASE-SIGNING.md b/freebsd/RELEASE-SIGNING.md
new file mode 100644
index 00000000..e4aa5181
--- /dev/null
+++ b/freebsd/RELEASE-SIGNING.md
@@ -0,0 +1,74 @@
+# Release Signing
+
+Every release checksum (`*.sha256`) is signed with
+[minisign](https://jedisct1.github.io/minisign/). The in-app updater **fails
+closed**: it downloads `aifw-update-*.tar.xz.sha256.minisig`, verifies it
+against the public key **compiled into the running `aifw-api` binary**, and
+refuses to install when the signature is missing or invalid. Because the key
+travels inside the binary, a compromised GitHub release (swapped tarball +
+swapped checksum) is not sufficient to push code onto appliances — the
+attacker would also need the secret key.
+
+CI-built releases are additionally attested with GitHub build provenance
+(`gh attestation verify <asset> --repo ZerosAndOnesLLC/AiFw`) and ship a
+CycloneDX SBOM (`aifw-release.cdx.json`) generated from `Cargo.lock` and
+`aifw-ui/package-lock.json`.
+
+## Key locations
+
+| What | Where |
+|------|-------|
+| Public key (trust root) | `freebsd/overlay/usr/local/etc/aifw/update-signing.pub` — committed; compiled into the updater via `include_str!`, baked into ISOs, published as a release asset |
+| Secret key (local releases) | `~/.minisign/aifw-update.key` on the release machine (override: `AIFW_MINISIGN_SECKEY`) — **never commit** |
+| Secret key (CI releases) | GitHub secret `MINISIGN_SECRET_KEY` (file contents); optional `MINISIGN_PASSWORD` if the key is password-protected |
+
+`freebsd/release.sh` signs at publish time and refuses to publish unsigned
+artifacts; CI signs in `build-iso.yml` and re-verifies against the committed
+public key before the release job uploads anything. Both paths catch a
+secret key that doesn't match the committed public key.
+
+## Generating a key
+
+```sh
+minisign -G -p ~/.minisign/aifw-update.pub -s ~/.minisign/aifw-update.key
+```
+
+Use `-W` for a passwordless key (required if CI must sign and no
+`MINISIGN_PASSWORD` secret is set). Keep an offline backup of the secret
+key; losing it means rotating (below) with no overlap.
+
+## Rotating the key
+
+Appliances trust exactly the key embedded in the build they are running, so
+rotation is a two-release handover:
+
+1. Generate the new keypair. Do **not** replace the old secret key yet.
+2. Commit the new public key to
+   `freebsd/overlay/usr/local/etc/aifw/update-signing.pub`.
+3. Cut the transition release **signed with the OLD key**. Fleet appliances
+   verify it with their embedded old key, install it, and are now running a
+   build that trusts the new key.
+4. All releases after the transition release are signed with the NEW key.
+   Update `~/.minisign/aifw-update.key` and the `MINISIGN_SECRET_KEY`
+   secret; retire the old key.
+
+An appliance that skips the transition release (offline during the window)
+verifies with the old key and will reject newer releases. Recovery: install
+the transition release explicitly (`aifw update install --from <tarball>`
+or the UI's manual upload), then update normally.
+
+## Compromised key / compromised release
+
+1. Immediately delete the `MINISIGN_SECRET_KEY` GitHub secret and destroy
+   the on-disk secret key.
+2. Mark every release signed by the compromised key as a **pre-release** on
+   GitHub (stable-channel appliances only pull `/releases/latest`, which
+   skips pre-releases) and delete any release known to carry a tampered
+   artifact.
+3. Rotate per the procedure above. The transition release must be built
+   from audited source and signed with the compromised key — that is
+   unavoidable (it is the only key the fleet trusts), so pin its content by
+   publishing its SHA-256 and attestation through an out-of-band channel
+   (project site, security advisory) before promoting it to stable.
+4. Publish a security advisory listing the compromised key ID, the affected
+   release window, and the new key.
diff --git a/freebsd/overlay/usr/local/etc/aifw/update-signing.pub b/freebsd/overlay/usr/local/etc/aifw/update-signing.pub
new file mode 100644
index 00000000..f4d0a3fb
--- /dev/null
+++ b/freebsd/overlay/usr/local/etc/aifw/update-signing.pub
@@ -0,0 +1,2 @@
+untrusted comment: minisign public key F1B14C3B88B534C1
+RWTBNLWIO0yx8R+mBWcURAIcRwDUCQDWK4ArTEKcL+V9knPAtsukmvua
diff --git a/freebsd/release.sh b/freebsd/release.sh
index 6e162ffe..f90328f6 100755
--- a/freebsd/release.sh
+++ b/freebsd/release.sh
@@ -123,6 +123,32 @@ if [ -z "$ISO_UPLOAD" ] && [ -z "$IMG_UPLOAD" ] && [ -z "$UPDATE_TARBALL" ]; the
     die "No artifacts to release. Run build-local.sh first."
 fi
 
+# --- Sign checksums (publisher authenticity) ---
+# The in-app updater fails closed: a release without a valid .minisig for
+# its update tarball checksum cannot be installed by any appliance. Signing
+# happens here — the single local publish gate — so build-local.sh /
+# build-update.sh test iterations don't need the key.
+# Key management: freebsd/RELEASE-SIGNING.md.
+SIGNKEY="${AIFW_MINISIGN_SECKEY:-$HOME/.minisign/aifw-update.key}"
+PUBKEY="$PROJECT_ROOT/freebsd/overlay/usr/local/etc/aifw/update-signing.pub"
+command -v minisign >/dev/null 2>&1 || die "minisign is required to sign release checksums: pkg install -y minisign"
+[ -f "$PUBKEY" ] || die "Missing committed public key: $PUBKEY"
+SIG_ASSETS=""
+for sha in "$ISO_SHA_UPLOAD" "$IMG_SHA_UPLOAD" "$UPDATE_SHA"; do
+    [ -n "$sha" ] || continue
+    sig="${sha}.minisig"
+    if [ ! -f "$sig" ] || [ "$sha" -nt "$sig" ]; then
+        [ -f "$SIGNKEY" ] || die "No signing key at $SIGNKEY (override with AIFW_MINISIGN_SECKEY). Unsigned releases cannot be installed — see freebsd/RELEASE-SIGNING.md."
+        minisign -S -s "$SIGNKEY" -m "$sha" -x "$sig" || die "Signing failed for $sha"
+    fi
+    # Verify against the COMMITTED public key — the one compiled into the
+    # appliance updater. Catches signing with a stale/rotated secret key
+    # before the release is published.
+    minisign -Vm "$sha" -x "$sig" -p "$PUBKEY" >/dev/null || die "Signature for $sha does not verify against $PUBKEY — signed with the wrong key?"
+    SIG_ASSETS="$SIG_ASSETS $sig"
+done
+echo "Signed and verified $(echo "$SIG_ASSETS" | wc -w | tr -d ' ') checksum file(s)"
+
 echo "Artifacts:"
 [ -n "$ISO_UPLOAD" ]      && ls -lh "$ISO_UPLOAD"
 [ -n "$IMG_UPLOAD" ]      && ls -lh "$IMG_UPLOAD"
@@ -205,6 +231,13 @@ ${DECOMPRESS_NOTE}
 
 ### Verify Downloads
 
+Each \`.sha256\` file is signed with the AiFw release key (\`update-signing.pub\`):
+
+\`\`\`bash
+minisign -Vm <file>.sha256 -x <file>.sha256.minisig -p update-signing.pub
+sha256sum -c <file>.sha256
+\`\`\`
+
 \`\`\`
 ${SHASUMS}\`\`\`"
 
@@ -215,6 +248,7 @@ ASSETS=""
 [ -n "$ISO_UPLOAD" ]      && ASSETS="$ASSETS $ISO_UPLOAD $ISO_SHA_UPLOAD"
 [ -n "$IMG_UPLOAD" ]      && ASSETS="$ASSETS $IMG_UPLOAD $IMG_SHA_UPLOAD"
 [ -n "$UPDATE_TARBALL" ]  && ASSETS="$ASSETS $UPDATE_TARBALL $UPDATE_SHA"
+ASSETS="$ASSETS $SIG_ASSETS $PUBKEY"
 
 # Publish as a PRE-RELEASE by default so it can be tested before the
 # community auto-pulls it: the in-app updater's stable channel uses GitHub
@@ -251,7 +285,7 @@ fi
 
 # --- Cleanup temp files ---
 if [ -n "$XZ_IMG" ]; then
-    rm -f "$XZ_IMG" "$IMG_SHA_UPLOAD"
+    rm -f "$XZ_IMG" "$IMG_SHA_UPLOAD" "${IMG_SHA_UPLOAD}.minisig"
     echo "Cleaned up temp files in /tmp"
 fi