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

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, 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. 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 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. 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. 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, 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):

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

Calling a premium endpoint that requires an API key:

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):

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):

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 blocks unauthorized cross-origin requests before they reach the API.
• API key validation via X-WorldMonitor-Key in api/_api-key.js enforces authentication, with stricter requirements for desktop clients and premium endpoints defined in gateway.ts.
• Rate limiting in 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 ensures internal clients use the same validation gates as external consumers through validateSecret() and pushSecretToSidecar().
• Gateway orchestration in 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, 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 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, 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. The desktop client stores its key securely using validateSecret() and pushSecretToSidecar() in src/services/runtime-config.ts, injecting it into outbound requests as the X-WorldMonitor-Key header.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}