@intentius/chant-lexicon-aws 0.124.52 → 0.124.54

package/src/index-import.ts

@@ -0,0 +1,140 @@
+/**
+ * The aws lexicon's index import seam (#4524, `chant import --index`).
+ *
+ * behold's lister reads AWS through Cloud Control, which returns each
+ * object's CloudFormation resource model, and #4521 normalizes it with this
+ * lexicon's deep hooks. So an indexed node's `attrs` already are
+ * CloudFormation properties, and the import IR is the one the CloudFormation
+ * template parser writes (`{ __intrinsic: "Ref" }` and so on), which
+ * `CFGenerator` turns into source.
+ *
+ * - Properties the schema lists in `readOnlyProperties` (the registry's
+ *   `attrs`) are left out, because no declaration can set them. Tags whose
+ *   key starts with `aws:` are left out too: CloudFormation sets them and
+ *   refuses them in a template.
+ * - A value that names another imported resource becomes `Ref` when it is
+ *   that resource's Cloud Control identifier (a single-part one; for the
+ *   types the catalog joins, Ref returns that identifier), and
+ *   `GetAtt(<id>, "Arn")` when it is the resource's ARN and the type has an
+ *   `Arn` attribute. Anything else stays a literal.
+ * - A masked value becomes a `String` parameter with `NoEcho`.
+ */
+import { createRequire } from "module";
+import { moduleSourceUrl } from "@intentius/chant/module-source";
+import type { IRNode } from "@intentius/chant/graph-ir";
+import type { IndexImportCodegen, IndexImportTarget } from "@intentius/chant/lifecycle/index-import";
+import type { ParameterIR } from "@intentius/chant/import/parser";
+
+const require = createRequire(moduleSourceUrl(import.meta.url));
+
+/** One `lexicon-aws.json` entry, the fields this seam reads. */
+export interface ImportManifestEntry {
+  resourceType: string;
+  kind: string;
+  /** GetAtt name -> CloudFormation attribute: the schema's `readOnlyProperties`. */
+  attrs?: Record<string, string>;
+}
+
+let cachedManifest: ReadonlyMap<string, ImportManifestEntry> | undefined;
+
+/** The generated registry keyed by type, or an empty map in a checkout that has not generated. */
+function defaultManifest(): ReadonlyMap<string, ImportManifestEntry> {
+  if (cachedManifest) return cachedManifest;
+  try {
+    const manifest = require("./generated/lexicon-aws.json") as Record<string, ImportManifestEntry>;
+    cachedManifest = new Map(Object.values(manifest).filter((e) => e.kind === "resource").map((e) => [e.resourceType, e]));
+  } catch {
+    cachedManifest = new Map();
+  }
+  return cachedManifest;
+}
+
+const CFN_TYPE = /^AWS::[A-Za-z0-9]+::[A-Za-z0-9]+$/;
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** Tags without the `aws:` ones, in either shape CloudFormation uses (a Key/Value list or a map). */
+function withoutAwsTags(tags: unknown): unknown {
+  if (Array.isArray(tags)) {
+    return tags.filter((t) => !(isRecord(t) && typeof t.Key === "string" && t.Key.startsWith("aws:")));
+  }
+  if (isRecord(tags)) {
+    return Object.fromEntries(Object.entries(tags).filter(([k]) => !k.startsWith("aws:")));
+  }
+  return tags;
+}
+
+/** The properties a declaration of `type` can hold, from an indexed node's attrs. */
+export function awsImportProperties(
+  type: string,
+  attrs: Record<string, unknown>,
+  manifest: ReadonlyMap<string, ImportManifestEntry> = defaultManifest(),
+): Record<string, unknown> {
+  const readOnly = new Set(Object.values(manifest.get(type)?.attrs ?? {}).map((a) => a.split(".")[0]));
+  const out: Record<string, unknown> = {};
+  for (const key of Object.keys(attrs).sort()) {
+    if (readOnly.has(key)) continue;
+    const value = key === "Tags" ? withoutAwsTags(attrs[key]) : attrs[key];
+    if (key === "Tags" && ((Array.isArray(value) && value.length === 0) || (isRecord(value) && Object.keys(value).length === 0))) continue;
+    out[key] = value;
+  }
+  return out;
+}
+
+/** True when `type` exposes `Arn` to GetAtt, or when there is no registry to ask. */
+function hasArnAttribute(type: string, manifest: ReadonlyMap<string, ImportManifestEntry>): boolean {
+  if (manifest.size === 0) return true;
+  return Object.values(manifest.get(type)?.attrs ?? {}).includes("Arn");
+}
+
+/** `value` as a reference to `target`, or undefined. */
+export function awsImportReference(
+  value: string,
+  target: IndexImportTarget,
+  manifest: ReadonlyMap<string, ImportManifestEntry> = defaultManifest(),
+): unknown | undefined {
+  const node = target.node;
+  if (node.nativeId !== undefined && value === node.nativeId && !value.includes("|")) {
+    return { __intrinsic: "Ref", name: target.logicalId };
+  }
+  const isArn = (node.facts?.cloudIds ?? []).some((c) => c.kind === "arn" && c.value === value);
+  if (isArn && hasArnAttribute(node.kind, manifest)) {
+    return { __intrinsic: "GetAtt", logicalId: target.logicalId, attribute: "Arn" };
+  }
+  return undefined;
+}
+
+/** The resource attributes `chant import --index` writes on every resource it imports (#4536). */
+export const ADOPTED_RESOURCE_ATTRIBUTES: Readonly<Record<string, string>> = { DeletionPolicy: "Retain", UpdateReplacePolicy: "Retain" };
+
+export function createAwsIndexImport(manifest?: ReadonlyMap<string, ImportManifestEntry>): IndexImportCodegen {
+  const m = () => manifest ?? defaultManifest();
+  return {
+    resource(node: IRNode) {
+      if (!CFN_TYPE.test(node.kind)) return { unsupported: `${node.kind} is not a CloudFormation resource type` };
+      // Retain on every imported resource until a person changes it in source
+      // (#4536, ruled on choudoufu#2284 Q4): CloudFormation deletes at stack
+      // level and reads no per-resource marker, so an adopted object is never
+      // deleted on the stack's word alone. Import requires a DeletionPolicy.
+      return { type: node.kind, properties: awsImportProperties(node.kind, node.attrs ?? {}, m()), attributes: { ...ADOPTED_RESOURCE_ATTRIBUTES } };
+    },
+    reference: (value, target) => awsImportReference(value, target, m()),
+    secretParameter(name, context): ParameterIR {
+      return {
+        name,
+        type: "String",
+        description: `${context.path} of ${context.node.id}, masked in the index`,
+        constraints: { NoEcho: true },
+      };
+    },
+    parameterReference: (name) => ({ __intrinsic: "Ref", name }),
+    typeLabel(node) {
+      const last = node.kind.split("::").pop() ?? "Resource";
+      return last.charAt(0).toUpperCase() + last.slice(1);
+    },
+  };
+}
+
+export const awsIndexImport: IndexImportCodegen = createAwsIndexImport();

