# Security Notes

## Supported security posture

This service is designed for internet exposure, but requires correct deployment configuration.

## Key controls

- SSRF protections in browser and outbound fetch paths
- Auth tiers: free/IP limited, API key, x402 pay-per-call
- Stripe webhook signature verification
- x402 replay protection with persistent tx-hash cache
- x402 transaction freshness checks (`X402_MAX_TX_AGE_SECONDS`)
- Namespaced memory isolation by auth tier

## Production requirements

1. `NODE_ENV=production`
2. `ALLOW_APIKEY_QUERY=false`
3. Correct `TRUST_PROXY` value for your reverse-proxy topology
4. Set strict `SSE_ALLOWED_HOSTS` and `SSE_ALLOWED_ORIGINS`
5. For multi-instance deployments, set `REDIS_URL` for shared rate-limit state
6. Keep `X402_TEST_MODE=0` (test mode is ignored in production)
7. Use `STRIPE_WEBHOOK_IP_ALLOWLIST` when your ingress path has stable source IPs
8. Enforce webhook source filtering at the edge (WAF/reverse proxy), not only app layer
9. Persist:
   - `KEYS_FILE`
   - `MEMORY_DB_PATH`
   - `X402_TX_CACHE_FILE`

## Edge filtering guidance (webhooks)

Recommended: restrict `POST /billing/webhook` at your reverse proxy/WAF to known Stripe source ranges and HTTPS only.

Defense in depth order:
1. Edge source filtering (IP/rules)
2. `STRIPE_WEBHOOK_IP_ALLOWLIST` in app
3. Stripe signature verification (`STRIPE_WEBHOOK_SECRET`)

## Secret hygiene

- Never commit real secrets to git (`.env`, `.env.*`, API keys, private keys).
- Keep runtime secrets in deployment secret stores (not in repository files).
- Before release, run:

```bash
git grep -nE "(ghp_|gho_|sk_live_|AKIA|xox[baprs]-|BEGIN (RSA|EC|OPENSSH|PRIVATE) KEY)" HEAD
```

## Dependency hygiene

- Run `npm audit` in CI.
- This repo uses an override for `express-rate-limit` to avoid a known high-severity advisory in transitive deps.

## Reporting

If you find a vulnerability, open a private report to the maintainers before public disclosure.