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
 

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,3 +1,4 @@
+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 { readFile } from 'node:fs/promises';
@@ -119,11 +120,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"

src/cli/commands/add/__tests__/multi-agent-credentials.test.ts

@@ -1,3 +1,4 @@
+import { readEnvFile } from '../../../../lib/utils/env';
 import { runCLI } from '../../../../test-utils/index.js';
 import { randomUUID } from 'node:crypto';
 import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
@@ -47,6 +48,10 @@ describe('multi-agent credential behavior', () => {
     }
   }
 
+  async function readEnvDecrypted() {
+    return readEnvFile(join(projectDir, 'agentcore'));
+  }
+
   describe('credential reuse with same API key', () => {
     it('first agent creates project-scoped credential', async () => {
       const result = await runCLI(
@@ -76,9 +81,11 @@ describe('multi-agent credential behavior', () => {
       expect(spec.credentials).toHaveLength(1);
       expect(spec.credentials[0].name).toBe(`${projectName}Gemini`);
 
-      const env = await readEnvLocal();
-      expect(env).toContain('AGENTCORE_CREDENTIAL_MULTIAGENTPROJGEMINI=');
-      expect(env).toContain('KEY1');
+      const rawEnv = await readEnvLocal();
+      expect(rawEnv).toContain('AGENTCORE_CREDENTIAL_MULTIAGENTPROJGEMINI=');
+      expect(rawEnv).not.toContain('KEY1'); // encrypted at rest
+      const env = await readEnvDecrypted();
+      expect(env.AGENTCORE_CREDENTIAL_MULTIAGENTPROJGEMINI).toBe('KEY1');
     });
 
     it('second agent with same key reuses credential (no duplicate)', async () => {
@@ -151,12 +158,15 @@ describe('multi-agent credential behavior', () => {
       // Should have 3 agents
       expect(spec.runtimes).toHaveLength(3);
 
-      // .env.local should have both keys
-      const env = await readEnvLocal();
-      expect(env).toContain('AGENTCORE_CREDENTIAL_MULTIAGENTPROJGEMINI=');
-      expect(env).toContain('KEY1');
-      expect(env).toContain('AGENTCORE_CREDENTIAL_MULTIAGENTPROJAGENT3GEMINI=');
-      expect(env).toContain('KEY2');
+      // .env.local should have both keys encrypted at rest, decryptable to original values
+      const rawEnv = await readEnvLocal();
+      expect(rawEnv).toContain('AGENTCORE_CREDENTIAL_MULTIAGENTPROJGEMINI=');
+      expect(rawEnv).toContain('AGENTCORE_CREDENTIAL_MULTIAGENTPROJAGENT3GEMINI=');
+      expect(rawEnv).not.toContain('KEY1'); // encrypted at rest
+      expect(rawEnv).not.toContain('KEY2'); // encrypted at rest
+      const env = await readEnvDecrypted();
+      expect(env.AGENTCORE_CREDENTIAL_MULTIAGENTPROJGEMINI).toBe('KEY1');
+      expect(env.AGENTCORE_CREDENTIAL_MULTIAGENTPROJAGENT3GEMINI).toBe('KEY2');
 
       // Generated code should reference correct credentials
       const agent1Code = await readFile(join(projectDir, 'app/Agent1/model/load.py'), 'utf-8');

src/cli/primitives/PaymentConnectorPrimitive.ts

@@ -2,6 +2,7 @@ import { findConfigRoot, removeEnvVars, setEnvVar, toError } from '../../lib';
 import type { AgentCoreProjectSpec, PaymentProvider } from '../../schema';
 import { PaymentConnectorNameSchema, PaymentConnectorSchema, PaymentProviderSchema } from '../../schema';
 import type { RemoveResult } from '../commands/remove/types';
+import { ANSI } from '../constants';
 import { getErrorMessage } from '../errors';
 import type { RemovalPreview, SchemaChange } from '../operations/remove/types';
 import { requireTTY } from '../tui/guards/tty';
@@ -447,6 +448,20 @@ export class PaymentConnectorPrimitive extends BasePrimitive<AddPaymentConnector
                 if (walletSecretResult !== true) failValidation(walletSecretResult);
               }
 
+              const usedLiteralSecretFlag = [
+                cliOptions.apiKeySecret,
+                cliOptions.walletSecret,
+                cliOptions.appSecret,
+                cliOptions.authorizationPrivateKey,
+              ].some(v => v !== undefined);
+              if (usedLiteralSecretFlag && !cliOptions.json) {
+                process.stderr.write(
+                  `${ANSI.yellow}Warning: passing secrets as CLI flags exposes them to shell history and the ` +
+                    `process table. Prefer interactive mode (run \`agentcore add payment-connector\` with no ` +
+                    `secret flags) for masked entry.${ANSI.reset}\n`
+                );
+              }
+
               let result: Awaited<ReturnType<typeof this.add>>;
               if (provider === 'StripePrivy') {
                 result = await this.add({

src/cli/telemetry/schemas/common-shapes.ts

@@ -125,6 +125,8 @@ export const ErrorName = z.enum([
   'PollExhaustedError',
   'PollTimeoutError',
   'ResourceNotFoundError',
+  'SecretDecryptionError',
+  'SecretEncryptionError',
   'ServiceError',
   'ServiceQuotaError',
   'ShellKickedError',