Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
fix(hopper): recover provenance-verified Spotlight exits
morluto4acda94b7620
diff --git a/src/application/MacHopper.ts b/src/application/MacHopper.tsindex a211e9f2d..858e7fe48 100644--- a/src/application/MacHopper.ts+++ b/src/application/MacHopper.ts@@ -15,6 +15,8 @@ import { promisify } from "node:util";import { z } from "zod";import { homeDirectoryFromEnvironment } from "../config/homeDirectory.js";+import { HOPPER_PUBLISHER } from "../domain/hopperPublisher.js";+import { macDeveloperIdRequirement } from "../process/MacCodeSignature.js";import {downloadHopperPackage,HOPPER_DOWNLOAD_BYTES,@@ -24,29 +26,10 @@ const execFileAsync = promisify(execFile);const RELEASES_URL ="https://www.hopperapp.com/include/files-api.php?request=releases&public=true";const DOWNLOAD_PREFIX = "https://www.hopperapp.com:443/downloader/public/";--/**- * Apple publisher identity pinned for the official Hopper macOS bundle. The- * team identifier was captured from `Hopper-6.6.0-demo.dmg` at- * `https://www.hopperapp.com:443/downloader/public/Hopper-6.6.0-demo.dmg`- * (34846271 bytes, SHA-1 0be530f038249742590992199c7b042ea20ca955) with- * `codesign -dvvv`, which reported- * `Authority=Developer ID Application: Cryptic Apps (2AMA2753NF)`.- */-export const HOPPER_PUBLISHER = Object.freeze({- bundleIdentifier: "com.cryptic-apps.hopper-web-4",- teamIdentifier: "2AMA2753NF",-});--/**- * Code requirement enforcing the bundle identifier and signing team together.- * The identifier is read from the sealed CodeDirectory, so it cannot be changed- * by editing `Info.plist` the way the previous string comparison could.- */-const HOPPER_PUBLISHER_REQUIREMENT =- `= identifier "${HOPPER_PUBLISHER.bundleIdentifier}"` +- ` and anchor apple generic` +- ` and certificate leaf[subject.OU] = "${HOPPER_PUBLISHER.teamIdentifier}"`;+const HOPPER_PUBLISHER_REQUIREMENT = macDeveloperIdRequirement(+ HOPPER_PUBLISHER.bundleIdentifier,+ HOPPER_PUBLISHER.teamIdentifier,+);/** Outcome of reading a mounted bundle's signature and publisher identity. */export type MacHopperBundleVerification =diff --git a/src/application/SetupInstallFailure.test.ts b/src/application/SetupInstallFailure.test.tsindex 980e22151..d8ba27bdb 100644--- a/src/application/SetupInstallFailure.test.ts+++ b/src/application/SetupInstallFailure.test.ts@@ -1,6 +1,6 @@import { describe, expect, it } from "vitest";-import { HOPPER_PUBLISHER } from "./MacHopper.js";+import { HOPPER_PUBLISHER } from "../domain/hopperPublisher.js";import { setupInstallFailure } from "./SetupInstallFailure.js";describe("macOS Hopper setup failure projection", () => {diff --git a/src/application/SetupInstallFailure.ts b/src/application/SetupInstallFailure.tsindex 0b332fa25..944a60343 100644--- a/src/application/SetupInstallFailure.ts+++ b/src/application/SetupInstallFailure.ts@@ -1,4 +1,4 @@-import { HOPPER_PUBLISHER } from "./MacHopper.js";+import { HOPPER_PUBLISHER } from "../domain/hopperPublisher.js";export type SetupFailureCode =| "unsupported_host"diff --git a/src/domain/hopperPublisher.ts b/src/domain/hopperPublisher.tsnew file mode 100644index 000000000..6c212ea64--- /dev/null+++ b/src/domain/hopperPublisher.ts@@ -0,0 +1,12 @@+/**+ * Apple publisher identity pinned for the official Hopper macOS bundle. The+ * team identifier was captured from `Hopper-6.6.0-demo.dmg` at+ * `https://www.hopperapp.com:443/downloader/public/Hopper-6.6.0-demo.dmg`+ * (34846271 bytes, SHA-1 0be530f038249742590992199c7b042ea20ca955) with+ * `codesign -dvvv`, which reported+ * `Authority=Developer ID Application: Cryptic Apps (2AMA2753NF)`.+ */+export const HOPPER_PUBLISHER = Object.freeze({+ bundleIdentifier: "com.cryptic-apps.hopper-web-4",+ teamIdentifier: "2AMA2753NF",+});diff --git a/src/hopper/BridgeLauncher.ts b/src/hopper/BridgeLauncher.tsindex 043d394a4..3f83867bf 100644--- a/src/hopper/BridgeLauncher.ts+++ b/src/hopper/BridgeLauncher.ts@@ -33,6 +33,7 @@ import {} from "./HopperTargetLease.js";import type { HopperTargetLease } from "./HopperTargetLease.js";import { HOPPER_SHUTDOWN_TIMEOUT_MS } from "./HopperSessionValues.js";+import { verifyMacHopperNativeHelper } from "./HopperMacPublisher.js";const execFileAsync = promisify(execFile);const HOPPER_BACKGROUND_STARTUP_MS = 5_000;@@ -47,6 +48,8 @@ export interface BridgeSession {/** Process handle returned by a bridge launcher. */export type BridgeLaunch = {+ /** Verified publisher and sealed native-helper identity; omission is unknown. */+ readonly nativeHelperVerified?: true;/** Only literal native-helper arguments support a pre-handoff denial conclusion. */readonly authorizationDenialBeforeHandoff?: true;/** Release application/target exclusivity only after verified document and process cleanup. */@@ -106,6 +109,7 @@ export type HopperApplicationLauncherOptions =});export interface HopperApplicationLauncherDependencies {+ readonly verifyNativeHelper?: typeof verifyMacHopperNativeHelper;readonly platform?: NodeJS.Platform;readonly acquireTargetLease?: typeof acquireHopperTargetLease;readonly acquireApplicationLease?: typeof acquireLinuxHopperApplicationLease;@@ -213,6 +217,13 @@ export class HopperApplicationLauncher implements BridgeLauncher {if (signal?.aborted === true) return err(new HopperCancelledError());const display = await this.#privateDisplay(signal);if (!display.ok) return err(display.error);+ const nativeHelperVerified =+ (this.dependencies.platform ?? process.platform) === "darwin" &&+ this.options.launchMode === "native" &&+ (await (+ this.dependencies.verifyNativeHelper ?? verifyMacHopperNativeHelper+ )(this.options.launcherPath, this.options.environment, signal)) ===+ "verified";const prepared = await prepareHopperApplication(this.options.launcherPath,this.options.environment,@@ -257,6 +268,9 @@ export class HopperApplicationLauncher implements BridgeLauncher {...ownedLauncher,providerLifetime: "external-application",shutdownMode: "bridge-request",+ ...(nativeHelperVerified+ ? { nativeHelperVerified: true as const }+ : {}),// The vendor helper interpolates these values into AppleScript// literals without escaping. Preserve them, but withhold the// pre-handoff conclusion when they can alter that script.diff --git a/src/hopper/HopperClient.ts b/src/hopper/HopperClient.tsindex 8af42774c..2943839f4 100644--- a/src/hopper/HopperClient.ts+++ b/src/hopper/HopperClient.ts@@ -770,6 +770,10 @@ export class HopperClient {});}if (hopperLauncherReportedApplicationNotFound(launcherFailure)) {+ // Only the verified native helper's Spotlight exit precedes any target+ // handoff. Wrappers can forward the same message after opening a document.+ if (this.#resources.launch?.nativeHelperVerified === true)+ this.#resources.shutdownConfirmed = true;return new HopperStartError({userMessage:"Hopper's launcher could not find Hopper because it relies on Spotlight. Enable Spotlight indexing for the volume that contains Hopper (for example: sudo mdutil -i on /System/Volumes/Data), wait for indexing to finish, then retry opening the target.",diff --git a/src/hopper/HopperMacPublisher.ts b/src/hopper/HopperMacPublisher.tsnew file mode 100644index 000000000..f60852915--- /dev/null+++ b/src/hopper/HopperMacPublisher.ts@@ -0,0 +1,36 @@+import { HOPPER_PUBLISHER } from "../domain/hopperPublisher.js";+import { macDeveloperIdRequirement } from "../process/MacCodeSignature.js";+import { execFileOutput } from "../process/ExecFileOutput.js";++/** Failure or unavailable verification leaves custom/native provenance unknown. */+export const verifyMacHopperNativeHelper = async (+ launcherPath: string,+ environment: Readonly<NodeJS.ProcessEnv>,+ signal?: AbortSignal,+): Promise<"verified" | "unknown"> => {+ // codesign treats a bare name as a local file, while spawn searches PATH.+ // Without an explicit path they need not identify the same executable.+ if (!launcherPath.includes("/")) return "unknown";+ try {+ await execFileOutput(+ "/usr/bin/codesign",+ [+ "--verify",+ "--strict",+ `-R${macDeveloperIdRequirement("hopper", HOPPER_PUBLISHER.teamIdentifier)}`,+ launcherPath,+ ],+ {+ env: environment,+ ...(signal === undefined ? {} : { signal }),+ timeout: 5_000,+ stopSignal: "SIGKILL",+ },+ );+ return "verified";+ } catch (cause: unknown) {+ // Optional provenance: a failed check must never authorize lease release.+ void cause;+ return "unknown";+ }+};diff --git a/src/process/MacCodeSignature.ts b/src/process/MacCodeSignature.tsnew file mode 100644index 000000000..92cd7f86f--- /dev/null+++ b/src/process/MacCodeSignature.ts@@ -0,0 +1,7 @@+/** Require a sealed identifier and Apple Developer ID signing team together. */+export const macDeveloperIdRequirement = (+ identifier: string,+ teamIdentifier: string,+): string =>+ `= identifier "${identifier}" and anchor apple generic` ++ ` and certificate leaf[subject.OU] = "${teamIdentifier}"`;diff --git a/tests/acceptance/providers/hopperStartupRecovery.test.ts b/tests/acceptance/providers/hopperStartupRecovery.test.tsindex 65882a86b..842fdaa07 100644--- a/tests/acceptance/providers/hopperStartupRecovery.test.ts+++ b/tests/acceptance/providers/hopperStartupRecovery.test.ts@@ -50,7 +50,42 @@ test(});const mcp = new Client({ name: "hopper-literal-boundary", version: "1" });let runtime: string | undefined;- onTestFinished(async () => {+ try {+ await mcp.connect(transport);+ const call = (name: string, arguments_: Record<string, string> = {}) =>+ mcp.callTool({ name, arguments: arguments_ });+ expect((await call("open_binary", { path: target })).isError).not.toBe(+ true,+ );+ const first = parseMcpToolError(await call("current_document"));+ runtime = dirname(await readFile(receipt, "utf8"));+ expect(first.error).toMatchObject({+ code: "cleanup_incomplete",+ details: {+ diagnostics: {+ primary_error: {+ code: "provider_unavailable",+ details: {+ launcher: {+ exit_code: 2,+ stderr: {+ text: expect.stringContaining(+ "Not authorized to send Apple events",+ ),+ },+ },+ },+ },+ },+ },+ });+ await access(`${receipt}.document-created`);+ await access(runtime);+ expect(parseMcpToolError(await call("list_procedures"))).toEqual(first);+ expect(parseMcpToolError(await call("close_binary")).error.code).toBe(+ "cleanup_incomplete",+ );+ } finally {// SDK close can return immediately after SIGKILL. Wait for its actual// child-close event before recovering this process's retained lease.let serverExited: Promise<void> | undefined;@@ -77,41 +112,7 @@ test(});if (!acquired.acquired) throw new Error("Fixture lease remained live");await acquired.lease.release();- });- await mcp.connect(transport);- const call = (name: string, arguments_: Record<string, string> = {}) =>- mcp.callTool({ name, arguments: arguments_ });- expect((await call("open_binary", { path: target })).isError).not.toBe(- true,- );- const first = parseMcpToolError(await call("current_document"));- runtime = dirname(await readFile(receipt, "utf8"));- expect(first.error).toMatchObject({- code: "cleanup_incomplete",- details: {- diagnostics: {- primary_error: {- code: "provider_unavailable",- details: {- launcher: {- exit_code: 2,- stderr: {- text: expect.stringContaining(- "Not authorized to send Apple events",- ),- },- },- },- },- },- },- });- await access(`${receipt}.document-created`);- await access(runtime);- expect(parseMcpToolError(await call("list_procedures"))).toEqual(first);- expect(parseMcpToolError(await call("close_binary")).error.code).toBe(- "cleanup_incomplete",- );+ }}},);@@ -201,7 +202,7 @@ test("recovers a denied Hopper launch through the same stdio MCP session and CLI).toBe(false);});-test.each(["handoff", "not-found"] as const)(+test.for(["handoff", "not-found"] as const)("preserves an unconfirmed %s handoff and closes only a late bridge with matching run identity",{ timeout: 60_000 },async (launchMode, { workspace }) => {@@ -269,17 +270,21 @@ test.each(["handoff", "not-found"] as const)(},},});- if (launchMode === "not-found")+ if (launchMode === "not-found") {+ await access(`${receipt}.document-created`);expect(initial.error.details).toMatchObject({diagnostics: {primary_error: { message: expect.stringContaining("Spotlight") },},});+ }expect(parseMcpToolError(await call("list_procedures"))).toEqual(initial);const status = z.object({result: z.object({provider_operation_health: z.object({- state: z.literal("not_started"),+ state: z.literal(+ launchMode === "handoff" ? "not_started" : "unknown",+ ),stage: z.literal("launch"),}),}),diff --git a/tests/boundary/cli/hopperLaunchFailureCli.test.ts b/tests/boundary/cli/hopperLaunchFailureCli.test.tsindex 476f58f6b..9a4f55b7c 100644--- a/tests/boundary/cli/hopperLaunchFailureCli.test.ts+++ b/tests/boundary/cli/hopperLaunchFailureCli.test.ts@@ -1,6 +1,6 @@import { chmod, copyFile, rm } from "node:fs/promises";-import { describe, expect, onTestFinished } from "vitest";+import { describe, expect } from "vitest";import { z } from "zod";import { workspaceCliTest } from "../../support/cli/workspaceCliFixture.js";@@ -39,7 +39,57 @@ describe("Hopper launcher failure through the one-shot CLI", () => {const targetPath = workspace.path("probe");await copyFile("/usr/bin/true", targetPath);const loaderArgs = ["--probe"];- onTestFinished(async () => {+ try {+ for (const attempt of ["first", "retry"]) {+ const result = await cli.run({+ arguments: [+ "analyze",+ targetPath,+ "--provider",+ "hopper",+ "--json",+ ],+ environment: {+ ...workspace.environment,+ HOPPER_LAUNCHER_PATH: launcherPath,+ HOPPER_LOADER_ARGS_JSON: JSON.stringify(loaderArgs),+ REA_LOG_LEVEL: "silent",+ },+ timeoutMs: 45_000,+ });+ const retained = RetainedRuntime.safeParse(result.json);+ if (retained.success)+ await rm(+ retained.data.details.diagnostics.cleanup_error.details+ .diagnostics.runtime_root,+ { recursive: true, force: true },+ );++ expect(result.exitCode, attempt).toBe(1);+ expect(result.json, attempt).toMatchObject({+ code: "cleanup_incomplete",+ details: {+ cleanup: "incomplete",+ diagnostics: {+ primary_error: {+ code: "provider_unavailable",+ details: {+ stage: "launch",+ launcher: {+ exit_code: 2,+ stderr: {+ text: expect.stringContaining(+ "Document state is unknown",+ ),+ },+ },+ },+ },+ },+ },+ });+ }+ } finally {const recovered = await acquireHopperTargetLease({targetPath,targetKind: "executable",@@ -48,50 +98,6 @@ describe("Hopper launcher failure through the one-shot CLI", () => {});expect(recovered.acquired).toBe(true);if (recovered.acquired) await recovered.lease.release();- });-- for (const attempt of ["first", "retry"]) {- const result = await cli.run({- arguments: ["analyze", targetPath, "--provider", "hopper", "--json"],- environment: {- ...workspace.environment,- HOPPER_LAUNCHER_PATH: launcherPath,- HOPPER_LOADER_ARGS_JSON: JSON.stringify(loaderArgs),- REA_LOG_LEVEL: "silent",- },- timeoutMs: 45_000,- });- const retained = RetainedRuntime.safeParse(result.json);- if (retained.success)- await rm(- retained.data.details.diagnostics.cleanup_error.details.diagnostics- .runtime_root,- { recursive: true, force: true },- );-- expect(result.exitCode, attempt).toBe(1);- expect(result.json, attempt).toMatchObject({- code: "cleanup_incomplete",- details: {- cleanup: "incomplete",- diagnostics: {- primary_error: {- code: "provider_unavailable",- details: {- stage: "launch",- launcher: {- exit_code: 2,- stderr: {- text: expect.stringContaining(- "Document state is unknown",- ),- },- },- },- },- },- },- });}},);diff --git a/tests/boundary/providers/hopper/hopperClient.helperFailure.test.ts b/tests/boundary/providers/hopper/hopperClient.helperFailure.test.tsindex 06e725dc1..b236b21eb 100644--- a/tests/boundary/providers/hopper/hopperClient.helperFailure.test.ts+++ b/tests/boundary/providers/hopper/hopperClient.helperFailure.test.ts@@ -15,6 +15,7 @@ import type {} from "../../../../src/hopper/BridgeLauncher.js";import { HopperApplicationLauncher } from "../../../../src/hopper/BridgeLauncher.js";import { HopperClient } from "../../../../src/hopper/HopperClient.js";+import { acquireHopperTargetLease } from "../../../../src/hopper/HopperTargetLease.js";import { HopperFixtureLauncher } from "./hopperClient.fixture.js";// Failure assertions keep the external document unknown. Teardown then publishes@@ -118,6 +119,86 @@ it("does not equate an owned native helper exit with an external GUI exit", asyn});});+it.skipIf(process.platform !== "darwin")(+ "releases the runtime and target lease after a provenance-verified Spotlight exit, then retries",+ async () => {+ const directory = await createTestTempDirectory(+ "rea-hopper-native-not-found-",+ );+ const targetPath = join(directory, "target");+ await writeFile(targetPath, "fixture target");+ const loaderArgs = [+ "-e",+ 'process.stderr.write("Hopper has not been found.\\nPlease make sure that Spotlight is active in order for this tool to find Hopper\'s executable.\\n", () => process.exit(3))',+ "--",+ ];+ // Simulate a verified native helper at the launcher provenance boundary;+ // publisher verification itself has real codesign boundary coverage.+ const native = new HopperApplicationLauncher(+ {+ environment: {},+ launcherPath: process.execPath,+ targetPath,+ targetKind: "executable",+ loaderArgs,+ bridgeScriptPath: "/rea/hopper_bridge.py",+ launchMode: "native",+ },+ { verifyNativeHelper: async () => "verified" },+ );+ const retry = new HopperFixtureLauncher();+ let session: BridgeSession | undefined;+ const client = new HopperClient({+ launcher: {+ async launch(input, options) {+ if (session !== undefined) return retry.launch(input);+ session = input;+ const launched = await native.launch(input, options);+ expect(launched).toMatchObject({+ ok: true,+ value: { nativeHelperVerified: true },+ });+ return launched;+ },+ },+ startupTimeoutMs: 10_000,+ });+ onTestFinished(async () => {+ const closed = await client.close();+ if (!closed.ok) throw closed.error;+ });+ const failed = await client.start();+ expect(failed).toMatchObject({+ ok: false,+ error: { _tag: "HopperStartError", cleanupIncomplete: false },+ });+ if (failed.ok) throw new Error("Expected Spotlight failure");+ expect(projectAnalysisError(failed.error)).toMatchObject({+ code: "provider_unavailable",+ message: expect.stringContaining("Spotlight"),+ details: { launcher: { exit_code: 3 } },+ });+ if (session === undefined) throw new Error("Missing launch session");+ await expect(access(session.directory)).rejects.toMatchObject({+ code: "ENOENT",+ });+ const lease = await acquireHopperTargetLease({+ targetPath,+ targetKind: "executable",+ loaderArgs,+ runId: "spotlight-retry-proof",+ });+ if (!lease.acquired)+ throw new Error("Spotlight failure retained the target lease");+ await lease.lease.release();+ expect(await client.start()).toMatchObject({ ok: true });+ expect(await client.callTool("echo", { value: "retried" })).toEqual({+ ok: true,+ value: { value: "retried" },+ });+ },+);+it.each(["exit", "signal", "exit75"] as const)("reports a failed non-owning launcher %s without waiting for bridge timeout or inventing a GUI exit",async (termination) => {diff --git a/tests/boundary/setup/macosHopperPublisherVerification.test.ts b/tests/boundary/setup/macosHopperPublisherVerification.test.tsindex 29b696e85..dcb85cca5 100644--- a/tests/boundary/setup/macosHopperPublisherVerification.test.ts+++ b/tests/boundary/setup/macosHopperPublisherVerification.test.ts@@ -6,10 +6,11 @@ import { promisify } from "node:util";import { describe, expect, it } from "vitest";import {- HOPPER_PUBLISHER,macHopperInstallDisclosure,systemMacHopperInstallHost,} from "../../../src/application/MacHopper.js";+import { verifyMacHopperNativeHelper } from "../../../src/hopper/HopperMacPublisher.js";+import { HOPPER_PUBLISHER } from "../../../src/domain/hopperPublisher.js";import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";const run = promisify(execFile);@@ -94,6 +95,24 @@ describe("macOS Hopper publisher verification", () => {);});+ itDarwin(+ "withholds native-helper provenance from custom signed or modified executables",+ async () => {+ const root = await createTestTempDirectory(+ "rea-hopper-helper-publisher-",+ );+ const app = await buildBundle(root, "hopper");+ const executable = join(app, ...executableSegments);+ await expect(+ verifyMacHopperNativeHelper(executable, process.env),+ ).resolves.toBe("unknown");+ await appendFile(executable, "modified\n");+ await expect(+ verifyMacHopperNativeHelper(executable, process.env),+ ).resolves.toBe("unknown");+ },+ );+// Opt-in positive control: point this at a mounted official Hopper bundle,// for example `hdiutil attach -readonly -nobrowse Hopper-6.6.0-demo.dmg`.// It proves the pinned requirement is satisfiable by the real publisher, so@@ -103,6 +122,12 @@ describe("macOS Hopper publisher verification", () => {"accepts the officially signed Hopper application",async () => {await expect(host().validBundle(realApp ?? "")).resolves.toBe("verified");+ await expect(+ verifyMacHopperNativeHelper(+ join(realApp ?? "", ...executableSegments),+ process.env,+ ),+ ).resolves.toBe("verified");},);});diff --git a/tests/fixtures/hopperLaunchAdmission.mjs b/tests/fixtures/hopperLaunchAdmission.mjsindex bb80ad448..6a5033d6b 100644--- a/tests/fixtures/hopperLaunchAdmission.mjs+++ b/tests/fixtures/hopperLaunchAdmission.mjs@@ -20,7 +20,8 @@ if (mode === "denied" || mode === "denied-after-handoff") {},);} else if (mode === "not-found") {- // The native helper's Spotlight lookup fails before any Apple event.+ // A custom wrapper can forward the native diagnostic after a handoff.+ await writeFile(`${receiptPath}.document-created`, "unconfirmed");process.stderr.write("Hopper has not been found.\nPlease make sure that Spotlight is active in order for this tool to find Hopper's executable.\n",() => process.exit(3),