feat: add records validator (#5)

* feat: add records validator

Author: vasco-santos

.gitignore

@@ -1,4 +1,5 @@
 dist/
+docs/
 
 # Logs
 logs

README.md

@@ -112,6 +112,20 @@ const data = ipns.unmarshal(storedData)
 
 Returns the entry data structure after being serialized.
 
+#### Validator
+
+```js
+const ipns = require('ipns')
+
+const validator = ipns.validator
+```
+
+Contains an object with `validate (marshalledData, peerId, callback)` and `select (dataA, dataB, callback)` functions.
+
+The `validate` function aims to verify if an IPNS record is valid. First the record is unmarshalled, then the public key is obtained and finally the record is validated (signature and validity are verified).
+
+The `select` function is responsible for deciding which ipns record is the best (newer) between two records. Both records are unmarshalled and their sequence numbers are compared. If the first record provided is the newer, the operation result will be `0`, otherwise the operation result will be `1`.
+
 ## API
 
 #### Create record

src/index.js

@@ -258,6 +258,38 @@ const extractPublicKeyFromId = (peerId) => {
   return crypto.keys.unmarshalPublicKey(decodedId.digest)
 }
 
+const marshal = ipnsEntryProto.encode
+
+const unmarshal = ipnsEntryProto.decode
+
+const validator = {
+  validate: (marshalledData, peerId, callback) => {
+    const receivedEntry = unmarshal(marshalledData)
+
+    // extract public key
+    extractPublicKey(peerId, receivedEntry, (err, pubKey) => {
+      if (err) {
+        return callback(err)
+      }
+
+      // Record validation
+      validate(pubKey, receivedEntry, (err) => {
+        if (err) {
+          return callback(err)
+        }
+
+        callback(null, true)
+      })
+    })
+  },
+  select: (dataA, dataB, callback) => {
+    const entryA = unmarshal(dataA)
+    const entryB = unmarshal(dataB)
+
+    callback(null, entryA.sequence > entryB.sequence ? 0 : 1)
+  }
+}
+
 module.exports = {
   // create ipns entry record
   create,
@@ -272,7 +304,9 @@ module.exports = {
   // get keys for routing
   getIdKeys,
   // marshal
-  marshal: ipnsEntryProto.encode,
+  marshal,
   // unmarshal
-  unmarshal: ipnsEntryProto.decode
+  unmarshal,
+  // validator
+  validator
 }

test/index.spec.js

@@ -236,4 +236,91 @@ describe('ipns', function () {
       })
     })
   })
+
+  it('should use validator.validate to validate a record', (done) => {
+    const sequence = 0
+    const validity = 1000000
+
+    ipns.create(rsa, cid, sequence, validity, (err, entry) => {
+      expect(err).to.not.exist()
+
+      ipns.embedPublicKey(rsa.public, entry, (err, entry) => {
+        expect(err).to.not.exist()
+
+        const marshalledData = ipns.marshal(entry)
+
+        ipns.validator.validate(marshalledData, ipfsId, (err, valid) => {
+          expect(err).to.not.exist()
+          expect(valid).to.equal(true)
+          done()
+        })
+      })
+    })
+  })
+
+  it('should use validator.validate to verify that a record is not valid', (done) => {
+    const sequence = 0
+    const validity = 1000000
+
+    ipns.create(rsa, cid, sequence, validity, (err, entry) => {
+      expect(err).to.not.exist()
+
+      ipns.embedPublicKey(rsa.public, entry, (err, entry) => {
+        expect(err).to.not.exist()
+
+        // corrupt the record by changing the value to random bytes
+        entry.value = crypto.randomBytes(46).toString()
+        const marshalledData = ipns.marshal(entry)
+
+        ipns.validator.validate(marshalledData, ipfsId, (err) => {
+          expect(err).to.exist() // failed validation
+          done()
+        })
+      })
+    })
+  })
+
+  it('should use validator.select to select the first record because it is newer', (done) => {
+    const sequence = 0
+    const validity = 1000000
+
+    ipns.create(rsa, cid, sequence, validity, (err, entry) => {
+      expect(err).to.not.exist()
+
+      ipns.create(rsa, cid, (sequence + 1), validity, (err, newEntry) => {
+        expect(err).to.not.exist()
+
+        const marshalledData = ipns.marshal(entry)
+        const marshalledNewData = ipns.marshal(newEntry)
+
+        ipns.validator.select(marshalledNewData, marshalledData, (err, valid) => {
+          expect(err).to.not.exist()
+          expect(valid).to.equal(0) // new data is the selected one
+          done()
+        })
+      })
+    })
+  })
+
+  it('should use validator.select to select the second record because it is newer', (done) => {
+    const sequence = 0
+    const validity = 1000000
+
+    ipns.create(rsa, cid, sequence + 1, validity, (err, entry) => {
+      expect(err).to.not.exist()
+
+      ipns.create(rsa, cid, (sequence), validity, (err, newEntry) => {
+        expect(err).to.not.exist()
+
+        const marshalledData = ipns.marshal(entry)
+        const marshalledNewData = ipns.marshal(newEntry)
+
+        ipns.validator.select(marshalledNewData, marshalledData, (err, valid) => {
+          expect(err).to.not.exist()
+          expect(valid).to.equal(1) // old data is the selected one
+          done()
+        })
+      })
+    })
+  })
 })