@bingine/cemem 0.0.0-stage → 0.1.1

package/dist/types/asm/disassembler.d.ts

@@ -0,0 +1,194 @@
+/**
+ * 反汇编器（x86 / x64 / ARM / Thumb / ARM64）—— 输出对齐 Cheat Engine 的
+ * `TLastDisassembleData`。
+ *
+ * 后端是 Capstone（见 `backend.ts` 里关于"CE 自己也用 binutils 而非手写解码器"的说明）。
+ * 本文件负责把 Capstone 的原始结果加工成 CE 需要的那套字段与文本格式。
+ *
+ * CE 的字段定义见 `lastdisassembledata.pas` 的 `TLastDisassembleData`：
+ *   address / prefix / opcode / parameters / description / Bytes /
+ *   SeperatorCount+Seperators / modrmValue / parameterValue /
+ *   datasize / isfloat / isfloat64 / hasSib / sibIndex / sibScaler /
+ *   isjump / iscall / isret / isrep / isconditionaljump / riprelative
+ *   / Disassembler（dcX86 / dcArm / dcArm64 / dcThumb）
+ *
+ * ## 文本格式
+ * CE 在 binutils 分支下产出 `"地址 - 字节 - 操作码 参数"`。
+ * 本模块的 `formatDisassembled` 产同样形状的字符串，同时把 opcode / parameters
+ * 分开保留（CE 内部也是分开存的，显示时才拼）。
+ *
+ * ## 多架构差异（这里是最容易出错的地方）
+ *
+ * | 项目 | x86/x64 | ARM/Thumb | ARM64 |
+ * | --- | --- | --- | --- |
+ * | 指令长度 | 1–15 字节，可变 | 4（Thumb 2/4） | 4 |
+ * | 前缀 | `rep`/`lock`/段前缀 | 无 | 无 |
+ * | 条件执行 | `jcc` 助记符（7x/0F 8x） | **指令后缀**（`moveq`/`addne`） | `b.eq` 助记符 |
+ * | 返回 | `ret`/`retf`/`iret` | `bx lr`/`pop {...,pc}`/`mov pc,lr` | `ret` |
+ * | 调用 | `call` | `bl`/`blx` | `bl`/`blr` |
+ * | 寄存器 | `rax`/`eax`/`al`… | `r0`–`r15`、`sp`/`lr`/`pc` | `x0`–`x30`、`w0`–`w30`、`sp`/`xzr`/`wzr` |
+ * | RIP 相对 | 有（`[rip+disp]`） | 无 | 有（`adrp`/`ldr xN, [pc,...]`、`b`/`bl` 的 PC 相对） |
+ *
+ * ## 已知限制
+ * `capstone-wasm` 不暴露 detail（`readInsn` 是私有的），因此拿不到
+ * "操作数类型/寄存器使用/内存操作数宽度"等结构信息。
+ * 本模块改用**助记符表**判定流程控制与数据宽度，对主流指令足够；
+ * 冷门指令会被标成 `isjump=false`（宁可少标，不要错标）。
+ */
+import { type AsmArchitecture, type AsmEndianness } from './backend';
+/** 值类型提示，对齐 CE 的 TDisAssemblerValueType */
+export declare enum DisasmValueType {
+    None = 0,
+    Address = 1,
+    Value = 2
+}
+/** 反汇编器类型，对齐 CE 的 TDisassemblerClass */
+export declare enum DisassemblerClass {
+    X86 = "dcX86",
+    Arm = "dcArm",
+    Arm64 = "dcArm64",
+    Thumb = "dcThumb"
+}
+/**
+ * 一条反汇编结果，字段对齐 CE 的 `TLastDisassembleData`。
+ */
+export interface DisassembledInstruction {
+    /** 指令地址 */
+    address: bigint;
+    /** 前缀文本（x86 的 `rep`/`lock`），ARM 上恒为空串 */
+    prefix: string;
+    /** 前缀字节数 */
+    prefixSize: number;
+    /**
+     * 操作码。
+     *
+     * 多架构注意：
+     *   - x86：`mov`、`je`
+     *   - ARM/Thumb：Capstone 把条件后缀并进助记符（`moveq`），本字段保持原样；
+     *     条件码另见 `conditionCode`。
+     *   - ARM64：`b`、`b.eq` 会拆成 `opcode='b'` + `suffix='.eq'`
+     *     （为与 x86 的 `jcc` 形态对齐，便于上层统一判断条件跳转）。
+     */
+    opcode: string;
+    /** 助记符后缀（ARM64 的 `.eq` 等）；无后缀时为空串 */
+    suffix: string;
+    /** 参数部分 */
+    parameters: string;
+    /** 描述（本移植留空） */
+    description: string;
+    /** 机器码字节，**每个字节一个 `Buffer`**（对齐 CE 的 `Bytes: array of byte`） */
+    bytes: Buffer[];
+    /** 分隔点：字节数组里 前缀/操作码/modrm/sib/额外 的分界下标 */
+    separators: number[];
+    separatorCount: number;
+    /** 内存操作数（modrm）指向的值 */
+    modrmValueType: DisasmValueType;
+    modrmValue: bigint;
+    /** 其它参数里的值（立即数/位移） */
+    parameterValueType: DisasmValueType;
+    parameterValue: bigint;
+    /** 该指令读写的数据宽度（字节）；不确定时为 0 */
+    dataSize: number;
+    /** 是否读写单精度浮点（仅在有把握时为 true） */
+    isFloat: boolean;
+    /** 是否读写双精度浮点 */
+    isFloat64: boolean;
+    /** 是否含 SIB 字节（仅 x86 有意义） */
+    hasSib: boolean;
+    sibIndex: number;
+    sibScaler: number;
+    /** 是否可能改变 pc/rip */
+    isJump: boolean;
+    /** 是否 call（含 `bl`） */
+    isCall: boolean;
+    /** 是否 ret（含 ARM 的 `bx lr`、`pop {...,pc}`） */
+    isRet: boolean;
+    /** 是否带 rep/repe/repne 前缀（仅 x86） */
+    isRep: boolean;
+    /** 是否条件跳转/条件执行 */
+    isConditionalJump: boolean;
+    /** 条件码文本（如 `eq`/`ne`）；无则空串 */
+    conditionCode: string;
+    /** RIP 相对（x86）或 PC 相对（ARM64）偏移下标；-1 表示不是 */
+    ripRelative: number;
+    /** 是否 64 位目标 */
+    is64Bit: boolean;
+    /** 使用的架构 */
+    arch: AsmArchitecture;
+    /** 反汇编器类型（对齐 CE 的 Disassembler 字段） */
+    disassemblerClass: DisassemblerClass;
+    /** 原始助记符（含后缀，小写） */
+    mnemonic: string;
+    /** 指令长度 */
+    size: number;
+}
+export interface DisassembleOptions {
+    /** 架构，默认 `x64` */
+    arch?: AsmArchitecture;
+    /** 兼容旧写法：位数。arch 优先 */
+    bitness?: 32 | 64;
+    /** 字节序，默认 little */
+    endianness?: AsmEndianness;
+}
+/**
+ * 反汇编内存中的一段代码。
+ *
+ * @param code 机器码缓冲区
+ * @param address 该缓冲区在目标进程中的地址
+ * @param maxInstructions 最多解多少条，默认 1
+ * @param options 架构/字节序
+ */
+export declare function disassemble(code: Buffer, address: bigint, maxInstructions?: number, options?: DisassembleOptions): DisassembledInstruction[];
+/** 反汇编一条指令 */
+export declare function disassembleOne(code: Buffer, address: bigint, options?: DisassembleOptions): DisassembledInstruction;
+/**
+ * 从目标进程读内存并反汇编一条。
+ *
+ * 读取长度按架构取：x86 最长指令 15 字节（读 16 留余量），
+ * ARM/ARM64 定长 4 字节（读 16 同样够用，且便于 Thumb 的 4 字节指令）。
+ */
+export declare function disassembleAt(readMemory: (address: bigint, size: number) => Buffer, address: bigint, options?: DisassembleOptions): DisassembledInstruction;
+/** 按架构取"对齐步长"（用于在解不出指令时安全推进） */
+export declare function alignmentOf(arch: AsmArchitecture): number;
+/** 把字节数组格式化成 `48 8B 05 10 20 30 40`（大写、空格分隔） */
+export declare function formatBytes(bytes: Buffer[] | Buffer): string;
+/**
+ * 格式化为 CE 风格的完整行：`地址 - 字节 - 操作码 参数`。
+ *
+ * 对齐 `disassembler.pas` 里 binutils 分支的写法。注意 CE 在字节与 ` - `
+ * 之间**多一个空格**（逐字节拼接时末尾留了空格），本函数保留这一细节。
+ */
+export declare function formatDisassembled(insn: DisassembledInstruction, options?: {
+    addressWidth?: number;
+    showAddress?: boolean;
+    showBytes?: boolean;
+}): string;
+/**
+ * 取出一条指令的**完整文本**（含前缀与后缀），可用于重新汇编。
+ *
+ * 为什么需要单独的函数：
+ *   - x86：CE 把 `rep`/`lock` 前缀单独存在 `prefix` 字段，
+ *     只用 `opcode + parameters` 会丢掉 `F3`/`F2`。
+ *   - ARM：条件码在助记符里，本模块已把它并回 `opcode`，
+ *     但 ARM64 的 `.eq` 后缀需要补上。
+ */
+export declare function instructionText(insn: DisassembledInstruction): string;
+/**
+ * 把 CE 风格的整行拆回各段（对齐 `disassembler.pas` 的 `splitDisassembledString`）。
+ */
+export declare function splitDisassembledString(disassembled: string): {
+    address: string;
+    bytes: string;
+    opcode: string;
+    parameters: string;
+};
+/**
+ * 计算跳转/调用的目标地址（非流程指令返回 null）。
+ *
+ * 覆盖形态：
+ *   - x86：`0x...`
+ *   - ARM：`#0x...`（Capstone 对 ARM 分支通常直接给绝对地址）
+ *   - ARM64：`0x...`
+ */
+export declare function branchTarget(insn: DisassembledInstruction): bigint | null;
+//# sourceMappingURL=disassembler.d.ts.map

