managing-apps/docs/KaigenConfiguration.md

Kaigen Service Configuration

The Kaigen service is used for managing user credits during backtest operations. It requires proper configuration to function correctly.

Environment Variables

Required Environment Variable

• KAIGEN_SECRET_KEY: The secret key used for AES-256-CBC encryption of Basic Auth tokens sent to the Kaigen service.

Setting the Environment Variable

Development

export KAIGEN_SECRET_KEY="your-secret-key-here"

Production

Set the environment variable in your deployment configuration:

KAIGEN_SECRET_KEY=your-secret-key-here

Docker

docker run -e KAIGEN_SECRET_KEY=your-secret-key-here your-app

Docker Compose

environment:
  - KAIGEN_SECRET_KEY=your-secret-key-here

Configuration Structure

The Kaigen service configuration is defined in appsettings.json:

{
  "Kaigen": {
    "BaseUrl": "https://api.kaigen.managing.live",
    "DebitEndpoint": "/api/credits/debit",
    "RefundEndpoint": "/api/credits/refund",
    "SecretKey": "${KAIGEN_SECRET_KEY}"
  }
}

Authentication Method

The service now uses Basic Authentication with AES-256-GCM encrypted tokens:

1. Token Format: {walletAddress}-{username}
2. Encryption: The token is encrypted using AES-256-GCM with the configured secret key
3. Basic Auth: The encrypted token is sent in the Authorization header as Basic {base64EncodedToken}:

Example Token Generation

// For user "john" with wallet "0x123..."
var authToken = "0x123...-john";
var encryptedToken = CryptoHelpers.EncryptAesGcm(authToken, secretKey);
var basicAuth = Convert.ToBase64String(Encoding.ASCII.GetBytes($"{encryptedToken}:"));
// Result: Authorization: Basic {base64EncodedToken}:

API Endpoints

• PUT /api/credits/debit - Debit credits from user account
• PUT /api/credits/refund - Refund credits to user account

Security Notes

• The secret key should never be committed to source control
• Use environment variables or secure configuration management systems
• The secret key is used for AES-256-GCM encryption of authentication tokens
• Rotate the secret key regularly for enhanced security
• Each request uses a unique nonce for encryption, ensuring replay attack protection
• The GCM mode provides both confidentiality and authenticity

Error Handling

If the KAIGEN_SECRET_KEY environment variable is not set, the application will throw an InvalidOperationException with a clear error message during startup.

Migration from Private Key Authentication

If migrating from the previous private key signature method:

1. Replace KAIGEN_PRIVATE_KEY with KAIGEN_SECRET_KEY in your environment variables
2. Update any configuration files to use the new SecretKey property instead of PrivateKey
3. The Kaigen server must be updated to handle Basic Auth with AES-256-GCM decryption