feat(llmo): CloudFront CDN log delivery with assume-role setup (LLMO-5566)

[claudiaboldis]

Summary

• Adds server-side STS AssumeRole (connector role) so the LLMO UI CloudFront wizard never needs AWS credentials in the browser — all CloudFront and CloudWatch Logs calls are performed by the Lambda
• Adds 5 read-only wizard endpoints (connect, distributions, prerequisites, origins, behaviors) that power the step-by-step CloudFront BYOCDN setup flow
• Adds POST /sites/:siteId/llmo/cdn-log-delivery (diagram step 8) — idempotently creates a CloudWatch Logs delivery source in the customer's account and links it to Adobe's cross-account delivery destination, enabling CloudFront standard log push to the cdn-logs S3 bucket

New files

File	Purpose
src/support/edge-optimize.js	assumeConnectorRole (STS), listCloudFrontDistributions, getDistributionConfig, idempotent step-on-poll deploy orchestrator
src/support/cdn-log-delivery.js	Provider-agnostic log-delivery registry; CloudFront path uses logs:PutDeliverySource + logs:CreateDelivery via the assumed role

Endpoints (all POST, all INTERNAL_ROUTES — admin/IMS-only)

• POST /sites/:siteId/llmo/edge-optimize/connect
• POST /sites/:siteId/llmo/edge-optimize/distributions
• POST /sites/:siteId/llmo/edge-optimize/prerequisites
• POST /sites/:siteId/llmo/edge-optimize/origins
• POST /sites/:siteId/llmo/edge-optimize/behaviors
• POST /sites/:siteId/llmo/cdn-log-delivery

⚠️ Cross-service dependencies (not in this PR — must land before prod)

1. Connector-role IAM policy (customer-bootstrap-role.yaml in EDGE_OPTIMIZE_TEMPLATE_BUCKET) must add logs:PutDeliverySource, logs:CreateDelivery, logs:GetDeliverySource, logs:DescribeDeliveries — today the role only grants CloudFront perms
2. spacecat-auth-service must provision the cdn-logs-<org> delivery destination + cross-account policy for the BYOCDN CloudFront path (the handler surfaces a clear "destination not provisioned" 400 if it's missing)

Test plan

# verify connector role assumable
curl -s -X POST "https://spacecat.experiencecloud.live/sites/$SITE_ID/llmo/edge-optimize/connect" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"accountId":"123456789012","externalId":"<externalId>"}'
# Expected: HTTP 200 { "connected": true }

# list distributions via assumed role
curl -s -X POST "https://spacecat.experiencecloud.live/sites/$SITE_ID/llmo/edge-optimize/distributions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"accountId":"123456789012","externalId":"<externalId>"}'
# Expected: HTTP 200 { "distributions": [...] }

# enable log delivery (idempotent)
curl -s -X POST "https://spacecat.experiencecloud.live/sites/$SITE_ID/llmo/cdn-log-delivery" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"accountId":"123456789012","externalId":"<externalId>","distributionId":"EDFDVBD6EXAMPLE"}'
# Expected: HTTP 200 { "alreadyExisted": false, "deliveryId": "..." }
# Re-run: HTTP 200 { "alreadyExisted": true }

Related

• Closes LLMO-5566
• Based on PR feat(llmo): add CloudFront wizard read endpoints #2654 (wizard read endpoints) and PR feat(llmo): CDN log-forwarding endpoint (BYOCDN CloudFront, step 8) #2671 (log-forwarding endpoint) by @Akbhardwaj

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[github-actions]

This PR will trigger a minor release when merged.

[MysticatBot]

Hey @claudiaboldis,

Verdict: Request changes - two issues to address before merge (concurrency cap and HTTP status correctness).
Complexity: HIGH - large diff; API surface + new dependency.
Changes: Adds CDN log delivery endpoints (single-distribution and bulk rescan) using STS AssumeRole to create CloudWatch Logs delivery sources in customer accounts (13 files).
Note: Recommend a human read before merge - this change modifies the OpenAPI contract (docs/openapi/). The bot review is a complement to, not a replacement for, a human read here.

Must fix before merge

1. [Important] Unbounded concurrency in rescanCdnLogDelivery will throttle on large accounts - src/controllers/llmo/llmo-cloudfront.js:1228. Promise.allSettled fires createCdnLogDelivery for ALL distributions in parallel with no concurrency cap. Each call issues 1-3 CloudWatch Logs API calls. A customer with 50+ distributions will hit CloudWatch Logs per-account throttling (10-25 TPS), causing most calls to fail with ThrottlingException. Fix: add a concurrency limiter (e.g. p-limit(5)) or batch distributions in small groups.
2. [Important] Missing server config returns 400 (client error) instead of 500 - src/controllers/llmo/llmo-cloudfront.js:1164. When CDN_LOG_DELIVERY_DEST_ACCOUNT_ID is not set, badRequest(...) tells the caller their input is wrong when the server is misconfigured. Fix: return internalServerError(...) instead (same applies in rescanCdnLogDelivery at line ~1218).

