@intentius/chant-lexicon-cedar 0.44.8

package/src/avp/embed.ts

@@ -0,0 +1,190 @@
+/**
+ * Typed embedding of a cedar policy into `AWS::VerifiedPermissions::Policy`
+ * (#1652).
+ *
+ * The aws lexicon keeps the deployment vehicle — its generated
+ * `VerifiedPermissionsPolicy` takes a required `PolicyStoreId` and a required
+ * `Definition`, and the `Definition.Static.Statement` inside it is an opaque
+ * string. Opaque is the problem the whole cedar lexicon exists to remove: today
+ * a team writes that string with `${}` templating and finds out at deploy time
+ * whether the entity type exists.
+ *
+ * This module closes the loop without joining the two lexicons together. It
+ * emits the *string* and the *JSON envelope* AVP expects and stops there:
+ * nothing here imports `@intentius/chant-lexicon-aws`, and nothing here needs
+ * to. A project that has both installed writes
+ *
+ * ```ts
+ * new VerifiedPermissionsPolicy({
+ *   PolicyStoreId: store.ref(),
+ *   Definition: avpPolicyDefinition("ownerRead", ownerReadProps),
+ * });
+ * ```
+ *
+ * and the statement is the same text `chant build` writes to `.cedar`, rendered
+ * by the same renderer, with `@id` intact.
+ *
+ * ### Why no dependency, and why the example uses plain objects
+ *
+ * A cedar → aws dependency would invert the epic's decision that Cedar is
+ * vendor-neutral and AVP is one of several evaluators, and it would make the
+ * cedar lexicon unbuildable without the aws one. The seam is therefore the
+ * data shape, which is stable CloudFormation, and
+ * `examples/avp-embedding/` demonstrates the pairing with a plain-object stand-in
+ * for `VerifiedPermissionsPolicy` — the shipped examples build with the cedar
+ * serializer alone, so a real cross-lexicon example could not run in this
+ * repo's example harness at all. The stand-in carries the exact prop names the
+ * generated class declares (`PolicyStoreId`, `Definition`, `Name`), so the
+ * substitution is a one-line edit in a real project.
+ */
+
+import type { Declarable } from "@intentius/chant/declarable";
+import type { OwnershipMarker } from "@intentius/chant/ownership";
+import {
+  cedarPolicyRecords,
+  renderPolicyText,
+  resolvePolicyId,
+  type CedarPolicyProps,
+} from "../serializer";
+import { policyToJson, type PolicyJson } from "../spec/wasm";
+import { encodeOwnershipDescription } from "./ownership";
+
+/** `Definition.Static` — the static-policy half of the AVP definition union. */
+export interface AvpStaticDefinition {
+  Statement: string;
+  Description?: string;
+}
+
+/** The `Definition` property of `AWS::VerifiedPermissions::Policy`. */
+export interface AvpPolicyDefinition {
+  Static: AvpStaticDefinition;
+}
+
+/** The props of `AWS::VerifiedPermissions::Policy` this module can fill. */
+export interface AvpPolicyResource {
+  PolicyStoreId: string;
+  Definition: AvpPolicyDefinition;
+}
+
+export interface AvpEmbedOptions {
+  /**
+   * Ownership marker to stamp into the description — the per-policy channel
+   * (see ./ownership.ts). Supply it and `describeResources`/`exportResources`
+   * can tell this policy from one somebody added in the console.
+   */
+  ownership?: OwnershipMarker;
+  /** The author's own description, kept ahead of the marker. */
+  description?: string;
+  /** Override the Cedar id. Defaults to the serializer's own derivation. */
+  policyId?: string;
+}
+
+function propsRecord(props: CedarPolicyProps | Record<string, unknown>): Record<string, unknown> {
+  return props as Record<string, unknown>;
+}
+
+/**
+ * The Cedar policy text for one policy — the exact string
+ * `Definition.Static.Statement` wants.
+ *
+ * `name` is the chant entity name; the `@id` annotation the statement carries
+ * is derived from it the same way the serializer derives it, which is what lets
+ * the live observation match a policy in the store back to the entity that
+ * declared it.
+ */
+export function avpStatement(
+  name: string,
+  props: CedarPolicyProps | Record<string, unknown>,
+  options: AvpEmbedOptions = {},
+): string {
+  const record = propsRecord(props);
+  return renderPolicyText(options.policyId ?? resolvePolicyId(name, record), record);
+}
+
+/**
+ * The Cedar JSON policy format for one policy — for an evaluator that takes
+ * JSON rather than text (`cedar-agent`, an embedded `cedar-wasm`).
+ *
+ * Not what AVP's `Definition` wants; AVP takes the text. Emitted here so the
+ * seam is documented in both directions rather than only the AWS one.
+ *
+ * Built the way the serializer's JSON leg is built (#1653): render the text,
+ * then hand it to `cedar-wasm`, so what comes back is Cedar's own reading
+ * rather than a second, worse encoder. Throws on text Cedar refuses — this is
+ * an authoring-time call, and a policy the module cannot read is a defect the
+ * caller wants to hear about rather than a `undefined` to thread through.
+ */
+export function avpStatementJSON(
+  name: string,
+  props: CedarPolicyProps | Record<string, unknown>,
+  options: AvpEmbedOptions = {},
+): PolicyJson {
+  const statement = avpStatement(name, props, options);
+  const converted = policyToJson(statement);
+  if (!converted.ok) {
+    throw new Error(`cedar: ${name} did not parse, so no JSON form could be produced — ${converted.error}`);
+  }
+  return converted.value;
+}
+
+/**
+ * The `Definition` property of `AWS::VerifiedPermissions::Policy`.
+ *
+ * With `options.ownership` set, the description carries chant's marker — the
+ * only per-policy ownership channel AVP has, because policies are not taggable.
+ */
+export function avpPolicyDefinition(
+  name: string,
+  props: CedarPolicyProps | Record<string, unknown>,
+  options: AvpEmbedOptions = {},
+): AvpPolicyDefinition {
+  const record = propsRecord(props);
+  const policyId = options.policyId ?? resolvePolicyId(name, record);
+  const description = options.ownership
+    ? encodeOwnershipDescription(options.description, options.ownership, policyId)
+    : options.description?.trim();
+
+  return {
+    Static: {
+      Statement: renderPolicyText(policyId, record),
+      ...(description ? { Description: description } : {}),
+    },
+  };
+}
+
+/**
+ * Both required props of `AWS::VerifiedPermissions::Policy`, ready to spread
+ * into the generated class.
+ *
+ * `PolicyStoreId` is a string here rather than an AttrRef because this module
+ * does not know the aws lexicon's reference types. A project passes
+ * `store.ref()` in place of the literal and TypeScript is satisfied by the
+ * generated class's own prop type, not by this one.
+ */
+export function avpPolicyResource(
+  name: string,
+  props: CedarPolicyProps | Record<string, unknown>,
+  policyStoreId: string,
+  options: AvpEmbedOptions = {},
+): AvpPolicyResource {
+  return { PolicyStoreId: policyStoreId, Definition: avpPolicyDefinition(name, props, options) };
+}
+
+/**
+ * Every `Cedar::Policy` in a build, rendered as AVP definitions and keyed by
+ * chant entity name.
+ *
+ * The whole-set form: one call turns a policy set into the definitions a stack
+ * of `VerifiedPermissionsPolicy` declarations needs, with references between
+ * declared entities already walked (that is what `cedarPolicyRecords` does).
+ */
+export function avpPolicySet(
+  entities: Map<string, Declarable>,
+  options: AvpEmbedOptions = {},
+): Record<string, AvpPolicyDefinition> {
+  const out: Record<string, AvpPolicyDefinition> = {};
+  for (const { name, id, props } of cedarPolicyRecords(entities)) {
+    out[name] = avpPolicyDefinition(name, props, { ...options, policyId: id });
+  }
+  return out;
+}

