@aroha-sdk/credentials 1.0.0

package/src/mandate.ts

@@ -0,0 +1,272 @@
+/**
+ * @aroha-sdk/credentials — ArohaMandateCredential
+ *
+ * Issues, attenuates, and verifies ArohaSpendingMandate tokens.
+ *
+ * The mandate chain enforces monotonic scope narrowing:
+ *   User → Intent Mandate (max budget)
+ *   Personal Agent → Cart Mandate (narrowed to specific service)
+ *   Provider Agent → Payment Mandate (single-transaction authorisation)
+ *
+ * Each mandate is Ed25519-signed by the grantor. The grantee carries the
+ * token in the ArohaSpendingMandate message body — the payment processor
+ * verifies the full chain without ever seeing the user's card number.
+ *
+ * References:
+ *   AP2 Protocol (Google) Intent/Cart/Payment Mandate pattern.
+ *   IETF draft-niyikiza-oauth-attenuating-agent-tokens (2024).
+ */
+
+import * as ed from "@noble/ed25519";
+import { sha512 } from "@noble/hashes/sha512";
+import { v4 as uuidv4 } from "uuid";
+import { type ArohaSpendingMandateBody, type SpendingConstraints } from "@aroha-sdk/core";
+
+ed.etc.sha512Sync = (...m: Parameters<typeof sha512>) => sha512(...m);
+
+export interface SignedMandate {
+  mandate: ArohaSpendingMandateBody;
+  /** base64url Ed25519 signature over the canonical mandate (proof). */
+  signature: string;
+  /** base64url serialised mandate + signature — embed in message body credentialToken. */
+  token: string;
+}
+
+export interface MandateVerificationResult {
+  valid: boolean;
+  mandate?: ArohaSpendingMandateBody;
+  reason?: string;
+}
+
+// ─── Issue ────────────────────────────────────────────────────────────────────
+
+/**
+ * Issue a root Intent Mandate from a user to their personal agent.
+ *
+ * @param grantorDID   User's DID (or personal-agent acting on user's behalf)
+ * @param granteeDID   Personal agent's DID
+ * @param constraints  Maximum spend envelope — all downstream mandates must be ≤ these
+ * @param privateKey   Grantor's Ed25519 private key (32 bytes)
+ * @param ttlMs        Time-to-live in milliseconds (default: 1 hour)
+ */
+export async function issueIntentMandate(
+  grantorDID: string,
+  granteeDID: string,
+  constraints: SpendingConstraints,
+  privateKey: Uint8Array,
+  ttlMs = 3_600_000
+): Promise<SignedMandate> {
+  return issueMandateInternal("intent", grantorDID, granteeDID, constraints, null, privateKey, ttlMs);
+}
+
+/**
+ * Attenuate a mandate to a narrower Cart Mandate.
+ * Validates that the new constraints are a subset of the parent's constraints.
+ */
+export async function attenuateToCart(
+  parent: SignedMandate,
+  granteeDID: string,
+  narrowedConstraints: SpendingConstraints,
+  grantorPrivateKey: Uint8Array,
+  ttlMs?: number
+): Promise<SignedMandate> {
+  assertNarrowing(parent.mandate.constraints, narrowedConstraints, parent.mandate.mandateTier, "cart");
+  const expiry = ttlMs
+    ? Math.min(new Date(parent.mandate.expiresAt).getTime(), Date.now() + ttlMs)
+    : new Date(parent.mandate.expiresAt).getTime();
+  return issueMandateInternal(
+    "cart",
+    parent.mandate.grantee,
+    granteeDID,
+    narrowedConstraints,
+    parent.mandate.mandateId,
+    grantorPrivateKey,
+    expiry - Date.now()
+  );
+}
+
+/**
+ * Attenuate a Cart Mandate to a single-transaction Payment Mandate.
+ */
+export async function attenuateToPayment(
+  parent: SignedMandate,
+  granteeDID: string,
+  narrowedConstraints: SpendingConstraints,
+  grantorPrivateKey: Uint8Array,
+  ttlMs?: number
+): Promise<SignedMandate> {
+  assertNarrowing(parent.mandate.constraints, narrowedConstraints, parent.mandate.mandateTier, "payment");
+  const expiry = ttlMs
+    ? Math.min(new Date(parent.mandate.expiresAt).getTime(), Date.now() + ttlMs)
+    : new Date(parent.mandate.expiresAt).getTime();
+  return issueMandateInternal(
+    "payment",
+    parent.mandate.grantee,
+    granteeDID,
+    narrowedConstraints,
+    parent.mandate.mandateId,
+    grantorPrivateKey,
+    expiry - Date.now()
+  );
+}
+
+// ─── Verify ───────────────────────────────────────────────────────────────────
+
+/**
+ * Verify a mandate token.
+ *
+ * @param token       The base64url mandate token from credentialToken field
+ * @param publicKey   Grantor's Ed25519 public key (32 bytes)
+ * @param expectedGrantee  If set, validates the grantee DID matches
+ */
+export async function verifyMandate(
+  token: string,
+  publicKey: Uint8Array,
+  expectedGrantee?: string
+): Promise<MandateVerificationResult> {
+  let signed: SignedMandate;
+  try {
+    signed = JSON.parse(Buffer.from(token, "base64url").toString("utf8")) as SignedMandate;
+  } catch {
+    return { valid: false, reason: "Malformed token" };
+  }
+
+  const { mandate, signature } = signed;
+
+  // Expiry check
+  if (new Date(mandate.expiresAt) < new Date()) {
+    return { valid: false, reason: "Mandate expired" };
+  }
+
+  // Grantee check
+  if (expectedGrantee && mandate.grantee !== expectedGrantee) {
+    return { valid: false, reason: `Mandate grantee mismatch: expected ${expectedGrantee}` };
+  }
+
+  // Signature check
+  try {
+    const canonical = canonicalizeMandate(mandate);
+    const bytes = new TextEncoder().encode(canonical);
+    const sigBytes = Buffer.from(signature, "base64url");
+    const valid = await ed.verifyAsync(sigBytes, bytes, publicKey);
+    if (!valid) return { valid: false, reason: "Invalid signature" };
+  } catch {
+    return { valid: false, reason: "Signature verification error" };
+  }
+
+  return { valid: true, mandate };
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+async function issueMandateInternal(
+  tier: "intent" | "cart" | "payment",
+  grantorDID: string,
+  granteeDID: string,
+  constraints: SpendingConstraints,
+  parentMandateId: string | null,
+  privateKey: Uint8Array,
+  ttlMs: number
+): Promise<SignedMandate> {
+  const mandate: ArohaSpendingMandateBody = {
+    mandateTier: tier,
+    constraints,
+    grantee: granteeDID,
+    grantor: grantorDID,
+    expiresAt: new Date(Date.now() + ttlMs).toISOString(),
+    parentMandateId,
+    mandateId: uuidv4(),
+  };
+
+  const canonical = canonicalizeMandate(mandate);
+  const bytes = new TextEncoder().encode(canonical);
+  const sig = await ed.signAsync(bytes, privateKey);
+  const signature = Buffer.from(sig).toString("base64url");
+  const token = Buffer.from(JSON.stringify({ mandate, signature })).toString("base64url");
+
+  return { mandate, signature, token };
+}
+
+/** Canonical JSON — lexicographically sorted keys, no whitespace. */
+function canonicalizeMandate(mandate: ArohaSpendingMandateBody): string {
+  return JSON.stringify(sortKeys(mandate));
+}
+
+function sortKeys(obj: unknown): unknown {
+  if (Array.isArray(obj)) return obj.map(sortKeys);
+  if (obj !== null && typeof obj === "object") {
+    return Object.keys(obj as Record<string, unknown>)
+      .sort()
+      .reduce((acc, k) => {
+        (acc as Record<string, unknown>)[k] = sortKeys((obj as Record<string, unknown>)[k]);
+        return acc;
+      }, {} as Record<string, unknown>);
+  }
+  return obj;
+}
+
+/**
+ * Validate that a narrowed constraint set is a subset of the parent's.
+ * Throws if any narrowed value exceeds the parent's limit.
+ */
+function assertNarrowing(
+  parent: SpendingConstraints,
+  child: SpendingConstraints,
+  parentTier: string,
+  childTier: string
+): void {
+  const prefix = `Cannot attenuate ${parentTier} → ${childTier}`;
+
+  if (child.spendLimitUsd > parent.spendLimitUsd) {
+    throw new Error(`${prefix}: child spendLimitUsd (${child.spendLimitUsd}) exceeds parent (${parent.spendLimitUsd})`);
+  }
+
+  if (
+    parent.sessionLimitUsd !== undefined &&
+    child.sessionLimitUsd !== undefined &&
+    child.sessionLimitUsd > parent.sessionLimitUsd
+  ) {
+    throw new Error(`${prefix}: child sessionLimitUsd exceeds parent`);
+  }
+
+  if (
+    parent.requireHumanApprovalAboveUsd !== undefined &&
+    child.requireHumanApprovalAboveUsd !== undefined &&
+    child.requireHumanApprovalAboveUsd > parent.requireHumanApprovalAboveUsd
+  ) {
+    throw new Error(`${prefix}: child approval threshold exceeds parent`);
+  }
+
+  if (parent.allowedMerchants != null && parent.allowedMerchants.length > 0) {
+    const parentSet = new Set(parent.allowedMerchants);
+    if (!child.allowedMerchants || child.allowedMerchants.length === 0) {
+      throw new Error(`${prefix}: parent restricts allowedMerchants but child sets none`);
+    }
+    for (const m of child.allowedMerchants) {
+      if (!parentSet.has(m)) {
+        throw new Error(`${prefix}: child allowedMerchants contains "${m}" not in parent`);
+      }
+    }
+  }
+
+  if (parent.merchantCategory !== undefined && parent.merchantCategory !== null) {
+    if (child.merchantCategory === null || child.merchantCategory === undefined) {
+      throw new Error(`${prefix}: child merchantCategory must not widen parent's "${parent.merchantCategory}" restriction`);
+    }
+    if (child.merchantCategory !== parent.merchantCategory) {
+      throw new Error(`${prefix}: child merchantCategory "${child.merchantCategory}" does not match parent "${parent.merchantCategory}"`);
+    }
+  }
+
+  if (parent.validUntil !== undefined && child.validUntil !== undefined) {
+    if (new Date(child.validUntil) > new Date(parent.validUntil)) {
+      throw new Error(`${prefix}: child validUntil (${child.validUntil}) extends beyond parent (${parent.validUntil})`);
+    }
+  }
+
+  if (parent.validFrom !== undefined && child.validFrom !== undefined) {
+    if (new Date(child.validFrom) < new Date(parent.validFrom)) {
+      throw new Error(`${prefix}: child validFrom (${child.validFrom}) precedes parent (${parent.validFrom})`);
+    }
+  }
+}

package/src/middleware.ts

@@ -0,0 +1,247 @@
+/**
+ * @aroha-sdk/credentials — ArohaServer middleware and HTTP route helpers
+ *
+ * Wire RBAC and the credential registry into ArohaServer without coupling
+ * aroha-core to this package.
+ *
+ *   import { createRbacMiddleware, credentialRegistryRoutes } from "@aroha-sdk/credentials";
+ *
+ *   const server = new ArohaServer({
+ *     ...
+ *     middleware: [createRbacMiddleware(policy)],
+ *     httpRoutes: credentialRegistryRoutes(registry, { resolveIssuerPublicKey }),
+ *   });
+ */
+
+import { type IncomingMessage, type ServerResponse } from "http";
+import { type ArohaEnvelope, type ArohaMiddleware, type ArohaHttpRoute, readBody } from "@aroha-sdk/core";
+import { verifyHumanCredential, deserializeCredential, serializeCredential } from "./credentials.js";
+import { verifyRevokeProof, CredentialRegistry } from "./registry.js";
+import { checkPermission, actionForMessageType, DEFAULT_RBAC_PERMISSIONS, type RbacPolicy } from "./rbac.js";
+import { type ArohaRole } from "./types.js";
+import { type HumanCredential } from "./types.js";
+
+// ─── RBAC middleware ──────────────────────────────────────────────────────────
+
+/**
+ * Create a ArohaServer middleware that enforces RBAC on every inbound message.
+ *
+ * @example
+ *   server = new ArohaServer({
+ *     middleware: [createRbacMiddleware({
+ *       resolveAgentRoles: async (did) => agentRoles.get(did) ?? [],
+ *       resolveIssuerPublicKey: async (did) => issuerKeys.get(did) ?? null,
+ *     })],
+ *   });
+ */
+export function createRbacMiddleware(policy: RbacPolicy): ArohaMiddleware {
+  return async (envelope: ArohaEnvelope, reject) => {
+    const result = await checkRbac(envelope, policy);
+    if (!result.allowed) {
+      const status = result.unauthorized ? 401 : 403;
+      const code   = result.unauthorized ? "Aroha_UNAUTHORIZED" : "Aroha_FORBIDDEN";
+      reject(status, code, result.reason ?? "Access denied");
+    }
+  };
+}
+
+async function checkRbac(
+  envelope: ArohaEnvelope,
+  policy: RbacPolicy
+): Promise<{ allowed: boolean; unauthorized?: boolean; reason?: string }> {
+  const action = actionForMessageType(envelope.type as Parameters<typeof actionForMessageType>[0]);
+  if (!action) return { allowed: true }; // acks and responses skip RBAC
+
+  const permissions = policy.permissions ?? DEFAULT_RBAC_PERMISSIONS;
+  const body = envelope.body as unknown as Record<string, unknown>;
+  const credentialId    = body?.credentialId    as string | undefined;
+  const credentialToken = body?.credentialToken as string | undefined;
+
+  let roles: ArohaRole[];
+
+  if (credentialId) {
+    if (!policy.credentialRegistry) {
+      return { allowed: false, unauthorized: true, reason: "credentialId supplied but no credential registry configured" };
+    }
+    const cred = await policy.credentialRegistry.resolve(credentialId);
+    if (!cred) {
+      return { allowed: false, unauthorized: true, reason: `Credential not found or expired: ${credentialId}` };
+    }
+    if (policy.resolveIssuerPublicKey) {
+      const issuerPubKey = await policy.resolveIssuerPublicKey(cred.issuerDID);
+      if (issuerPubKey) {
+        const token = serializeCredential(cred as HumanCredential);
+        const verifyResult = await verifyHumanCredential(token, issuerPubKey);
+        if (!verifyResult.valid) {
+          return { allowed: false, unauthorized: true, reason: `Registry credential signature invalid: ${verifyResult.reason}` };
+        }
+      }
+    }
+    roles = (cred as HumanCredential).roles;
+
+  } else if (credentialToken) {
+    if (!policy.resolveIssuerPublicKey) {
+      return { allowed: false, unauthorized: true, reason: "Server does not accept human credentials (no resolveIssuerPublicKey configured)" };
+    }
+    const parsed = deserializeCredential(credentialToken);
+    if (!parsed) {
+      return { allowed: false, unauthorized: true, reason: "credentialToken is malformed" };
+    }
+    const issuerPubKey = await policy.resolveIssuerPublicKey(parsed.issuerDID);
+    if (!issuerPubKey) {
+      return { allowed: false, unauthorized: true, reason: `Unknown credential issuer: ${parsed.issuerDID}` };
+    }
+    const verifyResult = await verifyHumanCredential(credentialToken, issuerPubKey);
+    if (!verifyResult.valid) {
+      return { allowed: false, unauthorized: true, reason: verifyResult.reason };
+    }
+    roles = verifyResult.credential!.roles;
+
+  } else {
+    roles = await policy.resolveAgentRoles(envelope.from);
+    if (roles.length === 0) {
+      return { allowed: false, unauthorized: false, reason: `Agent ${envelope.from} has no assigned roles` };
+    }
+  }
+
+  const result = checkPermission(roles, action, permissions);
+  return { allowed: result.allowed, reason: result.reason };
+}
+
+// ─── Credential registry HTTP routes ─────────────────────────────────────────
+
+export interface CredentialRegistryRouteOptions {
+  /**
+   * Resolve the issuer's public key for signature verification on register/revoke.
+   * When omitted, credentials are stored without signature verification.
+   */
+  resolveIssuerPublicKey?: (issuerDID: string) => Promise<Uint8Array | null>;
+}
+
+/**
+ * Returns ArohaHttpRoute[] that mount credential registry endpoints on ArohaServer.
+ *
+ * Endpoints added:
+ *   POST   /aroha/credentials          — register a credential
+ *   GET    /aroha/credentials/:id      — resolve by ID
+ *   GET    /aroha/credentials?userId=  — list by user
+ *   DELETE /aroha/credentials/:id      — revoke (requires X-Revoke-Proof header)
+ *
+ * @example
+ *   const registry = new CredentialRegistry();
+ *   const server = new ArohaServer({
+ *     httpRoutes: credentialRegistryRoutes(registry, { resolveIssuerPublicKey }),
+ *   });
+ */
+export function credentialRegistryRoutes(
+  registry: CredentialRegistry,
+  opts: CredentialRegistryRouteOptions = {}
+): ArohaHttpRoute[] {
+  return [
+    {
+      method: "POST",
+      test: (url) => url === "/aroha/credentials",
+      handle: (req, res) => handleRegister(req, res, registry, opts),
+    },
+    {
+      method: "DELETE",
+      test: (url) => /^\/aroha\/credentials\/[^?/]+$/.test(url),
+      handle: (req, res) => handleRevoke(req, res, registry, opts),
+    },
+    {
+      method: "GET",
+      test: (url) => /^\/aroha\/credentials\/[^?/]+$/.test(url),
+      handle: (req, res) => handleResolve(req, res, registry),
+    },
+    {
+      method: "GET",
+      test: (url) => url === "/aroha/credentials" || url.startsWith("/aroha/credentials?"),
+      handle: (req, res) => handleList(req, res, registry),
+    },
+  ];
+}
+
+// ─── Route handlers ───────────────────────────────────────────────────────────
+
+async function handleRegister(
+  req: IncomingMessage,
+  res: ServerResponse,
+  registry: CredentialRegistry,
+  opts: CredentialRegistryRouteOptions
+): Promise<void> {
+  const body = await readBody(req).catch(() => null);
+  if (!body) { res.writeHead(400); res.end(JSON.stringify({ error: "Invalid body" })); return; }
+
+  let cred: HumanCredential;
+  try { cred = JSON.parse(body) as HumanCredential; }
+  catch { res.writeHead(400); res.end(JSON.stringify({ error: "Invalid JSON" })); return; }
+
+  if (opts.resolveIssuerPublicKey) {
+    const pubKey = await opts.resolveIssuerPublicKey(cred.issuerDID);
+    if (!pubKey) {
+      res.writeHead(401);
+      res.end(JSON.stringify({ error: `Unknown credential issuer: ${cred.issuerDID}` }));
+      return;
+    }
+    const ok = await registry.register(cred, pubKey);
+    if (!ok) { res.writeHead(400); res.end(JSON.stringify({ error: "Credential signature invalid" })); return; }
+  } else {
+    registry.registerTrusted(cred);
+  }
+
+  res.writeHead(201, { "Content-Type": "application/json" });
+  res.end(JSON.stringify({ credentialId: cred.credentialId, stored: true }));
+}
+
+async function handleRevoke(
+  req: IncomingMessage,
+  res: ServerResponse,
+  registry: CredentialRegistry,
+  opts: CredentialRegistryRouteOptions
+): Promise<void> {
+  const credentialId = decodeURIComponent((req.url ?? "").split("/").pop() ?? "");
+  const cred = registry.resolve(credentialId);
+  if (!cred) { res.writeHead(404); res.end(JSON.stringify({ error: "Credential not found" })); return; }
+
+  if (opts.resolveIssuerPublicKey) {
+    const pubKey = await opts.resolveIssuerPublicKey(cred.issuerDID);
+    if (!pubKey) {
+      res.writeHead(401);
+      res.end(JSON.stringify({ error: `Unknown credential issuer: ${cred.issuerDID}` }));
+      return;
+    }
+    const proof = req.headers["x-revoke-proof"] as string | undefined;
+    if (!proof) { res.writeHead(401); res.end(JSON.stringify({ error: "X-Revoke-Proof header required" })); return; }
+    const valid = await verifyRevokeProof(credentialId, proof, pubKey);
+    if (!valid) { res.writeHead(403); res.end(JSON.stringify({ error: "Revoke proof invalid" })); return; }
+  }
+
+  registry.revoke(credentialId);
+  res.writeHead(200, { "Content-Type": "application/json" });
+  res.end(JSON.stringify({ credentialId, revoked: true }));
+}
+
+async function handleResolve(
+  _req: IncomingMessage,
+  res: ServerResponse,
+  registry: CredentialRegistry
+): Promise<void> {
+  const credentialId = decodeURIComponent((_req.url ?? "").split("?")[0].split("/").pop() ?? "");
+  const cred = registry.resolve(credentialId);
+  if (!cred) { res.writeHead(404); res.end(JSON.stringify({ error: "Credential not found or expired" })); return; }
+  res.writeHead(200, { "Content-Type": "application/json" });
+  res.end(JSON.stringify(cred));
+}
+
+async function handleList(
+  req: IncomingMessage,
+  res: ServerResponse,
+  registry: CredentialRegistry
+): Promise<void> {
+  const urlObj = new URL(req.url ?? "/", "http://localhost");
+  const userId = urlObj.searchParams.get("userId");
+  if (!userId) { res.writeHead(400); res.end(JSON.stringify({ error: "userId query param required" })); return; }
+  res.writeHead(200, { "Content-Type": "application/json" });
+  res.end(JSON.stringify(registry.listForUser(userId)));
+}
+

package/src/rbac.test.ts

@@ -0,0 +1,113 @@
+import { describe, it, expect } from "vitest";
+import { checkPermission, actionForMessageType, DEFAULT_RBAC_PERMISSIONS } from "./rbac.js";
+import { ArohaRole } from "./types.js";
+
+describe("actionForMessageType", () => {
+  it("maps ArohaRequest to query", () => {
+    expect(actionForMessageType("ArohaRequest")).toBe("query");
+  });
+  it("maps ArohaReserve to reserve", () => {
+    expect(actionForMessageType("ArohaReserve")).toBe("reserve");
+  });
+  it("maps ArohaCommit to commit", () => {
+    expect(actionForMessageType("ArohaCommit")).toBe("commit");
+  });
+  it("maps ArohaCancel to cancel", () => {
+    expect(actionForMessageType("ArohaCancel")).toBe("cancel");
+  });
+  it("maps ArohaDelegate to delegate", () => {
+    expect(actionForMessageType("ArohaDelegate")).toBe("delegate");
+  });
+  it("maps ArohaNegotiate to negotiate", () => {
+    expect(actionForMessageType("ArohaNegotiate")).toBe("negotiate");
+  });
+  it("returns null for response/ack types", () => {
+    expect(actionForMessageType("ArohaResponse")).toBeNull();
+    expect(actionForMessageType("ArohaReserveAck")).toBeNull();
+    expect(actionForMessageType("ArohaCommitAck")).toBeNull();
+    expect(actionForMessageType("ArohaError")).toBeNull();
+  });
+});
+
+describe("checkPermission", () => {
+  it("allows HumanAdmin all actions", () => {
+    const actions = ["query", "reserve", "commit", "cancel", "delegate", "negotiate", "admin"] as const;
+    for (const action of actions) {
+      const result = checkPermission([ArohaRole.HumanAdmin], action);
+      expect(result.allowed).toBe(true);
+    }
+  });
+
+  it("allows HumanUser to query/reserve/commit/cancel/negotiate but not delegate or admin", () => {
+    expect(checkPermission([ArohaRole.HumanUser], "query").allowed).toBe(true);
+    expect(checkPermission([ArohaRole.HumanUser], "reserve").allowed).toBe(true);
+    expect(checkPermission([ArohaRole.HumanUser], "delegate").allowed).toBe(false);
+    expect(checkPermission([ArohaRole.HumanUser], "admin").allowed).toBe(false);
+  });
+
+  it("allows HumanReadonly only query", () => {
+    expect(checkPermission([ArohaRole.HumanReadonly], "query").allowed).toBe(true);
+    expect(checkPermission([ArohaRole.HumanReadonly], "reserve").allowed).toBe(false);
+  });
+
+  it("denies AgentProvider all actions", () => {
+    expect(checkPermission([ArohaRole.AgentProvider], "query").allowed).toBe(false);
+  });
+
+  it("allows AgentOrchestrator to delegate", () => {
+    expect(checkPermission([ArohaRole.AgentOrchestrator], "delegate").allowed).toBe(true);
+  });
+
+  it("returns false with no roles", () => {
+    const result = checkPermission([], "query");
+    expect(result.allowed).toBe(false);
+    expect(result.reason).toMatch(/No roles/);
+  });
+
+  it("unions permissions across multiple roles", () => {
+    // HumanReadonly (query only) + AgentOrchestrator (query+reserve+..+delegate) → delegate allowed
+    const result = checkPermission([ArohaRole.HumanReadonly, ArohaRole.AgentOrchestrator], "delegate");
+    expect(result.allowed).toBe(true);
+  });
+
+  it("includes role list in result", () => {
+    const result = checkPermission([ArohaRole.HumanUser], "query");
+    expect(result.roles).toContain(ArohaRole.HumanUser);
+  });
+});
+
+describe("ArohaSpendingMandate action mapping", () => {
+  it("maps ArohaSpendingMandate to mandate", () => {
+    expect(actionForMessageType("ArohaSpendingMandate")).toBe("mandate");
+  });
+
+  it("ArohaSatisfactionSignal returns null (private signal, no RBAC)", () => {
+    expect(actionForMessageType("ArohaSatisfactionSignal")).toBeNull();
+  });
+});
+
+describe("mandate action permissions", () => {
+  it("allows HumanAdmin to issue mandates", () => {
+    expect(checkPermission([ArohaRole.HumanAdmin], "mandate").allowed).toBe(true);
+  });
+
+  it("allows HumanUser to issue mandates", () => {
+    expect(checkPermission([ArohaRole.HumanUser], "mandate").allowed).toBe(true);
+  });
+
+  it("allows AgentOrchestrator to issue mandates", () => {
+    expect(checkPermission([ArohaRole.AgentOrchestrator], "mandate").allowed).toBe(true);
+  });
+
+  it("denies HumanReadonly from issuing mandates", () => {
+    expect(checkPermission([ArohaRole.HumanReadonly], "mandate").allowed).toBe(false);
+  });
+
+  it("denies AgentObserver from issuing mandates", () => {
+    expect(checkPermission([ArohaRole.AgentObserver], "mandate").allowed).toBe(false);
+  });
+
+  it("denies AgentProvider from issuing mandates", () => {
+    expect(checkPermission([ArohaRole.AgentProvider], "mandate").allowed).toBe(false);
+  });
+});