Hetzner-Backup/v2_adminpanel/TODO_LIZENZSERVER_CONFIG.md

TODO: Lizenzserver Konfiguration Implementation

Overview

Implement client configuration management and single-session enforcement for Account Forger software.

Current State

• License activation works (consumes device slots)
• Basic verification exists at /api/license/verify
• No heartbeat system
• No single-session enforcement
• Admin panel has UI for "Lizenzserver Konfiguration" but backend is missing

Requirements

1. Single Session Enforcement: Only one device can run the software at a time (even if activated on multiple devices)
2. Heartbeat System: 30-second heartbeats to track active sessions
3. Version Management: Control minimum supported version and update notifications
4. Client Configuration: Manage Account Forger settings from admin panel

Implementation Tasks

1. Database Schema

Admin Panel Database

-- Client configuration (one row for Account Forger)
CREATE TABLE client_configs (
    id SERIAL PRIMARY KEY,
    client_name VARCHAR(100) NOT NULL DEFAULT 'Account Forger',
    api_key VARCHAR(255) NOT NULL,
    heartbeat_interval INTEGER DEFAULT 30, -- seconds
    session_timeout INTEGER DEFAULT 60, -- seconds (2x heartbeat)
    current_version VARCHAR(20) NOT NULL,
    minimum_version VARCHAR(20) NOT NULL,
    download_url TEXT,
    whats_new TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Active sessions tracking
CREATE TABLE active_sessions (
    id SERIAL PRIMARY KEY,
    license_id INTEGER REFERENCES licenses(id) ON DELETE CASCADE,
    hardware_id VARCHAR(255) NOT NULL,
    ip_address INET,
    client_version VARCHAR(20),
    session_token VARCHAR(255) UNIQUE NOT NULL,
    started_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    last_heartbeat TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    UNIQUE(license_id) -- Only one active session per license
);

-- Session history for debugging
CREATE TABLE session_history (
    id SERIAL PRIMARY KEY,
    license_id INTEGER REFERENCES licenses(id) ON DELETE CASCADE,
    hardware_id VARCHAR(255) NOT NULL,
    ip_address INET,
    client_version VARCHAR(20),
    started_at TIMESTAMP,
    ended_at TIMESTAMP,
    end_reason VARCHAR(50) -- 'normal', 'timeout', 'forced', 'replaced'
);

2. License Server Endpoints

New endpoints needed in /v2_lizenzserver/app/api/license.py:

1. POST /api/license/session/start

   • Input: license_key, machine_id, hardware_hash, version
   • Check: License valid? Already active session?
   • If active session exists: Return error "Es ist nur eine Sitzung erlaubt, stelle sicher, dass nirgendwo sonst das Programm läuft"
   • If no session: Create session, return session_token and version info
   • Response includes: session_token, whats_new (if newer version), download_url

2. POST /api/license/session/heartbeat

   • Input: session_token, license_key
   • Update last_heartbeat timestamp
   • Return: success status

3. POST /api/license/session/end

   • Input: session_token
   • Mark session as ended
   • Log to session_history

4. Background job: Clean up sessions older than 60 seconds without heartbeat

3. Admin Panel Implementation

Routes needed in /v2_adminpanel/routes/admin_routes.py:

1. GET /lizenzserver/config

   • Show current client configuration
   • Display active sessions count

2. POST /lizenzserver/config/update

   • Update version, download URL, what's new
   • Update minimum supported version

3. GET /lizenzserver/sessions

   • List all active sessions
   • Show: License key, Customer name, Hardware ID, IP, Started at, Last heartbeat

4. POST /lizenzserver/sessions/{session_id}/terminate

   • Force close a session (admin only: rac00n, w@rh@mm3r)

5. GET /lizenzserver/config/client/new (currently 404)

   • This is what's missing and causing the error
   • Should handle creating initial client config

4. Security

• API key required for all client requests
• License key validates ownership
• Hardware ID ensures device authenticity
• Session tokens prevent replay attacks

5. Client Flow

1. Startup:

   POST /api/license/session/start
   -> Get session_token or error
   -> Show version update if available
   

2. Running (every 30 seconds):

   POST /api/license/session/heartbeat
   -> Keep session alive
   

3. Shutdown:

   POST /api/license/session/end
   -> Clean session exit
   

6. Error Handling

• Network interruption: Session expires after 60s
• Software crash: Session expires after 60s
• Multiple launch attempts: Show error message
• Version too old: Block with message to update

7. Admin Features

• View active sessions
• Force terminate sessions
• Update version requirements
• View session history (last 24h)
• Manage client configuration

Implementation Order

1. Create database tables
2. Implement session management in license server
3. Add heartbeat endpoint
4. Create admin panel routes for configuration
5. Implement session viewing/management
6. Add background cleanup job
7. Test with Account Forger client

Notes

• YAGNI: One global config for all Account Forger instances
• No per-customer settings
• No grace period for session reclaim
• Generic error messages (no "who's using it" info)