<!-- source: https://deepwiki.com/qhkm/zeptoclaw/5.3-secrets-management -->

# Secrets Management

- src/cli/secrets.rs
- src/config/mod.rs
- src/config/types.rs
- src/security/encryption.rs
- src/security/mod.rs
- src/security/mount.rs
- src/security/path.rs

## Purpose and Scope

This page documents ZeptoClaw's secrets management system, which protects sensitive values in `config.json` (API keys, access tokens, webhook secrets) and OAuth credentials through encryption. The system provides:

- Inline encryption via ENC[...] values in the configuration file using XChaCha20-Poly1305 src/security/encryption.rs 1-14
- Master key derivation using Argon2id from environment variables or interactive passphrases src/security/encryption.rs 173-182
- Automatic decryption during config load src/config/mod.rs 83-88
- CLI commands for encrypting, decrypting, and rotating secrets src/cli/secrets.rs 14-20
- Mount and Path validation to prevent accidental exposure of host secrets during tool execution src/security/mount.rs 12-27

**Sources:** [src/config/types.rs1-139](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/types.rs#L1-L139) [src/config/mod.rs1-71](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/mod.rs#L1-L71) [src/security/encryption.rs1-14](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/encryption.rs#L1-L14)

## ENC[...] Inline Encryption Format

Sensitive configuration values are encrypted inline using a versioned envelope format. When the config file is loaded, any `ENC[...]` string values are automatically decrypted before the JSON is deserialized into the `Config` struct [src/config/mod.rs78-90](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/mod.rs#L78-L90)

### Supported Fields

The `is_secret_field` helper identifies fields that should be encrypted [src/security/encryption.rs14](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/encryption.rs#L14-L14) Common fields include:

### Encryption Format

The envelope follows this structure: `ENC[version:salt_b64:nonce_b64:ciphertext_b64]` [src/security/encryption.rs4-13](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/encryption.rs#L4-L13)

- Version : Currently 1 src/security/encryption.rs 34
- Salt : 16-byte random salt for Argon2id src/security/encryption.rs 28
- Nonce : 24-byte random nonce for XChaCha20 src/security/encryption.rs 31
- Ciphertext : AEAD output (plaintext + 16-byte Poly1305 tag) src/security/encryption.rs 13

**Sources:** [src/security/encryption.rs1-167](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/encryption.rs#L1-L167) [src/config/types.rs22-51](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/types.rs#L22-L51)

## Master Key Resolution

The `SecretEncryption` instance is initialized by resolving a master key. This happens during `Config::load_from_path` if encrypted values are detected [src/config/mod.rs83-88](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/mod.rs#L83-L88)

```

```

**Diagram: Master Key Resolution and Derivation**

### Key Derivation (Argon2id)

ZeptoClaw uses Argon2id to derive a 32-byte key from a passphrase. The parameters follow OWASP recommendations: 64MB memory, 3 iterations, and 1 parallelism factor [src/security/encryption.rs173-182](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/encryption.rs#L173-L182)

**Sources:** [src/config/mod.rs78-90](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/mod.rs#L78-L90) [src/security/encryption.rs173-185](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/encryption.rs#L173-L185)

## Configuration Decryption Flow

The decryption process is transparent to the rest of the application. It occurs after the file is read into a `serde_json::Value` but before it is cast into the `Config` struct [src/config/mod.rs78-90](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/mod.rs#L78-L90)

```

```

**Diagram: In-place JSON Decryption Flow**

**Sources:** [src/config/mod.rs78-90](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/mod.rs#L78-L90) [src/cli/secrets.rs104-128](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/secrets.rs#L104-L128)

## Secrets CLI Commands

The `zeptoclaw secrets` command (dispatched via `cmd_secrets`) provides management utilities [src/cli/secrets.rs14-20](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/secrets.rs#L14-L20)

### secrets encrypt

Reads `config.json`, identifies plaintext secret fields (via `is_secret_field`), encrypts them using the master key, and writes the file back [src/cli/secrets.rs27-45](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/secrets.rs#L27-L45) It skips values that are already encrypted [src/cli/secrets.rs56](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/secrets.rs#L56-L56)

### secrets decrypt

Reverses the encryption process, converting all `ENC[...]` envelopes back to plaintext in `config.json` [src/cli/secrets.rs82-100](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/secrets.rs#L82-L100)

### secrets rotate

Rotates the master key for all secrets [src/cli/secrets.rs135-173](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/secrets.rs#L135-L173):

1. Decrypts all secrets using the current master key src/cli/secrets.rs 146-147
2. Prompts for a new master passphrase src/cli/secrets.rs 152-161
3. Re-encrypts all values using a new SecretEncryption instance src/cli/secrets.rs 163-165

**Sources:** [src/cli/secrets.rs1-173](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/secrets.rs#L1-L173)

## Path and Mount Security

To prevent LLMs from accessing or leaking host secrets via tool execution, ZeptoClaw implements several security layers:

### Blocked Patterns

The system maintains a list of `DEFAULT_BLOCKED_PATTERNS` including `.ssh`, `.aws`, `.env`, and private key files [src/security/mount.rs12-27](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/mount.rs#L12-L27) These are checked during runtime mount validation [src/security/mount.rs198-215](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/mount.rs#L198-L215)

### Path Validation

The `SafePath` struct and `validate_path_in_workspace` function ensure that file operations remain within the designated workspace, preventing directory traversal and symlink-based escapes [src/security/path.rs11-31](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/path.rs#L11-L31) [src/security/path.rs70-130](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/path.rs#L70-L130)

```

```

**Diagram: Security Validation Entities**

**Sources:** [src/security/mount.rs12-27](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/mount.rs#L12-L27) [src/security/path.rs11-130](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/path.rs#L11-L130) [src/security/mod.rs1-21](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/mod.rs#L1-L21)

## Environment Variable Overrides

ZeptoClaw supports an environment variable overlay mechanism. Variables following the pattern `ZEPTOCLAW_SECTION_SUBSECTION_KEY` override config file values [src/config/mod.rs66-67](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/mod.rs#L66-L67)

This overlay occurs in `apply_env_overrides` after the config file has been loaded and decrypted [src/config/mod.rs95-96](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/mod.rs#L95-L96)

**Sources:** [src/config/mod.rs63-142](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/mod.rs#L63-L142)
