@intentius/chant-lexicon-aws 0.45.0 → 0.49.0

package/src/deep-observe.test.ts

@@ -25,9 +25,10 @@ const {
   awsDeepNormalizationHooks,
   hasOwnershipMarker,
   schemaReadOnlyPatterns,
+  outOfBandChildName,
 } = await import("./deep-observe");
 const { parseResourceDescription } = await import("./api/read-client");
-const { deepDiffForLexicon } = await import("@intentius/chant/lifecycle/deep-observe");
+const { deepDiffForLexicon, diffDeepObservation } = await import("@intentius/chant/lifecycle/deep-observe");
 const { normalizeDeepObservation, normalizeDeepProperties, flattenDeepProperties } = await import("@intentius/chant/deep-observation");
 
 const ok = (text: string) => ({ status: 200, text });
@@ -598,6 +599,205 @@ describe("observeResourcesDeepAws", () => {
   });
 });
 
+/**
+ * The out-of-band pass (#1015): child resources that exist live under a
+ * declared parent and correspond to nothing in the stack, in the estate, or
+ * in source — the console-added SNS subscription and inline role policy the
+ * issue names. Cloud Control's `ListResources` is scoped to one parent by
+ * `ResourceModel`, and everything the listing returns is sorted into
+ * declared or out-of-band.
+ */
+describe("out-of-band children (#1015)", () => {
+  /** A Cloud Control `ListResources` body — each model a JSON string, like `GetResource`. */
+  const list = (descriptions: Array<[string, Record<string, unknown>]>) =>
+    ok(
+      JSON.stringify({
+        ResourceDescriptions: descriptions.map(([id, props]) => ({
+          Identifier: id,
+          Properties: JSON.stringify(props),
+        })),
+      }),
+    );
+
+  test("a console-added inline policy surfaces as an entity nobody declared", async () => {
+    const fake = httpFake((_identifier, call) => {
+      if (!call.target) {
+        return stackResources([
+          ["AppRole", "AWS::IAM::Role", "app-role"],
+          // The stack's own inline policy, deployed under its Cloud Control
+          // identifier (`PolicyName|RoleName`, the schema's own order).
+          ["Inline", "AWS::IAM::RolePolicy", "declared-pol|app-role"],
+        ]);
+      }
+      if (call.target === "CloudApiService.ListResources") {
+        return list([
+          ["declared-pol|app-role", { RoleName: "app-role", PolicyName: "declared-pol" }],
+          [
+            "debug-access|app-role",
+            {
+              RoleName: "app-role",
+              PolicyName: "debug-access",
+              PolicyDocument: { Statement: [{ Sid: "Debug", Effect: "Allow", Action: ["s3:*"], Resource: "*" }] },
+            },
+          ],
+        ]);
+      }
+      return cloudControl("app-role", { RoleName: "app-role" });
+    });
+    const result = normalizeDeepObservation(
+      await observeResourcesDeepAws({ environment: "prod", entityNames: ["AppRole", "Inline"], http: fake.http }),
+    );
+
+    const name = outOfBandChildName("AWS::IAM::RolePolicy", "debug-access|app-role");
+    expect(result.resources[name]).toMatchObject({
+      type: "AWS::IAM::RolePolicy",
+      physicalId: "debug-access|app-role",
+    });
+    expect(result.resources[name].properties.PolicyName).toBe("debug-access");
+    // The stack's own inline policy is declared, not a finding.
+    expect(Object.keys(result.resources)).not.toContain(
+      outOfBandChildName("AWS::IAM::RolePolicy", "declared-pol|app-role"),
+    );
+    // The listing was scoped to the parent the stack read resolved.
+    const listing = fake.calls.find((c) => c.target === "CloudApiService.ListResources");
+    expect(JSON.parse(listing?.body ?? "{}")).toEqual({
+      TypeName: "AWS::IAM::RolePolicy",
+      ResourceModel: JSON.stringify({ RoleName: "app-role" }),
+    });
+  });
+
+  test("a console-added SNS subscription surfaces even though the topic has no deep reader", async () => {
+    const topicArn = "arn:aws:sns:us-east-1:111122223333:alerts";
+    const fake = httpFake((_identifier, call) => {
+      if (!call.target) {
+        return stackResources([
+          ["Alerts", "AWS::SNS::Topic", topicArn],
+          ["Mail", "AWS::SNS::Subscription", `${topicArn}:5d5a2c73`],
+        ]);
+      }
+      if (call.target === "CloudApiService.ListResources") {
+        return list([
+          [`${topicArn}:5d5a2c73`, { TopicArn: topicArn, Protocol: "email" }],
+          [`${topicArn}:rogue`, { TopicArn: topicArn, Protocol: "https", Endpoint: "https://n.example" }],
+        ]);
+      }
+      return apiError("ValidationException", "nothing else should be read");
+    });
+    const result = normalizeDeepObservation(
+      await observeResourcesDeepAws({ environment: "prod", entityNames: ["Alerts", "Mail"], http: fake.http }),
+    );
+
+    // The topic itself stays a hole — no deep reader — but the listing under
+    // it needs only the physical id the stack already resolved.
+    expect(result.unobserved.Alerts?.reason).toBe("unsupported-kind");
+    expect(Object.keys(result.resources)).toEqual([
+      outOfBandChildName("AWS::SNS::Subscription", `${topicArn}:rogue`),
+    ]);
+  });
+
+  test("a legacy AWS::IAM::Policy attachment is declared, not out-of-band", async () => {
+    const fake = httpFake((_identifier, call) => {
+      if (!call.target) {
+        return stackResources([
+          ["AppRole", "AWS::IAM::Role", "app-role"],
+          // The legacy inline form: its physical id is the policy name, which
+          // is the first part of the RolePolicy identifier the listing returns.
+          ["LegacyPol", "AWS::IAM::Policy", "stack-legacypol-1ABC"],
+        ]);
+      }
+      if (call.target === "CloudApiService.ListResources") {
+        return list([["stack-legacypol-1ABC|app-role", { RoleName: "app-role", PolicyName: "stack-legacypol-1ABC" }]]);
+      }
+      return cloudControl("app-role", { RoleName: "app-role" });
+    });
+    const result = normalizeDeepObservation(
+      await observeResourcesDeepAws({ environment: "prod", entityNames: ["AppRole", "LegacyPol"], http: fake.http }),
+    );
+    expect(Object.keys(result.resources)).toEqual(["AppRole"]);
+  });
+
+  test("an identity spelled in source counts as declared before it reaches any stack", async () => {
+    // The carve case: the policy is declared, its identity is spelled in
+    // props, and no stack carries it yet. Listing it is not a finding.
+    const declared = entities({
+      AppRole: { entityType: "AWS::IAM::Role", props: { RoleName: "app-role" } },
+      Carved: { entityType: "AWS::IAM::RolePolicy", props: { RoleName: "app-role", PolicyName: "carved" } },
+    });
+    const fake = httpFake((_identifier, call) => {
+      if (!call.target) return stackResources([["AppRole", "AWS::IAM::Role", "app-role"]]);
+      if (call.target === "CloudApiService.ListResources") {
+        return list([["carved|app-role", { RoleName: "app-role", PolicyName: "carved" }]]);
+      }
+      return cloudControl("app-role", { RoleName: "app-role" });
+    });
+    const result = normalizeDeepObservation(
+      await observeResourcesDeepAws({
+        environment: "prod",
+        entityNames: ["AppRole", "Carved"],
+        entities: declared,
+        http: fake.http,
+      }),
+    );
+    expect(Object.keys(result.resources)).toEqual(["AppRole"]);
+  });
+
+  test("a failed child listing is silence about children, never a fabricated finding", async () => {
+    const fake = httpFake((_identifier, call) => {
+      if (!call.target) return stackResources([["AppRole", "AWS::IAM::Role", "app-role"]]);
+      if (call.target === "CloudApiService.ListResources") {
+        // Floci's answer for an operation it does not serve.
+        return apiError("UnsupportedOperation", "ListResources is not supported for AWS::IAM::RolePolicy");
+      }
+      return cloudControl("app-role", { RoleName: "app-role" });
+    });
+    const result = normalizeDeepObservation(
+      await observeResourcesDeepAws({ environment: "prod", entityNames: ["AppRole"], http: fake.http }),
+    );
+    expect(Object.keys(result.resources)).toEqual(["AppRole"]);
+    expect(result.unobserved).toEqual({});
+  });
+
+  test("--owned: a withheld parent keeps its children out of the report too", async () => {
+    const fake = httpFake((_identifier, call) => {
+      if (!call.target) return stackResources([["AppRole", "AWS::IAM::Role", "app-role"]]);
+      if (call.target === "CloudApiService.ListResources") {
+        return list([["debug-access|app-role", { RoleName: "app-role", PolicyName: "debug-access" }]]);
+      }
+      // No ownership tag: the parent is not chant's.
+      return cloudControl("app-role", { RoleName: "app-role" });
+    });
+    const result = normalizeDeepObservation(
+      await observeResourcesDeepAws({ environment: "prod", entityNames: ["AppRole"], owned: true, http: fake.http }),
+    );
+    expect(result.unobserved.AppRole?.reason).toBe("filtered");
+    expect(Object.keys(result.resources)).toEqual([]);
+    expect(fake.calls.some((c) => c.target === "CloudApiService.ListResources")).toBe(false);
+  });
+
+  test("the deep diff reports the child as an undeclared entity, and the declared estate stays clean", async () => {
+    const declared = entities({ AppRole: { entityType: "AWS::IAM::Role", props: { RoleName: "app-role" } } });
+    const fake = httpFake((_identifier, call) => {
+      if (!call.target) return stackResources([["AppRole", "AWS::IAM::Role", "app-role"]]);
+      if (call.target === "CloudApiService.ListResources") {
+        return list([["debug-access|app-role", { RoleName: "app-role", PolicyName: "debug-access" }]]);
+      }
+      return cloudControl("app-role", { RoleName: "app-role" });
+    });
+    const live = normalizeDeepObservation(
+      await observeResourcesDeepAws({
+        environment: "prod",
+        entityNames: ["AppRole"],
+        entities: declared,
+        http: fake.http,
+      }),
+    );
+    const result = diffDeepObservation(declared, live, awsDeepNormalizationHooks);
+    expect(result.undeclaredEntities).toEqual([outOfBandChildName("AWS::IAM::RolePolicy", "debug-access|app-role")]);
+    expect(result.unchanged).toEqual(["AppRole"]);
+    expect(result.drifted).toEqual([]);
+  });
+});
+
 /**
  * The acceptance test for #1015: the real plugin, a mutated live tree, a
  * baseline, and exactly the genuine drift.

package/src/deep-observe.ts

@@ -56,10 +56,19 @@ import {
   AwsReadError,
   describeStackResources,
   getResource,
+  listResources,
   type AwsReadClientOptions,
   type AwsReadHttp,
+  type StackResource,
 } from "./api/read-client";
+import { declaredIdentifier } from "./identity-observe";
 import { AWS_TAG_OWNERSHIP_KEYS } from "./ownership";
+import {
+  AWS_DEEP_BLIND_SPOTS,
+  EC2_TOPOLOGY_GENERATED_NAMES,
+  EC2_TOPOLOGY_SERVICE_DEFAULTS,
+  EC2_TOPOLOGY_SOURCES,
+} from "./deep-topology";
 import { applyAwsEndpointArgv } from "./components/cloud-executor";
 import { toIngressRules } from "./dependencies";
 import { createRequire } from "node:module";
@@ -106,6 +115,9 @@ export const DEEP_SOURCES: Record<string, DeepSource> = {
     id: "GroupId",
     toModel: securityGroupToModel,
   },
+  // The EC2 topology types the folds fold over (#1269), sources and
+  // translations alongside their type in ./deep-topology.ts.
+  ...EC2_TOPOLOGY_SOURCES,
 };
 
 /**
@@ -114,6 +126,74 @@ export const DEEP_SOURCES: Record<string, DeepSource> = {
  */
 export const DEEP_READABLE_TYPES: ReadonlySet<string> = new Set(Object.keys(DEEP_SOURCES));
 
