audit_chain.hpp

Go to the documentation of this file.

// SPDX-License-Identifier: AGPL-3.0-or-later
// Copyright 2026 Johnson Ogundeji
// See LICENSE_COMMERCIAL for full terms.
#pragma once
 
#if !defined(SIGNET_ENABLE_COMMERCIAL) || !SIGNET_ENABLE_COMMERCIAL
#error "signet/ai/audit_chain.hpp requires SIGNET_ENABLE_COMMERCIAL=ON (AGPL-3.0 commercial tier). See LICENSE_COMMERCIAL."
#endif
 
// ---------------------------------------------------------------------------
// audit_chain.hpp -- Cryptographic hash chain for tamper-evident audit trails
//
// Provides a SHA-256-based hash chain that guarantees the integrity and
// ordering of AI decision records stored in Parquet files. Each entry in
// the chain commits to all previous entries through a cryptographic link,
// making any retrospective tampering (insertion, deletion, reordering, or
// modification of records) computationally detectable.
//
// Architecture:
//
//   AuditChainWriter   -- Builds hash chains during Parquet writes. Each
//                         record is hashed and linked to its predecessor.
//
//   AuditChainVerifier -- Verifies chain integrity during reads. Can
//                         verify individual entries, entire chains, or
//                         continuity across multiple Parquet files.
//
//   AuditMetadata      -- Stores chain summary in Parquet key-value
//                         metadata for fast cross-file verification
//                         without reading every entry.
//
// Hash chain algorithm:
//
//   entry_hash = SHA-256( LE64(sequence_number)
//                      || LE64(timestamp_ns)
//                      || prev_hash[32]
//                      || data_hash[32] )
//
//   where prev_hash is all zeros for the first entry (or a user-supplied
//   continuation hash when chaining across files).
//
// Binary serialization (112 bytes per entry, little-endian):
//
//   [0:8)    sequence_number  (int64_t LE)
//   [8:16)   timestamp_ns     (int64_t LE)
//   [16:48)  prev_hash        (32 bytes)
//   [48:80)  data_hash        (32 bytes)
//   [80:112) entry_hash       (32 bytes)
//
// Chain serialization: 4-byte entry count (uint32_t LE) followed by
// N entries of 112 bytes each.
//
// Header-only. No external dependencies beyond the project's own SHA-256
// implementation in signet/crypto/post_quantum.hpp.
//
// Part of SignetStack Signet Forge -- Phase 7: AI Decision Audit Trail.
// ---------------------------------------------------------------------------
 
#include "signet/crypto/sha256.hpp"
#include "signet/error.hpp"
#include "signet/types.hpp"
 
#include <array>
#include <atomic>
#include <chrono>
#include <cstdint>
#include <cstring>
#include <iomanip>
#include <sstream>
#include <stdexcept>
#include <string>
#include <vector>
 
namespace signet::forge {
 
// ===========================================================================
// Forward declarations
// ===========================================================================
struct HashChainEntry;    
class  AuditChainWriter;  
class  AuditChainVerifier; 
struct AuditMetadata;      
 
// ===========================================================================
// Constants
// ===========================================================================
 
inline constexpr size_t HASH_CHAIN_ENTRY_SIZE = 112;
 
// ===========================================================================
// Utility functions
// ===========================================================================
 
inline int64_t now_ns() {
    static std::atomic<int64_t> last_ns{0};
    // CWE-362: system_clock (UTC) + atomic CAS loop ensures monotonicity
    // across concurrent callers without mutex overhead.
    // R-5: system_clock provides UTC traceability per MiFID II RTS 25 Art.2.
    auto ns = std::chrono::duration_cast<std::chrono::nanoseconds>(
                  std::chrono::system_clock::now().time_since_epoch()).count();
    int64_t expected = last_ns.load(std::memory_order_acquire);
    while (ns <= expected) { ns = expected + 1; }
    while (!last_ns.compare_exchange_weak(expected, ns,
                std::memory_order_release, std::memory_order_acquire)) {
        if (ns <= expected) ns = expected + 1;
    }
    return ns;
}
 
struct ClockSyncStatus {
    bool is_synchronized{false};      
    int stratum{0};                   
    int64_t offset_ns{0};             
    int64_t max_error_ns{0};          
    std::string sync_source;          
    int64_t last_check_ns{0};         
 
