289 lines
14 KiB
Markdown
289 lines
14 KiB
Markdown
# Code-Signing Playbook — Pilot + Public Day 0
|
|
|
|
**Decision (2026-05-07):** Self-sign for pilot (Wave-1 Egzakta-internal, T+10 = 2026-05-16). Procure real certs in parallel for public Day 0 (T+30 = 2026-06-05).
|
|
|
|
**Why split:** Real Authenticode + Apple Developer ID have 5-15 business-day lead times. Self-signing unblocks the pilot ship date without paying for certs that aren't usable until a vetting check completes.
|
|
|
|
---
|
|
|
|
## 1. Pilot phase — self-sign (T+0 → T+10, Wave-1 only)
|
|
|
|
### 1.1 Windows self-sign
|
|
|
|
**Automated path (LAUNCH-06).** Three npm scripts wrap the cert generation + config wiring + signtool steps. Run from `app/`:
|
|
|
|
```powershell
|
|
# 1. Generate self-signed cert (idempotent — reuses existing cert by subject
|
|
# if one is still valid). Writes thumbprint to app/src-tauri/.thumbprint.txt
|
|
# (gitignored). PFX exports to %USERPROFILE%\waggle-pilot-codesign.pfx.
|
|
$env:WAGGLE_PILOT_PFX_PASSWORD = "your-strong-pw"
|
|
npm run tauri:sign:pilot:win:setup
|
|
|
|
# 2. Apply the captured thumbprint to tauri.build-override.conf.json
|
|
# (touches bundle.windows.{certificateThumbprint,digestAlgorithm,timestampUrl}
|
|
# only — preserves all other fields).
|
|
npm run tauri:sign:pilot:win:apply
|
|
|
|
# 3. Build — Tauri's MSI/NSIS bundlers pick up the thumbprint from the
|
|
# override config and sign automatically.
|
|
npm run tauri:build:win
|
|
|
|
# 4. (Optional, redundant safety) Re-sign the produced MSI explicitly
|
|
# via signtool. Useful if you want to apply timestamp at a different time
|
|
# than build.
|
|
npm run tauri:sign:pilot:win:sign -- src-tauri/target/release/bundle/msi/Waggle_*.msi
|
|
```
|
|
|
|
**What the scripts wrap (reference, in case you need to step outside the npm wrappers):**
|
|
|
|
- `app/scripts/sign-windows-pilot.ps1` — `-Mode Setup` runs `New-SelfSignedCertificate` with `Subject="CN=Egzakta Internal Pilot, O=Egzakta Group, C=RS"`, 2-year `NotAfter`, `Cert:\CurrentUser\My` store, then `Export-PfxCertificate`. `-Mode Sign -ArtifactPath <path>` wraps `signtool.exe sign /f <pfx> /tr http://timestamp.digicert.com /td sha256 /fd sha256` plus a `signtool verify /pa /v` round-trip.
|
|
- `app/scripts/apply-signing-config.mjs` — pure JSON merge: reads `.thumbprint.txt`, parses + uppercases + validates 40-hex format via the canonical helpers in `signing-config.ts`, writes the three fields back to `tauri.build-override.conf.json`. Idempotent.
|
|
- `app/scripts/signing-config.ts` — pure utility module (parse + merge) with 19-test vitest suite (`signing-config.test.ts`). Authoritative for thumbprint validation rules + idempotency invariants.
|
|
|
|
**What pilot users see on first install:**
|
|
- Windows SmartScreen: "Windows protected your PC" → "More info" → "Run anyway"
|
|
- Frame this in the pilot installer email: *"Internal Egzakta build — SmartScreen will warn. Click 'More info' then 'Run anyway' the first time. Subsequent launches are silent."*
|
|
|
|
### 1.2 macOS self-sign (ad-hoc)
|
|
|
|
**Already wired (LAUNCH-06).** `app/src-tauri/tauri.build-override.conf.json` ships with `bundle.macOS.signingIdentity = "-"`, so every `npm run tauri:build:mac` produces an ad-hoc-signed `.app` automatically — no operator step required.
|
|
|
|
**Re-sign + verify wrapper.** For nested helpers (sidecar, native deps) Tauri's bundler may miss, run:
|
|
|
|
```bash
|
|
npm run tauri:sign:pilot:mac:adhoc -- /path/to/Waggle.app
|
|
# Wraps: codesign --force --deep --sign - + codesign --verify --deep --strict
|
|
# Source: app/scripts/sign-macos-adhoc.sh
|
|
```
|
|
|
|
**Distribution:** Wrap `Waggle.app` in `.zip` (NOT `.dmg` — Gatekeeper enforces notarization on disk images more aggressively than zips since macOS 10.15):
|
|
|
|
```bash
|
|
ditto -c -k --keepParent /path/to/Waggle.app /path/to/Waggle.zip
|
|
```
|
|
|
|
**What pilot users see on first install:**
|
|
- Gatekeeper: "Waggle.app cannot be opened because Apple cannot check it for malicious software"
|
|
- **Workaround:** Right-click → Open → Open (one-time per user/machine)
|
|
- Or: System Settings → Privacy & Security → "Open Anyway" button after the first blocked attempt
|
|
- Frame this in the pilot installer email: *"Right-click → Open the first time. Apple notarization is in progress; this is an internal build."*
|
|
|
|
### 1.3 Pilot user comms template
|
|
|
|
Subject: **Welcome to Waggle Wave-1 — install + first-run notes**
|
|
|
|
> Hi [name],
|
|
>
|
|
> You're in the first pilot wave. The build is signed with our internal Egzakta certificate, which means your OS will warn you the first time you run it. This is expected — it's the same warning you'd get installing any new internal tool.
|
|
>
|
|
> **Windows:** download → run installer → on the SmartScreen warning, click "More info" then "Run anyway."
|
|
> **Mac:** download `.zip` → unzip → right-click `Waggle.app` → Open → Open. (Yes, twice "Open." That's the one-time Gatekeeper handshake.)
|
|
>
|
|
> Your `.mind/` data stays local — see attached one-pager on pilot data handling.
|
|
>
|
|
> Reply with your first task you'd like to do in Waggle. I'll watch the trace.
|
|
|
|
---
|
|
|
|
## 2. Public Day 0 prep — real certificates (start by T+15 = 2026-05-21)
|
|
|
|
### 2.1 Windows Authenticode
|
|
|
|
**Vendor options (price + lead time):**
|
|
|
|
| Vendor | OV (1yr) | EV (1yr) | Lead | SmartScreen reputation |
|
|
|---|---|---|---|---|
|
|
| SSL.com | ~$179 | ~$249 | 3-7 biz days | EV = instant; OV = builds over months |
|
|
| Sectigo / Comodo | ~$199 | ~$329 | 5-10 biz days | Same |
|
|
| DigiCert | ~$474 | ~$599 | 1-3 biz days | Same |
|
|
| GlobalSign | ~$259 | ~$439 | 5-10 biz days | Same |
|
|
|
|
**Recommendation: SSL.com EV Authenticode (~$249/yr).**
|
|
- EV gives instant SmartScreen trust (no warning on first install)
|
|
- SSL.com is fastest of the cheap-tier vendors
|
|
- EV requires a hardware token (USB HSM) shipped to you OR cloud-HSM for CI signing
|
|
- Tauri 2.0 supports Azure Key Vault for cloud-HSM signing — recommended for CI
|
|
|
|
**Verification you'll need to provide:**
|
|
- Egzakta Group business registration (APR)
|
|
- Egzakta Group D-U-N-S number (request free at dnb.com if not assigned)
|
|
- Phone verification call to a publicly listed Egzakta phone number
|
|
- Domain control proof for waggle-os.ai
|
|
|
|
**After receipt:**
|
|
- Replace `certificateThumbprint` in `tauri.conf.json` with the real cert's thumbprint
|
|
- Or use Azure Key Vault signing flow per Tauri docs
|
|
- Test sign + install on a fresh Win 11 VM; SmartScreen should pass without "More info" click
|
|
|
|
### 2.2 macOS — Apple Developer ID + Notarization
|
|
|
|
**Step 1: Enroll in Apple Developer Program ($99/yr).**
|
|
- Go to https://developer.apple.com/programs/enroll/
|
|
- Use Egzakta Group's Apple ID (create one tied to a generic ops@ address; do NOT use Marko's personal)
|
|
- Provide D-U-N-S number (same as Windows above)
|
|
- Lead time: 1-3 days for individual approval; 1-2 weeks for organization approval
|
|
|
|
**Step 2: Generate Developer ID certificates.**
|
|
- Xcode → Settings → Accounts → Manage Certificates → "+" → "Developer ID Application"
|
|
- Also create "Developer ID Installer" if you ship `.pkg`
|
|
|
|
**Step 3: App-specific password for notarytool.**
|
|
- https://appleid.apple.com → Sign-in and Security → App-Specific Passwords → Generate
|
|
- Label: `notarytool-waggle-ci`
|
|
- Copy the password — it shows only once
|
|
|
|
**Step 4: Sign + notarize.**
|
|
|
|
```bash
|
|
# Sign
|
|
codesign --force --deep --options runtime \
|
|
--sign "Developer ID Application: Egzakta Group (TEAMID)" \
|
|
/path/to/Waggle.app
|
|
|
|
# Zip for notarization
|
|
ditto -c -k --keepParent Waggle.app Waggle.zip
|
|
|
|
# Submit for notarization
|
|
xcrun notarytool submit Waggle.zip \
|
|
--apple-id "ops@egzakta.com" \
|
|
--team-id "TEAMID" \
|
|
--password "APP_SPECIFIC_PASSWORD" \
|
|
--wait
|
|
|
|
# After approval (5-30 min typical):
|
|
xcrun stapler staple Waggle.app
|
|
```
|
|
|
|
**Tauri config:**
|
|
|
|
```json
|
|
{
|
|
"bundle": {
|
|
"macOS": {
|
|
"signingIdentity": "Developer ID Application: Egzakta Group (TEAMID)",
|
|
"providerShortName": "TEAMID",
|
|
"entitlements": "./entitlements.plist"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**`entitlements.plist`** (allow JIT + outbound network for sidecar):
|
|
|
|
```xml
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
|
<plist version="1.0">
|
|
<dict>
|
|
<key>com.apple.security.cs.allow-jit</key><true/>
|
|
<key>com.apple.security.cs.allow-unsigned-executable-memory</key><true/>
|
|
<key>com.apple.security.network.client</key><true/>
|
|
<key>com.apple.security.network.server</key><true/>
|
|
<key>com.apple.security.files.user-selected.read-write</key><true/>
|
|
</dict>
|
|
</plist>
|
|
```
|
|
|
|
After notarization + stapling, Mac users see no warning on first launch — `.dmg` distribution becomes safe.
|
|
|
|
---
|
|
|
|
## 3. CI integration (post-pilot, before public Day 0)
|
|
|
|
**Target state:** every `main`-branch tag triggers signed builds for both platforms.
|
|
|
|
**Windows (GitHub Actions sketch):**
|
|
|
|
```yaml
|
|
- name: Sign Windows artifacts
|
|
shell: pwsh
|
|
run: |
|
|
# Use Azure Key Vault for cloud-HSM signing (EV cert lives in Key Vault)
|
|
az login --service-principal -u $env:AZURE_CLIENT_ID -p $env:AZURE_CLIENT_SECRET --tenant $env:AZURE_TENANT_ID
|
|
AzureSignTool sign -kvu "$env:KEY_VAULT_URL" -kvc "$env:CERT_NAME" `
|
|
-kva "$env:AZURE_CLIENT_ID" -kvs "$env:AZURE_CLIENT_SECRET" -kvt "$env:AZURE_TENANT_ID" `
|
|
-tr "http://timestamp.digicert.com" -td sha256 `
|
|
"src-tauri/target/release/bundle/msi/Waggle_*.msi"
|
|
```
|
|
|
|
Secrets needed in GH Actions env: `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, `AZURE_TENANT_ID`, `KEY_VAULT_URL`, `CERT_NAME`.
|
|
|
|
**macOS (GitHub Actions sketch):**
|
|
|
|
```yaml
|
|
- name: Import Apple cert
|
|
env:
|
|
DEV_CERT_P12_BASE64: ${{ secrets.APPLE_DEVID_P12_BASE64 }}
|
|
DEV_CERT_PASSWORD: ${{ secrets.APPLE_DEVID_P12_PASSWORD }}
|
|
KEYCHAIN_PASSWORD: ${{ secrets.MAC_KEYCHAIN_PASSWORD }}
|
|
run: |
|
|
echo "$DEV_CERT_P12_BASE64" | base64 -d > cert.p12
|
|
security create-keychain -p "$KEYCHAIN_PASSWORD" build.keychain
|
|
security default-keychain -s build.keychain
|
|
security unlock-keychain -p "$KEYCHAIN_PASSWORD" build.keychain
|
|
security import cert.p12 -P "$DEV_CERT_PASSWORD" -k build.keychain -T /usr/bin/codesign
|
|
security set-key-partition-list -S apple-tool:,apple: -s -k "$KEYCHAIN_PASSWORD" build.keychain
|
|
|
|
- name: Build, sign, notarize
|
|
env:
|
|
APPLE_ID: ${{ secrets.APPLE_ID }}
|
|
APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
|
|
APPLE_APP_PASSWORD: ${{ secrets.APPLE_APP_PASSWORD }}
|
|
run: |
|
|
npm run tauri build -- --target universal-apple-darwin
|
|
xcrun notarytool submit "src-tauri/target/universal-apple-darwin/release/bundle/macos/Waggle.app.zip" \
|
|
--apple-id "$APPLE_ID" --team-id "$APPLE_TEAM_ID" --password "$APPLE_APP_PASSWORD" --wait
|
|
xcrun stapler staple "src-tauri/target/universal-apple-darwin/release/bundle/macos/Waggle.app"
|
|
```
|
|
|
|
---
|
|
|
|
## 4. Timeline
|
|
|
|
| T+ | Date | Action |
|
|
|---|---|---|
|
|
| 0 | 2026-05-07 | Decision locked: self-sign for pilot, real certs for public Day 0 |
|
|
| 5 | 2026-05-12 | Generate self-sign certs (Win + Mac), update `tauri.build-override.conf.json` (now scripted via LAUNCH-06 wrappers), build pilot binaries |
|
|
| 9 | 2026-05-16 | **Pilot Wave-1 ship** with self-signed binaries + comms template §1.3 |
|
|
| 14 | 2026-05-21 | **Start cert procurement** — SSL.com EV Authenticode + Apple Developer Program enrollment |
|
|
| 21 | 2026-05-28 | Real certs in hand (assumes 7-day worst case) — replace thumbprints, rebuild, smoke-test |
|
|
| 25 | 2026-06-01 | Final notarization + signed-build CI green |
|
|
| 28-30 | 2026-06-05 | **Public Day 0** with fully-trusted signed binaries on both platforms |
|
|
|
|
## 5. Costs (year 1)
|
|
|
|
| Item | Cost |
|
|
|---|---|
|
|
| SSL.com EV Authenticode (Win, 1yr) | ~$249 |
|
|
| SSL.com USB HSM token (one-time) | ~$50, OR Azure Key Vault HSM ~$1.50/key/month |
|
|
| Apple Developer Program (Mac, 1yr) | $99 |
|
|
| D-U-N-S number | $0 (free request) |
|
|
| **Total Y1 minimum** | **~$348-400** |
|
|
|
|
Renewals: ~$348/yr ongoing. Tauri auto-updater also expects signed binaries — same certs cover that.
|
|
|
|
## 6. Failure modes + mitigations
|
|
|
|
| Failure | Symptom | Fix |
|
|
|---|---|---|
|
|
| Self-sign cert expired during pilot | Users get "certificate has expired" warning | Re-run `npm run tauri:sign:pilot:win:setup` (script reuses cert if still valid; generates a new one when NotAfter has passed); rerun apply + rebuild; redistribute installer |
|
|
| EV cert vendor demands more verification | Procurement slips past 2026-05-21 | Switch to OV ($179, faster) — accept slower SmartScreen reputation buildup |
|
|
| Notarization fails on a specific binary | Apple rejects with malware-pattern false positive | `xcrun notarytool log` for details; usually a sidecar binary needs `--options runtime` |
|
|
| Apple Developer Program enrollment delayed | Org approval takes 2 weeks | Enroll as individual under Marko's name first, transfer to org post-launch (allowed) |
|
|
| Win cert lost / HSM lost | Can't sign new builds | Re-purchase ($249); re-issue; old signed binaries remain valid until expiry |
|
|
|
|
---
|
|
|
|
## 7. References
|
|
|
|
- Tauri 2.0 signing docs: https://tauri.app/v1/guides/distribution/sign-windows + sign-macos
|
|
- Apple notarytool docs: https://developer.apple.com/documentation/security/customizing_the_notarization_workflow
|
|
- SSL.com Authenticode order page: https://www.ssl.com/certificates/code-signing/
|
|
- Microsoft signtool reference: https://learn.microsoft.com/en-us/windows/win32/seccrypto/signtool
|
|
- AzureSignTool (cloud HSM signing): https://github.com/vcsjones/AzureSignTool
|
|
|
|
---
|
|
|
|
Last updated: 2026-05-10 — LAUNCH-06 self-sign automation landed (Phase 2 Step 4). §1.1 now points to the npm-wrapped scripts (`tauri:sign:pilot:win:setup` / `:apply` / `:sign`) backed by `app/scripts/sign-windows-pilot.ps1`, `apply-signing-config.mjs`, and the tested `signing-config.ts` utility. §1.2 ships the macOS ad-hoc identity in the build-override config by default; `tauri:sign:pilot:mac:adhoc` re-signs nested helpers post-build.
|
|
Owner: Marko Marković (driving via CC); pilot self-sign actionable T+5; real cert procurement actionable T+14.
|