isLookupDummy method

packages/aws-cdk-lib/aws-kms/README.md

@@ -127,15 +127,16 @@ If the target key is not found in your account, an error will be thrown.
 To prevent the error in the case, you can receive a dummy key without the error
 by setting `returnDummyKeyOnMissing` to `true`. The dummy key has a `keyId` of
 `1234abcd-12ab-34cd-56ef-1234567890ab`. The value of the dummy key id can also be
-referenced using the `Key.DEFAULT_DUMMY_KEY_ID` variable.
+referenced using the `Key.DEFAULT_DUMMY_KEY_ID` variable, and you can check if the
+key is a dummy key by using the `Key.isLookupDummy()` method.
 
 ```ts
 const dummy = kms.Key.fromLookup(this, 'MyKeyLookup', {
   aliasName: 'alias/NonExistentAlias',
   returnDummyKeyOnMissing: true,
 });
 
-if (dummy.keyId === kms.Key.DEFAULT_DUMMY_KEY_ID) { // '1234abcd-12ab-34cd-56ef-1234567890ab'
+if (kms.Key.isLookupDummy(dummy)) {
   // alternative process
 }
 ```

packages/aws-cdk-lib/aws-kms/lib/key-lookup.ts

@@ -15,7 +15,9 @@ export interface KeyLookupOptions {
    * If it is set to `true` and the key was not found, a dummy
    * key with a key id '1234abcd-12ab-34cd-56ef-1234567890ab'
    * will be returned. The value of the dummy key id can also
-   * be referenced using the `Key.DEFAULT_DUMMY_KEY_ID` variable.
+   * be referenced using the `Key.DEFAULT_DUMMY_KEY_ID` variable,
+   * and you can check if the key is a dummy key by using the
+   * `Key.isLookupDummy()` method.
    *
    * @default false
    */

packages/aws-cdk-lib/aws-kms/lib/key.ts

@@ -557,7 +557,8 @@ export class Key extends KeyBase {
   /**
    * The default key id of the dummy key.
    *
-   * This value is used as a dummy key id if the key was not found by the `fromLookup` method.
+   * This value is used as a dummy key id if the key was not found
+   * by the `Key.fromLookup()` method.
    */
   public static readonly DEFAULT_DUMMY_KEY_ID = '1234abcd-12ab-34cd-56ef-1234567890ab';
 
@@ -661,7 +662,8 @@ export class Key extends KeyBase {
    * If you set `returnDummyKeyOnMissing` to `true` in `options` and the key was not found,
    * this method will return a dummy key with a key id '1234abcd-12ab-34cd-56ef-1234567890ab'.
    * The value of the dummy key id can also be referenced using the `Key.DEFAULT_DUMMY_KEY_ID`
-   * variable.
+   * variable, and you can check if the key is a dummy key by using the `Key.isLookupDummy()`
+   * method.
    *
    * The Key information will be cached in `cdk.context.json` and the same Key
    * will be used on future runs. To refresh the lookup, you will have to
@@ -704,6 +706,17 @@ export class Key extends KeyBase {
       Arn.format({ resource: 'key', service: 'kms', resourceName: attributes.keyId }, Stack.of(scope)));
   }
 
+  /**
+   * Checks if the key returned by the `fromLookup` method is a dummy key,
+   * i.e., a key that was not found.
+   *
+   * This method can only be used if the `returnDummyKeyOnMissing` option
+   * is set to `true` in the `options` for the `Key.fromLookup()` method.
+   */
+  public static isLookupDummy(key: IKey): boolean {
+    return key.keyId === Key.DEFAULT_DUMMY_KEY_ID;
+  }
+
   public readonly keyArn: string;
   public readonly keyId: string;
   protected readonly policy?: iam.PolicyDocument;

packages/aws-cdk-lib/aws-kms/test/key.from-lookup.test.ts

@@ -66,6 +66,38 @@ test('return dummy key if returnDummyKeyOnMissing is true', () => {
   ]);
 });
 
+describe('isLookupDummy method', () => {
+  test('return false if the lookup key is not a dummy key', () => {
+    const previous = mockKeyContextProviderWith({
+      keyId: '12345678-1234-1234-1234-123456789012',
+    }, options => {
+      expect(options.aliasName).toEqual('alias/foo');
+    });
+
+    const app = new App();
+    const stack = new Stack(app, 'MyStack', { env: { region: 'us-east-1', account: '123456789012' } });
+    const key = Key.fromLookup(stack, 'Key', {
+      aliasName: 'alias/foo',
+      returnDummyKeyOnMissing: true,
+    });
+
+    expect(Key.isLookupDummy(key)).toEqual(false);
+
+    restoreContextProvider(previous);
+  });
+
+  test('return true if the lookup key is a dummy key', () => {
+    const app = new App();
+    const stack = new Stack(app, 'MyStack', { env: { region: 'us-east-1', account: '123456789012' } });
+    const key = Key.fromLookup(stack, 'Key', {
+      aliasName: 'alias/foo',
+      returnDummyKeyOnMissing: true,
+    });
+
+    expect(Key.isLookupDummy(key)).toEqual(true);
+  });
+});
+
 interface MockKeyContextResponse {
   readonly keyId: string;
 }