@aroha-sdk/core 1.0.0

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@aroha-sdk/core",
+  "version": "1.0.0",
+  "description": "Aroha core: identity, crypto, messaging, transport",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./identity": "./dist/identity/index.js",
+    "./crypto": "./dist/crypto/index.js",
+    "./messages": "./dist/messages/index.js",
+    "./transport": "./dist/transport/index.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "dev": "tsc -p tsconfig.json --watch"
+  },
+  "dependencies": {
+    "@noble/curves": "^1.9.7",
+    "@noble/ed25519": "^2.1.0",
+    "@noble/hashes": "^1.4.0",
+    "undici": "^6.27.0",
+    "uuid": "^10.0.0",
+    "ws": "^8.17.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "@types/uuid": "^10.0.0",
+    "@types/ws": "^8.5.10",
+    "typescript": "^5.4.5",
+    "vitest": "^1.6.0"
+  }
+}

package/src/conformance/l0-did-identity.conformance.test.ts

@@ -0,0 +1,183 @@
+/**
+ * Aroha Protocol Conformance Suite — Layer 0: DID & Identity
+ *
+ * Tests the MUST requirements from docs/conformance/test-matrix.md rows L0-01 to L0-04.
+ * Each test maps to one test matrix row and is labelled accordingly.
+ */
+
+import { describe, it, expect } from "vitest";
+import * as ed from "@noble/ed25519";
+import { sha512 } from "@noble/hashes/sha512";
+import {
+  generateDID,
+  rotateDIDKey,
+  toMultibase,
+  fromMultibase,
+} from "../identity/did.js";
+import { buildEnvelope, validateEnvelope, newCorrelationId } from "../messages/envelope.js";
+import { NonceRegistry } from "../messages/nonce.js";
+
+ed.etc.sha512Sync = (...m: Parameters<typeof sha512>) => sha512(...m);
+
+// ─── L0-01: Valid did:aroha: DID backed by Ed25519 keypair ───────────────────
+
+describe("L0-01 [MUST] Agent generates a valid did:aroha: DID backed by Ed25519 keypair", () => {
+  it("generates a DID with the correct prefix", async () => {
+    const agent = await generateDID("test-agent", "https://example.com/aroha");
+    expect(agent.did).toMatch(/^did:aroha:/);
+  });
+
+  it("public key round-trips through multibase encoding", async () => {
+    const agent = await generateDID("multibase-test", "https://example.com/aroha");
+    const encoded = toMultibase(agent.publicKey);
+    const decoded = fromMultibase(encoded);
+    expect(decoded).toEqual(agent.publicKey);
+  });
+
+  it("DID document contains the public key in the first verificationMethod", async () => {
+    const agent = await generateDID("doc-test", "https://example.com/aroha");
+    expect(agent.document.verificationMethod).toHaveLength(1);
+    const vm = agent.document.verificationMethod[0];
+    expect(vm.type).toBe("Ed25519VerificationKey2020");
+    const recovered = fromMultibase(vm.publicKeyMultibase);
+    expect(recovered).toEqual(agent.publicKey);
+  });
+
+  it("public key verifies a signature made with the private key", async () => {
+    const agent = await generateDID("sig-test", "https://example.com/aroha");
+    const message = new TextEncoder().encode("hello aroha");
+    const sig = await ed.signAsync(message, agent.privateKey);
+    const valid = await ed.verifyAsync(sig, message, agent.publicKey);
+    expect(valid).toBe(true);
+  });
+});
+
+// ─── L0-02: DID document conforms to W3C DID Core 1.0 ───────────────────────
+
+describe("L0-02 [MUST] DID document conforms to W3C DID Core 1.0", () => {
+  it("includes the required @context entries", async () => {
+    const agent = await generateDID("ctx-test", "https://example.com/aroha");
+    const doc = agent.document;
+    expect(doc["@context"]).toContain("https://www.w3.org/ns/did/v1");
+    expect(doc["@context"]).toContain(
+      "https://w3id.org/security/suites/ed25519-2020/v1"
+    );
+  });
+
+  it("id field equals the DID", async () => {
+    const agent = await generateDID("id-test", "https://example.com/aroha");
+    expect(agent.document.id).toBe(agent.did);
+  });
+
+  it("authentication references the key id", async () => {
+    const agent = await generateDID("auth-test", "https://example.com/aroha");
+    const doc = agent.document;
+    const keyId = `${agent.did}#key-1`;
+    expect(doc.authentication).toContain(keyId);
+  });
+
+  it("assertionMethod references the key id", async () => {
+    const agent = await generateDID("assertion-test", "https://example.com/aroha");
+    const doc = agent.document;
+    const keyId = `${agent.did}#key-1`;
+    expect(doc.assertionMethod).toContain(keyId);
+  });
+
+  it("service array contains an ArohaEndpoint entry", async () => {
+    const endpoint = "https://agent.example.com/aroha";
+    const agent = await generateDID("svc-test", endpoint);
+    const svc = agent.document.service.find((s) => s.type === "ArohaEndpoint");
+    expect(svc).toBeDefined();
+    expect(svc!.serviceEndpoint).toBe(endpoint);
+  });
+
+  it("verificationMethod controller equals the DID", async () => {
+    const agent = await generateDID("ctrl-test", "https://example.com/aroha");
+    const vm = agent.document.verificationMethod[0];
+    expect(vm.controller).toBe(agent.did);
+  });
+});
+
+// ─── L0-03: Key rotation without DID change ──────────────────────────────────
+
+describe("L0-03 [MUST] Agent can rotate keys without changing DID", () => {
+  it("DID is unchanged after rotation", async () => {
+    const original = await generateDID("rotate-test", "https://example.com/aroha");
+    const rotated = await rotateDIDKey(original, 0); // 0h cooldown for tests
+    expect(rotated.did).toBe(original.did);
+  });
+
+  it("new keypair is different from the original", async () => {
+    const original = await generateDID("rotate-keys-test", "https://example.com/aroha");
+    const rotated = await rotateDIDKey(original, 0);
+    expect(rotated.privateKey).not.toEqual(original.privateKey);
+    expect(rotated.publicKey).not.toEqual(original.publicKey);
+  });
+
+  it("rotation record is stored in keyHistory", async () => {
+    const original = await generateDID("history-test", "https://example.com/aroha");
+    const rotated = await rotateDIDKey(original, 0);
+    expect(rotated.document.keyHistory).toBeDefined();
+    expect(rotated.document.keyHistory!.length).toBeGreaterThan(0);
+  });
+
+  it("new public key is recorded in the DID document after rotation", async () => {
+    const original = await generateDID("new-key-test", "https://example.com/aroha");
+    const rotated = await rotateDIDKey(original, 0);
+    const recoveredKey = fromMultibase(
+      rotated.document.verificationMethod[0].publicKeyMultibase
+    );
+    expect(recoveredKey).toEqual(rotated.publicKey);
+  });
+
+  it("new key signs and verifies correctly after rotation", async () => {
+    const original = await generateDID("sign-after-rotate", "https://example.com/aroha");
+    const rotated = await rotateDIDKey(original, 0);
+    const message = new TextEncoder().encode("post-rotation message");
+    const sig = await ed.signAsync(message, rotated.privateKey);
+    const valid = await ed.verifyAsync(sig, message, rotated.publicKey);
+    expect(valid).toBe(true);
+  });
+});
+
+// ─── L0-04: Reject messages signed with unknown DID ──────────────────────────
+
+describe("L0-04 [MUST] Agent rejects messages signed with unknown/wrong DID key", () => {
+  it("rejects an envelope when the verifying key does not match the signing key", async () => {
+    const sender = await generateDID("l0-04-sender", "https://example.com/aroha");
+    const stranger = await generateDID("l0-04-stranger", "https://example.com/aroha");
+    const myDID = "did:aroha:l0-04-receiver";
+    const reg = new NonceRegistry();
+
+    const env = await buildEnvelope(
+      "ArohaRequest",
+      sender.did,
+      myDID,
+      { capability: "test", params: {} },
+      newCorrelationId(),
+      sender.privateKey
+    );
+
+    // Validate with the wrong public key (stranger's key instead of sender's)
+    const result = await validateEnvelope(env, stranger.publicKey, myDID, reg);
+    expect(result.valid).toBe(false);
+  });
+
+  it("accepts an envelope when the correct sender key is used", async () => {
+    const sender = await generateDID("l0-04-valid", "https://example.com/aroha");
+    const myDID = "did:aroha:l0-04-valid-recv";
+    const reg = new NonceRegistry();
+
+    const env = await buildEnvelope(
+      "ArohaRequest",
+      sender.did,
+      myDID,
+      { capability: "test", params: {} },
+      newCorrelationId(),
+      sender.privateKey
+    );
+
+    const result = await validateEnvelope(env, sender.publicKey, myDID, reg);
+    expect(result.valid).toBe(true);
+  });
+});

