oleg.m/waggle-os

Fork 0

Files

Oleg Maslov 0c3e2ead3b

Installer Smoke / installer-smoke (push) Has been cancelled

Details

moving

2026-09-02 10:10:29 +02:00

14 KiB

Raw Blame History

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/:

# 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:

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):

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.

# 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:

{
  "bundle": {
    "macOS": {
      "signingIdentity": "Developer ID Application: Egzakta Group (TEAMID)",
      "providerShortName": "TEAMID",
      "entitlements": "./entitlements.plist"
    }
  }
}

entitlements.plist (allow JIT + outbound network for sidecar):

<?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):

- 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):

- 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.

14 KiB Raw Blame History