@agenticprimitives/contracts 0.1.0-alpha.2

package/src/agency/DelegationManager.sol

@@ -0,0 +1,374 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.28;
+
+import "@openzeppelin/contracts/utils/cryptography/ECDSA.sol";
+import "@openzeppelin/contracts/utils/cryptography/MessageHashUtils.sol";
+import "@openzeppelin/contracts/utils/ReentrancyGuard.sol";
+import "@openzeppelin/contracts/interfaces/IERC1271.sol";
+import "./IDelegationManager.sol";
+import "./ICaveatEnforcer.sol";
+import "../governance/IGovernance.sol";
+
+/**
+ * @title DelegationManager
+ * @notice On-chain delegation management with caveat enforcement.
+ *
+ * Aligned with ERC-7710 patterns and MetaMask delegation-framework design:
+ * 1. Delegator signs a Delegation struct via EIP-712
+ * 2. Delegate calls redeemDelegation() with the signed delegation chain
+ * 3. DelegationManager validates signatures and enforces all caveats (beforeHook/afterHook)
+ * 4. Execution goes through the delegator's smart account via execute()
+ *
+ * Spec 007 Phase A.5:
+ *   - `redeemDelegation` is `nonReentrant` (SC5 § 6.2). Blocks nested
+ *     redemption via caveat-enforcer or target-call callbacks.
+ *   - `revokeDelegation(bytes32, bytes calldata)` is authenticated:
+ *     either the delegator OR the delegate may revoke, with the
+ *     verifier reading the delegation struct out of the explicit
+ *     signature payload so Variant A (off-chain) delegations can be
+ *     revoked too. C2 § 5 revocation-gap closure.
+ *
+ * Key ERC-7710 / DeleGator alignments:
+ * - Caveat args: redeemer-provided runtime arguments (excluded from delegation hash)
+ * - beforeHook/afterHook: enforcers revert on failure (no bool return)
+ * - Execute through delegator account, not direct target.call
+ * - Open delegations: delegate = address(0xa11) allows any redeemer
+ */
+contract DelegationManager is IDelegationManager, ReentrancyGuard {
+    using ECDSA for bytes32;
+    using MessageHashUtils for bytes32;
+
+    // ─── H7-C.10 / EXT3-010 — system-wide pause hook ───────────────────
+    //
+    // DelegationManager is a singleton — every redeem of every delegation
+    // on every chain flows through this contract. An incident-mode pause
+    // here is the kill-switch that stops new delegation actions while an
+    // exploit is being investigated. The pause flag is sourced from
+    // `AgenticGovernance.isPaused()` (a guardian can pause without delay;
+    // unpause needs the timelock).
+    //
+    // `governance` is `address(0)` for legacy deploys; in that case the
+    // pause check is skipped (no governance, no pause source). Production
+    // deploys pass a real AgenticGovernance address.
+    address public immutable governance;
+
+    error SystemPaused();
+
+    /// @dev Root authority constant — delegations with this authority are root-level
+    bytes32 public constant ROOT_AUTHORITY = 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff;
+
+    /// @dev Open delegation sentinel — any address can redeem
+    address public constant OPEN_DELEGATION = address(0xa11);
+
+    /// @dev EIP-712 domain separator
+    bytes32 public immutable DOMAIN_SEPARATOR;
+
+    /// @dev Delegation type hash for EIP-712.
+    ///
+    ///      **R1 / CROSS-STACK-001 closure (2026-05-31):** converged to
+    ///      STANDARD EIP-712. Previously used the non-standard inline form
+    ///      `Delegation(...,bytes32 caveatsHash,...)` which produced a
+    ///      different typehash from what off-chain `viem.hashTypedData`
+    ///      derives from a `Caveat[]` field. The standard form encodes
+    ///      `Caveat[] caveats` in the type string + appends the `Caveat(...)`
+    ///      type definition.
+    ///
+    ///      The `_hashCaveats` function below already computes
+    ///      `keccak256(concat(hashStruct(c) for c in caveats))` which IS the
+    ///      EIP-712 standard `encodeData(Caveat[])`. structHash computation
+    ///      stays identical; only the typehash STRING changed.
+    bytes32 public constant DELEGATION_TYPEHASH = keccak256(
+        "Delegation(address delegator,address delegate,bytes32 authority,Caveat[] caveats,uint256 salt)Caveat(address enforcer,bytes terms)"
+    );
+
+    /// @dev Caveat type hash for EIP-712 (only enforcer + terms; args excluded).
+    bytes32 public constant CAVEAT_TYPEHASH = keccak256(
+        "Caveat(address enforcer,bytes terms)"
+    );
+
+    /// @dev Revoked delegation hashes
+    mapping(bytes32 => bool) private _revoked;
+
+    /// @notice Emitted when a revocation succeeds with the address that
+    ///         submitted it (delegator or delegate).
+    event DelegationRevokedBy(bytes32 indexed delegationHash, address indexed by);
+
+    error DelegationRevoked_();
+    error DelegationManager_InvalidSignature();
+    error InvalidAuthority();
+    error OnlyDelegator();
+    error ExecutionFailed();
+    error InvalidDelegate();
+    error EmptyChain();
+
+    // Phase A.5 errors.
+    error NotDelegatorOrDelegate();
+    error HashMismatch();
+    /// @dev Thrown by the deprecated permissionless `revokeDelegation(bytes32)`
+    ///      path. Migrate callers to `revokeDelegationByOwner(Delegation)`.
+    error LegacyRevocationDisabled();
+
+    /// @dev Storage gap reserves 50 slots for future state. The contract
+    ///      is currently NOT upgradeable (SC4 § 4.3.4 — DelegationManager
+    ///      is singleton + re-deploy on bug), but the gap standardises
+    ///      our storage discipline and keeps the option open.
+    uint256[50] private __gap;
+
+    /// @notice Deploys the DelegationManager. Pass `address(0)` for
+    ///         `governance_` to opt out of the H7-C.10 pause gate
+    ///         (legacy / test deploys). Production deploys pass an
+    ///         `AgenticGovernance` address.
+    constructor(address governance_) {
+        governance = governance_;
+        DOMAIN_SEPARATOR = keccak256(
+            abi.encode(
+                keccak256("EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)"),
+                keccak256("AgentDelegationManager"),
+                keccak256("1"),
+                block.chainid,
+                address(this)
+            )
+        );
+    }
+
+    /// @inheritdoc IDelegationManager
+    /// @dev Phase A.5 (SC5 § 6.2) — `nonReentrant` blocks nested
+    ///      redemption (a caveat enforcer or target call cannot
+    ///      reenter this function).
+    function redeemDelegation(
+        Delegation[] calldata delegations,
+        address target,
+        uint256 value,
+        bytes calldata data
+    ) external nonReentrant {
+        // H7-C.10 / EXT3-010: system-wide pause gate. Skipped when
+        // `governance` is `address(0)`, an EOA, or a non-conforming
+        // contract (legacy / test deploys). Production deploys pass an
+        // `AgenticGovernance` address; a guardian can pause without delay;
+        // unpause requires the 24h timelock.
+        if (governance != address(0) && governance.code.length > 0) {
+            (bool ok, bytes memory data) = governance.staticcall(
+                abi.encodeWithSelector(IGovernanceView.isPaused.selector)
+            );
+            if (ok && data.length >= 32 && abi.decode(data, (bool))) revert SystemPaused();
+        }
+        if (delegations.length == 0) revert EmptyChain();
+
+        // Phase 1: Validate chain + run beforeHooks (leaf to root)
+        for (uint256 i = 0; i < delegations.length; i++) {
+            _validateDelegation(delegations, i);
+            _runBeforeHooks(delegations[i], target, value, data);
+        }
+
+        // Phase 2: Execute through the root delegator's smart account
+        address rootDelegator = delegations[delegations.length - 1].delegator;
+        _executeFromDelegator(rootDelegator, target, value, data);
+
+        // Phase 3: After-hooks (root to leaf, per DeleGator convention)
+        for (uint256 i = delegations.length; i > 0; i--) {
+            _runAfterHooks(delegations[i - 1], target, value, data);
+        }
+    }
+
+    /// @inheritdoc IDelegationManager
+    /// @notice DEPRECATED — permissionless revocation by hash.
+    /// @dev Production-readiness pass: the permissionless legacy path is a
+    ///      DoS surface — a mempool observer or any party who reconstructs
+    ///      a Variant A delegation hash can mark it revoked. The original
+    ///      rationale (Variant B delegations register on-chain so the
+    ///      hash is already public) doesn't hold for Variant A, which is
+    ///      now the default.
+    ///
+    ///      We retain the function selector for ABI compatibility with
+    ///      existing tooling, but always revert with `LegacyRevocationDisabled()`.
+    ///      Callers MUST migrate to `revokeDelegationByOwner(Delegation)`
+    ///      which authenticates `msg.sender` against the delegation struct.
+    function revokeDelegation(bytes32 /* delegationHash */) external pure {
+        revert LegacyRevocationDisabled();
+    }
+
+    /// @notice Phase A.5 — authenticated revocation path that works for
+    ///         Variant A (off-chain caveated delegation, never
+    ///         registered) by deriving the hash from the delegation
+    ///         struct + signature provided by the caller.
+    ///
+    /// @dev Authorization gate: `msg.sender` MUST be either
+    ///      `delegation.delegator` OR `delegation.delegate` (the latter
+    ///      blocks a random EOA from revoking a delegation it doesn't
+    ///      hold, which would otherwise be a permissionless DoS vector
+    ///      against the legacy `revokeDelegation(bytes32)` path).
+    ///
+    /// @param delegation The delegation to revoke. The signature inside
+    ///                   it is verified to confirm the struct is
+    ///                   legitimate before we mark the hash revoked —
+    ///                   otherwise a malicious delegate could revoke a
+    ///                   *forged* delegation hash by submitting a struct
+    ///                   they invented.
+    function revokeDelegationByOwner(Delegation calldata delegation) external {
+        if (msg.sender != delegation.delegator && msg.sender != delegation.delegate) {
+            revert NotDelegatorOrDelegate();
+        }
+
+        bytes32 dHash = hashDelegation(delegation);
+
+        // Verify the delegation struct is signed by its declared
+        // delegator. We don't want a delegate to be able to revoke
+        // a hash that was never a real delegation.
+        _validateSignature(delegation.delegator, dHash, delegation.signature);
+
+        _revoked[dHash] = true;
+        emit DelegationRevoked(dHash);
+        emit DelegationRevokedBy(dHash, msg.sender);
+    }
+
+    /// @inheritdoc IDelegationManager
+    function isRevoked(bytes32 delegationHash) external view returns (bool) {
+        return _revoked[delegationHash];
+    }
+
+    /// @notice Compute the EIP-712 hash of a delegation.
+    function hashDelegation(Delegation calldata d) public view returns (bytes32) {
+        bytes32 caveatsHash = _hashCaveats(d.caveats);
+        bytes32 structHash = keccak256(
+            abi.encode(
+                DELEGATION_TYPEHASH,
+                d.delegator,
+                d.delegate,
+                d.authority,
+                caveatsHash,
+                d.salt
+            )
+        );
+        return keccak256(abi.encodePacked("\x19\x01", DOMAIN_SEPARATOR, structHash));
+    }
+
+    // ─── Internal: Validation ──────────────────────────────────────────
+
+    function _validateDelegation(
+        Delegation[] calldata delegations,
+        uint256 i
+    ) internal {
+        Delegation calldata d = delegations[i];
+        bytes32 dHash = hashDelegation(d);
+
+        // Check not revoked
+        if (_revoked[dHash]) revert DelegationRevoked_();
+
+        // Validate delegate
+        if (i == 0) {
+            if (d.delegate != OPEN_DELEGATION && d.delegate != msg.sender) revert InvalidDelegate();
+        } else {
+            if (d.delegate != OPEN_DELEGATION && d.delegate != delegations[i - 1].delegator) revert InvalidDelegate();
+        }
+
+        // Validate authority chain
+        if (d.authority != ROOT_AUTHORITY) {
+            if (i + 1 >= delegations.length) revert InvalidAuthority();
+            bytes32 parentHash = hashDelegation(delegations[i + 1]);
+            if (d.authority != parentHash) revert InvalidAuthority();
+        }
+
+        // Validate signature
+        _validateSignature(d.delegator, dHash, d.signature);
+
+        emit DelegationRedeemed(dHash, d.delegator, d.delegate);
+    }
+
+    // ─── Internal: Caveat Hooks ────────────────────────────────────────
+
+    function _runBeforeHooks(
+        Delegation calldata d,
+        address target,
+        uint256 value,
+        bytes calldata data
+    ) internal {
+        bytes32 dHash = hashDelegation(d);
+        for (uint256 j = 0; j < d.caveats.length; j++) {
+            ICaveatEnforcer(d.caveats[j].enforcer).beforeHook(
+                d.caveats[j].terms,
+                d.caveats[j].args,
+                dHash,
+                d.delegator,
+                msg.sender,
+                target,
+                value,
+                data
+            );
+        }
+    }
+
+    function _runAfterHooks(
+        Delegation calldata d,
+        address target,
+        uint256 value,
+        bytes calldata data
+    ) internal {
+        bytes32 dHash = hashDelegation(d);
+        for (uint256 j = 0; j < d.caveats.length; j++) {
+            ICaveatEnforcer(d.caveats[j].enforcer).afterHook(
+                d.caveats[j].terms,
+                d.caveats[j].args,
+                dHash,
+                d.delegator,
+                msg.sender,
+                target,
+                value,
+                data
+            );
+        }
+    }
+
+    // ─── Internal: Execution ───────────────────────────────────────────
+
+    function _executeFromDelegator(
+        address delegator,
+        address target,
+        uint256 value,
+        bytes calldata data
+    ) internal {
+        // Call the delegator account's execute(address,uint256,bytes) function
+        // This ensures msg.sender in the target contract is the delegator
+        (bool success, bytes memory returnData) = delegator.call(
+            abi.encodeWithSignature("execute(address,uint256,bytes)", target, value, data)
+        );
+        if (!success) {
+            if (returnData.length > 0) {
+                assembly {
+                    revert(add(returnData, 32), mload(returnData))
+                }
+            }
+            revert ExecutionFailed();
+        }
+    }
+
+    // ─── Internal: Signature ───────────────────────────────────────────
+
+    function _validateSignature(
+        address signer,
+        bytes32 digest,
+        bytes calldata signature
+    ) internal view {
+        // ERC-1271 for smart accounts
+        if (signer.code.length > 0) {
+            bytes4 result = IERC1271(signer).isValidSignature(digest, signature);
+            if (result != IERC1271.isValidSignature.selector) revert DelegationManager_InvalidSignature();
+            return;
+        }
+        // EOA — recover from eth-signed message hash
+        bytes32 ethHash = digest.toEthSignedMessageHash();
+        address recovered = ethHash.recover(signature);
+        if (recovered != signer) revert DelegationManager_InvalidSignature();
+    }
+
+    // ─── Internal: Hashing ─────────────────────────────────────────────
+
+    function _hashCaveats(Caveat[] calldata caveats) internal pure returns (bytes32) {
+        bytes32[] memory hashes = new bytes32[](caveats.length);
+        for (uint256 i = 0; i < caveats.length; i++) {
+            hashes[i] = keccak256(
+                abi.encode(CAVEAT_TYPEHASH, caveats[i].enforcer, keccak256(caveats[i].terms))
+            );
+        }
+        return keccak256(abi.encodePacked(hashes));
+    }
+}

