@intentius/chant-lexicon-cedar 0.44.8

package/src/init-templates.test.ts

@@ -0,0 +1,158 @@
+/**
+ * Every template scaffolds a project that builds — checked against the codegen
+ * rather than asserted in prose.
+ *
+ * "Builds" for cedar means something specific: the policy file imports classes
+ * and action constants that do not exist until `chant generate` has read the
+ * project's own schema. So the test runs the same pipeline stage `generate()`
+ * does — parse the template's `.cedarschema`, build the emit model — and
+ * requires every identifier the template imports to be in it. A template whose
+ * schema and policies drift apart fails here rather than in a user's terminal.
+ */
+
+import { describe, expect, it } from "vitest";
+import { checkParsePolicySet, checkParseSchema } from "@cedar-policy/cedar-wasm/nodejs";
+import { CEDAR_INIT_TEMPLATES, cedarInitTemplates } from "./init-templates";
+import { parseCedarSchema } from "./spec/parse";
+import { buildEmitModel } from "./codegen/emit";
+import { createNaming, POLICY_TS_NAME } from "./codegen/naming";
+
+/** Names exported by the generated index for a given schema. */
+function generatedNames(schemaText: string): Set<string> {
+  const { decls } = parseCedarSchema(schemaText);
+  const model = buildEmitModel(decls, createNaming(decls));
+
+  const names = new Set<string>([
+    POLICY_TS_NAME,
+    "EntityTypeName",
+    "EntityUid",
+    "ActionUid",
+    "PolicyRef",
+    "PolicyEffect",
+    "PolicyScope",
+    "PolicyProps",
+    "ALL_ACTIONS",
+    "ALL_ENTITY_TYPES",
+  ]);
+  for (const entity of model.entities) {
+    names.add(entity.tsName);
+    names.add(entity.attributesTsName);
+    names.add(entity.uidTsName);
+    names.add(`${entity.attributesTsName}Props`);
+  }
+  for (const action of model.actions) {
+    names.add(action.tsName);
+    names.add(action.contextTsName);
+    names.add(`${action.contextTsName}Props`);
+  }
+  return names;
+}
+
+/** Identifiers a policy file imports from the lexicon package (any subpath). */
+function importedNames(source: string): string[] {
+  const names: string[] = [];
+  const importRe = /import\s+(?:type\s+)?\{([^}]+)\}\s+from\s+"@intentius\/chant-lexicon-cedar[^"]*"/g;
+  for (const match of source.matchAll(importRe)) {
+    for (const raw of match[1].split(",")) {
+      const name = raw.trim().replace(/^type\s+/, "").split(/\s+as\s+/)[0].trim();
+      if (name) names.push(name);
+    }
+  }
+  return names;
+}
+
+/** Names the composites barrel exports — not schema-derived, so listed here. */
+const COMPOSITE_EXPORTS = new Set(["OwnerCanManage", "DenyByDefaultSet"]);
+
+/** Every entity type the schema declares, as a policy scope would spell it. */
+function entityTypeNames(schemaText: string): Set<string> {
+  return new Set(parseCedarSchema(schemaText).decls.filter((d) => d.kind === "entity").map((d) => d.typeName));
+}
+
+describe("cedarInitTemplates", () => {
+  it("names three templates", () => {
+    expect(CEDAR_INIT_TEMPLATES).toEqual(["default", "avp-embedding", "gateway-policy-set"]);
+  });
+
+  it("falls back to the default for an unknown name", () => {
+    expect(cedarInitTemplates("no-such-template")).toEqual(cedarInitTemplates());
+    expect(cedarInitTemplates("default")).toEqual(cedarInitTemplates());
+  });
+
+  it("gives each named template its own schema and policies", () => {
+    const avp = cedarInitTemplates("avp-embedding");
+    const gateway = cedarInitTemplates("gateway-policy-set");
+
+    expect(avp.root?.["schema.cedarschema"]).not.toEqual(gateway.root?.["schema.cedarschema"]);
+    expect(avp.src["policies.ts"]).not.toEqual(gateway.src["policies.ts"]);
+  });
+
+  for (const template of CEDAR_INIT_TEMPLATES) {
+    describe(template, () => {
+      const set = cedarInitTemplates(template);
+      const schemaText = set.root?.["schema.cedarschema"] ?? "";
+      const policies = set.src["policies.ts"] ?? "";
+
+      it("ships a schema at the path cedar resolves without any config", () => {
+        // spec/fetch.ts step 2: `schema.cedarschema` in the project root.
+        expect(schemaText.length).toBeGreaterThan(0);
+        expect(checkParseSchema(schemaText).type).toBe("success");
+      });
+
+      it("ships a policy file and a README", () => {
+        expect(policies).toContain("export const");
+        expect(set.root?.["README.md"]).toContain("chant generate --lexicon cedar");
+      });
+
+      it("wires the generate and build scripts into package.json", () => {
+        expect(set.scripts?.generate).toBe("chant generate --lexicon cedar");
+        expect(set.scripts?.build).toBe("chant build");
+      });
+
+      it("imports only names its own schema generates", () => {
+        const available = generatedNames(schemaText);
+        const missing = importedNames(policies).filter(
+          (name) => !available.has(name) && !COMPOSITE_EXPORTS.has(name),
+        );
+
+        expect(missing, `${template}: policies.ts imports names its schema does not produce`).toEqual([]);
+      });
+
+      it("names only entity types its own schema declares", () => {
+        const declared = entityTypeNames(schemaText);
+        const referenced = [...policies.matchAll(/is:\s*"([^"]+)"/g)].map((m) => m[1]);
+
+        expect(referenced.length).toBeGreaterThan(0);
+        for (const name of referenced) {
+          expect(declared, `${template}: ${name} is not in this template's schema`).toContain(name);
+        }
+      });
+
+      it("declares at least one forbid — Cedar's only override construct", () => {
+        expect(policies).toMatch(/effect:\s*"forbid"|DenyByDefaultSet/);
+      });
+    });
+  }
+
+  it("emits a bare-permit-free default policy set", () => {
+    // The meta-policy wall fails `permit (principal, action, resource);` in a
+    // prod build, so no scaffold may ship one.
+    const policies = cedarInitTemplates().src["policies.ts"];
+
+    expect(policies).toContain("principal: { is:");
+    expect(policies).toContain("when:");
+  });
+
+  it("produces schemas cedar-wasm accepts alongside a parsable policy shape", () => {
+    // A sanity check that the scope forms the templates use survive the
+    // round-trip through Cedar's own parser.
+    const probe = `permit (
+  principal is App::User,
+  action == App::Action::"read",
+  resource is App::Document
+)
+when { resource.owner == principal };`;
+
+    expect(checkParsePolicySet({ staticPolicies: probe }).type).toBe("success");
+  });
+});

