@aws-blocks/bb-app-setting 0.1.4 → 0.2.0

package/dist/types.d.ts

@@ -23,8 +23,24 @@ export interface AppSettingOptions<T = string> {
     value?: T;
     /** Runtime validation schema. Accepts any StandardSchemaV1 implementation (Zod, Valibot, ArkType). When provided, T is inferred from the schema. */
     schema?: StandardSchemaV1<T>;
-    /** When true, creates an SSM SecureString parameter encrypted with the default aws/ssm KMS key. */
+    /** When true, creates an SSM SecureString parameter. Encrypted with the default `aws/ssm` KMS key unless `kmsKeyArn` is set. */
     secret?: boolean;
+    /**
+     * ARN of a **customer-managed KMS key** used to encrypt this secret's
+     * SecureString value. When omitted, SSM uses the default `aws/ssm`
+     * AWS-managed key. Use a CMK when you need to control the decrypt/grant scope
+     * (e.g. cross-account access, key rotation, or a dedicated key policy).
+     *
+     * Only valid together with `secret: true`. The CDK layer grants the shared
+     * handler `kms:Decrypt` (plus `kms:Encrypt` for stack-managed secrets it
+     * writes) on this key, and the runtime `put()` passes the key so an overwrite
+     * does not silently fall back to the default key. Changing this on an existing
+     * secret re-encrypts its current value under the new key at deploy time.
+     *
+     * @example
+     * new AppSetting(scope, 'apiKey', { secret: true, kmsKeyArn: myKey.keyArn });
+     */
+    kmsKeyArn?: string;
     /** Optional logger for internal operations. When omitted, a default Logger at error level is created. */
     logger?: ChildLogger;
 }

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEzD;;GAEG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC,GAAG,MAAM;IAC5C;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iLAAiL;IACjL,KAAK,CAAC,EAAE,CAAC,CAAC;IACV,oJAAoJ;IACpJ,MAAM,CAAC,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAC7B,mGAAmG;IACnG,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,yGAAyG;IACzG,MAAM,CAAC,EAAE,WAAW,CAAC;CACrB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,yBAAyB,CAAC,CAAC,GAAG,MAAM,CAAE,SAAQ,iBAAiB,CAAC,CAAC,CAAC;IAClF;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACnB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEzD;;GAEG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC,GAAG,MAAM;IAC5C;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iLAAiL;IACjL,KAAK,CAAC,EAAE,CAAC,CAAC;IACV,oJAAoJ;IACpJ,MAAM,CAAC,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAC7B,gIAAgI;IAChI,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;;;;;;;;;;OAcG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yGAAyG;IACzG,MAAM,CAAC,EAAE,WAAW,CAAC;CACrB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,yBAAyB,CAAC,CAAC,GAAG,MAAM,CAAE,SAAQ,iBAAiB,CAAC,CAAC,CAAC;IAClF;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACnB"}

package/dist/version.d.ts

@@ -1,3 +1,3 @@
 export declare const BB_NAME = "AppSetting";
-export declare const BB_VERSION = "0.1.4";
+export declare const BB_VERSION = "0.2.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,3 +1,3 @@
 // Auto-generated by scripts/generate-version.mjs — do not edit manually
 export const BB_NAME = 'AppSetting';
-export const BB_VERSION = '0.1.4';
+export const BB_VERSION = '0.2.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws-blocks/bb-app-setting",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/aws-devtools-labs/aws-blocks.git",
@@ -39,8 +39,8 @@
     "test": "node --test --test-concurrency=1 dist/**/*.test.js"
   },
   "dependencies": {
-    "@aws-blocks/core": "^0.2.0",
-    "@aws-blocks/bb-logger": "^0.1.4",
+    "@aws-blocks/core": "^0.3.0",
+    "@aws-blocks/bb-logger": "^0.1.5",
     "@aws-sdk/client-ssm": "^3.0.0",
     "@standard-schema/spec": "^1.1.0"
   },

package/src/index.aws.test.ts

