@intentius/chant-lexicon-cedar 0.44.8

package/src/import/parser.test.ts

@@ -0,0 +1,265 @@
+import { describe, test, expect } from "vitest";
+import { readFileSync } from "fs";
+import { join } from "path";
+import { CedarParser, isPolicySetEnvelope } from "./parser";
+import { extractClauses } from "./clause-text";
+
+const testdata = (file: string) => readFileSync(join(import.meta.dirname, "testdata", file), "utf8");
+
+const parse = (content: string) => new CedarParser().parse(content);
+
+/** The one policy in a single-policy document. */
+const only = (content: string) => {
+  const { entities } = parse(content);
+  expect(entities).toHaveLength(1);
+  return entities[0];
+};
+
+const byName = (content: string, name: string) => {
+  const found = parse(content).entities.find((e) => e.name === name);
+  if (!found) throw new Error(`no policy named ${name}`);
+  return found;
+};
+
+// ── 1–4. Scope constraints ─────────────────────────────────────────
+
+describe("scope constraints", () => {
+  test("1. `== E` becomes an eq scope carrying the full entity UID", () => {
+    expect(only(testdata("simple.cedar")).props.principal).toEqual({ eq: 'App::User::"alice"' });
+  });
+
+  test("2. `is T` becomes an is scope", () => {
+    expect(only(testdata("simple.cedar")).props.resource).toEqual({ is: "App::Document" });
+  });
+
+  test("3. `is T in E` keeps both halves", () => {
+    expect(byName(testdata("full.cedar"), "full-grant").props.principal).toEqual({
+      is: "App::User",
+      in: 'App::Group::"engineering"',
+    });
+  });
+
+  test("4. an action set becomes an in scope with an array", () => {
+    expect(byName(testdata("realistic.cedar"), "owner-read").props.action).toEqual({
+      in: ['App::Action::"read"', 'App::Action::"list"'],
+    });
+  });
+
+  test("a one-element action set is Cedar's own normalization, not a lost prop", () => {
+    // `action in [X]` and `action in X` are the same constraint, and the module
+    // collapses the first into the second before this file ever sees it — so a
+    // round-trip rewrites the brackets away and cannot be made not to.
+    const { entities } = parse('@id("one") permit (principal, action in [App::Action::"read"], resource);');
+    expect(entities[0].props.action).toEqual({ in: 'App::Action::"read"' });
+  });
+});
+
+// ── 5–6. Effects and unconstrained scopes ──────────────────────────
+
+describe("effect and defaults", () => {
+  test("5. forbid is captured as the effect", () => {
+    expect(byName(testdata("full.cedar"), "deny-anonymous").props.effect).toBe("forbid");
+  });
+
+  test("6. an unconstrained scope is left out — `{}` and absent are one value", () => {
+    const props = byName(testdata("full.cedar"), "deny-anonymous").props;
+    expect(props.principal).toBeUndefined();
+    expect(props.action).toBeUndefined();
+    expect(props.resource).toBeUndefined();
+    expect(Object.keys(props)).toEqual(["effect", "annotations"]);
+  });
+});
+
+// ── 7–9. Conditions ────────────────────────────────────────────────
+
+describe("conditions", () => {
+  test("7. a when clause survives as the text it was written as", () => {
+    expect(byName(testdata("realistic.cedar"), "owner-read").props.when).toEqual([
+      "resource.owner == principal",
+    ]);
+  });
+
+  test("8. when and unless are captured separately, each in order", () => {
+    const props = byName(testdata("full.cedar"), "full-grant").props;
+    expect(props.when).toEqual([
+      "resource.owner == principal && context.mfa == true",
+      'principal.department == "eng"',
+    ]);
+    expect(props.unless).toEqual([
+      'resource.classification == "secret"',
+      'context.ip.isInRange(ip("10.0.0.0/8"))',
+    ]);
+  });
+
+  test("9. braces inside a string literal do not end the clause", () => {
+    expect(byName(testdata("full.cedar"), "quoted-note").props.when).toEqual([
+      'context.note == "a } b { c"',
+    ]);
+  });
+});
+
+// ── 10–11. Annotations ─────────────────────────────────────────────
+
+describe("annotations", () => {
+  test("10. every annotation is captured, including the id", () => {
+    expect(byName(testdata("full.cedar"), "full-grant").props.annotations).toEqual({
+      doc: "Everything the authoring model can carry, in one policy.",
+      id: "full-grant",
+      owner: "platform",
+      ticket: "SEC-12",
+    });
+  });
+
+  test("11. escapes in an annotation value are decoded, not carried as source", () => {
+    expect(byName(testdata("full.cedar"), "quoted-note").props.annotations).toMatchObject({
+      note: 'say "hi" \\ done',
+    });
+  });
+});
+
+// ── 12–13. Templates and document shape ────────────────────────────
+
+describe("templates", () => {
+  test("12. a policy with slots is read as a template, with the slots kept", () => {
+    const template = byName(testdata("full.cedar"), "share-with-slots");
+    expect(template.kind).toBe("template");
+    expect(template.props.principal).toEqual({ eq: "?principal" });
+    expect(template.props.resource).toEqual({ in: "?resource" });
+  });
+
+  test("13. static policies and templates come back from one document", () => {
+    const { entities } = parse(testdata("full.cedar"));
+    expect(entities.map((e) => `${e.kind}:${e.name}`)).toEqual([
+      "policy:full-grant",
+      "policy:deny-anonymous",
+      "policy:quoted-note",
+      "template:share-with-slots",
+    ]);
+  });
+});
+
+// ── 14–16. The JSON policy-set envelope ────────────────────────────
+
+describe("the JSON policy-set envelope", () => {
+  test("14. an envelope parses to the same policies as the text beside it", () => {
+    const fromText = parse(testdata("full.cedar")).entities;
+    const fromJSON = parse(testdata("full.cedar.json")).entities;
+    expect(fromJSON.map((e) => `${e.kind}:${e.name}`)).toEqual(fromText.map((e) => `${e.kind}:${e.name}`));
+    expect(fromJSON[0].props.annotations).toEqual(fromText[0].props.annotations);
+  });
+
+  test("15. an envelope's conditions come back re-rendered, since there is no source to quote", () => {
+    const props = parse(testdata("full.cedar.json")).entities[0].props;
+    // Semantically the same clause as the text fixture's, defensively
+    // parenthesized on the way out of the module (#1648 §1).
+    expect(props.when).toEqual([
+      "((resource.owner) == principal) && ((context.mfa) == true)",
+      '(principal.department) == "eng"',
+    ]);
+  });
+
+  test("16. template links are reported rather than silently dropped", () => {
+    const { warnings } = parse(
+      JSON.stringify({
+        staticPolicies: {},
+        templates: {
+          t: {
+            effect: "permit",
+            principal: { op: "==", slot: "?principal" },
+            action: { op: "All" },
+            resource: { op: "All" },
+            conditions: [],
+            annotations: { id: "t" },
+          },
+        },
+        templateLinks: [{ templateId: "t", newId: "t0", values: { "?principal": { type: "App::User", id: "a" } } }],
+      }),
+    );
+    expect(warnings.join(" ")).toContain("template link(s) were not imported");
+  });
+
+  test("an envelope keyed by id names the policy even without an @id annotation", () => {
+    const { entities } = parse(
+      JSON.stringify({
+        staticPolicies: {
+          "from-the-key": {
+            effect: "permit",
+            principal: { op: "All" },
+            action: { op: "All" },
+            resource: { op: "All" },
+            conditions: [],
+          },
+        },
+      }),
+    );
+    expect(entities.map((e) => e.name)).toEqual(["from-the-key"]);
+  });
+
+  test("staticPolicies given as raw Cedar text is read as text", () => {
+    const { entities } = parse(JSON.stringify({ staticPolicies: testdata("simple.cedar") }));
+    expect(entities.map((e) => e.name)).toEqual(["allow-alice-read"]);
+  });
+});
+
+// ── 17–18. Document-level behaviour ────────────────────────────────
+
+describe("documents", () => {
+  test("17. an empty document produces no entities and no noise", () => {
+    expect(parse("   \n  ")).toEqual({ entities: [], warnings: [] });
+  });
+
+  test("18. text the module rejects raises rather than importing half a policy", () => {
+    expect(() => parse("this is not cedar")).toThrow(/could not parse the policy document/);
+  });
+
+  test("comments are dropped — they are in no grammar the module round-trips", () => {
+    const { entities } = parse(`// a note about alice\n${testdata("simple.cedar")}`);
+    expect(entities).toHaveLength(1);
+    expect(JSON.stringify(entities[0].props)).not.toContain("a note about alice");
+  });
+});
+
+// ── The envelope shape test ────────────────────────────────────────
+
+describe("isPolicySetEnvelope", () => {
+  test("accepts the serializer's own document", () => {
+    expect(isPolicySetEnvelope(JSON.parse(testdata("full.cedar.json")))).toBe(true);
+  });
+
+  test("rejects a document carrying keys Cedar has never heard of", () => {
+    expect(isPolicySetEnvelope({ apiVersion: "v1", kind: "Pod" })).toBe(false);
+    expect(isPolicySetEnvelope({ staticPolicies: {}, Resources: {} })).toBe(false);
+    expect(isPolicySetEnvelope([])).toBe(false);
+    expect(isPolicySetEnvelope(null)).toBe(false);
+    expect(isPolicySetEnvelope({ templateLinks: [] })).toBe(false);
+  });
+});
+
+// ── The clause scanner on its own ──────────────────────────────────
+
+describe("extractClauses", () => {
+  test("returns the bodies of every clause, in order", () => {
+    expect(
+      extractClauses('@id("x")\npermit (principal, action, resource)\nwhen { a == 1 }\nunless { b };'),
+    ).toEqual([
+      { kind: "when", body: "a == 1" },
+      { kind: "unless", body: "b" },
+    ]);
+  });
+
+  test("an annotation's parentheses are not mistaken for the scope's", () => {
+    expect(extractClauses('@doc("(not the scope)")\npermit (principal, action, resource);')).toEqual([]);
+  });
+
+  test("a comment inside a clause is skipped, braces and all", () => {
+    expect(extractClauses("permit (principal, action, resource)\nwhen {\n  // } not the end\n  a\n};")).toEqual([
+      { kind: "when", body: "// } not the end\n  a" },
+    ]);
+  });
+
+  test("gives up rather than guessing at anything it does not recognize", () => {
+    expect(extractClauses("permit (principal, action, resource) when { unbalanced ;")).toBeNull();
+    expect(extractClauses("allow (principal, action, resource);")).toBeNull();
+    expect(extractClauses("permit (principal, action, resource); trailing")).toBeNull();
+  });
+});