package/dist/types/asm/disassembler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"disassembler.d.ts","sourceRoot":"","sources":["../../../src/asm/disassembler.ts"],"names":[],"mappings":"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"}

package/dist/types/backend/dbk-backend.d.ts

@@ -0,0 +1,353 @@
+/**
+ * DBK 内核驱动后端 —— 通过 CE 自己的 DBK 驱动 ioctl 读写受保护进程内存。
+ *
+ * ## 为什么需要它
+ *
+ * `SelfBackend` 走用户态 `OpenProcess`/`ReadProcessMemory`，因此**受保护进程
+ * （PPL、反作弊、以更高权限运行的进程）读不到**。CE 解决这个问题的办法是加载
+ * 自己的内核驱动（DBK64），再用一组 ioctl 让内核代劳。
+ * 本后端就是那组 ioctl 的 Node 实现。
+ *
+ * ## 协议来源（全部逐行核对 CE 源码，不是猜的）
+ *
+ * 1. **ioctl 码**（`Cheat Engine/dbk32/DBK32functions.pas` 第 26–93 行）：
+ *
+ *    ```pascal
+ *    const METHOD_BUFFERED   = 0;
+ *    const FILE_DEVICE_UNKNOWN = $00000022;
+ *    const FILE_RW_ACCESS    = 3;
+ *    IOCTL_CE_READMEMORY  = (IOCTL_UNKNOWN_BASE shl 16) or ($0800 shl 2) or METHOD_BUFFERED or (FILE_RW_ACCESS shl 14);
+ *    IOCTL_CE_WRITEMEMORY = (IOCTL_UNKNOWN_BASE shl 16) or ($0801 shl 2) or ...
+ *    ```
+ *
+ * 2. **读内存的调用形态**（`ReadProcessMemory64_Internal`，第 1523–1584 行）：
+ *
+ *    ```pascal
+ *    type TInputstruct = packed record
+ *      processid: uint64;
+ *      startaddress: uint64;
+ *      bytestoread: word;
+ *    end;
+ *    ...
+ *    input.processid := processid;
+ *    input.bytestoread := toread;
+ *    input.startaddress := mempointer;
+ *    deviceiocontrol(hdevice, cc, @input, sizeof(input), pointer(bufpointer), toread, br, nil)
+ *    ```
+ *
+ *    注意 `packed record` —— **没有对齐填充**，所以输入是 8+8+2 = **18 字节**。
+ *    输出直接写到调用方缓冲区。
+ *
+ * 3. **写内存的调用形态**（第 1620–1686 行）：
+ *
+ *    ```pascal
+ *    input: TInputstruct absolute ao[0];   // 512 字节的固定缓冲
+ *    zeromemory(@ao[0], 512);
+ *    input.bytestowrite := towrite;
+ *    input.startaddress := mempointer;
+ *    copymemory(@ao[sizeof(tinputstruct)], bufpointer2, towrite);   // 数据紧跟头部
+ *    deviceiocontrol(hdevice, cc, @ao[0], 512, @ao[0], 512, br, nil);  // 同一块缓冲 in/out
+ *    ```
+ *
+ *    单次最多写 `512 - sizeof(TInputstruct)` 字节。
+ *
+ * 4. **设备名**：`CreateFileW('\\.\' + servicename, ...)`（第 3436 行），
+ *    而 `servicename` 默认是 `'CEDRIVER73'`（第 3194 行），
+ *    也可被 CE 目录下的 `driver.dat` / `driver64.dat` 覆盖
+ *    （第 3217–3225 行按行读入）。因此设备名**不能写死**，本模块按
+ *    `driver.dat` → 默认值 → 常见候选的顺序探测。
+ *
+ * ## 必须说明的风险（诚实部分）
+ *
+ * **本后端的 ioctl 结构布局无法在没有管理员权限的机器上验证。**
+ * 原因是：只有内核驱动真正加载后 `\\.\CEDRIVER73` 才存在，而加载驱动需要管理员。
+ * 因此：
+ *   - `IOCTL` 码与输入结构是**按源码逐行实现**的，不是猜测；
+ *   - 但"驱动侧实际期待的结构布局"只能靠**加载后实测**确认；
+ *   - 所以本模块提供 `probe()`：它用 `IOCTL_CE_GETVERSION`（一个参数最少的 ioctl）
+ *     验证设备是否真的响应，并如实报告结果，而不是假装能用。
+ *
+ * @module node-cheat-engine/backend/dbk-backend
+ */
+import { type BackendCapabilities, type BackendModuleInfo, type BackendProcessHandle, type BackendProcessInfo, type BackendRegion, type BackendRegionFilter, type MemoryBackend } from './types';
+/**
+ * 本后端用到的 ioctl（功能号来自 `DBK32functions.pas` 的常量定义）。
+ *
+ * 值可以直接算出来校验：`0x22 << 16 = 0x220000`，`access << 14 = 0xC000`，
+ * 所以 READMEMORY（func 0）= `0x220000 | 0 | 0 | 0xC000` = **`0x22C000`**。
+ */
+export declare const DBK_IOCTL: Readonly<{
+    READ_MEMORY: number;
+    WRITE_MEMORY: number;
+    OPEN_PROCESS: number;
+    QUERY_VIRTUAL_MEMORY: number;
+    TEST: number;
+    /** `IOCTL_CE_GETVERSION`：功能号 0x16，参数最少，适合当"驱动是否活着"的探针 */
+    GET_VERSION: number;
+    /** `IOCTL_CE_MAKEWRITABLE`：功能号 0x19，把只读页改成可写 */
+    MAKE_WRITABLE: number;
+    /** `IOCTL_CE_ALLOCATEMEM`：功能号 0x1F */
+    ALLOCATE_MEM: number;
+    /** `IOCTL_CE_SUSPENDPROCESS` / `RESUMEPROCESS`：功能号 0x24 / 0x25 */
+    SUSPEND_PROCESS: number;
+    RESUME_PROCESS: number;
+}>;
+/** 读内存输入结构的大小：`processid(8) + startaddress(8) + bytestoread(2)`。 */
+export declare const DBK_READ_INPUT_SIZE = 18;
+/** 写内存输入结构的大小：`processid(8) + startaddress(8) + bytestowrite(2)`。 */
+export declare const DBK_WRITE_INPUT_SIZE = 18;
+/** 写内存用的固定缓冲区总大小（CE 源码里写死 512）。 */
+export declare const DBK_WRITE_BUFFER_SIZE = 512;
+/** 单次写入能携带的最大数据量。 */
+export declare const DBK_MAX_WRITE_PAYLOAD: number;
+/** 读内存单次请求上限（CE 按 4096 分块）。 */
+export declare const DBK_MAX_READ_CHUNK = 4096;
+/**
+ * 分配内存输入结构的大小。
+ *
+ * CE 源码（`DBK32functions.pas:2217-2223`）：
+ * ```pascal
+ * x: record
+ *   processid: uint64;
+ *   baseaddress: uint64;
+ *   size: uint64;
+ *   AllocationType: uint64;
+ *   Protect: uint64;
+ * end;
+ * ```
+ * 5 × uint64 = **40 字节**。
+ *
+ * ⚠️ 与读/写不同，这个记录**没有** `packed` 关键字 —— 但 5 个 uint64 本来
+ * 就是 8 字节对齐的，所以 packed 与否大小相同（40），无需纠结。
+ */
+export declare const DBK_ALLOC_INPUT_SIZE = 40;
+/**
+ * 打包「读内存」的输入结构。
+ *
+ * `packed record` 语义：**没有对齐填充**，所以是紧凑的 18 字节。
+ * 这一点很关键 —— 若按自然对齐会变成 24 字节，驱动读到的 `bytestoread` 位置就错了。
+ *
+ * @param pid 目标进程 id（CE 用 uint64 存）
+ * @param address 起始地址
+ * @param bytesToRead 要读的字节数（word，最大 65535）
+ * @returns 18 字节的输入缓冲
+ */
+export declare function packReadInput(pid: number, address: bigint, bytesToRead: number): Buffer;
+/**
+ * 打包「写内存」的输入缓冲（512 字节固定大小，数据紧跟头部）。
+ *
+ * 与读不同，写是**同一块 512 字节缓冲同时当 in/out**：
+ *   - 前 18 字节是 `{ processid, startaddress, bytestowrite }`；
+ *   - 从第 18 字节起是要写的数据；
+ *   - 调用时 in/out 都传这块缓冲。
+ *
+ * @param pid 目标进程 id
+ * @param address 起始地址
+ * @param data 要写入的数据（长度不得超过 `DBK_MAX_WRITE_PAYLOAD`）
+ * @returns 512 字节的缓冲区
+ */
+export declare function packWriteBuffer(pid: number, address: bigint, data: Buffer): Buffer;
+/**
+ * 打包「分配内存」的输入缓冲（40 字节，5 个 uint64）。
+ *
+ * 驱动侧（`IOPLDispatcher.c` 的 `IOCTL_CE_ALLOCATEMEM` 分支）会
+ * `KeAttachProcess` 到目标进程再调 `ZwAllocateVirtualMemory`，
+ * 并**把结果地址写回同一块 SystemBuffer 的前 8 字节**：
+ *
+ * ```c
+ * *(PUINT64)Irp->AssociatedIrp.SystemBuffer = 0;
+ * *(PUINT_PTR)Irp->AssociatedIrp.SystemBuffer = (UINT_PTR)BaseAddress;
+ * ```
+ *
+ * 所以调用方必须**用同一块缓冲同时作为 in 与 out**，再从偏移 0 读返回值。
+ */
+export declare function packAllocInput(pid: number, baseAddress: bigint, size: bigint, allocationType: bigint, protect: bigint): Buffer;
+/** 从驱动写回的缓冲里读出分配到的地址（偏移 0 的 uint64）。 */
+export declare function readAllocResult(buffer: Buffer): bigint;
+/** 默认设备名（`DBK32functions.pas` 第 3194 行的出厂值）。 */
+export declare const DEFAULT_DBK_SERVICE_NAME = "CEDRIVER73";
+/**
+ * 从 CE 目录的 `driver.dat` / `driver64.dat` 读取真实服务名。
+ *
+ * 文件格式（`DBK32functions.pas` 第 3217–3225 行，按行读）：
+ *   ```
+ *   第 1 行：servicename
+ *   第 2 行：processeventname
+ *   第 3 行：threadeventname
+ *   第 4 行：sysfile
+ *   ...
+ *   ```
+ * 只有第 1 行与本后端相关。
+ *
+ * @param ceDir Cheat Engine 安装目录（可选；给了才去读）
+ * @returns 服务名，读不到返回 null
+ */
+export declare function readServiceNameFromDriverDat(ceDir: string | undefined): string | null;
+/**
+ * 解析要用的设备路径。
+ *
+ * 顺序：显式配置 → `driver.dat` → 默认 `CEDRIVER73`。
+ *
+ * @param options.serviceName 显式服务名
+ * @param options.cheatEngineDir CE 安装目录（用于读 driver.dat）
+ * @returns `\\.\<服务名>`
+ */
+export declare function resolveDevicePath(options?: {
+    serviceName?: string;
+    cheatEngineDir?: string;
+}): string;
+export interface DbkBackendOptions {
+    /** 显式服务名（不加 `\\.\` 前缀也可）。默认按 driver.dat → CEDRIVER73 解析。 */
+    serviceName?: string;
+    /** Cheat Engine 安装目录（用于读 driver.dat 拿真实服务名）。 */
+    cheatEngineDir?: string;
+    /**
+     * 允许在驱动不可用时**回退**到用户态实现（`SelfBackend`）。
+     * 默认 `false`：本后端的语义就是"走驱动"，静默回退会让人误以为已经绕过了保护。
+     */
+    fallbackToSelf?: boolean;
+    /** 设备已打开的句柄（测试注入用；给了一般不该再让本类自己开） */
+    deviceHandle?: unknown;
+}
+/** 设备不可用（未加载驱动 / 权限不足）时抛出的错误。 */
+export declare class DbkDeviceError extends Error {
+    readonly devicePath: string;
+    readonly win32Code?: number | undefined;
+    constructor(message: string, devicePath: string, win32Code?: number | undefined);
+}
+/**
+ * 通过 CE 的 DBK 内核驱动读写目标进程内存。
+ *
+ * ## 与其他后端的关系
+ *
+ * - 进程/模块/线程枚举、分配、改保护这些**不需要内核**的操作，直接委托给
+ *   内部的 `SelfBackend`（避免重复实现，也避免为这些操作引入未验证的 ioctl）；
+ * - **只有内存读写走驱动** —— 这正是受保护进程唯一需要内核的地方，
+ *   也是风险最高、最需要精确复刻协议的部分。
+ *
+ * ## 为什么同步
+ *
+ * 驱动 ioctl 是同步的系统调用（`DeviceIoControl` 直接返回），
+ * 因此本后端声明 `capabilities.sync === true`，扫描/指针扫描/AutoAssembler
+ * 都能正常使用（它们内部要求同步后端）。
+ */
+export declare class DbkBackend implements MemoryBackend {
+    private readonly options;
+    readonly name = "dbk";
+    readonly capabilities: BackendCapabilities;
+    private readonly self;
+    private device;
+    private devicePath;
+    private versionCache;
+    constructor(options?: DbkBackendOptions);
+    /** 当前使用的设备路径（诊断用）。 */
+    get resolvedDevicePath(): string;
+    /** 驱动是否已打开。 */
+    get isDeviceOpen(): boolean;
+    /**
+     * 打开驱动设备。**需要驱动已加载**（加载驱动需要管理员权限，见 kernel-driver.js）。
+     *
+     * @throws DbkDeviceError 打开失败（未加载驱动 / 权限不足 / 名字不对）
+     */
+    openDevice(): void;
+    /** 关闭设备句柄。 */
+    closeDevice(): void;
+    /**
+     * 拿驱动版本，用来确认「设备真的在工作」。
+     *
+     * 这是**最有价值的自检**：它用参数最少的 ioctl，
+     * 能区分「设备打不开」与「设备打开了但协议不对」这两种完全不同的故障。
+     *
+     * @returns 版本字符串；调用失败返回 null
+     */
+    queryVersion(): string | null;
+    /**
+     * 一次性自检：设备能否打开、版本能否读到。
+     *
+     * 供工具输出使用 —— 让"驱动到底通没通"变成一个明确的结论，而不是靠猜。
+     */
+    probe(): {
+        devicePath: string;
+        opened: boolean;
+        version: string | null;
+        error: string | null;
+    };
+    /** 发一个 ioctl。in/out 可以是同一块 Buffer（METHOD_BUFFERED 允许）。 */
+    private ioctl;
+    listProcesses(): BackendProcessInfo[];
+    openProcess(pid: number): BackendProcessHandle;
+    closeProcess(handle: BackendProcessHandle): void;
+    queryModules(handle: BackendProcessHandle): BackendModuleInfo[];
+    queryThreads(handle: BackendProcessHandle): number[];
+    isWow64(handle: BackendProcessHandle): boolean;
+    queryRegions(handle: BackendProcessHandle, filter?: BackendRegionFilter): BackendRegion[];
+    /**
+     * 读内存 —— 通过 `IOCTL_CE_READMEMORY`。
+     *
+     * 按 CE 的做法**分块**（每块最多 4096 字节，且不跨页边界，
+     * 因为驱动侧按页处理）。读失败时返回已读到的部分，不抛错（与接口约定一致）。
+     */
+    readProcessMemory(handle: BackendProcessHandle, address: bigint, size: number): Buffer;
+    /**
+     * 写内存 —— 通过 `IOCTL_CE_WRITEMEMORY`。
+     *
+     * 按 CE 的做法分块：每块最多 `512 - 18 = 494` 字节，
+     * 且 512 字节缓冲**同时作为 in 与 out**。
+     *
+     * 失败**抛错**（写失败静默化会写坏目标，接口约定要求抛错）。
+     */
+    writeProcessMemory(_handle: BackendProcessHandle, address: bigint, data: Buffer, _fixProtection?: boolean): number;
+    /**
+     * 在目标进程内分配内存 —— 通过 `IOCTL_CE_ALLOCATEMEM`。
+     *
+     * 驱动会 `KeAttachProcess` 到目标进程后用 `ZwAllocateVirtualMemory` 分配，
+     * 因此**受保护进程也能分配**（这是用户态 `VirtualAllocEx` 做不到的）。
+     *
+     * @param size 请求大小（会被驱动按页向上取整）
+     * @param protect 保护属性，默认 `PAGE_EXECUTE_READWRITE`
+     * @param preferred 期望地址（`0n` 表示由系统选择），对应 `lpAddress`
+     * @returns 实际分配到的基址
+     */
+    allocate(handle: BackendProcessHandle, size: number, protect?: number, preferred?: bigint): bigint;
+    /**
+     * 改变内存保护属性。
+     *
+     * ## 为什么这里**不走驱动**
+     *
+     * CE 的驱动里确实有一个 `IOCTL_CE_MAKEWRITABLE`（功能号 `$0819`），但它
+     * **在 x64 驱动上是空的**（`DBKKernel/IOPLDispatcher.c:474-491`）：
+     *
+     * ```c
+     * case IOCTL_CE_MAKEWRITABLE:
+     * #ifdef AMD64
+     *     //untill I know how win64 handles paging, not implemented
+     * #else
+     *     ... MakeWritable(...)
+     * #endif
+     * ```
+     *
+     * 所以 64 位 Windows 上发这个 ioctl 只会得到「无效请求」。
+     * 而且它的输入结构里**没有 processid** —— 它是按调用者（驱动自己所在的
+     * 进程上下文）的页表改 PTE 的，本来也不适合"改另一个进程的保护"。
+     *
+     * 因此本方法**委托 `SelfBackend`（用户态 `VirtualProtectEx`）**，并明确告知这一点。
+     * 好消息是：**内存写入不需要先改保护** —— 驱动的写路径本身就绕过了页保护，
+     * 只读页照样能写。需要 `changeProtection` 的场景主要是为了「把页改成可执行」
+     * 或「让目标自己也能写」，那属于目标进程自身的权限，用户态调用是否成功取决于
+     * 当前进程对目标的权限（受保护进程仍会失败）。
+     *
+     * @returns 旧保护值（用户态 `VirtualProtectEx` 的返回值）
+     */
+    changeProtection(handle: BackendProcessHandle, address: bigint, size: number, newProtect: number): number;
+    /**
+     * 释放内存。
+     *
+     * 驱动**没有**提供释放 ioctl（`KernelFree` 释放的是驱动自己内核态分配的内存，
+     * 不是目标进程的）。因此这里委托用户态 `VirtualFreeEx`；
+     * 对受保护进程会失败 —— 那种情况下这块内存会一直留在目标进程里，
+     * 这是需要如实告诉调用方的限制。
+     */
+    free(handle: BackendProcessHandle, address: bigint): void;
+    dispose(): void;
+}
+//# sourceMappingURL=dbk-backend.d.ts.map

package/dist/types/backend/dbk-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dbk-backend.d.ts","sourceRoot":"","sources":["../../../src/backend/dbk-backend.ts"],"names":[],"mappings":"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"}