Framework Adapters
Framework adapters bind the lower-level identity and verify packages to common server frameworks. Use them before reaching for lower-level verification APIs.
Adapters are inbound enforcement only. They do not start Sessions, mint mandates, proxy to Gateway, or manage product state.
Adapter Map
Section titled “Adapter Map”| Adapter | Package | Use it for |
|---|---|---|
| Express | @caracalai/express | Protecting Express 5 routes with Caracal mandate verification. |
| ASGI | caracalai-asgi | Protecting FastAPI, Starlette, and other Python ASGI apps with Caracal mandate verification. |
| FastMCP | @caracalai/fastmcp, caracalai-fastmcp | Verifying FastMCP bearer tokens before tool execution. |
| Go net/http | github.com/garudex-labs/caracal/packages/adapters/nethttp/go | Protecting Go HTTP handlers. |
No adapter fits, or you need a custom boundary? Route through Verification Layer Overview to choose between the verify engine, identity package, and revocation stores.
Boundary Semantics
Section titled “Boundary Semantics”Every HTTP adapter maps verification failures through one canonical status function in @caracalai/verify (httpStatusForAuthError in TypeScript, verify.HTTPStatus in Go), so the boundary behaves identically across frameworks and languages:
- 401 - the credential itself was not accepted:
missing_token,invalid_token,invalid_zone,session_revoked,delegation_stale. - 403 - the mandate verified but its authority is insufficient for the route:
insufficient_scope,session_required,delegation_required,chain_mismatch,hop_count_exceeded.
Adapters never re-derive these status codes; they consume the shared mapping.
All adapters require trusted issuer, audience, zone, and route-authority requirements. In-memory revocation is suitable only for tests or one process; replicated deployments need a shared backend.