post_quantum.hpp

Go to the documentation of this file.

// SPDX-License-Identifier: AGPL-3.0-or-later
// Copyright 2026 Johnson Ogundeji
#pragma once
 
 
// ---------------------------------------------------------------------------
// post_quantum.hpp -- Post-quantum cryptography for SignetStack Signet Forge
//
// Provides two NIST post-quantum cryptographic primitives:
//
//   Kyber-768 KEM  -- Key Encapsulation Mechanism for establishing shared
//                     AES-256 keys between Parquet writer and reader.
//                     (NIST FIPS 203 / ML-KEM-768)
//
//   Dilithium-3    -- Digital signature scheme for Parquet footer signing
//                     and tamper detection.
//                     (NIST FIPS 204 / ML-DSA-65)
//
// Additionally provides a hybrid KEM (Kyber-768 + X25519) that combines
// post-quantum and classical key exchange for defense-in-depth.
//
// This is the first Parquet library to offer post-quantum encryption.
//
// TWO MODES OF OPERATION:
//
//   1. Bundled mode (default):
//      A simplified reference implementation using std::random_device and
//      SHA-256 for key generation, encapsulation stubs, and signature
//      simulation. This mode demonstrates the API and allows integration
//      testing WITHOUT any external dependencies.
//
//      *** WARNING: The bundled mode is NOT cryptographically secure. ***
//      *** It does NOT implement real Kyber or Dilithium algorithms.  ***
//      *** It is a functional stub for API development and testing.   ***
//
//   2. liboqs mode (SIGNET_HAS_LIBOQS defined):
//      Delegates to the Open Quantum Safe (liboqs) library for real
//      NIST-standardized Kyber-768 and Dilithium-3 implementations.
//      This is the recommended mode for production use.
//
// Header-only, zero external dependencies in bundled mode.
//
// References:
//   - NIST FIPS 203: Module-Lattice-Based Key-Encapsulation Mechanism
//   - NIST FIPS 204: Module-Lattice-Based Digital Signature Standard
//   - https://openquantumsafe.org/
//   - https://pq-crystals.org/kyber/
//   - https://pq-crystals.org/dilithium/
// ---------------------------------------------------------------------------
 
#include "signet/error.hpp"
#include "signet/crypto/cipher_interface.hpp"
 
#if !defined(SIGNET_ENABLE_COMMERCIAL) || !SIGNET_ENABLE_COMMERCIAL
#error "signet/crypto/post_quantum.hpp requires SIGNET_ENABLE_COMMERCIAL=ON (AGPL-3.0 commercial tier). See LICENSE_COMMERCIAL."
#endif
 
#if defined(SIGNET_REQUIRE_REAL_PQ) && SIGNET_REQUIRE_REAL_PQ && !defined(SIGNET_HAS_LIBOQS)
#error "SIGNET_REQUIRE_REAL_PQ=1 forbids bundled PQ stubs. Reconfigure with -DSIGNET_ENABLE_PQ=ON and install liboqs."
#endif
 
#if !defined(SIGNET_HAS_LIBOQS)
#pragma message("WARNING: Signet post-quantum crypto is using BUNDLED Kyber/Dilithium STUBS (NOT post-quantum secure). HybridKem X25519 provides real classical ECDH security; only the Kyber-768 lattice portion is a structural placeholder. Build with -DSIGNET_ENABLE_PQ=ON for real post-quantum resistance.")
#endif
 
#include <algorithm>
#include <array>
#include <cstddef>
#include <cstdint>
#include <cstring>
#include <random>
#include <string>
#include <utility>
#include <vector>
 
#ifdef SIGNET_HAS_LIBOQS
#include <oqs/oqs.h>
#endif
 
// SHA-256 is now in signet/crypto/sha256.hpp (Tier 1, AGPL-3.0-or-later).
#include "signet/crypto/sha256.hpp"
 
