@vauban-org/agent-sdk 0.16.0

package/src/auth/nonce-store.ts

@@ -0,0 +1,79 @@
+/**
+ * nonce-store — Replay attack prevention via nonce deduplication.
+ *
+ * NonceStore tracks seen idempotencyKeys within a TTL window to prevent
+ * replay attacks. The Redis implementation uses SET NX PX for atomic ops.
+ * The InMemory implementation is for testing only.
+ *
+ * ADR-ECO-017: nonce dedup via Redis SETNX TTL 10 min (auth side).
+ *
+ * @module auth/nonce-store
+ * @public
+ */
+
+export interface NonceStore {
+  /**
+   * Atomically sets the key if it does not exist.
+   *
+   * @param key   - Nonce/idempotencyKey to register.
+   * @param ttlMs - Time-to-live in milliseconds.
+   * @returns true if the key was newly set (first occurrence), false if already exists (replay).
+   */
+  setNX(key: string, ttlMs: number): Promise<boolean>;
+}
+
+/**
+ * In-memory NonceStore for unit tests.
+ * NOT for production — no persistence, no distributed dedup.
+ */
+export class InMemoryNonceStore implements NonceStore {
+  private readonly store = new Map<string, number>();
+
+  async setNX(key: string, ttlMs: number): Promise<boolean> {
+    const now = Date.now();
+    // Evict expired entries on each call (bounded cleanup)
+    for (const [k, expiry] of this.store.entries()) {
+      if (expiry <= now) this.store.delete(k);
+    }
+
+    if (this.store.has(key)) {
+      return false; // duplicate
+    }
+    this.store.set(key, now + ttlMs);
+    return true;
+  }
+
+  /** Test helper: clear all state. */
+  reset(): void {
+    this.store.clear();
+  }
+}
+
+/**
+ * Minimal Redis client interface required by RedisNonceStore.
+ * Compatible with ioredis and node-redis clients.
+ */
+export interface RedisClientLike {
+  set(
+    key: string,
+    value: string,
+    options: { nx: true; px: number }
+  ): Promise<string | null>;
+}
+
+/**
+ * Redis-backed NonceStore for production.
+ * Uses SET key value NX PX ttlMs — atomic, no race condition.
+ */
+export class RedisNonceStore implements NonceStore {
+  constructor(private readonly redis: RedisClientLike) {}
+
+  async setNX(key: string, ttlMs: number): Promise<boolean> {
+    const result = await this.redis.set(`vauban:nonce:${key}`, "1", {
+      nx: true,
+      px: ttlMs,
+    });
+    // SET NX returns "OK" on success, null if key already exists
+    return result !== null;
+  }
+}

package/src/auth/sign-event.ts

@@ -0,0 +1,51 @@
+/**
+ * sign-event — HMAC-SHA256 event signing helpers.
+ *
+ * ADR-ECO-017 canonical signature scheme:
+ *   HMAC-SHA256(key, type|source|timestamp|idempotencyKey|sha256(payload))
+ *
+ * IMPORTANT: This is the ONLY place in the codebase where crypto.createHmac
+ * is permitted for event signing. Direct usage outside this file is forbidden
+ * (enforced by CI lint rule no-direct-hmac-outside-sdk).
+ *
+ * @module auth/sign-event
+ * @public
+ */
+
+import { createHmac, createHash } from "node:crypto";
+import type { DomainEvent } from "../ports/event-bus.js";
+
+/**
+ * Builds the canonical string used as HMAC input.
+ * Format: type|source|timestamp|idempotencyKey|sha256(payload)
+ */
+export function canonicalEventString(
+  event: Omit<DomainEvent, "signature">,
+  payloadHash: string
+): string {
+  return [
+    event.type,
+    event.source,
+    event.timestamp,
+    event.idempotencyKey,
+    payloadHash,
+  ].join("|");
+}
+
+/**
+ * Signs an event using HMAC-SHA256 with the provided secret.
+ *
+ * @param event  - Event without signature field.
+ * @param secret - HMAC key (hex string or raw string).
+ * @returns Lowercase hex MAC (64 chars).
+ */
+export function signEvent(
+  event: Omit<DomainEvent, "signature">,
+  secret: string
+): string {
+  const payloadHash = createHash("sha256")
+    .update(JSON.stringify(event.payload))
+    .digest("hex");
+  const data = canonicalEventString(event, payloadHash);
+  return createHmac("sha256", secret).update(data).digest("hex");
+}

