@aroha-sdk/credentials 1.0.0

package/src/rbac.ts

@@ -0,0 +1,91 @@
+import { type ArohaMessageType } from "@aroha-sdk/core";
+import { ArohaRole, type HumanCredential } from "./types.js";
+
+export { ArohaRole } from "./types.js";
+
+// ─── Actions ──────────────────────────────────────────────────────────────────
+
+export type ArohaAction =
+  | "query"
+  | "reserve"
+  | "commit"
+  | "cancel"
+  | "delegate"
+  | "negotiate"
+  | "mandate"
+  | "admin";
+
+export function actionForMessageType(type: ArohaMessageType): ArohaAction | null {
+  switch (type) {
+    case "ArohaRequest":
+    case "ArohaStream":
+      return "query";
+    case "ArohaReserve":
+      return "reserve";
+    case "ArohaCommit":
+      return "commit";
+    case "ArohaCancel":
+      return "cancel";
+    case "ArohaDelegate":
+      return "delegate";
+    case "ArohaNegotiate":
+    case "ArohaCounterOffer":
+    case "ArohaAccept":
+      return "negotiate";
+    case "ArohaSpendingMandate":
+      return "mandate";
+    default:
+      return null;
+  }
+}
+
+// ─── Policy ───────────────────────────────────────────────────────────────────
+
+export type RolePermissions = Partial<Record<ArohaRole, ArohaAction[]>>;
+
+export interface RbacPolicy {
+  permissions?: RolePermissions;
+  resolveAgentRoles: (agentDID: string) => Promise<ArohaRole[]> | ArohaRole[];
+  resolveIssuerPublicKey?: (issuerDID: string) => Promise<Uint8Array | null> | Uint8Array | null;
+  credentialRegistry?: {
+    resolve(credentialId: string): HumanCredential | null | Promise<HumanCredential | null>;
+  };
+}
+
+export const DEFAULT_RBAC_PERMISSIONS: RolePermissions = {
+  [ArohaRole.HumanAdmin]:        ["query", "reserve", "commit", "cancel", "delegate", "negotiate", "mandate", "admin"],
+  [ArohaRole.HumanUser]:         ["query", "reserve", "commit", "cancel", "negotiate", "mandate"],
+  [ArohaRole.HumanReadonly]:     ["query"],
+  [ArohaRole.AgentOrchestrator]: ["query", "reserve", "commit", "cancel", "delegate", "negotiate", "mandate"],
+  [ArohaRole.AgentProvider]:     [],
+  [ArohaRole.AgentObserver]:     ["query"],
+};
+
+// ─── Permission check ─────────────────────────────────────────────────────────
+
+export interface RbacCheckResult {
+  allowed: boolean;
+  roles: ArohaRole[];
+  reason?: string;
+}
+
+export function checkPermission(
+  roles: ArohaRole[],
+  action: ArohaAction,
+  permissions: RolePermissions = DEFAULT_RBAC_PERMISSIONS
+): RbacCheckResult {
+  if (roles.length === 0) {
+    return { allowed: false, roles, reason: "No roles assigned" };
+  }
+  for (const role of roles) {
+    const allowed = permissions[role] ?? [];
+    if (allowed.includes("admin") || allowed.includes(action)) {
+      return { allowed: true, roles };
+    }
+  }
+  return {
+    allowed: false,
+    roles,
+    reason: `Roles [${roles.join(", ")}] do not permit action "${action}"`,
+  };
+}

package/src/registry.test.ts

