Aroha Protocol

Cryptographically bounded authority for every agent in the chain.

Aroha Mandates let any agent that delegates keep cryptographically enforceable control over every agent it hands work to. No agent can exceed the scope it was granted.

Docs · Support matrix · Local sandbox · Support · Spec

---

Mandate-first agent authority

import { generateKeyPair, generateDid } from "@aroha-sdk/core";
import { issueIntentMandate, attenuateToPayment, verifyMandateChain } from "@aroha-sdk/credentials";

const human = await generateKeyPair();
const assistant = await generateKeyPair();
const flightAgent = await generateKeyPair();
// Content-addressed DIDs (did:aroha:z…) commit to their own public key,
// so a verifier needs no registry lookup to check signatures.
const humanDID = generateDid(human.publicKey);
const assistantDID = generateDid(assistant.publicKey);
const flightAgentDID = generateDid(flightAgent.publicKey);

// Human issues an intent mandate to the assistant ($500, 1 hour TTL)
const intent = await issueIntentMandate(
  humanDID, assistantDID,
  { spendLimitUsd: 500, merchantCategory: "4511" }, // MCC 4511 = airlines
  human.privateKey,
  3_600_000,
);

// The assistant attenuates scope downward to the flight agent ($300 of the $500).
// The child token embeds the signed chain back to the human.
const payment = await attenuateToPayment(
  intent, flightAgentDID,
  { spendLimitUsd: 300, merchantCategory: "4511" },
  assistant.privateKey,
);

// Flight agent verifies every link back to the human root before acting
const result = await verifyMandateChain(payment.token, undefined, {
  expectedRoot: humanDID,          // the human authority must come from
  expectedGrantee: flightAgentDID, // the flight agent itself
});
// result.valid === true, result.chainVerified === true,
// result.mandate?.constraints.spendLimitUsd === 300.
// A link that widens scope, or is signed by anyone but its grantor, fails.

The example names each party with a did:aroha:z… identifier, which commits to its own key and verifies offline. On main (unreleased) a party can also be named by an HTTPS address that publishes its key, such as https://agents.example.com/assistant, for agents that already have one: see Web identities and the runnable examples/web-identities. A mandate can also be issued as a JWT that a stock JWT library reads: Mandates as JWTs.

---

The problem

Agents now act for people and hand work to other agents and tools, often run by other companies. MCP and A2A connect them; identity providers name them. Nothing that travels with the work proves what each agent was allowed to do, stops the whole chain when the person changes their mind, or leaves a record anyone else can check.

Approach	What you get today
Per-hop credentials (API keys, OAuth tokens)	Each hop enforces its own key. The person's limit, purpose and expiry are lost along the way.
Framework guardrails	Checks inside one codebase. Nothing survives the hop to another vendor's agent.
Aroha Mandates	A signed chain back to the person. Scope can only narrow. Any verifier checks it offline; revocation is pushed; every action, allowed or refused, gets a signed receipt.

Aroha answers four questions for every action: who is acting, what were they allowed to do, can it be stopped, and what actually happened. It works with MCP, A2A and your identity provider rather than replacing them. See what Aroha is (and is not).

---

How it works

1. Human issues a mandate — signs an IntentMandate with authorized actions, a spending cap, and a TTL. Cryptographically bound to the receiving agent's DID.
2. Any agent attenuates — delegates a strict subset of that scope to the next agent, signed by the delegating agent. Scope narrows, never widens.
3. Every agent verifies — before acting, an agent verifies the mandate chain back to its human origin, offline. A forged, altered, widened or expired link fails verification.
4. Revoke and prove — the person can revoke at any time; the registry witness pushes the revocation to verifiers. Every allowed or refused action produces a signed receipt.
5. Deploy in your existing stack — bridges for MCP, LangChain, A2A, and Composio. Mandate verification drops in in two lines.

---

Try it in sixty seconds

An inbox assistant that may read mail and propose what to archive, and may never delete, no matter what it is told. No server, no keys to configure, runs offline against the published packages.

git clone https://github.com/ArohaLabs/aroha-protocol
cd aroha-protocol/examples/mandates && npm install
node inbox.mjs

The mail tool checks the signed mandate on every call, so the assistant does not need to be trustworthy and does not need to remember the instruction. examples/mandates walks through both scripts, including the $500 flight example above.

---

Package architecture

Core — the four questions
├── @aroha-sdk/core           Identity (did:aroha), signed envelopes, receipts, conversation profile
├── @aroha-sdk/credentials  ★ Start here — mandates, attenuation, chain verification, revocation
├── @aroha-sdk/delegation     Multi-hop delegation with depth limits and stitched receipts
└── @aroha-sdk/policy         Deterministic limits checked before any model sees a request