    [[nodiscard]] bool meets_rts25_hft() const {
        return is_synchronized && max_error_ns <= 100'000;
    }
    [[nodiscard]] bool meets_rts25_standard() const {
        return is_synchronized && max_error_ns <= 1'000'000;
    }
};
 
inline std::string hash_to_hex(const std::array<uint8_t, 32>& hash) {
    static constexpr char hex_chars[] = "0123456789abcdef";
    std::string result;
    result.reserve(64);
    for (uint8_t byte : hash) {
        result.push_back(hex_chars[(byte >> 4) & 0x0F]);
        result.push_back(hex_chars[ byte       & 0x0F]);
    }
    return result;
}
 
inline expected<std::array<uint8_t, 32>> hex_to_hash(const std::string& hex) {
    if (hex.size() != 64) {
        return Error{ErrorCode::INVALID_FILE,
                     "hex_to_hash: expected 64 hex characters, got "
                     + std::to_string(hex.size())};
    }
 
    std::array<uint8_t, 32> hash{};
    for (size_t i = 0; i < 32; ++i) {
        char hi = hex[i * 2];
        char lo = hex[i * 2 + 1];
 
        auto hex_val = [](char c) -> int {
            if (c >= '0' && c <= '9') return c - '0';
            if (c >= 'a' && c <= 'f') return 10 + (c - 'a');
            if (c >= 'A' && c <= 'F') return 10 + (c - 'A');
            return -1;
        };
 
        int hi_val = hex_val(hi);
        int lo_val = hex_val(lo);
 
        if (hi_val < 0 || lo_val < 0) {
            return Error{ErrorCode::INVALID_FILE,
                         "hex_to_hash: invalid hex character at position "
                         + std::to_string(i * 2)};
        }
 
        hash[i] = static_cast<uint8_t>((hi_val << 4) | lo_val);
    }
 
    return hash;
}
 
inline std::string generate_chain_id() {
    int64_t ts = now_ns();
    std::ostringstream oss;
    oss << "chain-"
        << std::hex << std::setfill('0') << std::setw(16)
        << static_cast<uint64_t>(ts);
    return oss.str();
}
 
// ===========================================================================
// Internal helpers (detail namespace)
// ===========================================================================
namespace detail::audit {
 
inline void write_le64(uint8_t* dst, int64_t value) {
    auto v = static_cast<uint64_t>(value);
    dst[0] = static_cast<uint8_t>(v);
    dst[1] = static_cast<uint8_t>(v >> 8);
    dst[2] = static_cast<uint8_t>(v >> 16);
    dst[3] = static_cast<uint8_t>(v >> 24);
    dst[4] = static_cast<uint8_t>(v >> 32);
    dst[5] = static_cast<uint8_t>(v >> 40);
    dst[6] = static_cast<uint8_t>(v >> 48);
    dst[7] = static_cast<uint8_t>(v >> 56);
}
 
inline int64_t read_le64(const uint8_t* src) {
    uint64_t v = static_cast<uint64_t>(src[0])
               | (static_cast<uint64_t>(src[1]) << 8)
               | (static_cast<uint64_t>(src[2]) << 16)
               | (static_cast<uint64_t>(src[3]) << 24)
               | (static_cast<uint64_t>(src[4]) << 32)
               | (static_cast<uint64_t>(src[5]) << 40)
               | (static_cast<uint64_t>(src[6]) << 48)
               | (static_cast<uint64_t>(src[7]) << 56);
    return static_cast<int64_t>(v);
}
 
inline void write_le32(uint8_t* dst, uint32_t value) {
    dst[0] = static_cast<uint8_t>(value);
    dst[1] = static_cast<uint8_t>(value >> 8);
    dst[2] = static_cast<uint8_t>(value >> 16);
    dst[3] = static_cast<uint8_t>(value >> 24);
}
 
inline uint32_t read_le32(const uint8_t* src) {
    return static_cast<uint32_t>(src[0])
         | (static_cast<uint32_t>(src[1]) << 8)
         | (static_cast<uint32_t>(src[2]) << 16)
         | (static_cast<uint32_t>(src[3]) << 24);
}
 
} // namespace detail::audit
 
struct HashChainEntry {
    int64_t sequence_number = 0;
 
