lightning 4.7.1 → 4.10.0

package/CHANGELOG.md

@@ -1,6 +1,20 @@
 # Versions
 
-## 4.7.1
+## 4.10.0
+
+- `getChannels`: Add `past_states` to reflect the number of updates
+- `subscribeToChannels`: Add `past_states` to reflect to number of updates
+
+## 4.9.0
+
+- `grantAccess`: Add support for specifying `methods` for permissions
+
+## 4.8.0
+
+- `updateRoutingFees`: Add `failures` to indicate failed policy updates
+- `verifyAccess`: Add method to confirm a macaroon has given permissions
+
+## 4.7.2
 
 - `getPayment`: Add `created_at` to indicate the creation date of the payment
 - `getPayment`: Add `request` to indicate serialized payment request

package/README.md

@@ -89,6 +89,8 @@ Methods exported by this library support typescript, but ln-service includes add
     Remove failed payments from the database.
 - [deleteForwardingReputations](https://github.com/alexbosworth/ln-service#deleteforwardingreputations)
     Clear pathfinding reputations of routing nodes and channels.
+- [deletePayment](https://github.com/alexbosworth/ln-service#deletepayment): Remove a
+    past payment record.
 - [deletePayments](https://github.com/alexbosworth/ln-service#deletepayments): Remove all
     past payment records.
 - [diffieHellmanComputeSecret](https://github.com/alexbosworth/ln-service#diffiehellmancomputesecret):
@@ -295,6 +297,8 @@ Methods exported by this library support typescript, but ln-service includes add
     Edit the configuration for routing calculations
 - [updateRoutingFees](https://github.com/alexbosworth/ln-service#updateroutingfees): Set the
     forwarding fees or other routing policies for a channel or all channels.
+- [verifyAccess](https://github.com/alexbosworth/ln-service#verifyaccess): Confirm a macaroon
+    has permission to access a given resource.
 - [verifyBackup](https://github.com/alexbosworth/ln-service#verifybackup): Check if a channel fund
     recovery backup file is valid.
 - [verifyBackups](https://github.com/alexbosworth/ln-service#verifybackups): Check if multiple

package/grpc/handle_remove_listener.js

@@ -0,0 +1,25 @@
+const sumOf = arr => arr.reduce((sum, n) => sum + n, Number());
+
+/** Get a function that emits an error from a gRPC subscription proxy
+
+  {
+    emitter: <EventEmitter Subscription Proxy Object>
+    events: [<Event Name String>]
+    subscription: <gRPC Subscription Object>
+  }
+*/
+module.exports = ({emitter, events, subscription}) => {
+  // Cancel the subscription when all listeners are removed
+  emitter.on('removeListener', () => {
+    const counts = events.map(n => emitter.listenerCount(n));
+
+    // Exit early when there are still active listeners
+    if (!!sumOf(counts)) {
+      return;
+    }
+
+    subscription.cancel();
+
+    return;
+  });
+};

package/grpc/index.js

@@ -1,6 +1,7 @@
 const {defaultSocket} = require('./grpc_services');
 const emitSubscriptionError = require('./emit_subscription_error');
 const {grpcSslCipherSuites} = require('./grpc_services');
+const handleRemoveListener = require('./handle_remove_listener');
 const {maxReceiveMessageLength} = require('./grpc_services');
 const {packageTypes} = require('./grpc_services');
 const {protoFiles} = require('./grpc_services');
@@ -13,6 +14,7 @@ module.exports = {
   defaultSocket,
   emitSubscriptionError,
   grpcSslCipherSuites,
+  handleRemoveListener,
   maxReceiveMessageLength,
   packageTypes,
   protoFiles,

package/grpc/protos/lightning.proto

@@ -540,6 +540,23 @@ service Lightning {
     */
     rpc CheckMacaroonPermissions (CheckMacPermRequest)
         returns (CheckMacPermResponse);
+
+    /*
+    RegisterRPCMiddleware adds a new gRPC middleware to the interceptor chain. A
+    gRPC middleware is software component external to lnd that aims to add
+    additional business logic to lnd by observing/intercepting/validating
+    incoming gRPC client requests and (if needed) replacing/overwriting outgoing
+    messages before they're sent to the client. When registering the middleware
+    must identify itself and indicate what custom macaroon caveats it wants to
+    be responsible for. Only requests that contain a macaroon with that specific
+    custom caveat are then sent to the middleware for inspection. The other
+    option is to register for the read-only mode in which all requests/responses
+    are forwarded for interception to the middleware but the middleware is not
+    allowed to modify any responses. As a security measure, _no_ middleware can
+    modify responses for requests made with _unencumbered_ macaroons!
+    */
+    rpc RegisterRPCMiddleware (stream RPCMiddlewareResponse)
+        returns (stream RPCMiddlewareRequest);
 }
 
 message Utxo {
@@ -1140,6 +1157,11 @@ message HTLC {
 }
 
 enum CommitmentType {
+    /*
+    Returned when the commitment type isn't known or unavailable.
+    */
+    UNKNOWN_COMMITMENT_TYPE = 999;
+
     /*
     A channel using the legacy commitment format having tweaked to_remote
     keys.
@@ -1160,11 +1182,6 @@ enum CommitmentType {
     been broadcast.
     */
     ANCHORS = 2;
-
-    /*
-    Returned when the commitment type isn't known or unavailable.
-    */
-    UNKNOWN_COMMITMENT_TYPE = 999;
 }
 
 message ChannelConstraints {
@@ -2219,6 +2236,9 @@ message PendingChannelsResponse {
 
         // The commitment type used by this channel.
         CommitmentType commitment_type = 9;
+
+        // Total number of forwarding packages created in this channel.
+        int64 num_forwarding_packages = 10;
     }
 
     message PendingOpenChannel {
@@ -3635,7 +3655,28 @@ message PolicyUpdateRequest {
     // If true, min_htlc_msat is applied.
     bool min_htlc_msat_specified = 8;
 }
+enum UpdateFailure {
+    UPDATE_FAILURE_UNKNOWN = 0;
+    UPDATE_FAILURE_PENDING = 1;
+    UPDATE_FAILURE_NOT_FOUND = 2;
+    UPDATE_FAILURE_INTERNAL_ERR = 3;
+    UPDATE_FAILURE_INVALID_PARAMETER = 4;
+}
+
+message FailedUpdate {
+    // The outpoint in format txid:n
+    OutPoint outpoint = 1;
+
+    // Reason for the policy update failure.
+    UpdateFailure reason = 2;
+
+    // A string representation of the policy update error.
+    string update_error = 3;
+}
+
 message PolicyUpdateResponse {
+    // List of failed policy updates.
+    repeated FailedUpdate failed_updates = 1;
 }
 
 message ForwardingHistoryRequest {
@@ -3803,6 +3844,12 @@ message BakeMacaroonRequest {
 
     // The root key ID used to create the macaroon, must be a positive integer.
     uint64 root_key_id = 2;
+
+    /*
+    Informs the RPC on whether to allow external permissions that LND is not
+    aware of.
+    */
+    bool allow_external_permissions = 3;
 }
 message BakeMacaroonResponse {
     // The hex encoded macaroon, serialized in binary format.
@@ -4024,3 +4071,188 @@ message CheckMacPermRequest {
 message CheckMacPermResponse {
     bool valid = 1;
 }
+
+message RPCMiddlewareRequest {
+    /*
+    The unique ID of the intercepted request. Useful for mapping request to
+    response when implementing full duplex message interception.
+    */
+    uint64 request_id = 1;
+
+    /*
+    The raw bytes of the complete macaroon as sent by the gRPC client in the
+    original request. This might be empty for a request that doesn't require
+    macaroons such as the wallet unlocker RPCs.
+    */
+    bytes raw_macaroon = 2;
+
+    /*
+    The parsed condition of the macaroon's custom caveat for convenient access.
+    This field only contains the value of the custom caveat that the handling
+    middleware has registered itself for. The condition _must_ be validated for
+    messages of intercept_type stream_auth and request!
+    */
+    string custom_caveat_condition = 3;
+
+    /*
+    There are three types of messages that will be sent to the middleware for
+    inspection and approval: Stream authentication, request and response
+    interception. The first two can only be accepted (=forward to main RPC
+    server) or denied (=return error to client). Intercepted responses can also
+    be replaced/overwritten.
+    */
+    oneof intercept_type {
+        /*
+        Intercept stream authentication: each new streaming RPC call that is
+        initiated against lnd and contains the middleware's custom macaroon
+        caveat can be approved or denied based upon the macaroon in the stream
+        header. This message will only be sent for streaming RPCs, unary RPCs
+        must handle the macaroon authentication in the request interception to
+        avoid an additional message round trip between lnd and the middleware.
+        */
+        StreamAuth stream_auth = 4;
+
+        /*
+        Intercept incoming gRPC client request message: all incoming messages,
+        both on streaming and unary RPCs, are forwarded to the middleware for
+        inspection. For unary RPC messages the middleware is also expected to
+        validate the custom macaroon caveat of the request.
+        */
+        RPCMessage request = 5;
+
+        /*
+        Intercept outgoing gRPC response message: all outgoing messages, both on
+        streaming and unary RPCs, are forwarded to the middleware for inspection
+        and amendment. The response in this message is the original response as
+        it was generated by the main RPC server. It can either be accepted
+        (=forwarded to the client), replaced/overwritten with a new message of
+        the same type, or replaced by an error message.
+        */
+        RPCMessage response = 6;
+    }
+}
+
+message StreamAuth {
+    /*
+    The full URI (in the format /<rpcpackage>.<ServiceName>/MethodName, for
+    example /lnrpc.Lightning/GetInfo) of the streaming RPC method that was just
+    established.
+    */
+    string method_full_uri = 1;
+}
+
+message RPCMessage {
+    /*
+    The full URI (in the format /<rpcpackage>.<ServiceName>/MethodName, for
+    example /lnrpc.Lightning/GetInfo) of the RPC method the message was sent
+    to/from.
+    */
+    string method_full_uri = 1;
+
+    /*
+    Indicates whether the message was sent over a streaming RPC method or not.
+    */
+    bool stream_rpc = 2;
+
+    /*
+    The full canonical gRPC name of the message type (in the format
+    <rpcpackage>.TypeName, for example lnrpc.GetInfoRequest).
+    */
+    string type_name = 3;
+
+    /*
+    The full content of the gRPC message, serialized in the binary protobuf
+    format.
+    */
+    bytes serialized = 4;
+}
+
+message RPCMiddlewareResponse {
+    /*
+    The unique ID of the intercepted request that this response refers to. Must
+    always be set when giving feedback to an intercept but is ignored for the
+    initial registration message.
+    */
+    uint64 request_id = 1;
+
+    /*
+    The middleware can only send two types of messages to lnd: The initial
+    registration message that identifies the middleware and after that only
+    feedback messages to requests sent to the middleware.
+    */
+    oneof middleware_message {
+        /*
+        The registration message identifies the middleware that's being
+        registered in lnd. The registration message must be sent immediately
+        after initiating the RegisterRpcMiddleware stream, otherwise lnd will
+        time out the attempt and terminate the request. NOTE: The middleware
+        will only receive interception messages for requests that contain a
+        macaroon with the custom caveat that the middleware declares it is
+        responsible for handling in the registration message! As a security
+        measure, _no_ middleware can intercept requests made with _unencumbered_
+        macaroons!
+        */
+        MiddlewareRegistration register = 2;
+
+        /*
+        The middleware received an interception request and gives feedback to
+        it. The request_id indicates what message the feedback refers to.
+        */
+        InterceptFeedback feedback = 3;
+    }
+}
+
+message MiddlewareRegistration {
+    /*
+    The name of the middleware to register. The name should be as informative
+    as possible and is logged on registration.
+    */
+    string middleware_name = 1;
+
+    /*
+    The name of the custom macaroon caveat that this middleware is responsible
+    for. Only requests/responses that contain a macaroon with the registered
+    custom caveat are forwarded for interception to the middleware. The
+    exception being the read-only mode: All requests/responses are forwarded to
+    a middleware that requests read-only access but such a middleware won't be
+    allowed to _alter_ responses. As a security measure, _no_ middleware can
+    change responses to requests made with _unencumbered_ macaroons!
+    NOTE: Cannot be used at the same time as read_only_mode.
+    */
+    string custom_macaroon_caveat_name = 2;
+
+    /*
+    Instead of defining a custom macaroon caveat name a middleware can register
+    itself for read-only access only. In that mode all requests/responses are
+    forwarded to the middleware but the middleware isn't allowed to alter any of
+    the responses.
+    NOTE: Cannot be used at the same time as custom_macaroon_caveat_name.
+    */
+    bool read_only_mode = 3;
+}
+
+message InterceptFeedback {
+    /*
+    The error to return to the user. If this is non-empty, the incoming gRPC
+    stream/request is aborted and the error is returned to the gRPC client. If
+    this value is empty, it means the middleware accepts the stream/request/
+    response and the processing of it can continue.
+    */
+    string error = 1;
+
+    /*
+    A boolean indicating that the gRPC response should be replaced/overwritten.
+    As its name suggests, this can only be used as a feedback to an intercepted
+    response RPC message and is ignored for feedback on any other message. This
+    boolean is needed because in protobuf an empty message is serialized as a
+    0-length or nil byte slice and we wouldn't be able to distinguish between
+    an empty replacement message and the "don't replace anything" case.
+    */
+    bool replace_response = 2;
+
+    /*
+    If the replace_response field is set to true, this field must contain the
+    binary serialized gRPC response message in the protobuf format.
+    */
+    bytes replacement_serialized = 3;
+}

package/index.js

@@ -123,6 +123,7 @@ const {updateConnectedWatchtower} = require('./lnd_methods');
 const {updateChainTransaction} = require('./lnd_methods');
 const {updatePathfindingSettings} = require('./lnd_methods');
 const {updateRoutingFees} = require('./lnd_methods');
+const {verifyAccess} = require('./lnd_methods');
 const {verifyBackup} = require('./lnd_methods');
 const {verifyBackups} = require('./lnd_methods');
 const {verifyBytesSignature} = require('./lnd_methods');
@@ -254,6 +255,7 @@ module.exports = {
   updateChainTransaction,
   updatePathfindingSettings,
   updateRoutingFees,
+  verifyAccess,
   verifyBackup,
   verifyBackups,
   verifyBytesSignature,

package/lnd_methods/index.js

@@ -111,6 +111,7 @@ const {subscribeToPayViaRequest} = require('./offchain');
 const {subscribeToPayViaRoutes} = require('./offchain');
 const {subscribeToPeers} = require('./peers');
 const {subscribeToProbeForRoute} = require('./offchain');
+const {subscribeToRpcRequests} = require('./macaroon');
 const {subscribeToTransactions} = require('./onchain');
 const {subscribeToWalletStatus} = require('./unauthenticated');
 const {unlockUtxo} = require('./onchain');
@@ -239,6 +240,7 @@ module.exports = {
   subscribeToPayViaRoutes,
   subscribeToPeers,
   subscribeToProbeForRoute,
+  subscribeToRpcRequests,
   subscribeToTransactions,
   subscribeToWalletStatus,
   unlockUtxo,

package/lnd_methods/info/constants.json

@@ -25,6 +25,7 @@
     "596fd90ef310cd7abbf2251edaae9ba4d5f8a689": "0.13.1-beta",
     "725ff104808f49f0a5247bfdb4b6b5da7f488d38": "0.13.0-beta",
     "7f34774529fa0964d47fc418d4d2965435cbfdc0": "0.11.1-beta",
+    "86d3dec7b939b21bb10f2cd1ff56970c392a1c69": "0.13.2-beta",
     "86114c575c2dff9dff1e1bb4df961c64aea9fc1c": "0.10.4-beta",
     "d176d2d65fc06e6631c4dc9478592be8545a21de": "0.12.0-beta",
     "d233f61383f2f950aa06f5b09da5b0e78e784fae": "0.12.1-beta",

package/lnd_methods/macaroon/grant_access.d.ts

@@ -44,6 +44,8 @@ export type GrantAccessArgs = AuthenticatedLightningArgs<{
   is_ok_to_verify_bytes_signatures?: boolean;
   /** Can Verify Messages From Node Keys */
   is_ok_to_verify_messages?: boolean;
+  /** Method Name */
+  methods?: string[];
   /** Entity:Action */
   permissions?: string[];
 }>;

package/lnd_methods/macaroon/grant_access.js

@@ -3,8 +3,10 @@ const {returnResult} = require('asyncjs-util');
 
 const {isLnd} = require('./../../lnd_requests');
 const permissions = require('./permissions');
+const urisForMethod = require('./uris_for_method');
 
 const accessDenied = 'permission denied';
+const flatten = arr => [].concat(...arr);
 const hexAsBase64 = hex => Buffer.from(hex, 'hex').toString('base64');
 const isHex = n => !!n && !(n.length % 2) && /^[0-9A-F]*$/i.test(n);
 const {keys} = Object;
@@ -12,6 +14,8 @@ const method = 'bakeMacaroon';
 const notSupported = 'unknown service lnrpc.Lightning';
 const permissionSeparator = ':';
 const type = 'default';
+const uniq = arr => Array.from(new Set(arr));
+const uriAsPermission = uri => `uri:${uri}`;
 
 /** Give access to the node by making a macaroon access credential
 
@@ -24,6 +28,8 @@ const type = 'default';
 
   Note: `id` is not supported in LND versions 0.11.0 and below
 
+  `methods` is not supported in LND versions 0.11.0 and below
+
   {
     [id]: <Macaroon Id Positive Numeric String>
     [is_ok_to_adjust_peers]: <Can Add or Remove Peers Bool>
@@ -46,6 +52,7 @@ const type = 'default';
     [is_ok_to_verify_bytes_signatures]: <Can Verify Signatures of Bytes Bool>
     [is_ok_to_verify_messages]: <Can Verify Messages From Node Keys Bool>
     lnd: <Authenticated LND API Object>
+    [methods]: [<Method Name String>]
     [permissions]: [<Entity:Action String>]
   }
 
@@ -71,9 +78,25 @@ module.exports = (args, cbk) => {
         return cbk();
       },
 
+      // Derive URI permissions
+      uris: ['validate', ({}, cbk) => {
+        try {
+          const uris = (args.methods || []).map(method => {
+            return urisForMethod({method}).uris;
+          });
+
+          const permissions = uniq(flatten(uris)).map(uriAsPermission);
+
+          return cbk(null, permissions);
+        } catch (err) {
+          return cbk([400, err.message]);
+        }
+      }],
+
       // Permissions to grant
-      permissions: ['validate', ({}, cbk) => {
+      permissions: ['uris', ({uris}, cbk) => {
         const access = []
+          .concat(uris)
           .concat(keys(permissions).filter(n => !!args[permissions[n]]))
           .concat(args.permissions || []);
 

package/lnd_methods/macaroon/index.d.ts

@@ -1,3 +1,4 @@
 export * from './get_access_ids';
 export * from './grant_access';
 export * from './revoke_access';
+export * from './verify_access';

package/lnd_methods/macaroon/index.js

@@ -1,6 +1,13 @@
 const getAccessIds = require('./get_access_ids');
 const grantAccess = require('./grant_access');
 const revokeAccess = require('./revoke_access');
+const subscribeToRpcRequests = require('./subscribe_to_rpc_requests');
 const verifyAccess = require('./verify_access');
 
-module.exports = {getAccessIds, grantAccess, revokeAccess, verifyAccess};
+module.exports = {
+  getAccessIds,
+  grantAccess,
+  revokeAccess,
+  subscribeToRpcRequests,
+  verifyAccess,
+};