#!/usr/bin/env python3
from __future__ import annotations

import json
import textwrap
import traceback
from dataclasses import dataclass, field
from pathlib import Path
from typing import Any, Callable, Dict, Iterable, List, Optional

from Crypto.Cipher import AES, PKCS1_OAEP, PKCS1_v1_5, ChaCha20_Poly1305, Salsa20
from Crypto.Hash import HMAC, SHA256, SHA3_256, SHA512
from Crypto.IO import PEM, PKCS8
from Crypto.Protocol import HPKE
from Crypto.Protocol.DH import (
    import_x25519_private_key,
    import_x25519_public_key,
    key_agreement,
)
from Crypto.Protocol.KDF import HKDF, PBKDF2, scrypt
from Crypto.Protocol.SecretSharing import Shamir
from Crypto.PublicKey import ECC, RSA
from Crypto.Random import get_random_bytes
from Crypto.Signature import DSS, eddsa, pkcs1_15, pss
from Crypto.Util import Counter, RFC1751, number
from Crypto.Util.Padding import pad, unpad
from Crypto.Util.number import bytes_to_long, long_to_bytes
from Crypto.Util.strxor import strxor, strxor_c


SCRIPT_DIR = Path(__file__).resolve().parent
REPORT_PATH = SCRIPT_DIR / "Usage_report.md"


def _hex(data: bytes, limit: int = 64) -> str:
    value = data.hex()
    return value if len(value) <= limit else value[:limit] + "..."


def _repr_value(value: Any) -> str:
    if isinstance(value, bytes):
        return f"{_hex(value)} ({len(value)} bytes)"
    if isinstance(value, str):
        return value
    if isinstance(value, (int, float, bool)) or value is None:
        return repr(value)
    if isinstance(value, (list, tuple)):
        return json.dumps([_repr_value(item) for item in value], ensure_ascii=False, indent=2)
    if isinstance(value, dict):
        pretty = {str(k): _repr_value(v) for k, v in value.items()}
        return json.dumps(pretty, ensure_ascii=False, indent=2, sort_keys=True)
    return repr(value)


def l2b(value: int, blocksize: int = 0) -> bytes:
    if not isinstance(value, int):
        raise TypeError("value must be an int")
    if value < 0:
        raise ValueError("value must be non-negative")
    return long_to_bytes(value, blocksize) if blocksize else long_to_bytes(value)


def b2l(data: bytes) -> int:
    if not isinstance(data, (bytes, bytearray, memoryview)):
        raise TypeError("data must be bytes-like")
    return bytes_to_long(bytes(data))


def random_bytes(length: int) -> bytes:
    if length <= 0:
        raise ValueError("length must be positive")
    return get_random_bytes(length)


def xor_bytes(left: bytes, right: bytes) -> bytes:
    if len(left) != len(right):
        raise ValueError("inputs must have the same length")
    return strxor(left, right)


def xor_with_constant(data: bytes, constant: int) -> bytes:
    if not 0 <= constant <= 0xFF:
        raise ValueError("constant must be in range(0, 256)")
    return strxor_c(data, constant)


def split_blocks(data: bytes, block_size: int) -> List[bytes]:
    if block_size <= 0:
        raise ValueError("block_size must be positive")
    return [data[i : i + block_size] for i in range(0, len(data), block_size)]


def pad_bytes(data: bytes, block_size: int, style: str = "pkcs7") -> bytes:
    return pad(data, block_size, style=style)


def unpad_bytes(data: bytes, block_size: int, style: str = "pkcs7") -> bytes:
    return unpad(data, block_size, style=style)


def make_ctr_counter(
    *,
    nbits: int,
    prefix: bytes = b"",
    suffix: bytes = b"",
    initial_value: int = 1,
    little_endian: bool = False,
):
    return Counter.new(
        nbits,
        prefix=prefix,
        suffix=suffix,
        initial_value=initial_value,
        little_endian=little_endian,
    )


def derive_hkdf_key(master: bytes, length: int, salt: bytes, context: bytes = b"") -> bytes:
    return HKDF(master, length, salt, SHA256, context=context)


def derive_pbkdf2_key(password: bytes, salt: bytes, length: int, count: int = 100_000) -> bytes:
    return PBKDF2(password, salt, dkLen=length, count=count, hmac_hash_module=SHA512)


def derive_scrypt_key(password: bytes, salt: bytes, length: int, n: int = 2**14, r: int = 8, p: int = 1) -> bytes:
    return scrypt(password, salt, key_len=length, N=n, r=r, p=p)


def rfc1751_encode(key: bytes) -> str:
    return RFC1751.key_to_english(key)


def rfc1751_decode(words: str) -> bytes:
    return RFC1751.english_to_key(words)


def pem_wrap(data: bytes, marker: str, passphrase: Optional[bytes] = None) -> str:
    return PEM.encode(data, marker, passphrase=passphrase)


def pem_unwrap(pem_data: str, passphrase: Optional[bytes] = None):
    return PEM.decode(pem_data, passphrase=passphrase)


def pkcs8_wrap_der(
    private_key_der: bytes,
    key_oid: str,
    passphrase: bytes,
    protection: str = "PBKDF2WithHMAC-SHA512AndAES256-CBC",
    prot_params: Optional[Dict[str, Any]] = None,
) -> bytes:
    if prot_params is None:
        prot_params = {"iteration_count": 21_000}
    return PKCS8.wrap(
        private_key_der,
        key_oid,
        passphrase=passphrase,
        protection=protection,
        prot_params=prot_params,
    )


def pkcs8_unwrap_der(blob: bytes, passphrase: bytes):
    return PKCS8.unwrap(blob, passphrase=passphrase)


def generate_prime(bits: int = 256) -> int:
    return number.getPrime(bits)


def generate_strong_prime(bits: int = 512) -> int:
    return number.getStrongPrime(bits)


def mod_inverse(value: int, modulus: int) -> int:
    return number.inverse(value, modulus)


@dataclass
class Check:
    label: str
    passed: bool
    detail: str

    @property
    def status(self) -> str:
        return "PASS" if self.passed else "FAIL"


@dataclass
class DemoResult:
    name: str
    description: str
    usage_example: str
    outputs: Dict[str, Any] = field(default_factory=dict)
    pass_checks: List[Check] = field(default_factory=list)
    expected_failures: List[Check] = field(default_factory=list)
    notes: List[str] = field(default_factory=list)
    unexpected_error: Optional[str] = None

    @property
    def ok(self) -> bool:
        return self.unexpected_error is None and all(item.passed for item in self.pass_checks + self.expected_failures)


def condition(label: str, ok: bool, success_detail: str, failure_detail: str) -> Check:
    return Check(label=label, passed=ok, detail=success_detail if ok else failure_detail)


def expect_exception(label: str, func: Callable[[], Any], *exc_types: type[BaseException]) -> Check:
    try:
        func()
    except exc_types as exc:
        return Check(label=label, passed=True, detail=f"raised {type(exc).__name__}: {exc}")
    except Exception as exc:  # noqa: BLE001
        expected = ", ".join(exc.__name__ for exc in exc_types)
        return Check(
            label=label,
            passed=False,
            detail=f"raised unexpected {type(exc).__name__}: {exc}; expected {expected}",
        )
    expected = ", ".join(exc.__name__ for exc in exc_types)
    return Check(label=label, passed=False, detail=f"did not raise; expected {expected}")


def expect_equal(label: str, left: Any, right: Any) -> Check:
    return condition(label, left == right, "values match", f"values differ: {left!r} != {right!r}")


def expect_not_equal(label: str, left: Any, right: Any, detail: str) -> Check:
    return condition(label, left != right, detail, "values unexpectedly matched")


def expect_sentinel(label: str, value: bytes, sentinel: bytes) -> Check:
    return condition(label, value == sentinel, "returned sentinel as designed", "did not return sentinel")