@@ -0,0 +1,59 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import assert from 'node:assert';
+import { describe, test, mock } from 'node:test';
+import { SSMClient } from '@aws-sdk/client-ssm';
+import { Scope } from '@aws-blocks/core';
+import { AppSetting } from './index.aws.js';
+
+const TEST_CMK = 'arn:aws:kms:us-east-1:111122223333:key/abcd1234-5678-90ab-cdef-1234567890ab';
+
+/** Capture the input of the next PutParameterCommand sent by the runtime. */
+function captureSend() {
+	const inputs: any[] = [];
+	const m = mock.method(SSMClient.prototype, 'send', async (cmd: any) => {
+		inputs.push(cmd.input);
+		return {};
+	});
+	return { inputs, restore: () => m.mock.restore() };
+}
+
+describe('AWS runtime put() KMS key', () => {
+	test('passes the CMK as KeyId when a secret is backed by kmsKeyArn', async () => {
+		const { inputs, restore } = captureSend();
+		try {
+			const setting = new AppSetting(new Scope('app'), 'cmk', { secret: true, kmsKeyArn: TEST_CMK });
+			await setting.put('rotated-value');
+			assert.strictEqual(inputs.length, 1);
+			assert.strictEqual(inputs[0].Type, 'SecureString');
+			assert.strictEqual(inputs[0].KeyId, TEST_CMK, 'overwrite must re-specify the CMK, not fall back to aws/ssm');
+		} finally {
+			restore();
+		}
+	});
+
+	test('omits KeyId for a default-key secret', async () => {
+		const { inputs, restore } = captureSend();
+		try {
+			const setting = new AppSetting(new Scope('app'), 'plain', { secret: true });
+			await setting.put('v');
+			assert.strictEqual(inputs[0].Type, 'SecureString');
+			assert.strictEqual(inputs[0].KeyId, undefined);
+		} finally {
+			restore();
+		}
+	});
+
+	test('omits KeyId for a non-secret String parameter', async () => {
+		const { inputs, restore } = captureSend();
+		try {
+			const setting = new AppSetting<string>(new Scope('app'), 'cfg', { value: 'init' });
+			await setting.put('next');
+			assert.strictEqual(inputs[0].Type, 'String');
+			assert.strictEqual(inputs[0].KeyId, undefined);
+		} finally {
+			restore();
+		}
+	});
+});

package/src/index.aws.ts

@@ -67,7 +67,7 @@ export class AppSetting<T = string> extends Scope {
 	static fromExisting<T = string>(
 		scope: ScopeParent,
 		id: string,
-		options: { name: string; secret?: boolean },
+		options: { name: string; secret?: boolean; kmsKeyArn?: string },
 	): AppSetting<T> {
 		const opts: InternalAppSettingOptions<T> = { ...options, external: true };
 		return new AppSetting<T>(scope, id, opts);
@@ -76,6 +76,7 @@ export class AppSetting<T = string> extends Scope {
 	readonly bbName = BB_NAME;
 	private schema?: StandardSchemaV1<T>;
 	private isSecret: boolean;
+	private kmsKeyArn?: string;
 	private client: SSMClient;
 
 	/** @internal Logger for internal operations. Defaults to error-level when not provided. */
@@ -88,6 +89,7 @@ export class AppSetting<T = string> extends Scope {
 		const parameterName = options.name ?? `/${this.fullId}`;
 		this.schema = options.schema;
 		this.isSecret = options.secret ?? false;
+		this.kmsKeyArn = options.kmsKeyArn;
 		this.client = new SSMClient({
 			customUserAgent: this.buildUserAgentChain(),
 		});
@@ -160,6 +162,9 @@ export class AppSetting<T = string> extends Scope {
 			Value: serialized,
 			Type: this.isSecret ? 'SecureString' : 'String',
 			Overwrite: true,
+			// Re-specify the CMK on overwrite: SSM falls back to the default aws/ssm
+			// key when KeyId is omitted, which would silently downgrade encryption.
+			...(this.isSecret && this.kmsKeyArn ? { KeyId: this.kmsKeyArn } : {}),
 		}));
 	}
 }

package/src/index.cdk.test.ts