Non-blocking (3): minor issues and suggestions

• nit: docs/LLMO-5566/plan.md references src/controllers/llmo/llmo.js and 16 endpoints, but the actual controller is llmo-cloudfront.js and this PR delivers 2 endpoints - the plan is misleading from day one
• suggestion: Both new handlers diverge from the existing mutationErrorResponse pattern used by sibling endpoints in this controller (which surfaces actionable AWS errors like AccessDeniedException and ThrottlingException as 400s instead of generic 500) - consider using mutationErrorResponse in the outer catch for consistency - src/controllers/llmo/llmo-cloudfront.js:1270
• suggestion: rescanCdnLogDelivery response includes raw outcome.reason?.message per distribution, which can expose internal AWS error details (ARNs, role names) to the caller - consider sanitizing to error category only - src/controllers/llmo/llmo-cloudfront.js:1244

[MysticatBot]

Mysticat review failed: Claude CLI crashed (exit 1): stderr= stdout={"type":"result","subtype":"error_max_budget_usd","duration_ms":628407,"duration_api_ms":1527224,"is_error":true,"num_turns":38,"stop_reason":"end_turn","session_id":"7e869476-18cc-497e-b372-17f8889bac58","total_cost_usd":10.07213945,"usage":{"input_tokens":19,"cache_creation_input_tokens":224486,"c

[ABHA61]

Reviewed the two new CDN log-delivery endpoints (enableCdnLogDelivery, rescanCdnLogDelivery), the cdn-log-delivery.js support module, wiring, tests, and OpenAPI — and cross-checked against the public CloudFront log-forwarding docs. Structure, routing, capability gating, client return shapes, OpenAPI (no drift), and the core idempotency logic all verified clean; temp AWS credentials / externalId / role ARNs are never logged or returned. Items worth addressing, grouped by severity:

#	Sev · type	Finding	Loc
1	MED · correctness	Idempotency matches on delivery-source name only, ignoring the destination ARN — an existing delivery to a different/older destination is reported alreadyExisted and never re-pointed, so if Adobe's destination ARN ever changes, logs silently keep flowing to the old place.	cdn-log-delivery.js:157
2	MED · correctness	PutDeliverySource throwing ConflictException (distribution already bound to another delivery source — e.g. a customer who set it up manually first) is not handled: enable returns 500, rescan marks it failed. The public CLI doc explicitly warns this exact error can occur, so it's a realistic idempotency break.	cdn-log-delivery.js:191
3	MED · correctness/UX	A valid-format but nonexistent/wrong-account distributionId makes PutDeliverySource throw ResourceNotFoundException, which the handler maps to "Adobe log destination is not provisioned — run cdn-logs provisioning first," sending ops to chase a nonexistent provisioning gap.	llmo-cloudfront.js:1191
4	MED · security	enableCdnLogDelivery enables forwarding for any caller-supplied distributionId in the account with no check that the distribution serves this site. In an AWS account shared across two IMS orgs, org X's admin can route org Y's distribution access logs into org X's cdn-logs bucket (confused-deputy / cross-org capture). The existing assertDistributionServesSite helper (with its allowDomainMismatch override) closes this — and also fixes #3.	llmo-cloudfront.js:1153
5	MED · correctness/UX	The AWS-error categorization set is CloudFront-only; CloudWatch delivery errors — ServiceQuotaExceededException (deliveries-per-account cap, likely on rescan), ValidationException, ConflictException, ExpiredTokenException — fall through to a generic 500 instead of an actionable 4xx.	llmo-cloudfront.js:237
6	MED · operational	CDN_LOG_DELIVERY_DEST_ACCOUNT_ID is a new required env var with no in-repo reference (absent from .env.example/README/config), and it isn't listed as a provisioning follow-up. If unset on deploy, both endpoints hard-500 for every call until it's added out-of-band.	llmo-cloudfront.js:1173
7	MED · test-fidelity	Tests assert only the result of createCdnLogDelivery, never the AWS command inputs (resourceArn, logType, recordFields, suffixPath, region, credentials) — a typo in any of these ships green and only surfaces at live onboarding.	test/support/cdn-log-delivery.test.js:115
8	MED · test-fidelity	Controller tests stub the helpers and never assert their args — passing the customer accountId as adobeAccountId, swapping imsOrgId, or handing over wrong credentials would misroute logs with all tests green.	test/controllers/llmo/llmo-cloudfront.test.js:2346
9	LOW-MED · efficiency	DescribeDeliveriesCommand is passed a deliverySourceName filter the API doesn't accept (SDK input is only nextToken/limit); it's silently dropped, so every call paginates all account deliveries and relies on a client-side .find. Correct today, but O(N×total) during rescan, and the comment misrepresents it as server-filtered.	cdn-log-delivery.js:154
10	LOW-MED · security	On categorized errors, enable returns the raw AWS message in the 400 body — for AccessDenied that includes Adobe's cross-account destination ARN (the dest account id) and the assumed-role ARN. The per-distribution rescan summary already avoids this by returning the error name only; enable should match.	llmo-cloudfront.js:1205
11	LOW-MED · test-fidelity	The "AccessDenied" test constructs new Error('AccessDeniedException: …') whose .name is Error, so it hits the 500 fallback, not the 4xx categorization branch — the test asserts 500 and passes, leaving the categorization path unexercised.	test/…/llmo-cloudfront.test.js:2424
12	LOW-MED · UX	Rescan has no ResourceNotFoundException short-circuit: if the destination isn't provisioned, every distribution fails and it returns 200 with all-failed and opaque per-item codes — no actionable message, unlike enable.	llmo-cloudfront.js:1267
13	LOW-MED · scalability	Rescan runs the whole account in one synchronous request reusing one set of assumed credentials (STS session is 15 min). A large account can exceed the ~60s gateway timeout and/or the 15-min credential lifetime, failing late batches with no summary returned.	llmo-cloudfront.js:1243
14	LOW-MED · cross-service	toSafeAwsName must match spacecat-auth-service byte-for-byte and only strips @AdobeOrg/@; a non-standard imsOrgId (dots/spaces) would produce an invalid source name or a divergent destination ARN (surfacing as the misleading #3 message). Standard IMS org ids are fine.	cdn-log-delivery.js:58

Nits (optional, non-blocking):

• accountId is derived via replace(/\D/g,'') + length-12 rather than a strict /^\d{12}$/, so embedded junk silently coerces to a 12-digit id (bounded by STS trust). llmo-cloudfront.js:183
• findExistingDelivery's do…while(nextToken) has no max-page / seen-token guard (infinite-loop risk if the API echoes a stable token). cdn-log-delivery.js:151
• Untested reachable branches: partial-state fall-through (source exists, no delivery → created:true) and empty-distributions rescan. cdn-log-delivery.test.js:134
• Defense-in-depth: nothing server-side binds the client-supplied externalId/account to the site's org (STS bounds it; hardening = persist externalId at bootstrap and validate the account against the org). llmo-cloudfront.js:1179
• ResourceAlreadyExistsException in the CreateDelivery catch is dead code (CreateDelivery signals a dup via ConflictException, which is handled); the >60-char source-name hash-truncation is effectively unreachable for real ids; the two methods duplicate ~20 lines of preamble (a small shared helper would prevent drift); enable's ResourceNotFoundException branch writes no audit line; a new CloudWatchLogsClient is built per createCdnLogDelivery call.

Please confirm:

• IAM permissions — the code uses logs:PutDeliverySource, logs:CreateDelivery, logs:GetDeliverySource, and logs:DescribeDeliveries. Please confirm the bootstrap connector-role template grants all four (the public console doc lists only the first two), and that the template PR lands with or before this — otherwise the idempotency calls fail with AccessDenied.
• Shared-client placement — the new CloudWatch log-delivery control-plane (cdn-log-delivery.js) sits in api-service, while the connector-role AWS operations (assumeConnectorRole, CloudFrontEdgeClient) live in @adobe/spacecat-shared-tokowaka-client. It's the same class of connector-role operation and other consumers may need to (re)enable delivery, so worth deciding whether it belongs in the shared client (that also keeps the toSafeAwsName byte-for-byte contract in one place). Related direction: the CloudFront control-plane currently lives in spacecat-shared-tokowaka-client, but longer-term it should move into a dedicated cloudfront-client package — mirroring the existing cloudflare-client — and this log-delivery code should follow to that same home. Fine as a fast follow-up.

[claudiaboldis]

IAM permissions — confirmed. Both customer-bootstrap-role.yaml and customer-bootstrap-role-log-only.yaml already grant all four permissions: logs:PutDeliverySource, logs:CreateDelivery, logs:GetDeliverySource, and logs:DescribeDeliveries. The templates are included in this PR (added in the same commit), so they land together — no sequencing risk.

Shared-client placement — deferred, tracked. Agreed that cdn-log-delivery.js belongs in a shared package long-term. Moving it now would block this PR on a shared-client release cycle and add unrelated churn. The plan is to follow the CloudFront control-plane when it migrates to a dedicated cloudfront-client package (mirroring cloudflare-client), and cdn-log-delivery.js + toSafeAwsName move there at that point — keeping the byte-for-byte contract in one place. Will track as a follow-up ticket.