@atomicfinance/types 3.6.1 → 4.0.1

package/.yalc/@node-dlc/noise/README.md

@@ -0,0 +1,165 @@
+# Lightning Network Noise Protocol Socket (BOLT #8)
+
+[![CircleCI](https://circleci.com/gh/atomicfinance/node-dlc/tree/master.svg?style=shield)](https://circleci.com/gh/atomicfinance/node-dlc/tree/master)
+[![codecov](https://codecov.io/gh/atomicfinance/node-dlc/branch/master/graph/badge.svg)](https://codecov.io/gh/atomicfinance/node-dlc)
+
+Implements a Noise Protocol TCP Socket and Server in Node.js as defined in Lightning Network BOLT #8 for Encrypted and Authenticated Transport.
+
+`NoiseSocket` enables confidentiality between two nodes by encrypting all traffic between them. All traffic is also authenticated against the node's known long-term identifier (Bitcoin public key as curve secp256k1).
+
+`NoiseSocket` performs a cryptographic handshake upon connection and performs frequent key rotation. Once the handshake is complete, the `ready` event signals that messages can be sent or received.
+
+`NoiseSocket` is a decorator for `net.Socket`. It maintains the same interface used by `net.Socket` and implements a `Duplex` stream. This enables reading from the stream in paused (`readable` event) or flowing mode (piped or `data` event).
+
+Learn more about the Noise Protocol and the Lighting Network version:
+
+- [Noise Protocol](http://noiseprotocol.org/)
+- [Lightning Network BOLT #8](https://github.com/lightningnetwork/lightning-rfc/blob/master/08-transport.md)
+
+## Requirements
+
+- Node.js 18+
+
+## Usage
+
+### Creating a NoiseSocket Client
+
+This example shows how to create a `NoiseSocket` that connects to a `NoiseServer`.
+
+To create a `NoiseSocket`, you must provide:
+
+- local private key `ls` which is a `Buffer` with 32-bytes
+- remote node's compressed public key `rp` which is a `Buffer` with 33-bytes.
+
+These two values are required to create the encrypted and authenticated communication channel.
+
+```javascript
+const noise = require('@node-dlc/noise');
+
+// ls is private key as a Buffer(32) defining a point on elliptic
+// curve secp256k1
+const ls = Buffer.from(
+  '1111111111111111111111111111111111111111111111111111111111111111',
+  'hex',
+);
+
+// rpk is compressed public key as a Buffer(33) defining a point
+// on elliptic curve secp256k1
+const rpk = Buffer.from(
+  '028d7500dd4c12685d1f568b4c2b5048e8534b873319f3a8daa612b469132ec7f7',
+  'hex',
+);
+
+// Create a new `NoiseSocket` instance using the `connect` factory
+const socket = noise.connect({ ls, rpk, host: '127.0.0.1', port: 9735 });
+
+// Socket will emit the `connect` event when the TCP connection is
+// established, however the socket is not yet ready because the
+// handshake has not be completed
+socket.on('connect', () => {
+  console.log('connected to server');
+});
+
+// Socket will emit the `ready` event once the handshake is completed.
+// The socket is now ready for sending and receiving messages!
+socket.on('ready', () => {
+  console.log('handshake complete, ready for sending/receiving');
+
+  // Send a message
+  socket.write(Buffer.from('hello from client'));
+});
+
+// Attaching a `data` event will put the socket into flowing mode and will
+// process messages as soon as they arrive.
+socket.on('data', (buf) => {
+  console.log('received: ' + buf.toString());
+});
+```
+
+### Creating a NoiseSocket Server:
+
+```javascript
+const noise = require('@node-dlc/noise');
+
+// ls is private key as a Buffer(32) defining a point on elliptic
+// curve secp256k1
+const ls = Buffer.from('2121212121212121212121212121212121212121212121212121212121212121', 'hex');
+
+// Create a server bound to our local secret. New connections will be
+// handled by the onSocket function.
+const server = noise.createServer({ ls }, onSocket);
+
+// Start the server listening on port 9735.
+server.listen({ host: '127.0.0.1', port: 9735 });
+
+// Handle when a remote socket connects to the server. The socket
+// will be connected, but is not ready for use until the `ready`
+// event is emitted. `socket` is an instance of `NoiseSocket`.
+function onSocket(socket) {
+  console.log('remote socket connected');
+
+  // Socket will emit the `ready` event once the handshake is completed.
+  // The socket is now ready for sending and receiving messages!
+  socket.on('ready', () => {
+    console.log('handshake complete, ready for sending/receiving');
+
+    // Send a message
+    socket.write(Buffer.from('hello from server'));
+  });
+
+  // Attaching a `data` event will put the socket into flowing mode and
+  // will process messages as soon as they arrive.
+  socket.on('data', buf => {
+    console.log('received: ' + buf.toString());
+  });
+});
+```
+
+### Reading Modes
+
+Because Noisesocket is a `Duplex` stream and fully implements `Readable` functionality, it allows reading from the stream via both reading modes: flowing and paused.
+
+Flowing mode is the recommended technique for consuming data and can be achieved by using the `data` event or piping the NoiseSocket to another stream.
+
+The `data` event method reads data as soon as it comes in:
+
+```javascript
+socket.on('data', (buf) => {
+  /* do stuff with the buffer */
+});
+```
+
+You can pipe responses to other streams:
+
+```javascript
+let fs = require('fs');
+let wr = fs.createWriteStream('capture.bin');
+
+// pipe the raw buffer data to some other stream
+socket.pipe(wr);
+```
+
+Lastly, you can use paused mode to manually read from the stream. `readable` events will be emitted when new data is available. This mechanism allows you to directly control how reads occur and is useful
+for implementing wire protocols ontop of the `NoiseSocket`.
+
+```javascript
+socket.on('readable', () => {
+  let buf = socket.read();
+  if (buf) {
+    /* do stuff with the buffer */
+  }
+});
+```
+
+More information about reading modes is available in the Node.js [streams documentation](https://nodejs.org/api/stream.html#stream_two_reading_modes).
+
+### Writing
+
+Writing to the socket can be accomplished by calling `write` and passing in a Buffer.
+
+```javascript
+let d = Buffer.from('some data');
+socket.write(d);
+```
+
+The `write` method will return a boolean value indicating if you can continue to write to the socket. If `write` returns false, you must wait until the `drain` event is emitted before continuing to write data. If you do not respond to to the boolean flag, data will be buffered into memory.

package/.yalc/@node-dlc/noise/__integration__/ping-pong.spec.ts

@@ -0,0 +1,85 @@
+import * as crypto from '@node-dlc/crypto';
+import { expect } from 'chai';
+import sinon from 'sinon';
+import * as noise from '../lib';
+
+// This test creates a server and a client. Once the client has connected
+// to the server, the server will send a message with the body "ping".
+//
+// Once the client recieves the "ping" message it will reply with a "pong"
+// message.
+//
+// This test exercises key the complete connection / handshake process for both
+// client and server and sending and receiving data using the "flowing"
+// stream method by attaching to the "data" event.
+//
+describe('ping-pong integration test', () => {
+  it('should send 1001 messages back and forth without error', (done) => {
+    const server = createServer(complete);
+    const client = createClient(complete);
+
+    // complete will be called when any of the above happens
+    // 1. server has an error
+    // 2. client has an error
+    // 3. client has reached 1001 messages received
+    function complete(err) {
+      server.close();
+      client.end();
+      done(err);
+    }
+  });
+});
+
+function createServer(done) {
+  const ls = Buffer.from("2121212121212121212121212121212121212121212121212121212121212121", "hex"); // prettier-ignore
+  const esFactory = () => Buffer.from("2222222222222222222222222222222222222222222222222222222222222222", "hex"); // prettier-ignore
+
+  // create a server
+  const server = noise.createServer({ ls, esFactory }, (socket) => {
+    // send first message on connect
+    socket.on('connect', () => {
+      socket.write(Buffer.from('ping'));
+    });
+
+    socket.on('data', (data) => {
+      // verify a pong message was sent
+      expect(data.toString()).to.equal('pong');
+
+      // immediately reply with a pong
+      socket.write(Buffer.from('ping'));
+    });
+
+    socket.on('error', done);
+  });
+
+  server.listen({ port: 10000, host: '127.0.0.1' });
+
+  return server;
+}
+
+function createClient(done) {
+  const ls = Buffer.from("1111111111111111111111111111111111111111111111111111111111111111", "hex"); // prettier-ignore
+  const rpk = crypto.getPublicKey(Buffer.from("2121212121212121212121212121212121212121212121212121212121212121", "hex")); // prettier-ignore
+  const es = Buffer.from("1212121212121212121212121212121212121212121212121212121212121212", "hex"); // prettier-ignore
+  let count = 0;
+
+  const socket = noise.connect({ ls, es, rpk, host: '127.0.0.1', port: 10000 });
+
+  socket.on('data', (data) => {
+    if (count > 1000) return; // received reply to last message and socket hasn"t closed yet
+
+    // expect ping
+    expect(data.toString()).to.equal('ping');
+
+    // send pong
+    socket.write(Buffer.from('pong'));
+    count++;
+
+    // close things down if we"ve sent more than 1000 messages
+    if (count > 1000) done();
+  });
+
+  socket.on('error', done);
+
+  return socket;
+}

package/.yalc/@node-dlc/noise/__tests__/noise-server.spec.ts

@@ -0,0 +1,82 @@
+// tslint:disable: no-unused-expression
+import { expect } from 'chai';
+import { NoiseServer } from '../lib/noise-server';
+
+describe('NoiseServer', () => {
+  const ls = Buffer.from("2121212121212121212121212121212121212121212121212121212121212121", "hex"); // prettier-ignore
+
+  describe('constructor', () => {
+    it('should throw if the ephemeralSecretFactory is not a function', () => {
+      expect(() => {
+        new NoiseServer({ ls, esFactory: 1 as any });
+      }).to.throw();
+    });
+
+    it('should bind the error event', (done) => {
+      const sut1 = new NoiseServer({ ls });
+      sut1.listen({ port: 10000, host: '127.0.0.1' });
+      const sut2 = new NoiseServer({ ls });
+      sut2.listen({ port: 10000, host: '127.0.0.1' });
+      sut2.on('error', () => {
+        sut1.close();
+        sut2.close();
+        done();
+      });
+    });
+  });
+
+  describe('.address()', () => {
+    it('should return the address', (done) => {
+      let sut;
+      sut = new NoiseServer({ ls });
+      sut.listen({ port: 10000, host: '127.0.0.1' }, () => {
+        try {
+          const result = sut.address();
+          expect(result.address).to.equal('127.0.0.1');
+          expect(result.family).to.equal('IPv4');
+          expect(result.port).to.equal(10000);
+          done();
+        } finally {
+          sut.close();
+        }
+      });
+    });
+  });
+
+  describe('.listening', () => {
+    it('should return false prior to listening', () => {
+      const sut = new NoiseServer({ ls });
+      expect(sut.listening).to.be.false;
+    });
+    it('should return true once listening', (done) => {
+      let sut;
+      sut = new NoiseServer({ ls });
+      sut.listen({ port: 10000, host: '127.0.0.1' }, () => {
+        try {
+          expect(sut.listening).to.be.true;
+          done();
+        } finally {
+          sut.close();
+        }
+      });
+    });
+  });
+
+  describe('.maxConnections', () => {
+    it('should get / set the maxConnections', () => {
+      const sut = new NoiseServer({ ls });
+      sut.maxConnections = 1;
+      expect(sut.maxConnections).to.equal(1);
+    });
+  });
+
+  describe('.getConnections', () => {
+    it('should return the connection count', (done) => {
+      const sut = new NoiseServer({ ls });
+      sut.getConnections((err, cnt) => {
+        expect(cnt).to.equal(0);
+        done();
+      });
+    });
+  });
+});