@intentius/chant-lexicon-aws 0.124.23 → 0.124.25

package/src/caller-identity.test.ts

@@ -7,8 +7,9 @@
  * because a whoami that names a binding the read does not use is worse than no
  * whoami at all.
  */
+import { createHash } from "node:crypto";
 import { describe, test, expect } from "vitest";
-import { describeIdentity } from "./caller-identity";
+import { describeIdentity, type CallerIdentityOptions } from "./caller-identity";
 import { describeStackResources, type AwsReadHttp } from "./api/read-client";
 
 const CALLER_IDENTITY_XML = `
@@ -36,13 +37,24 @@ function recording(text: string, status = 200) {
   return { http, calls };
 }
 
+/**
+ * No shared config or credentials files: the chain must never read the real
+ * `~/.aws` of whoever runs the suite. Tests that exercise profiles inject
+ * their own files.
+ */
+const NO_FILES = { home: "/nonexistent-home", readFile: () => undefined };
+
+function whoami(options: CallerIdentityOptions) {
+  return describeIdentity({ ...options, chain: { ...NO_FILES, ...options.chain } });
+}
+
 /** Credentials that exist only in this record — never read from the process. */
 const CREDS = { AWS_ACCESS_KEY_ID: "AKIAEXAMPLEKEYID0000", AWS_SECRET_ACCESS_KEY: "notarealsecret" };
 
 describe("aws describeIdentity (#1982)", () => {
   test("reports the STS principal, the account+region scope, and where the binding came from", async () => {
     const { http, calls } = recording(CALLER_IDENTITY_XML);
-    const result = await describeIdentity({
+    const result = await whoami({
       environment: "prod",
       region: "eu-west-1",
       client: { http, env: CREDS },
@@ -63,31 +75,33 @@ describe("aws describeIdentity (#1982)", () => {
 
   test("no environment credentials against real AWS is no-credentials, and the call is never made", async () => {
     const { http, calls } = recording(CALLER_IDENTITY_XML);
-    const result = await describeIdentity({ environment: "prod", client: { http, env: {} } });
+    const result = await whoami({ environment: "prod", client: { http, env: {} } });
     expect(result).toEqual({
       unresolved: {
         reason: "no-credentials",
-        detail: "no AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY in the environment",
+        detail:
+          "no AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY in the environment, no AWS_PROFILE, and no default profile in /nonexistent-home/.aws/config or /nonexistent-home/.aws/credentials",
       },
     });
     expect(calls).toHaveLength(0);
   });
 
-  test("AWS_PROFILE alone is reported as no-credentials, naming the profile that does not sign", async () => {
-    const { http } = recording(CALLER_IDENTITY_XML);
-    const result = await describeIdentity({
+  test("an AWS_PROFILE that names no profile is no-credentials, naming the profile and the files read", async () => {
+    const { http, calls } = recording(CALLER_IDENTITY_XML);
+    const result = await whoami({
       environment: "prod",
       client: { http, env: { AWS_PROFILE: "acme-ci" } },
     });
     expect(result).toMatchObject({ unresolved: { reason: "no-credentials" } });
     const detail = (result as { unresolved: { detail: string } }).unresolved.detail;
     expect(detail).toContain("AWS_PROFILE=acme-ci");
-    expect(detail).toContain("not the profile file");
+    expect(detail).toContain("/nonexistent-home/.aws/config");
+    expect(calls).toHaveLength(0);
   });
 
   test("an unsigned emulator read still resolves an identity, and says it was unsigned", async () => {
     const { http, calls } = recording(CALLER_IDENTITY_XML);
-    const result = await describeIdentity({
+    const result = await whoami({
       environment: "floci",
       client: { http, env: { AWS_ENDPOINT_URL: "http://localhost:4566" } },
     });
@@ -106,21 +120,21 @@ describe("aws describeIdentity (#1982)", () => {
       403,
     );
     expect(
-      await describeIdentity({ environment: "prod", client: { http: denied.http, env: CREDS } }),
+      await whoami({ environment: "prod", client: { http: denied.http, env: CREDS } }),
     ).toMatchObject({ unresolved: { reason: "no-credentials" } });
 
     const broken = recording(
       "<ErrorResponse><Error><Code>ServiceUnavailable</Code><Message>try later</Message></Error></ErrorResponse>",
       503,
     );
-    const result = await describeIdentity({ environment: "prod", client: { http: broken.http, env: CREDS } });
+    const result = await whoami({ environment: "prod", client: { http: broken.http, env: CREDS } });
     expect(result).toMatchObject({ unresolved: { reason: "read-failed" } });
     expect((result as { unresolved: { detail: string } }).unresolved.detail).toContain("ServiceUnavailable");
   });
 
   test("an answer with no Arn is read-failed, never an empty identity", async () => {
     const { http } = recording("<GetCallerIdentityResponse><GetCallerIdentityResult/></GetCallerIdentityResponse>");
-    const result = await describeIdentity({ environment: "prod", client: { http, env: CREDS } });
+    const result = await whoami({ environment: "prod", client: { http, env: CREDS } });
     expect(result).toMatchObject({ unresolved: { reason: "read-failed" } });
   });
 
@@ -129,7 +143,7 @@ describe("aws describeIdentity (#1982)", () => {
     // to us-east-1; it does not consult AWS_REGION. Reporting the shell's var
     // here would describe a target no read uses.
     const { http, calls } = recording(CALLER_IDENTITY_XML);
-    const result = await describeIdentity({
+    const result = await whoami({
       environment: "prod",
       client: { http, env: { ...CREDS, AWS_REGION: "ap-south-1" } },
     });
@@ -140,7 +154,7 @@ describe("aws describeIdentity (#1982)", () => {
 
   test("no credential material appears anywhere in the reported row", async () => {
     const { http } = recording(CALLER_IDENTITY_XML);
-    const result = await describeIdentity({ environment: "prod", client: { http, env: CREDS } });
+    const result = await whoami({ environment: "prod", client: { http, env: CREDS } });
     const serialized = JSON.stringify(result);
     expect(serialized).not.toContain(CREDS.AWS_SECRET_ACCESS_KEY);
     expect(serialized).not.toContain(CREDS.AWS_ACCESS_KEY_ID);
@@ -152,7 +166,7 @@ describe("whoami and the live read resolve the same target (#1982 acceptance)",
     const env = { ...CREDS, AWS_ENDPOINT_URL: "http://localhost:4566" };
 
     const identityHttp = recording(CALLER_IDENTITY_XML);
-    const identity = await describeIdentity({
+    const identity = await whoami({
       environment: "floci",
       region: "eu-west-1",
       client: { http: identityHttp.http, env },
@@ -170,7 +184,7 @@ describe("whoami and the live read resolve the same target (#1982 acceptance)",
 
   test("against real AWS both resolve the same region, on each service's own host", async () => {
     const identityHttp = recording(CALLER_IDENTITY_XML);
-    await describeIdentity({
+    await whoami({
       environment: "prod",
       region: "eu-west-1",
       client: { http: identityHttp.http, env: CREDS },
@@ -189,3 +203,274 @@ describe("whoami and the live read resolve the same target (#1982 acceptance)",
     }
   });
 });
+
+describe("whoami resolves AWS profiles the way the AWS CLI does (#3954)", () => {
+  const HOME = "/home/op";
+  const files = (map: Record<string, string>) => ({ home: HOME, readFile: (path: string) => map[path] });
+
+  test("a static-key profile named by AWS_PROFILE signs the call and is named as the source", async () => {
+    const { http, calls } = recording(CALLER_IDENTITY_XML);
+    const result = await whoami({
+      environment: "prod",
+      client: { http, env: { AWS_PROFILE: "dev" } },
+      chain: files({
+        [`${HOME}/.aws/credentials`]: "[dev]\naws_access_key_id = AKIAPROFILEKEY00000\naws_secret_access_key = profilesecret\n",
+      }),
+    });
+    expect(result).toMatchObject({
+      identity: "arn:aws:sts::491500000000:assumed-role/deploy/ci",
+      source: "profile dev (static keys); chant default (no stacks[].region)",
+    });
+    expect(calls[0].headers.authorization).toContain("Credential=AKIAPROFILEKEY00000/");
+    expect(JSON.stringify(result)).not.toContain("profilesecret");
+  });
+
+  test("an SSO-session profile is resolved through the cached token and the SSO portal", async () => {
+    const sts = recording(CALLER_IDENTITY_XML);
+    const portal: Array<{ url: string; headers: Record<string, string> }> = [];
+    const result = await whoami({
+      environment: "prod",
+      client: { http: sts.http, env: { AWS_PROFILE: "loom" } },
+      chain: {
+        ...files({
+          [`${HOME}/.aws/config`]: [
+            "[profile loom]",
+            "sso_session = acme",
+            "sso_account_id = 491500000000",
+            "sso_role_name = Deployer",
+            "",
+            "[sso-session acme]",
+            "sso_start_url = https://acme.awsapps.com/start",
+            "sso_region = eu-west-1",
+          ].join("\n"),
+          [`${HOME}/.aws/sso/cache/${sha1("acme")}.json`]: JSON.stringify({
+            accessToken: "sso-bearer",
+            expiresAt: "2030-01-01T00:00:00Z",
+          }),
+        }),
+        now: () => new Date("2026-10-12T00:00:00Z"),
+        http: (url, init) => {
+          portal.push({ url, headers: init.headers });
+          return Promise.resolve({
+            status: 200,
+            text: JSON.stringify({
+              roleCredentials: { accessKeyId: "ASIASSOKEY000000000", secretAccessKey: "ssosecret", sessionToken: "ssotoken" },
+            }),
+          });
+        },
+      },
+    });
+    expect(portal).toEqual([
+      {
+        url: "https://portal.sso.eu-west-1.amazonaws.com/federation/credentials?account_id=491500000000&role_name=Deployer",
+        headers: { "x-amz-sso_bearer_token": "sso-bearer" },
+      },
+    ]);
+    expect((result as { source: string }).source).toContain(
+      "profile loom (sso session acme), role Deployer in 491500000000",
+    );
+    expect(sts.calls[0].headers.authorization).toContain("Credential=ASIASSOKEY000000000/");
+    expect(sts.calls[0].headers["x-amz-security-token"]).toBe("ssotoken");
+    const serialized = JSON.stringify(result);
+    for (const secret of ["sso-bearer", "ssosecret", "ssotoken"]) expect(serialized).not.toContain(secret);
+  });
+
+  test("an expired SSO session is no-credentials naming aws sso login --profile", async () => {
+    const { http, calls } = recording(CALLER_IDENTITY_XML);
+    const portalCalls: string[] = [];
+    const result = await whoami({
+      environment: "prod",
+      client: { http, env: { AWS_PROFILE: "loom" } },
+      chain: {
+        ...files({
+          [`${HOME}/.aws/config`]:
+            "[profile loom]\nsso_start_url = https://acme.awsapps.com/start\nsso_region = us-east-1\nsso_account_id = 491500000000\nsso_role_name = Deployer\n",
+          [`${HOME}/.aws/sso/cache/${sha1("https://acme.awsapps.com/start")}.json`]: JSON.stringify({
+            accessToken: "stale",
+            expiresAt: "2026-01-01T00:00:00Z",
+          }),
+        }),
+        now: () => new Date("2026-10-12T00:00:00Z"),
+        http: (url) => {
+          portalCalls.push(url);
+          return Promise.resolve({ status: 200, text: "{}" });
+        },
+      },
+    });
+    expect(result).toEqual({
+      unresolved: {
+        reason: "no-credentials",
+        detail: "profile loom: the SSO session has expired; run `aws sso login --profile loom`",
+      },
+    });
+    expect(portalCalls).toHaveLength(0);
+    expect(calls).toHaveLength(0);
+  });
+
+  test("a portal refusal of a cached session also names aws sso login", async () => {
+    const { http } = recording(CALLER_IDENTITY_XML);
+    const result = await whoami({
+      environment: "prod",
+      client: { http, env: {} },
+      chain: {
+        ...files({
+          [`${HOME}/.aws/config`]:
+            "[default]\nsso_session = acme\nsso_account_id = 1\nsso_role_name = R\n[sso-session acme]\nsso_start_url = https://a/start\nsso_region = us-east-1\n",
+          [`${HOME}/.aws/sso/cache/${sha1("acme")}.json`]: JSON.stringify({
+            accessToken: "revoked",
+            expiresAt: "2030-01-01T00:00:00Z",
+          }),
+        }),
+        now: () => new Date("2026-10-12T00:00:00Z"),
+        http: () => Promise.resolve({ status: 401, text: '{"message":"Session token not found or invalid"}' }),
+      },
+    });
+    expect(result).toMatchObject({ unresolved: { reason: "no-credentials" } });
+    expect((result as { unresolved: { detail: string } }).unresolved.detail).toContain(
+      "run `aws sso login --profile default`",
+    );
+  });
+
+  test("an expired sso-session token with a refresh token is refreshed, not reported expired", async () => {
+    const sts = recording(CALLER_IDENTITY_XML);
+    const seen: string[] = [];
+    const result = await whoami({
+      environment: "prod",
+      client: { http: sts.http, env: { AWS_PROFILE: "loom" } },
+      chain: {
+        ...files({
+          [`${HOME}/.aws/config`]:
+            "[profile loom]\nsso_session = acme\nsso_account_id = 491500000000\nsso_role_name = Deployer\n[sso-session acme]\nsso_start_url = https://a/start\nsso_region = us-east-1\n",
+          [`${HOME}/.aws/sso/cache/${sha1("acme")}.json`]: JSON.stringify({
+            accessToken: "stale",
+            expiresAt: "2026-01-01T00:00:00Z",
+            refreshToken: "refresh",
+            clientId: "cid",
+            clientSecret: "csecret",
+            registrationExpiresAt: "2030-01-01T00:00:00Z",
+          }),
+        }),
+        now: () => new Date("2026-10-12T00:00:00Z"),
+        http: (url, init) => {
+          seen.push(`${init.method} ${url}`);
+          if (url.startsWith("https://oidc.")) {
+            expect(JSON.parse(init.body ?? "{}")).toMatchObject({ grantType: "refresh_token", refreshToken: "refresh" });
+            return Promise.resolve({ status: 200, text: JSON.stringify({ accessToken: "fresh", expiresIn: 3600 }) });
+          }
+          expect(init.headers["x-amz-sso_bearer_token"]).toBe("fresh");
+          return Promise.resolve({
+            status: 200,
+            text: JSON.stringify({ roleCredentials: { accessKeyId: "ASIAX", secretAccessKey: "s", sessionToken: "t" } }),
+          });
+        },
+      },
+    });
+    expect(seen).toEqual([
+      "POST https://oidc.us-east-1.amazonaws.com/token",
+      "GET https://portal.sso.us-east-1.amazonaws.com/federation/credentials?account_id=491500000000&role_name=Deployer",
+    ]);
+    expect(result).toMatchObject({ identity: "arn:aws:sts::491500000000:assumed-role/deploy/ci" });
+  });
+
+  test("credential_process output signs the call; a failing process is no-credentials without echoing output", async () => {
+    const { http, calls } = recording(CALLER_IDENTITY_XML);
+    const config = { [`${HOME}/.aws/config`]: "[profile vault]\ncredential_process = aws-vault exec ci --json\n" };
+    const ran: string[] = [];
+    const ok = await whoami({
+      environment: "prod",
+      client: { http, env: { AWS_PROFILE: "vault" } },
+      chain: {
+        ...files(config),
+        runProcess: (command) => {
+          ran.push(command);
+          return Promise.resolve({
+            exitCode: 0,
+            stderr: "",
+            stdout: JSON.stringify({ Version: 1, AccessKeyId: "ASIAPROC00000000000", SecretAccessKey: "procsecret" }),
+          });
+        },
+      },
+    });
+    expect(ran).toEqual(["aws-vault exec ci --json"]);
+    expect((ok as { source: string }).source).toContain("profile vault (credential_process)");
+    expect(calls[0].headers.authorization).toContain("Credential=ASIAPROC00000000000/");
+
+    const bad = await whoami({
+      environment: "prod",
+      client: { http, env: { AWS_PROFILE: "vault" } },
+      chain: {
+        ...files(config),
+        runProcess: () => Promise.resolve({ exitCode: 0, stderr: "", stdout: '{"AccessKeyId":"ASIALEAK"' }),
+      },
+    });
+    expect(bad).toMatchObject({ unresolved: { reason: "no-credentials" } });
+    expect(JSON.stringify(bad)).not.toContain("ASIALEAK");
+  });
+
+  test("a role_arn profile assumes the role with its source profile's keys", async () => {
+    const assumed = `<AssumeRoleResponse><AssumeRoleResult><Credentials>
+      <AccessKeyId>ASIAROLE00000000000</AccessKeyId><SecretAccessKey>rolesecret</SecretAccessKey>
+      <SessionToken>roletoken</SessionToken><Expiration>2030-01-01T00:00:00Z</Expiration>
+    </Credentials></AssumeRoleResult></AssumeRoleResponse>`;
+    const calls: Array<{ body: string; auth: string }> = [];
+    const http: AwsReadHttp = (_url, init) => {
+      calls.push({ body: init.body, auth: init.headers.authorization ?? "" });
+      return Promise.resolve({ status: 200, text: init.body.includes("AssumeRole") ? assumed : CALLER_IDENTITY_XML });
+    };
+    const result = await whoami({
+      environment: "prod",
+      client: { http, env: { AWS_PROFILE: "deploy" } },
+      chain: files({
+        [`${HOME}/.aws/config`]:
+          "[profile deploy]\nrole_arn = arn:aws:iam::491500000000:role/deploy\nsource_profile = base\nrole_session_name = ci\n",
+        [`${HOME}/.aws/credentials`]: "[base]\naws_access_key_id = AKIABASE00000000000\naws_secret_access_key = basesecret\n",
+      }),
+    });
+    expect(calls).toHaveLength(2);
+    expect(calls[0].body).toContain("Action=AssumeRole");
+    expect(calls[0].body).toContain("RoleSessionName=ci");
+    expect(calls[0].auth).toContain("Credential=AKIABASE00000000000/");
+    expect(calls[1].auth).toContain("Credential=ASIAROLE00000000000/");
+    expect((result as { source: string }).source).toContain(
+      "profile deploy (role arn:aws:iam::491500000000:role/deploy via profile base (static keys))",
+    );
+  });
+
+  test("environment keys win over AWS_PROFILE, as in the AWS CLI, and the row says the profile was not used", async () => {
+    const { http, calls } = recording(CALLER_IDENTITY_XML);
+    const result = await whoami({
+      environment: "prod",
+      client: { http, env: { ...CREDS, AWS_PROFILE: "dev" } },
+      chain: files({ [`${HOME}/.aws/credentials`]: "[dev]\naws_access_key_id = AKIAOTHER\naws_secret_access_key = x\n" }),
+    });
+    expect((result as { source: string }).source).toContain("env AWS_ACCESS_KEY_ID; AWS_PROFILE=dev not used");
+    expect(calls[0].headers.authorization).toContain(`Credential=${CREDS.AWS_ACCESS_KEY_ID}/`);
+  });
+
+  test("the default profile answers when AWS_PROFILE is unset", async () => {
+    const { http } = recording(CALLER_IDENTITY_XML);
+    const result = await whoami({
+      environment: "prod",
+      client: { http, env: {} },
+      chain: files({ [`${HOME}/.aws/credentials`]: "[default]\naws_access_key_id = AKIADEF\naws_secret_access_key = d\n" }),
+    });
+    expect((result as { source: string }).source).toContain("profile default (static keys)");
+  });
+
+  test("AWS_CONFIG_FILE and AWS_SHARED_CREDENTIALS_FILE move the files read", async () => {
+    const { http } = recording(CALLER_IDENTITY_XML);
+    const result = await whoami({
+      environment: "prod",
+      client: {
+        http,
+        env: { AWS_PROFILE: "x", AWS_CONFIG_FILE: "/etc/aws/config", AWS_SHARED_CREDENTIALS_FILE: "/etc/aws/creds" },
+      },
+      chain: files({ "/etc/aws/creds": "[x]\naws_access_key_id = AKIAX\naws_secret_access_key = s\n" }),
+    });
+    expect((result as { source: string }).source).toContain("profile x (static keys)");
+  });
+});
+
+function sha1(value: string): string {
+  return createHash("sha1").update(value).digest("hex");
+}

package/src/caller-identity.ts

@@ -20,12 +20,24 @@
  *
  * ## Credentials
  *
- * `resolveCredentials` (./api/sigv4.ts) reads `AWS_ACCESS_KEY_ID` /
- * `AWS_SECRET_ACCESS_KEY` and nothing else — no profile file, no IMDS, no
- * container endpoint, deliberately. `AWS_PROFILE` alone therefore signs
- * nothing, and against real AWS the call comes back unauthorized. That is
- * reported as `no-credentials` naming the profile, which is a far better
- * answer than an empty stack read an hour later.
+ * Resolved the way the AWS CLI resolves them (#3954), by
+ * `./api/credential-chain.ts`: environment keys, then the profile
+ * `AWS_PROFILE` names (or `default`) from the shared config and credentials
+ * files, through static keys, `role_arn`, SSO sessions and
+ * `credential_process`. Before #3954 only the environment keys were read, so
+ * `AWS_PROFILE=dev` on an SSO session answered "no identity is configured"
+ * while `aws sts get-caller-identity` answered with a principal. An expired
+ * SSO session is `no-credentials` naming `aws sso login --profile <p>`.
+ *
+ * The native read transport still signs with environment keys only
+ * (`resolveCredentials` in ./api/sigv4.ts; #3958). So a profile-sourced row says
+ * what the CLI, and anything shelling out to it, would act as; it does not
+ * yet say what `describeResources` signs with. The `source` column names the
+ * profile, so the difference is visible.
+ *
+ * Against an endpoint override the chain is not walked: the emulator call is
+ * unsigned whatever resolves, and a whoami against Floci should not start an
+ * SSO refresh or a `credential_process`.
  *
  * No credential value is ever returned. The identity is the principal ARN the
  * service itself answers with, and the scope is an account and a region.
@@ -39,7 +51,7 @@ import {
   serviceUrl,
   type AwsReadClientOptions,
 } from "./api/read-client";
-import { resolveCredentials } from "./api/sigv4";
+import { resolveCredentialChain, type CredentialChainOptions } from "./api/credential-chain";
 
 /** The region the read transport falls back to when no stack declares one. */
 const DEFAULT_REGION = "us-east-1";
@@ -62,9 +74,9 @@ function regionSource(declared: string | undefined, env: Record<string, string |
   return "chant default (no stacks[].region)";
 }
 
-/** Where the signature came from, without any part of the credential itself. */
-function credentialSource(env: Record<string, string | undefined>): string | undefined {
-  if (!resolveCredentials(undefined, env)) return undefined;
+/** The environment-key label, used against an endpoint override where the chain is not walked. */
+function envCredentialLabel(env: Record<string, string | undefined>): string | undefined {
+  if (!env.AWS_ACCESS_KEY_ID || !env.AWS_SECRET_ACCESS_KEY) return undefined;
   return env.AWS_SESSION_TOKEN
     ? "env AWS_ACCESS_KEY_ID + AWS_SESSION_TOKEN"
     : "env AWS_ACCESS_KEY_ID";
@@ -73,6 +85,12 @@ function credentialSource(env: Record<string, string | undefined>): string | und
 /** Options this module needs beyond the contract — the injectable transport, for tests. */
 export interface CallerIdentityOptions extends DescribeIdentityOptions {
   client?: AwsReadClientOptions;
+  /**
+   * The credential chain's seams: shared-file reads, the SSO and
+   * `credential_process` transports, the clock. Its `env` defaults to the
+   * client's, and its STS transport to the client's `http`.
+   */
+  chain?: CredentialChainOptions;
 }
 
 /**
@@ -91,19 +109,23 @@ export async function describeIdentity(options: CallerIdentityOptions): Promise<
   const region = client.region ?? DEFAULT_REGION;
   const endpoint = serviceUrl("sts", override, client.region);
 
-  const credential = credentialSource(env);
   // Against an emulator the call is unsigned by design (Floci verifies no
   // signature), so an absent credential is not yet a refusal — the emulator
-  // answers with the identity it models. Against real AWS it is.
-  if (!credential && !override) {
-    return {
-      unresolved: {
-        reason: "no-credentials",
-        detail: env.AWS_PROFILE
-          ? `no AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY in the environment; AWS_PROFILE=${env.AWS_PROFILE} is set, but chant's native transport reads only the environment credentials, not the profile file`
-          : "no AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY in the environment",
-      },
-    };
+  // answers with the identity it models — and the chain is not walked.
+  let credential: string | undefined;
+  if (override) {
+    credential = envCredentialLabel(env);
+  } else if (client.credentials) {
+    credential = "credentials injected by the caller";
+  } else {
+    const chain = await resolveCredentialChain({
+      env,
+      ...options.chain,
+      sts: { ...(client.http ? { http: client.http } : {}), ...options.chain?.sts, env },
+    });
+    if ("unresolved" in chain) return { unresolved: chain.unresolved };
+    credential = chain.resolved.source;
+    client.credentials = chain.resolved.credentials;
   }
 
   let identity;