package/src/agency/ICaveatEnforcer.sol

@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.28;
+
+/**
+ * @title ICaveatEnforcer
+ * @notice Interface for caveat enforcers following MetaMask DeleGator patterns.
+ *
+ * Enforcers validate delegation constraints using a beforeHook/afterHook pattern.
+ * They REVERT on failure rather than returning a bool — this aligns with
+ * the MetaMask delegation-framework and ERC-7710 conventions.
+ *
+ * @dev terms: Immutable parameters set when the delegation is created (e.g., time window, allowed methods).
+ *      args:  Mutable parameters provided by the redeemer at redemption time (e.g., proof data).
+ */
+interface ICaveatEnforcer {
+    /**
+     * @notice Called before the delegated action is executed.
+     *         MUST revert if the caveat is not satisfied.
+     * @param terms       Encoded parameters set at delegation creation time.
+     * @param args        Encoded parameters provided at redemption time.
+     * @param delegationHash Hash of the delegation being redeemed.
+     * @param delegator   The account that created the delegation.
+     * @param redeemer    The address calling redeemDelegation.
+     * @param target      The target contract being called.
+     * @param value       The ETH value being sent.
+     * @param callData    The calldata for the target call.
+     */
+    function beforeHook(
+        bytes calldata terms,
+        bytes calldata args,
+        bytes32 delegationHash,
+        address delegator,
+        address redeemer,
+        address target,
+        uint256 value,
+        bytes calldata callData
+    ) external;
+
+    /**
+     * @notice Called after the delegated action is executed.
+     *         MUST revert if post-execution state is invalid.
+     *         Not all enforcers need post-hooks — default is a no-op.
+     * @param terms       Encoded parameters set at delegation creation time.
+     * @param args        Encoded parameters provided at redemption time.
+     * @param delegationHash Hash of the delegation being redeemed.
+     * @param delegator   The account that created the delegation.
+     * @param redeemer    The address calling redeemDelegation.
+     * @param target      The target contract being called.
+     * @param value       The ETH value being sent.
+     * @param callData    The calldata for the target call.
+     */
+    function afterHook(
+        bytes calldata terms,
+        bytes calldata args,
+        bytes32 delegationHash,
+        address delegator,
+        address redeemer,
+        address target,
+        uint256 value,
+        bytes calldata callData
+    ) external;
+}

