firekeep

Secure local credential vault. Encrypted JSON storage. CLI-first, core library open for GUI builders.

Install

cargo install --path firekeep-cli

Quick start

# Create vault
firekeep init

# Unlock (starts background daemon)
firekeep unlock

# Add secrets
firekeep add -n "GitHub" -u email -l github.com
firekeep add -n "Server SSH" -u root -t work,ssh

# List all
firekeep list

# Get details
firekeep get GitHub --show-password

# Generate passwords
firekeep gen
firekeep gen -l 32 --no-symbols

# Lock vault
firekeep lock

Encryption

master password → Argon2id → 256-bit key → XChaCha20-Poly1305 → encrypted vault.fire

• Salt: random 32 bytes, stored plain in vault file
• Nonce: random 24 bytes per encryption, prepended to ciphertext
• File: ~/.firekeep/vault.fire (single JSON, fully encrypted)

Vault format

{
  "version": 1,
  "salt": "<base64>",
  "data": "<base64 ciphertext>"
}

Decrypted payload:

{
  "version": 1,
  "entries": [
    {
      "id": "uuid-v4",
      "name": "GitHub",
      "url": "github.com",
      "username": "user@email.com",
      "password": "secret",
      "notes": "",
      "tags": ["dev"],
      "created_at": "2026-04-28T...",
      "updated_at": "2026-04-28T..."
    }
  ]
}

Architecture

firekeep-core (library) → firekeep-cli (binary)
         ↑
    GUI / TUI / other consumers

• daemon: holds decrypted vault in memory, listens on Unix socket (~/.firekeep/daemon.sock)
• auto-lock: exits daemon after configurable timeout of inactivity (default 15 min)
• lock: manual lock kills daemon, zeroizes memory

Commands

Command	Description
init	Create new vault
unlock	Unlock vault, start daemon (--timeout 5 for 5 min)
lock	Lock vault, stop daemon
status	Show vault path and lock state
add	Add entry (interactive or -n -u -l -t)
get <name>	Get entry (-p to show password)
list	List entries (-t <tag> to filter)
edit <name>	Edit entry interactively
delete <name>	Delete entry (-y to skip confirm)
gen	Generate password (-l 20 --no-symbols -c for clipboard)
export	Export vault decrypted (`-f json
import	Import entries (-f csv file.csv)

Core API

use firekeep_core::{Vault, Entry, PasswordSpec, generate_password, ExportFormat};

// Create vault
Vault::create("vault.fire".as_ref(), "master_password")?;

// Open and use
let mut vault = Vault::open("vault.fire".as_ref(), "master_password")?;
vault.add(Entry::new("GitHub".into()))?;
let entries = vault.list(None);
vault.save()?;

// Export / import
let json = vault.export(ExportFormat::Json)?;
vault.import(&json, ExportFormat::Json)?;

// Password generation
let pwd = generate_password(PasswordSpec::default().length(32).symbols(false));

Requirements

• Rust 1.70+
• Linux / macOS (Unix domain sockets)
• Optional: xclip or wl-copy for clipboard support

License

MIT