@dataclass
class Context:
    rsa_key: Any
    p256_key: Any
    ed25519_key: Any
    x25519_key: Any
    passphrase: bytes


def build_context() -> Context:
    return Context(
        rsa_key=RSA.generate(2048),
        p256_key=ECC.generate(curve="P-256"),
        ed25519_key=ECC.generate(curve="Ed25519"),
        x25519_key=ECC.generate(curve="Curve25519"),
        passphrase=b"correct horse battery staple",
    )


def demo_utilities_and_low_level_helpers() -> DemoResult:
    result = DemoResult(
        name="Utilities and low-level helpers",
        description="Integer/byte conversions, XOR helpers, number theory helpers, RFC1751, PEM, and PKCS#8 wrappers.",
        usage_example=textwrap.dedent(
            """\
            from pycryptodome_showcase_runner import (
                b2l, l2b, random_bytes, xor_bytes, xor_with_constant,
                generate_prime, generate_strong_prime, mod_inverse,
                rfc1751_encode, rfc1751_decode, pem_wrap, pem_unwrap,
                pkcs8_wrap_der, pkcs8_unwrap_der,
            )

            sample = l2b(65537)
            assert b2l(sample) == 65537
            mixed = xor_bytes(b"ABCDEF12", b"12345678")
            flipped = xor_with_constant(b"AAAA", 0x20)
            """
        ),
    )

    value = 65537
    encoded = l2b(value)
    decoded = b2l(encoded)
    random_blob = random_bytes(24)
    blocks = split_blocks(random_blob, 8)

    left = b"ByteString123456"
    right = b"AnotherString789"
    xored = xor_bytes(left, right)
    xored_constant = xor_with_constant(b"AAAA", 0x20)

    prime = generate_prime(256)
    strong_prime = generate_strong_prime(512)
    inverse = mod_inverse(3, 11)

    english_key = rfc1751_encode(b"12345678")
    decoded_key = rfc1751_decode(english_key)

    pem_blob = pem_wrap(b"demo payload", "TEST DATA", passphrase=b"demo-pass")
    pem_data, pem_marker, pem_encrypted = pem_unwrap(pem_blob, passphrase=b"demo-pass")

    temp_rsa = RSA.generate(1024)
    wrapped = pkcs8_wrap_der(
        temp_rsa.export_key(format="DER"),
        "1.2.840.113549.1.1.1",
        passphrase=b"demo-pass",
    )
    oid, unwrapped_der, params = pkcs8_unwrap_der(wrapped, passphrase=b"demo-pass")

    result.outputs.update(
        {
            "l2b_65537_hex": encoded.hex(),
            "random_bytes_length": len(random_blob),
            "split_blocks_lengths": [len(block) for block in blocks],
            "xor_bytes_hex": xored.hex(),
            "xor_with_constant_hex": xored_constant.hex(),
            "prime_bits": number.size(prime),
            "strong_prime_bits": number.size(strong_prime),
            "inverse_mod_11_of_3": inverse,
            "rfc1751_words": english_key,
            "pem_marker": pem_marker,
            "pem_encrypted": pem_encrypted,
            "pkcs8_oid": oid,
            "pkcs8_inner_der_length": len(unwrapped_der),
            "pkcs8_params": params,
        }
    )

    result.pass_checks.extend(
        [
            expect_equal("l2b/b2l round-trip", decoded, value),
            condition("random_bytes returned the requested length", len(random_blob) == 24, "24 bytes returned", "length mismatch"),
            condition("split_blocks partitioned data evenly", [len(block) for block in blocks] == [8, 8, 8], "three 8-byte blocks", "unexpected block sizes"),
            condition("xor_bytes produced same-length output", len(xored) == len(left), "length preserved", "length mismatch"),
            condition("getPrime produced a prime", number.isPrime(prime), "isPrime returned True", "isPrime returned False"),
            condition("getStrongPrime produced a prime", number.isPrime(strong_prime), "isPrime returned True", "isPrime returned False"),
            expect_equal("inverse(3,11) == 4", inverse, 4),
            expect_equal("RFC1751 round-trip", decoded_key, b"12345678"),
            expect_equal("PEM decode recovered original bytes", pem_data, b"demo payload"),
            expect_equal("PKCS#8 unwrap recovered DER", RSA.import_key(unwrapped_der).n, temp_rsa.n),
        ]
    )

    result.expected_failures.extend(
        [
            expect_exception(
                "xor_bytes rejects mismatched lengths",
                lambda: xor_bytes(b"short", b"longer"),
                ValueError,
            ),
            expect_exception(
                "inverse rejects non-invertible input",
                lambda: mod_inverse(2, 4),
                ValueError,
            ),
            expect_exception(
                "RFC1751 rejects malformed word list",
                lambda: rfc1751_decode("ONE TWO THREE"),
                ValueError,
            ),
            expect_exception(
                "PEM decode rejects wrong passphrase",
                lambda: pem_unwrap(pem_blob, passphrase=b"wrong-pass"),
                ValueError,
            ),
            expect_exception(
                "PKCS#8 unwrap rejects wrong passphrase",
                lambda: pkcs8_unwrap_der(wrapped, passphrase=b"wrong-pass"),
                ValueError,
            ),
        ]
    )

    result.notes.extend(
        [
            "PEM.encode()/decode() demonstrate the low-level textual envelope. For private keys, PKCS#8 protection is the stronger default.",
            "RFC1751 is mostly historical today, but it is useful to know the module exists.",
        ]
    )
    return result


def demo_hashes_and_hmac() -> DemoResult:
    result = DemoResult(
        name="Hashes and HMAC",
        description="SHA-256, SHA3-256, and HMAC verification including expected tamper failure.",
        usage_example=textwrap.dedent(
            """\
            from pycryptodome_showcase_runner import demo_hashes_and_hmac

            outcome = demo_hashes_and_hmac()
            print(outcome.outputs["sha256"])
            """
        ),
    )

    message = b"hash me"
    sha256_hex = SHA256.new(message).hexdigest()
    sha3_hex = SHA3_256.new(message).hexdigest()

    key = get_random_bytes(32)
    signer = HMAC.new(key, digestmod=SHA256)
    signer.update(message)
    tag = signer.digest()

    verifier = HMAC.new(key, digestmod=SHA256)
    verifier.update(message)
    verifier.verify(tag)

    result.outputs.update({"sha256": sha256_hex, "sha3_256": sha3_hex, "hmac_tag": tag.hex()})
    result.pass_checks.extend(
        [
            condition("SHA-256 digest is 32 bytes", len(bytes.fromhex(sha256_hex)) == 32, "digest length is 32", "digest length mismatch"),
            condition("SHA3-256 digest is 32 bytes", len(bytes.fromhex(sha3_hex)) == 32, "digest length is 32", "digest length mismatch"),
            condition("HMAC verification succeeded", True, "tag verified", "tag did not verify"),
        ]
    )
    result.expected_failures.append(
        expect_exception(
            "HMAC verification fails on modified message",
            lambda: (lambda v: (v.update(message + b"!"), v.verify(tag)))(HMAC.new(key, digestmod=SHA256)),
            ValueError,
        )
    )
    return result


