# 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
```bash
export KAIGEN_SECRET_KEY="your-secret-key-here"
```

#### Production
Set the environment variable in your deployment configuration:
```bash
KAIGEN_SECRET_KEY=your-secret-key-here
```

#### Docker
```bash
docker run -e KAIGEN_SECRET_KEY=your-secret-key-here your-app
```

#### Docker Compose
```yaml
environment:
  - KAIGEN_SECRET_KEY=your-secret-key-here
```

## Configuration Structure

The Kaigen service configuration is defined in `appsettings.json`:

```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
```csharp
// 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