@intentius/chant-lexicon-cedar 0.124.31 → 0.124.32

package/dist/plugin.js

@@ -0,0 +1,304 @@
+import { createSkillsLoader } from "@intentius/chant/lexicon-plugin-helpers";
+import { cedarSerializer } from "./serializer.js";
+import { rules } from "./lint/rules/index.js";
+import { postSynthChecks as cedarPostSynthChecks } from "./lint/post-synth/index.js";
+import { cedarAuditCatalog } from "./lint/audit-catalog.js";
+import { completions } from "./lsp/completions.js";
+import { hover } from "./lsp/hover.js";
+import { cedarMcpResources, cedarMcpTools } from "./mcp/index.js";
+import { cedarInitTemplates } from "./init-templates.js";
+import { cedarConfigSchema } from "./config.js";
+import { detectTemplate as detectCedarTemplate } from "./detect.js";
+import { CedarTemplateGenerator, CedarTemplateParser } from "./import/adapter.js";
+import { AVP_OWNERSHIP_KEYS } from "./avp/ownership.js";
+import { AVP_AMBIENT_KINDS } from "./avp/ambient.js";
+import { cedarCommandGroup } from "./commands.js";
+/**
+ * cedar lexicon plugin.
+ *
+ * Implements all required LexiconPlugin lifecycle methods.
+ */
+export const cedarPlugin = {
+    name: "cedar",
+    serializer: cedarSerializer,
+    // ── Required lifecycle methods ────────────────────────────────
+    async generate(options) {
+        // Cedar's codegen input is the project's own schema, so the `cedar` config
+        // namespace is read here rather than being decoration (#1650).
+        //
+        // The output goes into the *project* (#1696): `cedar.outDir`, else
+        // `src/generated/cedar` under the config's directory. Only when the project
+        // is this package itself does it land in `src/generated/`.
+        const { generate, resolveGeneratedDir, writeGeneratedFiles } = await import("./codegen/generate.js");
+        const { loadCedarProject } = await import("./config.js");
+        const { projectRoot, config } = await loadCedarProject(process.cwd());
+        const result = await generate({ ...options, projectRoot, config });
+        const outDir = resolveGeneratedDir({ projectRoot, config });
+        writeGeneratedFiles(result, outDir);
+        if (options?.verbose)
+            console.error(`cedar: wrote generated classes to ${outDir}`);
+    },
+    async validate(options) {
+        const { validate } = await import("./validate.js");
+        const { printValidationResult } = await import("@intentius/chant/codegen/validate");
+        const result = await validate();
+        printValidationResult(result);
+    },
+    async coverage(options) {
+        const { analyzeCedarCoverage } = await import("./coverage.js");
+        const { resolveGeneratedDir } = await import("./codegen/generate.js");
+        const { loadCedarProject } = await import("./config.js");
+        const { projectRoot, config } = await loadCedarProject(process.cwd());
+        analyzeCedarCoverage({
+            projectRoot,
+            config,
+            // Coverage compares the project's schema with the project's generated
+            // artifacts, which live where generate put them (#1696).
+            generatedDir: resolveGeneratedDir({ projectRoot, config }),
+            verbose: options?.verbose,
+            minOverall: options?.minOverall,
+        });
+    },
+    async package(options) {
+        const { packageLexicon } = await import("./codegen/package.js");
+        const { writeBundleSpec } = await import("@intentius/chant/codegen/package");
+        const { join, dirname } = await import("path");
+        const { fileURLToPath } = await import("url");
+        const { spec, stats } = await packageLexicon(options);
+        const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+        writeBundleSpec(spec, join(pkgDir, "dist"));
+        console.error(`Packaged ${stats.resources} resources, ${stats.ruleCount} rules, ${stats.skillCount} skills`);
+    },
+    // ── Optional extensions ────────────────────────────────────
+    // #1697 — the project's `.cedarschema` joins the build as a `Cedar::Schema`
+    // entity, so it is emitted beside the policies and CEDE010 validates
+    // against it rather than reporting that it could not. Nothing is
+    // contributed when only the bundled default schema applies.
+    async buildRoots(ctx) {
+        const { schemaBuildRoot } = await import("./schema-artifact.js");
+        return schemaBuildRoot(ctx);
+    },
+    // `chant cedar generate` and `chant cedar coverage` (#1696, via #1078).
+    commands() {
+        return cedarCommandGroup();
+    },
+    lintRules() {
+        return rules;
+    },
+    postSynthChecks() {
+        // Auto-discovered from lint/post-synth/ and committed as a static barrel
+        // by `npm run generate:barrels` — adding a check is dropping a file.
+        return cedarPostSynthChecks;
+    },
+    auditCatalog() {
+        return cedarAuditCatalog;
+    },
+    skills: createSkillsLoader(import.meta.url, [
+        {
+            file: "chant-cedar-authoring.md",
+            name: "chant-cedar-authoring",
+            description: "Author Cedar policies as typed chant resources — schema to generated classes to .cedar and JSON outputs",
+            triggers: [
+                { type: "file-pattern", value: "**/*.cedarschema" },
+                { type: "file-pattern", value: "**/policies.ts" },
+                { type: "context", value: "cedar policy" },
+                { type: "context", value: "cedar schema" },
+                { type: "context", value: "authorization policy" },
+            ],
+            parameters: [],
+            examples: [
+                {
+                    title: "Owner-scoped permit",
+                    description: "Grant an action to the owner of a resource",
+                    input: "Let users read documents they own",
+                    output: `new Policy({ principal: { is: "App::User" }, action: { eq: ReadAction }, when: ["resource.owner == principal"] })`,
+                },
+            ],
+        },
+        {
+            file: "chant-cedar-avp-embedding.md",
+            name: "chant-cedar-avp-embedding",
+            description: "Embed a typed cedar-lexicon policy into an AWS Verified Permissions policy resource instead of a hand-written string",
+            triggers: [
+                { type: "context", value: "verified permissions" },
+                { type: "context", value: "avp policy store" },
+                { type: "context", value: "cedar deployment" },
+                { type: "context", value: "cedar-agent" },
+            ],
+            parameters: [],
+            examples: [
+                {
+                    title: "Policy destined for a policy store",
+                    input: "Deploy this Cedar policy to Verified Permissions",
+                    output: "Emit the .cedar text and reference it — the typed statement seam lands with #1652",
+                },
+            ],
+        },
+        {
+            file: "chant-cedar-meta-policy.md",
+            name: "chant-cedar-meta-policy",
+            description: "Organizational policy over Cedar policy sets — the bare-permit wall, forbid conventions, and env-aware severity",
+            triggers: [
+                { type: "context", value: "cedar lint" },
+                { type: "context", value: "bare permit" },
+                { type: "context", value: "policy review" },
+                { type: "context", value: "meta-policy" },
+            ],
+            parameters: [],
+            examples: [
+                {
+                    title: "The bare-permit wall",
+                    input: "Is `permit (principal, action, resource);` acceptable?",
+                    output: "Warn in dev and staging; fail the build in prod",
+                },
+            ],
+        },
+        {
+            file: "chant-cedar-dogwood.md",
+            name: "chant-cedar-dogwood",
+            description: "Author dogwood temporal policies with the typed builders — parser primitives versus default-library macros, the callerPrincipal pin, the CLI-gated validation split, AgentCore embedding and trace replay",
+            triggers: [
+                { type: "file-pattern", value: "**/*.dw" },
+                { type: "file-pattern", value: "**/*.dwschema" },
+                { type: "context", value: "dogwood" },
+                { type: "context", value: "temporal policy" },
+                { type: "context", value: "agentcore policy" },
+                { type: "context", value: "rate limit policy" },
+                { type: "context", value: "policy replay" },
+            ],
+            parameters: [],
+            examples: [
+                {
+                    title: "Approval before action",
+                    description: "Allow a read only if a login happened inside the window",
+                    input: "Only let them read if they logged in within the last hour",
+                    output: `whenTemporal: [dogwood.formerly("1h", dogwood.predicate('Drupe::Action::"Login"', "response"))]`,
+                },
+                {
+                    title: "The macro caveat",
+                    input: "Use count_within for a rate limit",
+                    output: "count_within is a default-library macro a --macros caller replaces — emit the call and ship the definition, or build it from `count for … where`",
+                },
+            ],
+        },
+    ]),
+    initTemplates(template) {
+        // The branch names are spelled out here rather than only in
+        // ./init-templates.ts because `chant dev check-lexicon` counts a lexicon's
+        // templates by scanning this file. The content lives next door.
+        if (template === "avp-embedding")
+            return cedarInitTemplates("avp-embedding");
+        if (template === "gateway-policy-set")
+            return cedarInitTemplates("gateway-policy-set");
+        return cedarInitTemplates(template);
+    },
+    mcpTools() {
+        return cedarMcpTools();
+    },
+    mcpResources() {
+        // `createCatalogResource` resolves the registry relative to the module URL
+        // it is handed, so it needs this file's — src/generated/, not src/mcp/.
+        return cedarMcpResources(import.meta.url);
+    },
+    detectTemplate(data) {
+        return detectCedarTemplate(data);
+    },
+    /** `.cedar` text and the JSON policy-set envelope, into the core IR (#1653). */
+    templateParser() {
+        return new CedarTemplateParser();
+    },
+    /** The IR back out as `new Policy({ … })` against the generated classes. */
+    templateGenerator() {
+        return new CedarTemplateGenerator();
+    },
+    completionProvider(ctx) {
+        return completions(ctx);
+    },
+    hoverProvider(ctx) {
+        return hover(ctx);
+    },
+    async docs(options) {
+        const { generateDocs } = await import("./codegen/docs.js");
+        return generateDocs(options);
+    },
+    /** The shape of the `cedar` key in `chant.config.ts` — see ./config.ts. */
+    configSchema: cedarConfigSchema,
+    /**
+     * The pinned upstream is the Cedar *grammar*, not a downloaded spec (#1650).
+     *
+     * `CEDAR_WASM_VERSION` is the package version the self-upgrade tooling bumps;
+     * `CEDAR_LANG_VERSION` beside it is the language version `generate()` asserts
+     * at runtime, since a package bump that leaves the language at 4.5 cannot
+     * change what parses. Both live in src/spec/pin.ts, which also carries the
+     * content pin over the bundled default schema.
+     */
+    upstreamPin: {
+        file: "src/spec/pin.ts",
+        pattern: /export const CEDAR_WASM_VERSION\s*=\s*"([^"]+)"/,
+        replace: (v, line) => line.replace(/= "[^"]+"/, `= "${v}"`),
+        upstream: { owner: "cedar-policy", repo: "cedar", kind: "releases" },
+    },
+    // ── AVP lifecycle (#1652) ──────────────────────────────────────
+    /**
+     * AVP policy stores are taggable; the policies inside them are not, so the
+     * per-policy channel is a marker encoded into `Definition.Static.Description`
+     * and the store's tags are the coarse channel beside it. Only the two paths
+     * that actually read the description are declared (chant #1348) — the full
+     * design record is src/avp/OWNERSHIP.md.
+     */
+    ownershipChannel: {
+        keys: AVP_OWNERSHIP_KEYS,
+        reads: ["describeResources", "exportResources"],
+    },
+    /**
+     * Observe the declared policy set against a live AVP policy store.
+     *
+     * The tri-state carries more weight here than on most substrates: a declared
+     * policy reported absent becomes a `create`, and creating a permit that
+     * already exists duplicates a grant. Every path that did not look says so.
+     */
+    async describeResources(options) {
+        const { describeAvpResources } = await import("./avp/describe-resources.js");
+        return describeAvpResources({
+            environment: options.environment,
+            entityNames: options.entityNames,
+            entities: options.entities,
+            ...(options.owned !== undefined ? { owned: options.owned } : {}),
+            ...(options.region ? { client: { region: options.region } } : {}),
+        });
+    },
+    /** The one kind this lexicon deploys, and therefore the one it can enumerate. */
+    ambientKinds() {
+        return [...AVP_AMBIENT_KINDS];
+    },
+    /**
+     * Policies in the store that nothing declares — a standing grant nobody in
+     * the source tree can see. For an authorization store this is a security
+     * finding rather than housekeeping.
+     */
+    async observeAmbient(options) {
+        const { observeAvpAmbient } = await import("./avp/ambient.js");
+        return observeAvpAmbient({
+            environment: options.environment,
+            kinds: options.kinds,
+            observed: options.observed,
+            ...(options.region ? { client: { region: options.region } } : {}),
+        });
+    },
+    /**
+     * Full-fidelity read of the live policies, as import IR. Server-written
+     * fields are stripped to the declared shape unless `verbatim` is set — see
+     * the note in src/avp/live-export.ts for what counts as server-written when
+     * the only thing a user authors is the statement.
+     */
+    async exportResources(options) {
+        const { exportAvpResources } = await import("./avp/live-export.js");
+        return exportAvpResources({
+            environment: options.environment,
+            ...(options.selector ? { selector: options.selector } : {}),
+            ...(options.owned !== undefined ? { owned: options.owned } : {}),
+            ...(options.verbatim !== undefined ? { verbatim: options.verbatim } : {}),
+            ...(options.region ? { client: { region: options.region } } : {}),
+        });
+    },
+};

