cedar-mcp-server 1.0.0

package/src/tools/link-template.ts

@@ -0,0 +1,109 @@
+import { templateToJson, policyToText, policyToJson, validate } from "@cedar-policy/cedar-wasm/nodejs";
+import type { PolicyJson, DetailedError } from "@cedar-policy/cedar-wasm/nodejs";
+
+export interface LinkTemplateInput {
+  template: string;
+  principal?: string;
+  resource?: string;
+  schema?: string;
+}
+
+export interface LinkTemplateResult {
+  linked_policy?: string;
+  slots_bound: Record<string, string>;
+  valid?: boolean;
+  errors?: Array<{ message: string }>;
+  error?: string;
+}
+
+interface EntityRef {
+  type: string;
+  id: string;
+}
+
+function parseEntityRef(ref: string): EntityRef | null {
+  // Expects: "Namespace::Type::\"id\"" or "Type::\"id\""
+  const match = ref.match(/^(.+)::"(.+)"$/);
+  if (!match) return null;
+  return { type: match[1]!, id: match[2]! };
+}
+
+export async function handleLinkTemplate(input: LinkTemplateInput): Promise<LinkTemplateResult> {
+  // Parse the template
+  const parseResult = templateToJson(input.template);
+  if (parseResult.type === "failure") {
+    const msg = parseResult.errors.map(e => e.message).join("; ");
+    return { slots_bound: {}, error: `Failed to parse template: ${msg}` };
+  }
+
+  const json = parseResult.json as unknown as Record<string, unknown>;
+
+  // Determine which slots are present
+  const principalSlot = (json.principal as Record<string, unknown>)?.slot === "?principal";
+  const resourceSlot = (json.resource as Record<string, unknown>)?.slot === "?resource";
+
+  const slots_bound: Record<string, string> = {};
+
+  // Validate that required slots are provided
+  if (principalSlot && !input.principal) {
+    return { slots_bound: {}, error: "Template has a ?principal slot but no principal value was provided." };
+  }
+  if (resourceSlot && !input.resource) {
+    return { slots_bound: {}, error: "Template has a ?resource slot but no resource value was provided." };
+  }
+
+  // Parse and substitute slots
+  const linked = { ...json };
+
+  if (principalSlot && input.principal) {
+    const entity = parseEntityRef(input.principal);
+    if (!entity) {
+      return { slots_bound: {}, error: `Invalid principal entity reference format: "${input.principal}". Expected format: Namespace::Type::"id"` };
+    }
+    linked.principal = { op: "==", entity };
+    slots_bound["?principal"] = input.principal;
+  }
+
+  if (resourceSlot && input.resource) {
+    const entity = parseEntityRef(input.resource);
+    if (!entity) {
+      return { slots_bound: {}, error: `Invalid resource entity reference format: "${input.resource}". Expected format: Namespace::Type::"id"` };
+    }
+    linked.resource = { op: "==", entity };
+    slots_bound["?resource"] = input.resource;
+  }
+
+  // Convert linked JSON to Cedar text
+  const textResult = policyToText(linked as unknown as PolicyJson);
+  if (textResult.type === "failure") {
+    const msg = (textResult.errors as DetailedError[]).map(e => e.message).join("; ");
+    return { slots_bound, error: `Failed to render linked policy: ${msg}` };
+  }
+
+  const linked_policy = textResult.text;
+
+  // Optionally validate the linked policy (now a regular policy, not a template) against schema
+  if (input.schema) {
+    const parsed = policyToJson(linked_policy);
+    if (parsed.type === "failure") {
+      return { linked_policy, slots_bound, valid: false, errors: parsed.errors.map(e => ({ message: e.message })) };
+    }
+    let validateResult: ReturnType<typeof validate>;
+    try {
+      validateResult = validate({ schema: input.schema, policies: { staticPolicies: { p0: parsed.json }, templates: {} } });
+    } catch (e) {
+      return { linked_policy, slots_bound, valid: false, errors: [{ message: e instanceof Error ? e.message : String(e) }] };
+    }
+    if (validateResult.type === "failure") {
+      return { linked_policy, slots_bound, valid: false, errors: validateResult.errors.map(e => ({ message: e.message })) };
+    }
+    return {
+      linked_policy,
+      slots_bound,
+      valid: validateResult.validationErrors.length === 0,
+      errors: validateResult.validationErrors.map(e => ({ message: e.error.message })),
+    };
+  }
+
+  return { linked_policy, slots_bound };
+}

