avorelo 0.1.0

package/scripts/lib/local-pricing.js

@@ -0,0 +1,299 @@
+"use strict";
+
+// ── Local Pricing Source v1 ───────────────────────────────────────────────────
+//
+// Provides a local, offline pricing config for Avorelo cost evidence.
+// No network fetch. No API keys. No secrets.
+// Default-local pricing is allowed only with confidence low/medium and caveat.
+// User override via .claude/cco/config/local-pricing.json.
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+
+const SCHEMA_VERSION = 1;
+const CONTRACT = "avorelo.localPricing.v1";
+const LOCAL_PRICING_CONFIG_REL = ".claude/cco/config/local-pricing.json";
+const LOCAL_PRICING_EVENTS_REL = ".claude/cco/events/pricing.jsonl";
+
+function shortId() {
+  return crypto.randomBytes(4).toString("hex");
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function ensureDirFor(filePath) {
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+}
+
+// ── Default local pricing entries ─────────────────────────────────────────────
+// Based on publicly documented Anthropic/OpenAI pricing tiers as of 2025.
+// These are DEFAULTS only. Confidence: low. User must validate against actual invoices.
+// Do not use for billing reconciliation or exact cost claims.
+
+const DEFAULT_PRICING_ENTRIES = [
+  {
+    provider: "anthropic",
+    model: "claude-sonnet-4-6",
+    modelAlias: "claude-sonnet-4.6",
+    currency: "USD",
+    unit: "per_1m_tokens",
+    inputTokenPrice: 3.0,
+    cachedInputTokenPrice: 0.30,
+    outputTokenPrice: 15.0,
+    cacheWriteTokenPrice: 3.75,
+    cacheReadTokenPrice: 0.30,
+    batchInputTokenPrice: 1.50,
+    batchOutputTokenPrice: 7.50,
+    priorityInputTokenPrice: null,
+    priorityCachedInputTokenPrice: null,
+    priorityOutputTokenPrice: null,
+    sessionRuntimePricePerHour: null,
+    source: "default_local",
+    confidence: "low",
+    caveat: "Default local pricing — may not match actual API billing. Verify with your Anthropic billing dashboard.",
+    effectiveDate: "2025-01-01",
+  },
+  {
+    provider: "anthropic",
+    model: "claude-haiku-4-5",
+    modelAlias: "claude-haiku-4.5",
+    currency: "USD",
+    unit: "per_1m_tokens",
+    inputTokenPrice: 0.80,
+    cachedInputTokenPrice: 0.08,
+    outputTokenPrice: 4.0,
+    cacheWriteTokenPrice: 1.0,
+    cacheReadTokenPrice: 0.08,
+    batchInputTokenPrice: 0.40,
+    batchOutputTokenPrice: 2.0,
+    priorityInputTokenPrice: null,
+    priorityCachedInputTokenPrice: null,
+    priorityOutputTokenPrice: null,
+    sessionRuntimePricePerHour: null,
+    source: "default_local",
+    confidence: "low",
+    caveat: "Default local pricing — may not match actual API billing. Verify with your Anthropic billing dashboard.",
+    effectiveDate: "2025-01-01",
+  },
+  {
+    provider: "anthropic",
+    model: "claude-opus-4-7",
+    modelAlias: "claude-opus-4.7",
+    currency: "USD",
+    unit: "per_1m_tokens",
+    inputTokenPrice: 15.0,
+    cachedInputTokenPrice: 1.50,
+    outputTokenPrice: 75.0,
+    cacheWriteTokenPrice: 18.75,
+    cacheReadTokenPrice: 1.50,
+    batchInputTokenPrice: 7.50,
+    batchOutputTokenPrice: 37.50,
+    priorityInputTokenPrice: null,
+    priorityCachedInputTokenPrice: null,
+    priorityOutputTokenPrice: null,
+    sessionRuntimePricePerHour: null,
+    source: "default_local",
+    confidence: "low",
+    caveat: "Default local pricing — may not match actual API billing. Verify with your Anthropic billing dashboard.",
+    effectiveDate: "2025-01-01",
+  },
+  {
+    provider: "openai",
+    model: "gpt-4o",
+    modelAlias: "gpt-4o",
+    currency: "USD",
+    unit: "per_1m_tokens",
+    inputTokenPrice: 2.50,
+    cachedInputTokenPrice: 1.25,
+    outputTokenPrice: 10.0,
+    cacheWriteTokenPrice: null,
+    cacheReadTokenPrice: 1.25,
+    batchInputTokenPrice: 1.25,
+    batchOutputTokenPrice: 5.0,
+    priorityInputTokenPrice: null,
+    priorityCachedInputTokenPrice: null,
+    priorityOutputTokenPrice: null,
+    sessionRuntimePricePerHour: null,
+    source: "default_local",
+    confidence: "low",
+    caveat: "Default local pricing — may not match actual API billing. Verify with your OpenAI usage dashboard.",
+    effectiveDate: "2025-01-01",
+  },
+];
+
+// ── Build default config ───────────────────────────────────────────────────────
+
+function buildDefaultLocalPricingConfig() {
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    contract: CONTRACT,
+    pricingId: `lp-${Date.now()}-${shortId()}`,
+    createdAt: nowIso(),
+    updatedAt: nowIso(),
+    currency: "USD",
+    source: "default_local",
+    sourceName: "Avorelo default local pricing",
+    effectiveDate: "2025-01-01",
+    entries: JSON.parse(JSON.stringify(DEFAULT_PRICING_ENTRIES)),
+    redacted: true,
+  };
+}
+
+// ── Init ───────────────────────────────────────────────────────────────────────
+
+function initLocalPricing(cwd) {
+  const configPath = path.resolve(cwd, LOCAL_PRICING_CONFIG_REL);
+  if (fs.existsSync(configPath)) {
+    return { created: false, path: configPath, message: "Local pricing config already exists." };
+  }
+  const config = buildDefaultLocalPricingConfig();
+  ensureDirFor(configPath);
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2), "utf8");
+  return { created: true, path: configPath, message: "Local pricing config created with default entries." };
+}
+
+// ── Validate ───────────────────────────────────────────────────────────────────
+
+function validateLocalPricing(config) {
+  const errors = [];
+  if (!config) { errors.push("Config is null or undefined"); return { valid: false, errors }; }
+  if (config.contract !== CONTRACT) errors.push(`contract must be ${CONTRACT}`);
+  if (config.schemaVersion !== SCHEMA_VERSION) errors.push(`schemaVersion must be ${SCHEMA_VERSION}`);
+  if (!config.entries || !Array.isArray(config.entries)) errors.push("entries must be an array");
+  else {
+    config.entries.forEach((e, i) => {
+      if (!e.provider) errors.push(`entries[${i}].provider required`);
+      if (!e.model) errors.push(`entries[${i}].model required`);
+      if (!e.unit) errors.push(`entries[${i}].unit required`);
+      if (!e.confidence) errors.push(`entries[${i}].confidence required`);
+      if (!e.effectiveDate) errors.push(`entries[${i}].effectiveDate required`);
+      if (!e.caveat) errors.push(`entries[${i}].caveat required`);
+      if (e.source === "default_local" && e.confidence === "high")
+        errors.push(`entries[${i}]: default_local source cannot have confidence high`);
+    });
+  }
+  if (!config.source) errors.push("source required");
+  if (!config.effectiveDate) errors.push("effectiveDate required");
+  return { valid: errors.length === 0, errors };
+}
+
+// ── Read ───────────────────────────────────────────────────────────────────────
+
+function readLocalPricing(cwd) {
+  const configPath = path.resolve(cwd, LOCAL_PRICING_CONFIG_REL);
+  if (!fs.existsSync(configPath)) return null;
+  try {
+    const raw = fs.readFileSync(configPath, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+// ── Get pricing source for a provider/model ───────────────────────────────────
+
+function getLocalPricingEntry(cwd, provider, model) {
+  const config = readLocalPricing(cwd);
+  if (!config || !config.entries) return null;
+
+  const normalizedModel = (model || "").toLowerCase().replace(/[\s.]/g, "-");
+  const entry = config.entries.find((e) => {
+    const eModel = (e.model || "").toLowerCase().replace(/[\s.]/g, "-");
+    const eAlias = (e.modelAlias || "").toLowerCase().replace(/[\s.]/g, "-");
+    const eProvider = (e.provider || "").toLowerCase();
+    const matchProvider = !provider || eProvider === (provider || "").toLowerCase();
+    return matchProvider && (eModel === normalizedModel || eAlias === normalizedModel || normalizedModel.startsWith(eModel) || eModel.startsWith(normalizedModel));
+  });
+  return entry || null;
+}
+
+// ── Get pricing source summary ────────────────────────────────────────────────
+
+function getLocalPricingSource(cwd) {
+  const config = readLocalPricing(cwd);
+  if (!config) {
+    return {
+      available: false,
+      source: "unavailable",
+      entryCount: 0,
+      confidence: "unavailable",
+      effectiveDate: null,
+      caveat: "No local pricing config found. Run `avorelo pricing --init` to create one.",
+    };
+  }
+  const validation = validateLocalPricing(config);
+  if (!validation.valid) {
+    return {
+      available: false,
+      source: "invalid",
+      entryCount: 0,
+      confidence: "unavailable",
+      effectiveDate: null,
+      caveat: `Local pricing config is invalid: ${validation.errors.join("; ")}`,
+    };
+  }
+  return {
+    available: true,
+    source: config.source,
+    sourceName: config.sourceName,
+    entryCount: config.entries.length,
+    confidence: config.source === "default_local" ? "low" : "medium",
+    effectiveDate: config.effectiveDate,
+    caveat: config.source === "default_local"
+      ? "Default local pricing in use — confidence low. Verify against actual billing."
+      : `Local pricing from: ${config.sourceName || config.source}`,
+    pricingId: config.pricingId,
+  };
+}
+
+// ── Text format ────────────────────────────────────────────────────────────────
+
+function formatPricingText(cwd) {
+  const source = getLocalPricingSource(cwd);
+  if (!source.available) {
+    return [
+      "Avorelo Local Pricing",
+      "",
+      "  Status: unavailable",
+      `  ${source.caveat}`,
+      "",
+      "  To initialize: node bin/avorelo pricing --init",
+      "",
+    ].join("\n");
+  }
+  const config = readLocalPricing(cwd);
+  const lines = [
+    "Avorelo Local Pricing",
+    "",
+    `  Source:      ${source.source}`,
+    `  Confidence:  ${source.confidence}`,
+    `  Effective:   ${source.effectiveDate}`,
+    `  Entries:     ${source.entryCount}`,
+    `  Caveat:      ${source.caveat}`,
+    "",
+    "  Models:",
+  ];
+  (config.entries || []).forEach((e) => {
+    lines.push(`    ${e.provider}/${e.model}: input $${e.inputTokenPrice}/1M, output $${e.outputTokenPrice}/1M (${e.confidence})`);
+  });
+  lines.push("");
+  lines.push("  Note: Cost estimates use this config. Update entries to match your actual pricing.");
+  lines.push("");
+  return lines.join("\n");
+}
+
+module.exports = {
+  CONTRACT,
+  LOCAL_PRICING_CONFIG_REL,
+  buildDefaultLocalPricingConfig,
+  initLocalPricing,
+  validateLocalPricing,
+  readLocalPricing,
+  getLocalPricingEntry,
+  getLocalPricingSource,
+  formatPricingText,
+};

package/scripts/lib/mcp-enforcement.js

@@ -0,0 +1,311 @@
+"use strict";
+
+// ── MCP PreToolUse Enforcement ────────────────────────────────────────────────
+//
+// Contract: avorelo.mcpPreToolUseDecision.v1
+//
+// Governs MCP tool use at the PreToolUse hook boundary.
+// Does NOT execute tools. Does NOT leak raw input/output.
+// Always provides safeNextAction when blocking.
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { buildMcpToolInventory } = require("./mcp-tool-inventory");
+const { buildMcpToolRiskReport, REASON_CODES } = require("./mcp-tool-risk");
+const { buildMcpLeastPrivilegePolicy, DECISIONS } = require("./mcp-least-privilege-policy");
+
+const CONTRACT = "avorelo.mcpPreToolUseDecision.v1";
+const SCHEMA_VERSION = 1;
+
+const ENFORCEMENT_DIR_REL = ".claude/cco/orchestration/mcp-tool-governance";
+const DECISION_REL = `${ENFORCEMENT_DIR_REL}/latest-pretooluse-decision.json`;
+
+// MCP tool name prefixes that identify MCP calls
+const MCP_TOOL_PREFIXES = ["mcp__", "mcp_", "mcp:"];
+
+// Patterns suggesting a tool is destructive/deploy/prod at the call level
+const CALL_LEVEL_DESTRUCTIVE = [
+  /\b(delete|remove|drop|truncate|purge|wipe|destroy)\b/i,
+  /\brm\s+-rf\b/i,
+  /\b(deploy|publish|push.to.prod|ship.to.prod)\b/i,
+];
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function safeWriteJson(filePath, data) {
+  try {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+  } catch {
+    // non-fatal
+  }
+}
+
+function safeReadJson(absPath) {
+  try {
+    if (!fs.existsSync(absPath)) return null;
+    return JSON.parse(fs.readFileSync(absPath, "utf8").replace(/^/, ""));
+  } catch {
+    return null;
+  }
+}
+
+function makeDecisionId() {
+  return `mcp-dec-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 7)}`;
+}
+
+// ── Tool signal extraction ─────────────────────────────────────────────────────
+
+function extractToolUseSignal(input, options = {}) {
+  if (!input || typeof input !== "object") {
+    return { toolName: null, isMcpTool: false, serverName: null, actionSummary: null };
+  }
+
+  const toolName = String(input.tool_name || input.toolName || input.tool || "");
+  if (!toolName) {
+    return { toolName: null, isMcpTool: false, serverName: null, actionSummary: null };
+  }
+
+  const isMcpTool = MCP_TOOL_PREFIXES.some((prefix) => toolName.toLowerCase().startsWith(prefix));
+
+  // Extract server name from MCP tool naming convention: mcp__ServerName__toolName
+  let serverName = null;
+  if (isMcpTool) {
+    const parts = toolName.split(/__+/);
+    if (parts.length >= 3) {
+      serverName = parts[1];
+    } else if (parts.length === 2) {
+      serverName = parts[1];
+    }
+  }
+
+  // Summarize action without leaking raw input values (keys only)
+  const toolInput = input.tool_input || input.toolInput || input.input || {};
+  const inputKeys = Object.keys(toolInput || {}).slice(0, 8);
+  const actionSummary = inputKeys.length > 0
+    ? `tool: ${toolName}, input_keys: [${inputKeys.join(", ")}]`
+    : `tool: ${toolName}`;
+
+  return { toolName, isMcpTool, serverName, actionSummary };
+}
+
+// ── Policy lookup ─────────────────────────────────────────────────────────────
+
+function applyMcpPolicyToToolUse(cwd, signal, policy, options = {}) {
+  if (!signal || !signal.toolName) {
+    return {
+      decision: DECISIONS.ALLOW,
+      matchedPolicy: null,
+      reasonCodes: ["NO_TOOL_SIGNAL"],
+      safeNextAction: null,
+      taskStillExecutable: true,
+    };
+  }
+
+  if (!policy || !policy.decisions || policy.decisions.length === 0) {
+    // No policy = no inventory = no MCP servers configured
+    if (!signal.isMcpTool) {
+      return {
+        decision: DECISIONS.ALLOW,
+        matchedPolicy: null,
+        reasonCodes: ["NOT_AN_MCP_TOOL"],
+        safeNextAction: null,
+        taskStillExecutable: true,
+      };
+    }
+    // Unknown MCP tool with no policy → approval_required
+    return {
+      decision: DECISIONS.APPROVAL_REQUIRED,
+      matchedPolicy: null,
+      reasonCodes: [REASON_CODES.UNKNOWN_SERVER, "NO_POLICY_AVAILABLE"],
+      safeNextAction: "Run `avorelo mcp inventory` to discover and classify this tool before use.",
+      taskStillExecutable: true,
+    };
+  }
+
+  // Find matching policy by server name or tool name
+  const toolNameLower = signal.toolName.toLowerCase();
+  const serverNameLower = (signal.serverName || "").toLowerCase();
+
+  let matched = policy.decisions.find((d) => {
+    const dn = (d.name || "").toLowerCase();
+    const ds = (d.serverId || "").toLowerCase();
+    return dn === toolNameLower || ds.includes(serverNameLower) || toolNameLower.includes(dn);
+  });
+
+  if (!matched) {
+    // Unknown tool not in policy → approval_required
+    return {
+      decision: DECISIONS.APPROVAL_REQUIRED,
+      matchedPolicy: null,
+      reasonCodes: [REASON_CODES.UNKNOWN_SERVER, "TOOL_NOT_IN_POLICY"],
+      safeNextAction: "This tool was not found in the MCP inventory. Run `avorelo mcp inventory` and review before use.",
+      taskStillExecutable: true,
+    };
+  }
+
+  return {
+    decision: matched.decision,
+    matchedPolicy: {
+      toolId: matched.toolId,
+      name: matched.name,
+      riskLevel: matched.riskLevel,
+    },
+    reasonCodes: matched.reasonCodes || [],
+    safeNextAction: matched.safeNextAction || null,
+    taskStillExecutable: matched.taskStillExecutable !== false,
+  };
+}
+
+// ── Call-level safety check ───────────────────────────────────────────────────
+
+function checkCallLevelSafety(signal) {
+  if (!signal || !signal.toolName) return null;
+  const toolText = signal.toolName + " " + (signal.actionSummary || "");
+  for (const pattern of CALL_LEVEL_DESTRUCTIVE) {
+    if (pattern.test(toolText)) {
+      return {
+        decision: DECISIONS.BLOCK,
+        reasonCodes: [REASON_CODES.DESTRUCTIVE_ACTION, "CALL_LEVEL_DESTRUCTIVE_PATTERN"],
+        safeNextAction: "This tool call matches a destructive/deploy pattern. Use a scoped safe tool or get explicit approval.",
+        taskStillExecutable: false,
+      };
+    }
+  }
+  return null;
+}
+
+// ── Main decision function ────────────────────────────────────────────────────
+
+function decideMcpPreToolUse(cwd, input, options = {}) {
+  const decisionId = makeDecisionId();
+  const signal = extractToolUseSignal(input, options);
+
+  const baseDecision = {
+    contract: CONTRACT,
+    schemaVersion: SCHEMA_VERSION,
+    decisionId,
+    createdAt: nowIso(),
+    decision: DECISIONS.ALLOW,
+    toolSignal: {
+      toolName: signal.toolName,
+      isMcpTool: signal.isMcpTool,
+      serverName: signal.serverName,
+      actionSummary: signal.actionSummary,
+    },
+    matchedPolicy: null,
+    reasonCodes: [],
+    safeNextAction: null,
+    taskStillExecutable: true,
+    evidenceRefs: [],
+    redacted: true,
+  };
+
+  // If no tool signal, allow (don't block non-MCP tools)
+  if (!signal.toolName) {
+    baseDecision.decision = DECISIONS.ALLOW;
+    baseDecision.reasonCodes = ["NO_TOOL_SIGNAL"];
+    return baseDecision;
+  }
+
+  // Non-MCP tool: check call-level safety, then allow
+  if (!signal.isMcpTool) {
+    const callCheck = checkCallLevelSafety(signal);
+    if (callCheck) {
+      return { ...baseDecision, ...callCheck };
+    }
+    baseDecision.decision = DECISIONS.ALLOW;
+    baseDecision.reasonCodes = ["NOT_AN_MCP_TOOL"];
+    return baseDecision;
+  }
+
+  // MCP tool: call-level safety check first
+  const callCheck = checkCallLevelSafety(signal);
+  if (callCheck) {
+    return { ...baseDecision, ...callCheck };
+  }
+
+  // Load existing policy (if available)
+  let policy = null;
+  try {
+    const policyPath = path.join(cwd, ".claude/cco/orchestration/mcp-tool-governance/latest-policy.json");
+    policy = safeReadJson(policyPath);
+  } catch {
+    // non-fatal — will build fresh
+  }
+
+  // If no cached policy, build one now
+  if (!policy) {
+    try {
+      const inventory = buildMcpToolInventory(cwd, options);
+      const riskReport = buildMcpToolRiskReport(cwd, inventory, options);
+      policy = buildMcpLeastPrivilegePolicy(cwd, riskReport, options);
+    } catch {
+      // If we can't build policy, be conservative
+      const result = { ...baseDecision };
+      result.decision = DECISIONS.APPROVAL_REQUIRED;
+      result.reasonCodes = [REASON_CODES.UNKNOWN_SERVER, "POLICY_BUILD_FAILED"];
+      result.safeNextAction = "Cannot evaluate MCP tool risk. Run `avorelo mcp inventory` before proceeding.";
+      result.taskStillExecutable = true;
+      return result;
+    }
+  }
+
+  const policyResult = applyMcpPolicyToToolUse(cwd, signal, policy, options);
+  const result = {
+    ...baseDecision,
+    decision: policyResult.decision,
+    matchedPolicy: policyResult.matchedPolicy,
+    reasonCodes: policyResult.reasonCodes,
+    safeNextAction: policyResult.safeNextAction,
+    taskStillExecutable: policyResult.taskStillExecutable !== false,
+    evidenceRefs: [".claude/cco/orchestration/mcp-tool-governance/latest-policy.json"],
+  };
+
+  // Blocked decisions MUST have safeNextAction
+  if (result.decision === DECISIONS.BLOCK && !result.safeNextAction) {
+    result.safeNextAction = "This MCP tool is blocked. Use a scoped alternative or get explicit operator approval.";
+  }
+
+  return result;
+}
+
+// ── Write decision ────────────────────────────────────────────────────────────
+
+function writeMcpPreToolUseDecision(cwd, decision) {
+  const absPath = path.join(cwd, DECISION_REL);
+  safeWriteJson(absPath, decision);
+  return DECISION_REL;
+}
+
+function formatMcpPreToolUseText(decision, options = {}) {
+  const d = decision.decision || "unknown";
+  const tool = decision.toolSignal?.toolName || "unknown";
+  const lines = [
+    `MCP PreToolUse: ${tool} → ${d.toUpperCase()}`,
+  ];
+  if (decision.reasonCodes && decision.reasonCodes.length > 0) {
+    lines.push(`Reason: ${decision.reasonCodes.slice(0, 4).join(", ")}`);
+  }
+  if (decision.safeNextAction) {
+    lines.push(`Next: ${decision.safeNextAction}`);
+  }
+  return lines.join("\n");
+}
+
+// ── Exports ───────────────────────────────────────────────────────────────────
+
+module.exports = {
+  CONTRACT,
+  SCHEMA_VERSION,
+  DECISION_REL,
+  decideMcpPreToolUse,
+  extractToolUseSignal,
+  applyMcpPolicyToToolUse,
+  writeMcpPreToolUseDecision,
+  formatMcpPreToolUseText,
+};