hexcore-capstone 1.2.0

package/index.d.ts

@@ -0,0 +1,448 @@
+/**
+ * HexCore Capstone - TypeScript Definitions
+ * Modern N-API bindings for Capstone disassembler engine
+ *
+ * Copyright (c) HikariSystem. All rights reserved.
+ * Licensed under MIT License.
+ */
+
+/// <reference types="node" />
+
+/**
+ * Architecture constants
+ */
+export const ARCH: {
+	readonly ARM: number;
+	readonly ARM64: number;
+	readonly MIPS: number;
+	readonly X86: number;
+	readonly PPC: number;
+	readonly SPARC: number;
+	readonly SYSZ: number;
+	readonly XCORE: number;
+	readonly M68K: number;
+	readonly TMS320C64X: number;
+	readonly M680X: number;
+	readonly EVM: number;
+	readonly WASM?: number;
+	readonly BPF?: number;
+	readonly RISCV?: number;
+};
+
+/**
+ * Mode constants
+ */
+export const MODE: {
+	readonly LITTLE_ENDIAN: number;
+	readonly BIG_ENDIAN: number;
+	readonly ARM: number;
+	readonly THUMB: number;
+	readonly MCLASS: number;
+	readonly V8: number;
+	readonly MODE_16: number;
+	readonly MODE_32: number;
+	readonly MODE_64: number;
+	readonly MICRO: number;
+	readonly MIPS3: number;
+	readonly MIPS32R6: number;
+	readonly MIPS2: number;
+	readonly V9: number;
+	readonly QPX: number;
+	readonly M68K_000: number;
+	readonly M68K_010: number;
+	readonly M68K_020: number;
+	readonly M68K_030: number;
+	readonly M68K_040: number;
+	readonly M68K_060: number;
+	readonly RISCV32?: number;
+	readonly RISCV64?: number;
+	readonly RISCVC?: number;
+};
+
+/**
+ * Option type constants
+ */
+export const OPT: {
+	readonly SYNTAX: number;
+	readonly DETAIL: number;
+	readonly MODE: number;
+	readonly MEM: number;
+	readonly SKIPDATA: number;
+	readonly SKIPDATA_SETUP: number;
+	readonly MNEMONIC: number;
+	readonly UNSIGNED: number;
+};
+
+/**
+ * Option value constants
+ */
+export const OPT_VALUE: {
+	readonly OFF: number;
+	readonly ON: number;
+	readonly SYNTAX_DEFAULT: number;
+	readonly SYNTAX_INTEL: number;
+	readonly SYNTAX_ATT: number;
+	readonly SYNTAX_NOREGNAME: number;
+	readonly SYNTAX_MASM: number;
+};
+
+/**
+ * Error code constants
+ */
+export const ERR: {
+	readonly OK: number;
+	readonly MEM: number;
+	readonly ARCH: number;
+	readonly HANDLE: number;
+	readonly CSH: number;
+	readonly MODE: number;
+	readonly OPTION: number;
+	readonly DETAIL: number;
+	readonly MEMSETUP: number;
+	readonly VERSION: number;
+	readonly DIET: number;
+	readonly SKIPDATA: number;
+	readonly X86_ATT: number;
+	readonly X86_INTEL: number;
+	readonly X86_MASM: number;
+};
+
+/**
+ * Memory operand structure
+ */
+export interface MemoryOperand {
+	segment?: number;
+	base: number;
+	index?: number;
+	scale?: number;
+	disp: number;
+}
+
+/**
+ * x86 operand structure
+ */
+export interface X86Operand {
+	type: number;
+	size: number;
+	access: number;
+	avxBcast: number;
+	avxZeroOpmask: boolean;
+	reg?: number;
+	imm?: number;
+	mem?: MemoryOperand;
+}
+
+/**
+ * x86 instruction detail
+ */
+export interface X86Detail {
+	prefix: number[];
+	opcode: number[];
+	rexPrefix: number;
+	addrSize: number;
+	modRM: number;
+	sib: number;
+	disp: number;
+	sibIndex: number;
+	sibScale: number;
+	sibBase: number;
+	xopCC: number;
+	sseCC: number;
+	avxCC: number;
+	avxSAE: boolean;
+	avxRM: number;
+	eflags: number;
+	operands: X86Operand[];
+}
+
+/**
+ * ARM operand structure
+ */
+export interface ArmOperand {
+	type: number;
+	access: number;
+	reg?: number;
+	imm?: number;
+	fp?: number;
+}
+
+/**
+ * ARM instruction detail
+ */
+export interface ArmDetail {
+	usermode: boolean;
+	vectorSize: number;
+	vectorData: number;
+	cpsMode: number;
+	cpsFlag: number;
+	cc: number;
+	updateFlags: boolean;
+	writeback: boolean;
+	memBarrier: number;
+	operands: ArmOperand[];
+}
+
+/**
+ * ARM64 operand structure
+ */
+export interface Arm64Operand {
+	type: number;
+	access: number;
+	reg?: number;
+	imm?: number;
+	fp?: number;
+}
+
+/**
+ * ARM64 instruction detail
+ */
+export interface Arm64Detail {
+	cc: number;
+	updateFlags: boolean;
+	writeback: boolean;
+	operands: Arm64Operand[];
+}
+
+/**
+ * MIPS operand structure
+ */
+export interface MipsOperand {
+	type: number;
+	reg?: number;
+	imm?: number;
+	mem?: {
+		base: number;
+		disp: number;
+	};
+}
+
+/**
+ * MIPS instruction detail
+ */
+export interface MipsDetail {
+	operands: MipsOperand[];
+}
+
+/**
+ * Instruction detail (when detail mode is enabled)
+ */
+export interface InstructionDetail {
+	regsRead: number[];
+	regsWrite: number[];
+	groups: number[];
+	x86?: X86Detail;
+	arm?: ArmDetail;
+	arm64?: Arm64Detail;
+	mips?: MipsDetail;
+}
+
+/**
+ * Disassembled instruction
+ */
+export interface Instruction {
+	/** Instruction ID */
+	id: number;
+	/** Address of this instruction */
+	address: number;
+	/** Size of this instruction in bytes */
+	size: number;
+	/** Raw bytes of this instruction */
+	bytes: Buffer;
+	/** Mnemonic (e.g., "mov", "push") */
+	mnemonic: string;
+	/** Operand string (e.g., "rax, rbx") */
+	opStr: string;
+	/** Detailed info (only when detail mode is enabled) */
+	detail?: InstructionDetail;
+}
+
+/**
+ * Version information
+ */
+export interface Version {
+	major: number;
+	minor: number;
+	string: string;
+}
+
+/**
+ * Capstone disassembler class
+ *
+ * @example
+ * ```typescript
+ * import { Capstone, ARCH, MODE, OPT, OPT_VALUE } from 'hexcore-capstone';
+ *
+ * // Create disassembler for x86-64
+ * const cs = new Capstone(ARCH.X86, MODE.MODE_64);
+ *
+ * // Enable detail mode for operand info
+ * cs.setOption(OPT.DETAIL, OPT_VALUE.ON);
+ *
+ * // Disassemble code
+ * const code = Buffer.from([0x55, 0x48, 0x89, 0xe5]);
+ * const instructions = cs.disasm(code, 0x1000);
+ *
+ * for (const insn of instructions) {
+ *   console.log(`${insn.address.toString(16)}: ${insn.mnemonic} ${insn.opStr}`);
+ * }
+ *
+ * // Clean up
+ * cs.close();
+ * ```
+ */
+export class Capstone {
+	/**
+	 * Create a new Capstone disassembler instance
+	 *
+	 * @param arch - Architecture constant (use ARCH.X86, ARCH.ARM, etc.)
+	 * @param mode - Mode flags (use MODE.MODE_64, MODE.LITTLE_ENDIAN, etc.)
+	 * @throws Error if architecture or mode is invalid
+	 *
+	 * @example
+	 * ```typescript
+	 * // x86-64 disassembler
+	 * const cs64 = new Capstone(ARCH.X86, MODE.MODE_64);
+	 *
+	 * // ARM Thumb mode
+	 * const csArm = new Capstone(ARCH.ARM, MODE.THUMB);
+	 *
+	 * // MIPS big-endian 32-bit
+	 * const csMips = new Capstone(ARCH.MIPS, MODE.MODE_32 | MODE.BIG_ENDIAN);
+	 * ```
+	 */
+	constructor(arch: number, mode: number);
+
+	/**
+	 * Disassemble code buffer (synchronous)
+	 *
+	 * **Note:** For large buffers (>1MB), use `disasmAsync()` to avoid blocking.
+	 *
+	 * @param code - Buffer containing machine code to disassemble
+	 * @param address - Base address of the code (for correct jump targets)
+	 * @param count - Maximum number of instructions to disassemble (0 = all)
+	 * @returns Array of disassembled instructions
+	 *
+	 * @example
+	 * ```typescript
+	 * const code = Buffer.from([0x55, 0x48, 0x89, 0xe5, 0xc3]);
+	 * const insns = cs.disasm(code, 0x401000);
+	 * // Returns: push rbp, mov rbp,rsp, ret
+	 * ```
+	 */
+	disasm(code: Buffer | Uint8Array, address: number, count?: number): Instruction[];
+
+	/**
+	 * Disassemble code buffer (asynchronous, non-blocking)
+	 *
+	 * Use this method for large buffers to avoid blocking the event loop.
+	 * The disassembly runs in a background thread and returns a Promise.
+	 *
+	 * @param code - Buffer containing machine code to disassemble
+	 * @param address - Base address of the code (for correct jump targets)
+	 * @param count - Maximum number of instructions to disassemble (0 = all)
+	 * @returns Promise resolving to array of disassembled instructions
+	 *
+	 * @example
+	 * ```typescript
+	 * // Large file async disassembly
+	 * const largeCode = fs.readFileSync('large_binary.bin');
+	 * const insns = await cs.disasmAsync(largeCode, 0x401000);
+	 * console.log(`Disassembled ${insns.length} instructions`);
+	 * ```
+	 */
+	disasmAsync(code: Buffer | Uint8Array, address: number, count?: number): Promise<Instruction[]>;
+
+	/**
+	 * Set a disassembler option
+	 *
+	 * @param type - Option type (OPT.DETAIL, OPT.SYNTAX, etc.)
+	 * @param value - Option value (OPT_VALUE.ON, OPT_VALUE.SYNTAX_INTEL, etc.)
+	 * @returns true on success, throws on failure
+	 *
+	 * @example
+	 * ```typescript
+	 * // Enable detailed instruction info
+	 * cs.setOption(OPT.DETAIL, OPT_VALUE.ON);
+	 *
+	 * // Use Intel syntax (default)
+	 * cs.setOption(OPT.SYNTAX, OPT_VALUE.SYNTAX_INTEL);
+	 *
+	 * // Use AT&T syntax
+	 * cs.setOption(OPT.SYNTAX, OPT_VALUE.SYNTAX_ATT);
+	 * ```
+	 */
+	setOption(type: number, value: number): boolean;
+
+	/**
+	 * Close the disassembler and free resources
+	 *
+	 * Always call this when done to prevent memory leaks.
+	 */
+	close(): void;
+
+	/**
+	 * Get register name by ID
+	 *
+	 * @param regId - Register ID from instruction details
+	 * @returns Register name (e.g., "rax", "eip") or null if not found
+	 *
+	 * @example
+	 * ```typescript
+	 * const insn = cs.disasm(code, 0x1000)[0];
+	 * if (insn.detail?.x86?.operands[0]?.reg) {
+	 *   console.log(cs.regName(insn.detail.x86.operands[0].reg)); // "rbp"
+	 * }
+	 * ```
+	 */
+	regName(regId: number): string | null;
+
+	/**
+	 * Get instruction name by ID
+	 *
+	 * @param insnId - Instruction ID from disassembled instruction
+	 * @returns Instruction name or null if not found
+	 */
+	insnName(insnId: number): string | null;
+
+	/**
+	 * Get group name by ID
+	 *
+	 * @param groupId - Group ID from instruction details
+	 * @returns Group name (e.g., "jump", "call", "ret") or null
+	 */
+	groupName(groupId: number): string | null;
+
+	/**
+	 * Check if the disassembler handle is still open
+	 * @returns true if open
+	 */
+	isOpen(): boolean;
+
+	/**
+	 * Get the last error code
+	 * @returns Error code (use ERR constants)
+	 */
+	getError(): number;
+
+	/**
+	 * Get error message string
+	 * @param err - Error code (optional, defaults to last error)
+	 * @returns Error message
+	 */
+	strError(err?: number): string;
+}
+
+/**
+ * Get Capstone version
+ * @returns Version information
+ */
+export function version(): Version;
+
+/**
+ * Check if an architecture is supported
+ * @param arch Architecture constant
+ * @returns true if supported
+ */
+export function support(arch: number): boolean;
+
+export default Capstone;

