@aroha-sdk/core 1.0.0

package/src/messages/nonce.test.ts

@@ -0,0 +1,92 @@
+import { describe, it, expect } from "vitest";
+import { NonceRegistry, MapNonceStore, type NonceStore } from "./nonce.js";
+
+describe("MapNonceStore (default)", () => {
+  it("accepts a fresh nonce", () => {
+    const r = new NonceRegistry();
+    const exp = new Date(Date.now() + 60_000).toISOString();
+    expect(r.check("abc", exp)).toBe(true);
+  });
+
+  it("rejects a replayed nonce", () => {
+    const r = new NonceRegistry();
+    const exp = new Date(Date.now() + 60_000).toISOString();
+    r.check("abc", exp);
+    expect(r.check("abc", exp)).toBe(false);
+  });
+
+  it("evicts expired nonces", async () => {
+    const r = new NonceRegistry(100);
+    const exp = new Date(Date.now() - 1).toISOString(); // already expired
+    r.check("stale", exp);
+    await new Promise((res) => setTimeout(res, 150));
+    expect(r.size).toBe(0);
+  });
+
+  it("accepts a fresh nonce after expired one is evicted", async () => {
+    const r = new NonceRegistry(100);
+    const expiredAt = new Date(Date.now() - 1).toISOString();
+    r.check("stale", expiredAt);
+    await new Promise((res) => setTimeout(res, 150));
+    const freshExp = new Date(Date.now() + 60_000).toISOString();
+    expect(r.check("stale", freshExp)).toBe(true); // evicted, so fresh again
+  });
+});
+
+describe("custom NonceStore injection", () => {
+  it("delegates check to custom store", async () => {
+    const calls: string[] = [];
+    const store: NonceStore = {
+      async setIfAbsent(nonce, _expiryMs) {
+        calls.push(nonce);
+        return !calls.slice(0, -1).includes(nonce);
+      },
+      async evictExpired() {},
+    };
+    const r = new NonceRegistry(60_000, store);
+    const exp = new Date(Date.now() + 60_000).toISOString();
+    expect(await r.checkAsync("n1", exp)).toBe(true);
+    expect(await r.checkAsync("n1", exp)).toBe(false);
+    expect(calls).toEqual(["n1", "n1"]);
+  });
+});
+
+describe("NonceRegistry async path — injected store usage", () => {
+  it("calls the injected store, not the in-process map", async () => {
+    const calls: string[] = [];
+    const mockStore: NonceStore = {
+      setIfAbsent: async (nonce) => {
+        calls.push(nonce);
+        return true;
+      },
+      evictExpired: async () => {},
+    };
+    const registry = new NonceRegistry(60_000, mockStore);
+    const fresh = await registry.checkAsync(
+      "abc123",
+      new Date(Date.now() + 60_000).toISOString()
+    );
+    registry.destroy();
+    expect(fresh).toBe(true);
+    expect(calls).toContain("abc123");
+  });
+
+  it("returns false for a replayed nonce via injected store", async () => {
+    const seen = new Set<string>();
+    const mockStore: NonceStore = {
+      setIfAbsent: async (nonce) => {
+        if (seen.has(nonce)) return false;
+        seen.add(nonce);
+        return true;
+      },
+      evictExpired: async () => {},
+    };
+    const registry = new NonceRegistry(60_000, mockStore);
+    const expires = new Date(Date.now() + 60_000).toISOString();
+    const first = await registry.checkAsync("replay-me", expires);
+    const second = await registry.checkAsync("replay-me", expires);
+    registry.destroy();
+    expect(first).toBe(true);
+    expect(second).toBe(false);
+  });
+});

package/src/messages/nonce.ts

