cedar-mcp-server 1.0.0

package/src/tools/advise/avp-rules.ts

@@ -0,0 +1,70 @@
+/**
+ * AVP UpdatePolicy mutability rules — proven from official docs 2026-05-20:
+ * https://docs.aws.amazon.com/verifiedpermissions/latest/apireference/API_UpdatePolicy.html
+ *
+ * UpdatePolicy only updates STATIC policies. Template-linked → use UpdatePolicyTemplate.
+ */
+
+export type AvpUpdateMode = "in_place_via_update_policy" | "requires_delete_recreate" | "new_policy_via_create_policy";
+
+export interface AvpChangeClassification {
+  mode: AvpUpdateMode;
+  rationale: string;
+}
+
+/** Classify which AVP API call a given change type requires. */
+export function classifyAvpChange(changeField: string): AvpChangeClassification {
+  switch (changeField) {
+    case "action":
+    case "when_clause":
+    case "unless_clause":
+    case "policy_name":
+      return {
+        mode: "in_place_via_update_policy",
+        rationale: "AVP UpdatePolicy supports modifying actions, when/unless clauses, and policy name in-place.",
+      };
+    case "effect":
+    case "principal":
+    case "resource":
+    case "policy_type_conversion":
+      return {
+        mode: "requires_delete_recreate",
+        rationale: "AVP UpdatePolicy cannot change effect, principal scope, resource scope, or convert between static and template-linked policies. Delete the existing policy and create a new one.",
+      };
+    case "new_policy":
+      return {
+        mode: "new_policy_via_create_policy",
+        rationale: "New policy — use AVP CreatePolicy API.",
+      };
+    default:
+      return {
+        mode: "in_place_via_update_policy",
+        rationale: "Change type unclassified — assume in-place update is possible but verify.",
+      };
+  }
+}
+
+/** Validation error categories AVP raises — pre-detectable during authoring. */
+export const AVP_VALIDATION_ERRORS = [
+  { id: "UnrecognizedEntityType", description: "Policy references an entity type not declared in the schema." },
+  { id: "UnrecognizedActionId", description: "Policy references an action not declared in the schema." },
+  { id: "InvalidActionApplication", description: "Action does not apply to the specified principal and resource types per the schema appliesTo definition." },
+  { id: "UnexpectedType", description: "An operand has the wrong type for the operation (e.g. comparing a String to an entity)." },
+  { id: "IncompatibleTypes", description: "Types in a Set or if/then/else expression are incompatible." },
+  { id: "MissingAttribute", description: "Policy accesses an attribute not declared in the schema. Add the attribute to the schema or use a has guard." },
+  { id: "UnsafeOptionalAttributeAccess", description: "Policy accesses an optional attribute without a has guard. This causes Cedar to silently skip the policy for principals/resources missing the attribute." },
+  { id: "ImpossiblePolicy", description: "Cedar determined the condition always evaluates to false — the policy can never match any request." },
+  { id: "WrongNumberArguments", description: "Extension type function called with wrong number of arguments." },
+  { id: "FunctionArgumentValidationError", description: "Argument to an extension type function could not be parsed (e.g. invalid IP address string)." },
+] as const;
+
+export type AvpValidationErrorId = typeof AVP_VALIDATION_ERRORS[number]["id"];
+
+/** AVP immutability rules summary — for use in sampling prompts. */
+export const AVP_RULES_SUMMARY = `
+AVP UpdatePolicy constraints (verified from official API docs):
+MUTABLE via UpdatePolicy: action scope, when/unless conditions, policy name.
+IMMUTABLE (delete+recreate required): effect (permit↔forbid), principal scope, resource scope, static↔template-linked conversion.
+NEW policies: use CreatePolicy API.
+Template-linked policies: use UpdatePolicyTemplate, not UpdatePolicy.
+`.trim();

package/src/tools/advise/cedar-patterns.ts

