jsilnet 0.0.0-stage → 0.2.0

package/example/README.md

@@ -0,0 +1,22 @@
+# Runnable example
+
+This example builds a small managed assembly, inspects it with jsILNET, writes a
+byte-identical round trip, and edits an existing IL constant. The library itself
+does not require .NET; the .NET SDK is only used here to create the sample DLL.
+
+From the repository root, run:
+
+```sh
+dotnet build example/Sample.csproj -c Release
+node example/inspect.js example/bin/Release/net10.0/Sample.dll example/bin/Release/net10.0/Sample.roundtrip.dll
+node example/edit-constant.js example/bin/Release/net10.0/Sample.dll Answer 43 example/bin/Release/net10.0/Sample.edited.dll
+```
+
+`inspect.js` lists metadata and IL instructions, then optionally saves and
+reparses an unchanged output. `edit-constant.js` updates the `ldc.i4.s`
+instruction in the named method, saves the rewritten DLL, and reparses it to
+confirm the edit survived.
+
+To try the scripts with your own assembly, replace the sample DLL path with a
+managed `.dll` that matches jsILNET's supported input profile. Both scripts
+require Node.js 20 or later.

package/example/Sample.cs

@@ -0,0 +1,10 @@
+namespace JsILNET.Example;
+
+public static class Sample
+{
+    public static int Answer() => 42;
+
+    public static int Add(int left, int right) => left + right;
+
+    public static string Greeting() => "Hello from a managed assembly";
+}

package/example/Sample.csproj

@@ -0,0 +1,7 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+</Project>

package/example/edit-constant.js

@@ -0,0 +1,48 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { parseAssembly } from "jsilnet";
+
+const [inputPath, methodName, rawValue, outputPath, ...extraArgs] = process.argv.slice(2);
+const value = Number(rawValue);
+
+if (!inputPath || !methodName || !/^-?\d+$/.test(rawValue ?? "") ||
+    !Number.isInteger(value) || value < -128 || value > 127 ||
+    !outputPath || extraArgs.length > 0) {
+  console.error(
+    "Usage: node example/edit-constant.js <assembly.dll> <method-name> <signed-byte> <output.dll>"
+  );
+  process.exitCode = 1;
+} else {
+  if (resolve(inputPath) === resolve(outputPath)) {
+    throw new Error("Choose a separate output path so the input assembly is not overwritten");
+  }
+
+  const assembly = parseAssembly(new Uint8Array(await readFile(inputPath)));
+  const matches = assembly.methods.filter((method) => method.name === methodName);
+  if (matches.length !== 1) {
+    throw new Error(`Expected one method named ${methodName}, found ${matches.length}`);
+  }
+
+  const method = matches[0];
+  const instruction = assembly
+    .getInstructions(method.rid)
+    .find((item) => item.opcode.name === "ldc.i4.s");
+  if (!instruction) {
+    throw new Error(`Method ${methodName} has no ldc.i4.s instruction to edit`);
+  }
+
+  assembly.setInstructionOperand(method.rid, instruction.offset, value);
+  const output = assembly.toBuffer();
+  const reparsed = parseAssembly(output);
+  const updatedMethod = reparsed.methods.find((item) => item.rid === method.rid);
+  const updatedInstruction = reparsed
+    .getInstructions(updatedMethod.rid)
+    .find((item) => item.offset === instruction.offset);
+  if (updatedInstruction?.operand.value !== value) {
+    throw new Error("Edited constant did not survive serialization and reparsing");
+  }
+
+  await writeFile(outputPath, output);
+  console.log(`Changed ${methodName}'s ldc.i4.s constant to ${value}`);
+  console.log(`Wrote and reparsed ${outputPath}`);
+}

package/example/inspect.js

