diff --git a/README.md b/README.md index 65dab78c2..61a939a02 100644 --- a/README.md +++ b/README.md @@ -75,7 +75,10 @@ flags: for templates that take a model provider (`agent-python-strands` and its variant, `a2a-python-strands`, `agui-python-strands`, `agent-typescript-strands`) the wizard asks for the provider (Amazon Bedrock, Anthropic, OpenAI, an OpenAI-compatible endpoint, Gemini, or LiteLLM, which is Python-only), the model id, and an API-key file. The API key is kept in -`agentcore/.env.local` and provisioned as an AgentCore Identity credential on deploy. +`agentcore/.env.local` and provisioned as an AgentCore Identity credential on deploy. For a Box +template created with no API key, build reads the provider's key (such as `OPENAI_API_KEY`) from +your shell or `agentcore/.env.local`, adds a credential such as `openai`, and deploy provisions +that key in AgentCore Identity. To bring your own code into a project instead, add a runtime for it: diff --git a/docs/box-local-testing.md b/docs/box-local-testing.md index 5b147d5fb..5ebfc8c79 100644 --- a/docs/box-local-testing.md +++ b/docs/box-local-testing.md @@ -206,15 +206,29 @@ build context, and write a copy of the profile, the generated packs, and the pol Box `0.1.11-linux-preview.7` names its packs `@box/base`, `@box/bedrock`, and `@box/agentcore`. A profile that names a pack `box/` fails: box refuses it and names the `@box/` pack. -- **Gateway targets.** Each host or `host:port` that an `[egress]` entry, an `[mcp]` server - with `type = "http"`, or a policy permit names, and that the policy allows at least one - request to, gets one passthrough target on `-box-egress`. The target of an MCP server is +- **Gateway targets.** Each host or `host:port` that an `[egress]` entry, an `[mcp]` server with + `type = "http"`, or a policy permit names, and that the policy allows at least one request to, + gets one passthrough target on `-box-egress`. The target of an MCP server is `egress-`. Its `protocolType` is `CUSTOM`, thus only Box makes the decision on each - `mcp:call`. A host the gateway already has a target for keeps that target. Build owns - only the targets whose name starts with `egress-`: it adds them, changes them, and removes - one when no host needs it. It never changes another target. + `mcp:call`. A host the gateway already has a target for keeps that target. Build owns only the + targets it wrote, which it lists in `agentcore/box-gateway-targets.json`: it adds them, changes + them, and removes one when no host needs it. It never changes another target, also one whose name + starts with `egress-`. `agentcore create` and `agentcore add runtime` write an empty entry for + each new Box gateway, so build owns none of its targets until it writes one. For a gateway that + the file does not list, which an older CLI made, build takes each `egress-` target that has the + shape it writes as its own, once, and warns for each other `egress-` target, which it keeps as + yours. Commit `agentcore/box-gateway-targets.json` with `agentcore.json`: in a clone without it, + build goes back to that `egress-` rule, and can take or give up the wrong targets. The + `.gitignore` that `agentcore create` writes does not exclude it. Build writes the file, but you + edit it in one case: when you change a target that build wrote, build stops and tells you to + remove that target's name from the file to keep the target as yours. Then build no longer records, + changes, or removes it. - **Outbound auth.** An `aws://` secret signs with the gateway's role, an `env://` secret sends an API key from AgentCore Identity, and an entry with no secret sends no credential. + This includes the model-provider route that `agentcore create` writes when you give it no key, + such as `[egress.openai]` with `env://OPENAI_API_KEY` (also for Anthropic and Gemini). When that + key is set in your shell or in `agentcore/.env.local`, build adds an API key credential such as + `openai`, and deploy provisions your key in AgentCore Identity. - **Failures.** A profile Box refuses stops build and deploy with box's own error. A wildcard host, a plain-HTTP-only host, an unsupported secret, an MCP server that names more than one host, a path, or a port other than 443, and similar cases stop them too. The error starts with `Build stopped:` or `Deploy stopped:` and the diff --git a/src/core/project/backends/boxCodeZip.test.ts b/src/core/project/backends/boxCodeZip.test.ts index 5ea9460a3..ba6bd2c9e 100644 --- a/src/core/project/backends/boxCodeZip.test.ts +++ b/src/core/project/backends/boxCodeZip.test.ts @@ -251,6 +251,7 @@ function model(policyFiles: string[], runtime = "agent"): BoxNetwork { region: "us-west-2", hosts: [], envRoutes: [], + managedTargets: new Set(), policyFiles, runtimeProfile: runtimeProfileOf(policyFiles, runtime), runtimeProfileHeader: [`Derived from .box/${runtime}/local/profile.toml.`], diff --git a/src/core/project/backends/boxCodeZip.ts b/src/core/project/backends/boxCodeZip.ts index 2f2e7b7a7..d1108005c 100644 --- a/src/core/project/backends/boxCodeZip.ts +++ b/src/core/project/backends/boxCodeZip.ts @@ -2,14 +2,9 @@ import { chmodSync, copyFileSync, cpSync, mkdirSync, rmSync, writeFileSync } fro import { join, posix } from "node:path"; import type { Project } from "../../../handlers/project/types"; import type { BoxNetwork } from "../boxNetwork"; -import { - boxNetworkEdits, - runtimeProfileWriter, - writeBoxNetworkFiles, - writeRenderedBoxFiles, -} from "../boxNetworkWriters"; import { BOX_CODEZIP_DIST, runtimeRunsInBox } from "../templates/boxProfile"; import { BOX_BINARIES, type BoxLinuxBuild } from "./boxRelease"; +import { stagedRuntimeProfiles } from "./boxStaging"; /** The `.gitignore` staged into `.box-dist/`: build and deploy rewrite the folder every time. */ export const BOX_DIST_GITIGNORE = @@ -40,13 +35,7 @@ export async function stageBoxCodeZip( // @box/agentcore and @box/agentcore-codezip packs. kind: "codezip" as const, })); - const { files } = boxNetworkEdits([runtimeProfileWriter(staged)], networks, { - spec: project.spec, - projectRoot: project.rootPath, - env: {}, - envLocal: {}, - }); - const filesOf = (dist: string) => files.filter(({ path }) => path.startsWith(`${dist}/`)); + const writeProfile = stagedRuntimeProfiles(project, networks, staged); // One build for each box version the runtimes name, so each downloads once. const builds = new Map(); for (const runtime of runtimes) { @@ -54,7 +43,8 @@ export async function stageBoxCodeZip( if (!builds.has(version)) builds.set(version, await box(version)); } - for (const { runtime, dist } of staged) { + for (const stage of staged) { + const { runtime, dist } = stage; const entry = runtimes.find(({ name }) => name === runtime)!; const build = builds.get(entry.box?.version)!; const folder = join(project.rootPath, ...dist.split("/")); @@ -68,8 +58,7 @@ export async function stageBoxCodeZip( chmodSync(join(folder, binary), 0o755); } cpSync(build.resources, join(folder, "resources"), { recursive: true }); - writeBoxNetworkFiles(project.rootPath, filesOf(dist)); - writeRenderedBoxFiles(project.rootPath, runtime, dist, filesOf(dist)); + writeProfile(stage); } return runtimes.map((runtime) => runtime.name); } diff --git a/src/core/project/backends/boxContainer.test.ts b/src/core/project/backends/boxContainer.test.ts index 834de51ad..d61b39836 100644 --- a/src/core/project/backends/boxContainer.test.ts +++ b/src/core/project/backends/boxContainer.test.ts @@ -176,6 +176,7 @@ function model(policyFiles: string[]): BoxNetwork { region: "us-west-2", hosts: [], envRoutes: [], + managedTargets: new Set(), policyFiles, runtimeProfile: { packs: ["@box/base", "@box/agentcore"], diff --git a/src/core/project/backends/boxContainer.ts b/src/core/project/backends/boxContainer.ts index 800769361..1ae29ffc2 100644 --- a/src/core/project/backends/boxContainer.ts +++ b/src/core/project/backends/boxContainer.ts @@ -4,16 +4,10 @@ import { dirname, join, posix } from "node:path"; import type { Project } from "../../../handlers/project/types"; import type { ProjectRuntime } from "../../../projectSchemas/runtime"; import type { BoxNetwork } from "../boxNetwork"; -import { - boxNetworkEdits, - runtimeProfileWriter, - writeBoxNetworkFiles, - writeRenderedBoxFiles, -} from "../boxNetworkWriters"; import { isFile } from "../runtimeBuild"; import { runtimeRunsInBox } from "../templates/boxProfile"; import type { BoxRelease } from "./boxRelease"; -import { assertImageCopiesPolicyFiles } from "./boxStaging"; +import { assertImageCopiesPolicyFiles, stagedRuntimeProfiles } from "./boxStaging"; /** The folder a box image's Dockerfile copies its box profile and policy files from. */ export const BOX_IMAGE_DIST = ".box-dist"; @@ -130,13 +124,7 @@ export async function stageBoxContainers( dist: posix.join(runtime.buildContextPath ?? runtime.codeLocation, BOX_IMAGE_DIST), kind: "container" as const, })); - const { files } = boxNetworkEdits([runtimeProfileWriter(staged)], networks, { - spec: project.spec, - projectRoot: project.rootPath, - env: {}, - envLocal: {}, - }); - const filesOf = (dist: string) => files.filter(({ path }) => path.startsWith(`${dist}/`)); + const writeProfile = stagedRuntimeProfiles(project, networks, staged); for (const runtime of runtimes) { const policyFiles = networks.find((n) => n.runtime === runtime.name)?.policyFiles ?? []; assertImageCopiesPolicyFiles( @@ -145,15 +133,14 @@ export async function stageBoxContainers( policyFiles, ); } - for (const [index, { dist }] of staged.entries()) { + for (const [index, stage] of staged.entries()) { const runtime = runtimes[index]!; - const folder = join(project.rootPath, ...dist.split("/")); + const folder = join(project.rootPath, ...stage.dist.split("/")); await rm(folder, { recursive: true, force: true }); await mkdir(folder, { recursive: true }); const release = await releaseFor(runtime.box?.version); await writeFile(join(folder, BOX_RELEASE_ENV), boxReleaseEnv(release)); - writeBoxNetworkFiles(project.rootPath, filesOf(dist)); - writeRenderedBoxFiles(project.rootPath, runtime.name, dist, filesOf(dist)); + writeProfile(stage); } return runtimes.map((runtime) => runtime.name); } diff --git a/src/core/project/backends/boxStaging.ts b/src/core/project/backends/boxStaging.ts index 250d191eb..0e2162a34 100644 --- a/src/core/project/backends/boxStaging.ts +++ b/src/core/project/backends/boxStaging.ts @@ -1,7 +1,39 @@ import { readFileSync } from "node:fs"; import { ProjectStateError } from "../../../errors/errors"; +import type { Project } from "../../../handlers/project/types"; +import type { BoxNetwork } from "../boxNetwork"; +import { + boxNetworkEdits, + runtimeProfileWriter, + writeBoxNetworkFiles, + writeRenderedBoxFiles, + type StagedRuntime, +} from "../boxNetworkWriters"; import { boxLocalProfileFile } from "../templates/boxProfile"; +/** + * What the runtime profile writer writes from each runtime's Box network model for the runtimes of + * `staged`, with the function that writes one runtime's files into its staged folder and a copy + * into its `.box//aws/`. + */ +export function stagedRuntimeProfiles( + project: Project, + networks: readonly BoxNetwork[], + staged: readonly StagedRuntime[], +): (runtime: StagedRuntime) => void { + const { files } = boxNetworkEdits([runtimeProfileWriter(staged)], networks, { + spec: project.spec, + projectRoot: project.rootPath, + env: {}, + envLocal: {}, + }); + return ({ runtime, dist }) => { + const own = files.filter(({ path }) => path.startsWith(`${dist}/`)); + writeBoxNetworkFiles(project.rootPath, own); + writeRenderedBoxFiles(project.rootPath, runtime, dist, own); + }; +} + /** A `COPY` of the whole staged folder, which takes the policy files in with the profile. */ const COPIES_WHOLE_DIST = /^\s*COPY\s+(?:--\S+\s+)*(?:\.box-dist|\$\{BOX_DIST\})\/?\s/m; diff --git a/src/core/project/backends/cdk.test.ts b/src/core/project/backends/cdk.test.ts index 9a28b88ca..beef77371 100644 --- a/src/core/project/backends/cdk.test.ts +++ b/src/core/project/backends/cdk.test.ts @@ -341,6 +341,7 @@ describe("CdkBackend.build", () => { region: "us-west-2", hosts: [], envRoutes: [], + managedTargets: new Set(), policyFiles: [], runtimeProfile, grantedActions: [], diff --git a/src/core/project/boxGatewayTargets.ts b/src/core/project/boxGatewayTargets.ts new file mode 100644 index 000000000..2a1315f40 --- /dev/null +++ b/src/core/project/boxGatewayTargets.ts @@ -0,0 +1,121 @@ +/** + * The record of the targets that build writes for each Box gateway, by the gateway's name. Build + * owns those targets, and no other. `agentcore create` and `agentcore add runtime` write an empty + * entry for each new Box gateway, so the `egress-` rule applies only to a gateway an older CLI made. + */ +import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { z } from "zod"; +import { ProjectStateError } from "../../errors/errors"; + +/** The record's name in the `agentcore/` folder. */ +export const BOX_GATEWAY_TARGETS_NAME = "box-gateway-targets.json"; + +/** The record's path from the project root. */ +export const BOX_GATEWAY_TARGETS_FILE = `agentcore/${BOX_GATEWAY_TARGETS_NAME}`; + +const BoxGatewayTargetsSchema = z.record(z.string(), z.array(z.string())); + +/** The record as a file holds it. */ +export function boxGatewayTargetsText(record: Readonly>): string { + return `${JSON.stringify(record, undefined, 2)}\n`; +} + +/** + * The targets build wrote for each Box gateway, or `undefined` when the project has no record. + * Throws for a file that is not the record. + */ +export function readBoxGatewayTargets(projectRoot: string): Record | undefined { + const path = join(projectRoot, ...BOX_GATEWAY_TARGETS_FILE.split("/")); + if (!existsSync(path)) return undefined; + let document: unknown; + try { + document = JSON.parse(readFileSync(path, "utf8")); + } catch { + document = undefined; + } + const record = BoxGatewayTargetsSchema.safeParse(document); + if (record.success) return record.data; + throw new ProjectStateError( + `${BOX_GATEWAY_TARGETS_FILE} is not the record of the gateway targets that build writes: a ` + + "JSON object with a list of target names for each Box gateway. Remove the file, and build " + + "writes it again.", + ); +} + +/** Puts the record back as it was before a change: its old text, or no file. */ +export type RestoreRecord = () => void; + +/** How the record file is written and removed. */ +export interface RecordFiles { + readonly write: (path: string, text: string) => void; + readonly remove: (path: string) => void; +} + +/** The record file on disk. */ +export const FS_RECORD_FILES: RecordFiles = { + write: (path, text) => writeFileSync(path, text), + remove: (path) => rmSync(path, { force: true }), +}; + +/** + * Adds an empty entry for each of `gateways` that the record does not name yet. Returns the + * function that puts the record back, when it wrote the record; it leaves a file that is not the + * record to build, which refuses it. + */ +export function addBoxGatewaysToRecord( + projectRoot: string, + gateways: readonly string[], + files: RecordFiles = FS_RECORD_FILES, +): RestoreRecord | undefined { + return changeRecord(projectRoot, files, (record) => { + const added = gateways.filter((gateway) => !Object.hasOwn(record ?? {}, gateway)); + if (added.length === 0) return undefined; + return { ...record, ...Object.fromEntries(added.map((gateway) => [gateway, []])) }; + }); +} + +/** + * Removes the entry of each of `gateways` from the record, when the record names it. Returns the + * function that puts the record back, when it wrote the record; it leaves a file that is not the + * record to build, which refuses it. + */ +export function removeBoxGatewaysFromRecord( + projectRoot: string, + gateways: readonly string[], + files: RecordFiles = FS_RECORD_FILES, +): RestoreRecord | undefined { + return changeRecord(projectRoot, files, (record) => { + if (!record || !gateways.some((gateway) => Object.hasOwn(record, gateway))) return undefined; + return Object.fromEntries( + Object.entries(record).filter(([gateway]) => !gateways.includes(gateway)), + ); + }); +} + +/** + * Writes the record that `change` makes of the record, or of no record; `undefined` from `change` + * writes nothing. Returns the function that puts the old text back, or removes the file. + */ +function changeRecord( + projectRoot: string, + files: RecordFiles, + change: (record: Record | undefined) => Record | undefined, +): RestoreRecord | undefined { + let record: Record | undefined; + try { + record = readBoxGatewayTargets(projectRoot); + } catch (error) { + if (error instanceof ProjectStateError) return undefined; + throw error; + } + const changed = change(record); + if (changed === undefined) return undefined; + const path = join(projectRoot, ...BOX_GATEWAY_TARGETS_FILE.split("/")); + const before = record === undefined ? undefined : readFileSync(path, "utf8"); + files.write(path, boxGatewayTargetsText(changed)); + return () => { + if (before === undefined) files.remove(path); + else files.write(path, before); + }; +} diff --git a/src/core/project/boxNetwork/conditions.ts b/src/core/project/boxNetwork/conditions.ts index e21245ce0..dfbf6fef5 100644 --- a/src/core/project/boxNetwork/conditions.ts +++ b/src/core/project/boxNetwork/conditions.ts @@ -123,8 +123,13 @@ export function clausesFor(statement: Statement, action: NetworkAction): ClauseS const parts: Formula[] = [ scopeFormula(statement.principal, "principal", SELF), scopeFormula(statement.resource, "resource", UNUSED_RESOURCE), - ...statement.conditions.map((condition) => conditionFormula(condition, action)), ]; + for (const condition of statement.conditions) { + parts.push(conditionFormula(condition, action)); + // Box does not read a condition after one that an action test makes false. + if (condition.body.kind !== "cedar") continue; + if (actionValue(condition.body.expr, action) === (condition.polarity !== "when")) break; + } const clauses: Clause[] = []; const dead: DeadCause[] = []; for (const atoms of disjunctiveNormalForm({ kind: "and", items: parts }, false)) { @@ -246,16 +251,65 @@ function attributePath(expr: Expr): string[] | undefined { return undefined; } -/** Refuses an attribute the action's context does not declare, as Box refuses it at load. */ +/** + * Refuses an attribute the action's context does not declare, as Box refuses it at load. As Box + * reads a rule, an operand that an action test keeps from the action is not read: the right of + * `||` after a test that holds, the right of `&&` after one that does not, and the other branch of + * `if`. + */ function checkAttributes(expr: Expr, action: NetworkAction): void { const path = attributePath(expr); if (path && path.length > 1) { checkPath(path, action, expr.text); return; } + if (expr.kind === "and" || expr.kind === "or") { + for (const item of expr.items) { + checkAttributes(item, action); + if (actionValue(item, action) === (expr.kind === "or")) return; + } + return; + } + if (expr.kind === "if") { + checkAttributes(expr.test, action); + const test = actionValue(expr.test, action); + if (test !== false) checkAttributes(expr.then, action); + if (test !== true) checkAttributes(expr.otherwise, action); + return; + } for (const child of children(expr)) checkAttributes(child, action); } +/** The value of `expr` on `action` when only action tests and constants decide it. */ +function actionValue(expr: Expr, action: NetworkAction): boolean | undefined { + switch (expr.kind) { + case "literal": + return typeof expr.value === "boolean" ? expr.value : undefined; + case "not": { + const value = actionValue(expr.operand, action); + return value === undefined ? undefined : !value; + } + case "and": + case "or": { + const values = expr.items.map((item) => actionValue(item, action)); + const decides = expr.kind === "or"; + if (values.includes(decides)) return decides; + return values.every((value) => value === !decides) ? !decides : undefined; + } + case "binary": { + if (expr.op !== "==" && expr.op !== "!=" && expr.op !== "in") return undefined; + const variable = attributePath(expr.left); + if (variable?.length !== 1 || variable[0] !== "action") return undefined; + const entities = namedEntities(expr); + if (!entities) return undefined; + const matches = entities.some((e) => sameEntity(e, { type: ["Box", "Action"], id: action })); + return expr.op === "!=" ? !matches : matches; + } + default: + return undefined; + } +} + function checkPath(path: string[], action: NetworkAction, text: string): void { const [root, group, field] = path; if (root === "principal" || root === "resource" || root === "action") { @@ -448,14 +502,7 @@ function identityFormula( ): Formula | undefined { const variable = attributePath(expr.left); if (variable?.length !== 1) return undefined; - const entities = - expr.right.kind === "entity" - ? [expr.right.entity] - : expr.op === "in" && - expr.right.kind === "set" && - expr.right.items.every((i) => i.kind === "entity") - ? expr.right.items.map((i) => (i as Extract).entity) - : undefined; + const entities = namedEntities(expr); if (!entities) return undefined; let matches: boolean; if (variable[0] === "action") { @@ -470,6 +517,18 @@ function identityFormula( return constant(expr.op === "!=" ? !matches : matches, expr.text); } +/** The entities the right of `==`, `!=`, or `in` names: one entity, or a set of entities. */ +function namedEntities(expr: Extract): EntityRef[] | undefined { + const right = expr.right; + if (right.kind === "entity") return [right.entity]; + if (expr.op !== "in" || right.kind !== "set" || !right.items.every(isEntity)) return undefined; + return right.items.map((item) => item.entity); +} + +function isEntity(expr: Expr): expr is Extract { + return expr.kind === "entity"; +} + /** Why a rule that names the `Box::Action` `id`, which Box does not have, fails. */ export function unknownActionReason(id: string): string { return ( diff --git a/src/core/project/boxNetwork/dogwood.ts b/src/core/project/boxNetwork/dogwood.ts index 5ab901cb9..07fd872a7 100644 --- a/src/core/project/boxNetwork/dogwood.ts +++ b/src/core/project/boxNetwork/dogwood.ts @@ -128,10 +128,6 @@ function escapeRegExp(text: string): string { return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); } -// --------------------------------------------------------------------------- -// Tokens -// --------------------------------------------------------------------------- - type TokenKind = "ident" | "string" | "number" | "punct"; interface Token { @@ -288,10 +284,6 @@ function decodePattern(raw: string, span: SourceSpan): LikePattern { return { parts }; } -// --------------------------------------------------------------------------- -// Statements -// --------------------------------------------------------------------------- - const VARIABLES = new Set(["principal", "action", "resource", "context"]); const RELATION_OPERATORS = new Set(["==", "!=", "<", "<=", ">", ">="]); @@ -440,10 +432,6 @@ class Parser { return { polarity, body: { kind, text }, span: keyword.span }; } - // ------------------------------------------------------------------------- - // Expressions, by Cedar's precedence - // ------------------------------------------------------------------------- - private expr(): Expr { if (!this.isIdent("if")) return this.or(); const start = this.tokens[this.i++]!; @@ -712,10 +700,6 @@ class Parser { return this.fail("expected an attribute name after has", t); } - // ------------------------------------------------------------------------- - // Token helpers - // ------------------------------------------------------------------------- - private peek(): Token { const t = this.tokens[this.i]; if (t) return t; diff --git a/src/core/project/boxNetwork/egress.ts b/src/core/project/boxNetwork/egress.ts index 3a9dcbd16..dda60ff4f 100644 --- a/src/core/project/boxNetwork/egress.ts +++ b/src/core/project/boxNetwork/egress.ts @@ -1,3 +1,4 @@ +import { partition } from "@aws-sdk/util-endpoints"; import { z } from "zod"; import type { BoxEgressAuth } from "./network"; import type { FailureCode } from "./types"; @@ -134,6 +135,16 @@ const AWS_ENDPOINTS = [ }, ] as const; +/** The Bedrock runtime host of `region`, which the Box gateway's Bedrock model target fronts. */ +export function boxGatewayBedrockHost(region: string): string { + return `bedrock-runtime.${region}.${partition(region).dnsSuffix}`; +} + +/** The AgentCore data-plane host of `region`, which the Box gateway's AgentCore target fronts. */ +export function boxGatewayAgentCoreHost(region: string): string { + return `bedrock-agentcore.${region}.${partition(region).dnsSuffix}`; +} + /** The API of an AWS endpoint that the gateway signs for. */ export type AwsEndpointApi = (typeof AWS_ENDPOINTS)[number]["api"]; diff --git a/src/core/project/boxNetwork/hostMap.test.ts b/src/core/project/boxNetwork/hostMap.test.ts index b8b54381f..7986729a0 100644 --- a/src/core/project/boxNetwork/hostMap.test.ts +++ b/src/core/project/boxNetwork/hostMap.test.ts @@ -63,6 +63,49 @@ describe("the policy decision on each host", () => { expect(host(result, "y.example.com")?.reachable).toBe(true); }); + test("finds a host reachable when two path patterns of one permit hold on one path", () => { + const both = 'context.input.path like "/v1/*" && context.input.path like "*/items"'; + const result = map(reach("items", "x.example.com", both)); + expect(host(result, "x.example.com")).toMatchObject({ + reachable: true, + enforcedByBox: ["items"], + uncheckedBy: [], + }); + expect(host(result, "x.example.com")?.decision.allowed.map((s) => s.path)).toContain( + "/v1/items", + ); + }); + + test("finds a path of a permit that a forbid of one path leaves open", () => { + const both = 'context.input.path like "/v1/*" && context.input.path like "*/items"'; + const result = map( + reach("items", "x.example.com", both) + + forbid("no_list", on("x.example.com", 'context.input.path == "/v1/items"')), + ); + const decided = host(result, "x.example.com"); + expect(decided?.reachable).toBe(true); + expect(decided?.decision.allowed.map((s) => s.path)).not.toContain("/v1/items"); + }); + + test("finds no path when the path patterns of a permit never hold together", () => { + const never = 'context.input.path like "/v1/*" && context.input.path like "/v2/*"'; + expect(host(map(reach("never", "x.example.com", never)), "x.example.com")).toMatchObject({ + reachable: false, + uncheckedBy: [], + }); + }); + + test("keeps a host reachable, and names the permit, when its path tests are too many to check", () => { + const many = [..."abcdefghijklm"].map((c) => `context.input.path like "*${c}*"`).join(" && "); + const result = map(reach("many", "x.example.com", many)); + expect(result.failures).toEqual([]); + expect(host(result, "x.example.com")).toMatchObject({ + reachable: true, + uncheckedBy: ["many"], + enforcedByBox: ["many"], + }); + }); + test("names the limited permits and the forbids Box enforces on its own, in policy order", () => { const result = map( forbid("no_admin", on("x.example.com", 'context.input.path like "/admin/*"')) + @@ -76,6 +119,92 @@ describe("the policy decision on each host", () => { }); }); + test("names a connection permit that limits the address, and not one that allows any", () => { + const lan = 'context.input has ip4 && context.input.ip4 like "10.*"'; + const result = map( + connect("lan", on("a.example.com", lan)) + + permit("get_a", on("a.example.com")) + + connect("any", on("b.example.com", `(${NC} || ${lan})`)) + + permit("get_b", on("b.example.com")), + ); + expect(host(result, "a.example.com")?.enforcedByBox).toEqual(["lan"]); + expect(host(result, "b.example.com")?.enforcedByBox).toEqual([]); + }); + + describe("an attribute that an action test keeps from the action, as Box reads it", () => { + const codes = (result: ReturnType) => + result.failures.map(({ code, ruleId }) => [code, ruleId]); + const get = permit("get", on("a.example.com", 'context.input.method == "GET"')); + + // The guard of `&&` is false on net:connect, so that rule never allows a connection. + test.each([ + ["||", `(${NC} || context.input.method == "GET")`, true], + [ + "&& with !=", + `(action != Box::Action::"net:connect" && context.input.method == "GET")`, + false, + ], + ["if", `(if ${NC} then true else context.input.method == "GET")`, true], + [ + "|| with in", + `(action in [Box::Action::"net:connect"] || context.input.method == "GET")`, + true, + ], + ])("accepts a connection rule that reads a request field behind %s", (_, guard, reachable) => { + const result = map(connect("guarded", on("a.example.com", guard)) + get); + expect(codes(result)).toEqual([]); + expect(host(result, "a.example.com")?.reachable).toBe(reachable); + }); + + test("accepts a request rule that reads a connection field behind an action test", () => { + const guarded = permit( + "guarded", + on("a.example.com", `(${HR} || context.input.ip4 == "1.2.3.4")`), + ); + expect(codes(map(connect("c", on("a.example.com")) + guarded))).toEqual([]); + }); + + test("accepts a later condition that an earlier action test keeps from the action", () => { + const later = rule( + "later", + `permit (principal, ${NC}, resource) when { ${HR} } when { context.input.method == "GET" };`, + ); + expect(codes(map(later + reach("get", "a.example.com")))).toEqual([]); + }); + + // Box 0.1.11-preview.10 accepts each of these bodies before a host `when`. + test.each([ + [ + "temporal", + "exists (n: Long). ((count for (t: Timepoint). where (formerly within 10m (" + + 'Box::Action::"http:request"::response{ input.host: "api.github.com" } && tp(t)))) == n ' + + "&& n < 3)", + ], + ["guardrails", 'context.input.method == "GET"'], + ])( + "reads a host condition after a %s condition, which no action test decides", + (kind, body) => { + const limited = rule( + "limited", + `permit (principal, ${HR}, resource) when ${kind} { ${body} } when { ${on("a.example.com")} };`, + ); + const result = map(connect("c", on("a.example.com")) + limited); + expect(codes(result)).toEqual([]); + expect(host(result, "a.example.com")).toMatchObject({ + reachable: true, + enforcedByBox: ["limited"], + }); + }, + ); + + test("refuses the field when no action test keeps it from the action", () => { + const result = map( + connect("bare", on("a.example.com", 'context.input.method == "GET"')) + get, + ); + expect(codes(result)).toEqual([["UNKNOWN_ATTRIBUTE", "bare"]]); + }); + }); + test("gives a host only to a permit: a forbid with a fixed host makes no node", () => { expect(map(forbid("no_x", on("x.example.com"))).hosts).toEqual([]); }); diff --git a/src/core/project/boxNetwork/hostMap.ts b/src/core/project/boxNetwork/hostMap.ts index 62a9cbf22..914361de0 100644 --- a/src/core/project/boxNetwork/hostMap.ts +++ b/src/core/project/boxNetwork/hostMap.ts @@ -24,6 +24,7 @@ import { type BoxEgressSecret, type Destination, } from "./egress"; +import { findPath, pathTest, type PathTest } from "./pathSolver"; import { BOX_METADATA_RULE_IDS } from "./places"; import { ROUTABLE_METHODS, @@ -85,7 +86,12 @@ export interface MappedHost { readonly forbiddenBy: readonly string[]; /** The rules that limit what Box allows to the host, which Box enforces and a gateway does not. */ readonly enforcedByBox: readonly string[]; - /** Whether Box allows at least one sample request to the host. */ + /** + * The permits whose path tests are too many for build to check together. They keep an otherwise + * unreachable host reachable. + */ + readonly uncheckedBy: readonly string[]; + /** Whether Box allows at least one sample request to the host, or a permit of `uncheckedBy` can. */ readonly reachable: boolean; } @@ -200,10 +206,6 @@ class HostMapBuilder { return { hosts, failures: this.failures, websocketOnly: this.websocketOnly }; } - // --------------------------------------------------------------------------- - // Sources - // --------------------------------------------------------------------------- - /** Adds the entry's nodes, or records why it fails and returns the destinations it names. */ private addEgressEntry(name: string, raw: unknown): Destination[] | undefined { const problems: { code: FailureCode; reason: string }[] = []; @@ -355,6 +357,15 @@ class HostMapBuilder { let port: number; if (typeof pinned === "number") { if (!atoms("port").every((a) => holds(a, pinned)) || pinned === 80) continue; + if (!Number.isInteger(pinned) || pinned < 1 || pinned > 65535) { + this.ruleFailure( + rule, + "INVALID_PORT", + `allows ${host} on port ${pinned}, which is not a port. Name a port from 1 to ` + + "65535, such as context.input.port == 443.", + ); + continue; + } port = pinned; } else if (atoms("port").every((a) => holds(a, 443))) { port = 443; @@ -387,10 +398,6 @@ class HostMapBuilder { } } - // --------------------------------------------------------------------------- - // Rules - // --------------------------------------------------------------------------- - /** The statement's network clauses, or `undefined` for a rule that decides no host. */ private classify(statement: Statement, order: number): Rule | undefined { const scope = statement.action; @@ -598,24 +605,44 @@ function decide(node: Node, policy: Policy): MappedHost { for (const c of policy.connectForbids) { if (c !== connectForbid && possible(c.clause, node)) enforced.set(c.ruleId, c.order); } - for (const sample of samples) { + const consider = (sample: SampleRequest) => { const permits = policy.requestPermits.filter((c) => possible(c.clause, node, sample)); - if (permits.length === 0) continue; + if (permits.length === 0) return; if (connectForbid) { forbiddenBy.set(connectForbid.ruleId, connectForbid.order); - continue; + return; } - if (!connectPermit) continue; + if (!connectPermit) return; const forbid = policy.requestForbids.find((c) => definite(c.clause, node, sample)); if (forbid) { forbiddenBy.set(forbid.ruleId, forbid.order); - continue; + return; } allowed.push({ ...sample, ruleId: permits[0]!.ruleId }); for (const p of permits) if (limits(p.clause)) enforced.set(p.ruleId, p.order); for (const f of policy.requestForbids) { if (possible(f.clause, node, sample)) enforced.set(f.ruleId, f.order); } + }; + for (const sample of samples) consider(sample); + let checked = samples.length; + const unchecked = new Map(); + if (allowed.length === 0 && !connectForbid && connectPermit) { + const solved = solvedSamples(node, policy); + checked += solved.samples.length; + for (const sample of solved.samples) consider(sample); + if (allowed.length === 0) { + for (const c of solved.undecided) unchecked.set(c.ruleId, c.order); + for (const [ruleId, order] of unchecked) enforced.set(ruleId, order); + for (const f of policy.requestForbids) { + if (possible(offPath(f.clause), node)) enforced.set(f.ruleId, f.order); + } + } + } + if (allowed.length > 0 || unchecked.size > 0) { + const connects = policy.connectPermits.filter((c) => possible(c.clause, node)); + const open = new Set(connects.filter((c) => !limitsConnection(c.clause)).map((c) => c.ruleId)); + for (const c of connects) if (!open.has(c.ruleId)) enforced.set(c.ruleId, c.order); } for (const [ruleId, order] of forbiddenBy) enforced.set(ruleId, order); for (const ruleId of BOX_METADATA_RULE_IDS) enforced.delete(ruleId); @@ -627,11 +654,67 @@ function decide(node: Node, policy: Policy): MappedHost { authority: hostKey(node.host, node.port), ...(node.entry && { entry: node.entry }), namedBy: node.namedBy, - decision: { samples: samples.length, allowed }, + decision: { samples: checked, allowed }, forbiddenBy: inOrder(forbiddenBy), enforcedByBox: inOrder(enforced), - reachable: allowed.length > 0, + uncheckedBy: inOrder(unchecked), + reachable: allowed.length > 0 || unchecked.size > 0, + }; +} + +/** The clause without its path tests. */ +function offPath(clause: Clause): Clause { + return { ...clause, fields: clause.fields.filter((atom) => atom.field !== "path") }; +} + +/** + * A sample request for each routable method on which a permit allows a path that no forbid + * surely denies, found from the path tests of the rules, and each permit clause whose path tests + * are too many to search. + */ +function solvedSamples( + node: Node, + policy: Policy, +): { samples: SampleRequest[]; undecided: RuleClause[] } { + const samples: SampleRequest[] = []; + const undecided: RuleClause[] = []; + const tests = (clause: Clause): PathTest[] | undefined => { + const found: PathTest[] = []; + for (const atom of clause.fields) { + if (atom.field !== "path") continue; + const test = pathTest(atom); + if (test === false) return undefined; + if (test !== true) found.push(test); + } + return found; }; + for (const method of ROUTABLE_METHODS) { + const on = { method, path: "/" }; + const excluded = policy.requestForbids.flatMap(({ clause }) => { + if (!definite(offPath(clause), node, on)) return []; + const group = tests(clause); + return group === undefined ? [] : [group]; + }); + for (const permit of policy.requestPermits) { + if (!possible(offPath(permit.clause), node, on)) continue; + const required = tests(permit.clause); + if (required === undefined) continue; + const found = findPath(required, excluded, SENTINEL_SEGMENT); + if (found.kind === "undecided" && !undecided.includes(permit)) undecided.push(permit); + if (found.kind !== "path") continue; + samples.push({ method, path: found.path }); + break; + } + } + return { samples, undecided }; +} + +/** Whether a connection permit clause allows only some connections to its host: by address, or more. */ +function limitsConnection(clause: Clause): boolean { + return ( + clause.opaque.length > 0 || + clause.fields.some((atom) => atom.field === "ip4" || atom.field === "ip6") + ); } /** Whether a permit clause allows only some requests to its host: by method, path, or more. */ diff --git a/src/core/project/boxNetwork/index.ts b/src/core/project/boxNetwork/index.ts index af6e1596c..4c9dd46db 100644 --- a/src/core/project/boxNetwork/index.ts +++ b/src/core/project/boxNetwork/index.ts @@ -1,5 +1,6 @@ export { parseEndpoint } from "./egress"; export { + BOX_GATEWAY_TARGETS_FILE, boxGatewayIamWarnings, boxGatewayOf, buildBoxNetwork, diff --git a/src/core/project/boxNetwork/network.test.ts b/src/core/project/boxNetwork/network.test.ts index 04e2b6dc9..4d165f5ab 100644 --- a/src/core/project/boxNetwork/network.test.ts +++ b/src/core/project/boxNetwork/network.test.ts @@ -45,6 +45,8 @@ interface Options { readonly credentials?: ProjectSpec["credentials"]; readonly grantedActions?: string[]; readonly executionRoleArn?: string; + /** The targets that agentcore/box-gateway-targets.json names for the gateway. */ + readonly ownedTargets?: ReadonlySet; } /** The local box profile of runtime `agent`. */ @@ -94,6 +96,7 @@ function model(policy: string, egress: Record = {}, options: Op region: "us-west-2", targets: options.targets ?? [], grantedActions: options.grantedActions ?? [], + ...(options.ownedTargets && { ownedTargets: options.ownedTargets }), }); return { spec, @@ -286,40 +289,79 @@ describe("the gateway's targets", () => { ]); }); - test("refuses to manage an egress- target that build would not write, and names it", () => { - const r = model( - "", - { github: GITHUB }, - { - targets: [ - passthrough("egress-github", "https://api.github.com", { - passthrough: { endpoint: "https://api.github.com", protocolType: "MCP" }, - }), - passthrough("egress-old", "https://old.example.com", { - outboundAuth: { - type: "API_KEY", - credentialName: "old", - location: "QUERY_PARAMETER", - parameterName: "key", - }, - }), - ], + describe("the targets build owns", () => { + const mcpTarget = passthrough("egress-github", "https://api.github.com", { + passthrough: { endpoint: "https://api.github.com", protocolType: "MCP" }, + }); + const queryKey = passthrough("egress-old", "https://old.example.com", { + outboundAuth: { + type: "API_KEY", + credentialName: "old", + location: "QUERY_PARAMETER", + parameterName: "key", }, - ); - expect(r.failures()).toEqual([ - ["MANAGED_TARGET_CHANGED", "egress-github"], - ["MANAGED_TARGET_CHANGED", "egress-old"], - ]); - expect(r.lines()).toEqual([ - "agentcore/agentcore.json The gateway target 'egress-github' has protocolType MCP, " + - 'which build does not write for a target whose name starts with "egress-", so build ' + - 'does not change or remove it. Rename it without "egress-" to keep it as yours, or ' + - "remove it so build writes it again.", - "agentcore/agentcore.json The gateway target 'egress-old' sends the API key credential " + - "'old' in the query parameter key, which build does not write for a target whose name " + - 'starts with "egress-", so build does not change or remove it. Rename it without ' + - '"egress-" to keep it as yours, or remove it so build writes it again.', - ]); + }); + + test("are the ones agentcore/box-gateway-targets.json names, and a user's egress- target is not", () => { + const r = model( + "", + { github: GITHUB }, + { + targets: [passthrough("egress-mine", "https://mine.example.com"), queryKey], + ownedTargets: new Set(), + }, + ); + expect(r.failures()).toEqual([]); + expect([...r.network.managedTargets]).toEqual(["egress-github"]); + expect(r.network.warnings.filter((w) => w.includes("'egress-"))).toEqual([]); + }); + + test("fail a target the file names that the user changed, and say how to keep it", () => { + const r = model( + "", + { github: GITHUB }, + { + targets: [mcpTarget, queryKey], + ownedTargets: new Set(["egress-github", "egress-old"]), + }, + ); + expect(r.failures()).toEqual([ + ["MANAGED_TARGET_CHANGED", "egress-github"], + ["MANAGED_TARGET_CHANGED", "egress-old"], + ]); + expect(r.lines()[1]).toBe( + "agentcore/agentcore.json The gateway target 'egress-old' sends the API key credential " + + "'old' in the query parameter key, which build does not write, and " + + "agentcore/box-gateway-targets.json names it as a target that build writes, so build " + + "does not change or remove it. Remove 'egress-old' from that file to keep the target " + + "as yours, or remove the target so build writes it again.", + ); + }); + + test("are, for a gateway the file does not name, the egress- targets that build would write", () => { + const r = model( + "", + { github: GITHUB }, + { + targets: [passthrough("egress-stale", "https://stale.example.com"), queryKey], + }, + ); + expect(r.failures()).toEqual([]); + expect([...r.network.managedTargets]).toEqual(["egress-stale", "egress-github"]); + // The one build that takes the old egress- targets says which one it keeps as the user's. + expect(r.network.warnings.filter((w) => w.includes("'egress-"))).toEqual([ + "agentcore/agentcore.json: build keeps the gateway target 'egress-old' as yours, because " + + "it sends the API key credential 'old' in the query parameter key, which build does " + + "not write. Build does not change or remove it. Remove the target if build wrote it " + + "before and you do not use it.", + ]); + }); + + test("leave a user's target of another shape on an entry's host to the user", () => { + const r = model("", { github: GITHUB }, { targets: [mcpTarget] }); + expect(r.failures()).toEqual([["EXISTING_TARGET_CONFLICT", "github"]]); + expect([...r.network.managedTargets]).toEqual([]); + }); }); test("lets a new host take the name of an egress- target that no host takes now", () => { @@ -459,24 +501,23 @@ describe("outbound auth", () => { ]); }); - test("fails an entry named for a credential that another entry's variable takes", () => { - const shared = model( - "", - { - mirror: { - destinations: ["mirror.example.com"], - secret: { ref: "env://AGENTCORE_CREDENTIAL_GITHUB" }, - }, - github: GITHUB, - }, - { credentials: [{ authorizerType: "ApiKeyCredentialProvider", name: "github" }] }, - ); - expect(shared.failures()).toEqual([["API_KEY_CREDENTIAL_SHARED", "github"]]); - expect(shared.lines()).toEqual([ - ".box/agent/local/profile.toml:3:1 [egress.github] needs the API key credential 'github' for " + - "env://GITHUB_TOKEN, and [egress.mirror] takes that credential for " + - "env://AGENTCORE_CREDENTIAL_GITHUB. One credential holds one key. Rename the entry.", - ]); + test("takes one credential for its own variable and for one other variable, which build copies to it", () => { + const github = { authorizerType: "ApiKeyCredentialProvider", name: "github" } as const; + const mirror = { + destinations: ["mirror.example.com"], + secret: { ref: "env://AGENTCORE_CREDENTIAL_GITHUB" }, + }; + for (const egress of [ + { mirror, github: GITHUB }, + { github: GITHUB, mirror }, + ]) { + const shared = model("", egress, { credentials: [github] }); + expect(shared.failures()).toEqual([]); + expect(shared.network.hosts.map(({ outboundAuth }) => outboundAuth)).toMatchObject([ + { kind: "apiKey", credentialName: "github" }, + { kind: "apiKey", credentialName: "github" }, + ]); + } }); test("leaves an env:// entry that cannot name an API key credential to the credentials writer", () => { @@ -558,6 +599,23 @@ describe("hosts the model cannot carry", () => { ]); }); + test.each([65536, 0, -1])("fails each rule that names port %d, which is not a port", (port) => { + const pinned = `context.input.port == ${port}`; + const r = model( + connect("odd_connect", on("api.example.com", pinned)) + + permit("odd", on("api.example.com", pinned)), + ); + expect(r.lines()).toEqual( + [".box/agent/local/policy.dw:1:1", ".box/agent/local/policy.dw:2:1"].map( + (place, i) => + `${place} The rule "${["odd_connect", "odd"][i]}" allows api.example.com on port ` + + `${port}, which is not a port. Name a port from 1 to 65535, such as ` + + "context.input.port == 443.", + ), + ); + expect(r.targets()).toEqual([]); + }); + test("fails a host reachable only over plain HTTP", () => { expect( model( @@ -1010,6 +1068,18 @@ describe("warnings", () => { ]); }); + test("names a permit whose path tests build cannot check together, and keeps its host", () => { + const many = [..."abcdefghijklm"].map((c) => `context.input.path like "*${c}*"`).join(" && "); + const r = model(reach("many", "x.example.com", many)); + expect(r.failures()).toEqual([]); + expect(r.targets()).toEqual(["x.example.com -> egress-x-example-com"]); + expect(r.network.warnings[0]).toBe( + '.box/agent/local/policy.dw:2:1: The rule "many" has more path conditions than build can ' + + "check together, so build cannot tell whether your policy allows a request to " + + "x.example.com. Build gives the host a gateway target, and Box still applies the rule.", + ); + }); + test("names an entry whose host gets no target, and the forbids that deny it", () => { expect( model(forbid("no_github", on("api.github.com")), { github: GITHUB }).network.warnings, diff --git a/src/core/project/boxNetwork/network.ts b/src/core/project/boxNetwork/network.ts index b23cbc380..b4d0b1eb4 100644 --- a/src/core/project/boxNetwork/network.ts +++ b/src/core/project/boxNetwork/network.ts @@ -4,13 +4,11 @@ * the policy files to stage, and every warning and failure. Build, deploy, and staging write from * it. */ -import { - boxGatewayAgentCoreHost, - boxGatewayBedrockHost, -} from "../../../handlers/project/shortcuts"; +import { credentialEnvVarName } from "../../../projectSchemas/credential"; import type { AgentCoreGateway, AgentCoreGatewayTarget } from "../../../projectSchemas/gateway"; import type { ProjectSpec } from "../../../projectSchemas/project"; import type { ProjectRuntime } from "../../../projectSchemas/runtime"; +import { BOX_GATEWAY_TARGETS_FILE } from "../boxGatewayTargets"; import { BOX_BEDROCK_POLICY_FILE, BOX_MEMORY_POLICY_FILE } from "../boxMemory"; import { boxEgressCredentialName } from "../boxProfileCredentials"; import type { BoxEnvRoute } from "../boxProfileEgress"; @@ -18,6 +16,8 @@ import { buildHostMap, entryLabel, entryRef, type MappedHost } from "./hostMap"; import { BOX_EGRESS_TARGET_PREFIX, awsEndpoint, + boxGatewayAgentCoreHost, + boxGatewayBedrockHost, outboundAuthFor, parseEndpoint, targetNameFor, @@ -46,6 +46,8 @@ export type { BoxNetworkFailure } from "./types"; /** Where a failure of a target in agentcore.json is. */ const PROJECT_SPEC_PLACE = "agentcore/agentcore.json"; +export { BOX_GATEWAY_TARGETS_FILE }; + /** How the gateway authenticates its requests to a host. */ export type BoxEgressAuth = | { readonly kind: "none" } @@ -117,6 +119,11 @@ export interface BoxNetwork { readonly hosts: readonly BoxNetworkHost[]; /** The `env://` route of each target that sends an API key, for the credentials writer. */ readonly envRoutes: readonly BoxEnvRoute[]; + /** + * The targets of the gateway that build owns, which it adds, rewrites, and removes: each one it + * wrote before, and the new target of each host. Build keeps every other target as it is. + */ + readonly managedTargets: ReadonlySet; /** * The policy files, relative to the agent's local box folder, to copy beside the AgentCore * Runtime profile. @@ -160,6 +167,12 @@ export interface BoxNetworkProject { readonly targets: readonly AgentCoreGatewayTarget[]; /** The IAM actions that the gateway's `additionalPolicies` files grant, except build's own. */ readonly grantedActions: readonly string[]; + /** + * The targets that {@link BOX_GATEWAY_TARGETS_FILE} names for the gateway. Absent when the file + * does not name the gateway, which build last built before it kept the file: then build owns each + * target whose name starts with `egress-` and that has the shape build writes. + */ + readonly ownedTargets?: ReadonlySet; } /** The Box gateway of `runtime`: the gateway bound to it. */ @@ -211,9 +224,17 @@ export function buildBoxNetwork( runtime: project.runtime, profileFile: parsed.profile.path, region: project.region, - gateway: { name: project.gateway, targets: project.targets }, + gateway: { name: project.gateway, targets: project.targets, managed: targets.managed }, hosts: targets.hosts, telemetry: telemetry?.telemetry ?? [], + ruleIds: new Set( + parsed.statements + .filter( + ({ id, span }) => + placeOf(parsed, span) !== undefined || ruleOrigin(parsed, id).by !== "box", + ) + .map(({ id }) => id), + ), places: source.places, }); const derived = source && context && deriveRuntimeProfile(source.table, context); @@ -231,6 +252,7 @@ export function buildBoxNetwork( region: project.region, hosts: targets.hosts, envRoutes: envRoutesOf(targets.hosts), + managedTargets: targets.managed, policyFiles: parsed.profile.policyFiles, ...(sent && { telemetry: sent }), ...(derived && @@ -240,6 +262,17 @@ export function buildBoxNetwork( }), grantedActions: project.grantedActions, warnings: [ + ...map.hosts.flatMap(({ authority, uncheckedBy }) => + uncheckedBy.map((ruleId) => { + const { place, subject } = describeRule(parsed, ruleId); + return ( + `${place}: ${subject} has more path conditions than build can check together, so ` + + `build cannot tell whether your policy allows a request to ${authority}. Build gives ` + + "the host a gateway target, and Box still applies the rule." + ); + }), + ), + ...targets.warnings, ...hostWarnings(targets.hosts), ...map.websocketOnly.map(({ ruleId, span }) => { const { place, subject } = describeRule(parsed, ruleId, span); @@ -271,9 +304,12 @@ function envRoutesOf(hosts: readonly BoxNetworkHost[]): BoxEnvRoute[] { return routes; } -/** Whether build manages `target`: it adds, changes, and removes each target with the prefix. */ -export function isManagedTarget(target: Pick): boolean { - return target.name.startsWith(BOX_EGRESS_TARGET_PREFIX); +/** + * Whether build owns `target` of a gateway that {@link BOX_GATEWAY_TARGETS_FILE} does not name: its + * name starts with `egress-`, and it has the shape build writes. + */ +export function isManagedTarget(target: AgentCoreGatewayTarget): boolean { + return target.name.startsWith(BOX_EGRESS_TARGET_PREFIX) && unmanagedShape(target) === undefined; } /** The host map key of a passthrough target's endpoint, or `undefined` for another target. */ @@ -329,20 +365,41 @@ function hostTargets( project: BoxNetworkProject, located: (failure: ConversionFailure) => BoxNetworkFailure, profilePath: string, -): { hosts: BoxNetworkHost[]; failures: BoxNetworkFailure[] } { +): { + hosts: BoxNetworkHost[]; + failures: BoxNetworkFailure[]; + managed: ReadonlySet; + warnings: string[]; +} { const existing = project.targets; const failures: BoxNetworkFailure[] = []; + const recorded = project.ownedTargets; + const isManaged = (target: AgentCoreGatewayTarget) => + recorded ? recorded.has(target.name) : isManagedTarget(target); + const warnings: string[] = []; for (const target of existing) { - const changed = isManagedTarget(target) ? unmanagedShape(target) : undefined; + // The one build that takes a gateway's old egress- targets names each one it keeps. + const kept = + recorded === undefined && target.name.startsWith(BOX_EGRESS_TARGET_PREFIX) + ? unmanagedShape(target) + : undefined; + if (kept !== undefined) { + warnings.push( + `${PROJECT_SPEC_PLACE}: build keeps the gateway target '${target.name}' as yours, ` + + `because it ${kept}, which build does not write. Build does not change or remove it. ` + + "Remove the target if build wrote it before and you do not use it.", + ); + } + const changed = recorded?.has(target.name) ? unmanagedShape(target) : undefined; if (changed === undefined) continue; failures.push({ code: "MANAGED_TARGET_CHANGED", target: target.name, reason: - `The gateway target '${target.name}' ${changed}, which build does not write for a ` + - `target whose name starts with "${BOX_EGRESS_TARGET_PREFIX}", so build does not change ` + - `or remove it. Rename it without "${BOX_EGRESS_TARGET_PREFIX}" to keep it as yours, or ` + - "remove it so build writes it again.", + `The gateway target '${target.name}' ${changed}, which build does not write, and ` + + `${BOX_GATEWAY_TARGETS_FILE} names it as a target that build writes, so build does not ` + + `change or remove it. Remove '${target.name}' from that file to keep the target as ` + + "yours, or remove the target so build writes it again.", place: PROJECT_SPEC_PLACE, }); } @@ -362,7 +419,11 @@ function hostTargets( const claimed = new Set(); const reused = new Set(); - /** The variable and the entry of each API key credential an entry takes. */ + /** + * The variable and the entry of each API key credential an entry takes for a variable that is + * not the credential's own. Build copies the key of that variable to the credential's own, so an + * entry that reads the credential's own variable takes the same key. + */ const keys = new Map(); const hosts = mapped.map((host, index): BoxNetworkHost => { let auth: BoxEgressAuth = { kind: "none" }; @@ -373,17 +434,21 @@ function hostTargets( ); if (result.ok) auth = result.auth; else failAt(host, result.code, result.reason); - const holder = auth.kind === "apiKey" ? keys.get(auth.credentialName) : undefined; - if (auth.kind === "apiKey" && holder && holder.variable !== auth.variable) { + const alias = + auth.kind === "apiKey" && auth.variable !== credentialEnvVarName(auth.credentialName) + ? auth + : undefined; + const holder = alias && keys.get(alias.credentialName); + if (alias && holder && holder.variable !== alias.variable) { failAt( host, "API_KEY_CREDENTIAL_SHARED", - `needs the API key credential '${auth.credentialName}' for env://${auth.variable}, ` + + `needs the API key credential '${alias.credentialName}' for env://${alias.variable}, ` + `and ${holder.entry} takes that credential for env://${holder.variable}. One ` + "credential holds one key. Rename the entry.", ); - } else if (auth.kind === "apiKey" && !holder) { - keys.set(auth.credentialName, { variable: auth.variable, entry: entryLabel(entry) }); + } else if (alias && !holder) { + keys.set(alias.credentialName, { variable: alias.variable, entry: entryLabel(entry) }); } } let target: string | undefined; @@ -394,7 +459,7 @@ function hostTargets( if (held) { claimed.add(held.name); reused.add(index); - const conflict = isManagedTarget(held) + const conflict = isManaged(held) ? undefined : targetConflict(held, host, auth, profilePath); if (conflict) { @@ -448,7 +513,7 @@ function hostTargets( // A target that build does not manage keeps its name, and two hosts take no one name. const owners = new Map(); for (const target of existing) { - if (!isManagedTarget(target)) owners.set(target.name, `the gateway target '${target.name}'`); + if (!isManaged(target)) owners.set(target.name, `the gateway target '${target.name}'`); } const describeHost = (host: MappedHost) => host.entry ? `${entryLabel(host.entry)} for ${host.authority}` : `the host ${host.authority}`; @@ -473,7 +538,7 @@ function hostTargets( }); const served = hosts.filter((host) => host.target !== undefined).length; - const kept = existing.filter((target) => !isManagedTarget(target) && !claimed.has(target.name)); + const kept = existing.filter((target) => !isManaged(target) && !claimed.has(target.name)); if (served + kept.length > MAX_GATEWAY_TARGETS) { failures.push({ code: "TOO_MANY_TARGETS", @@ -484,7 +549,26 @@ function hostTargets( place: profilePath, }); } - return { hosts, failures }; + const managed = managedTargetsOf(existing.filter(isManaged), hosts, reused); + return { hosts, failures, managed, warnings }; +} + +/** + * The targets of a Box gateway that build owns (`BoxNetwork.managedTargets`), which the writers + * change and remove and the record lists: each target of `owned`, and the new target of each host + * that takes no target the gateway has (`reused`). Each other kind of target that build writes + * belongs in this set too. + */ +function managedTargetsOf( + owned: readonly AgentCoreGatewayTarget[], + hosts: readonly BoxNetworkHost[], + reused: ReadonlySet, +): Set { + const managed = new Set(owned.map(({ name }) => name)); + hosts.forEach(({ target }, index) => { + if (target !== undefined && !reused.has(index)) managed.add(target); + }); + return managed; } /** The source of the entry that names a host. */ diff --git a/src/core/project/boxNetwork/pathSolver.test.ts b/src/core/project/boxNetwork/pathSolver.test.ts new file mode 100644 index 000000000..064af2882 --- /dev/null +++ b/src/core/project/boxNetwork/pathSolver.test.ts @@ -0,0 +1,105 @@ +import { describe, expect, test } from "bun:test"; +import type { Comparison, FieldAtom } from "./conditions"; +import type { LikePattern } from "./dogwood"; +import { findPath, machinesFor, pathTest, type PathTest } from "./pathSolver"; + +/** A `like` pattern, with each `*` as a wildcard. */ +function like(text: string): LikePattern { + const parts: LikePattern["parts"][number][] = []; + for (const [i, piece] of text.split("*").entries()) { + if (i > 0) parts.push({ kind: "wildcard" }); + if (piece !== "") parts.push({ kind: "literal", text: piece }); + } + return { parts }; +} + +const atom = (comparison: Comparison, negated = false): FieldAtom => ({ + kind: "field", + field: "path", + comparison, + negated, + text: "context.input.path", +}); +const literal = (text: string): LikePattern => ({ parts: [{ kind: "literal", text }] }); +const must = (text: string): PathTest => ({ pattern: like(text), matches: true }); +const never = (text: string): PathTest => ({ pattern: like(text), matches: false }); + +describe("pathTest", () => { + test.each<[string, FieldAtom, PathTest | boolean]>([ + ["like", atom({ op: "like", pattern: like("/v1/*") }), must("/v1/*")], + ["!(like)", atom({ op: "like", pattern: like("/v1/*") }, true), never("/v1/*")], + ["==", atom({ op: "==", value: "/a" }), { pattern: literal("/a"), matches: true }], + ["!(==)", atom({ op: "==", value: "/a" }, true), { pattern: literal("/a"), matches: false }], + ["!=", atom({ op: "!=", value: "/a" }), { pattern: literal("/a"), matches: false }], + ["!(!=)", atom({ op: "!=", value: "/a" }, true), { pattern: literal("/a"), matches: true }], + ["has", atom({ op: "present" }), true], + ["!(has)", atom({ op: "present" }, true), false], + ])("reads %s", (_, input, expected) => { + expect(pathTest(input)).toEqual(expected); + }); +}); + +describe("findPath", () => { + const filler = "ยง"; + const path = (required: PathTest[], excluded: PathTest[][] = []) => { + const found = findPath(required, excluded, filler); + return found.kind === "path" ? found.path : found.kind; + }; + + test("finds the shortest path that two patterns of a permit allow together", () => { + expect(path([must("/v1/*"), must("*/items")])).toBe("/v1/items"); + }); + + test("finds a path past a != in a permit", () => { + const found = path([must("/a*"), { pattern: literal("/a"), matches: false }]); + expect(found).not.toBe("/a"); + expect(found).toStartWith("/a"); + }); + + test("finds a path past a negated like in a permit", () => { + const found = path([must("/v1/*"), never("/v1/admin*"), never("/v1/")]); + expect(found).toStartWith("/v1/"); + expect(found).not.toStartWith("/v1/admin"); + expect(found).not.toBe("/v1/"); + }); + + test("finds a path that a forbid does not hold on, and none when every path is forbidden", () => { + const found = path([must("/v1/*"), must("*/items")], [[must("/v1/items")]]); + expect(found).toBe("/v1//items"); + expect(path([must("/v1/*")], [[must("/*")]])).toBe("none"); + expect(path([must("/*")], [[]])).toBe("none"); + }); + + test("uses a character that no pattern names when the filler is in a pattern", () => { + const found = path([must("/*"), never("/"), never("/ยง*"), never("//*")]); + // U+E000, the first private-use character, which no pattern names. + expect(found).toBe("/\uE000"); + }); + + test("finds no path for patterns that never hold together", () => { + expect(path([must("/v1/*"), must("/v2/*")])).toBe("none"); + expect(path([must("v1/*")])).toBe("none"); + }); + + test("stops undecided when the search has too many states", () => { + expect(path([..."abcdefghijklm"].map((c) => must(`*${c}*`)))).toBe("undecided"); + }); +}); + +describe("machinesFor", () => { + test("gives equal patterns from different atoms one machine, beside the one for the leading /", () => { + const a = pathTest(atom({ op: "==", value: "/a" })) as PathTest; + const b = pathTest(atom({ op: "!=", value: "/a" }, true)) as PathTest; + expect(a.pattern).not.toBe(b.pattern); + expect(machinesFor([a, must("/v1/*")], [[b], [must("/v1/*")]]).count).toBe(3); + }); + + test("keeps a literal * apart from a wildcard", () => { + const star: PathTest = { + pattern: { parts: [{ kind: "literal", text: "/a*" }] }, + matches: true, + }; + expect(machinesFor([star, must("/a*")], []).count).toBe(3); + expect(findPath([star], [], "ยง")).toEqual({ kind: "path", path: "/a*" }); + }); +}); diff --git a/src/core/project/boxNetwork/pathSolver.ts b/src/core/project/boxNetwork/pathSolver.ts new file mode 100644 index 000000000..a87f6471c --- /dev/null +++ b/src/core/project/boxNetwork/pathSolver.ts @@ -0,0 +1,168 @@ +/** + * Finds a request path that a set of path tests allow together, as Box compares a path: a `like` + * pattern matches the whole path, and its `*` matches any run of characters. + */ +import type { FieldAtom } from "./conditions"; +import type { LikePattern } from "./dogwood"; + +/** A path test: the path matches `pattern`, or, when `matches` is false, does not match it. */ +export interface PathTest { + readonly pattern: LikePattern; + readonly matches: boolean; +} + +/** A path, or no path; `undecided` when the search stops at {@link MAX_PATH_STATES}. */ +export type PathSearch = + | { readonly kind: "path"; readonly path: string } + | { readonly kind: "none" } + | { readonly kind: "undecided" }; + +/** The most search states before the search stops undecided. */ +export const MAX_PATH_STATES = 4096; + +/** Each request path starts with `/`. */ +const ROOTED: PathTest = { + pattern: { parts: [{ kind: "literal", text: "/" }, { kind: "wildcard" }] }, + matches: true, +}; + +/** The test of a path atom, or the atom's value on every path when it does not read the path. */ +export function pathTest(atom: FieldAtom): PathTest | boolean { + const comparison = atom.comparison; + if (comparison.op === "present") return !atom.negated; + if (comparison.op === "like") return { pattern: comparison.pattern, matches: !atom.negated }; + if (typeof comparison.value !== "string") return atom.negated; + const pattern: LikePattern = { parts: [{ kind: "literal", text: comparison.value }] }; + if (comparison.op === "==") return { pattern, matches: !atom.negated }; + if (comparison.op === "!=") return { pattern, matches: atom.negated }; + return atom.negated; +} + +/** + * The shortest path that passes each test of `required` and fails at least one test of each group + * of `excluded`. A character that no pattern names is written as `filler`. + */ +export function findPath( + required: readonly PathTest[], + excluded: readonly (readonly PathTest[])[], + filler: string, +): PathSearch { + if (excluded.some((group) => group.length === 0)) return { kind: "none" }; + const { machines, wanted, groups, literals } = machinesFor(required, excluded); + const alphabet = [...literals, freeChar(literals, filler)]; + + const start = machines.map((machine) => machine.closure([0])); + const holds = (state: readonly number[][], test: { at: number; matches: boolean }) => + machines[test.at]!.accepts(state[test.at]!) === test.matches; + const accepted = (state: readonly number[][]) => + wanted.every((test) => holds(state, test)) && + groups.every((group) => !group.every((test) => holds(state, test))); + const dead = (state: readonly number[][]) => + wanted.some((test) => test.matches && state[test.at]!.length === 0); + + const key = (state: readonly number[][]) => state.map((set) => set.join(",")).join("|"); + const from = new Map(); + from.set(key(start), {}); + const queue: number[][][] = [start]; + for (let head = 0; head < queue.length; head++) { + const state = queue[head]!; + if (accepted(state)) return { kind: "path", path: pathTo(from, key(state)) }; + for (const char of alphabet) { + const next = state.map((set, i) => machines[i]!.step(set, char)); + const nextKey = key(next); + if (from.has(nextKey) || dead(next)) continue; + if (from.size >= MAX_PATH_STATES) return { kind: "undecided" }; + from.set(nextKey, { parent: key(state), char }); + queue.push(next); + } + } + return { kind: "none" }; +} + +/** + * One machine for each different pattern of the tests, with the leading `/` that each path has, + * and each test with the index of its pattern's machine. Equal patterns share one machine. + */ +export function machinesFor( + required: readonly PathTest[], + excluded: readonly (readonly PathTest[])[], +) { + const patterns: LikePattern[] = []; + const byKey = new Map(); + const indexOf = (pattern: LikePattern) => { + const key = patternKey(pattern); + const at = byKey.get(key) ?? patterns.push(pattern) - 1; + byKey.set(key, at); + return at; + }; + const wanted = [ROOTED, ...required].map((test) => ({ ...test, at: indexOf(test.pattern) })); + const groups = excluded.map((group) => + group.map((test) => ({ ...test, at: indexOf(test.pattern) })), + ); + return { + machines: patterns.map(machineOf), + count: patterns.length, + wanted, + groups, + literals: new Set(patterns.flatMap((p) => p.parts.flatMap(literalChars))), + }; +} + +/** A pattern as text, with each wildcard as `*` and each literal `*` and `\` escaped. */ +function patternKey(pattern: LikePattern): string { + return pattern.parts + .map((part) => (part.kind === "wildcard" ? "*" : part.text.replace(/[\\*]/g, "\\$&"))) + .join(""); +} + +/** A pattern as a machine whose state is the set of places in the pattern a prefix reaches. */ +function machineOf(pattern: LikePattern) { + const items = pattern.parts.flatMap((part) => + part.kind === "wildcard" ? [undefined] : [...part.text], + ); + const closure = (places: readonly number[]) => { + const reached = new Set(); + for (let place of places) { + reached.add(place); + while (place < items.length && items[place] === undefined) reached.add(++place); + } + return [...reached].sort((a, b) => a - b); + }; + return { + closure, + step: (places: readonly number[], char: string) => + closure( + places.flatMap((place) => { + if (place >= items.length) return []; + const item = items[place]; + if (item === undefined) return [place]; + return item === char ? [place + 1] : []; + }), + ), + accepts: (places: readonly number[]) => places.includes(items.length), + }; +} + +function literalChars(part: LikePattern["parts"][number]): string[] { + return part.kind === "literal" ? [...part.text] : []; +} + +/** `filler`, or another character that no pattern names. */ +function freeChar(literals: ReadonlySet, filler: string): string { + if (!literals.has(filler)) return filler; + for (let code = 0xe000; ; code++) { + const char = String.fromCharCode(code); + if (!literals.has(char)) return char; + } +} + +function pathTo( + from: ReadonlyMap, + end: string, +): string { + const chars: string[] = []; + for (let at = from.get(end); at?.parent !== undefined; at = from.get(at.parent)) { + chars.push(at.char!); + } + return chars.reverse().join(""); +} diff --git a/src/core/project/boxNetwork/profileParser.ts b/src/core/project/boxNetwork/profileParser.ts index 8b8576d73..eaa91c44d 100644 --- a/src/core/project/boxNetwork/profileParser.ts +++ b/src/core/project/boxNetwork/profileParser.ts @@ -5,8 +5,9 @@ * entry, `packs`, and `policies` for a message. */ import { posix } from "node:path"; -import { parse as parseToml } from "smol-toml"; +import { parse as parseToml, TomlError } from "smol-toml"; import type { ResolvedBoxProfile } from "../boxProfileResolver"; +import { isTable } from "../runtimeProfile/projectPaths"; import type { TomlTable } from "../runtimeProfile/types"; import { cloudWatchTelemetry, type ProfileCloudWatchTelemetry } from "./telemetry"; @@ -67,7 +68,7 @@ export function parseResolvedProfile( }; } } - const egress: Record = { ...(boxToml.egress as object | undefined) }; + const egress: Record = isTable(boxToml.egress) ? { ...boxToml.egress } : {}; const telemetry = cloudWatchTelemetry(boxToml); for (const { route, destinations } of openRoutes) { if (!Object.hasOwn(egress, route)) egress[route] = { destinations }; @@ -76,7 +77,7 @@ export function parseResolvedProfile( profile: { path: profilePath, egress, - mcp: (boxToml.mcp as Record | undefined) ?? {}, + mcp: isTable(boxToml.mcp) ? boxToml.mcp : {}, policyFiles, ...(telemetry.length > 0 && { telemetry }), }, @@ -101,13 +102,12 @@ export function profilePolicyFiles( ok: false as const, failure: { code, reason, place }, }); - let table: Record; + let table: TomlTable; try { - table = parseToml(text) as Record; + table = parseToml(text); } catch (error) { - const at = error as { line?: number; column?: number }; const place = - at.line !== undefined ? `${profilePath}:${at.line}:${at.column ?? 1}` : profilePath; + error instanceof TomlError ? `${profilePath}:${error.line}:${error.column}` : profilePath; return fail(`This is not valid TOML (${tomlProblem(error)}). Correct the syntax.`, place); } if (table.policy !== undefined) { @@ -121,14 +121,17 @@ export function profilePolicyFiles( const named = table.policies ?? []; const place = placeOfKey(text, profilePath, "policies"); const folder = posix.dirname(profilePath); - if (!Array.isArray(named) || !named.every((file) => typeof file === "string" && file !== "")) { + if ( + !Array.isArray(named) || + !named.every((file): file is string => typeof file === "string" && file !== "") + ) { return fail( '`policies` must be a list of policy file paths, such as ["policy.dw"]. Correct it.', place, ); } const files: string[] = []; - for (const file of named as string[]) { + for (const file of named) { const normal = posix.normalize(file.replace(/\\/g, "/")); if (posix.isAbsolute(normal) || normal === ".." || normal.startsWith("../")) { return fail( @@ -196,10 +199,6 @@ function placeOfKey(text: string, profilePath: string, key: string): string { /** The TOML reader's message, without its "Invalid TOML document:" start and its excerpt. */ function tomlProblem(error: unknown): string { - const message = ((error as { message?: string }).message ?? String(error)).split("\n")[0]!; + const message = (error instanceof Error ? error.message : String(error)).split("\n")[0]!; return message.replace(/^Invalid TOML document:\s*/, ""); } - -function isTable(value: unknown): value is Record { - return typeof value === "object" && value !== null && !Array.isArray(value); -} diff --git a/src/core/project/boxNetwork/telemetry.ts b/src/core/project/boxNetwork/telemetry.ts index efe36cb31..101e24a39 100644 --- a/src/core/project/boxNetwork/telemetry.ts +++ b/src/core/project/boxNetwork/telemetry.ts @@ -3,6 +3,7 @@ * `box.toml` that Box resolves it to. On AgentCore Runtime, Box signs each CloudWatch target with * the execution role, so that role needs a grant for what these targets send. */ +import { isTable } from "../runtimeProfile/projectPaths"; /** A CloudWatch target of the box profile, as Box sends to it. */ export type CloudWatchTelemetry = CloudWatchTarget & { @@ -57,13 +58,12 @@ const SIGNAL_GROUPS: ReadonlySet = new Set(["deny", "permit", "trace", " function includeOf(value: unknown): readonly string[] | undefined | null { if (value === undefined) return undefined; if (!Array.isArray(value) || value.length === 0) return null; - const known = value.every((word) => typeof word === "string" && SIGNAL_GROUPS.has(word)); - return known && new Set(value).size === value.length ? (value as string[]) : null; + const known = value.every( + (word): word is string => typeof word === "string" && SIGNAL_GROUPS.has(word), + ); + return known && new Set(value).size === value.length ? value : null; } -const isTable = (value: unknown): value is Record => - typeof value === "object" && value !== null && !Array.isArray(value); - /** The trimmed string `value`, or undefined when it is not a string. */ const text = (value: unknown) => (typeof value === "string" ? value.trim() : undefined); diff --git a/src/core/project/boxNetwork/types.ts b/src/core/project/boxNetwork/types.ts index f9d8ad25f..f00e9c1df 100644 --- a/src/core/project/boxNetwork/types.ts +++ b/src/core/project/boxNetwork/types.ts @@ -25,6 +25,7 @@ export const FAILURE_CODES = [ "WILDCARD_HOST", "UNCONSTRAINED_HOST", "UNCONSTRAINED_PORT", + "INVALID_PORT", "INVALID_HOST", "METHOD_NOT_ROUTABLE", "PLAIN_HTTP_ONLY", diff --git a/src/core/project/boxNetworkSource.test.ts b/src/core/project/boxNetworkSource.test.ts index 695fcb44b..4a4cef84e 100644 --- a/src/core/project/boxNetworkSource.test.ts +++ b/src/core/project/boxNetworkSource.test.ts @@ -239,6 +239,36 @@ describe("readBoxNetworks", () => { ); }); + test("takes the credential of another runtime for the credential's own variable", async () => { + const root = await project([]); + const profiles: Record = { + ".box/agent/local/profile.toml": { variable: "GITHUB_TOKEN", host: "api.github.com" }, + ".box/second/local/profile.toml": { + variable: "AGENTCORE_CREDENTIAL_GITHUB", + host: "uploads.github.com", + }, + }; + for (const [file, { variable, host }] of Object.entries(profiles)) { + await mkdir(join(root, file, ".."), { recursive: true }); + await writeFile( + join(root, file), + `[egress.github]\ndestinations = ["${host}"]\nsecret.ref = "env://${variable}"\n`, + ); + } + const resolver: BoxProfileResolver = { + resolve: async (_root, profilePath) => { + const { variable, host } = profiles[profilePath]!; + return boxShowOf({ + egress: { github: { destinations: [host], secret: { ref: `env://${variable}` } } }, + }); + }, + }; + + const networks = await readBoxNetworks(specWith("second"), root, resolver); + + expect(networks.map(({ failures }) => failures)).toEqual([[], []]); + }); + test("places a rule of a policy file at its line, and an entry at its line in the profile", async () => { const root = await project(["policy.dw"]); await writeFile( @@ -564,6 +594,56 @@ describe("two routes of one profile to one host", () => { }); }); +describe("the record of the targets build writes", () => { + const mine = { + name: "egress-mine", + targetType: "passthrough", + passthrough: { endpoint: "https://mine.example.com", protocolType: "CUSTOM" }, + }; + const withTarget = { + ...SPEC, + agentCoreGateways: [{ ...boxGatewaySpec("agent"), targets: [mine] }], + } as unknown as ProjectSpec; + const managed = async (root: string) => [ + ...(await readBoxNetworks(withTarget, root, new FakeBoxProfileResolver()))[0]!.managedTargets, + ]; + + test("makes only the targets it names build's", async () => { + const root = await project([]); + await mkdir(join(root, "agentcore")); + await writeFile( + join(root, "agentcore", "box-gateway-targets.json"), + '{"agent-box-egress": []}', + ); + expect(await managed(root)).not.toContain("egress-mine"); + }); + + test("makes each egress- target of the shape build writes build's, for a gateway it does not name", async () => { + const root = await project([]); + expect(await managed(root)).toContain("egress-mine"); + await mkdir(join(root, "agentcore")); + await writeFile( + join(root, "agentcore", "box-gateway-targets.json"), + '{"other-box-egress": []}', + ); + expect(await managed(root)).toContain("egress-mine"); + }); + + test("stops on a record that is not the one build writes, and names the file", async () => { + const root = await project([]); + await mkdir(join(root, "agentcore")); + await writeFile( + join(root, "agentcore", "box-gateway-targets.json"), + '{"agent-box-egress": "x"}', + ); + await expect(readBoxNetworks(withTarget, root, new FakeBoxProfileResolver())).rejects.toThrow( + "agentcore/box-gateway-targets.json is not the record of the gateway targets that build " + + "writes: a JSON object with a list of target names for each Box gateway. Remove the " + + "file, and build writes it again.", + ); + }); +}); + describe("the IAM policy files of the Box gateway", () => { test("counts the actions of each listed file, and warns for one it cannot count", async () => { const root = await project([]); @@ -596,6 +676,33 @@ describe("the IAM policy files of the Box gateway", () => { ]); }); + test("counts the actions of an Allow statement in each form IAM takes, and of no other", async () => { + const root = await project([]); + await mkdir(join(root, "agentcore")); + const files: Record = { + one: { Statement: { Effect: "Allow", Action: "lambda:InvokeFunctionUrl" } }, + mixed: { Statement: [{ Effect: "Deny", Action: "s3:*" }, null, "text", { Effect: "Allow" }] }, + none: { Version: "2012-10-17" }, + }; + for (const [name, document] of Object.entries(files)) { + await writeFile(join(root, "agentcore", `${name}.json`), JSON.stringify(document)); + } + const spec = { + ...SPEC, + agentCoreGateways: [ + { + ...boxGatewaySpec("agent"), + additionalPolicies: Object.keys(files).map((name) => `agentcore/${name}.json`), + }, + ], + } as unknown as ProjectSpec; + + const [network] = await readBoxNetworks(spec, root, new FakeBoxProfileResolver()); + + expect(network?.grantedActions).toEqual(["lambda:InvokeFunctionUrl"]); + expect(network?.warnings).toEqual([]); + }); + test("gives no warning for the Memory policy file that build writes before it writes it", async () => { const root = await project([]); const spec = { diff --git a/src/core/project/boxNetworkSource.ts b/src/core/project/boxNetworkSource.ts index 0b18cb0c2..0d1b50b47 100644 --- a/src/core/project/boxNetworkSource.ts +++ b/src/core/project/boxNetworkSource.ts @@ -8,6 +8,8 @@ import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises"; import { tmpdir } from "node:os"; import { dirname, isAbsolute, join, relative, sep } from "node:path"; import { parse as parseToml, stringify as stringifyToml } from "smol-toml"; +import { z } from "zod"; +import { credentialEnvVarName } from "../../projectSchemas/credential"; import type { ProjectSpec } from "../../projectSchemas/project"; import type { ProjectRuntime } from "../../projectSchemas/runtime"; import { InvalidEnvironmentError, ProjectStateError } from "../../errors/errors"; @@ -22,6 +24,7 @@ import { boxStartFolder, runtimeRunsInBox, } from "./templates/boxProfile"; +import { readBoxGatewayTargets } from "./boxGatewayTargets"; import { boxGatewayOf, buildBoxNetwork, @@ -36,6 +39,7 @@ import { } from "./boxNetwork"; import type { BoxProfileResolver, ResolvedBoxProfile } from "./boxProfileResolver"; import { profileKeyPlaces } from "./runtimeProfile/context"; +import { isTable } from "./runtimeProfile/projectPaths"; import type { TomlTable } from "./runtimeProfile/types"; /** The policy of an agent that has no local box profile at `profilePath`. */ @@ -65,6 +69,7 @@ export async function readBoxNetworks( addBoxGatewayTargets(withDefaults, region); const networks: BoxNetwork[] = []; const keys: SharedKeys = new Map(); + const record = readBoxGatewayTargets(projectRoot); for (const runtime of runtimes) { // ProjectSpecSchema requires a Box project to keep a gateway bound to each runtime. const entry = boxGatewayOf(withDefaults, runtime.name); @@ -84,6 +89,8 @@ export async function readBoxNetworks( region, targets: entry.targets, grantedActions: granted.actions, + ...(record && + Object.hasOwn(record, entry.name) && { ownedTargets: new Set(record[entry.name]) }), }); networks.push({ ...network, @@ -133,7 +140,10 @@ function sharedKeyFailures( ): BoxNetworkFailure[] { const failures: BoxNetworkFailure[] = []; for (const { outboundAuth: auth, sources } of network.hosts) { - if (auth.kind !== "apiKey") continue; + // Build copies the key of another variable to the credential's own, so it is the same key. + if (auth.kind !== "apiKey" || auth.variable === credentialEnvVarName(auth.credentialName)) { + continue; + } const holder = keys.get(auth.credentialName); if (holder === undefined) { keys.set(auth.credentialName, { variable: auth.variable, runtime: network.runtime }); @@ -242,7 +252,7 @@ async function readResolvedPolicy( */ function profileSource(text: string, profileFile: string): ParsedProfileSource | undefined { try { - return { table: parseToml(text) as TomlTable, places: profileKeyPlaces(text, profileFile) }; + return { table: parseToml(text), places: profileKeyPlaces(text, profileFile) }; } catch { return undefined; } @@ -256,9 +266,6 @@ function profileText(projectRoot: string, agentName: string): string | undefined return existsSync(path) ? readFileSync(path, "utf8") : undefined; } -const isTable = (value: unknown): value is Record => - typeof value === "object" && value !== null && !Array.isArray(value); - /** The `[options] bedrock.region` of the profile `table`, as a dotted or a quoted key. */ function bedrockRegionOf(table: Record): unknown { const options = isTable(table.options) ? table.options : {}; @@ -273,9 +280,9 @@ function bedrockRegionOf(table: Record): unknown { * region. An edit of the line that sets the region keeps every other line where it is. */ function profileForRegion(text: string, region: string): string | undefined { - let table: Record; + let table: TomlTable; try { - table = parseToml(text) as Record; + table = parseToml(text); } catch { return undefined; } @@ -419,6 +426,15 @@ function policyFileProblem( return undefined; } +/** The part of an IAM policy document that build reads: one statement, or a list of them. */ +const PolicyDocumentSchema = z.object({ Statement: z.unknown().optional() }); + +/** An Allow statement, with the action or the list of actions it names. */ +const AllowStatementSchema = z.object({ + Effect: z.literal("Allow"), + Action: z.union([z.string(), z.array(z.unknown())]), +}); + /** The policy files that build writes for the gateway's role. */ const BUILD_POLICY_FILES: ReadonlySet = new Set([ BOX_BEDROCK_POLICY_FILE, @@ -449,7 +465,7 @@ function grantedActions( try { text = readFileSync(join(projectRoot, ...policy.split("/")), "utf8"); } catch (error) { - const code = (error as NodeJS.ErrnoException).code; + const code = error instanceof Error && "code" in error ? String(error.code) : undefined; if (code === "ENOENT") { skipped("does not exist", "Create it, or remove it from additionalPolicies."); } else { @@ -464,18 +480,23 @@ function grantedActions( try { document = JSON.parse(text); } catch (error) { - skipped(`is not valid JSON (${(error as Error).message})`, "Correct the JSON."); + skipped( + `is not valid JSON (${error instanceof Error ? error.message : String(error)})`, + "Correct the JSON.", + ); continue; } - if (typeof document !== "object" || document === null || Array.isArray(document)) { + const policyDocument = PolicyDocumentSchema.safeParse(document); + if (!policyDocument.success) { skipped("is not a JSON object", "Make it an IAM policy document."); continue; } - const { Statement } = document as { Statement?: unknown }; - const statements = Array.isArray(Statement) ? Statement : [Statement]; - for (const statement of statements as { Effect?: unknown; Action?: unknown }[]) { - if (statement?.Effect !== "Allow") continue; - const named = Array.isArray(statement.Action) ? statement.Action : [statement.Action]; + const { Statement } = policyDocument.data; + for (const statement of Array.isArray(Statement) ? Statement : [Statement]) { + const allow = AllowStatementSchema.safeParse(statement); + if (!allow.success) continue; + const { Action } = allow.data; + const named = Array.isArray(Action) ? Action : [Action]; actions.push(...named.filter((action): action is string => typeof action === "string")); } } diff --git a/src/core/project/boxNetworkWriters.test.ts b/src/core/project/boxNetworkWriters.test.ts index c1d957ba7..5cf8e9f16 100644 --- a/src/core/project/boxNetworkWriters.test.ts +++ b/src/core/project/boxNetworkWriters.test.ts @@ -12,11 +12,21 @@ import { gatewayTargetsWriter, runtimeProfileWriter, telemetryPolicyWriter, + type BoxNetworkWriteContext, type BoxNetworkWriter, } from "./boxNetworkWriters"; +import { BOX_GATEWAY_TARGETS_FILE } from "./boxNetwork"; +import { ENV_LOCAL_RELATIVE_PATH } from "./envLocal"; import { AGENTCORE_CODEZIP_PACK_PATH, AGENTCORE_PACK_PATH } from "./templates/boxProfile"; import { serializeRuntimeProfile } from "./runtimeProfile/serialize"; +/** The targets build owns in a gateway that agentcore/box-gateway-targets.json does not name. */ +class EgressTargets extends Set { + override has(name: string): boolean { + return name.startsWith("egress-"); + } +} + /** A hand-built model of runtime `agent`, which each test changes as it needs. */ function network(overrides: Partial = {}): BoxNetwork { return { @@ -25,6 +35,7 @@ function network(overrides: Partial = {}): BoxNetwork { region: "us-west-2", hosts: [], envRoutes: [], + managedTargets: new EgressTargets(), policyFiles: [], runtimeProfile: { packs: ["@box/base", "@box/agentcore"], profile: { name: "demo" } }, runtimeProfileHeader: ["Derived from .box/agent/local/profile.toml."], @@ -142,7 +153,77 @@ describe("boxNetworkEdits", () => { }); }); +describe("boxNetworkEdits", () => { + test("gives a writer's warnings and late files agentcore.json as every writer changed it", () => { + const seen: string[] = []; + const reader: BoxNetworkWriter = { + name: "reader", + writes: () => [{ kind: "file", path: "seen.txt" }], + edits: () => ({ + warnings: (spec) => [`warning: ${spec.name}`], + filesAfter: (spec) => { + seen.push(spec.name); + return [{ path: "seen.txt", text: spec.name }]; + }, + }), + }; + const renamer: BoxNetworkWriter = { + name: "renamer", + writes: () => [{ kind: "defaultTargets" }], + edits: () => ({ + spec: [ + (spec) => { + spec.name = "renamed"; + return []; + }, + ], + }), + }; + + const edits = boxNetworkEdits([reader, renamer], [], contextFor()); + + expect(seen).toEqual(["renamed"]); + expect(edits.files).toEqual([{ path: "seen.txt", text: "renamed" }]); + expect(edits.warnings).toEqual(["warning: renamed"]); + }); +}); + describe("gatewayTargetsWriter", () => { + test("keeps a user's egress- target that the record does not name, and records the targets it writes", () => { + const project = spec([ + passthrough("egress-mine", "https://mine.example.com"), + passthrough("egress-gone", "https://gone.example.com"), + ]); + const models = [ + network({ + hosts: [ + host("httpbin.org", "egress-httpbin-org"), + host("api.github.com", "egress-github", { outboundAuth: GITHUB_AUTH }), + ], + managedTargets: new Set(["egress-gone", "egress-httpbin-org", "egress-github"]), + }), + ]; + + const edits = run([gatewayTargetsWriter], models, project); + + expect(targetNames(edits.spec)).toEqual(["egress-mine", "egress-httpbin-org"]); + expect(edits.messages).toContain( + "removing gateway target 'egress-gone' from 'agent-box-egress': the Box profile no longer " + + "allows gone.example.com", + ); + // No credential holds the GitHub key, so build writes no egress-github and records none. + expect(edits.files).toEqual([ + { + path: BOX_GATEWAY_TARGETS_FILE, + text: `${JSON.stringify({ "agent-box-egress": ["egress-httpbin-org"] }, undefined, 2)}\n`, + }, + ]); + }); + + test("records no file for a project with no box runtime", () => { + expect(run([gatewayTargetsWriter], []).files).toEqual([]); + }); + test("adds a host's target, rewrites a managed one, removes a stale one, and keeps the user's", () => { const project = spec([ passthrough("ours", "https://ours.example.com"), @@ -217,9 +298,10 @@ describe("gatewayTargetsWriter", () => { "sends the key of env://GITHUB_TOKEN, and agentcore.json has no API key credential " + "'github' to hold it", ]); + // A target that was never written changes nothing; unsentTargetWarnings says why it is not. const fresh = run([gatewayTargetsWriter], models); expect(fresh.specChanged).toBe(false); - expect(fresh.messages[0]).toStartWith("not adding gateway target 'egress-github'"); + expect(fresh.messages).toEqual([]); }); test("writes to the gateway bound to the runtime, whatever its name", () => { @@ -238,6 +320,75 @@ describe("gatewayTargetsWriter", () => { }); }); +describe("the warning for a host with no gateway target", () => { + /** The warnings of the credentials and gateway targets writers, as build runs them. */ + const warningsOf = (networks: BoxNetwork[], context: BoxNetworkWriteContext) => + boxNetworkEdits([credentialsWriter, gatewayTargetsWriter], networks, context).warnings; + + const github = (envRoutes: BoxNetwork["envRoutes"]) => + network({ + hosts: [ + host("api.github.com", "egress-github", { + outboundAuth: GITHUB_AUTH, + sources: [{ kind: "entry", egressEntry: "github", destinations: ["api.github.com"] }], + }), + ], + envRoutes, + }); + + test("warns for no host whose credential the credentials writer adds", () => { + const routes = [{ route: "github", variable: "GITHUB_TOKEN" }]; + expect(warningsOf([github(routes)], contextFor())).toEqual([]); + }); + + test("says why a host gets no target, and what to do, from the credentials writer", () => { + const routes = [{ route: "github", variable: "GITHUB_TOKEN" }]; + expect( + warningsOf([github(routes)], { ...contextFor(), env: {} }).map((w) => + w.replace(ENV_LOCAL_RELATIVE_PATH, ".env.local"), + ), + ).toEqual([ + "api.github.com: build gives [egress.github] no gateway target, so the agent cannot reach " + + "this host on AgentCore Runtime. GITHUB_TOKEN is not set here or in .env.local. Set " + + "GITHUB_TOKEN, or AGENTCORE_CREDENTIAL_GITHUB, and build again.", + ]); + }); + + test("says to build again for the variable of a credential that this build adds", () => { + const mirror = network({ + hosts: [ + host("mirror.example.com", "egress-mirror", { + outboundAuth: { + ...GITHUB_AUTH, + credentialName: "mirror", + variable: "AGENTCORE_CREDENTIAL_GITHUB", + }, + sources: [{ kind: "entry", egressEntry: "mirror", destinations: ["mirror.example.com"] }], + }), + ], + envRoutes: [ + { route: "github", variable: "GITHUB_TOKEN" }, + { route: "mirror", variable: "AGENTCORE_CREDENTIAL_GITHUB" }, + ], + }); + + expect(warningsOf([mirror], contextFor())).toEqual([ + "mirror.example.com: build gives [egress.mirror] no gateway target, so the agent cannot " + + "reach this host on AgentCore Runtime. env://AGENTCORE_CREDENTIAL_GITHUB is the " + + "variable of the credential 'github', which this build adds to agentcore.json. Build " + + "again, and the next build gives the host its target.", + ]); + }); + + test("names the credential and the variable when the credentials writer gives no reason", () => { + expect(warningsOf([github([])], contextFor())).toEqual([ + "api.github.com: build gives [egress.github] no gateway target, so the agent cannot reach " + + "this host on AgentCore Runtime. agentcore.json has no API key credential 'github' to " + + "hold the key of env://GITHUB_TOKEN.", + ]); + }); +}); + describe("credentialsWriter", () => { test("declares each credential once and seeds its key from the box variable", () => { const envRoutes = [{ route: "github", variable: "GITHUB_TOKEN" }]; @@ -257,6 +408,36 @@ describe("credentialsWriter", () => { ]); }); + test.each([["the credential's own variable"], ["the other variable"]])( + "stores a rotated key of a route that two runtimes read, with %s first", + (first) => { + const own = network({ + envRoutes: [{ route: "github", variable: "AGENTCORE_CREDENTIAL_GITHUB" }], + }); + const alias = network({ + runtime: "other", + gateway: "other-box-egress", + envRoutes: [{ route: "github", variable: "GITHUB_TOKEN" }], + }); + const project = spec(); + project.credentials.push({ authorizerType: "ApiKeyCredentialProvider", name: "github" }); + + const edits = boxNetworkEdits( + [credentialsWriter], + first === "the credential's own variable" ? [own, alias] : [alias, own], + { + ...contextFor(project), + env: { GITHUB_TOKEN: "ghp_new" }, + envLocal: { AGENTCORE_CREDENTIAL_GITHUB: "ghp_old" }, + }, + ); + + expect(edits.envLocal).toEqual([ + expect.objectContaining({ key: "AGENTCORE_CREDENTIAL_GITHUB", value: "ghp_new" }), + ]); + }, + ); + test("runs before the gateway targets, so a target gets the credential it adds", () => { const models = [ network({ diff --git a/src/core/project/boxNetworkWriters.ts b/src/core/project/boxNetworkWriters.ts index 9a2d48c88..6c38ddbcd 100644 --- a/src/core/project/boxNetworkWriters.ts +++ b/src/core/project/boxNetworkWriters.ts @@ -8,13 +8,14 @@ import { copyFileSync, existsSync, mkdirSync, rmSync, unlinkSync, writeFileSync import { dirname, join } from "node:path"; import { isDeepStrictEqual } from "node:util"; import type { EnvLocalEntry } from "../../handlers/project/types"; +import { credentialEnvironmentVariableNames } from "../../projectSchemas/credential"; import type { AgentCoreGatewayTarget } from "../../projectSchemas/gateway"; import type { ProjectSpec } from "../../projectSchemas/project"; import { + BOX_GATEWAY_TARGETS_FILE, boxGatewayOf, gatewayTargetFor, hostKey, - isManagedTarget, parseEndpoint, type BoxNetwork, type BoxNetworkHost, @@ -26,6 +27,7 @@ import { boxBedrockPolicy, boxMemoryPolicy, } from "./boxMemory"; +import { boxGatewayTargetsText } from "./boxGatewayTargets"; import { planBoxProfileCredentials, type BoxKeySources } from "./boxProfileCredentials"; import type { BoxEnvRoute } from "./boxProfileEgress"; import { @@ -70,8 +72,12 @@ export interface BoxNetworkEdits { /** Changes to the copy of agentcore.json, in order; each returns its step messages. */ readonly spec?: readonly ((spec: ProjectSpec) => string[])[]; readonly files?: readonly BoxNetworkFile[]; + /** Files that depend on the copy of agentcore.json once every writer changed it. */ + readonly filesAfter?: (spec: ProjectSpec) => readonly BoxNetworkFile[]; /** Entries for `.env.local`; each replaces the value it holds under that key. */ readonly envLocal?: readonly EnvLocalEntry[]; + /** Warnings on the copy of agentcore.json once every writer changed it. */ + readonly warnings?: (spec: ProjectSpec) => readonly string[]; } /** What a writer reads besides the models: the project, and where build looks for each key. */ @@ -102,6 +108,7 @@ export interface CollectedEdits { readonly files: readonly BoxNetworkFile[]; readonly envLocal: readonly EnvLocalEntry[]; readonly messages: readonly string[]; + readonly warnings: readonly string[]; } /** @@ -129,12 +136,17 @@ export function boxNetworkEdits( const messages: string[] = []; const files: BoxNetworkFile[] = []; const envLocal: EnvLocalEntry[] = []; - for (const writer of writers) { - const edits = writer.edits(networks, context); + const all = writers.map((writer) => writer.edits(networks, context)); + for (const edits of all) { for (const change of edits.spec ?? []) messages.push(...change(spec)); files.push(...(edits.files ?? [])); envLocal.push(...(edits.envLocal ?? [])); } + const warnings: string[] = []; + for (const edits of all) { + files.push(...(edits.filesAfter?.(spec) ?? [])); + warnings.push(...(edits.warnings?.(spec) ?? [])); + } const changedFields = (Object.keys(spec) as (keyof ProjectSpec)[]).filter( (field) => !isDeepStrictEqual(spec[field], context.spec[field]), ); @@ -145,6 +157,7 @@ export function boxNetworkEdits( files, envLocal, messages, + warnings, }; } @@ -186,27 +199,65 @@ export const credentialsWriter: BoxNetworkWriter = { }, ], envLocal: plan.entries, + warnings: (written) => unsentTargetWarnings(written, networks, plan.unprovisioned), }; }, }; +/** + * Each `env://` route of the networks once, by its name and its variable: two runtimes can read + * one credential from its own variable and from one other, and build copies the other's key. + */ function uniqueRoutes(networks: readonly BoxNetwork[]): BoxEnvRoute[] { const routes: BoxEnvRoute[] = []; for (const route of networks.flatMap((network) => network.envRoutes)) { - if (!routes.some((other) => other.route === route.route)) routes.push(route); + const seen = routes.some( + (other) => other.route === route.route && other.variable === route.variable, + ); + if (!seen) routes.push(route); } return routes; } -/** The `egress-` targets of each Box gateway, which build adds, rewrites, and removes. */ +/** + * The targets of each Box gateway that build owns, which it adds, rewrites, and removes, and the + * record of the targets it writes ({@link BOX_GATEWAY_TARGETS_FILE}). + */ export const gatewayTargetsWriter: BoxNetworkWriter = { name: "gateway targets", - writes: (networks) => networks.map(({ gateway }) => ({ kind: "gatewayTargets", gateway })), - edits: (networks) => ({ - spec: networks.map((network) => (spec: ProjectSpec) => writeGatewayTargets(spec, network)), - }), + writes: (networks) => [ + ...networks.map(({ gateway }) => ({ kind: "gatewayTargets" as const, gateway })), + ...(networks.length > 0 ? [{ kind: "file" as const, path: BOX_GATEWAY_TARGETS_FILE }] : []), + ], + edits: (networks) => { + if (networks.length === 0) return {}; + return { + spec: networks.map((network) => (spec: ProjectSpec) => writeGatewayTargets(spec, network)), + filesAfter: (written) => [ + { + path: BOX_GATEWAY_TARGETS_FILE, + text: boxGatewayTargetsText(recordOf(written, networks)), + }, + ], + }; + }, }; +/** + * The record of the targets build writes: for each Box gateway, the targets of the gateway in + * `spec`, agentcore.json as the writers changed it, that the model owns (`managedTargets`). + */ +function recordOf(spec: ProjectSpec, networks: readonly BoxNetwork[]): Record { + return Object.fromEntries( + networks.map((network) => [ + network.gateway, + (boxGatewayOf(spec, network.runtime)?.targets ?? []).flatMap(({ name }) => + network.managedTargets.has(name) ? [name] : [], + ), + ]), + ); +} + /** * Sets the build-owned targets of the network's Box gateway: a managed target that a host takes is * rewritten in place, every other managed target goes, a host whose managed target the gateway @@ -217,8 +268,9 @@ export const gatewayTargetsWriter: BoxNetworkWriter = { function writeGatewayTargets(spec: ProjectSpec, network: BoxNetwork): string[] { const gateway = boxGatewayOf(spec, network.runtime); if (!gateway) return []; + const managed = network.managedTargets; const served = network.hosts.flatMap((host) => - host.target === undefined || !isManagedTarget({ name: host.target }) + host.target === undefined || !managed.has(host.target) ? [] : [{ ...host, target: host.target }], ); @@ -229,7 +281,7 @@ function writeGatewayTargets(spec: ProjectSpec, network: BoxNetwork): string[] { const targets: AgentCoreGatewayTarget[] = []; const gatewayName = `'${gateway.name}'`; for (const target of existing) { - if (!isManagedTarget(target)) { + if (!managed.has(target.name)) { targets.push(target); continue; } @@ -257,12 +309,12 @@ function writeGatewayTargets(spec: ProjectSpec, network: BoxNetwork): string[] { messages.push(`adding gateway target '${host.target}' to ${gatewayName} for ${host.authority}`); } for (const host of unsent) { + if (!existing.some(({ name }) => name === host.target)) continue; const auth = undeclaredKey(spec, host)!; - const removed = existing.some(({ name }) => name === host.target); messages.push( - `${removed ? "removing" : "not adding"} gateway target '${host.target}' of ${gatewayName} ` + - `for ${host.authority}: it sends the key of env://${auth.variable}, and agentcore.json ` + - `has no API key credential '${auth.credentialName}' to hold it`, + `removing gateway target '${host.target}' of ${gatewayName} for ${host.authority}: it ` + + `sends the key of env://${auth.variable}, and agentcore.json has no API key credential ` + + `'${auth.credentialName}' to hold it`, ); } if (isDeepStrictEqual(targets, existing)) return messages; @@ -270,6 +322,49 @@ function writeGatewayTargets(spec: ProjectSpec, network: BoxNetwork): string[] { return messages; } +/** + * A warning for each host of `networks` that gets no gateway target because no API key credential + * of `spec`, agentcore.json as the writers changed it, holds the key its target sends: the agent + * cannot reach the host on AgentCore Runtime. It says why, from the credential planner's + * `unprovisioned`, and what to do. + */ +function unsentTargetWarnings( + spec: ProjectSpec, + networks: readonly BoxNetwork[], + unprovisioned: ReadonlyMap, +): string[] { + const warnings: string[] = []; + for (const { hosts, managedTargets } of networks) + for (const host of hosts) { + if (host.target === undefined || !managedTargets.has(host.target)) continue; + const auth = undeclaredKey(spec, host); + const source = host.sources.find( + (candidate): candidate is Exclude => + candidate.kind !== "rule", + ); + if (auth === undefined || source === undefined) continue; + const [table, route] = + source.kind === "entry" ? ["egress", source.egressEntry] : ["mcp", source.mcpEntry]; + // The model names a credential from agentcore.json before this build adds to it. + const holder = spec.credentials.find((credential) => + credentialEnvironmentVariableNames(credential).includes(auth.variable), + ); + const why = + unprovisioned.get(route) ?? + (holder + ? `env://${auth.variable} is the variable of the credential '${holder.name}', which ` + + "this build adds to agentcore.json. Build again, and the next build gives the host " + + "its target." + : `agentcore.json has no API key credential '${auth.credentialName}' to hold the key ` + + `of env://${auth.variable}.`); + warnings.push( + `${host.authority}: build gives [${table}.${route}] no gateway target, so the agent ` + + `cannot reach this host on AgentCore Runtime. ${why}`, + ); + } + return warnings; +} + /** The API key that a host's target sends, when agentcore.json declares no credential for it. */ function undeclaredKey( spec: ProjectSpec, diff --git a/src/core/project/boxProfileCredentials.test.ts b/src/core/project/boxProfileCredentials.test.ts index 6c5ec7081..d6b964d61 100644 --- a/src/core/project/boxProfileCredentials.test.ts +++ b/src/core/project/boxProfileCredentials.test.ts @@ -160,20 +160,30 @@ describe("planBoxProfileCredentials", () => { messages: [], added: [], entries: [], + unprovisioned: new Map(), }); }); - test("skips, with no message, the model-provider routes create writes", () => { + test("adds a credential for a model-provider route create writes, from the provider's variable", () => { const s = spec(); const plan = planBoxProfileCredentials( s, [route("openai", "OPENAI_API_KEY"), route("anthropic", "ANTHROPIC_API_KEY")], - shell({ OPENAI_API_KEY: "sk-x", ANTHROPIC_API_KEY: "sk-ant-x" }), + shell({ OPENAI_API_KEY: "sk-x" }), ); - expect(plan).toEqual({ messages: [], added: [], entries: [] }); - expect(s.credentials).toEqual([]); + expect(plan.added).toEqual([{ authorizerType: "ApiKeyCredentialProvider", name: "openai" }]); + expect(plan.entries).toMatchObject([{ key: "AGENTCORE_CREDENTIAL_OPENAI", value: "sk-x" }]); + expect(plan.unprovisioned).toEqual( + new Map([ + [ + "anthropic", + `ANTHROPIC_API_KEY is not set here or in ${ENV_LOCAL_RELATIVE_PATH}. Set ` + + "ANTHROPIC_API_KEY, or AGENTCORE_CREDENTIAL_ANTHROPIC, and build again.", + ], + ]), + ); }); test("skips, with no message, a route whose variable an existing credential reserves", () => { @@ -185,23 +195,18 @@ describe("planBoxProfileCredentials", () => { shell({}), ); - expect(plan).toEqual({ messages: [], added: [], entries: [] }); + expect(plan).toEqual({ messages: [], added: [], entries: [], unprovisioned: new Map() }); }); - test("reports a route that uses a model-provider name or variable in another way", () => { + test("adds a credential for a route that uses a model-provider name or variable in another way", () => { const plan = planBoxProfileCredentials( spec(), [route("openai", "MY_KEY"), route("my-llm", "GEMINI_API_KEY")], shell({ MY_KEY: "k", GEMINI_API_KEY: "k" }), ); - expect(plan.added).toEqual([]); - expect(plan.messages).toEqual([ - "skipping box egress 'openai' (env://MY_KEY): 'openai' is a model-provider route; " + - "agentcore create declares its key", - "skipping box egress 'my-llm' (env://GEMINI_API_KEY): GEMINI_API_KEY is a model provider's " + - "key variable; agentcore create declares its key", - ]); + expect(plan.added.map(({ name }) => name)).toEqual(["openai", "my-llm"]); + expect(plan.unprovisioned.size).toBe(0); }); test("reports, but does not add, a name that is not a valid credential name", () => { @@ -215,6 +220,9 @@ describe("planBoxProfileCredentials", () => { expect(plan.messages).toEqual([ "skipping box egress 'bad name!' (env://SOME_KEY): 'bad name!' is not a valid credential name", ]); + expect(plan.unprovisioned.get("bad name!")).toBe( + "'bad name!' is not a valid credential name. Rename the entry.", + ); }); test("reports, but does not add, a name that ends in a credential field suffix", () => { diff --git a/src/core/project/boxProfileCredentials.ts b/src/core/project/boxProfileCredentials.ts index b289357d4..721d62066 100644 --- a/src/core/project/boxProfileCredentials.ts +++ b/src/core/project/boxProfileCredentials.ts @@ -8,7 +8,6 @@ import { import type { ProjectSpec } from "../../projectSchemas/project"; import type { EnvLocalEntry } from "../../handlers/project/types"; import { hasValue, type BoxEnvRoute } from "./boxProfileEgress"; -import { MODEL_PROVIDER_EGRESS_ROUTES, MODEL_PROVIDER_KEY_VARIABLES } from "./templates/boxProfile"; import { ENV_LOCAL_RELATIVE_PATH } from "./envLocal"; /** @@ -28,6 +27,11 @@ export type BoxCredentialPlan = { added: Credential[]; /** The `.env.local` entries that store each key under its credential's reserved variable. */ entries: EnvLocalEntry[]; + /** + * By route, why no API key credential holds the key of a route that gets none, and what to do, + * in whole sentences. + */ + unprovisioned: Map; }; /** @@ -60,15 +64,16 @@ export function boxEgressCredentialName( * * Mutates `spec.credentials` in place, and is idempotent. It skips, with no message: * - a route whose variable an existing credential reserves: that credential holds the key; - * - a model-provider route as `agentcore create` writes it (`openai`, `anthropic`, `gemini` or - * `openai-compatible`, reading the provider variable such as `OPENAI_API_KEY`): its key is - * the variable LiteLLM reads, not a credential; * - a route named for an API key credential that keeps its key in Secrets Manager. * - * It skips, with a message, a route that uses a model-provider name or variable in any other way, - * and a route whose name `agentcore credentials add` would refuse: a name that is not a valid - * credential name, that ends in a credential field suffix, that derives the same variable as an - * existing credential, or that names a credential which is not an API key credential. + * A model-provider route that `agentcore create` writes with no key (`openai` reading + * `OPENAI_API_KEY`) is a route like any other: on AgentCore Runtime its gateway target sends the + * key of its credential. + * + * It skips, with a message, a route whose name `agentcore credentials add` would refuse: a name + * that is not a valid credential name, that ends in a credential field suffix, that derives the + * same variable as an existing credential, or that names a credential which is not an API key + * credential. */ export function planBoxProfileCredentials( spec: ProjectSpec, @@ -91,6 +96,7 @@ export function planBoxProfileCredentials( const messages: string[] = []; const added: Credential[] = []; const entries: EnvLocalEntry[] = []; + const unprovisioned = new Map(); /** * Stores the route's key under `credential`'s reserved variable, as `agentcore dev` reads it: the * route's variable from the environment, else from `.env.local`. A stored key that differs is @@ -128,20 +134,11 @@ export function planBoxProfileCredentials( for (const entry of routes) { const { route, variable } = entry; if (reservedVars.has(variable)) continue; - const providerName = MODEL_PROVIDER_EGRESS_ROUTES.has(route); - const providerVariable = MODEL_PROVIDER_KEY_VARIABLES.has(variable); - if (providerName && providerVariable) continue; - const skip = (reason: string) => + const skip = (reason: string, fix = "Rename the entry.") => { messages.push(`skipping box egress '${route}' (env://${variable}): ${reason}`); - if (providerName || providerVariable) { - skip( - providerName - ? `'${route}' is a model-provider route; agentcore create declares its key` - : `${variable} is a model provider's key variable; agentcore create declares its key`, - ); - continue; - } + unprovisioned.set(route, `${reason[0]!.toUpperCase()}${reason.slice(1)}. ${fix}`); + }; const existing = spec.credentials.find((credential) => credential.name === route); if (existing !== undefined) { if (existing.authorizerType !== "ApiKeyCredentialProvider") { @@ -183,6 +180,11 @@ export function planBoxProfileCredentials( `set here or in ${ENV_LOCAL_RELATIVE_PATH}, so deploy could not provision it. ` + `Set ${toSet(variable, route)} and build again`, ); + unprovisioned.set( + route, + `${variable} is not set here or in ${ENV_LOCAL_RELATIVE_PATH}. Set ` + + `${toSet(variable, route)} and build again.`, + ); continue; } @@ -195,5 +197,5 @@ export function planBoxProfileCredentials( "so deploy provisions it in AgentCore Identity", ); } - return { messages, added, entries }; + return { messages, added, entries, unprovisioned }; } diff --git a/src/core/project/boxProfileResolver.test.ts b/src/core/project/boxProfileResolver.test.ts index db877f739..dcc1f7d0b 100644 --- a/src/core/project/boxProfileResolver.test.ts +++ b/src/core/project/boxProfileResolver.test.ts @@ -338,19 +338,66 @@ describe("BoxCliProfileResolver", () => { ); }); - test("says to run uv sync in the agent's folder when Box refuses its missing .venv", async () => { - const error = await failure( - refusal([ - "box: error: /work/demo/app/agent/.venv/bin/python lies under the write grant /work/demo, so the workload can replace it", - ]), - ); + describe("the uv sync hint, when Box refuses a missing .venv under a write grant", () => { + /** A project folder with a space in its path, and the agent folders `agent` and `my agent`. */ + const project = async () => { + const root = await mkdtemp(join(tmpdir(), "box uv ")); + directories.push(root); + await mkdir(join(root, "app", "agent"), { recursive: true }); + await mkdir(join(root, "app", "my agent"), { recursive: true }); + return root; + }; + /** The last line of the error, which gives the hint. */ + const hint = async (root: string, lines: string[]) => { + const error = await new BoxCliProfileResolver(refusal(lines)) + .resolve(root, ".box/profile.toml") + .catch((caught: unknown) => caught); + return (error as Error).message.split("\n").at(-1); + }; + // Box 0.1.11-preview.10 wraps its error at 80 columns, at a space or inside a word, and + // indents each next line by 12 spaces. + const MORE = " ".repeat(12); + const grant = (root: string) => `lies under the write grant ${root} of \`[agent]\``; + + test("names the agent's folder", async () => { + const root = await project(); + const error = await new BoxCliProfileResolver( + refusal([`box: error: ${root}/app/agent/.venv/bin/python ${grant(root)}`]), + ) + .resolve(root, ".box/profile.toml") + .catch((caught: unknown) => caught); - expect((error as Error).message).toBe( - "Box refused the profile .box/profile.toml:\n" + - " box: error: /work/demo/app/agent/.venv/bin/python lies under the write grant " + - "/work/demo, so the workload can replace it\n" + - "Run 'uv sync' in app/agent, then retry.", - ); + expect((error as Error).message).toBe( + "Box refused the profile .box/profile.toml:\n" + + ` box: error: ${root}/app/agent/.venv/bin/python ${grant(root)}\n` + + "Run 'uv sync' in app/agent, then retry.", + ); + }); + + test("quotes a folder with a space, which Box wraps at that space", async () => { + const root = await project(); + const lines = [`box: error: ${root}/app/my`, `${MORE}agent/.venv/bin/python ${grant(root)}`]; + expect(await hint(root, lines)).toBe(`Run 'uv sync' in "app/my agent", then retry.`); + }); + + test("names the whole folder when Box wraps the path before the agent's folder", async () => { + const root = await project(); + const lines = [`box: error: ${root}/app`, `${MORE}/agent/.venv/bin/python lies under the`]; + lines.push(`${MORE}write grant ${root} of \`[agent]\``); + expect(await hint(root, lines)).toBe("Run 'uv sync' in app/agent, then retry."); + }); + + test("names the whole folder when Box wraps the path inside a word", async () => { + const root = await project(); + const lines = [`box: error: ${root}/app/ag`, `${MORE}ent/.venv/bin/python ${grant(root)}`]; + expect(await hint(root, lines)).toBe("Run 'uv sync' in app/agent, then retry."); + }); + + test("names no folder when the path names no folder of the project", async () => { + const root = await project(); + const lines = [`box: error: ${root}/app/gone/.venv/bin/python ${grant(root)}`]; + expect(await hint(root, lines)).toBe("Fix what Box reports, then retry."); + }); }); test("says how to see why when Box fails and prints no error", async () => { diff --git a/src/core/project/boxProfileResolver.ts b/src/core/project/boxProfileResolver.ts index 25ccbfbe1..a12483bf1 100644 --- a/src/core/project/boxProfileResolver.ts +++ b/src/core/project/boxProfileResolver.ts @@ -3,7 +3,7 @@ * the `box.toml` and `policy.dw` that a run of the profile gets, with every pack, option, and rule * Box adds already in them, so build reads them rather than compiling the profile itself. */ -import { realpathSync } from "node:fs"; +import { existsSync, realpathSync } from "node:fs"; import { isAbsolute, join, posix, relative, sep } from "node:path"; import { z } from "zod"; import { InvalidEnvironmentError } from "../../errors/errors"; @@ -210,21 +210,47 @@ function boxError(stderr: readonly string[]): string[] { return lines.filter((line) => line.trim() !== ""); } +/** The most places where Box wraps one error that build tries both ways. */ +const MAX_WRAPS = 8; + /** - * The agent's folder, from the project root, when Box refuses the profile because the agent's - * `.venv` lies under a write grant, as it does before `uv sync` makes the venv; else `undefined`. + * The agent's folder, from the project root and quoted when it has a space, when Box refuses the + * profile because the agent's `.venv` lies under a write grant, as it does before `uv sync` makes + * the venv; else `undefined`. Box wraps its error onto lines that start with spaces, at a space + * or inside a word, so the folder is the one way of joining the lines that names a folder on disk. */ function venvAgentFolder(lines: readonly string[], projectRoot: string): string | undefined { + const folders = new Set(); + for (const pieces of wrappedErrors(lines)) { + const wraps = Math.min(pieces.length - 1, MAX_WRAPS); + for (let joins = 0; joins < 2 ** wraps; joins++) { + const text = pieces.reduce( + (joined, piece, i) => `${joined}${(joins >> (i - 1)) & 1 ? " " : ""}${piece}`, + ); + const folder = /^box: error: (.+?)[\\/]\.venv[\\/]\S* lies under the write grant /.exec( + text, + )?.[1]; + if (folder !== undefined && existsSync(folder)) folders.add(folder); + } + } + const [folder, other] = [...folders]; + if (folder === undefined || other !== undefined) return undefined; + const inside = relative(realPath(projectRoot), realPath(folder)); + if (inside === "") return "the project folder"; + const outside = inside === ".." || inside.startsWith(`..${sep}`) || isAbsolute(inside); + const named = outside ? folder : inside.split(sep).join("/"); + return /\s/.test(named) ? `"${named}"` : named; +} + +/** Each error of Box as the pieces of its lines: a line that starts with a space goes on the last. */ +function wrappedErrors(lines: readonly string[]): string[][] { + const errors: string[][] = []; for (const line of lines) { - if (!line.includes("write grant")) continue; - const folder = /(\S+?)[\\/]\.venv[\\/]/.exec(line)?.[1]; - if (folder === undefined) continue; - const inside = relative(realPath(projectRoot), realPath(folder)); - if (inside === "") return "the project folder"; - const outside = inside === ".." || inside.startsWith(`..${sep}`) || isAbsolute(inside); - return outside ? folder : inside.split(sep).join("/"); + const last = errors.at(-1); + if (last && /^\s/.test(line)) last.push(line.trimStart()); + else errors.push([line]); } - return undefined; + return errors; } /** The path with every link resolved, or the path itself when it does not exist. */ diff --git a/src/core/project/manager.box.test.ts b/src/core/project/manager.box.test.ts index 9fe6b1320..8517ca07f 100644 --- a/src/core/project/manager.box.test.ts +++ b/src/core/project/manager.box.test.ts @@ -9,6 +9,7 @@ import type { AddResourceInput, Project } from "../../handlers/project/types"; import { resolveRuntimeTemplateShortcut } from "../../handlers/project/shortcuts"; import { createSilentLogger, TestIdentityClient } from "../../testing"; import { BOX_RELEASE } from "./backends/boxRelease"; +import type { RecordFiles } from "./boxGatewayTargets"; import { boxGatewayLogsNotice, FsProjectManager } from "./manager"; import { newProjectSpec } from "./templates/project"; import { defaultLogTargetNotice } from "./runtimeProfile/rules/additions"; @@ -33,7 +34,7 @@ afterEach(async () => { ); }); -function subject(json?: ReadWriteJson): FsProjectManager { +function subject(json?: ReadWriteJson, recordFiles?: RecordFiles): FsProjectManager { return new FsProjectManager({ logger: createSilentLogger(), identity: new TestIdentityClient(), @@ -41,9 +42,20 @@ function subject(json?: ReadWriteJson): FsProjectManager { runner: async () => {}, checkTool: async () => {}, ...(json && { json }), + ...(recordFiles && { recordFiles }), }); } +/** A writer of the record of build's targets that refuses each write and each removal. */ +const refusingRecordWrites: RecordFiles = { + write: (path) => { + throw new Error(`the test refuses the write of ${path}`); + }, + remove: (path) => { + throw new Error(`the test refuses the removal of ${path}`); + }, +}; + /** A JSON reader and writer that refuses each write of `specFile`, for each user, root too. */ function refusingSpecWrites(specFile: string): ReadWriteJson { const files = new FsReadWriteJson({ logger: createSilentLogger() }); @@ -155,6 +167,9 @@ async function existingProject(manager: FsProjectManager): Promise { return project; } +/** The record of the gateway targets that build writes, `agentcore/box-gateway-targets.json`. */ +const recordOf = (project: Project) => + join(project.rootPath, "agentcore", "box-gateway-targets.json"); const specText = (project: Project) => readFile(join(project.rootPath, "agentcore", "agentcore.json"), "utf8"); /** The spec on disk, parsed, for a test that reads runtimes or gateway bindings. */ @@ -286,6 +301,26 @@ describe("agentcore create", () => { expect(runtime?.network).toEqual(network); }); + test("a Box template writes an empty entry for each Box gateway in the record of build's targets", async () => { + const directory = await mkdtemp(join(tmpdir(), "agentcore-box-")); + tempDirectories.push(directory); + process.chdir(directory); + const project = await drain( + subject().create({ + name: "example", + skipInstall: true, + skipGit: true, + scaffoldRuntimeInput: resolveRuntimeTemplateShortcut("agent-python-strands-box", { + runtimeName: "agent", + }), + }), + ); + + expect(JSON.parse(await readFile(recordOf(project), "utf8"))).toEqual({ + "agent-box-egress": [], + }); + }); + test("templates that are not Box templates write no projectType and no gateway", () => { const spec = newProjectSpec("example", [{ runtimes: [{ name: "agent" } as never] }]); expect("projectType" in spec).toBe(false); @@ -417,6 +452,24 @@ describe("gateway targets in a Box project", () => { ]); }); + test("add runtime adds an empty entry for its Box gateway to the record of build's targets", async () => { + const manager = subject(); + const project = await createdProject(manager); + await writeFile(recordOf(project), '{\n "agent-box-egress": ["egress-x"]\n}\n'); + + await drain( + manager.addResource(project, { + resourceType: "runtime", + resourceConfig: { name: "search", language: "Python", protocol: "HTTP" }, + } as never), + ); + + expect(JSON.parse(await readFile(recordOf(project), "utf8"))).toEqual({ + "agent-box-egress": ["egress-x"], + "search-box-egress": [], + }); + }); + test("add runtime says that the new Box gateway sends its logs, and how to stop them", async () => { const manager = subject(); const project = await createdProject(manager); @@ -533,6 +586,32 @@ describe("gateway targets in a Box project", () => { ]); }); + test("remove runtime drops its Box gateway from the record, so add runtime again writes an empty entry", async () => { + const manager = subject(); + let project = await createdProject(manager, ["agent", "search"]); + await writeFile( + recordOf(project), + '{\n "agent-box-egress": ["egress-a"],\n "search-box-egress": ["egress-old"]\n}\n', + ); + + project = (await manager.removeResource(project, { resourceType: "runtime", name: "search" })) + .project; + expect(JSON.parse(await readFile(recordOf(project), "utf8"))).toEqual({ + "agent-box-egress": ["egress-a"], + }); + + await drain( + manager.addResource(project, { + resourceType: "runtime", + resourceConfig: { name: "search", language: "Python", protocol: "HTTP" }, + } as never), + ); + expect(JSON.parse(await readFile(recordOf(project), "utf8"))).toEqual({ + "agent-box-egress": ["egress-a"], + "search-box-egress": [], + }); + }); + test("add runtime refuses a start.py of the user's own, and changes nothing", async () => { const manager = subject(); const project = await createdProject(manager); @@ -666,6 +745,7 @@ describe("gateway targets in a Box project", () => { expect(messages).toContain(`writing box profile ${profile}`); expect(messages).not.toContain(boxGatewayLogsNotice(boxGatewaySpec("search").name)); expect(await specText(project)).toBe(before); + expect(existsSync(recordOf(project))).toBe(false); }); test("add runtime warns when the kept box profile is for another protocol", async () => { @@ -879,7 +959,9 @@ describe("gateway targets in a Box project", () => { test("remove all, then add runtime, adds a box runtime, as the project is still a Box project", async () => { const manager = subject(); let project = await createdProject(manager); + await writeFile(recordOf(project), '{\n "agent-box-egress": ["egress-old"]\n}\n'); project = (await manager.removeAllResources(project)).project; + expect(JSON.parse(await readFile(recordOf(project), "utf8"))).toEqual({}); await drain( manager.addResource(project, { @@ -893,6 +975,110 @@ describe("gateway targets in a Box project", () => { ["agent", { version: BOX_RELEASE.version }], ]); expect(spec.agentCoreGateways.map(({ boundRuntime }) => boundRuntime)).toEqual(["agent"]); + expect(JSON.parse(await readFile(recordOf(project), "utf8"))).toEqual({ + "agent-box-egress": [], + }); + }); +}); + +describe("the record of build's targets and agentcore.json, when a write fails", () => { + const RECORD = '{\n "agent-box-egress": ["egress-a"],\n "search-box-egress": ["egress-s"]\n}\n'; + const addSearch = (manager: FsProjectManager, project: Project) => + drain( + manager.addResource(project, { + resourceType: "runtime", + resourceConfig: { name: "search", language: "Python", protocol: "HTTP" }, + } as never), + ); + const flows: [ + string, + string[], + (manager: FsProjectManager, project: Project) => Promise, + ][] = [ + ["add runtime", ["agent"], addSearch], + [ + "remove runtime", + ["agent", "search"], + (manager, project) => + manager.removeResource(project, { resourceType: "runtime", name: "search" }), + ], + ["remove all", ["agent", "search"], (manager, project) => manager.removeAllResources(project)], + ]; + + test.each(flows)( + "%s keeps the record as it was when the write of agentcore.json fails", + async (_, runtimes, flow) => { + const project = await createdProject(subject(), runtimes); + const record = runtimes.length === 1 ? '{\n "agent-box-egress": ["egress-a"]\n}\n' : RECORD; + await writeFile(recordOf(project), record); + const before = await specText(project); + const specFile = join(project.rootPath, "agentcore", "agentcore.json"); + + await expect(flow(subject(refusingSpecWrites(specFile)), project)).rejects.toThrow( + `the test refuses the write of ${specFile}`, + ); + + expect(await specText(project)).toBe(before); + expect(await readFile(recordOf(project), "utf8")).toBe(record); + }, + ); + + test.each(flows)( + "%s keeps agentcore.json as it was when the write of the record fails", + async (_, runtimes, flow) => { + const project = await createdProject(subject(), runtimes); + const record = runtimes.length === 1 ? '{\n "agent-box-egress": ["egress-a"]\n}\n' : RECORD; + await writeFile(recordOf(project), record); + const before = await specText(project); + + await expect(flow(subject(undefined, refusingRecordWrites), project)).rejects.toThrow( + `the test refuses the write of ${recordOf(project)}`, + ); + + expect(await specText(project)).toBe(before); + expect(await readFile(recordOf(project), "utf8")).toBe(record); + }, + ); + + test("remove all keeps the record and agentcore.json as they were when it cannot remove a key", async () => { + const project = await createdProject(subject(), ["agent", "search"]); + const spec = JSON.parse(await specText(project)) as { credentials?: unknown[] }; + spec.credentials = [{ authorizerType: "ApiKeyCredentialProvider", name: "github" }]; + await writeFile(join(project.rootPath, "agentcore", "agentcore.json"), JSON.stringify(spec)); + await writeFile(recordOf(project), RECORD); + // A folder in the place of .env.local makes the removal of the credential's key fail. + const envLocal = join(project.rootPath, "agentcore", ".env.local"); + await rm(envLocal, { force: true }); + await mkdir(envLocal); + const before = await specText(project); + + await expect(subject().removeAllResources(project)).rejects.toThrow(); + + expect(await specText(project)).toBe(before); + expect(await readFile(recordOf(project), "utf8")).toBe(RECORD); + }); + + test("create writes the record before agentcore.json, so a failed record write leaves no project", async () => { + const directory = await mkdtemp(join(tmpdir(), "agentcore-box-")); + tempDirectories.push(directory); + process.chdir(directory); + await mkdir(join(directory, "example", "agentcore"), { recursive: true }); + await writeFile(join(directory, "example", "agentcore", "box-gateway-targets.json"), "{}\n"); + + await expect( + drain( + subject().create({ + name: "example", + skipInstall: true, + skipGit: true, + scaffoldRuntimeInput: resolveRuntimeTemplateShortcut("agent-python-strands-box", { + runtimeName: "agent", + }), + }), + ), + ).rejects.toThrow("File already exists"); + + expect(existsSync(join(directory, "example", "agentcore", "agentcore.json"))).toBe(false); }); }); diff --git a/src/core/project/manager.boxNetwork.test.ts b/src/core/project/manager.boxNetwork.test.ts index 9dff64eb3..2f9471537 100644 --- a/src/core/project/manager.boxNetwork.test.ts +++ b/src/core/project/manager.boxNetwork.test.ts @@ -13,6 +13,7 @@ import type { DeployBackendInput, ProjectBackend } from "./backends/types"; import { boxShowOf, FakeBoxProfileResolver } from "./boxProfileResolver-test-support"; import type { ResolvedBoxProfile } from "./boxProfileResolver"; import { seedBoxCache } from "./backends/box-release-test-support"; +import { ENV_LOCAL_RELATIVE_PATH, EnvLocalFile } from "./envLocal"; import { boxGatewayLogsNotice, FsProjectManager } from "./manager"; /** The golden files of this suite; `RECORD=1 bun test ` rewrites them, with no AWS call. */ @@ -181,6 +182,8 @@ async function strandsProject( const path = (root: string, relative: string) => join(root, ...relative.split("/")); const text = (root: string, relative: string) => readFile(path(root, relative), "utf8"); +/** The `host` or `host:port` a host warning starts with, before its first ": ". */ +const authorityOf = (warning: string) => warning.slice(0, Math.max(warning.indexOf(": "), 0)); /** Adds `tables` to the end of the profile, `top` to its start, and writes `.box/agent_python_strands/local/policy.dw`. */ async function editProfile(root: string, edit: { top?: string; tables?: string; policy?: string }) { @@ -360,14 +363,15 @@ describe("build writes the Box network of the box profile", () => { await editProfile(root, { tables: GITHUB_ROUTE }); box.answer = shows({ github: GITHUB }); - const { steps } = await build(manager, root); + const { steps, warnings } = await build(manager, root); expect(await targetNames(root)).toEqual(["bedrock", "agentcore"]); expect(JSON.parse(await text(root, SPEC)).credentials ?? []).toEqual([]); - expect(steps).toContain( - `not adding gateway target 'egress-github' of '${GATEWAY}' for api.github.com: it sends ` + - "the key of env://GITHUB_TOKEN, and agentcore.json has no API key credential 'github' " + - "to hold it", + expect(steps.some((step) => step.startsWith("not adding gateway target"))).toBe(false); + expect(warnings).toContain( + "api.github.com: build gives [egress.github] no gateway target, so the agent cannot reach " + + `this host on AgentCore Runtime. GITHUB_TOKEN is not set here or in ${ENV_LOCAL_RELATIVE_PATH}. ` + + "Set GITHUB_TOKEN, or AGENTCORE_CREDENTIAL_GITHUB, and build again.", ); // With no target, the Runtime profile has no route to api.github.com, as the old renderer. const egress = (await runtimeProfile(root)).egress as Record< @@ -377,6 +381,83 @@ describe("build writes the Box network of the box profile", () => { expect(Object.keys(egress).sort()).toEqual(["agentcore", "bedrock"]); }); + test("writes the target of a model-provider route once its key is set, as the warning says", async () => { + const { manager, root, box } = await strandsProject(); + const openai = { + destinations: ["api.openai.com"], + secret: { ref: "env://OPENAI_API_KEY" }, + }; + await editProfile(root, { + tables: + '\n[egress.openai]\ndestinations = ["api.openai.com"]\n' + + 'secret.ref = "env://OPENAI_API_KEY"\n', + }); + box.answer = shows({ openai }); + + const first = await build(manager, root); + expect(await targetNames(root)).toEqual(["bedrock", "agentcore"]); + expect(first.warnings.filter((w) => authorityOf(w) === "api.openai.com")).toHaveLength(1); + expect(first.warnings).toContain( + "api.openai.com: build gives [egress.openai] no gateway target, so the agent cannot reach " + + `this host on AgentCore Runtime. OPENAI_API_KEY is not set here or in ${ENV_LOCAL_RELATIVE_PATH}. ` + + "Set OPENAI_API_KEY, or AGENTCORE_CREDENTIAL_OPENAI, and build again.", + ); + + await new EnvLocalFile(root).insertIfNew([ + { key: "OPENAI_API_KEY", value: "sk-test", comment: "the key the agent reads locally" }, + ]); + const second = await build(manager, root); + expect(await targetNames(root)).toEqual(["bedrock", "agentcore", "egress-openai"]); + expect(second.warnings.filter((w) => authorityOf(w) === "api.openai.com")).toEqual([]); + }); + + test("keeps a user's egress- target that a new project has before its first build", async () => { + const { manager, root } = await strandsProject(); + // create wrote an empty entry for the Box gateway, so build owns none of its targets yet. + await editGateway(root, (gateway) => + gateway.targets.push(userTarget("egress-mine", "https://mine.example.com")), + ); + + await build(manager, root); + + expect(await targetNames(root)).toEqual(["egress-mine", "bedrock", "agentcore"]); + expect(JSON.parse(await text(root, "agentcore/box-gateway-targets.json"))).toEqual({ + [GATEWAY]: [], + }); + // The Runtime profile routes the user's target, as a target build does not own. + const egress = (await runtimeProfile(root)).egress as Record< + string, + { destinations: string[] } + >; + expect(egress["egress-mine"]?.destinations).toEqual(["mine.example.com"]); + }); + + test("takes the old egress- targets of a gateway that an older CLI made, one time", async () => { + const { manager, root } = await strandsProject(); + // A project of an older CLI has no record, and build wrote egress-old for a host it has left. + await rm(path(root, "agentcore/box-gateway-targets.json")); + await editGateway(root, (gateway) => + gateway.targets.push(userTarget("egress-old", "https://old.example.com")), + ); + + const first = await build(manager, root); + expect(await targetNames(root)).toEqual(["bedrock", "agentcore"]); + expect(first.steps).toContain( + `removing gateway target 'egress-old' from '${GATEWAY}': the Box profile no longer allows ` + + "old.example.com", + ); + expect(JSON.parse(await text(root, "agentcore/box-gateway-targets.json"))).toEqual({ + [GATEWAY]: [], + }); + + // Once the record names the gateway, a user's egress- target of the shape build writes stays. + await editGateway(root, (gateway) => + gateway.targets.push(userTarget("egress-mine", "https://mine.example.com")), + ); + await build(manager, root); + expect(await targetNames(root)).toEqual(["bedrock", "agentcore", "egress-mine"]); + }); + test("changes nothing on a second build", async () => { const { manager, root, counter, box } = await strandsProject({ env: { GITHUB_TOKEN: "ghp_123" }, @@ -450,13 +531,13 @@ describe("build writes the Box network of the box profile", () => { }); box.answer = boxShowOf({ egress: { bedrock: BEDROCK }, mcp: { tools } }); - const { steps } = await build(manager, root); + const { warnings } = await build(manager, root); expect(await targetNames(root)).toEqual(["bedrock", "agentcore"]); - expect(steps).toContain( - `not adding gateway target 'egress-tools' of '${GATEWAY}' for tools.example.com: it sends ` + - "the key of env://TOOLS_TOKEN, and agentcore.json has no API key credential 'tools' " + - "to hold it", + expect(warnings).toContain( + "tools.example.com: build gives [mcp.tools] no gateway target, so the agent cannot reach " + + `this host on AgentCore Runtime. TOOLS_TOKEN is not set here or in ${ENV_LOCAL_RELATIVE_PATH}. ` + + "Set TOOLS_TOKEN, or AGENTCORE_CREDENTIAL_TOOLS, and build again.", ); // With no target, the Runtime profile has no [mcp.tools] server, as it has no route above. expect((await runtimeProfile(root)).mcp).toBeUndefined(); diff --git a/src/core/project/manager.tsx b/src/core/project/manager.tsx index 480709beb..008fd3e7b 100644 --- a/src/core/project/manager.tsx +++ b/src/core/project/manager.tsx @@ -58,6 +58,14 @@ import { boxGatewayIamWarnings, type BoxNetwork } from "./boxNetwork"; import { boxNetworkFailureMessage, readBoxNetworks } from "./boxNetworkSource"; import { DEFAULT_REGION, regionFromConfigFile } from "../region"; import { BoxCliProfileResolver, type BoxProfileResolver } from "./boxProfileResolver"; +import { + addBoxGatewaysToRecord, + BOX_GATEWAY_TARGETS_FILE, + FS_RECORD_FILES, + removeBoxGatewaysFromRecord, + type RecordFiles, + type RestoreRecord, +} from "./boxGatewayTargets"; import { BOX_NETWORK_WRITERS, boxNetworkEdits, writeBoxNetworkFiles } from "./boxNetworkWriters"; import { createProjectTree } from "./templates/project"; import { @@ -428,6 +436,8 @@ type ProjectManagerConfig = { runner?: ProcessRunner; checkTool?: typeof requireTool; json?: ReadWriteJson; + /** How the record of build's targets is written; the file on disk by default. */ + recordFiles?: RecordFiles; /** * The environment the CDK backend reads HOME (the box cache) from, and build reads box `env://` * egress secrets from; process.env by default. @@ -458,6 +468,7 @@ export class FsProjectManager implements ProjectManager { private readonly runner: ProcessRunner; private readonly checkTool: typeof requireTool; private readonly json: ReadWriteJson; + private readonly recordFiles: RecordFiles; private readonly backends: Partial>; private readonly resolveAccount: (region: string) => Promise; private readonly processEnv: NodeJS.ProcessEnv; @@ -469,6 +480,7 @@ export class FsProjectManager implements ProjectManager { this.runner = config.runner ?? runProcess; this.checkTool = config.checkTool ?? requireTool; this.json = config.json ?? new FsReadWriteJson({ logger: config.logger }); + this.recordFiles = config.recordFiles ?? FS_RECORD_FILES; this.backends = config.backends ?? { CDK: new CdkBackend({ logger: config.logger, @@ -1072,17 +1084,30 @@ export class FsProjectManager implements ProjectManager { yield { type: "step", message: `updating project spec file at '${agentCoreSpecPath}'` }; let newProjectSpec: z.infer; + let restoreRecord: RestoreRecord | undefined; try { const newSpecParseResult = ProjectSpecSchema.safeParse(projectSpec); if (!newSpecParseResult.success) throw new ProjectStateError(z.prettifyError(newSpecParseResult.error), { cause: newSpecParseResult.error, }); + // Build owns no target of a new Box gateway yet: an empty entry in the record says so. The + // record changes first, and goes back when agentcore.json cannot take the gateway. + if (input.resourceType === "runtime") { + restoreRecord = addBoxGatewaysToRecord( + project.rootPath, + newSpecParseResult.data.agentCoreGateways.flatMap(({ name, boundRuntime }) => + boundRuntime === input.resourceConfig.name ? [name] : [], + ), + this.recordFiles, + ); + } newProjectSpec = await this.json.write(agentCoreSpecPath, newSpecParseResult.data); } catch (err) { this.logger.warn( `could not commit the spec update to ${agentCoreSpecPath}; attempting best-effort cleanup of staged changes`, ); + this.restoreRecord(restoreRecord); await Promise.all([ this.discardStaged(scaffoldedPaths), envFile?.rollback().catch((e) => { @@ -1101,9 +1126,11 @@ export class FsProjectManager implements ProjectManager { newProjectSpec, newProjectSpec.runtimes.filter(({ name }) => name === added), ); - yield* boxGatewayLogsWarnings( - newProjectSpec.agentCoreGateways.filter(({ boundRuntime }) => boundRuntime === added), + const boxGateways = newProjectSpec.agentCoreGateways.filter( + ({ boundRuntime }) => boundRuntime === added, ); + yield* boxGatewayLogsWarnings(boxGateways); + if (restoreRecord) yield { type: "step", message: `writing ${BOX_GATEWAY_TARGETS_FILE}` }; } return { @@ -1112,6 +1139,18 @@ export class FsProjectManager implements ProjectManager { }; } + /** Puts the record of build's targets back after a failed spec write; a failure is logged. */ + private restoreRecord(restore: RestoreRecord | undefined): void { + try { + restore?.(); + } catch (e) { + const error = AgentCoreCLIError.fromError(e); + this.logger + .child({ errorName: error.name, errorMessage: error.message }) + .warn(`failed to restore ${BOX_GATEWAY_TARGETS_FILE}`); + } + } + /** Best-effort removal of paths an add created; failures are logged, not thrown. */ private async discardStaged(paths: string[]): Promise { // A path inside another one goes with it. Removing both at the same time races: the @@ -1288,7 +1327,14 @@ export class FsProjectManager implements ProjectManager { } } - const newProjectSpec = await this.commitSpec(agentCoreSpecPath, newSpec, envFile); + // A Box gateway that goes takes its entry in the record of build's targets with it. + const newProjectSpec = await this.commitSpec(agentCoreSpecPath, newSpec, envFile, () => + removeBoxGatewaysFromRecord( + project.rootPath, + removedGateways.map(({ name }) => name), + this.recordFiles, + ), + ); // Build and deploy generate the runtime's .box//aws/ folder, so it goes with the runtime. // Its .box//local/ profile is the user's, as its code folder is, so it stays. if (input.resourceType === "runtime") { @@ -1344,7 +1390,13 @@ export class FsProjectManager implements ProjectManager { payments: undefined, }; - const newProjectSpec = await this.commitSpec(agentCoreSpecPath, newSpec, envFile); + const newProjectSpec = await this.commitSpec(agentCoreSpecPath, newSpec, envFile, () => + removeBoxGatewaysFromRecord( + project.rootPath, + existingProjectSpec.agentCoreGateways.map(({ name }) => name), + this.recordFiles, + ), + ); return { project: { ...project, spec: newProjectSpec }, @@ -1354,19 +1406,27 @@ export class FsProjectManager implements ProjectManager { // Validates and writes an updated spec; a failure rolls back any .env.local // edit staged for the same removal so the two files stay consistent. + /** + * Writes `newSpec` to agentcore.json. `changeRecord` changes the record of build's targets just + * before the write. When either fails, the record and `envFile` go back to what they were. + */ private async commitSpec( agentCoreSpecPath: string, newSpec: unknown, envFile: EnvLocalFile | undefined, + changeRecord?: () => RestoreRecord | undefined, ): Promise> { + let restoreRecord: RestoreRecord | undefined; try { const newSpecParseResult = ProjectSpecSchema.safeParse(newSpec); if (!newSpecParseResult.success) throw new InputValidationError(z.prettifyError(newSpecParseResult.error), { cause: newSpecParseResult.error, }); + restoreRecord = changeRecord?.(); return await this.json.write(agentCoreSpecPath, newSpecParseResult.data); } catch (err) { + this.restoreRecord(restoreRecord); await envFile?.rollback().catch((e) => { const error = AgentCoreCLIError.fromError(e); this.logger @@ -1680,12 +1740,13 @@ export class FsProjectManager implements ProjectManager { throw new InputValidationError(boxNetworkFailureMessage(networks, command)); } const envLocal = new EnvLocalFile(project.rootPath); - const edits = boxNetworkEdits(BOX_NETWORK_WRITERS, networks, { + const context = { spec: project.spec, projectRoot: project.rootPath, env: this.processEnv, envLocal: networks.length > 0 ? await envLocal.read() : {}, - }); + }; + const edits = boxNetworkEdits(BOX_NETWORK_WRITERS, networks, context); const messages = [...edits.messages]; let result = project; if (edits.specChanged) { @@ -1722,10 +1783,13 @@ export class FsProjectManager implements ProjectManager { const { written } = await envLocal.upsert([...edits.envLocal]); for (const key of written) messages.push(`writing ${key} to ${ENV_LOCAL_RELATIVE_PATH}`); } - const warnings = networks.flatMap((network) => [ - ...network.warnings, - ...boxGatewayIamWarnings(edits.spec, network), - ]); + const warnings = [ + ...networks.flatMap((network) => [ + ...network.warnings, + ...boxGatewayIamWarnings(edits.spec, network), + ]), + ...edits.warnings, + ]; const events: ProjectEvent[] = [ ...messages.map((message) => ({ type: "step" as const, message })), ...warnings.map((message) => ({ type: "warning" as const, message })), diff --git a/src/core/project/runtimeProfile/derive.test.ts b/src/core/project/runtimeProfile/derive.test.ts index eaec6ce02..5f68026d8 100644 --- a/src/core/project/runtimeProfile/derive.test.ts +++ b/src/core/project/runtimeProfile/derive.test.ts @@ -29,6 +29,7 @@ const context = (runtime: ProjectRuntime, places = new Map()) => gateway: { name: "agent-box-egress", targets: [] }, hosts: [], telemetry: [], + ruleIds: new Set(), places, }); diff --git a/src/core/project/runtimeProfile/rules/additions.test.ts b/src/core/project/runtimeProfile/rules/additions.test.ts index b0327d932..f4abae978 100644 --- a/src/core/project/runtimeProfile/rules/additions.test.ts +++ b/src/core/project/runtimeProfile/rules/additions.test.ts @@ -101,6 +101,7 @@ function contextOf( }, hosts: [], telemetry: options.telemetry ?? [], + ruleIds: new Set(), places: new Map(), }); } diff --git a/src/core/project/runtimeProfile/rules/gateway.test.ts b/src/core/project/runtimeProfile/rules/gateway.test.ts index 585b2e30d..c67ccc6e4 100644 --- a/src/core/project/runtimeProfile/rules/gateway.test.ts +++ b/src/core/project/runtimeProfile/rules/gateway.test.ts @@ -104,6 +104,7 @@ function contextOf( hosts: BoxNetworkHost[], targets: AgentCoreGatewayTarget[] = [], region = "us-west-2", + ruleIds: ReadonlySet = new Set(), ) { return runtimeProfileContext({ spec: project(targets), @@ -113,6 +114,7 @@ function contextOf( gateway: { name: GATEWAY, targets }, hosts, telemetry: [], + ruleIds, places: profileKeyPlaces(text, PROFILE), }); } @@ -123,8 +125,9 @@ function gateway( hosts: BoxNetworkHost[], targets: AgentCoreGatewayTarget[] = [], region?: string, + ruleIds?: ReadonlySet, ) { - return apply(parse(text) as TomlTable, contextOf(text, hosts, targets, region)); + return apply(parse(text) as TomlTable, contextOf(text, hosts, targets, region, ruleIds)); } /** @@ -267,6 +270,49 @@ describe("the gateway rule", () => { expect(Object.keys(table.egress as TomlTable).sort()).toEqual(["egress-orders", "orders"]); }); + describe("names no route so that box adds a rule with the @id of a rule of the policy", () => { + test("for an entry whose route takes the name of its target", () => { + const { table } = gateway( + '[egress.api]\ndestinations = ["api.example.com"]\n', + [host("api.example.com", entry("api", "api.example.com"), "egress-api")], + [passthrough("api", "https://orders.example.com")], + undefined, + new Set(["route_egress-api_request"]), + ); + + // The user's own target `api` keeps the route `api`. + expect(Object.keys(table.egress as TomlTable)).toEqual(["egress-api-2", "api"]); + expect(table.egress).toMatchObject({ + "egress-api-2": { backends: [{ url: "${{ inputs.gateway.url }}/egress-api" }] }, + }); + }); + + test("for each other host of an entry, and past a name that another route has", () => { + const { table } = gateway( + '[egress.models]\ndestinations = ["one.example.com", "two.example.com"]\n' + + '[egress.egress-models-two-2]\ndestinations = ["three.example.com"]\n', + [ + host("one.example.com", entry("models", "one.example.com"), "egress-models-one"), + host("two.example.com", entry("models", "two.example.com"), "egress-models-two"), + host( + "three.example.com", + entry("egress-models-two-2", "three.example.com"), + "egress-egress-models-two-2", + ), + ], + [], + undefined, + new Set(["route_egress-models-two_connect"]), + ); + + expect(Object.keys(table.egress as TomlTable)).toEqual([ + "models", + "egress-models-two-3", + "egress-models-two-2", + ]); + }); + }); + test("gives each host of an entry with several destinations its own route, signed for the Runtime's region and not the build region", () => { const text = '[egress.models]\ndestinations = ["api.one.example.com", "api.two.example.com:8443/v1"]\n'; @@ -616,6 +662,7 @@ describe("the gateway rule and the Runtime renderer it replaced", () => { gateway: { name: GATEWAY, targets }, hosts: network.hosts, telemetry: [], + ruleIds: new Set(), places: profileKeyPlaces(text, PROFILE), }), ); @@ -628,6 +675,22 @@ describe("the gateway rule and the Runtime renderer it replaced", () => { ), ); + test("give a route a free name when a rule of the policy has the @id of its route rule", () => { + const own = + '@id("route_egress-models-api-two-example-com_request")\n' + + 'permit (principal, action == Box::Action::"http:request", resource) when { ' + + 'context.input.host == "api.two.example.com" };\n'; + const { network } = bothProfiles(project(TARGETS, ["agentMemory"]), { + ...FIXTURE, + policy: FIXTURE.policy + own, + }); + + expect(network.failures).toEqual([]); + const keys = Object.keys(network.runtimeProfile?.egress as TomlTable); + expect(keys).toContain("egress-models-api-two-example-com-2"); + expect(keys).not.toContain("egress-models-api-two-example-com"); + }); + test("give the same [egress] and HTTP [mcp] tables on the first build", () => { const { network, derived } = bothProfiles(project(TARGETS, ["agentMemory"])); const old = rendered("first build"); diff --git a/src/core/project/runtimeProfile/rules/gateway.ts b/src/core/project/runtimeProfile/rules/gateway.ts index 321e267b6..1cd9dd75a 100644 --- a/src/core/project/runtimeProfile/rules/gateway.ts +++ b/src/core/project/runtimeProfile/rules/gateway.ts @@ -43,6 +43,7 @@ interface GatewayRoute { export function apply(table: Readonly, context: RuntimeProfileContext): RuleResult { const routes = gatewayRoutes(context); + const keys = routeKeys(routes, context); const written = new Set(); const egress: TomlTable = {}; @@ -55,7 +56,7 @@ export function apply(table: Readonly, context: RuntimeProfileContext host.sources.some((source) => source.kind === "entry" && source.egressEntry === name), ); for (const route of routesOf(hosts, routes)) { - egress[routeKey(route, routes, context)] = egressRoute(entry, route); + egress[keys.get(route.target)!] = egressRoute(entry, route); written.add(route.target); } } @@ -77,7 +78,7 @@ export function apply(table: Readonly, context: RuntimeProfileContext if (route.server) { mcp[route.server.mcpEntry] = mcpServer({}, route, route.server); } else { - egress[routeKey(route, routes, context)] = egressRoute({}, route); + egress[keys.get(route.target)!] = egressRoute({}, route); } } @@ -92,12 +93,14 @@ export function apply(table: Readonly, context: RuntimeProfileContext /** * The routes of the runtime: one for each passthrough target of its Box gateway, in the order of * the gateway's targets once build writes them. Build keeps each target it does not manage where - * it is, keeps each `egress-` target that a host takes, removes the other `egress-` targets, and + * it is, keeps each target it manages that a host takes, removes the other targets it manages, and * adds the target of each other host at the end. Throws for two targets for one host, which would * give the box two routes to that host. */ function gatewayRoutes(context: RuntimeProfileContext): GatewayRoute[] { - const managed = (name: string) => name.startsWith(BOX_EGRESS_TARGET_PREFIX); + const owned = context.gateway.managed; + const managed = (name: string) => + owned ? owned.has(name) : name.startsWith(BOX_EGRESS_TARGET_PREFIX); const served = context.hosts.filter( (host): host is BoxNetworkHost & { readonly target: string } => host.target !== undefined && managed(host.target), @@ -171,6 +174,31 @@ function routeKey( return name; } +/** + * The `[egress]` key of each route that serves no HTTP MCP server, by its target: its + * {@link routeKey}, or that key with `-2`, `-3`, and so on after it when box would add a route rule + * with the `@id` of a rule of the policy. A key that another route has stays that route's. + */ +function routeKeys( + routes: readonly GatewayRoute[], + context: RuntimeProfileContext, +): Map { + const named = routes + .filter((route) => route.server === undefined) + .map((route) => ({ route, key: routeKey(route, routes, context) })); + const used = new Set(named.map(({ key }) => key)); + const taken = (key: string) => + context.ruleIds.has(`route_${key}_connect`) || context.ruleIds.has(`route_${key}_request`); + const keys = new Map(); + for (const { route, key } of named) { + let free = key; + for (let n = 2; taken(free) || (free !== key && used.has(free)); n++) free = `${key}-${n}`; + used.add(free); + keys.set(route.target, free); + } + return keys; +} + /** The routes of `hosts`, in the order of the hosts; a host with no route has none. */ function routesOf( hosts: readonly BoxNetworkHost[], diff --git a/src/core/project/runtimeProfile/rules/paths.test.ts b/src/core/project/runtimeProfile/rules/paths.test.ts index 075d6e1c3..183cd7b27 100644 --- a/src/core/project/runtimeProfile/rules/paths.test.ts +++ b/src/core/project/runtimeProfile/rules/paths.test.ts @@ -32,6 +32,7 @@ const contextOf = (text: string, runtime: ProjectRuntime = CODEZIP) => gateway: { name: "agent-box-egress", targets: [] }, hosts: [], telemetry: [], + ruleIds: new Set(), places: profileKeyPlaces(text, PROFILE), }); diff --git a/src/core/project/runtimeProfile/rules/refusals.test.ts b/src/core/project/runtimeProfile/rules/refusals.test.ts index ed1720f94..bff1b0522 100644 --- a/src/core/project/runtimeProfile/rules/refusals.test.ts +++ b/src/core/project/runtimeProfile/rules/refusals.test.ts @@ -34,6 +34,7 @@ const contextOf = (text: string, runtime: ProjectRuntime = CODEZIP) => hosts: [], telemetry: withDeployRegion(cloudWatchTelemetry(parse(text) as TomlTable), "us-west-2", PROFILE) .telemetry, + ruleIds: new Set(), places: profileKeyPlaces(text, PROFILE), }); diff --git a/src/core/project/runtimeProfile/types.ts b/src/core/project/runtimeProfile/types.ts index 777c650b5..872386fda 100644 --- a/src/core/project/runtimeProfile/types.ts +++ b/src/core/project/runtimeProfile/types.ts @@ -69,11 +69,22 @@ export interface RuntimeProfileContext { /** The region build builds for: of the Box gateway and its `bedrock` and `agentcore` targets. */ readonly region: string; /** The runtime's Box gateway: its name, and its targets with the ones build adds. */ - readonly gateway: { readonly name: string; readonly targets: readonly AgentCoreGatewayTarget[] }; + readonly gateway: { + readonly name: string; + readonly targets: readonly AgentCoreGatewayTarget[]; + /** The targets build owns (`BoxNetwork.managedTargets`); absent: each `egress-` target. */ + readonly managed?: ReadonlySet; + }; /** The hosts of the Box network model, each with the gateway target it gets. */ readonly hosts: readonly BoxNetworkHost[]; /** The CloudWatch targets of the local profile, with the deploy region set. */ readonly telemetry: readonly CloudWatchTelemetry[]; + /** + * The `@id` of each rule of the local policy that box does not add for a route or a server. Box + * adds `route__connect` and `route__request` for each route, and refuses a second + * rule with the same `@id`. + */ + readonly ruleIds: ReadonlySet; readonly paths: RuntimePaths; /** * The profile that `agentcore create` writes for this runtime, `local`, and its Runtime form, diff --git a/src/core/project/templates/boxProfile.ts b/src/core/project/templates/boxProfile.ts index 724cc560b..c796b25d4 100644 --- a/src/core/project/templates/boxProfile.ts +++ b/src/core/project/templates/boxProfile.ts @@ -285,25 +285,6 @@ const GEMINI: ApiKeyRoute = { }; const OPENAI_COMPATIBLE_ROUTE = "openai-compatible"; -/** - * The `[egress.]` routes `agentcore create` writes for a model provider's API key. Their key - * is the project's model-provider credential, which `create` declares when it is given a key, or - * else a provider variable that LiteLLM reads; build does not declare a credential for them. - */ -export const MODEL_PROVIDER_EGRESS_ROUTES: ReadonlySet = new Set([ - OPENAI.name, - ANTHROPIC.name, - GEMINI.name, - OPENAI_COMPATIBLE_ROUTE, -]); - -/** The provider variables a model-provider route reads its key from when `create` had no key. */ -export const MODEL_PROVIDER_KEY_VARIABLES: ReadonlySet = new Set( - [OPENAI, ANTHROPIC, GEMINI].flatMap(({ providerVariable }) => - providerVariable === undefined ? [] : [providerVariable], - ), -); - /** * The route the agent's model calls take when they carry an API key, or * `undefined` when the agent calls Bedrock, calls no model, or calls a host the diff --git a/src/core/project/templates/project.ts b/src/core/project/templates/project.ts index 289a98e30..518928788 100644 --- a/src/core/project/templates/project.ts +++ b/src/core/project/templates/project.ts @@ -8,6 +8,7 @@ import type { import { InputValidationError } from "../../../errors/errors"; import { getRuntimeTemplateResolver } from "./runtime"; import { BOX_RELEASE } from "../backends/boxRelease"; +import { BOX_GATEWAY_TARGETS_NAME } from "../boxGatewayTargets"; import { BOX_CODEZIP_ENTRYPOINT, hasBoxProfile, @@ -62,6 +63,14 @@ export async function createProjectTree( const envEntries = templates.flatMap((template) => template.envEntries ?? []); const boxProject = options?.runtime !== undefined && hasBoxProfile(options.runtime); + const spec = newProjectSpec( + input.projectName, + templates.map(({ spec }) => spec), + ); + // Build owns no target of a new Box gateway yet: an empty entry in the record says so. + const boxGateways = (spec.agentCoreGateways ?? []).flatMap(({ name, boundRuntime }) => + boundRuntime === undefined ? [] : [name], + ); const tree = FsTreeNode.createDirectory(".", [ FsTreeNode.createFile(".gitignore", async () => { const shared = await config.assetSource.read("templates/shared/gitignore.template"); @@ -69,14 +78,15 @@ export async function createProjectTree( }), FsTreeNode.createDirectory("agentcore", [ await FsTreeNode.fromAssetSource({ assetSource: config.assetSource }, { assetDir: "cdk" }), - FsTreeNode.createFile("agentcore.json", async () => - json( - newProjectSpec( - input.projectName, - templates.map(({ spec }) => spec), - ), - ), - ), + // The record comes first: a failed write of either file leaves no project with one alone. + ...(boxGateways.length > 0 + ? [ + FsTreeNode.createFile(BOX_GATEWAY_TARGETS_NAME, async () => + json(Object.fromEntries(boxGateways.map((name) => [name, []]))), + ), + ] + : []), + FsTreeNode.createFile("agentcore.json", async () => json(spec)), FsTreeNode.createFile("aws-targets.json", async () => json([])), FsTreeNode.createFile(".env.local", () => config.assetSource.read("templates/shared/env.local.template"), diff --git a/src/handlers/project/shortcuts.ts b/src/handlers/project/shortcuts.ts index a1140608c..1e89dd3fd 100644 --- a/src/handlers/project/shortcuts.ts +++ b/src/handlers/project/shortcuts.ts @@ -1,4 +1,3 @@ -import { partition } from "@aws-sdk/util-endpoints"; import z from "zod"; import { DEFAULT_EPISODIC_REFLECTION_NAMESPACE_TEMPLATES, @@ -6,6 +5,10 @@ import { defaultMemoryName, type Memory, } from "../../projectSchemas/memory"; +import { + boxGatewayAgentCoreHost, + boxGatewayBedrockHost as bedrockHostOf, +} from "../../core/project/boxNetwork/egress"; import { InputValidationError } from "../../errors"; import type { AgentCoreGatewayTarget } from "../../projectSchemas/gateway"; import { DEFAULT_MODEL_IDS } from "../../projectSchemas/runtime"; @@ -41,7 +44,7 @@ export const BOX_GATEWAY_BEDROCK_TARGET_NAME = "bedrock"; /** The Bedrock runtime host of `region`, which the Box gateway's Bedrock model target fronts. */ export function boxGatewayBedrockHost(region: string = DEFAULT_EGRESS_BEDROCK_REGION): string { - return `bedrock-runtime.${region}.${partition(region).dnsSuffix}`; + return bedrockHostOf(region); } /** The Box gateway's passthrough target for the Bedrock model endpoint, signed with its role. */ @@ -62,11 +65,6 @@ export function getBoxGatewayBedrockTargetSpec( */ export const BOX_GATEWAY_AGENTCORE_TARGET_NAME = "agentcore"; -/** The AgentCore data-plane host of `region`, which the Box gateway's AgentCore target fronts. */ -export function boxGatewayAgentCoreHost(region: string = DEFAULT_EGRESS_BEDROCK_REGION): string { - return `bedrock-agentcore.${region}.${partition(region).dnsSuffix}`; -} - /** * The Box gateway's passthrough target for the AgentCore data plane (Memory), * signed with the gateway's role. diff --git a/src/projectSchemas/project.test.ts b/src/projectSchemas/project.test.ts index d643bb33d..683e5a378 100644 --- a/src/projectSchemas/project.test.ts +++ b/src/projectSchemas/project.test.ts @@ -594,6 +594,55 @@ describe("Box project gateways", () => { }); }); +describe("Box runtimes and the folder build stages box in", () => { + const boxed = (name: string, rest: Record = {}) => ({ + ...runtime, + name, + box: { version: "0.1.11-preview.10" }, + ...rest, + }); + const parse = (runtimes: { name: string }[]) => + ProjectSpecSchema.safeParse({ + ...minimalProject, + projectType: "box", + runtimes, + agentCoreGateways: runtimes.map(({ name }) => boxGatewaySpec(name)), + }); + const messages = (result: ReturnType) => + result.success ? [] : result.error.issues.map(({ message }) => message); + + test("rejects two box runtimes in one folder, however the path is written", () => { + expect( + messages( + parse([ + boxed("agent", { codeLocation: "./app/agent" }), + boxed("search", { codeLocation: "app/agent/" }), + ]), + ), + ).toEqual([ + 'Runtimes "agent" and "search" both run in a box from the folder app/agent, and build ' + + "stages the box of each in app/agent/.box-dist. Give each runtime its own folder.", + ]); + }); + + test("rejects a container runtime whose build context is the code folder of another", () => { + const container = boxed("image", { + build: "Container", + codeLocation: "./image", + buildContextPath: "./app/agent", + }); + expect(messages(parse([boxed("agent", { codeLocation: "app/agent" }), container]))).toEqual([ + 'Runtimes "agent" and "image" both run in a box from the folder app/agent, and build ' + + "stages the box of each in app/agent/.box-dist. Give each runtime its own folder.", + ]); + }); + + test("accepts one folder for a box runtime and a runtime that runs in no box", () => { + const plain = { ...runtime, name: "plain", codeLocation: "app/agent" }; + expect(parse([boxed("agent", { codeLocation: "app/agent" }), plain]).success).toBe(true); + }); +}); + describe("gateway variable prefixes", () => { const parse = (agentCoreGateways: unknown[]) => ProjectSpecSchema.safeParse({ ...minimalProject, runtimes: [runtime], agentCoreGateways }); diff --git a/src/projectSchemas/project.ts b/src/projectSchemas/project.ts index d0c472422..3cde3ae48 100644 --- a/src/projectSchemas/project.ts +++ b/src/projectSchemas/project.ts @@ -31,6 +31,29 @@ export const ProjectNameSchema = z export const ProjectTypeSchema = z.enum(["box"]); /** Whether the project is a Box project, so the CLI keeps a Box gateway for each runtime. */ export const isBoxProject = (spec: { projectType?: string }) => spec.projectType === "box"; + +/** + * The folder, from the project root, that build stages the box of a box runtime in: the code + * folder of a CodeZip runtime, and the build context of a container runtime. + */ +function boxFolderOf(runtime: { + readonly build: string; + readonly codeLocation: string; + readonly buildContextPath?: string; +}): string { + const folder = + runtime.build === "Container" + ? (runtime.buildContextPath ?? runtime.codeLocation) + : runtime.codeLocation; + const parts: string[] = []; + for (const part of folder.replace(/\\/g, "/").split("/")) { + if (part === "" || part === ".") continue; + if (part === ".." && parts.length > 0 && parts.at(-1) !== "..") parts.pop(); + else parts.push(part); + } + return parts.length > 0 ? parts.join("/") : "."; +} + /** The suffix of each Box gateway name: the runtime `agent` gets the gateway `agent-box-egress`. */ export const BOX_GATEWAY_SUFFIX = "-box-egress"; /** @@ -164,6 +187,27 @@ export const ProjectSpecSchema = z // 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. if (isBoxProject(spec)) { + // Build stages the box of each box runtime in .box-dist of its folder, so two in one folder + // would write one file twice. + const byFolder = new Map(); + for (const runtime of spec.runtimes) { + if (runtime.box === undefined) continue; + const folder = boxFolderOf(runtime); + const other = byFolder.get(folder); + if (other === undefined) { + byFolder.set(folder, runtime.name); + continue; + } + ctx.addIssue({ + code: "custom", + message: + `Runtimes "${other}" and "${runtime.name}" both run in a box from the folder ` + + `${folder}, and build stages the box of each in ` + + `${folder === "." ? "" : `${folder}/`}.box-dist. ` + + "Give each runtime its own folder.", + path: ["runtimes"], + }); + } const bound = new Set(spec.agentCoreGateways.map((gateway) => gateway.boundRuntime)); for (const runtime of spec.runtimes) { if (bound.has(runtime.name)) continue;