Add AccessControlDefaultAdminRules

.changeset/silent-dancers-type.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`AccessControlAdminRules`: Add extension to `AccessControl` to add extra conditions to manage the `DEFAULT_ADMIN_ROLE`

contracts/access/AccessControl.sol

@@ -44,7 +44,7 @@ import "../utils/introspection/ERC165.sol";
  *
  * WARNING: The `DEFAULT_ADMIN_ROLE` is also its own admin: it has permission to
  * grant and revoke this role. Extra precautions should be taken to secure
- * accounts that have been granted it.
+ * accounts that have been granted it. See {AccessControlAdminRules}
  */
 abstract contract AccessControl is Context, IAccessControl, ERC165 {
     struct RoleData {

contracts/access/AccessControlAdminRules.sol

@@ -0,0 +1,220 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Contracts (last updated v4.8.0) (access/AccessControlAdminRules.sol)
+
+pragma solidity ^0.8.0;
+
+import "./AccessControl.sol";
+import "./IAccessControlAdminRules.sol";
+import "../utils/math/SafeCast.sol";
+
+/**
+ * @dev Extension of {AccessControl} that allows to specify special rules to manage
+ * the `DEFAULT_ADMIN_ROLE` 's owner, which is a sensitive role with special permissions
+ * over other valid roles that may potentially have rights.
+ *
+ * If a specific role doesn't have an `adminRole` assigned, the holder of the
+ * `DEFAULT_ADMIN_ROLE` will have the ability to manage it, as determined by the
+ * function {getRoleAdmin}'s default value (`address(0)`).
+ *
+ * This contract implements the following risk mitigations on top of the AccessControl implementation:
+ *
+ * * Only one account holds the `DEFAULT_ADMIN_ROLE` at every time after construction except when renounced.
+ * * Enforce a 2-step process to transfer the `DEFAULT_ADMIN_ROLE` to another account.
+ *   - Even when it's been renounced.
+ * * Enforce a configurable delay between the two steps, with the ability to cancel in between.
+ *   - Even after the timer has passed to avoid locking it forever.
+ * * The `DEFAULT_ADMIN_ROLE` 's admin can be only held by itself.
+ *
+ * Once you understand what the {constructor} parameters, you can use this reference implementation:
+ *
+ * ```solidity
+ * contract MyToken is AccessControlAdminRules {
+ *   constructor() AccessControlAdminRules(
+ *     60 * 60 * 24, // 3 days
+ *     _msgSender() // Explicit initial `DEFAULT_ADMIN_ROLE` holder
+ *    ) {}
+ *}
+ * ```
+ *
+ * NOTE: The `delay` is only configurable in the constructor to avoid issues related with handling
+ * delay management during the transfer is pending to be completed.
+ *
+ * _Available since v4.9._
+ */
+abstract contract AccessControlAdminRules is IAccessControlAdminRules, AccessControl {
+    uint48 private immutable _delay;
+
+    address private _currentAdmin;
+    uint48 private _delayedUntil;
+
+    address private _pendingAdmin;
+
+    /**
+     * @dev Sets the initial values the internal delay and {owner}.
+     *
+     * The `delay` value is immutable. It can only be set at the constructor.
+     */
+    constructor(uint48 delay, address initialAdmin) {
+        _delay = delay;
+        _grantRole(DEFAULT_ADMIN_ROLE, initialAdmin);
+    }
+
+    /**
+     * @dev See {IAccessControlAdminRules-owner}
+     */
+    function owner() public view virtual returns (address) {
+        return _currentAdmin;
+    }
+
+    /**
+     * @dev See {IAccessControlAdminRules-delayedUntil}
+     */
+    function delayedUntil() public view virtual returns (uint48) {
+        return _delayedUntil;
+    }
+
+    /**
+     * @dev See {IAccessControlAdminRules-pendingAdmin}
+     */
+    function pendingAdmin() public view virtual returns (address) {
+        return _pendingAdmin;
+    }
+
+    /**
+     * @dev See {IERC165-supportsInterface}.
+     */
+    function supportsInterface(bytes4 interfaceId) public view virtual override returns (bool) {
+        return interfaceId == type(IAccessControlAdminRules).interfaceId || super.supportsInterface(interfaceId);
+    }
+
+    /**
+     * @dev See {IAccessControlAdminRules-beginAdminTransfer}
+     */
+    function beginAdminTransfer(address newAdmin) public override onlyRole(DEFAULT_ADMIN_ROLE) {
+        require(delayedUntil() == 0, "AccessControl: pending admin already set");
+        _delayedUntil = SafeCast.toUint48(block.timestamp) + _delay;
+        _pendingAdmin = newAdmin;
+        emit AdminRoleChangeStarted(pendingAdmin(), delayedUntil());
+    }
+
+    /**
+     * @dev See {IAccessControlAdminRules-acceptAdminTransfer}
+     */
+    function acceptAdminTransfer() public {
+        address pendingAdminOwner = pendingAdmin();
+        require(
+            _adminTransferIsUnlocked() && _msgSender() == pendingAdminOwner,
+            "AccessControl: delay must be met and caller must be pending admin"
+        );
+        _revokeRole(DEFAULT_ADMIN_ROLE, owner());
+        _grantRole(DEFAULT_ADMIN_ROLE, pendingAdminOwner);
+        _resetAdminTransfer();
+    }
+
+    /**
+     * @dev See {IAccessControlAdminRules-cancelAdminTransfer}
+     */
+    function cancelAdminTransfer() external override onlyRole(DEFAULT_ADMIN_ROLE) {
+        _resetAdminTransfer();
+    }
+
+    /**
+     * @dev Revokes `role` from the calling account.
+     *
+     * For `DEFAULT_ADMIN_ROLE`, only allows renouncing in two steps, so it's required
+     * that the {delayedUntil} is met and the pending admin is the zero address.
+     * After its execution, it will not be possible to call `onlyRole(DEFAULT_ADMIN_ROLE)`
+     * functions.
+     *
+     * For other roles, see {AccessControl-renounceRole}.
+     *
+     * NOTE: Renouncing `DEFAULT_ADMIN_ROLE` will leave the contract without an owner,
+     * thereby disabling any functionality that is only available to the default admin, and the
+     * possibility of reassigning a non-administrated role.
+     */
+    function renounceRole(bytes32 role, address account) public override(IAccessControl, AccessControl) {
+        if (role == DEFAULT_ADMIN_ROLE) {
+            require(
+                pendingAdmin() == address(0) && _adminTransferIsUnlocked(),
+                "AccessControl: admin can only renounce in two delayed steps"
+            );
+        }
+        super.renounceRole(role, account);
+    }
+
+    /**
+     * @dev See {AccessControl-grantRole}. Reverts for `DEFAULT_ADMIN_ROLE`.
+     */
+    function grantRole(
+        bytes32 role,
+        address account
+    ) public override(IAccessControl, AccessControl) onlyRole(getRoleAdmin(role)) {
+        require(role != DEFAULT_ADMIN_ROLE, "AccessControl: can't directly grant admin role");
+        super.grantRole(role, account);
+    }
+
+    /**
+     * @dev See {AccessControl-revokeRole}. Reverts for `DEFAULT_ADMIN_ROLE`.
+     */
+    function revokeRole(
+        bytes32 role,
+        address account
+    ) public override(IAccessControl, AccessControl) onlyRole(getRoleAdmin(role)) {
+        require(role != DEFAULT_ADMIN_ROLE, "AccessControl: can't directly revoke admin role");
+        super.revokeRole(role, account);
+    }
+
+    /**
+     * @dev See {AccessControl-_setRoleAdmin}. Reverts for `DEFAULT_ADMIN_ROLE`.
+     */
+    function _setRoleAdmin(bytes32 role, bytes32 adminRole) internal override {
+        require(role != DEFAULT_ADMIN_ROLE, "AccessControl: can't override admin's admin");
+        super._setRoleAdmin(role, adminRole);
+    }
+
+    /**
+     * @dev Grants `role` to `account`.
+     *
+     * For `DEFAULT_ADMIN_ROLE`, it only allows granting if there isn't already a role's owner
+     * or if the role has been previously renounced.
+     *
+     * For other roles, see {AccessControl-renounceRole}.
+     *
+     * NOTE: Exposing this function through another mechanism may make the
+     * `DEFAULT_ADMIN_ROLE` assignable again. Make sure to guarantee this is
+     * the expected behavior in your implementation.
+     */
+    function _grantRole(bytes32 role, address account) internal override {
+        if (role == DEFAULT_ADMIN_ROLE) {
+            require(owner() == address(0), "AccessControl: admin already granted");
+            _currentAdmin = account;
+        }
+        super._grantRole(role, account);
+    }
+
+    /**
+     * @dev See {AccessControl-_revokeRole}.
+     */
+    function _revokeRole(bytes32 role, address account) internal override {
+        if (role == DEFAULT_ADMIN_ROLE) {
+            delete _currentAdmin;
+        }
+        super._revokeRole(role, account);
+    }
+
+    /**
+     * @dev Resets the pending admin and delayed until.
+     */
+    function _resetAdminTransfer() private {
+        delete _pendingAdmin;
+        delete _delayedUntil;
+    }
+
+    /**
+     * @dev Checks if a {delayedUntil} has been set and met.
+     */
+    function _adminTransferIsUnlocked() private view returns (bool) {
+        uint48 delayedUntilTimestamp = delayedUntil();
+        return delayedUntilTimestamp > 0 && delayedUntilTimestamp < block.timestamp;
+    }
+}

contracts/access/IAccessControlAdminRules.sol

@@ -0,0 +1,71 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Contracts v4.9.0 (access/IAccessControlAdminRules.sol)
+
+pragma solidity ^0.8.0;
+
+import "./IAccessControl.sol";
+
+/**
+ * @dev External interface of AccessControladminRules declared to support ERC165 detection.
+ *
+ * _Available since v4.9._
+ */
+interface IAccessControlAdminRules is IAccessControl {
+    /**
+     * @dev Emitted when an `DEFAULT_ADMIN_ROLE` transfer is started, setting `newAdmin`
+     * as the next owner to be claimed after `delayedUntil` is met.
+     */
+    event AdminRoleChangeStarted(address indexed newAdmin, uint48 delayedUntil);
+
+    /**
+     * @dev Returns the address of the current `DEFAULT_ADMIN_ROLE` owner.
+     */
+    function owner() external view returns (address);
+
+    /**
+     * @dev Returns the timestamp in which the pending admin can claim the
+     * `DEFAULT_ADMIN_ROLE` role.
+     */
+    function delayedUntil() external view returns (uint48);
+
+    /**
+     * @dev Returns the address of the pending `DEFAULT_ADMIN_ROLE` owner.
+     */
+    function pendingAdmin() external view returns (address);
+
+    /**
+     * @dev Starts a `DEFAULT_ADMIN_ROLE` transfer by setting a pending admin and
+     * a timer to be met.
+     *
+     * Requirements:
+     *
+     * - There shouldn't be another admin transfer in progress. See {cancelAdminTransfer}.
+     * - Can only be called by the current `DEFAULT_ADMIN_ROLE` owner.
+     *
+     * Emits an {AdminRoleChangeStarted}.
+     */
+    function beginAdminTransfer(address newAdmin) external;
+
+    /**
+     * @dev Completes a `DEFAULT_ADMIN_ROLE` transfer.
+     *
+     * Requirements:
+     *
+     * - Caller should be the pending admin.
+     * - `DEFAULT_ADMIN_ROLE` should be granted to the caller.
+     * - `DEFAULT_ADMIN_ROLE` should be revoked from the previous owner.
+     * - Should allow to call {beginAdminTransfer} again.
+     */
+    function acceptAdminTransfer() external;
+
+    /**
+     * @dev Cancels a `DEFAULT_ADMIN_ROLE` transfer.
+     *
+     * Requirements:
+     *
+     * - Should allow to call {beginAdminTransfer} again.
+     * - Can be called even after the timer is met.
+     * - Can only be called by the current `DEFAULT_ADMIN_ROLE` owner.
+     */
+    function cancelAdminTransfer() external;
+}

contracts/access/Ownable.sol

@@ -53,10 +53,10 @@ abstract contract Ownable is Context {
 
     /**
      * @dev Leaves the contract without owner. It will not be possible to call
-     * `onlyOwner` functions anymore. Can only be called by the current owner.
+     * `onlyOwner` functions. Can only be called by the current owner.
      *
      * NOTE: Renouncing ownership will leave the contract without an owner,
-     * thereby removing any functionality that is only available to the owner.
+     * thereby disabling any functionality that is only available to the owner.
      */
     function renounceOwnership() public virtual onlyOwner {
         _transferOwnership(address(0));

contracts/access/README.adoc

@@ -23,3 +23,7 @@ This directory provides ways to restrict who can access the functions of a contr
 {{IAccessControlEnumerable}}
 
 {{AccessControlEnumerable}}
+
+{{IAccessControlAdminRules}}
+
+{{AccessControlAdminRules}}

docs/modules/ROOT/pages/access-control.adoc

@@ -131,6 +131,8 @@ Every role has an associated admin role, which grants permission to call the `gr
 
 This mechanism can be used to create complex permissioning structures resembling organizational charts, but it also provides an easy way to manage simpler applications. `AccessControl` includes a special role, called `DEFAULT_ADMIN_ROLE`, which acts as the **default admin role for all roles**. An account with this role will be able to manage any other role, unless `_setRoleAdmin` is used to select a new admin role.
 
+NOTE: For risk mitigations related to `DEFAULT_ADMIN_ROLE` management. See xref:api:access.adoc#AccessControlAdminRules[`AccessControlAdminRules`] as an alternative with restrictions such as 2-step admin role change, single-holder enforcing and configurable minimum delay.
+
 Let's take a look at the ERC20 token example, this time taking advantage of the default admin role:
 
 [source,solidity]