Authenticate and bound WebSocket connections in the event broadcaster

[priscaenoch]

Problem

src/ws/eventBroadcaster.ts accepts WebSocket connections and supports query-parameter filters (?contract=CXXX..., ?eventType=token_transfer), but there is no authentication, no origin check, and no cap on concurrent connections or subscriptions. Any client can open unlimited sockets and subscribe to the event stream. Closing this gap properly is cross-cutting: it involves the broadcaster, the WebSocket server setup, shared auth middleware, configuration, tests, and documentation.

What needs to be done

• Add an authentication/authorization check on the upgrade/connection handshake, consistent with the rest of the API (API key or token), implemented as reusable middleware.
• Validate the Origin header against an allowlist for browser clients.
• Enforce a per-client and global connection cap, and a cap on active filters/subscriptions per connection, all configurable via environment variables.
• Add heartbeat/ping-pong and idle-timeout handling to reap dead sockets, and send a clear close code/reason when a connection is rejected or a limit is exceeded.
• Document the WebSocket auth model, limits, and configuration.

Files

• src/ws/eventBroadcaster.ts
• the WebSocket server setup (src/ws/ and/or src/index.ts)
• shared auth middleware under src/middleware/
• src/config/ (limits + allowlist)
• .env.example, README.md
• tests under tests/

Acceptance deliverables

• Unauthenticated or disallowed-origin connections are rejected with a defined close code.
• Connection and subscription caps are enforced and configurable.
• The WebSocket auth model and limits are documented.
• All CI checks pass; the change cannot be merged until CI is green.

Tests to pass

• Test: a connection without valid auth is rejected.
• Test: exceeding the connection/subscription cap is rejected.
• Test: an authenticated connection receives filtered events.

[Malik6828]

I’d like to take on this task because it addresses an important reliability issue: configuration errors should be caught immediately at startup rather than appearing later as confusing runtime failures.

My approach would be to introduce a shared, Zod-based validation pattern for both the API and indexer, with centralized network resolution using STELLAR_NETWORK and NODE_ENV. I’ll ensure each service validates only the variables required for its active network, produces clear actionable errors listing the affected keys, and never exposes secret values in logs.

I’ll also update .env.example and the README so the documented configuration stays consistent with the validation schema. I’ll add focused tests covering both complete and incomplete environments for the API and indexer, including invalid configuration cases, and run the existing CI checks to ensure everything remains green.

I’m comfortable working across TypeScript/JavaScript codebases, configuration validation, testing, and documentation, and I’ll keep the implementation focused, maintainable, and aligned with the existing project structure.

[grantfox-oss]

🦊 GrantFox — @Malik6828 has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #42)
2. Your PR will be reviewed by the octraban maintainers

Good luck! Track your progress on GrantFox.