def demo_padding_and_cbc() -> DemoResult:
    result = DemoResult(
        name="Padding and AES-CBC",
        description="CBC mode with PKCS#7/ISO7816/X9.23 padding and expected padding failure on tamper.",
        usage_example=textwrap.dedent(
            """\
            from pycryptodome_showcase_runner import pad_bytes, unpad_bytes
            from Crypto.Cipher import AES
            from Crypto.Random import get_random_bytes

            key = get_random_bytes(16)
            iv = get_random_bytes(16)
            cipher = AES.new(key, AES.MODE_CBC, iv=iv)
            ciphertext = cipher.encrypt(pad_bytes(b"confidential", 16, style="pkcs7"))
            """
        ),
    )

    plaintext = b"Padding demo for CBC mode"
    styles = {}
    for style in ("pkcs7", "iso7816", "x923"):
        padded = pad_bytes(plaintext, AES.block_size, style=style)
        recovered = unpad_bytes(padded, AES.block_size, style=style)
        styles[style] = {"padded_length": len(padded), "round_trip": recovered == plaintext}

    key = get_random_bytes(16)
    iv = get_random_bytes(16)
    cipher = AES.new(key, AES.MODE_CBC, iv=iv)
    ciphertext = cipher.encrypt(pad_bytes(plaintext, AES.block_size, style="pkcs7"))

    cipher = AES.new(key, AES.MODE_CBC, iv=iv)
    recovered = unpad_bytes(cipher.decrypt(ciphertext), AES.block_size, style="pkcs7")

    tampered = bytearray(ciphertext)
    tampered[-1] ^= 1

    result.outputs.update(
        {
            "padding_styles": styles,
            "cbc_iv": iv.hex(),
            "cbc_ciphertext": ciphertext.hex(),
        }
    )
    result.pass_checks.extend(
        [
            expect_equal("CBC round-trip recovered original plaintext", recovered, plaintext),
            condition(
                "All padding styles round-tripped",
                all(item["round_trip"] for item in styles.values()),
                "all styles unpadded correctly",
                "a padding style failed",
            ),
        ]
    )
    result.expected_failures.append(
        expect_exception(
            "CBC + PKCS#7 unpad fails after last-byte tamper",
            lambda: unpad_bytes(AES.new(key, AES.MODE_CBC, iv=iv).decrypt(bytes(tampered)), AES.block_size, style="pkcs7"),
            ValueError,
        )
    )
    result.notes.append(
        "CBC provides confidentiality only. Padding errors are detectable here because the example explicitly calls unpad(); unauthenticated modification elsewhere may still decrypt to garbage."
    )
    return result


def _aead_round_trip(mode_name: str, key: bytes, plaintext: bytes, aad: bytes) -> Dict[str, Any]:
    if mode_name == "EAX":
        cipher = AES.new(key, AES.MODE_EAX)
    elif mode_name == "GCM":
        cipher = AES.new(key, AES.MODE_GCM)
    elif mode_name == "CCM":
        cipher = AES.new(key, AES.MODE_CCM)
    elif mode_name == "OCB":
        cipher = AES.new(key, AES.MODE_OCB)
    elif mode_name == "SIV":
        cipher = AES.new(key, AES.MODE_SIV)
    else:
        raise ValueError(f"unsupported mode {mode_name}")

    cipher.update(aad)
    ciphertext, tag = cipher.encrypt_and_digest(plaintext)
    nonce = getattr(cipher, "nonce", None)

    if mode_name == "EAX":
        dec = AES.new(key, AES.MODE_EAX, nonce=nonce)
    elif mode_name == "GCM":
        dec = AES.new(key, AES.MODE_GCM, nonce=nonce)
    elif mode_name == "CCM":
        dec = AES.new(key, AES.MODE_CCM, nonce=nonce)
    elif mode_name == "OCB":
        dec = AES.new(key, AES.MODE_OCB, nonce=nonce)
    else:
        dec = AES.new(key, AES.MODE_SIV)

    dec.update(aad)
    recovered = dec.decrypt_and_verify(ciphertext, tag)
    return {"nonce": nonce, "ciphertext": ciphertext, "tag": tag, "recovered": recovered}


def demo_aes_aead_modes() -> DemoResult:
    result = DemoResult(
        name="AES AEAD modes",
        description="EAX, GCM, CCM, OCB, and SIV with authenticated AAD and tamper detection.",
        usage_example=textwrap.dedent(
            """\
            from pycryptodome_showcase_runner import demo_aes_aead_modes

            report = demo_aes_aead_modes()
            for name, details in report.outputs["modes"].items():
                print(name, details["tag"])
            """
        ),
    )

    plaintext = b"AEAD-protected message"
    aad = b"header-data"
    modes_summary: Dict[str, Dict[str, Any]] = {}

    for mode_name, key in {
        "EAX": get_random_bytes(16),
        "GCM": get_random_bytes(32),
        "CCM": get_random_bytes(16),
        "OCB": get_random_bytes(16),
        "SIV": get_random_bytes(32),
    }.items():
        values = _aead_round_trip(mode_name, key, plaintext, aad)
        modes_summary[mode_name] = {
            "nonce": values["nonce"].hex() if values["nonce"] is not None else "omitted",
            "ciphertext": values["ciphertext"].hex(),
            "tag": values["tag"].hex(),
        }
        result.pass_checks.append(expect_equal(f"{mode_name} round-trip", values["recovered"], plaintext))

        bad_tag = bytearray(values["tag"])
        bad_tag[-1] ^= 1

        def fail_case() -> None:
            if mode_name == "EAX":
                dec = AES.new(key, AES.MODE_EAX, nonce=values["nonce"])
            elif mode_name == "GCM":
                dec = AES.new(key, AES.MODE_GCM, nonce=values["nonce"])
            elif mode_name == "CCM":
                dec = AES.new(key, AES.MODE_CCM, nonce=values["nonce"])
            elif mode_name == "OCB":
                dec = AES.new(key, AES.MODE_OCB, nonce=values["nonce"])
            else:
                dec = AES.new(key, AES.MODE_SIV)
            dec.update(aad)
            dec.decrypt_and_verify(values["ciphertext"], bytes(bad_tag))

        result.expected_failures.append(expect_exception(f"{mode_name} rejects bad tag", fail_case, ValueError))

    siv_key = get_random_bytes(32)
    siv_1 = AES.new(siv_key, AES.MODE_SIV)
    siv_1.update(aad)
    ct1, tag1 = siv_1.encrypt_and_digest(plaintext)
    siv_2 = AES.new(siv_key, AES.MODE_SIV)
    siv_2.update(aad)
    ct2, tag2 = siv_2.encrypt_and_digest(plaintext)

    result.outputs["modes"] = modes_summary
    result.outputs["siv_deterministic_ciphertext_match"] = ct1 <mark> ct2 and tag1 </mark> tag2
    result.pass_checks.append(
        condition(
            "SIV is deterministic when nonce is omitted",
            ct1 <mark> ct2 and tag1 </mark> tag2,
            "identical plaintext/AAD produced identical ciphertext+tag",
            "SIV unexpectedly differed without a nonce",
        )
    )
    result.notes.append("SIV is the odd one out: omitting the nonce is valid and makes encryption deterministic.")
    return result


def demo_ctr_and_counter() -> DemoResult:
    result = DemoResult(
        name="AES-CTR and Counter utility",
        description="CTR mode with custom Counter.new(), wraparound detection, and an example of silent failure when metadata is wrong.",
        usage_example=textwrap.dedent(
            """\
            from pycryptodome_showcase_runner import make_ctr_counter
            from Crypto.Cipher import AES
            from Crypto.Random import get_random_bytes

            key = get_random_bytes(16)
            prefix = get_random_bytes(8)
            ctr = make_ctr_counter(nbits=64, prefix=prefix, initial_value=1)
            cipher = AES.new(key, AES.MODE_CTR, counter=ctr)
            """
        ),
    )

    key = get_random_bytes(16)
    prefix = get_random_bytes(8)
    plaintext = b"CTR mode does not authenticate ciphertext"

    ctr = make_ctr_counter(nbits=64, prefix=prefix, initial_value=1)
    cipher = AES.new(key, AES.MODE_CTR, counter=ctr)
    ciphertext = cipher.encrypt(plaintext)

    ctr = make_ctr_counter(nbits=64, prefix=prefix, initial_value=1)
    recovered = AES.new(key, AES.MODE_CTR, counter=ctr).decrypt(ciphertext)

    wrong_prefix = bytes([prefix[0] ^ 1]) + prefix[1:]
    ctr_wrong = make_ctr_counter(nbits=64, prefix=wrong_prefix, initial_value=1)
    wrong_plaintext = AES.new(key, AES.MODE_CTR, counter=ctr_wrong).decrypt(ciphertext)

    tiny_prefix = get_random_bytes(15)

    def overflow_case() -> None:
        ctr_local = make_ctr_counter(nbits=8, prefix=tiny_prefix, initial_value=1)
        AES.new(key, AES.MODE_CTR, counter=ctr_local).encrypt(b"A" * (16 * 260))

    result.outputs.update(
        {
            "ctr_prefix": prefix.hex(),
            "ctr_ciphertext": ciphertext.hex(),
            "wrong_prefix_plaintext": wrong_plaintext.hex(),
        }
    )
    result.pass_checks.append(expect_equal("CTR round-trip", recovered, plaintext))
    result.expected_failures.extend(
        [
            expect_exception("Counter overflow raises OverflowError", overflow_case, OverflowError),
            expect_not_equal(
                "Wrong CTR prefix silently yields wrong plaintext",
                wrong_plaintext,
                plaintext,
                "plaintext changed without an authentication exception",
            ),
        ]
    )
    result.notes.append("CTR is a confidentiality mode only. The library can detect counter wraparound, but it cannot detect ciphertext tampering without an external MAC or AEAD wrapper.")
    return result


