@intentius/chant-lexicon-cedar 0.44.8

package/src/import/roundtrip.test.ts

@@ -0,0 +1,127 @@
+/**
+ * The epic's round-trip: TypeScript → `.cedar` → parse → TypeScript → `.cedar`,
+ * with the two `.cedar` outputs byte-identical.
+ *
+ * The regenerated TypeScript is checked as source, and the second serialization
+ * is driven from the same IR the generator emitted from — running the emitted
+ * file would need a compiler in the loop to prove something the IR already
+ * decides. `generator.test.ts` covers what that source says.
+ *
+ * Two normalizations are real and are asserted here rather than hidden:
+ *
+ * - **Annotation order.** Annotations serialize into a sorted map, so authored
+ *   order is not recoverable (#1648 §1). `@id` is always emitted first, and the
+ *   rest come back alphabetically.
+ * - **Clause order.** `when`/`unless` are separate props, so an interleaved
+ *   `when … unless … when` regroups into all `when`s and then all `unless`es.
+ *
+ * Both settle after one pass, which is what the idempotence test pins.
+ */
+
+import { describe, test, expect } from "vitest";
+import { readFileSync } from "fs";
+import { join } from "path";
+import { DECLARABLE_MARKER, type Declarable } from "@intentius/chant/declarable";
+import type { SerializerResult } from "@intentius/chant/serializer";
+import { checkParsePolicySet } from "@cedar-policy/cedar-wasm/nodejs";
+import { cedarSerializer, CEDAR_JSON_FILENAME, CEDAR_POLICY_TYPE } from "../serializer";
+import { CedarParser, type CedarPolicyIR } from "./parser";
+import { CedarGenerator, loadActionConstants, sanitizeName } from "./generator";
+
+const testdata = (file: string) => readFileSync(join(import.meta.dirname, "testdata", file), "utf8");
+
+/** The declarables an authored `policies.ts` would have produced. */
+function declarablesOf(entities: CedarPolicyIR[]): Map<string, Declarable> {
+  const map = new Map<string, Declarable>();
+  for (const entity of entities) {
+    map.set(sanitizeName(entity.name), {
+      [DECLARABLE_MARKER]: true,
+      lexicon: "cedar",
+      entityType: CEDAR_POLICY_TYPE,
+      kind: "resource",
+      props: entity.props,
+    } as unknown as Declarable);
+  }
+  return map;
+}
+
+function serialize(entities: CedarPolicyIR[]): SerializerResult {
+  const out = cedarSerializer.serialize(declarablesOf(entities));
+  if (typeof out === "string") throw new Error(`expected a SerializerResult, got ${JSON.stringify(out)}`);
+  return out;
+}
+
+/** One full lap: text in, IR, regenerated TypeScript, text back out. */
+function lap(text: string): { entities: CedarPolicyIR[]; source: string; text: string } {
+  const { entities } = new CedarParser().parse(text);
+  const source = new CedarGenerator({ actionConstants: loadActionConstants() }).generate(entities).source;
+  return { entities, source, text: serialize(entities).primary };
+}
+
+// ── 1–3. The fixtures ──────────────────────────────────────────────
+
+describe("round-trip", () => {
+  for (const fixture of ["simple", "realistic", "full"]) {
+    test(`${fixture}.cedar → IR → TypeScript → .cedar is byte-identical`, () => {
+      const original = testdata(`${fixture}.cedar`);
+      const round = lap(original);
+
+      expect(round.text).toBe(original);
+      expect(round.source).toContain("new Policy(");
+    });
+  }
+
+  test("4. a second lap changes nothing — the normalizations settle after one", () => {
+    const first = lap(testdata("full.cedar"));
+    const second = lap(first.text);
+
+    expect(second.text).toBe(first.text);
+    expect(second.source).toBe(first.source);
+    expect(second.entities).toEqual(first.entities);
+  });
+});
+
+// ── The JSON leg on both sides ─────────────────────────────────────
+
+describe("the JSON leg", () => {
+  test("survives the lap and stays a policy set Cedar accepts", () => {
+    const original = testdata("full.cedar");
+    const round = lap(original);
+
+    const before = JSON.parse(serialize(new CedarParser().parse(original).entities).files![CEDAR_JSON_FILENAME]);
+    const after = JSON.parse(serialize(round.entities).files![CEDAR_JSON_FILENAME]);
+
+    expect(after).toEqual(before);
+    expect(checkParsePolicySet(after).type).toBe("success");
+  });
+
+  test("importing the JSON envelope reaches the same policies as importing the text", () => {
+    const fromText = new CedarParser().parse(testdata("full.cedar")).entities;
+    const fromJSON = new CedarParser().parse(testdata("full.cedar.json")).entities;
+
+    // Scopes, effects, annotations and clause *count* match exactly; the clause
+    // text differs by the module's parenthesization, which is why the text leg
+    // is the one that round-trips byte-for-byte.
+    const shapeOf = (entities: CedarPolicyIR[]) =>
+      entities.map((e) => ({
+        kind: e.kind,
+        name: e.name,
+        ...e.props,
+        when: (e.props.when as string[] | undefined)?.length ?? 0,
+        unless: (e.props.unless as string[] | undefined)?.length ?? 0,
+      }));
+
+    expect(shapeOf(fromJSON)).toEqual(shapeOf(fromText));
+  });
+
+  test("a JSON-envelope import still serializes to a policy set Cedar accepts", () => {
+    const { entities } = new CedarParser().parse(testdata("full.cedar.json"));
+    const result = serialize(entities);
+
+    // The JSON companion is built from the emitted text, so it parsing is the
+    // text parsing. `{ staticPolicies: <text> }` would not do here: the
+    // document contains a template, and that channel only takes static policies.
+    expect(checkParsePolicySet(JSON.parse(result.files![CEDAR_JSON_FILENAME])).type).toBe("success");
+    expect(result.warnings ?? []).toEqual([]);
+  });
+});