    int64_t timestamp_ns = 0;
 
    std::array<uint8_t, 32> prev_hash{};
 
    std::array<uint8_t, 32> data_hash{};
 
    std::array<uint8_t, 32> entry_hash{};
 
    inline void compute_entry_hash() {
        // Build the preimage: 8 + 8 + 32 + 32 = 80 bytes
        uint8_t preimage[80];
 
        detail::audit::write_le64(preimage,      sequence_number);
        detail::audit::write_le64(preimage + 8,   timestamp_ns);
        std::memcpy(preimage + 16, prev_hash.data(),  32);
        std::memcpy(preimage + 48, data_hash.data(),  32);
 
        entry_hash = crypto::detail::sha256::sha256(preimage, sizeof(preimage));
    }
 
    [[nodiscard]] inline bool verify() const {
        uint8_t preimage[80];
 
        detail::audit::write_le64(preimage,      sequence_number);
        detail::audit::write_le64(preimage + 8,   timestamp_ns);
        std::memcpy(preimage + 16, prev_hash.data(),  32);
        std::memcpy(preimage + 48, data_hash.data(),  32);
 
        auto expected = crypto::detail::sha256::sha256(preimage, sizeof(preimage));
 
        // Constant-time comparison
        uint8_t diff = 0;
        for (size_t i = 0; i < 32; ++i) {
            diff |= entry_hash[i] ^ expected[i];
        }
 
        return diff == 0;
    }
 
    [[nodiscard]] inline std::vector<uint8_t> serialize() const {
        std::vector<uint8_t> buf(HASH_CHAIN_ENTRY_SIZE);
 
        detail::audit::write_le64(buf.data(),      sequence_number);
        detail::audit::write_le64(buf.data() + 8,   timestamp_ns);
        std::memcpy(buf.data() + 16, prev_hash.data(),  32);
        std::memcpy(buf.data() + 48, data_hash.data(),  32);
        std::memcpy(buf.data() + 80, entry_hash.data(), 32);
 
        return buf;
    }
 
    [[nodiscard]] static inline expected<HashChainEntry> deserialize(
            const uint8_t* data, size_t size) {
 
        if (size < HASH_CHAIN_ENTRY_SIZE) {
            return Error{ErrorCode::CORRUPT_PAGE,
                         "HashChainEntry::deserialize: need "
                         + std::to_string(HASH_CHAIN_ENTRY_SIZE)
                         + " bytes, got " + std::to_string(size)};
        }
 
        HashChainEntry entry;
        entry.sequence_number = detail::audit::read_le64(data);
        entry.timestamp_ns    = detail::audit::read_le64(data + 8);
        std::memcpy(entry.prev_hash.data(),  data + 16, 32);
        std::memcpy(entry.data_hash.data(),  data + 48, 32);
        std::memcpy(entry.entry_hash.data(), data + 80, 32);
 
        return entry;
    }
};
 
class AuditChainWriter {
public:
    inline AuditChainWriter()
        : last_hash_{}
        , next_seq_(0) {
        auto gate = commercial::require_feature("AuditChainWriter");
        (void)gate;
    }
 