def demo_aes_kw_kwp() -> DemoResult:
    result = DemoResult(
        name="AES Key Wrap (KW/KWP)",
        description="Deterministic authenticated key wrapping for key material.",
        usage_example=textwrap.dedent(
            """\
            from Crypto.Cipher import AES
            from Crypto.Random import get_random_bytes

            kek = get_random_bytes(16)
            wrapped = AES.new(kek, AES.MODE_KW).seal(b"12345678abcdefgh")
            """
        ),
    )

    kek = get_random_bytes(16)
    key_to_wrap = b"12345678abcdefgh"
    kw_wrapped = AES.new(kek, AES.MODE_KW).seal(key_to_wrap)
    kw_unwrapped = AES.new(kek, AES.MODE_KW).unseal(kw_wrapped)

    padded_key = b"not multiple of 8 bytes"
    kwp_wrapped = AES.new(kek, AES.MODE_KWP).seal(padded_key)
    kwp_unwrapped = AES.new(kek, AES.MODE_KWP).unseal(kwp_wrapped)

    result.outputs.update(
        {
            "kw_wrapped": kw_wrapped.hex(),
            "kwp_wrapped": kwp_wrapped.hex(),
        }
    )
    result.pass_checks.extend(
        [
            expect_equal("KW unwrapped the original key", kw_unwrapped, key_to_wrap),
            expect_equal("KWP unwrapped the original key", kwp_unwrapped, padded_key),
        ]
    )

    bad_kw = bytearray(kw_wrapped)
    bad_kw[-1] ^= 1
    bad_kwp = bytearray(kwp_wrapped)
    bad_kwp[0] ^= 1

    result.expected_failures.extend(
        [
            expect_exception(
                "KW rejects modified wrapped key",
                lambda: AES.new(kek, AES.MODE_KW).unseal(bytes(bad_kw)),
                ValueError,
            ),
            expect_exception(
                "KWP rejects modified wrapped key",
                lambda: AES.new(kek, AES.MODE_KWP).unseal(bytes(bad_kwp)),
                ValueError,
            ),
        ]
    )
    result.notes.append("KW requires wrapped key material to be a multiple of 8 bytes. KWP removes that constraint.")
    return result


def demo_rsa_primitives(ctx: Context) -> DemoResult:
    result = DemoResult(
        name="RSA encryption and signatures",
        description="OAEP, PKCS#1 v1.5 encryption, RSA-PSS, and PKCS#1 v1.5 signatures.",
        usage_example=textwrap.dedent(
            """\
            from Crypto.Hash import SHA256
            from Crypto.Cipher import PKCS1_OAEP
            from Crypto.Signature import pss

            key = RSA.generate(2048)
            ciphertext = PKCS1_OAEP.new(key.public_key(), hashAlgo=SHA256).encrypt(b"secret")
            signature = pss.new(key).sign(SHA256.new(b"message"))
            """
        ),
    )

    key = ctx.rsa_key
    message = b"RSA primitive demo"
    small_secret = b"0123456789abcdef"

    oaep_ciphertext = PKCS1_OAEP.new(key.public_key(), hashAlgo=SHA256, label=b"context").encrypt(message)
    oaep_plaintext = PKCS1_OAEP.new(key, hashAlgo=SHA256, label=b"context").decrypt(oaep_ciphertext)

    legacy_ciphertext = PKCS1_v1_5.new(key.public_key()).encrypt(small_secret)
    sentinel = get_random_bytes(len(small_secret))
    legacy_plaintext = PKCS1_v1_5.new(key).decrypt(legacy_ciphertext, sentinel, expected_pt_len=len(small_secret))

    msg_hash = SHA256.new(message)
    pss_signature = pss.new(key, salt_bytes=32).sign(msg_hash)
    pss.new(key.public_key(), salt_bytes=32).verify(SHA256.new(message), pss_signature)

    pkcs15_signature = pkcs1_15.new(key).sign(SHA256.new(message))
    pkcs1_15.new(key.public_key()).verify(SHA256.new(message), pkcs15_signature)

    result.outputs.update(
        {
            "oaep_ciphertext": oaep_ciphertext.hex(),
            "pkcs1_v1_5_ciphertext": legacy_ciphertext.hex(),
            "pss_signature": pss_signature.hex(),
            "pkcs1_v1_5_signature": pkcs15_signature.hex(),
        }
    )
    result.pass_checks.extend(
        [
            expect_equal("OAEP round-trip", oaep_plaintext, message),
            expect_equal("PKCS#1 v1.5 round-trip", legacy_plaintext, small_secret),
            condition("PSS verification succeeded", True, "signature verified", "signature did not verify"),
            condition("PKCS#1 v1.5 verification succeeded", True, "signature verified", "signature did not verify"),
        ]
    )

    bad_oaep = bytearray(oaep_ciphertext)
    bad_oaep[5] ^= 1
    bad_legacy = bytearray(legacy_ciphertext)
    bad_legacy[7] ^= 1
    bad_pss = bytearray(pss_signature)
    bad_pss[-1] ^= 1
    bad_pkcs15 = bytearray(pkcs15_signature)
    bad_pkcs15[0] ^= 1

    result.expected_failures.extend(
        [
            expect_exception(
                "OAEP rejects modified ciphertext",
                lambda: PKCS1_OAEP.new(key, hashAlgo=SHA256, label=b"context").decrypt(bytes(bad_oaep)),
                ValueError,
            ),
            expect_sentinel(
                "PKCS#1 v1.5 decryption returns sentinel on failure",
                PKCS1_v1_5.new(key).decrypt(bytes(bad_legacy), sentinel, expected_pt_len=len(small_secret)),
                sentinel,
            ),
            expect_exception(
                "PSS rejects modified signature",
                lambda: pss.new(key.public_key(), salt_bytes=32).verify(SHA256.new(message), bytes(bad_pss)),
                ValueError,
            ),
            expect_exception(
                "PKCS#1 v1.5 signature verification rejects modification",
                lambda: pkcs1_15.new(key.public_key()).verify(SHA256.new(message), bytes(bad_pkcs15)),
                ValueError,
                TypeError,
            ),
        ]
    )
    result.notes.append("PKCS#1 v1.5 encryption is kept only as a legacy interop example. OAEP is the modern RSA encryption default.")
    return result


