feat: Add Mutex mixin

Author: TSxo

.github/workflows/test.yml

@@ -10,9 +10,6 @@ env:
 
 jobs:
   check:
-    strategy:
-      fail-fast: true
-
     name: Foundry project
     runs-on: ubuntu-latest
     steps:

README.md

@@ -7,23 +7,24 @@ A suite of opinionated, optimized smart contract modules.
 The smart contracts are located in the `src` directory.
 
 ```ml
-auth
-├── IOwned.sol
-├── Owned.sol
-└── managed
-    ├── AuthManaged.sol
-    ├── AuthManager.sol
-    ├── IAuthManaged.sol
-    ├── IAuthManager.sol
-    └── IAuthority.sol
+.
+├── auth
+│   ├── IOwned.sol
+│   ├── Owned.sol
+│   └── managed
+│       ├── AuthManaged.sol
+│       ├── AuthManager.sol
+│       ├── IAuthManaged.sol
+│       ├── IAuthManager.sol
+│       └── IAuthority.sol
+├── mixins
+│   └── Mutex.sol
 ```
 
 ## Work in Progress
 
-This project is currently under active development. New modules and features will
-be added to enhance functionality and performance. While the core auth modules are
-available for testing and experimentation, the complete suite will be published
-once enough modules are integrated and thoroughly vetted.
+This project is currently under development. New modules and features will
+be added to enhance functionality and performance.
 
 Contributions and suggestions are welcomed.
 

src/auth/managed/AuthManager.sol

@@ -10,9 +10,6 @@ import { IAuthority } from "./IAuthority.sol";
 ///
 /// @author TSxo
 ///
-/// @notice A role-based access control system for managing permissions on smart
-/// contracts.
-///
 /// @dev This contract provides an efficient and flexible solution for managing
 /// the permissions of a system.
 ///

src/mixins/Mutex.sol

