hexcore-capstone 1.2.0

package/LICENSE

@@ -0,0 +1,26 @@
+MIT License
+
+Copyright (c) 2026 HikariSystem
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+This package uses Capstone Engine, which is licensed under the BSD license.
+See https://github.com/capstone-engine/capstone/blob/master/LICENSE.TXT

package/README.md

@@ -0,0 +1,191 @@
+# HexCore Capstone
+
+Modern Node.js bindings for [Capstone](https://capstone-engine.org) disassembler engine using N-API.
+
+[![npm version](https://badge.fury.io/js/hexcore-capstone.svg)](https://www.npmjs.com/package/hexcore-capstone)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+-  **Async API**: Non-blocking `disasmAsync()` for large binaries
+-  **Modern N-API**: Binary compatible across Node.js 18+
+-  **Zero Dependencies**: Capstone is bundled - just `npm install`
+-  **Full TypeScript**: Complete type definitions with JSDoc
+-  **Multi-Architecture**: x86, ARM, ARM64, MIPS, PPC, SPARC, M68K, and more
+-  **Detail Mode**: Access operands, registers, groups, and flags
+-  **ESM + CommonJS**: Works with `import` and `require`
+
+## Installation
+
+```bash
+npm install hexcore-capstone
+```
+
+No system dependencies required! Capstone is compiled from source automatically.
+
+## Quick Start
+
+### Basic Example
+
+```javascript
+const { Capstone, ARCH, MODE } = require('hexcore-capstone');
+
+// Create a disassembler for x86-64
+const cs = new Capstone(ARCH.X86, MODE.MODE_64);
+
+// Machine code to disassemble
+const code = Buffer.from([
+    0x55,                         // push rbp
+    0x48, 0x89, 0xe5,             // mov rbp, rsp
+    0x48, 0x83, 0xec, 0x20,       // sub rsp, 0x20
+    0xc3                          // ret
+]);
+
+// Disassemble
+const instructions = cs.disasm(code, 0x401000);
+
+for (const insn of instructions) {
+    console.log(`0x${insn.address.toString(16)}: ${insn.mnemonic} ${insn.opStr}`);
+}
+
+// Output:
+// 0x401000: push rbp
+// 0x401001: mov rbp, rsp
+// 0x401004: sub rsp, 0x20
+// 0x401008: ret
+
+cs.close();
+```
+
+### Async Disassembly (Recommended for large files)
+
+```javascript
+const { Capstone, ARCH, MODE } = require('hexcore-capstone');
+const fs = require('fs');
+
+const cs = new Capstone(ARCH.X86, MODE.MODE_64);
+
+// Load a large binary
+const largeCode = fs.readFileSync('large_binary.bin');
+
+// Disassemble without blocking the event loop
+const instructions = await cs.disasmAsync(largeCode, 0x401000);
+
+console.log(`Disassembled ${instructions.length} instructions`);
+
+cs.close();
+```
+
+### ESM Import
+
+```javascript
+import { Capstone, ARCH, MODE, OPT, OPT_VALUE } from 'hexcore-capstone';
+
+const cs = new Capstone(ARCH.ARM64, MODE.ARM);
+// ...
+```
+
+### Detail Mode
+
+```javascript
+const { Capstone, ARCH, MODE, OPT, OPT_VALUE } = require('hexcore-capstone');
+
+const cs = new Capstone(ARCH.X86, MODE.MODE_64);
+
+// Enable detail mode for operand info
+cs.setOption(OPT.DETAIL, OPT_VALUE.ON);
+
+const code = Buffer.from([0x48, 0x89, 0xc3]); // mov rbx, rax
+const insns = cs.disasm(code, 0x1000);
+
+for (const insn of insns) {
+    console.log(`${insn.mnemonic} ${insn.opStr}`);
+
+    if (insn.detail) {
+        console.log('  Registers read:', insn.detail.regsRead.map(r => cs.regName(r)));
+        console.log('  Registers written:', insn.detail.regsWrite.map(r => cs.regName(r)));
+        console.log('  Groups:', insn.detail.groups.map(g => cs.groupName(g)));
+    }
+}
+
+cs.close();
+```
+
+## Supported Architectures
+
+| Architecture | Constant | Detail Mode |
+|--------------|----------|-------------|
+| x86/x64 | `ARCH.X86` | ✅ Full |
+| ARM | `ARCH.ARM` | ✅ Full |
+| ARM64 | `ARCH.ARM64` | ✅ Full |
+| MIPS | `ARCH.MIPS` | ✅ Full |
+| PowerPC | `ARCH.PPC` | ✅ Full |
+| SPARC | `ARCH.SPARC` | ✅ Full |
+| SystemZ | `ARCH.SYSZ` | ✅ Full |
+| XCore | `ARCH.XCORE` | ✅ Full |
+| M68K | `ARCH.M68K` | ✅ Full |
+
+## API Reference
+
+### Class: Capstone
+
+#### `new Capstone(arch, mode)`
+Create a new disassembler instance.
+
+#### `cs.disasm(code, address, [count])`
+Disassemble code buffer synchronously. Returns `Instruction[]`.
+
+#### `cs.disasmAsync(code, address, [count])`
+Disassemble code buffer asynchronously. Returns `Promise<Instruction[]>`.
+
+> ⚡ **Use `disasmAsync()` for buffers >1MB** to avoid blocking the event loop.
+
+#### `cs.setOption(type, value)`
+Set a disassembler option (e.g., enable detail mode).
+
+#### `cs.close()`
+Close the handle and free resources.
+
+#### `cs.regName(regId)`, `cs.insnName(insnId)`, `cs.groupName(groupId)`
+Get human-readable names.
+
+### Helper Functions
+
+```javascript
+const { version, support, ARCH } = require('hexcore-capstone');
+
+console.log(`Capstone version: ${version().string}`);  // "5.0"
+console.log(`ARM supported: ${support(ARCH.ARM)}`);    // true
+```
+
+## Building from Source
+
+```bash
+git clone --recursive https://github.com/LXrdKnowkill/hexcore-capstone.git
+cd hexcore-capstone
+npm install
+npm run build
+npm test
+```
+
+> **Note:** Use `--recursive` to clone the vendored Capstone submodule.
+
+## Changelog
+
+### v1.1.0
+-  Add `disasmAsync()` for non-blocking disassembly
+-  Add ESM support via `index.mjs`
+-  Add detail mode for PPC, SPARC, SYSZ, XCORE, M68K
+-  Enhanced TypeScript definitions with JSDoc
+
+### v1.0.0
+-  Initial release with sync API
+
+## License
+
+MIT License - Copyright (c) HikariSystem
+
+## Acknowledgments
+
+- [Capstone Engine](https://capstone-engine.org) by Nguyen Anh Quynh
+- The Node.js N-API team

package/binding.gyp

@@ -0,0 +1,168 @@
+{
+  "targets": [
+    {
+      "target_name": "capstone_native",
+      "sources": [
+        "src/main.cpp",
+        "src/capstone_wrapper.cpp",
+
+        "deps/capstone/cs.c",
+        "deps/capstone/MCInst.c",
+        "deps/capstone/MCInstrDesc.c",
+        "deps/capstone/MCRegisterInfo.c",
+        "deps/capstone/Mapping.c",
+        "deps/capstone/SStream.c",
+        "deps/capstone/utils.c",
+
+        "deps/capstone/arch/X86/X86Module.c",
+        "deps/capstone/arch/X86/X86Disassembler.c",
+        "deps/capstone/arch/X86/X86DisassemblerDecoder.c",
+        "deps/capstone/arch/X86/X86ATTInstPrinter.c",
+        "deps/capstone/arch/X86/X86IntelInstPrinter.c",
+        "deps/capstone/arch/X86/X86InstPrinterCommon.c",
+        "deps/capstone/arch/X86/X86Mapping.c",
+
+        "deps/capstone/arch/ARM/ARMModule.c",
+        "deps/capstone/arch/ARM/ARMDisassembler.c",
+        "deps/capstone/arch/ARM/ARMInstPrinter.c",
+        "deps/capstone/arch/ARM/ARMMapping.c",
+
+        "deps/capstone/arch/AArch64/AArch64Module.c",
+        "deps/capstone/arch/AArch64/AArch64Disassembler.c",
+        "deps/capstone/arch/AArch64/AArch64InstPrinter.c",
+        "deps/capstone/arch/AArch64/AArch64Mapping.c",
+        "deps/capstone/arch/AArch64/AArch64BaseInfo.c",
+
+        "deps/capstone/arch/Mips/MipsModule.c",
+        "deps/capstone/arch/Mips/MipsDisassembler.c",
+        "deps/capstone/arch/Mips/MipsInstPrinter.c",
+        "deps/capstone/arch/Mips/MipsMapping.c",
+
+        "deps/capstone/arch/PowerPC/PPCModule.c",
+        "deps/capstone/arch/PowerPC/PPCDisassembler.c",
+        "deps/capstone/arch/PowerPC/PPCInstPrinter.c",
+        "deps/capstone/arch/PowerPC/PPCMapping.c",
+
+        "deps/capstone/arch/Sparc/SparcModule.c",
+        "deps/capstone/arch/Sparc/SparcDisassembler.c",
+        "deps/capstone/arch/Sparc/SparcInstPrinter.c",
+        "deps/capstone/arch/Sparc/SparcMapping.c",
+
+        "deps/capstone/arch/SystemZ/SystemZModule.c",
+        "deps/capstone/arch/SystemZ/SystemZDisassembler.c",
+        "deps/capstone/arch/SystemZ/SystemZInstPrinter.c",
+        "deps/capstone/arch/SystemZ/SystemZMapping.c",
+        "deps/capstone/arch/SystemZ/SystemZMCTargetDesc.c",
+
+        "deps/capstone/arch/XCore/XCoreModule.c",
+        "deps/capstone/arch/XCore/XCoreDisassembler.c",
+        "deps/capstone/arch/XCore/XCoreInstPrinter.c",
+        "deps/capstone/arch/XCore/XCoreMapping.c",
+
+        "deps/capstone/arch/M68K/M68KModule.c",
+        "deps/capstone/arch/M68K/M68KDisassembler.c",
+        "deps/capstone/arch/M68K/M68KInstPrinter.c",
+
+        "deps/capstone/arch/TMS320C64x/TMS320C64xModule.c",
+        "deps/capstone/arch/TMS320C64x/TMS320C64xDisassembler.c",
+        "deps/capstone/arch/TMS320C64x/TMS320C64xInstPrinter.c",
+        "deps/capstone/arch/TMS320C64x/TMS320C64xMapping.c",
+
+        "deps/capstone/arch/M680X/M680XModule.c",
+        "deps/capstone/arch/M680X/M680XDisassembler.c",
+        "deps/capstone/arch/M680X/M680XInstPrinter.c",
+
+        "deps/capstone/arch/EVM/EVMModule.c",
+        "deps/capstone/arch/EVM/EVMDisassembler.c",
+        "deps/capstone/arch/EVM/EVMInstPrinter.c",
+        "deps/capstone/arch/EVM/EVMMapping.c",
+
+        "deps/capstone/arch/WASM/WASMModule.c",
+        "deps/capstone/arch/WASM/WASMDisassembler.c",
+        "deps/capstone/arch/WASM/WASMInstPrinter.c",
+        "deps/capstone/arch/WASM/WASMMapping.c",
+
+        "deps/capstone/arch/MOS65XX/MOS65XXModule.c",
+        "deps/capstone/arch/MOS65XX/MOS65XXDisassembler.c",
+
+        "deps/capstone/arch/BPF/BPFModule.c",
+        "deps/capstone/arch/BPF/BPFDisassembler.c",
+        "deps/capstone/arch/BPF/BPFInstPrinter.c",
+        "deps/capstone/arch/BPF/BPFMapping.c",
+
+        "deps/capstone/arch/RISCV/RISCVModule.c",
+        "deps/capstone/arch/RISCV/RISCVDisassembler.c",
+        "deps/capstone/arch/RISCV/RISCVInstPrinter.c",
+        "deps/capstone/arch/RISCV/RISCVMapping.c",
+
+        "deps/capstone/arch/SH/SHModule.c",
+        "deps/capstone/arch/SH/SHDisassembler.c",
+        "deps/capstone/arch/SH/SHInstPrinter.c",
+
+        "deps/capstone/arch/TriCore/TriCoreModule.c",
+        "deps/capstone/arch/TriCore/TriCoreDisassembler.c",
+        "deps/capstone/arch/TriCore/TriCoreInstPrinter.c",
+        "deps/capstone/arch/TriCore/TriCoreMapping.c"
+      ],
+      "include_dirs": [
+        "<!@(node -p \"require('node-addon-api').include\")",
+        "deps/capstone/include",
+        "deps/capstone"
+      ],
+      "defines": [
+        "NAPI_VERSION=8",
+        "NAPI_DISABLE_CPP_EXCEPTIONS",
+        "CAPSTONE_HAS_X86",
+        "CAPSTONE_HAS_ARM",
+        "CAPSTONE_HAS_ARM64",
+        "CAPSTONE_HAS_MIPS",
+        "CAPSTONE_HAS_POWERPC",
+        "CAPSTONE_HAS_SPARC",
+        "CAPSTONE_HAS_SYSZ",
+        "CAPSTONE_HAS_XCORE",
+        "CAPSTONE_HAS_M68K",
+        "CAPSTONE_HAS_TMS320C64X",
+        "CAPSTONE_HAS_M680X",
+        "CAPSTONE_HAS_EVM",
+        "CAPSTONE_HAS_WASM",
+        "CAPSTONE_HAS_MOS65XX",
+        "CAPSTONE_HAS_BPF",
+        "CAPSTONE_HAS_RISCV",
+        "CAPSTONE_HAS_SH",
+        "CAPSTONE_HAS_TRICORE",
+        "CAPSTONE_USE_SYS_DYN_MEM"
+      ],
+      "conditions": [
+        ["OS=='win'", {
+          "msvs_settings": {
+            "VCCLCompilerTool": {
+              "ExceptionHandling": 1,
+              "AdditionalIncludeDirectories": [
+                "<(module_root_dir)/deps/capstone/include",
+                "<(module_root_dir)/deps/capstone"
+              ],
+              "DisableSpecificWarnings": ["4244", "4267", "4996"]
+            }
+          },
+          "defines": [
+            "WIN32",
+            "_WINDOWS"
+          ]
+        }],
+        ["OS=='linux'", {
+          "cflags": ["-fPIC", "-w"],
+          "cflags_cc": ["-fPIC", "-std=c++17", "-w"]
+        }],
+        ["OS=='mac'", {
+          "xcode_settings": {
+            "GCC_ENABLE_CPP_EXCEPTIONS": "YES",
+            "CLANG_CXX_LIBRARY": "libc++",
+            "MACOSX_DEPLOYMENT_TARGET": "10.15",
+            "WARNING_CFLAGS": ["-w"],
+            "OTHER_CFLAGS": ["-w"]
+          }
+        }]
+      ]
+    }
+  ]
+}

package/deps/capstone/LEB128.h

@@ -0,0 +1,38 @@
+//===- llvm/Support/LEB128.h - [SU]LEB128 utility functions -----*- C++ -*-===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+//
+// This file declares some utility functions for encoding SLEB128 and
+// ULEB128 values.
+//
+//===----------------------------------------------------------------------===//
+
+/* Capstone Disassembly Engine */
+/* By Nguyen Anh Quynh <aquynh@gmail.com>, 2013-2019 */
+
+#ifndef CS_LLVM_SUPPORT_LEB128_H
+#define CS_LLVM_SUPPORT_LEB128_H
+
+#include "include/capstone/capstone.h"
+
+/// Utility function to decode a ULEB128 value.
+static inline uint64_t decodeULEB128(const uint8_t *p, unsigned *n)
+{
+	const uint8_t *orig_p = p;
+	uint64_t Value = 0;
+	unsigned Shift = 0;
+	do {
+		Value += (uint64_t)(*p & 0x7f) << Shift;
+		Shift += 7;
+	} while (*p++ >= 128);
+	if (n)
+		*n = (unsigned)(p - orig_p);
+	return Value;
+}
+
+#endif  // LLVM_SYSTEM_LEB128_H

package/deps/capstone/MCDisassembler.h

@@ -0,0 +1,14 @@
+/* Capstone Disassembly Engine */
+/* By Nguyen Anh Quynh <aquynh@gmail.com>, 2013-2019 */
+
+#ifndef CS_MCDISASSEMBLER_H
+#define CS_MCDISASSEMBLER_H
+
+typedef enum DecodeStatus {
+	MCDisassembler_Fail = 0,
+	MCDisassembler_SoftFail = 1,
+	MCDisassembler_Success = 3,
+} DecodeStatus;
+
+#endif
+

package/deps/capstone/MCFixedLenDisassembler.h

@@ -0,0 +1,32 @@
+//===-- llvm/MC/MCFixedLenDisassembler.h - Decoder driver -------*- C++ -*-===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+// Fixed length disassembler decoder state machine driver.
+//===----------------------------------------------------------------------===//
+
+/* Capstone Disassembly Engine */
+/* By Nguyen Anh Quynh <aquynh@gmail.com>, 2013-2019 */
+
+#ifndef CS_LLVM_MC_MCFIXEDLENDISASSEMBLER_H
+#define CS_LLVM_MC_MCFIXEDLENDISASSEMBLER_H
+
+// Disassembler state machine opcodes.
+enum DecoderOps {
+	MCD_OPC_ExtractField = 1, // OPC_ExtractField(uint8_t Start, uint8_t Len)
+	MCD_OPC_FilterValue,      // OPC_FilterValue(uleb128 Val, uint16_t NumToSkip)
+	MCD_OPC_CheckField,       // OPC_CheckField(uint8_t Start, uint8_t Len,
+							  //                uleb128 Val, uint16_t NumToSkip)
+	MCD_OPC_CheckPredicate,   // OPC_CheckPredicate(uleb128 PIdx, uint16_t NumToSkip)
+	MCD_OPC_Decode,           // OPC_Decode(uleb128 Opcode, uleb128 DIdx)
+        MCD_OPC_TryDecode,        // OPC_TryDecode(uleb128 Opcode, uleb128 DIdx,
+                                  //               uint16_t NumToSkip)	
+	MCD_OPC_SoftFail,         // OPC_SoftFail(uleb128 PMask, uleb128 NMask)
+	MCD_OPC_Fail              // OPC_Fail()
+};
+
+#endif