package/index.js

@@ -0,0 +1,64 @@
+/**
+ * HexCore Capstone - Native Node.js Bindings
+ * Modern N-API bindings for Capstone disassembler engine
+ *
+ * Copyright (c) HikariSystem. All rights reserved.
+ * Licensed under MIT License.
+ *
+ * @example
+ * const { Capstone, ARCH, MODE } = require('hexcore-capstone');
+ *
+ * const cs = new Capstone(ARCH.X86, MODE.MODE_64);
+ * const code = Buffer.from([0x55, 0x48, 0x89, 0xe5]);
+ * const instructions = cs.disasm(code, 0x1000);
+ *
+ * for (const insn of instructions) {
+ *   console.log(`${insn.address.toString(16)}: ${insn.mnemonic} ${insn.opStr}`);
+ * }
+ *
+ * cs.close();
+ */
+
+'use strict';
+
+// Load the native addon
+let binding;
+try {
+	// Try to load prebuilt binary first
+	binding = require('./prebuilds/' + process.platform + '-' + process.arch + '/node.napi.node');
+} catch (e1) {
+	try {
+		// Fall back to node-gyp built binary
+		binding = require('./build/Release/capstone_native.node');
+	} catch (e2) {
+		try {
+			// Try debug build
+			binding = require('./build/Debug/capstone_native.node');
+		} catch (e3) {
+			throw new Error(
+				'Failed to load hexcore-capstone native module. ' +
+				'Make sure you have run npm install and have the required build tools. ' +
+				'Original errors:\n' +
+				`  Prebuild: ${e1.message}\n` +
+				`  Release: ${e2.message}\n` +
+				`  Debug: ${e3.message}`
+			);
+		}
+	}
+}
+
+// Export everything from the binding
+module.exports = binding;
+
+// Add convenience aliases
+module.exports.default = binding.Capstone;
+
+// Export named constants for easier destructuring
+module.exports.Capstone = binding.Capstone;
+module.exports.ARCH = binding.ARCH;
+module.exports.MODE = binding.MODE;
+module.exports.OPT = binding.OPT;
+module.exports.OPT_VALUE = binding.OPT_VALUE;
+module.exports.ERR = binding.ERR;
+module.exports.version = binding.version;
+module.exports.support = binding.support;

