feat(s3): allow configuring S3 Object Lock (#23744)

S3 Object Lock allows configuring various retention holds, for legal and compliance purposes, on an S3 bucket. This enables a write-once-read-many model. Object Lock can only be enabled on new buckets via the CloudFormation (and therefore via the CDK). Updates to an existing bucket will result in a CloudFormation update failure.

This behavior is possible today using Escape Hatches to modify the L1 construct (with the same limitations):

```ts
cfnBucket.addPropertyOverride("ObjectLockEnabled", true);
```

Providing L2 wrappers around this configuration can aleviate some common and easy-to-make mistakes, such as providing `ObjectLockConfiguration` without providing `ObjectLockEnabled` or specifying `"Governance"` instead of `"GOVERNANCE"` for the compliance mode.

It is possible to enable Object Lock without specifying a default duration. Therefore, there needs to be a means to set `ObjectLockEnabled`. This is done with the `ObjectLoc.enabled` property. Since this is a boolean, it can theoretically be set to `false`. If `false` and a `defaultRetention` is provided, an error is thrown.

CloudFormation allows specifying `Days` or `Years` for retention; for simplicity, this implementation always converts to `Days`. Because CloudFormation requires that to be a positive integer, this implementation also proactively performs that validation at synthesis time.

Further, CloudFormation does not allow omitting `ObjectLockEnabled` within `ObjectLockConfiguration`. The following template would result in a validation error that the input does not match the schema:

```yaml
Bucket:
  Type: AWS::S3::Bucket
  Properties:
    ObjectLockEnabled: true
    ObjectLockConfiguration:
      Rule:
        DefaultRetention:
          Days: 1
          Mode: GOVERNANCE
```

Therefore, this implementation also always sets
`ObjectLockConfiguration.ObjectLockEnabled` to `"Enabled"`.

Additionally, it seems that the behavior of doing

```yaml
Bucket:
  Type: AWS::S3::Bucket
  Properties:
    ObjectLockEnabled: true
    ObjectLockConfiguration:
      ObjectLockEnabled: 'Enabled'
```

causes CloudFormation to create the buckets with Object Lock enabled and then just wait and wait and wait. Frankly I didn't wait for the operation to time out so I don't know whether that would succeed or fail, but in any case, that would be a duplicate of specifying only `ObjectLockEnabled: true` (without nested in `ObjectLockConfiguration`) so this implementation prefers the shorter variant, which CloudFormation/S3 also seem to prefer, when Object Lock is enabled without default retention.

Unfortunately, there isn't a way to check during synthesis whether the bucket already exists, so there's not really a way to detect that pitfall. Users will just get the typical CloudFormation error for this situation and a stack rollback.

More variants of Object Lock configuration in S3 and descriptions of what CloudFormation does with them can be found at: https://gist.github.com/788df029f121af14645f31152ff54e32

This _partially_ addresses #5247 (nothing here handles MFA delete).
This follows up on #21738 which has been marked as abandoned.

----

### All Submissions:

* [X] Have you followed the guidelines in our [Contributing guide?](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md)

### Adding new Construct Runtime Dependencies:

* [ ] This PR adds new construct runtime dependencies following the process described [here](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md/#adding-construct-runtime-dependencies)

### New Features

* [X] Have you added the new feature to an [integration test](https://github.com/aws/aws-cdk/blob/main/INTEGRATION_TESTS.md)?
	* [X] Did you use `yarn integ` to deploy the infrastructure and generate the snapshot (i.e. `yarn integ` without `--dry-run`)?

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

Author: laurelmay

packages/@aws-cdk/aws-s3/README.md

@@ -616,3 +616,36 @@ const bucket = new s3.Bucket(this, 'MyBucket', {
   }]
 });
 ```
+
+## Object Lock Configuration
+
+[Object Lock](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lock-overview.html)
+can be configured to enable a write-once-read-many model for an S3 bucket. Object Lock must be
+configured when a bucket is created; if a bucket is created without Object Lock, it cannot be
+enabled later via the CDK.
+
+Object Lock can be enabled on an S3 bucket by specifying:
+
+```ts
+const bucket = new s3.Bucket(this, 'MyBucket', {
+  objectLockEnabled: true
+});
+```
+
+Usually, it is desired to not just enable Object Lock for a bucket but to also configure a
+[retention mode](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lock-overview.html#object-lock-retention-modes)
+and a [retention period](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lock-overview.html#object-lock-retention-periods).
+These can be specified by providing `objectLockDefaultRetention`:
+
+```ts
+// Configure for governance mode with a duration of 7 years
+new s3.Bucket(this, 'Bucket1', {
+  objectLockDefaultRetention: s3.ObjectLockRetention.governance(cdk.Duration.days(7 * 365)),
+});
+
+// Configure for compliance mode with a duration of 1 year
+new s3.Bucket(this, 'Bucket2', {
+  objectLockDefaultRetention: s3.ObjectLockRetention.compliance(cdk.Duration.days(365)),
+});
+
+```

packages/@aws-cdk/aws-s3/lib/bucket.ts

@@ -1401,10 +1401,34 @@ export interface BucketProps {
   /**
    * Whether this bucket should have versioning turned on or not.
    *
-   * @default false
+   * @default false (unless object lock is enabled, then true)
    */
   readonly versioned?: boolean;
 
+  /**
+   * Enable object lock on the bucket.
+   *
+   * Enabling object lock for existing buckets is not supported. Object lock must be
+   * enabled when the bucket is created.
+   *
+   * @see https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lock-overview.html#object-lock-bucket-config-enable
+   *
+   * @default false, unless objectLockDefaultRetention is set (then, true)
+   */
+  readonly objectLockEnabled?: boolean;
+
+  /**
+   * The default retention mode and rules for S3 Object Lock.
+   *
+   * Default retention can be configured after a bucket is created if the bucket already
+   * has object lock enabled. Enabling object lock for existing buckets is not supported.
+   *
+   * @see https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lock-overview.html#object-lock-bucket-config-enable
+   *
+   * @default no default retention period
+   */
+  readonly objectLockDefaultRetention?: ObjectLockRetention;
+
   /**
    * Whether this bucket should send notifications to Amazon EventBridge or not.
    *
@@ -1787,6 +1811,8 @@ export class Bucket extends BucketBase {
     const websiteConfiguration = this.renderWebsiteConfiguration(props);
     this.isWebsite = (websiteConfiguration !== undefined);
 
+    const objectLockConfiguration = this.parseObjectLockConfig(props);
+
     const resource = new CfnBucket(this, 'Resource', {
       bucketName: this.physicalName,
       bucketEncryption,
@@ -1802,6 +1828,8 @@ export class Bucket extends BucketBase {
       ownershipControls: this.parseOwnershipControls(props),
       accelerateConfiguration: props.transferAcceleration ? { accelerationStatus: 'Enabled' } : undefined,
       intelligentTieringConfigurations: this.parseTieringConfig(props),
+      objectLockEnabled: objectLockConfiguration ? true : props.objectLockEnabled,
+      objectLockConfiguration: objectLockConfiguration,
     });
     this._resource = resource;
 
@@ -2164,6 +2192,27 @@ export class Bucket extends BucketBase {
     });
   }
 
+  private parseObjectLockConfig(props: BucketProps): CfnBucket.ObjectLockConfigurationProperty | undefined {
+    const { objectLockEnabled, objectLockDefaultRetention } = props;
+
+    if (!objectLockDefaultRetention) {
+      return undefined;
+    }
+    if (objectLockEnabled === false && objectLockDefaultRetention) {
+      throw new Error('Object Lock must be enabled to configure default retention settings');
+    }
+
+    return {
+      objectLockEnabled: 'Enabled',
+      rule: {
+        defaultRetention: {
+          days: objectLockDefaultRetention.duration.toDays(),
+          mode: objectLockDefaultRetention.mode,
+        },
+      },
+    };
+  }
+
   private renderWebsiteConfiguration(props: BucketProps): CfnBucket.WebsiteConfigurationProperty | undefined {
     if (!props.websiteErrorDocument && !props.websiteIndexDocument && !props.websiteRedirect && !props.websiteRoutingRules) {
       return undefined;
@@ -2231,7 +2280,7 @@ export class Bucket extends BucketBase {
         effect: iam.Effect.ALLOW,
         principals: [new iam.ServicePrincipal('logging.s3.amazonaws.com')],
         actions: ['s3:PutObject'],
-        resources: [this.arnForObjects(prefix ? `${prefix}*`: '*')],
+        resources: [this.arnForObjects(prefix ? `${prefix}*` : '*')],
         conditions: conditions,
       }));
     } else if (this.accessControl && this.accessControl !== BucketAccessControl.LOG_DELIVERY_WRITE) {
@@ -2742,6 +2791,93 @@ export interface RoutingRule {
   readonly condition?: RoutingRuleCondition;
 }
 
+/**
+ * Modes in which S3 Object Lock retention can be configured.
+ *
+ * @see https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lock-overview.html#object-lock-retention-modes
+ */
+export enum ObjectLockMode {
+  /**
+   * The Governance retention mode.
+   *
+   * With governance mode, you protect objects against being deleted by most users, but you can
+   * still grant some users permission to alter the retention settings or delete the object if
+   * necessary. You can also use governance mode to test retention-period settings before
+   * creating a compliance-mode retention period.
+   */
+  GOVERNANCE = 'GOVERNANCE',
+
+  /**
+   * The Compliance retention mode.
+   *
+   * When an object is locked in compliance mode, its retention mode can't be changed, and
+   * its retention period can't be shortened. Compliance mode helps ensure that an object
+   * version can't be overwritten or deleted for the duration of the retention period.
+   */
+  COMPLIANCE = 'COMPLIANCE',
+}
+
+/**
+ * The default retention settings for an S3 Object Lock configuration.
+ *
+ * @see https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lock-overview.html
+ */
+export class ObjectLockRetention {
+  /**
+   * Configure for Governance retention for a specified duration.
+   *
+   * With governance mode, you protect objects against being deleted by most users, but you can
+   * still grant some users permission to alter the retention settings or delete the object if
+   * necessary. You can also use governance mode to test retention-period settings before
+   * creating a compliance-mode retention period.
+   *
+   * @param duration the length of time for which objects should retained
+   * @returns the ObjectLockRetention configuration
+   */
+  public static governance(duration: Duration): ObjectLockRetention {
+    return new ObjectLockRetention(ObjectLockMode.GOVERNANCE, duration);
+  }
+
+  /**
+   * Configure for Compliance retention for a specified duration.
+   *
+   * When an object is locked in compliance mode, its retention mode can't be changed, and
+   * its retention period can't be shortened. Compliance mode helps ensure that an object
+   * version can't be overwritten or deleted for the duration of the retention period.
+   *
+   * @param duration the length of time for which objects should be retained
+   * @returns the ObjectLockRetention configuration
+   */
+  public static compliance(duration: Duration): ObjectLockRetention {
+    return new ObjectLockRetention(ObjectLockMode.COMPLIANCE, duration);
+  }
+
+  /**
+   * The default period for which objects should be retained.
+   */
+  public readonly duration: Duration;
+
+  /**
+   * The retention mode to use for the object lock configuration.
+   *
+   * @see https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lock-overview.html#object-lock-retention-modes
+   */
+  public readonly mode: ObjectLockMode;
+
+  private constructor(mode: ObjectLockMode, duration: Duration) {
+    // https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lock-managing.html#object-lock-managing-retention-limits
+    if (duration.toDays() > 365 * 100) {
+      throw new Error('Object Lock retention duration must be less than 100 years');
+    }
+    if (duration.toDays() < 1) {
+      throw new Error('Object Lock retention duration must be at least 1 day');
+    }
+
+    this.mode = mode;
+    this.duration = duration;
+  }
+}
+
 /**
  * Options for creating Virtual-Hosted style URL.
  */

packages/@aws-cdk/aws-s3/test/bucket.test.ts

@@ -381,6 +381,110 @@ describe('bucket', () => {
     });
   });
 
+  test('bucket with object lock enabled but no retention', () => {
+    const stack = new cdk.Stack();
+    new s3.Bucket(stack, 'Bucket', {
+      objectLockEnabled: true,
+    });
+    Template.fromStack(stack).hasResourceProperties('AWS::S3::Bucket', {
+      ObjectLockEnabled: true,
+      ObjectLockConfiguration: Match.absent(),
+    });
+  });
+
+  test('object lock defaults to disabled', () => {
+    const stack = new cdk.Stack();
+    new s3.Bucket(stack, 'Bucket');
+    Template.fromStack(stack).hasResourceProperties('AWS::S3::Bucket', {
+      ObjectLockEnabled: Match.absent(),
+    });
+  });
+
+  test('object lock defaults to enabled when default retention is specified', () => {
+    const stack = new cdk.Stack();
+    new s3.Bucket(stack, 'Bucket', {
+      objectLockDefaultRetention: s3.ObjectLockRetention.governance(cdk.Duration.days(7 * 365)),
+    });
+    Template.fromStack(stack).hasResourceProperties('AWS::S3::Bucket', {
+      ObjectLockEnabled: true,
+      ObjectLockConfiguration: {
+        ObjectLockEnabled: 'Enabled',
+        Rule: {
+          DefaultRetention: {
+            Mode: 'GOVERNANCE',
+            Days: 7 * 365,
+          },
+        },
+      },
+    });
+  });
+
+  test('bucket with object lock enabled with governance retention', () => {
+    const stack = new cdk.Stack();
+    new s3.Bucket(stack, 'Bucket', {
+      objectLockEnabled: true,
+      objectLockDefaultRetention: s3.ObjectLockRetention.governance(cdk.Duration.days(1)),
+    });
+
+    Template.fromStack(stack).hasResourceProperties('AWS::S3::Bucket', {
+      ObjectLockEnabled: true,
+      ObjectLockConfiguration: {
+        ObjectLockEnabled: 'Enabled',
+        Rule: {
+          DefaultRetention: {
+            Mode: 'GOVERNANCE',
+            Days: 1,
+          },
+        },
+      },
+    });
+  });
+
+  test('bucket with object lock enabled with compliance retention', () => {
+    const stack = new cdk.Stack();
+    new s3.Bucket(stack, 'Bucket', {
+      objectLockEnabled: true,
+      objectLockDefaultRetention: s3.ObjectLockRetention.compliance(cdk.Duration.days(1)),
+    });
+    Template.fromStack(stack).hasResourceProperties('AWS::S3::Bucket', {
+      ObjectLockEnabled: true,
+      ObjectLockConfiguration: {
+        ObjectLockEnabled: 'Enabled',
+        Rule: {
+          DefaultRetention: {
+            Mode: 'COMPLIANCE',
+            Days: 1,
+          },
+        },
+      },
+    });
+  });
+
+  test('bucket with object lock disabled throws error with retention set', () => {
+    const stack = new cdk.Stack();
+    expect(() => new s3.Bucket(stack, 'Bucket', {
+      objectLockEnabled: false,
+      objectLockDefaultRetention: s3.ObjectLockRetention.governance(cdk.Duration.days(1)),
+    })).toThrow('Object Lock must be enabled to configure default retention settings');
+  });
+
+  test('bucket with object lock requires duration than one day', () => {
+    const stack = new cdk.Stack();
+    expect(() => new s3.Bucket(stack, 'Bucket', {
+      objectLockEnabled: true,
+      objectLockDefaultRetention: s3.ObjectLockRetention.governance(cdk.Duration.days(0)),
+    })).toThrow('Object Lock retention duration must be at least 1 day');
+  });
+
+  // https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lock-managing.html#object-lock-managing-retention-limits
+  test('bucket with object lock requires duration less than 100 years', () => {
+    const stack = new cdk.Stack();
+    expect(() => new s3.Bucket(stack, 'Bucket', {
+      objectLockEnabled: true,
+      objectLockDefaultRetention: s3.ObjectLockRetention.governance(cdk.Duration.days(365 * 101)),
+    })).toThrow('Object Lock retention duration must be less than 100 years');
+  });
+
   test('bucket with block public access set to BlockAll', () => {
     const stack = new cdk.Stack();
     new s3.Bucket(stack, 'MyBucket', {

packages/@aws-cdk/aws-s3/test/integ.bucket-object-lock.js.snapshot/ServerAccessLogsImportTestDefaultTestDeployAssert076DA7F5.assets.json

@@ -0,0 +1,19 @@
+{
+  "version": "29.0.0",
+  "files": {
+    "21fbb51d7b23f6a6c262b46a9caee79d744a3ac019fd45422d988b96d44b2a22": {
+      "source": {
+        "path": "ServerAccessLogsImportTestDefaultTestDeployAssert076DA7F5.template.json",
+        "packaging": "file"
+      },
+      "destinations": {
+        "current_account-current_region": {
+          "bucketName": "cdk-hnb659fds-assets-${AWS::AccountId}-${AWS::Region}",
+          "objectKey": "21fbb51d7b23f6a6c262b46a9caee79d744a3ac019fd45422d988b96d44b2a22.json",
+          "assumeRoleArn": "arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-hnb659fds-file-publishing-role-${AWS::AccountId}-${AWS::Region}"
+        }
+      }
+    }
+  },
+  "dockerImages": {}
+}

packages/@aws-cdk/aws-s3/test/integ.bucket-object-lock.js.snapshot/ServerAccessLogsImportTestDefaultTestDeployAssert076DA7F5.template.json

@@ -0,0 +1,36 @@
+{
+ "Parameters": {
+  "BootstrapVersion": {
+   "Type": "AWS::SSM::Parameter::Value<String>",
+   "Default": "/cdk-bootstrap/hnb659fds/version",
+   "Description": "Version of the CDK Bootstrap resources in this environment, automatically retrieved from SSM Parameter Store. [cdk:skip]"
+  }
+ },
+ "Rules": {
+  "CheckBootstrapVersion": {
+   "Assertions": [
+    {
+     "Assert": {
+      "Fn::Not": [
+       {
+        "Fn::Contains": [
+         [
+          "1",
+          "2",
+          "3",
+          "4",
+          "5"
+         ],
+         {
+          "Ref": "BootstrapVersion"
+         }
+        ]
+       }
+      ]
+     },
+     "AssertDescription": "CDK bootstrap stack version 6 required. Please run 'cdk bootstrap' with a recent version of the CDK CLI."
+    }
+   ]
+  }
+ }
+}