Merge pull request #5101 from guggero/macaroon-interceptor

Add macaroon based RPC middleware interceptor

lnrpc/lightning.pb.gw.go

@@ -2251,6 +2251,58 @@ func local_request_Lightning_CheckMacaroonPermissions_0(ctx context.Context, mar
 
 }
 
+func request_Lightning_RegisterRPCMiddleware_0(ctx context.Context, marshaler runtime.Marshaler, client LightningClient, req *http.Request, pathParams map[string]string) (Lightning_RegisterRPCMiddlewareClient, runtime.ServerMetadata, error) {
+	var metadata runtime.ServerMetadata
+	stream, err := client.RegisterRPCMiddleware(ctx)
+	if err != nil {
+		grpclog.Infof("Failed to start streaming: %v", err)
+		return nil, metadata, err
+	}
+	dec := marshaler.NewDecoder(req.Body)
+	handleSend := func() error {
+		var protoReq RPCMiddlewareResponse
+		err := dec.Decode(&protoReq)
+		if err == io.EOF {
+			return err
+		}
+		if err != nil {
+			grpclog.Infof("Failed to decode request: %v", err)
+			return err
+		}
+		if err := stream.Send(&protoReq); err != nil {
+			grpclog.Infof("Failed to send request: %v", err)
+			return err
+		}
+		return nil
+	}
+	if err := handleSend(); err != nil {
+		if cerr := stream.CloseSend(); cerr != nil {
+			grpclog.Infof("Failed to terminate client stream: %v", cerr)
+		}
+		if err == io.EOF {
+			return stream, metadata, nil
+		}
+		return nil, metadata, err
+	}
+	go func() {
+		for {
+			if err := handleSend(); err != nil {
+				break
+			}
+		}
+		if err := stream.CloseSend(); err != nil {
+			grpclog.Infof("Failed to terminate client stream: %v", err)
+		}
+	}()
+	header, err := stream.Header()
+	if err != nil {
+		grpclog.Infof("Failed to get header from client: %v", err)
+		return nil, metadata, err
+	}
+	metadata.HeaderMD = header
+	return stream, metadata, nil
+}
+
 // RegisterLightningHandlerServer registers the http handlers for service Lightning to "mux".
 // UnaryRPC     :call LightningServer directly.
 // StreamingRPC :currently unsupported pending https://github.com/grpc/grpc-go/issues/906.
@@ -3500,6 +3552,13 @@ func RegisterLightningHandlerServer(ctx context.Context, mux *runtime.ServeMux,
 
 	})
 
+	mux.Handle("POST", pattern_Lightning_RegisterRPCMiddleware_0, func(w http.ResponseWriter, req *http.Request, pathParams map[string]string) {
+		err := status.Error(codes.Unimplemented, "streaming calls are not yet supported in the in-process transport")
+		_, outboundMarshaler := runtime.MarshalerForRequest(mux, req)
+		runtime.HTTPError(ctx, mux, outboundMarshaler, w, req, err)
+		return
+	})
+
 	return nil
 }
 
@@ -4761,6 +4820,26 @@ func RegisterLightningHandlerClient(ctx context.Context, mux *runtime.ServeMux,
 
 	})
 
+	mux.Handle("POST", pattern_Lightning_RegisterRPCMiddleware_0, func(w http.ResponseWriter, req *http.Request, pathParams map[string]string) {
+		ctx, cancel := context.WithCancel(req.Context())
+		defer cancel()
+		inboundMarshaler, outboundMarshaler := runtime.MarshalerForRequest(mux, req)
+		rctx, err := runtime.AnnotateContext(ctx, mux, req, "/lnrpc.Lightning/RegisterRPCMiddleware", runtime.WithHTTPPathPattern("/v1/middleware"))
+		if err != nil {
+			runtime.HTTPError(ctx, mux, outboundMarshaler, w, req, err)
+			return
+		}
+		resp, md, err := request_Lightning_RegisterRPCMiddleware_0(rctx, inboundMarshaler, client, req, pathParams)
+		ctx = runtime.NewServerMetadataContext(ctx, md)
+		if err != nil {
+			runtime.HTTPError(ctx, mux, outboundMarshaler, w, req, err)
+			return
+		}
+
+		forward_Lightning_RegisterRPCMiddleware_0(ctx, mux, outboundMarshaler, w, req, func() (proto.Message, error) { return resp.Recv() }, mux.GetForwardResponseOptions()...)
+
+	})
+
 	return nil
 }
 
