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

package/DESIGN.md

@@ -27,16 +27,17 @@ CloudFormation cannot natively create SSM SecureString parameters. The CDK imple
   - Uses `lambda.Code.fromInline()` with `@aws-sdk/client-ssm` and `crypto`
   - On `Create`: generates a **random** secret via `crypto.randomBytes(32).toString('base64url')` and calls `PutParameterCommand` with `Type: 'SecureString'`, `Overwrite: false` (no serialized initial value — secrets never come from source)
   - On `Delete`: calls `DeleteParameterCommand` to clean up the parameter
-  - On `Update`: generates a random secret for newly added names (same as `Create`) **and** deletes parameters for names removed since the previous deployment (not a no-op); existing values are left untouched and managed at runtime via `put()`
-  - Granted `ssm:PutParameter` and `ssm:DeleteParameter` scoped to the parameter ARN, plus `kms:Encrypt` (with the `kms:ViaService` condition) so it can write the encrypted SecureString
-  - A single shared Lambda + `CustomResource` is created per stack; each secret parameter name is appended to the resource's `ParameterNames` list
+  - On `Update`: generates a random secret for newly added names (same as `Create`) **and** deletes parameters for names removed since the previous deployment (not a no-op). Existing values are left untouched **unless the secret's `keyId` changed** (i.e. `kmsKeyArn` was added/changed/removed) — in that case it reads the current value (`GetParameter` with decryption) and rewrites it under the new key (`Overwrite: true`), so the value survives a key rotation and the handler's new key-scoped grant stays consistent
+  - Granted `ssm:GetParameter`/`ssm:PutParameter`/`ssm:DeleteParameter` scoped to the parameter ARN, plus `kms:Encrypt`/`kms:Decrypt` (scoped by the `kms:ViaService` condition to `ssm.{region}`) so it can create, read-when-re-keying, and re-encrypt SecureStrings under either the default `aws/ssm` key or a customer-managed key
+  - A single shared Lambda + `CustomResource` is created per stack; each secret is appended to the resource's `Parameters` list as `{ name, keyId? }` — the optional `keyId` carries the customer-managed KMS key ARN and is passed as `KeyId` on `PutParameter`
 
-- **KMS encryption:** Uses the default `aws/ssm` managed KMS key (no custom key needed, $0/month)
+- **KMS encryption:** Uses the default `aws/ssm` managed KMS key (no custom key needed, $0/month). Set `kmsKeyArn` to encrypt with a **customer-managed key** instead: the bulk-init Custom Resource passes it as `KeyId` on `PutParameter`, the handler is granted `kms:Decrypt`/`Encrypt` on that specific key ARN, and the runtime `put()` re-specifies the key on overwrite (SSM would otherwise fall back to `aws/ssm`). Changing `kmsKeyArn` later re-encrypts the existing value (see the Update behavior above). The CMK's own key policy must permit the app's execution role.
 
 - **Handler permissions (the runtime `this.handler`):**
   - `ssm:GetParameter` on the parameter ARN
   - `ssm:PutParameter` on the parameter ARN
-  - `kms:Decrypt` **and** `kms:Encrypt` with a `kms:ViaService` condition restricting usage to `ssm.{region}.amazonaws.com`
+  - Default `aws/ssm` key: `kms:Decrypt` **and** `kms:Encrypt` with a `kms:ViaService` condition restricting usage to `ssm.{region}.amazonaws.com`
+  - Customer-managed key (`kmsKeyArn` set): `kms:Decrypt` **and** `kms:Encrypt` scoped to that specific key ARN, with **no** `ViaService` condition (see *KMS encryption* above). The CMK's own key policy must also permit this role.
 
 ## Serialization & Validation
 
@@ -63,7 +64,7 @@ The 4 KB (4096 bytes) size limit applies to the **JSON-encoded** value of non-se
 - `put()` writes the value to disk immediately.
 - Schema validation on `put()` when configured, throws `ValidationFailedException`.
 - Validates 4 KB serialized value size limit for non-secret parameters.
-- `secret: true` behaves identically to non-secret (no encryption locally).
+- `secret: true` behaves identically to non-secret (no encryption locally); `kmsKeyArn` is ignored in the mock.
 
 ### Mock vs AWS Behavior Differences
 

package/README.md

