feat: Add Verifier options (#297)

cre8 · web-flow · commit 2a6a3674f947 · 2025-06-30T13:49:41.000+02:00
Signed-off-by: Mirko Mollik &lt;mirko.mollik@eudi.sprind.org&gt;
diff --git a/docs/0.x/keybinding.md b/docs/0.x/keybinding.md
@@ -40,6 +40,9 @@ const presentedSdJwt = await sdjwt.present(
 ## Verify
 
 ```ts
-const verified = await sdjwt.verify(presentedSdJwt, ['id', 'ssn'], true);
+const verified = await sdjwt.verify(presentedSdJwt, {
+  requiredClaimKeys: ['id', 'ssn'],
+  keyBindingNonce: '1234'
+});
 console.log(verified.kb); // key binding header and payload is in kb object
 ```
diff --git a/docs/0.x/sdjwt-instance.md b/docs/0.x/sdjwt-instance.md
@@ -58,7 +58,7 @@ type SDJWTConfig = {
 - issue(payload[, disclosureFrame, options])
 - present(encodedSDJwt[, presentationFrame, options])
 - validate(encodedSDJwt)
-- verify(encodedSDJwt[, requiredClaimKeys, requireKeyBindings])
+- verify(encodedSDJwt[, verifierConfig])
 - config(newConfig)
 - encode(sdJwt)
 - decode(encodedSDJwt)
diff --git a/docs/0.x/verify.md b/docs/0.x/verify.md
@@ -1,8 +1,10 @@
 ```ts
 const verified = await sdjwt.verify(
   encodedSdjwt,
-  requiredClaimKeys,
-  requireKeyBindings,
+  {
+    requiredClaims: ['id', 'ssn'], // required claims to verify
+    keyBindingNonce: 'secure_none'
+  }
 );
 ```
 
diff --git a/examples/sd-jwt-example/all.ts b/examples/sd-jwt-example/all.ts
@@ -103,6 +103,8 @@ import { createSignerVerifier, digest, generateSalt, ES256 } from './utils';
 
   // Verify the presentation using the public key and the required claims
   // return a boolean result
-  const verified = await sdjwt.verify(presentation, requiredClaims);
+  const verified = await sdjwt.verify(presentation, {
+    requiredClaimKeys: requiredClaims,
+  });
   console.log('verified:', verified);
 })();
diff --git a/examples/sd-jwt-example/basic.ts b/examples/sd-jwt-example/basic.ts
@@ -53,6 +53,8 @@ import { createSignerVerifier, digest, ES256, generateSalt } from './utils';
 
   // Verify the presentation using the public key and the required claims
   // return a boolean result
-  const verified = await sdjwt.verify(presentation, requiredClaims);
+  const verified = await sdjwt.verify(presentation, {
+    requiredClaimKeys: requiredClaims,
+  });
   console.log(verified);
 })();
diff --git a/examples/sd-jwt-example/custom.ts b/examples/sd-jwt-example/custom.ts
@@ -80,6 +80,8 @@ import { createSignerVerifier, digest, ES256, generateSalt } from './utils';
 
   // Verify the presentation using the public key and the required claims
   // return a boolean result
-  const verified = await sdjwt.verify(presentation, requiredClaims);
+  const verified = await sdjwt.verify(presentation, {
+    requiredClaimKeys: requiredClaims,
+  });
   console.log('verified:', verified);
 })();
diff --git a/examples/sd-jwt-example/flattenJSON.ts b/examples/sd-jwt-example/flattenJSON.ts
@@ -52,6 +52,9 @@ import { createSignerVerifier, digest, generateSalt, ES256 } from './utils';
   const flattenPresentationJSON = FlattenJSON.fromEncode(presentedSdJwt);
   console.log('flattenJSON(presentation): ', flattenPresentationJSON.toJson());
 
-  const verified = await sdjwt.verify(presentedSdJwt, ['id', 'ssn'], true);
+  const verified = await sdjwt.verify(presentedSdJwt, {
+    requiredClaimKeys: ['firstname', 'id'],
+    keyBindingNonce: '1234',
+  });
   console.log(verified);
 })();