+/**
+ * A child type this reader enumerates under one declared parent (#1015's
+ * out-of-band case) — the console-added SNS subscription or inline role
+ * policy that no property diff can see, because it is not a property of
+ * anything declared: it is a whole resource CloudFormation never made.
+ *
+ * Cloud Control's `ListResources` takes the parent as a `ResourceModel`
+ * scope, which is what `model` builds from the physical id the stack read
+ * already resolved. Every listed child is then sorted into declared (it is
+ * some stack resource's physical id, or some declared entity's spelled
+ * identity) or out-of-band; the out-of-band ones ride into the observation
+ * as live resources nobody declared, which the deep diff reports as
+ * undeclared entities.
+ */
+export interface DeepChildSource {
+  /** The child's CloudFormation type — what `ListResources` is asked for. */
+  childType: string;
+  /** The `ResourceModel` scoping the listing to one parent. */
+  model: (parentPhysicalId: string) => Record<string, unknown>;
+  /**
+   * Legacy declared forms of the same live child. `AWS::IAM::Policy` attached
+   * to a role creates the same inline policy `AWS::IAM::RolePolicy` lists, but
+   * under its own physical id — the policy name, which is the second part of
+   * the RolePolicy identifier. Without this leg every legacy inline policy
+   * reads as out-of-band on a stack that declared it.
+   */
+  declaredVia?: Array<{
+    type: string;
+    /** The part of the child identifier that carries that type's physical id. */
+    part: (identifier: string) => string | undefined;
+  }>;
+}
+
+/**
+ * Parent type → the child types worth listing under it. Scoped like
+ * {@link DEEP_SOURCES}: the high-signal cases first — the issue's own
+ * examples — and widened per type, not by wildcard. A child type Cloud
+ * Control cannot list parent-scoped does not belong here.
+ */
+export const DEEP_CHILD_SOURCES: Record<string, readonly DeepChildSource[]> = {
+  "AWS::IAM::Role": [
+    {
+      childType: "AWS::IAM::RolePolicy",
+      model: (roleName) => ({ RoleName: roleName }),
+      // A RolePolicy identifier is `PolicyName|RoleName` — the schema's own
+      // primaryIdentifier order, which is what the manifest records and what
+      // `declaredIdentifier` joins by. The legacy type's physical id is the
+      // policy name, the first part.
+      declaredVia: [{ type: "AWS::IAM::Policy", part: (id) => id.split("|")[0] }],
+    },
+  ],
+  "AWS::SNS::Topic": [
+    {
+      childType: "AWS::SNS::Subscription",
+      model: (topicArn) => ({ TopicArn: topicArn }),
+    },
+  ],
+};
+
+/**
+ * The name an out-of-band child reports under. There is no chant entity name
+ * to use — nobody declared it — so the name has to carry the finding on its
+ * own: what kind of thing, and which one.
+ */
+export function outOfBandChildName(childType: string, identifier: string): string {
+  return `${childType}:${identifier}`;
+}
+
 /**
  * `describe-security-groups` -> the `AWS::EC2::SecurityGroup` resource model.
  *
@@ -205,6 +285,7 @@ export const AWS_SERVICE_DEFAULTS: Record<string, Record<string, unknown>> = {
     "SecurityGroupEgress[].CidrIp": "0.0.0.0/0",
     "SecurityGroupEgress[].IpProtocol": "-1",
   },
+  ...EC2_TOPOLOGY_SERVICE_DEFAULTS,
 };
 
 /**
@@ -218,6 +299,7 @@ export const AWS_SERVICE_DEFAULTS: Record<string, Record<string, unknown>> = {
  */
 export const AWS_GENERATED_NAMES: Record<string, ReadonlySet<string>> = {
   "AWS::EC2::SecurityGroup": new Set(["GroupName"]),
+  ...EC2_TOPOLOGY_GENERATED_NAMES,
 };
 
 /** Stable JSON with sorted keys — the fallback ordering key for a set-like array. */
