@intentius/chant-lexicon-aws 0.44.8 → 0.44.10

package/src/api/sigv4.test.ts

@@ -0,0 +1,260 @@
+/**
+ * SigV4 (#1686), checked against AWS's own published vectors.
+ *
+ * A signing implementation that is only tested against itself proves nothing —
+ * it will happily agree with its own mistake. Three of the fixtures below are
+ * values AWS publishes: the derived signing key from the documentation's
+ * "deriving the signing key" example, and the canonical request hash and
+ * signature of `get-vanilla` from the `aws-sig-v4-test-suite`. If a refactor
+ * breaks canonicalization, those three stop matching.
+ *
+ * Nothing here touches the network; there is nothing to touch. Signing is a
+ * pure function of the request and the clock.
+ */
+import { describe, test, expect } from "vitest";
+import { createHmac } from "node:crypto";
+import {
+  EMPTY_PAYLOAD_SHA256,
+  amzDate,
+  canonicalHeaders,
+  canonicalRequest,
+  resolveCredentials,
+  sha256Hex,
+  signRequest,
+  signingKey,
+  stringToSign,
+} from "./sigv4";
+
+/** The example secret AWS uses throughout its Signature Version 4 documentation. */
+const SECRET = "wJalrXUtnFEMI/K7MDENG+bPxRfiCYEXAMPLEKEY";
+const ACCESS_KEY = "AKIDEXAMPLE";
+
+describe("the published vectors", () => {
+  test("the signing key matches the documented derivation", () => {
+    // AWS, "Examples of how to derive a signing key for Signature Version 4":
+    // 20120215 / us-east-1 / iam.
+    expect(signingKey(SECRET, "20120215", "us-east-1", "iam").toString("hex")).toBe(
+      "f4780e2d9f65fa895f9c67b32ce1baf0b0d8a43505a000a1a9e090d414db404d",
+    );
+  });
+
+  test("get-vanilla canonicalizes and signs exactly as the test suite says", () => {
+    const { canonical, signed } = canonicalRequest(
+      "GET",
+      new URL("https://example.amazonaws.com/"),
+      { host: "example.amazonaws.com", "x-amz-date": "20150830T123600Z" },
+      EMPTY_PAYLOAD_SHA256,
+    );
+
+    expect(canonical).toBe(
+      [
+        "GET",
+        "/",
+        "",
+        "host:example.amazonaws.com",
+        "x-amz-date:20150830T123600Z",
+        "",
+        "host;x-amz-date",
+        EMPTY_PAYLOAD_SHA256,
+      ].join("\n"),
+    );
+    expect(signed).toBe("host;x-amz-date");
+
+    const scope = "20150830/us-east-1/service/aws4_request";
+    const sts = stringToSign("20150830T123600Z", scope, canonical);
+    expect(sts).toBe(
+      "AWS4-HMAC-SHA256\n20150830T123600Z\n" +
+        `${scope}\nbb579772317eb040ac9ed261061d46c1f17a8133879d6129b6e1c25292927e63`,
+    );
+
+    const key = signingKey(SECRET, "20150830", "us-east-1", "service");
+    expect(createHmac("sha256", key).update(sts, "utf8").digest("hex")).toBe(
+      "5fa00fa31553b73ebf1942676e86291e8372ff2a2260956d9b8aae1d763fbf31",
+    );
+  });
+
+  test("the empty-payload constant is what SHA-256 of nothing actually is", () => {
+    expect(sha256Hex("")).toBe(EMPTY_PAYLOAD_SHA256);
+  });
+});
+
+describe("header canonicalization", () => {
+  test("names lowercase and sort, values trim and collapse inner runs", () => {
+    expect(
+      canonicalHeaders({
+        "X-Amz-Date": "20150830T123600Z",
+        "Content-Type": "  application/json  ",
+        Host: "example.amazonaws.com",
+        "My-Header": "a   b\tc",
+      }),
+    ).toEqual({
+      canonical:
+        "content-type:application/json\nhost:example.amazonaws.com\n" +
+        "my-header:a b c\nx-amz-date:20150830T123600Z\n",
+      signed: "content-type;host;my-header;x-amz-date",
+    });
+  });
+
+  test("sorting is by byte, so an uppercase name still sorts by its lowercase form", () => {
+    expect(canonicalHeaders({ Zeta: "1", alpha: "2", MIDDLE: "3" }).signed).toBe("alpha;middle;zeta");
+  });
+
+  test("the unsignable headers are left out — signing what a proxy rewrites is an intermittent 403", () => {
+    const { signed } = canonicalHeaders({
+      authorization: "stale",
+      "user-agent": "chant",
+      "x-amzn-trace-id": "Root=1-x",
+      connection: "keep-alive",
+      expect: "100-continue",
+      host: "example.amazonaws.com",
+    });
+    expect(signed).toBe("host");
+  });
+
+  test("a bodyless request hashes to the empty-payload constant, not to a hash of nothing-in-particular", () => {
+    const headers = signRequest({
+      method: "POST",
+      url: "https://cloudformation.us-east-1.amazonaws.com/",
+      headers: {},
+      body: "",
+      service: "cloudformation",
+      region: "us-east-1",
+      credentials: { accessKeyId: ACCESS_KEY, secretAccessKey: SECRET },
+      now: new Date("2015-08-30T12:36:00Z"),
+    });
+    expect(headers["x-amz-content-sha256"]).toBe(EMPTY_PAYLOAD_SHA256);
+  });
+
+  test("the query string sorts by name then value, RFC 3986 encoded", () => {
+    const { canonical } = canonicalRequest(
+      "GET",
+      new URL("https://example.amazonaws.com/?b=2&a=z&a=a&c=hi%20there*"),
+      { host: "example.amazonaws.com" },
+      EMPTY_PAYLOAD_SHA256,
+    );
+    expect(canonical.split("\n")[2]).toBe("a=a&a=z&b=2&c=hi%20there%2A");
+  });
+
+  test("amzDate is ISO-8601 basic, which is what X-Amz-Date wants", () => {
+    expect(amzDate(new Date("2015-08-30T12:36:00.123Z"))).toBe("20150830T123600Z");
+  });
+});
+
+describe("signRequest", () => {
+  const credentials = { accessKeyId: ACCESS_KEY, secretAccessKey: SECRET };
+  const now = new Date("2015-08-30T12:36:00Z");
+
+  test("adds its own headers, keeps the caller's, and never emits host", () => {
+    const headers = signRequest({
+      method: "POST",
+      url: "https://cloudformation.us-west-2.amazonaws.com/",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body: "Action=DescribeStacks",
+      service: "cloudformation",
+      region: "us-west-2",
+      credentials,
+      now,
+    });
+
+    expect(headers["content-type"]).toBe("application/x-www-form-urlencoded");
+    expect(headers["x-amz-date"]).toBe("20150830T123600Z");
+    expect(headers["x-amz-content-sha256"]).toBe(sha256Hex("Action=DescribeStacks"));
+    expect(headers.host).toBeUndefined();
+    // A fixed clock makes the whole header a fixture; the primitives it is
+    // composed from are the ones checked against AWS's vectors above.
+    expect(headers.authorization).toBe(
+      "AWS4-HMAC-SHA256 Credential=AKIDEXAMPLE/20150830/us-west-2/cloudformation/aws4_request, " +
+        "SignedHeaders=content-type;host;x-amz-content-sha256;x-amz-date, " +
+        "Signature=3160e6fcf0cce7e8ff03c128e5e2bb6572ca59e843d3a88c26e45203288fc462",
+    );
+  });
+
+  test("host is signed even though it is not emitted — a different host is a different signature", () => {
+    const request = {
+      method: "POST",
+      headers: {},
+      body: "",
+      service: "cloudformation",
+      region: "us-east-1",
+      credentials,
+      now,
+    } as const;
+    const one = signRequest({ ...request, url: "https://cloudformation.us-east-1.amazonaws.com/" });
+    const other = signRequest({ ...request, url: "https://cloudformation.us-east-2.amazonaws.com/" });
+    expect(one.authorization).not.toBe(other.authorization);
+    expect(one.authorization).toContain("SignedHeaders=host;x-amz-content-sha256;x-amz-date");
+  });
+
+  test("a session token is both sent and signed", () => {
+    const headers = signRequest({
+      method: "POST",
+      url: "https://cloudcontrolapi.us-east-1.amazonaws.com/",
+      headers: {},
+      body: "{}",
+      service: "cloudcontrolapi",
+      region: "us-east-1",
+      credentials: { ...credentials, sessionToken: "FwoGZXIvYXdzEXAMPLE" },
+      now,
+    });
+    expect(headers["x-amz-security-token"]).toBe("FwoGZXIvYXdzEXAMPLE");
+    expect(headers.authorization).toContain("x-amz-security-token");
+  });
+
+  test("the same request at a different second is a different signature", () => {
+    const request = {
+      method: "POST",
+      url: "https://cloudformation.us-east-1.amazonaws.com/",
+      headers: {},
+      body: "",
+      service: "cloudformation",
+      region: "us-east-1",
+      credentials,
+    } as const;
+    expect(signRequest({ ...request, now }).authorization).not.toBe(
+      signRequest({ ...request, now: new Date("2015-08-30T12:36:01Z") }).authorization,
+    );
+  });
+});
+
+describe("credential resolution", () => {
+  const env = { AWS_ACCESS_KEY_ID: "AKIDENV", AWS_SECRET_ACCESS_KEY: "envsecret", AWS_SESSION_TOKEN: "envtoken" };
+
+  test("explicit credentials beat the environment", () => {
+    expect(resolveCredentials({ accessKeyId: "AKIDEXPLICIT", secretAccessKey: "s" }, env)).toEqual({
+      accessKeyId: "AKIDEXPLICIT",
+      secretAccessKey: "s",
+    });
+  });
+
+  test("the environment answers when nothing was passed, session token included", () => {
+    expect(resolveCredentials(undefined, env)).toEqual({
+      accessKeyId: "AKIDENV",
+      secretAccessKey: "envsecret",
+      sessionToken: "envtoken",
+    });
+  });
+
+  test("no session token in the environment means no session token in the result", () => {
+    expect(resolveCredentials(undefined, { AWS_ACCESS_KEY_ID: "a", AWS_SECRET_ACCESS_KEY: "b" })).toEqual({
+      accessKeyId: "a",
+      secretAccessKey: "b",
+    });
+  });
+
+  test("a half-set environment is absent, not a signature that cannot verify", () => {
+    expect(resolveCredentials(undefined, { AWS_ACCESS_KEY_ID: "a" })).toBeUndefined();
+    expect(resolveCredentials(undefined, { AWS_SECRET_ACCESS_KEY: "b" })).toBeUndefined();
+  });
+
+  test("an empty environment is absent", () => {
+    expect(resolveCredentials(undefined, {})).toBeUndefined();
+  });
+
+  test("a resolver decides, and its refusal is not overruled by the environment", () => {
+    expect(resolveCredentials(() => ({ accessKeyId: "AKIDRESOLVED", secretAccessKey: "s" }), env)).toEqual({
+      accessKeyId: "AKIDRESOLVED",
+      secretAccessKey: "s",
+    });
+    expect(resolveCredentials(() => undefined, env)).toBeUndefined();
+  });
+});

