Add logging capability to the lib and cli

[dnovick]

It is important that this library and the CLI have a logging capability.

However, since this is a library, we'll need the capability to be "pluggable" to various logging capabilities.

I think the right way may be some kind of logging class "registration" at startup, with sensible defaults (e.g., stderr).

The capability should use an existing open source C++ logging library and be configurable by the library user or by config file (e.g. JSON file).

[dnovick]

Proposal

Current state

• safe-crypto-lib is header-only and purely std::expected-based — no output of any kind.
• safe-crypto-cli has cli_error.hpp with a die() function that writes to std::cerr and calls std::exit(1). No structured logging exists anywhere.

---

Logging library: spdlog

spdlog (v1.15.x, Apache-2.0) is the recommended library.

• Header-only mode (SPDLOG_HEADER_ONLY) — matches the project's existing header-only library style
• Integrates cleanly with FetchContent (same pattern as CLI11, GTest, benchmark)
• Named loggers with a global registry, making "registration at startup" natural
• Multiple built-in sinks: stderr_color_sink, stdout_color_sink, rotating_file_sink, daily_file_sink
• Runtime log-level filtering (trace/debug/info/warn/error/critical/off)
• Thread-safe by default

---

Architecture

Layer 1 — Library hook (safe-crypto-lib/crypto_log.hpp)

A zero-dependency shim the library calls internally. No spdlog dependency here — the library stays dependency-free.

enum class LogLevel : uint8_t { Debug, Info, Warn, Error };

// Register a sink callable before any library operation.  Passing nullptr disables logging.
// Thread-safe after initial registration (intended to be called once at startup).
void crypto_set_log_sink(std::function<void(LogLevel, std::string_view)> sink);

// Used internally by the library.  No-op when no sink is registered.
void crypto_log(LogLevel level, std::string_view msg);

crypto_log is implemented with a std::atomic<bool> guard (sink_registered) and a std::shared_ptr<LogSink> protected by a std::mutex, so the common fast path (no sink registered, or reading an already-set sink) is lock-free.

The library will log only non-sensitive data: error conditions that mirror CryptoError.message() at Error level, and coarse operation lifecycle events at Debug level. Key material and plaintext are never logged.

Layer 2 — CLI integration (safe-crypto-cli/cli_logging.hpp)

Wires spdlog to the library hook at CLI startup:

// Called from main() before subcommand dispatch.
// Reads --log-level flag and optional --log-config <path> JSON file.
void cli_init_logging(spdlog::level::level_enum level,
                      const std::string& config_path = "");

cli_init_logging creates an spdlog logger (default: stderr_color_sink), then calls crypto_set_log_sink(...) to forward library events into it.

Layer 3 — JSON config file (optional, CLI only)

A --log-config <path> option on scli reads a JSON file:

{
  "level": "debug",
  "sinks": [
    { "type": "stderr" },
    { "type": "file", "path": "/var/log/scli.log", "max_size_mb": 10, "max_files": 3 }
  ]
}

JSON parsing uses nlohmann/json (v3.x, MIT, header-only, FetchContent). If --log-config is not supplied, the CLI defaults to stderr at warn level.

---

CMake additions

File	Purpose
cmake/PermSpdlog.cmake	FetchContent for spdlog v1.15.x
cmake/PermNlohmannJson.cmake	FetchContent for nlohmann/json v3.x

Both follow the existing PermGTest.cmake / PermCLI11.cmake pattern.

---

New files

File	Description
safe-crypto-lib/crypto_log.hpp	Zero-dependency library log hook
safe-crypto-cli/cli_logging.hpp	spdlog initialisation; wires hook

safe-crypto-lib/CMakeLists.txt and safe-crypto-cli/CMakeLists.txt each get minimal additions (one target_sources line; the CLI also gets target_link_libraries for spdlog and nlohmann_json).

---

Delivery plan (3 sequential PRs)

PR A — Library hook

• Add crypto_log.hpp to safe-crypto-lib
• Insert crypto_log(LogLevel::Error, ...) calls at key failure sites (e.g. where CryptoError is constructed in the providers)
• No new CMake dependencies; hook is a no-op by default

PR B — CLI spdlog integration

• cmake/PermSpdlog.cmake
• cli_logging.hpp
• Wire --log-level into main.cpp (CLI11 option, default warn)
• Update cli_error.hpp's die() to also route through the logger

PR C — JSON config file

• cmake/PermNlohmannJson.cmake
• --log-config <path> CLI option
• JSON parsing in cli_logging.hpp for sink selection and level

---

Security notes

• The library hook is opt-in and silent by default — existing callers that do not register a sink are unaffected.
• Log messages in the library must never include key bytes, IVs, plaintexts, or digests. Reviewers should enforce this during PR review.
• File sinks created by the CLI should be opened with mode 0600 (owner-only), consistent with write_secret_output.

[dnovick]

Addendum: Debug success-path tracing

In addition to Error-level logging at failure sites, the library should emit Debug-level traces at operation boundaries on the success path. This gives callers a complete diagnostic picture without needing to instrument their own code.

What gets traced

Each top-level library operation emits two Debug events:

When	Example message
Entry	"aes256_gcm_encrypt: plaintext=1024 bytes, aad=16 bytes"
Success return	"aes256_gcm_encrypt: ok, ciphertext=1040 bytes"

Sizes and algorithm names are safe to log. Key bytes, IVs, plaintexts, and ciphertexts are never included — this rule is enforced at PR review.

Fast-path cost

A bare crypto_log(Debug, ...) call at every operation entry/exit would impose an atomic-load overhead even in production (where no sink is registered). To eliminate this, crypto_log.hpp exposes a cheap predicate:

[[nodiscard]] inline bool crypto_log_enabled(LogLevel level) noexcept;

Implemented as a single std::memory_order_relaxed atomic load against the registered level threshold. Call sites wrap the trace in:

if (crypto_log_enabled(LogLevel::Debug)) {
    crypto_log(LogLevel::Debug, format_entry_msg(...));
}

When no sink is registered (the default), crypto_log_enabled returns false immediately and the message string is never constructed. The compiler can inline and eliminate the branch entirely in release builds.

Scope

Success-path tracing is added in PR A alongside the error-site logging — same header, same call-site pattern — so the full entry/exit instrumentation lands as a single reviewable diff.

[dnovick]

Completed by PRs #185, #186, and #187: library logging hook, CLI spdlog integration, JSON log config, and file-sink permission handling are merged.