def demo_rsa_key_io_and_parameters(ctx: Context) -> DemoResult:
    result = DemoResult(
        name="RSA key import/export and parameter extraction",
        description="PKCS#8-protected private export, DER/PEM/OpenSSH public export, parameter extraction, and key reconstruction.",
        usage_example=textwrap.dedent(
            """\
            key = RSA.generate(2048)
            private_pem = key.export_key(
                format="PEM",
                pkcs=8,
                passphrase=b"secret",
                protection="PBKDF2WithHMAC-SHA512AndAES256-CBC",
            )
            reloaded = RSA.import_key(private_pem, passphrase=b"secret")
            """
        ),
    )

    key = ctx.rsa_key
    private_pem = key.export_key(
        format="PEM",
        pkcs=8,
        passphrase=ctx.passphrase,
        protection="PBKDF2WithHMAC-SHA512AndAES256-CBC",
        prot_params={"iteration_count": 21_000},
    )
    private_der = key.export_key(
        format="DER",
        pkcs=8,
        passphrase=ctx.passphrase,
        protection="PBKDF2WithHMAC-SHA512AndAES256-CBC",
        prot_params={"iteration_count": 21_000},
    )
    public_pem = key.public_key().export_key(format="PEM")
    public_der = key.public_key().export_key(format="DER")
    public_openssh = key.public_key().export_key(format="OpenSSH")

    loaded_private = RSA.import_key(private_pem, passphrase=ctx.passphrase)
    loaded_private_der = RSA.import_key(private_der, passphrase=ctx.passphrase)
    loaded_public = RSA.import_key(public_pem)
    loaded_public_der = RSA.import_key(public_der)
    loaded_openssh = RSA.import_key(public_openssh)

    reconstructed_public = RSA.construct((key.n, key.e))
    reconstructed_private = RSA.construct((key.n, key.e, key.d, key.p, key.q, key.u))

    result.outputs.update(
        {
            "public_openssh_prefix": public_openssh.split()[0],
            "size_in_bits": key.size_in_bits(),
            "n_bits": key.n.bit_length(),
            "e": key.e,
            "u": key.u,
        }
    )
    result.pass_checks.extend(
        [
            expect_equal("PEM private import recovered modulus", loaded_private.n, key.n),
            expect_equal("DER private import recovered modulus", loaded_private_der.n, key.n),
            expect_equal("PEM public import recovered modulus", loaded_public.n, key.n),
            expect_equal("DER public import recovered modulus", loaded_public_der.n, key.n),
            expect_equal("OpenSSH public import recovered modulus", loaded_openssh.n, key.n),
            expect_equal("Public reconstruction preserved modulus", reconstructed_public.n, key.n),
            expect_equal("Private reconstruction preserved d", reconstructed_private.d, key.d),
        ]
    )
    result.expected_failures.append(
        expect_exception(
            "RSA protected private key rejects wrong passphrase",
            lambda: RSA.import_key(private_pem, passphrase=b"wrong-pass"),
            ValueError,
        )
    )
    return result


def demo_ecc_ecdsa_and_io(ctx: Context) -> DemoResult:
    result = DemoResult(
        name="ECC P-256, ECDSA, and key formats",
        description="Randomized ECDSA, deterministic RFC6979 ECDSA, SEC1/raw/OpenSSH import-export, and key reconstruction.",
        usage_example=textwrap.dedent(
            """\
            from Crypto.PublicKey import ECC
            from Crypto.Signature import DSS
            from Crypto.Hash import SHA256

            key = ECC.generate(curve="P-256")
            sig = DSS.new(key, "deterministic-rfc6979").sign(SHA256.new(b"msg"))
            """
        ),
    )

    key = ctx.p256_key
    message = b"ECDSA on P-256"
    randomized_sig = DSS.new(key, "fips-186-3").sign(SHA256.new(message))
    deterministic_sig = DSS.new(key, "deterministic-rfc6979").sign(SHA256.new(message))

    DSS.new(key.public_key(), "fips-186-3").verify(SHA256.new(message), randomized_sig)
    DSS.new(key.public_key(), "deterministic-rfc6979").verify(SHA256.new(message), deterministic_sig)

    public_pem = key.public_key().export_key(format="PEM")
    public_der = key.public_key().export_key(format="DER")
    public_sec1 = key.public_key().export_key(format="SEC1")
    public_sec1_compressed = key.public_key().export_key(format="SEC1", compress=True)
    public_raw = key.public_key().export_key(format="raw")
    public_openssh = key.public_key().export_key(format="OpenSSH")
    private_pem = key.export_key(
        format="PEM",
        use_pkcs8=True,
        passphrase=ctx.passphrase,
        protection="PBKDF2WithHMAC-SHA512AndAES256-CBC",
        prot_params={"iteration_count": 21_000},
    )

    loaded_private = ECC.import_key(private_pem, passphrase=ctx.passphrase)
    loaded_pem = ECC.import_key(public_pem)
    loaded_der = ECC.import_key(public_der)
    loaded_sec1 = ECC.import_key(public_sec1, curve_name="P-256")
    loaded_raw = ECC.import_key(public_raw, curve_name="P-256")
    loaded_openssh = ECC.import_key(public_openssh)
    reconstructed_private = ECC.construct(curve="P-256", d=key.d)
    reconstructed_public = ECC.construct(curve="P-256", point_x=key.pointQ.x, point_y=key.pointQ.y)

    result.outputs.update(
        {
            "public_sec1_length": len(public_sec1),
            "public_sec1_compressed_length": len(public_sec1_compressed),
            "public_raw_length": len(public_raw),
            "public_openssh_prefix": public_openssh.split()[0],
            "curve": key.curve,
            "private_scalar_hex_prefix": hex(int(key.d))[:34],
        }
    )
    result.pass_checks.extend(
        [
            condition("ECDSA randomized signature verified", True, "verified", "did not verify"),
            condition("ECDSA deterministic signature verified", True, "verified", "did not verify"),
            expect_equal("ECC private import recovered scalar", int(loaded_private.d), int(key.d)),
            expect_equal("PEM public import recovered X", int(loaded_pem.pointQ.x), int(key.pointQ.x)),
            expect_equal("DER public import recovered X", int(loaded_der.pointQ.x), int(key.pointQ.x)),
            expect_equal("SEC1 public import recovered X", int(loaded_sec1.pointQ.x), int(key.pointQ.x)),
            expect_equal("raw public import recovered X", int(loaded_raw.pointQ.x), int(key.pointQ.x)),
            expect_equal("OpenSSH public import recovered X", int(loaded_openssh.pointQ.x), int(key.pointQ.x)),
            expect_equal("reconstructed private scalar", int(reconstructed_private.d), int(key.d)),
            expect_equal("reconstructed public X", int(reconstructed_public.pointQ.x), int(key.pointQ.x)),
        ]
    )

    bad_sig = bytearray(deterministic_sig)
    bad_sig[-1] ^= 1
    result.expected_failures.extend(
        [
            expect_exception(
                "ECDSA verify rejects modified signature",
                lambda: DSS.new(key.public_key(), "deterministic-rfc6979").verify(SHA256.new(message), bytes(bad_sig)),
                ValueError,
            ),
            expect_exception(
                "ECC protected private key rejects wrong passphrase",
                lambda: ECC.import_key(private_pem, passphrase=b"wrong-pass"),
                ValueError,
            ),
        ]
    )
    result.notes.append("P-256 is the easiest choice when you need strong NIST/FIPS alignment for ECC signatures and ECDH.")
    return result