@@ -0,0 +1,73 @@
+/**
+ * Cedar design pattern definitions and classifier.
+ * Patterns proven from official docs 2026-05-20:
+ * https://docs.cedarpolicy.com/overview/patterns.html
+ */
+
+import type { PolicyJson } from "@cedar-policy/cedar-wasm/nodejs";
+
+export type CedarPattern = "membership" | "relationship" | "discretionary" | "hybrid" | "unknown";
+
+export interface PatternClassification {
+  pattern: CedarPattern;
+  confidence: "high" | "medium" | "low";
+  evidence: string;
+}
+
+/**
+ * Classify a single policy's primary Cedar pattern from its policyToJson AST.
+ *
+ * Membership (RBAC):  principal in Role::"X"  — scope uses "in" with a non-resource entity
+ * Relationship (ReBAC): principal in resource.attr — condition body has "in" with resource attribute
+ * Discretionary: principal == Service::"specific"  — scope uses "==" (specific entity)
+ * Hybrid: combination of the above
+ */
+export function classifyPolicy(json: PolicyJson): PatternClassification {
+  const principalOp = json.principal.op;
+  const conditionsText = JSON.stringify(json.conditions);
+
+  // Relationship: condition body contains "principal in resource" — ReBAC
+  const hasReBAC = conditionsText.includes('"in"') &&
+    conditionsText.includes('"Var":"principal"') &&
+    conditionsText.includes('"Var":"resource"');
+
+  // Membership: principal scope is "in" (role/group membership, not via condition)
+  const isMembership = principalOp === "in" && !hasReBAC;
+
+  // Discretionary: principal scope is "==" (specific entity)
+  const isDiscretionary = principalOp === "==";
+
+  if (hasReBAC && isMembership) {
+    return { pattern: "hybrid", confidence: "medium", evidence: "principal scope uses 'in' (Membership) and conditions use principal-in-resource pattern (Relationship)" };
+  }
+  if (hasReBAC) {
+    return { pattern: "relationship", confidence: "high", evidence: "condition body contains principal-in-resource relationship check" };
+  }
+  if (isMembership) {
+    return { pattern: "membership", confidence: "high", evidence: `principal scope uses 'in' — group/role membership (RBAC)` };
+  }
+  if (isDiscretionary) {
+    return { pattern: "discretionary", confidence: "high", evidence: `principal scope uses '==' — specific entity grant (Discretionary)` };
+  }
+  if (principalOp === "All") {
+    return { pattern: "unknown", confidence: "low", evidence: "principal is unconstrained in scope — pattern determined entirely by conditions" };
+  }
+
+  return { pattern: "unknown", confidence: "low", evidence: `principal op '${principalOp}' not recognized` };
+}
+
+/** Cedar patterns summary — for use in sampling prompts. */
+export const CEDAR_PATTERNS_SUMMARY = `
+Cedar supports three primary design patterns (official docs):
+
+1. MEMBERSHIP (RBAC): principal in Role::"group" — permissions follow group membership.
+   Example: permit(principal in Role::"editor", action in [...], resource);
+
+2. RELATIONSHIP (ReBAC): principal in resource.owners — permissions follow resource relationships.
+   Example: permit(principal is User, action in [...], resource is Doc) when { principal in resource.owners };
+
+3. DISCRETIONARY: principal == Service::"specific" — ad-hoc per-entity grants.
+   Example: permit(principal == Service::"Service-123", action == Action::"call", resource == Service::"Target");
+
+All three can coexist in a policy store. Individual policies should follow one pattern.
+`.trim();

package/src/tools/advise/context-builder.ts

