feat(security): Cross-Contract Call Reentrancy Lock using Host Invocation Key (#073)

[Ranjeet2063]

feat(security): Cross-Contract Call Reentrancy Lock using Host Invocation Key (#73)

Closes #73

Summary

Adds an advanced, multi-tiered Cross-Contract Call Reentrancy Guard to secure external token transfer entry points across task settlements, refunds, and dispute distributions. The protection combines:

1. Host Invocation Key Validation: Inspects active caller, function symbol, execution depth, and ledger sequence to intercept concurrent/recursive re-entry.
2. Strict Call Stack Depth Limits: Prevents unbounded call stack exhaustion by enforcing a configurable depth ceiling (default: 3).
3. Checks-Effects-Interactions (CEI) Invariant Enforcement: Ensures internal task state transitions (TaskStatus::Verified, TaskStatus::Cancelled, TaskStatus::Resolved, escrow release) commit before external token transfers dispatch.

Threat Model & Attack Surface

During external token transfers (token_client.transfer), control temporarily exits TaskManagerContract to the external token contract or recipient address. If the target contract or recipient implements a malicious callback handler, an attacker can attempt recursive entry into task settlement functions (complete_task, cancel_task, resolve_dispute) before state changes take effect, draining escrow funds or claiming duplicate payouts.

Defense-in-Depth Architecture

External Entry Point (e.g. complete_task)
       │
       ▼
[non_reentrant_enter]
  ├── Check GlobalLock == NotEntered? (If Entered ➔ PANIC: "ReentrancyGuard: reentrant call intercepted")
  ├── Check CallDepth + 1 <= MaxCallDepth? (If > Max ➔ PANIC: "ReentrancyGuard: max call depth exceeded")
  ├── Record HostInvocationKey { caller, function, depth, sequence }
  └── Set GlobalLock = Entered & Emit re_lock event
       │
       ▼
[Checks & Effects]
  ├── Verify authorization & task status
  ├── Mutate TaskStatus (Verified / Cancelled / Resolved)
  ├── Record audit root hash & update statistics
  └── Release escrow balance
       │
       ▼
[Interactions]
  └── Dispatch external token_client.transfer(...)
       │ (If malicious callback attempts re-entry ➔ blocked by Layer 1 & Layer 3)
       ▼
[non_reentrant_exit]
  ├── Decrement CallDepth
  ├── Clear HostInvocationKey
  ├── Set GlobalLock = NotEntered
  └── Emit re_rel event

Acceptance Criteria

Criterion	Where	Status
Advanced Host Invocation Key validation guard	src/reentrancy_guard.rs (HostInvocationKey, non_reentrant_enter, non_reentrant_exit)	✅ Implemented
Intercept reentrancy during cross-contract token transfers	src/lib.rs (complete_task, cancel_task, resolve_dispute)	✅ Implemented
Strict call stack depth limits	reentrancy_guard::get_call_depth, set_max_call_depth, get_max_call_depth	✅ Implemented
Security test suite simulating malicious callback contracts	src/reentrancy_test.rs (MaliciousCallbackToken simulating reentrant complete & cancel attacks)	✅ 10/10 Tests Passed
Clean compilation under all profiles	cargo test --lib & cargo build --target wasm32-unknown-unknown --release (201 KB WASM)	✅ Verified Green

Key Changes

• src/reentrancy_guard.rs: New core module containing ReentrancyStatus, HostInvocationKey, ReentrancyKey, guard functions, call depth trackers, and admin configurator.
• src/events.rs: Added event emitters emit_reentrancy_lock_acquired, emit_reentrancy_lock_released, and emit_max_call_depth_updated.
• src/lib.rs:
  • Exported reentrancy_guard and reentrancy_test.
  • Enforced CEI pattern and wrapped complete_task, cancel_task, and resolve_dispute with non_reentrant_enter / non_reentrant_exit.
  • Exposed inspection endpoints: get_reentrancy_status, get_call_depth, get_max_call_depth, get_invocation_key, and set_max_call_depth.
• src/reentrancy_test.rs: Comprehensive 10-test security suite testing cross-contract callback intercepts, stack depth limit violations, authorization checks, and state invariant proofs.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 074ccb20-ea65-49cc-9ed6-94be43b0565a

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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