@@ -17,15 +17,20 @@ import { AppSetting } from './index.cdk.js';
 
 class StubBlocksStack extends cdk.Stack {
 	public readonly handler: cdk.aws_lambda.Function;
+	public readonly executionRole: cdk.aws_iam.IRole;
 	public readonly id: string;
 	constructor(scope: Construct, id: string) {
 		super(scope, id);
 		this.id = id;
 		(globalThis as any).CURRENT_BLOCKS_STACK = this;
+		this.executionRole = new cdk.aws_iam.Role(this, 'BlocksRole', {
+			assumedBy: new cdk.aws_iam.ServicePrincipal('lambda.amazonaws.com'),
+		});
 		this.handler = new cdk.aws_lambda.Function(this, 'StubHandler', {
 			runtime: DEFAULT_NODE_RUNTIME,
 			handler: 'index.handler',
 			code: cdk.aws_lambda.Code.fromInline('exports.handler = async () => {};'),
+			role: this.executionRole,
 		});
 	}
 }
@@ -225,3 +230,120 @@ test('CDK: fromExisting still registers the runtime config key (BLOCKS_SSM_PARAM
 	);
 	assert.equal(registry.entries.get('BLOCKS_SSM_PARAM_DB_URL'), '/blocks/sandbox/db-abc-connection-string');
 });
