cedar-mcp-server 1.0.0

package/examples/abac-multi-tenant/run.ts

@@ -0,0 +1,92 @@
+/**
+ * Offline runner for the abac-multi-tenant example.
+ * Usage: npx tsx examples/abac-multi-tenant/run.ts
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { handleAuthorize } from "../../src/tools/authorize.js";
+import { handleValidate } from "../../src/tools/validate.js";
+import { handleExplain } from "../../src/tools/explain.js";
+import { handleCheckChange } from "../../src/tools/check-change.js";
+import { handleGenerateSample } from "../../src/tools/generate-sample.js";
+
+const dir = new URL(".", import.meta.url).pathname;
+const read = (p: string) => readFileSync(join(dir, p), "utf8");
+
+const schema = read("schema.json");
+const entities = read("entities/users-and-docs.json");
+
+const policies = [
+  read("policies/owner-full-access.cedar"),
+  read("policies/member-read-internal.cedar"),
+  read("policies/premium-share-guard.cedar"),
+  read("policies/private-doc-guard.cedar"),
+].join("\n\n");
+
+function section(title: string) {
+  console.log(`\n${"─".repeat(60)}`);
+  console.log(`  ${title}`);
+  console.log("─".repeat(60));
+}
+
+// ─── cedar_validate ───────────────────────────────────────────────────────────
+
+section("cedar_validate — all policies against schema");
+const vr = await handleValidate({ policies, schema });
+console.log(`  valid: ${vr.valid}  |  policies: ${vr.policy_count}`);
+if (vr.errors.length) console.log("  errors:", vr.errors);
+
+// ─── cedar_authorize ──────────────────────────────────────────────────────────
+
+section("cedar_authorize — ABAC decisions");
+const cases = [
+  { label: "alice reads q4-roadmap (owner, internal)", p: 'SaaS::User::"alice"', a: 'SaaS::Action::"READ"', r: 'SaaS::Document::"q4-roadmap"', expected: "Allow" },
+  { label: "bob reads q4-roadmap (non-owner, internal)", p: 'SaaS::User::"bob"', a: 'SaaS::Action::"READ"', r: 'SaaS::Document::"q4-roadmap"', expected: "Allow" },
+  { label: "charlie reads salary-review (non-owner, private)", p: 'SaaS::User::"charlie"', a: 'SaaS::Action::"READ"', r: 'SaaS::Document::"salary-review"', expected: "Deny" },
+  { label: "alice reads salary-review (owner, private)", p: 'SaaS::User::"alice"', a: 'SaaS::Action::"READ"', r: 'SaaS::Document::"salary-review"', expected: "Allow" },
+  { label: "charlie shares public-changelog (free plan)", p: 'SaaS::User::"charlie"', a: 'SaaS::Action::"SHARE"', r: 'SaaS::Document::"public-changelog"', expected: "Deny" },
+  { label: "bob shares public-changelog (pro plan)", p: 'SaaS::User::"bob"', a: 'SaaS::Action::"SHARE"', r: 'SaaS::Document::"public-changelog"', expected: "Allow" },
+];
+
+for (const c of cases) {
+  const r = await handleAuthorize({ policies, principal: c.p, action: c.a, resource: c.r, entities, schema });
+  const pass = r.decision === c.expected ? "✓" : "✗";
+  console.log(`  ${pass} ${c.label}: ${r.decision}`);
+}
+
+// ─── cedar_explain ────────────────────────────────────────────────────────────
+
+section("cedar_explain — premium-share-guard");
+const er = await handleExplain({ policy: read("policies/premium-share-guard.cedar") });
+console.log(`  summary: ${er.summary}`);
+console.log(`  patterns: ${er.patterns_detected.join(", ")}`);
+console.log(`  conditions:`);
+for (const c of er.conditions) console.log(`    [${c.kind}] ${c.text}`);
+
+// ─── cedar_generate_sample_request ───────────────────────────────────────────
+
+section("cedar_generate_sample_request — deny for member-read-internal");
+const gr = await handleGenerateSample({
+  policy: read("policies/member-read-internal.cedar"),
+  schema,
+  target_decision: "deny",
+});
+console.log(`  decision: ${gr.decision}`);
+console.log(`  resource attrs: ${JSON.stringify(gr.entities.find(e => e.uid.type.includes("Document"))?.attrs)}`);
+console.log(`  explanation: ${gr.explanation}`);
+
+// ─── cedar_check_policy_change ────────────────────────────────────────────────
+
+section("cedar_check_policy_change — owner check vs role check");
+const cr = await handleCheckChange({
+  old_policy: `permit(principal, action, resource) when { principal.name == resource.owner_id };`,
+  new_policy: `permit(principal in SaaS::Role::"editor", action, resource);`,
+});
+console.log(`  can_update_in_place: ${cr.can_update_in_place}`);
+for (const c of cr.changes) {
+  console.log(`  field=${c.field}  in_place_allowed=${c.in_place_allowed}`);
+}
+console.log(`  recommendation: ${cr.recommendation}`);
+
+console.log("\n✓ All done.");

package/examples/abac-multi-tenant/schema.json

@@ -0,0 +1,60 @@
+{
+  "SaaS": {
+    "entityTypes": {
+      "User": {
+        "memberOfTypes": [],
+        "shape": {
+          "type": "Record",
+          "attributes": {
+            "name": { "type": "String", "required": true },
+            "plan": { "type": "String", "required": true }
+          }
+        }
+      },
+      "Workspace": {
+        "memberOfTypes": [],
+        "shape": { "type": "Record", "attributes": {} }
+      },
+      "Document": {
+        "memberOfTypes": ["Workspace"],
+        "shape": {
+          "type": "Record",
+          "attributes": {
+            "visibility": { "type": "String", "required": true },
+            "owner_id": { "type": "String", "required": true }
+          }
+        }
+      }
+    },
+    "actions": {
+      "READ": {
+        "appliesTo": {
+          "principalTypes": ["User"],
+          "resourceTypes": ["Document"],
+          "context": { "type": "Record", "attributes": {} }
+        }
+      },
+      "WRITE": {
+        "appliesTo": {
+          "principalTypes": ["User"],
+          "resourceTypes": ["Document"],
+          "context": { "type": "Record", "attributes": {} }
+        }
+      },
+      "SHARE": {
+        "appliesTo": {
+          "principalTypes": ["User"],
+          "resourceTypes": ["Document"],
+          "context": { "type": "Record", "attributes": {} }
+        }
+      },
+      "DELETE": {
+        "appliesTo": {
+          "principalTypes": ["User"],
+          "resourceTypes": ["Document"],
+          "context": { "type": "Record", "attributes": {} }
+        }
+      }
+    }
+  }
+}

package/examples/api-gateway-path-routing/README.md

@@ -0,0 +1,154 @@
+# API Gateway Path Routing
+
+Role-based access control for a REST API gateway — combining role membership, HTTP method restriction, path matching, and depth limiting in a single Cedar policy.
+
+## What this example covers
+
+Three policies that mirror a real API gateway authorization model:
+
+- **Role-based action restriction**: `action in [API::Action::"GET", API::Action::"POST"]` — developers can read and create, but not update or delete
+- **Exact path match**: `resource.path == "/api/v1/projects"` — collection endpoint
+- **Path matching with depth limiting**: `like "/api/v1/projects/*" && !(like "/api/v1/projects/*/*")` — allows one path segment deep, blocks sub-resources
+- **No depth limit for viewers**: viewers can GET at any depth, developers cannot POST beyond one level
+
+The `cedar_generate_sample_request` results show the depth-limiting in action: the allow path is `/api/v1/projects/x`, the deny path is `/api/v1/projects/x/x`.
+
+## 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/api-gateway-path-routing/run.ts
+```
+
+## Files
+
+```
+schema.json                         API namespace: User, Role, Endpoint (path, method)
+policies/
+  admin-full-access.cedar           Admins: any action, any endpoint
+  developer-projects.cedar          Developers: GET/POST, depth-limited to one level
+  viewer-readonly.cedar             Viewers: GET only, any depth
+entities/
+  users-and-roles.json              Alice (admin), Bob (developer), Charlie (viewer)
+```
+
+---
+
+## Tool examples — copy and paste to Claude Code
+
+### cedar_authorize
+
+```
+Would Bob be allowed to GET /api/v1/projects/proj-1/tasks?
+
+Policies: [paste all .cedar files]
+Principal: API::User::"bob"
+Action: API::Action::"GET"
+Resource: API::Endpoint::"req"
+Entities: [paste entities/users-and-roles.json, then add this endpoint entity:
+  { "uid": { "type": "API::Endpoint", "id": "req" },
+    "attrs": { "path": "/api/v1/projects/proj-1/tasks", "method": "GET" },
+    "parents": [] }]
+Schema: [paste schema.json]
+```
+
+Expected: **Deny** — `/api/v1/projects/proj-1/tasks` is two levels deep. The `&&` condition fails because the path matches `like "/api/v1/projects/*/*"`, so `!(like "/api/v1/projects/*/*")` is false.
+
+```
+Would Charlie be allowed to GET /api/v1/projects/proj-1/tasks?
+```
+
+Expected: **Allow** — the `viewer-readonly` policy has no depth limit. Charlie can GET at any depth.
+
+### cedar_explain
+
+```
+Explain this Cedar policy:
+
+permit (
+  principal in API::Role::"developer",
+  action in [API::Action::"GET", API::Action::"POST"],
+  resource
+)
+when {
+  resource.path == "/api/v1/projects"
+  || (
+    resource.path like "/api/v1/projects/*"
+    && !(resource.path like "/api/v1/projects/*/*")
+  )
+};
+```
+
+Expected: a breakdown showing the two-part `||` condition — exact match at collection level, plus depth-limited path match — with the `like` patterns rendered as Cedar syntax.
+
+### cedar_generate_sample_request
+
+```
+Generate a sample request that would be ALLOWED by this policy:
+
+permit (
+  principal in API::Role::"developer",
+  action in [API::Action::"GET", API::Action::"POST"],
+  resource
+)
+when {
+  resource.path == "/api/v1/projects"
+  || (
+    resource.path like "/api/v1/projects/*"
+    && !(resource.path like "/api/v1/projects/*/*")
+  )
+};
+
+Schema: [paste schema.json]
+Target decision: allow
+```
+
+Expected: a path like `/api/v1/projects` or `/api/v1/projects/x` (one level deep).
+
+```
+Generate a sample request that would be DENIED.
+Target decision: deny
+```
+
+Expected: a path like `/api/v1/projects/x/x` — two levels deep, which satisfies the negative `like` pattern and makes `!(like "/api/v1/projects/*/*")` false.
+
+---
+
+## Test cases
+
+| Principal | Action | Path | Expected | Reason |
+|-----------|--------|------|----------|--------|
+| alice (admin) | DELETE | /api/v1/projects/proj-1 | **Allow** | Admin policy permits everything |
+| bob (developer) | GET | /api/v1/projects | **Allow** | Exact collection match |
+| bob (developer) | POST | /api/v1/projects/proj-1 | **Allow** | One level deep, POST permitted |
+| bob (developer) | GET | /api/v1/projects/proj-1/tasks | **Deny** | Two levels deep, depth limit triggered |
+| bob (developer) | DELETE | /api/v1/projects | **Deny** | DELETE not in developer action list |
+| charlie (viewer) | GET | /api/v1/projects/proj-1 | **Allow** | Viewer can GET one level |
+| charlie (viewer) | GET | /api/v1/projects/proj-1/tasks | **Allow** | Viewer has no depth limit |
+| charlie (viewer) | POST | /api/v1/projects | **Deny** | Viewer cannot POST |
+
+---
+
+## Common pitfalls in this pattern
+
+**Cedar `*` matches `/`** — unlike shell globs or URL matchers, Cedar's `*` wildcard matches any character sequence including path separators. `like "/api/v1/*"` matches `/api/v1/projects/proj-1/tasks/comments`. Depth limiting requires explicit negation: `&& !(like "/api/v1/projects/*/*")`.
+
+**Viewer and developer have different depth semantics — intentionally.** The developer policy has depth-limiting because developers are expected to act on individual resources, not traverse sub-resource trees. The viewer policy has no depth limit because read-only access to deeper paths is lower risk. This is a deliberate design choice, not an oversight.
+
+**Path matching is evaluated at request time, not at policy store creation.** The `resource.path` attribute comes from your entity store — the value your application puts there when building the authorization request. Cedar does not parse URLs. If your application sends `path: "/api/v1/projects/proj-1"` in the entity, that is what Cedar evaluates. Normalizing paths (trailing slash, URL encoding) is your application's responsibility.
+
+**Action names are Cedar entity IDs, not HTTP methods.** `API::Action::"GET"` is a Cedar entity identifier that happens to be named `GET`. You decide the mapping between Cedar action IDs and HTTP methods in your application layer. Cedar doesn't know what HTTP is.

package/examples/api-gateway-path-routing/entities/users-and-roles.json

@@ -0,0 +1,20 @@
+[
+  {
+    "uid": { "type": "API::User", "id": "alice" },
+    "attrs": {},
+    "parents": [{ "type": "API::Role", "id": "admin" }]
+  },
+  {
+    "uid": { "type": "API::User", "id": "bob" },
+    "attrs": {},
+    "parents": [{ "type": "API::Role", "id": "developer" }]
+  },
+  {
+    "uid": { "type": "API::User", "id": "charlie" },
+    "attrs": {},
+    "parents": [{ "type": "API::Role", "id": "viewer" }]
+  },
+  { "uid": { "type": "API::Role", "id": "admin" }, "attrs": {}, "parents": [] },
+  { "uid": { "type": "API::Role", "id": "developer" }, "attrs": {}, "parents": [] },
+  { "uid": { "type": "API::Role", "id": "viewer" }, "attrs": {}, "parents": [] }
+]

package/examples/api-gateway-path-routing/policies/admin-full-access.cedar

@@ -0,0 +1,6 @@
+// Admins have full access to all endpoints and methods
+permit (
+  principal in API::Role::"admin",
+  action,
+  resource
+);

package/examples/api-gateway-path-routing/policies/developer-projects.cedar

@@ -0,0 +1,14 @@
+// Developers can GET and POST to the projects collection and individual projects
+// Depth-limiting: allows /api/v1/projects and /api/v1/projects/{id} but NOT deeper paths
+permit (
+  principal in API::Role::"developer",
+  action in [API::Action::"GET", API::Action::"POST"],
+  resource
+)
+when {
+  resource.path == "/api/v1/projects"
+  || (
+    resource.path like "/api/v1/projects/*"
+    && !(resource.path like "/api/v1/projects/*/*")
+  )
+};

package/examples/api-gateway-path-routing/policies/viewer-readonly.cedar

@@ -0,0 +1,10 @@
+// Viewers can only GET — collection level and one level deep
+permit (
+  principal in API::Role::"viewer",
+  action == API::Action::"GET",
+  resource
+)
+when {
+  resource.path == "/api/v1/projects"
+  || resource.path like "/api/v1/projects/*"
+};

package/examples/api-gateway-path-routing/run.ts

@@ -0,0 +1,108 @@
+/**
+ * Offline runner for the api-gateway-path-routing example.
+ * Usage: npx tsx examples/api-gateway-path-routing/run.ts
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { handleAuthorize } from "../../src/tools/authorize.js";
+import { handleValidate } from "../../src/tools/validate.js";
+import { handleExplain } from "../../src/tools/explain.js";
+import { handleGenerateSample } from "../../src/tools/generate-sample.js";
+
+const dir = new URL(".", import.meta.url).pathname;
+const read = (p: string) => readFileSync(join(dir, p), "utf8");
+
+const schema = read("schema.json");
+const entities = read("entities/users-and-roles.json");
+
+const policies = [
+  read("policies/admin-full-access.cedar"),
+  read("policies/developer-projects.cedar"),
+  read("policies/viewer-readonly.cedar"),
+].join("\n\n");
+
+function section(title: string) {
+  console.log(`\n${"─".repeat(60)}`);
+  console.log(`  ${title}`);
+  console.log("─".repeat(60));
+}
+
+// Helper: build an endpoint entity on the fly for a given path + method
+function withEndpoint(path: string, method: string) {
+  const base = JSON.parse(entities) as unknown[];
+  base.push({
+    uid: { type: "API::Endpoint", id: "req" },
+    attrs: { path, method },
+    parents: [],
+  });
+  return JSON.stringify(base);
+}
+
+// ─── cedar_validate ───────────────────────────────────────────────────────────
+
+section("cedar_validate — all policies against schema");
+const vr = await handleValidate({ policies, schema });
+console.log(`  valid: ${vr.valid}  |  policies: ${vr.policy_count}`);
+
+// ─── cedar_authorize — path depth tests ───────────────────────────────────────
+
+section("cedar_authorize — path-depth routing decisions");
+
+const routeCases = [
+  { label: "bob GET /api/v1/projects (collection)", user: "bob", action: "GET", path: "/api/v1/projects", expected: "Allow" },
+  { label: "bob POST /api/v1/projects/proj-1 (one level deep)", user: "bob", action: "POST", path: "/api/v1/projects/proj-1", expected: "Allow" },
+  { label: "bob GET /api/v1/projects/proj-1/tasks (two levels — blocked)", user: "bob", action: "GET", path: "/api/v1/projects/proj-1/tasks", expected: "Deny" },
+  { label: "bob DELETE /api/v1/projects (DELETE not permitted)", user: "bob", action: "DELETE", path: "/api/v1/projects", expected: "Deny" },
+  { label: "charlie GET /api/v1/projects/proj-1 (viewer, one level)", user: "charlie", action: "GET", path: "/api/v1/projects/proj-1", expected: "Allow" },
+  { label: "charlie GET /api/v1/projects/proj-1/tasks (viewer, no depth limit — allowed)", user: "charlie", action: "GET", path: "/api/v1/projects/proj-1/tasks", expected: "Allow" },
+  { label: "alice DELETE /api/v1/projects/proj-1 (admin, anything)", user: "alice", action: "DELETE", path: "/api/v1/projects/proj-1", expected: "Allow" },
+];
+
+for (const c of routeCases) {
+  const ents = withEndpoint(c.path, c.action);
+  const r = await handleAuthorize({
+    policies,
+    principal: `API::User::"${c.user}"`,
+    action: `API::Action::"${c.action}"`,
+    resource: 'API::Endpoint::"req"',
+    entities: ents,
+    schema,
+  });
+  const pass = r.decision === c.expected ? "✓" : "✗";
+  console.log(`  ${pass} ${c.label}: ${r.decision}`);
+}
+
+// ─── cedar_explain ────────────────────────────────────────────────────────────
+
+section("cedar_explain — developer-projects (path-matching + depth limit)");
+const er = await handleExplain({ policy: read("policies/developer-projects.cedar") });
+console.log(`  summary: ${er.summary}`);
+console.log(`  conditions:`);
+for (const c of er.conditions) console.log(`    [${c.kind}] ${c.text}`);
+
+// ─── cedar_generate_sample_request ───────────────────────────────────────────
+
+section("cedar_generate_sample_request — allow path for developer-projects");
+const allowSample = await handleGenerateSample({
+  policy: read("policies/developer-projects.cedar"),
+  schema,
+  target_decision: "allow",
+});
+console.log(`  decision: ${allowSample.decision}`);
+const ep = allowSample.entities.find(e => e.uid.type.includes("Endpoint"));
+console.log(`  generated path: ${ep?.attrs?.path}`);
+console.log(`  explanation: ${allowSample.explanation}`);
+
+section("cedar_generate_sample_request — deny path (too deep)");
+const denySample = await handleGenerateSample({
+  policy: read("policies/developer-projects.cedar"),
+  schema,
+  target_decision: "deny",
+});
+console.log(`  decision: ${denySample.decision}`);
+const ep2 = denySample.entities.find(e => e.uid.type.includes("Endpoint"));
+console.log(`  generated path: ${ep2?.attrs?.path}`);
+console.log(`  explanation: ${denySample.explanation}`);
+
+console.log("\n✓ All done.");

package/examples/api-gateway-path-routing/schema.json

@@ -0,0 +1,54 @@
+{
+  "API": {
+    "entityTypes": {
+      "User": {
+        "memberOfTypes": ["Role"],
+        "shape": { "type": "Record", "attributes": {} }
+      },
+      "Role": {
+        "memberOfTypes": [],
+        "shape": { "type": "Record", "attributes": {} }
+      },
+      "Endpoint": {
+        "memberOfTypes": [],
+        "shape": {
+          "type": "Record",
+          "attributes": {
+            "path": { "type": "String", "required": true },
+            "method": { "type": "String", "required": true }
+          }
+        }
+      }
+    },
+    "actions": {
+      "GET": {
+        "appliesTo": {
+          "principalTypes": ["User"],
+          "resourceTypes": ["Endpoint"],
+          "context": { "type": "Record", "attributes": {} }
+        }
+      },
+      "POST": {
+        "appliesTo": {
+          "principalTypes": ["User"],
+          "resourceTypes": ["Endpoint"],
+          "context": { "type": "Record", "attributes": {} }
+        }
+      },
+      "PUT": {
+        "appliesTo": {
+          "principalTypes": ["User"],
+          "resourceTypes": ["Endpoint"],
+          "context": { "type": "Record", "attributes": {} }
+        }
+      },
+      "DELETE": {
+        "appliesTo": {
+          "principalTypes": ["User"],
+          "resourceTypes": ["Endpoint"],
+          "context": { "type": "Record", "attributes": {} }
+        }
+      }
+    }
+  }
+}