@vauban-org/agent-sdk 0.17.4 → 1.2.0

package/dist/ports/delegation.d.ts

@@ -0,0 +1,134 @@
+/**
+ * DelegationPort — delegation via → operator (Claim Algebra, S7 spec).
+ *
+ * Implements capability narrowing (R-1 invariant: child ⊆ parent),
+ * chain verification, revocation cascade, and depth limits.
+ * Ed25519 signatures, max_depth=5 V0 (configurable 1..10 Enterprise).
+ *
+ * Spec: docs/plans/PreCarre/canonical/specs/S7.md
+ */
+export interface Constraint {
+    readonly type: string;
+    readonly value: string | number | boolean;
+}
+export interface CapabilityScope {
+    readonly capabilities: ReadonlyArray<string>;
+    readonly constraints: ReadonlyArray<Constraint>;
+    readonly jurisdictions: ReadonlyArray<string>;
+    readonly expires_at: string;
+}
+export interface DelegationClaim {
+    readonly id: string;
+    readonly parent_id?: string;
+    readonly scope: CapabilityScope;
+    readonly ed25519_sig: string;
+    readonly ttl: number;
+    readonly issuer: string;
+    readonly holder: string;
+    readonly created_at: string;
+    readonly revoked_at?: string | null;
+}
+export interface RootCapability {
+    readonly capabilities: ReadonlyArray<string>;
+    readonly constraints: ReadonlyArray<Constraint>;
+    readonly jurisdictions: ReadonlyArray<string>;
+    readonly expires_at: string;
+}
+export interface VerifyChainResult {
+    readonly valid: boolean;
+    readonly chain_depth: number;
+    readonly errors: string[];
+    readonly chain: ReadonlyArray<DelegationClaim>;
+}
+export interface RevocationOpts {
+    readonly reason: string;
+    readonly cascade?: boolean;
+}
+export interface DelegationPort {
+    /**
+     * Mint a new delegation from a parent capability or root claim.
+     * Enforces R-1 narrowing: delegated scope must be ⊆ parent scope.
+     * Returns signed DelegationClaim or throws DelegationNotNarrowingError.
+     */
+    mintDelegation(parent: DelegationClaim | RootCapability, narrowed: CapabilityScope, opts?: {
+        ttl?: number;
+        issuerId?: string;
+        holderId?: string;
+    }): Promise<DelegationClaim>;
+    /**
+     * Verify a delegation claim chain from leaf to root.
+     * Checks: Ed25519 signatures, R-1 narrowing at each step,
+     * temporal frame nesting, revocation status, cycle detection, max_depth.
+     * Returns VerifyChainResult with full chain or error list.
+     */
+    verifyChain(claim: DelegationClaim): Promise<VerifyChainResult>;
+    /**
+     * Revoke a delegation claim.
+     * Propagates to all descendants (transitive revocation, ¬Revocation semantics).
+     * Returns count of claims revoked (including transitive descendants).
+     */
+    revoke(claimId: string, opts?: RevocationOpts): Promise<number>;
+    /**
+     * Get a claim by id (from persistent storage).
+     * Returns null if not found.
+     */
+    getClaim(claimId: string): Promise<DelegationClaim | null>;
+    /**
+     * Get all claims in a delegation chain from leaf to root.
+     * Follows parent_id pointers to build full chain.
+     */
+    getChain(claimId: string): Promise<DelegationClaim[]>;
+    /**
+     * Check if a claim is revoked (checks cache + on-chain, TTL 60s).
+     * Returns true if revoked, false if valid.
+     */
+    isRevoked(claimId: string): Promise<boolean>;
+    /**
+     * Get all descendant claims (transitive children).
+     * Used for revocation cascade validation.
+     */
+    getDescendants(claimId: string): Promise<DelegationClaim[]>;
+}
+export declare class DelegationNotNarrowingError extends Error {
+    readonly parentId: string;
+    readonly childId: string;
+    readonly violationType: string;
+    constructor(parentId: string, childId: string, violationType: string);
+}
+export declare class DelegationExpiredError extends Error {
+    readonly claimId: string;
+    readonly expiresAt: string;
+    constructor(claimId: string, expiresAt: string);
+}
+export declare class DelegationRevokedError extends Error {
+    readonly claimId: string;
+    readonly revokedAt: string;
+    readonly reason?: string | undefined;
+    constructor(claimId: string, revokedAt: string, reason?: string | undefined);
+}
+export declare class DelegationChainTooDeepError extends Error {
+    readonly claimId: string;
+    readonly depth: number;
+    readonly maxDepth: number;
+    constructor(claimId: string, depth: number, maxDepth: number);
+}
+export declare class DelegationSignatureInvalidError extends Error {
+    readonly claimId: string;
+    readonly reason: string;
+    constructor(claimId: string, reason: string);
+}
+export declare class DelegationCycleDetectedError extends Error {
+    readonly claimId: string;
+    readonly cycleSubject: string;
+    constructor(claimId: string, cycleSubject: string);
+}
+export declare class DelegationNotFoundError extends Error {
+    readonly claimId: string;
+    constructor(claimId: string);
+}
+export declare class DelegationTemporalFrameError extends Error {
+    readonly claimId: string;
+    readonly reason: string;
+    constructor(claimId: string, reason: string);
+}
+//# sourceMappingURL=delegation.d.ts.map