@@ -26,9 +26,20 @@ const setting = new AppSetting(scope, id, options)
 | `name` | `string` | No | SSM parameter path. When omitted, derived from the scope tree as `/${fullId}`, guaranteeing uniqueness within the stack. |
 | `value` | `T` | No | Initial value. Required for non-secret parameters. Must not be provided when `secret` is set. |
 | `schema` | `StandardSchemaV1<T>` | No | Runtime validation schema (Zod, Valibot, ArkType). Infers `T` from the schema. Cannot be used with `secret`. |
-| `secret` | `boolean` | No | When `true`, creates an SSM SecureString encrypted with the `aws/ssm` KMS key. Cannot be used with `schema` or `value`. |
+| `secret` | `boolean` | No | When `true`, creates an SSM SecureString encrypted with the default `aws/ssm` KMS key (or `kmsKeyArn` when set). Cannot be used with `schema` or `value`. |
+| `kmsKeyArn` | `string` | No | ARN of a customer-managed KMS key to encrypt the SecureString, instead of the default `aws/ssm` key. Only valid with `secret: true`. See the note below. |
 | `logger` | `ChildLogger` | No | Optional logger for internal operations. When omitted, a default Logger at error level is created. |
 
+> **Customer-managed KMS key (`kmsKeyArn`):** Provide a CMK ARN to control the
+> decrypt/grant scope of a secret (e.g. cross-account access or a dedicated key
+> policy). The construct grants the shared handler `kms:Decrypt` (plus
+> `kms:Encrypt` for secrets it writes) on that specific key ARN. Because AWS
+> Blocks does not own a bring-your-own key, **the key's own key policy must also
+> allow the app's Lambda execution role** to use it (or delegate to IAM via the
+> account-root statement CDK adds to same-account keys). Adding or changing
+> `kmsKeyArn` on an already-deployed secret re-encrypts its current value under
+> the new key on the next deploy, so decryption keeps working.
+
 > **Naming:** When you omit `name`, the framework derives a unique SSM path from
 > the construct scope tree (`/${fullId}`). This is the recommended approach — it
 > prevents collisions across stacks automatically. If you provide an explicit

package/dist/index.aws.d.ts

