@intentius/chant-lexicon-aws 0.44.9 → 0.44.12

package/src/api/read-client.test.ts

@@ -19,6 +19,7 @@ import {
   xmlError,
   type AwsReadHttp,
 } from "./read-client";
+import { EMPTY_PAYLOAD_SHA256 } from "./sigv4";
 
 const respond = (text: string, status = 200): ReturnType<AwsReadHttp> => Promise.resolve({ status, text });
 
@@ -210,25 +211,107 @@ describe("the region an endpoint override cannot carry in its host", () => {
   // snapshot recorded that region as holding nothing.
   test("the request names the region in its credential scope", async () => {
     const { http, calls } = recording(() => respond(stackXml));
-    await describeStackResources("web", { endpoint: "http://localhost:4566", region: "us-west-1", http });
+    await describeStackResources("web", { endpoint: "http://localhost:4566", region: "us-west-1", http, env: {} });
     expect(calls[0].headers.authorization).toContain("/us-west-1/cloudformation/aws4_request");
   });
 
   test("Cloud Control carries it too, scoped to its own service", async () => {
     const { http, calls } = recording(() => respond(JSON.stringify({ ResourceDescription: {} })));
-    await getResource("AWS::EC2::VPC", "vpc-01", { endpoint: "http://localhost:4566", region: "eu-west-1", http });
+    await getResource("AWS::EC2::VPC", "vpc-01", { endpoint: "http://localhost:4566", region: "eu-west-1", http, env: {} });
     expect(calls[0].headers.authorization).toContain("/eu-west-1/cloudcontrolapi/aws4_request");
   });
 
   test("no region, no header — nothing invents one", async () => {
     const { http, calls } = recording(() => respond(stackXml));
-    await describeStackResources("web", { endpoint: "http://localhost:4566", http });
+    await describeStackResources("web", { endpoint: "http://localhost:4566", http, env: {} });
     expect(calls[0].headers.authorization).toBeUndefined();
   });
 
   test("it is a scope, not a signature — the placeholder says so", async () => {
     const { http, calls } = recording(() => respond(stackXml));
-    await describeStackResources("web", { region: "us-west-1", http });
+    await describeStackResources("web", { region: "us-west-1", http, env: {} });
     expect(calls[0].headers.authorization).toContain("Signature=unsigned");
   });
 });