Adapters (use Aroha from the stack you already run)
├── @aroha-sdk/mcp-server     Remote MCP server (2026 authorization spec)
├── @aroha-sdk/mcp-guard      Mandate checks in front of any MCP server
├── @aroha-sdk/mcp-bridge     MCP ↔ Aroha  (includes wrapMcp() one-liner)
├── @aroha-sdk/a2a-bridge     A2A ↔ Aroha
└── @aroha-sdk/langchain-bridge  LangChain / OpenAI functions ↔ Aroha

Extensions (maintained, optional; developed outside this repository)
└── orchestrator (sagas) · settlement · commerce · reputation

Tooling
├── @aroha-sdk/cli            scaffold · convert · doctor · dev sandbox
└── create-aroha-agent        npx create-aroha-agent — zero-config scaffolder

---

Already building agents? Add mandate verification in 2 lines.

import { verifyMandateChain } from "@aroha-sdk/credentials";

// In your agent's request handler. HUMAN_ROOT_DID is the human you accept authority from;
// MY_DID is this agent's own DID. The mandate travels in the signed Aroha envelope body
// (`credentialToken`); over MCP it travels in `_meta["aroha/mandate"]` with a holder proof
// (see @aroha-sdk/mcp-bridge). There is no mandate HTTP header.
const { valid, chainVerified, mandate, reason } = await verifyMandateChain(
  envelope.body.credentialToken,
  undefined, // default resolver: content-addressed did:aroha:z… DIDs
  { expectedRoot: process.env.HUMAN_ROOT_DID, expectedGrantee: MY_DID },
);
if (!valid || !chainVerified) {
  res.status(403).json({ error: reason });
} else {
  // mandate.constraints.spendLimitUsd, mandate.constraints.merchantCategory, etc.
}

Already have an MCP server? Add one import:

import { wrapMcp, registryPublicKeyResolver } from "@aroha-sdk/mcp-bridge";

const agent = await wrapMcp(server.listTools(), {
  name: "my-tools",
  price: 0.01,
  resolvePublicKey: registryPublicKeyResolver(), // verifies who is calling
  handlers: { search: async (args) => ({ content: [{ type: "text", text: await search(args) }] }) },
});
await agent.start();
// ✓ did:aroha:my-tools  →  http://localhost:3001

Using LangChain? Call any mandate-aware Aroha agent as a native tool:

import { createArohaLangChainTool } from "@aroha-sdk/langchain-bridge";

const tool = await createArohaLangChainTool(
  "http://localhost:3001",
  "search-flights",
  "Search available flights by origin, destination, and date"
);
// plug `tool` straight into AgentExecutor, createOpenAIFunctionsAgent, etc.

Using an AI coding agent? Point it at the aroha-integrate Agent Skill (or docs/llms.txt): it picks the smallest integration path for your code, applies it, and checks that out-of-scope calls are refused.

Scaffold a new agent pre-wired for mandate verification:

npx create-aroha-agent my-agent
cd my-agent && npm install && npm run dev
# → [my-agent] did:aroha:my-agent  http://localhost:3001/aroha/v1  Ready ✓

---

CLI reference

aroha init my-agent              # interactive scaffold
aroha init my-agent --yes        # zero-config: picks all defaults, writes .env
aroha convert --from mcp --dir . # wrap existing agent
aroha doctor [endpoint]          # check environment + connectivity
aroha dev                        # local dev registry + dashboard

---

Deploy

One-click templates for fast deployment.

Note: the Vercel and Cloudflare buttons clone from github.com/ArohaLabs/aroha-protocol. You can also copy the template directory from a checkout and deploy it with the platform CLI.

Platform	Button
Vercel
Cloudflare
Railway	No published template yet; manual setup in examples/railway
Render	No one-click button (Render needs render.yaml at a repo root); Blueprint steps in examples/render

---

What's in this repo

packages/               SDK packages (@aroha-sdk/*)
agents/mock-provider-agent/ Reference provider agent for interoperability tests
examples/               Deployment templates (Vercel, Cloudflare, Railway, Render)
examples/mandates/      Two runnable scripts: an inbox assistant that cannot delete, and the $500 flight
examples/sandbox-agents/ Pre-built sandbox agents (flight, hotel, weather, web-search, summarizer)
contracts/              Solidity contracts (ArohaRegistry, ArohaEscrow, ArohaReputation)
docs/                   MkDocs documentation site

The Aroha runtime (desktop app) is developed in a separate, private repository and has not been released. The saga, settlement, commerce and reputation extensions are also developed outside this repository; they stay published on npm.

---

Prerequisites

Requirement	Version
Node.js	≥ 22
npm	≥ 10

Foundry and Python are only needed for the smart contract demo and MkDocs docs site respectively.

---

Contributing

Use GitHub Issues for bugs and feature requests and GitHub Discussions for questions and ideas, or email the maintainer listed in MAINTAINERS.md. See CONTRIBUTING.md (commits need a DCO sign-off) and SUPPORT.md. For security issues, see SECURITY.md.

npm install && npm run build && npm test

---

License

Apache-2.0 — see LICENSE and NOTICE.