namespace signet::forge::crypto {
 
[[nodiscard]] inline bool is_real_pq_crypto() noexcept {
#ifdef SIGNET_HAS_LIBOQS
    return true;
#else
    return false;
#endif
}
 
#ifdef SIGNET_HAS_LIBOQS
#if defined(OQS_KEM_alg_kyber_768)
inline constexpr const char* kOqsKemAlgMlKem768 = OQS_KEM_alg_kyber_768;
#elif defined(OQS_KEM_alg_ml_kem_768)
inline constexpr const char* kOqsKemAlgMlKem768 = OQS_KEM_alg_ml_kem_768;
#else
#error "liboqs is missing ML-KEM-768/Kyber-768 symbols required by SIGNET_REQUIRE_REAL_PQ"
#endif
 
#if defined(OQS_SIG_alg_dilithium_3)
inline constexpr const char* kOqsSigAlgMlDsa65 = OQS_SIG_alg_dilithium_3;
#elif defined(OQS_SIG_alg_ml_dsa_65)
inline constexpr const char* kOqsSigAlgMlDsa65 = OQS_SIG_alg_ml_dsa_65;
#else
#error "liboqs is missing ML-DSA-65/Dilithium-3 symbols required by SIGNET_REQUIRE_REAL_PQ"
#endif
#endif
 
// ===========================================================================
// Random byte generation helper (used by all PQ classes)
// ===========================================================================
namespace detail::pq {
 
inline void random_bytes(uint8_t* buf, size_t size) {
    detail::cipher::fill_random_bytes(buf, size);
}
 
inline std::vector<uint8_t> random_bytes(size_t size) {
    std::vector<uint8_t> buf(size);
    random_bytes(buf.data(), size);
    return buf;
}
 
} // namespace detail::pq
 
// ===========================================================================
// detail::x25519 — Constant-time X25519 (RFC 7748 Curve25519)
//
// Field: GF(2^255 - 19).
// Representation: 5-limb radix-2^51 (Clang/GCC) or 10-limb radix-2^25.5 (MSVC).
// All operations are constant-time (no data-dependent branches, no timing leaks).
//
// References:
//   - RFC 7748: Elliptic Curves for Diffie-Hellman Key Agreement
//   - D.J. Bernstein "Curve25519: new Diffie-Hellman speed records" (2006)
//   - SUPERCOP ref10 implementation
// ===========================================================================
namespace detail::x25519 {
 
// ---------------------------------------------------------------------------
// Field arithmetic — GF(2^255 - 19)
//
// We use two representations depending on compiler:
//   GCC/Clang: 5 x uint64_t limbs, radix 2^51. Products use unsigned __int128.
//   MSVC:      10 x int32_t limbs, radix 2^25.5. Products use int64_t.
// ---------------------------------------------------------------------------
 
#if defined(__GNUC__) || defined(__clang__)
 
// --- 5-limb 64-bit representation (Clang / GCC) ---
 
using u128 = unsigned __int128;
 
using Fe = std::array<uint64_t, 5>;
 
inline Fe fe_carry(Fe a) {
    constexpr uint64_t MASK51 = (1ULL << 51) - 1;
    for (int pass = 0; pass < 2; ++pass) {
        uint64_t c;
        c = a[0] >> 51; a[0] &= MASK51; a[1] += c;
        c = a[1] >> 51; a[1] &= MASK51; a[2] += c;
        c = a[2] >> 51; a[2] &= MASK51; a[3] += c;
        c = a[3] >> 51; a[3] &= MASK51; a[4] += c;
        c = a[4] >> 51; a[4] &= MASK51; a[0] += c * 19;
    }
    return a;
}
 
inline Fe fe_add(Fe a, const Fe& b) {
    for (int i = 0; i < 5; ++i) a[i] += b[i];
    return fe_carry(a);
}
 
inline Fe fe_sub(Fe a, const Fe& b) {
    // Add 2p before subtracting to stay positive (RFC 7748 §5, p = 2^255-19)
    a[0] += 0xFFFFFFFFFFFDAULL - b[0]; // 2p[0] = 2*(2^51-19) — absorbs p's -19 term
    a[1] += 0xFFFFFFFFFFFFEULL - b[1];
    a[2] += 0xFFFFFFFFFFFFEULL - b[2];
    a[3] += 0xFFFFFFFFFFFFEULL - b[3];
    a[4] += 0xFFFFFFFFFFFFEULL - b[4];
    return fe_carry(a);
}
 
inline Fe fe_mul(const Fe& a, const Fe& b) {
    // Schoolbook multiplication, reduced mod p on-the-fly.
    // 19*b[i] precomputed to avoid repeated multiplications.
    u128 t0 = (u128)a[0]*b[0] + 19*((u128)a[1]*b[4] + (u128)a[2]*b[3] + (u128)a[3]*b[2] + (u128)a[4]*b[1]);
    u128 t1 = (u128)a[0]*b[1] + (u128)a[1]*b[0] + 19*((u128)a[2]*b[4] + (u128)a[3]*b[3] + (u128)a[4]*b[2]);
    u128 t2 = (u128)a[0]*b[2] + (u128)a[1]*b[1] + (u128)a[2]*b[0] + 19*((u128)a[3]*b[4] + (u128)a[4]*b[3]);
    u128 t3 = (u128)a[0]*b[3] + (u128)a[1]*b[2] + (u128)a[2]*b[1] + (u128)a[3]*b[0] + 19*(u128)a[4]*b[4];
    u128 t4 = (u128)a[0]*b[4] + (u128)a[1]*b[3] + (u128)a[2]*b[2] + (u128)a[3]*b[1] + (u128)a[4]*b[0];
 
    constexpr uint64_t MASK51 = (1ULL << 51) - 1;
    Fe r;
    uint64_t c;
    r[0] = (uint64_t)t0 & MASK51; c = (uint64_t)(t0 >> 51); t1 += c;
    r[1] = (uint64_t)t1 & MASK51; c = (uint64_t)(t1 >> 51); t2 += c;
    r[2] = (uint64_t)t2 & MASK51; c = (uint64_t)(t2 >> 51); t3 += c;
    r[3] = (uint64_t)t3 & MASK51; c = (uint64_t)(t3 >> 51); t4 += c;
    r[4] = (uint64_t)t4 & MASK51; c = (uint64_t)(t4 >> 51);
    r[0] += c * 19;
    c = r[0] >> 51; r[0] &= MASK51; r[1] += c;
    return fe_carry(r);
}
 
inline Fe fe_sq(const Fe& a) { return fe_mul(a, a); }
 
inline Fe fe_from_bytes(const uint8_t* b) {
    constexpr uint64_t MASK51 = (1ULL << 51) - 1;
    auto load8 = [&](int i) -> uint64_t {
        uint64_t v = 0;
        for (int j = 0; j < 8 && i+j < 32; ++j)
            v |= (uint64_t)b[i+j] << (8*j);
        return v;
    };
    Fe f;
    f[0] =  load8( 0)        & MASK51;
    f[1] = (load8( 6) >>  3) & MASK51;
    f[2] = (load8(12) >>  6) & MASK51;
    f[3] = (load8(19) >>  1) & MASK51;
    f[4] = (load8(24) >> 12) & MASK51;
    return fe_carry(f);
}
 
inline void fe_to_bytes(uint8_t* out, Fe f) {
    constexpr uint64_t MASK51 = (1ULL << 51) - 1;
 
    // Fully normalize carries before canonical reduction.
    f = fe_carry(f);
    f = fe_carry(f);
 
    // Compute g = f - p by adding 19 and carrying into bit 255.
    uint64_t g0 = f[0] + 19;
    uint64_t c  = g0 >> 51; g0 &= MASK51;
    uint64_t g1 = f[1] + c; c = g1 >> 51; g1 &= MASK51;
    uint64_t g2 = f[2] + c; c = g2 >> 51; g2 &= MASK51;
    uint64_t g3 = f[3] + c; c = g3 >> 51; g3 &= MASK51;
    uint64_t g4 = f[4] + c; c = g4 >> 51; g4 &= MASK51;
 
    // If carry==1, f >= p and g is the reduced canonical representative.
    uint64_t mask = 0 - c;
    f[0] ^= mask & (f[0] ^ g0);
    f[1] ^= mask & (f[1] ^ g1);
    f[2] ^= mask & (f[2] ^ g2);
    f[3] ^= mask & (f[3] ^ g3);
    f[4] ^= mask & (f[4] ^ g4);
 
    // Pack radix-2^51 limbs into 32 little-endian bytes without overflow.
    const uint64_t w0 = f[0] | ((f[1] & ((1ULL << 13) - 1)) << 51);
    const uint64_t w1 = (f[1] >> 13) | ((f[2] & ((1ULL << 26) - 1)) << 38);
    const uint64_t w2 = (f[2] >> 26) | ((f[3] & ((1ULL << 39) - 1)) << 25);
    const uint64_t w3 = (f[3] >> 39) | (f[4] << 12);
 
    auto store8 = [&](uint8_t* p, uint64_t v) {
        for (int i = 0; i < 8; ++i) p[i] = static_cast<uint8_t>(v >> (8 * i));
    };
    store8(out + 0,  w0);
    store8(out + 8,  w1);
    store8(out + 16, w2);
    store8(out + 24, w3);
}
 
inline void fe_cswap(Fe& a, Fe& b, uint64_t swap) {
    uint64_t mask = 0 - swap; // 0 if swap==0, 0xFFFF...FF if swap==1
    for (int i = 0; i < 5; ++i) {
        uint64_t t = mask & (a[i] ^ b[i]);
        a[i] ^= t;
        b[i] ^= t;
    }
}
 
inline Fe fe_inv(const Fe& z) {
    // Constant-time addition chain for z^(p-2) mod p, p = 2^255 - 19
    // Follows NaCl ref10 / SUPERCOP — branch-free (CWE-208 compliant)
    Fe t0 = fe_sq(z);                                       // z^2
    Fe t1 = fe_sq(fe_sq(t0));                               // z^8
    t1 = fe_mul(t1, z);                                     // z^9
    t0 = fe_mul(t0, t1);                                    // z^11
    Fe t2 = fe_sq(t0);                                      // z^22
    t2 = fe_mul(t2, t1);                                    // z^(2^5-1) = z^31
    // z^(2^10-1)
    Fe a = t2; for (int i = 0; i < 5; ++i) a = fe_sq(a);
    a = fe_mul(a, t2);
    // z^(2^20-1)
    Fe b = a; for (int i = 0; i < 10; ++i) b = fe_sq(b);
    b = fe_mul(b, a);
    // z^(2^40-1)
    Fe c = b; for (int i = 0; i < 20; ++i) c = fe_sq(c);
    c = fe_mul(c, b);
    // z^(2^50-1)
    for (int i = 0; i < 10; ++i) c = fe_sq(c);
    c = fe_mul(c, a);
    // z^(2^100-1)
    Fe d = c; for (int i = 0; i < 50; ++i) d = fe_sq(d);
    d = fe_mul(d, c);
    // z^(2^200-1)
    Fe e = d; for (int i = 0; i < 100; ++i) e = fe_sq(e);
    e = fe_mul(e, d);
    // z^(2^250-1)
    for (int i = 0; i < 50; ++i) e = fe_sq(e);
    e = fe_mul(e, c);
    // z^(2^255-32) after squaring, then * z^11 = z^(2^255-21) = z^(p-2)
    for (int i = 0; i < 5; ++i) e = fe_sq(e);
    return fe_mul(e, t0);
}
 
#else // MSVC / other compilers — 10-limb int32_t representation
 
using Fe = std::array<int32_t, 10>;
 
inline Fe fe_from_bytes(const uint8_t* b) {
    auto load4 = [&](int i) -> int32_t {
        return (int32_t)b[i] | ((int32_t)b[i+1]<<8) | ((int32_t)b[i+2]<<16) | ((int32_t)b[i+3]<<24);
    };
    Fe h;
    h[0] =  load4( 0)         & 0x3FFFFFF;
    h[1] = (load4( 3) >> 2)   & 0x1FFFFFF;
    h[2] = (load4( 6) >> 3)   & 0x3FFFFFF;
    h[3] = (load4( 9) >> 5)   & 0x1FFFFFF;
    h[4] = (load4(12) >> 6)   & 0x3FFFFFF;
    h[5] =  load4(16)         & 0x1FFFFFF;
    h[6] = (load4(19) >> 1)   & 0x3FFFFFF;
    h[7] = (load4(22) >> 3)   & 0x1FFFFFF;
    h[8] = (load4(25) >> 4)   & 0x3FFFFFF;
    h[9] = (load4(28) >> 6)   & 0x1FFFFFF;
    return h;
}
 
inline void fe_carry_10(Fe& h) {
    for (int i = 0; i < 10; ++i) {
        int bits = (i % 2 == 0) ? 26 : 25;
        int32_t carry = h[i] >> bits;
        h[i] -= carry << bits;
        if (i < 9) h[i+1] += carry;
        else       h[0]   += carry * 19;
    }
}
 
inline Fe fe_add(Fe a, const Fe& b) {
    for (int i = 0; i < 10; ++i) a[i] += b[i];
    return a;
}
 
inline Fe fe_sub(Fe a, const Fe& b) {
    // Add 2p in each limb to stay non-negative.
    // RFC 7748 §5: p = 2^255 - 19. Limb 0 absorbs the -19 constant.
    // Audit #6 fix: corrected 2p[0] from 0x3FFFFF0 to 2*(2^26-19) — the
    // prior value silently corrupted all X25519 on MSVC (CWE-682).
    int32_t two_p[10] = {
        2 * (0x3FFFFFF - 18),  // 2*(2^26 - 19) — absorbs p's -19 term
        2 * 0x1FFFFFF,         // 2*(2^25 - 1)
        2 * 0x3FFFFFF,         // 2*(2^26 - 1)
        2 * 0x1FFFFFF,         // 2*(2^25 - 1)
        2 * 0x3FFFFFF,         // 2*(2^26 - 1)
        2 * 0x1FFFFFF,         // 2*(2^25 - 1)
        2 * 0x3FFFFFF,         // 2*(2^26 - 1)
        2 * 0x1FFFFFF,         // 2*(2^25 - 1)
        2 * 0x3FFFFFF,         // 2*(2^26 - 1)
        2 * 0x1FFFFFF          // 2*(2^25 - 1)
    };
    for (int i = 0; i < 10; ++i) a[i] = a[i] + two_p[i] - b[i];
    fe_carry_10(a);
    return a;
}
 
inline Fe fe_mul(const Fe& f, const Fe& g) {
    // 10x10 schoolbook with cross-product combining. Each product is int64_t.
    // KNOWN ISSUE (H-2, MSVC 10-limb path): The truncation from int64_t to
    // int32_t below loses high bits before carry propagation. This is
    // functionally correct only when each h[i] fits in int32_t after the
    // double fe_carry_10 pass, which holds for field elements in reduced
    // form. A future MSVC-validated fix should accumulate in int64_t and
    // carry in 64-bit precision (matching the ref10 implementation).
    int64_t h[10] = {};
    // 19*g[i] for i>=5 collapses the wrap-around
    int64_t g19[5];
    for (int i = 0; i < 5; ++i) g19[i] = (int64_t)g[i+5] * 19;
    for (int i = 0; i < 5; ++i) {
        for (int j = 0; j < 5; ++j) {
            h[i+j]   += (int64_t)f[i]   * g[j];
            h[i+j+5] += (int64_t)f[i]   * g[j+5];
            h[i+j]   += (int64_t)f[i+5] * g19[j];  // wrap
        }
    }
    Fe r;
    for (int i = 0; i < 10; ++i) r[i] = (int32_t)h[i];
    fe_carry_10(r); fe_carry_10(r);
    return r;
}
 
inline Fe fe_sq(const Fe& a) { return fe_mul(a, a); }
 
inline void fe_to_bytes(uint8_t* out, Fe h) {
    // KNOWN ISSUE (H-3, MSVC 10-limb path): The conditional subtraction
    // and packing below use data-dependent branching on limb values,
    // which is not constant-time on MSVC (no __int128 path). This is
    // acceptable for X25519 public key operations but must be addressed
    // before using this path for secret-dependent scalar operations on
    // MSVC. Tracked for fix when MSVC support is fully validated.
    fe_carry_10(h); fe_carry_10(h);
    // Conditionally subtract p
    int32_t q = (19 * h[0] + (1<<25)) >> 26;
    for (int i = 0; i < 9; ++i) {
        q = h[i] + q * (i%2==0 ? 19 : 1);
        q >>= (i%2==0 ? 26 : 25);
    }
    h[0] += 19 * q;
    fe_carry_10(h);
    // Pack
    uint32_t b[8];
    b[0] = (uint32_t)h[0] | ((uint32_t)h[1]<<26);
    b[1] = ((uint32_t)h[1]>>6) | ((uint32_t)h[2]<<19);
    b[2] = ((uint32_t)h[2]>>13) | ((uint32_t)h[3]<<13);
    b[3] = ((uint32_t)h[3]>>19) | ((uint32_t)h[4]<<6);
    b[4] = (uint32_t)h[5] | ((uint32_t)h[6]<<25);
    b[5] = ((uint32_t)h[6]>>7) | ((uint32_t)h[7]<<18);
    b[6] = ((uint32_t)h[7]>>14) | ((uint32_t)h[8]<<11);
    b[7] = ((uint32_t)h[8]>>21) | ((uint32_t)h[9]<<4);
    for (int i = 0; i < 8; ++i) {
        out[i*4+0] = (uint8_t)(b[i]);
        out[i*4+1] = (uint8_t)(b[i]>>8);
        out[i*4+2] = (uint8_t)(b[i]>>16);
        out[i*4+3] = (uint8_t)(b[i]>>24);
    }
}
 
inline void fe_cswap(Fe& a, Fe& b, uint64_t swap) {
    int32_t mask = (int32_t)(0 - swap);
    for (int i = 0; i < 10; ++i) {
        int32_t t = mask & (a[i] ^ b[i]);
        a[i] ^= t; b[i] ^= t;
    }
}
 
inline Fe fe_inv(const Fe& z) {
    // Same addition chain (ref10), but using 10-limb operations
    Fe t0 = fe_sq(z);                                       // z^2
    Fe t1 = fe_sq(fe_sq(t0));                               // z^8
    t1 = fe_mul(t1, z);                                     // z^9
    t0 = fe_mul(t0, t1);                                    // z^11
    Fe t2 = fe_sq(t0);                                      // z^22
    t2 = fe_mul(t2, t1);                                    // z^31 = z^(2^5-1)
    Fe a = t2;
    for (int i=0;i<5;i++) a=fe_sq(a);
    a=fe_mul(a,t2);
    Fe b=a; for(int i=0;i<10;i++) b=fe_sq(b); b=fe_mul(b,a);
    Fe c=b; for(int i=0;i<20;i++) c=fe_sq(c); c=fe_mul(c,b);
    for(int i=0;i<10;i++) c=fe_sq(c); c=fe_mul(c,a);
    Fe d=c; for(int i=0;i<50;i++) d=fe_sq(d); d=fe_mul(d,c);
    Fe e=d; for(int i=0;i<100;i++) e=fe_sq(e); e=fe_mul(e,d);
    for(int i=0;i<50;i++) e=fe_sq(e); e=fe_mul(e,c);
    for(int i=0;i<5;i++) e=fe_sq(e);
    return fe_mul(e,t0);  // z^(2^255-32) * z^11 = z^(2^255-21) = z^(p-2)
}
 
#endif // __GNUC__ || __clang__
 
// ---------------------------------------------------------------------------
// X25519 Montgomery ladder (common to both representations)
// ---------------------------------------------------------------------------
 
inline std::array<uint8_t, 32> clamp_scalar(std::array<uint8_t, 32> k) {
    k[0]  &= 248;
    k[31] &= 127;
    k[31] |= 64;
    return k;
}
 
inline std::array<uint8_t, 32> x25519_raw(
    const std::array<uint8_t, 32>& scalar,
    const std::array<uint8_t, 32>& point_u)
{
    // Decode input u-coordinate, masking the high bit per RFC 7748 §5
    std::array<uint8_t, 32> u_masked = point_u;
    u_masked[31] &= 0x7F;  // Ignore the top bit
    Fe u = fe_from_bytes(u_masked.data());
 
    // Montgomery ladder state: (x2,z2)=1 (point at infinity), (x3,z3)=u
    Fe x_1 = u;
    Fe x_2;
#if defined(__GNUC__) || defined(__clang__)
    x_2 = {1,0,0,0,0};
#else
    x_2 = {1,0,0,0,0,0,0,0,0,0};
#endif
    Fe z_2;
#if defined(__GNUC__) || defined(__clang__)
    z_2 = {0,0,0,0,0};
#else
    z_2 = {0,0,0,0,0,0,0,0,0,0};
#endif
    Fe x_3 = u;
    Fe z_3;
#if defined(__GNUC__) || defined(__clang__)
    z_3 = {1,0,0,0,0};
#else
    z_3 = {1,0,0,0,0,0,0,0,0,0};
#endif
 
    // a24 as field element (121665)
    Fe a24;
#if defined(__GNUC__) || defined(__clang__)
    a24 = {121665, 0, 0, 0, 0};
#else
    a24 = {121665, 0, 0, 0, 0, 0, 0, 0, 0, 0};
#endif
 
    uint64_t swap = 0;
 
    // 255-bit scalar, iterate from bit 254 down to 0
    for (int i = 254; i >= 0; --i) {
        uint64_t k_bit = (scalar[i / 8] >> (i % 8)) & 1;
        swap ^= k_bit;
        fe_cswap(x_2, x_3, swap);
        fe_cswap(z_2, z_3, swap);
        swap = k_bit;
 
        // Montgomery differential addition-and-doubling
        Fe A  = fe_add(x_2, z_2);
        Fe AA = fe_sq(A);
        Fe B  = fe_sub(x_2, z_2);
        Fe BB = fe_sq(B);
        Fe E  = fe_sub(AA, BB);
        Fe C  = fe_add(x_3, z_3);
        Fe D  = fe_sub(x_3, z_3);
        Fe DA = fe_mul(D, A);
        Fe CB = fe_mul(C, B);
        Fe t1 = fe_add(DA, CB);
        Fe t2 = fe_sub(DA, CB);
        x_3 = fe_sq(t1);
        z_3 = fe_mul(fe_sq(t2), x_1);
        x_2 = fe_mul(AA, BB);
        z_2 = fe_mul(E, fe_add(AA, fe_mul(a24, E)));
    }
 
    // Final conditional swap
    fe_cswap(x_2, x_3, swap);
    fe_cswap(z_2, z_3, swap);
 
    // Recover u-coordinate: x_2 * z_2^(-1)
    Fe result = fe_mul(x_2, fe_inv(z_2));
 
    std::array<uint8_t, 32> out;
    fe_to_bytes(out.data(), result);
    return out;
}
 
inline expected<std::array<uint8_t, 32>> x25519(
    const std::array<uint8_t, 32>& scalar,
    const std::array<uint8_t, 32>& u_coord)
{
    auto license = commercial::require_feature("PQ x25519");
    if (!license) return license.error();
 
    // L-C8: Clamp scalar per RFC 7748 §5 before use, in case caller
    // passes an unclamped key. This is idempotent if already clamped.
    std::array<uint8_t, 32> clamped = scalar;
    clamped[0]  &= 248;
    clamped[31] &= 127;
    clamped[31] |= 64;
 
    auto result = x25519_raw(clamped, u_coord);
    // Constant-time zero check: OR all 32 bytes, then compare (RFC 7748 §6.1, CWE-208)
    uint8_t acc = 0;
    for (size_t i = 0; i < 32; ++i) acc |= result[i];
    // acc == 0 means degenerate key (all-zero output)
    if (acc == 0) {
        return Error{ErrorCode::ENCRYPTION_ERROR,
                     "X25519: degenerate output (all-zero) — invalid input point"};
    }
    return result;
}
 
inline const std::array<uint8_t, 32>& base_point() {
    static const std::array<uint8_t, 32> BP = {
        9,0,0,0,0,0,0,0, 0,0,0,0,0,0,0,0,
        0,0,0,0,0,0,0,0, 0,0,0,0,0,0,0,0
    };
    return BP;
}
 
inline expected<std::pair<std::array<uint8_t,32>, std::array<uint8_t,32>>>
generate_keypair() {
    auto license = commercial::require_feature("PQ x25519 keypair");
    if (!license) return license.error();
 
    std::array<uint8_t,32> sk;
    pq::random_bytes(sk.data(), 32);
    sk = clamp_scalar(sk);
    auto pk_result = x25519(sk, base_point());
    if (!pk_result) return pk_result.error();
    return std::make_pair(sk, *pk_result);
}
 
} // namespace detail::x25519
 
// ===========================================================================
// KyberKem -- Kyber-768 Key Encapsulation Mechanism
//
// Used to establish shared AES-256 keys between Parquet writer and reader.
//
// Kyber-768 is the NIST ML-KEM-768 standard (FIPS 203), providing
// approximately 192-bit post-quantum security.
//
// Parameter set (Kyber-768 / ML-KEM-768):
//   Public key:     1184 bytes
//   Secret key:     2400 bytes
//   Ciphertext:     1088 bytes
//   Shared secret:  32 bytes (256 bits, suitable for AES-256)
// ===========================================================================
 
class KyberKem {
public:
#if defined(SIGNET_HAS_LIBOQS) && defined(OQS_KEM_ml_kem_768_length_public_key)
    static constexpr size_t PUBLIC_KEY_SIZE    = OQS_KEM_ml_kem_768_length_public_key;
    static constexpr size_t SECRET_KEY_SIZE    = OQS_KEM_ml_kem_768_length_secret_key;
    static constexpr size_t CIPHERTEXT_SIZE    = OQS_KEM_ml_kem_768_length_ciphertext;
    static constexpr size_t SHARED_SECRET_SIZE = OQS_KEM_ml_kem_768_length_shared_secret;
#elif defined(SIGNET_HAS_LIBOQS) && defined(OQS_KEM_kyber_768_length_public_key)
    static constexpr size_t PUBLIC_KEY_SIZE    = OQS_KEM_kyber_768_length_public_key;
    static constexpr size_t SECRET_KEY_SIZE    = OQS_KEM_kyber_768_length_secret_key;
    static constexpr size_t CIPHERTEXT_SIZE    = OQS_KEM_kyber_768_length_ciphertext;
    static constexpr size_t SHARED_SECRET_SIZE = OQS_KEM_kyber_768_length_shared_secret;
#else
    static constexpr size_t PUBLIC_KEY_SIZE    = 1184;  
    static constexpr size_t SECRET_KEY_SIZE    = 2400;  
    static constexpr size_t CIPHERTEXT_SIZE    = 1088;  
    static constexpr size_t SHARED_SECRET_SIZE = 32;    
#endif
 
