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

package/src/agent-permission-review.js

@@ -0,0 +1,250 @@
+import { createHash } from 'node:crypto';
+import { clone } from './resource-model.js';
+
+export const AGENT_PERMISSION_REVIEW_BOUNDARY = {
+  role: 'agent-permission-review',
+  scope: 'Deterministic permission review for agent dispatch decisions',
+  owns: ['capability expansion', 'grant resolution', 'permission snapshot creation'],
+  delegatesTo: ['resource-model'],
+  mustNotOwn: ['secret values', 'native K8s API calls', 'runtime execution']
+};
+
+const VALID_APPROVAL_MODES = new Set(['yolo', 'prompt', 'deny']);
+
+export function createPermissionReviewer(options = {}) {
+  return {
+    role: 'agent-permission-review',
+
+    reviewPermissions({ repository, ref, actor, agentStack, triggerSource, taskKind, runnerPool, toolRefs = [], skillRefs = [], mcpServerRefs = [], contextLabelRefs = [], workspacePolicyRef, isFork = false, resources = {} }) {
+      const reasons = [];
+      const grants = [];
+      const crossOrgDenials = [];
+      const untrustedForkWarnings = [];
+
+      // Step 1 — Resolve AgentStack
+      const stacks = resources.AgentStack || [];
+      const stack = stacks.find((s) => s.metadata?.name === agentStack);
+      if (!stack) {
+        return buildDecision({ decision: 'denied', reasons: [{ severity: 'error', message: `AgentStack not found: ${agentStack}` }], grants, capabilities: {}, actor, repository, ref, agentStack, taskKind, crossOrgDenials, untrustedForkWarnings });
+      }
+
+      // Step 1a — Validate approvalMode
+      const approvalMode = stack.spec?.approvalMode;
+      if (approvalMode !== undefined && !VALID_APPROVAL_MODES.has(approvalMode)) {
+        reasons.push({ severity: 'error', message: `Invalid approvalMode '${approvalMode}': must be one of ${[...VALID_APPROVAL_MODES].join(', ')}` });
+      }
+
+      // Step 1b — Deny mode blocks everything immediately
+      if (approvalMode === 'deny') {
+        reasons.push({ severity: 'error', message: `approvalMode is 'deny': all requests are blocked by policy` });
+        return buildDecision({ decision: 'denied', reasons, grants, capabilities: {}, actor, repository, ref, agentStack, taskKind, approvalMode, crossOrgDenials, untrustedForkWarnings });
+      }
+
+      // Step 2 — Cross-org denial check
+      const agentOrg = stack.spec?.organizationRef;
+      if (agentOrg && repository) {
+        // repository format: '<org>/<repo>' or just '<repo>'
+        const repoParts = repository.split('/');
+        const repoOrg = repoParts.length >= 2 ? repoParts[0] : null;
+        if (repoOrg && repoOrg !== agentOrg) {
+          crossOrgDenials.push({ agentOrg, resourceOrg: repoOrg, resource: repository });
+          reasons.push({ severity: 'error', message: `Cross-org access denied: agent org '${agentOrg}' cannot access repository in org '${repoOrg}'` });
+        }
+      }
+
+      // Step 3 — Expand capabilities from stack spec
+      const capabilities = {
+        toolRefs: clone(stack.spec?.toolPolicy ? [stack.spec.toolPolicy] : toolRefs),
+        mcpServerRefs: clone(stack.spec?.mcpServerRefs || mcpServerRefs),
+        skillRefs: clone(stack.spec?.skillRefs || skillRefs),
+        subagentRefs: clone(stack.spec?.subagentRefs || [])
+      };
+
+      // Step 4 — Untrusted fork detection
+      const isForkRef = isFork || /^refs\/pull\/\d+\//.test(ref);
+      if (isForkRef) {
+        const blockedKinds = ['AgentServiceAccount', 'AgentSecretGrant'];
+        untrustedForkWarnings.push({
+          ref,
+          isFork: true,
+          blockedKinds,
+          message: `Untrusted fork detected for ref '${ref}': privileged grants restricted`
+        });
+        reasons.push({ severity: 'warning', message: `Untrusted fork detected for ref '${ref}': privileged grants (${blockedKinds.join(', ')}) are not auto-approved` });
+      }
+
+      // Step 5 — Check runtime identity (AgentServiceAccount)
+      const serviceAccountRef = stack.spec?.runtimeIdentity?.serviceAccountRef || stack.spec?.runtimeIdentity;
+      const serviceAccounts = resources.AgentServiceAccount || [];
+      const serviceAccount = serviceAccounts.find((sa) => sa.metadata?.name === serviceAccountRef);
+      if (!serviceAccount) {
+        reasons.push({ severity: 'error', message: `Missing AgentServiceAccount: ${serviceAccountRef}` });
+      } else {
+        const saGrant = { kind: 'AgentServiceAccount', name: serviceAccount.metadata.name, status: 'bound' };
+        if (isForkRef) {
+          saGrant.status = 'fork-restricted';
+        }
+        grants.push(saGrant);
+      }
+
+      // Step 6 — Check role bindings
+      const roleBindings = resources.AgentRoleBinding || [];
+      const matchedBindings = roleBindings.filter((rb) => rb.spec?.subject === serviceAccountRef || rb.spec?.subject === agentStack);
+      for (const binding of matchedBindings) {
+        grants.push({ kind: 'AgentRoleBinding', name: binding.metadata.name, roleRef: binding.spec?.roleRef, scope: binding.spec?.scope, status: 'bound' });
+      }
+      if (matchedBindings.length === 0 && serviceAccount) {
+        reasons.push({ severity: 'warning', message: `No AgentRoleBinding found for subject: ${serviceAccountRef}` });
+      }
+
+      // Step 7 — Check secret grants
+      const secretGrants = resources.AgentSecretGrant || [];
+      const neededSecrets = collectSecretNeeds(stack, capabilities, resources);
+      for (const need of neededSecrets) {
+        const match = secretGrants.find((sg) => {
+          if (sg.spec?.subject !== serviceAccountRef && sg.spec?.subject !== agentStack) return false;
+          if (need.purpose && sg.spec?.purpose !== need.purpose) return false;
+          if (sg.spec?.allowedRepositories && sg.spec.allowedRepositories.length > 0 && !sg.spec.allowedRepositories.includes(repository)) return false;
+          if (sg.spec?.allowedRefs && sg.spec.allowedRefs.length > 0 && !sg.spec.allowedRefs.includes(ref)) return false;
+          return true;
+        });
+        if (!match) {
+          reasons.push({ severity: 'error', message: `Missing AgentSecretGrant for ${need.description} (purpose: ${need.purpose})` });
+        } else {
+          const grantEntry = { kind: 'AgentSecretGrant', name: match.metadata.name, purpose: match.spec?.purpose, status: 'granted' };
+          if (isForkRef) {
+            grantEntry.status = 'fork-restricted';
+          } else if (match.spec?.requiredApproval) {
+            grantEntry.status = 'requires-approval';
+            grantEntry.requiredApproval = match.spec.requiredApproval;
+            reasons.push({ severity: 'info', message: `AgentSecretGrant ${match.metadata.name} requires approval: ${match.spec.requiredApproval}` });
+          }
+          grants.push(grantEntry);
+        }
+      }
+
+      // Step 8 — Check config grants
+      const configGrants = resources.AgentConfigGrant || [];
+      const neededConfigs = collectConfigNeeds(stack, capabilities, resources);
+      for (const need of neededConfigs) {
+        const match = configGrants.find((cg) => {
+          if (cg.spec?.subject !== serviceAccountRef && cg.spec?.subject !== agentStack) return false;
+          if (need.purpose && cg.spec?.purpose !== need.purpose) return false;
+          return true;
+        });
+        if (!match) {
+          reasons.push({ severity: 'error', message: `Missing AgentConfigGrant for ${need.description} (purpose: ${need.purpose})` });
+        } else {
+          grants.push({ kind: 'AgentConfigGrant', name: match.metadata.name, purpose: match.spec?.purpose, status: 'granted' });
+        }
+      }
+
+      // Step 9 — Workspace policy enforcement
+      if (workspacePolicyRef) {
+        const policies = resources.KrateWorkspacePolicy || [];
+        const policy = policies.find((p) => p.metadata?.name === workspacePolicyRef);
+        if (policy) {
+          // Check maxConcurrentSessions
+          if (policy.spec?.maxConcurrentSessions === 0) {
+            reasons.push({ severity: 'error', message: `Workspace policy '${workspacePolicyRef}' maxConcurrentSessions is 0: no sessions allowed` });
+          }
+          // Check deniedTools
+          const deniedTools = policy.spec?.deniedTools || [];
+          const requestedTools = capabilities.toolRefs;
+          for (const tool of requestedTools) {
+            if (deniedTools.includes(tool)) {
+              reasons.push({ severity: 'error', message: `Tool '${tool}' is denied by workspace policy '${workspacePolicyRef}'` });
+            }
+          }
+          // Check allowedTools (if specified, only those tools are permitted)
+          const allowedTools = policy.spec?.allowedTools;
+          if (allowedTools && allowedTools.length > 0) {
+            for (const tool of requestedTools) {
+              if (!allowedTools.includes(tool)) {
+                reasons.push({ severity: 'error', message: `Tool '${tool}' is not in allowedTools for workspace policy '${workspacePolicyRef}'` });
+              }
+            }
+          }
+        }
+      }
+
+      // Step 10 — Decision
+      const hasErrors = reasons.some((r) => r.severity === 'error');
+      const hasApprovals = grants.some((g) => g.status === 'requires-approval');
+      let decision;
+      if (hasErrors) {
+        decision = 'denied';
+      } else if (hasApprovals) {
+        decision = 'requires-approval';
+      } else {
+        decision = 'allowed';
+      }
+
+      return buildDecision({ decision, reasons, grants, capabilities, actor, repository, ref, agentStack, taskKind, approvalMode, crossOrgDenials, untrustedForkWarnings });
+    },
+
+    createPermissionSnapshot(reviewResult) {
+      const snapshot = clone(reviewResult);
+      snapshot.snapshotAt = new Date().toISOString();
+      snapshot.frozen = true;
+      snapshot.digest = reviewResult.digest;
+      return Object.freeze(snapshot);
+    }
+  };
+}
+
+function collectSecretNeeds(stack, capabilities, resources) {
+  const needs = [];
+  if (stack.spec?.adapter) {
+    needs.push({ description: `model provider for adapter ${stack.spec.adapter}`, purpose: 'model-provider' });
+  }
+  const mcpServers = resources.AgentMcpServer || [];
+  for (const ref of capabilities.mcpServerRefs) {
+    const server = mcpServers.find((s) => s.metadata?.name === ref);
+    if (server?.spec?.secretRef) {
+      needs.push({ description: `MCP server ${ref} secret`, purpose: `mcp-server:${ref}` });
+    }
+  }
+  return needs;
+}
+
+function collectConfigNeeds(stack, capabilities, resources) {
+  const needs = [];
+  const mcpServers = resources.AgentMcpServer || [];
+  for (const ref of capabilities.mcpServerRefs) {
+    const server = mcpServers.find((s) => s.metadata?.name === ref);
+    if (server?.spec?.configMapRef) {
+      needs.push({ description: `MCP server ${ref} config`, purpose: `mcp-server:${ref}` });
+    }
+  }
+  return needs;
+}
+
+function buildDecision({ decision, reasons, grants, capabilities, actor, repository, ref, agentStack, taskKind, approvalMode, crossOrgDenials = [], untrustedForkWarnings = [] }) {
+  const result = {
+    decision,
+    actor,
+    repository,
+    ref,
+    agentStack,
+    taskKind,
+    capabilities: clone(capabilities),
+    grants: clone(grants),
+    reasons: clone(reasons),
+    crossOrgDenials: clone(crossOrgDenials),
+    untrustedForkWarnings: clone(untrustedForkWarnings),
+    reviewedAt: new Date().toISOString()
+  };
+  if (approvalMode !== undefined) {
+    result.approvalMode = approvalMode;
+  }
+  result.digest = computeDigest(result);
+  return result;
+}
+
+function computeDigest(result) {
+  const keys = Object.keys(result).filter((k) => k !== 'digest' && k !== 'reviewedAt').sort();
+  const canonical = {};
+  for (const key of keys) canonical[key] = result[key];
+  return createHash('sha256').update(JSON.stringify(canonical)).digest('hex');
+}