@@ -0,0 +1,109 @@
+/**
+ * Builds deterministic context from a policy store for cedar_advise sampling prompts.
+ * No LLM cost — pure AST walking and schema parsing.
+ */
+
+import { policyToJson, policySetTextToParts } from "@cedar-policy/cedar-wasm/nodejs";
+import { storeManager, StoreManager } from "../../resources/store-manager.js";
+import { classifyPolicy } from "./cedar-patterns.js";
+
+export interface PolicyInventoryEntry {
+  policy_id: string;
+  pattern: string;
+  pattern_confidence: string;
+  summary: string;
+  policy_text: string;
+}
+
+export interface StoreContext {
+  store_name: string;
+  schema_text: string;
+  policy_inventory: PolicyInventoryEntry[];
+  policy_count: number;
+}
+
+/**
+ * Build structured context from a named policy store.
+ * Returns null if the store doesn't exist or has no content.
+ */
+export function buildStoreContext(storeName: string, manager: StoreManager = storeManager): StoreContext | null {
+  try {
+    const schema = manager.readSchema(storeName);
+    const inventory: PolicyInventoryEntry[] = [];
+    const policyIds = manager.listPolicies(storeName);
+
+    for (const id of policyIds) {
+      const content = manager.readPolicy(storeName, id);
+      try {
+        const parseResult = policyToJson(content.trim());
+        if (parseResult.type === "success") {
+          const classification = classifyPolicy(parseResult.json);
+          inventory.push({
+            policy_id: id,
+            pattern: classification.pattern,
+            pattern_confidence: classification.confidence,
+            summary: buildPolicySummary(id, parseResult.json.effect, classification.evidence),
+            policy_text: content.trim(),
+          });
+        } else {
+          inventory.push({
+            policy_id: id,
+            pattern: "unknown",
+            pattern_confidence: "low",
+            summary: `${id}: parse failed — ${parseResult.errors[0]?.message ?? "unknown error"}`,
+            policy_text: content.trim(),
+          });
+        }
+      } catch {
+        inventory.push({
+          policy_id: id,
+          pattern: "unknown",
+          pattern_confidence: "low",
+          summary: `${id}: could not analyze`,
+          policy_text: content.trim(),
+        });
+      }
+    }
+
+    return {
+      store_name: storeName,
+      schema_text: schema,
+      policy_inventory: inventory,
+      policy_count: policyIds.length,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** Resolve a store_ref to a store name. Accepts "mystore", "cedar://policies/mystore", etc. */
+export function resolveStoreRef(storeRef: string): string {
+  if (storeRef.startsWith("cedar://")) {
+    const match = storeRef.match(/cedar:\/\/(?:policies|schema)\/([^/]+)/);
+    return match?.[1] ?? storeRef;
+  }
+  return storeRef;
+}
+
+function buildPolicySummary(id: string, effect: string, evidence: string): string {
+  return `${id} (${effect}, ${evidence})`;
+}
+
+/** Format store context as a prompt section. */
+export function formatContextForPrompt(ctx: StoreContext): string {
+  const lines: string[] = [
+    `Store: "${ctx.store_name}" (${ctx.policy_count} policies)`,
+    "",
+    "Schema:",
+    ctx.schema_text,
+    "",
+    "Existing policies:",
+  ];
+
+  for (const p of ctx.policy_inventory) {
+    lines.push(`  - ${p.policy_id}: pattern=${p.pattern} (${p.pattern_confidence} confidence) — ${p.summary}`);
+    lines.push(`    text: ${p.policy_text}`);
+  }
+
+  return lines.join("\n");
+}

package/src/tools/advise/gotchas.ts

@@ -0,0 +1,92 @@
+/**
+ * Cedar / AVP gotcha catalog.
+ * Drawn from 03-cedar-developer-guide.md and the AVP validation error categories.
+ */
+
+export interface Gotcha {
+  id: string;
+  severity: "high" | "medium" | "info";
+  description: string;
+  avp_error_category?: string;
+  keywords: string[];  // Used to match gotchas to intent keywords
+}
+
+export const GOTCHA_CATALOG: Gotcha[] = [
+  {
+    id: "optional_attribute_guard",
+    severity: "high",
+    description: "Optional schema attributes MUST be guarded with `entity has attr` before access. Without the guard, Cedar silently skips the policy for any entity missing the attribute — no error, just no match. This is one of the most common silent bugs in Cedar.",
+    avp_error_category: "UnsafeOptionalAttributeAccess",
+    keywords: ["optional", "has", "attribute", "guard", "email", "verified", "nullable"],
+  },
+  {
+    id: "forbid_overrides_permit",
+    severity: "high",
+    description: "A single matching `forbid` policy overrides ALL matching `permit` policies. There is no priority or weight system. Use `unless` to create exemptions inside the forbid itself.",
+    keywords: ["forbid", "block", "deny", "sensitive", "secret", "top_secret", "restrict"],
+  },
+  {
+    id: "avp_in_place_limitation",
+    severity: "high",
+    description: "AVP UpdatePolicy cannot change: effect (permit↔forbid), principal scope, or resource scope. These require deleting the old policy and creating a new one. Plan your deployment accordingly.",
+    avp_error_category: "ResourceNotFoundException",
+    keywords: ["change", "update", "modify", "rename", "role", "principal", "resource", "effect"],
+  },
+  {
+    id: "like_wildcard_crosses_slash",
+    severity: "medium",
+    description: "Cedar's `like` wildcard `*` matches ANY character sequence including `/`. To limit path depth, combine a positive `like` with a negated `like` for deeper patterns. Example: `resource.path like '/api/v1/*' && !(resource.path like '/api/v1/*/*')`.",
+    keywords: ["path", "like", "url", "endpoint", "api", "depth", "wildcard", "route"],
+  },
+  {
+    id: "array_containment_syntax",
+    severity: "medium",
+    description: "Cedar array containment is left-first: `[\"a\", \"b\"].contains(attr)` — the ARRAY is on the left. Writing `attr in [\"a\", \"b\"]` is an entity-hierarchy check, not a value containment check.",
+    keywords: ["contains", "list", "array", "set", "allowlist", "in"],
+  },
+  {
+    id: "schema_first_then_policy",
+    severity: "medium",
+    description: "Schema changes must be deployed BEFORE policies that reference new attributes or types. AVP validates policies against the current schema at creation/update time. Deploying a policy before its schema change causes UnrecognizedEntityType or MissingAttribute errors.",
+    avp_error_category: "MissingAttribute",
+    keywords: ["schema", "attribute", "entity", "add", "new", "field"],
+  },
+  {
+    id: "default_deny",
+    severity: "info",
+    description: "Cedar is default-deny. A request is denied unless at least one `permit` policy explicitly matches AND no `forbid` policy matches. There is no 'allow by default' mode.",
+    keywords: ["deny", "block", "default", "access"],
+  },
+  {
+    id: "rebac_migration_data",
+    severity: "medium",
+    description: "Migrating from RBAC to ReBAC (relationship-based) requires populating relationship attributes on existing resources BEFORE deploying the new policy. Without the data, the policy will deny all access for resources without the relationship attribute.",
+    keywords: ["owner", "owners", "relationship", "rebac", "migrate", "per-document", "per-resource"],
+  },
+  {
+    id: "avp_single_namespace",
+    severity: "info",
+    description: "AVP policy stores support only one namespace per schema. If your Cedar policies use multiple namespaces locally, they cannot be deployed to a single AVP policy store.",
+    keywords: ["namespace", "avp", "deploy"],
+  },
+  {
+    id: "action_groups_not_automatic",
+    severity: "medium",
+    description: "Action group entities must be included in the entity list when evaluating locally. AVP adds them automatically, but local evaluation via WASM (and this tool) does not. Pass action group entities explicitly in your entity list.",
+    keywords: ["action", "group", "batch", "evaluate", "test"],
+  },
+];
+
+/** Select relevant gotchas by matching intent keywords. */
+export function selectGotchas(intent: string, maxCount = 5): Gotcha[] {
+  const lower = intent.toLowerCase();
+  const scored = GOTCHA_CATALOG.map(g => ({
+    gotcha: g,
+    score: g.keywords.filter(kw => lower.includes(kw)).length,
+  }));
+  return scored
+    .filter(s => s.score > 0)
+    .sort((a, b) => b.score - a.score || (a.gotcha.severity === "high" ? -1 : 1))
+    .slice(0, maxCount)
+    .map(s => s.gotcha);
+}