package/src/avp/live-export.test.ts

@@ -0,0 +1,232 @@
+import { describe, expect, it } from "vitest";
+import { checkParsePolicySet } from "@cedar-policy/cedar-wasm/nodejs";
+import { CEDAR_POLICY_TYPE, type CedarPolicyProps } from "../serializer";
+import { avpStatement } from "./embed";
+import { exportAvpResources, policyToResourceIR } from "./live-export";
+import {
+  markedDescription,
+  mockAvpTransport,
+  MOCK_ENV,
+  type MockStore,
+} from "./testdata/mock-transport";
+
+const STORE = "PS-abc123";
+
+const OWNER_READ = `@id("owner-read")
+@doc("Owners always read their own documents.")
+permit (
+  principal is App::User,
+  action in [App::Action::"read", App::Action::"list"],
+  resource is App::Document
+)
+when { resource.owner == principal }
+unless { context.mfa == false };`;
+
+const RESTRICT_DELETE = `@id("restrict-delete")
+forbid (
+  principal,
+  action == App::Action::"delete",
+  resource is App::Document
+)
+when { resource.classification == "confidential" };`;
+
+const store: MockStore = {
+  policyStoreId: STORE,
+  policies: [
+    {
+      policyId: "p-2",
+      statement: RESTRICT_DELETE,
+      description: "added in the console",
+      createdDate: "2026-01-01T00:00:00Z",
+    },
+    {
+      policyId: "p-1",
+      statement: OWNER_READ,
+      description: markedDescription("owner-read", "Owners read their own."),
+      lastUpdatedDate: "2026-08-01T00:00:00Z",
+    },
+  ],
+};
+
+function run(options: Partial<Parameters<typeof exportAvpResources>[0]> = {}) {
+  const { http } = mockAvpTransport(store);
+  return exportAvpResources({
+    environment: "prod",
+    policyStoreId: STORE,
+    client: { http },
+    env: MOCK_ENV,
+    ...options,
+  });
+}
+
+/** A live policy through `policyToResourceIR`, which is the import parser's reading of it. */
+function irFor(statement: string, verbatim = false) {
+  return policyToResourceIR(
+    {
+      policyId: "p-x",
+      policyStoreId: STORE,
+      policyType: "STATIC",
+      statement,
+      authoredDescription: "",
+      marked: false,
+    },
+    { verbatim },
+  );
+}
+
+describe("reading a live statement back", () => {
+  it("goes through the import parser, so the id is the Cedar policy id", () => {
+    // Not `ownerRead`: turning a policy id into a TypeScript identifier is
+    // CedarGenerator's job downstream, and doing it here too applies it twice.
+    expect(irFor(OWNER_READ)?.logicalId).toBe("owner-read");
+    expect(irFor(OWNER_READ)?.type).toBe(CEDAR_POLICY_TYPE);
+  });
+
+  it("recovers effect and all three scopes", () => {
+    const props = irFor(OWNER_READ)!.properties;
+    expect(props.effect).toBe("permit");
+    expect(props.principal).toEqual({ is: "App::User" });
+    expect(props.action).toEqual({ in: ['App::Action::"read"', 'App::Action::"list"'] });
+    expect(props.resource).toEqual({ is: "App::Document" });
+    expect(irFor(RESTRICT_DELETE)!.properties.action).toEqual({ eq: 'App::Action::"delete"' });
+  });
+
+  it("keeps the author's own condition text rather than a re-printed tree", () => {
+    const props = irFor(OWNER_READ)!.properties;
+    expect(props.when).toEqual(["resource.owner == principal"]);
+    expect(props.unless).toEqual(["context.mfa == false"]);
+  });
+
+  it("does not let a record literal or a quoted brace end a clause early", () => {
+    const statement = `@id("tricky")
+permit (principal, action, resource)
+when { context == { mfa: true, note: "}" } };`;
+    expect(irFor(statement)!.properties.when).toEqual(['context == { mfa: true, note: "}" }']);
+  });
+
+  it("files a slotted policy as a template, which is Cedar's call and not this reader's", () => {
+    const templated = `@id("linked")\npermit (principal == ?principal, action, resource);`;
+    expect(irFor(templated)?.type).toBe("Cedar::Template");
+  });
+
+  it("refuses text the parser rejects rather than half-exporting it", () => {
+    expect(irFor("this is not cedar")).toBeUndefined();
+    expect(irFor("")).toBeUndefined();
+  });
+
+  it("round-trips: live statement → props → statement the parser still accepts", () => {
+    const props = irFor(OWNER_READ)!.properties as CedarPolicyProps;
+    const rerendered = avpStatement("ownerRead", props);
+
+    expect(checkParsePolicySet({ staticPolicies: rerendered }).type).toBe("success");
+    expect(irFor(rerendered)!.properties).toEqual(props);
+  });
+});
+
+describe("exportAvpResources", () => {
+  it("returns import IR keyed by the Cedar policy id", async () => {
+    const ir = await run();
+    expect(ir.resources.map((r) => r.logicalId)).toEqual(["owner-read", "restrict-delete"]);
+    expect(ir.resources[0].type).toBe(CEDAR_POLICY_TYPE);
+    expect(ir.parameters).toEqual([]);
+    expect(ir.metadata?.policyStoreId).toBe(STORE);
+  });
+
+  it("strips the server-written record by default", async () => {
+    const ir = await run();
+    const owner = ir.resources.find((r) => r.logicalId === "owner-read")!;
+
+    expect(owner.properties.avp).toBeUndefined();
+    expect(Object.keys(owner.properties).sort()).toEqual([
+      "action",
+      "annotations",
+      "effect",
+      "principal",
+      "resource",
+      "unless",
+      "when",
+    ]);
+    // The marker in particular: baking one environment's ownership stamp into
+    // regenerated source would make every environment claim to be that one.
+    expect(JSON.stringify(owner.properties)).not.toContain("chant:managed-by");
+  });
+
+  it("keeps the whole server record under verbatim", async () => {
+    const ir = await run({ verbatim: true });
+    const owner = ir.resources.find((r) => r.logicalId === "owner-read")!;
+    const avp = owner.properties.avp as Record<string, unknown>;
+
+    expect(avp.policyId).toBe("p-1");
+    expect(avp.policyStoreId).toBe(STORE);
+    expect(avp.lastUpdatedDate).toBe("2026-08-01T00:00:00Z");
+    expect(String(avp.description)).toContain("chant:managed-by");
+    expect(avp.statement).toBe(OWNER_READ);
+  });
+
+  it("filters to chant-owned policies on owned:true", async () => {
+    const ir = await run({ owned: true });
+    expect(ir.resources.map((r) => r.logicalId)).toEqual(["owner-read"]);
+  });
+
+  it("applies a name selector", async () => {
+    expect((await run({ selector: { name: "restrict-delete" } })).resources.map((r) => r.logicalId)).toEqual([
+      "restrict-delete",
+    ]);
+  });
+
+  it("applies a type selector, and yields nothing for another lexicon's type", async () => {
+    expect((await run({ selector: { type: CEDAR_POLICY_TYPE } })).resources).toHaveLength(2);
+    expect((await run({ selector: { type: "AWS::S3::Bucket" } })).resources).toEqual([]);
+  });
+
+  it("orders resources deterministically, whatever order the store enumerates", async () => {
+    const ids = (await run()).resources.map((r) => r.logicalId);
+    expect(ids).toEqual([...ids].sort());
+  });
+
+  it("exports a store that does not exist yet as an empty template", async () => {
+    const ir = await run({ policyStoreId: "PS-other" });
+    expect(ir.resources).toEqual([]);
+  });
+
+  it("throws rather than reporting an empty estate when the read fails", async () => {
+    const { http } = mockAvpTransport({
+      ...store,
+      listFails: { code: "ThrottlingException", message: "Rate exceeded", status: 429 },
+    });
+    await expect(
+      exportAvpResources({ environment: "prod", policyStoreId: STORE, client: { http }, env: MOCK_ENV }),
+    ).rejects.toThrow(/Rate exceeded/);
+  });
+
+  it("throws when nothing binds the environment to a store", async () => {
+    const { http } = mockAvpTransport(store);
+    await expect(
+      exportAvpResources({ environment: "prod", client: { http }, env: MOCK_ENV }),
+    ).rejects.toThrow(/no AVP policy store/);
+  });
+
+  it("throws when there are no credentials", async () => {
+    const { http } = mockAvpTransport(store);
+    await expect(
+      exportAvpResources({ environment: "prod", policyStoreId: STORE, client: { http }, env: {} }),
+    ).rejects.toThrow(/no AWS credentials/);
+  });
+
+  it("drops a policy whose statement could not be read rather than exporting a hole", async () => {
+    const flaky = mockAvpTransport({
+      policyStoreId: STORE,
+      policies: [
+        { policyId: "p-1", statement: OWNER_READ, getFails: true },
+        { policyId: "p-2", statement: RESTRICT_DELETE },
+      ],
+    });
+    const ir = await exportAvpResources({
+      environment: "prod",
+      policyStoreId: STORE,
+      client: { http: flaky.http },
+      env: MOCK_ENV,
+    });
+    expect(ir.resources.map((r) => r.logicalId)).toEqual(["restrict-delete"]);
+  });
+});