+
+/**
+ * The signing decision, as the client makes it. `./sigv4.test.ts` proves the
+ * signature is correct against AWS's own vectors; these prove the client only
+ * produces one when it should.
+ */
+describe("SigV4 on the read path", () => {
+  const credentials = { accessKeyId: "AKIDEXAMPLE", secretAccessKey: "wJalrXUtnFEMI/K7MDENG+bPxRfiCYEXAMPLEKEY" };
+  const now = new Date("2015-08-30T12:36:00Z");
+
+  test("credentials and a real host produce a signed request, not the placeholder", async () => {
+    const { http, calls } = recording(() => respond(stackXml));
+    await describeStackResources("web", { region: "us-west-1", credentials, now, http, env: {} });
+
+    const auth = calls[0].headers.authorization;
+    expect(auth).toContain("Credential=AKIDEXAMPLE/20150830/us-west-1/cloudformation/aws4_request");
+    expect(auth).not.toContain("Signature=unsigned");
+    expect(auth).toMatch(/Signature=[0-9a-f]{64}$/);
+    expect(calls[0].headers["x-amz-date"]).toBe("20150830T123600Z");
+    // The body hash, not the empty-payload constant — the Query call has a body.
+    expect(calls[0].headers["x-amz-content-sha256"]).toMatch(/^[0-9a-f]{64}$/);
+    expect(calls[0].headers["x-amz-content-sha256"]).not.toBe(EMPTY_PAYLOAD_SHA256);
+    // `host` is signed but never emitted: fetch computes it and forbids the override.
+    expect(calls[0].headers.host).toBeUndefined();
+    expect(auth).toContain("SignedHeaders=content-type;host;x-amz-content-sha256;x-amz-date");
+  });
+
+  test("an endpoint override is not signed, so the emulator lanes need no credentials", async () => {
+    const { http, calls } = recording(() => respond(stackXml));
+    await describeStackResources("web", {
+      endpoint: "http://localhost:4566",
+      region: "us-west-1",
+      credentials,
+      http,
+      env: {},
+    });
+    expect(calls[0].headers.authorization).toContain("Signature=unsigned");
+    expect(calls[0].headers["x-amz-date"]).toBeUndefined();
+  });
+
+  test("signEndpointOverride signs one anyway — for an override that is real AWS", async () => {
+    const { http, calls } = recording(() => respond(stackXml));
+    await describeStackResources("web", {
+      endpoint: "https://vpce-1234.cloudformation.us-west-1.vpce.amazonaws.com",
+      region: "us-west-1",
+      credentials,
+      signEndpointOverride: true,
+      now,
+      http,
+      env: {},
+    });
+    expect(calls[0].headers.authorization).toMatch(/Signature=[0-9a-f]{64}$/);
+  });
+
+  test("no credentials leaves the old unsigned path exactly as it was", async () => {
+    const { http, calls } = recording(() => respond(stackXml));
+    await describeStackResources("web", { region: "us-west-1", http, env: {} });
+    expect(calls[0].headers.authorization).toContain("Signature=unsigned");
+    expect(calls[0].headers["x-amz-date"]).toBeUndefined();
+    expect(calls[0].headers["x-amz-content-sha256"]).toBeUndefined();
+  });
+
+  test("the environment is the fallback source, and Cloud Control signs from it too", async () => {
+    const { http, calls } = recording(() => respond(JSON.stringify({ ResourceDescription: {} })));
+    await getResource("AWS::EC2::VPC", "vpc-01", {
+      region: "eu-west-1",
+      now,
+      http,
+      env: { AWS_ACCESS_KEY_ID: "AKIDENV", AWS_SECRET_ACCESS_KEY: "s", AWS_SESSION_TOKEN: "tok" },
+    });
+    expect(calls[0].headers.authorization).toContain("Credential=AKIDENV/20150830/eu-west-1/cloudcontrolapi/");
+    expect(calls[0].headers["x-amz-security-token"]).toBe("tok");
+    expect(calls[0].headers["x-amz-target"]).toBe("CloudApiService.GetResource");
+  });
+
+  test("signing without a named region falls back to the same default the host does", async () => {
+    const { http, calls } = recording(() => respond(stackXml));
+    await describeStackResources("web", { credentials, now, http, env: {} });
+    expect(calls[0].url).toBe("https://cloudformation.us-east-1.amazonaws.com/");
+    expect(calls[0].headers.authorization).toContain("/20150830/us-east-1/cloudformation/aws4_request");
+  });
+});

package/src/api/read-client.ts

@@ -19,12 +19,23 @@
  *
  * ## Signing
  *
