@intentius/chant-lexicon-cedar 0.44.8

package/src/spec/parse.ts

@@ -0,0 +1,253 @@
+/**
+ * Turn a `.cedarschema` into the flat declaration list the emitters read.
+ *
+ * The canonical input is the human-readable syntax and the canonical
+ * intermediate is `schemaToJsonWithResolvedTypes`' output (#1648 §4). That
+ * choice buys one thing that matters here: `schemaToJson` emits
+ * `{type:"EntityOrCommon", name}` for every named type, which cannot
+ * distinguish an entity reference from a primitive from a common-type alias,
+ * so an emitter reading it would have to re-implement Cedar's own name
+ * resolution. The resolved form hands back `{type:"Entity", name:"App::User"}`
+ * for references and bare primitives for the rest.
+ *
+ * What it does *not* resolve is common types in attribute position: those come
+ * back as a bare qualified name (`{type:"App::TagSet"}`) with the definition
+ * still in `commonTypes`. {@link resolveTypeRef} closes that last hop, so
+ * nothing downstream ever sees an alias.
+ *
+ * One declaration per entity type and one per action, each carrying its own
+ * fully-qualified `typeName` — which is what lets `NamingStrategy` contest
+ * short names across namespaces the same way it does for every other lexicon.
+ */
+
+import type { ParsedResult } from "@intentius/chant/codegen/generate";
+import { resolveSchema, type ResolvedNamespace, type ResolvedSchemaJson, type ResolvedType } from "./wasm";
+
+// ── Types ─────────────────────────────────────────────────────────
+
+/** A Cedar type, with common-type aliases already collapsed. */
+export type CedarTypeRef =
+  | { kind: "primitive"; cedar: "String" | "Long" | "Bool"; ts: "string" | "number" | "boolean" }
+  | { kind: "entity"; entityType: string }
+  | { kind: "set"; element: CedarTypeRef }
+  | { kind: "record"; attributes: CedarAttribute[] }
+  /** `ipaddr`, `decimal`, `datetime`, `duration` — carried as strings in TS. */
+  | { kind: "extension"; name: string }
+  /** An enumerated entity type, or anything the resolver left unrecognized. */
+  | { kind: "opaque"; name: string };
+
+export interface CedarAttribute {
+  name: string;
+  required: boolean;
+  type: CedarTypeRef;
+}
+
+interface CedarDeclBase extends ParsedResult {
+  /** Fully-qualified: `App::User`, or `App::Action::"read"`. */
+  typeName: string;
+  /** Namespace the declaration lives in; `""` for the empty namespace. */
+  namespace: string;
+  propertyTypes: Array<{ name: string }>;
+  enums: unknown[];
+}
+
+export interface CedarEntityDecl extends CedarDeclBase {
+  kind: "entity";
+  /** Unqualified name as written in the schema. */
+  shortName: string;
+  /** Fully-qualified parents from `in [...]`. */
+  memberOfTypes: string[];
+  attributes: CedarAttribute[];
+  /** Present for an enumerated entity (`entity Env enum ["prod","dev"]`). */
+  enumValues?: string[];
+}
+
+export interface CedarActionDecl extends CedarDeclBase {
+  kind: "action";
+  /** The action id as written (`read`). */
+  actionId: string;
+  principalTypes: string[];
+  resourceTypes: string[];
+  context: CedarAttribute[];
+}
+
+export type CedarDecl = CedarEntityDecl | CedarActionDecl;
+
+export interface ParsedSchema {
+  decls: CedarDecl[];
+  /** The resolved JSON, kept for the content pin and for coverage reporting. */
+  resolved: ResolvedSchemaJson;
+}
+
+// ── Parsing ───────────────────────────────────────────────────────
+
+/**
+ * Parse a `.cedarschema` into declarations plus the resolved JSON it came from.
+ *
+ * Throws with the wasm's own message on a schema that does not parse — which
+ * is the right failure for a project schema that is malformed, and reads far
+ * better than the alternative, since Cedar's parse errors carry `did you mean`
+ * suggestions.
+ */
+export function parseCedarSchema(schemaText: string): ParsedSchema {
+  const result = resolveSchema(schemaText);
+  if (!result.ok) {
+    throw new Error(`cedar: schema did not resolve — ${result.error}`);
+  }
+
+  const resolved = result.value;
+  const decls: CedarDecl[] = [];
+
+  for (const namespace of Object.keys(resolved).sort()) {
+    decls.push(...declarationsFor(namespace, resolved[namespace]));
+  }
+
+  return { decls, resolved };
+}
+
+/**
+ * `parseSchema` for `generatePipeline`. One buffer in, many declarations out.
+ */
+export function parseSchema(_typeName: string, data: Buffer): CedarDecl[] {
+  return parseCedarSchema(data.toString("utf-8")).decls;
+}
+
+function declarationsFor(namespace: string, body: ResolvedNamespace | undefined): CedarDecl[] {
+  if (!body) return [];
+  const commonTypes = body.commonTypes ?? {};
+  const decls: CedarDecl[] = [];
+
+  for (const shortName of Object.keys(body.entityTypes ?? {}).sort()) {
+    const entity = body.entityTypes![shortName];
+    const typeName = qualify(namespace, shortName);
+    const attributes = recordAttributes(entity.shape, commonTypes, namespace);
+
+    decls.push({
+      kind: "entity",
+      typeName,
+      namespace,
+      shortName,
+      memberOfTypes: [...(entity.memberOfTypes ?? [])].sort(),
+      attributes,
+      ...(entity.enum ? { enumValues: [...entity.enum] } : {}),
+      // One "property type" per entity: its attribute record. Nested anonymous
+      // records are inlined rather than named, so this stays 1:1.
+      propertyTypes: [{ name: `${shortName}_Attributes` }],
+      enums: entity.enum ? [entity.enum] : [],
+    });
+  }
+
+  for (const actionId of Object.keys(body.actions ?? {}).sort()) {
+    const action = body.actions![actionId];
+    const appliesTo = action.appliesTo ?? {};
+
+    decls.push({
+      kind: "action",
+      typeName: actionUid(namespace, actionId),
+      namespace,
+      actionId,
+      principalTypes: [...(appliesTo.principalTypes ?? [])].sort(),
+      resourceTypes: [...(appliesTo.resourceTypes ?? [])].sort(),
+      context: recordAttributes(appliesTo.context, commonTypes, namespace),
+      propertyTypes: [{ name: `${actionId}_Context` }],
+      enums: [],
+    });
+  }
+
+  return decls;
+}
+
+/** `App` + `User` → `App::User`; the empty namespace yields the bare name. */
+export function qualify(namespace: string, shortName: string): string {
+  return namespace ? `${namespace}::${shortName}` : shortName;
+}
+
+/** The entity UID form an action is referenced by in a policy. */
+export function actionUid(namespace: string, actionId: string): string {
+  return namespace ? `${namespace}::Action::"${actionId}"` : `Action::"${actionId}"`;
+}
+
+function recordAttributes(
+  shape: ResolvedType | undefined,
+  commonTypes: Record<string, ResolvedType>,
+  namespace: string,
+): CedarAttribute[] {
+  if (!shape || shape.type !== "Record" || !shape.attributes) return [];
+  return Object.keys(shape.attributes)
+    .sort()
+    .map((name) => {
+      const attr = shape.attributes![name];
+      return {
+        name,
+        // Cedar attributes are required unless the schema says otherwise, so
+        // `required` absent means required — the opposite of JSON Schema.
+        required: attr.required !== false,
+        type: resolveTypeRef(attr, commonTypes, namespace),
+      };
+    });
+}
+
+const PRIMITIVES: Record<string, { cedar: "String" | "Long" | "Bool"; ts: "string" | "number" | "boolean" }> = {
+  String: { cedar: "String", ts: "string" },
+  Long: { cedar: "Long", ts: "number" },
+  Bool: { cedar: "Bool", ts: "boolean" },
+};
+
+const EXTENSIONS = new Set(["ipaddr", "decimal", "datetime", "duration"]);
+
+/**
+ * Collapse one resolved type node, following common-type aliases.
+ *
+ * `seen` guards a schema whose common types reference each other — Cedar
+ * rejects true cycles, but a malformed one should not spin here.
+ */
+export function resolveTypeRef(
+  node: ResolvedType,
+  commonTypes: Record<string, ResolvedType>,
+  namespace: string,
+  seen: ReadonlySet<string> = new Set(),
+): CedarTypeRef {
+  const primitive = PRIMITIVES[node.type];
+  if (primitive) return { kind: "primitive", ...primitive };
+
+  if (node.type === "Entity") {
+    return { kind: "entity", entityType: node.name ?? "" };
+  }
+
+  if (node.type === "Set") {
+    const element = node.element
+      ? resolveTypeRef(node.element, commonTypes, namespace, seen)
+      : ({ kind: "opaque", name: "Set" } as CedarTypeRef);
+    return { kind: "set", element };
+  }
+
+  if (node.type === "Record") {
+    const attributes = Object.keys(node.attributes ?? {})
+      .sort()
+      .map((name) => {
+        const attr = node.attributes![name];
+        return {
+          name,
+          required: attr.required !== false,
+          type: resolveTypeRef(attr, commonTypes, namespace, seen),
+        };
+      });
+    return { kind: "record", attributes };
+  }
+
+  if (EXTENSIONS.has(node.type)) {
+    return { kind: "extension", name: node.type };
+  }
+
+  // `EntityOrCommon` should not survive resolution, but a defensive branch
+  // costs nothing and keeps a future wasm version from emitting `unknown`.
+  const named = node.type === "EntityOrCommon" ? (node.name ?? "") : node.type;
+
+  const commonKey = named.startsWith(`${namespace}::`) ? named.slice(namespace.length + 2) : named;
+  const definition = commonTypes[commonKey];
+  if (definition && !seen.has(named)) {
+    return resolveTypeRef(definition, commonTypes, namespace, new Set([...seen, named]));
+  }
+
+  return { kind: "opaque", name: named };
+}