package/src/index-search.test.ts

@@ -0,0 +1,87 @@
+/**
+ * #4525 on the aws lexicon: `chant search --index`'s join over the identity
+ * fixture (#4523's, ./testdata/indexed/identity.listing.json). A declared
+ * source with a bucket and a role made outside chant, a bucket that does not
+ * exist, a queue, an instance and a table outside the index's --types, joined
+ * through the aws lexicon's own index match. Each row gets one verdict, and
+ * the overlay carries what the index read onto the bound rows only.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import type { GraphIR, IRNode } from "@intentius/chant/graph-ir";
+import type { IndexIdentity } from "@intentius/chant/lifecycle/identity-match";
+import { joinDeclaredToIndex } from "@intentius/chant/lifecycle/index-join";
+import { typeListing, type ListingLexicon, type ListingResult } from "@intentius/chant/lifecycle/type-listing";
+import { awsDeclaredIdentity, awsIndexIdentity, type IdentityManifestEntry } from "./index-identity";
+import { awsKindForListedType } from "./listed-types";
+import { awsPlugin } from "./plugin";
+
+// The manifest rows these types generate, as index-identity.test.ts reads them.
+const ROWS: IdentityManifestEntry[] = [
+  { resourceType: "AWS::S3::Bucket", kind: "resource", primaryIdentifier: ["BucketName"], attrs: { Arn: "Arn", DomainName: "DomainName", RegionalDomainName: "RegionalDomainName", WebsiteURL: "WebsiteURL" } },
+  { resourceType: "AWS::IAM::Role", kind: "resource", primaryIdentifier: ["RoleName"], attrs: { Arn: "Arn", RoleId: "RoleId" } },
+  { resourceType: "AWS::SQS::Queue", kind: "resource", primaryIdentifier: ["QueueUrl"], attrs: { Arn: "Arn", QueueUrl: "QueueUrl" } },
+  { resourceType: "AWS::EC2::Instance", kind: "resource", primaryIdentifier: ["InstanceId"], attrs: { InstanceId: "InstanceId", PrivateIp: "PrivateIp", PublicIp: "PublicIp" } },
+  { resourceType: "AWS::DynamoDB::Table", kind: "resource", primaryIdentifier: ["TableName"], attrs: { Arn: "Arn", StreamArn: "StreamArn" } },
+];
+const MANIFEST: ReadonlyMap<string, IdentityManifestEntry> = new Map(ROWS.map((e) => [e.resourceType, e]));
+const identity: IndexIdentity = { ...awsIndexIdentity, declaredIdentity: (t, p) => awsDeclaredIdentity(t, p, MANIFEST) };
+const KINDS: ReadonlySet<string> = new Set(MANIFEST.keys());
+const aws: ListingLexicon = {
+  name: awsPlugin.name,
+  deepNormalizationHooks: awsPlugin.deepNormalizationHooks,
+  listedTypes: { ...awsPlugin.listedTypes!, kindFor: (t) => awsKindForListedType(t, KINDS) },
+};
+const listing = JSON.parse(readFileSync(join(import.meta.dirname, "testdata", "indexed", "identity.listing.json"), "utf-8")) as ListingResult;
+const doc = typeListing(listing, [aws]);
+
+const node = (name: string, kind: string, attrs: Record<string, unknown>): IRNode => ({ id: `app::${name}`, kind, lexicon: "aws", attrs });
+const declared: GraphIR = {
+  version: 1,
+  nodes: [
+    node("assets", "AWS::S3::Bucket", { BucketName: "cli-made-assets" }),
+    node("runner", "AWS::IAM::Role", { RoleName: "cli-made-role", AssumeRolePolicyDocument: {} }),
+    node("archive", "AWS::S3::Bucket", { BucketName: "never-made-archive" }),
+    node("jobs", "AWS::SQS::Queue", { QueueName: "cli-made-queue" }),
+    node("box", "AWS::EC2::Instance", { InstanceType: "t3.micro", ImageId: "ami-0abcdef1234567890" }),
+    node("carts", "AWS::DynamoDB::Table", { TableName: "carts" }),
+  ],
+  edges: [],
+  groups: { byLexicon: {} },
+};
+
+describe("search --index's join on the aws fixture", () => {
+  const { ir, joins } = joinDeclaredToIndex(declared, doc, [{ name: "aws", indexIdentity: identity }], { regionOf: () => "us-east-1" });
+  const row = (name: string) => ir.nodes.find((n) => n.id === `app::${name}`)!;
+
+  test("the bucket and role made outside chant are bound, with what the index read about them", () => {
+    expect(joins["app::assets"]).toMatchObject({ verdict: "bound", node: "aws/000000000000/us-east-1/AWS::S3::Bucket/cli-made-assets", nativeId: "cli-made-assets" });
+    expect(joins["app::runner"]).toMatchObject({ verdict: "bound", node: "aws/000000000000/global/AWS::IAM::Role/cli-made-role", location: "global" });
+    expect(row("assets").physicalId).toBe("cli-made-assets");
+    // The aws hooks prune read-only properties such as Arn from the indexed tree
+    // (#4521: an indexed tree has the shape an observed one has); the index
+    // carries the ARN as a cloud id in the node's facts.
+    expect(row("assets").attrs?.BucketName).toBe("cli-made-assets");
+    expect(row("assets").facts?.cloudIds).toContainEqual({ kind: "arn", value: "arn:aws:s3:::cli-made-assets" });
+  });
+
+  test("the bucket the index listed and did not find is absent", () => {
+    expect(joins["app::archive"]).toMatchObject({ verdict: "absent", identifier: "never-made-archive", location: "us-east-1" });
+    expect(row("archive").physicalId).toBeUndefined();
+  });
+
+  test("the queue and the instance spell no identity: no-binding, though both are indexed", () => {
+    expect(joins["app::jobs"]).toMatchObject({ verdict: "no-binding", detail: expect.stringContaining("QueueUrl") });
+    expect(joins["app::box"]).toMatchObject({ verdict: "no-binding", detail: expect.stringContaining("InstanceId") });
+    expect(row("jobs").physicalId).toBeUndefined();
+  });
+
+  test("the table outside --types is not observed, filtered", () => {
+    expect(joins["app::carts"]).toMatchObject({ verdict: "not-observed", reason: "filtered", listedType: "AWS::DynamoDB::Table" });
+  });
+
+  test("only the declared rows are in the answer", () => {
+    expect(ir.nodes.map((n) => n.id).sort()).toEqual(declared.nodes.map((n) => n.id).sort());
+  });
+});

package/src/listed-types.test.ts

@@ -0,0 +1,97 @@
+/**
+ * #4521 on the aws lexicon: Cloud Control's type names mapped to kinds, a
+ * fixture listing typed into nodes, and a capability that answers the same
+ * over the indexed fixture as over the equivalent declared graph.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import type { GraphIR } from "@intentius/chant/graph-ir";
+import { typeListing, type ListingLexicon, type ListingResult } from "@intentius/chant/lifecycle/type-listing";
+import { CapabilityEngine } from "@intentius/chant/capabilities/matcher";
+import { buildView, displayName } from "@intentius/chant/capabilities/view";
+import { resolvePacks, shippedRules } from "@intentius/chant/capabilities/catalog";
+import { MASKED } from "@intentius/chant/deep-observation";
+import { awsCapabilityPack } from "./capabilities/pack";
+import { awsKindForListedType, awsListedTypeForKind } from "./listed-types";
+import { awsPlugin } from "./plugin";
+
+const here = import.meta.dirname;
+const surface = JSON.parse(readFileSync(join(here, "..", "surface.snapshot.json"), "utf-8")) as {
+  entries: Record<string, { kind: string; resourceType: string }>;
+};
+const KINDS: ReadonlySet<string> = new Set(
+  Object.values(surface.entries).filter((e) => e.kind === "resource").map((e) => e.resourceType),
+);
+const listing = JSON.parse(readFileSync(join(here, "testdata", "indexed", "listing.json"), "utf-8")) as ListingResult;
+
+// The plugin's own hooks, with the kind set pinned to the checked-in surface so
+// the test does not depend on whether `chant generate` has run.
+const aws: ListingLexicon = {
+  name: awsPlugin.name,
+  deepNormalizationHooks: awsPlugin.deepNormalizationHooks,
+  listedTypes: { ...awsPlugin.listedTypes!, kindFor: (t) => awsKindForListedType(t, KINDS) },
+};
+
+describe("Cloud Control types to aws kinds", () => {
+  it("every aws resource kind has a listed type that maps back to it", () => {
+    const missing = [...KINDS].filter((k) => awsKindForListedType(awsListedTypeForKind(k), KINDS) !== k);
+    expect(missing).toEqual([]);
+    expect(KINDS.size).toBeGreaterThan(1000);
+  });
+
+  it("a type outside the lexicon, or not a CloudFormation name, has no kind", () => {
+    expect(awsKindForListedType("AWS::IoTFleetHub::Application", KINDS)).toBeUndefined();
+    expect(awsKindForListedType("aws_s3_bucket", KINDS)).toBeUndefined();
+    expect(awsKindForListedType("Alexa::ASK::Skill", KINDS)).toBe("Alexa::ASK::Skill");
+  });
+
+  it("the plugin declares the mapping for the aws substrate", () => {
+    expect(awsPlugin.listedTypes?.substrate).toBe("aws");
+  });
+});
+
+describe("the aws fixture listing as typed nodes", () => {
+  const doc = typeListing(listing, [aws]);
+
+  it("produces a typed node per mapped object, and an unknown-kind node for the rest", () => {
+    expect(doc.graph.nodes.map((n) => [n.nativeId, n.kind, n.unmappedKind ?? false])).toEqual([
+      ["vol-0a1b2c3d4e5f60718", "AWS::EC2::Volume", false],
+      ["fleet-console", "AWS::IoTFleetHub::Application", true],
+      ["orders-db", "AWS::RDS::DBInstance", false],
+      ["reports-db", "AWS::RDS::DBInstance", false],
+      ["shop-assets", "AWS::S3::Bucket", false],
+    ]);
+    expect(doc.graph.nodes).toHaveLength(listing.resources.length);
+  });
+
+  it("normalizes through the aws hooks: read-only properties pruned, secrets masked", () => {
+    const bucket = doc.graph.nodes.find((n) => n.nativeId === "shop-assets")!;
+    expect(bucket.attrs).toEqual({ BucketName: "shop-assets" });
+    const db = doc.graph.nodes.find((n) => n.nativeId === "orders-db")!;
+    expect(db.attrs.MasterUserPassword).toBe(MASKED);
+    expect(db.attrs.StorageEncrypted).toBe(true);
+    expect(db.facts?.markers).toEqual({ owner: "shop", encoding: "escaped", source: "live" });
+  });
+
+  it("encrypted-at-rest matches the same resources over the index as over the declared graph", () => {
+    // The declared form of the same three resources, as source would carry them.
+    const declared: GraphIR = {
+      nodes: [
+        { id: "orders-db", kind: "AWS::RDS::DBInstance", lexicon: "aws", attrs: { DBInstanceIdentifier: "orders-db", Engine: "postgres", StorageEncrypted: true } },
+        { id: "reports-db", kind: "AWS::RDS::DBInstance", lexicon: "aws", attrs: { DBInstanceIdentifier: "reports-db", Engine: "postgres", StorageEncrypted: false } },
+        { id: "vol-0a1b2c3d4e5f60718", kind: "AWS::EC2::Volume", lexicon: "aws", attrs: { AvailabilityZone: "us-east-1a", Size: 20, Encrypted: true } },
+        { id: "shop-assets", kind: "AWS::S3::Bucket", lexicon: "aws", attrs: { BucketName: "shop-assets" } },
+      ],
+      edges: [],
+      groups: {},
+    };
+    const answer = (g: GraphIR) => {
+      const e = new CapabilityEngine(buildView(g, resolvePacks([awsCapabilityPack])), shippedRules().rules);
+      return [...e.set("encrypted-at-rest", e.bind("encrypted-at-rest", [] as never)).keys()].map(displayName).sort();
+    };
+    // aws.paths: S3 buckets are always encrypted at rest; the unencrypted database is the one left out.
+    expect(answer(declared)).toEqual(["orders-db", "shop-assets", "vol-0a1b2c3d4e5f60718"]);
+    expect(answer(doc.graph)).toEqual(answer(declared));
+  });
+});

package/src/listed-types.ts

@@ -0,0 +1,56 @@
+/**
+ * Cloud Control's type names as aws lexicon kinds (#4521).
+ *
+ * behold#1029 lists AWS through Cloud Control `ListResources`, which names
+ * each object by its CloudFormation type (`AWS::S3::Bucket`), and the aws
+ * lexicon's kinds are those same names. So the mapping is the identity, kept
+ * to the types the lexicon generated: a type outside `lexicon-aws.json` (one
+ * newer than the pinned registry, or a third-party type) has no kind here and
+ * stays an unknown-kind node. Cloud Control returns the CloudFormation
+ * resource model, which is the tree the deep reader returns too
+ * (./deep-observe.ts), so no reshaping.
+ */
+import { createRequire } from "module";
+import { moduleSourceUrl } from "@intentius/chant/module-source";
+import type { ListedTypeMapping } from "@intentius/chant/lifecycle/type-listing";
+
+const require = createRequire(moduleSourceUrl(import.meta.url));
+
+// A CloudFormation type name: `<Organization>::<Service>::<Resource>`. The
+// organization is not always AWS (`Alexa::ASK::Skill`), so it is not pinned.
+const CFN_TYPE = /^[A-Za-z0-9]+::[A-Za-z0-9]+::[A-Za-z0-9]+$/;
+
+let cachedKinds: ReadonlySet<string> | null | undefined;
+
+/** The resource kinds `chant generate` wrote, or null in a checkout that has not generated. */
+function generatedKinds(): ReadonlySet<string> | null {
+  if (cachedKinds !== undefined) return cachedKinds;
+  try {
+    const manifest = require("./generated/lexicon-aws.json") as Record<string, { resourceType: string; kind: string }>;
+    cachedKinds = new Set(Object.values(manifest).filter((e) => e.kind === "resource").map((e) => e.resourceType));
+  } catch {
+    cachedKinds = null;
+  }
+  return cachedKinds;
+}
+
+/**
+ * The aws kind for a Cloud Control type, or undefined. With no kind set (no
+ * generated registry) every well-formed CloudFormation type maps, which is
+ * what the rest of the lexicon assumes before `chant generate` has run.
+ */
+export function awsKindForListedType(listedType: string, kinds: ReadonlySet<string> | null = generatedKinds()): string | undefined {
+  if (!CFN_TYPE.test(listedType)) return undefined;
+  if (kinds && !kinds.has(listedType)) return undefined;
+  return listedType;
+}
+
+/** The inverse, for tests and for a reader naming what to list: the same name. */
+export function awsListedTypeForKind(kind: string): string {
+  return kind;
+}
+
+export const awsListedTypes: ListedTypeMapping = {
+  substrate: "aws",
+  kindFor: (listedType) => awsKindForListedType(listedType),
+};

