fix: seal preview desktop bundles

Author: TrentBrown

docs/installation.md

@@ -9,6 +9,11 @@
 > 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.
+
 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
 Homebrew, DMG, and direct-download artifacts.
@@ -174,7 +179,7 @@ appropriate.
 
 ## Build from source
 
-Before the first public preview, macOS users can build the current source with the
+Contributors and users testing unreleased changes can build the current source with the
 pinned Bun 1.3.14 toolchain:
 
 ```sh

docs/releasing.md

@@ -44,6 +44,10 @@ real Developer ID signing, hardened runtime, secure timestamps, notarization, st
 Gatekeeper acceptance, and native ARM64/x64 evidence. The current workflow deliberately
 has no way to substitute synthetic evidence for those requirements.
 
+Preview Desktop bundles are ad-hoc signed and structurally verified before packaging.
+That integrity seal has no developer identity and confers no Gatekeeper trust; the
+release record therefore continues to describe preview Desktop trust as `unsigned`.
+
 ## Prerequisites
 
 All release work requires a clean checkout of the source commit to be released and the

scripts/desktop-package-lib.js

@@ -148,6 +148,7 @@ export function assertPackagedDesktopContents(options) {
  * @param {{applicationPath: string, controllerVersion: string, architecture: 'arm64'|'x64'}} options
  */
 export async function verifyPackagedDesktop(options) {
+  await verifyPackagedDesktopSignature(options.applicationPath);
   const resourcesRoot = resolve(options.applicationPath, 'Contents', 'Resources');
   const executableFormat = await inspectExecutable(
     resolve(options.applicationPath, 'Contents', 'MacOS', 'PortReeve'),
@@ -206,6 +207,31 @@ export async function verifyPackagedDesktop(options) {
   return artifact;
 }
 
+/**
+ * Reject a bundle whose nested code or sealed resources do not match its signature.
+ * An ad-hoc preview passes this structural check but remains untrusted by Gatekeeper.
+ *
+ * @param {string} applicationPath
+ * @param {(executable: string, arguments_: string[]) => Promise<{stdout: string, stderr: string, exitCode: number}>} [run]
+ */
+export async function verifyPackagedDesktopSignature(
+  applicationPath,
+  run = runCommand,
+) {
+  const result = await run('codesign', [
+    '--verify',
+    '--deep',
+    '--strict',
+    '--verbose=4',
+    applicationPath,
+  ]);
+  if (result.exitCode !== 0) {
+    throw new Error(
+      `Packaged Desktop bundle signature is invalid: ${result.stderr.trim() || result.stdout.trim()}`,
+    );
+  }
+}
+
 /**
  * Launch the assembled application through its real Electron executable. The
  * smoke branch is read-only and receives isolated lifecycle and Desktop paths.
@@ -316,3 +342,27 @@ function runBounded(executable, environment, timeoutMilliseconds) {
     });
   });
 }
+
+/** @param {string} executable @param {string[]} arguments_ @returns {Promise<{stdout: string, stderr: string, exitCode: number}>} */
+function runCommand(executable, arguments_) {
+  return new Promise((resolvePromise, reject) => {
+    const child = spawn(executable, arguments_, {
+      shell: false,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => {
+      stdout = (stdout + chunk).slice(0, OUTPUT_LIMIT);
+    });
+    child.stderr.on('data', (chunk) => {
+      stderr = (stderr + chunk).slice(0, OUTPUT_LIMIT);
+    });
+    child.once('error', reject);
+    child.once('close', (exitCode) => {
+      resolvePromise({ stdout, stderr, exitCode: exitCode ?? 70 });
+    });
+  });
+}

scripts/package-desktop.js

@@ -33,6 +33,8 @@ export async function packageDesktop(options = {}) {
     options.outputRoot ?? resolve(workspaceRoot, 'dist', 'desktop'),
   );
   const desktopRoot = resolve(workspaceRoot, 'apps', 'desktop');
+  const releaseChannel = options.releaseChannel ?? 'preview';
+  const osxSign = createDesktopSignOptions(releaseChannel);
   const stage = resolve(outputRoot, `stage-${architecture}`);
   const output = resolve(outputRoot, architecture);
   const resources = resolve(stage, 'release-input', 'portreeve');
@@ -94,7 +96,7 @@ export async function packageDesktop(options = {}) {
         private: true,
         type: 'module',
         main: 'main/index.js',
-        portreeveReleaseChannel: options.releaseChannel ?? 'preview',
+        portreeveReleaseChannel: releaseChannel,
       },
       null,
       2,
@@ -109,7 +111,7 @@ export async function packageDesktop(options = {}) {
         artifactVersion: artifact.version,
         artifactSha256: artifact.sha256,
         architecture,
-        releaseChannel: options.releaseChannel ?? 'preview',
+        releaseChannel,
         moduleGraph: {
           directLifecycleController: true,
           verifiedArtifactResolver: true,
@@ -142,6 +144,7 @@ export async function packageDesktop(options = {}) {
     prune: false,
     ignore: /^\/release-input(?:\/|$)/,
     extraResource: [resolve(stage, 'release-input', 'portreeve')],
+    osxSign,
   });
   if (paths.length !== 1) {
     throw new Error(`Desktop packager returned ${paths.length} output paths.`);
@@ -171,6 +174,43 @@ export async function packageDesktop(options = {}) {
   };
 }
 
+/**
+ * Preview bundles use an ad-hoc identity so every nested executable and the final
+ * application bundle are sealed consistently. This proves bundle integrity without
+ * claiming a Developer ID identity or Gatekeeper trust. Stable packaging remains
+ * unavailable until the separate Developer ID and notarization path is configured.
+ *
+ * @param {'preview'|'stable'} releaseChannel
+ */
+export function createDesktopSignOptions(releaseChannel) {
+  if (releaseChannel !== 'preview') {
+    throw new Error(
+      'Stable Desktop packaging requires configured Developer ID signing and notarization.',
+    );
+  }
+  return {
+    identity: '-',
+    identityValidation: false,
+    continueOnError: false,
+    preAutoEntitlements: false,
+    preEmbedProvisioningProfile: false,
+    ignore: isPromotedCliResource,
+    optionsForFile: () => ({ hardenedRuntime: false, timestamp: 'none' }),
+  };
+}
+
+/**
+ * The promoted CLI must remain byte-for-byte identical to its release manifest.
+ * The application signature seals that exact resource without re-signing it.
+ *
+ * @param {string} filePath
+ */
+export function isPromotedCliResource(filePath) {
+  return /\/Contents\/Resources\/portreeve\/portreeve-v[^/]+$/u.test(
+    filePath.replaceAll('\\', '/'),
+  );
+}
+
 /** @returns {'arm64'|'x64'} */
 function nativeArchitecture() {
   if (process.arch === 'arm64' || process.arch === 'x64') return process.arch;

test/desktop/package-verification.test.js

@@ -5,7 +5,12 @@ import {
   assertDesktopModuleGraph,
   assertDesktopPackageIdentity,
   assertPackagedDesktopContents,
+  verifyPackagedDesktopSignature,
 } from '../../scripts/desktop-package-lib.js';
+import {
+  createDesktopSignOptions,
+  isPromotedCliResource,
+} from '../../scripts/package-desktop.js';
 import { verifyDesktopRuntimeContract } from './runtime-contract.js';
 
 test('requires exact controller and artifact identity before packaging', () => {
@@ -15,6 +20,59 @@ test('requires exact controller and artifact identity before packaging', () => {
   );
 });
 
+test('ad-hoc signs preview bundles without implying Developer ID trust', () => {
+  const options = createDesktopSignOptions('preview');
+  expect(options).toMatchObject({
+    identity: '-',
+    identityValidation: false,
+    continueOnError: false,
+    preAutoEntitlements: false,
+    preEmbedProvisioningProfile: false,
+  });
+  expect(options.optionsForFile()).toEqual({
+    hardenedRuntime: false,
+    timestamp: 'none',
+  });
+  expect(
+    isPromotedCliResource(
+      '/tmp/PortReeve.app/Contents/Resources/portreeve/portreeve-v0.1.0-macos-arm64',
+    ),
+  ).toBe(true);
+  expect(
+    isPromotedCliResource(
+      '/tmp/PortReeve.app/Contents/Frameworks/PortReeve Helper.app',
+    ),
+  ).toBe(false);
+  expect(() => createDesktopSignOptions('stable')).toThrow(
+    'requires configured Developer ID signing and notarization',
+  );
+});
+
+test('rejects a structurally invalid packaged application signature', async () => {
+  /** @type {[string, string[]][]} */
+  const calls = [];
+  await verifyPackagedDesktopSignature(
+    '/tmp/PortReeve.app',
+    async (executable, arguments_) => {
+      calls.push([executable, arguments_]);
+      return { stdout: '', stderr: '', exitCode: 0 };
+    },
+  );
+  expect(calls).toEqual([
+    [
+      'codesign',
+      ['--verify', '--deep', '--strict', '--verbose=4', '/tmp/PortReeve.app'],
+    ],
+  ]);
+  await expect(
+    verifyPackagedDesktopSignature('/tmp/PortReeve.app', async () => ({
+      stdout: '',
+      stderr: 'code has no resources',
+      exitCode: 1,
+    })),
+  ).rejects.toThrow('code has no resources');
+});
+
 test('requires the direct lifecycle module graph and excludes the retired CLI adapter', () => {
   const inputs = [
     'apps/desktop/main/artifact.js',

test/release/documentation.test.js

@@ -177,9 +177,12 @@ test('preview installation guidance is safe, scoped, and lifecycle explicit', as
   );
   expect(installation).toContain('brew trust --formula trentbrown/portreeve/portreeve');
   expect(installation).toContain('PortReeve-VERSION-macos-arm64.dmg');
+  expect(installation).toContain('ad-hoc signed');
+  expect(installation).toMatch(/carries no verified\s+developer identity/u);
   expect(installation).toContain('System Settings');
   expect(installation).toContain('Privacy & Security');
   expect(installation).toContain('Open Anyway');
+  expect(installation).not.toContain('Before the first public preview');
   expect(installation).toContain('https://support.apple.com/102445');
   expect(installation).toContain('https://docs.brew.sh/Installation');
   expect(installation).toContain('portreeve uninstall');