@intentius/chant-lexicon-cedar 0.44.8

package/dist/rules/cede011.ts

@@ -0,0 +1,58 @@
+/**
+ * CEDE011: surface the Cedar validator's warnings
+ *
+ * `validate()` returns two arrays, and the second one is the interesting one
+ * for a policy nobody has noticed is dead. The validator's warnings are the
+ * findings that do not make the set invalid but do mean it is not doing what it
+ * says: "policy is impossible: the policy expression evaluates to false for all
+ * valid requests" is the one that matters most — a guard whose attribute
+ * comparison can never hold, so the grant it wraps never fires and the access
+ * it was written to give quietly does not exist.
+ *
+ * Split from CEDE010 rather than folded into it because the two mean different
+ * things: an error is a policy no evaluator will accept, a warning is a policy
+ * that will be accepted and will not work. They deserve different severities
+ * and, in a report, different lines.
+ *
+ * Same two traps as CEDE010 — findings live under `type: "success"`, and their
+ * order is not stable, so `validatePolicySet` sorts before returning.
+ */
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { parsedPolicySets } from "./cedar-helpers";
+import { findSchema, loadWasm, normalizePolicySet, validatePolicySet } from "./wasm-helpers";
+
+export const cede011: PostSynthCheck = {
+  id: "CEDE011",
+  description: "Cedar validation warnings (impossible policies, shadowed conditions) on an emitted policy set",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    const sets = parsedPolicySets(ctx);
+    if (sets.length === 0) return diagnostics;
+
+    // Both "no validator" and "no schema" are already reported once by
+    // CEDC010/CEDE010; repeating them here would triple the same line.
+    const wasm = loadWasm();
+    if (!wasm) return diagnostics;
+    const schema = findSchema(ctx);
+    if (!schema) return diagnostics;
+
+    for (const set of sets) {
+      const { policySet } = normalizePolicySet(wasm, set);
+      const outcome = validatePolicySet(wasm, policySet, schema.schema);
+      if (outcome.failure) continue; // CEDE010 reports the failed call
+
+      for (const finding of outcome.warnings) {
+        diagnostics.push({
+          checkId: "CEDE011",
+          severity: "warning",
+          message: `Policy "${finding.policyId}" validates but Cedar warns about it: ${finding.message}`,
+          entity: finding.policyId,
+          lexicon: set.lexicon,
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/ceds010.ts

@@ -0,0 +1,57 @@
+/**
+ * CEDS010: a bare `permit(principal, action, resource);` is a standing grant
+ *
+ * The one policy that permits everything to everyone on everything. It is
+ * valid Cedar, it is what a scaffolded policy looks like before anyone has
+ * written the real one, and the Cedar validator says nothing about it — checked
+ * directly against 4.12.0 (chant #1648): a schema-clean run over exactly this
+ * policy returns zero errors, zero warnings, zero other warnings. There is no
+ * upstream tool that will catch it, which is why the epic names this wall as a
+ * definition-of-done item and why it lives here.
+ *
+ * The shape is unambiguous in the JSON: all three scopes unconstrained
+ * (`op: "All"`) and no `when`/`unless` clause to narrow it. Anything with even
+ * one constraint or one guard is somebody's deliberate decision and is not this
+ * check's business (an unconstrained *action* alone is CEDS012).
+ *
+ * Severity is env-gated on the same `ctx.env` seam the k8s org-policy example
+ * and the aws tier checks use: a production build fails, everything else warns,
+ * so the scaffold-and-iterate loop stays workable while the thing that ships
+ * cannot carry it.
+ */
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { conditionsOf, effectOf, isProdLikeEnv, parsedPolicySets, scopeIsAll } from "./cedar-helpers";
+
+export const ceds010: PostSynthCheck = {
+  id: "CEDS010",
+  description: "A bare permit(principal, action, resource) with no scope constraints and no conditions grants everything",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    const prod = isProdLikeEnv(ctx.env);
+    const severity = prod ? "error" : "warning";
+
+    for (const set of parsedPolicySets(ctx)) {
+      for (const entry of set.entries) {
+        if (effectOf(entry.policy) !== "permit") continue;
+        const policy = entry.policy;
+        const bare =
+          scopeIsAll(policy.principal) &&
+          scopeIsAll(policy.action) &&
+          scopeIsAll(policy.resource) &&
+          conditionsOf(policy).length === 0;
+        if (!bare) continue;
+
+        diagnostics.push({
+          checkId: "CEDS010",
+          severity,
+          message: `Policy "${entry.key}" is a bare permit(principal, action, resource) — every principal may take every action on every resource.${prod ? "" : " This is an error in a production build."} Constrain a scope or add a when/unless guard.`,
+          entity: entry.key,
+          lexicon: set.lexicon,
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/ceds011.ts

@@ -0,0 +1,42 @@
+/**
+ * CEDS011: a policy set with no `forbid` has no floor
+ *
+ * Cedar's evaluation order is fixed and is the reason `forbid` exists: a
+ * `forbid` that matches beats every `permit`, no matter how the permits are
+ * written or in what order. That makes a `forbid` the only construct in the
+ * language that states an invariant — "never outside the corporate network",
+ * "never on a resource marked frozen" — which no later grant can widen.
+ *
+ * A set built only from permits has none. Every future policy is additive, and
+ * the blast radius of a careless one is bounded by nothing. This is a
+ * convention rather than a bug, so it warns; the fix is one `forbid` carrying
+ * whatever the set's real invariant is.
+ *
+ * Reported once per policy set, not once per permit.
+ */
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { effectOf, parsedPolicySets } from "./cedar-helpers";
+
+export const ceds011: PostSynthCheck = {
+  id: "CEDS011",
+  description: "A policy set built entirely from permits carries no forbid to bound them",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const set of parsedPolicySets(ctx)) {
+      if (set.entries.length === 0) continue;
+      if (set.entries.some((entry) => effectOf(entry.policy) === "forbid")) continue;
+
+      diagnostics.push({
+        checkId: "CEDS011",
+        severity: "warning",
+        message: `Cedar policy set "${set.source}" has ${set.entries.length} policy/policies and no forbid. A forbid beats every permit regardless of order, so it is the only way to state an invariant a later grant cannot widen — add one for whatever this set must never allow.`,
+        entity: set.source,
+        lexicon: set.lexicon,
+      });
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/ceds012.ts

@@ -0,0 +1,50 @@
+/**
+ * CEDS012: a `permit` over every action is IAM's `"Action": "*"`
+ *
+ * A permit that names a principal or a resource but leaves `action`
+ * unconstrained grants every action Cedar's schema defines on that target —
+ * including the ones added next quarter, which is what makes it different from
+ * a wide-but-enumerated grant. The author almost always meant a specific verb
+ * or a group (`action in [Action::"read", Action::"list"]`).
+ *
+ * Scoped deliberately narrow so it does not double-report: a policy with *no*
+ * constraint anywhere and no guard is a bare permit, which is CEDS010's
+ * finding and a more serious one. This check speaks only to a policy that
+ * constrained something and then left the verb open.
+ */
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { conditionsOf, effectOf, parsedPolicySets, scopeIsAll } from "./cedar-helpers";
+
+export const ceds012: PostSynthCheck = {
+  id: "CEDS012",
+  description: "A permit that leaves the action scope unconstrained grants every action, including future ones",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const set of parsedPolicySets(ctx)) {
+      for (const entry of set.entries) {
+        const policy = entry.policy;
+        if (effectOf(policy) !== "permit") continue;
+        if (!scopeIsAll(policy.action)) continue;
+
+        // The everything-permit belongs to CEDS010.
+        const narrowedElsewhere =
+          !scopeIsAll(policy.principal) ||
+          !scopeIsAll(policy.resource) ||
+          conditionsOf(policy).length > 0;
+        if (!narrowedElsewhere) continue;
+
+        diagnostics.push({
+          checkId: "CEDS012",
+          severity: "warning",
+          message: `Policy "${entry.key}" permits every action — the action scope is unconstrained, so the grant widens on its own as the schema gains actions. Name the actions it needs (action == Action::"read", or action in [ … ]).`,
+          entity: entry.key,
+          lexicon: set.lexicon,
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/policy-shape.ts

@@ -0,0 +1,148 @@
+/**
+ * CEDC001: a Cedar policy declaration must have a usable effect and no empty guard
+ *
+ * Two authoring mistakes that the serializer cannot report and the emitted
+ * artifact hides:
+ *
+ * - **An effect that is not `permit` or `forbid`.** Cedar has exactly two, and
+ *   the serializer coerces anything that is not the literal string `"forbid"`
+ *   into `permit`. So `effect: "deny"` — the word every other policy language
+ *   in the world uses, and the one a reader will reach for — silently emits a
+ *   *grant*. There is no downstream stage that can catch this: by the time the
+ *   policy set exists, the mistake looks like a deliberate permit.
+ * - **An empty `when`/`unless` entry.** `when: ["", "context.mfa"]` emits
+ *   `when {  }`, which is not a Cedar expression; the policy set then fails to
+ *   parse and the error arrives as a byte offset into a generated file. The
+ *   typo is here, in the source, and so is the line number worth printing.
+ *
+ * Source-level because both are visible only before serialization, and both
+ * are about a literal the author typed. A guard built from a variable or a
+ * template expression is out of reach of an AST rule and is left alone —
+ * CEDC011 covers the emitted form.
+ *
+ * Scoped by import: only calls to bindings imported from this lexicon are
+ * considered, so an unrelated `{ effect: "deny" }` in a file that has nothing
+ * to do with Cedar is never flagged.
+ */
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+import * as ts from "typescript";
+
+/** Module specifiers whose exports construct Cedar declarables. */
+const CEDAR_MODULE = /chant-lexicon-cedar/;
+
+/** The two effects Cedar has. */
+export const CEDAR_EFFECTS = ["permit", "forbid"] as const;
+
+function importedCedarBindings(sourceFile: ts.SourceFile): Set<string> {
+  const names = new Set<string>();
+  for (const statement of sourceFile.statements) {
+    if (!ts.isImportDeclaration(statement)) continue;
+    if (!ts.isStringLiteral(statement.moduleSpecifier)) continue;
+    if (!CEDAR_MODULE.test(statement.moduleSpecifier.text)) continue;
+
+    const bindings = statement.importClause?.namedBindings;
+    if (bindings && ts.isNamedImports(bindings)) {
+      for (const element of bindings.elements) names.add(element.name.text);
+    }
+    if (statement.importClause?.name) names.add(statement.importClause.name.text);
+  }
+  return names;
+}
+
+/** The callee identifier of a `new X(…)` / `X(…)` expression, if it has one. */
+function calleeName(node: ts.CallExpression | ts.NewExpression): string | undefined {
+  return ts.isIdentifier(node.expression) ? node.expression.text : undefined;
+}
+
+/** The last object-literal argument — where chant resources carry their props. */
+function propsLiteral(node: ts.CallExpression | ts.NewExpression): ts.ObjectLiteralExpression | undefined {
+  const args = [...(node.arguments ?? [])];
+  for (let i = args.length - 1; i >= 0; i--) {
+    const arg = args[i];
+    if (ts.isObjectLiteralExpression(arg)) return arg;
+  }
+  return undefined;
+}
+
+function property(obj: ts.ObjectLiteralExpression, key: string): ts.PropertyAssignment | undefined {
+  for (const prop of obj.properties) {
+    if (!ts.isPropertyAssignment(prop)) continue;
+    if (!ts.isIdentifier(prop.name) && !ts.isStringLiteral(prop.name)) continue;
+    if (prop.name.text === key) return prop;
+  }
+  return undefined;
+}
+
+function lineCol(sourceFile: ts.SourceFile, node: ts.Node): { line: number; column: number } {
+  const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+  return { line: line + 1, column: character + 1 };
+}
+
+export const cedarPolicyShapeRule: LintRule = {
+  id: "CEDC001",
+  severity: "error",
+  category: "correctness",
+  description:
+    "A Cedar policy declaration must use effect permit or forbid, and must not carry an empty when/unless clause",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const { sourceFile } = context;
+    const diagnostics: LintDiagnostic[] = [];
+    const cedarBindings = importedCedarBindings(sourceFile);
+    if (cedarBindings.size === 0) return diagnostics;
+
+    const report = (node: ts.Node, message: string): void => {
+      const { line, column } = lineCol(sourceFile, node);
+      diagnostics.push({
+        file: sourceFile.fileName,
+        line,
+        column,
+        ruleId: "CEDC001",
+        severity: "error",
+        message,
+      });
+    };
+
+    function inspect(node: ts.CallExpression | ts.NewExpression): void {
+      const callee = calleeName(node);
+      if (!callee || !cedarBindings.has(callee)) return;
+      const props = propsLiteral(node);
+      if (!props) return;
+
+      const effect = property(props, "effect");
+      if (effect && ts.isStringLiteral(effect.initializer)) {
+        const value = effect.initializer.text;
+        if (!(CEDAR_EFFECTS as readonly string[]).includes(value)) {
+          report(
+            effect,
+            `Cedar policy effect "${value}" is not a Cedar effect — the language has only permit and forbid, and anything that is not "forbid" is emitted as a permit. Write effect: "forbid" if that is what was meant.`,
+          );
+        }
+      }
+
+      for (const clause of ["when", "unless"] as const) {
+        const guard = property(props, clause);
+        if (!guard) continue;
+        const entries = ts.isArrayLiteralExpression(guard.initializer)
+          ? guard.initializer.elements
+          : [guard.initializer];
+        for (const entry of entries) {
+          if (!ts.isStringLiteral(entry) && !ts.isNoSubstitutionTemplateLiteral(entry)) continue;
+          if (entry.text.trim() !== "") continue;
+          report(
+            entry,
+            `Cedar policy has an empty ${clause} clause. An empty guard serializes to ${clause} {  }, which is not a Cedar expression and makes the whole policy set unparseable — write the condition, or drop the entry.`,
+          );
+        }
+      }
+    }
+
+    function visit(node: ts.Node): void {
+      if (ts.isCallExpression(node) || ts.isNewExpression(node)) inspect(node);
+      ts.forEachChild(node, visit);
+    }
+
+    visit(sourceFile);
+    return diagnostics;
+  },
+};

package/dist/rules/wasm-helpers.ts

@@ -0,0 +1,315 @@
+/**
+ * The `cedar-wasm` seam for the cedar post-synth checks.
+ *
+ * Cedar's real parser and validator ship as `@cedar-policy/cedar-wasm`, which
+ * runs in-process — no CLI on PATH, no Docker. Everything the checks need from
+ * it goes through this module so the traps live in one place. The traps, all
+ * of them empirically verified against 4.12.0 (chant #1648):
+ *
+ * 1. **`type: "success"` does not mean valid.** `failure` means the *call*
+ *    failed; `success` means validation *ran*, and can carry any number of
+ *    `validationErrors`. {@link validatePolicySet} asserts both.
+ * 2. **`validationErrors` ordering is non-deterministic** — the validator
+ *    parallelizes across policies and never re-sorts. Forty identical calls
+ *    produced six distinct orderings. Everything this module returns is sorted
+ *    by `policyId` then `message`, so a check's output is stable.
+ * 3. **Malformed input throws instead of returning a failure answer.** Missing
+ *    fields on a call struct raise a bare serde `Error` whose `line 1 column N`
+ *    refers to the internal call struct, not to anything the user wrote — it is
+ *    meaningless to surface. {@link call} wraps every entry point and normalizes
+ *    both channels into one result type.
+ * 4. **A bare-string policy set gets synthesized ids** (`policy0`, `policy1`),
+ *    and `@id` annotations do *not* become the policy id. Everything here
+ *    passes `staticPolicies` as a `Record<PolicyId, Policy>` keyed by chant's
+ *    own ids, so a diagnostic names something a reader can find.
+ * 5. **Only `strict` validation mode exists** in this build; any other value
+ *    throws. The settings are left at their default rather than passed.
+ *
+ * Only the `/nodejs` flavor is imported. The root/`esm` flavor imports the
+ * `.wasm` as an ES module, which Bun cannot start (`__wbindgen_start is not a
+ * function`) and Node only supports behind an experimental warning printed on
+ * every run; `/web` needs an explicit `initSync`. `/nodejs` is the one flavor
+ * that loads under `node`, `tsx`, `vitest`, and `bun` alike.
+ *
+ * Excluded from check auto-discovery by the "helper" filename filter.
+ */
+import { createRequire } from "module";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import type * as CedarWasm from "@cedar-policy/cedar-wasm/nodejs";
+import {
+  isRecord,
+  type CedarPolicyJson,
+  type CedarPolicySet,
+  type CedarPolicySetDoc,
+} from "./cedar-helpers";
+
+// ── Loading ───────────────────────────────────────────────────────
+
+type Wasm = typeof CedarWasm;
+
+let cached: Wasm | undefined;
+let loadError: string | undefined;
+
+/**
+ * The wasm module, loaded on first use.
+ *
+ * Lazy and `require`-based on purpose. The post-synth barrel is imported
+ * statically by `plugin.ts`, and every `chant lint`/`chant audit` run loads
+ * every active lexicon's plugin — a top-level import would pull 4 MB of wasm
+ * into any build that merely has cedar installed. `check()` is synchronous, so
+ * `await import()` is not available; `createRequire` is. The `/nodejs` flavor
+ * is CommonJS with a synchronous `readFileSync` init, so there is nothing to
+ * await anyway.
+ */
+export function loadWasm(): Wasm | undefined {
+  if (cached || loadError) return cached;
+  try {
+    const require = createRequire(import.meta.url);
+    cached = require("@cedar-policy/cedar-wasm/nodejs") as Wasm;
+  } catch (err) {
+    loadError = err instanceof Error ? err.message : String(err);
+  }
+  return cached;
+}
+
+/** Why the wasm could not be loaded, if it could not be. */
+export function wasmLoadError(): string | undefined {
+  loadWasm();
+  return loadError;
+}
+
+/** Reset the module cache. Test-only — lets a test exercise the load-failure path. */
+export function resetWasmCache(): void {
+  cached = undefined;
+  loadError = undefined;
+}
+
+// ── Calling ───────────────────────────────────────────────────────
+
+export type WasmResult<T> = { ok: true; value: T } | { ok: false; message: string };
+
+/**
+ * Run a wasm call, turning a thrown serde error into a result rather than an
+ * exception (trap 3 above). The thrown message is deliberately not passed
+ * through verbatim: its positions point into the internal call struct.
+ */
+export function call<T>(what: string, fn: () => T): WasmResult<T> {
+  try {
+    return { ok: true, value: fn() };
+  } catch (err) {
+    const raw = err instanceof Error ? err.message : String(err);
+    // Strip the internal `at line 1 column 42` suffix — it locates a field in
+    // the serialized call struct, never anything in the user's policy.
+    const message = raw.replace(/\s+at line \d+ column \d+\.?$/, "");
+    return { ok: false, message: `${what} could not be run by cedar-wasm: ${message}` };
+  }
+}
+
+/** The first line of a Cedar `DetailedError`, with its `help` when it has one. */
+export function describeError(error: { message: string; help?: string | null }): string {
+  return error.help ? `${error.message} (${error.help})` : error.message;
+}
+
+// ── Condition bodies ──────────────────────────────────────────────
+
+/**
+ * chant's serializer carries a `when`/`unless` body as Cedar expression
+ * *source* under a `__expr` key, because the authored model holds expression
+ * strings until schema-driven codegen (#1650) makes them typed trees. `__expr`
+ * is not part of Cedar's JSON policy grammar — the deserializer rejects it
+ * ("unknown variant `__expr`") — so anything handed to the wasm has to have
+ * those bodies parsed into real expression JSON first.
+ *
+ * There is no expression-level entry point in the package, so the expression
+ * is parsed inside a throwaway policy and the resulting condition body lifted
+ * back out. A source expression that does not parse is the finding CEDC011
+ * reports.
+ */
+export const EXPR_KEY = "__expr";
+
+export interface ExpressionFailure {
+  /** The policy key the clause belongs to. */
+  key: string;
+  /** `when` or `unless`, as the document spelled it. */
+  kind: string;
+  /** The expression source that failed. */
+  expression: string;
+  message: string;
+}
+
+export interface NormalizedPolicySet {
+  /** A policy set the wasm will accept, keyed by chant's own policy ids. */
+  policySet: CedarWasm.PolicySet;
+  /** Condition bodies whose expression source did not parse. */
+  expressionFailures: ExpressionFailure[];
+}
+
+function parseExpression(wasm: Wasm, expression: string): WasmResult<unknown> {
+  const answer = call("condition expression", () =>
+    wasm.policyToJson(`permit(principal, action, resource) when { ${expression} };`),
+  );
+  if (!answer.ok) return answer;
+  if (answer.value.type === "failure") {
+    return { ok: false, message: answer.value.errors.map(describeError).join("; ") };
+  }
+  const conditions = answer.value.json.conditions;
+  const body = Array.isArray(conditions) && isRecord(conditions[0]) ? conditions[0].body : undefined;
+  if (body === undefined) return { ok: false, message: "expression parsed to no condition body" };
+  return { ok: true, value: body };
+}
+
+/** Replace every `__expr` body in a policy set with parsed expression JSON. */
+export function normalizePolicySet(wasm: Wasm, set: CedarPolicySet): NormalizedPolicySet {
+  const staticPolicies: Record<string, unknown> = {};
+  const templates: Record<string, unknown> = {};
+  const expressionFailures: ExpressionFailure[] = [];
+
+  for (const entry of set.entries) {
+    const target = entry.template ? templates : staticPolicies;
+    target[entry.key] = normalizePolicy(wasm, entry.key, entry.policy, expressionFailures);
+  }
+
+  const doc: CedarPolicySetDoc = set.doc ?? {};
+  const policySet = {
+    staticPolicies,
+    templates,
+    templateLinks: Array.isArray(doc.templateLinks) ? doc.templateLinks : [],
+  } as unknown as CedarWasm.PolicySet;
+
+  return { policySet, expressionFailures };
+}
+
+function normalizePolicy(
+  wasm: Wasm,
+  key: string,
+  policy: CedarPolicyJson,
+  failures: ExpressionFailure[],
+): CedarPolicyJson {
+  if (!Array.isArray(policy.conditions)) return policy;
+
+  const conditions = policy.conditions.map((clause) => {
+    if (!isRecord(clause) || !isRecord(clause.body)) return clause;
+    const expression = clause.body[EXPR_KEY];
+    if (typeof expression !== "string") return clause;
+
+    const parsed = parseExpression(wasm, expression);
+    if (!parsed.ok) {
+      failures.push({
+        key,
+        kind: typeof clause.kind === "string" ? clause.kind : "when",
+        expression,
+        message: parsed.message,
+      });
+      // Leave a body the deserializer accepts so the rest of the set still
+      // validates — the unparseable clause is reported by CEDC011, not by a
+      // cascade of confusing structural errors from every other check.
+      return { ...clause, body: { Value: true } };
+    }
+    return { ...clause, body: parsed.value };
+  });
+
+  return { ...policy, conditions };
+}
+
+// ── Schema discovery ──────────────────────────────────────────────
+
+/** A Cedar schema found beside the policies in the build output. */
+export interface DiscoveredSchema {
+  /** Human-readable `.cedarschema` source, or a parsed JSON schema object. */
+  schema: CedarWasm.Schema;
+  /** The filename it came from. */
+  source: string;
+}
+
+/**
+ * The project's Cedar schema, if the build emitted one beside the policies.
+ *
+ * Two forms, both of which the wasm accepts — but only as the right JS type: a
+ * `string` is *always* read as human-readable `.cedarschema`, never as JSON, so
+ * a `.cedarschema.json` file has to be `JSON.parse`d into a live object first
+ * or the parser reports "unexpected token `{`" against perfectly valid JSON.
+ *
+ * Reads `ctx.outputs` only. Nothing emits a schema today — schema-driven
+ * codegen is #1650 — which is exactly why CEDE010 says so out loud instead of
+ * passing silently.
+ */
+export function findSchema(ctx: PostSynthContext): DiscoveredSchema | undefined {
+  for (const [, output] of ctx.outputs) {
+    if (typeof output === "string") continue;
+    for (const [filename, content] of Object.entries(output.files ?? {})) {
+      if (typeof content !== "string") continue;
+      if (filename.endsWith(".cedarschema.json")) {
+        try {
+          const parsed: unknown = JSON.parse(content);
+          if (isRecord(parsed)) return { schema: parsed as CedarWasm.Schema, source: filename };
+        } catch {
+          continue; // a schema that is not JSON is not a schema we can use
+        }
+      } else if (filename.endsWith(".cedarschema")) {
+        return { schema: content, source: filename };
+      }
+    }
+  }
+  return undefined;
+}
+
+// ── Validation ────────────────────────────────────────────────────
+
+/** One validator finding, already flattened and safe to sort. */
+export interface ValidationFinding {
+  policyId: string;
+  message: string;
+}
+
+export interface ValidationOutcome {
+  /** Sorted by `policyId` then `message` — the wasm's own order is not stable. */
+  errors: ValidationFinding[];
+  /** Same sort. */
+  warnings: ValidationFinding[];
+  /** Set when the call itself failed (a parse error, a malformed call struct). */
+  failure?: string;
+}
+
+function sortFindings(findings: ValidationFinding[]): ValidationFinding[] {
+  return [...findings].sort(
+    (a, b) => a.policyId.localeCompare(b.policyId) || a.message.localeCompare(b.message),
+  );
+}
+
+function flatten(errors: CedarWasm.ValidationError[]): ValidationFinding[] {
+  return errors.map((e) => ({ policyId: e.policyId, message: describeError(e.error) }));
+}
+
+/** Validate a normalized policy set against a schema. Never throws. */
+export function validatePolicySet(
+  wasm: Wasm,
+  policySet: CedarWasm.PolicySet,
+  schema: CedarWasm.Schema,
+): ValidationOutcome {
+  const answer = call("validate", () => wasm.validate({ schema, policies: policySet }));
+  if (!answer.ok) return { errors: [], warnings: [], failure: answer.message };
+
+  if (answer.value.type === "failure") {
+    return {
+      errors: [],
+      warnings: [],
+      failure: answer.value.errors.map(describeError).join("; "),
+    };
+  }
+
+  // `success` only means validation RAN. The findings are in the arrays.
+  return {
+    errors: sortFindings(flatten(answer.value.validationErrors)),
+    warnings: sortFindings(flatten(answer.value.validationWarnings)),
+  };
+}
+
+/** Parse-only gate, for when there is no schema to validate against. */
+export function parsePolicySet(wasm: Wasm, policySet: CedarWasm.PolicySet): WasmResult<string[]> {
+  const answer = call("checkParsePolicySet", () => wasm.checkParsePolicySet(policySet));
+  if (!answer.ok) return answer;
+  if (answer.value.type === "failure") {
+    return { ok: true, value: answer.value.errors.map(describeError).sort() };
+  }
+  return { ok: true, value: [] };
+}