@intentius/chant-lexicon-cedar 0.44.8

package/src/avp/ownership.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, it } from "vitest";
+import { hasOwnershipMarker, readOwnership } from "@intentius/chant/ownership";
+import {
+  AVP_DESCRIPTION_MAX,
+  AVP_OWNERSHIP_KEYS,
+  AVP_POLICY_ID_KEY,
+  decodeOwnershipDescription,
+  descriptionIsOwned,
+  encodeOwnershipDescription,
+  ownershipFromDescription,
+  ownershipFromStoreTags,
+  storeOwnershipTags,
+} from "./ownership";
+
+describe("the AVP description marker", () => {
+  it("keeps the author's text ahead of the marker", () => {
+    const encoded = encodeOwnershipDescription("Owners read their own documents.", {
+      stack: "authz",
+      env: "prod",
+    });
+    expect(encoded.startsWith("Owners read their own documents. [chant:")).toBe(true);
+
+    const decoded = decodeOwnershipDescription(encoded);
+    expect(decoded.text).toBe("Owners read their own documents.");
+    expect(decoded.marked).toBe(true);
+  });
+
+  it("round-trips the stack and env through core's own ownership helpers", () => {
+    const encoded = encodeOwnershipDescription(undefined, { stack: "authz", env: "prod" });
+    const { tags } = decodeOwnershipDescription(encoded);
+
+    expect(hasOwnershipMarker(tags, AVP_OWNERSHIP_KEYS)).toBe(true);
+    expect(readOwnership(tags, AVP_OWNERSHIP_KEYS)).toEqual({ stack: "authz", env: "prod" });
+  });
+
+  it("carries the cedar policy id, and does not let it count as an ownership claim", () => {
+    const encoded = encodeOwnershipDescription("", { stack: "authz" }, "owner-read");
+    expect(decodeOwnershipDescription(encoded).policyId).toBe("owner-read");
+
+    // A marker segment carrying only the id is not ownership.
+    const idOnly = decodeOwnershipDescription(`[${AVP_POLICY_ID_KEY}=owner-read]`);
+    expect(hasOwnershipMarker(idOnly.tags, AVP_OWNERSHIP_KEYS)).toBe(false);
+    expect(idOnly.policyId).toBe("owner-read");
+  });
+
+  it("survives values holding spaces and brackets", () => {
+    const encoded = encodeOwnershipDescription("desc", { stack: "my stack", env: "pr[7]" }, "a b");
+    const decoded = decodeOwnershipDescription(encoded);
+
+    expect(decoded.text).toBe("desc");
+    expect(readOwnership(decoded.tags, AVP_OWNERSHIP_KEYS)).toEqual({
+      stack: "my stack",
+      env: "pr[7]",
+    });
+    expect(decoded.policyId).toBe("a b");
+  });
+
+  it("truncates the prose rather than the marker at AVP's 150-character cap", () => {
+    const encoded = encodeOwnershipDescription("x".repeat(400), { stack: "authz", env: "prod" }, "p");
+
+    expect(encoded.length).toBeLessThanOrEqual(AVP_DESCRIPTION_MAX);
+    expect(descriptionIsOwned(encoded)).toBe(true);
+    expect(decodeOwnershipDescription(encoded).policyId).toBe("p");
+  });
+
+  it("keeps the marker whole when there is no room for prose at all", () => {
+    const encoded = encodeOwnershipDescription("x".repeat(400), {
+      stack: "s".repeat(60),
+      env: "e".repeat(60),
+    });
+    expect(descriptionIsOwned(encoded)).toBe(true);
+  });
+
+  it("reads an unmarked description as foreign, not as an error", () => {
+    expect(ownershipFromDescription("added by hand in the console")).toBe("foreign");
+    expect(ownershipFromDescription(undefined)).toBe("foreign");
+    expect(decodeOwnershipDescription("added by hand").text).toBe("added by hand");
+  });
+
+  it("degrades a corrupt marker entry to foreign rather than throwing", () => {
+    // A truncated percent-escape: the entry is dropped, and a foreign policy is
+    // never deleted, so the failure lands on the safe side.
+    const decoded = decodeOwnershipDescription("[chant:managed-by=%E0%A4 chant:stack=authz]");
+    expect(decoded.marked).toBe(true);
+    expect(hasOwnershipMarker(decoded.tags, AVP_OWNERSHIP_KEYS)).toBe(false);
+  });
+
+  it("classifies a marked description as owned", () => {
+    const encoded = encodeOwnershipDescription("d", { stack: "authz", env: "prod" }, "id");
+    expect(ownershipFromDescription(encoded)).toBe("owned");
+  });
+});
+
+describe("the store-level channel", () => {
+  it("stamps and reads the same keys as the per-policy channel", () => {
+    const tags = storeOwnershipTags({ stack: "authz", env: "prod" });
+    expect(tags[AVP_OWNERSHIP_KEYS.managedBy]).toBe("chant");
+    expect(ownershipFromStoreTags(tags)).toBe("owned");
+    expect(ownershipFromStoreTags({ Team: "platform" })).toBe("foreign");
+  });
+});

