# black-bag

`black-bag` is a zero-trace, no-compromise command-line vault for high-risk operators. It ships as a single Rust binary with the strongest defaults we can provide: Argon2id hardening, ML-KEM-1024 cascaded wrapping (Kyber), XChaCha20-Poly1305 payload encryption, zeroization of every secret buffer, and page-locked memory on Unix. There is no optional telemetry, no cloud, no GUI—just a laser-focused CLI that keeps secrets safe even under hostile conditions.

## Highlights

- **Zero-trace posture** – secrets never touch stdout, logs, temp files, or the clipboard. All input happens via hidden TTY prompts and is stored only after AEAD encryption.
- **Modern crypto pipeline** – Argon2id → ML-KEM-1024 (Kyber) → random 32-byte DEKs sealed with XChaCha20-Poly1305. Writes are atomic/fdatasync’d with strict permissions and zeroized in memory on drop.
- **Rich record catalogue** – logins, contacts, identity docs, secure notes, payment cards, SSH keys, PGP keys, TOTP seeds, recovery kits, bank accounts, Wi-Fi profiles, API credentials, and crypto wallets. Every record supports tagging and full-text queries.
- **Cross-platform parity** – builds cleanly on macOS, Linux, and Windows. `mlock` is enabled automatically on supported Unix platforms and degrades gracefully elsewhere.
- **Security by default** – all protective features are enabled in every binary; there are no configuration flags that weaken the threat posture.

## Quick start

```bash
# prerequisites: Rust toolchain 1.81+ (via rustup) and a standard build environment
cargo build --release
install -m 0755 target/release/black-bag ~/.local/bin/black-bag

black-bag --help
```

Recommended hygiene:
- Run from an encrypted disk.
- Disable shell history or use `HISTCONTROL=ignorespace` with leading spaces.
- Set `RUST_BACKTRACE=0` in operational shells.

## Creating your vault

```bash
black-bag init --mem-kib 262144
```
You’ll be prompted for the master passphrase twice. The vault stores under the platform data directory (e.g., `~/.config/black_bag/vault.cbor`).

## Adding records

```bash
# login
black-bag add login --title "Ops Portal" --username phoenix --url https://ops.example --tags mission

# contact
black-bag add contact --full-name "Analyst Zero" --emails a0@example --phones "mobile:+1-555-0101,desk:+1-555-0110" --tags handler

# identity document
black-bag add id --id-type passport --name-on-doc "Alex Smith" --number X1234567 --issuing-country US --expiry 2032-08-01

# secure note
black-bag add note --title "Fallback Protocol" --tags red-team

# bank account
black-bag add bank --institution "First Federal" --account-name "Ops budget" --routing-number 021000021 --tags finance

# Wi-Fi profile
black-bag add wifi --ssid "safehouse-net" --security WPA2 --location Berlin --tags infrastructure

# API credential
black-bag add api --service intel-api --environment production --access-key AKIA-123 --scopes read,write --tags automation

# crypto wallet
black-bag add wallet --label btc-cold --asset BTC --address bc1q... --network mainnet --tags treasury

# totp secret
black-bag add totp --title "GitHub MFA" --issuer GitHub --account you@example --secret JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP

# totp codes
black-bag totp code <UUID> --time 59

```

Sensitive fields (passwords, passphrases, API secrets, private keys) are collected via hidden prompts after the command issues—nothing sensitive ever appears in argv or shell history.

## Listing, filtering, and querying

```bash
black-bag list                      # masked summaries
black-bag list --kind bank_account  # filter by record family
black-bag list --tag mission        # filter by tag
black-bag list --query opsnet       # full-text search across metadata
```

Inspect a specific record:
```bash
black-bag get <UUID>
black-bag get <UUID> --reveal      # requires an interactive TTY
```

## Rotation, health, and recovery

- `black-bag rotate` – rewraps the master DEK with fresh randomness.
- `black-bag doctor` – prints health info (Argon2 params, feature flags, item counts).
- `black-bag recovery split` / `combine` – manage Shamir shares for catastrophic recovery.

## Threat model (summary)

See [`docs/THREAT_MODEL.md`](docs/THREAT_MODEL.md) for assumptions, adversary capabilities, and residual risks. Treat the vault ciphertext as sensitive and keep backups offline.

## Building and testing

```bash
cargo fmt
cargo clippy --all-targets --all-features
cargo test
```

CI should run the same three commands on every commit. Tests cover cryptographic round-trips, helper utilities, and zero-trace guarantees.

## Mission-ready checklist

- [x] Argon2id + ML-KEM-1024 + XChaCha20-Poly1305 enabled by default
- [x] No GUI, clipboard, or plaintext log exposure
- [x] Cross-platform parity (Windows/macOS/Linux)
- [x] Comprehensive record catalogue with search & tagging
- [x] Lint/tests clean with zero warnings
- [x] Operator docs and threat model committed

For production roll-out, schedule an independent cryptography/code audit and set up fuzzing pipelines (see [`docs/FURTHER_HARDENING.md`](docs/FURTHER_HARDENING.md)).
