@intentius/chant-lexicon-aws 0.44.13 → 0.45.0

package/src/agentcore/trace-fetch.ts

@@ -68,6 +68,9 @@
  * endpoint override, since an emulator does not verify signatures and requiring
  * credentials to read a local lane would be a tax with nothing behind it.
  * `signEndpointOverride: true` opts back in for an override that *is* real AWS.
+ * What counts as an override is read-client's `resolveEndpointOverride` rule —
+ * the `endpoint` option, else `AWS_ENDPOINT_URL_BEDROCK_AGENTCORE`, else
+ * `AWS_ENDPOINT_URL` (#1694).
  */
 
 import { mkdir, writeFile } from "node:fs/promises";
@@ -76,6 +79,7 @@ import {
   AwsReadError,
   requestHeaders,
   serviceUrl,
+  withEndpointOverride,
   type AwsCredentialSource,
   type AwsReadHttp,
 } from "../api/read-client";
@@ -506,7 +510,7 @@ const defaultHttp: AwsReadHttp = async (url, init, signal) => {
 
 /** Where to read from, how to reach it, and what to sign with. */
 export interface AgentCoreReadOptions {
-  /** Endpoint override. Omit for the real regional host. */
+  /** Endpoint override. Omitted, `AWS_ENDPOINT_URL[_BEDROCK_AGENTCORE]` answers; with neither, the real regional host. */
   readonly endpoint?: string;
   /** Default `us-east-1`. */
   readonly region?: string;
@@ -527,10 +531,11 @@ export interface AgentCoreReadOptions {
 async function agentCorePost(
   path: string,
   body: Record<string, unknown>,
-  options: AgentCoreReadOptions,
+  readOptions: AgentCoreReadOptions,
   http: AwsReadHttp,
   signal?: AbortSignal,
 ): Promise<Record<string, unknown>> {
+  const options = withEndpointOverride(SERVICE, readOptions);
   const url = `${serviceUrl(SERVICE, options.endpoint, options.region)}${path.replace(/^\//, "")}`;
   const wire = JSON.stringify(body);
   const res = await http(

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

@@ -13,6 +13,8 @@ import {
   getResource,
   listResources,
   parseResourceDescription,
+  resolveEndpointOverride,
+  serviceEndpointEnvVar,
   serviceUrl,
   xmlLeaves,
   xmlMembers,
@@ -315,3 +317,88 @@ describe("SigV4 on the read path", () => {
     expect(calls[0].headers.authorization).toContain("/20150830/us-east-1/cloudformation/aws4_request");
   });
 });
+
+describe("what counts as an endpoint override (#1694)", () => {
+  const credentials = { accessKeyId: "AKIDEXAMPLE", secretAccessKey: "wJalrXUtnFEMI/K7MDENG+bPxRfiCYEXAMPLEKEY" };
+  const now = new Date("2015-08-30T12:36:00Z");
+
+  test("the option, then the service variable, then AWS_ENDPOINT_URL — the SDK's precedence", () => {
+    const env = { AWS_ENDPOINT_URL: "http://all:1", AWS_ENDPOINT_URL_CLOUDFORMATION: "http://cfn:2" };
+    expect(resolveEndpointOverride("cloudformation", "http://opt:3", env)).toBe("http://opt:3");
+    expect(resolveEndpointOverride("cloudformation", undefined, env)).toBe("http://cfn:2");
+    expect(resolveEndpointOverride("cloudcontrolapi", undefined, env)).toBe("http://all:1");
+    expect(resolveEndpointOverride("cloudformation", undefined, {})).toBeUndefined();
+    expect(resolveEndpointOverride("cloudformation", "", { AWS_ENDPOINT_URL: "" })).toBeUndefined();
+  });
+
+  test("the service variable is named by the SDK's service id, not the signing name", () => {
+    expect(serviceEndpointEnvVar("cloudformation")).toBe("AWS_ENDPOINT_URL_CLOUDFORMATION");
+    expect(serviceEndpointEnvVar("cloudcontrolapi")).toBe("AWS_ENDPOINT_URL_CLOUDCONTROL");
+    expect(serviceEndpointEnvVar("bedrock-agentcore")).toBe("AWS_ENDPOINT_URL_BEDROCK_AGENTCORE");
+  });
+
+  test("AWS_ENDPOINT_URL alone retargets the request and leaves it unsigned, like the option", async () => {
+    const { http, calls } = recording(() => respond(stackXml));
+    await describeStackResources("web", {
+      region: "us-west-1",
+      credentials,
+      http,
+      env: { AWS_ENDPOINT_URL: "http://localhost:4566" },
+    });
+    expect(calls[0].url).toBe("http://localhost:4566/");
+    expect(calls[0].headers.authorization).toContain("Signature=unsigned");
+    expect(calls[0].headers["x-amz-date"]).toBeUndefined();
+  });
+
+  test("the service-specific variable does the same, for Cloud Control too", async () => {
+    const { http, calls } = recording(() => respond(JSON.stringify({ ResourceDescription: {} })));
+    await getResource("AWS::EC2::VPC", "vpc-01", {
+      region: "eu-west-1",
+      credentials,
+      http,
+      env: { AWS_ENDPOINT_URL_CLOUDCONTROL: "http://localhost:4566" },
+    });
+    expect(calls[0].url).toBe("http://localhost:4566/");
+    expect(calls[0].headers.authorization).toContain("Signature=unsigned");
+  });
+
+  test("the option is the same override — same target, same unsigned headers", async () => {
+    const viaEnv = recording(() => respond(stackXml));
+    const viaOption = recording(() => respond(stackXml));
+    await describeStackResources("web", {
+      region: "us-west-1",
+      credentials,
+      http: viaEnv.http,
+      env: { AWS_ENDPOINT_URL: "http://localhost:4566" },
+    });
+    await describeStackResources("web", {
+      endpoint: "http://localhost:4566",
+      region: "us-west-1",
+      credentials,
+      http: viaOption.http,
+      env: {},
+    });
+    expect(viaOption.calls[0]).toEqual(viaEnv.calls[0]);
+  });
+
+  test("signEndpointOverride signs against an override the environment named", async () => {
+    const { http, calls } = recording(() => respond(stackXml));
+    await describeStackResources("web", {
+      region: "us-west-1",
+      credentials,
+      signEndpointOverride: true,
+      now,
+      http,
+      env: { AWS_ENDPOINT_URL: "https://vpce-1234.cloudformation.us-west-1.vpce.amazonaws.com" },
+    });
+    expect(calls[0].url).toBe("https://vpce-1234.cloudformation.us-west-1.vpce.amazonaws.com/");
+    expect(calls[0].headers.authorization).toMatch(/Signature=[0-9a-f]{64}$/);
+  });
+
+  test("neither option nor variable: the real regional host, signed", async () => {
+    const { http, calls } = recording(() => respond(stackXml));
+    await describeStackResources("web", { region: "us-west-1", credentials, now, http, env: {} });
+    expect(calls[0].url).toBe("https://cloudformation.us-west-1.amazonaws.com/");
+    expect(calls[0].headers.authorization).toMatch(/Signature=[0-9a-f]{64}$/);
+  });
+});

package/src/api/read-client.ts

@@ -32,6 +32,14 @@
  *     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.
+ *
+ * What counts as an override is one rule, {@link resolveEndpointOverride}: the
+ * `endpoint` option, else the ambient `AWS_ENDPOINT_URL_<SERVICE>` the AWS SDK
+ * honours per service, else `AWS_ENDPOINT_URL` (#1694). Cedar's AVP client
+ * (`lexicons/cedar/src/avp/client.ts`) applies the same rule; it restates it
+ * rather than importing it, because cedar does not depend on this lexicon and
+ * a lexicon build compiles against the published core, so a helper hoisted
+ * into core would not be visible to either until the next core release.
  */
 import { resolveCredentials, signRequest, type AwsCredentialSource } from "./sigv4";
 
@@ -67,7 +75,11 @@ export class AwsReadError extends Error {
 }
 
 export interface AwsReadClientOptions {
-  /** Endpoint override (Floci `http://localhost:4566`). Omit for real AWS hosts. */
+  /**
+   * Endpoint override (Floci `http://localhost:4566`). Omitted, the environment
+   * answers through {@link resolveEndpointOverride}; when it names nothing
+   * either, the target is the real AWS host.
+   */
   endpoint?: string;
   /** Region for the real-AWS host and the Query `Version` context. */
   region?: string;
@@ -87,6 +99,45 @@ export interface AwsReadClientOptions {
   now?: Date;
 }
 
+/**
+ * The SDK's per-service endpoint variable for a signing-service name:
+ * `AWS_ENDPOINT_URL_<SERVICE ID>`, the service id upper-cased with every
+ * non-alphanumeric run replaced by `_`. The SDK keys that by the service id of
+ * its model, which is the signing name for every service here except Cloud
+ * Control (`cloudcontrolapi` signs, `CloudControl` is the id).
+ */
+const ENV_SERVICE_ID: Record<string, string> = { cloudcontrolapi: "cloudcontrol" };
+
+/** The name of the service-specific endpoint variable the AWS SDK reads for `service`. */
+export function serviceEndpointEnvVar(service: string): string {
+  const id = ENV_SERVICE_ID[service] ?? service;
+  return `AWS_ENDPOINT_URL_${id.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}`;
+}
+
+/**
+ * The one rule for what an endpoint override is (#1694): the `endpoint` option
+ * when given, else the service-specific `AWS_ENDPOINT_URL_<SERVICE>`, else the
+ * ambient `AWS_ENDPOINT_URL` — the same precedence the AWS SDK applies. The
+ * result is the target the request goes to and, through {@link requestHeaders},
+ * the fact that decides whether it is signed. Returns `undefined` for real AWS.
+ */
+export function resolveEndpointOverride(
+  service: string,
+  endpoint: string | undefined,
+  env: Record<string, string | undefined> = process.env,
+): string | undefined {
+  return endpoint || env[serviceEndpointEnvVar(service)] || env.AWS_ENDPOINT_URL || undefined;
+}
+
+/**
+ * `options` with its endpoint settled by {@link resolveEndpointOverride}, so
+ * the URL builder and the signing decision read the same answer.
+ */
+export function withEndpointOverride(service: string, options: AwsReadClientOptions): AwsReadClientOptions {
+  const endpoint = resolveEndpointOverride(service, options.endpoint, options.env ?? process.env);
+  return endpoint ? { ...options, endpoint } : options;
+}
+
 /** Service host for `service`, honouring an endpoint override. */
 export function serviceUrl(service: string, endpoint?: string, region = DEFAULT_REGION): string {
   return `${(endpoint ?? `https://${service}.${region}.amazonaws.com`).replace(/\/$/, "")}/`;
@@ -141,6 +192,9 @@ function regionScope(
  * `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.
+ *
+ * Callers pass options already settled by {@link withEndpointOverride}, so an
+ * override the environment named is skipped exactly like one the option did.
  */
 export function requestHeaders(
   service: string,
@@ -221,6 +275,7 @@ export async function cfnQuery(
   params: Record<string, string>,
   options: AwsReadClientOptions = {},
 ): Promise<string> {
+  options = withEndpointOverride("cloudformation", options);
   const http = options.http ?? defaultHttp;
   const url = serviceUrl("cloudformation", options.endpoint, options.region);
   const body = new URLSearchParams({ Action: action, Version: CFN_API_VERSION, ...params }).toString();
@@ -304,6 +359,7 @@ async function cloudControl(
   payload: Record<string, unknown>,
   options: AwsReadClientOptions = {},
 ): Promise<Record<string, unknown>> {
+  options = withEndpointOverride("cloudcontrolapi", options);
   const http = options.http ?? defaultHttp;
   const url = serviceUrl("cloudcontrolapi", options.endpoint, options.region);
   const payloadJson = JSON.stringify(payload);

package/src/codegen/docs-links.test.ts

@@ -4,6 +4,18 @@ import { join, basename } from "path";
 
 const docsDir = join(import.meta.dirname, "..", "..", "docs", "src", "content", "docs");
 const docsSource = join(import.meta.dirname, "docs.ts");
+const pagesDir = join(import.meta.dirname, "..", "..", "docs", "pages");
+
+/** Authored prose lives in docs/pages/ (chant #1731); docs.ts keeps only the overview strings. */
+function authoredSources(): Array<{ name: string; path: string }> {
+  const sources = [{ name: "docs.ts", path: docsSource }];
+  if (existsSync(pagesDir)) {
+    for (const file of readdirSync(pagesDir).sort()) {
+      if (file.endsWith(".mdx")) sources.push({ name: `docs/pages/${file}`, path: join(pagesDir, file) });
+    }
+  }
+  return sources;
+}
 const docsExist = existsSync(docsDir);
 
 /**
@@ -108,36 +120,38 @@ describe("docs internal links", () => {
     });
   }
 
-  // Validate source docs.ts — catches broken links before regeneration
-  test("docs.ts source — cross-page links use ../ not ./", () => {
-    if (!docsExist) return; // needs generated slugs for validation
-    const content = readFileSync(docsSource, "utf-8");
-    const links = extractMarkdownLinks(content);
-    const errors: string[] = [];
-    for (const link of links) {
-      const pathPart = link.href.split("#")[0];
-      // Links in docs.ts extraPages are rendered on non-index pages,
-      // so they must use ../ to navigate to sibling pages
-      if (pathPart.startsWith("./") && slugs.has(pathPart.slice(2).replace(/\/$/, ""))) {
-        errors.push(`line ${link.line}: [${link.text}](${link.href}) — use "../" prefix for cross-page links`);
+  // Validate the authored sources — docs.ts and docs/pages/*.mdx — so a
+  // broken link is caught before regeneration.
+  for (const source of authoredSources()) {
+    test(`${source.name} — cross-page links use ../ not ./`, () => {
+      if (!docsExist) return; // needs generated slugs for validation
+      const content = readFileSync(source.path, "utf-8");
+      const links = extractMarkdownLinks(content);
+      const errors: string[] = [];
+      for (const link of links) {
+        const pathPart = link.href.split("#")[0];
+        // Authored pages render as non-index pages, so sibling links must use ../
+        if (pathPart.startsWith("./") && slugs.has(pathPart.slice(2).replace(/\/$/, ""))) {
+          errors.push(`line ${link.line}: [${link.text}](${link.href}) — use "../" prefix for cross-page links`);
+        }
       }
-    }
-    if (errors.length > 0) {
-      throw new Error(`docs.ts has ./ links that will break on non-index pages:\n${errors.join("\n")}`);
-    }
-  });
+      if (errors.length > 0) {
+        throw new Error(`${source.name} has ./ links that will break on non-index pages:\n${errors.join("\n")}`);
+      }
+    });
 
-  test("docs.ts source — link targets exist as pages", () => {
-    if (!docsExist) return; // needs generated slugs for validation
-    const content = readFileSync(docsSource, "utf-8");
-    const links = extractMarkdownLinks(content);
-    const errors: string[] = [];
-    for (const link of links) {
-      const error = resolveTarget(link.href, slugs);
-      if (error) errors.push(`line ${link.line}: [${link.text}](${link.href}) — ${error}`);
-    }
-    if (errors.length > 0) {
-      throw new Error(`docs.ts has links to non-existent pages:\n${errors.join("\n")}`);
-    }
-  });
+    test(`${source.name} — link targets exist as pages`, () => {
+      if (!docsExist) return; // needs generated slugs for validation
+      const content = readFileSync(source.path, "utf-8");
+      const links = extractMarkdownLinks(content);
+      const errors: string[] = [];
+      for (const link of links) {
+        const error = resolveTarget(link.href, slugs);
+        if (error) errors.push(`line ${link.line}: [${link.text}](${link.href}) — ${error}`);
+      }
+      if (errors.length > 0) {
+        throw new Error(`${source.name} has links to non-existent pages:\n${errors.join("\n")}`);
+      }
+    });
+  }
 });