@sd-jwt/core 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [0.14.0](https://github.com/openwallet-foundation-labs/sd-jwt-js/compare/v0.13.0...v0.14.0) (2025-06-30)
+
+
+### Features
+
+* Add Verifier options ([#297](https://github.com/openwallet-foundation-labs/sd-jwt-js/issues/297)) ([2a6a367](https://github.com/openwallet-foundation-labs/sd-jwt-js/commit/2a6a3674f94742f48feaf660056226b1a54145e7))
+
+
+
+
+
 # [0.13.0](https://github.com/openwallet-foundation-labs/sd-jwt-js/compare/v0.12.0...v0.13.0) (2025-06-25)
 
 **Note:** Version bump only for package @sd-jwt/core

package/dist/index.d.mts

@@ -20,6 +20,15 @@ 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;
 };
 declare class Jwt<Header extends Record<string, unknown> = Record<string, unknown>, Payload extends Record<string, unknown> = Record<string, unknown>> {
     header?: Header;
@@ -55,6 +64,7 @@ declare class KBJwt<Header extends kbHeader = kbHeader, Payload extends kbPayloa
     verifyKB(values: {
         verifier: KbVerifier;
         payload: JwtPayload;
+        nonce: string;
     }): Promise<{
         payload: Payload;
         header: Header;
@@ -204,7 +214,7 @@ declare class SDJwtInstance<ExtendedPayload extends SdJwtPayload> {
     present<T extends Record<string, unknown>>(encodedSDJwt: string, presentationFrame?: PresentationFrame<T>, options?: {
         kb?: KBOptions;
     }): Promise<SDJWTCompact>;
-    verify(encodedSDJwt: string, requiredClaimKeys?: string[], requireKeyBindings?: boolean): Promise<{
+    verify(encodedSDJwt: string, options?: VerifierOptions): Promise<{
         payload: unknown;
         header: Record<string, unknown> | undefined;
         kb?: undefined;
@@ -261,7 +271,7 @@ declare class SDJwtGeneralJSONInstance<ExtendedPayload extends SdJwtPayload> {
     present<T extends Record<string, unknown>>(generalJSON: GeneralJSON, presentationFrame?: PresentationFrame<T>, options?: {
         kb?: KBOptions;
     }): Promise<GeneralJSON>;
-    verify(generalJSON: GeneralJSON, requiredClaimKeys?: string[], requireKeyBindings?: boolean): Promise<{
+    verify(generalJSON: GeneralJSON, options?: VerifierOptions): Promise<{
         payload: unknown;
         headers: any[];
         kb?: undefined;

package/dist/index.d.ts

@@ -20,6 +20,15 @@ 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;
 };
 declare class Jwt<Header extends Record<string, unknown> = Record<string, unknown>, Payload extends Record<string, unknown> = Record<string, unknown>> {
     header?: Header;
@@ -55,6 +64,7 @@ declare class KBJwt<Header extends kbHeader = kbHeader, Payload extends kbPayloa
     verifyKB(values: {
         verifier: KbVerifier;
         payload: JwtPayload;
+        nonce: string;
     }): Promise<{
         payload: Payload;
         header: Header;
@@ -204,7 +214,7 @@ declare class SDJwtInstance<ExtendedPayload extends SdJwtPayload> {
     present<T extends Record<string, unknown>>(encodedSDJwt: string, presentationFrame?: PresentationFrame<T>, options?: {
         kb?: KBOptions;
     }): Promise<SDJWTCompact>;
-    verify(encodedSDJwt: string, requiredClaimKeys?: string[], requireKeyBindings?: boolean): Promise<{
+    verify(encodedSDJwt: string, options?: VerifierOptions): Promise<{
         payload: unknown;
         header: Record<string, unknown> | undefined;
         kb?: undefined;
@@ -261,7 +271,7 @@ declare class SDJwtGeneralJSONInstance<ExtendedPayload extends SdJwtPayload> {
     present<T extends Record<string, unknown>>(generalJSON: GeneralJSON, presentationFrame?: PresentationFrame<T>, options?: {
         kb?: KBOptions;
     }): Promise<GeneralJSON>;
-    verify(generalJSON: GeneralJSON, requiredClaimKeys?: string[], requireKeyBindings?: boolean): Promise<{
+    verify(generalJSON: GeneralJSON, options?: VerifierOptions): Promise<{
         payload: unknown;
         headers: any[];
         kb?: undefined;

package/dist/index.js

@@ -202,6 +202,9 @@ var KBJwt = class _KBJwt extends Jwt {
       if (!verified) {
         throw new import_utils2.SDJWTException("Verify Error: Invalid JWT Signature");
       }
+      if (this.payload.nonce !== values.nonce) {
+        throw new import_utils2.SDJWTException("Verify Error: Invalid Nonce");
+      }
       return { payload: this.payload, header: this.header };
     });
   }
@@ -759,7 +762,7 @@ var _SDJwtInstance = class _SDJwtInstance {
   // 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
-  verify(encodedSDJwt, requiredClaimKeys, requireKeyBindings) {
+  verify(encodedSDJwt, options) {
     return __async(this, null, function* () {
       if (!this.userConfig.hasher) {
         throw new import_utils7.SDJWTException("Hasher not found");
@@ -770,16 +773,18 @@ var _SDJwtInstance = class _SDJwtInstance {
         throw new import_utils7.SDJWTException("Invalid SD JWT");
       }
       const { payload, header } = yield this.validate(encodedSDJwt);
-      if (requiredClaimKeys) {
+      if (options == null ? void 0 : options.requiredClaimKeys) {
         const keys = yield 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 import_utils7.SDJWTException(
             `Missing required claim keys: ${missingKeys.join(", ")}`
           );
         }
       }
-      if (!requireKeyBindings) {
+      if (!(options == null ? void 0 : options.keyBindingNonce)) {
         return { payload, header };
       }
       if (!sdjwt.kbJwt) {
@@ -790,7 +795,8 @@ var _SDJwtInstance = class _SDJwtInstance {
       }
       const kb = yield sdjwt.kbJwt.verifyKB({
         verifier: this.userConfig.kbVerifier,
-        payload
+        payload,
+        nonce: options.keyBindingNonce
       });
       if (!kb) {
         throw new Error("signature is not valid");
@@ -1024,7 +1030,7 @@ var SDJwtGeneralJSONInstance = class {
   // 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
-  verify(generalJSON, requiredClaimKeys, requireKeyBindings) {
+  verify(generalJSON, options) {
     return __async(this, null, function* () {
       if (!this.userConfig.hasher) {
         throw new import_utils7.SDJWTException("Hasher not found");
@@ -1036,16 +1042,18 @@ var SDJwtGeneralJSONInstance = class {
       if (!sdjwt.jwt || !sdjwt.jwt.payload) {
         throw new import_utils7.SDJWTException("Invalid SD JWT");
       }
-      if (requiredClaimKeys) {
+      if (options == null ? void 0 : options.requiredClaimKeys) {
         const keys = yield sdjwt.keys(hasher);
-        const missingKeys = requiredClaimKeys.filter((k) => !keys.includes(k));
+        const missingKeys = options == null ? void 0 : options.requiredClaimKeys.filter(
+          (k) => !keys.includes(k)
+        );
         if (missingKeys.length > 0) {
           throw new import_utils7.SDJWTException(
             `Missing required claim keys: ${missingKeys.join(", ")}`
           );
         }
       }
-      if (!requireKeyBindings) {
+      if (!(options == null ? void 0 : options.keyBindingNonce)) {
         return { payload, headers };
       }
       if (!sdjwt.kbJwt) {
@@ -1056,7 +1064,8 @@ var SDJwtGeneralJSONInstance = class {
       }
       const kb = yield sdjwt.kbJwt.verifyKB({
         verifier: this.userConfig.kbVerifier,
-        payload
+        payload,
+        nonce: options.keyBindingNonce
       });
       if (!kb) {
         throw new Error("signature is not valid");

package/dist/index.mjs

@@ -179,6 +179,9 @@ var KBJwt = class _KBJwt extends Jwt {
       if (!verified) {
         throw new SDJWTException2("Verify Error: Invalid JWT Signature");
       }
+      if (this.payload.nonce !== values.nonce) {
+        throw new SDJWTException2("Verify Error: Invalid Nonce");
+      }
       return { payload: this.payload, header: this.header };
     });
   }
@@ -744,7 +747,7 @@ var _SDJwtInstance = class _SDJwtInstance {
   // 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
-  verify(encodedSDJwt, requiredClaimKeys, requireKeyBindings) {
+  verify(encodedSDJwt, options) {
     return __async(this, null, function* () {
       if (!this.userConfig.hasher) {
         throw new SDJWTException6("Hasher not found");
@@ -755,16 +758,18 @@ var _SDJwtInstance = class _SDJwtInstance {
         throw new SDJWTException6("Invalid SD JWT");
       }
       const { payload, header } = yield this.validate(encodedSDJwt);
-      if (requiredClaimKeys) {
+      if (options == null ? void 0 : options.requiredClaimKeys) {
         const keys = yield 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 SDJWTException6(
             `Missing required claim keys: ${missingKeys.join(", ")}`
           );
         }
       }
-      if (!requireKeyBindings) {
+      if (!(options == null ? void 0 : options.keyBindingNonce)) {
         return { payload, header };
       }
       if (!sdjwt.kbJwt) {
@@ -775,7 +780,8 @@ var _SDJwtInstance = class _SDJwtInstance {
       }
       const kb = yield sdjwt.kbJwt.verifyKB({
         verifier: this.userConfig.kbVerifier,
-        payload
+        payload,
+        nonce: options.keyBindingNonce
       });
       if (!kb) {
         throw new Error("signature is not valid");
@@ -1009,7 +1015,7 @@ var SDJwtGeneralJSONInstance = class {
   // 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
-  verify(generalJSON, requiredClaimKeys, requireKeyBindings) {
+  verify(generalJSON, options) {
     return __async(this, null, function* () {
       if (!this.userConfig.hasher) {
         throw new SDJWTException6("Hasher not found");
@@ -1021,16 +1027,18 @@ var SDJwtGeneralJSONInstance = class {
       if (!sdjwt.jwt || !sdjwt.jwt.payload) {
         throw new SDJWTException6("Invalid SD JWT");
       }
-      if (requiredClaimKeys) {
+      if (options == null ? void 0 : options.requiredClaimKeys) {
         const keys = yield sdjwt.keys(hasher);
-        const missingKeys = requiredClaimKeys.filter((k) => !keys.includes(k));
+        const missingKeys = options == null ? void 0 : options.requiredClaimKeys.filter(
+          (k) => !keys.includes(k)
+        );
         if (missingKeys.length > 0) {
           throw new SDJWTException6(
             `Missing required claim keys: ${missingKeys.join(", ")}`
           );
         }
       }
-      if (!requireKeyBindings) {
+      if (!(options == null ? void 0 : options.keyBindingNonce)) {
         return { payload, headers };
       }
       if (!sdjwt.kbJwt) {
@@ -1041,7 +1049,8 @@ var SDJwtGeneralJSONInstance = class {
       }
       const kb = yield sdjwt.kbJwt.verifyKB({
         verifier: this.userConfig.kbVerifier,
-        payload
+        payload,
+        nonce: options.keyBindingNonce
       });
       if (!kb) {
         throw new Error("signature is not valid");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sd-jwt/core",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "sd-jwt draft 7 implementation in typescript",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -38,13 +38,13 @@
   },
   "license": "Apache-2.0",
   "devDependencies": {
-    "@sd-jwt/crypto-nodejs": "0.13.0"
+    "@sd-jwt/crypto-nodejs": "0.14.0"
   },
   "dependencies": {
-    "@sd-jwt/decode": "0.13.0",
-    "@sd-jwt/present": "0.13.0",
-    "@sd-jwt/types": "0.13.0",
-    "@sd-jwt/utils": "0.13.0"
+    "@sd-jwt/decode": "0.14.0",
+    "@sd-jwt/present": "0.14.0",
+    "@sd-jwt/types": "0.14.0",
+    "@sd-jwt/utils": "0.14.0"
   },
   "publishConfig": {
     "access": "public"
@@ -62,5 +62,5 @@
       "esm"
     ]
   },
-  "gitHead": "0654a46a0bafe529ab5ce98cecbd4cd67f3fc9a3"
+  "gitHead": "121c6d9d3a9df09e9bbaf9a20b7759aa79ec091d"
 }

package/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,9 +208,11 @@ 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(', ')}`,
@@ -222,7 +220,7 @@ export class SDJwtInstance<ExtendedPayload extends SdJwtPayload> {
       }
     }
 
-    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,9 +535,11 @@ 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(', ')}`,
@@ -549,7 +547,7 @@ export class SDJwtGeneralJSONInstance<ExtendedPayload extends SdJwtPayload> {
       }
     }
 
-    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');

package/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

package/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 };
   }
 

package/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: {