package/src/agent-project-controller.js

@@ -0,0 +1,117 @@
+// Agent Project Controller — Slice 1.2d
+// Manages KrateProject resources: validation, workflow columns, board state, and issue assignment.
+
+export const AGENT_PROJECT_CONTROLLER_BOUNDARY = {
+  role: 'agent-project-controller',
+  scope: 'KrateProject lifecycle: validation, workflow column definitions, board state management, issue assignment tracking',
+  owns: ['project validation', 'workflow columns', 'board state', 'default column resolution', 'issue assignment tracking'],
+  delegatesTo: ['resource-model'],
+  mustNotOwn: ['issue content', 'PR lifecycle', 'dispatch execution', 'Agent Mux sessions']
+};
+
+const VALID_BOARD_STATES = ['active', 'archived'];
+
+/**
+ * Validate a KrateProject resource. Returns { valid, errors }.
+ * @param {object} resource
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateAgentProject(resource) {
+  const errors = [];
+
+  // Guard against null/undefined resource
+  if (resource == null) {
+    errors.push('resource must not be null or undefined');
+    return { valid: false, errors };
+  }
+
+  // Validate metadata.name
+  if (!resource?.metadata?.name) {
+    errors.push('metadata.name is required');
+  }
+
+  const spec = resource?.spec || {};
+
+  // Validate organizationRef
+  if (!spec.organizationRef) {
+    errors.push('spec.organizationRef is required');
+  }
+
+  // Validate workflowColumns — must be a non-empty array
+  const cols = spec.workflowColumns;
+  if (!Array.isArray(cols) || cols.length === 0) {
+    errors.push('spec.workflowColumns must be a non-empty array');
+  } else {
+    // Check for duplicate column IDs
+    const seen = new Set();
+    for (const col of cols) {
+      if (seen.has(col.id)) {
+        errors.push(`spec.workflowColumns contains duplicate column ID: "${col.id}"`);
+        break;
+      }
+      seen.add(col.id);
+    }
+  }
+
+  // Validate boardState if explicitly set
+  const boardState = spec.boardState;
+  if (boardState != null && !VALID_BOARD_STATES.includes(boardState)) {
+    errors.push(`spec.boardState "${boardState}" is not supported; valid states are: ${VALID_BOARD_STATES.join(', ')}`);
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Factory that returns a KrateProject controller instance.
+ */
+export function createAgentProjectController() {
+  return {
+    role: 'agent-project-controller',
+
+    /**
+     * Validate a KrateProject resource.
+     * @param {object} resource
+     * @returns {{ valid: boolean, errors: string[] }}
+     */
+    validate(resource) {
+      return validateAgentProject(resource);
+    },
+
+    /**
+     * Return the workflow columns for a project, in order.
+     * @param {object} resource
+     * @returns {Array<{ id: string, displayName: string, color: string, default?: boolean }>}
+     */
+    getWorkflowColumns(resource) {
+      const cols = resource?.spec?.workflowColumns;
+      if (!Array.isArray(cols)) {
+        return [];
+      }
+      return [...cols];
+    },
+
+    /**
+     * Return the default column — the one marked `default: true`, or the first column.
+     * @param {object} resource
+     * @returns {{ id: string, displayName: string, color: string, default?: boolean } | undefined}
+     */
+    getDefaultColumn(resource) {
+      const cols = Array.isArray(resource?.spec?.workflowColumns)
+        ? resource.spec.workflowColumns
+        : [];
+      const marked = cols.find((c) => c.default === true);
+      return marked ?? cols[0];
+    },
+
+    /**
+     * Return the board state for a project.
+     * Defaults to 'active' when spec.boardState is not set.
+     * @param {object} resource
+     * @returns {string}
+     */
+    getBoardState(resource) {
+      return resource?.spec?.boardState ?? 'active';
+    }
+  };
+}

