@bcts/crypto 1.0.0-alpha.5

package/LICENSE

@@ -0,0 +1,48 @@
+Copyright © 2023 Blockchain Commons, LLC
+Copyright © 2025 Leonardo Amoroso Custodio
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+    1. Redistributions of source code must retain the above copyright notice,
+    this list of conditions and the following disclaimer.
+
+    2. Redistributions in binary form must reproduce the above copyright notice,
+    this list of conditions and the following disclaimer in the documentation
+    and/or other materials provided with the distribution.
+
+Subject to the terms and conditions of this license, each copyright holder and
+contributor hereby grants to those receiving rights under this license a
+perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+(except for failure to satisfy the conditions of this license) patent license to
+make, have made, use, offer to sell, sell, import, and otherwise transfer this
+software, where such license applies only to those patent claims, already
+acquired or hereafter acquired, licensable by such copyright holder or
+contributor that are necessarily infringed by:
+
+    (a) their Contribution(s) (the licensed copyrights of copyright holders and
+    non-copyrightable additions of contributors, in source or binary form)
+    alone; or
+
+    (b) combination of their Contribution(s) with the work of authorship to
+    which such Contribution(s) was added by such copyright holder or
+    contributor, if, at the time the Contribution is added, such addition causes
+    such combination to be necessarily infringed. The patent license shall not
+    apply to any other combinations which include the Contribution.
+
+Except as expressly stated above, no rights or licenses from any copyright
+holder or contributor is granted under this license, whether expressly, by
+implication, estoppel or otherwise.
+
+DISCLAIMER
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
+TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,65 @@
+# Blockchain Commons Crypto Interfaces for TypeScript
+
+> Disclaimer: This package is under active development and APIs may change.
+
+## Introduction
+
+`@bcts/crypto` exposes a uniform API for the cryptographic primitives used in higher-level [Blockchain Commons](https://blockchaincommons.com) projects such as Gordian Envelope.
+
+## Features
+
+- **Hash Functions**: SHA-256, SHA-512, HMAC, PBKDF2, HKDF, CRC32
+- **Symmetric Encryption**: ChaCha20-Poly1305 AEAD
+- **Public Key Cryptography**:
+  - X25519 (key agreement)
+  - ECDSA (secp256k1 signing/verification)
+  - Schnorr signatures (BIP-340)
+  - Ed25519 (signing/verification)
+- **Key Derivation**: Scrypt, Argon2id
+- **Memory Security**: Best-effort memory zeroing utilities
+
+## Security Considerations
+
+### Memory Zeroing (`memzero`)
+
+⚠️ **IMPORTANT SECURITY LIMITATION**
+
+The `memzero()` function provides **best-effort** memory clearing in JavaScript/TypeScript, but **cannot guarantee** that sensitive data is fully erased from memory.
+
+**Why this limitation exists:**
+
+- JavaScript/TypeScript lacks volatile memory writes (unlike the Rust reference implementation which uses `std::ptr::write_volatile()`)
+- JavaScript engines and JIT compilers may optimize away zeroing operations
+- The garbage collector may have made copies of sensitive data
+- Swapped pages or memory dumps may contain copies
+
+**What `memzero()` does:**
+
+- ✅ Overwrites memory with zeros to reduce exposure time
+- ✅ Makes a verification check to prevent some optimizations
+- ❌ Cannot guarantee complete erasure from physical memory
+
+**Best practices for sensitive operations:**
+
+1. **Use Web Crypto API when possible**: For truly sensitive cryptographic operations, use `crypto.subtle` with non-extractable keys
+2. **Minimize exposure time**: Call `memzero()` immediately after sensitive operations
+3. **Understand the limitations**: This is defense-in-depth, not a security guarantee
+4. **Consider your threat model**: Evaluate if JavaScript is appropriate for your security requirements
+
+**Example:**
+
+```typescript
+import { memzero } from '@bcts/crypto';
+
+const sensitiveKey = new Uint8Array(32);
+// ... use the key ...
+
+// Clear from memory (best effort)
+memzero(sensitiveKey);
+```
+
+For more details, see the [implementation comments](./src/memzero.ts).
+
+## Rust Reference Implementation
+
+This TypeScript implementation is based on [bc-crypto-rust](https://github.com/BlockchainCommons/bc-crypto-rust) **v0.14.0** ([commit](https://github.com/BlockchainCommons/bc-crypto-rust/tree/4f2b791320730578b04943c833c4a9e6c232fc4d)).