@mmo69/vmcode 0.0.0-stage → 1.1.0

package/README.md

@@ -1,3 +1,198 @@
-# Temporary Holding Version
+# vmcode
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> [🇻🇳 Tiếng Việt](README_VI.md) • 🇬🇧 English
+
+NodeJS SDK for the **JsVM.MMO69.Com** VMCode protection API — compile plain
+JavaScript into server-side TNVM **VM bytecode** without shipping the engine
+to the browser.
+
+- **Async task API** (captcha-solver style): submit → `taskId` → poll — made
+  for large files and slow presets
+- **Zero dependencies** (Node ≥ 18, built-in `fetch`)
+- **gzip uploads** for large payloads
+- Needs an **API key** (`tnvm_…`, Pro plan or higher) — create one at
+  <https://JsVM.MMO69.Com/client/apikeys.html>
+
+## Install
+
+```bash
+npm i @mmo69/vmcode
+# or just copy index.mjs — the whole library is a single file
+```
+
+## Quick start
+
+```js
+import { VmCode } from '@mmo69/vmcode';
+import fs from 'node:fs';
+
+const vm = new VmCode({ apiKey: 'tnvm_YOUR_KEY' });
+
+const out = await vm.protect(
+  fs.readFileSync('src/app.js', 'utf8'),
+  { preset: 'medium', target: 'node' },
+);
+fs.writeFileSync('app.protected.js', out.result);
+console.log(`Done in ${out.elapsed}ms — quota used: ${out.usage?.bytes}/${out.usage?.quotaMB}MB`);
+```
+
+Or protect a single function inline:
+
+```js
+const { result } = await vm.protect('function f(x){ return x*3+1; }', { preset: 'low' });
+console.log(result); // protected code — runs exactly like the original
+```
+
+## Presets
+
+| Option (order matches the tables below) | `low` | `medium` | `max` |
+|---|:---:|:---:|:---:|
+| `targetMode` | `root` | `root` | `root` |
+| `preprocessIdentifiers` | – | ✓ | ✓ |
+| `encryptBytecode` | – | ✓ | ✓ |
+| `debugProtection` | – | – | ✓ |
+| `dynamicOpcodes` | ✓ | ✓ | ✓ |
+| `decoyOpcodes` | – | ✓ | ✓ |
+| `deadCodeInjection` | – | – | ✓ |
+| `stackEncoding` | – | – | ✓ |
+| `rollingCipher` | – | ✓ | ✓ |
+| `integrityBinding` | – | – | ✓ |
+| `vmShielding` | – | – | ✓ |
+| `mixedBooleanArithmetic` | – | – | ✓ |
+| `handlerFragmentation` | – | – | ✓ |
+| `stringAtomization` | – | ✓ | ✓ |
+| `polymorphicDecoder` | – | ✓ | ✓ |
+| `scatteredKeys` | – | ✓ | ✓ |
+| `blockPermutation` | – | – | ✓ |
+| `opcodeMutation` | – | – | ✓ |
+| `bytecodeScattering` | – | ✓ | ✓ |
+| `incrementalCipher` | – | – | ✓ |
+| `semanticOpacity` | – | – | ✓ |
+| `observationResistance` | – | – | ✓ |
+
+- **`low`** *(default)* — fastest, only `dynamicOpcodes`: plain VM bytecode,
+  compact output. A 122KB file takes ~a few hundred ms.
+- **`medium`** — balanced: 9/21 options on. Roughly ~1s per MB of source.
+- **`max`** — all 21 options. Strongest but slow — cost scales with
+  **function count and file size** (~6–7s per MB): a 3MB file takes ~20s,
+  a 20MB file can take several minutes — `timeoutMs` (21 min) already covers it.
+
+**Auto-enable** (the engine turns these on by itself, no need to declare):
+enabling `integrityBinding` / `vmShielding` / `opcodeMutation` /
+`incrementalCipher` / `observationResistance` → auto-enables `rollingCipher`;
+enabling `stringAtomization` → auto-enables `polymorphicDecoder`.
+
+## Engine options
+
+Pass as the second argument of `submit()` / `protect()`. Booleans only work
+as **opt-IN additions** to the preset (the server only accepts `true` — you
+cannot turn off an option the preset already enables):
+
+```js
+await vm.protect(code, {
+  preset: 'medium',            // low | medium | max (default low)
+  targetMode: 'comment',       // root (default) | comment — Pro+
+  target: 'node',              // browser (default) | node — Pro+
+  rollingCipher: true,         // turn an extra option ON top of the preset
+  vmShielding: true,           // → rollingCipher comes along automatically
+});
+```
+
+### `targetMode`
+
+- **`root`** *(default)* — protects ALL top-level functions of the file
+- **`comment`** *(Pro+)* — only protects functions marked by a leading comment:
+  ```js
+  // tnvm:vm
+  function secret(a, b) { /* only this function gets VM-compiled */ }
+  ```
+
+### `target`
+
+- **`browser`** *(default)* — output runs in the browser
+- **`node`** *(Pro+)* — output runs in NodeJS
+
+### Security
+
+| Option | Description |
+|---|---|
+| `rollingCipher` | Position-dependent XOR encryption on every instruction |
+| `integrityBinding` | Bind bytecode decryption to interpreter source integrity |
+| `debugProtection` | Multi-layered anti-debugger with escalating response |
+| `vmShielding` | Per-function micro-interpreters with independent opcode shuffle |
+| `incrementalCipher` | Move instruction decryption into the VM dispatch loop |
+| `semanticOpacity` | Opaque predicates, handler aliasing, and encoding diversity |
+| `observationResistance` | Silent computation corruption when instrumentation detected |
+| `encryptBytecode` | RC4 encryption using an environment fingerprint key |
+
+### Obfuscation
+
+| Option | Description |
+|---|---|
+| `mixedBooleanArithmetic` | Replace arithmetic/bitwise ops with MBA expressions |
+| `stackEncoding` | XOR-encode VM stack values during execution |
+| `deadCodeInjection` | Insert unreachable bytecode sequences after RETURN |
+| `handlerFragmentation` | Split handlers into interleaved fragments |
+| `stringAtomization` | Replace string literals with encoded table lookups |
+| `blockPermutation` | Shuffle bytecode basic block order |
+| `opcodeMutation` | Runtime handler table mutations via MUTATE opcodes |
+| `bytecodeScattering` | Split bytecode into mixed-type fragments scattered through output |
+
+### Optimization
+
+| Option | Description |
+|---|---|
+| `preprocessIdentifiers` | Rename identifiers before compilation |
+| `dynamicOpcodes` | Filter unused opcode handlers from interpreter |
+| `decoyOpcodes` | Inject realistic fake opcode handlers |
+| `polymorphicDecoder` | Per-build random chain of reversible byte operations |
+| `scatteredKeys` | Fragment key materials across closure tiers |
+
+## Plan gating
+
+API keys are only issued from the **Pro** plan up, so any valid `tnvm_…` key
+unlocks every preset and all custom options:
+
+| Plan | Presets | Custom options | Max request size |
+|---|---|:---:|---|
+| Anonymous (web) | low, medium | ✗ | 128KB |
+| Free | low, medium | ✗ | 268KB |
+| **Pro** | low, medium, max | ✓ | 5MB |
+| Team | low, medium, max | ✓ + priority queue | 12MB |
+| Business | low, medium, max | ✓ + priority queue | 20MB |
+
+## API
+
+### `new VmCode({ apiKey, baseUrl, pollMs, timeoutMs, gzip })`
+
+| Option | Default | Note |
+|---|---|---|
+| `apiKey` | — | **required**, `tnvm_…` (Pro+) |
+| `baseUrl` | `https://JsVM.MMO69.Com` | change for a local server |
+| `pollMs` | `1000` | result polling interval |
+| `timeoutMs` | `1260000` | max wait of `protect()` — the server compiles max-size files up to 20 min, default 21 min covers it |
+| `gzip` | `true` | gzip requests > 1KB |
+
+### Methods
+
+| Method | Returns |
+|---|---|
+| `vm.protect(code, options?, callOpts?)` | `{ result, elapsed, usage? }` — submits and polls until done |
+| `vm.submit(code, options?)` | `{ taskId, status: 'pending' }` — creates the task, keep the `taskId` |
+| `vm.poll(taskId)` | `{status:'pending'\|'running'}` \| `done{result,elapsed,usage}` \| `error{error}` \| `gone` |
+| `vm.meta()` | `{ options, presets, plans, … }` from `/api/meta` |
+
+`callOpts` = `{ pollMs, timeoutMs }` overrides the constructor config for a
+single call.
+
+**The result can be fetched only ONCE** — after a `done` poll the task is
+deleted; unclaimed tasks expire after 2 hours. Queue-friendly: after
+`submit()` you can do other work and `poll()` whenever you're ready.
+
+### `VmError`
+
+Every failure throws a `VmError` — `err.code` matches the API error codes:
+`size` `options_locked` `quota` `rate` `engine` `task` `timeout` `network` …
+(`err.status` = HTTP status, `0` = network/timeout error on the SDK side).
+On `protect()` timeout the message already includes the `taskId` so you can
+resume polling manually.

