# ows-royalties API Hardening

**TL;DR:** A production-grade API hardening kit (rate limiting, compression, security headers, body limits, readiness, a custom circuit breaker with per-resource outbound guards, and observability) for the Accounting Flask services — piloted in `ows-royalties`, then templated to the five `ows-abacus-*` services. Delivered as a self-contained `core/hardening/` package behind env toggles so it can merge dark and enable per environment.

**Value:** Brings comprehensive, production-grade API hardening to the Abacus Flask services, in Flask/uWSGI idioms. Protects against abusive load (per-principal rate limits), cascading downstream failures (circuit breakers + per-resource timeouts), and common API risks (missing security headers, unbounded bodies), while staying observable and operable. Built to be an exemplary, reusable pattern for other Orchard teams.

## I want to…

**Understand the project**
- Read the technical design → [TRD.md](TRD.md)
- See the key engineering decisions and their rationale → [DECISION_LOG.md](DECISION_LOG.md)
- See how the rate limits were calibrated + how they compare to the API landscape → [RATE_LIMITS.md](RATE_LIMITS.md)

**Plan / execute the work**
- Track delivery → Epic [ACC-10607](https://theorchard.atlassian.net/browse/ACC-10607) and its child tickets (below)
- Adopter guide + breaker runbook → ships in-repo as `core/hardening/README.md` (created during implementation)

## Jira

| Ticket | Scope |
|---|---|
| [ACC-10607](https://theorchard.atlassian.net/browse/ACC-10607) | **Epic** — API Hardening · ows-royalties pilot |
| [ACC-10608](https://theorchard.atlassian.net/browse/ACC-10608) | 01 Foundations (deps, config toggles, test isolation) |
| [ACC-10609](https://theorchard.atlassian.net/browse/ACC-10609) | 02 Typed policy + custom circuit breaker |
| [ACC-10610](https://theorchard.atlassian.net/browse/ACC-10610) | 03 Outbound resilience (adapters, `call_downstream`, wiring) |
| [ACC-10611](https://theorchard.atlassian.net/browse/ACC-10611) | 04 Inbound HTTP hardening (errors, key, limits, compression, headers, body) |
| [ACC-10612](https://theorchard.atlassian.net/browse/ACC-10612) | 05 Observability + readiness |
| [ACC-10613](https://theorchard.atlassian.net/browse/ACC-10613) | 06 Orchestration, app wiring, uWSGI, README/runbook |
| [ACC-10614](https://theorchard.atlassian.net/browse/ACC-10614) | 07 (Ops) Edge header-trust + ProxyFix hop count — **blocks prod enablement** |

**Dependency order:** 01 → 02 → {03, 04} → 05 → 06; 07 runs in parallel and gates prod rate-limit enablement.

## Key Repositories

| Repo | Role |
|---|---|
| [theorchard/ows-royalties](https://github.com/theorchard/ows-royalties) | Pilot service |
| `ows-abacus-account` / `-event` / `-legacy-sync` / `-state` / `-worksheet` | Rollout targets (same scaffold) |