package/src/import/testdata/full.cedar

@@ -0,0 +1,36 @@
+@id("full-grant")
+@doc("Everything the authoring model can carry, in one policy.")
+@owner("platform")
+@ticket("SEC-12")
+permit (
+  principal is App::User in App::Group::"engineering",
+  action in [App::Action::"read", App::Action::"write", App::Action::"list"],
+  resource is App::Document in App::Folder::"handbook"
+)
+when { resource.owner == principal && context.mfa == true }
+when { principal.department == "eng" }
+unless { resource.classification == "secret" }
+unless { context.ip.isInRange(ip("10.0.0.0/8")) };
+
+@id("deny-anonymous")
+forbid (
+  principal,
+  action,
+  resource
+);
+
+@id("quoted-note")
+@note("say \"hi\" \\ done")
+permit (
+  principal == App::ServiceAccount::"ci",
+  action in [App::Action::"create", App::Action::"approve"],
+  resource
+)
+when { context.note == "a } b { c" };
+
+@id("share-with-slots")
+permit (
+  principal == ?principal,
+  action == App::Action::"share",
+  resource in ?resource
+);

package/src/import/testdata/full.cedar.json

@@ -0,0 +1,238 @@
+{
+  "staticPolicies": {
+    "full-grant": {
+      "effect": "permit",
+      "principal": {
+        "op": "is",
+        "entity_type": "App::User",
+        "in": {
+          "entity": {
+            "type": "App::Group",
+            "id": "engineering"
+          }
+        }
+      },
+      "action": {
+        "op": "in",
+        "entities": [
+          {
+            "type": "App::Action",
+            "id": "read"
+          },
+          {
+            "type": "App::Action",
+            "id": "write"
+          },
+          {
+            "type": "App::Action",
+            "id": "list"
+          }
+        ]
+      },
+      "resource": {
+        "op": "is",
+        "entity_type": "App::Document",
+        "in": {
+          "entity": {
+            "type": "App::Folder",
+            "id": "handbook"
+          }
+        }
+      },
+      "conditions": [
+        {
+          "kind": "when",
+          "body": {
+            "&&": {
+              "left": {
+                "==": {
+                  "left": {
+                    ".": {
+                      "left": {
+                        "Var": "resource"
+                      },
+                      "attr": "owner"
+                    }
+                  },
+                  "right": {
+                    "Var": "principal"
+                  }
+                }
+              },
+              "right": {
+                "==": {
+                  "left": {
+                    ".": {
+                      "left": {
+                        "Var": "context"
+                      },
+                      "attr": "mfa"
+                    }
+                  },
+                  "right": {
+                    "Value": true
+                  }
+                }
+              }
+            }
+          }
+        },
+        {
+          "kind": "when",
+          "body": {
+            "==": {
+              "left": {
+                ".": {
+                  "left": {
+                    "Var": "principal"
+                  },
+                  "attr": "department"
+                }
+              },
+              "right": {
+                "Value": "eng"
+              }
+            }
+          }
+        },
+        {
+          "kind": "unless",
+          "body": {
+            "==": {
+              "left": {
+                ".": {
+                  "left": {
+                    "Var": "resource"
+                  },
+                  "attr": "classification"
+                }
+              },
+              "right": {
+                "Value": "secret"
+              }
+            }
+          }
+        },
+        {
+          "kind": "unless",
+          "body": {
+            "isInRange": [
+              {
+                ".": {
+                  "left": {
+                    "Var": "context"
+                  },
+                  "attr": "ip"
+                }
+              },
+              {
+                "ip": [
+                  {
+                    "Value": "10.0.0.0/8"
+                  }
+                ]
+              }
+            ]
+          }
+        }
+      ],
+      "annotations": {
+        "doc": "Everything the authoring model can carry, in one policy.",
+        "id": "full-grant",
+        "owner": "platform",
+        "ticket": "SEC-12"
+      }
+    },
+    "deny-anonymous": {
+      "effect": "forbid",
+      "principal": {
+        "op": "All"
+      },
+      "action": {
+        "op": "All"
+      },
+      "resource": {
+        "op": "All"
+      },
+      "conditions": [],
+      "annotations": {
+        "id": "deny-anonymous"
+      }
+    },
+    "quoted-note": {
+      "effect": "permit",
+      "principal": {
+        "op": "==",
+        "entity": {
+          "type": "App::ServiceAccount",
+          "id": "ci"
+        }
+      },
+      "action": {
+        "op": "in",
+        "entities": [
+          {
+            "type": "App::Action",
+            "id": "create"
+          },
+          {
+            "type": "App::Action",
+            "id": "approve"
+          }
+        ]
+      },
+      "resource": {
+        "op": "All"
+      },
+      "conditions": [
+        {
+          "kind": "when",
+          "body": {
+            "==": {
+              "left": {
+                ".": {
+                  "left": {
+                    "Var": "context"
+                  },
+                  "attr": "note"
+                }
+              },
+              "right": {
+                "Value": "a } b { c"
+              }
+            }
+          }
+        }
+      ],
+      "annotations": {
+        "id": "quoted-note",
+        "note": "say \"hi\" \\ done"
+      }
+    }
+  },
+  "templates": {
+    "share-with-slots": {
+      "effect": "permit",
+      "principal": {
+        "op": "==",
+        "slot": "?principal"
+      },
+      "action": {
+        "op": "==",
+        "entity": {
+          "type": "App::Action",
+          "id": "share"
+        }
+      },
+      "resource": {
+        "op": "in",
+        "slot": "?resource"
+      },
+      "conditions": [],
+      "annotations": {
+        "id": "share-with-slots"
+      }
+    }
+  },
+  "templateLinks": []
+}

