fix(backend): secure wallet aliases and async failures

[ada-nwali]

Pull Request Template

📋 Description

Goal

Protect wallet-alias identity data and prevent cross-wallet identity merges, ensure rejected async handlers reach the Express error boundary, report failed background audit work, and restore vault strategy route registration.

Closes #1604
Closes #1602
Closes #1601
Closes #1600

Changes

• Require bearer authentication on wallet-alias link and resolve routes; enforce ownership of the primary Stellar wallet and restrict reads to the authenticated wallet identity.
• Perform provider-identity links transactionally at serializable isolation and reject attempts to merge distinct canonical identities.
• Load express-async-errors before registering routes so rejected Express 4 handlers reach the existing error boundary.
• Log unhandled process rejections, route fire-and-forget audit writes through a logging helper, and log bulk-export job failures.
• Remove the nested duplicate POST /strategy registration so strategy responds once and gasless-deposit/receipt routes register at startup.
• Add auth, ownership, collision, async-error-forwarding, and service-level identity conflict regression tests.

🔗 Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• ⚠️ Breaking change (fix or feature that would cause existing functionality to change)
• 🌊 Wave submission (contract migration, architectural wave release, or protocol upgrade)
• 📚 Documentation update
• 🔒 Security improvement
• ⚡ Performance optimization

---

🛡️ Risk Assessment

Risk Level

• 🟢 Low: Non-breaking change, documentation, style, or isolated helper refactoring
• 🟡 Medium: API enhancement, frontend workflow update, non-critical dependency upgrade
• 🟠 High: Core contract logic change, access control modification, financial accounting / share math
• 🔴 Critical: Wave submission, contract storage migration, protocol upgrade touching vault funds

Blast Radius & Impact Analysis

• Contract storage layout / data key migration involved
• Value transfer, deposit/withdraw flow, or vault share calculation affected
• External integration (Oracle, Soroban RPC, Bridge, Token contract) affected
• Database schema migration or data backfill required
• Breaking API or interface change affecting downstream clients
• Zero blast radius (isolated tooling / documentation only)

Detailed Risk & Blast Radius Notes:

The wallet-alias link/read API now requires a bearer session, and requests can access only the identity group containing that session wallet. Links reject existing cross-canonical ownership conflicts in a serializable transaction. Async handler failures now use the existing error boundary; background audit and export failures are logged. No contracts, funds flows, database schema, or migrations change.

---

🔄 Rollback Plan

Rollback Strategy & Feasibility

• Clean Git Revert: Revertable with zero persistent state drift
• Contract Upgrade Rollback: Tested rollback to previous contract WASM hash / implementation
• Database Migration Revert: Reversible migration down-script tested and verified
• Feature Flag / Circuit Breaker: Feature can be toggled off instantly without redeployment
• Emergency Pause: Contract pause / freeze mechanism available to halt affected functions
• Forward-Only / Irreversible: State migration cannot be cleanly reversed; emergency recovery runbook linked below

Rollback Trigger Criteria

• Unexpected increases in 5xx responses or authentication failures on wallet-alias routes; missing strategy, gasless-deposit, or receipt routes; or background job/audit error logs indicating regression.

Step-by-Step Rollback Procedure

1. Revert this PR commit and deploy the previous backend revision.
2. Confirm authenticated wallet-alias operations and strategy/gasless/receipt routes behave as before.
3. Review audit and export-job logs; no schema rollback or data migration is required.

---

⚡ Performance Impact

Performance & Resource Assessment

• Smart contract gas / compute units benchmarked (no regression > 5%, or justified below)
• Backend API latency (p95/p99) and database query execution plans verified
• Database indexing verified for newly queried columns (no table scans)
• Frontend bundle size and Time to Interactive (TTI) verified
• Memory allocation and leak checks verified (no memory leaks in long-running services)
• No measurable performance impact (documentation, tests, or trivial changes)

Performance & Gas Profiling Summary:

No contracts or data models changed. Alias linking now uses one serializable database transaction; API performance benchmarks were not run.

---

🔒 SECURITY REVIEW (⭐ MANDATORY FOR SMART CONTRACT CHANGES)

For all smart contract code changes, complete the following checklist.

See docs/SECURITY_CHECKLIST.md for detailed guidance.

Required: Security Checklist Sign-Off

• I have reviewed this PR against the Internal Security Checklist (docs/SECURITY_CHECKLIST.md)

  • Reentrancy: Verified Checks-Effects-Interactions (CEI) pattern
  • Access Control: Confirmed all sensitive functions are protected (onlyOwner, onlyRole(), etc.)
  • Input Validation: Validated all parameters have appropriate bounds checks
  • Unchecked Returns: All external calls have return value checks (require(success, ...))
  • Gas Limits: No unbounded loops or potential DOS vectors

  If any checkbox cannot be verified, explain below:

  Not applicable: this PR changes backend TypeScript only and does not modify smart contracts.
  

Slither Static Analysis Results

• Ran Slither locally: slither . --config-file slither.config.json

  • Result: Not run; there are no smart-contract changes in this PR.

• GitHub Actions Slither workflow passed:

  • 🟢 All High/Medium findings fixed OR
  • 🟡 All false positives documented with FP references

Slither is not applicable to this backend-only change; CI checks have not run yet.

If this PR has security findings, document them below:

Handling Security Findings