package/index.mjs

@@ -0,0 +1,25 @@
+/**
+ * HexCore Capstone - ESM Wrapper
+ * ECMAScript Module support for modern Node.js
+ *
+ * Copyright (c) HikariSystem. All rights reserved.
+ * Licensed under MIT License.
+ */
+
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+
+const capstone = require('./index.js');
+
+export const {
+	Capstone,
+	ARCH,
+	MODE,
+	OPT,
+	OPT_VALUE,
+	ERR,
+	version,
+	support
+} = capstone;
+
+export default Capstone;

package/package.json

@@ -0,0 +1,82 @@
+{
+	"name": "hexcore-capstone",
+	"version": "1.2.0",
+	"description": "Modern Node.js bindings for Capstone disassembler engine using N-API",
+	"main": "./index.js",
+	"module": "./index.mjs",
+	"types": "./index.d.ts",
+	"exports": {
+		".": {
+			"import": "./index.mjs",
+			"require": "./index.js",
+			"types": "./index.d.ts"
+		}
+	},
+	"scripts": {
+		"install": "prebuild-install || node-gyp rebuild",
+		"build": "node-gyp rebuild",
+		"build:debug": "node-gyp rebuild --debug",
+		"prebuild": "prebuildify --napi --strip",
+		"prebuild:all": "prebuildify-cross -i centos7-devtoolset7 -i alpine -i linux-armv7 -i linux-arm64",
+		"test": "node test/test.js",
+		"clean": "node-gyp clean",
+		"prepare": "npm run build"
+	},
+	"keywords": [
+		"capstone",
+		"disassembler",
+		"disassembly",
+		"reverse-engineering",
+		"binary-analysis",
+		"x86",
+		"x64",
+		"arm",
+		"arm64",
+		"mips",
+		"ppc",
+		"sparc",
+		"m68k",
+		"riscv",
+		"native",
+		"napi",
+		"async"
+	],
+	"author": "HikariSystem <hikarisystem@example.com>",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/hikarisystem/hexcore-capstone.git"
+	},
+	"bugs": {
+		"url": "https://github.com/hikarisystem/hexcore-capstone/issues"
+	},
+	"homepage": "https://github.com/hikarisystem/hexcore-capstone#readme",
+	"engines": {
+		"node": ">=18.0.0"
+	},
+	"dependencies": {
+		"node-addon-api": "^7.0.0",
+		"prebuild-install": "^7.1.1"
+	},
+	"devDependencies": {
+		"node-gyp": "^10.0.0",
+		"prebuildify": "^6.0.0"
+	},
+	"files": [
+		"src/",
+		"deps/capstone/*.c",
+		"deps/capstone/*.h",
+		"deps/capstone/include/",
+		"deps/capstone/arch/",
+		"prebuilds/",
+		"binding.gyp",
+		"index.js",
+		"index.mjs",
+		"index.d.ts"
+	],
+	"binary": {
+		"napi_versions": [
+			8
+		]
+	}
+}