@aroha-sdk/core 1.0.0

package/src/messages/envelope.test.ts

@@ -0,0 +1,289 @@
+import { describe, it, expect } from "vitest";
+import * as ed from "@noble/ed25519";
+import { sha512 } from "@noble/hashes/sha512";
+import { buildEnvelope, validateEnvelope, newCorrelationId, senderDID } from "./envelope.js";
+import { NonceRegistry } from "./nonce.js";
+
+ed.etc.sha512Sync = (...m: Parameters<typeof sha512>) => sha512(...m);
+
+async function makeKeyPair(id: string) {
+  const priv = ed.utils.randomPrivateKey();
+  const pub = await ed.getPublicKeyAsync(priv);
+  return { did: `did:aroha:${id}`, priv, pub };
+}
+
+describe("buildEnvelope", () => {
+  it("builds a signed envelope with all required fields", async () => {
+    const sender = await makeKeyPair("sender");
+    const cid = newCorrelationId();
+    const env = await buildEnvelope(
+      "ArohaRequest",
+      sender.did,
+      "did:aroha:recipient",
+      { capability: "search", params: {} },
+      cid,
+      sender.priv
+    );
+
+    expect(env.type).toBe("ArohaRequest");
+    expect(env.from).toBe(sender.did);
+    expect(env.to).toBe("did:aroha:recipient");
+    expect(env.correlationId).toBe(cid);
+    expect(env.id).toMatch(/^urn:uuid:/);
+    expect(env.proof).toBeDefined();
+    expect(env.proof!.type).toBe("Ed25519Signature2020");
+    expect(env.nonce).toBeTruthy();
+  });
+
+  it("sets expiry in the future", async () => {
+    const sender = await makeKeyPair("sender2");
+    const env = await buildEnvelope(
+      "ArohaResponse",
+      sender.did,
+      "did:aroha:other",
+      { capability: "search", result: {} },
+      newCorrelationId(),
+      sender.priv,
+      60
+    );
+    expect(new Date(env.expires) > new Date()).toBe(true);
+  });
+});
+
+describe("validateEnvelope", () => {
+  it("accepts a valid, freshly-built envelope", async () => {
+    const sender = await makeKeyPair("valid-sender");
+    const myDID = "did:aroha:receiver";
+    const reg = new NonceRegistry();
+
+    const env = await buildEnvelope(
+      "ArohaRequest",
+      sender.did,
+      myDID,
+      { capability: "do-thing", params: {} },
+      newCorrelationId(),
+      sender.priv
+    );
+
+    const result = await validateEnvelope(env, sender.pub, myDID, reg);
+    expect(result.valid).toBe(true);
+  });
+
+  it("rejects when addressed to the wrong recipient", async () => {
+    const sender = await makeKeyPair("wrong-to-sender");
+    const reg = new NonceRegistry();
+
+    const env = await buildEnvelope(
+      "ArohaRequest",
+      sender.did,
+      "did:aroha:someone-else",
+      { capability: "x", params: {} },
+      newCorrelationId(),
+      sender.priv
+    );
+
+    const result = await validateEnvelope(env, sender.pub, "did:aroha:me", reg);
+    expect(result.valid).toBe(false);
+    expect((result as { valid: false; reason: string }).reason).toMatch(/addressed to/);
+  });
+
+  it("rejects an expired envelope", async () => {
+    const sender = await makeKeyPair("expired-sender");
+    const myDID = "did:aroha:me";
+    const reg = new NonceRegistry();
+
+    const env = await buildEnvelope(
+      "ArohaRequest",
+      sender.did,
+      myDID,
+      { capability: "x", params: {} },
+      newCorrelationId(),
+      sender.priv,
+      -10 // already expired
+    );
+
+    const result = await validateEnvelope(env, sender.pub, myDID, reg);
+    expect(result.valid).toBe(false);
+    expect((result as { valid: false; reason: string }).reason).toMatch(/expired/);
+  });
+
+  it("rejects a replayed envelope", async () => {
+    const sender = await makeKeyPair("replay-sender");
+    const myDID = "did:aroha:me";
+    const reg = new NonceRegistry();
+
+    const env = await buildEnvelope(
+      "ArohaRequest",
+      sender.did,
+      myDID,
+      { capability: "x", params: {} },
+      newCorrelationId(),
+      sender.priv
+    );
+
+    await validateEnvelope(env, sender.pub, myDID, reg); // first — accepted
+    const result = await validateEnvelope(env, sender.pub, myDID, reg); // second — replay
+    expect(result.valid).toBe(false);
+    expect((result as { valid: false; reason: string }).reason).toMatch(/[Rr]eplay/);
+  });
+
+  it("rejects a tampered signature", async () => {
+    const sender = await makeKeyPair("tamper-sender");
+    const myDID = "did:aroha:me";
+    const reg = new NonceRegistry();
+
+    const env = await buildEnvelope(
+      "ArohaRequest",
+      sender.did,
+      myDID,
+      { capability: "x", params: {} },
+      newCorrelationId(),
+      sender.priv
+    );
+
+    const tampered = {
+      ...env,
+      proof: { ...env.proof!, proofValue: "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=" },
+    };
+
+    const result = await validateEnvelope(tampered, sender.pub, myDID, reg);
+    expect(result.valid).toBe(false);
+  });
+});
+
+describe("newCorrelationId", () => {
+  it("generates unique IDs each call", () => {
+    const a = newCorrelationId();
+    const b = newCorrelationId();
+    expect(a).not.toBe(b);
+    expect(a).toMatch(/^saga-/);
+  });
+});
+
+describe("senderDID", () => {
+  it("returns the from field", async () => {
+    const sender = await makeKeyPair("sid");
+    const env = await buildEnvelope(
+      "ArohaRequest",
+      sender.did,
+      "did:aroha:other",
+      { capability: "x", params: {} },
+      newCorrelationId(),
+      sender.priv
+    );
+    expect(senderDID(env)).toBe(sender.did);
+  });
+});
+
+describe("validateEnvelope clock tolerance", () => {
+  it("rejects an expired envelope with no tolerance", async () => {
+    const sender = await makeKeyPair("expired-no-tolerance-sender");
+    const myDID = "did:aroha:me";
+    const reg = new NonceRegistry();
+
+    // Build a normal envelope
+    const env = await buildEnvelope(
+      "ArohaRequest",
+      sender.did,
+      myDID,
+      { capability: "x", params: {} },
+      newCorrelationId(),
+      sender.priv,
+      300
+    );
+
+    // Mutate expires to the past
+    const expiredEnv = {
+      ...env,
+      expires: new Date(Date.now() - 5000).toISOString(), // 5 seconds ago
+    };
+
+    // Validate with skipSignature to avoid needing to re-sign
+    const result = await validateEnvelope(
+      expiredEnv,
+      sender.pub,
+      myDID,
+      reg,
+      { skipSignature: true }
+    );
+    expect(result.valid).toBe(false);
+    expect((result as { valid: false; reason: string }).reason).toMatch(/expired/);
+  });
+
+  it("accepts a slightly-expired envelope within clock tolerance", async () => {
+    const sender = await makeKeyPair("expired-within-tolerance-sender");
+    const myDID = "did:aroha:me";
+    const reg = new NonceRegistry();
+
+    // Build a normal envelope
+    const env = await buildEnvelope(
+      "ArohaRequest",
+      sender.did,
+      myDID,
+      { capability: "x", params: {} },
+      newCorrelationId(),
+      sender.priv,
+      300
+    );
+
+    // Mutate expires to 3 seconds ago
+    const expiredEnv = {
+      ...env,
+      expires: new Date(Date.now() - 3000).toISOString(),
+    };
+
+    // Validate with 10 second tolerance
+    const result = await validateEnvelope(
+      expiredEnv,
+      sender.pub,
+      myDID,
+      reg,
+      { skipSignature: true, clockToleranceMs: 10_000 }
+    );
+    expect(result.valid).toBe(true);
+  });
+
+  it("respects exact tolerance boundary", async () => {
+    const sender = await makeKeyPair("tolerance-boundary-sender");
+    const myDID = "did:aroha:me";
+    const regA = new NonceRegistry();
+    const regB = new NonceRegistry();
+
+    // Build a normal envelope
+    const env = await buildEnvelope(
+      "ArohaRequest",
+      sender.did,
+      myDID,
+      { capability: "x", params: {} },
+      newCorrelationId(),
+      sender.priv,
+      300
+    );
+
+    // Mutate expires to exactly 5 seconds ago
+    const expiredEnv = {
+      ...env,
+      expires: new Date(Date.now() - 5000).toISOString(),
+    };
+
+    // Test just below tolerance boundary (4999ms ago, 5000ms tolerance) — should accept
+    const resultBelowBoundary = await validateEnvelope(
+      { ...expiredEnv, expires: new Date(Date.now() - 4999).toISOString() },
+      sender.pub,
+      myDID,
+      regA,
+      { skipSignature: true, clockToleranceMs: 5000 }
+    );
+    expect(resultBelowBoundary.valid).toBe(true);
+
+    // Test just above tolerance boundary (5001ms ago, 5000ms tolerance) — should reject
+    const resultAboveBoundary = await validateEnvelope(
+      { ...expiredEnv, expires: new Date(Date.now() - 5001).toISOString() },
+      sender.pub,
+      myDID,
+      regB,
+      { skipSignature: true, clockToleranceMs: 5000 }
+    );
+    expect(resultAboveBoundary.valid).toBe(false);
+  });
+});

