Support build-time secrets / private package index auth (e.g. CodeArtifact) for container builds

[orangewise]

Description

There's no first-class way to pass a build-time secret — e.g. an AWS CodeArtifact auth token — into the container image build, for private Python packages that aren't on PyPI.

The only seam today is uvDefaultIndex / uvIndex in ~/.agentcore/config.json, emitted as --build-arg UV_DEFAULT_INDEX/UV_INDEX (src/lib/packaging/build-args.ts). This is used by agentcore dev (src/cli/operations/dev/container-dev-server.ts) and agentcore package (src/lib/packaging/container.ts). It has three problems:

1. Breaks layer caching — a CodeArtifact token rotates (≤12h) and rides inside the index URL, so the --build-arg value changes every build → the dependency-install layer is invalidated on every build.
2. Leaks the token into the image — passed as a build arg, it gets baked in when the Dockerfile does ENV UV_*=${UV_*} (as the generated template does).
3. No local/deploy parity — the deploy path builds via CodeBuild (in @aws/agentcore-cdk) with a hardcoded buildspec that passes no build args and whose role has no CodeArtifact permissions, so private-index builds that work in dev fail on deploy. The CDK build is also a getOrCreate() singleton with an inline buildspec and no extension hook, forcing consumers to patch the synthesized CfnProject via a CDK Aspect.

The proper pattern (generate a fresh token at build time and pass it via a BuildKit secret mount, RUN --mount=type=secret,…) keeps the token out of the cache key and out of the image — but the CLI passes no --secret flag to docker build, so it isn't reachable today.

Acceptance Criteria

• A way to supply build-time secrets (e.g. buildSecrets) that wires BuildKit secret mounts (docker build --secret id=…) into the build, so Dockerfiles can use RUN --mount=type=secret,id=… ….
• The same configuration is honored by both agentcore dev/package (local build) and agentcore deploy (CodeBuild via @aws/agentcore-cdk), so behavior is identical across local and deploy.
• For the CodeBuild path: the build role can be granted the needed permissions (e.g. codeartifact:GetAuthorizationToken, GetRepositoryEndpoint, ReadFromRepository, sts:GetServiceBearerToken), and a fresh token can be obtained at build time rather than passed in from outside.
• Secrets do not appear in the final image (no ENV/layer leakage) and do not invalidate the dependency layer cache on rotation.
• Documented in docs/configuration.md.
• (Minimal acceptable alternative): arbitrary --build-arg / --secret pass-through honored by both build paths. (The build-arg half of this overlaps with feat(config): support shared Dockerfile via buildContextPath and customDockerBuildArgs in agentcore.json #1236's customDockerBuildArgs; secrets, parity and CodeBuild perms are the parts that issue doesn't cover.)

Related issues

• feat(config): support shared Dockerfile via buildContextPath and customDockerBuildArgs in agentcore.json #1236 (feat(config): support shared Dockerfile via buildContextPath and customDockerBuildArgs in agentcore.json) — requests arbitrary build-arg passthrough via agentcore.json. That covers the build-arg half of the minimal alternative above. This request is complementary: it adds BuildKit secret mounts (token out of the image and out of the cache key — a build-arg can't do that), local↔deploy parity through the CodeBuild path in @aws/agentcore-cdk, and the CodeBuild IAM perms + fetch-token-at-build-time that a build-arg surface alone leaves unsolved. If customDockerBuildArgs lands, that's the natural place for a sibling buildSecrets key.
• Documentation: .env.local only works for agentcore dev, not agentcore deploy #1378 (.env.local only works for agentcore dev, not agentcore deploy) — independent confirmation of the same local↔deploy asymmetry, on the runtime env-var side. The build-time token has the analogous gap.

Additional Context

• Optionally, native CodeArtifact support (codeArtifact: { domain, owner, repository }) that fetches a token in pre_build and exposes it to the build as a secret would cover the most common case directly.
• The CodeBuild side lives in @aws/agentcore-cdk (source repo aws/agentcore-l3-cdk-constructs, not public at time of writing), maintained by the same team — so a complete fix likely spans both, ideally a single CLI-level config that flows into the generated CDK.
• Is build-secret support already planned for the v1.0.0-preview line?
• Happy to contribute a PR if a design direction is agreed.