@a5c-ai/krate 5.0.1-staging.00fa5317c

package/src/external/sync-controller.js

@@ -0,0 +1,235 @@
+// External Sync Controller — Slice 3.4
+//
+// Manages bidirectional sync between external providers and the Krate resource store.
+//
+// Responsibilities:
+//   - Event normalization (raw provider event → canonical internal format)
+//   - Resource upsert with external identity envelope (nativeId, url, etag)
+//   - High-watermark tracking per binding
+//   - Ownership mode arbitration (bidirectional / external-owned / krate-owned)
+//   - Tombstone creation for deleted external resources
+
+export const SYNC_CONTROLLER_BOUNDARY = {
+  role: 'sync-controller',
+  scope: 'Bidirectional sync — event normalization, resource upsert, watermark, ownership, tombstones',
+  owns: ['event normalization', 'resource upsert', 'watermark tracking', 'ownership modes', 'tombstones'],
+  delegatesTo: ['resource-model'],
+  mustNotOwn: ['HMAC verification', 'webhook delivery tracking']
+};
+
+/**
+ * Create a sync controller that manages bidirectional sync between external
+ * providers and the Krate resource store.
+ *
+ * @param {{ persistFn?: (resource: object) => Promise<any> }} [opts]
+ *   Optional persistFn is called (fire-and-forget) after watermark/resource changes.
+ *   It receives a K8s-style CRD resource representing the changed state.
+ * @returns {object}
+ */
+export function createSyncController({ persistFn } = {}) {
+  /** @type {Map<string, string>} bindingRef → ISO timestamp watermark */
+  const watermarks = new Map();
+
+  /** @type {Map<string, object>} `${namespace}/${kind}/${localName}` → resource */
+  const resources = new Map();
+
+  /** @type {Map<string, object>} nativeId → tombstone record */
+  const tombstones = new Map();
+
+  /**
+   * Fire-and-forget persistence: call persistFn without blocking the caller.
+   * @param {object} resource
+   */
+  function persist(resource) {
+    if (typeof persistFn === 'function') {
+      // Intentionally not awaited — persistence is async and non-blocking
+      Promise.resolve(persistFn(resource)).catch(() => {
+        // Swallow errors in fire-and-forget path; caller may wire monitoring separately
+      });
+    }
+  }
+
+  return {
+    /**
+     * Normalize a raw provider event into a canonical internal format.
+     *
+     * @param {{ eventType: string, action?: string, nativeId: string, providerRef: string,
+     *           resourceKind: string, data?: object, receivedAt?: string }} rawEvent
+     * @returns {{ eventType: string, action: string, nativeId: string, providerRef: string,
+     *             resourceKind: string, data: object, receivedAt: string, canonicalAt: string }}
+     */
+    normalizeEvent(rawEvent) {
+      return {
+        eventType: rawEvent.eventType,
+        action: rawEvent.action || 'unknown',
+        nativeId: rawEvent.nativeId,
+        providerRef: rawEvent.providerRef,
+        resourceKind: rawEvent.resourceKind,
+        data: rawEvent.data || {},
+        receivedAt: rawEvent.receivedAt || new Date().toISOString(),
+        canonicalAt: new Date().toISOString()
+      };
+    },
+
+    /**
+     * Upsert a resource in the local store with an external identity envelope.
+     *
+     * If the resource already exists (matched by localName + namespace + kind), it will
+     * be updated while preserving the nativeId and firstSyncedAt from the first sync.
+     *
+     * @param {{ kind: string, localName: string, namespace?: string, spec: object,
+     *           externalEnvelope: { nativeId: string, url: string, etag: string, providerRef: string } }} params
+     * @returns {object} The created/updated resource
+     */
+    upsertResource({ kind, localName, namespace = 'default', spec, externalEnvelope }) {
+      const key = `${namespace}/${kind}/${localName}`;
+      const existing = resources.get(key);
+      const now = new Date().toISOString();
+
+      const resource = {
+        apiVersion: 'krate.a5c.ai/v1alpha1',
+        kind,
+        metadata: {
+          name: localName,
+          namespace,
+          labels: {},
+          annotations: {}
+        },
+        spec: { ...spec },
+        status: {
+          phase: 'Synced',
+          external: {
+            nativeId: externalEnvelope.nativeId,
+            url: externalEnvelope.url,
+            etag: externalEnvelope.etag,
+            providerRef: externalEnvelope.providerRef,
+            lastSyncedAt: now,
+            firstSyncedAt: existing
+              ? existing.status.external.firstSyncedAt
+              : now
+          }
+        }
+      };
+
+      resources.set(key, resource);
+      persist(resource);
+      return resource;
+    },
+
+    /**
+     * Advance the high-watermark timestamp for a given binding.
+     * If the new timestamp is not later than the existing one, it is ignored.
+     *
+     * @param {string} bindingRef
+     * @param {string} timestamp  ISO 8601 timestamp
+     */
+    updateWatermark(bindingRef, timestamp) {
+      const current = watermarks.get(bindingRef);
+      if (!current || timestamp > current) {
+        watermarks.set(bindingRef, timestamp);
+        // Persist watermark as a CRD-shaped resource
+        persist({
+          apiVersion: 'krate.a5c.ai/v1alpha1',
+          kind: 'ExternalSyncWatermark',
+          metadata: {
+            name: `watermark-${bindingRef.replace(/[^a-zA-Z0-9]/g, '-')}`,
+            namespace: 'default',
+            labels: {},
+            annotations: {}
+          },
+          spec: {
+            bindingRef,
+            watermark: timestamp
+          },
+          status: {
+            lastUpdatedAt: new Date().toISOString()
+          }
+        });
+      }
+    },
+
+    /**
+     * Retrieve the current high-watermark for a given binding.
+     *
+     * @param {string} bindingRef
+     * @returns {string|null}
+     */
+    getWatermark(bindingRef) {
+      return watermarks.has(bindingRef) ? watermarks.get(bindingRef) : null;
+    },
+
+    /**
+     * Apply an ownership mode policy to determine whether an operation is allowed.
+     *
+     * Modes:
+     *   - 'bidirectional'  — both krate and external provider may write
+     *   - 'external-owned' — only the external provider may write; krate is read-only
+     *   - 'krate-owned'    — only krate may write; external provider is read-only
+     *
+     * @param {{ ownershipMode: string, operation: string, origin: string }} params
+     * @returns {{ allowed: boolean, reason: string|null }}
+     */
+    applyOwnershipMode({ ownershipMode, operation, origin }) {
+      if (ownershipMode === 'bidirectional') {
+        return { allowed: true, reason: null };
+      }
+
+      if (ownershipMode === 'external-owned') {
+        if (origin === 'krate' && operation === 'write') {
+          return {
+            allowed: false,
+            reason: 'external-owned mode — krate writes are blocked; this resource is read-only from krate perspective'
+          };
+        }
+        return { allowed: true, reason: null };
+      }
+
+      if (ownershipMode === 'krate-owned') {
+        if (origin === 'external' && operation === 'write') {
+          return {
+            allowed: false,
+            reason: 'krate-owned mode — external provider writes are blocked; krate is the authoritative source'
+          };
+        }
+        return { allowed: true, reason: null };
+      }
+
+      // Unknown mode — deny by default
+      return {
+        allowed: false,
+        reason: `unknown ownership mode: ${ownershipMode}`
+      };
+    },
+
+    /**
+     * Create a tombstone record marking that an external resource has been deleted.
+     *
+     * @param {{ nativeId: string, providerRef: string, resourceKind: string,
+     *           localRef: string, deletedAt?: string }} params
+     * @returns {{ nativeId: string, providerRef: string, resourceKind: string,
+     *             localRef: string, tombstoned: true, deletedAt: string }}
+     */
+    createTombstone({ nativeId, providerRef, resourceKind, localRef, deletedAt }) {
+      const record = {
+        nativeId,
+        providerRef,
+        resourceKind,
+        localRef,
+        tombstoned: true,
+        deletedAt: deletedAt || new Date().toISOString()
+      };
+      tombstones.set(nativeId, record);
+      return record;
+    },
+
+    /**
+     * Retrieve a tombstone record by nativeId, or null if not found.
+     *
+     * @param {string} nativeId
+     * @returns {object|null}
+     */
+    getTombstone(nativeId) {
+      return tombstones.has(nativeId) ? tombstones.get(nativeId) : null;
+    }
+  };
+}

