HomeAPI Integration & Developer Documentation

Protocol 2.2.2 — Frozen Specification

API Integration & Developer Documentation

Step-by-step guides for integrating License Key verification APIs and deploying bots on VPS

6 Quy Tắc Bảo Mật Bắt Buộc (Protocol 2.2.2)

Tất cả sản phẩm phát hành trên MrMMO phải tuân thủ nghiêm ngặt:

🚫 1. Không Nhúng LicenseKey Vĩnh Viễn

Tuyệt đối không hardcode LicenseKey vào source code hoặc đóng gói vào file thực thi (.exe / .py). Quy trình Zero-Config loại bỏ hoàn toàn việc phân phối key vĩnh viễn trong file chạy.

🔒 2. Lưu DeviceToken Trong OS Secure Storage

Sau bootstrap, DeviceToken phải được mã hóa qua Windows DPAPI (CryptProtectData), macOS Keychain, hoặc Linux Secret Service. Không lưu plaintext vào file cấu hình.

🧠 3. SessionToken Chỉ Giữ Trong RAM

SessionToken (JWT/HMAC-SHA256) có thời hạn ngắn (15–30 phút). Chỉ lưu trong bộ nhớ tạm (volatile RAM), tuyệt đối không bao giờ ghi xuống đĩa cứng.

🎟️ 4. ActivationTicket Là Vé Dùng 1 Lần

Vé kích hoạt (act_...) đi kèm file download bundle có hạn tối đa 24 giờ. Sau khi gọi bootstrap thành công, file activation.json phải được client xóa vĩnh viễn.

🆔 5. Ràng Buộc Định Danh ToolApp

Mọi request bootstrap, refresh, heartbeat đều phải gửi đúng canonical ToolApp ID (CUID) và tool_version (SemVer chuẩn). Sai lệch ID sẽ bị server từ chối ngay lập tức.

⚡ 6. Vô Hiệu Hóa Tức Thì (Cascade Revocation)

Khi khách hàng hoàn tiền (refund), hủy thuê bao hoặc reset HWID trên web, toàn bộ phiên làm việc của thiết bị đó sẽ lập tức bị khóa tại heartbeat tiếp theo.

Vòng Đời Bản Quyền Chuẩn (3 Giai Đoạn)

Quy trình vận hành theo hợp đồng Protocol 2.2.2 giữa Client và Server:

1Giai Đoạn 1: Cài Đặt Lần Đầu (Zero-Config Enrollment)

Khách mua tool ➔ Server tự động nhúng .mrmmo/activation.json vào file ZIP tải về ➔ Người dùng giải nén và mở tool ➔ Client gửi request:

POST /api/v1/license/bootstrap

Server xác thực vé kích hoạt một lần, trả về device_token (Client lưu vào DPAPI/Keychain) và session_token (lưu RAM). File activation.json bị xóa.

2Giai Đoạn 2: Các Lần Khởi Động Tiếp Theo (Seamless Session Refresh)

Người dùng mở lại tool ngày hôm sau ➔ Client nạp device_token từ OS Secure Storage ➔ Tự động gửi request cấp phiên mới:

POST /api/v1/license/session/refresh

Server đối soát thiết bị và gói thuê bao, trả về session_token mới. Người dùng hoàn toàn không phải nhập key lại.

3Giai Đoạn 3: Trong Khi Vận Hành (Runtime Heartbeat)

Client định kỳ gửi heartbeat theo chu kỳ động từ server (thông số heartbeat_interval trả về, ví dụ 120 giây) kèm session_token trong JSON body (không dùng header Authorization) để duy trì trạng thái:

POST /api/v1/license/heartbeat

Nếu bản quyền bị hủy, refund hoặc hết hạn, server trả về mã lỗi canonical (HTTP 403), client lập tức ngắt toàn bộ tác vụ automation.

Tích Hợp Khuyến Nghị: MrMMO Python Protected SDK V1

Tránh tự viết lại HTTP client thủ công (dễ bị bẻ khóa bytecode Python). Hãy sử dụng SDK bảo vệ lõi Native Rust chính thức của MrMMO:

Cấu trúc thư mục Tool Python chuẩn:

my_automation_tool/
├── main.py
├── requirements.txt
└── mrmmo_sdk/
    ├── __init__.py
    ├── __init__.pyi
    └── mrmmo_core.pyd  # Binary Rust native bảo vệ license & DPAPI trên Windows

File: main.py