package/src/auth/verify-event.ts

@@ -0,0 +1,112 @@
+/**
+ * verify-event — HMAC-SHA256 event verification with replay protection.
+ *
+ * Performs 3 checks in order per ADR-ECO-017:
+ *   1. Signature equality (timing-safe via timingSafeEqual)
+ *   2. Clock skew within window (default 5 min)
+ *   3. Nonce dedup via NonceStore (if provided)
+ *
+ * Throws typed errors: InvalidSignatureError | ClockSkewError |
+ *   ReplayDetectedError | UnknownSourceError
+ *
+ * @module auth/verify-event
+ * @public
+ */
+
+import { timingSafeEqual } from "node:crypto";
+import type { DomainEvent } from "../ports/event-bus.js";
+import { signEvent } from "./sign-event.js";
+import {
+  ClockSkewError,
+  InvalidSignatureError,
+  ReplayDetectedError,
+  UnknownSourceError,
+} from "./errors.js";
+import type { NonceStore } from "./nonce-store.js";
+
+/** Valid event sources per ADR-ECO-017. */
+const VALID_SOURCES = new Set([
+  "forge",
+  "vauban",
+  "vauban-finance",
+  "brain",
+  "citadel",
+  "glacis",
+  "cc",
+  "tenant",
+]);
+
+/** Default replay window: 5 minutes. */
+const DEFAULT_MAX_CLOCK_SKEW_MS = 5 * 60 * 1000;
+
+/** Default nonce TTL: 10 minutes. */
+const DEFAULT_NONCE_TTL_MS = 10 * 60 * 1000;
+
+export interface VerifyEventOptions {
+  /** Maximum allowed clock skew in milliseconds. Default: 300_000 (5 min). */
+  maxClockSkewMs?: number;
+  /** NonceStore for replay protection. If absent, replay check is skipped. */
+  nonceStore?: NonceStore;
+}
+
+/**
+ * Verifies a signed DomainEvent.
+ *
+ * @param event     - The full DomainEvent including signature field.
+ * @param secret    - HMAC key used to verify the signature.
+ * @param opts      - Optional clock skew tolerance and nonce store.
+ * @returns true if the event is valid.
+ * @throws {UnknownSourceError}     if event.source is not in the allowed enum.
+ * @throws {InvalidSignatureError}  if the HMAC does not match.
+ * @throws {ClockSkewError}         if the timestamp is outside the allowed window.
+ * @throws {ReplayDetectedError}    if the nonce was already seen (replay attack).
+ */
+export async function verifyEvent(
+  event: DomainEvent,
+  secret: string,
+  opts?: VerifyEventOptions
+): Promise<true> {
+  const maxClockSkewMs = opts?.maxClockSkewMs ?? DEFAULT_MAX_CLOCK_SKEW_MS;
+  const nonceStore = opts?.nonceStore;
+
+  // 1. Source validation — before signature check to fail fast on unknown sources
+  if (!VALID_SOURCES.has(event.source)) {
+    throw new UnknownSourceError(event.source);
+  }
+
+  // 2. Signature verification (timing-safe)
+  const { signature, ...eventWithoutSig } = event;
+  const expected = signEvent(eventWithoutSig, secret);
+
+  // Compare using timing-safe equality to prevent timing attacks
+  const expectedBuf = Buffer.from(expected, "utf8");
+  const actualBuf = Buffer.from(signature, "utf8");
+
+  // Buffers must be same length for timingSafeEqual; if different lengths → invalid
+  if (
+    expectedBuf.length !== actualBuf.length ||
+    !timingSafeEqual(expectedBuf, actualBuf)
+  ) {
+    throw new InvalidSignatureError();
+  }
+
+  // 3. Clock skew check
+  const eventTime = Date.parse(event.timestamp);
+  const skewMs = Math.abs(Date.now() - eventTime);
+  if (skewMs > maxClockSkewMs) {
+    throw new ClockSkewError(skewMs);
+  }
+
+  // 4. Nonce dedup (replay protection)
+  if (nonceStore !== undefined) {
+    const isNew = await nonceStore.setNX(
+      event.idempotencyKey,
+      DEFAULT_NONCE_TTL_MS
+    );
+    if (!isNew) {
+      throw new ReplayDetectedError(event.idempotencyKey);
+    }
+  }
+
+  return true;
+}