package/src/external/webhook-controller.js

@@ -0,0 +1,144 @@
+// External Webhook Controller — Slice 3.4
+//
+// Handles inbound webhook delivery:
+//   - HMAC-SHA256 signature verification
+//   - Delivery record creation and persistence (in-memory store)
+//   - Deduplication by deliveryId
+//   - Async event queue with subscriber support
+
+import { createHmac, timingSafeEqual } from 'node:crypto';
+
+export const WEBHOOK_CONTROLLER_BOUNDARY = {
+  role: 'webhook-controller',
+  scope: 'Inbound webhook delivery — HMAC verification, dedup, async event queue',
+  owns: ['HMAC validation', 'delivery records', 'dedup index', 'event queue'],
+  delegatesTo: ['sync-controller'],
+  mustNotOwn: ['resource persistence', 'ownership arbitration']
+};
+
+/**
+ * Create a webhook controller that handles inbound webhook delivery.
+ *
+ * @param {{ secret: string }} options
+ * @returns {object}
+ */
+export function createWebhookController(options = {}) {
+  const { secret } = options;
+
+  /** @type {Map<string, object>} deliveryId → delivery record */
+  const deliveries = new Map();
+
+  /** @type {Function[]} event subscribers */
+  const subscribers = [];
+
+  return {
+    /**
+     * Verify an HMAC-SHA256 signature against a request body.
+     *
+     * @param {string} body  Raw request body string
+     * @param {string|null} signature  Signature header value (e.g. "sha256=abc…")
+     * @returns {{ valid: boolean, reason: string|null }}
+     */
+    verifyHmacSignature(body, signature) {
+      if (!signature) {
+        return { valid: false, reason: 'missing signature header' };
+      }
+
+      if (!signature.startsWith('sha256=')) {
+        return { valid: false, reason: 'invalid signature format — must start with sha256=' };
+      }
+
+      const expected = 'sha256=' + createHmac('sha256', secret).update(body).digest('hex');
+
+      try {
+        const expectedBuf = Buffer.from(expected, 'utf8');
+        const actualBuf = Buffer.from(signature, 'utf8');
+        if (expectedBuf.length !== actualBuf.length) {
+          return { valid: false, reason: 'signature mismatch' };
+        }
+        const match = timingSafeEqual(expectedBuf, actualBuf);
+        if (!match) {
+          return { valid: false, reason: 'signature mismatch — HMAC does not match' };
+        }
+        return { valid: true, reason: null };
+      } catch {
+        return { valid: false, reason: 'signature verification error — invalid signature bytes' };
+      }
+    },
+
+    /**
+     * Create a delivery record for a received webhook payload.
+     *
+     * @param {{ deliveryId: string, eventType: string, payload: object, rawBody: string }} params
+     * @returns {{ deliveryId: string, eventType: string, timestamp: string, payload: object, rawBody: string, status: string }}
+     */
+    createDeliveryRecord({ deliveryId, eventType, payload, rawBody }) {
+      return {
+        deliveryId,
+        eventType,
+        timestamp: new Date().toISOString(),
+        payload,
+        rawBody,
+        status: 'received'
+      };
+    },
+
+    /**
+     * Persist a delivery record into the in-memory dedup store.
+     *
+     * @param {{ deliveryId: string }} record
+     */
+    recordDelivery(record) {
+      deliveries.set(record.deliveryId, record);
+    },
+
+    /**
+     * Check whether a deliveryId has already been processed.
+     *
+     * @param {string} deliveryId
+     * @returns {boolean}
+     */
+    isDuplicate(deliveryId) {
+      return deliveries.has(deliveryId);
+    },
+
+    /**
+     * Register a subscriber that will be called for each queued normalized event.
+     *
+     * @param {Function} handler  fn(event) → void
+     */
+    onEvent(handler) {
+      subscribers.push(handler);
+    },
+
+    /**
+     * Process a delivery: create a record, check dedup, emit to queue.
+     *
+     * @param {{ deliveryId: string, eventType: string, payload: object, rawBody: string }} params
+     * @returns {{ queued: number, duplicate: boolean, deliveryId: string }}
+     */
+    processDelivery({ deliveryId, eventType, payload, rawBody }) {
+      if (this.isDuplicate(deliveryId)) {
+        return { queued: 0, duplicate: true, deliveryId };
+      }
+
+      const record = this.createDeliveryRecord({ deliveryId, eventType, payload, rawBody });
+      this.recordDelivery(record);
+
+      const normalizedEvent = {
+        deliveryId,
+        eventType,
+        payload,
+        receivedAt: record.timestamp
+      };
+
+      let queued = 0;
+      for (const subscriber of subscribers) {
+        subscriber(normalizedEvent);
+        queued++;
+      }
+
+      return { queued, duplicate: false, deliveryId };
+    }
+  };
+}

