# Design Documentation: SD-JWT

Submitted by Kim Duffy for the Onyx Digital Identity Hackathon

Oct 8, 2023

## Overview

This documentation provides an overview of the design decisions and future opportunities related to the implementation of SD-JWT.

- [Repo](https://github.com/kimdhamilton/onyx-ssi-sdk/tree/kimdhamilton/sdjwt-hackathon)
- [Diffs](https://github.com/jpmorganchase/onyx-ssi-sdk/compare/sdjwt-hackathon...kimdhamilton:onyx-ssi-sdk:kimdhamilton/sdjwt-hackathon?expand=1)

## Table of Contents

- [Design Decisions](#design-decisions)
- [Additional Notes](#additional-notes)
* [Naming](#naming)
* [What's in, what's out](#whats-in-whats-out)
* [File structure](#file-structure)
- [Next steps and future direction](#next-steps-and-future-direction)
- [References](#references)

## Design Decisions

> Note: on our call, I said I was planning to submit this directly to DIF, but decided that path (including getting the dependency updated and back to you) would take too long. We can still go that route (later) if you prefer, but it is now a direct submission against the onyx repo.

Above all, I optimized for
- Consistency with the did-jwt (and eventually did-jwt-vc) to improve consistency with the rest of the Onyx library, and
- Demonstrating SD-JWT spec compliance

This and others are described below.

1. did-jwt consistency: it's exciting that Onyx is already using these libraries. These are actively maintained by the DIF community, so this ensures you get the latest and greatest signature suites, etc. I kept the function signatures similar and compatible, and also reused this functionality wherever possible

2. SD-JWT spec compliance: I added fairly comprehensive test vectors from the SD-JWT spec, and modifications to cover more test cases. Because they take a lot of space, they are in a separate sdjwt.vectors.ts file

3. VC support: A huge realization was that the [SD-JWT-VC](https://www.ietf.org/archive/id/draft-terbu-oauth-sd-jwt-vc-00.html) spec does NOT actually apply to did-jwt-vcs. But I think this modification would be pretty straightforward, and this is something I would have added with more time

4. Stringify issues.

In general, to match the SD-JWT spec examples exactly, 2 things are required when creating a disclosure:
1. must use the same salt, which they've provided
2. must stringify in the same way.

#2 is the complicated one. SD-JWT spec uses a stringification method that doesn't easily map to JSON.stringify. I included a workaround mode to demonstrate. I don't recommend using this compat mode in general. This is why there are two disclosures in the test vectors:

e.g.

specDisclosure:
      "WyJHMDJOU3JRZmpGWFE3SW8wOXN5YWpBIiwgInVwZGF0ZWRfYXQiLCAxNTcwMDAwMDAwXQ",
defaultDisclosure:
      "WyJHMDJOU3JRZmpGWFE3SW8wOXN5YWpBIiwidXBkYXRlZF9hdCIsMTU3MDAwMDAwMF0",

5. Creating SD-JWTs: this is where I took some shortcuts. The creation helpers I added are rudimentary, but help get you started. Future extensions are described below

## Additional Notes

### Naming

- "Disclosure" refers to: base64url-encode the byte representation of the UTF-8 string -- not the raw/decoded object form or a digest
- "Digest" is the hash/digest embedded in the SD-JWT payload

### What's in, what's out
- Implement recursion (with accompanying test cases, but this could use more)
- Did not include key binding

### File structure

The sdjwt.ts file is fairly meaty, and I normally might have teased it apart, but I wanted to follow the guidance to submit it in one file. So I added section or block comments to clarify sections
- types
- main functionality
- utilities
- creation helpers
- did-jwt workarounds

## Next steps and future direction
- Add more comments and test cases
- Check that digests are not found more than once and efficiency of recursive decoding.
- Implement key binding
- Built out an SD-JWT-VC example
- Improve SD-JWT creation/management helpers. Options I considered include
- json-pointer to point to the parts in a payload to redact
- Builders that support nesting and recursive SD more easily

## References
- [SD-JWT spec](https://datatracker.ietf.org/doc/draft-ietf-oauth-selective-disclosure-jwt/)
- [SD-JWT-VC spec](https://www.ietf.org/archive/id/draft-terbu-oauth-sd-jwt-vc-00.html)