package/src/conformance/l1-signed-envelopes.conformance.test.ts

@@ -0,0 +1,334 @@
+/**
+ * Aroha Protocol Conformance Suite — Layer 1: Signed Envelopes
+ *
+ * Tests the MUST requirements from docs/conformance/test-matrix.md rows L1-01 to L1-05.
+ * L1-06 (TLS enforcement) is a transport-level control verified during deployment;
+ * it cannot be meaningfully tested in unit scope — a note is included.
+ */
+
+import { describe, it, expect } from "vitest";
+import * as ed from "@noble/ed25519";
+import { sha512 } from "@noble/hashes/sha512";
+import { buildEnvelope, validateEnvelope, newCorrelationId } from "../messages/envelope.js";
+import { NonceRegistry } from "../messages/nonce.js";
+import { generateDID } from "../identity/did.js";
+
+ed.etc.sha512Sync = (...m: Parameters<typeof sha512>) => sha512(...m);
+
+async function makeAgent(id: string) {
+  return generateDID(id, `https://${id}.example.com/aroha`);
+}
+
+// ─── L1-01: Every outbound message is signed ─────────────────────────────────
+
+describe("L1-01 [MUST] Every outbound message is signed with sender's Ed25519 key", () => {
+  it("buildEnvelope attaches a proof block", async () => {
+    const sender = await makeAgent("l1-01-sender");
+    const env = await buildEnvelope(
+      "ArohaRequest",
+      sender.did,
+      "did:aroha:l1-01-recv",
+      { capability: "ping", params: {} },
+      newCorrelationId(),
+      sender.privateKey
+    );
+    expect(env.proof).toBeDefined();
+    expect(env.proof!.type).toBe("Ed25519Signature2020");
+    expect(env.proof!.proofValue).toBeTruthy();
+  });
+
+  it("proof verification key id points to sender's DID key", async () => {
+    const sender = await makeAgent("l1-01-key-id");
+    const env = await buildEnvelope(
+      "ArohaRequest",
+      sender.did,
+      "did:aroha:l1-01-key-id-recv",
+      { capability: "ping", params: {} },
+      newCorrelationId(),
+      sender.privateKey
+    );
+    expect(env.proof!.verificationMethod).toContain(sender.did);
+  });
+
+  it("proof verifies successfully against the sender's public key", async () => {
+    const sender = await makeAgent("l1-01-verify");
+    const myDID = "did:aroha:l1-01-verify-recv";
+    const reg = new NonceRegistry();
+
+    const env = await buildEnvelope(
+      "ArohaRequest",
+      sender.did,
+      myDID,
+      { capability: "ping", params: {} },
+      newCorrelationId(),
+      sender.privateKey
+    );
+
+    const result = await validateEnvelope(env, sender.publicKey, myDID, reg);
+    expect(result.valid).toBe(true);
+  });
+});
+
+// ─── L1-02: Receiver rejects messages with invalid signatures ─────────────────
+
+describe("L1-02 [MUST] Receiver rejects messages with invalid signatures", () => {
+  it("rejects a tampered proofValue", async () => {
+    const sender = await makeAgent("l1-02-tamper");
+    const myDID = "did:aroha:l1-02-tamper-recv";
+    const reg = new NonceRegistry();
+
+    const env = await buildEnvelope(
+      "ArohaRequest",
+      sender.did,
+      myDID,
+      { capability: "ping", params: {} },
+      newCorrelationId(),
+      sender.privateKey
+    );
+
+    const tampered = {
+      ...env,
+      proof: { ...env.proof!, proofValue: "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=" },
+    };
+
+    const result = await validateEnvelope(tampered, sender.publicKey, myDID, reg);
+    expect(result.valid).toBe(false);
+  });
+
+  it("rejects when signed with a different private key than the declared sender", async () => {
+    const declaredSender = await makeAgent("l1-02-declared");
+    const actualSigner = await makeAgent("l1-02-actual");
+    const myDID = "did:aroha:l1-02-wrong-key-recv";
+    const reg = new NonceRegistry();
+
+    // Signed with actualSigner's key but claims to be from declaredSender
+    const env = await buildEnvelope(
+      "ArohaRequest",
+      declaredSender.did,
+      myDID,
+      { capability: "ping", params: {} },
+      newCorrelationId(),
+      actualSigner.privateKey // wrong key
+    );
+
+    // Receiver looks up declaredSender's public key — signature won't verify
+    const result = await validateEnvelope(env, declaredSender.publicKey, myDID, reg);
+    expect(result.valid).toBe(false);
+  });
+});
+
+// ─── L1-03: Receiver rejects replayed messages ───────────────────────────────
+
+describe("L1-03 [MUST] Receiver rejects replayed messages (timestamp + nonce)", () => {
+  it("rejects an identical envelope submitted twice", async () => {
+    const sender = await makeAgent("l1-03-replay");
+    const myDID = "did:aroha:l1-03-replay-recv";
+    const reg = new NonceRegistry();
+
+    const env = await buildEnvelope(
+      "ArohaRequest",
+      sender.did,
+      myDID,
+      { capability: "ping", params: {} },
+      newCorrelationId(),
+      sender.privateKey
+    );
+
+    const first = await validateEnvelope(env, sender.publicKey, myDID, reg);
+    expect(first.valid).toBe(true);
+
+    const second = await validateEnvelope(env, sender.publicKey, myDID, reg);
+    expect(second.valid).toBe(false);
+    expect((second as { valid: false; reason: string }).reason).toMatch(/[Rr]eplay/);
+  });
+
+  it("accepts two different envelopes (different nonces) from the same sender", async () => {
+    const sender = await makeAgent("l1-03-two-valid");
+    const myDID = "did:aroha:l1-03-two-recv";
+    const reg = new NonceRegistry();
+
+    const env1 = await buildEnvelope(
+      "ArohaRequest",
+      sender.did,
+      myDID,
+      { capability: "ping", params: {} },
+      newCorrelationId(),
+      sender.privateKey
+    );
+    const env2 = await buildEnvelope(
+      "ArohaRequest",
+      sender.did,
+      myDID,
+      { capability: "ping", params: {} },
+      newCorrelationId(),
+      sender.privateKey
+    );
+
+    const r1 = await validateEnvelope(env1, sender.publicKey, myDID, reg);
+    const r2 = await validateEnvelope(env2, sender.publicKey, myDID, reg);
+    expect(r1.valid).toBe(true);
+    expect(r2.valid).toBe(true);
+  });
+});
+
+// ─── L1-04: Envelope includes expires field; expired envelopes rejected ───────
+
+describe("L1-04 [MUST] Envelope includes expires field; receiver rejects expired envelopes", () => {
+  it("buildEnvelope sets expires to a future timestamp", async () => {
+    const sender = await makeAgent("l1-04-expires");
+    const env = await buildEnvelope(
+      "ArohaRequest",
+      sender.did,
+      "did:aroha:l1-04-recv",
+      { capability: "ping", params: {} },
+      newCorrelationId(),
+      sender.privateKey
+    );
+    expect(env.expires).toBeDefined();
+    expect(new Date(env.expires) > new Date()).toBe(true);
+  });
+
+  it("rejects an envelope where expires is in the past", async () => {
+    const sender = await makeAgent("l1-04-past");
+    const myDID = "did:aroha:l1-04-past-recv";
+    const reg = new NonceRegistry();
+
+    // ttlSeconds = -10 creates an already-expired envelope
+    const env = await buildEnvelope(
+      "ArohaRequest",
+      sender.did,
+      myDID,
+      { capability: "ping", params: {} },
+      newCorrelationId(),
+      sender.privateKey,
+      -10
+    );
+
+    const result = await validateEnvelope(env, sender.publicKey, myDID, reg);
+    expect(result.valid).toBe(false);
+    expect((result as { valid: false; reason: string }).reason).toMatch(/expir/i);
+  });
+
+  it("accepts an envelope with expires well in the future", async () => {
+    const sender = await makeAgent("l1-04-future");
+    const myDID = "did:aroha:l1-04-future-recv";
+    const reg = new NonceRegistry();
+
+    const env = await buildEnvelope(
+      "ArohaRequest",
+      sender.did,
+      myDID,
+      { capability: "ping", params: {} },
+      newCorrelationId(),
+      sender.privateKey,
+      3600 // 1 hour TTL
+    );
+
+    const result = await validateEnvelope(env, sender.publicKey, myDID, reg);
+    expect(result.valid).toBe(true);
+  });
+});
+
+// ─── L1-05: Envelope schema validates against Aroha 1.0 message spec ─────────
+
+describe("L1-05 [MUST] Envelope schema validates against Aroha 1.0 message spec", () => {
+  it("built envelope contains all required top-level fields", async () => {
+    const sender = await makeAgent("l1-05-schema");
+    const env = await buildEnvelope(
+      "ArohaRequest",
+      sender.did,
+      "did:aroha:l1-05-recv",
+      { capability: "test", params: { x: 1 } },
+      newCorrelationId(),
+      sender.privateKey
+    );
+
+    // Required fields per Aroha 1.0 spec §3 (envelope schema)
+    expect(env["@context"]).toBeDefined();
+    expect(env.id).toMatch(/^urn:uuid:/);
+    expect(env.type).toBe("ArohaRequest");
+    expect(env.from).toMatch(/^did:aroha:/);
+    expect(env.to).toMatch(/^did:aroha:/);
+    expect(env.created).toBeTruthy();
+    expect(env.expires).toBeTruthy();
+    expect(env.nonce).toBeTruthy();
+    expect(env.correlationId).toBeTruthy();
+    expect(env.body).toBeDefined();
+    expect(env.proof).toBeDefined();
+  });
+
+  it("@context includes the Aroha protocol context", async () => {
+    const sender = await makeAgent("l1-05-ctx");
+    const env = await buildEnvelope(
+      "ArohaResponse",
+      sender.did,
+      "did:aroha:l1-05-ctx-recv",
+      { capability: "test", result: {} },
+      newCorrelationId(),
+      sender.privateKey
+    );
+    expect(env["@context"]).toContain("https://aroha-labs.com/contexts/v1");
+  });
+
+  it("correlationId links related messages in a saga", async () => {
+    const sender = await makeAgent("l1-05-cid");
+    const cid = newCorrelationId();
+
+    const req = await buildEnvelope(
+      "ArohaRequest",
+      sender.did,
+      "did:aroha:l1-05-cid-recv",
+      { capability: "test", params: {} },
+      cid,
+      sender.privateKey
+    );
+    const resp = await buildEnvelope(
+      "ArohaResponse",
+      "did:aroha:l1-05-cid-recv",
+      sender.did,
+      { capability: "test", result: {} },
+      cid, // same correlationId
+      sender.privateKey
+    );
+
+    expect(req.correlationId).toBe(cid);
+    expect(resp.correlationId).toBe(cid);
+  });
+
+  it("all valid Aroha message types can be built without error", async () => {
+    const sender = await makeAgent("l1-05-types");
+    const cid = newCorrelationId();
+    const recvDID = "did:aroha:l1-05-types-recv";
+
+    const types = [
+      ["ArohaRequest", { capability: "c", params: {} }],
+      ["ArohaResponse", { capability: "c", result: {} }],
+      ["ArohaError", { code: "Aroha_INTERNAL_ERROR", message: "test", retryable: false }],
+    ] as const;
+
+    for (const [type, body] of types) {
+      const env = await buildEnvelope(
+        type as Parameters<typeof buildEnvelope>[0],
+        sender.did,
+        recvDID,
+        body as Parameters<typeof buildEnvelope>[3],
+        cid,
+        sender.privateKey
+      );
+      expect(env.type).toBe(type);
+    }
+  });
+});
+
+// ─── L1-06: TLS 1.3+ enforcement (deployment-level control) ──────────────────
+
+describe("L1-06 [MUST] TLS 1.3+ enforced for all connections", () => {
+  it("is verified at deployment, not unit scope — minVersion TLSv1.3 must be set in server options", () => {
+    // TLS version enforcement cannot be meaningfully verified in a unit test.
+    // The reference implementation sets minVersion: 'TLSv1.3' in the HTTPS server
+    // options (docs/security/hardening.md §2) and nginx config (ssl_protocols TLSv1.3).
+    // This test documents the requirement and confirms the constant is correct.
+    const requiredMinTLSVersion = "TLSv1.3";
+    expect(requiredMinTLSVersion).toBe("TLSv1.3");
+  });
+});

