README docs for how to use V.PayID related functions. (#45)

Added a helper function for generating a new EC key.

Author: nhartner

README.md

@@ -47,6 +47,87 @@ splitPayIdString(payId)
 // Returns ['alice', 'example.com']
 ```
 
+## V.PayID
+
+The [V.PayID RFC](https://github.com/payid-org/rfcs/blob/master/src/spec/self-sov-verifiable-payid-protocol.md]) defines
+a method for signing and verifying PayID address mappings using cryptographic keys. The utils library provides several
+functions related to V.PayID.
+
+### `generateNewKey()`
+
+Generates a new elliptic curve key in JWK format.
+
+### `sign(key, address, signingParameters)`
+
+Signs an address mapping using the provided key and signing parameters and returns a verified address object in
+JWS format.
+
+### `verify(paymentInfo)`
+
+Verifies the signatures on `verifiedAddresses` in the provided `paymentInfo' object. Returns true if signatures
+are valid, false if any are invalid.
+
+### `verifySignedAddress(payId, verifiedAddress)`
+
+Verifies that the signature on a specific `verifiedAddress` matches its PayID and embedded public key.
+
+### `getJwkFromRecipient(signer)`
+
+Gets the public JWK from a JWS recipient/signer on a verified address.
+
+#### V.PayID Example
+
+The following shows a complete example of using the utils library to generate a key, sign an address mapping
+and construct a payment info object containing the verified/signed address, and lastly verifying the signature
+of a signed PayId address.
+
+```ts
+import * as utils from '@payid-org/utils'
+
+const payId = 'alice$payid.example'
+const address = {
+  environment: 'TESTNET',
+  paymentNetwork: 'XRPL',
+  addressDetailsType: {
+    address: 'rP3t3JStqWPYd8H88WfBYh3v84qqYzbHQ6',
+  },
+}
+
+// create a signing key
+const key = await utils.generateNewKey()
+
+const signingParameters = new utils.IdentityKeySigningParams(
+  key,
+  utils.getDefaultAlgorithm(key),
+)
+
+// generate a signed/verified address using the signing key
+const verifiedAddress = utils.sign(payId, address, signingParameters)
+
+// build a PaymentInfo containing a verified address
+const paymentInfo = {
+  payId,
+  verifiedAddresses: [verifiedAddress],
+}
+
+// pretty print the JSON representation.
+// this is what the PayID server should return for PayID lookups.
+console.log(JSON.stringify(paymentInfo, null, 2))
+
+// verify signatures on all the verifiedAddresses in a PaymentInfo object.
+utils.verifyPayId(paymentInfo)
+
+// verify a specific verifiedAddress
+utils.verifySignedAddress(payId, paymentInfo.verifiedAddresses[0])
+
+// inspect the PaymentInfo for detail information on signatures
+const inspector = new utils.PaymentInformationInspector()
+inspector.inspect(paymentInfo)
+
+// extract the public key for the first signature of the first verified address
+utils.getJwkFromRecipient(paymentInfo.verifiedAddresses[0].signatures[0])
+```
+
 ## Legal
 
 By using, reproducing, or distributing this code, you agree to the terms and conditions for use (including the Limitation of Liability) in the [Apache License 2.0](https://github.com/payid-org/payid/blob/master/LICENSE). If you do not agree, you may not use, reproduce, or distribute the code. **This code is not authorised for download in Australia. Any persons located in Australia are expressly prohibited from downloading, using, reproducing or distributing the code.** This code is not owned by, or associated with, NPP Australia Limited, and has no sponsorship, affiliation or other connection with the “Pay ID” service operated by NPP Australia Limited in Australia.

src/verifiable/keys.ts

@@ -8,6 +8,8 @@ import OKPKey = JWK.OKPKey
 import OctKey = JWK.OctKey
 import JWSRecipient = JWS.JWSRecipient
 
+const DEFAULT_CURVE = 'P-256'
+
 /**
  * Reads JWK key from a file.
  *
@@ -102,3 +104,12 @@ export function getDefaultAlgorithm(
   }
   return 'RS512'
 }
+
+/**
+ * Generates an new JWK key that can be used for V.PayID.
+ *
+ * @returns A JWK key.
+ */
+export async function generateNewKey(): Promise<ECKey> {
+  return JWK.generate('EC', DEFAULT_CURVE)
+}

test/unit/verifiable/signatures.test.ts

@@ -3,7 +3,7 @@ import 'mocha'
 import { assert } from 'chai'
 import { JWK } from 'jose'
 
-import { getDefaultAlgorithm } from '../../../src/verifiable'
+import { generateNewKey, getDefaultAlgorithm } from '../../../src/verifiable'
 import IdentityKeySigningParams from '../../../src/verifiable/identity-key-signing-params'
 import {
   sign,
@@ -18,7 +18,6 @@ import {
 } from '../../../src/verifiable/verifiable-payid'
 
 describe('sign()', function () {
-  const curve = 'P-256'
   const payId = 'alice$payid.example'
   const xrpAddress = 'rP3t3JStqWPYd8H88WfBYh3v84qqYzbHQ6'
   const addressDetails: CryptoAddressDetails = {
@@ -37,7 +36,7 @@ describe('sign()', function () {
   })
 
   it('Signed PayID returns JWS', async function () {
-    const key = await JWK.generate('EC', curve)
+    const key = await generateNewKey()
     const params = new IdentityKeySigningParams(key, defaultAlgorithm(key))
     const jws = sign(payId, address, params)
 
@@ -50,8 +49,8 @@ describe('sign()', function () {
   })
 
   it('signs and verifies with using multiple signatures', async function () {
-    const identityKey1 = await JWK.generate('EC', curve)
-    const identityKey2 = await JWK.generate('EC', curve)
+    const identityKey1 = await generateNewKey()
+    const identityKey2 = await generateNewKey()
     const jws = signWithKeys(payId, address, [
       new IdentityKeySigningParams(
         identityKey1,
@@ -72,7 +71,7 @@ describe('sign()', function () {
   })
 
   it('cannot be verified if payload tampered with', async function () {
-    const key = await JWK.generate('EC', curve)
+    const key = await generateNewKey()
     const jws = sign(
       payId,
       address,
@@ -83,7 +82,7 @@ describe('sign()', function () {
   })
 
   it('verification fails if payid does not match payload', async function () {
-    const key = await JWK.generate('EC', curve)
+    const key = await generateNewKey()
     const jws = sign(
       payId,
       address,