From 6f3c79f3f0ffc888fe963f2de07de6646830ab76 Mon Sep 17 00:00:00 2001 From: Han Ngo Date: Mon, 16 Nov 2026 02:02:48 +0700 Subject: [PATCH 1/7] feat(scripts): release.sh builds and verifies the direct release artifacts One command for the GitHub (Sparkle) release: preflight, tests, archive and export, app checks, notarize and staple, zips, EdDSA sign, appcast, smoke test with host restore, and a checks.md with one row per check. It never tags, uploads or publishes; gh and git are wrapped to read verbs only. - release-helper.swift: Ed25519 verify (CryptoKit), the appcast item, and a merge that keeps every prior item byte-identical. - --check-app runs every app row; the sandbox row counts only after the Developer ID identity row passes, so an ad-hoc build cannot pass vacuously. - SUPublicEDKey, SUFeedURL and the Sparkle tarball digest are pinned. - test-release.sh: offline cases with fixtures and PATH stubs. - RUNBOOK: step 3 points at the script; the manual sandbox check now checks the Developer ID signature first, then the entitlement. - QUALITY.md: Q-REL-1 (no key material) and Q-REL-2 (prior items verbatim). --- docs/QUALITY.md | 10 + docs/RUNBOOK.md | 43 +- scripts/fixtures/release/item-1.12.0.expected | 18 + scripts/fixtures/release/notes-1.12.0.html | 7 + scripts/fixtures/release/payload.bin | 1 + scripts/fixtures/release/payload.sig.b64 | 1 + scripts/fixtures/release/prior-1.xml | 26 + scripts/fixtures/release/prior-2.xml | 44 + scripts/fixtures/release/pub.b64 | 1 + scripts/fixtures/release/wrongkey.pub.b64 | 1 + scripts/release-helper.swift | 254 +++++ scripts/release.sh | 879 ++++++++++++++++++ scripts/test-release.sh | 398 ++++++++ 13 files changed, 1676 insertions(+), 7 deletions(-) create mode 100644 docs/QUALITY.md create mode 100644 scripts/fixtures/release/item-1.12.0.expected create mode 100644 scripts/fixtures/release/notes-1.12.0.html create mode 100644 scripts/fixtures/release/payload.bin create mode 100644 scripts/fixtures/release/payload.sig.b64 create mode 100644 scripts/fixtures/release/prior-1.xml create mode 100644 scripts/fixtures/release/prior-2.xml create mode 100644 scripts/fixtures/release/pub.b64 create mode 100644 scripts/fixtures/release/wrongkey.pub.b64 create mode 100644 scripts/release-helper.swift create mode 100755 scripts/release.sh create mode 100755 scripts/test-release.sh diff --git a/docs/QUALITY.md b/docs/QUALITY.md new file mode 100644 index 00000000..9e18ec47 --- /dev/null +++ b/docs/QUALITY.md @@ -0,0 +1,10 @@ +# Quality requirements + +Each entry names a scenario, the required response, how it is measured, and the check that proves it. + +## Release + +| ID | Attribute | Scenario | Response | Measure | Check | +|---|---|---|---|---|---| +| Q-REL-1 | security | a full `scripts/release.sh` run | no ASC API key or Sparkle EdDSA private key value appears in stdout, stderr, `checks.md`, or any file left under `--out` or the temp dir after exit | 0 hits | the "No key material left" row of every `checks.md`; `secrets-cleanup-on-failure`, `leak-scan-detects` and `refuse-xtrace` in `scripts/test-release.sh` | +| Q-REL-2 | integrity | a release run with N published prior appcast items | the new appcast holds N+1 items, each prior item byte-identical, each enclosure signature valid against the shipped `SUPublicEDKey` | N of N identical, N+1 of N+1 VALID | the "Prior items verbatim" and "Enclosure" rows of `checks.md`; the `appcast-*` and `cut-cmp-*` cases in `scripts/test-release.sh` | diff --git a/docs/RUNBOOK.md b/docs/RUNBOOK.md index 655a512c..45e2561c 100644 --- a/docs/RUNBOOK.md +++ b/docs/RUNBOOK.md @@ -106,15 +106,35 @@ the real `/Applications`). Never judge arrow or hiding behaviour on a copy outsi (every occurrence: the App Store target's four configurations plus the Direct target's four; `grep -c MARKETING_VERSION` must match the count you edited). -3. Archive the GitHub build with the **Hidden Bar** scheme - (`Release-Direct`; builds the **Hidden Bar Direct** target), then notarize (Developer ID), staple, zip, and publish a - GitHub release with notes listing closed issues. The **Hidden Bar App Store** - scheme archives `Release`, the sandboxed App Store build, which cannot hide - on macOS 27. v1.11 shipped that build to GitHub by mistake. Before zipping, - confirm the app is unsandboxed: +3. Build the GitHub release artifacts with one command, on the Mac mini, from a + clean tree at the release commit: ```sh - codesign -d --entitlements - 'Hidden Bar.app' | grep app-sandbox # must print nothing + scripts/release.sh --notes notes.html # for the appcast item + ``` + + It runs the tests, archives the **Hidden Bar** scheme (`Release-Direct`; + builds the **Hidden Bar Direct** target), checks the app, notarizes, + staples, zips, EdDSA-signs, builds `appcast.xml`, smoke-tests the zip with + a host restore, and writes `build/release-/checks.md` with one row + per check. It never tags, uploads or publishes; `checks.md` ends with the + publish commands as text. `scripts/release.sh --check-app ` runs the + app checks alone on any bundle; `bash scripts/test-release.sh` tests the + script offline. The steps below are what the script does, for a manual + run or when the script is broken on release day. + + The **Hidden Bar App Store** scheme archives `Release`, the sandboxed App + Store build, which cannot hide on macOS 27. v1.11 shipped that build to + GitHub by mistake. Before zipping, confirm the app is signed Developer ID + first, then that it is unsandboxed. The order matters: an ad-hoc or + unsigned build has no entitlements, so the sandbox grep alone prints + nothing and passes on the wrong build. + + ```sh + codesign -dvv 'Hidden Bar.app' 2>&1 | grep -E '^Authority=Developer ID Application: .*\(W777S7V8TN\)$|^Timestamp=|flags=.*runtime' + # must print 3 lines: the Developer ID authority, a Timestamp, and runtime flags + codesign -d --entitlements - --xml 'Hidden Bar.app' # must print a plist ... + codesign -d --entitlements - --xml 'Hidden Bar.app' | grep -c app-sandbox # ... and this must print 0 ``` The target signs automatically for development, so a plain archive fails @@ -151,6 +171,15 @@ lives in 1Password (`dfoundation-prod`, item "Hidden Bar Sparkle EdDSA private key"); only the public key (`SUPublicEDKey`) is in the repo. Losing the key means no installed copy can ever verify another update, so never regenerate it. +`scripts/release.sh` does steps 1 to 3 below and writes the zips and +`appcast.xml` under `build/release-/`: it signs with `sign_update` +from the pinned Sparkle tarball (sha256 checked every run), verifies every +enclosure against `SUPublicEDKey` (pinned in the script), and builds the +appcast by prepending the new item to the latest published `appcast.xml`, so +every prior item stays byte-identical (it does not use `generate_appcast`, +which rewrites prior items). Steps 4 and 5, the upload and publish, stay +manual; `checks.md` prints them. The manual commands, for reference: + Sparkle's `sign_update` and `generate_appcast` come from the Sparkle release tarball matching the pinned package version (2.10.1, `Sparkle-.tar.xz` under `bin/`). Run from a folder that holds only the zip(s) to publish: diff --git a/scripts/fixtures/release/item-1.12.0.expected b/scripts/fixtures/release/item-1.12.0.expected new file mode 100644 index 00000000..95c88c57 --- /dev/null +++ b/scripts/fixtures/release/item-1.12.0.expected @@ -0,0 +1,18 @@ + + Version 1.12.0 + Sun, 15 Nov 2026 16:33:08 GMT + 19 + 1.12.0 + 13.0 + https://github.com/dwarvesf/hidden/releases/tag/v1.12.0 + +
  • A redesigned Settings window.
  • +
  • Hiding works again while an app keeps the microphone open (Wispr Flow, Krisp, Discord...).
  • +
  • Switching from the App Store version offers to import your settings.
  • +
  • macOS 27: pinned sections (beta) keep icons where you put them after apps restart.
  • +
  • Fixes for macOS 26 and earlier.
  • + +]]>
    + +
    diff --git a/scripts/fixtures/release/notes-1.12.0.html b/scripts/fixtures/release/notes-1.12.0.html new file mode 100644 index 00000000..51037f46 --- /dev/null +++ b/scripts/fixtures/release/notes-1.12.0.html @@ -0,0 +1,7 @@ +
      +
    • A redesigned Settings window.
    • +
    • Hiding works again while an app keeps the microphone open (Wispr Flow, Krisp, Discord...).
    • +
    • Switching from the App Store version offers to import your settings.
    • +
    • macOS 27: pinned sections (beta) keep icons where you put them after apps restart.
    • +
    • Fixes for macOS 26 and earlier.
    • +
    diff --git a/scripts/fixtures/release/payload.bin b/scripts/fixtures/release/payload.bin new file mode 100644 index 00000000..957287fd --- /dev/null +++ b/scripts/fixtures/release/payload.bin @@ -0,0 +1 @@ +Hidden Bar release-script fixture payload diff --git a/scripts/fixtures/release/payload.sig.b64 b/scripts/fixtures/release/payload.sig.b64 new file mode 100644 index 00000000..b4b8ae5c --- /dev/null +++ b/scripts/fixtures/release/payload.sig.b64 @@ -0,0 +1 @@ +qAsECvbmtEMdTEWB3C8crQ3PZy4JhXBRbEfZjgZ3rYmzYP+WKIJJXoH6PxsYag7/J+yKZH79EuU5mlNfe6zTBQ== diff --git a/scripts/fixtures/release/prior-1.xml b/scripts/fixtures/release/prior-1.xml new file mode 100644 index 00000000..429f89dd --- /dev/null +++ b/scripts/fixtures/release/prior-1.xml @@ -0,0 +1,26 @@ + + + + Hidden Bar + https://github.com/dwarvesf/hidden + Hidden Bar updates + en + + Version 1.11.2 + Sun, 15 Nov 2026 06:50:21 GMT + 17 + 1.11.2 + 13.0 + https://github.com/dwarvesf/hidden/releases/tag/v1.11.2 + +
  • macOS 27: clicking the clock opens Notification Center again.
  • +
  • Icons you keep right of the arrow stay visible.
  • +
  • Microphone and camera indicators are no longer hidden.
  • +
  • Multi-display fixes, auto-update, and Turkish, Ukrainian and Italian translations.
  • + +]]>
    + +
    +
    +
    diff --git a/scripts/fixtures/release/prior-2.xml b/scripts/fixtures/release/prior-2.xml new file mode 100644 index 00000000..66a06907 --- /dev/null +++ b/scripts/fixtures/release/prior-2.xml @@ -0,0 +1,44 @@ + + + + Hidden Bar + https://github.com/dwarvesf/hidden + Hidden Bar updates + en + + Version 1.12.0 + Sun, 15 Nov 2026 16:33:08 GMT + 19 + 1.12.0 + 13.0 + https://github.com/dwarvesf/hidden/releases/tag/v1.12.0 + +
  • A redesigned Settings window.
  • +
  • Hiding works again while an app keeps the microphone open (Wispr Flow, Krisp, Discord...).
  • +
  • Switching from the App Store version offers to import your settings.
  • +
  • macOS 27: pinned sections (beta) keep icons where you put them after apps restart.
  • +
  • Fixes for macOS 26 and earlier.
  • + +]]>
    + +
    + + Version 1.11.2 + Sun, 15 Nov 2026 06:50:21 GMT + 17 + 1.11.2 + 13.0 + https://github.com/dwarvesf/hidden/releases/tag/v1.11.2 + +
  • macOS 27: clicking the clock opens Notification Center again.
  • +
  • Icons you keep right of the arrow stay visible.
  • +
  • Microphone and camera indicators are no longer hidden.
  • +
  • Multi-display fixes, auto-update, and Turkish, Ukrainian and Italian translations.
  • + +]]>
    + +
    +
    +
    diff --git a/scripts/fixtures/release/pub.b64 b/scripts/fixtures/release/pub.b64 new file mode 100644 index 00000000..7e2ae45d --- /dev/null +++ b/scripts/fixtures/release/pub.b64 @@ -0,0 +1 @@ +W7SukNcz0ZbDXDm/XnJgtc8RTz7s9OrSWaST/rz6EmU= diff --git a/scripts/fixtures/release/wrongkey.pub.b64 b/scripts/fixtures/release/wrongkey.pub.b64 new file mode 100644 index 00000000..ae0f5b58 --- /dev/null +++ b/scripts/fixtures/release/wrongkey.pub.b64 @@ -0,0 +1 @@ +4wa+sFG3gaWUVoA5U9Tru+uTFe/x+r4eSx9I7cI0Md4= diff --git a/scripts/release-helper.swift b/scripts/release-helper.swift new file mode 100644 index 00000000..cce092c8 --- /dev/null +++ b/scripts/release-helper.swift @@ -0,0 +1,254 @@ +// scripts/release-helper.swift : the release jobs bash does badly. +// +// verify Ed25519 check. Exit 0 VALID, 1 INVALID, 2 bad input. +// item --version --short --min-os --notes --url +// --length --sig --pubdate --link +// print the new appcast text. +// appcast --prior --item --out +// prepend the item; every prior item stays byte-identical. +// Exit 1 on a version collision, 2 on an unexpected feed shape. +// sigs one "version TAB short TAB url TAB length TAB signature" +// line per item, file mode 600. +// +// Run as `swift scripts/release-helper.swift ...` or compile once with swiftc. +import CryptoKit +import Foundation + +func fail(_ code: Int32, _ message: String) -> Never { + FileHandle.standardError.write(("release-helper: " + message + "\n").data(using: .utf8)!) + exit(code) +} + +func readText(_ path: String) -> String { + guard let data = FileManager.default.contents(atPath: path) else { fail(2, "cannot read \(path)") } + guard let text = String(data: data, encoding: .utf8) else { fail(2, "\(path) is not UTF-8") } + return text +} + +func options(_ args: ArraySlice, _ names: [String]) -> [String: String] { + var out: [String: String] = [:] + var it = args.makeIterator() + while let key = it.next() { + guard key.hasPrefix("--"), names.contains(String(key.dropFirst(2))) else { fail(2, "unknown option \(key)") } + guard let value = it.next() else { fail(2, "\(key) needs a value") } + out[String(key.dropFirst(2))] = value + } + for name in names where out[name] == nil { fail(2, "missing --\(name)") } + return out +} + +// MARK: feed parsing + +let itemOpen = " " +let itemClose = " " + +struct Item { + let range: Range // from the start of the line to the end of the line + var text: Substring +} + +/// Find each item as the lines that are exactly ` ` and ` `, outside CDATA. +/// Refuses (exit 2) a feed whose shape it would have to guess at. +func items(in feed: String, name: String) -> [Item] { + if feed.contains("\r") { fail(2, "\(name): CR bytes (CRLF line endings) are not supported") } + var found: [Item] = [] + var inCDATA = false + var start: String.Index? + var lineStart = feed.startIndex + while lineStart < feed.endIndex { + let lineEnd = feed[lineStart...].firstIndex(of: "\n").map { feed.index(after: $0) } ?? feed.endIndex + let line = feed[lineStart.. opened twice without ") } + start = lineStart + } else if bare == itemClose { + guard let s = start else { fail(2, "\(name): without ") } + found.append(Item(range: s.. tag at an unexpected indent: \(bare.trimmingCharacters(in: .whitespaces))") + } + } + inCDATA = cdataStateAfter(line, startingIn: inCDATA) + lineStart = lineEnd + } + if start != nil { fail(2, "\(name): never closed") } + if inCDATA { fail(2, "\(name): CDATA never closed") } + return found +} + +/// The text of one line that is outside CDATA, assuming the line starts outside CDATA. +func outsideCDATA(_ line: Substring) -> String { + var out = "" + var rest = line + while let open = rest.range(of: "") else { return out } + rest = rest[close.upperBound...] + } + return out + rest +} + +func cdataStateAfter(_ line: Substring, startingIn inside: Bool) -> Bool { + var inside = inside + var rest = line + while true { + let marker = inside ? "]]>" : " String { + var out = "" + var rest = text + while let open = rest.range(of: "") else { return out } + rest = rest[close.upperBound...] + } + return out + rest +} + +func element(_ name: String, in text: String) -> String? { + guard let open = text.range(of: "<\(name)>"), + let close = text.range(of: "", range: open.upperBound.. String? { + guard let enc = text.range(of: "") else { return nil } + let tag = " " + tail[.. "9", "1.10" > "1.9"). +func compareVersions(_ a: String, _ b: String) -> Int { + let pa = a.split(separator: ".").map { Int($0) ?? -1 } + let pb = b.split(separator: ".").map { Int($0) ?? -1 } + for i in 0.. String { + s.replacingOccurrences(of: "&", with: "&").replacingOccurrences(of: "<", with: "<") + .replacingOccurrences(of: ">", with: ">").replacingOccurrences(of: "\"", with: """) +} + +func requireMatch(_ value: String, _ pattern: String, _ what: String) { + if value.range(of: pattern, options: .regularExpression) == nil { fail(2, "\(what) '\(value)' does not match \(pattern)") } +} + +// MARK: subcommands + +let args = CommandLine.arguments +guard args.count >= 2 else { fail(2, "usage: release-helper verify|item|appcast|sigs ...") } + +switch args[1] { +case "verify": + guard args.count == 5, + let data = FileManager.default.contents(atPath: args[2]), + let sig = Data(base64Encoded: args[3]), + let pubRaw = Data(base64Encoded: args[4]), + let pub = try? Curve25519.Signing.PublicKey(rawRepresentation: pubRaw) else { + print("release-helper verify: bad input"); exit(2) + } + let ok = pub.isValidSignature(sig, for: data) + print(ok ? "VALID" : "INVALID") + exit(ok ? 0 : 1) + +case "item": + let o = options(args.dropFirst(2), ["version", "short", "min-os", "notes", "url", "length", "sig", "pubdate", "link"]) + requireMatch(o["version"]!, "^[0-9]+(\\.[0-9]+)*$", "--version") + requireMatch(o["short"]!, "^[0-9]+\\.[0-9]+(\\.[0-9]+)?$", "--short") + requireMatch(o["min-os"]!, "^[0-9]+(\\.[0-9]+)*$", "--min-os") + requireMatch(o["length"]!, "^[0-9]+$", "--length") + requireMatch(o["sig"]!, "^[A-Za-z0-9+/]+={0,2}$", "--sig") + requireMatch(o["url"]!, "^https://[A-Za-z0-9./_-]+$", "--url") + requireMatch(o["link"]!, "^https://[A-Za-z0-9./_-]+$", "--link") + requireMatch(o["pubdate"]!, "^[A-Z][a-z]{2}, [0-9]{2} [A-Z][a-z]{2} [0-9]{4} [0-9]{2}:[0-9]{2}:[0-9]{2} GMT$", "--pubdate") + var notes = readText(o["notes"]!) + if notes.contains("]]>") { fail(2, "notes contain ]]>, which would end the CDATA") } + if notes.contains(" tag") } + if notes.contains("\r") { fail(2, "notes contain CR bytes") } + while notes.hasSuffix("\n") { notes.removeLast() } + if notes.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty { fail(2, "notes are empty") } + let short = o["short"]! + print(""" + + Version \(short) + \(o["pubdate"]!) + \(o["version"]!) + \(short) + \(o["min-os"]!) + \(xmlEscape(o["link"]!)) + + + + """) + +case "appcast": + let o = options(args.dropFirst(2), ["prior", "item", "out"]) + let prior = readText(o["prior"]!) + let newItemText = readText(o["item"]!) + let priorItems = items(in: prior, name: "prior appcast") + if priorItems.isEmpty { fail(2, "prior appcast has no items; refusing to start a feed from nothing") } + let newItems = items(in: newItemText, name: "new item") + guard newItems.count == 1, newItems[0].range.lowerBound == newItemText.startIndex, + newItems[0].range.upperBound == newItemText.endIndex else { fail(2, "new item file must hold exactly one item and nothing else") } + let newFields = stripCDATA(newItems[0].text) + guard let newBuild = element("sparkle:version", in: newFields), + let newShort = element("sparkle:shortVersionString", in: newFields) else { fail(2, "new item lacks sparkle:version or shortVersionString") } + for item in priorItems { + let fields = stripCDATA(item.text) + guard let build = element("sparkle:version", in: fields), + let short = element("sparkle:shortVersionString", in: fields) else { fail(2, "a prior item lacks sparkle:version or shortVersionString") } + if compareVersions(newBuild, build) <= 0 { + fail(1, "new build \(newBuild) is not above prior item \(short) (build \(build))") + } + if newShort == short { fail(1, "prior item already has shortVersionString \(short) (build \(build))") } + } + let insertAt = priorItems[0].range.lowerBound + let out = String(prior[.. ") } + let feed = readText(args[2]) + var lines = "" + for item in items(in: feed, name: args[2]) { + let fields = stripCDATA(item.text) + let row = [element("sparkle:version", in: fields), element("sparkle:shortVersionString", in: fields), + enclosureAttribute("url", in: fields), enclosureAttribute("length", in: fields), + enclosureAttribute("sparkle:edSignature", in: fields)] + let values = row.compactMap { $0 } + if values.count != 5 { fail(2, "an item lacks a version, url, length or signature") } + if values.contains(where: { $0.rangeOfCharacter(from: .controlCharacters) != nil || $0.isEmpty }) { + fail(2, "an item field is empty or holds a control character") + } + lines += values.joined(separator: "\t") + "\n" + } + let fm = FileManager.default + if !fm.createFile(atPath: args[3], contents: lines.data(using: .utf8), attributes: [.posixPermissions: 0o600]) { + fail(2, "cannot write \(args[3])") + } + +default: + fail(2, "unknown subcommand \(args[1])") +} diff --git a/scripts/release.sh b/scripts/release.sh new file mode 100755 index 00000000..45e034fd --- /dev/null +++ b/scripts/release.sh @@ -0,0 +1,879 @@ +#!/bin/bash +# scripts/release.sh : build and verify the direct (GitHub, Sparkle) release artifacts. +# +# scripts/release.sh --notes [--out ] [--skip-tests] [--no-smoke] +# scripts/release.sh --check-app