@aroha-sdk/core 1.0.0

package/src/crypto/encryption.ts

@@ -0,0 +1,160 @@
+/**
+ * Aroha Protocol — Layer 3 Encryption
+ *
+ * Implements the spec rule:
+ *   "For sensitive body fields, senders SHOULD encrypt using DIDComm v2 JWE
+ *    with the recipient's public key."
+ *
+ * Uses X25519 ECDH for key agreement + AES-256-GCM for content encryption.
+ * This is a protocol-level primitive. It does not know what is being encrypted
+ * or why — that is the application's concern.
+ */
+
+import { x25519, edwardsToMontgomeryPub, edwardsToMontgomeryPriv } from "@noble/curves/ed25519";
+import { randomBytes, concatBytes } from "@noble/hashes/utils";
+import { sha256 } from "@noble/hashes/sha256";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface EncryptedBody {
+  /** Algorithm identifier */
+  alg: "ECDH-ES+A256GCM";
+  /** Base64url-encoded ephemeral X25519 public key */
+  epk: string;
+  /** Base64url-encoded IV (12 bytes for AES-GCM) */
+  iv: string;
+  /** Base64url-encoded ciphertext */
+  ciphertext: string;
+  /** Base64url-encoded AES-GCM authentication tag (16 bytes) */
+  tag: string;
+}
+
+// ─── Encrypt ──────────────────────────────────────────────────────────────────
+
+/**
+ * Encrypt a message body for a specific recipient.
+ *
+ * @param plaintext        The body object to encrypt (will be JSON-serialized)
+ * @param recipientPubKey  Recipient's Ed25519 public key (32 bytes).
+ *                         We convert it to X25519 for ECDH.
+ */
+export async function encryptBody(
+  plaintext: Record<string, unknown>,
+  recipientPubKey: Uint8Array
+): Promise<EncryptedBody> {
+  // Convert Ed25519 pubkey to X25519 for key exchange
+  const recipientX25519 = ed25519PubKeyToX25519(recipientPubKey);
+
+  // Generate ephemeral X25519 keypair
+  const ephemeralPriv = x25519.utils.randomPrivateKey();
+  const ephemeralPub = x25519.getPublicKey(ephemeralPriv);
+
+  // ECDH shared secret
+  const sharedSecret = x25519.getSharedSecret(ephemeralPriv, recipientX25519);
+
+  // Derive AES-256-GCM key from shared secret via SHA-256
+  const aesKey = sha256(sharedSecret);
+
+  // Encrypt with AES-256-GCM
+  const iv = randomBytes(12);
+  const plaintextBytes = new TextEncoder().encode(JSON.stringify(plaintext));
+  const { ciphertext, tag } = await aesGcmEncrypt(aesKey, iv, plaintextBytes);
+
+  return {
+    alg: "ECDH-ES+A256GCM",
+    epk: Buffer.from(ephemeralPub).toString("base64url"),
+    iv: Buffer.from(iv).toString("base64url"),
+    ciphertext: Buffer.from(ciphertext).toString("base64url"),
+    tag: Buffer.from(tag).toString("base64url"),
+  };
+}
+
+// ─── Decrypt ──────────────────────────────────────────────────────────────────
+
+/**
+ * Decrypt an encrypted message body.
+ *
+ * @param encrypted     The EncryptedBody from the message
+ * @param privateKey    Recipient's Ed25519 private key (32 bytes)
+ */
+export async function decryptBody(
+  encrypted: EncryptedBody,
+  privateKey: Uint8Array
+): Promise<Record<string, unknown>> {
+  // Convert Ed25519 private key to X25519
+  const x25519Priv = ed25519PrivKeyToX25519(privateKey);
+
+  const ephemeralPub = Buffer.from(encrypted.epk, "base64url");
+  const sharedSecret = x25519.getSharedSecret(x25519Priv, ephemeralPub);
+  const aesKey = sha256(sharedSecret);
+
+  const iv = Buffer.from(encrypted.iv, "base64url");
+  const ciphertext = Buffer.from(encrypted.ciphertext, "base64url");
+  const tag = Buffer.from(encrypted.tag, "base64url");
+
+  const plaintext = await aesGcmDecrypt(aesKey, iv, ciphertext, tag);
+  return JSON.parse(new TextDecoder().decode(plaintext));
+}
+
+// ─── Key Conversion ───────────────────────────────────────────────────────────
+// Ed25519 keys can be converted to X25519 (Curve25519) via the birational map
+// between the two curve models. @noble/curves implements the correct conversion.
+
+function ed25519PubKeyToX25519(edPub: Uint8Array): Uint8Array {
+  return edwardsToMontgomeryPub(edPub);
+}
+
+function ed25519PrivKeyToX25519(edPriv: Uint8Array): Uint8Array {
+  return edwardsToMontgomeryPriv(edPriv);
+}
+
+// ─── AES-256-GCM (Web Crypto API) ────────────────────────────────────────────
+
+async function aesGcmEncrypt(
+  key: Uint8Array,
+  iv: Uint8Array,
+  plaintext: Uint8Array
+): Promise<{ ciphertext: Uint8Array; tag: Uint8Array }> {
+  const cryptoKey = await crypto.subtle.importKey(
+    "raw",
+    key,
+    { name: "AES-GCM" },
+    false,
+    ["encrypt"]
+  );
+
+  const encrypted = await crypto.subtle.encrypt(
+    { name: "AES-GCM", iv, tagLength: 128 },
+    cryptoKey,
+    plaintext
+  );
+
+  const buf = new Uint8Array(encrypted);
+  const ciphertext = buf.slice(0, buf.length - 16);
+  const tag = buf.slice(buf.length - 16);
+  return { ciphertext, tag };
+}
+
+async function aesGcmDecrypt(
+  key: Uint8Array,
+  iv: Uint8Array,
+  ciphertext: Uint8Array,
+  tag: Uint8Array
+): Promise<Uint8Array> {
+  const cryptoKey = await crypto.subtle.importKey(
+    "raw",
+    key,
+    { name: "AES-GCM" },
+    false,
+    ["decrypt"]
+  );
+
+  const combined = concatBytes(ciphertext, tag);
+  const decrypted = await crypto.subtle.decrypt(
+    { name: "AES-GCM", iv, tagLength: 128 },
+    cryptoKey,
+    combined
+  );
+
+  return new Uint8Array(decrypted);
+}