package/src/boot/init-sdk.ts

@@ -0,0 +1,92 @@
+/**
+ * initSDK — SDK runtime initialization at agent boot.
+ *
+ * Promoted from forge/src/agents/shared/startup.ts (Vague 1.B.2).
+ * Forge-specific coupling neutralized:
+ * - CC_REGISTRY_URL hardcoded → parameterizable via `registryUrl` option
+ * - CC_SERVICE_TOKEN env var → kept as env var (secret, cannot be in code)
+ * - OTel collector URL → parameterizable
+ *
+ * @public @since 0.17.0
+ */
+
+import { initVaubanSDK } from "../otel/ingest.js";
+import type { BasicTracerProvider } from "@opentelemetry/sdk-trace-base";
+
+// ─── InitSDKOptions ───────────────────────────────────────────────────────────
+
+/**
+ * Options for initSDK.
+ *
+ * @public
+ */
+export interface InitSDKOptions {
+  /** Agent identifier (e.g. "forge-revenue"). */
+  agentId: string;
+  /** Agent semver version string. */
+  agentVersion: string;
+  /** Organization ID (e.g. "forge", "vauban", "cc"). */
+  orgId: string;
+  /** Human-readable agent name (default: agentId). */
+  agentName?: string;
+  /** Declared capabilities for the CC registry. */
+  capabilities?: string[];
+  /** Repository URL for the agent card. */
+  repoUrl?: string;
+  /**
+   * Command Center registry URL for auto-registration.
+   * When omitted, auto-registration is skipped.
+   * Default env fallback: `CC_REGISTRY_URL` environment variable.
+   */
+  registryUrl?: string;
+  /**
+   * OTel collector endpoint.
+   * Default: `http://alloy.observability.svc.cluster.local:4318`
+   */
+  collectorUrl?: string;
+  /** Enable console span exporter for local debugging. */
+  debug?: boolean;
+}
+
+// ─── initSDK ─────────────────────────────────────────────────────────────────
+
+/**
+ * Initialize OTel SDK + ports + agent registry at boot.
+ *
+ * Steps:
+ * 1. Calls `initVaubanSDK` to set up OTel OTLP exporter + W3C propagator.
+ * 2. Registers the agent in the CC registry (fire-and-forget, non-fatal).
+ *
+ * Returns the OTel BasicTracerProvider for introspection.
+ * Registration errors are logged as warnings and never throw.
+ *
+ * @example
+ * ```ts
+ * initSDK({
+ *   agentId: "forge-revenue",
+ *   agentVersion: "1.0.0",
+ *   orgId: "forge",
+ *   capabilities: ["revenue-tracking", "gtm"],
+ *   repoUrl: "https://github.com/vauban/forge",
+ * });
+ * ```
+ *
+ * @public
+ */
+export function initSDK(opts: InitSDKOptions): BasicTracerProvider {
+  const registryUrl = opts.registryUrl ?? process.env["CC_REGISTRY_URL"];
+  const apiKey = process.env["VAUBAN_API_KEY"] ?? "";
+
+  return initVaubanSDK({
+    apiKey,
+    agentId: opts.agentId,
+    agentVersion: opts.agentVersion,
+    orgId: opts.orgId,
+    agentName: opts.agentName ?? opts.agentId,
+    capabilities: opts.capabilities ?? [],
+    repoUrl: opts.repoUrl,
+    collectorUrl: opts.collectorUrl,
+    registryUrl,
+    debug: opts.debug,
+  });
+}

package/src/boot/load-agent-context.ts

