@vauban-org/agent-sdk 0.16.0

package/dist/agents/trading.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Agent-specific trading types — @vauban-org/agent-sdk v0.7.1 (sprint-526 Bloc 5b)
+ *
+ * Pure types + one pure helper. No I/O, no side effects.
+ *
+ * Types mirror the `trade_detail` DB schema (sprint-526:quick-1) so the SDK
+ * surface stays in sync with persistence without a direct DB dependency.
+ *
+ * @public
+ */
+/**
+ * A single trade record, mirroring the `trade_detail` table.
+ * All monetary values are in integer cents to avoid float64 rounding.
+ */
+export interface Trade {
+    id: string;
+    outcome_id: string;
+    agent_run_id: string | null;
+    symbol: string;
+    side: "BUY" | "SELL";
+    quantity: number;
+    entry_price_cents: number;
+    exit_price_cents: number | null;
+    pnl_cents: number | null;
+    slippage_bps: number | null;
+    alpaca_order_id: string;
+    trading_mode: "paper" | "live";
+    entry_at: string;
+    exit_at: string | null;
+    exit_reason: "stop" | "target" | "timeout" | "manual" | null;
+}
+/**
+ * Observable snapshot of a RiskGuard circuit-breaker instance.
+ * Mirrors the in-memory state exposed by the OODA RiskGuard.
+ */
+export interface RiskGuardState {
+    name: string;
+    state: "closed" | "open" | "half-open";
+    failure_count: number;
+    last_failure: string | null;
+    reset_after: string | null;
+}
+/**
+ * A single orientation-memory entry persisted to Brain.
+ * The `metadata.kind` discriminator enables efficient FTS filtering.
+ */
+export interface OrientationMemory {
+    entry_id: string;
+    content: string;
+    metadata: {
+        kind: "orientation-memory";
+        symbol: string;
+        regime: string;
+        observed_at: string;
+    };
+}
+/**
+ * Runtime-configurable thresholds for the trading-nq agent.
+ * Loaded via `AgentConfigLoader` so changes apply without restart.
+ */
+export interface TradingNQConfig {
+    thresholds: {
+        conviction_min: number;
+        kelly_cap: number;
+        kelly_bootstrap_fraction: number;
+        bootstrap_trade_threshold: number;
+        hitl_timeout_ms: number;
+        stop_loss_atr_multiple: number;
+        target_atr_multiple: number;
+        trade_timeout_minutes: number;
+    };
+}
+/**
+ * Compute a Kelly criterion sizing fraction with a bootstrap fallback.
+ *
+ * V5 anti-pattern #2 (piège 2): never apply full Kelly before sufficient
+ * historical data. When `historicalTradeCount < bootstrap_trade_threshold`,
+ * returns a conservative fixed fraction instead of the Kelly estimate.
+ *
+ * Variance is floored at `1e-9` to guard against divide-by-zero.
+ * Fraction is clamped to `[0, kelly_cap]` — never negative, never unbounded.
+ *
+ * @param historicalTradeCount - Completed trades available for calibration.
+ * @param expectedReturn       - Expected return per trade (e.g. mean PnL).
+ * @param variance             - Variance of returns (must be ≥ 0).
+ * @param config               - Cap + bootstrap parameters.
+ * @returns Sizing fraction and the mode used for traceability.
+ *
+ * @public
+ */
+export declare function computeKellyFraction(historicalTradeCount: number, expectedReturn: number, variance: number, config: {
+    kelly_cap: number;
+    kelly_bootstrap_fraction: number;
+    bootstrap_trade_threshold: number;
+}): {
+    fraction: number;
+    mode: "bootstrap" | "kelly";
+};
+//# sourceMappingURL=trading.d.ts.map

package/dist/agents/trading.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trading.d.ts","sourceRoot":"","sources":["../../src/agents/trading.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;GAGG;AACH,MAAM,WAAW,KAAK;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,KAAK,GAAG,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,OAAO,GAAG,MAAM,CAAC;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,WAAW,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,IAAI,CAAC;CAC9D;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;IACvC,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE;QACR,IAAI,EAAE,oBAAoB,CAAC;QAC3B,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;QACf,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE;QACV,cAAc,EAAE,MAAM,CAAC;QACvB,SAAS,EAAE,MAAM,CAAC;QAClB,wBAAwB,EAAE,MAAM,CAAC;QACjC,yBAAyB,EAAE,MAAM,CAAC;QAClC,eAAe,EAAE,MAAM,CAAC;QACxB,sBAAsB,EAAE,MAAM,CAAC;QAC/B,mBAAmB,EAAE,MAAM,CAAC;QAC5B,qBAAqB,EAAE,MAAM,CAAC;KAC/B,CAAC;CACH;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAClC,oBAAoB,EAAE,MAAM,EAC5B,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE;IACN,SAAS,EAAE,MAAM,CAAC;IAClB,wBAAwB,EAAE,MAAM,CAAC;IACjC,yBAAyB,EAAE,MAAM,CAAC;CACnC,GACA;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAA;CAAE,CASnD"}

