paid-services 10.1.0 → 10.3.0

package/CHANGELOG.md

@@ -1,26 +1,27 @@
 # Versions
 
+## Version 10.3.0
+
+- `getOfferInvoice`: Add support for offer paths that start at the payer
+- `serviceSupportOffer`: Add support for reply paths that start at the node
+
+## Version 10.2.0
+
+- `serviceSupportOffer`: Add `start` event with the support offer
+
 ## Version 10.1.0
 
-- `createSupportOffer`: Add `introduction` to start the created offer path at
-    a connected peer, for a node that is connected only by private channels
-- `getOfferInvoice`: Check the offer before deriving the payer key, so that a
-    refused offer does not use up a payer key index
-- `payOfferInvoice`: Refuse invoices that require multi-part payment
+- `createSupportOffer`: Add `introduction` to start the created offer path
 
 ## Version 10.0.0
 
 - `getOfferInvoice`: Add `features` to show the features of the invoice
 - `getOfferInvoice`: Add support for offers with an issuer id and no paths
-- `getOfferInvoice`: Check that an invoice for an offer without an issuer id
-    is signed by the final node of the path that the request was sent over
 
 ### Breaking Changes
 
 - `getOfferInvoice`: Refuse offers with an amount in a currency
-- `getOfferInvoice`: The payer id is now a key derived by LND in key family
-    808, and `payer_key_index` is returned in place of the removed
-    `payer_secret`
+- `getOfferInvoice`: Seed derived `payer_key_index` replaces `payer_secret`
 
 ## Version 9.3.0
 

package/network/constants.json

@@ -0,0 +1,18 @@
+{
+  "accessDeniedMessages": [
+    "^cannot determine data format of binary-encoded macaroon",
+    "^empty macaroon data",
+    "^expected 1 macaroon",
+    "^invalid ID$",
+    "^permission denied$",
+    "^unknown macaroon version",
+    "^unmarshal v[12]",
+    "^verification failed"
+  ],
+  "codeInvalidArgument": 3,
+  "codePermissionDenied": 7,
+  "codeUnauthenticated": 16,
+  "codeUnimplemented": 12,
+  "knownHopRecordTypes": ["1", "2", "4", "6", "8", "10", "12", "14"],
+  "typePathId": "6"
+}

package/network/get_message_hops.js

@@ -1,7 +1,9 @@
 const asyncAuto = require('async/auto');
 const asyncRetry = require('async/retry');
+const {getChannels} = require('ln-service');
 const {getIdentity} = require('ln-service');
 const {getPeers} = require('ln-service');
+const {getWalletInfo} = require('ln-service');
 const {returnResult} = require('asyncjs-util');
 
 const getRelayingRoute = require('./get_relaying_route');
@@ -19,8 +21,19 @@ const onlyChannelsBits = [66, 67];
   payment route found from the destination to self, through nodes that relay
   messages.
 
+  When a reply is expected back along the same nodes, and self only takes
+  messages from peers with a channel, a connected destination is only sent to
+  directly when it has a channel with self, since the reply comes back from
+  it.
+
+  The route is found over the channels that are known, the channels of the
+  public graph and the channels of self, so a destination that can only be
+  reached through unannounced channels of other nodes, as when self is only
+  connected through a peer that is itself private, is not supported.
+
   {
     destination: <Destination Node Public Key Hex String>
+    [is_expecting_reply]: <Reply Comes Back Along the Same Nodes Bool>
     lnd: <Authenticated LND API Object>
   }
 
@@ -29,17 +42,17 @@ const onlyChannelsBits = [66, 67];
     hops: [<Message Hop Public Key Hex String>]
   }
 */
