Create a persistent key store and API

[dnovick]

It would be good if we had a persistent key store with associated APIs and CLI support.

[dnovick]

Proposed Design: Persistent Key Store

Background

The existing in-memory key stores (symmetric, EC, RSA, PQC) are slot-based, process-local, and lost on process exit. This proposal adds an optional persistent layer on top, usable from the library, the CLI, or any app that uses the lib.

---

Core Questions and Proposed Answers

1. How do we protect the stored keys?

Stored keys must be encrypted at rest. We need a wrapping key to do this. Options:

Approach	Portability	Security	Complexity
Password/passphrase-derived (HKDF-SHA-384)	Full cross-platform	Good — depends on passphrase quality	Low
OS keychain (Keychain on macOS, Secret Service on Linux)	Platform-specific	Strong — OS enforces access control	High
Hardware key (TPM/Secure Enclave)	Very limited	Strongest	Very high

Recommendation: Start with password-derived wrapping key — it has no external dependencies and works everywhere we already CI. Define an abstract IWrappingKeySource interface so OS-keychain or hardware backends can be plugged in later without changing the store format.

Derivation:

1. User provides a passphrase.
2. A random 32-byte salt is generated and stored in the store header (plaintext).
3. HKDF-SHA-384(IKM=passphrase_bytes, salt=file_salt, info="safe-crypto-keystore-v1") → 32-byte AES-256 wrapping key.
4. The wrapping key never touches disk; it lives only in a FixedSecureBuffer<32> and is zeroed when the store is closed.

Re-keying (passphrase change) decrypts with the old wrapping key, generates a new salt, and re-encrypts in place (via atomic write).

2. File format: single encrypted file vs. directory of per-key files

Recommendation: single encrypted file, written atomically (write to temp, rename(2)).

• Simpler: no directory-scan logic, no partial-import edge cases.
• Atomic updates: rename is atomic on POSIX; no torn writes.
• Consistent: the whole store is one unit of integrity — the AES-256-GCM tag covers everything.
• Downside: larger stores must be fully read and re-written on every mutation. At the key counts we expect (tens, not millions), this is negligible.

3. Store file layout

[HEADER — plaintext]
  magic:       8 bytes   "SCKEYSTR"
  version:     2 bytes   uint16_be = 1
  salt:       32 bytes   random, used for HKDF wrapping-key derivation
  nonce:      12 bytes   random, AES-256-GCM nonce

[PAYLOAD — AES-256-GCM ciphertext + 16-byte tag]
  Encrypted with wrapping key derived from salt + passphrase.
  Decrypted contents: length-prefixed sequence of key entries.

[KEY ENTRY — repeated inside the payload]
  name_len:    1 byte    uint8
  name:        N bytes   UTF-8, max 255 bytes
  key_type:    1 byte    enum (see below)
  meta_len:    1 byte    uint8
  meta:        M bytes   type-specific metadata (curve id, bit width, variant)
  key_len:     2 bytes   uint16_be
  key_bytes:   K bytes   raw key material (same encoding as in-memory stores)
  created_at:  8 bytes   uint64_be, Unix timestamp seconds

Key types (enum): SymmetricKey, EcPrivate, EcPublic, RsaPrivate, RsaPublic, PqcPrivate, PqcPublic.

No external schema dependency; the format is self-describing enough for round-trip fidelity and is version-gated.

4. Cross-platform file paths

Default locations (all overridable via explicit path or SAFE_CRYPTO_KEYSTORE_PATH env var):

Platform	Default path
macOS	~/Library/Application Support/safe-crypto/keystore.skst
Linux	$XDG_DATA_HOME/safe-crypto/keystore.skst (fallback: ~/.local/share/safe-crypto/keystore.skst)

File created with mode 0600 (same as existing secret output files in the CLI).

---

C++ Library API

New optional header safe-crypto-lib/key_store_persistent.hpp, no required includes beyond what's already in the lib. Provider-agnostic — uses the lib's own AES-256-GCM and HKDF via the active provider.

// Opaque key info returned by list()
struct PersistentKeyInfo {
    std::string  name;
    PersistentKeyType type;
    std::uint64_t created_at;   // Unix timestamp
};

class PersistentKeyStore {
public:
    // Open existing store or create new one; returns error if passphrase is wrong.
    [[nodiscard]]
    static auto open(const std::filesystem::path& path, std::string_view passphrase)
        -> std::expected<PersistentKeyStore, std::string>;

