# Security Layers That Protect World Monitor's API Endpoints from Unauthorized Access

> Discover the robust security layers protecting World Monitor API endpoints. Explore CORS validation, API key enforcement, rate limiting, and secret management to prevent unauthorized access.

- Repository: [Elie Habib/worldmonitor](https://github.com/koala73/worldmonitor)
- Tags: best-practices
- Published: 2026-03-09

---

**World Monitor implements a defense-in-depth strategy that combines CORS origin validation, API key enforcement, rate limiting, and runtime secret management to block unauthorized requests before they reach business logic.**

The `koala73/worldmonitor` repository secures its public API through multiple overlapping security layers. Understanding how these security layers protect World Monitor's API endpoints from unauthorized access helps developers integrate correctly and security researchers audit the architecture.

## CORS and Origin Whitelisting

The first gatekeeper resides in [`server/cors.ts`](https://github.com/koala73/worldmonitor/blob/main/server/cors.ts), which implements strict **origin validation**. The system maintains an `ALLOWED_ORIGIN_PATTERNS` list that explicitly permits requests from the production application, Vercel preview domains, localhost during development, and the native desktop application.

The `isAllowedOrigin()` function evaluates incoming requests against these patterns. If the origin does not match, the gateway immediately returns an HTTP 403 response, preventing unauthorized cross-origin requests from receiving CORS headers or reaching downstream logic.

## API Key Validation

The second security layer enforces authentication via the **`X-WorldMonitor-Key`** header, implemented in [`api/_api-key.js`](https://github.com/koala73/worldmonitor/blob/main/api/_api-key.js). The `validateApiKey()` function checks submitted keys against the `WORLDMONITOR_VALID_KEYS` environment variable, which contains a whitelist of valid credentials.

### Desktop vs Browser Origin Requirements

The system applies differentiated policies based on client type. The `isDesktopOrigin()` function identifies requests from the native desktop application, which **always require a valid API key** regardless of the endpoint. Conversely, `isTrustedBrowserOrigin()` recognizes browser-based requests, which may access public endpoints without authentication.

### Premium RPC Path Protection

Certain high-value endpoints listed in `PREMIUM_RPC_PATHS` (such as stock analysis and back-testing) force key validation even for trusted browser origins. The [`gateway.ts`](https://github.com/koala73/worldmonitor/blob/main/gateway.ts) file implements this logic by invoking `validateApiKey(request, { forceKey: PREMIUM_RPC_PATHS.has(pathname) })`, ensuring sensitive operations remain protected.

## Rate Limiting

To prevent abuse, World Monitor implements dual-layer rate limiting in [`server/_shared/rate-limit.ts`](https://github.com/koala73/worldmonitor/blob/main/server/_shared/rate-limit.ts). The `checkRateLimit()` function enforces a global sliding-window limit of **600 requests per 60 seconds** per IP address, while `checkEndpointRateLimit()` applies stricter quotas to specific high-value endpoints (such as 3,000 requests per 60 seconds for article summarization).

The system extracts client IP addresses using the `getClientIp()` function, which prioritizes the **`cf-connecting-ip`** header set by Cloudflare, falling back to `x-real-ip` when necessary. This approach avoids trusting the client-controlled `x-forwarded-for` header to prevent IP spoofing.

## Runtime Secret Handling

The desktop client manages API keys through the runtime configuration service in [`src/services/runtime-config.ts`](https://github.com/koala73/worldmonitor/blob/main/src/services/runtime-config.ts). The `validateSecret()` function ensures keys conform to expected formats before storage, while `pushSecretToSidecar()` injects the `WORLDMONITOR_API_KEY` into outbound requests as the `X-WorldMonitor-Key` header. This ensures internal clients undergo the same validation gate as external consumers.

## How the Security Layers Work Together

The orchestration of these protections occurs in [`server/gateway.ts`](https://github.com/koala73/worldmonitor/blob/main/server/gateway.ts), which processes every incoming request through a strict pipeline:

1. **Origin validation** — `isAllowedOrigin()` rejects untrusted sources with a 403 response.
2. **CORS header generation** — `getCorsHeaders()` attaches appropriate cross-origin policies.
3. **API key verification** — `validateApiKey()` enforces authentication based on client type and endpoint sensitivity.
4. **Rate limit enforcement** — `checkEndpointRateLimit()` and `checkRateLimit()` return 429 responses for excessive traffic.
5. **Request routing** — Only after passing all gates does the request reach the business logic handler.

This defense-in-depth architecture ensures that unauthorized access attempts are blocked at multiple stages, minimizing the attack surface exposed to potential adversaries.

## Code Examples

Calling a public endpoint from a trusted browser origin (no key required):

```bash
curl -i https://api.worldmonitor.app/api/market/v1/list-market-quotes

```

Calling a premium endpoint that requires an API key:

```bash
curl -i \
  -H "X-WorldMonitor-Key: my-valid-key-1234" \
  https://api.worldmonitor.app/api/market/v1/analyze-stock \
  -d '{"ticker":"AAPL"}' -X POST

```

Desktop client request (key always required):

```bash
curl -i \
  -H "X-WorldMonitor-Key: $(cat ~/.worldmonitor/key)" \
  https://api.worldmonitor.app/api/maritime/v1/list-navigational-warnings

```

Demonstrating rate-limit handling (exceeding the 600 req/min limit):

```bash
for i in {1..650}; do
  curl -s -o /dev/null -w "%{http_code}\n" \
    -H "X-WorldMonitor-Key: my-valid-key-1234" \
    https://api.worldmonitor.app/api/news/v1/summarize-article-cache
done | tail -n 5

```

## Summary

- **CORS origin whitelisting** in [`server/cors.ts`](https://github.com/koala73/worldmonitor/blob/main/server/cors.ts) blocks unauthorized cross-origin requests before they reach the API.
- **API key validation** via `X-WorldMonitor-Key` in [`api/_api-key.js`](https://github.com/koala73/worldmonitor/blob/main/api/_api-key.js) enforces authentication, with stricter requirements for desktop clients and premium endpoints defined in [`gateway.ts`](https://github.com/koala73/worldmonitor/blob/main/gateway.ts).
- **Rate limiting** in [`server/_shared/rate-limit.ts`](https://github.com/koala73/worldmonitor/blob/main/server/_shared/rate-limit.ts) prevents abuse through IP-based request quotas using Cloudflare-aware IP extraction via `getClientIp()`.
- **Runtime secret management** in [`src/services/runtime-config.ts`](https://github.com/koala73/worldmonitor/blob/main/src/services/runtime-config.ts) ensures internal clients use the same validation gates as external consumers through `validateSecret()` and `pushSecretToSidecar()`.
- **Gateway orchestration** in [`server/gateway.ts`](https://github.com/koala73/worldmonitor/blob/main/server/gateway.ts) sequences these checks to create a defense-in-depth perimeter around all endpoints.

## Frequently Asked Questions

### What happens if a request comes from an unauthorized origin?

If the origin does not match the `ALLOWED_ORIGIN_PATTERNS` defined in [`server/cors.ts`](https://github.com/koala73/worldmonitor/blob/main/server/cors.ts), the `isAllowedOrigin()` function returns false and the gateway immediately responds with HTTP 403. This prevents the request from receiving CORS headers or accessing any downstream logic.

### Do all API endpoints require an API key?

No. Trusted browser origins can access public endpoints without a key, but desktop application origins always require one. Additionally, endpoints listed in `PREMIUM_RPC_PATHS` within [`gateway.ts`](https://github.com/koala73/worldmonitor/blob/main/gateway.ts) force key validation regardless of origin type, ensuring sensitive operations remain restricted.

### How does World Monitor prevent IP spoofing in rate limiting?

The system extracts client IP addresses using `getClientIp()` in [`server/_shared/rate-limit.ts`](https://github.com/koala73/worldmonitor/blob/main/server/_shared/rate-limit.ts), which prioritizes the `cf-connecting-ip` header set by Cloudflare and falls back to `x-real-ip`. This method explicitly ignores the client-controlled `x-forwarded-for` header to prevent spoofing attempts.

### Where are valid API keys stored and validated?

Valid keys are defined in the `WORLDMONITOR_VALID_KEYS` environment variable and validated by the `validateApiKey()` function in [`api/_api-key.js`](https://github.com/koala73/worldmonitor/blob/main/api/_api-key.js). The desktop client stores its key securely using `validateSecret()` and `pushSecretToSidecar()` in [`src/services/runtime-config.ts`](https://github.com/koala73/worldmonitor/blob/main/src/services/runtime-config.ts), injecting it into outbound requests as the `X-WorldMonitor-Key` header.