The engineering guide

Ten chapters on how Meridian was actually built — the design decisions, the sharp edges, and the bugs. Written for engineers: every chapter cites the real ADRs and shows real code from the repo.

1. Why build an identity platform
   The scope, the decomposition into interlocking projects, and what makes each one architecturally distinct.
2. Keys before tokens
   keysmith — four-state rotation with construction-time invariants, envelope encryption, and why the JOSE layer is hand-built.
3. The authorization server
   idp — the RFC map, refresh-family reuse detection, single-statement atomicity, and the html/template escaping bug.
4. Sessions at scale
   sessiond — why browser sessions are opaque tokens, Lua-script atomicity, and pub/sub invalidation with a provable staleness bound.
5. Adaptive defense
   sentinel — sliding-window limits, lockout that can't be weaponized, a deterministic risk pipeline, and a hash-chained audit log verified from two languages.
6. Federating identity
   bridge — the sharp edges of RP-side OIDC, why you never match accounts by email, and circuit breakers for IdPs you don't operate.
7. The human side
   portal — enumeration-safe recovery flows, TOTP from the RFC up, and Postgres as a job queue.
8. Authorization you can explain
   console — RBAC with decision traces as the contract, deny-overrides precedence, and an API dog-fooded through its own engine.
9. Running it
   The deployed stack — ECS Fargate, RDS, ElastiCache, CloudWatch on a real AWS account — CI security gates, and what is honestly still pending.
10. Lessons learned
    An honest synthesis — the bugs that taught something, what building this way was like, and what would be different next time.