package/src/tools/list-template-links.ts

@@ -0,0 +1,41 @@
+import { storeManager, StoreManager } from "../resources/store-manager.js";
+
+export interface ListTemplateLinksInput {
+  store: string;
+}
+
+export interface TemplateLinkEntry {
+  id: string;
+  template_id: string;
+  slot_values: Record<string, string>;
+}
+
+export interface ListTemplateLinksResult {
+  store: string;
+  links: TemplateLinkEntry[];
+  error?: string;
+}
+
+export async function handleListTemplateLinks(
+  input: ListTemplateLinksInput,
+  manager: StoreManager = storeManager
+): Promise<ListTemplateLinksResult> {
+  let ids: string[];
+  try {
+    ids = manager.listTemplateLinks(input.store);
+  } catch (e) {
+    return { store: input.store, links: [], error: e instanceof Error ? e.message : String(e) };
+  }
+
+  const links: TemplateLinkEntry[] = [];
+  for (const id of ids) {
+    try {
+      const data = manager.readTemplateLink(input.store, id);
+      links.push({ id, template_id: data.template_id, slot_values: data.slot_values });
+    } catch (e) {
+      return { store: input.store, links, error: `Failed to read link "${id}": ${e instanceof Error ? e.message : String(e)}` };
+    }
+  }
+
+  return { store: input.store, links };
+}

package/src/tools/list-templates.ts

@@ -0,0 +1,55 @@
+import { templateToJson } from "@cedar-policy/cedar-wasm/nodejs";
+import type { PolicyJson } from "@cedar-policy/cedar-wasm/nodejs";
+import { storeManager, StoreManager } from "../resources/store-manager.js";
+
+export interface ListTemplatesInput {
+  store: string;
+}
+
+export interface TemplateEntry {
+  id: string;
+  content: string;
+  slots: string[];
+}
+
+export interface ListTemplatesResult {
+  store: string;
+  templates: TemplateEntry[];
+  error?: string;
+}
+
+function detectSlots(json: PolicyJson): string[] {
+  const slots: string[] = [];
+  const p = json.principal as Record<string, unknown>;
+  const r = json.resource as Record<string, unknown>;
+  if (p?.slot === "?principal") slots.push("?principal");
+  if (r?.slot === "?resource") slots.push("?resource");
+  return slots;
+}
+
+export async function handleListTemplates(
+  input: ListTemplatesInput,
+  manager: StoreManager = storeManager
+): Promise<ListTemplatesResult> {
+  let ids: string[];
+  try {
+    ids = manager.listTemplates(input.store);
+  } catch (e) {
+    return { store: input.store, templates: [], error: e instanceof Error ? e.message : String(e) };
+  }
+
+  const templates: TemplateEntry[] = [];
+  for (const id of ids) {
+    let content: string;
+    try {
+      content = manager.readTemplate(input.store, id);
+    } catch (e) {
+      return { store: input.store, templates, error: `Failed to read template "${id}": ${e instanceof Error ? e.message : String(e)}` };
+    }
+    const parsed = templateToJson(content);
+    const slots = parsed.type === "success" ? detectSlots(parsed.json as PolicyJson) : [];
+    templates.push({ id, content, slots });
+  }
+
+  return { store: input.store, templates };
+}

package/src/tools/translate.ts

