Merge pull request #46 from vaxxnz/feature/byo_did_documents

Feature/byo did documents

.env.example

@@ -0,0 +1 @@
+LIVE_COVID_PASS_URI=

.gitignore

@@ -9,3 +9,4 @@
 coverage
 *.log
 .npmrc
+.env

README.md

@@ -35,13 +35,24 @@ This library is current used in
 
 ## Usage
 
+### Online
+
 ```javascript
 import { verifyPassURI } from "@vaxxnz/nzcp";
 
-// Verify a New Zealand COVID-19 Pass
+// Verify a live New Zealand COVID-19 Pass, resolving the DID document
 const result = await verifyPassURI("NZCP:/1/2KCEVIQEIVVWK6...");
 ```
 
+### Offline
+
+```javascript
+import { verifyPassURIOffline } from "@vaxxnz/nzcp";
+
+// Verify a live New Zealand COVID-19 Pass, using a prefetched DID document
+const result = verifyPassURIOffline("NZCP:/1/2KCEVIQEIVVWK6...");
+```
+
 ### Successful Verification
 
 On **successful** verification of the given pass, the `verifyPassURI` method returns the following result:
@@ -74,25 +85,68 @@ On **unsuccessful** verification of the given pass, the `verifyPassURI` method r
 }
 ```
 
-### Advanced Parameters
 
-To allow for flexibility in this library, `verifyPassURIWithTrustedIssuers` method allows for additional parameters as documented below.
+### Advanced Usage
+
+These examples show how to configure the library to supply your own trusted issuers or DID documents. This will allow you to use the library with the [example COVID Passes from the spec](https://nzcp.covid19.health.nz/#valid-worked-example).
 
-#### Custom Trusted Issuers
+
+The following example shows how to use the example trusted issuer for online verification:
 
 ```javascript
-import { verifyPassURIWithTrustedIssuers } from "@vaxxnz/nzcp";
+import { verifyPassURI, TRUSTED_ISSUERS } from "@vaxxnz/nzcp";
+
+// Trusted issuer for the example COVID Passes
+// "did:web:nzcp.covid19.health.nz"
+const exampleTrustedIssuer = TRUSTED_ISSUERS.MOH_EXAMPLE;
 
-// An array of trusted issuers which work with the NZ COVID Pass - Technical Specification
-// https://nzcp.covid19.health.nz/
-const nzcpTrustedIssuers = ["did:web:nzcp.covid19.health.nz"];
+// Alternatively you could supply a trusted issuer for live COVID Passes
+// If you omit the trusted issuer, the library will use the live DID document
+// "did:web:nzcp.identity.health.nz"
+const liveTrustedIssuer = TRUSTED_ISSUERS.MOH_LIVE;
 
-const result = await verifyPassURIWithTrustedIssuers(
-  "NZCP:/1/2KCEVIQEIVVWK6...", // COVID-19 Pass to be verified
-  nzcpTrustedIssuers // Array of trusted issuers
+const result = await verifyPassURI(
+  "NZCP:/1/2KCEVIQEIVVWK6...",            // COVID-19 Pass to be verified
+  { trustedIssuer: exampleTrustedIssuer } // Supply your own trusted issuer to overwrite the default
 );
 ```
 
+The following example shows how use the example DID document for offline verification:
+
+```javascript
+import { verifyPassURIOffline, DID_DOCUMENTS } from "@vaxxnz/nzcp";
+
+// DID Document for the example COVID Passes
+// Prefetched version of https://nzcp.covid19.health.nz/.well-known/did.json
+const exampleDIDDocument = DID_DOCUMENTS.MOH_EXAMPLE;
+
+// Alternatively you could supply a DID document for live COVID Passes
+// If you omit the DID Document, the library will use the live DID document
+// Prefetched version of https://nzcp.identity.health.nz/.well-known/did.json
+const liveTrustedIssuer = DID_DOCUMENTS.MOH_LIVE;
+
+const result = verifyPassURIOffline(
+  "NZCP:/1/2KCEVIQEIVVWK6...",          // COVID-19 Pass to be verified
+  { didDocument: exampleDIDDocument }   // Supply your own DID document to overwrite the default
+);
+```
+
+## Online VS Offline
+
+Currently for a Node.js/React Native project we recomend using `verifyPassURI` and for a browser based application to use `verifyPassURIOffline`.
+
+The difference between the `verifyPassURI` and `verifyPassURIOffline` interfaces is:
+ - `verifyPassURI`: This will resolve the DID document (which contains the Ministry of Health public key) from the web according to https://nzcp.covid19.health.nz/#ref:DID-CORE and then validate the DID document is from the MoH trusted issuer.
+ - `verifyPassURIOffline`: This will use a prefetched version of https://nzcp.identity.health.nz/.well-known/did.json to verify against
+
+There is a CORS policy on https://nzcp.identity.health.nz/.well-known/did.json which makes it currently unable to be fetched from the browser. The only option for browser based verifiers is currently to use the `verifyPassURIOffline` function. The Ministry Of Health is aware of this issue and is working to resolve it.
+
+Offline scanners or scanners opperating in poor network conditions will also need to use `verifyPassURIOffline`. Since `verifyPassURI` requires an Internet connection to resolve the DID document.
+
+NZCP.js has decided to support both use cases but which one to use is a decision that the user of this library is in the best position to make. If you have a network connection and want to be completely correct (and to specification) use `verifyPassURI`. If you want speed, don't have a network connection or don't mind using a prefetched DID document, use `verifyPassURIOffline`.
+
+If you want to supply your own trusted issuer or DID document parameters, you can follow the Advanced Usage guide above.
+
 ## Support
 
 See something that can be improved? [Report an Issue](https://github.com/vaxxnz/nzcp-js/issues) or contact us to [report a security concern](mailto:[email protected]).
@@ -115,7 +169,10 @@ yarn install
 ```bash
 # Use developer scripts
 yarn lint
-yarn test
-yarn test-watch
 yarn build-all
 ```
+
+## Run tests
+- Create `.env` in the root directory of the project
+  - see `.env.example` for an example.
+- Run `yarn test` or `yarn test-watch`

package.json

@@ -2,7 +2,10 @@
   "name": "@vaxxnz/nzcp",
   "version": "0.1.5",
   "description": "A JavaScript implementation of the NZ COVID Pass verification",
-  "contributors": ["Will Seagar <[email protected]>", "Ilia Sidorenko <[email protected]>"],
+  "contributors": [
+    "Will Seagar <[email protected]>",
+    "Ilia Sidorenko <[email protected]>"
+  ],
   "repository": "git://github.com/vaxxnz/nzcp-js.git",
   "license": "MIT",
   "keywords": [
@@ -40,6 +43,7 @@
     "@typescript-eslint/parser": "^4.19.0",
     "cbor": "^8.1.0",
     "did-resolver": "^3.1.3",
+    "dotenv": "^10.0.0",
     "elliptic": "^6.5.4",
     "esbuild": "^0.11.11",
     "esbuild-node-builtins": "^0.1.0",

src/browser.ts

@@ -2,5 +2,5 @@
  * This file is the entrypoint of browser builds.
  * The code executes when loaded in a browser.
  */
-import { verifyPassURI, verifyPassURIWithTrustedIssuers } from "./main";
-export { verifyPassURI, verifyPassURIWithTrustedIssuers };
+import { verifyPassURI, verifyPassURIOffline, DID_DOCUMENTS, TRUSTED_ISSUERS } from "./main";
+export { verifyPassURI, verifyPassURIOffline, DID_DOCUMENTS, TRUSTED_ISSUERS };