@a5c-ai/kradle 5.0.1-staging.3abdf9534c25

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}` };
+    }
+  };
+}

package/src/gitea-backend.js

@@ -0,0 +1,131 @@
+export function createGiteaBackend({ baseUrl = 'http://kradle-gitea-http:3000', token, fetchImpl = globalThis.fetch } = {}) {
+  if (!fetchImpl) throw new Error('Gitea backend requires a fetch implementation');
+  const root = baseUrl.replace(/\/$/, '');
+
+  async function request(method, path, body) {
+    const response = await fetchImpl(`${root}/api/v1${path}`, {
+      method,
+      headers: {
+        Accept: 'application/json',
+        'Content-Type': 'application/json',
+        ...(token ? { Authorization: `token ${token}` } : {})
+      },
+      ...(body === undefined ? {} : { body: JSON.stringify(body) })
+    });
+    if (!response.ok) throw new Error(`Gitea ${method} ${path} failed with ${response.status}`);
+    return response.status === 204 ? null : response.json();
+  }
+
+  return {
+    role: 'gitea-backend',
+    baseUrl: root,
+    createOrganization({ name, fullName = name, description = '', visibility = 'private' }) {
+      return request('POST', '/orgs', { username: name, full_name: fullName, description, visibility });
+    },
+    createUser({ username, email, fullName = username, password, mustChangePassword = true }) {
+      return request('POST', '/admin/users', { username, email, full_name: fullName, password, must_change_password: mustChangePassword });
+    },
+    editUser({ username, email, fullName, active = true, admin = false }) {
+      return request('PATCH', `/admin/users/${encodeURIComponent(username)}`, { email, full_name: fullName, active, admin });
+    },
+    addUserSshKey({ title, key, readOnly = false }) {
+      return request('POST', '/user/keys', { title, key, read_only: readOnly });
+    },
+    createRepository({ owner, name, private: isPrivate = true, defaultBranch = 'main', description = '' }) {
+      const path = owner ? `/orgs/${encodeURIComponent(owner)}/repos` : '/user/repos';
+      return request('POST', path, { name, private: isPrivate, default_branch: defaultBranch, description, auto_init: false });
+    },
+    addDeployKey({ owner, repo, title, key, readOnly = true }) {
+      return request('POST', `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/keys`, { title, key, read_only: readOnly });
+    },
+    addCollaborator({ owner, repo, username, permission = 'read' }) {
+      return request('PUT', `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/collaborators/${encodeURIComponent(username)}`, { permission });
+    },
+    addTeamRepository({ org, team, repo, owner = org, permission = 'read' }) {
+      return request('PUT', `/teams/${encodeURIComponent(team)}/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}`, { permission });
+    },
+    createTeam({ org, name, permission = 'read', units = ['repo.code', 'repo.pulls', 'repo.issues'] }) {
+      return request('POST', `/orgs/${encodeURIComponent(org)}/teams`, { name, permission, units });
+    },
+    addTeamMember({ team, username }) {
+      return request('PUT', `/teams/${encodeURIComponent(team)}/members/${encodeURIComponent(username)}`);
+    },
+    protectBranch({ owner, repo, branch = 'main', approvals = 1, statusChecks = [] }) {
+      return request('POST', `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/branch_protections`, {
+        branch_name: branch,
+        enable_push: false,
+        enable_push_whitelist: true,
+        required_approvals: approvals,
+        enable_status_check: statusChecks.length > 0,
+        status_check_contexts: statusChecks
+      });
+    },
+    createIssue({ owner, repo, title, body = '', labels = [], assignees = [] }) {
+      return request('POST', `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/issues`, { title, body, labels, assignees });
+    },
+    createPullRequest({ owner, repo, title, head, base = 'main', body = '' }) {
+      return request('POST', `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/pulls`, { title, head, base, body });
+    },
+    createWebhook({ owner, repo, url, events = ['push', 'pull_request'], secret }) {
+      return request('POST', `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/hooks`, {
+        type: 'gitea',
+        active: true,
+        events,
+        config: { url, content_type: 'json', ...(secret ? { secret } : {}) }
+      });
+    }
+  };
+}
+
+export function orgMemoryRepositoryName(org = 'default') {
+  return `_${String(org || 'default').replace(/[^a-zA-Z0-9.-]+/g, '-')}_`;
+}
+
+export function giteaIssueSyncPlan({ org = 'default', project = null, issue = null, repositories = [] } = {}) {
+  const owner = org;
+  const repo = orgMemoryRepositoryName(org);
+  const issueName = issue?.metadata?.name || issue?.name || '<issue>';
+  return {
+    backend: 'gitea',
+    owner,
+    repo,
+    issue: issueName,
+    project,
+    repositoryRefs: repositories,
+    metadataKeys: ['kradle.a5c.ai/project', 'kradle.a5c.ai/repositories'],
+    actions: [
+      { action: 'ensureOrgMemoryRepository', owner, repo },
+      { action: 'syncIssue', owner, repo, issue: issueName },
+      { action: 'writeIssueRepositoryMetadata', issue: issueName, repositories }
+    ]
+  };
+}
+
+export function githubProjectIssueSyncPlan({ org = 'default', project = null, issue = null, repositories = [] } = {}) {
+  return {
+    backend: 'github',
+    owner: org,
+    project,
+    issue: issue?.metadata?.name || issue?.name || '<issue>',
+    repositoryRefs: repositories,
+    metadataKeys: ['project item fields', 'kradle repositories field'],
+    actions: ['syncProjectItem', 'syncIssueMetadata', 'syncRepositoryLinks']
+  };
+}
+
+export function giteaRepositoryIntegrationPlan({ owner, repo, deployKeyTitle = 'kradle-gitops', permission = 'write', branch = 'main', webhookUrl }) {
+  return {
+    backend: 'gitea',
+    operations: [
+      { action: 'createOrganization', owner },
+      { action: 'createRepository', owner, repo },
+      { action: 'ensureUserMappings', owner },
+      { action: 'addDeployKey', owner, repo, title: deployKeyTitle, readOnly: false },
+      { action: 'addUserSshKey', owner, repo, title: 'developer key' },
+      { action: 'addCollaborator', owner, repo, permission },
+      { action: 'addTeamRepository', owner, repo, team: 'maintainers', permission: 'admin' },
+      { action: 'protectBranch', owner, repo, branch },
+      { action: 'createWebhook', owner, repo, url: webhookUrl }
+    ]
+  };
+}