paid-services 9.0.1 → 9.2.0

package/network/create_network_path.js

@@ -0,0 +1,122 @@
+const asyncAuto = require('async/auto');
+const {blindedPathFromHops} = require('bolt04');
+const {getIdentity} = require('ln-service');
+const {getPeers} = require('ln-service');
+const {returnResult} = require('asyncjs-util');
+
+const isHex = n => !(n.length % 2) && /^[0-9A-F]*$/i.test(n);
+const isHexString = n => typeof n === 'string' && isHex(n);
+const isLongPathId = n => n.length / 2 >= minPathIdBytes;
+const isPublicKey = n => typeof n === 'string' && /^[0-9A-F]{66}$/i.test(n);
+const minPathIdBytes = 16;
+
+/** Create a blinded path to self that can be published to receive messages,
+  starting at a connected `introduction` peer, or at self
+
+  A given path `id` is at least 16 bytes from a secure random source, kept
+  private.
+
+  {
+    [id]: <Random Path Identifier Hex String>
+    [introduction]: <Introduction Connected Peer Public Key Hex String>
+    lnd: <Authenticated LND API Object>
+  }
+
+  @returns via cbk or Promise
+  {
+    id: <Path Identifier Hex String>
+    path: {
+      hops: [{
+        encrypted_data: <Encrypted Recipient Data Hex String>
+        relay_key: <Blinded Relaying Node Public Key Hex String>
+      }]
+      introduction_node: <Introduction Node Public Key Hex String>
+      key: <First Hop Path Key Public Key Hex String>
+    }
+  }
+*/
+module.exports = ({id, introduction, lnd}, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!!id && !isHexString(id)) {
+          return cbk([400, 'ExpectedHexEncodedPathIdToCreateNetworkPath']);
+        }
+
+        // A path id is at least 16 random bytes, so it cannot be guessed
+        if (!!id && !isLongPathId(id)) {
+          return cbk([400, 'ExpectedLongerPathIdToCreateNetworkPath']);
+        }
+
+        if (!!introduction && !isPublicKey(introduction)) {
+          return cbk([400, 'ExpectedIntroductionPublicKeyToCreateNetworkPath']);
+        }
+
+        if (!lnd) {
+          return cbk([400, 'ExpectedLndToCreateNetworkPath']);
+        }
+
+        return cbk();
+      },
+
+      // Get the self identity key to use as the end of the path
+      getIdentity: ['validate', ({}, cbk) => getIdentity({lnd}, cbk)],
+
+      // Get the connected peers to confirm the introduction is connected
+      getPeers: ['validate', ({}, cbk) => {
+        // Exit early when there is no introduction peer
+        if (!introduction) {
+          return cbk();
+        }
+
+        return getPeers({lnd}, cbk);
+      }],
+
+      // Check the introduction is a connected peer, and get the path nodes
+      nodes: ['getIdentity', 'getPeers', ({getIdentity, getPeers}, cbk) => {
+        const identity = getIdentity.public_key;
+
+        // Exit early when the path starts and ends at self
+        if (!introduction) {
+          return cbk(null, {hops: [identity], introduction: identity});
+        }
+
+        // Node keys are compared in lowercase, as LND gives them
+        const key = introduction.toLowerCase();
+
+        if (key === identity) {
+          return cbk([400, 'ExpectedIntroductionPeerOtherThanSelfForPath']);
+        }
+
+        const peerKeys = getPeers.peers.map(n => n.public_key);
+
+        // The introduction node needs to be able to forward to self
+        if (!peerKeys.includes(key)) {
+          return cbk([503, 'ExpectedConnectedIntroductionPeerToCreatePath']);
+        }
+
+        return cbk(null, {hops: [key, identity], introduction: key});
+      }],
+
+      // Create the blinded path
+      create: ['nodes', ({nodes}, cbk) => {
+        try {
+          const blinded = blindedPathFromHops({id, hops: nodes.hops});
+
+          return cbk(null, {
+            id: blinded.id,
+            path: {
+              hops: blinded.path,
+              introduction_node: nodes.introduction,
+              key: blinded.key,
+            },
+          });
+        } catch (err) {
+          return cbk([400, 'FailedToCreateNetworkPath', {err}]);
+        }
+      }],
+    },
+    returnResult({reject, resolve, of: 'create'}, cbk));
+  });
+};

package/network/encode_network_response.js

