zentinel: Instructions file for Codex

Zentinel

Security-first reverse proxy built to guard the free web.

Zentinel is an open-source, high-performance reverse proxy built on Cloudflare's Pingora framework. It emphasizes predictability, transparency, and operational simplicity—infrastructure that lets operators sleep.

Philosophy (North Star)

Every contribution must align with the Manifesto:

1. Infrastructure should be calm — No surprises. Clear limits, predictable timeouts, explainable failure modes.
2. Security must be explicit — No magic, no implied policy. Every decision visible and traceable.
3. The edge is a boundary, not a battleground — Step in only when necessary, proportionally.
4. Complexity must be isolated — Core dataplane stays small. Complex logic lives in external agents.
5. The web is a commons — No vendor lock-in, no hidden control planes. Code is readable, forkable, modifiable.
6. Production correctness beats feature breadth — Boring reliability over shiny features.

Before adding anything, ask:

• Does this introduce ambiguity?
• Can this fail loudly and safely?
• Will this make someone's on-call worse?

---

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                         Zentinel Proxy                               │
│  ┌─────────────────────────────────────────────────────────────────┐│
│  │                    Pingora Foundation                            ││
│  │  (async I/O, connection pooling, TLS, HTTP/1.1 & HTTP/2)        ││
│  └─────────────────────────────────────────────────────────────────┘│
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────┐│
│  │ Routing  │ │  Rate    │ │  Cache   │ │ Filters  │ │   Agent    ││
│  │  Engine  │ │ Limiting │ │  Layer   │ │  Chain   │ │  Manager   ││
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └─────┬──────┘│
└────────────────────────────────────────────────────────────┼────────┘
                                                             │
                    ┌────────────────────────────────────────┼────────┐
                    │              External Agents            │        │
                    │  ┌─────────┐ ┌─────────┐ ┌─────────┐  │        │
                    │  │   WAF   │ │  Auth   │ │  Rate   │  │◄───────┘
                    │  │  Agent  │ │  Agent  │ │  Limit  │  │
                    │  └─────────┘ └─────────┘ └─────────┘  │
                    └───────────────────────────────────────────────────┘