package/src/init-templates.ts

@@ -0,0 +1,358 @@
+/**
+ * `chant init --lexicon cedar --template <name>` scaffolds.
+ *
+ * Every template ships a `schema.cedarschema` at the project root. That is not
+ * decoration: cedar's codegen input is the project's own schema (epic #1645),
+ * and a scaffold without one generates against the bundled default — a project
+ * whose typed classes describe somebody else's entity model.
+ *
+ * The filename is fixed rather than configured because `schema.cedarschema` in
+ * the project root is step 2 of the resolution order in `spec/fetch.ts`, so a
+ * scaffolded project needs no `cedar.schema` key at all. It also has to be
+ * fixed: core writes `chant.config.ts` before a plugin's root files and
+ * `writeIfNotExists` keeps the first one, so a template that shipped its own
+ * config would be silently discarded. The README each template ships is where
+ * `requireProjectSchema` gets recommended, which is the honest place for advice
+ * a scaffold cannot enforce.
+ *
+ * The policy files use `entityType`-string scopes (`{ is: "App::Document" }`)
+ * and generated action constants, so a scaffolded project compiles the moment
+ * `chant generate` has run against its own schema.
+ */
+
+import type { InitTemplateSet } from "@intentius/chant/lexicon";
+
+/** Filename every template writes its schema to — see spec/fetch.ts step 2. */
+const SCHEMA_FILE = "schema.cedarschema";
+
+function readme(title: string, body: string): string {
+  return `# ${title}
+
+\`\`\`bash
+npm install
+npx chant generate --lexicon cedar   # schema.cedarschema -> typed classes
+npx chant build                      # emits .cedar text + policies.cedar.json
+\`\`\`
+
+Generate first. The classes and action constants \`src/policies.ts\` imports do
+not exist until \`chant generate\` has read \`${SCHEMA_FILE}\`.
+
+${body}
+
+## Before this is real
+
+Add \`requireProjectSchema\` once you are past the scaffold:
+
+\`\`\`typescript
+// chant.config.ts
+export default {
+  lexicons: ["cedar"],
+  cedar: {
+    validation: { mode: "strict", requireProjectSchema: true },
+  },
+} satisfies ChantConfig;
+\`\`\`
+
+Without it, deleting or renaming \`${SCHEMA_FILE}\` falls back to the schema
+bundled with the lexicon and the build still succeeds — against an entity model
+this project never declared.
+
+## What comes out
+
+| File | Who reads it |
+|------|--------------|
+| \`dist/*.cedar\` | Every Cedar evaluator — AVP, cedar-agent, an embedded cedar-wasm |
+| \`dist/policies.cedar.json\` | The Cedar JSON policy format; also the parse source for import |
+`;
+}
+
+// ── default ───────────────────────────────────────────────────────
+
+const DEFAULT_SCHEMA = `// The entity model your policies are typed against.
+//
+// \`chant generate --lexicon cedar\` turns every declaration below into a
+// TypeScript class or constant, so a renamed entity type becomes a
+// compiler-guided refactor rather than a runtime validation failure.
+
+namespace App {
+  entity User = {
+    "email": String,
+    "department": String,
+  };
+
+  entity Document = {
+    "title": String,
+    "owner": User,
+    "classification": String,
+  };
+
+  action read, write appliesTo {
+    principal: [User],
+    resource: [Document],
+    context: {
+      "mfa": Bool,
+    }
+  };
+}
+`;
+
+const DEFAULT_POLICIES = `import { Policy, ReadAction, WriteAction } from "@intentius/chant-lexicon-cedar";
+
+/**
+ * A permit and a forbid — the smallest policy set worth deploying.
+ *
+ * Cedar is default-deny, so the permit is what grants anything at all. The
+ * forbid is not the absence of a grant: it beats every permit in the set
+ * unconditionally, which is what makes it survive a wider grant added later.
+ */
+
+/** Owners read and write their own documents. */
+export const ownerAccess = new Policy({
+  effect: "permit",
+  principal: { is: "App::User" },
+  action: { in: [ReadAction, WriteAction] },
+  resource: { is: "App::Document" },
+  when: ["resource.owner == principal"],
+});
+
+/** Nothing confidential moves without MFA, owner or not. */
+export const requireMfaOnConfidential = new Policy({
+  effect: "forbid",
+  principal: { is: "App::User" },
+  resource: { is: "App::Document" },
+  when: ['resource.classification == "confidential"'],
+  unless: ["context.mfa == true"],
+});
+`;
+
+// ── avp-embedding ─────────────────────────────────────────────────
+
+const AVP_SCHEMA = `// The entity model behind an Amazon Verified Permissions policy store.
+//
+// AVP is one deployment vehicle for Cedar; the schema and the policies are
+// ordinary Cedar either way, and the same emitted \`.cedar\` file is read by any
+// other evaluator with no AWS involved.
+
+namespace Store {
+  entity Tenant = {
+    "name": String,
+  };
+
+  entity User in [Tenant] = {
+    "email": String,
+    "tenant": Tenant,
+    "admin": Bool,
+  };
+
+  entity Record in [Tenant] = {
+    "tenant": Tenant,
+    "owner": User,
+    "sensitive": Bool,
+  };
+
+  action view, edit appliesTo {
+    principal: [User],
+    resource: [Record],
+    context: {
+      "mfa": Bool,
+    }
+  };
+}
+`;
+
+const AVP_POLICIES = `import { Policy, EditAction, ViewAction } from "@intentius/chant-lexicon-cedar";
+
+/**
+ * Policies destined for an AVP policy store.
+ *
+ * The statement each of these serializes to is what goes in a
+ * \`AWS::VerifiedPermissions::Policy\`'s \`definition.static.statement\` — the
+ * same bytes as the emitted \`.cedar\` file, so the deployed policy and the
+ * reviewed file cannot disagree.
+ *
+ * The typed handoff (a VerifiedPermissionsPolicy whose statement accepts a
+ * Policy value directly, plus the policy-store lifecycle and the ownership
+ * channel) is landing with INTENTIUS/chant#1652. Until it does, emit the
+ * \`.cedar\` file and reference its text; do not hand-type a statement string.
+ */
+
+/** Tenancy: nobody touches a record outside their own tenant. */
+export const tenantIsolation = new Policy({
+  effect: "forbid",
+  principal: { is: "Store::User" },
+  resource: { is: "Store::Record" },
+  unless: ["resource.tenant == principal.tenant"],
+});
+
+/** Members view records in their tenant. */
+export const tenantView = new Policy({
+  effect: "permit",
+  principal: { is: "Store::User" },
+  action: { eq: ViewAction },
+  resource: { is: "Store::Record" },
+  when: ["resource.tenant == principal.tenant"],
+});
+
+/** Owners and tenant admins edit; sensitive records also demand MFA. */
+export const ownerEdit = new Policy({
+  effect: "permit",
+  principal: { is: "Store::User" },
+  action: { eq: EditAction },
+  resource: { is: "Store::Record" },
+  when: ["resource.owner == principal || principal.admin == true"],
+  unless: ["resource.sensitive == true && context.mfa == false"],
+});
+`;
+
+// ── gateway-policy-set ────────────────────────────────────────────
+
+const GATEWAY_SCHEMA = `// An API gateway's authorization model.
+//
+// The principal is a caller identity, the resource is a route, and the action
+// is an HTTP method. Modelling routes as entities rather than strings is what
+// lets a policy say \`resource.public == true\` instead of matching paths.
+
+namespace Gateway {
+  entity Scope = {
+    "name": String,
+  };
+
+  entity Caller in [Scope] = {
+    "clientId": String,
+    "internal": Bool,
+  };
+
+  entity Route = {
+    "path": String,
+    "public": Bool,
+    "deprecated": Bool,
+  };
+
+  action get, post, delete appliesTo {
+    principal: [Caller],
+    resource: [Route],
+    context: {
+      "sourceIp": String,
+      "authenticated": Bool,
+    }
+  };
+}
+`;
+
+const GATEWAY_POLICIES = `import {
+  DeleteAction,
+  DenyByDefaultSet,
+  GetAction,
+  Policy,
+  PostAction,
+} from "@intentius/chant-lexicon-cedar";
+
+/**
+ * A gateway policy set with an explicit deny floor.
+ *
+ * \`DenyByDefaultSet\` returns the forbid and the permits it governs from one
+ * call, so the floor cannot be deleted in a refactor while the grants survive.
+ * A forbid beats every permit unconditionally — that is the whole reason to
+ * write one under a default-deny engine.
+ */
+
+/** Anonymous callers reach public routes, read-only. */
+const publicRead = new Policy({
+  effect: "permit",
+  principal: { is: "Gateway::Caller" },
+  action: { eq: GetAction },
+  resource: { is: "Gateway::Route" },
+  when: ["resource.public == true"],
+});
+
+/** Authenticated callers may write. */
+const authenticatedWrite = new Policy({
+  effect: "permit",
+  principal: { is: "Gateway::Caller" },
+  action: { in: [PostAction, DeleteAction] },
+  resource: { is: "Gateway::Route" },
+  when: ["context.authenticated == true"],
+});
+
+/** Deprecated routes are closed to everyone but internal callers. */
+const guarded = DenyByDefaultSet({
+  policies: [publicRead, authenticatedWrite],
+  entityType: "Gateway::Route",
+  when: ["resource.deprecated == true"],
+  unless: ["principal.internal == true"],
+  annotations: { id: "deprecated-route-floor" },
+});
+
+export const deprecatedRouteFloor = guarded.floor;
+export const publicReadGrant = guarded.members[0];
+export const authenticatedWriteGrant = guarded.members[1];
+`;
+
+// ── The template set ──────────────────────────────────────────────
+
+/**
+ * Scaffolds for `chant init`.
+ *
+ * An unrecognized name falls through to the default rather than throwing —
+ * the same behaviour every other lexicon's `initTemplates` has.
+ */
+export function cedarInitTemplates(template?: string): InitTemplateSet {
+  const scripts = {
+    generate: "chant generate --lexicon cedar",
+    build: "chant build",
+  };
+
+  if (template === "avp-embedding") {
+    return {
+      src: { "policies.ts": AVP_POLICIES },
+      root: {
+        [SCHEMA_FILE]: AVP_SCHEMA,
+        "README.md": readme(
+          "Cedar policies for a Verified Permissions store",
+          "The `Store` namespace models a multi-tenant record store. `tenantIsolation` is a\n" +
+            "`forbid`, deliberately: a forbid beats every permit in the set unconditionally,\n" +
+            "so a tenancy boundary written that way survives a wider grant added later.\n\n" +
+            "The statement each policy serializes to is what goes in an\n" +
+            "`AWS::VerifiedPermissions::Policy`. The typed handoff is landing with\n" +
+            "INTENTIUS/chant#1652 — until then, reference the emitted `.cedar` text rather\n" +
+            "than hand-typing a statement string.",
+        ),
+      },
+      scripts,
+    };
+  }
+
+  if (template === "gateway-policy-set") {
+    return {
+      src: { "policies.ts": GATEWAY_POLICIES },
+      root: {
+        [SCHEMA_FILE]: GATEWAY_SCHEMA,
+        "README.md": readme(
+          "Cedar policies for an API gateway",
+          "Routes are entities, not path strings, which is what lets a policy say\n" +
+            "`resource.public == true` instead of matching globs. The `DenyByDefaultSet`\n" +
+            "composite returns the deprecated-route floor and the grants it governs from one\n" +
+            "call, so a refactor cannot delete the floor and leave the grants behind.",
+        ),
+      },
+      scripts,
+    };
+  }
+
+  return {
+    src: { "policies.ts": DEFAULT_POLICIES },
+    root: {
+      [SCHEMA_FILE]: DEFAULT_SCHEMA,
+      "README.md": readme(
+        "Cedar policies",
+        "One permit and one forbid. Cedar is default-deny, so the permit is what grants\n" +
+          "anything at all; the forbid is not the absence of a grant but an override that\n" +
+          "beats every permit in the set.",
+      ),
+    },
+    scripts,
+  };
+}
+
+/** Every template name this lexicon scaffolds, for docs and tests. */
+export const CEDAR_INIT_TEMPLATES = ["default", "avp-embedding", "gateway-policy-set"] as const;