-module.exports = ({destination, lnd}, cbk) => {
+module.exports = (args, 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') {
+        if (!args.destination || typeof args.destination !== 'string') {
           return cbk([400, 'ExpectedDestinationToGetMessageHops']);
         }
 
-        if (!lnd) {
+        if (!args.lnd) {
           return cbk([400, 'ExpectedLndToGetMessageHops']);
         }
 
@@ -47,26 +60,67 @@ module.exports = ({destination, lnd}, cbk) => {
       },
 
       // Node keys are compared in lowercase, as LND gives them
-      key: ['validate', ({}, cbk) => cbk(null, destination.toLowerCase())],
+      key: ['validate', ({}, cbk) => {
+        return cbk(null, args.destination.toLowerCase());
+      }],
 
       // Get the connected peers
-      getPeers: ['validate', ({}, cbk) => getPeers({lnd}, cbk)],
+      getPeers: ['validate', ({}, cbk) => getPeers({lnd: args.lnd}, cbk)],
 
-      // A connected destination is sent to directly unless it needs a channel
-      isDirect: ['getPeers', 'key', ({getPeers, key}, cbk) => {
+      // A connected destination is a direct hop unless it needs a channel
+      isPeer: ['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 features of self when a reply comes back from the destination
+      getFeatures: ['isPeer', ({isPeer}, cbk) => {
+        // Exit early when the destination is not sent to directly anyway
+        if (!isPeer || !args.is_expecting_reply) {
+          return cbk();
+        }
+
+        return getWalletInfo({lnd: args.lnd}, cbk);
+      }],
+
+      // Get the channels with the destination when the reply needs a channel
+      getChannels: ['getFeatures', 'key', ({getFeatures, key}, cbk) => {
+        // Exit early when self takes messages from peers without a channel
+        if (!getFeatures || !hasBit(getFeatures.features, onlyChannelsBits)) {
+          return cbk();
+        }
+
+        return getChannels({lnd: args.lnd, partner_public_key: key}, cbk);
+      }],
+
+      // A connected destination also has a channel when the reply needs one
+      isDirect: ['getChannels', 'isPeer', ({getChannels, isPeer}, cbk) => {
+        // Exit early when the channels were not needed
+        if (!getChannels) {
+          return cbk(null, isPeer);
+        }
+
+        return cbk(null, !!getChannels.channels.length);
+      }],
+
       // Get the identity key of self, which routes are found back to
-      getIdentity: ['isDirect', ({isDirect}, cbk) => {
+      getIdentity: [
+        'getFeatures',
+        'isDirect',
+        ({getFeatures, isDirect}, cbk) =>
+      {
         // Exit early when the destination is sent to directly
         if (isDirect) {
           return cbk();
         }
 
-        return getIdentity({lnd}, cbk);
+        // Exit early when the identity key came with the features
+        if (!!getFeatures) {
+          return cbk(null, {public_key: getFeatures.public_key});
+        }
+
+        return getIdentity({lnd: args.lnd}, cbk);
       }],
 
       // Find a series of nodes to relay the message
@@ -95,9 +149,9 @@ module.exports = ({destination, lnd}, cbk) => {
         return asyncRetry({errorFilter: isRetry, times: maxAttempts}, cbk => {
           return getRelayingRoute({
             ignore,
-            lnd,
             source,
             destination: key,
+            lnd: args.lnd,
             peers: getPeers.peers,
           },
           (err, res) => {

package/network/get_path_after_self.js

@@ -0,0 +1,222 @@
+const asyncAuto = require('async/auto');
+const {decryptBlindedPath} = require('bolt04');
+const {diffieHellmanComputeSecret} = require('ln-service');
+const {getChannel} = require('ln-service');
+const {getChannels} = require('ln-service');
+const {returnResult} = require('asyncjs-util');
+
+const {knownHopRecordTypes} = require('./constants');
+const {typePathId} = require('./constants');
+
+const hasPathId = records => records.some(n => n.type === typePathId);
+const hopsAfterFirst = hops => hops.slice(1);
+const idsOf = channel => [channel.id].concat(channel.other_ids);
+const {isArray} = Array;
+const isEven = type => !(BigInt(type) % BigInt(2));
+const isKnown = record => knownHopRecordTypes.includes(record.type);
+const isPublicKey = n => typeof n === 'string' && /^[0-9A-F]{66}$/i.test(n);
+const isUnknownEven = record => !isKnown(record) && isEven(record.type);
+
+/** Get the blinded path after self, for a blinded path that starts at self
+
+  Self reads its own hop as an introduction node would. The path goes on from
+  the next node, which the hop names, or which is the peer at the other end
+  of the channel that the hop names.
+
+  As BOLT 4 asks of a node that forwards, the hop of self is not used when it
+  has an unknown even record, when it has a path id, or when it allows
+  features, since no onion message features are defined.
+
+  {
+    hops: [{
+      encrypted_data: <Encrypted Recipient Data Hex String>
+      relay_key: <Blinded Relaying Node Public Key Hex String>
+    }]
+    identity: <Node Identity Public Key Hex String>
+    key: <First Hop Path Key Public Key Hex String>
+    lnd: <Authenticated LND API Object>
+  }
+
+  @returns via cbk or Promise
+  {
+    hops: [{
+      encrypted_data: <Encrypted Recipient Data Hex String>
+      relay_key: <Blinded Relaying Node Public Key Hex String>
+    }]
+    introduction_node: <Next Node Public Key Hex String>
+    key: <Next Hop Path Key Public Key Hex String>
+  }
+*/
+module.exports = (args, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!isArray(args.hops) || !args.hops.length) {
+          return cbk([400, 'ExpectedBlindedPathHopsToGetPathAfterSelf']);
+        }
+
+        if (!isPublicKey(args.identity)) {
+          return cbk([400, 'ExpectedIdentityPublicKeyToGetPathAfterSelf']);
+        }
+
+        if (!args.key) {
+          return cbk([400, 'ExpectedPathKeyToGetPathAfterSelf']);
+        }
+
+        if (!args.lnd) {
+          return cbk([400, 'ExpectedLndToGetPathAfterSelf']);
+        }
+
+        return cbk();
+      },
+
+      // Compute the shared secret of the path key and the node identity key
+      getSecret: ['validate', ({}, cbk) => {
+        return diffieHellmanComputeSecret({
+          lnd: args.lnd,
+          partner_public_key: args.key,
+        },
+        cbk);
+      }],
+
+      // Decrypt the data of the hop of self to read where the path goes next
+      decrypt: ['getSecret', ({getSecret}, cbk) => {
+        const [own] = args.hops;
+
+        try {
+          return cbk(null, decryptBlindedPath({
+            encrypted: own.encrypted_data,
+            key: args.key,
+            secret: getSecret.secret,
+          }));
+        } catch (err) {
+          return cbk([503, 'FailedToDecryptOwnBlindedPathHop', {err}]);
+        }
+      }],
+
+      // Check the hop of self can be followed, as a forwarding node would
+      check: ['decrypt', ({decrypt}, cbk) => {
+        // An unknown even record cannot be ignored, so the hop cannot be used
+        if (decrypt.records.some(isUnknownEven)) {
+          return cbk([
+            400,
+            'UnexpectedUnknownRequiredRecordInOwnBlindedPathHop',
+          ]);
+        }
+
+        // No features are defined for onion messages, so a feature bit in
+        // the allowed features is an unknown feature, and the hop is not used
+        if (!!decrypt.features.length) {
+          return cbk([400, 'UnsupportedFeatureInOwnBlindedPathHop']);
+        }
+
+        // A hop with no next node or channel is the final hop of the path
+        if (!decrypt.next_node_id && !decrypt.next_channel_id) {
+          return cbk([400, 'UnexpectedBlindedPathToSelf']);
+        }
+
+        // A hop that goes on to a next node is not one with a path id record,
+        // which is present even when the path id is empty
+        if (hasPathId(decrypt.records)) {
+          return cbk([400, 'UnexpectedPathIdInOwnBlindedPathHop']);
+        }
+
+        return cbk();
+      }],
+
+      // The hops after self, which the path goes on over
+      hops: ['check', ({}, cbk) => {
+        const hops = hopsAfterFirst(args.hops);
+
+        // The next node has a hop of its own to send to
+        if (!hops.length) {
+          return cbk([400, 'ExpectedHopsAfterSelfInBlindedPath']);
+        }
+
+        return cbk(null, hops);
+      }],
+
+      // Get the channels of self when the next node is named by a channel
+      getChannels: ['decrypt', 'hops', ({decrypt}, cbk) => {
+        // Exit early when the hop names the next node
+        if (!!decrypt.next_node_id) {
+          return cbk();
+        }
+
+        return getChannels({lnd: args.lnd}, cbk);
+      }],
+
+      // Find the next channel among the channels of self
+      channel: ['decrypt', 'getChannels', ({decrypt, getChannels}, cbk) => {
+        // Exit early when the hop names the next node
+        if (!getChannels) {
+          return cbk();
+        }
+
+        const id = decrypt.next_channel_id;
+
+        // A private channel can be named by one of its aliases
+        return cbk(null, getChannels.channels.find(n => idsOf(n).includes(id)));
+      }],
+
+      // Look for the next channel in the graph when self does not list it
+      getChannel: ['channel', 'decrypt', ({channel, decrypt}, cbk) => {
+        // Exit early when the next node is already known
+        if (!!decrypt.next_node_id || !!channel) {
+          return cbk();
+        }
+
+        return getChannel({
+          id: decrypt.next_channel_id,
+          lnd: args.lnd,
+        },
+        (err, res) => {
+          // Exit early when the channel is not in the graph
+          if (!!err) {
+            return cbk([503, 'FailedToFindNextPeerInBlindedPath']);
+          }
+
+          return cbk(null, res);
+        });
+      }],
+
+      // The next node is the one that the hop names, or is across the channel
+      next: [
+        'channel',
+        'decrypt',
+        'getChannel',
+        ({channel, decrypt, getChannel}, cbk) =>
+      {
+        // Exit early when the hop names the next node
+        if (!!decrypt.next_node_id) {
+          return cbk(null, decrypt.next_node_id);
+        }
+
+        // Exit early when the channel is a channel of self
+        if (!!channel) {
+          return cbk(null, channel.partner_public_key);
+        }
+
+        const keys = getChannel.policies.map(n => n.public_key);
+
+        // The channel in the graph has to be one that self forwards over
+        if (!keys.includes(args.identity)) {
+          return cbk([503, 'FailedToFindNextPeerInBlindedPath']);
+        }
+
+        return cbk(null, keys.find(n => n !== args.identity));
+      }],
+
+      // The path goes on from the next node, with the next hop path key
+      path: ['decrypt', 'hops', 'next', ({decrypt, hops, next}, cbk) => {
+        return cbk(null, {
+          hops,
+          introduction_node: next,
+          key: decrypt.next_path_key,
+        });
+      }],
+    },
+    returnResult({reject, resolve, of: 'path'}, cbk));
+  });
+};

package/network/get_path_outbound.js

@@ -1,80 +1,170 @@
 const asyncAuto = require('async/auto');
+const asyncWhilst = require('async/whilst');
 const {getChannel} = require('ln-service');
+const {getIdentity} = require('ln-service');
 const {returnResult} = require('asyncjs-util');
 
 const getMessageHops = require('./get_message_hops');
+const getPathAfterSelf = require('./get_path_after_self');
 const pathIntroduction = require('./path_introduction');
 
 const edgeChannel = edge => edge.split('x').slice(0, -1).join('x');
+const {isArray} = Array;
+const isPublicKey = n => typeof n === 'string' && /^[0-9A-F]{66}$/i.test(n);
 
-/** Get the outbound hops to reach the introduction node of a blinded path
+/** Get the outbound hops to reach the introduction node of a blinded path,
+  with the hops and the path key to send over
 
   When the introduction node is not a connected peer, the message is relayed
   along a payment route through nodes that relay onion messages
 
+  A path that starts at self is sent from the next node of the path: self
+  reads its own hops, as an introduction node would, and sends over the hops
+  after them. A path that does not start at self is sent over as it is.
+
   {
+    [is_expecting_reply]: <Reply Comes Back Along the Same Nodes Bool>
     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>
     }
   }
 
   @returns via cbk or Promise
   {
+    hops: [{
+      encrypted_data: <Encrypted Recipient Data Hex String>
+      relay_key: <Blinded Relaying Node Public Key Hex String>
+    }]
+    key: <First Hop Path Key Public Key Hex String>
     outbound: [<Relaying Node Public Key Hex String>]
   }
 */
-module.exports = ({lnd, path}, cbk) => {
+module.exports = (args, cbk) => {
   return new Promise((resolve, reject) => {
     return asyncAuto({
       // Check arguments
       validate: cbk => {
-        if (!lnd) {
+        if (!args.lnd) {
           return cbk([400, 'ExpectedLndToGetPathOutbound']);
         }
 
-        if (!path) {
+        if (!args.path) {
           return cbk([400, 'ExpectedBlindedPathToGetPathOutbound']);
         }
 
+        if (!isArray(args.path.hops) || !args.path.hops.length) {
+          return cbk([400, 'ExpectedBlindedPathHopsToGetPathOutbound']);
+        }
+
+        // A node introduction is compared to self as a public key
+        if (!!args.path.introduction_node) {
+          if (!isPublicKey(args.path.introduction_node)) {
+            return cbk([400, 'ExpectedIntroductionNodeKeyToGetPathOutbound']);
+          }
+        }
+
+        if (!args.path.key) {
+          return cbk([400, 'ExpectedBlindedPathKeyToGetPathOutbound']);
+        }
+
         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) {
+        if (!args.path.introduction_edge) {
           return cbk();
         }
 
-        const id = edgeChannel(path.introduction_edge);
+        const id = edgeChannel(args.path.introduction_edge);
 
-        return getChannel({id, lnd}, cbk);
+        return getChannel({id, lnd: args.lnd}, cbk);
+      }],
+
+      // Get the identity key of self, which the path can start at
+      getIdentity: ['validate', ({}, cbk) => {
+        return getIdentity({lnd: args.lnd}, cbk);
       }],
 
       // Determine the introduction node of the path
       introduction: ['getChannel', ({getChannel}, cbk) => {
         try {
           const {introduction} = pathIntroduction({
-            path,
             channel: getChannel,
+            path: args.path,
           });
 
-          return cbk(null, introduction);
+          // Node keys are compared in lowercase, as LND gives them
+          return cbk(null, introduction.toLowerCase());
         } catch (err) {
           return cbk([400, err.message]);
         }
       }],
 
+      // Step past the hops of self while the path starts at self
+      stepped: [
+        'getIdentity',
+        'introduction',
+        ({getIdentity, introduction}, cbk) =>
+      {
+        const identity = getIdentity.public_key;
+
+        let path = {
+          hops: args.path.hops,
+          introduction_node: introduction,
+          key: args.path.key,
+        };
+
+        // Self reads its own hop as an introduction node would, and the path
+        // goes on from the next node, which can be self again
+        return asyncWhilst(
+          cbk => cbk(null, path.introduction_node === identity),
+          cbk => {
+            return getPathAfterSelf({
+              identity,
+              hops: path.hops,
+              key: path.key,
+              lnd: args.lnd,
+            },
+            (err, res) => {
+              if (!!err) {
+                return cbk(err);
+              }
+
+              path = res;
+
+              return cbk();
+            });
+          },
+          err => !!err ? cbk(err) : cbk(null, path)
+        );
+      }],
+
       // Get the hops to relay the message to the introduction node
-      getHops: ['introduction', ({introduction}, cbk) => {
-        return getMessageHops({lnd, destination: introduction}, cbk);
+      getHops: ['stepped', ({stepped}, cbk) => {
+        return getMessageHops({
+          destination: stepped.introduction_node,
+          is_expecting_reply: args.is_expecting_reply,
+          lnd: args.lnd,
+        },
+        cbk);
       }],
 
-      // The outbound hops end at the introduction node
-      outbound: ['getHops', ({getHops}, cbk) => {
-        return cbk(null, {outbound: getHops.hops});
+      // The outbound hops end at the introduction node of the path to send
+      outbound: ['getHops', 'stepped', ({getHops, stepped}, cbk) => {
+        return cbk(null, {
+          hops: stepped.hops,
+          key: stepped.key,
+          outbound: getHops.hops,
+        });
       }],
     },
     returnResult({reject, resolve, of: 'outbound'}, cbk));

package/network/make_network_request.js

@@ -17,7 +17,8 @@ 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 destination, with the response returned over a reply path back along
+  the route of the request
 
   The request fails when no response arrives within the `timeout`.