@@ -0,0 +1,37 @@
+const encodePeerResponse = require('./../p2p/encode_peer_response');
+
+const defaultServerError = [500, 'InternalServiceError'];
+
+/** Encode a response to a network request
+
+  When the response cannot be encoded, a generic server failure is encoded in
+  its place, and the encoding error is returned so that it can be reported
+
+  {
+    [failure]: [
+      <Failure Code Number>
+      <Failure Message String>
+    ]
+    id: <Request Id Hex String>
+    [records]: [{
+      type: <Type Number String>
+      value: <Value Hex String>
+    }]
+  }
+
+  @returns
+  {
+    [err]: [<Error Code Number>, <Error Message String>]
+    message: <Encoded Response Hex String>
+  }
+*/
+module.exports = ({failure, id, records}) => {
+  try {
+    return {message: encodePeerResponse({failure, id, records}).message};
+  } catch (err) {
+    return {
+      err: [503, err.message],
+      message: encodePeerResponse({id, failure: defaultServerError}).message,
+    };
+  }
+};

package/network/get_message_hops.js

@@ -0,0 +1,130 @@
+const asyncAuto = require('async/auto');
+const asyncRetry = require('async/retry');
+const {getIdentity} = require('ln-service');
+const {getPeers} = require('ln-service');
+const {returnResult} = require('asyncjs-util');
+
+const getRelayingRoute = require('./get_relaying_route');
+
+const hasBit = (list, bits) => !!(list || []).find(n => bits.includes(n.bit));
+const isRetry = err => !!err && err[1] === 'RetryWithoutIgnoredNodes';
+const maxAttempts = 10;
+const onlyChannelsBits = [66, 67];
+
+/** Get a series of nodes to relay a message to a destination
+
+  A connected destination is sent to directly, unless it signals feature bit
+  66 or 67, `option_onion_messages_only_channels`, that it only takes
+  messages from peers with a channel. Otherwise the message goes back along a
+  payment route found from the destination to self, through nodes that relay
+  messages.
+
+  {
+    destination: <Destination Node Public Key Hex String>
+    lnd: <Authenticated LND API Object>
+  }
+
+  @returns via cbk or Promise
+  {
+    hops: [<Message Hop Public Key Hex String>]
+  }
+*/
+module.exports = ({destination, lnd}, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        // The destination key is a string so that it can be compared
+        if (!destination || typeof destination !== 'string') {
+          return cbk([400, 'ExpectedDestinationToGetMessageHops']);
+        }
+
+        if (!lnd) {
+          return cbk([400, 'ExpectedLndToGetMessageHops']);
+        }
+
+        return cbk();
+      },
+
+      // Node keys are compared in lowercase, as LND gives them
+      key: ['validate', ({}, cbk) => cbk(null, destination.toLowerCase())],
+
+      // Get the connected peers
+      getPeers: ['validate', ({}, cbk) => getPeers({lnd}, cbk)],
+
+      // A connected destination is sent to directly unless it needs a channel
+      isDirect: ['getPeers', 'key', ({getPeers, key}, cbk) => {
+        const peer = getPeers.peers.find(n => n.public_key === key);
+
+        return cbk(null, !!peer && !hasBit(peer.features, onlyChannelsBits));
+      }],
+
+      // Get the identity key of self, which routes are found back to
+      getIdentity: ['isDirect', ({isDirect}, cbk) => {
+        // Exit early when the destination is sent to directly
+        if (isDirect) {
+          return cbk();
+        }
+
+        return getIdentity({lnd}, cbk);
+      }],
+
+      // Find a series of nodes to relay the message
+      hops: [
+        'getIdentity',
+        'getPeers',
+        'isDirect',
+        'key',
+        ({getIdentity, getPeers, isDirect, key}, cbk) =>
+      {
+        // Exit early when the destination is sent to directly
+        if (isDirect) {
+          return cbk(null, {hops: [key]});
+        }
+
+        const source = getIdentity.public_key;
+
+        if (key === source) {
+          return cbk([400, 'UnexpectedMessageDestinationIsSelf']);
+        }
+
+        const ignore = [];
+
+        // Find a route of nodes that relay messages, trying again without the
+        // nodes that do not
+        return asyncRetry({errorFilter: isRetry, times: maxAttempts}, cbk => {
+          return getRelayingRoute({
+            ignore,
+            lnd,
+            source,
+            destination: key,
+            peers: getPeers.peers,
+          },
+          (err, res) => {
+            if (!!err) {
+              return cbk(err);
+            }
+
+            // Exit early when the route has nodes to use
+            if (!!res.hops) {
+              return cbk(null, {hops: res.hops});
+            }
+
+            res.ignore.forEach(n => ignore.push(n));
+
+            return cbk([503, 'RetryWithoutIgnoredNodes']);
+          });
+        },
+        (err, res) => {
+          // Exit early when every attempt found nodes that do not relay
+          if (isRetry(err)) {
+            return cbk([503, 'FailedToFindMessageHopsToDestination']);
+          }
+
+          return cbk(err, res);
+        });
+      }],
+    },
+    returnResult({reject, resolve, of: 'hops'}, cbk));
+  });
+};

