Encrypted Vault¶

Missy's Vault provides ChaCha20-Poly1305 authenticated encryption for API keys, tokens, and other credentials. Secrets are stored encrypted on disk and referenced in config files via vault:// URIs, keeping plaintext credentials out of YAML entirely.

How It Works¶

graph LR
    A["missy vault set KEY val"] --> B[Vault]
    B --> C["Load vault.key (32 bytes)"]
    C --> D["Decrypt vault.enc → JSON dict"]
    D --> E["Add/update key-value pair"]
    E --> F["Re-encrypt → nonce + ciphertext"]
    F --> G["Atomic write → vault.enc"]

    H["config.yaml: vault://KEY"] --> I["load_config()"]
    I --> J["Vault.resolve('vault://KEY')"]
    J --> K["Decrypt + return value"]

Encryption Details¶

File Locations¶

Setup¶

Enable the Vault¶

# ~/.missy/config.yaml
vault:
  enabled: true
  vault_dir: "~/.missy/secrets"   # Default location

Requirements¶

The vault requires the cryptography Python package:

pip install cryptography

This is included in the base Missy installation. If you see a VaultError about a missing package, reinstall:

pip install -e ".[dev]"

CLI Commands¶

Store a Secret¶

missy vault set ANTHROPIC_API_KEY sk-ant-api03-your-key-here
missy vault set OPENAI_API_KEY sk-proj-your-key-here
missy vault set DISCORD_TOKEN your-bot-token

Retrieve a Secret¶

missy vault get ANTHROPIC_API_KEY
# Output: sk-ant-api03-your-key-here

List All Keys¶

missy vault list
# Output:
# ANTHROPIC_API_KEY
# OPENAI_API_KEY
# DISCORD_TOKEN

Delete a Secret¶

missy vault delete OPENAI_API_KEY

Config File References¶

Use vault://KEY_NAME in any config field that accepts a secret:

providers:
  anthropic:
    name: anthropic
    model: "claude-sonnet-4-6"
    api_key: "vault://ANTHROPIC_API_KEY"

  openai:
    name: openai
    model: "gpt-4o"
    api_key: "vault://OPENAI_API_KEY"
    api_keys:
      - "vault://OPENAI_KEY_1"
      - "vault://OPENAI_KEY_2"

During config loading, vault:// references are resolved transparently. The provider receives the decrypted secret, never the reference string.

Environment Variable References¶

The vault resolver also supports $ENV_VAR syntax as a fallback:

providers:
  anthropic:
    api_key: "$ANTHROPIC_API_KEY"   # Read from environment

Resolution Priority¶

Key File Security¶

Automatic Protections¶

The vault implements several protections for the key file:

1. Atomic exclusive creation -- The key file is created with O_CREAT | O_EXCL, preventing TOCTOU race conditions. If the file already exists, it is read instead of overwritten.

2. Strict permissions -- The key file is created with 0600 (owner read/write only). The vault directory is created with 0700.

3. Symlink rejection -- If the key file is a symlink, the vault refuses to read it. This prevents an attacker from replacing the key file with a symlink to a controlled location.

4. Hard link detection -- If the key file has multiple hard links (st_nlink > 1), the vault refuses to read it. This prevents an attacker from creating a hard link to monitor key file access.

5. Length validation -- The key must be exactly 32 bytes. Truncated or padded files are rejected.

Atomic Writes¶

The encrypted vault file is written atomically:

1. Create a temporary file in the same directory with correct permissions (0600).
2. Write the encrypted data and fsync.
3. Rename the temp file to vault.enc (atomic on POSIX).

This prevents data loss if the process crashes mid-write.

Backup Recommendations¶

# Back up the vault (both files required for restoration)
cp ~/.missy/secrets/vault.key /secure/backup/vault.key
cp ~/.missy/secrets/vault.enc /secure/backup/vault.enc
chmod 600 /secure/backup/vault.key /secure/backup/vault.enc

Programmatic Usage¶

from missy.security.vault import Vault

vault = Vault()  # Uses default ~/.missy/secrets

# Store
vault.set("MY_SECRET", "secret-value")

# Retrieve
value = vault.get("MY_SECRET")  # Returns None if not found

# Delete
vault.delete("MY_SECRET")  # Returns True if existed

# List keys
keys = vault.list_keys()  # ["ANTHROPIC_API_KEY", ...]

# Resolve references
secret = vault.resolve("vault://MY_SECRET")      # From vault
secret = vault.resolve("$MY_ENV_VAR")             # From environment
secret = vault.resolve("literal-value")           # Passthrough

Security Comparison¶