SvAuth Integration & Operations Guide
Comprehensive documentation on tenant architecture, native client integration, encrypted payload delivery, storefront webhook automation, and customer support procedures for verified sellers.
1. Quick Start Workflow
SvAuth protects native executables and dynamic libraries through a 4-step deployment cycle:
+-------------------+ +----------------------+ +----------------------+ +--------------------+
| 1. App Registered | ---> | 2. Get Packer Secret | ---> | 3. Pack & Verify | ---> | 4. Ship Binary |
| (Platform Staff) | | (SvAuth Dashboard) | | (svauth-packer CLI) | | (payload.bin) |
+-------------------+ +----------------------+ +----------------------+ +--------------------+
- App Provisioning: Staff or team invites provision your application and seller account.
- Acquire Packer Secret: Copy your 64-character hexadecimal key under Applications -> [Your App].
- Pack Runtime Payload: Run
npx svauth-packer packon your compiled binary. - Ship Locked Binary: Distribute
payload.binalongside your launcher. The client retrieves the decryption key in-memory upon valid authentication.
2. Tenancy Architecture & Scoping
SvAuth enforces strict cryptographic and relational isolation for every verified tenant:
- Zero Cross-Tenant Leakage: Sellers manage only their assigned application(s). You have zero visibility into other applications, platform infrastructure, global audit logs, or other sellers' telemetry.
- Database Tenant Scope: All seller dashboard views, API endpoints, and license operations strictly filter by your assigned
app_id. - Plan Quotas:
- Free Plan: 1 application, up to 30 active-or-unclaimed keys, 20 active registered users.
- Pro Plan: Up to 2,500 active-or-unclaimed keys, 5,000 active registered users.
- Self-Cleaning Quota: Expired, revoked, and paused licenses self-clean from the active count and do not count against your quota.
3. Adding Auth to Your Native Executable
The native C++ SDK (sdk/cpp) integrates directly into MSVC, Clang, or GCC with zero external library requirements:
#include "auth/auth_client.h"
using namespace authsdk;
// Configure connection endpoints and application binding
AuthConfig cfg;
cfg.host = "auth.yourdomain.com";
cfg.port = 443;
cfg.secure = true;
cfg.app = AUTH_OBF("myapp");
cfg.version = "1.0.0";
AuthClient auth(std::move(cfg));
// Listen for remote session denials (bans, heartbeat expiry, kill switches)
auth.onDenied = [](const std::string& code) {
printf("[!] Session terminated: %s\n", code.c_str());
ExitProcess(1);
};
4. Auth API Reference
SvAuth utilizes a monotonic challenge-response protocol to protect against credential interception:
1. Initial Challenge Handshake
// Request
{
"app": "myapp"
}
// Response (200 OK)
{
"ok": true,
"nonce": "64_HEX_CHARACTERS",
"server_time": 1789861210
}
2. Buyer Account Registration (Key Redemption)
// Request
{
"app": "myapp",
"key": "BRZ-A1B2-C3D4-E5F6",
"username": "customer1",
"password": "Str0ngP@ssw0rd!",
"hwid": "SHA256_COMPOSITE_MACHINE_HASH",
"nonce": "64_HEX_CHARACTERS",
"proof": "HMAC_SHA256_PROOF"
}
// Response (200 OK)
{
"ok": true,
"session_id": "3fa9642d-0689-436a-9f63-d959892fe221",
"token": "SESSION_BEARER_TOKEN",
"esk": "ENCRYPTED_SESSION_KEY",
"heartbeat_interval": 30
}
3. Password Authentication
Subsequent launches do not require the key. The client authenticates with username and password:
{
"app": "myapp",
"username": "customer1",
"password": "Str0ngP@ssw0rd!",
"hwid": "SHA256_COMPOSITE_MACHINE_HASH"
}
4. Signed Heartbeat
Clients send periodic heartbeats signed with their derived session key to keep the session alive and assert sequence monotonicity.
5. Wiring the UI & Session Callbacks
Example of binding authentication into an ImGui or native UI login window:
void RenderLoginModal() {
static char userBuf[64] = "";
static char passBuf[64] = "";
static char keyBuf[64] = "";
static std::string statusMsg = "";
ImGui::InputText("Username", userBuf, sizeof(userBuf));
ImGui::InputText("Password", passBuf, sizeof(passBuf), ImGuiInputTextFlags_Password);
if (ImGui::Button("Login")) {
auto res = g_auth->loginPassword(userBuf, passBuf);
if (res.ok) {
g_auth->startHeartbeat();
g_loggedIn = true;
} else {
statusMsg = "Error: " + res.code;
}
}
ImGui::Separator();
ImGui::InputText("License Key (First Time)", keyBuf, sizeof(keyBuf));
if (ImGui::Button("Register Account")) {
auto res = g_auth->registerAccount(keyBuf, userBuf, passBuf);
if (res.ok) {
g_auth->startHeartbeat();
g_loggedIn = true;
} else {
statusMsg = "Registration Failed: " + res.code;
}
}
}
6. Payload Packaging & Protection (`svauth-packer`)
All software binaries distributed to buyers must be encrypted using the official svauth-packer CLI:
# 1. Encrypt release binary into payload.bin
npx svauth-packer pack --app myapp --secret <64_HEX_SECRET> --in build/client.dll --out payload.bin
# 2. Mandatory Pre-Release Verification (Always run before shipping!)
npx svauth-packer verify --secret <64_HEX_SECRET> --in payload.bin
To decrypt and execute the payload in-memory upon successful login:
// Retrieve content key v1 from secure server escrow
std::string err;
Bytes contentKey = g_auth->unlock(1, &err);
if (contentKey.empty()) {
printf("[x] Unlock rejected: %s\n", err.c_str());
ExitProcess(1);
}
// Decrypt binary directly in-memory
Bytes payload = ReadFileBytes("payload.bin");
Bytes decrypted = AuthClient::decryptPayload(contentKey, payload);
// Zero plaintext bytes touch the disk
ExecuteFromMemory(decrypted);
7. Release Checklist & Secret Rotation
- Rotate packer secret in dashboard under Applications -> [App] -> Rotate Secret.
- Re-pack local release payload with the new 64-character secret.
- Run
npx svauth-packer verifyto guarantee[✓] VERIFY OK. - Confirm build hash registration under
/admin/versionsif enforcing version verification.
8. Error Codes & Resolution
| Error Code | Cause / Trigger | Recommended Client Action |
|---|---|---|
KEY_INVALID |
Voucher string format incorrect or does not exist. | Prompt customer to re-check voucher characters. |
KEY_ALREADY_USED |
License key has already been claimed by another user account. | Inform customer that keys are single-use; log in with existing account. |
HWID_LIMIT |
All allowed machine slots for the license are currently bound. | Direct customer to request an HWID reset in the seller panel. |
SESSION_LIMIT |
An active session is currently running on another machine. | Close duplicate background client processes or kill via panel. |
BANNED |
User account, license, machine HWID, or IP is restricted. | Display ban reason and cooldown timestamp to customer. |
KEY_EXPIRED |
Subscription duration has elapsed. | Prompt customer to renew their license through store checkout. |
OUT_OF_SCOPE |
Seller session attempting to access resources belonging to another app. | Re-authenticate with appropriate tenant permissions. |
9. Console Panel Guide
The console panel provides self-service management for operators and verified sellers:
- Keys: Generate batch license vouchers with custom tiers and
duration_days. Download key manifests in CSV format. - Users: Inspect active customers, review last-seen timestamps, reset HWID machine slots, and set temporary passwords.
- Sessions: Real-time telemetry on active sessions with live kill controls.
- Bans: Issue user, license, HWID, or app-scoped IP bans with optional shadow monitoring.
- Purchase Secret: Manage inbound store webhook secrets for automatic sale fulfillment.
10. Buyer Support Runbook
When customers contact your support channel, follow this diagnostic runbook:
| Symptom | Root Cause | Seller Action |
|---|---|---|
| `HWID_LIMIT` | Customer changed machine components or logged in on a second PC. | Open Users -> [User] and click Reset HWID. |
| `SESSION_LIMIT` | Ghost process or concurrent execution. | Locate the orphaned session under Sessions and click Kill. |
| Forgot Password | Customer cannot recall account password. | Click Set Password on their user record to issue a temporary password. |
| `KEY_EXPIRED` | Subscription period elapsed. | Explain that subscription days begin on first key redemption; offer renewal voucher. |
| Suspected Leaker | User attempting debugger inspection or redistributing keys. | Apply a Shadow Ban (shadow: true) to monitor security events silently. |
11. Security & Ban Model
SvAuth provides multi-tiered ban enforcement across four distinct scopes:
| Scope | Description | Application Scope |
|---|---|---|
user |
Disables user account and revokes active sessions. | Bound to seller app. |
license |
Revokes license key, terminating access. | Bound to seller app. |
hwid |
Blacklists machine hardware composite hash. | Bound to seller app. |
ip |
Blocks connection requests from an IP address. | Bound to YOUR app only (CGNAT Safe). |
Residential ISPs and mobile networks utilize Carrier-Grade NAT (CGNAT) where hundreds of households share one IP address. All seller-initiated IP bans in SvAuth are strictly scoped to your application. A ban issued by you prevents access to your software only, guaranteeing zero collateral damage to other tenants or customers sharing that public IP address.