@pinkparrot/qsafe-mayo-wasm 0.0.13 → 0.0.15

package/NOTICE

@@ -0,0 +1,13 @@
+Copyright 2023-2025 the MAYO team. All rights reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pinkparrot/qsafe-mayo-wasm",
-  "version": "0.0.13",
+  "version": "0.0.15",
   "author": "Pink Parrot",
   "description": "Post-quantum signatures in WebAssembly — MAYO-1 & MAYO-2, browser & Node.js ready",
   "type": "module",

package/readme.md

@@ -2,14 +2,22 @@
 
 > Post-quantum signatures in WebAssembly — MAYO-1 & MAYO-2, browser & Node.js ready
 
-JavaScript/WASM wrapper around [MAYO-C](https://github.com/PQCMayo/MAYO-C), a NIST post-quantum signature scheme finalist. Ships as two self-contained single-file modules with an unified JS API.
+JavaScript/WASM wrapper around [MAYO-C](https://github.com/PQCMayo/MAYO-C), a NIST post-quantum signature scheme. Ships as self-contained single-file modules with a unified JS API.
 
 Special thanks to Ward Beullens and his team — post-quantum crypto is hard enough without having to invent it yourself.
 
+## ⚠️ Security notice
+
+**Do not use MAYO alone in production.**
+
+MAYO-C is a relatively recent scheme and has not yet accumulated the same cryptanalytic scrutiny as classical algorithms. Until post-quantum cryptography matures further, always combine MAYO with a classical signature (e.g. Ed25519) in a hybrid double-signing scheme. This library is designed to be used as one half of such a pair.
+
+This library is provided as-is, without warranty. It wraps MAYO-C via Emscripten and has not undergone independent security audit. Use at your own risk.
+
 ## Links
 
 - **NPM:** [npmjs.com/package/@pinkparrot/qsafe-mayo-wasm](https://www.npmjs.com/package/@pinkparrot/qsafe-mayo-wasm)
-- **BROWSER** [unpkg.com/@pinkparrot/qsafe-mayo-wasm/dist/mayo.browser.min.js](https://unpkg.com/@pinkparrot/qsafe-mayo-wasm/dist/mayo.browser.min.js)
+- **Browser bundle:** [unpkg.com/@pinkparrot/qsafe-mayo-wasm/dist/mayo.browser.min.js](https://unpkg.com/@pinkparrot/qsafe-mayo-wasm/dist/mayo.browser.min.js)
 - **MAYO spec:** [pqmayo.org](https://pqmayo.org)
 - **MAYO-C source:** [github.com/PQCMayo/MAYO-C](https://github.com/PQCMayo/MAYO-C)
 
@@ -25,7 +33,7 @@ import { MayoSigner } from 'qsafe-mayo-wasm';
 const mayo = await MayoSigner.create('mayo1'); // or 'mayo2'
 
 // Generate a deterministic keypair from a 24-byte seed
-// Param2 "storeSecretKey" (default true) -> set to false when you only need to generate keys without doing operations
+// storeSecretKey (default true) — set to false if you only need the keypair bytes
 const { publicKey, secretKey } = mayo.keypairFromSeed(seed);
 
 // Sign
@@ -34,7 +42,7 @@ const signature = mayo.sign(msg);
 // Verify (stateless — no secret key needed)
 const valid = mayo.verify(msg, signature, publicKey);
 
-// *Optional* Use loadSecretKey when you already have a key from a previous session
+// Load an existing secret key from a previous session
 mayo.loadSecretKey(secretKey);
 ```
 
@@ -44,43 +52,51 @@ mayo.loadSecretKey(secretKey);
 Factory method. Loads the WASM module and returns a ready instance.
 - `variant`: `'mayo1'` (default) or `'mayo2'`
 
-### `new MayoSigner(variant?)` + `await signer.init()`
-Alternative if you need manual lifecycle control. Use `signer.ready` to check initialization state.
+### `new MayoSigner(variant?)` + `await signer.init(maxMsgSize?)`
+Alternative if you need manual lifecycle control.
+- `maxMsgSize`: maximum message size in bytes (default: `204800` — 200 KB). Messages exceeding this will throw at sign/verify time.
+- Use `signer.ready` to check initialization state.
 
 ### `keypairFromSeed(seed, storeSecretKey?)` → `Keypair | null`
 Derives a keypair deterministically from a 24-byte `Uint8Array` seed.
-Stores the secret key internally by default (`storeSecretKey = true`).
+- `storeSecretKey` (default `true`): stores the secret key internally for subsequent `sign()` calls.
+- Returns `null` if key generation failed.
 
 ### `loadSecretKey(secretKey)`
-Loads an existing secret key for subsequent `sign()` calls.
+Loads an existing 24-byte secret key for subsequent `sign()` calls.
 
 ### `sign(msg)` → `Uint8Array | null`
-Signs a message using the loaded secret key. Returns `null` on failure.
+Signs a message using the loaded secret key.
+- Returns `null` on failure.
+- **Throws** if no secret key is loaded, or if the message exceeds `maxMsgSize`.
 
 ### `verify(msg, signature, publicKey)` → `boolean`
 Verifies a signature. Stateless — no secret key required.
+- **Throws** if the message exceeds `maxMsgSize`.
 
-## Key sizes
+## Key & signature sizes
 
 | Variant | Secret key | Public key | Signature |
 |---------|-----------|------------|-----------|
 | MAYO-1  | 24 B      | 1420 B     | 454 B     |
 | MAYO-2  | 24 B      | 4912 B     | 186 B     |
 
+MAYO-2 trades a larger public key for a smaller signature — useful when bandwidth matters more than storage.
+
 ## Building from source
 
 Prerequisites:
 - **Node.js** ≥ 22
-- **Emscripten** (emcc) — see [emscripten.org](https://emscripten.org/docs/getting_started/downloads.html)
+- **Emscripten** (`emcc`) — see [emscripten.org](https://emscripten.org/docs/getting_started/downloads.html)
 - **cmake** (tested with 4.x)
 
 For exact Emscripten/cmake version requirements, see the [MAYO-C build notes](https://github.com/PQCMayo/MAYO-C).
-
 ```powershell
 git clone --recurse-submodules https://github.com/Seigneur-Machiavel/qsafe-mayo-wasm
 npm i --include=dev
-.\build_mayo1.ps1   # → dist/mayo1.cjs
-.\build_mayo2.ps1   # → dist/mayo2.cjs
+.\build_mayo1.ps1   # → dist/mayo1.cjs + dist/mayo1.js
+.\build_mayo2.ps1   # → dist/mayo2.cjs + dist/mayo2.js
+npm run build       # → dist/mayo.browser.min.js  (browser bundle)
 ```
 
 WASM is inlined in each `.js` file (`SINGLE_FILE=1`) — no separate `.wasm` asset needed.
@@ -88,4 +104,5 @@ WASM is inlined in each `.js` file (`SINGLE_FILE=1`) — no separate `.wasm` ass
 ## License
 
 Apache-2.0 — see [LICENSE](./LICENSE).  
-MAYO-C is also Apache-2.0 — see [mayo-c/LICENSE](./mayo-c/LICENSE).
+MAYO-C is also Apache-2.0 — see [mayo-c/LICENSE](./mayo-c/LICENSE).
+MAYO-C NOTICE — see [NOTICE-MAYO-C](./NOTICE-MAYO-C)

package/dist/mayo_api.browser.js

@@ -1,135 +0,0 @@
-import Mayo1Module from './mayo1.cjs';
-import Mayo2Module from './mayo2.cjs';
-
-/** @typedef {{ secretKey: Uint8Array, publicKey: Uint8Array }} Keypair */
-
-const SIZES = {
-	mayo1: { secretKeySize: 24, publicKeySize: 1420, signatureSize: 454 },
-	mayo2: { secretKeySize: 24, publicKeySize: 4912, signatureSize: 186 },
-}; // Note: if we want to use MAYO5 we needs at least 40 bytes of seed.
-
-function alloc(m, size) {
-	const ptr = m._malloc(size);
-	if (ptr === 0) throw new Error(`malloc failed (${size} bytes)`);
-	return ptr;
-}
-
-export class MayoSigner {
-	#m = null;
-	#secretKey = null;
-	#secretKeySize; #publicKeySize; #signatureSize;
-
-	/** @param {string} [variant] Default: 'mayo1' */
-	constructor(variant = 'mayo1') {
-		if (variant !== 'mayo1' && variant !== 'mayo2') throw new Error(`Unsupported MAYO variant: ${variant}`);
-		this.variant = variant;
-		({ secretKeySize: this.#secretKeySize,
-		   publicKeySize: this.#publicKeySize,
-		   signatureSize: this.#signatureSize } = SIZES[variant]);
-	}
-
-	/** Factory — preferred way to instantiate.
-	 * @param {string} [variant] Default: 'mayo1' */
-	static async create(variant = 'mayo1') {
-		const instance = new MayoSigner(variant);
-		await instance.init();
-		return instance;
-	}
-
-	/** Loads the WASM module. Must be called before any crypto operation if not using create(). */
-	async init() {
-		if (this.#m) return;
-		if (this.variant === 'mayo1') this.#m = await Mayo1Module();
-		if (this.variant === 'mayo2') this.#m = await Mayo2Module();
-		throw new Error(`Unsupported MAYO variant: ${this.variant}`);
-	}
-
-	/** Indicates whether the WASM module is loaded and ready for crypto operations. */
-	get ready() { return this.#m !== null; }
-
-	#assertReady() {
-		if (!this.#m) throw new Error('MayoSigner not initialized — call await init() first');
-	}
-
-	/** Derives a keypair deterministically from a seed, and loads the secret key.
-	 * @param {Uint8Array} seed - Must be exactly 24 bytes
-	 * @param {boolean} storeSecretKey - Whether to store the secret key internally for subsequent sign() calls. Set to false if you only need to generate keypair.
-	 * @returns {Keypair|null} null if key generation failed */
-	keypairFromSeed(seed, storeSecretKey = true) {
-		this.#assertReady();
-		if (!(seed instanceof Uint8Array) || seed.length !== this.#secretKeySize)
-			throw new TypeError(`seed must be a Uint8Array of ${this.#secretKeySize} bytes`);
-
-		const m = this.#m;
-		const seedPtr      = alloc(m, seed.length);
-		const publicKeyPtr = alloc(m, this.#publicKeySize);
-		const secretKeyPtr = alloc(m, this.#secretKeySize);
-
-		m.HEAPU8.set(seed, seedPtr);
-		const ret = m._keypair_from_seed(seedPtr, publicKeyPtr, secretKeyPtr);
-		const keypair = ret === 0 ? {
-			publicKey: m.HEAPU8.slice(publicKeyPtr, publicKeyPtr + this.#publicKeySize),
-			secretKey: m.HEAPU8.slice(secretKeyPtr, secretKeyPtr + this.#secretKeySize),
-		} : null;
-
-		m._free(seedPtr); m._free(publicKeyPtr); m._free(secretKeyPtr);
-
-		if (keypair && storeSecretKey) this.#secretKey = keypair.secretKey;
-		return keypair;
-	}
-
-	/** Loads a secret key for subsequent sign() calls.
-	 * @param {Uint8Array} secretKey - Must be exactly 24 bytes */
-	loadSecretKey(secretKey) {
-		if (!(secretKey instanceof Uint8Array) || secretKey.length !== this.#secretKeySize)
-			throw new TypeError(`secretKey must be a Uint8Array of ${this.#secretKeySize} bytes`);
-		this.#secretKey = secretKey;
-	}
-
-	/** Signs a message using the loaded secret key.
-	 * @param {Uint8Array} msg @returns {Uint8Array|null} signature, or null if signing failed */
-	sign(msg) {
-		this.#assertReady();
-		if (!this.#secretKey) throw new Error('No secret key loaded — call keypairFromSeed() or loadSecretKey() first');
-		if (!(msg instanceof Uint8Array)) throw new TypeError('msg must be a Uint8Array');
-
-		const m = this.#m;
-		const msgPtr          = alloc(m, msg.length);
-		const secretKeyPtr    = alloc(m, this.#secretKeySize);
-		const signaturePtr    = alloc(m, this.#signatureSize);
-		const signatureLenPtr = alloc(m, 4); // size_t in WASM32
-
-		m.HEAPU8.set(msg, msgPtr);
-		m.HEAPU8.set(this.#secretKey, secretKeyPtr);
-
-		const ret = m._sign(msgPtr, msg.length, secretKeyPtr, signaturePtr, signatureLenPtr);
-		const result = ret === 0 ? m.HEAPU8.slice(signaturePtr, signaturePtr + this.#signatureSize) : null;
-
-		m._free(msgPtr); m._free(secretKeyPtr); m._free(signaturePtr); m._free(signatureLenPtr);
-		return result;
-	}
-
-	/** Verifies a signature against a message and public key.
-	 * @param {Uint8Array} msg @param {Uint8Array} signature @param {Uint8Array} publicKey */
-	verify(msg, signature, publicKey) {
-		this.#assertReady();
-		if (!(msg instanceof Uint8Array)) throw new TypeError('msg must be a Uint8Array');
-		if (!(signature instanceof Uint8Array) || signature.length !== this.#signatureSize)
-			throw new TypeError(`signature must be a Uint8Array of ${this.#signatureSize} bytes`);
-		if (!(publicKey instanceof Uint8Array) || publicKey.length !== this.#publicKeySize)
-			throw new TypeError(`publicKey must be a Uint8Array of ${this.#publicKeySize} bytes`);
-
-		const m = this.#m;
-		const msgPtr       = alloc(m, msg.length);
-		const signaturePtr = alloc(m, this.#signatureSize);
-		const publicKeyPtr = alloc(m, this.#publicKeySize);
-
-		m.HEAPU8.set(msg, msgPtr);
-		m.HEAPU8.set(signature, signaturePtr);
-		m.HEAPU8.set(publicKey, publicKeyPtr);
-
-		const ret = m._verify(msgPtr, msg.length, signaturePtr, publicKeyPtr);
-		m._free(msgPtr); m._free(signaturePtr); m._free(publicKeyPtr);
-		return ret === 0;
-	}
-}