@pinkparrot/qsafe-sig 0.0.4 → 0.0.6

package/dist/qsafe-sig.browser.min.js

@@ -1778,7 +1778,17 @@ var VARIANT_ID = { "mayo1": 1, "mayo2": 2 };
 var VARIANT_BY_ID = { 1: "mayo1", 2: "mayo2" };
 
 // qsafeHelper.mjs
-var QsafeHelper = class {
+var QsafeHelper = class _QsafeHelper {
+  /** Retrieves the descriptor for a given protocol version and variant, throwing if unknown.
+   * @param {'mayo1' | 'mayo2'} [variant] defaults to DEFAULT_VARIANT
+   * @param {string} [version] defaults to CURRENT_VERSION */
+  static getVariantDescriptor(variant = DEFAULT_VARIANT, version = CURRENT_VERSION) {
+    const vProto = PROTOCOL_VERSIONS[version];
+    if (!vProto) throw new Error(`Unknown protocol version: ${version}`);
+    const desc = vProto.variants[variant];
+    if (!desc) throw new Error(`Unknown variant '${variant}' for protocol version ${version}`);
+    return desc;
+  }
   /** Derives ed25519 + mayo seeds from a master seed via HKDF-SHA256.
    * @param {Uint8Array} masterSeed  @param {number} mayoSeedSize */
   static deriveSeeds(masterSeed, mayoSeedSize) {
@@ -1786,6 +1796,17 @@ var QsafeHelper = class {
     const mayoSeed = hkdf(sha256, masterSeed, void 0, HKDF_INFO_MAYO, mayoSeedSize);
     return { edSeed, mayoSeed };
   }
+  /** Build a QsafeSigner header for the given version and variant: <version(u16 BE) + variantId(u8)>
+   * - Returned as a Uint8Array or write directly at cursor position if a BinaryWriter is provided.
+   * @param {'mayo1' | 'mayo2'} [variant] defaults to DEFAULT_VARIANT
+   * @param {string} [version] defaults to CURRENT_VERSION
+   * @param {BinaryWriter} [writer] - Optional pre-allocated writer */
+  static buildHeader(variant = DEFAULT_VARIANT, version = CURRENT_VERSION, writer) {
+    const w = writer || new BinaryWriter(HEADER_SIZE);
+    w.writeU16BE(Number(version));
+    w.writeByte(VARIANT_ID[variant]);
+    if (!writer) return w.getBytes();
+  }
   /** Resolves version + variantId from a signature header. @param {Uint8Array} sig */
   static parseHeader(sig) {
     if (sig.length < HEADER_SIZE) return null;
@@ -1797,6 +1818,13 @@ var QsafeHelper = class {
     if (!vProto || !variant || !vProto.variants[variant]) return null;
     return { version, variant, desc: vProto.variants[variant] };
   }
+  /** Checks that a signature buffer has a valid header and correct byte length.
+      * - Zero crypto — safe to call as a fast pre-filter. @param {Uint8Array} signature */
+  static checkSignatureFormat(signature) {
+    const h = _QsafeHelper.parseHeader(signature);
+    if (h) return signature.length === HEADER_SIZE + ED25519_SIG_SIZE + h.desc.sigSize;
+    else return false;
+  }
 };
 
 // node_modules/@noble/curves/utils.js
@@ -3001,31 +3029,11 @@ var QsafeSigner = class _QsafeSigner {
     crypto.getRandomValues(seed);
     return seed;
   }
-  /** Checks that a signature buffer has a valid header and correct byte length.
-      * - Zero crypto — safe to call as a fast pre-filter. @param {Uint8Array} signature */
-  static checkFormat(signature) {
-    const h = QsafeHelper.parseHeader(signature);
-    if (h) return signature.length === HEADER_SIZE + ED25519_SIG_SIZE + h.desc.sigSize;
-    else return false;
-  }
-  /** Verifies a hybrid signature. Lazy-loads the required WASM variant if not already cached.
-   * - Works with any protocol version whose descriptors are registered above.
-   * @param {Uint8Array} message
-   * @param {Uint8Array} signature  - from sign()
-   * @param {Uint8Array} publicKey  - from loadMasterKey() */
-  async verify(message, signature, publicKey) {
-    const h = QsafeHelper.parseHeader(signature);
-    if (!h || !_QsafeSigner.checkFormat(signature)) return false;
-    const sigReader = new BinaryReader(signature);
-    sigReader.read(HEADER_SIZE);
-    const edSig = sigReader.read(ED25519_SIG_SIZE);
-    const mayoSig = sigReader.read(h.desc.sigSize);
-    const pubReader = new BinaryReader(publicKey);
-    const edPub = pubReader.read(ED25519_PUB_SIZE);
-    const mayoPub = pubReader.read(h.desc.pubKeySize);
-    if (!ed25519.verify(edSig, message, edPub)) return false;
-    const signer = await this.#ensureShared(h.version, h.variant);
-    return signer.verify(message, mayoSig, mayoPub);
+  /** Parses a signature header and resolves its protocol version and variant.
+   * - Returns null if the header is invalid or references an unknown version/variant.
+   * @param {Uint8Array} headerOrSignature */
+  static parseHeader(headerOrSignature) {
+    return QsafeHelper.parseHeader(headerOrSignature);
   }
   /** Derives and loads a keypair from a master seed (16–32 bytes).
    * - After this call, sign() is ready to use.
@@ -3035,8 +3043,7 @@ var QsafeSigner = class _QsafeSigner {
     const isValidSize = masterSeed instanceof Uint8Array && (masterSeed.length === 16 || masterSeed.length === 24 || masterSeed.length === 32);
     if (!isValidSize) throw new TypeError("masterSeed must be a Uint8Array of 16, 24 or 32 bytes");
     if (!this.#mayoSigner) throw new Error("No signing instance \u2014 use QsafeSigner.create(), not createFull()");
-    const proto = PROTOCOL_VERSIONS[this.#version];
-    const desc = proto.variants[this.#variant];
+    const desc = QsafeHelper.getVariantDescriptor(this.#variant, this.#version);
     const { edSeed, mayoSeed } = QsafeHelper.deriveSeeds(masterSeed, desc.seedSize);
     this.#edPriv = edSeed;
     const mayo = this.#mayoSigner.keypairFromSeed(mayoSeed);
@@ -3057,18 +3064,38 @@ var QsafeSigner = class _QsafeSigner {
     if (!this.#edPriv) throw new Error("No key loaded \u2014 call loadMasterKey() first");
     if (!this.#mayoSigner) throw new Error("No signing instance \u2014 use QsafeSigner.create(), not createFull()");
     if (!this.#mayoSigner.ready) throw new Error("MAYO signer not ready \u2014 was create() called?");
-    const proto = PROTOCOL_VERSIONS[this.#version];
-    const desc = proto.variants[this.#variant];
+    const desc = QsafeHelper.getVariantDescriptor(this.#variant, this.#version);
     const edSig = ed25519.sign(message, this.#edPriv);
     const mayoSig = this.#mayoSigner.sign(message);
     if (!mayoSig) throw new Error("MAYO sign() returned null");
     const writer = new BinaryWriter(HEADER_SIZE + ED25519_SIG_SIZE + desc.sigSize);
-    writer.writeU16BE(Number(this.#version));
-    writer.writeByte(VARIANT_ID[this.#variant]);
+    QsafeHelper.buildHeader(this.#variant, this.#version, writer);
     writer.writeBytes(edSig);
     writer.writeBytes(mayoSig);
     return writer.getBytes();
   }
+  /** Verifies a hybrid signature. Lazy-loads the required WASM variant if not already cached.
+      * - Works with any protocol version whose descriptors are registered above.
+   * - Do not parallelize calls to verify(), async is justified by the lazy WASM loading. To parallelize, please use workers
+      * @param {Uint8Array} message
+      * @param {Uint8Array} signature  - from sign()
+      * @param {Uint8Array} publicKey  - from loadMasterKey() */
+  async verify(message, signature, publicKey) {
+    const h = QsafeHelper.parseHeader(signature);
+    if (!h) return false;
+    if (signature.length !== HEADER_SIZE + ED25519_SIG_SIZE + h.desc.sigSize) return false;
+    if (publicKey.length !== ED25519_PUB_SIZE + h.desc.pubKeySize) return false;
+    const sigReader = new BinaryReader(signature);
+    sigReader.read(HEADER_SIZE);
+    const edSig = sigReader.read(ED25519_SIG_SIZE);
+    const mayoSig = sigReader.read(h.desc.sigSize);
+    const pubReader = new BinaryReader(publicKey);
+    const edPub = pubReader.read(ED25519_PUB_SIZE);
+    const mayoPub = pubReader.read(h.desc.pubKeySize);
+    if (!ed25519.verify(edSig, message, edPub)) return false;
+    const signer = await this.#ensureShared(h.version, h.variant);
+    return signer.verify(message, mayoSig, mayoPub);
+  }
   /** Loads and caches a shared MayoSigner for version+variant. Idempotent.
    * These instances are ONLY used for verify() — keypairFromSeed() is never called on them.
    * @param {string} version  @param {'mayo1' | 'mayo2' | string} variant */
@@ -3084,7 +3111,9 @@ var QsafeSigner = class _QsafeSigner {
 export {
   AVAILABLE_VERSIONS,
   CURRENT_VERSION,
+  HEADER_SIZE,
   PROTOCOL_VERSIONS,
+  QsafeHelper,
   QsafeSigner,
   ed25519
 };

package/index.mjs

@@ -6,7 +6,7 @@ import { PROTOCOL_VERSIONS, CURRENT_VERSION, DEFAULT_VARIANT, AVAILABLE_VERSIONS
 		 ED25519_PRIV_SIZE, ED25519_PUB_SIZE, ED25519_SIG_SIZE,
 		 HEADER_SIZE, VARIANT_ID } from './constants.mjs';
 
-export { ed25519, PROTOCOL_VERSIONS, CURRENT_VERSION, AVAILABLE_VERSIONS };
+export { ed25519, QsafeHelper, HEADER_SIZE, PROTOCOL_VERSIONS, CURRENT_VERSION, AVAILABLE_VERSIONS };
 
 /** 
  * @typedef {{ publicKey: Uint8Array, secretKey: Uint8Array }} Keypair
@@ -67,39 +67,10 @@ export class QsafeSigner {
         return seed;
     }
 
-	/** Checks that a signature buffer has a valid header and correct byte length.
-     * - Zero crypto — safe to call as a fast pre-filter. @param {Uint8Array} signature */
-    static checkFormat(signature) {
-        const h = QsafeHelper.parseHeader(signature);
-        if (h) return signature.length === HEADER_SIZE + ED25519_SIG_SIZE + h.desc.sigSize;
-        else return false;
-    }
-
-    /** Verifies a hybrid signature. Lazy-loads the required WASM variant if not already cached.
-     * - Works with any protocol version whose descriptors are registered above.
-     * @param {Uint8Array} message
-     * @param {Uint8Array} signature  - from sign()
-     * @param {Uint8Array} publicKey  - from loadMasterKey() */
-    async verify(message, signature, publicKey) {
-        const h = QsafeHelper.parseHeader(signature);
-        if (!h || !QsafeSigner.checkFormat(signature)) return false;
-
-        const sigReader = new BinaryReader(signature);
-        sigReader.read(HEADER_SIZE); // skip header already parsed
-        const edSig   = sigReader.read(ED25519_SIG_SIZE);
-        const mayoSig = sigReader.read(h.desc.sigSize);
-
-        const pubReader = new BinaryReader(publicKey);
-        const edPub   = pubReader.read(ED25519_PUB_SIZE);
-        const mayoPub = pubReader.read(h.desc.pubKeySize);
-
-        // Fast path: ed25519 first (pure JS, no WASM)
-        if (!ed25519.verify(edSig, message, edPub)) return false;
-
-        // Lazy-load the shared signer for this version+variant if not already cached
-        const signer = await this.#ensureShared(h.version, h.variant);
-        return signer.verify(message, mayoSig, mayoPub);
-    }
+	/** Parses a signature header and resolves its protocol version and variant.
+	 * - Returns null if the header is invalid or references an unknown version/variant.
+	 * @param {Uint8Array} headerOrSignature */
+	static parseHeader(headerOrSignature) { return QsafeHelper.parseHeader(headerOrSignature); }
 
     /** Derives and loads a keypair from a master seed (16–32 bytes).
      * - After this call, sign() is ready to use.
@@ -110,8 +81,7 @@ export class QsafeSigner {
 		if (!isValidSize) throw new TypeError('masterSeed must be a Uint8Array of 16, 24 or 32 bytes');
 		if (!this.#mayoSigner) throw new Error('No signing instance — use QsafeSigner.create(), not createFull()');
 
-        const proto = PROTOCOL_VERSIONS[this.#version];
-        const desc  = proto.variants[this.#variant];
+		const desc = QsafeHelper.getVariantDescriptor(this.#variant, this.#version);
         const { edSeed, mayoSeed } = QsafeHelper.deriveSeeds(masterSeed, desc.seedSize);
 
         this.#edPriv = edSeed;
@@ -140,22 +110,48 @@ export class QsafeSigner {
         if (!this.#mayoSigner) throw new Error('No signing instance — use QsafeSigner.create(), not createFull()');
         if (!this.#mayoSigner.ready) throw new Error('MAYO signer not ready — was create() called?');
 
-        const proto  = PROTOCOL_VERSIONS[this.#version];
-        const desc   = proto.variants[this.#variant];
+		const desc 	  = QsafeHelper.getVariantDescriptor(this.#variant, this.#version);
         const edSig   = ed25519.sign(message, this.#edPriv);
         const mayoSig = this.#mayoSigner.sign(message);
         if (!mayoSig) throw new Error('MAYO sign() returned null');
 
-        // header: version(u16 BE) + variantId(u8)
         const writer = new BinaryWriter(HEADER_SIZE + ED25519_SIG_SIZE + desc.sigSize);
-        writer.writeU16BE(Number(this.#version));
-        writer.writeByte(VARIANT_ID[this.#variant]);
+		QsafeHelper.buildHeader(this.#variant, this.#version, writer);
         writer.writeBytes(edSig);
         writer.writeBytes(mayoSig);
 
         return writer.getBytes();
     }
 
+	/** Verifies a hybrid signature. Lazy-loads the required WASM variant if not already cached.
+     * - Works with any protocol version whose descriptors are registered above.
+	 * - Do not parallelize calls to verify(), async is justified by the lazy WASM loading. To parallelize, please use workers
+     * @param {Uint8Array} message
+     * @param {Uint8Array} signature  - from sign()
+     * @param {Uint8Array} publicKey  - from loadMasterKey() */
+    async verify(message, signature, publicKey) {
+        const h = QsafeHelper.parseHeader(signature);
+		if (!h) return false; // invalid header or unknown version/variant
+		if (signature.length !== HEADER_SIZE + ED25519_SIG_SIZE + h.desc.sigSize) return false;
+		if (publicKey.length !== ED25519_PUB_SIZE + h.desc.pubKeySize) return false;
+
+        const sigReader = new BinaryReader(signature);
+        sigReader.read(HEADER_SIZE); // skip header already parsed
+        const edSig   = sigReader.read(ED25519_SIG_SIZE);
+        const mayoSig = sigReader.read(h.desc.sigSize);
+
+        const pubReader = new BinaryReader(publicKey);
+        const edPub   = pubReader.read(ED25519_PUB_SIZE);
+        const mayoPub = pubReader.read(h.desc.pubKeySize);
+
+        // Fast path: ed25519 first (pure JS, no WASM)
+        if (!ed25519.verify(edSig, message, edPub)) return false;
+
+        // Lazy-load the shared signer for this version+variant if not already cached
+        const signer = await this.#ensureShared(h.version, h.variant);
+        return signer.verify(message, mayoSig, mayoPub);
+    }
+
     /** Loads and caches a shared MayoSigner for version+variant. Idempotent.
      * These instances are ONLY used for verify() — keypairFromSeed() is never called on them.
      * @param {string} version  @param {'mayo1' | 'mayo2' | string} variant */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pinkparrot/qsafe-sig",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "author": "PinkParrot",
   "license": "GPL-3.0",
   "description": "Combination of pre quantum and post quantum signature, designed for a smooth migration.",

package/qsafeHelper.mjs

@@ -1,11 +1,22 @@
 // @ts-check
 import { hkdf } from '@noble/hashes/hkdf.js';
 import { sha256 } from '@noble/hashes/sha2.js';
-import { BinaryReader } from './binary-writer-reader.mjs';
-import { PROTOCOL_VERSIONS, HKDF_INFO_ED25519, HKDF_INFO_MAYO,
-		 ED25519_PRIV_SIZE, HEADER_SIZE, VARIANT_BY_ID } from './constants.mjs';
+import { BinaryReader, BinaryWriter } from './binary-writer-reader.mjs';
+import { PROTOCOL_VERSIONS, HKDF_INFO_ED25519, HKDF_INFO_MAYO, DEFAULT_VARIANT, CURRENT_VERSION,
+		 ED25519_SIG_SIZE, ED25519_PRIV_SIZE, HEADER_SIZE, VARIANT_BY_ID, VARIANT_ID } from './constants.mjs';
 
 export class QsafeHelper {
+	/** Retrieves the descriptor for a given protocol version and variant, throwing if unknown.
+	 * @param {'mayo1' | 'mayo2'} [variant] defaults to DEFAULT_VARIANT
+	 * @param {string} [version] defaults to CURRENT_VERSION */
+	static getVariantDescriptor(variant = DEFAULT_VARIANT, version = CURRENT_VERSION) {
+		const vProto = PROTOCOL_VERSIONS[version];
+		if (!vProto) throw new Error(`Unknown protocol version: ${version}`);
+		const desc = vProto.variants[variant];
+		if (!desc) throw new Error(`Unknown variant '${variant}' for protocol version ${version}`);
+		return desc;
+	}
+
     /** Derives ed25519 + mayo seeds from a master seed via HKDF-SHA256.
      * @param {Uint8Array} masterSeed  @param {number} mayoSeedSize */
     static deriveSeeds(masterSeed, mayoSeedSize) {
@@ -14,6 +25,18 @@ export class QsafeHelper {
         return { edSeed, mayoSeed };
     }
 
+	/** Build a QsafeSigner header for the given version and variant: <version(u16 BE) + variantId(u8)>
+	 * - Returned as a Uint8Array or write directly at cursor position if a BinaryWriter is provided.
+	 * @param {'mayo1' | 'mayo2'} [variant] defaults to DEFAULT_VARIANT
+	 * @param {string} [version] defaults to CURRENT_VERSION
+	 * @param {BinaryWriter} [writer] - Optional pre-allocated writer */
+	static buildHeader(variant = DEFAULT_VARIANT, version = CURRENT_VERSION, writer) {
+		const w = writer || new BinaryWriter(HEADER_SIZE);
+		w.writeU16BE(Number(version));
+        w.writeByte(VARIANT_ID[variant]);
+		if (!writer) return w.getBytes();
+	}
+
     /** Resolves version + variantId from a signature header. @param {Uint8Array} sig */
     static parseHeader(sig) {
         if (sig.length < HEADER_SIZE) return null;
@@ -25,4 +48,12 @@ export class QsafeHelper {
         if (!vProto || !variant || !vProto.variants[variant]) return null;
         return { version, variant, desc: vProto.variants[variant] };
     }
+
+	/** Checks that a signature buffer has a valid header and correct byte length.
+     * - Zero crypto — safe to call as a fast pre-filter. @param {Uint8Array} signature */
+    static checkSignatureFormat(signature) {
+        const h = QsafeHelper.parseHeader(signature);
+        if (h) return signature.length === HEADER_SIZE + ED25519_SIG_SIZE + h.desc.sigSize;
+        else return false;
+    }
 }

package/test.mjs

@@ -1,5 +1,5 @@
 // @ts-check
-import { QsafeSigner } from './index.mjs';
+import { QsafeHelper, QsafeSigner } from './index.mjs';
 import { createRandomMessage, eq } from './test-helpers.mjs';
 
 const NB_OF_TESTS = 100;
@@ -49,7 +49,7 @@ async function testVariant(variant, log = false) {
     console.assert(!await verifier.verify(msg1, sig1, kpB.publicKey), `${variant} wrong pubkey wrongly accepted`);
     if (log) console.log(`✓ ${variant} cross-key rejection OK`);
 
-	// -- Tampered signature → rejected by verify(), not by checkFormat() --
+	// -- Tampered signature → rejected by verify(), not by checkSignatureFormat() --
 	const sigTampered = sig1.slice();
 	const tamperedIdx = 3 + Math.floor(Math.random() * (sig1.length - 3)); // random byte past the 3-byte header
 	sigTampered[tamperedIdx] ^= 0xFF;
@@ -65,10 +65,10 @@ async function testVariant(variant, log = false) {
 
     // -- checkFormat: structural check only (header + length), NOT a crypto check --
     // A bit-flipped sig has the same length and a valid header → format is still "correct"
-    console.assert( QsafeSigner.checkFormat(sig1),                         `${variant} valid sig should pass checkFormat`);
-    console.assert( QsafeSigner.checkFormat(sigTampered),                   `${variant} tampered sig has valid format (use verify() for crypto)`);
-    console.assert(!QsafeSigner.checkFormat(sig1.slice(0, sig1.length - 1)), `${variant} truncated sig should fail checkFormat`);
-    console.assert(!QsafeSigner.checkFormat(new Uint8Array(3)),              `${variant} garbage should fail checkFormat`);
+    console.assert( QsafeHelper.checkSignatureFormat(sig1),                           `${variant} valid sig should pass checkFormat`);
+    console.assert( QsafeHelper.checkSignatureFormat(sigTampered),                    `${variant} tampered sig has valid format (use verify() for crypto)`);
+    console.assert(!QsafeHelper.checkSignatureFormat(sig1.slice(0, sig1.length - 1)), `${variant} truncated sig should fail checkFormat`);
+    console.assert(!QsafeHelper.checkSignatureFormat(new Uint8Array(3)),              `${variant} garbage should fail checkFormat`);
     if (log) console.log(`✓ ${variant} checkFormat OK`);
 }