Talos — Secure Rust Licensing System

Talos is a Rust-based secure licensing framework providing:

Hardware-bound licensing
Encrypted license storage
License activation/validation
Heartbeat-based liveness checks
A lightweight Axum server backend
A robust async client library

Your software gets a reliable, secure "gatekeeper," inspired by Talos, the mythological bronze guardian who protected Crete.

Overview

Talos offers:

A client library for embedding license logic inside your application
A server component for verifying, activating, and tracking licenses
Full async, cross-platform compatibility (Windows, macOS, Linux)
Strong cryptography (AES-256-GCM + SHA-256 hardware fingerprinting)

Talos is built to be easy to integrate yet extremely hard to bypass.

Key Features

Hardware Binding — Licenses tied to CPU + motherboard fingerprint
Secure OS Keyring Storage — License data stored in Windows Credential Manager, macOS Keychain, or Linux Secret Service
AES-256-GCM Encryption — License data encrypted with hardware-derived keys
Networked License Control — Activate/validate/deactivate remotely
Heartbeat System — Keeps licenses alive and trackable
SQLite & Postgres Support — Choose your storage backend
Self-Hostable — Easy to deploy, zero external dependencies
Fully Async — Powered by tokio, axum, reqwest, sqlx
Strong Test Coverage — Unit tests + integration tests

How It Works

Talos generates a hardware fingerprint using CPU + motherboard identifiers (hashed via SHA-256).
License data is encrypted using AES-256-GCM with a hardware-derived key.
Encrypted data is stored securely in the OS keyring (with fallback to app data directory).
Client communicates with the server using HTTPS via reqwest.
Server stores licenses and heartbeat timestamps via SQLx.
A small REST API allows:
- Activation
- Validation
- Deactivation
- Heartbeat updates

Project Structure

talos/
├── src/
│   ├── client/
│   │   ├── license.rs            # License struct + client operations
│   │   ├── storage.rs            # Keyring + file storage abstraction
│   │   ├── encrypted_storage.rs  # AES-256-GCM encrypted storage
│   │   ├── heartbeat.rs          # Heartbeat HTTP operations
│   │   ├── key_generation.rs     # Device key helpers
│   │   └── main.rs               # Example client binary
│   ├── server/
│   │   ├── database.rs           # SQLite/Postgres abstraction
│   │   ├── handlers.rs           # Axum handlers for /activate, /validate...
│   │   ├── admin.rs              # Admin API handlers (feature-gated)
│   │   ├── auth.rs               # JWT authentication (feature-gated)
│   │   ├── routes.rs             # Router builder
│   │   ├── server_sim.rs         # In-memory simulation for tests
│   │   └── main.rs               # Server binary
│   ├── config.rs                 # Config loader (config.toml + env vars)
│   ├── encryption.rs             # AES-256-GCM utilities
│   ├── errors.rs                 # Custom LicenseError type
│   ├── hardware.rs               # Cross-platform hardware fingerprinting
│   ├── license_key.rs            # License key generation/validation
│   ├── tiers.rs                  # Tier configuration system
│   └── lib.rs                    # Library entry point
├── tests/                        # Unit and integration tests
├── examples/                     # Usage examples
├── migrations/                   # Database migrations
├── docs/
│   ├── public/
│   │   └── ROADMAP.md            # Development roadmap
│   ├── api/                      # API reference documentation
│   │   ├── rest-api.md           # Complete REST API reference
│   │   └── openapi.json          # OpenAPI 3.1.0 specification
│   ├── examples/                 # Complete runnable examples
│   │   ├── basic-client/         # Minimal client integration
│   │   ├── air-gapped/           # Offline validation example
│   │   └── feature-gating/       # Feature gating example
│   └── guide/                    # User guides
│       ├── getting-started.md    # 5-minute quickstart
│       ├── client-integration.md # Client library usage
│       ├── server-deployment.md  # Production deployment
│       ├── admin-api.md          # Admin API guide
│       └── troubleshooting.md    # Debugging and FAQ
├── .claude/
│   └── README.md                 # AI assistant context (for contributors)
├── config.toml.example           # Example configuration
├── .env.example                  # Example environment variables
├── Cargo.toml
└── README.md

