@ashishpandeyone/cdk-lambda-web-function 0.1.10 → 0.1.12

package/API.md

@@ -63,6 +63,8 @@ new NodejsWebFunction(scope: Construct, id: string, props: NodejsWebFunctionProp
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunction.addEnvironment">addEnvironment</a></code> | Adds an environment variable. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunction.addPermission">addPermission</a></code> | Allows a principal in another account, an AWS service or an organization to call the function's endpoints, through the function's resource policy. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunction.addToRolePolicy">addToRolePolicy</a></code> | Adds a statement to the execution role's policy. |
+| <code><a href="#@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunction.encryptionKeyPolicyStatement">encryptionKeyPolicyStatement</a></code> | The key-policy statement Lambda needs to start this function's environments with `encryptionKey`: `kms:Decrypt` for `lambda.amazonaws.com`, limited to this function's revisions (`aws:SourceArn` and the encryption context Lambda sets). |
+| <code><a href="#@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunction.logEncryptionKeyPolicyStatement">logEncryptionKeyPolicyStatement</a></code> | The key-policy statement CloudWatch Logs needs in `region` to encrypt this function's log groups there with `logEncryptionKey`, limited to those groups (`kms:EncryptionContext:aws:logs:arn`). |
 
 ---
 
@@ -351,6 +353,36 @@ Adds a statement to the execution role's policy.
 
 ---
 
+##### `encryptionKeyPolicyStatement` <a name="encryptionKeyPolicyStatement" id="@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunction.encryptionKeyPolicyStatement"></a>
+
+```typescript
+public encryptionKeyPolicyStatement(): PolicyStatement
+```
+
+The key-policy statement Lambda needs to start this function's environments with `encryptionKey`: `kms:Decrypt` for `lambda.amazonaws.com`, limited to this function's revisions (`aws:SourceArn` and the encryption context Lambda sets).
+
+It's added to `encryptionKey` when the key is defined in this app. Add it to every replica of a multi-Region key
+yourself: replicas don't share their primary's policy.
+
+##### `logEncryptionKeyPolicyStatement` <a name="logEncryptionKeyPolicyStatement" id="@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunction.logEncryptionKeyPolicyStatement"></a>
+
+```typescript
+public logEncryptionKeyPolicyStatement(region: string): PolicyStatement
+```
+
+The key-policy statement CloudWatch Logs needs in `region` to encrypt this function's log groups there with `logEncryptionKey`, limited to those groups (`kms:EncryptionContext:aws:logs:arn`).
+
+It's added to `logEncryptionKey` for the key's own region when the key is defined in this app. Add it to the
+replica in every other region the function serves from yourself: replicas don't share their primary's policy.
+
+###### `region`<sup>Required</sup> <a name="region" id="@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunction.logEncryptionKeyPolicyStatement.parameter.region"></a>
+
+- *Type:* string
+
+the region of the key or replica.
+
+---
+
 #### Static Functions <a name="Static Functions" id="Static Functions"></a>
 
 | **Name** | **Description** |
@@ -529,6 +561,8 @@ Imports an existing Web Function in this stack's account and region by its name.
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunction.property.logGroup">logGroup</a></code> | <code>aws-cdk-lib.aws_logs.ILogGroup</code> | The home-region log group that receives the logs of every region the function serves from. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunction.property.revisionId">revisionId</a></code> | <code>string</code> | The ID of the current revision. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunction.property.role">role</a></code> | <code>aws-cdk-lib.aws_iam.IRole</code> | The execution role. |
+| <code><a href="#@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunction.property.encryptionKey">encryptionKey</a></code> | <code>aws-cdk-lib.aws_kms.IKey</code> | The customer managed key of the function's revisions, if any. |
+| <code><a href="#@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunction.property.logEncryptionKey">logEncryptionKey</a></code> | <code>aws-cdk-lib.aws_kms.IKey</code> | The customer managed key of the function's log groups, if any. |
 
 ---
 
@@ -702,6 +736,30 @@ The execution role.
 
 ---
 
+##### `encryptionKey`<sup>Optional</sup> <a name="encryptionKey" id="@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunction.property.encryptionKey"></a>
+
+```typescript
+public readonly encryptionKey: IKey;
+```
+
+- *Type:* aws-cdk-lib.aws_kms.IKey
+
+The customer managed key of the function's revisions, if any.
+
+---
+
+##### `logEncryptionKey`<sup>Optional</sup> <a name="logEncryptionKey" id="@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunction.property.logEncryptionKey"></a>
+
+```typescript
+public readonly logEncryptionKey: IKey;
+```
+
+- *Type:* aws-cdk-lib.aws_kms.IKey
+
+The customer managed key of the function's log groups, if any.
+
+---
+
 #### Constants <a name="Constants" id="Constants"></a>
 
 | **Name** | **Type** | **Description** |
@@ -788,6 +846,8 @@ new WebFunction(scope: Construct, id: string, props: WebFunctionProps)
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunction.addEnvironment">addEnvironment</a></code> | Adds an environment variable. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunction.addPermission">addPermission</a></code> | Allows a principal in another account, an AWS service or an organization to call the function's endpoints, through the function's resource policy. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunction.addToRolePolicy">addToRolePolicy</a></code> | Adds a statement to the execution role's policy. |
+| <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunction.encryptionKeyPolicyStatement">encryptionKeyPolicyStatement</a></code> | The key-policy statement Lambda needs to start this function's environments with `encryptionKey`: `kms:Decrypt` for `lambda.amazonaws.com`, limited to this function's revisions (`aws:SourceArn` and the encryption context Lambda sets). |
+| <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunction.logEncryptionKeyPolicyStatement">logEncryptionKeyPolicyStatement</a></code> | The key-policy statement CloudWatch Logs needs in `region` to encrypt this function's log groups there with `logEncryptionKey`, limited to those groups (`kms:EncryptionContext:aws:logs:arn`). |
 
 ---
 
@@ -1076,6 +1136,36 @@ Adds a statement to the execution role's policy.
 
 ---
 
+##### `encryptionKeyPolicyStatement` <a name="encryptionKeyPolicyStatement" id="@ashishpandeyone/cdk-lambda-web-function.WebFunction.encryptionKeyPolicyStatement"></a>
+
+```typescript
+public encryptionKeyPolicyStatement(): PolicyStatement
+```
+
+The key-policy statement Lambda needs to start this function's environments with `encryptionKey`: `kms:Decrypt` for `lambda.amazonaws.com`, limited to this function's revisions (`aws:SourceArn` and the encryption context Lambda sets).
+
+It's added to `encryptionKey` when the key is defined in this app. Add it to every replica of a multi-Region key
+yourself: replicas don't share their primary's policy.
+
+##### `logEncryptionKeyPolicyStatement` <a name="logEncryptionKeyPolicyStatement" id="@ashishpandeyone/cdk-lambda-web-function.WebFunction.logEncryptionKeyPolicyStatement"></a>
+
+```typescript
+public logEncryptionKeyPolicyStatement(region: string): PolicyStatement
+```
+
+The key-policy statement CloudWatch Logs needs in `region` to encrypt this function's log groups there with `logEncryptionKey`, limited to those groups (`kms:EncryptionContext:aws:logs:arn`).
+
+It's added to `logEncryptionKey` for the key's own region when the key is defined in this app. Add it to the
+replica in every other region the function serves from yourself: replicas don't share their primary's policy.
+
+###### `region`<sup>Required</sup> <a name="region" id="@ashishpandeyone/cdk-lambda-web-function.WebFunction.logEncryptionKeyPolicyStatement.parameter.region"></a>
+
+- *Type:* string
+
+the region of the key or replica.
+
+---
+
 #### Static Functions <a name="Static Functions" id="Static Functions"></a>
 
 | **Name** | **Description** |
@@ -1254,6 +1344,8 @@ Imports an existing Web Function in this stack's account and region by its name.
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunction.property.logGroup">logGroup</a></code> | <code>aws-cdk-lib.aws_logs.ILogGroup</code> | The home-region log group that receives the logs of every region the function serves from. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunction.property.revisionId">revisionId</a></code> | <code>string</code> | The ID of the current revision. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunction.property.role">role</a></code> | <code>aws-cdk-lib.aws_iam.IRole</code> | The execution role. |
+| <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunction.property.encryptionKey">encryptionKey</a></code> | <code>aws-cdk-lib.aws_kms.IKey</code> | The customer managed key of the function's revisions, if any. |
+| <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunction.property.logEncryptionKey">logEncryptionKey</a></code> | <code>aws-cdk-lib.aws_kms.IKey</code> | The customer managed key of the function's log groups, if any. |
 
 ---
 
@@ -1427,6 +1519,30 @@ The execution role.
 
 ---
 
+##### `encryptionKey`<sup>Optional</sup> <a name="encryptionKey" id="@ashishpandeyone/cdk-lambda-web-function.WebFunction.property.encryptionKey"></a>
+
+```typescript
+public readonly encryptionKey: IKey;
+```
+
+- *Type:* aws-cdk-lib.aws_kms.IKey
+
+The customer managed key of the function's revisions, if any.
+
+---
+
+##### `logEncryptionKey`<sup>Optional</sup> <a name="logEncryptionKey" id="@ashishpandeyone/cdk-lambda-web-function.WebFunction.property.logEncryptionKey"></a>
+
+```typescript
+public readonly logEncryptionKey: IKey;
+```
+
+- *Type:* aws-cdk-lib.aws_kms.IKey
+
+The customer managed key of the function's log groups, if any.
+
+---
+
 #### Constants <a name="Constants" id="Constants"></a>
 
 | **Name** | **Type** | **Description** |
@@ -2965,8 +3081,10 @@ const nodejsWebFunctionProps: NodejsWebFunctionProps = { ... }
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunctionProps.property.authType">authType</a></code> | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionAuthType">WebFunctionAuthType</a></code> | How callers of the endpoint are authenticated. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunctionProps.property.applicationLogLevelV2">applicationLogLevelV2</a></code> | <code>aws-cdk-lib.aws_lambda.ApplicationLogLevel</code> | The minimum level of application logs to keep. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunctionProps.property.description">description</a></code> | <code>string</code> | A description of the function's code and configuration. |
+| <code><a href="#@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunctionProps.property.encryptionKey">encryptionKey</a></code> | <code>aws-cdk-lib.aws_kms.IKey</code> | A customer managed KMS key for the function's revisions: their code and environment variables. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunctionProps.property.endpoint">endpoint</a></code> | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionEndpointOptions">WebFunctionEndpointOptions</a></code> | The default endpoint (`fn.endpoint`): where it serves from, its name and limits. It serves the current revision; route it elsewhere with `fn.endpoint.routeTraffic()`. Add more endpoints with `addEndpoint`. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunctionProps.property.environment">environment</a></code> | <code>{[ key: string ]: string}</code> | Environment variables. |
+| <code><a href="#@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunctionProps.property.logEncryptionKey">logEncryptionKey</a></code> | <code>aws-cdk-lib.aws_kms.IKey</code> | A customer managed KMS key for the function's log groups, in every region it serves from. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunctionProps.property.logRemovalPolicy">logRemovalPolicy</a></code> | <code>aws-cdk-lib.RemovalPolicy</code> | What happens to the log groups when the function is removed: RETAIN or DESTROY. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunctionProps.property.logRetention">logRetention</a></code> | <code>aws-cdk-lib.aws_logs.RetentionDays</code> | Retention for every log group of the function, in every region it serves from. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunctionProps.property.maxConcurrencyPerEnvironment">maxConcurrencyPerEnvironment</a></code> | <code>number</code> | How many requests one execution environment handles at the same time (1-128). |
@@ -3021,6 +3139,27 @@ A description of the function's code and configuration.
 
 ---
 
+##### `encryptionKey`<sup>Optional</sup> <a name="encryptionKey" id="@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunctionProps.property.encryptionKey"></a>
+
+```typescript
+public readonly encryptionKey: IKey;
+```
+
+- *Type:* aws-cdk-lib.aws_kms.IKey
+- *Default:* an AWS owned key
+
+A customer managed KMS key for the function's revisions: their code and environment variables.
+
+A `PER_REGION` or `MULTI_REGION` endpoint needs a **multi-Region key** with a replica in every region it serves
+from, and each replica's policy must allow Lambda to decrypt (see `encryptionKeyPolicyStatement()`). A key defined
+in this app gets that statement added to its own policy.
+
+Changing the key creates a new revision. Earlier revisions, including the ones kept as rollback targets, still
+need their key.
+[disable-awslint:prefer-ref-interface]
+
+---
+
 ##### `endpoint`<sup>Optional</sup> <a name="endpoint" id="@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunctionProps.property.endpoint"></a>
 
 ```typescript
@@ -3049,6 +3188,26 @@ Names starting with `AWS_` are reserved.
 
 ---
 
+##### `logEncryptionKey`<sup>Optional</sup> <a name="logEncryptionKey" id="@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunctionProps.property.logEncryptionKey"></a>
+
+```typescript
+public readonly logEncryptionKey: IKey;
+```
+
+- *Type:* aws-cdk-lib.aws_kms.IKey
+- *Default:* CloudWatch Logs' own encryption
+
+A customer managed KMS key for the function's log groups, in every region it serves from.
+
+CloudWatch Logs needs a key in each group's region: for regions other than the key's own, the construct uses the
+replica of a **multi-Region key** there (the same key ID). Each key's policy must allow CloudWatch Logs in its
+region (see `logEncryptionKeyPolicyStatement()`). A key defined in this app gets that statement for its own region.
+
+Removing the key decrypts nothing: the groups keep their existing events encrypted with it.
+[disable-awslint:prefer-ref-interface]
+
+---
+
 ##### `logRemovalPolicy`<sup>Optional</sup> <a name="logRemovalPolicy" id="@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunctionProps.property.logRemovalPolicy"></a>
 
 ```typescript
@@ -3613,8 +3772,10 @@ const webFunctionOptions: WebFunctionOptions = { ... }
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionOptions.property.authType">authType</a></code> | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionAuthType">WebFunctionAuthType</a></code> | How callers of the endpoint are authenticated. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionOptions.property.applicationLogLevelV2">applicationLogLevelV2</a></code> | <code>aws-cdk-lib.aws_lambda.ApplicationLogLevel</code> | The minimum level of application logs to keep. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionOptions.property.description">description</a></code> | <code>string</code> | A description of the function's code and configuration. |
+| <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionOptions.property.encryptionKey">encryptionKey</a></code> | <code>aws-cdk-lib.aws_kms.IKey</code> | A customer managed KMS key for the function's revisions: their code and environment variables. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionOptions.property.endpoint">endpoint</a></code> | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionEndpointOptions">WebFunctionEndpointOptions</a></code> | The default endpoint (`fn.endpoint`): where it serves from, its name and limits. It serves the current revision; route it elsewhere with `fn.endpoint.routeTraffic()`. Add more endpoints with `addEndpoint`. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionOptions.property.environment">environment</a></code> | <code>{[ key: string ]: string}</code> | Environment variables. |
+| <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionOptions.property.logEncryptionKey">logEncryptionKey</a></code> | <code>aws-cdk-lib.aws_kms.IKey</code> | A customer managed KMS key for the function's log groups, in every region it serves from. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionOptions.property.logRemovalPolicy">logRemovalPolicy</a></code> | <code>aws-cdk-lib.RemovalPolicy</code> | What happens to the log groups when the function is removed: RETAIN or DESTROY. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionOptions.property.logRetention">logRetention</a></code> | <code>aws-cdk-lib.aws_logs.RetentionDays</code> | Retention for every log group of the function, in every region it serves from. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionOptions.property.maxConcurrencyPerEnvironment">maxConcurrencyPerEnvironment</a></code> | <code>number</code> | How many requests one execution environment handles at the same time (1-128). |
@@ -3664,6 +3825,27 @@ A description of the function's code and configuration.
 
 ---
 
+##### `encryptionKey`<sup>Optional</sup> <a name="encryptionKey" id="@ashishpandeyone/cdk-lambda-web-function.WebFunctionOptions.property.encryptionKey"></a>
+
+```typescript
+public readonly encryptionKey: IKey;
+```
+
+- *Type:* aws-cdk-lib.aws_kms.IKey
+- *Default:* an AWS owned key
+
+A customer managed KMS key for the function's revisions: their code and environment variables.
+
+A `PER_REGION` or `MULTI_REGION` endpoint needs a **multi-Region key** with a replica in every region it serves
+from, and each replica's policy must allow Lambda to decrypt (see `encryptionKeyPolicyStatement()`). A key defined
+in this app gets that statement added to its own policy.
+
+Changing the key creates a new revision. Earlier revisions, including the ones kept as rollback targets, still
+need their key.
+[disable-awslint:prefer-ref-interface]
+
+---
+
 ##### `endpoint`<sup>Optional</sup> <a name="endpoint" id="@ashishpandeyone/cdk-lambda-web-function.WebFunctionOptions.property.endpoint"></a>
 
 ```typescript
@@ -3692,6 +3874,26 @@ Names starting with `AWS_` are reserved.
 
 ---
 
+##### `logEncryptionKey`<sup>Optional</sup> <a name="logEncryptionKey" id="@ashishpandeyone/cdk-lambda-web-function.WebFunctionOptions.property.logEncryptionKey"></a>
+
+```typescript
+public readonly logEncryptionKey: IKey;
+```
+
+- *Type:* aws-cdk-lib.aws_kms.IKey
+- *Default:* CloudWatch Logs' own encryption
+
+A customer managed KMS key for the function's log groups, in every region it serves from.
+
+CloudWatch Logs needs a key in each group's region: for regions other than the key's own, the construct uses the
+replica of a **multi-Region key** there (the same key ID). Each key's policy must allow CloudWatch Logs in its
+region (see `logEncryptionKeyPolicyStatement()`). A key defined in this app gets that statement for its own region.
+
+Removing the key decrypts nothing: the groups keep their existing events encrypted with it.
+[disable-awslint:prefer-ref-interface]
+
+---
+
 ##### `logRemovalPolicy`<sup>Optional</sup> <a name="logRemovalPolicy" id="@ashishpandeyone/cdk-lambda-web-function.WebFunctionOptions.property.logRemovalPolicy"></a>
 
 ```typescript
@@ -4372,8 +4574,10 @@ const webFunctionProps: WebFunctionProps = { ... }
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionProps.property.authType">authType</a></code> | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionAuthType">WebFunctionAuthType</a></code> | How callers of the endpoint are authenticated. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionProps.property.applicationLogLevelV2">applicationLogLevelV2</a></code> | <code>aws-cdk-lib.aws_lambda.ApplicationLogLevel</code> | The minimum level of application logs to keep. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionProps.property.description">description</a></code> | <code>string</code> | A description of the function's code and configuration. |
+| <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionProps.property.encryptionKey">encryptionKey</a></code> | <code>aws-cdk-lib.aws_kms.IKey</code> | A customer managed KMS key for the function's revisions: their code and environment variables. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionProps.property.endpoint">endpoint</a></code> | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionEndpointOptions">WebFunctionEndpointOptions</a></code> | The default endpoint (`fn.endpoint`): where it serves from, its name and limits. It serves the current revision; route it elsewhere with `fn.endpoint.routeTraffic()`. Add more endpoints with `addEndpoint`. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionProps.property.environment">environment</a></code> | <code>{[ key: string ]: string}</code> | Environment variables. |
+| <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionProps.property.logEncryptionKey">logEncryptionKey</a></code> | <code>aws-cdk-lib.aws_kms.IKey</code> | A customer managed KMS key for the function's log groups, in every region it serves from. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionProps.property.logRemovalPolicy">logRemovalPolicy</a></code> | <code>aws-cdk-lib.RemovalPolicy</code> | What happens to the log groups when the function is removed: RETAIN or DESTROY. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionProps.property.logRetention">logRetention</a></code> | <code>aws-cdk-lib.aws_logs.RetentionDays</code> | Retention for every log group of the function, in every region it serves from. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionProps.property.maxConcurrencyPerEnvironment">maxConcurrencyPerEnvironment</a></code> | <code>number</code> | How many requests one execution environment handles at the same time (1-128). |
@@ -4426,6 +4630,27 @@ A description of the function's code and configuration.
 
 ---
 
+##### `encryptionKey`<sup>Optional</sup> <a name="encryptionKey" id="@ashishpandeyone/cdk-lambda-web-function.WebFunctionProps.property.encryptionKey"></a>
+
+```typescript
+public readonly encryptionKey: IKey;
+```
+
+- *Type:* aws-cdk-lib.aws_kms.IKey
+- *Default:* an AWS owned key
+
+A customer managed KMS key for the function's revisions: their code and environment variables.
+
+A `PER_REGION` or `MULTI_REGION` endpoint needs a **multi-Region key** with a replica in every region it serves
+from, and each replica's policy must allow Lambda to decrypt (see `encryptionKeyPolicyStatement()`). A key defined
+in this app gets that statement added to its own policy.
+
+Changing the key creates a new revision. Earlier revisions, including the ones kept as rollback targets, still
+need their key.
+[disable-awslint:prefer-ref-interface]
+
+---
+
 ##### `endpoint`<sup>Optional</sup> <a name="endpoint" id="@ashishpandeyone/cdk-lambda-web-function.WebFunctionProps.property.endpoint"></a>
 
 ```typescript
@@ -4454,6 +4679,26 @@ Names starting with `AWS_` are reserved.
 
 ---
 
+##### `logEncryptionKey`<sup>Optional</sup> <a name="logEncryptionKey" id="@ashishpandeyone/cdk-lambda-web-function.WebFunctionProps.property.logEncryptionKey"></a>
+
+```typescript
+public readonly logEncryptionKey: IKey;
+```
+
+- *Type:* aws-cdk-lib.aws_kms.IKey
+- *Default:* CloudWatch Logs' own encryption
+
+A customer managed KMS key for the function's log groups, in every region it serves from.
+
+CloudWatch Logs needs a key in each group's region: for regions other than the key's own, the construct uses the
+replica of a **multi-Region key** there (the same key ID). Each key's policy must allow CloudWatch Logs in its
+region (see `logEncryptionKeyPolicyStatement()`). A key defined in this app gets that statement for its own region.
+
+Removing the key decrypts nothing: the groups keep their existing events encrypted with it.
+[disable-awslint:prefer-ref-interface]
+
+---
+
 ##### `logRemovalPolicy`<sup>Optional</sup> <a name="logRemovalPolicy" id="@ashishpandeyone/cdk-lambda-web-function.WebFunctionProps.property.logRemovalPolicy"></a>
 
 ```typescript

package/README.md

@@ -279,6 +279,70 @@ table.grantReadWriteData(api);           // the default role trusts lambda.amazo
 - **The default execution role can only write to the function's own log groups**: the home region's, and the `.local` copy in every region it serves from. That's the minimum AWS documents for Web Functions. It doesn't use `AWSLambdaBasicExecutionRole`, which can also create any log group. Pass `role` to use your own, and include those log permissions.
 - **Renaming the function replaces it and changes its URL.** A generated name depends on the construct path, so moving the construct renames it too.
 
+### Encryption
+
+Lambda encrypts each revision's code and environment variables with an AWS owned key. To use your own key, pass `encryptionKey`:
+
+```ts
+declare const keyStack: Stack;     // deploys first
+declare const replicaStack: Stack; // in us-east-1, deploys before this stack
+
+const key = new kms.Key(keyStack, 'Key', { multiRegion: true });
+const api = new WebFunction(this, 'Api', {
+  runtime: lambda.Runtime.NODEJS_24_X,
+  code: lambda.Code.fromAsset('build'),
+  authType: WebFunctionAuthType.AWS_IAM,
+  endpoint: { endpointType: WebFunctionEndpointType.PER_REGION, regions: ['us-east-1'] },
+  encryptionKey: key,
+});
+
+// One replica per region the endpoint serves from, with Lambda's statement in its own policy.
+new kms.CfnReplicaKey(replicaStack, 'KeyReplica', {
+  primaryKeyArn: key.keyArn,
+  keyPolicy: new iam.PolicyDocument({
+    statements: [
+      new iam.PolicyStatement({ principals: [new iam.AccountRootPrincipal()], actions: ['kms:*'], resources: ['*'] }),
+      api.encryptionKeyPolicyStatement(),
+    ],
+  }),
+});
+```
+
+- **A key defined in your app gets Lambda's statement automatically.** It allows `kms:Decrypt` for `lambda.amazonaws.com`, limited to this function's revisions through `aws:SourceArn` and the encryption context Lambda sets. For an imported key, add `encryptionKeyPolicyStatement()` to its policy yourself.
+- **`PER_REGION` and `MULTI_REGION` endpoints need a multi-Region key**, with a replica in every region they serve from. The replicas must exist before the endpoint, so put the key and its replicas in stacks that deploy before the function's. Replica policies aren't copied from the primary, so each one needs `encryptionKeyPolicyStatement()`. With a single-Region key, the endpoint fails to activate in its other regions and the whole deployment rolls back. The construct fails synthesis instead, when it can tell: a key in your app without `multiRegion`, or an imported key whose ID doesn't start with `mrk-`.
+- **CloudFormation's role creates the revisions**, so it needs `kms:DescribeKey`, `kms:GenerateDataKey` and `kms:Decrypt` on the key. A key's default policy delegates to IAM, and CDK's default deployment role is allowed.
+- **Changing the key creates a new revision.** Earlier revisions keep their key, including the ones kept as rollback targets (`revisionRetention`). Keep the old key enabled while any of them might serve traffic again.
+- **Disabling the key, or removing Lambda's access, stops new execution environments from starting.** Running ones keep their decrypted copy for a while, so this doesn't contain traffic immediately.
+
+Log groups are encrypted by CloudWatch Logs. To use your own key for them too, pass `logEncryptionKey`. It can be the same key:
+
+```ts
+declare const key: kms.Key;              // multiRegion: true, in the function's region
+declare const replica: kms.CfnReplicaKey; // in us-east-1
+
+const api = new WebFunction(this, 'Api', {
+  runtime: lambda.Runtime.NODEJS_24_X,
+  code: lambda.Code.fromAsset('build'),
+  authType: WebFunctionAuthType.AWS_IAM,
+  endpoint: { endpointType: WebFunctionEndpointType.PER_REGION, regions: ['us-east-1'] },
+  logEncryptionKey: key,
+});
+
+// The replica's policy also allows CloudWatch Logs in its region, for this function's groups.
+replica.keyPolicy = new iam.PolicyDocument({
+  statements: [
+    new iam.PolicyStatement({ principals: [new iam.AccountRootPrincipal()], actions: ['kms:*'], resources: ['*'] }),
+    api.logEncryptionKeyPolicyStatement('us-east-1'),
+  ],
+});
+```
+
+- **CloudWatch Logs only uses a key in the group's own region.** The groups in the key's region use the key. Groups in other regions use the multi-Region key's replica there, which has the same key ID. With a single-Region key, synthesis fails as soon as a group is in another region.
+- **A key defined in your app gets CloudWatch Logs' statement for its own region.** It allows `logs.<region>.amazonaws.com` to use the key for this function's log groups only. Add `logEncryptionKeyPolicyStatement(region)` to each replica's policy, and to an imported key's.
+- **The construct's provider sets the key on each group, and needs `kms:DescribeKey` on it to do so.** The construct grants that through IAM, which a key's default policy allows. If a key's policy doesn't delegate to IAM, allow the provider's role in the key policy.
+- **Adding or changing the key encrypts new events only.** Existing events stay encrypted with the key they were written with. Removing `logEncryptionKey` sets the groups back to CloudWatch Logs' encryption.
+- **Retained log groups need their key to stay readable.** The default `logRemovalPolicy` is `RETAIN`, so keep the key while you keep the logs.
+
 ### Defaults for every function (property injection)
 
 To give every function under a scope the same defaults, register a property injector for `WebFunction.PROPERTY_INJECTION_ID`, as you would for aws-cdk-lib's constructs. For example, a team's log retention: