@sd-jwt/core

@sd-jwt/core

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. For SD-JWT-based Verifiable Credentials, use @sd-jwt/sd-jwt-vc, which is built on top of this package.

Installation

# Using npm
npm install @sd-jwt/core

# Using pnpm
pnpm add @sd-jwt/core

# Using yarn
yarn add @sd-jwt/core

Quick Start

import Crypto from 'node:crypto'
import { SDJwtInstance } from '@sd-jwt/core'

// Bring your own crypto – any Signer / Verifier / Hasher that fits the interface
const { privateKey, publicKey } = Crypto.generateKeyPairSync('ed25519')

const sdjwt = new SDJwtInstance({
  signer: async (data) => {
    const sig = Crypto.sign(null, Buffer.from(data), privateKey)
    return Buffer.from(sig).toString('base64url')
  },
  verifier: async (data, sig) => {
    return Crypto.verify(null, Buffer.from(data), publicKey, Buffer.from(sig, 'base64url'))
  },
  signAlg: 'EdDSA',
  hasher: async (data, alg) => {
    return new Uint8Array(Crypto.createHash(alg.replace('-', '')).update(data).digest())
  },
  hashAlg: 'sha-256',
  saltGenerator: async () => Crypto.randomBytes(16).toString('base64url'),
})

// Issue
const credential = await sdjwt.issue(
  { firstname: 'John', lastname: 'Doe', ssn: '123-45-6789' },
  { _sd: ['firstname', 'lastname', 'ssn'] }
)

// Present (disclose only firstname)
const presentation = await sdjwt.present(credential, { firstname: true })

// Verify
const { payload } = await sdjwt.verify(presentation)
console.log(payload) // { firstname: 'John', ... }

Examples

Runnable examples are available in examples/sd-jwt/core. Run them from the repository root:

pnpm tsx examples/sd-jwt/core/basic.ts

See the SD-JWT examples overview for the full list.

Security

• Mandatory Signing of the Issuer-signed JWT
• Manipulation of Disclosures
• Entropy of the salt
• Minimum length of the salt
• Choice of a Hash Algorithm
• Key Binding
• Blinding Claim Names
• Selectively-Disclosable Validity Claims
• Issuer Signature Key Distribution and Rotation
• Forwarding Credentials
• Integrity of Presentation
• Explicit Typing
• Duplicate Digest Rejection (Section 7.1 step 4)
• Unreferenced Disclosure Rejection (Section 7.1 step 5)
• Claim Name Collision Detection (Section 7.1 step 3c.ii.3)

Platform Support

This library is platform agnostic and works in:

• Node.js (>=20)
• Browsers (modern browsers with ES2020 support)
• React Native

A global TextEncoder and TextDecoder must be available. See the React Native notes if you need a polyfill.

Cryptographic operations (signing, verification, hashing, salt generation) are provided as callbacks. @owf/crypto provides Web Crypto based implementations.

Contributing

See the Contributing Guide for details on how to contribute to this project.

License

This project is licensed under the Apache License Version 2.0 (Apache-2.0).