@@ -0,0 +1,169 @@
+import { describe, it, expect } from "vitest";
+import * as ed from "@noble/ed25519";
+import { sha512 } from "@noble/hashes/sha512";
+import { CredentialRegistry, buildRevokeProof, verifyRevokeProof } from "./registry.js";
+import { issueHumanCredential, serializeCredential } 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" };
+}
+
+async function makeCred(issuer: Awaited<ReturnType<typeof makeIssuer>>, userId = "user-1") {
+  return issueHumanCredential(userId, [ArohaRole.HumanUser], issuer.did, issuer.priv);
+}
+
+describe("CredentialRegistry", () => {
+  it("registers and resolves a valid credential", async () => {
+    const issuer = await makeIssuer();
+    const cred = await makeCred(issuer);
+    const registry = new CredentialRegistry();
+
+    const ok = await registry.register(cred, issuer.pub);
+    expect(ok).toBe(true);
+
+    const resolved = registry.resolve(cred.credentialId);
+    expect(resolved).not.toBeNull();
+    expect(resolved?.userId).toBe("user-1");
+  });
+
+  it("rejects registration with wrong issuer key", async () => {
+    const issuer = await makeIssuer();
+    const wrongIssuer = await makeIssuer();
+    const cred = await makeCred(issuer);
+    const registry = new CredentialRegistry();
+
+    const ok = await registry.register(cred, wrongIssuer.pub);
+    expect(ok).toBe(false);
+    expect(registry.resolve(cred.credentialId)).toBeNull();
+  });
+
+  it("registerTrusted bypasses signature check", async () => {
+    const issuer = await makeIssuer();
+    const cred = await makeCred(issuer);
+    const registry = new CredentialRegistry();
+
+    registry.registerTrusted(cred);
+    expect(registry.resolve(cred.credentialId)).not.toBeNull();
+  });
+
+  it("revokes a credential", async () => {
+    const issuer = await makeIssuer();
+    const cred = await makeCred(issuer);
+    const registry = new CredentialRegistry();
+
+    registry.registerTrusted(cred);
+    expect(registry.resolve(cred.credentialId)).not.toBeNull();
+
+    const removed = registry.revoke(cred.credentialId);
+    expect(removed).toBe(true);
+    expect(registry.resolve(cred.credentialId)).toBeNull();
+  });
+
+  it("returns false when revoking a non-existent credential", () => {
+    const registry = new CredentialRegistry();
+    expect(registry.revoke("nonexistent")).toBe(false);
+  });
+
+  it("listForUser returns credentials for that user", async () => {
+    const issuer = await makeIssuer();
+    const cred1 = await makeCred(issuer, "alice");
+    const cred2 = await makeCred(issuer, "bob");
+    const registry = new CredentialRegistry();
+
+    registry.registerTrusted(cred1);
+    registry.registerTrusted(cred2);
+
+    const aliceList = registry.listForUser("alice");
+    expect(aliceList).toHaveLength(1);
+    expect(aliceList[0].userId).toBe("alice");
+  });
+
+  it("evicts expired credentials", async () => {
+    const issuer = await makeIssuer();
+    const expired = await issueHumanCredential("user-exp", [ArohaRole.HumanUser], issuer.did, issuer.priv, -1000);
+    const registry = new CredentialRegistry();
+    registry.registerTrusted(expired);
+
+    const count = registry.evictExpired();
+    expect(count).toBe(1);
+    expect(registry.size).toBe(0);
+  });
+
+  it("returns null on resolve of expired credential (auto-evict)", async () => {
+    const issuer = await makeIssuer();
+    const expired = await issueHumanCredential("user-exp", [ArohaRole.HumanUser], issuer.did, issuer.priv, -1000);
+    const registry = new CredentialRegistry();
+    registry.registerTrusted(expired);
+
+    expect(registry.resolve(expired.credentialId)).toBeNull();
+    expect(registry.size).toBe(0);
+  });
+});
+
+describe("buildRevokeProof / verifyRevokeProof", () => {
+  it("builds a proof that verifies", async () => {
+    const issuer = await makeIssuer();
+    const proof = await buildRevokeProof("cred-123", issuer.priv);
+    const valid = await verifyRevokeProof("cred-123", proof, issuer.pub);
+    expect(valid).toBe(true);
+  });
+
+  it("fails verification with wrong public key", async () => {
+    const issuer = await makeIssuer();
+    const other = await makeIssuer();
+    const proof = await buildRevokeProof("cred-456", issuer.priv);
+    const valid = await verifyRevokeProof("cred-456", proof, other.pub);
+    expect(valid).toBe(false);
+  });
+
+  it("fails verification with different credentialId", async () => {
+    const issuer = await makeIssuer();
+    const proof = await buildRevokeProof("cred-A", issuer.priv);
+    const valid = await verifyRevokeProof("cred-B", proof, issuer.pub);
+    expect(valid).toBe(false);
+  });
+});
+
+import type { HumanCredential } from "./types.js";
+
+describe("CredentialStore interface", () => {
+  it("MapCredentialStore is exported and usable", async () => {
+    const { MapCredentialStore } = await import("./registry.js");
+    const store = new MapCredentialStore();
+    const cred: HumanCredential = {
+      credentialId: "test-id",
+      userId: "user-1",
+      roles: [ArohaRole.HumanUser],
+      issuedAt: new Date().toISOString(),
+      expiresAt: new Date(Date.now() + 3600_000).toISOString(),
+      issuerDID: "did:aroha:issuer",
+      signature: "dummy",
+    };
+    await store.set(cred.credentialId, cred);
+    expect(await store.get(cred.credentialId)).toEqual(cred);
+    await store.delete(cred.credentialId);
+    expect(await store.get(cred.credentialId)).toBeUndefined();
+  });
+
+  it("CredentialRegistry accepts a custom store", async () => {
+    const { MapCredentialStore, CredentialRegistry } = await import("./registry.js");
+    const store = new MapCredentialStore();
+    const reg = new CredentialRegistry(store);
+    const cred: HumanCredential = {
+      credentialId: "custom-store-id",
+      userId: "user-2",
+      roles: [ArohaRole.HumanUser],
+      issuedAt: new Date().toISOString(),
+      expiresAt: new Date(Date.now() + 3600_000).toISOString(),
+      issuerDID: "did:aroha:issuer",
+      signature: "dummy",
+    };
+    reg.registerTrusted(cred);
+    expect(reg.resolve("custom-store-id")).toEqual(cred);
+  });
+});

