@ashishpandeyone/cdk-lambda-web-function 0.1.7 → 0.1.9

package/API.md

@@ -145,9 +145,9 @@ public addToResourcePolicy(statement: PolicyStatement): AddToResourcePolicyResul
 
 Adds a statement to the function's resource policy, e.g. to let another account manage the function. For invoking, prefer `addPermission` or `grantInvoke`.
 
-The function has one resource policy (`AWS::Lambda::ResourcePolicy`), created on the first statement. This stack
-is its only writer: another stack or template can't also attach one, and changes made outside CloudFormation
-are overwritten by the next update of the policy.
+The function has a single resource policy. Each stack writes only its own statements into it, through a custom
+resource that merges them with every other stack's, and with statements added outside CloudFormation. From a
+stack in another account than the function, nothing is added.
 
 ###### `statement`<sup>Required</sup> <a name="statement" id="@ashishpandeyone/cdk-lambda-web-function.NodejsWebFunction.addToResourcePolicy.parameter.statement"></a>
 
@@ -851,9 +851,9 @@ public addToResourcePolicy(statement: PolicyStatement): AddToResourcePolicyResul
 
 Adds a statement to the function's resource policy, e.g. to let another account manage the function. For invoking, prefer `addPermission` or `grantInvoke`.
 
-The function has one resource policy (`AWS::Lambda::ResourcePolicy`), created on the first statement. This stack
-is its only writer: another stack or template can't also attach one, and changes made outside CloudFormation
-are overwritten by the next update of the policy.
+The function has a single resource policy. Each stack writes only its own statements into it, through a custom
+resource that merges them with every other stack's, and with statements added outside CloudFormation. From a
+stack in another account than the function, nothing is added.
 
 ###### `statement`<sup>Required</sup> <a name="statement" id="@ashishpandeyone/cdk-lambda-web-function.WebFunction.addToResourcePolicy.parameter.statement"></a>
 