diff --git a/examples/sd-jwt-example/generalJSON.ts b/examples/sd-jwt-example/generalJSON.ts
@@ -74,7 +74,10 @@ import { createSignerVerifier, digest, generateSalt, ES256 } from './utils';
     JSON.stringify(generalPresentationJSON.toJson(), null, 2),
   );
 
-  const verified = await sdjwt.verify(presentedSdJwt, ['id', 'ssn'], true);
+  const verified = await sdjwt.verify(presentedSdJwt, {
+    requiredClaimKeys: ['firstname', 'id'],
+    keyBindingNonce: '1234',
+  });
   console.log(verified);
 
   const generalVerified = await generalJSONSdJwt.verify(generalJSON);
diff --git a/examples/sd-jwt-example/kb.ts b/examples/sd-jwt-example/kb.ts
@@ -23,7 +23,7 @@ import { createSignerVerifier, digest, ES256, generateSalt } from './utils';
     id: '1234',
   };
   const disclosureFrame: DisclosureFrame<typeof claims> = {
-    _sd: ['firstname', 'id'],
+    _sd: ['ssn', 'id'],
   };
 
   const kbPayload = {
@@ -48,6 +48,9 @@ import { createSignerVerifier, digest, ES256, generateSalt } from './utils';
     },
   );
 
-  const verified = await sdjwt.verify(presentedSdJwt, ['id', 'ssn'], true);
+  const verified = await sdjwt.verify(presentedSdJwt, {
+    requiredClaimKeys: ['ssn', 'id'],
+    keyBindingNonce: '1234',
+  });
   console.log(verified);
 })();
diff --git a/examples/sd-jwt-vc-example/all.ts b/examples/sd-jwt-vc-example/all.ts
@@ -111,6 +111,8 @@ import { createSignerVerifier, digest, ES256, generateSalt } from './utils';
 
   // Verify the presentation using the public key and the required claims
   // return a boolean result
-  const verified = await sdjwt.verify(credential, requiredClaims);
+  const verified = await sdjwt.verify(credential, {
+    requiredClaimKeys: requiredClaims,
+  });
   console.log('verified:', verified);
 })();
diff --git a/examples/sd-jwt-vc-example/basic.ts b/examples/sd-jwt-vc-example/basic.ts
@@ -61,6 +61,8 @@ import { createSignerVerifier, digest, ES256, generateSalt } from './utils';
 
   // Verify the presentation using the public key and the required claims
   // return a boolean result
-  const verified = await sdjwt.verify(presentation, requiredClaims);
+  const verified = await sdjwt.verify(presentation, {
+    requiredClaimKeys: requiredClaims,
+  });
   console.log(verified);
 })();
diff --git a/examples/sd-jwt-vc-example/custom.ts b/examples/sd-jwt-vc-example/custom.ts
@@ -88,6 +88,8 @@ import { createSignerVerifier, digest, ES256, generateSalt } from './utils';
 
   // Verify the presentation using the public key and the required claims
   // return a boolean result
-  const verified = await sdjwt.verify(presentation, requiredClaims);
+  const verified = await sdjwt.verify(presentation, {
+    requiredClaimKeys: requiredClaims,
+  });
   console.log('verified:', verified);
 })();
diff --git a/examples/sd-jwt-vc-example/kb.ts b/examples/sd-jwt-vc-example/kb.ts
@@ -56,6 +56,9 @@ import { createSignerVerifier, digest, ES256, generateSalt } from './utils';
     },
   );
 