package/src/spec/pin.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  assertPinnedLangVersion,
+  assertPinnedSchema,
+  CEDAR_LANG_VERSION,
+  CEDAR_SCHEMA_PIN,
+  CEDAR_WASM_VERSION,
+  PINNED_SCHEMA_NAMES,
+  resolvedSchemaDigest,
+  schemaDrift,
+} from "./pin";
+import { langVersion, packageVersion } from "./wasm";
+import { defaultSchemaPath } from "./fetch";
+import { parseCedarSchema } from "./parse";
+
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "..");
+
+describe("version pin", () => {
+  it("matches the installed cedar-wasm", () => {
+    expect(packageVersion()).toBe(CEDAR_WASM_VERSION);
+    expect(langVersion()).toBe(CEDAR_LANG_VERSION);
+  });
+
+  it("matches the version in package.json, which is what npm installs", () => {
+    const pkg = JSON.parse(readFileSync(join(repoRoot, "lexicons", "cedar", "package.json"), "utf-8")) as {
+      dependencies?: Record<string, string>;
+    };
+    expect(pkg.dependencies?.["@cedar-policy/cedar-wasm"]).toBe(CEDAR_WASM_VERSION);
+  });
+
+  it("refuses a language version other than the pinned one", () => {
+    expect(() => assertPinnedLangVersion({ actual: "4.6", env: {} })).toThrow(/language version mismatch/);
+  });
+
+  it("proceeds with a warning under the accept env var", () => {
+    const warnings: string[] = [];
+    assertPinnedLangVersion({
+      actual: "4.6",
+      env: { CHANT_ACCEPT_CEDAR_LANG: "1" },
+      warn: (m) => warnings.push(m),
+    });
+    expect(warnings).toHaveLength(1);
+  });
+
+  it("passes on a match", () => {
+    expect(() => assertPinnedLangVersion()).not.toThrow();
+  });
+});
+
+describe("content pin", () => {
+  const { decls, resolved } = parseCedarSchema(readFileSync(defaultSchemaPath(), "utf-8"));
+  const names = decls.map((d) => d.typeName).sort();
+
+  it("matches the bundled default schema", () => {
+    expect(resolvedSchemaDigest(resolved)).toBe(CEDAR_SCHEMA_PIN.digest);
+    expect(names).toEqual([...PINNED_SCHEMA_NAMES]);
+    expect(CEDAR_SCHEMA_PIN.declarations).toBe(names.length);
+  });
+
+  it("digests the resolved JSON, so reformatting the schema text does not move it", () => {
+    const reformatted = readFileSync(defaultSchemaPath(), "utf-8").replace(/\n/g, "\n\n");
+    expect(resolvedSchemaDigest(parseCedarSchema(reformatted).resolved)).toBe(CEDAR_SCHEMA_PIN.digest);
+  });
+
+  it("names what moved when it moves", () => {
+    const drift = schemaDrift({ changed: true }, [...names, "App::Ghost"], names);
+    expect(drift?.added).toEqual(["App::Ghost"]);
+    expect(drift?.removed).toEqual([]);
+  });
+
+  it("refuses rather than regenerating against a schema nobody chose", () => {
+    expect(() => assertPinnedSchema({ changed: true }, names, { env: {} })).toThrow(
+      /no longer resolves to the pinned JSON/,
+    );
+  });
+
+  it("warns instead under the accept env var", () => {
+    const warnings: string[] = [];
+    assertPinnedSchema({ changed: true }, names, {
+      env: { CHANT_ACCEPT_CEDAR_SCHEMA: "1" },
+      warn: (m) => warnings.push(m),
+    });
+    expect(warnings[0]).toMatch(/digest: "sha256:/);
+  });
+});

package/src/spec/pin.ts

@@ -0,0 +1,243 @@
+/**
+ * What this lexicon pins, and why it pins two different things (#1650, #1390).
+ *
+ * ## The version pin
+ *
+ * `@cedar-policy/cedar-wasm` and the Cedar *language* move independently: the
+ * package is 4.12.0, the grammar it implements is 4.5 (#1648 §0). A package
+ * bump that leaves the language at 4.5 cannot change what parses, so the
+ * language version is the value worth asserting at generation time and the
+ * package version is the one `upstreamPin` bumps. Both are recorded.
+ *
+ * The runtime assert is chant #1390's spirit applied to a dependency rather
+ * than to a downloaded spec: generation refuses when the installed package
+ * implements a different language version than the one whose resolved output
+ * produced the committed artifacts. Releases are roughly monthly, so this will
+ * fire — and when it does, the answer is to look at the new resolved JSON, not
+ * to publish types generated from a grammar nobody checked.
+ *
+ * ## The content pin
+ *
+ * The bundled default schema (`default-schema.cedarschema`) is what generation
+ * reads in this repo and in a fresh checkout, so it decides the published
+ * surface. There is no upstream URL to pin, so the pin is over content: a
+ * sha256 over the *resolved* JSON — the thing the emitters actually read —
+ * plus the covered entity-type and action names committed beside it.
+ *
+ * Resolved-JSON serialization is byte-deterministic (Rust `BTreeMap` ordering,
+ * 1 distinct serialization over 25 runs, #1648 §5.2), so the digest is stable.
+ * It moves when the default schema is edited, and — the case the pin exists for
+ * — when a cedar-wasm upgrade resolves the same schema differently. Both change
+ * the generated types, and neither is visible in a diff otherwise, because
+ * `src/generated/` is not committed.
+ *
+ * A user's own project schema is not pinned. It is their input, they own its
+ * churn, and refusing to generate because they edited their own schema would be
+ * absurd.
+ */
+
+import { createHash } from "crypto";
+import pinnedNames from "./pinned-names.json" with { type: "json" };
+import { langVersion } from "./wasm";
+
+/** The pinned `@cedar-policy/cedar-wasm` version — what `upstreamPin` bumps. */
+export const CEDAR_WASM_VERSION = "4.12.0";
+
+/** The Cedar *language* version that package implements (`getCedarLangVersion()`). */
+export const CEDAR_LANG_VERSION = "4.5";
+
+/** Env var that proceeds past a language-version mismatch for one run. */
+export const ACCEPT_LANG_ENV = "CHANT_ACCEPT_CEDAR_LANG";
+
+/** Env var that accepts a moved default-schema digest, printing the new pin. */
+export const ACCEPT_SCHEMA_ENV = "CHANT_ACCEPT_CEDAR_SCHEMA";
+
+/**
+ * The entity types and action UIDs the pinned default schema resolved to.
+ *
+ * Committed beside the digest for the same reason aws commits its type names:
+ * without the list, accepting a new pin is one opaque hash replacing another,
+ * and the generated artifacts cannot stand in because they are gitignored.
+ */
+export const PINNED_SCHEMA_NAMES: readonly string[] = pinnedNames as string[];
+
+export interface SchemaPin {
+  /** `sha256:…` over the resolved schema JSON. */
+  readonly digest: string;
+  /** How many entity types and actions the pinned schema declared. */
+  readonly declarations: number;
+  /** ISO date the pin was accepted, so a diff reads as a decision. */
+  readonly accepted: string;
+}
+
+/**
+ * The accepted default schema.
+ *
+ * To move it: run generation, read the refusal, confirm the delta is one you
+ * want, and paste the printed block here in its own commit.
+ */
+export const CEDAR_SCHEMA_PIN: SchemaPin = {
+  digest: "sha256:8f86a4e4fd6845c245c84d226277741c41d29da6a173f01477bda3a662dd3ec9",
+  declarations: 16,
+  accepted: "2026-08-10",
+};
+
+/**
+ * Digest the resolved schema JSON.
+ *
+ * Hashes the canonical serialization the wasm produced, not the authored
+ * `.cedarschema` text: reformatting a schema, or reordering its entity types,
+ * changes the text and not one byte of what the emitters read.
+ */
+export function resolvedSchemaDigest(resolved: unknown): string {
+  return `sha256:${createHash("sha256").update(JSON.stringify(resolved)).digest("hex")}`;
+}
+
+/** What moved between the pinned schema and the one just resolved. */
+export interface SchemaDrift {
+  digest: string;
+  declarations: number;
+  added: string[];
+  removed: string[];
+}
+
+/** Compare a freshly resolved schema against a pin. `null` when it matches. */
+export function schemaDrift(
+  resolved: unknown,
+  names: readonly string[],
+  pinnedNamesList: readonly string[] = PINNED_SCHEMA_NAMES,
+  pin: SchemaPin = CEDAR_SCHEMA_PIN,
+): SchemaDrift | null {
+  const digest = resolvedSchemaDigest(resolved);
+  if (digest === pin.digest) return null;
+
+  const current = new Set(names);
+  const pinned = new Set(pinnedNamesList);
+  return {
+    digest,
+    declarations: current.size,
+    added: [...current].filter((n) => !pinned.has(n)).sort(),
+    removed: [...pinned].filter((n) => !current.has(n)).sort(),
+  };
+}
+
+/** The report a mismatch produces. */
+export function schemaDriftMessage(drift: SchemaDrift, pin: SchemaPin = CEDAR_SCHEMA_PIN): string {
+  const delta = drift.declarations - pin.declarations;
+  const countLine =
+    delta === 0
+      ? `${drift.declarations} declarations, unchanged in count`
+      : `${drift.declarations} declarations, ${delta > 0 ? "+" : ""}${delta} against the pin`;
+
+  const lines = [
+    "The bundled default Cedar schema no longer resolves to the pinned JSON.",
+    "",
+    `  pinned    ${pin.digest}  (${pin.declarations} declarations, accepted ${pin.accepted})`,
+    `  resolved  ${drift.digest}  (${countLine})`,
+  ];
+
+  if (drift.added.length > 0) {
+    lines.push(`  added     ${summarize(drift.added)}`);
+  }
+  if (drift.removed.length > 0) {
+    lines.push(`  removed   ${summarize(drift.removed)}`);
+  }
+
+  lines.push(
+    "",
+    "Either the schema was edited or cedar-wasm resolves it differently than",
+    "the version the committed surface was generated from. Both rewrite the",
+    "generated types, and src/generated/ is not committed, so neither shows up",
+    "in a diff on its own.",
+    "",
+    "Confirm the delta is one you want and update lexicons/cedar/src/spec/pin.ts",
+    "and pinned-names.json, in their own commit:",
+    "",
+    `  digest: "${drift.digest}",`,
+    `  declarations: ${drift.declarations},`,
+    `  accepted: "<today>",`,
+    "",
+    `Or re-run with ${ACCEPT_SCHEMA_ENV}=1 to proceed this once and print the same block.`,
+  );
+
+  return lines.join("\n");
+}
+
+function summarize(names: string[]): string {
+  return `${names.slice(0, 5).join(", ")}${names.length > 5 ? ` (+${names.length - 5} more)` : ""}`;
+}
+
+/**
+ * Refuse a default schema whose resolved JSON does not match the pin.
+ *
+ * Unlike aws, this one refuses on any digest move rather than only on a
+ * declaration-set change. It can afford to: the input is a file in this repo
+ * and a dependency at a pinned version, neither of which changes under the
+ * build's feet the way a republished CloudFormation archive does.
+ */
+export function assertPinnedSchema(
+  resolved: unknown,
+  names: readonly string[],
+  options: {
+    pin?: SchemaPin;
+    pinnedNames?: readonly string[];
+    env?: NodeJS.ProcessEnv;
+    warn?: (message: string) => void;
+  } = {},
+): void {
+  const pin = options.pin ?? CEDAR_SCHEMA_PIN;
+  const drift = schemaDrift(resolved, names, options.pinnedNames ?? PINNED_SCHEMA_NAMES, pin);
+  if (!drift) return;
+
+  const env = options.env ?? process.env;
+  const warn = options.warn ?? ((m: string) => console.error(m));
+  const message = schemaDriftMessage(drift, pin);
+
+  if (env[ACCEPT_SCHEMA_ENV]) {
+    warn(message);
+    return;
+  }
+  throw new Error(message);
+}
+
+/**
+ * Refuse to generate against a Cedar language version other than the pinned one.
+ *
+ * chant #1390's rule, one level up the supply chain: a lexicon does not emit
+ * types derived from a grammar nobody chose. `getCedarLangVersion()` is the
+ * right probe because it is the number that decides what parses — the package
+ * version moves monthly and mostly does not.
+ */
+export function assertPinnedLangVersion(
+  options: {
+    actual?: string;
+    expected?: string;
+    env?: NodeJS.ProcessEnv;
+    warn?: (message: string) => void;
+  } = {},
+): void {
+  const expected = options.expected ?? CEDAR_LANG_VERSION;
+  const actual = options.actual ?? langVersion();
+  if (actual === expected) return;
+
+  const message = [
+    `Cedar language version mismatch: cedar-wasm reports ${actual}, this lexicon pins ${expected}.`,
+    "",
+    "The installed @cedar-policy/cedar-wasm implements a different grammar than",
+    "the one the generated entity and action types were derived from. Generation",
+    "refuses rather than emitting a surface nobody reviewed.",
+    "",
+    "To accept it: check the resolved schema JSON for shape changes, update",
+    `CEDAR_LANG_VERSION (and CEDAR_WASM_VERSION) in lexicons/cedar/src/spec/pin.ts,`,
+    "and refresh the schema pin in the same commit.",
+    "",
+    `Or re-run with ${ACCEPT_LANG_ENV}=1 to proceed this once.`,
+  ].join("\n");
+
+  const env = options.env ?? process.env;
+  if (env[ACCEPT_LANG_ENV]) {
+    (options.warn ?? ((m: string) => console.error(m)))(message);
+    return;
+  }
+  throw new Error(message);
+}

package/src/spec/pinned-names.json

@@ -0,0 +1,18 @@
+[
+  "App::Action::\"admin\"",
+  "App::Action::\"approve\"",
+  "App::Action::\"comment\"",
+  "App::Action::\"create\"",
+  "App::Action::\"delete\"",
+  "App::Action::\"list\"",
+  "App::Action::\"read\"",
+  "App::Action::\"share\"",
+  "App::Action::\"write\"",
+  "App::Application",
+  "App::Document",
+  "App::Folder",
+  "App::Group",
+  "App::ServiceAccount",
+  "App::Team",
+  "App::User"
+]