shuffrand/SECURITY.md

Cryptographically secure randomness and shuffling — with soul.

<!-- SECURITY.md -->
In the world of software, where everything from user authentication to game mechanics relies on true unpredictability, the integrity of your random numbers is non-negotiable. That’s why `shuffrand` is engineered with an uncompromising focus on cryptographic strength. At its core, we leverage globalThis.crypto.getRandomValues() (or node:crypto.webcrypto in Node.js environments), the gold standard for cryptographically secure pseudo-random number generators (CSPRNGs). This isn’t just about getting different numbers; it’s about ensuring high-entropy output that’s truly unpredictable and robust against statistical attacks. We’ve also meticulously implemented bias mitigation techniques and integrated rigorous runtime validation with ArkType to ensure that every input is safe and every output is as secure as intended.

However, it’s crucial to understand `shuffrand`’s precise scope. While we provide powerful, secure primitives for generating random numbers and shuffling arrays, we don’t venture into higher-level cryptographic operations like hashing, encryption, or digital signatures. For those, you should always rely on dedicated, peer-reviewed cryptographic libraries. A notable example within `shuffrand` is the preventIdentical option in cryptoShuffle: it’s a fantastic feature for enhancing user experience in scenarios with small arrays, ensuring a visibly different shuffle. But, and this is important, it does introduce a slight statistical bias by excluding the original permutation. Therefore, for truly fairness-critical applications, like lotteries or cryptographic key derivation, this option should be avoided.

Should you uncover a potential security vulnerability in `shuffrand`, please know that we take such reports with the utmost seriousness. Your responsible disclosure is invaluable to the integrity and trustworthiness of this library. We kindly ask that you report any findings directly to the author via the email address provided in the package.json file. Please include a detailed description of the vulnerability, steps to reproduce it, the affected versions, and any potential impact you’ve identified. We are committed to promptly investigating and addressing all legitimate security concerns to ensure `shuffrand` remains a dependable utility for the entire developer community.