-  const verified = await sdjwt.verify(presentedSdJwt, ['id', 'ssn'], true);
+  const verified = await sdjwt.verify(presentedSdJwt, {
+    requiredClaimKeys: ['firstname', 'id'],
+    keyBindingNonce: '1234',
+  });
   console.log(verified);
 })();
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
@@ -196,11 +196,7 @@ export class SDJwtInstance<ExtendedPayload extends SdJwtPayload> {
   // This function is for verifying the SD JWT
   // If requiredClaimKeys is provided, it will check if the required claim keys are presentation in the SD JWT
   // If requireKeyBindings is true, it will check if the key binding JWT is presentation and verify it
-  public async verify(
-    encodedSDJwt: string,
-    requiredClaimKeys?: string[],
-    requireKeyBindings?: boolean,
-  ) {
+  public async verify(encodedSDJwt: string, options?: VerifierOptions) {
     if (!this.userConfig.hasher) {
       throw new SDJWTException('Hasher not found');
     }
@@ -212,17 +208,19 @@ export class SDJwtInstance<ExtendedPayload extends SdJwtPayload> {
     }
     const { payload, header } = await this.validate(encodedSDJwt);
 
-    if (requiredClaimKeys) {
+    if (options?.requiredClaimKeys) {
       const keys = await sdjwt.keys(hasher);
-      const missingKeys = requiredClaimKeys.filter((k) => !keys.includes(k));
+      const missingKeys = options.requiredClaimKeys.filter(
+        (k) => !keys.includes(k),
+      );
       if (missingKeys.length > 0) {
         throw new SDJWTException(
           `Missing required claim keys: ${missingKeys.join(', ')}`,
         );
       }
     }
 
-    if (!requireKeyBindings) {
+    if (!options?.keyBindingNonce) {
       return { payload, header };
     }
 
@@ -235,10 +233,12 @@ export class SDJwtInstance<ExtendedPayload extends SdJwtPayload> {
     const kb = await sdjwt.kbJwt.verifyKB({
       verifier: this.userConfig.kbVerifier,
       payload: payload as JwtPayload,
+      nonce: options.keyBindingNonce,
     });
     if (!kb) {
       throw new Error('signature is not valid');
     }
+
     const sdHashfromKb = kb.payload.sd_hash;
     const sdjwtWithoutKb = new SDJwt({
       jwt: sdjwt.jwt,
@@ -521,11 +521,7 @@ export class SDJwtGeneralJSONInstance<ExtendedPayload extends SdJwtPayload> {
   // This function is for verifying the SD JWT
   // If requiredClaimKeys is provided, it will check if the required claim keys are presentation in the SD JWT
   // If requireKeyBindings is true, it will check if the key binding JWT is presentation and verify it
-  public async verify(
-    generalJSON: GeneralJSON,
-    requiredClaimKeys?: string[],
-    requireKeyBindings?: boolean,
-  ) {
+  public async verify(generalJSON: GeneralJSON, options?: VerifierOptions) {
     if (!this.userConfig.hasher) {
       throw new SDJWTException('Hasher not found');
     }
@@ -539,17 +535,19 @@ export class SDJwtGeneralJSONInstance<ExtendedPayload extends SdJwtPayload> {
       throw new SDJWTException('Invalid SD JWT');
     }
 
-    if (requiredClaimKeys) {
+    if (options?.requiredClaimKeys) {
       const keys = await sdjwt.keys(hasher);
-      const missingKeys = requiredClaimKeys.filter((k) => !keys.includes(k));
+      const missingKeys = options?.requiredClaimKeys.filter(
+        (k) => !keys.includes(k),
+      );
       if (missingKeys.length > 0) {
         throw new SDJWTException(
           `Missing required claim keys: ${missingKeys.join(', ')}`,
         );
       }
     }
 
-    if (!requireKeyBindings) {
+    if (!options?.keyBindingNonce) {
       return { payload, headers };
     }
 
@@ -562,6 +560,7 @@ export class SDJwtGeneralJSONInstance<ExtendedPayload extends SdJwtPayload> {
     const kb = await sdjwt.kbJwt.verifyKB({
       verifier: this.userConfig.kbVerifier,
       payload: payload as JwtPayload,
+      nonce: options.keyBindingNonce as string,
     });
     if (!kb) {
       throw new Error('signature is not valid');
diff --git a/packages/core/src/jwt.ts b/packages/core/src/jwt.ts
@@ -25,6 +25,17 @@ export type VerifierOptions = {
    * allowed skew for the current time in seconds. Positive value that will lower the iat and nbf checks, and increase the exp check.
    */
   skewSeconds?: number;
+
+  /**
+   * required claim keys for the payload.
+   * If the payload does not contain these keys, the verification will fail.
+   */
+  requiredClaimKeys?: string[];
+
+  /**
+   * nonce used to verify the key binding jwt to prevent replay attacks.
+   */
+  keyBindingNonce?: string;
 };
 
 // This class is used to create and verify JWT
diff --git a/packages/core/src/kbjwt.ts b/packages/core/src/kbjwt.ts
@@ -14,7 +14,11 @@ export class KBJwt<
 > extends Jwt<Header, Payload> {
   // Checking the validity of the key binding jwt
   // the type unknown is not good, but we don't know at this point how to get the public key of the signer, this is defined in the kbVerifier
-  public async verifyKB(values: { verifier: KbVerifier; payload: JwtPayload }) {
+  public async verifyKB(values: {
+    verifier: KbVerifier;
+    payload: JwtPayload;
+    nonce: string;
+  }) {
     if (!this.header || !this.payload || !this.signature) {
       throw new SDJWTException('Verify Error: Invalid JWT');
     }
@@ -45,6 +49,10 @@ export class KBJwt<
     if (!verified) {
       throw new SDJWTException('Verify Error: Invalid JWT Signature');
     }
+    if (this.payload.nonce !== values.nonce) {
+      throw new SDJWTException('Verify Error: Invalid Nonce');
+    }
+
     return { payload: this.payload, header: this.header };
   }
 
diff --git a/packages/core/src/test/kbjwt.spec.ts b/packages/core/src/test/kbjwt.spec.ts
@@ -117,6 +117,7 @@ describe('KB JWT', () => {
     const verified = await decoded.verifyKB({
       verifier: testVerifier,
       payload,
+      nonce: 'nonce',
     });
     expect(verified).toStrictEqual({
       header: {
@@ -177,7 +178,11 @@ describe('KB JWT', () => {
     const encodedKbJwt = await kbJwt.sign(testSigner);
     const decoded = KBJwt.fromKBEncode(encodedKbJwt);
     try {
-      await decoded.verifyKB({ verifier: testVerifier, payload });
+      await decoded.verifyKB({
+        verifier: testVerifier,
+        payload,
+        nonce: 'nonce',
+      });
     } catch (e: unknown) {
       const error = e as SDJWTException;
       expect(error.message).toBe('Invalid Key Binding Jwt');
@@ -222,7 +227,11 @@ describe('KB JWT', () => {
     const encodedKbJwt = await kbJwt.sign(testSigner);
     const decoded = KBJwt.fromKBEncode(encodedKbJwt);
     try {
-      await decoded.verifyKB({ verifier: testVerifier, payload });
+      await decoded.verifyKB({
+        verifier: testVerifier,
+        payload,
+        nonce: 'nonce',
+      });
     } catch (e: unknown) {
       const error = e as SDJWTException;
       expect(error.message).toBe('Verify Error: Invalid JWT Signature');
@@ -268,7 +277,11 @@ describe('KB JWT', () => {
     const decoded = KBJwt.fromKBEncode(encodedKbJwt);
     decoded.signature = undefined;
     try {
-      await decoded.verifyKB({ verifier: testVerifier, payload });
+      await decoded.verifyKB({
+        verifier: testVerifier,
+        payload,
+        nonce: 'nonce',
+      });
     } catch (e: unknown) {
       const error = e as SDJWTException;
       expect(error.message).toBe('Verify Error: Invalid JWT');
@@ -324,6 +337,7 @@ describe('KB JWT', () => {
     const verified = await decoded.verifyKB({
       verifier: testVerifier,
       payload,
+      nonce: 'nonce',
     });
     expect(verified).toStrictEqual({
       header: {
diff --git a/packages/sd-jwt-vc/src/sd-jwt-vc-instance.ts b/packages/sd-jwt-vc/src/sd-jwt-vc-instance.ts
@@ -108,16 +108,10 @@ export class SDJwtVcInstance extends SDJwtInstance<SdJwtVcPayload> {
    * Verifies the SD-JWT-VC. It will validate the signature, the keybindings when required, the status, and the VCT.
    * @param currentDate current time in seconds
    */
-  async verify(
-    encodedSDJwt: string,
-    //TODO: we need to move these values in options, causing a breaking change
-    requiredClaimKeys?: string[],
-    requireKeyBindings?: boolean,
-    options?: VerifierOptions,
-  ) {
+  async verify(encodedSDJwt: string, options?: VerifierOptions) {
     // Call the parent class's verify method
     const result: VerificationResult = await super
-      .verify(encodedSDJwt, requiredClaimKeys, requireKeyBindings)
+      .verify(encodedSDJwt, options)
       .then((res) => {
         return {
           payload: res.payload as SdJwtVcPayload,
