anantham-v2 2.0.0-alpha.1

package/dist/integrations/webhook-dispatcher.js

@@ -0,0 +1,155 @@
+import { createHmac, randomUUID } from "node:crypto";
+import { EventTypes } from "../domain/event.js";
+/**
+ * Outbound Webhook Dispatcher & Reliable Delivery Engine.
+ * PRD Part 2 Section 230–235.
+ */
+export class WebhookDispatcher {
+    eventStore;
+    subscriptionRepo;
+    deliveryRepo;
+    httpSender;
+    unsubscribe;
+    constructor(options) {
+        this.eventStore = options.eventStore;
+        this.subscriptionRepo = options.subscriptionRepo;
+        this.deliveryRepo = options.deliveryRepo;
+        this.httpSender =
+            options.httpSender ??
+                (async (url, body, headers) => {
+                    try {
+                        const res = await fetch(url, { method: "POST", body, headers });
+                        return { status: res.status, ok: res.ok };
+                    }
+                    catch (err) {
+                        return { status: 500, ok: false, error: err.message };
+                    }
+                });
+    }
+    start() {
+        if (this.unsubscribe)
+            return;
+        this.unsubscribe = this.eventStore.subscribe({}, (event) => {
+            this.handleEvent(event).catch(() => {
+                // Non-blocking on subscriber dispatch
+            });
+        });
+    }
+    stop() {
+        if (this.unsubscribe) {
+            this.unsubscribe();
+            this.unsubscribe = undefined;
+        }
+    }
+    /**
+     * Process an authoritative event and dispatch to matching subscriptions.
+     */
+    async handleEvent(event) {
+        if (!event.projectId)
+            return [];
+        if (event.type === EventTypes.INTEGRATION_WEBHOOK_DELIVERED ||
+            event.type === EventTypes.INTEGRATION_WEBHOOK_FAILED) {
+            return []; // Prevent recursive delivery cascades
+        }
+        const subscriptions = this.subscriptionRepo.listActiveByProject(event.projectId);
+        const deliveries = [];
+        for (const sub of subscriptions) {
+            if (this.matchesEvent(sub, event.type)) {
+                const delivery = await this.dispatchToSubscription(sub, event);
+                deliveries.push(delivery);
+            }
+        }
+        return deliveries;
+    }
+    matchesEvent(sub, eventType) {
+        return sub.events.includes("*") || sub.events.includes(eventType);
+    }
+    async dispatchToSubscription(sub, event) {
+        const deliveryId = `deliv_${randomUUID().slice(0, 8)}`;
+        const now = new Date().toISOString();
+        // 1. Durably record pending delivery attempt
+        const record = {
+            id: deliveryId,
+            subscriptionId: sub.id,
+            projectId: sub.projectId,
+            eventId: event.id,
+            attempt: 1,
+            status: "PENDING",
+            timestamp: now,
+            metadata: {},
+        };
+        this.deliveryRepo.save(record);
+        // 2. Prepare payload & cryptographic signature
+        const payloadStr = JSON.stringify({
+            deliveryId,
+            subscriptionId: sub.id,
+            event,
+            timestamp: now,
+        });
+        const headers = {
+            "Content-Type": "application/json",
+            "X-Anantham-Delivery-Id": deliveryId,
+            "X-Anantham-Event": event.type,
+        };
+        if (sub.secretRef) {
+            const hmac = createHmac("sha256", sub.secretRef);
+            hmac.update(payloadStr);
+            headers["X-Anantham-Signature"] = `sha256=${hmac.digest("hex")}`;
+        }
+        // 3. Execute HTTP Dispatch with retry
+        const maxAttempts = sub.retryPolicy?.maxAttempts ?? 3;
+        let attempt = 0;
+        let success = false;
+        let lastError;
+        let lastStatusCode = 0;
+        while (attempt < maxAttempts && !success) {
+            attempt++;
+            const res = await this.httpSender(sub.targetUrl, payloadStr, headers);
+            lastStatusCode = res.status;
+            if (res.ok) {
+                success = true;
+                break;
+            }
+            else {
+                lastError = res.error ?? `HTTP ${res.status}`;
+                // Permanent failure check: 4xx except 429
+                if (res.status >= 400 && res.status < 500 && res.status !== 429) {
+                    break; // Do not retry permanent client error
+                }
+            }
+        }
+        // 4. Update durable delivery record
+        record.attempt = attempt;
+        record.status = success ? "DELIVERED" : "FAILED";
+        record.statusCode = lastStatusCode;
+        record.error = success ? undefined : lastError;
+        this.deliveryRepo.save(record);
+        // 5. Emit delivery outcome event to EventStore
+        try {
+            this.eventStore.append({
+                id: `evt_${deliveryId}_result`,
+                schemaVersion: 1,
+                projectId: sub.projectId,
+                type: success
+                    ? EventTypes.INTEGRATION_WEBHOOK_DELIVERED
+                    : EventTypes.INTEGRATION_WEBHOOK_FAILED,
+                actor: "system",
+                timestamp: new Date().toISOString(),
+                payload: {
+                    deliveryId,
+                    subscriptionId: sub.id,
+                    targetUrl: sub.targetUrl,
+                    statusCode: lastStatusCode,
+                    attempt,
+                    success,
+                    error: lastError,
+                },
+            });
+        }
+        catch {
+            // Non-blocking
+        }
+        return record;
+    }
+}
+//# sourceMappingURL=webhook-dispatcher.js.map

