Added verification guards for finance actions

[Cofez]

feat: prevent verification bypass on restricted actions

Base branch: main | Head branch: bypass

---

📝 Description

Implements a centralized verification guard system that enforces deny-by-default access control on all restricted finance actions. Unverified, pending, and rejected actors are blocked from invoice uploads, bid placements, settlement initiations, and escrow releases through typed guard functions with exhaustive error variants.

Closes #540

🎯 Type of Change

• New feature
• Security enhancement
• Documentation update

🔧 Changes Made

New Files Added

• src/verification.rs — Centralized guard module (~400 lines, 47 inline unit tests)
• src/test_business_kyc.rs — Business KYC guard tests (37 tests)
• src/test_investor_kyc.rs — Investor KYC guard tests (38 tests)

Files Modified

• src/lib.rs — Added pub mod verification and test module declarations
• docs/contracts/verification.md — Comprehensive guard system documentation

Key Changes

• Deny-by-default guards: guard_invoice_upload, guard_settlement_initiation, guard_escrow_release (business); guard_bid_placement, guard_investment_action (investor)
• State transition enforcement: 3-of-9 transition matrix validated; Verified is terminal
• Investment limit computation: effective_limit = base_limit × tier_multiplier × risk_bps / 10_000 with checked arithmetic
• Per-investment risk caps: High (50K) and VeryHigh (10K) hard caps per individual investment
• Tier qualification: Dual-threshold system requiring both invested amount AND successful investment count
• Input validation: Rejection reason (512B cap) and KYC data (4,096B cap) size limits
• Typed errors: GuardError and TransitionError enums for precise audit trails

🧪 Testing

• Unit tests pass
• No breaking changes introduced
• Edge cases tested

Test Coverage

• 122 total tests across 3 files covering:
  • Negative tests for every guarded path (Pending, Rejected, NotSubmitted) across all 5 guard functions
  • Exhaustive 3×3 state transition matrix (all 9 from/to combinations)
  • All 20 tier × risk investment limit combinations
  • Per-investment risk cap enforcement (High, VeryHigh)
  • Rejection reason and KYC data boundary validation (empty, at-limit, over-limit)
  • Full lifecycle tests (submit → reject → resubmit → verify → action)
  • Error priority verification (status checks before amount checks)
  • Arithmetic overflow protection
  • Deny-by-default property verification
  • Error variant discrimination
  • Tier qualification with dual-threshold enforcement
  • Risk score boundary testing across all 4 risk levels

📋 Contract-Specific Checks

• Security considerations reviewed
• Error handling implemented
• Access control verified

Contract Testing Details

• All guard functions enforce deny-by-default: only Verified status passes
• Investment limits use checked_mul/checked_div to prevent overflow
• Status checks execute before amount checks to prevent limit probing by unverified actors
• Terminal Verified state prevents social-engineering status downgrades

📋 Review Checklist

• Code follows project style guidelines (matches existing fees.rs, settlement.rs, profits.rs patterns)
• Documentation updated
• No sensitive data exposed
• Error handling implemented
• Edge cases considered
• Code is self-documenting
• No hardcoded values (all limits are named constants)

🔍 Code Quality

• Code formatting follows rustfmt standards
• No unused imports or variables
• Functions are properly documented (NatSpec-style doc comments)
• cargo check --tests passes with 0 errors, 0 warnings

🚀 Performance & Security

• No potential security vulnerabilities
• Input validation implemented (size limits on reason/KYC data)
• Access controls properly configured (deny-by-default)
• Checked arithmetic prevents overflow/underflow

📚 Documentation

• docs/contracts/verification.md fully rewritten with guard taxonomy, transition matrix, tier/risk tables, effective limit formula, security assumptions, and test coverage mapping

🔗 Related Issues

Closes #540

🧪 How to Test

1. cargo check --tests — verify all code compiles with zero warnings
2. Review src/verification.rs for guard logic, limit computation, and state transitions
3. Review src/test_business_kyc.rs for negative tests on all business guard paths
4. Review src/test_investor_kyc.rs for investment limit and risk cap enforcement

⚠️ Breaking Changes

None — this is a new module addition with no modifications to existing modules.

[drips-wave]

@Cofez Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits