Docs/expired account recovery runbook

[mijinummi]

📝 Summary & Key Changes

This PR establishes the bridgelet-audit/ directory with operational runbooks and threat models covering contract trust boundaries, administrative privileges, token handling assumptions, and recovery procedures.

Closes #277
Closes #280
Closes #276
Closes #274

1. 📖 Operational Runbook: Stuck/Expired Account Recovery — Closes #280

• File Added: bridgelet-audit/runbooks/stuck-expired-account-recovery.md
• Diagnostics: Outlined step-by-step verification using is_expired() and get_status() prior to taking recovery actions.
• Execution Paths: Detailed permissionless expire() vs. restricted recover() (creator/recovery address) invocation conditions.
• Reserve Cleanup: Documented post-recovery reserve reclamation using reclaim_reserve() and noted its idempotent safety guarantees.

2. 🗺️ Threat Model: Cross-Contract Trust Boundaries — Closes #274

• File Added: bridgelet-audit/threat-models/cross-contract-trust-boundaries.md
• Interaction Mapping: Modeled cross-contract call flows between AccountFactory, SweepController, EphemeralAccount, and standard token contracts.
• Trust Verification: Analyzed expectations vs. on-chain validations for code identity, initialization, interface compliance, and batch gas griefing risks.

3. 🛡️ Threat Model: Upgrade & Admin Authority — Closes #276

• File Added: bridgelet-audit/threat-models/upgrade-admin-authority.md
• Capability Matrix: Documented administrative entrypoints across all workspace contracts, including EphemeralAccountContract::upgrade() and ReserveContract::set_base_reserve().
• Immutability Fact: Noted the factual absence of upgrade entrypoints in AccountFactory and SweepController.
• Blast Radius Analysis: Evaluated key compromise scenarios per contract and recommended multi-sig/timelock governance controls.

4. 🪙 Threat Model: Token Transfer Trust Assumptions — Closes #277

• File Added: bridgelet-audit/threat-models/token-transfer-trust-assumptions.md
• Asset Assumptions: Evaluated trust assumptions regarding payment.asset compliance with SEP-41 / Soroban Asset Contract standards in execute_transfers.
• Malicious Vectors: Detailed gas griefing, selective panic DOS, and control flow hijacking risks.
• Reentrancy: Cross-referenced Soroban runtime protections and internal checks-effects-interactions ordering documented in docs/reentrancy-analysis.md.

---

📁 Files Added

• bridgelet-audit/runbooks/stuck-expired-account-recovery.md
• bridgelet-audit/threat-models/cross-contract-trust-boundaries.md
• bridgelet-audit/threat-models/upgrade-admin-authority.md
• bridgelet-audit/threat-models/token-transfer-trust-assumptions.md

---

✅ Checklist

• Documentation-only changes contained entirely within bridgelet-audit/
• All diagrams, interfaces, and function references verified against contract source
• Cross-references to existing core docs validated
• Closes [Operational runbook] bridgelet-audit/runbooks/stuck-expired-account-recovery.md: Recovering funds from a stuck or expired ephemeral account #280, [Threat-model writeup] bridgelet-audit/threat-models/cross-contract-trust-boundaries.md: Cross-contract trust boundaries #274, [Threat-model writeup] bridgelet-audit/threat-models/upgrade-admin-authority.md: Upgrade / admin authority threat model #276, [Threat-model writeup] bridgelet-audit/threat-models/token-transfer-trust-assumptions.md: Token transfer trust assumptions #277

[drips-wave]

@mijinummi 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