@@ -0,0 +1,164 @@
+/**
+ * loadAgentContext — Brain context loading at agent boot.
+ *
+ * Promoted from forge/src/agents/shared/startup.ts (Vague 1.B.2).
+ * Forge-specific coupling neutralized:
+ * - "FORGE.md" hardcoded string → parameterizable via `projectMd` option
+ * - forge_config / forge_decision categories → parameterizable
+ *
+ * @public @since 0.17.0
+ */
+
+import type { BrainPort, BrainEntry } from "../ports/brain.js";
+import type { LoggerPort } from "../ports/logger.js";
+
+// ─── AgentContext ─────────────────────────────────────────────────────────────
+
+/**
+ * Context loaded from Brain at agent boot.
+ *
+ * @public
+ */
+export interface AgentContext {
+  /** Content of the project markdown document (e.g. FORGE.md), or null if not found. */
+  projectMdContent: string | null;
+  /** Recent decisions relevant to this agent's domain. */
+  recentDecisions: Array<{ content: string; created_at?: string }>;
+  /** Domain-specific context entries. */
+  domainContext: Array<{ content: string; created_at?: string }>;
+}
+
+// ─── LoadAgentContextOptions ──────────────────────────────────────────────────
+
+/**
+ * Options for loadAgentContext.
+ *
+ * @public
+ */
+export interface LoadAgentContextOptions {
+  /**
+   * Brain query string + category tag for the project markdown document.
+   * Example: `{ query: "FORGE.md 0-Employee Business OS", category: "forge_config", tag: "forge-md" }`
+   * When omitted, no projectMd query is performed.
+   */
+  projectMd?: {
+    /** FTS query string for the project markdown. */
+    query: string;
+    /** Brain category for the project markdown entry. */
+    category: string;
+    /** Brain tag for the project markdown entry. */
+    tag: string;
+  };
+  /** Category to use when querying recent decisions (default: "decision"). */
+  decisionsCategory?: string;
+  /** Maximum number of recent decisions to load (default: 10). */
+  recentDecisionsLimit?: number;
+  /** Domain tag categories for context loading (default: ["context"]). */
+  domainCategories?: string[];
+  /** Maximum number of domain context entries to load (default: 20). */
+  domainContextLimit?: number;
+}
+
+// ─── loadAgentContext ─────────────────────────────────────────────────────────
+
+/**
+ * Load agent context from Brain at boot.
+ *
+ * Three queries:
+ * 1. Optional project markdown document (e.g. FORGE.md, CLAUDE.md)
+ * 2. Recent decisions for the agent's domain tags
+ * 3. Domain-specific context entries
+ *
+ * All queries are non-fatal — failures log a warning and return empty data.
+ * This ensures agents can boot even when Brain is temporarily unavailable.
+ *
+ * @example
+ * ```ts
+ * const ctx = await loadAgentContext(brain, "forge-revenue", ["revenue", "gtm"], logger, {
+ *   projectMd: { query: "FORGE.md 0-Employee Business OS", category: "forge_config", tag: "forge-md" },
+ *   decisionsCategory: "forge_decision",
+ * });
+ * ```
+ *
+ * @public
+ */
+export async function loadAgentContext(
+  brain: BrainPort,
+  agentId: string,
+  domainTags: string[],
+  logger: LoggerPort,
+  opts: LoadAgentContextOptions = {}
+): Promise<AgentContext> {
+  const {
+    projectMd,
+    decisionsCategory = "decision",
+    recentDecisionsLimit = 10,
+    domainContextLimit = 20,
+  } = opts;
+
+  let projectMdContent: string | null = null;
+  let recentDecisions: Array<{ content: string; created_at?: string }> = [];
+  let domainContext: Array<{ content: string; created_at?: string }> = [];
+
+  // Query 1: project markdown (optional)
+  if (projectMd) {
+    try {
+      const entries = await brain.queryKnowledge?.(projectMd.query, {
+        category: projectMd.category,
+        tags: [projectMd.tag],
+        limit: 1,
+      });
+      if (entries && entries.length > 0) {
+        projectMdContent = entries[0]?.content ?? null;
+      }
+    } catch (err) {
+      logger.warn(
+        { err },
+        `[${agentId}] Failed to load project markdown from Brain`
+      );
+    }
+  }
+
+  // Query 2: recent decisions
+  try {
+    const decisions = await brain.queryKnowledge?.(
+      `recent decisions ${domainTags.join(" ")}`,
+      {
+        category: decisionsCategory,
+        tags: domainTags,
+        limit: recentDecisionsLimit,
+      }
+    );
+    recentDecisions = (decisions ?? []).map((e: BrainEntry) => ({
+      content: e.content,
+      created_at: e.created_at,
+    }));
+  } catch (err) {
+    logger.warn({ err }, `[${agentId}] Failed to load recent decisions`);
+  }
+
+  // Query 3: domain context
+  try {
+    const context = await brain.queryKnowledge?.(`${agentId} domain context`, {
+      tags: [agentId, ...domainTags],
+      limit: domainContextLimit,
+    });
+    domainContext = (context ?? []).map((e: BrainEntry) => ({
+      content: e.content,
+      created_at: e.created_at,
+    }));
+  } catch (err) {
+    logger.warn({ err }, `[${agentId}] Failed to load domain context`);
+  }
+
+  logger.info(
+    {
+      projectMdLoaded: projectMdContent !== null,
+      decisions: recentDecisions.length,
+      context: domainContext.length,
+    },
+    `[${agentId}] Context loaded`
+  );
+
+  return { projectMdContent, recentDecisions, domainContext };
+}