    struct KeyPair {
        std::vector<uint8_t> public_key;   
        std::vector<uint8_t> secret_key;   
 
        ~KeyPair() {
            if (!secret_key.empty()) {
                volatile uint8_t* p = secret_key.data();
                for (size_t i = 0; i < secret_key.size(); ++i) p[i] = 0;
            }
        }
    };
 
    struct EncapsulationResult {
        std::vector<uint8_t> ciphertext;       
        std::vector<uint8_t> shared_secret;    
    };
 
    // -----------------------------------------------------------------------
    // generate_keypair -- Generate a Kyber-768 keypair
    //
    // Bundled mode:
    //   Generates random bytes for public/secret keys. The keys are
    //   structurally valid (correct sizes) but NOT real Kyber lattice keys.
    //
    // liboqs mode:
    //   Delegates to OQS_KEM_kyber_768_keypair() for real key generation.
    // -----------------------------------------------------------------------
    [[nodiscard]] static expected<KeyPair> generate_keypair() {
        auto license = commercial::require_feature("Kyber generate_keypair");
        if (!license) return license.error();
 
#ifdef SIGNET_HAS_LIBOQS
        // --- liboqs mode: real Kyber-768 key generation ---
        OQS_KEM* kem = OQS_KEM_new(kOqsKemAlgMlKem768);
        if (!kem) {
            return Error{ErrorCode::ENCRYPTION_ERROR,
                         "KyberKem: failed to initialize OQS Kyber-768"};
        }
 
        KeyPair kp;
        kp.public_key.resize(kem->length_public_key);
        kp.secret_key.resize(kem->length_secret_key);
 
        OQS_STATUS rc = OQS_KEM_keypair(kem,
                                         kp.public_key.data(),
                                         kp.secret_key.data());
        OQS_KEM_free(kem);
 
        if (rc != OQS_SUCCESS) {
            return Error{ErrorCode::ENCRYPTION_ERROR,
                         "KyberKem: OQS keypair generation failed"};
        }
 
        return kp;
#else
        // --- REFERENCE IMPLEMENTATION — use liboqs for production ---
        //
        // Generates random bytes of the correct sizes. These are NOT
        // real Kyber lattice keys and provide NO post-quantum security.
        // The encapsulate/decapsulate functions below use SHA-256-based
        // deterministic derivation so that the round-trip is functional.
        KeyPair kp;
        kp.public_key = detail::pq::random_bytes(PUBLIC_KEY_SIZE);
        kp.secret_key = detail::pq::random_bytes(SECRET_KEY_SIZE);
 
        // Embed a copy of the public key hash at the end of the secret key
        // so decapsulation can derive the same shared secret.
        // secret_key layout: [random_seed(2368)] [pk_hash(32)]
        auto pk_hash = detail::sha256::sha256(kp.public_key);
        std::memcpy(kp.secret_key.data() + SECRET_KEY_SIZE - 32,
                    pk_hash.data(), 32);
 
        return kp;
#endif
    }
 
