@go-to-k/cdkd 0.124.0 → 0.125.0

package/dist/cli.js

@@ -19,9 +19,9 @@ import { CloudFrontClient, CreateCloudFrontOriginAccessIdentityCommand, CreateDi
 import { CloudWatchClient, DeleteAlarmsCommand, DescribeAlarmsCommand, ListTagsForResourceCommand as ListTagsForResourceCommand$4, PutMetricAlarmCommand, TagResourceCommand as TagResourceCommand$6, UntagResourceCommand as UntagResourceCommand$6 } from "@aws-sdk/client-cloudwatch";
 import { CloudWatchLogsClient, CreateLogGroupCommand, DeleteDataProtectionPolicyCommand, DeleteIndexPolicyCommand, DeleteLogGroupCommand, DeleteRetentionPolicyCommand, DescribeIndexPoliciesCommand, DescribeLogGroupsCommand, GetDataProtectionPolicyCommand, ListTagsForResourceCommand as ListTagsForResourceCommand$5, PutBearerTokenAuthenticationCommand, PutDataProtectionPolicyCommand, PutIndexPolicyCommand, PutLogGroupDeletionProtectionCommand, PutRetentionPolicyCommand, ResourceAlreadyExistsException, ResourceNotFoundException as ResourceNotFoundException$4, TagResourceCommand as TagResourceCommand$7, UntagResourceCommand as UntagResourceCommand$7 } from "@aws-sdk/client-cloudwatch-logs";
 import { BedrockAgentCoreControlClient, CreateAgentRuntimeCommand, DeleteAgentRuntimeCommand, GetAgentRuntimeCommand, ResourceNotFoundException as ResourceNotFoundException$5, UpdateAgentRuntimeCommand } from "@aws-sdk/client-bedrock-agentcore-control";
-import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { cpSync, createWriteStream, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import * as path from "node:path";
-import { dirname, isAbsolute, resolve } from "node:path";
+import { dirname, isAbsolute, join, normalize, resolve } from "node:path";
 import { execFile, spawn } from "node:child_process";
 import { tmpdir } from "node:os";
 import { AssociateVPCWithHostedZoneCommand, ChangeResourceRecordSetsCommand, ChangeTagsForResourceCommand, CreateHostedZoneCommand, CreateQueryLoggingConfigCommand, DeleteHostedZoneCommand, DeleteQueryLoggingConfigCommand, DisassociateVPCFromHostedZoneCommand, GetHostedZoneCommand, ListHostedZonesByNameCommand, ListHostedZonesCommand, ListQueryLoggingConfigsCommand, ListResourceRecordSetsCommand, ListTagsForResourceCommand as ListTagsForResourceCommand$6, Route53Client, UpdateHostedZoneCommentCommand } from "@aws-sdk/client-route-53";
@@ -57,6 +57,9 @@ import { CreateNamespaceCommand, CreateTableBucketCommand, CreateTableCommand as
 import { AttachTrafficSourcesCommand, AutoScalingClient, CreateAutoScalingGroupCommand, DeleteAutoScalingGroupCommand, DeleteLifecycleHookCommand, DeleteNotificationConfigurationCommand, DescribeAutoScalingGroupsCommand, DescribeLifecycleHooksCommand, DescribeNotificationConfigurationsCommand, DescribeTrafficSourcesCommand, DetachTrafficSourcesCommand, DisableMetricsCollectionCommand, EnableMetricsCollectionCommand, PutLifecycleHookCommand, PutNotificationConfigurationCommand, UpdateAutoScalingGroupCommand } from "@aws-sdk/client-auto-scaling";
 import * as readline from "node:readline/promises";
 import { Document, Pair, Scalar, YAMLMap, YAMLSeq, parse as parse$1, stringify } from "yaml";
+import { mkdir, mkdtemp } from "node:fs/promises";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
 import { createServer } from "node:net";
 import { promisify } from "node:util";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
@@ -36687,16 +36690,23 @@ function resolveAssetCodePath$1(stack, logicalId, resource) {
 * bind mounts at the same target so cdkd cannot rely on overlay
 * layering.
 *
-* **Out of scope (hard-errors)**:
+* **Same-stack handling** (`{Ref: <Id>}` / `{Fn::GetAtt: [<Id>, 'Ref']}`):
 *
-*   - Literal ARN strings (`arn:aws:lambda:...`) — these are external /
-*     pre-existing layers (no asset on disk to mount) including
-*     cross-account / cross-region.
-*   - Same-stack refs that don't point at an `AWS::Lambda::LayerVersion`
-*     resource — almost always a typo'd logical ID.
-*   - Same-stack refs to a `LayerVersion` whose `Metadata['aws:asset:path']`
-*     is missing — the layer's content is `S3Bucket` / `S3Key` from
-*     outside cdk.out and there's no local directory to bind-mount.
+*   - Refs that don't point at an `AWS::Lambda::LayerVersion` resource
+*     hard-error — almost always a typo'd logical ID.
+*   - Refs to a `LayerVersion` whose `Metadata['aws:asset:path']` is
+*     missing hard-error — the layer's content is `S3Bucket` / `S3Key`
+*     from outside cdk.out and there's no local directory to bind-mount.
+*
+* **Literal-ARN handling** (issue #448): entries shaped like the string
+* `arn:aws:lambda:<region>:<account>:layer:<name>:<version>` are parsed
+* into a `{kind: 'arn', ...}` resolved layer. The actual
+* `lambda:GetLayerVersion` + presigned-URL download + unzip happens
+* later in the CLI (`materializeLayerFromArn(...)`), which can optionally
+* `sts:AssumeRole` into the layer's account when the dev's default
+* credentials cannot read it. Covers AWS-published public layers (Lambda
+* Powertools, Datadog Extension, etc.) and cross-account / cross-region
+* shared layers.
 */
 function resolveLambdaLayers(stack, logicalId, props) {
 	const layers = props["Layers"];
@@ -36707,13 +36717,24 @@ function resolveLambdaLayers(stack, logicalId, props) {
 	const out = [];
 	for (let i = 0; i < layers.length; i++) {
 		const entry = layers[i];
+		if (typeof entry === "string") {
+			const parsed = parseLayerVersionArn(entry);
+			if (!parsed) throw new LocalInvokeResolutionError(`Lambda '${logicalId}' has a Layers entry [${i}] cdkd cannot resolve locally: literal string '${entry}'. Expected a same-stack Ref / Fn::GetAtt to an AWS::Lambda::LayerVersion OR a literal layer-version ARN of the form arn:aws:lambda:<region>:<account>:layer:<name>:<version>.`);
+			out.push({
+				kind: "arn",
+				logicalId: parsed.arn,
+				...parsed
+			});
+			continue;
+		}
 		const layerLogicalId = pickLayerLogicalId(entry);
-		if (!layerLogicalId) throw new LocalInvokeResolutionError(`Lambda '${logicalId}' has a Layers entry [${i}] cdkd cannot resolve locally: ${describeLayerEntry(entry)}. Only same-stack Ref / Fn::GetAtt to an AWS::Lambda::LayerVersion are supported in v1; cross-account / cross-region / pre-existing-ARN layers are deferred to a follow-up PR.`);
+		if (!layerLogicalId) throw new LocalInvokeResolutionError(`Lambda '${logicalId}' has a Layers entry [${i}] cdkd cannot resolve locally: ${describeLayerEntry(entry)}. Expected a same-stack Ref / Fn::GetAtt to an AWS::Lambda::LayerVersion OR a literal layer-version ARN of the form arn:aws:lambda:<region>:<account>:layer:<name>:<version>.`);
 		const layerResource = resources[layerLogicalId];
 		if (!layerResource) throw new LocalInvokeResolutionError(`Lambda '${logicalId}' Layers entry [${i}] references '${layerLogicalId}', but no resource with that logical ID exists in stack '${stack.stackName}'.`);
 		if (layerResource.Type !== "AWS::Lambda::LayerVersion") throw new LocalInvokeResolutionError(`Lambda '${logicalId}' Layers entry [${i}] references '${layerLogicalId}' (${layerResource.Type}), which is not an AWS::Lambda::LayerVersion.`);
 		const assetPath = resolveAssetCodePath$1(stack, layerLogicalId, layerResource);
 		out.push({
+			kind: "asset",
 			logicalId: layerLogicalId,
 			assetPath
 		});
@@ -36721,6 +36742,29 @@ function resolveLambdaLayers(stack, logicalId, props) {
 	return out;
 }
 /**
+* Parse a Lambda layer-version ARN string into its segments.
+*
+* Returns `undefined` for anything that does not match the strict
+* `arn:aws:lambda:<region>:<account>:layer:<name>:<version>` shape so
+* the caller can produce a clearer error than a silent
+* misinterpretation of hand-edited templates. The partition segment
+* accepts `aws` / `aws-cn` / `aws-us-gov` so GovCloud / China-region
+* ARNs work without code changes.
+*
+* Exported for unit testing.
+*/
+function parseLayerVersionArn(input) {
+	const m = /^arn:(aws|aws-cn|aws-us-gov):lambda:([a-z]{2}-(?:[a-z]+-){1,2}\d+):(\d{12}):layer:([A-Za-z0-9_-]+):(\d+)$/.exec(input);
+	if (!m) return void 0;
+	return {
+		arn: input,
+		region: m[2],
+		accountId: m[3],
+		name: m[4],
+		version: m[5]
+	};
+}
+/**
 * Walk a single Layers-array entry and return the referenced layer's
 * logical ID — or `undefined` for shapes we don't try to resolve in v1.
 *
@@ -36789,6 +36833,195 @@ function notFoundError$1(target, stack, resources) {
 	return new LocalInvokeResolutionError(msg.trimEnd());
 }
 
+//#endregion
+//#region src/local/layer-arn-materializer.ts
+var LayerMaterializationError = class LayerMaterializationError extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "LayerMaterializationError";
+		Object.setPrototypeOf(this, LayerMaterializationError.prototype);
+	}
+};
+async function materializeLayerFromArn(layer, options = {}) {
+	const logger = getLogger();
+	let credentials;
+	if (options.roleArn) try {
+		credentials = await assumeRoleForLayer(options.roleArn, layer.region, options);
+		logger.debug(`Layer ${layer.arn}: assumed role ${options.roleArn} for GetLayerVersion`);
+	} catch (err) {
+		throw new LayerMaterializationError(`Layer ${layer.arn}: STS AssumeRole(${options.roleArn}) failed: ${errMsg(err)}. Check the role trust policy permits your principal and sts:AssumeRole is allowed.`);
+	}
+	let presignedUrl;
+	try {
+		presignedUrl = await fetchLayerContentUrl(layer, credentials, options);
+	} catch (err) {
+		const hint = looksLikeAccessDenied(err) ? " GetLayerVersion access denied; check the credentials / role can read the layer (grant lambda:GetLayerVersion on the layer ARN, or pass --layer-role-arn <arn> to assume a role in the layer account)." : "";
+		throw new LayerMaterializationError(`Layer ${layer.arn}: GetLayerVersion failed in region ${layer.region}: ${errMsg(err)}.${hint}`);
+	}
+	let zipBytes;
+	try {
+		zipBytes = await downloadPresignedZip(presignedUrl, options);
+	} catch (err) {
+		throw new LayerMaterializationError(`Layer ${layer.arn}: failed to download layer ZIP from the presigned URL: ${errMsg(err)}.`);
+	}
+	const dir = await mkdtemp(join(tmpdir(), `cdkd-local-arn-layer-${layer.name}-${layer.version}-`));
+	try {
+		await unzipBufferToDirectory(zipBytes, dir);
+	} catch (err) {
+		try {
+			rmSync(dir, {
+				recursive: true,
+				force: true
+			});
+		} catch {}
+		throw new LayerMaterializationError(`Layer ${layer.arn}: failed to unzip layer contents into '${dir}': ${errMsg(err)}.`);
+	}
+	return dir;
+}
+async function fetchLayerContentUrl(layer, credentials, options) {
+	const client = (options.lambdaClientFactory ?? await defaultLambdaClientFactory())(layer.region, credentials);
+	try {
+		const command = await buildGetLayerVersionCommand(`arn:aws:lambda:${layer.region}:${layer.accountId}:layer:${layer.name}`, Number(layer.version));
+		const url = (await client.send(command))?.Content?.Location;
+		if (!url || typeof url !== "string") throw new Error("GetLayerVersion response did not include Content.Location (presigned ZIP URL)");
+		return url;
+	} finally {
+		client.destroy?.();
+	}
+}
+async function assumeRoleForLayer(roleArn, region, options) {
+	const client = (options.stsClientFactory ?? await defaultStsClientFactory())(region);
+	try {
+		const command = await buildAssumeRoleCommand(roleArn);
+		const creds = (await client.send(command))?.Credentials;
+		if (!creds?.AccessKeyId || !creds.SecretAccessKey) throw new Error("AssumeRole returned no Credentials");
+		return {
+			accessKeyId: creds.AccessKeyId,
+			secretAccessKey: creds.SecretAccessKey,
+			...creds.SessionToken !== void 0 && { sessionToken: creds.SessionToken }
+		};
+	} finally {
+		client.destroy?.();
+	}
+}
+async function defaultLambdaClientFactory() {
+	const { LambdaClient } = await import("@aws-sdk/client-lambda");
+	return (region, credentials) => new LambdaClient({
+		region,
+		...credentials && { credentials: {
+			accessKeyId: credentials.accessKeyId,
+			secretAccessKey: credentials.secretAccessKey,
+			...credentials.sessionToken !== void 0 && { sessionToken: credentials.sessionToken }
+		} }
+	});
+}
+async function defaultStsClientFactory() {
+	const { STSClient } = await import("@aws-sdk/client-sts");
+	return (region) => new STSClient({ region });
+}
+async function buildGetLayerVersionCommand(layerArn, versionNumber) {
+	const { GetLayerVersionCommand } = await import("@aws-sdk/client-lambda");
+	return new GetLayerVersionCommand({
+		LayerName: layerArn,
+		VersionNumber: versionNumber
+	});
+}
+async function buildAssumeRoleCommand(roleArn) {
+	const { AssumeRoleCommand } = await import("@aws-sdk/client-sts");
+	return new AssumeRoleCommand({
+		RoleArn: roleArn,
+		RoleSessionName: `cdkd-local-layer-${Date.now()}`,
+		DurationSeconds: 3600
+	});
+}
+async function downloadPresignedZip(presignedUrl, options) {
+	if (options.fetchZip) return options.fetchZip(presignedUrl);
+	const response = await fetch(presignedUrl);
+	if (!response.ok) throw new Error(`HTTP ${response.status} ${response.statusText} from layer Content.Location URL`);
+	const buf = await response.arrayBuffer();
+	return new Uint8Array(buf);
+}
+/**
+* Minimal ZIP unzipper that handles the subset of the ZIP format Lambda
+* layer ZIPs ever use (DEFLATE compression method 8, STORE method 0).
+* Avoids bringing in a heavyweight dep for a 50-line task.
+*
+* Path-traversal guard: every entry's relative path is `normalize()`d
+* and rejected if the resulting absolute path escapes `destDir` (the
+* "Zip Slip" CVE class). Symlinks inside the ZIP are also rejected for
+* the same reason — they could point at arbitrary host paths.
+*/
+async function unzipBufferToDirectory(zipBytes, destDir) {
+	const view = new DataView(zipBytes.buffer, zipBytes.byteOffset, zipBytes.byteLength);
+	const eocdSig = 101010256;
+	const minScan = Math.max(0, zipBytes.byteLength - 65535 - 22);
+	let eocdOffset = -1;
+	for (let i = zipBytes.byteLength - 22; i >= minScan; i--) if (view.getUint32(i, true) === eocdSig) {
+		eocdOffset = i;
+		break;
+	}
+	if (eocdOffset < 0) throw new Error("Not a ZIP file (no End of Central Directory record found)");
+	const totalEntries = view.getUint16(eocdOffset + 10, true);
+	const cdSize = view.getUint32(eocdOffset + 12, true);
+	const cdOffset = view.getUint32(eocdOffset + 16, true);
+	const destAbsolute = resolve(destDir);
+	let cursor = cdOffset;
+	const cdEnd = cdOffset + cdSize;
+	let parsed = 0;
+	while (cursor < cdEnd && parsed < totalEntries) {
+		if (view.getUint32(cursor, true) !== 33639248) throw new Error(`Corrupt ZIP: missing Central Directory header at offset ${cursor}`);
+		const compressionMethod = view.getUint16(cursor + 10, true);
+		const compressedSize = view.getUint32(cursor + 20, true);
+		const uncompressedSize = view.getUint32(cursor + 24, true);
+		const fileNameLength = view.getUint16(cursor + 28, true);
+		const extraFieldLength = view.getUint16(cursor + 30, true);
+		const fileCommentLength = view.getUint16(cursor + 32, true);
+		const externalAttrs = view.getUint32(cursor + 38, true);
+		const localHeaderOffset = view.getUint32(cursor + 42, true);
+		const fileName = new TextDecoder("utf-8").decode(zipBytes.subarray(cursor + 46, cursor + 46 + fileNameLength));
+		cursor += 46 + fileNameLength + extraFieldLength + fileCommentLength;
+		parsed++;
+		const targetPath = resolve(destAbsolute, normalize(fileName));
+		if (!targetPath.startsWith(destAbsolute + (destAbsolute.endsWith("/") ? "" : "/"))) throw new Error(`Refusing to extract entry '${fileName}' — path escapes the destination directory`);
+		if ((externalAttrs >>> 16 & 61440) === 40960) throw new Error(`Refusing to extract symlink entry '${fileName}' from layer ZIP (security)`);
+		if (fileName.endsWith("/")) {
+			await mkdir(targetPath, { recursive: true });
+			continue;
+		}
+		await mkdir(dirname(targetPath), { recursive: true });
+		if (view.getUint32(localHeaderOffset, true) !== 67324752) throw new Error(`Corrupt ZIP: missing Local File Header for '${fileName}'`);
+		const lfhFileNameLength = view.getUint16(localHeaderOffset + 26, true);
+		const lfhExtraFieldLength = view.getUint16(localHeaderOffset + 28, true);
+		const dataOffset = localHeaderOffset + 30 + lfhFileNameLength + lfhExtraFieldLength;
+		const compressedData = zipBytes.subarray(dataOffset, dataOffset + compressedSize);
+		let payload;
+		if (compressionMethod === 0) payload = compressedData;
+		else if (compressionMethod === 8) payload = await inflateRaw(compressedData);
+		else throw new Error(`Unsupported ZIP compression method ${compressionMethod} for entry '${fileName}' (only STORE and DEFLATE supported)`);
+		if (payload.length !== uncompressedSize && compressionMethod !== 0) throw new Error(`ZIP entry '${fileName}': inflate produced ${payload.length} bytes, expected ${uncompressedSize}`);
+		await pipeline(Readable.from(payload), createWriteStream(targetPath));
+	}
+}
+async function inflateRaw(data) {
+	const { inflateRaw: inflate } = await import("node:zlib");
+	return new Promise((resolveP, rejectP) => {
+		inflate(data, (err, out) => {
+			if (err) rejectP(err);
+			else resolveP(out);
+		});
+	});
+}
+function errMsg(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+function looksLikeAccessDenied(err) {
+	if (!(err instanceof Error)) return false;
+	const name = err.name ?? "";
+	const code = err.Code ?? "";
+	const message = err.message ?? "";
+	return name === "AccessDeniedException" || code === "AccessDeniedException" || /access denied/i.test(message) || /not authorized/i.test(message);
+}
+
 //#endregion
 //#region src/local/env-resolver.ts
 /**
@@ -43667,7 +43900,8 @@ async function localStartApiCommand(target, options) {
 				stsRegion: options.region ?? process.env["AWS_REGION"] ?? process.env["AWS_DEFAULT_REGION"],
 				inlineTmpDirs,
 				layerTmpDirs,
-				stateByStack
+				stateByStack,
+				...options.layerRoleArn !== void 0 && { layerRoleArn: options.layerRoleArn }
 			});
 			specs.set(logicalId, spec);
 		}
@@ -43977,10 +44211,10 @@ function warnIamRoutes(routesWithAuth) {
 * missing, runtime not supported).
 */
 async function buildContainerSpec(args) {
-	const { logicalId, stacks, overrides, assumeRole, containerHost, debugPort, stsRegion, inlineTmpDirs, layerTmpDirs, stateByStack } = args;
+	const { logicalId, stacks, overrides, assumeRole, containerHost, debugPort, stsRegion, inlineTmpDirs, layerTmpDirs, stateByStack, layerRoleArn } = args;
 	const lambda = resolveLambdaByLogicalId(logicalId, stacks);
 	const codeDir = lambda.codePath ?? materializeInlineCode$1(lambda.handler, lambda.inlineCode ?? "", resolveRuntimeFileExtension(lambda.runtime), inlineTmpDirs);
-	const optDir = materializeLambdaLayers$1(lambda.layers, layerTmpDirs);
+	const optDir = await materializeLambdaLayers$1(lambda.layers, layerTmpDirs, layerRoleArn);
 	let templateEnv = getTemplateEnv$1(lambda.resource);
 	const stateBundle = stateByStack.get(lambda.stack.stackName);
 	let stateAudit;
@@ -44039,22 +44273,46 @@ async function buildContainerSpec(args) {
 *
 * Three branches:
 *   - 0 layers → `undefined` (no `/opt` mount).
-*   - 1 layer → bind-mount the layer's asset dir directly (no copy).
+*   - 1 layer → bind-mount the layer's asset dir directly (no copy)
+*     when the entry is a same-stack asset. Literal-ARN entries always
+*     pre-materialize first.
 *   - 2+ layers → copy each into a fresh tmpdir IN ORDER (later
 *     layers overwrite earlier files via `cpSync({force: true})`),
 *     bind-mount the tmpdir at `/opt`. Records the tmpdir in
 *     `layerTmpDirs` so `shutdown(...)` removes it.
 *
+* Issue #448: literal-ARN entries (`{kind: 'arn', ...}`) are downloaded
+* + unzipped via `lambda:GetLayerVersion` BEFORE the cpSync-merge
+* branches run. Every per-ARN tmpdir is also recorded in `layerTmpDirs`
+* so the same shutdown path cleans it up — even for the single-layer
+* fast path that bind-mounts the dir directly.
+*
 * AWS Lambda's actual runtime extracts every layer ZIP into `/opt`
 * in template order — the merge mirrors that. Docker rejects multiple
 * `-v ...:/opt:ro` entries at the same target, so cdkd can't rely on
 * overlay layering and must produce a single merged dir on the host.
 */
-function materializeLambdaLayers$1(layers, layerTmpDirs) {
+async function materializeLambdaLayers$1(layers, layerTmpDirs, layerRoleArn) {
 	if (layers.length === 0) return void 0;
-	if (layers.length === 1) return layers[0].assetPath;
+	const flat = [];
+	for (const layer of layers) {
+		if (layer.kind === "asset") {
+			flat.push({
+				logicalId: layer.logicalId,
+				assetPath: layer.assetPath
+			});
+			continue;
+		}
+		const dir = await materializeLayerFromArn(layer, { ...layerRoleArn !== void 0 && { roleArn: layerRoleArn } });
+		layerTmpDirs.add(dir);
+		flat.push({
+			logicalId: layer.arn,
+			assetPath: dir
+		});
+	}
+	if (flat.length === 1) return flat[0].assetPath;
 	const dir = mkdtempSync(path.join(tmpdir(), "cdkd-local-start-api-layers-"));
-	for (const layer of layers) cpSync(layer.assetPath, dir, {
+	for (const layer of flat) cpSync(layer.assetPath, dir, {
 		recursive: true,
 		force: true
 	});
@@ -44459,7 +44717,7 @@ function parseDebugPort(raw) {
 * Builder for the `start-api` subcommand. Wired up by `local.ts`.
 */
 function createLocalStartApiCommand() {
-	const startApi = new Command("start-api").description("Run a long-running local HTTP server that maps API Gateway routes (REST v1, HTTP API, Function URL) to Lambda invocations against the AWS Lambda Runtime Interface Emulator (Docker required). Supports Lambda TOKEN/REQUEST authorizers, Cognito User Pool / HTTP v2 JWT authorizers, and REST v1 AWS_IAM (SigV4 signature verification only — IAM policy evaluation is NOT emulated; see docs/local-emulation.md). When JWKS is unreachable, JWT authorizers fall back to pass-through (every token accepted) with a warn line — local dev fallback. VPC-config Lambdas run locally and surface a warn line at startup; their containers do NOT get attached to the deployed VPC subnets, so calls to private RDS / ElastiCache will fail.").argument("[target]", "Optional API filter. Accepts the bare CDK logical id ('MyHttpApi'; single-stack apps only), stack-qualified logical id ('MyStack:MyHttpApi'), full CDK Construct path ('MyStack/MyHttpApi/Resource'), or an ancestor Construct path that prefix-matches ('MyStack/MyHttpApi'). When omitted, every discovered API gets its own server. Mirrors `cdkd local invoke` / `cdkd local run-task` target syntax.").addOption(new Option("--port <port>", "HTTP server port (default: auto-allocate)").default("0")).addOption(new Option("--host <host>", "Bind address").default("127.0.0.1")).addOption(new Option("--stack <name>", "Stack to start (single-stack apps auto-detect)")).addOption(new Option("--warm", "Pre-start one container per Lambda at server boot").default(false)).addOption(new Option("--per-lambda-concurrency <n>", "Pool size cap per Lambda (default 2, max 4)").default("2")).addOption(new Option("--no-pull", "Skip docker pull (cached image)")).addOption(new Option("--container-host <host>", "IP the host uses to bind/probe the RIE port (must be a numeric IP — `docker run -p <ip>:<port>:8080` rejects hostnames). Defaults to 127.0.0.1.").default("127.0.0.1")).addOption(new Option("--debug-port-base <port>", "Reserve a contiguous --debug-port range (one per Lambda)")).addOption(new Option("--env-vars <file>", "JSON env-var overrides (SAM-compatible: {\"LogicalId\":{\"KEY\":\"VALUE\"}, \"Parameters\": {...}})")).addOption(new Option("--assume-role <arn-or-pair>", "Assume the Lambda's execution role and forward STS-issued temp creds. Bare <arn> = global default; <LogicalId>=<arn> = per-Lambda override (repeatable). Per-Lambda > global > unset (developer creds passed through).").argParser((raw, prev) => parseAssumeRoleToken(raw, prev))).addOption(new Option("--watch", "Hot-reload: re-synth + re-discover routes when cdk.out/ or asset directories change. Off by default; the server keeps the previous version serving when synth fails mid-reload.").default(false)).addOption(new Option("--stage <name>", "Select an API Gateway Stage by its 'StageName'. Default: the first Stage attached to each API. Drives event.stageVariables for both REST v1 and HTTP API v2. NOTE: For HTTP API v2 routes, requestContext.stage is always '$default' regardless of this flag (AWS-side limitation — HTTP API only exposes one stage to the integration event); only event.stageVariables is affected for v2 routes. For REST v1 routes the selected StageName is also threaded into requestContext.stage.")).addOption(new Option("--api <id>", "DEPRECATED — use the positional <target> argument instead. Same accepted forms (bare logical id, stack-qualified, Construct path, ancestor prefix). Will be removed in a future major release.")).addOption(new Option("--from-state", "Read cdkd S3 state for every routed stack and substitute Ref / Fn::GetAtt / Fn::Sub / Fn::Join (and AWS pseudo parameters) in Lambda env vars with the deployed physical IDs / attributes. Off by default — pre-PR warn-and-drop semantics are preserved. Turn on for stacks already deployed via cdkd deploy. Mirrors `cdkd local invoke --from-state` / `cdkd local run-task --from-state`. Re-runs against fresh state on every hot-reload firing (--watch).").default(false)).addOption(new Option("--stack-region <region>", "Region of the cdkd state record to read (used with --from-state when the same stack name has state in multiple regions).")).addOption(new Option("--allow-unverified-sigv4", "Opt-in: allow AWS_IAM SigV4 requests that cannot be cryptographically verified (foreign access-key-id, OR no local AWS credentials configured) to pass through with a placeholder principalId. DEFAULT off — fail-closed so unauthenticated bypass is impossible against `event.requestContext.identity.accessKey`-trusting handler code. Use only in dev loops where you understand the risk.").default(false)).action(withErrorHandling(localStartApiCommand));
+	const startApi = new Command("start-api").description("Run a long-running local HTTP server that maps API Gateway routes (REST v1, HTTP API, Function URL) to Lambda invocations against the AWS Lambda Runtime Interface Emulator (Docker required). Supports Lambda TOKEN/REQUEST authorizers, Cognito User Pool / HTTP v2 JWT authorizers, and REST v1 AWS_IAM (SigV4 signature verification only — IAM policy evaluation is NOT emulated; see docs/local-emulation.md). When JWKS is unreachable, JWT authorizers fall back to pass-through (every token accepted) with a warn line — local dev fallback. VPC-config Lambdas run locally and surface a warn line at startup; their containers do NOT get attached to the deployed VPC subnets, so calls to private RDS / ElastiCache will fail.").argument("[target]", "Optional API filter. Accepts the bare CDK logical id ('MyHttpApi'; single-stack apps only), stack-qualified logical id ('MyStack:MyHttpApi'), full CDK Construct path ('MyStack/MyHttpApi/Resource'), or an ancestor Construct path that prefix-matches ('MyStack/MyHttpApi'). When omitted, every discovered API gets its own server. Mirrors `cdkd local invoke` / `cdkd local run-task` target syntax.").addOption(new Option("--port <port>", "HTTP server port (default: auto-allocate)").default("0")).addOption(new Option("--host <host>", "Bind address").default("127.0.0.1")).addOption(new Option("--stack <name>", "Stack to start (single-stack apps auto-detect)")).addOption(new Option("--warm", "Pre-start one container per Lambda at server boot").default(false)).addOption(new Option("--per-lambda-concurrency <n>", "Pool size cap per Lambda (default 2, max 4)").default("2")).addOption(new Option("--no-pull", "Skip docker pull (cached image)")).addOption(new Option("--container-host <host>", "IP the host uses to bind/probe the RIE port (must be a numeric IP — `docker run -p <ip>:<port>:8080` rejects hostnames). Defaults to 127.0.0.1.").default("127.0.0.1")).addOption(new Option("--debug-port-base <port>", "Reserve a contiguous --debug-port range (one per Lambda)")).addOption(new Option("--env-vars <file>", "JSON env-var overrides (SAM-compatible: {\"LogicalId\":{\"KEY\":\"VALUE\"}, \"Parameters\": {...}})")).addOption(new Option("--assume-role <arn-or-pair>", "Assume the Lambda's execution role and forward STS-issued temp creds. Bare <arn> = global default; <LogicalId>=<arn> = per-Lambda override (repeatable). Per-Lambda > global > unset (developer creds passed through).").argParser((raw, prev) => parseAssumeRoleToken(raw, prev))).addOption(new Option("--watch", "Hot-reload: re-synth + re-discover routes when cdk.out/ or asset directories change. Off by default; the server keeps the previous version serving when synth fails mid-reload.").default(false)).addOption(new Option("--stage <name>", "Select an API Gateway Stage by its 'StageName'. Default: the first Stage attached to each API. Drives event.stageVariables for both REST v1 and HTTP API v2. NOTE: For HTTP API v2 routes, requestContext.stage is always '$default' regardless of this flag (AWS-side limitation — HTTP API only exposes one stage to the integration event); only event.stageVariables is affected for v2 routes. For REST v1 routes the selected StageName is also threaded into requestContext.stage.")).addOption(new Option("--api <id>", "DEPRECATED — use the positional <target> argument instead. Same accepted forms (bare logical id, stack-qualified, Construct path, ancestor prefix). Will be removed in a future major release.")).addOption(new Option("--layer-role-arn <arn>", "Role to sts:AssumeRole before calling lambda:GetLayerVersion on every literal-ARN entry in Properties.Layers (issue #448). Use only when the dev credentials cannot read the layer — typically cross-account layers. AWS-published public layers (e.g. Lambda Powertools) are readable from every account and need no role.")).addOption(new Option("--from-state", "Read cdkd S3 state for every routed stack and substitute Ref / Fn::GetAtt / Fn::Sub / Fn::Join (and AWS pseudo parameters) in Lambda env vars with the deployed physical IDs / attributes. Off by default — pre-PR warn-and-drop semantics are preserved. Turn on for stacks already deployed via cdkd deploy. Mirrors `cdkd local invoke --from-state` / `cdkd local run-task --from-state`. Re-runs against fresh state on every hot-reload firing (--watch).").default(false)).addOption(new Option("--stack-region <region>", "Region of the cdkd state record to read (used with --from-state when the same stack name has state in multiple regions).")).addOption(new Option("--allow-unverified-sigv4", "Opt-in: allow AWS_IAM SigV4 requests that cannot be cryptographically verified (foreign access-key-id, OR no local AWS credentials configured) to pass through with a placeholder principalId. DEFAULT off — fail-closed so unauthenticated bypass is impossible against `event.requestContext.identity.accessKey`-trusting handler code. Use only in dev loops where you understand the risk.").default(false)).action(withErrorHandling(localStartApiCommand));
 	[
 		...commonOptions,
 		...appOptions,
@@ -45562,6 +45820,14 @@ async function localInvokeCommand(target, options) {
 		} catch (err) {
 			getLogger().debug(`Failed to remove merged-layers tmpdir ${imagePlan.layersTmpDir}: ${err instanceof Error ? err.message : String(err)}`);
 		}
+		if (imagePlan?.layerArnTmpDirs) for (const dir of imagePlan.layerArnTmpDirs) try {
+			rmSync(dir, {
+				recursive: true,
+				force: true
+			});
+		} catch (err) {
+			getLogger().debug(`Failed to remove ARN-layer tmpdir ${dir}: ${err instanceof Error ? err.message : String(err)}`);
+		}
 	}, (err) => {
 		getLogger().debug(`cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
 	});
@@ -45747,7 +46013,7 @@ async function resolveZipImagePlan(lambda, options) {
 	}
 	const image = resolveRuntimeImage(lambda.runtime);
 	await pullImage(image, options.pull === false);
-	const layerPlan = materializeLambdaLayers(lambda.layers);
+	const layerPlan = await materializeLambdaLayersIncludingArns(lambda.layers, options);
 	const containerCodePath = resolveRuntimeCodeMountPath(lambda.runtime);
 	const tmpfs = resolveTmpfsForLambda(lambda);
 	return {
@@ -45761,10 +46027,48 @@ async function resolveZipImagePlan(lambda, options) {
 		cmd: [lambda.handler],
 		...inlineTmpDir !== void 0 && { inlineTmpDir },
 		...layerPlan.tmpDir !== void 0 && { layersTmpDir: layerPlan.tmpDir },
+		...layerPlan.extraTmpDirs.length > 0 && { layerArnTmpDirs: layerPlan.extraTmpDirs },
 		...tmpfs !== void 0 && { tmpfs }
 	};
 }
 /**
+* Two-stage layer materialization (issue #448).
+*
+*   - Stage 1: every `{kind: 'arn'}` entry is downloaded + unzipped
+*     into its own tmpdir via `materializeLayerFromArn`. The per-ARN
+*     tmpdirs are tracked in `extraTmpDirs` so the outer cleanup can
+*     remove them.
+*   - Stage 2: the resulting `{logicalId, assetPath}[]` list (in
+*     template order — ARN entries surface their `arn` as the
+*     `logicalId` for log lines) is handed to the existing
+*     `materializeLambdaLayers` `cpSync`-merge path. AWS's "last layer
+*     wins" file-collision semantic is preserved across both layer
+*     kinds because the merge step is unchanged.
+*/
+async function materializeLambdaLayersIncludingArns(layers, options) {
+	const extraTmpDirs = [];
+	const flat = [];
+	for (const layer of layers) {
+		if (layer.kind === "asset") {
+			flat.push({
+				logicalId: layer.logicalId,
+				assetPath: layer.assetPath
+			});
+			continue;
+		}
+		const dir = await materializeLayerFromArn(layer, { ...options.layerRoleArn !== void 0 && { roleArn: options.layerRoleArn } });
+		extraTmpDirs.push(dir);
+		flat.push({
+			logicalId: layer.arn,
+			assetPath: dir
+		});
+	}
+	return {
+		...materializeLambdaLayers(flat),
+		extraTmpDirs
+	};
+}
+/**
 * Build the `--tmpfs /tmp:rw,size=<N>m` plan for a Lambda (issue #440).
 *
 * The shape is identical for ZIP and IMAGE Lambdas — `--tmpfs` overlays
@@ -46172,7 +46476,7 @@ function pickReferencedLogicalId(intrinsic) {
 */
 function createLocalCommand() {
 	const local = new Command("local").description("Local execution of Lambda functions (RIE) and ECS task definitions (Docker required)");
-	const invoke = new Command("invoke").description("Run a Lambda function locally in a Docker container (RIE-backed). Target accepts a CDK display path (MyStack/MyApi/Handler) or stack-qualified logical ID (MyStack:MyApiHandler1234ABCD). Single-stack apps may omit the stack prefix.").argument("<target>", "CDK display path or stack-qualified logical ID of the Lambda to invoke").addOption(new Option("-e, --event <file>", "JSON event payload file (default: {})")).addOption(new Option("--event-stdin", "Read event JSON from stdin").default(false)).addOption(new Option("--env-vars <file>", "JSON env-var overrides (SAM-compatible: {\"LogicalId\":{\"KEY\":\"VALUE\"}})")).addOption(new Option("--no-pull", "Skip docker pull (use cached image) — no-op for IMAGE local-build path; `docker build` does not pull base layers by default")).addOption(new Option("--no-build", "Skip docker build on the IMAGE local-build path (use the previously-built tag). Requires the deterministic tag to already be in the local registry; errors with an actionable message when missing. No-op for ZIP Lambdas and the IMAGE ECR-pull path. Compatible with --no-pull.")).addOption(new Option("--debug-port <port>", "Node --inspect-brk port (default: off)")).addOption(new Option("--container-host <host>", "Host to bind the RIE port to").default("127.0.0.1")).addOption(new Option("--assume-role [arn]", "Assume the Lambda's deployed execution role and forward STS-issued temp credentials to the container so the handler runs with the deployed function's narrow permissions (closes the \"developer admin / function narrow\" skew). Three forms: (1) `--assume-role <arn>` assumes the explicit ARN; (2) `--assume-role` (bare) auto-resolves the function's execution role ARN from cdkd state (requires --from-state); (3) `--no-assume-role` explicitly opts out (forces dev creds even with --from-state). Off by default — when omitted, the developer's shell credentials are forwarded unchanged (SAM-compatible default). STS failures degrade to a warn + dev-creds fallback.")).addOption(new Option("--ecr-role-arn <arn>", "Role ARN to assume before authenticating against ECR for cross-account / centralized registries (#455). Issues sts:AssumeRole via the default credential chain and uses the temporary credentials for ecr:GetAuthorizationToken + docker pull. Required when the caller does not have direct cross-account access to the target repository. Same-account / same-region pulls do not need this flag.")).addOption(new Option("--from-state", "Read cdkd S3 state for the target stack and substitute Ref / Fn::GetAtt / Fn::Sub in env vars with the deployed physical IDs / attributes. Off by default — keep PR 1 warn-and-drop semantics; turn on for stacks already deployed via cdkd deploy.").default(false)).addOption(new Option("--stack-region <region>", "Region of the cdkd state record to read (used with --from-state when the same stack name has state in multiple regions).")).action(withErrorHandling(localInvokeCommand));
+	const invoke = new Command("invoke").description("Run a Lambda function locally in a Docker container (RIE-backed). Target accepts a CDK display path (MyStack/MyApi/Handler) or stack-qualified logical ID (MyStack:MyApiHandler1234ABCD). Single-stack apps may omit the stack prefix.").argument("<target>", "CDK display path or stack-qualified logical ID of the Lambda to invoke").addOption(new Option("-e, --event <file>", "JSON event payload file (default: {})")).addOption(new Option("--event-stdin", "Read event JSON from stdin").default(false)).addOption(new Option("--env-vars <file>", "JSON env-var overrides (SAM-compatible: {\"LogicalId\":{\"KEY\":\"VALUE\"}})")).addOption(new Option("--no-pull", "Skip docker pull (use cached image) — no-op for IMAGE local-build path; `docker build` does not pull base layers by default")).addOption(new Option("--no-build", "Skip docker build on the IMAGE local-build path (use the previously-built tag). Requires the deterministic tag to already be in the local registry; errors with an actionable message when missing. No-op for ZIP Lambdas and the IMAGE ECR-pull path. Compatible with --no-pull.")).addOption(new Option("--debug-port <port>", "Node --inspect-brk port (default: off)")).addOption(new Option("--container-host <host>", "Host to bind the RIE port to").default("127.0.0.1")).addOption(new Option("--assume-role [arn]", "Assume the Lambda's deployed execution role and forward STS-issued temp credentials to the container so the handler runs with the deployed function's narrow permissions (closes the \"developer admin / function narrow\" skew). Three forms: (1) `--assume-role <arn>` assumes the explicit ARN; (2) `--assume-role` (bare) auto-resolves the function's execution role ARN from cdkd state (requires --from-state); (3) `--no-assume-role` explicitly opts out (forces dev creds even with --from-state). Off by default — when omitted, the developer's shell credentials are forwarded unchanged (SAM-compatible default). STS failures degrade to a warn + dev-creds fallback.")).addOption(new Option("--layer-role-arn <arn>", "Role to sts:AssumeRole before calling lambda:GetLayerVersion on every literal-ARN entry in Properties.Layers (issue #448). Use only when the dev credentials cannot read the layer — typically cross-account layers. AWS-published public layers (e.g. Lambda Powertools) are readable from every account and need no role.")).addOption(new Option("--ecr-role-arn <arn>", "Role ARN to assume before authenticating against ECR for cross-account / centralized registries (#455). Issues sts:AssumeRole via the default credential chain and uses the temporary credentials for ecr:GetAuthorizationToken + docker pull. Required when the caller does not have direct cross-account access to the target repository. Same-account / same-region pulls do not need this flag.")).addOption(new Option("--from-state", "Read cdkd S3 state for the target stack and substitute Ref / Fn::GetAtt / Fn::Sub in env vars with the deployed physical IDs / attributes. Off by default — keep PR 1 warn-and-drop semantics; turn on for stacks already deployed via cdkd deploy.").default(false)).addOption(new Option("--stack-region <region>", "Region of the cdkd state record to read (used with --from-state when the same stack name has state in multiple regions).")).action(withErrorHandling(localInvokeCommand));
 	[
 		...commonOptions,
 		...appOptions,
@@ -47464,7 +47768,7 @@ function reorderArgs(argv) {
 */
 async function main() {
 	const program = new Command();
-	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.124.0");
+	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.125.0");
 	program.addCommand(createBootstrapCommand());
 	program.addCommand(createSynthCommand());
 	program.addCommand(createListCommand());