hexcore-capstone 1.2.0

package/src/capstone_wrapper.h

@@ -0,0 +1,147 @@
+/*
+ * HexCore Capstone - Native Node.js Bindings
+ * Capstone Wrapper Header
+ * Copyright (c) HikariSystem. All rights reserved.
+ * Licensed under MIT License.
+ */
+
+#ifndef CAPSTONE_WRAPPER_H
+#define CAPSTONE_WRAPPER_H
+
+#include <napi.h>
+#include <capstone/capstone.h>
+#include <vector>
+#include <string>
+
+// Forward declaration
+class DisasmAsyncWorker;
+
+/**
+ * CapstoneWrapper - N-API class wrapping Capstone disassembler
+ *
+ * JavaScript usage:
+ *   const cs = new Capstone(ARCH.X86, MODE.MODE_64);
+ *   const instructions = cs.disasm(buffer, 0x1000);
+ *   const instructionsAsync = await cs.disasmAsync(buffer, 0x1000);
+ *   cs.close();
+ */
+class CapstoneWrapper : public Napi::ObjectWrap<CapstoneWrapper> {
+public:
+    /**
+     * Initialize the class in the module exports
+     */
+    static Napi::Object Init(Napi::Env env, Napi::Object exports);
+
+    /**
+     * Constructor called from JavaScript
+     * @param info Contains arch and mode arguments
+     */
+    CapstoneWrapper(const Napi::CallbackInfo& info);
+
+    /**
+     * Destructor - ensures handle is closed
+     */
+    ~CapstoneWrapper();
+
+    // Accessors for async worker
+    csh GetHandle() const { return handle_; }
+    cs_arch GetArch() const { return arch_; }
+    bool IsOpened() const { return opened_; }
+
+private:
+    // Capstone handle
+    csh handle_;
+    bool opened_;
+    cs_arch arch_;
+    cs_mode mode_;
+    bool detailEnabled_;
+
+    // Class reference for preventing garbage collection during async ops
+    static Napi::FunctionReference constructor;
+
+    /**
+     * Disassemble a buffer (synchronous)
+     * @param info[0] Buffer - code to disassemble
+     * @param info[1] Number - base address
+     * @param info[2] Number - (optional) max instructions, 0 = all
+     * @returns Array of instruction objects
+     */
+    Napi::Value Disasm(const Napi::CallbackInfo& info);
+
+    /**
+     * Disassemble a buffer (asynchronous - non-blocking)
+     * @param info[0] Buffer - code to disassemble
+     * @param info[1] Number - base address
+     * @param info[2] Number - (optional) max instructions, 0 = all
+     * @returns Promise<Array> of instruction objects
+     */
+    Napi::Value DisasmAsync(const Napi::CallbackInfo& info);
+
+    /**
+     * Set option
+     * @param info[0] Number - option type (CS_OPT_*)
+     * @param info[1] Number - option value
+     */
+    Napi::Value SetOption(const Napi::CallbackInfo& info);
+
+    /**
+     * Close the handle and free resources
+     */
+    Napi::Value Close(const Napi::CallbackInfo& info);
+
+    /**
+     * Get register name by ID
+     * @param info[0] Number - register ID
+     * @returns String - register name
+     */
+    Napi::Value RegName(const Napi::CallbackInfo& info);
+
+    /**
+     * Get instruction name by ID
+     * @param info[0] Number - instruction ID
+     * @returns String - instruction name
+     */
+    Napi::Value InsnName(const Napi::CallbackInfo& info);
+
+    /**
+     * Get group name by ID
+     * @param info[0] Number - group ID
+     * @returns String - group name
+     */
+    Napi::Value GroupName(const Napi::CallbackInfo& info);
+
+    /**
+     * Check if handle is opened
+     * @returns Boolean
+     */
+    Napi::Value IsOpen(const Napi::CallbackInfo& info);
+
+    /**
+     * Get last error code
+     * @returns Number - error code
+     */
+    Napi::Value GetError(const Napi::CallbackInfo& info);
+
+    /**
+     * Get error message string
+     * @param info[0] Number - (optional) error code, defaults to last error
+     * @returns String - error message
+     */
+    Napi::Value StrError(const Napi::CallbackInfo& info);
+
+    // Helper methods
+    Napi::Object InstructionToObject(Napi::Env env, cs_insn* insn);
+    Napi::Object DetailToObject(Napi::Env env, cs_insn* insn);
+    Napi::Object X86DetailToObject(Napi::Env env, cs_x86* x86);
+    Napi::Object ArmDetailToObject(Napi::Env env, cs_arm* arm);
+    Napi::Object Arm64DetailToObject(Napi::Env env, cs_arm64* arm64);
+    Napi::Object MipsDetailToObject(Napi::Env env, cs_mips* mips);
+    Napi::Object PpcDetailToObject(Napi::Env env, cs_ppc* ppc);
+    Napi::Object SparcDetailToObject(Napi::Env env, cs_sparc* sparc);
+    Napi::Object SyszDetailToObject(Napi::Env env, cs_sysz* sysz);
+    Napi::Object XcoreDetailToObject(Napi::Env env, cs_xcore* xcore);
+    Napi::Object M68kDetailToObject(Napi::Env env, cs_m68k* m68k);
+};
+
+#endif // CAPSTONE_WRAPPER_H
+

