@intentius/chant-lexicon-cedar 0.44.8

package/README.md

@@ -0,0 +1,190 @@
+# @intentius/chant-lexicon-cedar
+
+Cedar lexicon plugin for [chant](https://github.com/intentius/chant) — typed
+authoring for [Cedar](https://www.cedarpolicy.com/) authorization policies.
+
+Cedar has no variables, no modules and no loops, and its toolchain validates
+and evaluates policies after they are written. Teams generate `.cedar` text
+with string templating today. This lexicon is the typed authoring layer above
+that text.
+
+## Status
+
+Complete. The lexicon landed across the eight sub-issues of
+INTENTIUS/chant#1645: the upstream pin (#1648), the scaffold and serializer
+(#1649), schema-driven codegen (#1650), lint and post-synth validation through
+`cedar-wasm` (#1651), AVP embedding and policy-store observation (#1652),
+import/reconcile (#1653), the docs/LSP/MCP/skills/composites surface (#1654),
+and CI/publishing onboarding (#1655).
+
+## The policy model
+
+A policy is a `Cedar::Policy` entity whose props are:
+
+| Prop | Meaning |
+|------|---------|
+| `effect` | `"permit"` or `"forbid"`; defaults to `permit` |
+| `principal`, `action`, `resource` | scope constraints — `{}` for any, or `{ eq }`, `{ in }`, `{ is }` |
+| `when`, `unless` | Cedar expression strings, one clause each |
+| `annotations` | `Record<string, string>`, emitted as `@key("value")` |
+
+The policy id comes from the export's logical name (`allowAdminRead` →
+`allow-admin-read`) unless `annotations.id` sets one.
+
+## Where the types come from
+
+`chant generate` reads a `.cedarschema` and emits a class per entity type, a
+constant per action, and a UID type per entity — so `action: { eq: ReadAction }`
+is checked at compile time and a renamed entity type is a compiler-guided
+refactor.
+
+Point it at your schema in `chant.config.ts`:
+
+```ts
+import type { ChantConfig } from "@intentius/chant";
+import "@intentius/chant-lexicon-cedar";
+
+export default {
+  lexicons: ["cedar"],
+  cedar: { schema: "schema.cedarschema" },
+} satisfies ChantConfig;
+```
+
+`cedar.schema` defaults to `schema.cedarschema` in the project root. When
+neither the configured path nor that default exists, generation falls back to
+the small application-authorization schema bundled at
+`src/spec/default-schema.cedarschema`, so a fresh checkout still produces a
+surface. Set `cedar.validation.requireProjectSchema` to turn that fallback off
+once your project has its own schema.
+
+## Pins
+
+Two, for two different things:
+
+- `CEDAR_WASM_VERSION` — the `@cedar-policy/cedar-wasm` package, bumped by the
+  weekly `cedar-upgrade` Op.
+- `CEDAR_LANG_VERSION` — the Cedar *language* that package implements (4.5).
+  `generate()` asserts it before emitting anything, because a package bump that
+  leaves the language alone cannot change what parses.
+
+Beside them, a content pin over the resolved JSON of the bundled default
+schema. It moves when the schema is edited and — the case it exists for — when
+a cedar-wasm upgrade resolves the same schema differently. Both rewrite the
+generated types, and `src/generated/` is not committed.
+
+## Output
+
+Serializing produces canonical `.cedar` policy text as the primary output and
+a Cedar JSON policy set as `policies.cedar.json` beside it. Both are consumed
+by any Cedar evaluator with chant nowhere in sight.
+
+The JSON leg is built by handing the emitted text back to `cedar-wasm`, so
+what lands on disk is Cedar's own reading of it — expression trees, not
+expression source — and a policy carrying a `?principal`/`?resource` slot is
+filed under `templates` rather than `staticPolicies` because Cedar, not this
+serializer, decides which it is. Text the module cannot parse yields a build
+warning and no JSON file, never an invalid one.
+
+## Import
+
+`chant import` reads either surface back into TypeScript:
+
+```bash
+chant import policies.cedar.json --output ./src
+```
+
+The text leg round-trips byte-for-byte — `.cedar` → props → `new Policy({ … })`
+→ `.cedar` — because condition bodies are lifted out of the source verbatim and
+then checked against the tree `cedar-wasm` makes of them. Two normalizations do
+happen on the first lap and settle after it: annotations come back
+alphabetically (they serialize into a sorted map), and interleaved
+`when`/`unless` clauses regroup, since they are separate props.
+
+Importing the JSON envelope instead has no source to quote, so its clauses come
+back as the module renders them — semantically identical, defensively
+parenthesized.
+
+## Composites
+
+Cedar has nowhere to put a repeated policy shape, so the factories live here.
+
+```ts
+import { OwnerCanManage, DenyByDefaultSet } from "@intentius/chant-lexicon-cedar";
+```
+
+- `OwnerCanManage({ entityType, actions })` — a permit whose resource scope and
+  ownership guard arrive together.
+- `DenyByDefaultSet({ policies, when })` — a guarded `forbid` floor and the
+  permits it governs, returned from one call so the floor cannot be dropped
+  alone. It throws on an empty `when`: an unguarded forbid overrides every
+  permit and authorizes nothing.
+
+## Agent surface
+
+Three skills (`chant-cedar-authoring`, `chant-cedar-avp-embedding`, `chant-cedar-meta-policy`),
+three `chant init` templates (`default`, `avp-embedding`,
+`gateway-policy-set`), and three MCP contributions:
+
+| Contribution | What it answers |
+|---|---|
+| `cedar:diff` | This build's policy set against the previous one |
+| `chant://cedar/resource-catalog` | Every declaration generated from the schema |
+| `cedar:coverage` | Which schema entity types and actions the policy set can apply to, which are reachable only from a `forbid`, and which no policy touches |
+
+`cedar:coverage` resolves each policy through Cedar's own
+`getValidRequestEnvsPolicy` rather than reading the scope literally, so action
+groups, `is`, `in` and `appliesTo` are expanded by Cedar and not by a second,
+worse implementation of it.
+
+## Amazon Verified Permissions
+
+AVP is one evaluator among several, and the aws lexicon keeps the deployment
+vehicle. What this lexicon adds is the typed statement inside it:
+`avpPolicyDefinition(name, props)` returns exactly the `Definition` property
+`AWS::VerifiedPermissions::Policy` takes, rendered by the same renderer that
+writes the `.cedar` file — so the two cannot drift. There is deliberately **no
+dependency on the aws lexicon**; the seam is the data shape. See
+`examples/avp-embedding/`.
+
+Beside the embedding, `describeResources()`, `observeAmbient()` and
+`exportResources()` read a live policy store. `chant lifecycle diff --live`
+reports declared policies that are missing from the store, and
+`observeAmbient()` reports the reverse — policies in the store that no
+declaration accounts for, which for an authorization store is a standing grant
+nobody in the source tree can see.
+
+The store is named by `CEDAR_AVP_POLICY_STORE_ID` (or
+`CEDAR_AVP_POLICY_STORE_ID_<ENV>`), or by a `policyStoreId` prop on a declared
+policy. AVP policy stores are taggable and individual policies are not, so
+chant's per-policy ownership marker rides in the policy description — the
+design record is `src/avp/OWNERSHIP.md`.
+
+## Commands
+
+```bash
+just bundle     # build dist/ (manifest, rules, integrity, OKF)
+just test       # run the lexicon's tests
+just validate   # check generated artifacts
+just generate   # schema-driven codegen from your .cedarschema
+
+npm run docs        # regenerate the docs site's pages + sidebar
+npm run docs:build  # build the Starlight site in docs/
+```
+
+## Project structure
+
+- `src/plugin.ts` — LexiconPlugin with all lifecycle methods
+- `src/serializer.ts` — `.cedar` text and JSON policy-set output
+- `src/avp/` — AVP embedding, the policy-store readers, and the ownership channel
+- `src/import/` — `chant import` parser, generator and round-trip fixtures
+- `src/detect.ts` — which documents belong to this lexicon
+- `src/codegen/` — code generation, docs, and packaging pipelines
+- `src/spec/` — schema resolution, parsing, and the grammar pin
+- `src/lint/rules/` — lint rules
+- `src/lsp/` — LSP completions and hover over the generated registry
+- `src/mcp/` — MCP tools and resources, including policy coverage
+- `src/composites/` — `OwnerCanManage`, `DenyByDefaultSet`
+- `src/skills/` — the three agent skills
+- `src/init-templates.ts` — `chant init --lexicon cedar --template …`
+- `src/generated/` — generated artifacts (do not edit)
+- `docs/` — the standalone Starlight site, generated by `npm run docs`

package/dist/avp/ambient.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Policies that are simply *there* (#1652, chant #1278).
+ *
+ * For most lexicons ambient discovery is housekeeping — an unattached security
+ * group, an orphaned volume. For an authorization store it is a security
+ * finding. A policy in the store that no chant entity declares is a grant
+ * nobody in the source tree can see: it was added in the console, or by a
+ * previous tool, or by a teammate's script, and it is being evaluated on every
+ * request. `describeResources` structurally cannot report it, because it
+ * resolves outward from what was declared and this is precisely what was not.
+ *
+ * The reader reports the policy and its statement. It does not decide that an
+ * ambient `permit` is dangerous — that is a conclusion, and putting conclusions
+ * in observations is the mistake chant #1271 undid. What it does carry is the
+ * `effect`, because "which ambient policies are permits" is the first question
+ * anyone asks and re-parsing the statement to answer it is work every consumer
+ * would repeat.
+ */
+import type { ResourceMetadata } from "@intentius/chant/lexicon";
+import { type AvpClientOptions } from "./client.js";
+/**
+ * The kinds this lexicon can enumerate beyond the declared estate.
+ *
+ * One, and it is the only kind cedar deploys. Declared separately from the
+ * reader so `chant search` can say `--ambient` is relevant to a policy query
+ * without paying for a scan to find out.
+ */
+export declare const AVP_AMBIENT_KINDS: readonly string[];
+export interface ObserveAvpAmbientOptions {
+    environment: string;
+    /** Entity types the project declares — the bound on what to enumerate. */
+    kinds: string[];
+    /** Already-observed managed resources, to exclude. */
+    observed: Record<string, ResourceMetadata>;
+    /** Cedar ids the project declares, so a declared-but-unobserved policy is not called ambient. */
+    declaredPolicyIds?: Iterable<string>;
+    policyStoreId?: string;
+    entities?: Map<string, {
+        entityType: string;
+        props: Record<string, unknown>;
+    }>;
+    client?: AvpClientOptions;
+    env?: Record<string, string | undefined>;
+}
+/**
+ * Policies in the store that nothing declares and nothing already observed.
+ *
+ * Best-effort by contract: ambient discovery is additive, and a failure here
+ * must not sink a managed observation that already succeeded, so the whole scan
+ * degrades to `{}` rather than throwing. The managed answer is complete without
+ * any of this.
+ */
+export declare function observeAvpAmbient(options: ObserveAvpAmbientOptions): Promise<Record<string, ResourceMetadata>>;
+//# sourceMappingURL=ambient.d.ts.map

package/dist/avp/ambient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ambient.d.ts","sourceRoot":"","sources":["../../src/avp/ambient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAEjE,OAAO,EAAwB,KAAK,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAKvE;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,EAAE,SAAS,MAAM,EAAwB,CAAC;AAExE,MAAM,WAAW,wBAAwB;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC3C,iGAAiG;IACjG,iBAAiB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IACrC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;IAC/E,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;CAC1C;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAgE3C"}

package/dist/avp/client.d.ts

@@ -0,0 +1,127 @@
+/**
+ * The AVP read transport (#1652).
+ *
+ * Amazon Verified Permissions speaks AWS JSON 1.0 — a POST of a JSON body with
+ * `x-amz-target: VerifiedPermissions.<Operation>` — so this is the same shape
+ * as `lexicons/aws/src/api/read-client.ts`'s Cloud Control half, pointed at a
+ * different service. That file is the precedent for the decision this module
+ * embodies: **no AWS SDK dependency**. The repo has none anywhere (the aws
+ * lexicon's runtime deps are `fflate` and `js-yaml`), and adding
+ * `@aws-sdk/client-verifiedpermissions` — 30-odd transitive packages — to the
+ * cedar lexicon so that one reader can issue three calls would put an AWS SDK
+ * in the dependency tree of a lexicon whose whole premise is that Cedar is
+ * vendor-neutral.
+ *
+ * ## Signing
+ *
+ * Requests are unsigned, exactly like the aws lexicon's read client. Real AWS
+ * rejects them; an emulator with an endpoint override does not. This is
+ * therefore an emulator-and-test transport today, and the honest consequence is
+ * encoded in {@link credentialsAvailable}: with no credentials and no endpoint
+ * override, the observation reports every entity NOT-OBSERVED with
+ * `no-credentials` rather than issuing a request that will fail. The signed
+ * path lands when SigV4 lands in `lexicons/aws/src/api/read-client.ts`, which
+ * is where it belongs — one implementation, not two.
+ */
+/** Injectable HTTP, mirroring `AwsReadHttp` in the aws lexicon so tests avoid the network. */
+export type AvpHttp = (url: string, init: {
+    headers: Record<string, string>;
+    body: string;
+}, signal?: AbortSignal) => Promise<{
+    status: number;
+    text: string;
+}>;
+/** A failed AVP read, carrying enough to classify it without matching on prose. */
+export declare class AvpReadError extends Error {
+    readonly status: number;
+    /** The service's own error code (`ResourceNotFoundException`, `AccessDeniedException`, …). */
+    readonly code?: string | undefined;
+    constructor(message: string, status: number, 
+    /** The service's own error code (`ResourceNotFoundException`, `AccessDeniedException`, …). */
+    code?: string | undefined);
+}
+export interface AvpClientOptions {
+    /** Endpoint override (an emulator, or a VPC endpoint). Omit for real AWS hosts. */
+    endpoint?: string;
+    /** Region for the real-AWS host and the credential scope. */
+    region?: string;
+    http?: AvpHttp;
+    signal?: AbortSignal;
+    /** Environment to read credentials from. Defaults to `process.env`; injectable for tests. */
+    env?: Record<string, string | undefined>;
+}
+/** Service host for AVP, honouring an endpoint override. */
+export declare function avpUrl(endpoint?: string, region?: string): string;
+/**
+ * Whether this process has anything to authenticate with.
+ *
+ * An endpoint override counts: an emulator is reached without credentials, and
+ * refusing to look at one because `AWS_ACCESS_KEY_ID` is unset would make the
+ * local lanes unobservable. Everything else is the ordinary AWS credential
+ * surface, minus the instance-metadata path this transport cannot use anyway.
+ */
+export declare function credentialsAvailable(env?: Record<string, string | undefined>): boolean;
+/** One AVP call. Throws {@link AvpReadError} carrying the service's `__type`. */
+export declare function avpCall(operation: string, payload: Record<string, unknown>, options?: AvpClientOptions): Promise<Record<string, unknown>>;
+/** One policy, as `ListPolicies` reports it — no statement, only the description. */
+export interface AvpPolicySummary {
+    policyStoreId: string;
+    policyId: string;
+    policyType: string;
+    /** `definition.static.description` — the channel chant's marker rides (see ./ownership.ts). */
+    description?: string;
+    createdDate?: string;
+    lastUpdatedDate?: string;
+}
+/** One policy, as `GetPolicy` reports it — the statement included. */
+export interface AvpPolicyDetail extends AvpPolicySummary {
+    /** The Cedar policy text. */
+    statement: string;
+}
+/** `ListPolicies` for one store, paginated to exhaustion. */
+export declare function listPolicies(policyStoreId: string, options?: AvpClientOptions): Promise<AvpPolicySummary[]>;
+/**
+ * `GetPolicy` — the full record for one policy, statement included.
+ *
+ * A template-linked policy has no `definition.static`, so its statement comes
+ * back empty; callers treat an empty statement as "not a static policy this
+ * lexicon authored" rather than as a parse failure.
+ */
+export declare function getPolicy(policyStoreId: string, policyId: string, options?: AvpClientOptions): Promise<AvpPolicyDetail>;
+/** One policy store, as `GetPolicyStore` reports it. */
+export interface AvpPolicyStore {
+    policyStoreId: string;
+    arn?: string;
+    description?: string;
+    createdDate?: string;
+    lastUpdatedDate?: string;
+}
+/** `GetPolicyStore` — used to resolve the store ARN the tag read needs. */
+export declare function getPolicyStore(policyStoreId: string, options?: AvpClientOptions): Promise<AvpPolicyStore>;
+/** `ListTagsForResource` — the store-level half of the ownership channel. */
+export declare function listStoreTags(resourceArn: string, options?: AvpClientOptions): Promise<Record<string, string>>;
+/** True when the failure means the store itself is not there. */
+export declare function storeDoesNotExist(err: unknown): boolean;
+/**
+ * Map a transport failure onto the closed {@link UnobservedReason} set.
+ *
+ * Anything that is not demonstrably a credential problem is `read-failed`,
+ * because guessing wider would let a throttle or a DNS failure masquerade as a
+ * verdict about the estate.
+ */
+export declare function classifyAvpFailure(err: unknown): {
+    reason: "no-credentials" | "read-failed";
+    detail: string;
+};
+/**
+ * The address a read was issued against, for the observation's `queried` map
+ * (chant #1620).
+ *
+ * An absence is only as trustworthy as the address behind it, and an AVP read
+ * has three ways to be pointed at the wrong place: the region, the store id,
+ * and the `@id` annotation the policy is matched on. All three are in here.
+ */
+export declare function policyAddress(policyStoreId: string, cedarPolicyId: string, region?: string): string;
+/** The address of the store-wide enumeration itself. */
+export declare function storeAddress(policyStoreId: string, region?: string): string;
+//# sourceMappingURL=client.d.ts.map

package/dist/avp/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/avp/client.ts"],"names":[],"mappings":"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"}

package/dist/avp/describe-resources.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `describeResources()` against an AVP policy store (#1652).
+ *
+ * The tri-state matters more here than it does for most substrates. A Cedar
+ * policy that chant declares and the store does not have is a *missing
+ * authorization rule*: reporting it absent proposes a create, which is right.
+ * Reporting it absent because the store id was wrong, or because the read
+ * failed, proposes creating a permit that already exists — duplicating a grant.
+ * So every path that did not actually look says so.
+ *
+ * Built on core's observer harness (`observeEntities`), which owns the shape:
+ * bind-or-not-observe-all with a typed reason, bounded concurrency, a per-entity
+ * throw degrading to `read-failed` rather than a silent absence, and collection
+ * of the `queried` addresses.
+ */
+import type { ObservationResult } from "@intentius/chant/lexicon";
+import { type AvpClientOptions } from "./client.js";
+export interface DescribeAvpOptions {
+    environment: string;
+    entityNames: string[];
+    entities: Map<string, {
+        entityType: string;
+        props: Record<string, unknown>;
+    }>;
+    /** Restrict to policies carrying chant's description marker. */
+    owned?: boolean;
+    /** Explicit store id; otherwise resolved per {@link resolvePolicyStoreId}. */
+    policyStoreId?: string;
+    client?: AvpClientOptions;
+    /** Environment to read the binding and credentials from. Injectable for tests. */
+    env?: Record<string, string | undefined>;
+}
+/**
+ * Observe the declared policy set against a live AVP store.
+ *
+ * Never throws for a transport or binding problem — a throw is the
+ * whole-lexicon failure and core would mark every entity `read-failed`, which
+ * is a worse-shaped version of what this returns directly with the right
+ * reason on it.
+ */
+export declare function describeAvpResources(options: DescribeAvpOptions): Promise<ObservationResult>;
+//# sourceMappingURL=describe-resources.d.ts.map

package/dist/avp/describe-resources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-resources.d.ts","sourceRoot":"","sources":["../../src/avp/describe-resources.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAoB,MAAM,0BAA0B,CAAC;AAWpF,OAAO,EAML,KAAK,gBAAgB,EACtB,MAAM,UAAU,CAAC;AASlB,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;IAC9E,gEAAgE;IAChE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,8EAA8E;IAC9E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,kFAAkF;IAClF,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;CAC1C;AAyCD;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA+GlG"}

package/dist/avp/embed.d.ts

@@ -0,0 +1,120 @@
+/**
+ * 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 { type CedarPolicyProps } from "../serializer.js";
+import { type PolicyJson } from "../spec/wasm.js";
+/** `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;
+}
+/**
+ * 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 declare function avpStatement(name: string, props: CedarPolicyProps | Record<string, unknown>, options?: AvpEmbedOptions): string;
+/**
+ * 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 declare function avpStatementJSON(name: string, props: CedarPolicyProps | Record<string, unknown>, options?: AvpEmbedOptions): PolicyJson;
+/**
+ * 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 declare function avpPolicyDefinition(name: string, props: CedarPolicyProps | Record<string, unknown>, options?: AvpEmbedOptions): AvpPolicyDefinition;
+/**
+ * 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 declare function avpPolicyResource(name: string, props: CedarPolicyProps | Record<string, unknown>, policyStoreId: string, options?: AvpEmbedOptions): AvpPolicyResource;
+/**
+ * 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 declare function avpPolicySet(entities: Map<string, Declarable>, options?: AvpEmbedOptions): Record<string, AvpPolicyDefinition>;
+//# sourceMappingURL=embed.d.ts.map

package/dist/avp/embed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embed.d.ts","sourceRoot":"","sources":["../../src/avp/embed.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,EAIL,KAAK,gBAAgB,EACtB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAG7D,gFAAgF;AAChF,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,uEAAuE;AACvE,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,mBAAmB,CAAC;CAC7B;AAED,4EAA4E;AAC5E,MAAM,WAAW,iBAAiB;IAChC,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,mBAAmB,CAAC;CACjC;AAED,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAMD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjD,OAAO,GAAE,eAAoB,GAC5B,MAAM,CAGR;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjD,OAAO,GAAE,eAAoB,GAC5B,UAAU,CAOZ;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjD,OAAO,GAAE,eAAoB,GAC5B,mBAAmB,CAarB;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjD,aAAa,EAAE,MAAM,EACrB,OAAO,GAAE,eAAoB,GAC5B,iBAAiB,CAEnB;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EACjC,OAAO,GAAE,eAAoB,GAC5B,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAMrC"}

package/dist/avp/live-export.d.ts

@@ -0,0 +1,94 @@
+/**
+ * `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 { type AvpClientOptions } from "./client.js";
+import { type AvpLivePolicy } from "./store.js";
+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 declare function policyToResourceIR(policy: AvpLivePolicy, options?: {
+    verbatim?: boolean;
+}): ResourceIR | undefined;
+/**
+ * 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 declare function exportAvpResources(options: ExportAvpOptions): Promise<ExportedTemplate>;
+//# sourceMappingURL=live-export.d.ts.map

package/dist/avp/live-export.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-export.d.ts","sourceRoot":"","sources":["../../src/avp/live-export.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACnF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AAEjE,OAAO,EAA2C,KAAK,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAE1F,OAAO,EAA0C,KAAK,aAAa,EAAE,MAAM,SAAS,CAAC;AAErF,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,gEAAgE;IAChE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,uEAAuE;IACvE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;IAC/E,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;CAC1C;AAED,iEAAiE;AACjE,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,aAAa,EACrB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAO,GACnC,UAAU,GAAG,SAAS,CAgCxB;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAuD7F"}