+
+const TEST_CMK = 'arn:aws:kms:us-east-1:111122223333:key/abcd1234-5678-90ab-cdef-1234567890ab';
+
+test('CDK: secret with kmsKeyArn grants handler KMS on the specific CMK ARN (not a ViaService wildcard)', () => {
+	const { stack, parent } = setup();
+	new AppSetting(parent, 'cmk-secret', { secret: true, name: '/app/cmk-secret', kmsKeyArn: TEST_CMK });
+	const template = Template.fromStack(stack);
+	const policies = template.findResources('AWS::IAM::Policy');
+
+	let found = false;
+	for (const logicalId of Object.keys(policies)) {
+		const statements = policies[logicalId]?.Properties?.PolicyDocument?.Statement;
+		if (!Array.isArray(statements)) continue;
+		for (const stmt of statements) {
+			const actions = Array.isArray(stmt.Action) ? stmt.Action : [stmt.Action];
+			if (!actions.includes('kms:Decrypt')) continue;
+			// The CMK grant scopes to the exact key ARN and carries no ViaService condition.
+			const resStr = JSON.stringify(stmt.Resource);
+			if (resStr.includes(TEST_CMK)) {
+				found = true;
+				assert.ok(actions.includes('kms:Encrypt'), 'stack-managed CMK secret should grant kms:Encrypt');
+				// Standard-tier SecureStrings only use Encrypt/Decrypt — no GenerateDataKey.
+				assert.ok(
+					!actions.some((a: string) => a.startsWith('kms:GenerateDataKey')),
+					'CMK grant should not include kms:GenerateDataKey* (advanced-tier only)',
+				);
+				assert.strictEqual(stmt.Condition, undefined, 'CMK grant should not use a ViaService wildcard condition');
+			}
+		}
+	}
+	assert.ok(found, `Expected a handler KMS grant scoped to the CMK ARN ${TEST_CMK}`);
+});
+
+test('CDK: secret with kmsKeyArn passes the KeyId to the bulk secret custom resource', () => {
+	const { stack, parent } = setup();
+	new AppSetting(parent, 'cmk-secret', { secret: true, name: '/app/cmk-secret', kmsKeyArn: TEST_CMK });
+	const template = Template.fromStack(stack);
+
+	const crs = template.findResources('AWS::CloudFormation::CustomResource');
+	const bulk = Object.values(crs).find((r) => Array.isArray(r?.Properties?.Parameters));
+	assert.ok(bulk, 'Expected a bulk-secrets custom resource with a Parameters list');
+	const params = bulk.Properties.Parameters as Array<{ name: string; keyId?: string }>;
+	const entry = params.find((p) => p.name === '/app/cmk-secret');
+	assert.ok(entry, 'the secret should appear in the bulk Parameters');
+	assert.strictEqual(entry?.keyId, TEST_CMK, 'the CMK ARN must be passed through as keyId');
+});
+
+test('CDK: a default-key secret carries no keyId in the bulk Parameters', () => {
+	const { stack, parent } = setup();
+	new AppSetting(parent, 'plain-secret', { secret: true, name: '/app/plain-secret' });
+	const template = Template.fromStack(stack);
+	const crs = template.findResources('AWS::CloudFormation::CustomResource');
+	const bulk = Object.values(crs).find((r) => Array.isArray(r?.Properties?.Parameters));
+	const params = bulk?.Properties?.Parameters as Array<{ name: string; keyId?: string }>;
+	const entry = params.find((p) => p.name === '/app/plain-secret');
+	assert.ok(entry, 'the secret should appear in the bulk Parameters');
+	assert.strictEqual(entry?.keyId, undefined, 'a default-key secret must not set keyId');
+});
+
+test('CDK: kmsKeyArn without secret throws ValidationFailed', () => {
+	const { parent } = setup();
+	assert.throws(
+		() => new AppSetting(parent, 'bad', { value: 'x', name: '/app/bad', kmsKeyArn: TEST_CMK }),
+		/only valid with 'secret: true'/,
+	);
+});
+
+test('CDK: fromExisting with kmsKeyArn grants read-only KMS scoped to the CMK ARN (Decrypt, no Encrypt)', () => {
+	const { stack, parent } = setup();
+	AppSetting.fromExisting(parent, 'ext-cmk', { name: '/ext/cmk-secret', secret: true, kmsKeyArn: TEST_CMK });
+	const template = Template.fromStack(stack);
+	const policies = template.findResources('AWS::IAM::Policy');
+
+	let found = false;
+	for (const logicalId of Object.keys(policies)) {
+		const statements = policies[logicalId]?.Properties?.PolicyDocument?.Statement;
+		if (!Array.isArray(statements)) continue;
+		for (const stmt of statements) {
+			const actions = Array.isArray(stmt.Action) ? stmt.Action : [stmt.Action];
+			if (JSON.stringify(stmt.Resource).includes(TEST_CMK) && actions.includes('kms:Decrypt')) {
+				found = true;
+				assert.ok(!actions.includes('kms:Encrypt'), 'external (read-only) CMK secret must not grant kms:Encrypt');
+			}
+		}
+	}
+	assert.ok(found, 'external CMK secret should grant kms:Decrypt scoped to the CMK ARN');
+});
+
+test('CDK: bulk-init role can read + re-key secrets (ssm:GetParameter + kms:Encrypt/Decrypt), no GenerateDataKey', () => {
+	// The re-encrypt-on-key-change path reads the current value (GetParameter +
+	// Decrypt) and rewrites it under the new key (Encrypt). The bulk-init statement
+	// is uniquely identified by ssm:AddTagsToResource.
+	const { stack, parent } = setup();
+	new AppSetting(parent, 'cmk-secret', { secret: true, name: '/app/cmk-secret', kmsKeyArn: TEST_CMK });
+	const template = Template.fromStack(stack);
+	const policies = template.findResources('AWS::IAM::Policy');
+
+	let bulkSsm: string[] | undefined;
+	let bulkKms: string[] | undefined;
+	for (const logicalId of Object.keys(policies)) {
+		const statements = policies[logicalId]?.Properties?.PolicyDocument?.Statement;
+		if (!Array.isArray(statements)) continue;
+		for (const stmt of statements) {
+			const actions: string[] = Array.isArray(stmt.Action) ? stmt.Action : [stmt.Action];
+			if (actions.includes('ssm:AddTagsToResource')) bulkSsm = actions;
+			if (actions.includes('kms:Encrypt') && stmt.Condition?.StringEquals?.['kms:ViaService']) bulkKms = actions;
+		}
+	}
+	assert.ok(bulkSsm, 'expected the bulk-init ssm statement (identified by AddTagsToResource)');
+	assert.ok(bulkSsm?.includes('ssm:GetParameter'), 'bulk-init needs ssm:GetParameter to read a value when re-keying');
+	assert.ok(bulkKms, 'expected the bulk-init KMS statement (ViaService-scoped)');
+	assert.ok(bulkKms?.includes('kms:Decrypt'), 'bulk-init needs kms:Decrypt to read the current value when re-keying');
+	assert.ok(
+		!bulkKms?.some((a) => a.startsWith('kms:GenerateDataKey')),
+		'no GenerateDataKey* — standard-tier SecureStrings do not use it',
+	);
+});

package/src/index.cdk.ts

@@ -21,7 +21,9 @@ export type { AppSettingOptions } from './types.js';
  * - String parameters use `aws-cdk-lib/aws-ssm.StringParameter` directly.
  * - SecureString parameters use a Custom Resource Lambda because
  *   CloudFormation cannot natively create SecureString parameters.
