M49: Signed-first install path — eliminate unverified bootstrap

Production installs now use secai-bootstrap.sh which configures the
container signing policy (policy.json + registries.d + cosign public
key) BEFORE the first rpm-ostree rebase, so the signed transport is
used from day one. The unverified recovery path is moved to a separate
doc. CI now publishes the image digest for pinned installs, and a
first-boot setup wizard guides users through integrity verification,
vault setup, and health checks.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: SecAI-Hub

.github/workflows/build.yml

@@ -63,3 +63,26 @@ jobs:
             "$IMAGE_REF"
         env:
           COSIGN_PRIVATE_KEY: ${{ secrets.SIGNING_SECRET }}
+
+      # Publish the image digest so users can pin installs to an exact build.
+      # The digest appears in the workflow summary and as an artifact.
+      - name: Extract and publish image digest
+        if: github.event_name != 'pull_request'
+        id: digest
+        run: |
+          DIGEST=$(skopeo inspect "docker://${IMAGE_REF}:latest" 2>/dev/null | jq -r '.Digest' || echo "")
+          if [ -z "$DIGEST" ] || [ "$DIGEST" = "null" ]; then
+            echo "WARNING: Could not extract image digest"
+            echo "digest=unknown" >> "$GITHUB_OUTPUT"
+          else
+            echo "digest=${DIGEST}" >> "$GITHUB_OUTPUT"
+            echo "${DIGEST}" > IMAGE_DIGEST
+            echo "## Image Digest" >> "$GITHUB_STEP_SUMMARY"
+            echo "" >> "$GITHUB_STEP_SUMMARY"
+            echo "Pinned install reference:" >> "$GITHUB_STEP_SUMMARY"
+            echo '```' >> "$GITHUB_STEP_SUMMARY"
+            echo "sudo bash secai-bootstrap.sh --digest ${DIGEST}" >> "$GITHUB_STEP_SUMMARY"
+            echo '```' >> "$GITHUB_STEP_SUMMARY"
+            echo "" >> "$GITHUB_STEP_SUMMARY"
+            echo "Full image ref: \`${IMAGE_REF}@${DIGEST}\`" >> "$GITHUB_STEP_SUMMARY"
+          fi

.github/workflows/release.yml

@@ -141,6 +141,23 @@ jobs:
         env:
           COSIGN_PRIVATE_KEY: ${{ secrets.SIGNING_SECRET }}
 
+      - name: Record release image digest
+        run: |
+          IMAGE_REF="ghcr.io/${{ github.repository }}"
+          TAG="${{ github.ref_name }}"
+          DIGEST=$(skopeo inspect "docker://${IMAGE_REF}:${TAG}" 2>/dev/null | jq -r '.Digest' || echo "")
+          if [ -n "$DIGEST" ] && [ "$DIGEST" != "null" ]; then
+            echo "${DIGEST}" > dist/IMAGE_DIGEST
+            echo "${IMAGE_REF}@${DIGEST}" > dist/IMAGE_REF_PINNED
+            echo "## Install with digest pinning" >> "$GITHUB_STEP_SUMMARY"
+            echo '```bash' >> "$GITHUB_STEP_SUMMARY"
+            echo "sudo bash secai-bootstrap.sh --digest ${DIGEST}" >> "$GITHUB_STEP_SUMMARY"
+            echo '```' >> "$GITHUB_STEP_SUMMARY"
+          else
+            echo "WARNING: Could not extract image digest for tag ${TAG}"
+            echo "unknown" > dist/IMAGE_DIGEST
+          fi
+
       - name: Create GitHub Release
         if: ${{ !inputs.dry_run }}
         uses: softprops/action-gh-release@da05d552573ad5aba039eaac05058a918a7bf631 # v2.2.2