package/dist/agents/trading.js

@@ -0,0 +1,39 @@
+/**
+ * Agent-specific trading types — @vauban-org/agent-sdk v0.7.1 (sprint-526 Bloc 5b)
+ *
+ * Pure types + one pure helper. No I/O, no side effects.
+ *
+ * Types mirror the `trade_detail` DB schema (sprint-526:quick-1) so the SDK
+ * surface stays in sync with persistence without a direct DB dependency.
+ *
+ * @public
+ */
+/**
+ * Compute a Kelly criterion sizing fraction with a bootstrap fallback.
+ *
+ * V5 anti-pattern #2 (piège 2): never apply full Kelly before sufficient
+ * historical data. When `historicalTradeCount < bootstrap_trade_threshold`,
+ * returns a conservative fixed fraction instead of the Kelly estimate.
+ *
+ * Variance is floored at `1e-9` to guard against divide-by-zero.
+ * Fraction is clamped to `[0, kelly_cap]` — never negative, never unbounded.
+ *
+ * @param historicalTradeCount - Completed trades available for calibration.
+ * @param expectedReturn       - Expected return per trade (e.g. mean PnL).
+ * @param variance             - Variance of returns (must be ≥ 0).
+ * @param config               - Cap + bootstrap parameters.
+ * @returns Sizing fraction and the mode used for traceability.
+ *
+ * @public
+ */
+export function computeKellyFraction(historicalTradeCount, expectedReturn, variance, config) {
+    if (historicalTradeCount < config.bootstrap_trade_threshold) {
+        return { fraction: config.kelly_bootstrap_fraction, mode: "bootstrap" };
+    }
+    const kelly = expectedReturn / Math.max(variance, 1e-9);
+    return {
+        fraction: Math.min(Math.max(kelly, 0), config.kelly_cap),
+        mode: "kelly",
+    };
+}
+//# sourceMappingURL=trading.js.map

package/dist/agents/trading.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trading.js","sourceRoot":"","sources":["../../src/agents/trading.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAoEH;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,oBAAoB,CAClC,oBAA4B,EAC5B,cAAsB,EACtB,QAAgB,EAChB,MAIC;IAED,IAAI,oBAAoB,GAAG,MAAM,CAAC,yBAAyB,EAAE,CAAC;QAC5D,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,wBAAwB,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;IAC1E,CAAC;IACD,MAAM,KAAK,GAAG,cAAc,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IACxD,OAAO;QACL,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,SAAS,CAAC;QACxD,IAAI,EAAE,OAAO;KACd,CAAC;AACJ,CAAC"}