package/src/agent-provider-config-controller.js

@@ -0,0 +1,150 @@
+// Agent Provider Config Controller — Slice 1.2c
+// Manages AgentProviderConfig resources: model provider config validation,
+// endpoint resolution, credential ref validation, and feature flag management.
+
+export const AGENT_PROVIDER_CONFIG_CONTROLLER_BOUNDARY = {
+  role: 'agent-provider-config-controller',
+  scope: 'AgentProviderConfig lifecycle: validation, endpoint resolution, credential ref validation, feature flags',
+  owns: ['provider config validation', 'endpoint resolution', 'credential ref validation', 'feature flag defaults', 'rate limit defaults'],
+  delegatesTo: ['resource-model'],
+  mustNotOwn: ['secret values', 'dispatch execution', 'Agent Mux sessions', 'adapter implementation']
+};
+
+const VALID_PROVIDER_TYPES = ['anthropic', 'openai', 'azure-openai', 'google-vertex', 'foundry', 'custom'];
+
+const DEFAULT_ENDPOINTS = Object.freeze({
+  anthropic: 'https://api.anthropic.com/v1',
+  openai: 'https://api.openai.com/v1',
+  'azure-openai': null,   // requires explicit endpoint (tenant-specific)
+  'google-vertex': 'https://us-central1-aiplatform.googleapis.com/v1',
+  foundry: null,          // requires explicit endpoint
+  custom: null            // requires explicit endpoint
+});
+
+const DEFAULT_FEATURE_FLAGS = Object.freeze({
+  streaming: true,
+  tool_use: true,
+  vision: false
+});
+
+const DEFAULT_RATE_LIMITS = Object.freeze({
+  requestsPerMinute: 60,
+  tokensPerMinute: 100000
+});
+
+/**
+ * Validate an AgentProviderConfig resource. Returns { valid, errors }.
+ * @param {object} resource
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateAgentProviderConfig(resource) {
+  const errors = [];
+
+  // Guard against null/undefined resource
+  if (resource == null) {
+    errors.push('resource must not be null or undefined');
+    return { valid: false, errors };
+  }
+
+  // Validate metadata.name
+  if (!resource?.metadata?.name) {
+    errors.push('metadata.name is required');
+  }
+
+  const spec = resource?.spec || {};
+
+  // Validate providerType
+  const providerType = spec.providerType;
+  if (!providerType) {
+    errors.push(`spec.providerType is required; valid types are: ${VALID_PROVIDER_TYPES.join(', ')}`);
+  } else if (!VALID_PROVIDER_TYPES.includes(providerType)) {
+    errors.push(`spec.providerType "${providerType}" is not supported; valid types are: ${VALID_PROVIDER_TYPES.join(', ')}`);
+  }
+
+  // Validate credentialRef — always required for security
+  if (!spec.credentialRef) {
+    errors.push('spec.credentialRef is required; provide a Kubernetes Secret name for the API key');
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Factory that returns an AgentProviderConfig controller instance.
+ */
+export function createAgentProviderConfigController() {
+  return {
+    role: 'agent-provider-config-controller',
+
+    /**
+     * Validate an AgentProviderConfig resource.
+     * @param {object} resource
+     * @returns {{ valid: boolean, errors: string[] }}
+     */
+    validate(resource) {
+      return validateAgentProviderConfig(resource);
+    },
+
+    /**
+     * Resolve the effective API endpoint for a provider config.
+     * Returns the explicit spec.endpoint if set, otherwise falls back to
+     * the well-known default for the provider type.
+     * @param {object} resource
+     * @returns {string|null}
+     */
+    resolveEndpoint(resource) {
+      if (resource == null) {
+        throw new Error('resource must not be null or undefined');
+      }
+      const spec = resource?.spec || {};
+
+      // If an explicit endpoint is set in spec, prefer it
+      if (spec.endpoint) {
+        return spec.endpoint;
+      }
+
+      // Fall back to the known default for the provider type
+      const providerType = spec.providerType;
+      return DEFAULT_ENDPOINTS[providerType] ?? null;
+    },
+
+    /**
+     * Return the effective feature flags for a provider config.
+     * Merges spec.featureFlags with defaults; spec values take precedence.
+     * @param {object} resource
+     * @returns {{ streaming: boolean, tool_use: boolean, vision: boolean, [key: string]: boolean }}
+     */
+    getFeatureFlags(resource) {
+      if (resource == null) {
+        throw new Error('resource must not be null or undefined');
+      }
+      const specFlags = resource?.spec?.featureFlags ?? {};
+      return { ...DEFAULT_FEATURE_FLAGS, ...specFlags };
+    },
+
+    /**
+     * Return the effective rate limit configuration for a provider config.
+     * Merges spec.rateLimits with defaults; spec values take precedence.
+     * @param {object} resource
+     * @returns {{ requestsPerMinute: number, tokensPerMinute: number }}
+     */
+    getRateLimits(resource) {
+      if (resource == null) {
+        throw new Error('resource must not be null or undefined');
+      }
+      const specLimits = resource?.spec?.rateLimits ?? {};
+      return {
+        requestsPerMinute: specLimits.requestsPerMinute ?? DEFAULT_RATE_LIMITS.requestsPerMinute,
+        tokensPerMinute: specLimits.tokensPerMinute ?? DEFAULT_RATE_LIMITS.tokensPerMinute
+      };
+    },
+
+    /**
+     * Return the list of supported provider types.
+     * @returns {string[]}
+     */
+    getSupportedProviderTypes() {
+      return [...VALID_PROVIDER_TYPES];
+    }
+  };
+}