Make role grant system more consistent with other privileges.

Previously, membership of role A in role B could be recorded in the
catalog tables only once. This meant that a new grant of role A to
role B would overwrite the previous grant. For other object types, a
new grant of permission on an object - in this case role A - exists
along side the existing grant provided that the grantor is different.
Either grant can be revoked independently of the other, and
permissions remain so long as at least one grant remains. Make role
grants work similarly.

Previously, when granting membership in a role, the superuser could
specify any role whatsoever as the grantor, but for other object types,
the grantor of record must be either the owner of the object, or a
role that currently has privileges to perform a similar GRANT.
Implement the same scheme for role grants, treating the bootstrap
superuser as the role owner since roles do not have owners. This means
that attempting to revoke a grant, or admin option on a grant, can now
fail if there are dependent privileges, and that CASCADE can be used
to revoke these. It also means that you can't grant ADMIN OPTION on
a role back to a user who granted it directly or indirectly to you,
similar to how you can't give WITH GRANT OPTION on a privilege back
to a role which granted it directly or indirectly to you.

Previously, only the superuser could specify GRANTED BY with a user
other than the current user. Relax that rule to allow the grantor
to be any role whose privileges the current user posseses. This
doesn't improve compatibility with what we do for other object types,
where support for GRANTED BY is entirely vestigial, but it makes this
feature more usable and seems to make sense to change at the same time
we're changing related behaviors.

Along the way, fix "ALTER GROUP group_name ADD USER user_name" to
require the same privileges as "GRANT group_name TO user_name".
Previously, CREATEROLE privileges were sufficient for either, but
only the former form was permissible with ADMIN OPTION on the role.
Now, either CREATEROLE or ADMIN OPTION on the role suffices for
either spelling.

Patch by me, reviewed by Stephen Frost.

Discussion: http://postgr.es/m/CA+TgmoaFr-RZeQ+WoQ5nKPv97oT9+aDgK_a5+qWHSgbDsMp1Vg@mail.gmail.com

Author: robertmhaas

doc/src/sgml/ref/alter_group.sgml

@@ -52,7 +52,11 @@ ALTER GROUP <replaceable class="parameter">group_name</replaceable> RENAME TO <r
    equivalent to granting or revoking membership in the role named as the
    <quote>group</quote>; so the preferred way to do this is to use
    <link linkend="sql-grant"><command>GRANT</command></link> or
-   <link linkend="sql-revoke"><command>REVOKE</command></link>.
+   <link linkend="sql-revoke"><command>REVOKE</command></link>. Note that
+   <command>GRANT</command> and <command>REVOKE</command> have additional
+   options which are not available with this command, such as the ability
+   to grant and revoke <literal>ADMIN OPTION</literal>, and the ability to
+   specify the grantor.
   </para>
 
   <para>

doc/src/sgml/ref/grant.sgml

@@ -267,8 +267,14 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace
 
   <para>
    If <literal>GRANTED BY</literal> is specified, the grant is recorded as
-   having been done by the specified role.  Only database superusers may
-   use this option, except when it names the same role executing the command.
+   having been done by the specified role. A user can only attribute a grant
+   to another role if they possess the privileges of that role. The role
+   recorded as the grantor must have <literal>ADMIN OPTION</literal> on the
+   target role, unless it is the bootstrap superuser. When a grant is recorded
+   as having a grantor other than the bootstrap superuser, it depends on the
+   grantor continuing to posess <literal>ADMIN OPTION</literal> on the role;
+   so, if <literal>ADMIN OPTION</literal> is revoked, dependent grants must
+   be revoked as well.
   </para>
 
   <para>
@@ -333,7 +339,7 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace
     owner of the affected object.  In particular, privileges granted via
     such a command will appear to have been granted by the object owner.
     (For role membership, the membership appears to have been granted
-    by the containing role itself.)
+    by the bootstrap superuser.)
    </para>
 
    <para>

doc/src/sgml/ref/revoke.sgml

@@ -198,9 +198,10 @@ REVOKE [ ADMIN OPTION FOR ]
   <para>
    When revoking membership in a role, <literal>GRANT OPTION</literal> is instead
    called <literal>ADMIN OPTION</literal>, but the behavior is similar.
-   This form of the command also allows a <literal>GRANTED BY</literal>
-   option, but that option is currently ignored (except for checking
-   the existence of the named role).
+   Note that, in releases prior to <productname>PostgreSQL</productname> 16,
+   dependent privileges were not tracked for grants of role membership,
+   and thus <literal>CASCADE</literal> had no effect for role membership.
+   This is no longer the case.
    Note also that this form of the command does not
    allow the noise word <literal>GROUP</literal>
    in <replaceable class="parameter">role_specification</replaceable>.
@@ -239,7 +240,10 @@ REVOKE [ ADMIN OPTION FOR ]
    <para>
     If a superuser chooses to issue a <command>GRANT</command> or <command>REVOKE</command>
     command, the command is performed as though it were issued by the
-    owner of the affected object.  Since all privileges ultimately come
+    owner of the affected object.  (Since roles do not have owners, in the
+    case of a <command>GRANT</command> of role membership, the command is
+    performed as though it were issued by the bootstrap superuser.)
+    Since all privileges ultimately come
     from the object owner (possibly indirectly via chains of grant options),
     it is possible for a superuser to revoke all privileges, but this might
     require use of <literal>CASCADE</literal> as stated above.