Skip to content
This repository was archived by the owner on Mar 8, 2024. It is now read-only.

Commit 1ac5f41

Browse files
authored
README docs for how to use V.PayID related functions. (#45)
Added a helper function for generating a new EC key.
1 parent 66f4879 commit 1ac5f41

File tree

3 files changed

+98
-7
lines changed

3 files changed

+98
-7
lines changed

README.md

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,87 @@ splitPayIdString(payId)
4747
// Returns ['alice', 'example.com']
4848
```
4949

50+
## V.PayID
51+
52+
The [V.PayID RFC](https://github.com/payid-org/rfcs/blob/master/src/spec/self-sov-verifiable-payid-protocol.md]) defines
53+
a method for signing and verifying PayID address mappings using cryptographic keys. The utils library provides several
54+
functions related to V.PayID.
55+
56+
### `generateNewKey()`
57+
58+
Generates a new elliptic curve key in JWK format.
59+
60+
### `sign(key, address, signingParameters)`
61+
62+
Signs an address mapping using the provided key and signing parameters and returns a verified address object in
63+
JWS format.
64+
65+
### `verify(paymentInfo)`
66+
67+
Verifies the signatures on `verifiedAddresses` in the provided `paymentInfo' object. Returns true if signatures
68+
are valid, false if any are invalid.
69+
70+
### `verifySignedAddress(payId, verifiedAddress)`
71+
72+
Verifies that the signature on a specific `verifiedAddress` matches its PayID and embedded public key.
73+
74+
### `getJwkFromRecipient(signer)`
75+
76+
Gets the public JWK from a JWS recipient/signer on a verified address.
77+
78+
#### V.PayID Example
79+
80+
The following shows a complete example of using the utils library to generate a key, sign an address mapping
81+
and construct a payment info object containing the verified/signed address, and lastly verifying the signature
82+
of a signed PayId address.
83+
84+
```ts
85+
import * as utils from '@payid-org/utils'
86+
87+
const payId = 'alice$payid.example'
88+
const address = {
89+
environment: 'TESTNET',
90+
paymentNetwork: 'XRPL',
91+
addressDetailsType: {
92+
address: 'rP3t3JStqWPYd8H88WfBYh3v84qqYzbHQ6',
93+
},
94+
}
95+
96+
// create a signing key
97+
const key = await utils.generateNewKey()
98+
99+
const signingParameters = new utils.IdentityKeySigningParams(
100+
key,
101+
utils.getDefaultAlgorithm(key),
102+
)
103+
104+
// generate a signed/verified address using the signing key
105+
const verifiedAddress = utils.sign(payId, address, signingParameters)
106+
107+
// build a PaymentInfo containing a verified address
108+
const paymentInfo = {
109+
payId,
110+
verifiedAddresses: [verifiedAddress],
111+
}
112+
113+
// pretty print the JSON representation.
114+
// this is what the PayID server should return for PayID lookups.
115+
console.log(JSON.stringify(paymentInfo, null, 2))
116+
117+
// verify signatures on all the verifiedAddresses in a PaymentInfo object.
118+
utils.verifyPayId(paymentInfo)
119+
120+
// verify a specific verifiedAddress
121+
utils.verifySignedAddress(payId, paymentInfo.verifiedAddresses[0])
122+
123+
// inspect the PaymentInfo for detail information on signatures
124+
const inspector = new utils.PaymentInformationInspector()
125+
inspector.inspect(paymentInfo)
126+
127+
// extract the public key for the first signature of the first verified address
128+
utils.getJwkFromRecipient(paymentInfo.verifiedAddresses[0].signatures[0])
129+
```
130+
50131
## Legal
51132

52133
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

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@ import OKPKey = JWK.OKPKey
88
import OctKey = JWK.OctKey
99
import JWSRecipient = JWS.JWSRecipient
1010

11+
const DEFAULT_CURVE = 'P-256'
12+
1113
/**
1214
* Reads JWK key from a file.
1315
*
@@ -102,3 +104,12 @@ export function getDefaultAlgorithm(
102104
}
103105
return 'RS512'
104106
}
107+
108+
/**
109+
* Generates an new JWK key that can be used for V.PayID.
110+
*
111+
* @returns A JWK key.
112+
*/
113+
export async function generateNewKey(): Promise<ECKey> {
114+
return JWK.generate('EC', DEFAULT_CURVE)
115+
}

test/unit/verifiable/signatures.test.ts

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ import 'mocha'
33
import { assert } from 'chai'
44
import { JWK } from 'jose'
55

6-
import { getDefaultAlgorithm } from '../../../src/verifiable'
6+
import { generateNewKey, getDefaultAlgorithm } from '../../../src/verifiable'
77
import IdentityKeySigningParams from '../../../src/verifiable/identity-key-signing-params'
88
import {
99
sign,
@@ -18,7 +18,6 @@ import {
1818
} from '../../../src/verifiable/verifiable-payid'
1919

2020
describe('sign()', function () {
21-
const curve = 'P-256'
2221
const payId = 'alice$payid.example'
2322
const xrpAddress = 'rP3t3JStqWPYd8H88WfBYh3v84qqYzbHQ6'
2423
const addressDetails: CryptoAddressDetails = {
@@ -37,7 +36,7 @@ describe('sign()', function () {
3736
})
3837

3938
it('Signed PayID returns JWS', async function () {
40-
const key = await JWK.generate('EC', curve)
39+
const key = await generateNewKey()
4140
const params = new IdentityKeySigningParams(key, defaultAlgorithm(key))
4241
const jws = sign(payId, address, params)
4342

@@ -50,8 +49,8 @@ describe('sign()', function () {
5049
})
5150

5251
it('signs and verifies with using multiple signatures', async function () {
53-
const identityKey1 = await JWK.generate('EC', curve)
54-
const identityKey2 = await JWK.generate('EC', curve)
52+
const identityKey1 = await generateNewKey()
53+
const identityKey2 = await generateNewKey()
5554
const jws = signWithKeys(payId, address, [
5655
new IdentityKeySigningParams(
5756
identityKey1,
@@ -72,7 +71,7 @@ describe('sign()', function () {
7271
})
7372

7473
it('cannot be verified if payload tampered with', async function () {
75-
const key = await JWK.generate('EC', curve)
74+
const key = await generateNewKey()
7675
const jws = sign(
7776
payId,
7877
address,
@@ -83,7 +82,7 @@ describe('sign()', function () {
8382
})
8483

8584
it('verification fails if payid does not match payload', async function () {
86-
const key = await JWK.generate('EC', curve)
85+
const key = await generateNewKey()
8786
const jws = sign(
8887
payId,
8988
address,

0 commit comments

Comments
 (0)