    inline HashChainEntry append(const uint8_t* record_data, size_t record_size,
                                 int64_t timestamp_ns) {
        HashChainEntry entry;
        entry.sequence_number = next_seq_;
        entry.timestamp_ns    = timestamp_ns;
        entry.prev_hash       = last_hash_;
        entry.data_hash       = crypto::detail::sha256::sha256(record_data, record_size);
 
        entry.compute_entry_hash();
 
        last_hash_ = entry.entry_hash;
        ++next_seq_;
        entries_.push_back(entry);
 
        return entry;
    }
 
    inline HashChainEntry append(const uint8_t* record_data, size_t record_size) {
        return append(record_data, record_size, now_ns());
    }
 
    [[nodiscard]] inline int64_t length() const {
        return static_cast<int64_t>(entries_.size());
    }
 
    [[nodiscard]] inline std::array<uint8_t, 32> last_hash() const {
        return last_hash_;
    }
 
    [[nodiscard]] inline const std::vector<HashChainEntry>& entries() const {
        return entries_;
    }
 
    [[nodiscard]] inline std::vector<uint8_t> serialize_chain() const {
        // CWE-190: Integer Overflow or Wraparound — guard against entry count
        // exceeding uint32_t range before narrowing cast to the 4-byte header.
        if (entries_.size() > UINT32_MAX) {
            throw std::overflow_error("Audit chain too large to serialize");
        }
        auto count = static_cast<uint32_t>(entries_.size());
        std::vector<uint8_t> buf;
        buf.reserve(4 + static_cast<size_t>(count) * HASH_CHAIN_ENTRY_SIZE);
 
        // Write entry count
        uint8_t count_buf[4];
        detail::audit::write_le32(count_buf, count);
        buf.insert(buf.end(), count_buf, count_buf + 4);
 
        // Write each entry
        for (const auto& entry : entries_) {
            auto entry_bytes = entry.serialize();
            buf.insert(buf.end(), entry_bytes.begin(), entry_bytes.end());
        }
 
        return buf;
    }
 
    inline void reset(std::array<uint8_t, 32> initial_prev_hash = {}, int64_t initial_seq = 0) {
        entries_.clear();
        last_hash_ = initial_prev_hash;
        next_seq_  = initial_seq;
    }
 
private:
    std::vector<HashChainEntry> entries_;
    std::array<uint8_t, 32>     last_hash_;
    int64_t                     next_seq_;
};
 
class AuditChainVerifier {
public:
    struct VerificationResult {
        bool valid = false;
 
        int64_t entries_checked = 0;
 
        int64_t first_bad_index = -1;
 
        std::string error_message;
    };
 
    [[nodiscard]] static inline VerificationResult verify(
            const uint8_t* chain_data, size_t chain_size) {
 
        VerificationResult result;
 
        // Need at least the 4-byte count header
        if (chain_size < 4) {
            result.error_message = "chain data too small for header (need >= 4 bytes)";
            return result;
        }
 
        uint32_t count = detail::audit::read_le32(chain_data);
        size_t expected_size = 4 + static_cast<size_t>(count) * HASH_CHAIN_ENTRY_SIZE;
 
        // CWE-400, CWE-789: Memory Allocation with Excessive Size Value —
        // validate that count * ENTRY_SIZE fits in chain_size before reserve().
        if (expected_size < 4 || chain_size < expected_size) {
            result.error_message = "chain data truncated: expected "
                                 + std::to_string(expected_size)
                                 + " bytes for " + std::to_string(count)
                                 + " entries, got " + std::to_string(chain_size);
            return result;
        }
 
        // Deserialize all entries
        std::vector<HashChainEntry> entries;
        entries.reserve(count);
 
        const uint8_t* ptr = chain_data + 4;
        for (uint32_t i = 0; i < count; ++i) {
            auto entry_result = HashChainEntry::deserialize(
                ptr, HASH_CHAIN_ENTRY_SIZE);
 
            if (!entry_result) {
                result.error_message = "failed to deserialize entry "
                                     + std::to_string(i) + ": "
                                     + entry_result.error().message;
                result.first_bad_index = static_cast<int64_t>(i);
                return result;
            }
 
            entries.push_back(std::move(*entry_result));
            ptr += HASH_CHAIN_ENTRY_SIZE;
        }
 
        return verify(entries);
    }
 
