@intentius/chant-lexicon-cedar 0.44.8 → 0.44.9

package/dist/skills/chant-cedar-authoring.md

@@ -0,0 +1,180 @@
+---
+skill: chant-cedar-authoring
+description: Author Cedar authorization policies as typed chant resources — schema to generated classes to .cedar and JSON outputs
+user-invocable: true
+---
+
+# Cedar Policies as Typed Resources
+
+## What this lexicon covers
+
+Cedar is an authorization policy language. Its toolchain validates and evaluates
+policies; it does not help you write them. There are no functions, no modules,
+no loops, and templates carry exactly two slots (`?principal`, `?resource`), so
+teams managing large policy sets generate `.cedar` text with string templating.
+This lexicon replaces that with typed TypeScript.
+
+Two artifacts come out of every build:
+
+- `<name>.cedar` — the policy text every Cedar evaluator reads (Amazon Verified
+  Permissions, cedar-agent, an embedded `cedar-wasm`).
+- `policies.cedar.json` — the same set in the Cedar JSON policy format, beside
+  it. This is also the parse source for import.
+
+chant is nowhere in either. An emitted policy set is consumed by any evaluator.
+
+## The three steps
+
+### 1. Declare a schema
+
+The schema is *your* file, not a global upstream — it is the input codegen
+reads. Write it in Cedar's human-readable syntax and point the config at it:
+
+```typescript
+// chant.config.ts
+import type { ChantConfig } from "@intentius/chant";
+import "@intentius/chant-lexicon-cedar";
+
+export default {
+  lexicons: ["cedar"],
+  cedar: {
+    schema: "authz/app.cedarschema",
+    validation: { mode: "strict", requireProjectSchema: true },
+  },
+} satisfies ChantConfig;
+```
+
+Turn `requireProjectSchema` on once the project has its own schema. Without it a
+missing file silently falls back to the bundled default, and the difference
+between "your entity types" and "somebody else's" is invisible.
+
+### 2. Run generate
+
+```bash
+npx chant generate --lexicon cedar
+```
+
+That produces, per declaration in the schema:
+
+| Schema declaration | Generated |
+|---|---|
+| `entity Document in [Folder] = { … }` | `Document` class, `DocumentAttributes` property class, `DocumentUid` template-literal type |
+| `action read appliesTo { … }` | `ReadAction` constant, `ReadContext` property class |
+| — | `Policy` class, `EntityTypeName`, `ActionUid`, `PolicyScope`, `ALL_ACTIONS`, `ALL_ENTITY_TYPES` |
+
+`DocumentUid` is `` `App::Document::"${string}"` `` — a typo'd namespace is a
+compile error, not a validation error hours later.
+
+### 3. Write policies
+
+```typescript
+import { Policy, ReadAction, WriteAction, type UserUid } from "@intentius/chant-lexicon-cedar";
+
+const archivist: UserUid = 'App::User::"archivist"';
+
+export const ownerRead = new Policy({
+  effect: "permit",
+  principal: { is: "App::User" },
+  action: { in: [ReadAction, WriteAction] },
+  resource: { is: "App::Document" },
+  when: ["resource.owner == principal"],
+  annotations: { doc: "Owners always read their own documents." },
+});
+
+export const restrictDelete = new Policy({
+  effect: "forbid",
+  resource: { is: "App::Document" },
+  when: ['resource.classification == "confidential"'],
+  unless: [`principal == ${archivist}`],
+});
+```
+
+## Policy props
+
+| Prop | Meaning |
+|------|---------|
+| `effect` | `"permit"` or `"forbid"`. Defaults to `permit` |
+| `principal`, `action`, `resource` | Scope constraints. Omit for unconstrained |
+| `when` | Cedar expression strings, one `when { … }` clause each |
+| `unless` | Cedar expression strings, one `unless { … }` clause each |
+| `annotations` | `Record<string, string>`, emitted as `@key("value")` |
+
+### Scope forms
+
+| Written | Emitted |
+|---|---|
+| `{}` or omitted | `principal` |
+| `{ eq: X }` | `principal == X` |
+| `{ in: X }` | `principal in X` |
+| `{ in: [X, Y] }` | `principal in [X, Y]` |
+| `{ is: "App::User" }` | `principal is App::User` |
+| `{ is: "App::User", in: X }` | `principal is App::User in X` |
+
+`when`/`unless` stay strings. Cedar's expression grammar *is* the policy
+language; typing it in TypeScript is a separate problem, and the escape hatch
+would leak either way.
+
+## Policy ids
+
+The id comes from the export's logical name, kebab-cased: `allowAdminRead`
+becomes `@id("allow-admin-read")`. Set `annotations.id` to pin one explicitly —
+worth doing for a policy whose id something downstream references.
+
+## Composites
+
+Repeated policy shapes go in a factory, because Cedar has nowhere to put them.
+
+```typescript
+import {
+  DeleteAction,
+  DenyByDefaultSet,
+  OwnerCanManage,
+  ReadAction,
+  WriteAction,
+} from "@intentius/chant-lexicon-cedar";
+
+const docOwner = OwnerCanManage({
+  entityType: "App::Document",
+  actions: [ReadAction, WriteAction],
+  principal: "App::User",
+});
+
+const guarded = DenyByDefaultSet({
+  policies: [docOwner],
+  entityType: "App::Document",
+  actions: DeleteAction,
+  when: ['resource.classification == "confidential"'],
+  unless: ['principal == App::User::"archivist"'],
+});
+
+export const [confidentialFloor, documentOwnerGrant] = guarded.all;
+```
+
+`DenyByDefaultSet` returns the `forbid` floor and its members from one call, so
+deleting the floor deletes the grants with it. A `forbid` beats every `permit`
+in the set unconditionally — it is the only construct that survives a later,
+wider grant.
+
+## Checking the result
+
+```bash
+npx chant build                         # emits both artifacts, runs the CED rules
+npx chant coverage --lexicon cedar      # is every schema declaration generated?
+```
+
+The MCP tool `cedar:coverage` answers the other question: which schema entity
+types and actions the *policy set* can reach, which are reachable only from a
+`forbid`, and which no policy touches at all. An entity type nothing covers is
+inert under Cedar's default-deny — either the intent or a hole.
+
+## Things that will bite
+
+- **An empty schema validates everything clean.** `checkParseSchema("")`
+  succeeds. Set `requireProjectSchema: true`.
+- **`Group` and `Team`-shaped container entities appear in no `appliesTo`.**
+  They exist to be `in`, so no policy — not even `permit (principal, action,
+  resource)` — resolves to them. `cedar:coverage` reports that honestly rather
+  than rounding it up.
+- **A policy naming an entity type outside the schema still parses.** It
+  resolves to an empty request envelope and never fires. `cedar:coverage`
+  reports it under `inert`.

