From 84dfe6fab212efd9542e558794d3126c2292fe2d Mon Sep 17 00:00:00 2001 From: Gibran Iqbal Date: Tue, 28 Apr 2026 16:40:44 -0500 Subject: [PATCH] Add canonical GUI install guidance for unsigned releases The public release repository remains the sterile metadata-only distribution surface. This adds the canonical Finder/Installer.app install guide for unsigned macOS Apple Silicon packages and links it from README and policy without adding any GitHub Release asset. Constraint: Public repo history must contain release metadata and documentation only, never ICUP source code, binaries, signing material, or private provenance. Constraint: Unsigned native-host users need a non-terminal install path that can rely on macOS Gatekeeper exception prompts. Rejected: Attach a standalone install guide asset | expands the release asset set and duplicates tracked documentation. Confidence: high Scope-risk: narrow Directive: Keep release assets limited to the documented four-file set unless ICUP validators and policy are updated together. Tested: python3 scripts/validate_public_release_repo_tree.py --repo-dir /Users/jbz/src/redactpiitools-release. Not-tested: Live GitHub release publication from this commit. --- README.md | 6 ++++ docs/unsigned-native-host-install.md | 54 ++++++++++++++++++++++++++++ metadata/release-content-policy.md | 2 ++ 3 files changed, 62 insertions(+) create mode 100644 docs/unsigned-native-host-install.md diff --git a/README.md b/README.md index f1f3c12..02ee3cf 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,12 @@ Each public release may attach only: The internal native-host handoff tarball is intentionally not a public release asset. +## macOS Early Access Install + +Unsigned macOS Apple Silicon native-host releases use Finder and Installer.app. If macOS blocks the package, follow the Privacy & Security exception flow in the canonical guide: + +- [Unsigned Native Host Install Guide](docs/unsigned-native-host-install.md) + ## Repository Policy Tracked files in this repository are limited to public metadata and policy files. Do not commit product source code, build outputs, packaged binaries, signing materials, private provenance, workspace dumps, or source-bearing archives. diff --git a/docs/unsigned-native-host-install.md b/docs/unsigned-native-host-install.md new file mode 100644 index 0000000..f96bfd3 --- /dev/null +++ b/docs/unsigned-native-host-install.md @@ -0,0 +1,54 @@ +# Unsigned Native Host Install Guide + +This guide is for Early Access macOS Apple Silicon releases that attach a file named like: + +`PrivacyGuard-native-host-X.Y.Z-macos-arm64-unsigned.pkg` + +The package contains an ad-hoc signed native-host binary and is not Apple notarized. macOS may block it until you approve an exception in Privacy & Security. Use the notarized package instead whenever the release provides one without `-unsigned` in the filename. + +## Install Without Command Line + +1. Open the RedactPIITool public release page: + +2. In the release Assets section, download `PrivacyGuard-native-host-X.Y.Z-macos-arm64-unsigned.pkg`. +3. Double-click the downloaded `.pkg` file in Finder. +4. If Installer.app opens, follow the prompts and enter your macOS administrator password if asked. +5. If macOS blocks the package: + - Close the warning. + - Open System Settings. + - Go to Privacy & Security. + - Click Open Anyway for the PrivacyGuard package. + - Confirm Open when macOS asks. + - Follow the Installer.app prompts. +6. Restart Chrome after the installer completes. + +## Install The Chrome Extension + +Install the Chrome extension from the Chrome Web Store: + + + +## Verify The Install + +After installing both components: + +1. Open Chrome. +2. Open the PrivacyGuard extension options. +3. Confirm the native host status shows connected. + +The installer places the native host under `/Library/Application Support/PrivacyGuard/native-host-swift/` and registers the Chrome native messaging manifest at `/Library/Google/Chrome/NativeMessagingHosts/com.privacyguard.pii.json`. + +## Release Files + +Public Early Access releases attach only these release assets: + +- `PrivacyGuard-vX.Y.Z.zip` +- `PrivacyGuard-native-host-X.Y.Z-macos-arm64-unsigned.pkg` +- `bundle-manifest.json` +- `SHA256SUMS.txt` + +The public release does not attach ICUP source archives, native-host handoff tarballs, build workspaces, signing material, or private provenance. + +## Trust Notice + +This Early Access path exists for releases made before Apple Developer ID signing and notarization are available. Apple-notarized packages provide a smoother default macOS install experience and additional Apple verification. The unsigned package requires you to decide whether to approve the exception for this release. diff --git a/metadata/release-content-policy.md b/metadata/release-content-policy.md index 311c25c..4a05de9 100644 --- a/metadata/release-content-policy.md +++ b/metadata/release-content-policy.md @@ -13,6 +13,8 @@ Allowed tracked content: - `docs/**` public release-consumer documentation - `metadata/**` public release policy and metadata +For unsigned macOS Apple Silicon Early Access releases, `docs/unsigned-native-host-install.md` is the canonical public install document. It is tracked documentation, not a GitHub Release asset. + Disallowed tracked content: - ICUP source code or copied build scripts