Spending Mandates

npm install @aroha-sdk/credentials @noble/ed25519 @noble/hashes

import * as ed from "@noble/ed25519";
import { sha512 } from "@noble/hashes/sha512";

// Required for Node.js < 20 (noble needs a sync sha512 shim)
ed.etc.sha512Sync = (...m) => sha512(...m);

// One key pair per participant
const humanPrivKey   = ed.utils.randomPrivateKey();
const humanPubKey    = await ed.getPublicKeyAsync(humanPrivKey);

const agentPrivKey   = ed.utils.randomPrivateKey();
const agentPubKey    = await ed.getPublicKeyAsync(agentPrivKey);

const paymentPrivKey = ed.utils.randomPrivateKey();
const paymentPubKey  = await ed.getPublicKeyAsync(paymentPrivKey);

// DIDs are any URI — did:aroha: format used in examples
const humanDID   = "did:aroha:human:alice";
const agentDID   = "did:aroha:agent:orchestrator";
const paymentDID = "did:aroha:provider:payment-proc";

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

const intentMandate = await issueIntentMandate(
  humanDID,    // grantor — the human authorising spend
  agentDID,    // grantee — the orchestrator receiving authority
  {
    spendLimitUsd: 1000,       // hard ceiling for this session
    currency: "USD",
    allowedMerchants: null,    // null = any merchant
  },
  humanPrivKey,
  3_600_000    // TTL in ms (1 hour)
);

// intentMandate = { mandate, signature, token }
// token is a base64url blob — embed it in message credentialToken fields

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

const cartMandate = await attenuateToCart(
  intentMandate,      // the parent SignedMandate (from step 03)
  flightAgentDID,     // the service agent receiving this mandate
  {
    spendLimitUsd: 450,                    // narrowed from $1000
    currency: "USD",
    merchantCategory: "airlines",          // now restricted to airlines
    allowedMerchants: ["did:aroha:provider:united"],
  },
  agentPrivKey        // orchestrator signs this attenuation
);

// Attempting to widen throws immediately:
// attenuateToCart(intentMandate, ..., { spendLimitUsd: 9999 }, ...)
// → Error: spendLimitUsd 9999 exceeds parent limit 1000

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

const paymentMandate = await attenuateToPayment(
  cartMandate,        // the parent Cart Mandate
  paymentDID,         // the payment processor's DID
  {
    spendLimitUsd: 389.99,                 // the actual ticket price
    currency: "USD",
    merchantCategory: "airlines",
    allowedMerchants: ["did:aroha:provider:united"],
  },
  flightAgentPrivKey  // flight agent signs this attenuation
);

import { enforceSpendingConstraints, SpendingConstraintViolation } from "@aroha-sdk/credentials";

try {
  const mandate = await enforceSpendingConstraints(
    paymentMandate.token,   // base64url token from the message body
    flightAgentPubKey,      // public key of whoever signed this mandate
    {
      expectedGrantee:    paymentDID,                           // my own DID
      merchantDID:        "did:aroha:provider:united",          // who I am
      proposedAmountUsd:  389.99,                               // what I intend to charge
    }
  );
  // mandate.constraints is now the verified, authorized constraint set.
  // Safe to proceed with payment.
  console.log(`Authorized: $${mandate.constraints.spendLimitUsd}`);
  // → Authorized: $389.99

} catch (err) {
  if (err instanceof SpendingConstraintViolation) {
    // err.code: "MANDATE_INVALID" | "LIMIT_EXCEEDED" | "MERCHANT_NOT_ALLOWED"
    console.error(`Rejected [${err.code}]: ${err.message}`);
    // → e.g. "Rejected [LIMIT_EXCEEDED]: Proposed $500 exceeds mandate limit $389.99"
  }
}

// Lower-level alternative — use verifyMandate() if you need finer control:
// const result = await verifyMandate(token, pubKey, myDID);
// if (!result.valid) throw new Error(result.reason);
// // then check result.mandate.constraints yourself

// ✓ ENFORCED BY THE PROTOCOL (cryptographic, automatic):
//   - spendLimitUsd cannot increase during attenuation
//   - merchantCategory and allowedMerchants can only narrow, never broaden
//   - Signature verification — tampered tokens are rejected
//   - Expiry — expired mandates are rejected
//   - Grantee lock — mandate can only be used by the intended DID

// ✗ NOT ENFORCED BY THE PROTOCOL (your responsibility):
//   - Actually checking the mandate before processing a payment
//     → you must call verifyMandate() yourself
//   - Blocking a payment if spendLimitUsd is exceeded in your system
//     → read result.mandate.constraints and enforce in your logic
//   - Tracking cumulative spend across multiple mandates
//     → maintain a spend ledger in your database
//   - Settlement / fund movement
//     → use IArohaSettlement (alpha) or your own payment backend

// The mandate proves intent and authorization.
// Enforcement of actual money movement is your application's job.