credential provider follow-ups: name collisions, vendor change, and an untested secret-delete risk

Lavora sul branch refactor, iniziando da src/assets/cdk/lib/cdk-stack.ts, AgentCoreCredentialProvider.ts, l’handler di eliminazione e src/projectSchemas/credential.ts. Prima separa le quattro domande aperte e riproduci il caso di eliminazione dello stack di secretRef; confronta la denominazione del provider e il comportamento in caso di modifica del vendor con i vincoli indicati. Il lavoro è completato quando ogni domanda ha una risoluzione implementata o un risultato del test confermato, con copertura dei relativi percorsi di deployment.

Status

The drop bug is fixed by #2089, which creates credential providers in CloudFormation. Two of the six open questions below are answered; four are still open. This issue now tracks those four.

The original bug

On the refactor branch, agentcore project deploy silently ignored any credential declared in agentcore.json — the provider was never created and the deploy reported success:

$ agentcore project add credentials api-key --name openai-key
$ agentcore project deploy
...
Deployed project 'Example' to target 'default'          # exit 0

$ agentcore identity api-key-credential-provider get --name openai-key
Error: ApiKeyCredentialProvider not found for openai-key

The vended CDK app expected provider ARNs to already be recorded in agentcore/.cli/deployed-state.json (src/assets/cdk/bin/cdk.ts, read inside a try/catch that tolerated absence). Nothing in the deploy path wrote that file, so the credentials map was always undefined and every declaration fell on the floor — silently, because the read tolerated a missing file.

Not in main; refactor only.

How #2089 fixes it

src/assets/cdk/lib/cdk-stack.ts creates a provider for each declared credential using the constructs from L3 #333. Payment connectors now carry the credential's name and the stack resolves it to the ARN of the provider it created, which removed the last reader of deployed-state.json.

Answered: .env.local secrets are neither plaintext nor EXTERNAL

The original framing offered two options and both were bad. There is a third, which is what L3 #333 built for: the provider is created with CREDENTIAL_SECRET_PLACEHOLDER, and the CLI replaces it over the Identity API once the deploy succeeds. Real secret material never enters the template. A credential with a secretRef/clientSecretRef deploys as EXTERNAL and needs no sync.

One correction to the L3's own docstring, which suggests detecting an unsynced provider by finding the placeholder still in place: that is not implementable. ApiKey is a CloudFormation write-only property and GetApiKeyCredentialProvider returns only apiKeySecretArn — there is nothing to read back and compare. #2089 therefore syncs unconditionally on every deploy, at the cost of a new secret version each time.

Answered: secret rotation

Moot under the placeholder design. The template never carries the real key, so a stack update cannot overwrite a rotated secret with a stale one. If CloudFormation does update the resource for some other reason, it writes the placeholder and the post-deploy sync immediately replaces it.

Still open

1. Provider names are not scoped to a project, so stacks collide

AgentCoreApiKeyCredentialProvider sets the CFN Name to the bare credential name (AgentCoreCredentialProvider.ts:47, :116) — projectName only feeds tags. Names are unique per (account, region, token vault), so:

• two projects in one account+region both declaring openai-key collide
• two targets of one project in the same region collide — each target gets its own stack, and both try to create the same provider name

The imperative prototype reused an existing provider, so this used to be silent sharing; under CloudFormation the second stack fails with AlreadyExists. A hard failure is the better default, but it is a behaviour change and it makes a same-region two-target project undeployable.

Needs either a naming strategy (project- or target-scoped names, which changes what users pass to agentcore identity ...) or CFN resource import for adoption. The L3's ExternallyManagedStateSchema covers only customJwtAuthorizer and vpcConfig, so there is no existing escape hatch.

2. Changing a vendor is a replacement into a name collision

CredentialProviderVendor is create-only on OAuth2 and Payment, and Name is create-only too. Changing a credential's vendor while keeping its name makes CloudFormation replace the resource with one claiming a name still held by the resource being replaced. Needs a guard that refuses the edit with an actionable message.

3. Unverified: does deleting a stack destroy a customer-owned secret?

The delete handler lists secretsmanager:DeleteSecret unconditionally. If that applies to an EXTERNAL secret, deleting a stack destroys a secret the customer owns and manages elsewhere. Still untested.

This is now cheap to test: deploy a project with a secretRef credential, delete the stack, and check whether the referenced secret survives. Worth doing before refactor ships — it is the highest-severity unknown left here.

4. CredentialNameSchema.min(3)

Still a workaround for the pinned L3 rejecting shorter names at build (src/projectSchemas/credential.ts). Since we maintain the L3, align it and drop back to 1.

Moved out

Payment credential providers are tracked in #2095. project deploy refuses them with an explicit error rather than half-creating one; that issue covers both the Quick Create path (needs no provider, already released in L3 alpha.49 via L3 #324) and the Manual path's schema gap.

Reference, still accurate

• CloudFormation support: ApiKeyCredentialProvider, OAuth2CredentialProvider and PaymentCredentialProvider are all LIVE and FULLY_MUTABLE in the us-east-1 registry. On AWS::BedrockAgentCore::ApiKeyCredentialProvider: readOnlyProperties include CredentialProviderArn and ApiKeySecretArn; writeOnlyProperties are ApiKey, ApiKeySecretConfig, ApiKeySecretSource; createOnlyProperties is Name.
• The L3 tolerates a CDK token for a credential ARN. CredentialDeployedStateSchema.credentialProviderArn is a bare z.string(), and all consumption sites pass it straight into a CFN property or a truthiness check — no .split/.match/.slice/.startsWith/.replace on a credential ARN anywhere. IAM grants are built from the credential name plus partition/region/account, never by parsing the ARN. So no L3 schema change was needed.
• OAuth2CredentialProvider differs in shape: ClientSecretSource is read-only at the top level, so the secret config lives inside Oauth2ProviderConfigInput. All 9 vendor configs support ClientSecretConfig + ClientSecretSource.
• CustomOauth2ProviderConfigInput requires OauthDiscovery and has no Scopes field, which is why a spec's scopes are consumed where the credential is used, not where the provider is made.