SvAuth Docs
Docs generated from SELLERS.md — last updated September 2026

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:

Workflow Sequence
+-------------------+      +----------------------+      +----------------------+      +--------------------+
| 1. App Registered | ---> | 2. Get Packer Secret | ---> | 3. Pack & Verify     | ---> | 4. Ship Binary     |
| (Platform Staff)  |      | (SvAuth Dashboard)   |      | (svauth-packer CLI)  |      | (payload.bin)      |
+-------------------+      +----------------------+      +----------------------+      +--------------------+
  1. App Provisioning: Staff or team invites provision your application and seller account.
  2. Acquire Packer Secret: Copy your 64-character hexadecimal key under Applications -> [Your App].
  3. Pack Runtime Payload: Run npx svauth-packer pack on your compiled binary.
  4. Ship Locked Binary: Distribute payload.bin alongside 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:

auth_setup.cpp
#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

POST /v1/auth/challenge
// Request
{
  "app": "myapp"
}

// Response (200 OK)
{
  "ok": true,
  "nonce": "64_HEX_CHARACTERS",
  "server_time": 1789861210
}

2. Buyer Account Registration (Key Redemption)

POST /v1/auth/register
// 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:

POST /v1/auth/login_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:

ui_login.cpp
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:

Packaging Commands
# 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:

payload_unlock.cpp
// 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

Pre-Flight Verification Checklist
  1. Rotate packer secret in dashboard under Applications -> [App] -> Rotate Secret.
  2. Re-pack local release payload with the new 64-character secret.
  3. Run npx svauth-packer verify to guarantee [✓] VERIFY OK.
  4. Confirm build hash registration under /admin/versions if 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).
App-Scoped IP Bans vs Global IP Bans

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.