feat: create credential providers before synthesizing a deploy

src/core/project/backends/cdk.test.ts

@@ -1,12 +1,12 @@
 import { afterEach, describe, expect, test } from "bun:test";
-import { existsSync } from "node:fs";
 import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { tmpdir } from "node:os";
 import type { DeployResult, Project, ProjectEvent } from "../../../handlers/project/types";
 import { ProjectSpecSchema } from "../../../projectSchemas/project";
 import { createSilentLogger } from "../../../testing";
 import { CdkBackend } from "./cdk";
+import type { CredentialProvisioner } from "./cdk/credentials";
 import { DEPLOYED_STATE_RELATIVE_PATH } from "./cdk/deployedState";
 import type { DeployBackendInput } from "./types";
 import type { BootstrapState } from "./cdk/environment";
@@ -120,6 +120,7 @@ type HarnessOptions = {
   template?: boolean;
   failOperation?: CdkOperation["kind"];
   bootstrapError?: Error;
+  provisionCredentials?: CredentialProvisioner;
   /** Whether CloudFormation still holds the target's stack. Defaults to present. */
   stackExists?: boolean;
 };
@@ -194,6 +195,7 @@ function harness(options: HarnessOptions = {}) {
         },
       };
     },
+    ...(options.provisionCredentials && { provisionCredentials: options.provisionCredentials }),
   });
 
   return {
@@ -312,22 +314,82 @@ describe("CdkBackend.deploy", () => {
     expect(JSON.parse(await Bun.file(statePath).text())).toEqual({
       targets: {
         default: {
+          resources: { credentials: {} },
           stackArn:
             "arn:aws:cloudformation:us-east-1:111122223333:stack/AgentCore-example-default/abc",
         },
       },
     });
   });
 
-  test("fails a deploy whose result carries no stack ARN, recording nothing", async () => {
+  test("provisions credentials before synth and records them under the target", async () => {
+    const input = await project();
+    await writeAssembly(input, [TARGET.name]);
+    const provisionCredentials: CredentialProvisioner = async function* () {
+      yield { message: "Preparing credential provider 'openai-key'" };
+      return { "openai-key": { credentialProviderArn: "arn:apikey:openai-key" } };
+    };
+    const subject = harness({
+      outputs: { RuntimeArn: "arn:runtime" },
+      stackArn: "arn:aws:cloudformation:us-east-1:111122223333:stack/AgentCore-example-default/abc",
+      provisionCredentials,
+    });
+
+    const deployed = await collectDeploy(subject.backend.deploy(input, deployInput()));
+
+    // The credential step runs (and its ARNs are recorded) before synthesis, so
+    // the assembly is synthesized against a state file that already describes them.
+    const messages = deployed.events.map((event) => event.message);
+    expect(messages.indexOf("Preparing credential provider 'openai-key'")).toBeLessThan(
+      messages.indexOf("Synthesizing CloudFormation templates"),
+    );
+
+    // The pre-synth credentials write and the post-deploy stack-ARN write merge
+    // into one target entry rather than clobbering each other.
+    const statePath = join(input.rootPath, DEPLOYED_STATE_RELATIVE_PATH);
+    expect(JSON.parse(await Bun.file(statePath).text())).toEqual({
+      targets: {
+        default: {
+          stackArn:
+            "arn:aws:cloudformation:us-east-1:111122223333:stack/AgentCore-example-default/abc",
+          resources: {
+            credentials: { "openai-key": { credentialProviderArn: "arn:apikey:openai-key" } },
+          },
+        },
+      },
+    });
+  });
+
+  test("fails a deploy whose result carries no stack ARN, recording no binding", async () => {
     const input = await project();
     await writeAssembly(input, [TARGET.name]);
     const subject = harness({ outputs: { RuntimeArn: "arn:runtime" }, omitStackArn: true });
 
     await expect(collectDeploy(subject.backend.deploy(input, deployInput()))).rejects.toThrow(
       /without a stack ARN/,
     );
-    expect(existsSync(join(input.rootPath, DEPLOYED_STATE_RELATIVE_PATH))).toBe(false);
+    // The pre-synth credentials write may have created the file, but the failed
+    // deploy must not have recorded a stack binding.
+    const state = JSON.parse(
+      await Bun.file(join(input.rootPath, DEPLOYED_STATE_RELATIVE_PATH)).text(),
+    );
+    expect(state.targets.default?.stackArn).toBeUndefined();
+  });
+
+  test("checks local CDK prerequisites before provisioning credentials", async () => {
+    const input = await project(false); // no agentcore/cdk/node_modules
+    let provisioned = false;
+    // eslint-disable-next-line require-yield -- a spy that should never run (deploy fails first)
+    const provisionCredentials: CredentialProvisioner = async function* () {
+      provisioned = true;
+      return {};
+    };
+    const subject = harness({ provisionCredentials });
+
+    await expect(collectDeploy(subject.backend.deploy(input, deployInput()))).rejects.toThrow(
+      /npm install/,
+    );
+    expect(provisioned).toBe(false);
   });
 
   test("fails before touching AWS when the existing state file is malformed", async () => {

src/core/project/backends/cdk.ts

@@ -13,6 +13,7 @@ import type { Logger } from "../../../logging";
 import type { DeployBackendInput, ProjectBackend } from "./types";
 import { createCloudFormationClient } from "../../factories";
 import type { CreateCloudFormationClient } from "../../types";
+import { createCredentialProvisioner, type CredentialProvisioner } from "./cdk/credentials";
 import {
   countDeployableResources,
   stackArtifactForTarget,
@@ -51,6 +52,7 @@ export type CdkBackendConfig = {
   stack?: StackProbe;
   resolveAccount?: AccountResolver;
   loadBootstrapTemplate?: BootstrapTemplateLoader;
+  provisionCredentials?: CredentialProvisioner;
 };
 
 /** Builds and deploys projects through the scaffolded CDK app. */
@@ -65,6 +67,7 @@ export class CdkBackend implements ProjectBackend {
   private readonly stack: StackProbe;
   private readonly resolveAccount: AccountResolver;
   private readonly loadBootstrapTemplate: BootstrapTemplateLoader;
+  private readonly provisionCredentials: CredentialProvisioner;
 
   constructor(config: CdkBackendConfig) {
     this.logger = config.logger;
@@ -86,24 +89,30 @@ export class CdkBackend implements ProjectBackend {
       ((stackName, region, credentials) => probeStack(stackName, region, credentials, readStack));
     this.resolveAccount = config.resolveAccount ?? resolveAwsAccount;
     this.loadBootstrapTemplate = config.loadBootstrapTemplate ?? loadBootstrapTemplate;
+    this.provisionCredentials = config.provisionCredentials ?? createCredentialProvisioner();
   }
 
-  public async *build(project: Project): AsyncGenerator<ProjectEvent, void> {
+  // Local prerequisites for synth. Checked before any AWS mutation so a missing
+  // toolchain or dependencies fails without having provisioned credentials.
+  private async ensureCdkDependencies(project: Project): Promise<void> {
     const cdkDir = this.cdkDirectory(project);
-
     if (!existsSync(join(cdkDir, "node_modules"))) {
       throw new ProjectStateError(
         `CDK dependencies are missing for project '${project.name}'. ` +
           `Run 'cd ${cdkDir} && npm install'.`,
       );
     }
     await this.checkTool("npm", "Install Node.js: https://nodejs.org/");
+  }
+
+  public async *build(project: Project): AsyncGenerator<ProjectEvent, void> {
+    await this.ensureCdkDependencies(project);
 
     yield { message: "Synthesizing CloudFormation templates" };
     await this.runner(
       ["npm", "run", "cdk", "--", "synth", "--quiet", "--output", this.assemblyDirectory(project)],
       {
-        cwd: cdkDir,
+        cwd: this.cdkDirectory(project),
         onOutput: (chunk) => this.logger.debug(chunk),
       },
     );
@@ -124,11 +133,24 @@ export class CdkBackend implements ProjectBackend {
       );
     }
 
-    // Validate any existing deployed state before mutating AWS. A malformed file
-    // must fail here — not after bootstrap/deploy — so we never leave AWS changed
-    // with the new stack ARN unrecorded because the post-deploy write can't parse it.
+    // Fail on local setup errors (missing toolchain/deps) and malformed state
+    // before any AWS mutation, so a local problem never leaves credentials
+    // provisioned or the stack ARN unrecorded.
+    await this.ensureCdkDependencies(project);
     await readDeployedState(this.json, project.rootPath);
 
+    // Credential providers aren't stack resources; the synthesized app reads their
+    // ARNs from deployed-state.json, so they must exist and be recorded before synth.
+    const provisioned = yield* this.provisionCredentials(project, {
+      credentials,
+      region: target.region,
+    });
+    // Recorded every deploy (even when empty) so dropping the last credential
+    // from the spec clears the stale entry instead of leaving it advertised.
+    await updateTargetState(this.json, project.rootPath, target.name, {
+      resources: { credentials: provisioned },
+    });
+
     yield* this.build(project);
     const assemblyDirectory = this.assemblyDirectory(project);
     const artifact = await stackArtifactForTarget(this.json, assemblyDirectory, target.name);

src/core/project/backends/cdk/credentials.client.test.ts

@@ -0,0 +1,192 @@
+import { afterEach, describe, expect, mock, test } from "bun:test";
+
+// credentials.test.ts drives the provisioner with a fake client; this covers the
+// real factory by mocking the AWS SDK it lazily imports.
+
+class ResourceNotFoundException extends Error {
+  constructor() {
+    super("not found");
+    this.name = "ResourceNotFoundException";
+  }
+}
+class GetApiKeyCredentialProviderCommand {
+  constructor(readonly input: unknown) {}
+}
+class CreateApiKeyCredentialProviderCommand {
+  constructor(readonly input: unknown) {}
+}
+class GetOauth2CredentialProviderCommand {
+  constructor(readonly input: unknown) {}
+}
+class CreateOauth2CredentialProviderCommand {
+  constructor(readonly input: unknown) {}
+}
+
+const sent: unknown[] = [];
+let send: (command: unknown) => Promise<unknown>;
+
+class BedrockAgentCoreControlClient {
+  constructor(readonly config: unknown) {}
+  send(command: unknown) {
+    sent.push(command);
+    return send(command);
+  }
+}
+
+mock.module("@aws-sdk/client-bedrock-agentcore-control", () => ({
+  BedrockAgentCoreControlClient,
+  GetApiKeyCredentialProviderCommand,
+  CreateApiKeyCredentialProviderCommand,
+  GetOauth2CredentialProviderCommand,
+  CreateOauth2CredentialProviderCommand,
+  ResourceNotFoundException,
+}));
+
+const { createIdentityProviderClient } = await import("./credentials");
+const credentials = async () => ({ accessKeyId: "a", secretAccessKey: "b" });
+
+afterEach(() => {
+  sent.length = 0;
+});
+
+describe("createIdentityProviderClient", () => {
+  test("passes region and credentials to the SDK client", async () => {
+    send = async () => ({ credentialProviderArn: "arn:cp" });
+    const client = await createIdentityProviderClient("eu-west-1", credentials);
+    await client.getApiKeyProvider("k");
+
+    expect((sent[0] as GetApiKeyCredentialProviderCommand).input).toEqual({ name: "k" });
+  });
+
+  test("maps an API key provider, including its secret ARN", async () => {
+    send = async () => ({
+      credentialProviderArn: "arn:cp",
+      apiKeySecretArn: { secretArn: "arn:secret" },
+    });
+    const client = await createIdentityProviderClient("us-east-1", credentials);
+
+    expect(await client.getApiKeyProvider("k")).toEqual({
+      credentialProviderArn: "arn:cp",
+      clientSecretArn: "arn:secret",
+    });
+  });
+
+  test("maps an OAuth2 provider it finds, including its secret ARN", async () => {
+    send = async () => ({
+      credentialProviderArn: "arn:cp",
+      clientSecretArn: { secretArn: "arn:secret" },
+    });
+    const client = await createIdentityProviderClient("us-east-1", credentials);
+
+    expect(await client.getOauth2Provider("o")).toEqual({
+      credentialProviderArn: "arn:cp",
+      clientSecretArn: "arn:secret",
+    });
+  });
+
+  test("omits the secret ARN when Identity returns none", async () => {
+    send = async () => ({ credentialProviderArn: "arn:cp" });
+    const client = await createIdentityProviderClient("us-east-1", credentials);
+
+    expect(await client.getApiKeyProvider("k")).toEqual({ credentialProviderArn: "arn:cp" });
+  });
+
+  test("returns undefined when the provider does not exist", async () => {
+    send = async () => {
+      throw new ResourceNotFoundException();
+    };
+    const client = await createIdentityProviderClient("us-east-1", credentials);
+
+    expect(await client.getApiKeyProvider("missing")).toBeUndefined();
+    expect(await client.getOauth2Provider("missing")).toBeUndefined();
+  });
+
+  test("propagates errors other than not-found", async () => {
+    const failure = Object.assign(new Error("denied"), { name: "AccessDeniedException" });
+    send = async () => {
+      throw failure;
+    };
+    const client = await createIdentityProviderClient("us-east-1", credentials);
+
+    await expect(client.getApiKeyProvider("k")).rejects.toBe(failure);
+  });
+
+  test("throws when Identity returns no provider ARN", async () => {
+    send = async () => ({});
+    const client = await createIdentityProviderClient("us-east-1", credentials);
+
+    await expect(client.createApiKeyProvider({ name: "k", apiKey: "sk" })).rejects.toThrow(
+      /no credentialProviderArn/,
+    );
+  });
+
+  test("creates an API key provider from an inline key", async () => {
+    send = async () => ({ credentialProviderArn: "arn:cp" });
+    const client = await createIdentityProviderClient("us-east-1", credentials);
+
+    await client.createApiKeyProvider({ name: "k", apiKey: "sk-live" });
+
+    expect((sent[0] as CreateApiKeyCredentialProviderCommand).input).toEqual({
+      name: "k",
+      apiKey: "sk-live",
+    });
+  });
+
+  test("creates an API key provider from an external secret reference", async () => {
+    send = async () => ({ credentialProviderArn: "arn:cp" });
+    const client = await createIdentityProviderClient("us-east-1", credentials);
+
+    const secretRef = { secretId: "s", jsonKey: "apiKey" };
+    await client.createApiKeyProvider({ name: "k", secretRef });
+
+    expect((sent[0] as CreateApiKeyCredentialProviderCommand).input).toEqual({
+      name: "k",
+      apiKeySecretConfig: secretRef,
+      apiKeySecretSource: "EXTERNAL",
+    });
+  });
+
+  test("returns the created API key provider's secret ARN", async () => {
+    send = async () => ({
+      credentialProviderArn: "arn:cp",
+      apiKeySecretArn: { secretArn: "arn:secret" },
+    });
+    const client = await createIdentityProviderClient("us-east-1", credentials);
+
+    expect(await client.createApiKeyProvider({ name: "k", apiKey: "sk" })).toEqual({
+      credentialProviderArn: "arn:cp",
+      clientSecretArn: "arn:secret",
+    });
+  });
+
+  test("creates an OAuth2 provider without a returned secret ARN", async () => {
+    send = async () => ({ credentialProviderArn: "arn:cp" });
+    const client = await createIdentityProviderClient("us-east-1", credentials);
+
+    expect(
+      await client.createOauth2Provider({
+        name: "o",
+        vendor: "CustomOauth2",
+        config: { customOauth2ProviderConfig: { oauthDiscovery: { discoveryUrl: "u" } } },
+      }),
+    ).toEqual({ credentialProviderArn: "arn:cp" });
+  });
+
+  test("creates an OAuth2 provider with its vendor and config", async () => {
+    send = async () => ({
+      credentialProviderArn: "arn:cp",
+      clientSecretArn: { secretArn: "arn:secret" },
+    });
+    const client = await createIdentityProviderClient("us-east-1", credentials);
+
+    const config = { customOauth2ProviderConfig: { oauthDiscovery: { discoveryUrl: "u" } } };
+    const result = await client.createOauth2Provider({ name: "o", vendor: "CustomOauth2", config });
+
+    expect((sent[0] as CreateOauth2CredentialProviderCommand).input).toEqual({
+      name: "o",
+      credentialProviderVendor: "CustomOauth2",
+      oauth2ProviderConfigInput: config,
+    });
+    expect(result).toEqual({ credentialProviderArn: "arn:cp", clientSecretArn: "arn:secret" });
+  });
+});