@intentius/chant-lexicon-cedar 0.124.30 → 0.124.32

package/dist/avp/live-export.js

@@ -0,0 +1,151 @@
+/**
+ * `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 { CedarTemplateParser } from "../import/adapter.js";
+import { credentialsAvailable, storeDoesNotExist } from "./client.js";
+import { descriptionIsOwned } from "./ownership.js";
+import { loadLivePolicies, resolvePolicyStoreId } from "./store.js";
+/**
+ * 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, options = {}) {
+    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 = { ...resource.properties };
+    if (options.verbatim) {
+        const record = {
+            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) {
+    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;
+    try {
+        policies = await loadLivePolicies({
+            policyStoreId,
+            ...(options.client ? { client: options.client } : {}),
+            withStatements: true,
+        });
+    }
+    catch (err) {
+        if (storeDoesNotExist(err))
+            policies = [];
+        else
+            throw err;
+    }
+    const resources = [];
+    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 },
+    };
+}

package/dist/avp/ownership.js

@@ -0,0 +1,144 @@
+/**
+ * The ownership channel for Amazon Verified Permissions (#1652).
+ *
+ * AVP is the one target in chant where the obvious channel does not exist. A
+ * policy *store* is taggable — `TagResource` takes the same key/value map every
+ * other AWS resource does. An individual policy is not: `CreatePolicy` accepts
+ * a policy store id, a definition, and a client token, and there is no tag
+ * surface on it at all. So the store-level tags can say "this store is chant's"
+ * and nothing native can say "this policy is chant's" — which is the granularity
+ * `delete` needs, because a store holds policies from more than one source the
+ * moment somebody uses the console.
+ *
+ * The one durable, writable, readable per-policy field AVP has is
+ * `Definition.Static.Description`. That is the channel: chant's marker is
+ * encoded into a trailing bracketed segment of the description, ahead of which
+ * the author's own text is preserved. It is read back on `describeResources`
+ * and on `exportResources`, which is exactly what `ownershipChannel.reads`
+ * declares (chant #1348) — no third path claims a verdict it cannot resolve.
+ *
+ * See ./OWNERSHIP.md for the design record, including what this channel costs
+ * and the two alternatives that were rejected.
+ */
+import { classifyOwnership, hasOwnershipMarker, ownershipEntries } from "@intentius/chant/ownership";
+/**
+ * The marker keys, shared by both AVP channels.
+ *
+ * The same three names serve the store's tag map and the per-policy description
+ * marker, because `ownershipChannel` declares one {@link ChannelKeys} and a
+ * lexicon whose two channels disagreed on key names would be two conventions
+ * wearing one declaration. AWS tag keys permit `:`, and the description
+ * encoding below quotes its values, so neither channel constrains the other.
+ */
+export const AVP_OWNERSHIP_KEYS = {
+    managedBy: "chant:managed-by",
+    stack: "chant:stack",
+    env: "chant:env",
+};
+/**
+ * The Cedar policy id this AVP policy carries, recorded beside the marker.
+ *
+ * Deliberately *not* part of {@link AVP_OWNERSHIP_KEYS}: it is not an ownership
+ * claim and `hasOwnershipMarker` must not consult it. It is here because
+ * `ListPolicies` returns descriptions but not statements, so without it every
+ * live policy needs a second `GetPolicy` round trip just to learn which chant
+ * entity it belongs to.
+ */
+export const AVP_POLICY_ID_KEY = "chant:policy-id";
+/**
+ * AVP caps `Definition.Static.Description` at 150 characters.
+ *
+ * The marker is what makes a policy deletable, so when the author's own text
+ * plus the marker exceed the cap, the *text* is truncated and the marker is
+ * kept whole. Silently dropping the marker would turn an owned policy into a
+ * foreign one, and a foreign policy is never deleted — the estate would grow
+ * undeletable policies with no error anywhere.
+ */
+export const AVP_DESCRIPTION_MAX = 150;
+const MARKER_SEGMENT = /\s*\[(chant:[^\]]*)\]\s*$/;
+/**
+ * Encode the marker into a description.
+ *
+ * Values are percent-encoded, so a stack named `my stack` or an id holding a
+ * `]` round-trips instead of corrupting the segment. Reversed by
+ * {@link decodeOwnershipDescription}.
+ */
+export function encodeOwnershipDescription(text, marker, policyId) {
+    const entries = ownershipEntries(AVP_OWNERSHIP_KEYS, marker);
+    if (policyId)
+        entries[AVP_POLICY_ID_KEY] = policyId;
+    const segment = `[${Object.entries(entries)
+        .map(([key, value]) => `${key}=${encodeURIComponent(value)}`)
+        .join(" ")}]`;
+    const authored = (text ?? "").trim();
+    if (authored.length === 0)
+        return segment;
+    // The marker survives; the prose is what gives way (see AVP_DESCRIPTION_MAX).
+    const room = AVP_DESCRIPTION_MAX - segment.length - 1;
+    if (room <= 0)
+        return segment;
+    return `${authored.slice(0, room).trimEnd()} ${segment}`;
+}
+/** Recover the author's text and chant's marker from a live description. */
+export function decodeOwnershipDescription(description) {
+    if (!description)
+        return { text: "", tags: {}, marked: false };
+    const match = MARKER_SEGMENT.exec(description);
+    if (!match)
+        return { text: description.trim(), tags: {}, marked: false };
+    const tags = {};
+    for (const pair of match[1].split(/\s+/)) {
+        if (pair.length === 0)
+            continue;
+        const eq = pair.indexOf("=");
+        if (eq <= 0)
+            continue;
+        try {
+            tags[pair.slice(0, eq)] = decodeURIComponent(pair.slice(eq + 1));
+        }
+        catch {
+            // A malformed escape is a corrupt marker, not a crash. The entry is
+            // dropped, which at worst downgrades the verdict to `foreign` — and a
+            // foreign policy is never deleted, so the failure direction is the safe
+            // one.
+            continue;
+        }
+    }
+    const policyId = tags[AVP_POLICY_ID_KEY];
+    return {
+        text: description.slice(0, match.index).trim(),
+        tags,
+        ...(policyId ? { policyId } : {}),
+        marked: true,
+    };
+}
+/**
+ * The per-policy verdict, read off a live description.
+ *
+ * Two-valued on purpose: this function is only ever called where the
+ * description was actually read, and `unknown` is reserved for the paths that
+ * could not read it at all (the contract in core's `ownership.ts`).
+ */
+export function ownershipFromDescription(description) {
+    return classifyOwnership(decodeOwnershipDescription(description).tags, AVP_OWNERSHIP_KEYS);
+}
+/** True when a live description carries chant's marker. */
+export function descriptionIsOwned(description) {
+    return hasOwnershipMarker(decodeOwnershipDescription(description).tags, AVP_OWNERSHIP_KEYS);
+}
+/**
+ * The store-level verdict, read off a policy store's tag map.
+ *
+ * The coarse channel: it answers "is this store chant's" and says nothing about
+ * any individual policy in it. Kept separate from
+ * {@link ownershipFromDescription} so a caller cannot accidentally treat a
+ * store's tags as a policy's marker — the mistake the whole design exists to
+ * avoid.
+ */
+export function ownershipFromStoreTags(tags) {
+    return classifyOwnership(tags, AVP_OWNERSHIP_KEYS);
+}
+/** The tag entries to stamp onto a policy store. */
+export function storeOwnershipTags(marker) {
+    return ownershipEntries(AVP_OWNERSHIP_KEYS, marker);
+}