package/dist/ports/delegation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegation.d.ts","sourceRoot":"","sources":["../../src/ports/delegation.ts"],"names":[],"mappings":"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"}

package/dist/ports/delegation.js

@@ -0,0 +1,105 @@
+/**
+ * DelegationPort — delegation via → operator (Claim Algebra, S7 spec).
+ *
+ * Implements capability narrowing (R-1 invariant: child ⊆ parent),
+ * chain verification, revocation cascade, and depth limits.
+ * Ed25519 signatures, max_depth=5 V0 (configurable 1..10 Enterprise).
+ *
+ * Spec: docs/plans/PreCarre/canonical/specs/S7.md
+ */
+// ─── Typed errors ─────────────────────────────────────────────────────────────
+export class DelegationNotNarrowingError extends Error {
+    parentId;
+    childId;
+    violationType;
+    constructor(parentId, childId, violationType // "capability_expansion" | "constraint_removal" | "jurisdiction_expansion"
+    ) {
+        super(`Delegation R-1 narrowing violated (parent=${parentId}, child=${childId}): ${violationType}`);
+        this.parentId = parentId;
+        this.childId = childId;
+        this.violationType = violationType;
+        this.name = "DelegationNotNarrowingError";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+export class DelegationExpiredError extends Error {
+    claimId;
+    expiresAt;
+    constructor(claimId, expiresAt) {
+        super(`Delegation claim expired (${claimId}): expires_at=${expiresAt}`);
+        this.claimId = claimId;
+        this.expiresAt = expiresAt;
+        this.name = "DelegationExpiredError";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+export class DelegationRevokedError extends Error {
+    claimId;
+    revokedAt;
+    reason;
+    constructor(claimId, revokedAt, reason) {
+        super(`Delegation claim revoked (${claimId}) at ${revokedAt}${reason ? `: ${reason}` : ""}`);
+        this.claimId = claimId;
+        this.revokedAt = revokedAt;
+        this.reason = reason;
+        this.name = "DelegationRevokedError";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+export class DelegationChainTooDeepError extends Error {
+    claimId;
+    depth;
+    maxDepth;
+    constructor(claimId, depth, maxDepth) {
+        super(`Delegation chain exceeds max depth (${claimId}): depth=${depth}, max=${maxDepth}`);
+        this.claimId = claimId;
+        this.depth = depth;
+        this.maxDepth = maxDepth;
+        this.name = "DelegationChainTooDeepError";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+export class DelegationSignatureInvalidError extends Error {
+    claimId;
+    reason;
+    constructor(claimId, reason) {
+        super(`Delegation signature invalid (${claimId}): ${reason}`);
+        this.claimId = claimId;
+        this.reason = reason;
+        this.name = "DelegationSignatureInvalidError";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+export class DelegationCycleDetectedError extends Error {
+    claimId;
+    cycleSubject;
+    constructor(claimId, cycleSubject) {
+        super(`Delegation cycle detected (${claimId}): subject ${cycleSubject} appears in chain`);
+        this.claimId = claimId;
+        this.cycleSubject = cycleSubject;
+        this.name = "DelegationCycleDetectedError";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+export class DelegationNotFoundError extends Error {
+    claimId;
+    constructor(claimId) {
+        super(`Delegation claim not found: ${claimId}`);
+        this.claimId = claimId;
+        this.name = "DelegationNotFoundError";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+export class DelegationTemporalFrameError extends Error {
+    claimId;
+    reason;
+    constructor(claimId, reason // "not_yet_valid" | "temporal_nesting_violated"
+    ) {
+        super(`Delegation temporal frame error (${claimId}): ${reason}`);
+        this.claimId = claimId;
+        this.reason = reason;
+        this.name = "DelegationTemporalFrameError";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+//# sourceMappingURL=delegation.js.map

package/dist/ports/delegation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegation.js","sourceRoot":"","sources":["../../src/ports/delegation.ts"],"names":[],"mappings":"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"}

package/dist/ports/event-bus.d.ts

@@ -19,6 +19,10 @@
  * ADR-ECO-017: Cross-product events MUST carry a DomainEvent signature.
  * Use DomainEvent for inter-product events and CloudEvent for intra-product.
  *
+ * OTel instrumentation: import { createTracedEventBusPort } to wrap any
+ * EventBusPort implementation with OpenTelemetry spans per publish/subscribe call.
+ * Gracefully degrades to noop spans when no OTel SDK is installed.
+ *
  * @public
  */
 export interface CloudEvent {
@@ -112,19 +116,6 @@ export interface EventBusPort {
      * @param key   - Idempotency key (dedups within window; UUIDv7 recommended).
      */
     publishWithIdempotency<T>(event: Omit<DomainEvent<T>, "signature">, key: string): Promise<void>;
-    /**
-     * Subscribe to a stream with a consumer group.
-     *
-     * Returns an unsubscribe function. The handler receives each event after
-     * dedup (based on `event.id`). Implementation MUST:
-     *   1. Create consumer group if it doesn't exist (XGROUP CREATE).
-     *   2. XREADGROUP → handler → XACK.
-     *   3. On 3 consecutive XAUTOCLAIM failures → XADD to DLQ stream.
-     *   4. Extract `traceparent` and set as parent span context.
-     *
-     * @deprecated Prefer the overload returning Subscription for CloudEvent streams.
-     */
-    subscribe(stream: string, consumerGroup: string, handler: (event: CloudEvent) => Promise<void>): Promise<() => void>;
     /**
      * Subscribe to DomainEvents of a specific type.
      *
@@ -164,4 +155,29 @@ export interface EventBusPort {
      */
     pendingCount(stream: string, consumerGroup: string): Promise<number>;
 }
+/**
+ * Thrown when an event could not be published to Redis (connection lost,
+ * stream key conflict, or OOM on XADD). The original event is available
+ * for retry or DLQ routing.
+ */
+export declare class EventPublishError extends Error {
+    readonly cause?: unknown | undefined;
+    /** The stream key the event was targeting. */
+    readonly stream: string;
+    /** The event id (UUIDv7) that failed to publish. */
+    readonly eventId: string;
+    constructor(message: string, stream: string, eventId: string, cause?: unknown | undefined);
+}
+/**
+ * Wrap any EventBusPort implementation with OTel spans.
+ * Publishes and subscribeDomain calls each get a span with the event type
+ * and stream as attributes. Gracefully degrades to noop spans when no OTel
+ * SDK is installed.
+ *
+ * Usage:
+ *   const raw: EventBusPort = buildRedisEventBus(...);
+ *   const traced = createTracedEventBusPort(raw);
+ *   await traced.publish(event, "vault.events") // emits "event-bus.publish" span
+ */
+export declare function createTracedEventBusPort(impl: EventBusPort): EventBusPort;
 //# sourceMappingURL=event-bus.d.ts.map

package/dist/ports/event-bus.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"event-bus.d.ts","sourceRoot":"","sources":["../../src/ports/event-bus.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"event-bus.d.ts","sourceRoot":"","sources":["../../src/ports/event-bus.ts"],"names":[],"mappings":"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"}

package/dist/ports/event-bus.js

@@ -19,7 +19,112 @@
  * ADR-ECO-017: Cross-product events MUST carry a DomainEvent signature.
  * Use DomainEvent for inter-product events and CloudEvent for intra-product.
  *
+ * OTel instrumentation: import { createTracedEventBusPort } to wrap any
+ * EventBusPort implementation with OpenTelemetry spans per publish/subscribe call.
+ * Gracefully degrades to noop spans when no OTel SDK is installed.
+ *
  * @public
  */
-export {};
+// ─── Typed errors ─────────────────────────────────────────────────────────────
+/**
+ * Thrown when an event could not be published to Redis (connection lost,
+ * stream key conflict, or OOM on XADD). The original event is available
+ * for retry or DLQ routing.
+ */
+export class EventPublishError extends Error {
+    cause;
+    /** The stream key the event was targeting. */
+    stream;
+    /** The event id (UUIDv7) that failed to publish. */
+    eventId;
+    constructor(message, stream, eventId, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = "EventPublishError";
+        this.stream = stream;
+        this.eventId = eventId;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+import { SpanStatusCode, trace } from "@opentelemetry/api";
+const PORT_TRACER = trace.getTracer("vauban-agent-sdk.ports", "0.1.0");
+/**
+ * Wrap any EventBusPort implementation with OTel spans.
+ * Publishes and subscribeDomain calls each get a span with the event type
+ * and stream as attributes. Gracefully degrades to noop spans when no OTel
+ * SDK is installed.
+ *
+ * Usage:
+ *   const raw: EventBusPort = buildRedisEventBus(...);
+ *   const traced = createTracedEventBusPort(raw);
+ *   await traced.publish(event, "vault.events") // emits "event-bus.publish" span
+ */
+export function createTracedEventBusPort(impl) {
+    function spanName(op) {
+        return `event-bus.${op}`;
+    }
+    return {
+        async publish(event, stream) {
+            return PORT_TRACER.startActiveSpan(spanName("publish"), {
+                attributes: {
+                    "event.type": event.type,
+                    "event.stream": stream,
+                    "event.id": event.id,
+                    "vauban.port.name": "event-bus",
+                },
+            }, async (span) => {
+                try {
+                    await impl.publish(event, stream);
+                    span.setStatus({ code: SpanStatusCode.OK });
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    span.setStatus({ code: SpanStatusCode.ERROR, message });
+                    if (err instanceof Error)
+                        span.recordException(err);
+                    throw err;
+                }
+                finally {
+                    span.end();
+                }
+            });
+        },
+        async publishWithIdempotency(event, key) {
+            return PORT_TRACER.startActiveSpan(spanName("publishWithIdempotency"), {
+                attributes: {
+                    "event.type": event.type,
+                    "event.idempotency_key": key,
+                    "vauban.port.name": "event-bus",
+                },
+            }, async (span) => {
+                try {
+                    await impl.publishWithIdempotency(event, key);
+                    span.setStatus({ code: SpanStatusCode.OK });
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    span.setStatus({ code: SpanStatusCode.ERROR, message });
+                    if (err instanceof Error)
+                        span.recordException(err);
+                    throw err;
+                }
+                finally {
+                    span.end();
+                }
+            });
+        },
+        subscribeDomain(eventType, handler, opts) {
+            return impl.subscribeDomain(eventType, handler, opts);
+        },
+        replayFrom(streamKey, fromId) {
+            return impl.replayFrom(streamKey, fromId);
+        },
+        dlq() {
+            return impl.dlq();
+        },
+        pendingCount(stream, consumerGroup) {
+            return impl.pendingCount(stream, consumerGroup);
+        },
+    };
+}
 //# sourceMappingURL=event-bus.js.map

package/dist/ports/event-bus.js.map

@@ -1 +1 @@
-{"version":3,"file":"event-bus.js","sourceRoot":"","sources":["../../src/ports/event-bus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG"}
+{"version":3,"file":"event-bus.js","sourceRoot":"","sources":["../../src/ports/event-bus.ts"],"names":[],"mappings":"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"}

package/dist/ports/federation.contract.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * FederationPort contract tests (S4 spec).
+ *
+ * Applied to any FederationPort implementation.
+ * Verifies: send→receive roundtrip, signature verification, delegation chain preservation,
+ * consistent hash routing determinism, replay protection via nonce.
+ */
+export declare const federationPortContract: (factory: () => any) => void;
+//# sourceMappingURL=federation.contract.test.d.ts.map

package/dist/ports/federation.contract.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"federation.contract.test.d.ts","sourceRoot":"","sources":["../../src/ports/federation.contract.test.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA2FH,eAAO,MAAM,sBAAsB,GAAI,SAAS,MAAM,GAAG,SA0NxD,CAAC"}