avorelo 0.3.8 → 0.4.0-rc.2

package/scripts/lib/agent-access-governance.js

@@ -0,0 +1,455 @@
+"use strict";
+
+const crypto = require("crypto");
+const path = require("path");
+const { canExportReports } = require("./entitlements");
+const { ensureCcoDirs, nowIso, safeReadJson, safeWriteJson } = require("./fsx");
+
+const GOVERNANCE_CONTRACT = "avorelo.agentAccessGovernance.v1";
+const GOVERNANCE_SCHEMA_VERSION = 1;
+const SUBJECT_TYPES = Object.freeze([
+  "agent_surface",
+  "tool",
+  "mcp_server",
+  "browser_integration",
+  "package",
+  "extension",
+  "connector",
+  "skill",
+  "command",
+  "unknown",
+]);
+const TRUST_STATUSES = Object.freeze(["known", "reviewed", "unknown", "blocked"]);
+const REQUESTED_ACTION_TYPES = Object.freeze([
+  "command_run",
+  "tool_call",
+  "mcp_call",
+  "browser_action",
+  "network_request",
+  "file_read",
+  "file_write",
+  "deploy_publish",
+  "auth_billing_ci_prod_change",
+  "unknown",
+]);
+const ACCESS_MODES = Object.freeze(["read_only", "write", "execute", "network", "browser", "unknown"]);
+const DECISIONS = Object.freeze(["allow", "warn", "approval_required", "block"]);
+
+const LATEST_RECEIPT_REL_PATH = ".claude/cco/security/agent-access-governance/latest-receipt.json";
+const HISTORY_DIR_REL_PATH = ".claude/cco/security/agent-access-governance/history";
+const EVENT_LOG_REL_PATH = ".claude/cco/events/agent-access-governance.jsonl";
+
+function sha256(value) {
+  return crypto.createHash("sha256").update(String(value || "")).digest("hex");
+}
+
+function unique(values) {
+  return [...new Set((values || []).filter(Boolean))];
+}
+
+function normalizeEnum(value, allowed, fallback) {
+  const normalized = String(value || "").trim().toLowerCase();
+  return allowed.includes(normalized) ? normalized : fallback;
+}
+
+function normalizeSubjectType(value) {
+  return normalizeEnum(value, SUBJECT_TYPES, "unknown");
+}
+
+function normalizeTrustStatus(value) {
+  return normalizeEnum(value, TRUST_STATUSES, "unknown");
+}
+
+function normalizeRequestedActionType(value) {
+  return normalizeEnum(value, REQUESTED_ACTION_TYPES, "unknown");
+}
+
+function normalizeAccessMode(value) {
+  return normalizeEnum(value, ACCESS_MODES, "unknown");
+}
+
+function normalizePathList(value) {
+  const list = Array.isArray(value) ? value : value ? [value] : [];
+  return list
+    .map((item) => String(item || "").replace(/\\/g, "/").trim())
+    .filter(Boolean);
+}
+
+function normalizeDomainList(value) {
+  const list = Array.isArray(value) ? value : value ? [value] : [];
+  return list
+    .map((item) => String(item || "").trim().toLowerCase())
+    .filter(Boolean);
+}
+
+function normalizeOptionalString(value) {
+  const text = String(value || "").trim();
+  return text || null;
+}
+
+function normalizeOwnerSponsor(value, fallback) {
+  const text = normalizeOptionalString(value);
+  return text || fallback;
+}
+
+function requestedActionTypeFromInput(input = {}, classification = null) {
+  const raw = String(input.actionType || "").trim().toLowerCase();
+  if (raw === "command_run" || raw === "git_operation") return "command_run";
+  if (raw === "tool_call") return "tool_call";
+  if (raw === "mcp_tool_call" || raw === "mcp_call") return "mcp_call";
+  if (raw === "browser_action" || raw === "visual_qa_run") return "browser_action";
+  if (raw === "network_request") return "network_request";
+  if (raw === "file_read") return "file_read";
+  if (raw === "file_write" || raw === "config_change") return "file_write";
+  if (raw === "deploy_operation" || raw === "deploy_publish") return "deploy_publish";
+  const reasonCodes = new Set(classification?.combined?.reasonCodes || []);
+  if (reasonCodes.has("AUTH_OR_BILLING_SCOPE") || reasonCodes.has("DEPLOYMENT_CONFIG") || reasonCodes.has("CI_CONFIG")) {
+    return "auth_billing_ci_prod_change";
+  }
+  return "unknown";
+}
+
+function inferSubjectType(input = {}, requestedActionType = "unknown") {
+  const raw = String(input.actionType || "").trim().toLowerCase();
+  if (input.subject && typeof input.subject === "object" && input.subject.type) {
+    return normalizeSubjectType(input.subject.type);
+  }
+  if (raw === "tool_call") return "tool";
+  if (raw === "mcp_tool_call" || raw === "mcp_call") return "mcp_server";
+  if (raw === "browser_action" || raw === "visual_qa_run") return "browser_integration";
+  if (raw === "command_run" || raw === "git_operation" || raw === "deploy_operation") return "command";
+  if (raw === "package_install" || raw === "package_script") return "package";
+  if (raw === "file_read" || raw === "file_write" || raw === "config_change") return "agent_surface";
+  if (requestedActionType === "auth_billing_ci_prod_change") return "agent_surface";
+  return "unknown";
+}
+
+function inferSubjectTrustStatus(input = {}, requestedActionType = "unknown") {
+  const subject = input.subject && typeof input.subject === "object" ? input.subject : {};
+  const metadata = input.toolMetadata && typeof input.toolMetadata === "object" ? input.toolMetadata : {};
+  if (subject.blocked === true || metadata.blocked === true) return "blocked";
+  if (subject.trustStatus) return normalizeTrustStatus(subject.trustStatus);
+  if (metadata.reviewed === true || metadata.trusted === true) return "reviewed";
+  if (subject.reviewed === true || subject.known === true) return "reviewed";
+  if (["command_run", "file_read", "file_write", "deploy_publish", "auth_billing_ci_prod_change"].includes(requestedActionType)) {
+    return "known";
+  }
+  if (requestedActionType === "browser_action" && /^https?:\/\/(localhost|127\.0\.0\.1|\[::1\]|::1)/i.test(String(input.url || input.target || ""))) {
+    return "known";
+  }
+  return "unknown";
+}
+
+function buildSubjectIdentity(input = {}, classification = null) {
+  const requestedActionType = requestedActionTypeFromInput(input, classification);
+  const explicitSubject = input.subject && typeof input.subject === "object" ? input.subject : {};
+  const metadata = input.toolMetadata && typeof input.toolMetadata === "object" ? input.toolMetadata : {};
+  const type = inferSubjectType(input, requestedActionType);
+  const trustStatus = inferSubjectTrustStatus(input, requestedActionType);
+  const name = normalizeOptionalString(
+    explicitSubject.name
+      || input.toolName
+      || (input.mcpServer && input.toolName ? `${input.mcpServer}:${input.toolName}` : null)
+      || input.mcpServer
+      || input.domain
+      || input.target
+      || input.command
+      || type
+  ) || type;
+  const source = normalizeOptionalString(explicitSubject.source || metadata.source || input.source || input.requestedBy || "local");
+  const configPath = normalizeOptionalString(explicitSubject.configPath || metadata.configPath);
+  const owner = normalizeOwnerSponsor(explicitSubject.owner || metadata.owner, "workspace operator");
+  const sponsor = normalizeOwnerSponsor(explicitSubject.sponsor || metadata.sponsor, "Avorelo local policy");
+  const idSeed = [
+    explicitSubject.id,
+    type,
+    name,
+    source,
+    configPath,
+    owner,
+    sponsor,
+  ].filter(Boolean).join("|");
+
+  return {
+    id: normalizeOptionalString(explicitSubject.id) || `${type}-${sha256(idSeed).slice(0, 12)}`,
+    type,
+    name,
+    source,
+    configPath,
+    owner,
+    sponsor,
+    trustStatus,
+  };
+}
+
+function normalizeRequestedAction(input = {}, classification = null) {
+  const type = requestedActionTypeFromInput(input, classification);
+  return {
+    type,
+    target: sanitizeSummaryText(normalizeOptionalString(input.target || input.command || input.url || input.toolName || input.mcpServer)),
+    task: sanitizeSummaryText(normalizeOptionalString(input.userIntent || input.taskType || input.task)),
+    source: sanitizeSummaryText(normalizeOptionalString(input.requestedBy || input.source || "local")),
+  };
+}
+
+function inferAccessMode(requestedActionType) {
+  if (requestedActionType === "file_read") return "read_only";
+  if (requestedActionType === "file_write" || requestedActionType === "auth_billing_ci_prod_change") return "write";
+  if (requestedActionType === "browser_action") return "browser";
+  if (requestedActionType === "network_request") return "network";
+  if (requestedActionType === "command_run" || requestedActionType === "tool_call" || requestedActionType === "mcp_call" || requestedActionType === "deploy_publish") {
+    return "execute";
+  }
+  return "unknown";
+}
+
+function normalizeScope(input = {}, decision = {}, classification = null) {
+  const requestedAction = normalizeRequestedAction(input, classification);
+  const normalizedPaths = ["file_read", "file_write", "auth_billing_ci_prod_change"].includes(requestedAction.type)
+    ? normalizePathList(input.targetPaths || input.target || [])
+    : [];
+  const normalizedDomains = normalizeDomainList(input.domain || input.url || []);
+  const toolScope = unique([normalizeOptionalString(input.toolName)].filter(Boolean));
+  const mcpScope = unique([normalizeOptionalString(input.mcpServer)].filter(Boolean));
+  const ttlSeconds = Number.isFinite(Number(input.ttlSeconds))
+    ? Math.max(0, Number(input.ttlSeconds))
+    : (Number.isFinite(Number(decision.ttlSeconds)) ? Math.max(0, Number(decision.ttlSeconds)) : null);
+
+  return {
+    accessMode: normalizeAccessMode(inferAccessMode(requestedAction.type)),
+    pathScope: normalizedPaths,
+    domainScope: normalizedDomains,
+    toolScope,
+    mcpScope,
+    allowNetwork: requestedAction.type === "network_request" || requestedAction.type === "browser_action",
+    allowSecrets: input.secretAccess === true,
+    dryRun: input.dryRun === true,
+    testOnly: input.testOnly === true,
+    ttlSeconds,
+    expiresAt: ttlSeconds ? new Date(Date.now() + ttlSeconds * 1000).toISOString() : null,
+  };
+}
+
+function summarizeScope(scope) {
+  return {
+    accessMode: scope.accessMode,
+    pathScope: scope.pathScope,
+    domainScope: scope.domainScope,
+    toolScope: scope.toolScope,
+    mcpScope: scope.mcpScope,
+    allowNetwork: scope.allowNetwork,
+    allowSecrets: scope.allowSecrets,
+    dryRun: scope.dryRun,
+    testOnly: scope.testOnly,
+  };
+}
+
+function buildApprovalBoundary(requestedAction, scope, decision, subject) {
+  const required = decision.decision === "approval_required" || decision.decision === "block";
+  const targetSummary = scope.pathScope[0]
+    || scope.domainScope[0]
+    || scope.toolScope[0]
+    || scope.mcpScope[0]
+    || requestedAction.target
+    || subject.name;
+  return {
+    required,
+    summary: required
+      ? `Review required before ${requestedAction.type} reaches ${targetSummary}.`
+      : "No explicit approval boundary is required for the current scoped action.",
+  };
+}
+
+function buildTtlSummary(scope) {
+  return {
+    ttlSeconds: Number.isFinite(Number(scope.ttlSeconds)) ? Number(scope.ttlSeconds) : null,
+    expiresAt: scope.expiresAt || null,
+    summary: Number.isFinite(Number(scope.ttlSeconds)) && Number(scope.ttlSeconds) > 0
+      ? `Scoped review window: ${Number(scope.ttlSeconds)} seconds.`
+      : "No temporary grant window was recorded.",
+  };
+}
+
+function sanitizeSummaryText(value) {
+  return String(value || "")
+    .replace(/sk-[A-Za-z0-9]{16,}/g, "[redacted-openai-key]")
+    .replace(/ghp_[A-Za-z0-9]{20,}/g, "[redacted-github-token]")
+    .replace(/AKIA[0-9A-Z]{16}/g, "[redacted-aws-key]")
+    .replace(/(bearer\s+)[A-Za-z0-9._-]{8,}/ig, "$1[redacted]");
+}
+
+function buildGovernanceReceipt(input = {}, decision = {}, classification = null) {
+  const subject = buildSubjectIdentity(input, classification);
+  const requestedAction = normalizeRequestedAction(input, classification);
+  const scope = normalizeScope(input, decision, classification);
+  const approvalBoundary = buildApprovalBoundary(requestedAction, scope, decision, subject);
+  const ttlSummary = buildTtlSummary(scope);
+  const reasonCodes = unique(decision.reasonCodes || []);
+
+  return {
+    schemaVersion: GOVERNANCE_SCHEMA_VERSION,
+    contract: GOVERNANCE_CONTRACT,
+    decisionId: decision.decisionId,
+    decision: normalizeEnum(decision.decision, DECISIONS, "warn"),
+    severity: normalizeOptionalString(decision.riskLevel) || "unknown",
+    reasonCodes,
+    subjectSummary: {
+      ...subject,
+      name: sanitizeSummaryText(subject.name),
+      source: sanitizeSummaryText(subject.source),
+      configPath: sanitizeSummaryText(subject.configPath),
+      owner: sanitizeSummaryText(subject.owner),
+      sponsor: sanitizeSummaryText(subject.sponsor),
+    },
+    ownerSponsorSummary: {
+      owner: subject.owner,
+      sponsor: subject.sponsor,
+      trustStatus: subject.trustStatus,
+    },
+    requestedActionSummary: requestedAction,
+    scopeSummary: summarizeScope(scope),
+    approvalBoundary,
+    ttlSummary,
+    saferBoundaryHint: sanitizeSummaryText(decision.saferAlternative || "Keep the action inside the smallest reviewed scope."),
+    evidencePath: null,
+    redacted: true,
+    createdAt: decision.createdAt || nowIso(),
+  };
+}
+
+function writeJsonl(cwd, relPathValue, entry) {
+  const fs = require("fs");
+  const absPath = path.join(cwd, relPathValue);
+  fs.mkdirSync(path.dirname(absPath), { recursive: true });
+  fs.appendFileSync(absPath, `${JSON.stringify(entry)}\n`, "utf8");
+}
+
+function writeGovernanceReceipt(cwd, receipt, options = {}) {
+  ensureCcoDirs(cwd);
+  const payload = {
+    ...receipt,
+    evidencePath: LATEST_RECEIPT_REL_PATH,
+  };
+  safeWriteJson(cwd, LATEST_RECEIPT_REL_PATH, payload);
+  writeJsonl(cwd, EVENT_LOG_REL_PATH, payload);
+
+  if (canExportReports(options.plan || "free")) {
+    safeWriteJson(cwd, `${HISTORY_DIR_REL_PATH}/${payload.decisionId}.json`, payload);
+  }
+
+  return LATEST_RECEIPT_REL_PATH;
+}
+
+function readLatestGovernanceReceipt(cwd) {
+  return safeReadJson(cwd, LATEST_RECEIPT_REL_PATH, null);
+}
+
+function readGovernanceEvents(cwd) {
+  const fs = require("fs");
+  const absPath = path.join(cwd, EVENT_LOG_REL_PATH);
+  if (!fs.existsSync(absPath)) return [];
+  return fs.readFileSync(absPath, "utf8")
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+function buildAgentAccessGovernanceSurface(cwd) {
+  const latestReceipt = readLatestGovernanceReceipt(cwd);
+  const events = readGovernanceEvents(cwd).slice(-50);
+  const trustStatuses = events.map((event) => event?.subjectSummary?.trustStatus).filter(Boolean);
+  const unknownSubjects = trustStatuses.filter((status) => status === "unknown").length;
+  const reviewedSubjects = trustStatuses.filter((status) => status === "known" || status === "reviewed").length;
+  const topReasonCounts = {};
+
+  events.forEach((event) => {
+    (event.reasonCodes || []).forEach((code) => {
+      topReasonCounts[code] = (topReasonCounts[code] || 0) + 1;
+    });
+  });
+
+  const topReasonCodes = Object.entries(topReasonCounts)
+    .sort((left, right) => right[1] - left[1])
+    .slice(0, 3)
+    .map(([code]) => code);
+
+  const status = latestReceipt ? "foundation" : "partial";
+  const nextAction = unknownSubjects > 0
+    ? "Review unknown subjects before relying on write-capable or external actions."
+    : latestReceipt
+      ? "Use governance receipts to keep approval boundaries visible in future risky actions."
+      : "Run `avorelo guard` on a risky action to generate the first governance receipt.";
+
+  return {
+    status,
+    showInStatus: true,
+    showInDashboard: true,
+    subjectsReviewed: reviewedSubjects,
+    unknownSubjects,
+    approvalBoundariesAvailable: Boolean(latestReceipt?.approvalBoundary),
+    latestReceiptPath: latestReceipt ? LATEST_RECEIPT_REL_PATH : null,
+    latestReceipt,
+    topReasonCodes,
+    nextAction,
+    statusLine: `Agent Access Governance: ${status.toUpperCase()} · reviewed=${reviewedSubjects} · unknown=${unknownSubjects} · approval boundaries ${latestReceipt?.approvalBoundary ? "available" : "missing"} · latest receipt ${latestReceipt ? "available" : "missing"}`,
+    dashboardCard: {
+      headline: `Agent Access Governance: ${status.toUpperCase()}`,
+      summary: `Reviewed=${reviewedSubjects}, unknown=${unknownSubjects}, approval boundaries ${latestReceipt?.approvalBoundary ? "available" : "missing"}.`,
+      latestReceiptPath: latestReceipt ? LATEST_RECEIPT_REL_PATH : null,
+      topReasonCodes,
+      nextAction,
+    },
+  };
+}
+
+function applyGovernanceDecisionFloor(decision, receipt) {
+  const next = { ...decision };
+  const subjectTrustStatus = receipt?.subjectSummary?.trustStatus || "unknown";
+  const reasonCodes = new Set(next.reasonCodes || []);
+
+  if (subjectTrustStatus === "blocked") {
+    next.decision = "block";
+    next.blocked = true;
+    next.requiresApproval = false;
+    next.riskLevel = next.riskLevel === "critical" ? next.riskLevel : "high";
+    reasonCodes.add("SUBJECT_BLOCKED");
+    next.explanation = `${next.explanation} The subject is explicitly blocked.`;
+  } else if (subjectTrustStatus === "unknown" && next.decision === "allow" && ["tool_call", "mcp_call", "network_request", "browser_action"].includes(receipt?.requestedActionSummary?.type)) {
+    next.decision = "warn";
+    next.blocked = false;
+    next.requiresApproval = false;
+    reasonCodes.add("SUBJECT_UNKNOWN");
+    next.explanation = `${next.explanation} Subject identity is incomplete, so Avorelo is keeping the action visible.`;
+  }
+
+  next.reasonCodes = Array.from(reasonCodes);
+  return next;
+}
+
+module.exports = {
+  GOVERNANCE_CONTRACT,
+  GOVERNANCE_SCHEMA_VERSION,
+  SUBJECT_TYPES,
+  TRUST_STATUSES,
+  REQUESTED_ACTION_TYPES,
+  ACCESS_MODES,
+  LATEST_RECEIPT_REL_PATH,
+  EVENT_LOG_REL_PATH,
+  buildSubjectIdentity,
+  normalizeRequestedAction,
+  normalizeScope,
+  buildGovernanceReceipt,
+  writeGovernanceReceipt,
+  readLatestGovernanceReceipt,
+  readGovernanceEvents,
+  buildAgentAccessGovernanceSurface,
+  applyGovernanceDecisionFloor,
+};