avorelo 0.1.0 → 0.2.0

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

@@ -1,455 +0,0 @@
-"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,
-};