package/src/boot/load-recent-memory.ts

@@ -0,0 +1,92 @@
+/**
+ * loadRecentMemory — load recent agent outcomes from Brain at boot.
+ *
+ * Promoted from forge/src/agents/shared/startup.ts (Vague 1.B.2).
+ * Forge-specific coupling neutralized:
+ * - "forge_outcome" category → parameterizable
+ * - "forge" tag → parameterizable
+ *
+ * @public @since 0.17.0
+ */
+
+import type { BrainPort, BrainEntry } from "../ports/brain.js";
+
+// ─── LoadRecentMemoryOptions ─────────────────────────────────────────────────
+
+/**
+ * Options for loadRecentMemory.
+ *
+ * @public
+ */
+export interface LoadRecentMemoryOptions {
+  /** Brain category for outcome entries (default: "outcome"). */
+  category?: string;
+  /** Additional tags to filter entries (default: [agentId]). */
+  tags?: string[];
+  /** Maximum number of entries to load (default: 5). */
+  limit?: number;
+  /** Maximum total characters for the returned summary (default: 2000). */
+  maxChars?: number;
+  /** Maximum characters per entry preview (default: 300). */
+  maxEntryChars?: number;
+}
+
+// ─── loadRecentMemory ────────────────────────────────────────────────────────
+
+/**
+ * Load recent outcomes for an agent from Brain and return a concise text summary.
+ *
+ * Returns an empty string when Brain is unavailable or no entries exist —
+ * never throws, so agents can boot even when Brain is temporarily down.
+ *
+ * @example
+ * ```ts
+ * const memory = await loadRecentMemory(brain, "forge-revenue", {
+ *   category: "forge_outcome",
+ *   tags: ["forge", "agent:forge-revenue", "outcome"],
+ * });
+ * // → "2026-05-07: Revenue cycle completed: 3 leads qualified...\n..."
+ * ```
+ *
+ * @public
+ */
+export async function loadRecentMemory(
+  brain: BrainPort,
+  agentId: string,
+  opts: LoadRecentMemoryOptions = {}
+): Promise<string> {
+  const {
+    category = "outcome",
+    tags,
+    limit = 5,
+    maxChars = 2000,
+    maxEntryChars = 300,
+  } = opts;
+
+  const effectiveTags = tags ?? [agentId];
+
+  let entries: BrainEntry[] = [];
+  try {
+    entries =
+      (await brain.queryKnowledge?.("recent outcomes", {
+        category,
+        tags: effectiveTags,
+        limit,
+      })) ?? [];
+  } catch {
+    // Non-fatal: agent can still boot without memory
+    return "";
+  }
+
+  return entries
+    .map((e) => {
+      const date = e.created_at ?? "unknown";
+      const preview =
+        e.content.length > maxEntryChars
+          ? e.content.slice(0, maxEntryChars) + "..."
+          : e.content;
+      return `${date}: ${preview}`;
+    })
+    .join("\n")
+    .slice(0, maxChars);
+}