@aroha-sdk/core 1.0.0

package/src/transport/client.ts

@@ -0,0 +1,236 @@
+/**
+ * Aroha Protocol — Layer 0 Transport Client
+ *
+ * Sends Aroha messages to remote agents over HTTPS.
+ * Handles streaming responses via WebSocket.
+ *
+ * This is protocol infrastructure. It does not know what the messages
+ * mean or what to do with responses — that is the orchestrator's job.
+ */
+
+import { WebSocket } from "ws";
+import { type ArohaEnvelope } from "../messages/envelope.js";
+
+// ─── Connection Pool ──────────────────────────────────────────────────────────
+
+export interface ConnectionPoolConfig {
+  /**
+   * Maximum number of concurrent connections per origin (scheme+host+port).
+   * Default: 10
+   */
+  connections?: number;
+  /**
+   * How long an idle connection is kept alive in ms.
+   * Default: 60_000 (60 seconds)
+   */
+  keepAliveTimeoutMs?: number;
+}
+
+/**
+ * AgentConnectionPool — maintains persistent HTTP connections per origin.
+ *
+ * Uses undici (built into Node.js 22+) to pool connections, eliminating
+ * the TCP+TLS handshake overhead on every ArohaClient.send() call.
+ *
+ * For an orchestrator talking to 20 agents at 100 msg/s, this removes
+ * ~2,000 TLS handshakes per second (~400ms each = 800s of saved latency/s).
+ *
+ * Usage:
+ *   const pool = new AgentConnectionPool();
+ *   const client = new ArohaClient({ pool });
+ */
+export class AgentConnectionPool {
+  private readonly connections: number;
+  private readonly keepAliveTimeoutMs: number;
+  // Map from origin → undici Pool instance (lazy-created)
+  private readonly pools = new Map<string, import("undici").Pool>();
+
+  constructor(config: ConnectionPoolConfig = {}) {
+    this.connections       = config.connections       ?? 10;
+    this.keepAliveTimeoutMs = config.keepAliveTimeoutMs ?? 60_000;
+  }
+
+  async fetch(url: string, init: RequestInit): Promise<Response> {
+    const origin = new URL(url).origin;
+    let pool = this.pools.get(origin);
+
+    if (!pool) {
+      const { Pool } = await import("undici");
+      pool = new Pool(origin, {
+        connections: this.connections,
+        keepAliveTimeout: this.keepAliveTimeoutMs / 1000,
+        keepAliveMaxTimeout: this.keepAliveTimeoutMs / 1000,
+      });
+      this.pools.set(origin, pool);
+    }
+
+    const { fetch: undiciFetch } = await import("undici");
+    return undiciFetch(url, { ...init, dispatcher: pool } as Parameters<typeof undiciFetch>[1]) as unknown as Response;
+  }
+
+  async destroy(): Promise<void> {
+    await Promise.all([...this.pools.values()].map((p) => p.destroy()));
+    this.pools.clear();
+  }
+
+  get poolCount(): number {
+    return this.pools.size;
+  }
+}
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface SendOptions {
+  timeoutMs?: number;
+}
+
+export interface ArohaClientOptions {
+  /** Optional connection pool for persistent keep-alive connections. */
+  pool?: AgentConnectionPool;
+}
+
+// ─── Client ───────────────────────────────────────────────────────────────────
+
+export class ArohaClient {
+  private readonly pool?: AgentConnectionPool;
+
+  constructor(opts: ArohaClientOptions = {}) {
+    this.pool = opts.pool;
+  }
+
+  /**
+   * Send an Aroha message and await a synchronous response.
+   * Returns the response ArohaEnvelope, or null when the provider responds
+   * with 202 Accepted (async / streaming — use stream() for WebSocket events).
+   */
+  async send(
+    endpoint: string,
+    envelope: ArohaEnvelope,
+    opts: SendOptions = {}
+  ): Promise<ArohaEnvelope | null> {
+    const { timeoutMs = 30_000 } = opts;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+    const fetchFn = this.pool
+      ? (url: string, init: RequestInit) => this.pool!.fetch(url, init)
+      : fetch;
+
+    let response: Response;
+    try {
+      response = await fetchFn(endpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(envelope),
+        signal: controller.signal,
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+
+    if (response.status === 202) {
+      return null;
+    }
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new ArohaTransportError(response.status, error);
+    }
+
+    return response.json() as Promise<ArohaEnvelope>;
+  }
+
+  /**
+   * Open a WebSocket stream to receive ArohaStream events for a given saga.
+   *
+   * @param wsEndpoint    WebSocket URL (wss://<host>/aroha/stream)
+   * @param correlationId The saga correlationId to subscribe to
+   * @param streamToken   One-time token from the 202 response (recommended)
+   */
+  stream(
+    wsEndpoint: string,
+    correlationId: string,
+    streamToken?: string
+  ): AsyncIterable<ArohaEnvelope> {
+    const u = new URL(wsEndpoint);
+    u.searchParams.set("cid", correlationId);
+    if (streamToken) u.searchParams.set("tok", streamToken);
+    const ws = new WebSocket(u.toString());
+
+    return {
+      [Symbol.asyncIterator]() {
+        const queue: ArohaEnvelope[] = [];
+        let resolve: ((value: IteratorResult<ArohaEnvelope>) => void) | null = null;
+        let done = false;
+        let error: Error | null = null;
+
+        ws.on("message", (data) => {
+          const envelope = JSON.parse(data.toString()) as ArohaEnvelope;
+          if (resolve) {
+            const r = resolve;
+            resolve = null;
+            r({ value: envelope, done: false });
+          } else {
+            queue.push(envelope);
+          }
+        });
+
+        ws.on("close", () => {
+          done = true;
+          if (resolve) {
+            const r = resolve;
+            resolve = null;
+            r({ value: undefined as unknown as ArohaEnvelope, done: true });
+          }
+        });
+
+        ws.on("error", (err) => {
+          error = err;
+          if (resolve) {
+            const r = resolve;
+            resolve = null;
+            r({ value: undefined as unknown as ArohaEnvelope, done: true });
+          }
+        });
+
+        return {
+          next(): Promise<IteratorResult<ArohaEnvelope>> {
+            if (error) return Promise.reject(error);
+            if (queue.length > 0) {
+              return Promise.resolve({ value: queue.shift()!, done: false });
+            }
+            if (done) {
+              return Promise.resolve({ value: undefined as unknown as ArohaEnvelope, done: true });
+            }
+            return new Promise((r) => { resolve = r; });
+          },
+          return(): Promise<IteratorResult<ArohaEnvelope>> {
+            ws.close();
+            return Promise.resolve({ value: undefined as unknown as ArohaEnvelope, done: true });
+          },
+        };
+      },
+    };
+  }
+
+  /**
+   * Fetch the DID Document from an agent's well-known endpoint.
+   */
+  async fetchDIDDocument(agentBaseUrl: string): Promise<Record<string, unknown>> {
+    const response = await fetch(`${agentBaseUrl}/.well-known/aroha-agent.json`);
+    if (!response.ok) throw new Error(`Failed to fetch DID Document from ${agentBaseUrl}`);
+    return response.json() as Promise<Record<string, unknown>>;
+  }
+}
+
+// ─── Errors ───────────────────────────────────────────────────────────────────
+
+export class ArohaTransportError extends Error {
+  constructor(
+    public readonly statusCode: number,
+    public readonly body: string
+  ) {
+    super(`Aroha transport error ${statusCode}: ${body}`);
+    this.name = "ArohaTransportError";
+  }
+}

package/src/transport/http-utils.ts

@@ -0,0 +1,30 @@
+import { type IncomingMessage } from "http";
+
+export function readBody(req: IncomingMessage, maxBytes = 1_048_576): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    let totalBytes = 0;
+    let settled = false;
+
+    const done = (fn: () => void) => {
+      if (settled) return;
+      settled = true;
+      fn();
+    };
+
+    req.on("data", (chunk: Buffer) => {
+      totalBytes += chunk.length;
+      if (totalBytes > maxBytes) {
+        const err = new Error("PAYLOAD_TOO_LARGE");
+        (err as NodeJS.ErrnoException).code = "PAYLOAD_TOO_LARGE";
+        done(() => reject(err));
+        req.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+
+    req.on("end", () => done(() => resolve(Buffer.concat(chunks).toString("utf8"))));
+    req.on("error", (err) => done(() => reject(err)));
+  });
+}

package/src/transport/index.ts

@@ -0,0 +1,3 @@
+export * from "./server.js";
+export * from "./client.js";
+export * from "./http-utils.js";

package/src/transport/server.ts

@@ -0,0 +1,383 @@
+/**
+ * Aroha Protocol — Layer 0 Transport Server (core)
+ *
+ * Responsibilities (protocol only):
+ *   - Serve /.well-known/aroha-agent.json
+ *   - Accept POST /aroha/v1, validate envelope (sig + nonce + expiry + recipient)
+ *   - Run optional middleware chain before dispatch
+ *   - Dispatch valid envelopes to the application handler
+ *   - Handle WebSocket streams
+ *   - Delegate unknown HTTP routes to optional httpRoutes handlers
+ *
+ * What this server deliberately does NOT do:
+ *   - RBAC / credential verification  →  @aroha-sdk/credentials createRbacMiddleware()
+ *   - Credential registry endpoints   →  @aroha-sdk/credentials credentialRegistryRoutes()
+ *   - Settlement                      →  @aroha-sdk/settlement
+ */
+
+import { createServer, type IncomingMessage, type ServerResponse } from "http";
+import { readBody } from "./http-utils.js";
+import { WebSocketServer, WebSocket } from "ws";
+import { randomBytes } from "@noble/hashes/utils";
+import { type ArohaEnvelope } from "../messages/envelope.js";
+import { validateEnvelope, type ValidationResult } from "../messages/envelope.js";
+import { NonceRegistry, type NonceStore } from "../messages/nonce.js";
+import { type DIDDocument } from "../identity/did.js";
+
+const PROTOCOL_VERSION = "1.0";
+
+// ─── Middleware types ──────────────────────────────────────────────────────────
+
+/**
+ * A ArohaMiddleware runs after envelope validation and before dispatch.
+ * Call reject() to short-circuit with an HTTP error. Return without calling
+ * reject to pass the envelope to the next middleware or the handler.
+ */
+export type ArohaMiddleware = (
+  envelope: ArohaEnvelope,
+  reject: (status: number, errorCode: string, reason: string) => void
+) => Promise<void>;
+
+/**
+ * An additional HTTP route registered on ArohaServer.
+ * Use credentialRegistryRoutes() from @aroha-sdk/credentials to mount the
+ * credential registry without coupling aroha-core to auth logic.
+ */
+export interface ArohaHttpRoute {
+  method: string;
+  test: (url: string) => boolean;
+  handle: (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+}
+
+// ─── Handler types ────────────────────────────────────────────────────────────
+
+export type MessageHandler = (
+  envelope: ArohaEnvelope,
+  respond: (reply: ArohaEnvelope) => void,
+  stream: (event: ArohaEnvelope) => void
+) => Promise<void>;
+
+import type { PublicKeyResolver } from "../identity/did-cache.js";
+export type { PublicKeyResolver };
+
+// ─── Options ──────────────────────────────────────────────────────────────────
+
+export interface ArohaServerOptions {
+  agentDID: string;
+  didDocument: DIDDocument;
+  port: number;
+  onMessage: MessageHandler;
+  resolvePublicKey: PublicKeyResolver;
+  /**
+   * Optional did:aroha-web: document to serve at the well-known path.
+   * When set, the server serves GET /.well-known/aroha/agents/{path}/did.json
+   * in addition to the standard /.well-known/aroha-agent.json endpoint.
+   */
+  webDIDDocument?: import("../identity/web-did.js").WebDIDDocument;
+  /**
+   * Middleware chain — runs in order after envelope validation.
+   * Any middleware may call reject() to abort processing.
+   * Mount RBAC here via createRbacMiddleware() from @aroha-sdk/credentials.
+   */
+  middleware?: ArohaMiddleware[];
+  /**
+   * Additional HTTP route handlers mounted alongside /aroha/v1.
+   * Checked in order after built-in routes. First match wins.
+   * Mount credential registry here via credentialRegistryRoutes() from @aroha-sdk/credentials.
+   */
+  httpRoutes?: ArohaHttpRoute[];
+  /**
+   * Trusted mesh / VPC mode: skip Ed25519 signature verification for senders
+   * whose DID matches this predicate. Use within private networks protected by
+   * mTLS or a VPC where network-level trust replaces cryptographic identity.
+   * Configure via @aroha-sdk/trusted-mesh createTrustedMeshOptions().
+   */
+  bypassSignatureFor?: (senderDID: string) => boolean;
+  /**
+   * Development mode — skips ALL cryptographic validation (signatures, nonce
+   * replay, expiry) so you can spin up agents with zero ceremony on localhost.
+   *
+   * Set devMode: false (or omit) before deploying to production. The flip
+   * requires no other code changes — your capability handlers are identical.
+   *
+   * @aroha-sdk/micro sets this automatically when devMode: true is passed there.
+   */
+  devMode?: boolean;
+  /**
+   * Minimum client protocol version accepted.
+   * Requests with X-Aroha-Client-Version below this are rejected with 400.
+   * Default: "1.0".
+   */
+  minClientVersion?: string;
+  /**
+   * Custom nonce store for distributed deployments.
+   * Defaults to in-process MapNonceStore (breaks in multi-instance deployments).
+   * In production, inject a Redis-backed NonceStore to share nonce state
+   * across all instances and prevent cross-instance replay attacks.
+   */
+  nonceStore?: NonceStore;
+  /**
+   * Clock skew tolerance applied to envelope expiry checks, in milliseconds.
+   * Recommended value for cross-region deployments: 5000.
+   * Default: 0 (strict — rejects messages expired by even 1ms).
+   */
+  clockToleranceMs?: number;
+  /**
+   * Maximum allowed request body size in bytes.
+   * Requests exceeding this limit are rejected with HTTP 413.
+   * Default: 1_048_576 (1 MiB).
+   */
+  maxBodyBytes?: number;
+}
+
+// ─── Server ───────────────────────────────────────────────────────────────────
+
+export class ArohaServer {
+  private readonly nonceRegistry: NonceRegistry;
+  private readonly wsClients = new Map<string, WebSocket>();
+  private readonly streamTokens = new Map<string, { cid: string; expiresMs: number }>();
+  private server: ReturnType<typeof createServer> | null = null;
+  private wss: WebSocketServer | null = null;
+
+  constructor(private readonly opts: ArohaServerOptions) {
+    this.nonceRegistry = new NonceRegistry(60_000, opts.nonceStore);
+  }
+
+  start(): Promise<void> {
+    if (this.opts.devMode) {
+      if (process.env.NODE_ENV !== "development") {
+        throw new Error(
+          `[Aroha] devMode can only be enabled when NODE_ENV=development. ` +
+          `Current NODE_ENV: "${process.env.NODE_ENV ?? "(unset)"}". ` +
+          `Remove devMode: true before deploying.`
+        );
+      }
+      console.warn(
+        "[Aroha] WARNING: devMode is ENABLED — ALL cryptographic validation is bypassed. " +
+        "Never use devMode in production."
+      );
+    }
+    return new Promise((resolve) => {
+      this.server = createServer((req, res) => this.handleHttp(req, res));
+      this.wss = new WebSocketServer({ server: this.server });
+      this.wss.on("connection", (ws, req) => this.handleWsConnection(ws, req));
+      this.server.listen(this.opts.port, () => {
+        console.log(`[Aroha] ${this.opts.agentDID} listening on port ${this.opts.port}`);
+        resolve();
+      });
+    });
+  }
+
+  stop(): Promise<void> {
+    this.nonceRegistry.destroy();
+    return new Promise((resolve, reject) => {
+      this.server?.close((err) => (err ? reject(err) : resolve()));
+    });
+  }
+
+  // ─── Version helpers ───────────────────────────────────────────────────────
+
+  private versionLessThan(a: string, b: string): boolean {
+    const [aMaj, aMin = 0] = a.split(".").map(Number);
+    const [bMaj, bMin = 0] = b.split(".").map(Number);
+    return aMaj < bMaj || (aMaj === bMaj && aMin < bMin);
+  }
+
+  private writeJson(res: ServerResponse, status: number, body: object): void {
+    res.writeHead(status, {
+      "Content-Type": "application/json",
+      "X-Aroha-Version": PROTOCOL_VERSION,
+    });
+    res.end(JSON.stringify(body));
+  }
+
+  // ─── HTTP ──────────────────────────────────────────────────────────────────
+
+  private async handleHttp(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    const url = req.url ?? "/";
+
+    if (req.method === "GET" && url === "/.well-known/aroha-agent.json") {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify(this.opts.didDocument));
+      return;
+    }
+
+    // did:aroha-web: well-known document — served at the agent's specific path
+    if (req.method === "GET" && this.opts.webDIDDocument) {
+      const { wellKnownPath } = await import("../identity/web-did.js");
+      const expectedPath = wellKnownPath(this.opts.webDIDDocument.id);
+      if (url === expectedPath || url === expectedPath.replace(/\/did\.json$/, "")) {
+        res.writeHead(200, {
+          "Content-Type":                "application/json",
+          "Access-Control-Allow-Origin": "*",
+          "Cache-Control":               "no-cache",
+        });
+        res.end(JSON.stringify(this.opts.webDIDDocument, null, 2));
+        return;
+      }
+    }
+
+    if (req.method === "POST" && url === "/aroha/v1") {
+      await this.handleInbound(req, res);
+      return;
+    }
+
+    for (const route of this.opts.httpRoutes ?? []) {
+      if (route.method === req.method && route.test(url)) {
+        await route.handle(req, res);
+        return;
+      }
+    }
+
+    res.writeHead(404);
+    res.end();
+  }
+
+  private async handleInbound(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    // ── Protocol version check ──────────────────────────────────────────────
+    const clientVersion = req.headers["x-aroha-client-version"] as string | undefined;
+    if (this.opts.minClientVersion) {
+      const effectiveVersion = clientVersion ?? "0.0";
+      if (this.versionLessThan(effectiveVersion, this.opts.minClientVersion)) {
+        this.writeJson(res, 400, {
+          error: `Protocol version ${effectiveVersion} below minimum ${this.opts.minClientVersion}`,
+          code: "VERSION_NOT_SUPPORTED",
+          serverVersion: PROTOCOL_VERSION,
+        });
+        return;
+      }
+    }
+
+    let body: string;
+    try {
+      body = await readBody(req, this.opts.maxBodyBytes ?? 1_048_576);
+    } catch (e) {
+      const code = (e as NodeJS.ErrnoException).code;
+      if (code === "PAYLOAD_TOO_LARGE") {
+        this.writeJson(res, 413, { error: "Payload too large" });
+        return;
+      }
+      this.writeJson(res, 400, { error: "Invalid body" });
+      return;
+    }
+
+    let envelope: ArohaEnvelope;
+    try { envelope = JSON.parse(body) as ArohaEnvelope; }
+    catch {
+      this.writeJson(res, 400, { error: "Invalid JSON" });
+      return;
+    }
+
+    // ── Dev mode: skip all crypto/auth — localhost hackathon mode ───────────
+    if (this.opts.devMode) {
+      let syncReply: ArohaEnvelope | null = null;
+      const respond = (reply: ArohaEnvelope) => { syncReply = reply; };
+      const stream  = (event: ArohaEnvelope) => {
+        const ws = this.wsClients.get(envelope.correlationId);
+        if (ws?.readyState === WebSocket.OPEN) ws.send(JSON.stringify(event));
+      };
+      await this.opts.onMessage(envelope, respond, stream);
+      if (syncReply) {
+        this.writeJson(res, 200, syncReply);
+      } else {
+        const streamToken = Buffer.from(randomBytes(16)).toString("base64url");
+        this.streamTokens.set(streamToken, { cid: envelope.correlationId, expiresMs: Date.now() + 30_000 });
+        this.writeJson(res, 202, { streamToken });
+      }
+      return;
+    }
+
+    const senderPubKey = await this.opts.resolvePublicKey(envelope.from);
+    if (!senderPubKey) {
+      this.writeJson(res, 401, { error: "Unknown sender DID" });
+      return;
+    }
+
+    const skipSignature = this.opts.bypassSignatureFor?.(envelope.from) ?? false;
+    const result: ValidationResult = await validateEnvelope(
+      envelope,
+      senderPubKey,
+      this.opts.agentDID,
+      this.nonceRegistry,
+      {
+        ...(skipSignature ? { skipSignature: true } : {}),
+        ...(this.opts.clockToleranceMs !== undefined
+          ? { clockToleranceMs: this.opts.clockToleranceMs }
+          : {}),
+      }
+    );
+
+    if (!result.valid) {
+      this.writeJson(res, 401, { error: result.reason });
+      return;
+    }
+
+    // ── Middleware chain ────────────────────────────────────────────────────
+    for (const mw of this.opts.middleware ?? []) {
+      let wasRejected = false;
+      let rejectStatus = 0, rejectCode = "", rejectReason = "";
+      await mw(envelope, (status, code, reason) => {
+        wasRejected = true; rejectStatus = status; rejectCode = code; rejectReason = reason;
+      });
+      if (wasRejected) {
+        this.writeJson(res, rejectStatus, { error: rejectReason, code: rejectCode });
+        return;
+      }
+    }
+
+    // ── Dispatch ────────────────────────────────────────────────────────────
+    let syncReply: ArohaEnvelope | null = null;
+    const respond = (reply: ArohaEnvelope) => { syncReply = reply; };
+    const stream  = (event: ArohaEnvelope) => {
+      const ws = this.wsClients.get(envelope.correlationId);
+      if (ws?.readyState === WebSocket.OPEN) ws.send(JSON.stringify(event));
+    };
+
+    await this.opts.onMessage(envelope, respond, stream);
+
+    if (syncReply) {
+      this.writeJson(res, 200, syncReply);
+    } else {
+      const streamToken = Buffer.from(randomBytes(16)).toString("base64url");
+      this.streamTokens.set(streamToken, { cid: envelope.correlationId, expiresMs: Date.now() + 30_000 });
+      this.writeJson(res, 202, { streamToken });
+    }
+  }
+
+  // ─── WebSocket ─────────────────────────────────────────────────────────────
+
+  private handleWsConnection(ws: WebSocket, req: IncomingMessage): void {
+    const url = new URL(req.url ?? "/", "http://localhost");
+    const cid = url.searchParams.get("cid");
+    if (!cid) { ws.close(1008, "Missing cid parameter"); return; }
+
+    const tok = url.searchParams.get("tok");
+
+    // In production mode, stream token is required.
+    // In devMode, the token is optional (hackathon / localhost convenience).
+    if (!this.opts.devMode) {
+      if (!tok) {
+        ws.close(1008, "Stream token required in production mode");
+        return;
+      }
+      // Consume first (atomic remove), then validate — prevents TOCTOU race
+      const entry = this.streamTokens.get(tok);
+      this.streamTokens.delete(tok);
+      if (!entry || entry.cid !== cid || entry.expiresMs < Date.now()) {
+        ws.close(1008, "Invalid or expired stream token");
+        return;
+      }
+    } else if (tok) {
+      // devMode but token provided — consume first, then validate
+      const entry = this.streamTokens.get(tok);
+      this.streamTokens.delete(tok);
+      if (!entry || entry.cid !== cid || entry.expiresMs < Date.now()) {
+        ws.close(1008, "Invalid or expired stream token");
+        return;
+      }
+    }
+
+    this.wsClients.set(cid, ws);
+    ws.on("close", () => this.wsClients.delete(cid));
+  }
+}

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "composite": true,
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["dist", "node_modules", "**/*.test.ts"]
+}