Add shielded access control

[andrew-fleming]

Supersedes #190 -> keeps commit history clean in original PR by not changing history with f/p signed commits. Resolves #88

Summary by CodeRabbit

Release Notes

• New Features

  • Introduced a new shielded role-based access control system supporting secure role assignment, revocation, and self-revocation workflows.

• Tests

  • Added extensive test coverage and testing utilities for the access control system, including initialization validation and state management verification.

• Documentation

  • Updated simulator documentation and quick-start examples with improved type configuration guidance.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 75fcc7ce-dae1-49b0-ae25-f90e356a2001

📥 Commits

Reviewing files that changed from the base of the PR and between c953f86 and b56a359.

📒 Files selected for processing (24)

• CHANGELOG.md
• contracts/src/access/ShieldedAccessControl.compact
• contracts/src/access/test/ShieldedAccessControl.test.ts
• contracts/src/access/test/mocks/MockAccessControl.compact
• contracts/src/access/test/mocks/MockOwnable.compact
• contracts/src/access/test/mocks/MockShieldedAccessControl.compact
• contracts/src/access/test/mocks/MockZOwnablePK.compact
• contracts/src/access/test/simulators/ShieldedAccessControlSimulator.ts
• contracts/src/access/test/simulators/ZOwnablePKSimulator.ts
• contracts/src/access/witnesses/ShieldedAccessControlWitnesses.ts
• contracts/src/access/witnesses/ZOwnablePKWitnesses.ts
• contracts/src/archive/test/mocks/MockShieldedToken.compact
• contracts/src/security/test/mocks/MockInitializable.compact
• contracts/src/security/test/mocks/MockPausable.compact
• contracts/src/token/test/mocks/MockFungibleToken.compact
• contracts/src/token/test/mocks/MockMultiToken.compact
• contracts/src/token/test/mocks/MockNonFungibleToken.compact
• contracts/src/utils/test/mocks/MockUtils.compact
• contracts/test-utils/address.ts
• packages/simulator/README.md
• packages/simulator/test/fixtures/sample-contracts/witnesses/SampleZOwnableWitnesses.ts
• packages/simulator/test/fixtures/sample-contracts/witnesses/WitnessWitnesses.ts
• packages/simulator/test/integration/SampleZOwnableSimulator.ts
• packages/simulator/test/integration/WitnessSimulator.ts

---

Walkthrough

This PR introduces a complete shielded access control module enabling role-based access without publicly disclosing role assignments. The core implementation uses Merkle trees to store role commitments, derives account identifiers from secret keys, and validates authorization through witness-backed circuit proofs. Supporting infrastructure includes a comprehensive test suite, simulators, witness implementations, and updates existing witness interfaces to be generic over ledger types.

Changes

