lnrpc+rpcserver: improve docs for CheckMacaroonPermissions

Fixes #10026.

lnrpc/lightning.pb.go

@@ -17406,9 +17406,25 @@ type CheckMacPermRequest struct {
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields
 
-	Macaroon    []byte                `protobuf:"bytes,1,opt,name=macaroon,proto3" json:"macaroon,omitempty"`
+	// The macaroon to check permissions for, serialized in binary format. For
+	// a macaroon to be valid, it must have been issued by lnd, must succeed all
+	// caveat conditions, and must contain all of the permissions specified in
+	// the permissions field.
+	Macaroon []byte `protobuf:"bytes,1,opt,name=macaroon,proto3" json:"macaroon,omitempty"`
+	// The list of permissions the macaroon should be checked against. Only if
+	// the macaroon contains all of these permissions, it is considered valid.
+	// If the list of permissions given is empty, then the macaroon is
+	// considered valid only based on issuance authority and caveat validity.
+	// An empty list of permissions is therefore equivalent to saying "skip
+	// checking permissions".
 	Permissions []*MacaroonPermission `protobuf:"bytes,2,rep,name=permissions,proto3" json:"permissions,omitempty"`
-	FullMethod  string                `protobuf:"bytes,3,opt,name=fullMethod,proto3" json:"fullMethod,omitempty"`
+	// The RPC method to check the macaroon against. This is only used if there
+	// are custom `uri:<rpcpackage>.<ServiceName>/<MethodName>` permissions in
+	// the permission list above. To check a macaroon against the list of
+	// permissions of a certain RPC method, query the `ListPermissions` RPC
+	// first, extract the permissions for the method, and then pass them in the
+	// `permissions` field above.
+	FullMethod string `protobuf:"bytes,3,opt,name=fullMethod,proto3" json:"fullMethod,omitempty"`
 }
 
 func (x *CheckMacPermRequest) Reset() {

lnrpc/lightning.proto

@@ -548,9 +548,10 @@ service Lightning {
         returns (ListPermissionsResponse);
 
     /*
-    CheckMacaroonPermissions checks whether a request follows the constraints
-    imposed on the macaroon and that the macaroon is authorized to follow the
-    provided permissions.
+    CheckMacaroonPermissions checks whether the provided macaroon contains all
+    the provided permissions. If the macaroon is valid (e.g. all caveats are
+    satisfied), and all permissions provided in the request are met, then
+    this RPC returns true.
     */
     rpc CheckMacaroonPermissions (CheckMacPermRequest)
         returns (CheckMacPermResponse);
@@ -5107,8 +5108,26 @@ message Op {
 }
 
 message CheckMacPermRequest {
+    // The macaroon to check permissions for, serialized in binary format. For
+    // a macaroon to be valid, it must have been issued by lnd, must succeed all
+    // caveat conditions, and must contain all of the permissions specified in
+    // the permissions field.
     bytes macaroon = 1;
+
+    // The list of permissions the macaroon should be checked against. Only if
+    // the macaroon contains all of these permissions, it is considered valid.
+    // If the list of permissions given is empty, then the macaroon is
+    // considered valid only based on issuance authority and caveat validity.
+    // An empty list of permissions is therefore equivalent to saying "skip
+    // checking permissions".
     repeated MacaroonPermission permissions = 2;
+
+    // The RPC method to check the macaroon against. This is only used if there
+    // are custom `uri:<rpcpackage>.<ServiceName>/<MethodName>` permissions in
+    // the permission list above. To check a macaroon against the list of
+    // permissions of a certain RPC method, query the `ListPermissions` RPC
+    // first, extract the permissions for the method, and then pass them in the
+    // `permissions` field above.
     string fullMethod = 3;
 }
 

lnrpc/lightning.swagger.json

@@ -1991,7 +1991,7 @@
     },
     "/v1/macaroon/checkpermissions": {
       "post": {
-        "summary": "CheckMacaroonPermissions checks whether a request follows the constraints\nimposed on the macaroon and that the macaroon is authorized to follow the\nprovided permissions.",
+        "summary": "CheckMacaroonPermissions checks whether the provided macaroon contains all\nthe provided permissions. If the macaroon is valid (e.g. all caveats are\nsatisfied), and all permissions provided in the request are met, then\nthis RPC returns true.",
         "operationId": "Lightning_CheckMacaroonPermissions",
         "responses": {
           "200": {
@@ -4667,17 +4667,20 @@
       "properties": {
         "macaroon": {
           "type": "string",
-          "format": "byte"
+          "format": "byte",
+          "description": "The macaroon to check permissions for, serialized in binary format. For\na macaroon to be valid, it must have been issued by lnd, must succeed all\ncaveat conditions, and must contain all of the permissions specified in\nthe permissions field."
         },
         "permissions": {
           "type": "array",
           "items": {
             "type": "object",
             "$ref": "#/definitions/lnrpcMacaroonPermission"
-          }
+          },
+          "description": "The list of permissions the macaroon should be checked against. Only if\nthe macaroon contains all of these permissions, it is considered valid.\nIf the list of permissions given is empty, then the macaroon is\nconsidered valid only based on issuance authority and caveat validity.\nAn empty list of permissions is therefore equivalent to saying \"skip\nchecking permissions\"."
         },
         "fullMethod": {
-          "type": "string"
+          "type": "string",
+          "description": "The RPC method to check the macaroon against. This is only used if there\nare custom `uri:\u003crpcpackage\u003e.\u003cServiceName\u003e/\u003cMethodName\u003e` permissions in\nthe permission list above. To check a macaroon against the list of\npermissions of a certain RPC method, query the `ListPermissions` RPC\nfirst, extract the permissions for the method, and then pass them in the\n`permissions` field above."
         }
       }
     },

lnrpc/lightning_grpc.pb.go

@@ -384,9 +384,10 @@ type LightningClient interface {
 	// ListPermissions lists all RPC method URIs and their required macaroon
 	// permissions to access them.
 	ListPermissions(ctx context.Context, in *ListPermissionsRequest, opts ...grpc.CallOption) (*ListPermissionsResponse, error)
-	// CheckMacaroonPermissions checks whether a request follows the constraints
-	// imposed on the macaroon and that the macaroon is authorized to follow the
-	// provided permissions.
+	// CheckMacaroonPermissions checks whether the provided macaroon contains all
+	// the provided permissions. If the macaroon is valid (e.g. all caveats are
+	// satisfied), and all permissions provided in the request are met, then
+	// this RPC returns true.
 	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
@@ -1712,9 +1713,10 @@ type LightningServer interface {
 	// ListPermissions lists all RPC method URIs and their required macaroon
 	// permissions to access them.
 	ListPermissions(context.Context, *ListPermissionsRequest) (*ListPermissionsResponse, error)
-	// CheckMacaroonPermissions checks whether a request follows the constraints
-	// imposed on the macaroon and that the macaroon is authorized to follow the
-	// provided permissions.
+	// CheckMacaroonPermissions checks whether the provided macaroon contains all
+	// the provided permissions. If the macaroon is valid (e.g. all caveats are
+	// satisfied), and all permissions provided in the request are met, then
+	// this RPC returns true.
 	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

rpcserver.go

@@ -8787,7 +8787,10 @@ func (r *rpcServer) ListPermissions(_ context.Context,
 	}, nil
 }
 
-// CheckMacaroonPermissions checks the caveats and permissions of a macaroon.
+// CheckMacaroonPermissions checks whether the provided macaroon contains all
+// the provided permissions. If the macaroon is valid (e.g. all caveats are
+// satisfied), and all permissions provided in the request are met, then
+// this RPC returns true.
 func (r *rpcServer) CheckMacaroonPermissions(ctx context.Context,
 	req *lnrpc.CheckMacPermRequest) (*lnrpc.CheckMacPermResponse, error) {