Merge pull request #76 from TrentBrown/tb-portreeve-apple-trust-03-verification-sealed-distribution

feat(release): verify and seal Apple trust distribution

Author: TrentBrown

.agents/skills/release-portreeve/SKILL.md

@@ -29,7 +29,8 @@ gate.
 - For a local engine check, run `release:prepare`. Explain that one host stops before
   the complete native matrix.
 - For a complete candidate or rehearsal, use the manual GitHub workflow with
-  `publish=false`. Download `distribution-<version>` after it succeeds and run
+  `trust=true` and `publish=false`. Approval of `release-trust` authorizes only the
+  nonpublic Apple producer. Download `distribution-<version>` after it succeeds and run
   `release:inspect` against its `release-record.json`, followed by the disposable
   `release:homebrew-smoke` formula/cask installation check on macOS.
 - For an interrupted candidate, resume only through the exact recovery path documented
@@ -67,6 +68,7 @@ For the complete hosted rehearsal:
 gh workflow run release.yml \
   -f channel=preview \
   -f version=0.1.0-preview.1 \
+  -f trust=true \
   -f publish=false
 ```
 
@@ -85,6 +87,11 @@ temporary tap, and must clean up without changing supervision or PortReeve data.
 Do not invent signing evidence for stable. Missing Developer ID, notarization, stapling,
 Gatekeeper, or native evidence must remain a failure.
 
+Require the protected producer plus one current native ARM64 and one current native
+Intel Apple trust document for every new public preview as well as stable. A personal
+manual-install check on another architecture is optional; hosted native evidence is not.
+Historical previews through `0.1.0-preview.4` remain immutable unsigned history.
+
 ## Preserve the publication boundary
 
 Do not set `publish=true`, call `release:publish`, create or move a tag, create a GitHub
@@ -94,7 +101,8 @@ explicitly requests those public mutations after the exact plan is available.
 When publication is explicitly requested:
 
 1. Revalidate the completed record and every artifact digest.
-2. Present the plan path and SHA-256 plus GitHub, tap, and update-metadata targets.
+2. Require `publication-plan.sha256` to match the exact plan, then present the plan path
+   and SHA-256 plus GitHub, tap, and update-metadata targets.
 3. Obtain the user's explicit approval for that exact candidate if it has not already
    been given.
 4. Use the normal `release-publication` environment or the documented direct command.
@@ -118,6 +126,7 @@ Separate:
 - generated artifact names and digests;
 - preview/stable, maturity, and Desktop trust;
 - public mutations performed, or an explicit statement that none occurred;
+- protected trust approval and publication approval as separate facts;
 - generated Homebrew and Desktop PR URLs plus verified merge commits when published;
 - exact recovery or next command.
 

.github/workflows/release.yml

@@ -36,6 +36,7 @@ env:
   BUN_VERSION: 1.3.14
   NODE_VERSION: 22
   RELEASE_ROOT: dist/releases/${{ inputs.version }}
+  TRUSTED_ROOT: dist/trusted/${{ inputs.version }}
   PORTREEVE_HOMEPAGE_URL: ${{ github.server_url }}/${{ github.repository }}
   PORTREEVE_RELEASE_BASE_URL:
     ${{ github.server_url }}/${{ github.repository }}/releases/download
@@ -186,7 +187,6 @@ jobs:
     permissions:
       contents: read
     env:
-      TRUSTED_OUTPUT_ROOT: dist/trusted/${{ inputs.version }}
       PORTREEVE_APPLE_SIGNING_IDENTITY: ${{ vars.PORTREEVE_APPLE_SIGNING_IDENTITY }}
       PORTREEVE_APPLE_TEAM_ID: ${{ vars.PORTREEVE_APPLE_TEAM_ID }}
       PORTREEVE_APPLE_NOTARY_KEY_ID: ${{ vars.PORTREEVE_APPLE_NOTARY_KEY_ID }}
@@ -215,15 +215,94 @@ jobs:
         run: >-
           bun run release:produce-apple-trust -- --record
           "$RELEASE_ROOT/release-record.json" --qualification
-          "$RELEASE_ROOT/evidence/trust-qualification.json" --output
-          "$TRUSTED_OUTPUT_ROOT"
+          "$RELEASE_ROOT/evidence/trust-qualification.json" --output "$TRUSTED_ROOT"
       - uses: actions/upload-artifact@v7
         with:
           name: trusted-${{ inputs.version }}
-          path: ${{ env.TRUSTED_OUTPUT_ROOT }}
+          path: ${{ env.TRUSTED_ROOT }}
           if-no-files-found: error
           retention-days: 7
 
+  trusted-native-evidence:
+    needs: release-trust
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - runner: macos-15
+            architecture: arm64
+          - runner: macos-15-intel
+            architecture: x64
+    runs-on: ${{ matrix.runner }}
+    name: Apple trust evidence (macos-${{ matrix.architecture }})
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: ${{ env.BUN_VERSION }}
+      - run: bun ci
+      - uses: actions/download-artifact@v8
+        with:
+          name: trusted-${{ inputs.version }}
+          path: ${{ env.TRUSTED_ROOT }}
+      - name: Restore authoritative executable modes
+        run: chmod 755 "$TRUSTED_ROOT"/artifacts/portreeve-v*
+      - name: Verify exact Apple artifacts on their native architecture
+        run: >-
+          bun run release:apple-native-evidence -- --record
+          "$TRUSTED_ROOT/release-record.json" --producer-evidence
+          "$TRUSTED_ROOT/evidence/apple-trust-producer.json"
+      - uses: actions/upload-artifact@v7
+        with:
+          name: apple-native-${{ matrix.architecture }}
+          path:
+            ${{ env.TRUSTED_ROOT }}/evidence/apple-native-${{ matrix.architecture
+            }}.json
+          if-no-files-found: error
+          retention-days: 7
+
+  finalize-trusted-distribution:
+    needs: trusted-native-evidence
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: ${{ env.BUN_VERSION }}
+      - run: bun ci
+      - uses: actions/download-artifact@v8
+        with:
+          name: trusted-${{ inputs.version }}
+          path: ${{ env.TRUSTED_ROOT }}
+      - uses: actions/download-artifact@v8
+        with:
+          pattern: apple-native-*
+          path: ${{ env.TRUSTED_ROOT }}/evidence
+          merge-multiple: true
+      - name: Seal exact distribution metadata and publication plan
+        run: >-
+          bun run release:finalize-desktop -- --record
+          "$TRUSTED_ROOT/release-record.json" --producer-evidence
+          "$TRUSTED_ROOT/evidence/apple-trust-producer.json" --apple-evidence
+          "$TRUSTED_ROOT"/evidence/apple-native-*.json --current-update-manifest
+          distribution/desktop-update.json
+      - uses: actions/upload-artifact@v7
+        with:
+          name: distribution-${{ inputs.version }}
+          path: ${{ env.TRUSTED_ROOT }}
+          if-no-files-found: error
+          retention-days: 14
+
   desktop-evidence:
     needs: aggregate-native-evidence
     strategy:
@@ -265,6 +344,7 @@ jobs:
           retention-days: 7
 
   finalize-distribution:
+    if: ${{ !inputs.trust }}
     needs: desktop-evidence
     runs-on: ubuntu-24.04
     steps:
@@ -299,8 +379,8 @@ jobs:
           retention-days: 14
 
   publish:
-    if: inputs.publish
-    needs: finalize-distribution
+    if: ${{ always() && inputs.publish && !failure() && !cancelled() }}
+    needs: [finalize-distribution, finalize-trusted-distribution]
     runs-on: ubuntu-24.04
     environment: release-publication
     permissions:

README.md

@@ -3,10 +3,10 @@
 > [!WARNING]
 >
 > **Alpha Preview** — PortReeve is evolving quickly. Breaking changes remain possible,
-> and the current macOS preview is unsigned until Apple Developer ID signing and
-> notarization are configured. Review the
-> [installation and removal guide](docs/installation.md), including the scoped macOS
-> **Open Anyway** procedure, before installing it.
+> and the currently published macOS previews through `0.1.0-preview.4` are immutable
+> unsigned history. New public previews require Apple Developer ID signing and
+> notarization. Review the [installation and removal guide](docs/installation.md),
+> including the narrowly scoped historical-preview guidance, before installing.
 
 <p align="center">
   <img src="apps/desktop/assets/branding/portreeve-lockup.svg" width="570" alt="PortReeve, Local Port Authority">
@@ -32,8 +32,8 @@ brew install trentbrown/portreeve/portreeve
 ```
 
 Homebrew does not silently install or start the supervised service. Direct macOS DMGs,