package/network/get_path_id.js

@@ -0,0 +1,61 @@
+const asyncAuto = require('async/auto');
+const {decryptBlindedPath} = require('bolt04');
+const {diffieHellmanComputeSecret} = require('ln-service');
+const {returnResult} = require('asyncjs-util');
+
+/** Get the path id of a received message from its encrypted recipient data
+
+  {
+    encrypted: <Encrypted Recipient Data Hex String>
+    key: <Path Key Hex String>
+    lnd: <Authenticated LND API Object>
+  }
+
+  @returns via cbk or Promise
+  {
+    [id]: <Path Identifier Hex String>
+  }
+*/
+module.exports = ({encrypted, key, lnd}, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!encrypted) {
+          return cbk([400, 'ExpectedEncryptedRecipientDataToGetPathId']);
+        }
+
+        if (!key) {
+          return cbk([400, 'ExpectedPathKeyToGetPathId']);
+        }
+
+        if (!lnd) {
+          return cbk([400, 'ExpectedLndToGetPathId']);
+        }
+
+        return cbk();
+      },
+
+      // Compute the shared secret of the path key and the node identity key
+      getSecret: ['validate', ({}, cbk) => {
+        return diffieHellmanComputeSecret({lnd, partner_public_key: key}, cbk);
+      }],
+
+      // Decrypt the recipient data to get the path id
+      decrypt: ['getSecret', ({getSecret}, cbk) => {
+        try {
+          const {id} = decryptBlindedPath({
+            encrypted,
+            key,
+            secret: getSecret.secret,
+          });
+
+          return cbk(null, {id});
+        } catch (err) {
+          return cbk([503, 'FailedToDecryptRecipientDataForPathId', {err}]);
+        }
+      }],
+    },
+    returnResult({reject, resolve, of: 'decrypt'}, cbk));
+  });
+};

package/network/get_path_outbound.js

@@ -0,0 +1,82 @@
+const asyncAuto = require('async/auto');
+const {getChannel} = require('ln-service');
+const {returnResult} = require('asyncjs-util');
+
+const getMessageHops = require('./get_message_hops');
+const pathIntroduction = require('./path_introduction');
+
+const edgeChannel = edge => edge.split('x').slice(0, -1).join('x');
+
+/** Get the outbound hops to reach the introduction node of a blinded path
+
+  When the introduction node is not a connected peer, the message is relayed
+  along a payment route through nodes that relay onion messages
+
+  {
+    lnd: <Authenticated LND API Object>
+    path: {
+      [introduction_edge]: <Introduction Node Edge Format Channel Id String>
+      [introduction_node]: <Introduction Node Public Key Hex String>
+    }
+  }
+
+  @returns via cbk or Promise
+  {
+    outbound: [<Relaying Node Public Key Hex String>]
+  }
+*/
+module.exports = ({lnd, path}, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!lnd) {
+          return cbk([400, 'ExpectedLndToGetPathOutbound']);
+        }
+
+        if (!path) {
+          return cbk([400, 'ExpectedBlindedPathToGetPathOutbound']);
+        }
+
+        return cbk();
+      },
+
+      // Get the channel of the introduction edge
+      getChannel: ['validate', ({}, cbk) => {
+        // Exit early when the introduction is a node and not an edge
+        if (!path.introduction_edge) {
+          return cbk();
+        }
+
+        const id = edgeChannel(path.introduction_edge);
+
+        return getChannel({id, lnd}, cbk);
+      }],
+
+      // Determine the introduction node of the path
+      introduction: ['getChannel', ({getChannel}, cbk) => {
+        try {
+          const {introduction} = pathIntroduction({
+            path,
+            channel: getChannel,
+          });
+
+          return cbk(null, introduction);
+        } catch (err) {
+          return cbk([400, err.message]);
+        }
+      }],
+
+      // Get the hops to relay the message to the introduction node
+      getHops: ['introduction', ({introduction}, cbk) => {
+        return getMessageHops({lnd, destination: introduction}, cbk);
+      }],
+
+      // The outbound hops end at the introduction node
+      outbound: ['getHops', ({getHops}, cbk) => {
+        return cbk(null, {outbound: getHops.hops});
+      }],
+    },
+    returnResult({reject, resolve, of: 'outbound'}, cbk));
+  });
+};

