Developer ID and notarization on macOS (including the bundled node and native libraries), the owner's existing Azure Artifact Signing on Windows with SignPath Foundation or a CA certificate as alternatives, and signed checksums on Linux. Lists the decisions the owner has to make.
85 lines
4.3 KiB
Markdown
85 lines
4.3 KiB
Markdown
# Signing the community edition installers (P2.5)
|
|
|
|
A proposal for the project owner. Nothing here is set up yet: the release workflow builds
|
|
unsigned installers, and signing needs accounts that only the owner can open.
|
|
|
|
## What happens without signing
|
|
|
|
| System | What the user sees | Workaround we document |
|
|
|---|---|---|
|
|
| Windows | SmartScreen: "Windows protected your PC" | More info → Run anyway |
|
|
| macOS | Gatekeeper: the app "cannot be opened because the developer cannot be verified" | Right-click → Open, or `xattr -dr com.apple.quarantine /Applications/Waggle.app` |
|
|
| Linux | Nothing blocks the install | Compare the file with `SHA256SUMS` |
|
|
|
|
The server archive is already protected in transit: the installer refuses an archive whose
|
|
SHA-256 does not match the `.sha256` published next to it (ADR-0009). That proves the file
|
|
was not damaged or swapped on the way, but not who built it, which is what signing adds.
|
|
|
|
## Proposal per system
|
|
|
|
### macOS: Developer ID and notarization
|
|
|
|
- **Account:** an Apple Developer Program membership in the owner's company name. An
|
|
organization account needs a D-U-N-S number.
|
|
- **What it signs:** the app bundle with a Developer ID Application certificate and the
|
|
hardened runtime, then Apple notarizes the DMG and the ticket is stapled to it.
|
|
- **Work on our side:** notarization rejects any unsigned Mach-O file inside the bundle.
|
|
`Contents/Resources/resources` holds the bundled `node`, the `.node` addons and the
|
|
onnxruntime and libvips dylibs, so a signing step before `tauri build` must sign each of them
|
|
with the same identity. Tauri then signs the app and runs notarization when these CI secrets
|
|
are set: `APPLE_CERTIFICATE`, `APPLE_CERTIFICATE_PASSWORD`, `APPLE_SIGNING_IDENTITY`,
|
|
`APPLE_API_ISSUER`, `APPLE_API_KEY` and the API key file.
|
|
- **The server archive** for macOS should carry the same signed `node` and libraries, so a
|
|
quarantined download does not block them either.
|
|
|
|
### Windows: reuse the owner's existing signing service
|
|
|
|
The commercial release pipeline signed Windows builds with Microsoft's Azure Artifact Signing
|
|
(formerly Trusted Signing; `Microsoft.ArtifactSigning.Client` in the old `release.yml`). If the
|
|
owner keeps that account, the simplest path is to sign the community edition with it as well:
|
|
the publisher shown to users stays the owner's company, and no new identity check is needed.
|
|
|
|
Alternatives, if that account cannot be used for an open-source release:
|
|
|
|
- **SignPath Foundation:** free signing for open-source projects that meet its rules (an OSI
|
|
license, a public repository, a reproducible build in public CI). The certificate belongs to
|
|
SignPath Foundation, so Windows shows it, not the owner, as the publisher.
|
|
- **A certificate from a public CA** (OV or EV), kept on a hardware token or a cloud HSM.
|
|
|
|
Whatever the certificate, SmartScreen builds reputation per publisher over downloads, so the
|
|
first releases can still show a warning for a while.
|
|
|
|
What to sign: the NSIS and MSI installers, the `Waggle.exe` inside them, and the bundled
|
|
`node.exe` and `.node` addons in the server archive.
|
|
|
|
### Linux: signed checksums
|
|
|
|
Linux packages are not signed by default. We propose signing the release's `SHA256SUMS` file:
|
|
|
|
- **Keyless with Sigstore (cosign)** in GitHub Actions: no key to store; the signature binds the
|
|
file to the workflow run that produced it. This needs the repository on GitHub (Q9).
|
|
- **Or a GPG key** held by the owner, with the public key published in the repository.
|
|
|
|
A signed apt repository can come later, if the owner wants `apt install` instead of a
|
|
downloaded `.deb`.
|
|
|
|
### npm package of the installer
|
|
|
|
When the installer package is published to npm, publish it with provenance
|
|
(`npm publish --provenance` from GitHub Actions), so npm shows which workflow built it.
|
|
|
|
## Not needed for v1
|
|
|
|
The Tauri auto-updater needs its own signing key pair (`TAURI_SIGNING_PRIVATE_KEY`). The updater
|
|
is disabled in v1, so this key is not needed yet.
|
|
|
|
## Decisions for the owner
|
|
|
|
1. Who owns the signing accounts: the owner's company (recommended), or a new open-source
|
|
entity.
|
|
2. Windows: reuse the existing Azure Artifact Signing, or SignPath Foundation, or a CA certificate.
|
|
3. Whether the first release may ship unsigned, with the workarounds above in the install guide.
|
|
|
|
Once the accounts exist, the release workflow gets one signing step per system and the
|
|
secrets listed above. The build steps do not change.
|