fix: contract error handling, referral auth ownership, and CI caching improvements

[ayomideadeniran]

Summary of Changes

This pull request resolves four issues across contract error handling, backend referral authorization, workflow secrets & CLI security, and CI caching optimizations.

---

1. Contract Error Handling & Documentation (#1634)

• Eliminated Panics from Public Entry Points:
  • YieldVault::pause_with_role and unpause_with_role: replaced panic assertions with permissions::require_pauser_or_admin_auth returning Result<(), VaultError>, mapping unauthorized callers cleanly to VaultError::RescueUnauthorized.
  • YieldVault::cancel_emergency_action: replaced expect("Admin not set") and assert!(!proposal.executed) with clean ok_or checks and VaultError::ProposalAlreadyExecuted.
  • YieldVault::set_emergency_dispute_window: returns Result<(), VaultError>, validating that seconds > 0 and returning Err(VaultError::InvalidAmount) instead of panicking via assert!.
  • YieldVault::snapshot_user_balance: returns Result<(), VaultError>, safely matching CheckpointNonce instead of panicking on expect("no checkpoint").
  • YieldVault::execute_withdrawal: re-validates that the user's current share balance is sufficient (balance >= pending.shares) and positive before executing the transfer.
  • YieldVault::do_withdraw: safely looks up TokenAsset with ok_or rather than unwrap.
  • YieldVault::set_strategy: replaced expect("Admin not set") and checked_add().expect("overflow") with ok_or and saturating arithmetic.
• Corrected Documentation:
  • Updated set_strategy docstring under # Errors to correctly reflect returning Err(VaultError::StrategyNotWhitelisted) when the strategy is not whitelisted.

2. Backend Referral Authorization & Endpoints (#1603)

• tenantGuard Middleware Enhancement:
  • Added requireAuth: boolean option to tenantGuard. When enabled, requests without an authenticated wallet (or admin API key) are rejected with 401 Unauthorized ({ error: 'Unauthorized', status: 401, message: 'Authentication required' }).
  • Cross-tenant/non-owner requests continue to be rejected with 403 Forbidden.
  • Admin API keys with Permission.ADMIN_READ bypass the check as expected.
• Referral Endpoints Security:
  • GET /api/v1/referrals/:wallet: protected by tenantGuard with requireAuth: true and admin bypass.
  • GET /api/v1/referrals/code/:wallet: converted to a pure read-only endpoint using referralService.getReferralCode(wallet). Returns 404 Not Found if no referral code has been created for the wallet (avoiding side-effect writes on GET requests). Protected with tenantGuard({ requireAuth: true }).
  • POST /api/v1/referrals/code/:wallet: added dedicated code-creation endpoint invoking referralService.getOrCreateReferralCode(wallet), protected by tenantGuard({ requireAuth: true }).

3. Workflow Secret & Command-Line Security (#1599)

• Non-Secret Configuration Migration:
  • In .github/workflows/load-tests.yml: migrated BASE_URL, ASSET, AMOUNT, and METRICS_PATH from secrets.* to vars.* with fallback to secrets.* and sensible defaults.
  • In .github/workflows/production-deploy.yml: migrated VITE_SOROBAN_RPC_URL, VITE_STELLAR_NETWORK_PASSPHRASE, VITE_VAULT_CONTRACT_ID, VITE_API_BASE_URL, and VITE_SENTRY_DSN from secrets.* to vars.* with fallback.
• Secure Token Passing:
  • In .github/workflows/production-deploy.yml: removed --token=${{ secrets.VERCEL_TOKEN }} from CLI invocations (vercel pull and vercel deploy), avoiding token leakage into process tables and shell logs. Passed VERCEL_TOKEN securely via the env: block where Vercel CLI natively reads it.

4. CI Dependency & Tool Caching (#1598)

• Precompiled Binary Installation:
  • Replaced time-consuming cargo install commands with taiki-e/install-action across CI workflows:
    • cargo-audit in dependency-security.yml and rust-security.yml.
    • cargo-deny in rust-security.yml.
    • cargo-fuzz in rust-wasm.yml.
    • soroban-cli in staging-deploy.yml.
• Dependency Caching:
  • Configured actions/setup-node@v4 with cache: npm and appropriate cache-dependency-path across test-coverage.yml, staging-deploy.yml, and rust-wasm.yml.

---

Verification & Testing

• Contract compilation verified with cargo check -p vault and cargo test -p share-price-math (12 tests passing).
• Backend TypeScript compilation verified for tenantGuard.ts, referralEndpoints.ts, and referralService.ts.
• Workflow YAML syntax validated.

Closes #1634
Closes #1603
Closes #1599
Closes #1598

[drips-wave]

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