@@ -303,6 +385,18 @@ export const awsDeepNormalizationHooks: DeepNormalizationHooks = {
     if (schemaReadOnlyPatterns(node.entityType).has(node.pattern)) return true;
     if (AWS_READ_ONLY_NAMES.has(lastSegment(node.pattern))) return true;
 
+    // A declared property this type's source cannot see (#1269). With nothing
+    // live to stand against it would report `value -> <absent>` on every clean
+    // apply — a blind spot rendered as drift. Counterpart-gated the other way
+    // round: a live tree that does carry the field is still compared.
+    if (
+      node.side === "declared" &&
+      node.counterpart === "absent" &&
+      AWS_DEEP_BLIND_SPOTS[node.entityType]?.has(node.pattern)
+    ) {
+      return true;
+    }
+
     // Provider defaults, on the live side only, and only where source is silent
     // about the property. `"unknown"` (a one-sided normalization) never prunes:
     // the reader must not decide this before the declared tree is in hand.
@@ -606,9 +700,119 @@ export async function observeResourcesDeepAws(
     };
   });
 
+  // The out-of-band pass (#1015): under each declared parent whose type names
+  // child sources, list what actually exists and keep what nothing declared.
+  // A parent `--owned` withheld keeps its children out too — reporting a
+  // foreign resource's children while withholding the resource itself would
+  // be the filter half-applied. A parent with no deep reader of its own
+  // (`unsupported-kind`) still gets its children enumerated: listing under it
+  // needs only the physical id the stack already resolved.
+  const parents: Array<{ resource: StackResource; sources: readonly DeepChildSource[] }> = [];
+  for (const entityName of options.entityNames) {
+    const resource = byLogicalId.get(entityName);
+    const sources = resource ? DEEP_CHILD_SOURCES[resource.type] : undefined;
+    if (!resource?.physicalId || !sources) continue;
+    if (unobserved[entityName]?.reason === "filtered") continue;
+    parents.push({ resource, sources });
+  }
+  const children = await enumerateOutOfBandChildren({
+    parents,
+    allStackResources: stackResources,
+    entities: options.entities,
+    client,
+    normalize: (childType, properties) =>
+      normalizeDeepProperties(properties, {
+        entityType: childType,
+        side: "live",
+        hooks: awsDeepNormalizationHooks,
+      }),
+    concurrently: boundedConcurrently,
+  });
+  for (const [name, child] of Object.entries(children)) {
+    if (!resources[name]) resources[name] = child;
+  }
+
   return deepObservation(resources, unobserved);
 }
 