package/src/import/testdata/realistic.cedar

@@ -0,0 +1,35 @@
+@id("owner-read")
+@doc("Owners always read their own documents.")
+permit (
+  principal is App::User,
+  action in [App::Action::"read", App::Action::"list"],
+  resource is App::Document
+)
+when { resource.owner == principal };
+
+@id("public-read")
+permit (
+  principal is App::User,
+  action == App::Action::"read",
+  resource is App::Document
+)
+when { resource.public == true }
+when { context.mfa == true };
+
+@id("owner-write")
+permit (
+  principal is App::User,
+  action == App::Action::"write",
+  resource is App::Document
+)
+when { resource.owner == principal }
+unless { context.mfa == false };
+
+@id("restrict-delete")
+forbid (
+  principal,
+  action == App::Action::"delete",
+  resource is App::Document
+)
+when { resource.classification == "confidential" }
+unless { principal == App::User::"archivist" };

package/src/import/testdata/simple.cedar

@@ -0,0 +1,6 @@
+@id("allow-alice-read")
+permit (
+  principal == App::User::"alice",
+  action == App::Action::"read",
+  resource is App::Document
+);

package/src/index.ts

@@ -0,0 +1,94 @@
+// Plugin
+export { cedarPlugin } from "./plugin";
+
+// Serializer
+export { cedarSerializer, policyIdFromLogicalName, resolvePolicyId, cedarPolicyRecords } from "./serializer";
+export { CEDAR_POLICY_TYPE, CEDAR_JSON_FILENAME } from "./serializer";
+export type { CedarEffect, CedarScope, CedarPolicyProps, CedarPolicyRecord } from "./serializer";
+
+// AVP embedding (#1652) — the typed statement an `AWS::VerifiedPermissions::Policy`
+// carries, without a dependency on the aws lexicon. See src/avp/embed.ts.
+export {
+  avpStatement,
+  avpStatementJSON,
+  avpPolicyDefinition,
+  avpPolicyResource,
+  avpPolicySet,
+} from "./avp/embed";
+export type {
+  AvpEmbedOptions,
+  AvpPolicyDefinition,
+  AvpPolicyResource,
+  AvpStaticDefinition,
+} from "./avp/embed";
+
+// The AVP ownership channel (#1652, chant #1348). Design record: src/avp/OWNERSHIP.md.
+export {
+  AVP_OWNERSHIP_KEYS,
+  AVP_POLICY_ID_KEY,
+  AVP_DESCRIPTION_MAX,
+  encodeOwnershipDescription,
+  decodeOwnershipDescription,
+  ownershipFromDescription,
+  ownershipFromStoreTags,
+  descriptionIsOwned,
+  storeOwnershipTags,
+} from "./avp/ownership";
+export type { DecodedDescription } from "./avp/ownership";
+
+// AVP lifecycle readers (#1652).
+export { describeAvpResources } from "./avp/describe-resources";
+export { observeAvpAmbient, AVP_AMBIENT_KINDS } from "./avp/ambient";
+export { exportAvpResources, policyToResourceIR } from "./avp/live-export";
+export { resolvePolicyStoreId, AVP_POLICY_STORE_ENV } from "./avp/store";
+
+export { policySetJSON, escapeCedarString } from "./serializer";
+export type { CedarPolicySetJSON } from "./serializer";
+
+// Import / reconcile (#1653) — `.cedar` text and the JSON policy-set envelope
+// in, authoring TypeScript out.
+export { CedarParser, isPolicySetEnvelope } from "./import/parser";
+export type { CedarParseResult, CedarPolicyIR, CedarEntityKind } from "./import/parser";
+export { CedarGenerator, loadActionConstants, sanitizeName, CEDAR_PACKAGE } from "./import/generator";
+export type { CedarGenerateOptions, CedarGenerateResult } from "./import/generator";
+export { CedarTemplateParser, CedarTemplateGenerator } from "./import/adapter";
+export { detectTemplate } from "./detect";
+
+// Lint rules
+export { rules as cedarLintRules } from "./lint/rules";
+
+// Packaging pipeline (for external tooling)
+export { packageLexicon } from "./codegen/package";
+export type { PackageOptions, PackageResult } from "./codegen/package";
+
+// The `cedar` config namespace (#1344). Importing this package is what brings
+// the key into ChantConfig, so a `chant.config.ts` that sets it compiles.
+export { cedarConfigSchema, loadCedarConfig, CEDAR_DEFAULT_SCHEMA_PATH } from "./config";
+export type { CedarConfig } from "./config";
+
+// Upstream pin — the cedar-wasm package version and the Cedar language
+// version it implements (#1650).
+export { CEDAR_WASM_VERSION, CEDAR_LANG_VERSION } from "./spec/pin";
+
+// Schema coverage — is every schema declaration reachable from the generated
+// artifacts? Policy coverage below asks the other half.
+export { computeCedarCoverage, formatCedarCoverage, analyzeCedarCoverage } from "./coverage";
+export type { CedarCoverageReport, CedarCoverageItem } from "./coverage";
+
+// Policy coverage — which schema declarations the built policy set can apply
+// to. Backs the `cedar:coverage` MCP tool.
+export { computePolicyCoverage, formatPolicyCoverage } from "./mcp/policy-coverage";
+export type {
+  CedarPolicyCoverageReport,
+  CedarPolicyCoverageItem,
+  CedarPolicyCoverageOptions,
+} from "./mcp/policy-coverage";
+
+// Composites — the repeated policy shapes Cedar itself has nowhere to put.
+export * from "./composites/index";
+
+// `chant init --lexicon cedar --template <name>` scaffolds.
+export { cedarInitTemplates, CEDAR_INIT_TEMPLATES } from "./init-templates";
+
+// Generated entity types, actions and the Policy authoring class (#1650).
+export * from "./generated/index";