quantum-resistant-rustykey 0.8.2 → 0.9.4

package/README.md

@@ -69,6 +69,8 @@ The three parameter sets (512/768/1024) use the same implementation family and d
 
 ### Why we mix C => emscripten with Rust => wasm-bindgen for web-assembly module creation
 
+Current status in this repository: the shipped cryptographic WASM modules are built via Emscripten from vetted C/C++ upstream code, while Rust/TypeScript is primarily used for package-level ergonomics and integration layers.
+
 Increasingly, developers favor Rust => wasm-bindgen over C => emscripten for Rust's superior compile-time memory safety...and leaning on Rust is implied in our brand! RustyKey® current dual approach is a way to balance performance, security-vetted logic, and web compatibility. Some technical factors may make C => emscripten approach acceptable and, in some cases, preferable for post-quantum cryptography:
 
 - upstream Reliability: Many NIST-standardized PQC algorithms (like ML-KEM) have highly optimized, audited, and "constant-time" reference implementations written in C. Using C => Emscripten allows RustyKey® to port these vetted "upstream" sources directly, reducing the risk of introducing new implementation bugs during a full rewrite into Rust.
@@ -77,6 +79,14 @@ Increasingly, developers favor Rust => wasm-bindgen over C => emscripten for Rus
 
 - Toolchain Maturity: Emscripten is a mature leader in the WASM ecosystem (sometimes...bloated!). For projects needing to bridge legacy or specialized C libraries with the web, emscripten provides a stable environment that can, when optimized, outperform wasm-bindgen in raw execution speed for specific linear memory access patterns.
 
+- Verification Portability: security claims often live with the upstream C implementation (proof scripts, constant-time analyses, side-channel patches). Keeping that code path in WASM preserves traceability between "what was reviewed" and "what is shipped."
+
+- Rust Still Adds Value Around the Core: Rust/TypeScript remain excellent for orchestration layers (API ergonomics, input validation, lifecycle safety, integration code). In practice this means "safe glue + vetted primitive core" rather than forcing a full cryptographic rewrite too early.
+
+- Practical Side-Channel Discipline in Rust is non-trivial: Rust memory safety does not automatically guarantee constant-time behavior. Extra care is still required around branching, indexing, optimizer behavior, allocations, and panic paths, especially when targeting wasm32.
+
+- Long-term Strategy: once a Rust implementation reaches parity in test vectors, profiling, and side-channel review, migrating selected modules can reduce FFI complexity. Until then, Emscripten can be the lower-risk route for production-adjacent cryptographic primitives.
+
 
 ### Why we offer WASM implementations of SQISign (NIST on-ramp only) alongside established, standards-track Falcon and Dilithium?
 
