feat: harden release signing and coverage gate

2026-07-29 22:54:51 +02:00
parent aa4895912a
commit 18f42621c2
13 changed files with 496 additions and 39 deletions
@@ -18,9 +18,57 @@ certificate through its supported CSC environment variables, then set:
 ```powershell
 $env:FORGEFLOW_SIGNED_RELEASE = '1'
 $env:FORGEFLOW_EXPECTED_PUBLISHER = 'CN=Exact Legal Publisher, O=Exact Legal Organization, C=BE'
-npm run dist:win
+npm run dist:win:signed
 ```

+The signed command requires signed-release mode, an exact publisher subject and
+either a classic `WIN_CSC_LINK` certificate configuration or complete Azure
+credentials. It enables electron-builder's `forceCodeSigning` gate, so missing
+signing material cannot silently produce a production candidate.
+
+### Recommended: Azure Artifact Signing
+
+1. Create an Azure Artifact Signing account and identity-validation certificate
+   profile for the legal ForgeFlow publisher.
+2. Create an Entra app registration and give its service principal the
+   `Artifact Signing Certificate Profile Signer` role on that account.
+3. Store the following as protected CI variables—never in Git:
+
+```powershell
+$env:AZURE_TENANT_ID = '<tenant id>'
+$env:AZURE_CLIENT_ID = '<application/client id>'
+$env:AZURE_CLIENT_SECRET = '<secret value>'
+$env:FORGEFLOW_AZURE_SIGNING_ENDPOINT = 'https://<region>.codesigning.azure.net/'
+$env:FORGEFLOW_AZURE_SIGNING_ACCOUNT = '<artifact signing account>'
+$env:FORGEFLOW_AZURE_CERTIFICATE_PROFILE = '<certificate profile>'
+$env:FORGEFLOW_SIGNED_RELEASE = '1'
+$env:FORGEFLOW_EXPECTED_PUBLISHER = 'CN=<exact subject from Get-AuthenticodeSignature>'
+npm run dist:win:signed
+```
+
+The generated configuration uses SHA-256 and Microsoft's RFC 3161 timestamp
+service. `FORGEFLOW_EXPECTED_PUBLISHER` must still contain the complete subject
+reported by the resulting certificate, even though Azure's builder option uses
+its CN component.
+
+### Alternative: classic CA certificate
+
+When a CA supplies a CI-compatible PFX or hardware/cloud connector supported by
+electron-builder, configure its protected values and use the same command:
+
+```powershell
+$env:WIN_CSC_LINK = 'C:\secure\forgeflow-signing.pfx'
+$env:WIN_CSC_KEY_PASSWORD = '<secret password>'
+$env:FORGEFLOW_SIGNED_RELEASE = '1'
+$env:FORGEFLOW_EXPECTED_PUBLISHER = 'CN=<exact legal subject>, O=<organization>, C=BE'
+npm run dist:win:signed
+```
+
+Do not purchase a certificate before the CA or cloud service confirms the exact
+legal subject and that its key-storage method works with the intended Windows CI
+runner. An ordinary OV certificate can still accumulate SmartScreen reputation;
+EV or Azure Artifact Signing provides immediate publisher trust.
+
 Both installer and portable executable must have a valid Authenticode signature,
 the expected publisher and a timestamp. The build also creates SHA-256 files, a
 CycloneDX SBOM and a provenance document containing commit and build ID.