Validated ID DID JWT Library

Validated Id did-jwt library allows you to sign and verify JSON Web Tokens (JWT) using ES256K, ES256K-R and Ed25519 algorithms using vid:did.

Public keys are resolved using the Decentralized ID (DID) of the signing identity of the claim, which is passed as the iss attribute of the encoded JWT.

Supports OIDC SIOP DID flows using @validatedid/did-auth library to verify a SIOP Response JWT where client_id and aud are URLs instead of a DID.

Table of Contents

1. Installation
2. DID methods
3. Example
4. Library Test
5. Licensing

Installation

npm install @validatedid/did-jwt

or if you use yarn

yarn add @validatedid/did-jwt

DID methods

We only support vid:did DID method:

• vid

Example

1. Create a did-JWT

createJWT

In practice you should secure the key passed to SimpleSigner. The key provided in code below is for informational purposes.

const didJWT = require("@validatedid/did-jwt");
const signer = didJWT.SimpleSigner(
  "278a5de700e29faae8e40e366ec5012b5ec63d36ec77e8a2417154cc1d25383f"
);

let jwt = "";
didJWT
  .createJWT(
    {
      aud: "did:vid:0xf3beac30c498d9e26865f34fcaa57dbb935b0d74",
      exp: 1957463421,
      name: "name",
    },
    {
      alg: "ES256K-R",
      issuer: "did:vid:0xf3beac30c498d9e26865f34fcaa57dbb935b0d74",
      signer,
    }
  )
  .then((response) => {
    jwt = response;
  });

console.log(jwt);

2. Decode a did-JWT

Try decoding the JWT. You can also do this using jwt.io

//pass the jwt from step 1
let decoded = didJWT.decodeJWT(jwt);
console.log(decoded);

Once decoded a did-JWT will resemble:

{
  header: { typ: 'JWT', alg: 'ES256K-R' },
  payload: {
    iat: 1571692233,
    exp: 1957463421,
    aud: 'did:vid:0xf3beac30c498d9e26865f34fcaa57dbb935b0d74',
    name: 'name',
    iss: 'did:vid:0xf3beac30c498d9e26865f34fcaa57dbb935b0d74'
  },
  signature: 'kkSmdNE9Xbiql_KCg3IptuJotm08pSEeCOICBCN_4YcgyzFc4wIfBdDQcz76eE-z7xUR3IBb6-r-lRfSJcHMiAA',
  data: 'eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NkstUiJ9.eyJpYXQiOjE1NzE2OTIyMzMsImV4cCI6MTk1NzQ2MzQyMSwiYXVkIjoiZGlkOmV0aHI6MHhmM2JlYWMzMGM0OThkOWUyNjg2NWYzNGZjYWE1N2RiYjkzNWIwZDc0IiwibmFtZSI6InVQb3J0IERldmVsb3BlciIsImlzcyI6ImRpZDpldGhyOjB4ZjNiZWFjMzBjNDk4ZDllMjY4NjVmMzRmY2FhNTdkYmI5MzViMGQ3NCJ9'
}

4. Verify a did-JWT

verifyJWT

You need to provide a did-resolver for the verify function. For this example we will use ethr-did, but there are other methods available above. For more information on configuring the Resolver object please see did-resolver

npm install @validatedid/vid-did-resolver

const Resolver = require("did-resolver");
const vidDid = require("@validatedid/vid-did-resolver").getResolver();

let resolver = new Resolver.Resolver(vidDid);

let verifiedResponse = {};
// pass the JWT from step 1 & 2
didJWT
  .verifyJwt(jwt, {
    resolver: resolver,
    audience: "did:vid:0xf3beac30c498d9e26865f34fcaa57dbb935b0d74",
  })
  .then((response) => {
    verifiedResponse = response;
  });

console.log(verifiedResponse);

A verified did-JWT returns an object resembling:

{
  payload: {
    iat: 1571692448,
    exp: 1957463421,
    aud: 'did:vid:0xf3beac30c498d9e26865f34fcaa57dbb935b0d74',
    name: 'name',
    iss: 'did:vid:0xf3beac30c498d9e26865f34fcaa57dbb935b0d74'
  },
  doc: {
    '@context': 'https://w3id.org/did/v1',
    id: 'did:vid:0xf3beac30c498d9e26865f34fcaa57dbb935b0d74',
    publicKey: [ [Object] ],
    authentication: [ [Object] ]
  },
  issuer: 'did:vid:0xf3beac30c498d9e26865f34fcaa57dbb935b0d74',
  signer: {
    id: 'did:vid:0xf3beac30c498d9e26865f34fcaa57dbb935b0d74#owner',
    type: 'Secp256k1VerificationKey2018',
    controller: 'did:vid:0xf3beac30c498d9e26865f34fcaa57dbb935b0d74',
    ethereumAddress: '0xf3beac30c498d9e26865f34fcaa57dbb935b0d74'
  },
  jwt: 'eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NkstUiJ9.eyJpYXQiOjE1NzE2OTI0NDgsImV4cCI6MTk1NzQ2MzQyMSwiYXVkIjoiZGlkOmV0aHI6MHhmM2JlYWMzMGM0OThkOWUyNjg2NWYzNGZjYWE1N2RiYjkzNWIwZDc0IiwibmFtZSI6InVQb3J0IERldmVsb3BlciIsImlzcyI6ImRpZDpldGhyOjB4ZjNiZWFjMzBjNDk4ZDllMjY4NjVmMzRmY2FhNTdkYmI5MzViMGQ3NCJ9.xd_CSWukS6rK8y7GVvyH_c5yRsDXojM6BuKaf1ZMg0fsgpSBioS7jBfyk4ZZvS0iuFu4u4_771_PNWvmsvaZQQE'
}

4. Verify vid did-JWT

We are using the ES256K-R algorithm that allows to recover the publickey based on the signature and the data. That's why for now the vid-did-resolver doesn't reply with the ethereumAddress inside the publickey object. Indeed we are recovering the pubkey from the signature and then we are converting it to an eth address. Finally we are comparing that recovered eth address against the ethereumAddress return by the resolver to verify the signature.

The vidVerifyJwt function is used to verify a DID JWT. In the options, the resolver can be an url to connect with the VIDchain API, or an object resolver like the example in the previous section.

const urlResolver = "https://api.vidchain.net/api/v1/identifiers";

let verifiedResponse = {};
// pass the JWT from step 1 & 2
didJWT
  .vidVerifyJwt(jwt, {
    resolver: urlResolver,
    audience: "did:vid:0xf3beac30c498d9e26865f34fcaa57dbb935b0d74",
  })
  .then((response) => {
    verifiedResponse = response;
  });

console.log(verifiedResponse);

Library Test

Create an .env file using .env.example and update the env variables.

# unit tests
$ yarn test

Licensing

Unless required by applicable law or agreed to in writing, software distributed under the Licence is distributed on an "AS IS" basis, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the Licence for the specific language governing permissions and limitations under the Licence.

Library based on did-jwt library licensed under Apache 2.0 Copyright 2020 decentralized identity. Here are the changes applied to the original library:

• remove uport-base64url dependency in favor of base64url
• use of tweetnacl-ts dependency instead of tweetnacl
• Use of the factory pattern for signer and verifier algorithm
• Add unit tests