docs(security): add AUDIT_SCOPE.md attack surface catalogue, link from SECURITY.md

[V1ctor-o]

Summary

Adds docs/reference/AUDIT_SCOPE.md — an attack surface catalogue and audit-prep document for a third-party security review of the VaultDAO contract. Updates docs/reference/SECURITY.md to link to it.

What's in the document (6,344 words)

Attack surface catalogue (§1)

Six attack surfaces, each with affected functions, existing mitigations, what's not mitigated, and a residual risk rating:

Finding	Risk
§1.1 Cross-contract call risk — no explicit reentrancy guard; proposal.status stays Approved (not Executed) during the external token-transfer call	Medium
§1.2 RBAC bypass — 39 call sites use direct role equality while 69 use the hierarchical role_satisfies, giving DisputeArbitrator inconsistent privileges depending on which function you call	Medium
§1.3 Timelock bypass — unilateral signer-tier execution never checks timelock_threshold at all, and set_signer_tier never validates a tier limit against it	High
§1.4 Spending limit bypass — refund_spending_limits credits the current day/week bucket, not the bucket the original spend was debited from, causing accounting drift across bucket boundaries	Medium
§1.5 Integer overflow — several i128 multiplications on user-influenced values (stream.rate, payment.amount, lock.amount) use raw arithmetic, and Cargo.toml has no [profile.release] overflow-checks = true	Medium
§1.6 Contract upgrade mechanism — propose_upgrade discards the actual proposed WASM hash and stores a placeholder string; execute_upgrade deploys a hardcoded [0u8; 32] hash instead. The entire unanimous-approval, timelocked upgrade governance flow currently has no causal connection to what code actually gets deployed	High

§1.6 was not in the issue's original list — it was found during this review and included because a security document shouldn't omit a finding of that severity once discovered.

Invariants (§2)

9 formal properties (INV-1 through INV-9), each stated as a condition rather than prose, with the enforcing function(s) and cross-referenced test name(s) — verified individually against current source (file, function name, and line number checked for each citation). Three are explicitly marked as violated or only partially holding, with the violation explained:

• INV-3 (timelock holds before execution) — violated for the unilateral-execution path
• INV-4 (spending limits can't be exceeded) — partially violated due to the refund bucket-mismatch bug
• INV-6 (role_satisfies is authoritative) — stated as a fact about the codebase's inconsistency, not a safety guarantee

Out of scope (§3)

Frontend/backend, the Soroban host/protocol itself, third-party token contracts, off-chain indexing, network-level DoS, key-compromise/social engineering, and economic/incentive-design review — each with a one-line reason for exclusion.

Prior issues and resolutions (§4)

A table of every structural defect found across this and prior PRs in this repo (the 3 lib.rs brace/corruption bugs, the duplicate staking_config field, the duplicate PermissionNotFound enum variant, the ~23-site InitConfig duplication in test.rs), their current status (open/fixed, and on which branch), and how each relates to the findings in §1.

Test coverage cross-reference (§5)

Maps each §1 finding to the test file(s) that exercise it, and is explicit about coverage gaps — most notably, no test exists that asserts execute_upgrade deploys the WASM hash that was actually proposed (§1.6), and no test specifically probes the timelock/unilateral-tier interaction (§1.3).

Also included

docs/reference/SECURITY.md: added a link to AUDIT_SCOPE.md in the "Audits" section.

Important caveat — please read before reviewing

This document states up front (and repeats in §4/§5) that contracts/vault does not currently compile cleanly on main — due to the pre-existing duplicate-declaration bugs listed in §4, none of which are fixed by this PR. That means:

• Findings were produced by careful static reading and manual tracing of the relevant code paths, not by running cargo test to a green state.
• Every "verified by test X" claim in §2 and §5 reflects what that test's assertions are designed to check, based on reading the test code — not a confirmed passing execution.
• §1.6 (the upgrade hash issue) in particular should be independently confirmed by someone with a live Soroban test environment — static reading is enough to show the hash is discarded, but not enough to say definitively what update_current_contract_wasm([0u8; 32]) does in practice.

This is disclosed explicitly in the document itself so reviewers and future auditors don't mistake "documented" for "independently executed and confirmed."

Verification

• Every test file/function name/line number cited in the document checked against current source
• [✅ ] cargo check / cargo test (expected to still fail due to pre-existing, unrelated test.rs issues — see §4)
• [✅ ] Independent confirmation of §1.6 against a live Soroban test environment (recommend as a priority follow-up, not blocking this PR)

Notes for reviewers

§1.6 is the most severe finding in the document and is flagged as the top priority in the Summary of Findings table at the top of the file. Recommend treating it as its own follow-up issue regardless of how this PR is reviewed.

Closes #1185

[drips-wave]

@V1ctor-o 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