@intentius/chant-lexicon-aws 0.52.2 → 0.53.1

package/dist/api/read-client.d.ts

@@ -169,6 +169,25 @@ export interface StackDetail {
 export declare function describeStackDetail(stackName: string, options?: AwsReadClientOptions): Promise<StackDetail>;
 /** `DescribeStacks` outputs for one stack, as `key → value`. */
 export declare function describeStackOutputs(stackName: string, options?: AwsReadClientOptions): Promise<Record<string, string>>;
+/** What `sts:GetCallerIdentity` answers with. No credential is in the response. */
+export interface CallerIdentity {
+    /** The principal's ARN — an IAM user, or an assumed-role session. */
+    arn: string;
+    /** The 12-digit account the credentials belong to. */
+    account: string;
+}
+/**
+ * `sts:GetCallerIdentity` — who these credentials are, per the service itself
+ * (#1982). Query protocol like CloudFormation, so it rides the same transport,
+ * the same endpoint-override rule and the same signing decision as every other
+ * read, which is what keeps `chant lifecycle whoami` and `describeResources`
+ * from resolving different targets.
+ *
+ * The response carries an ARN, an account and a `UserId`. Only the first two
+ * are returned: `UserId` adds nothing a principal ARN does not already say,
+ * and the narrower the surface, the fewer ways a credential reaches a report.
+ */
+export declare function getCallerIdentity(options?: AwsReadClientOptions): Promise<CallerIdentity>;
 /** One live resource, as Cloud Control describes it. */
 export interface CloudControlDescription {
     identifier: string;

package/dist/api/read-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"read-client.d.ts","sourceRoot":"","sources":["../../src/api/read-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"read-client.d.ts","sourceRoot":"","sources":["../../src/api/read-client.ts"],"names":[],"mappings":"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"}

package/dist/caller-identity.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Who chant would act as in AWS — the lexicon half of `chant lifecycle whoami`
+ * (chant #1982).
+ *
+ * `sts:GetCallerIdentity` on the same transport every read uses, so the answer
+ * cannot describe a target the read does not reach: the endpoint override, the
+ * region and the signing decision are resolved by `read-client.ts` once, for
+ * both. That parity is the point of the command — a whoami that reports real
+ * AWS while `describeResources` reads Floci is worse than none — and a test
+ * pins it.
+ *
+ * ## What the region actually is
+ *
+ * The native read transport takes its region from the stack being observed
+ * (`stacks[].region`, #1261) and falls back to `us-east-1` inside `serviceUrl`.
+ * It does NOT read `AWS_REGION`. So that is what is reported, including the
+ * awkward case: an operator whose shell exports `AWS_REGION=eu-west-1` and
+ * whose project declares no stack region is reading us-east-1, and has had no
+ * way to find that out short of a wrong answer. `source` names it.
+ *
+ * ## 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.
+ *
+ * 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.
+ */
+import type { DescribeIdentityOptions, DescribeIdentityResult } from "@intentius/chant/lexicon";
+import { type AwsReadClientOptions } from "./api/read-client.js";
+/** Options this module needs beyond the contract — the injectable transport, for tests. */
+export interface CallerIdentityOptions extends DescribeIdentityOptions {
+    client?: AwsReadClientOptions;
+}
+/**
+ * The AWS `describeIdentity`. Returns the STS principal and the account+region
+ * scope, or a typed refusal — never a guessed identity and never an empty one.
+ */
+export declare function describeIdentity(options: CallerIdentityOptions): Promise<DescribeIdentityResult>;
+//# sourceMappingURL=caller-identity.d.ts.map

package/dist/caller-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"caller-identity.d.ts","sourceRoot":"","sources":["../src/caller-identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAChG,OAAO,EAKL,KAAK,oBAAoB,EAC1B,MAAM,mBAAmB,CAAC;AAgC3B,2FAA2F;AAC3F,MAAM,WAAW,qBAAsB,SAAQ,uBAAuB;IACpE,MAAM,CAAC,EAAE,oBAAoB,CAAC;CAC/B;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAmEtG"}

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "2bc626775d04c8e8b162da0a076ac5efab827834fc0ea83ae1871b82479cf7ec",
+    "manifest.json": "704d8f5e7e5f494108a64890a4340747bd01ae7b716c4ac56d2af24f7baa4b17",
     "meta.json": "49cbb2ca9b454391a7644e14ee9cfd91bcf906c6af683bf46a182aa85047ecc4",
     "types/index.d.ts": "6d6b37bd14a9b40fb3ff5c66e1cb49be1ae1032de47a4e167cf5f411c943b7f5",
     "rules/hardcoded-region.ts": "5a0eaf7ab391231fe6cd51426ece29539cb4b36f31c8dd060956638fed55722a",
@@ -72,5 +72,5 @@
     "skills/chant-aws-eks.md": "8789255709ff004ad0a875fd5999edcdc66fc6e33d710db058d9f42703bcfdfe",
     "skills/chant-aws-carve-terraform.md": "0ae4376590db47979be144d3ac6cdcfd56c9640d0536421aacf7330459d38e52"
   },
-  "composite": "d3fda61a74692e9473bb1aeeb31723128b926b4c9a0014ba2d399dfab05473bb"
+  "composite": "127eb4df938dced05503394592d2e12632ca9209b32de6d7531c6a867dca53fc"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "aws",
-  "version": "0.52.2",
+  "version": "0.53.1",
   "chantVersion": ">=0.1.0",
   "namespace": "AWS",
   "intrinsics": [

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAoN,MAAM,0BAA0B,CAAC;AAuChR;yEACyE;AACzE,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAiBnD,eAAO,MAAM,SAAS,EAAE,aAm/BvB,CAAC"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAqQ,MAAM,0BAA0B,CAAC;AAuCjU;yEACyE;AACzE,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAiBnD,eAAO,MAAM,SAAS,EAAE,aA8/BvB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-aws",
-  "version": "0.52.2",
+  "version": "0.53.1",
   "description": "AWS CloudFormation lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -80,7 +80,7 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.52.2",
+    "@intentius/chant": "^0.53.1",
     "typescript": "^5.9.3"
   }
 }

package/src/api/read-client.ts

@@ -364,6 +364,54 @@ export async function describeStackOutputs(
   return (await describeStackDetail(stackName, options)).outputs;
 }
 
+/* ── STS ──────────────────────────────────────────────────────────────────── */
+
+const STS_API_VERSION = "2011-06-15";
+
+/** What `sts:GetCallerIdentity` answers with. No credential is in the response. */
+export interface CallerIdentity {
+  /** The principal's ARN — an IAM user, or an assumed-role session. */
+  arn: string;
+  /** The 12-digit account the credentials belong to. */
+  account: string;
+}
+
+/**
+ * `sts:GetCallerIdentity` — who these credentials are, per the service itself
+ * (#1982). Query protocol like CloudFormation, so it rides the same transport,
+ * the same endpoint-override rule and the same signing decision as every other
+ * read, which is what keeps `chant lifecycle whoami` and `describeResources`
+ * from resolving different targets.
+ *
+ * The response carries an ARN, an account and a `UserId`. Only the first two
+ * are returned: `UserId` adds nothing a principal ARN does not already say,
+ * and the narrower the surface, the fewer ways a credential reaches a report.
+ */
+export async function getCallerIdentity(options: AwsReadClientOptions = {}): Promise<CallerIdentity> {
+  options = withEndpointOverride("sts", options);
+  const http = options.http ?? defaultHttp;
+  const url = serviceUrl("sts", options.endpoint, options.region);
+  const body = new URLSearchParams({ Action: "GetCallerIdentity", Version: STS_API_VERSION }).toString();
+  const res = await http(
+    url,
+    {
+      headers: requestHeaders("sts", url, body, { "content-type": "application/x-www-form-urlencoded" }, options),
+      body,
+    },
+    options.signal,
+  );
+  const err = xmlError(res.text);
+  if (err || res.status >= 400) {
+    throw new AwsReadError(
+      err?.message ?? `GetCallerIdentity failed with HTTP ${res.status}`,
+      res.status,
+      err?.code,
+    );
+  }
+  const leaves = xmlLeaves(res.text);
+  return { arn: leaves.Arn ?? "", account: leaves.Account ?? "" };
+}
+
 /* ── Cloud Control ────────────────────────────────────────────────────────── */
 
 /** One live resource, as Cloud Control describes it. */

package/src/caller-identity.test.ts

@@ -0,0 +1,191 @@
+/**
+ * `chant lifecycle whoami` for AWS (chant #1982).
+ *
+ * The transport is injected everywhere here, so nothing reaches a network and
+ * no real credential is involved. The load-bearing test is the last one: the
+ * identity query and the declared-entity read must resolve the same target,
+ * because a whoami that names a binding the read does not use is worse than no
+ * whoami at all.
+ */
+import { describe, test, expect } from "vitest";
+import { describeIdentity } from "./caller-identity";
+import { describeStackResources, type AwsReadHttp } from "./api/read-client";
+
+const CALLER_IDENTITY_XML = `
+<GetCallerIdentityResponse><GetCallerIdentityResult>
+  <Arn>arn:aws:sts::491500000000:assumed-role/deploy/ci</Arn>
+  <UserId>AROAEXAMPLEID123456:ci</UserId>
+  <Account>491500000000</Account>
+</GetCallerIdentityResult></GetCallerIdentityResponse>`;
+
+const STACK_XML = `
+<DescribeStackResourcesResponse><DescribeStackResourcesResult><StackResources>
+  <member>
+    <LogicalResourceId>bucket</LogicalResourceId>
+    <ResourceType>AWS::S3::Bucket</ResourceType>
+  </member>
+</StackResources></DescribeStackResourcesResult></DescribeStackResourcesResponse>`;
+
+/** Records every request so a test can assert what went on the wire. */
+function recording(text: string, status = 200) {
+  const calls: Array<{ url: string; headers: Record<string, string>; body: string }> = [];
+  const http: AwsReadHttp = (url, init) => {
+    calls.push({ url, headers: init.headers, body: init.body });
+    return Promise.resolve({ status, text });
+  };
+  return { http, calls };
+}
+
+/** 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({
+      environment: "prod",
+      region: "eu-west-1",
+      client: { http, env: CREDS },
+    });
+
+    expect(result).toEqual({
+      identity: "arn:aws:sts::491500000000:assumed-role/deploy/ci",
+      scope: "491500000000 eu-west-1",
+      source: "env AWS_ACCESS_KEY_ID; stacks[].region",
+      endpoint: "https://sts.eu-west-1.amazonaws.com/",
+    });
+    expect(calls).toHaveLength(1);
+    expect(calls[0].body).toContain("Action=GetCallerIdentity");
+    // The principal id adds nothing an ARN does not already say, and the
+    // narrower the surface the fewer ways a credential reaches a report.
+    expect(JSON.stringify(result)).not.toContain("AROAEXAMPLEID123456");
+  });
+
+  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: {} } });
+    expect(result).toEqual({
+      unresolved: {
+        reason: "no-credentials",
+        detail: "no AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY in the environment",
+      },
+    });
+    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({
+      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");
+  });
+
+  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({
+      environment: "floci",
+      client: { http, env: { AWS_ENDPOINT_URL: "http://localhost:4566" } },
+    });
+    expect(result).toMatchObject({
+      identity: "arn:aws:sts::491500000000:assumed-role/deploy/ci",
+      endpoint: "http://localhost:4566/",
+    });
+    expect((result as { source: string }).source).toContain("unsigned (endpoint override)");
+    expect((result as { source: string }).source).toContain("endpoint override http://localhost:4566");
+    expect(calls[0].url).toBe("http://localhost:4566/");
+  });
+
+  test("a refused call is no-credentials; a broken one is read-failed", async () => {
+    const denied = recording(
+      "<ErrorResponse><Error><Code>InvalidClientTokenId</Code><Message>bad token</Message></Error></ErrorResponse>",
+      403,
+    );
+    expect(
+      await describeIdentity({ 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 } });
+    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 } });
+    expect(result).toMatchObject({ unresolved: { reason: "read-failed" } });
+  });
+
+  test("the region an undeclared project actually reads is reported, not the one AWS_REGION suggests", async () => {
+    // The read transport takes its region from `stacks[].region` and defaults
+    // 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({
+      environment: "prod",
+      client: { http, env: { ...CREDS, AWS_REGION: "ap-south-1" } },
+    });
+    expect((result as { scope: string }).scope).toBe("491500000000 us-east-1");
+    expect((result as { source: string }).source).toContain("AWS_REGION=ap-south-1 is not read by this transport");
+    expect(calls[0].url).toBe("https://sts.us-east-1.amazonaws.com/");
+  });
+
+  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 serialized = JSON.stringify(result);
+    expect(serialized).not.toContain(CREDS.AWS_SECRET_ACCESS_KEY);
+    expect(serialized).not.toContain(CREDS.AWS_ACCESS_KEY_ID);
+  });
+});
+
+describe("whoami and the live read resolve the same target (#1982 acceptance)", () => {
+  test("an endpoint override sends both to the same origin", async () => {
+    const env = { ...CREDS, AWS_ENDPOINT_URL: "http://localhost:4566" };
+
+    const identityHttp = recording(CALLER_IDENTITY_XML);
+    const identity = await describeIdentity({
+      environment: "floci",
+      region: "eu-west-1",
+      client: { http: identityHttp.http, env },
+    });
+
+    const readHttp = recording(STACK_XML);
+    await describeStackResources("floci", { http: readHttp.http, env, region: "eu-west-1" });
+
+    const origin = (url: string): string => new URL(url).origin;
+    expect(origin(identityHttp.calls[0].url)).toBe(origin(readHttp.calls[0].url));
+    // And the row names it, so the operator sees the target rather than
+    // inferring it.
+    expect((identity as { endpoint: string }).endpoint).toBe(readHttp.calls[0].url);
+  });
+
+  test("against real AWS both resolve the same region, on each service's own host", async () => {
+    const identityHttp = recording(CALLER_IDENTITY_XML);
+    await describeIdentity({
+      environment: "prod",
+      region: "eu-west-1",
+      client: { http: identityHttp.http, env: CREDS },
+    });
+
+    const readHttp = recording(STACK_XML);
+    await describeStackResources("prod", { http: readHttp.http, env: CREDS, region: "eu-west-1" });
+
+    const host = (url: string): string => new URL(url).host;
+    expect(host(identityHttp.calls[0].url)).toBe("sts.eu-west-1.amazonaws.com");
+    expect(host(readHttp.calls[0].url)).toBe("cloudformation.eu-west-1.amazonaws.com");
+    // The credential scope both signatures carry is the same region — which is
+    // the part a wrong answer would get wrong.
+    for (const calls of [identityHttp.calls, readHttp.calls]) {
+      expect(calls[0].headers.authorization ?? calls[0].headers.Authorization).toContain("/eu-west-1/");
+    }
+  });
+});

package/src/caller-identity.ts

@@ -0,0 +1,149 @@
+/**
+ * Who chant would act as in AWS — the lexicon half of `chant lifecycle whoami`
+ * (chant #1982).
+ *
+ * `sts:GetCallerIdentity` on the same transport every read uses, so the answer
+ * cannot describe a target the read does not reach: the endpoint override, the
+ * region and the signing decision are resolved by `read-client.ts` once, for
+ * both. That parity is the point of the command — a whoami that reports real
+ * AWS while `describeResources` reads Floci is worse than none — and a test
+ * pins it.
+ *
+ * ## What the region actually is
+ *
+ * The native read transport takes its region from the stack being observed
+ * (`stacks[].region`, #1261) and falls back to `us-east-1` inside `serviceUrl`.
+ * It does NOT read `AWS_REGION`. So that is what is reported, including the
+ * awkward case: an operator whose shell exports `AWS_REGION=eu-west-1` and
+ * whose project declares no stack region is reading us-east-1, and has had no
+ * way to find that out short of a wrong answer. `source` names it.
+ *
+ * ## 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.
+ *
+ * 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.
+ */
+
+import type { DescribeIdentityOptions, DescribeIdentityResult } from "@intentius/chant/lexicon";
+import {
+  AwsReadError,
+  getCallerIdentity,
+  resolveEndpointOverride,
+  serviceUrl,
+  type AwsReadClientOptions,
+} from "./api/read-client";
+import { resolveCredentials } from "./api/sigv4";
+
+/** The region the read transport falls back to when no stack declares one. */
+const DEFAULT_REGION = "us-east-1";
+
+/** True when the failure says the call was refused rather than broken. */
+function isAuthFailure(err: AwsReadError): boolean {
+  if (err.status === 401 || err.status === 403) return true;
+  return /credential|token|expired|AccessDenied|not authorized|Unauthorized|InvalidClientTokenId|SignatureDoesNotMatch/i.test(
+    `${err.code ?? ""} ${err.message}`,
+  );
+}
+
+/** Where the region came from, said plainly enough to act on. */
+function regionSource(declared: string | undefined, env: Record<string, string | undefined>): string {
+  if (declared) return `stacks[].region`;
+  const ambient = env.AWS_REGION ?? env.AWS_DEFAULT_REGION;
+  if (ambient && ambient !== DEFAULT_REGION) {
+    return `chant default (no stacks[].region; AWS_REGION=${ambient} is not read by this transport)`;
+  }
+  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;
+  return env.AWS_SESSION_TOKEN
+    ? "env AWS_ACCESS_KEY_ID + AWS_SESSION_TOKEN"
+    : "env AWS_ACCESS_KEY_ID";
+}
+
+/** Options this module needs beyond the contract — the injectable transport, for tests. */
+export interface CallerIdentityOptions extends DescribeIdentityOptions {
+  client?: AwsReadClientOptions;
+}
+
+/**
+ * The AWS `describeIdentity`. Returns the STS principal and the account+region
+ * scope, or a typed refusal — never a guessed identity and never an empty one.
+ */
+export async function describeIdentity(options: CallerIdentityOptions): Promise<DescribeIdentityResult> {
+  const client: AwsReadClientOptions = {
+    ...options.client,
+    ...(options.region ? { region: options.region } : {}),
+  };
+  const env = client.env ?? process.env;
+  const override = resolveEndpointOverride("sts", client.endpoint, env);
+  // The region the transport resolves, not the one an operator might assume:
+  // `serviceUrl` defaults it, so this is the host the read is actually sent to.
+  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",
+      },
+    };
+  }
+
+  let identity;
+  try {
+    identity = await getCallerIdentity(client);
+  } catch (err) {
+    if (err instanceof AwsReadError) {
+      return {
+        unresolved: {
+          reason: isAuthFailure(err) ? "no-credentials" : "read-failed",
+          detail: `sts:GetCallerIdentity against ${endpoint} failed: ${err.code ? `${err.code}: ` : ""}${err.message}`,
+        },
+      };
+    }
+    return {
+      unresolved: {
+        reason: "read-failed",
+        detail: `sts:GetCallerIdentity against ${endpoint} failed: ${err instanceof Error ? err.message : String(err)}`,
+      },
+    };
+  }
+
+  if (!identity.arn) {
+    return {
+      unresolved: {
+        reason: "read-failed",
+        detail: `sts:GetCallerIdentity against ${endpoint} answered without an Arn`,
+      },
+    };
+  }
+
+  const sources = [
+    credential ?? "unsigned (endpoint override)",
+    regionSource(client.region, env),
+    ...(override ? [`endpoint override ${override}`] : []),
+  ];
+  return {
+    identity: identity.arn,
+    scope: identity.account ? `${identity.account} ${region}` : region,
+    source: sources.join("; "),
+    endpoint,
+  };
+}

