feat: enhance CI workflow, add CORS handling, and update documentation

[promisszn]

Pull Request: Implement Contract CI, Deployment, Documentation, and CORS Security

Summary

Implement Stellar contract CI/CD automation, contract deployment script, developer documentation, and CORS origin whitelisting to improve the development workflow and security posture.

• Added Stellar CLI installation and WASM optimization steps to CI workflow.
• Created automated deployment script (scripts/deploy.sh) to build, optimize, and deploy contracts.
• Improved CORS middleware to default to localhost in development and enforce origin whitelisting.
• Added tests for CORS functionality.
• Updated architecture and development documentation for clarity and completeness.

Type of Change

• 🐛 Bug fix (non-breaking change which fixes an issue)
• ✨ New feature (non-breaking change which adds functionality)
• 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
• 📚 Documentation update
• 🔧 Refactoring (no functional changes)
• ⚡ Performance improvement
• 🧪 Test addition or update

Related Issues

Closes #248, Closes #249, Closes #250, Closes #251

Changes Made

1. CI Workflow Enhancement (#248)

• File: .github/workflows/ci.yml
• Added Stellar CLI installation via official install script: curl -fsSL https://github.com/stellar/stellar-cli/raw/main/install.sh | sh -s -- --install-deps
• Added cargo build --target wasm32-unknown-unknown --release to compile WASM contract
• Added stellar contract optimize step to optimize generated WASM binaries for deployment
• Configured artifact upload for optimized WASM files using actions/upload-artifact@v4
• Ensures build fails if WASM compilation or optimization fails

2. Contract Deployment Script (#249)

• File: scripts/deploy.sh (new)
• Accepts --network and --source-account CLI arguments
• Automates the full deployment pipeline: build → optimize → deploy
• Uses stellar contract deploy to submit contract to network
• Extracts contract ID from deployment output
• Saves deployment metadata to deploy/deployment-info.json (network, WASM path, optimized WASM path, contract ID, raw output)
• Supports testnet and mainnet deployments

3. Developer Documentation (#250)

• File: docs/DEVELOPMENT.md (new)
  • Prerequisites section (Node.js v20, Rust, stellar CLI, jq)
  • Local environment setup with Prisma database initialization
  • Build, test, and deploy commands
  • Detailed deployment workflow using scripts/deploy.sh
• File: docs/ARCHITECTURE.md (updated)
  • Added Mermaid flowchart showing contract → indexer → database → API → UI flow
  • Expanded component descriptions and system overview

4. CORS Security (#251)

• File: backend/src/app.ts
  • Reads CORS_ALLOWED_ORIGINS environment variable (comma-separated list)
  • Defaults to http://localhost:3000 in development when env var is unset
  • Non-browser requests (no Origin header) are allowed
  • Disallowed origins receive HTTP 403 with { error: 'CORS origin not allowed' } JSON response
  • Added error handler middleware to map CORS errors to 403 status
• File: backend/.env.example (updated)
  • Added comment documenting CORS_ALLOWED_ORIGINS usage and development default
• File: backend/tests/cors.test.ts (new)
  • Vitest + supertest test verifying non-whitelisted origins return 403
  • Validates JSON error response structure

Testing

Test Coverage

• Unit tests added/updated
• Integration tests added/updated

Test Results

Backend Test Suite (Vitest):

• tests/claimable.service.test.ts: ✓ 6 passed
• tests/cors.test.ts: ✓ 1 passed (new test for CORS 403 response)
• tests/deprecated.test.ts: ✓ 2 passed
• tests/rate-limiter.test.ts: ✓ 2 passed
• tests/stream.test.ts: ✓ 3 passed

Total: 5 test files, 14 tests — all passing

Fixed Issues During Implementation

• Fixed backend/src/controllers/sse.controller.ts: Made subscribe handler async to support await on Prisma queries
• Generated Prisma client via npx prisma generate

Test Steps

1. CORS validation:

   cd backend
   npm install
   npm test

   Verify test file cors.test.ts passes.

2. Manual CORS test (when server running):

   curl -H "Origin: https://evil.example" http://localhost:3001/
   # Expected: 403 { error: 'CORS origin not allowed' }

3. Deploy script validation (requires Stellar testnet setup):

   export STELLAR_SECRET="your-testnet-secret"
   export STELLAR_PUBLIC="your-testnet-public"
   chmod +x scripts/deploy.sh
   ./scripts/deploy.sh --network testnet --source-account "$STELLAR_PUBLIC"
   cat deploy/deployment-info.json
   # Expected: JSON with contract_id, network, wasm, optimized_wasm paths

Breaking Changes

Potential Breaking Change: CORS is now restricted by default in production.

• Old behavior: In development, all origins accepted. In production, CORS callback was permissive without env var set.
• New behavior: Development defaults to http://localhost:3000 only. Production requires explicit CORS_ALLOWED_ORIGINS env var. Non-matching origins receive 403 instead of silent rejection.

Migration Guide:

• Production deployments must set CORS_ALLOWED_ORIGINS to comma-separated list of allowed frontend URLs (e.g., https://app.flowfi.xyz,https://flowfi.xyz).
• Verify CI/deployment secrets include CORS_ALLOWED_ORIGINS.
• Local dev continues to work without changes if .env is not set (defaults to http://localhost:3000).

Screenshots/Demo

N/A (infrastructure/backend changes)

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published
• I have checked for breaking changes and documented them if applicable

Additional Notes

• scripts/deploy.sh requires stellar CLI and jq to be available in the environment. CI installs both; local developers should follow docs/DEVELOPMENT.md.
• Prisma client generation is now part of the test setup; ensure npx prisma generate is run before tests if schema changes.
• Architecture docs include Mermaid diagram; renders in GitHub and most markdown viewers.
• CORS tests use Vitest and supertest; expand with additional origin patterns as needed.