- * - SecureString parameters are encrypted with the default `aws/ssm` KMS key.
+ * - SecureString parameters are encrypted with the default `aws/ssm` KMS key,
+ *   or with a customer-managed key when `kmsKeyArn` is provided (the handler is
+ *   then granted `kms:Decrypt`/`Encrypt` on that specific key ARN).
  */
 export class AppSetting<T = string> extends Scope {
 	/**
@@ -40,7 +42,7 @@ export class AppSetting<T = string> extends Scope {
 	static fromExisting<T = string>(
 		scope: ScopeParent,
 		id: string,
-		options: { name: string; secret?: boolean },
+		options: { name: string; secret?: boolean; kmsKeyArn?: string },
 	): AppSetting<T> {
 		const opts: InternalAppSettingOptions<T> = { ...options, external: true };
 		return new AppSetting<T>(scope, id, opts);
@@ -72,6 +74,25 @@ export class AppSetting<T = string> extends Scope {
 			throw err;
 		}
 
+		if (options.kmsKeyArn !== undefined) {
+			if (!options.secret) {
+				const err = new Error(
+					`AppSetting '${id}': 'kmsKeyArn' is only valid with 'secret: true'. ` +
+					`Non-secret String parameters are not encrypted.`
+				);
+				err.name = AppSettingErrors.ValidationFailed;
+				throw err;
+			}
+			if (options.kmsKeyArn.trim() === '') {
+				const err = new Error(
+					`AppSetting '${id}': 'kmsKeyArn' must be a non-empty KMS key ARN. ` +
+					`Omit it to use the default aws/ssm key.`
+				);
+				err.name = AppSettingErrors.ValidationFailed;
+				throw err;
+			}
+		}
+
 		if (options.secret && options.value !== undefined) {
 			const err = new Error(
 				`AppSetting '${id}': secrets should not have a value in source code. ` +
@@ -130,21 +151,33 @@ export class AppSetting<T = string> extends Scope {
 			// then fail tagging it (AddTagsToResource needs ssm:GetParameters).
 			// We only need runtime read access, granted below.
 			if (!external) {
-				registerSecret(cdk.Stack.of(this), parameterName);
+				registerSecret(cdk.Stack.of(this), parameterName, options.kmsKeyArn);
 			}
 
-			// Grant handler KMS access for the default aws/ssm key. External secrets
-			// are read-only (Decrypt only); stack-managed secrets also need Encrypt
-			// so the app can write the value via put().
-			this.handler.addToRolePolicy(new iam.PolicyStatement({
-				actions: external ? ['kms:Decrypt'] : ['kms:Decrypt', 'kms:Encrypt'],
-				resources: ['*'],
-				conditions: {
-					StringEquals: {
-						'kms:ViaService': `ssm.${cdk.Stack.of(this).region}.amazonaws.com`,
+			// Grant the handler KMS access. External secrets are read-only (Decrypt
+			// only); stack-managed secrets also need Encrypt so the app can write the
+			// value via put(). Standard-tier SecureStrings only use Encrypt/Decrypt
+			// (no GenerateDataKey — that's advanced-tier envelope encryption).
+			if (options.kmsKeyArn) {
+				// Customer-managed key: grant on the specific key ARN. NOTE: the key's
+				// own key policy must also allow this role (we can't edit a BYO key's
+				// policy from here) — see the README.
+				this.executionRole.addToPrincipalPolicy(new iam.PolicyStatement({
+					actions: external ? ['kms:Decrypt'] : ['kms:Decrypt', 'kms:Encrypt'],
+					resources: [options.kmsKeyArn],
+				}));
+			} else {
+				// Default aws/ssm key: scope the wildcard with a ViaService condition.
+				this.executionRole.addToPrincipalPolicy(new iam.PolicyStatement({
+					actions: external ? ['kms:Decrypt'] : ['kms:Decrypt', 'kms:Encrypt'],
+					resources: ['*'],
+					conditions: {
+						StringEquals: {
+							'kms:ViaService': `ssm.${cdk.Stack.of(this).region}.amazonaws.com`,
+						},
 					},
-				},
-			}));
+				}));
+			}
 		} else if (!external) {
 			// ── String parameter via CDK construct ──────────────────────────
 			const param = new ssm.StringParameter(this, 'Param', {
@@ -159,7 +192,7 @@ export class AppSetting<T = string> extends Scope {
 
 		// Grant handler SSM access on this parameter. External parameters are owned
 		// elsewhere, so the app only reads them (no ssm:PutParameter).
-		this.handler.addToRolePolicy(new iam.PolicyStatement({
+		this.executionRole.addToPrincipalPolicy(new iam.PolicyStatement({
 			actions: external ? ['ssm:GetParameter'] : ['ssm:GetParameter', 'ssm:PutParameter'],
 			resources: [parameterArn],
 		}));
@@ -174,101 +207,127 @@ export class AppSetting<T = string> extends Scope {
 
 const SECRET_BULK_KEY = Symbol.for('BLOCKS_SECRET_BULK_INIT');
 
+interface SecretParam {
+	name: string;
+	/** Customer-managed KMS key ARN, or undefined for the default aws/ssm key. */
+	keyId?: string;
+}
+
 interface SecretBulkState {
-	parameterNames: string[];
+	params: SecretParam[];
 }
 
 /**
- * Register a secret parameter name. On first call, creates the shared Lambda,
- * Provider, and a single CustomResource. All subsequent calls just append to
- * the parameter list (resolved lazily at synth time).
+ * Register a secret parameter (and its optional customer-managed KMS key). On
+ * first call, creates the shared Lambda, Provider, and a single CustomResource.
+ * All subsequent calls just append to the parameter list (resolved lazily at
+ * synth time).
  */
