@aroha-sdk/credentials 1.0.0

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@aroha-sdk/credentials",
+  "version": "1.0.0",
+  "description": "Human credentials, RBAC, and credential registry for the Aroha Protocol",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@aroha-sdk/core": "^1.0.0",
+    "@noble/ed25519": "^2.1.0",
+    "@noble/hashes": "^1.4.0",
+    "uuid": "^10.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  }
+}

package/src/credentials.test.ts

@@ -0,0 +1,93 @@
+import { describe, it, expect } from "vitest";
+import * as ed from "@noble/ed25519";
+import { sha512 } from "@noble/hashes/sha512";
+import {
+  issueHumanCredential,
+  verifyHumanCredential,
+  serializeCredential,
+  deserializeCredential,
+} from "./credentials.js";
+import { ArohaRole } from "./types.js";
+
+ed.etc.sha512Sync = (...m: Parameters<typeof sha512>) => sha512(...m);
+
+async function makeIssuer() {
+  const priv = ed.utils.randomPrivateKey();
+  const pub = await ed.getPublicKeyAsync(priv);
+  return { priv, pub, did: "did:aroha:issuer" };
+}
+
+describe("issueHumanCredential", () => {
+  it("issues a credential with correct fields", async () => {
+    const issuer = await makeIssuer();
+    const cred = await issueHumanCredential(
+      "user-123",
+      [ArohaRole.HumanUser],
+      issuer.did,
+      issuer.priv,
+      3_600_000,
+      "user@example.com"
+    );
+
+    expect(cred.userId).toBe("user-123");
+    expect(cred.roles).toContain(ArohaRole.HumanUser);
+    expect(cred.issuerDID).toBe(issuer.did);
+    expect(cred.email).toBe("user@example.com");
+    expect(cred.signature).toBeTruthy();
+    expect(new Date(cred.expiresAt) > new Date()).toBe(true);
+  });
+});
+
+describe("verifyHumanCredential", () => {
+  it("verifies a valid credential token", async () => {
+    const issuer = await makeIssuer();
+    const cred = await issueHumanCredential("user-456", [ArohaRole.HumanAdmin], issuer.did, issuer.priv);
+    const token = serializeCredential(cred);
+
+    const result = await verifyHumanCredential(token, issuer.pub);
+    expect(result.valid).toBe(true);
+    expect(result.credential?.userId).toBe("user-456");
+  });
+
+  it("rejects a token signed by a different key", async () => {
+    const issuer = await makeIssuer();
+    const otherIssuer = await makeIssuer();
+    const cred = await issueHumanCredential("user-789", [ArohaRole.HumanUser], issuer.did, issuer.priv);
+    const token = serializeCredential(cred);
+
+    const result = await verifyHumanCredential(token, otherIssuer.pub);
+    expect(result.valid).toBe(false);
+    expect(result.reason).toMatch(/invalid/i);
+  });
+
+  it("rejects a malformed token", async () => {
+    const issuer = await makeIssuer();
+    const result = await verifyHumanCredential("not-valid-base64url!!!", issuer.pub);
+    expect(result.valid).toBe(false);
+    expect(result.reason).toMatch(/malformed/i);
+  });
+
+  it("rejects an expired credential", async () => {
+    const issuer = await makeIssuer();
+    const cred = await issueHumanCredential("user-exp", [ArohaRole.HumanUser], issuer.did, issuer.priv, -1000);
+    const token = serializeCredential(cred);
+
+    const result = await verifyHumanCredential(token, issuer.pub);
+    expect(result.valid).toBe(false);
+    expect(result.reason).toMatch(/expired/i);
+  });
+});
+
+describe("serializeCredential / deserializeCredential", () => {
+  it("round-trips a credential", async () => {
+    const issuer = await makeIssuer();
+    const cred = await issueHumanCredential("round-trip", [ArohaRole.HumanReadonly], issuer.did, issuer.priv);
+    const token = serializeCredential(cred);
+    const decoded = deserializeCredential(token);
+    expect(decoded).toEqual(cred);
+  });
+
+  it("returns null for garbage input", () => {
+    expect(deserializeCredential("!!!")).toBeNull();
+  });
+});

package/src/credentials.ts