@@ -1457,7 +1457,7 @@ new WebFunctionBase(scope: Construct, id: string, props?: ResourceProps)
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionBase.with">with</a></code> | Applies one or more mixins to this construct. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionBase.applyCrossStackReferenceStrength">applyCrossStackReferenceStrength</a></code> | Override the cross-stack reference strength for this resource. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionBase.applyRemovalPolicy">applyRemovalPolicy</a></code> | Apply the given removal policy to this resource. |
-| <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionBase.addToResourcePolicy">addToResourcePolicy</a></code> | Adds a statement to the function's resource policy (not added for an imported function). |
+| <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionBase.addToResourcePolicy">addToResourcePolicy</a></code> | Adds a statement to the function's resource policy, e.g. to let another account manage the function. For invoking, prefer `addPermission` or `grantInvoke`. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionBase.grantInvoke">grantInvoke</a></code> | Allows `grantee` to call the function's endpoint. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionBase.metric">metric</a></code> | A metric of this function's execution environments in `AWS/Lambda/Web` (dimension `FunctionName`), across all endpoints. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionBase.metricActiveTime">metricActiveTime</a></code> | Time the execution environments were active (`EnvironmentActiveTime`). |
@@ -1545,7 +1545,11 @@ account for data recovery and cleanup later (`RemovalPolicy.RETAIN`).
 public addToResourcePolicy(statement: PolicyStatement): AddToResourcePolicyResult
 ```
 
-Adds a statement to the function's resource policy (not added for an imported function).
+Adds a statement to the function's resource policy, e.g. to let another account manage the function. For invoking, prefer `addPermission` or `grantInvoke`.
+
+The function has a single resource policy. Each stack writes only its own statements into it, through a custom
+resource that merges them with every other stack's, and with statements added outside CloudFormation. From a
+stack in another account than the function, nothing is added.
 
 ###### `statement`<sup>Required</sup> <a name="statement" id="@ashishpandeyone/cdk-lambda-web-function.WebFunctionBase.addToResourcePolicy.parameter.statement"></a>
 
@@ -3214,7 +3218,7 @@ const webFunctionAttributes: WebFunctionAttributes = { ... }
 | **Name** | **Type** | **Description** |
 | --- | --- | --- |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionAttributes.property.endpointName">endpointName</a></code> | <code>string</code> | The endpoint `grantInvoke` allows calling. |
-| <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionAttributes.property.webFunctionArn">webFunctionArn</a></code> | <code>string</code> | The function's ARN, e.g. `arn:aws:lambda:us-east-1:111122223333:web-function/orders`. It may be in another region or account; across accounts, `grantInvoke` also needs the function's resource policy to allow the caller. |
+| <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionAttributes.property.webFunctionArn">webFunctionArn</a></code> | <code>string</code> | The function's ARN, e.g. `arn:aws:lambda:us-east-1:111122223333:web-function/orders`. It may be in another region or account; across accounts, `grantInvoke` also needs the function's resource policy to allow the caller. A token (e.g. from another stack) is taken to be in this stack's account and region. |
 | <code><a href="#@ashishpandeyone/cdk-lambda-web-function.WebFunctionAttributes.property.webFunctionName">webFunctionName</a></code> | <code>string</code> | The function's name. |
 
 ---
@@ -3241,7 +3245,7 @@ public readonly webFunctionArn: string;
 - *Type:* string
 - *Default:* built from `webFunctionName`, in this stack's account and region
 
-The function's ARN, e.g. `arn:aws:lambda:us-east-1:111122223333:web-function/orders`. It may be in another region or account; across accounts, `grantInvoke` also needs the function's resource policy to allow the caller.
+The function's ARN, e.g. `arn:aws:lambda:us-east-1:111122223333:web-function/orders`. It may be in another region or account; across accounts, `grantInvoke` also needs the function's resource policy to allow the caller. A token (e.g. from another stack) is taken to be in this stack's account and region.
 
 ---
 
@@ -4846,7 +4850,7 @@ The grant is on the endpoint's home-region ARN, which IAM evaluates for every re
 endpoint serves from, including a MULTI_REGION global URL.
 
 A grantee in the function's account gets an IAM policy statement. Another account or an AWS service also gets
-a statement in the function's resource policy (not for an imported function's endpoints).
+a statement in the function's resource policy.
 
 ###### `grantee`<sup>Required</sup> <a name="grantee" id="@ashishpandeyone/cdk-lambda-web-function.WebFunctionGrants.invoke.parameter.grantee"></a>
 
@@ -4939,7 +4943,7 @@ WebFunctionOrigin.withOriginAccessControl(endpoint: WebFunctionEndpoint, props?:
 
 An origin for an `AWS_IAM` endpoint, with origin access control: CloudFront signs every request to the endpoint (`always-amz-auth`, which keeps the viewer's `Authorization` header for your application), and the function's resource policy allows `cloudfront.amazonaws.com` to call this endpoint on behalf of this distribution only.
 
-The distribution must be in the function's stack.
+The distribution can be in another stack than the function, in the same account.
 
 ###### `endpoint`<sup>Required</sup> <a name="endpoint" id="@ashishpandeyone/cdk-lambda-web-function.WebFunctionOrigin.withOriginAccessControl.parameter.endpoint"></a>
 
@@ -4965,9 +4969,9 @@ The distribution must be in the function's stack.
 
 A Lambda Web Function, created in this app (`WebFunction`) or imported (`WebFunction.fromWebFunctionArn`).
 
-`addToResourcePolicy` adds to the function's resource policy (who else may call or manage it). A `WebFunction` has
-one, created by its stack on the first statement. An imported function's policy belongs to the stack that created
-it, so the statement isn't added (`statementAdded: false`).
+`addToResourcePolicy` adds to the function's resource policy (who else may call or manage it). Each stack writes
+only its own statements into the function's single policy, so any stack in the function's account can add them,
+including one that imports the function. From another account, nothing is added (`statementAdded: false`).
 
 #### Methods <a name="Methods" id="Methods"></a>
 
@@ -4993,9 +4997,8 @@ Allows `grantee` to call the function's endpoint (`lambda:InvokeWebFunctionEndpo
 
 for an imported function, the endpoint named in its attributes, or every endpoint.
 
-For a `WebFunction`, a grantee in this account gets an IAM policy statement; another account or an AWS service
-also gets a statement in the function's resource policy. For an imported function, only the grantee's IAM policy
-changes: across accounts, the function's own resource policy must also allow the grantee.
+A grantee in the function's account gets an IAM policy statement; another account or an AWS service also gets a
+statement in the function's resource policy (not when the function itself is in another account than this stack).
 [disable-awslint:no-grants]
 
 ###### `grantee`<sup>Required</sup> <a name="grantee" id="@ashishpandeyone/cdk-lambda-web-function.IWebFunction.grantInvoke.parameter.grantee"></a>

