Phase 6: unsigned distribution — ad-hoc codesign + release runbook + install page#28
Merged
Conversation
- client/pkg-build/build.sh: codesign -s - --force the staged bb-vpn, sing-box, xray binaries and BBVPN.app; verify --strict before pkgbuild. Strips xattrs AFTER signing (signature lives in LC_CODE_SIGNATURE / Contents/_CodeSignature, not xattrs). - docs/release.md: operator runbook covering build, ad-hoc signing semantics, hosting via long-random nginx path, per-user install-page generation via envsubst, token rotation procedure (9-step table with time estimates), upgrade flow + verification steps on a clean Mac. - client/pkg-build/install-page-template.html: user-facing install page template with PKG_URL/PKG_NAME/ENROLL_URI/USER_NAME envsubst slots. Self-contained CSS, dark-mode aware, robots noindex/nofollow.
Owner
Author
|
@copilot please re-review — fixes pushed since the last review |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR implements “Phase 6” of the macOS .pkg distribution plan by adding ad-hoc codesigning of staged payload binaries, plus operator/user documentation for building, hosting, and installing the package via a per-user install page.
Changes:
- Add ad-hoc codesigning + verification for staged payload (bb-vpn, sing-box, xray, BBVPN.app) prior to
pkgbuild. - Add an operator release runbook describing build/host/distribute flow (including install-page generation and token rotation guidance).
- Add a user-facing install page template and cross-link the runbook from repo docs (README/AGENTS).
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
| README.md | Adds a .pkg distribution (Phase 4–6) section and links to the operator runbook. |
| docs/release.md | New operator runbook for building, ad-hoc signing, hosting, install-page generation, upgrade flow, and token rotation. |
| client/pkg-build/install-page-template.html | New per-user install page template with envsubst placeholders and Gatekeeper guidance. |
| client/pkg-build/build.sh | Adds ad-hoc codesign + verification step for staged payload prior to packaging. |
| AGENTS.md | Updates .pkg installer section and links to the Phase 6 runbook/template. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- install-page Stop/start: use absolute bb-vpn path (sudo strips PATH so ~/.local/bin/bb-vpn shortcut isn't on the search path; same fix already applied to the enroll Terminal fallback). - docs/release.md + AGENTS.md: clarify that --deep only applies to BBVPN.app; standalone bb-vpn/sing-box/xray Mach-Os are signed without --deep (matches what build.sh actually does). Dismissed (not in Phase 6 must-fix scope): HTML-escape of envsubst placeholders (operator-controlled inputs, single-user threat model); token-gen tr -d shortening (pre-existing pattern from control-plane-bootstrap.md, mirrored in release.md for consistency).
Owner
Author
|
@copilot please re-review — fixes pushed since the last review |
Contributor
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Phase 6 of
docs/plans/20260517-pkg-and-pull-control-plane.md— operator-facing distribution flow for the .pkg.client/pkg-build/build.sh— ad-hoc codesign (codesign -s - --force) ofbb-vpn,sing-box,xray, andBBVPN.appin the staging tree beforepkgbuild. Verifies withcodesign --verify --strict(per binary) and--verify --deep --strict(on the .app). Signing happens beforexattr -crsince the signature lives inLC_CODE_SIGNATURE/Contents/_CodeSignature/, not as an xattr.docs/release.md— operator runbook covering: prerequisites,make build-pkg, what ad-hoc signing buys (and doesn't buy — Gatekeeper still treats the .pkg as "unidentified developer"), hosting via long-random nginx path (/d/<32-hex>/), per-user install-page generation via envsubst, 9-step token rotation procedure with time estimates, upgrade flow that matchespostinstall.shactual behavior (immediatebb-vpn startfor enrolled users), and verification on a fresh Mac.client/pkg-build/install-page-template.html— user-facing install page template withPKG_URL/PKG_NAME/ENROLL_URI/USER_NAMEenvsubst placeholders. Self-contained CSS, dark-mode aware,robots: noindex, nofollow. Text-only Gatekeeper instructions (no screenshots — intentional per zero-license constraints).README.md+AGENTS.md— added.pkg distribution (Phase 4–6)section + link todocs/release.mdso future operators/agents land on the runbook.The .pkg itself stays unsigned (no Developer ID Installer cert;
productbuild --signwith an arbitrary identity would be worse than unsigned).Pre-PR review
.btn.secondaryCSS,sudoon system-domain bootout examples, etc.). Iter 2 critical re-check, smells, codex, and phase 4 safety net all clean.Test plan
make build-pkgsucceeds end-to-end with the new codesign stepcodesign -dvvon staged binaries:Signature=adhoccodesign --verify --deep --stricton BBVPN.app: passes silentlyenvsubst < install-page-template.htmlrenders cleanly (placeholders filled, no unfilled${...}sequences)