    // -----------------------------------------------------------------------
    // encapsulate -- Generate a shared secret from a public key
    //
    // The sender calls this with the recipient's public key. It produces:
    //   - ciphertext: sent to the recipient (1088 bytes)
    //   - shared_secret: used locally as the AES-256 key (32 bytes)
    //
    // Bundled mode:
    //   Generates a random seed, derives shared_secret = SHA-256(seed || pk),
    //   and produces ciphertext = seed XOR SHA-256(pk). This is NOT real
    //   Kyber encapsulation but demonstrates the API contract.
    //
    // liboqs mode:
    //   Delegates to OQS_KEM_kyber_768_encaps().
    // -----------------------------------------------------------------------
    [[nodiscard]] static expected<EncapsulationResult> encapsulate(
        const uint8_t* public_key, size_t pk_size) {
 
        auto license = commercial::require_feature("Kyber encapsulate");
        if (!license) return license.error();
 
        if (pk_size != PUBLIC_KEY_SIZE) {
            return Error{ErrorCode::ENCRYPTION_ERROR,
                         "KyberKem: public key must be "
                         + std::to_string(PUBLIC_KEY_SIZE) + " bytes, got "
                         + std::to_string(pk_size)};
        }
 
#ifdef SIGNET_HAS_LIBOQS
        // --- liboqs mode: real Kyber-768 encapsulation ---
        OQS_KEM* kem = OQS_KEM_new(kOqsKemAlgMlKem768);
        if (!kem) {
            return Error{ErrorCode::ENCRYPTION_ERROR,
                         "KyberKem: failed to initialize OQS Kyber-768"};
        }
 
        EncapsulationResult result;
        result.ciphertext.resize(kem->length_ciphertext);
        result.shared_secret.resize(kem->length_shared_secret);
 
        OQS_STATUS rc = OQS_KEM_encaps(kem,
                                         result.ciphertext.data(),
                                         result.shared_secret.data(),
                                         public_key);
        OQS_KEM_free(kem);
 
        if (rc != OQS_SUCCESS) {
            return Error{ErrorCode::ENCRYPTION_ERROR,
                         "KyberKem: OQS encapsulation failed"};
        }
 
        return result;
#else
        // --- REFERENCE IMPLEMENTATION — use liboqs for production ---
        //
        // 1. Generate random 32-byte seed
        // 2. shared_secret = SHA-256(seed || public_key_hash)
        // 3. ciphertext = [seed(32)] [pk_hash_xor_pad(1056)] -- padded to 1088
        //
        // The ciphertext contains the seed in cleartext (XORed with pk-derived
        // mask for minimal obfuscation). This is NOT cryptographically secure.
 
        // CR-2: Unless SIGNET_ALLOW_STUB_PQ is explicitly defined, refuse to
        // perform actual encryption with the insecure stub implementation.
#ifndef SIGNET_ALLOW_STUB_PQ
        return Error{ErrorCode::ENCRYPTION_ERROR,
                     "KyberKem: stub PQ implementation provides zero security. "
                     "Build with -DSIGNET_ENABLE_PQ=ON (liboqs) for real Kyber-768, "
                     "or define SIGNET_ALLOW_STUB_PQ to allow the insecure stub."};
#endif
 
        EncapsulationResult result;
 
        // Generate random seed
        std::array<uint8_t, 32> seed;
        detail::pq::random_bytes(seed.data(), 32);
 
        // Derive public key hash
        auto pk_hash = detail::sha256::sha256(public_key, pk_size);
 
        // Derive shared secret: SHA-256(seed || pk_hash)
        result.shared_secret.resize(SHARED_SECRET_SIZE);
        auto ss = detail::sha256::sha256_concat(
            seed.data(), seed.size(), pk_hash.data(), pk_hash.size());
        std::memcpy(result.shared_secret.data(), ss.data(), SHARED_SECRET_SIZE);
 
        // Build ciphertext (1088 bytes):
        // [seed XOR pk_hash (32 bytes)] [padding derived from pk_hash (1056 bytes)]
        result.ciphertext.resize(CIPHERTEXT_SIZE, 0);
 
        // XOR seed with pk_hash for minimal obfuscation
        for (size_t i = 0; i < 32; ++i) {
            result.ciphertext[i] = seed[i] ^ pk_hash[i];
        }
 
        // Fill remaining ciphertext with deterministic padding from pk_hash
        // so that the decapsulator can identify and strip it
        for (size_t i = 32; i < CIPHERTEXT_SIZE; ++i) {
            result.ciphertext[i] = pk_hash[i % 32] ^ static_cast<uint8_t>(i);
        }
 
        return result;
#endif
    }
 