package/network/get_relaying_route.js

@@ -0,0 +1,100 @@
+const asyncAuto = require('async/auto');
+const asyncMap = require('async/map');
+const {getNode} = require('ln-service');
+const {getRouteToDestination} = require('ln-service');
+const {returnResult} = require('asyncjs-util');
+
+const relaysAsHops = require('./relays_as_hops');
+const routeRelays = require('./route_relays');
+
+const tokens = 1;
+
+/** Get a route of nodes that relay a message to a destination, from a
+  payment route found from the destination back to self
+
+  When the route cannot be used, the nodes to avoid in the next route are
+  given instead.
+
+  {
+    destination: <Destination Node Public Key Hex String>
+    ignore: [{
+      [from_public_key]: <Avoid Route From Node Public Key Hex String>
+      [to_public_key]: <Avoid Route To Node Public Key Hex String>
+    }]
+    lnd: <Authenticated LND API Object>
+    peers: [{
+      public_key: <Peer Public Key Hex String>
+    }]
+    source: <Self Public Key Hex String>
+  }
+
+  @returns via cbk or Promise
+  {
+    [hops]: [<Message Hop Public Key Hex String>]
+    [ignore]: [{
+      [from_public_key]: <Avoid Route From Node Public Key Hex String>
+      [to_public_key]: <Avoid Route To Node Public Key Hex String>
+    }]
+  }
+*/
+module.exports = ({destination, ignore, lnd, peers, source}, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Find a route from the destination back to self
+      getRoute: cbk => {
+        return getRouteToDestination({
+          ignore,
+          lnd,
+          tokens,
+          destination: source,
+          is_ignoring_past_failures: true,
+          start: destination,
+        },
+        cbk);
+      },
+
+      // Get the nodes that the message goes through on the route
+      relays: ['getRoute', ({getRoute}, cbk) => {
+        // Exit early when there is no route
+        if (!getRoute.route) {
+          return cbk([503, 'FailedToFindMessageHopsToDestination']);
+        }
+
+        return cbk(null, routeRelays({
+          destination,
+          peers,
+          source,
+          route: getRoute.route,
+        }));
+      }],
+
+      // Get the features of each node, as no features when not known
+      getNodes: ['relays', ({relays}, cbk) => {
+        return asyncMap(relays.relays || [], (key, cbk) => {
+          return getNode({
+            lnd,
+            is_omitting_channels: true,
+            public_key: key,
+          },
+          (err, res) => cbk(null, !!err ? {features: []} : res));
+        },
+        cbk);
+      }],
+
+      // Check that every node on the route relays messages
+      route: ['getNodes', 'relays', ({getNodes, relays}, cbk) => {
+        // Exit early when the first hop is not a peer
+        if (!!relays.ignore) {
+          return cbk(null, {ignore: relays.ignore});
+        }
+
+        return cbk(null, relaysAsHops({
+          destination,
+          nodes: getNodes,
+          relays: relays.relays,
+        }));
+      }],
+    },
+    returnResult({reject, resolve, of: 'route'}, cbk));
+  });
+};

package/network/index.js

@@ -0,0 +1,15 @@
+const createNetworkPath = require('./create_network_path');
+const makeNetworkRequest = require('./make_network_request');
+const requestNetworkReply = require('./request_network_reply');
+const resolvePathIntroductions = require('./resolve_path_introductions');
+const serviceNetworkMessages = require('./service_network_messages');
+const serviceNetworkRequests = require('./service_network_requests');
+
+module.exports = {
+  createNetworkPath,
+  makeNetworkRequest,
+  requestNetworkReply,
+  resolvePathIntroductions,
+  serviceNetworkMessages,
+  serviceNetworkRequests,
+};

package/network/make_network_request.js