package/dist/policy-text.js

@@ -0,0 +1,117 @@
+/**
+ * Cedar policy-text rendering, shared by the `.cedar` serializer, the AVP
+ * statement renderer, and the dogwood dialect's `.dw` leg.
+ *
+ * Upstream's dogwood policy grammar is Cedar's shape — `annotation* effect
+ * "(" scope ")" cond* ";"` — and only the `cond` rule differs, gaining
+ * `guardrails { … }` and `temporal { … }` forms. So everything above the first
+ * clause is common, and it lives here rather than being copied into
+ * `./dogwood/serialize.ts`, where a change to how a scope constraint is
+ * written would have had to be made twice.
+ *
+ * `resolvePolicyId` is here for the same reason it was extracted from
+ * `serialize()` by #1652: it is the only rule linking a chant entity to a
+ * policy id, the AVP observation matches against it, and the `.dw` leg has to
+ * derive ids the same way the `.cedar` leg does. One copy, three callers.
+ *
+ * This module is a leaf on purpose: `./serializer.ts` and `./dogwood/*` both
+ * import it, and neither imports the other's rendering.
+ */
+import { isResourceDeclarable } from "@intentius/chant/declarable";
+/** A plain object — not null, not an array. */
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** The `props` of a resource-kind Declarable, or `{}` for anything else. */
+export function getProps(entity) {
+    if (isResourceDeclarable(entity) && isRecord(entity.props)) {
+        return entity.props;
+    }
+    return {};
+}
+/** Escape a string for a double-quoted Cedar literal. */
+export function escapeCedarString(value) {
+    return value
+        .replace(/\\/g, "\\\\")
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, "\\n")
+        .replace(/\r/g, "\\r")
+        .replace(/\t/g, "\\t");
+}
+/**
+ * Derive a policy id from a logical name: `allowAdminRead` → `allow-admin-read`.
+ * Cedar ids are free-form strings; kebab-case keeps them readable in the
+ * `@id` annotation and stable across a rename-free refactor.
+ */
+export function policyIdFromLogicalName(name) {
+    return name
+        .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2")
+        .replace(/[\s_]+/g, "-")
+        .toLowerCase();
+}
+/**
+ * The Cedar id for a policy: an explicit `annotations.id` when the author gave
+ * one, else derived from the logical name.
+ *
+ * This is the only rule that links a chant entity to a policy in a live AVP
+ * store (#1652) — the observation resolves the same id from the same props and
+ * matches it against the `@id` annotation the statement carries — and it is
+ * also what gives a `.dw` policy the id its `.cedar` sibling would have had.
+ * Two copies of this rule would be a mapping that drifts silently.
+ */
+export function resolvePolicyId(logicalName, props) {
+    const explicit = isRecord(props.annotations) ? props.annotations.id : undefined;
+    return typeof explicit === "string" && explicit.length > 0
+        ? explicit
+        : policyIdFromLogicalName(logicalName);
+}
+function refText(value) {
+    return String(value);
+}
+/** `principal`, `principal == User::"alice"`, `action in [ … ]`, `resource is Photo`. */
+export function renderScope(variable, scope) {
+    if (!isRecord(scope))
+        return variable;
+    const parts = [variable];
+    if (typeof scope.is === "string")
+        parts.push(`is ${scope.is}`);
+    if (scope.eq !== undefined)
+        parts.push(`== ${refText(scope.eq)}`);
+    if (scope.in !== undefined) {
+        parts.push(Array.isArray(scope.in)
+            ? `in [${scope.in.map(refText).join(", ")}]`
+            : `in ${refText(scope.in)}`);
+    }
+    return parts.join(" ");
+}
+/** A `when`/`unless` prop as a list of clause bodies — one string, or several. */
+export function conditionStrings(value) {
+    if (value === undefined || value === null)
+        return [];
+    if (Array.isArray(value))
+        return value.map(refText);
+    return [refText(value)];
+}
+/**
+ * Everything above the first clause: the annotations, the effect, and the
+ * three scope positions.
+ */
+export function renderPolicyHead(id, props) {
+    const lines = [];
+    // @id first, then the author's own annotations in declaration order.
+    const annotations = isRecord(props.annotations) ? props.annotations : {};
+    lines.push(`@id("${escapeCedarString(id)}")`);
+    for (const [key, value] of Object.entries(annotations)) {
+        if (key === "id" || value === undefined || value === null)
+            continue;
+        lines.push(`@${key}("${escapeCedarString(refText(value))}")`);
+    }
+    const effect = props.effect === "forbid" ? "forbid" : "permit";
+    lines.push(`${effect} (`);
+    lines.push(`  ${renderScope("principal", props.principal)},`);
+    lines.push(`  ${renderScope("action", props.action)},`);
+    lines.push(`  ${renderScope("resource", props.resource)}`);
+    lines.push(")");
+    return lines;
+}

