feat: enforce timelocked unpause in emergency killswitch

[ScriptedBro]

PR: feat: enforce timelocked unpause in emergency killswitch

Branch: feature/killswitch-timelock → main

Summary

Closes #660
Closes #660

This pull request implements the Unpause Timelock safety invariants for the emergency_killswitch contract. The mechanism introduces a mandatory cooling-off window during an incident, preventing rapid-cycle state oscillations and accidental premature reactivation of the contract.

---

Changes

• emergency_killswitch/src/lib.rs:

  • Added the Error::InvalidSchedule (5) error code.
  • Updated pause to automatically cancel and remove any pending unpause schedule (DataKey::UnpauseSchedule) to prevent the bypass of cooling-off windows with stale/queued schedules.
  • Updated unpause to strictly enforce env.ledger().timestamp() >= scheduled_time using the schedule recorded under DataKey::UnpauseSchedule, returning Error::InvalidSchedule if no schedule is active, and Error::Unauthorized if called prematurely.
  • Updated schedule_unpause to reject past-dated schedules (time < env.ledger().timestamp()) with Error::InvalidSchedule, ensuring the timelock cannot be bypassed by scheduling in the past.
  • Added clean inline /// documentation on the timelock invariants.

• emergency_killswitch/tests/test_killswitch.rs:

  • Added robust unit tests using ledger time travel to cover all edge cases:
    • test_premature_unpause_rejection: Asserts that unpause fails before the scheduled time and succeeds exactly at the boundary.
    • test_re_pause_cancels_schedule: Asserts that a new pause cancels any existing schedule, requiring a new schedule to be set.
    • test_timelock_bypass_rejection: Asserts that past-dated unpause schedule timestamps are immediately rejected.
    • Cleaned up unused variable warnings (_unauthorized).

• emergency_killswitch/THREAT_MODEL.md:

  • Updated identified threat vectors to document the new timelock security invariants, specifically detailing mitigation of rapid toggle abuse (oscillation) and premature reactivation, referencing schedule_unpause, unpause, is_paused, pause, and DataKey.

• docs/killswitch-timelock.md:

  • Created a comprehensive architectural document detailing the state representation, actions, transition diagrams, error codes, and security verification.

---

Test Output

running 8 tests
test test_module_pause ... ok
test test_authorized_emergency_flow ... ok
test test_per_function_pause ... ok
test test_max_paused_functions_limit ... ok
test test_premature_unpause_rejection ... ok
test test_re_pause_cancels_schedule ... ok
test test_timelock_bypass_rejection ... ok
test test_unauthorized_emergency_trigger ... ok

test result: ok. 8 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.19s