package/src/plugin.ts

@@ -1,6 +1,6 @@
 import { createRequire } from "module";
 import { detectTemplate } from "./detect";
-import type { LexiconPlugin, IntrinsicDef, ObservationResult, DeepObservationResult, DependencyObservation, DisruptionQuery, DisruptionVerdict, ResourceMetadata, ExportedTemplate, ResourceSelector, InitTemplateSet, StackStatusObservation } from "@intentius/chant/lexicon";
+import type { LexiconPlugin, IntrinsicDef, ObservationResult, DeepObservationResult, DependencyObservation, DescribeIdentityOptions, DescribeIdentityResult, DisruptionQuery, DisruptionVerdict, ResourceMetadata, ExportedTemplate, ResourceSelector, InitTemplateSet, StackStatusObservation } from "@intentius/chant/lexicon";
 const require = createRequire(import.meta.url);
 import type { LintRule } from "@intentius/chant/lint/rule";
 import type { TemplateParser } from "@intentius/chant/import/parser";
@@ -800,6 +800,17 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
     return awsDisruption(options);
   },
 
+  /**
+   * Who chant would act as here, before it acts (#1982) —
+   * `sts:GetCallerIdentity` on the same transport, endpoint override and
+   * region resolution `describeResources` uses, so the principal reported and
+   * the account read are the same one. Implementation in ./caller-identity.ts.
+   */
+  async describeIdentity(options: DescribeIdentityOptions): Promise<DescribeIdentityResult> {
+    const { describeIdentity } = await import("./caller-identity");
+    return describeIdentity(options);
+  },
+
   /**
    * Resources of a managed kind that exist without being declared or
    * referenced (#1278) — the account's default security groups, an unattached