@@ -0,0 +1,148 @@
+/**
+ * Aroha Protocol — Human Credential System (Layer 1 extension)
+ *
+ * Human users are not DID-bearing agents. They authenticate to their Personal
+ * Agent (out of band — password, OAuth, passkey, etc.), which then issues them
+ * a short-lived signed credential. That credential travels in the body of any
+ * Aroha message the user triggers, letting provider agents verify who initiated
+ * the request and what they are allowed to do.
+ *
+ * The credential is signed by the issuing agent's Ed25519 private key using
+ * the same canonicalization rules as Aroha envelope proofs.
+ */
+
+import * as ed from "@noble/ed25519";
+import { sha512 } from "@noble/hashes/sha512";
+import { v4 as uuidv4 } from "uuid";
+import { type ArohaRole, type HumanCredential } from "./types.js";
+
+ed.etc.sha512Sync = (...m: Parameters<typeof sha512>) => sha512(...m);
+
+// Re-export so consumers can import from this module
+export type { HumanCredential } from "./types.js";
+
+export interface CredentialVerificationResult {
+  valid: boolean;
+  credential?: HumanCredential;
+  reason?: string;
+}
+
+// ─── Issue ────────────────────────────────────────────────────────────────────
+
+/**
+ * Issue a signed HumanCredential.
+ *
+ * @param userId      Application user identifier
+ * @param roles       Roles to grant (e.g. ["human:user"])
+ * @param issuerDID   DID of the issuing agent (the Personal Agent)
+ * @param privateKey  Ed25519 private key of the issuing agent (32 bytes)
+ * @param ttlMs       Time-to-live in milliseconds (default: 1 hour)
+ * @param email       Optional email for display purposes
+ */
+export async function issueHumanCredential(
+  userId: string,
+  roles: ArohaRole[],
+  issuerDID: string,
+  privateKey: Uint8Array,
+  ttlMs = 3_600_000,
+  email?: string
+): Promise<HumanCredential> {
+  const now = new Date();
+  const credential: Omit<HumanCredential, "signature"> = {
+    credentialId: uuidv4(),
+    userId,
+    roles,
+    issuedAt:  now.toISOString(),
+    expiresAt: new Date(now.getTime() + ttlMs).toISOString(),
+    issuerDID,
+    ...(email ? { email } : {}),
+  };
+
+  const canonical = canonicalizeCredential(credential);
+  const bytes = new TextEncoder().encode(canonical);
+  const sig = await ed.signAsync(bytes, privateKey);
+
+  return {
+    ...credential,
+    signature: Buffer.from(sig).toString("base64url"),
+  };
+}
+
+/**
+ * Serialize a HumanCredential to a compact base64url token suitable for
+ * embedding in a Aroha message body as `credentialToken`.
+ */
+export function serializeCredential(cred: HumanCredential): string {
+  return Buffer.from(JSON.stringify(cred)).toString("base64url");
+}
+
+/**
+ * Deserialize a credentialToken back to a HumanCredential object.
+ * Returns null if the token is malformed.
+ */
+export function deserializeCredential(token: string): HumanCredential | null {
+  try {
+    return JSON.parse(Buffer.from(token, "base64url").toString("utf8")) as HumanCredential;
+  } catch {
+    return null;
+  }
+}
+
+// ─── Verify ───────────────────────────────────────────────────────────────────
+
+/**
+ * Verify a HumanCredential.
+ *
+ * Checks:
+ *   1. Token is parseable
+ *   2. Expiry has not passed
+ *   3. Ed25519 signature is valid against the issuer's public key
+ *
+ * @param token       The base64url credentialToken from the message body
+ * @param issuerPublicKey  Ed25519 public key of the issuer DID (32 bytes)
+ */
+export async function verifyHumanCredential(
+  token: string,
+  issuerPublicKey: Uint8Array
+): Promise<CredentialVerificationResult> {
+  const cred = deserializeCredential(token);
+  if (!cred) {
+    return { valid: false, reason: "Credential token is malformed" };
+  }
+
+  if (new Date(cred.expiresAt) < new Date()) {
+    return { valid: false, reason: `Credential expired at ${cred.expiresAt}` };
+  }
+
+  const { signature, ...body } = cred;
+  const canonical = canonicalizeCredential(body);
+  const bytes = new TextEncoder().encode(canonical);
+
+  try {
+    const sig = Buffer.from(signature, "base64url");
+    const ok = await ed.verifyAsync(sig, bytes, issuerPublicKey);
+    if (!ok) return { valid: false, reason: "Credential signature invalid" };
+    return { valid: true, credential: cred };
+  } catch {
+    return { valid: false, reason: "Credential signature verification threw an error" };
+  }
+}
+
+// ─── Canonicalization ─────────────────────────────────────────────────────────
+
+/** Canonical JSON for signing — excludes `signature`, sorts keys. */
+function canonicalizeCredential(cred: Omit<HumanCredential, "signature">): string {
+  return JSON.stringify(sortKeysDeep(cred));
+}
+
+function sortKeysDeep(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortKeysDeep);
+  if (value !== null && typeof value === "object") {
+    const sorted: Record<string, unknown> = {};
+    for (const key of Object.keys(value as object).sort()) {
+      sorted[key] = sortKeysDeep((value as Record<string, unknown>)[key]);
+    }
+    return sorted;
+  }
+  return value;
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from "./types.js";
+export * from "./credentials.js";
+export * from "./rbac.js";
+export * from "./registry.js";
+export * from "./middleware.js";
+export * from "./mandate.js";