    [[nodiscard]] static inline VerificationResult verify(
            const std::vector<HashChainEntry>& entries) {
 
        VerificationResult result;
 
        if (entries.empty()) {
            result.valid           = true;
            result.entries_checked = 0;
            result.first_bad_index = -1;
            return result;
        }
 
        std::array<uint8_t, 32> expected_prev_hash{};  // zeros for first entry
 
        for (size_t i = 0; i < entries.size(); ++i) {
            const auto& entry = entries[i];
 
            // Check 1: sequence number must match position
            if (entry.sequence_number != static_cast<int64_t>(i)) {
                result.valid           = false; // defensive: CWE-705
                result.entries_checked = static_cast<int64_t>(i);
                result.first_bad_index = static_cast<int64_t>(i);
                result.error_message   = "entry " + std::to_string(i)
                    + ": expected sequence_number " + std::to_string(i)
                    + ", got " + std::to_string(entry.sequence_number);
                return result;
            }
 
            // Check 2: prev_hash must match expected
            if (entry.prev_hash != expected_prev_hash) {
                result.valid           = false; // defensive: MiFID II RTS 24 Art.4
                result.entries_checked = static_cast<int64_t>(i);
                result.first_bad_index = static_cast<int64_t>(i);
                result.error_message   = "entry " + std::to_string(i)
                    + ": prev_hash mismatch (chain link broken)";
                return result;
            }
 
            // Check 3: entry_hash must be self-consistent
            if (!entry.verify()) {
                result.valid           = false; // defensive: tamper detection
                result.entries_checked = static_cast<int64_t>(i);
                result.first_bad_index = static_cast<int64_t>(i);
                result.error_message   = "entry " + std::to_string(i)
                    + ": entry_hash does not match recomputed hash (data tampered)";
                return result;
            }
 
            // Check 4: timestamp must be non-decreasing
            if (i > 0 && entry.timestamp_ns < entries[i - 1].timestamp_ns) {
                result.valid           = false; // defensive: ordering violation
                result.entries_checked = static_cast<int64_t>(i);
                result.first_bad_index = static_cast<int64_t>(i);
                result.error_message   = "entry " + std::to_string(i)
                    + ": timestamp_ns (" + std::to_string(entry.timestamp_ns)
                    + ") < previous (" + std::to_string(entries[i - 1].timestamp_ns)
                    + ") — ordering violation";
                return result;
            }
 
            // Advance the expected prev_hash for the next entry
            expected_prev_hash = entry.entry_hash;
        }
 
        // All entries passed
        result.valid           = true;
        result.entries_checked = static_cast<int64_t>(entries.size());
        result.first_bad_index = -1;
        return result;
    }
 
    [[nodiscard]] static inline bool verify_continuity(
            const std::array<uint8_t, 32>& file1_last_hash,
            const std::vector<HashChainEntry>& file2_entries) {
 
        if (file2_entries.empty()) {
            return true;  // empty continuation is vacuously valid
        }
 
        return file2_entries[0].prev_hash == file1_last_hash;
    }
 
    [[nodiscard]] static inline bool verify_entry(
            const HashChainEntry& entry,
            const std::array<uint8_t, 32>& expected_prev_hash) {
 
        if (entry.prev_hash != expected_prev_hash) {
            return false;
        }
 
        return entry.verify();
    }
};
 
struct AuditMetadata {
    std::string chain_id;
 
    int64_t start_sequence = 0;
 
    int64_t end_sequence = 0;
 
    std::array<uint8_t, 32> first_prev_hash{};
 
    std::array<uint8_t, 32> last_entry_hash{};
 
    std::string created_by = SIGNET_CREATED_BY;
 
 
    std::string first_hash;
 