package/dist/integrations/webhook-dispatcher.js.map

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

package/dist/integrations/webhook-ingestion-engine.d.ts

@@ -0,0 +1,31 @@
+import { type EventStore } from "../event-state/event-store.js";
+import { type IntegrationRepository } from "../persistence/repositories/integration-repository.js";
+export interface WebhookIngestionOptions {
+    eventStore: EventStore;
+    integrationRepo: IntegrationRepository;
+}
+export interface IngestionResult {
+    accepted: boolean;
+    deliveryId: string;
+    eventId?: string;
+    errorMessage?: string;
+}
+/**
+ * Inbound Webhook Ingestion Engine with HMAC Verification & Replay Protection.
+ * PRD Part 2 Section 225–226.
+ */
+export declare class WebhookIngestionEngine {
+    private readonly eventStore;
+    private readonly integrationRepo;
+    private readonly processedDeliveryIds;
+    constructor(options: WebhookIngestionOptions);
+    /**
+     * Cryptographically verify HMAC-SHA256 signature using timing-safe comparison.
+     */
+    static verifySignature(rawBody: string, signature: string, secret: string): boolean;
+    /**
+     * Ingest and validate incoming webhook payload.
+     */
+    ingest(integrationId: string, rawBody: string, headers: Record<string, string | string[] | undefined>): IngestionResult;
+}
+//# sourceMappingURL=webhook-ingestion-engine.d.ts.map

package/dist/integrations/webhook-ingestion-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-ingestion-engine.d.ts","sourceRoot":"","sources":["../../src/integrations/webhook-ingestion-engine.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAChE,OAAO,EAAE,KAAK,qBAAqB,EAAE,MAAM,uDAAuD,CAAC;AAOnG,MAAM,WAAW,uBAAuB;IACtC,UAAU,EAAE,UAAU,CAAC;IACvB,eAAe,EAAE,qBAAqB,CAAC;CACxC;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,qBAAa,sBAAsB;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;IACxC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAwB;IACxD,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAqB;gBAE9C,OAAO,EAAE,uBAAuB;IAK5C;;OAEG;WACW,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO;IAoB1F;;OAEG;IACI,MAAM,CACX,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,GACrD,eAAe;CA8GnB"}

package/dist/integrations/webhook-ingestion-engine.js