package/src/mandate.test.ts

@@ -0,0 +1,293 @@
+import { describe, it, expect } from "vitest";
+import * as ed from "@noble/ed25519";
+import { sha512 } from "@noble/hashes/sha512";
+import {
+  issueIntentMandate,
+  attenuateToCart,
+  attenuateToPayment,
+  verifyMandate,
+  type SignedMandate,
+} from "./mandate.js";
+import type { SpendingConstraints } from "@aroha-sdk/core";
+
+ed.etc.sha512Sync = (...m: Parameters<typeof sha512>) => sha512(...m);
+
+async function makeKey() {
+  const priv = ed.utils.randomPrivateKey();
+  const pub = await ed.getPublicKeyAsync(priv);
+  return { priv, pub };
+}
+
+const BASE: SpendingConstraints = {
+  spendLimitUsd: 500,
+  sessionLimitUsd: 200,
+  requireHumanApprovalAboveUsd: 100,
+  allowedMerchants: ["merchant-a", "merchant-b", "merchant-c"],
+};
+
+// ─── issueIntentMandate ───────────────────────────────────────────────────────
+
+describe("issueIntentMandate", () => {
+  it("issues a mandate with correct fields", async () => {
+    const k = await makeKey();
+    const m = await issueIntentMandate("did:aroha:grantor", "did:aroha:grantee", BASE, k.priv);
+    expect(m.mandate.mandateTier).toBe("intent");
+    expect(m.mandate.grantor).toBe("did:aroha:grantor");
+    expect(m.mandate.grantee).toBe("did:aroha:grantee");
+    expect(m.mandate.parentMandateId).toBeNull();
+    expect(m.mandate.mandateId).toBeTruthy();
+    expect(new Date(m.mandate.expiresAt) > new Date()).toBe(true);
+    expect(m.token).toBeTruthy();
+    expect(m.signature).toBeTruthy();
+  });
+
+  it("respects custom ttlMs", async () => {
+    const k = await makeKey();
+    const before = Date.now();
+    const m = await issueIntentMandate("did:aroha:g", "did:aroha:e", BASE, k.priv, 10_000);
+    const expMs = new Date(m.mandate.expiresAt).getTime();
+    expect(expMs - before).toBeGreaterThan(9_000);
+    expect(expMs - before).toBeLessThan(11_000);
+  });
+});
+
+// ─── verifyMandate ────────────────────────────────────────────────────────────
+
+describe("verifyMandate", () => {
+  it("accepts a valid token", async () => {
+    const k = await makeKey();
+    const m = await issueIntentMandate("did:aroha:g", "did:aroha:e", BASE, k.priv);
+    const r = await verifyMandate(m.token, k.pub);
+    expect(r.valid).toBe(true);
+    expect(r.mandate?.mandateId).toBe(m.mandate.mandateId);
+  });
+
+  it("rejects a token signed by a different key", async () => {
+    const k = await makeKey();
+    const other = await makeKey();
+    const m = await issueIntentMandate("did:aroha:g", "did:aroha:e", BASE, k.priv);
+    const r = await verifyMandate(m.token, other.pub);
+    expect(r.valid).toBe(false);
+    expect(r.reason).toMatch(/signature/i);
+  });
+
+  it("rejects an expired mandate", async () => {
+    const k = await makeKey();
+    const m = await issueIntentMandate("did:aroha:g", "did:aroha:e", BASE, k.priv, -1);
+    const r = await verifyMandate(m.token, k.pub);
+    expect(r.valid).toBe(false);
+    expect(r.reason).toMatch(/expired/i);
+  });
+
+  it("rejects grantee mismatch", async () => {
+    const k = await makeKey();
+    const m = await issueIntentMandate("did:aroha:g", "did:aroha:e", BASE, k.priv);
+    const r = await verifyMandate(m.token, k.pub, "did:aroha:someone-else");
+    expect(r.valid).toBe(false);
+    expect(r.reason).toMatch(/grantee/i);
+  });
+
+  it("rejects malformed token", async () => {
+    const k = await makeKey();
+    const r = await verifyMandate("not!!valid!!base64url", k.pub);
+    expect(r.valid).toBe(false);
+    expect(r.reason).toMatch(/malformed/i);
+  });
+});
+
+// ─── attenuateToCart — narrowing enforcement ──────────────────────────────────
+
+describe("attenuateToCart narrowing", () => {
+  async function intent(): Promise<[SignedMandate, Uint8Array, Uint8Array]> {
+    const k = await makeKey();
+    const m = await issueIntentMandate("did:aroha:user", "did:aroha:agent", BASE, k.priv);
+    return [m, k.priv, k.pub];
+  }
+
+  it("allows valid narrowing", async () => {
+    const [parent, agentKey] = await intent();
+    const narrow: SpendingConstraints = {
+      spendLimitUsd: 100,
+      sessionLimitUsd: 50,
+      requireHumanApprovalAboveUsd: 50,
+      allowedMerchants: ["merchant-a"],
+    };
+    await expect(
+      attenuateToCart(parent, "did:aroha:provider", narrow, agentKey)
+    ).resolves.toBeDefined();
+  });
+
+  it("rejects spendLimitUsd widening", async () => {
+    const [parent, agentKey] = await intent();
+    await expect(
+      attenuateToCart(parent, "did:aroha:p", { spendLimitUsd: 1000 }, agentKey)
+    ).rejects.toThrow(/spendLimit/i);
+  });
+
+  it("rejects sessionLimitUsd widening", async () => {
+    const [parent, agentKey] = await intent();
+    await expect(
+      attenuateToCart(parent, "did:aroha:p", { spendLimitUsd: 100, sessionLimitUsd: 999 }, agentKey)
+    ).rejects.toThrow(/sessionLimit/i);
+  });
+
+  it("rejects requireHumanApprovalAboveUsd widening", async () => {
+    const [parent, agentKey] = await intent();
+    await expect(
+      attenuateToCart(parent, "did:aroha:p", { spendLimitUsd: 100, requireHumanApprovalAboveUsd: 999 }, agentKey)
+    ).rejects.toThrow(/approval threshold/i);
+  });
+
+  it("rejects allowedMerchants with unlisted merchant", async () => {
+    const [parent, agentKey] = await intent();
+    await expect(
+      attenuateToCart(parent, "did:aroha:p", {
+        spendLimitUsd: 100,
+        allowedMerchants: ["merchant-a", "merchant-unknown"],
+      }, agentKey)
+    ).rejects.toThrow(/allowedMerchants/i);
+  });
+
+  it("rejects empty allowedMerchants when parent restricts", async () => {
+    const [parent, agentKey] = await intent();
+    await expect(
+      attenuateToCart(parent, "did:aroha:p", {
+        spendLimitUsd: 100,
+        allowedMerchants: [],
+      }, agentKey)
+    ).rejects.toThrow(/allowedMerchants/i);
+  });
+
+  it("rejects missing allowedMerchants when parent restricts", async () => {
+    const [parent, agentKey] = await intent();
+    await expect(
+      attenuateToCart(parent, "did:aroha:p", { spendLimitUsd: 100 }, agentKey)
+    ).rejects.toThrow(/allowedMerchants/i);
+  });
+});
+
+// ─── attenuateToPayment — narrowing enforcement ───────────────────────────────
+
+describe("attenuateToPayment narrowing", () => {
+  it("rejects spendLimitUsd widening from cart", async () => {
+    const intentKey = await makeKey();
+    const cartKey = await makeKey();
+    const intent = await issueIntentMandate("did:aroha:user", "did:aroha:agent", BASE, intentKey.priv);
+    const cart = await attenuateToCart(intent, "did:aroha:provider", {
+      spendLimitUsd: 100, allowedMerchants: ["merchant-a"],
+    }, intentKey.priv);
+    await expect(
+      attenuateToPayment(cart, "did:aroha:processor", { spendLimitUsd: 999 }, cartKey.priv)
+    ).rejects.toThrow(/spendLimit/i);
+  });
+});
+
+// ─── Full chain: intent → cart → payment ─────────────────────────────────────
+
+describe("full delegation chain", () => {
+  it("intent → cart → payment verifies end-to-end", async () => {
+    const userKey = await makeKey();
+    const agentKey = await makeKey();
+    const providerKey = await makeKey();
+
+    const intent = await issueIntentMandate(
+      "did:aroha:user", "did:aroha:agent", BASE, userKey.priv
+    );
+    const cart = await attenuateToCart(intent, "did:aroha:provider", {
+      spendLimitUsd: 100,
+      allowedMerchants: ["merchant-a"],
+    }, userKey.priv);
+    const payment = await attenuateToPayment(cart, "did:aroha:processor", {
+      spendLimitUsd: 42,
+      allowedMerchants: ["merchant-a"],
+    }, userKey.priv);
+
+    expect(payment.mandate.mandateTier).toBe("payment");
+    expect(payment.mandate.parentMandateId).toBe(cart.mandate.mandateId);
+    expect(payment.mandate.constraints.spendLimitUsd).toBe(42);
+
+    const r = await verifyMandate(payment.token, userKey.pub, "did:aroha:processor");
+    expect(r.valid).toBe(true);
+  });
+});
+
+describe("assertNarrowing — merchantCategory", () => {
+  it("allows child to keep same merchantCategory", async () => {
+    const k = await makeKey();
+    const parent = await issueIntentMandate("did:aroha:g", "did:aroha:e", {
+      spendLimitUsd: 500,
+      merchantCategory: "travel",
+    }, k.priv);
+    await expect(
+      attenuateToCart(parent, "did:aroha:p", { spendLimitUsd: 100, merchantCategory: "travel" }, k.priv)
+    ).resolves.toBeDefined();
+  });
+
+  it("rejects child setting merchantCategory to null when parent restricts it", async () => {
+    const k = await makeKey();
+    const parent = await issueIntentMandate("did:aroha:g", "did:aroha:e", {
+      spendLimitUsd: 500,
+      merchantCategory: "travel",
+    }, k.priv);
+    await expect(
+      attenuateToCart(parent, "did:aroha:p", { spendLimitUsd: 100, merchantCategory: null }, k.priv)
+    ).rejects.toThrow(/merchantCategory/i);
+  });
+
+  it("rejects child setting different merchantCategory", async () => {
+    const k = await makeKey();
+    const parent = await issueIntentMandate("did:aroha:g", "did:aroha:e", {
+      spendLimitUsd: 500,
+      merchantCategory: "travel",
+    }, k.priv);
+    await expect(
+      attenuateToCart(parent, "did:aroha:p", { spendLimitUsd: 100, merchantCategory: "food" }, k.priv)
+    ).rejects.toThrow(/merchantCategory/i);
+  });
+});
+
+describe("assertNarrowing — validUntil / validFrom", () => {
+  const future = (offsetMs: number) => new Date(Date.now() + offsetMs).toISOString();
+
+  it("rejects child validUntil beyond parent validUntil", async () => {
+    const k = await makeKey();
+    const parent = await issueIntentMandate("did:aroha:g", "did:aroha:e", {
+      spendLimitUsd: 500,
+      validUntil: future(3_600_000), // 1 hour
+    }, k.priv);
+    await expect(
+      attenuateToCart(parent, "did:aroha:p", {
+        spendLimitUsd: 100,
+        validUntil: future(7_200_000), // 2 hours — wider
+      }, k.priv)
+    ).rejects.toThrow(/validUntil/i);
+  });
+
+  it("allows child validUntil within parent window", async () => {
+    const k = await makeKey();
+    const parent = await issueIntentMandate("did:aroha:g", "did:aroha:e", {
+      spendLimitUsd: 500,
+      validUntil: future(3_600_000),
+    }, k.priv);
+    await expect(
+      attenuateToCart(parent, "did:aroha:p", {
+        spendLimitUsd: 100,
+        validUntil: future(1_800_000), // 30 min — narrower
+      }, k.priv)
+    ).resolves.toBeDefined();
+  });
+
+  it("rejects child validFrom before parent validFrom", async () => {
+    const k = await makeKey();
+    const parent = await issueIntentMandate("did:aroha:g", "did:aroha:e", {
+      spendLimitUsd: 500,
+      validFrom: future(3_600_000),
+    }, k.priv);
+    await expect(
+      attenuateToCart(parent, "did:aroha:p", {
+        spendLimitUsd: 100,
+        validFrom: future(1_800_000), // starts earlier than parent — wider
+      }, k.priv)
+    ).rejects.toThrow(/validFrom/i);
+  });
+});