package/src/plugin.ts

@@ -3,6 +3,9 @@ import { createRequire } from "module";
 import { awsBehaviourKinds } from "./behaviour-kinds";
 import { detectTemplate } from "./detect";
 import { awsCapabilityPack } from "./capabilities/pack";
+import { awsListedTypes } from "./listed-types";
+import { awsIndexIdentity } from "./index-identity";
+import { awsIndexImport } from "./index-import";
 import type { LexiconPlugin, IntrinsicDef, ObservationResult, DeepObservationResult, DependencyObservation, DescribeIdentityOptions, DescribeIdentityResult, DisruptionQuery, DisruptionVerdict, ResourceMetadata, ExportedTemplate, ResourceSelector, InitTemplateSet, StackStatusObservation } from "@intentius/chant/lexicon";
 const require = createRequire(moduleSourceUrl(import.meta.url));
 import type { LintRule } from "@intentius/chant/lint/rule";
@@ -98,6 +101,13 @@ export const awsPlugin: LexiconPlugin = {
   referenceCatalog: awsReferenceCatalog,
   capabilityPack: awsCapabilityPack,
 
+  // Cloud inventory type names to kinds, for an indexed resource (#4521).
+  listedTypes: awsListedTypes,
+  // Declared entities to indexed resources by primaryIdentifier (#4523).
+  indexIdentity: awsIndexIdentity,
+  // Indexed resources as CloudFormation import IR, for `chant import --index` (#4524).
+  indexImport: awsIndexImport,
+
   lintRules(): LintRule[] {
     const rulesDir = join(dirname(fileURLToPath(import.meta.url)), "lint", "rules");
     return discoverLintRules(rulesDir, import.meta.url);

package/src/reference-catalog.ts

@@ -28,6 +28,22 @@ export const awsReferenceCatalog: ReferenceCatalog = {
     { kind: "AWS::ECS::Service", ids: ["ServiceArn"] },
     { kind: "AWS::ECS::TaskDefinition", ids: ["TaskDefinitionArn"] },
     { kind: "AWS::RDS::DBInstance", ids: ["DBInstanceArn", "Endpoint.Address"] },
+    // Targets of the CloudFormation-shape rules an index needs (#4522, the
+    // missing rules counted on INTENTIUS/behold#1023). Over an index each
+    // node is also matched by its Cloud Control identifier and its cloud ids,
+    // so a role's ARN joins even though the deep hooks prune `Arn`.
+    { kind: "AWS::RDS::DBSubnetGroup", ids: ["DBSubnetGroupName"] },
+    { kind: "AWS::IAM::Role", ids: ["Arn", "RoleName"] },
+    { kind: "AWS::EC2::EIP", ids: ["AllocationId", "PublicIp"] },
+    { kind: "AWS::Logs::LogGroup", ids: ["LogGroupName", "Arn"] },
+    { kind: "AWS::Route53::HostedZone", ids: ["Id"] },
+    { kind: "AWS::EKS::Cluster", ids: ["Name", "Arn"] },
+    { kind: "AWS::CloudFormation::Stack", ids: ["StackId"] },
+    // #4535: a record set is named by its record name, which is what a CNAME
+    // in the same zone points at; a bucket by its name, which is what a
+    // workload's env var carries (behold#166, ../../k8s/src/reference-catalog.ts).
+    { kind: "AWS::Route53::RecordSet", ids: ["Name"] },
+    { kind: "AWS::S3::Bucket", ids: ["BucketName"] },
   ],
   refs: [
     // ── containment (→ boundary boxes, #779) ──
@@ -86,25 +102,52 @@ export const awsReferenceCatalog: ReferenceCatalog = {
     // intrinsics to bare logical ids (= node ids), so these match by node id; the
     // property names are the CFN template shape (SecurityGroupIds, Cluster, …),
     // which differs from the describe/SDK shape above. No targetKind needed —
-    // logical ids are unique.
-    { from: "AWS::EC2::Subnet", path: "VpcId", relation: "containment", label: "in VPC" },
-    { from: "AWS::EC2::SecurityGroup", path: "VpcId", relation: "containment", label: "in VPC" },
-    { from: "AWS::EC2::RouteTable", path: "VpcId", relation: "containment", label: "in VPC" },
-    { from: "AWS::EC2::Instance", path: "SubnetId", relation: "containment", label: "in subnet" },
-    { from: "AWS::EC2::Instance", path: "SecurityGroupIds[]", relation: "reference", label: "sg" },
-    { from: "AWS::EC2::NatGateway", path: "SubnetId", relation: "containment", label: "in subnet" },
-    { from: "AWS::EC2::Route", path: "RouteTableId", relation: "reference", label: "in" },
-    { from: "AWS::EC2::Route", path: "GatewayId", relation: "reference", label: "via" },
-    { from: "AWS::EC2::Route", path: "NatGatewayId", relation: "reference", label: "via" },
-    { from: "AWS::ElasticLoadBalancingV2::LoadBalancer", path: "Subnets[]", relation: "containment", label: "in subnet" },
-    { from: "AWS::ElasticLoadBalancingV2::LoadBalancer", path: "SecurityGroups[]", relation: "reference", label: "sg" },
-    { from: "AWS::ElasticLoadBalancingV2::TargetGroup", path: "VpcId", relation: "containment", label: "in VPC" },
-    { from: "AWS::ElasticLoadBalancingV2::Listener", path: "LoadBalancerArn", relation: "reference", label: "on" },
-    { from: "AWS::ElasticLoadBalancingV2::Listener", path: "DefaultActions[].TargetGroupArn", relation: "reference", label: "forwards to" },
-    { from: "AWS::ECS::Service", path: "Cluster", relation: "reference", label: "in cluster" },
-    { from: "AWS::ECS::Service", path: "TaskDefinition", relation: "reference", label: "runs" },
-    { from: "AWS::ECS::Service", path: "LoadBalancers[].TargetGroupArn", relation: "reference", label: "registered in" },
-    { from: "AWS::RDS::DBInstance", path: "DBSubnetGroupName", relation: "reference", label: "subnets" },
-    { from: "AWS::RDS::DBInstance", path: "VPCSecurityGroups[]", relation: "reference", label: "sg" },
+    // logical ids are unique. Over an index (#4522) the same paths hold physical
+    // values, some of them names, so each carries the `indexedTargetKind` it
+    // takes there (ruled on INTENTIUS/behold#1023 Q4).
+    { from: "AWS::EC2::Subnet", path: "VpcId", indexedTargetKind: "AWS::EC2::VPC", relation: "containment", label: "in VPC" },
+    { from: "AWS::EC2::SecurityGroup", path: "VpcId", indexedTargetKind: "AWS::EC2::VPC", relation: "containment", label: "in VPC" },
+    { from: "AWS::EC2::RouteTable", path: "VpcId", indexedTargetKind: "AWS::EC2::VPC", relation: "containment", label: "in VPC" },
+    { from: "AWS::EC2::Instance", path: "SubnetId", indexedTargetKind: "AWS::EC2::Subnet", relation: "containment", label: "in subnet" },
+    { from: "AWS::EC2::Instance", path: "SecurityGroupIds[]", indexedTargetKind: "AWS::EC2::SecurityGroup", relation: "reference", label: "sg" },
+    { from: "AWS::EC2::NatGateway", path: "SubnetId", indexedTargetKind: "AWS::EC2::Subnet", relation: "containment", label: "in subnet" },
+    { from: "AWS::EC2::Route", path: "RouteTableId", indexedTargetKind: "AWS::EC2::RouteTable", relation: "reference", label: "in" },
+    { from: "AWS::EC2::Route", path: "GatewayId", indexedTargetKind: "AWS::EC2::InternetGateway", relation: "reference", label: "via" },
+    { from: "AWS::EC2::Route", path: "NatGatewayId", indexedTargetKind: "AWS::EC2::NatGateway", relation: "reference", label: "via" },
+    { from: "AWS::ElasticLoadBalancingV2::LoadBalancer", path: "Subnets[]", indexedTargetKind: "AWS::EC2::Subnet", relation: "containment", label: "in subnet" },
+    { from: "AWS::ElasticLoadBalancingV2::LoadBalancer", path: "SecurityGroups[]", indexedTargetKind: "AWS::EC2::SecurityGroup", relation: "reference", label: "sg" },
+    { from: "AWS::ElasticLoadBalancingV2::TargetGroup", path: "VpcId", indexedTargetKind: "AWS::EC2::VPC", relation: "containment", label: "in VPC" },
+    { from: "AWS::ElasticLoadBalancingV2::Listener", path: "LoadBalancerArn", indexedTargetKind: "AWS::ElasticLoadBalancingV2::LoadBalancer", relation: "reference", label: "on" },
+    { from: "AWS::ElasticLoadBalancingV2::Listener", path: "DefaultActions[].TargetGroupArn", indexedTargetKind: "AWS::ElasticLoadBalancingV2::TargetGroup", relation: "reference", label: "forwards to" },
+    { from: "AWS::ECS::Service", path: "Cluster", indexedTargetKind: "AWS::ECS::Cluster", relation: "reference", label: "in cluster" },
+    { from: "AWS::ECS::Service", path: "TaskDefinition", indexedTargetKind: "AWS::ECS::TaskDefinition", relation: "reference", label: "runs" },
+    { from: "AWS::ECS::Service", path: "LoadBalancers[].TargetGroupArn", indexedTargetKind: "AWS::ElasticLoadBalancingV2::TargetGroup", relation: "reference", label: "registered in" },
+    { from: "AWS::RDS::DBInstance", path: "DBSubnetGroupName", indexedTargetKind: "AWS::RDS::DBSubnetGroup", relation: "reference", label: "subnets" },
+    { from: "AWS::RDS::DBInstance", path: "VPCSecurityGroups[]", indexedTargetKind: "AWS::EC2::SecurityGroup", relation: "reference", label: "sg" },
+
+    // ── CloudFormation property shape, as Cloud Control returns it (#4522) ──
+    // The rules INTENTIUS/behold#1023's count found missing for an index of
+    // example-three-cloud. Targeted, so they hold over physical values and over
+    // logical ids alike.
+    { from: "AWS::EC2::VPCGatewayAttachment", path: "VpcId", targetKind: "AWS::EC2::VPC", relation: "reference", label: "attaches to" },
+    { from: "AWS::EC2::VPCGatewayAttachment", path: "InternetGatewayId", targetKind: "AWS::EC2::InternetGateway", relation: "reference", label: "attaches" },
+    { from: "AWS::EC2::NatGateway", path: "AllocationId", targetKind: "AWS::EC2::EIP", relation: "reference", label: "address" },
+    { from: "AWS::ECS::TaskDefinition", path: "ExecutionRoleArn", targetKind: "AWS::IAM::Role", relation: "reference", label: "execution role" },
+    { from: "AWS::ECS::TaskDefinition", path: "TaskRoleArn", targetKind: "AWS::IAM::Role", relation: "reference", label: "task role" },
+    { from: "AWS::ECS::TaskDefinition", path: "ContainerDefinitions[].LogConfiguration.Options.awslogs-group", targetKind: "AWS::Logs::LogGroup", relation: "reference", label: "logs to" },
+    { from: "AWS::EC2::SecurityGroup", path: "SecurityGroupIngress[].SourceSecurityGroupId", targetKind: "AWS::EC2::SecurityGroup", relation: "reference", label: "allows" },
+    { from: "AWS::Route53::RecordSet", path: "HostedZoneId", targetKind: "AWS::Route53::HostedZone", relation: "containment", label: "in zone" },
+    // A CNAME to another record of the estate (#4535: example-three-cloud's
+    // latency record for gcp points at gcp.three-cloud.example.). Optional,
+    // since most record values are addresses or hostnames outside it.
+    { from: "AWS::Route53::RecordSet", path: "ResourceRecords[]", targetKind: "AWS::Route53::RecordSet", relation: "reference", label: "aliases", optional: true },
+  ],
+  // Tags that name a cloud id in their key or value (behold#1023 Q5). Used
+  // over indexed nodes only. No rule matches equal tag values in general.
+  tagRefs: [
+    { key: "aws:cloudformation:stack-id", read: "value", targetKind: "AWS::CloudFormation::Stack", label: "in stack" },
+    { key: "aws:eks:cluster-name", read: "value", targetKind: "AWS::EKS::Cluster", label: "cluster" },
+    { key: "eks:cluster-name", read: "value", targetKind: "AWS::EKS::Cluster", label: "cluster" },
+    { key: "kubernetes.io/cluster/", read: "key-suffix", targetKind: "AWS::EKS::Cluster", label: "cluster" },
   ],
 };

package/src/spec/fetch.ts

@@ -33,6 +33,11 @@ export interface CFNSchema {
     cloudFormationSystemTags?: boolean;
     tagProperty?: string;
   };
+  /**
+   * The resource provider's handlers (`create`, `read`, `update`, `delete`,
+   * `list`), each with its IAM permissions. A legacy type has none (#4536).
+   */
+  handlers?: Record<string, unknown>;
   additionalProperties?: boolean;
 }
 

package/src/spec/parse.test.ts

@@ -283,6 +283,21 @@ describe("parseCFNSchema", () => {
     });
   });
 
