diff --git a/README.md b/README.md index 48a57be..0e237dd 100644 --- a/README.md +++ b/README.md @@ -292,7 +292,7 @@ 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 ad-hoc signed and not notarized, so Gatekeeper calls Shift an unidentified developer, and an installed package leaves the app free of the quarantine flag - it opens with no prompt. From the disk image, the first launch needs one approval (right-click → Open, or 允许 in System Settings → Privacy & Security). Details in `docs/RELEASE.md`. +A new macOS machine installs **`Shift-macOS-universal.dmg`**: builds are ad-hoc signed and not notarized, so Gatekeeper calls Shift an unidentified developer. Double-click the image, drag `Shift.app` to /Applications, then allow the first launch once (right-click → Open, or 允许 in System Settings → Privacy & Security). In-app updates download the same image without a browser, so they never prompt. 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. diff --git a/README.zh-CN.md b/README.zh-CN.md index 78c252b..67bb1a5 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -294,7 +294,7 @@ Shift 会持续维护局域网内其他 Shift 实例的列表,并据此提供 ## 软件更新 -新的 macOS 机器请安装 **`Shift-macOS-universal.pkg`**:本项目的构建采用 ad-hoc 签名且未做公证,Gatekeeper 会把 Shift 判为身份不明的开发者,而通过安装包安装不会把隔离属性带给应用,装好后打开不会再有提示。若改用磁盘镜像安装,首次打开需要允许一次(右键 → 打开,或在「系统设置 → 隐私与安全性」中点「允许」)。详见 `docs/RELEASE.md`。 +新的 macOS 机器请安装 **`Shift-macOS-universal.dmg`**:本项目的构建采用 ad-hoc 签名且未做公证,Gatekeeper 会把 Shift 判为身份不明的开发者。双击挂载镜像,把 `Shift.app` 拖进「应用程序」,然后允许首次启动一次(右键 → 打开,或在「系统设置 → 隐私与安全性」中点「允许」)。软件内升级自己下载的是同一个镜像、不经浏览器,因此不会弹窗。详见 `docs/RELEASE.md`。 更新通道就是这个仓库:一条 `releases` 分支保存安装包以及 `shift-update.json` 清单,清单写明每个安装包的名称、体积与 SHA256。更新源地址在构建时由 git 远端推导——已适配 Gitea、GitHub、GitLab 三种形式,也可用 `SHIFT_UPDATE_URL` 覆盖——因此无需额外部署任何更新服务。 diff --git a/artifacts/README-macOS-universal.txt b/artifacts/README-macOS-universal.txt index 67203e2..c0ef6fe 100644 --- a/artifacts/README-macOS-universal.txt +++ b/artifacts/README-macOS-universal.txt @@ -1,47 +1,32 @@ Shift 0.1.3 - macOS 通用(universal) -本文件说明 macOS 安装包是怎么打出来的、两个安装包各自负责什么、在其它机器上 -会遇到什么,以及如何自己校验。完整细节见仓库 docs/RELEASE.md 的「macOS packaging」。 +本文件说明 macOS 安装包是怎么打出来的、在其它机器上会遇到什么,以及如何自己校验。 +完整细节见仓库 docs/RELEASE.md 的「macOS packaging」。 -为什么有两个安装包 ------------------- +关于这个安装包 +-------------- + +Shift 的 macOS 产物只有一个:Shift-macOS-universal.dmg,通用二进制,Apple silicon 与 +Intel 都能用。它既是新机器的首次安装方式,也是软件内升级的载体(更新清单里的 macos +键指向它)。清单的键必须是 .dmg,因为软件内升级的交接脚本要用 hdiutil 挂载镜像再 +取出应用包;早期曾随包发布的 .pkg 在验证过 DMG 可用后就撤掉了,不为它多维护一份 +产物。 本项目的构建是 ad-hoc 签名(src-tauri/tauri.conf.json 里 signingIdentity 固定为 "-"),且没有 Apple Developer ID 可做公证。Gatekeeper 因此无法为任何 Shift 构建背书, -一台新机器上的表现取决于安装包的形式: - -| 安装包 | 用途 | 新机器上的表现 | -| --- | --- | --- | -| Shift-macOS-universal.pkg | 首次安装,交给任何新机器 | installer 不会把隔离属性带给装好的应用,装好后打开**完全没有提示**。已实测:装好的副本只带 com.apple.provenance,没有 com.apple.quarantine。 | -| Shift-macOS-universal.dmg | 软件内升级通道(清单里的 macos 键) | 应用自己下载的副本不带隔离属性,所以软件内升级也不弹窗。若是从浏览器下载再拖进 /Applications,首次打开需要允许一次。 | - -所以:新机器装 .pkg,已在用的 Shift 走软件内升级(下载的是 .dmg)。清单的 macos -键必须是 .dmg —— 软件内升级的交接脚本用 hdiutil 挂载镜像再取出应用包,指向 .pkg -会让每次升级都挂载失败。 - -pkg 里的应用与被拖出来的应用是同一份签名:pkgbuild 既不重新签名也不剥离签名, -内置应用、DMG 内副本、pkg 内副本的 CDHash 完全一致(已核对)。 +一台新机器上会看到「身份不明的开发者」提示——这是可以放行的,见下节。 在其它机器上安装 ---------------- -安装包 .pkg(推荐,新机器) - 1. 下载 Shift-macOS-universal.pkg。pkg 本身没有签名(productsign 需要一枚带 - Installer Signing 用途的证书,本项目只有代码签名身份),因此浏览器下载后 - 双击可能被拦:右键 → 打开,或在「系统设置 → 隐私与安全性」中点「仍要打开」, - 只需一次,发生在安装之前。 - 2. 之后按提示安装,载荷会落到 /Applications。 - 3. 启动 Shift,不会再有任何 Gatekeeper 提示。 - 终端安装连这一次都不需要: - sudo installer -pkg Shift-macOS-universal.pkg -target / - -磁盘镜像 .dmg(新机器,或想手动装) - 1. 双击挂载,把 Shift.app 拖进 /Applications。 - 2. 首次启动被拦:「无法打开,因为来自身份不明的开发者」。点取消后,右键 - Shift.app → 打开,或在「系统设置 → 隐私与安全性」中点「仍要打开」。 - 3. 只需允许一次,之后再打开正常。 +新机器首次安装 + 1. 下载并双击 Shift-macOS-universal.dmg 挂载镜像。 + 2. 把 Shift.app 拖进「应用程序」(或任何你有权限的位置)。 + 3. 首次启动会被拦:「无法打开,因为来自身份不明的开发者」。点取消,然后 + 右键 Shift.app → 打开,或在「系统设置 → 隐私与安全性」中点「仍要打开」。 + 4. 只需允许一次,之后再打开正常。 macOS 权限 截图与录屏需要「屏幕录制」,输出目录需要「文件与文件夹」,带声音录屏需要 @@ -68,16 +53,12 @@ macOS 权限 pnpm install pnpm mac:drag-bridge -生成通用应用与 DMG,再把应用包包成 .pkg: +生成通用应用与 DMG: 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 -scripts/macos-pkg.sh 把应用包暂存到一个 /Applications 根目录下,再用 pkgbuild 打包; -install-location 指向 /Applications,所以这台机器上的每个用户都会装到那里。它用 -ditto 而不是 cp,以保留资源分支、符号链接与代码签名。 +产物在 src-tauri/target/universal-apple-darwin/release/bundle/macos/ 下:Shift.app +与 Shift-macOS-universal.dmg。发布流程(清单、签名、推送)见仓库 docs/RELEASE.md。 若希望更新通道能校验来源,构建时把 ed25519 公钥编进去(发布流程见仓库 docs/RELEASE.md 的「Signing the channel」): @@ -100,14 +81,9 @@ docs/RELEASE.md 的「Signing the channel」): # Signature=adhoc # Identifier=app.nex.shift -安装包本体(pkg 未签名是已知状态,真正的签名在里面的应用上): - - pkgutil --check-signature Shift-macOS-universal.pkg # Status: no signature - pkgutil --payload-files Shift-macOS-universal.pkg # ./Shift.app/... - 镜像完整性: hdiutil verify Shift-macOS-universal.dmg -校验后仍打不开的话,请确认不是在压缩包预览窗口里运行的,并优先使用 .pkg;若坚持用 -.dmg,按上面的「在其它机器上安装」处理首次允许。 +校验后仍打不开的话,请确认不是在压缩包预览窗口里运行的,并按上面的「新机器首次安装」 +处理首次允许:右键 → 打开,或在「系统设置 → 隐私与安全性」中点「仍要打开」。 diff --git a/docs/RELEASE.md b/docs/RELEASE.md index f133785..b63f350 100644 --- a/docs/RELEASE.md +++ b/docs/RELEASE.md @@ -39,8 +39,7 @@ not a code limit, and it decides what the channel may contain: | Key | Shipped | Notes | | --- | --- | --- | -| `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" | +| `macos` | yes | One universal bundle, Apple silicon and Intel, shipped as a DMG. Verified on a fresh machine by dragging it to /Applications — 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 | @@ -99,32 +98,32 @@ project wants, and no release is worse off for losing a certificate no other Mac Reusing that identity again would mean installing it **and trusting it** on every machine, which is not something to ask of a user. -So: ad-hoc, and the two containers each cover one job. +So: ad-hoc, and one container. The channel ships **`Shift-macOS-universal.dmg`** and nothing +else on macOS — the earlier `.pkg` companion was dropped after the DMG was verified to work +on a fresh machine, and one file per platform is less to keep straight. -| Container | First launch on a fresh machine | +| Situation | What happens | | --- | --- | -| `.pkg`, via Installer.app or `installer` | `installer` does not propagate quarantine onto what it installs, so the app opens with **no prompt at all**. Verified: an installed copy carries `com.apple.provenance` and no `com.apple.quarantine`. The package itself is unsigned (`productsign` needs an *Installer Signing* certificate; a code-signing identity is rejected), so a browser-downloaded package may need right-click → 打开 once, before anything installs. `installer -pkg … -target /` needs nothing. | -| `.dmg`, app dragged to /Applications | The app keeps the browser's quarantine flag, so the first launch needs the one approval above. Shift's own downloader sets no quarantine flag, which is why **in-app updates never prompt** — only a browser download on a new machine does. | +| A machine installing Shift for the first time | Double-click the DMG, drag `Shift.app` to /Applications. The app keeps the browser's quarantine flag, so the **first launch** needs the one approval above: right-click → 打开, or 允许 in 系统设置 → 隐私与安全性. Every launch after that is normal. | +| An installed Shift updating itself | `update_install`'s handoff downloads the DMG, mounts it with `hdiutil`, copies the bundle out and drops the quarantine flag. Shift's own downloader sets no quarantine flag (`curl` sets none, and the handoff strips it anyway), so **in-app updates never prompt**. | -`scripts/macos-pkg.sh ` builds the package: it stages the bundle under -an `/Applications` root and runs `pkgbuild`, which neither re-signs nor strips the payload — -the CDHash is identical in the built bundle, the DMG copy and the pkg copy. +The `macos` manifest key is a DMG for the same reason: the in-app handoff mounts the image, +so pointing the key at a package would break every in-app update. That was the one real +constraint the container had to satisfy, and a DMG satisfies it. -The `macos` manifest key stays a DMG on purpose: `update_install`'s handoff mounts the image -with `hdiutil` and copies the bundle out of it, so pointing the key at a `.pkg` would make -every in-app update fail to mount. +`scripts/macos-pkg.sh` — which staged the bundle under an `/Applications` root and ran +`pkgbuild` — is kept in the tree but is no longer part of a release: it built a container +with no manifest key, and the DMG covers the first install anyway. Closing this for good means an Apple Developer ID: `Developer ID Application` + -`notarytool` + `stapler staple`. 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. +`notarytool` + `stapler staple`. Then the DMG opens 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 --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 ``` @@ -145,19 +144,17 @@ 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 macOS `.pkg`, the portable -ZIPs, `SHA256SUMS.txt`, the `README-Windows-.txt` notes and -`README-macOS-universal.txt` — the packaging note that explains the ad-hoc signature, what a -fresh machine does with each container, and how to verify a download — 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. +`*.AppImage` / `*.deb` (Linux). Other files in `artifacts/` — the portable ZIPs, +`SHA256SUMS.txt`, the `README-Windows-.txt` notes and `README-macOS-universal.txt`, +the packaging note explaining the ad-hoc signature and how to verify a download — travel +with the branch and are downloadable from it, but are not offered as installers by the +manifest. Dotfiles and an old manifest are skipped. `README-macOS-universal.txt` is tracked in the repository as well as pushed to the channel, so the scheme is documented where a contributor reads it and not only next to a build -product. Every claim in it was checked against the shipped artifacts: the installed -`.pkg`'s payload is `Signature=adhoc`, `pkgutil --check-signature` reports `no signature` -for the package itself, and `shasum -a 256 -c SHA256SUMS.txt` passes on the published set. +product. Every claim in it was checked against the shipped artifacts: the bundle inside the +published DMG is `Signature=adhoc`, and `shasum -a 256 -c SHA256SUMS.txt` passes on the +published set. 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 @@ -340,8 +337,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. +The 0.1.3 tree still carries the retired `Shift-macOS-universal.pkg`, because removing it +means re-publishing; it has no manifest key, so no client can be served it, and it is simply +not built any more ("macOS packaging"). macOS ships one artifact from the next publish on. `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 diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 6a24750..ea73a17 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -108,12 +108,13 @@ names what is still missing. signing with a locally created certificate made every other machine refuse the app as *damaged / malware* with no override, because that certificate cannot chain to a trusted root anywhere else, while an ad-hoc binary gets the softer "unidentified developer" box - the user can approve. The channel also publishes `Shift-macOS-universal.pkg`, since - `installer` does not leave the installed copy quarantined and the app then opens with no - prompt at all. The `macos` manifest key stays a DMG so the in-app handoff can keep - mounting it; see "macOS packaging" in `docs/RELEASE.md`. A Developer ID plus notarization - removes the prompt entirely and would also stop Screen Recording approval from resetting - between builds. + the user can approve. The channel ships one macOS container, the DMG: it was verified on a + fresh machine (drag to /Applications, one approval on first launch), so the `.pkg` that + once accompanied it was dropped rather than kept as a second thing to maintain. The `macos` + manifest key has to stay a DMG anyway, because the in-app handoff mounts it with `hdiutil`; + see "macOS packaging" in `docs/RELEASE.md`. A Developer ID plus notarization removes the + prompt entirely and 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