Add AccessControl base for role-based authorization

[Jim8y]

Summary

The framework only shipped single-owner Ownable, so every contract that needs more than one privileged account (a minter, a pauser, a fee setter) hand-rolls its own unaudited authorization. This adds AccessControl, the OpenZeppelin AccessControl analog adapted to Neo's static-method model — the single most-used safety primitive in the OZ library.

A role is a 32-byte id; accounts are granted roles, and each role is administered by another role. DEFAULT_ADMIN_ROLE (32 zero bytes) is the root role and is its own admin; the account it is granted to at deployment can administer every other role.

Security properties

• Explicit-actor authorization. Callers pass the acting account and the contract verifies it both holds the required role and witnessed the call (Runtime.CheckWitness), honoring the signer's witness scope. This avoids the confused-deputy hole of deriving the actor from Transaction.Sender, and lets a contract/multisig hold a role.
• No key aliasing. Roles are a fixed 32 bytes, validated on every entry point, so the membership key tag ++ role ++ account is structurally injective — no two distinct (role, account) pairs can collide on one storage cell.
• No single-call brick. The last DEFAULT_ADMIN_ROLE holder can never be removed (guarded on both revoke and renounce), so the contract can never be left un-administrable from one call; root control is handed over by granting to a successor first.
• No init replay. A one-time initialization flag stops a deploy-time re-init from adding a co-admin.
• Idempotent + event-accurate. Grant/revoke/admin-change are idempotent and emit events only on an actual state change; a maintained per-role member count backs the last-admin guard.

API

DEFAULT_ADMIN_ROLE / HasRole / GetRoleAdmin / GetRoleMemberCount ([Safe] reads); GrantRole(role, admin, account) / RevokeRole(role, admin, account) / RenounceRole(role, account); the OnlyRole(role, account) guard authors call at the top of their own role-gated methods; and protected GrantRoleInternal / RevokeRoleInternal / SetRoleAdminInternal cores that are not exported to the ABI. Storage uses reserved prefix 0xFB.

No [OnlyRole] modifier attribute is shipped: a Neo ModifierAttribute.Enter() cannot read the decorated method's runtime arguments, so it could only gate a compile-time-constant role against the wrong actor model. The OnlyRole guard is the runtime-flexible substitute.

Testing

AccessControlTest (24 cases): bootstrap and replay protection, the confused-deputy attack (admin without a witness for this call), grant/revoke/renounce by the wrong party, idempotency, the last-admin brick on both revoke and renounce, safe admin handoff, the admin-role hierarchy (re-pointing a role's admin), malformed-role faults, and the manifest safe-flag + ABI-exclusion surface (protected cores absent from the ABI). Full framework suite green (277).

The design and this implementation were each put through an independent multi-design + adversarial security-audit pass (privilege escalation, bricking, key aliasing, witness bypass, count desync) before submission.

[codecov]

Codecov Report

❌ Patch coverage is 87.36842% with 12 lines in your changes missing coverage. Please review.
✅ Project coverage is 82.99%. Comparing base (752686f) to head (8eb0d57).

Files with missing lines	Patch %	Lines
src/Neo.SmartContract.Framework/AccessControl.cs	87.36%	12 Missing ⚠️

Additional details and impacted files

@@              Coverage Diff              @@
##           master-n3    #1771      +/-   ##
=============================================
+ Coverage      82.95%   82.99%   +0.03%     
=============================================
  Files            306      307       +1     
  Lines          27371    27491     +120     
  Branches        3826     3848      +22     
=============================================
+ Hits           22705    22815     +110     
- Misses          3497     3507      +10     
  Partials        1169     1169              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[ajara87]

lgtm

[Jim8y]

Updated. CI is green and all review threads are resolved.

[shargon]

Why don't use Integers?

[Jim8y]

Addressed. Roles now use integer identifiers directly, with storage keys derived from the integer value.