@@ -0,0 +1,136 @@
+import { createHmac, timingSafeEqual, randomUUID } from "node:crypto";
+import { InboundWebhookPayloadSchema, } from "../domain/integration.js";
+import { EventTypes } from "../domain/event.js";
+/**
+ * Inbound Webhook Ingestion Engine with HMAC Verification & Replay Protection.
+ * PRD Part 2 Section 225–226.
+ */
+export class WebhookIngestionEngine {
+    eventStore;
+    integrationRepo;
+    processedDeliveryIds = new Set();
+    constructor(options) {
+        this.eventStore = options.eventStore;
+        this.integrationRepo = options.integrationRepo;
+    }
+    /**
+     * Cryptographically verify HMAC-SHA256 signature using timing-safe comparison.
+     */
+    static verifySignature(rawBody, signature, secret) {
+        if (!signature || !secret)
+            return false;
+        const hmac = createHmac("sha256", secret);
+        hmac.update(rawBody);
+        const expected = hmac.digest("hex");
+        const cleanSig = signature.startsWith("sha256=") ? signature.slice(7) : signature;
+        if (cleanSig.length !== expected.length) {
+            return false;
+        }
+        try {
+            return timingSafeEqual(Buffer.from(cleanSig, "hex"), Buffer.from(expected, "hex"));
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Ingest and validate incoming webhook payload.
+     */
+    ingest(integrationId, rawBody, headers) {
+        // 1. Resolve Integration
+        const integration = this.integrationRepo.findById(integrationId);
+        if (!integration) {
+            return { accepted: false, deliveryId: "unknown", errorMessage: `Integration '${integrationId}' not found.` };
+        }
+        if (integration.status !== "ACTIVE") {
+            return {
+                accepted: false,
+                deliveryId: "unknown",
+                errorMessage: `Integration '${integrationId}' is not active (status: ${integration.status}).`,
+            };
+        }
+        // 2. Verify Signature if Secret Reference Configured
+        if (integration.secretRef) {
+            const sigHeader = (headers["x-hub-signature-256"] ||
+                headers["x-signature-256"] ||
+                headers["x-anantham-signature"]);
+            if (!sigHeader) {
+                return { accepted: false, deliveryId: "unknown", errorMessage: "Missing required webhook signature header." };
+            }
+            const isValid = WebhookIngestionEngine.verifySignature(rawBody, sigHeader, integration.secretRef);
+            if (!isValid) {
+                return { accepted: false, deliveryId: "unknown", errorMessage: "Invalid cryptographic webhook signature." };
+            }
+        }
+        // 3. Parse & Validate Payload Envelope
+        let jsonBody;
+        try {
+            jsonBody = JSON.parse(rawBody);
+        }
+        catch {
+            return { accepted: false, deliveryId: "unknown", errorMessage: "Malformed JSON webhook payload." };
+        }
+        const parsed = InboundWebhookPayloadSchema.safeParse(jsonBody);
+        if (!parsed.success) {
+            return {
+                accepted: false,
+                deliveryId: "unknown",
+                errorMessage: `Schema validation failed: ${parsed.error.message}`,
+            };
+        }
+        const payload = parsed.data;
+        // 4. Replay & Duplicate Protection (In-Memory + Persistent EventStore Check)
+        const replayKey = `${integrationId}:${payload.deliveryId}`;
+        if (this.processedDeliveryIds.has(replayKey)) {
+            return {
+                accepted: false,
+                deliveryId: payload.deliveryId,
+                errorMessage: `Duplicate webhook rejected: deliveryId '${payload.deliveryId}' already processed.`,
+            };
+        }
+        // Check persistent EventStore to defend against post-restart replay attacks
+        const existingEvents = this.eventStore.getEventsByProject(integration.projectId, {
+            type: EventTypes.INTEGRATION_WEBHOOK_RECEIVED,
+        });
+        const isPersistentDuplicate = existingEvents.some((e) => e.payload?.integrationId === integrationId && e.payload?.deliveryId === payload.deliveryId);
+        if (isPersistentDuplicate) {
+            this.processedDeliveryIds.add(replayKey);
+            return {
+                accepted: false,
+                deliveryId: payload.deliveryId,
+                errorMessage: `Duplicate webhook rejected: deliveryId '${payload.deliveryId}' already processed.`,
+            };
+        }
+        // Bound memory cache to prevent unbounded growth
+        if (this.processedDeliveryIds.size >= 10000) {
+            const firstKey = this.processedDeliveryIds.values().next().value;
+            if (firstKey)
+                this.processedDeliveryIds.delete(firstKey);
+        }
+        this.processedDeliveryIds.add(replayKey);
+        // 5. Commit Untrusted Webhook Event to Authoritative EventStore
+        const eventId = `evt_webhook_${randomUUID().slice(0, 8)}`;
+        const event = {
+            id: eventId,
+            schemaVersion: 1,
+            projectId: integration.projectId,
+            type: EventTypes.INTEGRATION_WEBHOOK_RECEIVED,
+            actor: "system",
+            timestamp: new Date().toISOString(),
+            payload: {
+                integrationId: integration.id,
+                deliveryId: payload.deliveryId,
+                eventType: payload.eventType,
+                originalTimestamp: payload.timestamp,
+                data: payload.payload,
+            },
+        };
+        this.eventStore.append(event);
+        return {
+            accepted: true,
+            deliveryId: payload.deliveryId,
+            eventId,
+        };
+    }
+}
+//# sourceMappingURL=webhook-ingestion-engine.js.map

package/dist/integrations/webhook-ingestion-engine.js.map

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

package/dist/jobs/background-job-manager.d.ts

@@ -0,0 +1,97 @@
+import { type BackgroundJob, type JobCreationRequest, type JobStatus, type JobFailureClassification } from "../domain/job.js";
+import { type TaskLease } from "../domain/lease.js";
+import { EventStore } from "../event-state/event-store.js";
+import { JobRepository } from "../persistence/repositories/job-repository.js";
+import { TaskRepository } from "../persistence/repositories/task-repository.js";
+import { ProjectRepository } from "../persistence/repositories/project-repository.js";
+import { SessionRepository } from "../persistence/repositories/session-repository.js";
+import { TaskClaimManager } from "../tasks/task-claim-manager.js";
+import { WorkflowRetryHandler } from "../workflow/workflow-retry-handler.js";
+export interface BackgroundJobManagerOptions {
+    jobRepo: JobRepository;
+    taskRepo: TaskRepository;
+    projectRepo: ProjectRepository;
+    sessionRepo: SessionRepository;
+    claimManager: TaskClaimManager;
+    eventStore?: EventStore;
+    retryHandler?: WorkflowRetryHandler;
+}
+/**
+ * Authoritative Background Job Lifecycle Manager.
+ * Orchestrates job creation, claims, generation-fenced heartbeats, checkpoints,
+ * cancellation, timeouts, and completion.
+ * PRD Part 2 Section 120–135.
+ */
+export declare class BackgroundJobManager {
+    private readonly jobRepo;
+    private readonly taskRepo;
+    private readonly projectRepo;
+    private readonly sessionRepo;
+    private readonly claimManager;
+    private readonly eventStore?;
+    private readonly retryHandler;
+    constructor(options: BackgroundJobManagerOptions);
+    /**
+     * Create and persist a new background job with an underlying durable task.
+     */
+    createJob(request: JobCreationRequest): BackgroundJob;
+    /**
+     * Worker claims a background job, acquiring an exclusive lease with a monotonic generation token.
+     */
+    claimJob(jobId: string, worker: {
+        agentId: string;
+        instanceId: string;
+        ttlMs?: number;
+        maxRenewals?: number;
+    }): {
+        job: BackgroundJob;
+        lease: TaskLease;
+    };
+    /**
+     * Worker sends a periodic heartbeat. Fencing tokens and deadlines are strictly validated.
+     */
+    heartbeatJob(jobId: string, leaseId: string, generation: number, worker: {
+        agentId: string;
+        instanceId: string;
+    }): {
+        success: boolean;
+        lease?: TaskLease;
+        cancelled?: boolean;
+        timedOut?: boolean;
+        reason?: string;
+    };
+    /**
+     * Associates a progress checkpoint with the background job.
+     */
+    checkpointJob(jobId: string, leaseId: string, generation: number, checkpointId: string): void;
+    /**
+     * Completes a background job. Fencing token is strictly validated.
+     */
+    completeJob(jobId: string, leaseId: string, generation: number, result?: {
+        artifacts?: string[];
+        data?: unknown;
+        tokensUsed?: number;
+        costUsd?: number;
+        durationMs?: number;
+        toolCalls?: number;
+    }): BackgroundJob;
+    /**
+     * Fails a background job attempt. Retries if transient; fails closed immediately on policy denials.
+     */
+    failJob(jobId: string, leaseId: string, generation: number, error: unknown): {
+        status: JobStatus;
+        retrying: boolean;
+        backoffMs?: number;
+        classification: JobFailureClassification;
+    };
+    /**
+     * Cancel an active or queued background job.
+     */
+    cancelJob(jobId: string, reason?: string, requestedBy?: string): BackgroundJob;
+    /**
+     * Retrieve current live status of a background job.
+     */
+    getJob(jobId: string): BackgroundJob | null;
+    private createAndAppendEventInTx;
+}
+//# sourceMappingURL=background-job-manager.d.ts.map

package/dist/jobs/background-job-manager.d.ts.map

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