def demo_ed25519(ctx: Context) -> DemoResult:
    result = DemoResult(
        name="Ed25519 signatures and key formats",
        description="Ed25519 signing, raw key import/export, and PKCS#8-protected private export.",
        usage_example=textwrap.dedent(
            """\
            from Crypto.PublicKey import ECC
            from Crypto.Signature import eddsa

            key = ECC.generate(curve="Ed25519")
            signature = eddsa.new(key, "rfc8032").sign(b"message")
            """
        ),
    )

    key = ctx.ed25519_key
    message = b"Ed25519 message"
    signature = eddsa.new(key, "rfc8032").sign(message)
    eddsa.new(key.public_key(), "rfc8032").verify(message, signature)

    raw_public = key.public_key().export_key(format="raw")
    raw_private = key.seed
    imported_public = eddsa.import_public_key(raw_public)
    imported_private = eddsa.import_private_key(raw_private)

    private_pem = key.export_key(
        format="PEM",
        use_pkcs8=True,
        passphrase=ctx.passphrase,
        protection="PBKDF2WithHMAC-SHA512AndAES256-CBC",
        prot_params={"iteration_count": 21_000},
    )
    loaded_private = ECC.import_key(private_pem, passphrase=ctx.passphrase)

    result.outputs.update(
        {
            "raw_public_length": len(raw_public),
            "seed_length": len(raw_private),
            "signature_length": len(signature),
        }
    )
    result.pass_checks.extend(
        [
            condition("Ed25519 signature verified", True, "verified", "did not verify"),
            expect_equal("Raw public import preserved curve", imported_public.curve, "Ed25519"),
            expect_equal("Raw private import preserved curve", imported_private.curve, "Ed25519"),
            expect_equal("PEM import recovered the same seed", loaded_private.seed, key.seed),
        ]
    )

    bad_sig = bytearray(signature)
    bad_sig[0] ^= 1
    result.expected_failures.extend(
        [
            expect_exception(
                "Ed25519 verify rejects modified signature",
                lambda: eddsa.new(key.public_key(), "rfc8032").verify(message, bytes(bad_sig)),
                ValueError,
            ),
            expect_exception(
                "Ed25519 protected private key rejects wrong passphrase",
                lambda: ECC.import_key(private_pem, passphrase=b"wrong-pass"),
                ValueError,
            ),
        ]
    )
    result.notes.append("Ed25519 uses a seed-based private key model instead of the scalar d model used by NIST P-curves.")
    return result


def demo_ecdh_p256() -> DemoResult:
    result = DemoResult(
        name="ECDH on P-256 + HKDF + AES-GCM",
        description="Pair-wise key agreement, KDF extraction, and immediate use with AEAD.",
        usage_example=textwrap.dedent(
            """\
            from Crypto.PublicKey import ECC
            from Crypto.Protocol.DH import key_agreement

            alice = ECC.generate(curve="P-256")
            bob = ECC.generate(curve="P-256")
            """
        ),
    )

    alice = ECC.generate(curve="P-256")
    bob = ECC.generate(curve="P-256")
    salt = get_random_bytes(16)
    context = b"P-256 ECDH demo"

    def kdf(shared: bytes) -> bytes:
        return derive_hkdf_key(shared, 32, salt, context)

    alice_key = key_agreement(static_priv=alice, static_pub=bob.public_key(), kdf=kdf)
    bob_key = key_agreement(static_priv=bob, static_pub=alice.public_key(), kdf=kdf)

    cipher = AES.new(alice_key, AES.MODE_GCM)
    ciphertext, tag = cipher.encrypt_and_digest(b"hello over ECDH")
    nonce = cipher.nonce
    recovered = AES.new(bob_key, AES.MODE_GCM, nonce=nonce).decrypt_and_verify(ciphertext, tag)

    wrong_peer = ECC.generate(curve="P-256")
    wrong_key = key_agreement(static_priv=wrong_peer, static_pub=alice.public_key(), kdf=kdf)

    result.outputs.update(
        {
            "session_key": alice_key.hex(),
            "nonce": nonce.hex(),
            "ciphertext": ciphertext.hex(),
            "tag": tag.hex(),
        }
    )
    result.pass_checks.extend(
        [
            expect_equal("Alice and Bob derived the same key", alice_key, bob_key),
            expect_equal("ECDH-derived AES-GCM round-trip", recovered, b"hello over ECDH"),
        ]
    )
    result.expected_failures.extend(
        [
            expect_not_equal(
                "Wrong private key produces a different session key",
                wrong_key,
                alice_key,
                "derived key changed as expected",
            ),
            expect_exception(
                "GCM rejects modified tag after ECDH key agreement",
                lambda: AES.new(bob_key, AES.MODE_GCM, nonce=nonce).decrypt_and_verify(ciphertext, tag[:-1] + bytes([tag[-1] ^ 1])),
                ValueError,
            ),
        ]
    )
    return result


def demo_x25519(ctx: Context) -> DemoResult:
    result = DemoResult(
        name="X25519 / Curve25519 key agreement",
        description="X25519 shared secret derivation, HKDF extraction, and raw key import/export.",
        usage_example=textwrap.dedent(
            """\
            from Crypto.PublicKey import ECC
            from Crypto.Protocol.DH import key_agreement

            alice = ECC.generate(curve="Curve25519")
            bob = ECC.generate(curve="Curve25519")
            """
        ),
    )

    alice = ctx.x25519_key
    bob = ECC.generate(curve="Curve25519")
    salt = get_random_bytes(16)

    def kdf(shared: bytes) -> bytes:
        return derive_hkdf_key(shared, 32, salt, b"X25519 demo")

    alice_key = key_agreement(static_priv=alice, static_pub=bob.public_key(), kdf=kdf)
    bob_key = key_agreement(static_priv=bob, static_pub=alice.public_key(), kdf=kdf)

    raw_public = alice.public_key().export_key(format="raw")
    raw_private = alice.seed
    imported_public = import_x25519_public_key(raw_public)
    imported_private = import_x25519_private_key(raw_private)

    wrong_key = key_agreement(
        static_priv=ECC.generate(curve="Curve25519"),
        static_pub=bob.public_key(),
        kdf=kdf,
    )

    result.outputs.update(
        {
            "session_key": alice_key.hex(),
            "raw_public_length": len(raw_public),
            "seed_length": len(raw_private),
        }
    )
    result.pass_checks.extend(
        [
            expect_equal("Alice and Bob derived the same X25519 key", alice_key, bob_key),
            expect_equal("Imported public key curve", imported_public.curve, "Curve25519"),
            expect_equal("Imported private key curve", imported_private.curve, "Curve25519"),
        ]
    )
    result.expected_failures.append(
        expect_not_equal(
            "Wrong X25519 private key derives a different secret",
            wrong_key,
            alice_key,
            "derived key changed as expected",
        )
    )
    result.notes.append("X25519 is for key agreement only. It is not a signature algorithm.")
    return result


def demo_stream_ciphers() -> DemoResult:
    result = DemoResult(
        name="Stream ciphers and authenticated stream constructions",
        description="ChaCha20-Poly1305, XChaCha20-Poly1305, and Salsa20 with Encrypt-then-MAC.",
        usage_example=textwrap.dedent(
            """\
            from Crypto.Cipher import ChaCha20_Poly1305, Salsa20

            key = get_random_bytes(32)
            cipher = ChaCha20_Poly1305.new(key=key)
            """
        ),
    )

    key = get_random_bytes(32)
    aad = b"stream-header"

    cipher = ChaCha20_Poly1305.new(key=key)
    cipher.update(aad)
    chacha_ct, chacha_tag = cipher.encrypt_and_digest(b"secret stream")
    chacha_nonce = cipher.nonce
    dec = ChaCha20_Poly1305.new(key=key, nonce=chacha_nonce)
    dec.update(aad)
    chacha_pt = dec.decrypt_and_verify(chacha_ct, chacha_tag)

    xnonce = get_random_bytes(24)
    cipher = ChaCha20_Poly1305.new(key=key, nonce=xnonce)
    xct, xtag = cipher.encrypt_and_digest(b"secret stream x")
    xpt = ChaCha20_Poly1305.new(key=key, nonce=xnonce).decrypt_and_verify(xct, xtag)

    salsa = Salsa20.new(key=key)
    salsa_ct = salsa.encrypt(b"legacy stream")
    package = salsa.nonce + salsa_ct
    mac = HMAC.new(key, digestmod=SHA256)
    mac.update(package)
    salsa_tag = mac.digest()

    verifier = HMAC.new(key, digestmod=SHA256)
    verifier.update(package)
    verifier.verify(salsa_tag)
    recovered = Salsa20.new(key=key, nonce=salsa.nonce).decrypt(salsa_ct)

    result.outputs.update(
        {
            "chacha20_poly1305_nonce": chacha_nonce.hex(),
            "xchacha20_poly1305_nonce": xnonce.hex(),
            "salsa20_nonce": salsa.nonce.hex(),
            "salsa20_tag": salsa_tag.hex(),
        }
    )
    result.pass_checks.extend(
        [
            expect_equal("ChaCha20-Poly1305 round-trip", chacha_pt, b"secret stream"),
            expect_equal("XChaCha20-Poly1305 round-trip", xpt, b"secret stream x"),
            expect_equal("Salsa20 + HMAC round-trip", recovered, b"legacy stream"),
        ]
    )

    result.expected_failures.extend(
        [
            expect_exception(
                "ChaCha20-Poly1305 rejects bad tag",
                lambda: (lambda c: (c.update(aad), c.decrypt_and_verify(chacha_ct, chacha_tag[:-1] + bytes([chacha_tag[-1] ^ 1]))))(ChaCha20_Poly1305.new(key=key, nonce=chacha_nonce)),
                ValueError,
            ),
            expect_exception(
                "Salsa20 package HMAC rejects tampering",
                lambda: (lambda v: (v.update(package[:-1] + bytes([package[-1] ^ 1])), v.verify(salsa_tag)))(HMAC.new(key, digestmod=SHA256)),
                ValueError,
            ),
        ]
    )
    result.notes.append("Salsa20 alone is unauthenticated. The example deliberately wraps it in Encrypt-then-MAC.")
    return result


