cedar-mcp-server 1.0.0

package/dist/utils/format-detector.js

@@ -0,0 +1,298 @@
+/**
+ * Cedar input format detection and normalization.
+ *
+ * Three AVP SDK variants exist in the wild — all need conversion to Cedar WASM format:
+ *
+ *   Ruby SDK (snake_case):   identifier.entity_type / entity_id, string/long/boolean
+ *   Python/JS SDK (camelCase): identifier.entityType / entityId, string/long/boolean
+ *   Official API/Console (PascalCase): Identifier.EntityType / EntityId, String/Long/Boolean
+ *
+ * Cedar WASM format:
+ *   uid: { type, id }, attrs: { key: rawValue }, parents: [{ type, id }]
+ *   Entity refs in attrs: { __entity: { type, id } }
+ *   Extension types: { __extn: { fn, arg } }
+ *
+ * Detection strategy: case-insensitive key lookup handles all three casing variants
+ * in a single code path. One normalizer to rule them all.
+ *
+ * Cedar CLI format (uid.__entity wrapper): WASM accepts natively — no conversion needed.
+ *
+ * Attribute value wrapper detection rule:
+ *   Single-key object whose key (lowercased) is a known AVP type name AND whose value
+ *   is the matching primitive. Multi-key objects are Cedar Records — not touched.
+ *
+ * Limitation: a Cedar Record with exactly one field named "string"/"long"/"boolean"
+ *   would be misidentified. Adding a second field removes the ambiguity.
+ *
+ * Sources confirmed by SDK docs (2026-05-20):
+ *   Ruby: entity_type/entity_id/entity_identifier (snake_case)
+ *   Python/JS: entityType/entityId/entityIdentifier (camelCase)
+ *   Official API: EntityType/EntityId/EntityIdentifier (PascalCase)
+ */
+// ─── Case-insensitive key access ──────────────────────────────────────────────
+/** Find the value of a key case-insensitively. First match wins. */
+function getCI(obj, key) {
+    const lower = key.toLowerCase();
+    const found = Object.keys(obj).find((k) => k.toLowerCase() === lower);
+    return found !== undefined ? obj[found] : undefined;
+}
+function hasKeyCI(obj, key) {
+    const lower = key.toLowerCase();
+    return Object.keys(obj).some((k) => k.toLowerCase() === lower);
+}
+// ─── Detection ────────────────────────────────────────────────────────────────
+export function detectFormat(entities, principal, action, resource) {
+    // AVP principal/action/resource — any casing of entity_type/entityType/EntityType
+    if (isAvpRef(principal) || isAvpActionRef(action) || isAvpRef(resource)) {
+        return {
+            format: "avp",
+            confidence: "high",
+            note: "Principal, action, or resource is in AVP format (entity_type/entityType/EntityType keys). Automatically converted to Cedar format.",
+        };
+    }
+    // AVP entity list: `identifier` key (case-insensitive) is the clearest signal
+    if (entities.some(hasAvpIdentifierKey)) {
+        return {
+            format: "avp",
+            confidence: "high",
+            note: "Entities are in AVP format (identifier/Identifier key, typed attribute wrappers). Automatically converted to Cedar format.",
+        };
+    }
+    // AVP-typed attribute values without identifier key (partial AVP)
+    if (entities.some(hasAvpTypedAttributeValues)) {
+        return {
+            format: "avp",
+            confidence: "medium",
+            note: "Entity attributes appear to use AVP typed wrappers (string/long/boolean/set/record). Automatically unwrapped to raw Cedar values.",
+        };
+    }
+    // Cedar CLI uid.__entity wrapper — WASM accepts natively, no conversion needed
+    if (entities.some(hasCedarCliEntityWrapper)) {
+        return {
+            format: "cedar_cli",
+            confidence: "high",
+            note: "Entity UIDs use the __entity wrapper (Cedar CLI format). Compatible with Cedar WASM — no conversion needed.",
+        };
+    }
+    return {
+        format: "cedar",
+        confidence: "high",
+        note: "Input is in Cedar/WASM format.",
+    };
+}
+// ─── Normalization ────────────────────────────────────────────────────────────
+export function normalizeEntities(entities, format) {
+    if (format === "cedar" || format === "cedar_cli")
+        return entities;
+    return entities.map(normalizeAvpEntity);
+}
+export function normalizePrincipalRef(ref) {
+    // Cedar string literal: 'Ns::Type::"id"'
+    if (typeof ref === "string") {
+        const match = ref.match(/^(.+)::"(.+)"$/);
+        if (!match)
+            return { error: `Invalid Cedar entity reference: "${ref}". Expected: Namespace::Type::"id"` };
+        return { type: match[1], id: match[2] };
+    }
+    if (typeof ref !== "object" || ref === null) {
+        return { error: `Unrecognized entity reference format: ${JSON.stringify(ref)}` };
+    }
+    const obj = ref;
+    // WASM native: { type, id }
+    if (typeof obj["type"] === "string" && typeof obj["id"] === "string") {
+        return { type: obj["type"], id: obj["id"] };
+    }
+    // WASM Cedar CLI: { __entity: { type, id } }
+    if (obj["__entity"] && typeof obj["__entity"] === "object") {
+        const inner = obj["__entity"];
+        if (typeof inner["type"] === "string" && typeof inner["id"] === "string") {
+            return { type: inner["type"], id: inner["id"] };
+        }
+    }
+    // AVP entity ref — all three casings (entity_type / entityType / EntityType)
+    const entityType = getCI(obj, "entity_type") ?? getCI(obj, "entityType") ?? getCI(obj, "EntityType");
+    const entityId = getCI(obj, "entity_id") ?? getCI(obj, "entityId") ?? getCI(obj, "EntityId");
+    if (typeof entityType === "string" && typeof entityId === "string") {
+        return { type: entityType, id: entityId };
+    }
+    // AVP action ref — all three casings (action_type / actionType / ActionType)
+    const actionType = getCI(obj, "action_type") ?? getCI(obj, "actionType") ?? getCI(obj, "ActionType");
+    const actionId = getCI(obj, "action_id") ?? getCI(obj, "actionId") ?? getCI(obj, "ActionId");
+    if (typeof actionType === "string" && typeof actionId === "string") {
+        return { type: actionType, id: actionId };
+    }
+    return { error: `Unrecognized entity reference format: ${JSON.stringify(ref)}` };
+}
+export function unwrapAvpAttributes(attrs) {
+    const result = {};
+    for (const [key, value] of Object.entries(attrs)) {
+        result[key] = unwrapAvpValue(value);
+    }
+    return result;
+}
+// ─── Private: detection helpers ───────────────────────────────────────────────
+function isAvpRef(ref) {
+    if (typeof ref !== "object" || ref === null)
+        return false;
+    const obj = ref;
+    const hasType = typeof getCI(obj, "entity_type") === "string" ||
+        typeof getCI(obj, "entityType") === "string" ||
+        typeof getCI(obj, "EntityType") === "string";
+    const hasId = typeof getCI(obj, "entity_id") === "string" ||
+        typeof getCI(obj, "entityId") === "string" ||
+        typeof getCI(obj, "EntityId") === "string";
+    return hasType && hasId;
+}
+function isAvpActionRef(ref) {
+    if (typeof ref !== "object" || ref === null)
+        return false;
+    const obj = ref;
+    const hasType = typeof getCI(obj, "action_type") === "string" ||
+        typeof getCI(obj, "actionType") === "string" ||
+        typeof getCI(obj, "ActionType") === "string";
+    const hasId = typeof getCI(obj, "action_id") === "string" ||
+        typeof getCI(obj, "actionId") === "string" ||
+        typeof getCI(obj, "ActionId") === "string";
+    return hasType && hasId;
+}
+function hasAvpIdentifierKey(entity) {
+    if (typeof entity !== "object" || entity === null)
+        return false;
+    return hasKeyCI(entity, "identifier");
+}
+function hasAvpTypedAttributeValues(entity) {
+    if (typeof entity !== "object" || entity === null)
+        return false;
+    const e = entity;
+    const rawAttrs = getCI(e, "attributes") ??
+        getCI(e, "Attributes") ??
+        e["attrs"];
+    if (!rawAttrs || typeof rawAttrs !== "object")
+        return false;
+    return Object.values(rawAttrs).some(isAvpTypedValue);
+}
+function hasCedarCliEntityWrapper(entity) {
+    if (typeof entity !== "object" || entity === null)
+        return false;
+    const e = entity;
+    const uid = e["uid"];
+    if (typeof uid !== "object" || uid === null)
+        return false;
+    return "__entity" in uid;
+}
+/**
+ * Detects AVP typed value wrappers (case-insensitive type key).
+ * Rule: single-key object whose key lowercased is a known AVP type name with matching value type.
+ * Multi-key objects are Cedar Records.
+ */
+function isAvpTypedValue(v) {
+    if (typeof v !== "object" || v === null || Array.isArray(v))
+        return false;
+    const keys = Object.keys(v);
+    if (keys.length !== 1)
+        return false;
+    const key = keys[0].toLowerCase();
+    const val = v[keys[0]];
+    return ((key === "string" && typeof val === "string") ||
+        (key === "long" && typeof val === "number") ||
+        (key === "boolean" && typeof val === "boolean") ||
+        key === "entityidentifier" ||
+        key === "entity_identifier" ||
+        key === "set" ||
+        key === "record" ||
+        key === "ipaddr" ||
+        key === "ipaddress" ||
+        key === "decimal" ||
+        key === "datetime" ||
+        key === "duration");
+}
+// ─── Private: value unwrapping ────────────────────────────────────────────────
+function unwrapAvpValue(v) {
+    if (typeof v !== "object" || v === null || Array.isArray(v))
+        return v;
+    const keys = Object.keys(v);
+    if (keys.length !== 1)
+        return v; // Multi-key object = Cedar Record, not AVP wrapper
+    const key = keys[0];
+    const lowerKey = key.toLowerCase();
+    const val = v[key];
+    switch (lowerKey) {
+        case "string":
+            return typeof val === "string" ? val : v;
+        case "long":
+            return typeof val === "number" ? val : v;
+        case "boolean":
+            return typeof val === "boolean" ? val : v;
+        // Entity reference → WASM __entity
+        case "entityidentifier":
+        case "entity_identifier": {
+            const ref = resolveAvpEntityRef(val);
+            return ref ? { __entity: ref } : v;
+        }
+        // Set → array (recursively normalize values)
+        case "set":
+            return Array.isArray(val) ? val.map(unwrapAvpValue) : v;
+        // Record → object (recursively normalize values)
+        case "record":
+            if (typeof val === "object" && val !== null && !Array.isArray(val)) {
+                return unwrapAvpAttributes(val);
+            }
+            return v;
+        // Cedar extension types → WASM __extn format
+        case "ipaddr":
+        case "ipaddress":
+            return typeof val === "string" ? { __extn: { fn: "ip", arg: val } } : v;
+        case "decimal":
+            return typeof val === "string" ? { __extn: { fn: "decimal", arg: val } } : v;
+        case "datetime":
+            return typeof val === "string" ? { __extn: { fn: "datetime", arg: val } } : v;
+        case "duration":
+            return typeof val === "string" ? { __extn: { fn: "duration", arg: val } } : v;
+        default:
+            return v;
+    }
+}
+/** Resolves an AVP entity reference object (any casing) to { type, id }. */
+function resolveAvpEntityRef(ref) {
+    if (typeof ref !== "object" || ref === null)
+        return null;
+    const obj = ref;
+    const type = (getCI(obj, "entity_type") ?? getCI(obj, "entityType") ?? getCI(obj, "EntityType"));
+    const id = (getCI(obj, "entity_id") ?? getCI(obj, "entityId") ?? getCI(obj, "EntityId"));
+    if (type && id)
+        return { type, id };
+    return null;
+}
+// ─── Private: entity normalization ───────────────────────────────────────────
+function normalizeAvpEntity(entity) {
+    if (typeof entity !== "object" || entity === null)
+        return entity;
+    const e = entity;
+    // UID: find identifier/Identifier key (any casing), convert to { type, id }
+    const identifierKey = Object.keys(e).find((k) => k.toLowerCase() === "identifier");
+    let uid;
+    if (identifierKey) {
+        const idObj = e[identifierKey];
+        const type = getCI(idObj, "entity_type") ?? getCI(idObj, "entityType") ?? getCI(idObj, "EntityType");
+        const id = getCI(idObj, "entity_id") ?? getCI(idObj, "entityId") ?? getCI(idObj, "EntityId");
+        uid = { type, id };
+    }
+    else {
+        uid = e["uid"];
+    }
+    // Attrs: find attributes/Attributes key (any casing), fall back to attrs
+    const attrsKey = Object.keys(e).find((k) => k.toLowerCase() === "attributes");
+    const rawAttrs = (attrsKey ? e[attrsKey] : e["attrs"]) ?? {};
+    const attrs = unwrapAvpAttributes(rawAttrs);
+    // Parents: find parents/Parents key (any casing), convert entity_type/entityType/EntityType → type/id
+    const parentsKey = Object.keys(e).find((k) => k.toLowerCase() === "parents");
+    const rawParents = ((parentsKey ? e[parentsKey] : e["parents"]) ?? []);
+    const parents = rawParents.map((p) => {
+        if (typeof p !== "object" || p === null)
+            return p;
+        const ref = resolveAvpEntityRef(p);
+        return ref ?? p;
+    });
+    return { uid, attrs, parents };
+}
+//# sourceMappingURL=format-detector.js.map

