@aroha-sdk/credentials

Issue, attenuate, and verify cryptographically signed IntentMandates — the bounded-authority primitive for Aroha agent chains.

Install

npm install @aroha-sdk/credentials

Quick example

import { issueIntentMandate, attenuateToPayment, attenuateToCart, verifyMandate } from "@aroha-sdk/credentials";

// Step 1: Human issues root mandate to orchestrator
const { mandate, token } = await issueIntentMandate(
  humanDID,          // grantor
  orchestratorDID,   // grantee
  { spendLimitUsd: 500, allowedActions: ["book-flights", "book-hotels"] },
  humanPrivateKey,
  3_600_000,         // TTL: 1 hour in ms
);

// Step 2: Orchestrator narrows scope and delegates to flight agent
const flightMandate = await attenuateToPayment(
  mandate,
  flightAgentDID,
  { spendLimitUsd: 300 },   // must be ≤ parent's 500
  orchestratorPrivateKey,
);

// Step 3: Flight agent verifies before acting
const { valid, mandate: decoded, reason } = await verifyMandate(
  flightMandate.token,
  humanPublicKey,
);
// valid === true
// decoded.constraints.spendLimitUsd === 300
// Forging a $400 mandate → valid === false (signature mismatch)

// Attenuate to a specific cart total
const cartMandate = await attenuateToCart(
  mandate,
  paymentAgentDID,
  { spendLimitUsd: 299, cartId: "cart_abc" },
  flightAgentPrivateKey,
);

Why this exists in the mandate chain

This is the core of Aroha's bounded-authority story. The attenuation principle means scope can only narrow as a mandate passes from orchestrator to sub-agent — it can never widen. Each delegation is Ed25519-signed, so forgery and scope escalation are cryptographically impossible without the delegator's private key.

API

• issueIntentMandate(grantorDID, granteeDID, constraints, privateKey, ttlMs) — create a root mandate signed by the human or top-level orchestrator. Returns { mandate, signature, token }.
• attenuateToPayment(parentMandate, granteeDID, constraints, delegatorPrivateKey) — issue a child mandate with narrower payment scope. Returns { mandate, signature, token }.
• attenuateToCart(parentMandate, granteeDID, constraints, delegatorPrivateKey) — attenuate to a specific cart/transaction. Returns { mandate, signature, token }.
• verifyMandate(token, issuerPublicKey) — verify the full mandate chain. Returns { valid, mandate?, reason? }.

License

MIT