@@ -0,0 +1,157 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.20;
+
+/// @title Mutex
+///
+/// @author TSxo
+///
+/// @dev Provides mechanisms to guard against reentrancy attacks.
+///
+/// # Guards
+///
+/// Exposes two modifiers: `lock` for write operations and `whenUnlocked` for
+/// reads.
+///
+/// The `lock` modifier acquires a lock before function execution and releases
+/// it afterward. While locked, no other function using `lock` or `whenUnlocked`
+/// can be called.
+///
+/// The `whenUnlocked` modifier ensures no lock is held during calls to view
+/// functions, preventing read-level reentrancy.
+///
+/// Functions guarded by these modifiers cannot directly call each other. To
+/// navigate this issue, extract reusable logic into modifier-free internal or
+/// private functions and compose calls to them from a single guarded entry point.
+///
+/// For the rationale behind `1` and `2` representing locked states, see:
+/// - https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/utils/ReentrancyGuard.sol
+/// - https://eips.ethereum.org/EIPS/eip-2200
+///
+/// # Upgrade Compatible
+///
+/// This contract utilizes ERC-7201 namespaced storage, making it compatible with
+/// upgradeable contract architectures. Note, it does not enforce any restrictions
+/// against reinitialization, leaving such protection mechanisms up to the
+/// inheriting contract.
+///
+/// # Disclaimer
+///
+/// This contract prioritizes an opinionated balance between optimization and
+/// readability. **It was not designed with user safety in mind** and contains
+/// minimal safety checks. It is experimental software and is provided **as-is**,
+/// without any warranties or guarantees of functionality, security, or fitness
+/// for any particular purpose.
+///
+/// There are implicit invariants this contract expects to hold. Users and
+/// developers integrating this contract **do so at their own risk** and are
+/// responsible for thoroughly reviewing the code before use.
+///
+/// The author assumes **no liability** for any loss, damage, or unintended
+/// behavior resulting from the use, deployment, or interaction with this contract.
+///
+/// # Acknowledgements
+///
+/// Heavy inspiration is taken from:
+/// - Open Zeppelin;
+/// - Solmate; and
+/// - Solady.
+///
+/// Thank you.
+abstract contract Mutex {
+    // -------------------------------------------------------------------------
+    // Type Declarations
+
+    /// @custom:storage-location erc7201:libsol.storage.Mutex
+    struct MutexStorage {
+        uint256 locked;
+    }
+
+    // -------------------------------------------------------------------------
+    // State
+
+    /// @dev keccak256(abi.encode(uint256(keccak256("libsol.storage.Mutex")) - 1)) & ~bytes32(uint256(0xff))
+    bytes32 private constant STORAGE = 0x4772547a0c85096864cfb8fb79e76bca1fc87ca09848b27c5507e4697fcfd100;
+
+    /// @dev Represents the unlocked state.
+    uint256 private constant UNLOCKED = 1;
+
+    /// @dev Represents the locked state.
+    uint256 private constant LOCKED = 2;
+
+    // -------------------------------------------------------------------------
+    // Errors
+
+    /// @notice Raised when entering a guarded function after a lock has been
+    /// acquired.
+    error Mutex__Locked();
+
+    // -------------------------------------------------------------------------
+    // Modifiers
+
+    /// @dev Guards against reentrancy attacks by acquiring a lock before function
+    /// execution and releasing it afterward.
+    modifier lock() virtual {
+        _acquireLock();
+        _;
+        _releaseLock();
+    }
+
+    /// @dev Guards against read-only reentrancy attacks by ensuring no write
+    /// lock is held.
+    ///
+    /// Important: Does not acquire a lock. See the `lock()` modifier.
+    modifier whenUnlocked() virtual {
+        _assertUnlocked();
+        _;
+    }
+
+    // -------------------------------------------------------------------------
+    // Functions - Init
+
+    /// @notice Initializes the contract by setting the locked status to `UNLOCKED`.
+    function _initializeMutex() internal virtual {
+        assembly ("memory-safe") {
+            sstore(STORAGE, UNLOCKED)
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Functions - Internal
+
+    /// @notice Acquires the lock. Once acquired, no reentrant calls can be made
+    /// to functions that use the `lock` or `whenUnlocked` modifiers.
+    function _acquireLock() internal virtual {
+        _assertUnlocked();
+
+        assembly ("memory-safe") {
+            sstore(STORAGE, LOCKED)
+        }
+    }
+
+    /// @notice Releases the lock.
+    function _releaseLock() internal virtual {
+        assembly ("memory-safe") {
+            sstore(STORAGE, UNLOCKED)
+        }
+    }
+
+    /// @notice Returns whether the lock is currently acquired.
+    ///
+    /// @return result True if the lock is acquired, false otherwise.
+    function _isLocked() internal view virtual returns (bool result) {
+        assembly ("memory-safe") {
+            result := eq(sload(STORAGE), LOCKED)
+        }
+    }
+
+    /// @notice Asserts that the lock has not been acquired.
+    function _assertUnlocked() internal view virtual {
+        assembly ("memory-safe") {
+            if eq(sload(STORAGE), LOCKED) {
+                mstore(0x00, 0x02c73c37) // `Mutex__Locked()`
+                revert(0x1c, 0x04)
+            }
+        }
+    }
+}

src/mocks/mixins/MutexImpl.sol

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.20;
+
+import { Mutex } from "@tsxo/libsol/mixins/Mutex.sol";
+
+contract MutexImpl is Mutex {
+    uint256 private _count;
+
+    constructor() {
+        _initializeMutex();
+    }
+
+    function increment() public lock {
+        _count++;
+    }
+
+    function count() public view whenUnlocked returns (uint256) {
+        return _count;
+    }
+
+    function unguardedToGuarded() external {
+        increment();
+    }
+
+    function guardedToGuarded() external lock {
+        increment();
+    }
+
+    function unguardedToGuardedRead() external view {
+        count();
+    }
+
+    function guardedToGuardedRead() external lock {
+        count();
+    }
+
+    function unguardedToExternal(MutexAttack attacker) external {
+        attacker.execute(this.increment.selector);
+    }
+
+    function guardedToExternal(MutexAttack attacker) external lock {
+        attacker.execute(this.increment.selector);
+    }
+
+    function isLocked() external view returns (bool) {
+        return _isLocked();
+    }
+}
+
+contract MutexAttack {
+    error Failed();
+
+    function execute(bytes4 selector) external {
+        (bool success,) = msg.sender.call(abi.encodeWithSelector(selector));
+
+        if (!success) revert Failed();
+    }
+}

test/mixins/Mutex.t.sol

@@ -0,0 +1,68 @@
+pragma solidity 0.8.20;
+
+import { Test } from "forge-std/Test.sol";
+import { Mutex } from "@tsxo/libsol/mixins/Mutex.sol";
+import { MutexImpl, MutexAttack } from "@tsxo/libsol/mocks/mixins/MutexImpl.sol";
+
+contract MutextTest is Test {
+    // -------------------------------------------------------------------------
+    // State
+
+    MutexImpl mutex;
+    MutexAttack attacker;
+
+    // -------------------------------------------------------------------------
+    // Set Up
+
+    function setUp() public {
+        mutex = new MutexImpl();
+        attacker = new MutexAttack();
+    }
+
+    // -------------------------------------------------------------------------
+    // Test - Initialization
+
+    function test_IsUnlockedByDefault() public view {
+        assertFalse(mutex.isLocked());
+    }
+
+    // -------------------------------------------------------------------------
+    // Test - Guards
+
+    function test_UnguardedCanCallGuarded() public {
+        assertEq(mutex.count(), 0);
+        mutex.unguardedToGuarded();
+        assertEq(mutex.count(), 1);
+    }
+
+    function test_GuardedCannotCallGuarded() public {
+        bytes4 err = Mutex.Mutex__Locked.selector;
+        vm.expectRevert(err);
+
+        mutex.guardedToGuarded();
+    }
+
+    function test_UnguardedCanCallGuardedRead() public view {
+        mutex.unguardedToGuardedRead();
+    }
+
+    function test_GuardedCannotCallGuardedRead() public {
+        bytes4 err = Mutex.Mutex__Locked.selector;
+        vm.expectRevert(err);
+
+        mutex.guardedToGuardedRead();
+    }
+
+    function test_UnguardedExternalCallCanReenter() public {
+        assertEq(mutex.count(), 0);
+        mutex.unguardedToExternal(attacker);
+        assertEq(mutex.count(), 1);
+    }
+
+    function test_GuardedExternalCallPreventsReentrancy() public {
+        bytes4 err = MutexAttack.Failed.selector;
+        vm.expectRevert(err);
+
+        mutex.guardedToExternal(attacker);
+    }
+}