rea-agents 6.0.0 → 6.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (343) hide show
  1. package/README.md +23 -17
  2. package/bridge/android/ReaJadxBridge.java +14 -5
  3. package/bridge/ghidra/ReaGhidraBridge.java +173 -47
  4. package/bridge/hopper_bridge.py +310 -128
  5. package/bridge/mitmproxy/capture.py +0 -2
  6. package/bridge/native/rea_lldb_tracer.py +630 -94
  7. package/bridge/process/ProcessRunTokenReader.swift +39 -5
  8. package/bridge/pwntools/recorded_crash_impl.py +4 -0
  9. package/dist/android/JadxConfiguration.js +196 -33
  10. package/dist/android/JadxMcpTransport.js +4 -0
  11. package/dist/android/JadxProtocol.js +6 -0
  12. package/dist/android/JadxProvider.js +19 -2
  13. package/dist/android/JadxSession.js +23 -4
  14. package/dist/application/AnalysisContextQueries.js +8 -35
  15. package/dist/application/AnalysisDocument.js +32 -0
  16. package/dist/application/AppBundleExecutable.js +67 -21
  17. package/dist/application/CallPathTracing.js +19 -3
  18. package/dist/application/CapabilityInventory.js +6 -3
  19. package/dist/application/ClientConfigurationDocument.js +871 -6
  20. package/dist/application/ClientRegistrationIdentity.js +26 -5
  21. package/dist/application/ClientRegistrationStatus.js +29 -14
  22. package/dist/application/DirectAnalysis.js +27 -37
  23. package/dist/application/Doctor.js +4 -2
  24. package/dist/application/DoctorScope.js +25 -13
  25. package/dist/application/EnhancedLiteralTracing.js +22 -25
  26. package/dist/application/EnhancedTools.js +13 -11
  27. package/dist/application/EvidenceBundleFiles.js +23 -11
  28. package/dist/application/FunctionAnalysisEvidence.js +2 -3
  29. package/dist/application/InventoryProjectionEvidence.js +4 -3
  30. package/dist/application/InvestigationProviders.js +3 -2
  31. package/dist/application/JsonFiles.js +50 -28
  32. package/dist/application/ProcedureAddressResolution.js +11 -0
  33. package/dist/application/ReconstructionCoverageService.js +7 -4
  34. package/dist/application/ReconstructionObligationLedgerService.js +4 -3
  35. package/dist/application/Setup.js +13 -1
  36. package/dist/application/SetupClientConfiguration.js +10 -15
  37. package/dist/application/SetupHost.js +5 -2
  38. package/dist/application/SetupPlan.js +5 -3
  39. package/dist/application/SupportedClients.js +34 -1
  40. package/dist/application/Uninstall.js +4 -3
  41. package/dist/application/Update.js +18 -3
  42. package/dist/application/UpdateRuntime.js +46 -25
  43. package/dist/application/WebModuleTraceService.js +4 -2
  44. package/dist/application/WebNetworkCaptureService.js +4 -2
  45. package/dist/application/WebRuntimeService.js +5 -3
  46. package/dist/application/WebScriptExportService.js +2 -2
  47. package/dist/application/WebSourceLocationService.js +4 -2
  48. package/dist/application/WorkflowEvidence.js +82 -0
  49. package/dist/application/binary/AnalysisProviderEvaluation.js +21 -5
  50. package/dist/application/binary/AnalysisProviderRegistry.js +2 -0
  51. package/dist/application/binary/AnalysisSnapshotCache.js +3 -6
  52. package/dist/application/binary/BinarySession.js +95 -68
  53. package/dist/application/binary/BinarySessionOpen.js +3 -3
  54. package/dist/application/binary/BinarySessionRecords.js +25 -3
  55. package/dist/application/binary/BinarySessionStatus.js +17 -1
  56. package/dist/application/binary/CompositeProvider.js +13 -0
  57. package/dist/application/binary/LazyAnalysisProvider.js +3 -0
  58. package/dist/application/binaryDiagnostics/BinaryLayoutService.js +4 -2
  59. package/dist/application/binaryDiagnostics/RecordedCrashService.js +4 -2
  60. package/dist/application/evm/EvmInterfaceService.js +4 -2
  61. package/dist/application/investigation/EvidenceLedger.js +21 -7
  62. package/dist/application/investigation/InvestigationRecords.js +8 -0
  63. package/dist/application/javascript/JavaScriptAnalysisControl.js +34 -0
  64. package/dist/application/javascript/JavaScriptApplicationEvidence.js +24 -3
  65. package/dist/application/javascript/JavaScriptApplicationEvidenceGraph.js +19 -2
  66. package/dist/application/javascript/JavaScriptApplicationService.js +22 -15
  67. package/dist/application/javascript/JavaScriptApplicationWorkflowService.js +5 -5
  68. package/dist/application/javascript/JavaScriptArtifactAnalysis.js +5 -4
  69. package/dist/application/javascript/JavaScriptArtifactGraphBuilder.js +39 -7
  70. package/dist/application/javascript/JavaScriptArtifactPathResolution.js +6 -3
  71. package/dist/application/javascript/JavaScriptArtifactReconstruction.js +11 -3
  72. package/dist/application/javascript/JavaScriptModuleRelationships.js +37 -8
  73. package/dist/application/javascript/JavaScriptRecoveryService.js +4 -2
  74. package/dist/application/javascript/JavaScriptRuntimeObservationService.js +3 -1
  75. package/dist/application/javascript/JavaScriptRuntimeReconciliationService.js +3 -3
  76. package/dist/application/javascript/JavaScriptSemanticGraphBuilder.js +63 -61
  77. package/dist/application/javascript/JavaScriptSemanticGraphValueProjection.js +23 -1
  78. package/dist/application/managed/ManagedApplicationGraphService.js +4 -3
  79. package/dist/application/managed/ManagedMemberComparisonService.js +7 -4
  80. package/dist/application/managed/ManagedNativeVerificationService.js +4 -3
  81. package/dist/application/managed/ManagedReconstructionService.js +4 -3
  82. package/dist/application/process/ProcessCli.js +14 -6
  83. package/dist/application/process/ProcessEvidence.js +4 -3
  84. package/dist/application/workflowInputError.js +18 -0
  85. package/dist/artifacts/ArtifactProvider.js +12 -2
  86. package/dist/artifacts/MachOSliceArtifactReader.js +98 -14
  87. package/dist/artifacts/NativeDmgArtifactReader.js +13 -6
  88. package/dist/artifacts/apple/AppleAssetCatalogAnalysis.js +22 -3
  89. package/dist/artifacts/apple/InterfaceBuilderAnalysis.js +176 -56
  90. package/dist/artifacts/apple/InterfaceBuilderDecodeBudget.js +195 -0
  91. package/dist/artifacts/apple/KeyedArchiveReader.js +36 -22
  92. package/dist/artifacts/apple/MachoLoadCommandReader.js +92 -31
  93. package/dist/artifacts/apple/NibArchive.js +81 -14
  94. package/dist/artifacts/apple/NibViewHierarchy.js +10 -3
  95. package/dist/artifacts/apple/PlistNumberLiterals.js +164 -0
  96. package/dist/artifacts/inventory/ArtifactGraphConstruction.js +13 -8
  97. package/dist/artifacts/inventory/scanCanonical.js +11 -14
  98. package/dist/artifacts/javascript/JavaScriptArtifactFiles.js +6 -2
  99. package/dist/browser/CdpCaptureCompleteness.js +2 -0
  100. package/dist/browser/CdpCaptureEventHandlers.js +76 -11
  101. package/dist/browser/CdpCaptureEventTypes.js +5 -1
  102. package/dist/browser/CdpCaptureEvents.js +25 -0
  103. package/dist/browser/CdpConnection.js +30 -11
  104. package/dist/browser/CdpOptionalCommand.js +2 -3
  105. package/dist/browser/CdpPageCapture.js +23 -1
  106. package/dist/browser/PlaywrightElectronActiveActions.js +32 -23
  107. package/dist/browser/PlaywrightElectronActiveProjection.js +141 -0
  108. package/dist/browser/PlaywrightElectronActiveProvider.js +123 -124
  109. package/dist/browser/WebSourceMapFetcher.js +426 -72
  110. package/dist/browser/assets/LocalWebScriptArtifacts.js +2 -2
  111. package/dist/browser/history/CaptureFailures.js +37 -1
  112. package/dist/browser/history/CaptureRelease.js +5 -0
  113. package/dist/browser/history/HarCaptureAdapter.js +3 -3
  114. package/dist/browser/history/HarJson.js +3 -2
  115. package/dist/browser/history/HistoricalCaptureDecoder.js +4 -2
  116. package/dist/cli/analysisSelector.js +23 -0
  117. package/dist/cli/applicationCommands.js +2 -3
  118. package/dist/cli/coreBinaryCommands.js +70 -12
  119. package/dist/cli/electronCommands.js +7 -6
  120. package/dist/cli/javascriptApplicationAnalysis.js +7 -3
  121. package/dist/cli/jsonOutput.js +4 -99
  122. package/dist/cli/nativeCallCommands.js +2 -3
  123. package/dist/cli/webRuntimeCommands.js +8 -8
  124. package/dist/cli.js +2 -1
  125. package/dist/cliCommandNames.js +0 -1
  126. package/dist/cliJsonInput.js +9 -4
  127. package/dist/config/environment.js +4 -0
  128. package/dist/config/ghidraStartupTimeout.js +17 -0
  129. package/dist/config/mcpResponseBudget.js +22 -0
  130. package/dist/config/parseConfig.js +2 -1
  131. package/dist/contracts/enhancedInputs.js +5 -3
  132. package/dist/contracts/enhancedToolContracts.js +3 -3
  133. package/dist/contracts/hopperMemoryContracts.js +2 -5
  134. package/dist/contracts/javascript/electronToolContracts.js +1 -1
  135. package/dist/contracts/managed/managedToolContracts.js +2 -4
  136. package/dist/contracts/native/nativeToolContracts.js +4 -2
  137. package/dist/contracts/officialToolContracts.js +14 -15
  138. package/dist/contracts/promptContracts.js +3 -3
  139. package/dist/contracts/sessionLifecycleInputs.js +3 -7
  140. package/dist/contracts/sessionStatusContract.js +2 -4
  141. package/dist/contracts/sessionToolContracts.js +4 -6
  142. package/dist/contracts/sessionToolSchemas.js +2 -5
  143. package/dist/contracts/toolContractExamples.js +0 -1
  144. package/dist/contracts/toolContractHelpers.js +4 -1
  145. package/dist/contracts/toolEffects.js +0 -1
  146. package/dist/contracts/toolOutputSchemaGroups.js +28 -27
  147. package/dist/contracts/toolOutputSchemaPrimitives.js +18 -0
  148. package/dist/contracts/toolSchemaMetadata.js +69 -10
  149. package/dist/contracts/webNetworkCaptureToolContracts.js +1 -1
  150. package/dist/domain/analysisErrorBase.js +8 -3
  151. package/dist/domain/analysisErrorCore.js +3 -1
  152. package/dist/domain/analysisErrorPresentation.js +72 -17
  153. package/dist/domain/analysisErrorProjection.js +106 -27
  154. package/dist/domain/android/androidAnalysis.js +2 -4
  155. package/dist/domain/android/androidApplication.js +17 -9
  156. package/dist/domain/apple/appleApplication.js +41 -14
  157. package/dist/domain/apple/dyldEnvironment.js +73 -0
  158. package/dist/domain/apple/dylibResolution.js +120 -9
  159. package/dist/domain/apple/dylibResolutionFindings.js +9 -7
  160. package/dist/domain/apple/interfaceBuilderGraph.js +25 -13
  161. package/dist/domain/apple/interfaceBuilderKeyedArchive.js +13 -3
  162. package/dist/domain/apple/keyedArchive.js +9 -1
  163. package/dist/domain/apple/machoContainer.js +54 -0
  164. package/dist/domain/apple/plistNumbers.js +76 -0
  165. package/dist/domain/artifactIdentity.js +29 -0
  166. package/dist/domain/artifactInventoryEvidence.js +19 -24
  167. package/dist/domain/bridgeCandidateProjection.js +71 -0
  168. package/dist/domain/browserCompleteness.js +1 -0
  169. package/dist/domain/browserObservationError.js +24 -5
  170. package/dist/domain/browserScenarioValues.js +2 -6
  171. package/dist/domain/bundleComparison.js +3 -2
  172. package/dist/domain/canonicalJsonDigestSteps.js +133 -0
  173. package/dist/domain/canonicalOrdering.js +9 -5
  174. package/dist/domain/changedBehavior.js +6 -6
  175. package/dist/domain/comparisonSourceEvidence.js +40 -0
  176. package/dist/domain/configurationErrors.js +1 -1
  177. package/dist/domain/evidence.js +64 -9
  178. package/dist/domain/evidenceBundle.js +42 -1
  179. package/dist/domain/evidenceErrors.js +12 -1
  180. package/dist/domain/explicitSensitiveFailure.js +17 -1
  181. package/dist/domain/firmware/firmwareAnalysis.js +6 -7
  182. package/dist/domain/hopperErrors.js +23 -2
  183. package/dist/domain/hopperValues.js +51 -8
  184. package/dist/domain/immutableJson.js +114 -0
  185. package/dist/domain/inputIssueProjection.js +3 -0
  186. package/dist/domain/javascript/electronActiveObservation.js +30 -4
  187. package/dist/domain/javascript/electronStaticAnalysisValues.js +6 -12
  188. package/dist/domain/javascript/javascriptApplicationAnalysis.js +71 -23
  189. package/dist/domain/javascript/javascriptApplicationGraph.js +13 -0
  190. package/dist/domain/javascript/javascriptAstValues.js +20 -0
  191. package/dist/domain/javascript/javascriptRecovery.js +3 -8
  192. package/dist/domain/javascript/javascriptSemanticAnalysis.js +97 -2
  193. package/dist/domain/javascript/javascriptSemanticCoverage.js +6 -5
  194. package/dist/domain/javascript/javascriptSemanticDataEffectHelpers.js +9 -17
  195. package/dist/domain/javascript/javascriptSemanticDataEffects.js +22 -5
  196. package/dist/domain/javascript/javascriptSemanticGraph.js +13 -0
  197. package/dist/domain/javascript/javascriptSemanticGraphSchemas.js +1 -0
  198. package/dist/domain/javascript/javascriptSemanticPrimitives.js +25 -17
  199. package/dist/domain/javascript/javascriptSemanticQuerySchemas.js +8 -4
  200. package/dist/domain/javascript/javascriptSemanticResourceLimits.js +77 -0
  201. package/dist/domain/javascript/javascriptSemanticValues.js +83 -11
  202. package/dist/domain/javascript/javascriptSourceParser.js +6 -2
  203. package/dist/domain/javascript/javascriptStaticAnalysis.js +22 -17
  204. package/dist/domain/javascript/javascriptStaticAnalysisBundler.js +5 -3
  205. package/dist/domain/javascript/javascriptStaticAnalysisCalls.js +14 -4
  206. package/dist/domain/javascript/javascriptStaticAnalysisFindings.js +66 -7
  207. package/dist/domain/javascript/javascriptStaticAnalysisHelpers.js +28 -16
  208. package/dist/domain/javascript/javascriptStaticAnalysisState.js +3 -2
  209. package/dist/domain/jsonSerialization.js +109 -0
  210. package/dist/domain/jsonValue.js +90 -6
  211. package/dist/domain/localPath.js +6 -0
  212. package/dist/domain/managed/managedApplicationGraph.js +10 -10
  213. package/dist/domain/managed/managedInspectionEvidence.js +16 -0
  214. package/dist/domain/managed/managedMemberComparisonMatch.js +5 -9
  215. package/dist/domain/managed/managedNativeVerification.js +3 -9
  216. package/dist/domain/native/fileOffsetPartialObservation.js +1 -0
  217. package/dist/domain/native/nativeCallObservation.js +33 -11
  218. package/dist/domain/native/nativeCallPartialObservation.js +33 -0
  219. package/dist/domain/process/processCapture.js +8 -4
  220. package/dist/domain/process/processComparison.js +38 -4
  221. package/dist/domain/process/processScenario.js +11 -10
  222. package/dist/domain/propertyListKeys.js +1 -1
  223. package/dist/domain/propertyListXmlText.js +19 -0
  224. package/dist/domain/providerAdapterError.js +1 -1
  225. package/dist/domain/providerOperationHealth.js +54 -0
  226. package/dist/domain/reconstructionVerification.js +6 -43
  227. package/dist/domain/reconstructionVerificationSchemas.js +2 -2
  228. package/dist/domain/staticRuntimeCorrelation.js +6 -43
  229. package/dist/domain/webBundleAnalysis.js +20 -8
  230. package/dist/domain/webBundleAnalyzerInspection.js +13 -8
  231. package/dist/domain/webBundleAnalyzerResult.js +41 -2
  232. package/dist/domain/webRuntime.js +19 -5
  233. package/dist/domain/webSourceLocation.js +1 -0
  234. package/dist/firmware/FirmwareFiles.js +1 -1
  235. package/dist/generatedPackageMetadata.js +1 -1
  236. package/dist/ghidra/GhidraAnalysisProfile.js +5 -0
  237. package/dist/ghidra/GhidraClient.js +47 -14
  238. package/dist/ghidra/GhidraDiagnostics.js +7 -7
  239. package/dist/ghidra/GhidraFunctionValues.js +10 -7
  240. package/dist/ghidra/GhidraInstallation.js +18 -21
  241. package/dist/ghidra/GhidraInventoryValues.js +14 -4
  242. package/dist/ghidra/GhidraJavaLaunch.js +62 -0
  243. package/dist/ghidra/GhidraLauncher.js +33 -16
  244. package/dist/ghidra/GhidraProviderCapabilities.js +14 -2
  245. package/dist/ghidra/GhidraProviderClient.js +23 -12
  246. package/dist/ghidra/GhidraSessionError.js +11 -7
  247. package/dist/ghidra/GhidraTargetSnapshot.js +47 -12
  248. package/dist/ghidra/GhidraTransport.js +20 -0
  249. package/dist/hopper/BridgeLauncher.js +31 -11
  250. package/dist/hopper/HopperAnalysisProfile.js +62 -4
  251. package/dist/hopper/HopperCleanup.js +15 -3
  252. package/dist/hopper/HopperClient.js +222 -14
  253. package/dist/hopper/HopperFileOffset.js +237 -0
  254. package/dist/hopper/HopperMachOImage.js +196 -0
  255. package/dist/hopper/HopperOperationStage.js +6 -0
  256. package/dist/hopper/HopperProvider.js +63 -9
  257. package/dist/hopper/HopperProviderCapabilities.js +19 -1
  258. package/dist/hopper/HopperRegexSearch.js +137 -0
  259. package/dist/hopper/HopperRegexWorker.js +27 -0
  260. package/dist/hopper/HopperRequestQueue.js +68 -19
  261. package/dist/hopper/HopperTargetLease.js +3 -2
  262. package/dist/inspector/JavaScriptRuntimeScope.js +9 -1
  263. package/dist/inspector/V8InspectorCaptureProjection.js +8 -3
  264. package/dist/inspector/V8InspectorProvider.js +47 -11
  265. package/dist/javascript/sourceMaps/DecodedSourceMap.js +47 -0
  266. package/dist/javascript/sourceMaps/SourceMapCommand.js +16 -0
  267. package/dist/javascript/sourceMaps/SourceMapFormat.js +79 -31
  268. package/dist/javascript/sourceMaps/TraceSourceMap.js +14 -28
  269. package/dist/mcpDoctor.js +62 -2
  270. package/dist/native/AppleDispatchCoverage.js +47 -6
  271. package/dist/native/AppleDispatchDecodeFacts.js +6 -0
  272. package/dist/native/AppleDispatchMetadata.js +6 -3
  273. package/dist/native/AppleMachoFixups.js +48 -24
  274. package/dist/native/AppleMachoSelection.js +32 -16
  275. package/dist/native/AppleObjcCategories.js +6 -2
  276. package/dist/native/AppleObjcDispatchFacets.js +5 -2
  277. package/dist/native/AppleObjcProperties.js +2 -1
  278. package/dist/native/AppleSwiftDispatchFacets.js +27 -21
  279. package/dist/native/AppleSwiftVtables.js +21 -15
  280. package/dist/native/CommandRunner.js +81 -84
  281. package/dist/native/LldbCallTracer.js +365 -102
  282. package/dist/native/LldbRetainedObservations.js +178 -0
  283. package/dist/native/NativeCallObservation.js +62 -3
  284. package/dist/native/NativeMacOSProvider.js +98 -17
  285. package/dist/native/SignatureTargetBinding.js +155 -0
  286. package/dist/native/parsers/lipo.js +71 -1
  287. package/dist/native/pwndbg/PwndbgCoreContext.js +25 -5
  288. package/dist/native/pwntools/RecordedCrashStructureBindings.js +2 -0
  289. package/dist/process/DarwinProcessRunTokenReader.js +8 -9
  290. package/dist/process/ExecFileOutput.js +20 -0
  291. package/dist/process/OwnedCommand.js +7 -2
  292. package/dist/process/ProcessOwnership.js +203 -53
  293. package/dist/process/ProcessOwnershipObservation.js +49 -4
  294. package/dist/process/ProviderProcess.js +38 -7
  295. package/dist/process/capture/ProcessCaptureError.js +2 -2
  296. package/dist/process/capture/ProcessCaptureLifecycle.js +100 -34
  297. package/dist/server/EvidenceMcpServer.js +146 -0
  298. package/dist/server/createServer.js +15 -8
  299. package/dist/server/registerAndroidTools.js +2 -4
  300. package/dist/server/registerApplicationTools/helpers.js +2 -4
  301. package/dist/server/registerArtifactComparisonTool.js +11 -7
  302. package/dist/server/registerBinaryDiagnosticsTools.js +2 -4
  303. package/dist/server/registerBrowserScenarioTool.js +2 -4
  304. package/dist/server/registerBrowserTools.js +2 -4
  305. package/dist/server/registerBundleComparisonTool.js +2 -3
  306. package/dist/server/registerCloseLifecycleTool.js +8 -18
  307. package/dist/server/registerElectronTools.js +2 -4
  308. package/dist/server/registerEnhancedTools.js +18 -59
  309. package/dist/server/registerEvidenceTools.js +2 -4
  310. package/dist/server/registerEvmTools.js +2 -4
  311. package/dist/server/registerFirmwareTools.js +2 -4
  312. package/dist/server/registerFunctionComparisonTool.js +10 -6
  313. package/dist/server/registerInvestigationTools.js +7 -7
  314. package/dist/server/registerJavaScriptRecoveryTool.js +2 -4
  315. package/dist/server/registerJavaScriptRuntimeObservationTools.js +2 -4
  316. package/dist/server/registerManagedWorkflowTools/compareManagedMembers.js +2 -4
  317. package/dist/server/registerManagedWorkflowTools/importManagedReconstruction.js +2 -4
  318. package/dist/server/registerManagedWorkflowTools/projectManagedApplicationGraph.js +2 -4
  319. package/dist/server/registerManagedWorkflowTools/verifyManagedNativeBoundaries.js +2 -4
  320. package/dist/server/registerOfficialTools.js +2 -4
  321. package/dist/server/registerProcessComparisonTool.js +71 -45
  322. package/dist/server/registerRecordedCrashTools.js +2 -4
  323. package/dist/server/registerSessionRecordTools.js +5 -6
  324. package/dist/server/registerSessionStatusTool.js +17 -3
  325. package/dist/server/registerSessionTools.js +11 -3
  326. package/dist/server/registerWebModuleTool.js +2 -4
  327. package/dist/server/registerWebNetworkCaptureTool.js +2 -4
  328. package/dist/server/registerWebRuntimeTools.js +3 -7
  329. package/dist/server/registerWebScriptTool.js +2 -4
  330. package/dist/server/registerWebSourceLocationTool.js +2 -4
  331. package/dist/server/runDerivedOperation.js +15 -3
  332. package/dist/server/sessionAvailabilityPolicy.js +0 -1
  333. package/dist/server/toolRegistrationOptions.js +2 -2
  334. package/dist/server/toolResult.js +62 -10
  335. package/dist/server/toolResultEncoding.js +33 -0
  336. package/install.sh +1 -1
  337. package/native/windows/build/manifest.json +1 -1
  338. package/package.json +8 -3
  339. package/scripts/electron-active-hook-boundaries.cjs +18 -20
  340. package/scripts/electron-active-hook.cjs +241 -37
  341. package/skills/reverse-engineer-anything/SKILL.md +11 -3
  342. package/skills/reverse-engineer-anything/references/javascript-applications.md +8 -1
  343. package/dist/ghidra/GhidraDefaults.js +0 -2