def demo_secret_sharing_and_kdfs() -> DemoResult:
    result = DemoResult(
        name="Secret sharing and KDFs",
        description="Shamir split/combine plus HKDF, PBKDF2, and scrypt helper outputs.",
        usage_example=textwrap.dedent(
            """\
            from Crypto.Protocol.SecretSharing import Shamir

            secret = get_random_bytes(16)
            shares = Shamir.split(2, 5, secret)
            restored = Shamir.combine(shares[:2])
            """
        ),
    )

    secret = get_random_bytes(16)
    shares = Shamir.split(2, 5, secret)
    restored = Shamir.combine(shares[:2])

    bad_shares = list(shares[:2])
    index, share = bad_shares[1]
    bad_shares[1] = (index, bytes([share[0] ^ 1]) + share[1:])
    wrong_restored = Shamir.combine(bad_shares)

    salt = get_random_bytes(16)
    hkdf_key = derive_hkdf_key(secret, 32, salt, b"demo")
    pbkdf2_key = derive_pbkdf2_key(b"passphrase", salt, 32, count=50_000)
    scrypt_key = derive_scrypt_key(b"passphrase", salt, 32)

    result.outputs.update(
        {
            "shares_preview": [(idx, piece.hex()) for idx, piece in shares[:3]],
            "hkdf_key": hkdf_key.hex(),
            "pbkdf2_key": pbkdf2_key.hex(),
            "scrypt_key": scrypt_key.hex(),
        }
    )
    result.pass_checks.extend(
        [
            expect_equal("Shamir combine restored the secret", restored, secret),
            condition("HKDF length is 32 bytes", len(hkdf_key) == 32, "32 bytes", "wrong length"),
            condition("PBKDF2 length is 32 bytes", len(pbkdf2_key) == 32, "32 bytes", "wrong length"),
            condition("scrypt length is 32 bytes", len(scrypt_key) == 32, "32 bytes", "wrong length"),
        ]
    )
    result.expected_failures.append(
        expect_not_equal(
            "Modified Shamir share silently reconstructs the wrong secret",
            wrong_restored,
            secret,
            "reconstructed output changed without authenticity protection",
        )
    )
    result.notes.append("Shamir split/combine gives threshold reconstruction, not authenticity. Authenticate shares if hostile modification is possible.")
    return result


def demo_hpke() -> DemoResult:
    result = DemoResult(
        name="HPKE (base, Auth, and PSK modes)",
        description="RFC 9180-style hybrid public-key encryption using PyCryptodome's HPKE module.",
        usage_example=textwrap.dedent(
            """\
            from Crypto.Protocol import HPKE

            receiver = ECC.generate(curve="P-256")
            encryptor = HPKE.new(receiver_key=receiver.public_key(), aead_id=HPKE.AEAD.AES128_GCM)
            ciphertext = encryptor.seal(b"message")
            decryptor = HPKE.new(receiver_key=receiver, aead_id=HPKE.AEAD.AES128_GCM, enc=encryptor.enc)
            """
        ),
    )

    receiver = ECC.generate(curve="P-256")
    sender = ECC.generate(curve="P-256")
    psk_pair = (b"psk-id", get_random_bytes(32))

    base_sender = HPKE.new(receiver_key=receiver.public_key(), aead_id=HPKE.AEAD.AES128_GCM, info=b"ctx")
    base_ct = base_sender.seal(b"base mode", auth_data=b"aad")
    base_receiver = HPKE.new(receiver_key=receiver, aead_id=HPKE.AEAD.AES128_GCM, enc=base_sender.enc, info=b"ctx")
    base_pt = base_receiver.unseal(base_ct, auth_data=b"aad")

    auth_sender = HPKE.new(
        receiver_key=receiver.public_key(),
        sender_key=sender,
        aead_id=HPKE.AEAD.CHACHA20_POLY1305,
        info=b"ctx",
    )
    auth_ct = auth_sender.seal(b"auth mode")
    auth_receiver = HPKE.new(
        receiver_key=receiver,
        sender_key=sender.public_key(),
        aead_id=HPKE.AEAD.CHACHA20_POLY1305,
        enc=auth_sender.enc,
        info=b"ctx",
    )
    auth_pt = auth_receiver.unseal(auth_ct)

    psk_sender = HPKE.new(
        receiver_key=receiver.public_key(),
        aead_id=HPKE.AEAD.AES256_GCM,
        psk=psk_pair,
        info=b"ctx",
    )
    psk_ct = psk_sender.seal(b"psk mode")
    psk_receiver = HPKE.new(
        receiver_key=receiver,
        aead_id=HPKE.AEAD.AES256_GCM,
        psk=psk_pair,
        enc=psk_sender.enc,
        info=b"ctx",
    )
    psk_pt = psk_receiver.unseal(psk_ct)

    result.outputs.update(
        {
            "base_enc_length": len(base_sender.enc),
            "auth_enc_length": len(auth_sender.enc),
            "psk_enc_length": len(psk_sender.enc),
        }
    )
    result.pass_checks.extend(
        [
            expect_equal("HPKE base mode round-trip", base_pt, b"base mode"),
            expect_equal("HPKE auth mode round-trip", auth_pt, b"auth mode"),
            expect_equal("HPKE PSK mode round-trip", psk_pt, b"psk mode"),
        ]
    )
    result.expected_failures.extend(
        [
            expect_exception(
                "HPKE base mode rejects wrong AAD",
                lambda: HPKE.new(receiver_key=receiver, aead_id=HPKE.AEAD.AES128_GCM, enc=base_sender.enc, info=b"ctx").unseal(base_ct, auth_data=b"wrong"),
                ValueError,
            ),
            expect_exception(
                "HPKE auth mode rejects wrong sender public key",
                lambda: HPKE.new(
                    receiver_key=receiver,
                    sender_key=ECC.generate(curve="P-256").public_key(),
                    aead_id=HPKE.AEAD.CHACHA20_POLY1305,
                    enc=auth_sender.enc,
                    info=b"ctx",
                ).unseal(auth_ct),
                ValueError,
            ),
            expect_exception(
                "HPKE PSK mode rejects wrong PSK",
                lambda: HPKE.new(
                    receiver_key=receiver,
                    aead_id=HPKE.AEAD.AES256_GCM,
                    psk=(psk_pair[0], get_random_bytes(32)),
                    enc=psk_sender.enc,
                    info=b"ctx",
                ).unseal(psk_ct),
                ValueError,
            ),
        ]
    )
    result.notes.append("HPKE is the cleanest high-level way in PyCryptodome to combine asymmetric setup with AEAD-protected payload transport.")
    return result