package/src/messages/envelope.ts

@@ -0,0 +1,232 @@
+/**
+ * Aroha Protocol — Layer 3 Message Envelope
+ *
+ * Implements the spec's message envelope format.
+ * Every Aroha message, regardless of type, uses this envelope.
+ *
+ * Responsibilities:
+ *   - Build outbound envelopes (build + sign)
+ *   - Validate inbound envelopes (schema + signature + nonce + expiry + recipient)
+ *
+ * This module is pure protocol. It does not route messages or apply
+ * business logic — that belongs to the application tier.
+ */
+
+import { randomBytes } from "@noble/hashes/utils";
+import { v4 as uuidv4 } from "uuid";
+import { signMessage, verifyMessageSignature, type MessageProof } from "../crypto/signing.js";
+import { NonceRegistry } from "./nonce.js";
+import { type ArohaMessageType, type ArohaBodyByType } from "./types.js";
+
+// ─── Envelope Type ────────────────────────────────────────────────────────────
+
+export interface ArohaEnvelope<T extends ArohaMessageType = ArohaMessageType> {
+  "@context": string[];
+  id: string;           // urn:uuid:<uuid-v4>
+  type: T;
+  from: string;         // did:aroha:<sender>
+  to: string;           // did:aroha:<recipient>
+  created: string;      // ISO8601
+  expires: string;      // ISO8601
+  nonce: string;        // random hex-32, replay prevention
+  correlationId: string; // links messages in a saga or session
+  body: T extends keyof ArohaBodyByType ? ArohaBodyByType[T] : Record<string, unknown>;
+  proof?: MessageProof;
+  /** W3C Trace Context traceparent header — injected by @aroha-sdk/telemetry for distributed tracing. */
+  traceparent?: string;
+  /**
+   * Model routing hint — set by @aroha-sdk/orchestrator ModelRouter.
+   * Informational only: tells the receiving agent which model tier to use
+   * for processing this request. Never enforced by the transport layer.
+   */
+  routingHint?: {
+    complexity: "trivial" | "standard" | "complex";
+    suggestedModel?: string;
+  };
+}
+
+// ─── Build ────────────────────────────────────────────────────────────────────
+
+const Aroha_CONTEXT = [
+  "https://aroha-labs.com/contexts/v1",
+  "https://w3id.org/security/suites/ed25519-2020/v1",
+];
+
+/**
+ * Build and sign an outbound Aroha message envelope.
+ *
+ * @param type             One of the 15 Aroha message types
+ * @param from             Sender DID (did:aroha:<id>)
+ * @param to               Recipient DID (did:aroha:<id>)
+ * @param body             Message body — typed per message type
+ * @param correlationId    Saga or session ID linking related messages
+ * @param privateKey       Sender's Ed25519 private key
+ * @param ttlSeconds       How long the message is valid (default: 300s / 5min)
+ */
+export interface BuildEnvelopeOptions {
+  ttlSeconds?: number;
+  /** W3C Trace Context traceparent — propagated by @aroha-sdk/telemetry. */
+  traceparent?: string;
+  /** Model routing hint — set by @aroha-sdk/orchestrator ModelRouter. */
+  routingHint?: ArohaEnvelope["routingHint"];
+}
+
+export async function buildEnvelope<T extends ArohaMessageType>(
+  type: T,
+  from: string,
+  to: string,
+  body: T extends keyof ArohaBodyByType ? ArohaBodyByType[T] : Record<string, unknown>,
+  correlationId: string,
+  privateKey: Uint8Array,
+  ttlSecondsOrOptions: number | BuildEnvelopeOptions = 300
+): Promise<ArohaEnvelope<T>> {
+  const opts: BuildEnvelopeOptions =
+    typeof ttlSecondsOrOptions === "number"
+      ? { ttlSeconds: ttlSecondsOrOptions }
+      : ttlSecondsOrOptions;
+  const ttlSeconds = opts.ttlSeconds ?? 300;
+
+  const now = new Date();
+  const expires = new Date(now.getTime() + ttlSeconds * 1000);
+
+  const envelope: ArohaEnvelope<T> = {
+    "@context": Aroha_CONTEXT,
+    id: `urn:uuid:${uuidv4()}`,
+    type,
+    from,
+    to,
+    created: now.toISOString(),
+    expires: expires.toISOString(),
+    nonce: Buffer.from(randomBytes(32)).toString("hex"),
+    correlationId,
+    body,
+    ...(opts.traceparent ? { traceparent: opts.traceparent } : {}),
+    ...(opts.routingHint ? { routingHint: opts.routingHint } : {}),
+  };
+
+  const keyId = `${from}#key-1`;
+  const proof = await signMessage(
+    envelope as unknown as Record<string, unknown>,
+    privateKey,
+    keyId
+  );
+
+  return { ...envelope, proof };
+}
+
+/**
+ * Build an unsigned Aroha envelope for use within a trusted network mesh
+ * (VPC, mTLS service mesh). The receiving server must be configured with
+ * bypassSignatureFor to accept envelopes from this sender DID.
+ */
+export async function buildUnsignedEnvelope<T extends ArohaMessageType>(
+  type: T,
+  from: string,
+  to: string,
+  body: T extends keyof ArohaBodyByType ? ArohaBodyByType[T] : Record<string, unknown>,
+  correlationId: string,
+  opts: BuildEnvelopeOptions = {}
+): Promise<ArohaEnvelope<T>> {
+  const ttlSeconds = opts.ttlSeconds ?? 300;
+  const now = new Date();
+  const expires = new Date(now.getTime() + ttlSeconds * 1000);
+
+  return {
+    "@context": Aroha_CONTEXT,
+    id: `urn:uuid:${uuidv4()}`,
+    type,
+    from,
+    to,
+    created: now.toISOString(),
+    expires: expires.toISOString(),
+    nonce: Buffer.from(randomBytes(32)).toString("hex"),
+    correlationId,
+    body,
+    ...(opts.traceparent ? { traceparent: opts.traceparent } : {}),
+  };
+}
+
+// ─── Validate ─────────────────────────────────────────────────────────────────
+
+export type ValidationResult =
+  | { valid: true }
+  | { valid: false; reason: string };
+
+/**
+ * Validate an inbound Aroha message envelope.
+ *
+ * Checks (per spec):
+ *   1. Signature verification (against provided public key)
+ *   2. Message expiry (expires field)
+ *   3. Nonce freshness (replay attack prevention)
+ *   4. Recipient match (to field must equal this agent's DID)
+ *
+ * @param envelope      The received message envelope
+ * @param senderPubKey  Ed25519 public key of the claimed sender (looked up from registry)
+ * @param myDID         This agent's DID (to verify the "to" field)
+ * @param nonceRegistry Shared nonce registry for this agent
+ */
+export interface ValidateEnvelopeOptions {
+  /** Skip Ed25519 signature check — use only within trusted mesh / VPC environments. */
+  skipSignature?: boolean;
+  /**
+   * Clock skew tolerance in milliseconds applied to the expires check.
+   * Accepts messages that expired up to this many ms ago.
+   * Recommended: 5000 (5s) for cross-region deployments.
+   * Default: 0 (strict).
+   */
+  clockToleranceMs?: number;
+}
+
+export async function validateEnvelope(
+  envelope: ArohaEnvelope,
+  senderPubKey: Uint8Array,
+  myDID: string,
+  nonceRegistry: NonceRegistry,
+  options?: ValidateEnvelopeOptions
+): Promise<ValidationResult> {
+  // 1. Recipient check — must be addressed to us
+  if (envelope.to !== myDID) {
+    return { valid: false, reason: `Message addressed to ${envelope.to}, not ${myDID}` };
+  }
+
+  // 2. Expiry check
+  const tolerance = options?.clockToleranceMs ?? 0;
+  if (tolerance < 0) {
+    return { valid: false, reason: "Invalid clockToleranceMs: must be non-negative" };
+  }
+  if (new Date(envelope.expires).getTime() + tolerance < Date.now()) {
+    return { valid: false, reason: `Message expired at ${envelope.expires} (outside tolerance window)` };
+  }
+
+  // 3. Nonce check (replay prevention)
+  const nonceFresh = await nonceRegistry.checkAsync(envelope.nonce, envelope.expires);
+  if (!nonceFresh) {
+    return { valid: false, reason: "Nonce replay detected" };
+  }
+
+  // 4. Signature verification (skip in trusted mesh mode)
+  if (!options?.skipSignature) {
+    const isValid = await verifyMessageSignature(
+      envelope as unknown as Record<string, unknown>,
+      senderPubKey
+    );
+    if (!isValid) {
+      return { valid: false, reason: "Signature verification failed" };
+    }
+  }
+
+  return { valid: true };
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+/** Create a new correlationId for a new saga or session. */
+export function newCorrelationId(): string {
+  return `saga-${uuidv4()}`;
+}
+
+/** Extract the sender's DID from an envelope. */
+export function senderDID(envelope: ArohaEnvelope): string {
+  return envelope.from;
+}

package/src/messages/idempotency.ts

@@ -0,0 +1,142 @@
+/**
+ * Idempotency Store — server-side deduplication for ArohaRequest.
+ *
+ * ArohaCommit is already spec-idempotent. But ArohaRequest (capability
+ * invocations) are not — a retried "book-flight" request could create a
+ * duplicate booking. The idempotency store fixes this.
+ *
+ * Protocol contract:
+ *   Sender includes idempotencyKey: string in ArohaRequestBody.
+ *   Receiver checks the store before processing. If the key exists and
+ *   the cached response is still valid, the cached response is returned
+ *   immediately — no work is done twice.
+ *
+ * Key design: senderDID:idempotencyKey — scoped per sender so different
+ * orchestrators cannot accidentally share idempotency keys.
+ *
+ * Reference: Stripe API idempotency (https://stripe.com/docs/idempotency)
+ */
+
+import { type ArohaEnvelope } from "./envelope.js";
+
+// ─── Interface ────────────────────────────────────────────────────────────────
+
+export interface IIdempotencyStore {
+  /**
+   * Retrieve a cached response for this key.
+   * Returns null if not found or expired.
+   */
+  get(senderDID: string, idempotencyKey: string): Promise<ArohaEnvelope | null>;
+
+  /**
+   * Store a response for this key with a TTL.
+   * TTL default: 86_400_000 ms (24 hours) — matches typical saga window.
+   */
+  set(
+    senderDID: string,
+    idempotencyKey: string,
+    response: ArohaEnvelope,
+    ttlMs?: number
+  ): Promise<void>;
+}
+
+// ─── In-memory implementation ─────────────────────────────────────────────────
+
+interface StoredEntry {
+  response: ArohaEnvelope;
+  expiresAt: number;
+}
+
+export class InMemoryIdempotencyStore implements IIdempotencyStore {
+  private readonly defaultTtlMs: number;
+  private readonly store = new Map<string, StoredEntry>();
+  private readonly cleanupIntervalMs: number;
+  private readonly cleanupTimer: ReturnType<typeof setInterval>;
+
+  constructor(config: { defaultTtlMs?: number; cleanupIntervalMs?: number } = {}) {
+    this.defaultTtlMs       = config.defaultTtlMs       ?? 86_400_000; // 24h
+    this.cleanupIntervalMs  = config.cleanupIntervalMs  ?? 300_000;    // 5m
+
+    // Periodically evict expired entries to prevent unbounded memory growth
+    this.cleanupTimer = setInterval(() => this.evictExpired(), this.cleanupIntervalMs);
+    // Don't prevent process exit if only cleanup timer is pending
+    if (this.cleanupTimer.unref) this.cleanupTimer.unref();
+  }
+
+  async get(senderDID: string, idempotencyKey: string): Promise<ArohaEnvelope | null> {
+    const key = storeKey(senderDID, idempotencyKey);
+    const entry = this.store.get(key);
+    if (!entry) return null;
+    if (Date.now() > entry.expiresAt) {
+      this.store.delete(key);
+      return null;
+    }
+    return entry.response;
+  }
+
+  async set(
+    senderDID: string,
+    idempotencyKey: string,
+    response: ArohaEnvelope,
+    ttlMs = this.defaultTtlMs
+  ): Promise<void> {
+    this.store.set(storeKey(senderDID, idempotencyKey), {
+      response,
+      expiresAt: Date.now() + ttlMs,
+    });
+  }
+
+  destroy(): void {
+    clearInterval(this.cleanupTimer);
+    this.store.clear();
+  }
+
+  get size(): number {
+    return this.store.size;
+  }
+
+  private evictExpired(): void {
+    const now = Date.now();
+    for (const [key, entry] of this.store) {
+      if (now > entry.expiresAt) this.store.delete(key);
+    }
+  }
+}
+
+// ─── Utility ──────────────────────────────────────────────────────────────────
+
+function storeKey(senderDID: string, idempotencyKey: string): string {
+  return `${senderDID}:${idempotencyKey}`;
+}
+
+/**
+ * Check the idempotency store and return a cached response if one exists.
+ * Returns null if the request should proceed normally.
+ *
+ * Usage in an agent's message handler:
+ *   const cached = await checkIdempotency(store, envelope);
+ *   if (cached) { respond(cached); return; }
+ *   // ... process normally ...
+ *   const response = buildResponse(...);
+ *   await storeIdempotency(store, envelope, response);
+ *   respond(response);
+ */
+export async function checkIdempotency(
+  store: IIdempotencyStore,
+  envelope: ArohaEnvelope
+): Promise<ArohaEnvelope | null> {
+  const body = envelope.body as { idempotencyKey?: string };
+  if (!body.idempotencyKey) return null;
+  return store.get(envelope.from, body.idempotencyKey);
+}
+
+export async function storeIdempotency(
+  store: IIdempotencyStore,
+  requestEnvelope: ArohaEnvelope,
+  responseEnvelope: ArohaEnvelope,
+  ttlMs?: number
+): Promise<void> {
+  const body = requestEnvelope.body as { idempotencyKey?: string };
+  if (!body.idempotencyKey) return;
+  await store.set(requestEnvelope.from, body.idempotencyKey, responseEnvelope, ttlMs);
+}

package/src/messages/index.ts

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export * from "./envelope.js";
+export * from "./nonce.js";
+export * from "./idempotency.js";