package/src/crypto/index.ts

@@ -0,0 +1,2 @@
+export * from "./signing.js";
+export * from "./encryption.js";

package/src/crypto/signing.test.ts

@@ -0,0 +1,79 @@
+import { describe, it, expect } from "vitest";
+import * as ed from "@noble/ed25519";
+import { sha512 } from "@noble/hashes/sha512";
+import { signMessage, verifyMessageSignature, canonicalizeMessage } from "./signing.js";
+
+ed.etc.sha512Sync = (...m: Parameters<typeof sha512>) => sha512(...m);
+
+async function makeKeyPair() {
+  const priv = ed.utils.randomPrivateKey();
+  const pub = await ed.getPublicKeyAsync(priv);
+  return { priv, pub };
+}
+
+describe("canonicalizeMessage", () => {
+  it("excludes the proof field", () => {
+    const msg = { a: 1, proof: { proofValue: "sig" }, b: 2 };
+    const canon = canonicalizeMessage(msg);
+    expect(JSON.parse(canon)).not.toHaveProperty("proof");
+  });
+
+  it("sorts keys lexicographically", () => {
+    const msg = { z: 3, a: 1, m: 2 };
+    const canon = canonicalizeMessage(msg);
+    expect(canon).toBe(JSON.stringify({ a: 1, m: 2, z: 3 }));
+  });
+
+  it("sorts nested object keys", () => {
+    const msg = { outer: { z: 1, a: 2 } };
+    const canon = canonicalizeMessage(msg);
+    expect(JSON.parse(canon).outer).toEqual({ a: 2, z: 1 });
+  });
+
+  it("preserves arrays", () => {
+    const msg = { list: [3, 1, 2] };
+    const canon = canonicalizeMessage(msg);
+    expect(JSON.parse(canon).list).toEqual([3, 1, 2]);
+  });
+});
+
+describe("signMessage / verifyMessageSignature", () => {
+  it("produces a valid signature that verifies", async () => {
+    const { priv, pub } = await makeKeyPair();
+    const msg = { id: "test-msg", body: { hello: "world" } };
+    const proof = await signMessage(msg, priv, "did:aroha:test#key-1");
+
+    expect(proof.type).toBe("Ed25519Signature2020");
+    expect(proof.proofPurpose).toBe("authentication");
+    expect(proof.verificationMethod).toBe("did:aroha:test#key-1");
+    expect(proof.proofValue).toBeTruthy();
+
+    const valid = await verifyMessageSignature({ ...msg, proof }, pub);
+    expect(valid).toBe(true);
+  });
+
+  it("rejects a tampered message", async () => {
+    const { priv, pub } = await makeKeyPair();
+    const msg = { id: "test-msg", body: { hello: "world" } };
+    const proof = await signMessage(msg, priv, "did:aroha:test#key-1");
+
+    const tampered = { id: "TAMPERED", body: { hello: "world" }, proof };
+    const valid = await verifyMessageSignature(tampered, pub);
+    expect(valid).toBe(false);
+  });
+
+  it("rejects a message with wrong public key", async () => {
+    const { priv } = await makeKeyPair();
+    const { pub: wrongPub } = await makeKeyPair();
+    const msg = { id: "test-msg" };
+    const proof = await signMessage(msg, priv, "did:aroha:test#key-1");
+    const valid = await verifyMessageSignature({ ...msg, proof }, wrongPub);
+    expect(valid).toBe(false);
+  });
+
+  it("returns false when proof is missing", async () => {
+    const { pub } = await makeKeyPair();
+    const valid = await verifyMessageSignature({ id: "no-proof" }, pub);
+    expect(valid).toBe(false);
+  });
+});