Cohort / File(s)	Summary
Shielded Access Control Core contracts/src/access/ShieldedAccessControl.compact, contracts/src/access/witnesses/ShieldedAccessControlWitnesses.ts, contracts/src/access/test/simulators/ShieldedAccessControlSimulator.ts	Implements shielded role-based access control with Merkle tree ledger for role commitments, role admin mappings, revocation nullifiers, and sealed instance salt. Provides authorization circuits (assertOnlyRole, canProveRole), role management (grantRole, revokeRole, renounceRole), and account/commitment derivation via witness-based secret key and Merkle path proofs.
Shielded Access Control Testing contracts/src/access/test/ShieldedAccessControl.test.ts, contracts/src/access/test/mocks/MockShieldedAccessControl.compact	Comprehensive 1366-line test suite covering initialization, deterministic hashing, role verification, authorization flows, state transitions, and Merkle tree operations. Mock contract re-exports and wraps production circuits for testing exposure of internal logic.
Witness Type Generalization contracts/src/access/witnesses/ZOwnablePKWitnesses.ts, contracts/src/access/test/simulators/ZOwnablePKSimulator.ts, packages/simulator/test/fixtures/sample-contracts/witnesses/SampleZOwnableWitnesses.ts, packages/simulator/test/fixtures/sample-contracts/witnesses/WitnessWitnesses.ts, packages/simulator/test/integration/SampleZOwnableSimulator.ts, packages/simulator/test/integration/WitnessSimulator.ts	Generalized witness interfaces and factories to be parameterized over concrete ledger type L, changing IZOwnablePKWitnesses<P> to IZOwnablePKWitnesses<L, P> and updating context parameter types from WitnessContext<Ledger, P> to WitnessContext<L, P>.
Documentation & Type Improvements packages/simulator/README.md, contracts/test-utils/address.ts	Updated README with extracted ledger type alias examples showing how to parameterize witness factories. Added explicit return type to createEitherTestUser function signature.
Test-Only Warnings contracts/src/access/test/mocks/MockAccessControl.compact, contracts/src/access/test/mocks/MockOwnable.compact, contracts/src/access/test/mocks/MockZOwnablePK.compact, contracts/src/archive/test/mocks/MockShieldedToken.compact, contracts/src/security/test/mocks/MockInitializable.compact, contracts/src/security/test/mocks/MockPausable.compact, contracts/src/token/test/mocks/MockFungibleToken.compact, contracts/src/token/test/mocks/MockMultiToken.compact, contracts/src/token/test/mocks/MockNonFungibleToken.compact, contracts/src/utils/test/mocks/MockUtils.compact	Added prominent test-only warnings with SPDX license identifiers clarifying that mocks expose internal circuits, bypass safety checks, and must not be deployed in production.
Changelog CHANGELOG.md	Added single entry documenting use of generic ledger type in ZOwnablePKWitnesses.

Sequence Diagram(s)

sequenceDiagram
    actor User
    participant Contract as ShieldedAccessControl
    participant Witness as Witness System
    participant PrivateState as Private State
    participant Ledger as Merkle Tree Ledger
    
    User->>Contract: assertOnlyRole(role)
    Contract->>Witness: wit_secretKey()
    Witness->>PrivateState: retrieve secretKey
    PrivateState-->>Witness: secretKey
    Witness-->>Contract: [privateState, secretKey]
    
    Contract->>Contract: computeAccountId(secretKey, instanceSalt)
    Contract->>Contract: computeRoleCommitment(role, accountId)
    
    Contract->>Witness: wit_getRoleCommitmentPath(roleCommitment)
    Witness->>Ledger: findPathForLeaf(roleCommitment)
    Ledger-->>Witness: merkleTreePath
    Witness-->>Contract: [privateState, merkleTreePath]
    
    Contract->>Contract: computeNullifier(roleCommitment)
    Contract->>Ledger: check nullifier membership
    Ledger-->>Contract: nullifier status
    
    alt Role is valid and not revoked
        Contract-->>User: ✓ Authorization granted
    else Role not found or revoked
        Contract-->>User: ✗ Authorization denied
    end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

The PR introduces substantial new functionality with a comprehensive shielded access control module (782 lines), extensive test coverage (1366 lines), and simulator implementations. However, the witness type generalization follows a consistent, repetitive pattern across multiple files, reducing per-file complexity. The changes span diverse areas (Compact circuits, TypeScript utilities, tests, documentation) requiring separate reasoning for each cohort, but the core logic is well-contained within the ShieldedAccessControl module.

Possibly related PRs

• Migrate to Compact 0.26.0 #279: Updates witness interface typing by making ZOwnablePKWitnesses generic over ledger type L and changing WitnessContext parameter types—the same witness generalization pattern applied in this PR.
• Upgrade Simulator, Contracts to 0.29.0 #366: Applies identical witness generalization (making witness factories generic over L) across the codebase, creating a direct code-level dependency.

Suggested reviewers

• 0xisk

---

🐰 A shielded role unfolds with care,
Merkle roots commit what's kept so rare,
Witness paths let secrets stay secure,
While smart commitments help endure,
Access flows where privacy's paramount! 🌳

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}