package/src/registry.ts

@@ -0,0 +1,259 @@
+/**
+ * Aroha Protocol — Human Credential Registry
+ *
+ * Stores signed HumanCredentials so that any agent in the network can
+ * verify a human user's identity and roles by credential ID, without
+ * requiring the full credential token to be re-sent on every message.
+ *
+ * Flow:
+ *   1. Personal Agent issues a HumanCredential (issueHumanCredential)
+ *   2. Personal Agent registers it in the registry  (CredentialRegistry.register)
+ *   3. Human sends a Aroha message with credentialId in the body
+ *   4. Provider agent looks up the credential (CredentialRegistry.resolve)
+ *   5. Provider verifies the stored credential's signature and checks roles
+ *
+ * The registry is exposed as HTTP endpoints by ArohaServer when
+ * ArohaServerOptions.credentialRegistry is set:
+ *
+ *   POST   /aroha/credentials          — register (verifies sig before storing)
+ *   GET    /aroha/credentials/:id      — resolve by ID (public)
+ *   DELETE /aroha/credentials/:id      — revoke (requires issuer proof header)
+ *
+ * Remote agents use CredentialRegistryClient to call these endpoints.
+ */
+
+import * as ed from "@noble/ed25519";
+import { sha512 } from "@noble/hashes/sha512";
+import { type HumanCredential } from "./types.js";
+import { verifyHumanCredential } from "./credentials.js";
+
+ed.etc.sha512Sync = (...m: Parameters<typeof sha512>) => sha512(...m);
+
+// ─── CredentialStore interface ────────────────────────────────────────────────
+
+export interface CredentialStore {
+  set(id: string, credential: HumanCredential): Promise<void> | void;
+  get(id: string): Promise<HumanCredential | undefined> | HumanCredential | undefined;
+  delete(id: string): Promise<boolean> | boolean;
+  values(): AsyncIterable<HumanCredential> | Iterable<HumanCredential>;
+}
+
+// ─── Default in-process store ─────────────────────────────────────────────────
+
+export class MapCredentialStore implements CredentialStore {
+  private readonly store = new Map<string, HumanCredential>();
+
+  set(id: string, credential: HumanCredential): void {
+    this.store.set(id, credential);
+  }
+
+  get(id: string): HumanCredential | undefined {
+    return this.store.get(id);
+  }
+
+  delete(id: string): boolean {
+    return this.store.delete(id);
+  }
+
+  values(): Iterable<HumanCredential> {
+    return this.store.values();
+  }
+
+  get size(): number { return this.store.size; }
+}
+
+// ─── Registry ─────────────────────────────────────────────────────────────────
+
+export class CredentialRegistry {
+  private readonly store: CredentialStore;
+
+  constructor(store: CredentialStore = new MapCredentialStore()) {
+    this.store = store;
+  }
+
+  /**
+   * Register a credential after verifying its Ed25519 signature.
+   *
+   * @param credential     The credential to store
+   * @param issuerPublicKey  Ed25519 public key of credential.issuerDID (32 bytes)
+   * @returns `true` if stored successfully, `false` if signature is invalid
+   */
+  async register(credential: HumanCredential, issuerPublicKey: Uint8Array): Promise<boolean> {
+    const { serializeCredential } = await import("./credentials.js");
+    const token = serializeCredential(credential);
+    const result = await verifyHumanCredential(token, issuerPublicKey);
+    if (!result.valid) return false;
+    await this.store.set(credential.credentialId, credential);
+    return true;
+  }
+
+  /**
+   * Register a credential that has already been verified.
+   * Use this when the calling code has already confirmed validity
+   * (e.g., the issuing agent registering its own credential).
+   */
+  registerTrusted(credential: HumanCredential): void {
+    this.store.set(credential.credentialId, credential);
+  }
+
+  /**
+   * Resolve a credential by ID.
+   * Returns null if not found, or if the credential has expired (auto-evicts).
+   */
+  resolve(credentialId: string): HumanCredential | null {
+    const cred = this.store.get(credentialId);
+    if (!cred) return null;
+    if (cred instanceof Promise) return null; // async store: use async resolveAsync instead
+    const credTyped = cred as HumanCredential;
+    if (new Date(credTyped.expiresAt) < new Date()) {
+      this.store.delete(credentialId); // evict expired
+      return null;
+    }
+    return credTyped;
+  }
+
+  /**
+   * Revoke a credential by ID.
+   * @returns `true` if it existed and was removed, `false` if not found
+   */
+  revoke(credentialId: string): boolean {
+    const result = this.store.delete(credentialId);
+    if (result instanceof Promise) return false;
+    return result as boolean;
+  }
+
+  /**
+   * List all active (non-expired) credentials for a given userId.
+   */
+  listForUser(userId: string): HumanCredential[] {
+    const now = new Date();
+    const results: HumanCredential[] = [];
+    const vals = this.store.values();
+    for (const cred of vals as Iterable<HumanCredential>) {
+      if (cred.userId === userId && new Date(cred.expiresAt) >= now) {
+        results.push(cred);
+      }
+    }
+    return results;
+  }
+
+  /** Total number of stored credentials (including potentially expired ones). */
+  get size(): number {
+    const s = this.store as MapCredentialStore;
+    return s.size ?? 0;
+  }
+
+  /**
+   * Evict all expired credentials. Called periodically to free memory.
+   * Returns the number of credentials evicted.
+   */
+  evictExpired(): number {
+    const now = new Date();
+    let count = 0;
+    const vals = this.store.values();
+    for (const cred of vals as Iterable<HumanCredential>) {
+      if (new Date(cred.expiresAt) < now) {
+        this.store.delete(cred.credentialId);
+        count++;
+      }
+    }
+    return count;
+  }
+}
+
+// ─── HTTP Client ───────────────────────────────────────────────────────────────
+
+/**
+ * HTTP client for remote credential registry lookups.
+ *
+ * Any agent can use this to query the registry hosted by a Personal Agent
+ * (or any ArohaServer with credentialRegistry configured).
+ */
+export class CredentialRegistryClient {
+  constructor(private readonly baseUrl: string) {}
+
+  /**
+   * Register a credential in the remote registry.
+   * The registry will verify the credential's signature before storing.
+   */
+  async register(credential: HumanCredential): Promise<{ ok: boolean; reason?: string }> {
+    const res = await fetch(`${this.baseUrl}/aroha/credentials`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(credential),
+    });
+    if (res.ok) return { ok: true };
+    const body = await res.json().catch(() => ({})) as Record<string, unknown>;
+    return { ok: false, reason: String(body.error ?? res.statusText) };
+  }
+
+  /**
+   * Resolve a credential by ID from the remote registry.
+   * Returns null if not found or expired.
+   */
+  async resolve(credentialId: string): Promise<HumanCredential | null> {
+    const res = await fetch(`${this.baseUrl}/aroha/credentials/${encodeURIComponent(credentialId)}`);
+    if (!res.ok) return null;
+    return res.json() as Promise<HumanCredential>;
+  }
+
+  /**
+   * Revoke a credential.
+   *
+   * The caller must provide a revocation proof: a base64url Ed25519 signature
+   * over `{credentialId, action:"revoke"}` using the issuer's private key.
+   * This is checked server-side before deletion.
+   */
+  async revoke(credentialId: string, revokeProof: string): Promise<{ ok: boolean; reason?: string }> {
+    const res = await fetch(`${this.baseUrl}/aroha/credentials/${encodeURIComponent(credentialId)}`, {
+      method: "DELETE",
+      headers: { "X-Revoke-Proof": revokeProof },
+    });
+    if (res.ok) return { ok: true };
+    const body = await res.json().catch(() => ({})) as Record<string, unknown>;
+    return { ok: false, reason: String(body.error ?? res.statusText) };
+  }
+
+  /**
+   * List all active credentials for a userId.
+   */
+  async listForUser(userId: string): Promise<HumanCredential[]> {
+    const res = await fetch(`${this.baseUrl}/aroha/credentials?userId=${encodeURIComponent(userId)}`);
+    if (!res.ok) return [];
+    return res.json() as Promise<HumanCredential[]>;
+  }
+}
+
+// ─── Revoke proof helpers ──────────────────────────────────────────────────────
+
+/**
+ * Build a revocation proof to pass to CredentialRegistryClient.revoke().
+ * Signs `{action:"revoke",credentialId}` with the issuer's private key.
+ */
+export async function buildRevokeProof(
+  credentialId: string,
+  issuerPrivateKey: Uint8Array
+): Promise<string> {
+  const payload = JSON.stringify({ action: "revoke", credentialId });
+  const bytes = new TextEncoder().encode(payload);
+  const sig = await ed.signAsync(bytes, issuerPrivateKey);
+  return Buffer.from(sig).toString("base64url");
+}
+
+/**
+ * Verify a revocation proof server-side.
+ */
+export async function verifyRevokeProof(
+  credentialId: string,
+  proof: string,
+  issuerPublicKey: Uint8Array
+): Promise<boolean> {
+  try {
+    const payload = JSON.stringify({ action: "revoke", credentialId });
+    const bytes = new TextEncoder().encode(payload);
+    const sig = Buffer.from(proof, "base64url");
+    return await ed.verifyAsync(sig, bytes, issuerPublicKey);
+  } catch {
+    return false;
+  }
+}

package/src/types.ts

@@ -0,0 +1,19 @@
+export enum ArohaRole {
+  HumanAdmin        = "human:admin",
+  HumanUser         = "human:user",
+  HumanReadonly     = "human:readonly",
+  AgentOrchestrator = "agent:orchestrator",
+  AgentProvider     = "agent:provider",
+  AgentObserver     = "agent:observer",
+}
+
+export interface HumanCredential {
+  credentialId: string;
+  userId: string;
+  email?: string;
+  roles: ArohaRole[];
+  issuedAt: string;
+  expiresAt: string;
+  issuerDID: string;
+  signature: string;
+}

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "composite": true
+  },
+  "references": [
+    { "path": "../../packages/aroha-core" }
+  ],
+  "include": ["src/**/*"]
+}