package/dist/skills/chant-cedar-avp-embedding.md

@@ -0,0 +1,125 @@
+---
+skill: chant-cedar-avp-embedding
+description: Embed a typed cedar-lexicon policy into an AWS Verified Permissions policy resource instead of a hand-written string
+user-invocable: true
+---
+
+# Cedar Policies Inside Verified Permissions
+
+## The seam
+
+Amazon Verified Permissions is one deployment vehicle for Cedar, and chant
+already ships it: `AWS::VerifiedPermissions::Policy` in the aws lexicon carries
+its policy text in a `definition.static.statement` field typed `CedarPolicy` —
+which is to say, `string`.
+
+That string is the seam. Everything upstream of it — the schema, the entity
+types, the actions, the scope constraints — is what the cedar lexicon owns.
+Everything downstream — the policy store, the CloudFormation `ApplyOp`, the IAM
+around it — is the aws lexicon's, and already works.
+
+```
+cedar lexicon                       aws lexicon
+schema → Policy → .cedar text  →   VerifiedPermissionsPolicy.definition.static.statement
+```
+
+The walk-away test holds on both sides. The emitted `.cedar` file is read by any
+evaluator with no AWS involved; the AVP resource deploys through the same
+CloudFormation path every other AWS resource does.
+
+## The typed handoff
+
+`avpPolicyDefinition(name, props)` returns exactly the `Definition` property
+`AWS::VerifiedPermissions::Policy` takes, rendered by the same renderer that
+writes the `.cedar` file — so the deployed policy and the reviewed file cannot
+disagree.
+
+```typescript
+import { Policy, ReadAction, avpPolicyDefinition } from "@intentius/chant-lexicon-cedar";
+import { VerifiedPermissionsPolicy } from "@intentius/chant-lexicon-aws";
+
+const ownerReadProps = {
+  effect: "permit",
+  principal: { is: "App::User" },
+  action: { eq: ReadAction },
+  resource: { is: "App::Document" },
+  when: ["resource.owner == principal"],
+} as const;
+
+/** The evaluator-agnostic artifact: this is what lands in the `.cedar` file. */
+export const ownerRead = new Policy(ownerReadProps);
+
+/** The AVP deployment view of the same policy. */
+export const ownerReadAvp = new VerifiedPermissionsPolicy({
+  PolicyStoreId: policyStore.ref(),
+  Definition: avpPolicyDefinition("ownerRead", ownerReadProps, {
+    ownership: { stack: "authz", env: "prod" },
+    description: "Owners read their own documents.",
+  }),
+});
+```
+
+Beside it: `avpStatement()` for the bare string, `avpStatementJSON()` for
+evaluators that take the JSON policy format, and `avpPolicySet(entities)` to
+render a whole build's policies at once, keyed by chant entity name.
+
+**The cedar lexicon does not depend on the aws lexicon.** The seam is the data
+shape, which is stable CloudFormation. `examples/avp-embedding/` shows the
+pairing with a plain-object stand-in, because the shipped cedar examples build
+against the cedar serializer alone.
+
+## The lifecycle surface
+
+`describeResources()`, `observeAmbient()` and `exportResources()` read a live
+policy store. Point them at one with `CEDAR_AVP_POLICY_STORE_ID` (or
+`CEDAR_AVP_POLICY_STORE_ID_<ENV>`), or a `policyStoreId` prop on a declared
+policy.
+
+The link from a chant entity to a live policy is the Cedar `@id` annotation,
+which is derived from the export name (`ownerRead` → `owner-read`) unless
+`annotations.id` overrides it. Rename an export and the observation follows it;
+rename it *and* pin `annotations.id` and the live policy stays matched.
+
+## Rules
+
+- **Do not write the statement as prose.** A hand-typed
+  `"permit(principal, action, resource);"` in an AVP resource is the exact thing
+  this lexicon exists to remove, and the meta-policy wall (see the
+  `chant-cedar-meta-policy` skill) fails a bare permit in a prod build.
+- **Do not try to tag an individual policy.** AVP policy *stores* are taggable;
+  individual policies are not — `CreatePolicy` has no tag surface and a policy
+  has no ARN. chant's per-policy marker therefore rides in the policy
+  description, stamped by passing `ownership` to `avpPolicyDefinition` and read
+  back by `describeResources`/`exportResources`. Store tags remain the coarse
+  channel. The design record, including what the choice costs, is
+  `src/avp/OWNERSHIP.md`.
+- **Do not hand-write the description when you want ownership.** Pass
+  `ownership` and let the marker be encoded; the description is capped at 150
+  characters and the encoder truncates prose rather than the marker, which is
+  what keeps a chant-owned policy from silently reading as foreign.
+- **Do not treat an ambient permit as housekeeping.** A permit found in a store
+  that no source file declares is a standing grant somebody made outside review.
+  It is a security finding. `observeAmbient()` reports the statement and its
+  effect and stops short of the verdict — the judgement is yours.
+
+## Non-AVP evaluators
+
+AVP is not the only target, and the lexicon does not privilege it. The same
+emitted `.cedar` and `policies.cedar.json` feed:
+
+- **cedar-agent** — a standalone Cedar decision service; point it at the policy
+  file and the entity store.
+- **An embedded `cedar-wasm`** — the package this lexicon already depends on.
+  Load the policy text in-process and call `isAuthorized`.
+- **Cloudflare-style embeddings** — the same file, read at the edge.
+
+If the deployment target is anything other than AVP, there is no embedding step
+at all. Emit the files and ship them.
+
+## Cedar-for-Kubernetes
+
+The CNCF push includes Cedar as a Kubernetes authorizer, with policies as CRDs.
+Those kinds belong to the k8s lexicon's CRD sources — the same rule that kept
+`helm.cattle.io` out of the k3s lexicon. What the cedar lexicon does there is
+lint the policy *text* embedded in those kinds, which is the pattern the ARGO
+rules already use.