@@ -6,12 +6,14 @@ import { AnalysisCapabilityUnavailableError } from "../domain/analysisErrorCore.
6
6
  import { HopperCancelledError, HopperProcessError, HopperProtocolError, HopperRemoteError, HopperStartError, HopperTimeoutError, } from "../domain/hopperErrors.js";
7
7
  import {} from "../domain/analysisErrorBase.js";
8
8
  import { hopperStartupFailure, } from "../domain/hopperStartupFailure.js";
9
+ import { providerRetryAction, sharedProviderFailureStage, } from "../domain/providerOperationHealth.js";
9
10
  import { err, ok } from "../domain/result.js";
10
11
  import { silentLogger } from "../logger.js";
11
12
  import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";
12
13
  import { ProviderStartupDeadline } from "../process/ProviderDeadline.js";
13
14
  import { ProviderRunLineage } from "../process/ProviderRunLineage.js";
14
15
  import { ProviderProcessSupervisor, } from "../process/ProviderProcess.js";
16
+ import { hopperOperationStage } from "./HopperOperationStage.js";
15
17
  import { cleanupHopperSession } from "./HopperCleanup.js";
16
18
  import { parseHopperServerInfo, } from "./HopperSessionValues.js";
17
19
  import { connectHopperSocketOnce } from "./HopperSocketConnection.js";
