@aroha-sdk/core 1.0.0

package/src/identity/did.test.ts

@@ -0,0 +1,232 @@
+import { describe, it, expect } from "vitest";
+import {
+  generateDID,
+  rotateDIDKey,
+  revokeKey,
+  verifyRevocation,
+  buildDIDDocument,
+  extractPublicKey,
+  extractEndpoint,
+  extractNamespace,
+  toMultibase,
+  fromMultibase,
+} from "./did.js";
+
+describe("toMultibase / fromMultibase", () => {
+  it("round-trips a Uint8Array", () => {
+    const bytes = new Uint8Array(32).fill(42);
+    const encoded = toMultibase(bytes);
+    expect(encoded).toMatch(/^z/);
+    const decoded = fromMultibase(encoded);
+    expect(decoded).toEqual(bytes);
+  });
+
+  it("throws on non-base58btc multibase prefix", () => {
+    expect(() => fromMultibase("mSomeBase64")).toThrow("Only base58btc");
+  });
+});
+
+describe("generateDID", () => {
+  it("produces a DID with the expected format", async () => {
+    const kp = await generateDID("test-agent", "https://example.com/aroha");
+    expect(kp.did).toBe("did:aroha:test-agent");
+    expect(kp.privateKey).toHaveLength(32);
+    expect(kp.publicKey).toHaveLength(32);
+  });
+
+  it("embeds the endpoint in the DID document service", async () => {
+    const kp = await generateDID("my-agent", "https://agent.example.com");
+    const endpoint = extractEndpoint(kp.document);
+    expect(endpoint).toBe("https://agent.example.com");
+  });
+
+  it("embeds the public key in the verification method", async () => {
+    const kp = await generateDID("key-agent", "https://example.com");
+    const extracted = extractPublicKey(kp.document);
+    expect(extracted).toEqual(kp.publicKey);
+  });
+
+  it("sets @context, authentication, assertionMethod, keyAgreement", async () => {
+    const kp = await generateDID("ctx-agent", "https://example.com");
+    const doc = kp.document;
+    expect(doc["@context"]).toContain("https://www.w3.org/ns/did/v1");
+    expect(doc.authentication).toContain(`${kp.did}#key-1`);
+    expect(doc.assertionMethod).toContain(`${kp.did}#key-1`);
+    expect(doc.keyAgreement).toContain(`${kp.did}#key-1`);
+  });
+});
+
+describe("buildDIDDocument", () => {
+  it("reconstructs a document from an existing key", async () => {
+    const original = await generateDID("rebuild-agent", "https://example.com");
+    const doc = buildDIDDocument(
+      "rebuild-agent",
+      original.publicKey,
+      "https://example.com",
+      original.document.created
+    );
+    expect(doc.id).toBe("did:aroha:rebuild-agent");
+    expect(extractPublicKey(doc)).toEqual(original.publicKey);
+  });
+});
+
+describe("extractPublicKey / extractEndpoint", () => {
+  it("throws when there are no verification methods", () => {
+    const doc = {
+      "@context": [],
+      id: "did:aroha:empty",
+      verificationMethod: [],
+      authentication: [],
+      assertionMethod: [],
+      keyAgreement: [],
+      service: [],
+      created: "",
+      updated: "",
+    };
+    expect(() => extractPublicKey(doc)).toThrow("no verification methods");
+  });
+
+  it("throws when there is no ArohaEndpoint service", async () => {
+    const kp = await generateDID("no-svc", "https://example.com");
+    const doc = { ...kp.document, service: [] };
+    expect(() => extractEndpoint(doc)).toThrow("no ArohaEndpoint service");
+  });
+});
+
+describe("rotateDIDKey", () => {
+  it("returns a new keypair with a different public key", async () => {
+    const original = await generateDID("my-agent", "https://example.com");
+    const rotated = await rotateDIDKey(original);
+    expect(Buffer.from(rotated.publicKey).toString("hex"))
+      .not.toBe(Buffer.from(original.publicKey).toString("hex"));
+  });
+
+  it("adds a keyHistory entry signed by the predecessor", async () => {
+    const original = await generateDID("my-agent", "https://example.com");
+    const rotated = await rotateDIDKey(original);
+    expect(rotated.document.keyHistory).toHaveLength(1);
+    const record = rotated.document.keyHistory![0];
+    expect(record.rotatedAt).toBeTruthy();
+    expect(record.predecessorSignature).toBeTruthy();
+  });
+
+  it("rotation record has valid predecessor signature", async () => {
+    const { verifyKeyRotation } = await import("./web-did.js");
+    const original = await generateDID("my-agent", "https://example.com");
+    const rotated = await rotateDIDKey(original);
+    const record = rotated.document.keyHistory![0];
+    expect(await verifyKeyRotation(record)).toBe(true);
+  });
+
+  it("extractPublicKey returns the new key after rotation (past cool-down)", async () => {
+    const original = await generateDID("my-agent", "https://example.com");
+    const rotated = await rotateDIDKey(original, 0); // 0-hour cool-down for test
+    const extracted = extractPublicKey(rotated.document);
+    expect(Buffer.from(extracted).toString("hex"))
+      .toBe(Buffer.from(rotated.publicKey).toString("hex"));
+  });
+
+  it("extractPublicKey throws during cool-down window", async () => {
+    const original = await generateDID("my-agent", "https://example.com");
+    const rotated = await rotateDIDKey(original, 24); // 24-hour cool-down
+    expect(() => extractPublicKey(rotated.document)).toThrow(/cool-down/i);
+  });
+});
+
+import { generateWebAgent, rotateKey, verifyKeyRotation } from "./web-did.js";
+
+describe("resolveWebDID — rotation chain verification", () => {
+  it("verifyKeyRotation returns true for a valid rotation", async () => {
+    const agent = await generateWebAgent("example.com", "test-agent");
+    const rotated = await rotateKey(agent);
+    const record = rotated.webDocument.arohaWeb.keyHistory[0];
+    expect(await verifyKeyRotation(record)).toBe(true);
+  });
+
+  it("verifyKeyRotation returns false for a tampered rotation record", async () => {
+    const agent = await generateWebAgent("example.com", "test-agent");
+    const rotated = await rotateKey(agent);
+    const record = { ...rotated.webDocument.arohaWeb.keyHistory[0] };
+    // Tamper with the signature
+    record.predecessorSignature = "invalidsignature";
+    expect(await verifyKeyRotation(record)).toBe(false);
+  });
+});
+
+describe("Emergency key revocation", () => {
+  it("revokeKey adds revokedKeys entry to DID document", async () => {
+    const agent = await generateDID("revoke-test", "http://localhost");
+    const revoked = await revokeKey(agent, "Compromised — emergency revocation");
+    expect(revoked.document.revokedKeys).toHaveLength(1);
+    expect(revoked.document.revokedKeys![0].reason).toBe("Compromised — emergency revocation");
+    expect(revoked.document.revokedKeys![0].keyMultibase).toBe(
+      agent.document.verificationMethod[0].publicKeyMultibase
+    );
+  });
+
+  it("extractPublicKey throws when current key is in revokedKeys", async () => {
+    const agent = await generateDID("revoke-test-2", "http://localhost");
+    // Simulate a document where the active verificationMethod key is itself listed as revoked
+    const currentKeyMultibase = agent.document.verificationMethod[0].publicKeyMultibase;
+    const docWithRevokedCurrentKey = {
+      ...agent.document,
+      revokedKeys: [
+        {
+          keyMultibase: currentKeyMultibase,
+          revokedAt: new Date().toISOString(),
+          reason: "stolen",
+        },
+      ],
+    };
+    expect(() => extractPublicKey(docWithRevokedCurrentKey)).toThrow(/revoked/);
+  });
+
+  it("revokeKey rotates to a new keypair immediately (no cooldown)", async () => {
+    const agent = await generateDID("revoke-test-3", "http://localhost");
+    const revoked = await revokeKey(agent, "stolen");
+    // New key should be immediately trusted — no cooldown
+    const newPubKey = extractPublicKey(revoked.document);
+    expect(newPubKey).not.toEqual(agent.publicKey);
+  });
+
+  it("revokeKey signs the revocation with the old key", async () => {
+    const agent = await generateDID("revoke-test-4", "http://localhost");
+    const revoked = await revokeKey(agent, "test");
+    expect(revoked.document.revokedKeys![0].selfSignature).toBeDefined();
+    expect(revoked.document.revokedKeys![0].selfSignature!.length).toBeGreaterThan(0);
+  });
+
+  it("selfSignature is cryptographically valid — verifyRevocation returns true", async () => {
+    const agent = await generateDID("revoke-verify-test", "http://localhost");
+    const revoked = await revokeKey(agent, "testing verification");
+    const record = revoked.document.revokedKeys![0];
+    const isValid = await verifyRevocation(record, agent.publicKey);
+    expect(isValid).toBe(true);
+  });
+});
+
+describe("DID namespacing", () => {
+  it("generateDID with namespace produces did:aroha:namespace.agentId", async () => {
+    const agent = await generateDID("invoice-processor", "http://localhost", { namespace: "acme-corp" });
+    expect(agent.did).toBe("did:aroha:acme-corp.invoice-processor");
+    expect(agent.document.id).toBe("did:aroha:acme-corp.invoice-processor");
+  });
+
+  it("generateDID without namespace is unchanged (backwards compat)", async () => {
+    const agent = await generateDID("invoice-processor", "http://localhost");
+    expect(agent.did).toBe("did:aroha:invoice-processor");
+  });
+
+  it("generateDID throws on invalid namespace", async () => {
+    await expect(generateDID("agent", "http://localhost", { namespace: "UPPER_CASE" }))
+      .rejects.toThrow(/Invalid namespace/);
+  });
+
+  it("extractNamespace returns null for un-namespaced DID", () => {
+    expect(extractNamespace("did:aroha:flight-agent")).toBeNull();
+  });
+
+  it("extractNamespace returns the namespace for namespaced DID", () => {
+    expect(extractNamespace("did:aroha:acme-corp.invoice-processor")).toBe("acme-corp");
+  });
+});

