From 9806afbcedc91181594c8b2d2305434923167c65 Mon Sep 17 00:00:00 2001 From: "shumeiko.it" Date: Sun, 1 Nov 2026 01:39:49 +0100 Subject: [PATCH] docs(oss): propose how to sign the installers (P2.5) 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. --- docs/oss/signing.md | 84 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 docs/oss/signing.md diff --git a/docs/oss/signing.md b/docs/oss/signing.md new file mode 100644 index 0000000..c3ca80e --- /dev/null +++ b/docs/oss/signing.md @@ -0,0 +1,84 @@ +# 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.