[licjun]

Issue # (if applicable)

N/A

Reason for this change

Lambda WebFunction launched on 2026-10-12. Today it can only be defined through its
three L1 resources — AWS::Lambda::WebFunction, AWS::Lambda::WebFunctionRevision
and AWS::Lambda::WebFunctionEndpoint — which the caller has to wire together
themselves, including the dependency order between them and the FunctionName
each of them repeats.

Code is the harder part. A WebFunction reads its code from S3 at every sandbox
start, using the Lambda service principal through a bucket resource policy, not
the caller's credentials. The bucket therefore has to have versioning enabled (a
revision pins one object version for its lifetime), SSE-S3 encryption (the
AWS-managed KMS key cannot grant the service principal) and that read policy. The
CDK bootstrap bucket satisfies none of these, so lambda.Code.fromAsset cannot be
used and local code needs a staging step.

VPC egress works differently from lambda.Function: a WebFunction does not take
subnets and security groups, it references an AWS::Lambda::NetworkConnector that
owns the network interfaces, so they are provisioned once with the connector rather
than per function.

Description of changes

WebFunction creates the function, one revision and one endpoint, and sets the
dependencies and shared FunctionName between them. It exposes domainName,
endpointArn, revisionArn and revisionId, implements IGrantable, offers
grants.invoke(), and creates an execution role if none is given. authType is
required with no default, so making an endpoint public is always explicit.

WebFunctionCode has three factories:

• fromBucket — code already in a compliant bucket; the bucket is validated, not
  modified.
• fromAssetToManagedBucket — a local asset staged into a per-stack bucket CDK
  creates with versioning, SSE-S3 and the service-principal read policy.
• fromAssetToProvidedBucket — a local asset staged into the caller's bucket, which
  is validated for versioning and encryption.

Staging uses a new internal custom resource that copies one object server-side with
CopyObject and returns the VersionId it wrote, which the revision pins. This is
why it is not BucketDeployment: that resource does not report the written version,
so getting one would need a second custom resource calling headObject, which
returns whichever version is current when it runs rather than the one just written.
An update writes a new object version and leaves the old one in place; the old version
is deleted only when the copy it belongs to is removed, in the cleanup phase, and kept
if the revision reading it is retained. Because the copy is server-side, the object's
bytes never pass through Lambda — no AWS CLI layer, no /tmp ceiling.

NetworkConnector wraps AWS::Lambda::NetworkConnector. Its configuration is
chosen through NetworkConnectorConfiguration.vpcEgress({...}), which takes a vpc
plus an optional vpcSubnets selection and the security groups. By default the
construct creates the operator role the service assumes to manage the interfaces and
attaches the AWSLambdaNetworkConnectorOperatorPolicy managed policy; a role defined
in the same app gets that policy attached too, and an imported one gets a warning
since it cannot be modified.

Every update to a connector produces a new immutable version, so
WebFunctionProps.egressNetworkConnector pins the revision to the connector's
latestVersionArn. A connector in the same stack is therefore replaced-and-moved
as one deployment; a connector in another stack is rejected at synthesis, because
that ARN changes on every update and CloudFormation will not let an Export change
while another stack imports it. NetworkConnector.fromNetworkConnectorVersionArn
is the way to pin a fixed version, including across stacks.

Describe any new or updated permissions being added