package/src/avp/live-export.ts

@@ -0,0 +1,185 @@
+/**
+ * `exportResources()` against an AVP policy store (#1652).
+ *
+ * `describeResources` returns scrubbed metadata for diffing — you cannot
+ * regenerate a policy from "STATIC, last updated Tuesday". This is the other
+ * half: the live statement, parsed back into the props a `Cedar::Policy`
+ * declaration carries, as `TemplateIR` so it feeds `templateGenerator()`
+ * unchanged. The scrubbing boundary stays single-purpose; nothing here is
+ * reachable from the lifecycle paths, which consume the lexicon through
+ * `ObservationLexicon` and cannot see this method at all.
+ *
+ * ## The parse is the import parser's
+ *
+ * The live-export guide's third step is "map to `TemplateIR` by reusing your
+ * import parser", and #1653 shipped one. So a live statement goes through
+ * `CedarTemplateParser` — the same code path `chant import policies.cedar`
+ * takes — rather than a second reader that would have to re-derive scope
+ * mapping, clause-text recovery and template detection, and would drift the
+ * first time either side changed. This module's job is the AVP half: bind the
+ * store, enumerate it, decide what is server-written, and apply the filters.
+ *
+ * ## What is server-written here
+ *
+ * The live-export guide says strip to the declared shape by default and keep
+ * the rest under `verbatim`. For AVP the split is unusually clean, because the
+ * only thing a user authors is the statement. Everything else on the record —
+ * `policyId` (service-assigned), `policyStoreId`, `policyType`, `createdDate`,
+ * `lastUpdatedDate`, and the derived `principal`/`resource` summaries AVP
+ * computes from the statement — is server-written and stripped by default.
+ * `Description` is stripped too: chant's marker lives in it, so exporting it
+ * verbatim into regenerated source would bake one environment's ownership stamp
+ * into the code that produces every environment.
+ *
+ * `verbatim: true` puts all of it back under an `avp` key, raw description
+ * included.
+ */
+
+import type { ExportedTemplate, ResourceSelector } from "@intentius/chant/lexicon";
+import type { ResourceIR } from "@intentius/chant/import/parser";
+import { CedarTemplateParser } from "../import/adapter";
+import { credentialsAvailable, storeDoesNotExist, type AvpClientOptions } from "./client";
+import { descriptionIsOwned } from "./ownership";
+import { loadLivePolicies, resolvePolicyStoreId, type AvpLivePolicy } from "./store";
+
+export interface ExportAvpOptions {
+  environment: string;
+  selector?: ResourceSelector;
+  /** Restrict to policies carrying chant's description marker. */
+  owned?: boolean;
+  /** Keep the server-written AVP record alongside the authored props. */
+  verbatim?: boolean;
+  policyStoreId?: string;
+  entities?: Map<string, { entityType: string; props: Record<string, unknown> }>;
+  client?: AvpClientOptions;
+  env?: Record<string, string | undefined>;
+}
+
+/** The server-written AVP record, kept only under `verbatim`. */
+export interface AvpRecord {
+  policyId: string;
+  policyStoreId: string;
+  policyType: string;
+  description?: string;
+  createdDate?: string;
+  lastUpdatedDate?: string;
+  statement: string;
+}
+
+/**
+ * One live policy as import IR, or `undefined` when its statement could not be
+ * read or parsed.
+ *
+ * The parse is `CedarTemplateParser`'s — one policy is a policy set of one, so
+ * the same reader `chant import` uses answers here, including whether Cedar
+ * read it as a static policy or as a template (`Cedar::Policy` vs
+ * `Cedar::Template`, decided by whether it carries a slot). The `logicalId` it
+ * assigns is the Cedar policy id; turning that into a TypeScript identifier is
+ * `CedarGenerator`'s job downstream, and doing it here too would apply the
+ * transform twice.
+ *
+ * Dropping an unparseable policy is deliberate. A regenerated policy set that
+ * silently lost a `forbid` reads as a working export and is an authorization
+ * hole; a missing entry is visible.
+ */
+export function policyToResourceIR(
+  policy: AvpLivePolicy,
+  options: { verbatim?: boolean } = {},
+): ResourceIR | undefined {
+  if (!policy.statement) return undefined;
+
+  let parsed;
+  try {
+    parsed = new CedarTemplateParser().parse(policy.statement);
+  } catch {
+    return undefined;
+  }
+  const resource = parsed.resources[0];
+  if (!resource) return undefined;
+
+  const properties: Record<string, unknown> = { ...resource.properties };
+
+  if (options.verbatim) {
+    const record: AvpRecord = {
+      policyId: policy.policyId,
+      policyStoreId: policy.policyStoreId,
+      policyType: policy.policyType,
+      ...(policy.description !== undefined ? { description: policy.description } : {}),
+      ...(policy.createdDate ? { createdDate: policy.createdDate } : {}),
+      ...(policy.lastUpdatedDate ? { lastUpdatedDate: policy.lastUpdatedDate } : {}),
+      statement: policy.statement,
+    };
+    properties.avp = record;
+  }
+
+  return {
+    ...resource,
+    properties,
+    metadata: { ...resource.metadata, avpPolicyId: policy.policyId },
+  };
+}
+
+/**
+ * Read a live policy store as full-fidelity import IR.
+ *
+ * Unlike the observation, this throws when it cannot read: `chant import` has
+ * no tri-state to degrade into, and an empty template returned from a failed
+ * read would generate a source tree that deletes every policy. The one
+ * exception is a store that does not exist, which is an honest empty estate.
+ */
+export async function exportAvpResources(options: ExportAvpOptions): Promise<ExportedTemplate> {
+  const env = options.env ?? process.env;
+  const policyStoreId = resolvePolicyStoreId({
+    environment: options.environment,
+    ...(options.policyStoreId ? { policyStoreId: options.policyStoreId } : {}),
+    ...(options.entities ? { entities: options.entities } : {}),
+    env,
+  });
+
+  if (!policyStoreId) {
+    throw new Error(
+      `no AVP policy store for environment "${options.environment}" — set CEDAR_AVP_POLICY_STORE_ID or pass policyStoreId`,
+    );
+  }
+  if (!credentialsAvailable(env)) {
+    throw new Error("no AWS credentials and no endpoint override — cannot export from AVP");
+  }
+
+  let policies: AvpLivePolicy[];
+  try {
+    policies = await loadLivePolicies({
+      policyStoreId,
+      ...(options.client ? { client: options.client } : {}),
+      withStatements: true,
+    });
+  } catch (err) {
+    if (storeDoesNotExist(err)) policies = [];
+    else throw err;
+  }
+
+  const resources: ResourceIR[] = [];
+  for (const policy of policies) {
+    // Ownership is read on this path, which is what lets it be declared in
+    // `ownershipChannel.reads` (chant #1348).
+    if (options.owned && !descriptionIsOwned(policy.description)) continue;
+
+    const ir = policyToResourceIR(policy, { ...(options.verbatim ? { verbatim: true } : {}) });
+    if (!ir) continue;
+    // The type is compared against what the parser decided, not a constant:
+    // a policy carrying a `?principal`/`?resource` slot comes back as
+    // `Cedar::Template`, and `--type Cedar::Policy` should not sweep it up.
+    if (options.selector?.type !== undefined && options.selector.type !== ir.type) continue;
+    if (options.selector?.name !== undefined && ir.logicalId !== options.selector.name) continue;
+    resources.push(ir);
+  }
+
+  // Stable order: the store's enumeration order is not a contract, and an
+  // import that reshuffles the file on every run is unusable as a diff.
+  resources.sort((a, b) => a.logicalId.localeCompare(b.logicalId));
+
+  return {
+    resources,
+    parameters: [],
+    metadata: { lexicon: "cedar", policyStoreId },
+  };
+}