@@ -150,5 +167,7 @@ jobs:
             dist/*-sbom.cdx.json
             dist/SHA256SUMS
             dist/SHA256SUMS.sig
+            dist/IMAGE_DIGEST
+            dist/IMAGE_REF_PINNED
           generate_release_notes: true
           fail_on_unmatched_files: false

README.md

@@ -49,24 +49,26 @@ Built on [uBlue](https://universal-blue.org/) (Fedora Atomic / Silverblue). All
 ### Install (Fedora Atomic)
 
 ```bash
-# 1. Verify image signature BEFORE installing (mandatory)
-cosign verify --key cosign.pub ghcr.io/sec_ai/secai_os:latest
+# 1. Download and review the signed bootstrap script
+curl -sSfL https://raw.githubusercontent.com/SecAI-Hub/SecAI_OS/main/files/scripts/secai-bootstrap.sh \
+  -o /tmp/secai-bootstrap.sh
+less /tmp/secai-bootstrap.sh
 
-# 2. Rebase to the signed image
-sudo rpm-ostree rebase ostree-image-signed:docker://ghcr.io/sec_ai/secai_os:latest
-sudo systemctl reboot
+# 2. Run the bootstrap (configures signing policy + verified rebase)
+#    Use --digest from the latest release for production installs
+sudo bash /tmp/secai-bootstrap.sh --digest sha256:RELEASE_DIGEST
 
-# 3. Set up encrypted vault
-sudo /usr/libexec/secure-ai/setup-vault.sh /dev/sdX
+# 3. Reboot and run the setup wizard
+sudo systemctl reboot
+sudo /usr/libexec/secure-ai/secai-setup-wizard.sh
 ```
 
-> **First install on a fresh Fedora Silverblue?** The signed transport requires that
-> the signing policy is already configured. On a fresh install, see
-> [docs/install/bare-metal.md](docs/install/bare-metal.md) for the one-time bootstrap
-> procedure (uses cosign verification + a single unverified pull, then locks to signed
-> transport permanently).
+The bootstrap script verifies the image signature and configures the signing policy
+**before** the rebase, so the first pull uses the signed transport — no unverified
+pull is ever performed. See the [latest release](https://github.com/SecAI-Hub/SecAI_OS/releases/latest)
+for the digest, or omit `--digest` for evaluation.
 
-See [docs/install/](docs/install/) for detailed guides: [bare metal](docs/install/bare-metal.md) | [virtual machine](docs/install/vm.md) | [development](docs/install/dev.md)
+See [docs/install/](docs/install/) for detailed guides: [bare metal](docs/install/bare-metal.md) | [virtual machine](docs/install/vm.md) | [development](docs/install/dev.md) | [recovery](docs/install/recovery-bootstrap.md)
 
 ### Get Your First Model
 
@@ -156,7 +158,7 @@ Every model passes through the same fully automatic pipeline:
 | **Updates** | Cosign-verified rpm-ostree, staged workflow, greenboot auto-rollback |
 | **Supply Chain** | Per-service CycloneDX SBOMs, SLSA3 provenance attestation, cosign-signed checksums |
 
-See [docs/threat-model.md](docs/threat-model.md) for threat classes, residual risks, and security invariants. See [docs/security-status.md](docs/security-status.md) for implementation status of all 48 milestones.
+See [docs/threat-model.md](docs/threat-model.md) for threat classes, residual risks, and security invariants. See [docs/security-status.md](docs/security-status.md) for implementation status of all 49 milestones.
 
 ### Verify Image Signatures
 
@@ -239,7 +241,7 @@ All CI jobs are defined in [`.github/workflows/ci.yml`](.github/workflows/ci.yml
 | [Threat Model](docs/threat-model.md) | Threat classes, invariants, residual risks |
 | [API Reference](docs/api.md) | HTTP API for all services |
 | [Policy Schema](docs/policy-schema.md) | Full policy.yaml schema reference |
-| [Security Status](docs/security-status.md) | Implementation status of all 48 milestones |
+| [Security Status](docs/security-status.md) | Implementation status of all 49 milestones |
 | [Test Matrix](docs/test-matrix.md) | Test coverage: 1,141 tests across Go and Python (see [test-counts.json](docs/test-counts.json)) |
 | [Compatibility Matrix](docs/compatibility-matrix.md) | GPU, VM, and hardware support |
 | [Security Test Matrix](docs/security-test-matrix.md) | Security feature test coverage |
@@ -376,7 +378,7 @@ See [docs/test-matrix.md](docs/test-matrix.md) for full breakdown.
 ## Roadmap
 
 <details>
-<summary>All 47 project milestones (click to expand)</summary>
+<summary>All 49 project milestones (click to expand)</summary>
 
 - [x] **Milestone 0** -- Threat model, dataflow, invariants, policy files
 - [x] **Milestone 1** -- Bootable OS, encrypted vault, GPU drivers
@@ -427,6 +429,7 @@ See [docs/test-matrix.md](docs/test-matrix.md) for full breakdown.
 - [x] **Milestone 46** -- Operational maturity: bootstrap trust gap fix (cosign verify before rebase), CI runs on all changes (removed paths-ignore for .md), Python quality gates (ruff + bandit + split test suites), docs-validation CI job, production-readiness checklist, SLOs, release channel policy, support lifecycle, sample verification output
 - [x] **Milestone 47** -- CI enforcement hardening: enforced vulnerability scanning (govulncheck + pip-audit + bandit fail on HIGH/HIGH) with waiver mechanism, mypy type checking for security-sensitive services, pinned reproducible Python CI dependencies, Go 1.23→1.25 (12 stdlib CVE fixes), verification-first bootstrap docs
 - [x] **Milestone 48** -- Production hardening: build script fail-closed (fatal errors for 12 required services + binary verification gate), incident store fsync (crash-safe persistence), GPU backend metadata recording, llama-server watchdog (Type=notify + WatchdogSec=30), model catalog externalization (YAML with fallback), circuit breaker for inter-service HTTP calls, post-upgrade model verification in Greenboot, cosign key rotation documentation (full lifecycle)
+- [x] **Milestone 49** -- Signed-first install path: bootstrap script configures signing policy before first rebase (eliminates unverified transport), digest-pinned install flow (CI publishes digests in build summary + release assets), first-boot setup wizard (interactive integrity verification + vault + TPM2 + health check), recovery/dev path separated into dedicated doc
 
 </details>
 

docs/install/bare-metal.md

@@ -67,117 +67,85 @@ Replace `/dev/sdX` or `/dev/rdiskN` with your actual USB device. Double-check th
 
 After booting into the fresh Fedora Silverblue installation, open a terminal.
 
-### 4a. Verify image signature (mandatory)
+### Production Install (Recommended)
 
-Before installing the image, verify its authenticity using cosign.
-**Do not skip this step — it is the cryptographic attestation that the
-image you are about to install was built by the SecAI project.**
+The bootstrap script configures the container signing policy **before** pulling the image, so the very first rebase uses the signed transport. No unverified pull is ever performed.
 
 ```bash
-# Install cosign (if not already present)
-sudo dnf install -y cosign
+# 1. Download the bootstrap script
+curl -sSfL https://raw.githubusercontent.com/SecAI-Hub/SecAI_OS/main/files/scripts/secai-bootstrap.sh \
+  -o /tmp/secai-bootstrap.sh
 
-# Fetch the project's public key
-curl -sSfL https://raw.githubusercontent.com/SecAI-Hub/SecAI_OS/main/cosign.pub -o /tmp/cosign.pub
+# 2. Review the script before running (ALWAYS review downloaded scripts)
+less /tmp/secai-bootstrap.sh
 
-# Verify the image signature — STOP if this fails
-cosign verify --key /tmp/cosign.pub ghcr.io/sec_ai/secai_os:latest
+# 3. Run the bootstrap (use the digest from the latest release for production)
+sudo bash /tmp/secai-bootstrap.sh --digest sha256:RELEASE_DIGEST
 ```
 
-You must see `The following checks were performed on each of these signatures: ...`
-with a successful verification result. **Do not proceed if verification fails.**
+> **Where do I find the digest?** Check the
+> [latest release](https://github.com/SecAI-Hub/SecAI_OS/releases/latest)
+> for the `IMAGE_DIGEST` asset, or the build workflow summary.
+> For evaluation, you can omit `--digest` to use `:latest`.
 
-### 4b. First-time bootstrap (fresh Fedora Silverblue only)
+The script will:
 
-> **Why an unverified pull?** A fresh Fedora Silverblue installation does
-> not yet have the SecAI signing policy in its local ostree store. The very
-> first rebase therefore uses `ostree-unverified-registry:` as a one-time
-> bootstrapping step. This is safe because you verified the image signature
-> out-of-band in step 4a above. After this single unverified pull, all
-> future updates use the signed transport and are verified automatically
-> by rpm-ostree.
->
-> **Risk acknowledgment:** If you skipped step 4a, this unverified pull
-> has no integrity guarantee. Go back and run the cosign verification first.
+1. Install cosign (if needed) and fetch the SecAI public signing key
+2. Verify the key's SHA256 fingerprint against a hardcoded value
+3. Configure the signing policy on your system (`policy.json` + `registries.d`)
+4. Verify the image signature using cosign
+5. Rebase using the **signed** transport (`ostree-image-signed:docker://`)
+6. Prompt you to reboot
 
-```bash
-# One-time unverified pull (safe ONLY because you verified the signature in 4a)
-sudo rpm-ostree rebase ostree-unverified-registry:ghcr.io/sec_ai/secai_os:latest
-sudo systemctl reboot
-```
-
-### 4c. Lock to signed transport (mandatory)
-
-Immediately after the first reboot, switch to the signed image transport.
-**This step is not optional** — it ensures all future updates are
-cryptographically verified by rpm-ostree before they are applied.
+After the script completes:
 
 ```bash
-# Lock to signed transport — all future updates verified automatically
-sudo rpm-ostree rebase ostree-image-signed:docker://ghcr.io/sec_ai/secai_os:latest
 sudo systemctl reboot
 ```
 
-After this reboot, the system is running SecAI OS with full signature
-verification enabled. All subsequent `rpm-ostree upgrade` commands will
-reject unsigned or tampered images.
-
-### Returning users / existing SecAI OS installs
+### Returning Users / Existing SecAI OS Installs
 
 If you are upgrading an existing SecAI OS installation (already on the
 signed transport), simply run:
 
 ```bash
-cosign verify --key /path/to/cosign.pub ghcr.io/sec_ai/secai_os:latest
 sudo rpm-ostree upgrade
 sudo systemctl reboot
 ```
 
----
-
-## Step 5: Set Up the Encrypted Vault
+All upgrades are automatically verified against the cosign signing key
+baked into the image.
 
-On first boot after rebasing, the firstboot script runs automatically. It will:
+### Recovery / Development Install
 
-1. Create the encrypted vault partition at `/var/lib/secure-ai/vault` (if not already present).
-2. Initialize the registry manifest.
-3. Set up systemd service dependencies.
-4. Configure nftables firewall rules.
-5. Run Greenboot health checks.
-
-You will be prompted to set a vault passphrase. This passphrase encrypts the LUKS volume that stores your models and configuration. Store it securely -- there is no recovery mechanism.
+> **WARNING**: The recovery path uses an unverified container transport.
+> Use it **only** when the signing policy is broken or for development/CI.
+> See [Recovery Bootstrap](recovery-bootstrap.md) for instructions.
 
 ---
 
-## Step 6: First Boot Verification
+## Step 5: First-Boot Setup Wizard
 
-After firstboot completes, run the automated health check:
+After rebooting into SecAI OS, run the interactive setup wizard:
 
 ```bash
-# Comprehensive health check (validates all services, endpoints, security posture)
-sudo /usr/libexec/secure-ai/first-boot-check.sh
+sudo /usr/libexec/secure-ai/secai-setup-wizard.sh
 ```
 
-This validates all core services are running, health endpoints respond, attestation
-state is verified, no open incidents exist, and no services are exposed on public
-interfaces. See [docs/production-operations.md](../production-operations.md) for details.
-
-You can also verify manually:
-
-```bash
-# Check that all services are running
-systemctl status secure-ai-registry
-systemctl status secure-ai-tool-firewall
-systemctl status secure-ai-ui
+The wizard walks you through:
 
-# Check firewall rules
-sudo nft list ruleset
+1. **System identity** — OS version, deployment origin, Secure Boot + TPM2 status
+2. **Image integrity** — Cosign signature verification of the running image
+3. **Transport check** — Confirms you are on signed transport (offers to switch if not)
+4. **Vault setup** — Creates the encrypted LUKS volume for models and secrets
+5. **TPM2 sealing** (optional) — Seals the vault key to TPM2 PCRs for auto-unlock on trusted boots
+6. **Health check** — Validates all services are running and endpoints are reachable
+7. **Summary** — Security posture card and next steps
 
-# Check vault status
-curl http://localhost:8480/api/vault/status
+You can also run the health check independently at any time:
 
-# Open the UI
-xdg-open http://localhost:8480
+```bash
+sudo /usr/libexec/secure-ai/first-boot-check.sh
 ```
 
 ---
@@ -220,3 +188,5 @@ nvidia-smi
 ```bash
 sudo cryptsetup status secure-ai-vault
 ```
+
+**Bootstrap script fails:** See [Recovery Bootstrap](recovery-bootstrap.md) for the manual fallback procedure.