package/src/disasm_async_worker.h

@@ -0,0 +1,215 @@
+/*
+ * HexCore Capstone - Native Node.js Bindings
+ * Async Disassembly Worker
+ * Copyright (c) HikariSystem. All rights reserved.
+ * Licensed under MIT License.
+ */
+
+#ifndef DISASM_ASYNC_WORKER_H
+#define DISASM_ASYNC_WORKER_H
+
+#include <napi.h>
+#include <capstone/capstone.h>
+#include <vector>
+#include <cstring>
+
+/**
+ * Intermediate structure to hold disassembled instruction data
+ * This is used to transfer data from worker thread to main thread
+ */
+struct DisasmResult {
+    uint32_t id;
+    uint64_t address;
+    uint16_t size;
+    std::vector<uint8_t> bytes;
+    std::string mnemonic;
+    std::string op_str;
+
+    // Detail data (optional)
+    bool hasDetail;
+    std::vector<uint16_t> regsRead;
+    std::vector<uint16_t> regsWrite;
+    std::vector<uint8_t> groups;
+};
+
+/**
+ * AsyncWorker for non-blocking disassembly
+ * Runs cs_disasm in a background thread and returns results via Promise
+ */
+class DisasmAsyncWorker : public Napi::AsyncWorker {
+public:
+    DisasmAsyncWorker(
+        Napi::Env env,
+        csh handle,
+        cs_arch arch,
+        std::vector<uint8_t> code,
+        uint64_t address,
+        size_t count,
+        bool includeDetail
+    ) : Napi::AsyncWorker(env),
+        deferred_(Napi::Promise::Deferred::New(env)),
+        handle_(handle),
+        arch_(arch),
+        code_(std::move(code)),
+        address_(address),
+        count_(count),
+        includeDetail_(includeDetail),
+        numInsns_(0),
+        error_(CS_ERR_OK) {}
+
+    ~DisasmAsyncWorker() {}
+
+    /**
+     * Get the Promise that will be resolved when work completes
+     */
+    Napi::Promise GetPromise() { return deferred_.Promise(); }
+
+    /**
+     * Execute in background thread - no V8/N-API calls allowed here!
+     */
+    void Execute() override {
+        cs_insn* insn = nullptr;
+
+        // Perform disassembly in background thread
+        numInsns_ = cs_disasm(
+            handle_,
+            code_.data(),
+            code_.size(),
+            address_,
+            count_,
+            &insn
+        );
+
+        if (numInsns_ == 0) {
+            error_ = cs_errno(handle_);
+            return;
+        }
+
+        // Copy data to our intermediate structures (no V8 objects here!)
+        results_.reserve(numInsns_);
+
+        for (size_t i = 0; i < numInsns_; i++) {
+            DisasmResult result;
+            result.id = insn[i].id;
+            result.address = insn[i].address;
+            result.size = insn[i].size;
+            result.bytes.assign(insn[i].bytes, insn[i].bytes + insn[i].size);
+            result.mnemonic = insn[i].mnemonic;
+            result.op_str = insn[i].op_str;
+            result.hasDetail = false;
+
+            // Copy detail if available and requested
+            if (includeDetail_ && insn[i].detail != nullptr) {
+                result.hasDetail = true;
+                cs_detail* detail = insn[i].detail;
+
+                result.regsRead.assign(
+                    detail->regs_read,
+                    detail->regs_read + detail->regs_read_count
+                );
+                result.regsWrite.assign(
+                    detail->regs_write,
+                    detail->regs_write + detail->regs_write_count
+                );
+                result.groups.assign(
+                    detail->groups,
+                    detail->groups + detail->groups_count
+                );
+            }
+
+            results_.push_back(std::move(result));
+        }
+
+        // Free Capstone memory
+        cs_free(insn, numInsns_);
+    }
+
+    /**
+     * Called in main thread after Execute completes successfully
+     */
+    void OnOK() override {
+        Napi::Env env = Env();
+        Napi::HandleScope scope(env);
+
+        // Convert results to JavaScript array
+        Napi::Array jsArray = Napi::Array::New(env, results_.size());
+
+        for (size_t i = 0; i < results_.size(); i++) {
+            jsArray.Set(static_cast<uint32_t>(i), ResultToObject(env, results_[i]));
+        }
+
+        deferred_.Resolve(jsArray);
+    }
+
+    /**
+     * Called in main thread if Execute throws
+     */
+    void OnError(const Napi::Error& error) override {
+        deferred_.Reject(error.Value());
+    }
+
+private:
+    Napi::Promise::Deferred deferred_;
+    csh handle_;
+    cs_arch arch_;
+    std::vector<uint8_t> code_;
+    uint64_t address_;
+    size_t count_;
+    bool includeDetail_;
+
+    // Results from Execute()
+    size_t numInsns_;
+    cs_err error_;
+    std::vector<DisasmResult> results_;
+
+    /**
+     * Convert our intermediate structure to a JavaScript object
+     */
+    Napi::Object ResultToObject(Napi::Env env, const DisasmResult& result) {
+        Napi::Object obj = Napi::Object::New(env);
+
+        obj.Set("id", Napi::Number::New(env, result.id));
+        obj.Set("address", Napi::Number::New(env, static_cast<double>(result.address)));
+        obj.Set("size", Napi::Number::New(env, result.size));
+        obj.Set("mnemonic", Napi::String::New(env, result.mnemonic));
+        obj.Set("opStr", Napi::String::New(env, result.op_str));
+
+        // Copy bytes
+        Napi::Buffer<uint8_t> bytes = Napi::Buffer<uint8_t>::Copy(
+            env, result.bytes.data(), result.bytes.size()
+        );
+        obj.Set("bytes", bytes);
+
+        // Add detail if available
+        if (result.hasDetail) {
+            Napi::Object detail = Napi::Object::New(env);
+
+            // Registers read
+            Napi::Array regsRead = Napi::Array::New(env, result.regsRead.size());
+            for (size_t j = 0; j < result.regsRead.size(); j++) {
+                regsRead.Set(static_cast<uint32_t>(j), Napi::Number::New(env, result.regsRead[j]));
+            }
+            detail.Set("regsRead", regsRead);
+
+            // Registers written
+            Napi::Array regsWrite = Napi::Array::New(env, result.regsWrite.size());
+            for (size_t j = 0; j < result.regsWrite.size(); j++) {
+                regsWrite.Set(static_cast<uint32_t>(j), Napi::Number::New(env, result.regsWrite[j]));
+            }
+            detail.Set("regsWrite", regsWrite);
+
+            // Groups
+            Napi::Array groups = Napi::Array::New(env, result.groups.size());
+            for (size_t j = 0; j < result.groups.size(); j++) {
+                groups.Set(static_cast<uint32_t>(j), Napi::Number::New(env, result.groups[j]));
+            }
+            detail.Set("groups", groups);
+
+            obj.Set("detail", detail);
+        }
+
+        return obj;
+    }
+};
+
+#endif // DISASM_ASYNC_WORKER_H

