You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: website/docs/library/access/AccessControl/AccessControlFacet.mdx
+28-38Lines changed: 28 additions & 38 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -25,15 +25,14 @@ Manages role-based access control within a diamond.
25
25
</DocSubtitle>
26
26
27
27
<Callouttype="info"title="Key Features">
28
-
- Role-based access control (RBAC) implementation.
29
-
- Supports granting and revoking roles for individual accounts and batches.
30
-
- Allows for defining role administrators to manage role assignments.
31
-
- Emits events for role changes for off-chain monitoring.
28
+
- Role-based access control for granular permission management.
29
+
- Support for batch granting and revoking roles.
30
+
- Extensible with other access control facets like `AccessControlPausableFacet`.
32
31
</Callout>
33
32
34
33
## Overview
35
34
36
-
The AccessControlFacet provides a robust framework for implementing role-based access control (RBAC) within a Compose diamond. It allows for granular permission management by defining roles, assigning them to accounts, and enforcing role requirements for function execution. This facet is crucial for securing sensitive operations and ensuring that only authorized entities can perform specific actions.
35
+
The AccessControlFacet provides a robust role-based access control (RBAC) system for Compose diamonds. It allows for granular permission management by defining roles and assigning them to accounts. This facet is crucial for securing sensitive functions and orchestrating complex interactions by enforcing role requirements.
- Initialize roles and grant initial permissions during diamond deployment or upgrade initialization.
525
-
-Define role hierarchies using `setRoleAdmin` to ensure proper administrative control.
526
-
-Utilize `requireRole` within functions to enforce access control checks, reverting with specific errors if unauthorized.
514
+
- Initialize roles and grant them to appropriate accounts during diamond deployment.
515
+
-Use `grantRoleBatch` and `revokeRoleBatch` for efficient mass role management.
516
+
-Define clear hierarchies for roles using `setRoleAdmin` to manage administrative privileges.
527
517
</Callout>
528
518
529
519
## Security Considerations
530
520
531
521
<Callouttype="warning"title="Security">
532
-
Ensure that sensitive roles, such as `ADMIN_ROLE`, are only granted to trusted addresses. The `setRoleAdmin` function's access control is enforced by the current role administrator, preventing unauthorized changes to role hierarchies. Batch operations (`grantRoleBatch`, `revokeRoleBatch`) should be used cautiously to avoid unintended mass role modifications. Reentrancy is not a direct concern as functions operate on state and do not make external calls without proper checks.
522
+
Ensure that role administration is properly secured. The `setRoleAdmin`, `grantRole`, and `revokeRole` functions require the caller to be the admin of the role. Reentrancy is mitigated as role modifications are atomic. Input validation is handled internally by the facet to prevent invalid role or account assignments.
Manages role-based access control for diamond operations.
24
+
Manages roles and permissions within a diamond.
25
25
</DocSubtitle>
26
26
27
27
<Callouttype="info"title="Key Features">
28
-
-Role-based access control (RBAC) for granular permissions.
29
-
-Functions for granting, revoking, and checking roles (`grantRole`, `revokeRole`, `hasRole`).
30
-
- Built-in reversion with `AccessControlUnauthorizedAccount` error for unauthorized access attempts.
31
-
-Supports setting administrative roles for managing other roles.
28
+
-Permission management via roles assigned to accounts.
29
+
-Ability to grant and revoke roles dynamically.
30
+
- Built-in check for role existence with `hasRole`.
31
+
-Revert mechanism for unauthorized access attempts via `requireRole`.
32
32
</Callout>
33
33
34
34
<Callouttype="info"title="Module Usage">
@@ -37,7 +37,7 @@ This module provides internal functions for use in your custom facets. Import it
37
37
38
38
## Overview
39
39
40
-
This module provides a robust role-based access control (RBAC) system, enabling granular permission management within your diamond. By composing this module, you can define roles and assign them to addresses, ensuring that only authorized accounts can execute sensitive functions. This enhances security and maintainability by centralizing access logic.
40
+
The AccessControl module provides a robust system for managing roles and permissions, ensuring that only authorized accounts can perform specific actions. This is crucial for maintaining security and control within a Compose diamond by enabling granular access delegation and revocation.
function enforceAdminRole(address _account) view external {
429
+
bytes32 adminRole = keccak256("AccessControl.ADMIN_ROLE"); // Example role
430
+
accessControl.requireRole(adminRole, _account);
424
431
}
425
432
}`}
426
433
</ExpandableCode>
427
434
428
435
## Best Practices
429
436
430
437
<Callouttype="tip"title="Best Practice">
431
-
- Define roles using `bytes32`constants and manage them consistently across facets.
432
-
- Use `requireRole`within facet functions to enforce access control checks inline.
433
-
-Leverage `setRoleAdmin` to manage role administration hierarchies for enhanced security.
438
+
- Define roles using `bytes32` and `keccak256` for clarity and gas efficiency.
439
+
- Use `requireRole`for immediate enforcement of permissions within functions.
440
+
-Carefully manage the administration of roles using `setRoleAdmin` to prevent unintended privilege escalation.
434
441
</Callout>
435
442
436
443
## Integration Notes
437
444
438
445
<Callouttype="success"title="Shared Storage">
439
-
The `AccessControlMod` is designed to be integrated into a Compose diamond using the diamond storage pattern. Its storage is located at the slot identified by `STORAGE_POSITION`, which is `keccak256("compose.accesscontrol")`. Facets can retrieve the `AccessControlMod` contract instance using `_diamondStorage.getFacetAddress(keccak256("compose.accesscontrol"))` and then interact with its functions. The `AccessControlStorage` struct is empty, indicating that the module manages its state internally or through a separate mechanism managed by the diamond's initialization process.
446
+
The AccessControl module utilizes the diamond storage pattern, storing its state at a well-defined slot identified by `keccak256("compose.accesscontrol")`. Facets can access this state by calling the `getStorage()` function or directly interacting with the module's functions, which implicitly read from this storage slot. Ensure that the AccessControl module is correctly initialized and its storage slot is reserved to avoid conflicts with other modules.
Manages role-based pausing and unpausing of operations.
24
+
Control role access and pause/unpause specific roles.
25
25
</DocSubtitle>
26
26
27
27
<Callouttype="info"title="Key Features">
28
-
- Role-specific pausing and unpausing of operations.
29
-
- Integration with diamond's access control for administrative actions.
30
-
- Emits `RolePaused` and `RoleUnpaused` events for state changes.
31
-
- Reverts with specific errors for unauthorized access and paused roles.
28
+
- Allows pausing and unpausing of specific roles, preventing execution of role-bound functions.
29
+
- Integrates seamlessly with existing AccessControl mechanisms.
30
+
- Provides view functions to check the current paused status of any role.
32
31
</Callout>
33
32
34
33
## Overview
35
34
36
-
This facet provides granular control over role execution by allowing specific roles to be temporarily paused. It integrates with the diamond's access control system to ensure only authorized entities can manage pause states. This enables flexible operational control and emergency stops for critical functions.
35
+
This facet provides granular control over role-based access, allowing specific roles to be temporarily paused. It integrates with the core AccessControl logic to enforce role permissions and adds a pausing mechanism for enhanced operational flexibility. Use this facet to manage temporary disruptions or maintenance periods for specific functionalities tied to roles.
- Initialize the facet with appropriate role administrators during diamond deployment.
315
-
-Use `pauseRole` and `unpauseRole`judiciously to manage operational states, ensuring the caller has the necessary administrative privileges.
316
-
- Leverage `requireRoleNotPaused` within other facets to conditionally gate functionality based on the operational status of a role.
329
+
- Initialize or upgrade the diamond to include this facet to enable role pausing capabilities.
330
+
-Ensure the caller invoking `pauseRole` and `unpauseRole` has the necessary administrative privileges for the target role.
331
+
- Leverage `requireRoleNotPaused` within other facets or contract logic to dynamically enforce pausing states.
317
332
</Callout>
318
333
319
334
## Security Considerations
320
335
321
336
<Callouttype="warning"title="Security">
322
-
Ensure that the administrative role capable of pausing and unpausing is properly secured. The `requireRoleNotPaused` function should be integrated into any facet function that relies on a role's operational status to prevent execution when paused. Reentrancy is not a concern as the functions are read-only or perform state changes without external calls.
337
+
The `pauseRole` and `unpauseRole` functions are restricted to the admin of the respective role, preventing unauthorized pausing. The `requireRoleNotPaused` function reverts with `AccessControlRolePaused` if the role is paused, ensuring that paused roles cannot be utilized. Ensure that any critical functions protected by roles properly call `requireRoleNotPaused`or equivalent logic to respect the paused state.
0 commit comments