feat: define and export known error prefixes

README.md

@@ -1,6 +1,6 @@
 [![npm](https://img.shields.io/npm/dt/did-jwt.svg)](https://www.npmjs.com/package/did-jwt)
 [![npm](https://img.shields.io/npm/v/did-jwt.svg)](https://www.npmjs.com/package/did-jwt)
-[![Twitter Follow](https://img.shields.io/twitter/follow/uport_me.svg?style=social&label=Follow)](https://twitter.com/uport_me)
+[![Twitter Follow](https://img.shields.io/twitter/follow/veramolabs.svg?style=social&label=Follow)](https://twitter.com/veramolabs)
 [![codecov](https://codecov.io/gh/decentralized-identity/did-jwt/branch/master/graph/badge.svg)](https://codecov.io/gh/decentralized-identity/did-jwt)
 
 # did-jwt
@@ -14,7 +14,7 @@ identity of the token, which is passed as the `iss` attribute of the JWT payload
 
 ## DID methods
 
-All DID methods that can be resolved using the [`did-resolver'](https://github.com/decentralized-identity/did-resolver)
+All DID methods that can be resolved using the [`did-resolver`](https://github.com/decentralized-identity/did-resolver)
 interface are supported for verification.
 
 If your DID method requires a different signing algorithm than what is already supported, please create an issue.
@@ -35,15 +35,16 @@ yarn add did-jwt
 
 ### 1. Create a did-JWT
 
-In practice, you must secure the key passed to ES256KSigner. The key provided in code below is for informational
+In practice, you must secure the key passed to `ES256KSigner`. The key provided in code below is for informational
 purposes only.
 
-```js
-const didJWT = require('did-jwt')
+```ts
+import didJWT from 'did-jwt';
+
 const signer = didJWT.ES256KSigner(didJWT.hexToBytes('278a5de700e29faae8e40e366ec5012b5ec63d36ec77e8a2417154cc1d25383f'))
 
 let jwt = await didJWT.createJWT(
-  { aud: 'did:ethr:0xf3beac30c498d9e26865f34fcaa57dbb935b0d74', exp: 1957463421, name: 'uPort Developer' },
+  { aud: 'did:ethr:0xf3beac30c498d9e26865f34fcaa57dbb935b0d74', iat: undefined, name: 'uPort Developer' },
   { issuer: 'did:ethr:0xf3beac30c498d9e26865f34fcaa57dbb935b0d74', signer },
   { alg: 'ES256K' }
 )
@@ -62,19 +63,17 @@ console.log(decoded)
 
 Once decoded a did-JWT will resemble:
 
-```js
-{
-  header: { typ: 'JWT', alg: 'ES256K' },
+```ts
+expect(decoded).toEqual({
+  header: { alg: 'ES256K', typ: 'JWT' },
   payload: {
-    iat: 1571692233,
-    exp: 1957463421,
     aud: 'did:ethr:0xf3beac30c498d9e26865f34fcaa57dbb935b0d74',
     name: 'uPort Developer',
     iss: 'did:ethr:0xf3beac30c498d9e26865f34fcaa57dbb935b0d74'
   },
-  signature: 'kkSmdNE9Xbiql_KCg3IptuJotm08pSEeCOICBCN_4YcgyzFc4wIfBdDQcz76eE-z7xUR3IBb6-r-lRfSJcHMiAA',
-  data: 'eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NkstUiJ9.eyJpYXQiOjE1NzE2OTIyMzMsImV4cCI6MTk1NzQ2MzQyMSwiYXVkIjoiZGlkOmV0aHI6MHhmM2JlYWMzMGM0OThkOWUyNjg2NWYzNGZjYWE1N2RiYjkzNWIwZDc0IiwibmFtZSI6InVQb3J0IERldmVsb3BlciIsImlzcyI6ImRpZDpldGhyOjB4ZjNiZWFjMzBjNDk4ZDllMjY4NjVmMzRmY2FhNTdkYmI5MzViMGQ3NCJ9'
-}
+  signature: 'mAhpAnw-9u57hyAaDufj2GPMbmuZyPDlU7aYSUMKk7P_9_cF3iLk-hFjFhb5xaUQB5nXYrciw6ZJ2RSAZI-IDQ',
+  data: 'eyJhbGciOiJFUzI1NksiLCJ0eXAiOiJKV1QifQ.eyJhdWQiOiJkaWQ6ZXRocjoweGYzYmVhYzMwYzQ5OGQ5ZTI2ODY1ZjM0ZmNhYTU3ZGJiOTM1YjBkNzQiLCJuYW1lIjoidVBvcnQgRGV2ZWxvcGVyIiwiaXNzIjoiZGlkOmV0aHI6MHhmM2JlYWMzMGM0OThkOWUyNjg2NWYzNGZjYWE1N2RiYjkzNWIwZDc0In0'
+})
 ```
 
 ### 3. Verify a did-JWT
@@ -88,14 +87,14 @@ npm install ethr-did-resolver
 ```
 
 ```js
-const Resolver = require('did-resolver')
-const ethrDid = require('ethr-did-resolver').getResolver({ rpcUrl: 'https://mainnet.infura.io/v3/...' })
+import {Resolver} from 'did-resolver';
+import {getResolver} from 'ethr-did-resolver'
 
-let resolver = new Resolver.Resolver(ethrDid)
+let resolver = new Resolver({...getResolver({infuraProjectId: '<get a free ID from infura.io>'})});
 
-// pass the JWT from step 1
+// use the JWT from step 1
 let verificationResponse = await didJWT.verifyJWT(jwt, {
-  resolver: resolver,
+  resolver,
   audience: 'did:ethr:0xf3beac30c498d9e26865f34fcaa57dbb935b0d74'
 })
 console.log(verificationResponse)
@@ -104,31 +103,44 @@ console.log(verificationResponse)
 A verification response is an object resembling:
 
 ```typescript
-{
+expect(verificationResponse).toEqual({
   payload: {
-    iat: 1571692448,
-    exp: 1957463421,
     aud: 'did:ethr:0xf3beac30c498d9e26865f34fcaa57dbb935b0d74',
     name: 'uPort Developer',
     iss: 'did:ethr:0xf3beac30c498d9e26865f34fcaa57dbb935b0d74'
   },
   didResolutionResult: {
     didDocumentMetadata: {},
-    didResolutionMetadata: {},
+    didResolutionMetadata: { contentType: 'application/did+ld+json' },
     didDocument: {
-      '@context': 'https://w3id.org/did/v1',
+      '@context': [
+        'https://www.w3.org/ns/did/v1',
+        'https://w3id.org/security/suites/secp256k1recovery-2020/v2'
+      ],
       id: 'did:ethr:0xf3beac30c498d9e26865f34fcaa57dbb935b0d74',
-      publicKey: [ [Object] ],
-      authentication: [ [Object] ]
+      verificationMethod: [
+        {
+          id: 'did:ethr:0xf3beac30c498d9e26865f34fcaa57dbb935b0d74#controller',
+          type: 'EcdsaSecp256k1RecoveryMethod2020',
+          controller: 'did:ethr:0xf3beac30c498d9e26865f34fcaa57dbb935b0d74',
+          blockchainAccountId: 'eip155:1:0xF3beAC30C498D9E26865F34fCAa57dBB935b0D74'
+        }
+      ],
+      authentication: [
+        'did:ethr:0xf3beac30c498d9e26865f34fcaa57dbb935b0d74#controller'
+      ],
+      assertionMethod: [
+        'did:ethr:0xf3beac30c498d9e26865f34fcaa57dbb935b0d74#controller'
+      ]
     }
   },
   issuer: 'did:ethr:0xf3beac30c498d9e26865f34fcaa57dbb935b0d74',
   signer: {
-    id: 'did:ethr:0xf3beac30c498d9e26865f34fcaa57dbb935b0d74#owner',
-    type: 'Secp256k1VerificationKey2018',
-    owner: 'did:ethr:0xf3beac30c498d9e26865f34fcaa57dbb935b0d74',
-    ethereumAddress: '0xf3beac30c498d9e26865f34fcaa57dbb935b0d74'
+    id: 'did:ethr:0xf3beac30c498d9e26865f34fcaa57dbb935b0d74#controller',
+    type: 'EcdsaSecp256k1RecoveryMethod2020',
+    controller: 'did:ethr:0xf3beac30c498d9e26865f34fcaa57dbb935b0d74',
+    blockchainAccountId: 'eip155:1:0xF3beAC30C498D9E26865F34fCAa57dBB935b0D74'
   },
-  jwt: 'eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NkstUiJ9.eyJpYXQiOjE1NzE2OTI0NDgsImV4cCI6MTk1NzQ2MzQyMSwiYXVkIjoiZGlkOmV0aHI6MHhmM2JlYWMzMGM0OThkOWUyNjg2NWYzNGZjYWE1N2RiYjkzNWIwZDc0IiwibmFtZSI6InVQb3J0IERldmVsb3BlciIsImlzcyI6ImRpZDpldGhyOjB4ZjNiZWFjMzBjNDk4ZDllMjY4NjVmMzRmY2FhNTdkYmI5MzViMGQ3NCJ9.xd_CSWukS6rK8y7GVvyH_c5yRsDXojM6BuKaf1ZMg0fsgpSBioS7jBfyk4ZZvS0iuFu4u4_771_PNWvmsvaZQQE'
-}
+  jwt: 'eyJhbGciOiJFUzI1NksiLCJ0eXAiOiJKV1QifQ.eyJhdWQiOiJkaWQ6ZXRocjoweGYzYmVhYzMwYzQ5OGQ5ZTI2ODY1ZjM0ZmNhYTU3ZGJiOTM1YjBkNzQiLCJuYW1lIjoidVBvcnQgRGV2ZWxvcGVyIiwiaXNzIjoiZGlkOmV0aHI6MHhmM2JlYWMzMGM0OThkOWUyNjg2NWYzNGZjYWE1N2RiYjkzNWIwZDc0In0.mAhpAnw-9u57hyAaDufj2GPMbmuZyPDlU7aYSUMKk7P_9_cF3iLk-hFjFhb5xaUQB5nXYrciw6ZJ2RSAZI-IDQ'
+})
 ```

src/Errors.ts

@@ -0,0 +1,39 @@
+/**
+ * Error prefixes used for known verification failure cases.
+ *
+ * For compatibility, these error prefixes match the existing error messages, but will be adjusted in a future major
+ * version update to match the scenarios better.
+ *
+ * @beta
+ */
+export const enum JWT_ERROR {
+  /**
+   * Thrown when a JWT payload schema is unexpected or when validity period does not match
+   */
+  INVALID_JWT = 'invalid_jwt',
+  /**
+   * Thrown when the verifier audience does not match the one set in the JWT payload
+   */
+  INVALID_AUDIENCE = 'invalid_config',
+  /**
+   * Thrown when none of the public keys of the issuer match the signature of the JWT.
+   *
+   * This is equivalent to `NO_SUITABLE_KEYS` when the `proofPurpose` is NOT specified.
+   */
+  INVALID_SIGNATURE = 'invalid_signature',
+  /**
+   * Thrown when the DID document of the issuer does not have any keys that match the signature for the given
+   * `proofPurpose`.
+   *
+   * This is equivalent to `invalid_signature`, when a `proofPurpose` is specified.
+   */
+  NO_SUITABLE_KEYS = 'no_suitable_keys',
+  /**
+   * Thrown when the `alg` of the JWT or the encoding of the key is not supported
+   */
+  NOT_SUPPORTED = 'not_supported',
+  /**
+   * Thrown when the DID resolver is unable to resolve the issuer DID.
+   */
+  RESOLVER_ERROR = 'resolver_error',
+}