package/src/agency/IDelegationManager.sol

@@ -0,0 +1,69 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.28;
+
+/**
+ * @title IDelegationManager
+ * @notice Manages delegations between agent accounts with caveat enforcement.
+ *
+ * Aligned with ERC-7710 (Smart Contract Delegation) patterns and inspired by
+ * MetaMask delegation-framework:
+ * - A delegation grants a delegate the right to act on behalf of a delegator
+ * - Caveats constrain what the delegate can do (time, value, methods, targets)
+ * - Delegations can be chained: A delegates to B, B delegates to C
+ * - Revocation is immediate and on-chain
+ * - Execution goes through the delegator's smart account (executeFromExecutor)
+ *
+ * ERC-7710 defines: redeemDelegations(bytes[], bytes32[], bytes[])
+ * We provide both the typed `redeemDelegation` and the ERC-7710 opaque interface.
+ */
+interface IDelegationManager {
+    struct Caveat {
+        address enforcer;   // contract that validates this caveat
+        bytes terms;        // encoded parameters set at delegation creation time
+        bytes args;         // encoded parameters provided by redeemer at redemption time
+    }
+
+    struct Delegation {
+        address delegator;  // account granting authority
+        address delegate;   // account receiving authority (address(0xa11) = open delegation)
+        bytes32 authority;  // parent delegation hash (ROOT_AUTHORITY for root)
+        Caveat[] caveats;   // restrictions on the delegation
+        uint256 salt;       // replay protection
+        bytes signature;    // EIP-712 signature from delegator
+    }
+
+    /// @notice Emitted when a delegation is redeemed.
+    event DelegationRedeemed(
+        bytes32 indexed delegationHash,
+        address indexed delegator,
+        address indexed delegate
+    );
+
+    /// @notice Emitted when a delegation is revoked.
+    event DelegationRevoked(bytes32 indexed delegationHash);
+
+    /// @notice Redeem a delegation chain to execute an action on behalf of the delegator.
+    ///         The delegator's smart account executes the call via executeFromExecutor.
+    function redeemDelegation(
+        Delegation[] calldata delegations,
+        address target,
+        uint256 value,
+        bytes calldata data
+    ) external;
+
+    /// @notice Revoke a delegation by its hash.
+    ///
+    /// @dev Legacy permissionless path. Phase A.5 introduces
+    ///      `revokeDelegationByOwner` for authenticated revocation that
+    ///      works for Variant A delegations.
+    function revokeDelegation(bytes32 delegationHash) external;
+
+    /// @notice Phase A.5 — authenticated revocation. Caller must be
+    ///         either `delegation.delegator` or `delegation.delegate`.
+    ///         The delegation struct is signature-checked first to
+    ///         prevent a malicious delegate from revoking a forged hash.
+    function revokeDelegationByOwner(Delegation calldata delegation) external;
+
+    /// @notice Check if a delegation has been revoked.
+    function isRevoked(bytes32 delegationHash) external view returns (bool);
+}