package/dist/utils/format-detector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-detector.js","sourceRoot":"","sources":["../../src/utils/format-detector.ts"],"names":[],"mappings":"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"}

package/examples/README.md

@@ -0,0 +1,36 @@
+# Examples
+
+Three self-contained Cedar authorization scenarios. Each one has a schema, policy files, an entity store, a runnable script, and a README with copy-paste prompts for Claude Code.
+
+## Pick your pattern
+
+| Example | Cedar patterns | Start here if... |
+|---------|---------------|-----------------|
+| [rbac-document-management](./rbac-document-management/) | Role membership, `forbid` + `unless`, default deny | You're new to Cedar or building a simple role-based system |
+| [abac-multi-tenant](./abac-multi-tenant/) | Attribute conditions, `contains()`, optional attribute guards, plan-tier gating | You need decisions based on resource or user attributes, not just roles |
+| [api-gateway-path-routing](./api-gateway-path-routing/) | Path matching with `like`, depth limiting via negation, method restriction | You're authorizing HTTP requests at a gateway or proxy |
+
+## Run all examples offline
+
+Each example includes a `run.ts` that exercises all tools against the example files. No MCP client or AI assistant required.
+
+```bash
+npx tsx examples/rbac-document-management/run.ts
+npx tsx examples/abac-multi-tenant/run.ts
+npx tsx examples/api-gateway-path-routing/run.ts
+```
+
+## Use with Claude Code
+
+Add `cedar-mcp-server` to your MCP configuration, then paste the prompts from any example README directly into a conversation. The examples are designed so the tool inputs fit in a single message.
+
+```json
+{
+  "mcpServers": {
+    "cedar": {
+      "command": "npx",
+      "args": ["-y", "cedar-mcp-server"]
+    }
+  }
+}
+```

