> For the complete documentation index, see [llms.txt](https://docs.cyne.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cyne.ai/guides/credential-security.md).

# Credential Security

This guide provides best practices for managing secrets, API keys, and sensitive configurations within Cyne AI to ensure security and operational efficiency.

### **Core Concepts**

#### **Environment Variables**

Cyne AI uses a hierarchical system for environment variables:

1. **Character-specific secrets** (highest priority).
2. **Environment variables** defined in `.env` files.
3. **Default values** (lowest priority).

***

#### **Secret Types**

Common secrets managed in Cyne AI:

```env
# API Keys
OPENAI_API_KEY=sk-your-openai-key

# Client Authentication
DISCORD_API_TOKEN=your-discord-token
TELEGRAM_BOT_TOKEN=your-telegram-token

# Solana Wallet Credentials
SOLANA_PRIVATE_KEY=example-private-key
SOLANA_PUBLIC_KEY=example-public-key
```

***

### **Implementation Guide**

#### **Basic Setup**

1. Create a `.env` file from the provided template:

   ```bash
   cp .env.example .env
   ```
2. Configure environment variable discovery in your code:

   ```typescript
   import { config } from "dotenv";
   config(); // Load environment variables
   ```

***

#### **Character-Specific Secrets**

Define secrets directly in character files for modular configuration:

```json
{
  "name": "TradingAgent",
  "settings": {
    "secrets": {
      "OPENAI_API_KEY": "character-specific-key",
      "SOLANA_PRIVATE_KEY": "character-specific-wallet"
    }
  }
}
```

Access secrets in your code:

```typescript
const apiKey = runtime.getSetting("OPENAI_API_KEY");
```

***

### **Secure Storage**

#### **Wallet Management**

Handle Solana wallet credentials securely:

```typescript
class WalletManager {
  private async initializeWallet(runtime: IAgentRuntime) {
    const privateKey = runtime.getSetting("SOLANA_PRIVATE_KEY");
    if (!privateKey) {
      throw new Error("Wallet private key not configured");
    }
    // Validate and initialize the wallet
    const keyBuffer = Buffer.from(privateKey, "base64");
    if (keyBuffer.length !== 64) {
      throw new Error("Invalid key format");
    }
    return new Wallet(privateKey);
  }
}
```

***

#### **Encryption for Secrets**

Encrypt sensitive secrets before storage:

```typescript
import { createCipheriv, createDecipheriv, randomBytes } from "crypto";

class SecretEncryption {
  static async encrypt(value: string, key: Buffer): Promise<string> {
    const iv = randomBytes(16);
    const cipher = createCipheriv("aes-256-gcm", key, iv);
    let encrypted = cipher.update(value, "utf8", "hex");
    encrypted += cipher.final("hex");
    return JSON.stringify({
      iv: iv.toString("hex"),
      encrypted,
      tag: cipher.getAuthTag().toString("hex")
    });
  }

  static async decrypt(encrypted: string, key: Buffer): Promise<string> {
    const { iv, encrypted: encryptedData, tag } = JSON.parse(encrypted);
    const decipher = createDecipheriv("aes-256-gcm", key, Buffer.from(iv, "hex"));
    decipher.setAuthTag(Buffer.from(tag, "hex"));
    let decrypted = decipher.update(encryptedData, "hex", "utf8");
    decrypted += decipher.final("utf8");
    return decrypted;
  }
}
```

***

### **Best Practices**

#### **1. Environment Segregation**

Use separate `.env` files for different environments:

* `.env.development` – Development settings
* `.env.staging` – Staging environment
* `.env.production` – Production environment

***

#### **2. Secret Validation**

Ensure required secrets are defined:

```typescript
async function validateSecrets(character: Character): Promise<void> {
  const required = ["OPENAI_API_KEY", "SOLANA_PRIVATE_KEY"];
  const missing = required.filter((key) => !character.settings.secrets[key]);
  if (missing.length > 0) {
    throw new Error(`Missing required secrets: ${missing.join(", ")}`);
  }
}
```

***

#### **3. Git Security**

Exclude sensitive files from version control by adding the following to `.gitignore`:

```bash
.env
characters/**/secrets.json
```

***

#### **4. Secret Rotation**

Regularly rotate secrets to enhance security:

```typescript
class SecretRotation {
  private static readonly SECRET_LIFETIME = 90 * 24 * 60 * 60 * 1000; // 90 days

  async shouldRotateSecret(secretName: string): Promise<boolean> {
    const lastRotation = await this.getLastRotation(secretName);
    return Date.now() - lastRotation > SecretRotation.SECRET_LIFETIME;
  }

  async rotateSecret(secretName: string): Promise<void> {
    // Logic for secret rotation
    const newSecret = await this.generateNewSecret();
    await this.updateSecret(secretName, newSecret);
  }
}
```

***

### **Troubleshooting**

#### **Common Issues**

1. **Missing Secrets**\
   Ensure required environment variables or character-specific secrets are defined:

   ```typescript
   if (!process.env.OPENAI_API_KEY) {
     throw new Error("OpenAI API key is missing.");
   }
   ```
2. **Invalid Secret Format**\
   Validate the format of critical secrets like API keys:

   ```typescript
   function validateApiKey(key: string): boolean {
     return key.startsWith("sk-") && key.length > 20;
   }
   ```
3. **Secret Loading Errors**\
   Handle errors gracefully during secret loading:

   ```typescript
   try {
     await loadSecrets();
   } catch (error) {
     console.error("Error loading secrets:", error.message);
   }
   ```

***

### **Security Considerations**

#### **1. API Keys Handling**

* Use strong validation logic for keys.
* Rotate keys periodically to reduce risks.

***

#### **2. Access Control**

* Restrict access to sensitive secrets using a controlled list.
* Log unauthorized access attempts for monitoring.

***

#### **3. Encryption at Rest**

* Encrypt all sensitive data stored on disk.
* Use AES-256-GCM encryption for strong security.

***

### **Related Resources**

* **Configuration Guide**: General setup instructions.
* **Local Development Guide**: Best practices for local environments.
* **Infrastructure Guide**: Secure deployment practices.

***

By following these guidelines, you can manage secrets effectively and securely within the **Cyne AI** framework, ensuring robust and secure operations.