package/src/import/parser.ts

@@ -0,0 +1,352 @@
+/**
+ * Cedar policy parser for `chant import`.
+ *
+ * Two surfaces come in and one IR goes out:
+ *
+ * - **`.cedar` policy text** — split by `policySetTextToParts`, then each
+ *   policy handed to `policyToJson` (or `templateToJson`, for one carrying a
+ *   slot). The Cedar grammar is never touched here; the module owns it.
+ * - **the JSON policy-set envelope** the serializer writes beside the text —
+ *   `{ staticPolicies, templates, templateLinks }`, whose values are already
+ *   in Cedar's JSON policy format.
+ *
+ * The IR is lossless with respect to the authoring model: effect, all three
+ * scopes, every `when`/`unless` clause in order, and every annotation. What is
+ * *not* in the model is not invented — Cedar comments are dropped by the
+ * module before this file sees them, and template links have no authoring
+ * shape yet, so they are reported as a warning rather than silently discarded.
+ *
+ * Unconstrained scopes are the one thing left out of `props`, because `{}` and
+ * absent are the same value to the serializer (`principal` with no constraint).
+ * Writing `principal: {}` into every imported policy would be noise, not
+ * fidelity.
+ */
+
+import {
+  policyToJson,
+  policyToText,
+  splitPolicySet,
+  templateToJson,
+  type PolicyJson,
+} from "../spec/wasm";
+import { escapeCedarString, type CedarScope } from "../serializer";
+import { extractClauses } from "./clause-text";
+
+// ── IR ────────────────────────────────────────────────────────────
+
+/**
+ * Whether Cedar read this as a static policy or as a template.
+ *
+ * The discriminant is not chant's: a policy is a template exactly when it
+ * carries a `?principal`/`?resource` slot, and `policyToJson` refuses one.
+ */
+export type CedarEntityKind = "policy" | "template";
+
+/** One imported Cedar policy, in the lossless intermediate shape. */
+export interface CedarPolicyIR {
+  kind: CedarEntityKind;
+  /** The Cedar policy id — its `@id`, or the envelope key it was filed under. */
+  name: string;
+  /** The `Cedar::Policy` props, ready to hand to the authoring class. */
+  props: Record<string, unknown>;
+}
+
+export interface CedarParseResult {
+  entities: CedarPolicyIR[];
+  warnings: string[];
+}
+
+// ── PolicyJson → props ────────────────────────────────────────────
+
+type EntityUidJson = { __entity: { type: string; id: string } } | { type: string; id: string };
+
+/** `{ type: "App::User", id: "alice" }` → `App::User::"alice"`. */
+function uidText(uid: EntityUidJson): string {
+  const parts = "__entity" in uid ? uid.__entity : uid;
+  return `${parts.type}::"${escapeCedarString(parts.id)}"`;
+}
+
+/**
+ * One scope constraint, back to the authoring form.
+ *
+ * `undefined` is the unconstrained case — see the note at the top of the file
+ * about why it is omitted rather than written as `{}`.
+ */
+function scopeProps(constraint: unknown): CedarScope | undefined {
+  if (!constraint || typeof constraint !== "object") return undefined;
+  const scope = constraint as Record<string, unknown>;
+
+  const inTarget = (value: unknown): string | string[] | undefined => {
+    if (!value || typeof value !== "object") return undefined;
+    const target = value as Record<string, unknown>;
+    if (typeof target.slot === "string") return target.slot;
+    if (Array.isArray(target.entities)) return target.entities.map((e) => uidText(e as EntityUidJson));
+    if (target.entity) return uidText(target.entity as EntityUidJson);
+    return undefined;
+  };
+
+  switch (scope.op) {
+    case "is": {
+      if (typeof scope.entity_type !== "string") return undefined;
+      const within = inTarget(scope.in);
+      return within === undefined ? { is: scope.entity_type } : { is: scope.entity_type, in: within };
+    }
+    case "==":
+      if (typeof scope.slot === "string") return { eq: scope.slot };
+      return scope.entity ? { eq: uidText(scope.entity as EntityUidJson) } : undefined;
+    case "in": {
+      const within = inTarget(scope);
+      return within === undefined ? undefined : { in: within };
+    }
+    default:
+      // `All`, and anything a later Cedar version adds that this does not know.
+      return undefined;
+  }
+}
+
+/**
+ * Render one condition body back to Cedar text through the module.
+ *
+ * There is no entry point that renders an expression on its own, so the body
+ * is wrapped in the most boring policy that can hold it and the wrapper is
+ * sliced back off. The wrapper is the module's own output, so its shape is
+ * fixed: `permit(principal, action, resource) when { … };`.
+ */
+function renderConditionBody(kind: "when" | "unless", body: unknown): string | undefined {
+  const probe = {
+    effect: "permit",
+    principal: { op: "All" },
+    action: { op: "All" },
+    resource: { op: "All" },
+    conditions: [{ kind, body }],
+  } as unknown as PolicyJson;
+
+  const rendered = policyToText(probe);
+  if (!rendered.ok) return undefined;
+
+  const opening = `${kind} { `;
+  const start = rendered.value.indexOf(opening);
+  if (start < 0 || !rendered.value.endsWith(" };")) return undefined;
+  return rendered.value.slice(start + opening.length, -3);
+}
+
+/** Re-parse one clause body and return the tree the module makes of it. */
+function parseConditionBody(body: string): unknown {
+  const parsed = policyToJson(`permit (principal, action, resource) when { ${body} };`);
+  return parsed.ok ? parsed.value.conditions[0]?.body : undefined;
+}
+
+/**
+ * The `when` and `unless` clause texts, in order.
+ *
+ * Verbatim source wins when there is source to quote and the module agrees it
+ * means the same thing; otherwise the rendered form is used. `policyToJson`
+ * serializes deterministically with sorted keys (#1648 §5.2), so comparing two
+ * of its trees by their JSON text is sound.
+ */
+function conditionProps(
+  json: PolicyJson,
+  sourceText: string | undefined,
+): { when: string[]; unless: string[]; warnings: string[] } {
+  const conditions = json.conditions ?? [];
+  const warnings: string[] = [];
+
+  const source = sourceText ? extractClauses(sourceText) : null;
+  const usable = source !== null && source.length === conditions.length ? source : null;
+
+  const when: string[] = [];
+  const unless: string[] = [];
+
+  for (const [index, condition] of conditions.entries()) {
+    const candidate = usable?.[index];
+    let text: string | undefined;
+
+    if (
+      candidate &&
+      candidate.kind === condition.kind &&
+      JSON.stringify(parseConditionBody(candidate.body)) === JSON.stringify(condition.body)
+    ) {
+      text = candidate.body;
+    } else {
+      text = renderConditionBody(condition.kind, condition.body);
+    }
+
+    if (text === undefined) {
+      warnings.push(`a ${condition.kind} clause could not be rendered back to Cedar text and was dropped`);
+      continue;
+    }
+
+    (condition.kind === "when" ? when : unless).push(text);
+  }
+
+  return { when, unless, warnings };
+}
+
+/**
+ * One `PolicyJson` as `Cedar::Policy` props.
+ *
+ * Key order matches the props interface, so the generator's `JSON.stringify`
+ * emits policies that read the way they would have been written.
+ */
+function policyProps(
+  json: PolicyJson,
+  sourceText: string | undefined,
+): { props: Record<string, unknown>; warnings: string[] } {
+  const props: Record<string, unknown> = { effect: json.effect === "forbid" ? "forbid" : "permit" };
+
+  const principal = scopeProps(json.principal);
+  if (principal) props.principal = principal;
+  const action = scopeProps(json.action);
+  if (action) props.action = action;
+  const resource = scopeProps(json.resource);
+  if (resource) props.resource = resource;
+
+  const { when, unless, warnings } = conditionProps(json, sourceText);
+  if (when.length > 0) props.when = when;
+  if (unless.length > 0) props.unless = unless;
+
+  const annotations = json.annotations ?? {};
+  if (Object.keys(annotations).length > 0) props.annotations = { ...annotations };
+
+  return { props, warnings };
+}
+
+/** The id a policy answers to: its own `@id` first, then where it was filed. */
+function policyId(json: PolicyJson, fallback: string): string {
+  const annotated = json.annotations?.id;
+  return typeof annotated === "string" && annotated.length > 0 ? annotated : fallback;
+}
+
+// ── Envelope shape ────────────────────────────────────────────────
+
+const ENVELOPE_KEYS = new Set(["staticPolicies", "templates", "templateLinks"]);
+
+/**
+ * Is this the JSON policy-set envelope?
+ *
+ * Deliberately strict about foreign keys: a CloudFormation template or a
+ * Kubernetes manifest must not walk in through a permissive shape test, and
+ * `detect.ts` leans on the same rule.
+ */
+export function isPolicySetEnvelope(data: unknown): data is Record<string, unknown> {
+  if (!data || typeof data !== "object" || Array.isArray(data)) return false;
+  const keys = Object.keys(data);
+  if (keys.length === 0) return false;
+  if (!keys.every((key) => ENVELOPE_KEYS.has(key))) return false;
+  return "staticPolicies" in data || "templates" in data;
+}
+
+/** Normalize the three shapes `staticPolicies` is allowed to take into pairs. */
+function envelopeEntries(value: unknown, fallbackPrefix: string): Array<[string, unknown]> {
+  if (Array.isArray(value)) return value.map((entry, index) => [`${fallbackPrefix}${index}`, entry]);
+  if (value && typeof value === "object") return Object.entries(value as Record<string, unknown>);
+  return [];
+}
+
+// ── Parser ────────────────────────────────────────────────────────
+
+export class CedarParser {
+  parse(content: string): CedarParseResult {
+    if (!content.trim()) return { entities: [], warnings: [] };
+
+    const asJSON = tryParseJSON(content);
+    if (isPolicySetEnvelope(asJSON)) return this.parseEnvelope(asJSON);
+
+    return this.parseText(content);
+  }
+
+  // ── `.cedar` text ───────────────────────────────────────────────
+
+  private parseText(content: string): CedarParseResult {
+    const parts = splitPolicySet(content);
+    if (!parts.ok) throw new Error(`cedar: could not parse the policy document — ${parts.error}`);
+
+    const entities: CedarPolicyIR[] = [];
+    const warnings: string[] = [];
+
+    const collect = (
+      sources: string[],
+      kind: CedarEntityKind,
+      convert: (source: string) => ReturnType<typeof policyToJson>,
+      fallbackPrefix: string,
+    ): void => {
+      for (const [index, source] of sources.entries()) {
+        const converted = convert(source);
+        if (!converted.ok) {
+          warnings.push(`skipped a ${kind} that did not convert: ${converted.error}`);
+          continue;
+        }
+        entities.push(this.toIR(kind, converted.value, `${fallbackPrefix}${index}`, source, warnings));
+      }
+    };
+
+    collect(parts.value.policies, "policy", policyToJson, "policy");
+    collect(parts.value.templates, "template", templateToJson, "template");
+
+    return { entities, warnings };
+  }
+
+  // ── JSON policy-set envelope ────────────────────────────────────
+
+  private parseEnvelope(envelope: Record<string, unknown>): CedarParseResult {
+    // `staticPolicies` is allowed to be one blob of `.cedar` text, in which
+    // case the whole envelope is the text surface wearing a wrapper — templates
+    // and all, since the text is what says which is which.
+    const asText = typeof envelope.staticPolicies === "string" ? this.parseText(envelope.staticPolicies) : null;
+
+    const entities: CedarPolicyIR[] = [...(asText?.entities ?? [])];
+    const warnings: string[] = [...(asText?.warnings ?? [])];
+
+    const collect = (
+      value: unknown,
+      kind: CedarEntityKind,
+      convert: (source: string | PolicyJson) => ReturnType<typeof policyToJson>,
+      fallbackPrefix: string,
+    ): void => {
+      for (const [key, entry] of envelopeEntries(value, fallbackPrefix)) {
+        const converted = convert(entry as string | PolicyJson);
+        if (!converted.ok) {
+          warnings.push(`skipped ${kind} \`${key}\`: ${converted.error}`);
+          continue;
+        }
+        // A policy given as text carries its own layout; one given as JSON has
+        // none to quote, and its conditions come back as the module renders them.
+        const source = typeof entry === "string" ? entry : undefined;
+        entities.push(this.toIR(kind, converted.value, key, source, warnings));
+      }
+    };
+
+    if (!asText) collect(envelope.staticPolicies, "policy", policyToJson, "policy");
+    collect(envelope.templates, "template", templateToJson, "template");
+
+    const links = envelope.templateLinks;
+    if (Array.isArray(links) && links.length > 0) {
+      warnings.push(
+        `${links.length} template link(s) were not imported — a linked template has no authoring shape in this lexicon yet`,
+      );
+    }
+
+    return { entities, warnings };
+  }
+
+  private toIR(
+    kind: CedarEntityKind,
+    json: PolicyJson,
+    fallbackId: string,
+    sourceText: string | undefined,
+    warnings: string[],
+  ): CedarPolicyIR {
+    const name = policyId(json, fallbackId);
+    const { props, warnings: propWarnings } = policyProps(json, sourceText);
+    for (const warning of propWarnings) warnings.push(`${name}: ${warning}`);
+    return { kind, name, props };
+  }
+}
+
+function tryParseJSON(content: string): unknown {
+  try {
+    return JSON.parse(content);
+  } catch {
+    return undefined;
+  }
+}