package/src/crypto/signing.ts

@@ -0,0 +1,104 @@
+/**
+ * Aroha Protocol — Layer 3 Signing
+ *
+ * Implements the signing rule from the spec:
+ *   "The proof.proofValue MUST be the Ed25519 signature over the canonical
+ *    JSON of the message with the proof field omitted, keys sorted
+ *    lexicographically."
+ *
+ * This module is pure protocol infrastructure. It knows nothing about
+ * what the message body contains or what the agent does with it.
+ */
+
+import * as ed from "@noble/ed25519";
+import { sha512 } from "@noble/hashes/sha512";
+
+ed.etc.sha512Sync = (...m: Parameters<typeof sha512>) => sha512(...m);
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface MessageProof {
+  type: "Ed25519Signature2020";
+  created: string;
+  verificationMethod: string; // did:aroha:<id>#key-1
+  proofPurpose: "authentication";
+  proofValue: string; // base64url-encoded Ed25519 signature
+}
+
+// ─── Signing ──────────────────────────────────────────────────────────────────
+
+/**
+ * Sign a Aroha message.
+ * Returns a proof object to embed in the message envelope.
+ *
+ * @param message           Full message object (proof field will be excluded before signing)
+ * @param privateKey        Ed25519 private key (32 bytes)
+ * @param verificationMethodId  e.g. "did:aroha:my-agent#key-1"
+ */
+export async function signMessage(
+  message: Record<string, unknown>,
+  privateKey: Uint8Array,
+  verificationMethodId: string
+): Promise<MessageProof> {
+  const canonical = canonicalizeMessage(message);
+  const bytes = new TextEncoder().encode(canonical);
+  const signature = await ed.signAsync(bytes, privateKey);
+
+  return {
+    type: "Ed25519Signature2020",
+    created: new Date().toISOString(),
+    verificationMethod: verificationMethodId,
+    proofPurpose: "authentication",
+    proofValue: Buffer.from(signature).toString("base64url"),
+  };
+}
+
+/**
+ * Verify a Aroha message signature.
+ *
+ * @param message    Full message object including the proof field
+ * @param publicKey  Ed25519 public key (32 bytes) of the claimed sender
+ * @returns          true if signature is valid, false otherwise
+ */
+export async function verifyMessageSignature(
+  message: Record<string, unknown>,
+  publicKey: Uint8Array
+): Promise<boolean> {
+  const proof = message.proof as MessageProof | undefined;
+  if (!proof?.proofValue) return false;
+
+  const canonical = canonicalizeMessage(message); // excludes proof
+  const bytes = new TextEncoder().encode(canonical);
+
+  try {
+    const signature = Buffer.from(proof.proofValue, "base64url");
+    return await ed.verifyAsync(signature, bytes, publicKey);
+  } catch {
+    return false;
+  }
+}
+
+// ─── Canonicalization ─────────────────────────────────────────────────────────
+
+/**
+ * Produce the canonical JSON string of a message for signing/verification.
+ *
+ * Per spec: exclude the "proof" field, sort all keys lexicographically
+ * at every level of nesting.
+ */
+export function canonicalizeMessage(message: Record<string, unknown>): string {
+  const { proof: _excluded, ...rest } = message;
+  return JSON.stringify(sortKeysDeep(rest));
+}
+
+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/identity/credentials.ts