    // -----------------------------------------------------------------------
    // decapsulate -- Recover the shared secret from ciphertext + secret key
    //
    // The recipient calls this with the received ciphertext and their
    // secret key. It produces the same 32-byte shared secret that the
    // sender derived during encapsulation.
    //
    // Bundled mode:
    //   Extracts the seed from ciphertext by XORing with pk_hash (derived
    //   from the pk_hash embedded in the secret key), then derives
    //   shared_secret = SHA-256(seed || pk_hash).
    //
    // liboqs mode:
    //   Delegates to OQS_KEM_kyber_768_decaps().
    // -----------------------------------------------------------------------
    [[nodiscard]] static expected<std::vector<uint8_t>> decapsulate(
        const uint8_t* ciphertext, size_t ct_size,
        const uint8_t* secret_key, size_t sk_size) {
 
        auto license = commercial::require_feature("Kyber decapsulate");
        if (!license) return license.error();
 
        if (ct_size != CIPHERTEXT_SIZE) {
            return Error{ErrorCode::ENCRYPTION_ERROR,
                         "KyberKem: ciphertext must be "
                         + std::to_string(CIPHERTEXT_SIZE) + " bytes, got "
                         + std::to_string(ct_size)};
        }
        if (sk_size != SECRET_KEY_SIZE) {
            return Error{ErrorCode::ENCRYPTION_ERROR,
                         "KyberKem: secret key must be "
                         + std::to_string(SECRET_KEY_SIZE) + " bytes, got "
                         + std::to_string(sk_size)};
        }
 
#ifdef SIGNET_HAS_LIBOQS
        // --- liboqs mode: real Kyber-768 decapsulation ---
        OQS_KEM* kem = OQS_KEM_new(kOqsKemAlgMlKem768);
        if (!kem) {
            return Error{ErrorCode::ENCRYPTION_ERROR,
                         "KyberKem: failed to initialize OQS Kyber-768"};
        }
 
        std::vector<uint8_t> shared_secret(kem->length_shared_secret);
 
        OQS_STATUS rc = OQS_KEM_decaps(kem,
                                         shared_secret.data(),
                                         ciphertext,
                                         secret_key);
        OQS_KEM_free(kem);
 
        if (rc != OQS_SUCCESS) {
            return Error{ErrorCode::ENCRYPTION_ERROR,
                         "KyberKem: OQS decapsulation failed"};
        }
 
        return shared_secret;
#else
        // --- REFERENCE IMPLEMENTATION — use liboqs for production ---
        //
        // 1. Extract pk_hash from secret_key (last 32 bytes)
        // 2. Recover seed = ciphertext[0..31] XOR pk_hash
        // 3. shared_secret = SHA-256(seed || pk_hash)
 
        // CR-2: Unless SIGNET_ALLOW_STUB_PQ is explicitly defined, refuse to
        // perform actual decryption with the insecure stub implementation.
#ifndef SIGNET_ALLOW_STUB_PQ
        return Error{ErrorCode::ENCRYPTION_ERROR,
                     "KyberKem: stub PQ implementation provides zero security. "
                     "Build with -DSIGNET_ENABLE_PQ=ON (liboqs) for real Kyber-768, "
                     "or define SIGNET_ALLOW_STUB_PQ to allow the insecure stub."};
#endif
 
        // Extract pk_hash from the tail of secret_key
        std::array<uint8_t, 32> pk_hash;
        std::memcpy(pk_hash.data(), secret_key + SECRET_KEY_SIZE - 32, 32);
 
        // Recover seed by XORing the first 32 bytes of ciphertext with pk_hash
        std::array<uint8_t, 32> seed;
        for (size_t i = 0; i < 32; ++i) {
            seed[i] = ciphertext[i] ^ pk_hash[i];
        }
 
        // Derive shared secret: SHA-256(seed || pk_hash)
        auto ss = detail::sha256::sha256_concat(
            seed.data(), seed.size(), pk_hash.data(), pk_hash.size());
 
        std::vector<uint8_t> shared_secret(SHARED_SECRET_SIZE);
        std::memcpy(shared_secret.data(), ss.data(), SHARED_SECRET_SIZE);
 
        return shared_secret;
#endif
    }
};
 
// ===========================================================================
// DilithiumSign -- Dilithium-3 Digital Signatures
//
// Used to sign Parquet file footers for tamper detection.
//
// Dilithium-3 is the NIST ML-DSA-65 standard (FIPS 204), providing
// approximately 192-bit post-quantum security for digital signatures.
//
// Parameter set (Dilithium-3 / ML-DSA-65):
//   Public key:       liboqs-defined (1952 in current profiles)
//   Secret key:       liboqs-defined (4032 for ML-DSA-65, 4000 in older Dilithium-3 builds)
//   Signature (max):  liboqs-defined (3309 for ML-DSA-65, 3293 in older Dilithium-3 builds)
// ===========================================================================
 
class DilithiumSign {
public:
#if defined(SIGNET_HAS_LIBOQS) && defined(OQS_SIG_ml_dsa_65_length_public_key)
    static constexpr size_t PUBLIC_KEY_SIZE    = OQS_SIG_ml_dsa_65_length_public_key;
    static constexpr size_t SECRET_KEY_SIZE    = OQS_SIG_ml_dsa_65_length_secret_key;
    static constexpr size_t SIGNATURE_MAX_SIZE = OQS_SIG_ml_dsa_65_length_signature;
#elif defined(SIGNET_HAS_LIBOQS) && defined(OQS_SIG_dilithium_3_length_public_key)
    static constexpr size_t PUBLIC_KEY_SIZE    = OQS_SIG_dilithium_3_length_public_key;
    static constexpr size_t SECRET_KEY_SIZE    = OQS_SIG_dilithium_3_length_secret_key;
    static constexpr size_t SIGNATURE_MAX_SIZE = OQS_SIG_dilithium_3_length_signature;
#else
    static constexpr size_t PUBLIC_KEY_SIZE    = 1952;   
    static constexpr size_t SECRET_KEY_SIZE    = 4000;   
    static constexpr size_t SIGNATURE_MAX_SIZE = 3293;   
#endif
 