package/src/api/sigv4.ts

@@ -0,0 +1,243 @@
+/**
+ * AWS Signature Version 4, for the shared read transport (#1686).
+ *
+ * Two modules asked for this by name before it existed: `./read-client.ts` and
+ * cedar's `lexicons/cedar/src/avp/client.ts` both send a placeholder
+ * `Signature=unsigned` `Authorization` header that carries a credential scope
+ * and nothing else, and both say in prose that the real thing belongs here
+ * once rather than twice. Nothing else in the repo signs an AWS request — the
+ * appliers (`op/activities/aws-apply.ts`) are unsigned too, which is why the
+ * native paths have been emulator-scoped.
+ *
+ * ## No dependency
+ *
+ * SigV4 is four HMACs and two SHA-256s. `node:crypto` has both, so signing
+ * costs nothing in the dependency tree — which matters here, because the whole
+ * reason these transports are hand-written is to keep `@aws-sdk/*` and its
+ * thirty-odd transitive packages out of a lexicon.
+ *
+ * ## What is signed, and what is not
+ *
+ * Header signing only. Query-string (presigned-URL) signing has no caller: the
+ * read paths POST to a service endpoint, they do not hand out URLs.
+ *
+ * `host` is signed but never emitted. `fetch` computes `Host` from the URL and
+ * forbids overriding it, so the signer derives the same value from the URL it
+ * was given. A transport that rewrites the URL underneath the signer — a proxy
+ * that keeps the original `Host`, say — would invalidate the signature; the
+ * injectable-HTTP seam is for tests and emulators, not for URL rewriting.
+ */
+import { createHash, createHmac } from "node:crypto";
+
+const ALGORITHM = "AWS4-HMAC-SHA256";
+const TERMINATOR = "aws4_request";
+
+/** SHA-256 of the empty string — the payload hash of every bodyless request. */
+export const EMPTY_PAYLOAD_SHA256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
+
+/**
+ * Headers that must not be signed even when a caller sets them: `authorization`
+ * is the output, and the others are rewritten in transit by proxies and agents,
+ * so signing them produces intermittent 403s rather than security.
+ */
+const UNSIGNABLE = new Set(["authorization", "connection", "expect", "user-agent", "x-amzn-trace-id"]);
+
+/** A resolved credential set. `sessionToken` is present for STS/role credentials. */
+export interface AwsCredentials {
+  accessKeyId: string;
+  secretAccessKey: string;
+  sessionToken?: string;
+}
+
+/**
+ * The credential injection seam: a function the caller supplies to decide, by
+ * whatever means it likes, what to sign with. Returning `undefined` means "this
+ * process has no credentials" and is respected as an answer, not overridden.
+ */
+export type AwsCredentialResolver = () => AwsCredentials | undefined;
+
+/** Either literal credentials or a resolver for them. */
+export type AwsCredentialSource = AwsCredentials | AwsCredentialResolver;
+
+/**
+ * Credentials for a request: explicit → environment → absent.
+ *
+ * A resolver function is authoritative — if one is injected and it declines,
+ * the environment is not consulted behind its back, because the point of
+ * injecting one is to control the answer. Literal credentials are likewise
+ * final. Only the no-source case falls through to `AWS_ACCESS_KEY_ID` /
+ * `AWS_SECRET_ACCESS_KEY` (plus `AWS_SESSION_TOKEN` when set), and a half-set
+ * environment — a key id with no secret — is absent rather than a signature
+ * that cannot verify.
+ *
+ * Deliberately not implemented: the profile file, IMDS, and the container
+ * credential endpoints. Each is a separate transport with its own failure and
+ * caching story; a caller that has those can resolve them itself and pass the
+ * result in, which is what the resolver seam is for.
+ */
+export function resolveCredentials(
+  source?: AwsCredentialSource,
+  env: Record<string, string | undefined> = process.env,
+): AwsCredentials | undefined {
+  if (typeof source === "function") return source();
+  if (source) return source;
+  const accessKeyId = env.AWS_ACCESS_KEY_ID;
+  const secretAccessKey = env.AWS_SECRET_ACCESS_KEY;
+  if (!accessKeyId || !secretAccessKey) return undefined;
+  return {
+    accessKeyId,
+    secretAccessKey,
+    ...(env.AWS_SESSION_TOKEN ? { sessionToken: env.AWS_SESSION_TOKEN } : {}),
+  };
+}
+
+/** One request to sign. `headers` are the caller's; the signer adds its own. */
+export interface SigV4Request {
+  method: string;
+  /** Absolute URL. Its host is signed and its path/query are canonicalized. */
+  url: string;
+  headers: Record<string, string>;
+  body: string;
+  /** Service name as it appears in the credential scope (`cloudformation`, `cloudcontrolapi`, …). */
+  service: string;
+  region: string;
+  credentials: AwsCredentials;
+  /** Signing clock. Injected by tests; otherwise now. */
+  now?: Date;
+}
+
+/** `YYYYMMDDTHHMMSSZ` — the `X-Amz-Date` format, which is ISO-8601 basic. */
+export function amzDate(date: Date): string {
+  return date.toISOString().replace(/[:-]|\.\d{3}/g, "");
+}
+
+/** Lowercase hex SHA-256. */
+export function sha256Hex(payload: string): string {
+  return createHash("sha256").update(payload, "utf8").digest("hex");
+}
+
+function hmac(key: Buffer | string, data: string): Buffer {
+  return createHmac("sha256", key).update(data, "utf8").digest();
+}
+
+/**
+ * The signing key: four chained HMACs from the secret, so the key on the wire
+ * is scoped to one day, one region and one service rather than being the
+ * account secret itself.
+ */
+export function signingKey(secretAccessKey: string, day: string, region: string, service: string): Buffer {
+  const dateKey = hmac(`AWS4${secretAccessKey}`, day);
+  const regionKey = hmac(dateKey, region);
+  const serviceKey = hmac(regionKey, service);
+  return hmac(serviceKey, TERMINATOR);
+}
+
+/**
+ * RFC 3986 percent-encoding. `encodeURIComponent` leaves `!'()*` alone and AWS
+ * does not, which is the difference between a signature that verifies and one
+ * that does not for any path or parameter containing them.
+ */
+function encodeRfc3986(value: string): string {
+  return encodeURIComponent(value).replace(
+    /[!'()*]/g,
+    (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`,
+  );
+}
+
+/**
+ * The canonical path.
+ *
+ * Every caller of this module POSTs to `/`, so the one place implementations
+ * genuinely diverge — S3 signs the path once-encoded, every other service signs
+ * it twice-encoded — never arises. Segments are encoded once; a future caller
+ * with a real path on a non-S3 service is the moment to revisit that.
+ */
+function canonicalPath(pathname: string): string {
+  if (!pathname || pathname === "/") return "/";
+  return pathname.split("/").map(encodeRfc3986).join("/");
+}
+
+/** Query parameters sorted by name, then by value, each side encoded. */
+function canonicalQuery(search: URLSearchParams): string {
+  const pairs: Array<[string, string]> = [];
+  search.forEach((value, name) => pairs.push([encodeRfc3986(name), encodeRfc3986(value)]));
+  pairs.sort((a, b) => (a[0] === b[0] ? (a[1] < b[1] ? -1 : a[1] > b[1] ? 1 : 0) : a[0] < b[0] ? -1 : 1));
+  return pairs.map(([name, value]) => `${name}=${value}`).join("&");
+}
+
+/**
+ * Header names lowercased, values trimmed with internal whitespace runs
+ * collapsed, sorted by name. Returns the canonical block and the `;`-joined
+ * signed-header list that has to agree with it exactly.
+ */
+export function canonicalHeaders(headers: Record<string, string>): { canonical: string; signed: string } {
+  const entries = Object.entries(headers)
+    .map(([name, value]) => [name.toLowerCase().trim(), value.trim().replace(/\s+/g, " ")] as const)
+    .filter(([name]) => !UNSIGNABLE.has(name))
+    .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+  return {
+    canonical: entries.map(([name, value]) => `${name}:${value}\n`).join(""),
+    signed: entries.map(([name]) => name).join(";"),
+  };
+}
+
+/** The canonical request, verbatim as it is hashed into the string to sign. */
+export function canonicalRequest(
+  method: string,
+  url: URL,
+  headers: Record<string, string>,
+  payloadHash: string,
+): { canonical: string; signed: string } {
+  const { canonical: headerBlock, signed } = canonicalHeaders(headers);
+  return {
+    canonical: [
+      method.toUpperCase(),
+      canonicalPath(url.pathname),
+      canonicalQuery(url.searchParams),
+      headerBlock,
+      signed,
+      payloadHash,
+    ].join("\n"),
+    signed,
+  };
+}
+
+/** The string to sign: algorithm, timestamp, scope, hashed canonical request. */
+export function stringToSign(timestamp: string, scope: string, canonical: string): string {
+  return [ALGORITHM, timestamp, scope, sha256Hex(canonical)].join("\n");
+}
+
+/**
+ * The caller's headers plus everything SigV4 adds: `x-amz-date`,
+ * `x-amz-content-sha256`, `x-amz-security-token` when the credentials are
+ * temporary, and the `Authorization` header itself.
+ *
+ * `host` is signed (AWS requires it) but not returned — see the module header.
+ */
+export function signRequest(request: SigV4Request): Record<string, string> {
+  const url = new URL(request.url);
+  const timestamp = amzDate(request.now ?? new Date());
+  const day = timestamp.slice(0, 8);
+  const payloadHash = request.body.length === 0 ? EMPTY_PAYLOAD_SHA256 : sha256Hex(request.body);
+
+  const signable: Record<string, string> = {
+    ...request.headers,
+    host: url.host,
+    "x-amz-date": timestamp,
+    "x-amz-content-sha256": payloadHash,
+    ...(request.credentials.sessionToken ? { "x-amz-security-token": request.credentials.sessionToken } : {}),
+  };
+
+  const { canonical, signed } = canonicalRequest(request.method, url, signable, payloadHash);
+  const scope = `${day}/${request.region}/${request.service}/${TERMINATOR}`;
+  const key = signingKey(request.credentials.secretAccessKey, day, request.region, request.service);
+  const signature = hmac(key, stringToSign(timestamp, scope, canonical)).toString("hex");
+
+  const { host: _host, ...emitted } = signable;
+  return {
+    ...emitted,
+    authorization:
+      `${ALGORITHM} Credential=${request.credentials.accessKeyId}/${scope}, ` +
+      `SignedHeaders=${signed}, Signature=${signature}`,
+  };
+}

package/src/identity-observe.test.ts

@@ -0,0 +1,104 @@
+/**
+ * The identity fallback (#1647) — unit half. The carve state in miniature: a
+ * declared Bucket absent from every stack, present live, named precisely by
+ * its own `BucketName`. The Cloud Control edge is the injected `http` seam
+ * `read-client` already exposes.
+ */
+import { describe, test, expect } from "vitest";
+import { declaredIdentifier, observeByIdentity } from "./identity-observe";
+
+const entity = (entityType: string, props: Record<string, unknown>) => ({ entityType, props });
+
+describe("declaredIdentifier (#1647)", () => {
+  test("a scalar primary identifier reads straight off the props", () => {
+    expect(declaredIdentifier("AWS::S3::Bucket", { BucketName: "acme-platform-assets-prod" })).toBe(
+      "acme-platform-assets-prod",
+    );
+  });
+
+  test("absent, empty, or non-scalar identifier parts refuse — a Ref is not an identity", () => {
+    expect(declaredIdentifier("AWS::S3::Bucket", {})).toBeUndefined();
+    expect(declaredIdentifier("AWS::S3::Bucket", { BucketName: "" })).toBeUndefined();
+    expect(declaredIdentifier("AWS::S3::Bucket", { BucketName: { Ref: "Other" } })).toBeUndefined();
+  });
+
+  test("an unknown type has no identifier to spell", () => {
+    expect(declaredIdentifier("AWS::Made::Up", { Name: "x" })).toBeUndefined();
+  });
+});
+
+/** A Cloud Control `GetResource` answer, double-encoded the way the API is. */
+const ccFound = (identifier: string, properties: Record<string, unknown>) => ({
+  status: 200,
+  text: JSON.stringify({
+    ResourceDescription: { Identifier: identifier, Properties: JSON.stringify(properties) },
+  }),
+});
+
+const ccError = (type: string, message: string) => ({
+  status: 400,
+  text: JSON.stringify({ __type: type, message }),
+});
+
+describe("observeByIdentity (#1647)", () => {
+  const bucket = new Map([["assets", entity("AWS::S3::Bucket", { BucketName: "acme-platform-assets-prod" })]]);
+
+  test("a live identifier-named resource reads OBSERVED — external, foreign, never absent", async () => {
+    const calls: Array<{ url: string; body: string }> = [];
+    const { resources, queried } = await observeByIdentity(["assets"], bucket, {}, {
+      http: async (url, init) => {
+        calls.push({ url, body: init.body });
+        return ccFound("acme-platform-assets-prod", { BucketName: "acme-platform-assets-prod", SecretToken: "s3cr3t" });
+      },
+    });
+    expect(calls).toHaveLength(1);
+    expect(calls[0].url).toContain("cloudcontrol");
+    expect(resources.assets).toMatchObject({
+      type: "AWS::S3::Bucket",
+      physicalId: "acme-platform-assets-prod",
+      status: "EXTERNAL",
+      ownership: "foreign",
+    });
+    // Live properties ride along, sensitive keys scrubbed like stack outputs.
+    expect(resources.assets.attributes).toMatchObject({ BucketName: "acme-platform-assets-prod", SecretToken: "[REDACTED]" });
+    // #1620: the attempted address is on the wire whatever the verdict.
+    expect(queried.assets).toContain("AWS::S3::Bucket");
+    expect(queried.assets).toContain("acme-platform-assets-prod");
+  });
+
+  test("a genuine miss keeps the stack's absent verdict, with the address still recorded", async () => {
+    const { resources, queried } = await observeByIdentity(["assets"], bucket, {}, {
+      http: async () => ccError("ResourceNotFoundException", "no such bucket"),
+    });
+    expect(resources.assets).toBeUndefined();
+    expect(queried.assets).toBeDefined();
+  });
+
+  test("an emulator without Cloud Control keeps the absent verdict — never a hole, or pre-first-apply plans stop proposing create", async () => {
+    const { resources } = await observeByIdentity(["assets"], bucket, {}, {
+      http: async () => ccError("UnsupportedOperation", "Operation GetResource is not supported."),
+    });
+    expect(resources.assets).toBeUndefined();
+  });
+
+  test("entities the stack already answered for are never re-read", async () => {
+    let called = 0;
+    const already = { assets: { type: "AWS::S3::Bucket", physicalId: "b", status: "CREATE_COMPLETE" } };
+    const { resources } = await observeByIdentity(["assets"], bucket, already, {
+      http: async () => ((called += 1), ccFound("x", {})),
+    });
+    expect(called).toBe(0);
+    expect(resources).toEqual({});
+  });
+
+  test("entities with no spellable identifier are skipped without a call", async () => {
+    let called = 0;
+    const anonymous = new Map([["q", entity("AWS::SQS::Queue", {})]]);
+    const { resources, queried } = await observeByIdentity(["q"], anonymous, {}, {
+      http: async () => ((called += 1), ccFound("x", {})),
+    });
+    expect(called).toBe(0);
+    expect(resources).toEqual({});
+    expect(queried).toEqual({});
+  });
+});