package/README_VI.md

@@ -0,0 +1,196 @@
+# vmcode
+
+> 🇻🇳 Tiếng Việt • [🇬🇧 English](README.md)
+
+SDK NodeJS cho API bảo vệ mã **JsVM.MMO69.Com** (TNVM VMCode) — biên dịch
+JavaScript thường thành **VM bytecode** xử lý bên server, không ship engine ra
+trình duyệt.
+
+- **API bất đồng bộ** kiểu captcha-solver: submit → `taskId` → poll — sinh ra
+  cho file lớn và preset chậm
+- **Zero dependencies** (Node ≥ 18, dùng `fetch` có sẵn)
+- **gzip upload** cho payload lớn
+- Cần **API key** (`tnvm_…`, gói Pro trở lên) — tạo tại
+  [https://JsVM.MMO69.Com/client/apikeys.html](https://JsVM.MMO69.Com/client/apikeys.html)
+
+## Cài đặt
+
+```bash
+npm i @mmo69/vmcode
+# hoặc chỉ copy index.mjs — cả thư viện gói gọn trong 1 file
+```
+
+## Dùng nhanh
+
+```js
+import { VmCode } from '@mmo69/vmcode';
+import fs from 'node:fs';
+
+const vm = new VmCode({ apiKey: 'tnvm_CUA_BAN' });
+
+const out = await vm.protect(
+  fs.readFileSync('src/app.js', 'utf8'),
+  { preset: 'medium', target: 'node' },
+);
+fs.writeFileSync('app.protected.js', out.result);
+console.log(`Xong sau ${out.elapsed}ms — đã dùng ${out.usage?.bytes}/${out.usage?.quotaMB}MB`);
+```
+
+Hoặc inline 1 hàm:
+
+```js
+const { result } = await vm.protect('function f(x){ return x*3+1; }', { preset: 'low' });
+console.log(result); // mã đã bảo vệ — chạy y hệt bản gốc
+```
+
+## Preset
+
+| Option (thứ tự trong bảng ở dưới) | `low` | `medium` | `max` |
+| --------------------------------------- | :------: | :--------: | :------: |
+| `targetMode`                          | `root` |  `root`  | `root` |
+| `preprocessIdentifiers`               |    –    |     ✓     |    ✓    |
+| `encryptBytecode`                     |    –    |     ✓     |    ✓    |
+| `debugProtection`                     |    –    |     –     |    ✓    |
+| `dynamicOpcodes`                      |    ✓    |     ✓     |    ✓    |
+| `decoyOpcodes`                        |    –    |     ✓     |    ✓    |
+| `deadCodeInjection`                   |    –    |     –     |    ✓    |
+| `stackEncoding`                       |    –    |     –     |    ✓    |
+| `rollingCipher`                       |    –    |     ✓     |    ✓    |
+| `integrityBinding`                    |    –    |     –     |    ✓    |
+| `vmShielding`                         |    –    |     –     |    ✓    |
+| `mixedBooleanArithmetic`              |    –    |     –     |    ✓    |
+| `handlerFragmentation`                |    –    |     –     |    ✓    |
+| `stringAtomization`                   |    –    |     ✓     |    ✓    |
+| `polymorphicDecoder`                  |    –    |     ✓     |    ✓    |
+| `scatteredKeys`                       |    –    |     ✓     |    ✓    |
+| `blockPermutation`                    |    –    |     –     |    ✓    |
+| `opcodeMutation`                      |    –    |     –     |    ✓    |
+| `bytecodeScattering`                  |    –    |     ✓     |    ✓    |
+| `incrementalCipher`                   |    –    |     –     |    ✓    |
+| `semanticOpacity`                     |    –    |     –     |    ✓    |
+| `observationResistance`               |    –    |     –     |    ✓    |
+
+- **`low`** *(mặc định)* — nhanh nhất, chỉ `dynamicOpcodes`: bytecode VM thuần,
+  output gọn. File 122KB ~vài trăm ms.
+- **`medium`** — cân bằng: 9/21 option bật. Tốc độ ~1 giây mỗi MB mã nguồn.
+- **`max`** — tất cả 21 option. Mạnh nhất nhưng chậm — thời gian tăng theo
+  **số hàm lẫn size file** (~6–7 giây mỗi MB): file 3MB ~20 giây,
+  file 20MB có thể mất vài phút — `timeoutMs` mặc định 21 phút đã đủ.
+
+**Auto-enable** (engine tự bật kèm, không cần khai báo):
+bật `integrityBinding` / `vmShielding` / `opcodeMutation` / `incrementalCipher` /
+`observationResistance` → tự bật `rollingCipher`; bật `stringAtomization` → tự
+bật `polymorphicDecoder`.
+
+## Tuỳ chọn engine (options)
+
+Truyền vào tham số thứ 2 của `submit()` / `protect()`. **Boolean chỉ có tác
+dụng BẬT THÊM** ngoài preset (server chỉ nhận `true` — không thể tắt option mà
+preset đã bật):
+
+```js
+await vm.protect(code, {
+  preset: 'medium',            // low | medium | max (mặc định low)
+  targetMode: 'comment',       // root (mặc định) | comment — Pro+
+  target: 'node',              // browser (mặc định) | node — Pro+
+  rollingCipher: true,         // bật THÊM option ngoài preset
+  vmShielding: true,           // → tự bật rollingCipher kèm theo
+});
+```
+
+### `targetMode`
+
+- **`root`** *(mặc định)* — bảo vệ TOÀN BỘ hàm top-level của file
+- **`comment`** *(Pro+)* — chỉ bảo vệ hàm có comment đánh dấu ngay phía trên:
+  ```js
+  // tnvm:vm
+  function secret(a, b) { /* chỉ hàm này được VM hoá */ }
+  ```
+
+### `target`
+
+- **`browser`** *(mặc định)* — output chạy trong trình duyệt
+- **`node`** *(Pro+)* — output chạy trong NodeJS
+
+### Bảo mật (Security)
+
+| Option                    | Mô tả                                                                      |
+| ------------------------- | ---------------------------------------------------------------------------- |
+| `rollingCipher`         | Mã hoá XOR phụ thuộc vị trí trên từng instruction                    |
+| `integrityBinding`      | Ràng buộc giải mã bytecode vào tính toàn vẹn source của interpreter |
+| `debugProtection`       | Chống debugger đa tầng, phản ứng leo thang dần                         |
+| `vmShielding`           | Micro-interpreter riêng cho từng hàm, xáo trộn opcode độc lập        |
+| `incrementalCipher`     | Đưa việc giải mã instruction vào vòng dispatch của VM                |
+| `semanticOpacity`       | Opaque predicates, alias handler, đa dạng hoá kiểu mã hoá              |
+| `observationResistance` | Âm thầm làm hỏng kết quả tính toán khi phát hiện instrumentation   |
+| `encryptBytecode`       | Mã hoá RC4 bằng khoá fingerprint của môi trường chạy                |
+
+### Nghiền mã (Obfuscation)
+
+| Option                     | Mô tả                                                  |
+| -------------------------- | -------------------------------------------------------- |
+| `mixedBooleanArithmetic` | Thay phép toán số học/bitwise bằng biểu thức MBA  |
+| `stackEncoding`          | XOR-encode giá trị trên stack VM trong lúc chạy     |
+| `deadCodeInjection`      | Chèn chuỗi bytecode không thể tới ngay sau RETURN   |
+| `handlerFragmentation`   | Tách handler thành các mảnh đan xen nhau            |
+| `stringAtomization`      | Thay string literal bằng tra bảng đã mã hoá        |
+| `blockPermutation`       | Xáo trộn thứ tự basic block của bytecode            |
+| `opcodeMutation`         | Đột biến bảng handler lúc runtime qua opcode MUTATE |
+| `bytecodeScattering`     | Tách bytecode thành mảnh trộn lẫn rải khắp output |
+
+### Tối ưu (Optimization)
+
+| Option                    | Mô tả                                                      |
+| ------------------------- | ------------------------------------------------------------ |
+| `preprocessIdentifiers` | Đổi tên identifier trước khi compile                    |
+| `dynamicOpcodes`        | Lọc opcode handler không dùng khỏi interpreter           |
+| `decoyOpcodes`          | Tiêm các handler opcode giả giống thật                  |
+| `polymorphicDecoder`    | Chuỗi phép toán byte ngẫu nhiên, đổi theo từng build |
+| `scatteredKeys`         | Phân mảnh key material qua các tầng closure              |
+
+## Phân quyền theo gói
+
+API key chỉ cấp từ gói **Pro** trở lên, nên với key `tnvm_…` mọi preset và
+tuỳ biến đều mở:
+
+| Gói            | Preset           |     Tuỳ biến option     | Giới hạn / request |
+| --------------- | ---------------- | :------------------------: | -------------------- |
+| Ẩn danh (web)  | low, medium      |             ✗             | 128KB                |
+| Free            | low, medium      |             ✗             | 268KB                |
+| **Pro**   | low, medium, max |             ✓             | 5MB                  |
+| Team            | low, medium, max | ✓ + hàng đợi ưu tiên | 12MB                 |
+| Business        | low, medium, max | ✓ + hàng đợi ưu tiên | 20MB                 |
+
+## API
+
+### `new VmCode({ apiKey, baseUrl, pollMs, timeoutMs, gzip })`
+
+| Option        | Default                    | Ghi chú                                                                                               |
+| ------------- | -------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `apiKey`    | —                         | **bắt buộc**, `tnvm_…` (Pro+)                                                               |
+| `baseUrl`   | `https://JsVM.MMO69.Com` | đổi khi chạy server local                                                                           |
+| `pollMs`    | `1000`                   | nhịp poll kết quả                                                                                   |
+| `timeoutMs` | `1260000`                 | thời gian chờ tối đa của `protect()` — server compile file cỡ lớn tối đa 20 phút, mặc định 21 phút là đủ |
+| `gzip`      | `true`                   | nén gzip request > 1KB                                                                                |
+
+### Phương thức
+
+| Phương thức                            | Trả về                                                                                           |
+| ----------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `vm.protect(code, options?, callOpts?)` | `{ result, elapsed, usage? }` — submit + tự poll tới khi xong                                 |
+| `vm.submit(code, options?)`             | `{ taskId, status: 'pending' }` — tạo task, giữ `taskId`                                    |
+| `vm.poll(taskId)`                       | `{status:'pending'\|'running'}` \| `done{result,elapsed,usage}` \| `error{error}` \| `gone` |
+| `vm.meta()`                             | `{ options, presets, plans, … }` từ `/api/meta`                                              |
+
+`callOpts` = `{ pollMs, timeoutMs }` đè cấu hình constructor cho 1 lần gọi.
+
+**Kết quả chỉ lấy được MỘT LẦN** — poll nhận `done` xong task bị xoá; task
+không ai lấy sẽ hết hạn sau 2 giờ. Queue-friendly: `submit()` xong có thể
+làm việc khác, `poll()` khi cần.
+
+### `VmError`
+
+Mọi lỗi đều throw `VmError` — `err.code` khớp mã lỗi API:
+`size` `options_locked` `quota` `rate` `engine` `task` `timeout` `network` …
+(`err.status` = HTTP status, `0` = lỗi mạng/timeout phía SDK).
+`protect()` timeout thì message kèm sẵn `taskId` để poll thủ công tiếp.

package/index.mjs

@@ -0,0 +1,104 @@
+// vmcode — NodeJS SDK for the JsVM.MMO69.Com code-protection API (TNVM VMCode).
+// Async captcha-solver style API: POST /api/vm → {taskId} → poll POST /api/vm/result.
+// Requires an API key (tnvm_…, Pro plan+) — create at https://JsVM.MMO69.Com/client/apikeys.html
+// Zero dependencies — only the Node ≥ 18 built-in fetch (gzip responses auto-decompressed).
+
+import zlib from 'node:zlib';
+
+const DEFAULT_BASE = 'https://JsVM.MMO69.Com';
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** Error thrown by the SDK/API — err.code matches API codes: size, options_locked, quota, rate, engine, task, timeout, network… */
+export class VmError extends Error {
+  constructor(message, code, status = 0) {
+    super(message);
+    this.name = 'VmError';
+    this.code = code || 'error';
+    this.status = status; // HTTP status (0 = network/timeout error on the SDK side)
+  }
+}
+
+export class VmCode {
+  /**
+   * @param {object} opts
+   * @param {string}  opts.apiKey     tnvm_… API key (required — Pro plan or higher)
+   * @param {string} [opts.baseUrl]   default https://JsVM.MMO69.Com (change for local/dev)
+   * @param {number} [opts.pollMs]    result polling interval (default 1000)
+   * @param {number} [opts.timeoutMs] max wait of protect() (default 21 minutes — the server compiles max-size files up to 20 min)
+   * @param {boolean} [opts.gzip]     gzip requests > 1KB (default true)
+   */
+  constructor({ apiKey, baseUrl, pollMs = 1000, timeoutMs = 21 * 60_000, gzip = true } = {}) {
+    if (!apiKey) throw new VmError('Missing apiKey (tnvm_…) — create one at /client/apikeys.html (Pro plan+)', 'apikey');
+    this.apiKey = String(apiKey);
+    this.base = String(baseUrl || DEFAULT_BASE).replace(/\/+$/, '');
+    this.pollMs = pollMs;
+    this.timeoutMs = timeoutMs;
+    this.gzip = gzip;
+  }
+
+  async #post(path, body) {
+    const json = JSON.stringify(body);
+    const headers = { 'content-type': 'application/json', authorization: `Bearer ${this.apiKey}` };
+    let payload = json;
+    if (this.gzip && json.length > 1024) { // large body → gzip it, the server decompresses automatically
+      payload = zlib.gzipSync(Buffer.from(json));
+      headers['content-encoding'] = 'gzip';
+    }
+    let res;
+    try {
+      res = await fetch(this.base + path, { method: 'POST', headers, body: payload });
+    } catch (err) {
+      throw new VmError(`Cannot connect to ${this.base}: ${err.message}`, 'network');
+    }
+    const data = await res.json().catch(() => null);
+    if (!res.ok) throw new VmError((data && data.error) || `HTTP ${res.status}`, (data && data.code) || 'http', res.status);
+    return data;
+  }
+
+  /** GET /api/meta — options + presets + plans (ground truth for building an option UI) */
+  async meta() {
+    let res;
+    try { res = await fetch(this.base + '/api/meta', { headers: { authorization: `Bearer ${this.apiKey}` } }); }
+    catch (err) { throw new VmError(`Cannot connect to ${this.base}: ${err.message}`, 'network'); }
+    const data = await res.json().catch(() => null);
+    if (!res.ok) throw new VmError((data && data.error) || `HTTP ${res.status}`, (data && data.code) || 'http', res.status);
+    return data;
+  }
+
+  /** Step 1 — create a compile task → {taskId, status:'pending'} (keep the taskId for polling) */
+  submit(code, options = {}) {
+    if (typeof code !== 'string' || !code.trim()) throw new VmError('Missing code (JavaScript source string)', 'missing');
+    return this.#post('/api/vm', { code, options });
+  }
+
+  /** Step 2 — poll the task → {status:'pending'|'running'} | done{result,elapsed,usage} | error | gone */
+  poll(taskId) {
+    return this.#post('/api/vm/result', { taskId });
+  }
+
+  /**
+   * Submit + auto-poll until done — the quickest way to use the SDK.
+   * @param {string} code       source JavaScript
+   * @param {object} options    preset 'low'|'medium'|'max' + targetMode 'root'|'comment' +
+   *                            target 'browser'|'node' + boolean engine options (see vm.meta())
+   * @param {object} [callOpts] {pollMs, timeoutMs} overrides the constructor config for this call
+   * @returns {Promise<{result:string, elapsed:number, usage?:object}>}
+   */
+  async protect(code, options = {}, { pollMs = this.pollMs, timeoutMs = this.timeoutMs } = {}) {
+    const { taskId } = await this.submit(code, options);
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+      if (Date.now() > deadline) {
+        throw new VmError(`Timeout after ${timeoutMs}ms — task ${taskId} not finished, keep polling with poll("${taskId}")`, 'timeout');
+      }
+      await sleep(pollMs);
+      const r = await this.poll(taskId);
+      if (r.status === 'done') return { result: r.result, elapsed: r.elapsed, usage: r.usage };
+      if (r.status === 'error') throw new VmError(r.error || 'Engine failed to process the code', 'engine');
+      if (r.status === 'gone') throw new VmError(r.error || 'Task not found or result already fetched', 'task');
+      // pending / running → wait for the next tick
+    }
+  }
+}
+
+export default VmCode;

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "@mmo69/vmcode",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "description": "NodeJS SDK for the JsVM.MMO69.Com VMCode API — protect JavaScript with server-side TNVM VM bytecode (async task: submit → taskId → poll).",
+  "type": "module",
+  "main": "index.mjs",
+  "exports": {
+    ".": "./index.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nttrung9x/vmcode.git"
+  },
+  "files": [
+    "index.mjs",
+    "README.md",
+    "README_VI.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "javascript", "obfuscator", "vm", "protect", "bytecode", "tnvm", "jsvm", "mmo69"
+  ],
+  "homepage": "https://JsVM.MMO69.Com",
+  "license": "MIT"
+}