Skip to main content

Core Concepts

Mandaitor's architecture is built around a few key concepts. Understanding them is essential to effectively using the platform.

Mandate​

A Mandate is the central object in Mandaitor. It is a digital, verifiable record of delegated authority. Think of it as a power of attorney for an AI agent. Each mandate contains:

  • Principal: The entity granting authority (e.g., a human user, a company).
  • Delegate: The entity receiving authority (e.g., an AI agent, a service).
  • Scope: What the delegate is allowed to do.
  • Constraints: The rules and boundaries that limit the delegation.
  • Proof: A cryptographic signature that makes the mandate tamper-proof.

Mandates have a lifecycle, starting as ACTIVE and potentially moving to SUSPENDED, REVOKED, or EXPIRED.

Principal and Delegate​

The Principal is the owner of the authority. The Delegate is the actor who receives it. Both are represented by a Subject object, which includes a unique subject_id and a type (e.g., HUMAN, AI_AGENT, SERVICE).

Example Subject
{
  "type": "AI_AGENT",
  "subject_id": "monco:agent:validate-agent-v2",
  "display_name": "Monco Validation Agent"
}

Scope​

The Scope defines the specific permissions being granted. It consists of:

  • actions: A list of operations the delegate can perform (e.g., construction.validation.approve).
  • resources: A list of resource URIs the actions apply to (e.g., monco:project:proj_123/*).
  • effect: Either ALLOW or DENY.

This model provides fine-grained access control, ensuring the delegate can only perform authorized actions on specific resources.

Constraints​

Constraints add an extra layer of security by defining the conditions under which a mandate is valid. Common constraints include:

  • Time: When a mandate starts and expires.
  • Rate Limits: How many times an action can be performed in a given time window.
  • Financial Limits: Maximum monetary value for transactions.
  • Escalation Rules: When to notify a human or require manual approval.

Taxonomies​

A Taxonomy is a structured vocabulary for a specific industry. It defines the set of possible actions and resources that can be used in a mandate's scope. For example, the @mandaitor/taxonomy-construction package defines actions like construction.validation.approve and resource patterns for construction projects.

This ensures that all parties speak the same language and that mandates are based on a shared, standardized understanding of the domain.

Audit Trail​

Every significant event in the Mandaitor system—from mandate creation to verification—is recorded as an AuditEvent. These events are cryptographically linked together using a hash chain, creating an immutable and verifiable audit trail. Each event is signed by a Key Management Service (KMS), providing the highest level of integrity and non-repudiation.

This ensures that a complete and trustworthy history of all delegations and verifications is always available.