package/dist/auth/errors.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Event auth errors — typed failures for cross-product event verification.
+ *
+ * ADR-ECO-017: verifyEvent throws typed errors for each failure mode.
+ * Consumers MUST catch and handle these explicitly (no silent ignore).
+ *
+ * @module auth/errors
+ * @public
+ */
+/** Thrown when the event's HMAC signature does not match the recomputed value. */
+export declare class InvalidSignatureError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Thrown when the event timestamp is outside the acceptable clock skew window.
+ * Default window: 5 minutes (±300 000 ms).
+ */
+export declare class ClockSkewError extends Error {
+    readonly skewMs: number;
+    constructor(skewMs: number);
+}
+/**
+ * Thrown when the nonce (idempotencyKey) has already been seen within the TTL window.
+ * Indicates a replay attack or duplicate delivery.
+ */
+export declare class ReplayDetectedError extends Error {
+    readonly idempotencyKey: string;
+    constructor(idempotencyKey: string);
+}
+/**
+ * Thrown when the event's source field is not in the allowed enum.
+ * Allowed sources: forge | vauban | vauban-finance | brain | citadel | glacis | cc | tenant
+ */
+export declare class UnknownSourceError extends Error {
+    readonly source: string;
+    constructor(source: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/auth/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/auth/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,kFAAkF;AAClF,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,OAAO,SAA+B;CAKnD;AAED;;;GAGG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBACZ,MAAM,EAAE,MAAM;CAQ3B;AAED;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;gBACpB,cAAc,EAAE,MAAM;CAQnC;AAED;;;GAGG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBACZ,MAAM,EAAE,MAAM;CAQ3B"}

package/dist/auth/errors.js

@@ -0,0 +1,57 @@
+/**
+ * Event auth errors — typed failures for cross-product event verification.
+ *
+ * ADR-ECO-017: verifyEvent throws typed errors for each failure mode.
+ * Consumers MUST catch and handle these explicitly (no silent ignore).
+ *
+ * @module auth/errors
+ * @public
+ */
+/** Thrown when the event's HMAC signature does not match the recomputed value. */
+export class InvalidSignatureError extends Error {
+    constructor(message = "Event signature is invalid") {
+        super(message);
+        this.name = "InvalidSignatureError";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * Thrown when the event timestamp is outside the acceptable clock skew window.
+ * Default window: 5 minutes (±300 000 ms).
+ */
+export class ClockSkewError extends Error {
+    skewMs;
+    constructor(skewMs) {
+        super(`Event timestamp skew (${skewMs}ms) exceeds the allowed window. Possible replay or clock drift.`);
+        this.name = "ClockSkewError";
+        this.skewMs = skewMs;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * Thrown when the nonce (idempotencyKey) has already been seen within the TTL window.
+ * Indicates a replay attack or duplicate delivery.
+ */
+export class ReplayDetectedError extends Error {
+    idempotencyKey;
+    constructor(idempotencyKey) {
+        super(`Replay detected: idempotencyKey "${idempotencyKey}" has already been processed within the nonce TTL window.`);
+        this.name = "ReplayDetectedError";
+        this.idempotencyKey = idempotencyKey;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * Thrown when the event's source field is not in the allowed enum.
+ * Allowed sources: forge | vauban | vauban-finance | brain | citadel | glacis | cc | tenant
+ */
+export class UnknownSourceError extends Error {
+    source;
+    constructor(source) {
+        super(`Unknown event source: "${source}". Must be one of: forge, vauban, vauban-finance, brain, citadel, glacis, cc, tenant.`);
+        this.name = "UnknownSourceError";
+        this.source = source;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/auth/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/auth/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,kFAAkF;AAClF,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAC9C,YAAY,OAAO,GAAG,4BAA4B;QAChD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QACpC,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,cAAe,SAAQ,KAAK;IAC9B,MAAM,CAAS;IACxB,YAAY,MAAc;QACxB,KAAK,CACH,yBAAyB,MAAM,iEAAiE,CACjG,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IACnC,cAAc,CAAS;IAChC,YAAY,cAAsB;QAChC,KAAK,CACH,oCAAoC,cAAc,2DAA2D,CAC9G,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,CAAC,cAAc,GAAG,cAAc,CAAC;QACrC,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAClC,MAAM,CAAS;IACxB,YAAY,MAAc;QACxB,KAAK,CACH,0BAA0B,MAAM,uFAAuF,CACxH,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF"}

package/dist/auth/nonce-store.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 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 declare class InMemoryNonceStore implements NonceStore {
+    private readonly store;
+    setNX(key: string, ttlMs: number): Promise<boolean>;
+    /** Test helper: clear all state. */
+    reset(): void;
+}
+/**
+ * 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 declare class RedisNonceStore implements NonceStore {
+    private readonly redis;
+    constructor(redis: RedisClientLike);
+    setNX(key: string, ttlMs: number): Promise<boolean>;
+}
+//# sourceMappingURL=nonce-store.d.ts.map

package/dist/auth/nonce-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nonce-store.d.ts","sourceRoot":"","sources":["../../src/auth/nonce-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,UAAU;IACzB;;;;;;OAMG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACrD;AAED;;;GAGG;AACH,qBAAa,kBAAmB,YAAW,UAAU;IACnD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA6B;IAE7C,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAczD,oCAAoC;IACpC,KAAK,IAAI,IAAI;CAGd;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,GAAG,CACD,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,OAAO,EAAE;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,GAChC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC3B;AAED;;;GAGG;AACH,qBAAa,eAAgB,YAAW,UAAU;IACpC,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAL,KAAK,EAAE,eAAe;IAE7C,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAQ1D"}

package/dist/auth/nonce-store.js

@@ -0,0 +1,55 @@
+/**
+ * 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
+ */
+/**
+ * In-memory NonceStore for unit tests.
+ * NOT for production — no persistence, no distributed dedup.
+ */
+export class InMemoryNonceStore {
+    store = new Map();
+    async setNX(key, ttlMs) {
+        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() {
+        this.store.clear();
+    }
+}
+/**
+ * Redis-backed NonceStore for production.
+ * Uses SET key value NX PX ttlMs — atomic, no race condition.
+ */
+export class RedisNonceStore {
+    redis;
+    constructor(redis) {
+        this.redis = redis;
+    }
+    async setNX(key, ttlMs) {
+        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;
+    }
+}
+//# sourceMappingURL=nonce-store.js.map

package/dist/auth/nonce-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nonce-store.js","sourceRoot":"","sources":["../../src/auth/nonce-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAaH;;;GAGG;AACH,MAAM,OAAO,kBAAkB;IACZ,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;IAEnD,KAAK,CAAC,KAAK,CAAC,GAAW,EAAE,KAAa;QACpC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,uDAAuD;QACvD,KAAK,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;YAC/C,IAAI,MAAM,IAAI,GAAG;gBAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QAC1C,CAAC;QAED,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACxB,OAAO,KAAK,CAAC,CAAC,YAAY;QAC5B,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,GAAG,KAAK,CAAC,CAAC;QACjC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,oCAAoC;IACpC,KAAK;QACH,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;CACF;AAcD;;;GAGG;AACH,MAAM,OAAO,eAAe;IACG;IAA7B,YAA6B,KAAsB;QAAtB,UAAK,GAAL,KAAK,CAAiB;IAAG,CAAC;IAEvD,KAAK,CAAC,KAAK,CAAC,GAAW,EAAE,KAAa;QACpC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,gBAAgB,GAAG,EAAE,EAAE,GAAG,EAAE;YAC9D,EAAE,EAAE,IAAI;YACR,EAAE,EAAE,KAAK;SACV,CAAC,CAAC;QACH,6DAA6D;QAC7D,OAAO,MAAM,KAAK,IAAI,CAAC;IACzB,CAAC;CACF"}

package/dist/auth/sign-event.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 type { DomainEvent } from "../ports/event-bus.js";
+/**
+ * Builds the canonical string used as HMAC input.
+ * Format: type|source|timestamp|idempotencyKey|sha256(payload)
+ */
+export declare function canonicalEventString(event: Omit<DomainEvent, "signature">, payloadHash: string): string;
+/**
+ * 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 declare function signEvent(event: Omit<DomainEvent, "signature">, secret: string): string;
+//# sourceMappingURL=sign-event.d.ts.map

package/dist/auth/sign-event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sign-event.d.ts","sourceRoot":"","sources":["../../src/auth/sign-event.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEzD;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,WAAW,CAAC,EACrC,WAAW,EAAE,MAAM,GAClB,MAAM,CAQR;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,WAAW,CAAC,EACrC,MAAM,EAAE,MAAM,GACb,MAAM,CAMR"}

package/dist/auth/sign-event.js

@@ -0,0 +1,42 @@
+/**
+ * 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";
+/**
+ * Builds the canonical string used as HMAC input.
+ * Format: type|source|timestamp|idempotencyKey|sha256(payload)
+ */
+export function canonicalEventString(event, payloadHash) {
+    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, secret) {
+    const payloadHash = createHash("sha256")
+        .update(JSON.stringify(event.payload))
+        .digest("hex");
+    const data = canonicalEventString(event, payloadHash);
+    return createHmac("sha256", secret).update(data).digest("hex");
+}
+//# sourceMappingURL=sign-event.js.map

package/dist/auth/sign-event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sign-event.js","sourceRoot":"","sources":["../../src/auth/sign-event.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGrD;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAClC,KAAqC,EACrC,WAAmB;IAEnB,OAAO;QACL,KAAK,CAAC,IAAI;QACV,KAAK,CAAC,MAAM;QACZ,KAAK,CAAC,SAAS;QACf,KAAK,CAAC,cAAc;QACpB,WAAW;KACZ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CACvB,KAAqC,EACrC,MAAc;IAEd,MAAM,WAAW,GAAG,UAAU,CAAC,QAAQ,CAAC;SACrC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;SACrC,MAAM,CAAC,KAAK,CAAC,CAAC;IACjB,MAAM,IAAI,GAAG,oBAAoB,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;IACtD,OAAO,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACjE,CAAC"}

package/dist/auth/verify-event.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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 type { DomainEvent } from "../ports/event-bus.js";
+import type { NonceStore } from "./nonce-store.js";
+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 declare function verifyEvent(event: DomainEvent, secret: string, opts?: VerifyEventOptions): Promise<true>;
+//# sourceMappingURL=verify-event.d.ts.map

package/dist/auth/verify-event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-event.d.ts","sourceRoot":"","sources":["../../src/auth/verify-event.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAQzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAoBnD,MAAM,WAAW,kBAAkB;IACjC,4EAA4E;IAC5E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,4EAA4E;IAC5E,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,kBAAkB,GACxB,OAAO,CAAC,IAAI,CAAC,CA4Cf"}

package/dist/auth/verify-event.js

@@ -0,0 +1,78 @@
+/**
+ * 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 { signEvent } from "./sign-event.js";
+import { ClockSkewError, InvalidSignatureError, ReplayDetectedError, UnknownSourceError, } from "./errors.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;
+/**
+ * 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, secret, opts) {
+    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;
+}
+//# sourceMappingURL=verify-event.js.map

package/dist/auth/verify-event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-event.js","sourceRoot":"","sources":["../../src/auth/verify-event.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EACL,cAAc,EACd,qBAAqB,EACrB,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAGrB,2CAA2C;AAC3C,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC;IAC5B,OAAO;IACP,QAAQ;IACR,gBAAgB;IAChB,OAAO;IACP,SAAS;IACT,QAAQ;IACR,IAAI;IACJ,QAAQ;CACT,CAAC,CAAC;AAEH,wCAAwC;AACxC,MAAM,yBAAyB,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;AAEhD,qCAAqC;AACrC,MAAM,oBAAoB,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAS5C;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,KAAkB,EAClB,MAAc,EACd,IAAyB;IAEzB,MAAM,cAAc,GAAG,IAAI,EAAE,cAAc,IAAI,yBAAyB,CAAC;IACzE,MAAM,UAAU,GAAG,IAAI,EAAE,UAAU,CAAC;IAEpC,gFAAgF;IAChF,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;QACrC,MAAM,IAAI,kBAAkB,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC7C,CAAC;IAED,0CAA0C;IAC1C,MAAM,EAAE,SAAS,EAAE,GAAG,eAAe,EAAE,GAAG,KAAK,CAAC;IAChD,MAAM,QAAQ,GAAG,SAAS,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC;IAEpD,+DAA+D;IAC/D,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAClD,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IAEjD,kFAAkF;IAClF,IACE,WAAW,CAAC,MAAM,KAAK,SAAS,CAAC,MAAM;QACvC,CAAC,eAAe,CAAC,WAAW,EAAE,SAAS,CAAC,EACxC,CAAC;QACD,MAAM,IAAI,qBAAqB,EAAE,CAAC;IACpC,CAAC;IAED,sBAAsB;IACtB,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAC9C,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC,CAAC;IAChD,IAAI,MAAM,GAAG,cAAc,EAAE,CAAC;QAC5B,MAAM,IAAI,cAAc,CAAC,MAAM,CAAC,CAAC;IACnC,CAAC;IAED,qCAAqC;IACrC,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,MAAM,KAAK,GAAG,MAAM,UAAU,CAAC,KAAK,CAClC,KAAK,CAAC,cAAc,EACpB,oBAAoB,CACrB,CAAC;QACF,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,mBAAmB,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;QACtD,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/boot/init-sdk.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 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 type { BasicTracerProvider } from "@opentelemetry/sdk-trace-base";
+/**
+ * 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;
+}
+/**
+ * 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 declare function initSDK(opts: InitSDKOptions): BasicTracerProvider;
+//# sourceMappingURL=init-sdk.d.ts.map

package/dist/boot/init-sdk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init-sdk.d.ts","sourceRoot":"","sources":["../../src/boot/init-sdk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAIzE;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,mCAAmC;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,yCAAyC;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,wDAAwD;IACxD,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAID;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,cAAc,GAAG,mBAAmB,CAgBjE"}