Uport-jwt NPM | npm.io

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

ES256k the secp256k1 ECDSA curve

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	yes
`s`	Hex encoded `s` value of secp256k1 signature	yes
`recoveryParam`	Recovery parameter of signature (can be used to calculate signing public key)	no

babel-runtime base64url did-resolver elliptic js-sha256 mnid uport-did-resolver uport-lite

@infinitebrahmanuniverse/nolb-upo @everything-registry/sub-chunk-3021

0.0.2

6 years ago

0.0.1

6 years ago