    struct SignKeyPair {
        std::vector<uint8_t> public_key;   
        std::vector<uint8_t> secret_key;   
 
        ~SignKeyPair() {
            if (!secret_key.empty()) {
                volatile uint8_t* p = secret_key.data();
                for (size_t i = 0; i < secret_key.size(); ++i) p[i] = 0;
            }
        }
    };
 
    // -----------------------------------------------------------------------
    // generate_keypair -- Generate a Dilithium-3 signing keypair
    //
    // Bundled mode:
    //   Generates random bytes for the keys and embeds a hash binding
    //   between public and secret keys for the signature stub to use.
    //
    // liboqs mode:
    //   Delegates to OQS_SIG_dilithium_3_keypair().
    // -----------------------------------------------------------------------
    [[nodiscard]] static expected<SignKeyPair> generate_keypair() {
        auto license = commercial::require_feature("Dilithium generate_keypair");
        if (!license) return license.error();
 
#ifdef SIGNET_HAS_LIBOQS
        // --- liboqs mode: real Dilithium-3 key generation ---
        OQS_SIG* sig = OQS_SIG_new(kOqsSigAlgMlDsa65);
        if (!sig) {
            return Error{ErrorCode::ENCRYPTION_ERROR,
                         "DilithiumSign: failed to initialize OQS Dilithium-3"};
        }
 
        SignKeyPair kp;
        kp.public_key.resize(sig->length_public_key);
        kp.secret_key.resize(sig->length_secret_key);
 
        OQS_STATUS rc = OQS_SIG_keypair(sig,
                                          kp.public_key.data(),
                                          kp.secret_key.data());
        OQS_SIG_free(sig);
 
        if (rc != OQS_SUCCESS) {
            return Error{ErrorCode::ENCRYPTION_ERROR,
                         "DilithiumSign: OQS keypair generation failed"};
        }
 
        return kp;
#else
#ifndef SIGNET_ALLOW_STUB_PQ
        return Error{ErrorCode::ENCRYPTION_ERROR,
                     "DilithiumSign: stub PQ implementation provides zero security. "
                     "Install liboqs and rebuild with -DSIGNET_ENABLE_PQ=ON, "
                     "or define SIGNET_ALLOW_STUB_PQ to allow the insecure stub."};
#else
        // --- TEST-ONLY STUB IMPLEMENTATION — use liboqs for production ---
        //
        // Generates random keys with an embedded binding:
        //   secret_key layout: [random(3936)] [SHA-256(pk_seed)(32)] [pk_seed(32)]
        //   public_key layout: [pk_seed(32)] [random(1920)]
        //
        // The pk_seed is shared between both keys so that sign() can produce
        // a deterministic "signature" that verify() can check.
 
        SignKeyPair kp;
        kp.public_key = detail::pq::random_bytes(PUBLIC_KEY_SIZE);
        kp.secret_key = detail::pq::random_bytes(SECRET_KEY_SIZE);
 
        // Embed the first 32 bytes of public key (pk_seed) at the end of
        // secret key, and its hash before it, for the stub signature scheme.
        auto pk_seed_hash = detail::sha256::sha256(
            kp.public_key.data(), 32);
 
        // sk[3968..3999] = pk_seed (first 32 bytes of pk)
        std::memcpy(kp.secret_key.data() + SECRET_KEY_SIZE - 32,
                    kp.public_key.data(), 32);
 
        // sk[3936..3967] = SHA-256(pk_seed)
        std::memcpy(kp.secret_key.data() + SECRET_KEY_SIZE - 64,
                    pk_seed_hash.data(), 32);
 
        return kp;
#endif
#endif
    }
 
