From e9760b8514dc255d2b0834abe4b2ec745758ef12 Mon Sep 17 00:00:00 2001 From: "mula.liu" Date: Mon, 26 Oct 2026 09:22:39 +0800 Subject: [PATCH] release: publish a macOS .pkg so a fresh machine can open Shift MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Builds are signed with the self-signed "Shift Local Signing" identity and are not notarized, so Gatekeeper calls Shift an unidentified developer. Dragging the app out of the DMG hands that verdict to the app: a fresh machine refuses the first launch until the user approves it in 系统设置 → 隐私与安全性. `scripts/macos-pkg.sh` wraps the built bundle with pkgbuild and the channel now publishes `Shift-macOS-universal.pkg` alongside the DMG. Verified rather than assumed: installing a quarantined copy of the package leaves the installed app with only `com.apple.provenance` — no `com.apple.quarantine` — and `codesign --verify --deep --strict` still passes, because pkgbuild neither re-signs nor strips the payload (CDHash identical across built bundle, DMG copy and pkg copy: 3b7fac6c…). The package is unsigned because `productsign` needs an Installer Signing certificate and this build has only a code-signing identity, so the approval does not vanish — it moves to the download, once, before anything is installed. `installer -pkg … -target /` needs no approval at all. The `macos` manifest key stays a DMG on purpose: `update_install`'s handoff mounts the image with hdiutil, so pointing the key at a .pkg would break in-app updates. --- README.md | 2 ++ README.zh-CN.md | 2 ++ docs/RELEASE.md | 59 ++++++++++++++++++++++++++++++++++++++++---- docs/ROADMAP.md | 6 +++++ scripts/macos-pkg.sh | 44 +++++++++++++++++++++++++++++++++ 5 files changed, 108 insertions(+), 5 deletions(-) create mode 100755 scripts/macos-pkg.sh diff --git a/README.md b/README.md index b0a09bf..e9c3f81 100644 --- a/README.md +++ b/README.md @@ -292,6 +292,8 @@ Each is overridable in Settings. File actions offer a *collect everything in one ## Updates +A new macOS machine should install **`Shift-macOS-universal.pkg`**: builds are signed with a self-signed identity and not notarized, so Gatekeeper calls Shift an unidentified developer, and an installed package leaves the app free of the quarantine flag. If you install the disk image instead, the first launch needs one approval in System Settings → Privacy & Security. Details in `docs/RELEASE.md`. + The update channel is this repository: a `releases` branch holding the installers plus `shift-update.json`, which names each artifact, its size and its SHA256. The feed URL is derived from the git remote at build time - Gitea, GitHub and GitLab forms are known, and `SHIFT_UPDATE_URL` overrides it - so no update service has to be deployed anywhere. Once a day at startup, and on demand from Settings -> **Updates**, Shift reads the manifest, compares versions with semver rules including prereleases, and offers a download. A downloaded installer is checked twice before it can be installed: exact byte length, then a recomputed SHA256 that must match the manifest. A mismatch deletes the file and says so, so nothing half-downloaded launches. Publishing is one command, `scripts/publish-release.sh`, and `docs/RELEASE.md` covers the manifest format, the flags, and the difference between the integrity the hash proves and the authenticity a signed manifest adds (`--key` plus a key baked in with `SHIFT_UPDATE_PUBKEY`). diff --git a/README.zh-CN.md b/README.zh-CN.md index 1693088..81acc57 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -294,6 +294,8 @@ Shift 会持续维护局域网内其他 Shift 实例的列表,并据此提供 ## 软件更新 +新的 macOS 机器请安装 **`Shift-macOS-universal.pkg`**:本项目的构建使用自签名身份且未做公证,Gatekeeper 会把 Shift 判为身份不明的开发者,而通过安装包安装不会把隔离属性带给应用。若改用磁盘镜像安装,首次打开需要在「系统设置 → 隐私与安全性」里允许一次。详见 `docs/RELEASE.md`。 + 更新通道就是这个仓库:一条 `releases` 分支保存安装包以及 `shift-update.json` 清单,清单写明每个安装包的名称、体积与 SHA256。更新源地址在构建时由 git 远端推导——已适配 Gitea、GitHub、GitLab 三种形式,也可用 `SHIFT_UPDATE_URL` 覆盖——因此无需额外部署任何更新服务。 Shift 每天启动时检查一次(也可在设置 → **软件更新** 中手动检查),读取清单、按含预发布规则的 semver 比较版本,然后提供下载。下载完成的安装包在安装前要通过两道校验:字节数完全一致,以及重新计算的 SHA256 与清单一致。任一不符即删除文件并明确报错,因此半成品永远不会被启动。发布只需一条命令 `scripts/publish-release.sh`;`docs/RELEASE.md` 说明清单格式、参数,以及可选的 ed25519 清单签名——签名用来证明清单的来源,而不只是下载内容与清单一致。 diff --git a/docs/RELEASE.md b/docs/RELEASE.md index 6c05f54..b781641 100644 --- a/docs/RELEASE.md +++ b/docs/RELEASE.md @@ -39,7 +39,8 @@ not a code limit, and it decides what the channel may contain: | Key | Shipped | Notes | | --- | --- | --- | -| `macos` | yes | One universal bundle, Apple silicon and Intel | +| `macos` | yes | One universal bundle, Apple silicon and Intel. The DMG, because that is what the in-app updater mounts | +| — | yes | `Shift-macOS-universal.pkg`, also macOS universal: the file to hand a machine installing Shift for the first time. It carries no manifest key — see "macOS packaging" | | `windows` | yes | x64, which is also what an ARM machine falls back to | | `windows-arm64` | no | Buildable — `build-windows-release.sh --arch arm64` still works — just not published | | `linux` | no | Build target, not a product; see below | @@ -67,10 +68,53 @@ by a test rather than by a comment. The branch is rebuilt as a fresh root commit on every publish and force-pushed, so it never accumulates gigabytes of installer history while `main` stays clean. +## macOS packaging + +Shift builds are signed with a **self-signed** identity ("Shift Local Signing") and are +**not notarized** — notarization needs an Apple Developer ID account. Gatekeeper therefore +calls any Shift build an unidentified developer, and how annoying that is depends entirely +on the container: + +| Container | What a fresh machine does | +| --- | --- | +| DMG, app dragged into /Applications | The app itself carries the quarantine flag from the browser, so **the first launch of Shift** is refused: *"无法打开,因为来自身份不明的开发者"*. The user approves in 系统设置 → 隐私与安全性 (允许 / 仍要打开), or right-clicks the app and chooses 打开. | +| `.pkg`, installed with Installer.app or `installer` | The approval moves to the package, once, before anything is installed (double-click reports it, right-click → 打开 passes it, `installer` from a terminal needs nothing). `installer` does not propagate quarantine onto what it installs, so **the installed app launches with no prompt at all** — verified: an installed copy carries only `com.apple.provenance`, no `com.apple.quarantine`. | + +Both containers hold the same signed universal bundle — `pkgbuild` neither re-signs nor +strips the signature, and the payload passes `codesign --verify --deep --strict`. + +So the channel publishes both, for different jobs: + +- **`Shift-macOS-universal.pkg`** — first install on any machine. Build it with + `scripts/macos-pkg.sh `; it stages the bundle under a + `/Applications` root and runs `pkgbuild`, keeping the app's own signature. + The package itself is unsigned: `productsign` needs a certificate with the *Installer + Signing* purpose and this build has only a code-signing identity. A browser-downloaded + unsigned package is refused on a plain double-click, so the user approves it once — + right-click → 打开, or 仍要打开 in 系统设置 → 隐私与安全性. What the package changes is + *where* that single approval lands: on the download, before install, instead of on the + app every time it is opened. + `installer -pkg Shift-macOS-universal.pkg -target /` from a terminal needs no such + permission at all. +- **`Shift-macOS-universal.dmg`** — the `macos` manifest key, because + `update_install`'s handoff mounts the image with `hdiutil` and copies the bundle out of + it. Pointing the key at a `.pkg` would make that mount fail, so the key stays a DMG + until the updater learns to run `installer`. A DMG Shift downloads itself arrives without + a quarantine flag (`curl` sets none, and the handoff strips it anyway), which is why + in-app updates never trigger the prompt — it is only the browser download on a new + machine that does. + +Closing this for good means an Apple Developer ID: sign with `Developer ID Application`, +notarize with `notarytool`, and staple the ticket. Then both containers open on double-click +with no pane to visit, and Screen Recording approval stops resetting between builds because +the identity stops changing. + ## Publishing ```bash -pnpm tauri build … # bundles land in artifacts/ +pnpm tauri build --target universal-apple-darwin --bundles app,dmg +scripts/macos-pkg.sh src-tauri/target/universal-apple-darwin/release/bundle/macos/Shift.app \ + artifacts/Shift-macOS-universal.pkg # the first-install container printf 'Fixes the ring on external displays.\n' > /tmp/notes.md scripts/publish-release.sh --notes /tmp/notes.md # hash, commit, push ``` @@ -91,9 +135,11 @@ same Python pass that walks the files produces both. Recognised installers: `Shift-macOS-universal.dmg` (macOS), `Shift-Setup--win-x64.exe` and `Shift-Setup--win-arm64.exe` (Windows, keys `windows` and `windows-arm64`), -`*.AppImage` / `*.deb` (Linux). Other files in `artifacts/` — the portable ZIPs, -`SHA256SUMS.txt`, the `README-Windows-.txt` notes — travel with the branch but are -not offered as installers. Dotfiles and an old manifest are skipped. +`*.AppImage` / `*.deb` (Linux). Other files in `artifacts/` — the macOS `.pkg`, the portable +ZIPs, `SHA256SUMS.txt`, the `README-Windows-.txt` notes — travel with the branch and +are downloadable from it, but are not offered as installers by the manifest. The `.pkg` +carries no key on purpose: the `macos` key must stay a DMG so the in-app handoff can mount +it ("macOS packaging"). Dotfiles and an old manifest are skipped. Both Windows architectures come from one command, which cross-compiles each target, checks the PE machine field of the binary it just built (`0x8664` for x64, `0xAA64` for @@ -276,6 +322,9 @@ than trusting the local copy: | `windows-arm64` | not published | by choice — see "Supported release targets" | | `linux` | not published | by choice: Linux is a build target here, not a shipped product | +`Shift-macOS-universal.pkg` sits on the same branch with no manifest key, for first installs +("macOS packaging"); it was hashed the same way and downloaded back to check. + `shift-update.sig` verifies over the manifest's exact bytes against the key baked into both artifacts. The channel's home is derived from `origin` at build time, and this forge is Gitea, so the raw form is `/raw/branch/releases/`. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 3ded83b..a7a226f 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -105,6 +105,12 @@ names what is still missing. the older store's guess, then the legacy key is dropped so a later upgrade cannot resurrect rows the user has since removed. - Signed and notarized macOS package: pending (builds are signed with a local identity). + Until then the channel also publishes `Shift-macOS-universal.pkg`, because Gatekeeper + refuses an unnotarized app on first launch and `installer` does not leave the installed + copy quarantined — so the prompt moves to the download, once, instead of the app. The + `macos` manifest key stays a DMG so the in-app handoff can keep mounting it; see + "macOS packaging" in `docs/RELEASE.md`. Notarization needs a Developer ID account, and + it would also stop Screen Recording approval from resetting between builds. - Signed Windows installer: pending. - Manifest signing is done. `scripts/release-key.py` mints the release key, `publish-release.sh --key` publishes a detached `shift-update.sig` over the manifest's diff --git a/scripts/macos-pkg.sh b/scripts/macos-pkg.sh new file mode 100755 index 0000000..878ce64 --- /dev/null +++ b/scripts/macos-pkg.sh @@ -0,0 +1,44 @@ +#!/bin/bash +# Wrap a built Shift.app in a .pkg installer for the release channel. +# +# scripts/macos-pkg.sh [version] +# +# Why a package at all: this build is signed with a self-signed identity and is not +# notarized, so Gatekeeper calls it an unidentified developer. Dragging the app out of +# a disk image hands that verdict to the app itself, and a fresh machine refuses to open +# it until the user allows it in System Settings > Privacy & Security. `installer` does +# not propagate the quarantine flag onto what it installs, so a .pkg-installed copy +# launches with no prompt at all. The disk image stays the auto-update transport, which +# needs no administrator password; the package is what a new machine should install. +# +# The payload keeps the signature the app was built with; pkgbuild does not re-sign or +# strip it. An installer-signing identity would let the package itself be signed too, +# which needs a certificate with the Installer Signing purpose -- productsign rejects +# an application identity, and this repository's build has only that one. +set -euo pipefail + +APP="${1:?usage: $0 [version]}" +OUT="${2:?usage: $0 [version]}" +VERSION="${3:-$(plutil -extract CFBundleShortVersionString raw "$APP/Contents/Info.plist" 2>/dev/null || echo 0.0.0)}" + +[ -d "$APP" ] || { echo "not an app bundle: $APP" >&2; exit 2; } + +STAGE=$(mktemp -d /tmp/shift-pkg-stage.XXXXXX) +trap 'rm -rf "$STAGE"' EXIT +mkdir -p "$STAGE/Applications" +# ditto, not cp: it keeps resource forks, symlinks and code signatures intact. +ditto "$APP" "$STAGE/Applications/$(basename "$APP")" + +# install-location is the folder the payload is rooted at, so the app lands in +# /Applications for every user of the machine. +pkgbuild \ + --version "$VERSION" \ + --identifier "$(plutil -extract CFBundleIdentifier raw "$APP/Contents/Info.plist" 2>/dev/null || echo app.nex.shift)" \ + --install-location /Applications \ + --root "$STAGE/Applications" \ + --ownership preserve \ + "$OUT" + +echo "wrote $OUT ($(stat -f%z "$OUT") bytes, version $VERSION)" +echo "payload check:" +pkgutil --payload-files "$OUT" | head -4