@@ -21,7 +23,6 @@ import { HopperResponseStream } from "./HopperResponseStream.js";
21
23
  import { responseResult, } from "./protocol.js";
22
24
  const SHUTDOWN_TIMEOUT_MS = 30_000;
23
25
  const SESSION_ROOT = process.platform === "darwin" ? "/tmp" : tmpdir();
24
- /** Safe launcher telemetry; stderr content is intentionally never exposed. */
25
26
  /**
26
27
  * Owns one authenticated NDJSON-over-Unix-socket bridge session.
27
28
  *
@@ -45,6 +46,7 @@ export class HopperClient {
45
46
  #closing = false;
46
47
  #launcherExitCode;
47
48
  #launcherFailureDiagnostic;
49
+ #operationFailure;
48
50
  #startupController;
49
51
  #startPromise;
50
52
  #closePromise;
@@ -52,11 +54,31 @@ export class HopperClient {
52
54
  this.#responses.push(chunk);
53
55
  };
54
56
  #onSocketError = () => {
55
- this.#failAll(new HopperProcessError(null));
57
+ const error = new HopperProcessError(null, undefined, undefined, undefined, "unreachable");
58
+ this.#failAll(error);
59
+ this.#rememberProcessFailure(error, []);
56
60
  };
57
61
  #onSocketClose = () => {
58
- if (!this.#closing)
59
- this.#failAll(new HopperProcessError(null));
62
+ if (this.#closing)
63
+ return;
64
+ const launch = this.#launch;
65
+ if (launch?.providerLifetime === "launcher-process" &&
66
+ this.#launcherExitCode !== undefined)
67
+ return;
68
+ if (launch?.providerLifetime === "launcher-process") {
69
+ setImmediate(() => {
70
+ if (this.#closing || this.#launcherExitCode !== undefined)
71
+ return;
72
+ const exitCode = launch.process.exitCode ?? null;
73
+ const error = new HopperProcessError(exitCode, this.#launcherFailureDiagnostic, undefined, undefined, exitCode !== null ? "exited" : "unreachable");
74
+ this.#failAll(error);
75
+ this.#rememberProcessFailure(error, []);
76
+ });
77
+ return;
78
+ }
79
+ const error = new HopperProcessError(null, undefined, undefined, undefined, "unreachable");
80
+ this.#failAll(error);
81
+ this.#rememberProcessFailure(error, []);
60
82
  };
61
83
  constructor(options) {
62
84
  this.#logger = options.logger ?? silentLogger;
@@ -91,6 +113,56 @@ export class HopperClient {
91
113
  requestActivity() {
92
114
  return this.#requests.activity();
93
115
  }
116
+ /**
117
+ * Latest operational health for this owned bridge.
118
+ * A recorded exit remains visible after request activity returns to idle.
119
+ */
120
+ operationHealth() {
121
+ const failure = this.#operationFailure;
122
+ if (failure !== undefined) {
123
+ const requests = failure.requests.map((request) => ({
124
+ ...request,
125
+ stage: failure.startupFailure
126
+ ? "launch"
127
+ : hopperOperationStage(request.operation),
128
+ }));
129
+ return {
130
+ state: failure.state,
131
+ stage: requests.length === 0
132
+ ? failure.startupFailure
133
+ ? "launch"
134
+ : "connection"
135
+ : sharedProviderFailureStage(requests),
136
+ retryAction: providerRetryAction(failure.state, failure.startupFailure),
137
+ exitCode: failure.exitCode,
138
+ requests,
139
+ };
140
+ }
141
+ const activity = this.requestActivity();
142
+ if (activity !== null) {
143
+ const stage = hopperOperationStage(activity.operation);
144
+ return {
145
+ state: "busy",
146
+ stage,
147
+ retryAction: "wait",
148
+ exitCode: null,
149
+ requests: [
150
+ {
151
+ requestId: activity.requestId,
152
+ operation: activity.operation,
153
+ stage,
154
+ },
155
+ ],
156
+ };
157
+ }
158
+ return {
159
+ state: "idle",
160
+ stage: null,
161
+ retryAction: null,
162
+ exitCode: null,
163
+ requests: [],
164
+ };
165
+ }
94
166
  /** Launch the bridge once and complete its authenticated health handshake. */