package/examples/abac-multi-tenant/README.md

@@ -0,0 +1,150 @@
+# ABAC Multi-Tenant (SaaS document collaboration)
+
+Attribute-based access control for a multi-tenant SaaS app where decisions depend on document visibility, ownership, and user plan tier.
+
+## What this example covers
+
+Four Cedar patterns that appear together in almost every real SaaS authorization model:
+
+- **Name-based identity**: `principal.name == resource.owner_id` — matching a user to their own resources
+- **Array containment**: `["internal", "public"].contains(resource.visibility)` — allowlist of values
+- **Plan-tier gating**: `principal.plan == "pro" || principal.plan == "enterprise"` — feature flagging in Cedar
+- **`forbid` with `unless`**: blocks private document access except for the owner
+
+Demonstrates all five tools, with `cedar_check_policy_change` showing the principal-change trap.
+
+## Quick start
+
+Configure the MCP server in Claude Code (`.claude/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "cedar": {
+      "command": "npx",
+      "args": ["-y", "cedar-mcp-server"]
+    }
+  }
+}
+```
+
+Or run offline:
+
+```bash
+npx tsx examples/abac-multi-tenant/run.ts
+```
+
+## Files
+
+```
+schema.json                    SaaS namespace: User (name, plan), Document (visibility, owner_id)
+policies/
+  owner-full-access.cedar      Owners have full access to their documents
+  member-read-internal.cedar   Authenticated users can read internal/public docs
+  premium-share-guard.cedar    Only pro/enterprise plan can share
+  private-doc-guard.cedar      Private docs blocked for non-owners (forbid + unless)
+entities/
+  users-and-docs.json          Alice (enterprise), Bob (pro), Charlie (free) + documents
+```
+
+---
+
+## Tool examples — copy and paste to Claude Code
+
+### cedar_authorize
+
+```
+Is charlie allowed to read the salary-review document?
+
+Policies: [paste all .cedar files]
+Principal: SaaS::User::"charlie"
+Action: SaaS::Action::"READ"
+Resource: SaaS::Document::"salary-review"
+Entities: [paste entities/users-and-docs.json]
+Schema: [paste schema.json]
+```
+
+Expected: **Deny** — `salary-review` has `visibility: "private"` and `owner_id: "alice"`. Charlie is not the owner, so the `private-doc-guard` forbid fires.
+
+```
+Can charlie share the public-changelog?
+```
+
+Expected: **Deny** — `premium-share-guard` requires `plan == "pro"` or `"enterprise"`. Charlie is on the free plan.
+
+### cedar_explain
+
+```
+Explain this Cedar policy:
+
+permit (
+  principal,
+  action == SaaS::Action::"READ",
+  resource
+)
+when {
+  ["internal", "public"].contains(resource.visibility)
+};
+```
+
+Expected: plain-English breakdown including the `contains()` containment check and the pattern detection `attribute_containment_check`.
+
+### cedar_generate_sample_request
+
+```
+Generate a sample request that would be ALLOWED by this policy:
+
+permit (
+  principal,
+  action == SaaS::Action::"SHARE",
+  resource
+)
+when {
+  principal.plan == "pro" || principal.plan == "enterprise"
+};
+
+Schema: [paste schema.json]
+```
+
+Expected: a principal with `plan: "pro"` or `"enterprise"`, with an explanation of which condition was satisfied.
+
+### cedar_check_policy_change
+
+```
+Can this change be applied in-place in Amazon Verified Permissions?
+
+Old policy:
+permit(principal, action, resource) when { principal.name == resource.owner_id };
+
+New policy:
+permit(principal in SaaS::Role::"editor", action, resource);
+```
+
+Expected: **cannot update in-place** — switching from a condition-based identity check to a role-based principal scope changes the principal clause, which AVP treats as immutable.
+
+---
+
+## Test cases
+
+| Principal | Action | Resource | Expected | Reason |
+|-----------|--------|----------|----------|--------|
+| alice (owner) | READ | salary-review (private) | **Allow** | Owner exempt from private-doc-guard |
+| alice (owner) | DELETE | q4-roadmap | **Allow** | Owner full access |
+| bob (non-owner, pro) | READ | q4-roadmap (internal) | **Allow** | member-read-internal matches |
+| bob (non-owner, pro) | READ | salary-review (private) | **Deny** | private-doc-guard forbid, bob is not owner |
+| bob (pro) | SHARE | public-changelog | **Allow** | pro plan satisfies premium-share-guard |
+| charlie (non-owner, free) | READ | public-changelog (public) | **Allow** | member-read-internal: "public" in allowlist |
+| charlie (free) | SHARE | public-changelog | **Deny** | free plan fails premium-share-guard |
+| charlie (non-owner, free) | READ | salary-review (private) | **Deny** | private-doc-guard forbid |
+
+---
+
+## Common pitfalls in this pattern
+
+**`principal.name` is not authentication.** Cedar doesn't verify identity — it evaluates the entity attributes you provide. If you pass `attrs: { name: "alice" }`, Cedar trusts it. The security boundary is in how you build your entity store, not in the Cedar policy.
+
+**Array containment goes array-first.** Cedar uses `["a", "b"].contains(value)` — the array is on the LEFT, the value is on the right. Writing `value.contains("a")` is a type error because strings don't have a `contains` method in Cedar.
+
+**`forbid` + `unless` is not the same as two separate permits.** The `unless` clause in `private-doc-guard` means "forbid UNLESS owner". Without the `unless`, the forbid would block the owner too and no `permit` could override it. Never assume a `permit` can override a `forbid` — it cannot.
+
+**Plan-tier changes need policy updates.** If a user upgrades from free to pro, their `plan` attribute in the entity store must be updated before Cedar reflects the change. Cedar has no concept of time — it evaluates the current entity state only.

package/examples/abac-multi-tenant/entities/users-and-docs.json

@@ -0,0 +1,33 @@
+[
+  {
+    "uid": { "type": "SaaS::User", "id": "alice" },
+    "attrs": { "name": "alice", "plan": "enterprise" },
+    "parents": []
+  },
+  {
+    "uid": { "type": "SaaS::User", "id": "bob" },
+    "attrs": { "name": "bob", "plan": "pro" },
+    "parents": []
+  },
+  {
+    "uid": { "type": "SaaS::User", "id": "charlie" },
+    "attrs": { "name": "charlie", "plan": "free" },
+    "parents": []
+  },
+  { "uid": { "type": "SaaS::Workspace", "id": "acme-corp" }, "attrs": {}, "parents": [] },
+  {
+    "uid": { "type": "SaaS::Document", "id": "q4-roadmap" },
+    "attrs": { "visibility": "internal", "owner_id": "alice" },
+    "parents": [{ "type": "SaaS::Workspace", "id": "acme-corp" }]
+  },
+  {
+    "uid": { "type": "SaaS::Document", "id": "public-changelog" },
+    "attrs": { "visibility": "public", "owner_id": "alice" },
+    "parents": [{ "type": "SaaS::Workspace", "id": "acme-corp" }]
+  },
+  {
+    "uid": { "type": "SaaS::Document", "id": "salary-review" },
+    "attrs": { "visibility": "private", "owner_id": "alice" },
+    "parents": [{ "type": "SaaS::Workspace", "id": "acme-corp" }]
+  }
+]

package/examples/abac-multi-tenant/policies/member-read-internal.cedar

@@ -0,0 +1,9 @@
+// Any authenticated user can read internal and public documents
+permit (
+  principal,
+  action == SaaS::Action::"READ",
+  resource
+)
+when {
+  ["internal", "public"].contains(resource.visibility)
+};

package/examples/abac-multi-tenant/policies/owner-full-access.cedar

@@ -0,0 +1,9 @@
+// Document owners have full access to their own documents
+permit (
+  principal,
+  action,
+  resource
+)
+when {
+  principal.name == resource.owner_id
+};

package/examples/abac-multi-tenant/policies/premium-share-guard.cedar

@@ -0,0 +1,9 @@
+// Only pro and enterprise plan users can share documents
+permit (
+  principal,
+  action == SaaS::Action::"SHARE",
+  resource
+)
+when {
+  principal.plan == "pro" || principal.plan == "enterprise"
+};

package/examples/abac-multi-tenant/policies/private-doc-guard.cedar

@@ -0,0 +1,13 @@
+// Private documents are blocked for everyone except the owner
+// Uses optional attribute guard: check visibility before accessing
+forbid (
+  principal,
+  action,
+  resource
+)
+when {
+  resource.visibility == "private"
+}
+unless {
+  principal.name == resource.owner_id
+};