charsleysa / sd-jwt-js

A JavaScript implementation of the Selective Disclosure JWT (SD-JWT) spec.

SD-JWT Implementation in JavaScript (TypeScript)

This is the reference implmentation of IETF SD-JWT specification written in TypeScript. It aims to provide a production-ready, robust and secure way to handle JWTs with selective disclosure capabilities.

Hopae, a founding member of OpenWallet Foundation, is building wallet module in TypeScript and need this project as a core component.

Currently compliant with:

• draft-ietf-oauth-selective-disclosure-jwt-08
• draft-ietf-oauth-sd-jwt-vc-03

Background

"Selective Disclosure for JWT" offers a cutting-edge approach to handling JSON Web Tokens (JWT) in a way that enhances user privacy and data security. In today's digital landscape, the demand for efficient yet secure data transmission is paramount. This project addresses that need by enabling selective disclosure of JWT claims, ensuring that only necessary information is shared.

Crucially, the solution is designed to be framework-agnostic, making it compatible with a wide array of JavaScript frameworks, including React and React Native. This broad compatibility ensures that the implementation can be seamlessly integrated into various applications, irrespective of the underlying framework.

Another key aspect of this project is its capability to encode JWTs into QR codes. This feature is particularly useful for mobile and decentralized applications where ease of data transmission is essential. However, the complexity of JWTs can lead to large QR codes that are difficult to scan. Addressing this challenge, "Selective Disclosure for JWT" is specifically optimized to reduce the overall size of the JWT, ensuring that the resulting QR codes are practical and easily scannable.

Design Concepts

The design of "Selective Disclosure for JWT" is centered around flexibility, efficiency, and security. Here are the key design concepts:

1. Framework Agnostic: The implementation is designed to be universally compatible with various JavaScript frameworks. It can be easily plugged into applications built with React, React Native, and other frameworks without necessitating significant alterations in the existing codebase.
2. Data Minimization and Efficiency: One of the core objectives is to minimize the payload size of JWTs. This is crucial for QR code generation, ensuring that the encoded data is concise enough to be efficiently transformed into a QR code, which remains easily scannable.
3. Modular Design: The architecture is modular, allowing developers to integrate selective disclosure capabilities as needed. This modular approach also facilitates easy updates and maintenance.
4. Security-First: Security is a paramount concern, especially when handling JWTs. The implementation follows best practices in security and data integrity, ensuring that the selective disclosure process does not compromise the token's security.
5. Scalability and Performance: Designed to handle various loads, the implementation remains efficient and performant even under high demand, making it suitable for both small-scale and large-scale applications.

By adhering to these design principles, "Selective Disclosure for JWT" aims to set a new standard in the secure and efficient handling of JWTs across diverse JavaScript environments.

Architecture

How to use

Packages

• @sd-jwt/core: Core library for selective disclosure JWTs
• @sd-jwt/sd-jwt-vc: SD-JWT VC format based on the core functions
• @sd-jwt/decode: Decode SD JWT into objects
• @sd-jwt/present: Present SD JWT
• @sd-jwt/utils: Utility functions for SD JWT
• @sd-jwt/types: Types for SD JWT
• @sd-jwt/hash: SHA-256 support for SD JWT
• @sd-jwt/crypto-nodejs: Nodejs Crypto support for SD JWT
• @sd-jwt/crypto-browser: Browser Crypto support for SD JWT

Online Debugging Tool

You can use our online debugger built with our library here: https://sdjwt.co

Version

We keep all the versions of our packages in sync.

It means for example, that if you are using @sd-jwt/[email protected], you should use @sd-jwt/[email protected], @sd-jwt/[email protected] and so on.

Development

Build

To build this projects

pnpm install

pnpm run build

Testing

To run the test suite, execute:

pnpm test

We use Vitest for our testing framework. Ensure you have written tests for all new features.

We also use CodeCov for our testing coverage. You can check the details of coverage of each package

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

Contributing

Contributions are welcome! Please read our contributing guidelines before making pull requests.

License

This project is licensed under the Apache 2.0 License

Contact

For support or contributions, You can find us in OpenWallet Foundation discord.

Acknowledgments

Special thanks to all the contributors and the OpenWallet Foundation community for their invaluable input.