    // Import raw key material under a name; fails if name already exists.
    [[nodiscard]]
    auto import_key(std::string_view name, PersistentKeyType type,
                    CByteSpan<std::dynamic_extent> key_material,
                    ByteSpan<std::dynamic_extent>  meta = {})
        -> std::expected<void, std::string>;

    // Export key material into a SecureBuffer (zeroed on destruction).
    [[nodiscard]]
    auto export_key(std::string_view name) const
        -> std::expected<SecureBuffer, std::string>;

    // Load a named key into the active provider's in-memory store; returns KeyId.
    [[nodiscard]]
    auto load_key(std::string_view name) const
        -> std::expected<unsigned int, std::string>;

    // List all stored key names and types.
    [[nodiscard]]
    auto list_keys() const -> std::vector<PersistentKeyInfo>;

    // Delete a key entry; re-encrypts and writes the store.
    [[nodiscard]]
    auto delete_key(std::string_view name)
        -> std::expected<void, std::string>;

    // Re-encrypt the store with a new passphrase.
    [[nodiscard]]
    auto rekey(std::string_view new_passphrase)
        -> std::expected<void, std::string>;

    // Explicitly close and zero in-memory state (also happens on destruction).
    void close() noexcept;

    ~PersistentKeyStore();
    // Move-only (no copy — prevents accidental duplication of key material).
    PersistentKeyStore(PersistentKeyStore&&) noexcept;
    PersistentKeyStore& operator=(PersistentKeyStore&&) noexcept;
    PersistentKeyStore(const PersistentKeyStore&) = delete;
    PersistentKeyStore& operator=(const PersistentKeyStore&) = delete;
};

The wrapping key (FixedSecureBuffer<32>) is held as a private member and zeroed on close/destruction. The decrypted payload is never held fully in memory except during a single operation.

---

CLI Commands

New keystore subcommand group:

scli keystore init   [--path <path>]
    Create a new empty key store. Prompts for passphrase (or reads from
    SAFE_CRYPTO_KEYSTORE_PASSPHRASE env var for scripted use).

scli keystore import --name <name> --type <type> --key <input-spec> [--path <path>]
    Import a key. --type: symmetric | ec-private | ec-public | rsa-private |
                          rsa-public | pqc-private | pqc-public
    --key uses the standard input spec (file path, base64:<data>, or "-").

scli keystore export --name <name> [--output <output-spec>] [--path <path>]
    Export a key to stdout (base64) or a file.

scli keystore load   --name <name> [--path <path>]
    Load a key into the active provider's in-memory store. Prints the KeyId
    so it can be used with other scli commands in the same process.

scli keystore list   [--path <path>]
    Print key names, types, and creation timestamps.

scli keystore delete --name <name> [--path <path>]
    Remove a key entry and re-encrypt the store.

scli keystore rekey  [--path <path>]
    Change the store passphrase (prompts for old then new).

---

Implementation Plan (proposed PRs)

PR	Scope
A	Store format + crypto: PersistentKeyStore class with open, import_key, export_key, list_keys, delete_key, rekey, close. Full test suite in safe-crypto-lib-test/.
B	load_key: bridge from persistent store into active provider's in-memory store, covering all key types. Tests per provider.
C	CLI: scli keystore subcommand group. Integration tests in safe-crypto-cli-test/.
D	Default-path logic: XDG/Library path resolution, SAFE_CRYPTO_KEYSTORE_PATH env var, README docs.

---

Open Questions / Decisions Needed

1. Passphrase input in CLI — read from SAFE_CRYPTO_KEYSTORE_PASSPHRASE env var for scripted use, or require interactive terminal prompt, or both? Should we emit a warning if the env var is used (since it may appear in process listings)?

2. Key naming constraints — allow arbitrary UTF-8 up to 255 bytes, or restrict to [a-zA-Z0-9_.-] for safety? Restricted names are easier to use safely on the command line.

3. load_key lifetime — the in-memory KeyId is valid for the process lifetime (until explicitly destroyed). Should PersistentKeyStore track which KeyIds it has loaded and destroy them on close()? This provides cleaner automatic cleanup but adds coupling to the in-memory store.

4. Concurrency — a single store-level mutex is sufficient for in-process use. For multi-process access (e.g., two CLI invocations simultaneously), a file advisory lock (flock(2)) should guard read-modify-write on the store file. Worth adding from the start or defer?

5. Key metadata depth — the current proposal stores just enough to round-trip the key (type + minimal variant info). Should we also store usage constraints (sign-only, encrypt-only, not-before/not-after timestamps)?

6. Windows — not currently in CI. The path conventions and file-permission model differ. Stub out the path logic behind a compile-time #ifdef now, or defer entirely?