@@ -4886,6 +4965,8 @@ var (
 	pattern_Lightning_ListPermissions_0 = runtime.MustPattern(runtime.NewPattern(1, []int{2, 0, 2, 1, 2, 2}, []string{"v1", "macaroon", "permissions"}, ""))
 
 	pattern_Lightning_CheckMacaroonPermissions_0 = runtime.MustPattern(runtime.NewPattern(1, []int{2, 0, 2, 1, 2, 2}, []string{"v1", "macaroon", "checkpermissions"}, ""))
+
+	pattern_Lightning_RegisterRPCMiddleware_0 = runtime.MustPattern(runtime.NewPattern(1, []int{2, 0, 2, 1}, []string{"v1", "middleware"}, ""))
 )
 
 var (
@@ -5010,4 +5091,6 @@ var (
 	forward_Lightning_ListPermissions_0 = runtime.ForwardResponseMessage
 
 	forward_Lightning_CheckMacaroonPermissions_0 = runtime.ForwardResponseMessage
+
+	forward_Lightning_RegisterRPCMiddleware_0 = runtime.ForwardResponseStream
 )

lnrpc/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 {
@@ -4051,3 +4068,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;
+}

lnrpc/lightning.swagger.json

@@ -1675,6 +1675,49 @@
         ]
       }
     },
+    "/v1/middleware": {
+      "post": {
+        "summary": "RegisterRPCMiddleware adds a new gRPC middleware to the interceptor chain. A\ngRPC middleware is software component external to lnd that aims to add\nadditional business logic to lnd by observing/intercepting/validating\nincoming gRPC client requests and (if needed) replacing/overwriting outgoing\nmessages before they're sent to the client. When registering the middleware\nmust identify itself and indicate what custom macaroon caveats it wants to\nbe responsible for. Only requests that contain a macaroon with that specific\ncustom caveat are then sent to the middleware for inspection. The other\noption is to register for the read-only mode in which all requests/responses\nare forwarded for interception to the middleware but the middleware is not\nallowed to modify any responses. As a security measure, _no_ middleware can\nmodify responses for requests made with _unencumbered_ macaroons!",
+        "operationId": "Lightning_RegisterRPCMiddleware",
+        "responses": {
+          "200": {
+            "description": "A successful response.(streaming responses)",
+            "schema": {
+              "type": "object",
+              "properties": {
+                "result": {
+                  "$ref": "#/definitions/lnrpcRPCMiddlewareRequest"
+                },
+                "error": {
+                  "$ref": "#/definitions/rpcStatus"
+                }
+              },
+              "title": "Stream result of lnrpcRPCMiddlewareRequest"
+            }
+          },
+          "default": {
+            "description": "An unexpected error response.",
+            "schema": {
+              "$ref": "#/definitions/rpcStatus"
+            }
+          }
+        },
+        "parameters": [
+          {
+            "name": "body",
+            "description": " (streaming inputs)",
+            "in": "body",
+            "required": true,
+            "schema": {
+              "$ref": "#/definitions/lnrpcRPCMiddlewareResponse"
+            }
+          }
+        ],
+        "tags": [
+          "Lightning"
+        ]
+      }
+    },
     "/v1/newaddress": {
       "get": {
         "summary": "lncli: `newaddress`\nNewAddress creates a new address under control of the local wallet.",
@@ -4479,6 +4522,24 @@
       ],
       "default": "INITIATOR_UNKNOWN"
     },
+    "lnrpcInterceptFeedback": {
+      "type": "object",
+      "properties": {
+        "error": {
+          "type": "string",
+          "description": "The error to return to the user. If this is non-empty, the incoming gRPC\nstream/request is aborted and the error is returned to the gRPC client. If\nthis value is empty, it means the middleware accepts the stream/request/\nresponse and the processing of it can continue."
+        },
+        "replace_response": {
+          "type": "boolean",
+          "description": "A boolean indicating that the gRPC response should be replaced/overwritten.\nAs its name suggests, this can only be used as a feedback to an intercepted\nresponse RPC message and is ignored for feedback on any other message. This\nboolean is needed because in protobuf an empty message is serialized as a\n0-length or nil byte slice and we wouldn't be able to distinguish between\nan empty replacement message and the \"don't replace anything\" case."
+        },
+        "replacement_serialized": {
+          "type": "string",
+          "format": "byte",
+          "description": "If the replace_response field is set to true, this field must contain the\nbinary serialized gRPC response message in the protobuf format."
+        }
+      }
+    },
     "lnrpcInvoice": {
       "type": "object",
       "properties": {
@@ -4903,6 +4964,23 @@
         }
       }
     },