    std::string last_hash;
 
    std::string prev_file_hash;
 
    int64_t record_count = 0;
 
    std::string record_type;
 
    [[nodiscard]] inline std::vector<std::pair<std::string, std::string>>
    to_key_values() const {
        std::vector<std::pair<std::string, std::string>> kvs;
        kvs.emplace_back("signetstack.audit.chain_id", chain_id);
        kvs.emplace_back("signetstack.audit.first_seq", std::to_string(start_sequence));
        kvs.emplace_back("signetstack.audit.last_seq",  std::to_string(end_sequence));
        kvs.emplace_back("signetstack.audit.first_hash", first_hash);
        kvs.emplace_back("signetstack.audit.last_hash",  last_hash);
        kvs.emplace_back("signetstack.audit.prev_file_hash", prev_file_hash);
        kvs.emplace_back("signetstack.audit.record_count", std::to_string(record_count));
        if (!record_type.empty()) {
            kvs.emplace_back("signetstack.audit.record_type", record_type);
        }
        return kvs;
    }
 
    [[nodiscard]] inline std::string serialize() const {
        std::ostringstream oss;
        oss << "chain_id=" << chain_id
            << ";start_seq=" << start_sequence
            << ";end_seq=" << end_sequence
            << ";first_prev=" << hash_to_hex(first_prev_hash)
            << ";last_hash=" << hash_to_hex(last_entry_hash)
            << ";created_by=" << created_by;
        return oss.str();
    }
 
