From 641577f1a876660d3c2a019e1226f0862c412965 Mon Sep 17 00:00:00 2001 From: Varun Gunda Date: Fri, 20 Nov 2026 17:39:07 -0800 Subject: [PATCH] fix(gateway): refuse a bound NONE gateway in a Box project, explain a 403 Companion to aws/agentcore-l3-cdk-constructs#476. That change gives each Box gateway a resource policy that lets only its runtime's execution role invoke it. The project schema now refuses authorizerType "NONE" on a gateway with boundRuntime in a Box project. A Box gateway holds its runtime's outbound credentials, and with NONE anyone with its URL could call it. The L3 schema has the same check and the same message. The CLI writes AWS_IAM for each Box gateway, so only a hand edit hits this. `agentcore gateway invoke` now explains an HTTP 403 from an AWS_IAM gateway. The resource policy denies every other principal, so a developer's own credentials get AccessDenied on a Box gateway, even with administrator access. The command line writes the hint to stderr, and the TUI shows it as the note of the failed exchange. --- src/handlers/gateway/invoke/index.tsx | 4 ++- src/handlers/gateway/invoke/invoke.test.tsx | 38 +++++++++++++++++++++ src/handlers/gateway/invoke/response.ts | 18 ++++++++++ src/handlers/gateway/invoke/screen.tsx | 9 ++++- src/projectSchemas/project.test.ts | 21 ++++++++++++ src/projectSchemas/project.ts | 13 +++++++ 6 files changed, 101 insertions(+), 2 deletions(-) diff --git a/src/handlers/gateway/invoke/index.tsx b/src/handlers/gateway/invoke/index.tsx index a025429c67..52a183f3e0 100644 --- a/src/handlers/gateway/invoke/index.tsx +++ b/src/handlers/gateway/invoke/index.tsx @@ -16,7 +16,7 @@ import { resolveGatewayInvokeSources, resolveGatewayInvokeTuiBearerToken, } from "./request"; -import { writeGatewayInvokeResponse } from "./response"; +import { gatewayAccessDeniedHint, writeGatewayInvokeResponse } from "./response"; import { GatewayInvokeLaunchContextKey } from "./launchContext"; export const invokeGatewayFlags = [ @@ -134,6 +134,8 @@ export const createInvokeGatewayHandler = ( beforeOutput, }); if (response.statusCode < 200 || response.statusCode >= 300) { + const hint = gatewayAccessDeniedHint(response.statusCode, gateway.authorizerType); + if (hint) io.stderr.write(`${hint}\n`); throw new GatewayInvokeResponseError(`HTTP ${response.statusCode}`); } }; diff --git a/src/handlers/gateway/invoke/invoke.test.tsx b/src/handlers/gateway/invoke/invoke.test.tsx index 5080809540..a74a25daef 100644 --- a/src/handlers/gateway/invoke/invoke.test.tsx +++ b/src/handlers/gateway/invoke/invoke.test.tsx @@ -316,6 +316,44 @@ describe("gateway invoke", () => { expect(output.stderr()).toHaveLength(0); }); + test("explains an HTTP 403 from an AWS_IAM Gateway", async () => { + const core = configuredCore({ authorizerType: "AWS_IAM" }); + core.gateway.setInvokeResponse({ + statusCode: 403, + contentType: "application/json", + requestId: "request-403", + body: body(Buffer.from('{"message":"AccessDeniedException"}')), + }); + const output = captureIO(); + + const code = await runWithExitCode(async () => + runCommand(core, output.io, ["gateway", "invoke", "--id", GATEWAY_ID, "--payload", "{}"]), + ); + + expect(code).toBe(ExitCode.FAILURE); + expect(output.stderr().toString()).toContain( + "If this is a Box Gateway (bound to one runtime in a Box project), its resource policy " + + "lets only that runtime's execution role invoke it.", + ); + }); + + test("adds no access hint to an HTTP 403 from a Gateway without AWS_IAM", async () => { + const core = configuredCore(); + core.gateway.setInvokeResponse({ + statusCode: 403, + contentType: "application/json", + requestId: "request-403", + body: body(Buffer.from('{"message":"Forbidden"}')), + }); + const output = captureIO(); + + await runWithExitCode(async () => + runCommand(core, output.io, ["gateway", "invoke", "--id", GATEWAY_ID, "--payload", "{}"]), + ); + + expect(output.stderr().toString()).not.toContain("Box Gateway"); + }); + test("streams a non-2xx body before returning a failure exit code", async () => { const core = configuredCore(); core.gateway.setInvokeResponse({ diff --git a/src/handlers/gateway/invoke/response.ts b/src/handlers/gateway/invoke/response.ts index b670d0b24b..c72b56794b 100644 --- a/src/handlers/gateway/invoke/response.ts +++ b/src/handlers/gateway/invoke/response.ts @@ -27,6 +27,24 @@ function summary( ); } +/** + * The hint for an HTTP 403 from an AWS_IAM Gateway. In a Box project, each Box Gateway has a + * resource policy that denies every principal except its runtime's execution role, so even an + * administrator gets AccessDenied. + */ +export function gatewayAccessDeniedHint( + statusCode: number, + authorizerType: string | undefined, +): string | undefined { + if (statusCode !== 403 || authorizerType !== "AWS_IAM") return undefined; + return ( + "Access denied. If this is a Box Gateway (bound to one runtime in a Box project), its " + + "resource policy lets only that runtime's execution role invoke it. Your credentials " + + "cannot invoke it, even with administrator access. Otherwise, check that your " + + "credentials allow bedrock-agentcore:InvokeGateway on this Gateway." + ); +} + export async function writeGatewayInvokeResponse( response: GatewayInvokeResponse, output: StreamingResponseOutput, diff --git a/src/handlers/gateway/invoke/screen.tsx b/src/handlers/gateway/invoke/screen.tsx index ff8af30553..ca842f8322 100644 --- a/src/handlers/gateway/invoke/screen.tsx +++ b/src/handlers/gateway/invoke/screen.tsx @@ -20,6 +20,7 @@ import { coreOptsFromCtx } from "../../utils"; import type { GatewayInvokeRequest, GatewayInvokeResponse } from "../types"; import { GatewayInvokeLaunchContextKey, type GatewayInvokeLaunchContext } from "./launchContext"; import { normalizeGatewayInvokeRequest } from "./request"; +import { gatewayAccessDeniedHint } from "./response"; const theme = darkTheme; const ACCEPT = "application/json, text/event-stream, */*;q=0.1"; @@ -320,7 +321,13 @@ export function GatewayInvokeConsole({ if (response.mcpSessionId) setMcpSessionId(response.mcpSessionId); if (response.mcpProtocolVersion) setMcpProtocolVersion(response.mcpProtocolVersion); updateExchange({ - ...(success ? {} : { note: `HTTP ${response.statusCode}` }), + ...(success + ? {} + : { + note: + gatewayAccessDeniedHint(response.statusCode, detail.data?.authorizerType) ?? + `HTTP ${response.statusCode}`, + }), state: success ? "complete" : "failed", }); } catch (error) { diff --git a/src/projectSchemas/project.test.ts b/src/projectSchemas/project.test.ts index d643bb33db..47f0576de5 100644 --- a/src/projectSchemas/project.test.ts +++ b/src/projectSchemas/project.test.ts @@ -553,6 +553,27 @@ describe("gateway boundRuntime and discoveryPrefix", () => { test.each(["my-prefix", "", "1BOX"])("rejects discoveryPrefix %j", (discoveryPrefix) => { expect(parse({ boundRuntime: "agent", discoveryPrefix }).success).toBe(false); }); + + test("rejects a bound NONE gateway in a Box project, and accepts one outside it", () => { + const spec = (projectType?: string) => ({ + ...minimalProject, + ...(projectType && { projectType }), + runtimes: [runtime], + agentCoreGateways: [gateway({ boundRuntime: "agent", authorizerType: "NONE" })], + }); + const box = ProjectSpecSchema.safeParse(spec("box")); + expect(box.success).toBe(false); + expect(box.error?.issues.map(({ message }) => message)).toContain( + 'Gateway "agent-box-egress" has boundRuntime "agent" in a Box project and authorizerType "NONE". Anyone with its URL could call it and use its credentials. Use "AWS_IAM".', + ); + expect(ProjectSpecSchema.safeParse(spec()).success).toBe(true); + expect( + ProjectSpecSchema.safeParse({ + ...spec("box"), + agentCoreGateways: [gateway({ boundRuntime: "agent" })], + }).success, + ).toBe(true); + }); }); describe("Box project gateways", () => { diff --git a/src/projectSchemas/project.ts b/src/projectSchemas/project.ts index d0c4724226..4a27b74db2 100644 --- a/src/projectSchemas/project.ts +++ b/src/projectSchemas/project.ts @@ -160,6 +160,19 @@ export const ProjectSpecSchema = z path: ["agentCoreGateways"], }); } + // A Box gateway holds its runtime's outbound credentials. With NONE, anyone who has its URL + // can call it and use them. The L3 schema has the same check. + if ( + isBoxProject(spec) && + gateway.boundRuntime !== undefined && + gateway.authorizerType === "NONE" + ) { + ctx.addIssue({ + code: "custom", + message: `Gateway "${gateway.name}" has boundRuntime "${gateway.boundRuntime}" in a Box project and authorizerType "NONE". Anyone with its URL could call it and use its credentials. Use "AWS_IAM".`, + path: ["agentCoreGateways"], + }); + } } // A Box project keeps one Box gateway for each runtime. Without it, a deploy would delete the // deployed gateway, so every command stops here and prints the entry to add back.