+  test("keeps the handlers section as its sorted operation names (#4536)", () => {
+    const schema = JSON.stringify({
+      typeName: "AWS::Test::Handled",
+      properties: { Name: { type: "string" } },
+      handlers: { read: { permissions: ["test:Get"] }, create: { permissions: ["test:Create"] }, delete: { permissions: [] } },
+      additionalProperties: false,
+    });
+    expect(parseCFNSchema(schema).resource.handlers).toEqual(["create", "delete", "read"]);
+  });
+
+  test("omits handlers when the schema has none, as a legacy type does (#4536)", () => {
+    const schema = JSON.stringify({ typeName: "AWS::Test::Legacy", properties: { Name: { type: "string" } }, additionalProperties: false });
+    expect(parseCFNSchema(schema).resource.handlers).toBeUndefined();
+  });
+
   test("omits tagging when not taggable", () => {
     const schema = JSON.stringify({
       typeName: "AWS::Test::NotTaggable",

package/src/spec/parse.ts

@@ -80,6 +80,14 @@ export interface ParsedResource {
   conditionalCreateOnly: string[];
   replacementStrategy?: "delete_then_create" | "create_then_delete";
   tagging?: ResourceTagging;
+  /**
+   * The schema's `handlers` section as its operation names, sorted
+   * (`["create", "delete", "list", "read", "update"]`). The permissions each
+   * handler lists are left out. Absent when the schema has no handlers, as a
+   * legacy type does. CloudFormation can import a type with `create` and
+   * `read` (../importable.ts, #4536).
+   */
+  handlers?: string[];
 }
 
 /** How a type's tags are written: a `[{Key, Value}]` list or a key-to-value map. */
@@ -223,6 +231,9 @@ export function parseCFNSchema(data: string | Buffer): SchemaParseResult {
     };
   }
 
+  // --- Handlers (#4536): which operations the resource provider implements ---
+  const handlers = schema.handlers && typeof schema.handlers === "object" ? Object.keys(schema.handlers).sort() : [];
+
   // --- Replacement strategy ---
   let replacementStrategy: ParsedResource["replacementStrategy"];
   if (schema.replacementStrategy === "delete_then_create" || schema.replacementStrategy === "create_then_delete") {
@@ -252,6 +263,7 @@ export function parseCFNSchema(data: string | Buffer): SchemaParseResult {
       conditionalCreateOnly: stripPointerPaths(schema.conditionalCreateOnlyProperties ?? [], schema),
       ...(replacementStrategy && { replacementStrategy }),
       ...(tagging && { tagging }),
+      ...(handlers.length > 0 && { handlers }),
     },
     propertyTypes: boundedPropertyTypes,
     enums,