95
167
  start(signal) {
96
168
  if (this.#closePromise !== undefined) {
@@ -120,8 +192,22 @@ export class HopperClient {
120
192
  };
121
193
  void started.then((result) => {
122
194
  release();
123
- if (!result.ok)
195
+ if (!result.ok) {
196
+ if (result.error instanceof HopperProcessError)
197
+ this.#rememberProcessFailure(result.error, []);
198
+ else if (this.#operationFailure === undefined &&
199
+ (result.error instanceof HopperTimeoutError ||
200
+ result.error instanceof HopperStartError))
201
+ this.#operationFailure = {
202
+ state: result.error instanceof HopperTimeoutError
203
+ ? "not_started"
204
+ : "unknown",
205
+ exitCode: null,
206
+ startupFailure: true,
207
+ requests: [],
208
+ };
124
209
  reset();
210
+ }
125
211
  }, (cause) => {
126
212
  this.#logger.debug({ error: cause instanceof Error ? cause.message : String(cause) }, "Hopper startup promise rejected during bookkeeping");
127
213
  release();
@@ -132,6 +218,7 @@ export class HopperClient {
132
218
  async #start(signal) {
133
219
  if (isAborted(signal))
134
220
  return err(new HopperCancelledError());
221
+ this.#operationFailure = undefined;
135
222
  if (this.#socket !== undefined || this.#runtimeRoot !== undefined) {
136
223
  return err(new HopperProtocolError("Hopper client is already started"));
137
224
  }
@@ -283,12 +370,18 @@ export class HopperClient {
283
370
  async #connect(socketPath, deadline) {
284
371
  while (deadline.remainingMs() > 0) {
285
372
  if (deadline.signal.aborted)
286
- return err(startupInterruption(deadline));
373
+ return err(await this.#startupInterruption(deadline));
287
374
  if (this.#closing)
288
375
  return err(new HopperProcessError(null));
289
376
  if (this.#launcherExitCode !== undefined &&
290
- hopperStartupFailure(this.#launcherExitCode) !== undefined)
291
- return err(new HopperProcessError(this.#launcherExitCode, this.#launcherFailureDiagnostic));
377
+ this.#launch !== undefined &&
378
+ (this.#launch.providerLifetime === "launcher-process" ||
379
+ this.#launcherExitCode !== 0)) {
380
+ const failure = await this.#launcherStartupFailure(this.#launch.providerLifetime === "launcher-process", this.#launcherExitCode, deadline);
381
+ return deadline.interruption === "cancelled"
382
+ ? err(await this.#startupInterruption(deadline))
383
+ : err(failure);
384
+ }
292
385
  try {
293
386
  await access(socketPath);
294
387
  }
@@ -296,7 +389,7 @@ export class HopperClient {
296
389
  // best-effort cleanup: socket polling; absence means keep waiting.
297
390
  void cause;
298
391
  if ((await deadline.wait(50)) === "aborted")
299
- return err(startupInterruption(deadline));
392
+ return err(await this.#startupInterruption(deadline));
300
393
  continue;
301
394
  }
302
395
  const attempt = await connectHopperSocketOnce(socketPath, deadline.signal);
@@ -306,24 +399,63 @@ export class HopperClient {
306
399
  return ok(undefined);
307
400
  }
308
401
  if ((await deadline.wait(50)) === "aborted")
309
- return err(startupInterruption(deadline));
402
+ return err(await this.#startupInterruption(deadline));
310
403
  }
311
- return err(new HopperTimeoutError(this.#options.startupTimeoutMs));
404
+ return err(await this.#startupInterruption(deadline));
405
+ }
406
+ async #startupInterruption(deadline) {
407
+ if (deadline.interruption === "cancelled")
408
+ return new HopperCancelledError();
409
+ return new HopperTimeoutError(deadline.timeoutMs, undefined, undefined, "not_started", "launch", this.#launcherOutcome((await this.#process?.waitForOutputClose(0)) ?? false));
410
+ }
411
+ #launcherOutcome(outputClosed) {
412
+ const snapshot = this.#process?.snapshot();
413
+ const token = this.#token;
414
+ if (snapshot === undefined)
415
+ return undefined;
416
+ const redact = (text) => token === undefined
417
+ ? text
418
+ : text.replaceAll(token, "[redacted transport credential]");
419
+ return {
420
+ exit_code: snapshot.exitCode ?? null,
421
+ signal: snapshot.signal ?? null,
422
+ stdout: { ...snapshot.stdout, text: redact(snapshot.stdout.text) },
423
+ stderr: { ...snapshot.stderr, text: redact(snapshot.stderr.text) },
424
+ output_closed: outputClosed,
425
+ diagnostic_truncated: snapshot.diagnosticTruncated === true,
426
+ };
427
+ }
428
+ async #launcherStartupFailure(ownsProviderLifetime, exitCode, deadline) {
429
+ const process = this.#process;
430
+ // Descendants may inherit the helper's pipes. Bound drainage independently
431
+ // from readiness, and report whether producer output actually closed.
432
+ const outputClosed = (await process?.waitForOutputClose(Math.min(1_000, deadline.remainingMs()))) ?? false;
433
+ const launcherFailure = this.#launcherOutcome(outputClosed);
434
+ if (ownsProviderLifetime)
435
+ return new HopperProcessError(exitCode, this.#launcherFailureDiagnostic, undefined, undefined, "exited", "launch", launcherFailure);
436
+ return new HopperStartError({
437
+ userMessage: "Hopper's launcher helper failed before bridge readiness. Review details.launcher and complete Hopper setup before retrying.",
438
+ ...(launcherFailure === undefined ? {} : { launcherFailure }),
439
+ });
312
440
  }
313
441
  async #request(method, params, options) {
314
442
  const id = this.#nextId++;
315
443
  const socket = this.#socket;
316
444
  const token = this.#token;
317
445
  if (socket === undefined || socket.destroyed || token === undefined) {
318
- return err(new HopperProcessError(null, undefined, method, id));
446
+ return this.#unavailableRequest(new HopperProcessError(null, undefined, method, id, "unreachable", hopperOperationStage(method)));
319
447
  }
320
448
  if (options.signal?.aborted === true)
321
449
  return err(new HopperCancelledError());
322
450
  const startedAt = performance.now();
323
451
  const result = await this.#requests.run(id, method, params, {
324
452
  ...(options.signal === undefined ? {} : { signal: options.signal }),
453
+ ...(options.timeoutMs === undefined
454
+ ? {}
455
+ : { timeoutMs: options.timeoutMs }),
325
456
  ...(options.progress !== undefined ? { progress: options.progress } : {}),
326
457
  });
458
+ this.#retainRequestHealth(result, id, method);
327
459
  this.#logger[result.ok ? "debug" : "warn"]({
328
460
  method,
329
461
  durationMs: Math.round((performance.now() - startedAt) * 100) / 100,
@@ -394,8 +526,10 @@ export class HopperClient {
394
526
  type: "launcher-exit",
395
527
  code: event.code,
396
528
  });
397
- if (launch.ownsProcessLifetime && !this.#closing)
398
- this.#failAll(new HopperProcessError(event.code, this.#launcherFailureDiagnostic));
529
+ if (launch.providerLifetime === "launcher-process" && !this.#closing) {
530
+ this.#rememberExit(event.code);
531
+ this.#failAll(new HopperProcessError(event.code, this.#launcherFailureDiagnostic, undefined, undefined, "exited"));
532
+ }
399
533
  }
400
534
  #abortProtocol(message, cause) {
401
535
  this.#failAll(new HopperProtocolError(message, { cause }));
@@ -404,7 +538,81 @@ export class HopperClient {
404
538
  #failAll(error) {
405
539
  this.#requests.failAll(error);
406
540
  }
541
+ #unavailableRequest(error) {
542
+ this.#rememberProcessFailure(error, error.requestId === undefined || error.operation === undefined
543
+ ? []
544
+ : [{ requestId: error.requestId, operation: error.operation }]);
545
+ return err(error);
546
+ }
547
+ #retainRequestHealth(result, requestId, operation) {
548
+ if (this.#closing)
549
+ return;
550
+ if (result.ok)
551
+ return;
552
+ if (!(result.error instanceof HopperProcessError))
553
+ return;
554
+ this.#rememberProcessFailure(result.error, [
555
+ {
556
+ requestId: result.error.requestId ?? requestId,
557
+ operation: result.error.operation ?? operation,
558
+ },
559
+ ]);
560
+ }
561
+ #rememberExit(code) {
562
+ if (this.#closing)
563
+ return;
564
+ const previous = this.#operationFailure;
565
+ this.#operationFailure = {
566
+ state: "exited",
567
+ exitCode: code ?? previous?.exitCode ?? null,
568
+ startupFailure: hopperStartupFailure(code) !== undefined ||
569
+ previous?.startupFailure === true,
570
+ requests: previous?.requests ?? [],
571
+ };
572
+ }
573
+ #rememberProcessFailure(error, requests) {
574
+ if (this.#closing)
575
+ return;
576
+ const previous = this.#operationFailure;
577
+ const state = processFailureState(error);
578
+ const startupFailure = error.stage === "launch" ||
579
+ error.failureCode !== undefined ||
580
+ previous?.startupFailure === true;
581
+ const merged = mergeFailedRequests(previous?.requests ?? [], requests);
582
+ if (previous !== undefined &&
583
+ PROCESS_FAILURE_RANK[previous.state] > PROCESS_FAILURE_RANK[state]) {
584
+ this.#operationFailure = {
585
+ ...previous,
586
+ startupFailure,
587
+ requests: merged,
588
+ };
589
+ return;
590
+ }
591
+ this.#operationFailure = {
592
+ state,
593
+ exitCode: state === "exited"
594
+ ? (error.exitCode ?? previous?.exitCode ?? null)
595
+ : null,
596
+ startupFailure,
597
+ requests: merged,
598
+ };
599
+ }
407
600
  }
601
+ const PROCESS_FAILURE_RANK = {
602
+ not_started: 0,
603
+ unknown: 0,
604
+ unreachable: 1,
605
+ exited: 2,
606
+ };
607
+ const processFailureState = (error) => error.providerState === "exited" || error.exitCode !== null
608
+ ? "exited"
609
+ : error.providerState;
610
+ const mergeFailedRequests = (current, added) => {
611
+ const byId = new Map();
612
+ for (const request of [...current, ...added])
613
+ byId.set(request.requestId, request);
614
+ return [...byId.values()].sort((left, right) => left.requestId - right.requestId);
615
+ };
408
616
  const isAborted = (signal) => signal?.aborted === true;
409
617
  const startupInterruption = (deadline) => deadline.interruption === "cancelled"
410
618
  ? new HopperCancelledError()
@@ -0,0 +1,237 @@
1
+ import { createHash } from "node:crypto";
2
+ import { constants } from "node:fs";
3
+ import { open } from "node:fs/promises";
4
+ import { z } from "zod";
5
+ import { AnalysisAccessDeniedError, AnalysisArtifactChangedError, AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
6
+ import { BinaryTargetError } from "../domain/configurationErrors.js";
7
+ import { readFatSliceDeclarations, validateFatSlice, } from "../domain/apple/machoContainer.js";
8
+ import { err, ok } from "../domain/result.js";
9
+ const OPERATION = "address_to_file_offset";
10
+ const MAX_FAT_ARCHITECTURES = 128;
11
+ const PREFIX_BYTES = 8 + MAX_FAT_ARCHITECTURES * 32;
12
+ const observationSchema = z.strictObject({
13
+ address: z.string().regex(/^0x[0-9a-f]+$/u),
14
+ provider_file_offset: z
15
+ .number()
16
+ .int()
17
+ .nonnegative()
18
+ .max(Number.MAX_SAFE_INTEGER),
19
+ provider_source_path: z.string().nullable(),
20
+ provider_image_header_hex: z
21
+ .string()
22
+ .regex(/^[a-f0-9]{24}$/u)
23
+ .nullable(),
24
+ });
25
+ /** Bind native image-relative offsets to coordinates in the admitted source bytes. */
26
+ export async function mapHopperFileOffset(target, value, signal) {
27
+ const parsed = observationSchema.safeParse(value);
28
+ if (!parsed.success)
29
+ return err(new AnalysisOutputError(OPERATION, "Hopper's native file mapping observation is malformed"));
30
+ const observation = parsed.data;
31
+ const partial = (reason) => ({
32
+ operation: OPERATION,
33
+ ...observation,
34
+ original_file_offset: { available: false, reason },
35
+ });
36
+ const unavailable = (reason) => err(new AnalysisCapabilityUnavailableError("hopper", OPERATION, reason, {
37
+ partialObservation: partial(reason),
38
+ }));
39
+ if (target.kind !== "executable")
40
+ return unavailable("The selected database digest does not identify its original executable bytes. Open that executable to verify original-file coordinates; read_bytes still exposes the database's native bytes.");
41
+ if (signal?.aborted)
42
+ return err(new AnalysisCancelledError(OPERATION, {
43
+ partialObservation: partial("Source verification was cancelled"),
44
+ }));
45
+ try {
46
+ const captured = await snapshotFromPath(target.path, signal);
47
+ if (!captured.ok)
48
+ return err(new AnalysisArtifactChangedError(OPERATION, target.path, captured.error, {
49
+ partialObservation: partial(captured.error),
50
+ }));
51
+ const snapshot = captured.value;
52
+ if (signal?.aborted)
53
+ return err(new AnalysisCancelledError(OPERATION, {
54
+ partialObservation: partial("Source verification was cancelled"),
55
+ }));
56
+ if (snapshot.sha256 !== target.sha256) {
57
+ const reason = `Source ${target.path} differs from the admitted artifact: expected SHA-256 ${target.sha256}, observed ${snapshot.sha256}. Reopen the changed source for a new analysis identity.`;
58
+ return err(new AnalysisArtifactChangedError(OPERATION, target.path, reason, {
59
+ partialObservation: partial(reason),
60
+ }));
61
+ }
62
+ const mapped = originalOffset(snapshot, observation);
63
+ if (!mapped.ok)
64
+ return unavailable(mapped.error);
65
+ return ok({
66
+ address: observation.address,
67
+ file_offset: mapped.value + observation.provider_file_offset,
68
+ provider_file_offset: observation.provider_file_offset,
69
+ image_base_file_offset: mapped.value,
70
+ source_path: target.path,
71
+ });
72
+ }
73
+ catch (cause) {
74
+ if (signal?.aborted)
75
+ return err(new AnalysisCancelledError(OPERATION, {
76
+ cause,
77
+ partialObservation: partial("Source verification was cancelled"),
78
+ }));
79
+ const reason = `Cannot verify original source bytes: ${cause instanceof Error ? cause.message : String(cause)}`;
80
+ const code = typeof cause === "object" && cause !== null && "code" in cause
81
+ ? cause.code
82
+ : undefined;
83
+ if (code === "EACCES" || code === "EPERM")
84
+ return err(new AnalysisAccessDeniedError(OPERATION, target.path, code, {
85
+ cause,
86
+ partialObservation: partial(reason),
87
+ }));
88
+ return err(new BinaryTargetError(target.path, reason, {
89
+ cause,
90
+ partialObservation: partial(reason),
91
+ }));
92
+ }
93
+ }
94
+ async function snapshotFromPath(path, signal) {
95
+ const file = await open(path, constants.O_RDONLY | constants.O_NONBLOCK);
96
+ try {
97
+ if (!(await file.stat()).isFile())
98
+ return err(`Source ${path} is no longer a regular file. Restore the admitted executable or reopen a regular source.`);
99
+ return ok(await readSourceSnapshot(file, signal));
100
+ }
101
+ finally {
102
+ await file.close();
103
+ }
104
+ }
105
+ function fatLayout(prefix) {
106
+ const magic = prefix.length < 4 ? 0 : prefix.readUInt32BE(0);
107
+ if (![0xcafebabe, 0xbebafeca, 0xcafebabf, 0xbfbafeca].includes(magic))
108
+ return ok(null);
109
+ if (prefix.length < 8)
110
+ return err("The original FAT header is truncated");
111
+ const littleEndian = magic === 0xbebafeca || magic === 0xbfbafeca;
112
+ const wide = magic === 0xcafebabf || magic === 0xbfbafeca;
113
+ const count = littleEndian ? prefix.readUInt32LE(4) : prefix.readUInt32BE(4);
114
+ if (count === 0 || count > MAX_FAT_ARCHITECTURES)
115
+ return err("FAT architecture count is outside the supported 1..128 range");
116
+ const tableEnd = 8 + count * (wide ? 32 : 20);
117
+ const table = prefix.subarray(8, tableEnd);
118
+ const parsed = readFatSliceDeclarations(table, { count, wide, littleEndian });
119
+ if (parsed.status !== "parsed")
120
+ return err(parsed.reason);
121
+ if (wide) {
122
+ for (const slice of parsed.slices)
123
+ if ((littleEndian
124
+ ? table.readUInt32LE(slice.index * 32 + 28)
125
+ : table.readUInt32BE(slice.index * 32 + 28)) !== 0)
126
+ return err(`FAT64 architecture ${slice.index} has a nonzero reserved field`);
127
+ }
128
+ return ok({ slices: parsed.slices, tableEnd });
129
+ }
130
+ async function readSourceSnapshot(file, signal) {
131
+ const prefix = Buffer.alloc(PREFIX_BYTES);
132
+ const hash = createHash("sha256");
133
+ let size = 0;
134
+ let layout;
135
+ const headers = new Map();
136
+ const capture = (bytes, position) => {
137
+ if (layout?.ok !== true || layout.value === null)
138
+ return;
139
+ for (const slice of layout.value.slices) {
140
+ const start = Math.max(position, slice.offset);
141
+ const end = Math.min(position + bytes.length, slice.offset + 12);
142
+ if (end <= start)
143
+ continue;
144
+ let header = headers.get(slice.index);
145
+ if (header === undefined) {
146
+ header = Buffer.alloc(12);
147
+ headers.set(slice.index, header);
148
+ }
149
+ bytes.copy(header, start - slice.offset, start - position, end - position);
150
+ }
151
+ };
152
+ for await (const chunk of file.createReadStream({
153
+ start: 0,
154
+ autoClose: false,
155
+ ...(signal === undefined ? {} : { signal }),
156
+ })) {
157
+ const bytes = Buffer.from(chunk);
158
+ hash.update(bytes);
159
+ if (size < prefix.length)
160
+ bytes.copy(prefix, size, 0, Math.min(bytes.length, prefix.length - size));
161
+ if (layout === undefined && size + bytes.length >= prefix.length) {
162
+ layout = fatLayout(prefix);
163
+ capture(prefix, 0);
164
+ }
165
+ capture(bytes, size);
166
+ size += bytes.length;
167
+ }
168
+ if (layout === undefined) {
169
+ layout = fatLayout(prefix.subarray(0, size));
170
+ capture(prefix.subarray(0, size), 0);
171
+ }
172
+ return { layout, headers, size, sha256: hash.digest("hex") };
173
+ }
174
+ function originalOffset(snapshot, observation) {
175
+ const { layout, size, headers } = snapshot;
176
+ if (!layout.ok)
177
+ return layout;
178
+ if (layout.value === null)
179
+ return observation.provider_file_offset < size
180
+ ? ok(0)
181
+ : err("Provider mapping lies outside the admitted executable bytes");
182
+ const header = observation.provider_image_header_hex === null
183
+ ? null
184
+ : Buffer.from(observation.provider_image_header_hex, "hex");
185
+ const loadedMagic = header?.readUInt32BE(0);
186
+ if (header === null ||
187
+ loadedMagic === undefined ||
188
+ ![0xfeedface, 0xfeedfacf, 0xcefaedfe, 0xcffaedfe].includes(loadedMagic))
189
+ return err("Hopper did not expose the loaded Mach-O header needed to identify its FAT slice");
190
+ const little = loadedMagic === 0xcefaedfe || loadedMagic === 0xcffaedfe;
191
+ const cpu = little ? header.readUInt32LE(4) : header.readUInt32BE(4);
192
+ const subtype = little ? header.readUInt32LE(8) : header.readUInt32BE(8);
193
+ const matches = [];
194
+ const ranges = [...layout.value.slices].sort((a, b) => a.offset - b.offset);
195
+ for (let index = 1; index < ranges.length; index++) {
196
+ const previous = ranges[index - 1];
197
+ const current = ranges[index];
198
+ if (previous !== undefined &&
199
+ current !== undefined &&
200
+ current.offset < previous.offset + previous.size)
201
+ return err("Original FAT slices overlap");
202
+ }
203
+ for (const slice of layout.value.slices) {
204
+ const reason = validateFatSlice(slice, size, layout.value.tableEnd);
205
+ if (reason !== null)
206
+ return err(reason);
207
+ const embedded = headers.get(slice.index);
208
+ if (slice.size < 12 || embedded === undefined)
209
+ return err(`FAT architecture ${slice.index} has a truncated Mach-O header`);
210
+ const embeddedMagic = embedded.readUInt32BE(0);
211
+ if (![0xfeedface, 0xfeedfacf, 0xcefaedfe, 0xcffaedfe].includes(embeddedMagic))
212
+ return err(`FAT architecture ${slice.index} does not contain a Mach-O image`);
213
+ const embeddedLittle = embeddedMagic === 0xcefaedfe || embeddedMagic === 0xcffaedfe;
214
+ const identityError = validateFatSlice(slice, size, layout.value.tableEnd, {
215
+ cpuType: embeddedLittle
216
+ ? embedded.readUInt32LE(4)
217
+ : embedded.readUInt32BE(4),
218
+ cpuSubtype: embeddedLittle
219
+ ? embedded.readUInt32LE(8)
220
+ : embedded.readUInt32BE(8),
221
+ });
222
+ if (identityError !== null)
223
+ return err(identityError);
224
+ if (slice.cpuType === cpu && slice.cpuSubtype === subtype)
225
+ matches.push(slice);
226
+ }
227
+ const selected = matches.length === 1 ? matches[0] : undefined;
228
+ if (selected === undefined)
229
+ return err(`Original FAT slice matching Hopper's loaded header is ${matches.length === 0 ? "missing" : "ambiguous"}`);
230
+ if (headers.get(selected.index)?.equals(header) !== true)
231
+ return err("Original FAT slice header disagrees with Hopper's loaded header");
232
+ if (observation.provider_file_offset >= selected.size)
233
+ return err("Provider mapping lies outside the loaded FAT slice");
234
+ if (!Number.isSafeInteger(selected.offset + observation.provider_file_offset))
235
+ return err("Original file offset exceeds the exact JSON integer range");
236
+ return ok(selected.offset);
237
+ }