Prerequisites

Rust (stable)
SQLite or PostgreSQL
sqlx-cli (for running migrations)

Install Rust:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

rustup update

Install SQLx CLI:

cargo install sqlx-cli

Installation

Add Talos to your project:

[dependencies]

talos = "0.2"

Then:

cargo build

Feature Flags

Talos uses Cargo feature flags to let you include only what you need:

Feature	Default	Description
`server`	Yes	Server components (handlers, database)
`sqlite`	Yes	SQLite database backend
`postgres`	No	PostgreSQL database backend
`jwt-auth`	No	JWT authentication middleware for protected endpoints
`admin-api`	No	Admin CRUD API for license management
`rate-limiting`	No	Rate limiting middleware for abuse prevention
`background-jobs`	No	Scheduled background jobs for license maintenance
`openapi`	No	OpenAPI 3.0 specification and Swagger UI

Examples

# Default: server + SQLite

talos = "0.2"



# Client-only (no server components)

talos = { version = "0.2", default-features = false }



# Server with PostgreSQL instead of SQLite

talos = { version = "0.2", default-features = false, features = ["server", "postgres"] }



# Server with both SQLite and PostgreSQL

talos = { version = "0.2", features = ["postgres"] }



# Full server with admin API and JWT auth

talos = { version = "0.2", features = ["admin-api", "jwt-auth"] }



# Server with background jobs enabled

talos = { version = "0.2", features = ["background-jobs"] }



# Full-featured server

talos = { version = "0.2", features = ["admin-api", "jwt-auth", "rate-limiting", "background-jobs"] }



# Server with OpenAPI documentation

talos = { version = "0.2", features = ["admin-api", "openapi"] }

Quick Start

1. Configure

Copy the example configuration files:

cp config.toml.example config.toml

cp .env.example .env

Edit config.toml as needed:

server_url = "http://127.0.0.1:8080"

heartbeat_interval = 60

enable_logging = true



[database]

db_type = "sqlite"

sqlite_url = "sqlite://talos.db"

2. Run Migrations

sqlx migrate run

3. Start the Server

cargo run --bin talos_server

4. Use the Client

use talos::client::License;
use talos::errors::LicenseResult;

#[tokio::main]
async fn main() -> LicenseResult<()> {
    // Create a new license client
    let mut license = License::new(
        "LIC-XXXX-XXXX-XXXX".to_string(),  // Your license key
        "http://127.0.0.1:8080".to_string(),
    );

    // Bind to this hardware (replaces activate())
    let bind_result = license.bind(Some("My Workstation"), None).await?;
    println!("License bound. Features: {:?}", bind_result.features);

    // Validate the license
    let validation = license.validate().await?;
    if validation.has_feature("feature_a") {
        println!("Feature A is enabled!");
    }

    // Check a specific feature
    let feature_result = license.validate_feature("premium_export").await?;
    if feature_result.allowed {
        println!("Premium export is available");
    }

    // Send heartbeat
    let heartbeat = license.heartbeat().await?;
    println!("Server time: {}", heartbeat.server_time);

    // Release when done (replaces deactivate())
    license.release().await?;

    Ok(())
}

Air-Gapped Systems

For systems that need to operate offline within a grace period:

use talos::client::License;

async fn check_license_with_fallback() -> bool {
    let mut license = License::load_from_disk().await.unwrap();

    // Try online validation first, fall back to cached offline validation
    match license.validate_with_fallback().await {
        Ok(result) => {
            if let Some(warning) = &result.warning {
                // System should go online soon
                eprintln!("Warning: {}", warning);
            }
            true
        }
        Err(e) => {
            eprintln!("License validation failed: {}", e);
            false
        }
    }
}

Or run the provided example:

cargo run --example manual_activate

Server API Endpoints

OpenAPI Documentation (requires `openapi` feature)

When running with the openapi feature enabled, interactive API documentation is available:

Endpoint	Description
`/swagger-ui`	Swagger UI for interactive API exploration
`/api-docs/openapi.json`	OpenAPI 3.0 specification (JSON)

Run the server with OpenAPI enabled:

cargo run --bin talos_server --features "openapi,admin-api"

Then navigate to http://127.0.0.1:8080/swagger-ui in your browser.

System Endpoints (always available)

Method	Endpoint	Description
GET	`/health`	Health check with database status

The health endpoint returns:

{
  "status": "healthy",
  "service": "talos",
  "version": "0.2.2",
  "database": {
    "connected": true,
    "db_type": "sqlite"
  }
}

Legacy Client Endpoints (always available)

Method	Endpoint	Description
POST	`/activate`	Activate a license
POST	`/validate`	Validate if license is active
POST	`/deactivate`	Deactivate a license
POST	`/heartbeat`	Send heartbeat ping

Client API v1 Endpoints (always available)

Method	Endpoint	Description
POST	`/api/v1/client/bind`	Bind license to hardware
POST	`/api/v1/client/release`	Release license from hardware
POST	`/api/v1/client/validate`	Validate a license
POST	`/api/v1/client/validate-or-bind`	Validate or auto-bind
POST	`/api/v1/client/heartbeat`	Send heartbeat
POST	`/api/v1/client/validate-feature`	Validate feature access

Admin Endpoints (requires `admin-api` feature)

Method	Endpoint	Description
POST	`/api/v1/licenses`	Create a new license
POST	`/api/v1/licenses/batch`	Batch create licenses
GET	`/api/v1/licenses/{id}`	Get license by ID
GET	`/api/v1/licenses?org_id=X`	List licenses by org
PATCH	`/api/v1/licenses/{id}`	Update a license
POST	`/api/v1/licenses/{id}/revoke`	Revoke a license (with optional grace period)
POST	`/api/v1/licenses/{id}/reinstate`	Reinstate a suspended/revoked license
POST	`/api/v1/licenses/{id}/extend`	Extend license expiration
PATCH	`/api/v1/licenses/{id}/usage`	Update usage/bandwidth metrics
POST	`/api/v1/licenses/{id}/release`	Release hardware binding
POST	`/api/v1/licenses/{id}/blacklist`	Permanently blacklist a license

Token Endpoints (requires `admin-api` feature)

Method	Endpoint	Description
POST	`/api/v1/tokens`	Create a new API token
GET	`/api/v1/tokens`	List all API tokens
GET	`/api/v1/tokens/{id}`	Get token details
DELETE	`/api/v1/tokens/{id}`	Revoke a token

All legacy client requests use:

{
  "license_id": "LICENSE-12345",
  "client_id": "CLIENT-67890"
}

Example

curl -X POST http://127.0.0.1:8080/validate \

  -H "Content-Type: application/json" \

  -d '{"license_id":"LICENSE-12345","client_id":"CLIENT-67890"}'

Error Response Format

All API endpoints return errors in a standardized JSON format:

{
  "error": {
    "code": "LICENSE_NOT_FOUND",
    "message": "The requested license does not exist",
    "details": null
  }
}

Error Codes

Code	HTTP Status	Description
License State
`LICENSE_NOT_FOUND`	404	License key does not exist
`LICENSE_EXPIRED`	403	License has expired
`LICENSE_REVOKED`	403	License has been revoked
`LICENSE_SUSPENDED`	403	License is temporarily suspended
`LICENSE_BLACKLISTED`	403	License is permanently blacklisted
`LICENSE_INACTIVE`	403	License is not active
Hardware Binding
`ALREADY_BOUND`	409	License is bound to another device
`NOT_BOUND`	409	License is not bound to any device
`HARDWARE_MISMATCH`	403	Hardware ID doesn't match bound device
Features & Quotas
`FEATURE_NOT_INCLUDED`	403	Feature not in license tier
`QUOTA_EXCEEDED`	403	Usage quota exceeded
Validation
`INVALID_REQUEST`	400	Request payload is invalid
`MISSING_FIELD`	400	Required field is missing
`INVALID_FIELD`	400	Field value is invalid
Authentication
`MISSING_TOKEN`	401	No authorization token provided
`INVALID_HEADER`	400	Authorization header malformed
`INVALID_TOKEN`	401	Token is invalid
`TOKEN_EXPIRED`	401	Token has expired
`INSUFFICIENT_SCOPE`	403	Token lacks required permissions
`AUTH_DISABLED`	501	Authentication not configured
Server Errors
`NOT_FOUND`	404	Resource not found
`CONFLICT`	409	Operation conflicts with current state
`DATABASE_ERROR`	500	Database operation failed
`CONFIG_ERROR`	500	Server configuration error
`CRYPTO_ERROR`	500	Encryption operation failed
`NETWORK_ERROR`	502	External service communication failed
`INTERNAL_ERROR`	500	Unexpected server error

