@intentius/chant-lexicon-cedar 0.44.8

package/src/skills/chant-cedar-meta-policy.md

@@ -0,0 +1,119 @@
+---
+skill: chant-cedar-meta-policy
+description: Organizational policy over Cedar policy sets — the bare-permit wall, forbid conventions, and env-aware severity
+user-invocable: true
+---
+
+# Policy About Policy
+
+## The ruling this sits under
+
+Cedar is a target, never chant's gate. There is no `cedarGate()` and there will
+not be one: organizational policy in chant is TypeScript post-synth checks, and
+a second policy engine would duplicate the lint engine and break "TypeScript is
+the one language."
+
+So the rules below are ordinary `PostSynthCheck`s and lint rules under the `CED`
+prefix. They read the emitted policy set the way any other check reads emitted
+YAML. Cedar's own validator runs beside them, in-process, through
+`@cedar-policy/cedar-wasm` — no CLI on PATH, no Docker.
+
+## The bare-permit wall
+
+```cedar
+permit (principal, action, resource);
+```
+
+Every scope position unconstrained, no `when`, no `unless`. It grants every
+principal every action on every resource. It is legal Cedar, it validates
+clean, and it is the single most damaging line a policy set can contain.
+
+The rule is **env-aware, not absolute**:
+
+| Environment | Verdict |
+|---|---|
+| dev / local | warn — a scratch policy set during development is a normal state |
+| staging | warn, and expect it fixed before promotion |
+| **prod** | **fail the build** |
+
+Env-aware because an absolute rule gets suppressed the first time it fires
+during development, and a suppressed rule protects nothing. Failing only where
+the blast radius is real keeps the wall credible.
+
+A permit with any of the following is not bare and does not trip the wall:
+
+- a constrained scope position (`is`, `in`, `==`) on principal, action, or
+  resource, or
+- at least one `when` or `unless` clause.
+
+## Schema-absent references
+
+A policy naming an entity type or action the schema does not declare fails
+**everywhere** — dev included. There is no environment where that is intended.
+Two distinct failure modes hide behind it:
+
+1. **The typo.** `App::Documnt`. With generated classes this is a compile error
+   before any check runs, which is the point of the codegen. It survives only in
+   hand-written expression strings inside `when`/`unless`.
+2. **The silent no-op.** A scope naming an entity type outside the schema
+   *parses*, and `getValidRequestEnvsPolicy` answers "success, nothing" — an
+   empty request envelope. The policy is well-formed, deployed, and can never
+   fire. `cedar:coverage` reports these under `inert`.
+
+## Forbid conventions
+
+Cedar is default-deny, so a `forbid` is never about the absence of a grant. It
+is about the presence of a bad one: a forbid beats every permit in the set
+unconditionally, which makes it the only construct that survives a later, wider
+grant somebody adds next quarter.
+
+Three conventions follow:
+
+**Every forbid carries a guard.** An unguarded `forbid (principal, action,
+resource)` denies everything and no permit can lift it — the policy set
+authorizes nothing. `DenyByDefaultSet` throws on an empty `when` for this
+reason.
+
+**A forbid and the permits it governs ship together.** Separated, the forbid
+gets deleted during a refactor and the permits keep working, wider than anyone
+intended. `DenyByDefaultSet({ policies, when })` returns both from one call.
+
+**Sensitive resources get an explicit floor, not just an absent permit.**
+"Nobody wrote a permit for it" and "a forbid says no" look identical at
+evaluation time and completely different in review. `cedar:coverage`'s
+`forbidOnly` list is how you find declarations that have a floor; its
+`uncovered` list is how you find the ones relying on absence.
+
+## Cross-domain checks
+
+This is the thing no Cedar tool can express, because Cedar only ever sees
+policies. In a chant build, policies and the infrastructure they govern are in
+one entity graph, so a post-synth check can span both:
+
+- an entity id in a policy references an actual resource declaration
+- every declared bucket is covered by at least one `forbid`
+- no schema action lacks any policy
+
+These are ordinary post-synth checks. They are the differentiator, and they only
+work because the policy set and the estate are built together.
+
+## Severity, by environment
+
+| Finding | dev | staging | prod |
+|---|---|---|---|
+| Bare permit | warn | warn | fail |
+| Entity type or action absent from schema | fail | fail | fail |
+| Unguarded forbid | fail | fail | fail |
+| Policy with an empty request envelope (inert) | warn | warn | fail |
+| Schema action no policy covers | info | warn | warn |
+| Entity type reachable only from a forbid | info | info | info |
+
+The last row is deliberately never a failure. A resource nothing grants access
+to is frequently correct.
+
+## Where these live
+
+Post-synth checks and their catalog entries are **INTENTIUS/chant#1651**'s
+scope. This skill describes the conventions the checks encode; if you are
+writing a check, put it in `src/lint/post-synth/` with a `CED` id and an
+`auditCatalog()` entry, not in a policy file.

