Identity Package

The identity packages verify Caracal mandate JWTs. Use them when you are building a connector, transport, or custom resource-server boundary that accepts mandates directly.

Install

Ecosystem	Package
TypeScript	npm install @caracalai/identity
Python	pip install caracalai-identity
Go	go get github.com/garudex-labs/caracal/packages/identity/go

Node packages target Node >=22; Python packages require Python >=3.12.

Verification inputs

Option	Meaning
issuer / Issuer	Expected STS issuer.
audience / Audience	Expected audience for the mandate.
zoneId / expected_zone_id / ZoneID	Zone claim check. When omitted, the verifier reads the unverified zone_id claim to select the zone keyset, then proves it through signature verification.
requiredScopes / required_scopes / RequiredScopes	Scopes every accepted mandate must contain.
requiredTargets / required_targets / RequiredTargets	Target resources every accepted mandate must include.
requiredUse / required_use / RequiredUse	Token use, usually resource.
requireAgent / require_agent / RequireAgent	Require agent-session claims.
requireDelegation / require_delegation / RequireDelegation	Require a delegation edge.
requireChainContains / require_chain_contains / RequireChainContains	Require an application in the delegation chain.
maxHopCount / max_hop_count / MaxHopCount	Cap delegation chain depth.

TypeScript example

import { verify } from "@caracalai/identity";

const claims = await verify(token, {
  issuer: "https://sts.example.com",
  audience: "https://api.example.com",
  zoneId: "zone_prod",
  requiredScopes: ["tickets:read"],
  requiredTargets: ["https://api.example.com/tickets"],
});

JWKS caching

STS signing keysets are zone-scoped: every fetch hits {issuer}/.well-known/jwks.json?zone_id={zone} and is cached per issuer and zone. TypeScript verifiers use an in-memory JWKS cache by default. Build a cache explicitly when a resource server wants shorter local-development TTLs, a custom fetch implementation, or warmup during service boot.

import { createJwksCache, verify } from "@caracalai/identity";

const jwksCache = createJwksCache({ ttlMs: 300_000, fetchTimeoutMs: 5_000 });
await jwksCache.warm("https://sts.example.com", "zone_prod");

const claims = await verify(token, {
  issuer: "https://sts.example.com",
  audience: "https://api.example.com",
  zoneId: "zone_prod",
  jwksCache,
});

Go and Python identity packages also cache issuer JWKS metadata in memory. Python exposes warm_jwks(issuer, zone_id) for service boot; Go callers can warm the cache with GetJWKSContext(ctx, issuer, zoneID).

Failure classes

Error	Meaning
TokenInvalidError	Signature, issuer, audience, expiry, use, or claim validation failed.
ZoneInvalidError	The token zone did not match the expected zone.
ScopeInsufficientError	A required scope is missing.
AgentIdentityRequiredError	The verifier requires an agent identity.
DelegationRequiredError	The verifier requires delegated authority.
ChainMismatchError	The delegation chain is missing a required application.
HopCountExceededError	The mandate exceeds the configured hop limit.

When to Use MCP Auth Transport

Use MCP Auth Transport when you also need revocation checks, reusable verifier defaults, bearer-header parsing, and safe debugging hints. Use the identity package directly when you are composing your own verifier or connector boundary.