feat: add receipts (#133)

feat: add receipts

fix: explicitly specify mocha test directories
The recursive wildcard (**) isn't supported universally, including on circleci

Author: wilsonianb

scripts/generate-fixtures.ts

@@ -100,7 +100,12 @@ const variants = Array.prototype.concat.apply([], [
   NUMBERS.map((pair) => ({
     name: 'frame:stream_data_blocked:offset:' + pair.name,
     frame: new Packet.StreamDataBlockedFrame(123, pair.value)
-  }))
+  })),
+  {
+    name: 'frame:stream_receipt',
+    frame: new Packet.StreamReceiptFrame(1,
+      Buffer.from('AQAAAAAAAAAAAAAAAAAAAAABAAAAAAAAAfTBIvoCUt67Zy1ZGCP3EOmVFtZzhc85fah8yPnoyL9RMA==', 'base64'))
+  }
 ])
 
 const fixtures = variants.map(function (params: any) {

src/connection.ts

@@ -20,11 +20,12 @@ import {
   ConnectionMaxStreamIdFrame,
   StreamMaxDataFrame,
   StreamDataBlockedFrame,
+  StreamReceiptFrame,
   ConnectionMaxDataFrame,
   ConnectionDataBlockedFrame,
   StreamMoneyBlockedFrame
 } from './packet'
-import { Reader } from 'oer-utils'
+import { Reader, Writer } from 'oer-utils'
 import { CongestionController } from './util/congestion'
 import { Plugin } from './util/plugin-interface'
 import {
@@ -38,6 +39,7 @@ import {
 } from './util/long'
 import * as Long from 'long'
 import Rational from './util/rational'
+import { createReceipt, RECEIPT_VERSION } from './util/receipt'
 import { v4 as uuid } from 'uuid'
 
 const RETRY_DELAY_START = 100
@@ -65,6 +67,10 @@ export interface ConnectionOpts {
   enablePadding?: boolean,
   /** User-specified connection identifier that was passed into [`generateAddressAndSecret`]{@link Server#generateAddressAndSecret} */
   connectionTag?: string,
+  /** User-specified receipt nonce that was passed into [`generateAddressAndSecret`]{@link Server#generateAddressAndSecret} */
+  receiptNonce?: Buffer,
+  /** User-specified receipt secret that was passed into [`generateAddressAndSecret`]{@link Server#generateAddressAndSecret} */
+  receiptSecret?: Buffer,
   /** Maximum number of streams the other entity can have open at once. Defaults to 10 */
   maxRemoteStreams?: number,
   /** Number of bytes each connection can have in the buffer. Defaults to 65534 */
@@ -147,6 +153,8 @@ function defaultGetExpiry (): Date {
 export class Connection extends EventEmitter {
   /** Application identifier for a certain connection */
   readonly connectionTag?: string
+  protected readonly _receiptNonce?: Buffer
+  protected readonly _receiptSecret?: Buffer
 
   protected connectionId: string
   protected plugin: Plugin
@@ -221,6 +229,11 @@ export class Connection extends EventEmitter {
     this.allowableReceiveExtra = Rational.fromNumber(1.01, true)
     this.enablePadding = !!opts.enablePadding
     this.connectionTag = opts.connectionTag
+    if (!opts.receiptNonce !== !opts.receiptSecret) {
+      throw new Error('receiptNonce and receiptSecret must accompany each other')
+    }
+    this._receiptNonce = opts.receiptNonce
+    this._receiptSecret = opts.receiptSecret
     this.maxStreamId = 2 * (opts.maxRemoteStreams || DEFAULT_MAX_REMOTE_STREAMS)
     this.maxBufferedData = opts.connectionBufferSize || MAX_DATA_SIZE * 2
     this.minExchangeRatePrecision = opts.minExchangeRatePrecision || DEFAULT_MINIMUM_EXCHANGE_RATE_PRECISION
@@ -681,8 +694,22 @@ export class Connection extends EventEmitter {
     }
 
     // Add incoming amounts to each stream
+    const totalsReceived: Map<number, string> = new Map()
     for (let { stream, amount } of amountsToReceive) {
       stream._addToIncoming(amount, prepare)
+      totalsReceived.set(stream.id, stream.totalReceived)
+    }
+
+    // Add receipt frame(s)
+    if (this._receiptNonce && this._receiptSecret) {
+      for (let [streamId, totalReceived] of totalsReceived) {
+        responseFrames.push(new StreamReceiptFrame(streamId, createReceipt({
+          nonce: this._receiptNonce,
+          streamId,
+          totalReceived,
+          secret: this._receiptSecret
+        })))
+      }
     }
 
     // TODO make sure the queued frames aren't too big
@@ -1142,6 +1169,17 @@ export class Connection extends EventEmitter {
       }
 
       if (responsePacket.ilpPacketType === IlpPacketType.Fulfill) {
+        for (let frame of responsePacket.frames) {
+          if (frame.type === FrameType.StreamReceipt) {
+            const stream = this.streams.get(frame.streamId.toNumber())
+            if (stream) {
+              stream._setReceipt(frame.receipt)
+            } else {
+              this.log.debug('received receipt for unknown stream %d: %h', frame.streamId, frame.receipt)
+            }
+          }
+        }
+
         for (let stream of streamsSentFrom) {
           stream._executeHold(requestPacket.sequence.toString())
         }
@@ -1158,7 +1196,7 @@ export class Connection extends EventEmitter {
   }
 
   /**
-   * (Internal) Send volly of test packests to find the exchange rate, its precision, and potential other amounts to try.
+   * (Internal) Send volley of test packets to find the exchange rate, its precision, and potential other amounts to try.
    * @private
    */
   protected async sendTestPacketVolley (testPacketAmounts: number[]): Promise<any> {

src/crypto.ts

@@ -2,20 +2,24 @@
 import { hmac, randomBytes } from './util/crypto-node'
 export {
   decrypt,
+  decryptConnectionAddressToken, // only in node, not browser
   encrypt,
+  encryptConnectionAddressToken, // only in node, not browser
   generateSharedSecretFromToken, // only in node, not browser
+  generateReceiptHMAC, // only in node, not browser
   hash,
+  hmac,
   randomBytes
 } from './util/crypto-node'
 
-const TOKEN_LENGTH = 18
+export const TOKEN_NONCE_LENGTH = 18
 const ENCRYPTION_KEY_STRING = Buffer.from('ilp_stream_encryption', 'utf8')
 const FULFILLMENT_GENERATION_STRING = Buffer.from('ilp_stream_fulfillment', 'utf8')
 const PACKET_ID_STRING = Buffer.from('ilp_stream_packet_id', 'utf8')
 export const ENCRYPTION_OVERHEAD = 28
 
-export function generateToken (): Buffer {
-  return randomBytes(TOKEN_LENGTH)
+export function generateTokenNonce (): Buffer {
+  return randomBytes(TOKEN_NONCE_LENGTH)
 }
 
 export function generateRandomCondition (): Buffer {

src/index.ts

@@ -6,7 +6,7 @@ import { Connection, ConnectionOpts } from './connection'
 
 export { Connection } from './connection'
 export { DataAndMoneyStream } from './stream'
-export { Server, ServerOpts, createServer } from './server'
+export { Server, ServerOpts, createServer, GenerateAddressSecretOpts } from './server'
 
 export interface CreateConnectionOpts extends ConnectionOpts {
   /** ILP Address of the server */

src/packet.ts

@@ -47,7 +47,8 @@ export enum FrameType {
   StreamMoneyBlocked = 0x13,
   StreamData = 0x14,
   StreamMaxData = 0x15,
-  StreamDataBlocked = 0x16
+  StreamDataBlocked = 0x16,
+  StreamReceipt = 0x17
 }
 
 /**
@@ -68,6 +69,7 @@ export type Frame =
   | StreamDataFrame
   | StreamMaxDataFrame
   | StreamDataBlockedFrame
+  | StreamReceiptFrame
 
 /**
  * STREAM Protocol Packet
@@ -487,6 +489,33 @@ export class StreamDataBlockedFrame extends BaseFrame {
   }
 }
 
+export class StreamReceiptFrame extends BaseFrame {
+  type: FrameType.StreamReceipt
+  streamId: Long
+  receipt: Buffer
+
+  constructor (streamId: LongValue, receipt: Buffer) {
+    super('StreamReceipt')
+    this.streamId = longFromValue(streamId, true)
+    this.receipt = receipt
+  }
+
+  static fromContents (reader: Reader): StreamReceiptFrame {
+    const streamId = reader.readVarUIntLong()
+    const receipt = reader.readVarOctetString()
+    return new StreamReceiptFrame(streamId, receipt)
+  }
+
+  toJSON (): Object {
+    return {
+      type: this.type,
+      name: this.name,
+      streamId: this.streamId,
+      receipt: this.receipt.toString('base64')
+    }
+  }
+}
+
 function parseFrame (reader: Reader): Frame | undefined {
   const type = reader.readUInt8Number()
   const contents = Reader.from(reader.readVarOctetString())
@@ -520,6 +549,8 @@ function parseFrame (reader: Reader): Frame | undefined {
       return StreamMaxDataFrame.fromContents(contents)
     case FrameType.StreamDataBlocked:
       return StreamDataBlockedFrame.fromContents(contents)
+    case FrameType.StreamReceipt:
+      return StreamReceiptFrame.fromContents(contents)
     default:
       return undefined
   }

src/pool.ts

@@ -1,5 +1,6 @@
 import createLogger from 'ilp-logger'
 import * as IlpPacket from 'ilp-packet'
+import { Reader } from 'oer-utils'
 import { Connection, BuildConnectionOpts } from './connection'
 import * as cryptoHelper from './crypto'
 
@@ -52,15 +53,46 @@ export class ServerConnectionPool {
     if (pendingConnection) return pendingConnection
 
     const connectionPromise = (async () => {
-      const sharedSecret = await this.getSharedSecret(id, prepare)
+      const token = Buffer.from(id, 'base64')
+      const sharedSecret = await this.getSharedSecret(token, prepare)
       // If we get here, that means it was a token + sharedSecret we created
-      const tilde = id.indexOf('~')
-      const connectionTag = tilde !== -1 ? id.slice(tilde + 1) : undefined
+      let connectionTag: string | undefined
+      let receiptNonce: Buffer | undefined
+      let receiptSecret: Buffer | undefined
+      const reader = new Reader(cryptoHelper.decryptConnectionAddressToken(this.serverSecret, token))
+      reader.skipOctetString(cryptoHelper.TOKEN_NONCE_LENGTH)
+      if (reader.peekVarOctetString().length) {
+        connectionTag = reader.readVarOctetString().toString('ascii')
+      } else {
+        reader.skipVarOctetString()
+      }
+      switch (reader.peekVarOctetString().length) {
+        case 0:
+          reader.skipVarOctetString()
+          break
+        case 16:
+          receiptNonce = reader.readVarOctetString()
+          break
+        default:
+          throw new Error('receiptNonce must be 16 bytes')
+      }
+      switch (reader.peekVarOctetString().length) {
+        case 0:
+          reader.skipVarOctetString()
+          break
+        case 32:
+          receiptSecret = reader.readVarOctetString()
+          break
+        default:
+          throw new Error('receiptSecret must be 32 bytes')
+      }
       const conn = await Connection.build({
         ...this.connectionOpts,
         sharedSecret,
         connectionTag,
-        connectionId: id
+        connectionId: id,
+        receiptNonce,
+        receiptSecret
       })
       log.debug('got incoming packet for new connection: %s%s', id, (connectionTag ? ' (connectionTag: ' + connectionTag + ')' : ''))
       try {
@@ -92,11 +124,10 @@ export class ServerConnectionPool {
   }
 
   private async getSharedSecret (
-    id: string,
+    token: Buffer,
     prepare: IlpPacket.IlpPrepare
   ): Promise<Buffer> {
     try {
-      const token = Buffer.from(id, 'ascii')
       const sharedSecret = cryptoHelper.generateSharedSecretFromToken(
         this.serverSecret, token)
       // TODO just pass this into the connection?

src/server.ts

@@ -5,9 +5,9 @@ import createLogger from 'ilp-logger'
 import * as cryptoHelper from './crypto'
 import { Connection, ConnectionOpts } from './connection'
 import { ServerConnectionPool } from './pool'
+import { Predictor, Writer } from 'oer-utils'
 import { Plugin } from './util/plugin-interface'
 
-const CONNECTION_ID_REGEX = /^[a-zA-Z0-9~_-]+$/
 const DEFAULT_DISCONNECT_DELAY = 100
 
 export interface ServerOpts extends ConnectionOpts {
@@ -20,6 +20,12 @@ export interface ServerOpts extends ConnectionOpts {
   disconnectDelay?: number
 }
 
+export interface GenerateAddressSecretOpts {
+  connectionTag?: string,
+  receiptNonce?: Buffer,
+  receiptSecret?: Buffer
+}
+
 /**
  * STREAM Server that can listen on an account and handle multiple incoming [`Connection`s]{@link Connection}.
  * Note: the connections this refers to are over ILP, not over the Internet.
@@ -155,23 +161,61 @@ export class Server extends EventEmitter {
    * Two different clients SHOULD NOT be given the same address and secret.
    *
    * @param connectionTag Optional connection identifier that will be appended to the ILP address and can be used to identify incoming connections. Can only include characters that can go into an ILP Address
+   * @param receiptNonce Optional nonce to include in STREAM receipts
+   * @param receiptSecret Optional secret to use for signing STREAM receipts
    */
-  generateAddressAndSecret (connectionTag?: string): { destinationAccount: string, sharedSecret: Buffer } {
+  generateAddressAndSecret (opts?: string | GenerateAddressSecretOpts): { destinationAccount: string, sharedSecret: Buffer, receiptsEnabled: boolean } {
     if (!this.connected) {
       throw new Error('Server must be connected to generate address and secret')
     }
-    let token = base64url(cryptoHelper.generateToken())
-    if (connectionTag) {
-      if (!CONNECTION_ID_REGEX.test(connectionTag)) {
-        throw new Error('connectionTag can only include ASCII characters a-z, A-Z, 0-9, "_", "-", and "~"')
+    let connectionTag = Buffer.alloc(0)
+    let receiptNonce = Buffer.alloc(0)
+    let receiptSecret = Buffer.alloc(0)
+    let receiptsEnabled = false
+    if (opts) {
+      if (typeof opts === 'object') {
+        if (opts.connectionTag) {
+          connectionTag = Buffer.from(opts.connectionTag, 'ascii')
+        }
+        if (!opts.receiptNonce !== !opts.receiptSecret) {
+          throw new Error('receiptNonce and receiptSecret must accompany each other')
+        }
+        if (opts.receiptNonce) {
+          if (opts.receiptNonce.length !== 16) {
+            throw new Error('receiptNonce must be 16 bytes')
+          }
+          receiptsEnabled = true
+          receiptNonce = opts.receiptNonce
+        }
+        if (opts.receiptSecret) {
+          if (opts.receiptSecret.length !== 32) {
+            throw new Error('receiptSecret must be 32 bytes')
+          }
+          receiptSecret = opts.receiptSecret
+        }
+      } else {
+        connectionTag = Buffer.from(opts, 'ascii')
       }
-      token = token + '~' + connectionTag
     }
-    const sharedSecret = cryptoHelper.generateSharedSecretFromToken(this.serverSecret, Buffer.from(token, 'ascii'))
+    const tokenNonce = cryptoHelper.generateTokenNonce()
+    const predictor = new Predictor()
+    predictor.writeOctetString(tokenNonce, cryptoHelper.TOKEN_NONCE_LENGTH)
+    predictor.writeVarOctetString(connectionTag)
+    predictor.writeVarOctetString(receiptNonce)
+    predictor.writeVarOctetString(receiptSecret)
+    const writer = new Writer(predictor.length)
+    writer.writeOctetString(tokenNonce, cryptoHelper.TOKEN_NONCE_LENGTH)
+    writer.writeVarOctetString(connectionTag)
+    writer.writeVarOctetString(receiptNonce)
+    writer.writeVarOctetString(receiptSecret)
+
+    const token = cryptoHelper.encryptConnectionAddressToken(this.serverSecret, writer.getBuffer())
+    const sharedSecret = cryptoHelper.generateSharedSecretFromToken(this.serverSecret, token)
     return {
       // TODO should this be called serverAccount or serverAddress instead?
-      destinationAccount: `${this.serverAccount}.${token}`,
-      sharedSecret
+      destinationAccount: `${this.serverAccount}.${base64url(token)}`,
+      sharedSecret,
+      receiptsEnabled
     }
   }