package/dist/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-cedar",
-  "version": "0.44.8",
+  "version": "0.44.9",
   "description": "Cedar lexicon for chant — typed authoring for Cedar authorization policies",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -69,7 +69,7 @@
   },
   "peerDependencies": {
     "zod": "^4.3.6",
-    "@intentius/chant": "^0.44.8",
+    "@intentius/chant": "^0.44.9",
     "typescript": "^5.9.3"
   }
 }

package/src/codegen/package.ts

@@ -2,10 +2,12 @@
  * Cedar lexicon packaging — delegates to core's packagePipeline.
  */
 
+import { cedarPlugin } from "../plugin";
 import { readFileSync } from "fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
 import {
+  collectSkills,
   packagePipeline,
   type PackageOptions,
   type PackageResult,
@@ -42,8 +44,7 @@ export async function packageLexicon(opts: PackageOptions = {}): Promise<Package
 
       srcDir: pkgDir,
 
-      // Skills, initTemplates and the docs site are #1654.
-      collectSkills: () => new Map(),
+      collectSkills: () => collectSkills(cedarPlugin.skills?.() ?? []),
 
       version: pkgJson.version ?? "0.0.0",
     },

package/src/config.test.ts

@@ -37,6 +37,18 @@ describe("cedar config namespace", () => {
   it("leaves everything optional, so an empty namespace is legal", () => {
     expect(cedarConfigSchema.parse({})).toEqual({});
   });
+
+  it("takes the dogwood binary path (#1659)", () => {
+    const parsed = cedarConfigSchema.parse({ dogwood: { binary: "../dogwood/target/release/dogwood" } });
+    expect(parsed.dogwood?.binary).toBe("../dogwood/target/release/dogwood");
+  });
+
+  it("rejects a typo in the dogwood namespace, where a silent skip would follow", () => {
+    // A misspelled key here means "no binary found", and "no binary found" is
+    // an advisory rather than a failure — exactly the case strictObject exists
+    // to catch before it turns into a validation gap nobody notices.
+    expect(() => cedarConfigSchema.parse({ dogwood: { path: "/usr/local/bin/dogwood" } })).toThrow();
+  });
 });
 
 describe("schema resolution", () => {

package/src/config.ts

@@ -71,6 +71,34 @@ export const cedarConfigSchema = z.strictObject({
       requireProjectSchema: z.boolean().optional(),
     })
     .optional(),
+
+  /**
+   * The dogwood dialect's CLI-gated leg (#1659).
+   *
+   * `strictObject` again, for the reason the outer one is: a typo here is the
+   * difference between "full .dw validation ran" and "DWDE010 said it could
+   * not run", and the second is easy to skim past.
+   */
+  dogwood: z
+    .strictObject({
+      /**
+       * Path to the `dogwood` binary, absolute or relative to the config file.
+       *
+       * Optional, and its absence is not an error: DWDE010 warns-and-skips
+       * with an issue-linked advisory when no binary is found, which is the
+       * epic's explicit exception. Set this when the binary is built somewhere
+       * `PATH` does not reach — the on-demand harness shape the epic borrows
+       * from forgejo-runtime-e2e.
+       *
+       * A `chant.config.ts` cannot be read from inside a post-synth check —
+       * `check()` is synchronous and evaluating project code is not — so this
+       * key is honoured from `chant.config.json` and the `CHANT_DOGWOOD_BINARY`
+       * environment variable covers the TypeScript-config case. See
+       * `src/dogwood/cli.ts`.
+       */
+      binary: z.string().optional(),
+    })
+    .optional(),
 });
 
 export type CedarConfig = z.infer<typeof cedarConfigSchema>;