package/dist/avp/statement.js

@@ -0,0 +1,45 @@
+/**
+ * The two text-level facts the observation needs from a live Cedar statement
+ * (#1652): which `@id` it carries — the link back to a chant entity — and
+ * whether it permits or forbids.
+ *
+ * Both by regex, with no parser behind them, and that is the point. Reading a
+ * policy *properly* is `src/import/parser.ts`'s job and it goes through
+ * `cedar-wasm`, which is a 12 MB module; the observation path must not load it,
+ * because `plugin.ts` imports `ambientKinds()` eagerly and every `chant`
+ * invocation would pay for it. Live export, which is allowed to be slow and
+ * needs real fidelity, uses the import parser instead of anything here.
+ *
+ * Neither function is a judgement. `observeAmbient` reports the effect and
+ * stops; whether an ambient `permit` is a standing grant worth acting on is the
+ * consumer's call.
+ */
+/** The `@id("…")` a chant-emitted statement always carries, or undefined. */
+export function policyIdFromStatement(statement) {
+    const match = /@id\s*\(\s*"((?:[^"\\]|\\.)*)"\s*\)/.exec(statement);
+    if (!match)
+        return undefined;
+    return unescapeCedarString(match[1]);
+}
+/** `permit` or `forbid`, scanned past any annotations. */
+export function effectFromStatement(statement) {
+    const match = /(?:^|\n)\s*(permit|forbid)\s*\(/.exec(stripAnnotations(statement));
+    return match ? match[1] : undefined;
+}
+function stripAnnotations(statement) {
+    return `\n${statement.replace(/@[A-Za-z_][A-Za-z0-9_]*\s*\(\s*"(?:[^"\\]|\\.)*"\s*\)/g, "\n")}`;
+}
+function unescapeCedarString(value) {
+    return value.replace(/\\(.)/g, (_, ch) => {
+        switch (ch) {
+            case "n":
+                return "\n";
+            case "r":
+                return "\r";
+            case "t":
+                return "\t";
+            default:
+                return ch;
+        }
+    });
+}

package/dist/avp/store.js

@@ -0,0 +1,105 @@
+/**
+ * Binding a chant environment to an AVP policy store, and reading it (#1652).
+ *
+ * Everything that talks to a store needs the same two things first: which store
+ * this environment means, and the store's policies indexed by the Cedar id a
+ * chant entity resolves to. Both live here so `describeResources`,
+ * `observeAmbient` and `exportResources` cannot disagree about either.
+ */
+import { boundedConcurrently } from "@intentius/chant/observation";
+import { getPolicy, listPolicies, } from "./client.js";
+import { decodeOwnershipDescription } from "./ownership.js";
+import { policyIdFromStatement } from "./statement.js";
+/** The env var an environment's policy store is named in when config does not name it. */
+export const AVP_POLICY_STORE_ENV = "CEDAR_AVP_POLICY_STORE_ID";
+/** Per-environment override: `CEDAR_AVP_POLICY_STORE_ID_PROD`. */
+export function policyStoreEnvKey(environment) {
+    return `${AVP_POLICY_STORE_ENV}_${environment.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}`;
+}
+/**
+ * Which policy store this environment means.
+ *
+ * Resolution order, most specific first:
+ *
+ *   1. an explicit `policyStoreId` from the caller;
+ *   2. a `policyStoreId` prop on a declared policy — the entity-prop
+ *      pass-through the observation guide recommends for finding the cloud-side
+ *      identifier, and the form a project uses when it declares the store in the
+ *      same build;
+ *   3. `CEDAR_AVP_POLICY_STORE_ID_<ENV>`, then `CEDAR_AVP_POLICY_STORE_ID`.
+ *
+ * `undefined` means no binding, and every caller turns that into `no-binding`
+ * rather than an empty read. An empty read would say the store holds nothing,
+ * which is a claim about an estate nobody looked at.
+ */
+export function resolvePolicyStoreId(options) {
+    if (options.policyStoreId)
+        return options.policyStoreId;
+    for (const [, entity] of options.entities ?? new Map()) {
+        const declared = entity.props.policyStoreId;
+        if (typeof declared === "string" && declared.length > 0)
+            return declared;
+    }
+    const env = options.env ?? process.env;
+    const scoped = env[policyStoreEnvKey(options.environment)];
+    if (scoped)
+        return scoped;
+    return env[AVP_POLICY_STORE_ENV] || undefined;
+}
+/**
+ * Every policy in the store, each resolved to its Cedar id where possible.
+ *
+ * The marker is the cheap path: `ListPolicies` returns descriptions, so a
+ * chant-stamped policy is identified in the enumeration itself. Anything
+ * unmarked — a console edit, another tool's policy — costs one `GetPolicy` to
+ * read the `@id` out of its statement, run through the shared bounded pool so a
+ * store of two hundred policies is not two hundred serial round trips.
+ *
+ * A per-policy `GetPolicy` failure leaves that policy without a statement and
+ * without a Cedar id rather than sinking the enumeration: the caller then treats
+ * the entity it would have matched as not-observed, which is the honest verdict.
+ */
+export async function loadLivePolicies(options) {
+    const summaries = await listPolicies(options.policyStoreId, options.client);
+    const live = summaries.map((summary) => {
+        const decoded = decodeOwnershipDescription(summary.description);
+        return {
+            ...summary,
+            ...(decoded.policyId ? { cedarPolicyId: decoded.policyId } : {}),
+            authoredDescription: decoded.text,
+            marked: decoded.marked,
+        };
+    });
+    const needsStatement = live.filter((policy) => options.withStatements || policy.cedarPolicyId === undefined);
+    await boundedConcurrently(needsStatement, async (policy) => {
+        try {
+            const detail = await getPolicy(options.policyStoreId, policy.policyId, options.client);
+            policy.statement = detail.statement;
+            if (policy.cedarPolicyId === undefined) {
+                const fromStatement = policyIdFromStatement(detail.statement);
+                if (fromStatement)
+                    policy.cedarPolicyId = fromStatement;
+            }
+        }
+        catch {
+            // One unreadable policy is not a verdict about the store. It stays in the
+            // list without a statement, so anything that depended on reading it
+            // reports a hole instead of an absence.
+        }
+    });
+    return live;
+}
+/** Index live policies by the Cedar id a chant entity resolves to. */
+export function indexByCedarId(policies) {
+    const index = new Map();
+    for (const policy of policies) {
+        if (policy.cedarPolicyId === undefined)
+            continue;
+        // First wins: two policies claiming one id is a live-side collision, and
+        // silently preferring the later one would make the observation depend on
+        // enumeration order.
+        if (!index.has(policy.cedarPolicyId))
+            index.set(policy.cedarPolicyId, policy);
+    }
+    return index;
+}

package/dist/avp/testdata/mock-transport.js

@@ -0,0 +1,100 @@
+/**
+ * A fake AVP wire, for the tests of every reader in ../ .
+ *
+ * Mocks the *client layer*, never the network: it implements {@link AvpHttp},
+ * the same injection point `lexicons/aws/src/api/read-client.ts` exposes, so a
+ * test drives real `avpCall` / `listPolicies` / `getPolicy` code — the
+ * pagination loop, the `__type` error mapping, the description decoding — with
+ * only the socket replaced.
+ */
+import { encodeOwnershipDescription } from "../ownership.js";
+/** A chant-stamped description for a policy the fake store should read as owned. */
+export function markedDescription(policyId, text = "", marker = { stack: "authz", env: "prod" }) {
+    return encodeOwnershipDescription(text, marker, policyId);
+}
+/** A statement carrying the `@id` a chant entity resolves to. */
+export function statementFor(policyId, body = "permit (\n  principal,\n  action,\n  resource\n)") {
+    return `@id("${policyId}")\n${body};`;
+}
+/** Build an {@link AvpHttp} over one fake store. */
+export function mockAvpTransport(store) {
+    const calls = [];
+    const pageSize = store.pageSize ?? 50;
+    const error = (type, message, status = 400) => ({
+        status,
+        text: JSON.stringify({ __type: `com.amazonaws.verifiedpermissions#${type}`, message }),
+    });
+    const definitionOf = (policy, withStatement) => ({
+        static: {
+            ...(policy.description !== undefined ? { description: policy.description } : {}),
+            ...(withStatement ? { statement: policy.statement } : {}),
+        },
+    });
+    const http = async (_url, init) => {
+        const operation = (init.headers["x-amz-target"] ?? "").split(".").pop() ?? "";
+        const payload = JSON.parse(init.body);
+        calls.push({ operation, payload });
+        if (payload.policyStoreId !== undefined && payload.policyStoreId !== store.policyStoreId) {
+            return error("ResourceNotFoundException", `No policy store: ${String(payload.policyStoreId)}`, 404);
+        }
+        switch (operation) {
+            case "ListPolicies": {
+                if (store.listFails) {
+                    return error(store.listFails.code, store.listFails.message, store.listFails.status ?? 400);
+                }
+                const from = typeof payload.nextToken === "string" ? Number(payload.nextToken) : 0;
+                const page = store.policies.slice(from, from + pageSize);
+                const next = from + pageSize < store.policies.length ? String(from + pageSize) : undefined;
+                return {
+                    status: 200,
+                    text: JSON.stringify({
+                        policies: page.map((policy) => ({
+                            policyStoreId: store.policyStoreId,
+                            policyId: policy.policyId,
+                            policyType: policy.policyType ?? "STATIC",
+                            definition: definitionOf(policy, false),
+                            ...(policy.createdDate ? { createdDate: policy.createdDate } : {}),
+                            ...(policy.lastUpdatedDate ? { lastUpdatedDate: policy.lastUpdatedDate } : {}),
+                        })),
+                        ...(next ? { nextToken: next } : {}),
+                    }),
+                };
+            }
+            case "GetPolicy": {
+                const policy = store.policies.find((p) => p.policyId === payload.policyId);
+                if (!policy)
+                    return error("ResourceNotFoundException", "No such policy", 404);
+                if (policy.getFails)
+                    return error("ThrottlingException", "Rate exceeded", 429);
+                return {
+                    status: 200,
+                    text: JSON.stringify({
+                        policyStoreId: store.policyStoreId,
+                        policyId: policy.policyId,
+                        policyType: policy.policyType ?? "STATIC",
+                        definition: definitionOf(policy, true),
+                        ...(policy.createdDate ? { createdDate: policy.createdDate } : {}),
+                        ...(policy.lastUpdatedDate ? { lastUpdatedDate: policy.lastUpdatedDate } : {}),
+                    }),
+                };
+            }
+            case "GetPolicyStore":
+                return {
+                    status: 200,
+                    text: JSON.stringify({
+                        policyStoreId: store.policyStoreId,
+                        arn: store.arn ?? `arn:aws:verifiedpermissions::111122223333:policy-store/${store.policyStoreId}`,
+                    }),
+                };
+            case "ListTagsForResource":
+                return { status: 200, text: JSON.stringify({ tags: store.tags ?? {} }) };
+            default:
+                return error("UnknownOperationException", `no mock for ${operation}`, 400);
+        }
+    };
+    return { http, calls };
+}
+/** The env a reader needs to consider itself credentialed against a fake endpoint. */
+export const MOCK_ENV = {
+    AWS_ENDPOINT_URL: "http://localhost:4566",
+};

package/dist/codegen/docs-cli.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env tsx
+/**
+ * Thin entry point for `npm run docs` in lexicon-cedar.
+ */
+import { generateDocs } from "./docs.js";
+await generateDocs({ verbose: true });