package/src/spec/default-schema.cedarschema

@@ -0,0 +1,108 @@
+// The schema `chant generate` falls back to when a project declares none.
+//
+// Cedar's codegen input is the project's own schema, not one global upstream
+// (epic #1645), so there is no spec to fetch. That leaves `generate()` with
+// nothing to do in a checkout that has not written a schema yet — which is
+// every fresh clone, every `just check-lexicons` run, and this lexicon's own
+// examples. This file is that fallback: a small, realistic application
+// authorization model, generated from whenever `cedar.schema` is unset or
+// points at a file that is not there.
+//
+// Point `cedar.schema` in chant.config.ts at your own `.cedarschema` and this
+// file stops being read.
+
+namespace App {
+  // Common types are resolved away by the codegen — they exist here because
+  // real schemas use them, and the resolver has to collapse them.
+  type Level = Long;
+  type TagSet = Set<String>;
+
+  entity Group = {
+    "name": String,
+    "description"?: String,
+  };
+
+  entity Team in [Group] = {
+    "name": String,
+    "costCenter"?: String,
+  };
+
+  entity User in [Group, Team] = {
+    "email": String,
+    "department": String,
+    "level": Level,
+    "manager"?: User,
+    "roles": TagSet,
+    "mfaEnabled": Bool,
+  };
+
+  entity ServiceAccount in [Group] = {
+    "name": String,
+    "owner": User,
+    "rotatedAt"?: String,
+  };
+
+  entity Folder = {
+    "name": String,
+    "owner": User,
+    "tags": TagSet,
+  };
+
+  entity Document in [Folder] = {
+    "title": String,
+    "owner": User,
+    "folder": Folder,
+    "public": Bool,
+    "tags": TagSet,
+    "classification": String,
+  };
+
+  entity Application = {
+    "name": String,
+    "owner": Team,
+  };
+
+  action read, list appliesTo {
+    principal: [User, ServiceAccount],
+    resource: [Document, Folder],
+    context: {
+      "mfa": Bool,
+      "sourceIp"?: String,
+    }
+  };
+
+  action write, create, comment appliesTo {
+    principal: [User],
+    resource: [Document, Folder],
+    context: {
+      "mfa": Bool,
+      "reason"?: String,
+    }
+  };
+
+  action delete, share appliesTo {
+    principal: [User],
+    resource: [Document],
+    context: {
+      "mfa": Bool,
+      "approvedBy"?: User,
+    }
+  };
+
+  action approve appliesTo {
+    principal: [User],
+    resource: [Document],
+    context: {
+      "mfa": Bool,
+    }
+  };
+
+  action admin appliesTo {
+    principal: [User],
+    resource: [Application],
+    context: {
+      "mfa": Bool,
+      "breakGlass"?: Bool,
+    }
+  };
+}

package/src/spec/fetch.ts