package/src/avp/ownership.ts

@@ -0,0 +1,170 @@
+/**
+ * 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 type { ChannelKeys, OwnershipMarker } from "@intentius/chant/ownership";
+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: ChannelKeys = {
+  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;
+
+/** What {@link decodeOwnershipDescription} recovers from a live description. */
+export interface DecodedDescription {
+  /** The author's own description, marker segment removed. */
+  text: string;
+  /** Marker entries, keyed by {@link AVP_OWNERSHIP_KEYS} names, for the core ownership helpers. */
+  tags: Record<string, string>;
+  /** The Cedar policy id the marker recorded, when it carried one. */
+  policyId?: string;
+  /** Whether a marker segment was present at all. */
+  marked: boolean;
+}
+
+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: string | undefined,
+  marker: OwnershipMarker,
+  policyId?: string,
+): string {
+  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: string | undefined): DecodedDescription {
+  if (!description) return { text: "", tags: {}, marked: false };
+
+  const match = MARKER_SEGMENT.exec(description);
+  if (!match) return { text: description.trim(), tags: {}, marked: false };
+
+  const tags: Record<string, string> = {};
+  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: string | undefined): "owned" | "foreign" {
+  return classifyOwnership(decodeOwnershipDescription(description).tags, AVP_OWNERSHIP_KEYS);
+}
+
+/** True when a live description carries chant's marker. */
+export function descriptionIsOwned(description: string | undefined): boolean {
+  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: Record<string, unknown> | undefined): "owned" | "foreign" {
+  return classifyOwnership(tags, AVP_OWNERSHIP_KEYS);
+}
+
+/** The tag entries to stamp onto a policy store. */
+export function storeOwnershipTags(marker: OwnershipMarker): Record<string, string> {
+  return ownershipEntries(AVP_OWNERSHIP_KEYS, marker);
+}

package/src/avp/statement.ts

