transmute-industries / vc-jwt-sd

Experimental implementation of sd-jwt for W3C Verifiable Credentials

@transmute/vc-jwt-sd

🚧 Experimental implementation of sd-jwt for use with W3C Verifiable Credentials. 🔥

Questions? Contact Transmute

Usage

npm i @transmute/vc-jwt-sd --save

import sd from '@transmute/vc-jwt-sd'

Issuer Claims

This implementation relies on custom yaml tags to indicate disclosability:

# Based on https://w3c.github.io/vc-data-model/#example-a-simple-example-of-a-verifiable-credential
"@context":
  - https://www.w3.org/ns/credentials/v2
  - https://www.w3.org/ns/credentials/examples/v2
id: http://university.example/credentials/3732
type:
  - VerifiableCredential
  - ExampleDegreeCredential
issuer:
  id: https://university.example/issuers/565049
  name:
    - value: test value 0
      lang: en
    - !sd # indicates a disclosable claim
      value: test value 1
      lang: en
    - value: test value 2
      lang: en
    - !sd # indicates a disclosable claim
      value: test value 3
      lang: en
    - value: test value 4
      lang: en
validFrom: 2015-05-10T12:30:00Z
credentialStatus:
  - id: https://vendor.example/status-list/urn:uuid:d31ada5d-1d3d-4f68-8587-8ff9bb3038d6#0
    type: StatusList2021Entry
    statusPurpose: revocation
    statusListIndex: "0"
    statusListCredential: https://vendor.example/status-list/urn:uuid:d31ada5d-1d3d-4f68-8587-8ff9bb3038d6
credentialSubject:
  id: did:example:ebfeb1f712ebc6f1c276e12ec21
  degree:
    type: ExampleBachelorDegree
    subtype: Bachelor of Science and Arts

Credential Issuance

const alg = 'ES384';
const claimset = `... yaml example above ... `;

const issuerRole = await sd.key.generate(alg);
const issuerId = 'https://university.example/issuers/565049'
const issuerKeyId = `${issuerId}#key-42`

const holderRole = await sd.key.generate(alg); // or get it some other way.
const holderId = 'did:example:ebfeb1f712ebc6f1c276e12ec21'
const holderKeyId = `${holderId}#${holderRole.publicKeyJwk.kid}`

const vc = await sd.issuer({ 
  iss: issuerId, 
  kid: issuerKeyId,
  typ: `application/vc+ld+json+sd-jwt`,
  secretKeyJwk: issuerRole.secretKeyJwk 
})
.issue({
  holder: holderKeyId,
  claimset
})

Holder Disclosure

This implementation relies on yaml to indicate holder disclosures:

"@context":
  - https://www.w3.org/ns/credentials/v2
  - https://www.w3.org/ns/credentials/examples/v2
id: http://university.example/credentials/3732
type:
  - VerifiableCredential
  - ExampleDegreeCredential
issuer:
  id: https://university.example/issuers/565049
  name:
    - value: test value 0
      lang: en
    - value: test value 1 # The value or True can be provided to signal intentional disclosure.
      lang: en
    - value: test value 2
      lang: en
    - False # This boolean indicates that this claim should not be disclosed in a presentation
    - value: test value 4
      lang: en
validFrom: 2015-05-10T12:30:00Z
credentialStatus:
  - id: https://vendor.example/status-list/urn:uuid:d31ada5d-1d3d-4f68-8587-8ff9bb3038d6#0
    type: StatusList2021Entry
    statusPurpose: revocation
    statusListIndex: "0"
    statusListCredential: https://vendor.example/status-list/urn:uuid:d31ada5d-1d3d-4f68-8587-8ff9bb3038d6
credentialSubject:
  id: did:example:ebfeb1f712ebc6f1c276e12ec21
  degree:
    type: ExampleBachelorDegree
    subtype: Bachelor of Science and Arts

Presentation with Holder Binding

const audience = 'aud-9877'
const nonce = 'nonce-5486168'
const disclosure = `... yaml example above ... `;
const vp = await sd.holder({ 
  secretKeyJwk: holderRole.secretKeyJwk,
  iss: holderId,
  kid: holderKeyId
})
.issue({
  token: vc,
  disclosure,
  audience,
  nonce
})

Verification by Key Resolution

Some protocols allow for discovery of public keys from identifiers.

🍃 This interface is safer, since it performs verification internally, which will fail closed when the incorrect public key is provided.

const verification = await sd.verifier({
  resolver: {
    resolve: async (kid: string) => {
      if (kid === issuerKeyId){
        return issuerRole.publicKeyJwk
      } 
      if (kid === holderKeyId){
        return holderRole.publicKeyJwk
      }
      throw new Error('Unsupported kid: ' + kid)
    }
  }
})
.verify({
  token: vp,
  audience,
  nonce
})

Verification by Token

Some protocols require disovery of public keys from protected header and payload claims.

🍂 This interface is less safe, but more flexible. When misconfigured, this interface can lead to decoded values being treated as if they had been verified.