@@ -0,0 +1,116 @@
+/**
+ * Aroha Protocol — Nonce Registry
+ *
+ * Implements the spec rule:
+ *   "A receiving agent MUST reject any message where nonce has been seen before
+ *    (replay attack)"
+ *
+ * Nonces are stored with a TTL equal to the message's expires window.
+ * After a nonce expires it is automatically evicted to bound memory usage.
+ *
+ * This is protocol infrastructure. It has no knowledge of message contents.
+ */
+
+// ─── NonceStore interface ─────────────────────────────────────────────────────
+
+/**
+ * Pluggable nonce deduplication backend.
+ * Default: MapNonceStore (in-process). Production: inject a Redis adapter.
+ */
+export interface NonceStore {
+  /**
+   * Record a nonce and return true if it is fresh (first seen).
+   * Returns false if the nonce was already recorded (replay).
+   * expiryMs is the absolute expiry timestamp in milliseconds.
+   */
+  setIfAbsent(nonce: string, expiryMs: number): Promise<boolean>;
+  evictExpired(): Promise<void>;
+}
+
+// ─── Default in-process store ─────────────────────────────────────────────────
+
+export class MapNonceStore implements NonceStore {
+  private readonly seen = new Map<string, number>();
+
+  async setIfAbsent(nonce: string, expiryMs: number): Promise<boolean> {
+    if (this.seen.has(nonce)) return false;
+    this.seen.set(nonce, expiryMs);
+    return true;
+  }
+
+  async evictExpired(): Promise<void> {
+    const now = Date.now();
+    for (const [nonce, expiryMs] of this.seen) {
+      if (expiryMs < now) this.seen.delete(nonce);
+    }
+  }
+
+  get size(): number { return this.seen.size; }
+}
+
+// ─── Registry ─────────────────────────────────────────────────────────────────
+
+export class NonceRegistry {
+  private readonly store: NonceStore;
+  private readonly cleanupTimer: ReturnType<typeof setInterval>;
+  // Synchronous seen map for backward-compat check()
+  private readonly syncSeen = new Map<string, number>();
+
+  constructor(cleanupIntervalMs = 60_000, store?: NonceStore) {
+    this.store = store ?? new MapNonceStore();
+    this.cleanupTimer = setInterval(() => {
+      this.store.evictExpired().catch(() => {});
+      this.evictSyncSeen();
+    }, cleanupIntervalMs);
+    // Allow the process to exit even if this registry is still alive.
+    if (typeof this.cleanupTimer.unref === "function") this.cleanupTimer.unref();
+  }
+
+  /**
+   * Synchronous check — uses a dedicated in-process map.
+   * Use checkAsync when injecting a custom store.
+   *
+   * @param nonce     The nonce string from the message envelope
+   * @param expiresAt ISO8601 expiry time from the message's "expires" field
+   * @returns         true if the nonce is fresh (first time seen), false if replay
+   */
+  check(nonce: string, expiresAt: string): boolean {
+    const now = Date.now();
+    // Evict expired entries
+    for (const [n, exp] of this.syncSeen) {
+      if (exp < now) this.syncSeen.delete(n);
+    }
+    if (this.syncSeen.has(nonce)) return false;
+    this.syncSeen.set(nonce, new Date(expiresAt).getTime());
+    return true;
+  }
+
+  /**
+   * Async check — works with any NonceStore, including custom backends.
+   *
+   * @param nonce     The nonce string from the message envelope
+   * @param expiresAt ISO8601 expiry time from the message's "expires" field
+   * @returns         true if the nonce is fresh (first time seen), false if replay
+   */
+  async checkAsync(nonce: string, expiresAt: string): Promise<boolean> {
+    const expiryMs = new Date(expiresAt).getTime();
+    return this.store.setIfAbsent(nonce, expiryMs);
+  }
+
+  /** Number of nonces currently tracked (sync store). */
+  get size(): number {
+    return this.syncSeen.size;
+  }
+
+  /** Stop the background cleanup timer. Call when the owning server shuts down. */
+  destroy(): void {
+    clearInterval(this.cleanupTimer);
+  }
+
+  private evictSyncSeen(): void {
+    const now = Date.now();
+    for (const [n, exp] of this.syncSeen) {
+      if (exp < now) this.syncSeen.delete(n);
+    }
+  }
+}

package/src/messages/types.ts