package/README.md

@@ -186,7 +186,9 @@ fn.addPermission('Cdn', {
 
 `addPermission` allows calling every endpoint unless you pass `endpoint`. For other actions, such as letting another account create revisions, use `fn.addToResourcePolicy(statement)`. Statements use the endpoint ARN for invoking and the function ARN for actions on the function.
 
-- **One resource policy per function, written by the function's stack.** The construct creates it (`AWS::Lambda::ResourcePolicy`) with the first statement. CloudFormation can't attach a second one: another stack, or a `CfnResourcePolicy` of your own on the function, fails at change-set validation with "already exists". If you attached one yourself, move its statements into `addPermission` or `addToResourcePolicy`. Each update of the policy replaces any statements added outside CloudFormation.
+- **Each stack writes only its own statements.** A Web Function has a single resource policy, and Web Functions have no `AddPermission`. So each stack that adds statements gets a custom resource (`Custom::LambdaWebResourcePolicyStatements`). It reads the policy, replaces the statements that stack wrote before, and writes the policy back, retrying if another writer changed it in the meantime. Statements from other stacks, and ones added outside CloudFormation, are kept. Writers include the function's stack, a stack with a CloudFront distribution, and a stack that imports the function in the same account.
+- **Sids are unique in the policy.** `addPermission`'s `id` becomes the statement's `Sid`, and other statements get a generated one (`Cdk<hash><n>`). If another stack or tool already uses that `Sid` for different content, the deployment fails with the `Sid`.
+- **Don't also attach an `AWS::Lambda::ResourcePolicy` yourself.** That resource replaces the whole document on every update, dropping every other writer's statements.
 - **Public policies are rejected.** Lambda refuses a policy that lets anyone call the function, and the construct fails synthesis first. A `*` principal is only accepted with a condition that pins the caller, such as `aws:PrincipalOrgID` (`iam.OrganizationPrincipal`) or `aws:SourceAccount`. For a public endpoint, use `authType: NONE`.
 - **Scope AWS services to your resource.** Lambda accepts a service principal with no condition, which would let that service call the endpoint on behalf of any account. The construct warns unless you give `sourceArn` or `sourceAccount` (or an `aws:SourceArn`, `aws:SourceAccount`, `aws:SourceOrgID` or `aws:SourceOrgPaths` condition).
 - Lambda copies the policy to every region the function's endpoints serve from. The copy is eventually consistent, and in tests changes applied in every region within seconds.
@@ -226,7 +228,10 @@ Some things to know:
 - Request bodies work without clients sending `x-amz-content-sha256`: CloudFront signs `POST`, `PUT` and `PATCH` requests with an unsigned payload.
 - A `PER_REGION` endpoint's origin calls one region: the home region, or the one you pass as `region`. Use one origin per region, for example in an origin group.
 - A `MULTI_REGION` endpoint can't include opt-in regions (such as `me-central-1`), because CloudFront can't sign for them. The construct fails synthesis.
-- The distribution must be in the function's stack. Lambda@Edge origin-request and origin-response triggers aren't supported on behaviors with this origin.
+- The distribution can be in another stack, in the function's account. Its stack writes the CloudFront statement into the function's resource policy, so the function's stack doesn't depend on it.
+- That stack can also be in another region, for example us-east-1 for an ACM certificate. CDK then passes the endpoint's domain and ARN with its cross-region references: SSM parameters plus custom resources of its own.
+- **Those references are strong by default.** A change that replaces the endpoint gives it a new domain and ARN. That includes a new endpoint type or region set, or a renamed function. The function's stack can't update a value while the distribution's stack still uses the old one, the same as with `Fn::ImportValue` in one region. Deploy such a change in two steps, or use weak references: CDK's synth warning `@aws-cdk/core:crossStackReferencesDefaultStrong` explains how.
+- Lambda@Edge origin-request and origin-response triggers aren't supported on behaviors with this origin.
 - The endpoint stays reachable at its own domain for signed requests your policies allow. Until a new distribution finishes deploying, requests through it can get a transient 403.
 - `new WebFunctionOrigin(endpoint)` is for a public (`NONE`) endpoint, for example behind AWS WAF. Lambda doesn't authenticate those requests, so the endpoint's own domain stays public too.
 
@@ -247,7 +252,7 @@ live.metricConcurrentRequests().createAlarm(this, 'Busy', { threshold: 60, evalu
 
 An imported function's metrics default to its own region. Its endpoints, revisions and log groups stay with the stack that defines it.
 
-An imported function's `grantInvoke` adds to the caller's IAM policy only, which is all a caller in the function's account needs. A caller in another account also needs the function's resource policy to allow it, which only the function's own stack can change: `addToResourcePolicy` on an imported function adds nothing and warns.
+An imported function works like a `WebFunction` here. `grantInvoke` and `addToResourcePolicy` write the importing stack's statements into the function's resource policy, in the function's region. This works only when the function is in the stack's account. For a function in another account, `grantInvoke` adds to the caller's IAM policy only, and `addToResourcePolicy` adds nothing and warns, so ask that account to allow the caller.
 
 ## Configuration
 
@@ -271,6 +276,7 @@ table.grantReadWriteData(api);           // the default role trusts lambda.amazo
 - **Each execution environment has 2 vCPUs and 2 GB of memory.** There's no memory setting as on Lambda functions; scale with `maxConcurrencyPerEnvironment` and more environments instead.
 - Requests handled by one environment share module-level state, so keep handlers concurrency-safe.
 - Environment variable names starting with `AWS_` are reserved.
+- **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.
 
 ### Bundling TypeScript with `NodejsWebFunction`
@@ -458,6 +464,35 @@ new WebFunction(this, 'Api', {
 - With `DESTROY`, deletion waits about a minute after the function is gone, because environments flush their last lines late.
 - Subscribe only to `fn.logGroup`: subscribing to the `.local` groups as well delivers every event twice.
 
+## cdk-nag
+
+The library acknowledges the [cdk-nag](https://github.com/cdklabs/cdk-nag) AwsSolutions findings on the resources it creates, each with a reason, so they don't show up in your reports:
+
+| Finding | Resource | Reason |
+|---|---|---|
+| IAM5 (wildcards) | the default execution role | log streams of the function's own log groups, in every region it serves from |
+| IAM5 | the deployment handlers' role (canary and linear deployments) | their own log group, `cloudwatch:DescribeAlarms` (composite alarms need `*`), and the revisions and endpoints of the functions they deploy |
+| IAM4, IAM5, SF1, SF2 | the CDK Provider framework behind deployments | CDK's own functions and waiter state machine |
+| S1 (access logs) | the stack's code bucket | it only holds copies of the stack's code assets |
+
+- **This works with both cdk-nag versions**, without depending on cdk-nag. cdk-nag 3 reads CDK's `Validations.of(...).acknowledge()`, one ID per finding. cdk-nag 2 reads `cdk_nag` metadata in the template.
+- **Your own statements and resources are still checked.** That includes statements you add to the function's role (`addToRolePolicy`, grants) and your CloudFront distribution's settings.
+- Only the AwsSolutions pack is covered; findings from the HIPAA, NIST and PCI packs aren't acknowledged.
+
+## Upgrading
+
+### From 0.1.5 to 0.1.7, with a resource policy
+
+Versions 0.1.5 to 0.1.7 wrote the function's resource policy with an `AWS::Lambda::ResourcePolicy`. Later versions don't (0.1.7 has the same code as 0.1.6). When an update removes that resource, CloudFormation deletes the function's **whole** resource policy at the end of the update, including the statements the new version just wrote. Callers that rely on the policy then get 403: other accounts, AWS services, and CloudFront.
+
+If your function has a resource policy (from `addPermission`, a grant to another account or an AWS service, or `WebFunctionOrigin`), first deploy once on the version you have, with the old resource retained:
+
+```ts
+(fn.node.findChild('ResourcePolicy') as CfnResource).applyRemovalPolicy(RemovalPolicy.RETAIN);
+```
+
+Then upgrade, without changing your statements in the same deployment. The new version takes over the statements it writes itself. A statement you removed in the same deployment would stay in the policy.
+
 ## Limitations
 
 - Not yet supported: VPC access (network connectors), KMS encryption, and tracing.