# Distribution and code signing

How Vitals is built, signed and delivered — and, honestly, what the free
approach does not solve.

## The problem

Windows shows **SmartScreen** on any executable it has not seen before:

> Windows protected your PC
> Microsoft Defender SmartScreen prevented an unrecognised app from starting.

Running it requires clicking _More info_ → _Run anyway_. Most people close the
dialog instead. (Vitals does not install a service — the privileged helper
is not shipped, ADR 0012 — so the only thing Windows is judging is the
installer itself.)

## What actually removes the warning, and what it costs

| Approach                | Cost/year | Removes SmartScreen                             |
| ----------------------- | --------- | ----------------------------------------------- |
| Unsigned                | Free      | No                                              |
| Self-signed certificate | Free      | **No** — worse, it looks like forgery           |
| Sigstore / cosign       | Free      | No (not a Windows trust root)                   |
| Certum Open Source (OV) | ~€30–60   | Only after building reputation, weeks to months |
| OV / EV certificate     | ~€250–600 | Reputation-based for both since 2024            |
| SignPath Foundation     | Free      | Reputation-based; needs an established project  |
| Microsoft Store         | Free\*    | Yes — Store installs never show SmartScreen     |

\* Individual developer registration has been free since September 2025.
Azure Artifact Signing (formerly Trusted Signing) is not offered to individual
developers outside the US and Canada, so it is not an option for this project.

There is no path — free or paid — to an immediate SmartScreen bypass through
direct download any more: since 2024 EV certificates build reputation the same
way OV ones do. The Store is the only warning-free route.

## What we do

### 1. Reproducible builds, publicly verifiable

Every release is built by a GitHub Actions workflow from a tagged commit. The
workflow file is in the repository, so anyone can read exactly what produced
the binary. This does not stop SmartScreen but it does mean nobody has to
trust a binary blob built on a developer's laptop.

### 2. Checksums and build provenance

Every artefact ships with a SHA-256 checksum and a
[SLSA provenance attestation](https://slsa.dev), generated by
`actions/attest-build-provenance`. This is free, and it cryptographically
links a binary to the exact commit, workflow and runner that produced it.

Verify a download:

```powershell
# Checksum
Get-FileHash .\Vitals_x64-setup.exe -Algorithm SHA256

# Provenance, with the GitHub CLI
gh attestation verify .\Vitals_x64-setup.exe --repo dragoscv/vitals
```

Stronger than a code-signing certificate in one specific way: a certificate
proves _who_ built it, provenance proves _what source_ built it. It is weaker
in the way that matters commercially — Windows does not check it.

### 3. Microsoft Store, as an MSIX that Microsoft signs

The Store is the only route to a warning-free install. Registration is free
for individuals. Vitals takes the **MSIX route**: the package is uploaded
unsigned and Microsoft signs it, so no code-signing certificate is needed.
Tauri has no MSIX bundler, so `packaging/msix/build-msix.ps1` lays the
package out from the release executables and the generated brand assets.

The Store build is the **same binary**; Store policy is applied at run time
(`apps/desktop/src-tauri/src/distribution.rs`) when the process has package
identity:

- **no self-update** — the Store updates the package;
- **no Task Manager replacement** — its HKLM IFEO write is virtualised;
- **no sensors service or driver** — not shipped in the package; CPU
  temperature falls back to what Windows reports without it;
- **start with Windows** and the watchdog use the manifest's
  `windows.startupTask` entries, because Run-key writes are virtualised too.

Trade-offs, stated plainly:

- **Certification review** adds days to each release, so the Store lags the
  direct download.
- **The listing must never change underneath Microsoft.** For the EXE route
  the URL they review has to keep serving the same bytes, so the Store points
  at a versioned asset, never at `latest`.

### 4. Honest documentation of the warning

The download page and README explain the warning, show the expected checksum,
and tell people how to verify it. Pretending it does not exist trains users to
click through security warnings — the same failure the process-termination
risk model exists to avoid.

## If signing is funded later

The switch is small and localised:

1. Add `WINDOWS_CERTIFICATE` (base64 PFX) and
   `WINDOWS_CERTIFICATE_PASSWORD` repository secrets.
2. That is all. `release.yml` imports the certificate and passes the
   thumbprint to `tauri build` through a `--config` override; with the secrets
   absent it builds unsigned and says so.

Deliberately not designed around: nothing in the build depends on signing
being absent.

## Update signing is separate, and is already done

Tauri's updater verifies a **minisign** signature on every update package
before applying it. That key is ours, costs nothing, and is unrelated to
Windows code signing.

This matters more than SmartScreen for ongoing safety: it means a
man-in-the-middle cannot serve a malicious update, even though the initial
download shows a warning. The private key lives only in repository secrets
and on the maintainer's machine under `%USERPROFILE%\.tauri`, never in the
repository (`docs/releasing.md`).

## Summary

- SmartScreen on first run is **expected** for the direct download. Documented,
  not hidden.
- Provenance and checksums give verifiability without a certificate.
- The Store listing ships as an MSIX signed by Microsoft (`packaging/msix/`).
- Updates are cryptographically verified regardless of channel.