package/dist/schema-artifact.js

@@ -0,0 +1,66 @@
+/**
+ * The project schema as a build artifact (#1697).
+ *
+ * CEDE010 can only validate a policy set against a schema the build emitted
+ * beside it, and until now nothing emitted one: the `.cedarschema` drove
+ * codegen and then stayed in the source tree, so every consumer build got the
+ * parse-only advisory. This module closes that gap from two directions.
+ *
+ * `Schema` is a declarable a project can author by hand when it wants a
+ * particular filename or a schema that is not the one in `chant.config.ts`.
+ * `schemaBuildRoot` is the automatic path: the plugin's `buildRoots` hook
+ * contributes one `Schema` entity per build, holding the resolved project
+ * schema, so a project with a `cedar.schema` gets `dist/schema.cedarschema`
+ * and full validation without declaring anything.
+ *
+ * The bundled default schema is never emitted. A project without its own
+ * schema has policies the default may well reject, and CEDE010 failing a
+ * build against a schema the project never wrote would be a worse surprise
+ * than the advisory it replaces.
+ */
+import { isPropertyDeclarable } from "@intentius/chant/declarable";
+import { createResource } from "@intentius/chant/runtime";
+import { getProps } from "./policy-text.js";
+import { resolveSchemaPath } from "./spec/fetch.js";
+import { readFileSync } from "fs";
+import { basename } from "path";
+/** The entity type of a {@link Schema}. */
+export const CEDAR_SCHEMA_TYPE = "Cedar::Schema";
+/** The logical name the build-root contribution uses. */
+export const CEDAR_SCHEMA_ENTITY_NAME = "cedarSchema";
+/** Filename the schema is emitted under when `filename` is unset. */
+export const CEDAR_SCHEMA_FILENAME = "schema.cedarschema";
+/** A `.cedarschema` emitted with the policy set, so post-synth validation has something to validate against. */
+export const Schema = createResource(CEDAR_SCHEMA_TYPE, "cedar", {});
+/** Every `Cedar::Schema` in the entity map, with its props read. */
+export function schemaEntities(entities) {
+    const files = [];
+    for (const [name, entity] of entities) {
+        if (isPropertyDeclarable(entity))
+            continue;
+        if (entity.entityType !== CEDAR_SCHEMA_TYPE)
+            continue;
+        const props = getProps(entity);
+        if (typeof props.text !== "string")
+            continue;
+        files.push({
+            name,
+            filename: typeof props.filename === "string" ? props.filename : CEDAR_SCHEMA_FILENAME,
+            text: props.text.endsWith("\n") ? props.text : props.text + "\n",
+        });
+    }
+    return files;
+}
+/**
+ * The `buildRoots` contribution: the project's resolved schema as one
+ * {@link Schema} entity, or nothing when only the bundled default applies.
+ */
+export async function schemaBuildRoot(ctx) {
+    const config = ctx.config.cedar ?? {};
+    const source = resolveSchemaPath({ projectRoot: ctx.projectRoot, config });
+    if (source.isDefault)
+        return { entities: new Map() };
+    const text = readFileSync(source.path, "utf-8");
+    const entity = new Schema({ text, filename: basename(source.path) });
+    return { entities: new Map([[CEDAR_SCHEMA_ENTITY_NAME, entity]]) };
+}