Enforce Boundaries
Caracal’s trust model depends on clear boundaries. Do not blur runtime lifecycle, product management, token issuance, protected-resource routing, and audit evidence.
Boundary Map
Section titled “Boundary Map”| Boundary | Trusted side | Untrusted or constrained side |
|---|---|---|
| Runtime CLI | Local lifecycle and caracal run config | Product-management state and admin actions. |
| Console/Admin API | Authenticated operators and Control/Admin clients | Anonymous clients and expired/insufficient tokens. |
| STS | Valid application credentials, policy/grant/session state | Malformed subject tokens, invalid client secrets, unsatisfied step-up. |
| Gateway | Verified inbound mandate, configured binding, revocation-fresh state | Arbitrary upstream URLs, path traversal, replayed/expiring tokens. |
| Audit | HMAC-verified stream events and append-only database role | Tampered stream payloads or mutable evidence. |
| Redis | Signed operational messages | Unsigned or mismatched stream messages in published modes. |
| Postgres | Service roles and fail-closed RLS | Cross-zone reads without zone context. |
| Control | Enabled gate, verified JWT, replay-safe JTI, rate limit | Disabled gate, replayed tokens, unsupported commands. |
Gateway Fail-Closed Checks
Section titled “Gateway Fail-Closed Checks”Gateway denies before upstream dispatch when:
- bearer token is missing, malformed, too large, expiring, revoked, replayed, or signature-invalid;
X-Caracal-Resourceis missing;- no binding exists for the token zone and resource;
- path traversal is detected;
- STS exchange fails or the STS circuit is open;
- upstream host safety rules reject the destination.
Control Boundary
Section titled “Control Boundary”Control is optional. It requires a gate file, JWKS-backed JWT verification, replay protection, rate limits, and an API token for dispatch. It must not be exposed as a top-level runtime CLI command.