package/src/main.cpp

@@ -0,0 +1,145 @@
+/*
+ * HexCore Capstone - Native Node.js Bindings
+ * Main entry point for N-API addon
+ * Copyright (c) HikariSystem. All rights reserved.
+ * Licensed under MIT License.
+ */
+
+#include <napi.h>
+#include "capstone_wrapper.h"
+
+/**
+ * Initialize the addon module
+ */
+Napi::Object Init(Napi::Env env, Napi::Object exports) {
+    // Initialize Capstone wrapper class
+    CapstoneWrapper::Init(env, exports);
+
+    // Export architecture constants
+    Napi::Object arch = Napi::Object::New(env);
+    arch.Set("ARM", Napi::Number::New(env, CS_ARCH_ARM));
+    arch.Set("ARM64", Napi::Number::New(env, CS_ARCH_ARM64));
+    arch.Set("MIPS", Napi::Number::New(env, CS_ARCH_MIPS));
+    arch.Set("X86", Napi::Number::New(env, CS_ARCH_X86));
+    arch.Set("PPC", Napi::Number::New(env, CS_ARCH_PPC));
+    arch.Set("SPARC", Napi::Number::New(env, CS_ARCH_SPARC));
+    arch.Set("SYSZ", Napi::Number::New(env, CS_ARCH_SYSZ));
+    arch.Set("XCORE", Napi::Number::New(env, CS_ARCH_XCORE));
+    arch.Set("M68K", Napi::Number::New(env, CS_ARCH_M68K));
+    arch.Set("TMS320C64X", Napi::Number::New(env, CS_ARCH_TMS320C64X));
+    arch.Set("M680X", Napi::Number::New(env, CS_ARCH_M680X));
+    arch.Set("EVM", Napi::Number::New(env, CS_ARCH_EVM));
+    #ifdef CS_ARCH_WASM
+    arch.Set("WASM", Napi::Number::New(env, CS_ARCH_WASM));
+    #endif
+    #ifdef CS_ARCH_BPF
+    arch.Set("BPF", Napi::Number::New(env, CS_ARCH_BPF));
+    #endif
+    #ifdef CS_ARCH_RISCV
+    arch.Set("RISCV", Napi::Number::New(env, CS_ARCH_RISCV));
+    #endif
+    exports.Set("ARCH", arch);
+
+    // Export mode constants
+    Napi::Object mode = Napi::Object::New(env);
+    mode.Set("LITTLE_ENDIAN", Napi::Number::New(env, CS_MODE_LITTLE_ENDIAN));
+    mode.Set("BIG_ENDIAN", Napi::Number::New(env, CS_MODE_BIG_ENDIAN));
+    mode.Set("ARM", Napi::Number::New(env, CS_MODE_ARM));
+    mode.Set("THUMB", Napi::Number::New(env, CS_MODE_THUMB));
+    mode.Set("MCLASS", Napi::Number::New(env, CS_MODE_MCLASS));
+    mode.Set("V8", Napi::Number::New(env, CS_MODE_V8));
+    mode.Set("MODE_16", Napi::Number::New(env, CS_MODE_16));
+    mode.Set("MODE_32", Napi::Number::New(env, CS_MODE_32));
+    mode.Set("MODE_64", Napi::Number::New(env, CS_MODE_64));
+    mode.Set("MICRO", Napi::Number::New(env, CS_MODE_MICRO));
+    mode.Set("MIPS3", Napi::Number::New(env, CS_MODE_MIPS3));
+    mode.Set("MIPS32R6", Napi::Number::New(env, CS_MODE_MIPS32R6));
+    mode.Set("MIPS2", Napi::Number::New(env, CS_MODE_MIPS2));
+    mode.Set("V9", Napi::Number::New(env, CS_MODE_V9));
+    mode.Set("QPX", Napi::Number::New(env, CS_MODE_QPX));
+    mode.Set("M68K_000", Napi::Number::New(env, CS_MODE_M68K_000));
+    mode.Set("M68K_010", Napi::Number::New(env, CS_MODE_M68K_010));
+    mode.Set("M68K_020", Napi::Number::New(env, CS_MODE_M68K_020));
+    mode.Set("M68K_030", Napi::Number::New(env, CS_MODE_M68K_030));
+    mode.Set("M68K_040", Napi::Number::New(env, CS_MODE_M68K_040));
+    mode.Set("M68K_060", Napi::Number::New(env, CS_MODE_M68K_060));
+    #ifdef CS_MODE_RISCV32
+    mode.Set("RISCV32", Napi::Number::New(env, CS_MODE_RISCV32));
+    mode.Set("RISCV64", Napi::Number::New(env, CS_MODE_RISCV64));
+    mode.Set("RISCVC", Napi::Number::New(env, CS_MODE_RISCVC));
+    #endif
+    exports.Set("MODE", mode);
+
+    // Export option constants
+    Napi::Object opt = Napi::Object::New(env);
+    opt.Set("SYNTAX", Napi::Number::New(env, CS_OPT_SYNTAX));
+    opt.Set("DETAIL", Napi::Number::New(env, CS_OPT_DETAIL));
+    opt.Set("MODE", Napi::Number::New(env, CS_OPT_MODE));
+    opt.Set("MEM", Napi::Number::New(env, CS_OPT_MEM));
+    opt.Set("SKIPDATA", Napi::Number::New(env, CS_OPT_SKIPDATA));
+    opt.Set("SKIPDATA_SETUP", Napi::Number::New(env, CS_OPT_SKIPDATA_SETUP));
+    opt.Set("MNEMONIC", Napi::Number::New(env, CS_OPT_MNEMONIC));
+    opt.Set("UNSIGNED", Napi::Number::New(env, CS_OPT_UNSIGNED));
+    exports.Set("OPT", opt);
+
+    // Export option value constants
+    Napi::Object optValue = Napi::Object::New(env);
+    optValue.Set("OFF", Napi::Number::New(env, CS_OPT_OFF));
+    optValue.Set("ON", Napi::Number::New(env, CS_OPT_ON));
+    optValue.Set("SYNTAX_DEFAULT", Napi::Number::New(env, CS_OPT_SYNTAX_DEFAULT));
+    optValue.Set("SYNTAX_INTEL", Napi::Number::New(env, CS_OPT_SYNTAX_INTEL));
+    optValue.Set("SYNTAX_ATT", Napi::Number::New(env, CS_OPT_SYNTAX_ATT));
+    optValue.Set("SYNTAX_NOREGNAME", Napi::Number::New(env, CS_OPT_SYNTAX_NOREGNAME));
+    optValue.Set("SYNTAX_MASM", Napi::Number::New(env, CS_OPT_SYNTAX_MASM));
+    exports.Set("OPT_VALUE", optValue);
+
+    // Export error constants
+    Napi::Object err = Napi::Object::New(env);
+    err.Set("OK", Napi::Number::New(env, CS_ERR_OK));
+    err.Set("MEM", Napi::Number::New(env, CS_ERR_MEM));
+    err.Set("ARCH", Napi::Number::New(env, CS_ERR_ARCH));
+    err.Set("HANDLE", Napi::Number::New(env, CS_ERR_HANDLE));
+    err.Set("CSH", Napi::Number::New(env, CS_ERR_CSH));
+    err.Set("MODE", Napi::Number::New(env, CS_ERR_MODE));
+    err.Set("OPTION", Napi::Number::New(env, CS_ERR_OPTION));
+    err.Set("DETAIL", Napi::Number::New(env, CS_ERR_DETAIL));
+    err.Set("MEMSETUP", Napi::Number::New(env, CS_ERR_MEMSETUP));
+    err.Set("VERSION", Napi::Number::New(env, CS_ERR_VERSION));
+    err.Set("DIET", Napi::Number::New(env, CS_ERR_DIET));
+    err.Set("SKIPDATA", Napi::Number::New(env, CS_ERR_SKIPDATA));
+    err.Set("X86_ATT", Napi::Number::New(env, CS_ERR_X86_ATT));
+    err.Set("X86_INTEL", Napi::Number::New(env, CS_ERR_X86_INTEL));
+    err.Set("X86_MASM", Napi::Number::New(env, CS_ERR_X86_MASM));
+    exports.Set("ERR", err);
+
+    // Export version function
+    exports.Set("version", Napi::Function::New(env, [](const Napi::CallbackInfo& info) {
+        Napi::Env env = info.Env();
+        int major, minor;
+        cs_version(&major, &minor);
+
+        Napi::Object version = Napi::Object::New(env);
+        version.Set("major", Napi::Number::New(env, major));
+        version.Set("minor", Napi::Number::New(env, minor));
+        version.Set("string", Napi::String::New(env,
+            std::to_string(major) + "." + std::to_string(minor)));
+        return version;
+    }));
+
+    // Export support check function
+    exports.Set("support", Napi::Function::New(env, [](const Napi::CallbackInfo& info) {
+        Napi::Env env = info.Env();
+        if (info.Length() < 1 || !info[0].IsNumber()) {
+            Napi::TypeError::New(env, "Architecture constant required").ThrowAsJavaScriptException();
+            return Napi::Boolean::New(env, false);
+        }
+
+        int arch = info[0].As<Napi::Number>().Int32Value();
+        bool supported = cs_support(arch);
+        return Napi::Boolean::New(env, supported);
+    }));
+
+    return exports;
+}
+
+NODE_API_MODULE(capstone_native, Init)