+    "lnrpcMiddlewareRegistration": {
+      "type": "object",
+      "properties": {
+        "middleware_name": {
+          "type": "string",
+          "description": "The name of the middleware to register. The name should be as informative\nas possible and is logged on registration."
+        },
+        "custom_macaroon_caveat_name": {
+          "type": "string",
+          "description": "The name of the custom macaroon caveat that this middleware is responsible\nfor. Only requests/responses that contain a macaroon with the registered\ncustom caveat are forwarded for interception to the middleware. The\nexception being the read-only mode: All requests/responses are forwarded to\na middleware that requests read-only access but such a middleware won't be\nallowed to _alter_ responses. As a security measure, _no_ middleware can\nchange responses to requests made with _unencumbered_ macaroons!\nNOTE: Cannot be used at the same time as read_only_mode."
+        },
+        "read_only_mode": {
+          "type": "boolean",
+          "description": "Instead of defining a custom macaroon caveat name a middleware can register\nitself for read-only access only. In that mode all requests/responses are\nforwarded to the middleware but the middleware isn't allowed to alter any of\nthe responses.\nNOTE: Cannot be used at the same time as custom_macaroon_caveat_name."
+        }
+      }
+    },
     "lnrpcMultiChanBackup": {
       "type": "object",
       "properties": {
@@ -5626,6 +5704,77 @@
         }
       }
     },