@@ -0,0 +1,107 @@
+/**
+ * "Fetch" the Cedar schema — which for this lexicon means reading a file.
+ *
+ * Every other lexicon downloads one global upstream spec. Cedar's interesting
+ * spec is the *project's* schema (epic #1645), so there is nothing to fetch,
+ * nothing to cache, and no network at all. What replaces it is a small
+ * resolution order:
+ *
+ *   1. `cedar.schema` from the project's `chant.config.ts`
+ *   2. `schema.cedarschema` in the project root
+ *   3. the schema bundled at `./default-schema.cedarschema`
+ *
+ * Step 3 is the one that needs defending. Without it `generate()` has nothing
+ * to read in a checkout that has not written a schema yet — which is every
+ * fresh clone, `just check-lexicons`, and this lexicon's own examples — and a
+ * lexicon whose generate step only works after the user does something is a
+ * lexicon whose generate step is never gated. The default is a real
+ * application-authorization schema, not a stub, so the surface it produces is
+ * worth exercising.
+ *
+ * `requireProjectSchema` turns step 3 off for projects that have moved past it.
+ */
+
+import { existsSync, readFileSync } from "fs";
+import { dirname, isAbsolute, join, resolve } from "path";
+import { fileURLToPath } from "url";
+import { CEDAR_DEFAULT_SCHEMA_PATH } from "../config";
+
+/** Filename the bundled fallback schema ships under. */
+export const DEFAULT_SCHEMA_FILENAME = "default-schema.cedarschema";
+
+/** Map key used for the single schema entry, so `parseSchema` can tell them apart. */
+export const DEFAULT_SCHEMA_KEY = "<bundled-default>";
+
+const specDir = dirname(fileURLToPath(import.meta.url));
+
+/** Absolute path to the schema bundled with this package. */
+export function defaultSchemaPath(): string {
+  return join(specDir, DEFAULT_SCHEMA_FILENAME);
+}
+
+export interface SchemaSource {
+  /** Absolute path the text came from. */
+  path: string;
+  /** The `.cedarschema` text. */
+  text: string;
+  /** True when the bundled fallback was used rather than a project schema. */
+  isDefault: boolean;
+}
+
+export interface ResolveSchemaOptions {
+  /** Project root to resolve a relative `cedar.schema` against. Defaults to `process.cwd()`. */
+  projectRoot?: string;
+  /** Already-loaded `cedar` config namespace, if the caller has one. */
+  config?: { schema?: string; validation?: { requireProjectSchema?: boolean } };
+}
+
+/**
+ * Resolve which schema `generate()` should read, without loading it.
+ *
+ * Separated from {@link fetchSchemas} so tests and `coverage()` can ask the
+ * question without reading the file.
+ */
+export function resolveSchemaPath(options: ResolveSchemaOptions = {}): { path: string; isDefault: boolean } {
+  const root = options.projectRoot ?? process.cwd();
+  const configured = options.config?.schema;
+
+  const candidates = configured
+    ? [isAbsolute(configured) ? configured : resolve(root, configured)]
+    : [resolve(root, CEDAR_DEFAULT_SCHEMA_PATH)];
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return { path: candidate, isDefault: false };
+  }
+
+  if (options.config?.validation?.requireProjectSchema) {
+    throw new Error(
+      `cedar: no schema found at ${candidates.join(", ")}. ` +
+        "`cedar.validation.requireProjectSchema` is on, so the bundled default schema is not used.",
+    );
+  }
+
+  return { path: defaultSchemaPath(), isDefault: true };
+}
+
+/** Read the resolved schema. */
+export function readSchemaSource(options: ResolveSchemaOptions = {}): SchemaSource {
+  const { path, isDefault } = resolveSchemaPath(options);
+  return { path, text: readFileSync(path, "utf-8"), isDefault };
+}
+
+/**
+ * The `fetchSchemas` callback for `generatePipeline`.
+ *
+ * Keyed by `<bundled-default>` or by the project schema's absolute path, which
+ * is how `parseSchema` knows whether the content pin applies.
+ */
+export async function fetchSchemas(options?: {
+  force?: boolean;
+  projectRoot?: string;
+  config?: ResolveSchemaOptions["config"];
+}): Promise<Map<string, Buffer>> {
+  const source = readSchemaSource({ projectRoot: options?.projectRoot, config: options?.config });
+  return new Map([
+    [source.isDefault ? DEFAULT_SCHEMA_KEY : source.path, Buffer.from(source.text, "utf-8")],
+  ]);
+}

package/src/spec/parse.test.ts