// for testing, not a real dereferencer
const dereference = async (url: string) => {
  if (url.startsWith('https://university.example/issuers/565049')){
    return { 
      id: issuerKeyId,
      type: 'JsonWebKey',
      controller: issuerId,
      publicKeyJwk: issuerRole.publicKeyJwk
    }
  }
  if (url.startsWith('did:example:ebfeb1f712ebc6f1c276e12ec21')){
    return { 
      id: holderKeyId,
      type: 'JsonWebKey',
      controller: holderId,
      publicKeyJwk: holderRole.publicKeyJwk
    }
  }
  throw new Error('Unsupported didUrl: ' + didUrl)
}
const verification = await sd.verifier({
  verifier: {
    verify: async (token: string) => {
      const jwt = token.split('~')[0]
      const decodedHeader = decodeProtectedHeader(jwt)
      if (decodedHeader.typ === 'application/vc+ld+json+sd-jwt'){
        const decodedPayload = decodeJwt(jwt)
        const iss = (decodedHeader.iss || decodedPayload.iss) as string
        const kid = decodedHeader.kid as string
        const absoluteDidUrl = kid && kid.startsWith(iss)? kid : `${iss}#${kid}`
        const { publicKeyJwk } = await dereference(absoluteDidUrl)
        const verifier = await sd.JWS.verifier(publicKeyJwk)
        return verifier.verify(jwt)
      } 
      if (decodedHeader.typ === 'kb+jwt'){
        const decodedPayload = decodeJwt(jwt)
        const iss = (decodedHeader.iss || decodedPayload.iss) as string
        const kid = decodedHeader.kid as string
        const absoluteDidUrl = kid && kid.startsWith(iss)? kid : `${iss}#${kid}`
        const { publicKeyJwk } = await dereference(absoluteDidUrl)
        const verifier = await sd.JWS.verifier(publicKeyJwk)
        return verifier.verify(jwt)
      } 
      throw new Error('Unsupported token typ')
    }
  }
})
.verify({
  token: vp,
  audience,
  nonce
})

Validation

🚧 This library does not perform validation currently. This is the result of the verification operations above:

{
  "protectedHeader": {
    "alg": "ES384",
    "kid": "https://university.example/issuers/565049#key-42",
    "typ": "application/vc+ld+json+sd-jwt"
  },
  "claimset": {
    "iss": "https://university.example/issuers/565049",
    "cnf": {
      "jkt": "did:example:ebfeb1f712ebc6f1c276e12ec21#KmC0EKbs0kL2v6kxPP_c4g-HMMy-n8C5NwtN2tH_msc"
    },
    "@context": [
      "https://www.w3.org/ns/credentials/v2",
      "https://www.w3.org/ns/credentials/examples/v2"
    ],
    "id": "http://university.example/credentials/3732",
    "type": [
      "VerifiableCredential",
      "ExampleDegreeCredential"
    ],
    "issuer": {
      "id": "https://university.example/issuers/565049",
      "name": [
        {
          "value": "test value 0",
          "lang": "en"
        },
        {
          "value": "test value 1",
          "lang": "en"
        },
        {
          "value": "test value 2",
          "lang": "en"
        },
        {
          "value": "test value 4",
          "lang": "en"
        }
      ]
    },
    "validFrom": "2015-05-10T12:30:00Z",
    "credentialStatus": [
      {
        "id": "https://vendor.example/status-list/urn:uuid:d31ada5d-1d3d-4f68-8587-8ff9bb3038d6#0",
        "type": "StatusList2021Entry",
        "statusPurpose": "revocation",
        "statusListIndex": "0",
        "statusListCredential": "https://vendor.example/status-list/urn:uuid:d31ada5d-1d3d-4f68-8587-8ff9bb3038d6"
      }
    ],
    "credentialSubject": {
      "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
      "degree": {
        "type": "ExampleBachelorDegree",
        "subtype": "Bachelor of Science and Arts"
      }
    },
  }
}

Develop

npm i
npm t
npm run lint
npm run build

Integration Tests

Synching tests cases from reference implementation

git clone [email protected]:danielfett/sd-jwt.git
cd sd-jwt
python3 -m venv venv
source venv/bin/activate
pip install git+https://github.com/danielfett/sd-jwt.git
cd tests/testcases
sd-jwt-generate example
cd ..
cp -r ./testcases ../../testcases

Other implementations

• https://github.com/openwallet-foundation-labs/sd-jwt-python
• https://github.com/oauth-wg/oauth-selective-disclosure-jwt
• https://github.com/danielfett/sd-jwt
• https://github.com/christianpaquin/sd-jwt
• https://github.com/chike0905/sd-jwt-ts
• https://github.com/or13/vc-sd-jwt

vc-jwt-sd's Issues

question - impact of RDF

Hi.
Thank you for the great work.

Did you check, or do you know, the impact of RDF/normalisation processing?
Should we expect any difference if we strip that away (for pedagogical purposes)?

Missing module crypto

need to fix so it can run in web browser.

Remove "alg" from role initializers

it should be possible init an holder, issuer, verifier, without setting an algorithm, this supports the case where the algorihm is assigned by a remote signer.

Import in module fails due to default export

When doing import SD from '@transmute/vc-jwt-sd' the default export returns an object like so {default: SD}

the current import into an ES2022 module can only be done like so:

import SD from '@transmute/vc-jwt-sd';
const vcjwtsd = (SD as any).default;

address multiple audience use case

audience can be an array of strings.

Verification of expiry and issuance date

Do iat and exp get checked in the verify process? Afaik. they don't. The proposed verifier uses jose.compactVerify(jws, publicKey); which does not check on the dates. Neither this is done for validFrom and validUntil.

Is the user supposed to do these checks? because i tested expired credentials and they verified.

refactor this library to just implement the OAuth WG draft

move all the W3C stuff to another repo.