@@ -0,0 +1,50 @@
+/**
+ * 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.
+ */
+
+import type { CedarEffect } from "../serializer";
+
+/** The `@id("…")` a chant-emitted statement always carries, or undefined. */
+export function policyIdFromStatement(statement: string): string | undefined {
+  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: string): CedarEffect | undefined {
+  const match = /(?:^|\n)\s*(permit|forbid)\s*\(/.exec(stripAnnotations(statement));
+  return match ? (match[1] as CedarEffect) : undefined;
+}
+
+function stripAnnotations(statement: string): string {
+  return `\n${statement.replace(/@[A-Za-z_][A-Za-z0-9_]*\s*\(\s*"(?:[^"\\]|\\.)*"\s*\)/g, "\n")}`;
+}
+
+function unescapeCedarString(value: string): string {
+  return value.replace(/\\(.)/g, (_, ch: string) => {
+    switch (ch) {
+      case "n":
+        return "\n";
+      case "r":
+        return "\r";
+      case "t":
+        return "\t";
+      default:
+        return ch;
+    }
+  });
+}

package/src/avp/store.ts

@@ -0,0 +1,152 @@
+/**
+ * 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,
+  type AvpClientOptions,
+  type AvpPolicySummary,
+} from "./client";
+import { decodeOwnershipDescription } from "./ownership";
+import { policyIdFromStatement } from "./statement";
+
+/** 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: string): string {
+  return `${AVP_POLICY_STORE_ENV}_${environment.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}`;
+}
+
+export interface StoreBindingOptions {
+  environment: string;
+  /** Explicit store id from the caller — wins over everything. */
+  policyStoreId?: string;
+  /** Declared entities, read for a `policyStoreId` prop (the entity-prop pass-through). */
+  entities?: Map<string, { entityType: string; props: Record<string, unknown> }>;
+  env?: Record<string, string | undefined>;
+}
+
+/**
+ * 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: StoreBindingOptions): string | undefined {
+  if (options.policyStoreId) return options.policyStoreId;
+
+  for (const [, entity] of options.entities ?? new Map()) {
+    const declared = (entity.props as { policyStoreId?: unknown }).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;
+}
+
+/** One live policy, with whatever chant could learn about which entity it belongs to. */
+export interface AvpLivePolicy extends AvpPolicySummary {
+  /** The Cedar `@id` — the link back to a chant entity. Undefined when unrecoverable. */
+  cedarPolicyId?: string;
+  /** The policy text, when it was fetched (see `withStatements`). */
+  statement?: string;
+  /** The author's description, marker segment removed. */
+  authoredDescription: string;
+  /** Whether the description carried chant's ownership marker. */
+  marked: boolean;
+}
+
+export interface LoadPoliciesOptions {
+  policyStoreId: string;
+  client?: AvpClientOptions;
+  /**
+   * Fetch each policy's statement.
+   *
+   * The thin observation does not need one: a marked policy's description
+   * already names its Cedar id, and `describeResources` returns scrubbed
+   * metadata rather than config. Ambient discovery and live export both do, so
+   * they ask for them.
+   */
+  withStatements?: boolean;
+}
+
+/**
+ * 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: LoadPoliciesOptions): Promise<AvpLivePolicy[]> {
+  const summaries = await listPolicies(options.policyStoreId, options.client);
+
+  const live: AvpLivePolicy[] = 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: readonly AvpLivePolicy[]): Map<string, AvpLivePolicy> {
+  const index = new Map<string, AvpLivePolicy>();
+  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/src/avp/testdata/mock-transport.ts

@@ -0,0 +1,147 @@
+/**
+ * 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 type { AvpHttp } from "../client";
+import { encodeOwnershipDescription } from "../ownership";
+
+/** One policy the fake store holds. */
+export interface MockPolicy {
+  policyId: string;
+  statement: string;
+  description?: string;
+  policyType?: string;
+  createdDate?: string;
+  lastUpdatedDate?: string;
+  /** Make `GetPolicy` fail for this one, to exercise a per-policy hole. */
+  getFails?: boolean;
+}
+
+export interface MockStore {
+  policyStoreId: string;
+  policies: MockPolicy[];
+  /** Page size, so the pagination loop is actually exercised. */
+  pageSize?: number;
+  /** Fail `ListPolicies` with this AWS error code. */
+  listFails?: { code: string; message: string; status?: number };
+  tags?: Record<string, string>;
+  arn?: string;
+}
+
+/** A chant-stamped description for a policy the fake store should read as owned. */
+export function markedDescription(
+  policyId: string,
+  text = "",
+  marker: { stack: string; env?: string } = { stack: "authz", env: "prod" },
+): string {
+  return encodeOwnershipDescription(text, marker, policyId);
+}
+
+/** A statement carrying the `@id` a chant entity resolves to. */
+export function statementFor(policyId: string, body = "permit (\n  principal,\n  action,\n  resource\n)"): string {
+  return `@id("${policyId}")\n${body};`;
+}
+
+export interface MockTransport {
+  http: AvpHttp;
+  /** Every operation issued, in order — for asserting round-trip counts. */
+  calls: Array<{ operation: string; payload: Record<string, unknown> }>;
+}
+
+/** Build an {@link AvpHttp} over one fake store. */
+export function mockAvpTransport(store: MockStore): MockTransport {
+  const calls: Array<{ operation: string; payload: Record<string, unknown> }> = [];
+  const pageSize = store.pageSize ?? 50;
+
+  const error = (type: string, message: string, status = 400) => ({
+    status,
+    text: JSON.stringify({ __type: `com.amazonaws.verifiedpermissions#${type}`, message }),
+  });
+
+  const definitionOf = (policy: MockPolicy, withStatement: boolean) => ({
+    static: {
+      ...(policy.description !== undefined ? { description: policy.description } : {}),
+      ...(withStatement ? { statement: policy.statement } : {}),
+    },
+  });
+
+  const http: AvpHttp = async (_url, init) => {
+    const operation = (init.headers["x-amz-target"] ?? "").split(".").pop() ?? "";
+    const payload = JSON.parse(init.body) as Record<string, unknown>;
+    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: Record<string, string | undefined> = {
+  AWS_ENDPOINT_URL: "http://localhost:4566",
+};

package/src/codegen/docs-cli.ts

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