@@ -0,0 +1,152 @@
+const {randomBytes} = require('crypto');
+
+const asyncAuto = require('async/auto');
+const {returnResult} = require('asyncjs-util');
+
+const encodePeerRequest = require('./../p2p/encode_peer_request');
+const parseRequestMessage = require('./../p2p/parse_request_message');
+const requestNetworkReply = require('./request_network_reply');
+
+const {isArray} = Array;
+const isPublicKey = n => typeof n === 'string' && /^[0-9A-F]{66}$/i.test(n);
+const {isSafeInteger} = Number;
+const isTimeout = n => isSafeInteger(n) && n > 0;
+const bufferAsHex = buffer => Buffer.from(buffer).toString('hex');
+const makeId = () => bufferAsHex(randomBytes(32));
+const peerRequestType = 32768;
+const typeNetworkRequest = '32769';
+
+/** Make a network request over onion messages, sent over a blinded path of
+  the destination, with the response returned over a reply path to self
+
+  The request fails when no response arrives within the `timeout`.
+
+  {
+    lnd: <Authenticated LND API Object>
+    path: {
+      hops: [{
+        encrypted_data: <Encrypted Recipient Data Hex String>
+        relay_key: <Blinded Relaying Node Public Key Hex String>
+      }]
+      [introduction_edge]: <Introduction Node Edge Format Channel Id String>
+      [introduction_node]: <Introduction Node Public Key Hex String>
+      key: <First Hop Path Key Public Key Hex String>
+    }
+    [records]: [{
+      type: <Type Number String>
+      value: <Value Hex Encoded String>
+    }]
+    [timeout]: <Response Timeout Milliseconds Number> // Default: 30000
+    type: <Request Type Number String>
+  }
+
+  @throws error via cbk or Promise
+  [0, NetworkRequestTimeout]
+
+  @returns via cbk or Promise
+  {
+    [records]: [{
+      type: <Type Number String>
+      value: <Value Hex Encoded String>
+    }]
+  }
+*/
+module.exports = ({lnd, path, records, timeout, type}, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!lnd) {
+          return cbk([400, 'ExpectedLndToMakeNetworkRequest']);
+        }
+
+        if (!path) {
+          return cbk([400, 'ExpectedBlindedPathToMakeNetworkRequest']);
+        }
+
+        if (!isArray(path.hops) || !path.hops.length) {
+          return cbk([400, 'ExpectedBlindedPathHopsToMakeNetworkRequest']);
+        }
+
+        if (!path.introduction_edge && !path.introduction_node) {
+          return cbk([400, 'ExpectedPathIntroductionToMakeNetworkRequest']);
+        }
+
+        // A node introduction is looked up as a public key
+        if (!!path.introduction_node && !isPublicKey(path.introduction_node)) {
+          return cbk([400, 'ExpectedIntroductionKeyToMakeNetworkRequest']);
+        }
+
+        if (!!path.introduction_edge) {
+          if (typeof path.introduction_edge !== 'string') {
+            return cbk([400, 'ExpectedIntroductionEdgeToMakeNetworkRequest']);
+          }
+        }
+
+        if (!path.key) {
+          return cbk([400, 'ExpectedBlindedPathKeyToMakeNetworkRequest']);
+        }
+
+        if (timeout !== undefined && !isTimeout(timeout)) {
+          return cbk([400, 'ExpectedPositiveTimeoutToMakeNetworkRequest']);
+        }
+
+        if (!type) {
+          return cbk([400, 'ExpectedTypeToMakeNetworkRequest']);
+        }
+
+        return cbk();
+      },
+
+      // Generate an id for the request
+      id: ['validate', ({}, cbk) => cbk(null, makeId())],
+
+      // Encode the request message
+      message: ['id', ({id}, cbk) => {
+        try {
+          const {message} = encodePeerRequest({id, records, type});
+
+          return cbk(null, {type: typeNetworkRequest, value: message});
+        } catch (err) {
+          return cbk([400, err.message]);
+        }
+      }],
+
+      // Send the request and wait for the reply on its reply path
+      getReply: ['message', ({message}, cbk) => {
+        return requestNetworkReply({
+          lnd,
+          message,
+          path,
+          timeout,
+          types: [typeNetworkRequest],
+        },
+        cbk);
+      }],
+
+      // Read the response to the request
+      request: ['getReply', 'id', ({getReply, id}, cbk) => {
+        try {
+          const {response} = parseRequestMessage({
+            message: getReply.reply.value,
+            type: peerRequestType,
+          });
+
+          if (!response || response.id !== id) {
+            return cbk([503, 'ExpectedResponseToNetworkRequest']);
+          }
+
+          // Exit early when the server responds with a failure code
+          if (!!response.failure) {
+            return cbk(response.failure);
+          }
+
+          return cbk(null, {records: response.records});
+        } catch (err) {
+          return cbk([503, 'ExpectedResponseToNetworkRequest']);
+        }
+      }],
+    },
+    returnResult({reject, resolve, of: 'request'}, cbk));
+  });
+};