@@ -0,0 +1,123 @@
+import { describe, expect, it } from "vitest";
+import { parseCedarSchema, resolveTypeRef, type CedarEntityDecl, type CedarActionDecl } from "./parse";
+import { resolveSchema } from "./wasm";
+
+const SCHEMA = `
+namespace Chant {
+  type Level = Long;
+  type Tags = Set<String>;
+
+  entity Group;
+
+  entity User in [Group] = {
+    "department": String,
+    "level": Level,
+    "manager"?: User,
+    "tags": Tags,
+    "active": Bool,
+  };
+
+  entity Env enum ["prod", "dev"];
+
+  action read appliesTo {
+    principal: [User],
+    resource: [Group],
+    context: { "mfa": Bool, "ip"?: ipaddr }
+  };
+}
+`;
+
+function entity(name: string): CedarEntityDecl {
+  const decl = parseCedarSchema(SCHEMA).decls.find((d) => d.typeName === name);
+  if (!decl || decl.kind !== "entity") throw new Error(`no entity ${name}`);
+  return decl;
+}
+
+describe("parseCedarSchema", () => {
+  it("produces one declaration per entity type and action", () => {
+    const names = parseCedarSchema(SCHEMA).decls.map((d) => d.typeName);
+    // Entity types first, then actions, each group sorted — the order the
+    // resolved JSON already hands back, which is what keeps codegen stable.
+    expect(names).toEqual([
+      "Chant::Env",
+      "Chant::Group",
+      "Chant::User",
+      'Chant::Action::"read"',
+    ]);
+  });
+
+  it("resolves common types away", () => {
+    const attrs = Object.fromEntries(entity("Chant::User").attributes.map((a) => [a.name, a.type]));
+    // `level` is declared as the common type `Level`; nothing downstream should
+    // ever see the alias.
+    expect(attrs.level).toEqual({ kind: "primitive", cedar: "Long", ts: "number" });
+    expect(attrs.tags).toEqual({
+      kind: "set",
+      element: { kind: "primitive", cedar: "String", ts: "string" },
+    });
+  });
+
+  it("keeps entity references as references, not strings", () => {
+    const manager = entity("Chant::User").attributes.find((a) => a.name === "manager");
+    expect(manager?.type).toEqual({ kind: "entity", entityType: "Chant::User" });
+  });
+
+  it("treats a missing `required` as required, the opposite of JSON Schema", () => {
+    const attrs = entity("Chant::User").attributes;
+    expect(attrs.find((a) => a.name === "department")?.required).toBe(true);
+    expect(attrs.find((a) => a.name === "manager")?.required).toBe(false);
+  });
+
+  it("carries enum entity values through", () => {
+    expect(entity("Chant::Env").enumValues).toEqual(["prod", "dev"]);
+  });
+
+  it("reads an action's appliesTo and context", () => {
+    const decl = parseCedarSchema(SCHEMA).decls.find((d) => d.kind === "action") as CedarActionDecl;
+    expect(decl.actionId).toBe("read");
+    expect(decl.principalTypes).toEqual(["Chant::User"]);
+    expect(decl.resourceTypes).toEqual(["Chant::Group"]);
+    expect(decl.context.map((a) => a.name)).toEqual(["ip", "mfa"]);
+    expect(decl.context.find((a) => a.name === "ip")?.type).toEqual({ kind: "extension", name: "ipaddr" });
+  });
+
+  it("handles the empty namespace", () => {
+    const decls = parseCedarSchema(`entity Thing = { "n": Long };`).decls;
+    expect(decls.map((d) => d.typeName)).toEqual(["Thing"]);
+  });
+
+  it("reports a malformed schema with Cedar's own message", () => {
+    expect(() => parseCedarSchema("entity User = {")).toThrow(/schema did not resolve/);
+  });
+
+  it("does not treat a parseable empty schema as a schema", () => {
+    // `checkParseSchema("")` succeeds — an empty schema is legal Cedar (#1648
+    // §1) — so "did it parse" can never stand in for "is there a schema".
+    expect(parseCedarSchema("").decls).toEqual([]);
+  });
+});
+
+describe("resolveTypeRef", () => {
+  it("survives a self-referential common type instead of spinning", () => {
+    const commonTypes = { Loop: { type: "Chant::Loop" } };
+    expect(resolveTypeRef({ type: "Chant::Loop" }, commonTypes, "Chant")).toEqual({
+      kind: "opaque",
+      name: "Chant::Loop",
+    });
+  });
+});
+
+describe("resolveSchema", () => {
+  it("refuses a non-string rather than trapping the wasm", () => {
+    // A JS object here is `memory access out of bounds`, not a failure answer
+    // (#1648 §5.4) — the guard is what keeps that from reaching the caller.
+    const result = resolveSchema({ Chant: {} });
+    expect(result.ok).toBe(false);
+    expect(result.ok === false && result.error).toMatch(/as a string/);
+  });
+
+  it("leaves the wasm usable after a rejected call", () => {
+    resolveSchema(123);
+    expect(resolveSchema(SCHEMA).ok).toBe(true);
+  });
+});