@mandaitor/sdk

The official TypeScript SDK for the Mandaitor Delegation Mandate Registry API. This SDK provides a robust, type-safe interface for managing AI agent delegation mandates, verifying runtime actions, and retrieving cryptographic Proof-of-Mandate artifacts.

Overview

Mandaitor is the runtime trust layer for delegated AI actions. Instead of assuming that an AI agent is allowed to act because it has application access, you verify whether a specific delegator granted a specific delegate the right to perform a specific action on a specific resource, under explicit constraints.

This SDK simplifies the integration of Mandaitor into Node.js, edge, and browser environments. It handles authentication, request retries, error mapping, and provides full TypeScript definitions for all Mandaitor domain objects including mandates, audit events, and Verifiable Credentials.

Installation

Install the package via your preferred package manager. The SDK requires Node.js 18 or later.

npm install @mandaitor/sdk

Initialization

Initialize the MandaitorClient with your API key and tenant identifier. You can obtain these credentials from the Mandaitor dashboard after completing the onboarding process.

import { MandaitorClient } from "@mandaitor/sdk";

const client = new MandaitorClient({
  apiKey: process.env.MANDAITOR_API_KEY,
  tenantId: "tnt_your_tenant_id",
  timeout: 5000,
  retries: 2
});

Core Workflows

Creating a Mandate

Delegation begins by creating a mandate. A mandate explicitly defines the boundaries of authority granted to an AI agent by a human principal. It specifies the allowed actions, target resources, and any constraints such as expiration times or financial limits.

const mandate = await client.createMandate({
  principal: {
    type: "NATURAL_PERSON",
    subject_id: "user:[email protected]",
  },
  delegate: {
    type: "AGENT",
    subject_id: "agent:validation-v3",
  },
  scope: {
    actions: ["construction.validation.approve", "construction.validation.flag"],
    resources: ["project:proj_12345/*"],
    effect: "ALLOW",
  },
  constraints: {
    valid_until: new Date(Date.now() + 86400000).toISOString(),
    require_mfa_for_high_risk: true
  },
});

console.log(`Created mandate: ${mandate.mandate_id}`);

Verifying an Action

Before an agent executes an action, it must verify its authority against the Mandaitor registry. The verification engine evaluates the requested action against all active mandates bound to the agent.

const result = await client.verify({
  delegate_subject_id: "agent:validation-v3",
  action: "construction.validation.approve",
  resource: "project:proj_12345/zone:EG/installation:stk_01",
});

if (result.decision === "ALLOW") {
  // Proceed with the action
  console.log("Action authorized");
} else {
  // Block the action and log the reason
  console.error(`Action denied: ${result.reason}`);
}

Obtaining a Proof-of-Mandate

For high-assurance workflows, you can request a cryptographically signed Proof-of-Mandate (PoM) Verifiable Credential alongside the verification decision. This artifact serves as immutable evidence that the action was authorized at a specific point in time.

const result = await client.verifyWithPoM(
  {
    delegate_subject_id: "agent:validation-v3",
    action: "construction.validation.approve",
    resource: "project:proj_12345/zone:EG",
  },
  { format: "sd-jwt-vc" }
);

console.log(`Proof artifact: ${result.pom_token}`);

API Reference

The MandaitorClient exposes methods covering the entire mandate lifecycle, audit trailing, and configuration management.

| Category | Method | Description | | :--- | :--- | :--- | | Lifecycle | createMandate(req) | Issues a new delegation mandate | | | getMandate(id) | Retrieves a mandate's current state and configuration | | | listMandates(params) | Queries mandates with filtering and pagination | | | revokeMandate(id) | Permanently invalidates a mandate | | | suspendMandate(id) | Temporarily pauses a mandate's authority | | | reactivateMandate(id) | Restores a suspended mandate to active status | | Verification | verify(req) | Evaluates whether an action is currently authorized | | | verifyWithPoM(req, opts) | Evaluates an action and returns a signed Verifiable Credential | | | verifyWithDrift(req) | Evaluates an action and includes semantic drift signals | | Audit | getMandateEvents(id) | Retrieves the immutable audit log for a specific mandate | | | listEvents(params) | Queries the tenant-wide audit log | | | getEvidencePack(id) | Exports a cryptographically verifiable court-ready evidence package | | Identity | initiateEudiSession() | Starts an eIDAS 2.0 wallet authentication session | | | exchangeToken(params) | Exchanges an IdP token for a Mandaitor session token |

Error Handling

The SDK throws typed error classes that map directly to the Mandaitor API error responses. This allows for precise error handling and automated recovery strategies.

| Error Class | HTTP Status | Typical Cause | | :--- | :--- | :--- | | MandaitorAuthError | 401 | The API key is missing, invalid, or expired | | MandaitorForbiddenError | 403 | The API key lacks the required scope for the operation | | MandaitorNotFoundError | 404 | The requested mandate, event, or resource does not exist | | MandaitorConflictError | 409 | Attempting an invalid state transition (e.g., revoking a revoked mandate) | | MandaitorRateLimitError | 429 | The tenant has exceeded its sustained or burst request limits | | MandaitorValidationError | 400 | The request payload violates schema constraints |

Development and Testing

The SDK is built with TypeScript and bundled using tsup. We use Vitest for both unit and integration testing.

# Build the SDK
pnpm build

# Run unit tests
pnpm test:unit

# Run integration tests against the sandbox environment
pnpm test:integration

License

Apache-2.0