    // -----------------------------------------------------------------------
    // sign -- Sign a message with the secret key
    //
    // Produces a signature of up to SIGNATURE_MAX_SIZE bytes.
    //
    // Bundled mode:
    //   Produces a "signature" = SHA-256(sk_binding || message) padded to
    //   a fixed size. This is NOT a real Dilithium lattice signature and
    //   provides NO post-quantum security. Any party with the secret key
    //   binding can forge signatures.
    //
    // liboqs mode:
    //   Delegates to OQS_SIG_dilithium_3_sign().
    // -----------------------------------------------------------------------
    [[nodiscard]] static expected<std::vector<uint8_t>> sign(
        const uint8_t* message, size_t msg_size,
        const uint8_t* secret_key, size_t sk_size) {
 
        auto license = commercial::require_feature("Dilithium sign");
        if (!license) return license.error();
 
        if (sk_size != SECRET_KEY_SIZE) {
            return Error{ErrorCode::ENCRYPTION_ERROR,
                         "DilithiumSign: secret key must be "
                         + std::to_string(SECRET_KEY_SIZE) + " bytes, got "
                         + std::to_string(sk_size)};
        }
 
#ifdef SIGNET_HAS_LIBOQS
        // --- liboqs mode: real Dilithium-3 signing ---
        OQS_SIG* sig = OQS_SIG_new(kOqsSigAlgMlDsa65);
        if (!sig) {
            return Error{ErrorCode::ENCRYPTION_ERROR,
                         "DilithiumSign: failed to initialize OQS Dilithium-3"};
        }
 
        std::vector<uint8_t> signature(sig->length_signature);
        size_t sig_len = 0;
 
        OQS_STATUS rc = OQS_SIG_sign(sig,
                                       signature.data(), &sig_len,
                                       message, msg_size,
                                       secret_key);
        OQS_SIG_free(sig);
 
        if (rc != OQS_SUCCESS) {
            return Error{ErrorCode::ENCRYPTION_ERROR,
                         "DilithiumSign: OQS signing failed"};
        }
 
        signature.resize(sig_len);
        return signature;
#else
#ifndef SIGNET_ALLOW_STUB_PQ
        return Error{ErrorCode::ENCRYPTION_ERROR,
                     "DilithiumSign: stub PQ implementation provides zero security. "
                     "Install liboqs and rebuild with -DSIGNET_ENABLE_PQ=ON, "
                     "or define SIGNET_ALLOW_STUB_PQ to allow the insecure stub."};
#else
        // --- TEST-ONLY STUB IMPLEMENTATION — use liboqs for production ---
        //
        // "Signature" = SHA-256(pk_seed_hash || message), zero-padded to
        // SIGNATURE_MAX_SIZE bytes.
        //
        // pk_seed_hash is extracted from sk[3936..3967].
        // This is a MAC, NOT a digital signature. It proves knowledge of
        // the secret key but does NOT provide the non-repudiation or
        // unforgeability guarantees of a real Dilithium signature.
 
        // Extract the pk_seed_hash from the secret key
        std::array<uint8_t, 32> pk_seed_hash;
        std::memcpy(pk_seed_hash.data(),
                    secret_key + SECRET_KEY_SIZE - 64, 32);
 
        // Compute "signature" = SHA-256(pk_seed_hash || message)
        auto sig_hash = detail::sha256::sha256_concat(
            pk_seed_hash.data(), pk_seed_hash.size(),
            message, msg_size);
 
        // Pad to SIGNATURE_MAX_SIZE
        // Layout: [SHA-256 hash (32 bytes)] [deterministic padding (3261 bytes)]
        std::vector<uint8_t> signature(SIGNATURE_MAX_SIZE, 0);
        std::memcpy(signature.data(), sig_hash.data(), 32);
 
        // Fill padding deterministically from the hash so verify() can
        // check it (the padding is derived, not random)
        for (size_t i = 32; i < SIGNATURE_MAX_SIZE; ++i) {
            signature[i] = sig_hash[i % 32] ^ static_cast<uint8_t>(i & 0xFF);
        }
 
        return signature;
#endif
#endif
    }
 
    // -----------------------------------------------------------------------
    // verify -- Verify a signature against a message and public key
    //
    // Returns true if the signature is valid, false otherwise.
    //
    // Bundled mode:
    //   Recomputes the expected "signature" from the public key's pk_seed
    //   and message, then compares in constant time.
    //
    // liboqs mode:
    //   Delegates to OQS_SIG_dilithium_3_verify().
    // -----------------------------------------------------------------------
    [[nodiscard]] static expected<bool> verify(
        const uint8_t* message, size_t msg_size,
        const uint8_t* signature, size_t sig_size,
        const uint8_t* public_key, size_t pk_size) {
 
        auto license = commercial::require_feature("Dilithium verify");
        if (!license) return license.error();
 
        if (pk_size != PUBLIC_KEY_SIZE) {
            return Error{ErrorCode::ENCRYPTION_ERROR,
                         "DilithiumSign: public key must be "
                         + std::to_string(PUBLIC_KEY_SIZE) + " bytes, got "
                         + std::to_string(pk_size)};
        }
        if (sig_size == 0 || sig_size > SIGNATURE_MAX_SIZE) {
            return Error{ErrorCode::ENCRYPTION_ERROR,
                         "DilithiumSign: invalid signature size "
                         + std::to_string(sig_size)};
        }
 
#ifdef SIGNET_HAS_LIBOQS
        // --- liboqs mode: real Dilithium-3 verification ---
        OQS_SIG* sig_ctx = OQS_SIG_new(kOqsSigAlgMlDsa65);
        if (!sig_ctx) {
            return Error{ErrorCode::ENCRYPTION_ERROR,
                         "DilithiumSign: failed to initialize OQS Dilithium-3"};
        }
 
        OQS_STATUS rc = OQS_SIG_verify(sig_ctx,
                                         message, msg_size,
                                         signature, sig_size,
                                         public_key);
        OQS_SIG_free(sig_ctx);
 
        return (rc == OQS_SUCCESS);
#else
#ifndef SIGNET_ALLOW_STUB_PQ
        return Error{ErrorCode::ENCRYPTION_ERROR,
                     "DilithiumSign: stub PQ implementation provides zero security. "
                     "Install liboqs and rebuild with -DSIGNET_ENABLE_PQ=ON, "
                     "or define SIGNET_ALLOW_STUB_PQ to allow the insecure stub."};
#else
        // --- TEST-ONLY STUB IMPLEMENTATION — use liboqs for production ---
        //
        // Recompute the expected "signature" from pk_seed and message,
        // then compare the first 32 bytes (the SHA-256 core) in constant time.
 
        // Extract pk_seed from the first 32 bytes of the public key
        auto pk_seed_hash = detail::sha256::sha256(public_key, 32);
 
        // Recompute expected signature hash
        auto expected_hash = detail::sha256::sha256_concat(
            pk_seed_hash.data(), pk_seed_hash.size(),
            message, msg_size);
 
        // Constant-time comparison of the first 32 bytes
        // (the SHA-256 hash is the cryptographic core of our stub signature)
        if (sig_size < 32) {
            return false;
        }
 
        uint8_t diff = 0;
        for (size_t i = 0; i < 32; ++i) {
            diff |= signature[i] ^ expected_hash[i];
        }
 
        return (diff == 0);
#endif
#endif
    }
};
 
// ===========================================================================
// HybridKem -- Kyber-768 + X25519 Hybrid Key Encapsulation
//
// Combines post-quantum (Kyber-768) and classical (X25519) key exchange
// into a single hybrid KEM. The shared secret is derived as:
//
//   shared_secret = SHA-256(kyber_shared_secret || x25519_shared_secret)
//
// This provides defense-in-depth: even if Kyber is broken (unlikely given
// NIST standardization), X25519 still provides classical security. And
// if X25519 is broken by a quantum computer, Kyber still provides
// post-quantum security.
//
// This follows the "KEM combiner" approach recommended by NIST and the
// IETF Composite KEM draft.
//
// X25519 implementation:
//   Uses the constant-time Montgomery ladder in detail::x25519 (RFC 7748).
//   DH commutativity: X25519(eph_sk, recip_pk) == X25519(recip_sk, eph_pk).
//   This is correct in both bundled mode and liboqs mode.
// ===========================================================================
 
class HybridKem {
public:
    static constexpr size_t X25519_PUBLIC_KEY_SIZE    = 32;  
    static constexpr size_t X25519_SECRET_KEY_SIZE    = 32;  
    static constexpr size_t HYBRID_SHARED_SECRET_SIZE = 32;  
 
    struct HybridKeyPair {
        std::vector<uint8_t> kyber_public_key;   
        std::vector<uint8_t> kyber_secret_key;   
        std::vector<uint8_t> x25519_public_key;  
        std::vector<uint8_t> x25519_secret_key;  
 
        ~HybridKeyPair() {
            if (!kyber_secret_key.empty()) {
                volatile uint8_t* p = kyber_secret_key.data();
                for (size_t i = 0; i < kyber_secret_key.size(); ++i) p[i] = 0;
            }
            if (!x25519_secret_key.empty()) {
                volatile uint8_t* p = x25519_secret_key.data();
                for (size_t i = 0; i < x25519_secret_key.size(); ++i) p[i] = 0;
            }
        }
    };
 
    struct HybridEncapsResult {
        std::vector<uint8_t> kyber_ciphertext;   
        std::vector<uint8_t> x25519_public_key;  
        std::vector<uint8_t> shared_secret;      
    };
 
