API Protocol v2

Enterprise only — server issues session secrets, clients verify Ed25519, and Operations run on signed envelopes. API 1.2 / 1.3 / 1.4 stay fully supported.

Why Protocol v2

Quick Start

Request MAC

After init, every request must include session, ts, nonce, seq, and mac.

POST
/api/v2/
2.0
{sha256(body_json)}
{session}
{ts}
{nonce}
{seq}

mac = HMAC-SHA256(canonical, session_secret) as lowercase hex. Response headers X-Signature-Timestamp + X-Signature-Ed25519 must verify against the server public key.

AEAD response body

When the session has a stored sess_secret, authenticated replies may include X-LA-Enc: aead.

• Wire: base64(iv16 || tag16 || ciphertext)
• Key: SHA256("la2aead|" + session_secret) (32 raw bytes)
• Cipher: AES-256-GCM with 16-byte IV (OpenSSL / C++ / PHP). .NET AesGcm only accepts 12 — use BouncyCastle.Cryptography in C#.

Sequence after login / license

1. init → client starts at seq = 0
2. login / license sends seq = 1; server rotates session and returns "seq": 0
3. Client must adopt that value (ForceAdopt). If seq is missing (legacy), adopt 1
4. Next check sends adopted + 1

Client increments before the HTTP call; server bumps only after MAC OK. On unsigned Ghost/WAF 404 or pre-bump Fail, roll client seq back.

หลัง login/license SDK เก็บ pack grant — HasFeature / info.features. ดู Subscriptions & Features.

type=feature — server ticket

หลัง license เรียก Feature("inject") — เซิร์ฟตรวจแพ็กคีย์แล้วออก feature_token (TTL 60s). Lite ที่ไม่มีชื่อนั้นได้ 403 Feature not entitled. เปิด Panel Require Feature Ack เมื่อต้องการ one-shot consume.

HTTP 404 Ghost on Init

SDK ทุกภาษาแยกข้อความ: Init = Ghost / app not found · request อื่น = Ghost/WAF + seq rolled back. Spec: GHOST_404.md · PROTOCOL_V2.md

Idle TTL — Invalid session on Login

1. เปิดแอป → Init → หน้าใส่ License ค้าง > 90 วิ → กด Login → Invalid session
2. SDK ล่าสุด: Login / License จับ error นี้แล้ว Init ใหม่ + retry ครั้งเดียว อัตโนมัติ
3. อย่าสับสนกับ Invalid license key / Invalid mac / Invalid sequence

รายละเอียด: Troubleshooting → API v2 · Error Codes → Protocol v2 · PROTOCOL_V2.md

Request Flow

1. init (+ optional device_pubkey, optional hash) → session, session_secret, pubkey, policy (includes hash_check, hash_auto_ban, tool_auto_ban, block_ai, idle_ttl, …)
2. login / license with MAC + hwid → rotated session + seq: 0 (SDK re-Inits once if session was wiped by idle TTL)
3. check / var / opsack with MAC + same hwid
4. ban — self-report ban (HWID from session; unvalidated Ops may ban only bound_hwid)
5. AEAD body when X-LA-Enc: aead

type=var — Global Variables

Global app variables are never public. Server gate (VarCore::ClientAccessError):

• Session validated (login / license) + non-empty credential
• User exists, not banned, active subscription
• bound_hwid set + request hwid must match (stolen session alone fails)
• HWID/IP not blacklisted · license key not banned · optional app hwid_lock
• Fresh check heartbeat (v2) before first var
• Entitlement var enabled · name charset [A-Za-z0-9._:-] ≤ 64
• Response includes var_mac (HMAC-SHA256 over value with session secret)

Init-only sessions → Session not authenticated. Expired sub → No active subscription / heartbeat sub_expired. Panel / Seller always force authed=1.

Flow: init → license/login → check → type=var + varid + hwid. API v1: same HWID gate on var / getvar / setvar.

See Error Codes → Variables · API Endpoints.

type=ban — Client Self-Ban

Authenticated (or Ops Init-bound) clients can ask the server to ban the current machine after a Hardening trip.

• Body: type=ban, reason (≤99 chars, e.g. tool:bad_process), optional hwid
• When session is not login-validated: server ignores client HWID and uses bound_hwid only
• Respect panel tool_auto_ban — only call Ban when policy.tool_auto_ban is true
• SDK: C# BanAsync · C++ Ban · PHP Ban · Python ban

Server-side hash rejects can auto-ban without the client when hash_auto_ban is ON — see Access Controls.

Operations Envelope

On authenticated check, the server may attach a signed ops object (payload, sig, raw, optional jti). Verify Ed25519 before execute. Ack with opsack + device_sig from the enrolled device key (enroll via device_pubkey on init — kept across license/login rotation). Wire result_data as base64 + result_enc=b64; forward envelope jti once. Send the same hwid on every check/opsack so bound_hwid matches the panel target. Spec: sdk/PROTOCOL_V2.md.

• C++: ops_executor.hpp
• C#: OpsEnvelope.cs
• Places (list_dir tokens): OPS_PLACES.md · panel guide Operations → Places
• Contract: PROTOCOL_V2.md

Official SDKs

require 'LibreAuthV2.php';
$app = new LibreAuthV2('AppName', 'OWNER_ID_10', 'https://libreauth.nutexe.dev/api/v2/');
$app->Init(); // or Init($exeMd5) when Hash Check is on
$app->Login('user', 'pass', 'HWID');

Seller API + Protocol v2

Seller API (/seller-api/, sellerkey) is orthogonal to Protocol v2. It already manages apps whose clients call /api/v2/. Seller wire stays JSON + Bearer — not HMAC. See Seller API. type=info returns capabilities.api_v2.

Protocol comparison