@pinkparrot/qsafe-sig 0.0.5 → 0.0.7

package/README.md

@@ -31,15 +31,15 @@ const masterSeed = QsafeSigner.generateMasterKey(); // 32-byte Uint8Array
 
 // Create a signer and derive a keypair from the seed
 const signer = await QsafeSigner.create();
-const { publicKey, secretKey } = signer.loadMasterKey(masterSeed);
+const { hybridKey, secretKey } = signer.loadMasterKey(masterSeed);
 
 // Sign
 const message   = new TextEncoder().encode('hello world');
-const signature = signer.sign(message);
+const hybridSig = signer.sign(message);
 
 // Verify (use createFull() for backward-compatible multi-version verification)
 const verifier = await QsafeSigner.createFull();
-const valid    = await verifier.verify(message, signature, publicKey);
+const valid    = await verifier.verify(message, hybridSig, hybridKey);
 console.log(valid); // true
 ```
 
@@ -48,7 +48,12 @@ console.log(valid); // true
 Each `sign()` call produces a single `Uint8Array` containing:
 
 ```
-[ header (3B) | ed25519 signature (64B) | MAYO signature (variant-dependent) ]
+[ ed25519 signature (64B) | MAYO signature (variant-dependent) ]
+```
+
+Each `hybridKey` follow the format:
+```
+[ header (3B) | ed25519 pubKey | MAYO pubKey (variant-dependent) ]
 ```
 
 The header encodes the protocol version and MAYO variant so `verify()` always knows what it's reading — no out-of-band metadata needed.
@@ -78,16 +83,16 @@ Generates a cryptographically random master seed.
 
 - `size`: `16`, `24`, or `32` bytes. Default: `32`
 
-### `QsafeSigner.checkFormat(signature)` → `boolean`
+### `QsafeHelper.checkFormat(hybridKey, hybridSig?)` → `boolean`
 
-Fast structural check: validates the header and byte length. **Does not perform any cryptographic verification** — use as a pre-filter before `verify()`.
+Fast structural check: validates the header and byte length. **Does not perform any cryptographic verification**.
 
-### `signer.loadMasterKey(masterSeed)` → `{ publicKey, secretKey }`
+### `signer.loadMasterKey(masterSeed)` → `{ hybridKey, secretKey }`
 
 Derives and loads a keypair from the master seed. Must be called before `sign()`.
 
 - `masterSeed`: `Uint8Array` of 16, 24, or 32 bytes
-- Returns `{ publicKey: Uint8Array, secretKey: Uint8Array }`
+- Returns `{ hybridKey: Uint8Array, secretKey: Uint8Array }`
 
 The same instance can sign many messages after a single `loadMasterKey()` call.
 
@@ -95,7 +100,7 @@ The same instance can sign many messages after a single `loadMasterKey()` call.
 
 Signs a message. Requires a prior `loadMasterKey()` call.
 
-### `signer.verify(message, signature, publicKey)` → `Promise<boolean>`
+### `signer.verify(message, hybridSig, hybridKey)` → `Promise<boolean>`
 
 Verifies a hybrid signature. Lazy-loads the required WASM variant on first call, then caches it. Works across all registered protocol versions.
 

package/benchmark.mjs

@@ -11,7 +11,7 @@ async function chainVerify(variant) {
     console.log(`\n-- Chain verify x${COUNT}: ${variant} --`);
 
     const signer = await QsafeSigner.create(variant);
-    const { publicKey } = signer.loadMasterKey(SEED);
+    const { hybridKey } = signer.loadMasterKey(SEED);
 
     // -- Sign phase --
     const messages = [];
@@ -30,7 +30,7 @@ async function chainVerify(variant) {
 
     const t0verify = performance.now();
     for (let i = 0; i < COUNT; i++)
-        if (!await verifier.verify(messages[i], sigs[i], publicKey)) failures++;
+        if (!await verifier.verify(messages[i], sigs[i], hybridKey)) failures++;
 	
     const verifyMs = performance.now() - t0verify;
     console.log(`Verify : ${verifyMs.toFixed(2)} ms total | ~${(verifyMs / COUNT).toFixed(3)} ms/op`);

package/binary-writer-reader.mjs

@@ -1,4 +1,4 @@
-// Minimal binary writer/reader for the custom signature format. Not a general-purpose library, just enough for our needs.
+// Minimal binary writer/reader. Not a general-purpose library, just enough for our needs.
 export class BinaryWriter {
     cursor = 0;
     view;

package/constants.mjs

@@ -2,8 +2,7 @@
 import { MayoSigner } from '@pinkparrot/qsafe-mayo-wasm';
 
 /**
- * @typedef {{ sigSize: number, pubKeySize: number, seedSize: number }} VariantDesc
- * @typedef {{ publicKey: Uint8Array, secretKey: Uint8Array }} Keypair */
+ * @typedef {{ sigSize: number, pubKeySize: number, seedSize: number }} VariantDesc */
 
 /** Versioned protocol descriptors and loaders.
  * - Each version entry describes the crypto params for that protocol version.

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,10 +1796,23 @@ var QsafeHelper = class {
     const mayoSeed = hkdf(sha256, masterSeed, void 0, HKDF_INFO_MAYO, mayoSeedSize);
     return { edSeed, mayoSeed };
   }
-  /** Resolves version + variantId from a signature header. @param {Uint8Array} sig */
-  static parseHeader(sig) {
-    if (sig.length < HEADER_SIZE) return null;
-    const reader = new BinaryReader(sig);
+  /** 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 hybridKey header.
+  * - Passing the hybridKey header (3 first bytes) will produce the same result.
+  * @param {Uint8Array} hybridKey */
+  static parseHeader(hybridKey) {
+    if (hybridKey.length < HEADER_SIZE) return null;
+    const reader = new BinaryReader(hybridKey);
     const version = String(reader.readU16BE());
     const variantId = reader.readByte();
     const variant = VARIANT_BY_ID[variantId];
@@ -1797,6 +1820,16 @@ var QsafeHelper = class {
     if (!vProto || !variant || !vProto.variants[variant]) return null;
     return { version, variant, desc: vProto.variants[variant] };
   }
+  /** Quick format check for a hybridKey, without parsing the full signature.
+   * @param {Uint8Array} hybridKey
+   * @param {Uint8Array} [hybridSig] Optional: signature associated to the hybridKey. */
+  static checkFormat(hybridKey, hybridSig) {
+    const h = _QsafeHelper.parseHeader(hybridKey);
+    if (!h) return false;
+    if (hybridKey.length !== HEADER_SIZE + ED25519_PUB_SIZE + h.desc.pubKeySize) return false;
+    if (hybridSig && hybridSig.length !== ED25519_SIG_SIZE + h.desc.sigSize) return false;
+    return true;
+  }
 };
 
 // node_modules/@noble/curves/utils.js
@@ -3001,34 +3034,6 @@ var QsafeSigner = class _QsafeSigner {
     crypto.getRandomValues(seed);
     return seed;
   }
-  /** 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);
-  }
-  /** 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);
-  }
   /** Derives and loads a keypair from a master seed (16–32 bytes).
    * - After this call, sign() is ready to use.
    * - Requires a signer created with create(), not createFull().
@@ -3037,40 +3042,60 @@ 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);
     if (!mayo || !this.#mayoSigner.ready) throw new Error("MAYO keypair generation failed");
-    const pub = new BinaryWriter(ED25519_PUB_SIZE + desc.pubKeySize);
-    pub.writeBytes(ed25519.getPublicKey(edSeed));
-    pub.writeBytes(mayo.publicKey);
-    const sec = new BinaryWriter(1 + ED25519_PRIV_SIZE + desc.seedSize);
-    sec.writeByte(VARIANT_ID[this.#variant]);
-    sec.writeBytes(edSeed);
-    sec.writeBytes(mayo.secretKey);
-    return { publicKey: pub.getBytes(), secretKey: sec.getBytes() };
+    const pubWriter = new BinaryWriter(HEADER_SIZE + ED25519_PUB_SIZE + desc.pubKeySize);
+    QsafeHelper.buildHeader(this.#variant, this.#version, pubWriter);
+    pubWriter.writeBytes(ed25519.getPublicKey(edSeed));
+    pubWriter.writeBytes(mayo.publicKey);
+    const secWriter = new BinaryWriter(1 + ED25519_PRIV_SIZE + desc.seedSize);
+    secWriter.writeByte(VARIANT_ID[this.#variant]);
+    secWriter.writeBytes(edSeed);
+    secWriter.writeBytes(mayo.secretKey);
+    return { hybridKey: pubWriter.getBytes(), secretKey: secWriter.getBytes() };
   }
   /** Signs a message. Requires a prior loadMasterKey() call.
-   * - The same instance can sign many messages without re-loading the key.
-   * @param {Uint8Array} message */
+     * - The same instance can sign many messages without re-loading the key.
+  * - Returned hybrid signature: [ ed25519 signature (64B) | MAYO signature (variant-dependent) ]
+     * @param {Uint8Array} message */
   sign(message) {
     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]);
+    const writer = new BinaryWriter(ED25519_SIG_SIZE + desc.sigSize);
     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} hybridSig  - from sign()
+      * @param {Uint8Array} hybridKey  - from loadMasterKey() */
+  async verify(message, hybridSig, hybridKey) {
+    const h = QsafeHelper.parseHeader(hybridKey);
+    if (!h) return false;
+    if (hybridSig.length !== ED25519_SIG_SIZE + h.desc.sigSize) return false;
+    if (hybridKey.length !== HEADER_SIZE + ED25519_PUB_SIZE + h.desc.pubKeySize) return false;
+    const sigReader = new BinaryReader(hybridSig);
+    const edSig = sigReader.read(ED25519_SIG_SIZE);
+    const mayoSig = sigReader.read(h.desc.sigSize);
+    const pubReader = new BinaryReader(hybridKey);
+    pubReader.read(HEADER_SIZE);
+    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 */
@@ -3086,7 +3111,9 @@ var QsafeSigner = class _QsafeSigner {
 export {
   AVAILABLE_VERSIONS,
   CURRENT_VERSION,
+  HEADER_SIZE,
   PROTOCOL_VERSIONS,
+  QsafeHelper,
   QsafeSigner,
   ed25519
 };

package/index.mjs

@@ -6,10 +6,10 @@ 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
+ * @typedef {{ hybridKey : Uint8Array, secretKey: Uint8Array }} Keypair
  * @typedef {import('@pinkparrot/qsafe-mayo-wasm').MayoSigner} MayoSigner */
 
 export class QsafeSigner {
@@ -67,40 +67,6 @@ export class QsafeSigner {
         return seed;
     }
 
-	/** 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); }
-
-    /** 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);
-    }
-
     /** Derives and loads a keypair from a master seed (16–32 bytes).
      * - After this call, sign() is ready to use.
      * - Requires a signer created with create(), not createFull().
@@ -110,52 +76,78 @@ 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;
         const mayo = this.#mayoSigner.keypairFromSeed(mayoSeed); // stores secretKey in this.#mayoSigner
         if (!mayo || !this.#mayoSigner.ready) throw new Error('MAYO keypair generation failed');
 
-        // publicKey = ed25519_pub(32) + mayo_pub
-        const pub = new BinaryWriter(ED25519_PUB_SIZE + desc.pubKeySize);
-        pub.writeBytes(ed25519.getPublicKey(edSeed));
-        pub.writeBytes(mayo.publicKey);
+        // hybridKey = header + ed25519_pub(32) + mayo_pub
+        const pubWriter = new BinaryWriter(HEADER_SIZE + ED25519_PUB_SIZE + desc.pubKeySize);
+		QsafeHelper.buildHeader(this.#variant, this.#version, pubWriter);
+        pubWriter.writeBytes(ed25519.getPublicKey(edSeed));
+        pubWriter.writeBytes(mayo.publicKey);
 
         // secretKey = variantId(1) + ed25519_priv(32) + mayo_sec(seedSize)
-        const sec = new BinaryWriter(1 + ED25519_PRIV_SIZE + desc.seedSize);
-        sec.writeByte(VARIANT_ID[this.#variant]);
-        sec.writeBytes(edSeed);
-        sec.writeBytes(mayo.secretKey);
+        const secWriter = new BinaryWriter(1 + ED25519_PRIV_SIZE + desc.seedSize);
+        secWriter.writeByte(VARIANT_ID[this.#variant]);
+        secWriter.writeBytes(edSeed);
+        secWriter.writeBytes(mayo.secretKey);
 
-        return { publicKey: pub.getBytes(), secretKey: sec.getBytes() };
+        return { hybridKey: pubWriter.getBytes(), secretKey: secWriter.getBytes() };
     }
 
     /** Signs a message. Requires a prior loadMasterKey() call.
      * - The same instance can sign many messages without re-loading the key.
+	 * - Returned hybrid signature: [ ed25519 signature (64B) | MAYO signature (variant-dependent) ]
      * @param {Uint8Array} message */
     sign(message) {
         if (!this.#edPriv) throw new Error('No key loaded — call loadMasterKey() first');
         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]);
+        const writer = new BinaryWriter(ED25519_SIG_SIZE + desc.sigSize);
         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} hybridSig  - from sign()
+     * @param {Uint8Array} hybridKey  - from loadMasterKey() */
+    async verify(message, hybridSig, hybridKey) {
+        const h = QsafeHelper.parseHeader(hybridKey);
+		if (!h) return false; // invalid header or unknown version/variant
+		if (hybridSig.length !== ED25519_SIG_SIZE + h.desc.sigSize) return false;
+		if (hybridKey.length !== HEADER_SIZE + ED25519_PUB_SIZE + h.desc.pubKeySize) return false;
+
+        const sigReader = new BinaryReader(hybridSig);
+        const edSig   = sigReader.read(ED25519_SIG_SIZE);
+        const mayoSig = sigReader.read(h.desc.sigSize);
+
+        const pubReader = new BinaryReader(hybridKey);
+        pubReader.read(HEADER_SIZE); // skip header already parsed
+        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.5",
+  "version": "0.0.7",
   "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,23 @@
 // @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 { HKDF_INFO_ED25519, HKDF_INFO_MAYO, DEFAULT_VARIANT, CURRENT_VERSION,
+		 ED25519_SIG_SIZE, ED25519_PUB_SIZE, ED25519_PRIV_SIZE,
+		 PROTOCOL_VERSIONS, 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,10 +26,24 @@ export class QsafeHelper {
         return { edSeed, mayoSeed };
     }
 
-    /** Resolves version + variantId from a signature header. @param {Uint8Array} sig */
-    static parseHeader(sig) {
-        if (sig.length < HEADER_SIZE) return null;
-        const reader    = new BinaryReader(sig);
+	/** 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 hybridKey header.
+	 * - Passing the hybridKey header (3 first bytes) will produce the same result.
+	 * @param {Uint8Array} hybridKey */
+    static parseHeader(hybridKey) {
+        if (hybridKey.length < HEADER_SIZE) return null;
+        const reader    = new BinaryReader(hybridKey);
         const version   = String(reader.readU16BE());
         const variantId = reader.readByte();
         const variant   = VARIANT_BY_ID[variantId];
@@ -25,4 +51,15 @@ export class QsafeHelper {
         if (!vProto || !variant || !vProto.variants[variant]) return null;
         return { version, variant, desc: vProto.variants[variant] };
     }
+
+	/** Quick format check for a hybridKey, without parsing the full signature.
+	 * @param {Uint8Array} hybridKey
+	 * @param {Uint8Array} [hybridSig] Optional: signature associated to the hybridKey. */
+	static checkFormat(hybridKey, hybridSig) {
+		const h = QsafeHelper.parseHeader(hybridKey);
+		if (!h) return false; // invalid header or unknown version/variant
+		if (hybridKey.length !== HEADER_SIZE + ED25519_PUB_SIZE + h.desc.pubKeySize) return false;
+		if (hybridSig && hybridSig.length !== ED25519_SIG_SIZE + h.desc.sigSize) return false;
+		return true;
+	}
 }

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;
@@ -19,14 +19,14 @@ async function testVariant(variant, log = false) {
     const kpA1 = signerA1.loadMasterKey(SEED_A);
     const kpA2 = signerA2.loadMasterKey(SEED_A);
 	if (log) console.log(`- keypair generation time ~${((performance.now() - start) / 2).toFixed(2)} ms`);
-    console.assert(eq(kpA1.publicKey, kpA2.publicKey), `${variant} publicKey should be deterministic`);
+    console.assert(eq(kpA1.hybridKey, kpA2.hybridKey), `${variant} hybridKey should be deterministic`);
     console.assert(eq(kpA1.secretKey, kpA2.secretKey), `${variant} secretKey should be deterministic`);
     if (log) console.log(`✓ ${variant} keypair determinism OK`);
 
     // -- Different seeds → different keypairs --
     const signerB = await QsafeSigner.create(variant);
     const kpB = signerB.loadMasterKey(SEED_B);
-    console.assert(!eq(kpA1.publicKey, kpB.publicKey), `${variant} collision: same pubKey from different seeds`);
+    console.assert(!eq(kpA1.hybridKey, kpB.hybridKey), `${variant} collision: same pubKey from different seeds`);
     console.assert(!eq(kpA1.secretKey, kpB.secretKey), `${variant} collision: same secKey from different seeds`);
     if (log) console.log(`✓ ${variant} seed isolation OK`);
 
@@ -38,38 +38,30 @@ async function testVariant(variant, log = false) {
 	
 	start = performance.now();
     const verifier = await QsafeSigner.createFull();
-    console.assert( await verifier.verify(msg1, sig1, kpA1.publicKey),  `${variant} sig1/msg1 rejected`);
-    console.assert( await verifier.verify(msg2, sig2, kpA1.publicKey),  `${variant} sig2/msg2 rejected`);
+    console.assert( await verifier.verify(msg1, sig1, kpA1.hybridKey),  `${variant} sig1/msg1 rejected`);
+    console.assert( await verifier.verify(msg2, sig2, kpA1.hybridKey),  `${variant} sig2/msg2 rejected`);
 
-	console.assert(!await verifier.verify(msg2, sig1, kpA1.publicKey),  `${variant} sig1 wrongly accepts msg2`);
-    console.assert(!await verifier.verify(msg1, sig2, kpA1.publicKey),  `${variant} sig2 wrongly accepts msg1`);
+	console.assert(!await verifier.verify(msg2, sig1, kpA1.hybridKey),  `${variant} sig1 wrongly accepts msg2`);
+    console.assert(!await verifier.verify(msg1, sig2, kpA1.hybridKey),  `${variant} sig2 wrongly accepts msg1`);
     if (log) console.log(`✓ ${variant} verifying OK ~${((performance.now() - start) / 4).toFixed(2)} ms`);
 
     // -- Wrong public key → rejected --
-    console.assert(!await verifier.verify(msg1, sig1, kpB.publicKey), `${variant} wrong pubkey wrongly accepted`);
+    console.assert(!await verifier.verify(msg1, sig1, kpB.hybridKey), `${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() --
 	const sigTampered = sig1.slice();
 	const tamperedIdx = 3 + Math.floor(Math.random() * (sig1.length - 3)); // random byte past the 3-byte header
 	sigTampered[tamperedIdx] ^= 0xFF;
-	console.assert(!await verifier.verify(msg1, sigTampered, kpA1.publicKey), `${variant} tampered sig wrongly accepted (flipped byte at index ${tamperedIdx})`);
+	console.assert(!await verifier.verify(msg1, sigTampered, kpA1.hybridKey), `${variant} tampered sig wrongly accepted (flipped byte at index ${tamperedIdx})`);
 	if (log) console.log(`✓ ${variant} tampered sig rejection OK (flipped byte at index ${tamperedIdx})`);
 
 	// -- Tampered message → rejected --
 	const msgTampered = msg1.slice();
 	const msgTamperedIdx = Math.floor(Math.random() * msg1.length);
 	msgTampered[msgTamperedIdx] ^= 0xFF;
-	console.assert(!await verifier.verify(msgTampered, sig1, kpA1.publicKey), `${variant} tampered msg wrongly accepted (flipped byte at index ${msgTamperedIdx})`);
+	console.assert(!await verifier.verify(msgTampered, sig1, kpA1.hybridKey), `${variant} tampered msg wrongly accepted (flipped byte at index ${msgTamperedIdx})`);
 	if (log) console.log(`✓ ${variant} tampered msg rejection OK (flipped byte at index ${msgTamperedIdx})`);
-
-    // -- 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`);
-    if (log) console.log(`✓ ${variant} checkFormat OK`);
 }
 
 console.log(`-- Testing mayo1 --`);