ironclaw/docs/drafts/security/secrets.mdx

---
title: Secrets Management
sidebarTitle: Secrets
description: Encrypted credential storage and zero-exposure model
---

IronClaw uses a zero-exposure credential model: secrets are encrypted at rest and never exposed to untrusted code.

## Overview

<Frame>
  <img src="/assets/secrets-overview.svg" alt="Secrets Management Diagram" />
</Frame>

<Note>
  [Download the Excalidraw file](/assets/secrets-overview.excalidraw) to explore or edit this diagram.
</Note>

<Frame>
  <img src="/assets/secrets-encryption-flow.svg" alt="Secrets Encryption Flow" />
</Frame>

<Note>
  [Download the Excalidraw file](/assets/secrets-encryption-flow.excalidraw) to explore or edit this diagram.
</Note>

## Zero-Exposure Model

Secrets follow a strict lifecycle:

1. **Stored encrypted** — AES-256-GCM in database
2. **Master key in keychain** — OS-managed, hardware-backed
3. **Injected at proxy boundary** — HTTP requests only
4. **Containers never see raw values** — Safe even if compromised

<Frame>
  <img src="/assets/secrets-zero-exposure.svg" alt="Zero-Exposure Credential Model" />
</Frame>

<Note>
  [Download the Excalidraw file](/assets/secrets-zero-exposure.excalidraw) to explore or edit this diagram.
</Note>

## Encryption

### Algorithm: AES-256-GCM

- **Key size**: 256 bits
- **Mode**: GCM (Galois/Counter Mode)
- **Authentication**: Built-in AEAD

### Key Hierarchy

```shell
Master Key (from OS keychain)
    │
    ├──► SecretsCrypto
    │       │
    │       └──► Encrypt/Decrypt secrets
    │
    └──► Derived per-secret keys
```

## Master Key Sources

The master key can come from three sources:

| Source | Security | Convenience |
|--------|----------|-------------|
| **OS Keychain** | ★★★★★ | ★★★☆☆ |
| **Environment Variable** | ★★★☆☆ | ★★★★★ |
| **Skip** | ★☆☆☆☆ | ★★★★★ |

### OS Keychain (Recommended)

- **macOS**: Keychain Access
- **Linux**: GNOME Keyring or KWallet
- **Windows**: Windows Credential Store

```bash
# Generated and stored automatically
# Two system dialogs on first use (normal)
```

### Environment Variable

```bash
export SECRETS_MASTER_KEY="32-byte-hex-encoded-key"

# Generate a key
openssl rand -hex 32
```

## Secret Storage

Secrets are stored in the `secrets` database table:

| Column | Type | Description |
|--------|------|-------------|
| `user_id` | TEXT | Owner |
| `name` | TEXT | Secret identifier |
| `value` | BLOB | Encrypted value |
| `created_at` | TIMESTAMP | Creation time |
| `updated_at` | TIMESTAMP | Last update |

## Managing Secrets

### Via Wizard

Secrets are configured during onboarding:

```bash
ironclaw onboard
```

### Via CLI

```bash
# List secrets
ironclaw secret list

# Get a secret (decrypted)
ironclaw secret get telegram_bot_token

# Set a secret
ironclaw secret set telegram_bot_token "your-token"

# Delete a secret
ironclaw secret delete telegram_bot_token
```

### Environment Variables

Some secrets can be set via env vars:

```bash
export TELEGRAM_BOT_TOKEN="your-token"
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
```

## Secret Names

Common secret names used by IronClaw:

| Name | Used By | Source |
|------|---------|--------|
| `telegram_bot_token` | Telegram channel | @BotFather |
| `telegram_webhook_secret` | Telegram channel | Generated |
| `llm_openai_api_key` | OpenAI provider | platform.openai.com |
| `llm_anthropic_api_key` | Anthropic provider | console.anthropic.com |
| `llm_compatible_api_key` | OpenAI-compatible | Provider |
| `llm_nearai_api_key` | NEAR AI Cloud | cloud.near.ai |

## Platform Notes

### macOS

Two system dialogs on first keychain access:
1. "Enter your password to unlock the keychain"
2. "Allow ironclaw to access this keychain item"

Click "Always Allow" to minimize prompts.

### Linux

Requires `gnome-keyring`:

```bash
# Ubuntu/Debian
sudo apt install gnome-keyring

# Fedora
sudo dnf install gnome-keyring

# Arch
sudo pacman -S gnome-keyring
```

### Windows

Uses Windows Data Protection API (DPAPI). No additional setup required.

## Security Best Practices

1. **Use OS keychain** when possible
2. **Generate strong master keys** if using env var mode
3. **Rotate secrets regularly**
4. **Audit secret access** via logs
5. **Never commit secrets** to version control

## Troubleshooting

<AccordionGroup>
  <Accordion title="Keychain prompts repeatedly" icon="refresh-cw">
    On macOS, click "Always Allow" on the keychain dialog. This is expected OS behavior.
  </Accordion>

  <Accordion title="Keychain not available on Linux" icon="linux">
    Install `gnome-keyring`:
    ```bash
    sudo apt install gnome-keyring
    ```

    Or use environment variable mode in Step 2.
  </Accordion>

  <Accordion title="Secret not found" icon="search">
    - Check secret name spelling
    - Verify secret was saved during onboarding
    - Re-run `ironclaw onboard` to reconfigure
  </Accordion>

  <Accordion title="Decryption fails" icon="key">
    - Master key may have changed
    - Database may be corrupted
    - Try restoring from backup
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Safety Layer" icon="shield" href="/security/safety-layer">
    Prompt injection defense
  </Card>

  <Card title="Sandbox" icon="container" href="/security/sandbox">
    WASM and Docker isolation
  </Card>
</CardGroup>