-function registerSecret(stack: cdk.Stack, parameterName: string): void {
+function registerSecret(stack: cdk.Stack, parameterName: string, keyId?: string): void {
 	let state = (stack as any)[SECRET_BULK_KEY] as SecretBulkState | undefined;
 	if (state) {
-		state.parameterNames.push(parameterName);
+		state.params.push({ name: parameterName, keyId });
 		return;
 	}
 
 	// First secret in this stack — create all shared infrastructure
-	state = { parameterNames: [parameterName] };
+	state = { params: [{ name: parameterName, keyId }] };
 	(stack as any)[SECRET_BULK_KEY] = state;
 
 	const secretInitFn = new lambda.Function(stack, 'BlocksSecretInitFn', {
 		runtime: DEFAULT_NODE_RUNTIME,
 		handler: 'index.handler',
 		code: lambda.Code.fromInline(`
-			const { SSMClient, PutParameterCommand, DeleteParameterCommand, AddTagsToResourceCommand } = require('@aws-sdk/client-ssm');
-			const crypto = require('crypto');
-			const client = new SSMClient({});
-			exports.handler = async (event) => {
-				const names = event.ResourceProperties.ParameterNames || [];
-				const stackName = event.ResourceProperties.StackName || '';
-				const tags = stackName ? [{ Key: 'aws-blocks-stack', Value: stackName }] : [];
-				const oldNames = (event.OldResourceProperties || {}).ParameterNames || [];
-				if (event.RequestType === 'Delete') {
-					for (const name of names) {
-						try { await client.send(new DeleteParameterCommand({ Name: name })); } catch {}
-					}
-					return { PhysicalResourceId: 'bb-secrets-bulk' };
-				}
-				if (event.RequestType === 'Create') {
-					for (const name of names) {
-						const secret = crypto.randomBytes(32).toString('base64url');
-						try {
-							await client.send(new PutParameterCommand({
-								Name: name, Value: secret, Type: 'SecureString', Overwrite: false, Tags: tags,
-							}));
-						} catch (e) {
-							if (e.name !== 'ParameterAlreadyExists') throw e;
-							if (tags.length) {
-								await client.send(new AddTagsToResourceCommand({ ResourceType: 'Parameter', ResourceId: name, Tags: tags }));
-							}
+				const { SSMClient, GetParameterCommand, PutParameterCommand, DeleteParameterCommand, AddTagsToResourceCommand } = require('@aws-sdk/client-ssm');
+				const crypto = require('crypto');
+				const client = new SSMClient({});
+				async function putSecret(p, tags) {
+					const secret = crypto.randomBytes(32).toString('base64url');
+					const input = { Name: p.name, Value: secret, Type: 'SecureString', Overwrite: false, Tags: tags };
+					// A CMK ARN pins the SecureString to a customer-managed key; omit for the default aws/ssm key.
+					if (p.keyId) input.KeyId = p.keyId;
+					try {
+						await client.send(new PutParameterCommand(input));
+					} catch (e) {
+						if (e.name !== 'ParameterAlreadyExists') throw e;
+						if (tags.length) {
+							await client.send(new AddTagsToResourceCommand({ ResourceType: 'Parameter', ResourceId: p.name, Tags: tags }));
 						}
 					}
-					return { PhysicalResourceId: 'bb-secrets-bulk' };
 				}
-				if (event.RequestType === 'Update') {
-					const added = names.filter(n => !oldNames.includes(n));
-					const removed = oldNames.filter(n => !names.includes(n));
-					for (const name of added) {
-						const secret = crypto.randomBytes(32).toString('base64url');
-						try {
-							await client.send(new PutParameterCommand({
-								Name: name, Value: secret, Type: 'SecureString', Overwrite: false, Tags: tags,
-							}));
-						} catch (e) {
-							if (e.name !== 'ParameterAlreadyExists') throw e;
-							if (tags.length) {
-								await client.send(new AddTagsToResourceCommand({ ResourceType: 'Parameter', ResourceId: name, Tags: tags }));
-							}
+				// Re-encrypt an EXISTING secret under a new (or removed) KMS key, preserving its
+				// current value. Without this, changing kmsKeyArn leaves the value encrypted under
+				// the old key while the app's IAM grant flips to the new key, so the next get()
+				// fails with AccessDenied.
+				async function reencrypt(p) {
+					const cur = await client.send(new GetParameterCommand({ Name: p.name, WithDecryption: true }));
+					const value = cur.Parameter && cur.Parameter.Value;
+					if (value === undefined || value === null) return;
+					const input = { Name: p.name, Value: value, Type: 'SecureString', Overwrite: true };
+					if (p.keyId) input.KeyId = p.keyId; // omit => back to the default aws/ssm key
+					await client.send(new PutParameterCommand(input));
+				}
+				// A pre-CMK deployment stored ParameterNames (string[]); map it to the {name} shape.
+				function readOld(op) {
+					if (Array.isArray(op.Parameters)) return op.Parameters;
+					if (Array.isArray(op.ParameterNames)) return op.ParameterNames.map((n) => ({ name: n }));
+					return [];
+				}
+				exports.handler = async (event) => {
+					const params = event.ResourceProperties.Parameters || [];
+					const stackName = event.ResourceProperties.StackName || '';
+					const tags = stackName ? [{ Key: 'aws-blocks-stack', Value: stackName }] : [];
+					const oldParams = readOld(event.OldResourceProperties || {});
+					const names = params.map(p => p.name);
+					const oldByName = Object.fromEntries(oldParams.map(p => [p.name, p]));
+					if (event.RequestType === 'Delete') {
+						for (const name of names) {
+							try { await client.send(new DeleteParameterCommand({ Name: name })); } catch {}
 						}
+						return { PhysicalResourceId: 'bb-secrets-bulk' };
 					}
-					for (const name of removed) {
-						try { await client.send(new DeleteParameterCommand({ Name: name })); } catch {}
+					if (event.RequestType === 'Create') {
+						for (const p of params) await putSecret(p, tags);
+						return { PhysicalResourceId: 'bb-secrets-bulk' };
+					}
+					if (event.RequestType === 'Update') {
+						for (const p of params) {
+							const old = oldByName[p.name];
+							if (!old) { await putSecret(p, tags); continue; }        // newly added
+							if ((old.keyId || '') !== (p.keyId || '')) await reencrypt(p); // key changed => re-key, preserving value
+							// else: unchanged — leave the runtime-managed value alone
+						}
+						for (const name of Object.keys(oldByName)) {
+							if (!names.includes(name)) { try { await client.send(new DeleteParameterCommand({ Name: name })); } catch {} }
+						}
+						return { PhysicalResourceId: 'bb-secrets-bulk' };
 					}
 					return { PhysicalResourceId: 'bb-secrets-bulk' };
-				}
-				return { PhysicalResourceId: 'bb-secrets-bulk' };
-			};
-		`),
+				};
+			`),
 	});
 
 	secretInitFn.addToRolePolicy(new iam.PolicyStatement({
-		actions: ['ssm:PutParameter', 'ssm:DeleteParameter', 'ssm:AddTagsToResource'],
+		// GetParameter is needed to read a secret's current value when re-keying it.
+		actions: ['ssm:GetParameter', 'ssm:PutParameter', 'ssm:DeleteParameter', 'ssm:AddTagsToResource'],
 		resources: cdk.Lazy.list({
-			produce: () => state!.parameterNames.map(name =>
+			produce: () => state!.params.map(p =>
 				stack.formatArn({
 					service: 'ssm',
 					resource: 'parameter',
-					resourceName: name.replace(/^\//, ''),
+					resourceName: p.name.replace(/^\//, ''),
 				})
 			),
 		}),
 	}));
 
+	// SSM SecureString encryption goes through KMS via the SSM service. Scoping to
+	// `kms:ViaService = ssm.<region>` covers both the default aws/ssm key and any
+	// customer-managed key used above (the CMK's own key policy must also allow
+	// this role). Encrypt = create/re-key; Decrypt = read the current value when
+	// re-keying. Standard-tier SecureStrings don't use GenerateDataKey.
 	secretInitFn.addToRolePolicy(new iam.PolicyStatement({
-		actions: ['kms:Encrypt'],
+		actions: ['kms:Encrypt', 'kms:Decrypt'],
 		resources: ['*'],
 		conditions: {
 			StringEquals: {
@@ -284,7 +343,7 @@ function registerSecret(stack: cdk.Stack, parameterName: string): void {
 	new cdk.CustomResource(stack, 'BlocksSecretsBulk', {
 		serviceToken: provider.serviceToken,
 		properties: {
-			ParameterNames: cdk.Lazy.list({ produce: () => state!.parameterNames }),
+			Parameters: cdk.Lazy.any({ produce: () => state!.params }),
 			StackName: (() => { let s = stack; while (s.nestedStackParent) s = s.nestedStackParent; return s.stackName; })(),
 		},
 	});

package/src/index.mock.ts

@@ -86,7 +86,7 @@ export class AppSetting<T = string> extends Scope {
 	static fromExisting<T = string>(
 		scope: ScopeParent,
 		id: string,
-		options: { name: string; secret?: boolean },
+		options: { name: string; secret?: boolean; kmsKeyArn?: string },
 	): AppSetting<T> {
 		const opts: InternalAppSettingOptions<T> = { ...options, external: true };
 		return new AppSetting<T>(scope, id, opts);

package/src/types.ts

@@ -27,8 +27,24 @@ export interface AppSettingOptions<T = string> {
 	value?: T;
 	/** Runtime validation schema. Accepts any StandardSchemaV1 implementation (Zod, Valibot, ArkType). When provided, T is inferred from the schema. */
 	schema?: StandardSchemaV1<T>;
-	/** When true, creates an SSM SecureString parameter encrypted with the default aws/ssm KMS key. */
+	/** When true, creates an SSM SecureString parameter. Encrypted with the default `aws/ssm` KMS key unless `kmsKeyArn` is set. */
 	secret?: boolean;
+	/**
+	 * ARN of a **customer-managed KMS key** used to encrypt this secret's
+	 * SecureString value. When omitted, SSM uses the default `aws/ssm`
+	 * AWS-managed key. Use a CMK when you need to control the decrypt/grant scope
+	 * (e.g. cross-account access, key rotation, or a dedicated key policy).
+	 *
+	 * Only valid together with `secret: true`. The CDK layer grants the shared
+	 * handler `kms:Decrypt` (plus `kms:Encrypt` for stack-managed secrets it
+	 * writes) on this key, and the runtime `put()` passes the key so an overwrite
+	 * does not silently fall back to the default key. Changing this on an existing
+	 * secret re-encrypts its current value under the new key at deploy time.
+	 *
+	 * @example
+	 * new AppSetting(scope, 'apiKey', { secret: true, kmsKeyArn: myKey.keyArn });
+	 */
+	kmsKeyArn?: string;
 	/** Optional logger for internal operations. When omitted, a default Logger at error level is created. */
 	logger?: ChildLogger;
 }

package/src/version.ts

@@ -1,3 +1,3 @@
 // Auto-generated by scripts/generate-version.mjs — do not edit manually
 export const BB_NAME = 'AppSetting';
-export const BB_VERSION = '0.1.4';
+export const BB_VERSION = '0.2.0';