Skip to main content

Core Authority System

This page explains the core enforcement model implemented under caracal/core.

Audience: Developer

Context: Use this page when changing or debugging authority issuance, delegation, validation, or the surrounding data model.

Core Explanation​

Principal registry​

caracal/core/identity.py exposes PrincipalRegistry, which maps PostgreSQL Principal rows to runtime-facing identity objects. It can register principals, fetch them, list them, and ensure key material exists when delegation tokens are generated.

Authority policies​

Policies are persisted as AuthorityPolicy rows and constrain issuance:

  • max_validity_seconds
  • allowed_resource_patterns
  • allowed_actions
  • allow_delegation
  • max_network_distance

The policy is the upper bound. It is not the execution grant itself.

Mandate issuance​

MandateManager.issue_mandate():

  1. optionally checks issuance rate limits
  2. loads the issuer's active policy
  3. validates requested validity and scope against that policy
  4. resolves delegation network distance
  5. signs canonical mandate data
  6. stores the resulting ExecutionMandate
  7. records an authority-ledger issuance event

Delegation​

Delegation is modeled in two related but distinct ways:

  • delegation tokens in caracal/core/delegation.py
  • delegation graph edges in caracal/core/delegation_graph.py

The graph is what validates authority topology between mandates. It enforces explicit direction rules such as:

  • user to agent: allowed
  • user to service: allowed
  • agent to service: allowed
  • agent to user: blocked
  • service-originated delegation: blocked

Validation​

AuthorityEvaluator.validate_mandate() is the fail-closed execution gate. It checks:

  • mandate presence
  • revocation state
  • validity window
  • issuer existence and public key
  • mandate signature
  • action scope
  • resource scope
  • delegation path validity

Every denial reason is explicit and can be recorded.

Authority ledger​

AuthorityLedgerWriter and AuthorityLedgerQuery persist issuance, validation, denial, and revocation events. This is separate from the metering ledger used for usage events.

Intent Binding​

caracal/core/intent.py provides a structured intent object and a stable hash over action, resource, and parameters. When a mandate is bound to an intent, the intent hash narrows what the mandate should authorize semantically.

Cryptography​

caracal/core/crypto.py signs mandates and Merkle roots with ECDSA P-256 using canonicalized JSON payloads or direct root hashes.

The mandate signature path matters because validation reconstructs and verifies the signed fields rather than trusting the database row implicitly.

Internal Behavior​

The authority layer is tightly coupled to the database schema:

  • principals, mandates, policies, and delegation edges are SQLAlchemy-backed
  • validation may use Redis-backed mandate caching when configured
  • authority events can be linked to Merkle integrity workflows through database relationships

It is also intentionally opinionated:

  • uncertainty becomes denial
  • delegated scope must be a subset of the source scope
  • delegated validity cannot outlive the source mandate
  • revocation can cascade through the delegation graph

Edge Cases And Constraints​

  • Policy creation can auto-provision a principal row in some CLI paths when a UUID is supplied but no principal exists yet.
  • Mandate validation uses pattern matching for resource and action scopes, so scope grammar consistency matters.
  • Delegation tokens and delegation edges are related but not interchangeable concepts.
AI tools
On this page