feat(secrets): encrypt sensitive .env.local values at rest

docs/payments.md

@@ -197,14 +197,28 @@ AGENTCORE_CREDENTIAL_{CREDENTIAL_NAME}_AUTHORIZATION_ID=...
 `{CREDENTIAL_NAME}` is the connector's credential name uppercased with hyphens replaced by underscores. For example, a
 credential named `my-cdp-creds` becomes `AGENTCORE_CREDENTIAL_MY_CDP_CREDS_API_KEY_ID`.
 
+### Secret encryption at rest
+
+Connector secret values in `agentcore/.env.local` (API key secrets, wallet secrets, private keys) are encrypted at rest
+with a machine-local key stored outside the project directory (your OS keychain, or `~/.agentcore/secrets.key` on
+machines without a keychain). Copying or syncing the project directory does **not** expose the secrets — only the holder
+of the machine key can decrypt them. Reference IDs (API key ID, app ID) remain readable.
+
+To rotate a credential, re-run `agentcore add payment-connector` with the new values (this re-encrypts immediately).
+Editing `agentcore/.env.local` by hand still works: paste the new plaintext value and run `agentcore deploy` — the CLI
+re-encrypts it on the next write.
+
 ### Credential Rotation
 
-To rotate credentials:
+The preferred rotation path is to re-run `agentcore add payment-connector` with the new values — the CLI re-encrypts the
+secrets immediately and there is no plaintext window. Hand-editing `.env.local` also works: paste the new plaintext
+value and run `agentcore deploy -y` — the CLI re-encrypts on the next write.
 
-1. Update the values in `agentcore/.env.local`
+1. Re-run `agentcore add payment-connector` with the new values (preferred), **or** open `agentcore/.env.local`, paste
+   the new plaintext secret value, and save.
 2. Run `agentcore deploy -y`
 
-Deploy automatically updates the PaymentCredentialProvider on AWS with the new secret values.
+Deploy automatically updates the PaymentCredentialProvider on AWS with the new (re-encrypted) secret values.
 
 ## Deploying with Payments
 

e2e-tests/payment-strands-bedrock.test.ts

@@ -125,6 +125,21 @@ describe.sequential('e2e: payments — create → add payment → deploy → sta
     expect(cred).toBeTruthy();
   });
 
+  it.skipIf(!canRun)('stores connector secrets encrypted at rest, never as plaintext', async () => {
+    // The deploy step below reads these same values back and decrypts them, so a
+    // passing deploy already proves the round trip works. This assertion additionally
+    // pins the security invariant the encryption feature exists to guarantee: the raw
+    // secret must never touch disk in cleartext. Without it, a regression that silently
+    // reverted to plaintext storage would still deploy green and go unnoticed.
+    const envLocal = await readFile(join(projectPath, 'agentcore', '.env.local'), 'utf-8');
+
+    expect(envLocal, '.env.local should contain at least one enc:v1: envelope').toContain('enc:v1:');
+
+    for (const raw of [process.env.CDP_API_KEY_SECRET!, process.env.CDP_WALLET_SECRET!]) {
+      expect(envLocal, 'raw secret value must not appear in cleartext on disk').not.toContain(raw);
+    }
+  });
+
   it.skipIf(!canRun)('has payment capability code in agent', async () => {
     const config = JSON.parse(await readFile(join(projectPath, 'agentcore', 'agentcore.json'), 'utf-8'));
     const runtimeName = config.runtimes?.[0]?.name;

esbuild.config.mjs

@@ -56,7 +56,7 @@ await esbuild.build({
   banner: {
     js: `import { createRequire } from 'module'; import { fileURLToPath as __ef } from 'url'; import { dirname as __ed } from 'path'; const require = createRequire(import.meta.url); const __filename = __ef(import.meta.url); const __dirname = __ed(__filename);`,
   },
-  external: ['fsevents', '@aws-cdk/toolkit-lib'],
+  external: ['fsevents', '@aws-cdk/toolkit-lib', '@napi-rs/keyring'],
   plugins: [optionalDepsPlugin, textLoaderPlugin],
 });
 

integ-tests/add-agent-auth.test.ts

@@ -1,22 +1,36 @@
+import { readEnvFile } from '../src/lib/utils/env.js';
 import { createTestProject, readProjectConfig, runCLI } from '../src/test-utils/index.js';
 import type { TestProject } from '../src/test-utils/index.js';
+import { mkdtempSync, rmSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { afterAll, beforeAll, describe, expect, it } from 'vitest';
 
 describe('integration: add BYO agent with CUSTOM_JWT auth', () => {
   let project: TestProject;
+  let keyDir: string;
+  const prevEnv = { kc: process.env.AGENTCORE_DISABLE_KEYCHAIN, cfg: process.env.AGENTCORE_CONFIG_DIR };
   const agentName = 'AuthAgent';
   const discoveryUrl = 'https://cognito-idp.us-east-1.amazonaws.com/us-east-1_test123/.well-known/openid-configuration';
 
   beforeAll(async () => {
+    // Isolate secret-at-rest encryption from the developer's real OS keychain and
+    // ~/.agentcore: force the keyfile provider into a throwaway dir. cleanSpawnEnv
+    // inherits process.env, so spawned CLI processes pick these up too.
+    keyDir = mkdtempSync(join(tmpdir(), 'agentcore-integ-keys-'));
+    process.env.AGENTCORE_DISABLE_KEYCHAIN = '1';
+    process.env.AGENTCORE_CONFIG_DIR = keyDir;
     project = await createTestProject({
       noAgent: true,
     });
   });
 
   afterAll(async () => {
     await project.cleanup();
+    process.env.AGENTCORE_DISABLE_KEYCHAIN = prevEnv.kc;
+    process.env.AGENTCORE_CONFIG_DIR = prevEnv.cfg;
+    rmSync(keyDir, { recursive: true, force: true });
   });
 
   it('adds a BYO agent with CUSTOM_JWT authorizer and audience', async () => {
@@ -119,11 +133,13 @@ describe('integration: add BYO agent with CUSTOM_JWT auth', () => {
     expect(oauthCred!.authorizerType).toBe('OAuthCredentialProvider');
     expect((oauthCred as { managed?: boolean }).managed).toBe(true);
 
-    // Verify .env.local has client secrets (namespaced per credential)
+    // Client ID is a reference (plaintext); the client SECRET is encrypted at rest.
     const envPath = join(project.projectPath, 'agentcore', '.env.local');
     const envContent = await readFile(envPath, 'utf-8');
     expect(envContent).toContain('my-client-id');
-    expect(envContent).toContain('my-client-secret');
+    expect(envContent).not.toContain('my-client-secret'); // encrypted at rest
+    const env = await readEnvFile(join(project.projectPath, 'agentcore'));
+    expect(env.AGENTCORE_CREDENTIAL_AUTHAGENT2_OAUTH_CLIENT_SECRET).toBe('my-client-secret');
   });
 
   it('adds a BYO agent with default AWS_IAM auth (no auth flags)', async () => {

package.json

@@ -114,6 +114,9 @@
     "yaml": "^2.8.3",
     "zod": "^4.3.5"
   },
+  "optionalDependencies": {
+    "@napi-rs/keyring": "^1.3.0"
+  },
   "peerDependencies": {
     "aws-cdk-lib": "^2.258.0",
     "constructs": "^10.0.0"