package/src/identity/did.ts

@@ -0,0 +1,426 @@
+/**
+ * Aroha DID (Decentralized Identifier) implementation.
+ *
+ * DID format:  did:aroha:<unique-id>
+ * Spec:        W3C DID Core 1.0 (https://www.w3.org/TR/did-core/)
+ *
+ * A DID Document contains:
+ *   - Verification methods (public keys)
+ *   - Authentication references
+ *   - Service endpoints (Aroha agent endpoint)
+ */
+
+import * as ed from "@noble/ed25519";
+import { sha256 } from "@noble/hashes/sha256";
+import { sha512 } from "@noble/hashes/sha512";
+import { bytesToHex, randomBytes } from "@noble/hashes/utils";
+
+// noble/ed25519 v2 requires sha512 sync
+ed.etc.sha512Sync = (...m: Parameters<typeof sha512>) => sha512(...m);
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface VerificationMethod {
+  id: string;
+  type: "Ed25519VerificationKey2020";
+  controller: string;
+  /** Base58-encoded public key with multibase prefix 'z' */
+  publicKeyMultibase: string;
+}
+
+export interface ServiceEndpoint {
+  id: string;
+  type: "ArohaEndpoint";
+  serviceEndpoint: string;
+}
+
+export interface KeyRotationRecord {
+  /** ISO8601 — when the rotation was announced. */
+  rotatedAt: string;
+  /** ISO8601 — earliest time the new key becomes trusted (rotatedAt + coolDownHours). */
+  trustAfter: string;
+  /** Multibase pubkey of the replaced (predecessor) key. */
+  predecessorKey: string;
+  /** SHA-256 hex of the new key. */
+  newKeyHash: string;
+  /**
+   * Ed25519 signature over `predecessorKey || newKeyHash || rotatedAt`,
+   * signed by the predecessor key. Proves voluntary key rotation.
+   */
+  predecessorSignature: string;
+}
+
+export interface RevokedKeyRecord {
+  /** Multibase public key that was revoked. */
+  keyMultibase: string;
+  /** ISO8601 — when revocation was announced. */
+  revokedAt: string;
+  /** Human-readable reason (e.g. "Compromised — see incident #42"). */
+  reason: string;
+  /**
+   * Ed25519 signature over `keyMultibase || revokedAt || reason`
+   * signed by the key being revoked. Proves intentional revocation.
+   */
+  selfSignature?: string;
+}
+
+export interface DIDDocument {
+  "@context": string[];
+  id: string;
+  verificationMethod: VerificationMethod[];
+  authentication: string[];
+  assertionMethod: string[];
+  keyAgreement: string[];
+  service: ServiceEndpoint[];
+  created: string;
+  updated: string;
+  /** Rotation history (newest-first). Present only after at least one rotation. */
+  keyHistory?: KeyRotationRecord[];
+  /** Keys that have been explicitly revoked and must never be trusted. */
+  revokedKeys?: RevokedKeyRecord[];
+}
+
+export interface AgentKeyPair {
+  did: string;
+  privateKey: Uint8Array;
+  publicKey: Uint8Array;
+  document: DIDDocument;
+}
+
+// ─── Base58 encoding (multibase 'z' prefix) ───────────────────────────────────
+
+const BASE58_ALPHABET =
+  "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+
+function encodeBase58(bytes: Uint8Array): string {
+  let num = BigInt("0x" + bytesToHex(bytes));
+  const digits: number[] = [];
+  while (num > 0n) {
+    digits.push(Number(num % 58n));
+    num /= 58n;
+  }
+  // leading zeros
+  for (const b of bytes) {
+    if (b !== 0) break;
+    digits.push(0);
+  }
+  return digits
+    .reverse()
+    .map((d) => BASE58_ALPHABET[d])
+    .join("");
+}
+
+function decodeBase58(s: string): Uint8Array {
+  let num = 0n;
+  for (const c of s) {
+    const idx = BASE58_ALPHABET.indexOf(c);
+    if (idx < 0) throw new Error(`Invalid base58 character: ${c}`);
+    num = num * 58n + BigInt(idx);
+  }
+  const hex = num.toString(16).padStart(64, "0");
+  return Uint8Array.from(Buffer.from(hex, "hex"));
+}
+
+export function toMultibase(bytes: Uint8Array): string {
+  return "z" + encodeBase58(bytes);
+}
+
+export function fromMultibase(multibase: string): Uint8Array {
+  if (!multibase.startsWith("z")) {
+    throw new Error("Only base58btc multibase (prefix 'z') is supported");
+  }
+  return decodeBase58(multibase.slice(1));
+}
+
+// ─── DID Generation ───────────────────────────────────────────────────────────
+
+export interface GenerateDIDOptions {
+  /**
+   * Optional tenant namespace — produces did:aroha:<namespace>.<agentId>.
+   * Must match /^[a-z0-9-]+$/.
+   */
+  namespace?: string;
+}
+
+/**
+ * Generate a new Aroha DID with a fresh Ed25519 keypair.
+ *
+ * @param agentId  Human-readable identifier (e.g. "expedia-flights-v2")
+ * @param endpoint Aroha endpoint URL for the agent
+ * @param options  Optional generation options (e.g. namespace for multi-tenancy)
+ */
+export async function generateDID(
+  agentId: string,
+  endpoint: string,
+  options: GenerateDIDOptions = {}
+): Promise<AgentKeyPair> {
+  const { namespace } = options;
+  if (namespace && !/^[a-z0-9-]+$/.test(namespace)) {
+    throw new Error(`Invalid namespace "${namespace}" — must match /^[a-z0-9-]+$/`);
+  }
+  const qualifiedId = namespace ? `${namespace}.${agentId}` : agentId;
+
+  const privateKey = ed.utils.randomPrivateKey();
+  const publicKey = await ed.getPublicKeyAsync(privateKey);
+
+  const did = `did:aroha:${qualifiedId}`;
+  const now = new Date().toISOString();
+  const keyId = `${did}#key-1`;
+
+  const document: DIDDocument = {
+    "@context": [
+      "https://www.w3.org/ns/did/v1",
+      "https://w3id.org/security/suites/ed25519-2020/v1",
+    ],
+    id: did,
+    verificationMethod: [
+      {
+        id: keyId,
+        type: "Ed25519VerificationKey2020",
+        controller: did,
+        publicKeyMultibase: toMultibase(publicKey),
+      },
+    ],
+    authentication: [keyId],
+    assertionMethod: [keyId],
+    keyAgreement: [keyId],
+    service: [
+      {
+        id: `${did}#aroha`,
+        type: "ArohaEndpoint",
+        serviceEndpoint: endpoint,
+      },
+    ],
+    created: now,
+    updated: now,
+  };
+
+  return { did, privateKey, publicKey, document };
+}
+
+/**
+ * Reconstruct a DID Document from an existing keypair.
+ * Used when loading a saved agent identity from storage.
+ */
+export function buildDIDDocument(
+  agentId: string,
+  publicKey: Uint8Array,
+  endpoint: string,
+  created: string
+): DIDDocument {
+  const did = `did:aroha:${agentId}`;
+  const keyId = `${did}#key-1`;
+  const now = new Date().toISOString();
+
+  return {
+    "@context": [
+      "https://www.w3.org/ns/did/v1",
+      "https://w3id.org/security/suites/ed25519-2020/v1",
+    ],
+    id: did,
+    verificationMethod: [
+      {
+        id: keyId,
+        type: "Ed25519VerificationKey2020",
+        controller: did,
+        publicKeyMultibase: toMultibase(publicKey),
+      },
+    ],
+    authentication: [keyId],
+    assertionMethod: [keyId],
+    keyAgreement: [keyId],
+    service: [
+      {
+        id: `${did}#aroha`,
+        type: "ArohaEndpoint",
+        serviceEndpoint: endpoint,
+      },
+    ],
+    created,
+    updated: now,
+  };
+}
+
+/**
+ * Extract public key bytes from a DID Document's first verification method.
+ * Throws if a key rotation cool-down window is still active.
+ */
+export function extractPublicKey(doc: DIDDocument): Uint8Array {
+  const vm = doc.verificationMethod[0];
+  if (!vm) throw new Error(`DID ${doc.id} has no verification methods`);
+
+  // Check if the current key has been explicitly revoked
+  if (doc.revokedKeys && doc.revokedKeys.length > 0) {
+    const currentKeyMultibase = vm.publicKeyMultibase;
+    const revoked = doc.revokedKeys.find(r => r.keyMultibase === currentKeyMultibase);
+    if (revoked) {
+      throw new Error(
+        `DID ${doc.id} key ${currentKeyMultibase.slice(0, 12)}... was revoked at ${revoked.revokedAt}: ${revoked.reason}`
+      );
+    }
+  }
+
+  if (doc.keyHistory && doc.keyHistory.length > 0) {
+    const latest = doc.keyHistory[0];
+    if (new Date() < new Date(latest.trustAfter)) {
+      throw new Error(
+        `DID ${doc.id} key rotation cool-down active until ${latest.trustAfter}`
+      );
+    }
+  }
+
+  return fromMultibase(vm.publicKeyMultibase);
+}
+
+/**
+ * Extract the Aroha service endpoint URL from a DID Document.
+ */
+export function extractEndpoint(doc: DIDDocument): string {
+  const svc = doc.service.find((s) => s.type === "ArohaEndpoint");
+  if (!svc) throw new Error(`DID ${doc.id} has no ArohaEndpoint service`);
+  return svc.serviceEndpoint;
+}
+
+// ─── Key rotation ─────────────────────────────────────────────────────────────
+
+function keyCommitmentHash(publicKey: Uint8Array): string {
+  return bytesToHex(sha256(publicKey));
+}
+
+/**
+ * Rotate to a new keypair for a did:aroha: identity.
+ * The predecessor key signs the rotation record.
+ * The new key is not trusted until coolDownHours have elapsed.
+ */
+export async function rotateDIDKey(
+  current: AgentKeyPair,
+  coolDownHours = 24
+): Promise<AgentKeyPair> {
+  const newPrivateKey = ed.utils.randomPrivateKey();
+  const newPublicKey = await ed.getPublicKeyAsync(newPrivateKey);
+
+  const oldPubMultibase = toMultibase(current.publicKey);
+  const now = new Date();
+  const trustAfter = new Date(now.getTime() + coolDownHours * 3_600_000);
+
+  const newKeyHash = keyCommitmentHash(newPublicKey);
+  // Payload format matches verifyKeyRotation in web-did.ts:
+  // predecessorKey (multibase) + newKeyHash (hex) + rotatedAt (ISO8601)
+  const payload = new TextEncoder().encode(
+    oldPubMultibase + newKeyHash + now.toISOString()
+  );
+  const sig = await ed.signAsync(payload, current.privateKey);
+
+  const rotation: KeyRotationRecord = {
+    rotatedAt: now.toISOString(),
+    trustAfter: trustAfter.toISOString(),
+    predecessorKey: oldPubMultibase,
+    newKeyHash,
+    predecessorSignature: Buffer.from(sig).toString("base64url"),
+  };
+
+  const keyId = `${current.did}#key-1`;
+  const newDoc: DIDDocument = {
+    ...current.document,
+    verificationMethod: [
+      {
+        id: keyId,
+        type: "Ed25519VerificationKey2020",
+        controller: current.did,
+        publicKeyMultibase: toMultibase(newPublicKey),
+      },
+    ],
+    updated: now.toISOString(),
+    keyHistory: [rotation, ...(current.document.keyHistory ?? [])],
+  };
+
+  return { did: current.did, privateKey: newPrivateKey, publicKey: newPublicKey, document: newDoc };
+}
+
+/**
+ * Emergency key revocation — immediately marks the current key as revoked
+ * and rotates to a new keypair with NO cooldown period.
+ *
+ * Use when a private key is known or suspected to be compromised.
+ * After calling this, publish the updated DID Document immediately.
+ *
+ * @param current  The current agent keypair (needed to sign the revocation)
+ * @param reason   Human-readable reason for revocation
+ */
+export async function revokeKey(
+  current: AgentKeyPair,
+  reason: string
+): Promise<AgentKeyPair> {
+  const newPrivateKey = ed.utils.randomPrivateKey();
+  const newPublicKey = await ed.getPublicKeyAsync(newPrivateKey);
+
+  const now = new Date().toISOString();
+  const oldKeyMultibase = toMultibase(current.publicKey);
+
+  // Sign revocation with the key being revoked (proves intentional)
+  const payload = new TextEncoder().encode(oldKeyMultibase + now + reason);
+  const sig = await ed.signAsync(payload, current.privateKey);
+
+  const revokedRecord: RevokedKeyRecord = {
+    keyMultibase: oldKeyMultibase,
+    revokedAt: now,
+    reason,
+    selfSignature: Buffer.from(sig).toString("base64url"),
+  };
+
+  const keyId = `${current.did}#key-1`;
+  const newDoc: DIDDocument = {
+    ...current.document,
+    verificationMethod: [
+      {
+        id: keyId,
+        type: "Ed25519VerificationKey2020",
+        controller: current.did,
+        publicKeyMultibase: toMultibase(newPublicKey),
+      },
+    ],
+    updated: now,
+    // No keyHistory entry — no cooldown, immediate trust of new key
+    revokedKeys: [revokedRecord, ...(current.document.revokedKeys ?? [])],
+  };
+
+  return { did: current.did, privateKey: newPrivateKey, publicKey: newPublicKey, document: newDoc };
+}
+
+/**
+ * Verify a revocation record's self-signature.
+ * Returns true if the signature is valid — i.e., the holder of the revoked
+ * key intentionally created this record.
+ *
+ * @param record     The RevokedKeyRecord to verify
+ * @param publicKey  The public key that was revoked (to verify against)
+ */
+export async function verifyRevocation(
+  record: RevokedKeyRecord,
+  publicKey: Uint8Array
+): Promise<boolean> {
+  if (!record.selfSignature) return false;
+  try {
+    const payload = new TextEncoder().encode(
+      record.keyMultibase + record.revokedAt + record.reason
+    );
+    const sig = Buffer.from(record.selfSignature, "base64url");
+    return await ed.verifyAsync(sig, payload, publicKey);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Extract the namespace from a namespaced DID.
+ * Returns null for un-namespaced DIDs.
+ *
+ * Example:
+ *   extractNamespace("did:aroha:acme-corp.invoice-processor") → "acme-corp"
+ *   extractNamespace("did:aroha:flight-agent")                → null
+ */
+export function extractNamespace(did: string): string | null {
+  const suffix = did.replace("did:aroha:", "");
+  const dotIndex = suffix.indexOf(".");
+  return dotIndex >= 0 ? suffix.slice(0, dotIndex) : null;
+}

package/src/identity/index.ts

@@ -0,0 +1,4 @@
+export * from "./did.js";
+export * from "./credentials.js";
+export * from "./web-did.js";
+export * from "./did-cache.js";