package/src/crypto/encryption.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect } from "vitest";
+import * as ed from "@noble/ed25519";
+import { sha512 } from "@noble/hashes/sha512";
+import { encryptBody, decryptBody } from "./encryption.js";
+
+ed.etc.sha512Sync = (...m: Parameters<typeof sha512>) => sha512(...m);
+
+describe("encryptBody / decryptBody", () => {
+  it("round-trips a plaintext object", async () => {
+    const priv = ed.utils.randomPrivateKey();
+    const pub = await ed.getPublicKeyAsync(priv);
+    const plaintext = { capability: "book-flight", params: { origin: "JFK", dest: "LAX" } };
+
+    const encrypted = await encryptBody(plaintext, pub);
+
+    expect(encrypted.alg).toBe("ECDH-ES+A256GCM");
+    expect(encrypted.ciphertext).toBeTruthy();
+    expect(encrypted.tag).toBeTruthy();
+
+    const decrypted = await decryptBody(encrypted, priv);
+    expect(decrypted).toEqual(plaintext);
+  });
+
+  it("produces different ciphertext each time (random IV)", async () => {
+    const priv = ed.utils.randomPrivateKey();
+    const pub = await ed.getPublicKeyAsync(priv);
+    const plaintext = { hello: "world" };
+
+    const a = await encryptBody(plaintext, pub);
+    const b = await encryptBody(plaintext, pub);
+
+    expect(a.ciphertext).not.toBe(b.ciphertext);
+    expect(a.iv).not.toBe(b.iv);
+  });
+
+  it("fails to decrypt with a different private key", async () => {
+    const priv1 = ed.utils.randomPrivateKey();
+    const pub1 = await ed.getPublicKeyAsync(priv1);
+    const priv2 = ed.utils.randomPrivateKey();
+
+    const encrypted = await encryptBody({ secret: "data" }, pub1);
+
+    await expect(decryptBody(encrypted, priv2)).rejects.toThrow();
+  });
+});