@@ -33,10 +33,12 @@ export declare class AppSetting<T = string> extends Scope {
     static fromExisting<T = string>(scope: ScopeParent, id: string, options: {
         name: string;
         secret?: boolean;
+        kmsKeyArn?: string;
     }): AppSetting<T>;
     readonly bbName = "AppSetting";
     private schema?;
     private isSecret;
+    private kmsKeyArn?;
     private client;
     /** @internal Logger for internal operations. Defaults to error-level when not provided. */
     protected log: ChildLogger;

package/dist/index.aws.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.aws.d.ts","sourceRoot":"","sources":["../src/index.aws.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,KAAK,EAA6C,MAAM,kBAAkB,CAAC;AACpF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAGpD,OAAO,KAAK,EAAE,iBAAiB,EAA6B,MAAM,YAAY,CAAC;AAG/E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAGzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,YAAY,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAqBpD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,UAAU,CAAC,CAAC,GAAG,MAAM,CAAE,SAAQ,KAAK;IAChD;;;;;;OAMG;IACH,MAAM,CAAC,YAAY,CAAC,CAAC,GAAG,MAAM,EAC7B,KAAK,EAAE,WAAW,EAClB,EAAE,EAAE,MAAM,EACV,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GACzC,UAAU,CAAC,CAAC,CAAC;IAKhB,QAAQ,CAAC,MAAM,gBAAW;IAC1B,OAAO,CAAC,MAAM,CAAC,CAAsB;IACrC,OAAO,CAAC,QAAQ,CAAU;IAC1B,OAAO,CAAC,MAAM,CAAY;IAE1B,2FAA2F;IAC3F,SAAS,CAAC,GAAG,EAAE,WAAW,CAAC;gBAEf,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC;IAazE;;;;;;;;;;;;;OAaG;IACG,GAAG,IAAI,OAAO,CAAC,CAAC,CAAC;IA2BvB;;;;;;;;;;;;;;OAcG;IACG,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;CAYlC"}
+{"version":3,"file":"index.aws.d.ts","sourceRoot":"","sources":["../src/index.aws.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,KAAK,EAA6C,MAAM,kBAAkB,CAAC;AACpF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAGpD,OAAO,KAAK,EAAE,iBAAiB,EAA6B,MAAM,YAAY,CAAC;AAG/E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAGzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,YAAY,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAqBpD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,UAAU,CAAC,CAAC,GAAG,MAAM,CAAE,SAAQ,KAAK;IAChD;;;;;;OAMG;IACH,MAAM,CAAC,YAAY,CAAC,CAAC,GAAG,MAAM,EAC7B,KAAK,EAAE,WAAW,EAClB,EAAE,EAAE,MAAM,EACV,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAC7D,UAAU,CAAC,CAAC,CAAC;IAKhB,QAAQ,CAAC,MAAM,gBAAW;IAC1B,OAAO,CAAC,MAAM,CAAC,CAAsB;IACrC,OAAO,CAAC,QAAQ,CAAU;IAC1B,OAAO,CAAC,SAAS,CAAC,CAAS;IAC3B,OAAO,CAAC,MAAM,CAAY;IAE1B,2FAA2F;IAC3F,SAAS,CAAC,GAAG,EAAE,WAAW,CAAC;gBAEf,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC;IAczE;;;;;;;;;;;;;OAaG;IACG,GAAG,IAAI,OAAO,CAAC,CAAC,CAAC;IA2BvB;;;;;;;;;;;;;;OAcG;IACG,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;CAelC"}

package/dist/index.aws.js

@@ -56,6 +56,7 @@ export class AppSetting extends Scope {
     bbName = BB_NAME;
     schema;
     isSecret;
+    kmsKeyArn;
     client;
     /** @internal Logger for internal operations. Defaults to error-level when not provided. */
     log;
@@ -65,6 +66,7 @@ export class AppSetting 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(),
         });
@@ -130,6 +132,9 @@ export class AppSetting 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/dist/index.aws.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.aws.test.d.ts.map

package/dist/index.aws.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.aws.test.d.ts","sourceRoot":"","sources":["../src/index.aws.test.ts"],"names":[],"mappings":""}

package/dist/index.aws.test.js

@@ -0,0 +1,56 @@
+// 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 = [];
+    const m = mock.method(SSMClient.prototype, 'send', async (cmd) => {
+        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(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/dist/index.cdk.d.ts

@@ -10,7 +10,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 declare class AppSetting<T = string> extends Scope {
     /**
@@ -29,6 +31,7 @@ export declare class AppSetting<T = string> extends Scope {
     static fromExisting<T = string>(scope: ScopeParent, id: string, options: {
         name: string;
         secret?: boolean;
+        kmsKeyArn?: string;
     }): AppSetting<T>;
     constructor(scope: ScopeParent, id: string, options: AppSettingOptions<T>);
 }

package/dist/index.cdk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.cdk.d.ts","sourceRoot":"","sources":["../src/index.cdk.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,KAAK,EAAwC,MAAM,sBAAsB,CAAC;AACnF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,OAAO,KAAK,EAAE,iBAAiB,EAA6B,MAAM,YAAY,CAAC;AAE/E,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,YAAY,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD;;;;;;;;GAQG;AACH,qBAAa,UAAU,CAAC,CAAC,GAAG,MAAM,CAAE,SAAQ,KAAK;IAChD;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,YAAY,CAAC,CAAC,GAAG,MAAM,EAC7B,KAAK,EAAE,WAAW,EAClB,EAAE,EAAE,MAAM,EACV,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GACzC,UAAU,CAAC,CAAC,CAAC;gBAKJ,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC;CA0HzE"}
+{"version":3,"file":"index.cdk.d.ts","sourceRoot":"","sources":["../src/index.cdk.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,KAAK,EAAwC,MAAM,sBAAsB,CAAC;AACnF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,OAAO,KAAK,EAAE,iBAAiB,EAA6B,MAAM,YAAY,CAAC;AAE/E,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,YAAY,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD;;;;;;;;;;GAUG;AACH,qBAAa,UAAU,CAAC,CAAC,GAAG,MAAM,CAAE,SAAQ,KAAK;IAChD;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,YAAY,CAAC,CAAC,GAAG,MAAM,EAC7B,KAAK,EAAE,WAAW,EAClB,EAAE,EAAE,MAAM,EACV,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAC7D,UAAU,CAAC,CAAC,CAAC;gBAKJ,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC;CAyJzE"}

package/dist/index.cdk.js

@@ -15,7 +15,9 @@ export { AppSettingErrors } from './errors.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 extends Scope {
     /**
@@ -53,6 +55,20 @@ export class AppSetting extends Scope {
             err.name = AppSettingErrors.ValidationFailed;
             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. ` +
                 `Remove the value — a random secret will be generated on first deploy. ` +
@@ -96,20 +112,33 @@ export class AppSetting 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 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],
+                }));
             }
-            // 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`,
+            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 ──────────────────────────
@@ -125,7 +154,7 @@ export class AppSetting extends Scope {
         // (external non-secret: parameter exists already; nothing to create.)
         // 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],
         }));
@@ -137,90 +166,110 @@ export class AppSetting extends Scope {
 // ── Bulk Secret Initialization (one CustomResource per stack) ───────────────
 const SECRET_BULK_KEY = Symbol.for('BLOCKS_SECRET_BULK_INIT');
 /**
- * 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, parameterName) {
+function registerSecret(stack, parameterName, keyId) {
     let state = stack[SECRET_BULK_KEY];
     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[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 => stack.formatArn({
+            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: {
@@ -234,7 +283,7 @@ function registerSecret(stack, parameterName) {
     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/dist/index.cdk.test.js

@@ -14,15 +14,20 @@ import { Scope, DEFAULT_NODE_RUNTIME } from '@aws-blocks/core/cdk';
 import { AppSetting } from './index.cdk.js';
 class StubBlocksStack extends cdk.Stack {
     handler;
+    executionRole;
     id;
     constructor(scope, id) {
         super(scope, id);
         this.id = id;
         globalThis.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,
         });
     }
 }
@@ -185,3 +190,106 @@ test('CDK: fromExisting still registers the runtime config key (BLOCKS_SSM_PARAM
     assert.ok(registry.entries.has('BLOCKS_SSM_PARAM_DB_URL'), 'external setting must register BLOCKS_SSM_PARAM_DB_URL so the runtime can resolve the parameter');
     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) => 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;
+    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;
+    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;
+    let bulkKms;
+    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('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/dist/index.mock.d.ts

@@ -36,6 +36,7 @@ export declare class AppSetting<T = string> extends Scope {
     static fromExisting<T = string>(scope: ScopeParent, id: string, options: {
         name: string;
         secret?: boolean;
+        kmsKeyArn?: string;
     }): AppSetting<T>;
     private parameterName;
     private initialValue;

package/dist/index.mock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.mock.d.ts","sourceRoot":"","sources":["../src/index.mock.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,EAA0B,MAAM,kBAAkB,CAAC;AAEjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAMpD,OAAO,KAAK,EAAE,iBAAiB,EAA6B,MAAM,YAAY,CAAC;AAE/E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAIzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,YAAY,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAsCpD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,UAAU,CAAC,CAAC,GAAG,MAAM,CAAE,SAAQ,KAAK;IAChD;;;;;;;;;OASG;IACH,MAAM,CAAC,YAAY,CAAC,CAAC,GAAG,MAAM,EAC7B,KAAK,EAAE,WAAW,EAClB,EAAE,EAAE,MAAM,EACV,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GACzC,UAAU,CAAC,CAAC,CAAC;IAKhB,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,YAAY,CAAI;IACxB,OAAO,CAAC,MAAM,CAAC,CAAsB;IACrC,OAAO,CAAC,QAAQ,CAAU;IAE1B,2FAA2F;IAC3F,SAAS,CAAC,GAAG,EAAE,WAAW,CAAC;gBAEf,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC;IAyBzE;;;;;;;;;;;OAWG;IACG,GAAG,IAAI,OAAO,CAAC,CAAC,CAAC;IAWvB;;;;;;;;;;;;;;OAcG;IACG,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;CAelC"}
+{"version":3,"file":"index.mock.d.ts","sourceRoot":"","sources":["../src/index.mock.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,EAA0B,MAAM,kBAAkB,CAAC;AAEjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAMpD,OAAO,KAAK,EAAE,iBAAiB,EAA6B,MAAM,YAAY,CAAC;AAE/E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAIzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,YAAY,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAsCpD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,UAAU,CAAC,CAAC,GAAG,MAAM,CAAE,SAAQ,KAAK;IAChD;;;;;;;;;OASG;IACH,MAAM,CAAC,YAAY,CAAC,CAAC,GAAG,MAAM,EAC7B,KAAK,EAAE,WAAW,EAClB,EAAE,EAAE,MAAM,EACV,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAC7D,UAAU,CAAC,CAAC,CAAC;IAKhB,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,YAAY,CAAI;IACxB,OAAO,CAAC,MAAM,CAAC,CAAsB;IACrC,OAAO,CAAC,QAAQ,CAAU;IAE1B,2FAA2F;IAC3F,SAAS,CAAC,GAAG,EAAE,WAAW,CAAC;gBAEf,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC;IAyBzE;;;;;;;;;;;OAWG;IACG,GAAG,IAAI,OAAO,CAAC,CAAC,CAAC;IAWvB;;;;;;;;;;;;;;OAcG;IACG,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;CAelC"}