package/src/codegen/generate.ts

@@ -27,6 +27,15 @@ import {
   type EnumOverlayApplication,
   type EnumOverlayEntry,
 } from "./enum-overlay";
+import {
+  applyPropertyOverlay,
+  assertPropertyOverlayCoverage,
+  propertyOverlayByType,
+  propertyOverlayEntries,
+  redundantPropertyOverlayWarnings,
+  type PropertyOverlayApplication,
+  type PropertyOverlayEntry,
+} from "./property-overlay";
 import { samResources } from "./sam";
 import { fallbackResources } from "./fallback";
 import { NamingStrategy, publishedNames, propertyTypeName, extractDefName } from "./naming";
@@ -56,6 +65,9 @@ let awsOverlay: Map<string, EnumOverlayEntry[]> = new Map();
 let awsOverlayApplications: EnumOverlayApplication[] = [];
 let awsOverlaySeenTypes = new Set<string>();
 let awsOverlayStrict = false;
+/** Backfilled properties (chant #3953), reset per `generate()` call; strictness and seen types are shared with the enum overlay. */
+let awsPropertyOverlay: Map<string, PropertyOverlayEntry[]> = new Map();
+let awsPropertyOverlayApplications: PropertyOverlayApplication[] = [];
 
 const awsPipelineConfig: GeneratePipelineConfig<SchemaParseResult> = {
   fetchSchemas: async (opts) => {
@@ -69,8 +81,11 @@ const awsPipelineConfig: GeneratePipelineConfig<SchemaParseResult> = {
 
   parseSchema: (typeName, data) => {
     awsOverlaySeenTypes.add(typeName);
+    // Properties first, so an enum overlay entry could name a backfilled one.
+    const backfilled = applyPropertyOverlay(data, awsPropertyOverlay.get(typeName) ?? []);
+    awsPropertyOverlayApplications.push(...backfilled.applications);
     const entries = awsOverlay.get(typeName) ?? [];
-    const overlaid = applyEnumOverlay(typeName, data, entries, { strict: awsOverlayStrict });
+    const overlaid = applyEnumOverlay(typeName, backfilled.data, entries, { strict: awsOverlayStrict });
     awsOverlayApplications.push(...overlaid.applications);
     const result = parseCFNSchema(overlaid.data);
     if (!result.resource.typeName) return null;
@@ -142,6 +157,11 @@ const awsPipelineConfig: GeneratePipelineConfig<SchemaParseResult> = {
     log(`Applied ${applied} curated enum overlay entries`);
     warnings.push(...redundantOverlayWarnings(awsOverlayApplications));
 
+    assertPropertyOverlayCoverage(propertyOverlayEntries(), awsOverlaySeenTypes, awsOverlayStrict);
+    const backfilled = awsPropertyOverlayApplications.filter((a) => a.outcome === "applied").length;
+    log(`Backfilled ${backfilled} properties the pinned spec predates`);
+    warnings.push(...redundantPropertyOverlayWarnings(awsPropertyOverlayApplications));
+
     log(`Total: ${results.length} resource schemas`);
     return { results, warnings };
   },
@@ -174,6 +194,8 @@ export async function generate(opts: GenerateOptions = {}): Promise<GenerateResu
   awsOverlay = enumOverlayByType();
   awsOverlayApplications = [];
   awsOverlaySeenTypes = new Set();
+  awsPropertyOverlay = propertyOverlayByType();
+  awsPropertyOverlayApplications = [];
   // A fixture set is a trimmed subset, so an entry it never reaches is
   // expected; a run over the real zip has no such excuse.
   awsOverlayStrict = !opts.schemaSource;

package/src/codegen/property-overlay.json

@@ -0,0 +1,19 @@
+{
+  "$comment": "Properties CloudFormation has shipped since the pinned Registry spec (src/spec/pin.ts) was accepted (chant #3953). Hand-maintained, merged into the raw schema at codegen time by src/codegen/property-overlay.ts. Each entry is copied from the live Registry schema; retire it when a pin bump (#3960) brings the property in; generation warns when it does.",
+  "entries": [
+    {
+      "type": "AWS::BedrockAgentCore::Runtime",
+      "property": "PlatformVersion",
+      "issue": 3953,
+      "source": "https://schema.cloudformation.us-east-1.amazonaws.com/CloudformationSchema.zip (aws-bedrockagentcore-runtime.json)",
+      "reviewed": "2026-10-12",
+      "schema": {
+        "type": "string",
+        "description": "The version of the runtime platform",
+        "minLength": 1,
+        "maxLength": 128,
+        "pattern": "^[^\\s]+$"
+      }
+    }
+  ]
+}

package/src/codegen/property-overlay.test.ts

@@ -0,0 +1,61 @@
+import { describe, test, expect } from "vitest";
+import {
+  applyPropertyOverlay,
+  assertPropertyOverlayCoverage,
+  propertyOverlayEntries,
+  redundantPropertyOverlayWarnings,
+  type PropertyOverlayEntry,
+} from "./property-overlay";
+
+const entry = (over: Partial<PropertyOverlayEntry> = {}): PropertyOverlayEntry => ({
+  type: "AWS::Test::Resource",
+  property: "Version",
+  issue: 1,
+  source: "https://example.invalid",
+  reviewed: "2026-10-12",
+  schema: { type: "string", maxLength: 8 },
+  ...over,
+});
+
+const schema = (properties: Record<string, unknown> = { Name: { type: "string" } }) =>
+  JSON.stringify({ typeName: "AWS::Test::Resource", properties, additionalProperties: false });
+
+describe("applyPropertyOverlay", () => {
+  test("adds a property the schema lacks, leaving the rest alone", () => {
+    const { data, applications } = applyPropertyOverlay(schema(), [entry()]);
+    expect(applications.map((a) => a.outcome)).toEqual(["applied"]);
+    const doc = JSON.parse(data as string);
+    expect(doc.properties.Version).toEqual({ type: "string", maxLength: 8 });
+    expect(doc.properties.Name).toEqual({ type: "string" });
+  });
+
+  test("the spec wins once it declares the property", () => {
+    const upstream = schema({ Version: { type: "string", maxLength: 128 } });
+    const { data, applications } = applyPropertyOverlay(upstream, [entry()]);
+    expect(data).toBe(upstream);
+    expect(applications.map((a) => a.outcome)).toEqual(["redundant"]);
+    expect(redundantPropertyOverlayWarnings(applications)).toHaveLength(1);
+  });
+
+  test("keeps the input's encoding", () => {
+    const { data } = applyPropertyOverlay(Buffer.from(schema()), [entry()]);
+    expect(Buffer.isBuffer(data)).toBe(true);
+  });
+});
+
+describe("assertPropertyOverlayCoverage", () => {
+  test("a strict run refuses an entry on a type it never saw", () => {
+    expect(() => assertPropertyOverlayCoverage([entry()], new Set(), true)).toThrow(/AWS::Test::Resource/);
+    expect(() => assertPropertyOverlayCoverage([entry()], new Set(), false)).not.toThrow();
+  });
+});
+
+describe("property-overlay.json", () => {
+  test("every entry names a top-level property and a schema with a type", () => {
+    for (const e of propertyOverlayEntries()) {
+      expect(e.type).toMatch(/^AWS::\w+::\w+$/);
+      expect(e.property).toMatch(/^[A-Z]\w*$/);
+      expect(typeof e.schema.type).toBe("string");
+    }
+  });
+});