@intentius/chant-lexicon-cedar 0.124.31 → 0.124.32

package/dist/avp/client.js

@@ -0,0 +1,318 @@
+/**
+ * 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
+ *
+ * SigV4 lives once, in `lexicons/aws/src/api/sigv4.ts` (#1686). This module
+ * does not import it. A cedar → aws dependency edge would make the vendor-
+ * neutral lexicon unbuildable without the AWS one, which is the same rule that
+ * kept `src/avp/embed.ts` free of the aws lexicon: the seam is the data shape.
+ * So the signer arrives as a function on {@link AvpClientOptions}, typed here
+ * structurally against what the aws lexicon exports, and a project holding both
+ * lexicons wires them in one line:
+ *
+ * ```ts
+ * import { signRequest } from "@intentius/chant-lexicon-aws";
+ * import { describeAvpResources } from "@intentius/chant-lexicon-cedar";
+ *
+ * await describeAvpResources({
+ *   environment,
+ *   entityNames,
+ *   entities,
+ *   client: { region: "us-west-2", signer: signRequest },
+ * });
+ * ```
+ *
+ * Three cases go out unsigned, byte for byte as they did before signing
+ * existed — the credential scope of {@link regionScope} and nothing more:
+ *
+ *   - **No signer.** The default, and the reason `credentialsAvailable` still
+ *     gates the readers: a caller that wires nothing in is still an
+ *     emulator-and-test transport, and real AWS still rejects it.
+ *   - **No credentials.** A signer with nothing to sign with does not run.
+ *   - **An endpoint override.** An emulator does not verify signatures, and
+ *     signing against one would make every local lane need credentials to read
+ *     what it just deployed. `signEndpointOverride` opts back in for an
+ *     override that *is* real AWS — a VPC endpoint, a signing proxy.
+ *
+ * What counts as an override is {@link resolveEndpointOverride}: the
+ * `endpoint` option, else `AWS_ENDPOINT_URL_VERIFIEDPERMISSIONS`, else
+ * `AWS_ENDPOINT_URL` — the AWS SDK's own precedence, and the same rule the aws
+ * lexicon's `api/read-client.ts` applies to every transport it owns (#1694).
+ * It is restated here rather than imported for the reason above: cedar does
+ * not depend on the aws lexicon, and a lexicon build compiles against the
+ * published core, so a helper hoisted into core would reach neither lexicon
+ * until the next core release.
+ */
+const DEFAULT_REGION = "us-east-1";
+const TARGET_PREFIX = "VerifiedPermissions";
+const SERVICE = "verifiedpermissions";
+const defaultHttp = async (url, init, signal) => {
+    const res = await fetch(url, { method: "POST", headers: init.headers, body: init.body, signal });
+    return { status: res.status, text: await res.text() };
+};
+/** A failed AVP read, carrying enough to classify it without matching on prose. */
+export class AvpReadError extends Error {
+    constructor(message, status, 
+    /** The service's own error code (`ResourceNotFoundException`, `AccessDeniedException`, …). */
+    code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "AvpReadError";
+    }
+}
+/**
+ * Credentials for a request: explicit → environment → absent.
+ *
+ * The same rule the aws lexicon's `resolveCredentials` applies, and for the same
+ * reasons: an injected resolver is authoritative and its refusal is not
+ * second-guessed against the environment, and a half-set environment is absent
+ * rather than a signature that cannot verify. A caller with a profile file, IMDS
+ * or a container credential endpoint resolves those itself and passes the result
+ * in — that is what the resolver form is for.
+ */
+export function resolveAvpCredentials(source, env = process.env) {
+    if (typeof source === "function")
+        return source();
+    if (source)
+        return source;
+    const accessKeyId = env.AWS_ACCESS_KEY_ID;
+    const secretAccessKey = env.AWS_SECRET_ACCESS_KEY;
+    if (!accessKeyId || !secretAccessKey)
+        return undefined;
+    return {
+        accessKeyId,
+        secretAccessKey,
+        ...(env.AWS_SESSION_TOKEN ? { sessionToken: env.AWS_SESSION_TOKEN } : {}),
+    };
+}
+/** Service host for AVP, honouring an endpoint override. */
+export function avpUrl(endpoint, region = DEFAULT_REGION) {
+    return `${(endpoint ?? `https://${SERVICE}.${region}.amazonaws.com`).replace(/\/$/, "")}/`;
+}
+/** The service-specific endpoint variable the AWS SDK reads for Verified Permissions. */
+const SERVICE_ENDPOINT_ENV_VAR = "AWS_ENDPOINT_URL_VERIFIEDPERMISSIONS";
+/**
+ * The one rule for what an endpoint override is (#1694): the `endpoint`
+ * option when given, else `AWS_ENDPOINT_URL_VERIFIEDPERMISSIONS`, else the
+ * ambient `AWS_ENDPOINT_URL`. The result is both the target and, through
+ * {@link requestHeaders}, the fact that decides whether the request is signed.
+ * Returns `undefined` for real AWS. Mirrors the aws lexicon's
+ * `resolveEndpointOverride` for this one service.
+ */
+export function resolveEndpointOverride(endpoint, env = process.env) {
+    return endpoint || env[SERVICE_ENDPOINT_ENV_VAR] || env.AWS_ENDPOINT_URL || undefined;
+}
+/**
+ * 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 function credentialsAvailable(env = process.env) {
+    return Boolean(resolveEndpointOverride(undefined, env) ||
+        env.AWS_ACCESS_KEY_ID ||
+        env.AWS_PROFILE ||
+        env.AWS_SESSION_TOKEN ||
+        env.AWS_ROLE_ARN ||
+        env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI ||
+        env.AWS_WEB_IDENTITY_TOKEN_FILE);
+}
+/**
+ * The credential scope header.
+ *
+ * This is NOT SigV4 — the signature is a placeholder, exactly as in the aws
+ * lexicon's read client, and it must not be mistaken for a signed read path. It
+ * carries the region so that an endpoint override (one host for every region)
+ * still reaches the right one, and it is only ever sent when no signature was
+ * produced; the moment one is, {@link requestHeaders} sends that instead.
+ */
+function regionScope(region, env) {
+    if (!region)
+        return {};
+    const day = new Date().toISOString().slice(0, 10).replace(/-/g, "");
+    const key = env.AWS_ACCESS_KEY_ID || "chant";
+    return {
+        authorization: `AWS4-HMAC-SHA256 Credential=${key}/${day}/${region}/${SERVICE}/aws4_request, ` +
+            "SignedHeaders=host, Signature=unsigned",
+    };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * The headers one request goes out with — signed when a signer was injected,
+ * something resolved to sign with, and the target is real AWS; scope-only in
+ * every other case, which is the path this transport had before signing.
+ *
+ * Signing needs a region even when the caller named none, because the scope
+ * string has a slot for one; it borrows the same default {@link avpUrl} used to
+ * build the host, so the signature agrees with the endpoint it is sent to.
+ */
+function requestHeaders(operation, url, body, endpoint, options, env) {
+    const base = {
+        "content-type": "application/x-amz-json-1.0",
+        "x-amz-target": `${TARGET_PREFIX}.${operation}`,
+    };
+    const signer = options.signer;
+    const credentials = signer ? resolveAvpCredentials(options.credentials, env) : undefined;
+    if (!signer || !credentials || (endpoint && options.signEndpointOverride !== true)) {
+        return { ...base, ...regionScope(options.region, env) };
+    }
+    return signer({
+        method: "POST",
+        url,
+        headers: base,
+        body,
+        service: SERVICE,
+        region: options.region ?? DEFAULT_REGION,
+        credentials,
+        ...(options.now ? { now: options.now } : {}),
+    });
+}
+/** One AVP call. Throws {@link AvpReadError} carrying the service's `__type`. */
+export async function avpCall(operation, payload, options = {}) {
+    const env = options.env ?? process.env;
+    const http = options.http ?? defaultHttp;
+    const endpoint = resolveEndpointOverride(options.endpoint, env);
+    const url = avpUrl(endpoint, options.region);
+    const payloadJson = JSON.stringify(payload);
+    const res = await http(url, {
+        headers: requestHeaders(operation, url, payloadJson, endpoint, options, env),
+        body: payloadJson,
+    }, options.signal);
+    let parsed;
+    try {
+        parsed = JSON.parse(res.text);
+    }
+    catch {
+        throw new AvpReadError(`unparseable ${operation} response`, res.status);
+    }
+    const body = isRecord(parsed) ? parsed : {};
+    const type = typeof body.__type === "string" ? body.__type.split("#").pop() : undefined;
+    if (type || res.status >= 400) {
+        const message = typeof body.message === "string" ? body.message : `${operation} failed with HTTP ${res.status}`;
+        throw new AvpReadError(message, res.status, type);
+    }
+    return body;
+}
+function summaryOf(raw, fallbackStore) {
+    const definition = isRecord(raw.definition) ? raw.definition : {};
+    const staticDef = isRecord(definition.static) ? definition.static : {};
+    const description = typeof staticDef.description === "string" ? staticDef.description : undefined;
+    return {
+        policyStoreId: typeof raw.policyStoreId === "string" ? raw.policyStoreId : fallbackStore,
+        policyId: typeof raw.policyId === "string" ? raw.policyId : "",
+        policyType: typeof raw.policyType === "string" ? raw.policyType : "STATIC",
+        ...(description !== undefined ? { description } : {}),
+        ...(typeof raw.createdDate === "string" ? { createdDate: raw.createdDate } : {}),
+        ...(typeof raw.lastUpdatedDate === "string" ? { lastUpdatedDate: raw.lastUpdatedDate } : {}),
+    };
+}
+/** `ListPolicies` for one store, paginated to exhaustion. */
+export async function listPolicies(policyStoreId, options = {}) {
+    const out = [];
+    let nextToken;
+    do {
+        const body = await avpCall("ListPolicies", { policyStoreId, ...(nextToken ? { nextToken } : {}) }, options);
+        const rows = Array.isArray(body.policies) ? body.policies : [];
+        for (const row of rows) {
+            if (isRecord(row))
+                out.push(summaryOf(row, policyStoreId));
+        }
+        nextToken = typeof body.nextToken === "string" && body.nextToken.length > 0 ? body.nextToken : undefined;
+    } while (nextToken);
+    return out;
+}
+/**
+ * `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 async function getPolicy(policyStoreId, policyId, options = {}) {
+    const body = await avpCall("GetPolicy", { policyStoreId, policyId }, options);
+    const definition = isRecord(body.definition) ? body.definition : {};
+    const staticDef = isRecord(definition.static) ? definition.static : {};
+    return {
+        ...summaryOf(body, policyStoreId),
+        policyId: typeof body.policyId === "string" ? body.policyId : policyId,
+        statement: typeof staticDef.statement === "string" ? staticDef.statement : "",
+    };
+}
+/** `GetPolicyStore` — used to resolve the store ARN the tag read needs. */
+export async function getPolicyStore(policyStoreId, options = {}) {
+    const body = await avpCall("GetPolicyStore", { policyStoreId }, options);
+    return {
+        policyStoreId: typeof body.policyStoreId === "string" ? body.policyStoreId : policyStoreId,
+        ...(typeof body.arn === "string" ? { arn: body.arn } : {}),
+        ...(typeof body.description === "string" ? { description: body.description } : {}),
+        ...(typeof body.createdDate === "string" ? { createdDate: body.createdDate } : {}),
+        ...(typeof body.lastUpdatedDate === "string" ? { lastUpdatedDate: body.lastUpdatedDate } : {}),
+    };
+}
+/** `ListTagsForResource` — the store-level half of the ownership channel. */
+export async function listStoreTags(resourceArn, options = {}) {
+    const body = await avpCall("ListTagsForResource", { resourceArn }, options);
+    const tags = isRecord(body.tags) ? body.tags : {};
+    const out = {};
+    for (const [key, value] of Object.entries(tags)) {
+        if (typeof value === "string")
+            out[key] = value;
+    }
+    return out;
+}
+/* ── Classification ───────────────────────────────────────────────────────── */
+/** True when the failure means the store itself is not there. */
+export function storeDoesNotExist(err) {
+    if (!(err instanceof AvpReadError))
+        return false;
+    return err.code === "ResourceNotFoundException" || /not\s*found|does not exist/i.test(err.message);
+}
+const CREDENTIAL_PATTERN = /credential|token|expired|AccessDenied|not authorized|Unauthorized|UnrecognizedClient|InvalidSignature/i;
+/**
+ * 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 function classifyAvpFailure(err) {
+    const code = err instanceof AvpReadError && err.code ? `${err.code}: ` : "";
+    const message = err instanceof Error ? err.message : String(err);
+    const detail = `${code}${message}`;
+    return {
+        reason: CREDENTIAL_PATTERN.test(detail) ? "no-credentials" : "read-failed",
+        detail,
+    };
+}
+/**
+ * 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 function policyAddress(policyStoreId, cedarPolicyId, region) {
+    return `avp://${region ?? DEFAULT_REGION}/policy-store/${policyStoreId}/policy?@id=${encodeURIComponent(cedarPolicyId)}`;
+}
+/** The address of the store-wide enumeration itself. */
+export function storeAddress(policyStoreId, region) {
+    return `avp://${region ?? DEFAULT_REGION}/policy-store/${policyStoreId}/policies`;
+}

package/dist/avp/describe-resources.js

@@ -0,0 +1,144 @@
+/**
+ * `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 { observation, observeEntities, unobservedAll, } from "@intentius/chant/observation";
+import { CEDAR_POLICY_TYPE, resolvePolicyId } from "../serializer.js";
+import { classifyAvpFailure, credentialsAvailable, policyAddress, storeAddress, storeDoesNotExist, } from "./client.js";
+import { ownershipFromDescription } from "./ownership.js";
+import { indexByCedarId, loadLivePolicies, resolvePolicyStoreId, } from "./store.js";
+/** A bind failure that already knows its verdict. */
+class AvpBindFailure extends Error {
+    constructor(reason, detail) {
+        super(detail);
+        this.reason = reason;
+        this.detail = detail;
+        this.name = "AvpBindFailure";
+    }
+}
+function metadataFor(policy, ownership) {
+    return {
+        type: CEDAR_POLICY_TYPE,
+        physicalId: policy.policyId,
+        // AVP has no lifecycle state on a policy: it exists or it does not. The
+        // policy type is the most useful thing to show, and a template-linked
+        // policy differing from a static one IS drift worth seeing.
+        status: policy.policyType || "STATIC",
+        ...(policy.lastUpdatedDate ? { lastUpdated: policy.lastUpdatedDate } : {}),
+        ownership,
+        attributes: {
+            policyStoreId: policy.policyStoreId,
+            policyId: policy.policyId,
+            policyType: policy.policyType,
+            ...(policy.cedarPolicyId ? { cedarPolicyId: policy.cedarPolicyId } : {}),
+            ...(policy.authoredDescription ? { description: policy.authoredDescription } : {}),
+            ...(policy.createdDate ? { createdDate: policy.createdDate } : {}),
+        },
+    };
+}
+/**
+ * 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 async function describeAvpResources(options) {
+    const env = options.env ?? process.env;
+    const typesByName = {};
+    for (const name of options.entityNames) {
+        typesByName[name] = options.entities.get(name)?.entityType ?? CEDAR_POLICY_TYPE;
+    }
+    const policyStoreId = resolvePolicyStoreId({
+        environment: options.environment,
+        ...(options.policyStoreId ? { policyStoreId: options.policyStoreId } : {}),
+        entities: options.entities,
+        env,
+    });
+    if (!policyStoreId) {
+        return observation({}, unobservedAll(options.entityNames, "no-binding", `no AVP policy store for environment "${options.environment}" — set ${"CEDAR_AVP_POLICY_STORE_ID"} or declare policyStoreId on a policy`, typesByName));
+    }
+    if (!credentialsAvailable(env)) {
+        return observation({}, unobservedAll(options.entityNames, "no-credentials", "no AWS credentials and no endpoint override — the AVP store was not queried", typesByName));
+    }
+    const region = options.client?.region;
+    const declared = options.entityNames.map((name) => {
+        const entity = options.entities.get(name);
+        return {
+            name,
+            type: entity?.entityType ?? CEDAR_POLICY_TYPE,
+            props: entity?.props ?? {},
+        };
+    });
+    const adapter = {
+        async bind() {
+            try {
+                const policies = await loadLivePolicies({
+                    policyStoreId,
+                    ...(options.client ? { client: options.client } : {}),
+                });
+                return { policyStoreId, byCedarId: indexByCedarId(policies), ...(region ? { region } : {}) };
+            }
+            catch (err) {
+                // A store that is not there yet is the pre-first-apply state: nothing
+                // is deployed, so every declared policy is genuinely absent and
+                // `create` is the right proposal.
+                if (storeDoesNotExist(err)) {
+                    return { policyStoreId, byCedarId: new Map(), ...(region ? { region } : {}) };
+                }
+                const { reason, detail } = classifyAvpFailure(err);
+                throw new AvpBindFailure(reason, `ListPolicies failed for store ${policyStoreId}: ${detail}`);
+            }
+        },
+        classifyBindFailure(err) {
+            if (err instanceof AvpBindFailure)
+                return { reason: err.reason, detail: err.detail };
+            const { reason, detail } = classifyAvpFailure(err);
+            return { reason, detail: `${storeAddress(policyStoreId, region)}: ${detail}` };
+        },
+        async read(binding, entity) {
+            if (entity.type !== CEDAR_POLICY_TYPE) {
+                // Cedar declares one deployable kind. Anything else is a schema entity
+                // or action constant, which has no AVP counterpart at all — saying so
+                // per entity keeps it out of `lifecycle plan` as a create.
+                return {
+                    unobserved: {
+                        reason: "unsupported-kind",
+                        detail: `no AVP reader for ${entity.type} — only ${CEDAR_POLICY_TYPE} is deployed to a policy store`,
+                    },
+                };
+            }
+            const cedarPolicyId = resolvePolicyId(entity.name, entity.props);
+            const queried = policyAddress(binding.policyStoreId, cedarPolicyId, binding.region);
+            const policy = binding.byCedarId.get(cedarPolicyId);
+            // The store was enumerated and this `@id` is not in it. That is an
+            // absence, and the only shape allowed to become a create.
+            if (!policy)
+                return { absent: true, queried };
+            const ownership = ownershipFromDescription(policy.description);
+            if (options.owned && ownership !== "owned") {
+                return {
+                    unobserved: {
+                        reason: "filtered",
+                        detail: "live policy carries no chant description marker",
+                    },
+                    queried,
+                };
+            }
+            return { present: metadataFor(policy, ownership), queried };
+        },
+    };
+    return observeEntities(declared, adapter);
+}

package/dist/avp/embed.js

@@ -0,0 +1,125 @@
+/**
+ * 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 { cedarPolicyRecords, renderPolicyText, resolvePolicyId, } from "../serializer.js";
+import { policyToJson } from "../spec/wasm.js";
+import { encodeOwnershipDescription } from "./ownership.js";
+function propsRecord(props) {
+    return props;
+}
+/**
+ * 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, props, options = {}) {
+    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, props, options = {}) {
+    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, props, options = {}) {
+    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, props, policyStoreId, options = {}) {
+    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, options = {}) {
+    const out = {};
+    for (const { name, id, props } of cedarPolicyRecords(entities)) {
+        out[name] = avpPolicyDefinition(name, props, { ...options, policyId: id });
+    }
+    return out;
+}