@@ -0,0 +1,357 @@
+/**
+ * Aroha Protocol — Layer 3 Message Type Definitions
+ *
+ * All message types defined by the Aroha spec (aroha/1.0).
+ * These are the ONLY valid values for the "type" field in a Aroha envelope.
+ *
+ * Applications may not invent new top-level message types — they extend
+ * behavior through the "body" field only.
+ */
+
+// ─── Credential Token (Layer 1 extension — carried in message body) ──────────
+//
+// Human-triggered messages attach a base64url HumanCredential token here.
+// Provider agents verify the token against the issuer's public key.
+// Agent-to-agent messages omit this field; roles are resolved from the DID.
+
+export interface WithCredential {
+  /**
+   * Registry-based auth: the credential ID returned on registration.
+   * The receiving agent resolves the full credential from the registry.
+   * Preferred over credentialToken for repeated calls — shorter and revocable.
+   */
+  credentialId?: string;
+  /**
+   * Inline auth: base64url-encoded signed HumanCredential.
+   * Used when no shared registry is available (e.g. first call or direct peer).
+   * If credentialId is also present, credentialId takes precedence.
+   */
+  credentialToken?: string;
+}
+
+// ─── Preference Context (Layer 5, carried in message body) ───────────────────
+
+export interface PreferenceContext {
+  budget?: { max: number; currency: string };
+  quality?: { minRating?: number };
+  accessibility?: Record<string, boolean | string>;
+  constraints?: string[];
+  /** Signed VC granting the recipient access to read this context */
+  consentToken?: string;
+}
+
+// ─── Message Body Definitions ─────────────────────────────────────────────────
+
+export interface ArohaRequestBody extends WithCredential {
+  capability: string;
+  params: Record<string, unknown>;
+  preferenceContext?: PreferenceContext;
+  /**
+   * Idempotency key — if set, the receiving agent deduplicates requests with
+   * the same key from the same sender within a 24-hour window.
+   * Prevents duplicate side effects on retried requests (e.g. double-booking).
+   * Use a UUID generated once per logical operation, not per retry attempt.
+   */
+  idempotencyKey?: string;
+}
+
+export interface ArohaResponseBody {
+  capability: string;
+  result: Record<string, unknown>;
+}
+
+export interface ArohaStreamBody {
+  capability: string;
+  progressPct: number; // 0–100
+  event: string;
+  data?: Record<string, unknown>;
+}
+
+// ─── Capability Schema Negotiation (CSN) ─────────────────────────────────────
+// Extends the existing ArohaNegotiate flow with intent-based capability
+// discovery. Structural JSON Schema matching is deterministic and preferred;
+// an LLM matcher is used only when schema matching is ambiguous.
+// Agreed mappings are SHA-256 cached for zero-round-trip reuse.
+
+export interface CapabilitySchemaShape {
+  /** JSON Schema for the capability's input body (params field). */
+  input: Record<string, unknown>;
+  /** JSON Schema for the capability's expected output (result field). */
+  output?: Record<string, unknown>;
+}
+
+export interface CSNNegotiateExtension {
+  /**
+   * Natural-language description of what the requestor needs.
+   * The provider uses this as a hint when structural schema matching is
+   * ambiguous. Absent means "use schema-only matching".
+   */
+  capabilityIntent?: string;
+  /**
+   * JSON Schema of the requestor's expected interface.
+   * The provider runs structural compatibility matching against its registry.
+   * If a high-confidence match is found, no LLM call is needed.
+   */
+  desiredSchema?: CapabilitySchemaShape;
+  /**
+   * SHA-256 hex of the canonical desiredSchema JSON.
+   * The provider checks its cache first — if a mapping exists for this hash
+   * and this sender DID, the negotiation resolves in < 1ms without LLM.
+   */
+  schemaHash?: string;
+  /**
+   * If true, the provider returns its full signed capability manifest
+   * in the ArohaAccept body. The requestor caches it for future calls.
+   */
+  requestCapabilityManifest?: boolean;
+  /**
+   * When true, the provider MUST NOT use LLM-based fuzzy matching.
+   * If structural/cache match fails, return ArohaError with code CSN_NO_STRUCTURAL_MATCH.
+   */
+  disallowLLMFallback?: boolean;
+}
+
+export interface CapabilityManifestEntry {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  outputSchema?: Record<string, unknown>;
+  supportsSaga: boolean;
+  defaultPricing?: { model: "per-call" | "subscription" | "negotiated"; amount?: number; currency?: string };
+  defaultSLA?: { maxResponseMs: number; p99Ms?: number };
+}
+
+export interface SignedCapabilityManifest {
+  agentDID: string;
+  capabilities: CapabilityManifestEntry[];
+  generatedAt: string;
+  /** Ed25519 signature over the canonical manifest JSON. */
+  signature: string;
+}
+
+export interface ArohaNegotiateBody {
+  capability: string;
+  proposedTerms: {
+    price?: { amount: number; currency: string };
+    sla?: { maxResponseMs: number; uptime: number };
+    validForMs?: number;
+    [key: string]: unknown;
+  };
+  /** CSN extension — omit for traditional price/SLA-only negotiation. */
+  csn?: CSNNegotiateExtension;
+}
+
+export interface CSNAcceptExtension {
+  /**
+   * The actual registered capability name that matched the intent/schema.
+   * May differ from the `capability` field when CSN resolves an alias.
+   */
+  resolvedCapability?: string;
+  /** The schema the provider agreed to serve. Stored by requestor for caching. */
+  agreedSchema?: CapabilitySchemaShape;
+  /** Echo of the requestor's schemaHash — allows cache population. */
+  schemaHash?: string;
+  /** Returned when requestCapabilityManifest was true. */
+  capabilityManifest?: SignedCapabilityManifest;
+  /**
+   * How the capability was matched:
+   * "schema" — deterministic structural match (preferred, no LLM)
+   * "intent" — LLM-assisted match (less certain, human approval recommended)
+   * "cache"  — recovered from SHA-256 negotiation cache (zero-latency)
+   */
+  matchMethod?: "schema" | "intent" | "cache";
+  /** Structural compatibility score (0–1) when matchMethod is "schema". */
+  compatibilityScore?: number;
+  /**
+   * Audit trail of how the match was resolved.
+   * Consumers can use this to tune caching or flag unexpected LLM usage.
+   */
+  matchAudit?: {
+    structuralScore?: number;
+    cacheHit?: boolean;
+    llmUsed: boolean;
+    llmModel?: string;
+    fallbackReason?: string;
+  };
+}
+
+export interface ArohaCounterOfferBody {
+  capability: string;
+  revisedTerms: ArohaNegotiateBody["proposedTerms"];
+  csn?: Pick<CSNAcceptExtension, "resolvedCapability" | "agreedSchema" | "capabilityManifest">;
+}
+
+export interface ArohaAcceptBody {
+  capability: string;
+  acceptedTerms: ArohaNegotiateBody["proposedTerms"];
+  /** CSN extension — present when the accept resolves a capability schema match. */
+  csn?: CSNAcceptExtension;
+}
+
+export interface ArohaReserveBody extends WithCredential {
+  capability: string;
+  params: Record<string, unknown>;
+  holdDurationMs: number;
+  preferenceContext?: PreferenceContext;
+}
+
+export interface ArohaReserveAckBody {
+  reservationToken: string;
+  expiresAt: string; // ISO8601
+}
+
+export interface ArohaCommitBody {
+  reservationToken: string;
+}
+
+export interface ArohaCommitAckBody {
+  reservationToken: string;
+  result: Record<string, unknown>;
+}
+
+export interface ArohaCancelBody {
+  reservationToken: string;
+  reason: string;
+}
+
+export interface ArohaCancelAckBody {
+  reservationToken: string;
+}
+
+export interface ArohaDelegateBody extends WithCredential {
+  targetDID: string;
+  capability: string;
+  params: Record<string, unknown>;
+  preferenceContext?: PreferenceContext;
+}
+
+export interface ArohaErrorBody {
+  code: ArohaErrorCode;
+  message: string;
+  retryable: boolean;
+  details?: Record<string, unknown>;
+}
+
+export interface ArohaSatisfactionSignalBody {
+  sagaId: string;
+  agentDID: string;
+  /** The capability this signal applies to (e.g. "search-flights"). */
+  capability: string;
+  outcome: "satisfied" | "neutral" | "dissatisfied";
+  dimensions: {
+    price: "satisfied" | "neutral" | "dissatisfied";
+    quality: "satisfied" | "neutral" | "dissatisfied";
+    speed: "satisfied" | "neutral" | "dissatisfied";
+  };
+  /** Whether the saga completed within the provider's stated SLA. */
+  withinSLA: boolean;
+  /** Whether a compensation (ArohaCancel) was required to recover. */
+  requiredCompensation: boolean;
+}
+
+/**
+ * ArohaSpendingMandate — Layer 1 authorization token for agent payments.
+ *
+ * Enables agents to spend funds on behalf of a user without ever seeing
+ * raw payment credentials. Each hop in the delegation chain can only
+ * narrow constraints — never widen them.
+ *
+ * Mandate chain: User (intent) → Personal Agent (cart) → Provider (payment).
+ *
+ * References:
+ *   AP2 Protocol (Google) — Intent/Cart/Payment Mandate pattern.
+ *   IETF draft-niyikiza-oauth-attenuating-agent-tokens — monotonic scope narrowing.
+ */
+export interface ArohaSpendingMandateBody {
+  mandateTier: "intent" | "cart" | "payment";
+  constraints: SpendingConstraints;
+  grantee: string;   // DID of the agent receiving this mandate
+  grantor: string;   // DID of the agent issuing this mandate
+  expiresAt: string; // ISO8601
+  parentMandateId: string | null;
+  mandateId: string;
+}
+
+export interface SpendingConstraints {
+  spendLimitUsd: number;
+  sessionLimitUsd?: number;
+  currency?: string;                        // ISO 4217, default "USD"
+  merchantCategory?: string | null;         // MCC allow-list; null = any
+  requireHumanApprovalAboveUsd?: number;
+  allowedMerchants?: string[] | null;       // DID allow-list; null = any
+  validFrom?: string;                       // ISO8601
+  validUntil?: string;                      // ISO8601
+}
+
+// ─── Error Codes ──────────────────────────────────────────────────────────────
+
+export enum ArohaErrorCode {
+  // Auth / access errors
+  Unauthorized          = "Aroha_UNAUTHORIZED",   // missing or invalid credential
+  Forbidden             = "Aroha_FORBIDDEN",       // credential valid but role denied
+
+  // Protocol errors
+  InvalidSignature      = "Aroha_INVALID_SIGNATURE",
+  ExpiredMessage        = "Aroha_EXPIRED_MESSAGE",
+  ReplayDetected        = "Aroha_REPLAY_DETECTED",
+  UnknownCapability     = "Aroha_UNKNOWN_CAPABILITY",
+  TrustLevelInsufficient = "Aroha_TRUST_LEVEL_INSUFFICIENT",
+
+  // Saga errors
+  ReservationFailed     = "Aroha_RESERVATION_FAILED",
+  ReservationExpired    = "Aroha_RESERVATION_EXPIRED",
+  CommitFailed          = "Aroha_COMMIT_FAILED",
+  CancelFailed          = "Aroha_CANCEL_FAILED",
+  InvalidToken          = "Aroha_INVALID_TOKEN",
+
+  // Availability errors
+  NoInventory           = "Aroha_NO_INVENTORY",
+  CapacityExceeded      = "Aroha_CAPACITY_EXCEEDED",
+  ServiceUnavailable    = "Aroha_SERVICE_UNAVAILABLE",
+
+  // Generic
+  InternalError         = "Aroha_INTERNAL_ERROR",
+  InvalidParams         = "Aroha_INVALID_PARAMS",
+
+  // CSN errors
+  CSN_NO_STRUCTURAL_MATCH = "CSN_NO_STRUCTURAL_MATCH",
+}
+
+// ─── Message Type Union ───────────────────────────────────────────────────────
+
+export type ArohaMessageType =
+  | "ArohaRequest"
+  | "ArohaResponse"
+  | "ArohaStream"
+  | "ArohaNegotiate"
+  | "ArohaCounterOffer"
+  | "ArohaAccept"
+  | "ArohaReserve"
+  | "ArohaReserveAck"
+  | "ArohaCommit"
+  | "ArohaCommitAck"
+  | "ArohaCancel"
+  | "ArohaCancelAck"
+  | "ArohaDelegate"
+  | "ArohaError"
+  | "ArohaSatisfactionSignal"
+  | "ArohaSpendingMandate";
+
+export type ArohaBodyByType = {
+  ArohaRequest:           ArohaRequestBody;
+  ArohaResponse:          ArohaResponseBody;
+  ArohaStream:            ArohaStreamBody;
+  ArohaNegotiate:         ArohaNegotiateBody;
+  ArohaCounterOffer:      ArohaCounterOfferBody;
+  ArohaAccept:            ArohaAcceptBody;
+  ArohaReserve:           ArohaReserveBody;
+  ArohaReserveAck:        ArohaReserveAckBody;
+  ArohaCommit:            ArohaCommitBody;
+  ArohaCommitAck:         ArohaCommitAckBody;
+  ArohaCancel:            ArohaCancelBody;
+  ArohaCancelAck:         ArohaCancelAckBody;
+  ArohaDelegate:          ArohaDelegateBody;
+  ArohaError:             ArohaErrorBody;
+  ArohaSatisfactionSignal: ArohaSatisfactionSignalBody;
+  ArohaSpendingMandate:   ArohaSpendingMandateBody;
+};