uport-jwt

0.0.2 • Public • Published

uport-jwt

The uPort-JWT library allows you to sign and verify JSON Web Tokens (JWT). Public keys are resolved using the Decentralized ID (DID) of the iss claim of the JWT.

JWT Details

Algorithms supported

Claims

Name Description Required
iss The DID of the signing identity yes
sub The DID of the subject of the JWT no
aud The DID or URL of the audience of the JWT. Our libraries or app will not accept any JWT that has someone else as the audience no
iat The time of issuance yes
exp Expiration time of JWT no

Installation

npm install uport-jwt

or if you use yarn

yarn add uport-jwt

API

Creating a JWT

Use the createJWT() function

import { createJWT, SimpleSigner } from 'uport-jwt'

const signer = SimpleSigner('PRIVATEKEY')

createJWT(
    {aud: 'did:uport:did:uport:2nQtiQG6Cgm1GYTBaaKAgr76uY7iSexUkqY', exp: 1485321133, name: 'Bob Smith'},
    {issuer: 'did:uport:2nQtiQG6Cgm1GYTBaaKAgr76uY7iSexUkqX', signer}).then(jwt => {
    console.log(jwt)
})

Parameters

createJWT(payload, settings)
Name Description Required
payload an object containing any claims you want to encode in the JWT including optional standard claims such as sub, aud and exp yes
settings.issuer The DID of the audience of the JWT yes
settings.signer A signing function (see SimpleSigner) yes
settings.expiresIn How many seconds after signing should the JWT be valid (sets the exp claim) no

Promise Return Value

The createJWT() function returns a Promise.

A successfull call returns an object containing the following attributes:

Name Description
jwt String containing a JSON Web Tokens (JWT)

If there are any errors found during the signing process the promise is rejected with a clear error message.

Verifying a JWT

Use the verifyJWT() function

import { verifyJWT } from 'uport-jwt'

verifyJWT('eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NksifQ.eyJpc3MiOiJkaWQ6dXBvcn....', {audience: 'Your DID'}).then({payload, doc, did, signer, jwt} => {
    console.log(payload)
})

Parameters

verifyJWT(jwt, options)
Name Description Required
jwt String containing a JSON Web Tokens (JWT) yes
options.audience The DID of the audience of the JWT no
options.callbackUrl The the URL receiving the JWT no

Promise Return Value

The verifyJWT() function returns a Promise.

A successfull call returns an object containing the following attributes:

Name Description
payload An object containing the JSON parsed contents of the payload section of the JWT
issuer The DID of the issuer of the JWT
signer An object containing information about which key signed the JWT. This is useful if a DID document has multiple keys listed
doc The DID Document of the issuer of the JWT
jwt The original JWT passed in to the function

If there are any errors found during the verification process the promise is rejected with a clear error message.

Signer Functions

We provide a simple signing abstraction that makes it easy to add support for your own Key Management infrastructure.

SimpleSigner

For most people you can use our SimpleSigner() function to creaate a signer function using a hex encoded private key.

import { SimpleSigner } from 'uport-jwt'
const signer = SimpleSigner('278a5de700e29faae8e40e366ec5012b5ec63d36ec77e8a2417154cc1d25383f')

Parameters

SimpleSigner(privateKey)
Name Description Required
privateKey hex encoded secp256k1 privatekey yes

Note this is NOT a constructor, but a higher order function that returns a signing function.

Creating Custom Signers for integrating with HSM

You can easily create custom signers that integrates into your existing signing infrastructure. A signer function takes the raw data to be signed and returns a Promise containing the signature parameters.

function mySigner (hash) {
    return new Promise((resolve, reject) => {
        const signature = /// sign it
        resolve(signature)
    })
}

Parameters

Name Description Required
hash Buffer containing hash of data to be signed yes

Promise Return Value

Your function must returns a Promise.

A successfull call returns an object containing the following attributes:

Name Description
r Hex encoded r value of secp256k1 signature
s Hex encoded s value of secp256k1 signature
recoveryParam Recovery parameter of signature (can be used to calculate signing public key)

Readme

Keywords

none

Package Sidebar

Install

npm i uport-jwt

Weekly Downloads

1

Version

0.0.2

License

Apache-2.0

Unpacked Size

529 kB

Total Files

20

Last publish

Collaborators

  • pelleb