Testing

Run all tests:

cargo test

Run with all features enabled:

cargo test --features "admin-api,jwt-auth"

Run with logging:

RUST_LOG=info cargo test

Roadmap

See the full ROADMAP.md for detailed development plans.

Current Status: v0.2.2

Talos is a fully-featured, production-ready licensing system with:

License activation/validation/deactivation with bind/release workflow
Heartbeat mechanism with grace period support
Hardware binding (SHA-256 fingerprint)
Encrypted storage (AES-256-GCM)
Configurable license key generation
Tier-based feature system with configurable tiers
Organization/tenant grouping (1 org = N licenses)
Bandwidth/quota tracking exposed in validation responses
JWT authentication middleware
Admin API (CRUD operations)
Rate limiting middleware
License lifecycle management (suspend, revoke, reinstate, extend)
Background jobs (grace period expiration, license expiration, stale device cleanup)
License blacklisting (permanent ban with audit trail)
OpenAPI 3.0 specification with Swagger UI
Standardized error response format
Updated client library with v1 API methods (bind/release/validate/validate-feature/heartbeat)
Secure encrypted cache for offline/air-gapped system support
Admin API IP whitelisting (CIDR support, IPv4/IPv6, proxy header support)

Upcoming:

Audit logging
API key rotation
Webhook notifications
Dashboard UI
Analytics and reporting

Documentation

Comprehensive documentation is available in the docs/ folder:

Guides

Guide	Description
Getting Started	5-minute quickstart with feature flags and setup
Client Integration	Full client lifecycle, offline validation, feature gating
Server Deployment	Database setup, Docker, nginx/traefik, production checklist
Admin API	All admin endpoints, authentication, security best practices
Troubleshooting	Common errors, debugging tips, FAQ

API Reference

Resource	Description
REST API Reference	Complete endpoint documentation with examples
OpenAPI Spec	OpenAPI 3.1.0 specification
`/swagger-ui`	Interactive API explorer (when running with `openapi` feature)

Examples

Complete, runnable examples are available in docs/examples/:

Example	Description
basic-client	Minimal client integration with runtime license key entry
air-gapped	Offline validation with encrypted cache and grace periods
feature-gating	Enable/disable features based on license tier

Each example includes a README with step-by-step instructions for both Windows (PowerShell) and Mac/Linux (bash).

Contributing

PRs, issues, and discussions are all welcome. See CONTRIBUTING.md for guidelines.

License

MIT License — see LICENSE for details.

netviper-talos 0.2.4

Talos — Secure Rust Licensing System

Overview

Key Features

How It Works

Project Structure

Prerequisites

Installation

Feature Flags

Examples

Quick Start

1. Configure

2. Run Migrations

3. Start the Server

4. Use the Client

Air-Gapped Systems

Server API Endpoints

OpenAPI Documentation (requires openapi feature)

System Endpoints (always available)

Legacy Client Endpoints (always available)

Client API v1 Endpoints (always available)

Admin Endpoints (requires admin-api feature)

Token Endpoints (requires admin-api feature)

Example

Error Response Format

Error Codes

Testing

Roadmap

Documentation

Guides

API Reference

Examples

Contributing

License

OpenAPI Documentation (requires `openapi` feature)

Admin Endpoints (requires `admin-api` feature)

Token Endpoints (requires `admin-api` feature)