• The code bucket grants s3:GetObject and s3:GetObjectVersion to
  lambda.amazonaws.com, conditioned on aws:SourceAccount and aws:SourceArn. For
  fromBucket and a provided bucket, it is scoped to the function's code and its
  revisions; for the managed bucket, one statement covers web-function/* and any
  WebFunction revision in the account.
• A caller-supplied KMS key is granted to the same service principal under the same
  conditions, so the service can decrypt the code and environment variables.
• The copy custom resource's role gets s3:GetObject and s3:GetObjectVersion on the
  source bucket's objects, and put and delete on the destination key pattern.
• A WebFunction's default execution role gets AWSLambdaBasicExecutionRole.
• grants.invoke() grants lambda:InvokeWebFunctionEndpoint on the endpoint ARN.
• A NetworkConnector's default operator role is created with
  AWSLambdaNetworkConnectorOperatorPolicy and trusts lambda.amazonaws.com.

Description of how you validated changes

Unit tests for both constructs, the code factories and the copy custom resource,
including its handler.

Five integ tests, each with a snapshot generated by a real deployment in
us-west-2: a minimal WebFunction, one setting every supported prop, one staging a
local asset into the managed bucket, a standalone NetworkConnector, and a
WebFunction with egress through a connector. The WebFunction tests assert against
the deployed endpoint. Under IAM_AUTH an unsigned request gets 403, which
confirms the endpoint is live and enforcing auth. The connector test uses an
APPLICATION_MANAGED endpoint and expects 200 with an object the handler can only
read through the VPC's S3 gateway endpoint, so it also shows the handler runs and its
egress goes through the connector.

Both constructs were also exercised by hand in a bug bash with several engineers,
and the findings from it are fixed in this change.

Checklist

• My code adheres to the CONTRIBUTING GUIDE and DESIGN GUIDELINES

---

awslint exclusion

props-physical-name:aws-cdk-lib.aws_lambda.WebFunctionEndpointProps is excluded on
purpose: the endpoint's physical name is endpointName, the service's term
(AWS::Lambda::WebFunctionEndpoint.EndpointName), rather than webFunctionEndpointName.

Not in this PR: weighted traffic

WebFunctionTraffic has only single(). A WebFunction keeps one revision, so there is no
second revision to split traffic with; weights need addressable, retained revisions, which
can be added later together with a WebFunctionTraffic.weighted() factory without changing
single() or the traffic prop. Until then, use endpoint.resource to set RevisionWeights.

Integ snapshot changes

integ.webfunction-network-connector and integ.webfunction-staged-asset give their
Custom::S3ObjectCopy resources new logical ids: a copy's id now depends only on the copy
function, and its key is computed by the handler from the content and the revision's
configuration. Both were regenerated by a deployment.

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

[github-actions]

👋 It looks like your PR description follows the template but is missing a valid issue number in the first section.

PRs without a linked issue will receive lower priority for review and merging. Please update the description to include a reference like Closes #123. If no existing issue matches your change, create one first.

[github-actions]

⚠️ Experimental Feature: This security report is currently in experimental phase. Results may include false positives and the rules are being actively refined.
This security report is NOT a review blocker. Please try merge from main to avoid findings unrelated to the PR.
To suppress a specific rule, see Suppressing Rules.

---

	Tests	Passed ✅	Skipped ⚠️	Failed
Security Guardian Results	276 ran	271 passed	5 skipped

Test	Result
No test annotations available

• View Security Guardian Results

[github-actions]

⚠️ Experimental Feature: This security report is currently in experimental phase. Results may include false positives and the rules are being actively refined.
This security report is NOT a review blocker. Please try merge from main to avoid findings unrelated to the PR.
To suppress a specific rule, see Suppressing Rules.

---

	Tests	Passed ✅	Skipped ⚠️	Failed
Security Guardian Results with resolved templates	276 ran	271 passed	5 skipped

Test	Result
No test annotations available

• View Security Guardian Results with resolved templates

[maintainer-for-aws]

Automated review

A maintainer will still review this — treat the notes below as a starting point.

📌 Commit 51ce842

This PR adds net-new L2 constructs for AWS Lambda's WebFunction family — WebFunction, WebFunctionEndpoint, NetworkConnector, and supporting WebFunctionCode/WebFunctionRuntime/WebFunctionTraffic value types plus an internal Custom::S3ObjectCopy resource — to aws-cdk-lib. It collapses the three WebFunction L1 resources and the network connector into ergonomic constructs and solves S3 code staging and VPC egress. The modified files (index.ts, custom-resources config.ts, the READMEs, and awslint.json) are purely additive, so nothing changes for existing stacks.

The change is in good shape overall: the abstraction and layering are sound, token handling is carefully guarded throughout, the public surface is JSII-clean, IAM grants and resource policies are scoped and secure-by-default (public exposure is always explicit via a required auth choice), and test coverage — unit tests plus five integration tests with real deploy-time assertions — is thorough. No blocking issues were found. The findings are design-polish and documentation items: a missing CloudWatch metric* affordance on the new L2s, a few interface/convention gaps (the endpoint's missing static type guard, IWebFunction not extending the shared resource-policy interface), prop-shape observations where mutually-constrained flat props could be modeled polymorphically, an inaccurate @default on endpointName for the addEndpoint() path, and an undocumented awslint suppression. Each can be addressed additively without a breaking change.

🔴 0 blocking · 🟡 7 recommended · ⚪ 3 optional

Files with findings (5)

File	Findings
packages/aws-cdk-lib/aws-lambda/lib/network-connector.ts	🟡 1
packages/aws-cdk-lib/aws-lambda/lib/webfunction-endpoint.ts	🟡 3 ⚪ 1
packages/aws-cdk-lib/aws-lambda/lib/webfunction.ts	🟡 2 ⚪ 1
packages/aws-cdk-lib/awslint.json	🟡 1
packages/aws-cdk-lib/aws-lambda/lib/webfunction-runtime.ts	⚪ 1

---

Generated automatically. React 👍 or 👎 to tell us whether this review helped, so we can improve these reviews.

[maintainer-for-aws]

See the review summary comment for the overview; the notes below are inline.

[maintainer-for-aws]

See the review summary comment for the overview; the notes below are inline.

[piotrekwitkowski]

These groups expand into the endpoint's Regions, which is create-only, and into the default prod-<hash> name, so changing a group's contents or order replaces the endpoint and changes its domainName. That leaves two options once Lambda launches in more Regions. Updating a group gives every app that uses it a new endpoint URL on a routine aws-cdk-lib upgrade. Freezing the groups keeps ALL_DEFAULT_REGIONS in stable API under a name that is no longer true, along with SPARSE_GLOBAL and MAJOR_REGIONS as fixed picks.

Could they leave this PR instead? Without groups, WebFunctionReplicaRegions and its excluded list aren't needed either, so multiRegion() and perRegion() could take the Regions directly:

WebFunctionEndpointLocation.multiRegion(['us-east-1', 'eu-west-1']);

Groups can be added later without a breaking change. Removing them after release would be one.

[licjun]

Agreed, removed in 00ac84a. WebFunctionRegions and WebFunctionReplicaRegions are gone, and multiRegion() / perRegion() take the Regions directly. Groups can come back later as an addition if there's a way to make them stable.

[piotrekwitkowski]

This retains the bucket and the auto-delete resource but not bucket.policy, which holds the only lambda.amazonaws.com read grant. After stack deletion with a retained revision, the bucket and object survive and the policy is deleted, so the revision fails at its next sandbox start, which is the case this is meant to cover. Adding bucket.policy?.node.defaultChild to the list, and asserting AWS::S3::BucketPolicy in the retention tests, would close it. A provided bucket has the same gap, because its CDK-created policy defaults to Delete.

[licjun]

Thanks, fixed in 6f5bb8b. The managed bucket's policy is now retained with the bucket, and a provided bucket's policy is retained while any revision using it is; otherwise both keep their own removal policy. The retention tests now check AWS::S3::BucketPolicy for both.

[piotrekwitkowski]

Only an empty list is rejected. CloudFormation requires at least one Region other than the home Region (Regions: "You can't specify only the home Region"), so multiRegion(WebFunctionReplicaRegions.of(['us-east-1'])) in a us-east-1 stack passes synth and fails at deploy.

The default name also hashes the raw list (private/webfunction-util.ts:16), so reordering it, or adding or removing the home Region, renames and replaces an endpoint that is otherwise the same. Could the home Region be dropped and the list sorted before hashing and rendering, with an error when nothing is left? Changing the hash inputs after release would rename every default regional endpoint.

[licjun]

Fixed in 00ac84a. The list is now treated as a set: duplicates and the stack's own Region are dropped and the rest sorted before both rendering and the default name, and a list with no other Region fails at synthesis. In an environment-agnostic stack the Region isn't known, so only the dedupe and sort apply there.

[piotrekwitkowski]

Nit: this comment is out of date now that the vendored schema is gone and integ.webfunction-network-connector.ts deploys a WEB_FUNCTION connector. Keeping MICRO_VM here still makes sense, since it's the only deploy of that compute type, but the comment could give that as the reason instead. An awsApiCall on the connector's state would also make the test assert something beyond a successful deploy.

[licjun]

Updated the comment in 81e8a92. On the state check: awsApiCall needs the command in the AWS SDK, and the latest public @aws-sdk/client-lambda (3.1159.0) has no NetworkConnector commands yet, so it would fail at deploy. I'll add it once the SDK has GetNetworkConnector. The WEB_FUNCTION connector is exercised end to end in integ.webfunction-network-connector, where the handler reaches an S3 object through it.

[piotrekwitkowski]

Seven inline comments below from another review pass, posted here so more people can weigh in.

One more that has no single line. No integ test deploys a resource policy, the IAM_AUTH success path, a MULTI_REGION or PER_REGION endpoint, or addEndpoint(). So the policy this PR renders, grants.invoke() with a non-identity principal, and the regional endpoint naming haven't been accepted by the service in a test. An integ with a helper Lambda that signs requests (SigV4 plus X-Amz-Content-SHA256), granted through endpoint.grants.invoke() and asserting a 200, plus one MULTI_REGION addEndpoint(), would cover most of it.

cc @matboros

[piotrekwitkowski]

Literals inside any intrinsic other than the four handled above pass through unchanged, also when that intrinsic is nested inside a handled one. So a {{resolve:...}} inside Fn::Base64, Fn::ToJsonString, Fn::Select over Fn::Split, a Fn::FindInMap default, or an Fn::Base64 value in an Fn::Sub variable map still reaches the copy and fails the deploy, for example environment: { AUTH: Fn.base64(admin:${secret.unsafeUnwrap()}) }.

An allowlist would close the whole class. Keep only Ref, Fn::GetAtt, Fn::ImportValue and Fn::Sub placeholders, keep the Fn::If skeleton around them so conditional references stay conditional, and hash everything else. A synth-time error if {{resolve: is left in the result would make it fail closed.

[licjun]

Fixed in 5d28935. The fingerprint is an allowlist now: Ref, Fn::GetAtt and Fn::ImportValue are kept, Fn::Join, Fn::Sub and Fn::If keep their shape with their literals hashed, and any other intrinsic is replaced by the hash of its value. The references inside it go into a separate References list, under their Fn::If when conditional, so they still change the key without being evaluated in place (a list-valued one inside a Fn::Join would break it). Synthesis fails if {{resolve: is left. Tests cover the Fn::Base64, Fn::Select over Fn::Split, nested and Fn::Sub variable cases.

[piotrekwitkowski]

retentionOf reads cfnOptions and revisionConfiguration (:664) reads the L1 getters, so escape-hatch overrides on the revision are invisible to both. fn.resourceRevision.addOverride('DeletionPolicy', 'Retain') (and UpdateReplacePolicy) leaves the copy at Delete, so the next code change deletes the object the retained revision pins. addPropertyOverride('ServiceConfig.TimeoutSeconds', 60) replaces the revision without moving the key, so the old and new revisions share one object version again.

Deriving both from the resolved _toCloudFormation() output, minus BuildConfig.CodeConfig, the way function-hash.ts does for lambda.Function, would pick up both.

[licjun]

Fixed in 5d28935: the copy's policies and its configuration are both read from the revision's rendered _toCloudFormation() output, minus BuildConfig.CodeConfig, so addOverride on the policies and addPropertyOverride on properties are seen. Tests for both.

[piotrekwitkowski]

Is this confirmed for PER_REGION? The CloudFormation reference only documents DomainName as "The domain name assigned to the endpoint", and the per-Region hostnames are in RegionalEndpoints. No integ test deploys a PER_REGION endpoint, so this contract would freeze unverified. If it can't be checked before merge, I'd drop the sentence here and at :426.

[licjun]

Yes, checked on a deployed endpoint: a PER_REGION endpoint in a us-west-2 stack returned the DomainName <id>.jcg.lambda-web.us-west-2.on.aws, the home Region's hostname, so I kept the sentence. The new integ.webfunction-endpoints (9c8aced) also deploys a PER_REGION endpoint and checks that its domainName answers (403 unsigned).

[piotrekwitkowski]

RETAIN_EXCEPT_ON_CREATE counts as retained here, so the copy, the managed bucket and the auto-delete resource get a plain Retain. If the first deployment fails, CloudFormation deletes the revision but keeps the bucket and its object, which is what RetainExceptOnCreate exists to avoid. Carrying the strongest policy across (Delete < RetainExceptOnCreate < Retain) instead of a boolean would keep it.

[licjun]

Fixed in 5d28935. The strongest policy is carried (Delete < RetainExceptOnCreate < Retain): a revision with RetainExceptOnCreate gives the copy, the managed bucket, its policy and the auto-delete resource a DeletionPolicy of RetainExceptOnCreate. UpdateReplacePolicy has no such value, so it is Retain wherever something is retained.

[piotrekwitkowski]

This client uses the copy function's Region. A provided bucket in another Region, which the Lambda docs allow for code, then fails CopyObject and DeleteObject with PermanentRedirect. new S3({ followRegionRedirects: true }) would cover it, and a test with a bucket from Bucket.fromBucketAttributes({ region }) would guard it.

[licjun]

Confirmed and fixed in 726be1d. I deployed a revision in us-west-2 whose code was in a us-east-1 bucket and the service accepted it, so the handler's client now sets followRegionRedirects: true, with a test on the client's config. A test with fromBucketAttributes({ region }) on the lib side wouldn't catch it, since the template is the same.

[piotrekwitkowski]

When does the role lose access here? As far as I can tell, a destination change gives a new copy function that keeps its old grants, and CloudFormation deletes the copy before its function and policy in cleanup. Swallowing AccessDenied turns a grant regression or an SCP deny into UPDATE_COMPLETE with a leaked object version. Could this keep only NoSuchBucket?

[licjun]

You're right: the destination is part of the copy function's identity, so a moved destination gets a new function and the old one deletes with its old grants. The comment predates that. Removed in 726be1d; only NoSuchBucket is tolerated, and AccessDenied now fails the Delete (tested).

[piotrekwitkowski]

The HOME_REGION-only rule for a function with an egressNetworkConnector is enforced in WebFunction and addEndpoint() (webfunction.ts:697) but not here. So new WebFunctionEndpoint(this, 'Ep', { webFunction: fnWithConnector, endpointLocation: WebFunctionEndpointLocation.multiRegion([...]), ... }) passes synth and the service rejects it at deploy. Running the same check here, plus a sentence in the README's network connector section, would cover it.

[licjun]

Fixed in f5018cd: the check now runs in WebFunctionEndpoint, so it covers the default endpoint, addEndpoint() and a standalone endpoint for a function defined in the app (an imported function's connector isn't known). The README's network connector section says so.

[piotrekwitkowski]

Three small doc items inline. The PR description has one more, and it becomes the squash commit message. It still says the copy "never prunes on update" and gets "list-versions on the destination key pattern". Since 5c3caf1f Delete removes the replaced version, and the copy role gets s3:GetObject and s3:GetObjectVersion on the source and put and delete on the destination (s3-object-copy.ts:171-177).

[piotrekwitkowski]

The singleton key includes the destination (s3-object-copy.ts:230, -dest-..., plus role, VPC, security groups and log group), and the staged-asset integ snapshot has two copy functions, ...dest438c... and ...destb0df.... So it's one copy function per destination bucket and copy options rather than one per stack.

[licjun]

Right, fixed in b6833ae: one copy function for each destination bucket and set of copyOptions, shared by the WebFunctions in the stack that use them.

[piotrekwitkowski]

A second AWS::Lambda::ResourcePolicy for the same function doesn't replace the first. When I deployed one, CloudFormation rejected it with "already exists", at change-set validation from another stack and as CREATE_FAILED in the same stack. A policy set outside CloudFormation blocks it the same way, which I hit on an existing stack. So moving from an escape-hatch CfnResourcePolicy or an out-of-band policy to grants.invoke() takes two deploys, one to remove the old policy and one to add the grants.

[licjun]

Thanks for testing it. Fixed in b6833ae: the README now says a second AWS::Lambda::ResourcePolicy, or a policy set outside CloudFormation, fails with "already exists", and that moving to grants.invoke() takes two deploys, one to remove the old policy and one to add the grants.

[piotrekwitkowski]

Small one. The default endpoint is homeRegion(), so spanning multiple Regions is opt-in, and the Lambda guide sends users to CloudFront for a custom domain or AWS WAF, which the CloudFront section further down also covers. Something like "each WebFunction gets its own HTTPS endpoint, in one Region by default or across several" would match the rest of the README.

[licjun]

Fixed in b6833ae: "Each WebFunction gets its own HTTPS endpoint, in one Region by default or across several."

[licjun]

Re the coverage gap in the last review: added integ.webfunction-endpoints in 9c8aced and deployed it. A helper Lambda whose only permission is the statement endpoint.grants.invoke() adds to the function's resource policy (granted to an ArnPrincipal, so nothing lands on its role) signs a GET with SigV4 and X-Amz-Content-SHA256 and gets a 200. A MULTI_REGION and a PER_REGION endpoint added with addEndpoint() are created and return 403 to an unsigned request. The MULTI_REGION endpoint isn't called signed, since SigV4a needs CRT in the helper; your CloudFront test covered that path. cc @matboros

[maintainer-for-aws]

See the review summary comment for the overview; the notes below are inline.

[maintainer-for-aws]

🟡 Recommended — WebFunction and NetworkConnector each define a static type guard (isWebFunction / isNetworkConnector, backed by a Symbol.for), but the public WebFunctionEndpoint construct class defines neither an isWebFunctionEndpoint guard nor the backing symbol. The guidance says every construct class should expose a static isFoo(x): x is Foo and steer consumers away from instanceof (AGENTS_CONSTRUCT_DESIGN.md#static-type-check). Without it, a consumer holding an IWebFunctionEndpoint that needs to narrow to the concrete class is pushed toward instanceof, and the endpoint is inconsistent with its two sibling constructs added in this same change.

Suggested change: Add the same Symbol.for('@aws-cdk/aws-lambda.WebFunctionEndpoint') marker plus public static isWebFunctionEndpoint(x: any): x is WebFunctionEndpoint pattern used by WebFunction.

[licjun]

Added in 51ce842: WebFunctionEndpoint.isWebFunctionEndpoint(), backed by Symbol.for('@aws-cdk/aws-lambda.WebFunctionEndpoint') like the other two. An imported endpoint is not one.

[maintainer-for-aws]

🟡 Recommended — This change adds props-physical-name:aws-cdk-lib.aws_lambda.WebFunctionEndpointProps to the awslint exclude list, suppressing the rule that enforces the {resource}Name physical-name convention. A suppression turns off a build-time guardrail for a design guideline, so it should carry a stated justification (CONTRIBUTING.md#awslint). The suppression itself looks defensible: the endpoint's physical-name prop is endpointName, matching the service term, which is the correct call under official-terminology naming rather than the awslint-expected webFunctionEndpointName — but nothing in the file or nearby records that reasoning for a future reader.

Suggested change: Record a short justification next to the entry (or in the PR description) noting that endpointName is the deliberate, service-aligned physical-name prop, so the dropped guardrail stays traceable.

[licjun]

The justification is in the PR description, under "awslint exclusion": the endpoint's physical name is endpointName, the service's term (AWS::Lambda::WebFunctionEndpoint.EndpointName), rather than webFunctionEndpointName. awslint.json is plain JSON, so there is no place for a note next to the entry.

[licjun]

Updated the PR description, per the last review: an update leaves the old object version in place and it is deleted only when its copy is removed in cleanup (kept if its revision is retained), and the copy role gets s3:GetObject/s3:GetObjectVersion on the source objects and put/delete on the destination key pattern. I also corrected the code-bucket grant line, which said it was scoped to the code object: that holds for fromBucket and a provided bucket, while the managed bucket has one statement for web-function/* and any WebFunction revision in the account.