ADR 0005: API Security Defaults

Ratification

Adopted before ADR 0018. There was no separate ratification process. Git history for this file on main is the record.

• Discussion Issue: not recorded (before ADR 0018)
• Merge PR: see git history for this file
• Accepted: as merged to main

Context

Why this matters: Security is not one switch — it is a set of defaults: who may call the API, how much traffic they can send, which browser origins we trust, and how large bodies may be. If those defaults differ between a laptop and staging/production, teams often find gaps only after abuse or incidents.

Set a baseline early (even with mock auth) so integrators learn real headers and keys. Moving later to real identity is then mostly configuration, not a full redesign.

Decision

Protected routes under /api/v1/* share one security baseline:

1. Per-client rate limiting is enabled by default.
2. CORS is allowlist-based and configured from environment.
3. Security headers are attached to every response.
4. Request body size is capped via configurable global limit.
5. Basic auth strategy is required in all environments; current default is mock API-key auth.

Configuration

• API_RATE_LIMIT_REQUESTS, API_RATE_LIMIT_WINDOW_SECONDS
• API_BODY_MAX_BYTES
• CORS_ALLOW_ORIGINS, CORS_ALLOW_METHODS, CORS_ALLOW_HEADERS, CORS_ALLOW_CREDENTIALS
• API_AUTH_STRATEGY, API_MOCK_API_KEY, API_AUTH_HEADER, API_PROTECTED_PREFIX

Contract impact

• Unauthorized requests return 401 with stable security error payload.
• Body overflow returns 413.
• Rate-limit overflow returns 429 and Retry-After header.
• Protected endpoint docs must include these responses in OpenAPI.

Consequences

Positive

• Security constraints are explicit and testable from day one.
• Client teams know non-functional contract limits early.
• Future migration to production auth can replace mock strategy without policy rewrite.

Trade-offs

• Additional configuration and local setup overhead.
• In-memory rate-limit is process-local and not distributed (acceptable for current stage).

Implementation Notes

• Security middleware is part of application startup defaults.
• Analyst-facing constraints are documented in docs/internal/system-design.html.
• Developer checklist is documented in docs/internal/developers.html.

Page history