+/**
+ * List every child-sourced type under its declared parents and return the
+ * resources nothing declared, named by {@link outOfBandChildName}.
+ *
+ * "Declared" is answered three ways, in order of how directly the stack says
+ * it: the child identifier is some stack resource's physical id (the normal
+ * case — a declared `AWS::SNS::Subscription` deploys under its ARN); a
+ * `declaredVia` legacy form's physical id is the identifier's relevant part;
+ * or a declared entity's props spell the identifier (`declaredIdentifier`,
+ * the carve case — declared in source, not yet in any stack).
+ *
+ * A listing that fails is silence about that parent's children, never a
+ * finding and never a hole: there is no declared entity to hang a hole on,
+ * and fabricating one would put an undeclared name in the unobserved report.
+ * `UnsupportedOperation` — an emulator without parent-scoped listing — lands
+ * here too, which is what keeps the Floci lanes quiet.
+ */
+async function enumerateOutOfBandChildren(args: {
+  parents: Array<{ resource: StackResource; sources: readonly DeepChildSource[] }>;
+  allStackResources: StackResource[];
+  entities?: Map<string, { entityType: string; props: Record<string, unknown> }>;
+  client: AwsReadClientOptions;
+  normalize: (childType: string, properties: Record<string, unknown>) => Record<string, unknown>;
+  concurrently: <T>(items: T[], fn: (item: T) => Promise<void>) => Promise<unknown>;
+}): Promise<Record<string, DeepResourceObservation>> {
+  const out: Record<string, DeepResourceObservation> = {};
+  if (args.parents.length === 0) return out;
+
+  // Physical ids by type, over the WHOLE stack — a stack resource that is not
+  // a declared chant entity (a nested stack's row, a resource another tool
+  // added to the same stack) is still stack-managed, not out-of-band.
+  const addTo = (map: Map<string, Set<string>>, key: string, value: string) => {
+    const set = map.get(key) ?? new Set<string>();
+    set.add(value);
+    map.set(key, set);
+  };
+  const stackIdsByType = new Map<string, Set<string>>();
+  for (const r of args.allStackResources) {
+    if (r.physicalId) addTo(stackIdsByType, r.type, r.physicalId);
+  }
+  const declaredIdsByType = new Map<string, Set<string>>();
+  for (const entity of args.entities?.values() ?? []) {
+    const id = declaredIdentifier(entity.entityType, entity.props ?? {});
+    if (id) addTo(declaredIdsByType, entity.entityType, id);
+  }
+
+  const isDeclared = (source: DeepChildSource, identifier: string): boolean => {
+    if (stackIdsByType.get(source.childType)?.has(identifier)) return true;
+    if (declaredIdsByType.get(source.childType)?.has(identifier)) return true;
+    for (const via of source.declaredVia ?? []) {
+      const part = via.part(identifier);
+      if (part && stackIdsByType.get(via.type)?.has(part)) return true;
+    }
+    return false;
+  };
+
+  const listings = args.parents.flatMap(({ resource, sources }) =>
+    sources.map((source) => ({ physicalId: resource.physicalId as string, source })),
+  );
+  await args.concurrently(listings, async ({ physicalId, source }) => {
+    let listed;
+    try {
+      listed = await listResources(source.childType, args.client, source.model(physicalId));
+    } catch {
+      return;
+    }
+    for (const child of listed) {
+      if (!child.identifier || isDeclared(source, child.identifier)) continue;
+      out[outOfBandChildName(source.childType, child.identifier)] = {
+        type: source.childType,
+        physicalId: child.identifier,
+        properties: args.normalize(source.childType, child.properties),
+      };
+    }
+  });
+  return out;
+}
+
 /**
  * Read every `ec2`-sourced type in bulk, keyed by physical id.
  *