- * Requests are unsigned, exactly like `awsApply`'s. That is what makes the
- * emulator-first lanes work with no credential plumbing, and it is the reason
- * this is scoped to the Floci lanes (#1198) rather than announced as a
- * real-cloud read path: real AWS rejects an unsigned request. The CLI path
- * remains available for a signed read until SigV4 lands here.
+ * Requests are signed with SigV4 (#1686) when credentials resolve — see
+ * `./sigv4.ts`, which holds the implementation so that cedar's AVP client can
+ * adopt the same one rather than growing a second. Two cases stay unsigned, and
+ * both are deliberate:
+ *
+ *   - **No credentials.** The caller's existing no-credentials path is
+ *     untouched: the request still goes out carrying only the credential scope
+ *     of {@link regionScope}, which is what the emulator lanes have always
+ *     sent.
+ *   - **An endpoint override.** Floci does not verify signatures, and signing
+ *     against it would mean every local lane suddenly needs credentials to read
+ *     what it just deployed. `signEndpointOverride` opts back in for an
+ *     override that *is* real AWS — a VPC endpoint, a signing proxy.
  */
+import { resolveCredentials, signRequest, type AwsCredentialSource } from "./sigv4";
+
+export type { AwsCredentials, AwsCredentialResolver, AwsCredentialSource } from "./sigv4";
 
 const DEFAULT_REGION = "us-east-1";
 const CFN_API_VERSION = "2010-05-15";
@@ -62,6 +73,18 @@ export interface AwsReadClientOptions {
   region?: string;
   http?: AwsReadHttp;
   signal?: AbortSignal;
+  /**
+   * What to sign with: literal credentials, or a resolver that decides. Omitted,
+   * the environment answers; when it has nothing, the request goes out unsigned
+   * exactly as it did before signing existed.
+   */
+  credentials?: AwsCredentialSource;
+  /** Environment the credential fallback reads. Defaults to `process.env`; injectable for tests. */
+  env?: Record<string, string | undefined>;
+  /** Sign even against an endpoint override — for an override that is real AWS. */
+  signEndpointOverride?: boolean;
+  /** Signing clock. Injected by tests so a signature is reproducible. */
+  now?: Date;
 }
 
 /** Service host for `service`, honouring an endpoint override. */
@@ -84,15 +107,19 @@ export function serviceUrl(service: string, endpoint?: string, region = DEFAULT_
  * an empty observation and the snapshot recorded the region as holding nothing.
  * A three-region estate snapshotted as one region and nothing said so.
  *
- * This is NOT SigV4. The signature is a placeholder and real AWS rejects it —
- * as it already rejects every request from this module, which is unsigned by
- * design (see the header comment). It carries the scope, nothing more, and it
- * must not be mistaken for the signed read path that would replace it.
+ * This is NOT SigV4. The signature is a placeholder and real AWS rejects it. It
+ * is what an unsigned request still has to carry so an emulator learns the
+ * region, and it is only ever sent when no credentials resolved — the moment
+ * they do, {@link requestHeaders} sends a real signature instead.
  */
-function regionScope(service: string, region?: string): Record<string, string> {
+function regionScope(
+  service: string,
+  region: string | undefined,
+  env: Record<string, string | undefined>,
+): Record<string, string> {
   if (!region) return {};
   const day = new Date().toISOString().slice(0, 10).replace(/-/g, "");
-  const key = process.env.AWS_ACCESS_KEY_ID || "chant";
+  const key = env.AWS_ACCESS_KEY_ID || "chant";
   return {
     authorization:
       `AWS4-HMAC-SHA256 Credential=${key}/${day}/${region}/${service}/aws4_request, ` +
@@ -100,6 +127,44 @@ function regionScope(service: string, region?: string): Record<string, string> {
   };
 }
 
+/**
+ * The headers one request goes out with — signed when there is something to
+ * sign with and the target is real AWS, scope-only otherwise.
+ *
+ * Signing needs a region even when the caller named none, because the scope
+ * string has a slot for one; it borrows the same `us-east-1` default that
+ * {@link serviceUrl} already used to build the host, so the signature agrees
+ * with the endpoint it is sent to.
+ *
+ * Exported because this decision — sign, or carry the scope and no signature —
+ * belongs to the lexicon's read transport rather than to any one API on it.
+ * `agentcore/trace-fetch.ts` reads `bedrock-agentcore` through the same seam,
+ * and a second copy of this would be a second place for the emulator carve-out
+ * to drift.
+ */
+export function requestHeaders(
+  service: string,
+  url: string,
+  body: string,
+  base: Record<string, string>,
+  options: AwsReadClientOptions,
+): Record<string, string> {
+  const env = options.env ?? process.env;
+  const credentials = resolveCredentials(options.credentials, env);
+  const signable = credentials && (!options.endpoint || options.signEndpointOverride === true);
+  if (!signable) return { ...base, ...regionScope(service, options.region, env) };
+  return signRequest({
+    method: "POST",
+    url,
+    headers: base,
+    body,
+    service,
+    region: options.region ?? DEFAULT_REGION,
+    credentials,
+    ...(options.now ? { now: options.now } : {}),
+  });
+}
+
 /* ── CloudFormation Query ─────────────────────────────────────────────────── */
 
 /**
@@ -162,10 +227,13 @@ export async function cfnQuery(
   const res = await http(
     url,
     {
-      headers: {
-        "content-type": "application/x-www-form-urlencoded",
-        ...regionScope("cloudformation", options.region),
-      },
+      headers: requestHeaders(
+        "cloudformation",
+        url,
+        body,
+        { "content-type": "application/x-www-form-urlencoded" },
+        options,
+      ),
       body,
     },
     options.signal,
@@ -238,15 +306,21 @@ async function cloudControl(
 ): Promise<Record<string, unknown>> {
   const http = options.http ?? defaultHttp;
   const url = serviceUrl("cloudcontrolapi", options.endpoint, options.region);
+  const payloadJson = JSON.stringify(payload);
   const res = await http(
     url,
     {
-      headers: {
-        "content-type": "application/x-amz-json-1.0",
-        "x-amz-target": `${CLOUD_CONTROL_TARGET_PREFIX}.${operation}`,
-        ...regionScope("cloudcontrolapi", options.region),
-      },
-      body: JSON.stringify(payload),
+      headers: requestHeaders(
+        "cloudcontrolapi",
+        url,
+        payloadJson,
+        {
+          "content-type": "application/x-amz-json-1.0",
+          "x-amz-target": `${CLOUD_CONTROL_TARGET_PREFIX}.${operation}`,
+        },
+        options,
+      ),
+      body: payloadJson,
     },
     options.signal,
   );

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();
+  });
+});