Enforce Boundaries
Boundary Decisions
Section titled “Boundary Decisions”| Boundary | Accepted caller | Must remain outside |
|---|---|---|
| Runtime CLI | Local operator managing lifecycle or launching a workload | Product-management state and admin credentials |
| Web console/BFF | Authenticated, admitted operator with zone access | Anonymous callers and direct browser possession of root service tokens |
| Admin API | Trusted Admin SDK or console backend | Workload code |
| Control API | Enabled gate plus short-lived, scoped, zone-bound Control token | Replayed tokens, root admin token distribution, lifecycle commands |
| STS | Valid application/workload/Gateway proof and well-formed exchange | End-user password authentication and unsupported token fields |
| Gateway | Mandate, X-Caracal-Resource, binding, safe path and upstream | Caller-selected upstreams and caller-provided upstream credentials |
| Coordinator | SDK authority or operator credential appropriate to the route | Direct table mutation and unsigned lifecycle publication |
| Audit | Signed events and authenticated operator search | Mutable evidence and untrusted stream payloads |
Protected Request Boundary
Section titled “Protected Request Boundary”Gateway denies before upstream dispatch when it cannot establish a valid, unexpired, unreplayed, unrevoked mandate; a resource header and binding; an allowed operation and scope; a safe path and host; and a successful STS exchange. It strips caller authorization before applying the configured upstream credential.
Gateway is an HTTP proxy. It streams HTTP responses, including SSE, while rechecking revocation. It strips hop-by-hop upgrade headers and does not proxy WebSockets. Protect WebSockets in process with the verification engine or an adapter.
Management Boundary
Section titled “Management Boundary”The console is the human management surface. Admin SDK and Control API are automation surfaces. The runtime CLI remains local lifecycle and workload launch only. A Control gate or API outage must not prevent caracal status, down, or up from operating locally.
The system-zone viewer adds a console-side read-only boundary: mutation controls are disabled and non-read requests are blocked. It is a transparency surface, not an alternative management route.
Fail-Closed Expectations
Section titled “Fail-Closed Expectations”- Gateway and STS deny when authority, revocation, policy, or service proof cannot be established.
- Published modes do not permit
JTI_FAIL_OPENand require integrity keys. - Postgres row-level security denies cross-zone access without valid context.
- Control denies when disabled, unauthenticated, replayed, rate-limited, out of scope, or unable to record required audit evidence.
- Audit rejects integrity failures rather than treating them as trustworthy evidence.
For deployment controls, use Harden Production. For exact Gateway behavior, use Proxy Through Gateway.
Next Step
Section titled “Next Step”The architecture journey ends here. Use Understand Services for each service’s configuration, readiness, and failure posture.