package/src/external/write-controller.js

@@ -0,0 +1,283 @@
+// External Write Controller — Slice 3.5
+// Manages WriteIntent lifecycle: creation, approval enforcement, idempotency,
+// retry logic, and confirmation recording.
+
+import { createResource, clone } from '../resource-model.js';
+
+export const WRITE_CONTROLLER_BOUNDARY = {
+  role: 'external-write-controller',
+  scope: 'WriteIntent lifecycle — creation, approval, rejection, execution with retry',
+  owns: ['WriteIntent creation', 'approval gate', 'retry logic', 'idempotency key'],
+  delegatesTo: ['resource-model'],
+  mustNotOwn: ['conflict resolution', 'sync state', 'external API client']
+};
+
+const VALID_PHASES = ['PendingApproval', 'ReadyToSend', 'Sending', 'Retrying', 'Succeeded', 'Failed', 'Rejected'];
+
+// ---------------------------------------------------------------------------
+// Idempotency key
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate a deterministic idempotency key for a write operation.
+ * The key is stable for the same (interfaceKey, operation, resourceRef, payload).
+ *
+ * @param {{ interfaceKey: string, operation: string, resourceRef: string, payload: object }} input
+ * @returns {string}
+ */
+export function getIdempotencyKey({ interfaceKey, operation, resourceRef, payload }) {
+  const canonical = JSON.stringify({ interfaceKey, operation, resourceRef, payload }, Object.keys({ interfaceKey, operation, resourceRef, payload }).sort());
+  // Simple deterministic hash using djb2-style accumulation (no external deps)
+  let hash = 5381;
+  for (let i = 0; i < canonical.length; i++) {
+    hash = ((hash << 5) + hash) ^ canonical.charCodeAt(i);
+    hash = hash >>> 0; // keep 32-bit unsigned
+  }
+  return `idem-${interfaceKey}-${operation}-${hash.toString(16)}`;
+}
+
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate a WriteIntent input object.
+ *
+ * @param {object} input
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateWriteIntent(input) {
+  const errors = [];
+  if (!input) {
+    return { valid: false, errors: ['input must not be null or undefined'] };
+  }
+  if (!input.interfaceKey || typeof input.interfaceKey !== 'string') {
+    errors.push('interfaceKey is required and must be a non-empty string');
+  }
+  if (!input.operation || typeof input.operation !== 'string') {
+    errors.push('operation is required and must be a non-empty string');
+  }
+  if (!input.resourceRef || typeof input.resourceRef !== 'string') {
+    errors.push('resourceRef is required and must be a non-empty string');
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+// ---------------------------------------------------------------------------
+// Controller factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a WriteController that manages ExternalWriteIntent resources.
+ *
+ * @param {{ persistFn?: (resource: object) => Promise<any> }} [opts]
+ *   Optional persistFn is called (fire-and-forget) after intent state changes.
+ * @returns {object}
+ */
+export function createWriteController({ persistFn } = {}) {
+  /**
+   * Fire-and-forget persistence helper.
+   * @param {object} resource
+   */
+  function persist(resource) {
+    if (typeof persistFn === 'function') {
+      Promise.resolve(persistFn(resource)).catch(() => {});
+    }
+  }
+
+  return {
+    role: 'write-controller',
+
+    /**
+     * Create a new ExternalWriteIntent resource.
+     * If requiresApproval is true, phase starts as PendingApproval.
+     * If requiresApproval is false, phase starts as ReadyToSend.
+     *
+     * @param {{ interfaceKey, operation, payload, resourceRef, requiresApproval?, maxRetries?, namespace?, organizationRef? }} input
+     * @returns {{ intent: object } | { error: true, message: string }}
+     */
+    createWriteIntent({
+      interfaceKey,
+      operation,
+      payload = {},
+      resourceRef,
+      requiresApproval = false,
+      maxRetries = 3,
+      namespace = 'default',
+      organizationRef = 'default'
+    }) {
+      const validation = validateWriteIntent({ interfaceKey, operation, resourceRef });
+      if (!validation.valid) {
+        return { error: true, message: validation.errors.join('; ') };
+      }
+
+      const idempotencyKey = getIdempotencyKey({ interfaceKey, operation, resourceRef, payload });
+      const now = new Date().toISOString();
+      const intentName = `write-intent-${idempotencyKey}-${Date.now()}`;
+      const phase = requiresApproval ? 'PendingApproval' : 'ReadyToSend';
+
+      const intent = createResource('ExternalWriteIntent', { name: intentName, namespace }, {
+        organizationRef,
+        interfaceKey,
+        operation,
+        payload,
+        resourceRef,
+        requiresApproval,
+        maxRetries,
+        idempotencyKey
+      });
+      intent.status = {
+        phase,
+        retryCount: 0,
+        createdAt: now
+      };
+
+      persist(intent);
+      return { intent };
+    },
+
+    /**
+     * Approve a PendingApproval intent, transitioning it to ReadyToSend.
+     *
+     * @param {{ intentName, approvedBy, resources }} opts
+     * @returns {{ intent: object } | { error: true, reason: string, message: string }}
+     */
+    approveWriteIntent({ intentName, approvedBy, resources = {} }) {
+      if (!intentName) {
+        return { error: true, reason: 'missing-name', message: 'intentName is required' };
+      }
+      if (!approvedBy) {
+        return { error: true, reason: 'missing-approver', message: 'approvedBy is required' };
+      }
+
+      const intents = resources.ExternalWriteIntent || [];
+      const found = intents.find((i) => i.metadata?.name === intentName);
+      if (!found) {
+        return { error: true, reason: 'not-found', message: `ExternalWriteIntent not found: ${intentName}` };
+      }
+      if (found.status?.phase !== 'PendingApproval') {
+        return { error: true, reason: 'invalid-phase', message: `Intent is not in PendingApproval: ${found.status?.phase}` };
+      }
+
+      const updated = clone(found);
+      updated.status = {
+        ...updated.status,
+        phase: 'ReadyToSend',
+        approvedBy,
+        approvedAt: new Date().toISOString()
+      };
+
+      persist(updated);
+      return { intent: updated };
+    },
+
+    /**
+     * Reject a PendingApproval intent, transitioning it to Rejected.
+     *
+     * @param {{ intentName, rejectedBy, reason, resources }} opts
+     * @returns {{ intent: object } | { error: true, reason: string, message: string }}
+     */
+    rejectWriteIntent({ intentName, rejectedBy, reason = '', resources = {} }) {
+      if (!intentName) {
+        return { error: true, reason: 'missing-name', message: 'intentName is required' };
+      }
+      if (!rejectedBy) {
+        return { error: true, reason: 'missing-rejecter', message: 'rejectedBy is required' };
+      }
+
+      const intents = resources.ExternalWriteIntent || [];
+      const found = intents.find((i) => i.metadata?.name === intentName);
+      if (!found) {
+        return { error: true, reason: 'not-found', message: `ExternalWriteIntent not found: ${intentName}` };
+      }
+      if (found.status?.phase !== 'PendingApproval') {
+        return { error: true, reason: 'invalid-phase', message: `Intent is not in PendingApproval: ${found.status?.phase}` };
+      }
+
+      const updated = clone(found);
+      updated.status = {
+        ...updated.status,
+        phase: 'Rejected',
+        rejectedBy,
+        rejectedAt: new Date().toISOString(),
+        rejectionReason: reason
+      };
+
+      persist(updated);
+      return { intent: updated };
+    },
+
+    /**
+     * Execute a WriteIntent by calling the provided executor function.
+     * Handles Sending → Succeeded / Retrying → Failed lifecycle.
+     *
+     * @param {{ intentName, resources, executor, onPhaseChange? }} opts
+     * @returns {Promise<{ intent: object } | { error: true, intent: object, message: string }>}
+     */
+    async executeWriteIntent({ intentName, resources = {}, executor, onPhaseChange }) {
+      if (!intentName) {
+        return { error: true, message: 'intentName is required' };
+      }
+      if (typeof executor !== 'function') {
+        return { error: true, message: 'executor must be a function' };
+      }
+
+      const intents = resources.ExternalWriteIntent || [];
+      const found = intents.find((i) => i.metadata?.name === intentName);
+      if (!found) {
+        return { error: true, message: `ExternalWriteIntent not found: ${intentName}` };
+      }
+      if (found.status?.phase !== 'ReadyToSend') {
+        return { error: true, message: `Intent is not ReadyToSend: ${found.status?.phase}` };
+      }
+
+      const maxRetries = found.spec?.maxRetries ?? 3;
+      let intent = clone(found);
+
+      // Transition to Sending
+      intent.status = { ...intent.status, phase: 'Sending', sendingAt: new Date().toISOString() };
+      if (onPhaseChange) onPhaseChange('Sending');
+
+      let lastError = null;
+      let attempt = 0;
+
+      while (attempt <= maxRetries) {
+        try {
+          const externalResult = await executor();
+          intent.status = {
+            ...intent.status,
+            phase: 'Succeeded',
+            succeededAt: new Date().toISOString(),
+            externalResult,
+            retryCount: attempt
+          };
+          if (onPhaseChange) onPhaseChange('Succeeded');
+          return { intent };
+        } catch (err) {
+          lastError = err;
+          attempt++;
+          if (attempt <= maxRetries) {
+            intent.status = {
+              ...intent.status,
+              phase: 'Retrying',
+              retryCount: attempt,
+              lastError: err.message
+            };
+            if (onPhaseChange) onPhaseChange('Retrying');
+          }
+        }
+      }
+
+      // Exhausted retries
+      intent.status = {
+        ...intent.status,
+        phase: 'Failed',
+        failedAt: new Date().toISOString(),
+        retryCount: attempt - 1,
+        lastError: lastError?.message ?? 'unknown error'
+      };
+      if (onPhaseChange) onPhaseChange('Failed');
+      return { error: true, intent, message: `Execution failed after ${attempt - 1} retries: ${lastError?.message}` };
+    }
+  };
+}