    // -----------------------------------------------------------------------
    // generate_keypair
    // Generates Kyber-768 + real X25519 (RFC 7748) keypair.
    // -----------------------------------------------------------------------
    [[nodiscard]] static expected<HybridKeyPair> generate_keypair() {
        auto license = commercial::require_feature("HybridKem generate_keypair");
        if (!license) return license.error();
 
        // Kyber-768 component (stub or real via liboqs)
        auto kyber_result = KyberKem::generate_keypair();
        if (!kyber_result) return kyber_result.error();
 
        HybridKeyPair hkp;
        hkp.kyber_public_key = std::move(kyber_result->public_key);
        hkp.kyber_secret_key = std::move(kyber_result->secret_key);
 
        // X25519 component: real RFC 7748 Curve25519 keypair
        auto x25519_kp = detail::x25519::generate_keypair();
        if (!x25519_kp) return x25519_kp.error();
 
        hkp.x25519_secret_key.assign(x25519_kp->first.begin(),  x25519_kp->first.end());
        hkp.x25519_public_key.assign(x25519_kp->second.begin(), x25519_kp->second.end());
 
        return hkp;
    }
 
    // -----------------------------------------------------------------------
    // encapsulate
    //
    // Kyber-768 encapsulation (stub or liboqs) + real X25519 DH:
    //   1. kyber_ss from KyberKem::encapsulate(recipient.kyber_pk)
    //   2. Generate ephemeral X25519 keypair (eph_sk, eph_pk)
    //   3. x25519_ss = X25519(eph_sk, recipient.x25519_pk)  -- real DH
    //   4. shared_secret = SHA-256(kyber_ss || x25519_ss)
    //   5. Send: kyber_ciphertext + eph_pk
    //
    // The recipient runs decapsulate() with their full keypair to
    // recover the same shared_secret because X25519 is commutative:
    //   X25519(eph_sk, recip_pk) == X25519(recip_sk, eph_pk)
    // -----------------------------------------------------------------------
    [[nodiscard]] static expected<HybridEncapsResult> encapsulate(
        const HybridKeyPair& recipient_pk) {
 
        auto license = commercial::require_feature("HybridKem encapsulate");
        if (!license) return license.error();
 
        // Step 1: Kyber-768 encapsulation
        auto kyber_result = KyberKem::encapsulate(
            recipient_pk.kyber_public_key.data(),
            recipient_pk.kyber_public_key.size());
        if (!kyber_result) return kyber_result.error();
 
        // Step 2: Generate ephemeral X25519 keypair
        auto eph_kp = detail::x25519::generate_keypair();
        if (!eph_kp) return eph_kp.error();
        const auto& eph_sk = eph_kp->first;
        const auto& eph_pk = eph_kp->second;
 
        // Step 3: X25519 shared secret = X25519(eph_sk, recipient.x25519_pk)
        if (recipient_pk.x25519_public_key.size() != 32) {
            return Error{ErrorCode::ENCRYPTION_ERROR,
                         "HybridKem: recipient X25519 public key must be 32 bytes"};
        }
        std::array<uint8_t, 32> recip_x25519_pk;
        std::memcpy(recip_x25519_pk.data(),
                    recipient_pk.x25519_public_key.data(), 32);
 
        auto x25519_ss_result = detail::x25519::x25519(eph_sk, recip_x25519_pk);
        if (!x25519_ss_result) return x25519_ss_result.error();
 
        // Step 4: Combined shared secret = SHA-256(label || kyber_ss || x25519_ss)
        // Domain separation per NIST SP 800-227 (Final, Sep 2025) §4.2 hybrid combiner
        auto combined = detail::sha256::sha256_concat(
            kyber_result->shared_secret.data(),
            kyber_result->shared_secret.size(),
            x25519_ss_result->data(),
            x25519_ss_result->size());
 
        HybridEncapsResult result;
        result.kyber_ciphertext = std::move(kyber_result->ciphertext);
        result.x25519_public_key.assign(eph_pk.begin(), eph_pk.end());
        result.shared_secret.assign(combined.begin(), combined.end());
 
        return result;
    }
 
    // -----------------------------------------------------------------------
    // decapsulate
    //
    // Recovers the same shared_secret as encapsulate() because X25519 DH
    // is commutative: X25519(eph_sk, recip_pk) == X25519(recip_sk, eph_pk).
    //
    //   1. kyber_ss = KyberKem::decapsulate(kyber_ciphertext, recip.kyber_sk)
    //   2. x25519_ss = X25519(recip.x25519_sk, eph_pk)  -- commutative with encaps
    //   3. shared_secret = SHA-256(kyber_ss || x25519_ss)  -- identical to encaps
    //
    // Works in both bundled mode (Kyber stub + real X25519) and
    // liboqs mode (real Kyber + real X25519).
    // -----------------------------------------------------------------------
    [[nodiscard]] static expected<std::vector<uint8_t>> decapsulate(
        const HybridEncapsResult& encaps,
        const HybridKeyPair& recipient_sk) {
 
        auto license = commercial::require_feature("HybridKem decapsulate");
        if (!license) return license.error();
 
        // Step 1: Kyber-768 decapsulation
        auto kyber_ss = KyberKem::decapsulate(
            encaps.kyber_ciphertext.data(),
            encaps.kyber_ciphertext.size(),
            recipient_sk.kyber_secret_key.data(),
            recipient_sk.kyber_secret_key.size());
        if (!kyber_ss) return kyber_ss.error();
 
        // Step 2: X25519 key agreement (commutative with encapsulate)
        if (recipient_sk.x25519_secret_key.size() != 32 ||
            encaps.x25519_public_key.size() != 32) {
            return Error{ErrorCode::ENCRYPTION_ERROR,
                         "HybridKem: X25519 key sizes must be 32 bytes"};
        }
        std::array<uint8_t, 32> recip_sk_arr, eph_pk_arr;
        std::memcpy(recip_sk_arr.data(), recipient_sk.x25519_secret_key.data(), 32);
        std::memcpy(eph_pk_arr.data(),   encaps.x25519_public_key.data(),       32);
 
        auto x25519_ss_result = detail::x25519::x25519(recip_sk_arr, eph_pk_arr);
        if (!x25519_ss_result) return x25519_ss_result.error();
 
        // Step 3: Combined shared secret — identical to encapsulate()
        // Domain separation per NIST SP 800-227 (Final, Sep 2025) §4.2 hybrid combiner
        auto combined = detail::sha256::sha256_concat(
            kyber_ss->data(), kyber_ss->size(),
            x25519_ss_result->data(), x25519_ss_result->size());
 
        return std::vector<uint8_t>(combined.begin(), combined.end());
    }
};
 
// ===========================================================================
// PostQuantumConfig -- Configuration for post-quantum encryption in PME
//
// This structure integrates with the existing EncryptionConfig to add
// post-quantum key encapsulation and footer signing.
//
// Usage:
//   PostQuantumConfig pq_cfg;
//   pq_cfg.enabled = true;
//   pq_cfg.hybrid_mode = true;  // Kyber + X25519
//
//   // Generate keypairs (typically done once, stored securely)
//   auto kem_kp = KyberKem::generate_keypair();
//   pq_cfg.recipient_public_key = kem_kp->public_key;
//   pq_cfg.recipient_secret_key = kem_kp->secret_key;
//
//   auto sig_kp = DilithiumSign::generate_keypair();
//   pq_cfg.signing_public_key = sig_kp->public_key;
//   pq_cfg.signing_secret_key = sig_kp->secret_key;
//
// When writing:
//   1. encapsulate() with recipient_public_key to get the AES-256 key
//   2. Use that key as the footer_key / column_key in EncryptionConfig
//   3. sign() the serialized footer with signing_secret_key
//   4. Store the KEM ciphertext and signature in file metadata
//
// When reading:
//   1. decapsulate() with recipient_secret_key to recover the AES-256 key
//   2. Use that key to decrypt footer / columns via PME
//   3. verify() the footer signature with signing_public_key
// ===========================================================================
 
struct PostQuantumConfig {
    bool enabled = false;
 
    bool hybrid_mode = true;
 
    // --- Kyber KEM keypair for file encryption key exchange ---
 
    std::vector<uint8_t> recipient_public_key;
 
    std::vector<uint8_t> recipient_secret_key;
 
    // --- Dilithium signing keypair for footer signing ---
 
    std::vector<uint8_t> signing_public_key;
 
    std::vector<uint8_t> signing_secret_key;
 
    ~PostQuantumConfig() {
        auto zero_vec = [](std::vector<uint8_t>& v) {
            if (!v.empty()) {
                volatile uint8_t* p = v.data();
                for (size_t i = 0; i < v.size(); ++i) p[i] = 0;
            }
        };
        zero_vec(recipient_secret_key);
        zero_vec(signing_secret_key);
    }
};
 
} // namespace signet::forge::crypto