jsilnet 0.1.0 → 0.2.0

package/README.md

@@ -1,11 +1,12 @@
 # jsILNET
 
-`jsILNET` is a Node.js library with no third-party runtime dependencies for inspecting and rewriting .NET assemblies. It reads PE/CLI formats directly and does not require a .NET runtime.
+`jsILNET` is a JavaScript library for inspecting and rewriting .NET assemblies. It reads PE/CLI formats directly and does not require a .NET runtime. The package provides a synchronous Node.js API and a Promise-based browser API backed by a Web Worker.
 
 ## Requirements
 
 - Node.js 20 or later
 - ECMAScript modules
+- Web Workers for the browser entry point (`jsilnet/browser`)
 
 ## Install
 
@@ -53,15 +54,32 @@ await writeFile("output.dll", assembly.toBuffer());
 
 Edits are validated against the supported input profile; unsupported or unsafe rewrites fail explicitly. See the [Current capabilities](REFERENCE.md#current-capabilities) and [API surface](REFERENCE.md#api-surface) references for supported features, APIs, and limitations.
 
+## Browser usage
 
-## Live Demo
-A [Live-Demo](https://jsilnet-live-demo.vercel.app/) is available. 
+In a browser application using a package-aware bundler with module Worker support, import the separate browser entry point:
 
-Restricted to a 3 MiB .NET DLL or EXE with a `ldc-i4.s` instruction.
+```js
+import { parseAssembly } from "jsilnet/browser";
+
+async function roundTripFile(file) {
+  const assembly = await parseAssembly(file); // File and Blob inputs are supported.
+  try {
+    const state = await assembly.getState();
+    console.log(`Assembly modified: ${state.modified}`);
+    const bytes = await assembly.serialize();
+    return new Blob([bytes], { type: "application/octet-stream" });
+  } finally {
+    assembly.dispose();
+  }
+}
+```
 
-The Example Project inside `example/` produces such DLL.
+The browser API is Promise-based and runs parsing, editing, and serialization in a Web Worker; the default Node.js entry point remains synchronous. Assembly methods must be awaited, `getState()` returns a snapshot, and `serialize()` returns a `Uint8Array`. Resolver callbacks such as `resolveEnum` and `resolveType` may be synchronous or asynchronous. Calling `dispose()` terminates the Worker and releases its Assembly state.
 
-Source and documentation of this Demo-App is inside `live-demo/`
+`parseAssembly` also accepts `Uint8Array` and `ArrayBuffer`. For full-buffer byte inputs, `{ transferInput: true }` transfers the input to the Worker and detaches it from the caller; subarray views are copied.
+
+## Live Demo
+The browser-only demo in `live-demo/` inspects and patches .NET assemblies without uploading them. Build it with `npm run build --prefix live-demo`, then serve `live-demo/dist/` from any static web host. See [`live-demo/README.md`](live-demo/README.md) for local preview instructions.
 
 ## Documentation
 
@@ -76,4 +94,5 @@ Source and documentation of this Demo-App is inside `live-demo/`
 npm install
 npm test
 npm run check
+npm run check:browser
 ```

package/REFERENCE.md

@@ -64,6 +64,10 @@ This document records detailed feature coverage, exported APIs, behavioral limit
 
 The package exports `parseAssembly` and `Assembly`, plus lower-level PE, metadata, heap, signature, binary-reader, coded-index, CIL-instruction, and method-body parsing utilities.
 
+The `jsilnet/browser` package subpath exports a Promise-based `parseAssembly` and `Assembly` proxy. It accepts a `Blob` for worker-side file reading, or a `Uint8Array`/`ArrayBuffer`; for a full-buffer `Uint8Array` or `ArrayBuffer`, `transferInput: true` transfers ownership and detaches the input from the caller. Assembly operations execute in a dedicated module Worker; `getState()` retrieves a structured-cloneable snapshot, `serialize()` returns a `Uint8Array`, and `dispose()` terminates the Worker. `callUtility(name, ...args)` runs an exported standalone utility in a Worker. Browser support is not yet fully at parity: callback-valued `resolveEnum`/`resolveType` options cannot be structured-cloned, and standalone utility results omit function-valued properties other than the restored `parsePE().rvaToOffset` mapping.
+
+The package declarations cover all package exports and public `Assembly` methods. Run `npm run check:types` to regenerate the declarations, compile a consumer type check, and verify API coverage.
+
 An `Assembly` exposes parsed PE/CLI metadata, `module`, `types`, `typeRefs`, `typeSpecs`, `methods`, `memberRefs`, `moduleRefs`, `methodSpecs`, `genericParams`, `genericParamConstraints`, `customAttributes`, `assemblyRefs`, `files`, and `resources`. Type records include their fields, methods, events, properties, and generic parameters; method records include their parameter rows. Method bodies are loaded with `getMethodBody` or `getInstructions`. Editing methods include `setInstructionOperand`, `setInstructionOpcode`, `insertInstruction`, `removeInstruction`, `setMethodMaxStack`, `replaceMethodSignature`, `replaceCodeViewPath`, `replaceModule`, `replaceField`, `replaceFieldSignature`, `addField`, `insertField`, `removeField`, `addFieldRva`, `replaceFieldRva`, `removeFieldRva`, `addMethod`, `insertMethod`, `addConstant`, `replaceConstant`, `addParam`, `insertParam`, `replaceParam`, `removeParam`, `addProperty`, `insertProperty`, `removeProperty`, `addEvent`, `insertEvent`, `removeEvent`, `addMethodSemantics`, `replaceMethodSemantics`, `removeMethodSemantics`, `replaceAssemblyIdentity`, `signStrongName`, `replaceStrongNamePublicKey`, `verifyStrongNameSignature`, `parseCustomAttribute`, `replaceCustomAttribute`, `addCustomAttribute`, `removeCustomAttribute`, `addManifestResource`, `replaceManifestResource`, `replaceLinkedResource`, `removeManifestResource`, `addTypeRef`, `insertTypeRefSorted`, `removeTypeRef`, `addModuleRef`, `replaceModuleRef`, `removeModuleRef`, `addTypeSpec`, `replaceTypeSpecSignature`, `addStandAloneSig`, `insertStandAloneSig`, `replaceStandAloneSig`, `removeStandAloneSig`, `addMemberRef`, `insertMemberRefSorted`, `addMethodSpec`, `replaceMethodSpecInstantiation`, `insertMethodSpecSorted`, `removeMethodSpec`, `addGenericParam`, `replaceGenericParam`, `removeGenericParam`, `addGenericParamConstraint`, `insertGenericParamConstraint`, `replaceGenericParamConstraint`, `removeGenericParamConstraint`, `addAssemblyRef`, `insertAssemblyRef`, `removeAssemblyRef`, `addAssemblyProcessor`, `replaceAssemblyProcessor`, `removeAssemblyProcessor`, `addAssemblyOS`, `replaceAssemblyOS`, `removeAssemblyOS`, `addAssemblyRefProcessor`, `replaceAssemblyRefProcessor`, `removeAssemblyRefProcessor`, `addAssemblyRefOS`, `replaceAssemblyRefOS`, `removeAssemblyRefOS`, `addFile`, `insertFile`, `removeFile`, and `addUserString`; sorted insertion and removal methods return a token map when existing token RIDs change. `addConstant` and `replaceConstant` accept the ECMA element type and its raw encoded value bytes; adding requires an existing Field, Param, or Property parent and rejects duplicate parents or an append that violates declared table ordering. `replaceModule({ name, generation })` updates the module name or unsigned 16-bit generation while preserving its MVID. `signStrongName(privateKey)` accepts an RSA PEM or Node.js private `KeyObject` and signs during serialization; the key must match the assembly's existing full public key, and a correctly sized signature slot is reused or allocated in a new PE section. `replaceStrongNamePublicKey(privateKey, { hashAlgorithm })` explicitly changes the full Assembly public key/hash ID to match the supplied private key, then requests signing; the Assembly name, version, and culture remain unchanged. `replaceAssemblyIdentity({ name, culture, version })` changes those three manifest identity fields. `verifyStrongNameSignature()` verifies signatures using the embedded RSA public key. Signing supports the standard 16-slot PE optional header when 15 or 16 data directories are declared, and SHA-1, SHA-256, SHA-384, or SHA-512 assembly hash IDs; other directory-count profiles are refused. Custom-attribute and PermissionSet parse/edit methods accept `resolveEnum(name)` and `resolveType(name, context)` options (or properties on their input objects); a type resolver returns `{ assembly, rid }` for a TypeDef from another parsed assembly and can enable external enum, constructor, inheritance, and named-member validation. `addCustomAttribute` appends only when the declared parent ordering remains valid. `replaceLinkedResource(rid, data)` supports resources whose `Implementation` points directly to a File row, updates that File row's hash using the containing Assembly hash algorithm, and leaves the new external payload available as `resources[rid - 1].data`; it does not write the external file. `insertGenericParamConstraint({ ownerRid, constraint })` inserts into an already Owner-ordered GenericParamConstraint table and returns `{ rid, tokenMap }`. `Resource, File, TypeRef, ModuleRef, AssemblyRef, StandAloneSig, MethodSpec, GenericParamConstraint, GenericParam, Property, Event, and CustomAttribute removal rejects rows with live references and remaps surviving references. `serialize` returns a `Uint8Array`, and `toBuffer` returns a Node.js `Buffer`.
 Sorted row insertions are available through `insertConstant`, `insertFieldMarshal`, `insertClassLayout`, `insertFieldLayout`, `insertFieldRva`, `insertImplMap`, `insertMethodSemantics`, `insertMethodImpl`, `insertNestedClass`, `insertGenericParam`, `insertDeclSecurity`, `insertInterfaceImplementation`, `insertCustomAttribute`, and the TypeRef/MemberRef/MethodSpec insertion APIs. Token-row removals for Constant, FieldMarshal, FieldRVA, ClassLayout, FieldLayout, DeclSecurity, MethodSemantics, MethodImpl, ImplMap, and NestedClass reject live references, remap surviving token references, and return a token map; edits that shift tokens are refused with debug data, opaque metadata streams, or incompatible method-body edits.
 `insertFile({ beforeRid, name, flags, hashValue })` inserts at a 1-based File row position (use `files.length + 1` to append), remaps File references, and returns `{ token, tokenMap }`.

package/dist/browser/index.js

@@ -0,0 +1,345 @@
+// src/binary/errors.js
+var FormatError = class extends Error {
+  constructor(message, { offset, context } = {}) {
+    const location = Number.isInteger(offset) ? ` at file offset 0x${offset.toString(16)}` : "";
+    const scope = context ? ` (${context})` : "";
+    super(`${message}${location}${scope}`);
+    this.name = "FormatError";
+    this.offset = offset;
+    this.context = context;
+  }
+};
+var UnsupportedFormatError = class extends FormatError {
+  constructor(message, options = {}) {
+    super(message, options);
+    this.name = "UnsupportedFormatError";
+  }
+};
+
+// src/browser/index.js
+var nextRequestId = 0;
+function createWorker(workerFactory) {
+  if (workerFactory) return workerFactory();
+  if (typeof Worker === "undefined") {
+    throw new Error("jsILNET browser APIs require Web Worker support");
+  }
+  return new Worker(new URL("./worker.js", import.meta.url), { type: "module" });
+}
+function normalizeInput(input, transferInput) {
+  if (typeof Blob !== "undefined" && input instanceof Blob) {
+    return { input, transfer: [] };
+  }
+  if (input instanceof ArrayBuffer) {
+    const buffer = transferInput ? input : input.slice(0);
+    return { input: buffer, transfer: [buffer] };
+  }
+  if (input instanceof Uint8Array) {
+    if (transferInput && input.buffer instanceof ArrayBuffer && input.byteOffset === 0 && input.byteLength === input.buffer.byteLength) {
+      return { input: input.buffer, transfer: [input.buffer] };
+    }
+    const bytes = Uint8Array.from(input);
+    return { input: bytes.buffer, transfer: [bytes.buffer] };
+  }
+  throw new TypeError("Assembly input must be a Uint8Array, ArrayBuffer, or Blob");
+}
+function encodeCallbacks(value, callbacks, seen = /* @__PURE__ */ new WeakMap()) {
+  if (typeof value === "function") {
+    const id = callbacks.size + 1;
+    callbacks.set(id, value);
+    return { __jsilnetCallback: id };
+  }
+  if (value === null || typeof value !== "object") return value;
+  if (seen.has(value)) return seen.get(value);
+  if (typeof Blob !== "undefined" && value instanceof Blob) return value;
+  if (value instanceof ArrayBuffer || ArrayBuffer.isView(value)) return value;
+  const output = value instanceof Map ? /* @__PURE__ */ new Map() : value instanceof Set ? /* @__PURE__ */ new Set() : Array.isArray(value) ? [] : {};
+  seen.set(value, output);
+  if (value instanceof Map) {
+    for (const [key, item] of value) {
+      output.set(encodeCallbacks(key, callbacks, seen), encodeCallbacks(item, callbacks, seen));
+    }
+  } else if (value instanceof Set) {
+    for (const item of value) output.add(encodeCallbacks(item, callbacks, seen));
+  } else if (Array.isArray(value)) {
+    for (const item of value) output.push(encodeCallbacks(item, callbacks, seen));
+  } else {
+    for (const key of Object.keys(value)) {
+      output[key] = encodeCallbacks(value[key], callbacks, seen);
+    }
+  }
+  return output;
+}
+function decodeAssemblyReferences(value, assembly, seen = /* @__PURE__ */ new WeakMap()) {
+  if (value === null || typeof value !== "object") return value;
+  if (value.__jsilnetAssembly === true) return assembly;
+  if (seen.has(value)) return seen.get(value);
+  if (value instanceof ArrayBuffer || ArrayBuffer.isView(value)) return value;
+  const output = value instanceof Map ? /* @__PURE__ */ new Map() : value instanceof Set ? /* @__PURE__ */ new Set() : Array.isArray(value) ? [] : {};
+  seen.set(value, output);
+  if (value instanceof Map) {
+    for (const [key, item] of value) {
+      output.set(
+        decodeAssemblyReferences(key, assembly, seen),
+        decodeAssemblyReferences(item, assembly, seen)
+      );
+    }
+  } else if (value instanceof Set) {
+    for (const item of value) output.add(decodeAssemblyReferences(item, assembly, seen));
+  } else if (Array.isArray(value)) {
+    for (const item of value) output.push(decodeAssemblyReferences(item, assembly, seen));
+  } else {
+    for (const key of Object.keys(value)) {
+      output[key] = decodeAssemblyReferences(value[key], assembly, seen);
+    }
+  }
+  return output;
+}
+async function encodeResolverResult(value, currentAssembly, seen = /* @__PURE__ */ new WeakMap()) {
+  if (value instanceof BrowserAssembly) {
+    return value === currentAssembly ? { __jsilnetAssemblyReference: true } : { __jsilnetSerializedAssembly: await value.serialize() };
+  }
+  if (value === null || typeof value !== "object") {
+    if (typeof value === "function" || typeof value === "symbol") {
+      throw new TypeError("Resolver results must be structured-cloneable values");
+    }
+    return value;
+  }
+  if (seen.has(value)) return seen.get(value);
+  if (value instanceof ArrayBuffer || ArrayBuffer.isView(value)) return value;
+  const output = value instanceof Map ? /* @__PURE__ */ new Map() : value instanceof Set ? /* @__PURE__ */ new Set() : Array.isArray(value) ? [] : {};
+  seen.set(value, output);
+  if (value instanceof Map) {
+    for (const [key, item] of value) {
+      output.set(
+        await encodeResolverResult(key, currentAssembly, seen),
+        await encodeResolverResult(item, currentAssembly, seen)
+      );
+    }
+  } else if (value instanceof Set) {
+    for (const item of value) {
+      output.add(await encodeResolverResult(item, currentAssembly, seen));
+    }
+  } else if (Array.isArray(value)) {
+    for (const item of value) output.push(await encodeResolverResult(item, currentAssembly, seen));
+  } else {
+    for (const key of Object.keys(value)) {
+      output[key] = await encodeResolverResult(value[key], currentAssembly, seen);
+    }
+  }
+  return output;
+}
+function makeError(data) {
+  const error = data?.name === "FormatError" ? new FormatError(data.message) : data?.name === "UnsupportedFormatError" ? new UnsupportedFormatError(data.message) : new Error(data?.message ?? "Browser worker request failed");
+  if (data?.name && data.name !== "FormatError" && data.name !== "UnsupportedFormatError") {
+    error.name = data.name;
+  }
+  if (data && "offset" in data) error.offset = data.offset;
+  if (data && "context" in data) error.context = data.context;
+  return error;
+}
+function addRvaMapper(pe) {
+  if (!pe || !Array.isArray(pe.sections) || !Number.isInteger(pe.sectionOffset)) return pe;
+  pe.rvaToOffset = (rva, size = 1) => {
+    if (!Number.isInteger(rva) || !Number.isInteger(size) || rva < 0 || size < 0) {
+      throw new FormatError("Invalid RVA range (RVA mapping)");
+    }
+    if (rva === 0 && size === 0) return 0;
+    for (const section of pe.sections) {
+      const span = Math.max(section.virtualSize, section.rawSize);
+      if (rva < section.virtualAddress || rva - section.virtualAddress >= span) continue;
+      const delta = rva - section.virtualAddress;
+      if (delta + size > section.rawSize || section.rawPointer + delta + size > pe.bytes.length) {
+        throw new FormatError(
+          "RVA range is not backed by file data",
+          { offset: section.rawPointer + delta, context: `section ${section.name}` }
+        );
+      }
+      return section.rawPointer + delta;
+    }
+    if (rva < pe.sectionOffset && rva + size <= pe.bytes.length) return rva;
+    throw new FormatError(`RVA 0x${rva.toString(16)} is not mapped by a PE section (RVA mapping)`);
+  };
+  return pe;
+}
+var WorkerClient = class {
+  #worker;
+  #pending = /* @__PURE__ */ new Map();
+  #onMessage;
+  #onError;
+  #onMessageError;
+  #closed = false;
+  constructor(worker) {
+    this.#worker = worker;
+    this.#onMessage = (event) => {
+      const response = event.data;
+      const pending = this.#pending.get(response?.id);
+      if (!pending) return;
+      if (response.type === "resolver") {
+        void this.#resolveCallback(response, pending);
+        return;
+      }
+      this.#pending.delete(response.id);
+      if (response.ok) pending.resolve(response.value);
+      else pending.reject(makeError(response.error));
+    };
+    this.#onError = (event) => {
+      const error = event.error ?? new Error(event.message || "Browser worker failed");
+      for (const pending of this.#pending.values()) pending.reject(error);
+      this.#pending.clear();
+      this.#close();
+    };
+    this.#onMessageError = () => {
+      const error = new Error("Browser worker sent an uncloneable response");
+      for (const pending of this.#pending.values()) pending.reject(error);
+      this.#pending.clear();
+      this.#close();
+    };
+    worker.addEventListener("message", this.#onMessage);
+    worker.addEventListener("error", this.#onError);
+    worker.addEventListener("messageerror", this.#onMessageError);
+  }
+  request(type, payload = {}, transfer = [], resolverOptions = {}) {
+    if (this.#closed) {
+      return Promise.reject(new Error("Browser worker is closed"));
+    }
+    const id = ++nextRequestId;
+    return new Promise((resolve, reject) => {
+      const callbacks = /* @__PURE__ */ new Map();
+      const encodedPayload = encodeCallbacks(payload, callbacks);
+      this.#pending.set(id, { resolve, reject, callbacks, resolverOptions });
+      try {
+        this.#worker.postMessage({ id, type, ...encodedPayload }, transfer);
+      } catch (error) {
+        this.#pending.delete(id);
+        if (error?.name === "DataCloneError") {
+          reject(new TypeError("Browser Worker request contains a non-cloneable value"));
+        } else {
+          reject(error);
+        }
+      }
+    });
+  }
+  async #resolveCallback(response, pending) {
+    const callback = pending.callbacks.get(response.callbackId);
+    try {
+      if (!callback) throw new TypeError("Worker requested an unknown resolver callback");
+      const args = pending.resolverOptions.decodeArguments ? pending.resolverOptions.decodeArguments(response.args) : response.args;
+      const result = await callback(...args);
+      if (this.#closed || !this.#pending.has(response.id)) return;
+      const value = pending.resolverOptions.encodeResult ? await pending.resolverOptions.encodeResult(result) : result;
+      if (this.#closed || !this.#pending.has(response.id)) return;
+      this.#worker.postMessage({
+        type: "resolverResult",
+        id: response.id,
+        resolverRequestId: response.resolverRequestId,
+        ok: true,
+        value
+      });
+    } catch (error) {
+      if (this.#closed || !this.#pending.has(response.id)) return;
+      this.#worker.postMessage({
+        type: "resolverResult",
+        id: response.id,
+        resolverRequestId: response.resolverRequestId,
+        ok: false,
+        error: {
+          name: error?.name ?? "Error",
+          message: error?.message ?? String(error)
+        }
+      });
+    }
+  }
+  dispose() {
+    if (this.#closed) return;
+    for (const pending of this.#pending.values()) {
+      pending.reject(new Error("Browser worker was disposed"));
+    }
+    this.#pending.clear();
+    this.#close();
+  }
+  #close() {
+    if (this.#closed) return;
+    this.#closed = true;
+    this.#worker.removeEventListener("message", this.#onMessage);
+    this.#worker.removeEventListener("error", this.#onError);
+    this.#worker.removeEventListener("messageerror", this.#onMessageError);
+    this.#worker.terminate();
+  }
+};
+var BrowserAssembly = class _BrowserAssembly {
+  #client;
+  #proxy;
+  constructor(client) {
+    this.#client = client;
+  }
+  static async from(input, { workerFactory, transferInput = false } = {}) {
+    const normalizedInput = normalizeInput(input, transferInput);
+    const worker = createWorker(workerFactory);
+    const client = new WorkerClient(worker);
+    const { input: inputValue, transfer } = normalizedInput;
+    try {
+      await client.request("parse", { input: inputValue }, transfer);
+      const instance = new _BrowserAssembly(client);
+      instance.#proxy = new Proxy(instance, {
+        get(target, property, receiver) {
+          if (property === "then") return void 0;
+          if (Reflect.has(target, property)) {
+            const value = Reflect.get(target, property, target);
+            return typeof value === "function" ? value.bind(target) : value;
+          }
+          if (typeof property === "string") {
+            return (...args) => target.#call(property, args);
+          }
+          return void 0;
+        }
+      });
+      return instance.#proxy;
+    } catch (error) {
+      client.dispose();
+      throw error;
+    }
+  }
+  async getState() {
+    return this.#client.request("state");
+  }
+  async callUtility(name, ...args) {
+    const result = await this.#client.request("utility", { name, args });
+    return name === "parsePE" ? addRvaMapper(result) : result;
+  }
+  async #call(name, args) {
+    const result = await this.#client.request(
+      "call",
+      { name, args },
+      [],
+      {
+        decodeArguments: (value) => decodeAssemblyReferences(value, this.#proxy),
+        encodeResult: (value) => encodeResolverResult(value, this.#proxy)
+      }
+    );
+    return result?.__jsilnetAssembly === true ? this.#proxy : result;
+  }
+  dispose() {
+    this.#client.dispose();
+  }
+};
+async function parseAssembly(input, options) {
+  return BrowserAssembly.from(input, options);
+}
+async function callUtility(name, ...args) {
+  const worker = createWorker();
+  const client = new WorkerClient(worker);
+  try {
+    const result = await client.request("utility", { name, args });
+    return name === "parsePE" ? addRvaMapper(result) : result;
+  } finally {
+    client.dispose();
+  }
+}
+export {
+  BrowserAssembly as Assembly,
+  BrowserAssembly,
+  FormatError,
+  UnsupportedFormatError,
+  callUtility,
+  parseAssembly
+};