v2hub-admin 1.0.0

Admin extension for V2Hub VPN Subscription API client

V2Hub Admin - Admin Extension for VPN Subscription API

Admin API extension for V2Hub with HMAC-SHA256 authentication for privileged operations.

Features

• 🔐 HMAC Authentication: SHA-256 signature-based authentication
• 🎯 Admin Operations: Manage all subscriptions across the system
• 🔄 Async & Sync: Both AsyncAdminClient and AdminClient
• 📦 Inherits V2Hub: Built on top of the main v2hub library
• 🛡️ Type Safe: Full type hints and Pydantic models

Installation

# Install v2hub-admin (will automatically install v2hub as dependency)
pip install v2hub-admin

Quick Start

Async Usage

from v2hub_admin import AsyncAdminClient

async with AsyncAdminClient(
    base_url="https://api.example.com",
    api_token="your-admin-token",
    hmac_secret="your-hmac-secret"
) as admin:
    # List all subscriptions in the system
    all_subs = await admin.list_all_subscriptions()

    # Get any subscription by token
    sub = await admin.get_any_subscription("sub_token_123")

    # Delete any subscription (admin privilege)
    await admin.delete_any_subscription("sub_token_123")

Sync Usage

from v2hub_admin import AdminClient

with AdminClient(
    base_url="https://api.example.com",
    api_token="your-admin-token",
    hmac_secret="your-hmac-secret"
) as admin:
    # List all subscriptions
    all_subs = admin.list_all_subscriptions()

    # Get statistics
    stats = admin.get_statistics()
    print(f"Total subscriptions: {stats['total_subscriptions']}")

HMAC Authentication

The admin client uses HMAC-SHA256 for request signing:

import hmac
import hashlib
from datetime import datetime

# The library handles this automatically
# This is just for understanding

timestamp = datetime.utcnow().isoformat()
message = f"DELETE:/admin/subscriptions/{token}:{timestamp}"
signature = hmac.new(
    secret.encode(),
    message.encode(),
    hashlib.sha256
).hexdigest()

Admin API Endpoints

Subscriptions

• list_all_subscriptions() - List all subscriptions in system
• get_any_subscription(token) - Get any subscription (bypass ownership)
• delete_any_subscription(token) - Delete any subscription (admin privilege)

Statistics (if available)

• get_statistics() - Get system-wide statistics
• get_user_stats(user_id) - Get stats for specific user

Error Handling

Inherits all exception types from v2hub:

from v2hub import VPNAPIError, AuthenticationError, AuthorizationError
from v2hub_admin import AsyncAdminClient

async with AsyncAdminClient(base_url, token, secret) as admin:
    try:
        await admin.delete_any_subscription("token123")
    except AuthenticationError:
        print("Invalid HMAC signature or credentials")
    except AuthorizationError:
        print("Insufficient admin privileges")
    except VPNAPIError as e:
        print(f"API error: {e}")

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Type checking
mypy src/

Requirements

• v2hub >= 1.0.0 (automatically installed)
• Python >= 3.9

CLI Integration

Works seamlessly with v2hub-cli:

# Install CLI with admin support
pip install v2hub-cli[admin]

# Use admin commands
v2hub admin list-all
v2hub admin delete-any <token>
v2hub admin stats

Security Notes

⚠️ Important:

• Store HMAC secrets securely (environment variables, secret managers)
• Never commit secrets to version control
• Use HTTPS in production
• Rotate secrets regularly
• Admin tokens have elevated privileges - protect them carefully

License

MIT License - see LICENSE file for details.

Author

nestt