Option A: Fixed in This PR ✅

• Vulnerability identified and resolved
• Test case added to verify fix
• Explain fix below:

  The auth/ownership and cross-identity merge paths are guarded and regression tests were added. Test execution is pending.
  

Option B: False Positive 🟡

• Identified as false positive (tool limitation or misleading check)
• Added entry to contracts/.false-positives.md with:
  • Detector rule name
  • Technical reasoning (3+ sentences why it's safe)
  • Evidence (code snippet, test case, or reference)
• Reference number (e.g., FP-001):

• Inline suppression added to code:

  // slither-disable-next-line <detector-name>
  // Reason: [one-line reason]

Option C: Accepted Risk ⚠️

• Acknowledged as low-priority style issue (naming conventions, etc.)
• Added to Slither exclusions
• Explain below:

---

📝 Testing

Functional Testing

• Unit tests added/updated for changes
• Integration tests passing
• End-to-end (E2E) tests passing
• Manual testing completed and documented below:

  `npm test` and the focused wallet-alias tests were not run in this session. Changed-file TypeScript syntax parsing passed.
  

cd backend && npm run typecheck failed during the schema prebuild because @typescript/typescript-darwin-arm64 could not be resolved.
cd backend && ./node_modules/.bin/tsc --noEmit failed on pre-existing syntax errors in src/eventOutbox.ts (duplicate const record, present at HEAD).
cd backend && ./node_modules/.bin/eslint src/walletAliasEndpoints.ts src/adminAudit.ts src/index.ts src/vaultEndpoints.ts src/__tests__/walletAliasEndpoints.test.ts was blocked because root package.json is invalid JSON at line 83.

### Security Testing
- For state-changing functions:
- [ ] Reentrancy test (if applicable): Verify re-entry is blocked
- [ ] Access control test: Verify unauthorized access is rejected
- [ ] Boundary / Edge-case test: Verify limits, zero-amounts, and rounding behavior

- For external integrations:
- [ ] Return value verification test
- [ ] Failure / timeout scenario test

### Test Coverage
- [ ] All new code paths have test coverage
- [ ] Security-critical paths have comprehensive test cases
- [ ] Coverage report:

Coverage was not collected because tests were not run.

---

## 🚀 Deployment Notes

### Mainnet Readiness
- [ ] This code is ready for production deployment
- [ ] All critical tests pass
- [ ] Security review approved
- [ ] No temporary debug code
- [ ] No TODO comments

### Breaking Changes
If this PR introduces breaking changes:
- [ ] Migration guide provided
- [ ] Deprecation period defined: `[timeframe]`
- [ ] Legacy code deprecated with warnings

---

## 📊 Automated Scan Results

<!-- GitHub Actions will update this section -->

### Slither Analysis
- ✓ Status: Not run (backend-only change; Slither not applicable)
- 🔴 High/Medium findings: 0
- 🟡 Low/Informational findings: 0

### Related Documentation
- [Security Checklist](docs/SECURITY_CHECKLIST.md) — Use for code review
- [False Positive Process](docs/FALSE_POSITIVE_HANDLING.md) — For non-vulnerabilities
- [Slither Configuration](slither.config.json) — Current scanner settings

---

## ✅ Reviewer Checklist

**For code reviewers** (use this to guide your review):

- [ ] PR author completed Risk Assessment and Rollback Plan ✓
- [ ] Performance and gas impact evaluated and verified ✓
- [ ] PR author completed security checklist ✓
- [ ] All findings documented and categorized (fixed/false positive/excluded)
- [ ] Inline security comments are clear and justified
- [ ] Tests cover security-critical code paths
- [ ] No external calls bypass return value checks
- [ ] Access control is properly enforced
- [ ] State updates follow CEI pattern
- [ ] Input validation is comprehensive
- [ ] Follow-up actions (if any) tracked in issues

---

## 📞 Questions or Issues?

- 🤔 Confused about security checklist? → See [`docs/SECURITY_CHECKLIST.md`](/docs/SECURITY_CHECKLIST.md)
- 🔍 Marking finding as false positive? → Follow [`docs/FALSE_POSITIVE_HANDLING.md`](/docs/FALSE_POSITIVE_HANDLING.md)
- 🆘 Need security review help? → Tag `@security-team` in comments

---

## 📋 Pre-Submit Checklist

Before marking PR as ready for review:

- [ ] Description, Goal, and Changes are clearly stated
- [ ] Risk Assessment completed with appropriate risk tier and blast radius
- [ ] Rollback Plan completed with concrete steps and trigger criteria
- [ ] Performance Impact assessed with gas / compute benchmarks
- [ ] All security checklist items checked (✅ or explanation provided)
- [ ] All tests passing locally: `npm test` (not run)
- [ ] Linter passing: `npm run lint` (not run; targeted ESLint invocation was blocked by invalid root `package.json`)
- [ ] Slither passing locally OR findings documented: `slither . --config-file slither.config.json` (not applicable; no contract changes)
- [ ] Code follows project style guide
- [ ] No merge conflicts
- [ ] Commits are clean and well-documented
- [ ] Branch is up-to-date with main/develop
- [ ] For **release PRs**: `docs/RELEASE_READINESS_CHECKLIST.md` completed and linked in PR description

---

**✅ Ready for Review?** Ensure all items above are checked before requesting review.

[drips-wave]

@ada-nwali 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