package/src/lint/audit-catalog.ts

@@ -0,0 +1,130 @@
+/**
+ * The cedar lexicon's `chant audit` catalog — metadata for every CED check,
+ * contributed via `cedarPlugin.auditCatalog()` (#687, #1346).
+ *
+ * A check's own definition says what it looks for. It does not say how severe
+ * the finding is, whether the fix is mechanical, what backs the rule, or what
+ * to title it in a report. `resolveAuditCatalog` merges this map over core's
+ * static catalog to answer all four — and it skips a lexicon that omits the
+ * method *silently*, which is how fly's and temporal's checks reached the
+ * report with no metadata at all. A repo-level test fails on a gap in either
+ * direction, so this map and the shipped checks move together.
+ *
+ * Every entry here is `yamlBased: true`: each check reads `ctx.outputs` — the
+ * emitted policy set — and nothing reads `ctx.entities`, so all of them fire
+ * on an audit of a standalone `policies.cedar.json` exactly as they do on a
+ * `chant build`. `auditRule()` hardcodes that, so it is used throughout rather
+ * than constructing `RuleMeta` by hand the way fly and fountain must.
+ *
+ * `authority` is left off deliberately. The catalog test treats a citation as
+ * proof that a finding is `security`, and Cedar's own docs are a language
+ * reference rather than a benchmark like CIS or OSSF Scorecard; citing them
+ * would be dressing up chant's own opinion. The one place a citation would be
+ * honest — the bare-permit wall — is chant's convention, not upstream's, and
+ * the verification report is explicit that Cedar's validator says nothing
+ * about it.
+ */
+
+import { auditRule, type RuleMeta } from "@intentius/chant/audit/catalog";
+
+export const cedarAuditCatalog: Record<string, RuleMeta> = {
+  // ── Pre-synth lint rule ────────────────────────────────────────
+  //
+  // Not a post-synth check, and so not required by the coverage test — but a
+  // reader who hits CEDC001 wants the same metadata as one who hits CEDC010,
+  // which is the reason fountain catalogs FTN001.
+  CEDC001: auditRule(
+    "CEDC001",
+    "merge-worthy",
+    "guidance",
+    "Cedar policy has an unusable effect or an empty guard",
+    'Use effect: "permit" or "forbid" — anything else is emitted as a permit — and remove empty when/unless entries.',
+    { category: "correctness" },
+  ),
+
+  // ── Correctness ────────────────────────────────────────────────
+  CEDC010: auditRule(
+    "CEDC010",
+    "merge-worthy",
+    "guidance",
+    "Cedar policy set does not parse",
+    "Fix the policy set so Cedar's own parser accepts it — no evaluator can load it as it stands.",
+    { category: "correctness" },
+  ),
+  CEDC011: auditRule(
+    "CEDC011",
+    "merge-worthy",
+    "guidance",
+    "Cedar condition expression does not parse",
+    "Correct the when/unless expression source named in the finding; the rest of the policy set cannot load until it parses.",
+    { category: "correctness" },
+  ),
+  CEDC012: auditRule(
+    "CEDC012",
+    "merge-worthy",
+    "guidance",
+    "Duplicate Cedar policy id",
+    "Rename one of the colliding declarations, or give it an explicit and distinct @id annotation — the JSON policy set keeps only one of them.",
+    { category: "correctness" },
+  ),
+  CEDC013: auditRule(
+    "CEDC013",
+    "report-only",
+    "guidance",
+    "Cedar policy annotation is empty or disagrees with the policy id",
+    "Make @id match the policy's id (or drop it and let chant derive one), and give every other annotation a real value.",
+    { category: "best-practice" },
+  ),
+  CEDC014: auditRule(
+    "CEDC014",
+    "merge-worthy",
+    "guidance",
+    "Cedar scope constraint names a bare type instead of an entity",
+    'Write the reference as a full UID — Namespace::Type::"id" — so it resolves to an entity rather than degrading to a type name with an empty id.',
+    { category: "correctness" },
+  ),
+
+  // ── Evaluability (the validator) ───────────────────────────────
+  CEDE010: auditRule(
+    "CEDE010",
+    "merge-worthy",
+    "guidance",
+    "Cedar policy fails validation against the schema",
+    "Fix the entity type, action, or attribute the validator names — a policy the validator rejects can never grant anything. If the finding is the advisory, emit a .cedarschema beside the policies so validation can run at all.",
+    { category: "correctness" },
+  ),
+  CEDE011: auditRule(
+    "CEDE011",
+    "report-only",
+    "guidance",
+    "Cedar validator warns about a policy",
+    "Read the validator's warning — an impossible policy evaluates to false for every valid request, so the access it was written to grant does not exist.",
+    { category: "correctness" },
+  ),
+
+  // ── Security ───────────────────────────────────────────────────
+  CEDS010: auditRule(
+    "CEDS010",
+    "merge-worthy",
+    "guidance",
+    "Bare permit(principal, action, resource) grants everything",
+    "Constrain a scope or add a when/unless guard. Cedar's validator does not flag this policy; a production build fails on it.",
+    { category: "security" },
+  ),
+  CEDS011: auditRule(
+    "CEDS011",
+    "report-only",
+    "guidance",
+    "Cedar policy set has no forbid",
+    "Add a forbid for whatever the set must never allow — a forbid beats every permit, so it is the only invariant a later grant cannot widen.",
+    { category: "security" },
+  ),
+  CEDS012: auditRule(
+    "CEDS012",
+    "report-only",
+    "guidance",
+    "Cedar permit leaves the action scope unconstrained",
+    'Name the actions the grant needs (action == Action::"read", or action in [ … ]) so it does not widen as the schema gains actions.',
+    { category: "security" },
+  ),
+};