@@ -0,0 +1,164 @@
+/**
+ * Aroha Verifiable Credentials (VCs)
+ *
+ * Based on W3C Verifiable Credentials Data Model 2.0.
+ * VCs allow agents to prove claims about themselves (corporate identity,
+ * compliance certifications, capability authorization) without revealing
+ * more than necessary (selective disclosure via ZKP proofs).
+ *
+ * Issuance flow:
+ *   Trust Anchor (e.g. Expedia Corp) issues a VC to its agent.
+ *   The VC is signed with the issuer's private key.
+ *   The agent presents the VC during negotiation.
+ *   The counterpart verifies the VC signature.
+ */
+
+import * as ed from "@noble/ed25519";
+import { sha512 } from "@noble/hashes/sha512";
+import { v4 as uuidv4 } from "uuid";
+
+ed.etc.sha512Sync = (...m: Parameters<typeof sha512>) => sha512(...m);
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export type TrustLevel = 0 | 1 | 2 | 3 | 4;
+
+export const TRUST_LEVEL_DESCRIPTIONS: Record<TrustLevel, string> = {
+  0: "Public — read capability manifests only",
+  1: "Registered — on-chain registration + stake",
+  2: "Verified — VC from recognized trust anchor",
+  3: "Reputable — reputation score >= 0.8",
+  4: "User-trusted — explicit user authorization",
+};
+
+export interface CredentialSubject {
+  id: string; // DID of the subject (the agent being described)
+  [key: string]: unknown;
+}
+
+export interface VerifiableCredential {
+  "@context": string[];
+  id: string;
+  type: string[];
+  issuer: string; // DID of the issuer (e.g. did:aroha:expedia-corp)
+  issuanceDate: string;
+  expirationDate?: string;
+  credentialSubject: CredentialSubject;
+  proof?: VCProof;
+}
+
+export interface VCProof {
+  type: "Ed25519Signature2020";
+  created: string;
+  verificationMethod: string; // issuer DID + key fragment
+  proofPurpose: "assertionMethod";
+  proofValue: string; // base64url-encoded signature
+}
+
+// ─── Standard Aroha credential types ──────────────────────────────────────────
+
+/** Issued by a company to vouch that an agent is operated by them. */
+export interface CorporateIdentityCredential extends VerifiableCredential {
+  credentialSubject: {
+    id: string;
+    companyName: string;
+    companyDomain: string;
+    registeredCountry: string;
+  };
+}
+
+/** Issued by a compliance body (e.g. PCI-DSS, HIPAA auditor). */
+export interface ComplianceCertificationCredential extends VerifiableCredential {
+  credentialSubject: {
+    id: string;
+    standard: string; // "PCI-DSS-L1" | "HIPAA" | "SOC2-T2" | ...
+    certifiedUntil: string;
+    scope: string;
+  };
+}
+
+/** Issued by a platform operator to authorize an agent to act. */
+export interface CapabilityAuthorizationCredential extends VerifiableCredential {
+  credentialSubject: {
+    id: string;
+    authorizedCapabilities: string[];
+    maxTransactionValue?: { amount: number; currency: string };
+  };
+}
+
+// ─── Issue / Verify ───────────────────────────────────────────────────────────
+
+/**
+ * Issue a Verifiable Credential.
+ * The issuer signs the credential's canonical JSON with their Ed25519 key.
+ */
+export async function issueCredential(
+  credential: Omit<VerifiableCredential, "proof" | "id">,
+  issuerPrivateKey: Uint8Array,
+  issuerKeyId: string
+): Promise<VerifiableCredential> {
+  const id = `urn:uuid:${uuidv4()}`;
+  const unsigned: VerifiableCredential = { ...credential, id };
+
+  const payload = JSON.stringify(canonicalize(unsigned));
+  const payloadBytes = new TextEncoder().encode(payload);
+
+  const signature = await ed.signAsync(payloadBytes, issuerPrivateKey);
+  const proofValue = Buffer.from(signature).toString("base64url");
+
+  const proof: VCProof = {
+    type: "Ed25519Signature2020",
+    created: new Date().toISOString(),
+    verificationMethod: issuerKeyId,
+    proofPurpose: "assertionMethod",
+    proofValue,
+  };
+
+  return { ...unsigned, proof };
+}
+
+/**
+ * Verify a Verifiable Credential's signature.
+ * Returns true if the signature is valid.
+ */
+export async function verifyCredential(
+  credential: VerifiableCredential,
+  issuerPublicKey: Uint8Array
+): Promise<boolean> {
+  if (!credential.proof) return false;
+
+  const { proof, ...unsigned } = credential;
+  const payload = JSON.stringify(canonicalize(unsigned as VerifiableCredential));
+  const payloadBytes = new TextEncoder().encode(payload);
+
+  const signature = Buffer.from(proof.proofValue, "base64url");
+  return ed.verifyAsync(signature, payloadBytes, issuerPublicKey);
+}
+
+/**
+ * Check if a credential is expired.
+ */
+export function isCredentialExpired(credential: VerifiableCredential): boolean {
+  if (!credential.expirationDate) return false;
+  return new Date(credential.expirationDate) < new Date();
+}
+
+// ─── Deterministic JSON (canonical form for signing) ──────────────────────────
+
+function canonicalize(obj: unknown): unknown {
+  if (Array.isArray(obj)) return obj.map(canonicalize);
+  if (obj !== null && typeof obj === "object") {
+    return Object.keys(obj as object)
+      .sort()
+      .reduce(
+        (acc, key) => {
+          (acc as Record<string, unknown>)[key] = canonicalize(
+            (obj as Record<string, unknown>)[key]
+          );
+          return acc;
+        },
+        {} as Record<string, unknown>
+      );
+  }
+  return obj;
+}