@@ -0,0 +1,66 @@
+import {
+  policyToJson,
+  policyToText,
+  schemaToJson,
+  schemaToText,
+} from "@cedar-policy/cedar-wasm/nodejs";
+import type { Schema } from "@cedar-policy/cedar-wasm/nodejs";
+
+export interface TranslateInput {
+  input: string;
+  type: "policy" | "schema";
+  direction: "to_json" | "to_cedar";
+}
+
+export interface TranslateResult {
+  output: string | null;
+  error: string | null;
+}
+
+function parseSchemaInput(input: string): Schema {
+  try {
+    return JSON.parse(input);
+  } catch {
+    return input;
+  }
+}
+
+export async function handleTranslate(input: TranslateInput): Promise<TranslateResult> {
+  // per spike-report-wasm-api.md §5-6: function names are policyToJson/policyToText/schemaToJson/schemaToText,
+  // not translate_policy/translate_schema as the design doc assumed
+  if (input.type === "policy") {
+    if (input.direction === "to_json") {
+      const answer = policyToJson(input.input);
+      if (answer.type === "failure") {
+        return { output: null, error: answer.errors.map((e) => e.message).join("; ") };
+      }
+      return { output: JSON.stringify(answer.json, null, 2), error: null };
+    } else {
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(input.input);
+      } catch {
+        return { output: null, error: "Input must be a valid JSON policy object for to_cedar direction" };
+      }
+      const answer = policyToText(parsed as Parameters<typeof policyToText>[0]);
+      if (answer.type === "failure") {
+        return { output: null, error: answer.errors.map((e) => e.message).join("; ") };
+      }
+      return { output: answer.text, error: null };
+    }
+  } else {
+    if (input.direction === "to_json") {
+      const answer = schemaToJson(parseSchemaInput(input.input));
+      if (answer.type === "failure") {
+        return { output: null, error: answer.errors.map((e) => e.message).join("; ") };
+      }
+      return { output: JSON.stringify(answer.json, null, 2), error: null };
+    } else {
+      const answer = schemaToText(parseSchemaInput(input.input));
+      if (answer.type === "failure") {
+        return { output: null, error: answer.errors.map((e) => e.message).join("; ") };
+      }
+      return { output: answer.text, error: null };
+    }
+  }
+}

package/src/tools/validate-entities.ts

