# Operations Runbook

## 1. Provisioning a New Operator

1. Install Rust toolchain (1.81+) and clone repository.
2. Build release binary:
   ```bash
   cargo build --release
   install -m 0755 target/release/black-bag ~/.local/bin/black-bag
   ```
3. Initialize vault:
   ```bash
   black-bag init --mem-kib 262144
   ```
4. Store Shamir recovery shares offline:
   ```bash
   black-bag recovery split --threshold 3 --shares 7
   ```
5. Record Argon2 parameters (`black-bag doctor`) in secure onboarding log.

## 2. Daily Use Checklist

- Launch inside a clean terminal session (`HISTCONTROL=ignorespace`, no shell logging).
- Source any necessary environment (no secrets in shell history).
- Unlock vault when needed:
  ```bash
  black-bag list --kind login
  ```
- Use `--query` / `--tag` to narrow results; secrets remain masked until `--reveal`.
- Always `black-bag get <UUID> --reveal` inside a TTY to view plaintext.
- Use `black-bag totp code <UUID>` to generate MFA tokens (add `--time <unix>` for historical checks).
- Rotate KEK weekly or after missions:
  ```bash
  black-bag rotate
  ```

## 3. Backup Procedure

1. Close all active black-bag sessions.
2. Copy ciphertext file while verifying timestamp:
   ```bash
   cp ~/.config/black_bag/vault.cbor /offline/secure/vault-$(date +%Y%m%d).cbor
   ```
3. Transport only over encrypted channels (age, minisign, scp over WireGuard).
4. Verify integrity at destination via `black-bag doctor` (requires passphrase).

## 4. Recovery Procedure

1. Gather required Shamir shares (e.g., any 3 of 7).
2. Reconstruct secret:
   ```bash
   black-bag recovery combine --shares share1,share2,share3
   ```
3. Use recovered value to bootstrap new master passphrase or offline escrow plan.
4. Reissue new shares post-recovery to maintain secret splitting hygiene.

## 5. Incident Response

- **Suspected compromise**: immediately rotate KEK, change affected secrets, and issue new Shamir shares.
- **Device loss**: rely on offline backups + shares; assume vault file is exposed.
- **Coercion scenario**: leverage duress planning (out of scope but supported via separate Shamir slots if desired).

## 6. Automation Hooks

- Use `black-bag list --kind api_credential --query prod` to script API key audits.
- Combine with tools like `jq` by first capturing masked summaries (safe to log).
- Avoid scripting decryption; prefer interactive reveal to protect outputs.

## 7. Maintenance

- Weekly `cargo test` / `cargo clippy --all-targets --all-features` to ensure build health.
- Monitor `docs/FURTHER_HARDENING.md` for planned improvements (fuzzing, audits).
- Keep repository in sync; recompile after every update.
