cedar-mcp-server 1.0.0

package/src/tools/diff-stores.ts

@@ -0,0 +1,298 @@
+import { isAuthorized } from "@cedar-policy/cedar-wasm/nodejs";
+import type { StoreManager } from "../resources/store-manager.js";
+import { handleCheckChange } from "./check-change.js";
+import { handleDiffSchema, type SchemaDiff } from "./diff-schema.js";
+import { normalizePrincipalRef } from "../utils/format-detector.js";
+import type { Entities } from "@cedar-policy/cedar-wasm/nodejs";
+
+export interface DiffStoresInput {
+  blue: string;
+  green: string;
+  behavioral_test_requests?: string;
+}
+
+export interface PolicyChangeInfo {
+  policy_id: string;
+  can_update_in_place: boolean;
+  changes: Array<{ field: string; in_place_allowed: boolean; reason: string }>;
+  recommendation: string;
+}
+
+export interface BehavioralDriftEntry {
+  principal: string;
+  action: string;
+  resource: string;
+  blue_decision: "Allow" | "Deny" | "Error";
+  green_decision: "Allow" | "Deny" | "Error";
+  drifted: boolean;
+  error?: string;
+}
+
+export interface DiffStoresResult {
+  blue: string;
+  green: string;
+  policies_added: Array<{ policy_id: string; content: string }>;
+  policies_removed: Array<{ policy_id: string; content: string }>;
+  policies_modified: PolicyChangeInfo[];
+  schema_diff: SchemaDiff;
+  behavioral_diff?: BehavioralDriftEntry[];
+  summary: string;
+  error?: string;
+}
+
+export async function handleDiffStores(
+  input: DiffStoresInput,
+  manager: StoreManager
+): Promise<DiffStoresResult> {
+  // Validate stores exist
+  try {
+    manager.requireStore(input.blue);
+  } catch (e) {
+    return errorResult(input.blue, input.green, e instanceof Error ? e.message : String(e));
+  }
+  try {
+    manager.requireStore(input.green);
+  } catch (e) {
+    return errorResult(input.blue, input.green, e instanceof Error ? e.message : String(e));
+  }
+
+  const bluePolicies = new Map<string, string>();
+  const greenPolicies = new Map<string, string>();
+
+  for (const id of manager.listPolicies(input.blue)) {
+    bluePolicies.set(id, manager.readPolicy(input.blue, id));
+  }
+  for (const id of manager.listPolicies(input.green)) {
+    greenPolicies.set(id, manager.readPolicy(input.green, id));
+  }
+
+  // Structural diff
+  const policies_added: DiffStoresResult["policies_added"] = [];
+  const policies_removed: DiffStoresResult["policies_removed"] = [];
+  const policies_modified: PolicyChangeInfo[] = [];
+
+  for (const [id, content] of greenPolicies) {
+    if (!bluePolicies.has(id)) {
+      policies_added.push({ policy_id: id, content });
+    }
+  }
+
+  for (const [id, content] of bluePolicies) {
+    if (!greenPolicies.has(id)) {
+      policies_removed.push({ policy_id: id, content });
+    } else {
+      const blueContent = content;
+      const greenContent = greenPolicies.get(id)!;
+      if (blueContent.trim() !== greenContent.trim()) {
+        // Reuse check-change logic for AVP immutability classification
+        const changeResult = await handleCheckChange({
+          old_policy: blueContent,
+          new_policy: greenContent,
+        });
+        if (changeResult.error) {
+          // Parse error on one or both sides — report as modified with error context
+          policies_modified.push({
+            policy_id: id,
+            can_update_in_place: false,
+            changes: [],
+            recommendation: `Could not diff policy "${id}": ${changeResult.error}`,
+          });
+        } else if (changeResult.changes.length > 0) {
+          policies_modified.push({
+            policy_id: id,
+            can_update_in_place: changeResult.can_update_in_place,
+            changes: changeResult.changes.map((c) => ({
+              field: c.field,
+              in_place_allowed: c.in_place_allowed,
+              reason: c.reason,
+            })),
+            recommendation: changeResult.recommendation,
+          });
+        }
+        // If changes.length === 0 and no error: policies differ in text but not semantically
+        // (formatting change). Treat as unchanged — no entry in policies_modified.
+      }
+    }
+  }
+
+  // Schema diff — structured via handleDiffSchema
+  let schema_diff: SchemaDiff;
+  try {
+    const blueSchema = manager.readSchema(input.blue);
+    const greenSchema = manager.readSchema(input.green);
+    schema_diff = await handleDiffSchema({ blue: blueSchema, green: greenSchema });
+  } catch (e) {
+    schema_diff = emptySchemaDiff(`Schema comparison failed: ${e instanceof Error ? e.message : String(e)}`);
+  }
+
+  // Behavioral diff (optional)
+  let behavioral_diff: BehavioralDriftEntry[] | undefined;
+  if (input.behavioral_test_requests) {
+    behavioral_diff = await runBehavioralDiff(
+      input.blue,
+      input.green,
+      input.behavioral_test_requests,
+      manager
+    );
+  }
+
+  // Summary
+  const totalChanges =
+    policies_added.length + policies_removed.length + policies_modified.length;
+  const requiresRecreate = policies_modified.filter((p) => !p.can_update_in_place).length;
+  const driftCount = behavioral_diff?.filter((d) => d.drifted).length ?? 0;
+  const schema_changed = hasSchemaChanges(schema_diff);
+  const schemaBreaking = schema_diff.risk_level === "breaking";
+
+  let summary: string;
+  if (totalChanges === 0 && !schema_changed) {
+    summary = "No changes detected between blue and green stores.";
+  } else {
+    const parts: string[] = [];
+    if (policies_added.length) parts.push(`${policies_added.length} added`);
+    if (policies_removed.length) parts.push(`${policies_removed.length} removed`);
+    if (policies_modified.length) {
+      parts.push(`${policies_modified.length} modified`);
+      if (requiresRecreate) parts.push(`(${requiresRecreate} require delete-recreate in AVP)`);
+    }
+    if (schema_changed) {
+      parts.push(schemaBreaking ? "schema changed (BREAKING)" : "schema changed");
+    }
+    if (driftCount) parts.push(`${driftCount} authorization decision(s) would change`);
+    summary = `Policy diff: ${parts.join(", ")}.`;
+  }
+
+  return {
+    blue: input.blue,
+    green: input.green,
+    policies_added,
+    policies_removed,
+    policies_modified,
+    schema_diff,
+    ...(behavioral_diff !== undefined ? { behavioral_diff } : {}),
+    summary,
+  };
+}
+
+function hasSchemaChanges(d: SchemaDiff): boolean {
+  return (
+    d.namespaces_added.length > 0 ||
+    d.namespaces_removed.length > 0 ||
+    d.entity_types.added.length > 0 ||
+    d.entity_types.removed.length > 0 ||
+    d.entity_types.modified.length > 0 ||
+    d.actions.added.length > 0 ||
+    d.actions.removed.length > 0 ||
+    d.actions.modified.length > 0 ||
+    d.common_types.added.length > 0 ||
+    d.common_types.removed.length > 0 ||
+    d.common_types.modified.length > 0
+  );
+}
+
+function emptySchemaDiff(error?: string): SchemaDiff {
+  return {
+    namespaces_added: [],
+    namespaces_removed: [],
+    entity_types: { added: [], removed: [], modified: [] },
+    actions: { added: [], removed: [], modified: [] },
+    common_types: { added: [], removed: [], modified: [] },
+    summary: "",
+    risk_level: "safe",
+    ...(error ? { error } : {}),
+  };
+}
+
+async function runBehavioralDiff(
+  blue: string,
+  green: string,
+  requestsJson: string,
+  manager: StoreManager
+): Promise<BehavioralDriftEntry[]> {
+  let requests: Array<{
+    principal: string | object;
+    action: string | object;
+    resource: string | object;
+    entities: string;
+    context?: string;
+  }>;
+  try {
+    requests = JSON.parse(requestsJson);
+    if (!Array.isArray(requests)) return [{ principal: "", action: "", resource: "", blue_decision: "Deny", green_decision: "Deny", drifted: false }];
+  } catch {
+    return [];
+  }
+
+  const bluePolicies = manager.readAllPolicies(blue);
+  const greenPolicies = manager.readAllPolicies(green);
+
+  const entries: BehavioralDriftEntry[] = [];
+
+  for (const req of requests) {
+    const principalRef = normalizePrincipalRef(req.principal);
+    const actionRef = normalizePrincipalRef(req.action);
+    const resourceRef = normalizePrincipalRef(req.resource);
+
+    const refError =
+      ("error" in principalRef ? principalRef.error : null) ??
+      ("error" in actionRef ? actionRef.error : null) ??
+      ("error" in resourceRef ? resourceRef.error : null);
+
+    const principalStr = typeof req.principal === "string" ? req.principal : JSON.stringify(req.principal);
+    const actionStr = typeof req.action === "string" ? req.action : JSON.stringify(req.action);
+    const resourceStr = typeof req.resource === "string" ? req.resource : JSON.stringify(req.resource);
+
+    if (refError) {
+      entries.push({ principal: principalStr, action: actionStr, resource: resourceStr, blue_decision: "Error", green_decision: "Error", drifted: false, error: refError });
+      continue;
+    }
+
+    let entities: Entities;
+    try {
+      entities = JSON.parse(req.entities);
+    } catch {
+      entries.push({ principal: principalStr, action: actionStr, resource: resourceStr, blue_decision: "Error", green_decision: "Error", drifted: false, error: "Invalid entities JSON" });
+      continue;
+    }
+
+    // After the refError guard above, refs are guaranteed to be NormalizedRef (no error field)
+    const safeP = principalRef as { type: string; id: string };
+    const safeA = actionRef as { type: string; id: string };
+    const safeR = resourceRef as { type: string; id: string };
+    const context = {};
+    const callBase = { principal: safeP, action: safeA, resource: safeR, context, entities };
+
+    const blueAnswer = isAuthorized({ ...callBase, policies: { staticPolicies: bluePolicies } });
+    const greenAnswer = isAuthorized({ ...callBase, policies: { staticPolicies: greenPolicies } });
+
+    const blueDecision: "Allow" | "Deny" =
+      blueAnswer.type === "success" && blueAnswer.response.decision === "allow" ? "Allow" : "Deny";
+    const greenDecision: "Allow" | "Deny" =
+      greenAnswer.type === "success" && greenAnswer.response.decision === "allow" ? "Allow" : "Deny";
+
+    entries.push({
+      principal: principalStr,
+      action: actionStr,
+      resource: resourceStr,
+      blue_decision: blueDecision,
+      green_decision: greenDecision,
+      drifted: blueDecision !== greenDecision,
+    });
+  }
+
+  return entries;
+}
+
+function errorResult(blue: string, green: string, error: string): DiffStoresResult {
+  return {
+    blue,
+    green,
+    policies_added: [],
+    policies_removed: [],
+    policies_modified: [],
+    schema_diff: emptySchemaDiff(),
+    summary: "",
+    error,
+  };
+}
+

