@sd-jwt/core

SD-JWT Implementation in JavaScript (TypeScript)

SD-JWT Core

About

Core library for Selective Disclosure for JWTs (SD-JWT) — RFC 9901.

This package provides types, utilities, encoding/decoding, presentation, and the main SDJwtInstance class — everything needed to issue, present, and verify SD-JWTs.

Check the detail description in our github repo.

Installation

To install this project, run the following command:

# using npm
npm install @sd-jwt/core

# using yarn
yarn add @sd-jwt/core

# using pnpm
pnpm install @sd-jwt/core

Ensure you have Node.js installed as a prerequisite.

Usage

The library can be used to create sd-jwt based credentials. To be compliant with the sd-jwt-vc standard, you can use the @sd-jwt/sd-jwt-vc that is implementing this spec. If you want to use the pure sd-jwt class or implement your own sd-jwt credential approach, you can use this library.

Dependencies

• @owf/identity-common

Verification

The library provides two verification approaches:

Standard Verification (Fail-Fast)

The verify() method throws an error immediately when the first validation failure is encountered:

try {
  const result = await sdjwt.verify(credential);
  console.log('Verified payload:', result.payload);
} catch (error) {
  console.error('Verification failed:', error.message);
}

Safe Verification (Collect All Errors)

The safeVerify() method collects all validation errors instead of failing on the first one. This is useful when you want to show users all issues with a credential at once:

import type { SafeVerifyResult, VerificationError } from '@sd-jwt/core';

const result = await sdjwt.safeVerify(credential);

if (result.success) {
  // Verification succeeded
  console.log('Verified payload:', result.data.payload);
  console.log('Header:', result.data.header);
  if (result.data.kb) {
    console.log('Key binding:', result.data.kb);
  }
} else {
  // Verification failed - inspect all errors
  for (const error of result.errors) {
    console.error(`[${error.code}] ${error.message}`);
    if (error.details) {
      console.error('Details:', error.details);
    }
  }
}

Error Codes

The safeVerify() method returns errors with the following codes:

Code	Description
HASHER_NOT_FOUND	Hasher function not configured
VERIFIER_NOT_FOUND	Verifier function not configured
INVALID_SD_JWT	SD-JWT structure is invalid or cannot be decoded
INVALID_JWT_FORMAT	JWT format is malformed
JWT_NOT_YET_VALID	JWT iat or nbf claim is in the future
JWT_EXPIRED	JWT exp claim is in the past
INVALID_JWT_SIGNATURE	Signature verification failed
MISSING_REQUIRED_CLAIMS	Required claim keys are not present
KEY_BINDING_JWT_MISSING	Key binding JWT required but not present
KEY_BINDING_VERIFIER_NOT_FOUND	Key binding verifier not configured
KEY_BINDING_SIGNATURE_INVALID	Key binding signature verification failed
KEY_BINDING_SD_HASH_INVALID	Key binding sd_hash does not match
UNKNOWN_ERROR	An unexpected error occurred