@@ -364,12 +374,7 @@ ML-KEM logic comes from **mlkem-native** (C), compiled with **Emscripten** under
 
 This implementation includes patches to withstand side-channel attacks. For more information about the security improvements, see: [RaspberryPi recovers secret keys from NIST winner implementation...within minutes](https://kannwischer.eu/papers/2024_kyberslash_preprint20240628.pdf)
 
-## Contributing
 
-- Please make pull requests tested to work on Bun and previous Node.js versions
-- Follow the existing code style and testing practices
-- Include tests for new features
-- Update documentation as needed
 
 ## License
 
@@ -424,20 +429,9 @@ This project was generously supported by:
   <img src="./logo-buzzybee.ai.png" width="60" alt="BuzzyBee Logo" />
 </div>
 
-## How we work (aka Conduct)
-
-**"You are very welcome to our house: It must appear in other ways than words!" - W. Shakespeare**
 
-- do you think of yourself as total n00b...or seasoned and cynical Cryptologic Scientist. WELCOME one and all!
-- consider helping us build a friendly, safe and welcoming environment for all, regardless of level of experience, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, nationality, or other similar characteristic.
-- please avoid aliases or nicknames that might detract from a friendly, safe and welcoming environment.
-- getting annoyed? First try being kind and courteous: someone may simply have had a bad day.
-- people have differences of opinion, usually every design or implementation choice carries a trade-off and numerous costs. There is seldom a right answer.
-- go light on unstructured critique, encourage others!
-- if you feel you have been or are being harassed or made uncomfortable by a community member, contact BuzzyBee® our friendly multi-LLM on the chat widget on our testbed site
 
 ## Appendix (WIP) testbed 'coming soon' features
-
 Below our some examples of stats and interactivity we plan to add to the testbed depending on user-interest that will help users understand the trade-offs between lattice-based (ML-KEM/DSA) and isogeny-based (SQISign) crypto:
 
 - Memory Peak (Heap Usage): WASM runs in a linear memory space. Tracking performance.memory.usedJSHeapSize (in supported browsers) or monitoring the WASM instance’s memory growth is vital, especially for ML-DSA (Dilithium), which can be memory-intensive.

package/dist/index.d.ts

@@ -0,0 +1,68 @@
+//#region src/types.d.ts
+type MaybePromise<T> = T | Promise<T>;
+interface KeyPair {
+  get(key: "public_key" | "private_key"): MaybePromise<any>;
+}
+interface EncryptResult {
+  get(key: "cyphertext" | "secret"): MaybePromise<any>;
+}
+interface IMlKem {
+  keypair(): KeyPair;
+  encrypt(public_key: any): EncryptResult;
+  decrypt(cyphertext: any, private_key: any): Promise<any>;
+  buffer_to_string(buffer: any): MaybePromise<string>;
+  encryptMessage(message: string, secret: any): Promise<Uint8Array>;
+  decryptMessage(encryptedMessage: Uint8Array, secret: any): Promise<string>;
+  delete(): void;
+}
+interface IFnDsa {
+  keypair(): KeyPair;
+  sign(message: Uint8Array | ArrayBuffer | string, private_key: unknown): Promise<Uint8Array>;
+  verify(signature: Uint8Array | ArrayBuffer | string, message: Uint8Array | ArrayBuffer | string, public_key: unknown): Promise<boolean>;
+  buffer_to_string(value: Uint8Array | ArrayBuffer | string): string;
+}
+//#endregion
+//#region src/fndsa.d.ts
+declare function loadFnDsa512(): Promise<IFnDsa>;
+declare function loadFnDsa1024(): Promise<IFnDsa>;
+//#endregion
+//#region src/mldsa.d.ts
+declare function loadMlDsa3(): Promise<IFnDsa>;
+declare function loadMlDsa5(): Promise<IFnDsa>;
+//#endregion
+//#region src/sqisign.d.ts
+declare function loadSqisignLvl1(): Promise<IFnDsa>;
+declare function loadSqisignLvl3(): Promise<IFnDsa>;
+declare function loadSqisignLvl5(): Promise<IFnDsa>;
+//#endregion
+//#region src/sqisign-kat-lvl1.d.ts
+/**
+ * NIST-style KAT vector for SQIsign level 1 (count = 0) from upstream
+ * `KAT/PQCsignKAT_353_SQIsign_lvl1.rsp` in https://github.com/SQISign/the-sqisign
+ * Used for fast verify-only tests (reference keygen/sign are too slow for CI).
+ */
+declare const SQISIGN_LVL1_KAT0_PK_HEX = "07CCD21425136F6E865E497D2D4D208F0054AD81372066E817480787AAF7B2029550C89E892D618CE3230F23510BFBE68FCCDDAEA51DB1436B462ADFAF008A010B";
+/** `sm` from the KAT file (signature || message). */
+declare const SQISIGN_LVL1_KAT0_SM_HEX = "84228651F271B0F39F2F19F2E8718F31ED3365AC9E5CB303AFE663D0CFC11F0455D891B0CA6C7E653F9BA2667730BB77BEFE1B1A31828404284AF8FD7BAACC010001D974B5CA671FF65708D8B462A5A84A1443EE9B5FED7218767C9D85CEED04DB0A69A2F6EC3BE835B3B2624B9A0DF68837AD00BCACC27D1EC806A44840267471D86EFF3447018ADB0A6551EE8322AB30010202D81C4D8D734FCBFBEADE3D3F8A039FAA2A2C9957E835AD55B22E75BF57BB556AC8";
+/** Detached signature bytes (first `CRYPTO_BYTES` of `sm`). */
+declare const SQISIGN_LVL1_KAT0_SIG_HEX: string;
+/** Message bytes (remainder of `sm` after the signature). */
+declare const SQISIGN_LVL1_KAT0_MSG_HEX: string;
+/** NIST-style KAT vector for SQIsign level 3 (count = 0). */
+declare const SQISIGN_LVL3_KAT0_PK_HEX = "C32377D6F6D70729884A7F6877EF4791E35D21F751A3E96DE23F9A7A3C01BCD8A5F146DC19E4E2AC63007457F97D8A40EE84AEE7564CA9A7FBE6200FD3E5E55901BFC60EB25C50D39F5C91C96510556BAA22028DF76360841721A601D65E8D0F06";
+declare const SQISIGN_LVL3_KAT0_SM_HEX = "0868CFBF275B8E7B19BF597D658D62CC913B9B2933E30A297288FBE687F6F6B8AC8AF7AA007F191386BB1A203CDDBC2BDB42792D05DA69A4507073D12B0BDC47E2B36BC4BA45C68791918281E578F2DC14294504726DCD4CA4C4565FBB89A12800048C7B84746A2CBD8247248E248B70B51AE91994957857692A028D8F5CABABFC91E4BF1C5D350219A0189C57DE4A7710D29E0364C79B2188449EC0397359430D594C7B5980CC67551933A902D3C11F0FBD6DC39711D3E1F501159EE7FB85CE81B4CE24E1016006567DF469315D513E73F69F6301664E6449AF9DCEB4000D15D81C4D8D734FCBFBEADE3D3F8A039FAA2A2C9957E835AD55B22E75BF57BB556AC8";
+declare const SQISIGN_LVL3_KAT0_SIG_HEX: string;
+declare const SQISIGN_LVL3_KAT0_MSG_HEX: string;
+/** NIST-style KAT vector for SQIsign level 5 (count = 0). */
+declare const SQISIGN_LVL5_KAT0_PK_HEX = "86FFA3B0F73D55A64D13C6F89F28D75FD17C5E2368E1D451127C16D1A97CDB440E20333A233AD2F8E4D70187C8AE31602049ADE949A87F95E79DA4C456F5D400B2485A96D04708A2F30046812B8D65A3BFBFDED0DD6563462F9E2BCE760CD753CAE8471BEC7049EF28FFEFE859C15DAC49DB959AEE99842D97A380A70DD7330106";
+declare const SQISIGN_LVL5_KAT0_SM_HEX = "6B8EF5D7689A1EA1CFCE9C6F7495E309E9D1D1B03E61CD97088E679C4901D0B6B6D38217F4AED6C44949B41F9AF80B43E84D0C91BDB1D00E06957BEBF30A58012AD01E52CF7906CE197AD06696F7FCF756908EA980549E7C215D089BDE7117799F628817A1B9C8FB7FEBFF7E9D9B776142460CFAAFC97D48A57E09E0DA378401000229CC8E1B94E1F2F8AFDC42066BEACE076E3E70DD01F90C4D01DAC17BEC58743532848D438A87A574D9DB940C17236AE3566281E27A99EFE5EE26E05B88A1D610A80B3AF38267D845C7FE330F199B43794A9B2E14846924127366B8F6A1F0F24D3C4B54D79DBB61B098BF32D98EA8819F7BE4A5FFBA29E88B1A996C6CDFD32B048BC2ACFFA28870181447FCC8B6F97B63C47CB013C6F3D84CBD07619A5C355B000911D81C4D8D734FCBFBEADE3D3F8A039FAA2A2C9957E835AD55B22E75BF57BB556AC8";
+declare const SQISIGN_LVL5_KAT0_SIG_HEX: string;
+declare const SQISIGN_LVL5_KAT0_MSG_HEX: string;
+//#endregion
+//#region src/index.d.ts
+declare function loadMlKem768(): Promise<IMlKem>;
+declare function loadMlKem512(): Promise<IMlKem>;
+declare function loadMlKem1024(): Promise<IMlKem>;
+//#endregion
+export { SQISIGN_LVL1_KAT0_MSG_HEX, SQISIGN_LVL1_KAT0_PK_HEX, SQISIGN_LVL1_KAT0_SIG_HEX, SQISIGN_LVL1_KAT0_SM_HEX, SQISIGN_LVL3_KAT0_MSG_HEX, SQISIGN_LVL3_KAT0_PK_HEX, SQISIGN_LVL3_KAT0_SIG_HEX, SQISIGN_LVL3_KAT0_SM_HEX, SQISIGN_LVL5_KAT0_MSG_HEX, SQISIGN_LVL5_KAT0_PK_HEX, SQISIGN_LVL5_KAT0_SIG_HEX, SQISIGN_LVL5_KAT0_SM_HEX, loadFnDsa1024, loadFnDsa512, loadMlDsa3, loadMlDsa5, loadMlKem1024, loadMlKem512, loadMlKem768, loadSqisignLvl1, loadSqisignLvl3, loadSqisignLvl5 };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/types.ts","../src/fndsa.ts","../src/mldsa.ts","../src/sqisign.ts","../src/sqisign-kat-lvl1.ts","../src/index.ts"],"mappings":";KAAY,YAAA,MAAkB,CAAA,GAAI,OAAA,CAAQ,CAAA;AAAA,UAEzB,OAAA;EAEhB,GAAA,CAAI,GAAA,iCAAoC,YAAA;AAAA;AAAA,UAGxB,aAAA;EAEhB,GAAA,CAAI,GAAA,4BAA+B,YAAA;AAAA;AAAA,UAGnB,MAAA;EAChB,OAAA,IAAW,OAAA;EACX,OAAA,CAAQ,UAAA,QAAkB,aAAA;EAC1B,OAAA,CAAQ,UAAA,OAAiB,WAAA,QAAmB,OAAA;EAC5C,gBAAA,CAAiB,MAAA,QAAc,YAAA;EAC/B,cAAA,CAAe,OAAA,UAAiB,MAAA,QAAc,OAAA,CAAQ,UAAA;EACtD,cAAA,CAAe,gBAAA,EAAkB,UAAA,EAAY,MAAA,QAAc,OAAA;EAC3D,MAAA;AAAA;AAAA,UASgB,MAAA;EAChB,OAAA,IAAW,OAAA;EACX,IAAA,CACC,OAAA,EAAS,UAAA,GAAa,WAAA,WACtB,WAAA,YACE,OAAA,CAAQ,UAAA;EACX,MAAA,CACC,SAAA,EAAW,UAAA,GAAa,WAAA,WACxB,OAAA,EAAS,UAAA,GAAa,WAAA,WACtB,UAAA,YACE,OAAA;EACH,gBAAA,CAAiB,KAAA,EAAO,UAAA,GAAa,WAAA;AAAA;;;iBCgLhB,YAAA,CAAA,GAAgB,OAAA,CAAQ,MAAA;AAAA,iBAKxB,aAAA,CAAA,GAAiB,OAAA,CAAQ,MAAA;;;iBCDzB,UAAA,CAAA,GAAc,OAAA,CAAQ,MAAA;AAAA,iBAKtB,UAAA,CAAA,GAAc,OAAA,CAAQ,MAAA;;;iBC0BtB,eAAA,CAAA,GAAmB,OAAA,CAAQ,MAAA;AAAA,iBAK3B,eAAA,CAAA,GAAmB,OAAA,CAAQ,MAAA;AAAA,iBAK3B,eAAA,CAAA,GAAmB,OAAA,CAAQ,MAAA;;;;AHpQjD;;;;cIKa,wBAAA;;cAIA,wBAAA;;cAIA,yBAAA;;cAGA,yBAAA;;cAGA,wBAAA;AAAA,cAEA,wBAAA;AAAA,cAEA,yBAAA;AAAA,cACA,yBAAA;;cAGA,wBAAA;AAAA,cAEA,wBAAA;AAAA,cAEA,yBAAA;AAAA,cACA,yBAAA;;;iBCgNS,YAAA,CAAA,GAAgB,OAAA,CAAQ,MAAA;AAAA,iBAIxB,YAAA,CAAA,GAAgB,OAAA,CAAQ,MAAA;AAAA,iBAIxB,aAAA,CAAA,GAAiB,OAAA,CAAQ,MAAA"}