package/src/tools/explain.ts

@@ -0,0 +1,278 @@
+import { policyToJson, templateToJson, policySetTextToParts } from "@cedar-policy/cedar-wasm/nodejs";
+import {
+  describePrincipal,
+  describeAction,
+  describeResource,
+  describeCondition,
+  detectPatterns,
+} from "../parser/policy-ast.js";
+import type { PolicyJson } from "@cedar-policy/cedar-wasm/nodejs";
+import { storeManager } from "../resources/store-manager.js";
+
+export interface ExplainInput {
+  policy: string;
+  schema?: string;
+}
+
+export interface ScopeDescription {
+  scope: string;
+  description: string;
+}
+
+export interface ConditionDescription {
+  kind: "when" | "unless";
+  text: string;
+}
+
+export interface ExplainResult {
+  effect: "permit" | "forbid";
+  principal: ScopeDescription;
+  action: ScopeDescription;
+  resource: ScopeDescription;
+  conditions: ConditionDescription[];
+  summary: string;
+  patterns_detected: string[];
+  error?: string;
+  /**
+   * 10d workspace auto-discovery: populated by the server.ts MCP handler when
+   * the schema was resolved from a loaded MCP root rather than supplied inline.
+   * On ExplainManyResult the field appears on the top-level result so a single
+   * auto-discovery decision applies to the whole policy set.
+   */
+  auto_discovered?: {
+    schema_from?: string;
+  };
+}
+
+function parsePolicyJson(policyText: string): PolicyJson {
+  const result = policyToJson(policyText);
+  if (result.type === "success") return result.json;
+
+  const errors = result.errors.map((e) => e.message).join("; ");
+
+  // Fall back to templateToJson if the error is about template slots
+  if (errors.includes("template") || errors.includes("slot")) {
+    const templateResult = templateToJson(policyText);
+    if (templateResult.type === "success") return templateResult.json as unknown as PolicyJson;
+    throw new Error(templateResult.errors.map((e) => e.message).join("; "));
+  }
+
+  throw new Error(errors);
+}
+
+function buildSummary(
+  json: PolicyJson,
+  principalDesc: string,
+  actionDesc: string,
+  resourceDesc: string,
+  conditions: ConditionDescription[],
+  isTemplate: boolean
+): string {
+  const effect = json.effect === "permit" ? "PERMITS" : "FORBIDS";
+  const base = `${effect} ${principalDesc} to perform ${actionDesc} on ${resourceDesc}`;
+
+  if (isTemplate) {
+    const slots = [
+      json.principal.op === "==" && "slot" in json.principal ? `?principal` : null,
+      json.resource.op === "==" && "slot" in json.resource ? `?resource` : null,
+    ].filter(Boolean);
+    return `TEMPLATE POLICY: ${base}. Template slots: ${slots.join(", ")}.`;
+  }
+
+  if (conditions.length === 0) return `${base}.`;
+
+  const whenClauses = conditions
+    .filter((c) => c.kind === "when")
+    .map((c) => c.text.replace(/^WHEN /, ""));
+  const unlessClauses = conditions
+    .filter((c) => c.kind === "unless")
+    .map((c) => c.text.replace(/^UNLESS /, ""));
+
+  let summary = base;
+  if (whenClauses.length > 0) summary += `, when: ${whenClauses.join("; ")}`;
+  if (unlessClauses.length > 0) summary += `, unless: ${unlessClauses.join("; ")}`;
+  return summary + ".";
+}
+
+export async function handleExplain(input: ExplainInput): Promise<ExplainResult> {
+  let json: PolicyJson;
+  let isTemplate = false;
+
+  try {
+    const raw = policyToJson(input.policy);
+    if (raw.type === "failure") {
+      const errors = raw.errors.map((e) => e.message).join("; ");
+      if (errors.includes("template") || errors.includes("slot")) {
+        const templateResult = templateToJson(input.policy);
+        if (templateResult.type === "failure") {
+          return {
+            effect: "permit",
+            principal: { scope: "unknown", description: "unknown" },
+            action: { scope: "unknown", description: "unknown" },
+            resource: { scope: "unknown", description: "unknown" },
+            conditions: [],
+            summary: "Failed to parse policy.",
+            patterns_detected: [],
+            error: templateResult.errors.map((e) => e.message).join("; "),
+          };
+        }
+        json = templateResult.json as unknown as PolicyJson;
+        isTemplate = true;
+      } else {
+        return {
+          effect: "permit",
+          principal: { scope: "unknown", description: "unknown" },
+          action: { scope: "unknown", description: "unknown" },
+          resource: { scope: "unknown", description: "unknown" },
+          conditions: [],
+          summary: "Failed to parse policy.",
+          patterns_detected: [],
+          error: errors,
+        };
+      }
+    } else {
+      json = raw.json;
+    }
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    return {
+      effect: "permit",
+      principal: { scope: "unknown", description: "unknown" },
+      action: { scope: "unknown", description: "unknown" },
+      resource: { scope: "unknown", description: "unknown" },
+      conditions: [],
+      summary: "Failed to parse policy.",
+      patterns_detected: [],
+      error: msg,
+    };
+  }
+
+  const principalDesc = describePrincipal(json.principal);
+  const actionDesc = describeAction(json.action);
+  const resourceDesc = describeResource(json.resource);
+
+  const conditions: ConditionDescription[] = json.conditions.map((c) => ({
+    kind: c.kind,
+    text: describeCondition(c),
+  }));
+
+  const patterns = detectPatterns(json);
+  if (isTemplate && !patterns.includes("template_policy")) patterns.unshift("template_policy");
+
+  const summary = buildSummary(json, principalDesc, actionDesc, resourceDesc, conditions, isTemplate);
+
+  return {
+    effect: json.effect,
+    principal: { scope: json.principal.op, description: principalDesc },
+    action: { scope: json.action.op, description: actionDesc },
+    resource: { scope: json.resource.op, description: resourceDesc },
+    conditions,
+    summary,
+    patterns_detected: patterns,
+  };
+}
+
+// ─── Multi-policy entry point ──────────────────────────────────────────────────
+
+export interface ExplainManyResult {
+  policy_count: number;
+  policies: Array<ExplainResult & { index: number }>;
+  /**
+   * 10d workspace auto-discovery: see ExplainResult.auto_discovered. On the
+   * many-result the field lives at the top level so the auto-discovered schema
+   * is reported once rather than duplicated on every policy entry.
+   */
+  auto_discovered?: {
+    schema_from?: string;
+  };
+}
+
+/**
+ * Explains a Cedar policy set (one or more policies).
+ * Uses policySetTextToParts to split, then explains each individually.
+ * Falls back to single-policy handling when there is exactly one policy.
+ */
+export async function handleExplainMany(input: ExplainInput): Promise<ExplainManyResult | ExplainResult> {
+  const parts = policySetTextToParts(input.policy);
+
+  // Single policy or unparseable — fall through to single-policy handler
+  if (parts.type === "failure" || (parts.policies.length + parts.policy_templates.length) <= 1) {
+    return handleExplain(input);
+  }
+
+  const allPolicies = [...parts.policies, ...parts.policy_templates];
+  const results = await Promise.all(
+    allPolicies.map(async (policyText, i) => {
+      const result = await handleExplain({ policy: policyText, schema: input.schema });
+      return { ...result, index: i };
+    })
+  );
+
+  return {
+    policy_count: allPolicies.length,
+    policies: results,
+  };
+}
+
+// ─── 10d workspace auto-discovery wrapper ────────────────────────────────────
+
+/**
+ * Inputs accepted by the MCP-level explain entry point. Wider than
+ * `ExplainInput` because it also accepts the `_ref` shape the MCP layer
+ * resolves before reaching `handleExplainMany`.
+ */
+export interface ExplainMcpInput {
+  policy: string;
+  schema?: string;
+  schema_ref?: string;
+  store?: string;
+}
+
+/**
+ * 10d workspace auto-discovery wrapper for `cedar_explain`. Resolves the
+ * schema from a loaded MCP root when neither `schema` nor `schema_ref` was
+ * supplied. The schema is optional for explain, so single-store deployments
+ * with no schema file just delegate to the parser without one. Multi-store
+ * deployments with no explicit `store` parameter return an ambiguity error.
+ */
+export async function handleExplainMcp(
+  input: ExplainMcpInput,
+  resolveRef: (uri: string) => { content: string } | { error: string },
+): Promise<{ result: ExplainResult | ExplainManyResult } | { error: string }> {
+  let schema = input.schema;
+  if (!schema && input.schema_ref) {
+    const resolved = resolveRef(input.schema_ref);
+    if ("error" in resolved) return { error: resolved.error };
+    schema = resolved.content;
+  }
+
+  let autoSchemaFrom: string | undefined;
+  if (!schema && !input.schema_ref) {
+    if (input.store) {
+      try {
+        schema = storeManager.readSchema(input.store);
+        autoSchemaFrom = input.store;
+      } catch (e) {
+        return { error: e instanceof Error ? e.message : String(e) };
+      }
+    } else {
+      const def = storeManager.getDefaultStore();
+      if (def.kind === "single") {
+        try {
+          schema = storeManager.readSchema(def.store.name);
+          autoSchemaFrom = def.store.name;
+        } catch {
+          // Store has no schema file; explain runs without a schema.
+        }
+      } else if (def.kind === "ambiguous") {
+        return { error: `Multiple stores are loaded (${def.names.join(", ")}). Pass store: "<name>" to choose.` };
+      }
+    }
+  }
+
+  const result = await handleExplainMany({ policy: input.policy, schema });
+  if (autoSchemaFrom) {
+    result.auto_discovered = { schema_from: autoSchemaFrom };
+  }
+  return { result };
+}

package/src/tools/format.ts

@@ -0,0 +1,33 @@
+import { formatPolicies } from "@cedar-policy/cedar-wasm/nodejs";
+
+export interface FormatInput {
+  policies: string;
+  line_width?: number;
+  indent_width?: number;
+}
+
+export interface FormatResult {
+  formatted: string | null;
+  error: string | null;
+}
+
+export async function handleFormat(input: FormatInput): Promise<FormatResult> {
+  // per spike-report-wasm-api.md §3: formatPolicies takes FormattingCall object, not raw string
+  const answer = formatPolicies({
+    policyText: input.policies,
+    ...(input.line_width !== undefined ? { lineWidth: input.line_width } : {}),
+    ...(input.indent_width !== undefined ? { indentWidth: input.indent_width } : {}),
+  });
+
+  if (answer.type === "failure") {
+    return {
+      formatted: null,
+      error: answer.errors.map((e) => e.message).join("; "),
+    };
+  }
+
+  return {
+    formatted: answer.formatted_policy,
+    error: null,
+  };
+}