Skip to content

Commit

Permalink
Merge branch 'release/v0.1.2'
Browse files Browse the repository at this point in the history
  • Loading branch information
@mi-xu
mi-xu committed Apr 10, 2019
2 parents 68eda6b + be10aae commit a4b0ecb
Show file tree
Hide file tree
Showing 21 changed files with 4,891 additions and 5,361 deletions.
4 changes: 2 additions & 2 deletions .babelrc
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
{
"presets": ["env"],
"plugins": ["transform-runtime", "transform-object-rest-spread"]
"presets": ["@babel/env"],
"plugins": ["@babel/plugin-transform-runtime"]
}
7 changes: 7 additions & 0 deletions .eslintrc.js
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
module.exports = {
"extends": "standard",
"plugins": ["jest"],
"env": {
"jest/globals": true
}
}
4 changes: 4 additions & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,3 +9,7 @@ coverage
*.tgz
/docs/.DS_Store
/.DS_Store
docs/*.html
docs/fonts
docs/scripts
docs/styles
19 changes: 17 additions & 2 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,26 @@

[Algorithms supported](docs/guides/index.md#algorithms-supported) | [DID Public Key Types](docs/guides/index.md#did-publickey-types) | [Claim Specification](docs/guides/index.md#claims)


The did-JWT library allows you to sign and verify [JSON Web Tokens (JWT)](https://tools.ietf.org/html/rfc7519) using ES256K or ES256K-R algorithms.
The did-JWT library allows you to sign and verify [JSON Web Tokens (JWT)](https://tools.ietf.org/html/rfc7519) using ES256K, ES256K-R and Ed25519 algorithms.

Public keys are resolved using the [Decentralized ID (DID)](https://w3c-ccg.github.io/did-spec/#decentralized-identifiers-dids) of the signing identity of the claim, which is passed as the `iss` attribute of the encoded JWT.

## DID methods

We currently support the following DID methods:

- [`ethr`](https://github.com/uport-project/ethr-did-resolver)
- [`uport`](https://github.com/uport-project/uport-did-resolver)
- [`https`](https://github.com/uport-project/https-did-resolver)
- [`nacl`](https://github.com/uport-project/nacl-did)
- [`muport`](https://github.com/3box/muport-did-resolver)

You will need to install each one you need to support. See each method for how to configure it.

Support for other DID methods should be simple. Write a DID resolver supporting the [`did-resolver'](https://github.com/uport-project/did-resolver) interface. Once you've verified that it works, please add a PR adding it to the above list so people can find it.

If your DID method requires a different signing algorithm than what is already supported, please create a PR.

## Installation

```bash
Expand Down
178 changes: 0 additions & 178 deletions docs/reference/index.md
View file
Original file line number Diff line number Diff line change
@@ -1,178 +0,0 @@
---
title: "DID JWT"
index: 3
category: "did-jwt"
type: "reference"
---

## Algorithms supported

- `ES256K` the [secp256k1 ECDSA curve](https://en.bitcoin.it/wiki/Secp256k1)
- `ES256K-R` the [secp256k1 ECDSA curve](https://en.bitcoin.it/wiki/Secp256k1) with recovery parameter

## DID PublicKey Types

The `PublicKey` section of a DID document contains one or more Public Keys. We support the following types:

Name | Encoding | Algorithm's
---- | -------- | -----------
`Secp256k1SignatureVerificationKey2018` | `publicKeyHex` | `ES256K`, `ES256K-R`
`Secp256k1VerificationKey2018` | `publicKeyHex` | `ES256K`, `ES256K-R`
`Secp256k1VerificationKey2018` | `ethereumAddress` | `ES256K-R`

## Claims

Name | Description | Required
---- | ----------- | --------
[`iss`](https://tools.ietf.org/html/rfc7519#section-4.1.1) | The [DID](https://w3c-ccg.github.io/did-spec/) of the signing identity| yes
[`sub`](https://tools.ietf.org/html/rfc7519#section-4.1.2) | The [DID](https://w3c-ccg.github.io/did-spec/) of the subject of the JWT| no
[`aud`](https://tools.ietf.org/html/rfc7519#section-4.1.3) | The [DID](https://w3c-ccg.github.io/did-spec/) 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`](https://tools.ietf.org/html/rfc7519#section-4.1.6) | The time of issuance | yes
[`exp`](https://tools.ietf.org/html/rfc7519#section-4.1.4) | Expiration time of JWT | no

## Modules

<dl>
<dt><a href="#module_did-jwt/JWT">did-jwt/JWT</a></dt>
<dd></dd>
</dl>

## Functions

<dl>
<dt><a href="#SimpleSigner">SimpleSigner(hexPrivateKey)</a> ⇒ <code>function</code></dt>
<dd><p>The SimpleSigner returns a configured function for signing data. It also defines
an interface that you can also implement yourself and use in our other modules.</p>
</dd>
</dl>

<a name="module_did-jwt/JWT"></a>

## did-jwt/JWT

* [did-jwt/JWT](#module_did-jwt/JWT)
* [.decodeJWT(jwt)](#module_did-jwt/JWT.decodeJWT) ⇒ <code>Object</code>
* [.createJWT(payload, [options])](#module_did-jwt/JWT.createJWT) ⇒ <code>Promise.&lt;Object, Error&gt;</code>
* [.verifyJWT(jwt, [options])](#module_did-jwt/JWT.verifyJWT) ⇒ <code>Promise.&lt;Object, Error&gt;</code>
* [.resolveAuthenticator(alg, did, auth)](#module_did-jwt/JWT.resolveAuthenticator) ⇒ <code>Promise.&lt;Object, Error&gt;</code>

<a name="module_did-jwt/JWT.decodeJWT"></a>

### did-jwt/JWT.decodeJWT(jwt) ⇒ <code>Object</code>
Decodes a JWT and returns an object representing the payload

**Kind**: static method of [<code>did-jwt/JWT</code>](#module_did-jwt/JWT)
**Returns**: <code>Object</code> - a JS object representing the decoded JWT

| Param | Type | Description |
| --- | --- | --- |
| jwt | <code>String</code> | a JSON Web Token to verify |

**Example**
```js
decodeJWT('eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NksifQ.eyJpYXQiOjE1MjU5Mjc1MTcsImF1ZCI6ImRpZDp1cG9ydDoyb3NuZko0V3k3TEJBbTJuUEJYaXJlMVdmUW43NVJyVjZUcyIsImV4cCI6MTU1NzQ2MzQyMSwibmFtZSI6InVQb3J0IERldmVsb3BlciIsImlzcyI6ImRpZDp1cG9ydDoyb3NuZko0V3k3TEJBbTJuUEJYaXJlMVdmUW43NVJyVjZUcyJ9.R7owbvNZoL4ti5ec-Kpktb0datw9Y-FshHsF5R7cXuKaiGlQz1dcOOXbXTOb-wg7-30CDfchFERR6Yc8F61ymw')


```
<a name="module_did-jwt/JWT.createJWT"></a>

### did-jwt/JWT.createJWT(payload, [options]) ⇒ <code>Promise.&lt;Object, Error&gt;</code>
Creates a signed JWT given an address which becomes the issuer, a signer, and a payload for which the signature is over.

**Kind**: static method of [<code>did-jwt/JWT</code>](#module_did-jwt/JWT)
**Returns**: <code>Promise.&lt;Object, Error&gt;</code> - a promise which resolves with a signed JSON Web Token or rejects with an error

| Param | Type | Description |
| --- | --- | --- |
| payload | <code>Object</code> | payload object |
| [options] | <code>Object</code> | an unsigned credential object |
| options.issuer | <code>String</code> | The DID of the issuer (signer) of JWT |
| options.alg | <code>String</code> | The JWT signing algorithm to use. Supports: [ES256K, ES256K-R], Defaults to: ES256K |
| options.signer | [<code>SimpleSigner</code>](#SimpleSigner) | a signer, reference our SimpleSigner.js |

**Example**
```js
const signer = SimpleSigner(process.env.PRIVATE_KEY)
createJWT({address: '5A8bRWU3F7j3REx3vkJ...', signer}, {key1: 'value', key2: ..., ... }).then(jwt => {
...
})


```
<a name="module_did-jwt/JWT.verifyJWT"></a>

### did-jwt/JWT.verifyJWT(jwt, [options]) ⇒ <code>Promise.&lt;Object, Error&gt;</code>
Verifies given JWT. If the JWT is valid, the promise returns an object including the JWT, the payload of the JWT,
and the did doc of the issuer of the JWT.

**Kind**: static method of [<code>did-jwt/JWT</code>](#module_did-jwt/JWT)
**Returns**: <code>Promise.&lt;Object, Error&gt;</code> - a promise which resolves with a response object or rejects with an error

| Param | Type | Description |
| --- | --- | --- |
| jwt | <code>String</code> | a JSON Web Token to verify |
| [options] | <code>Object</code> | an unsigned credential object |
| options.auth | <code>Boolean</code> | Require signer to be listed in the authentication section of the DID document (for Authentication purposes) |
| options.audience | <code>String</code> | DID of the recipient of the JWT |
| options.callbackUrl | <code>String</code> | callback url in JWT |

**Example**
```js
verifyJWT('did:uport:eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NksifQ.eyJyZXF1Z....', {audience: '5A8bRWU3F7j3REx3vkJ...', callbackUrl: 'https://...'}).then(obj => {
const did = obj.did // DID of signer
const payload = obj.payload
const doc = obj.doc // DID Document of signer
const jwt = obj.jwt
const signerKeyId = obj.signerKeyId // ID of key in DID document that signed JWT
...
})


```
<a name="module_did-jwt/JWT.resolveAuthenticator"></a>

### did-jwt/JWT.resolveAuthenticator(alg, did, auth) ⇒ <code>Promise.&lt;Object, Error&gt;</code>
Resolves relevant public keys or other authenticating material used to verify signature from the DID document of provided DID

**Kind**: static method of [<code>did-jwt/JWT</code>](#module_did-jwt/JWT)
**Returns**: <code>Promise.&lt;Object, Error&gt;</code> - a promise which resolves with a response object containing an array of authenticators or if non exist rejects with an error

| Param | Type | Description |
| --- | --- | --- |
| alg | <code>String</code> | a JWT algorithm |
| did | <code>String</code> | a Decentralized IDentifier (DID) to lookup |
| auth | <code>Boolean</code> | Restrict public keys to ones specifically listed in the 'authentication' section of DID document |

**Example**
```js
resolveAuthenticator('ES256K', 'did:uport:2nQtiQG6Cgm1GYTBaaKAgr76uY7iSexUkqX').then(obj => {
const payload = obj.payload
const profile = obj.profile
const jwt = obj.jwt
...
})


```
<a name="SimpleSigner"></a>

## SimpleSigner(hexPrivateKey) ⇒ <code>function</code>
The SimpleSigner returns a configured function for signing data. It also defines
an interface that you can also implement yourself and use in our other modules.

**Kind**: global function
**Returns**: <code>function</code> - a configured signer function

| Param | Type | Description |
| --- | --- | --- |
| hexPrivateKey | <code>String</code> | a hex encoded private key |

**Example**
```js
const signer = SimpleSigner(process.env.PRIVATE_KEY)
signer(data, (err, signature) => {
...
})


```
Loading

0 comments on commit a4b0ecb

Please sign in to comment.