cedar-mcp-server 1.0.0

package/src/prompts/index.ts

@@ -0,0 +1,217 @@
+/**
+ * MCP Prompt definitions for cedar-mcp-server.
+ *
+ * Registration in src/server.ts:
+ *   import { PROMPT_DEFINITIONS } from "./prompts/index.js";
+ *   for (const p of PROMPT_DEFINITIONS) {
+ *     server.prompt(p.name, p.description, p.argsSchema, p.handler);
+ *   }
+ *
+ * Each PromptDefinition is built via definePrompt(), which captures the Zod
+ * raw shape generically so TypeScript preserves the concrete arg types through
+ * the handler. The array is typed as PromptDefinition<ZodRawShape> for the
+ * export; the SDK's server.prompt() overload accepts the same shape.
+ */
+
+import { z } from "zod";
+import type { GetPromptResult } from "@modelcontextprotocol/sdk/types.js";
+import type { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import type { ServerRequest, ServerNotification } from "@modelcontextprotocol/sdk/types.js";
+
+type ZodRawShape = Record<string, z.ZodTypeAny>;
+type ShapeOutput<S extends ZodRawShape> = { [K in keyof S]: z.infer<S[K]> };
+type PromptExtra = RequestHandlerExtra<ServerRequest, ServerNotification>;
+
+/**
+ * PromptDefinition is intentionally generic so handler arg types are preserved
+ * internally. At the export boundary the array is cast to the widened union
+ * via definePrompt() which uses `as unknown as` once, in one place.
+ */
+export interface PromptDefinition<Args extends ZodRawShape = ZodRawShape> {
+  name: string;
+  description: string;
+  argsSchema: Args;
+  handler: (args: ShapeOutput<Args>, extra: PromptExtra) => GetPromptResult | Promise<GetPromptResult>;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyPromptDefinition = PromptDefinition<any>;
+
+function definePrompt<Args extends ZodRawShape>(
+  def: PromptDefinition<Args>
+): AnyPromptDefinition {
+  return def as AnyPromptDefinition;
+}
+
+// ---------------------------------------------------------------------------
+// 1. cedar-review-policy-diff
+//
+// UX assumption: the user has two named policy stores ("blue" = production,
+// "green" = candidate) and wants a structured review before promoting. They
+// expect the prompt to drive all Cedar tool calls and produce a clear verdict.
+//
+// Falsifiability check: would this be useless? Yes, if it skipped the schema
+// diff step. A promoter who misses schema diff will hit breaking changes only
+// at query time. Fixed: schema diff is an explicit step with BREAKING/
+// NON-BREAKING classification.
+// ---------------------------------------------------------------------------
+const reviewPolicyDiff = definePrompt({
+  name: "cedar-review-policy-diff",
+  description:
+    "Drive a structured Cedar policy store promotion review: diff policies, diff schema, summarize breaking risk, and produce a go/no-go recommendation.",
+  argsSchema: {
+    blue_store: z.string().describe("Name of the baseline (production) policy store"),
+    green_store: z.string().describe("Name of the candidate policy store to review"),
+    focus: z
+      .string()
+      .optional()
+      .describe(
+        "Optional: narrows review attention, e.g. 'AVP immutability' or 'forbid rules only'"
+      ),
+  },
+  handler: (args) => {
+    const focusNote = args.focus
+      ? `\n\nFocus area for this review: ${args.focus}. Apply extra scrutiny to anything touching that area.`
+      : "";
+
+    const text =
+      `You are reviewing a Cedar policy store promotion from "${args.blue_store}" (baseline) to "${args.green_store}" (candidate).` +
+      `${focusNote}` +
+      `\n\nWork through the following steps in order.\n\n` +
+      `Step 1: Structural diff.\n` +
+      `Call cedar_diff_policy_stores with blue="${args.blue_store}" and green="${args.green_store}". ` +
+      `List every added, removed, and modified policy. Note the policy IDs and whether each change is additive or restrictive.\n\n` +
+      `Step 2: Schema diff.\n` +
+      `Call cedar_diff_schema with schemas from both stores (cedar://schema/${args.blue_store} and cedar://schema/${args.green_store}). ` +
+      `If the diff is non-trivial (any entity type added, removed, or attribute changed), classify each change as BREAKING or NON-BREAKING. ` +
+      `A schema change is BREAKING if existing valid Cedar requests could become invalid or if attribute types narrow.\n\n` +
+      `Step 3: Behavioral drift summary.\n` +
+      `If behavioral_test_requests are available in either store, note any decisions that differ between blue and green. ` +
+      `Flag any new Deny decisions that did not exist in blue as HIGH risk.\n\n` +
+      `Step 4: Recommendation.\n` +
+      `Produce a plain-English summary covering: (a) structural changes, (b) breaking schema risk items, ` +
+      `(c) behavioral drift if present, and (d) a clear PROMOTE / DO NOT PROMOTE / PROMOTE WITH CAUTION verdict with reasoning. ` +
+      `No marketing language. Use semicolons instead of dashes for lists. Be specific about which policy IDs drive the verdict.`;
+
+    return {
+      messages: [{ role: "user" as const, content: { type: "text" as const, text } }],
+    };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// 2. cedar-explain-denial
+//
+// UX assumption: a developer got an unexpected Deny (or Allow) and wants a
+// plain-English explanation without needing to know which tools to call or
+// in what order.
+// ---------------------------------------------------------------------------
+const explainDenial = definePrompt({
+  name: "cedar-explain-denial",
+  description:
+    "Explain why a Cedar authorization request was allowed or denied, in plain English, by evaluating the request and examining the deciding policies.",
+  argsSchema: {
+    principal: z.string().describe('Principal entity reference, e.g. MyApp::User::"alice"'),
+    action: z.string().describe('Action entity reference, e.g. MyApp::Action::"read"'),
+    resource: z.string().describe('Resource entity reference, e.g. MyApp::Document::"doc-1"'),
+    store: z.string().describe("Name of the policy store to evaluate against"),
+  },
+  handler: (args) => {
+    const text =
+      `Explain why the following Cedar authorization request was decided the way it was.\n\n` +
+      `Principal: ${args.principal}\n` +
+      `Action:    ${args.action}\n` +
+      `Resource:  ${args.resource}\n` +
+      `Store:     ${args.store}\n\n` +
+      `Work through the following steps.\n\n` +
+      `Step 1: Evaluate.\n` +
+      `Call cedar_authorize with:\n` +
+      `  policy_ref  = "cedar://policies/${args.store}"\n` +
+      `  schema_ref  = "cedar://schema/${args.store}"\n` +
+      `  principal   = "${args.principal}"\n` +
+      `  action      = "${args.action}"\n` +
+      `  resource    = "${args.resource}"\n` +
+      `  entities    = load from "cedar://entities/${args.store}" if available, otherwise use []\n\n` +
+      `Step 2: Explain deciding policies.\n` +
+      `Take the policy IDs returned in determining_policies from Step 1. ` +
+      `Call cedar_explain on those policy IDs so you have the human-readable logic for each one.\n\n` +
+      `Step 3: Plain-English explanation.\n` +
+      `Write a clear explanation covering:\n` +
+      `  (a) The decision (Allow or Deny) and which policy or policies drove it.\n` +
+      `  (b) Why this principal, action, and resource matched or did not match each determining policy.\n` +
+      `  (c) What would need to change for the opposite decision: either a policy edit, an entity attribute change, or a context value.\n\n` +
+      `Keep the explanation factual and specific. Avoid jargon beyond standard Cedar terms (permit, forbid, principal, action, resource, context).`;
+
+    return {
+      messages: [{ role: "user" as const, content: { type: "text" as const, text } }],
+    };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// 3. cedar-avp-migration-checklist
+//
+// UX assumption: the user is preparing to move a local Cedar policy set into
+// Amazon Verified Permissions and wants a guided checklist to avoid easy-to-miss
+// steps (schema format, single-namespace constraint, entity validation).
+// This is purely informational; no tool calls are issued inside the prompt body.
+//
+// Design for "no required args": namespace is optional. When supplied it is
+// substituted into the checklist where AVP requires a single namespace. When
+// omitted a placeholder is used so the checklist is still complete and actionable.
+// ---------------------------------------------------------------------------
+const avpMigrationChecklist = definePrompt({
+  name: "cedar-avp-migration-checklist",
+  description:
+    "Provide a guided checklist for migrating a local Cedar policy set into Amazon Verified Permissions, covering schema format, namespace constraints, entity validation, and behavioral diff.",
+  argsSchema: {
+    namespace: z
+      .string()
+      .optional()
+      .describe(
+        "Optional: the single Cedar namespace your AVP policy store will use, e.g. MyApp"
+      ),
+  },
+  handler: (args) => {
+    const ns = args.namespace ?? "<YourNamespace>";
+
+    const text =
+      `AVP migration checklist for namespace: ${ns}\n\n` +
+      `Work through each item before moving policies or schema into Amazon Verified Permissions.\n\n` +
+      `1. Schema format detection.\n` +
+      `Call cedar_validate_schema on your existing schema file. Note whether it is in Cedar JSON format or .cedarschema (human-readable) format. ` +
+      `AVP accepts both, but they have different upload paths. Confirm which format you have before proceeding.\n\n` +
+      `2. Single-namespace constraint.\n` +
+      `AVP enforces a single namespace per policy store. All entity types, actions, and attributes must live under "${ns}". ` +
+      `If your local Cedar schema uses multiple namespaces, flatten them now. cedar_validate_schema will surface any namespace collisions.\n\n` +
+      `3. Entity format auto-detection.\n` +
+      `Cedar WASM accepts a relaxed entity format; AVP is stricter. Run cedar_validate_entities against your entity set with the schema attached. ` +
+      `Fix any entities missing required attributes or using incorrect UID formats before upload.\n\n` +
+      `4. Template-linked policies.\n` +
+      `If you use policy templates, call cedar_link_template for each template-principal-resource combination to confirm links are valid. ` +
+      `AVP supports template-linked policies but each link must reference a template that already exists in the store.\n\n` +
+      `5. Schema diff before PutSchema.\n` +
+      `If you are updating an existing AVP store schema (not a fresh store), call cedar_diff_schema between your local schema and the current AVP schema. ` +
+      `Classify every change as BREAKING or NON-BREAKING before calling PutSchema. ` +
+      `AVP does not roll back schema changes automatically; a BREAKING change can silently invalidate existing policies.\n\n` +
+      `6. Behavioral diff before traffic shift.\n` +
+      `After loading policies into the AVP store, use cedar_diff_policy_stores to compare local (blue) with AVP (green). ` +
+      `Run any behavioral test cases you have. Confirm no new Deny decisions appear for requests that should be allowed. ` +
+      `Only shift production traffic after this step passes.\n\n` +
+      `All steps must pass before tagging the migration as complete.`;
+
+    return {
+      messages: [{ role: "user" as const, content: { type: "text" as const, text } }],
+    };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Export
+// ---------------------------------------------------------------------------
+
+export const PROMPT_DEFINITIONS: AnyPromptDefinition[] = [
+  reviewPolicyDiff,
+  explainDenial,
+  avpMigrationChecklist,
+];

package/src/resources/ref-resolver.ts

@@ -0,0 +1,134 @@
+/**
+ * Resolves cedar:// resource references to their content.
+ * Allows tools to accept policy_ref / schema_ref as alternatives to inline text.
+ *
+ * URI patterns:
+ *   cedar://policies/{store}                → all policies in store concatenated
+ *   cedar://policies/{store}/{id}           → single policy content
+ *   cedar://schema/{store}                  → schema content
+ *   cedar://templates/{store}               → template ID list as JSON array
+ *   cedar://templates/{store}/{template_id} → single template content
+ *   cedar://template-links/{store}          → link ID list as JSON array
+ *   cedar://template-links/{store}/{link_id}→ single template-link JSON content
+ *   cedar://entities/{store}                → merged entity arrays as JSON
+ *   cedar://entities/{store}/{file_id}      → single entity file content
+ */
+
+import { storeManager } from "./store-manager.js";
+
+export type RefResolution =
+  | { content: string; resolved_from: string }
+  | { error: string };
+
+export function resolveRef(ref: string): RefResolution {
+  const match = ref.match(/^cedar:\/\/(.+)$/);
+  if (!match) return { error: `Invalid cedar:// reference: "${ref}"` };
+
+  const path = match[1]!;
+
+  // cedar://schema/{store}
+  const schemaMatch = path.match(/^schema\/([^/]+)$/);
+  if (schemaMatch) {
+    const storeName = schemaMatch[1]!;
+    try {
+      return { content: storeManager.readSchema(storeName), resolved_from: ref };
+    } catch (e) {
+      return { error: e instanceof Error ? e.message : String(e) };
+    }
+  }
+
+  // cedar://policies/{store}/{policy_id}
+  const singlePolicyMatch = path.match(/^policies\/([^/]+)\/([^/]+)$/);
+  if (singlePolicyMatch) {
+    const storeName = singlePolicyMatch[1]!;
+    const policyId = singlePolicyMatch[2]!;
+    try {
+      return { content: storeManager.readPolicy(storeName, policyId), resolved_from: ref };
+    } catch (e) {
+      return { error: e instanceof Error ? e.message : String(e) };
+    }
+  }
+
+  // cedar://policies/{store}  — all policies concatenated
+  const allPoliciesMatch = path.match(/^policies\/([^/]+)$/);
+  if (allPoliciesMatch) {
+    const storeName = allPoliciesMatch[1]!;
+    try {
+      return { content: storeManager.readAllPolicies(storeName), resolved_from: ref };
+    } catch (e) {
+      return { error: e instanceof Error ? e.message : String(e) };
+    }
+  }
+
+  // cedar://templates/{store}/{template_id}
+  const singleTemplateMatch = path.match(/^templates\/([^/]+)\/([^/]+)$/);
+  if (singleTemplateMatch) {
+    const storeName = singleTemplateMatch[1]!;
+    const templateId = singleTemplateMatch[2]!;
+    try {
+      return { content: storeManager.readTemplate(storeName, templateId), resolved_from: ref };
+    } catch (e) {
+      return { error: e instanceof Error ? e.message : String(e) };
+    }
+  }
+
+  // cedar://templates/{store}  — template ID list as JSON
+  const allTemplatesMatch = path.match(/^templates\/([^/]+)$/);
+  if (allTemplatesMatch) {
+    const storeName = allTemplatesMatch[1]!;
+    try {
+      return { content: JSON.stringify(storeManager.listTemplates(storeName)), resolved_from: ref };
+    } catch (e) {
+      return { error: e instanceof Error ? e.message : String(e) };
+    }
+  }
+
+  // cedar://template-links/{store}/{link_id}
+  const singleLinkMatch = path.match(/^template-links\/([^/]+)\/([^/]+)$/);
+  if (singleLinkMatch) {
+    const storeName = singleLinkMatch[1]!;
+    const linkId = singleLinkMatch[2]!;
+    try {
+      const link = storeManager.readTemplateLink(storeName, linkId);
+      return { content: JSON.stringify(link), resolved_from: ref };
+    } catch (e) {
+      return { error: e instanceof Error ? e.message : String(e) };
+    }
+  }
+
+  // cedar://template-links/{store}  — link ID list as JSON
+  const allLinksMatch = path.match(/^template-links\/([^/]+)$/);
+  if (allLinksMatch) {
+    const storeName = allLinksMatch[1]!;
+    try {
+      return { content: JSON.stringify(storeManager.listTemplateLinks(storeName)), resolved_from: ref };
+    } catch (e) {
+      return { error: e instanceof Error ? e.message : String(e) };
+    }
+  }
+
+  // cedar://entities/{store}/{file_id}
+  const singleEntityMatch = path.match(/^entities\/([^/]+)\/([^/]+)$/);
+  if (singleEntityMatch) {
+    const storeName = singleEntityMatch[1]!;
+    const fileId = singleEntityMatch[2]!;
+    try {
+      return { content: storeManager.readEntities(storeName, fileId), resolved_from: ref };
+    } catch (e) {
+      return { error: e instanceof Error ? e.message : String(e) };
+    }
+  }
+
+  // cedar://entities/{store}  — merged entity arrays as JSON
+  const allEntitiesMatch = path.match(/^entities\/([^/]+)$/);
+  if (allEntitiesMatch) {
+    const storeName = allEntitiesMatch[1]!;
+    try {
+      return { content: storeManager.readAllEntities(storeName), resolved_from: ref };
+    } catch (e) {
+      return { error: e instanceof Error ? e.message : String(e) };
+    }
+  }
+
+  return { error: `Unrecognized cedar:// URI pattern: "${ref}". Supported: cedar://policies/{store}[/{id}], cedar://schema/{store}, cedar://templates/{store}[/{id}], cedar://template-links/{store}[/{id}], cedar://entities/{store}[/{id}]` };
+}

package/src/resources/store-manager.ts

@@ -0,0 +1,248 @@
+/**
+ * StoreManager maps MCP root URIs to named Cedar policy stores.
+ *
+ * Convention for a policy store directory:
+ *   <root>/
+ *     policies/        ← .cedar files, one per policy
+ *     schema.cedarschema  ← Cedar schema text (preferred)
+ *     schema.json         ← Cedar JSON schema (fallback)
+ *
+ * Security: isPathAllowed() checks that any file access stays within a loaded root.
+ * The SDK does not enforce roots automatically — every file operation calls this check.
+ */
+
+import { readdirSync, readFileSync, existsSync } from "node:fs";
+import { join, basename } from "node:path";
+
+export interface PolicyStore {
+  name: string;
+  uri: string;
+  path: string;
+}
+
+export class StoreManager {
+  private stores = new Map<string, PolicyStore>();
+
+  // ─── Store lifecycle ────────────────────────────────────────────────────────
+
+  loadFromRoots(roots: Array<{ uri: string; name?: string }>): void {
+    this.stores.clear();
+    const usedNames = new Map<string, number>(); // tracks how many times each base name is used
+
+    for (const root of roots) {
+      if (!root.uri.startsWith("file://")) {
+        console.error(`[cedar-mcp-server] Skipping unsupported root URI scheme: ${root.uri} (only file:// is supported)`);
+        continue;
+      }
+      const rawPath = root.uri.replace(/^file:\/\//, "").replace(/\/$/, "");
+      // Security: refuse to load a root that resolves to an empty filesystem
+      // path (uri === "file:///" or similar). isPathAllowed below uses
+      // `startsWith(store.path)`, and `<anything>.startsWith("")` is true,
+      // so an empty-path store would silently let every Cedar file operation
+      // touch any path on the filesystem. The fix is defense-in-depth: this
+      // skips at the StoreManager boundary regardless of which caller
+      // (cwd-fallback, --root flag, or client listRoots) produced the URI.
+      if (rawPath.length === 0) {
+        console.error(`[cedar-mcp-server] Refusing to load root with empty path after URI normalization (uri: "${root.uri}"). Filesystem-root URIs (file:///) are unsafe — they would bypass the per-store path sandbox.`);
+        continue;
+      }
+      const baseName = root.name ?? basename(rawPath) ?? "default";
+
+      // Disambiguate collisions with a numeric suffix
+      const count = usedNames.get(baseName) ?? 0;
+      usedNames.set(baseName, count + 1);
+      const name = count === 0 ? baseName : `${baseName}-${count + 1}`;
+
+      if (count > 0) {
+        console.error(`[cedar-mcp-server] Store name collision: "${baseName}" is used by multiple roots. Renamed to "${name}". Consider giving roots explicit names.`);
+      }
+
+      this.stores.set(name, { name, uri: root.uri, path: rawPath });
+    }
+  }
+
+  listStoreNames(): string[] {
+    return [...this.stores.keys()];
+  }
+
+  getStore(name: string): PolicyStore | undefined {
+    return this.stores.get(name);
+  }
+
+  /**
+   * Workspace auto-discovery (10d) helper. Returns:
+   *   - { kind: "none" }       when no stores are loaded.
+   *   - { kind: "single", ... } when exactly one store is loaded.
+   *   - { kind: "ambiguous", names } when multiple stores are loaded and the
+   *     caller did not pass an explicit `store` name to disambiguate.
+   *
+   * Tools call this when a required input ref is missing. Single-store
+   * deployments resolve cleanly; multi-store deployments surface an
+   * actionable error listing the candidates rather than guessing.
+   */
+  getDefaultStore(): { kind: "none" } | { kind: "single"; store: PolicyStore } | { kind: "ambiguous"; names: string[] } {
+    const names = this.listStoreNames();
+    if (names.length === 0) return { kind: "none" };
+    if (names.length === 1) return { kind: "single", store: this.stores.get(names[0]!)! };
+    return { kind: "ambiguous", names };
+  }
+
+  // ─── Policy access ──────────────────────────────────────────────────────────
+
+  listPolicies(storeName: string): string[] {
+    const store = this.requireStore(storeName);
+    const policiesDir = join(store.path, "policies");
+    if (!existsSync(policiesDir)) return [];
+    return readdirSync(policiesDir)
+      .filter((f) => f.endsWith(".cedar"))
+      .map((f) => f.replace(/\.cedar$/, ""))
+      .sort();
+  }
+
+  readPolicy(storeName: string, policyId: string): string {
+    const store = this.requireStore(storeName);
+    // Prevent path traversal — policy IDs must be simple filenames with no slashes or dots
+    if (!/^[a-zA-Z0-9_-]+$/.test(policyId)) {
+      throw new Error(`Invalid policy ID: "${policyId}". Policy IDs must contain only letters, digits, hyphens, and underscores.`);
+    }
+    const filePath = join(store.path, "policies", `${policyId}.cedar`);
+    if (!existsSync(filePath)) {
+      throw new Error(`Policy not found: "${policyId}" in store "${storeName}"`);
+    }
+    return readFileSync(filePath, "utf8");
+  }
+
+  readAllPolicies(storeName: string): string {
+    const ids = this.listPolicies(storeName);
+    return ids.map((id) => this.readPolicy(storeName, id)).join("\n\n");
+  }
+
+  // ─── Template access ────────────────────────────────────────────────────────
+
+  listTemplates(storeName: string): string[] {
+    const store = this.requireStore(storeName);
+    const templatesDir = join(store.path, "templates");
+    if (!existsSync(templatesDir)) return [];
+    return readdirSync(templatesDir)
+      .filter((f) => f.endsWith(".cedar"))
+      .map((f) => f.replace(/\.cedar$/, ""))
+      .sort();
+  }
+
+  readTemplate(storeName: string, templateId: string): string {
+    const store = this.requireStore(storeName);
+    if (!/^[a-zA-Z0-9_-]+$/.test(templateId)) {
+      throw new Error(`Invalid template ID: "${templateId}". Template IDs must contain only letters, digits, hyphens, and underscores.`);
+    }
+    const filePath = join(store.path, "templates", `${templateId}.cedar`);
+    if (!existsSync(filePath)) {
+      throw new Error(`Template not found: "${templateId}" in store "${storeName}"`);
+    }
+    return readFileSync(filePath, "utf8");
+  }
+
+  // ─── Template link access ────────────────────────────────────────────────────
+
+  listTemplateLinks(storeName: string): string[] {
+    const store = this.requireStore(storeName);
+    const linksDir = join(store.path, "template-links");
+    if (!existsSync(linksDir)) return [];
+    return readdirSync(linksDir)
+      .filter((f) => f.endsWith(".json"))
+      .map((f) => f.replace(/\.json$/, ""))
+      .sort();
+  }
+
+  readTemplateLink(storeName: string, linkId: string): { template_id: string; slot_values: Record<string, string> } {
+    const store = this.requireStore(storeName);
+    if (!/^[a-zA-Z0-9_-]+$/.test(linkId)) {
+      throw new Error(`Invalid link ID: "${linkId}". Link IDs must contain only letters, digits, hyphens, and underscores.`);
+    }
+    const filePath = join(store.path, "template-links", `${linkId}.json`);
+    if (!existsSync(filePath)) {
+      throw new Error(`Template link not found: "${linkId}" in store "${storeName}"`);
+    }
+    const raw = readFileSync(filePath, "utf8");
+    return JSON.parse(raw) as { template_id: string; slot_values: Record<string, string> };
+  }
+
+  // ─── Entities access ────────────────────────────────────────────────────────
+
+  listEntities(storeName: string): string[] {
+    const store = this.requireStore(storeName);
+    const entitiesDir = join(store.path, "entities");
+    if (!existsSync(entitiesDir)) return [];
+    return readdirSync(entitiesDir)
+      .filter((f) => f.endsWith(".json"))
+      .map((f) => f.replace(/\.json$/, ""))
+      .sort();
+  }
+
+  readEntities(storeName: string, entityFileId: string): string {
+    const store = this.requireStore(storeName);
+    if (!/^[a-zA-Z0-9_-]+$/.test(entityFileId)) {
+      throw new Error(`Invalid entity file ID: "${entityFileId}". Entity file IDs must contain only letters, digits, hyphens, and underscores.`);
+    }
+    const filePath = join(store.path, "entities", `${entityFileId}.json`);
+    if (!existsSync(filePath)) {
+      throw new Error(`Entity file not found: "${entityFileId}" in store "${storeName}"`);
+    }
+    return readFileSync(filePath, "utf8");
+  }
+
+  readAllEntities(storeName: string): string {
+    const ids = this.listEntities(storeName);
+    const merged: unknown[] = [];
+    for (const id of ids) {
+      const raw = this.readEntities(storeName, id);
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(raw);
+      } catch {
+        throw new Error(`Entity file "${id}" in store "${storeName}" contains invalid JSON.`);
+      }
+      if (!Array.isArray(parsed)) {
+        throw new Error(`Entity file "${id}" in store "${storeName}" must contain a JSON array at the top level, got ${typeof parsed}.`);
+      }
+      merged.push(...parsed);
+    }
+    return JSON.stringify(merged);
+  }
+
+  // ─── Schema access ──────────────────────────────────────────────────────────
+
+  readSchema(storeName: string): string {
+    const store = this.requireStore(storeName);
+    const cedarSchema = join(store.path, "schema.cedarschema");
+    if (existsSync(cedarSchema)) return readFileSync(cedarSchema, "utf8");
+    const jsonSchema = join(store.path, "schema.json");
+    if (existsSync(jsonSchema)) return readFileSync(jsonSchema, "utf8");
+    throw new Error(`Schema not found in store "${storeName}". Expected schema.cedarschema or schema.json at ${store.path}`);
+  }
+
+  // ─── Security ───────────────────────────────────────────────────────────────
+
+  isPathAllowed(filePath: string): boolean {
+    const normalizedRequest = filePath.replace(/\/$/, "");
+    for (const store of this.stores.values()) {
+      if (normalizedRequest.startsWith(store.path)) return true;
+    }
+    return false;
+  }
+
+  // ─── Private ────────────────────────────────────────────────────────────────
+
+  requireStore(name: string): PolicyStore {
+    const store = this.stores.get(name);
+    if (!store) {
+      const available = [...this.stores.keys()].join(", ") || "none";
+      const hint = this.stores.size === 0
+        ? " No roots are configured. Add MCP roots in your client settings, each pointing at a directory with a policies/ subdirectory and a schema.cedarschema or schema.json file."
+        : ` Available stores: ${available}.`;
+      throw new Error(`Store not found: "${name}".${hint}`);
+    }
+    return store;
+  }
+}
+
+export const storeManager = new StoreManager();