@@ -0,0 +1,125 @@
+import { checkParseEntities } from "@cedar-policy/cedar-wasm/nodejs";
+import type { Schema, Entities } from "@cedar-policy/cedar-wasm/nodejs";
+
+export interface ValidateEntitiesInput {
+  entities: string;
+  schema?: string;
+}
+
+export type EntityErrorKind =
+  | "unknown_type"
+  | "missing_required_attribute"
+  | "type_mismatch"
+  | "unknown_attribute"
+  | "disallowed_parent_type"
+  | "parse_error"
+  | "other";
+
+export interface EntityError {
+  entity_uid: string;
+  error_kind: EntityErrorKind;
+  message: string;
+  attribute?: string;
+}
+
+export interface ValidateEntitiesResult {
+  valid: boolean;
+  entity_count: number;
+  errors: EntityError[];
+}
+
+function parseSchema(schemaStr: string | undefined): Schema | undefined {
+  if (!schemaStr) return undefined;
+  try {
+    return JSON.parse(schemaStr);
+  } catch {
+    return schemaStr;
+  }
+}
+
+// Each regex captures: 1) entity_uid (everything between backticks), 2) attribute name when present.
+const RE_TYPE_MISMATCH = /in attribute `([^`]+)` on `([^`]+)`, type mismatch/;
+const RE_MISSING_REQUIRED = /expected entity `([^`]+)` to have attribute `([^`]+)`, but it does not/;
+const RE_UNKNOWN_TYPE = /entity `([^`]+)` has type `[^`]+` which is not declared in the schema/;
+const RE_UNKNOWN_ATTR = /attribute `([^`]+)` on `([^`]+)` should not exist according to the schema/;
+const RE_DISALLOWED_PARENT = /`([^`]+)` is not allowed to have an ancestor of type `[^`]+` according to the schema/;
+
+export function classifyError(message: string): EntityError {
+  let m: RegExpMatchArray | null;
+
+  if ((m = message.match(RE_TYPE_MISMATCH))) {
+    return { entity_uid: m[2], error_kind: "type_mismatch", attribute: m[1], message };
+  }
+  if ((m = message.match(RE_MISSING_REQUIRED))) {
+    return {
+      entity_uid: m[1],
+      error_kind: "missing_required_attribute",
+      attribute: m[2],
+      message,
+    };
+  }
+  if ((m = message.match(RE_UNKNOWN_TYPE))) {
+    return { entity_uid: m[1], error_kind: "unknown_type", message };
+  }
+  if ((m = message.match(RE_UNKNOWN_ATTR))) {
+    return { entity_uid: m[2], error_kind: "unknown_attribute", attribute: m[1], message };
+  }
+  if ((m = message.match(RE_DISALLOWED_PARENT))) {
+    return { entity_uid: m[1], error_kind: "disallowed_parent_type", message };
+  }
+
+  return {
+    entity_uid: "",
+    error_kind: "other",
+    message: `[unrecognized error pattern; the regex classifier did not match this message, so error_kind defaulted to "other"] ${message}`,
+  };
+}
+
+export async function handleValidateEntities(
+  input: ValidateEntitiesInput
+): Promise<ValidateEntitiesResult> {
+  // 1. Parse entities JSON
+  let entities: unknown;
+  try {
+    entities = JSON.parse(input.entities);
+  } catch (e) {
+    return {
+      valid: false,
+      entity_count: 0,
+      errors: [
+        {
+          entity_uid: "",
+          error_kind: "parse_error",
+          message: `Entities JSON failed to parse: ${e instanceof Error ? e.message : String(e)}`,
+        },
+      ],
+    };
+  }
+
+  if (!Array.isArray(entities)) {
+    return {
+      valid: false,
+      entity_count: 0,
+      errors: [
+        {
+          entity_uid: "",
+          error_kind: "parse_error",
+          message: "Entities must be a JSON array of entity objects",
+        },
+      ],
+    };
+  }
+
+  const entity_count = entities.length;
+  const schema = parseSchema(input.schema);
+
+  const call = schema ? { entities: entities as Entities, schema } : { entities: entities as Entities };
+  const answer = checkParseEntities(call);
+
+  if (answer.type === "success") {
+    return { valid: true, entity_count, errors: [] };
+  }
+
+  const errors = answer.errors.map((e) => classifyError(e.message));
+  return { valid: false, entity_count, errors };
+}

package/src/tools/validate-schema.ts

@@ -0,0 +1,128 @@
+import { checkParseSchema } from "@cedar-policy/cedar-wasm/nodejs";
+import type { Schema } from "@cedar-policy/cedar-wasm/nodejs";
+
+export interface ValidateSchemaInput {
+  schema: string;
+}
+
+export interface SchemaParseError {
+  message: string;
+  source_location?: { start: number; end: number; label?: string | null };
+}
+
+export interface ValidateSchemaResult {
+  valid: boolean;
+  format: "json" | "cedarschema";
+  namespaces: string[];
+  entity_type_count: number;
+  action_count: number;
+  common_type_count: number;
+  errors: SchemaParseError[];
+}
+
+function parseSchemaInput(schemaStr: string): { schema: Schema; format: "json" | "cedarschema" } {
+  try {
+    return { schema: JSON.parse(schemaStr), format: "json" };
+  } catch {
+    return { schema: schemaStr, format: "cedarschema" };
+  }
+}
+
+interface JsonSchemaShape {
+  [namespace: string]: {
+    entityTypes?: Record<string, unknown>;
+    actions?: Record<string, unknown>;
+    commonTypes?: Record<string, unknown>;
+  };
+}
+
+function summarizeJsonSchema(json: unknown): {
+  namespaces: string[];
+  entity_type_count: number;
+  action_count: number;
+  common_type_count: number;
+} {
+  const empty = { namespaces: [], entity_type_count: 0, action_count: 0, common_type_count: 0 };
+  if (!json || typeof json !== "object") return empty;
+  const shape = json as JsonSchemaShape;
+
+  const namespaces = Object.keys(shape);
+  let entity_type_count = 0;
+  let action_count = 0;
+  let common_type_count = 0;
+
+  for (const ns of namespaces) {
+    const block = shape[ns];
+    if (block.entityTypes) entity_type_count += Object.keys(block.entityTypes).length;
+    if (block.actions) action_count += Object.keys(block.actions).length;
+    if (block.commonTypes) common_type_count += Object.keys(block.commonTypes).length;
+  }
+
+  return { namespaces, entity_type_count, action_count, common_type_count };
+}
+
+export async function handleValidateSchema(
+  input: ValidateSchemaInput
+): Promise<ValidateSchemaResult> {
+  if (!input.schema || input.schema.trim() === "") {
+    return {
+      valid: false,
+      format: "cedarschema",
+      namespaces: [],
+      entity_type_count: 0,
+      action_count: 0,
+      common_type_count: 0,
+      errors: [{ message: "Schema input is empty" }],
+    };
+  }
+
+  const { schema, format } = parseSchemaInput(input.schema);
+  const answer = checkParseSchema(schema);
+
+  if (answer.type === "failure") {
+    return {
+      valid: false,
+      format,
+      namespaces: [],
+      entity_type_count: 0,
+      action_count: 0,
+      common_type_count: 0,
+      errors: answer.errors.map((e) => ({
+        message: e.message,
+        ...(e.sourceLocations && e.sourceLocations.length > 0
+          ? { source_location: { start: e.sourceLocations[0].start, end: e.sourceLocations[0].end, label: e.sourceLocations[0].label } }
+          : {}),
+      })),
+    };
+  }
+
+  if (format === "json") {
+    const summary = summarizeJsonSchema(schema);
+    return { valid: true, format, ...summary, errors: [] };
+  }
+
+  // For cedarschema text, derive summary by translating to JSON form.
+  // schemaToJsonWithResolvedTypes only accepts string input (per spike-report §"Schema standalone ops spike").
+  if (typeof schema === "string") {
+    try {
+      const { schemaToJsonWithResolvedTypes } = await import("@cedar-policy/cedar-wasm/nodejs");
+      const jsonAnswer = schemaToJsonWithResolvedTypes(schema);
+      if (jsonAnswer.type === "success") {
+        const summary = summarizeJsonSchema(jsonAnswer.json);
+        return { valid: true, format, ...summary, errors: [] };
+      }
+    } catch {
+      // fall through to summary-less success
+    }
+  }
+
+  return {
+    valid: true,
+    format,
+    namespaces: [],
+    entity_type_count: 0,
+    action_count: 0,
+    common_type_count: 0,
+    errors: [],
+  };
+}

package/src/tools/validate-template.ts

@@ -0,0 +1,72 @@
+import { templateToJson, validate } from "@cedar-policy/cedar-wasm/nodejs";
+import type { PolicyJson, Schema } from "@cedar-policy/cedar-wasm/nodejs";
+
+function parseSchema(schemaStr: string): Schema {
+  try { return JSON.parse(schemaStr); } catch { return schemaStr; }
+}
+
+export interface ValidateTemplateInput {
+  template: string;
+  schema: string;
+}
+
+export interface ValidateTemplateResult {
+  valid: boolean;
+  errors: Array<{ message: string; help?: string }>;
+  warnings: Array<{ message: string }>;
+  slots_detected: string[];
+  error?: string;
+}
+
+function detectSlots(json: PolicyJson): string[] {
+  const slots: string[] = [];
+  const p = json.principal as Record<string, unknown>;
+  const r = json.resource as Record<string, unknown>;
+  if (p?.slot === "?principal") slots.push("?principal");
+  if (r?.slot === "?resource") slots.push("?resource");
+  return slots;
+}
+
+export async function handleValidateTemplate(input: ValidateTemplateInput): Promise<ValidateTemplateResult> {
+  if (!input.schema?.trim()) {
+    return { valid: false, errors: [], warnings: [], slots_detected: [], error: "schema is required" };
+  }
+
+  // Parse the template
+  const parseResult = templateToJson(input.template);
+  if (parseResult.type === "failure") {
+    return {
+      valid: false,
+      errors: parseResult.errors.map(e => ({ message: e.message })),
+      warnings: [],
+      slots_detected: [],
+    };
+  }
+
+  const slots_detected = detectSlots(parseResult.json as PolicyJson);
+
+  // Validate against schema using the JSON policy struct format with templates key
+  const templateId = "t0";
+  let validateResult: ReturnType<typeof validate>;
+  try {
+    validateResult = validate({ schema: parseSchema(input.schema), policies: { staticPolicies: {}, templates: { [templateId]: parseResult.json } } });
+  } catch (e) {
+    return { valid: false, errors: [{ message: e instanceof Error ? e.message : String(e) }], warnings: [], slots_detected };
+  }
+
+  if (validateResult.type === "failure") {
+    return {
+      valid: false,
+      errors: validateResult.errors.map(e => ({ message: e.message, help: e.help ?? undefined })),
+      warnings: [],
+      slots_detected,
+    };
+  }
+
+  return {
+    valid: validateResult.validationErrors.length === 0,
+    errors: validateResult.validationErrors.map(e => ({ message: e.error.message, help: e.error.help ?? undefined })),
+    warnings: validateResult.validationWarnings.map(w => ({ message: w.error.message })),
+    slots_detected,
+  };
+}