def demo_hybrid_rsa_aes(ctx: Context) -> DemoResult:
    result = DemoResult(
        name="Hybrid envelope: RSA-OAEP + AES-EAX",
        description="A common real-world composition: RSA protects a random session key and AES-EAX protects the bulk plaintext.",
        usage_example=textwrap.dedent(
            """\
            session_key = get_random_bytes(16)
            wrapped_session_key = PKCS1_OAEP.new(rsa_public).encrypt(session_key)
            cipher = AES.new(session_key, AES.MODE_EAX)
            ciphertext, tag = cipher.encrypt_and_digest(plaintext)
            """
        ),
    )

    plaintext = b"Large payloads should use hybrid encryption"
    session_key = get_random_bytes(16)
    wrapped_session_key = PKCS1_OAEP.new(ctx.rsa_key.public_key(), hashAlgo=SHA256).encrypt(session_key)

    cipher = AES.new(session_key, AES.MODE_EAX)
    ciphertext, tag = cipher.encrypt_and_digest(plaintext)
    nonce = cipher.nonce

    recovered_session_key = PKCS1_OAEP.new(ctx.rsa_key, hashAlgo=SHA256).decrypt(wrapped_session_key)
    recovered_plaintext = AES.new(recovered_session_key, AES.MODE_EAX, nonce=nonce).decrypt_and_verify(ciphertext, tag)

    result.outputs.update(
        {
            "wrapped_session_key": wrapped_session_key.hex(),
            "nonce": nonce.hex(),
            "ciphertext": ciphertext.hex(),
            "tag": tag.hex(),
        }
    )
    result.pass_checks.extend(
        [
            expect_equal("Hybrid session key unwrap", recovered_session_key, session_key),
            expect_equal("Hybrid ciphertext round-trip", recovered_plaintext, plaintext),
        ]
    )

    bad_tag = tag[:-1] + bytes([tag[-1] ^ 1])
    result.expected_failures.extend(
        [
            expect_exception(
                "Hybrid AEAD layer rejects tampered tag",
                lambda: AES.new(recovered_session_key, AES.MODE_EAX, nonce=nonce).decrypt_and_verify(ciphertext, bad_tag),
                ValueError,
            ),
            expect_exception(
                "Hybrid unwrap rejects wrong RSA private key",
                lambda: PKCS1_OAEP.new(RSA.generate(2048), hashAlgo=SHA256).decrypt(wrapped_session_key),
                ValueError,
            ),
        ]
    )
    return result


def demo_unexpected_failure_capture() -> DemoResult:
    return DemoResult(
        name="Internal runner health",
        description="A trivial sanity record proving the report generator itself executed.",
        usage_example="outcome = demo_unexpected_failure_capture()",
        outputs={"runner": "alive"},
        pass_checks=[condition("Runner reached the final demo", True, "yes", "no")],
    )


def run_showcase() -> List[DemoResult]:
    ctx = build_context()
    demos = [
        lambda: demo_utilities_and_low_level_helpers(),
        lambda: demo_hashes_and_hmac(),
        lambda: demo_padding_and_cbc(),
        lambda: demo_aes_aead_modes(),
        lambda: demo_ctr_and_counter(),
        lambda: demo_aes_kw_kwp(),
        lambda: demo_rsa_primitives(ctx),
        lambda: demo_rsa_key_io_and_parameters(ctx),
        lambda: demo_ecc_ecdsa_and_io(ctx),
        lambda: demo_ed25519(ctx),
        lambda: demo_ecdh_p256(),
        lambda: demo_x25519(ctx),
        lambda: demo_stream_ciphers(),
        lambda: demo_secret_sharing_and_kdfs(),
        lambda: demo_hpke(),
        lambda: demo_hybrid_rsa_aes(ctx),
        lambda: demo_unexpected_failure_capture(),
    ]

    results: List[DemoResult] = []
    for demo in demos:
        try:
            results.append(demo())
        except Exception:  # noqa: BLE001
            results.append(
                DemoResult(
                    name=getattr(demo, "__name__", demo.__class__.__name__),
                    description="This demo crashed unexpectedly.",
                    usage_example="",
                    unexpected_error=traceback.format_exc(),
                )
            )
    return results


def summarize(results: Iterable[DemoResult]) -> Dict[str, int]:
    totals = {"demos": 0, "all_green": 0, "unexpected_errors": 0, "checks": 0, "checks_passed": 0}
    for result in results:
        totals["demos"] += 1
        checks = result.pass_checks + result.expected_failures
        totals["checks"] += len(checks)
        totals["checks_passed"] += sum(1 for item in checks if item.passed)
        if result.ok:
            totals["all_green"] += 1
        if result.unexpected_error:
            totals["unexpected_errors"] += 1
    return totals


def write_usage_report(results: List[DemoResult], path: Path = REPORT_PATH) -> Path:
    totals = summarize(results)
    lines: List[str] = []
    lines.append("# Usage Report")
    lines.append("")
    lines.append("This report was generated by running `pycryptodome_showcase_runner.py` against the local PyCryptodome installation.")
    lines.append("")
    lines.append("## Summary")
    lines.append("")
    lines.append(f"- Demos executed: **{totals['demos']}**")
    lines.append(f"- Demos fully green: **{totals['all_green']}**")
    lines.append(f"- Total checks: **{totals['checks_passed']} / {totals['checks']}**")
    lines.append(f"- Unexpected runner errors: **{totals['unexpected_errors']}**")
    lines.append("")
    lines.append("## How to use this script")
    lines.append("")
    lines.append("```bash")
    lines.append("python pycryptodome_showcase_runner.py")
    lines.append("```")
    lines.append("")
    lines.append("That command re-runs the demonstrations and rewrites this report in-place.")
    lines.append("")

    for idx, result in enumerate(results, 1):
        lines.append(f"## {idx}. {result.name}")
        lines.append("")
        lines.append(result.description)
        lines.append("")
        lines.append(f"Overall status: **{'PASS' if result.ok else 'FAIL'}**")
        lines.append("")
        if result.usage_example:
            lines.append("### Example usage")
            lines.append("")
            lines.append("```python")
            lines.append(result.usage_example.rstrip())
            lines.append("```")
            lines.append("")
        if result.outputs:
            lines.append("### Observed outputs")
            lines.append("")
            for key, value in result.outputs.items():
                if isinstance(value, (dict, list, tuple)):
                    lines.append(f"- **{key}**:")
                    lines.append("")
                    lines.append("```json")
                    lines.append(json.dumps(value, indent=2, ensure_ascii=False, default=str))
                    lines.append("```")
                else:
                    lines.append(f"- **{key}**: `{_repr_value(value)}`")
            lines.append("")
        if result.pass_checks:
            lines.append("### Success-path checks")
            lines.append("")
            for item in result.pass_checks:
                lines.append(f"- **{item.status}** — {item.label}: {item.detail}")
            lines.append("")
        if result.expected_failures:
            lines.append("### Expected failure-path checks")
            lines.append("")
            for item in result.expected_failures:
                lines.append(f"- **{item.status}** — {item.label}: {item.detail}")
            lines.append("")
        if result.notes:
            lines.append("### Notes")
            lines.append("")
            for note in result.notes:
                lines.append(f"- {note}")
            lines.append("")
        if result.unexpected_error:
            lines.append("### Unexpected error")
            lines.append("")
            lines.append("```text")
            lines.append(result.unexpected_error.rstrip())
            lines.append("```")
            lines.append("")

    path.write_text("\n".join(lines), encoding="utf-8")
    return path


def main() -> int:
    results = run_showcase()
    report_path = write_usage_report(results)
    totals = summarize(results)
    print(f"Wrote report to {report_path}")
    print(json.dumps(totals, indent=2, sort_keys=True))
    return 0


if __name__ == "__main__":
    raise SystemExit(main())