lnrpc+rpcserver: improve docs for CheckMacaroonPermissions

Fixes #10026.

Author: guggero

lnrpc/lightning.pb.go

@@ -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);
@@ -5099,8 +5100,24 @@ 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.
     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.proto

@@ -1971,7 +1971,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": {
@@ -4643,17 +4643,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."
         },
         "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.swagger.json

@@ -8726,7 +8726,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) {