-Linux executables, checksum verification, unsigned-app guidance, and removal procedures
-are covered in the [installation guide](docs/installation.md).
+Linux executables, checksum verification, historical unsigned-preview guidance, and
+removal procedures are covered in the [installation guide](docs/installation.md).
 
 <!-- product-overview:identity-problem -->
 

docs/desktop.md

@@ -7,8 +7,9 @@ bundles a verified CLI artifact and can install that artifact into the one manag
 per-user location used by native supervision.
 
 Desktop is currently alpha software. Its persistent header notice reports product
-maturity independently of update channel and macOS trust; a preview download may be
-unsigned without making every future preview unsigned.
+maturity independently of update channel and macOS trust. Historical previews through
+`0.1.0-preview.4` remain unsigned, while every new public preview requires Developer ID
+signing and notarization.
 
 ## Overview and lifecycle
 

docs/installation.md

@@ -2,17 +2,18 @@
 
 > **Alpha Preview**
 >
-> PortReeve is evolving quickly and may make breaking changes. The current public alpha
-> preview is available on
-> [GitHub Releases](https://github.com/TrentBrown/portreeve/releases), and its macOS
-> application is unsigned until Apple Developer ID signing and notarization are
-> configured. Product maturity (`alpha`), release channel (`preview`), and macOS trust
-> (`unsigned`) are separate facts.
-
-The preview is ad-hoc signed so macOS can verify that the assembled application bundle
-and its nested executables have not changed. An ad-hoc signature carries no verified
-developer identity and is not notarization, so Gatekeeper may still require the scoped
-**Open Anyway** procedure below.
+> PortReeve is evolving quickly and may make breaking changes. Public alpha previews are
+> available on [GitHub Releases](https://github.com/TrentBrown/portreeve/releases).
+> Published previews through `0.1.0-preview.4` are immutable unsigned history; every new
+> public preview requires Apple Developer ID signing and notarization. Product maturity
+> (`alpha`), release channel (`preview`), and macOS trust are separate facts.
+
+Historical previews through `0.1.0-preview.4` are ad-hoc signed so macOS can verify that
+the assembled application bundle and its nested executables have not changed. An ad-hoc
+signature carries no verified developer identity and is not notarization, so Gatekeeper
+may still require the scoped **Open Anyway** procedure below. Newer public previews fail
+closed unless they are Developer ID-signed, notarized, stapled, accepted by Gatekeeper,
+and independently verified on native Apple Silicon and Intel runners.
 
 Use [GitHub Releases](https://github.com/TrentBrown/portreeve/releases) to identify the
 newest preview and verify its assets. The commands below install the currently published
@@ -79,9 +80,10 @@ shasum -a 256 PortReeve-VERSION-macos-ARCH.dmg
 Compare the complete output with the corresponding line in the downloaded checksum
 file. Do not continue when the values differ.
 
-## Opening an unsigned preview safely
+## Opening a historical unsigned preview safely
 
-Try to open PortReeve normally first. An unsigned preview may be blocked because Apple
+This exception applies only to immutable previews through `0.1.0-preview.4`. Try to open
+PortReeve normally first. A historical unsigned preview may be blocked because Apple
 cannot verify a Developer ID signature or notarization ticket. Only continue when the
 DMG came from the PortReeve GitHub Release and its SHA-256 matches the release checksum.
 

docs/issues/tb-portreeve-apple-trust/decisions.md

@@ -42,3 +42,20 @@ PortReeve accepts only its exact Developer ID identity, Team ID, and product-spe
 - Allow unbounded polling - rejected because failure must terminate predictably.
 
 **Promoted:** 2026-08-28. PR: https://github.com/TrentBrown/portreeve/pull/74.
+
+---
+
+## Transform signed CLI metadata as one authority set
+
+**Confidence:** HIGH
+
+**Blast Radius:** Protected producer output, release record, manifest, Homebrew formula, checksums, native verification, and finalization
+
+When the protected producer transforms either macOS CLI, it must rewrite the corresponding manifest entries, Homebrew checksums, SHA256SUMS document, and release-record metadata identities before the output is verified or uploaded. Native Apple jobs and finalization consume only this synchronized protected tree; they do not tolerate metadata that still names the unsigned predecessor.
+
+**Triggered by:** Developer ID signing changes the macOS CLI bytes after preliminary qualification
+
+**Alternatives considered:**
+Defer metadata repair until finalization - rejected because native verification must consume a self-consistent protected output. Keep separate unsigned and signed manifests - rejected because multiple authorities would make downstream selection ambiguous. Rebuild metadata independently in each native job - rejected because read-only verifiers must not mutate the producer output.
+
+**Promoted:** 2026-08-29. PR: https://github.com/TrentBrown/portreeve/pull/76.