import sys from mrmmo_sdk import ToolRuntime, LicenseError # 1. Khởi tạo đối tượng bảo vệ bản quyền Protocol 2.2.2 # Tự động nạp cấu hình từ ToolApp ID biên dịch sẵn runtime = ToolRuntime() try: # 2. Quy trình khởi tạo tự động (Ưu tiên DeviceToken DPAPI -> Hoặc đọc activation.json) runtime.initialize() print(f"[+] Bản quyền hợp lệ! Trạng thái: {runtime.status}") print(f"[+] Thời hạn phiên: {runtime.session_expires_at}") except LicenseError as err: # 3. Xử lý lỗi bản quyền theo mã chuẩn Protocol 2.2.2 # Mã lỗi: SUBSCRIPTION_INACTIVE, DEVICE_LIMIT_EXCEEDED, HWID_MISMATCH,... print(f"[-] Không thể kích hoạt bản quyền: [{err.code}] {err.message}") sys.exit(1) # 4. THỰC THI TÁC VỤ BẢO VỆ QUA NATIVE RUST (Chống Patch Code) def run_automation(): sensitive_data = "user_account_payload_or_algorithm_input" # Hàm native Rust sẽ từ chối giải mã nếu phiên bản quyền không phải ACTIVE processed_data = runtime.protected_transform(sensitive_data) print(f"[+] Dữ liệu đã xử lý an toàn: {processed_data}") if __name__ == "__main__": run_automation()

Bảo Vệ Thuật Toán Nhạy Cảm Qua Native Rust

Không nên chỉ kiểm tra if not runtime.is_authorized(): sys.exit() vì attacker có thể patch bytecode Python để bỏ qua lệnh if. Thay vào đó, hãy chuyển logic giải mã payload hoặc thuật toán trọng tâm của tool vào hàm native runtime.protected_transform(...). Lõi Rust sẽ chặn đứng thực thi nếu trạng thái bản quyền không phải là ACTIVE.

Đặc Tả REST API Protocol 2.2.2 (Dành Cho Custom Client)

Dành cho nhà phát triển muốn xây dựng Custom Client bằng C++, C#, Go hoặc NodeJS:

Production API Base URL:

Cấu hình domain chính thức: https://mrmmo.com (hoặc lấy động từ file activation.json: apiBaseUrl).

POST/api/v1/license/bootstrap

Kích hoạt thiết bị lần đầu bằng vé một lần (Zero-Config).

Request Payload:

{
  "ticket": "act_8a2d1f04b2c9e71a9540de83c1b504f2f3e4d5c6b7a890123456789abcdef012",
  "hwid": "5f4dcc3b5aa765d61d8327deb882cf992b9599b421a7f1a5120157ac04acadc5",
  "tool_id": "cmtpwjdmo0000j6n72lcpnevw",
  "tool_version": "1.0.0"
}

POST/api/v1/license/session/refresh

Cấp phiên làm việc mới cho thiết bị đã đăng ký (khởi động tool lần sau).

Request Payload:

{
  "device_token": "dev_c91b504f2f3e4d5c6b7a890123456789abcdef0128a2d1f04b2c9e71a9540de83",
  "hwid": "5f4dcc3b5aa765d61d8327deb882cf992b9599b421a7f1a5120157ac04acadc5",
  "tool_id": "cmtpwjdmo0000j6n72lcpnevw",
  "tool_version": "1.0.0"
}

POST/api/v1/license/heartbeat

Duy trì phiên làm việc trong khi tool đang chạy (chu kỳ động theo heartbeat_interval từ server, ví dụ 120 giây).

Request Payload (JSON Body, không gửi qua Header Authorization):

{
  "session_token": "eyJhbGciOiJIUzI1NiIsInZlcnNpb24iOjIsInR5cCI...",
  "hwid": "5f4dcc3b5aa765d61d8327deb882cf992b9599b421a7f1a5120157ac04acadc5",
  "tool_id": "cmtpwjdmo0000j6n72lcpnevw",
  "tool_version": "1.0.0"
}

POST/api/v1/license/verify

Xác thực key thủ công trực tiếp hoặc tái liên kết thiết bị khi người dùng nhập key trên UI.

Request Payload:

{
  "key": "MRMMO-VIP-A1B2C3-D4E5F6",
  "hwid": "5f4dcc3b5aa765d61d8327deb882cf992b9599b421a7f1a5120157ac04acadc5",
  "tool_id": "cmtpwjdmo0000j6n72lcpnevw",
  "tool_version": "1.0.0"
}

LOCAL DEVELOPMENT ONLY

Mục này chỉ dành riêng cho lập trình viên kiểm thử kết nối trên máy tính cục bộ trong quá trình phát triển (Local Testnet):

# Chỉ định API origin khi chạy dev server cục bộ:

export MRMMO_API_BASE_URL="http://localhost:3000"

# Hoặc trong code dev test:

runtime = ToolRuntime(api_base_url="http://localhost:3000")

* Lưu ý: Không phân phối cấu hình localhost trong gói phát hành cho khách hàng. Sản phẩm chính thức luôn phải kết nối qua HTTPS production.