@@ -0,0 +1,37 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { parseAssembly } from "jsilnet";
+
+const [inputPath, outputPath, ...extraArgs] = process.argv.slice(2);
+
+if (!inputPath || extraArgs.length > 0) {
+  console.error("Usage: node example/inspect.js <assembly.dll> [roundtrip.dll]");
+  process.exitCode = 1;
+} else {
+  if (outputPath && resolve(inputPath) === resolve(outputPath)) {
+    throw new Error("Choose a separate output path so the input assembly is not overwritten");
+  }
+
+  const input = new Uint8Array(await readFile(inputPath));
+  const assembly = parseAssembly(input);
+
+  console.log(`Types: ${assembly.types.length}`);
+  console.log(`Methods: ${assembly.methods.length}`);
+  for (const method of assembly.methods.slice(0, 10)) {
+    const instructions = method.rva === 0 ? [] : assembly.getInstructions(method.rid);
+    console.log(`\n${method.name} (RID ${method.rid})`);
+    for (const instruction of instructions.slice(0, 12)) {
+      const offset = instruction.offset.toString(16).padStart(4, "0");
+      console.log(`  IL_${offset}: ${instruction.opcode.name}`);
+    }
+    if (instructions.length > 12) console.log("  ...");
+  }
+
+  if (outputPath) {
+    const output = assembly.toBuffer();
+    parseAssembly(output);
+    await writeFile(outputPath, output);
+    console.log(`\nWrote and reparsed ${outputPath}`);
+    console.log(`Byte-identical round trip: ${Buffer.compare(input, output) === 0}`);
+  }
+}

package/package.json

@@ -1,6 +1,61 @@
-{
-  "name": "jsilnet",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "jsilnet",
+  "version": "0.2.0",
+  "description": "Node.js and browser ECMA-335 / CLI assembly reader and writer",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Th3C0D3R/jsILNET.git"
+  },
+  "homepage": "https://github.com/Th3C0D3R/jsILNET#readme",
+  "bugs": {
+    "url": "https://github.com/Th3C0D3R/jsILNET/issues"
+  },
+  "keywords": [
+    "dotnet",
+    "ecma-335",
+    "cil",
+    "cli",
+    "pe",
+    "assembly",
+    "il",
+    "metadata",
+    "nodejs"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "types": "./src/index.d.ts",
+  "files": [
+    "src",
+    "dist/browser",
+    "example",
+    "REFERENCE.md"
+  ],
+  "exports": {
+    ".": "./src/index.js",
+    "./browser": {
+      "types": "./src/browser/index.d.ts",
+      "default": "./dist/browser/index.js"
+    }
+  },
+  "scripts": {
+    "test": "node --test",
+    "check": "node --check src/index.js",
+    "build:browser": "node scripts/build-browser.js",
+    "check:browser": "npm run build:browser && node scripts/check-browser-bundle.js",
+    "build:types": "tsc --allowJs --checkJs false --declaration --emitDeclarationOnly --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir src/types src/index.js",
+    "precheck:types": "npm run build:types",
+    "check:types": "tsc --noEmit --strict --skipLibCheck --module NodeNext --moduleResolution NodeNext type-tests/core-api.ts type-tests/browser-api.ts && node scripts/check-type-coverage.js",
+    "prepublishOnly": "npm test && npm run check && npm run check:types && npm run check:browser"
+  },
+  "devDependencies": {
+    "esbuild": "^0.28.2",
+    "typescript": "^5.8.3"
+  },
+  "dependencies": {
+    "fflate": "^0.8.3",
+    "node-forge": "^1.4.3"
+  }
+}

package/src/assembly/instruction-editing.js

