@intentius/chant-lexicon-aws 0.44.8 → 0.44.10

package/src/identity-observe.ts

@@ -0,0 +1,114 @@
+/**
+ * The identity fallback on the stack read (#1647).
+ *
+ * `describeResources` asks CloudFormation exactly one question — is there a
+ * logical id named <entity> in this stack? — which reads a freshly
+ * carve-emitted, still-Terraform-owned resource as confirmed-absent even
+ * though the declared `BucketName` names it precisely. When a declared entity
+ * is absent from the stack AND its props spell the type's full primary
+ * identifier (the spec knowledge the codegen already compiled into
+ * `lexicon-aws.json`), ask Cloud Control for it by identity. Found means
+ * OBSERVED: `ownership: "foreign"` (it exists and something other than this
+ * stack owns it — Terraform, a console hand, another tool) and
+ * `status: "EXTERNAL"` (live outside the stack, deliberately not a
+ * CloudFormation status word).
+ *
+ * Best-effort ON TOP of a stack answer, never instead of one: a genuine miss
+ * (`ResourceNotFoundException`) keeps the stack's absent verdict, and so does
+ * every other refusal (`UnsupportedOperation` — a Floci without Cloud
+ * Control — credentials, throttling). The stack read succeeded; absence at
+ * stack scope is an honest verdict this fallback can refine but must never
+ * degrade into a hole, or a pre-first-apply plan would stop proposing
+ * `create` the moment the emulator lacks Cloud Control.
+ */
+import { createRequire } from "module";
+import { getResource, type AwsReadClientOptions } from "./api/read-client";
+import type { ResourceMetadata } from "@intentius/chant/lexicon";
+
+const require = createRequire(import.meta.url);
+
+interface LexiconEntry {
+  resourceType: string;
+  kind: string;
+  primaryIdentifier?: string[];
+}
+
+let byResourceType: Map<string, LexiconEntry> | undefined;
+function manifestByType(): Map<string, LexiconEntry> {
+  if (!byResourceType) {
+    const manifest = require("./generated/lexicon-aws.json") as Record<string, LexiconEntry>;
+    byResourceType = new Map(Object.values(manifest).map((e) => [e.resourceType, e]));
+  }
+  return byResourceType;
+}
+
+/**
+ * The Cloud Control identifier the declared props spell, or undefined when the
+ * type has no primary identifier on record or any part of it is absent or
+ * non-scalar (a Ref, an intrinsic, a server-assigned name). Multi-part
+ * identifiers join with `|`, Cloud Control's own separator.
+ */
+export function declaredIdentifier(entityType: string, props: Record<string, unknown>): string | undefined {
+  const entry = manifestByType().get(entityType);
+  const parts = entry?.primaryIdentifier;
+  if (!entry || entry.kind !== "resource" || !parts || parts.length === 0) return undefined;
+  const values: string[] = [];
+  for (const part of parts) {
+    const v = props[part];
+    if (typeof v !== "string" && typeof v !== "number") return undefined;
+    const s = String(v);
+    if (!s) return undefined;
+    values.push(s);
+  }
+  return values.join("|");
+}
+
+/** The same scrub the stack-output path applies, on live property KEYS. */
+function redactSensitive(properties: Record<string, unknown>): Record<string, unknown> | undefined {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(properties)) {
+    out[key] = /password|secret|token/i.test(key) ? "[REDACTED]" : value;
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+/**
+ * Identity-read every entity the stack did not answer for and whose props
+ * spell an identifier. `already` is the stack's answer — an entity the stack
+ * DID return is never re-read. The `queried` map records the address each
+ * attempted read was issued against (#1620), whatever the verdict.
+ */
+export async function observeByIdentity(
+  entityNames: string[],
+  entities: Map<string, { entityType: string; props: Record<string, unknown> }> | undefined,
+  already: Record<string, ResourceMetadata>,
+  client: AwsReadClientOptions,
+): Promise<{ resources: Record<string, ResourceMetadata>; queried: Record<string, string> }> {
+  const resources: Record<string, ResourceMetadata> = {};
+  const queried: Record<string, string> = {};
+  if (!entities) return { resources, queried };
+  for (const name of entityNames) {
+    if (already[name]) continue;
+    const entity = entities.get(name);
+    if (!entity) continue;
+    const identifier = declaredIdentifier(entity.entityType, entity.props ?? {});
+    if (!identifier) continue;
+    queried[name] = `cloudcontrol:GetResource:${entity.entityType}:${identifier}`;
+    try {
+      const found = await getResource(entity.entityType, identifier, client);
+      if (!found) continue;
+      resources[name] = {
+        type: entity.entityType,
+        physicalId: found.identifier || identifier,
+        status: "EXTERNAL",
+        ownership: "foreign",
+        ...(redactSensitive(found.properties) ? { attributes: redactSensitive(found.properties) } : {}),
+      };
+    } catch {
+      // Refusals of every kind keep the stack's verdict — see the module
+      // comment for why a failed refinement must not become a hole.
+      continue;
+    }
+  }
+  return { resources, queried };
+}

package/src/index.ts

@@ -52,8 +52,21 @@ export {
   type AwsReadClientOptions,
   type CloudControlDescription,
   type StackResource,
+  type AwsCredentials,
+  type AwsCredentialResolver,
+  type AwsCredentialSource,
 } from "./api/read-client";
 
+// SigV4 (#1686). Exported as its own surface because it is deliberately not
+// specific to this transport: cedar's AVP client is the next caller, and the
+// point of the module is that there is one signer rather than one per lexicon.
+export {
+  signRequest,
+  resolveCredentials,
+  EMPTY_PAYLOAD_SHA256,
+  type SigV4Request,
+} from "./api/sigv4";
+
 // Intrinsics
 export {
   Sub,

package/src/lifecycle-integration.test.ts

@@ -143,6 +143,75 @@ describe("aws lifecycle integration (#163)", () => {
     expect(cs2.entries.find((e) => e.name === "MyBucket")!.action).toBe("noop");
   });
 
+  // #1647 — the carve state, end to end: terraform applied the bucket, carve
+  // emitted a carveout declaring it by BucketName, and no CFN stack has ever
+  // heard of it. The stack read alone said confirmed-absent (missing → a plan
+  // proposing create for a bucket that EXISTS); the identity fallback asks
+  // Cloud Control by the declared identifier and the verdict comes back
+  // observed.
+  test("identity fallback: a declared, stack-absent, live resource reads observed, not missing (#1647)", async () => {
+    const routeBoth = (cc: { status?: number; text: string }): void => {
+      vi.spyOn(globalThis, "fetch").mockImplementation((async (url: string, init: { body: string; headers?: Record<string, string> }) => {
+        const target = init.headers?.["x-amz-target"] ?? "";
+        if (target.endsWith("GetResource")) return { status: cc.status ?? 200, text: () => Promise.resolve(cc.text) };
+        const action = new URLSearchParams(init.body).get("Action") ?? "";
+        return {
+          status: 200,
+          text: () => Promise.resolve(action === "DescribeStackResources" ? stackResourcesXml([]) : stackOutputsXml()),
+        };
+      }) as unknown as typeof fetch);
+    };
+
+    const entities = new Map([
+      ["assets", { entityType: "AWS::S3::Bucket", props: { BucketName: "acme-platform-assets-prod" } }],
+    ]);
+
+    routeBoth({
+      text: JSON.stringify({
+        ResourceDescription: {
+          Identifier: "acme-platform-assets-prod",
+          Properties: JSON.stringify({ BucketName: "acme-platform-assets-prod" }),
+        },
+      }),
+    });
+    const observed = normalizeObservation(
+      await awsPlugin.describeResources!({
+        environment: "prod",
+        buildOutput: "",
+        entityNames: ["assets"],
+        entities,
+      }),
+    );
+    expect(observed.resources.assets).toMatchObject({
+      type: "AWS::S3::Bucket",
+      status: "EXTERNAL",
+      ownership: "foreign",
+    });
+    // #1620: the identity read's address rides the observation.
+    expect(observed.queried.assets).toContain("acme-platform-assets-prod");
+
+    // Through the change set: declared + live → noop, never create. `foreign`
+    // ownership never escalates anything (#120's rule holds).
+    const cs = buildChangeSet("prod", { declared: new Set(["assets"]), observedNow: observed.resources, observedThen: undefined });
+    expect(cs.entries.find((e) => e.name === "assets")!.action).toBe("noop");
+
+    // An emulator without Cloud Control keeps today's verdict exactly: absent,
+    // create proposed — the fallback must not turn pre-first-apply into a hole.
+    routeBoth({ status: 400, text: JSON.stringify({ __type: "UnsupportedOperation", message: "not supported" }) });
+    const degraded = normalizeObservation(
+      await awsPlugin.describeResources!({
+        environment: "prod",
+        buildOutput: "",
+        entityNames: ["assets"],
+        entities,
+      }),
+    );
+    expect(degraded.resources.assets).toBeUndefined();
+    expect(degraded.unobserved.assets).toBeUndefined();
+    const cs2 = buildChangeSet("prod", { declared: new Set(["assets"]), observedNow: degraded.resources, observedThen: undefined });
+    expect(cs2.entries.find((e) => e.name === "assets")!.action).toBe("create");
+  });
+
   describe("describeStackStatus (#57 — per-component stack presence)", () => {
     const err = (stderr: string) => ({ stdout: "", stderr, exitCode: 255 });
 

package/src/plugin.ts

@@ -548,6 +548,7 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
     environment: string;
     buildOutput: string;
     entityNames: string[];
+    entities?: Map<string, { entityType: string; props: Record<string, unknown> }>;
     stack?: string;
     region?: string;
     owned?: boolean;
@@ -592,9 +593,14 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
       // A stack that doesn't exist yet is the pre-first-apply state: nothing is
       // deployed for this env, so there are no live resources (every declared
       // resource is "pending") — not an error. That is a real absence, so the
-      // empty result is the honest one and `create` is the right proposal.
+      // empty result is the honest one and `create` is the right proposal —
+      // EXCEPT for an entity whose props spell its own physical identity
+      // (#1647): a freshly carve-emitted, still-Terraform-owned resource lives
+      // in no stack at all, and only an identity read can see it.
       if (err instanceof AwsReadError && stackDoesNotExist(err.message)) {
-        return observation(resources);
+        const { observeByIdentity } = await import("./identity-observe");
+        const identity = await observeByIdentity(options.entityNames, options.entities, resources, client);
+        return observation({ ...resources, ...identity.resources }, undefined, identity.queried);
       }
       // Any other failure (credentials, throttling, a region that can't be
       // reached) establishes nothing about what is deployed. Reporting every
@@ -655,6 +661,14 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
       };
     }
 
+    // The identity fallback (#1647): entities the stack did not answer for but
+    // whose declared props spell a full primary identifier get a Cloud Control
+    // read before "absent" stands. Computed against the stack's answer and
+    // merged at the return sites, so the own-property enrichment below neither
+    // re-describes nor un-observes what identity found.
+    const { observeByIdentity } = await import("./identity-observe");
+    const identity = await observeByIdentity(options.entityNames, options.entities, resources, client);
+
     // Each resource's OWN properties, on top of the stack outputs above (#1279).
     // Until this, a node's `attrs` were the stack's exports replicated onto
     // every member, so no instance carried its own `VpcId`.
@@ -687,13 +701,13 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
           detail: `the stack was read, but this resource's own properties were not — ${own.failures.get(type) ?? "the describe call failed"}`,
         };
       }
-      return observation(described, holes);
+      return observation({ ...described, ...identity.resources }, holes, identity.queried);
     }
 
     // Every entity the stack answered for was answered for: an entity the
     // template doesn't carry is genuinely not in this stack, which is an
-    // absence, not a hole.
-    return observation(withProperties);
+    // absence, not a hole — unless the identity fallback saw it live (#1647).
+    return observation({ ...withProperties, ...identity.resources }, undefined, identity.queried);
   },
 
   /**