    [[nodiscard]] static inline expected<AuditMetadata> deserialize(
            const std::string& s) {
 
        AuditMetadata meta;
 
        // Parse semicolon-delimited key=value pairs into a map
        auto parse_pairs = [](const std::string& input)
            -> std::vector<std::pair<std::string, std::string>> {
 
            std::vector<std::pair<std::string, std::string>> pairs;
            size_t pos = 0;
 
            while (pos < input.size()) {
                // Find the next semicolon (or end of string)
                size_t semi = input.find(';', pos);
                if (semi == std::string::npos) {
                    semi = input.size();
                }
 
                // Extract the key=value substring
                std::string token = input.substr(pos, semi - pos);
 
                // Split on first '='
                size_t eq = token.find('=');
                if (eq != std::string::npos) {
                    std::string key   = token.substr(0, eq);
                    std::string value = token.substr(eq + 1);
                    pairs.emplace_back(std::move(key), std::move(value));
                }
 
                pos = semi + 1;
            }
 
            return pairs;
        };
 
        auto pairs = parse_pairs(s);
 
        // Helper to find a key
        auto find_key = [&pairs](const std::string& key) -> const std::string* {
            for (const auto& [k, v] : pairs) {
                if (k == key) return &v;
            }
            return nullptr;
        };
 
        // chain_id (required)
        const auto* chain_id_val = find_key("chain_id");
        if (!chain_id_val) {
            return Error{ErrorCode::INVALID_FILE,
                         "AuditMetadata: missing required field 'chain_id'"};
        }
        meta.chain_id = *chain_id_val;
 
        // start_seq (required)
        const auto* start_val = find_key("start_seq");
        if (!start_val) {
            return Error{ErrorCode::INVALID_FILE,
                         "AuditMetadata: missing required field 'start_seq'"};
        }
        try {
            meta.start_sequence = std::stoll(*start_val);
        } catch (const std::exception&) {
            return Error{ErrorCode::INVALID_FILE,
                         "AuditMetadata: invalid start_seq value: " + *start_val};
        }
 
        // end_seq (required)
        const auto* end_val = find_key("end_seq");
        if (!end_val) {
            return Error{ErrorCode::INVALID_FILE,
                         "AuditMetadata: missing required field 'end_seq'"};
        }
        try {
            meta.end_sequence = std::stoll(*end_val);
        } catch (const std::exception&) {
            return Error{ErrorCode::INVALID_FILE,
                         "AuditMetadata: invalid end_seq value: " + *end_val};
        }
 
        // first_prev (required, 64 hex chars)
        const auto* first_prev_val = find_key("first_prev");
        if (!first_prev_val) {
            return Error{ErrorCode::INVALID_FILE,
                         "AuditMetadata: missing required field 'first_prev'"};
        }
        auto first_prev_result = hex_to_hash(*first_prev_val);
        if (!first_prev_result) {
            return Error{ErrorCode::INVALID_FILE,
                         "AuditMetadata: invalid first_prev hash: "
                         + first_prev_result.error().message};
        }
        meta.first_prev_hash = *first_prev_result;
 
        // last_hash (required, 64 hex chars)
        const auto* last_hash_val = find_key("last_hash");
        if (!last_hash_val) {
            return Error{ErrorCode::INVALID_FILE,
                         "AuditMetadata: missing required field 'last_hash'"};
        }
        auto last_hash_result = hex_to_hash(*last_hash_val);
        if (!last_hash_result) {
            return Error{ErrorCode::INVALID_FILE,
                         "AuditMetadata: invalid last_hash: "
                         + last_hash_result.error().message};
        }
        meta.last_entry_hash = *last_hash_result;
 
        // created_by (optional, defaults to SIGNET_CREATED_BY)
        const auto* created_val = find_key("created_by");
        if (created_val) {
            meta.created_by = *created_val;
        }
 
        return meta;
    }
};
 
inline expected<AuditMetadata> build_audit_metadata(
        const AuditChainWriter& writer,
        const std::string& chain_id) {
 
    if (writer.length() == 0) {
        return Error{ErrorCode::INTERNAL_ERROR,
                     "build_audit_metadata: writer has no entries"};
    }
 
    const auto& entries = writer.entries();
 
    AuditMetadata meta;
    meta.chain_id        = chain_id;
    meta.start_sequence  = entries.front().sequence_number;
    meta.end_sequence    = entries.back().sequence_number;
    meta.first_prev_hash = entries.front().prev_hash;
    meta.last_entry_hash = entries.back().entry_hash;
    meta.created_by      = SIGNET_CREATED_BY;
 
    return meta;
}
 
inline expected<std::vector<HashChainEntry>> deserialize_and_verify_chain(
        const uint8_t* chain_data, size_t chain_size) {
 
    // Deserialize
    if (chain_size < 4) {
        return Error{ErrorCode::HASH_CHAIN_BROKEN,
                     "chain data too small for header"};
    }
 
    uint32_t count = detail::audit::read_le32(chain_data);
    size_t expected_size = 4 + static_cast<size_t>(count) * HASH_CHAIN_ENTRY_SIZE;
 
    // CWE-400, CWE-789: bounds check before reserve() prevents excessive allocation.
    if (expected_size < 4 || chain_size < expected_size) {
        return Error{ErrorCode::HASH_CHAIN_BROKEN,
                     "chain data truncated: expected "
                     + std::to_string(expected_size) + " bytes, got "
                     + std::to_string(chain_size)};
    }
 
    std::vector<HashChainEntry> entries;
    entries.reserve(count);
 
    const uint8_t* ptr = chain_data + 4;
    for (uint32_t i = 0; i < count; ++i) {
        auto entry_result = HashChainEntry::deserialize(ptr, HASH_CHAIN_ENTRY_SIZE);
        if (!entry_result) {
            return Error{ErrorCode::HASH_CHAIN_BROKEN,
                         "entry " + std::to_string(i) + ": "
                         + entry_result.error().message};
        }
        entries.push_back(std::move(*entry_result));
        ptr += HASH_CHAIN_ENTRY_SIZE;
    }
 
    // Verify
    auto result = AuditChainVerifier::verify(entries);
    if (!result.valid) {
        return Error{ErrorCode::HASH_CHAIN_BROKEN, result.error_message};
    }
 
    return entries;
}
 
} // namespace signet::forge