+    "lnrpcRPCMessage": {
+      "type": "object",
+      "properties": {
+        "method_full_uri": {
+          "type": "string",
+          "description": "The full URI (in the format /\u003crpcpackage\u003e.\u003cServiceName\u003e/MethodName, for\nexample /lnrpc.Lightning/GetInfo) of the RPC method the message was sent\nto/from."
+        },
+        "stream_rpc": {
+          "type": "boolean",
+          "description": "Indicates whether the message was sent over a streaming RPC method or not."
+        },
+        "type_name": {
+          "type": "string",
+          "description": "The full canonical gRPC name of the message type (in the format\n\u003crpcpackage\u003e.TypeName, for example lnrpc.GetInfoRequest)."
+        },
+        "serialized": {
+          "type": "string",
+          "format": "byte",
+          "description": "The full content of the gRPC message, serialized in the binary protobuf\nformat."
+        }
+      }
+    },
+    "lnrpcRPCMiddlewareRequest": {
+      "type": "object",
+      "properties": {
+        "request_id": {
+          "type": "string",
+          "format": "uint64",
+          "description": "The unique ID of the intercepted request. Useful for mapping request to\nresponse when implementing full duplex message interception."
+        },
+        "raw_macaroon": {
+          "type": "string",
+          "format": "byte",
+          "description": "The raw bytes of the complete macaroon as sent by the gRPC client in the\noriginal request. This might be empty for a request that doesn't require\nmacaroons such as the wallet unlocker RPCs."
+        },
+        "custom_caveat_condition": {
+          "type": "string",
+          "title": "The parsed condition of the macaroon's custom caveat for convenient access.\nThis field only contains the value of the custom caveat that the handling\nmiddleware has registered itself for. The condition _must_ be validated for\nmessages of intercept_type stream_auth and request!"
+        },
+        "stream_auth": {
+          "$ref": "#/definitions/lnrpcStreamAuth",
+          "description": "Intercept stream authentication: each new streaming RPC call that is\ninitiated against lnd and contains the middleware's custom macaroon\ncaveat can be approved or denied based upon the macaroon in the stream\nheader. This message will only be sent for streaming RPCs, unary RPCs\nmust handle the macaroon authentication in the request interception to\navoid an additional message round trip between lnd and the middleware."
+        },
+        "request": {
+          "$ref": "#/definitions/lnrpcRPCMessage",
+          "description": "Intercept incoming gRPC client request message: all incoming messages,\nboth on streaming and unary RPCs, are forwarded to the middleware for\ninspection. For unary RPC messages the middleware is also expected to\nvalidate the custom macaroon caveat of the request."
+        },
+        "response": {
+          "$ref": "#/definitions/lnrpcRPCMessage",
+          "description": "Intercept outgoing gRPC response message: all outgoing messages, both on\nstreaming and unary RPCs, are forwarded to the middleware for inspection\nand amendment. The response in this message is the original response as\nit was generated by the main RPC server. It can either be accepted\n(=forwarded to the client), replaced/overwritten with a new message of\nthe same type, or replaced by an error message."
+        }
+      }
+    },
+    "lnrpcRPCMiddlewareResponse": {
+      "type": "object",
+      "properties": {
+        "request_id": {
+          "type": "string",
+          "format": "uint64",
+          "description": "The unique ID of the intercepted request that this response refers to. Must\nalways be set when giving feedback to an intercept but is ignored for the\ninitial registration message."
+        },
+        "register": {
+          "$ref": "#/definitions/lnrpcMiddlewareRegistration",
+          "title": "The registration message identifies the middleware that's being\nregistered in lnd. The registration message must be sent immediately\nafter initiating the RegisterRpcMiddleware stream, otherwise lnd will\ntime out the attempt and terminate the request. NOTE: The middleware\nwill only receive interception messages for requests that contain a\nmacaroon with the custom caveat that the middleware declares it is\nresponsible for handling in the registration message! As a security\nmeasure, _no_ middleware can intercept requests made with _unencumbered_\nmacaroons!"
+        },
+        "feedback": {
+          "$ref": "#/definitions/lnrpcInterceptFeedback",
+          "description": "The middleware received an interception request and gives feedback to\nit. The request_id indicates what message the feedback refers to."
+        }
+      }
+    },
     "lnrpcReadyForPsbtFunding": {
       "type": "object",
       "properties": {
@@ -6047,6 +6196,15 @@
     "lnrpcStopResponse": {
       "type": "object"
     },
+    "lnrpcStreamAuth": {
+      "type": "object",
+      "properties": {
+        "method_full_uri": {
+          "type": "string",
+          "description": "The full URI (in the format /\u003crpcpackage\u003e.\u003cServiceName\u003e/MethodName, for\nexample /lnrpc.Lightning/GetInfo) of the streaming RPC method that was just\nestablished."
+        }
+      }
+    },
     "lnrpcTimestampedError": {
       "type": "object",
       "properties": {

lnrpc/lightning.yaml

@@ -153,4 +153,6 @@ http:
     - selector: lnrpc.Lightning.CheckMacaroonPermissions
       post: "/v1/macaroon/checkpermissions"
       body: "*"
-
+    - selector: lnrpc.Lightning.RegisterRPCMiddleware
+      post: "/v1/middleware"
+      body: "*"

lnrpc/lightning_grpc.pb.go

@@ -389,6 +389,20 @@ type LightningClient interface {
 	//imposed on the macaroon and that the macaroon is authorized to follow the
 	//provided permissions.
 	CheckMacaroonPermissions(ctx context.Context, in *CheckMacPermRequest, opts ...grpc.CallOption) (*CheckMacPermResponse, error)
+	//
+	//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!
+	RegisterRPCMiddleware(ctx context.Context, opts ...grpc.CallOption) (Lightning_RegisterRPCMiddlewareClient, error)
 }
 
 type lightningClient struct {
@@ -1209,6 +1223,37 @@ func (c *lightningClient) CheckMacaroonPermissions(ctx context.Context, in *Chec
 	return out, nil
 }
 
+func (c *lightningClient) RegisterRPCMiddleware(ctx context.Context, opts ...grpc.CallOption) (Lightning_RegisterRPCMiddlewareClient, error) {
+	stream, err := c.cc.NewStream(ctx, &Lightning_ServiceDesc.Streams[11], "/lnrpc.Lightning/RegisterRPCMiddleware", opts...)
+	if err != nil {
+		return nil, err
+	}
+	x := &lightningRegisterRPCMiddlewareClient{stream}
+	return x, nil
+}
+
+type Lightning_RegisterRPCMiddlewareClient interface {
+	Send(*RPCMiddlewareResponse) error
+	Recv() (*RPCMiddlewareRequest, error)
+	grpc.ClientStream
+}
+
+type lightningRegisterRPCMiddlewareClient struct {
+	grpc.ClientStream
+}
+
+func (x *lightningRegisterRPCMiddlewareClient) Send(m *RPCMiddlewareResponse) error {
+	return x.ClientStream.SendMsg(m)
+}
+
+func (x *lightningRegisterRPCMiddlewareClient) Recv() (*RPCMiddlewareRequest, error) {
+	m := new(RPCMiddlewareRequest)
+	if err := x.ClientStream.RecvMsg(m); err != nil {
+		return nil, err
+	}
+	return m, nil
+}
+
 // LightningServer is the server API for Lightning service.
 // All implementations must embed UnimplementedLightningServer
 // for forward compatibility
@@ -1584,6 +1629,20 @@ type LightningServer interface {
 	//imposed on the macaroon and that the macaroon is authorized to follow the
 	//provided permissions.
 	CheckMacaroonPermissions(context.Context, *CheckMacPermRequest) (*CheckMacPermResponse, error)
+	//
+	//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!
+	RegisterRPCMiddleware(Lightning_RegisterRPCMiddlewareServer) error
 	mustEmbedUnimplementedLightningServer()
 }
 
@@ -1777,6 +1836,9 @@ func (UnimplementedLightningServer) ListPermissions(context.Context, *ListPermis
 func (UnimplementedLightningServer) CheckMacaroonPermissions(context.Context, *CheckMacPermRequest) (*CheckMacPermResponse, error) {
 	return nil, status.Errorf(codes.Unimplemented, "method CheckMacaroonPermissions not implemented")
 }
+func (UnimplementedLightningServer) RegisterRPCMiddleware(Lightning_RegisterRPCMiddlewareServer) error {
+	return status.Errorf(codes.Unimplemented, "method RegisterRPCMiddleware not implemented")
+}
 func (UnimplementedLightningServer) mustEmbedUnimplementedLightningServer() {}
 
 // UnsafeLightningServer may be embedded to opt out of forward compatibility for this service.
@@ -2954,6 +3016,32 @@ func _Lightning_CheckMacaroonPermissions_Handler(srv interface{}, ctx context.Co
 	return interceptor(ctx, in, info, handler)
 }
 
+func _Lightning_RegisterRPCMiddleware_Handler(srv interface{}, stream grpc.ServerStream) error {
+	return srv.(LightningServer).RegisterRPCMiddleware(&lightningRegisterRPCMiddlewareServer{stream})
+}
+
+type Lightning_RegisterRPCMiddlewareServer interface {
+	Send(*RPCMiddlewareRequest) error
+	Recv() (*RPCMiddlewareResponse, error)
+	grpc.ServerStream
+}
+
+type lightningRegisterRPCMiddlewareServer struct {
+	grpc.ServerStream
+}
+
+func (x *lightningRegisterRPCMiddlewareServer) Send(m *RPCMiddlewareRequest) error {
+	return x.ServerStream.SendMsg(m)
+}
+
+func (x *lightningRegisterRPCMiddlewareServer) Recv() (*RPCMiddlewareResponse, error) {
+	m := new(RPCMiddlewareResponse)
+	if err := x.ServerStream.RecvMsg(m); err != nil {
+		return nil, err
+	}
+	return m, nil
+}
+
 // Lightning_ServiceDesc is the grpc.ServiceDesc for Lightning service.
 // It's only intended for direct use with grpc.RegisterService,
 // and not to be introspected or modified (even as a copy)
@@ -3225,6 +3313,12 @@ var Lightning_ServiceDesc = grpc.ServiceDesc{
 			Handler:       _Lightning_SubscribeChannelBackups_Handler,
 			ServerStreams: true,
 		},
+		{
+			StreamName:    "RegisterRPCMiddleware",
+			Handler:       _Lightning_RegisterRPCMiddleware_Handler,
+			ServerStreams: true,
+			ClientStreams: true,
+		},
 	},
 	Metadata: "lightning.proto",
 }

lnrpc/rpc_utils.go

@@ -9,6 +9,13 @@ import (
 	"github.com/lightningnetwork/lnd/lnwallet"
 )
 
+const (
+	// RegisterRPCMiddlewareURI is the full RPC method URI for the
+	// middleware registration call. This is declared here rather than where
+	// it's mainly used to avoid circular package dependencies.
+	RegisterRPCMiddlewareURI = "/lnrpc.Lightning/RegisterRPCMiddleware"
+)
+
 // RPCTransactionDetails returns a set of rpc transaction details.
 func RPCTransactionDetails(txns []*lnwallet.TransactionDetail) *TransactionDetails {
 	txDetails := &TransactionDetails{