package/src/identity/did-cache.ts

@@ -0,0 +1,113 @@
+/**
+ * DID Resolution Cache
+ *
+ * Wraps any PublicKeyResolver with an in-memory cache.
+ *
+ * Cache strategy by DID method:
+ *   did:aroha:       Permanent — the public key IS the DID (base58 of key bytes).
+ *                    The key can never change without changing the DID itself.
+ *   did:aroha-web:   TTL-based — keys rotate with a 24-hour cooldown per spec.
+ *                    Default TTL: 23h to stay just inside the rotation window.
+ *   Other methods:   TTL-based with configurable default.
+ *
+ * At 1000 messages/second resolving 20 known agents, this eliminates
+ * ~50,000 redundant base58 decodes and ~1,000 DNS+HTTPS fetches per second.
+ */
+
+export interface DidCacheConfig {
+  /** TTL for did:aroha-web: entries in ms. Default: 82_800_000 (23 hours) */
+  webDidTtlMs?: number;
+  /** TTL for unknown DID methods. Default: 300_000 (5 minutes) */
+  defaultTtlMs?: number;
+  /** Maximum number of entries before LRU eviction. Default: 1000 */
+  maxSize?: number;
+}
+
+export type PublicKeyResolver = (senderDID: string) => Promise<Uint8Array | null>;
+
+interface CacheEntry {
+  key: Uint8Array | null;
+  expiresAt: number; // Infinity for permanent entries
+  lastUsed: number;
+}
+
+export class DidResolutionCache {
+  private readonly webDidTtlMs: number;
+  private readonly defaultTtlMs: number;
+  private readonly maxSize: number;
+  private readonly cache = new Map<string, CacheEntry>();
+
+  constructor(config: DidCacheConfig = {}) {
+    this.webDidTtlMs  = config.webDidTtlMs  ?? 82_800_000; // 23h
+    this.defaultTtlMs = config.defaultTtlMs ?? 300_000;    // 5m
+    this.maxSize      = config.maxSize      ?? 1_000;
+  }
+
+  /**
+   * Wrap a resolver function with cache semantics.
+   * The returned resolver is a drop-in replacement.
+   */
+  wrap(resolver: PublicKeyResolver): PublicKeyResolver {
+    return async (did: string): Promise<Uint8Array | null> => {
+      const cached = this.get(did);
+      if (cached !== undefined) return cached;
+
+      const key = await resolver(did);
+      this.set(did, key);
+      return key;
+    };
+  }
+
+  /** Manually populate the cache (e.g. from known agent registry). */
+  set(did: string, key: Uint8Array | null): void {
+    if (this.cache.size >= this.maxSize) this.evictLru();
+
+    const ttl = this.ttlFor(did);
+    this.cache.set(did, {
+      key,
+      expiresAt: ttl === Infinity ? Infinity : Date.now() + ttl,
+      lastUsed: Date.now(),
+    });
+  }
+
+  /** Returns undefined on cache miss or expiry. */
+  get(did: string): Uint8Array | null | undefined {
+    const entry = this.cache.get(did);
+    if (!entry) return undefined;
+    if (entry.expiresAt !== Infinity && Date.now() > entry.expiresAt) {
+      this.cache.delete(did);
+      return undefined;
+    }
+    entry.lastUsed = Date.now();
+    return entry.key;
+  }
+
+  /** Invalidate a specific DID (e.g. after a key rotation event). */
+  invalidate(did: string): void {
+    this.cache.delete(did);
+  }
+
+  get size(): number {
+    return this.cache.size;
+  }
+
+  private ttlFor(did: string): number {
+    if (did.startsWith("did:aroha:") && !did.startsWith("did:aroha-web:")) {
+      return Infinity; // key is encoded in the DID itself — never rotates
+    }
+    if (did.startsWith("did:aroha-web:")) {
+      return this.webDidTtlMs;
+    }
+    return this.defaultTtlMs;
+  }
+
+  private evictLru(): void {
+    let oldest: [string, CacheEntry] | null = null;
+    for (const entry of this.cache.entries()) {
+      if (!oldest || entry[1].lastUsed < oldest[1].lastUsed) {
+        oldest = entry;
+      }
+    }
+    if (oldest) this.cache.delete(oldest[0]);
+  }
+}