# Changelog — `api`

All notable changes to the **api** container are documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and the container adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

The `api` and `ui` containers are versioned independently. The HTTP wire
contract (endpoints, token kinds, RBAC roles, response envelope) is the
boundary between them — bumping the **major** here implies a breaking
change to that contract that consumers must adapt to.

Tags use the `api-v<MAJOR>.<MINOR>.<PATCH>` form so they don't collide
with the UI's tags in this monorepo.

## [1.0.0] — 2026-05-01

First stable release. Implements every milestone of `SPEC.md` from the
api side (M1–M7, M11–M14) plus shared concerns from M12.

### Added
- Slim 4 + FrankenPHP JSON backend on `:8081` with healthcheck.
- Doctrine DBAL data layer supporting **SQLite** (default) and **MySQL 8 / MariaDB 10.6+**, selected via `DB_DRIVER`. WAL + tuned PRAGMAs on SQLite, transactional writes throughout.
- Phinx migrations and idempotent seeders for every table in `SPEC.md` §4: `reporters`, `consumers`, `api_tokens`, `categories`, `reports`, `ip_scores`, `job_locks`, `job_runs`, `ip_enrichment`, `manual_blocks`, `allowlist`, `policies`, `policy_category_thresholds`, `users`, `oidc_role_mappings`, `audit_log`.
- Four-kind token model (`reporter`, `consumer`, `admin`, `service`) with SHA-256 hashing, `irdb_<kind>_<32 base32>` formatting, and a `RbacMiddleware` driving role enforcement on every admin endpoint.
- `X-Acting-User-Id` impersonation header — only honoured in combination with a `service` token; ignored on every other kind.
- **Public API**: `POST /api/v1/report` (token-bucket rate limiter, 60 req/s/token by default); `GET /api/v1/blocklist` (text + JSON, ETag, 30 s per-consumer cache).
- **Admin API**: full CRUD for reporters, consumers, tokens, categories, policies; manual blocks and allowlist (Operator+ for writes); IP search + IP detail with timeline; dashboard stats; effective-config and jobs-status endpoints; audit-log search; manual job triggers; demo-data seed and operational `purge`.
- **Auth API**: `upsert-oidc`, `upsert-local`, `users/{id}` — service-token-only, used by the UI BFF to translate browser identities into stable user records and roles.
- **Internal jobs**: `recompute-scores`, `cleanup-audit`, `cleanup-expired-manual-blocks`, `enrich-pending`, `refresh-geoip`, `tick`, `status`. Loopback / RFC1918 only via `InternalNetworkMiddleware`; bearer-gated by `INTERNAL_JOB_TOKEN`. Single-shot lock acquisition via `job_locks` with crash-tolerant expiry and `job_runs` history per execution.
- **Reputation engine**: linear and exponential decay, weighted by per-reporter trust at report time. 365-day hard cutoff. Manual blocks and allowlist evaluated at distribution time, not folded into scores; allowlist always wins.
- **Enrichment**: MaxMind GeoLite2-Country/ASN and IPinfo adapters, downloaded at build or refreshed via job; missing-DB scenarios degrade cleanly.
- **Audit log**: every write through admin/auth endpoints emits an entry attributed to the acting user (not the service token), with field-level before/after diffs on updates and human-readable entity labels frozen at write time.
- **Hardening**: security headers (CSP, HSTS, X-Frame-Options, Referrer-Policy), token entropy verified, secrets scrubbed from logs.
- **Documentation**: OpenAPI 3.0.3 served at `/api/v1/openapi.yaml` with viewer at `/api/docs`; canonical reference for request/response schemas.
- CLI `bin/console`: `db:migrate`, `db:rollback`, `db:seed`, `auth:bootstrap-service-token`, `auth:create-token`, `jobs:run`, `jobs:status`, `scores:rebuild`.

[1.0.0]: https://github.com/your-org/irdb/releases/tag/api-v1.0.0