@smartledger/keys 3.1.1 → 4.0.0

package/dist/lumen-keys.js

@@ -7848,14 +7848,19 @@ zoo`.split("\n"));
         publicKey
       };
     }
-    async sign(privateKey, message) {
+    async sign(privateKey, message, options = {}) {
+      if (options.context !== void 0 && !(options.context instanceof Uint8Array && options.context.length === 0)) {
+        throw new Error("BsvEcdsaSuite: ECDSA has no context string; bind the context into the message instead");
+      }
       try {
         return sign(message, privateKey, { prehash: false });
       } catch (error) {
         throw new Error(`BsvEcdsaSuite signing failed: ${error instanceof Error ? error.message : String(error)}`);
       }
     }
-    async verify(publicKey, message, signature) {
+    async verify(publicKey, message, signature, options = {}) {
+      if (options.context !== void 0 && !(options.context instanceof Uint8Array && options.context.length === 0))
+        return false;
       try {
         return verify(signature, message, publicKey, { prehash: false }) === true;
       } catch (error) {
@@ -7920,6 +7925,16 @@ zoo`.split("\n"));
     }
     return ml_dsa87_lib;
   }
+  function contextOption(options) {
+    const context = options.context;
+    if (context === void 0)
+      return void 0;
+    if (!(context instanceof Uint8Array))
+      throw new Error("context must be a Uint8Array");
+    if (context.length > 255)
+      throw new Error("context must be at most 255 bytes");
+    return context.length === 0 ? void 0 : { context };
+  }
   var ML_DSA_SIZES = {
     "ml-dsa-44": { publicKey: 1312, privateKey: 2560, signature: 2420 },
     "ml-dsa-65": { publicKey: 1952, privateKey: 4032, signature: 3309 },
@@ -7944,21 +7959,21 @@ zoo`.split("\n"));
         throw new Error(`${this.suiteId} key generation failed: ${error instanceof Error ? error.message : String(error)}`);
       }
     }
-    async sign(privateKey, message) {
+    async sign(privateKey, message, options = {}) {
       try {
         const lib = await this.getLib();
-        return lib.sign(message, privateKey);
+        return lib.sign(message, privateKey, contextOption(options));
       } catch (error) {
         throw new Error(`${this.suiteId} signing failed: ${error instanceof Error ? error.message : String(error)}`);
       }
     }
-    async verify(publicKey, message, signature) {
+    async verify(publicKey, message, signature, options = {}) {
       try {
         const lib = await this.getLib();
         if (publicKey.length !== this.sizes.publicKey || signature.length !== this.sizes.signature) {
           return false;
         }
-        return lib.verify(signature, message, publicKey) === true;
+        return lib.verify(signature, message, publicKey, contextOption(options)) === true;
       } catch (error) {
         return false;
       }
@@ -8429,6 +8444,7 @@ zoo`.split("\n"));
   };
 
   // src/sdk.ts
+  var DEFAULT_SIGNING_CONTEXT = "@smartledger/keys/4";
   var COUNTER_SUFFIX = /^pk-[^:-]+-(\d+)$/;
   var MAX_KEY_ID_ATTEMPTS = 8;
   function assertAgentId(agentId) {
@@ -8453,6 +8469,12 @@ zoo`.split("\n"));
       this.getOrCreateInFlight = /* @__PURE__ */ new Map();
       this.keyRegistry = config.keyRegistry;
       this.suiteRegistry = config.suiteRegistry;
+      const context = config.signingContext ?? DEFAULT_SIGNING_CONTEXT;
+      const bytes = typeof context === "string" ? new TextEncoder().encode(context) : Uint8Array.from(context);
+      if (bytes.length < 1 || bytes.length > 255) {
+        throw new Error("signingContext must be 1 to 255 bytes");
+      }
+      this.signingContext = bytes;
     }
     /**
      * Create a new key for an agent.
@@ -8518,9 +8540,29 @@ Consider using one of these suites or remove the derivationContext option.` : `N
         );
       }
       const suite = this.suiteRegistry.getSuite(result.meta.suiteId);
-      const hashAlg = this.getHashAlgorithm(result.meta.suiteId);
-      const messageHash = await hashBytes(message, hashAlg);
-      return await suite.sign(result.keypair.privateKey, messageHash);
+      const { input, options } = await this.signingInput(result.meta.suiteId, message, "v4");
+      return await suite.sign(result.keypair.privateKey, input, options);
+    }
+    /**
+     * What a key of `suiteId` signs for `message` under a scheme.
+     *
+     * v4: ML-DSA signs the message itself in FIPS 204 pure mode with this SDK's
+     * context string, so a standard verifier needs only the message and the
+     * context, and the signature is not limited by an outside digest. ECDSA
+     * signs SHA-256(message): ECDSA signs a digest by definition and has no
+     * context, so callers who need domain separation for it put the purpose in
+     * the message.
+     *
+     * v3-digest: what 3.x signed — SHA3-256(message) for ML-DSA, empty context.
+     */
+    async signingInput(suiteId, message, scheme) {
+      if (scheme !== "v4" && scheme !== "v3-digest") {
+        throw new Error(`Unknown signature scheme: ${String(scheme)}`);
+      }
+      if (suiteId.startsWith("ml-dsa")) {
+        return scheme === "v4" ? { input: message, options: { context: this.signingContext } } : { input: await hashBytes(message, "sha3-256") };
+      }
+      return { input: await hashBytes(message, "sha256") };
     }
     /**
      * Verify a signature.
@@ -8538,15 +8580,14 @@ Consider using one of these suites or remove the derivationContext option.` : `N
       if (!statusAllows(result.meta, options.keyStatus ?? "any")) {
         return false;
       }
-      return this.verifyAgainst(result.meta, result.publicKey, message, signature);
+      return this.verifyAgainst(result.meta, result.publicKey, message, signature, options.scheme ?? "v4");
     }
     /** The cryptographic check alone. Anything but a strict `true` is a failure. */
-    async verifyAgainst(meta, publicKey, message, signature) {
+    async verifyAgainst(meta, publicKey, message, signature, scheme = "v4") {
       try {
         const suite = this.suiteRegistry.getSuite(meta.suiteId);
-        const hashAlg = this.getHashAlgorithm(meta.suiteId);
-        const messageHash = await hashBytes(message, hashAlg);
-        return await suite.verify(publicKey, messageHash, signature) === true;
+        const { input, options } = await this.signingInput(meta.suiteId, message, scheme);
+        return await suite.verify(publicKey, input, signature, options) === true;
       } catch {
         return false;
       }
@@ -8790,7 +8831,7 @@ Consider using one of these suites or remove the derivationContext option.` : `N
             fail("Signature must be a Uint8Array");
             continue;
           }
-          const valid = await this.verifyAgainst(key.meta, key.publicKey, message, entry.signature);
+          const valid = await this.verifyAgainst(key.meta, key.publicKey, message, entry.signature, options.scheme ?? "v4");
           if (valid) {
             results.push({ suiteId, keyId, valid: true });
           } else {
@@ -8948,15 +8989,6 @@ Consider using one of these suites or remove the derivationContext option.` : `N
         options
       );
     }
-    /**
-     * Helper: Get hash algorithm for a suite.
-     */
-    getHashAlgorithm(suiteId) {
-      if (suiteId.startsWith("ml-dsa")) {
-        return "sha3-256";
-      }
-      return "sha256";
-    }
     /**
      * Helper: register a key under the agent's next free key ID.
      *