@@ -0,0 +1,165 @@
+import { FormatError } from "../binary/errors.js";
+import { encodeOpcode } from "../il/instructions.js";
+import { listOpcodes } from "../il/opcodes.js";
+import {
+  insertInstruction,
+  layoutStructuralState,
+  removeInstruction,
+  updateStructuralOperand
+} from "../il/rewrite.js";
+import { createOperandPatches } from "../writer/patch.js";
+import { metadataTableNames } from "../metadata/tables.js";
+
+export function createInstructionEditor(assembly, hooks) {
+  return {
+    setInstructionOperand(methodRid, instructionOffset, value) {
+      hooks.ensureEditable();
+      const body = assembly.getMethodBody(methodRid);
+      if (!body) throw new FormatError("Method has no CIL body");
+      const instruction = body.instructions.find((candidate) => candidate.offset === instructionOffset);
+      if (!instruction) throw new RangeError(`No instruction begins at IL_${instructionOffset.toString(16)}`);
+      if (!instruction.operand) throw new TypeError("Instruction has no operand");
+
+      if (instruction.operand.kind === "branch") {
+        hooks.validateBranchTarget(body, value);
+      } else if (instruction.operand.kind === "switch") {
+        if (!Array.isArray(value)) throw new TypeError("Switch operand must be an array of IL target offsets");
+        for (const target of value) hooks.validateBranchTarget(body, target);
+      } else if (instruction.opcode.name === "ldstr") {
+        if (!Number.isInteger(value) || (value >>> 24) !== 0x70) {
+          throw new TypeError("ldstr operand must be a 0x70-prefixed user-string token");
+        }
+        assembly.heaps.getUserString(value);
+      } else if (instruction.operand.kind === "token") {
+        if (!Number.isInteger(value) || value < 0 || value > 0xffffffff) {
+          throw new RangeError("Metadata token must be an unsigned 32-bit integer");
+        }
+        const table = value >>> 24;
+        const rid = value & 0x00ffffff;
+        if (!hooks.allowedTokenTables(instruction.opcode.name).includes(table)) {
+          throw new FormatError(`Metadata table ${table} is not valid for ${instruction.opcode.name}`);
+        }
+        if (rid === 0 || rid > (assembly.tables.counts[table] ?? 0)) {
+          throw new RangeError(
+            `${instruction.opcode.name} references missing ${metadataTableNames[table]} row ${rid}`
+          );
+        }
+        hooks.validateInstructionGenericContext(assembly, methodRid, instruction, value);
+      }
+
+      if (instruction.operand.kind === "branch" && instruction.operand.targetOffset === value) return assembly;
+      if (instruction.operand.kind === "switch" &&
+          instruction.operand.targetOffsets.length === value.length &&
+          instruction.operand.targetOffsets.every((target, index) => target === value[index])) return assembly;
+      if (instruction.operand.kind !== "branch" && instruction.operand.kind !== "switch" &&
+          instruction.operand.value === value) return assembly;
+
+      if (assembly._structuralBodies.has(methodRid) || assembly._addedMethodBodies.has(methodRid)) {
+        const state = hooks.createStructuralState(methodRid);
+        const editableInstruction = state.instructions.find((candidate) => candidate.offset === instructionOffset);
+        updateStructuralOperand(state, editableInstruction, value);
+        hooks.commitStructuralState(methodRid, state);
+      } else {
+        const patches = createOperandPatches(instruction, value);
+        for (const patch of patches) assembly._patches.push(patch);
+        instruction.operand = instruction.operand.kind === "branch"
+          ? { kind: "branch", targetOffset: value }
+          : instruction.operand.kind === "switch"
+            ? { kind: "switch", targetOffsets: [...value] }
+            : { ...instruction.operand, value };
+      }
+      return assembly;
+    },
+
+    setInstructionOpcode(methodRid, instructionOffset, opcodeNameOrCode) {
+      hooks.ensureEditable();
+      const body = assembly.getMethodBody(methodRid);
+      if (!body) throw new FormatError("Method has no CIL body");
+      const instruction = body.instructions.find((candidate) => candidate.offset === instructionOffset);
+      if (!instruction) throw new RangeError(`No instruction begins at IL_${instructionOffset.toString(16)}`);
+      const opcode = listOpcodes().find((candidate) =>
+        candidate.name === opcodeNameOrCode || candidate.code === opcodeNameOrCode
+      );
+      if (!opcode) throw new RangeError(`Unknown CIL opcode ${opcodeNameOrCode}`);
+      const encoded = encodeOpcode(opcode);
+      if (encoded.length !== instruction.opcodeSize || opcode.operand !== instruction.opcode.operand) {
+        throw new FormatError("Opcode edit must preserve the opcode and operand widths");
+      }
+      if (opcode.code === instruction.opcode.code) return assembly;
+      if (instruction.operand?.kind === "token") {
+        if (opcode.name !== "ldstr") {
+          const table = instruction.operand.value >>> 24;
+          const rid = instruction.operand.value & 0x00ffffff;
+          if (!hooks.allowedTokenTables(opcode.name).includes(table)) {
+            throw new FormatError(`Metadata table ${table} is not valid for ${opcode.name}`);
+          }
+          if (rid === 0 || rid > (assembly.tables.counts[table] ?? 0)) {
+            throw new RangeError(
+              `${opcode.name} references missing ${metadataTableNames[table]} row ${rid}`
+            );
+          }
+          hooks.validateInstructionGenericContext(
+            assembly, methodRid, { ...instruction, opcode }, instruction.operand.value
+          );
+        }
+      }
+      if (assembly._structuralBodies.has(methodRid) || assembly._addedMethodBodies.has(methodRid)) {
+        const state = hooks.createStructuralState(methodRid);
+        const editableInstruction = state.instructions.find((candidate) => candidate.offset === instructionOffset);
+        editableInstruction.opcode = opcode;
+        layoutStructuralState(state);
+        hooks.commitStructuralState(methodRid, state);
+      } else {
+        assembly._patches.push({ offset: instruction.opcodeOffset, bytes: encoded });
+        instruction.opcode = opcode;
+      }
+      return assembly;
+    },
+
+    insertInstruction(methodRid, beforeOffset, opcodeNameOrCode, operand) {
+      hooks.ensureEditable();
+      const opcode = listOpcodes().find((candidate) =>
+        candidate.name === opcodeNameOrCode || candidate.code === opcodeNameOrCode
+      );
+      if (!opcode) throw new RangeError(`Unknown CIL opcode ${opcodeNameOrCode}`);
+      const state = hooks.createStructuralState(methodRid);
+      const instruction = insertInstruction(state, beforeOffset, opcode, operand);
+      if (instruction.operand?.kind === "token" && opcode.name !== "ldstr") {
+        const token = instruction.operand.value;
+        const table = token >>> 24;
+        const rid = token & 0x00ffffff;
+        if (!hooks.allowedTokenTables(opcode.name).includes(table)) {
+          throw new FormatError(`Metadata table ${table} is not valid for ${opcode.name}`);
+        }
+        if (rid === 0 || rid > (assembly.tables.counts[table] ?? 0)) {
+          throw new RangeError(
+            `${opcode.name} references missing ${metadataTableNames[table]} row ${rid}`
+          );
+        }
+        hooks.validateInstructionGenericContext(assembly, methodRid, instruction, token);
+      }
+      hooks.commitStructuralState(methodRid, state);
+      return instruction;
+    },
+
+    removeInstruction(methodRid, instructionOffset) {
+      hooks.ensureEditable();
+      const state = hooks.createStructuralState(methodRid);
+      const instruction = removeInstruction(state, instructionOffset);
+      hooks.commitStructuralState(methodRid, state);
+      return instruction;
+    },
+
+    setMethodMaxStack(methodRid, maxStack) {
+      hooks.ensureEditable();
+      if (!Number.isInteger(maxStack) || maxStack < 0 || maxStack > 0xffff) {
+        throw new RangeError("maxStack must be an unsigned 16-bit integer");
+      }
+      const state = hooks.createStructuralState(methodRid);
+      state.maxStack = maxStack;
+      layoutStructuralState(state);
+      hooks.commitStructuralState(methodRid, state);
+      return assembly;
+    }
+  };
+}